Communitygithub.com

V4TIME/V4SKILL

创建、读取、编辑、模板化并审核 Microsoft Word .docx 文件。

V4SKILL 是什么?

这是一个专注于处理 Microsoft Word .docx 文件的 AI 代理技能。它基于 python-docx 库,通过小型 CLI 工具实现了对 .docx 文件的完整生命周期管理,包括从头创建、读取内容、编辑修改、基于模板填充以及审核修订和评论。该技能支持处理文本、样式、列表、表格、图片、页眉/页脚、`{{token}}` 模板变量、跟踪修订(查看/接受/拒绝)、评论(查看/添加/删除)、目录和页码字段,还包含文档包健康检查功能。它适用于 Claude Code、Cursor 和 Codex 等支持终端命令的 AI 代理平台。通过一系列专用脚本,开发者可以精确控制文档的每个部分,例如使用 JSON 规范创建文档、替换文本、设置表格单元格、插入或删除段落、合并格式化运行块等。需要注意的是,该技能不直接渲染 PDF(需要通过 LibreOffice 转换),也不支持处理旧版 `.doc` 格式。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/docx

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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
删除段落 Ndocx_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. 创建。 编写一个 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 文件的顶部。
  2. 读取。 使用 scripts/docx_read.py,并指定唯一个模式标志。--text 返回正文段落、所有表格单元格文本以及页眉/页脚文本,以 JSON 格式输出。--structure 返回标题大纲以及段落/表格/节的数量。--images DIR 将 word/media/ 下的每个文件都复制到指定目录。
  3. 编辑。 使用 scripts/docx_edit.py。replace 命令会遍历正文、表格(包括嵌套表格)、页眉和页脚,并保留运行块的格式;添加 --body-only 可跳过页眉/页脚。使用 -o out.docx 将输出保存到新文件以保留原文件;省略 -o 则在原文件上直接编辑。insert/delete/style/toc 命令的段落索引基于 --structure/--text 输出的正文顺序。对于经过大量 Word 编辑的文档,首先运行 normalize 命令——它会合并格式相同的相邻运行块,以便后续的查找替换操作能够可靠匹配。
  4. 审核修订。 docx_revisions.py list 会报告正文、表格、页眉或页脚中所有的 w:ins 和 w:del(包含 id、作者、日期、受影响的文本)。accept-all / reject-all 可以批量处理;accept/reject --id N 处理单个修订。接受(accept)操作会保留插入内容并删除被标记为删除的文本;拒绝(reject)则相反。
  5. 评论。 docx_comments.py list 返回每条评论的 id、作者、日期、正文文本以及它所锚定的文档文本。add --target "some phrase" 会为指定短语的首次出现位置添加一条新评论(必要时会拆分运行块,格式得以保留)。delete --id N 会移除该评论及其标记,而不修改文档文本。
  6. 模板。 在文档中放置 {{name}} 形式的标记。运行 scripts/docx_template.py 并传入一个 JSON 对象作为值。使用 --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 处理运行级别(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 确认自定义样式已应用。

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

相关技能