Pi Agent 源码级教程
APX

附录 A —— v0.80 → v1.4 迁移对照

3,307 字 · 含 86 行代码 · 约 16 分钟

这一篇为三类人写:

  • 读过旧版教程(对应 ^0.80.2),现在要看 v1.4.0
  • 读过别的分析文章,里面引的是老路径
  • 手上有一份自己写的扩展,升级后跑不起来

第一次读这本书,这一篇可以跳过。 它不进主线:正文按 v1.4.0 写清了路径, 不需要先知道"它以前是什么样"。碰到跑不起来的旧扩展,再回来看这份清单。

五分钟能读完的纠偏清单放在第一节,后面是逐条证据。

本篇怎么用:先读 §一 那八条清单,撞上具体报错再按 §二 / §三 查行号; 这一篇没有练习——它的判据是"旧扩展能重新跑起来"。


一、五分钟纠偏清单

如果你记得的是左边,现在应该是右边。八条,按踩坑概率排序。

# 你可能记得 v1.4.0 的事实
1 五个包 十二个包(README 只公示 7 个)
2 packages/agent/src/harness/ 是运行时 整个搬到了 packages/durable/src/harness/
3 有 packages/orchestrator/ 整包删除,仓库里没有这个名字
4 agent/src/index.ts 导出 harness / session / compaction 只有 5 行,导出 agent / agent-loop / proxy / stream-fn / types
5 7 个内置工具 8 个(漏了 powershell)
6 依赖 ^0.80.2 全部 1.4.0,且不用 ^
7 循环靠 stopReason 判断要不要继续 靠 content.filter(c => c.type === "toolCall");stopReason 只留 error / aborted / length
8 会话存在 agent/src/harness/session/ 存在 durable/src/storage/,同时 coding-agent 有另一套自己的

八条里前四条是"路径变了",后四条是"结论变了"。路径变了只需要改 grep,结论变了要重写认知——所以第八条最贵,它牵扯到 M03 第六节整章的论证。


二、路径对照:11 条搬迁记录

