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

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

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

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 共六个年代层）。校验时连微软私有扩展都能查到出处。

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

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

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

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

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

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

新建文档不用 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/。这个脚本做了三件预处理，件件为模型服务：

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

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

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

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

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

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

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

<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 领域资深开发者都常踩的坑，被一句话焊死在流程里。

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

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

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

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：

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 里的原型	一句话要点
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 之间偶有细微差异，「看图验收」不等于最终像素级一致。

十、评测表

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

十一、安装与使用

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

# 方式一：作为官方插件市场安装（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 清单里对号入座。

# 读：连修订历史一起抽出文本
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，值得用这个标准重写一遍。