插件验收测试 Flan246/dsh-plugin-litmus

dsh-plugin-litmus

npm version
npm downloads
GitHub stars
license

DeepSeek Harness 插件的自动化验收测试工具：用声明式场景（scenario.yaml）在隔离的 DSH_HOME 中真实驱动 headless agent 跑一遍，再对会话日志做断言与 LLM 评分，输出报告。CLI 命令名为 dsh-litmus。

安装

npm i -g dsh-plugin-litmus
或免安装直接跑
npx dsh-plugin-litmus run

前置条件

- Node.js ≥ 22.15（会话日志解码依赖 node:zlib 的 zstdDecompressSync）。
- 本机有 dsh 可执行（定位优先级：DEEPSEEK_HARNESS_CLI > $DSH_REPO/apps/cli/lib/bin.js（DSH_REPO 默认 D:\deepseek-harness）> PATH 中的 dsh > npx @deepseek-ai/dsh）。Windows 上若 PATH 命中 dsh.cmd/npx 无法直接执行（execFile 对 .cmd 的限制），请设置 DEEPSEEK_HARNESS_CLI 环境变量指向 dsh 的 bin.js（例如 D:\deepseek-harness\apps\cli\lib\bin.js）。
- .cmd 路由（PATH 命中 dsh.cmd 或 npx 兜底）会经 cmd.exe shell 执行：工具会对每个参数做双引号包裹 + 内部引号转义，&、|、>、^ 等元字符不会被解释；但 cmd 批处理中 % 仍会触发环境变量展开（无法靠引号保护），prompt 含 %VAR% 样式文本时可能被改写。需要完全规避时请设置 DEEPSEEK_HARNESS_CLI 走 node bin.js 直调路径（不经 shell）。
- DEEPSEEK_API_KEY 已导出（agent 运行与 LLM judge 都需要）。
- 访问外网（npm 安装插件、DeepSeek API）需 HTTPS_PROXY=http://127.0.0.1:7897（按本机代理调整）。

scenario.yaml 契约

每个场景是 //scenario.yaml（只扫一层子目录），场景目录内其余文件会在运行时拷贝到隔离工作目录。

完整示例：

name: bib 补全与引用对账 # 必填，场景名
plugins: [dsh-latex-guard] # 可选，默认 []；逐个 dsh plugin add（npm 包名或本地路径）
workdir: . # 可选；场景目录下要拷入隔离工作目录的子路径 prompt: 把 refs.bib 缺的字段补全，然后检查 main.tex 的引用是否完整。已有内容不要动。 # 必填，非空 timeout: 600 # 可选，默认 600 秒 assertions: # 必填，至少 1 条
- tool_called: bib_fill
- file_contains: [refs.bib, "year = {2015}"]
- tool_called: cite_audit
judge: # 可选；配置后用 DEEPSEEK_API_KEY 调 deepseek-chat 按 rubric 打分 rubric:
- 任务完成度
- 工具选择正确性

8 种断言：

| 断言 | 写法 | 语义 |
| tool_called | - tool_called: | 会话中调用过该工具 |
| tool_not_called | - tool_not_called: | 会话中未调用该工具 |
| tool_args_contains | - tool_args_contains: [, ] | 该工具某次调用的参数 JSON 包含子串 |
| output_matches | - output_matches: | 最终回答匹配正则（载入时校验可编译） |
| output_not_matches | - output_not_matches: | 最终回答不匹配正则 |
| file_contains | - file_contains: [, ] | 隔离工作目录中的文件包含子串 |
| file_not_contains | - file_not_contains: [, ] | 文件不包含子串 |
| exit_code | - exit_code: | headless 进程退出码等于该值 |

文件路径相对于隔离工作目录；断言全部通过场景才算 passed。校验失败报 INVALID_SCENARIO（消息含 zod 字段路径，如 assertions.0）。

headless 进程非零退出不会让场景直接 error：仍会尝试解码会话日志，交由 exit_code 等断言自行裁决（此时报告的错误栏会注明 headless exited : ）。只有插件安装失败、workdir 拷贝失败才会直接判 error，超时被杀判 timeout。

用法

初始化两个示例场景（s1-lit-search / s2-file-workflow） dsh-litmus init [dir]

运行 下所有场景 dsh-litmus run [--report ] [--keep-all]

run 的行为：逐场景创建临时隔离工作目录（拷入场景文件、独立 DSH_HOME、DSH_PERMISSION_MODE=danger-full-access；子进程环境会剔除 ambient 的 DSH_ 变量，防止本机配置渗入隔离运行）→ 安装 plugins → 以 --profile headless 跑 prompt → 解码最新会话日志 → 执行断言与可选 judge → 输出 console 汇总并写 report.md（默认 /report.md）。失败场景的隔离目录保留并打印路径（--keep-all 保留全部）；注意通过场景的临时目录当前也不自动删除，积累在系统临时目录（dsh-eval-）下可自行清理。

退出码

- 0：全部场景 passed。
- 1：有场景 failed / timeout / error。
- 2：用法或输入错误（场景文件不合法、目录下没有任何 scenario.yaml）。

judge 说明

场景配置 judge.rubric 后，会把工具调用序列与最终回答（截断 8000 字符）发给 deepseek-chat，按每个 rubric 维度打 0/1/2 分（0 失败 / 1 部分 / 2 达标）并附评语。judge 需要 DEEPSEEK_API_KEY；未配置 key 或请求失败时静默跳过，不影响断言判定（judge 分数只进报告，不参与 passed/failed）。

License

MIT © 2026 Flan246