先说结论：这不是教程，这是事故现场实录。我在 Windows 上折腾 DeepSeek Harness（后面统一叫 DSH），原计划一小时收工，结果把一晚上过成了连续剧——每当我以为要大结局，下一集就给我来个反转。
全文短段落、口语化、多级编号，代码原样保留。看完你能少踩 7 个坑，这买卖稳赚不赔。
一、环境准备阶段
环境是地基。地基没打好，后面全是在废墟上盖楼——我盖了一晚上，收获一堆报错截图。
1.1 坑 1：nvm 说“版本没装”
**现象：**我兴冲冲敲下 nvm use 22.19.0，终端回我一句 activation error: Version not installed。那一刻，我和终端相顾无言。
原因：nvm 不是许愿池。它只负责切换到已安装的版本，不会自动下载。想用它，得先把版本装上——就像你让前台开 8 楼的房间，结果你连房卡都没办，人家只能对你露出职业微笑。
正确做法：
|
1 2 3 |
nvm ls # 先看已安装了哪些版本 nvm install 22.19.0 # 需要哪个版本，先装上 nvm use 22.19.0 |
DSH 要求 Node 22.19.0+ 或 24.0.0+。如果你机器上已经有更高版本（比如 22.22.0），直接用就行，别降级。降级这件事，99% 的时候是自己给自己挖坑，剩下 1% 是给别人挖。
1.2 坑 2：dsh 命令找不到
现象：'dsh' 不是内部或外部命令。翻译成人话：系统把 PATH 翻了个底朝天，没找到你。这感觉就像你喊了一个人的名字，结果发现对方根本没加你好友。
**原因：**我之前只用了 npx @deepseek-ai/dsh web 临时跑一下。npx 是临时演员，演完就卸妆走人，从没全局安装过，PATH 里当然没有 dsh 的名字。
**正确做法：**给它一个正式编制。
|
1 |
npm install -g @deepseek-ai/dsh |
装完必须重开终端窗口。Windows 的 PATH 刷新速度，比楼下奶茶店的出餐速度还慢，不重开它根本不认账。验证：
|
1 |
dsh --version |
网络慢就挂镜像，老规矩：
|
1 |
npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com |
二、插件安装阶段
环境阶段勉强通关，我以为噩梦结束了。太天真了，插件阶段正拎着砖头在门口等我。
2.1 坑 3：新包旧包一起装，ID 打架
现象：dsh web 一启动就报 duplicate loader entry id: web-ui-compat。
原因：package.json 里同时躺着旧包 @linxin666/dsh-web-ui-all 和新包 @linxin666/dsh-web-all，俩包都带 compat 桥接层，同一个 id 被注册了两次。这就像两个人拿着同一把钥匙开门，锁不报警才怪。
**排查：**去配置文件里看看是不是两个包都在：
|
1 |
type C:\Users\Lenovo\.dsh\profiles\web\package.json |
看 dependencies 和 dsh.profile.bundles 里是不是两个包都赖着不走。
**解决：**把旧包请出去：
|
1 |
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。旧包就像前任，留着只会给新生活添堵。
2.2 坑 4：pnpm 拦路打劫
**现象：**插件安装时报 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: cloudflared, cpu-features, node-pty, ssh2。
**原因：**pnpm 10+ 默认拦截需要运行编译脚本的依赖，官方理由是防恶意脚本。它确实防住了恶意脚本，也顺便防住了我的终端。cloudflared 这些是 DSH 终端功能依赖的原生模块，不编译，运行时直接给你表演当场崩溃。
**解决（交互式）：**逐个批准，像给熊孩子逐个签字放行的家长：
|
1 |
dsh plugin --profile web approve-builds |
**解决（非交互式）：**编辑 C:\Users\Lenovo\.dsh\profiles\web\pnpm-workspace.yaml，手动放行：
|
1 2 3 4 5 |
allowBuilds: cloudflared@0.7.3: true cpu-features@0.0.10: true node-pty@1.1.0: true ssh2@1.17.0: true |
2.3 坑 5：回退层的目录不是软链
现象：
|
1 |
dsh: ....dsh-module-fallback\node_modules\dagre-d3-es exists and is not a symlink or dsh-managed module proxy |
原因：healProfileModuleFallback 要求回退层里的条目必须是符号链接。但 Windows 下创建软链常需要管理员权限，某些操作就退化成直接复制真实目录——你想走 VIP 通道，最后被塞进了人挤人的地铁。dsh 一看：这不是我的人，拒绝接管。
**解决：**删掉不合规的目录，或者干脆把整个回退层删了让它重建：
|
1 |
rmdir /s /q "C:\Users\Lenovo\.dsh\profiles\web\.dsh-module-fallback" |
别怕，回退层只是运行时解析缓存，不影响插件本体（插件还在 package.json 和 pnpm store 里）。验证配置是否完好：
|
1 |
dsh --profile web --dump-config |
注意：--dump-config 能打印 ≠ dsh web 能启动。前者只读配置，相当于体检报告；后者会执行 composeProfile 和 heal 逻辑，相当于直接上手术台。体检合格和手术成功是两码事，这个道理放哪都成立。
三、自定义大模型网关接入
插件装完了，我以为终于可以安心写代码了。结果网关接入这一段，才是我今晚真正的巅峰。
3.1 坑 6：reasoning effort 不被支持
现象：
|
1 |
provider "llm-api-gateway" model "deepseek-v4-flash" does not support reasoning effort "low" |
**原因：**DSH 默认可能给请求带上 reasoning_effort 参数，但你的模型/网关不支持。你点了一道菜单上没有的菜，人家只能礼貌地说：不好意思，后厨没这个食材。
**解决：**在 provider 配置里把 reasoning effort 相关设置去掉。
3.2 坑 7：405——baseURL 少了 /v1
**现象：**网关日志里，Anthropic 端点岁月静好（POST /v1/messages HTTP/1.1 200 OK），DSH 的请求却一路打到 405（POST /chat/completions HTTP/1.1 405 Method Not Allowed）。
**原因：**DSH 配的是 api: openai-completions，它会往 baseURL 后面拼 /chat/completions。如果 baseURL 只写到 http://192.168.5.34:9000，实际请求就变成 /chat/completions；而网关的 OpenAI 兼容端点挂在 /v1/chat/completions。少写一个 /v1，就像订酒店只报了楼层没报房号，前台看你的眼神都开始不对劲了。
**解决：**baseURL 补全到 /v1：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
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 分别测两个端点，哪个返回 200，DSH 的 api 就配哪个协议：
|
1 2 |
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"}]}' |
实践是检验真理的唯一标准，也是检验 baseURL 的唯一标准。
3.3 关于“上下文注入”日志的澄清
有人看到日志里冒出“上下文注入 @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 类能力参数 |
三条核心原则：
- 报错里的路径和 id 就是线索——duplicate loader entry id 就去找哪个包重复，exists and is not a symlink 就去删那个目录，405 就去核对请求路径。程序员排障靠的不是第六感，是报错信息本身，报错才是我们唯一的真相来源。
- --dump-config 通过不代表能启动——配置校验和运行时 compose 是两条路径。体检报告合格 ≠ 手术成功，这条在坑 5 已经实测验证过了。
- 协议要对齐——DSH 的 api 字段必须和网关实际提供的协议一致（openai-completions vs Anthropic messages），baseURL 要写到协议端点前缀那一层。协议不对，其他全对也没用，就像你对着苹果手机喊小爱同学。
最后附上我的完整配置，注意 openai 的协议后面一定要加 /v1：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
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 |
本指南基于 Windows + nvm + Node 22.22.0 + DSH Web profile 的实战环境整理，命令路径以 C:\Users\Lenovo 为例，实际使用请换成自己的用户目录。另外，deepseek 自定义的提供商配置 llm-api-gateway 是功能更全的版本，目前闭源，需要的可以留言。
P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/qq_34419312
