common_agent/设计文档/2.知识资产与文件解析模块设计.md

知识资产与文件解析模块设计

1. 领域模型

对象	职责
知识库	聚合文档、模型配置、检索配置和索引版本
知识文档	关联附件，维护解析和索引状态
解析快照	保存文本抽取结果，作为切片输入
知识切片	保存切片内容、序号、元数据和启用状态
切片向量	保存 Embedding 向量、模型名和维度
知识库模型配置	固定知识库 Embedding 模型和切片配置

2. 状态流转

文档解析状态：

UPLOADED -> PARSING -> PARSED，失败时进入 FAILED。

文档索引状态：

PENDING -> INDEXING -> INDEXED，失败时进入 FAILED。

切片策略继续使用整型枚举值，例如 1 表示固定长度，5 表示按分隔符。

3. 数据流

flowchart LR
    Upload["上传文件"] --> Attachment["sys_attachment"]
    Attachment --> Document["rag_document"]
    Document --> Parse["rag_document_parse_result"]
    Parse --> Chunk["rag_chunk"]
    Chunk --> Embedding["rag_chunk_embedding"]
    Embedding --> Retrieval["检索召回"]

4. 设计约束

• rag_document 只引用附件和知识库，不存储大段解析文本。
• 解析快照按文档唯一，重新解析时更新快照。
• rag_chunk_embedding 必须记录模型和维度，防止向量空间混用。
• 知识库模型配置由模型与路由模块维护，但知识资产模块负责消费。
• 检索配置要面向 Workflow 和 Agent 复用，不绑定某一个页面。