# 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 启动路径清晰可执行。