DSH plugin 依赖放哪栏:peerDependencies 与 dependencies 的分工
插件装上了,工具也能跑,但日志里偶尔出现 instanceof 判断失败;或者编辑器里类型正常,运行时却报方法不存在。这类问题很少是版本写错,更多是依赖放错了栏。
DSH plugin 依赖错位的三个症状,同一个根因
症状一,两份实例。 你的插件 import { Service } from '@deepseek-ai/cordis',宿主也有一份。两份不是同一个函数,instanceof 永远返回 false,服务注册看起来成功、实际不被识别。
症状二,类型对不上。 编辑器用你 node_modules 里的类型,运行期用宿主那一份,版本差一点就会「编译通过、运行时没有这个方法」。
症状三,链接安装后模块找不到。 本地 checkout 装进 profile,代码里 import 一个宿主已有的包,运行时报 ERR_MODULE_NOT_FOUND。
三个症状的共同点:依赖的归属与解析路径没对齐。 前者决定用谁的副本,后者决定能不能找到。
DSH plugin 依赖三栏的分工
DSH plugin 依赖三栏的分工只看一件事:这个包要不要和宿主共享同一个运行实例。
| 字段 | 回答什么 | 典型对象 |
|---|---|---|
peerDependencies | 期望宿主提供哪一份 | @deepseek-ai/* 运行时包 |
devDependencies | 开发与测试时需要什么 | 同一批 peer 包的本地副本 |
dependencies | 我自带哪一份 | 需要独立版本的第三方库、无状态工具包 |
判断标准只有一句:这个包需要和宿主共享同一个运行实例吗? 需要,写 peer;不需要,写 dependencies;只用于编译和测试的副本,写 dev。放错栏不会立刻报错,它会在热重载、双入口、链接安装这些场景才暴露。
为什么 dsh 包要同时写两栏
这是 DSH plugin 依赖规则里最反直觉的一条:同一个包,同时出现在 peerDependencies 与 devDependencies。
- 运行期:Harness 的运行时解析已把宿主那份纳入查找范围,于是用宿主副本,不重复加载;
- 开发期:
devDependencies给你一份本地副本,类型检查、单测、独立示例才能跑起来。
只写 peer 会怎样? 本地开发时编辑器找不到类型,测试跑不起来;发布后 pnpm 还会提示缺少 peer。只写 dependencies 会怎样? 运行期可能装出第二份,症状一就出现了。peer 范围要写宽一点,过窄的范围会在宿主升级小版本时把插件挡在 engines.dsh 检查之外,表现是安装或启动被拒绝。
DSH plugin 链接安装时的解析顺序
DSH plugin 的本地 checkout 装进 profile 时,会保留自己的 node_modules。 这解释了「为什么在示例目录里能跑,装进 profile 就找不到」。
- 普通导入按 Node 的祖先目录顺序查找,当前目录没有就往上找;
- 每一级目录都会参考当时的 peer 声明,更近的物理包优先;
- 链接目标本身可以没有
package.json,祖先目录的 peer 仍然生效。
关键不是「有没有 node_modules」,而是「查找路径覆盖到了哪里」。 宿主装在 profile 的依赖树里,你的 checkout 在另一个位置,两者不在同一条祖先链上,找不到是正常的。需要指定路径时,用 require.resolve(name, { paths }),它是原生查询;不要指望普通 import 自动跨越目录。
npm、桌面端与源码启动共用这套规则。 也就是说,本地能跑不代表装进 profile 能跑,反之亦然;两边都要验证。
想确认运行时到底解析到哪一份,别猜,直接问 Node:
node -e "console.log(require.resolve('@deepseek-ai/cordis', { paths: ['./'] }))"
输出的路径如果落在你自己的 node_modules,而不是 profile 的依赖树,就说明多了一份副本——这正是 instanceof 失败的前兆。
一个可参考的 DSH plugin package.json
下面这份 DSH plugin 的 package.json 把三栏的写法放在一起,可以直接对照。
{
"name": "dsh-my-plugin",
"type": "module",
"main": "index.js",
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
"engines": { "dsh": ">=0.2.0 <0.3.0" },
"peerDependencies": {
"@deepseek-ai/cordis": ">=0.2.0 <0.3.0",
"@deepseek-ai/dsh-tools": ">=0.2.0 <0.3.0"
},
"devDependencies": {
"@deepseek-ai/cordis": "^0.2.0",
"@deepseek-ai/dsh-tools": "^0.2.0"
},
"dependencies": { "undici": "^6.0.0" }
}
三个观察点: undici 放在 dependencies,因为它是普通第三方库,需要自己的版本;两个 dsh 包放在 peer 与 dev 两栏,范围写法一致;engines.dsh 单独声明,安装与启动时按它检查运行时版本。
别把 typescript 放进 dependencies。 它会跟着包一起发给用户,除非你的插件真的在运行期编译代码。
DSH plugin 依赖自检与常见错配
改完 DSH plugin 依赖,按四步验证,每步都有可观察结果:
pnpm why <包名>:确认只出现一份,出现多份说明有包走了 dependencies;- 启动后看日志:没有
ERR_MODULE_NOT_FOUND,也没有 peer 警告; - 触发一次热重载:行为不变,说明没有因重复实例导致注册失效;
- 用链接方式装进一个干净 profile:能加载,说明解析路径覆盖到了。
三类常见错配,对照排查:
| 现象 | 原因 | 处理 |
|---|---|---|
instanceof 失败 | 共享包装了两份 | 移到 peer,删掉多出的副本 |
| 安装时提示缺 peer | 只写了 dev 没写 peer | 两栏都补,范围保持一致 |
| 链接后找不到模块 | 解析路径不覆盖宿主 | 改用 require.resolve 的 paths |
最后一条经验:依赖问题不要靠「多装一次」解决。 重复安装只会让第二份更隐蔽;先把归属改对,再谈版本。
依赖准确了,插件的行为才可预测。想看 bundle 的 manifest 怎么写,读 DSH plugin 打包成 bundle;想看从 git 安装的构建授权,读 DSH plugin 发布到 npm;想看版本范围怎么声明,读 插件版本兼容。
常见问题
需要与宿主共享实例的 dsh 包,同时写进 peerDependencies 与 devDependencies。运行期使用宿主安装的那一份,devDependency 那一份只用于类型检查与独立测试,避免装出第二个实例。
这通常是因为 DSH plugin 把该包放进了 dependencies,或者 peer 范围不满足导致 pnpm 另装一份。共享实例的包必须走 peer,让运行期解析到宿主那一份;两份实例会让类身份与单例状态都对不上。
DSH plugin 用链接安装时,checkout 会保留自己的 node_modules,普通导入按 Node 的祖先目录顺序查找 peer 声明。解析路径没覆盖到宿主目录时就会失败;需要显式路径时应使用 require.resolve 的 paths 选项。
不需要,纯 DSH plugin 工具库不必写 peerDependencies。无状态的 dsh 工具包按普通依赖处理,放进 dependencies 即可;只有当这个包需要与宿主共享同一份运行实例时,peer 才是必需的。
相关术语
- peerDependencies
- peerDependencies 是声明插件期望由宿主提供的依赖的字段,运行期解析到宿主那份实例,避免重复安装与状态分裂。— DeepSeek Harness 开发文档
- devDependencies
- devDependencies 是只在开发与测试时安装的依赖,用来做类型检查与独立运行测试,不进入运行期解析。— DeepSeek Harness 开发文档
- 链接安装
- 链接安装是把本地 checkout 以 link 形式装进 profile,目标保留自己的 node_modules,模块解析仍按祖先目录规则进行。— DeepSeek Harness 开发文档
- 运行时解析
- 运行时解析是 Harness 在启动 profile 时确定依赖实际指向哪一份副本的规则,npm、桌面端与源码启动共用同一套。— DeepSeek Harness 开发文档
来源
- DeepSeek Harness 开发文档:打包与安装插件· deepseek-harness
- dsh CLI README· deepseek-ai
- deepseek-harness 仓库· deepseek-ai