DEMO-AGENT/docs/设计文档/2.功能流程设计.md

V1 功能设计文档

1. 功能设计目标

V1 的功能设计目标是让复试展示者在本地快速完成一个可讲解、可演示、可改题的 Agent Demo。系统不追求复杂平台能力，而是优先保证以下闭环稳定：

• 场景配置可选择。
• 文档可上传并入库。
• 用户可在场景下发起对话。
• Agent 可返回结构化结果、引用来源和工具调用记录。
• 每次成功或失败的对话都有审计记录。
• 本地和 Docker 均可启动。

2. 用户角色

V1 仅设计一个用户角色：Demo 操作者。

该角色负责启动系统、选择场景、上传材料、触发入库、发起对话、查看输出和审计日志。系统不在 V1 中区分管理员、审核员、普通用户等权限角色。

3. 核心业务流程

启动系统
  ↓
查看 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 对话流程

用户提交问题
  ↓
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 启动路径清晰可执行。