ooxml-integrity

ooxml-integrity

ooxml-integrity 会在自动编辑后检查 .docx 和 .pptx 文件。 它能发现损坏的批注锚点、丢失的修订记录、孤立的脚注，以及可能溢出文本框的演示文稿文本。

检查器会读取文档包和本地字体文件。它在本地运行，无需渲染、模型调用或网络访问，因此文档可以留在你的设备上。

浏览器演示无需安装即可运行。文件只会留在你的浏览器标签页中；Python 会在启动时下载一次。演示版固定使用已发布的版本，每次发布后更新，并在页脚显示其版本。真实浏览器检查会在部署到 Pages 前拦截变更。版本发布在 PyPI 上；每个版本的升级说明都会描述发现项的变化和兼容性。

pip install ooxml-integrity
ooxml-integrity check edited.docx --against original.docx

edited.docx: 2 error(s), 0 warning(s), 0 info
  [ERROR] CMT005  comment id=1 is orphaned - present in comments.xml but
                  anchored to nothing - the reviewer's note is invisible in Word
  [ERROR] FID001  comment anchors: 2 -> 1 (1 lost)

在本例中，编辑后的文件可以在 Word 中打开且不会显示警告，字数和页数也保持不变。审阅者的备注 “分发前请对照源表确认此图” 仍在文档包中，但它的锚点已经丢失，Word 不再将其显示在图旁。

为什么要做这个项目

我最初做了一个小实验：让 Agent 编辑一份已经包含审阅者批注和修订记录的合同。在两次运行中，任务都是更新同一张表中的三个数字。标记为 careful 的运行保留了批注，并将编辑记录在另一位作者名下。fast 运行使用了 python-docx，丢失了批注锚点：

	fast Agent	careful Agent
页边距中的审阅者批注	缺失	存在，锚定到图
表格编辑	未跟踪（0 w:ins，0 w:del）	已跟踪（9 w:ins，2 w:del）
打开时的 Word 警告	无	无
字数	118	118

原因是段落被替换了。在 python-docx 中设置 paragraph.text 会将段落内容替换为一个新文本运行。这也会移除其中存储的批注锚点、脚注引用、文本运行格式和修订标记。即便发生了这些丢失，文件仍然可以正常打开。

在另一个测试中，我们故意引入了六种缺陷，检查器全部发现了：仅检查编辑后的文件就找到了其中五种；另一种通过 Markdown 往返处理后，文件内部仍保持一致，因此只有与源文件比较时才能发现（--against）。XML 解析、命名空间／根元素检查和成功转换为 LibreOffice PDF，都无法将这些情况与对照组区分开来。该实验没有运行完整的 XSD 验证，也没有进行系统性的视觉审查。在八次真实 Agent 运行中，检查器没有报告任何误报。

研究说明介绍了实验、保存的输出、渲染器测量结果和局限性。

在经过审阅的文档上使用工具和 Agent

八次运行只能说明一种趋势。 审阅历史基准测试 在两份保留实时审阅历史的合同上，向六种文档工具、两条代码路径中的 python-docx，以及三个在隔离容器中运行的编码 Agent，分别提交了 30 个普通请求（替换短语、回复评论、接受一处修订、修正脚注）。一个从未导入检查器的预言机将每份输出与其源文件进行比较，并在 Word for Mac 中打开每种损坏类型的一份输出。

• Claude Code (Opus 5.5) 和 Codex (gpt-6.1-sol) 均完成并保留了全部 150 次尝试，各进行了五次采集。在每次采集中，Codex 对第一份合同评论的回复都没有文档锚点，而 Word for Mac 不会显示此类回复。 使用本地 Qwen3.8 27B 的 OpenCode 有一次移除了另一位审阅者的插入标记，导致该审阅者待处理的句子显示为已接受文本。
• 在 python-docx 中赋值给 Paragraph.text 或 _Cell.text，导致 28 份输出中有 14 份受损。docx-cli 导致 56 份输出中有 38 份受损：项目符号变成了字面文本 •，而新词被归到了另一位审阅者名下。两种工具修改的是文档标题，而不是指定的页眉。
• 在 69 份受损输出中，冻结版检查器 (0.4.6) 报告了 41 份，同时将 537 份正确输出中的 145 份标记为问题，其中大多数是请求的更改本身。0.4.9 将每项任务请求的更改声明为预期内容后，报告了 65 份，并将 12 份标记为问题；这些都是基准测试范围之外的真实报告，例如 Word 不会显示的回复。

