119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
# 对话模块详细设计
|
||
|
||
## 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 的细节实现。
|