DeepSeek Harness 踩坑指南（基于大模型网关）

架构彭鱼宴
69 阅读5分钟

我的开源大模型网关项目：github.com/boonya-hrgk…

image.png

基于一次完整的 Windows 环境安装、插件配置、自定义网关接入的实战记录整理。

一、环境准备阶段

坑 1：Node 版本检查与 nvm 使用

现象：执行 nvm use 22.19.0 报 activation error: Version not installed。

原因：nvm 只能切换到已安装的版本，不会自动下载。

正确做法：

bash

nvm ls                    # 先看已安装哪些版本
nvm install 22.19.0       # 需要哪个版本先装
nvm use 22.19.0

DSH 要求 Node 22.19.0+  或 24.0.0+ 。如果已有更高版本（如 22.22.0），直接用即可，不必降级。

坑 2：dsh 命令找不到

现象：'dsh' 不是内部或外部命令。

原因：只用了 npx @deepseek-ai/dsh web 临时运行，从未全局安装，系统 PATH 里自然没有 dsh。

正确做法：

bash

npm install -g @deepseek-ai/dsh

安装后必须重开终端窗口，否则 PATH 不会刷新。验证：

bash

dsh --version

网络慢时可加镜像：

bash

npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com

二、插件安装阶段

坑 3：装了废弃包，触发重复 loader entry

现象：dsh web 启动报

text

duplicate loader entry id: web-ui-compat

原因：package.json 里同时存在旧包 @linxin666/dsh-web-ui-all 和新包 @linxin666/dsh-web-all，两者都含 compat 桥接层，同一 id 被注册两次。

排查：

cmd

type C:\Users\Lenovo.dsh\profiles\web\package.json

看 dependencies 和 dsh.profile.bundles 是否两个包都在。

解决：

cmd

dsh plugin --profile web remove @linxin666/dsh-web-ui-all

若移除后仍报重复，再检查 cordis.patch.yml 里有无手写的 web-ui-compat insert 残留行，一并删除。

教训：dsh-web-ui-all 已废弃，统一用 @linxin666/dsh-web-all@latest。

坑 4：pnpm 拦截原生构建脚本

现象：插件安装报

text

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: cloudflared, cpu-features, node-pty, ssh2

原因：pnpm 10+ 默认拦截需要运行编译脚本的依赖（防止恶意脚本）。这些是 DSH 终端功能依赖的原生模块，不编译则运行时崩溃。

解决（交互式） ：

bash

dsh plugin --profile web approve-builds

逐个批准即可。

解决（非交互式） ：编辑 C:\Users\Lenovo.dsh\profiles\web\pnpm-workspace.yaml：

yaml

allowBuilds:
  cloudflared@0.7.3: true
  cpu-features@0.0.10: true
  node-pty@1.1.0: true
  ssh2@1.17.0: true

坑 5：模块回退层的真实目录冲突

现象：

text

dsh: ....dsh-module-fallback\node_modules\dagre-d3-es exists and is not a symlink or dsh-managed module proxy

原因：healProfileModuleFallback 要求回退层里的条目必须是符号链接。Windows 下创建软链常需管理员权限，某些操作退化成直接复制真实目录，dsh 拒绝接管。

解决：删掉不合规目录，或干脆删掉整个回退层让它重建：

cmd

rmdir /s /q "C:\Users\Lenovo.dsh\profiles\web.dsh-module-fallback"

回退层只是运行时解析缓存，不影响插件本体（插件还在 package.json 和 pnpm store 里）。

验证配置是否完好：

bash

dsh --profile web --dump-config

注意：--dump-config 能打印 ≠ dsh web 能启动。前者只读配置，后者会执行 composeProfile 和 heal 逻辑，路径不同。

三、自定义大模型网关接入

坑 6：reasoning effort 不被支持

现象：

text

provider "llm-api-gateway" model "deepseek-v4-flash" does not support reasoning effort "low"

原因：DSH 默认可能给请求带上 reasoning_effort 参数，但你的模型/网关不支持。

解决：在 provider 配置里去掉 reasoning effort 相关设置。

