前言¶

DeepSeek Harness（DSH）的插件思路，是把不同能力拆成可安裝的工具。對 API 調用來說，直接讓模型讀取整份 OpenAPI 文檔、再自行拼請求，容易出現參數不一致、憑據處理失控和調用範圍過大。

dsh-openapi 針對這類場景提供一組模型側工具：先列出已配置的 API 與操作，再查看單個操作細節，最後在聲明參數約束下執行調用。

這是什麼¶

dsh-openapi 是面向 DeepSeek Harness 的 OpenAPI 3.x discovery and safe API calling tools 插件，維護者爲 Degurechaff5757，許可證爲 MIT。

它索引已配置的 OpenAPI 3.0 和 3.1 JSON/YAML 文檔，並向模型暴露三個工具：

• openapi_list：發現 API 並搜索操作
• openapi_describe：查看單個操作的參數、請求體、servers 和 responses
• openapi_call：基於聲明參數執行調用，並限制輸出

核心功能¶

下面介紹該插件已提供的主要能力：

1. 支持 API 發現和操作搜索。
2. 支持查看單個操作的參數、請求體、servers 和 responses。
3. 支持基於聲明參數的調用校驗和輸出限制。
4. 支持靜態非密 headers 和 credentials 環境變量映射。
5. 默認只讀，僅啓用 GET 和 HEAD。
6. 默認阻止 URL credentials、localhost 名稱、私有 IP 字面量，以及解析到私有 IP 的主機名。
7. 限制響應體大小，並阻止 set-cookie 等敏感響應頭返回。
8. 限制重定向次數，並對每個重定向目標重新檢查。

安裝與啓用¶

從 GitHub 安裝時，使用下面命令：

dsh plugin --profile web add github:Degurechaff57/dsh-openapi

安裝完成後，API 目錄默認是空的。需要把要調用的 API 添加到 profile 的 cordis.patch.yml 中。

該插件是 plain ESM JavaScript；從 GitHub 安裝時不會運行 build 或 prepare script。

Node engines 要求爲：

^22.19.0 || >=24.0.0

DeepSeek Harness 目前處於 developer preview；這個版本針對 source CLI 0.1.0-rc.5 和 npm prerelease 0.1.0-rc.6 測試。

典型用法¶

先在 profile 的 cordis.patch.yml 中添加 apis 條目。下面以 petstore 爲例：

- id: openapi
  config:
    apis:
      - id: petstore
        source: https://petstore3.swagger.io/api/v3/openapi.json
        baseUrl: https://petstore3.swagger.io/api/v3
        allowedMethods: [GET, HEAD]

這一步聲明瞭 API 文檔來源、基礎 URL 和允許調用的方法。

然後啓動 Harness，可以這樣提出請求：

Use openapi_list to find the operation that lists pets, describe it, then call it.

openapi_list 會先找到相關操作，openapi_describe 會給出參數、請求體、servers 和 responses，openapi_call 會在聲明參數範圍內執行調用。

如果本地有源碼目錄，也可以用本地路徑安裝：

dsh plugin --profile web add /absolute/path/to/dsh-openapi

對於需要鑑權的接口，可以把請求頭映射到環境變量。例如將 Authorization 頭映射到 INTERNAL_API_TOKEN，並設置 prefix Bearer：

- id: openapi
  config:
    apis:
      - id: internal-api
        source: ./openapi/internal.yml
        baseUrl: https://api.example.com/v1
        headers:
          Accept: application/json
        credentials:
          - header: Authorization
            env: INTERNAL_API_TOKEN
            prefix: 'Bearer '
        allowedMethods: [GET, HEAD, POST]

credentials 值來自環境變量，會覆蓋調用提供的值，並且不會出現在工具結果中。

適用場景與注意¶

這個插件適合以下場景：

• 需要讓模型調用已經聲明好的 OpenAPI 操作。
• 希望限制可調用的方法、參數和輸出大小。
• 需要把憑據從 YAML 中移走，並通過環境變量注入。
• 需要避免默認訪問本地或私有網絡目標。

使用前需要注意：

• APIs 由管理員配置，模型不能在運行時加載任意 spec。
• 默認僅允許 GET 和 HEAD。
• allowPrivateNetwork: true 可允許本地或私有網絡目標，但這是明確信任決策，不是網絡沙箱替代品。
• 當前支持 OpenAPI 3.0/3.1 和 local #/... references。
• remote $ref 文檔和 deepObject 等專門序列化尚未支持。
• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼和 MIT 許可證。

結尾¶

dsh-openapi 的價值在於把 OpenAPI 調用收進一組受限工具裏：模型可以看到操作，但不能隨意擴展調用範圍；憑據走環境變量，響應和重定向也有邊界。

GitHub 倉庫：https://github.com/Degurechaff57/dsh-openapi