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--，留 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）。