# 审计系统：先从一份已经返回的答案开始

这不是审计表结构手册，而是一页渐进式入门导读。

第一次阅读时，不需要记 `diagnosis_run`、`agent_step` 或事件类型。先回答一个问题：**系统已经给出了诊断答案，为什么还需要审计？**

## 1. 如果只有答案和日志，会发生什么

假设用户收到一份“数据库连接池可能耗尽”的诊断报告。业务日志也显示 Agent 和 Tool 都执行成功。

但系统仍然无法直接证明：

- 报告是否属于本轮请求，而不是混入同一 Session 的上一轮数据；
- Agent 是否真的调用了它声称使用的 Tool；
- Tool 成功是否等于找到了证据；
- EvidenceGuard 和 SemanticGuard 是否真正执行；
- 最终发布结果与 Run 终态、SSE outcome 是否一致；
- Router、Agent 和 Guard 的 Token 能否与总数对上。

这些不是“多打印几行日志”就能稳定解决的问题。它们需要明确的执行身份、决策类型、顺序和关联关系。

## 2. 审计在一次请求中做了什么

```mermaid
flowchart LR
    Q["一次诊断请求"] --> R["建立 exact Run<br/>固定本轮身份"]
    R --> D["在原始决策点记录<br/>Router / Agent / Tool / Guard / Release"]
    D --> S["Run、Timeline、Step、Tool<br/>分别保存各自事实"]
    S --> T["Trace 聚合回放<br/>计数与 Token 对账"]
    T --> A["回答答案为何产生<br/>也诚实暴露审计缺口"]
```

顺着这条线，审计只做三类事情：

1. **固定身份**：用 `runId` 把一次执行与多轮 Session 分开。
2. **记录决定**：让真正做决定的组件留下有类型、有顺序的结构化事实。
3. **聚合对账**：从最终结果倒推 Timeline、Agent Step、Tool 和 Token，检查它们是否一致。

审计不会替 Agent 诊断，也不会替 Harness 决定能否发布。它负责让这些行为在事后可以被准确解释。

## 3. 先建立这个最小心智模型

```mermaid
flowchart TB
    EXEC["一次 Agent 执行"] --> RUN["Run<br/>结果封面"]
    EXEC --> TL["Timeline<br/>决策脊柱"]
    EXEC --> DETAIL["Step / Tool<br/>行为明细"]
    EXEC --> SENSITIVE["Reasoning<br/>独立敏感审计面"]

    RUN --> TRACE["普通 Trace"]
    TL --> TRACE
    DETAIL --> TRACE
    SENSITIVE -.-> RTRACE["独立受限查询"]
```

第一次阅读只需要记住：

> Run 告诉我们结果，Timeline 告诉我们决定怎样发生，Step 和 Tool 告诉我们模型与外部世界实际做过什么；它们通过 exact `runId` 组合成一条可回放的证据链。

到这里可以先停下，不需要继续记表名。

## 4. 推荐阅读顺序

```mermaid
flowchart LR
    START["先建立直觉"] --> CASE["01 真实 Run 案例<br/>审计怎样使用"]
    CASE --> DESIGN["02 审计主设计<br/>为什么这样设计"]
    DESIGN --> EVOLUTION["03 设计演进<br/>为什么变成现在这样"]
    EVOLUTION --> NEXT["后续专题<br/>数据模型、Token、Tool、Reasoning、失败"]
```

| 顺序 | 先回答的问题 | 阅读 |
|---|---|---|
| 01 | 拿到一份结果后，怎样从后向前回放整次执行？ | [从一次诊断 Run 看审计系统如何记录决策](从一次诊断Run看审计系统如何记录决策.md) |
| 02 | 为什么日志不够，为什么需要 exact Run、typed event 和分层数据？ | [审计系统设计：从调试日志到可回放的决策证据](审计系统设计-从调试日志到可回放的决策证据.md) |
| 03 | 这套设计经历了哪些真实问题，哪些阶段性方案后来被替换？ | [审计设计演进：从 Session Trace 到 Exact Run](审计设计演进-从SessionTrace到ExactRun.md) |

建议一次只读一篇。第一篇建立使用直觉，第二篇理解设计取舍，第三篇再理解这些边界如何被真实问题一步步推出来；数据表、完整事件类型和代码类名都不是第一次阅读的前置知识。

## 5. 遇到具体问题时再往下读

| 当你想知道 | 当前资料 |
|---|---|
| 一次 SUCCESS 诊断的业务链路、字段和真实数值 | [一次诊断全流程 E2E 导读](../diagnosis/一次诊断全流程-E2E导读.md) |
| Session、Run、Trace 和 Reasoning 当前生命周期 | [Session、Run 与 Trace 生命周期](../../architecture/session-trace-lifecycle.md) |
| exact Run 为什么出现，曾经发生过什么串线问题 | [Session-Run-Trace 隔离工程纪要](../diagnosis/Session-Run-Trace隔离-从串线到可回放.md) |
| 如何人工验收一条 Trace 是否完整和安全 | [Trace 检查清单](../../demo/trace-inspection-checklist.md) |

后续本目录会继续补充数据模型、Token、Tool、Reasoning、失败图谱和面试速查。它们会继续保持同样的渐进式结构，不要求从目录头到尾顺序阅读。

## 6. 与 Harness 文档的分工

- [Harness 入门](../harness/README.md)回答“如何让一次非确定性 Agent 执行受控并安全发布”。
- 审计文档回答“这些控制和决定如何被记录、回放和对账”。
- Harness 是执行控制边界，Audit 是决策证据边界；二者协作，但不是同一个职责。