Skip to content

README.md

Latest commit

 

History

History
79 lines (63 loc) · 4.43 KB

README.md

File metadata and controls

79 lines (63 loc) · 4.43 KB
Raw

Chatbox 源码拆解

面向工程师的 Chatbox Community Edition 源码导读。本文档基于 /Users/hanqing/CliX/chatbox-main 当前快照整理，更新时间：2026-08-02。

Chatbox 不是一个“把聊天页面包进 Electron”的薄壳。它把多供应商模型接入、流式消息、工具调用、Agent Mode、沙箱代码执行、MCP、Skills、知识库 RAG、跨平台存储和自动更新放进了同一个客户端。本拆解的目标，是沿着一条真实消息从 UI 进入模型、再从模型返回 UI 的路径，把这些模块如何协作讲清楚。

这份拆解回答什么问题

每章同时回答三个问题：

  1. 是什么：模块的职责、边界和核心数据结构。
  2. 怎么做：从入口、调用链、状态变化和关键源码路径追踪实现。
  3. 为什么：解释跨平台、可靠性、安全性和可维护性方面的设计取舍。

本仓库只保存分析文档，不复制 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、路径都使用占位符；不要把真实凭据放进源码或文档。

License

分析文字以 CC BY-SA 4.0 发布；Chatbox 源码的版权和许可证归原项目所有。本仓库不替代官方文档或源码许可证。