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