三层架构 —— 十二个包各自站在哪一层
上一章给了一张体量表。但体量只回答"哪里代码多",不回答"哪块代码归谁管"。
这一章给的是后者:一张能定位任何文件的图。
零、读这章之前,你需要先知道一件事
三个词:monorepo = 一个仓库里放很多包;workspace = npm 让这些包互相认识的机制
(就是根 package.json 里那个 workspaces 字段);依赖深度 = A 依赖 B、B 依赖 C,
则 A 到 C 的距离是 2。
没有它会怎样:你会把 12 个 package.json 当成 12 个要发布的包,再把
node_modules 里指向同仓库的软链当外部依赖——两条都能推出错误结论。
本书哪里用到:§三 那张 12 行表;算法在 §十二 实验 1。
一、给一个路径,你能说出它在哪层吗
先做个小测。下面六个路径,各自属于哪一层?
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 三步判层法
给定任意一个文件路径,三步就能判出它属于哪一层:
第一步:取 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) —— 一条边的方向是"依赖方 → 被依赖方"。按路径长度给每个包算一个深度:
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 层(基础 / 运行时 / 产品) | 谁负责什么 |
职责切法是这样的:
基础层 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 |
最后一列很容易被忽略,但它是个免费的情报:每文件行数告诉你这个包按什么切文件。
schema107 /ai140 → 按"一个概念一个文件"切,文件多而小tui434 /agent427 → 按"一个职责一个大文件"切,文件少而大
两种都是对的,但读法不同。schema 里你需要扫文件名找功能(coerce.ts 管转换、explain.ts 管报错);agent 里你必须通读全文,因为 agent-loop.ts 一个文件就是整层逻辑。
agent 以 6 个文件、427 行均值成为全仓库最"胖"的包。这不是美学选择,是刻意不拆:拆成 10 个文件之后,那个 960 行的循环会被切断,读的人就得在文件间跳。M03 会看到它为什么不拆。
4.1 schema 的结构暴露了它的野心
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 32formats/ 一个文件一个 format(email、date-time、uri…),31 个文件 1,713 行,占了 37%。这种"一格式一文件"的排布说明它追求的是穷举而非通用:每个 format 都有自己的边界条件(email 的国际化、date-time 的闰秒),塞进一个 switch 会变成噩梦。
explain.ts 391 行单独成文件,是为了给模型看的错误信息。校验失败时,agent 要把错误回给模型让它改参数,所以"错在哪、期望什么、实际是什么"必须是结构化可读的,不能是一句 invalid。
4.2 telemetry 只有 5 个文件,但结构很讲究
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 的文件名就是一份需求清单
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
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
runtime/ 2,067 8 文件(沙箱本体)declarations.ts 341 TS 声明生成types.ts 255source.ts 126cloudflare.ts 76portable.ts 54codemode 的整个意义是"模型写的代码只能在受限环境里跑",所以 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):
// 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 里最反直觉的比例:
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 解决的不是"不同的外部服务",而是"同一个进程里多个插件之间怎么通信"。
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/。
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。它们互不依赖,这是全图最重要的一条"缺席的边"。
agent → ai, schema 2,559 行durable → chord, ai, codemode, schema, telemetry 33,728 行6.1 agent 只认两样东西
"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 个包,因为它是运行时
chord → 插件宿主(热重载)ai → 调模型codemode → 沙箱执行schema → 工具参数校验telemetry → 遥测再加它自己 33,728 行。durable/src/ 的目录结构:
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.tstasks.ts / documents.ts / timers.ts / search.ts 这四个根层文件说明它的野心不止对话:任务、文档、定时器、搜索都是一等公民。
再看 harness/ 那 24 个文件的实际分布(共 11,332 行):
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.tsharness/ 里最大的不是 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 是产品,所以它最大
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 个文件,拆开是这样:
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 搬到远端
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% 会猜错。
八、全景图
把上面四节合成一张图。箭头方向 = 依赖方向。
┌─────────────────────────────┐ 产品层 │ 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。两件事都是反的。
① 依赖方向(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。
九、三条反直觉的边
图里有一条边画出来会让人愣一下,另有两条该有却没有。 §八 那张图看不出"哪条边缺席",所以单独拎出来画:
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):
import type { Static } from "@earendil-works/pi-schema";Static<T> 干的事是把 JSON Schema 字面量转成 TypeScript 类型。写了:
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 要依赖它"。
事实:
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 步):
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 字段说"实际能装哪几个"。
接下来是五条纪律。它们不是并列的五条,是同一根管道上的五个卡点:
源码 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 只有两行:
# .npmrcsave-exact=truemin-release-age=2save-exact 让直接依赖连 ^ 都不许;min-release-age=2 是 npm 的
发布时间门禁:不到 2 天的版本,解析时直接跳过。
这一条防的是 npm 生态最典型的投毒:抢注包名、立刻发一个往安装脚本 里塞币的版本,靠前几小时大量项目自动升级得手。2 天冷静期买的是 "让别人先踩雷"的时间。代价也真实:上游修完漏洞,你也得等两天。
11.2 锁文件是代码,得 review
.husky/pre-commit 的第一件事不是格式化,是查锁文件:
# .husky/pre-commit(节选)STAGED_FILES=$(git diff --cached --name-only)node scripts/check-lockfile-commit.mjsif [ $? -ne 0 ]; then exit 1fiscripts/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 当场解析。
{ "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:把图算出来。
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:验证没有反向边。
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:确认那条缺席的边。
grep -c "pi-durable" packages/coding-agent/package.jsongrep -rl "pi-durable" packages/coding-agent/src | wc -l(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 个包上全部命中。它不是玄学:切文件的方式就是作者对"什么是同一个东西"的理解,而理解方式直接决定了你该用什么策略去读。
本章小结
- 层不是画的,是依赖图上的最长路径算出来的。
- 五个零依赖包:
schematelemetrytuimcpcodemode。 - 两个归一层方向相反:
ai归一厂商,agent归一会话。 - 缺席的那两条边(→
durable、→schema)比存在的 18 条更能说明架构。 - 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 栈防环。
常见误区
- 你会以为 层是目录结构定的;实际是 依赖图算的;证据 §三 脚本输出。
- 你会以为
tui零依赖就什么都不需要;实际是 它运行时需要原生二进制, 所以 build 排在coding-agent前面;证据 §十三 坑 5。 - 你会以为 五个零依赖包重要性相同;实际是
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 | 远端执行环境 |