ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 依赖放哪栏:peerDependencies 与 dependencies 的分工

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugin依赖管理peerDependenciespnpm版本兼容
插件装完出现两份实例、类型对不上、链接安装后找不到模块,多数不是版本问题,而是依赖放错了栏。本文讲清三栏分工与链接安装的解析顺序。

插件装上了,工具也能跑,但日志里偶尔出现 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 就找不到」。

  1. 普通导入按 Node 的祖先目录顺序查找,当前目录没有就往上找;
  2. 每一级目录都会参考当时的 peer 声明,更近的物理包优先;
  3. 链接目标本身可以没有 package.json,祖先目录的 peer 仍然生效。

关键不是「有没有 node_modules」,而是「查找路径覆盖到了哪里」。 宿主装在 profile 的依赖树里,你的 checkout 在另一个位置,两者不在同一条祖先链上,找不到是正常的。需要指定路径时,用 require.resolve(name, { paths }),它是原生查询;不要指望普通 import 自动跨越目录。

npm、桌面端与源码启动共用这套规则。 也就是说,本地能跑不代表装进 profile 能跑,反之亦然;两边都要验证。

想确认运行时到底解析到哪一份,别猜,直接问 Node:

bash
node -e "console.log(require.resolve('@deepseek-ai/cordis', { paths: ['./'] }))"

输出的路径如果落在你自己的 node_modules,而不是 profile 的依赖树,就说明多了一份副本——这正是 instanceof 失败的前兆。

一个可参考的 DSH plugin package.json

下面这份 DSH plugin 的 package.json 把三栏的写法放在一起,可以直接对照。

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 依赖,按四步验证,每步都有可观察结果:

  1. pnpm why <包名>:确认只出现一份,出现多份说明有包走了 dependencies;
  2. 启动后看日志:没有 ERR_MODULE_NOT_FOUND,也没有 peer 警告;
  3. 触发一次热重载:行为不变,说明没有因重复实例导致注册失效;
  4. 用链接方式装进一个干净 profile:能加载,说明解析路径覆盖到了。

三类常见错配,对照排查:

现象原因处理
instanceof 失败共享包装了两份移到 peer,删掉多出的副本
安装时提示缺 peer只写了 dev 没写 peer两栏都补,范围保持一致
链接后找不到模块解析路径不覆盖宿主改用 require.resolve 的 paths

最后一条经验:依赖问题不要靠「多装一次」解决。 重复安装只会让第二份更隐蔽;先把归属改对,再谈版本。

依赖准确了,插件的行为才可预测。想看 bundle 的 manifest 怎么写,读 DSH plugin 打包成 bundle;想看从 git 安装的构建授权,读 DSH plugin 发布到 npm;想看版本范围怎么声明,读 插件版本兼容。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

插件里用到的 @deepseek-ai 包,应该放 peerDependencies 还是 dependencies?

需要与宿主共享实例的 dsh 包,同时写进 peerDependencies 与 devDependencies。运行期使用宿主安装的那一份,devDependency 那一份只用于类型检查与独立测试,避免装出第二个实例。

为什么插件装好后会出现两份同一个库,导致 instanceof 判断失败?

这通常是因为 DSH plugin 把该包放进了 dependencies,或者 peer 范围不满足导致 pnpm 另装一份。共享实例的包必须走 peer,让运行期解析到宿主那一份;两份实例会让类身份与单例状态都对不上。

DSH plugin 用链接安装后,为什么找不到宿主已经装好的依赖?

DSH plugin 用链接安装时,checkout 会保留自己的 node_modules,普通导入按 Node 的祖先目录顺序查找 peer 声明。解析路径没覆盖到宿主目录时就会失败;需要显式路径时应使用 require.resolve 的 paths 选项。

一个没有任何宿主依赖的纯 DSH plugin 工具库,也要写 peerDependencies 吗?

不需要,纯 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 开发文档

来源