Degurechaff57/dsh-openapi

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 | 本地或远程规范大小上限 |
| maxResponseBytes | 262144 | 返回给模型的响应体上限 |
| maxRedirects | 3 | 重定向上限；每一跳都会重新校验 |
| maxOperationsPerApi | 1000 | 单个 API 的 operation 上限 |

每个 apis 条目支持：

| 字段 | 默认值 | 用途 |
|---|---:|---|
| id | 必填 | 工具调用使用的稳定 id |
| source | 必填 | HTTP(S) URL、file: URL、绝对路径，或相对 Harness 进程的路径 |
| baseUrl | 规范中的 server | 显式覆盖 API 服务器 |
| headers | {} | 静态非敏感请求头 |
| credentials | [] | 请求头与环境变量映射 |
| allowedMethods | [GET, HEAD] | 工具允许调用的方法 |
| allowPrivateNetwork | false | 显式允许回环/私网目标 |

安全默认值

- 规范只能由管理员配置，模型不能在运行时任意加载 URL。
- 默认只开放 GET、HEAD。
- 只接受 operation 声明过的参数。
- 默认阻止 URL 内凭据、localhost、私网 IP，以及 DNS 解析到私网的主机；每次重定向都会重新检查，跨域重定向会移除凭据。
- 响应体有硬上限，set-cookie 等敏感响应头不会返回给模型。
- 密钥来自环境变量，覆盖调用参数，永远不会出现在工具结果中。

本地开发服务需要设置 allowPrivateNetwork: true。这是明确的信任选择，不是网络沙箱。DNS 在校验和连接之间仍可能变化；高安全场景不要使用不可信的 OpenAPI 文档或恶意 DNS 环境。

当前范围

- OpenAPI 3.0 / 3.1，JSON / YAML
- 本地 #/... 引用
- 常见 path、query、header、cookie 参数序列化
- JSON 与文本响应

暂不跟随远程 $ref，也不猜测 deepObject 等特殊序列化；遇到不明确的输入会直接失败。

DeepSeek Harness 仍处于开发者预览期。本版本已测试当前源码 CLI（0.1.0-rc.5）和 npm 预发布版（0.1.0-rc.6），上游发生破坏性变更后会快速跟进。

开发与测试

npm install
npm run check

测试覆盖解析、引用、operation 索引、请求构造、凭据优先级、方法限制、私网阻止、重定向检查、输出截断和插件注册。

许可证

MIT