实战避坑：这些报错到底什么意思

下面每一条都来自真实排查，不是从文档里抄的。遇到同名报错可以直接对号。

版本错配：插件全都消失了

症状：升级 dsh 主程序后重启，界面里一堆功能消失，某些端口不监听。

原因：profile 目录里 node_modules/@deepseek-ai/dsh-* 还是旧版本，而主程序已经是新版本。内核会按版本检查插件，版本对不上就整批跳过。

确认办法：

dsh --version                                  # 主程序版本
cat ~/.dsh/profiles/web/package.json | grep dsh-   # profile 里的版本范围

处理：让 profile 内的包版本与主程序一致，并在 package.json 里用 overrides 锁死，否则下次安装又会回退。

实测案例：从 0.2.0-rc.2 升到 0.2.1-rc.2 时，如果不处理，会有十来个核心插件被静默禁用——界面看起来「没坏」，只是功能没了，很难第一时间发现。

配置补丁 cordis.patch.yml 里，一个 bundle 往往往配置里插好几行。以浏览器相关的能力为例，至少涉及四行：惰性根行、浏览器提供者、Electron 提供者、以及真正注册工具的那一行。

要让出某个工具名，必须禁注册工具的那一行，禁掉根行没有任何效果。写补丁后先看合成结果：

dsh --profile web --dump-config | grep -A3 插件名

cordis.patch.yml 里写的 name 表示「目标当前必须叫这个名字」，不匹配就整条跳过。想改名不是在这里改。补丁静默不生效，九成是名字对不上。

在开启了 skills 权限的 profile 里执行 dsh plugin add 会中断，node_modules 已经更新但 package.json 没写版本范围。

后果：这次能用，下次 install 就回退成旧版本。处理：手动把版本范围补进 package.json。

典型报错长得像 xxx is not a function，而且只在特定操作下出现。

原因：内核重构把某个导出从一个包搬到了另一个包，插件还在从旧包解构，拿到 undefined。之所以是「有时」，是因为代码里往往有短路判断，只有走到那一步才炸。

处理：找插件源码里那行 import，改成兼容写法（先试新包、回退旧包）。这类修改会被插件升级覆盖，升级后要重做。

桌面版的插件安装走应用内管理器，只接受 npm 已发布包。github:user/repo 这种源、以及额外的 pnpm 参数，在桌面端都不生效——命令行也会被拒绝，因为 profile 被应用独占。

结论：想用 GitHub 直装的插件，去网页版或 CLI。

有些插件（导出 PDF、页面截图一类）依赖本机 Chrome/Chromium。纯服务器环境没有浏览器，调用就报 ..._BROWSER_UNAVAILABLE。

处理：要么装无头浏览器，要么把这类工具从注册表里摘掉。摘掉的方式是注释插件里注册该工具的那几行，注意升级会覆盖。

DSH 生态还很年轻，插件的兼容性窗口大概就是「最近一两个内核版本」。装插件前看三件事：最近提交时间、有没有针对新版本的 issue、README 里写的适配版本。三项都旧，就别装了。