前言¶

在 DSH 插件體系中，Agent 經常需要比較兩份內容：配置片段、接口響應、表格或文檔修訂。dsh-tool-diff 是 omdsh-dev 維護的一個 DSH Diff 文本差異工具插件，用於把這類比較收斂爲一個只讀、純函數、零依賴的 diff 工具。

下面介紹它的定位、安裝方式、典型用法和使用邊界。

這是什麼¶

dsh-tool-diff 提供文本 / JSON / CSV / Markdown 結構化比較，並生成 unified diff。

它註冊 diff 工具，row id 爲 tool-diff，許可爲 MIT。

核心功能¶

diff 工具支持以下 action：

• text：文本比較。
• json：JSON 結構化比較。
• csv：CSV 結構化比較。
• markdown：Markdown 結構化比較。
• patch：生成 unified diff，並在內存中校驗，絕不落盤。

所有 action 都會輸出 JSON 文本字符串信封，並帶有通用摘要：

{
  "equal": true,
  "truncated": false,
  "beforeBytes": 128,
  "afterBytes": 132,
  "changes": []
}

其中字段含義如下：

• equal：兩側內容是否相等。
• truncated：輸出是否被截斷。
• beforeBytes：before 側字節數。
• afterBytes：after 側字節數。
• changes：變更列表。

安裝與啓用¶

先安裝到目標 profile，再驗證插件是否已註冊。

已覈實的 headless profile 安裝命令爲：

dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff

注意：

• web 與 headless 是不同 profile。
• web 安裝不會自動覆蓋 headless。
• dsh run 默認使用 headless profile。
• 如果目標 profile 是 web，需要單獨爲 web profile 安裝。

在 web profile 安裝後，可以用下面命令確認工具 row 已出現：

dsh --profile web --dump-config | grep tool-diff

運行驗證：

dsh run "使用 diff 工具對比兩段文本"

典型用法¶

調用 diff 工具時，需要填寫以下字段：

1、action：選擇比較類型，支持 text、json、csv、markdown、patch。

2、before：原內容。

3、after：新內容。

可選字段：

• format：支持 unified、structured、both。
• unified 默認用於 text / patch。
• structured 默認用於 json / csv / markdown。
• key：CSV 場景可用 key 指定主鍵列名或 1-based 索引；缺省按位置比較。

下面是一個最小調用要求：

使用 diff 工具對比兩段文本

適用場景與注意¶

適合以下場景：

• 需要比較兩份文本、JSON、CSV 或 Markdown 內容。
• 需要生成 unified diff。
• 需要只讀、純函數、零依賴的差異比較工具。
• 不希望 patch 文件落盤，只希望在內存中生成並校驗。

使用邊界：

• 只讀：不讀文件、不寫文件、不聯網、不調用 git。
• patch 只在內存中生成並校驗補丁，絕不落盤。
• 輸入單側限制爲 256 KiB。
• 輸出限制爲 64 KiB。
• timeoutMs 爲 2000。
• 工具參數會記入會話日誌，不要傳入敏感數據。
• 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。

參考¶

GitHub 倉庫：

https://github.com/omdsh-dev/dsh-tool-diff