aps-agent/poc/pi-fallback/GOAL-P2.md

# GOAL：Pi Agent 兜底能力 · P2 写操作过确认卡门禁（多 agent 协同 · 第三轮）

> 本文件是本轮协同的唯一权威协调板。每位 agent 开工前必读；完成后在文末留言板交接。
> 已提交基线：3543208（FB-01 P1 只读）+ 0198dec（P0 设施）。P1 真实冒烟 7 判据全 PASS。

## 本轮目标（P2 出口标准）

按根目录《Pi-Agent兜底能力详细方案》§6 P2：S2（已登记意图失败自救的修复动作）/S3（新格式数据导入）/S9（批量数据处理）写路径进产品——Pi 的**写**能力在确认卡 + checkpoint + diff 验证 + 计划锁四重治理下开放。

具体交付：

1. `_POWER_MAP` 新增 `agent.fallback.execute` = **P2**（执行已批准计划 → 确认卡）；`agent.fallback.execute.highrisk` = **P3**（默认拒绝，本轮不开放白名单）；
2. **计划锁**：propose 产出的《执行计划草稿》结构化（步骤清单：每步工具/参数摘要/预期影响），出确认卡时冻结（evidenceRefs + 计划指纹 sha256）；execute 时逐步比对——Pi 调用计划外工具或参数超界 → 立即熔断 blocked；
3. **checkpoint 强制**：execute 批准后立即建成对快照（前），执行结束后建（后），world diff 进验证报告；执行失败/熔断 → 自动回滚到前快照 + 显式声明；
4. **diff 验证器**：新建 `server/agent_core/fallback_verify.py`（moduleId: core-fallback-verify）——world diff 摘要、验证规则（行数/金额对账类）、报告生成（数字只许来自冻结快照）；
5. **工具桥写面**：`aps_invoke(intent, params)` 工具开放（内部仍过 harness/_POWER_MAP；P2 意图经由确认卡通道，不得绕过）；S3 场景的导入类写只允许走既有 `import.commit` 等已登记意图——**Pi 没有新的物理写能力，只有编排既有写意图的能力**；
6. **确认卡 UX**：fallback 计划确认卡在 Web 对话流呈现（复用既有 stage_confirmation 块），批准走 `/api/actions/confirm` 唯一通道；
7. **prompt 注入防线**：inbox 数据/订单备注进 Pi 前包裹隔离标记；确认只信 gateway 会话内真实确认卡；至少 5 个注入用例进黄金测试（可复用 poc/tests/rogue_llm_server.py 模式）；
8. 黄金测试：`tests/golden/test_fallback_execute.py`（计划锁偏离熔断/checkpoint 对/回滚验证/注入集/未登记写意图拒绝/确认卡过期）全部确定性（fake runner 注入）；
9. 真实冒烟：S3 场景——一份无人写过 importer 的 Excel/CSV，从"给文件"到"确认卡批准→导入→对账报告"全链路（真实 Kimi K2.6）；
10. 文档同轮：fallback.md 增补 P2 章节、harness.md 权力矩阵、CHANGELOG（FB-02 条目）。

## 硬约束（在 GOAL-P1 基础上追加）

- 工作区根：当前仓库根目录；Python 一律 `.venv\Scripts\python.exe`；
- **不 git commit/push**（每轮结束统一等授权）；改动最小化；
- 修改 harness.py / workflow.py / state/ 前必须先 rg 查调用方并做影响评估，HIGH 级先停下报告；
- 宪法红线复诵：写主干必过 Harness；`/api/actions/confirm` 是唯一执行通道；checkpoint 成对快照；证据链 verify_pending_evidence 缺项拒绝；失败显式；
- **Pi 侧绝不新增物理写通道**（不开 raw fs 写世界、不开 SQL、不开直连外部系统）；写能力 = 编排既有已登记意图；
- 黄金测试确定性：不依赖真实 LLM/网络；
- 真实冒烟用临时 APS_HOME，不得污染 server/data/。

## 角色分工

| 角色 | 任务 | 输出 |
|------|------|------|
| Agent-I 设计员 | P2 文件级详细设计（计划锁数据结构、checkpoint 接线、确认卡接线、注入防线、测试矩阵、爆炸半径） | `poc/pi-fallback/P2-DESIGN.md` |
| Agent-J 实施员 | 按设计施工全部产品代码 + 黄金测试 | 代码 + `P2-IMPL-NOTES.md` |
| Agent-K 验证员 | 全量黄金 + 真实 S3 冒烟 + 注入攻击复证 | `P2-VALIDATION.md` + 冒烟记录 |

