pi coding-agent CHANGELOG 精读：版本规范、演进脉络与自动化消费链

packages/coding-agent/CHANGELOG.md 是 pi 项目（AI agent toolkit：统一 LLM API、agent 循环、TUI 与编码代理 CLI）中 coding-agent 包的完整变更记录，自 0.10.0（2025-11-25）首次公开发布起逐版本累积至今约 5630 行、180 多个版本条目。本篇围绕这份文档的结构规范与书写约定展开，并结合仓库中的解析工具与发布脚本，讲清它"被谁写、被谁读、被谁消费"：读完后你既能快速掌握 coding-agent 从 0.10 到 0.84 的演进脉络，也能复用仓库内置的解析逻辑在 TUI、SDK 或 CI 中以程序化方式消费这份变更记录。

一、文档定位：包级变更记录，而非项目级公告

该文件只覆盖 packages/coding-agent 一个包。仓库中 packages/ai、packages/tui、packages/client、packages/protocol 等 workspace 包各自维护独立的 CHANGELOG.md，因此 coding-agent 条目中大量出现 "inherited"（继承）措辞——从条目原文可以确认，这些变更来自上游 pi-ai 包（例如 0.78.1 中 "Added MiniMax-M3 model support inherited from @earendil-works/pi-ai"），随依赖升级一并进入 coding-agent 的行为。

文档遵循 Keep a Changelog 风格的骨架，每条记录由以下要素构成：

• 版本头：## [x.y.z] - YYYY-MM-DD，如 ## [0.84.4] - 2026-08-28；文件最顶部固定保留一个 ## [Unreleased] 段落，用于暂存尚未发布版本的改动（当前 Unreleased 段记录了两处修复：write 工具误报 UTF-16 码元计数为字节数，以及工具调用后普通 HTTP 代理请求挂起的问题）。
• 固定小节顺序：New Features / Breaking Changes / Added / Changed / Fixed / Removed，不同版本按实际需要取舍。其中 Breaking Changes 是独立小节，对 0.x 版本的破坏性变更做显式声明，而不是隐含在版本号里。
• 日期即事实：每个版本头都带发布日期，从 0.10.0 的 2025-11-25 到 0.84.4 的 2026-08-28，时间线连续可核对。

二、条目书写规范：四类值得注意的约定

2.1 New Features：粗体亮点 + 文档跳转

New Features 小节只收录用户可感知的新能力，格式统一为"特性名 — 一句话说明。See 章节名"。例如 0.84.4 的条目：

• Terminal capability overrides — Override detected terminal hyperlink, image, and truecolor support. See Capability Overrides.
• RPC queue clearing — Retrieve and clear queued steering and follow-up messages with clear_queue. See RPC clear_queue.

这里的相对链接以 packages/coding-agent/ 为基准解析，对应仓库路径为 terminal-setup.md 与 rpc.md。条目中还大量指向 extensions.md、providers.md、settings.md、keybindings.md、compaction.md、windows.md、environment-variables.md 等文档，以及跨包引用如 tui/README.md、ai/README.md、client/README.md、protocol/README.md，形成"变更记录 → 功能文档"的索引网络。

2.2 问题编号与贡献者署名

细粒度条目以 issue/PR 编号引用上游讨论，例如 0.84.4 中 "Fixed compaction and branch summaries forcing toolChoice: "none" (#8649, #8638)"，社区贡献的条目还会附上作者，如 "#8355 by @cristinaponcela"、"#8275 by @bnsd55"。这使每条变更都可以回溯到对应的讨论与实现上下文。

2.3 Breaking Changes：附带迁移前后代码示例

破坏性变更不仅列条目，还在版本头下直接给出 Before/After 代码。以 0.84.0 的会话 API v4 迁移为例，条目说明将 pi-agent-core 的 harness 会话模型替换为基于 lane 的 Session、SessionStorage、SessionRepo API，并区分了两种注册方式：

• 通过 createProvider({ fetchModels }) 构建的 provider 无需迁移——createProvider() 自身负责恢复、持久化与内存发布，Before 与 After 代码完全一致；
• 手写原生 Provider.refreshModels() 的 provider 需要把直接的 store 读写替换为带代际校验的 context.publish() 事务：读用只读的 context.stored 快照，写通过 publish({ persist, update }) 提交，persist: null 表示删除存储项。

