91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# 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
|