当Word样式不可信：DOCX转Markdown的实战教训

构建DOCX到Markdown转换器时，最危险的假设莫过于相信Word的样式系统。开发者往往默认Heading 1代表章节标题、Heading 2代表子章节，逻辑清晰。但现实是，当人类打开文件开始“创作”时，一切规范都会崩塌。

样式失效的真实案例

一位开发者分享了他遇到的典型故障：一份40页的合同文档，作者通过选中文本、加粗、将字号调到16pt来“格式化”标题。文档中没有任何标题样式，大纲视图中一片空白。转换器面对的是一堵密不透风的正文墙，最终输出的自然也是毫无结构的文字块。下游的RAG或Agent拿到的是12000词的无结构文本，分块策略完全失效。

这个案例揭示了一个被低估的事实：用户上传的文档往往不是按规范生成的，而是人类在Word中即兴操作的产物。样式系统在理论上是可靠的，但在实践中经常被绕过。

启发式回退：不优雅但有效

解决方案并不复杂，甚至有些“笨拙”——增加一轮启发式回退处理。具体规则包括：

• 如果段落较短（少于120字符）、完全加粗、且字号明显大于文档正文字体，则提升为标题；
• 如果段落以冒号结尾且下一段是列表，则提升为标题；
• 如果段落全大写且少于80字符，则提升为标题。

这些规则谈不上精确，但覆盖了大量“人类 improvisation”场景。开发者对此的比喻很到位：Word文档就像考古现场，你需要逐层挖掘人类即兴发挥留下的痕迹。

启发式回退的判定需要先建立“文档正文基准”。常见做法是统计全文所有段落的字号与字重分布，取出现频率最高的字号作为正文字号（body font size），并记录常规字重。标题候选段落的字号需显著大于该基准（例如大 4pt 以上或超过 1.3 倍），同时满足加粗、短文本等条件。为避免误判，还应加入排除规则：如段落位于表格单元格内、属于列表项、以句号结尾且含多个句子、或前后文均为普通正文且无空行分隔时，降低其标题置信度。置信度可以按规则加权累加，超过阈值才提升为对应层级标题，层级可按字号从大到小映射为 H1、H2、H3。这套方法本质上是基于排版特征的统计推断，而非语义理解，因此宁可漏判也不要过度提升，以免打乱下游分块结构。

悬空样式引用：另一个隐蔽陷阱

除了样式被绕过，另一个常见问题是w:style引用可能指向styles.xml中根本不存在的样式。某些导出工具会写入悬空引用，解析器如果直接崩溃，整个转换流程就会中断。修正方案是将缺失的样式定义一律视为正文处理，而不是抛出异常。

这个细节说明，健壮的解析器需要容忍格式层面的“谎言”。DOCX不是一份严格的文档格式，而是一个意图容器，其中相当一部分意图是假的。

styles.xml 是 DOCX 包内定义所有样式（字符样式、段落样式、表格样式等）的核心部件，每个样式在其中拥有唯一的 w:styleId。当文档正文段落通过 <w:pStyle w:val="..."/> 引用某个样式时，这个 ID 理应在 styles.xml 中存在对应定义。然而，Word 本身允许“延迟定义”——引用可以先存在，定义可以后补；更常见的是，第三方导出工具（如在线编辑器、PDF 转 Word 服务、LibreOffice 另存等）在生成 DOCX 时仅复制了引用而未复制定义，从而产生悬空引用。此外，样式还可能通过 w:basedOn 链式继承，若父样式缺失，解析整条链就会中断。健壮的解析器应当把“引用存在但定义缺失”视为一种合法状态，回退到默认段落样式并继续处理，而不是抛出异常终止转换。

对RAG与Agent开发者的启示

对于需要解析用户上传文档来构建RAG上下文或Agent输入的开发者，这篇分享给出了一个务实的建议：将60%的精力预留给处理“奇怪文件”，而不是那些格式规范的干净样本。真实世界的数据管道中，异常文件才是常态。

该开发者已将转换器打包为在线工具，启发式标题识别默认开启。对于需要处理大量用户文档的团队，这类回退策略值得纳入默认配置，而非作为可选项。

核心要点

• Word样式系统在真实用户文档中经常被绕过，不能作为唯一的结构依据；
• 启发式规则（短段落+加粗+大字号、冒号+列表、全大写短文本）能有效捕获“手工标题”；
• 解析器应容忍悬空样式引用，将缺失定义视为正文而非崩溃；
• 处理用户上传文档时，异常文件的精力投入应占大头。