Pi Agent 源码级教程
M02

三层架构 —— 十二个包各自站在哪一层

7,678 字 · 含 262 行代码 · 约 39 分钟

上一章给了一张体量表。但体量只回答"哪里代码多",不回答"哪块代码归谁管"。

这一章给的是后者:一张能定位任何文件的图。


零、读这章之前,你需要先知道一件事

三个词:monorepo = 一个仓库里放很多包;workspace = npm 让这些包互相认识的机制 (就是根 package.json 里那个 workspaces 字段);依赖深度 = A 依赖 B、B 依赖 C, 则 A 到 C 的距离是 2。

没有它会怎样:你会把 12 个 package.json 当成 12 个要发布的包,再把 node_modules 里指向同仓库的软链当外部依赖——两条都能推出错误结论。

本书哪里用到:§三 那张 12 行表;算法在 §十二 实验 1。


一、给一个路径,你能说出它在哪层吗

先做个小测。下面六个路径,各自属于哪一层?

text
packages/ai/src/providers/anthropic.tspackages/agent/src/agent-loop.tspackages/durable/src/harness/scheduler.tspackages/coding-agent/src/core/tools/bash.tspackages/schema/src/compiler.tspackages/tui/src/tui.ts

如果你能凭命名猜个大半,说明 Pi 的目录结构是健康的。但要精确到"它能不能依赖别人、别人能不能依赖它",得看 package.json。

层不是一个概念,是一组约束。判定"某文件在第 N 层"的唯一可用标准是:它所在包能 import 谁。一个文件放在哪个目录是编写者的习惯,dependencies 才是编译器认可的边界。

这一章的做法是:只看 12 个 package.json 的 dependencies,把图画出来,再回头解释每个包为什么在这个位置。

1.1 三步判层法

给定任意一个文件路径,三步就能判出它属于哪一层:

text
第一步:取 packages/<包名>/ 里的 <包名>第二步:查这个包的 dependencies第三步:它依赖谁 → 它就比谁浅一层

举三个例子。

packages/ai/src/providers/anthropic.ts → 包是 ai → 依赖 schema telemetry → 两个都是深度 0 → 自己深度 1。至于 anthropic.ts 在 providers/ 子目录下,跟层级无关,只影响这层的内部组织。

packages/durable/src/harness/scheduler.ts → 包是 durable → 依赖 5 个 → 最深的是 chord/ai(深度 1)→ 自己深度 2。harness/ 三个字不改变任何东西。

packages/schema/src/compiler.ts → 包是 schema → 无依赖 → 深度 0。

关键点是第三步:目录深度不是层级。packages/durable/src/harness/scheduler.ts 有 5 层目录,但它只比 ai 深一层——因为目录结构是编写者的自由,dependencies 才是边界。

同理,packages/coding-agent/src/core/tools/bash.ts 有 5 层目录,深度是 3;而 packages/tui/src/tui.ts 只有 3 层目录,深度是 0。路径长短和层级没任何关系。


二、先把词对齐:包、层、边

三个词,先定义清楚,后面不再解释。

包(package) —— packages/ 下的一个目录,有一个 package.json,有一个 npm 名。12 个,上一章列过。

边(edge) —— package.json 里 dependencies 出现一次兄弟包,就算一条边。注意区分:

  • 运行时依赖(dependencies)→ 画进图,因为它决定跨包边界
  • 开发依赖(devDependencies)→ 不画,它只影响构建
  • 外部依赖(openai、ws 之类)→ 不画,它不属于仓库内部结构

层(layer) —— 一条边的方向是"依赖方 → 被依赖方"。按路径长度给每个包算一个深度:

text
depth(p) = 0                        如果 p 不依赖任何兄弟包depth(p) = 1 + max(depth(deps))     否则

深度相同的包在同一层。边只能从浅层指向深层,绝不能反向——这是整张图唯一需要验证的性质,第十节会给验证脚本。


三、层不是画的,是算出来的

按上面那个公式,把 12 个包算一遍:

包 依赖的兄弟包 深度
telemetry — 0
schema — 0
tui — 0
mcp — 0
codemode — 0
chord schema, telemetry 1
ai schema, telemetry 1
durable chord, ai, codemode, schema, telemetry 2
agent ai, schema 2
env chord, durable 3
coding-agent agent, ai, codemode, mcp, tui 3
evals — 0

算出来是 4 层深度(0/1/2/3),不是 3 层。

那为什么本章标题叫"三层架构"?因为两种切法都对,但回答的问题不同:

切法 依据 结果 回答什么问题
分层 深度公式 4 层(0–3) 谁能在谁前面构建
分职责 干的是什么事 3 层(基础 / 运行时 / 产品) 谁负责什么

职责切法是这样的:

text
基础层   schema telemetry tui mcp codemode     ← 单点能力,谁都能用运行层   ai chord agent durable env            ← 把能力组装成"能跑的东西"产品层   coding-agent  evals                   ← 给人用

注意 ai 在职责切法里属于"运行层",在深度切法里深度只有 1。两个答案不矛盾:它只依赖基础层,但它干的是运行时的事。

读源码时用职责切法(它告诉你该看谁),改构建时用深度切法(它告诉你先编谁)。 全章剩下部分两种都会用到,每次会给出来。


四、基础层:五个零依赖包

五个包的共同点:dependencies 里没有任何兄弟包。它们排在最前面,也最容易被单独复用。

包 行数 按职责的一句话
schema 4,608 JSON Schema 编译器,把 schema 变成普通闭包
telemetry 1,580 厂商中立的遥测契约
tui 19,971 终端差分渲染库
mcp 3,305 独立的 MCP 客户端
codemode 3,054 沙箱 JS 执行,唯一能力是调注入的工具

