Pi Agent 源码级教程
APX

附录 D —— 合龙:一次请求,二十五个落点

1,777 字 · 含 7 行代码 · 约 8 分钟

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 站那个折叠是全书的分水岭:

text
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)。凡是"无限增长"的地方,最后都得有一个常数。


五、如果只带走五句话

  1. 内核只做一件事:请求变一次 HTTP,结果变一条消息;其余全在外围(M01)。
  2. 每跨一次边界,只允许收窄一次,收窄处必须是一个函数(M04 / M06 / M09)。
  3. 改历史就追加,删除用墓碑表达(M09 / M10 / M11 / M12)。
  4. 失败也是数据:工具失败进 toolResult,模型失败进 stopReason, 外壳崩溃合成一条 assistant 消息(M03 §十)。调用方只有一条路径。
  5. 安全来自"只有一条能力",不来自过滤危险 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 差分渲染