<!-- title: AI改Word不毁稿：官方docx技能拆解 -->

# AI改Word不毁稿：官方docx技能拆解

**概述**：本期把 Anthropic 官方技能库里的 docx 技能拆到行级——它是「文档四件套」（docx/pdf/pptx/xlsx）中最能体现 Skill 设计功力的一位：SKILL.md 开篇一句话给模型装上正确心智模型，中段用十三条「Critical Rules」把踩坑史写成禁令，编辑线为 LLM 预处理输入，修订线把职场协作礼节直接编码进 XML 操作规则。全文引用均来自技能包原文，看完你可以直接照抄这套写法。

---

## 一、先看全貌：一个技能包的解剖图

docx 技能的目录结构是这样的：

```text
docx/
├── SKILL.md                  # 主文件，约四百行，全部核心逻辑
└── scripts/
    ├── accept_changes.py     # 接受全部修订，产出干净稿
    ├── comment.py            # 加批注，封装五个 XML 文件的联动
    └── office/               # 共享工具箱（四个文档技能公用）
        ├── unpack.py         # docx → 一堆可编辑的 XML
        ├── pack.py           # XML → docx，带校验和自动修复
        ├── validate.py       # 对照 XSD 模式校验
        ├── soffice.py        # LibreOffice 封装，转格式用
        ├── helpers/          # merge_runs.py、simplify_redlines.py
        ├── validators/       # docx.py、pptx.py、redlining.py、base.py
        ├── schemas/          # ISO-IEC 29500-4:2016 全套 XSD + ECMA OPC + 微软扩展
        └── templates/        # comments.xml 等 5 个批注模板
```

三个值得注意的结构信号：

**信号一：SKILL.md 很厚，但厚得有纪律。** 官方技能规范建议 SKILL.md 控制在五百行内，docx 压着上限写——因为 Word 文档的坑太密，它选择把最高频的生成与编辑逻辑全部内联，把 XSD 模式、评论模板这些重资产下沉到 scripts/ 目录。这是标准的渐进式披露：模型先读四百行主文件，只在需要校验细节时才去碰 schemas/。

**信号二：docx 包里躺着 pptx 的校验器。** `validators/` 目录下除了 `docx.py` 还有 `pptx.py`，共享一个 `base.py`。这说明 `office/` 不是 docx 的私产，而是四个文档技能共用的基建层——monorepo 里抽公共库的思路，被原样搬进了技能生态。

**信号三：schemas 目录是一本缩微的标准库。** ISO-IEC 29500-4:2016 的全套 XSD（wml、dml、sml、vml、shared-math……）、ECMA 第四版的 OPC 关系模式，外加微软自扩展命名空间（wml-2010 到 wml-sdtdatahash-2020 共六个年代层）。校验时连微软私有扩展都能查到出处。

```mermaid
flowchart TD
    A["SKILL.md<br/>入口与规则"] --> B["快速路由表"]
    B --> C["读档分析"]
    B --> D["新建：生成线"]
    B --> E["改旧：编辑线"]
    D --> D1["docx-js 写 JS"]
    D1 --> D2["validate.py 校验"]
    D2 --> D3["交付 docx"]
    E --> E1["unpack.py 解包"]
    E1 --> E2["直接改 XML"]
    E2 --> E3["pack.py 打包修复"]
    E3 --> D3
    F["schemas<br/>ISO 29500 全集"] -.-> D2
    G["templates<br/>批注模板五件"] -.-> E2
    H["office 工具箱<br/>四技能公用"] -.-> E1
```

---

## 二、逐行拆：第一句话就是设计

SKILL.md 的 Overview 段只有一句话：

> A .docx file is a ZIP archive containing XML files.

这一句是整个技能的地基。大模型对「Word 文档」的直觉是排版后的页面，一旦带着这个直觉动手，就会去找「保留格式重写全文」的方案——然后毁掉一切。这句话强行把心智模型掰到正确方向：**docx 不是文档，是压缩包；改 Word 就是改 XML**。后面所有工作流都从这个前提出发。给模型写技能，第一句别写功能介绍，写心智模型。

