搭建读取上传文档、供AI智能体检索的系统

## 规范分支命名，并把API、worker和共享代码分开 在修改代码前明确责任归属，使每项行为都留在能够对其进行测试和维护的层中。 ### 使用可追溯的分支 - 按 `type/user/description pattern` 为分支命名。 - `type` 应保持小写，并选择公认的变更类别，例如 `feat`、`fix`、`refactor`、`chore`、`docs`、`test`、`perf`、`ci`、`build` 或 `revert`。 - `user` 应填写负责该工作的人员；绝不能用通用的智能体名称或工具名称代替。 - `description` 应简短、使用小写并采用 kebab-case。 ### 分离运行时职责 - 将同步API处理、异步文档工作、共享模型与服务以及部署相关事项分别放在不同的软件包中。 - 将端点编排、业务规则、持久化、解析、检索和通用工具放入责任归属明确的模块中；把独立分发的SDK视为独立产品。 - 当某项行为跨越多个软件包时，应先定义共享契约，再分别测试每个责任方的实现。 ## 把上传的文件交给适合其格式的解析器 采用分阶段流水线，让每份文档都沿着一条可见路径，从上传一直流转到可引用的检索证据。 1. 接收上传内容，创建作业，持久化源对象，并将异步工作加入队列。 2. 只对文档分析一次，再依据文件类型和结构证据将其路由至解析器。 3. 将解析器输出转换为一个类型化的表格契约。 4. 将各行转换为类型化分块记录。 5. 在检索前发布文档、节、分块和图的状态。 ### 明确解析器路由 - 为所有格式使用一个类型化解析器入口，并返回任务局部的制品路径。 - 按格式专用策略路由PDF、DOCX、PPTX、电子表格、Markdown、文本、图像和原始片段输入；旧版办公文件格式应先转换，再交给现代解析器。 - 对PDF，应区分开放式语义分类与仅用于路由的类别，例如图册、扫描件、幻灯片和通用类别。 - 对超大文档，只在入口执行一次结构剖析，再将生成的分片计划传递给下游。 - 解析后，移除未被引用的图像，并应用确定性的图像压缩。 ## 识别标题层级，并在转换时保留表格和图片 根据现有的最强证据判断结构，并在转换期间保留表格、图像和标题之间的关系。 ### 按证据顺序确定标题 1. 如果存在嵌入式目录，应将其作为事实依据。 2. 匹配明确的编号模式和特定语言的章节标记。 3. 只对尚未解决的候选标题使用LLM层级模型。 4. 对布局丰富的PDF，将字体几何特征聚类为数量受限的标题层级。 ### 保留格式特有的行为 - 按源顺序遍历DOCX正文元素，包括段落、表格、图像和目录区域。 - 维护标题栈；当新标题返回父级时，关闭其后代层级。 - 使用准确的 `rowspan` 和 `colspan` 将表格转换为HTML，并通过感知哈希去除重复图像。 - 将标准PDF路由至内容提取和Markdown解析；将图册型或超大文档路由至各自的专用路径。 - 为摘要、层级识别、图像描述、OCR和粗粒度分类分别使用独立的模型配置键。 ## 按固定格式保存分块、导航和清单文件 将已持久化的语料库视为权威来源；中间DataFrame只是暂时的实现细节。 ### 存储语料库与文档状态 - 在每份已摄取文档的独立目录旁保存语料库级图元数据和检索命中统计。 - 持久化有序分块、层级导航、解析元数据、完整标题树、已归档的源资产、提取出的图像与表格以及诊断输出。 - 只使用三种核心分块类型：`text`、`image` 和 `table`。 - 为每个分块提供确定性的 `chunk_id`、类型化内容、层级路径，以及长度、摘要、页码、令牌数、关键词、文件路径和跨分块引用等元数据。 ### 保留引用与导航 - 通过 `connect_to` 条目表示内联关系，其中包含 `target`、`relation`、`ref` 和以字符偏移量表示的 `position`。 - 对内联资产使用 `embeds`，对非内联关联使用 `related`。 - 将 `doc_nav.json` 构建为节树，其中包含摘要、分块数、子节点以及图像或表格资源。 - 构建 `manifest.json`，其中包含源元数据、统计信息和嵌套的 `HIERARCHY`。 - 在写入 `chunks.json` 前，将暂时的解析器行转换为类型化分块载荷。 ## 同步发布数据库记录、搜索索引和图关系 发布一个一致的修订版，使关系型记录、搜索通道和图边描述同一组分块。 ### 维护关系型数据的责任归属 - 在文档层存储文档标识、所有者、命名空间、状态、当前修订版和源文件名。 - 在能够识别修订版的节树中存储父级链接、路径、标题、级别、摘要和排序顺序。 - 按分块存储内容哈希、分块类型、可搜索文本、源路径、资产路径、元数据和排序顺序。 - 将图节点限定在文档范围内；当图边表示对称关联时，应使用无向边。 ### 按固定顺序发布 1. 按确定性内容哈希跨文档去除重复分块。 2. 从分块路径出发，按自顶向下的顺序构建祖先节。 3. 为每个分块分别生成内容、路径和原始词项搜索通道。 4. 只有在至少共享3个关键词且分数不低于0.8时，才创建文档图节点和关键词重叠边。 内容搜索使用经过分词的内容及摘要，路径搜索使用经过分词的文件名及节路径，子字符串搜索使用原始内容及路径。 ## 同时提供传统排序检索和有预算上限的智能体检索 按责任归属分离请求整形、词法搜索、水合、图访问、命中统计、工作流执行、导航和证据呈现。 ### 保留两种检索模式 - 在传统模式下，通过倒数排名融合来组合路径、内容和词项通道。 - 使用默认通道权重 `path=1.0`、`content=2.0` 和 `term=1.5`，并采用 `score = weight / (k + rank + 1)` 及 `k=60`。 - 在智能体式模式下，让规划器把复杂查询分解成由检索步骤组成的DAG；不得在检索内部规划答案合成步骤。 - 对完整DAG实施统一的令牌预算。预算耗尽时，应安全停止，并返回到目前为止收集到的最佳证据。 - 将发现、受约束的广度优先节导航和证据呈现作为不同阶段执行。 - 将 `evidence_text` 作为主要响应，并仅将已弃用的 `answer_text` 保留为空的兼容字段。 ### 有目的地进行水合与排序 - 将未打开的节呈现为由标题和摘要组成的大纲，并且只对选中的叶节点水合原始 `text`、`image` 和 `table` 分块。 - 以原生方式解析已连接的资产并将其内联嵌入，不使用脆弱的字符串替换占位符。 - 先按 `agent_score`、再按 `discovery_score` 对智能体结果排序；将 `agent_score=0` 的行降至后备池。 - 在组装前排除指定的文档和节，并且只保留允许的分块类型。 - 附加包含 `document_id`、`chunk_id`、`source_file_name` 和 `section_path` 的引用。 ## 让分块ID保持稳定，只缓存成功的结果 明确快捷路径、标识符、变更顺序和遥测信息，使优化不会改变检索语义。 ### 保持结果可复现 - 仅根据文本内容的稳定哈希生成分块ID，并排除图像和表格引用，使相同内容能够跨上传去重。 - 先规划DOM变更，再按相反顺序应用，以避免索引偏移。 - 使用感知哈希去除文档内相同图像的重复项，同时复用已缓存的元数据。 - 对出现在不同位置的重复图像赋予确定但唯一的ID，并在查找附近的文本上下文时跳过二进制标识符。 ### 限制快捷路径和缓存 - 当 `total_chunks <= top_k` 时，通过明确的小型语料库路径直接返回所有分块。 - 按用户、命名空间、查询、`top_k` 和筛选条件进行缓存；执行前验证缓存版本，并且只在成功后写入。 - 记录每个分块和每份文档的命中，用于提升排名，同时不更改源内容。 - 为智能体的操作、输入、输出、延迟和令牌用量保留仅追加的运行记录与步骤记录。 ## 处理LLM API的特殊之处，并在报告完成前本地验证 明确模型约束和本地验证命令，使故障始终可以诊断。 ### 加固模型集成 - `json` 一词必须包含在请求DeepSeek `json_object` 模式的内容中。 - 流式传输期间，只有在 `delta.content` 不为 `None` 时才进行拼接。 - 在每个令牌各自的速率限制内轮换API令牌，应用冷却期，并使用下一个可用令牌就地重试。 - 检索应只提供证据；下游智能体负责判断证据是否充分，并在检索服务之外合成答案。 ### 在本地验证系统 - 从版本已锁定的工作区安装，在本地复制环境模板，并启动所需的数据库、缓存、对象存储、API和工作进程服务。 - 提供针对解析器、分析器、层级和智能体式处理的端到端调试命令，然后在API、工作进程和共享软件包中运行lint、安全自动修复和类型检查。 - 在诊断更高层流水线故障前，验证本地API文档和支撑服务端点。 - 在受影响的解析器、发布路径、检索模式和质量检查获得直接结果之前，不得报告完成。