0.80.8 的 "Unified model runtime and provider authentication" 同样是典型示例：SDK 的 CreateAgentSessionOptions.authStorage / modelRegistry 选项被异步 modelRuntime 取代，ModelRegistry.getApiKeyAndHeaders() 被 ModelRuntime.getAuth() 替代，且 refresh() 从同步变为必须 await 的 Promise<void>。阅读这份文档升级版本时，Breaking Changes 小节是必读部分。

2.4 版本号即语义

0.x 阶段 minor 位递增（0.78 → 0.79 → 0.80 → 0.84）中同样会出现破坏性变更（0.80.8、0.83.0、0.84.0 均有 Breaking Changes 小节），文档以显式小节而非语义化版本隐含规则来传递这一信息，这是使用 0.x 版本时的关键前提。

三、版本演进时间线（精选）

版本	日期	里程碑
0.10.0	2025-11-25	首次公开发布：交互式 TUI、read/write/edit/bash/glob/grep/think 工具、会话管理（--continue/--resume/--session）、Anthropic/OpenAI/Google 提供商、models.json 自定义模型
0.79.0	2026-06-08	项目信任机制：加载项目本地设置/资源/指令前询问，project_trust 扩展事件，--approve/--no-approve 非交互控制
0.80.8	2026-07-16	ModelRuntime 统一模型配置、provider 级 /login 与动态目录（破坏性变更）；pi update --models 强制刷新目录
0.81.0	2026-07-21	llama.cpp 本地模型管理（/llama 搜索下载 HF 模型）、扩展可注册完整 pi-ai provider、工具/压缩/分支摘要用量计入会话统计
0.82.0	2026-07-24	约束工具采样（strict JSON Schema / OpenAI Lark/regex 语法）、OpenRouter 与 Kimi Code 订阅登录、bash 工具注入 PI_SESSION_ID 等会话环境变量
0.84.0	2026-08-06	全屏 TUI 模式（运行时切换、独立滚动、可拖滚动条）、Mermaid/LaTeX 渲染、AGENTS.override.md 目录级上下文覆盖；同时落地 v4 会话 API 等破坏性变更
0.84.3	2026-08-24	Windows PowerShell 工具、安装器管理式安全更新（暂存-校验-原子激活）、/thinking 选择器与 Ctrl+S 持久化
0.84.4	2026-08-28	当前最新版：终端能力覆盖（超链接/图片/truecolor）、扩展 UI 提示事件（ui_prompt_start/ui_prompt_end）、RPC clear_queue、全屏选择复制控制

四、程序化解析：changelog.ts 如何读懂这份文档

这份文档不是纯人读资产，仓库内置了完整的解析与消费链。

4.1 解析器：parseChangelog / getNewEntries

utils/changelog.ts 定义了核心数据结构与算法：

export interface ChangelogEntry {
	major: number;
	minor: number;
	patch: number;
	content: string;
}

parseChangelog(changelogPath) 逐行扫描文件，以 ## 开头的行作为版本边界，用正则 ##\s+\[?(\d+)\.(\d+)\.(\d+)\]? 提取版本号，把版本头到下一个版本头之间的所有行收集为 content；无法解析版本号的 ## 行会重置状态。由此得到按文件顺序（新到旧）排列的条目数组。配套的 compareVersions() 按 major/minor/patch 逐位比较，getNewEntries(entries, lastVersion) 返回所有高于给定版本的条目——这正是"启动时只展示新内容"的过滤基础。文件路径由 config.ts 中的 getChangelogPath() 解析为包目录下的 CHANGELOG.md。

4.2 交互模式中的两处消费点

从源码结构看，interactive-mode.ts 中 TUI 启动时会调用 getChangelogPath() + parseChangelog()，以记录的 lastVersion 为界取出新条目，对每条内容执行链接规范化后拼接展示；文件另一处（约 L6236-L6243）同样解析全量条目用于查看完整版本记录的命令。两条路径都先经过 normalizeChangelogLinks，保证展示的链接指向对应版本标签的源码快照。

4.3 链接规范化：normalizeChangelogLinks

