DEMO-AGENT/docs/需求分析/7.审计模块需求.md

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 模块需要提供服务函数：

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 输出的依据。