帮我调研一下 @earendil-works/pi-agent-core 和 @earendil-works/pi-ai 的最新更新,深入调研我目前安装的版本和最新版本之间的更新内容和细节,确认后,和我讨论能否进行升级。
这是一次调研 + 讨论任务:默认不要改 package.json 或跑安装命令,讨论确认后再动。
变更查询来源(按优先级)
这两个包同属 pi monorepo(github.com/earendil-works/pi),变更日志在仓库里,不在 npm release notes,逐版本读、别只看最新一版:
- pi-ai:
packages/ai/CHANGELOG.md→ https://github.com/earendil-works/pi/blob/main/packages/ai/CHANGELOG.md - pi-agent-core:
packages/agent/CHANGELOG.md→ https://github.com/earendil-works/pi/blob/main/packages/agent/CHANGELOG.md - 发布节奏 / 日期交叉印证(npm 版本历史):
两个 CHANGELOG 都遵循 Keep a Changelog(Breaking Changes / Added / Changed / Fixed / Removed)。重点抓 Breaking Changes。
硬性约束(务必遵守)
两个包锁步升级到同一版本。lockfile 里 pi-agent-core 依赖同版本 pi-ai;只升其中一个会造成版本错配。
typebox跟随 pi,绝不单独升。本项目 package.json 把typebox精确锁死(无^),就是为了和 pi 内部捆绑的 typebox 完全一致——两边TSchema类型标识必须是同一份,否则本项目用Type.Object(...)造出来的 schema 传给 pi 校验会类型不兼容,还可能产生两份 typebox 副本。- 升级 pi 后,去 pnpm-lock.yaml 查 pi 实际解析的
typebox版本;只有当它变了,才把项目的typebox精确 pin 改成同一版本。 - 参考:pi 的 typebox 迁移发生在 0.69.0(
@sinclair/typebox0.34.x →typebox1.x);0.86.0 起精确依赖typebox 1.3.27。
- 升级 pi 后,去 pnpm-lock.yaml 查 pi 实际解析的
本项目实际用法(评估破坏性变更时以这些为准):
Type/Static/TSchema:lib/tools/*、lib/mcp/client.ts 里的typebox/value校验器。- agent runtime:hooks/useBackgroundAgent.ts、lib/agent/、
AgentTool协议(tool 抛错=失败、返回=成功)。
会话树与压缩依赖的 harness 已 vendor,不随 pi 升级。pi 1.0.0 删除了整个实验性 harness(Session 层、压缩函数、
session/testing、compactionSummary等自定义消息类型),本项目把用到的部分冻结在 0.84.4 快照,放在 lib/shims/pi-harness/(原因、偏离与维护约定见其 README)。升级 pi 时:- 不必再 diff 上游 harness(上游已不存在),但要按 README「维护约定」核对它依赖的 pi 公开 API(
uuidv7、Models.completeSimple、retryAssistantCall、contentText、消息类型、CustomAgentMessages等)没有变。 - vendored conformance 套件(经 lib/persistence/session-tree.test.ts 运行)必须保持全绿。
- 不必再 diff 上游 harness(上游已不存在),但要按 README「维护约定」核对它依赖的 pi 公开 API(
系统提示词与工具不进
agent.state。pi 0.86 起把系统提示词和工具声明作为 transcript 里的role: 'system'消息传递;本项目让agent.state.messages保持纯对话流(会话树的水位线 / 下标对齐依赖这一点),由 entrypoints/background/agent/factory.ts 的prepareRequest按AgentPreamble在每次请求前现装 system 头。升级 pi 时:- 重点读 agent-loop 的
declareToolChanges、prepareRequest、prepareNextTurn(Agent 选项名为prepareNextTurnWithContext)、finishTurn有没有改语义或时序。 - factory.test.ts 会兜住「每次请求都有头、system 消息永不进 state」这条不变式,必须保持全绿。
- 重点读 agent-loop 的
版本范围用
~。package.json里两个包写~x.y.z(只放行 patch),minor 升级必须走本流程,避免一次pnpm install悄悄带进破坏性变更并与精确 pin 的typebox错位。已知上游行为(已核实至 1.4.0,后续升级时重新核对):Copilot 下的 GPT-6 Sol / Luna 可选「关闭思考」,但 Responses 适配器对
github-copilot不发送effort: "none",由 Copilot 服务端决定;Copilot 的 Gemini 条目(1.4.0 为gemini-3.8-flash、gemini-4-argon)supportsReasoningEffort: false,思考档不生效。请求不带 pi 的归因。pi-agent-core 1.4 起 agent loop 默认带
PI_ATTRIBUTION(OpenRouter 的X-OpenRouter-Title: pi、NVIDIA 的X-BILLING-INVOKE-ORIGIN: Pi等);factory.ts 传identity: { attribution: null }关掉,OpenRouter 的 Cebian 归因仍由lib/providers/resolve-model.ts写进model.headers。升级时核对ClientIdentity/mergeClientIdentity的语义没变,factory.test.ts的「请求归因」用例会兜住。
工作流
pnpm outdated看两个包的 Current / Latest。- 逐版本读上面两个 CHANGELOG(把 Current→Latest 之间每个版本都覆盖到),重点抓
Breaking Changes和公开 API 改动。 - 交叉验证:CHANGELOG 与 npm 版本历史日期是否一致;破坏性变更是否命中本项目实际用法(别人眼里的 breaking 我们可能没用到)。
- 给结论 + 和我讨论:能否升、要不要顺带动
typebox(按上面约束判断)、升级后需要手动回归哪些链路(发消息 / 流式思考 / 工具调用 / 中止 abort / 模型切换 / 压缩 / 分支回卷)。默认不改 package.json,确认后再动。