这些数量是两份文档上的尝试次数，并非独立文档数量。证据包含冻结协议、其修订内容和每次采集结果。

应用于其他项目

我们已将语料库和基准测试中的发现提交给上游，并为每项发现提供了独立复现。adeu 修复了两项，docx-cli 修复了三项；其余问题仍未解决。

项目	发现	状态
adeu	批注引用测试运行生成的 rStyle="CommentReference"，但未定义该样式	已在 3.0.3 中修复；此语料库中的参考文档已被采纳为上游测试夹具
python-docx	paragraph.text setter 会分离通过 1.2 的批注 API 创建的批注锚点和现有脚注引用	未解决；PR #1605 恢复了批注锚点，但作者于 2026-11-09 关闭了该 PR，且未合并；脚注和修订不在其范围内
python-docx	add_comment() 引用了 CommentReference 样式，却未定义该样式	未解决
anthropics/skills	docx 技能的 validate.py 会通过这样一种文件：批注存在于 comments.xml 中，却没有锚定到任何内容——它检查的是标记 → 批注，而不是反向关系	未解决；PR #1734 正等待维护者审查
sontanon/docx-mcp	提出提供带标签的配对；询问拒绝已带修订的输入的策略	未解决
docx-cli	任何写入操作都会将 • 等数字字符引用转换成字面文本；Word 显示 • 而不是项目符号	已在 0.27.0 中修复（PR #14）；在发布后复查中，S1 输出均未出现字面项目符号（0.26.0：28 个全部出现）
docx-cli	在另一位作者待处理的插入内容中执行 replace --track，会将新文本署名给该作者；且无法找到嵌套删除旁边的目标内容	已在 0.27.0 中修复（PR #19、#20）；在复查中，两个带修订的 K4 编辑均得到保留
docx-cli	在包含嵌套删除的、另一位作者待处理的插入内容中执行不带修订的 replace，会替换错误的文本范围	已在 0.28.0 中修复（PR #21）；在复查中，S2 上不带修订的 K4 编辑已完成并得到保留（0.27.0：未完成且已损坏）
docxengine	新建批注会将 w14:paraId 写入未声明 w14 的批注部分；Word 报告内容无法读取	未解决
docxengine、SecurityRonin/docx-mcp	回复没有锚定到文档中的任何位置，Word 不会显示它	未解决
Codex	回复批注时，模型生成的代码声明了 commentsExtended，但其内容类型被 Word 拒绝（PKG010），且回复没有锚定到任何位置（CMT005）	未解决

已合并到上游的测试夹具贡献：adeu #138 （跨 LibreOffice、Word for Mac 和 Word for Windows 的批注投影）以及 adeu #140（修订投影和 接受／拒绝）。准备这些内容时，发现 adeu 自身一致性测试套件中存在 Python／TypeScript 命名空间序列化不匹配 （#139，已在 3.0.4 中修复）。 上游已采用：自 adeu #156（于 2026-09-29 合并）起，adeu 的测试套件会安装 ooxml-integrity；自 adeu #161（于 2026-10-05 合并）起，版本固定为 0.4.8。对于每个共享的跨平台场景，测试套件会应用编辑、对输出运行 check()，并与输入运行 compare()；若出现错误级别的问题则判定失败。两个接受／拒绝场景会使用 expect()，将它们要求的修订计数变化声明为预期结果。

两个问题

文档即使丢失了所有样式、脚注和修订，内部仍可能保持一致。因此，检查器支持两种检查方式。

内部引用是否完好？ 检查单个文件中的批注、脚注、样式、编号、关系和跟踪修订。

ooxml-integrity check report.docx

编辑丢失了什么？ 将结构计数和文本与源文件进行比较。即使编辑后的文件没有损坏的引用，也能发现内容丢失。

