{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Docx

创建、读取、编辑、模板化和审阅 Word .docx 文件。

Skill 元数据

参考：完整 SKILL.md

Docx Skill

通过小 CLI 用 python-docx 创建、读取、编辑和模板化 Microsoft Word .docx 文件。它处理文本、样式、列表、表、图像、页眉/页脚、{{token}} 模板、修订追踪（列出/接受/拒绝）、评论（列出/添加/删除）、目录和页码字段，以及包健康检查。它本身不渲染文档（PDF 需要 LibreOffice——见转换为 PDF），也不编辑旧版 .doc。

何时使用

• 用户要求生成 Word 文档（报告、信函、合同）。
• 你需要 .docx 的文本、大纲、样式或嵌入图像。
• 你必须改既有 .docx：替换文本、编辑表格单元格、插入/删除段落、应用样式、合并碎片 run。
• 你有一个带 {{placeholders}} 的 .docx 模板要从数据填充。
• 文档有修订要审阅、接受或拒绝。
• 你需要读审阅者评论，或添加/删除评论。
• .docx 打不开或行为异常，需要损坏分拣。
• 文档需要目录或"第 X 页 / 共 Y 页"页脚。
• 不用于：.doc（旧版）、.odt 或 WYSIWYG 布局工作。

前置条件

• Python 3.10+，安装 python-docx： pip install python-docx（导入名 docx；lxml 随附）。
• 评论 add 在 python-docx >= 1.2 用原生 API，旧版本用 XML 回退——两者自动。
• 图像块：图像文件须本地存在（PNG/JPEG）。

运行方式

所有辅助脚本位于本文件旁的 scripts/。用 terminal 工具运行；每个支持 --help 并向 stdout 打印 JSON。

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

快速参考

流程

1. 创建。 用 write_file 写 JSON 规格，然后运行 scripts/docx_create.py。规格支持：page（毫米尺寸+边距）、header/footer 字符串、footer_page_numbers（加"第 X 页 / 共 Y 页"字段页脚）、styles（带字体、字号、粗/斜体、十六进制 color 的自定义段落样式），以及 blocks——heading（1-9 级）、paragraph（text 或 runs 列表，每个 run 可设 bold/italic/underline）、bullet_list、numbered_list、table（header 行加粗渲染，rows，可选内置表 style 如 Table Grid）、image（path，可选 width_mm）、toc（目录字段）和 page_break。完整规格格式见 scripts/docx_create.py 顶部。
2. 读取。 用 scripts/docx_read.py，只带一个模式标志。--text 返回正文段落、所有表格单元格文本和页眉/页脚文本为 JSON。--structure 返回标题大纲加段落/表/节计数。--images DIR 把 word/media/ 下每个文件拷出包。
3. 编辑。 用 scripts/docx_edit.py。replace 遍历正文、表（含嵌套）、页眉和页脚，保留 run 格式；加 --body-only 跳过页眉/页脚。传 -o out.docx 保留原件；省略则原地编辑。insert/delete/style/toc 的段落索引指 --structure/--text 的正文顺序。从重度 Word 编辑出来的文档先跑 normalize——它合并格式相同的相邻 run，使后续查找替换可靠匹配。
4. 审阅修订。 docx_revisions.py list 报告正文、表、页眉或页脚任何位置的每个 w:ins 和 w:del（id、作者、日期、受影响文本）。accept-all / reject-all 批量解决；accept/reject --id N 处理单条修订。接受保留插入、丢弃删除文本；拒绝相反。
5. 评论。 docx_comments.py list 返回每条评论的 id、作者、日期、正文和它锚定的文档文本。add --target "some phrase" 把新评论锚定到该短语首次出现处（按需拆分 run；格式保留）。delete --id N 移除评论及其标记，不碰文档文本。
6. 模板。 在文档中放 {{name}} 风格 token。运行 scripts/docx_template.py，传值的 JSON 对象。用 --strict 在 token 未填充时失败；JSON 输出无论如何都列出 filled 计数和 unfilled_tokens。
7. 验证（总是）：用 --text 或 --structure 重读输出，并对任何经修订/评论手术产出的内容跑 docx_validate.py。

转换为 PDF

无需脚本。安装 LibreOffice 后，无头转换：

soffice --headless --convert-to pdf --outdir outdir/ file.docx

先检查可用性（command -v soffice || command -v libreoffice）。两者都无，则告知用户此环境 PDF 转换不可用，而非临时凑合——python-docx 不能渲染 PDF，布局保真需要真实渲染器。

常见陷阱

• token 跨 run 拆分。 Word 常把文本碎片成多个 run。替换辅助折叠匹配的 run（替换继承第一个 run 的格式）；先跑 docx_edit.py normalize 减少碎片，利于后续所有编辑。
• 修订覆盖。 docx_revisions.py 解决 run 级插入和删除（绝大多数）。段落标记和表行修订、格式变更记录和移动由 --revisions 检测但不自动解决——见 references/revisions-and-comments.md，把这些交给 Word。
• 评论线程。 回复和"已解决"状态存于 commentsExtended.xml，本 skill 忽略；它添加的评论是普通顶层评论。
• 字段结果由 Word 计算。 toc、page-numbers 及 toc/footer_page_numbers 规格选项写字段代码。Word/LibreOffice 在打开文件时填充实际条目和编号（Word 可能提示更新字段）；python-docx 从不计算它们，因此此前显示占位文本。
• 校验是健康检查，非 schema 校验。 docx_validate.py 验证 zip、必需部件、关系目标、图像魔数字节和引用样式。它不是 XSD 校验——文件可能通过却仍含 Word 不喜欢的 XML。
• 样式名必须存在。 应用文档中未定义的样式会抛 KeyError。Heading 1、List Bullet、List Number、Table Grid 等内置在默认模板中存在；自定义样式须先在创建规格中声明。
• 编号列表重启。 List Number 依赖 Word 默认编号；同一文档中的多个列表可能续编而非重启。需要精确多列表编号的用户请提醒。
• 单元格写入替换格式。 set-cell 用 cell.text = ...，把该单元格 run 重置为纯格式。
• 编码。 所有 JSON 规格/值文件显式按 UTF-8 读取；写自己的粘合代码时绝不依赖 locale 默认。
• 不要解压后 sed XML。 通过脚本（或 python-docx）编辑；在 document.xml 中裸文本替换容易损坏文件。patch/write_file 只用于 JSON 输入，绝不用于 .docx 本身。

验证

• 创建/编辑/模板后，跑 docx_read.py out.docx --text，检查预期字符串出现（旧字符串消失）。
• 接受/拒绝后，docx_revisions.py list 应返回 []（或只有你有意留下的 id）；评论手术后，docx_comments.py list 应反映变更，且 --text 输出不变。
• docx_validate.py out.docx 在健康包上退出 0 且 "ok": true——任何修订/评论/字段操作后都跑它。
• 用 --strict 运行的模板，或检查 unfilled_tokens == []。
• 结构检查：--structure 应显示预期标题大纲和表形状；--styles 确认自定义样式已应用。