dsh-llm-gateway-compat: DeepSeek Harness 的 OpenAI 兼容網關適配器

前言¶

DeepSeek Harness (DSH) 採用插件化架構，在對接第三方 OpenAI 兼容網關時，開發者常遇到流式輸出中工具調用 ID 被覆蓋、特定請求 400 錯誤無法自動恢復等問題。dsh-llm-gateway-compat 是社區維護的適配器插件，旨在修復這些兼容性問題，提供更穩定的網關連接能力。

插件定位¶

這是一個非 DeepSeek 官方的社區插件，由用戶 snowshadow 維護。它主要解決 DSH 在與 OpenAI 兼容網關交互時的三個核心痛點：流式工具調用 ID 的覆蓋風險、特定 400 錯誤的處理以及 Chat Completions 路由的適配。

核心功能¶

該插件包含以下功能模塊：

流式工具調用修復
插件會包裹 llm/stream 流程。當流式響應中出現空的 id 或 name 時，這些空值不會覆蓋此前已接收到的非空值。如果沒有接收到任何 ID，插件會自動合成 compat_call_<index>。
請求錯誤處理
插件監聽 agent/request-error 事件。當遇到開發者角色的拒絕或 max_completion_tokens 相關的 400 錯誤時，插件會將匹配字段寫入官方的 llm-pi-ai 兼容配置中，並嘗試重試一次該步驟。對於通用的 400 錯誤，插件不會進行重試。
Chat Completions 路由適配器
插件提供可選的路由適配器，默認使用 system 作爲角色，使用 max_tokens 作爲輸出限制。它確保空工具調用 ID 不會覆蓋，並支持額外的請求字段和自定義認證頭。

安裝與啓用¶

安裝此插件需要 DeepSeek Harness 版本不低於 0.1.5-rc.1。執行以下命令進行安裝：

dsh plugin --profile web add github:snowshadow/dsh-llm-gateway-compat

安裝後需重啓 dsh web 服務。由於插件包含構建產物（位於 lib/ 目錄），無需在安裝時進行 TypeScript 構建。

配置說明¶

插件的所有配置項均需在 settings.yaml 中手動編輯，暫無 Web 設置卡片。

全局開關¶

在 settings.yaml 中添加 llm-gateway-compat 配置段，控制核心行爲：

配置項	默認值	說明
`enabled`	`true`	總開關，控制流式包裹和錯誤恢復功能。
`diagnose`	`true`	分類識別網關 400 錯誤並注入診斷信息。
`autoApplyCompat`	`true`	將識別到的錯誤配置持久化寫入 `llm-pi-ai` 並重試。

提供商路由配置¶

通過 providers 字段定義 Chat Completions 路由。以下是接入阿里雲 DashScope 的示例：

llm-gateway-compat:
  providers:
    dashscope-compat:
      displayName: DashScope
      baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
      apiKeyEnv: DASHSCOPE_API_KEY
      authHeader: bearer
      thinkingFormat: reasoning_content
      extraBody:
        user: harness
      models:
        - id: deepseek-v4-flash
          name: DeepSeek V4 Flash

關鍵參數說明：
* baseURL：網關地址，插件會自動追加 /chat/completions。
* apiKeyEnv：憑證引用，需在模型頁面或環境變量中定義。
* authHeader：認證方式，支持 bearer 或 api-key。
* thinkingFormat：推理格式，可選 reasoning_content（默認）、thinking、think-tags 或 none。
* extraBody：用於傳遞網關特有的字段（如 user），插件會自動剝離 max_completion_tokens 以避免衝突。

限制與注意事項¶

使用該插件時需注意以下限制：

非官方軟件：此包非 DeepSeek 官方出品，不獲得官方背書。
版本要求：必須使用 DeepSeek Harness >= 0.1.5-rc.1。
恢復能力：無法恢復網關從未發送過的工具名稱。
輸入限制：插件拒絕圖像輸入，會返回 UNSUPPORTED_CONTENT 錯誤。
標籤應用：think-tags 僅應用於重放的助手歷史記錄，不適用於流式傳輸中的部分標籤。
配置方式：沒有 Web 設置卡片，所有配置必須手動編輯 settings.yaml。
重放限制：autoApplyCompat 僅在 llm-pi-ai 路由上生效，寫入 supportsDeveloperRole: false 和 maxTokensField: max_tokens。

結語¶

dsh-llm-gateway-compat 通過修復流式調用和錯誤處理機制，提升了 DSH 與第三方 OpenAI 兼容網關的兼容性。開發者可根據自身需求配置路由和參數，但需注意其非官方性質及特定的配置限制。

查看插件目錄
 查看源碼