DeepSeek Harness (DSH) 採用插件化架構，旨在通過模塊化工具解決特定開發場景的痛點。在 API 接口的維護與調用過程中，保持接口定義（OpenAPI 規範）與客戶端代碼的一致性，以及及時識別版本升級帶來的破壞性變更，是開發者常遇到的問題。dsh-api-contract 插件正是爲此設計，它能在本地直接解析規範並生成類型化代碼。
插件定位與基礎信息¶
這是一個工作流類插件，由 uckkk 維護，採用 MIT 開源許可證。它是一個純 Node 實現，不依賴網絡或外部服務。
核心能力包括：
* 解析 OpenAPI 3.x 規範（支持 JSON 或 YAML）。
* 生成 TypeScript 類型化客戶端（基於 fetch）。
* 生成 Python 類型化客戶端（基於 requests）。
* 檢測破壞性變更，包括刪除接口路徑/方法、刪除必填參數、參數類型變化、響應結構變化等。
安裝與啓用¶
通過官方插件命令安裝：
dsh plugin add github:uckkk/dsh-api-contract
安裝完成後，需要在項目的 package.json 配置文件中，將插件加入 dsh.profile.bundles 列表，使其在會話中可用：
{
"dsh": {
"profile": {
"bundles": ["dsh-api-contract"]
}
}
}
典型用法¶
安裝並啓用後，可以在 DSH 會話中直接調用插件提供的工具。
1. 生成類型化客戶端
根據指定的 OpenAPI 規範文件生成客戶端代碼。以下命令生成一個 TypeScript 客戶端：
gen_client(spec="openapi.yaml", lang="typescript", outDir="./src/api")
2. 檢測破壞性變更
在升級接口規範版本前，對比新舊規範以發現潛在的破壞性變更。以下命令對比兩個版本：
diff_spec(oldSpec="openapi.v1.", newSpec="openapi.v2.")
適用場景與注意事項¶
- 技術棧：TypeScript 客戶端直接使用瀏覽器原生的
fetch；Python 客戶端依賴requests庫，使用前需確保已安裝（pip install requests）。 - 源碼安全：插件以當前 DSH 進程的權限在本機運行第三方代碼。請務必在安裝前審閱其源碼，確認無安全風險後再使用。
- 格式支持：支持 JSON 以及常見的塊結構 YAML（支持嵌套映射、序列、
$ref引用等）。
總結¶
dsh-api-contract 爲 DSH 環境提供了一套完整的接口契約管理方案。通過解析 OpenAPI 規範生成類型化客戶端並審計破壞性變更，可以減少手動維護代碼的出錯率，提升 API 交互的規範性。
