ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 怎么测:装配、配置、工具契约与卸载四层检查,不接真实模型也能完整验证

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugin插件测试CIdump-configDeepSeek Harness
没有模型、没有人点界面,也能判断插件有没有坏。把验证拆成装配、配置、契约、卸载四层,每层给出命令、预期结果,以及放进 CI 的四条断言。

插件测试的难处不在写断言,而在不知道断言该写在哪。界面能打开、工具能点,看起来都对,可换台机器就加载失败。

把验证拆成四层,每层只回答一个问题,测试就不再靠手感。

先定义什么叫坏掉的 DSH plugin

一个插件有四种坏法,对应四层验证。 先把分类摆清楚,后面的命令才有意义:

坏法表现归属
加载不进来启动报错或插件停住装配层
加载了但配置是错的行为与预期不符配置层
工具调用报错或渲染异常模型侧报错、界面空白契约层
重载后行为叠加定时器翻倍、监听重复卸载层

只有第一层会阻断启动,后三层都是「跑得起来但不对」。 所以验证顺序也按这个来,先保证能跑,再保证跑对。

装配层:DSH plugin 能不能加载

装配层通过了,才说明 DSH plugin 真的被 Loader 挂载并执行。

这一层只回答一个问题:Loader 有没有把你的插件挂上去。

  1. 准备一个只包含本插件的 cordis.yml,用 --patch 挂载启动;
  2. 在 apply 第一行写一句明确的日志,例如 [hello] loaded;
  3. 启动后确认终端出现这句日志;
  4. 记录进程退出码,正常启动时不应该是 1;
  5. 删掉插件文件再启动一次,确认失败信息能指出模块找不到。

第 5 步经常被跳过,但它才是测试。 只验证「成功路径能跑」,等于没验证错误处理;故意制造一次失败,你才知道失败时长什么样。

失败时不要只看终端最后一行。必需插件激活失败会生成 startup-<时间戳>-<uuid>.log,里面才有完整的插件状态与堆栈。

配置层:DSH plugin 组合后的值对不对

配置问题最隐蔽,因为默认值会让错误看起来正常。 这一层用 --dump-config,不启动服务也能看:

  1. 在不启动的情况下执行 <命令> --dump-config,找到你的插件那一层;
  2. 确认 config 里的值是你写的,而不是被上层 patch 覆盖掉的;
  3. 传一个非法值(例如把数字写成字符串),确认加载失败且报错指向该字段;
  4. 删掉一个必填字段,确认失败而不是静默用空值;
  5. 恢复配置,确认能正常启动。

第 3、4 步验证的是 schema 是否真的生效。 如果非法值也能加载,说明你的 Config 没导出,或者 schema 写成了普通对象,框架根本没校验。

还有一个容易漏的点:patch 会整行替换 config,不会深度合并。你在 profile 里只改一个键,可能把其他默认值一起抹掉;测试时至少覆盖「只有部分字段」的配置。

契约层:DSH plugin 工具声明与实际行为

工具是插件最容易出问题的地方,因为它跨了模型、框架与界面三层。 这一层不用模型,也能测四件事:

  1. parameters 是否被正确推导,传错类型时是否在调用前就被拒绝;
  2. execute 的返回值是否满足 output.schema 声明的类型;
  3. render 是否只依赖入参与规范值,没有读取外部可变状态;
  4. 工具名是否与已有工具冲突,注册时是否被拒绝。

第 3 条只能靠你自查。 渲染函数要求是纯函数,一旦它读了全局变量或当前时间,同一份结果在不同时刻渲染出的卡片就不一样,测试无法复现。

契约测试的最小做法是「错一次」。 故意返回一个不符合 schema 的值,确认框架报错;故意注册一个重名工具,确认被拒绝。两次都按预期失败,契约才算被真正约束。

卸载层:DSH plugin 重载之后还剩下什么

这一层最容易被忽略,却决定了插件能不能长期开发。 验证方式:

  1. 启动后记录资源特征,例如监听数量或轮询日志频率;
  2. 连续触发热重载三次以上;
  3. 确认特征值没有变化;
  4. 卸载插件后确认资源消失,端口与句柄没有残留;
  5. 重新加载,确认功能恢复且没有「已被占用」类报错。

