@deepwhale-cn/dsh-docx-batch

整目录的 Word 一次处理完：批量替换文本、提取正文、按文件名合并、列页眉页脚、转 Markdown —— 不打开 Word，不动原文件。

关键词：Word 批量替换 · docx 批量处理 · 批量合并 Word · 提取 Word 文本 · Word 转 Markdown · 页眉页脚提取 · 合同批量改甲方 · 命令行处理 Word

不装会怎样

50 份合同要统一把甲方「深鲸科技」改成「深海鲸」：不装就得逐份打开 Word、Ctrl+H、保存、关掉， 半小时起步，改到第 37 份时手一滑漏一份也没人发现。

几十份周报要合成一份、把 Word 文档塞进知识库前要先转成 Markdown、需要核对每份文档的页眉页脚 写的是什么 —— 这些都属于「机械但量大」的活，人工做既慢又容易漏。

更麻烦的是：直接让 AI 改原文件，一旦改坏没有退路。这个插件只读输入，所有产物写到单独的输出目录， 同名文件自动加序号、不覆盖任何东西。

能做什么

子命令	作用	产物（可核对）
replace	整目录批量替换文本，--from/--to 可多组	替换后的 .docx 副本；JSON 里给出每个文件替换了几处
extract	提取正文文本（含表格）	每个文档一个 .txt
merge	按文件名自然顺序合并成一个 docx（正文 + 表格）	merged.docx，段落数只增不减
headers	列出每份文档每一节的页眉、页脚文本	headers.txt
to-md	按「标题样式 → #、表格 → Markdown 表格」转换	每个文档一个 .md

共同约定：

• 不修改输入文件，默认输出到 <输入目录>/_输出，可用 --out 指定；
• 同名文件不覆盖：已存在时自动变成 合同_1.docx、合同_2.docx；
• 目录递归处理，自动跳过 Word 临时文件（~$ 开头）和 _输出 目录；
• --json 输出结构化结果，方便脚本 / CI 断言；出错时退出码非 0 并说明缺什么。

# 整目录替换，多组同时替换
dsh-docx-batch replace --input ./合同 --out ./合同_新 \
  --from 深鲸科技 --to 深海鲸 --from 2024 --to 2026

# 提取正文
dsh-docx-batch extract --input ./合同 --out ./文本

# 按文件名顺序合并
dsh-docx-batch merge --input ./周报 --out ./合并

# 页眉页脚清单 / 转 Markdown
dsh-docx-batch headers --input ./合同
dsh-docx-batch to-md --input ./合同 --out ./md

不能做什么

• ❌ 不保证排版 100% 不变：替换跨多个 run（同一段里被拆开的文字块）时会合并该段落的 run， 段落内的局部加粗、字号、颜色可能丢失。重要文档请先跑一份对比再批量用。
• ❌ 不处理 .doc（老格式）、.docm、加密/需要密码打开的文档；.doc 请先另存为 .docx。
• ❌ 不处理脚注、尾注、批注、文本框、SmartArt、图片里的文字 —— 只覆盖正文段落、表格、页眉页脚。
• ❌ merge 只合并正文和表格；页眉页脚、样式主题不合并，复杂排版（分栏、自动编号域）会退化为纯文本顺序。
• ❌ headers 只读页眉页脚，不改；replace 能改页眉页脚里的文字。
• ❌ 不是格式转换器：不导出 PDF、不做 OCR、不做批量重命名。
• ❌ 替换是字面匹配，大小写敏感，不支持正则；--from 是空字符串之类无意义输入不做特殊处理。
• ✅ 全部在本机由 python-docx 处理，不联网、不上传文档。

安装

dsh plugin --profile web add @deepwhale-cn/dsh-docx-batch

运行依赖本机的 python3 + python-docx（插件不会替你装）。缺依赖时 CLI 会直接打印安装命令：

python3 -m pip install python-docx
# macOS 没有 python3 时
brew install python3

用法

dsh-docx-batch --help
dsh-docx-batch --demo        # 自造样例文件跑完整流程，打印产物路径
dsh-docx-batch <action> --input <文件或目录> [--out <目录>] [--json]

--demo 会在系统临时目录里造样例文档并依次跑 replace / extract / to-md / merge / headers， 不动你的任何文件，跑完直接看产物路径就知道它能干什么。

License

MIT © 温州深鲸智能科技有限公司