dsh-openapi

让 DeepSeek Harness 通过安全、结构化的工具调用任意 OpenAPI 3.x API。

English · DeepSeek Harness

dsh-openapi 是 DeepSeek Harness 原生 bundle，会索引配置好的 OpenAPI 文档，并注册三个模型工具：

• openapi_list：列出 API、搜索 operation。
• openapi_describe：查看某个 operation 的参数、请求体、服务器和响应。
• openapi_call：校验并调用 operation，限制返回大小。

项目直接使用 ESM JavaScript，因此从 GitHub 安装时不会执行构建或 prepare 脚本。

为什么需要它

Harness 已经有 Shell，但 API 更适合更窄、更可控的接口：无需把巨大的规范塞进模型上下文；只允许规范声明的参数；凭据来自环境变量；默认只读；校验 SSRF 风险；限制响应大小。本插件通过 Harness 官方扩展点实现这些能力，不修改 agent loop。

安装

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

安装后的 API 目录为空。在 profile 的 cordis.patch.yml 中加入配置：

- 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]

启动 Harness 后可以直接说：

用 openapi_list 找到列出宠物的接口，先描述参数，再调用它。

本地源码安装：

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

凭据配置

不要把密钥写入 YAML。将请求头映射到环境变量：

- 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]

凭据请求头最后写入，模型参数无法覆盖；环境变量缺失时会在发出网络请求前失败。

配置项

顶层配置：

字段	默认值	用途
apis	[]	API 文档列表
timeoutMs	30000	单次调用超时
maxSpecBytes	2097152	本地或远程规范大小上限