Word 转 Markdown 报“保真率 98%“，可那张表散了

Word 转 Markdown 报保真率 98%可那张表散了一份静静躺在目录里的发布说明 .docx我顺手丢给 tri-docx2md 想转成 Markdown四道门跑完门D 交的报告说保真率 98.4%、判定却是 C 级强制人工复核。真相反直觉数字好看不代表能直接用因为 mammoth 转出来字符都很齐唯独把那张 4 列的表格拆成了一堆散行文本Markdown 里连一个|都没有。这篇文章记录我用 tri-docx2md 转这份文档的全过程以及后来换 pandoc 换出一个完全相反的更差数字、更好结果的结论。这份 docx 是什么来头要转的是一份「智能运维平台操作手册 v3.1」的发布会 .docxpython-docx 建的里面有二级标题一张 4 列 3 行的变更明细表格还有几段正文。文件不大37KB 出头。tri-docx2md 不是直接叫一个库去转它是个编排车间先体检、再选刀、干完活必须交一份账。门A预检说这是块省心的料第一步跑preflight.pypython scripts/preflight.py--docrelease-notes.docx--json它读文件头 8 个字节做魔数判定PK\x03\x04开头就是 OOXML 的 .docxD0CF11E0开头才是旧式 .doc。这份是标准的 zip 容器 .docx没加密6 个段落、1 张表格、0 张图直接给 L0 快速档风险列表是空的。{detected_type:docx,encrypted:false,paragraph_count:6,table_count:1,image_count:0,grade_suggestion:L0,risks:[]}有意思的是encrypted:false这一项不是摆设——OOXML 文档如果带了EncryptionInfo这里会直接 BLOCK提示你手动解密绝不碰加密文件。tri-docx2md 在这点很老实加密就停不搞破解。门B刀库里 mammoth 被封了首选门B 跑detect_backends.py把六个后端在本地探一遍import 和 CLI 双路探测python scripts/detect_backends.py--gradeL0--json结果有点出乎意料除了 antiword其它全都装着后端档位本地状态许可证mammothL0✅ import 可用BSD-2-ClausemarkitdownL0✅ import 可用MITpython-docxL0✅ import 可用MITpandocL1✅ CLI 可用GPL-2.0LibreOfficeDOC✅ CLI 可用MPL-2.0antiwordDOC❌ 未装GPL-2.0L0 档首选 mammoth降级链是 markitdown → python-docx。antiword 那条是给 .doc 旧格式兜底用的没装暂时不碍事。我心想 mammoth 做 .docx 是出了名的稳就让它上。门Cmammoth 转完我心里咯噔一下按手册里的命令用 mammoth 的 Python API 转importmammothwithopen(release-notes.docx,rb)asf:rmammoth.convert_to_markdown(f)open(release-notes.md,w,encodingutf-8).write(r.value)转出来的 Markdown 一打开标题还在正文也在但那张表格没了——它变成了一堆没有|分隔的散行模块 变更类型 说明 影响范围 告警中心 新增 风暴收敛聚合规则 告警详情页/通知通道表格的语义在 Markdown 里是没勾的意思。我压着火没换刀先跑门D 看它到底怎么判。门D保真率 98.4%判定 C 级门D 交账python scripts/quality_check.py--docrelease-notes.docx--mdrelease-notes.md--backendmammoth--gradeL0--json报告出来了核心数据看着挺唬人关键数据mammothL0保真率98.4%丢失率1.6%噪声率1.6%结构对比标题 2/2、表格0/1、图片 0/0置信度C强制人工复核保真率 98.4%四舍五入就是丢得很少。可结构对比那一栏写着表格 0/1——源文档里明明有一张表Markdown 里却找不到一个表格语法。门D 给的判定原因很直白“源文档检出表格 1 处而 MD 无表格语法”直接 C 级。这里我想岔了一点差点误判保真率高不等于能直接入库。因为保真率算的是源文档的可提取文本被 MD 覆盖了多少mammoth 把表格细胞里的文字都提出来了字符一个没少所以召回率很高可它把表格的结构弄丢了这在 Markdown 里等于把表拆平了。对要当知识库入库的文档来说散行的表格比丢几个字严重得多——检索、引用都废了。换 pandoc数字变差结果反而更好C 级除非用户点头否则按管道要沿降级链重转。L0 的链是 markitdown/python-docx基本是同类货不如直接上 L1 的 pandocpandoc release-notes.docx-tgfm--wrapnone-orelease-notes-pandoc.mdpandoc 输出里那表格回来了成了规范的 GFM 语法|和分隔线一个不缺| 模块 | 变更类型 | 说明 | 影响范围 | |--- |--- |--- |--- | | 告警中心 | 新增 | 风暴收敛聚合规则 | 告警详情页/通知通道 | | CMDB | 优化 | 查询接口二级缓存 | 资产列表/拓扑页 |再跑一遍门D结果让我愣住了关键数据mammothL0pandocL1保真率98.4%89.6%丢失率1.6%10.4%噪声率1.6%1.7%结构对比表格 0/1表格1/1置信度CB抽查复核pandoc 的保真率反而暴跌到 89.6%比 mammoth 低了快九个百分点。可它的表格在结构对比里是 1/1全齐。门D 判成 B 级原因是保真率落在 85–95% 区间需要抽查复核但结构上表格保住了。我盯着这两组数想了半天才想明白 tri-docx2md 这套分级的设计意图结构对比是硬指标保真率是软指标。保真率的低很多是文字层面的假象——pandoc 输出 GFM 表格要占用|、空格、分隔线这些符号这些不是源文档里的可见文字bigram 一比就跟源文本对不上召回率就掉下来了。但去掉 Markdown 语法符号后真正的文字一个没丢表格还整整齐齐。mammoth 那边字符都召回了结构却平了属于高召回、低可用。所以那个保真率 98.4% 却是 C 级的怪象本质是结构丢失比文字丢失严重得多而保真率这个单一数字根本看不出结构。要信得看结构对比和置信度不能只看最大那个百分比。踩完这趟我认了几条理保真率高≠能用mammoth 把文字都召回了但表格散架照样 C 级。入库的文档结构完整比字符齐全重要。置信度分级是结构优先结构对比不吻合直接压到 C哪怕保真率 98%。这是 tri-docx2md 最值钱的设计。带表格的文档直接上 L1L0 快速档的 mammoth 对这种小表就翻车了复杂表格更悬。与其 C 级再降级不如一开始就 pandoc。数字要分开看保真率、丢失率、噪声率、结构对比各回答一个问题混在一起看会得出98% 很稳的错误结论。顺带一提我在做雷达鸭的案例库时也常有人直接把 Word 导出的内容当知识源丢进来。用这套保真口径至少能一眼分清哪些文档是文字齐但结构废哪些是真的能入库——省去不少返工。收尾Word 转 Markdown 真正难的不是调用哪个库而是知道自己丢了什么结构。mammoth 和 pandoc 都是好库差别在于谁把表格当结构、谁只当文字。tri-docx2md 这个质检车间的价值就是把这件事摊成了四个能对照的数字——而这次我最该记住的是别被 98.4% 那张好看的脸骗了。我是老三10 年软件开发经验软件设计师、人工智能应用工程师专注鸿蒙应用开发ArkTS北向开发与 Web 前端探索 AI 自动化不定期在 CSDN 分享鸿蒙 / AI 方向技术文章。本文遵循 MIT 协议转载请注明出处。这个系列的文章都来自开源的 tri 技能库。整套 tri-xxx 技能都能在 skillhub 找到并安装一条命令装完即用比如本文用到的 tri-docx2mdskillhub install tri-docx2md。装完每个技能都有 README想摸清它到底能干嘛读那个就够了。