DSH 插件开发四件套

原名：dsh-plugin-devkit 一句话：写 DSH 插件时最容易踩的四个坑，做成四个命令。写完跑一遍就知道对不对。

---

为什么需要它

给 DSH 写插件有个特点：搞错了往往不报错，就是不生效。 你会花几个小时怀疑人生，最后发现是某个约定没遵守。

这四件工具，就是从"花了几小时"的那四次里长出来的。

---

四个命令

一、冒烟测试 ——「我的插件能加载吗」

dsh-plugin-devkit smoke ./lib/client.js

它干什么：用假的 window / react 把你的插件加载一遍， 看它能不能正常执行并导出 apply 和 inject。

为什么有用：不需要真装进 DSH 就能测。 装进 DSH 才发现坏了的话，代价是整个界面起不来（重装/回滚很麻烦）。

输出示例：
  ✓ 调用了 __ModuleLoader__.load，id = 我的插件
  ✓ factory 执行成功
  ✓ apply 跑通，挂载尝试的插槽: ["settings.section"]
  ✅ 冒烟测试全过

---

二、副本漂移检测 ——「我改的代码到底跑起来没有」

dsh-plugin-devkit sync-check <插件名>

它干什么：比对「插件源码目录」和「DSH 实际加载的那份副本」。

为什么有用：用 file: 方式装的插件，DSH 加载的是 profiles/<名字>/node_modules/ 里的副本，不是你改的源码目录。

⇒ 只改源码不同步 = 改了跟没改一样
  ★ 我们连栽两轮才明白这件事

---

三、版本对齐检测 ——「为什么设置页报 404」

dsh-plugin-devkit version-check

它干什么：检查 profile 里的官方包版本，是不是跟客户端自带的那个一致。

为什么有用：不一致会出各种怪事。我们遇到过的真实案例：

「权限」下拉框变成"不可用"，报错 HTTP 404
根因：profile 里装的是旧版 dsh-permission-presets（没有 catalog 接口），
      客户端里是新版（有这个接口）
⇒ 版本对不上 ⇒ 接口找不到 ⇒ 404

---

四、CSS 变量冲突扫描 ——「我的样式把别人弄坏了」

dsh-plugin-devkit css-check

它干什么：扫「我们往 :root 设的 CSS 变量」和「第三方插件读的变量」有没有撞车。

为什么有用：真实案例 ——

我把一个 DSH 本体不存在的变量设成 transparent
⇒ 另一个插件正好读这个变量 ⇒ 它的面板全透

---

适合谁

任何想给 DSH 写插件的人。 这四个坑他们 100% 会撞上。

---

需要什么

• 只需要 Node（DSH 自带）
• 不需要装任何第三方包

---

当前状态：四个脚本已可运行，正在补统一的 CLI 外壳。

---

怎么装

# 方式一：不装，直接用
npx dsh-plugin-devkit smoke ./lib/client.js

# 方式二：装到全局
npm i -g dsh-plugin-devkit
dsh-plugin-devkit smoke ./lib/client.js

四个子命令

dsh-plugin-devkit smoke   <客户端插件.js>    # 冒烟测试
dsh-plugin-devkit sync    <插件名>          # 副本漂移检测（可加 --sync 同步）
dsh-plugin-devkit version                   # 版本对齐检测
dsh-plugin-devkit css                       # CSS 变量冲突扫描

退出码

• 0 = 检查通过
• 1 = 有问题（看输出）
• 2 = 用法错误

许可

MIT

---

维护策略

这是一个个人项目，按现状发布（as-is）。

• Issue / PR 欢迎，但不保证及时回复 —— 我有正职，这是业余时间做的
• PR 我会看 diff 再决定要不要合并 —— 不会盲目合并（安全起见）
• 不接受"催更" —— 有需要欢迎自己 fork 改
• 如果你发现了好用的改进，欢迎提 PR；如果我长期没回，你完全可以 fork 走

这个项目不承诺任何 SLA。 用之前请自己评估。