前言¶
DSH 的文档处理链路里，经常需要回答一个问题：这版文件和上一版相比，到底改了哪几处。用 Word 自带的「比较」，文件要传到别人服务器；用 git diff，输出是行号补丁，改了一句价款要自己在满屏 -/+ 里找。dsh-doc-compare 就是针对这件事做的插件。
这是什么¶
dsh-doc-compare（npm 包名 @deepwhale-cn/dsh-doc-compare）是一个 DSH 插件，作者为 feely0208（温州深鲸智能科技有限公司），MIT 许可证，当前版本 0.1.0。它读入两份 .docx / .md / .txt 文件，按段落做工整差异，输出「改前 → 改后」的报告，适合合同、方案文档的逐条核对。
核心功能¶
下面按 README 列出的能力介绍。
- 段落级三类差异：新增、删除、修改。修改项给出改前和改后内容，并标出改动的词句。
- 结构风险单独提示：标题被改名、被删除、层级从 H2 掉到 H3，会在报告中单独列出。合同场景里这类变化通常比错别字更值得先确认。
- 表格按行比对：报告里给出每个表格的行数变化（例如 3 → 4 行），以及具体哪一行新增、删除或修改。
- 两种输出：默认 Markdown 报告，可用
--out另存；--json输出机器可读结果。 - 本机完成：不联网、不上传、不调第三方接口；
.docx通过纯 JS 库mammoth在本进程内解析。
安装与启用¶
安装命令来自插件 README：
dsh plugin --profile web add @deepwhale-cn/dsh-doc-compare
安装后可用两个入口：命令行 dsh-doc-compare，以及侧栏「文档比对」面板。运行环境要求 Node >= 18、dsh >= 0.1.0-rc.6 且 < 0.3.0；唯一第三方依赖是 mammoth ^1.13.0，纯 JS、离线可用，安装体积约 1.9MB，其余为 Node 内置模块。
典型用法¶
命令行的三种典型调用：
# 出 Markdown 报告到终端
dsh-doc-compare 合同-旧.docx 合同-新.docx
# 另存报告 + 机器可读 JSON
dsh-doc-compare 旧.md 新.md --out 比对报告.md
dsh-doc-compare 旧.txt 新.txt --json
退出码是脚本化调用的关键，README 里给出三档：
| 退出码 | 含义 |
|---|---|
| 0 | 无差异 |
| 1 | 有差异 |
| 2 | 解析失败（文件不存在、格式不支持、docx 损坏） |
需要限制比对量时用 --max-paragraphs。默认只比对前 2000 段（叙述段落，含标题），超出部分会在报告里明确提示；需要完整比对时调大该值，硬上限 5000。
面板侧的用法不同：左右各贴一段文本，本机比对后在面板里看修改/新增/删除，标题结构变化用红色风险条单独列出。文件比对不走面板，面板不读本地路径，需要比对文件时用命令行。
适用场景与注意¶
适合需要逐条确认文档变化的人和流程：签前核对合同、评审方案定稿、批量检查多个版本之间改了哪些条款。差别较大、体积较大的文档，先确认段落数是否落在默认 2000 段以内。
两点使用前提：插件以当前 dsh 进程权限运行，能读到什么文件取决于进程本身的权限；安装前应检查源码与许可证，本插件为 MIT 许可证。插件只读原文件，不会改写文档；只有 --out 会写报告，且写到指定路径。
相关链接¶
- 目录页：https://www.skillhub.cn/plugins/feely0208/dsh-doc-compare
- GitHub：https://github.com/feely0208/dsh-doc-compare
