170 lines
6.1 KiB
Markdown
170 lines
6.1 KiB
Markdown
# V1 功能设计文档
|
||
|
||
## 1. 功能设计目标
|
||
|
||
V1 的功能设计目标是让复试展示者在本地快速完成一个可讲解、可演示、可改题的 Agent Demo。系统不追求复杂平台能力，而是优先保证以下闭环稳定：
|
||
|
||
- 场景配置可选择。
|
||
- 文档可上传并入库。
|
||
- 用户可在场景下发起对话。
|
||
- Agent 可返回结构化结果、引用来源和工具调用记录。
|
||
- 每次成功或失败的对话都有审计记录。
|
||
- 本地和 Docker 均可启动。
|
||
|
||
## 2. 用户角色
|
||
|
||
V1 仅设计一个用户角色：Demo 操作者。
|
||
|
||
该角色负责启动系统、选择场景、上传材料、触发入库、发起对话、查看输出和审计日志。系统不在 V1 中区分管理员、审核员、普通用户等权限角色。
|
||
|
||
## 3. 核心业务流程
|
||
|
||
```text
|
||
启动系统
|
||
↓
|
||
查看 5 个预置场景
|
||
↓
|
||
选择场景
|
||
↓
|
||
上传题目材料
|
||
↓
|
||
触发知识库入库
|
||
↓
|
||
发起 Agent 对话
|
||
↓
|
||
查看结构化输出、引用和工具调用
|
||
↓
|
||
查看审计日志
|
||
```
|
||
|
||
任一环节失败时，页面应给出明确提示，并尽量保留用户已完成的上下文。
|
||
|
||
## 4. 场景选择流程
|
||
|
||
1. 首页调用 `apps.scenarios.services.list_scenarios()`。
|
||
2. 服务从 `configs/` 读取 YAML 场景配置。
|
||
3. 校验必填字段、工具名称和输出类型。
|
||
4. 页面展示场景名称、描述、适用题型、启用状态。
|
||
5. 用户点击进入 `/chat/<scenario_id>/`。
|
||
|
||
异常处理：
|
||
|
||
- 配置目录不存在：展示空状态和配置目录提示。
|
||
- 单个配置非法：不阻断其他配置，页面展示该配置错误。
|
||
- 场景不存在：跳转或渲染错误页，提示检查场景 ID。
|
||
|
||
## 5. 文件上传流程
|
||
|
||
1. 用户进入 `/documents/upload/`。
|
||
2. 页面加载可用场景下拉框。
|
||
3. 用户选择场景并上传 `.txt`、`.md`、`.pdf` 或 `.docx` 文件。
|
||
4. Documents 模块校验文件类型和大小。
|
||
5. 保存文件到 `UPLOAD_ROOT/<scenario_id>/`。
|
||
6. 写入 `UploadedDocument` 记录，状态为 `uploaded`。
|
||
7. 返回文件列表页并展示上传结果。
|
||
|
||
V1 文件上传默认手动入库，避免上传大文件时页面阻塞过久。
|
||
|
||
## 6. 文档入库流程
|
||
|
||
1. 用户在文件列表点击“入库”。
|
||
2. Documents 模块读取文件并抽取文本。
|
||
3. 调用 `agent_core.rag.ingest.ingest_document()`。
|
||
4. Agent Core 按固定长度切分文本。
|
||
5. 写入本地 Chroma collection。
|
||
6. 入库成功：更新状态为 `indexed`。
|
||
7. 入库失败：更新状态为 `failed`，保存错误信息。
|
||
|
||
文本为空、文件丢失、向量库不可写都应进入失败状态，不能让页面报 500。
|
||
|
||
## 7. Agent 对话流程
|
||
|
||
```text
|
||
用户提交问题
|
||
↓
|
||
Chat 表单校验
|
||
↓
|
||
Scenarios 加载场景配置
|
||
↓
|
||
Agent Core 执行 run_agent()
|
||
↓
|
||
RAG 按场景和可选文档范围检索知识片段
|
||
↓
|
||
工具系统执行可用工具
|
||
↓
|
||
LLM Provider 生成结果
|
||
↓
|
||
结构化输出解析
|
||
↓
|
||
Audit 写入日志
|
||
↓
|
||
Chat 页面展示结果
|
||
```
|
||
|
||
Chat 模块只负责请求处理和页面展示，不直接写 RAG、工具和模型调用细节。
|
||
|
||
## 8. RAG 检索流程
|
||
|
||
1. Orchestrator 读取场景配置中的 `rag.enabled`、`collection`、`top_k`。
|
||
2. 若启用 RAG，则调用 `agent_core.rag.retriever.retrieve()`。
|
||
3. 检索必须按 `scenario_id` 过滤，避免跨场景污染。
|
||
4. 如果用户在对话页选择了文档，则同时按 `document_ids` 过滤；未选择时使用当前场景全部已入库文档。
|
||
5. 返回片段内容、来源文件、chunk ID、分数。
|
||
6. 片段进入 Prompt，同时随 AgentResult 返回给页面和审计日志。
|
||
|
||
检索失败时，AgentResult 应记录错误或警告；若业务允许，可继续使用非 RAG 上下文回答。
|
||
|
||
## 9. 工具调用流程
|
||
|
||
1. 场景配置声明可用工具名称。
|
||
2. Orchestrator 从 Tool Registry 查询工具。
|
||
3. 对不可用工具记录失败，不中断整个流程。
|
||
4. 内置工具按统一参数和返回结构执行。
|
||
5. 工具结果进入 Prompt 或结构化输出上下文。
|
||
6. 所有工具调用写入 AgentResult 和审计日志。
|
||
|
||
V1 先采用“配置声明 + Orchestrator 决策”的轻量策略，不实现复杂多轮工具调用协议。
|
||
|
||
## 10. 审计日志流程
|
||
|
||
1. Chat 模块在 Agent Core 返回后调用 `apps.audit.services.create_audit_log()`。
|
||
2. 成功结果记录输入、输出、引用、工具调用、模型名和耗时。
|
||
3. 失败结果也记录场景、输入、错误信息和已产生的中间结果。
|
||
4. 日志中不得保存 `LLM_API_KEY`、环境变量完整内容或上传文件绝对敏感路径。
|
||
5. 审计列表展示摘要，详情页展示完整 JSON 片段。
|
||
|
||
## 11. 复试改题流程
|
||
|
||
1. 判断题目最接近的模板。
|
||
2. 复制 `configs/` 中相近 YAML。
|
||
3. 修改场景名称、角色、目标、指令和输出类型。
|
||
4. 上传题目文档并入库。
|
||
5. 如题目需要计算或查询，新增一个内置工具并在场景中声明。
|
||
6. 用 2 到 3 个问题验证输出和审计链路。
|
||
7. 演示时重点展示配置、知识库、工具调用、结构化结果和审计日志。
|
||
|
||
## 12. 异常处理流程
|
||
|
||
| 异常 | 处理方式 |
|
||
|---|---|
|
||
| 场景配置缺失 | 页面展示错误，保留返回首页入口 |
|
||
| 场景字段非法 | 标记非法配置，不影响其他场景 |
|
||
| 上传文件类型不支持 | 表单错误提示 |
|
||
| 文件读取失败 | 文档状态改为 `failed` |
|
||
| RAG 入库失败 | 记录错误信息并允许重试 |
|
||
| LLM 配置缺失 | AgentResult 返回失败，审计日志记录失败 |
|
||
| 工具调用失败 | 记录工具失败，流程尽量继续 |
|
||
| 结构化解析失败 | 展示原始输出并记录解析错误 |
|
||
|
||
## 13. V1 功能验收标准
|
||
|
||
- 首页可以展示 5 个预置场景。
|
||
- 场景配置来自 YAML 文件。
|
||
- 可以上传 `.txt`、`.md`、`.pdf` 和 `.docx` 文件。
|
||
- 文件可触发入库，并显示 `uploaded`、`indexed`、`failed` 状态。
|
||
- 可以进入任一场景对话页并提交问题。
|
||
- AgentResult 至少包含回答、结构化输出、引用、工具调用、耗时和状态。
|
||
- 成功和失败对话都能生成审计日志。
|
||
- 审计详情可以解释一次 Agent 输出的输入、依据和过程。
|
||
- 本地启动和 Docker 启动路径清晰可执行。
|