99 lines
7.2 KiB
Markdown
99 lines
7.2 KiB
Markdown
# 第 1 轮工作计划（轻量合并版）：证据链强关联扩展与 EvidenceItem 统一
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
把 `mes.dispatch`（P3）已实现的「确认令牌 + 排产版本证据 + 写前快照绑定、缺项拒绝」强校验，扩展到 `workflow.execute_confirmed` 覆盖的全部 P2/P3 动作，并统一证据链协议（证据引用 + 输入快照指纹 + 版本绑定）。本轮目标状态：矩阵 M1「证据链 v1」由 Partial 升为 Done（以黄金测试为准）。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：`mes.dispatch` 的 `stage_dispatch`/`apply_dispatch` 已强制绑定确认令牌、`schedule-version:<id>` 证据与写前快照（`test_mes.py` 覆盖缺项拒绝/版本替换拒绝/幂等）；database 审批后端（迁移 20260731_03 + InnoDB 校验）已收口（18 passed）。
|
||
- 当前缺口：`execute_confirmed` 覆盖 32 个 P2/P3 动作，26 处 `write_audit` 大多未携带 `beforeSnapshot` 与 `evidenceRefs`；执行端不校验 staging 时的世界指纹（漂移检测缺失）；版本绑定只对 mes.dispatch 生效。
|
||
- 本轮为什么现在做：完成度矩阵点名「下一步必须补…把强关联扩展到其余 P2/P3，并统一 EvidenceItem、输入快照和版本协议」，属 P0 批次验收出口。
|
||
- Workspace preflight：共享脏工作区（58 modified + ~40 untracked），无分支/无提交（沿用源会话约束）；确认路径基线 36 passed；GitNexus 索引 5703 symbols。
|
||
- 方向分析：Q1 推荐选项 A，目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
execute_confirmed（32 动作，26 审计缺字段，无漂移检测）
|
||
-> 统一证据协议：stage 记录 beforeFingerprint + evidenceRefs + beforeSnapshot
|
||
-> 执行前校验：漂移检测 + 版本证据绑定 + 前置快照存在性（fail closed）
|
||
-> 全部 P2/P3 审计事件携带 beforeSnapshot + evidenceRefs
|
||
-> 黄金测试（漂移/缺证据/版本替换拒绝）+ 全量回归
|
||
-> 矩阵 M1 证据链 v1 → Done
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（单模块域：harness/workflow/mes/测试；集成点唯一：确认执行路径）。
|
||
- 规模依据：核心改动集中在 `server/agent_core/harness.py`、`server/aps_domain/workflow.py`、`server/aps_domain/mes.py` + 新增黄金测试；风险评估 MEDIUM（execute_confirmed 5 个直接调用者，均为确认 API/测试）。
|
||
- 选择原因：源会话既定共享脏工作区无分支约束；改动耦合紧密，主 agent 实现 + 独立审计 agent 只读并行，避免共享工作区写冲突。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 证据链强关联扩展到其余 P2/P3 + 统一 EvidenceItem/输入快照/版本协议（选项 A）。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送，继续在共享脏工作区交付（沿用源会话约束，直到用户另行授权）。
|
||
- 决策 3（P1）：验证深度 = 聚焦确认路径测试 + 全量黄金回归（`python -m pytest tests/golden -q -p no:cacheprovider`）。
|
||
|
||
默认假设：
|
||
- 假设 1：`stage_confirmation` 无法拿到调用方世界时（测试假 store 未注册到 scoped cache），`beforeFingerprint` 记为 None 且跳过漂移强制，保证存量测试不破坏；生产路径身份/世界已加载时强制生效。
|
||
- 假设 2：版本绑定动作集合 = 参数含 `versionId` 且证据要求 `schedule-version:<versionId>` 的动作（schedule.publish / flex.reschedule / schedule.adjust.commit / flex.adjust.commit / rush.apply / mes.dispatch 等），以执行端声明为准。
|
||
- 假设 3：审计字段统一为 `beforeSnapshot`（写前 checkpoint pairId）+ `evidenceRefs`（pending 记录参数，缺省空列表）。
|
||
|
||
未决但不阻塞：MySQL 实机多主机断连/死锁故障注入（需外部环境，本轮不做）。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `harness.stage_confirmation`：记录 `beforeFingerprint`（世界指纹，已加载时）、`evidenceRefs`（显式或按 versionId 派生）、`beforeSnapshot`；新增 `world_fingerprint()` 工具与 `verify_pending_evidence()` 校验器（漂移/版本证据/快照存在性）。
|
||
- `workflow.execute_confirmed`：执行前统一证据校验（失败关闭 + DENIED 审计 + 无世界写入）；26 处 `write_audit` 补 `beforeSnapshot`/`evidenceRefs`。
|
||
- `mes.stage_dispatch`/`apply_dispatch`：对齐统一协议（保持现有强校验，接入公共校验器/字段命名）。
|
||
- 新增 `tests/golden/test_evidence_contract.py`：漂移拒绝、缺证据拒绝、版本替换拒绝、审计字段断言、代表性 P2 动作（schedule.publish/order.upsert）绑定。
|
||
- 文档：`docs/architecture/harness.md`、`docs/product/plan-completion-matrix.md`（M1 证据链 v1）、`docs/CHANGELOG.md`。
|
||
|
||
Out of scope:
|
||
- MySQL 实机/多主机/断连死锁注入；WORM 归档；审批意见/委托/转派/批量；文件→DB 存量迁移（下一轮）。
|
||
- 任何分支、提交、推送、合并、清理用户改动。
|
||
|
||
## 6. 成功标准
|
||
|
||
- `python -m pytest -q tests/golden/test_evidence_contract.py tests/golden/test_harness_p3.py tests/golden/test_mes.py tests/golden/test_approval_database_store.py tests/golden/test_e2e_acceptance.py -p no:cacheprovider` 全部通过。
|
||
- 全量 `python -m pytest tests/golden -q -p no:cacheprovider` 通过（基线 397，预期 + 新增测试数）。
|
||
- `python -m ruff check` 改动文件干净。
|
||
- `git status` 仅新增预期文件/修改（无提交、无推送）。
|
||
|
||
## 7. 验证方式
|
||
|
||
- 聚焦：`python -m pytest -q tests/golden/test_evidence_contract.py -p no:cacheprovider`
|
||
- 回归：确认路径 36+、全量黄金套件。
|
||
- 静态：`python -m ruff check` 改动文件。
|
||
- 范围：`git diff --stat` 核对仅本轮文件。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| 漂移检测误伤存量确认流程 | 存量测试/API 回归 | beforeFingerprint 仅在 scoped store 已加载时强制；聚焦+全量回归 |
|
||
| execute_confirmed MEDIUM 风险（5 直接调用者） | 确认 API 行为变化 | 校验失败关闭路径只拒绝「漂移/缺证据/版本替换」，正常路径行为不变 |
|
||
| 共享脏工作区并发写冲突 | 文件互相覆盖 | 主 agent 实现；审计 agent 只读并行 |
|
||
| 版本绑定动作集合判定偏差 | 该强校验覆盖不全 | 校验器以参数声明为准 + 黄金测试固定代表性动作 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试出现非本轮相关回归且无法快速定位时，暂停并报告。
|
||
- 审计 agent 发现 blocking findings 且修复需要产品决策时，暂停询问用户。
|
||
- 任何需要提交/推送/合并/清理用户改动的操作，一律停下等待用户授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、审计、文档全部完成；聚焦与全量验证通过。
|
||
- 审计 findings 清零或全部修复并复验。
|
||
- 矩阵与 CHANGELOG 回写完成；`git status` 无意外改动；不提交、不合并（等待用户对合并/提交的授权）。
|
||
- 收口：向用户报告主要结论、关键洞察、需要特别留意的地方；询问是否提交/合并（普通模式门）。
|
||
|
||
## 11. 下一步
|
||
|
||
本计划为轻量合并版：主 agent 实现 + 独立审计 agent 并行只读审查 + 主 agent 集成验证 + 收口报告。目标续跑轮授权直接进入实施。
|