帮我调研一下 @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。pi 1.5.0 起 pi-ai / pi-agent-core 既不依赖也不再 re-export TypeBox,工具参数改由自带的@earendil-works/pi-schema校验,Tool/AgentTool的参数接受任意 JSON Schema 对象。本项目的Type一律从typebox导入,不要从 pi-ai 导入。AgentTool的params类型由 pi-schema 识别 TypeBox schema 上的'~kind'/'~optional'等标记推导(Enum / Tuple / Intersect 会推成unknown)。单独升级typebox时要确认这些标记还在,pnpm compile会兜住类型退化。- 历史:pi 0.69.0 迁到
typebox1.x,0.86.0 起精确依赖typebox 1.3.27,1.5.0 去掉该依赖。
-
本项目实际用法(评估破坏性变更时以这些为准):
Type/Static/TSchema(来自typebox):lib/tools/*、lib/mcp/client.ts 里的typebox/value校验器。- 工具参数校验在 pi 内部:pi-schema 的
compile(schema, { coerce: true }),MCP 工具的纯 JSON Schema 也走同一套宽松类型转换。 - 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悄悄带进破坏性变更。 -
已知上游行为(已核实至 1.5.0,后续升级时重新核对):Copilot 下的 GPT-6 Sol / Luna / GPT-6.1 Terra 可选「关闭思考」,但 Responses 适配器对
github-copilot不发送effort: "none",由 Copilot 服务端决定;Copilot 的 Gemini 条目(1.5.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 我们可能没用到)。
- 给结论 + 和我讨论:能否升、升级后需要手动回归哪些链路(发消息 / 流式思考 / 工具调用 / 中止 abort / 模型切换 / 压缩 / 分支回卷)。默认不改 package.json,确认后再动。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |