docx

1实现原理 · 为什么它能做到

把 .docx 当『ZIP 容器 + OOXML』处理，按任务类型分三条技术路线：创建走 npm docx-js 编程生成；编辑既有文件走 unzip→改 XML→zip 的外科手术；读取走 pandoc。

skills/docx/SKILL.md

A `.docx` is a ZIP archive of XML files. Choose your approach by task:

创建侧内置一整套『反 footgun』gotcha 知识（A4 默认页、表格双宽度、ShadingType.CLEAR、列表 numbering、ImageRun type、PageBreak 位置、PositionalTab 点线等），把 Word/Google Docs 渲染差异写死成规则。

skills/docx/SKILL.md

**Table shading:** use `ShadingType.CLEAR`, never `SOLID` (renders black).

注：这些是 docx-js API 与真实渲染器（Word/Google Docs/LibreOffice）之间的坑位清单；例如 'Column widths must sum to the table width'、'Never use `\n` — use separate `Paragraph` elements.'

编辑侧先做 runs 归一化再改文本：Word 会把一句话拆成大量 `<w:r>` runs，merge_runs.py 把相邻同格式 runs 合并，使 find-and-replace 在 XML 上可靠。

skills/docx/SKILL.md

Word splits text across many `<w:r>` runs (revision ids, spell-check markers), so a phrase you can see in the document often doesn't exist as a contiguous string in the XML. `merge_runs.py` merges adjacent identically-formatted runs in `word/document.xml` without changing content or rendering

注：merge_runs.py docstring 自述同一机制：'This coalesces adjacent runs whose formatting (<w:rPr>) is identical, strips rsid attributes and proofErr markers'。

验证闭环=『渲染成图再看 + XSD 校验』双轨：soffice 转 PDF→pdftoppm 出图→模型 Read 图片做视觉 QA；validate.py 做 schema/关系/修订一致性检查。

skills/docx/SKILL.md

python scripts/office/validate.py out.docx --original doc.docx # XSD checks; --auto-repair fixes common issues

注：视觉 QA 流程：'python scripts/office/soffice.py --headless --convert-to pdf output.docx' → 'pdftoppm -jpeg -r 100 output.pdf page' → 'ls page-*.jpg # then Read the images'。soffice.py 是沙箱适配包装（AF_UNIX 被禁时用 LD_PRELOAD shim 回退）。

修订（redline）有专门验收工具：validate.py 的 --author 模式检查所有改动是否被 `<w:ins>`/`<w:del>` 包住，防止『改了却不可见』的意外。

skills/docx/SKILL.md

it reports any text you changed without a `<w:ins>`/`<w:del>` around it, which is easy to do by accident and invisible in the accepted view

注：正文还给出修订语义细节：'Inside `<w:del>`, the text element is `<w:delText>`, not `<w:t>`.'、删除段落标记=并入下一段的语义，以及 accept_changes.py（LibreOffice 接受修订）与 pandoc 行为差异分析。

批注是『六文件联动』装配：comment.py 自动写 4 个 comments XML + relationships + content-type overrides，再打印要插入 document.xml 的锚点片段。

skills/docx/SKILL.md

The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `commentsExtensible.xml`, the relationships, and the content-type overrides.

注：模板文件在 scripts/templates/（comments*.xml ×4 + people.xml）；comment.py 支持目录模式与 .docx 直改模式（-o 输出）。

对『来自外部的不可信 .docx』有明确防御动作：解包后删除符号链接条目（zip-slip 类攻击面）。

skills/docx/SKILL.md

find unpacked -type l -delete # strip symlink entries — docx from external parties is untrusted

注：这是 prompt 级指引（提示宿主在解包后清 symlink），非脚本强制；结合 XSD 校验与『编辑时不要 pretty-print』约束构成文档手术的安全习惯。

2核心能力

01编程创建专业 Word 文档（TOC/标题层级/页码/信头/表格/点线制表位）

02编辑/重组既有 .docx/.dotx（解包→XML 编辑→回封），含 find-and-replace

03内容读取与抽取（pandoc→markdown），legacy .doc 先 soffice 转 .docx

04Tracked changes：修订标记制作、--author 验收、accept_changes.py 一键接受

05批注装配（六文件联动 + 锚点片段输出）

06XSD 校验 + 渲染视觉 QA 双轨验证（--original 基线化/--auto-repair）

3外部依赖

类型	依赖
package	docx（npm，docx-js）
cli	pandoc（读取 .docx → markdown）
cli	LibreOffice soffice（渲染 QA/接受修订/.doc 转换；经 soffice.py 包装）
cli	pdftoppm（Poppler，PDF 渲染成图）
cli	unzip / zip（解包与回封 OOXML 容器）

4风险提醒风险提醒：蓝色 · 知晓即可

风险提醒：蓝色 · 知晓即可

