# 对话模块需求文档

## 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 的流程：

```text
用户提交问题
  ↓
校验 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 输出。
- 页面能展示结构化结果。
- 页面能展示引用来源。
- 页面能展示工具调用记录。
- 执行失败时有可理解的错误提示。
- 每次对话都会产生审计日志。