旧教程里所有 packages/agent/src/harness/** 下的引用,现在都要改。实测结果:

旧路径(v0.80) 新路径(v1.4.0) 行数
agent/src/harness/compaction/compaction.ts coding-agent/src/core/compaction/compaction.ts 1,105
agent/src/harness/compaction/branch-summarization.ts coding-agent/src/core/compaction/branch-summarization.ts 387
agent/src/harness/session/jsonl-storage.ts durable/src/storage/jsonl/storage.ts 908
agent/src/harness/session/memory-storage.ts durable/src/storage/memory.ts 893
agent/src/harness/types.ts durable/src/harness/types.ts 1,080
agent/src/harness/ 整个目录 durable/src/harness/(24 文件 / 11,332 行) —
coding-agent/src/core/config.ts coding-agent/src/config.ts 682

注意第一、二行的去向和第三、四行完全不同。

压缩相关的两个文件去了 coding-agent,存储相关的两个去了 durable。它们都是从同一个 harness/ 目录出发的,但搬去了两个地方。

这不是搬错了,是按"谁能用"重新切了一刀:

  • 压缩是"这个会话的上下文管理",只有 CLI 需要 → coding-agent
  • 存储是"持久化的底层能力",任何运行时都需要 → durable

同时 durable/src/harness/compaction.ts(501 行)也存在,它是另一套压缩——给 durable 自己的会话用的。两个 compaction.ts 不是同一个东西,这是迁移时最容易搞混的一处。

2.1 为什么会有两个 harness/

packages/agent/src/harness/ 不存在了,但 packages/durable/src/harness/ 存在,而且只有 24 个文件 11,332 行——比旧版小了很多。

旧版的 harness/ 同时管三件事:会话、压缩、运行时。v1.4.0 把这三件事拆开了:

text
运行时   → durable/src/harness/    (24 文件 11,332 行)压缩     → coding-agent/src/core/compaction/  (4 文件 1,664 行)         + durable/src/harness/compaction.ts  (501 行)会话     → durable/src/session/    (7 文件)         + coding-agent/src/core/session-manager.ts (2,029 行)

一个目录变成四个。 这是全书最重要的一次架构变动,M10 和 M11 分两章才能讲完。


三、行号对照:文件还在,内容已重写

这一类比路径失效更难发现。文件存在,grep 得到,工具不报错——但行号指向的内容已经不一样了。

实际校验出来的两条:

旧引用 文件现在多少行 旧行号
coding-agent/src/core/tools/read.ts:275 224 越界
coding-agent/src/core/tools/edit.ts:330 218 越界

两个工具都被重写过,行数比旧版少了。read.ts 从 275+ 降到 224,edit.ts 从 330+ 降到 218——行数变少意味着逻辑被压缩或搬到别处,旧行号全部作废。

还有一批是"文件在,行数变了但没越界"的,它们不会报错,只会静默指错地方:

文件 旧教程记的 实际
coding-agent/src/core/compaction/compaction.ts 984 1,105
coding-agent/src/core/compaction/branch-summarization.ts 330 387
durable/src/storage/jsonl/storage.ts 838 908
durable/src/storage/memory.ts 837 893
durable/src/harness/types.ts 1,012 1,080
durable/src/harness/scheduler.ts 2,999 3,159

六条全部偏小。规律很清楚:上游一直在加代码,行号只会往后漂。所以任何"三天前看到的行号"都值得重新确认。

3.1 校验脚本只查得到两类错

本书的校验脚本查三件事:

  1. 文件存不存在
  2. 行号越不越界
  3. 是否命中已知的废弃路径(如 packages/agent/src/harness/)

它查不出"行号没越界但指错了"。这是所有行号校验的固有局限——除非把每行内容也存下来做 diff,否则无法判断"第 412 行还是不是那个 if"。

所以本书的做法是:所有行号都对着 v1.4.0 快照重新读一遍,不抄任何二手资料。你如果发现某条引用对不上,大概率是你手上的快照不是 v1.4.0。


四、论断作废清单

比路径更麻烦的是"句子还在,但已经错了"。下面八条是旧教程里明确作废的论断。

4.1 "Pi 由五个包组成"

作废。现在十二个:

text
agent  ai  chord  codemode  coding-agent  durableenv  evals  mcp  schema  telemetry  tui

新增的七个是 chord codemode env evals mcp schema telemetry。删掉的是一个:orchestrator。

4.2 "运行时在 packages/agent 里"

作废。packages/agent 现在只有 6 个文件 2,559 行,是无状态内核。有状态的运行时在 packages/durable(97 文件 / 33,728 行)。

一句话分清:

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

4.3 "agent/src/index.ts 导出 harness"

作废。整个文件 5 行:

ts
export * from "./agent.ts";export * from "./agent-loop.ts";export * from "./proxy.ts";export { setDefaultStreamFn } from "./stream-fn.ts";export * from "./types.ts";

如果你写过 import { SessionManager } from "@earendil-works/pi-agent-core",现在这行会失败。

4.4 "循环靠 stopReason 决定要不要继续"

作废,而且这是最深的一条。

旧模型是:模型返回 stopReason: "toolUse" → 执行工具 → 再请求;stopReason: "stop" → 结束。循环本质上是读信号灯。

v1.4.0 的模型是:直接数 toolCall。

ts
// agent-loop.ts 内层循环的续命条件const toolCalls = message.content.filter((c) => c.type === "toolCall");

stopReason 的七个取值里,循环只关心三个:error / aborted(硬退出)、length(整批工具失败)。toolUse 仍然被四个 provider 发出来,但循环不看它——纯兼容性残留。

为什么改?因为"信号灯由谁点亮"不可靠。七家 provider 对"这轮有没有工具调用"的表达不一致,有的在 stopReason 里说,有的只在 content 里放。数 content 是唯一不需要 trust 任何 provider 的做法。

M03 §6.1 有完整的七值归属表。

4.5 "工具集在请求前算出来就固定了"

作废。工具集现在是从 transcript 动态算出来的:

ts
getCurrentTools([...context.messages, ...baseline])

它接受的是消息数组,不是工具列表。工具集由历史上的 system 消息加减得出——某个扩展在某轮追加了一条"新增工具 X",从那以后 X 就一直在。

这个设计的后果是:工具集变化必须写成消息。不能只改内存里的数组,否则分叉、回放、持久化之后就不一致了。

4.6 "有 7 个内置工具"

作废,8 个:

text
bash  powershell  read  write  edit  find  grep  ls

漏的是 powershell。它不是 bash 的别名——coding-agent/src/core/tools/powershell.ts 独立实现,走 powershell -Command 而不是 bash -c。

4.7 "依赖版本 ^0.80.2"

作废,两个层面都变了:

  • 版本号:全部 1.4.0
  • 写法:没有 ^,全部写死

写死的好处是 monorepo 内部永远一致;代价是任何包升版都得全体一起升(npm version --workspaces)。

4.8 "有一个 orchestrator 负责多 agent 编排"

作废。packages/orchestrator 和 @earendil-works/pi-orchestrator 都不存在了。

多 agent 编排现在没有内建支持——你要么自己写(用 SDK 起多个 session),要么用 env 把 agent 部署到远端各自跑。


五、旧版根本没有的东西

有八个概念在 v0.80 里不存在,现在是一等公民。如果你在读旧教程时觉得"这里少了点什么",多半少的就是下面某一条。

新东西 在哪 解决什么
steering agent-loop.ts 运行中插话,不必等这一轮跑完
follow-up agent-loop.ts 跑完后自动追补一次,不用人再敲
finishTurn 返回 continue agent-loop.ts 扩展可以让一轮"不结束",兑现成 context-only turn
AgentRequestUpdate(Omit 掉 messages) types.ts 类型层面禁止 prepareRequest 注入消息
chord 独立包 插件热重载 + 复制状态 + JSON link RPC
codemode 独立包 沙箱执行模型写的脚本
env 独立包 把 durable 部署到远端机器
telemetry 独立包 厂商中立遥测

前四个是循环语义的变化,后四个是能力的扩张。

前四个里最值得注意是第三个:finishTurn 返回 { action: "continue" }。它意味着"这一轮结束了,但别把这次 run 结束"——循环会再跑一次 context-only turn,拿模型的下一句话。

这一个返回值,就是"三条出路"里的第三条。旧版只有一条出路:没有工具调用了就结束。

5.1 十二个包,各自从哪来

迁移时最容易搞错的是"这个包到底是不是新的"。逐个交代,只写能验证的部分:

包 旧教程提过吗 本章能确认的事实
agent 提过 从"含运行时"缩成无状态内核,只剩 6 文件 2,559 行
ai 提过 仍然只依赖 schema + telemetry
coding-agent 提过 77,658 行,接下了压缩与会话
chord 未提 50,101 行,全仓库第二大
durable 未提 33,728 行,旧 harness/ 的主要落点
schema 未提 43 文件 4,608 行,被 4 个包依赖
telemetry 未提 8 文件 1,580 行,被 3 个包依赖
tui 未提 46 文件 19,971 行
mcp 未提 18 文件 3,305 行
codemode 未提 17 文件 3,054 行
env 未提 8 文件 2,398 行,依赖 chord + durable
evals 未提 5 文件 1,452 行,不进 build
orchestrator 提过 已删除

一句话概括:旧教程 ch02 里出现过的包路径只有四个——ai、agent、coding-agent、orchestrator。 前三个还在,第四个删了,另外九个从头到尾没提过。

那九个包合起来占 76% 的代码。这就是本书 Part D 存在的理由。

schema 和 telemetry 这两个包可以多看一眼,因为它们的"被依赖数"异常高:

text
被 4 个包依赖:schema      (chord, ai, durable, agent)被 3 个包依赖:telemetry   (chord, ai, durable)被 2 个包依赖:chord       (durable, env)被 2 个包依赖:ai          (durable, agent)

两个包只有 4,608 和 1,580 行,却是全图的分叉点。被多个包同时需要的东西必须成为独立包 —— 否则要么复制多份(会漂),要么互相直接依赖(违反分层)。

这也是判断"下一个应该抽什么出来"的现成标准:看谁被反复依赖。


六、没变的东西

纠偏不是把一切都推翻。下面这些在 v0.80 和 v1.4.0 里逻辑一致,读到旧教程的相应段落可以直接用。

不变的部分 说明
双层循环的骨架 内层转"模型↔工具",外层管续命。骨架没动
Message / AssistantMessage / ToolResultMessage 的字段 ai/src/types.ts 里的形状基本一致
13 种流式事件 start / text_delta / toolcall_end / done… 类型名没改
provider 归一化的思路 一个 stream(),抹平各家差异
terminate 语义 工具可以要求"这批之后别再调模型"
上下文压缩的触发条件 超阈值 → 摘要 → 替换老消息
JSONL 会话格式 一条 entry 一行,parent 指向上一条
扩展的注册方式 工厂函数里注册 tools / commands / handlers

这八条"不变"比"变了"更重要:它们说明 v0.80 → v1.4 不是重写,是重新分配——把原来挤在 agent 里的东西分给 durable、coding-agent 和四个新包。

读懂一次架构重分配,比读十次 API 变更有用。

6.1 四段最容易被照抄错的代码

网上旧文章里这四段很常见。每一段都能"看起来对",但跑不起来或者没效果。

第一段:从内核包里找会话。

ts
// 旧写法import { SessionManager } from "@earendil-works/pi-agent-core";// 现在的两个选择import { createAgentSession } from "@earendil-works/pi-coding-agent";import { SessionManager } from "@earendil-works/pi-durable";

两个选择不是等价物。前者是产品级会话(JSONL、能回滚、人能看懂);后者是运行时级会话(事务、可续跑)。选错不报错,但要到崩溃恢复时才发现。

第二段:用 stopReason 判工具。

ts
// 旧写法(能跑,但已经不准确)if (message.stopReason === "toolUse") {	// 执行工具}// 现在的写法const toolCalls = message.content.filter((c) => c.type === "toolCall");if (toolCalls.length > 0) {	// 执行工具}

旧写法不是"错误",是"不可靠"。toolUse 仍被四个 provider 发出,但并非所有 provider 都发。用它判断的后果是:某些 provider 下工具永远不执行,而这很难复现——换一家就正常了。

第三段:引 harness 下的文件。

ts
// 旧路径(0 命中)import { x } from "../agent/src/harness/session/jsonl-storage.ts";// 新路径import { x } from "../durable/src/storage/jsonl/storage.ts";

注意文件名从 jsonl-storage.ts 改成了 storage.ts。grep jsonl-storage 会返回 0,grep jsonl/storage 才对。

第四段:找 orchestrator 做多 agent。

ts
// 这个包已经不存在了import { Orchestrator } from "@earendil-works/pi-orchestrator";

多 agent 现在只能在应用层做:用 SDK 起多个 session,自己管调度。这也是 durable 的 scheduler.ts 为什么有 3,159 行的原因——调度能力被下放到了运行时,而不是编排包。


七、自查:一条命令验证你的记忆

不想信我,自己跑:

bash
# 在仓库根目录执行# 1. 包数量(应该 12,不是 5)ls packages | wc -l# 2. orchestrator 不存在(应该 0)ls packages | grep -c orchestrator# 3. 版本号(应该只有一行 1.4.0)for p in packages/*/package.json; do  node -p "require('./$p').version"done | sort -u# 4. 旧的 harness 路径不存在(应该 0)ls packages/agent/src/ | grep -c harness# 5. 新的 harness 在 durable(应该 24)ls packages/durable/src/harness/*.ts | wc -l# 6. index.ts 只有 5 行(应该 5)wc -l < packages/agent/src/index.ts# 7. 八个工具(应该 8)ls packages/coding-agent/src/core/tools/*.ts | \  grep -cE '/(bash|powershell|read|write|edit|find|grep|ls)\.ts'
powershell
# PowerShell 5.1,同样七条(Get-ChildItem packages -Directory).Count                                  # 12(Get-ChildItem packages -Directory |  Where-Object Name -match 'orchestrator').Count                           # 0Get-ChildItem packages/*/package.json |  ForEach-Object { (Get-Content $_ -Raw | ConvertFrom-Json).version } |  Sort-Object -Unique                                                     # 1.4.0(Get-ChildItem packages/agent/src -Filter *harness*).Count                 # 0(Get-ChildItem packages/durable/src/harness/*.ts).Count                    # 24(Get-Content packages/agent/src/index.ts).Count                            # 5$t = '^(bash|powershell|read|write|edit|find|grep|ls)\.ts$'(Get-ChildItem packages/coding-agent/src/core/tools/*.ts |  Where-Object Name -match $t).Count                                       # 8

