DeepSeek Harness 插件安装错误排查
一份 DeepSeek Harness 插件安装失败排障表：pnpm 找不到、allowBuilds 拦截、缺失 lib/ 构建产物，教你分辨到底碰到了哪一种。
dsh plugin add 的失败大多落在三类里:pnpm 不可达、GitHub 来源的插件需要一个你还没放行的构建权限,或者插件的构建没有产出 dsh 期望加载的东西。本文逐一讲清楚,给出该找的确切症状和对应修法。
为什么插件安装会以可预测的方式失败
dsh plugin --profile <name> <参数...> 会把 profile 参数之后的所有内容原样转发给 pnpm,并在该 profile 目录内执行。正因如此,几乎每一个安装失败本质上都是一个套着 dsh 命令外壳的 pnpm 失败——这其实是好消息,意味着这些错误是一致的、被充分理解的,而不是 dsh 专属的谜题。
错误 1:"command not found: pnpm"
症状:dsh plugin --profile web add <包名> 在任何包解析开始之前就立即失败,通常报的是 shell 层面的"command not found"或类似错误。
原因:dsh plugin 会直接调用 pnpm。如果 pnpm 没有安装或不在你的 PATH 里,它就没有可以转发的对象。
修复:安装 pnpm,并确认它能从你的 shell 里被解析到(pnpm --version)。如果你是通过某个同时用 Corepack 管理 pnpm 的包管理器装的 dsh,确认 Corepack 本身是开启的。
错误 2:allowBuilds 拦截
症状:dsh plugin add github:owner/repo 调用失败,pnpm 拒绝运行一个构建/prepare 脚本,并建议你添加一条 allowBuilds 条目。
原因:pnpm 10 及以上版本默认拦截 git 依赖上的 prepare 脚本执行。GitHub 安装拉取的是源码而非构建产物——如果插件是 TypeScript 写的、且没有直接提交 lib/ 目录,它就需要那个 prepare 脚本先跑起来 dsh 才能加载,而 pnpm 没有明确许可就不会运行它。
修复:在该 profile 的 pnpm-workspace.yaml 里把这个包加进 allowBuilds:
allowBuilds:
dsh-hello-plugin: true
只对你审查过或信任的源码这么做,并把安装锁定到某个 commit(github:owner/repo#<sha>)——这样做等于授予该包在安装期于你机器上执行任意代码的权限,且脱离 dsh 运行时后续会施加的任何沙箱。我们的 GitHub 安装指南完整讲解了这个提示,安全清单讲了放行前该看什么。
错误 3:GitHub 安装后提示"Cannot find module"
症状:add 命令本身看起来成功了(可能是在你放行了 allowBuilds 之后),但这个 profile 下次启动时插件加载失败,报了一个模块解析错误。
原因:几乎总是以下两种情况之一——要么构建步骤根本没跑起来(检查这个包在 package.json 里到底有没有声明 prepare 脚本,以及构建权限是否放行给了正确的包名),要么这个仓库本身确实没有产出 dsh 期望的产物(这是插件本身的编写缺口,不是安装侧能修的)。
修复:确认构建确实跑了——检查 node_modules 里已安装的包内,是否真的存在一个 lib/(或者 package.json 里 main 指向的任何目录)。如果它缺失,又没有 prepare 脚本去生成它,说明这个插件没有为 GitHub 安装正确打包——去找有没有已发布到 npm 的替代版本,或者查一下插件的 issue/discussion 追踪。
错误 4:本地路径安装解析到了错误的目录
症状:dsh plugin --profile demo add ./hello-plugin 报路径解析错误,或者更让人困惑的是——命令成功了,但装的不是你想要的那个插件。
原因:本地相对路径是以你执行 add 命令时所在的目录为锚点解析的,而不是以 profile 自己的目录为锚点。如果你在家目录下执行命令,而插件文件夹是相对于三层之下的某个项目目录来写的,pnpm 会以你 shell 当前所在的位置去解析这个路径,而不是任何 dsh 专属的位置。
修复:要么先 cd 到相对路径本应相对的那个目录再执行 add,要么直接用绝对路径消除歧义:
dsh plugin --profile demo add /Users/you/projects/hello-plugin
同一类错误也适用于 tarball 安装(dsh plugin --profile demo add ./hello-plugin-0.1.0.tgz)——tarball 路径的解析方式是一样的。
快速诊断表
| 症状 | 最可能的原因 | 该去哪里看 |
|---|---|---|
| 任何包解析开始之前就失败 | pnpm 不在 PATH 里 | 在你的 shell 里执行 pnpm --version |
| 安装拒绝运行构建脚本 | 未放行 allowBuilds(pnpm 10+ 默认拦截) | Profile 目录下的 pnpm-workspace.yaml |
| 安装成功,插件启动时失败 | 缺失构建产物(lib/) | Profile 内的 node_modules/<package> |
| 安装成功,dsh 打印警告但什么也没发生 | 包的 package.json 里没有 dsh 字段 | 该包自己的 package.json——见我们的插件发现指南 |
| 本地路径安装找不到你的插件 | 相对路径从错误的目录解析 | 本地路径是相对于你当前 shell 所在目录解析的,不是 profile 目录 |
值得知道的一个"非错误":静默的无效安装
如果 dsh plugin add 没有报错就完成了,但这个插件看起来什么都没做,检查一下这个包的 package.json 里到底有没有声明 dsh.bundle 或 dsh.profile 字段。没有这个字段的包,依然会作为一个普通依赖被顺利装进去——pnpm 没有理由失败——但 dsh 会打印一条警告,不会激活它的任何配置。这不是 bug;这正是 dsh 用来区分"真实插件"和"插件可能依赖的普通库"的方式。安装前如何验证这一点,见如何寻找 DeepSeek Harness 插件。
社区诊断工具
生态里有一小批社区插件,专门用来在这些问题发生之前或之后把它们捕捉出来。dsh-plugin-check 会针对已安装插件的 manifest 协议、patch 格式和已知的构建陷阱运行健康检查。dsh-doctor 是一个专门针对这类安装问题的诊断、修复、回滚插件。这些都是普通的第三方 dsh 插件——不是 dsh 本身的一部分,我们也没有独立核实过它们——在依赖它们之前,请以我们安全清单里讲到的同等审慎程度去安装它们。
确认修复生效
解决任何安装错误之后,运行:
dsh --profile web --dump-config
这会打印完整组合后的配置,精确显示哪些 bundle 补丁当前生效。这是确认一个插件真的进入了运行中的配置、而不只是静静躺在 node_modules 里没被解析的最可靠方法。
FAQ
为什么同一个插件从 npm 装没问题,从 GitHub 装就失败？
npm 发布的插件自带构建产物,所以没有构建步骤,也没有 allowBuilds 提示。同一个插件的 GitHub 版本是源码,需要一个 prepare 脚本先跑起来——而这正是 pnpm 10+ 默认拦截的那一步。
安装前能不能提前判断一个插件会不会需要 allowBuilds？
看这个仓库的 package.json 里有没有 scripts.prepare 条目,再看仓库里有没有直接提交 lib/(或等价的)目录。如果有 prepare 脚本、又没有预构建产物,就该预期会碰到这个提示。
我放行了 allowBuilds,安装还是失败,现在怎么办？
去看实际的构建错误输出,而不只是权限提示。一个被放行的构建依然可能因为自身的问题失败——缺构建工具链、Node 版本不匹配,或者插件自己的构建脚本本身就是坏的。
dsh 对插件安装有自己的一套错误码吗？
没有——因为 dsh plugin 是转发给 pnpm 的,你看到的错误就是 pnpm 自己的错误输出。安装这一步没有单独的 dsh 专属错误分类体系。
如果我碰到的错误都不在这几种里怎么办？
这三类专门覆盖了绝大多数安装期失败。对于更广泛的环境和运行时问题(Node 版本不匹配、平台特定的 bug、会话错误),见我们的12 个常见错误排障指南。
下一步
想了解 GitHub 安装和 allowBuilds 决策的完整全貌,读从 GitHub 安装插件。对于插件运行起来之后而非安装期出现的错误,见DeepSeek Harness 排障。在给任何你没审查过的东西放行构建权限之前,先过一遍插件安全清单。