dsh-openapi
让 DeepSeek Harness 通过安全、结构化的工具调用任意 OpenAPI 3.x API。
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](LICENSE)