坑 7：405 Method Not Allowed —— baseURL 少了 /v1

现象：网关日志：

text

POST /v1/messages?beta=true HTTP/1.1 200 OK          ← Anthropic 端点正常
POST /chat/completions HTTP/1.1 405 Method Not Allowed  ← DSH 请求打错路径

原因：DSH 配的是 api: openai-completions，会向 baseURL 拼 /chat/completions。若 baseURL 只写到 http://192.168.5.34:9000，实际请求变成 /chat/completions；而网关的 OpenAI 兼容端点挂在 /v1/chat/completions，故 405。

解决：baseURL 补全到 /v1：

yaml

llm-pi-ai:
  providers:
    llm-api-gateway:
      displayName: llm-api-gateway
      apiKeyEnv: LLM_API_GATEWAY_API_KEY
      api: openai-completions
      baseURL: http://192.168.5.34:9000/v1
      models:
        - id: deepseek-v4-flash
          name: deepseek-v4-flash
        - id: deepseek-v4-pro
          name: deepseek-v4-pro
agent-default-model:
  provider: llm-api-gateway
  model: deepseek-v4-flash

快速定位法：用 curl 分别测两个端点——

bash

curl -X POST http://192.168.5.34:9000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'
curl -X POST http://192.168.5.34:9000/v1/messages -H "Content-Type: application/json" -d '{"model":"deepseek-v4-flash","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

哪个返回 200，DSH 的 api 就该配哪个协议。

关于“上下文注入”日志的澄清

text

上下文注入 @deepseek-ai/dsh-system-prompt
上下文注入 skill-catalog

这两条是 DSH 组装请求时的正常信息输出，不是错误。DSH 采用分层注入：系统提示 + 技能目录 + 对话历史 + 工具结果。真正导致失败的是紧随其后的状态码。

四、通用排查思路总结

阶段关键动作易踩的坑
环境nvm ls 确认已装版本直接 nvm use 未安装的版本
安装npm i -g 后重开终端用 npx 临时运行后找不到命令
插件只用新包名 dsh-web-all新旧包并存导致 id 重复
构建approve-builds 放行原生模块忽略 pnpm 构建脚本警告
启动回退层删掉重建Windows 软链退化成真实目录
网关baseURL 补全到 /v1少写路径段导致 405
模型去掉不支持的参数reasoning_effort 类能力参数

三条核心原则：

  1. 报错里的路径和 id 就是线索——duplicate loader entry id 就去找哪个包重复，exists and is not a symlink 就去删那个目录，405 就去核对请求路径。
  2. --dump-config 通过不代表能启动——配置校验和运行时 compose 是两条路径。
  3. 协议要对齐——DSH 的 api 字段必须和网关实际提供的协议一致（openai-completions vs Anthropic messages），baseURL 要写到协议端点前缀那一层。

本指南基于 Windows + nvm + Node 22.22.0 + DSH Web profile 的实战环境整理，命令路径以 C:\Users\Lenovo 为例，实际使用请替换为自己的用户目录。

附加说明 deepseek 自定义的提供商配置llm-api-gateway (这个是一个更多功能的版本目前是闭源状态，需要的可以留言） 点击设置 > 打开配置文件（可以修改或者去掉报错的地方）：

image.png

给大家看看我的配置（注意openai的协议后面要加/v1）：

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1
ui-theme:
  preference: light
llm-pi-ai:
  providers:
    {
      llm-api-gateway:
        {
          displayName: llm-api-gateway,
          apiKeyEnv: LLM_API_GATEWAY_API_KEY,
          api: openai-completions,
          baseURL: http://192.168.5.34:9000/v1,
          models:
            [
              { id: deepseek-v4-flash, name: deepseek-v4-flash },
              { id: deepseek-v4-pro, name: deepseek-v4-pro }
            ]
        }
    }
agent-default-model:
  provider: llm-api-gateway
  model: deepseek-v4-flash
pet: {}
skin-custom-theme:
  applied: false

参考文档：

[DeepSeek Harness 保姆级安装与使用教程！](``` www.cnblogs.com/jinjiangong…

avatar
文章
阅读
粉丝