前言¶

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