@@ -0,0 +1,79 @@
# 调研：pi v1.0.1 与 ZCode v3.14.3 二次对照
- 状态：记录（2026-10-03）；owner： `feature/pi-zcode-second-pass`
- 对象：
- [earendil-works/pi ](https://github.com/earendil-works/pi ) `4c6fb7cfe8c538a668726f6f8b3554098c39faee` （ ， `c7cdb460` （
- [zai-org/ZCode ](https://github.com/zai-org/ZCode ) `29628c9acdb81b703bbd4080c207a0e7ce5e276e` （ ， `/tmp/ZCode-study` 。Apache-2.0，根目录 LICENSE、NOTICE.md、THIRD-PARTY-NOTICES.md。
- 本仓事实以 Dev `7139e58df0` 为准。前序：[2026-10-01-agent-harness.md ](../proposals/2026-10-01-agent-harness.md ) 的 P0– 2026-10-02-agent-stack-completion.md ](../proposals/2026-10-02-agent-stack-completion.md )、[2026-10-02-agent-stack-audit.md ](2026-10-02-agent-stack-audit.md )、[2026-10-03-pi-durable-review.md ](2026-10-03-pi-durable-review.md )。
- 提示词不逐字照搬。移植设计时在 NOTICE 里注明来源与修改；不把上游包、插件市场或技能正文整仓拷入。
结论先说：P0–P4 已经借走回放、结束门禁、续写、验证器、子代理和工作流骨架。这一轮要补的是模型层健壮性、上下文工程、权限与钩子、文件回滚、代码编排端口。不引入 `@earendil-works/pi-durable` 、Chord，也不移植 ZCode 的 TypeScript 动态工作流。
---
## 1. 来源现在是什么
pi 仍是最小可扩展的 agent harness：交互、print、JSON、RPC 和 TypeScript SDK。v1.0.1 的实质增量是 codemode、MCP 产品化、虚拟模型、分类器基础设施，以及整棵 Pico5 运行时。`packages/durable` 仍标 Experimental； `packages/agent` 在 v1.0.0 删掉了实验内核 pico3。coding-agent 的实验 TUI 已迁到 durable。
ZCode 是桌面、Web 和 CLI 共用的编程工作台。本记录只看 `apps/zcode-cli/packages/core` 与 `contracts` 里的 harness，以及产品壳里和运行态有关的协议。P0–P4 已经对齐的部分（原生工具回放、Stop 上限 3、输出续写 3 次、同名同参提醒、证据清单验证、子代理深度 1、声明式工作流）不再重复评级。
## 2. 评级
每条都标了本仓落点。阶段名沿用 agent-stack 提案的 N1、N2、N3；「批次」指本任务之后的实现批次。
| 主题 | 上游 | 本仓 | 评级 | 批次 |
|---|---|---|---|---|
| 上下文溢出识别 | pi `packages/ai` ：按供应商文案识别，含 Z.AI 中文站 | `deps/agent-native/runtime/llm/providers.go` 的 `ContextOverflow` 要求错误信息同时含 “context” 与 overflow/too long/length | adopt | 2，
| Retry-After 与容量重试 | pi：解析失败则指数退避；“Selected model is at capacity” 可重试 | `runtime/llm/client.go` 对 429/5xx 标可重试，不读 Retry-After | adopt | 2，
| 未完成的工具调用 | pi `1b2aa0ca0` ： `runtime/llm/sse.go` 的 `mapFinish` ： `length` 或空、且已有工具增量时返回 `StopToolCalls` | adopt | 2 |
| 流式重试不吞增量 | pi 的重试发生在收到正文之前 | `WithRetry` 先缓冲整次尝试再转发。默认打开会让流式失效 | adopt | 2，
| 用量拆分 | pi 会话成本区分请求与累计 | 循环把每轮 prompt token 累加（审计 N20） ，
| 运行内清理旧工具结果 | ZCode compact：保留最近若干条，更早的 Read/Bash/Grep 结果可替换 | 产品回放保留全文；内核 `session/compact.go` 按条数裁尾，可切断工具配对（审计 N7） | adopt | 4，
| 压缩与追加的竞态 | pi durable：压缩是新条目加 head，不改历史 | `compact.go` 读完解锁再摘要（审计 N8） ，
| 先读后改、文件过期 | ZCode `tool/read-file-state.ts` 、edit handler：未读或 mtime 变化则拒绝 | 内置 write/edit 与后端 `write_file` 无此检查 | adopt | 4，
| 提醒不占 user 角色 | ZCode `system-reminder/source.ts` ：按来源节流，不破坏工具配对 | `runtime/loop.go` 的 `withEphemeral` 追加 user 消息（审计 N22） ，
| 子代理结果上限 | ZCode agent handler 约 120KB | `modules/backend/internal/runtime/sub_loop.go` 把结果原文交回 | adopt | 4，
| 默认工具 `+name/-name` | pi settings， `30a1d1849` | `runtime/tools/registry.go` 只有精确名和通配 | adopt | 4，
| RPC 回执 | pi `e473b5cd8` ： `started` / `queued` / `handled` | `rpc/server.go` 只返回 OK 与正文 | adopt | 4 |
| 按字符截断 | ZCode 与审计 N16 | `runmgr.go` 的 `ExecuteTool` 用字节切片截断工具结果 | adopt | 4 |
| 权限三档 | ZCode： ，
| 钩子总线 | ZCode `contracts/hooks` ： `adapters/native/backend.go` 不透传（审计 N31） | adopt 进程内总线；hold 进程级钩子 | 6，N1 |
| 向用户提问 | ZCode AskUserQuestion | HITL 有 choice/input/confirm/form，没有一等工具 | adopt | 6，
| 计划模式工具闸 | ZCode EnterPlanMode / ExitPlanMode | `update_plan` 只写计划，不限制写工具 | adopt | 6，
| 确认卡参数 | 本仓缺口，不是上游新能力 | `ExecuteTool` 算出 `argsPreview` 后丢弃 | adopt | 6 |
| 意图与结果分两次提交 | pi durable Tools： `replay` 取存储时与当前声明的交集 | 工具结果在执行后一次写入；崩溃留下无结果的调用（审计 N1 的同类） | adopt | 7，
| 只回滚写文件 | ZCode `contracts/rewind` ；pi 文件检查点只追踪写 | 无文件回滚 | adopt | 7，
| 请求只读已落盘投影 | pi `466db0fec` ： ，
| 模型回退链 | pi 虚拟模型是每请求路由器，不是静态链 | 无回退；溢出不重试 | adopt 静态链，默认空；hold 虚拟模型路由 | 7，N3 |
| GenAI span | 提案 §2.1 已列名字；ZCode telemetry 默认少采正文 | 有 logging-system 的 trace_id，无这组 span | adopt | 7，
| 代码编排工具 | pi `packages/codemode` ：模型写 JS，跑在 QuickJS，中间结果不进上下文；bash 对脚本最多 1MiB | 后端 `workflow_script.go` 是工作流步骤，不是模型侧工具 | adopt 端口语义，不搬 QuickJS | 8，
| MCP 延迟暴露 | pi `docs/mcp.md` ： `runtime/mcp/manager.go` 启动即连接；stdio 取消后读协程不退出（审计 N3）；失败重连只有注释（N18）；HTTP Close 为空（N19） ，
| 运行态单一所有者 | ZCode 协议把 in-flight 与 settled 分开；发送即 ack | 前端 `store.ts` 的 live 与 runs 分别更新。Dev #161 已修可见性回归 | adopt 剩余的单一状态源与事件穷举 | 5 |
| 架构基线棘轮 | ZCode `architecture-policy.yaml` 与 knip | Dev 已有库间导入棘轮，不管 backend internal 分层，也不查死导出 | adopt | 3 |
## 3. 拒绝，以及为什么
| 项 | 理由 |
|---|---|
| 依赖 pi-durable 或 Chord | TypeScript、Experimental、Chord 不是稳定契约。只借鉴规则和测试意图 |
| 透明续跑 | 骨架设计 §4.2 明确不做 |
| 回滚对话历史 | 文件可以回到某条用户消息之前；消息树保持追加 |
| 绕过确认的权限档 | ZCode 的 yolo 与本仓「deny 不能被 allow 跳过」冲突 |
| 进程级钩子、MCP OAuth | 宿主是多租户后端，不是单用户 CLI。钩子先做进程内回调 |
| ZCode 动态工作流 DSL | 编排已裁定归 Agent-Squad。不移植 TypeScript 沙箱脚本图 |
| ZCode TUI、桌面、远程 SSH、CUA、cron、插件市场 | 产品形态是单二进制加 Web。CUA 在上游也是占位 |
| pi 虚拟模型与分类器路由 | 当前没有「每个请求选模型」的产品需求。回退链用静态列表 |
| Anthropic 原生协议与 thinking 签名回放 | 仍按提案 N2 单独做。本轮只堵住会执行未完成工具调用的解析 |
## 4. 不回退的既有决定
- 交付守卫失败即不通过。ZCode 在验证器自身出错时放行。见 harness 提案 §2。
- 正文里的伪造工具调用要拦截。见 harness 提案 P0。
- 动态工作流步数、脚本确认和回调白名单保持 P4 的数字。代码编排端口默认关闭。
- 回合默认仍有轮次和预算上限。ZCode 的长任务哲学是不按工具次数硬停；本仓保留上限作安全阀。
- 库声明自己不是操作系统沙箱。
## 5. 本记录的验收
- 本文件、pi-durable 记录文首更正、提案 §2.4 互相链接。
- 不改 Go 或 TypeScript 代码，不改三个库的指针。