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