Docx 技能
通过小型 CLI 工具,使用 python-docx 创建、读取、编辑和模板化 Microsoft Word .docx 文件。它处理文本、样式、列表、表格、图片、页眉/页脚、{{token}} 模板变量、跟踪修订(查看/接受/拒绝)、评论(查看/添加/删除)、目录和页码字段以及文档包健康检查。它不直接渲染文档(需要 LibreOffice 转换为 PDF——请参阅“转换为 PDF”部分),也不编辑旧版 .doc 文件。
何时使用
- 用户要求生成 Word 文档(报告、信函、合同)。
- 你需要获取
.docx文件的文本、大纲、样式或嵌入图片。 - 你需要修改现有的
.docx:替换文本、编辑表格单元格、插入/删除段落、应用样式、合并分散的运行块。 - 你有一个包含
{{placeholders}}的.docx模板需要根据数据填充。 - 文档包含需要审核、接受或拒绝的跟踪修订。
- 你需要查看审阅者的评论,或添加/删除评论。
.docx文件无法打开或行为异常,需要进行损坏排查。- 文档需要目录或“第 X 页,共 Y 页”页脚。
- 不适用于:
.doc(旧版)、.odt或所见即所得的布局工作。
前提条件
- Python 3.10+,并安装
python-docx: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) |
操作步骤
- 创建。 编写一个 JSON 规范并使用
write_file,然后运行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文件的顶部。 - 读取。 使用
scripts/docx_read.py,并指定唯一个模式标志。--text返回正文段落、所有表格单元格文本以及页眉/页脚文本,以 JSON 格式输出。--structure返回标题大纲以及段落/表格/节的数量。--images DIR将word/media/下的每个文件都复制到指定目录。 - 编辑。 使用
scripts/docx_edit.py。replace命令会遍历正文、表格(包括嵌套表格)、页眉和页脚,并保留运行块的格式;添加--body-only可跳过页眉/页脚。使用-o out.docx将输出保存到新文件以保留原文件;省略-o则在原文件上直接编辑。insert/delete/style/toc命令的段落索引基于--structure/--text输出的正文顺序。对于经过大量 Word 编辑的文档,首先运行normalize命令——它会合并格式相同的相邻运行块,以便后续的查找替换操作能够可靠匹配。 - 审核修订。
docx_revisions.py list会报告正文、表格、页眉或页脚中所有的w:ins和w:del(包含 id、作者、日期、受影响的文本)。accept-all/reject-all可以批量处理;accept/reject --id N处理单个修订。接受(accept)操作会保留插入内容并删除被标记为删除的文本;拒绝(reject)则相反。 - 评论。
docx_comments.py list返回每条评论的 id、作者、日期、正文文本以及它所锚定的文档文本。add --target "some phrase"会为指定短语的首次出现位置添加一条新评论(必要时会拆分运行块,格式得以保留)。delete --id N会移除该评论及其标记,而不修改文档文本。 - 模板。 在文档中放置
{{name}}形式的标记。运行scripts/docx_template.py并传入一个 JSON 对象作为值。使用--strict可以在存在未填充的标记时失败退出;JSON 输出会始终包含filled填充计数和unfilled_tokens未填充标记列表。 - 验证(始终执行):使用
--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处理运行级别(run-level)的插入和删除(占绝大多数)。段落标记(paragraph-mark)和表格行(table-row)的修订、格式更改记录以及移动操作会被--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检查压缩包、必需部件、关系目标、图片魔数和引用的样式。它不是 XSD 验证——一个文件可能通过检查但仍然包含 Word 不喜欢的 XML。 - 样式名称必须存在。 应用文档中未定义的样式会引发
KeyError错误。内置样式如Heading 1、List Bullet、List Number、Table Grid存在于默认模板中;自定义样式必须先在创建规范中声明。 - 编号列表会重新开始编号。
List Number依赖于 Word 的默认编号方式;一个文档中的多个独立列表可能会继续编号而不是重新开始。如果需要精确的多列表编号,请警告用户。 - 单元格写入会替换格式。
set-cell使用cell.text = ...,这会将单元格中的运行块重置为纯文本格式。 - 编码。 所有 JSON 规范/值文件都显式以 UTF-8 读取;编写自己的胶水代码时不要依赖区域设置默认值。
- 不要解压后对 XML 进行 sed 操作。 通过脚本(或 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确认自定义样式已应用。