开篇 —— 为什么 Pi-Agent 值得你花时间
先看 README 的第一句话:
Pi is a minimal, extensible agent harness that you can make your own.
"minimal"和"extensible"这两个词经常一起出现,但很少同时成立。极简的东西通常定死,可扩展的东西通常臃肿。Pi 的说法是:内核做小,把复杂度赶到外围,外围全部可替换。
这句话是不是真的,不用看宣传,看行数就行。
零、三个问题,一个答案
标题问"值不值得花时间",答案先摆在这儿,后面每一节都是它的证据。你点开这本书,多半是下面三句话里有一句像你:
| 你的动机 | Pi 的对应身份 | 一句话答案 | 证据 |
|---|---|---|---|
| "想找个好用、透明的编码 agent" | 工具 | 缺的功能它不塞给你,但每条都留了出口让你自己造 | §五、§六 |
| "想知道 agent 到底怎么做的" | 教材 | 内核 2,559 行,一下午读得完;4,206 行测试把每个边界条件单独钉住 | §一、§三 |
| "要做自己的 agent" | SDK | 十行起一个 session,对外契约只有 index.ts 那 5 行 |
§一、§七、附录 C、E01–E08 |
三个动机指向同一个只占仓库 1.1% 的包,这件事本身就值得好奇。多数框架只满足其中一条:好用的读不透,读得透的没测试,能当 SDK 的得先把整个运行时啃完。
三笔账,分开算。
当工具用:五个入口(交互 / print / JSON / RPC / SDK)共用同一套机制(§六),八个内置工具每个都配一个配套件(§三)。它明说不做权限系统、不做 sub-agent、不做 plan mode,但每个"不做"后面都跟着"你想要就自己写,出口在这张表里"(§五)。花时间换来的是能改成自己的,不是配置项多一点。
当教材读:一个 agent 框架最难自学的是边界在哪,Pi 把边界写得很便宜——内核只占 1.1%(§一),"不做"清单就是边界(§十二 方法三),78% 的代码在处理和模型无关的事(§三)。你读的这 2,559 行是通用机制:换个语言或模型商,两层循环和三条出路照样成立。§1.1 那句"源码小、测试大、文档厚"则让你看到高质量 agent 的真实成本结构。
当 SDK 用:agent 包的对外契约收敛在 5 行 index.ts 里(§一),§七 那十行代码没有一行循环,却跑完了整场。你不需要碰 tui,不需要碰 coding-agent 那 77,614 行——只要能拿到 stream(model, context, options) 和它吐出的那串事件。附录 C 把这条路走完:一个 HTTP + SSE 的服务,里面包着一个 agent。
什么人不用花时间。 三种情况直说:
- 只想装个 CLI 就能用 → 装就是了,别读源码。它不带权限系统、不带 sub-agent,开箱能直接用的那块给得很少(§五)。
- 不会 TypeScript 又不想学 → 先花十二分钟读附录 B,否则 M03 第一段代码就会卡住。
- 想学提示词工程 → 本书不是那类书。M08 讲的是 Pi 自己那八节提示词怎么装配、从哪条目录链读来,不教你怎么写 prompt。
所以 README 那句 "minimal" 算成立,但成立的只有第一个含义:不是整个项目小,是核心小(§一)。22 万行外围一行没少,只是它们全在可替换的那一侧。值得花时间的理由也在这儿——你要读的那一小块不大,却正好是最难自己想清楚的那一块。
读这章之前:你需要先知道一件事
agent 是什么:一个能自己决定"下一步做什么"的模型,加一个把它套起来的循环。 「问一句答一句」不算——它得能自己发起工具调用、看到结果、再决定下一步。
没有它会怎样:你会把"调一次模型"当成 agent 的全部,然后想不通这本书为什么用一整章
(M03)去解释一个 while 循环。
本书哪里用到:§四 那张三层图里有它,M03 全章都在拆这个循环。
一、仓库自报的数字,互相打架
把源码 clone 到本地,钉在 v1.4.0 这个 tag 上:本书所有行号、文件数、代码行数 都是这一份快照里数的,上游后来已发到 v1.5.x,默认分支对不上。
git clone --depth 1 --branch v1.4.0 \ https://github.com/earendil-works/pi.gitcd pi进到仓库根目录,数一遍:
# 只数 packages/*/src 下的 .ts,排除 test / distfind packages -path '*/src/*' -name '*.ts' | wc -l # 920find packages -path '*/src/*' -name '*.ts' -exec cat {} + | wc -l # 228,895# PowerShell 5.1 等价写法(Get-ChildItem packages -Recurse -Filter *.ts | Where-Object FullName -match '\\src\\').Count # 920(Get-ChildItem packages -Recurse -Filter *.ts | Where-Object FullName -match '\\src\\' | Get-Content | Measure-Object -Line).Lines # 228895920 个文件,22.9 万行 TypeScript。这个体量谈不上"minimal"。
下文凡是命令行,都默认当前目录是仓库根目录(git clone 后的那个 pi/)。
Windows 读者看这一行就够: 含 &&、$VAR、| head、heredoc 的命令,本书紧跟一个 powershell 版;只用到 grep / sed / find / ls 的地方不逐条双写,对照关系如下(后文不再重复):
| bash | PowerShell 5.1 |
|---|---|
grep -n 模式 文件 |
Select-String -Path 文件 -Pattern 模式 |
sed -n '71,99p' 文件 |
(Get-Content 文件)[70..98] |
find . -name '*.ts' |
Get-ChildItem -Recurse -Filter *.ts |
ls 目录 |
Get-ChildItem 目录 |
wc -l 文件 |
(Get-Content 文件).Count(少算末尾换行,见 §十一 坑 2) |
但按包拆开,分布是这样的(每包一个 wc -l,命令见 §十 实验 1):
| 包 | 行数 | 占比 | 一句话 |
|---|---|---|---|
coding-agent |
77,658 | 33.9% | 交互式 CLI,主力 |
chord |
50,101 | 21.9% | 热重载插件宿主 |
durable |
33,728 | 14.7% | 可持久化运行时 |
ai |
28,581 | 12.5% | 多 provider 统一层 |
tui |
19,971 | 8.7% | 终端差分渲染 |
schema |
4,608 | 2.0% | 类型契约 |
mcp |
3,305 | 1.4% | 外部工具协议 |
codemode |
3,054 | 1.3% | 沙箱脚本执行 |
agent |
2,559 | 1.1% | 无状态内核 |
env |
2,398 | 1.0% | 环境抽象 |
telemetry |
1,580 | 0.7% | 遥测契约 |
evals |
1,452 | 0.6% | 评测工具 |
内核 agent 只占 1.1%。剩下 98.9% 全是它的外围。
这就是"极简"的第一个含义:不是整个项目小,是核心小。agent 包 6 个文件:
agent-loop.ts 960 两层循环agent.ts 624 有状态外壳types.ts 552 全部类型proxy.ts 396 代理流函数stream-fn.ts 21 默认流函数注册index.ts 5 桶文件index.ts 只有 5 行,因为它是纯桶(barrel):
export * from "./agent.ts";export * from "./agent-loop.ts";export * from "./proxy.ts";export { setDefaultStreamFn } from "./stream-fn.ts";export * from "./types.ts";这 5 行里没有一行是逻辑,但它告诉你一件事:这个包的对外契约全部收敛在 5 个模块里。读 agent 不需要跳来跳去,六个文件加起来 2,559 行,一下午能读完。
而这 2,559 行要支撑的是 226,436 行的外围——内外比 1 : 88。
1.1 但真实行数还要多一倍
上面那个 22.9 万只是 ".ts 文件里的源码"。把 test/ 目录也算进去,整个仓库是这样的:
| 分类 | 文件数 | 行数 |
|---|---|---|
src/ 源码 |
927 | 229,029 |
test/ 测试 |
1,148 | 288,596 |
| 其余(examples / scripts / 配置) | 191 | 22,262 |
| 合计 | 2,266 | 539,887 |
三个数字值得停下来看。
一,测试行数比源码多 26%。 288,596 vs 229,029。而且文件数更极端:2,266 个 .ts 里,1,148 个是测试,占 50.7%——随便拎一个文件名出来,一半概率是 .test.ts。
二,内核的测试比例最高。 agent 包 6 个源文件 2,559 行(wc -l 数出来是 2,553,每个文件差 1 行),配 8 个测试文件 4,206 行,比例 1 : 1.6。拆开看:
agent-loop.ts 960 ←—→ agent-loop.test.ts 2,234agent.ts 624 ←—→ agent.test.ts 1,229types.ts 552proxy.ts 396 ←—→ proxy.test.ts 171stream-fn.ts 21index.ts 5agent-loop.ts 一个文件配了 2.3 倍行数的测试。全包测试占比 63%,是 12 个包里最高的。
三,这不是反例,是代价的转移。 "极简内核"并不是真的简单——它是把复杂度从"代码分支"挤到了"状态组合"。960 行里塞了两个循环、五条退出路径、五个可变状态、三种恢复层,可能的状态组合远超 960 行能容下的显式分支。于是余量只能写在测试里:每个边界条件单独一个 case。
所以"极简"的完整定义是:源码小,测试大,文档厚。三者加起来才是真实成本。本书只讲源码那一块,但你必须知道另外两块存在——否则会低估改一行代码的风险。
顺带一个阅读提示:全书引用的行号、体量、比例,默认都不含 test/ 与 dist/。看到与你自己数的对不上,先检查这两个目录。
二、README 公示 7 个包,仓库里有 12 个
README 的 ## Packages 表格列了 7 个包:
@earendil-works/chord@earendil-works/pi-telemetry@earendil-works/pi-ai@earendil-works/pi-durable@earendil-works/pi-agent-core@earendil-works/pi-coding-agent@earendil-works/pi-tui而 packages/ 下实际有 12 个目录,全部 version 1.4.0:
| 目录 | npm 名 | README 公示 |
|---|---|---|
agent |
@earendil-works/pi-agent-core |
✅ |
ai |
@earendil-works/pi-ai |
✅ |
chord |
@earendil-works/chord |
✅ |
coding-agent |
@earendil-works/pi-coding-agent |
✅ |
durable |
@earendil-works/pi-durable |
✅ |
telemetry |
@earendil-works/pi-telemetry |
✅ |
tui |
@earendil-works/pi-tui |
✅ |
codemode |
@earendil-works/pi-codemode |
❌ |
env |
@earendil-works/pi-env |
❌ |
evals |
@earendil-works/pi-evals |
❌ |
mcp |
@earendil-works/pi-mcp |
❌ |
schema |
@earendil-works/pi-schema |
❌ |
差的 5 个不是"忘了写"。看名字就知道它们偏工具链:
schema—— 类型契约,agent、ai、chord、durable都依赖它,但用户不直接用mcp—— Model Context Protocol 接入,可选扩展codemode—— 沙箱里执行模型写的脚本,可选能力env—— 环境抽象,给chord/durable用evals—— 评测,npm run eval才用得上
公示的是"用户会装的",隐藏的是"内部零件"。这个区分很有用:读源码时先判断一个包是"面向用户"还是"面向兄弟包",读法完全不同——前者要看它的 CLI 和文档,后者只需看它的导出。
三、那 22 万行到底在补什么
内核只做一件事:给定上下文,驱动"模型 ↔ 工具"的循环。它不管的事有六类,对应六个大包。
| 缺什么 | 谁补 | 行数 |
|---|---|---|
| 各家 provider 的协议差异 | ai |
28,581 |
| 终端怎么画得快 | tui |
19,971 |
| 会话怎么存、怎么恢复 | durable |
33,728 |
| 工具怎么安全地并发改文件 | coding-agent |
77,658 |
| 插件怎么热更新 | chord |
50,101 |
| 怎么接外部 MCP server | mcp |
3,305 |
按顺序说。
ai(28,581 行) —— 7 家 provider 各有一套事件格式、错误码、工具调用协议、thinking 参数。ai 把它们归一成一件事:stream(model, context, options) 返回一个事件流,事件类型固定 12 种。这套归一层之所以占 12.5%,是因为协议适配天然啰嗦——一个 provider 一个文件,每个文件几百到两千行。
tui(19,971 行) —— 终端渲染不是 console.log。要处理宽字符、ANSI 转义、光标定位、双缓冲差分。Pi 的 TUI 能做到"改一个字符只发一个字符的字节量",靠的就是这 2 万行。
durable(33,722 行) —— 名字容易误解成"会话存储包"。它有 harness/(25 文件)、scheduler.ts(2,999 行)、tool.ts(1,098 行)、generation.ts(1,148 行),是一个完整的可持久化 agent 运行时。存只是它的副作用,"中断后从断点继续"才是目的。
durable/src/ 的顶层目录把它暴露得很彻底:
harness/ 25 文件 运行时主体(scheduler / tool / generation)session/ 7 文件 会话与事务storage/ 多后端 jsonl / sqlite / memory / indexeddb / storecodemode/ 沙箱执行tools/ 内置工具tool-search/ 工具检索images/ env/ testing/tasks.ts documents.ts entries.ts timers.ts search.ts最后那五个根层 .ts 是信号:一个包如果只有存储,不会有 scheduler(调度)和 timers(定时器)。这两个词出现在哪里,哪里就有"时间"——而"时间"是 agent 运行时最难持久化的东西。
coding-agent(77,658 行) —— 占三分之一,因为它是产品。CLI 参数、交互模式、命令系统、8 个内置工具、扩展加载、Skills、主题、RPC 服务……所有"用户能感知到的东西"都在这里。
chord(50,101 行) —— 第二大的包,也是最容易被忽略的。它是个通用插件宿主:contract 契约、replicated state、JSON link 上的 RPC、热重载。它和 agent 没有必然关系,是个独立产品,被 durable 和 env 复用。
chord/src/ 有 29 个顶层文件加 7 个子目录,名字能拼出一套完整机制:
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 ← 热重载注意 delta.ts 和 reload.ts 同时存在。前者说明状态变更以增量传播,后者说明代码可以在不重启进程的情况下被替换。这两件事能同时成立,才叫"热重载的插件宿主"。
mcp + codemode(6,339 行) —— 两条扩展路线。mcp 接外部工具服务器,codemode 让模型写脚本在沙箱里跑。都是可选能力,加起来只占 2.8%。
对比一下就很清楚:78% 的代码在处理"和模型无关的事"——UI、存储、插件、协议、并发。真正的 agent 逻辑只有 1.1%。
再补三个"只有读代码才知道"的细节,它们能校准你对每个包的预期。
schema 不用 eval。 包描述写得很具体:
JSON Schema validation without eval: drafts 2020-12 and 7, compiled into plain closures
大多数 JSON Schema 校验库在运行时拼字符串再 eval,或者解释执行 schema 树。schema 的做法是把 schema 编译成一组普通闭包。为什么值得单独立包?因为工具参数校验在 agent 里是热路径——每次工具调用都要跑一遍,它必须快且能跑在受限环境里。
codemode 的权限边界只有一条。
Sandboxed JavaScript execution where the only capability is calling injected tools
"唯一能力就是调注入的工具"——沙箱里连 fetch 都没有,模型写的脚本能碰到的只有你主动注入的那几个函数。这比"禁掉危险 API"的黑名单思路可靠得多。
coding-agent 的 tools/ 目录有 16 个文件,但只有 8 个工具。
真工具:bash powershell read write edit find grep ls配套件:file-mutation-queue output-accumulator truncate path-utils render-utils edit-diff tool-definition-wrapper index每个工具配一个配套件,比例 1 : 1。这不是冗余,是这 8 个工具能安全并发的全部原因——file-mutation-queue 管同一个文件的写冲突,output-accumulator 管流式输出别撑爆内存,truncate 管输出长度上限。M05 会把这三件事拆开讲。
四、build 顺序能当依赖图看吗
根 package.json 的 build 脚本是一长串手写的 cd(package.json:15,原文是一行,这里按箭头折开):
cd packages/telemetry && npm run build &&cd ../schema && npm run build &&cd ../chord && npm run build &&cd ../tui && npm run build &&cd ../codemode && npm run build &&cd ../mcp && npm run build &&cd ../ai && npm run build &&cd ../durable && npm run build &&cd ../env && npm run build &&cd ../agent && npm run build &&cd ../coding-agent && npm run build# PowerShell 5.1 不认 &&,用 foreach 保持同一顺序foreach ($p in 'telemetry','schema','chord','tui','codemode','mcp', 'ai','durable','env','agent','coding-agent') { cd packages/$p; npm run build; cd ../..}11 步,evals 不在里面(它是测试工具,构建时不参与)。注意 build:offline 是同一个序列,只把 ai 换成 npm run build:offline——因为它默认会去网络拉模型目录。
为什么必须手写这个顺序而不能交给 npm run build --workspaces?因为 workspace 的构建顺序取决于拓扑排序,而这个仓库里存在不经过 npm 依赖声明的隐式依赖——比如 coding-agent 的构建脚本会去读 tui 产出的原生二进制。手写顺序是"显式声明拓扑",代价是每次新增包都要记得改这一行。
把每个包的 dependencies 拿出来,能得到真正的依赖图(数据源:各包 package.json 本身):
| 包 | 依赖的兄弟包 |
|---|---|
telemetry |
— |
schema |
— |
tui |
— |
mcp |
— |
codemode |
— |
chord |
schema, telemetry |
ai |
schema, telemetry |
durable |
chord, ai, codemode, schema, telemetry |
env |
chord, durable |
agent |
ai, schema |
coding-agent |
agent-core, ai, codemode, mcp, tui |
evals |
— |
三个观察。
第一,5 个包零依赖。 telemetry schema tui mcp codemode 谁也不依赖,所以它们排在最前面,也最容易被单独复用。tui 甚至可以脱离 Pi 当通用终端 UI 库用。
第二,agent 只依赖 ai 和 schema。 它不知道 coding-agent 存在,不知道 durable 存在,更不知道 tui。这是内核能做小的结构保证——依赖少,能看见的东西就少。
整个依赖声明就这么三行(packages/agent/package.json:25-28):
"dependencies": { "@earendil-works/pi-ai": "1.4.0", "@earendil-works/pi-schema": "1.4.0"}两个版本号全是写死的 1.4.0,没有 ^。
锁版本是 monorepo 的常见选择,但"所有包同一个版本号"要更狠一点:它消除了"A 依赖 pi-ai@1.2、B 依赖 pi-ai@1.4"这类幽灵问题,代价是任何包升版都得全体一起升。看一眼升版脚本就知道(package.json:42):
npm version patch --workspaces --no-git-tag-version \ --no-workspaces-update && node scripts/sync-versions.js# 续行用反引号,不是反斜杠;&& 换成 ;npm version patch --workspaces --no-git-tag-version ` --no-workspaces-update; node scripts/sync-versions.js--workspaces 一次改 12 个 package.json,sync-versions.js 再扫一遍把漏网的内部依赖版本同步。两条命令省不了:前者改 version 字段,后者改内部 dependencies 里引用的版本号。
第三,coding-agent 不依赖 durable。 这条最反直觉:一般会以为会话管理在 durable,CLI 自然要依赖它。事实是 coding-agent 有自己的 src/core/session-manager.ts,durable 是一套平行的运行时,给需要崩溃恢复的场景用。
也就是说仓库里有两套"会话"实现。这个设计取舍留到 M10、M11 再算账,现在只需要记住:依赖图里缺席的箭头,往往比存在的箭头更能说明架构意图。
还有一条边值得记住:env 依赖 chord + durable。看它的包描述就明白了——
Remote execution environments for Pi Durable: a small daemon deployed over SSH and its ExecutionEnv client
env 不是"环境变量管理",是把 durable 的 agent 部署到远端机器上跑的客户端加守护进程。一条 SSH 连接,两端各跑一个 durable。所以它必然同时依赖 chord(它用 chord 的 link 做通信)和 durable(它要在远端跑的就是这个运行时)。
这种"包名看不出来、看描述才明白"的情况在 12 个包里出现了三次:env(不是环境变量)、chord(不是音乐或和弦,是协议)、schema(不是数据库 schema,是 JSON Schema 编译器)。
五、它刻意不做的四件事
判断一个框架的设计意图,看 README 承认不做什么,比看它标榜做什么更准。Pi 的 README 里明写了四处"不做"。
一,不做 sub-agent。 README 原话:
Pi ships with powerful defaults but skips features like sub-agents and plan mode.
子代理(一个 agent 派生另一个 agent 跑子任务)是很多 agent 框架的核心卖点。Pi 不做,让你"让 Pi 自己搭"或者装个包。理由不难猜:子代理一旦进内核,内核就要管调度、管预算、管结果合并——agent-loop.ts 会从 960 行涨到 3,000 行。
二,不做 plan mode。 同上。计划模式本质是"先生成一份计划再逐步执行",这属于工作流,不是循环语义。
三,不做权限系统。 README 有一整节 Permissions & Containerization:
Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.
这不是疏忽,是明确的选择。要边界就去容器化,README 给了三种模式(Gondolin 微VM / Docker / OpenShell)。内核里只有一个 beforeToolCall 钩子(agent-loop.ts:718),谁想加审批就在那挂。
四,没有 orchestrator。 多 agent 编排根本不在仓库里:packages/ 下 12 个包没有一个叫 orchestrator,v1.4.0 把它整个删掉了。要编排,自己写——下面那张表最后一行就是这条路。
四个"不做"指向同一个结论:凡是"策略"的东西全部外置,内核只保留"机制"。这是 agent 能停在 2,559 行的唯一原因。
而且每个"不做"都留了替代路径,不是关上门:
| 内核不做 | 你想要时怎么办 | 出口 |
|---|---|---|
| sub-agent | 扩展注册一个工具,工具内部用 SDK 再起一个 session | 扩展机制 + SDK |
| plan mode | 写成 prompt template,或用 slash command 触发 | prompt-templates.md / slash-commands.md |
| 权限系统 | 在 beforeToolCall 钩子上挂审批,或整进程容器化 |
钩子 + containerization.md |
| 多 agent 编排 | 自己写,或用 env 把 agent 部署到远端 |
应用层 |
这张表是本书反复出现的模式:内核对每个需求都给一个"你自己写"的出口,而不是一个开关。代价是你得写代码,好处是内核永远不膨胀。
六、五个入口,一套机制
packages/coding-agent/docs/how-pi-works.md 里有一句话,把整个仓库的骨架说完了:
All interfaces use the same agent and session mechanisms.
Pi 有五种用法,共用同一套内核:
| 入口 | 怎么用 | 输出形态 | 典型场景 |
|---|---|---|---|
| 交互模式 | pi |
终端界面 | 人坐在前面敲 |
| print 模式 | pi -p "..." |
最终回复纯文本 | shell 里 $(pi -p ...) |
| JSON 模式 | pi --json |
一行一个事件的 JSONL | 喂给别的程序解析 |
| RPC 模式 | stdin 收 JSONL 命令 | stdout 吐响应与事件 | 编辑器插件、IDE |
| SDK | import 一个类,进程内调用 |
JS 对象 | 自己写产品 |
五条路的字节流完全不同——ANSI 转义序列、纯文本、JSONL、管道、函数调用——但往下走两层就汇到一起:
交互 ─┐print ─┤JSON ─┼→ 事件订阅 → agent-loop → stream(model, context, options)RPC ─┤SDK ─┘ ↑ 七个 provider 在这里被抹平这就是"极简"的第二个含义:内核不知道有几个入口。它只做一件事——产出一串事件;谁消费、怎么渲染、要不要序列化成 JSON,它全不管。
反过来说,五种入口的代码一行都不在 agent 包里。它们全在 coding-agent(77,658 行)里。这解释了内外比为什么是 1 : 88:五个外壳就吃掉了一大半外围。
七、十行跑起一个 agent,然后拆开看
先跑通,再拆开。
@earendil-works/pi-coding-agent 提供 SDK,可以把整个 Pi 当成一个库装进你自己的进程:
import { createAgentSession } from "@earendil-works/pi-coding-agent";const { session } = await createAgentSession();try { await session.prompt("What files are in the current directory?"); console.log(session.getLastAssistantText());} finally { session.dispose();}十行。它用的是当前工作目录、已发现的资源、已保存的配置和已登录的凭据——所以运行前先 pi 一次把 /login 做完。
这段代码里没有任何循环。循环在里面。await session.prompt(...) 要等到整轮跑完才 resolve,中间可能经历了五次模型请求和十二次工具调用,你在外面看不见。
想把中间过程看清楚,就订阅事件(订阅必须在 prompt 之前):
session.subscribe((event) => { if (event.type === "turn_end") { console.log(`第 ${event.turnIndex} 轮结束,` + `工具调用 ${event.toolResults.length} 个`); }});这几行是本书的入口:所有后面要讲的机制,都是为了让你能预测这串事件长什么样。
现在把全链路摊开,后面每章负责其中一段。
你敲一行字 ↓① 变成 UserMessage,追加进 session 的一条 entry ↓ coding-agent/core/session-manager.ts② 装配 context: system prompt(基础指令 + 发现的上下文文件 + 工具说明 + skill 描述) + 当前活跃分支的历史 ↓ coding-agent/core/system-prompt.ts③ prepareRequest 钩子: 允许改模型、改思考等级、追加消息 ↓ agent/src/agent-loop.ts④ 发给 provider,流式回来 ↓ ai/src/providers/*.ts⑤ assistant 消息落进 transcript(text / thinking / toolCall) ↓ agent/src/agent-loop.ts⑥ 有 toolCall → 分派给 8 个内置工具 ↓ coding-agent/core/tools/*.ts⑦ toolResult 追加进 transcript ↓⑧ 还有工具或还有排队消息 → 回④,否则进⑨ ↓⑨ turn_end → agent_end九站。其中③⑤⑧在 agent 的 960 行里,④在 ai 的 28,581 行里,①②⑥在 coding-agent 里。
这九站和 M00 的十二节不是两套说法,是同一件事的两个切面。
M00 讲的是「一次进程的启动」:从 argv 进来到屏幕上出现第一个字,
正文十个站。这张图讲的是「一轮对话的生命周期」:从 UserMessage
进来到 turn_end,九站。两边对得上的只有中间一段:
| 这一段 | M00(进程视角,十站) | 本章(对话视角,九站) |
|---|---|---|
| 参数 → 判模式 → 装配 → 造 session | 第一–四站 | — |
| 系统提示、取那一句、进 TUI | 第五–六站 | ①② |
| 进 loop、拼 payload、流式回来 | 第七–九站 | ③④ |
| 字节变字、回到屏幕 | 第九–十站 | — |
| 工具调用与回填 | 第十一站(一句话带过) | ⑤–⑦ |
收尾(turn_end → agent_end) |
— | ⑧⑨ |
所以定位代码时用本章的表:它告诉你每一站在哪个文件。 判断一次启动到底做了什么时用 M00:它给你一条从头到尾不断的线。
这条链上有一处设计值得提前点出来:session.systemPrompt 是只读的,但它会变。SDK 文档原话是,它返回"当前生效的系统提示词,含尚未发给模型的变更"——也就是说提示词的变更是先声明、后生效,工具集的增删也是先告诉模型再换。这是全书反复出现的主线:变量只增不改,变更即追加。
到这儿你已经能把这一百来行代码对应到具体文件。但那是「看懂」。 下一节先解决「跑起来」——你不能改一个自己启动不了的东西。
八、把仓库跑起来
§七 那十行代码跑在别人装好的 npm 包上。你要改的是这份源码本身, 所以得先让它在你的机器上启动。
这是全书唯一一节不读代码的内容。但跳过它,后面每一章的「实验」都会停在 「你应该能看到」。
8.1 四步,每步一个判据
| # | 做什么 | 判据 | 本机实测 |
|---|---|---|---|
| 0 | node -v |
≥ v22.19.0 |
v24.12.0 |
| 1 | 数包 | 12 个包,version 全 1.4.0 |
12 个 |
| 2 | npm install |
出现指向 packages/* 的软链 |
13 条 |
| 3 | 直接跑 src |
打印 1.4.0 |
1.4.0 |
第 0 步的门槛不是随手定的。根 package.json:68-70 写着
"node": ">=22.19.0"。Node 从 22.x 起能直接执行 .ts:把类型剥掉,
当普通 JS 跑。Pi 就是靠这个做到「不 build 也能跑 src」。版本不够时
第 3 步会直接失败,你不必去怀疑自己改错了代码。
第 1 步有个副作用值得记住:packages/ 下我数到 12 个目录,
但 build 链上只有 11 个。evals 不在链上,它由 package.json:34
那条 npm run eval 单独调用。
第 2 步的判据不是「装完没报错」,而是「软链建没建」。npm 的 workspace
机制会在 node_modules/@earendil-works/ 下给每个包建一条符号链接,
指回 packages/ 里的源码目录。本机实测:
pi-ai -> packages\aipi-agent-core -> packages\agentpi-coding-agent -> packages\coding-agent软链一多,就说明 workspace 被正确识别、第三方依赖也落盘了。
8.2 那条长命令,三个词
node --import \ ./packages/coding-agent/src/experimental/source-resolver.ts \ packages/coding-agent/src/cli.ts --versionPowerShell 不认行尾反斜杠,写一行即可。仓库自己也是这么调的,
见 pi-test.ps1:61-64——它多了一步:把路径转成 file:// URL,
因为 --import 要的是模块说明符,不是 Windows 路径。
三个词:
--import:跑主文件之前先加载一个模块。只影响本次进程。source-resolver.ts:把@earendil-works/pi-ai这种包名改指到packages/ai/src/index.ts,靠的就是tsconfig.json里那张paths表(tsconfig.json共 67 行,@earendil-works/*占了大部分)。cli.ts:真正的入口。
不加 --import 会怎样?本机实测(路径省略了前缀):
Error [ERR_MODULE_NOT_FOUND]: Cannot find module'…\node_modules\@earendil-works\pi-ai\dist\index.js'imported from …\packages\coding-agent\src\main.ts注意路径里的 dist。node_modules/@earendil-works/pi-ai 是软链,
它 package.json 的 exports 指向 dist/index.js;没 build 过,
dist 不存在,于是报「找不到模块」。
source-resolver.ts:6-8 的注释把这件事说得很直白:
Node strips TypeScript natively, but it does not apply the workspace source aliases from tsconfig.json. Internal source processes preload this resolver so they cannot silently fall through to stale package dist files.
最后半句才是重点:silently fall through to stale package dist。
等你 build 过一次,dist/ 就有了;这时候忘了 --import,它不报错,
而是安静地跑上一次 build 的旧代码。你以为改了没生效,其实是
你改的那个文件根本没被加载。
8.3 改一行,看到变化
验证「跑的是源码」只有一个办法:改它。
打开 packages/coding-agent/src/main.ts:646-649,把第 647 行改成:
console.log(`${VERSION} (edited src)`);重跑 8.2 那条命令。本机实测输出:
1.4.0 (edited src)改回来再跑,输出回到 1.4.0。这一来一回证明三件事:跑的是 src、
改完立即生效、不用 build。这就是这个仓库日常开发的样子。
8.4 另外两条路:build 与 test
改 src 之外还有一条正式路,也是发布用的:
npm run buildpackage.json:15 把 11 个包串成一条 cd 链,顺序我照原样抄:
telemetry → schema → chord → tui → codemode → mcp → ai → durable →
env → agent → coding-agent。产物落在
packages/coding-agent/dist/bundle/cli.js,也正是
packages/coding-agent/package.json 里 bin.pi 指的那个文件。
build 过之后,pi 这个命令跑的就是它。
测试是 vitest(同一个 package.json 的 test 是 vitest --run):
npm test --workspace @earendil-works/pi-coding-agent这两条本机没跑成,原因不在代码:npm run build 要用
typescript / vitest / esbuild 的平台二进制,都在 devDependencies 里,
而这台机器装不上它们(下一小节有真实报错,见 8.5)。按本书的规矩,「没跑过」
就不写「应该会输出」。
8.5 装依赖:四个坑,本机全踩了
npm install 是这一节唯一的失败点。四次尝试的真实报错:
| # | 做法 | 报错 |
|---|---|---|
| 1 | 默认配置 | ENOTFOUND nexus.devops.csvw.com |
| 2 | 换 npmjs 官方源 | ECONNRESET(大包,重试 3 次耗尽) |
| 3 | 加长重试与超时 | ENOTEMPTY / EPERM(Windows 文件锁) |
| 4 | --omit=dev --ignore-scripts |
✅ added 130 packages in 7m |
四条对策,按顺序试:
- 先看一眼源。
npm config get registry。很多公司机器默认指向内网 Nexus,离开内网就ENOTFOUND。报错里出现公司域名时,加--registry=https://registry.npmjs.org。 ECONNRESET不是你的错。 几百 KB 的元数据能过、几十 MB 的 tarball 过不去。本机折在wrangler、workerd、vitest、@esbuild/win32-x64上。加大重试有用,但不保证。ENOTEMPTY是文件锁。 上一次失败的残留目录被 node 进程占着。 删掉node_modules重装;删不干净就关终端再开。- postinstall 里还套着
npm install。packages/coding-agent/examples/extensions/with-deps是带本地依赖的 workspace,esbuild也会再抓一次平台二进制。两条都会把 install 挂住—— 本机卡在node install.js上二十多分钟没有输出。--ignore-scripts跳过它们。
装完还差一步。 packages/ai/src/providers/data/ 是被 gitignore 的
生成产物,干净的 clone 里没有它。而 42 个 *.models.ts 每个都在顶层
import 一个 JSON(amazon-bedrock.models.ts:1-4):
// This file is auto-generated by scripts/generate-models.tsimport values from "./data/amazon-bedrock.json" with { type: "json" };缺了它,第 3 步报的不是「少个数据文件」,而是更前面一句
Cannot find module …/providers/data/amazon-bedrock.json。补法:
npm run generate:models它会去抓 models.dev 的模型目录(catalog/sources/index.ts:72-76)。
没有外网就跑不通,本机实测 Failed to fetch models.dev catalog。
退路是去掉 --strict 直接跑 node catalog/generate.ts:抓不到的源退化成
空,文件能生成,但模型列表是残的——够你跑 --version、够你读代码,
不够你真的跟模型对上一次话。
这条也顺带解释了 §六 那张「五个入口」表:不管从哪个入口进, 都要先把这堆 JSON 读进内存。没有它们,五个入口一个都开不了门。
到这儿,"是什么"和"跑不跑得起来"都交代过了。为什么同一件事(发请求、收结果) 会被切成十二个包、这一刀切在哪,§三 已经摊开算过一遍。剩下的问题只有一个: 这 34 章该按什么顺序读——§九。
九、这本书怎么读
34 章正文分六个部分,按"离内核的距离"排:前三部分读源码,中间两部分动手,最后一部分教你把 Pi 用起来。加上五篇附录,站上共 39 篇。
Part A · 全景(M00–M02) —— 「第一天」把一次启动从头走到尾,你这章给这份体量称重,下一章把它摊成三层架构图。目标:拿到一条能走的路 + 一张能定位任何代码的图。
Part B · 内核(M03–M07) —— agent 包的六个文件(agent-loop / agent / types / proxy / stream-fn / index)+ ai 的归一层 + coding-agent 的工具和消息。这五章是全书密度最高的部分,agent-loop.ts 那 960 行会被拆到不能再拆。
Part C · 上下文工程(M08–M10) —— 系统提示词怎么拼、超长对话怎么压、会话怎么存和恢复。这三章回答"模型凭什么知道得这么多"。
Part D · 盲区(M11–M15) —— durable、chord、mcp+codemode、tui、schema+telemetry。这五块网上的讲解最少,却占仓库 44% 的代码。
Part E · 造物(E01–E08,选修) —— 不读 Pi,自己写:从空目录开始,八章造出一个 1,252 行的零依赖 mini-agent,消息投影、真模型接口、工具写锁、压缩、会话、扩展钩子、命令行,每章一个能直接跑的入口。全程不 clone Pi、不配 API key;每章末尾有一节「与 Pi 的对照」,把刚写的东西指回对应源码。它不依赖前面任何一章也能开始,但读完 Part B 再做会快很多。
Part F · 应用(F01–F10) —— 前五部分都在讲"它是怎么做的",这一部分讲"你该怎么用它"。十篇全是使用视角:配置文件哪一层盖哪一层、模型与凭据怎么接、工具开关如何反过来改写系统提示词、四层指令怎么叠、扩展怎么落位和造工具、MCP 与 codemode 怎么接和写、包怎么打、五种接口怎么选、上线前该查什么。每篇都以源码行号为据,但不读源码也能照着做。它和 Part E 一样可以独立开始。
读法建议:
- 想改 Pi 的行为 → 读 Part B 的钩子章节(M03 第七节),别动内核
- 想接新 provider → 读 M04
- 想写扩展 → 读 M07
- 想知道为什么 Pi 卡住不恢复 → 读 M10、M11
- 想抄它的 UI → 读 M14
- 想把内核自己造一遍 → 读 Part E:E01–E08 零依赖零凭据,
node直接跑 - 只想把 Pi 用起来、不改它的代码 → 读 Part F:从 F01 顺着读到 F10,全程只改配置文件
每章结尾都有「自己动手验证」和「工程暗坑」,前者给能跑的命令,后者只写真踩过的坑。
书末还有四页附录。三页是卡住时的入口,一页是读完后的全景:
| 附录 | 什么时候翻 |
|---|---|
| B · TypeScript 速查 | 看到 satisfies、keyof、declare module 不知道什么意思 |
| A · v0.80 → v1.4 迁移对照 | 手上的资料写于 v0.80 时代,路径或结论对不上 |
| C · 把 Agent 装进你的服务 | 想把这个 Agent 接进自己的后端(HTTP + SSE) |
| D · 合龙:一次请求,二十五个落点 | 进 Part B 前先花 8 分钟扫一遍当地图;每个 Part 读完回来重扫,卡住哪站回哪章 |
正文里每遇到一次这类写法,首次出现处都留了回指。不用背,卡了再翻。 附录 D 反过来:它标的是每个结论出自哪一章,读不懂哪一站就回哪一章。
9.1 六个里程碑
书是按"闭环"分批写的:每一批结束时,该部分的每一章都能独立回答一个问题,且章与章之间的指针都对得上。比如 Part B 结束后,你应该能从"我敲了一行字"一直讲到"toolResult 写回 transcript",中间不需要跳出去查。
Part A 全景 → Part B 内核 → Part C 上下文工程 → Part D 盲区,四批正文之后是站点收尾(构建通过、0 失效引用)。Part E 是后来加的一批:八章自成一段,每章一个能跑的终点,不依赖 Pi 源码。Part F 是最后加的一批:十篇应用视角,把散落在 docs/ 里的配置项按"你要做什么"重新组织。
9.2 四种不同的读法
同一本书,四类人应该走不一样的路。
路径一:三小时速通(只想用)。 F01 → F02 → F03 → F04。四章,约三小时。目标:知道配置写在哪个文件、模型怎么接、工具和指令从哪来。这是最短的一条"能上手干活"的路。
路径二:一周读通(想改内核)。 按顺序读 Part A 和 Part B,七章。重点在 M03:那章把 960 行拆成了两层循环、十三条事件、七种 stopReason。读完你应该能预测任意一段对话的事件序列。
路径三:只查变动最大的三块。 M03 §六(三个开关的来历)+ M10 + M11。这三处是这两年改得最狠的地方,也是外部资料最容易讲错的地方。其余章节的差别属于"路径变了、结论没变"。
路径四:写扩展的人。 M07(事件的语义)→ F05(落位与拦截)→ F06(造工具)→ F07(用别人的工具)→ F08(打包分发)。前两章建立心智模型,后三章是照着做的步骤。
补一句:**不会 TypeScript 的话,先花十二分钟读附录 B。**它不在主线上,但缺了它,M03 的第一段代码就会卡住。
四条路有一个共同的起点:先搞清楚哪一块代码属于哪一层。这就是下一章。
十、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出;标
[需 key]的实验另给了无 key 变体。
实验 1:自己数一遍行数。
# 在仓库根目录执行for d in packages/*/; do n=$(find "$d" -path '*/src/*' -name '*.ts' ! -name '*.test.ts' | wc -l) l=$(find "$d" -path '*/src/*' -name '*.ts' ! -name '*.test.ts' \ -exec cat {} + 2>/dev/null | wc -l) echo "$(basename $d) $n $l"done | sort -k3 -rn# PowerShell 5.1Get-ChildItem packages/*/ -Directory | ForEach-Object { $f = Get-ChildItem $_.FullName -Recurse -Filter *.ts | Where-Object { $_.FullName -match '\\src\\' -and $_.Name -notmatch '\.test\.ts$' } [pscustomobject]@{ dir=$_.Name; n=$f.Count; l=($f | Get-Content | Measure-Object -Line).Lines }} | Sort-Object l -Descending如果数字和上表对不上,先检查两件事:有没有把 dist/ 算进去,有没有把 *.test.ts 算进去。这两个是行数统计最大的污染源。
实验 2:验证依赖图里缺席的那条边。
grep -r "pi-durable" packages/coding-agent/src --include=*.ts | headGet-ChildItem packages/coding-agent/src -Recurse -Filter *.ts | Select-String -Pattern 'pi-durable'应该一条都没有。再试试:
grep -r "pi-durable" packages/env/package.json packages/durable/package.jsonenv 依赖 durable,coding-agent 不依赖。这两个事实放在一起,才看得清"会话"在这个项目里被实现了几次。
实验 3:找到内核真正的入口。
wc -l packages/agent/src/*.tscat packages/agent/src/index.tsGet-ChildItem packages/agent/src/*.ts | ForEach-Object { "{0,5} {1}" -f (Get-Content $_).Count, $_.Name }Get-Content packages/agent/src/index.ts6 个文件,index.ts 5 行。然后读 packages/agent/package.json 的 dependencies——只有两个。一个包的可信边界,就是它的 dependencies 加它的导出。
实验 4:验证测试比源码多。
cd packages/agentwc -l src/*.ts | tail -1 # 源码wc -l test/*.ts | tail -1 # 测试cd packages/agent(Get-Content src/*.ts | Measure-Object -Line).Lines(Get-Content test/*.ts | Measure-Object -Line).Lines应该是 2,553 对 4,115。test/*.ts 这个 glob 不含 test/utils/ 下那 3 个辅助文件;把它们算进来(find test -name '*.ts' -exec cat {} + | wc -l)才是 4,206。单独看最大的那个:
wc -l src/agent-loop.ts test/agent-loop.test.ts 959 src/agent-loop.ts 2234 test/agent-loop.test.ts 3193 total# PS 的 Count 会少算末尾换行,与上面差 1,见 §十一 坑 2(Get-Content src/agent-loop.ts).Count(Get-Content test/agent-loop.test.ts).Count实验 5:跑一次 print 模式。 [需 key]
pi -p "列出当前目录的文件数量,只回答数字"pi --json -p "同样的问题" | head -3pi -p "列出当前目录的文件数量,只回答数字"(pi --json -p "同样的问题") | Select-Object -First 3第一条输出一句话,第二条输出三行 JSONL。同一个内核,两种外壳——这就是第五节那张表的最小验证。注意第一条要先把 /login 做完。
没 key 也能走一半: 不登 pi 直接跑,两条命令都会在发请求前停下,报 No API key found for provider …(正是附录 C 第一节引的那个错)。想不花钱把整条链路跑完,用 M03 §十二 那个假 streamFn——判据从"模型回什么"变成"事件顺序对不对"。
实验 6:找一下内核自带的示例。
ls packages/agent/examples/mcp-codemode/两个文件:main.ts 和 tools.ts。一个 1.1% 的内核包,示例却是"用 MCP 接工具 + 用 codemode 执行"——这两个能力都属于外围包。这反过来证明了一件事:内核只认工具接口,不关心工具从哪来。
十一、读这份仓库的六个坑
装依赖那四个坑不在本节,在 8.5——那是真跑起来才会撞上的,跟着命令查更顺。
1. README 和代码不同步,以代码为准。
7 包 vs 12 包只是最明显的一处。更细的:workspaces 里写着 apps/*,但仓库根本没有 apps/ 目录——那是留给下游示例或历史遗留的 glob。package.json:6-11 里还有三条指向 packages/coding-agent/examples/extensions/* 的 workspace,那些是扩展示例,不是产品包。
判断"哪些是产品包"的经验规则:看 packages/ 下有没有 package.json,且 private 不为 true。
2. wc -l 的口径不统一。
wc -l 数的是换行符数量。文件末尾没有换行时,会少算 1。PowerShell 的 (Get-Content x).Count 又不一样——它不数末尾空行。
实测:agent-loop.ts 用 PowerShell 数是 959,用 split('\n') 数是 960。全书统一用后者(和本书的校验口径一致)。差了这 1 行,行号引用就会在边界上翻车。
3. 别指望从 agent/src/index.ts 找到 harness。
流传的说法里,agent 包还导出 harness / session / compaction。v1.4.0 的 index.ts 只有 5 行,导出 agent、agent-loop、proxy、stream-fn、types——harness 早就搬到 durable/src/harness/ 了。
这是最容易栽的一处:按 agent/src/harness/** 去找文件必然扑空,而原因不是文件藏起来了,是这个包真的没有。跳进去之前先 ls packages/agent/src/,那 5 行导出就是全部。
4. evals 不在 build 里,但它在 packages/ 下。
跑 npm run build 不会构建 evals,跑 npm run check 也不会 typecheck 它。它是独立工具,只在 npm run eval 时被 workspace 脚本调用。别把它当成"第 13 个包"去找它的构建产物。
5. 包名会骗人,description 不会。
前面已经踩过三次:env 不是环境变量,是远程执行环境;chord 不是音乐,是插件协议宿主;schema 不是数据库,是 JSON Schema 编译器。判断一个包干什么,只有两处可信:description 和 src/ 里的文件名。README 的表格和目录名都可能滞后。
6. 行号会漂,漂的方式很隐蔽。
上游 main 分支持续演进,你在 GitHub 上点开的文件和本地快照未必是同一版。更阴的是"文件还在,内容已换"——比如 tools/read.ts 上一版还是 275 行,现在重写成 224 行,按 read.ts:275 去跳直接越界。
所以本书所有引用都基于 v1.4.0 这一版快照,而不是你此刻在 GitHub 上看到的最新 main。每次发布前,书里的每一条 文件:行号 还会被脚本扫一遍:文件是否存在、行号是否越界、是否命中已经搬走的旧路径。人眼会漏,脚本不会。
十二、三个可以带走的方法
方法一:用体量分布定位权重。
一个 22 万行的仓库,读什么取决于"哪里是重点"。体量分布就是权重图:coding-agent 占 33.9%,说明它是产品主体;agent 占 1.1%,说明它是稳定内核。
反过来说也成立:如果一个 1% 的包你读不懂,那你读 33% 的包只会更糊涂。先读内核,再读外围。
方法二:用 build 顺序反推隐式依赖。
dependencies 只记录显式的包依赖,构建脚本的顺序才暴露真实约束。这个仓库里 tui 在 coding-agent 前面,schema 在 chord 前面——这些都是"不写进 dependencies 也必须先构建"的隐式边。
读任何 monorepo,先看根 build 脚本的 cd 链,比看 12 个 package.json 快得多。
方法三:把"不做"当成设计文档。
README 承认的四件不做的事(sub-agent、plan mode、权限系统、orchestrator),拼起来正好是内核的边界。框架的能力上限由它做什么决定,它的可维护性由它不做什么决定。
Pi 全部四个"不做",都指向同一个动作:把策略推到钩子外面。
十三、本书的引用口径
§十一 的坑 6 提到了行号会漂。这一节把"怎么保证不漂"说清楚,因为它直接决定了你能不能用书里的坐标去源码里跳。
一,版本锁定。 全书基于 v1.4.0 这个发布版,不是你打开 GitHub 那一刻的 main。验证方式一行:
for p in packages/*/package.json; do node -p "require('./$p').version"done | sort -u# 不依赖 node,直接读 JSON 再去重Get-ChildItem packages/*/package.json | ForEach-Object { (Get-Content $_ -Raw | ConvertFrom-Json).version } | Sort-Object -Unique应该只输出一行 1.4.0。如果出现了第二个版本号,说明你手上的快照不是同一次发布。
二,行号口径。 统一用 split('\n').length,不用 wc -l,也不用 PowerShell 的 (Get-Content x).Count。三个工具数同一个文件会差 1–2 行,在边界行上就会误判。
三,引用写法。 正文里出现 packages/agent/src/agent-loop.ts:342-372 这种形式,意思是"这个文件第 342 到 372 行"。单行写成 :412。如果代码被改写省略,块内用 // … 标记,并在块首写上 文件:起-止行。
四,机器校验。 每次发布前,全书的 文件:行号 都被脚本扫一遍,报三类问题:文件不存在、行号越界、命中废弃路径(比如 packages/agent/src/harness/)。第三类最重要——它专治"文件还在但东西搬走了"。
现在你已经有了地图、有了坐标、有了验证手段。
本章小结
- 22 万行里真正的 agent 逻辑只占 1.1%,其余 78% 与模型无关。
- README 公示 7 个包,仓库里 12 个;差额只有依赖图看得全。
- build 顺序是手写清单,只保证"被依赖的先建",不能当依赖图。
- 四个"不做"拼起来就是内核边界:策略全推到钩子外面。
- 全书坐标锁在 v1.4.0,行号由脚本逐条扫,不靠人眼。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 体量分布 | 各包行数占比,就是阅读权重图 | §三 |
| 隐式依赖 | 不写进 dependencies、但构建顺序暴露的边 |
§四 |
| 内核边界 | 由"不做清单"描述出来的能力上限 | §五 |
| 入口 | 交互 / print / JSON / RPC / SDK,共用一套机制 | §六 |
| 引用口径 | 版本锁定 + 行号算法 + 脚本校验,三件齐全才算坐标 | §十三 |
练习
练习 1(读):§一 里同一次 clone,find 数出的文件数和仓库自报的
对不上,两个数都由脚本算出。差在哪?→ 先列出口径差的至少两种可能
(含不含测试 / 含不含 node_modules / 只算不算 src/),
再回 §一 核对作者用的是哪一种。
练习 2(改):把 §七 订阅回调里的 turn_end 换成 agent_end,
跑一遍同一句 prompt。预期:打印从"每轮一次"变成"每次运行一次";
回滚:把字符串改回 turn_end,不涉及任何仓库文件。
常见误区
- 你会以为 "minimal"指整个项目小;实际是 只有内核小, 外围 22 万行一行没少;证据 §一 的体量表。
- 你会以为 build 顺序就是拓扑序;实际是 它是手写清单,
漏了
evals、还混进读产物的隐式边;证据 §四。 - 你会以为 78% 的代码是冗余;实际是 它们在做和模型无关的事 (IO、权限、TUI、压缩);证据 §三 的分类表。
读完自检
三条,能不能不看稿说出来?说不出来的那条,回右边一格重读。
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| Pi 凭什么值得你花时间? | 三种动机对三个身份:能改成自己的 / 内核读得完 / 十行接进自己进程;只想用 CLI 的人不用读 | §零 |
| 22 万行里,真正的 agent 逻辑占多少? | 1.1%。其余 78% 在处理"和模型无关的事" | §三 |
| README 只公示 7 个包,仓库里有几个? | 12 个;差额只有靠依赖图才看得全 | §二 |
| build 顺序为什么不能当依赖图看? | 它是手写的顺序,只保证"被依赖的先建":漏掉 evals、混进 npm 不认的隐式边(读 tui 产物),也说不出几层。要判层得看 dependencies 算最长路径 |
§四 |
下一步
十二个包的体量和依赖都清楚了,但还不知道它们怎么分层——ai 和 agent 的边界画在哪?coding-agent 为什么不依赖 durable?chord 凭什么被 durable 依赖?
下一章把 12 个包摊开成一张三层架构图,每个箭头都带出处,并给出一个判据:给定一个文件路径,三步之内能说出它属于哪一层。
源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
package.json |
76 | workspaces :5-12、build 顺序 :15 |
README.md |
— | 定位声明、Packages 表、权限声明 |
packages/agent/package.json |
51 | 两个依赖 |
packages/agent/src/index.ts |
6 | 全部导出 |
packages/agent/src/agent-loop.ts |
960 | 内核体量 |
packages/agent/src/agent.ts |
624 | 有状态外壳体量 |
packages/agent/test/agent-loop.test.ts |
2,235 | 测试与源码的比例 |
packages/coding-agent/docs/how-pi-works.md |
— | 五个入口共用一套机制 |
packages/coding-agent/docs/sdk.md |
— | 十行 SDK 示例 |
pi-test.ps1 |
68 | 仓库自己的启动封装 :61-64 |
tsconfig.json |
67 | paths 表,source-resolver 的根据 |
packages/coding-agent/src/experimental/source-resolver.ts |
87 | 源码别名解析,关键注释 :6-8 |
packages/coding-agent/src/main.ts |
1,011 | --version 分支 :646-649 |
packages/coding-agent/package.json |
— | bin.pi / test |
packages/ai/src/providers/amazon-bedrock.models.ts |
15 | 生成产物,顶层 import JSON :1-4 |
packages/ai/catalog/sources/index.ts |
96 | 抄 models.dev :72-76 |