版本基线与上游差异

先看结论：本书逐行讲解与所有源码引用统一锁定在 Pi v0.87.0、commit 16787ad（2026-09-21 发布）。截至 2026-09-23，这就是上游最新的发布版本。本书上一版锁定在 v0.83.0（c13ffe1）；如果你读过旧版，下面「从 v0.83.0 到 v0.87.0 变了什么」一节列出了影响本书结论的变化。

两个版本各自负责什么

层次	版本	用途
本书源码基线	v0.87.0 · 16787ad	逐行引用、行号、实验对照与自动校验都以它为准
上游最新发布	v0.87.0（核对于 2026-09-23）	帮你判断后来发生了什么；上游再发新版后，它会领先于本书基线

全站正文顶部都会显示这两个层次。看到 GitHub 上的 main 与书中行号不同，先不要把它判断成书中错误；请先打开 从 v0.87.0 到 main 的比较页，确认差异来自上游演进还是本书表述。

为什么不直接追着 main 写

源码书最怕“今天能点、明天行号全漂”。锁定 commit 可以让以下三件事同时成立：

1. 文中的文件、符号与行号能由 npm run verify:sources 重复验证；
2. 读者运行配套实验时，看到的行为能与书中解释对上；
3. 上游继续开发时，旧结论仍有一个明确、可追溯的适用范围。

代价是本书不会自动覆盖每个新功能。页面写“Pi 的做法”时，默认含义都是“本书锁定版本中 Pi 的做法”；若讨论其他版本，会显式写出版本号与核对日期。

从 v0.83.0 到 v0.87.0 变了什么

两个版本之间有 1286 个提交，下面只列改变了本书结论的部分。它们都已写进对应章节的正文，这里是一份索引，方便读过旧版的人定位。

系统提示词与工具进了对话记录

• pi-ai 新增第四种消息角色 system。系统提示词和工具声明现在是对话记录里的系统消息，可以在对话中途变化；Provider 收到的是只含 messages 的 TranscriptContext，需要用 getCurrentSystemPrompt() / getCurrentTools() 读取。→ 3.2、5.2、6.1、7.4
• ToolCall.arguments 与工具结果的 details 限定为 JSON 兼容值；StopReason 新增 deferred，共 7 种。→ 2.3、3.4

Agent Loop 的钩子重新设计

• 新增 prepareRequest（每次请求模型前）、finishTurn（一轮定稿后决定结束或续跑）；prepareNextTurn 只在确定开新一轮时运行。0.84 引入的 shouldStopAfterTurn 在 0.87 已被 finishTurn 取代。被 beforeToolCall 拦截的调用也能参与整批提前终止。→ 3.5、5.3、6.3

会话：SessionManager 成为上下文的唯一权威

• coding-agent 每次请求前都用 SessionManager 的会话投影替换上下文，直接改 agent.state.messages 不再影响后续请求。
• 会话条目从 9 种变为 11 种，新增 usage 与 context_edit；重试不再删除失败的消息，而是追加一条 context_edit 把它从后续上下文中省略。压缩支持「不保留尾部」（retain-none）。→ 5.5、5.6、6.6
• pi-agent-core 的通用 harness 换成按 lane 组织的 Storage / Session / SessionRepo 三层，旧的 JSONL/内存存储被删除，SQLite 后端移到 packages/session-backends/sqlite-node；AgentHarness 变成独立的持久化运行时。→ 3.6、6.5

工具、扩展与 Skill

• 内置工具从 7 个变为 8 个（新增 Windows 可选的 powershell），启动时的工具集可由 defaultTools 设置决定。→ 6.4
• 扩展事件新增 context_with_system、agent_before_settle 等，turn_end 可以追加条目、要求续跑；pi.on() 返回取消订阅函数。→ 7.1、7.3
• Skill 注入的门槛从「必须启用 read」放宽为「read 或 bash 任一」。→ 7.2

包与入口

• 仓库从 7 个包扩到 12 个（新增 chord、client、durable、protocol、telemetry、session-backends/sqlite-node）；pi 命令改为加载打包后的运行时。→ 4.3、5.1
• JSON / RPC 模式的 message_update 只发增量；终端界面的全屏模式成为正式功能。→ 5.4、6.9、6.10

完整的上游变更见各包的 CHANGELOG.md，或 v0.83.0 到 v0.87.0 的比较页。旧版本书对应的源码树仍可在 c13ffe1 查看。

推荐阅读方式

• 第一次学习 Pi 逻辑：始终按锁定版本阅读和实验，不要在中途切换到 main。
• 准备开发 Pi 或插件：先用本书建立调用链，再在你实际安装的版本中全文搜索同名符号，并阅读从 16787ad 到目标版本的 diff。
• 准备给 Pi 本体贡献代码：以当前上游的 CONTRIBUTING.md、测试与类型定义为最终准绳；本书负责解释架构，不替代当前仓库规范。

升级本书基线时要做什么

升级不是改一个版本号。维护者需要：

1. 更新 source-lock.json 的 commit、日期、包版本与上游核对信息；
2. 把 _sources/pi 检出到新 commit，先用脚本自动平移未改动代码的行号，再运行 npm run verify:sources 处理剩下的引用；
3. 逐章复核所有行为性结论，尤其是 Agent Loop、工具、Session、Compaction 与 Extension；
4. 重新运行 npm run check、全部 labs 与各章实践任务，替换真实采集的输出；
5. 更新本页的基线、上游版本与差异摘要。

仓库命名、锁定文件结构与引用校验机制详见仓库、版本与历史。