附录 A —— v0.80 → v1.4 迁移对照
这一篇为三类人写:
- 读过旧版教程(对应
^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 把这三件事拆开了:
运行时 → 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 校验脚本只查得到两类错
本书的校验脚本查三件事:
- 文件存不存在
- 行号越不越界
- 是否命中已知的废弃路径(如
packages/agent/src/harness/)
它查不出"行号没越界但指错了"。这是所有行号校验的固有局限——除非把每行内容也存下来做 diff,否则无法判断"第 412 行还是不是那个 if"。
所以本书的做法是:所有行号都对着 v1.4.0 快照重新读一遍,不抄任何二手资料。你如果发现某条引用对不上,大概率是你手上的快照不是 v1.4.0。
四、论断作废清单
比路径更麻烦的是"句子还在,但已经错了"。下面八条是旧教程里明确作废的论断。
4.1 "Pi 由五个包组成"
作废。现在十二个:
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 行:
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。
// 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 动态算出来的:
getCurrentTools([...context.messages, ...baseline])它接受的是消息数组,不是工具列表。工具集由历史上的 system 消息加减得出——某个扩展在某轮追加了一条"新增工具 X",从那以后 X 就一直在。
这个设计的后果是:工具集变化必须写成消息。不能只改内存里的数组,否则分叉、回放、持久化之后就不一致了。
4.6 "有 7 个内置工具"
作废,8 个:
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 这两个包可以多看一眼,因为它们的"被依赖数"异常高:
被 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 四段最容易被照抄错的代码
网上旧文章里这四段很常见。每一段都能"看起来对",但跑不起来或者没效果。
第一段:从内核包里找会话。
// 旧写法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 判工具。
// 旧写法(能跑,但已经不准确)if (message.stopReason === "toolUse") { // 执行工具}// 现在的写法const toolCalls = message.content.filter((c) => c.type === "toolCall");if (toolCalls.length > 0) { // 执行工具}旧写法不是"错误",是"不可靠"。toolUse 仍被四个 provider 发出,但并非所有 provider 都发。用它判断的后果是:某些 provider 下工具永远不执行,而这很难复现——换一家就正常了。
第三段:引 harness 下的文件。
// 旧路径(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。
// 这个包已经不存在了import { Orchestrator } from "@earendil-works/pi-orchestrator";多 agent 现在只能在应用层做:用 SDK 起多个 session,自己管调度。这也是 durable 的 scheduler.ts 为什么有 3,159 行的原因——调度能力被下放到了运行时,而不是编排包。
七、自查:一条命令验证你的记忆
不想信我,自己跑:
# 在仓库根目录执行# 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 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 的那几条就是你要改的地方:
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/ 上移一层 |