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:
路线选择表：'| **Create** a new document | Write a `docx` (npm) script — see gotchas below |'、'| **Edit** an existing document | `unzip` → edit `word/document.xml` → `zip` (docx-js cannot open existing files) |'。docx-js 不能打开既有文件，所以编辑必须回到 XML 层。
创建侧内置一整套『反 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外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| 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管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: merge_runs.py / comment.py / accept_changes.py / validate.py / soffice.py（p
- 本地工作目录: 文件读写与工件输出: 输出/中间 .docx（unzip 解包目录、zip 回封、out.docx）
审计说明： 。运行自带 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结论
适合： 适合在受管 sandbox（Claude Code 类，预装 docx-js/pandoc/soffice/poppler）中高频产出/批改 Word 文档、做模板套版、审阅修订与批注的自动化场景；其 validate+渲染 QA 闭环特别适合『交付即可信』要求。
不适合： 不适合需要所见即所得可视化编辑器、复杂排版设计探索（表格版式试错成本高）；不适合无 LibreOffice/poppler 的裸环境（验证与 .doc 转换不可用）；不适合对许可合规要求苛刻、不能接受专有条款的组织；不适合纯读取场景（杀鸡用牛刀，pandoc/markitdown 即可）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload docx.tar.gz
sha256:
Option B · Copy Guide for Agent054b66c290295197…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 41bbe19d1a.