DSH 插件(八):9 个插件的发布与安装踩坑
发布 dsh-plugin-session-export@1.0.1 那天,清单仓库的 README 在同一轮对话里改了两遍:
35bd265:把“未发布”改成1.0.0;a9e7c20:把1.0.0改成1.0.1。
原因很简单:README 里硬编码了版本号。插件发一次版,清单就要跟着改一次;9 个插件就是 9 份需要同步的文档。
这篇讲这套插件怎么发布、怎么安装,以及几个只有真正装过才会遇到的坑。
一、三种安装方式
| 方式 | 命令 | 适合 | 代价 |
|---|---|---|---|
| npm | dsh plugin --profile web add dsh-plugin-xxx | 普通用户 | 需要已发布 |
| GitHub | ... add github:owner/repo#v1.0.0 | 未发 npm,或想固定版本 | 需要该 tag 存在 |
| 本地 | ... add link:. | 开发调试 | 目录不能删、不能移动 |
安装完都要做同一件事:
dsh --profile web --dump-config输出里要同时出现插件 id 和 bundle 标记。只看到包名、没有 # == dsh-plugin-xxx,说明 patch 没应用,通常是 dsh.bundle.patch 路径写错或文件没打进包里。
然后重启 profile。插件不是热加载的,add 只改依赖和配置,运行中的进程不会重新组合 bundle。
二、坑一:tag 和 package.json 版本会漂
这是最隐蔽的一类。session-export 的 package.json 是 1.0.1,但仓库里最新的 git tag 停在 v0.2.0。
如果安装命令写:
dsh plugin --profile web add github:zhaoxuejie/dsh-plugin-session-export#v1.0.1会直接失败,因为 v1.0.1 这个 ref 不存在。用户看到的是“安装失败”,不会想到是 tag 没打。
npm version 默认会同时改 package.json、提交并打 tag;但如果版本号是手改的,或者发布时用了 --no-git-tag-version,两边就会分叉。session-export 就是后一种情况。
现在的做法是:
- 能发 npm 就优先发 npm,安装命令不写版本;
- 必须从 Git 装时,固定到 commit SHA,不依赖 tag;
- 发版后在清单里只写“已发布 / 未发布”,不写具体版本号。
最后一条就是那两次 README 回改的直接教训。
三、坑二:pnpm 10 默认不执行 git 依赖的构建
9 个插件分两类:
- 零构建:源码就是运行文件,
main指向src/index.mjs,没有prepare; - 要编译:TypeScript 源码,
prepare里跑tsc,安装时生成lib/。
从 GitHub 安装第二类时,pnpm 10 默认拒绝执行依赖的 prepare 脚本,首次安装会失败。需要在 profile 的 pnpm-workspace.yaml 里显式允许:
allowBuilds:
dsh-plugin-feihualing: true这是个安全开关,不是 bug:允许构建等于允许在你机器上执行这个包的代码。所以只对信任的仓库开启,并且优先固定 commit:
dsh plugin --profile web add github:zhaoxuejie/dsh-plugin-feihualing#<sha>固定 SHA 还有一个好处:上游 force push 或删 tag,你的安装不会突然失效。
四、坑三:npm 包能装,但插件不生效
files 字段决定哪些文件进 tarball。漏一个,包能装、require 也不报错,但宿主加载时找不到入口。
三个必须进包的文件:
| 文件 | 漏了会怎样 |
|---|---|
lib/ 或 src/ | 入口不存在,加载即失败 |
cordis.patch.yml | 包装上了,但没挂进配置树 |
| client 入口(如有) | Node 侧正常,浏览器面板空白 |
发布前用 npm pack --dry-run 看文件清单,比装完再排查快得多。特别是编译型插件,files 里写 src 却没写 lib,本地开发一切正常,发布后必坏。
exports 也要对得上。dsh.client 指向 ./client,exports 里就必须有 "./client";少这一条,Node 侧能加载,浏览器侧解析不到。
五、坑四:link 安装不是复制
link:. 在 Windows 上建的是目录联接,profile 直接读当前源码目录。
三个后果:
- 改源码立即生效,但必须重启
dsh web; - 删掉或移动源码目录,profile 立即坏掉;
- 用
link:装的插件不会进node_modules的常规副本,清理依赖时容易被误删。
只想本地试用、不打算长期开发,用 file:. 装一份独立副本更稳。
六、发版前检查清单
| 检查 | 命令 / 位置 | 通过标准 |
|---|---|---|
| 版本号 | package.json | 与本次改动匹配,未被占用 |
| tag | git tag | 与版本一致,或明确不使用 tag 安装 |
| 构建 | pnpm run build | 无报错,lib/ 已生成 |
| 打包内容 | npm pack --dry-run | 入口、patch、client 都在 |
| 安装 | 干净 profile | add 成功 |
| 挂载 | dsh --profile web --dump-config | 出现插件 id 与 # == 标记 |
| 运行 | 重启后实际调用 | 工具可见、面板可开、无控制台报错 |
| 卸载 | remove 后重启 | 路由、定时器、DOM 都不残留 |
这份清单目前是手动的。RFC-001 想把清单元数据上移到每个插件的 package.json,用 GitHub Actions 自动聚合 README,做到“新增插件不用打开清单仓库”。
那个方案还是草案,没有落地。 现在仍然是手改 README 的 4 个位置:总览表、详解小节、目录、相关项目。写这篇的时候,我刻意没有把它描述成“已实现”,因为设计文档和运行中的系统是两件事。
七、这一系列到此为止
9 个插件,9 篇文章,从工具拦截到游戏,实际上只讲了三件事:
- 插件是旁路:不改宿主业务,只挂契约;
- 失败要选边:守卫失败关闭,通知失败开放;
- 能确定的不交给模型:路径、引用、判定、格式,全部用代码算。
这套插件现在还不算什么:没有统一 UI,没有插件间编排,也不能替代真正的工作流系统。它的价值在于把“在别人的 Agent 运行时里加一层”这件事拆开给你看——哪些位置能加、加了之后怎么卸、卸不干净会留下什么。
如果只记一句:先想清楚失败的那一侧代价更小,再决定代码怎么写。