ooxml-integrity check edited.docx --against original.docx

如果原文件本身可能已损坏，例如用户上传给 Agent 的文档，可添加 --introduced（0.10.0），仅对编辑引入的问题判定失败。原文件已有的问题会列为已抑制；内容丢失始终计入。什么情况下会视为同一个问题。

当不存在达到 --fail-on 阈值（默认为 error）的问题时，退出码为 0；存在此类问题时为 1；用法错误时为 2。使用 --json 输出机器可读结果，使用 --quiet 仅打印会导致本次运行失败的问题。

仅修复三类问题

大多数问题无法根据文件修复：恢复丢失的批注、样式或跟踪修订，意味着猜测原有内容。fix 仅进行结果唯一的三类修复，并在写入前重新检查副本。

ooxml-integrity fix edited.docx -o repaired.docx

• anchor-replies（CMT005）：对于父批注已锚定的回复，按 Word 写入线程的顺序，为其设置与父批注相同的范围。在 Word for Mac 中，只有修复后，该回复才会显示在线程中。
• renumber-revisions（REV001）：每个重复的修订 ID（首次出现之后）都会获得一个新 ID。
• content-type（PKG010）：相关部件在 [Content_Types].xml 中的 Override 会被设置为其关系类型所要求的内容类型。Word for Mac 拒绝了 fix 以此方式修复的五个 Codex 输出，并打开了 fix 根据其中一个输出写入的副本，且回复显示在线程中。

其他所有问题都会列为未修复，并注明原因。输入文件永远不会更改。在副本中，只有修复过的字节会不同，其他所有 ZIP 成员都会按原样复制。退出码 0 表示已写入经过验证的副本；1 表示没有可修复内容；2 表示用法错误，或 fix 不会重写该包；3 表示重新检查失败。修复内容、拒绝修复的情况及保证。

幻灯片：文本是否能放进文本框？

ooxml-integrity check deck.pptx

deck.pptx: 6 error(s), 4 warning(s), 1 info
  [ERROR] PPT001  text needs 144pt in a 40pt box - 104pt too tall (260% over), 3 line(s)
            -> slide1/OVER_huge_type_tiny_box
  [ERROR] PPT003  word wrap is off and the longest line is 304pt in a 182pt box
                  - 122pt runs outside the shape
            -> slide2/OVER_nowrap_single_line
  [WARN ] PPT004  shape extends 142pt past the right edge - content will be cut off
            -> slide3/OFFCANVAS_right
  [WARN ] PPT006  overlaps 'OVERLAP_upper_right' over 23% of the smaller shape
            -> slide3/OVERLAP_lower_left

文本适配需要有效的字体和字号，这些值可能继承自文本运行、段落、列表样式、版式和母版占位符、演示文稿默认设置及主题。检查器会解析这些值，并通过 fontTools 读取字体的 hmtx/cmap 表。相关的 python-pptx 讨论介绍了文本适配为何需要测量文本。

在对照 PowerPoint for Mac 检查参考演示文稿时，所有 21 个可检查形状的预测结论和行数都一致。其他渲染器在一个接近宽度限制的形状上给出了不同结果。检查器会将最高 5% 的预测垂直溢出报告为 PPT002 borderline，并将缺失字体报告为 PPT007。验证记录说明了比较方法及其局限性。

0.4.0 后续增加的检查涵盖较长的基本拉丁单词、TTC/OTC 字体成员、演示文稿幻灯片顺序，以及每个幻灯片母版的拉丁主题字体。为此专门制作的 4 个演示文稿共记录了 29 项 PowerPoint 幻灯片观察结果。长标记、字体集合、幻灯片顺序和主题说明记录了相关案例及其现存局限。

在 CI 中

- uses: Dmitry-Kov/[email protected]
  with:
    files: "out/**/*.docx"
    against: templates/master.docx   # optional, enables the fidelity check
    fail-on: error

在生成脚本运行、Agent 编辑或模板合并之后执行检查，同时确保源文件和已编辑文件仍可用于比较。

