92 lines
14 KiB
Markdown
92 lines
14 KiB
Markdown
# GOAL：Pi Agent 兜底能力 · P3 高风险场景与运维（多 agent 协同 · 第四轮）
|
||
|
||
> 本文件是本轮协同的唯一权威协调板。每位 agent 开工前必读；完成后在文末留言板交接。
|
||
> 已提交基线：3543208（P1）+ 967ae37（P2）+ poc 设施两轮。P2 S3 冒烟 16/16、注入攻击 21/21。
|
||
|
||
## 本轮目标（P3 出口标准）
|
||
|
||
按根目录《Pi-Agent兜底能力详细方案》§6 P3：S4（缺算法/策略的沙盒试排）/S6（外部集成故障补录与对账）/S7（现场运维诊断）三个高风险场景 + `agent.fallback.execute.highrisk`=P3 的白名单治理机制。
|
||
|
||
具体交付：
|
||
|
||
1. **P3 白名单机制**：`agent.fallback.execute.highrisk` 从"默认拒绝"升级为"白名单放行"——配置化的场景级白名单（文件化，类似 features.json 语义；**文件缺失/损坏 → 默认全拒 fail-closed**，与 fallback 开关的默认关语义对齐），每项放行本身登记为 P2 管理动作（改白名单要确认卡）；
|
||
2. **S4 缺算法沙盒试排**：Pi 在沙盒内生成/执行临时分析或试排脚本，产物为**草稿版本**（P1 语义，不写主干）；与既有 flex.schedule / scenario.compare 沙盒语义对齐；收益与风险边界在文档写明；
|
||
3. **S6 集成故障补录**：MES/WMS 接口故障时，Pi 辅助生成待补录清单/对账文件；补录写操作逐笔过确认卡（P2 既有机制）；外部系统恢复后的对账流程（读侧对账 P0 + 差异报告）；
|
||
4. **S7 运维诊断入口**：运维角色专属入口（与 auth 角色体系对齐；非运维角色物理不可见/不可用）；Pi 可读日志/配置诊断（只读 P1），改配置类动作走 highrisk 白名单 + 确认卡；全程审计可回放；
|
||
5. **角色门禁**：fallback 触发增加角色维度（设计员评估现状 auth/角色能力的复用面；普通用户/运维/管理员对 S4/S6/S7 的可见性矩阵）；
|
||
6. 黄金测试：白名单 fail-closed（缺失/损坏/越权场景）、S4 草稿不碰主干断言、S6 补录确认卡链路、S7 角色越权拒绝、P3 动作未入白名单默认拒绝——全部确定性；
|
||
7. 真实冒烟：S6 场景（模拟 MES 断连 → Pi 生成补录清单 → 确认卡 → 补录 → 恢复后对账报告）；S7 诊断场景只读部分；
|
||
8. 文档同轮：fallback.md P3 章节、harness.md 权力矩阵、CHANGELOG（FB-03 条目）。
|
||
|
||
## 硬约束（GOAL-P2 全部继承，追加）
|
||
|
||
- 不 git commit/push；改动最小化；Python 用 .venv\Scripts\python.exe；
|
||
- **P3 白名单语义必须 fail-closed**：任何配置问题 → 拒绝而非放行（与 features 的 fail-open 相反，与 fallback 默认关同理，要在设计里写清楚语义不混淆）；
|
||
- S4 产物只允许草稿语义：验证器要断言沙盒试排不产生主干写事件；
|
||
- S7 运维入口：角色判定复用 server/auth 既有身份体系，不新造权限模型；
|
||
- 黄金测试确定性（fake runner）；真实冒烟用临时 APS_HOME；
|
||
- 每轮结束统一等提交授权。
|
||
|
||
## 角色分工
|
||
|
||
| 角色 | 任务 | 输出 |
|
||
|------|------|------|
|
||
| Agent-L 设计员 | P3 文件级详细设计（白名单 schema/角色矩阵/三场景接线/测试矩阵/爆炸半径） | `poc/pi-fallback/P3-DESIGN.md` |
|
||
| Agent-M 实施员 | 按设计施工产品代码 + 黄金测试 | 代码 + `P3-IMPL-NOTES.md` |
|
||
| Agent-N 验证员 | 全量回归 + S6/S7 真实冒烟 + 白名单攻击复证 | `P3-VALIDATION.md` |
|
||
|
||
## 已知前置问题（设计中必须回答）
|
||
|
||
1. **角色体系现状**：server/auth 现有角色粒度是否足以表达"运维"？若无，最小扩展方案是什么（不新造权限模型）；
|
||
2. **S4 与既有沙盒的关系**：flex.simulate_due / scenario.compare 已是沙盒试排，Pi 兜底 S4 的增量价值边界在哪（避免重复造轮子——兜底应编排既有沙盒意图，而非自建试排引擎）；
|
||
3. **S6 对账的"恢复后"语义**：外部系统恢复是事件还是人工触发？对账报告的证据链怎么冻结；
|
||
4. **白名单粒度**：场景级（S4/S6/S7 整体开关）还是意图级（每个 highrisk 动作单独登记）？给出取舍。
|
||
|
||
## 协同留言板
|
||
|
||
（格式：`[角色] 时间 — 结论/交接物/给下一位的话`）
|
||
|
||
[Agent-L 设计员] 2026-09-03 — P3 文件级详细设计完成，交接物：`poc/pi-fallback/P3-DESIGN.md`（11 节 + 附录，§0 现状事实 15 条全部源码核实、§8 测试矩阵 21 例、§9 双冒烟脚本规格、§10 爆炸半径 rg 实测无 HIGH）。
|
||
|
||
**4 个前置问题的答案**（详见设计 §4.1/§5.1/§6.5/§2.3）：
|
||
1. **角色体系**：server/auth 现有粒度足够——roles 是自由字符串元组（JMS 透传），审批角色有 action/power/全局三层 env 解析（APS_APPROVAL_ROLE_POLICIES 既有机制）；「运维」= 角色字符串 `ops`，最小扩展 = 纯配置零代码，server/auth 一行不改；「非运维物理不可见」落在 propose 闸 1.5（身份不符 → return None，与原话术同形态）。
|
||
2. **S4 与既有沙盒**：兜底不建试排引擎——S4 = Pi 编排既有沙盒意图（flex.simulate_due/flex.compare/scenario.compare/scenario.sensitivity，全 P0/P1 深拷贝沙盒），增量价值 = 意图自动组合 + 参数探索（临时脚本只作产物不执行，围墙无代码执行面）+ 草稿叙事；验证器用 world_fingerprint 前后相等（auditEvents 等 append-only 键已被指纹排除）+ 零 WORLD_WRITE 审计断言「草稿不碰主干」。
|
||
3. **S6 恢复语义**：人工触发，不是事件——用户明示后编排器 probe readiness，connected 才进对账协议（不轮询、不后台监听，现状无告警子系统也不造）；证据链三层冻结 = 外部响应原文落盘 sha256 → manifest 汇总指纹 → 指纹进 ALGO_RUN 审计 rationale，对账纯读 P0，差异处置回到逐笔卡。
|
||
4. **白名单粒度**：意图级为骨架 + 场景级为聚合开关 + 角色级第三维，三层同文件——纯场景级会把 S7 里不同权力动作一勺烩，纯意图级丢失场景归属会让意图被全局放行悄悄扩面。
|
||
|
||
**关键设计决策**（M 轮照此施工）：① 白名单 fail-closed 到「未知键即全文件判损坏」的强度（与 features.json 的 unknown 忽略相反，两文件两加载器语义隔离，互不 import）；② 白名单出卡/执行双端 sha256 比对，审批窗口内白名单变更 → 执行拒绝；③ P3 三场景只开放 frozen 步 + params 内联（吸收 K 轮教训：ASSISTED 真实模型未端到端验证、artifactRef 对真实 Pi 物理不可用）；④ S6 逐笔出卡 = 每项 backlog 一张独立 P2 卡（卡间无事务关联，符合补录语义），单轮上限白名单 maxItemsPerRun；⑤ 改白名单 = `agent.fallback.policy.update` P2 管理动作（Pi 只产 diff 声明，完整文档由编排器再生成），改配置 = `agent.fallback.ops.config.apply` P3（继承既有 requiredApprovals=2 + SOD + executionGrant 双人链，一行新机制不造）；⑥ S7 只读诊断不登记任何新工具——日志/配置脱敏后经 inbox 注入，Pi 仍只有 fs_read。
|
||
|
||
**风险最高点**：§10.1/10.2 双 MED——fallback_lane 计划锁闸口改造（validate_plan/check_step_request 硬拒改白名单裁决）与 execute_confirmed 两个写文件新分支（热路径）；均已给降级方案（frozen 直执 + checkpoint 前置保证最坏退化为一次显式失败且已回滚的确认；原子写 tmp+replace 无中间态），且 H-8 专项守护「白名单缺失时 P2 存量路径零影响」。
|
||
|
||
给 Agent-M 的话：照 §1 变更清单 12 项施工，§2.1 裁决表与 §8 测试矩阵是硬契约；三处易踩坑已在设计写明——新出卡路径必须照做指纹对齐（refresh_confirmation_world_fingerprint）与 contextPolicies setdefault（§0.14①②）；S6 多卡循环 stage 时每张卡都要独立走这套；脱敏函数失败归并不阻断（export_snapshot:791 先例）。施工前先复跑 P2 三目标文件 41 例确认基线绿。未 git commit，等统一授权。
|
||
|
||
[Agent-M 实施员] 2026-09-04 — P3 产品代码 + 黄金测试施工完成，交接物：`poc/pi-fallback/P3-IMPL-NOTES.md`（改动清单 11 文件、自验数字、9 条偏差如实登记、遗留清单）。
|
||
|
||
**自验数字**：新建 `test_fallback_highrisk.py` 21 例（H-1..H-21，§8 矩阵全覆写）**21 passed**；四文件联合（highrisk+execute+lane+feature_flags）**65 passed**（P2 存量 44 例零回归）；爆炸半径 19 文件 **195 passed**；ruff 与 HEAD 基线多重集比对 **59=59 零新增**（施工中的 9 条新增违规已全部修净复核）。文档三处同步（harness.md 矩阵+2 行+变更记录 / fallback.md P3 章节 / CHANGELOG FB-03 条目）。
|
||
|
||
**两条设计外增量（已在 IMPL-NOTES/CHANGELOG 登记，请 N 重点复证）**：⑦ harness `refresh_confirmation_world_fingerprint` 原实现推进指纹不重算信封哈希——S6 第二张及以后确认卡必现「完整性校验失败」，已修（P2 单卡未暴露是因为无身份绑定时指纹为空 refresh 空转）；⑧ S6 兄弟卡世界指纹重锚——首笔落账后同 run 其余待批卡冻结指纹推进+信封重算，否则漂移检测误杀，§6.3「逐笔互不影响」语义的落地必需。
|
||
|
||
**遗留（诚实标注）**：① S6/S7 两个冒烟脚本本轮未写，§9.1/§9.2 验收点 + smoke_s3_execute.py 手法可直接照做，CHANGELOG 数字已留「待 Agent-N 补实测」；② 分批全量黄金未复跑（只到爆炸半径切片 195 例）；③ MockMesClient 无 fetch_work_order/readiness，stub 下对账按 MISSING 如实呈现，真实 MES 链路待冒烟。
|
||
|
||
给 Agent-N 的话：除设计 §8 矩阵外，建议专项复证偏差⑦⑧的攻击面——伪造/篡改同 run 待批卡后重锚是否仍 fail-closed、非同 run 的世界改动在第二笔审批时是否仍被漂移检测拦下（H-8/H-20 已覆盖基础形态）。未 git commit，等统一授权。
|
||
|
||
[Agent-N 验证员] 2026-09-04 — 终验完成，交接物：`poc/pi-fallback/P3-VALIDATION.md`（全量回归/专项复证/双冒烟逐步证据/出口标准 8 项逐条/未验证清单）+ `tests/golden/test_fallback_p3_attack.py`（7 例攻击专项）+ `smoke/smoke_s6_reconcile.py` / `smoke/smoke_s7_ops.py`（五/四阶段可复跑）+ `regression_driver.py` 与两份回归结果 JSONL。**判定：P3 条件 NO-GO。**
|
||
|
||
**核心数字**：全量 golden 191 文件 **1501 passed / 18 failed / 10 errors**（stash 基线 9 文件逐例一致，全为既有失败：native sidecar 环境依赖 11 例 + folder_schedule 系列 6 例 + MES/HTTP fixture 8+2+4+2——与 P3 零相关）；文档门禁 **25 passed**；ruff M 的 8 文件 **59=59 零新增**复算一致；四文件联合 **65 passed**、含攻击专项五文件 **72 passed**。
|
||
|
||
**偏差⑦⑧专项 7/7 全过**：第二张卡信封完整+乱序双批、旧卡伪造/参数篡改/重放三态全拒、跨 run 卡不被重锚（漂移检测拦）、非兄弟改动借重锚混检被拦、伪造兄弟（篡改 runId 落盘）蹭重锚被 paramsHash 层物理拒。附带发现：审批仓 transaction 每次从盘刷新，纯内存篡改会被自动中和（信任方向正确）。
|
||
|
||
**S6 冒烟 19/24——抓到一个真实链路才摸得到的产品缺陷（FB-03-BUG-1，判 NO-GO 的唯一原因）**：段 C 补录写在真实断连下 100% 失败回滚——`mes.apply_report` 本地落账前无条件 `client.post_report()` 同步推 MES，断连注入（设计 §0.8 官方手法）下 MesHttpError 上抛 → execute_plan 整体回滚。golden 层 MockMesClient post_report 永远成功 + probe 走 monkeypatch seam，结构性摸不到。真实失败文案实测：「兜底执行失败（MesHttpError: [MES_HTTP_TIMEOUT] POST /work-orders/EXT-1001/reports (HTTP 504)），已自动回滚……你的数据未留下任何变更」。治理面在失败前全部正常（显式失败+回滚+失败现场建档+审计齐全）。其余全绿：断连注入 CONNECT_FAILED、真实 Pi 产 S6 两步计划（woId/进度与 CSV 一致）、逐笔双卡、恢复后假 MES（冒烟内嵌 HTTP 服务）对账 MATCH 1/DRIFT 1、manifest sha256 应验、ALGO_RUN 含 manifestSha256、对账纯读指纹相等、删白名单对照组零卡零变更、probe 仍 failed 如实回复「尚未恢复」（H-17 真实复证）。
|
||
|
||
**S7 冒烟 12/12 全过**：ops 身份四文件注入 + 预埋双形态敏感串脱敏实测（`***REDACTED***`、零泄漏）+ P1 草稿 + 世界零变更 + calls.jsonl 围墙内读取；非 ops（desktop planner）对照**物理不可见**实测（零 run、原话术）；验收点 D（双人链）由 H-20 确定性全覆盖已登记。
|
||
|
||
**给修复轮的话**：FB-03-BUG-1 是设计层语义决策（补录 = 本地落账 + 待同步标记恢复后闭环，还是同步推送容忍失败），非一行笔误，我按约束未动产品代码；修复后 `smoke_s6_reconcile.py` 五阶段全自动可复跑（outage 阶段 D3–D6/G1 转绿即解除 NO-GO）。环境层坑两个已在脚本内修复并登记：本机系统代理劫持 httpx 本地请求（NO_PROXY 修正）、Windows MAX_PATH 致 rmtree 失败（robocopy purge 兜底）。未 git commit，等统一授权。
|
||
|
||
[Agent-O 修复收口] 2026-09-04 — FB-03-BUG-1 已修复并复证，交接 `docs/CHANGELOG.md` 顶部条目 +
|
||
`tests/golden/test_fallback_offline_booking.py`（6 passed）+ `smoke_s6_reconcile.py` 复跑结果。
|
||
语义：S6 补录步 params 显式声明 `offlineBooking: true`，出卡闸与执行端双端实时探测断连事实，
|
||
双成立才走 `apply_report(offline_booking=True)` 本地落账并打 `syncStatus=PENDING_SYNC`；
|
||
在线路径默认参数不变；PENDING_SYNC 自动补推仍为后续轮次。确定性联合 78 passed、文档门禁
|
||
25 passed、ruff 零新增；真实 S6 冒烟复跑 24/24，段 C D3–D6/G1 全绿。**P3 判定转 GO**；
|
||
Agent-N 的 NO-GO 留言保留为修复前时序记录。P3/P4 代码均未提交，等统一授权。
|