前言¶
在 DeepSeek Harness（DSH）裏和 agent 討論接口時，常見做法是邊聊邊寫文檔或直接在代碼裏改路由。問題在於：命名、分頁、錯誤碼、版本往往寫到一半才暴露分歧；接口一改，也很難用同一套標準判斷會不會傷到已有客戶端。
@jojonadam/dsh-api-contract（GitHub：JOJO-Adam/dsh-api-contract）面向的是接口這一層：契約先行、可被機器校驗、變更用同一把尺子評審。它不是「讓 AI 寫一份接口文檔」，而是把開接口、審 OpenAPI、判破壞性變更、定錯誤契約等步驟放進可重複觸發的技能流程。維護者爲 JOJO-Adam，社區目錄分類爲「工作流」。
這是什麼¶
一句話定位：API contract studio for DeepSeek Harness——契約優先編寫、破壞性變更評審、錯誤契約、版本與文檔（README 與 package 描述中概括爲 contract-first authoring、breaking-change review、error contracts、versioning、docs）。
插件當前版本爲 0.1.0（見 package.json），許可證 MIT。運行環境要求：Node.js >= 20，DSH >= 0.2.0-rc.2。
核心功能¶
裝完之後，README 列出的能力包括：
- 開新接口：把必須早定的七件事（資源邊界、命名、分頁、錯誤、鑑權、冪等、版本）一次問清楚，而不是寫到一半才發現分歧。
- 寫/審 OpenAPI：資源導向的路徑設計、
components複用、請求響應約定，以及那些會悄悄變成破壞性變更的反模式。 - 判破壞性變更：按變更類型給出客戶端具體壞在哪，含「未知字段」這類常被忽略的兼容例外。
- 定錯誤契約：HTTP 狀態碼與業務錯誤碼的分工，以及業務失敗仍返 200 的反模式。
- 版本與棄用：什麼時候才真需要新版本、版本放哪、四步棄用流程。
- 文檔與示例：文檔從契約生成，示例質量的四個層次。
邊界（同樣來自 README）：只管接口層（契約、演進、文檔），不替代框架選型與代碼規範；變更檢測以你提供的契約文件爲準，沒有契約時應先補契約；不生成可直接上線的服務端實現。
安裝與啓用¶
安裝命令須使用資料原文，區分 Web 與桌面 profile：
# Web 版
dsh plugin --profile web add @jojonadam/dsh-api-contract
# 桌面版
dsh plugin --profile desktop add @jojonadam/dsh-api-contract
DSH 插件以當前 dsh 進程權限運行。安裝前建議自行查看 GitHub 倉庫 源碼與 MIT 許可證，確認符合團隊安全與合規要求。
典型用法¶
README 說明：直接用自然語言即可觸發，也可顯式點名技能。例如：
- 「幫我設計一個訂單接口的契約」
- 「這次把 status 改成枚舉算不算破壞性變更」
- 「錯誤碼怎麼設計」
經過上面的步驟，你和 agent 討論接口時會先拿到一份能落地的契約；要改接口時，它會先告訴你這次會不會傷到現有客戶端。
適用場景與注意¶
適合誰：需要在 agent 協作下做 REST/OpenAPI 契約設計、評審接口變更、統一錯誤與版本策略的團隊或個人；已有或計劃維護 OpenAPI 契約文件的場景與「變更以契約文件爲準」的設定一致。
注意：
- 生態上 DSH 的理念是「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係，不要當作官方應用商店。
- 無契約文件時，插件側的第一件事是補契約，而不是憑空做破壞性對比。
- 星標與版本以你安裝時倉庫/目錄頁爲準；撰寫時 GitHub 公開星標爲 0。
結尾¶
dsh-api-contract 的價值在於把接口層的判斷變成可複覈的流程：契約先行 → 機器可校驗 → 變更用同一標準評審。若要安裝或查看詳情，可訪問 SkillHub 插件頁 與 GitHub：JOJO-Adam/dsh-api-contract。
