前言¶
在 DSH 裏維護或評審 API 契約時，常見做法是人工對比兩份 OpenAPI 文檔，或依賴完整語義解析與行爲級契約測試。前者容易漏掉「新增必填字段」「參數從可選變必填」「響應類型變更」等結構性破壞；後者成本高，也不總是發佈前必跑的一步。下面介紹社區插件 dsh-openapi-diff（維護者 lengrufeng2008），它對兩份 OpenAPI JSON 做結構性破壞性變更檢查，並在 DSH 中通過工具 openapi_diff 調用，適合在改 spec、發版或安全/治理流程裏做快速門禁。
DeepSeek Harness 的理念是「一切皆插件」；插件目錄頁託管在 SkillHub 等社區站點，與 DeepSeek / 幻方無官方從屬關係，安裝前請自行覈對源碼與許可證。
這是什麼¶
dsh-openapi-diff 的定位是：針對 OpenAPI JSON 文檔，比較「舊版」與「新版」，報告可能破壞客戶端或下游集成的結構級差異。倉庫：https://github.com/lengrufeng2008/dsh-openapi-diff。SkillHub 分類爲 admin-security；當前 GitHub 星標爲 0。許可證爲 MIT（README Provenance）。
核心功能¶
依據 README 與 package.json 描述，插件關注下列一類變更（均爲結構性，而非運行時行爲）：
- 刪除的 paths、methods、parameters、properties、responses
- 新增必填字段（new required fields）
- 參數由可選變爲必填（parameter-became-required）
- 類型變更（type changes）
命令行與庫側入口見倉庫 bin/dsh-openapi-diff.mjs 與導出路徑 ./diff；在 DSH 側通過 Cordis bundle（plugin/cordis.patch.yml）集成工具 openapi_diff。
能力邊界¶
README Limits 一節說明，使用前應明確預期：
- 僅支持 JSON 格式的 OpenAPI，不支持 YAML 等其它序列化形式（除非你先自行轉成 JSON）。
- 檢查的是結構性子集：不做完整的
$ref解析，也不處理 oneOf / allOf 的完整語義。 - 不是行爲兼容測試或契約測試（contract test）。
- 無報錯結果不能證明 API 完全兼容；它只是結構性 diff 輔助，不能替代聯調與測試。
環境與依賴¶
package.json 要求 Node.js >= 20，包類型爲 ES module（"type": "module"）。
典型用法¶
命令行¶
在倉庫根目錄，對兩份 JSON spec 做對比：
node bin/dsh-openapi-diff.mjs old.json new.json
需要機器可讀輸出時：
node bin/dsh-openapi-diff.mjs old.json new.json --json
在 DSH 中¶
README 給出的調用方式爲：
Use openapi_diff with old=old.json new=new.json.
即在 Harness 會話中讓智能體使用 openapi_diff 工具，並傳入 old、new 兩個 spec 文件路徑（或等價參數，以插件實際 schema 爲準）。已抓取資料中未給出 SkillHub 或 README 上的 dsh plugin add … 一類安裝命令；若從目錄頁安裝，請以 SkillHub 插件頁 與倉庫文檔當時展示的內容爲準，勿憑倉庫名自行拼接命令。
自測¶
維護者提供的測試命令：
npm test
對應 package.json 中的 node --test test/*.test.mjs。
適用場景與注意¶
適合：需要在改 OpenAPI JSON、合併 PR 或發佈前，快速列出「刪 path/方法/參數/屬性/響應、新必填、類型變」等明顯破壞性結構變更的團隊；與 admin-security 分類下的治理、變更審查流程可以配合使用（仍須人工判斷業務是否真 breaking）。
注意：
- 插件在 當前 DSH 進程權限下運行，能讀寫的路徑與宿主一致；安裝或啓用前請閱讀
plugin/、src/源碼及 MIT 許可證。 - 僅 JSON、無完整
$ref/ oneOf / allOf 語義，複雜 spec 可能漏報或誤報邊界情況，重要發佈應結合真實客戶端測試。 - 社區插件星標與活躍度會變化；以 GitHub 與目錄頁爲準，本文不引用未在資料中出現的用戶案例或數據。
結尾¶
dsh-openapi-diff 提供一份輕量、獨立的 OpenAPI JSON 結構性破壞性變更檢查，可在 CLI 或 DSH 的 openapi_diff 中使用，用於在完整契約測試之前做快速 diff 門禁。目錄頁：https://www.skillhub.cn/plugins/lengrufeng2008/dsh-openapi-diff；源碼與說明：https://github.com/lengrufeng2008/dsh-openapi-diff。
