一、环境准备阶段

环境是地基。地基没打好，后面全是在废墟上盖楼——我盖了一晚上，收获一堆报错截图。

1.1 坑 1：nvm 说“版本没装”

**现象：**我兴冲冲敲下 nvm use 22.19.0，终端回我一句 activation error: Version not installed。那一刻，我和终端相顾无言。

原因：nvm 不是许愿池。它只负责切换到已安装的版本，不会自动下载。想用它，得先把版本装上——就像你让前台开 8 楼的房间，结果你连房卡都没办，人家只能对你露出职业微笑。

正确做法：

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 的名字。

**正确做法：**给它一个正式编制。

装完必须重开终端窗口。Windows 的 PATH 刷新速度，比楼下奶茶店的出餐速度还慢，不重开它根本不认账。验证：

网络慢就挂镜像，老规矩：

二、插件安装阶段

环境阶段勉强通关，我以为噩梦结束了。太天真了，插件阶段正拎着砖头在门口等我。

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 被注册了两次。这就像两个人拿着同一把钥匙开门，锁不报警才怪。

**排查：**去配置文件里看看是不是两个包都在：

看 dependencies 和 dsh.profile.bundles 里是不是两个包都赖着不走。

**解决：**把旧包请出去：

移除后还报重复？再检查 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 终端功能依赖的原生模块，不编译，运行时直接给你表演当场崩溃。

**解决（交互式）：**逐个批准，像给熊孩子逐个签字放行的家长：

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

2.3 坑 5：回退层的目录不是软链

现象：

原因：healProfileModuleFallback 要求回退层里的条目必须是符号链接。但 Windows 下创建软链常需要管理员权限，某些操作就退化成直接复制真实目录——你想走 VIP 通道，最后被塞进了人挤人的地铁。dsh 一看：这不是我的人，拒绝接管。

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

别怕，回退层只是运行时解析缓存，不影响插件本体（插件还在 package.json 和 pnpm store 里）。验证配置是否完好：

注意：--dump-config 能打印 ≠ dsh web 能启动。前者只读配置，相当于体检报告；后者会执行 composeProfile 和 heal 逻辑，相当于直接上手术台。体检合格和手术成功是两码事，这个道理放哪都成立。

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

插件装完了，我以为终于可以安心写代码了。结果网关接入这一段，才是我今晚真正的巅峰。

3.1 坑 6：reasoning effort 不被支持

现象：

**原因：**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：

**快速定位法：**用 curl 分别测两个端点，哪个返回 200，DSH 的 api 就配哪个协议：

实践是检验真理的唯一标准，也是检验 baseURL 的唯一标准。

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

有人看到日志里冒出“上下文注入 @deepseek-ai/dsh-system-prompt”“上下文注入 skill-catalog”就慌了，以为系统在搞什么秘密行动。

别慌。这两条是 DSH 组装请求时的正常信息输出，不是错误。DSH 采用分层注入：系统提示 + 技能目录 + 对话历史 + 工具结果。就像厨房里传来切菜声，那不是火灾，是厨师在正常上班。真正决定成败的是紧随其后的状态码——切菜声后面传来的，才可能是碗摔碎的声音。

四、通用排查思路总结

三条核心原则：

1. 报错里的路径和 id 就是线索——duplicate loader entry id 就去找哪个包重复，exists and is not a symlink 就去删那个目录，405 就去核对请求路径。程序员排障靠的不是第六感，是报错信息本身，报错才是我们唯一的真相来源。
2. --dump-config 通过不代表能启动——配置校验和运行时 compose 是两条路径。体检报告合格 ≠ 手术成功，这条在坑 5 已经实测验证过了。
3. 协议要对齐——DSH 的 api 字段必须和网关实际提供的协议一致（openai-completions vs Anthropic messages），baseURL 要写到协议端点前缀那一层。协议不对，其他全对也没用，就像你对着苹果手机喊小爱同学。

最后附上我的完整配置，注意 openai 的协议后面一定要加 /v1：

本指南基于 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