Docling DOCX 代码块识别机制：从 Code-detection Fixture 到 msword_backend 源码级解析

本文以 Docling 仓库中 DOCX 代码块检测的 ground truth 文档 docx_code_blocks.docx.md 为主线，完整讲解其 8 个测试用例的设计意图，并深入 msword_backend.py 源码，说明 Docling 如何把 Word 文档中的代码段落识别为 CodeItem、如何避免把等宽字体的普通正文误判为代码，以及代码块如何合并为多行结构——读者读完即可掌握该机制的判定规则、边界条件与验证方式。

Ground Truth 文档的角色

在 Docling 的测试体系里，DOCX 转换测试遵循“源文件 + 三件套 ground truth”的组织方式：

• 源文件：tests/data/docx/sources/docx_code_blocks.docx；
• 期望的 Markdown 输出：tests/data/docx/groundtruth/docx_code_blocks.docx.md（即本文主体文档）；
• 期望的 DoclingDocument JSON：tests/data/docx/groundtruth/docx_code_blocks.docx.json；
• 对应的集成测试：test_docx_code_blocks（约 L1356 起）。

该 fixture 文档共定义 8 个用例（Case A 至 Case H），前半部分验证“应识别为代码”的正例，后半部分专门构造“应识别为普通正文”的反例陷阱。测试断言的结论是：转换结果中恰好出现 3 个 CodeItem（Case C、D、E 各一个），其余全部保持为普通 TextItem。

八个用例逐一拆解

正例：应识别为代码的三个 Case

Case C —— 'Source Code' 样式段落。原文为一个 Python 代码段落：

import sys
print(sys.argv)

该段落使用了名为 “Source Code” 的 Word 段落样式。这是命中样式名单精确匹配信号的代表用例；ground truth JSON 中它会与相邻的同样式段落合并成一个 CodeItem，文本为 import sys\nprint(sys.argv)。

Case D —— 全等宽字体段落（无代码样式）。原文是一条 SQL 语句：

SELECT * FROM users WHERE active = 1;

该段落没有代码样式，仅整段使用等宽字体。它验证的是字体回退信号：只要段落几乎全部字符落在等宽字体、且文本含有代码特征字符，同样会被判为代码。

Case E —— 多行等宽代码块。原文是一个完整的 Python 函数：

