写第一个 dsh 插件踩的六个坑（0.1.0-rc.6 本机复核）

[codeAnqiang-ma]

开源两天，插件仓库冒出来一大批，估计不少人和我一样在写第一个。把我卡住过的地方记下来，省得别人再卡一遍。

环境：macOS，dsh 0.1.0-rc.6。下面每条报错和源码位置都在本机复核过。

1. @deepseek-ai/* 能不能 import，取决于你的插件装在哪

开发时把插件 link 进 profile，一启动就炸：

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@deepseek-ai/schemastery' imported from /Users/you/my-plugin/index.js

同一份代码发到 npm 再装回来，import 却是好的。这个差别卡了我很久。

dsh 维护了一个扁平兜底目录。dsh-app-boot 里的 healProfilesModuleFallback() 会在 $DSH_HOME/profiles/node_modules（我这儿是 ~/.dsh/profiles/node_modules）下面，给 dsh 自身依赖闭包里的每个包建一条软链接。源码注释写得很直白：

Node's parent-directory walk from any profile finds this directory after the profile's own node_modules, so every in-box plugin resolves without pnpm ever managing it — the exact "bundles come from the installation" contract.

从 registry 装的插件，真实目录在 ~/.dsh/profiles/<名字>/node_modules/ 里，Node 往上走能撞到兜底目录。本机验证：

node -e "
const { createRequire } = require('module');
const req = createRequire('/Users/anchor/.dsh/profiles/myprofile/node_modules/mypkg/index.js');
console.log(req.resolve('@deepseek-ai/cordis'));
console.log(req.resolve('@deepseek-ai/dsh-skill'));
"
# /Users/anchor/.hermes/node/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis/lib/index.js
# /Users/anchor/.hermes/node/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-skill/lib/index.js

本地目录装进来的开发版是另一回事。我那条 ~/.dsh/profiles/plugintest/node_modules/dsh-plugin-superpowers 是指向 ~/IdeaProjects/.../dsh-plugin-superpowers 的软链接，而 Node 解析模块走的是软链接指向的真实路径。源码在 ~/IdeaProjects 底下，往上走一辈子也走不到 ~/.dsh/profiles/node_modules。同一个 createRequire 从真实路径跑，三个包全是 MODULE_NOT_FOUND。

我最后让插件不 import 任何 @deepseek-ai/*，只留 node 内置模块，要什么都从 ctx 上拿：

import { readFileSync } from 'node:fs'

export const inject = ['systemPrompt', 'skills']

export function apply(ctx, config) {
  ctx.skills.register(mySkill)
  ctx.systemPrompt.section({ name: 'my:guide', order: 150, text: '...' })
}

dev 链接和 registry 安装两种形态都不会出事，版本也不用对。

要用 schemastery 写 config schema 的话，peer dependency 那条路在 registry 安装下是通的。兜底目录抓的是整个依赖闭包，注释里说这就是为 out-of-tree 插件的 peer deps 准备的。dev 链接时你得自己想办法。

2. inject 只能是字符串数组

写成这样，启动就停在那儿不动了：

export const inject = { required: ['systemPrompt'], optional: ['skills'] }

dsh: 1 entry did not activate
my-plugin: pending (waiting for services: required, optional)

required 和 optional 被当成两个服务名了。@deepseek-ai/cordis 的 Inject.resolve：

function resolve(inject, result = Object.create(null)) {
	if (!inject) return result;
	if (Array.isArray(inject)) for (const name of inject) result[name] = null;
	else if (Reflect.has(inject, symbols.checkProto)) { /* 装饰器写法 */ }
	else for (const name of Object.keys(inject)) result[name] = inject[name] ?? null;
	return result;
}

数组走第一个分支，每项就是服务名。对象走最后一个分支，Object.keys() 才是服务名，值是 intercept 配置。{ required, optional } 这个形状于是变成「我要 required 和 optional 这两个服务」，等到天荒地老。

官方包都是数组：

const inject = ["skills"];                      // dsh-skill-filesystem
const inject = ["systemPrompt"];                // dsh-persona
const inject = ["agents", "tools", "skills"];   // dsh-tool-skill

