dsh-docx-batch：整目录的 Word 一次处理完

前言¶

在 DSH（DeepSeek Harness）的生态里，一切皆插件。当开发者需要处理大量 Word 文档时，手动逐份打开、替换、合并既耗时又容易出错。这个插件针对「整目录批量处理」这一场景提供命令行工具，不打开 Word，不动原文件，所有产物写到单独的输出目录。

这是一个工作流分类的 DSH 插件，用于 Word 文档的批量替换、提取、合并与转换。它只读输入文件，默认输出到 <输入目录>/_输出，同名文件自动加序号、不覆盖任何东西。

整目录批量替换文本，--from/--to 可多组。产物是替换后的 .docx 副本，JSON 里给出每个文件替换了几处。

dsh-docx-batch replace --input ./合同 --out ./合同_新 \
  --from 深鲸科技 --to 深海鲸 --from 2024 --to 2026

提取正文文本（含表格），每个文档一个 .txt。

dsh-docx-batch extract --input ./合同 --out ./文本

按文件名自然顺序合并成一个 docx（正文 + 表格），生成 merged.docx，段落数只增不减。

dsh-docx-batch merge --input ./周报 --out ./合并

列出每份文档每一节的页眉、页脚文本，生成 headers.txt。

dsh-docx-batch headers --input ./合同

按「标题样式 → #、表格 → Markdown 表格」转换，每个文档一个 .md。

dsh-docx-batch to-md --input ./合同 --out ./md

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，不动你的任何文件，跑完直接看产物路径就知道它能干什么。

适合需要批量处理 Word 文档的场景，如：合同批量改甲方、周报合并、Word 文档转知识库的 Markdown、核对页眉页脚内容等。

注意：

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

dsh-docx-batch 通过命令行提供整目录的 Word 批量处理能力，适合需要从机械重复的文档操作中解放出来的场景。更多细节与源码可查看：