零依赖不是巧合,是准入条件。往任何一个里加一条兄弟依赖,它就掉出基础层,整个构建顺序都要重排。

先把十二个包的完整台账放这儿,后面反复要查:

包 文件 行数 依赖数 深度 每文件均值
coding-agent 256 77,658 5 3 303
chord 216 50,101 2 1 232
durable 97 33,728 5 2 348
ai 206 28,581 2 1 139
tui 46 19,971 0 0 434
schema 43 4,608 0 0 107
mcp 18 3,305 0 0 184
codemode 17 3,054 0 0 180
agent 6 2,559 2 2 427
env 8 2,398 2 3 300
telemetry 8 1,580 0 0 198
evals 5 1,452 0 0 290
合计 924 228,999 — — 248

最后一列很容易被忽略,但它是个免费的情报:每文件行数告诉你这个包按什么切文件。

  • schema 107 / ai 140 → 按"一个概念一个文件"切,文件多而小
  • tui 434 / agent 427 → 按"一个职责一个大文件"切,文件少而大

两种都是对的,但读法不同。schema 里你需要扫文件名找功能(coerce.ts 管转换、explain.ts 管报错);agent 里你必须通读全文,因为 agent-loop.ts 一个文件就是整层逻辑。

agent 以 6 个文件、427 行均值成为全仓库最"胖"的包。这不是美学选择,是刻意不拆:拆成 10 个文件之后,那个 960 行的循环会被切断,读的人就得在文件间跳。M03 会看到它为什么不拆。

4.1 schema 的结构暴露了它的野心

text
compiler.ts    594   把 schema 编译成闭包coerce.ts      557   类型强制转换checks.ts      452   keyword 校验explain.ts     391   错误信息生成formats/     1,713  31 个文件,每个 format 一个resolver.ts    204   $ref 解析annotations.ts 209builders.ts    201validator.ts    94index.ts        32

formats/ 一个文件一个 format(email、date-time、uri…),31 个文件 1,713 行,占了 37%。这种"一格式一文件"的排布说明它追求的是穷举而非通用:每个 format 都有自己的边界条件(email 的国际化、date-time 的闰秒),塞进一个 switch 会变成噩梦。

explain.ts 391 行单独成文件,是为了给模型看的错误信息。校验失败时,agent 要把错误回给模型让它改参数,所以"错在哪、期望什么、实际是什么"必须是结构化可读的,不能是一句 invalid。

4.2 telemetry 只有 5 个文件,但结构很讲究

text
index.ts     466   契约(接口与类型)memory.ts    464   参考实现(存在内存里,供测试)metrics.ts   146render.ts     50   渲染成文本noop.ts       38   什么都不做

契约 > 参考实现 > 空实现,三层齐全。这是"中立的遥测"必须付的成本:用户可以选择接 OpenTelemetry、接自己的后端,或者干脆 noop。如果只有契约没有 noop,每个不想接遥测的人都要自己写一个空实现。

46 行对 464 行——noop 只有前者的 12%。这个小文件是个信号:一个库如果提供了 40 行的 noop 实现,说明它真的想让你是可选的。

4.3 tui 的文件名就是一份需求清单

text
terminal.ts  tui.ts  layout.ts  layout-node.ts       ← 渲染核心alt-screen-search.ts  tui-alt-screen.ts  tui-main-screen.tseditor-component.ts  kill-ring.ts  undo-stack.ts     ← 编辑器fuzzy.ts  autocomplete.ts  word-navigation.ts        ← 输入补全oklab.ts  colors.ts  terminal-colors.ts              ← 颜色terminal-image.ts  latex.ts                          ← 富内容native-modifiers.ts  native-module-path.ts           ← 原生绑定

kill-ring.ts 和 undo-stack.ts 同时存在,说明它实现的是 Emacs 那套 yank/kill 语义,不是简单的 Ctrl+Z。oklab.ts 说明颜色计算在感知均匀空间里做,不是在 sRGB 里加减。

一个 2 万行的终端 UI 库,27 个顶层文件,每个文件解决一个具体问题。M14 会拆开其中最关键的一个:差分渲染。

4.4 mcp 里最大的不是 client

text
client.ts     622oauth/      1,365   7 文件transports/   857   4 文件(stdio / http / sse / websocket)protocol/     365   3 文件

oauth/ 比 client.ts 还大两倍多。这是接入外部 MCP server 的真实成本分布:协议本身不难,鉴权才难。 设备码流程、token 刷新、PKCE、动态客户端注册——每一样都是一屏代码。

记住这个比例。后面看到 evals 只有 1,452 行而 mcp 的鉴权就 1,365 行时,你会明白"接一个外部系统"和"自己算一个分数"的成本差多少。

4.5 codemode 的 2/3 在 sandbox

text
runtime/        2,067   8 文件(沙箱本体)declarations.ts   341   TS 声明生成types.ts          255source.ts         126cloudflare.ts      76portable.ts        54

codemode 的整个意义是"模型写的代码只能在受限环境里跑",所以 runtime/ 占 68% 是合理的。它支持多种 runtime(portable / cloudflare / wasm),每个都有自己的隔离模型。


五、中间层:两个归一层,方向相反

深度 1 的两个包是 ai 和 chord。它们都依赖 schema + telemetry,看起来像同一类东西。

其实它们归一的方向完全是垂直的。

5.1 ai 归一的是"南北向差异"

7 家 provider,7 套协议,7 种错误码,7 个 thinking 参数名。ai 把它们压成一个 stream(model, context, options),事件类型固定 12 种。

它的入口文件第一行就写了这个设计(packages/ai/src/index.ts:1-5):

