Document pi-agent-core 0.67.6→0.67.68 upgrade trace and rollback plan (B1.1)

2026-04-20 11:04:13 -04:00
1 parent b100bdcc10
commit b3b9eb60e4
@@ -0,0 +1,90 @@
+# Proposal B1.1: pi-agent-core 升级到 in-tree reference 的决策记录
+
+> 来源：问题.md B1（pi-mono-reference 与实际依赖 62 patch 漂移）
+> 状态：executed（已 commit `35c1229`）+ open（需 eval 监控）
+> 决策时间：2026-04-20 Roundtable
+> Owner: TBD（建议项目 maintainer）
+> 关联 commit：`35c1229 Pin pi-agent-core/pi-ai/pi-coding-agent to exact 0.67.68`
+> Blocking dependencies for full close-out：B5 LLM eval harness
+
+---
+
+## 背景
+
+问题.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），同时保持 in-tree reference 不变。
+
+执行后的事实：
+- `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 的情况下**无法量化**，今晚选择"接受 + 监控"：
+
+1. **prompt cache 语义可能变化**：0.67.6 → 0.67.68 跨度内 pi-ai 修改过 cache header 行为，cache hit rate 可能改变
+2. **tool schema 解析可能更严格**：上游对 tool name / input schema 的 validate 可能更严
+3. **streaming / token 事件分片可能变化**：cost-writer 的 token ledger 计算可能产生轻微偏差
+4. **transitive dep 跃迁**：`@mistralai/mistralai` 在该版本范围内做过 1.x → 2.x major bump（pnpm-lock diff 可见），如果使用 Mistral provider 行为可能变化
+5. **hook 签名兼容性**：本地 `hook-handlers.ts` / `context-compactor.ts` / `cost-writer.ts` 的 hook 注入接口若有变化，会在运行时才暴露
+
+## 监控与回滚计划
+
+### 监控指标（手动观察直到 B5 落地）
+- 启动主进程后第一个 agent run 是否能跑完一轮 tool call
+- compactor 触发时是否有 tool_use/tool_result 报错
+- 长会话（>50 轮）是否出现非预期 cost / token 偏差
+- 任何 provider 返回 400 / unexpected tool schema error
+
+### 紧急回滚步骤（任何上面的指标异常时执行）
+```bash
+# 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"
+```
+
+如选择回滚，**必须同步**把 `pi-mono-reference/packages/*/package.json` 也降到 `0.67.6`，避免 reference 与运行时再次分叉。
+
+## 不在范围
+
+- 不在本 proposal 内升级到 `0.67.68` 之上的更新版本（任何后续升级单独走 proposal）
+- 不在本 proposal 内引入自动化升级机制（renovate / dependabot 等）
+- 不在本 proposal 内添加 LLM 行为 eval（那是 B5 的工作；B5 完成前本升级的"监控"只能靠人工）
+
+## 完成定义
+
+本 proposal 在以下条件全部满足时关闭：
+1. B5 LLM eval harness 落地，能跑一组 agent 行为 fixture
+2. 在该 harness 上对比 `0.67.6` ↔ `0.67.68` 的行为 diff
+3. 行为 diff 报告附 commit，确认无意外回归
+4. 关闭 B1.1，写入到 changelog