七条全部对上的话,你手上的快照就是本书用的这一份。

如果第 4 条和第 5 条同时满足,说明你理解对了一件事:harness 没消失,它搬了家,而且变小了。


八、四个可以带走的方法

方法一:迁移时先分"路径变了"和"结论变了"。

路径变了,grep 就能修;结论变了,要重读代码。混在一起处理,会以为改完 import 就完事了——第八条(stopReason 退役)这种,改完 import 依然是错的。

判断法:一句话里如果出现"因为…所以…",它就是结论;只出现"文件在哪",它就是路径。

方法二:看到"行数变少"就当重写处理。

read.ts 275 → 224,edit.ts 330 → 218。行数减少意味着逻辑被压缩、内联或搬走,旧行号 100% 失效。行数变多反而安全些(新代码在后面追加),变少要格外小心。

方法三:用"目录搬家"读架构。

agent/src/harness/ 一个目录变成四个新位置,搬法本身就是架构说明书。东西搬去哪,说明谁需要它。 压缩搬去 coding-agent,因为只有 CLI 要上下文管理;存储搬去 durable,因为任何运行时都要落盘。

想知道一个模块的定位,别看它的文档,看它从哪搬到了哪。

方法四(额外):用 grep 的"0 命中"当体检。

升级完别人的代码库,不要只看 git diff。 先跑五条 grep -c,命中数为 0 的那几条就是你要改的地方:

bash
grep -rc "stopReason === \"toolUse\"" src | grep -v ':0'grep -rc "agent/src/harness" src | grep -v ':0'grep -rc "orchestrator" src | grep -v ':0'grep -rc "pi-agent-core\".*SessionManager" src | grep -v ':0'grep -rc "tools/read.ts:[0-9]\{3\}" docs | grep -v ':0'

前四条对代码,最后一条对文档。升级之后的"编译通过"不代表"行为正确"——只有把旧符号搜干净,才能确定没漏。


源码索引

文件 行数 本章用到的位置
packages/agent/src/index.ts 6 全部导出
packages/agent/src/agent-loop.ts 960 内层循环续命条件
packages/agent/src/types.ts 552 AgentRequestUpdate
packages/durable/src/harness/types.ts 1,080 旧 types.ts 的落点
packages/durable/src/harness/scheduler.ts 3,159 旧 2,999 行已过期
packages/durable/src/harness/compaction.ts 501 与 coding-agent 那套不同
packages/durable/src/storage/jsonl/storage.ts 908 旧 jsonl-storage.ts
packages/durable/src/storage/memory.ts 893 旧 memory-storage.ts
packages/coding-agent/src/core/compaction/compaction.ts 1,105 旧 984 行已过期
packages/coding-agent/src/core/session-manager.ts 2,029 另一套会话实现
packages/coding-agent/src/core/tools/read.ts 224 旧行号 275 越界
packages/coding-agent/src/core/tools/edit.ts 218 旧行号 330 越界
packages/coding-agent/src/config.ts 682 从 core/ 上移一层