93 lines
5.1 KiB
Markdown
93 lines
5.1 KiB
Markdown
# 第 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. 本轮工作方向
|
||
|
||
```text
|
||
世界内 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 实现 + 验证 + 收口报告。
|