BiBoyang/dsh-eval-harness
51最近提交 2026年8月14日
dsh-eval-harness DSH 插件
dsh-eval-harness 是一个 DSH 插件，为 DSH 插件和 skill 开发提供回归评测工作流。你可以编写 YAML 测试用例，在 headless 模式下驱动真实 DSH agent 运行，解析会话跟踪，断言期望行为，并将结果与基线对比，生成 PASS/WARN/FAIL 报告及 CI 兼容的退出码。它设计为集成到 CI 管道中，自动捕获回归问题。
如何安装 dsh-eval-harness DSH 插件
dsh plugin --profile headless add dsh-eval-harness复制不会执行命令。安装 dsh-eval-harness DSH 插件前请核对仓库和版本。
dsh-eval-harness DSH 插件数据来源
dsh-eval-harness DSH 插件快照日期：2026年8月16日
discovered
dsh-eval-harness DSH 插件能做什么
- 通过 eval_run 执行目录下所有 YAML 用例，驱动 headless DSH agent 并收集会话跟踪。
- 支持多种断言类型：turn_end、tools_called、output_contains、max_steps、max_tokens、no_tool_errors、tools_exact、tools_not_called、output_not_contains、output_matches、tool_args_contains、tool_result_contains 以及 LLM 语义评审（output_judge）。
- 提供 eval_gate 将本次报告与基线报告对比，输出整体判定（PASS/WARN/FAIL）和退出码，用于 CI 集成。
- 内置零依赖的 YAML 子集解析器，用于解析用例文件。
- 支持并发执行用例（concurrency 参数），每个用例拥有独立的会话目录和工作空间。
- 自动识别并读取 zstd 压缩或纯文本 JSONL 会话跟踪。
dsh-eval-harness DSH 插件适合哪些场景
- 在合并拉取请求前对 DSH 插件或 skill 运行回归测试。
- 集成到 CI 管道中，根据测试结果自动拦截部署。
- 当结构断言不足以评估时，使用 LLM 语义评审判断 agent 回答的正确性。
- 比较不同运行的 token 消耗，发现意外的成本增加。
- 维护一份期望行为的基线，当变更导致回归时收到告警。
dsh-eval-harness DSH 插件适合谁
- DSH 插件开发者，需要确保插件不破坏现有功能。
- DSH skill 作者，希望通过自动化测试验证 skill 行为。
- CI/CD 管道维护者，为 DSH 项目设置回归门禁。
dsh-eval-harness DSH 插件的限制
- 需要真实的 DSH 环境，具有 headless profile 以及有效的 DSH 二进制文件或 npx 回退。
- LLM 语义评审依赖 OpenAI 兼容 API（默认 DeepSeek），需要设置 EVAL_JUDGE_API_KEY 或 DEEPSEEK_API_KEY 环境变量；若缺失则调用会报错。
- 仅支持 YAML 子集：不支持锚点、多文档或复杂流结构；解析错误会报告行号。
- 默认并发数为 1；更高的并发可能需要谨慎的资源管理。
- 基线报告在变更后需通过单独的工作流手动更新。
dsh-eval-harness DSH 插件的仓库 README 摘录
以下文字摘自 dsh-eval-harness DSH 插件的上游仓库 BiBoyang/dsh-eval-harness 的 README，版权归原作者，仅作引用。
DSH 插件/skill 作者的回归评测门禁：写 yaml 用例 → headless 驱动真实 agent 跑 → 解析 session trace 断言 → 对比 baseline 出 PASS/WARN/FAIL 报告与 CI 退出码。 ## 简介 给 DSH 插件/skill 的回归评测流程提供一个可进 CI 的门禁工具： 1. 用 yaml 写评测用例（prompt + 期望行为断言）； 2. `eval_run` 逐条 fork `dsh --profile headless --patch <overlay> <prompt>` 子进程跑真实 agent（overlay 把会话落盘切到隔离目录，每条用例独立 workspace），解析落盘的 `session.jsonl` / `session.jsonl.zstd` trace（多帧 zstd 直读），执行断言，写 `report.json` + `report.md`； 3. `eval_gate` 把本次报告与 baseline 报告对比，输出 `OVERALL=PASS|WARN|FAIL|N/A` 与退出码，供 CI 拦截回归。 ## 安装 已发布到 npm（[`dsh-eval-harness`](https://www.npmjs.com/package/dsh-eval-harness)）： ```sh dsh plugin --profile headless add dsh-eval-harness # 或从 GitHub 源码安装： # dsh plugin --profile headless add github:boyang/dsh-eval-harness # 验证挂载 dsh --profile headless --dump-config | grep dsh-eval-harness ``` ## 能力面 ### Tools | 工具 | 说明 | | --- | --- | | `eval_run` | 跑 cases_dir 下全部用例：headless 驱动真实 agent → 采集 session trace → 断言 → 写 report.json/report.md | | `eval_gate` | 对比 baseline 与本次报告，输出门禁判定（OVERALL/EXIT_CODE），strict 模式收紧 WARN 退出码 | ### Skills | Skill | 作用 | | --- | --- | | `eval` | 教模型帮用户编写评测用例（用例格式、断言编写要点、解析子集约束） | ## 用例格式（cases/*.yml） 一个文件一条用例： ```yaml name: 用例名
阅读完整 README仓库未声明许可，使用前请先与作者确认。
dsh-eval-harness DSH 插件常见问题
如何安装 dsh-eval-harness？
使用 DSH 插件安装命令：`dsh plugin --profile headless add dsh-eval-harness`。也可以从 GitHub 源码安装：`dsh plugin --profile headless add github:boyang/dsh-eval-harness`。安装后通过 `dsh --profile headless --dump-config | grep dsh-eval-harness` 验证插件是否挂载。
如何编写测试用例？
在 cases 目录下创建 YAML 文件，格式遵循 README 中的说明。每个文件包含一个用例，字段包括 `name`、`prompt`、可选的 `require_plugins`、`tags`、`retries` 以及 `assert` 部分。`assert` 支持多种断言类型，如 `turn_end`、`tools_called`、`output_contains`、`max_steps`、`max_tokens` 等。还可以使用 `output_judge` 进行基于 LLM 的语义评审。
如何配置 LLM 评审器？
评审器使用 OpenAI 兼容的聊天补全 API。设置环境变量 `EVAL_JUDGE_API_KEY`（回退到 `DEEPSEEK_API_KEY`）、`EVAL_JUDGE_BASE_URL`（默认 `https://api.deepseek.com`）和 `EVAL_JUDGE_MODEL`（默认 `deepseek-chat`）。如果未设置，评审器调用将报错。评审器仅在所有结构断言通过后才会调用，以节省 token。
如何更新基线报告？
使用提供的 GitHub Actions 工作流 `update-baseline.yml`（从 Actions 页面手动触发）。它会运行所有用例，覆盖 `baseline/report.json`，创建一个包含报告摘要的 PR 供人工审查。不要自动合并。更新基线后，后续的 eval_gate 将使用新基线进行比较。
门禁判定逻辑是什么？
判定按优先级顺序：如果任何用例从 PASS 变为 FAIL/error，或新增用例为 FAIL/error，则判定为 FAIL（退出码 1）。如果任何用例从 FAIL/error 变为 PASS，或用例数量变化（新增/移除），则判定为 WARN（退出码 0，严格模式为 2）。如果 token 总量超过阈值，则判定为 WARN。如果所有与基线一致，则判定为 PASS（退出码 0）。如果没有基线，则判定为 N/A（退出码 2）。