前言¶
在 Agent 里改 Word，常见做法是整篇用库重新生成，或只改纯文本。复杂模板上的样式、页眉页脚、分节、编号、修订痕迹和图片，很容易丢或错位。若还要处理中文公文（GB/T 9704）一类版式，单靠「另存为」或简单替换往往不够稳。
下面介绍 SkillHub 上的 docx优化版（坐标 @user_c66b8218/docx007-skill）。它把 .docx 当作 ZIP 包内的 Open XML，走 解包 → 就地改 XML → 再打包，并配套校验与渲染，目标是在创建、编辑、填表、重排版和格式转换时尽量保持原有格式不变。
这是什么¶
docx优化版 是社区发布（community）、分类为 office-efficiency 的 Agent Skill，维护方为 SkillHub 用户 user_c66b8218，当前商店版本 1.0.0。Skill 包内自带一套可运行的 Python 工具链（lxml、python-docx，并依赖本机 LibreOffice、poppler-utils 等），不要求 API Key（requires_api_key=false）。
一句话定位：在 Agent 会话中，按 READ → ACT → VERIFY 流程处理 Microsoft Word .docx——读结构、在解包目录里改 XML 或新建文档、再校验并渲染成 PDF/PNG 目检；对中文/CJK 与 GB/T 9704 公文排版有专门说明与脚本支持。
核心功能¶
以下能力均来自 Skill 包内的 SKILL.md 与 references/ 文档，可按任务路由选用：
- 创建（Pipeline A）：无现成
.docx时，用python-docx新建文档（见references/create.md）。 - 填充与编辑（Pipeline B）：对已有
.docx解包后做 run 感知的查找替换、占位符填充、插入段落/标题等（见references/edit.md）。 - 套用样式与模板（Pipeline C）：重排版或套模板，含 Overlay 与 Base-Replace 两种策略（见
references/format.md）。 - 读取与分析：
docx_reader.py提供结构概览、--outline标题树、--preview、--diff-against对比。 - 格式保持：解包编辑再打包，旨在保留样式、主题、页眉页脚、多节版式、编号、修订（track changes）、域与嵌入图片；Skill 明确强调优先编辑而非整包重生成。
- 校验与可视化：
docx_validate.py做元素顺序等门禁；docx_render.py经 LibreOffice 输出 PDF 与分页 PNG，便于核对版式与 CJK 字体。 - 格式转换：
libreoffice_convert.py支持.doc/.odt/.rtf转.docx或转 PDF。 - 中文与公文：UTF-8、
w:rFonts东亚字体、字号表；公文场景参考 GB/T 9704（如正文仿宋_GB2312 三号、标题黑体等，见references/cjk-guide.md）。
商店侧 SkillHub 评分 100000，下载 1342 次（统计以 SkillHub 页面抓取为准）。
安装与启用¶
环境依赖¶
在 Skill 目录下执行脚本前，需满足包内声明的依赖：
- Python：
python-docx、lxml、Pillow - 系统：
libreoffice（soffice）、poppler-utils（pdftoppm） - 字体：建议安装 Noto Sans CJK / Noto Serif CJK，便于 CJK 渲染
安装后可在 Skill 根目录运行环境自检：
python3 scripts/docx_doctor.py
输出应为 READY。
通过 SkillHub CLI 安装¶
若尚未安装 CLI，可按 SkillHub 官方说明安装：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
将 Skill 安装到当前 Agent 的 skills 目录（必须使用 --dir，否则默认 ./skills/ 可能不会被 Agent 加载）。例如在 Cursor 中：
skillhub install docx007-skill --namespace user_c66b8218 --dir ~/.cursor/skills/
其他客户端常见路径（来自 SkillHub 安装文档）：Claude Code 为 ~/.claude/skills/；Codex 为 ~/.codex/skills/ 或项目下 .agents/skills/。安装后通常需重启或重新加载 Agent 方能识别新 Skill。
通过自然语言让 Agent 安装¶
SkillHub 页面提供的提示词为：根据 https://skillhub.cn/install/skillhub.md，安装 @user_c66b8218/docx007-skill。
典型用法¶
典型流程与 Skill 内 references/quickstart.md 一致：先 READ，再 ACT，最后 VERIFY。以下命令均在 Skill 包根目录（含 scripts/ 的路径）下执行。
1. 读取原文结构
python3 scripts/docx_reader.py input.docx --outline
2. 解包、替换、再打包
python3 scripts/docx_unpack.py input.docx /tmp/wd
python3 scripts/docx_replace_text.py /tmp/wd --find OLD --replace NEW
python3 scripts/docx_pack.py /tmp/wd output.docx
3. 校验与对比、渲染目检
python3 scripts/docx_validate.py output.docx --report
python3 scripts/docx_reader.py output.docx --diff-against input.docx
python3 scripts/docx_render.py output.docx --out /tmp/rev
模板占位符填充示例（同一解包目录）：
python3 scripts/docx_fill_placeholders.py /tmp/wd --data '{"name":"张三"}'
遗留 .doc 可先转换：
python3 scripts/libreoffice_convert.py old.doc --to docx --outdir .
在 Agent 对话中，触发词包括 Word、docx、文档、公文、套模板、report、mail merge 等（见 Skill 元数据 triggers）。Agent 应按 Skill 要求：任何交付物须通过 docx_validate.py、--diff-against，并完成 docx_render.py 的 PNG 目检。
适用场景与注意¶
适合谁
- 需要在 Agent 里改合同、报告、论文、公文等 保留原模板版式 的场景。
- 要做批量占位符填充、run 感知替换、插入带大纲级别的标题，且担心 python-docx 单独重写整文档丢格式时。
- 处理 中文/CJK 或 GB/T 9704 公文版式，并愿意按 Open XML 元素顺序等规则编辑 XML 的开发者。
限制与注意
- 依赖本机 LibreOffice 与 poppler；无图形环境时渲染链路可能需额外配置，故障排查见
references/troubleshooting.md。 - Open XML 对元素顺序、修订标记（
w:ins/w:del）、单位（半磅、dxa、EMU）有硬约束；违反时docx_validate.py会失败，需对照references/openxml-element-order.md等文档修改。 - SkillHub 商店版本为 1.0.0，包内
SKILL.mdfrontmatter 另有内部版本字段，以实际安装包为准。 - 本 Skill 是工具与工作流说明，不替代你对机密文档的合规审批；敏感文件请在隔离环境中操作。
结尾¶
docx优化版 把 Word 当作可审计的 XML 包，用脚本链固定 读 → 改 → 验 → 看 的步骤，适合在 Agent 里做可复现、低格式损耗的 .docx 处理。官方入口与安装坐标：
- SkillHub 页面：https://www.skillhub.cn/skills/user_c66b8218/docx007-skill
- API 坐标：https://api.skillhub.cn/user_c66b8218/docx007-skill
- 安装：
skillhub install docx007-skill --namespace user_c66b8218 --dir <你的 Agent skills 目录>
