aps-agent/poc/pi-fallback/P3-IMPL-NOTES.md

# P3-IMPL-NOTES — 高风险场景 + 白名单治理（FB-03）实施交付记录

> Agent-M 实施员，2026-09-04。施工图：`poc/pi-fallback/P3-DESIGN.md`
> （§1 变更清单 12 项、§8 测试矩阵 21 例为硬契约）。未 git commit/push。

## 1. 改动文件清单

| 文件 | 形态 | 内容 |
| --- | --- | --- |
| `server/agent_core/fallback_highrisk.py` | 新建 ~430 行 | 白名单加载（fail-closed，每次现读不缓存；返回 {ok,error,grants,path,sha256,doc}）、`validate_whitelist_doc`（未知场景键/未知字段/未登记 intent → 整文件判损坏）、`check_scenario_step`（抛 HighriskDenied）、`identity_roles_match`（system 放行）、`validate_backlog_item`、`validate_features_config_doc`、`validate_config_apply_params(params, *, check_hashes=True)`、`apply_policy_diff`、`canonical_sha256`/`file_sha256`、`s6_max_items` |
| `server/agent_core/harness.py` | +~10 行 | `_POWER_MAP`/`_POLICY_DESC` 各 +2（`agent.fallback.policy.update`=P2、`agent.fallback.ops.config.apply`=P3）；**缺陷修复** `refresh_confirmation_world_fingerprint` 推进 beforeFingerprint 时同步重算 envelopeHash（见偏差⑦） |
| `server/agent_core/fallback_lane.py` | +~900/-14 行 | _PLAN_SCENARIOS 扩 7 场景；FALLBACK_P3_INTENTS 登记表；FallbackConfig +3 字段；validate_plan `world=None` 可选参 + P3 分支 `_validate_highrisk_step`（frozen-only、拒 artifactRef、S4 expected 只许 sandboxOutput、S6 逐项对账、S7 check_hashes=False）；check_step_request P3 白名单裁决；propose 闸 1.5（S4/S6/S7 信号归类 + 角色不符 return None 物理不可见）+ S6/S7 inbox 注入 + 三场景简报段；S6 逐笔独立卡 `_stage_s6_item_cards`（独立指纹 + 截断声明 + contextPolicies setdefault）/ S7 `_stage_s7_action_cards`（编排器再生成文档 + 机器填充指纹）/ S4 单卡 + 沙盒尾行 + whitelistSha256 入 params；execute_plan 闸 1.5 白名单双端 sha256 比对 + S4 沙盒分支（直调 flex.simulate_due/compare_sort_modes/compare_scenarios/run_sensitivity，输出落 outbox/sandbox-steps/，4.5 物理断言，成功走 _build_sandbox_report）+ **S6 兄弟卡重锚** `_reanchor_s6_sibling_cards`（见偏差⑧）；_STEP_APPLIERS += mes.report（`_apply_mes_report_step` 复用 mes.apply_report，track 默认 flex）；S6 段 D `_propose_s6_reconcile`（`_probe_mes_connectivity`/`_fetch_external_wo` 可 monkeypatch seam、`_reconcile_domain` 双来源并集、外部原文落 inbox/external/ + manifest + ALGO_RUN 审计、Pi 叙事失败降级机器摘要；probe≠ok →「尚未恢复」显式回复不建 run 目录） |
| `server/agent_core/fallback_verify.py` | +~120 行 | `verify_sandbox_no_main_writes`（前后指纹相等 + 执行区间零 WORLD_WRITE 审计双断言）、`reconcile_external`（MATCH/DRIFT/MISSING 三档，比对 status/progressPct/qtyDone，str() 比较）、`build_reconcile_report` |
| `server/integrations/pi_bridge.py` | +~280 行 | `export_integration_status`（inbox/integration-status.md + pending-sync.json）、`export_ops_diagnostics`（inbox/ops/ 四文件：logs-tail/config-snapshot/health/integrations，单文件失败归并占位）、`_redact_ops_line`（_OPS_SECRET_RE + _OPS_KEYISH_RE → ***REDACTED***）、_PLAN_TASK_TEMPLATE {p3_sections} 占位（空时与 P2 渲染逐字节一致）、render_plan_task_brief 加 p3_sections 参。TOOL_REGISTRY 五键未动 |
| `server/aps_domain/workflow.py` | +~150 行 | 顶部 `import json`/`from pathlib import Path`；`_atomic_write_json`（tmp+os.replace）/ `_backup_config_file`（.bak-<ts>-<rand>，留 5 份）；execute_confirmed +2 分支：policy.update（beforeSha256 漂移比对 → 冻结文档复验 → 原子写 + 回读校验 + 备份 → WORLD_WRITE 审计）与 ops.config.apply（consume_execution_grant → 漂移比对 → 原子写 + 回读 + 备份 → P3 审计含 grantId/approvals/前后 sha256）；两分支全异常归并显式失败 |
| `tests/golden/test_fallback_highrisk.py` | 新建 ~900 行 | 21 例 H-1..H-21（§8 矩阵全覆写）；fixture 隔离 APS_FALLBACK_DIR/APS_FEATURES_PATH/APS_FALLBACK_HIGHRISK_PATH + scoped 仓/checkpoint 注册表快照还原；FakeStore（+path 属性）；`_bind_personal_world` 注入；`_seed_s6_world`（track=fixed 使 world_diff 可见）/`_seed_mes_mirror`（MockMesClient 指 tmp，零仓库污染）；H-16/17 monkeypatch probe/fetch seam；H-18 角色不符 → None + 零 run 零审计；H-19 APS_HOME 埋 token 断言脱敏；H-20 双审批 SOD 全链；H-21 含漂移拒绝子案 |
| `tests/golden/test_fallback_execute.py` | 注释 ±3 行 | T-3 断言行注释指向 P3 白名单机制（「登记 ≠ 自动放行」）；断言零改动 |
| `docs/architecture/harness.md` | +3 行 | 权力矩阵 +2 行（policy.update/ops.config.apply）+ FB-03 变更记录行 |
| `docs/architecture/fallback.md` | +~65 行 | P3 章节：fail-closed 语义对照表、角色矩阵与不可见闸、三场景、审计回放、验证 |
| `docs/CHANGELOG.md` | +1 条目 | FB-03 条目（顶部） |