紧跟其后的 Quick Reference 是一张四行路由表：

| 任务 | 方案 |
|------|------|
| 读/分析内容 | pandoc 或解包看原始 XML |
| 新建文档 | docx-js |
| 编辑既有文档 | 解包 → 改 XML → 重打包 |

没有废话，没有背景铺垫，模型扫一眼就知道走哪条产线。读档给 pandoc（快），改档给原生 XML（保真），建档给 JS 库（保证合法）。三条路线的选型逻辑后面细说。

---

## 三、生成线：十三条 Critical Rules 全是伤疤

新建文档不用 Python 的 python-docx，也不用直接写 OOXML，而是让模型写 JavaScript、用 docx-js 库（npm 包名就叫 `docx`）生成。原因很直白：从零生成 OOXML 极易产出非法结构，库帮你兜底合法性；而生成 JS 代码恰好是模型的舒适区。

真正值钱的是后面那组 Critical Rules。逐条归类，你会发现每一条都是一次真实事故的化石：

**第一类：默认值陷阱。**
- 「docx-js 默认 A4 纸，不是 US Letter，必须显式设置页宽页高」——不设，美国用户拿到欧洲纸型。
- 横版页要传竖版尺寸、让库内部交换宽高——因为「docx-js 在 XML 层自己换」，直接传横版数字会翻车。这种反直觉行为不写进技能，模型永远猜不对。

**第二类：跨平台兼容。**
- 表格宽度「永远用 DXA 绝对单位，PERCENTAGE 在 Google Docs 上会崩」——一条规则同时覆盖了 Word、Google Docs、WPS 三端的渲染差异。
- 底纹必须 `ShadingType.CLEAR` 而非 SOLID，否则整格黑底。
- 页尺寸表甚至给出了换算常数：1440 DXA = 1 英寸，US Letter 内容宽度 9360 DXA。模型不用心算，直接查表。

**第三类：XML 合法性。**
- 「永远不要用 `\n`」——换行必须拆成独立 Paragraph，否则产出非法结构。
- 「永远不要手插 unicode 圆点 `•`」——项目符号必须走 numbering 配置，否则 Word 里它不是列表，是长得像列表的普通段落。
- PageBreak 必须包在 Paragraph 里，「裸写会产生非法 XML」。
- ImageRun 必须带 `type` 参数，altText 三个字段缺一不可（无障碍要求）。

**第四类：可维护性。**
- 覆盖内置样式必须用精确 ID（`Heading1` 而非自造名），且要带 `outlineLevel`，否则目录（TOC）抓不到标题。
- 「不要拿表格当分隔线」——单元格有最小高度，渲染成空盒子；分隔线应该用段落的下边框实现。

这十三条没有一条是「最佳实践」式的空话，全是「不这么做就会坏」的硬约束。写自己技能时照此办理：**你的负向清单长度，等于你踩过的坑的总深度。**

---

## 四、编辑线：为 LLM 预处理输入的三步 surgery

编辑既有文档是更难的题：库会重写全文件、毁掉原格式，所以这里反其道而行——回到裸 XML。流程三步：

**Step 1 解包**：`python scripts/office/unpack.py document.docx unpacked/`。这个脚本做了三件预处理，件件为模型服务：

1. ** pretty-print**：把压缩成一行的 XML 展开缩进，模型才能按行定位；
2. **合并相邻 run**：Word 保存时会把手打的一段话切成几十个碎 run（拼写检查、输入法都会切），`merge_runs` 把它们拼回去——否则模型的 Edit 工具匹配不到完整字符串；
3. **智能引号转实体**：把 `’` `“` 换成 `&#x2019;` `&#x201C;`，纯文本引号在任何编辑器、任何传输管道里都不会被转坏。

这三步的共性：**在模型动手之前，先把战场清扫成模型友好的形状。** 这是给 Agent 写技能独有的设计维度——传统脚本的用户是人，可以人肉适配；技能的用户是模型，输入必须先整形。

