5.3 KiB

Raw Permalink Blame History

第 8 轮工作计划（轻量合并版）：审计事件独立介质镜像（AuditMirror）

更新日期：2026-08-01

1. 本轮目标

新增审计事件独立介质镜像：APS_AUDIT_MIRROR=1 启用时，write_audit 在写世界内 auditEvents 的同时，把每条审计事件同步追加到独立 append-only JSONL 镜像（按租户/项目隔离）；/api/gov/audit 优先读取镜像（事件以镜像为准），业务进程修改 world 无法抹掉独立介质证据；矩阵 116 行「审计 append-only 且可检测篡改」剩余项（业务进程不可改写历史事件/独立介质）前进一步。

2. 背景和当前状态

当前已完成：第 6 轮 AuditLedger 锚定根（篡改可检测，但审计事件本体仍只存 world 内）；verify_audit_chain 链式校验；write_audit 105 个调用点统一走同一函数。
当前缺口：审计事件只存世界内 auditEvents，业务进程改 world 可抹掉历史（虽会被锚定根揭穿，但证据本体缺失）；无独立介质事件副本。
本轮为什么现在做：矩阵 116 行剩余「业务进程也无法修改历史事件；独立介质」；本地可验证（显式启用 + tmp 目录）。
Workspace preflight：第 7 轮收口（451 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
方向分析：Q1 推荐选项 B（审计事件独立存储镜像），目标续跑轮授权执行。

3. 本轮工作方向

write_audit 只写 world auditEvents（105 调用点）
-> audit_mirror.py：AuditMirror append-only JSONL（按租户/项目隔离，原子追加）
-> write_audit 条件镜像（APS_AUDIT_MIRROR=1；失败不影响业务写）
-> /api/gov/audit 优先读镜像（有镜像以镜像为准，无镜像回退 world）
-> 黄金测试：镜像追加、改 world 不影响镜像、隔离、启用/禁用
-> 矩阵 116 行注记；CHANGELOG

4. 已确认决策

任务重量：

档位：轻型（audit_mirror 新模块 + write_audit 条件分支 + 网关读取优先 + 黄金测试）。
规模依据：调用点签名不变（0 处调用点改动）；改动集中在 audit.py（1 处定义）+ gateway（1 处读取）+ 新模块；风险 LOW。
选择原因：独立介质是矩阵 116 行明确剩余项；镜像方案避免 105 处签名重构。

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

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

默认假设：

假设 1：镜像默认关闭（APS_AUDIT_MIRROR=1 显式启用），避免侵入未配置环境与常规测试；生产启用由运维显式开启。
假设 2：镜像文件路径 APS_AUDIT_MIRROR_DIR 或 server/data/audit-mirror/<tenant>/<world>.jsonl；写入失败仅记日志不影响业务（镜像尽力而为，主证据仍在 world+锚定）。
假设 3：/api/gov/audit 有镜像时事件列表以镜像为准（且镜像计数≥world 时用镜像），否则回退 world（兼容旧数据）。
假设 4：镜像行 {event, mirroredAt} 保留完整事件 JSON，供链校验与锚定复用。

未决但不阻塞：镜像 WORM 介质/加密、自动清理策略、跨进程锁强化（后续轮）。

5. 范围

In scope:

server/agent_core/audit_mirror.py（新）：AuditMirror.append_event(event) / read_events() / count()，按租户/项目隔离。
server/agent_core/audit.py：write_audit 在返回前，若 APS_AUDIT_MIRROR=1 则调用镜像追加（try/except 容错）。
server/gateway/app.py：gov_audit 优先读镜像（镜像存在且非空时以镜像为事件源）。
tests/golden/test_audit_mirror.py（新）：镜像追加/读取、改 world 不影响镜像、租户隔离、启用/禁用开关、链校验仍可作用于镜像事件。
文档：docs/architecture/harness.md、docs/product/plan-completion-matrix.md（116 行注记）、docs/CHANGELOG.md。

Out of scope:

105 处调用点签名重构、WORM/加密、清理策略、跨进程锁强化。
提交/推送/合并/清理用户改动。

6. 成功标准

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

7. 验证方式

audit_mirror 单测（追加/读取/隔离/开关/篡改）；gov_audit 镜像优先 API 测试；全量回归。

8. 关键风险

风险	影响	控制方式
镜像写入失败影响业务	审计丢失但业务中断	try/except 容错，仅记日志
测试污染共享目录	断言漂移	tmp 目录 + 环境变量隔离
镜像与 world 不一致	读取歧义	gov_audit 有镜像以镜像为准 + 测试锁定

9. 停止条件

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

10. 本轮完成定义

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

11. 下一步

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

5.3 KiB Raw Permalink Blame History Unescape Escape