此操作会在作业页面写入摘要，并可生成 JSON 和 SARIF 报告。SARIF 发现项可作为代码扫描注释显示在拉取请求中。配置指南介绍了严重性覆盖、必须填写 reason 的路径范围忽略规则，以及适用于已有发现项的计数基线。

由 Agent 执行

claude mcp add ooxml-integrity -- ooxml-integrity mcp

Agent 可以在编辑完文档后、返回文件前运行相同的检查。ooxml-integrity mcp 是一个本地 MCP 服务，包含两个工具：check 和 compare；它通过标准输入和标准输出通信，不会打开套接字。调用会返回 check --json --coverage 的报告和一行结论。MCP 指南提供了 Claude Code、Codex 和 OpenCode 的配置。

从 Python 使用

from ooxml_integrity import check, compare

for f in check("edited.docx"):
    print(f.code, f.severity.value, f.message, f.where)

for f in compare("original.docx", "edited.docx"):
    print(f.code, f.message)

支持 Python 3.9 及更高版本。需要两个依赖项：lxml、fonttools（以及仅用于读取配置文件的 tomli，适用于 Python 3.10 及更早版本）。如果控制台脚本不在 PATH 中，可在任何位置运行 python -m ooxml_integrity check report.docx。

报告内容及覆盖范围

每条发现项都有稳定的代码和严重性，并会尽可能标明部件、形状或 XPath。会隐藏内容或其审计轨迹的丢失属于错误；仅影响外观的丢失属于警告。未定义的段落样式和表格样式仍属于错误，因为它们可能包含编号和结构信息；未定义的字符样式则属于警告。 这些表格描述的是 0.10.0。在 0.4.0 中，未定义的字符样式属于错误；升级后可使用 --fail-on warn，继续将其视为失败。

.docx：

