DEMO-AGENT/docs/设计文档/模块设计/5.审计模块详细设计.md

审计模块详细设计

1. 模块目标

Audit 模块记录 Agent 执行过程，使演示者能够解释一次输出的来源、工具调用和模型结果。它是系统从“普通问答页面”变成“可追踪业务 Agent”的关键。

2. 职责边界

负责：

• AgentAuditLog 模型。
• 审计写入服务。
• 审计列表页。
• 审计详情页。
• 敏感信息过滤。

不负责：

• 不执行 Agent。
• 不执行 RAG。
• 不执行工具。
• 不调用模型。

3. 数据模型设计

模型：AgentAuditLog

字段见 docs/设计文档/3.数据库设计.md。

JSON 字段默认值必须使用函数，例如 default=list、default=dict，避免多实例共享同一对象。

4. 日志写入流程

服务函数：

def create_audit_log(
    scenario_id: str,
    scenario_name: str,
    user_input: str,
    agent_result: AgentResult,
) -> AgentAuditLog:
    """将 AgentResult 映射为 AgentAuditLog，并在保存前做敏感信息脱敏。"""

写入映射：

• agent_result.references -> retrieved_chunks
• agent_result.tool_calls -> tool_calls
• agent_result.structured_output -> structured_output
• agent_result.answer -> final_answer
• agent_result.raw_output -> raw_output
• agent_result.model_name -> model_name
• agent_result.latency_ms -> latency_ms
• agent_result.status -> status
• agent_result.error -> error_message

5. 日志列表页设计

路径：/audit/

查询：

• 默认按创建时间倒序。
• V1 可不做分页，若日志较多再加 Django Paginator。

展示：

• ID。
• 场景名称。
• 用户输入前 80 字。
• 状态。
• 模型名。
• 耗时。
• 创建时间。
• 详情链接。

6. 日志详情页设计

路径：/audit/<log_id>/

展示：

• 基础信息。
• 用户输入。
• 最终回答。
• 结构化输出。
• RAG 检索片段。
• 工具调用。
• 原始输出。
• 错误信息。

JSON 可用格式化后的 <pre> 展示。

7. 敏感信息处理

不得保存：

• LLM_API_KEY
• 完整环境变量 dump
• 用户机器上的敏感绝对路径
• Docker secret 或 token

如错误信息来自异常对象，应在保存前做简单脱敏，至少替换 API Key 值。

8. 异常处理

异常	处理
AgentResult 字段缺失	使用默认空值
JSON 不可序列化	转为字符串或空对象
日志不存在	返回 404
写入失败	抛给 Chat，由 Chat 展示审计失败提示

9. 验收标准

• 每次对话成功后有审计日志。
• Agent 失败也有失败日志。
• 列表页可查看日志摘要。
• 详情页可查看输入、输出、引用和工具调用。
• 日志不包含 API Key。