中文 · English · 日本語

dsh-deepseek-relay — DeepSeek 中转站思考强度适配插件

让 deepseek-harness（dsh）里通过中转站（第三方 OpenAI 兼容网关，如 OneAPI / new-api / one-hub 或各种「API 转发」服务）接入的 DeepSeek 模型，也能像官方 API 一样在 Web UI 里设置推理等级（思考强度）：Off / Low / High / Max 四档，并把思考参数按中转站认识的格式发出去。

⚠️ 升级须知（v0.1.1，重要）

如果你是从旧版升级的老板，只有一处需要你手动确认：

唯一需要你手动改的地方

如果你的老配置里有个模型实际能识图（比如 deepseek-v4-flash-vision-exp），但之前只写了 id、没写任何能力字段——升级后它默认变为「不支持识图」。想让它能收图，需要手动补一行：

- id: deepseek-v4-flash-vision-exp
  supportsVision: true   # ← 升级后想用识图，这行要自己加

其余模型（纯文本）无需改动，保持原样即可；supportsVision 缺省按 false 处理，这是设计使然——让 harness 在误传图片时给出友好的「该模型不支持图片」提示，而不是把请求发出去再报错。

特性

• ✅ 在 Web UI 暴露 Off / Low / High / Max 四档推理等级（与官方 llm-deepseek 完全一致）
• ✅ 自动按中转站方言（openai / deepseek）序列化思考参数
• ✅ 支持按模型覆盖 wire 值，应对网关要求 ultra 之类自定义取值
• ✅ 支持按模型声明识图能力（supportsVision），收图时给友好拦截
• ✅ 一个插件实例可挂多条中转站路由
• ✅ 纯插件即可生效，无需改动 harness 本体

问题

官方 API 走内置 llm-deepseek 适配器，resolveModel 会返回 reasoning.efforts = [Off, Low, High, Max]，所以 UI 有推理等级选项。

中转站通常走 llm-pi-ai 的「自定义提供方」（openai-completions）。但：

1. Web UI 的表单没有 reasoningEfforts 字段，手写模型没有推理元数据，UI 里根本不出现推理等级选项；
2. 即使声明了，发往中转站的思考参数格式也不一定对——DeepSeek 官方格式（thinking: {type: "enabled"} + reasoning_effort）和 OpenAI 格式（只有 reasoning_effort）在中转站上不通用。

解决方式

本插件注册独立的 OpenAI 兼容适配器路由（每条中转站一条路由），并且：

• 始终向 UI 暴露 Off / Low / High / Max 四档推理等级（与官方 llm-deepseek 完全一致，见 src/adapter.ts 的 REASONING_EFFORTS）；
• 按 thinkingFormat 把思考参数写成中转站认识的方言（见 src/serialize.ts）：

档位	openai（默认）	deepseek
off	不发送任何思考字段（网关默认）	thinking: {type:"disabled"}
low	reasoning_effort: "low"	thinking:{type:"enabled"} + reasoning_effort:"low"
high	reasoning_effort: "high"	thinking:{type:"enabled"} + reasoning_effort:"high"
max	reasoning_effort: "max"	thinking:{type:"enabled"} + reasoning_effort:"max"

• thinkingFormat: auto 时按 baseURL 域名猜：含 deepseek.com/ai/cn 用 deepseek，其余默认 openai（多数中转站）。
• 支持按模型覆盖 wire 值（reasoningEfforts），应对「网关要求 ultra 之类自定义取值」的场景。

使用

两种方式都符合官方插件规范（见下文「官方规范符合性」）：

方式 A：从源码运行，--patch 本地加载（开发 / 自用）

在 deepseek-harness 仓库根目录（已 pnpm install 过）：

pnpm dsh web --patch ./dsh-deepseek-relay/cordis.yml

启动前先编辑 cordis.yml，把 providers.relay 换成你的中转站信息：

