DSH plugin 怎么测:装配、配置、工具契约与卸载四层检查,不接真实模型也能完整验证
插件测试的难处不在写断言,而在不知道断言该写在哪。界面能打开、工具能点,看起来都对,可换台机器就加载失败。
把验证拆成四层,每层只回答一个问题,测试就不再靠手感。
先定义什么叫坏掉的 DSH plugin
一个插件有四种坏法,对应四层验证。 先把分类摆清楚,后面的命令才有意义:
| 坏法 | 表现 | 归属 |
|---|---|---|
| 加载不进来 | 启动报错或插件停住 | 装配层 |
| 加载了但配置是错的 | 行为与预期不符 | 配置层 |
| 工具调用报错或渲染异常 | 模型侧报错、界面空白 | 契约层 |
| 重载后行为叠加 | 定时器翻倍、监听重复 | 卸载层 |
只有第一层会阻断启动,后三层都是「跑得起来但不对」。 所以验证顺序也按这个来,先保证能跑,再保证跑对。
装配层:DSH plugin 能不能加载
装配层通过了,才说明 DSH plugin 真的被 Loader 挂载并执行。
这一层只回答一个问题:Loader 有没有把你的插件挂上去。
- 准备一个只包含本插件的
cordis.yml,用--patch挂载启动; - 在
apply第一行写一句明确的日志,例如[hello] loaded; - 启动后确认终端出现这句日志;
- 记录进程退出码,正常启动时不应该是 1;
- 删掉插件文件再启动一次,确认失败信息能指出模块找不到。
第 5 步经常被跳过,但它才是测试。 只验证「成功路径能跑」,等于没验证错误处理;故意制造一次失败,你才知道失败时长什么样。
失败时不要只看终端最后一行。必需插件激活失败会生成 startup-<时间戳>-<uuid>.log,里面才有完整的插件状态与堆栈。
配置层:DSH plugin 组合后的值对不对
配置问题最隐蔽,因为默认值会让错误看起来正常。 这一层用 --dump-config,不启动服务也能看:
- 在不启动的情况下执行
<命令> --dump-config,找到你的插件那一层; - 确认
config里的值是你写的,而不是被上层 patch 覆盖掉的; - 传一个非法值(例如把数字写成字符串),确认加载失败且报错指向该字段;
- 删掉一个必填字段,确认失败而不是静默用空值;
- 恢复配置,确认能正常启动。
第 3、4 步验证的是 schema 是否真的生效。 如果非法值也能加载,说明你的 Config 没导出,或者 schema 写成了普通对象,框架根本没校验。
还有一个容易漏的点:patch 会整行替换 config,不会深度合并。你在 profile 里只改一个键,可能把其他默认值一起抹掉;测试时至少覆盖「只有部分字段」的配置。
契约层:DSH plugin 工具声明与实际行为
工具是插件最容易出问题的地方,因为它跨了模型、框架与界面三层。 这一层不用模型,也能测四件事:
parameters是否被正确推导,传错类型时是否在调用前就被拒绝;execute的返回值是否满足output.schema声明的类型;render是否只依赖入参与规范值,没有读取外部可变状态;- 工具名是否与已有工具冲突,注册时是否被拒绝。
第 3 条只能靠你自查。 渲染函数要求是纯函数,一旦它读了全局变量或当前时间,同一份结果在不同时刻渲染出的卡片就不一样,测试无法复现。
契约测试的最小做法是「错一次」。 故意返回一个不符合 schema 的值,确认框架报错;故意注册一个重名工具,确认被拒绝。两次都按预期失败,契约才算被真正约束。
卸载层:DSH plugin 重载之后还剩下什么
这一层最容易被忽略,却决定了插件能不能长期开发。 验证方式:
- 启动后记录资源特征,例如监听数量或轮询日志频率;
- 连续触发热重载三次以上;
- 确认特征值没有变化;
- 卸载插件后确认资源消失,端口与句柄没有残留;
- 重新加载,确认功能恢复且没有「已被占用」类报错。
重载三次是有意为之。 只重载一次,很多重复注册问题不会显形;三次之后,泄漏会变成肉眼可见的频率变化。
放进 CI:DSH plugin 的四条断言
CI 没有界面,也没有模型,能断言的是四件事:
- 进程能起来:启动命令在超时内没有退出,或退出码为 0;
- 装配成功:日志里出现你写的那句加载标记;
- 配置可解析:
--dump-config退出码为 0,且输出里包含预期字段; - 失败可判定:故意传入非法配置时,退出码非 0。
第 4 条是关键。 只断言成功路径的 CI,会在插件永远加载失败时依然通过——因为「没起来」和「起来了但没输出」在很多脚本里都表现为「命令结束」。
一个够用的骨架长这样:
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 实验环境。
常见问题
不接模型也能测 DSH plugin 的四类问题:插件能否加载、配置是否合法、工具定义是否符合契约、卸载是否残留。只有「模型会不会选中这个工具」必须接真实模型,其余都可以在本地或无密钥环境完成。
用 --patch 挂载本地 DSH plugin 启动,观察日志里是否出现插件的加载输出。失败时进程会以非零退出码结束并写出诊断。日志加退出码,比在界面里找入口更快。
验证 DSH plugin 工具契约要同时看三处:parameters 是否被正确推导、execute 返回值是否符合 output.schema、render 是否为纯函数。前两项由框架校验,render 的纯函数性质需要你自己检查是否引用了外部可变状态。
两类:启动阶段必需插件激活失败时进程以退出码 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 行为参考
来源
- DeepSeek Harness 开发文档:第一个插件· deepseek-harness
- DeepSeek Harness 开发文档:开发一个工具· deepseek-harness
- DeepSeek Harness CLI 行为参考· deepseek-ai