附录 D —— 合龙:一次请求,二十五个落点
Part A–D 那十五章是纵向的:一章一个包,一段一段往下钻。这一页横着走一遍—— 一条用户输入,从敲下回车到看见回复,中途在哪些地方换了手。
每一站都标了它在哪一章讲过。如果某一站你读不出"为什么必须在这儿换手", 说明那一章还差一点;回去补,比继续往前读有效。
前提:pi "找出所有 TODO",模型 anthropic/claude-sonnet-4-5,
工作目录里有 AGENTS.md,装了 read / grep / edit 三个工具。
本篇怎么用:当验收清单用——进 Part B 前先花几分钟扫一遍 §一 那 25 行当地图; 每个 Part 读完回来重扫,逐行自问"这步为什么必须在这儿换手",卡住的就去对应章 重读;不配练习。
一、一条链路,二十五个落点
| # | 发生什么 | 谁做的 | 哪章 |
|---|---|---|---|
| 1 | --model 那串字符被解析成一个 Model |
model-resolver.ts |
M04 §8.1 |
| 2 | provider 由三层叠出来:builtin → models.json → 扩展 |
provider-composer.ts |
M04 §8.5 |
| 3 | 找凭据——不在装配时定死 | model-runtime.ts |
M04 §8.6 |
| 4 | 算工具集:八个工具各自的 promptSnippet 被收进来 |
createAllTools |
M05 §1.3 |
| 5 | 系统提示词拼成八个键值对,不是一段字符串 | buildSystemPromptSections |
M08 §二 |
| 6 | 从 cwd 往上爬 AGENTS.md 链,五个候选名命中即停 |
system-prompt.ts |
M08 §四 |
| 7 | Skills 只把清单写进提示词,正文留给工具去拉 | M08 §五 | |
| 8 | 组装 Context:首条 system + 消息数组 |
normalizeContext |
M04 §2.1 |
| 9 | 过第一道闸门:这条会话是不是快装不下了 | compaction.ts |
M09 §2.1 |
| 10 | 从叶子回溯,把会话树投影成 messages | session-manager.ts |
M10 §5.1 |
| 11 | 8 种消息收窄成 4 种,不认识的一律丢掉 | convertToLlm |
M06 §4.3 |
| 12 | Context 折叠成 TranscriptContext:system 折进首条消息 |
ai |
M04 §2.1 |
| 13 | 内层循环开转,emit turn_start |
agent-loop.ts |
M03 §五 |
| 14 | streamSimple 派活给翻译器,吐 12 种事件 |
api/*.ts |
M04 §三 |
| 15 | 流式增量一条条落进 transcript | M03 §八 | |
| 16 | 收尾:stopReason 记下来,但循环不看它 |
M03 §6.1 | |
| 17 | 有 toolCall?分派 → 并行执行 → 按原序记账 |
M03 §九 | |
| 18 | 每个工具过五步管道:垫片 / 校验 / 钩子 / 执行 / 收尾 | M05 §三 | |
| 19 | 两个工具改同一个文件 → 按路径分片的串行锁 | M05 §五 | |
| 20 | 结果变成一条 ToolResultMessage,isError 也在里面 |
M05 §六 |
第 20 站之后回到第 13 站,内层再转一圈。转不动了才轮到外层:
| # | 发生什么 | 谁做的 | 哪章 |
|---|---|---|---|
| 21 | 外层挨个问:steering / follow-up / 宿主要不要续命 | agent-loop.ts |
M03 §6.2–§6.4,逐轮账本 §6.6 |
| 22 | 没有就收尾,emit turn_end / agent_end |
M03 §5.4 | |
| 23 | 10 个内核事件翻译成 41 个扩展钩子 | agent-session.ts |
M07 §三 |
| 24 | TUI 重画组件树,只有变了的那一行被写出去 | tui-main-screen.ts |
M14 §四 |
| 25 | 追加一条 entry 到 JSONL——只追加,不改旧行 | session-manager.ts |
M10 §三 |
一张图压一下,第 12 站那个折叠是全书的分水岭:
Context(system + 工具 + 消息) │ M04 §2.1:折进首条消息,只此一次 ▼TranscriptContext(provider 只认这个) │ M04 §三:12 种事件 ▼ provider左边是 Agent 的世界,右边是模型的世界。 两者之间只有这一个接口, 所以"改一句系统提示词"不能改第一条消息——只能追加一条新的(M04 §2.2)。
二、三个折叠点:跨边界只允许收窄一次
链路里有三处"形状变了",它们的位置比实现更重要:
| 折叠 | 从 → 到 | 收窄掉了什么 | 哪章 |
|---|---|---|---|
| 给模型看 | Context → TranscriptContext |
系统提示词单独存在的能力 | M04 §2.1 |
| 换协议 | 8 种 AgentMessage → 4 种 Message |
只给系统记的四种 | M06 §四 |
| 换长度 | 完整历史 → 摘要 + 保留区 | 被压掉的原文(磁盘上还在) | M09 §一 |
三处的共同点:收窄只发生一次,而且发生在一个文件里的一个函数。
ai 那边二十四行,convertToLlm 一个 switch,压缩那边一道切点。
这条规律可以直接用来读陌生代码:找"类型变了"的那几行,别找最大的文件。 M04 §十一 把它叫做用折叠点找设计重心。
三、五笔"只追加"
五个地方出现了同一条手法:要改历史,就追加一条,别动旧行。
| 场景 | 追加的是什么 | 为什么不能改 | 哪章 |
|---|---|---|---|
| 消息 | 新的 turn / toolResult |
重放要可复现 | M03 §7.3 |
| 压缩 | 一条 compaction entry 当墓碑 |
磁盘得留证据,上下文可以有多个视图 | M09 §一 |
| 会话 | 一行 JSONL entry | 崩溃后靠追加顺序重建 | M10 §三 |
| 持久运行时 | 一次提交(marker + sidecar) | 失败即终态,不回头改 | M11 §十 |
| chord 状态 | delta | 不可变是所有权约定 | M12 §九 |
代价是文件只长不缩——所以每个包都得配一个"什么时候全量重写"的策略 (M10 §3.5)。追加负责正确性,重写负责体积,两者不是替代关系。
四、三道边界
全书反复在划三条线,十五条链路最后都收敛到它们身上。
信任边界。 谁是敌人,决定校验写多重。pi-schema 把每个关键字都当敌人,
因为 schema 来自 MCP server;pi-telemetry 一行校验都不做,因为输入是
同仓库里写死的常量(M15 §十五 方法二)。防御等级跟来源走,不跟类型走。
能力边界。 codemode 的沙箱不是"禁掉危险 API",是只放进去一个 tools
(M13 §6.1)。黑名单永远补不完,白名单只需要一条。同一思路在工具层是五步管道
(M05 §三),在扩展层是三种错误策略(M07 §五)。
字节边界。 到了输出侧,一切都要变成数字:一个 spinner 只该写 99 个字节 (M14 §四),工具输出 50KB 封顶(M05 §七),遥测字段 500 字符硬边界 (M15 §10.3)。凡是"无限增长"的地方,最后都得有一个常数。
五、如果只带走五句话
- 内核只做一件事:请求变一次 HTTP,结果变一条消息;其余全在外围(M01)。
- 每跨一次边界,只允许收窄一次,收窄处必须是一个函数(M04 / M06 / M09)。
- 改历史就追加,删除用墓碑表达(M09 / M10 / M11 / M12)。
- 失败也是数据:工具失败进
toolResult,模型失败进stopReason, 外壳崩溃合成一条 assistant 消息(M03 §十)。调用方只有一条路径。 - 安全来自"只有一条能力",不来自过滤危险 API 的数量(M13 §6.1)。
五句话里没有一句是"某个类怎么实现的"。这就是这本书想留下的东西: 实现会被重写,形状不会。
六、这一页没讲的
- 多用户与权限:Pi 刻意不做权限系统(M01 §五),这里没有"谁能调什么"。
- 多 agent 编排:
orchestrator在 v1.4 不存在,它的活被扩展钩子接走了(M07 §八)。 - 部署形态:进程内 SDK 加 HTTP + SSE 在附录 C,这里只到"事件出了内核"。
- 性能数字:除 TUI 的字节数,全书没做 benchmark;本书关心"为什么这么设计", 不关心"快了多少倍"。
七、接下来读什么
三条路,按你现在的状态选:
想改行为。 回 M07 §七照着写一个扩展——那是唯一一个"不改内核也能改一切"的口子。
写完再回这一页,你会发现自己动的是第 22 站和第 23 站之间。
落地的写法(放哪个目录、on() 接哪些事件、registerTool 的每个参数)在 F05 / F06。
想改内核。 从 M03 §5.1 那段骨架开始,把 agent-loop.ts 抄一遍再对照。
它 960 行,抄完你就有了自己的 Agent 循环。
想搬进产品。 附录 C 有能跑的四十行服务和四个上线坑;
M11 讲清楚了"进程随时会消失"时该怎么办。
五种入口的业务选型(交互 / -p / json / rpc / SDK)在 F09,上线前的三条边界在 F10。
源码索引
| 文件 | 行数 | 本页用到的位置 |
|---|---|---|
packages/agent/src/agent-loop.ts |
960 | 两层循环、turn_start / turn_end |
packages/coding-agent/src/core/model-resolver.ts |
690 | --model 解析 |
packages/coding-agent/src/core/provider-composer.ts |
738 | provider 三层叠加 |
packages/coding-agent/src/core/system-prompt.ts |
229 | 八节提示词 |
packages/coding-agent/src/core/messages.ts |
197 | convertToLlm 闸门 |
packages/coding-agent/src/core/session-manager.ts |
— | 投影与追加 |
packages/coding-agent/src/core/tools/ |
3,662 | 八个工具 |
packages/coding-agent/src/core/compaction/compaction.ts |
1,105 | 切点与摘要 |
packages/tui/src/tui-main-screen.ts |
661 | 差分渲染 |