手册/第 03 章
03
架构图:14 个组件、2 层边界
下面这张图是可校验的:每个组件的职责都绑定到具体的 path:line,
生成时通过了 schema 校验、布局校验与浏览器渲染校验。可以缩放、拖拽、切换明暗主题。
1× 是缩略总览——这张图画布宽 1750px,塞进 898px 的栏位里最小字号只剩约 3px,看不清是正常的。工具栏的 2× / 3× 会按比例放大并可在框内拖动: 实测最小字号依次为 3.2px → 6.7px → 10.3px。也可点 ⤢ 放大 全屏, 或 新窗口 ↗ 用图自身的缩放控件浏览。
怎么读这张图
- 从左到右是主路径:用户 → CLI → 模式外壳 → 会话核心 → agent 循环 → 模型层 → 厂商 API。
- 向下是副作用:工具执行落到工作区、会话落到磁盘、扩展挂钩到循环。
- 两个边界框不是装饰:外层 region 是「pi 进程内、可信核心」;内层 security-group 是 「用户代码沙箱边界」。扩展运行在同一个进程、同一套操作系统权限里,所以它被单独圈出来。
- 颜色即类型:进程内逻辑 / 渲染 / 持久化 / 用户代码 / 外部云服务 / 人,六种角色不混用。
| 组件 | 职责 | 证据(path:line) |
|---|---|---|
| cli | 解析参数、加载配置、按模式分发 | main.ts:623 main.ts:950 |
| mode-interactive | 交互式 TUI 会话(7,110 行的热点) | interactive-mode.ts:453 |
| mode-headless | --print / --mode json / RPC | print-mode.ts:33 rpc-mode.ts:54 |
| tui | 保留模式组件树 + 差分渲染 | tui.ts:506 |
| session | 一次会话的全部状态与编排 | agent-session.ts:379 |
| loop | 请求 → 工具 → 再请求,直到结束 | agent-loop.ts:251 :737 |
| ai / providers | 统一事件流 + 95 个 provider 文件 | stream-fn.ts:15 models.ts:1077 |
| tools | read / write / edit / bash 等工具实现 | tools/index.ts:1 bash.ts:434 |
| extensions | TypeScript 钩子:工具、命令、事件、UI | loader.ts:831 runner.ts:364 |
| store | JSONL 会话文件 + 设置 | session-manager.ts:1187 settings-manager.ts:272 |
注意这个不对称
核心小,外围厚。真正决定一次 run 走向的
agent-loop.ts 只有 6 个源文件;
而 interactive-mode.ts(7,110 行)和 agent-session.ts(4,458 行)是体量最大的两个热点。
读懂 pi 的难点从来不是 agent 算法,而是产品外壳的状态编排。