- insert:
    - id: dsh-deepseek-relay
      name: '/绝对路径/deepseek-harness/dsh-deepseek-relay/src/index.ts'
      config:
        providers:
          my-relay:
            baseURL: https://your-relay.example.com/v1
            apiKeyEnv: RELAY_API_KEY
            thinkingFormat: auto
            models:
              - id: deepseek-v4-flash
              - id: deepseek-v4-flash-vision-exp
                supportsVision: true   # 能识图的模型记得开

• API key：设置环境变量 RELAY_API_KEY，或启动后在 Web UI 设置 → 模型 里选中该提供方填入密钥（密钥存 $DSH_HOME/.credentials.yaml）。
• 模型：models 列表即模型选择器里出现的模型；contextWindow / maxTokens 会作为上下文 / 输出上限信息。
• 保存后，在模型选择器选到该模型的会话里，输入框旁就会出现 Off / Low / High / Max 推理等级下拉（和官方 API 一样）。

方式 B：作为组合包（bundle）安装（可分发）

# 本地目录 / git / tarball 均可；首次会初始化 profile
dsh plugin --profile demo add ./dsh-deepseek-relay
# 或 dsh plugin --profile demo add github:you/dsh-deepseek-relay

包内 cordis.patch.yml 声明了插件行（name: dsh-deepseek-relay 按包名解析，加载 lib/index.js），prepare 脚本（esbuild）会在安装时自动构建 lib/。安装后插件处于 dormant（空配置可安全装载，不注册任何路由 / 目录，适配器与 configurable-provider 目录两侧都有空数组守卫，见 src/index.ts 的 ensureDirectory / ensureRegistrationFacts），在 profile 的 cordis.patch.yml 或 $DSH_HOME/cordis.patch.yml 里覆盖同 id 行填入中转站配置（参考 cordis.patch.yml 顶部注释），或随后在 Web UI 设置中热更新生效。

配置项

字段	说明	默认
baseURL	中转站 OpenAI 兼容地址，/chat/completions 自动拼接	必填
apiKeyEnv	API key 环境变量名	RELAY_API_KEY
displayName	模型选择器显示名	路由 key
thinkingFormat	auto / openai / deepseek	auto
reasoningEffort	默认推理等级 off/low/high/max	high
maxTokensField	输出上限字段 max_tokens/max_completion_tokens	max_tokens
maxTokens	路由级默认输出上限	256000
models[].id	发往网关的模型 id	必填
models[].name	选择器显示名	id
models[].contextWindow	上下文容量	262144
models[].maxTokens	该模型输出上限	路由级值
models[].reasoningEfforts	按档位覆盖 wire 值（null=支持但不发送）	方言默认
models[].supportsVision	模型是否支持识图（Web UI 中是模型行的「支持识图」勾选框）。true → inputModalities:['text','image']；false 或省略 → ['text']（显式非 undefined，让 harness 在提交图片时给出友好的「模型不支持图片」提示）	false

💡 升级用户看这里：老配置里若某个模型实际能识图但只写了 id，升级后它会按 supportsVision: false 处理——想用识图就按上方「升级须知」补一行 supportsVision: true。

官方规范符合性

对照仓库 docs/user/develop/basic/{index,config,publish}.zh.md 与 docs/user/develop/practice/llm-adapter.zh.md：

官方要求	本插件
插件模块导出 name + apply(ctx, config)	✅ src/index.ts
声明 inject（本插件依赖 llm 服务）	✅ inject = ['llm']
导出 Config 类型 + 同名 Schemastery schema，默认值写在 schema 中	✅ src/index.ts
--patch overlay 加载本地插件（源码路径 .ts）	✅ cordis.yml（方式 A）
组合包 dsh.bundle manifest + cordis.patch.yml（按包名引用）	✅ package.json + cordis.patch.yml（方式 B）
git 安装的 TS 包必须自带 prepare 构建（产出 lib/）	✅ scripts/build.mjs + tsconfig.build.json
LlmAdapter 契约：实现 stream()、resolveModel 返回 reasoning 元数据、attributionHeaders()、LlmError 稳定 code、透传 options.signal	✅ src/adapter.ts

