Web0926/dsh-llm-verifier

dsh-llm-verifier

让多个 Coding Agent 独立生成补丁，先用项目测试淘汰失败方案，再由 LLM Verifier 排名；只有你二次授权后，获胜补丁才会写入原仓库。

English

dsh-llm-verifier 是面向 DeepSeek Harness 的开发者预览插件。它会让 3 个或 5 个候选 Agent 在各自的 detached Git worktree 中完成同一项编码任务，逐个执行项目验证，只把通过验证的补丁交给 llm-verifier 排名。候选生成和排名期间，原工作区保持不变；应用获胜补丁需要第二次明确授权。

[!WARNING]
当前公开版本只适合处理可信仓库。候选生成使用 detached Git worktree 和 DeepSeek Harness workspace-write 权限模式，但验证命令仍会在宿主机执行目标仓库代码。使用前请阅读安全边界。

为什么做这个项目

同一个 Coding Agent 对同一个任务进行多次独立尝试，可能得到质量明显不同的补丁：某个候选修复更简单，某个候选补充了更完整的测试，另一个候选可能引入隐藏回归。手动运行并比较多个候选，又会带来新的编排和评审成本。

这个插件把流程收敛为一次带审批的纵向工作流：

1. 所有候选接收完全相同的编码任务。
2. 候选修改分别保存在 detached Git worktree。
3. 先执行确定性的项目验证，再进行模型排名。
4. 验证失败的候选直接淘汰。
5. 多个合格补丁需要比较时，由 LLM Verifier 排名。
6. 生成可审计报告和获胜补丁。
7. 用户第二次授权后才应用补丁，并重新执行原验证命令。

flowchart LR
T[同一项编码任务] --> C1[候选 1]
T --> C2[候选 2]
T --> C3[候选 3]
T -. Best-of-5 .-> C45[候选 4 和 5]

C1 --> V1{项目验证}
C2 --> V2{项目验证}
C3 --> V3{项目验证}
C45 --> V45{项目验证}

V1 -->|通过| R[LLM Verifier 或仅按验证选出]
V2 -->|通过| R
V3 -->|通过| R
V45 -->|通过| R
V1 -->|失败| X[淘汰]
V2 -->|失败| X
V3 -->|失败| X
V45 -->|失败| X

R --> A[报告和 winner.patch]
A --> H{第二次授权}
H -->|同意| P[应用补丁并重新验证]
H -->|停止| U[原工作区保持不变]

核心能力

- Best-of-3 / Best-of-5： 默认 3 个候选，高价值任务可选择 5 个。
- 验证优先： 测试失败的候选不会进入模型排名。
- 受控排名： 只有一个候选通过时直接胜出；两个候选使用一个 pivot；三个至五个候选使用两个 pivots。
- 两次审批： 首次审批允许候选执行，第二次审批允许应用获胜补丁。
- 应用前完整性复核： 再次校验仓库路径、基础 HEAD、干净状态和补丁 SHA-256。
- 可审计产物： 报告记录候选名次、变更文件、耗时、进程状态、补丁哈希、Verifier 请求数和 Token 用量。
- 凭据控制： 验证进程不会收到 DeepSeek API Key；候选日志、错误、验证输出和文本 diff 会依据精确凭据值进行脱敏。
- 不自动操作 Git： 不会自动 commit、push、stash、reset 或应用补丁。

当前状态

| 项目 | 当前公开版本 |
|---|---|
| 阶段 | 开发者预览 |
| DeepSeek Harness | 固定 0.1.0-rc.7 |
| Node.js | 24.x |
| Python Bridge | 由 uv 管理；Python >=3.9,"
}

插件会再次请求授权，应用后重新运行原验证命令。

4. 卸载
bash
dsh plugin --profile web remove dsh-llm-verifier

工具

verified_best_of

完成候选生成、项目验证和获胜者选择，期间不修改原工作区。

| 参数 | 必填 | 说明 |
|---|---:|---|
| task | 是 | 所有候选共享的编码任务。 |
| candidateCount | 否 | 3 或 5，默认 3。 |
| validationCommands | 否 | 显式验证命令；省略时自动识别一种受支持的根项目类型。 |

可能的运行状态为 winner_selected、no_winner 和 failed。

apply_verified_winner

在单独审批后应用一个已选出的获胜补丁。应用前再次检查仓库身份和状态、基础提交及补丁 SHA-256，随后重新运行原始验证命令。

自动验证识别

显式命令优先。没有显式命令时，仓库根目录必须只匹配一种受支持项目类型：

