Word（DOCX）的创建、编辑与分析

.docx 本质是 ZIP + 内嵌 XML。适用于：新建/读取/编辑 Word、目录与页码、信纸抬头、从 docx 抽取或重组内容、插图、查找替换、修订与批注、将内容整理成正式 Word 文档等。不用于 PDF、电子表格、Google Docs 或与写文档无关的纯编程任务。

速查

| 任务 | 做法 | |------|------| | 读/分析 | pandoc 或解包看 XML | | 新建 | docx-js（npm install -g docx），见下文要点 | | 改已有稿 | 解包 → 改 XML → 再打包 |

老版 .doc 转 .docx

python scripts/office/soffice.py --headless --convert-to docx document.doc

读取内容

pandoc --track-changes=all document.docx -o output.md
python scripts/office/unpack.py document.docx unpacked/

转图片（便于目视检查）

python scripts/office/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

接受所有修订（需 LibreOffice）

python scripts/accept_changes.py input.docx output.docx

新建文档（docx-js）

用 JavaScript 生成 .docx，生成后 必须校验；失败则解包修 XML 再打包。

python scripts/office/validate.py doc.docx

页面尺寸（极其重要）

docx-js 默认 A4，不是美标 Letter。 美标请显式设置（单位 DXA，1440 DXA = 1 英寸）：

• US Letter：宽 12240，高 15840，四边边距常用各 1440（1 英寸）。
• 横向：仍传入「竖向」宽高数值，并设 orientation: PageOrientation.LANDSCAPE，由库内部交换。

样式与标题

• 默认正文字体可用 Arial，标题保持黑色易读。
• 覆盖内置标题样式时 id 必须精确：Heading1、Heading2…，并设 outlineLevel，否则目录（TOC）异常。

列表

禁止手写 • 或 Unicode 项目符号字符。应使用 numbering + LevelFormat.BULLET / DECIMAL。同一 reference 连续编号；不同 reference 会重新从 1 开始。

表格

• 表宽用 WidthType.DXA，不要用百分比（Google Docs 等会坏）。
• 同时设置 columnWidths 与每个单元格的 width，且列宽之和等于表宽。
• 底纹用 ShadingType.CLEAR，不要用易出黑底的 SOLID。
• 给单元格加 margins 做内边距。
• 不要用表格当分隔线：空表会显示成难看条块；改用段落 border 或制表位。

图片

ImageRun 必须 指定 type（png/jpg/…），并填齐 altText 的 title/description/name。

分页

PageBreak 必须放在 Paragraph 的 children 里，不能单独悬空，否则 XML 无效。

目录

TOC 要求标题段 只用 HeadingLevel，不要只靠自定义样式名。

其它要点

• 不要用 \n 拼段落，应多个 Paragraph。
• 脚注、超链接、制表位、多栏等见上游英文 SKILL.md 中的完整代码块。

编辑已有文档（三步）

1. 解包

python scripts/office/unpack.py document.docx unpacked/

会整理 XML、合并相邻 run、把弯引号转成实体等。需要保留原始 run 结构时加 --merge-runs false。

2. 编辑 unpacked/word/ 下 XML

• 修订、批注的作者名默认用 「Claude」，除非用户指定。
• 字符串级替换请直接用编辑工具，不要为小事写 Python 脚本。
• 新增正文中的弯引号请用 XML 实体：’（右单引）、“/”（双引号）等。
• 批注可借助 comment.py（详见上游英文文档）。

3. 打包

python scripts/office/pack.py unpacked/ output.docx --original document.docx

含校验与自动修复（部分问题可修，结构性错误需人工改）。可 --validate false 跳过校验。

常见坑

• 插入修订时 整段替换 w:r，不要把修订标签插在 run 中间弄碎结构。
• 保留原 run 的 w:rPr（粗体、字号等）到新的修订 run 里。

XML 与修订（摘要）

• 元素顺序、xml:space="preserve"、RSID 格式等须符合 Word OOXML 约定。
• 插入用 w:ins，删除用 w:del；段落内用 w:delText 等。
• 删整段 时还要处理段落标记上的删除标记，否则接受修订后会留下空段落。
• 批注范围标记 commentRangeStart/End 与 w:r 同级，不要塞在 w:r 里面。

更完整的 XML 样例（修订嵌套、图片 relationship、多栏等）见上游仓库英文 SKILL.md。

依赖

• pandoc：文本抽取
• docx：npm install -g docx
• LibreOffice：PDF 转换等（scripts/office/soffice.py）
• Poppler：pdftoppm

许可证以上游 LICENSE.txt 为准。