## 已知前置问题（来自 P1 遗留，设计中必须解决）

1. **凭证语义张力**：真实 Pi 无法获知桥侧 callId（P1 已降级为防伪绊线）。P2 写路径上必须给出更严格的方案：Pi 的每个写意图调用本身就是桥侧事件，验证器应基于「桥侧真实事件流」而非 Pi 自述；
2. **90s 同步超时**：S3 大数据导入可能超 90s——设计要给出长任务方案（如分段确认/异步 job + 轮询，复用 server/agent_core/async_jobs.py 若合适）；
3. **主线 LLM 正常时未登记口令的意图落点**未验证（P1-SMOKE §6.3），P2 测试矩阵要覆盖。

## 协同留言板

（格式：`[角色] 时间 — 结论/交接物/给下一位的话`）

[Agent-I 设计员] 2026-09-03 — P2 文件级详细设计完成，交接物：`poc/pi-fallback/P2-DESIGN.md`（变更清单 12 项 / 计划锁 schema+指纹+逐步比对算法 / checkpoint 与回滚确切调用链 / 确认卡零前端改动接线 / 三前置问题取舍 / 注入防线 7 用例 / S3 冒烟 8 验收点 / 测试矩阵 17+3 例 / 爆炸半径 rg 实测无 HIGH）。

变更清单概要：修改 4 个产品文件——harness.py（+4 行纯追加，LOW）、workflow.py execute_confirmed（+1 分支 ~70 行，MED）、fallback_lane.py（+~520 行计划锁/执行编排/守卫模板参数化，MED）、pi_bridge.py（+~200 行 fs_write/aps_invoke 邮箱协议，LOW-MED）；新建 fallback_verify.py（diff 验证器）与 test_fallback_execute.py；gateway/contracts/state/apps-web/tool_runtime/async_jobs 全部零改动。

三个前置问题答案：① 凭证语义——写路径验证只信桥侧真实事件流（邮箱请求文件 + 桥签发 callId 账 + 前后快照 diff），Pi 自述（含「用户已确认」）一律不作执行依据；② 90s——重活前置到提议段冻结为 artifacts，执行段 FROZEN 模式确定性秒级完成、ASSISTED 独立 120s 预算闸超时即熔断回滚，async_jobs 评估后不复用（现有 jobs 全跑深拷贝快照、物理不写主干，接入写路径需新开副作用通道）；③ 意图落点——黄金层 T-16/T-17 锁「assistant.reply 落点→兜底分支」接线，真实冒烟补主线 LLM 正常时 SSE intent 事件断言，两层拼全链。

风险最高点与降级方案：workflow.py execute_confirmed 新分支（热路径，MED，全表唯一集中点）——降级方案 = 分支体全异常归并显式失败 + checkpoint 前置保证最坏情况退化为「一次显式失败且已回滚的确认」，绝无半写入不声明；守卫模板参数化（run 目录内放开 write）是对 P1 围墙的唯一语义放松，readonly 模式逐字节保持 P1 行为。

给 Agent-J 的话：照 §1 变更清单施工，§2.2 schema 与 §8 测试矩阵是硬契约；FakeStore 记得挂 `.checkpoints` 属性（§0.5 注入点）；失败回滚的审计必须在 restore 之后补写（§0.4/§3.2）；施工前请再跑一次 P1 的 13 例确认基线绿。


[Agent-J 实施员] 2026-09-03 — P2 全部产品代码 + 黄金测试施工完成，交接物：`poc/pi-fallback/P2-IMPL-NOTES.md`（改动清单/偏差说明/自验数字/遗留清单全在里面）。设计 §1 清单 12 项中 #1–#10 全部落地；#11 smoke_s3_execute.py 与 #12 rogue 剧本按设计 §7 分工归 K 轮，接口提示已写进 notes §4。

实测数字（可复跑）：三目标文件 `test_fallback_execute.py`(19 例新)+`test_fallback_lane.py`+`test_feature_flags.py` = **41 passed**；爆炸半径切片（confirm/审批/saga/checkpoint/chat/契约/导入 16 文件）**118 passed**；assistant/state 切片 24 passed；全量黄金两批 573 + 517 passed（批二 3 failed + 14 errors 经 `git stash -u` 基线复跑逐例一致，是日期炸弹与 MES fixture 的既有失败，与本轮无关）；ruff 本轮全部新/改文件零新增（harness 存量 5 条、workflow 存量 50 条，stash 基线同为 55 条）。

