Introduction

DeepSeek Harness (DSH) is a plugin-based platform. When developing agents or applications, the LLM adapter is the core component that connects model services. dsh-llm-ai is a multi-provider LLM adapter plugin maintained by WooLeo1995. It replaces the older dsh-llm-pi-ai plugin, runs on the openai-completions protocol, and directly fetches model and provider information from the api.json registry of models.dev.

Core Features

The plugin provides the following capabilities at the ctx.llm interface:

  • models.dev Catalog Integration: The plugin fetches the models.dev api.json registry on load and caches it locally. Offline startup is supported; it only reports an error if no cache exists and the registry cannot be fetched.
  • openai-completions Runtime: Uses the harness’s built-in streaming implementation (direct fetch + SSE) and supports text, tool calls, hierarchical reasoning, image input (limited by maxRequestImageBytes), as well as usage and cache statistics.
  • Stable Error Codes: Provides a stable set of error classification codes (such as AUTH, RATE_LIMIT, TIMEOUT, etc.) to facilitate retry or fallback handling at the upper layer.
  • Compatibility Flags: Adapts behavior based on the specific model and protocol through configuration items such as maxTokensField, supportsDeveloperRole, and thinkingFormat, while rejecting unknown configuration key values.
  • Reasoning Declaration: Supports mapping reasoning levels to the wire format via reasoningEfforts, allowing the default models.dev behavior to be overridden through configuration.
  • Dynamic Configuration: The providers configuration dictionary supports hot updates and takes effect without restarting the process.
  • Credential Management: The configuration stores only environment variable references. Credentials are resolved through the credential interface at request time, avoiding plaintext storage.
  • Endpoint Probing: Supports GET /models discovery for declared gateways.
  • Configurable Provider Catalog: Exposes the 203+ providers from models.dev in the configuration interface.

Installation and Activation

Use the official CLI to install. The installation process handles dependencies automatically and disables the old llm-pi-ai plugin to avoid conflicts.

dsh plugin --profile <name> add dsh-llm-ai

The installation command executes pnpm add and applies dsh.bundle.patch. This patch mounts the llm-ai plugin to ctx.llm while disabling llm-pi-ai. Because both share configuration keys, an error is reported if a conflict is detected during installation.

Configuration Example

Add the following configuration to cordis.patch.yml to enable it.

- id: llm-ai
  name: '@deepseek-ai/dsh-llm-ai'
  config:
    catalogUrl: https://models.dev/api.json
    catalogCachePath: /path/to/cache
    providers:
      openai:
        apiKeyEnv: OPENAI_API_KEY

The configuration supports the following parameters:
* catalogUrl: Optional. Used to specify a mirror address for models.dev.
* catalogCachePath: Optional. Specifies the cache file path.
* providers: Defines provider routing and supports automatic retrieval from models.dev or manual declaration.

Notes

  • Conflict Issue: llm-pi-ai and llm-ai cannot coexist. The installation command handles conflicts automatically, but during manual migration, you need to remove the old llm-pi-ai disable line and the llm-ai insert line from cordis.patch.yml.
  • Configuration Change: The timeoutMs configuration item has been removed. Manually configuring this field will cause an error during installation or runtime.
  • Cache Location: The cache file is located by default at storages/models-dev-cache.json under the DSH home directory.
  • Protocol Support: The current version (v1) only supports the openai-completions protocol. Protocols such as anthropic-messages are planned for v2.
  • Version Compatibility: The plugin is developed based on @deepseek-ai/*@next (0.1.1-rc.2) and is compatible with the same-generation DSH desktop version.

Summary

dsh-llm-ai introduces the community-maintained models.dev catalog, solving the cumbersome configuration problem of multi-provider adaptation. It provides a stable error handling mechanism and a runtime interface, making it suitable for DSH users who need to connect to multiple OpenAI-compatible models.

  • GitHub repository: https://github.com/WooLeo1995/dsh-llm-ai
  • Plugin directory: https://www.skillhub.cn/plugins/WooLeo1995/dsh-llm-ai