Documentation Drift

漂移记录文档说的,和代码做的,不一样的地方

收录标准(SKELETON §7):只收可双向举证的条目——文档侧与代码侧各给一个 path:line,两侧都由校验器核对。不收笔误、格式问题、以及显然无害的历史遗留。

条目 3上游文档 32945 行 / 97 个文件

这 3 条不是系统性扫描的结果,是写作 21 章过程中的顺手发现。一次针对 32945 行 markdown 的完整核对必然会找出更多。把本页当作「这类问题存在」的证据,不是「问题只有这些」的清单。

d1 · 严重度 中 · 见 ch03

README 的 Low-Level API 示例掩盖了 agentLoopContinue 会就地修改调用方数组

文档说
示例构造一个 context 对象,先后喂给 agentLoop() 和 agentLoopContinue(),未提两者对 messages 数组的处理不同
packages/agent/README.md:482
代码是
runAgentLoopContinue 浅拷贝 context,messages 仍是调用方那个数组的引用;循环全程 push 进去。runAgentLoop 则在 L104 新建数组,调用方数组不受影响。
packages/agent/src/agent-loop.ts:136
影响
照 README 示例写的低层调用方,其 context.messages 会在 agentLoopContinue 之后被追加了整轮消息,而 agentLoop 之后不会。同一个对象、两个入口、两种语义,且签名看不出来。Agent 类使用者不受影响(agent.ts:437 每次 slice 快照)。
d2 · 严重度 低 · 见 ch15

security.md 的 Security Policy 链接仍指向旧仓名 pi-mono

文档说
链接写死 earendil-works/pi-mono
packages/coding-agent/docs/security.md:57
代码是
仓库已更名为 earendil-works/pi;GitHub 对 pi-mono 返回 301 重定向到 pi(curl -I 实测)。仓库内多处 markdown 仍残留 pi-mono 链接。
README.md:2
影响
链接目前仍可达(靠 GitHub 的重定向)。风险在于重定向是 GitHub 的服务承诺而非仓库自身保证:若日后有人注册 earendil-works/pi-mono,这些链接会静默指向他人仓库。安全策略链接尤其不该依赖重定向。
d3 · 严重度 高 · 见 ch06

compaction 存在两份独立实现,文档只描述其中一份

文档说
文档的 Source files 一节只列 packages/coding-agent/src/core/compaction/*,读者会认为那是唯一实现
packages/coding-agent/docs/compaction.md:6
代码是
packages/agent 另有一份 harness/compaction/compaction.ts(848 行),并从 @earendil-works/pi-agent-core 的公开 API 导出 compact / prepareCompaction / shouldCompact / findCutPoint 等同名函数。两份文件 diff 达 880 行,导出函数名仅一处不同(completeSummarization vs completeSimpleWithRetries)。coding-agent CLI 用的是自己那份(core/compaction/index.ts),并不消费 agent 包的那份。
packages/agent/src/index.ts:75
影响
同一组函数名存在于两个已发布的 npm 包中,实现独立演进。按文档读源码的人看到的是 CLI 那份;用 @earendil-works/pi-agent-core 写代码的人调到的是另一份。文档没有任何地方提示这种分叉。这是 harness-v2 迁移期的中间态,但对库使用者是当下的事实。

上游后续(锚点之后)

锚点之后上游已经往前走了,本书没有换锚点。截至 v1.2.0(06a4669,2026-10-13,锚点之后 1333 个提交):harness-v2 这一系没有切成默认路径,而是被整体删除了。删除前夕(f29ea3d),锚点上那 22 个抛错方法里 17 个已有实现、4 个被删除、1 个仍是桩;随后 7fd478a(2026-10-01) 把 AgentHarness、v4 会话栈与 harness 版压缩、工具连同设计文档一起从 pi-agent-core 移除,随 v1.0.0 发布。上游指向的后继 pi-durable 是另起的实验性设计,coding-agent 不依赖它;默认 CLI 仍然走 new Agent。所以:书里的判定在锚点版本上依然成立,而第 08 章那个「空壳」执行器,上游没有把它做完接上,而是放弃了。逐条变化见 第 08 章追记 与 漂移记录 · 上游后续。

下面是追记的证据,分两种写法。锚点之后、删除之前的那段历史只给提交级链接:相关文件在 v1.2.0 上已不存在,行级引用无法再被核对,本书不保留未经核对的行号。v1.2.0 上的现状用 @后 标记的行级引用,由 tools/check-citations.mjs 的 GATE 1b 逐行核对;提交链接的哈希与日期由 GATE 1d 对照 data/stats.json 核对。

完整重锚需要逐行重核全书 159 处引用(按 path:line 去重),而第 07 / 08 / 19 章引用的文件大多已被删除——那等于写另一本书。锚定版本记录的恰好是一套上游造到一半、又放弃了的设计,本书选择保留它、只追记。刷新追记:同时改 tools/stats.sh 里的 UPSTREAM_TAG 与 UPSTREAM(40 位哈希),再跑 tools/build.sh;stats.sh 对追记叙述的每个前提都有 FATAL 判定,前提变了要先改判定和文字。

基于 earendil-works/pi @ ac4ac9e(2026-08-07 快照)。
本页由 tools/gen-aux.mjs 生成,数字来自 data/stats.json,未手写。