Craft Agents 0.11.2 源码拆解

在线阅读 · 分析源码 v0.11.2

这是一套面向“想真正理解一个桌面多会话 Agent 产品如何落地”的源码学习笔记。写法参考本地 refs/dg-ai-notes 对 Pi 项目的拆解方式：不是逐文件翻译，而是从读者问题出发，把入口、主链、关键类型、状态机、失败路径和设计取舍连起来。

基准快照：Craft Agents 0.11.2
分析日期：2026-07-25
源码规模：约 1,500 个 TypeScript/TSX 文件、34 万行代码；14 个主要 workspace 包/应用

一句话结论

Craft Agents 不是“给聊天框套一层 Electron”。它更像一个以 SessionManager 为会话 Actor、以文件系统为事实源、以 WebSocket RPC 为进程边界、同时承载 Claude 与 Pi 两套 Agent runtime 的个人 Agent 操作系统。

它最值得学习的不是某个 UI 组件，而是五个组合设计：

1. 把会话作为拥有运行时资源、持久状态和事件出口的 Actor。
2. 用统一 AgentBackend 隔离 provider SDK，同时允许 provider-native 分支、转向和压缩语义存在。
3. 把 Electron 本地模式和 headless 远程模式收敛到同一 RPC 协议，再用 capability 反向调用客户端浏览器。
4. 把 Sources、Skills、Tasks、Automations、Messaging 都接到同一会话生命周期，而不是各自再造执行引擎。
5. 用“先落盘、再确认、再广播”的耐久性纪律，降低流式、多窗口和断线重连带来的状态分叉。

章节导航

章节	核心问题	建议读者
00. 阅读指南与全景地图	如何阅读这套笔记？系统有哪些主链？	所有人
01. 产品问题与设计哲学	Craft Agents 解决的到底是什么问题？	产品、架构
02. Monorepo 与依赖边界	14 个包如何分工，依赖为什么这样走？	工程、架构
03. 运行时拓扑与 RPC	Electron、本地服务、远程服务、WebUI 如何共用后端？	架构、全栈
04. 领域模型与磁盘布局	workspace/project/session/source/task 如何落盘？	后端、数据
05. SessionManager：会话 Actor	9,000 行核心类到底管理什么？	Agent 工程
06. AgentBackend 与动态路由	多 provider 如何共享外壳又保留原生能力？	Agent 工程
07. Claude 后端执行链	Claude Agent SDK 如何接入权限、工具、恢复与事件？	Agent 工程
08. Pi 子进程桥	为什么拆进独立进程？JSONL 协议如何工作？	Agent、系统
09. 消息、事件与前端一致性	流式 token 如何变成可恢复的 UI 状态？	全栈、前端
10. Prompt、上下文与压缩	稳定/易变上下文、缓存、恢复、压缩如何协作？	Agent 工程
11. 工具、权限与安全边界	safe/ask/allow-all 如何真正约束工具？	安全、Agent
12. Sources、MCP、API 与凭据	外部系统如何被热插拔成统一工具？	集成、平台
13. 持久化、分支、迁移与分享	会话如何耐久、分叉、跨机器和公开分享？	数据、后端
14. Tasks、Automations 与后台工作	DAG、多会话协作和事件自动化如何复用会话？	工作流、Agent
15. 内置浏览器与远程能力	服务端 Agent 如何操纵客户端 Electron 浏览器？	系统、桌面
16. Electron、WebUI 与 Viewer	三种 UI 表面如何共享协议和组件？	前端、桌面
17. 消息网关	Telegram/WhatsApp/Lark 如何绑定会话并处理审批？	集成、后端
18. 工程质量、测试与可迁移结论	哪些设计可复用？哪些债务要警惕？	架构、负责人

三条推荐阅读路线

路线 A：先抓住 Agent 主链

00 → 05 → 06 → 07 → 08 → 09 → 10 → 11

读完应能回答：一条用户消息从 UI 发出后，如何落盘、选后端、组 prompt、跑工具、处理中断，再以事件形式稳定回到 UI。

路线 B：理解产品级平台化

01 → 02 → 03 → 04 → 12 → 14 → 15 → 17

读完应能回答：一个 Agent 产品如何从单对话扩成多工作区、多数据源、远程运行、工作流和外部消息入口。

路线 C：准备二次开发

02 → 03 → 04 → 05 → 09 → 13 → 16 → 18

读完应能定位：新 RPC 放哪里、新会话字段如何持久化、新事件如何进入前端、新 provider 或 source 应接在哪层。

文档中的证据约定

• “事实”尽量附源码路径和符号；行号以 0.11.2 快照为准。
• 伪代码只保留控制流，不保证可直接编译。
• “设计判断”是依据代码结构做出的解释，会与源码事实分开表述。
• “风险/债务”不等于已发现线上 bug，而是从耦合、状态量和失败窗口推导出的维护成本。
• Mermaid 图聚焦关系和时序，不试图一比一复刻所有分支。

最小源码入口集

如果只打开十个文件，建议从这些开始：

1. SessionManager.ts
2. backend/types.ts
3. backend/factory.ts
4. claude-agent.ts
5. pi-agent.ts
6. pi-agent-server/src/index.ts
7. protocol/dto.ts
8. sessions/jsonl.ts
9. core/pre-tool-use.ts
10. renderer/event-processor/processor.ts

版本边界

这套笔记描述的是 0.11.2 的真实实现，不把 README 中的愿景自动当作已完成能力。例如 Tasks 的 schema 已经能解析 route、loop、approval 等控制节点，但当前 Conductor 真正执行的是 session 节点、依赖、输入引用、并发、重试与验证/修复主链。类似差异会在正文明确标注。

本地运行文档站

npm install
npm run dev

生产构建与类型检查：

npm run check
npm run build

docs/ 是拆解内容的事实源；构建前脚本会为 Starlight 生成带 frontmatter 的 src/content/docs/，该目录不提交到 Git。