dsh-openapi
适用于 DeepSeek Harness 的 OpenAPI 3.x 发现和安全 API 调用工具。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Degurechaff57/dsh-openapi#fb854355b89e495ded090b9e2eb94c33430d2366Openapi 以 dsh-openapi 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Give DeepSeek Harness a safe, structured doorway into any OpenAPI 3.x API.
dsh-openapi is a native DeepSeek Harness bundle that indexes configured OpenAPI documents and adds three model-facing tools:
openapi_list discovers APIs and searches operations.openapi_describe returns parameters, request bodies, servers, and responses for one operation.openapi_call validates and invokes an operation with bounded output.It is plain ESM JavaScript, so installing from GitHub does not run a build or prepare script.
Harness already gives an agent a shell. APIs still benefit from a narrower interface: operation discovery without reading a huge spec into the model context, declared-parameter validation, environment-backed credentials, read-only defaults, SSRF checks, and response limits. This plugin provides those controls without patching the Harness agent loop.
dsh plugin --profile web add github:Degurechaff57/dsh-openapi
The bundle installs with an empty API catalog. Add API entries to your profile's 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]
Start Harness and ask:
Use
openapi_listto find the operation that lists pets, describe it, then call it.
For a source checkout, install the local directory instead:
dsh plugin --profile web add /absolute/path/to/dsh-openapi
Keep secrets out of YAML. Map a request header to an environment variable:
- 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]
The credential header is applied after model-supplied header parameters, so a tool call cannot override it. Missing environment variables fail the call before network I/O.
Top-level options:
| Field | Default | Purpose |
|---|---|---|
apis | [] | Configured API documents |
timeoutMs | 30000 | Per-call timeout |
maxSpecBytes | 2097152 | Maximum local or remote spec size |
maxResponseBytes | 262144 | Maximum response body returned to the model |
maxRedirects | 3 | Redirect limit; every destination is rechecked |
maxOperationsPerApi | 1000 | Catalog size limit per API |
Each apis entry accepts:
| Field | Default | Purpose |
|---|---|---|
id | required | Stable id used in tool calls |
source | required | HTTP(S) URL, file: URL, absolute path, or path relative to the Harness process |
baseUrl | spec server | Explicit API server override |
headers | {} | Static non-secret headers |
credentials | [] | Header/environment-variable mappings |
allowedMethods | [GET, HEAD] | Methods the tool may invoke |
allowPrivateNetwork | false | Opt in to loopback/private-network destinations |
GET and HEAD are enabled.set-cookie are not returned.allowPrivateNetwork: true is necessary for local development servers. It is an explicit trust decision, not a substitute for a network sandbox. DNS can change between validation and connection, so do not use untrusted OpenAPI documents or hostile DNS infrastructure for high-assurance isolation.
#/... referencesRemote $ref documents and specialized serialization such as deepObject are intentionally not followed yet. The plugin fails loudly instead of making an ambiguous request.
DeepSeek Harness is in developer preview. This release is tested against the current source CLI (0.1.0-rc.5) and npm prerelease (0.1.0-rc.6); compatibility updates will follow upstream breaking changes.
npm install
npm run check
The test suite covers parsing, references, catalog generation, request construction, credential precedence, method restrictions, private-network rejection, redirect validation, output truncation, and plugin registration.