Proposal B1.1: pi-agent-core 升级到 in-tree reference 的决策记录

来源：问题.md B1（pi-mono-reference 与实际依赖 62 patch 漂移）状态：executed（已 commit 35c1229）+ guarded（2026-04-23 runtime contract tests）决策时间：2026-04-20 Roundtable Owner: TBD（建议项目 maintainer）关联 commit：35c1229 Pin pi-agent-core/pi-ai/pi-coding-agent to exact 0.67.68 Runtime guardrail：tests/unit/pi-runtime-dependency-contract.test.ts + tests/integration/pi-runtime-contract.spec.ts + tests/eval/harness.test.ts Superseded note（2026-04-22）：in-tree pi-mono-reference/ snapshot has been removed. Runtime truth now lives in root package.json and pnpm-lock.yaml. Guardrail note（2026-04-23）：runtime truth is now executable: package pins, lockfile entries, installed package versions, exported API surface, Agent factory wiring, coding tools, skill loader, hook bundle, and eval fixture piAgentCoreVersion are covered by automated tests.

背景

问题.md B1 记录的事实：

来源	pi-agent-core 版本
`pi-mono-reference/packages/agent/package.json`	`0.67.68`
主项目 `package.json`（修复前）	`^0.67.6`
`pnpm-lock.yaml`（修复前）	`0.67.6`
`node_modules/...`（修复前实际安装）	`0.67.6`

caret range ^0.67.6 在 pnpm semver 里允许 resolve 到 >=0.67.6 <0.68.0 的最新版本。也就是说：下一个新工程师 pnpm install 时大概率会拿到 0.67.68（caret 范围内的最高 patch），与当前 lockfile 锁定的 0.67.6 静默分叉。

圆桌三人立场

讨论中三人对"今晚 pin 到哪个版本"出现实质分歧：

角色	立场	理由
Karpathy	pin 到 `0.67.6`（不升级）	march of nines / 62 patch silent drift / 无 eval baseline 不能动 prompt cache & tool schema
Jobs	pin 到 `0.67.68`（对齐 in-tree）	in-tree reference 就是团队的 canonical 意图，`0.67.6` 是 caret 漂移的偶然产物
Linus（执行者）	pin 到 `0.67.68`	依据：lockfile 应对齐 in-tree reference，否则下次 install 仍会随机升

实际执行的决策

采纳 Linus / Jobs 立场：pin 到精确 0.67.68（升级 62 patch），并记录 runtime package set as the source of truth.

执行后的事实：

pnpm install --no-frozen-lockfile 后 pnpm typecheck 全绿
node_modules/@mariozechner/pi-agent-core/package.json 显示 0.67.68
三个相关包（pi-agent-core / pi-ai / pi-coding-agent）一致 pin 到 0.67.68

Karpathy 视角的剩余风险（必须记录）

以下风险在没有 B5 eval harness 的情况下无法量化，今晚选择"接受 + 监控"：

prompt cache 语义可能变化：0.67.6 → 0.67.68 跨度内 pi-ai 修改过 cache header 行为，cache hit rate 可能改变
tool schema 解析可能更严格：上游对 tool name / input schema 的 validate 可能更严
streaming / token 事件分片可能变化：cost-writer 的 token ledger 计算可能产生轻微偏差
transitive dep 跃迁：@mistralai/mistralai 在该版本范围内做过 1.x → 2.x major bump（pnpm-lock diff 可见），如果使用 Mistral provider 行为可能变化
hook 签名兼容性：本地 hook-handlers.ts / context-compactor.ts / cost-writer.ts 的 hook 注入接口若有变化，会在运行时才暴露

自动化护栏

pi-mono-reference/ 删除后，源级 review 能力转为本项目内的运行时契约。当前护栏分三层：

tests/unit/pi-runtime-dependency-contract.test.ts
- package.json 三个 pi runtime 包必须精确 pin 到 0.67.68
- pnpm-lock.yaml importer / resolution / snapshot 必须指向同一版本
- node_modules 中实际安装包版本必须一致
- AgentCompany 使用的 pi API surface 必须存在
tests/integration/pi-runtime-contract.spec.ts
- createPiAgent 必须创建真实 Agent，保持 sequential tool execution 和三类 hook
- createRunScopedCodingTools 必须输出当前 worker 依赖的 coding-tool surface
- bash spawn hook 必须保留 run-scoped env 注入
- loadSkills 必须能读取 progressive-disclosure SKILL.md
tests/eval/harness.test.ts
- 每个 fixture 的 meta.piAgentCoreVersion 必须等于 shipping runtime version
- 真实 fixture 继续穿过 pi-agent-core Agent loop replay

监控与回滚计划

监控指标

启动主进程后第一个 agent run 是否能跑完一轮 tool call
compactor 触发时是否有 tool_use/tool_result 报错
长会话（>50 轮）是否出现非预期 cost / token 偏差
任何 provider 返回 400 / unexpected tool schema error

紧急回滚步骤（任何上面的指标异常时执行）

# 1. 改 package.json 三个 pi 包到 0.67.6
# 2. 重生成 lockfile
pnpm install --no-frozen-lockfile
# 3. 验证
pnpm typecheck
# 4. commit
git add package.json pnpm-lock.yaml
git commit -m "Revert pi-agent-core pin to 0.67.6 due to behavior regression"

如选择回滚，必须同步更新本 proposal 的目标版本记录、package.json、pnpm-lock.yaml 和行为 diff 报告。

不在范围

不在本 proposal 内升级到 0.67.68 之上的更新版本（任何后续升级单独走 proposal）
不在本 proposal 内引入自动化升级机制（renovate / dependabot 等）
不在本 proposal 内添加 LLM 行为 eval（那是 B5 的工作；B5 完成前本升级的"监控"只能靠人工）

完成定义

本 proposal 在以下条件全部满足时关闭：

package.json / pnpm-lock.yaml / installed package versions 三者一致
pi exported API surface、Agent factory、coding tools、skill loader、hook bundle 都有自动化契约
eval fixtures 的 piAgentCoreVersion 与 shipping runtime version 一致
pnpm verify 覆盖 unit / integration / eval / e2e

5.8 KiB Raw Blame History Unescape Escape