下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/songyuankeyan--word-doc-ooxml-pro.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @songyuankeyan/word-doc-ooxml-pro。Word/docx 文档全能处理技能。当用户需要生成、读取、解析、编辑、排版美化、批量处理、格式校验或转换 Word 文档时使用;覆盖长篇报告、公文、合同、论文、标书、会议纪要、模板套打、批量替换、合并拆分、目录页码、页眉页脚、表格与图片、修订批注等场景。内置零第三方依赖的 Python 脚本,可直接运行并交付 .docx 成品与结构报告。
阅读全文 (展开查看完整说明)
概述
Overview
把 Word 需求变成可验收的 .docx 成品,而不是操作建议。全部脚本只用 Python 标准库(zipfile + xml.etree)直接读写 OOXML,无需 python-docx、lxml、Word 或 LibreOffice,因此在本地、云端、隔离环境都能跑。
先诊断,再动手;永远保留原文件;每个成品都要跑一次校验并给出报告。
核心原则
- 零依赖优先:只用标准库。遇到需要第三方库的方案,先判断能否用 OOXML 原生实现(绝大多数能,见
references/01-ooxml.md)。 - 不覆盖原件:所有编辑输出为新文件,命名
<原名>_edited.docx或用户指定路径;批量处理输出到独立目录。 - 先诊断后修改:修改任何已有文档前,先运行
docx_inspect.py拿到结构快照,确认段落数、表格数、样式、图片、修订状态。 - 文本跨 run 是头号坑:Word 会把一句话拆进多个
<w:t>。替换、提取前必须按段落合并 run,见references/01-ooxml.md第三节。 - 成品必须自检:交付前运行
docx_check.py,报告中的 error 级问题必须修完再交付。 - 中文语境默认:字体、字号、行距、缩进、编号按中文习惯,见
references/02-cn-typography.md;用户明确要求英文/APA 等时切换预设。 - 不猜内容:合同金额、日期、人名、条款等缺失信息先问,不编造。占位符统一用
〔待填:XXX〕并在交付说明里列出。
意图决策树
| 用户意图 | 主脚本 | 必读参考 |
|---|---|---|
| 从零写一份 Word(报告/公文/合同/论文) | scripts/docx_build.py | references/03-recipes.md 第一至三节 + 02-cn-typography.md |
| 看懂一份文档 / 提取内容 / 转 Markdown | scripts/docx_inspect.py | references/01-ooxml.md |
| 改文字、批量替换、改样式、合并、拆分 | scripts/docx_edit.py | references/03-recipes.md 第四节 + 01-ooxml.md 第三节 |
| 排版美化、统一格式、加目录页码页眉 | scripts/docx_build.py 或 docx_edit.py | references/02-cn-typography.md + 04-troubleshooting.md |
| 检查有没有问题 / 交付前验收 | scripts/docx_check.py | references/04-troubleshooting.md |
| 报修:打不开、乱码、样式丢失、目录不更新 | scripts/docx_inspect.py + docx_check.py | references/04-troubleshooting.md |
| 批量套模板 / 邮件合并 / 生成 N 份 | scripts/docx_build.py --batch | references/03-recipes.md 第五节 |
复杂任务按 诊断 → 规划 → 执行 → 校验 → 交付 串联多个脚本,中间结果存到工作目录,不要反复读写同一文件。
标准工作流
第 1 步:确认输入
至少明确:交付物类型(生成 / 修改 / 检查)、目标文件路径、文档用途与读者、篇幅要求。已有文档先问「要保留原格式还是重排」。
第 2 步:诊断(仅处理已有文档时)
python scripts/docx_inspect.py <文件.docx> --out report.json读报告确认:段落/表格/图片数量、用到的样式、是否存在修订或批注、页眉页脚、文档是否损坏。发现修订未接受时先询问用户,不要静默丢弃。
第 3 步:构造内容描述 JSON
生成类任务不直接手写 XML,先写结构化 JSON(字段见 assets/report-template.json),再交给 docx_build.py。好处是内容可审阅、可复用、可批量套打。
第 4 步:执行
python scripts/docx_build.py content.json --preset business --out 成品.docx
python scripts/docx_edit.py 原.docx --replace replacements.json --out 改后.docx
python scripts/docx_edit.py --merge a.docx b.docx --out 合并.docx
python scripts/docx_check.py 成品.docx --out check.json脚本均支持 --help;输出 JSON 便于程序判读,加 --text 可同时打印人类可读摘要。
第 5 步:校验与交付
运行 docx_check.py,逐项处理 error;把报告随成品一起交付。说明改了什么、有哪些占位符待填、哪些内容需要用户核对。
脚本速查
| 脚本 | 能力 | 依赖 |
|---|---|---|
docx_inspect.py | 解析 ZIP 部件、段落/表格/样式/图片/页眉页脚/修订/批注,导出 JSON 或 Markdown 大纲 | 标准库 |
docx_build.py | 由 JSON 生成完整 docx:标题层级、正文、表格、列表、页眉页脚、页码、样式预设、批量套打 | 标准库 |
docx_edit.py | 跨 run 批量替换、正则替换、样式批量改写、多文档合并、按标题拆分、转 Markdown | 标准库 |
docx_check.py | 标题层级跳跃、样式混用、空段、超长段、表格列数不齐、占位符残留(含页眉页脚)、图片引用缺失、修订残留、XML 合法性 | 标准库 |
_ooxml.py | 公共层:整包读写、跨 run 文本合并、命名空间、关系与部件校验;其余 4 个脚本均依赖它,需同目录放置 | 标准库 |
两个容易误解的行为
--normalize只清除直接字号、保留rFonts:清掉中文字体会让汉字回退到西文字体,得不偿失。目标是让段落统一继承 Normal 样式,不是剥光格式。docx_check.py默认把占位符报为 warn(模板文档本就该有占位符);交付成品时用--strict让占位符变成 error,防止漏填。
安装与兼容性
本技能除 SKILL.md 外还包含 scripts/、references/、assets/,必须整个目录放入 Agent 的 skills 目录才能生效;只放 SKILL.md 会导致脚本缺失。
Marvis(Windows / macOS)
- 从 SkillHub 下载 ZIP 包,或直接取得技能目录;
- 解压后把整个技能目录放入:
- Windows:
C:Users<用户名>.marvisskillscustomword-doc-ooxml-pro - macOS:
~/.marvis/skills/custom/word-doc-ooxml-pro/
- Windows:
- 重启 Marvis 客户端(或重新打开会话),技能即被加载;
- 用一句自然语言触发,例如「帮我生成一份 Word 报告」「把这份 docx 转成 Markdown」。
注意:Marvis 客户端「技能广场」收录的技能由平台运营侧维护,与 SkillHub 站内可见状态不是同一目录;SkillHub 的「安装到本地 Agent」一键按钮当前仅支持 WorkBuddy,Marvis 用户需按上述方式手工放置目录。
其他 Agent
| Agent | 目录 |
|---|---|
| WorkBuddy | ~/.workbuddy/skills/ |
| CodeBuddy | ~/.codebuddy/skills/ |
| Claude Code | ~/.claude/skills/ |
| Cursor | ~/.cursor/skills/ |
| Windsurf | ~/.codeium/windsurf/skills/ |
| Codex | ~/.codex/skills/ |
| Gemini CLI | ~/.gemini/skills/ |
其余客户端与最新清单见官方文档 https://skillhub.cn/install/skillhub.md。
运行环境要求
- Python 3.8+,仅用标准库(
zipfile、xml.etree、json、argparse),无需 python-docx / lxml / Word / LibreOffice; - 脚本内部用相对路径引用
_ooxml.py,因此scripts/内 5 个.py必须在同一目录,不可拆散; - 无需联网,可离线运行。
安装排查
| 现象 | 原因与处理 |
|---|---|
| 技能完全不触发 | 目录层级多了或少了:必须是 skills/custom/<技能名>/SKILL.md,不能是 custom/SKILL.md 或双层嵌套 |
| 触发后脚本报找不到模块 | scripts/ 里 5 个 py 文件没放全,或 _ooxml.py 被单独挪走 |
| 改了文件但行为没变 | 客户端有加载缓存,重启客户端后再试 |
| 生成的文件打不开 | 先跑 python scripts/docx_check.py 成品.docx --out check.json,按报告修 error 级问题 |
资源索引
| 文件 | 何时读 |
|---|---|
references/01-ooxml.md | 需要理解 docx 内部结构、手改 XML、处理跨 run 文本、图片/域/修订时 |
references/02-cn-typography.md | 需要确定字体字号行距、公文/商务/论文格式、标题编号体系时 |
references/03-recipes.md | 需要现成场景配方:长报告、合同、公文、批量套打、合并拆分、转 Markdown |
references/04-troubleshooting.md | 出现打不开、乱码、样式丢失、目录不更新、表格跑版、文件异常大时 |
assets/report-template.json | 生成报告/方案类文档的内容 JSON 骨架 |
assets/contract-template.json | 生成合同/协议类文档的内容 JSON 骨架 |
assets/mail-merge-template.json | 批量套打模板(占位符与 CSV 列名一一对应) |
assets/style-presets.json | 中文三套排版预设:公文(GB/T 9704 参照)、商务报告、学术论文 |
输出规范
- 交付
.docx成品 + 一份说明:文件路径、结构摘要、校验结果、待填占位符清单 - 长文档同时给出 Markdown 大纲(由
docx_inspect.py --outline生成),方便用户先审结构 - 批量任务输出清单表格:序号 → 来源数据 → 输出文件 → 校验状态
- 不在对话里粘贴大段 XML;需要展示时只给关键片段并说明作用
红线
- 不编造合同金额、日期、法条、人名、统计数据;缺失一律留占位符并列出
- 不静默丢弃修订、批注、批注者信息;涉及法律/审计文档时尤其注意
- 不覆盖原文件;不删除用户文档中的图片、嵌入对象、域代码,除非明确要求
- 不用
pip install作为默认方案;确需第三方库时先说明原因并取得同意 - 处理含个人信息、商业秘密的文档时不外传内容,只在本地处理