DeepSeek Harness 插件 dsh-llm-ai 介绍

前言¶

DeepSeek Harness (DSH) 是一个基于插件的平台。在开发智能体或应用时，LLM 适配器是连接模型服务的核心组件。dsh-llm-ai 是一个多提供商的 LLM 适配器插件，由 WooLeo1995 维护。它替代了旧的 dsh-llm-pi-ai 插件，运行在 openai-completions 协议上，并直接从 models.dev 的 api.json 注册表获取模型与提供者信息。

核心功能¶

该插件在 ctx.llm 接口处提供了以下能力：

• models.dev 目录集成：插件加载时会拉取 models.dev 的 api.json 注册表，并将其缓存到本地。支持离线启动，仅在无缓存且无法获取时才报错。
• openai-completions 运行时：使用 harness 自有的流式实现（直接 fetch + SSE），支持文本、工具调用、分层推理、图片输入（受 maxRequestImageBytes 限制）以及使用与缓存统计。
• 稳定的错误代码：提供了一套稳定的错误分类代码（如 AUTH、RATE_LIMIT、TIMEOUT 等），便于上层进行重试或降级处理。
• 兼容性开关：通过 maxTokensField、supportsDeveloperRole、thinkingFormat 等配置项，根据具体模型和协议进行适配，拒绝未知的配置键值。
• 推理声明：支持通过 reasoningEfforts 映射推理级别到 wire 格式，允许通过配置覆盖 models.dev 的默认行为。
• 动态配置：providers 配置字典支持热更新，无需重启进程即可生效。
• 凭证管理：配置中仅存储环境变量引用，请求时通过凭证接口解析，避免明文存储。
• 端点探测：支持对声明的网关进行 GET /models 发现。
• 可配置提供者目录：将 models.dev 的 203+ 提供者声明到配置界面。

安装与启用¶

使用官方 CLI 进行安装。安装过程会自动处理依赖，并禁用旧的 llm-pi-ai 插件以避免冲突。

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

安装命令会执行 pnpm add，并应用 dsh.bundle.patch。该补丁会将 llm-ai 插件挂载到 ctx.llm，同时禁用 llm-pi-ai。由于两者共享配置键，安装过程中若检测到冲突会报错。

配置示例¶

在 cordis.patch.yml 中添加以下配置即可启用。

- 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

配置支持以下参数：
* catalogUrl：可选，用于指定 models.dev 的镜像地址。
* catalogCachePath：可选，指定缓存文件路径。
* providers：定义提供者路由，支持从 models.dev 自动获取或手动声明。

注意事项¶

• 冲突问题：llm-pi-ai 和 llm-ai 不能共存。安装命令会自动处理冲突，但手动迁移时需从 cordis.patch.yml 中移除旧的 llm-pi-ai 禁用行和 llm-ai 插入行。
• 配置项变更：timeoutMs 配置项已被移除。如果手动配置该字段，安装或运行时会报错。
• 缓存位置：缓存文件默认位于 DSH 的 home 目录下的 storages/models-dev-cache.json。
• 协议支持：当前版本（v1）仅支持 openai-completions 协议。anthropic-messages 等协议属于 v2 规划。
• 版本兼容：该插件基于 @deepseek-ai/*@next (0.1.1-rc.2) 开发，与同一代的 DSH 桌面端版本兼容。

总结¶

dsh-llm-ai 通过引入 models.dev 的社区维护目录，解决了多提供商适配的配置繁琐问题。它提供了一套稳定的错误处理机制和运行时接口，适合需要连接多种 OpenAI 兼容模型的 DSH 用户使用。

• GitHub 仓库: https://github.com/WooLeo1995/dsh-llm-ai
• 插件目录: https://www.skillhub.cn/plugins/WooLeo1995/dsh-llm-ai