88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
# 第 11 轮工作计划（轻量合并版）：统一 EvidenceItem 可追溯链
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
新增统一证据项模块 `server/agent_core/evidence.py`：提供 `EvidenceItem`（结构化证据记录）与 `trace_chain()`（把 run-id、算法版本、种子、知识版本、用户确认串成一条可复算链）工具；黄金测试证明输入包、算法版本、种子、知识版本与用户确认可串成一条链并可复算；矩阵 114 行「结论、动作、报告可追溯和可复算」剩余项（统一 EvidenceItem）落地。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：第 1 轮证据链 v1（确认路径 evidenceRefs/beforeSnapshot/beforeFingerprint）；`schedule-version:<id>` 版本证据协议；schedule_result 含 `evidenceRefs`（run-id）。
|
||
- 当前缺口：run-id、solverMeta、seed、knowledgeVersion 等分散在不同引擎/领域，无统一 EvidenceItem 结构与串链工具；「输入包、算法版本、种子、知识版本和用户确认可串成一条链」无自动化验证。
|
||
- 本轮为什么现在做：矩阵 114 行剩余验收「统一 EvidenceItem；输入包、算法版本、种子、知识版本和用户确认可串成一条链」；纯本地、与第 1 轮证据链自然衔接。
|
||
- Workspace preflight：第 10 轮收口（468 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
|
||
- 方向分析：Q1 推荐（可追溯链统一），目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
run-id/solverMeta/seed/knowledgeVersion 分散
|
||
-> evidence.py：EvidenceItem（kind/ref/version/inputsHash/seed/knowledgeVersion/runId/userConfirm）
|
||
-> trace_chain(run_id, ...)：规范化 JSON + 链哈希（可复算、可追溯）
|
||
-> 黄金测试：链确定性、元素变化断链、与 schedule-version 证据协议兼容
|
||
-> 矩阵 114 行注记；CHANGELOG
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（新模块 evidence.py + 黄金测试 + 文档）。
|
||
- 规模依据：独立模块，不改既有引擎/契约；风险 LOW。
|
||
- 选择原因：矩阵 114 行明确剩余项；统一证据协议是跨引擎可追溯的基础设施。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 统一 EvidenceItem 可追溯链。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送。
|
||
- 决策 3（P1）：验证深度 = 聚焦 evidence 测试 + 全量黄金回归。
|
||
|
||
默认假设：
|
||
- 假设 1：EvidenceItem 为结构化记录（dataclass），字段含 kind/ref/runId/version/engine/seed/knowledgeVersion/inputsHash/confirmId/note。
|
||
- 假设 2：trace_chain 输出 {items, chainHash}，chainHash = SHA256(规范化 JSON 串联)；任何元素变化断链。
|
||
- 假设 3：与既有 `schedule-version:<id>` 证据协议兼容（kind="schedule-version" 映射）。
|
||
|
||
未决但不阻塞：真实求解 run 接入 trace_chain（后续轮）；前端追溯 UI。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `server/agent_core/evidence.py`（新）：`EvidenceItem`（dataclass/构造）、`evidence_ref(kind, id)`、`trace_chain(items)`（规范化+链哈希）、`parse_evidence_ref()`。
|
||
- `tests/golden/test_evidence_item.py`（新）：构造/序列化、链确定性、元素变化断链、ref 解析、与 schedule-version 兼容。
|
||
- 文档：`docs/architecture/harness.md`、`docs/product/plan-completion-matrix.md`（114 行注记）、`docs/CHANGELOG.md`。
|
||
|
||
Out of scope:
|
||
- 各引擎实际写入 trace_chain、前端追溯 UI、WORM/加密。
|
||
- 提交/推送/合并/清理用户改动。
|
||
|
||
## 6. 成功标准
|
||
|
||
- 聚焦：`python -m pytest -q tests/golden/test_evidence_item.py -p no:cacheprovider` 通过（≥5 项）。
|
||
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 468。
|
||
- ruff 干净；git diff --check 无空白错误。
|
||
|
||
## 7. 验证方式
|
||
|
||
- evidence 单测（构造/链确定性/断链/ref 解析/兼容）；全量回归。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| 链哈希规范不一致 | 复算失败 | 固定 sort_keys+separators；测试锁定 |
|
||
| 与既有证据协议冲突 | 兼容性 | parse/format 复用 schedule-version 语法 |
|
||
| 类型漂移 | 契约不稳 | dataclass + 测试覆盖字段集合 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
||
- 任何提交/推送/合并/清理操作停下等待授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
|
||
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
||
|
||
## 11. 下一步
|
||
|
||
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|