111 lines
5.8 KiB
Markdown
111 lines
5.8 KiB
Markdown
# 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 的情况下**无法量化**，今晚选择"接受 + 监控"：
|
||
|
||
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 注入接口若有变化，会在运行时才暴露
|
||
|
||
## 自动化护栏
|
||
|
||
`pi-mono-reference/` 删除后，源级 review 能力转为本项目内的运行时契约。当前护栏分三层：
|
||
|
||
1. `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 必须存在
|
||
2. `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`
|
||
3. `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
|
||
|
||
### 紧急回滚步骤（任何上面的指标异常时执行）
|
||
```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"
|
||
```
|
||
|
||
如选择回滚，**必须同步**更新本 proposal 的目标版本记录、`package.json`、`pnpm-lock.yaml` 和行为 diff 报告。
|
||
|
||
## 不在范围
|
||
|
||
- 不在本 proposal 内升级到 `0.67.68` 之上的更新版本（任何后续升级单独走 proposal）
|
||
- 不在本 proposal 内引入自动化升级机制（renovate / dependabot 等）
|
||
- 不在本 proposal 内添加 LLM 行为 eval（那是 B5 的工作；B5 完成前本升级的"监控"只能靠人工）
|
||
|
||
## 完成定义
|
||
|
||
本 proposal 在以下条件全部满足时关闭：
|
||
1. `package.json` / `pnpm-lock.yaml` / installed package versions 三者一致
|
||
2. pi exported API surface、Agent factory、coding tools、skill loader、hook bundle 都有自动化契约
|
||
3. eval fixtures 的 `piAgentCoreVersion` 与 shipping runtime version 一致
|
||
4. `pnpm verify` 覆盖 unit / integration / eval / e2e
|