weichen
001648cd0e
Why: the matrix scoped native work to the pi wrapper's exposed surface; the full-agent batch deliberately expands beyond it, so the new domains need their own acceptance basis recorded (standard conformance + negative tests + product acceptance, not pi comparison) plus honest security boundary notes. Evidence: docs-only change; go vet/test unaffected (verified green in the code commits this branch carries). Impact: docs/parity-matrix.md gains the R15 expansion table mapping every domain to its test evidence; README package table reflects the new runtime/mcp, runtime/skills, runtime/promptx, runtime/subagent packages and the v0.2 exec port. Refs: docs/parity-matrix.md #1-#16 remain valid for wrapper-parity rows.
92 lines
9.7 KiB
Markdown
92 lines
9.7 KiB
Markdown
---
|
||
title: "U9a Parity Matrix：Agent-Native 对齐 PI 0.85.1 核心能力盘点"
|
||
date: 2026-09-29
|
||
task_id: multi-repo-design-2026-09-28
|
||
track: U9 (R14：产品核心能力可替代，非上游复刻)
|
||
baseline_fixed: true
|
||
---
|
||
|
||
# U9a 能力盘点（三层基线固定）
|
||
|
||
## 基线
|
||
|
||
| 层 | 版本/内容 | 证据 |
|
||
|---|---|---|
|
||
| 上游包 | `@earendil-works/pi-coding-agent@0.85.1`（gitHead `d981de12`，MIT） | deploy/pi-agent/Dockerfile:18 |
|
||
| 项目 wrapper | deploy/pi-agent：runner.mjs（`/v1/run`、`/v1/run/stream`、`/v1/search`）+ entrypoint（`--mode rpc --no-session`、`--tools read,write,edit --approve`）+ extensions/tavily-search.mjs + result-v1/settle-policy/reasoning-materialize/change-report-narrative .mjs | deploy/pi-agent/* |
|
||
| 产品调用侧 | internal/agent/piagent.go（typed_result、NDJSON 流式优先+一次性回落、data-root 不符拒绝、AssessStepFailure 重试分类）、pi_runner_search.go（/v1/search）、MaterializeTargets | internal/agent/* |
|
||
| 原生现状 | agent-native：runtime（loop/tools/llm/session）+ exec 冻结端口 + contract v0.1.0（尚未被 runtime 消费）+ adapters/pitransport + abtest（6 例 + Judge） | modules/agent-native |
|
||
|
||
对标口径：**产品实际依赖**（wrapper 真实暴露面），不是上游全部功能。任何重构建制以固定 0.85.1 为准，不对上游 main。
|
||
|
||
## Parity Matrix
|
||
|
||
状态：native = available / partial / missing / not_required。
|
||
|
||
| # | 能力域 | 上游/wrapper 现状 | 产品依赖 | native 现状 | 差距 → 批次 |
|
||
|---|---|---|---|---|---|
|
||
| 1 | 多轮执行循环 + 工具调度 | rpc 模式内核 | 必需（全部小队任务） | **available**（loop + 并行工具 + turn cap，runtime/loop.go） | 行为等价性入 Batch2 回归 |
|
||
| 2 | 模型流式（Chat Completions/SSE） | MiniMax openai-compatible | 必需 | **available**（llm SSE 客户端） | 流错误/截断负例入 Batch1 |
|
||
| 3 | 文件工具 read/write/edit/list | wrapper 限定 `--tools read,write,edit --approve` | 必需 | **available**（builtin 四件 + jail 路径约束） | 工具语义负例（越界/截断/错误格式）Batch2 |
|
||
| 4 | 工具策略（workspace/reasoning profile） | wrapper 参数组合 | 必需 | **partial**（jail 有；profile 组装在 Core，TaskPolicy 未接 runtime） | Batch2 |
|
||
| 5 | **搜索（Tavily /v1/search）** | 项目自加扩展（非上游核心） | **必需**（pi_runner_search.go 消费方） | **missing** | **Batch1**：builtin search 工具 + Provider 接口（密钥 Core 注入） |
|
||
| 6 | typed-result-v1 编解码/摘要 | result-v1.mjs（canonical JSON digest） | 必需（PI 互操作合同） | **available**（adapters/pitransport，含 Node 交叉验证测试） | 维持；native 自产结果不经此编码 |
|
||
| 7 | 结果 settle/outcome 分类 | settle-policy.mjs（agent_settled 等） | 必需（成功/失败判定入口） | **available**（exec.AssessStepFailure） | **Batch1**：与 settle-policy 逐事件 fixture 对齐 |
|
||
| 8 | 过程流 NDJSON（proc 帧） | /v1/run/stream 实时转发 | 必需（小队过程视图 2026-09-28 设计） | **partial**（runtime Event 有；词汇表与 proc 帧未对齐） | **Batch1**：事件词汇 conformance |
|
||
| 9 | 交付物物化（Targets→Patches 校验） | 产品侧 MaterializeTargets | 必需 | **available**（exec.deliverable） | 回归入 Batch2 |
|
||
| 10 | 取消传播 | 产品侧 stream ctx 取消（retryable） | 必需 | **partial**（loop ctx 有；模型/工具层传播未验证，contract CapCancel 未接） | **Batch2** |
|
||
| 11 | 长上下文 compaction | 上游核心有（长会话压缩）；wrapper 未禁用 | **依赖未证实**（任务为有界单发，--no-session） | missing | Batch3 可选：先实测长任务 token 压力再定 |
|
||
| 12 | 会话/执行恢复 | 上游 sessions；wrapper 明确 `--no-session`（临时会话） | **not_required**（产品恢复走 task_runs/重跑，不延续上游会话） | partial（JSONL transcript） | Batch3：对齐 contract 的 Unknown/resume 语义即可 |
|
||
| 13 | TS 扩展 ABI | 上游支持 | **not_required**（仅 Tavily 一个项目自写扩展 → 以 #5 builtin 工具替代） | — | 不做 |
|
||
| 14 | 终端 UI/主题/全供应商登录/全部 SDK 面 | 上游产品功能 | **not_required**（方案 KTD12 明确不复刻） | — | 不做 |
|
||
| 15 | reasoning-materialize / change-report-narrative（.mjs） | 项目自加后处理 | partial（app 组合根 pi-agent 条件门控的 summary/narrative） | missing | Batch3：由 Core 侧等价实现或显式降级，不搬 .mjs |
|
||
| 16 | usage/预算 | rpc 报用量 | 必需（Result token 字段） | **partial**（llm 用量有；预算/截止未贯穿） | Batch2 |
|
||
|
||
## U9b 分批补齐计划（估算按有上下文实施者工作日）
|
||
|
||
| 批 | 内容 | 估算 | 出口 |
|
||
|---|---|---|---|
|
||
| **Batch1 必需协议域**（✅ 2026-09-29 完成） | ① builtin `web_search` 工具（SearchProvider 接口，Tavily 兼容响应形状；密钥/端点经 Options 注入，测试用 fake）② settle/outcome 分类与 settle-policy.mjs 逐事件 fixture 对齐（Node fixture 复用 pitransport testdata 模式）③ 过程事件词汇表 conformance（runtime.Event ⇄ proc 帧：text_delta/reasoning_delta/tool_* 全集） | 实际 1 日 | 三域全部落地：`runtime/tools/search.go`（密钥池轮换+输出逐字段对齐+8 测试）；`exec/settle_parity_test.go`（10 场景 Go+Node 双侧交叉验证，Go 为终裁者契约）；`runtime/event_vocabulary_test.go`（行为级词汇 conformance）。#5/#7/#8 关闭 |
|
||
| **Batch2 安全与语义域** | ④ 取消传播（ctx→llm 请求/工具执行；contract CapCancel 接 runtime）⑤ 工具语义负例（jail 越界、长输出截断、错误格式）⑥ retry/failure 分类与传输错误矩阵回归 ⑦ 预算/截止贯穿（Budget→loop） | 2–3 日 | #3/#4/#10/#16 关闭；负例不冒充 PASS |
|
||
| **Batch3 长尾与决策域** | ⑧ 长任务 token 实测 → 决定 compaction 是否必需 ⑨ transcript→contract resume 语义对齐 ⑩ summary/narrative Core 等价实现或显式降级声明 | 3–5 日（含实测） | not_required 项有书面证据；partial 项二选一定案 |
|
||
|
||
## U9c 对比验收（扩展现有 6 例）
|
||
|
||
- 每个必需域（#1–#10、#16）至少：正常 1 + 异常 1 + 边界 1 配对用例，双后端同输入；
|
||
- Judge 增补：绝对成功率门槛（当前仅相对）、语义 rubric、实际后端身份断言（禁 fallback 混淆）、副作用检查；
|
||
- 固定语料重复配对（≥10 样本/域）报告分布；P95≤1.3× 沿用但 6 例不得外推结论；
|
||
- 准入：必需域全过 + 严重缺陷 0 + 语义无重大缺项；SKIP/零用例不算 PASS。
|
||
|
||
## U9d/e 渐进启用与收口
|
||
|
||
按方案原条款执行：隔离环境/内部账号允许清单 → 按任务类别开放 → 配置 PR 显式切换 → PI 适配器保留回退。默认后端不因验收通过自动切换。
|
||
|
||
## 记录与证据
|
||
|
||
- 本矩阵证据均指向仓库内文件（上文路径），不含运行时截图；
|
||
- Batch1 完成后在本文件追加"实测证据"列；
|
||
- 上游仅引固定 0.85.1 的 README/docs 结论，不引 main。
|
||
|
||
---
|
||
|
||
## R15 扩面批次（full-agent-r1，2026-10-01）：从「wrapper 对标」到「完全智能体」
|
||
|
||
用户定调（2026-10-01）：Agent-Native 补全 pi-Agent 全量工具调用能力（网络搜索、代码编写、
|
||
系统工具、外部工具调用、技能、提示词），并与 Agent-Squad 融合。扩面域**不做 pi 对标**
|
||
（上游 wrapper 未暴露这些能力），改以「标准符合 + conformance 负例 + 产品验收」为准——
|
||
对标口径条款对本批新增域不适用，原有 #1–#16 行继续有效。
|
||
|
||
| 域 | 内容 | 出口证据 |
|
||
|---|---|---|
|
||
| 执行基座 | exec.Request v0.2（Model/ToolAllowlist/Skills/Budget/SessionScope/ExecutionID/Env）+ Registry.Restrict 策略层（精确名 + 命名空间通配）+ 预算贯穿（token/工具数/截止，budget_exceeded 永久失败）+ 取消传播到工具 | loop_budget / registry_policy / request_v2 / step_retry_budget 测试；关闭 #4/#10/#16 |
|
||
| 代码工具面 | glob（** 跨目录）、grep 正则/include/ignore_case、read 行范围分页、multi_edit 原子多处替换 | code_tools_test.go |
|
||
| 系统工具 | run_command / run_python：解释器白名单、env 白名单（宿主密钥不透传）、进程组 SIGKILL（超时/取消）、64KB 头尾截断、命令黑名单、脚本落盘 .agent/scripts/；Options.Exec 未配置不注册 | exec_tools_test.go（含杀组时限断言） |
|
||
| 网络面 | tavily_search/web_search 经 Options.Search 接线（关闭 #5 尾环）；fetch_url：SSRF 硬边界（私网/回环/链路本地/元数据端点逐跳校验）、域名策略、2MB/20s、HTML 剥离 | fetch_test.go + 适配器接线测试 |
|
||
| MCP | stdio + Streamable HTTP 客户端、initialize/tools/list(paged)/tools/call、Mcp-Session-Id、mcp__<server>__<tool> 桥接、64 工具/1KB 描述/64KB 结果上限、不可达 fail-closed、真实子进程测试（re-exec fake server） | runtime/mcp/mcp_test.go |
|
||
| 技能/提示词 | SKILL.md 加载（目录名权威、frontmatter 描述）、load_skill 渐进披露、声明技能 fail-closed 校验、promptx 装配器（环境/技能索引/交付物） | skills_test / promptx_test / 适配器测试 |
|
||
| 会话 | compaction（阈值触发、原子改写、失败留痕不阻断）、元数据 sidecar、崩溃半行容错 | compact_test.go；对齐 #11/#12 |
|
||
| 委派 | runtime/subagent 端口 + delegate_task（信息集=委派条款）；嵌套执行由宿主注入 | subagent_test.go |
|
||
|
||
安全声明（不冒充已解决）：run_command **不是 OS 沙箱**（宿主负责隔离）；技能正文与 MCP
|
||
server 描述是提示注入面（只信受信根 + 长度上限）；fetch 的 DNS 解析存在 rebinding 窗口。
|