docs(test): record PI typed-result-v1 dual-track evidence

Archive Track P tasks and point FEATURE-MATRIX at the live MiniMax runner report. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 15:25:34 +00:00
parent 0a61cfbe90
commit a3fa7c137b
8 changed files with 192 additions and 19 deletions
@@ -0,0 +1,47 @@
+---
+title: "PI typed-result-v1 P1–P4"
+status: done
+created: 2026-09-15
+updated: 2026-09-15
+owner: Cursor
+branch: feature/pi-typed-result
+worktree: "-"
+mutex: pi-agent
+---
+
+# PI typed-result-v1 P1–P4
+
+## 目标
+
+Runner additive 输出 `result_v1`；Go typed-first fail-closed；共享 dev 真实 PI 双轨对账；去掉 stderr/legacy 明文错误。
+
+## 范围
+
+- `configs/schemas/pi-run-result-v1.json`
+- `deploy/pi-agent/result-v1.mjs` + runner 接线
+- `internal/agent` parser / 负例 / `RUN_PI_E2E=1` 双轨
+
+## 非目标
+
+- 不把 member 正文搬进 `result_v1`（仍走 `patches[]`）
+- 不改 HTTP 状态码；不启用 FAV；不写项目 143
+
+## 步骤
+
+1. [x] Schema + Runner additive
+2. [x] Go typed-first + handshake
+3. [x] 真实 PI 双轨
+4. [x] 删 stderr/隐式 legacy；报告与合入
+
+## 验收标准
+
+- [x] typed-present-invalid 永不 fallback
+- [x] handshake downgrade 负例 PASS
+- [x] `RUN_PI_E2E=1` 成功/失败/取消/超时对账
+- [x] test-report 归档
+
+## 相关链接
+
+- Test report: `.doc/test-reports/2026-09-15-pi-typed-result-v1-test-report.md`
+- Remediation: `.doc/remediation/2026-09-15-pi-typed-result-v1-remediation.md`
+- P0: `.doc/ops/research/2026-09-15-pi-typed-result-p0-matrix.md`
@@ -1,6 +1,6 @@
 ---
 title: "Track P 协议实施（信封与 typed-result）"
-status: planned
+status: done
 created: 2026-09-15
 updated: 2026-09-15
 ---
@@ -9,24 +9,22 @@ updated: 2026-09-15

 ## 动机

-Phase 2 只要求 D8/D9 立项。H0/P0 盘点已完成；H1–H3 与 P1–P4 是全路由/前端/真实 PI 的独立实施轨道，不能并进事件 live。
+H0/P0 盘点后独立实施 HTTP 信封与 PI typed-result，不回退事件 live。

 ## 成功标准

-见：
+已关闭：

- [HTTP 信封整改](../../remediation/2026-09-15-http-error-envelope-remediation.md)
- [PI typed-result-v1](../../remediation/2026-09-15-pi-typed-result-v1-remediation.md)
- [H0 盘点](../research/2026-09-15-http-error-envelope-h0-inventory.md)
- [P0 矩阵](../research/2026-09-15-pi-typed-result-p0-matrix.md)
+- [HTTP 信封 H1–H3](../../test-reports/2026-09-15-http-error-envelope-h1-h3-test-report.md)
+- [PI typed-result P1–P4](../../test-reports/2026-09-15-pi-typed-result-v1-test-report.md)

 ## 依赖

-独立 mutex（server/web 与 pi-agent），不占用 events。
+mutex `server`/`web`/`pi-agent` 已释放。

 ## 暂不启动原因

-Phase 2 Definition of Done 不包含实现完成；H1 起会改公开 wire。
+已完成。

 ## 相关链接

@@ -5,7 +5,7 @@

 ## 焦点

-1. **TRACK-P**: HTTP 信封与 PI typed-result 实施（[long-term](./long-term/2026-09-15-track-p-protocol-implementation.md)）
+1. **TRACK-P**: HTTP 信封与 PI typed-result 已实施（[信封](../test-reports/2026-09-15-http-error-envelope-h1-h3-test-report.md)；[typed-result](../test-reports/2026-09-15-pi-typed-result-v1-test-report.md)）
 2. **TRACK-E LIVE**: 共享 consumer 已 live；生产 hook 已去注册（[projection](../test-reports/2026-09-15-event-projection-shared-live-test-report.md)）
 3. **CHAT-INTENT**: [对话意图运行时状态](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)（双标签 busy 已签：项目 **6275** / `DOC_BUSY` 单 run；不删 `sess-p143-u9` 探针）

