DOCX 创建、编辑和分析
.docx 文件是一个 XML 文件的 ZIP 压缩包。根据任务选择方法：
| 任务 | 方法 |
|---|---|
| 创建新文档 | 编写 docx (npm) 脚本——见下面的注意事项 |
| 编辑现有文档 | unzip → 编辑 word/document.xml → zip (docx-js 无法打开现有文件) |
| 读取内容 | pandoc -t markdown file.docx |
下面的脚本路径相对于此技能的目录。
使用 docx-js 创建——注意事项
docx 已预先安装——不要先运行 npm install；直接编写脚本并使用 require('docx')。仅当该 require 失败时：npm install docx。模型了解 API；以下是容易出错之处：
- 页面尺寸默认为 A4。 要使用 US Letter，设置
page: { size: { width: 12240, height: 15840 } }(DXA；1440 = 1 英寸)。 - 横向页面： 传入纵向尺寸和
orientation: PageOrientation.LANDSCAPE——docx-js 内部会自动交换宽高。 - 表格需要双重宽度： 设置表格的
columnWidths以及每个单元格的width，两者均使用WidthType.DXA（PERCENTAGE 在 Google Docs 中会出错）。列宽之和必须等于表格宽度。 - 表格底纹： 使用
ShadingType.CLEAR，切勿使用SOLID（会渲染为黑色）。 - 列表： 切勿直接插入
•；应使用带有LevelFormat.BULLET的numbering配置。 ImageRun需要type:("png","jpg", ...)。PageBreak必须位于Paragraph内部。- 切勿使用
\n——应使用单独的Paragraph元素。 - 目录 (TOC)： 标题必须使用内置的
HeadingLevel.*；自定义标题样式需要设置outlineLevel，否则不会出现在目录中。 - 不要使用表格作为水平线——改用段落底部边框。
- 点前导符/同一行右对齐： 使用
TextRun内部的PositionalTab(alignment: PositionalTabAlignment.RIGHT,leader: PositionalTabLeader.DOT)，不要使用字面量的.或空格填充。
验证输出
在编写 .docx 之后，将其渲染并查看：
python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg # 然后读取这些图像
pdftoppm 会将页码以总页数的宽度进行零填充（page-01.jpg…page-12.jpg）。
编辑现有文档
旧的 .doc 文件必须先转换：python scripts/office/soffice.py --headless --convert-to docx file.doc。
unzip -q doc.docx -d unpacked/
find unpacked -type l -delete # 移除符号链接条目——来自外部方的 docx 不可信
python scripts/merge_runs.py unpacked/ # 合并碎片化的运行，使文本可查找
# 原地编辑 unpacked/word/document.xml——不要重新格式化或美化打印
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx # XSD 检查；--auto-repair 可修复常见问题
# 进行修订？添加 --author "<进行修订的名称>" 以检查每个编辑是否都被跟踪
Word 会将文本分散到多个 <w:r> 运行中（修订 ID、拼写检查标记），因此你在文档中看到的短语在 XML 中通常不是连续的字符串。merge_runs.py 合并 word/document.xml 中相邻且格式相同的运行，而不更改内容或渲染；它也直接接受 .docx 文件（python scripts/merge_runs.py doc.docx -o merged.docx）。
跟踪修订： 在修订时，使用 --author "<进行修订的名称>"（需要 --original）进行验证——它会报告任何你所更改但未包含在 <w:ins>/<w:del> 中的文本，这很容易无意中造成，并且在已接受视图中不可见。将运行包裹在带有 w:id、w:author、w:date 属性的 <w:ins>/<w:del> 中。在 <w:del> 内部，文本元素是 <w:delText>，而不是 <w:t>。一个被删除的段落标记（<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>）意味着“将此段落合并到下一段”——因此直接删除一个段落就是该标记加上包围每个运行的 <w:del>。<w:del/> 必须位于 rPr 的其他子元素之前；它们的顺序由模式强制规定。
要生成接受所有跟踪修订的干净副本：python scripts/accept_changes.py in.docx out.docx。
接受一个被删除的段落标记应将此段落与下面的段落合并，因此所有运行都被删除的段落将消失。Word 会这样做；accept_changes.py 和 pandoc --track-changes=accept 并不总是能做到。两者都以相同的方式失败——它们会剥离已删除的文本，但留下空段落，当段落是自动编号时，它看起来像一个多余的空项目符号：
pandoc --track-changes=accept从不会合并段落。accept_changes.py（LibreOffice）可以正确合并，除非被删除的段落后面跟着一个空的间隔段落。
任何一个视图中的空项目符号都是该视图的产物，而不是文档的缺陷。请在 XML 中检查段落删除。
批注
批注需要六个交叉引用的文件。使用辅助程序——当你还将编辑 document.xml 时使用目录模式（节省一次解压/重新压缩的循环），否则使用 .docx 直接模式：
# 针对已解压的目录（放置标记时首选）
python scripts/comment.py unpacked/ "费用及支出上限过低"
python scripts/comment.py unpacked/ "同意" --parent 0
# 直接针对 .docx 文件
python scripts/comment.py contract.docx "此上限过低" -o annotated.docx
该脚本会写入 comments.xml、commentsExtended.xml、commentsIds.xml、commentsExtensible.xml、关系文件以及内容类型覆盖。批注 ID 会自动分配。然后它打印需要添加到 word/document.xml 的 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 代码片段，以便批注锚定到特定文本——在放置这些标记之前，批注存在但不可见。
依赖项
docx (npm，已预先安装——仅当 require('docx') 失败时才安装) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)