DOCX 创建、编辑与分析技能。
一、用途 该技能适用于用户需要创建、读取、编辑或操作 Word 文档（.docx 文件）或 Word 模板（.dotx 文件）的场景。
二、基本原理与任务路径 .docx 是一个包含 XML 文件的 ZIP 压缩包。按任务选择处理方式：
- 创建新文档：编写 docx（npm）脚本，注意下方陷阱。
- 编辑现有文档：解压 → 编辑 word/document.xml → 重新打包（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 的编号配置。
- 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/ # 合并碎片化的 run，使文本可被查找
就地编辑 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> run 中（修订 id、拼写检查标记），因此文档中可见的短语在 XML 中往往并不作为连续字符串存在。merge_runs.py 会合并 word/document.xml 中相邻且格式相同的 run，不改变内容或渲染；它也可直接接受 .docx（python scripts/merge_runs.py doc.docx -o merged.docx）。
六、修订跟踪（Tracked changes） 进行修订时，使用 --author "<你进行修订时使用的名称>" 校验（需要 --original）——它会报告任何你修改但未用 <w:ins>/<w:del> 包裹的文本，这种情况容易意外发生且在已接受视图中不可见。用带 w:id、w:author、w:date 属性的 <w:ins>/<w:del> 包裹 run。在 <w:del> 内，文本元素是 <w:delText>，而非 <w:t>。被删除的段落标记（<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>）表示“将此段落合并到下一段”——因此彻底删除一个段落就是该标记加上用 <w:del> 包裹每个 run。<w:del/> 必须位于 rPr 其他子元素之前；其顺序由 schema 强制。
要生成接受所有修订的干净副本：python scripts/accept_changes.py in.docx out.docx。
接受被删除的段落标记应将该段落与下一段合并，因此所有 run 均被删除的段落会消失。Word 会这样做；accept_changes.py 和 pandoc --track-changes=accept 并不总是如此。两者以相同方式失败——它们剥离被删除的文本但留下空段落，当该段落为自动编号时会读作多余的空项目符号：
- pandoc --track-changes=accept 从不合并段落。
- accept_changes.py（LibreOffice）能正确合并，除非被删除段落后面跟着一个空的分隔段落。 任一视图中的空项目符号都是该视图的产物，而非文档缺陷。请在 XML 中检查段落删除情况。
七、批注（Comments） 批注需要六个相互链接的文件。使用辅助脚本——当你还将编辑 document.xml 时用目录模式（省去一次解压/重打包），否则用 .docx 直接模式：
针对已解压的目录（同时放置标记时首选）
python scripts/comment.py unpacked/ "Fees & expenses cap is too low" python scripts/comment.py unpacked/ "Agreed" --parent 0
直接针对 .docx
python scripts/comment.py contract.docx "This cap is too low" -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）