重载三次是有意为之。 只重载一次,很多重复注册问题不会显形;三次之后,泄漏会变成肉眼可见的频率变化。

放进 CI:DSH plugin 的四条断言

CI 没有界面,也没有模型,能断言的是四件事:

  1. 进程能起来:启动命令在超时内没有退出,或退出码为 0;
  2. 装配成功:日志里出现你写的那句加载标记;
  3. 配置可解析:--dump-config 退出码为 0,且输出里包含预期字段;
  4. 失败可判定:故意传入非法配置时,退出码非 0。

第 4 条是关键。 只断言成功路径的 CI,会在插件永远加载失败时依然通过——因为「没起来」和「起来了但没输出」在很多脚本里都表现为「命令结束」。

一个够用的骨架长这样:

bash
export DSH_HOME="$(mktemp -d)"
dsh --profile web --patch ./cordis.yml --dump-config > /tmp/cfg.yml || exit 1
dsh --profile web --patch ./cordis.yml > /tmp/run.log 2>&1 &
grep -q '\[hello\] loaded' /tmp/run.log || exit 1

另外把 DSH_HOME 指向临时目录。 CI 里不要用默认的 ~/.dsh,否则一次运行会污染缓存与 profile,下一次结果不可比。

只有一类问题必须接真实模型:模型会不会在合适的时机选中你的工具。 这取决于工具名、描述、参数说明与系统提示,属于「可发现性」问题,不是装配或契约问题。验证方式是发一条自然语言指令,观察是否触发;触发不了,改的是描述与命名,不是代码逻辑。这类验证慢、要密钥、结果有波动,适合人工抽查,不适合每次提交都跑。

测试的目标不是覆盖率,而是把「只有用户能发现」的问题提前到本地。四层里每层留一个能失败一次的用例,比写一百个永远通过的断言有用。想先定位现有故障,读 DSH plugin 本地调试;想看工具契约的细节,读 工具 execute 契约;想在无密钥环境里练手,读 Cordis 实验环境。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 测试一定要接真实模型吗,不接模型能测出什么问题?

不接模型也能测 DSH plugin 的四类问题:插件能否加载、配置是否合法、工具定义是否符合契约、卸载是否残留。只有「模型会不会选中这个工具」必须接真实模型,其余都可以在本地或无密钥环境完成。

本地改完 DSH plugin 后,怎么快速确认它能被加载而不是直接开界面点?

用 --patch 挂载本地 DSH plugin 启动,观察日志里是否出现插件的加载输出。失败时进程会以非零退出码结束并写出诊断。日志加退出码,比在界面里找入口更快。

怎么验证 DSH plugin 工具的参数与返回值真的符合声明,而不是靠人工试?

验证 DSH plugin 工具契约要同时看三处:parameters 是否被正确推导、execute 返回值是否符合 output.schema、render 是否为纯函数。前两项由框架校验,render 的纯函数性质需要你自己检查是否引用了外部可变状态。

DSH plugin 放进 CI 后没有界面,验证失败的信号是什么?

两类:启动阶段必需插件激活失败时进程以退出码 1 结束并生成 startup 诊断文件;装配成功但行为不符时,依赖你写的断言,例如日志里没有预期输出。CI 要把这两类都覆盖。

相关术语

装配验证
装配验证是确认插件能被 Loader 加载并进入运行状态的过程,观察点是启动日志与进程退出码。— DeepSeek Harness 开发文档
契约验证
契约验证是检查工具的参数声明、返回值与渲染函数是否符合框架约定,避免运行期才暴露类型或渲染问题。— DeepSeek Harness 开发文档
dump-config
dump-config 是不启动服务、直接打印组合后配置树的检查手段,用来确认 patch 层叠加后的实际取值。— DeepSeek Harness CLI 行为参考
诊断文件
诊断文件是启动失败时 CLI 写入的 startup 日志,包含版本、profile、未激活插件与原始错误,位于 DSH_HOME 的 logs 目录。— DeepSeek Harness CLI 行为参考

来源