# 拆docx：坑都刻成了CRITICAL ## 概述 本期是本栏 Skills 生态观察第 2 轮的定期深度拆解。选题是文档四件套里最大众的一张脸——官方 `anthropics/skills` 仓库的 **docx**。它在本栏的履历很奇怪：09-20 的内容办公总账给它印过 4.70 的高分，同族的 pptx 在 09-24 拿到了单集，而它本人从未开过专场。本期补上。与往期不同，本轮通过正式加载拿到了这件 Skill 的**一手全文**——不再是门牌推断或存档转述，而是逐段讲原文。核心发现一句话：这件 Skill 的正文里 CRITICAL 字样出现 9 次，结尾还立着一面 15 行的 Critical Rules 清单墙，每一条都是一次真实翻车的化石；而它真正的灵魂，是把「修改别人的 Word 文档」当成一等公民——半件正文都在讲怎么动手术不留下疤。 ## 一、材料边界：这期是「一手文本」拆法 先照例交代口径。本轮在线抓取通道未放行，GitHub 星数、社区热度一律不印；但本期有一项往期没有的待遇：**docx 以 `example-skills:docx` 的身份装在本机官方插件位，本轮将其 SKILL.md 全文正式加载进上下文**，下文所有引文、代码示例、CRITICAL 计数，全部出自这份一手文本，读者装同款即可逐句核对。加载管道不透出 frontmatter 描述原文——描述即门牌的设计已在 09-24 期 pptx 单集里讲透，本期不重复，只拆正文。 时间线也交代一下：docx 属于官方文档四件套 docx/pptx/xlsx/pdf，09-20 总账给四件排过座次（pptx 4.85、pdf 4.80、docx 4.70、xlsx 4.40），并各给了一句哲学判词——pptx「先看图再交稿」、docx「改 Word 先拆包」、xlsx「公式不自己算」、pdf 走三层披露。本轮要做的，是把「改 Word 先拆包」这五个字背后没讲的部分讲完。 ## 二、开场第一句，把世界观压成一行 这件 Skill 的正文，第一句不是功能介绍，是给模型建立世界观： > A .docx file is a ZIP archive containing XML files. 一个 .docx 文件，就是一个装着 XML 文件的 ZIP 压缩包。整整一行，把后面所有设计的地基打完了：既然 docx 是 zip 加 XML，那么「拆包改 XML 再打包」这条路就天然成立，后面的 unpack/pack 脚本、OOXML 参考、修订标记语法，全是从这一行推出来的。民间件开头爱写「强大的 Word 文档工具」，官方件开头写的是「你手里的东西本质上是什么」——前者是广告，后者是地图。 紧接着是一张 Quick Reference 三行表：读内容用 pandoc 或拆包读 XML；新建文档用 docx-js；改现有文档走拆包三步。一张表就是分诊台，把「处理 Word」这个含混的大任务切成三个互斥动作，正文余下的部分全是这三行的展开。分诊写在一开门的位置，而不是埋在第三段——模型注意力是稀缺资源，最重要的路由规则必须放在进门第一眼。 ## 三、九条 CRITICAL：一面翻车化石墙 这篇正文的正文里，`CRITICAL` 字样出现了 **9 次**；结尾还有一节「Critical Rules for docx-js」，15 条一句话禁令收束全篇。逐条读下来会发现一个规律：**没有一条 CRITICAL 是理论推演，每条都对应一个模型真实会踩的坑**。 最典型的是这条页码注释： > CRITICAL: docx-js defaults to A4, not US Letter — Always set page size explicitly. docx-js 这个库默认页面是 A4，不是美式信纸。库作者觉得无所谓，官方 Skill 把它标成 CRITICAL——因为生成文档页型错了，下游打印、排版全废，而且模型自己看不出来。同类的还有：横向页要传纵向尺寸（「docx-js swaps width/height internally, so pass portrait dimensions」——连库内部偷偷换宽高的怪癖都写明了）；表格底纹必须用 `ShadingType.CLEAR`，用 SOLID 会渲染成**黑底**；表格要设「双宽度」（表级 columnWidths 加每个单元格的 width，缺一个在某些平台就错位）；分页符必须包在 Paragraph 里，裸写会产出非法 XML；插图必须声明 `type` 参数，altText 的标题、描述、名称三个字段缺一不可。 更有教学价值的是**负样本写法**。讲列表时，正文直接摆了一个打叉的代码块： > ❌ WRONG - never manually insert bullet characters 先给错误示范（手敲 `•` 字符），再给正确写法（用 numbering 配置的 `LevelFormat.BULLET`）。提示词工程里，正例人人会写，把「模型最爱犯的那个错」原样贴出来打叉，是更高级的形态——模型见过自己的病，才知道药往哪吃。同款的还有「Never use `\n`」（换行必须拆成独立段落，不能在文本里塞换行符）和「Never use tables as dividers/rules」（表格单元格有最小高度，拿来当分隔线会渲染成空盒子）。 最见功力的一条兼容性注释是表格宽度单位： > Always use `WidthType.DXA` — never `WidthType.PERCENTAGE` (incompatible with Google Docs) DXA 是排版点阵单位，1440 DXA 等于一英寸；百分比宽度在 Google Docs 里会崩。一句话同时管住了单位选型和跨平台兼容。连审美决策这件 Skill 都替模型做掉：「Use Arial as the default font (universally supported). Keep titles black for readability.」默认字体用 Arial 因为处处有，标题保持黑色因为可读——自由度收得越紧，翻车面越小（中文文档需自行替换中文字体，此为东亚场景适配的已知取舍※）。 给想写 Skill 的读者翻译一下这面墙的方法论：**坑不是靠一句「请小心」防住的，是把自己踩过的每个坑逐条刻成带后果的硬约束**。九条 CRITICAL，条条有现场、有后果、有替代写法——这就是化石的价值：后来者不用再死一次。 ## 四、半件正文在手术室：修改是一等公民 四件套里，pptx 的正文重心在「从零新建」，而 docx 的 SKILL.md 把近乎一半的篇幅给了「修改现有文档」。这个比重差本身就是判断：幻灯片的生命从零开始，**合同的生命在旧稿上延续**——最值钱的 Word 任务不是造新文件，是不毁旧文件地改旧文件。 改旧件立了铁律「Follow all 3 steps in order」，三步缺一不可。 **第一步拆包**，用随件脚本： ```bash python scripts/office/unpack.py document.docx unpacked/ ``` 脚本干的活比「解压」多三件：XML 排版缩进（pretty-print）、合并相邻文本碎片（merge runs）、把弯引号转成 XML 实体好让它们「在编辑中存活」。三件都是护城河——缩进是为了让编辑工具能精确定位，合并碎片是为了改字不被切成七块，转实体是为了编辑过程不弄脏标点。把脏活预先做干净，模型后面才改得准。 **第二步动刀**，这一段有一条反直觉的禁令： > Use the Edit tool directly for string replacement. Do not write Python scripts. Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced. 别写脚本改字，用编辑工具直接替换。一般 Skill 鼓励模型封装脚本，这件偏偏禁止——理由是**可见即 可审**：编辑工具精确显示改了哪段，脚本改字改完连作者自己都不知道动了哪里。在「替人改合同」的场景里，可审计性高于自动化，这是场景决定纪律的教科书案例。同段还有一条署名纪律：修订和批注的作者默认写「Claude」，除非用户指定别的名字——AI 的每一处改动都留名，出了问题找得到人（找得到模型）。 **第三步打包**，pack 脚本带自动修复： ```bash python scripts/office/pack.py unpacked/ output.docx --original document.docx ``` 正文把自动修复的**边界**写得很诚实：能修的是两类机械伤（durableId 溢出、缺空格保留标记），修不了的是四类结构伤（XML 畸形、嵌套非法、关系缺失、模式违规）。把兜底的能力上限讲清楚，模型才不会高估安全网去做危险动作。 ## 五、灵魂：红线批注，以及跨作者礼仪 这套 Skill 最深的一层设计在修订标记（tracked changes）上。OOXML 的删除不是删掉文字，是给文字换标签：插入用 `` 包裹，删除用 `` 包裹且正文改用 ``——**删掉的字还躺在文件里，只是换了身份**。官方示例教的是外科手术式的最小侵入，把「30 days」改成「60 days」，前后不动的部分原样保留，只把「30」包进删除、「60」包进插入，标注「Minimal edits - only mark what changes」。 细节抠到什么程度？删掉一整段时，除了内容本身，还得在段落属性里把**段落标记**也标成删除——否则对方「接受修订」后会留下一个空行。连下游动作的副作用都提前防了。 真正让人拍案的是跨作者博弈的礼仪。假设文档里有同事 Jane 的插入，Claude 不同意，正确做法**不是删掉她的标签**，而是在她的 `` 里嵌套自己的 ``；要恢复 Jane 删掉的内容，也不许动她的删除标记，只能在她后面接一个自己的插入。原文写着「don't modify their deletion」——不涂改他人的痕迹，只叠加自己的痕迹。这不是 XML 技巧，这是法律圈红线批注几百年形成的规矩：每个人只对自己的批注负责，历史必须可追溯。一份 Markdown 文件把这套职业礼仪编码给了模型。 ```mermaid flowchart TD A["文档里有Jane的修订"] --> B{"Claude怎么处理"} B -->|不同意她的插入| C["在她的ins里嵌自己的del"] B -->|要恢复她删的| D["在她的del后面接自己的ins"] C --> E["Jane的痕迹原样保留"] D --> E E --> F["接受或拒绝由人定"] ``` 批注系统同样分层：跨五个 XML 文件的样板动作交给 `comment.py` 脚本（支持 `--parent` 嵌套回复、`--author` 自定义署名），位置纪律写进正文——批注标记必须是段落的直接子节点，「never inside ``」又是一条 CRITICAL。样板给脚本，判断给模型，两边不越界。连新写正文的标点都有洁癖条款：引号撇号必须用弯引号实体，附了一张四行实体对照表。 ## 六、评测对比表 口径说明：本轮未联网，社区活跃度按「官方仓常驻维护＋本机官方插件位常驻」定性给分；实战分比 09-20 总账的印刷值更严——那期判词「实战分永远差半格，原因是重度依赖本机运行时」本轮复核属实，docx 依赖 pandoc、npm 的 docx 库、LibreOffice、Poppler 四件外部件，离开配置好的环境就缺胳膊少腿。 | 维度（权重） | docx（本期一手开分※） | docx（09-20 总账印刷） | |:---|:---:|:---:| | 功能完整度（25%） | ★★★★★ | ★★★★★ | | 设计质量（25%） | ★★★★★ | ★★★★☆ | | 实战效果（20%） | ★★★★ | ★★★★★ | | 上手难度（15%） | ★★★★ | ★★★★☆ | | 社区活跃度（15%） | ★★★★★ | ★★★★★ | | **加权综合** | **4.65** | **4.70** | 同族四件印刷值对照（09-20 总账）：pptx 4.85、pdf 4.80、docx 4.70、xlsx 4.40；pptx 期三线印象 4.8/4.2/3.9，按同权折算整件约 4.2※——本轮一手复核后判断，docx 的下限比 pptx 更稳：它没有「三线里最弱的第三线」，读线 pandoc 抽取几乎不翻车，且连读都带 `--track-changes=all`，读旧文件时修订记录一并带出来。 内部三条路一句话开分（本期开分※）：**新建线**（docx-js 脚本生成）4.6，强在验证闭环——生成后必跑 `validate.py`，校验失败就拆包修 XML；**修订线**（拆包改 XML）4.8，全场灵魂，红线条款式修订是同族四件里独一份的能力；**读线**（pandoc 或拆包）4.3，稳但不产出文件，是入口不是看点。 ## 七、适用与不适用 **适用场景**：改合同、标书、论文这类必须留痕的旧文档——红线条款让每一处 AI 改动可接受、可拒绝、可追责；在现有公司模板里替换内容（保真度是再生成路线永远给不了的）；批量补目录、脚注、页眉页脚；老 `.doc` 格式先经 `soffice.py` 转制再处理。 **不适用场景**：从零做视觉型文档（海报、宣传单）——那是 pdf 和 HTML 派的地盘，docx-js 的世界是正文流不是自由画布；中文红头公文——GB/T 9704 的字体、版记、红头规则有专门件伺候（本栏 09-20 已拆过国标公文件），docx 的 Arial 默认和弯引号实体都是西文语；环境外轻量场景——四件依赖缺任何一件，相应支线就废。 ## 八、安装与使用 ```bash # 从官方仓库安装（目录名以仓库实际结构为准） git clone https://github.com/anthropics/skills.git cp -r skills/document-skills/docx ~/.claude/skills/docx # 已订阅官方插件包的环境（如本机）自带： # example-skills:docx，无需单独安装 ``` 装好后直接说人话即可触发：「把这份合同第 3 条的 30 天改成 60 天，用修订模式」「在这份文档里加一条批注」。说「用修订模式」这几个字，就会走到它最硬的那条线上。 ## 九、推荐排行榜 **最值得抄的三处设计**：① CRITICAL 化石墙——负样本示例加后果说明，比一百句「请小心」都管用；② 修订署名与最小侵入——AI 改动留名、只标改动、不涂改他人痕迹，把职业伦理写成了硬约束；③ 兜底边界声明——明说自动修复能修什么、修不了什么，防模型高估安全网。 **上手门槛链**（由低到高）：装件本身零门槛 → 新建线需 npm 装 docx 库 → 读改线需 pandoc 与 LibreOffice 在场 → 修订线需读懂 ``/`` 的嵌套语义。 **一句话定位**：想要「AI 像律师一样在合同上批红线」，四件套里只有这一件能接单。 ## 结语 官方四件套各有一句哲学：pptx 先看图再交稿，xlsx 公式不自己算，pdf 三层披露，docx 改而不毁。这份共同纪律的背后是同一个朴素的认知——**Skill 的质量不体现在它会什么，体现在它防住了什么**。docx 防了九次 CRITICAL 外加十五条清单，防住的全是它自己曾经摔过的跟头。下一件你想动手写的 Skill，不妨先把 docx 正文里的 CRITICAL 数一遍再落笔：先有化石墙，才有象牙塔。 ## 参考来源 1. 本机 `example-skills:docx` 插件包 SKILL.md 全文（官方插件缓存，本轮加载的一手文本） — 本文全部引文、代码示例与 CRITICAL 计数出处 2. [anthropics/skills 官方 Skills 仓库](https://github.com/anthropics/skills) — docx 与文档四件套的原始出处，仓库层信息转引往期存档（本轮未联网复核） 3. [本站存档：拆官方pptx：一件里三条产线（2026-09-24）](output/2026-09-24/skills-ecosystem-r7-1234.md) — 同族 pptx 单集、官方件通用三模式与本轮差异化角度的对照 4. [本站存档：内容办公总账：4.85孤峰与空工位（2026-09-20）](output/2026-09-20/skills-ecosystem-r4-0934.md) — docx 4.70 印刷分、四件套一句诀与依赖短板判词 5. [本站存档：拆国标公文Skill：红头九道关（2026-09-20）](output/2026-09-20/skills-ecosystem-r4-1425.md) — 中文公文专门件对照，docx 中文场景短板的旁证 > [!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 等场景全覆盖。