4.6 KiB

Raw Permalink Blame History

第 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. 本轮工作方向

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 实现 + 验证 + 收口报告。

4.6 KiB Raw Permalink Blame History Unescape Escape