CHANGELOG.md 内部链接是包相对路径（如 [Extensions](https://gitcode.com/GitHub_Trending/pi/pi/blob/e266507b606b9552fa277252644054afd4384b11/packages/coding-agent/docs/extensions.md?utm_source=gitcode_repo_files#project_trust)），直接放给包外读者会失效。changelog.ts 的规范化逻辑：

1. 仓库更名归一：用正则把遗留仓库名（badlogic/pi-mono 与 earendil-works/pi-mono）统一改写为当前仓库 earendil-works/pi——这也解释了为什么 0.80.x 之前的条目原始链接还指向 pi-mono，而消费端看到的都是归一化地址；
2. 浮动引用钉死标签：blob/main/ 或 tree/main/ 前缀改写为 blob/vX.Y.Z/，确保链接指向该版本发布时的源码状态；
3. 相对路径 → 仓库绝对路径：以 packages/coding-agent 为基准拼接并归一化（Windows 反斜杠统一转正斜杠），目录型目标用 tree 路由、文件型用 blob 路由，保留 query 与 fragment；
4. 外部 URL 与纯锚点原样保留：以 #、// 或 URL scheme 开头的目标不做处理。

测试用例 验证了两类行为：包相对链接 README.md#project-trust、docs/extensions.md#project_trust、examples/extensions/ 以及根目录 ../../README.md#supply-chain-hardening 全部被改写为钉住 v0.79.0 标签的 blob/tree 链接；遗留 pi-mono 链接被归一化，而外部链接和本地锚点保持不变。

五、发布流水线：这份文档如何被维护

CHANGELOG.md 的更新是仓库发布流程的固定环节，核心脚本为 scripts/release.mjs。文件头注释列出了完整步骤：

1. 检查工作区无未提交改动；
2. 校验每个公开 workspace 包均已注册到 npm（npm view <name> version 探测，E404 视为未注册并报错）；
3. 通过 npm run version:xxx 升版本或指定显式版本号；
4. 更新各 CHANGELOG.md：把 [Unreleased] 段落改写为 [version] - date——这正是文档中"Unreleased 段在每次发布后消失并重新出现"的机制；
5. 重新生成发布产物；
6. 运行检查与测试；
7. 提交并打 tag；
8. 重新向 changelogs 添加空的 [Unreleased] 段落；
9. 提交下一周期的 changelog 更新；
10. 推送 main 与 tag，触发 CI 发布与 pi.dev 公告。

多包发布由 scripts/release-packages.mjs 与 scripts/local-release.mjs 支撑。发布说明的生成则交给 scripts/release-notes.mjs：其 extract 子命令 "Extract release notes from the coding-agent changelog"，通过 extractChangelogSection 按版本头切出对应段落，支持 --changelog（默认指向本文件）、--base-path（默认 packages/coding-agent，用于相对链接基准）、--repo、--since-tag、--tag、--version、--out 等参数。

由此可以推断出文档的写作纪律：先写进 [Unreleased]，发布时脚本统一改版本号与日期。这保证了版本头格式（## [x.y.z] - YYYY-MM-DD）严格稳定，parseChangelog 的正则才能持续命中。

六、实战阅读指南

• 升级前：只读目标区间内的 Breaking Changes 与 Changed 小节。0.80.8 与 0.84.0 是迁移量最大的两个点（ModelRuntime 接管认证与模型目录、v4 会话 API），条目自带迁移代码可直接对照扩展代码改造。
• 追新时：读各版本 New Features 粗体条目即可建立能力地图；条目中的 "See" 链接（本仓库中为 packages/coding-agent/docs/ 下的相对路径）直达功能文档细节。
• 排障时：条目中的 issue/PR 编号（如 #8979、#8649）提供了精确的讨论入口；涉及 provider 适配的修复（重试分类、toolChoice 透传、推理回放等）通常以 "Fixed inherited ..." 前缀标识，说明根因在 pi-ai 层，可顺藤到 packages/ai/CHANGELOG.md 交叉核对。
• 自动化消费：直接复用 parseChangelog + getNewEntries + normalizeChangelogLinks 三件套，即可获得"过滤新条目 + 链接钉标签"的完整能力，无需自行解析 Markdown。
• 适用前提：文档仅描述 coding-agent 包的行为变化；日期与版本以当前仓库内容为准，0.x 版本不承诺 minor 升级无破坏性变更，以显式 Breaking Changes 小节为准。

七、小结

packages/coding-agent/CHANGELOG.md 表面是变更记录，实际是 pi 项目发布工程的核心数据源：结构上遵循 Unreleased + 版本头 + 固定小节 的可解析约定，内容上以粗体亮点、issue 编号、inherited 前缀与 Breaking 迁移示例维持高信息密度，工程上被 changelog.ts 解析器、TUI 启动提示、release.mjs 发布流程与 release-notes.mjs 公告生成共同消费。理解这套"书写—解析—发布"闭环，既是快速掌握 coding-agent 演进史的最短路径，也是为多包 monorepo 设计可机器消费变更记录的参考实现。