130 lines
3.3 KiB
Markdown
130 lines
3.3 KiB
Markdown
# 对话模块需求文档
|
|
|
|
## 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 输出。
|
|
- 页面能展示结构化结果。
|
|
- 页面能展示引用来源。
|
|
- 页面能展示工具调用记录。
|
|
- 执行失败时有可理解的错误提示。
|
|
- 每次对话都会产生审计日志。
|