docx

Docx 技能

通过小型 CLI 使用 python-docx 创建、读取、编辑和套用模板处理 Microsoft Word .docx 文件。它支持文本、样式、列表、表格、图片、页眉/页脚、{{token}} 模板填充、修订（列出/接受/拒绝）、批注（列出/添加/删除）、目录和页码字段，以及文档包健康检查。它本身不渲染文档（生成 PDF 需要 LibreOffice — 参见“转换为 PDF”），也不编辑旧版 .doc 文件。

适用场景

• 用户要求生成 Word 文档（报告、信函、合同）。
• 你需要获取 .docx 的文本、大纲、样式或嵌入图片。
• 你必须修改现有 .docx：替换文本、编辑表格单元格、插入/删除段落、应用样式、合并分散的文本片段。
• 你有一个包含 {{placeholders}}、需要用数据填充的 .docx 模板。
• 文档中有需要审核、接受或拒绝的修订。
• 你需要读取审阅者的批注，或添加/删除批注。
• .docx 无法打开或表现异常，你需要排查损坏问题。
• 文档需要目录或“第 X 页，共 Y 页”页脚。
• 不适用于：.doc（旧版）、.odt 或所见即所得的版式编辑。

前置条件

• 安装了 python-docx 的 Python 3.10+： pip install python-docx（导入名称为 docx；它会一并安装 lxml）。
• add 批注功能在 python-docx >= 1.2 时使用原生 API，在较旧版本中使用 XML 回退方案，两者均会自动处理。
• 图片块所用的图片文件必须存在于本地（PNG/JPEG）。

运行方法

所有辅助脚本都位于与此文件同级的 scripts/ 目录中。使用 terminal 工具运行；每个脚本都支持 --help，并将 JSON 输出到 stdout。

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

快速参考

任务	命令
根据 JSON 规范创建文档	docx_create.py spec.json out.docx
完整文本（正文+表格+页眉/页脚）	docx_read.py f.docx --text
标题大纲和表格结构	docx_read.py f.docx --structure
实际使用的样式	docx_read.py f.docx --styles
提取嵌入图片	docx_read.py f.docx --images outdir/
检测修订/批注	docx_read.py f.docx --revisions
查找/替换（保留格式）	docx_edit.py replace f.docx --find A --replace B -o out.docx
设置表格单元格	docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
在索引 N 前插入段落	docx_edit.py insert f.docx --index N --text X --style Normal
删除段落 N	docx_edit.py delete f.docx --index N
为段落 N 应用样式	docx_edit.py style f.docx --index N --style "Heading 1"
合并格式相同且相邻的文本片段	docx_edit.py normalize f.docx -o out.docx
在段落 N 前插入目录字段	docx_edit.py toc f.docx --index N -o out.docx
“第 X 页，共 Y 页”页脚字段	docx_edit.py page-numbers f.docx
填充 {{tokens}}	docx_template.py tpl.docx values.json out.docx --strict
列出修订（ID/作者/日期/文本）	docx_revisions.py list f.docx
接受/拒绝所有修订	docx_revisions.py accept-all f.docx -o out.docx（或 reject-all）
接受/拒绝单条修订	docx_revisions.py accept f.docx --id 3 -o out.docx
列出批注（含锚定文本）	docx_comments.py list f.docx
添加锚定到文本的批注	docx_comments.py add f.docx --target "phrase" --text "note" --author You
按 ID 删除批注	docx_comments.py delete f.docx --id 0
检查文档包健康状况	docx_validate.py f.docx（出错时退出码为 1）

流程

1. 创建。 使用 write_file 编写 JSON 规范，然后运行 scripts/docx_create.py。该规范支持：page（以 mm 为单位的尺寸和边距）、header/footer 字符串、footer_page_numbers （添加“Page X of 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}} 样式的标记。使用 JSON 对象提供值，运行 scripts/docx_template.py。使用 --strict 可在仍有标记未填充时失败；无论是否使用该参数，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，且要保证布局保真度，必须使用真正的渲染器。

注意事项

• 令牌被拆分到多个运行中。 Word 经常会将文本拆分成多个运行。替换辅助程序会合并匹配的运行（替换内容会继承第一个运行的格式）；先运行 docx_edit.py normalize 可减少文本碎片化，便于后续所有编辑。
• 修订范围。 docx_revisions.py 可处理运行级别的插入和删除（占绝大多数）。段落标记和表格行修订、格式更改记录以及移动操作可通过 --revisions 检测到，但不会自动处理——请参阅 references/revisions-and-comments.md，并交由 Word 处理。
• 评论串联。 回复和“已解决”状态存储在 commentsExtended.xml 中，此技能会忽略该文件；它添加的评论都是普通的顶级评论。
• 字段结果由 Word 计算。 toc、page-numbers 以及 toc/footer_page_numbers 规范选项会写入字段代码。打开文件时，Word/LibreOffice 会填充实际条目和页码（Word 可能会提示更新字段）；python-docx 不会计算这些内容，因此在此之前会显示占位文本。
• 验证是健康检查，不是架构验证。 docx_validate.py 会验证 zip、必需部件、关系目标、图像魔数和引用的样式。这不是 XSD 验证——文件即使通过检查，也仍可能包含 Word 不喜欢的 XML。
• 样式名称必须存在。 应用文档中未定义的样式会引发 KeyError。默认模板中包含 Heading 1、List Bullet、List Number、Table Grid 等内置样式；必须先在创建规范中声明自定义样式。
• 编号列表会重新开始。 List Number 依赖 Word 的默认编号；同一文档中的不同列表可能会接续编号，而不是重新开始。对于需要精确控制多个列表编号的用户，请提前说明这一点。
• 单元格写入会重置格式。 set-cell 使用 cell.text = ...，这会将该单元格中的运行重置为普通格式。
• 编码。 所有 JSON 规范/值文件都会显式按 UTF-8 读取；编写自己的胶水代码时，切勿依赖区域设置默认值。
• 不要解压后用 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 后会以 "ok": true 退出，退出码为 0——任何修订/评论/字段操作后都要运行此命令。
• 对模板运行时使用 --strict，或检查 unfilled_tokens == []。
• 结构检查：--structure 应显示预期的标题大纲和表格形状；--styles 可确认自定义样式已应用。