注：--patch 从源码路径加载 .ts 是官方教程支持的开发方式；正式分发（npm / git / tarball）走方式 B，prepare 构建出 lib/index.js 后与源码运行等价。两种方式共用同一份 src/。

备选：不装插件，直接用官方 llm-pi-ai 手工配置

官方 llm-pi-ai 本身支持同样的能力，只是要手写 $DSH_HOME/settings.yaml。如果不想装插件，可以这样写（等效于 thinkingFormat: deepseek）：

llm-pi-ai:
  providers:
    my-relay:
      apiKeyEnv: RELAY_API_KEY
      api: openai-completions
      baseURL: https://your-relay.example.com/v1
      compat:
        thinkingFormat: deepseek
      models:
        - id: deepseek-v4-flash
          reasoningEfforts:
            off:
            low: low
            high: high
            max: max

注意：reasoningEfforts 里 off: 冒号后留空表示「支持该档、不发送」；其余档必须给 wire 值，否则配置被拒。多数网关（OneAPI 等）应使用 thinkingFormat: openai 而不是 deepseek，除非网关原样转发官方 API。

代码结构

dsh-deepseek-relay/
├── cordis.yml          # --patch 本地加载配置示例（方式 A）
├── cordis.patch.yml    # 组合包配置层（方式 B，dsh.bundle.patch 指向它）
├── package.json        # dsh.bundle manifest + scripts（prepare 构建）
├── scripts/build.mjs   # esbuild 构建单文件 lib/index.js（external @deepseek-ai/*）
├── tsconfig.json       # 类型检查（tsc --noEmit）
└── src/
    ├── index.ts      # 插件入口：Config schema、路由注册、settings 热更新
    ├── adapter.ts    # RelayAdapter：四档推理等级 + fetch/SSE stream
    ├── serialize.ts  # 消息 + 思考参数序列化（openai/deepseek 方言）
    ├── translate.ts  # SSE chunk → harness StreamChunk
    ├── sse.ts        # SSE 解析（eventsource-parser）
    └── types.ts      # wire 类型

验证

• tsc --noEmit 完整类型检查：0 错误（对 @deepseek-ai/dsh-llm 等 0.1.1-rc.2 官方 npm 包）。
• 序列化逻辑测试（resolveThinking / resolveThinkingFormat / serializeRequest，openai/deepseek 方言 × off/low/high/max × 模型级覆盖 × session-title × maxTokensField）：全部通过。
• SSE 转换测试（reasoning_content 流、tool_calls 增量拼接、usage 去重、[DONE] 收尾、空响应）：全部通过。
• 验证依赖通过 npm 平铺安装（C:/Users/29261/Downloads/relay-verify，测试脚本可复用）。

注意事项

• 中转站若在 /chat/completions 之外还有 /v1 后缀，baseURL 写完整路径，例如 https://relay.example.com（若网关恰好要求不带 /v1）。
• 插件默认只支持文本输入（与官方 llm-deepseek 一致）；图片输入会以 UNSUPPORTED_CONTENT 拒绝。若某模型已声明 supportsVision: true，但图片传输功能（attachments store 集成）尚未实现，会给出 UNSUPPORTED_CONTENT（「图片传输待实现」），届时再补。
• 一个插件实例可配多条中转站路由（providers dict 里加即可）。

免责声明

本插件为第三方非官方适配层，与 DeepSeek 官方无隶属关系。使用中转站 / 第三方网关请遵守其服务条款与当地法律法规；本插件按「现状」提供，不保证适配所有网关，也不对安装、使用、升级过程中可能造成的任何数据丢失、配置损坏或账号风险负责。升级前请自行备份 $DSH_HOME（含 settings.yaml 与 .credentials.yaml）。点击本仓库链接即视为已知晓并同意上述条款。