Skip to content

DSH 插件(八):9 个插件的发布与安装踩坑 ​

发布 dsh-plugin-session-export@1.0.1 那天,清单仓库的 README 在同一轮对话里改了两遍:

  • 35bd265:把“未发布”改成 1.0.0;
  • a9e7c20:把 1.0.0 改成 1.0.1。

原因很简单:README 里硬编码了版本号。插件发一次版,清单就要跟着改一次;9 个插件就是 9 份需要同步的文档。

这篇讲这套插件怎么发布、怎么安装,以及几个只有真正装过才会遇到的坑。

一、三种安装方式 ​

方式命令适合代价
npmdsh plugin --profile web add dsh-plugin-xxx普通用户需要已发布
GitHub... add github:owner/repo#v1.0.0未发 npm,或想固定版本需要该 tag 存在
本地... add link:.开发调试目录不能删、不能移动

安装完都要做同一件事:

bash
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。

如果安装命令写:

bash
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 里显式允许:

yaml
allowBuilds:
  dsh-plugin-feihualing: true

这是个安全开关,不是 bug:允许构建等于允许在你机器上执行这个包的代码。所以只对信任的仓库开启,并且优先固定 commit:

bash
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:. 在 Windows 上建的是目录联接,profile 直接读当前源码目录。

三个后果:

  1. 改源码立即生效,但必须重启 dsh web;
  2. 删掉或移动源码目录,profile 立即坏掉;
  3. 用 link: 装的插件不会进 node_modules 的常规副本,清理依赖时容易被误删。

只想本地试用、不打算长期开发,用 file:. 装一份独立副本更稳。

六、发版前检查清单 ​

检查命令 / 位置通过标准
版本号package.json与本次改动匹配,未被占用
taggit tag与版本一致,或明确不使用 tag 安装
构建pnpm run build无报错,lib/ 已生成
打包内容npm pack --dry-run入口、patch、client 都在
安装干净 profileadd 成功
挂载dsh --profile web --dump-config出现插件 id 与 # == 标记
运行重启后实际调用工具可见、面板可开、无控制台报错
卸载remove 后重启路由、定时器、DOM 都不残留

这份清单目前是手动的。RFC-001 想把清单元数据上移到每个插件的 package.json,用 GitHub Actions 自动聚合 README,做到“新增插件不用打开清单仓库”。

那个方案还是草案,没有落地。 现在仍然是手改 README 的 4 个位置:总览表、详解小节、目录、相关项目。写这篇的时候,我刻意没有把它描述成“已实现”,因为设计文档和运行中的系统是两件事。

七、这一系列到此为止 ​

9 个插件,9 篇文章,从工具拦截到游戏,实际上只讲了三件事:

  1. 插件是旁路:不改宿主业务,只挂契约;
  2. 失败要选边:守卫失败关闭,通知失败开放;
  3. 能确定的不交给模型:路径、引用、判定、格式,全部用代码算。

这套插件现在还不算什么:没有统一 UI,没有插件间编排,也不能替代真正的工作流系统。它的价值在于把“在别人的 Agent 运行时里加一层”这件事拆开给你看——哪些位置能加、加了之后怎么卸、卸不干净会留下什么。

如果只记一句:先想清楚失败的那一侧代价更小,再决定代码怎么写。

本文阅读--次|全站访问--次|访客--人