第 2.2.2 节：把解析结果统一成可检索的中间文档格式
中间文档格式只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够按顺序说明中间文档格式的触发、处理、复核、记录和兜底步骤。
核心概念
下面几个概念按照“四层解释法”来讲：人话解释、项目位置、工程动作、面试说法。
文档解析
人话解释：文档解析是把客户给的文件、网页、扫描件和工单记录，转换成系统能理解、能检索、能追踪的资料结构。它不是简单复制文字，而是尽量保留文档里的标题、段落、表格、图片、页码、来源和业务含义。
项目位置：在客服工作台里，文档解析位于资料上传之后、分块和索引之前。售后政策 PDF（便携式文档格式）只有先被解析成正文块、表格块、版本信息和权限标签，后续才能进入分块、Embedding（嵌入向量）和检索。
工程动作：你要设计格式识别、解析器选择、正文抽取、表格抽取、图片记录、OCR（光学字符识别）、噪声清洗、元数据补充、质量评分、人工复核和入库日志。
面试说法：文档解析是 RAG（检索增强生成）的上游质量门。我的重点不是把文件转成文本，而是保证资料进入知识库时带来源、结构、版本、权限和质量状态，避免后续检索在脏数据上工作。
中间文档格式
人话解释：中间文档格式是原始资料和知识片段之间的一层标准表示。不同格式的资料先统一转换成同一种“可治理文档”，再交给后续分块和索引。
项目位置：客服项目里，PDF（便携式文档格式）、Word（文字文档）、Excel（电子表格）、Markdown（轻量标记语言）、网页和工单历史都要先落到中间文档格式。这样后续模块不用关心原始文件来自哪里，只需要读取统一的正文块、表格块、图片块、元数据和质量标记。
工程动作：你要定义 document_id（文档编号）、source_id（来源编号）、source_type（来源类型）、content_blocks（内容块）、table_blocks（表格块）、image_blocks（图片块）、permission_tags（权限标签）、version（版本）、effective_date（生效日期）、quality_score（质量评分）等字段。
面试说法：我会在文档解析和分块索引之间设计中间文档格式，避免每种文件格式直接耦合到检索系统。这样格式扩展、质量检查、权限过滤和错误追踪都会更稳定。
元数据
人话解释：Metadata（元数据） 是描述资料本身的信息。正文告诉你“政策内容是什么”，元数据告诉你“这份政策从哪里来、哪个版本、谁能看、什么时候生效、质量如何”。
项目位置：客服工作台里，售后政策正文可以回答问题，但元数据决定它能不能被检索、能不能展示给外部客户、是否比旧版本优先、引用时显示什么来源。
工程动作：你要保留来源、格式、上传人、负责人、版本、生效日期、权限标签、文件指纹、解析器类型、质量评分、入库追踪编号和审核状态。
面试说法：RAG 不是只存文本。元数据决定权限、版本、引用和排错能力。没有元数据，后续就无法解释为什么命中了某个片段，也无法避免旧资料和无权限资料进入回答。
文件指纹
人话解释：file_hash（文件指纹）是用来识别文件内容是否相同或发生变化的标记。它比文件名可靠，因为同一份文件可以改名，不同文件也可能重名。
项目位置：客户重复上传同一个售后政策 PDF（便携式文档格式）时，系统要通过文件指纹判断是否重复；客户上传新版价格表时，也要判断内容是否真的变化。
工程动作：你要在资料接入时计算文件指纹，并记录到 source_id（来源编号）和 document_id（文档编号）的关系里。重复文件可以跳过、合并或进入版本对比。
面试说法：我会用文件指纹避免重复入库和重复索引，同时帮助判断资料是否变化。这样可以降低索引噪声，也能解释为什么某次上传没有生成新版本。
质量标记
人话解释：质量标记是系统对解析结果的判断，例如“正文为空”“疑似乱码”“OCR（光学字符识别）置信度低”“表格丢失”“权限缺失”“版本冲突”。
项目位置：客服知识库不能把所有解析结果都直接发布。售后政策如果 OCR（光学字符识别）质量低，价格表如果表头丢失，历史工单如果未脱敏，都应该进入待复核状态，而不是直接给 Agent（智能体）使用。
工程动作：你要设计 quality_score（质量评分）、quality_flags（质量标记）、review_required（是否需要复核）和阻断规则。严重问题阻止发布，轻微问题允许入库但标记风险。
面试说法：质量标记是把文档解析从“脚本处理”变成“可运营流程”的关键。系统要知道哪些资料可直接索引，哪些必须人工确认。
入库日志
人话解释：入库日志记录一次资料进入知识库的完整过程：谁上传了什么，使用了什么解析器，解析是否成功，生成了多少内容块，哪些质量检查失败，最后是否进入索引。
项目位置：当客服问“为什么新政策搜不到”时，入库日志能告诉我们：文件是否上传成功、解析是否失败、是否卡在待审核、是否因为权限标签缺失没有发布、是否索引失败。
工程动作：你要设计 ingestion_trace_id（入库追踪编号）、解析开始时间、结束时间、解析器类型、输入文件、输出块数量、失败原因、质量评分、操作者和下一步动作。
面试说法：我会给资料入库设计可追踪日志，因为 RAG 问题排查不能只看最终回答。上游每一步都要能复盘。
本章在客服 Agent（智能体）工作台中的位置
客服 Agent 工作台可以拆成 8 层。本章重点在第 2、3、4 层。
| 层级 | 作用 | 本章关注点 |
|---|---|---|
| 用户入口 | 客户、客服、运营上传资料或提问 | 本章只关注运营和管理员上传资料。 |
| 资料接入层 | 接收 PDF（便携式文档格式）、Word（文字文档）、Excel（电子表格）、网页、工单历史 | 本章核心。 |
| 解析清洗层 | 抽取正文、表格、图片、标题、OCR（光学字符识别）文本和网页正文 | 本章核心。 |
| 资料治理层 | 版本、权限、状态、质量评分、审核和入库日志 | 本章核心。 |
| 分块索引层 | 分块、Embedding（嵌入向量）、关键词索引、向量索引 | 后续章节展开。 |
| 检索生成层 | 检索、重排序、生成带引用回答 | 后续章节展开。 |
| 工具调用层 | 查订单、查工单、创建工单、发起审批 | 本章只处理工单历史作为资料来源。 |
| 质检运营层 | 反馈、错误复盘、资料修正和重新入库 | 本章提供日志和质量证据。 |
这一章的位置很靠前，但影响很深。分块策略再好，也救不了标题丢失、表格打散、权限缺失、版本混乱的资料。Embedding（嵌入向量）模型再强，也无法知道 OCR（光学字符识别）把“不可退货”识别成“可退货”。
系统流程图
下面是客服知识库资料从接入到入库的推荐流程。
读图重点：先看三个分支：重复文件只留跳过日志，扫描内容按需进入 OCR，质量闸门再分成通过、复核和失败。只有通过路径进入分块索引，其他路径都必须修正并记录 ingestion_trace_id。
这张图有 5 个重点：
- 先建来源记录，再解析文件。否则失败后没有追踪对象。
- 文件指纹和版本判断发生在解析前，避免重复索引。
- OCR（光学字符识别）不是默认成功，要有状态和置信度。
- 表格块和图片块不能被粗暴压平成正文。
- 只有通过质量闸门的中间文档，才应该进入分块和索引。
模块拆分
文档解析和数据入库可以先拆成 9 个模块。
| 模块 | 负责什么 | 主要输出 |
|---|---|---|
| 来源登记模块 | 记录资料来源、上传人、负责人、授权范围 | source_id（来源编号）和来源清单。 |
| 文件指纹模块 | 计算 file_hash（文件指纹），判断重复和变更 | 去重结果和版本判断。 |
| 格式识别模块 | 判断 source_type（来源类型）和文件特征 | 解析策略建议。 |
| 解析调度模块 | 根据格式选择 parser_type（解析器类型） | 解析任务和状态。 |
| 内容抽取模块 | 提取正文、标题、表格、图片、页码、OCR（光学字符识别）文本 | 中间内容块。 |
| 清洗规范化模块 | 去除噪声、整理标题路径、统一空白和重复内容 | 可治理正文结构。 |
| 元数据与权限模块 | 补充版本、生效日期、权限标签、负责人和状态 | 可过滤、可引用的元数据。 |
| 质量闸门模块 | 检查空文本、乱码、表格丢失、OCR（光学字符识别）低置信度、权限缺失 | quality_score（质量评分）和复核建议。 |
| 入库日志模块 | 记录每次处理的输入、输出、失败和下一步 | ingestion_trace_id（入库追踪编号）和可复盘日志。 |
作品集项目不必一开始把每个模块都做成复杂后台。你可以先把它们设计成清晰的流程和字段契约，再实现最小闭环：上传资料、解析、生成中间文档、质量检查、人工确认、进入索引。