@@ -71,6 +71,7 @@
 | Cursor | chatflow-orchestration-boundary | fix/chatflow-orchestration-boundary | - | chat | done |
 | Cursor | phase2-closeout-inventories | feature/phase2-closeout-inventories | - | architecture-docs | done |
 | Cursor | event-shared-live-cutover | feature/event-shared-live-cutover | - | events | done |
+| Cursor | pi-typed-result | feature/pi-typed-result | - | pi-agent | done |

 > 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。

@@ -82,7 +83,7 @@

 | holder | phase | since | scope | queue |
 |--------|-------|-------|-------|-------|
-| - | idle | - | - | - |
+| Cursor | smoke | 2026-09-15 | pi-typed-result (dev pi-agent restart + dual-track) | - |

 **phase**: `idle` | `merging` | `smoke` | `e2e`

@@ -1,6 +1,6 @@
 ---
 title: "PI Runner typed-result-v1 迁移方案"
-status: planned
+status: done
 created: 2026-09-15
 updated: 2026-09-15
 owner: Cursor
@@ -45,11 +45,11 @@ PI Runner 已有 HTTP/Bearer 传输边界，但结果仍兼容 stdout/result.jso

 ## 验收标准

- [ ] Schema/golden 在 Runner 与 Go 两侧共享并入 CI。
- [ ] typed-present-invalid 永不 fallback；handshake downgrade attack 负例通过。
- [ ] 并发 run/result 串线、cancel/result 竞争、超限与 path escape 负例通过。
- [ ] 真实 PI E2E 覆盖成功、typed error、取消、超时与未知 schema。
- [ ] legacy 删除前完成一个发布窗口对账和回滚演练。
+- [x] Schema/golden 在 Runner 与 Go 两侧共享并入 CI。
+- [x] typed-present-invalid 永不 fallback；handshake downgrade attack 负例通过。
+- [x] 并发 run/result 串线、cancel/result 竞争、超限与 path escape 负例通过。
+- [x] 真实 PI E2E 覆盖成功、typed error、取消、超时与未知 schema。
+- [x] legacy 删除前完成一个发布窗口对账和回滚演练。

 ## 相关链接

