# 对话模块详细设计

## 1. 模块目标

Chat 模块负责复试演示中的主交互：用户选择场景后提交问题，系统展示 Agent 输出、引用、工具调用和审计入口。

## 2. 职责边界

负责：

- 对话页 GET/POST。
- 用户输入表单校验。
- 获取场景配置。
- 调用 Agent Core。
- 调用 Audit 服务写日志。
- 渲染 AgentResult。

不负责：

- 不直接读取 YAML。
- 不直接调用 LLM。
- 不直接执行 RAG 和工具。
- 不实现复杂多轮会话状态。

## 3. 页面设计

路径：`/chat/<scenario_id>/`

GET：

- 加载场景配置。
- 展示场景摘要。
- 加载当前场景下状态为 `indexed` 的文档列表。
- 展示空表单。

POST：

- 校验输入。
- 执行 Agent。
- 写审计。
- 展示结果和审计链接。

## 4. 表单设计

字段：

| 字段 | 类型 | 规则 |
|---|---|---|
| `message` | textarea | 必填，最大 4000 字 |
| `document_ids` | 多选 | 可选，只能选择当前场景下已入库文档 |

错误提示：

- 空输入：`请输入要咨询的问题。`
- 超长输入：`问题过长，请控制在 4000 字以内。`
- 文档不属于当前场景或未入库：`请选择当前场景下已入库的文档。`

## 5. Agent Core 调用流程

```python
scenario = get_scenario(scenario_id)
result = run_agent(
    scenario_config=scenario,
    user_input=form.cleaned_data["message"],
    options={"document_ids": form.cleaned_data.get("document_ids", [])}
)
```

Chat 只依赖 Agent Core 的统一返回对象，不关心内部是否使用 RAG、工具或真实模型。

未选择文档时，`document_ids` 传空列表或不传，由 Agent Core 默认使用当前场景全部已入库文档。

## 6. 结果展示设计

优先级：

1. 如果 `structured_output` 不为空，展示结构化 JSON 或字段化结果。
2. 展示 `answer`。
3. 展示 `references`。
4. 展示 `tool_calls`。
5. 展示 `latency_ms`、`model_name`、`status`。
6. 如果有 `error`，展示中文错误提示。

结构化解析失败时，页面仍展示 `raw_output` 或 `answer`。

## 7. 审计日志写入流程

Agent Core 返回后调用：

```python
audit_log = create_audit_log(
    scenario_id=scenario.id,
    scenario_name=scenario.name,
    user_input=message,
    agent_result=result,
)
```

如果 Agent Core 抛异常，Chat 应构造失败结果并继续写失败审计。

## 8. 异常处理

| 异常 | 处理 |
|---|---|
| 场景不存在 | 显示错误并返回首页入口 |
| 表单无效 | 留在页面并显示表单错误 |
| Agent Core 抛异常 | 构造 failed AgentResult，写审计 |
| 审计写入失败 | 页面提示审计失败，但展示 Agent 输出 |
| LLM 配置缺失 | 展示模型配置缺失 |

## 9. 验收标准

- 从首页可进入对话页。
- 可提交问题并渲染 AgentResult。
- 可选择本次对话使用的文档范围；未选择时默认使用当前场景全部已入库文档。
- 失败时有中文提示。
- 成功和失败都尽量写入审计。
- View 中没有 RAG、工具、LLM 的细节实现。