前言¶
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