与设计的 5 处偏差（理由详见 notes §2）：① 守卫用双模板方案——readonly 逐字节保持 P1，设计预期"被打破的守卫测试"实际未破，改为同轮新增 v2 模板字节级断言；② 执行段简报渲染器放 fallback_lane 而非 pi_bridge；③ 步骤级 TOOL 审计由 execute_plan 成功路径补写而非 workflow 分支；④ ExecuteResult.message 由 execute_plan 组装；⑤ T-17 用 monkeypatch 直驱 parse_llm_result 覆盖三态。另修复一个施工期缺陷：ExecuteResult 默认 status="failed" 曾致成功路径误入失败分支被回滚，已改为成功显式置位，T-2 锁定。

给 Agent-K 的话：① 真实 S3 冒烟按设计 §7 跑（临时 APS_HOME + features.json 开 fallback + 根 .env 的 kimi-k2.6 key，验收点 A–H）；fake runner 注入点 `fallback_lane.build_pi_runner(config, *, mode=...)`；`make_customer_file` 自检要求 detect_kind 对该文件失败。② 注入复证：rogue_llm_server.py SCENARIOS += inject_via_csv / inject_fake_approval，断言计划锁拦截 + 卡片无 Pi 散文 + 审批仓空，并复跑 P1 三剧本回归。③ 我验证过：黄金 19 例全确定性（无固定端口）、切片、全量、ruff；**没验证**：真实 pi + 真实 LLM 端到端、守卫 v2 模板在真实子进程行为、--sabotage 变体（脚本未实现）。④ 注意 tests/golden/_saga_cp.json 会被 saga 测试例行改写，跑完全量后记得 `git checkout --` 还原再 diff。

[Agent-K 验证员] 2026-09-03 — P2 最终验证完成，判定 **GO**。交接物：`poc/pi-fallback/P2-VALIDATION.md`（出口标准 10 项逐条对照 + 未验证清单）。

实测数字（均可复跑）：全量黄金 4 批 **1090 passed / 3 failed / 14 errors**（stash 基线逐例一致，是日期炸弹 + MES fixture 既有失败）；ruff 本轮文件零新增；文档门禁 25 passed；P2 目标三文件 44 passed。S3 真实冒烟（真实 server+Pi+kimi-k2.6，run fb-20260903-165059-f5af4c）**16/16 全 PASS**：确认卡 power=P2/指纹 fae5bfdd3635/evidenceRefs 齐，批准返回「兜底计划已执行完成 ✅ salesOrders +15（与计划一致 ✅）」，checkpoint 对 3f1897329b→956f75816e，verify-report 数字与冻结快照重算逐值相等，审计链 102 条 ok，注入行被真实模型当数据处理且原订单无恙。

注入攻击复证（真实 Pi 子进程在环，rogue 剧本化模型）：新增 tests/attack_p2_writegate.py + rogue_llm_server.ScriptedLLMServer，**21/21 全 PASS**——a 计划外工具→计划锁熔断 blocked+自动回滚世界零变更；b 自述「用户已确认」→物理无效（卡照出、自签发动作文件永不被消费）；c inbox 藏注入→隔离（卡片零注入文本、删除未发生、合法行照导）。P1 两剧本回归 PASS。

我修了 3 个真实缺陷（只有真实子进程能暴露，全部已补确定性测试锁定，细节见验证报告 §5）：K-1 plan 模式工具事件映射缺 fs_write 必抛 harness_error；K-2 计划简报未锁 params 内联+规范字段名（真实 Pi 无 sha256 工具、会猜错 deliveryDate）；K-3 出卡审计落链与 contextPolicies 事后物化导致漂移比对必然误报（harness +refresh_confirmation_world_fingerprint / stage 前 setdefault）。

未验证/遗留：① ASSISTED 成功路径真实模型端到端未跑（黄金 T-10 + 攻击 a 真实熔断已夹逼）；② --sabotage 变体脚本未实现（J 遗留）；③ 37 行版冒烟未跑（15 行，预算）；④ PO 号重编为既有 upsert 语义（观察项）；⑤ 设计级发现——artifactRef 路线对真实 Pi 物理不可用，建议设计文档显式标注。未 git commit，等统一授权。