**Step 2 编辑**：直接用 Edit 工具做字符串替换。注意这句元指令：

> Use the Edit tool directly for string replacement. Do not write Python scripts.

让模型不要「写脚本去改」，而是「逐处替换」。理由写明了：脚本引入不必要的复杂度，而 Edit 工具能精确展示替换了什么。这是在约束代理行为而非文档知识——技能作者很清楚，模型遇事爱写 Python，而这里最安全的手术刀是一次可见的字符串替换。

**Step 3 打包**：`pack.py` 校验加自动修复，这里的分寸感是全技能最精细的设计之一。自动修复白名单只有两项：超出 `0x7FFFFFFF` 的 `durableId` 重新生成、`<w:t>` 补上丢失的 `xml:space="preserve"`。而四类问题明确列为「不可修复」：畸形 XML、非法嵌套、关系缺失、模式违规——这些必须打回给模型改，不能静默「修」出一个看似能开实则损坏的文件。**哪些错机器能兜、哪些错必须还给人（模型），白名单写得清清楚楚。**

---

## 五、修订线：把职场礼节编码进 XML

这是 docx 技能真正惊艳的部分。审阅场景要求 AI 以「修订模式」改稿——改动可接受、可拒绝、可追溯。OOXML 的修订协议冷知识密度极高，技能逐一拆给了模型：

**最小修改原则**。把「30 days」改成「60 days」，不许重写整句，只包裹变化的词：

```xml
<w:r><w:t>The term is </w:t></w:r>
<w:del w:id="1" w:author="Claude" w:date="...">
  <w:r><w:delText>30</w:delText></w:r>
</w:del>
<w:ins w:id="2" w:author="Claude" w:date="...">
  <w:r><w:t>60</w:t></w:r>
</w:ins>
<w:r><w:t> days.</w:t></w:r>
```

注意 `<w:del>` 里的文本用 `<w:delText>` 而非 `<w:t>`——混用即非法。

**整段删除要删两次**。清空一个段落时，除了包住内容，还必须在 `<w:pPr><w:rPr>` 里补一个 `<w:del/>` 把段落标记本身也标记为删除。技能原文的警告很狠：不加这个，「接受修订后会留下一个空段落或空列表项」。这是 OOXML 领域资深开发者都常踩的坑，被一句话焊死在流程里。

**然后是两条「协作礼节」**——我认为这是全技能的灵气所在：

- **拒绝他人的插入**：把你的 `<w:del>` 嵌套进对方的 `<w:ins>` 里面，而不是删掉对方的标记；
- **恢复他人的删除**：在对方的 `<w:del>` 后面追加自己的 `<w:ins>`，而不是改动对方的删除记录。

翻译成人话：**AI 永远不篡改别人留下的修订痕迹，只在自己的图层上表达异议。** 这是审阅场景的职场礼仪——就像 paper review 里你不该抹掉别的审稿人的批注，而是写自己的回应。技能把这种伦理写成了确定性的 XML 操作规则，模型没有自由发挥的空间，也就没有作恶的可能。

配套的身份规则同样讲究：修订与批注的作者名默认写 `Claude`，「除非用户明确要求换名」。AI 产出永远署自己的名——可追溯性是默认值，不是可选项。

```mermaid
flowchart TD
    A["要改一段文字"] --> B{"改动落在谁的痕迹上"}
    B -->|"空白处新改"| C["del 包旧词<br/>ins 包新词"]
    B -->|"撤他人插入"| D["把 del 嵌进<br/>对方 ins 内层"]
    B -->|"恢复他人删除"| E["不动原 del<br/>旁边补一条 ins"]
    C --> F["复制原 run 的 rPr<br/>加粗字号不丢"]
    D --> F
    E --> F
    F --> G["pack.py 校验入库"]
```

