基于一次完整的 Windows 环境安装、插件配置、自定义网关接入的实战记录整理。
一、环境准备阶段
坑 1：Node 版本检查与 nvm 使用
现象：执行 nvm use 22.19.0 报 activation error: Version not installed。
原因：nvm 只能切换到已安装的版本，不会自动下载。
正确做法：
|
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），直接用即可，不必降级。
坑 2：dsh命令找不到
现象：'dsh' 不是内部或外部命令。
原因：只用了 npx @deepseek-ai/dsh web 临时运行，从未全局安装，系统 PATH 里自然没有 dsh。
正确做法：
|
1 |
npm install -g @deepseek-ai/dsh |
安装后必须重开终端窗口，否则 PATH 不会刷新。验证：
|
1 |
dsh --version |
网络慢时可加镜像：
|
1 |
npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com |
二、插件安装阶段
坑 3：装了废弃包，触发重复 loader entry
现象：dsh web 启动报
|
1 |
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。
坑 4：pnpm 拦截原生构建脚本
现象：插件安装报
|
1 |
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: cloudflared, cpu-features, node-pty, ssh2 |
原因：pnpm 10+ 默认拦截需要运行编译脚本的依赖（防止恶意脚本）。这些是 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 |
坑 5：模块回退层的真实目录冲突
现象：
|
1 |
dsh: ....dsh-module-fallback\node_modules\dagre-d3-es exists and is not a symlink or dsh-managed module proxy |
原因：healProfileModuleFallback 要求回退层里的条目必须是符号链接。Windows 下创建软链常需管理员权限，某些操作退化成直接复制真实目录，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 逻辑，路径不同。
三、自定义大模型网关接入
坑 6：reasoning effort 不被支持
现象：
|
1 |
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
现象：网关日志：
|
1 2 |
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：
|
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 分别测两个端点——
|
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"}]}' |
哪个返回 200，DSH 的 api 就该配哪个协议。
关于“上下文注入”日志的澄清
|
1 2 |
上下文注入 @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 是两条路径。
- 协议要对齐——DSH 的 api 字段必须和网关实际提供的协议一致（openai-completions vs Anthropic messages），baseURL 要写到协议端点前缀那一层。
本指南基于 Windows + nvm + Node 22.22.0 + DSH Web profile 的实战环境整理，命令路径以 C:\Users\Lenovo 为例，实际使用请替换为自己的用户目录。
附加说明 deepseek 自定义的提供商配置llm-api-gateway (这个是一个更多功能的版本目前是闭源状态，需要的可以留言） 点击设置 > 打开配置文件（可以修改或者去掉报错的地方）：
给大家看看我的配置（注意openai的协议后面要加/v1）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
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 |