## 2. 自验数字（本轮实测）

- `test_fallback_highrisk.py`：**21 passed**（2.5s 量级，全确定性 fake runner）
- 四文件联合（highrisk + execute + lane + feature_flags）：**65 passed**
- 爆炸半径切片（confirm/审批/saga/checkpoint/chat/契约/导入 19 文件）：**195 passed**
- ruff：本轮 7 个新增/修改文件与 HEAD 基线按「文件+规则」多重集比对 **59 = 59，零新增**（施工过程中产生的 9 条新增违规——7×ISC004/1×I001/1×RUF100/RUF059×3——已全部修复后复核）
- `_saga_cp.json`：测试跑完 `git checkout --` 还原纪律已执行，工作区无残留改动

## 3. 与设计（P3-DESIGN）的偏差

1. **S6 补录结构化载体 = plan.json 的 steps**（计划锁指纹天然绑定），backlog.json 不作强制中间件——§6.3 backlog 校验语义由 `_validate_highrisk_step` 逐项世界对账承接。
2. **MockMesClient 实际没有 fetch_work_order/readiness**（§0.9 称同接口，源码核实没有）——`_fetch_external_wo` 用 getattr 防御，stub 下对账按 MISSING 如实呈现。
3. **S4 成功路径用 sandbox-report.md** 替代 verify-report（expected 只许 sandboxOutput，check_expectations 自然跳过）。
4. **S6 golden 用 track="fixed"**（world_diff 的 _DIFF_TABLES 不含 flexWorkOrders，未改该表以免动 P2 口径）。
5. **execute.highrisk 的 _POLICY_DESC 旧文案未改**（设计只批 +4 行；该键仍未开放，P3 场景走独立意图不经此键）。
6. **`validate_config_apply_params` 加 check_hashes 参**（K-3 教训：Pi 无 sha256 工具；出卡闸 check_hashes=False，指纹由编排器组装时机器再生成 + 复验）。
7. **【设计外缺陷修复】harness.refresh_confirmation_world_fingerprint 同步重算 envelopeHash**：原实现推进 beforeFingerprint 后信封投影变化而 envelopeHash 冻结，verify_confirmation_envelope 必判「完整性校验失败」——S6 多卡场景第二张及以后的卡 100% 必现（P2 单卡测试未暴露：无身份绑定时 beforeFingerprint=None，refresh 空转）。调用方仅 fallback_lane 三处出卡路径，全部受益，影响面 LOW。已在 harness.md 变更记录与 CHANGELOG 如实登记。
8. **【设计外增量机制】S6 兄弟卡世界指纹重锚** `_reanchor_s6_sibling_cards`：§6.3「逐笔独立审批、互不影响」语义的落地必需——第一笔落账改变世界指纹后，同 run 其余待批卡的冻结指纹不重锚则必被漂移检测误杀。重锚只推进同 runId、同 action 的待批记录并同步重算信封哈希；审批窗口内的**非兄弟**业务改动仍被下一笔的漂移检测正常拦截。尽力而为（异常安全返回 0），绝不反噬主执行。
9. **测试设施自重**（非产品偏差）：FakeStore +`path` 属性（get_checkpoints/get_plan_store 取目录用）；`_bind_personal_world` 把 FakeStore 注入 scoped 仓注册表（身份绑定后 worldKey=personal-{uid}，不注入则出卡指纹捕获/执行端解析/审计落链全部绕过测试仓）；autouse fixture 快照/还原 `_stores` 与 `_checkpoints` 注册表防跨测试泄漏。

## 4. 遗留与交接（给 Agent-N）

- **冒烟脚本未交付**：`poc/pi-fallback/smoke/smoke_s6_reconcile.py` 与 `smoke_s7_ops.py` 本轮时间耗尽未写——设计 §9.1/§9.2 验收点齐全，手法参考同目录 `smoke_s3_execute.py`（临时 APS_HOME、watcher 投件、单次执行内起杀 server）。要点：MES_HTTP_BASE_URL 指不可达端口造断连、reset_http_mes_client 恢复、对照组删白名单；S7 用 JMS_AUTH_DEFAULT_ROLE 或测试登录给 ops 角色。**CHANGELOG 验证数字已留「待 Agent-N 补实测」。**
- **分批全量黄金未复跑**：本轮只跑到爆炸半径切片（195 例）；全量两批回归属验证员职责，既有失败基线（test_preference_features 3 例日期炸弹、mes_http 等 14 errors）用 stash 基线对照法核实。
- **真实 MES 链路**：`_probe_mes_connectivity`/`_fetch_external_wo` 是 seam，stub 客户端下对账按 MISSING 呈现；真实 MES_HTTP 端到端对账需真实冒烟验证。
- **工作区非本轮改动**：`tests/golden/test_multimodal.py`（dxf_drawing 相关）曾出现在工作区，非 P3 范围，未触碰。
- 硬约束全程遵守：未 git commit/push；Python 一律 `.venv\Scripts\python.exe`；白名单 fail-closed；测试确定性（fake runner + monkeypatch seam，零网络零真 LLM）。