顺带一提上图的格式细节：技能要求加修订时**整块替换 `<w:r>` 元素**、并把原 run 的 `<w:rPr>` 复制进新结构——否则新插的字会丢掉加粗和字号。段落标记删除、格式继承、嵌套规则三层叠加，才构成一次「合格的」AI 修订。

---

## 六、批注线：一条评论，五个文件

Word 批注的存储结构是个著名的坑：加一条批注要同时动 `comments.xml`、`commentsExtended.xml`、`commentsIds.xml`、`commentsExtensible.xml` 和 `people.xml` 五个文件——分别存正文、回复关系、ID 稳定性、扩展属性和作者信息。技能的解法不是教模型手写五份 XML，而是封装成 `comment.py`：

```bash
python scripts/comment.py unpacked/ 0 "批注内容（需预转义）"
python scripts/comment.py unpacked/ 1 "回复内容" --parent 0
```

脚本包掉跨文件联动，模型只需要在 `document.xml` 里放两个标记位。而标记位本身还有一条硬规则：`<w:commentRangeStart>` 和 `<w:commentRangeEnd>` 必须是 `<w:r>` 的兄弟节点，「永远不要放进 run 里面」。templates/ 目录里五个模板文件就是给这条链路兜底的骨架。

回看这个分层：**跨文件的机械劳动给脚本，需要语义判断的标记定位给模型。** 人机分工的边界画在「哪边更不容易错」上，而不是「哪边更高级」上。

---

## 七、验证闭环：一本随身携带的 ISO 标准

生成线终点和编辑线终点都汇入同一个动作：校验。`validate.py` 背后是 schemas/ 目录里那套完整的 ISO/IEC 29500 XSD——这意味着模型改完的每一个 docx，都是对照国际标准逐节点验过的，而不是「打开不报错就算过」。

依赖清单也诚实：pandoc 负责抽文本（`--track-changes=all` 连修订历史一起转出来），docx-js 负责生成，LibreOffice 负责转 PDF 与验收清稿，Poppler 的 `pdftoppm` 负责把 PDF 渲染成图让模型「亲眼看」排版效果。`soffice.py` 封装层专门注明为沙箱环境自动配置——技能作者很清楚自己的代码会跑在容器里。

整条验收链路是一个完整的感知-行动环：改 XML → 打包校验 → 转 PDF → 渲染成图 → 模型看图确认 → 不对再回去改。技能没有假设模型一次改对，而是给了它「看见自己作品」的眼睛。

---

## 八、可抄的写法排行榜

把 docx 技能的设计手法提炼成七条，按复用价值排序：

| 排名 | 写法 | docx 里的原型 | 一句话要点 |
|------|------|--------------|-----------|
| 1 | 第一句给心智模型 | 「docx 是装着 XML 的 ZIP」 | 先矫正直觉，再教操作 |
| 2 | 负向清单即踩坑史 | 十三条 Critical Rules | 每条「别」背后是一次事故 |
| 3 | 就地标注兼容性 | 「PERCENTAGE 在 Google Docs 会崩」 | 原因写在规则旁边，模型才能举一反三 |
| 4 | 为模型预处理输入 | unpack 三件套 | 用户的输入要整形，模型的输入更要 |
| 5 | 元指令约束代理行为 | 「用 Edit，别写脚本」 | 技能可以指挥模型用什么工具干活 |
| 6 | 自动修复白名单 | pack.py 可修两项、不可修四项 | 兜底与放行的边界要显式 |
| 7 | 礼节编码进操作规则 | 不动他人修订的两条嵌套规则 | 把伦理翻译成确定性步骤 |

---

## 九、适用与不适用

**适合**：合同/公文审阅修订、批量生成报告与通知、给既有 Word 文档加批注、老 `.doc` 批量转 `.docx`、产出后需要渲染验证的正式文档流水线。

**不适合**：重度视觉排版（宣传单页、复杂图文混排——那是 canvas-design 类技能的地盘）；数据计算表格（请用同门 xlsx 技能，它解决的是公式重算这个 docx 完全不碰的问题）；只想读内容不需要写回的场景，一句 pandoc 就够，不必惊动整套工具链。