代码	检查
PKG001-008	OPC 包完整性、内容类型、归档预算、不安全的部件名称
PKG009	0.4.4：不支持 Strict Open XML，因此未运行 Word 检查；报告为错误
PKG010	0.7.0，ERROR：主文档关联的某个部件，其声明的内容类型与其关系类型要求的不一致，例如 Codex 的 commentsExtended 部件，Word for Mac 会拒绝此类部件；范围和语料运行
PKG011	0.8.3，ERROR：[Content_Types].xml 中某个扩展名出现第二个 Default，或某个部件名称出现第二个 Override，比较方式与 OPC 相同；即使第二个条目与第一个相同，Word for Mac 也会拒绝该包；Word 检查
PKG012	0.8.4，ERROR：Override 的部件名称转义了非保留字符、斜杠、反斜杠或非 ASCII 字符，或包含未以有效转义序列开头的 %；Word for Mac 会拒绝此类情况；Word 检查
XML001	每个 XML 部件格式良好
REL001-003	r:id / r:embed / r:link 引用可解析；目标存在；存在未引用的关系
REL004	0.8.3，ERROR：同一个关系部件中的两个关系使用了相同的 Id；Word for Mac 会拒绝此类情况；Word 检查
STY001	未定义的段落/表格样式：错误；未定义的字符样式：警告
STY002	未定义的 basedOn / next / link 样式引用：警告；0.4.5：next / link 为信息
NUM001-004	numId → w:num → abstractNumId → w:abstractNum；ilvl 已定义
FTN001-002	脚注引用可解析；存在孤立脚注
CMT001-006	批注范围/引用 ↔ 相关批注部件；存在无法解析或无法读取的批注部件
CMT007	0.10.0，ERROR：某个故事中，一个批注 ID 对应第二个 commentRangeStart、commentRangeEnd 或 commentReference；已关闭的 python-docx PR #1605 在设置某条批注的第一个段落文本时，将该文本分成两部分写入；文本框在 mc:Fallback 中的副本不计入
REV001-003	已验证的段落标记/内容配对之外存在修订 ID 冲突；w:del 包含 w:delText，并遵循合法的 w:ins > w:del 嵌套
TBL001-002	存在 tblGrid；比较每行单元格数与网格列数，并考虑 gridSpan
SDT001-002	内容控件完整性
TXT001	未设置有效 xml:space="preserve" 的文本片段中存在 XML 边缘空白
TXT002	WARN：XML 解码后出现字面数字标点/符号拼写，可能表明发生了双重转义；范围和意图歧义
FID000	无法运行请求的源文件比较
FID001-003	按结构计数，与源文件相比存在内容丢失和新增（0.10.0：也包括尾注引用和分节符）；文本量减少
FID004-006	编辑后的文件中缺少批注、脚注或尾注文本，允许 ID 发生变化；0.4.6：带修订标记的编辑不算丢失
FID007-008	页眉/页脚故事缺失或发生未跟踪的更改（0.4.6）；页眉/页脚中丢失了带修订标记的结构
FID009	0.4.2：在受支持的主文档配置中，包装元素数量相同，但字面插入/删除文本缺失；限制
FID010	0.4.2：在填充量相同的脚注/尾注文本组中，保留插入/删除标记的注释数量减少；限制
FID011	WARN：保留了源文件中的插入文本，并在其原有作者/日期上下文中增加了字符，但没有独立的新插入上下文；范围和意图歧义
FID012	0.4.9，INFO：按故事（正文、页眉/页脚位置、注释）、类型和作者列出编辑所添加的修订，以便预期可以要求在正确位置进行带修订标记的编辑
FID013	0.5.1，WARN：编辑所添加的带修订标记替换中，删除并重新插入的未更改词语多于更改的词语（至少四个），导致审阅者看到未更改的文本被删除线标出后又重新添加；范围
FID014	0.8.0，INFO：列出编辑更改过文本的段落，以及更改前后的文本和接受、拒绝修订后的文本，以便预期可以要求文本达到编辑任务要求的结果
FID015	0.10.0：源文件中的书签已丢失。若编辑后的文件中仍有 REF、PAGEREF 或 NOTEREF 字段指向该书签，则报 ERROR；更新字段时，Word 会显示“错误！未找到引用源。”或“错误！未定义书签。”；若只有内部链接指向该书签，或没有任何内容指向该书签，则报 WARN；无人指向的隐藏书签（_GoBack、_Hlk…）不予报告；范围和语料运行
FID016	0.10.0：按故事和类型列出源文件中丢失的字段（REF、TOC、PAGE 等）。丢失 REF、PAGEREF 或 NOTEREF 时，或某一类型的字段全部丢失时，报 ERROR；否则报 WARN。字段由其类型及其指向的书签构成；不比较开关、简单或复杂形式，以及嵌套在其他字段结果中的字段（如目录中的条目）；范围和语料运行
INT001	检查引发异常且未能完成：错误；其他检查仍会运行，覆盖率报告会将该检查的范围标记为 skipped
EXP001	0.4.8：声明的预期（--expect 或 [[expect]]）未匹配到任何发现，所请求的更改并未发生；预期的更改
.pptx：

code	检查项
PPT000	无法测量文本；报告为错误
PKG009	0.4.4：不支持 Strict Open XML，因此未运行布局检查；报告为错误
XML001、PKG003-005、PKG011、PKG012、REL001、REL002、REL004	0.9.0：.docx 的包规则，说明 PowerPoint for Mac 的行为；缺少缩略图或 SmartArt 绘图属于 REL002 WARN；PowerPoint 检查
PPT001	文本高度超出文本框，且超过测量容差
PPT002	预测的文本高度超出文本框最多 5%——临界溢出
PPT003	文本行超出可用宽度：未启用换行，或单个字形过宽
PPT004	形状超出幻灯片边缘，或完全位于幻灯片外
PPT005	要求缩小以适应，但未存储 fontScale——结果取决于渲染器
PPT006	两个包含文本的形状重叠
PPT007	声明的字体不可用；这些形状的测量值为估算值
INT001	检查引发错误且未完成：错误；仍会运行其他检查，覆盖率报告会将该检查涉及的范围标记为 skipped

使用 --coverage 查看结果的范围。它会按文件区分各个范围的状态：checked、not-present、estimated、skipped 和 unsupported；若结果存在缺口，则会注明 no findings in checked surfaces，而不是 clean。ooxml-integrity doctor 会报告当前机器上有哪些测量功能可用。 请参阅支持矩阵和覆盖率与 doctor。

