DSH 插件避坑

August 17, 2026 · View on GitHub

dsh-plugin-verify 判定站出品。本文基于我们自己的运行时验证实践（18 份可复现报告 + 三个闭环案例），只写亲历过的坑，不写没验证过的结论。

生态里最常听到的一句话是："等我适配好别人插件，人家又更新了，不是砸了。"

这句话暴露的真实痛点不是"找不到插件"，是**"适配成本会被更新破坏"**。适配者最怕的不是写代码，是写完被下一次发布悄悄推翻。

我们做运行时验证以来，反复撞见同一个底层模式——依赖版本错位。它有三个分身，每个都真实地砸过东西：

模式一：验证基准与插件依赖面的版本错位

现象：插件静态检查全过、逻辑看着完全正常，一跑运行时却 0/7 全挂，输出为空，headless 根本没起来。

亲历实例：一个高星终端类插件，静态检查全部通过（R1/R2 规则命中、无高危告警），但运行时验证 7 项全失败，终端 dump 为空。排查到最后，原因不是插件有 bug，而是验证基准（@deepseek-ai/dsh 0.1.0-rc.5）与插件声明的依赖面（面向 rc.6）存在版本错位——插件按新一版 API 写的，基准还在旧版。我们把它判为 ⓘ 环境边界（环境导致，非插件缺陷），等基准升级后复验。

为什么发生：DSH 还在 rc 阶段快速迭代，插件作者和验证工具各自 pin 的基准版本很容易差一代。插件不是写坏了，是它面向的世界比你的验证环境新了一版。

怎么避：

  • 验证/判定任何结果，先记录基准版本（我们的报告带 verifiedBy: dsh-plugin-verify@x.y.z + schemaVersion）。没有基准的验证结论没有意义。
  • 插件作者在 README/package.json 里显式声明自己面向的 dsh 版本（dsh 字段或 engines），别让依赖面变成隐式契约。
  • 适配者遇到"明明看起来没问题但跑不起来"——先查版本对位，再查代码。

模式二：官方升级会把你的通道一起带崩

现象：什么都没改，官方发布一个新 rc，你的 PTY/命令通道/工具调用突然全挂。

亲历实例：官方 @deepseek-ai/dsh 升到 0.1.0-rc.7 时，把 node-pty 从 ^1.1.0 提到 1.2.0-beta.15，Windows 上 persistent PTY 直接起不来（pid 0 + 进程立即退出），Linux/macOS 正常（官方 Discussion #2851）。这次不是插件的问题，是官方升级带崩了运行环境。

为什么发生：harness 的 PTY/子进程层是基础设施，它的依赖升级影响所有上层。rc 阶段的依赖升级（尤其是上 beta）没有兼容性承诺。

怎么避：

  • 如果你的分发/自举依赖官方 npm 包（如 npx 启动器、桌面壳），pin 精确版本，不用 latest/^，官方修完再解锁（我们的处置：桌面壳锁 rc.6，等官方修复出 rc.8 再解）。
  • 验证工具记录官方版本基线：我们的报告全部标注验证时的 dsh 基准版本，官方一发新版就重跑冒烟，把"环境坏了"和"插件坏了"分开。
  • 遇到"昨天还好的今天挂了"，先看官方发布记录，别急着怀疑自己的代码。

模式三：把"未评估"误当成"没问题"

现象：字段缺失/值语义不清，导致下游把"没测过"读成"测过且干净"。

亲历实例：我们的 security 字段曾有多条是 null，本意是"未评估，不误报"；catalog 维护者反馈：一个大多数时候为 null 的 security 字段，很容易被读成"没发现问题"而不是"未评估"——我们采纳并改进了文档标注（null = 未评估 / {status:clean} = 已检查干净）。

为什么发生：布尔/三态字段的缺省值语义不显式写清楚，读的人用直觉补齐。

怎么避：

  • 任何状态字段，把缺省值的语义显式写进文档，别让读者猜。
  • 验证报告把"环境边界/未评估/失败"三态分开标（我们目录的 ✅/ⓘ/候选 就是这个设计）。
  • 下游消费数据时，把 null/缺失当"未知"处理，不当"通过"。

操作清单（给读者带走）

  1. 所有验证结论带基准版本，没有基准的结论不成立。
  2. 分发/自举 pin 精确版本，官方修复后解 pin。
  3. 插件显式声明面向的 dsh 版本，别让依赖面成为隐式契约。
  4. "昨天好的今天挂了"先查官方发布记录，再查自己的代码。
  5. 状态字段写清缺省语义，"未评估"永远不等于"通过"。

后记：素材来源与边界

本篇所有实例来自 dsh-plugin-verify 的运行时验证实践——18 份可复现报告、三个闭环案例（帮一个插件作者定位 bug 并按建议修复、一个高星插件判环境边界待基准升级、一个官方回归被社区反馈检出）。我们只写自己亲历过的坑，不写没验证过的结论——这也是为什么它篇幅短：诚实度要求素材亲历，这是它唯一的护城河。

更多案例见 docs/case-studies/，判定站主页见 README。