短板也说清楚：编辑线依赖模型对 XML 的逐处定位，遇到几百页、样式表极度混乱的文档，解包后的 XML 体积会考验上下文预算；LibreOffice 渲染与真实 Word 之间偶有细微差异，「看图验收」不等于最终像素级一致。

---

## 十、评测表

| 维度 | 权重 | 评分 | 简评 |
|------|------|------|------|
| 功能完整度 | 25% | ★★★★★ | 读/建/改/批注/修订/验收/格式转换全链路闭环 |
| 设计质量 | 25% | ★★★★★ | 双产线分工、渐进披露、礼节编码，教科书级 |
| 实战效果 | 20% | ★★★★☆ | 生成线极稳；超长文档编辑受上下文限制 |
| 上手难度 | 15% | ★★★★☆ | 依赖 pandoc/LibreOffice/Node，技能自带校验兜底 |
| 社区活跃度 | 15% | ★★★★☆ | 官方技能库随 Claude Code 生态持续维护 |

综合 4.7/5。如果说 skill-creator 教你「怎么写技能」，docx 就是「写成了什么样子」的最佳实物参考——两者的差距，就是设计与实现的差距。

---

## 十一、安装与使用

```bash
# 方式一：作为官方插件市场安装（Claude Code 会话内执行）
/plugin marketplace add anthropics/skills
# 随后在插件列表中启用 example-skills，即含 docx/pdf/pptx/xlsx 四个文档技能

# 方式二：手动安装单个技能
git clone https://github.com/anthropics/skills.git
mkdir -p ~/.claude/skills
cp -r <仓库内的docx技能目录> ~/.claude/skills/docx
```

装好后直接对 Claude 说人话即可触发，例如：「把这份合同的违约金从 30 天改成 60 天，用修订模式」「审阅这份文档，把你的意见加为批注」。生成线开箱依赖 Node 的 docx 包（`npm install -g docx`），编辑验收依赖 pandoc 与 LibreOffice，缺什么技能会自己在 Dependencies 清单里对号入座。

核心命令速查（均出自 SKILL.md 原文）：

```bash
# 读：连修订历史一起抽出文本
pandoc --track-changes=all document.docx -o output.md

# 编辑三步
python scripts/office/unpack.py document.docx unpacked/
#   ……用 Edit 工具直接改 unpacked/word/ 下的 XML……
python scripts/office/pack.py unpacked/ output.docx --original document.docx

# 创建后校验，失败则解包修 XML 再重打包
python scripts/office/validate.py doc.docx

# 一键接受全部修订，产出干净终稿
python scripts/accept_changes.py input.docx output.docx
```

---

## 结语

docx 技能最值得记住的不是它会给模型省多少 token，而是它示范了一种写作姿态：**作者假想读者是一个记忆力绝佳但没有常识的实习生**——所以先给心智模型，再给禁令清单，把每次事故的原因写在规则旁边，把职场礼节翻译成确定的操作步骤，最后给它一双能看见自己作品的眼睛。你下一份 SKILL.md，值得用这个标准重写一遍。

## 参考来源

1. [anthropics/skills 官方技能仓库](https://github.com/anthropics/skills) — docx 技能所在仓库，随 Claude Code 插件市场分发
2. [docx (docx-js) npm 包](https://www.npmjs.com/package/docx) — SKILL.md 指定的文档生成库，生成线唯一依赖
3. [ECMA-376 / ISO-IEC 29500 标准](https://ecma-international.org/publications-and-standards/standards/ecma-376/) — OOXML 格式标准，技能包 schemas/ 目录内置其 2016 第四部分全套 XSD
4. [pandoc 官方手册](https://pandoc.org/MANUAL.html) — `--track-changes` 参数的出处，技能读档线的核心工具
5. [docx 技能包 SKILL.md 原文与 scripts/ 目录](https://github.com/anthropics/skills) — 本文所有引文、规则与目录结构的直接来源

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)