ts
// Core only, side-effect free: no generated catalogs, no provider factories,// no api-registry, no OAuth implementations, no compat. Provider factories// live under "@earendil-works/pi-ai/providers/*", API implementations under// "@earendil-works/pi-ai/api/*", the old global API under// "@earendil-works/pi-ai/compat".

这段注释值得逐字读,它定义了一套入口分层:

入口 内容 什么时候用
@earendil-works/pi-ai 纯类型 + 无副作用核心 你只想要类型,不想拉起 OAuth 和模型目录
.../providers/* provider 工厂 你要实例化某一家
.../api/* API 协议实现 你要改某家协议
.../compat 旧全局 API 你还在用老写法

"side-effect free" 是这里最硬的约束:import 主入口不会加载 310 行的 models.generated.ts,不会拉起 OAuth,不会注册任何 provider。这在 CLI 启动时间里能省下几十毫秒,在浏览器里能省一次网络请求。

5.2 96 个 provider 文件只有 4,020 行

这是 ai 里最反直觉的比例:

text
api/         43 文件   13,721 行    ← 协议实现providers/   96 文件    4,020 行    ← provider 工厂auth/        19 文件    3,836 行utils/       28 文件    3,075 行models.ts                1,301 行types.ts                   918 行

providers/ 平均每个文件 42 行。打开一个看,它基本就是个"声明式清单"——模型列表、默认参数、走哪个 api 实现。真正的协议逻辑全在 api/ 的 43 个文件里。

这解释了一件很实际的事:"给 Pi 加一个新 provider"和"给 Pi 加一个新协议"是两件完全不同量级的事。前者改 providers/ 一个文件(几十行),后者要写 api/ 的一个新实现(几百到两千行)。

M04 会给完整的加 provider 步骤。

5.3 chord 归一的是"东西向差异"

chord 解决的不是"不同的外部服务",而是"同一个进程里多个插件之间怎么通信"。

text
contract.ts  declare.ts  schema.ts        契约与声明host.ts  cell.ts  node.ts  cluster.ts     宿主与节点link.ts  connection.ts  websocket.ts      传输state.ts  delta.ts  registry.ts  watch.ts 复制状态reload.ts  loader.ts  manager.ts          热重载

它的关键设计有两个,都能从文件名读出来:

一,契约先行。 contract.ts + declare.ts 意味着插件和宿主之间先谈好一份契约,而不是互相 import。这样插件才能在不重启的情况下被替换——新插件只要满足同一份契约,宿主根本不关心它是谁。

二,状态是复制的,不是共享的。 state.ts + delta.ts + registry.ts 说明状态变更以增量广播。共享内存做不到跨进程,复制状态可以——websocket.ts 在那儿,就是为了让 cluster.ts 能把节点放到另一台机器上。

所以 chord 和 ai 虽然同层,但完全可以独立使用:

  • 只用 ai → 你想统一多家 LLM
  • 只用 chord → 你想写个热重载插件系统,跟 LLM 无关

durable 同时依赖两者,因为它们解决两个正交的问题。

还有一个子目录值得单独提:chord/src/next/。

text
host/        31 文件   8,846 行store/       34 文件   6,117 行remote/      10 文件   2,696 行jobs/        10 文件   2,495 行documents/   13 文件   2,222 行link/        12 文件   2,052 行contracts/   13 文件   1,835 行state/        7 文件     991 行registries/   7 文件     853 行data/         8 文件     574 行

十个子目录加起来约 28,700 行,占整个 chord 的 57%。也就是说:你看到的 chord/src/ 顶层那些 link.ts state.ts reload.ts,只占它的一半;另一半是一个叫 next 的服务端子系统。

名字叫 next,不是随便取的——这是个跑在 Node 服务端的完整应用层:host 宿主、store 存储、jobs 作业、documents 文档、remote 远程。M12 会给读者一个诚实的交代:哪些读了,哪些只看了目录。


六、深度 2:内核与运行时

深度 2 的两个包是 agent 和 durable。它们互不依赖,这是全图最重要的一条"缺席的边"。

text
agent      → ai, schema                2,559 行durable    → chord, ai, codemode, schema, telemetry   33,728 行

6.1 agent 只认两样东西

json
"dependencies": {	"@earendil-works/pi-ai": "1.4.0",	"@earendil-works/pi-schema": "1.4.0"}

ai 提供 stream() 和消息类型,schema 提供工具参数的类型推导(types.ts:17 用 Static<> 把 JSON Schema 转成 TS 类型)。

就这两样。 没有存储、没有 UI、没有插件、没有 MCP。所以 960 行的 agent-loop.ts 是全仓库最纯的一段代码——它只能看见"一个流函数"和"一堆类型"。

这个约束的价值在改代码时才显出来:你在 agent-loop.ts 里写不出 fs.writeFile,因为没 import;也拿不到 session,因为没这个类型。依赖少,能犯的错就少。

6.2 durable 依赖 5 个包,因为它是运行时

text
chord       → 插件宿主(热重载)ai          → 调模型codemode    → 沙箱执行schema      → 工具参数校验telemetry   → 遥测

再加它自己 33,728 行。durable/src/ 的目录结构:

text
harness/       25 文件   运行时主体session/        7 文件   会话与事务storage/        多后端    jsonl / sqlite / memory / indexeddbcodemode/  tools/  tool-search/  images/  env/  testing/tasks.ts  documents.ts  entries.ts  timers.ts  search.ts  truncate.ts

tasks.ts / documents.ts / timers.ts / search.ts 这四个根层文件说明它的野心不止对话:任务、文档、定时器、搜索都是一等公民。

再看 harness/ 那 24 个文件的实际分布(共 11,332 行):

text
scheduler.ts         3,159   ← 占整个 harness 的 28%generation.ts        1,188tool.ts              1,147types.ts             1,080harness.ts             612compaction.ts          501live.ts                452view.ts                400context.ts             383agent.ts  submissions.ts  task-graph.ts  transcript.tspartial-changes.ts  inbox.ts  prompt.ts  telemetry.tsregistry.ts  util.ts  usage.ts  json.ts  define.tsprovider.ts  registry-reader.ts

harness/ 里最大的不是 agent.ts(362 行),是 scheduler.ts(3,159 行)——大小是前者的 8.7 倍。

这个比例本身就是一条结论:在有状态的运行时里,"什么时候该跑"比"怎么跑"难一个数量级。 agent.ts 只管跑一轮;scheduler.ts 要管并发、超时、重试、优先级、依赖就绪、持久化队列。

另一个信号是 submissions.ts(318)+ inbox.ts(179)同时存在。两者都是"消息入口",但方向相反:inbox 是外部往内投,submissions 是内部任务提交。双向都有一等公民,说明这不是一个只能被动的运行时。

这就是 durable 和 agent 的分工边界,一句话:

agent 管"这一轮怎么跑完",durable 管"跑到一半崩了之后怎么接着跑"。

前者无状态,后者有状态且状态要落盘。M11 会详细讲它怎么做到"中断后可恢复"。


七、深度 3:两个产品

7.1 coding-agent 是产品,所以它最大

text
core/        100 文件   约 36,400 行   ← 内核粘合层modes/        69 文件   约 24,500 行   ← 五种入口的 UIextensions/   25 文件    7,818 行   ← 扩展加载器utils/        37 文件    3,925 行cli/          12 文件    1,471 行package-manager-cli.ts   1,210 行main.ts                  1,011 行config.ts                  682 行index.ts                   500 行   ← SDK 导出面

modes/ 两万四千多行对应上一章那张"五个入口"表——交互、print、JSON、RPC、SDK,每种模式一套实现。这是"极简内核"藏起来的成本:内核不管怎么显示,所以显示逻辑全在这里。

core/ 的 100 个文件,拆开是这样:

text
core/ 根层      60 文件  约 27,300 行   粘合层与状态  compaction/    4 文件   1,664 行  tools/        24 文件   4,688 行  extensions/    9 文件   5,113 行  export-html/   3 文件     756 行

根层 60 个文件里,有一个数字很吓人:agent-session.ts 4,479 行。

这是全仓库最大的单文件,比 agent-loop.ts 大 4.7 倍。它管的是"一个会话的全部对外行为"——提示词的拼接、工具变更的声明、压缩的触发、模型的切换、队列的排队与去重。M10 会专门拆它。

core/ 36,058 行是粘合层:把 agent 的循环接到 ai 的流、把工具接到 codemode 的沙箱、把会话接到 JSONL 文件。这部分代码之所以多,是因为每接一条边都要处理错误、超时、取消、路径。

7.2 env 把 durable 搬到远端

text
remote-env.ts    958ssh.ts           540connection.ts    438watch.ts         163terminal.ts      128list-files.ts    103

包描述说得很清楚:一个跑在 SSH 上的小守护进程,加一个 ExecutionEnv 客户端。

所以 env 依赖 chord + durable 两件事:chord 提供跨进程的 link(SSH 两端要靠它传消息),durable 是远端要跑的那个运行时。

它不是"环境变量管理"——这是 12 个包里最容易误判的一个,光看名字 100% 会猜错。


八、全景图

把上面四节合成一张图。箭头方向 = 依赖方向。

text
                        ┌─────────────────────────────┐   产品层               │  coding-agent     env       │   (深度 3)             │   77,658       2,398        │                        └──────┬───────────┬──────────┘                               │           │                        ┌──────┴──────┐    │   运行层               │ agent       │    │   (深度 2)             │  2,559      │    │                        └──────┬──────┘    │              ┌────────────────┼───────────┴───────────┐              │                │                       │   中间层     │  durable       │  ai          chord    │   (深度 1)   │  33,728        │  28,581      50,101   │              └───┬────────────┴────────┬──────────────┘                  │                     │        ┌─────────┴─────────────────────┴──────────────┐   基础层         schema   telemetry   tui   mcp   codemode   (深度 0)        4,608      1,580   19,971 3,305   3,054        └──────────────────────────────────────────────┘

看不出来的几点,补三行:

  • agent 只连到 ai 和 schema 两根线,是图里最"瘦"的节点
  • durable 横跨五个基础/中间层包,是整个图的枢纽
  • coding-agent 和 env 之间没有边——它们都是产品,但服务不同场景(本地 CLI vs 远端部署)

还有 evals(1,452 行,深度 0)不在图里。它是测试工具,不参与构建,也不被任何包依赖。

8.1 箭头是依赖,不是调用

这张图极容易被读错一层。把箭头当成"调用方向",会得出两个错误结论: agent 自己挑 provider、agent 自己实现 bash。两件事都是反的。

text
① 依赖方向(package.json 定的,编译期就锁死)   coding-agent ─────▶ agent ─────▶ ai ─────▶ schema   上层 import 下层;箭头指谁,谁就必须先 build。② 运行时的两个缝:实现在上层,被塞进下层   模型调用                              工具调用   ┌────────────────────────────┐        ┌────────────────────────────┐   │ coding-agent/              │        │ coding-agent/              │   │  src/core/sdk.ts:46        │        │  src/core/tools/bash.ts    │   │ setDefaultStreamFn(...)    │        │ createBashToolDefinition   │   └───────────┬────────────────┘        └───────────┬────────────────┘               │                                     │               ▼                                     ▼   ┌────────────────────────────┐        ┌────────────────────────────┐   │ agent/src/stream-fn.ts     │        │ agent/src/types.ts:495     │   │ let defaultStreamFn        │        │ execute: (...) => ...      │   └───────────┬────────────────┘        └───────────┬────────────────┘               │                                     │               ▼                                     ▼   agent-loop.ts:412                     agent-loop.ts:842   await streamFunction(...)             await tool.execute(...)

两条补丁:

  • agent 不认识 anthropic、openai,也不认识 bash。它只认识两个类型: StreamFn(packages/agent/src/stream-fn.ts:3),以及一个带 execute 的 AgentTool(packages/agent/src/types.ts:495)。
  • 实现是宿主塞进来的。packages/coding-agent/src/core/sdk.ts:46 那一行 setDefaultStreamFn(streamSimple) 就是"塞"这个动作本身;工具更直接, createBashToolDefinition (packages/coding-agent/src/core/tools/bash.ts:426)造出一个对象, 随 tools 数组传进循环。

所以"深度 2 的 agent 驱动深度 3 的 coding-agent"这句话成立, "深度 3 的 coding-agent 依赖深度 2 的 agent"也成立。 依赖定的是编译边界,调用由注入决定,两件事不冲突。

M03 讲 agent loop 时会直接用到这条:换 provider 不用动 agent, 加一个工具也不用动 agent。


九、三条反直觉的边

图里有一条边画出来会让人愣一下,另有两条该有却没有。 §八 那张图看不出"哪条边缺席",所以单独拎出来画:

text
  agent         ───────────> schema   有,只为一个 import type(9.1)  coding-agent  ┄┄┄┄┄┄┄┄┄┄┄> durable  无,各有各的会话实现(9.2)  coding-agent  ┄┄┄┄┄┄┄┄┄┄┄> schema   无,那个 import 走 ai 转手(9.3)  实线 = dependencies 里写着;虚线 = 没有,但你八成以为有。

下面逐条说为什么。

9.1 有:agent → schema

旧版里 agent 只依赖 ai。v1.4.0 多了一条指向 schema 的边,用途单一(packages/agent/src/types.ts:17):

ts
import type { Static } from "@earendil-works/pi-schema";

Static<T> 干的事是把 JSON Schema 字面量转成 TypeScript 类型。写了:

ts
const params = {	type: "object",	properties: { path: { type: "string" } },	required: ["path"],} as const;

就能拿到 { path: string } 而不是 unknown。

这条边为什么值得单说? 因为它是"类型安全链"的前半截。后半截在 coding-agent:工具作者写一个 JSON Schema,参数类型、运行时校验、给模型的工具描述,全都从同一份 schema 生成。三处一致,靠的就是这条边。

如果没有它,工具参数就只能手写 TS 类型 + 手写校验 + 手写文档,三份东西迟早不一致。

9.2 没有:coding-agent → durable

这是最容易误判的一条。直觉是"会话管理在 durable,所以 CLI 要依赖它"。

事实:

bash
grep -r "pi-durable" packages/coding-agent/src --include=*.ts    # 0 条ls packages/coding-agent/src/core/session-manager.ts            # 存在

coding-agent 有自己的会话实现,durable 是一套平行的运行时。

为什么?因为两者对"持久化"的要求不一样:

coding-agent 的会话 durable 的会话
目标 人看得懂、能回滚 崩溃后能精确续跑
落盘单位 JSONL,一条 entry 一行 事务 + 提交点
分支 改 active leaf 即可 需要 generation 约束
复杂度 单一文件 5 种存储后端

一个交互式 CLI,用户按 Ctrl+C 就停了,不需要"在第 7 次工具调用之后精确恢复"。所以它选了最简的 JSONL。而 durable 是给"跑一小时的自动化任务"用的,那个才需要事务。

两条线各自演化,比强行统一成本低。 M10 讲前者,M11 讲后者,最后会对比一次。

9.3 没有:coding-agent → schema

coding-agent 依赖 agent,agent 依赖 schema,所以它间接能拿到 schema。但它的 dependencies 里没有直接写 schema。

这是 npm 的常规做法:不依赖你没直接 import 的包。反过来说,如果你在 coding-agent 里想用 Static<>,应该确认它是否 re-export 了——跨两跳的类型引用是 monorepo 里最脆的东西。

9.4 没有:README 里公示的包只有七个

上一章提过:README 的 Packages 表只列了 7 个,仓库里有 12 个。换个角度看,这不是"忘了写",而是公示标准与代码存在时间差。

公示的 7 个:chord telemetry ai durable agent-core coding-agent tui

没公示的 5 个:schema mcp codemode env evals

判据是"用户会不会写进 npm i"。前七个都是"你可以单独装来用"的,后五个是"你只会通过别人拿到"的。

但这个判据有一条反例,而且很硬:mcp 的包描述写的是——

Standalone Model Context Protocol client for pi and other applications

"standalone"和"other applications"两个词直接声称它是个通用库。而它没进 README 表格。

这条矛盾本身就是情报:README 的表格是滞后于代码的。读这类仓库时,宁可相信 package.json 的 description,也别只信 README 的汇总表——后者是人手维护的,前者是发布流程的一部分。


十、验证:没有一条箭头反向

上一章问过"build 顺序能不能当依赖图看",结论是不能——它是手写的顺序。现在把这句话变成一条可逐行核对的规则。

规则:对任意一条边 A → B,B 在 build 序列里必须排在 A 前面。

build 序列(package.json:15,11 步):

text
1 telemetry   2 schema     3 chord      4 tui       5 codemode6 mcp         7 ai         8 durable    9 env      10 agent11 coding-agent

逐条核对:

边 依赖方位置 被依赖方位置 是否合法
chord → schema 3 2 ✅
chord → telemetry 3 1 ✅
ai → schema 7 2 ✅
ai → telemetry 7 1 ✅
durable → chord 8 3 ✅
durable → ai 8 7 ✅
durable → codemode 8 5 ✅
durable → schema 8 2 ✅
durable → telemetry 8 1 ✅
env → chord 9 3 ✅
env → durable 9 8 ✅
agent → ai 10 7 ✅
agent → schema 10 2 ✅
coding-agent → agent 11 10 ✅
coding-agent → ai 11 7 ✅
coding-agent → codemode 11 5 ✅
coding-agent → mcp 11 6 ✅
coding-agent → tui 11 4 ✅

18 条边,18 个 ✅。没有一条反向。

但注意一个细节:env(第 9 位)排在 agent(第 10 位)前面,可 env 的深度是 3、agent 是 2。

这说明 build 顺序是拓扑序,不是分层序。拓扑序只保证"依赖在前",不强求"同层相邻"。env 排在 agent 之前完全合法,因为它们之间没有边。

这条区别很重要:如果你按"深度 0 → 1 → 2 → 3"去排 build,会得到另一个也能跑的顺序;但仓库选了现在这个,因为 agent 排在 coding-agent 前面更符合人的阅读顺序。拓扑序不唯一,选哪个都能跑。


十一、离仓那条边:依赖是怎么出去的

§十 验证的 18 条边全在仓里。但依赖图还有一条朝外的边: packages/* → npm 上的 tarball。这条边不在任何 dependencies 字段里, 所以前面那些验证方法一条都管不到它。

先把三个数字对齐。 packages/ 下有 12 个带 package.json 的目录; README 的包表只公示 7 个;而 private: true 的只有 1 个 (evals)。

什么意思?文档是地图,不是领土。 schema mcp codemode env 这四个包不在包表里、也没标 private,只是没被推荐出口——跟能不能发布 没关系。包表说"作者想让你用哪几个",private 字段说"实际能装哪几个"。

接下来是五条纪律。它们不是并列的五条,是同一根管道上的五个卡点:

text
  源码 packages/      │      │ 11.1 解析期   .npmrc:save-exact + min-release-age=2      ▼  锁文件      │      │ 11.2 提交期   check-lockfile-commit.mjs 拦锁文件变更      ▼  tarball(pack:packages 打出来的)      │      │ 11.5 发布前   check:package-install 先装进真项目跑一遍      ▼  npm registry      │      │ 11.4 安装期   install-lock 的 lifecycle 白名单,双向断言      ├─────────▶ 官方安装器:走 install-lock 假根,传递依赖全钉死      └─────────▶ npm i -g:只钉直接依赖,传递依赖当场解析(11.3)

到用户机器这一步分了两条路,11.3 讲的就是这件事。 下面是按"能拦住多少事故"排的,不是按管道顺序排的。

11.1 不许"今天刚发布的依赖"

.npmrc 只有两行:

ini
# .npmrcsave-exact=truemin-release-age=2

save-exact 让直接依赖连 ^ 都不许;min-release-age=2 是 npm 的 发布时间门禁:不到 2 天的版本,解析时直接跳过。

这一条防的是 npm 生态最典型的投毒:抢注包名、立刻发一个往安装脚本 里塞币的版本,靠前几小时大量项目自动升级得手。2 天冷静期买的是 "让别人先踩雷"的时间。代价也真实:上游修完漏洞,你也得等两天。

11.2 锁文件是代码,得 review

.husky/pre-commit 的第一件事不是格式化,是查锁文件:

sh
# .husky/pre-commit(节选)STAGED_FILES=$(git diff --cached --name-only)node scripts/check-lockfile-commit.mjsif [ $? -ne 0 ]; then  exit 1fi

scripts/check-lockfile-commit.mjs(120 行)的逻辑是三道放行、一道拦截:

情形 结果
本次没暂存 package-lock.json 直接过(:82-84)
设了 PI_ALLOW_LOCKFILE_CHANGE=1 过,并提醒你一句(:86-89)
变更只涉内部包的元数据 过(:91-95)
其余一律拦 列出版本变化摘要(前 40 条),exit 1(:97-120)

第三条值得单独说:"只涉内部包元数据"也放行。内部包版本联动是常态, 每回都要人签字,签字很快就成橡皮了。闸门卡在该卡的地方,才能 一直卡得住。

拦下来的时候它不只说"不行",还告诉你具体怎么放行: PI_ALLOW_LOCKFILE_CHANGE=1 git commit ...。放行需要显式写一个环境变量, 而不是点一下"我知道了"。

11.3 installer 装的,和 npm 装的不是同一个东西

同一个版本号 1.4.0,两条安装路径拿到的东西不一样:

  • 官方安装器:从 packages/coding-agent/install-lock/ 装。那是个 private: true 的假根,只声明一个依赖、一条 override,旁边配 52 KB 的 lock——传递依赖全被钉死。
  • npm i -g:钉直接依赖,传递依赖由 npm 当场解析。
json
{  "name": "@earendil-works/pi-coding-agent-install",  "private": true,  "dependencies": { "@earendil-works/pi-coding-agent": "1.4.0" },  "overrides": { "protobufjs": "7.6.6" }}

README 把这句话放在 Getting started 里,只用了一个从句 ("which does not pin transitive dependencies")一带而过。但它是整节 的根:能钉就钉,钉不了就明说钉不了。

那个 overrides 也不是摆设。protobufjs 不在直接依赖里,是被拉进来的 传递依赖;把它写成常量,等于在告诉 npm:不管上游谁要它,都用这个版本。

11.4 lifecycle script 白名单是双向的

依赖可能在安装时执行任意代码(postinstall),所以白名单本身也是 攻击面。scripts/generate-coding-agent-install-lock.mjs(456 行) 两个方向都拦:

  • :328 — 锁里出现带安装脚本的包,报错,等人 review 后加白名单;
  • :335-337 — 白名单里的包在锁里消失了,也报错,逼你删掉这一行。

只做第一个方向的话,白名单只会越来越长,最后长到没人看。双向断言是 所有白名单的防腐剂。

11.5 测的和发的,必须是同一份

  • npm run pack:packages 把包打成一堆 tarball;
  • check:package-install 把它们装进一个真项目跑一遍;
  • npm publish 发的是这份验过的 tarball,不回工作区重新打。

一句话:你测的字节,和你发的字节,必须能对上一一对应。 从工作区重新 打包再发,等于发了一份没人测过的东西——而它看起来跟测过的那份一模一样。

CI 那边是同一个思路的两半:npm ci --ignore-scripts 装(不跑安装脚本), 然后 npm audit --omit=dev 查漏洞、查签名;时间表是每天 07:37 (.github/workflows/npm-audit.yml 的 cron)。漏洞库天天在长,审计就必须 有定时器,不能只靠发版那天跑一次。

11.6 为什么一个 agent 仓库要这么狠

因为 agent 会自己跑 npm install,也会自己改 package.json。

人类仓库里,"锁文件变更要过目"是个软约定,靠自觉,漏一次也没人发现。 agent 仓库里它必须是硬闸门:它不会"顺手看一眼 diff",但 pre-commit 一定会跑。

所以这一节和全书的关系不是"顺便讲讲工程实践": 这条边管不住,上一节那 18 个 ✅ 都白搭。 仓内拓扑序再干净,也挡 不住一个被投毒的传递依赖——而它照样能通过全部类型检查。


十二、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

实验 1:把图算出来。

bash
node -e "const fs=require('fs');const name2dir={},deps={};for(const d of fs.readdirSync('packages')){  const p='packages/'+d+'/package.json';  if(!fs.existsSync(p))continue;  const j=JSON.parse(fs.readFileSync(p,'utf8'));  name2dir[j.name]=d;  deps[d]=j.dependencies||{};}for(const d in deps){  deps[d]=Object.keys(deps[d]).filter(n=>name2dir[n])    .map(n=>name2dir[n]);}const memo={};const depth=(d,stack=new Set())=>{  if(memo[d]!==undefined)return memo[d];  if(stack.has(d))return 0;  stack.add(d);  const v=deps[d].reduce((m,x)=>Math.max(m,1+depth(x,stack)),0);  stack.delete(d);  return memo[d]=v;};for(const d of Object.keys(deps).sort())console.log(depth(d),d);"

输出 12 行,按目录名字母序(sort() 的结果):agent 2、ai 1、chord 1、codemode 0、coding-agent 3、durable 2、env 3、evals 0、mcp 0、schema 0、telemetry 0、tui 0——和第三节那张表 12/12 一致。

这个脚本为什么多了一行 name2dir? 因为包名不是目录名:@earendil-works/pi-ai 的目录是 packages/ai。直接 replace('@earendil-works/','') 会得到 pi-ai,deps['pi-ai'] 查不到任何人,所有兄弟边都变成 0,整张图塌成 0/1/2 三层、还静默不报错。本章第一版脚本就是这么错的。

实验 2:验证没有反向边。

bash
node -e "const fs=require('fs');const order=fs.readFileSync('package.json','utf8')  .match(/\"build\": \"([^\"]+)\"/)[1]  .split('cd ../').map(s=>s.replace('cd packages/','').trim());const idx={};order.forEach((s,i)=>{const m=s.match(/^([a-z-]+)/); if(m)idx[m[1]]=i;});let bad=0;for(const d of Object.keys(idx)){  const p='packages/'+d+'/package.json';  const j=JSON.parse(fs.readFileSync(p,'utf8'));  for(const k of Object.keys(j.dependencies||{})){    const dep=k.replace('@earendil-works/','').replace('pi-','');    const real=dep==='agent-core'?'agent':dep;    if(idx[real]===undefined)continue;    if(idx[real]>=idx[d]){console.log('反向:',d,'->',real);bad++;}  }}console.log(bad===0?'OK 无反向边':'发现 '+bad+' 条反向');"

实验 3:确认那条缺席的边。

bash
grep -c "pi-durable" packages/coding-agent/package.jsongrep -rl "pi-durable" packages/coding-agent/src | wc -l
powershell
(Select-String -Path packages/coding-agent/package.json `  -Pattern 'pi-durable').Count(Get-ChildItem packages/coding-agent/src -Recurse -Filter *.ts |  Select-String -Pattern 'pi-durable').Count

两条都应该是 0。


十三、工程暗坑

1. npm 名和目录名对不上,重命名映射写在代码里。

目录 npm 名
agent @earendil-works/pi-agent-core
ai @earendil-works/pi-ai
chord @earendil-works/chord
其余 9 个 @earendil-works/pi-<目录名>

agent 和 chord 是例外。写脚本把 npm 名映射回目录名时,pi-agent-core → agent 这条必须硬编码,否则会去找一个叫 agent-core 的目录。

2. 深度算法在环上会死循环。

上面的脚本用 seen 集合防环。真实仓库里没有环(npm 也不允许),但如果你改成"边遍历边算",一旦未来出现循环依赖,它会静默返回 0 而不是报错。算图之前先查环。

3. 深度不等于分层,别拿它排 build。

env 和 agent 的例子说明:深度 3 的包可以排在深度 2 的包前面。按深度分组只能得到"哪些包可以并行构建",不能得到唯一顺序。

4. dependencies 里可能写着 workspace:*。

v1.4.0 这个仓库全部写死 1.4.0。如果你看到 workspace:*,说明是别的仓库或别的版本,npm version --workspaces 那套流程不适用。

5. 五个零依赖包里有一个其实"有依赖"。

tui 的 dependencies 是空的,但它运行时需要原生二进制(native-module-path.ts、build:native:win32 那几条脚本)。这属于"运行时隐式依赖",dependencies 看不出来,只有 build 顺序知道——tui 排在 coding-agent 前面就是这个原因。


十四、四个可以带走的方法

方法一:用 dependencies 当"能看见什么"的尺子。

一个包能犯什么错,取决于它能 import 什么。agent 只有两个依赖,所以它写不出文件、拿不到网络、碰不到 session——这不是靠自觉,是编译器拦着。

读一个陌生 backend 项目,先看最内层那个包的 dependencies。它短,说明边界画得清;它长,说明边界已经糊了。

方法二:区分拓扑序和分层序。

拓扑序回答"先编谁",分层序回答"谁能看见谁"。两者经常被混为一谈,后果是:你以为把 env 挪到 agent 后面是"修复分层",其实那个改动毫无意义——它们之间没有边。

判断一个包在第几层,看最长路径而不是构建位置。

方法三:把"缺席的边"列成清单。

coding-agent → durable 不存在,coding-agent → schema 不存在。这两条缺席比 18 条存在的边更能说明架构:它故意让两套会话实现并存,也故意不让你跨两跳引类型。

做完一张依赖图,试着把"你以为该有但没有"的边都列出来,每一条背后都是一个设计决定。

方法四(额外送一条):用每文件行数判断该扫还是该读。

拿到一个陌生的包,先算 总行数 / 文件数:

  • 均值 < 150,扫文件名就够(一概念一文件)
  • 均值 > 400,必须通读全文(一职责一大文件)
  • 中间地带,先读 index.ts 看导出面

这条规则在 12 个包上全部命中。它不是玄学:切文件的方式就是作者对"什么是同一个东西"的理解,而理解方式直接决定了你该用什么策略去读。


本章小结

  1. 层不是画的,是依赖图上的最长路径算出来的。
  2. 五个零依赖包:schema telemetry tui mcp codemode。
  3. 两个归一层方向相反:ai 归一厂商,agent 归一会话。
  4. 缺席的那两条边(→durable、→schema)比存在的 18 条更能说明架构。
  5. npm 名 ≠ 目录名,pi-agent-core → agent 必须硬编码。

概念回顾

术语 一句话 在哪
包 一个目录就是一个 npm 包,名可以不同 §二
层 依赖图上从零依赖包算起的最长路径 §三
归一 把 N 家差异折叠成同一个接口 §五
缺席的边 你以为该有、但故意不存在的那条依赖 §九
离仓那条边 installer 带着 install-lock/ 把传递依赖钉死 §十一

练习

练习 1(读):§九 列了三条反直觉的边。挑一条,去对应 packages/*/package.json 里把它的出处行号找出来;找不到的那条, 说明它为什么是"故意缺席"。