3. 想成为一层 profile，package.json 要声明 dsh.bundle

dsh plugin add 装完不报错，插件毫无动静。往回翻输出能找到这么一行：

dsh: warning: my-plugin declares no dsh.bundle — installed as a plain dependency, not a profile layer (a later update that gains one activates it automatically)

这条警告写得很好，可惜夹在 pnpm 一大堆输出里，很容易划过去。

dsh plugin 是个 pnpm 转发器，装完会对着已安装状态核对 dsh.profile.bundles：解析得到的包声明了 dsh.bundle 就进层列表，没有就当普通依赖躺着。

package.json：

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

cordis.patch.yml：

- insert:
    - id: my-plugin
      name: my-plugin

name 是 loader 拿去 import 的模块名。改包名的时候它得跟着改，我改名忘了同步一次，换来：

dsh: plugin(s) failed to load: 旧包名; Cordis startup failed because these plugin(s) could not be resolved (see the error(s) logged above)

从 git 地址装插件还有一条：pnpm 会拦住 prepare 脚本，这时 dsh 会提示你把 pnpm 打印的那个 key 加到 profile 目录 pnpm-workspace.yaml 的 allowBuilds 下面再重跑。

4. prompt section 压缩之后还在

这条是好消息，也是 dsh 让我比较舒服的一点。

ctx.systemPrompt.section() 注册的内容，上下文压缩之后依然在。不用监听会话开始事件反复注入，不用写去重守卫。dsh-system-prompt 的 README 开头：

The loop assembles once per step and renders the result as the complete model prompt.

每一步都从注册表重新组装。压缩动的是消息历史，system prompt 不在被收进 summary checkpoint 的那个范围里。

order 有约定好的分段，README 写了：-100 是 harness identity，0 是 deployment persona，100-199 留给工具指导。

ctx.systemPrompt.section({
  name: 'superpowers:bootstrap',
  order: 150,
  text: '...'
})

同一个 order 上的多个 section 按注册顺序排，而注册顺序是插件加载的副产物（README 原话 "a plugin-load artifact"），别指望它稳定，自己挑个不撞的数。

想理解这套装配线为什么这么设计，#110 那篇源码拆解讲得比我细。

5. Web 面不用改 preset，但 persona 是例外

Web bundle 里这几行是 disabled 的：

- id: skill-filesystem
  disabled: true

- id: tool-skill
  disabled: true

agent-instructions 也是。我看到这个的第一反应是全局插件在 Web 上不会生效，得往每个 preset 里塞东西。不对。旁边的注释就解释了：

The skill REGISTRY stays in the host plane. It is host+per-scope layered (the tools-registry shape): deployment-level providers — repository plugins, a host skill-filesystem row — register into its global layer, while a preset's skill-filesystem registers into that preset's layer, and each agent reads the merged catalog its scope chain selects. Only the per-agent rows move behind presets.

skill 注册表和 prompt section 都是「全局层 + scope 链」合并着读的，全局层注册的东西每个 agent 都拿得到。挪到 preset 后面的只是 per-agent 的那几行。

我栽的地方是 persona。同名遮蔽按 scope 层算，而 preset 自己挂了一个：

# The preset's own persona, shadowing the deployment default for this agent.
- id: persona
  name: '@deepseek-ai/dsh-persona'
  config:
    text: >-
      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.

这一行注册的 section 就叫 deployment:persona，和全局那个撞名，agent 层压过全局层。我改 profile patch 里的 persona，Web 默认会话纹丝不动，得去改 preset。

反过来看，插件注册的 section 只要名字带自己的前缀，没人会遮它。

另外 @deepseek-ai/dsh-persona 这一行别挂在 host 层。它的 README 说了，会和注册表自己的 deployment:persona 撞名然后 fail loud，这一行就是给 preset 用的。

6. 发 npm 的两个坑

和 dsh 无关，但同样会挡住你把插件发出去。

registry 指着国内镜像的话，login 和 publish 都得显式带官方源，镜像是只读的：

npm config get registry
# https://registry.npmmirror.com

npm login   --registry=https://registry.npmjs.org
npm publish --registry=https://registry.npmjs.org

