96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# 审计系统：先从一份已经返回的答案开始
|
|
|
|
这不是审计表结构手册，而是一页渐进式入门导读。
|
|
|
|
第一次阅读时，不需要记 `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 是决策证据边界；二者协作，但不是同一个职责。
|