def fib(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

这个用例额外验证两件事：

1. 连续多个等宽代码段落会合并为一个 CodeItem，而不是逐段生成多个代码块；
2. 合并时保留缩进——return a 这样的行本身没有任何代码特征字符，但因为它紧跟在前一个代码段落之后且以空白开头，会被判定为“代码块延续行”而留在块内。

测试中对它的断言（见 tests/test_backend_msword.py L1372-L1375）要求合并后的文本逐字符等于带换行与缩进的完整函数体。

反例：四个防误判陷阱

Case A —— 普通正文。一段描述解析器工作原理的常规文字，使用默认正文字体，断言其必须保持为 TextItem。

Case B —— 正文中夹一个等宽单词。原文为 “Call the printf function to print formatted output to standard out.”，其中 printf 用等宽字体渲染。关键在于：字体检测是按段落字符占比计算的（见后文 90% 阈值），一个等宽单词不足以让整段翻转为代码。

Case F —— 'Source Reference' 样式（子串陷阱）。样式名 “Source Reference” 包含子串 “Source”，但不在样式名单中。这验证样式名是精确匹配而非子串匹配——否则 “Source Reference”“Area Code”“Unicode” 这类样式都会被误伤。

Case G —— 'Listing Number' 样式且无代码字符（子串陷阱）。“Listing” 样式常见于代码清单题注，它刻意不在代码样式名单里；同时该行 “Listing 3.2” 也不含任何代码特征字符，双信号均不满足，必须保持为正文。

Case H —— 纯 Courier 正文（无代码特征字符）。“This memo is set in a typewriter face for a vintage look and feel throughout.” 整段用打字机体（Courier 系），但全文只含字母与空格，没有任何 {};=<> 等代码指示字符，也没有函数调用/定义形态。这验证了字体信号必须与文本特征叠加才生效——纯等宽排版的“复古风”备忘录不能被误判为代码。

四个反例的断言集中体现（tests/test_backend_msword.py L1377-L1385）：这四句话必须全部出现在“非代码 TextItem”集合里。

源码级原理：两层判定信号

判定入口在 _get_label_and_level：该方法把每个段落归类为标题、代码或普通文本，其中 L1392-L1393 是关键分支——

if self._is_code_style(style) or self._is_code_by_font(paragraph, style):
    return "Code", None

即“样式信号”或“字体信号”任一命中，段落标签即为 Code。两类信号的优先级与判定细节如下。

第一层：样式名 / styleId 精确匹配

_is_code_style 会沿段落的 base_style 继承链向上回溯（最多 _MAX_STYLE_INHERITANCE_DEPTH = 10 层，防止畸形 or 循环的继承链），逐层检查样式名和 styleId：

• 样式名集合 _CODE_STYLE_NAMES（小写精确匹配）：source code、code、code block、code listing、html preformatted、preformatted text、preformatted、verbatim；
• styleId 集合 _CODE_STYLE_IDS：sourcecode、source_code、code、codeblock、codelisting、htmlpreformatted、preformattedtext、preformatted、verbatim。

源码注释明确说明这是“精确匹配、永不按子串匹配”，并且有意排除了 “Listing” 这类题注样式——这正对应 Case F/G 两个陷阱的设计依据。注释同时提到该名单“镜像 pandoc 的 docx reader”，即与主流转换工具的约定保持一致。样式信号一旦命中，无需任何文本特征即可判定为代码，因此 Case C 中哪怕代码很短也会成立。

第二层：等宽字体回退信号

当样式名不构成证据时，才启用低精度的字体回退判定 _is_code_by_font。它按“最便宜的检查优先”的顺序层层过滤：

1. 内容层过滤：页眉页脚（ContentLayer.FURNITURE）只认显式样式，字体信号直接返回 False；
2. 题注样式排除：样式名含 caption/figure/table/label 的段落排除；以 figure/table/listing + 数字 开头的题注行排除（“Listing 3.2” 正是被这一条与代码特征双重拦截，对应 Case G）；
3. 代码特征检查（核心，见下节）：文本必须携带某种代码信号，或者是“上一兄弟节点是代码且本行以空白开头”的延续行；
4. 列表项排除：带有 numId/ilvl 编号属性的段落不再改判为代码（显式代码样式仍可胜出）；
5. 字符占比检查：调用 _monospaced_char_counts 统计段落中落在等宽字体（_MONOSPACE_FONTS：Consolas、Courier、Courier New、Lucida Console、Menlo、Monaco、DejaVu Sans Mono、Andale Mono、Liberation Mono、SF Mono）下的字符比例，必须不低于 _MONOSPACE_CHAR_RATIO = 0.9。注意该方法通过 XPath 扫描段落元素下所有 w:r 节点（包括超链接、修订插入、智能标签和域结果中嵌套的 run），防止某个比例字体的 span 溜过“全等宽”检查——Case B 中那个孤立的等宽单词 printf 就是在这里被 90% 阈值挡住的；
6. 表格排除：表格单元格内的段落不走字体信号（从源码结构看，单元格场景改由显式代码样式处理，见 msword_backend.py 附近的单元格分支）。

字体继承的细节也值得注意：run.font.name 为 None 的 run 会继承样式链上解析出的字体（_effective_style_font），但文档默认样式被排除在证据之外——“停留在默认样式上不代表作者意图”，因此整篇 Courier 主题的文档不会仅因主题字体被判为代码，这正是 Case H 的防线之一。

代码特征：四种可叠加的文本信号

_is_code_by_font 里的 has_code_char 由四个信号“或”起来（msword_backend.py）：

信号	实现	说明
指示字符	_CODE_INDICATIVE_CHARS = frozenset("{};=<>")	命中其中任一即强信号；单独的分号不算（strong_hits - {";"}），因为电话、引用条款等正文里分号很常见，终止符单独成行的场景留给“延续行”兜底
调用形态	_CODE_CALL_PATTERN（L356-L358）	匹配参数“长得像代码”的函数/方法调用，如 set()、print(sys.argv)；刻意排除 party(ies) 这类纯文本括号形态
定义/块头形态	_CODE_DEF_PATTERN（L366-L372）	匹配以 def/class/if/elif/while/for/with/except/finally/try/catch/switch/function/func/fn/sub/proc 等关键字开头且以冒号结尾的块头行；return、import 等不会产生块头的关键字被刻意排除，避免误伤正文
语言识别	detect_code_language(...)	复用 Docling 的语言检测工具，只要能把该行归入某种具体编程语言即视为信号

四个信号的设计意图是让 Case D（SQL 的 *、= ）、Case E 第一行（def fib(n): 命中定义形态 + =）通过，而 Case B/H 这类无特征文本直接出局。

代码块合并与边界规则

识别出代码段落后，Docling 不会逐段生成代码块，而是在 Code 分支 做合并：

• 合并条件（三条件同时满足）：上一个产出项是 CodeItem、它是当前父容器的最后一个子节点（任何中间元素都会断开块）、且处于同一内容层；
• 空行处理：块内的空段落被缓冲（_pending_code_blank_lines），只有后续还有代码时才以换行形式写入，保证“代码块永远不以空行结尾”；行尾则做 rstrip()，但行首缩进保留（L2041 注释：Kept unstripped: code blocks preserve leading indentation）；
• 语言重探测：每次合并后，若累计语言的 code_language 仍为 UNKNOWN，会用合并后的完整文本重新调用 detect_code_language——单段可能模棱两可，整块往往就能确定；
• 延续行的衔接：每处理一个段落前都会更新 _prev_sibling_is_code（msword_backend.py），供下一段的“延续行”判定使用，这就是 Case E 中 return a 能留在块内的机制；
• 边界情况（由 test_docx_code_block_merging 等测试覆盖）：代码块中间插入图片会断开块，拆成两个 CodeItem；表格单元格是天然边界，围绕单元格的空代码段落不会“消耗”这道屏障。

如何复现验证

在仓库根目录运行对应测试即可复现本文全部结论：

python -m pytest tests/test_backend_msword.py -k code_block -v

其中：

• test_docx_code_blocks（tests/test_backend_msword.py）：转换提交的 fixture 文件，断言恰好 3 个 CodeItem、三个正例文本逐一相等、四个反例全部落在普通文本集合；
• test_docx_code_block_merging 等（L1388 起）：用 python-docx 现场构造文档，验证合并、边界与列表交互规则。

测试中的两个辅助函数也值得参考：_code_items 收集 CodeItem，_plain_texts 则特意用 isinstance(item, TextItem) and not isinstance(item, CodeItem) 排除代码项——因为 CodeItem 是 TextItem 的子类，只用 isinstance(item, TextItem) 过滤会漏掉这个包含关系。

实操启示

1. 想让 Word 文档里的代码被 Docling 识别为 CodeItem，最可靠的方式是给段落套用 “Source Code”/“Code” 等名单内样式（或继承自它们的样式），这是最高精度信号，短代码、无特征字符的代码同样有效；
2. 没有代码样式时，整段使用 Consolas/Courier/Menlo 等名单内等宽字体（占比 ≥90%）且文本含 {};=<>、调用或关键字块头形态，也能命中；混合字体（正文夹少量等宽词）不会触发；
3. 想避免误判：题注样式（Listing、Caption 等）与表格内文本天然不受字体信号影响；纯等宽排版的怀旧风正文（无代码字符）会被正确保留为正文；
4. 连续代码段落会被合并为一个代码块并保留缩进，中间穿插图片、表格等元素则会断开，编写自动化测试时可据此设计断言。

以上规则均以当前仓库 docling/backend/msword_backend.py 的实现为准；样式名单、等宽字体集合与 90% 阈值均为类级常量，如仓库后续版本调整，应以最新源码为准。