面向工程师的 Chatbox Community Edition 源码导读。本文档基于
/Users/hanqing/CliX/chatbox-main当前快照整理，更新时间：2026-08-02。
Chatbox 不是一个“把聊天页面包进 Electron”的薄壳。它把多供应商模型接入、流式消息、工具调用、Agent Mode、沙箱代码执行、MCP、Skills、知识库 RAG、跨平台存储和自动更新放进了同一个客户端。本拆解的目标，是沿着一条真实消息从 UI 进入模型、再从模型返回 UI 的路径，把这些模块如何协作讲清楚。
每章同时回答三个问题：
- 是什么：模块的职责、边界和核心数据结构。
- 怎么做：从入口、调用链、状态变化和关键源码路径追踪实现。
- 为什么：解释跨平台、可靠性、安全性和可维护性方面的设计取舍。
本仓库只保存分析文档，不复制 Chatbox 源码。源码事实以 chatboxai/chatbox 为准；章节中的路径均对应上游仓库的 src/ 或 docs/ 目录。
01 总览与架构
↓
02 启动、进程与平台抽象
↓
03 会话、消息、线程与分叉
↓
04 一次生成：上下文 → 模型 → 流式消息
↓
05 Provider 与模型注册表
↓
06 Agent Mode 与工具编排
├── 07 MCP / Skills / Virtual CLI
├── 08 Sandbox 与安全边界
└── 09 知识库与 RAG
↓
10 存储、迁移与备份
↓
11 UI 状态、路由与跨平台交付
↓
12 测试、错误治理与工程方法
| 章节 | 主题 | 读完后应掌握的模型 |
|---|---|---|
| 01 | 一张图看懂 Chatbox | 产品边界、分层、核心运行时 |
| 02 | Electron 启动与平台抽象 | Main/Preload/Renderer、IPC、Platform |
| 03 | 会话与消息数据模型 | Session、Thread、Fork、持久化语义 |
| 04 | 一次 AI 生成的完整链路 | 上下文构建、模型调用、流式落盘 |
| 05 | Provider 与模型注册表 | ProviderDefinition、能力门控、OAuth、models.dev |
| 06 | Agent Mode 与工具编排 | 工具构建、审批、暂停、继续、工具循环 |
| 07 | MCP、Skills 与 Virtual CLI | 外部工具、渐进式上下文、应用自操作边界 |
| 08 | Sandbox 与安全边界 | 沙箱会话、文件根、Full Access、操作日志 |
| 09 | 知识库与 RAG | 文档解析、embedding、向量检索、Session Attachment |
| 10 | 存储、迁移与备份 | 配置/会话/blob 的混合存储与恢复 |
| 11 | UI 状态、路由与跨平台交付 | Jotai/Zustand/React Query、Web/Mobile/Desktop |
| 12 | 测试与可迁移的工程方法 | 测试矩阵、错误治理、架构启示 |
| 问题 | 先看 |
|---|---|
| Electron 到底怎么启动 | src/main/main.ts、src/preload/index.ts、src/renderer/index.tsx |
| 一次发送消息在哪里编排 | src/renderer/stores/session/orchestration.ts、generation.ts |
| 消息和工具调用怎么持久化 | src/shared/types/session.ts、stream-chunk-processor.ts |
| Provider 如何注册 | src/shared/providers/registry.ts、index.ts、definitions/ |
| Agent 工具从哪里来 | src/renderer/stores/session/tools-builder.ts、agent-harness.ts |
| 代码执行如何离开 Renderer | src/renderer/sandbox/、src/main/sandbox/、src/main/sandbox/ipc-handlers.ts |
| 会话在哪里存 | src/renderer/storage/、src/main/store-node.ts、src/renderer/platform/ |
chatbox-main是一个没有.git元数据的源码快照，因此本文不把无法确认的 commit、发布版本或线上配置写成确定事实。- 文档中的“当前实现”指本地快照中实际存在的代码；上游仓库后续变化可能使路径和细节发生漂移。
- 示例中的 API key、token、路径都使用占位符；不要把真实凭据放进源码或文档。
分析文字以 CC BY-SA 4.0 发布；Chatbox 源码的版权和许可证归原项目所有。本仓库不替代官方文档或源码许可证。