文档类 Skill 凭什么「不坏文件」

它替你干掉什么：干掉「改完不知道有没有坏」

怎么装

# Claude Code：四件套在 document-skills 这个插件里
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

# 只想要脚本、不想装 skill：直接 clone，scripts/ 目录可独立使用
git clone https://github.com/anthropics/skills

# 系统依赖（docx/SKILL.md 自己列的四项）
# docx（npm，环境预装）· pandoc · LibreOffice（soffice）· pdftoppm（Poppler）

第一条立刻能跑的用法（照抄 docx/SKILL.md 的编辑流程）

unzip -q doc.docx -d unpacked/
find unpacked -type l -delete              # 剥掉符号链接
python scripts/merge_runs.py unpacked/     # 先把碎掉的 run 合并
# 手工编辑 unpacked/word/document.xml —— 不要 reformat
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx

这六行里没有一行是装饰：find -type l -delete 防的是符号链接被打进包；merge_runs.py 决定你能不能在 XML 里搜到一句完整的话；zip -Xr 且必须 cd 进目录里打包，否则压出来多一层目录、Word 直接不认；--original 让校验器拿原件做基线。

机制：有效的不是提示词，是那一层 XSD

校验器长在哪

validate.py 接受一个解包目录或一个打包文件，另有四个开关：--original 拿原件做基线、--auto-repair 自动修、--author NAME 开修订校验、-v 详细输出。退出码：0 全过、1 校验失败、2 参数或文件错——这就是可以直接写进循环的那个信号。

它到底修什么、查什么

• schema 校验：docx 与 pptx 拿 schemas/ 里的 XSD 逐个 part 校。这是「文件还能不能打开」这件事最接近真相的判据。
• auto-repair 的两类具体问题：paraId / durableId 超出 OOXML 允许的取值范围；w:t 上带空白却缺 xml:space="preserve"。两个都是手改 XML 的高频副作用。
• redlining 校验：给了 --author 就逐字比对原件，凡是文本变了却没有被 <w:ins>/<w:del> 记录下来的，都算错。「假装留了痕」这件事从此有人管。

为什么 merge_runs 要排在编辑之前

Word 会把一句话切成十几个 <w:r>：拼写检查、语言标记、rsid 都会在中间插刀。于是 XML 里根本不存在「the quick brown fox」这个连续字符串，模型按字面查找必然扑空——然后它会开始瞎猜位置，那才是真正坏文件的起点。先合并再编辑，是把一类幻觉从源头掐掉。

真实用法与边界：三条产线，三种完全不同的 oracle

docx 线 · oracle = XSD + 修订比对

python scripts/accept_changes.py in.docx out.docx         # 接受全部修订
python scripts/comment.py unpacked/ "这里口径不一致"        # 目录模式（编辑 XML 时用这个）
python scripts/comment.py unpacked/ "同意" --parent 0       # 回复第 0 条
python scripts/comment.py contract.docx "问一句" -o annotated.docx
python scripts/office/validate.py out.docx --original doc.docx --author "BigCat"

目录模式下 comment.py 会把 <w:commentRangeStart> / <w:commentRangeEnd> / <w:commentReference> 三个片段打印出来给你放进 word/document.xml——批注的挂载点由人决定，编号与关系文件的记账由脚本做。这个分工是整套设计的缩影。

pptx 线 · oracle = XSD + 关系与内容类型

python scripts/thumbnail.py template.pptx template-thumbs   # 先看版式，第二个参数务必给
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # 复制页，别手抄
# 调序 / 删页 = 改 ppt/presentation.xml 里的 <p:sldIdLst>
python scripts/clean.py unpacked/                            # 删完清孤儿 slide/media/rels
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)
python scripts/office/validate.py out.pptx --original deck.pptx

两条硬规矩：add_slide.py 直接作用在 .pptx 上时必须带 -o，否则原地改写输入；模板派生的 deck 必须带 --original，否则模板自带的报错会把你自己的错淹掉。

xlsx 线 · oracle = 重算，不是 schema

python scripts/recalc.py output.xlsx [timeout_seconds]   # 默认 30 秒
# LibreOffice 算完每一个公式并原地重写文件，返回 JSON：
# status(success|errors_found) · total_formulas · total_errors · error_summary

收尾统一走三层 QA

# ① 文件 QA
python scripts/office/validate.py out.pptx --original src.pptx
# ② 内容 QA：读回来，抓占位符
markitdown out.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert"
# ③ 视觉 QA：转 PDF 再出图，自己看一眼
python scripts/office/soffice.py --headless --convert-to pdf out.pptx
pdftoppm -jpeg -r 150 out.pdf slide && ls -1 slide-*.jpg

三层各挡各的：schema 挡打不开，grep 挡「xxx / TODO / 请在此处填写」漏进终稿，出图挡文字溢出框和白底白字。少一层就漏一类，而这三类没有任何交集。

代价与替代品：这套流水线不便宜

四条诚实的代价

• 依赖重。LibreOffice + pandoc + Poppler + Node，容器里装是标配，笔记本上为重算一次公式装一个 LibreOffice 就未必划算。装不全的后果不是报错退出，是静默降级——这比报错危险。
• openpyxl 的往返是有损的。官方文档原话：openpyxl does currently not read all possible items in an Excel file so images and charts will be lost from existing files if they are opened and saved with the same name.（openpyxl 3.1.5，据 PyPI 2024-06）。xlsx/SKILL.md 又补了两条同源的坑：data_only=True 读出来再保存，会把每一条公式永久替换成字面值；.xlsm 不带 keep_vba=True 就丢宏。这是「不坏文件」这件事最容易破功的地方，而且它不报错。
• 生成库开不了旧文件。dolanmiu/docx（npm install docx，文档在 docx.js.org）只能生成与构造，读不进现成的 .docx。docx 编辑走解包路线不是偷懒，是没有别的路。
• 校验通过 ≠ 内容对。XSD 只管结构，它不会拦下一份结构完美的空话。所以第 03 节那条 grep 和那几张图不能省——真正的 oracle 分三层，别只留最便宜的一层。

四种「不走这条路」的替代品

• 只读一遍 → markitdown file.xlsx 或 pandoc -t markdown file.docx。解包是为了改，不是为了看。
• 从零生成 → docx（npm）写 Word、gitbrent/PptxGenJS（npm install pptxgenjs，据 GitHub 仓库页 2026-09 约 6.2 千 star、MIT）写 PPT。生成完照样走 validate 与视觉 QA，但不必碰解包。
• 只要一张表 → CSV。为了一份两列数据引入整条 OOXML 流水线，是本系列最常见的过度工程。
• 在 claude.ai 或 API 上 → 四件套是预置的 skill_id，零安装（见 Skill 13）。这条流水线是给 Claude Code 与自建环境用的。