English · 简体中文
# DSH Plugin A/B Test
> 在发布 DSH 插件改动前，先用同一组任务验证它是否真的更好。
DSH Plugin A/B Test 会把当前版本（Control）和候选版本（Candidate）放进彼此隔离的 DSH 环境，逐题配对运行，再生成可复核的证据与发布建议。它适合回答三个很实际的问题：
- 新版本是否提高了任务成功率？
- 提升是否伴随明显的 token、延迟或工具错误回退？
- 结果能否由其他人用同一批输入重新跑出来？
最终结果只有四种：`PROMOTE`、`REVIEW`、`REJECT`、`INCONCLUSIVE`。其中 `PROMOTE` 也只是一项离线建议；本项目不会修改真实 DSH profile，也不会替你执行发布。
## 先看结果
下面是本仓库离线样例的一次真实输出（省略无关字段）：
```json
{
"outcome": "PROMOTE",
"validPairCount": 2,
"invalidPairCount": 0,
"triggeredRules": ["primary.superiority"]
}
```
除了这条结论，你还会得到每次运行的 session 证据、断言结果、配对差值，以及 JSON、Markdown、HTML 三种报告。结论不靠模型拍板，而是由 manifest 中的确定性规则计算。
## 快速开始
当前 MVP 从源码运行，要求 Node.js `^22.19.0 || >=24.0.0` 和 pnpm `11.19.0`。初始化样例使用离线 scripted provider，不需要模型 API key。
```bash
pnpm install --frozen-lockfile
node --import tsx src/cli/bin.ts init --output ./my-experiment --json
node --import tsx src/cli/bin.ts freeze --manifest ./my-experiment/experiment.yml --output ./evidence --json
node --import tsx src/cli/bin.ts run --manifest ./my-experiment/experiment.yml --output ./evidence --json
node --import tsx src/cli/bin.ts decision --manifest ./my-experiment/experiment.yml --output ./evidence --json
node --import tsx src/cli/bin.ts report --manifest ./my-experiment/experiment.yml --output ./evidence --json
```
打开 `./evidence//report.html` 即可查看静态报告。要测试自己的插件，只需修改初始化目录里的 `experiment.yml`、`evals/cases.yml` 和两个 variant 配置。
## 怎么判断
| 结果 | 含义 | 常见下一步 |
| --- | --- | --- |
| `PROMOTE` | 证据充分、质量达到目标且 guardrail 通过 | 进入人工发布流程 |
| `REVIEW` | 有改善，但成本、延迟、错误率或波动需要判断 | 阅读 pair 证据后人工复核 |
| `REJECT` | hard gate 失败、关键用例回退或收益不足 | 修复 Candidate 后重跑 |
| `INCONCLUSIVE` | 有效样本不足、插件暴露未证实或运行环境不可比 | 补齐证据，不把它当作失败 |
默认比较任务成功率，并可约束 token、P95 延迟和工具错误率。阈值、最小有效 pair 数、重复次数与并发数都写在 manifest 中；详细字段见 [manifest 文档](docs/manifest.md)，规则优先级见 [决策文档](docs/decisions.md)。
## 为什么结果可信
- **同题配对**：Control 与 Candidate 使用相同 case、workspace fixture 和模型参数。
- **顺序平衡**：运行顺序按 pair 交替，减少固定先后顺序带来的偏差。
- **环境隔离**：每个 arm 拥有独立的 `DSH_HOME`、profile、workspace、session root 和冻结插件制品。
- **制品可追溯**：支持本地目录、tarball、精确 npm 版本和固定 GitHub commit；运行前会再次校验制品哈希。
- **暴露可证明**：从 session 事件、工具调用或插件 receipt 判断目标插件是否真正参与了运行。
- **盲评不泄露身份**：可选 comparator 只看到匿名的 A/B 输出，映射在比较完成后才揭示。
- **失败不伪装成回退**：provider outage、损坏会话、环境差异等基础设施问题进入无效证据或 `INCONCLUSIVE`。
证据默认写入：
```text