| 根目录标识 | 命令 |
|---|---|
| package.json、唯一 JavaScript 包管理器、test script | 对应包管理器的 test 命令 |
| pyproject.toml | uv run pytest |
| Cargo.toml | cargo test |
| go.mod | go test ./... |
| 带 test target 的 Makefile | make test |

同时匹配多种项目类型、存在多个 JavaScript 包管理器或无法识别时，插件会 fail fast，并要求用户显式提供命令。

安全边界

插件对仓库修改、凭据和产物采取保守策略，但当前公开版本尚未形成容器级隔离边界。

- 只接受普通、干净的 Git 仓库根目录。
- 拒绝子模块、稀疏检出、linked worktree 和未提交修改。
- 候选工作区位于 $DSH_HOME/llm-verifier/runs/ 下的 detached worktree。
- 候选 Harness 显式使用 workspace-write，不会继承宿主的 DSH_PERMISSION_MODE。
- 验证命令会在宿主机执行仓库代码；当前版本只应处理可信仓库与可信验证命令。
- 验证进程不会收到 API Key。
- 候选把精确凭据写入文本、二进制内容或符号链接目标时，整个候选立即失效。
- 二进制内容不会发送给 Verifier，完整 binary patch 只保存在本地。
- 取消或超时会终止候选进程组，并尝试清理插件创建的 worktree。
- 应用失败后保留现场供检查，不会自动执行 git reset 回滚。

每次都应阅读审批提示，尤其关注首次审批展示的验证命令。

运行产物
text
$DSH_HOME/llm-verifier/runs//
├── artifacts/
├── manifest.json
├── report.md
├── winner.patch
└── apply-result.json        # 仅在尝试应用后生成

报告会记录候选启动、完成、通过验证和进入排名的数量，退出码与耗时、diff stat、补丁路径与 SHA-256、日志路径、二进制文件元数据、Verifier 请求数和 Token 用量。发送给 Verifier 的材料发生截断时，报告会指向完整本地产物。

成本提示

默认三项评审标准、每项重复两次时，全部候选合格的 Best-of-3 约产生 36 次 Verifier 请求，Best-of-5 约产生 72 次。实际请求数会受合格候选和缓存命中影响，并写入报告。

真实候选和 Verifier 运行会产生模型费用；自动测试不会调用真实 DeepSeek API。

配置

默认值：

| 配置 | 默认值 |
|---|---:|
| defaultCandidateCount | 3 |
| candidateProfile | headless |
| credentialRef | DEEPSEEK_API_KEY |
| verifierModel | deepseek-v4-flash |
| nEvaluations | 2 |
| maxVerifierWorkers | 8 |
| verifierEffort | high |
| verifierMaxTokens | 32768 |
| candidateTimeoutMs | 1200000 |
| validationTimeoutMs | 600000 |
| runTimeoutMs | 2700000 |
| maxVerifierTraceBytes | 524288 |
| stateDirectory | $DSH_HOME/llm-verifier |

可在 Web profile 的 cordis.patch.yml 中覆盖配置：
yaml
- id: llm-verifier
config:
defaultCandidateCount: 3
candidateProfile: headless
credentialRef: DEEPSEEK_API_KEY
verifierModel: deepseek-v4-flash
nEvaluations: 2
maxVerifierWorkers: 8
verifierEffort: high
verifierMaxTokens: 32768
candidateTimeoutMs: 1200000
validationTimeoutMs: 600000
runTimeoutMs: 2700000
maxVerifierTraceBytes: 524288
stateDirectory: $DSH_HOME/llm-verifier

nEvaluations 支持 1–4，maxVerifierWorkers 支持 1–16，verifierEffort 支持 low、high、max。verifierModel 必须以 deepseek- 开头。

开发验证
bash
pnpm run typecheck
pnpm test
pnpm run build
python3 -m py_compile python/verifier_bridge.py

测试覆盖 Best-of-3 / Best-of-5 合格候选矩阵、补丁篡改、凭据脱敏、Verifier 故障、应用后验证失败、二进制补丁、输入截断和残留进程清理。

提交修改前请阅读 CONTRIBUTING.md。Bug 报告应只包含脱敏证据，禁止提交凭据或私有仓库正文。

当前限制

- 不支持 Windows。
- 不支持脏工作区、子模块、稀疏检出或 linked worktree。
- 候选数量固定为 3 或 5。
- 不自动 commit、push、merge 或应用补丁。
- 不支持 OpenAI、Vertex、vLLM 等其他 Verifier 后端。
- 暂无自定义 Web UI、ProgressTracker 或提前停止。
- 仅支持源码构建和本地路径安装，尚未发布 npm 包或预构建 GitHub Release。

License

MIT