# Audit 模块需求文档

## 1. 模块定位

Audit 模块负责记录和展示 Agent 执行过程，是项目体现企业级能力的重要模块。

复试演示时，审计日志用于证明系统不是黑盒问答，而是可以追踪输入、检索、工具调用、模型输出和执行耗时。

## 2. 模块目标

- 记录每次 Agent 对话。
- 记录 RAG 检索片段。
- 记录工具调用详情。
- 记录模型输出和结构化结果。
- 提供审计日志列表和详情页。
- 支持按场景查看日志。

## 3. 职责边界

### 3.1 负责

- 审计日志数据模型。
- 日志写入服务。
- 日志列表页面。
- 日志详情页面。
- 工具调用记录展示。
- RAG 引用记录展示。

### 3.2 不负责

- 不执行 Agent。
- 不执行工具调用。
- 不执行 RAG 检索。
- 不参与模型生成。
- 不做复杂权限控制。

## 4. 数据模型需求

建议模型：`AgentAuditLog`

字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | int | 主键 |
| `scenario_id` | string | 场景 ID |
| `scenario_name` | string | 场景名称 |
| `user_input` | text | 用户输入 |
| `retrieved_chunks` | JSON | 检索片段 |
| `tool_calls` | JSON | 工具调用记录 |
| `structured_output` | JSON | 结构化输出 |
| `final_answer` | text | 最终回答 |
| `raw_output` | text | 模型原始输出 |
| `model_name` | string | 模型名称 |
| `latency_ms` | int | 执行耗时 |
| `status` | string | `success` / `failed` |
| `error_message` | text | 错误信息 |
| `created_at` | datetime | 创建时间 |

## 5. 日志写入需求

Audit 模块需要提供服务函数：

```text
create_audit_log(
  scenario_id,
  scenario_name,
  user_input,
  agent_result
) -> AgentAuditLog
```

写入规则：

- Agent 成功时，记录完整结果。
- Agent 失败时，也要记录用户输入、场景和错误信息。
- RAG 片段和工具调用使用 JSON 保存。
- 不记录 API Key 等敏感配置。

## 6. 页面需求

### 6.1 审计日志列表页

路径：`/audit/`

展示字段：

- 日志 ID。
- 场景名称。
- 用户输入摘要。
- 状态。
- 模型名称。
- 执行耗时。
- 创建时间。
- 详情入口。

### 6.2 审计日志详情页

路径：`/audit/<log_id>/`

展示内容：

- 用户输入。
- 最终回答。
- 结构化输出。
- RAG 检索片段。
- 工具调用记录。
- 模型名称。
- 执行耗时。
- 错误信息。

## 7. 检索片段展示需求

每个引用片段建议包含：

| 字段 | 说明 |
|---|---|
| `source` | 来源文件名 |
| `chunk_id` | 片段 ID |
| `content` | 片段内容 |
| `score` | 相似度分数 |

## 8. 工具调用展示需求

每次工具调用建议包含：

| 字段 | 说明 |
|---|---|
| `tool_name` | 工具名称 |
| `arguments` | 调用参数 |
| `result` | 工具结果 |
| `success` | 是否成功 |
| `error` | 错误信息 |

## 9. 验收标准

- 每次对话成功后都会生成审计日志。
- Agent 执行失败时也会生成失败日志。
- 审计列表可以查看所有日志。
- 审计详情可以查看用户输入、检索片段、工具调用和最终输出。
- 日志中不保存 API Key。
- 可以根据日志解释一次 Agent 输出的依据。