docx

DOCX 创建、编辑与分析

.docx 是由 XML 文件组成的 ZIP 压缩包。请根据任务选择方法：

任务	方法
创建新文档	编写 docx（npm）脚本，参见下方的注意事项
编辑已有文档	unzip → 编辑 word/document.xml → zip（docx-js 无法打开已有文件）
读取内容	pandoc -t markdown file.docx

下方的脚本路径均相对于此 Skill 的目录。

使用 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 文档中会失效）。列宽之和必须等于表格宽度。
• **表格底纹：**使用 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   # then Read the images

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   # strip symlink entries — docx from external parties is untrusted
python scripts/merge_runs.py unpacked/   # coalesce fragmented runs so text is findable
# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx   # XSD checks; --auto-repair fixes common issues
# redlining? add --author "<the name you redlined under>" to check every edit is tracked

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 其他子元素之前，这些子元素的顺序由 schema 强制规定。

要生成接受所有修订后的干净副本：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 直接模式：

# Against an already-unpacked directory (preferred when also placing markers)
python scripts/comment.py unpacked/ "Fees & expenses cap is too low"
python scripts/comment.py unpacked/ "Agreed" --parent 0

# Against a .docx directly
python scripts/comment.py contract.docx "This cap is too low" -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）