局限性

• DOCX 证据语料库使用了来自五种产品（Word for Windows、Word for Mac、Word Online、LibreOffice、python-docx）的 50 个合成来源和 220 对标注样本：120 对无缺陷对照样本和 100 对注入缺陷的样本。记录的结果显示，错误级别的真阳性有 111 个，假阳性和假阴性均为零。100% 的精确率和召回率适用于该语料库及其标注的 14 条规则；其他规则未在此处测量。尚未测量在客户文档上的准确率。
• 单独的现有修订样本包含 30 对样本：15 对在 adeu、Word Online 和 Word for Windows 中保留审阅内容的对照样本；九个注入缺陷（历史检查器修订版：检测出七个，漏检两个；0.4.2 的 FID009/FID010 后续测试：检测出九个）；以及六个被排除在保留指标之外的接受/拒绝特征样本。各产品组单独报告。三次 Windows 保存保留了修订，但更改了表格宽度；尚未测量布局是否保持不变，也未测量更广泛的 Office 审阅操作。
• 审阅历史基准测试使用了两份专门编写的合同、每种工具和 Agent 的一个版本，以及一个 Word for Mac 构建版本来确认每种损坏。它比较审阅内容，不比较格式或布局。
• PPTX 证据来自 PowerPoint for Mac 的编辑视图检查，以及后续回归测试演示文稿的原生导出。未测试 Windows 和幻灯片放映模式。未应用 GPOS 字距调整和字形塑形，因此复杂文字脚本和大量连字字体的结果为估算值。
• 演示文稿中的组合形状、表格、SmartArt 和图表未建模。旋转形状的几何检查仅部分支持。
• 仅测量过 Carlito/Calibri 这一度量兼容字体组合。

完整清单及各项依据的数据见docs/research.md。

后续计划

基准测试表明，面对相同的请求，不同工具和 Agent 在同一份文档上可能保留或丢失审阅信息；而告知检查器所请求的更改后，它就能区分这两种情况。这些文档是专为基准测试编写的。接下来的问题是，检查器在真实的审阅文档和真实流水线对这些文档所做的编辑中表现如何。

如果你的工作流包含自动 DOCX 编辑，随后由人工审阅，可以用一组本地的修改前后文档进行一次 30 分钟试点。 分享反馈，告诉我们有用的发现、误报、漏检缺陷或设置问题。请附上生成器和检查器版本、发现代码以及预期行为与实际行为。GitHub 报告是公开的；是否附上文档由你决定。

如需附上机密文档对，请先将其匿名化。副本会保留结构并移除文本、作者、日期、属性和图片，而命令会检查所有发现是否仍然存在：

ooxml-integrity anonymize original.docx edited.docx -o share/

了解匿名化会替换哪些内容、读者仍能从中了解什么，以及如何评估效果。

贡献与兼容性

请参阅 CONTRIBUTING.md，了解如何提交可复现的报告、开发环境设置、证据要求以及 PR 相关检查。 兼容性与升级介绍规则代码、严重级别、JSON/覆盖率版本、基线迁移，以及即使在补丁版本中也可能影响 CI 门禁的更改。如需报告敏感漏洞，请使用 SECURITY.md 中的私密渠道。

仓库布局

src/ooxml_integrity/   inspector, fidelity, fonts, pptx layout and checks,
                       coverage, doctor, policy, sarif, cli, MCP server
tests/                 labelled-corpus, story-fidelity and false-positive regressions
research/              corpus builders, mutators, calibration, renderer comparison
docs/                  research notes, configuration, support matrix, validation records
demo/                  browser checker, landing page, bundled fonts and examples
corpus/                reference .docx and .pptx, byte-reproducible
evidence/docx-beta/    50 producer sources and 220 labelled DOCX pairs
evidence/docx-revisions/  30 pairs with existing revisions and explicit known misses
evidence/review-history-benchmark/  frozen protocol, tool and agent captures, evaluation
runs/                  the first eight agent outputs, used as fixtures
action.yml             the GitHub Action

许可证

MIT。