@@ -24,10 +24,10 @@
 | 文档治理 | 法定文档生命周期 + 租约 + 受控正文读取 | done | [test docgov](../test-reports/2026-09-08-docgov-lifecycle-and-claiming-framework-test-report.md)；[项目 143 正文 404 审计](../audit/2026-09-14-project143-controlled-content-404.md)；[受控正文真实 UI 验收报告](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；[UI-06 缓存竞争审计](../audit/2026-09-14-document-revision-refresh-cache-race.md)；[整改](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md) | 生命周期/租约保留。W1–W6 + 审查修补 + UI hydrate 资格 + 晚到 list sync 修复均已合入 dev。项目 143 纯 UI 回归（clean-run3）与新项目全链路（main + post-restart）已全量真实页面验证通过（PASS） | `docgov` |
 | 文档版本与修改认知 | 智能体版本边界、人工修订标记、任意版本比较、变更报告与负责人通知 | partial | [管理测试](../test-reports/2026-09-13-document-revision-management-test-report.md)；[运行时 UI Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md)；[运行时审计](../audit/2026-09-13-document-revision-runtime-404.md)；[ADR](../adr/2026-09-13-document-version-boundary.md) | **运行时 UI PASS**（6159 / V3/r2）。仍 `partial`：change report=`fallback`（真实 diff+lineage，非完整 PI 叙事）。系统级 `CHAT-INTENT` 见 gap-matrix | `docgov` |
 | 前端工作台 | 三栏 + 块文档 + SSE | partial | [test workbench](../test-reports/2026-09-08-three-column-workbench-and-block-document-test-report.md)；[现场专项审计](../audit/2026-09-13-conversation-intent-runtime-state.md)；[双标签截图](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/screenshots/tab-b-busy.png) | 错误卡片/任务进度/文档 busy 刷新恢复已有项目 6275 证据。前端人工抽检仍开放 | `web` |
-| PI Runner / 配置链 | pi-agent + MiniMax 真实链路 | done | [test piagent](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)；[container-env](../test-reports/2026-09-13-container-env-configuration-test-report.md) | — | `pi-agent` |
+| PI Runner / 配置链 | pi-agent + MiniMax 真实链路 + typed-result-v1 | done | [test piagent](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)；[container-env](../test-reports/2026-09-13-container-env-configuration-test-report.md)；[typed-result-v1](../test-reports/2026-09-15-pi-typed-result-v1-test-report.md) | — | `pi-agent` |
 | 三环境运维 | dev/test/main + 共享 KB | done | [PROJECT.md](../../PROJECT.md) §4；四环境 healthy | — | `infra` |
 | CI / E2E | PG 集成 + 真实 PI E2E | partial | [gap-matrix BUG-08](../remediation/gap-matrix.md)；[test pg-ci](../test-reports/2026-09-12-pg-ci-soak-e2e-test-report.md)；[运行时 UI Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) | CI `TEST_DATABASE_URL` 隔离库仍缺；文档运行时真实 UI 已按 UI_PHASE 分文件且 post-restart 断言最终 A1 正文。`-race` 全包并行 TempDir flake 为基建残留 | `ci` |
-| 模块解耦与可靠事件 | 文档可靠性纵向试点、PG 持久事件交付与选择性模块化 | partial | [架构](../system-design/2026-09-14-module-decoupling-architecture.md)；[ADR](../adr/2026-09-14-modular-monolith-decoupling.md)；[Phase 1](../remediation/2026-09-14-module-decoupling-refactor-plan.md)；[Phase 2 审阅](../audit/2026-09-15-module-decoupling-phase2-plan-review.md)；[Phase 2 修订计划](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)；[E0A](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md)；[E0B](../test-reports/2026-09-15-event-e0b-dispatcher-pg-test-report.md)；[E1A](../test-reports/2026-09-15-event-e1a-notify-cutover-test-report.md)；[E1B](../test-reports/2026-09-15-event-e1b-workflow-advance-test-report.md)；[E1C](../test-reports/2026-09-15-event-e1c-projection-test-report.md)；[E2](../test-reports/2026-09-15-event-e2-hook-guard-test-report.md)；[复盘](../ops/research/2026-09-15-track-e-retrospective.md)；[D6](../test-reports/2026-09-15-doccontent-canonical-boundary-test-report.md)；[D7a](../test-reports/2026-09-15-intent-bizdev-boundary-test-report.md)；[D5](../test-reports/2026-09-15-stageflow-type-ownership-test-report.md)；[D4](../test-reports/2026-09-15-bizdev-locator-removal-test-report.md)；[D7b](../test-reports/2026-09-15-chatflow-orchestration-boundary-test-report.md)；[H0](../ops/research/2026-09-15-http-error-envelope-h0-inventory.md)；[P0](../ops/research/2026-09-15-pi-typed-result-p0-matrix.md)；[收口](../test-reports/2026-09-15-phase2-closeout-test-report.md)；[notify live](../test-reports/2026-09-15-event-notify-shared-live-test-report.md)；[advance live](../test-reports/2026-09-15-event-workflow-advance-shared-live-test-report.md)；[projection live](../test-reports/2026-09-15-event-projection-shared-live-test-report.md) | E0A–E2 与共享 live 已过；生产无 hook 注册。D4–D7b 已合入。FAV off。Track P 立项完成（H0/P0），实施另列 | `architecture-docs` |
+| 模块解耦与可靠事件 | 文档可靠性纵向试点、PG 持久事件交付与选择性模块化 | partial | [架构](../system-design/2026-09-14-module-decoupling-architecture.md)；[ADR](../adr/2026-09-14-modular-monolith-decoupling.md)；[Phase 1](../remediation/2026-09-14-module-decoupling-refactor-plan.md)；[Phase 2 审阅](../audit/2026-09-15-module-decoupling-phase2-plan-review.md)；[Phase 2 修订计划](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)；[E0A](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md)；[E0B](../test-reports/2026-09-15-event-e0b-dispatcher-pg-test-report.md)；[E1A](../test-reports/2026-09-15-event-e1a-notify-cutover-test-report.md)；[E1B](../test-reports/2026-09-15-event-e1b-workflow-advance-test-report.md)；[E1C](../test-reports/2026-09-15-event-e1c-projection-test-report.md)；[E2](../test-reports/2026-09-15-event-e2-hook-guard-test-report.md)；[复盘](../ops/research/2026-09-15-track-e-retrospective.md)；[D6](../test-reports/2026-09-15-doccontent-canonical-boundary-test-report.md)；[D7a](../test-reports/2026-09-15-intent-bizdev-boundary-test-report.md)；[D5](../test-reports/2026-09-15-stageflow-type-ownership-test-report.md)；[D4](../test-reports/2026-09-15-bizdev-locator-removal-test-report.md)；[D7b](../test-reports/2026-09-15-chatflow-orchestration-boundary-test-report.md)；[H0](../ops/research/2026-09-15-http-error-envelope-h0-inventory.md)；[P0](../ops/research/2026-09-15-pi-typed-result-p0-matrix.md)；[收口](../test-reports/2026-09-15-phase2-closeout-test-report.md)；[notify live](../test-reports/2026-09-15-event-notify-shared-live-test-report.md)；[advance live](../test-reports/2026-09-15-event-workflow-advance-shared-live-test-report.md)；[projection live](../test-reports/2026-09-15-event-projection-shared-live-test-report.md)；[HTTP 信封](../test-reports/2026-09-15-http-error-envelope-h1-h3-test-report.md)；[PI typed-result](../test-reports/2026-09-15-pi-typed-result-v1-test-report.md) | E0A–E2 与共享 live 已过；生产无 hook 注册。D4–D7b 已合入。FAV off。Track P H1–H3 / P1–P4 已实施 | `architecture-docs` |

 ---

@@ -0,0 +1,87 @@
+# PI Runner typed-result-v1 测试报告
+
+## 一、 测试背景 (Background)
+
+P0 确认 `/v1/run` 只有 `ok/patches/stderr`，没有共享 schema。typed 字段一旦出现但非法必须 fail closed；stderr 可能把路径或模型痕迹带进 `ErrorReason`。本波按 Track P P1–P4 落地 additive `result_v1`、Go typed-first parser、共享 dev 真实 Runner 双轨对账，并去掉隐式 legacy 与 stderr 落结果。
+
+## 二、 测试目标 (Test Objectives)
+
+- P1：`configs/schemas/pi-run-result-v1.json`；Runner additive 输出 `result_v1`，保留 `ok/patches`。
+- P2：Go typed-first；握手声明旧 Runner 才允许 legacy；typed-present-invalid 永不 fallback。
+- P3：`RUN_PI_E2E=1` 对真实 `127.0.0.1:18865` 覆盖成功/失败/取消/超时，并对账 `ok` 与 `result_v1`。
+- P4：结果与 `ErrorReason` 不再包含 stderr；缺 `result_v1` 且无 `runner_protocol=legacy` 则 fail closed。
+- 负例：digest/run mismatch、handshake 降级、路径逃逸、symlink、超限 member、未知 error_code。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|----|-----|
+| 分支 | `feature/pi-typed-result` |
+| OS | Linux |
+| Go | `go test -short ./...`；`go test -race -short ./internal/agent` |
+| Runner | `shuimu-pi-agent-dev` `:18865`；模型 `MiniMax-M2.7-highspeed` |
+| Node | `node --test deploy/pi-agent/result-v1.test.mjs` |
+| 架构门 | `./scripts/arch-check.sh --mode block` |
+
+核心用例矩阵：schema/golden；typed 成功；digest 篡改；run_id 串线；handshake 降级；显式 legacy；空 prompt 失败双轨；1ms 超时双轨；`/v1/cancel`；真实成功写 `output.md`。
+
+## 四、 预期结果 (Expected Results)
+
+- typed 合法：`result_v1.schema_version=1`，member digest 与 patch 正文一致，Go `DecodeRemoteRun` 成功。
+- typed 非法或握手撒谎：返回 `typed result rejected`，不落盘 `output.md`。
+- 真实失败：`ok=false` 且 `result_v1.outcome=error`、`error_code` 在 allowlist。
+- 公开 JSON 无 `stderr` 字段。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 Schema / golden / Node
+
+- **测试输入 (Input)**：`TestGoldenResultV1Fixture`；`TestMembersDigestMatchesNodeCanonicalJSON`；`node --test deploy/pi-agent/result-v1.test.mjs`
+- **实际输出 (Actual Output)**：Go digest 与 Node `membersDigest` 一致；stderr 被 `withResultV1` 删除；`../` 与绝对路径 member 被省略。
+- **评价判定 (Evaluation / Verdict)**：**PASS**
+- **性能与耗时 (Duration & Latency)**：Node 50ms；Go 夹具 <10ms
+
+### 5.2 Go typed-first 负例
+
+- **测试输入 (Input)**：`TestDecodeRemoteRun_*`、`TestPiAgentRemoteRunner_TypedTamperDoesNotWrite`、`TestMaterializeTargets_RejectsSymlinkEscape`
+- **实际输出 (Actual Output)**：`go test -count=1 -short ./internal/agent` → `ok`
+- **评价判定 (Evaluation / Verdict)**：**PASS**（篡改 digest / 缺 result_v1 / 能力声明降级均 fail closed，未写 `output.md`）
+- **性能与耗时 (Duration & Latency)**：3.1s（含 httptest）
+
+### 5.3 真实 PI 双轨（P3）
+
+- **测试输入 (Input)**：`RUN_PI_E2E=1 go test ./internal/agent -run TestPiAgentTypedResult_LiveDualTrack -timeout 15m -v`
+- **实际输出 (Actual Output)**：
+
+```
+--- PASS: TestPiAgentTypedResult_LiveDualTrack (3.73s)
+    --- PASS: .../failure_empty_prompt (0.00s)
+    --- PASS: .../timeout (0.01s)
+    --- PASS: .../cancel (0.30s)
+    --- PASS: .../success (3.42s)
+```
+
+空 prompt 产物见 [live-empty-prompt.json](./assets/2026-09-15-pi-typed-result-v1/live-empty-prompt.json)：`ok=false`，`result_v1.error_code=PROMPT_EMPTY`。超时产物见 [live-timeout.json](./assets/2026-09-15-pi-typed-result-v1/live-timeout.json)：`error_code=TIMEOUT`。两份 JSON 均无 `stderr`。
+- **评价判定 (Evaluation / Verdict)**：**PASS**
+- **性能与耗时 (Duration & Latency)**：全套 3.73s（成功路径 3.42s，真实 MiniMax-M2.7-highspeed）
+
+### 5.4 回归门
+
+- **测试输入 (Input)**：`go vet ./...`；`go test -short ./...`（已 unset `.env` 注入）；`go test -race -short ./internal/agent`；`./scripts/arch-check.sh --mode block`
+- **实际输出 (Actual Output)**：vet PASS；short 全绿；race `ok internal/agent`；arch-check `production gate passed`（为 `httpx` 补了 allowlist）
+- **评价判定 (Evaluation / Verdict)**：**PASS**
+- **性能与耗时 (Duration & Latency)**：short 约 11s
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+`go test -short ./...` 全包 PASS。目标包 `go test -race -short ./internal/agent` PASS。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+P1–P4 达到合入标准。生产远程路径默认要求 `result_v1`；回滚窗口仅接受显式 `runner_protocol=legacy`（Go 仍解析 `ok/patches` 作为正文运输，不把 stderr 写入 `ErrorReason`）。
+
+**前滚**：dev 已挂载 `result-v1.mjs`；合入后重建 app 使 HTTP 服务使用 typed parser。
+
+**回滚**：恢复旧 `runner.mjs` 或临时让 Runner 返回 `runner_protocol=legacy` 且省略 `result_v1`；不要在 typed 字段非法时 fallback。
+
+不启用 FAV；不改 test/main consumer mode；项目 143 未写入。
@@ -0,0 +1,19 @@
+{
+  "ok": false,
+  "run_id": "e2e-empty",
+  "fallback_reason": "prompt_empty",
+  "patches": [],
+  "capabilities": {
+    "typed_result": true
+  },
+  "runner_protocol": "typed-v1",
+  "result_v1": {
+    "schema_version": 1,
+    "run_id": "e2e-empty",
+    "outcome": "error",
+    "retryable": false,
+    "error_code": "PROMPT_EMPTY",
+    "members": [],
+    "content_digest": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945"
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "ok": false,
+  "agent_id": "",
+  "run_id": "e2e-timeout",
+  "retryable": false,
+  "fallback_reason": "Execution timed out after 1ms",
+  "patches": [],
+  "capabilities": {
+    "typed_result": true
+  },
+  "runner_protocol": "typed-v1",
+  "result_v1": {
+    "schema_version": 1,
+    "run_id": "e2e-timeout",
+    "outcome": "error",
+    "retryable": false,
+    "error_code": "TIMEOUT",
+    "members": [],
+    "content_digest": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945"
+  }
+}