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 兼容网关的兼容性。开发者可根据自身需求配置路由和参数，但需注意其非官方性质及特定的配置限制。

查看插件目录
 查看源码