docx

Word 文档

你已经了解 Word 的功能。这项技能补充了代码中看不到的内容：一个能正确处理修订和批注的库、可捕获未跟踪编辑的验证功能、一种查看读者实际看到的页面的方法，以及 docx-js 和 OOXML 中会悄无声息地生成损坏文件的行为。

运行脚本

<skill> 是包含此文件的目录。从用户的工作目录使用绝对路径运行打包的脚本，这样脚本文件的相对路径才能正常工作：

uv run <skill>/ooxml/scripts/unpack.py contract.docx unpacked

运行你编写的 Python 代码时，需声明其依赖项，可以使用 uv run --with defusedxml script.py 或 PEP 723 标头。运行 Node 脚本时，使用 NODE_PATH=<skill>/node_modules node build.js；如果缺少 <skill>/node_modules，请在 <skill> 中运行一次 npm install。渲染页面需要 LibreOffice（soffice）和 poppler（pdftoppm）；读取文档需要 pandoc。

选择工作流

任务	使用方法
阅读文本	pandoc --track-changes=all file.docx -t markdown。它还会显示修订和批注。使用 accept 或 reject 代替 all，即可查看相应的结果。
创建文档	docx-js：先阅读 docx-js.md。其中介绍了页面大小、样式和图像相关的行为，否则这些问题可能会导致文件损坏。
编辑他人的文档，或任何法律、学术、商业或官方文档	使用修订，让每项编辑都可供审阅：参见下方的修订工作流。
对本次会话中创建的文档进行小幅编辑	使用同一个库，但不跟踪更改。完成编辑后，调用 doc.save(require_tracking=False)，它仍会检查架构。若需进行较大改动，请使用 docx-js 重新生成文件。
批注、元数据、嵌入式媒体、原始结构	解包并读取 XML；ooxml.md 介绍了相关模式。

修订工作流

1. 阅读。 使用 pandoc（见上文）转换文档，并列出你将进行的所有更改。根据周围的文本定位每处更改，切勿使用 Markdown 行号，因为它们与 XML 中的位置无关。
2. 解包。 uv run <skill>/ooxml/scripts/unpack.py contract.docx unpacked 会打印建议的 RSID。将其作为 Document(..., rsid=...) 的参数传入，使本次会话中的编辑共用一个修订 ID。
3. 编辑。 阅读 ooxml.md，然后编写一个使用 Document 库的脚本。tracked_replace(old, new) 可处理大多数编辑：它会跨多个文本片段查找内容，并仅标记存在差异的词语。将相关更改分批处理，每个脚本处理几项到十几项，以便出错时容易定位。在每批编辑前再次对 unpacked/word/document.xml 执行 Grep，因为每次保存后行号都会变化。
4. 保存。 doc.save() 会拒绝写入包含未跟踪编辑或违反架构的 XML 的文档，并指出具体差异。请修复脚本，而不是跳过验证。
5. 打包。 uv run <skill>/ooxml/scripts/pack.py unpacked reviewed.docx 会重新打包文件，并检查 LibreOffice 是否能打开它。
6. 验证。 运行 pandoc --track-changes=all reviewed.docx -t markdown，确认所有预期更改均已显示，且没有其他内容发生变化。然后检查输出（见下文）。

若要接受或拒绝现有更改，请在进行自己的编辑前调用 doc.accept_all_changes() 或 doc.reject_all_changes()。

检查输出

1. 验证。 uv run <skill>/ooxml/scripts/validate.py reviewed.docx --original contract.docx 会检查架构，并确认原始文档中的每项更改都已跟踪；doc.save() 也会执行相同的检查。传入 --author NAME，即可直接编辑该作者先前插入的内容。对于从头生成的文档，省略 --original，只检查架构。
2. 查看。 uv run <skill>/ooxml/scripts/render.py reviewed.docx pages 会为每一页打印一个 PNG 路径（使用 --pages 2-4 指定页码范围）。交付你创建或重新整理的文档前，请先查看这些图像。LibreOffice 会将 docx-js 生成的目录渲染为空白；Word 打开文件时会填充目录。

会导致静默失败的陷阱

• 在其他作者的更改中进行部分编辑。 要删除他人插入内容中的文本，请将你的 <w:del> 嵌套在其中。切勿直接编辑他们的文本。
• 将 pandoc 用作编辑器。 它会重写整个文档，并丢弃格式、批注和修订记录。可用它来读取，但不要用它来生成交付成果。