对话模块需求文档

1. 模块定位

Chat 模块负责 Agent 对话页面和用户交互，是复试演示时最核心的入口。

该模块接收用户问题，加载场景配置，调用 Agent Core 执行智能编排，并将结构化结果、引用来源、工具调用和审计信息展示给用户。

2. 模块目标

提供按场景进入的 Agent 对话页。
支持用户输入业务问题。
调用 Agent Core 执行完整 Agent 流程。
展示结构化输出。
展示 RAG 引用片段。
展示工具调用记录。
触发审计日志写入。

3. 职责边界

3.1 负责

对话页面渲染。
表单接收和校验。
当前场景上下文传递。
调用 Agent Core。
展示 Agent 返回结果。

3.2 不负责

不直接读取 YAML 场景文件。
不直接执行 RAG 检索。
不直接执行工具函数。
不直接调用大模型 API。
不直接写复杂审计细节。

4. 页面需求

4.1 Agent 对话页

路径：/chat/<scenario_id>/

页面区域：

当前场景摘要。
当前场景下已入库文档多选框。
用户问题输入框。
提交按钮。
Agent 结构化输出区域。
引用来源区域。
工具调用区域。
执行耗时区域。
审计日志详情入口。

5. 表单需求

用户输入表单字段：

字段	类型	必填	说明
`message`	textarea	是	用户业务问题
`document_ids`	list[int]	否	本次对话指定使用的已入库文档

校验规则：

输入不能为空。
输入长度建议不超过 4000 字。
如果场景不存在，需要返回明确错误。
document_ids 只能包含当前场景下状态为 indexed 的文档。
未选择文档时，默认使用当前场景下全部已入库文档作为 RAG 范围。

6. Agent 执行流程

Chat 模块调用 Agent Core 的流程：

用户提交问题
  ↓
校验 scenario_id 和 message
  ↓
获取场景配置
  ↓
调用 `run_agent(scenario_config, user_input, options=None)`
  ↓
获取 AgentResult
  ↓
调用 Audit 模块记录日志
  ↓
渲染结果页面

7. AgentResult 展示需求

Agent Core 返回结果建议包含：

字段	说明
`answer`	自然语言回答
`structured_output`	结构化结果
`references`	RAG 引用来源
`tool_calls`	工具调用记录
`raw_output`	模型原始输出
`latency_ms`	执行耗时
`error`	错误信息

页面需要优先展示结构化结果。如果结构化解析失败，则展示自然语言回答和错误提示。

8. 错误处理需求

需要处理以下错误：

错误	页面行为
场景不存在	显示场景不存在
用户输入为空	显示表单错误
LLM API Key 缺失	显示模型配置缺失
RAG 检索失败	显示检索失败，但允许模型基于已有信息回答
工具调用失败	显示工具失败信息，并继续生成结果
结构化解析失败	展示原始回答，并提示结构化解析失败

9. 验收标准

可以从场景列表进入对话页。
可以提交问题并获得 Agent 输出。
页面能展示结构化结果。
页面能展示引用来源。
页面能展示工具调用记录。
执行失败时有可理解的错误提示。
每次对话都会产生审计日志。

3.3 KiB Raw Blame History