dsh-universe-api

简体中文

dsh-universe-api is an offline API-discovery plugin for DeepSeek Harness (DSH) and DSH Desktop. It registers one read-only tool, universe_api_search, for deterministic English and Chinese search across a bundled snapshot of the public-apis catalog.

This is a discovery tool, not an API client. It never calls a candidate API, accepts no API keys, and performs no runtime network requests. Verify pricing, availability, authentication, and terms in the provider's official documentation before making an important choice.

Version 0.1.0-rc.1 is a release candidate intended for hands-on testing.

What it provides

• Offline, deterministic search over 1,693 normalized public API records.
• English and Chinese query expansion, Unicode normalization, and CJK-aware matching.
• Hard filters for category, authentication, HTTPS, CORS, status, and source tier.
• Stable ranking with match reasons and catalog freshness metadata.
• An optional private canonical-v1 catalog that fully replaces the bundled snapshot.
• One reusable DSH contract that works in CLI, Web profiles, and DSH Desktop.

The plugin does not silently relax filters when there are no matches. In particular, unknown is distinct from no, and sourceTier: "apilayer" returns zero results with the public-only bundled catalog.

Requirements

• DSH or DSH Desktop with access to a DSH Terminal.
• Node.js ^22.19.0 || >=24.0.0 for source development. DSH Desktop users normally use the runtime supplied by Desktop.

Run all installation commands below in the DSH Terminal opened from DSH Desktop, not an unrelated system shell. Add --profile <name> after plugin and after dsh if you manage a non-default profile.

Install

Choose one source and pin it when possible.

Local checkout

dsh plugin add /absolute/path/to/dsh-universe-api

GitHub tag

dsh plugin add github:Ruixinhua/dsh-universe-api#v0.1.0-rc.1

The package is pure ESM and has no build or prepare install hook, so a GitHub installation does not need pnpm allowBuilds permission.

Release tarball

Download the .tgz and matching .sha256 assets from the GitHub release, place them in the same directory, and verify the checksum:

sha256sum --check dsh-universe-api-0.1.0-rc.1.tgz.sha256
dsh plugin add /absolute/path/to/dsh-universe-api-0.1.0-rc.1.tgz

On macOS, use shasum -a 256 -c dsh-universe-api-0.1.0-rc.1.tgz.sha256 if sha256sum is unavailable.

Confirm activation

dsh --dump-config

Confirm that the output contains a dsh-universe-api layer and plugin row. Fully quit and restart DSH Desktop after installing or changing configuration; opening a new chat alone is not sufficient.

Use

Ask DSH to use the tool explicitly while testing:

Use universe_api_search to find 3 weather APIs that require no API key and have HTTPS=yes and CORS=yes. Explain why each result matched.

Chinese example:

请使用 universe_api_search，找 3 个无需 API key、HTTPS=yes、CORS=yes 的天气 API，并说明匹配理由。

The tool accepts:

Input	Type and behavior
query	Optional natural-language string, up to 2,048 characters. Omit it to browse using filters only.
categories	Optional string array with at most 20 values of up to 128 characters each. Multiple values use OR semantics.
sourceTier	all (default), public, or apilayer.
auth	none, api_key, oauth2, basic, bearer, signed, user_agent, other, or unknown.
https, cors	yes, no, or unknown; values are matched exactly.
status	active, coming_soon, stale, candidate, or unknown.
limit	Integer from 1 to 20; default 5.

Results contain catalog identity and freshness, normalized query details, the applied filters, the total match count, truncation state, and ranked API records with match reasons. Markdown is rendered for chat, while Code Mode can consume the complete structured value.

Use a private catalog

Add a later row to the active profile's cordis.patch.yml (normally under $DSH_HOME/profiles/<name>/) and set catalogPath:

- id: dsh-universe-api
  config:
    catalogPath: '/absolute/path/to/private/catalog.json'

The file must:

• use canonical catalog schema v1;
• be a regular JSON file at an absolute path;
• be no larger than 16 MiB; and
• contain a complete catalog, not a partial overlay.

Use dsh --dump-config with the same profile selection to confirm that this row is the final value for dsh-universe-api. An external catalog fully replaces the bundled public snapshot. It is never merged with the public data. An invalid, missing, relative, oversized, or unreadable file prevents the plugin from loading; there is no silent fallback. Results identify the source as external without exposing the local path. Restart DSH Desktop after changing the file or its path.

See Private catalog format for the canonical-v1 shape and validation rules.

Remove

dsh plugin remove dsh-universe-api

Fully quit and restart DSH Desktop, then confirm with dsh --dump-config that the layer is gone.

Test a release candidate

The maintainer gates are:

npm ci
npm run typecheck
npm test
npm run check
npm pack --dry-run

For a real acceptance test, install the release tarball, not the checkout that produced it. Follow the manual test checklist, which covers offline behavior, exact filters, private catalog replacement, the Web profile, and uninstall.

Data, privacy, and limitations

• The bundled snapshot was generated from public-apis/public-apis commit 988c57be4616cc9507fd3e8c34adedba5387f079 and is distributed under that project's MIT license. See third-party notices.
• No APILayer record from the prior mixed private catalog is redistributed. sourceTier: "apilayer" exists so a compatible private catalog can expose that tier.
• Catalog entries can become stale after the snapshot is generated. The tool does not probe endpoints or verify current provider terms.
• The plugin does not provide a browser UI, semantic embeddings, a remote database, an MCP server, or API execution.
• The private catalog path and API documentation URLs are read for discovery only. The plugin does not accept, store, or transmit credentials.
• Unknown tool arguments are rejected. Never place credentials in a tool call: DSH may retain attempted arguments in its session history even when the plugin rejects them.

Maintainer documentation

• Development and architecture
• Catalog maintenance
• Manual release-candidate testing
• Contributing
• Security policy

License

The plugin code is licensed under the MIT License. Bundled third-party data retains its upstream notice as described in THIRD_PARTY_NOTICES.md.