DEMO-AGENT/docs/需求分析/5.文档模块需求.md

文档模块需求文档

1. 模块定位

Documents 模块负责文件上传、文件管理、文本抽取和知识库入库入口。

该模块是复试题快速适配的关键模块。拿到题目材料后，用户需要能快速上传文档，并让 Agent 在对话中使用这些文档。

2. 模块目标

• 支持上传题目材料和知识库文件。
• 保存文件元数据。
• 支持按场景关联文件。
• 提供文档入库入口。
• 为 Agent Core 的 RAG 模块提供文件内容。

3. 职责边界

3.1 负责

• 文件上传页面。
• 文件保存。
• 文件元数据记录。
• 文件与场景关联。
• 文本抽取入口。
• 触发 RAG 入库。

3.2 不负责

• 不负责具体向量检索算法。
• 不负责 embedding 生成细节。
• 不负责 Agent 对话编排。
• 不负责模型回答。

4. 支持文件类型

V1 必须支持：

类型	扩展名	说明
文本文档	.txt	第一优先级，最稳定
Markdown	.md	适合准备知识库和规则
PDF	.pdf	复试常见材料格式，V1 抽取纯文本
Word	.docx	复试常见材料格式，V1 抽取段落文本

后续增强：

类型	扩展名	说明
Excel	.xlsx	后续可作为业务数据源或结构化表格导入

5. 数据模型需求

建议模型：UploadedDocument

字段：

字段	类型	说明
id	int	主键
scenario_id	string	关联场景 ID
original_name	string	原始文件名
file	FileField	Django FileField 相对路径，不保存用户本机绝对路径
file_type	string	文件类型
size	int	文件大小
status	string	uploaded / indexed / failed
error_message	text	入库失败原因
created_at	datetime	上传时间
updated_at	datetime	更新时间

6. 页面需求

6.1 文件上传页

路径：/documents/upload/

页面元素：

• 场景选择下拉框。
• 文件选择按钮。
• 上传按钮。
• 支持类型提示。
• 上传结果提示。

6.2 文件列表页

路径：/documents/

展示内容：

• 文件名。
• 所属场景。
• 文件类型。
• 文件大小。
• 入库状态。
• 上传时间。
• 入库按钮。

7. RAG 入库流程

用户上传文件后，可以手动触发入库。

流程：

1. 用户上传文件。
2. 系统保存文件和元数据。
3. 用户点击入库按钮。
4. Documents 模块读取文件文本。
5. 调用 agent_core.rag.ingest。
6. 入库成功后更新状态为 indexed。
7. 入库失败后更新状态为 failed 并保存错误信息。

8. 文本抽取需求

V1 文本抽取策略：

• .txt：按 UTF-8 读取，失败时尝试系统默认编码。
• .md：按 UTF-8 读取，保留标题和正文。
• .pdf：抽取纯文本，不要求 OCR、表格还原和复杂版式理解。
• .docx：抽取段落、标题和普通表格文本，不要求完整保留 Word 样式。

入库失败后的文档允许重新触发入库。重新入库前需要清理或覆盖同一 document_id 对应的旧 chunk，避免重复检索。

9. 验收标准

• 可以上传 .txt、.md、.pdf、.docx 文件。
• 上传后可以在文件列表看到记录。
• 文件可以关联到指定场景。
• 可以触发文件入库。
• 入库成功后状态变为 indexed。
• 入库失败时页面能显示失败原因。
• 入库失败的文档可以重新入库。