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元素。 - 目录： 标题必须使用内置的
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/ # 合并碎片化的 runs，使文本可查找
# 原地编辑 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:ins>/<w:del> 中，并附带 w:id、w:author、w:date 属性。在 <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 会自动分配。然后它会打印出 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 片段，需要添加到 word/document.xml 中，以便注释锚定到特定文本——在放置这些标记之前，注释存在但不可见。
依赖项
docx (npm, 已预安装 — 仅当 require('docx') 失败时安装) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)