5.1 KiB

Raw Permalink Blame History

第 6 轮工作计划（轻量合并版）：审计独立介质锚定（AuditLedger）

更新日期：2026-08-01

1. 本轮目标

新增独立 append-only 审计账本：为世界状态内的审计事件生成外部锚定根（Merkle 式聚合哈希），写入独立介质（按租户/项目隔离的 JSONL 账本），并提供篡改检测与锚定校验；网关 /api/gov/audit 展示锚定状态、新增显式锚定端点；矩阵「审计 append-only 且可检测篡改 / 全审计」由 Partial 前进一步（独立介质 + 锚定证明）。

2. 背景和当前状态

当前已完成：write_audit 写世界内 auditEvents（append-only SHA-256 链），verify_audit_chain 可检测链内篡改（test_m2_state.py 覆盖）；门禁管理台 /api/gov/audit 展示链校验。
当前缺口：审计与业务库同存（world 内），无独立介质；无外部锚定根；业务进程可改世界内的 auditEvents 而不被外部证据揭穿。
本轮为什么现在做：矩阵 104/116 行 P0 剩余「审计与业务库职责分离；外部锚定；不可改删」；纯本地可验证。
Workspace preflight：第 5 轮收口（440 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
方向分析：Q1 推荐选项 B（审计独立介质锚定），目标续跑轮授权执行。

3. 本轮工作方向

世界内 auditEvents（链式哈希）
-> AuditLedger：audit_root(events) 聚合根 + 独立 JSONL 账本（按 tenant/world_key 隔离，append-only）
-> 网关：/api/gov/audit 返回 anchor 状态；POST /api/gov/audit/anchor 显式锚定
-> 前端 AuditView 展示锚定状态
-> 黄金测试：根确定性、锚定往返、篡改检测（改事件/删账本行）、隔离
-> 矩阵 104/116 行注记；CHANGELOG

4. 已确认决策

任务重量：

档位：轻型（新模块 audit_ledger + 网关端点 + 前端展示 + 黄金测试）。
规模依据：新增独立模块、不改 write_audit 链路、不引入循环依赖；风险 LOW。
选择原因：独立介质锚定是矩阵 P0 明确剩余项，最小可验证增量。

P0/P1 决策（按 Q1 推荐采纳）：

决策 1（P0）：本轮切片 = 审计独立介质锚定（选项 B）。
决策 2（P1）：不新建分支、不提交、不推送。
决策 3（P1）：验证深度 = 聚焦 audit_ledger 测试 + 全量黄金回归。

默认假设：

假设 1：锚定根 = SHA-256 聚合（对每个事件哈希按序做双哈希链聚合，形成单一 root；与 verify_audit_chain 互补）。
假设 2：账本文件放 server/data/audit-ledger/<tenant>/<world>.jsonl（append-only，每行 {eventId, root, count, at}）。
假设 3：显式锚定（用户/管理台触发），不自动 hook 每次写（避免 IO 侵入业务路径）；校验时若未锚定返回当前待锚定根。
假设 4：锚定文件损坏/缺失 → ok=false + 明确原因（可恢复：重新锚定会追加新行，历史行保留）。

未决但不阻塞：WORM 物理介质、Merkle 树完整实现、合规导出、异常告警（后续轮）。

5. 范围

In scope:

server/agent_core/audit_ledger.py（新）：audit_root(events)、AnchorLedger（append/verify/status，按 tenant/world_key 隔离路径）。
server/gateway/app.py：/api/gov/audit 返回 anchor 状态；新增 POST /api/gov/audit/anchor。
apps/web/src/gov/GovConsole.tsx：AuditView 展示锚定状态（根摘要/事件数/ok）。
apps/web/src/api/types.ts：AuditView 相关类型（ChainStatus 扩展或新增 anchor 字段）。
tests/golden/test_audit_ledger.py（新）：根确定性、锚定往返、篡改检测（改事件/删账本行/改根）、隔离。
文档：docs/architecture/harness.md、docs/product/plan-completion-matrix.md（104/116 行注记）、docs/CHANGELOG.md。

Out of scope:

WORM 物理介质、完整 Merkle 树、合规导出、异常告警、自动锚定 hook。
提交/推送/合并/清理用户改动。

6. 成功标准

聚焦：python -m pytest -q tests/golden/test_audit_ledger.py -p no:cacheprovider 通过（≥4 项）。
全量：python -m pytest tests/golden -q -p no:cacheprovider（固定 .venv）≥ 440。
ruff 干净；前端 tsc 通过；git diff --check 无空白错误。

7. 验证方式

audit_ledger 单测（根/往返/篡改/隔离）；网关锚定端点 API 测试；全量回归。

8. 关键风险

风险	影响	控制方式
锚定文件路径/权限问题	校验失败	目录懒创建、异常安全返回 ok=false+原因
根算法与链校验不一致	混淆	root 独立于链哈希，互补且文档说明
前端类型漂移	编译失败	同步 types.ts + tsc

9. 停止条件

全量黄金测试非本轮相关回归无法快速定位时暂停。
任何提交/推送/合并/清理操作停下等待授权。

10. 本轮完成定义

实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
收口：报告主要结论、关键洞察、需要特别留意的地方。

11. 下一步

轻量合并版：主 agent 实现 + 验证 + 收口报告。

5.1 KiB Raw Permalink Blame History Unescape Escape