外部 .docx 为不可信输入 — zip-symlink/畸形 XML 等攻击面靠提示级指引缓解（无脚本强制）；恶意文档的解析暴露面最终在宿主工具与解析器。
XML 直改易损坏文档 — 直接编辑 word/document.xml 要求精确的 XML 语义（转义、命名空间、元素顺序），模型出错会产出坏文件；validate.py 能拦一部分但不是全部。
运行时 gcc 编译 shim — soffice.py 在受限环境会调用本机 gcc 编译 C shim 并 LD_PRELOAD——代码自包含无害，但『skill 触发本机编译』值得知晓。
强环境依赖 — docx-js/pandoc/soffice/pdftoppm 需预装；缺失时条件安装会引入网络与版本不确定性。
专有许可 — LICENSE.txt 为 Anthropic 服务条款式专有许可（含 ADDITIONAL RESTRICTIONS），非开源——商用/再分发需审阅条款。

风险提醒：蓝色，知晓即可。运行自带 python 脚本 + 本地 CLI（pandoc/soffice/pdftoppm/unzip/zip），读写本地工作区文件，无网络外发（仅 require/import 失败时的条件 npm/pip 回退到官方 registry）、无凭证读取。注意点：① soffice.py 在受限沙箱下会现场 gcc 编译自带的 socket shim（内容自包含、仅本地 AF_UNIX 回退，非恶意）；② 编辑外部 .docx 属处理不可信输入，依赖提示级防御（删 symlink + XSD 校验）；③ XML 直改模式若转义不当会损坏文档。均不构成网络/凭证风险。

5第二遍独立确认

[ok] 『创建走 docx-js』路线与依赖声明 — approach 表与 Dependencies 节一致；npm 包不在仓库内（外部依赖，条件安装）。
[ok] merge_runs 机制（runs 拆分问题） — SKILL.md 描述与 merge_runs.py docstring 相互印证，均原文在。
[ok] redline --author 验收与 accept_changes — 两工具及用法命令行均存在于 SKILL.md，accept_changes.py 存在且 docstring 相符。
[ok] 批注六文件机制与 templates — comment.py 写 4 个 comments xml + rels + content-type（代码 rels/ct 常量可查）；templates/ 5 个 xml 模板（含 people.xml）与脚本引用一致。
[ok] soffice.py 沙箱 shim 无外联 — C shim 仅拦 AF_UNIX socket/listen/accept 做 socketpair 回退；编译产物在 tempdir；无任何网络地址。
[ok] 网络/凭证零命中 — 脚本层无网络调用无 env/token 读取（get_soffice_env 仅拷贝环境变量+设 SAL_USE_VCLPLUGIN/LD_PRELOAD）。
[ok] 功能声明 vs 实现（夸大检查） — description 声称的能力均有对应命令/脚本；'Do NOT use for PDFs, spreadsheets…' 负面边界清晰。唯一无法源码证实的是环境预装假设。
[ok] 元数据 — 本地 HEAD==pin 41bbe19；LICENSE.txt 为 Anthropic 专有条款（© 2025 Anthropic, PBC.），与 SKILL.md frontmatter 'Proprietary' 一致。

6结论

把 Word 的『隐藏复杂度』显式化：runs 拆分、六文件批注、修订语义、渲染怪癖全部写成可执行知识。

编辑→校验→渲染成图 Read 的闭环让模型能自证文档正确。

自带 XSD schema 校验 + 自动修复，比裸 XML 编辑可靠得多。

对不可信输入的防御意识（删 symlink + 明确 'external parties is untrusted'）。

共享 office/ 工具树跨 docx/pptx/xlsx 复用，行为单一来源、维护集中。

适合：适合在受管 sandbox（Claude Code 类，预装 docx-js/pandoc/soffice/poppler）中高频产出/批改 Word 文档、做模板套版、审阅修订与批注的自动化场景；其 validate+渲染 QA 闭环特别适合『交付即可信』要求。

不适合：不适合需要所见即所得可视化编辑器、复杂排版设计探索（表格版式试错成本高）；不适合无 LibreOffice/poppler 的裸环境（验证与 .doc 转换不可用）；不适合对许可合规要求苛刻、不能接受专有条款的组织；不适合纯读取场景（杀鸡用牛刀，pandoc/markitdown 即可）。

安装 agent 直装可复制

① 本站镜像更新 2026-09-09

方式 A · 人下载镜像包下载 docx.tar.gz

sha256: 054b66c290295197…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit 41bbe19d1a；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库anthropics / anthropics/skills

原始 GitHubanthropics/skills ↗

Stars175386

最近推送2026-09-03

本 skill commit41bbe19d1a

本站信息

收录日期2026-09-06

分类文档与知识

侦查报告2026-09-06 · 2 遍

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：蓝色 · 知晓即可

5第二遍独立确认

6结论

4风险提醒风险提醒：蓝色 · 知晓即可