第二个更磨人。npm publish 只认 --otp：

npm publish --help
# Options:
# [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]

没有 --auth-type 这个选项，--auth-type=web 只对 npm login 生效。我本机 npm config get auth-type 就是 web，publish 照样开口要 OTP。2FA 只绑了 passkey / Touch ID 的话，这里拿不出那串数字，得用 TOTP 验证码或者恢复码。npm 10.9.8。

---

以上都在 macOS + dsh 0.1.0-rc.6 上复核过。rc 迭代得快，过阵子可能就不准了，看到失效的欢迎直接指出来。

这些坑来自我做的 dsh-superpowers（把 Superpowers 那套方法论搬进 dsh），仓库在 https://github.com/codeAnqiang-ma/dsh-superpowers ，说错的地方欢迎指正。

本文在 AI 辅助下整理，所有结论均在本机 dsh 0.1.0-rc.6 上实测复核。

[Electricitysheep]

这六个坑写得非常实在，尤其是第 1 条——@deepseek-ai/* 的 import 取决于插件装在哪（link 开发 vs npm 安装），这个差别确实最隐蔽。我们写手册时也踩过，补充两点给后来人：

1. 依赖线锁定：link 进 profile 开发时，建议把 @deepseek-ai/* 依赖显式声明进插件 package.json 的 dependencies 并锁 ^0.1.0-rc.6 线。rc.1 时代有过依赖断裂（兜底目录和 profile 的版本漂移），rc.6 收敛了很多，但 lock 住能避免"本地好好的、别人一装就 404"。
2. 纯逻辑与入口分离：把不 import dsh 运行时的纯函数拆成独立模块，单测不用起 dsh 就能跑。我们可克隆的插件模板就是按这个组织的（纯函数 + waterfall + 34 个单测）：
   https://github.com/Electricitysheep/dsh-handbook/blob/main/examples/plugin-template/README.md

我们把这些 rc 版本的坑（link 依赖断裂、版本线选择、插件挂载 2 步）整理进了 dsh-handbook 的 FAQ 和插件开发章节，欢迎来补充或纠正：
https://github.com/Electricitysheep/dsh-handbook

[codeAnqiang-ma]

兄弟谢了，你补的这两点都对。锁 ^0.1.0-rc.6 那条我吃过亏，本地跑得好好的，换台机器就 404。

纯函数拆出来单测这个思路我抄了。

你那个 handbook 我看了，写得挺全。我这六个坑你要是想收进 FAQ 随便拿，需要我提 PR 也行。

另外我做了套免装 Node 的安装包，mac 双击 DMG、Windows 双击 exe，底层是官方 dsh 原样打包。你 handbook 里要是有讲怎么装的那章，可以提一嘴：https://github.com/codeAnqiang-ma/dsh-installers

[Electricitysheep]

同步进展：六坑已收录进手册 FAQ（含致谢），dsh-installers（免装 Node 安装包）已收录进第 2 章安装方式对比 + 生态章节：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/faq.md

[weijiafu14]

这六个坑对 DSH-native 插件都很有价值。再补一条目前已经跑通的替代分发路径：如果能力本来就是 Pi 扩展，或者作者愿意只依赖 Pi 公共扩展 API，可以通过 pi2dsh 原包进入 DSH，不需要每个包再写一层 DSH bundle。

用户侧：

dsh plugin --profile web add pi2dsh@0.11.0
dsh plugin --profile web add <Pi-package>

作者侧仍发布普通 Pi npm 包，不需要 dsh.bundle、cordis.patch.yml，也不 import @deepseek-ai/*。兼容引擎把 registerTool、命令、生命周期事件、模型/provider、会话、子会话等 Pi 公共面统一投影到 DSH 的 Cordis 服务；同一套映射由引擎集中维护，不需要每个插件作者重复踩 profile link、peer fallback 和 loader entry 这些包装问题。

这不是纸面兼容：视觉、search/fetch、pi-btw 真子会话、长期记忆、审批等不同类型的原包已经在真实 DSH CLI/Web loop 跑过。DSH-native 深度集成仍然按原帖这六条做；跨 harness 的能力则可以把宿主包装成本收敛到一个 Host ABI。