练习 2(改):把依赖图脚本里的 pi-agent-core → agent 这条映射 删掉重跑。预期:agent 查不到目录,整张图塌成 0/1/2(M01 §四 实测); 回滚:把这条映射加回去,并保留 seen 栈防环。

常见误区

  1. 你会以为 层是目录结构定的;实际是 依赖图算的;证据 §三 脚本输出。
  2. 你会以为 tui 零依赖就什么都不需要;实际是 它运行时需要原生二进制, 所以 build 排在 coding-agent 前面;证据 §十三 坑 5。
  3. 你会以为 五个零依赖包重要性相同;实际是 codemode 自带沙箱, 体量远超其余四个;证据 §四 的体量表。

读完自检

四条,能不能不看稿说出来?说不出来的那条,回右边一格重读。

自检 一句话答案 不会就去
层是画的,还是算出来的? 算出来的:看依赖图上的最长路径,不看构建位置 §三
五个零依赖包是哪五个? schema telemetry tui mcp codemode §四
为什么 coding-agent 不依赖 durable? 两套会话实现故意并存,跨这条边就得二选一 §9.2
同一个版本号,installer 装的为什么和 npm 装的不一样? installer 从 install-lock/ 装,传递依赖全钉死;npm 不钉 §11.3

下一步

图有了,接下来该下潜了。

Part B 从 agent-loop.ts 开始——960 行,两个循环,三条出路。那是整张图里最瘦的节点,也是唯一一个"少一行就少一个能力"的地方。


源码索引

文件 行数 本章用到的位置
package.json 76 build 序列 :15、workspaces :5-12
packages/agent/package.json 51 两条依赖 :25-28
packages/agent/src/types.ts 552 Static<> 导入 :17
packages/ai/src/index.ts 48 入口分层注释 :1-5
packages/ai/src/models.generated.ts 310 主入口刻意不加载
packages/schema/src/compiler.ts 594 schema 编译成闭包
packages/telemetry/src/noop.ts 38 38 行的空实现
packages/mcp/src/client.ts 622 MCP 客户端主体
packages/codemode/src/runtime/ 8 文件 / 2,067 沙箱本体
packages/durable/src/harness/ 25 文件 运行时主体
packages/coding-agent/src/core/session-manager.ts — 自带的会话实现
packages/coding-agent/src/core/tools/ 16 文件 8 工具 + 8 配套件
packages/env/src/remote-env.ts 958 远端执行环境