DevRico003/dsh-verifier-gate

dsh-verifier-gate

一个用于 DeepSeek Harness（dsh）的 LLM 即验证器插件。它在每个智能体回合结束时添加一道质量门，外加三个智能体可调用来检查自身工作的工具。

评分方法是 Kwok 等人 llm-as-a-verifier 的移植（项目网站 llm-as-a-verifier.com，论文 arXiv 2607.05391，MIT）。那个仓库从 N 条智能体轨迹中选出最佳的一条。本插件采用相同的数学方法，并将其接入正在运行的 harness。

各部分如何组合在一起

两张图。第一张是插件在一个智能体回合内部的位置：它在哪里读取，在哪里发言。第二张是技能 graph-verified-coding，即决定智能体何时调用这些工具的工作方法。

flowchart TD
subgraph turn["One agent turn in dsh"]
S["agent steps 1..nread, edit, bash, browser, tests"]
S -->|"before a merge, before the final answer:verifier_assess, verifier_select, verifier_compare"| T["tool verdictscore, pass, findings"]
T --> S
S --> E{"turn stopping"}
end
E -->|"gate: three calls at high over thewhole turn plus the goal objective"| G{"score ≥ 0.6 ?"}
G -->|"yes, or a repair roundalready ran in this turn"| C["turn closes"]
G -->|"no, first time"| R["[dsh-verifier-gate] findingsthe agent repairs"]
R --> S
subgraph backend["verifier backend"]
V["same model, OpenAI-compatiblestreamed, logprobs top 20score = expectation over the letter distribution"]
end
T -.-> V
E -.-> V

flowchart TD
C["1 Contractacceptance criteria with an observable artifact each"] --> K["2 Cut false edgesnodes; parallel only where no output flowschildren write .graph/<node>.md"]
K --> W["3 Work nodeimplement, run the proving command, keep the output"]
W --> G["4 Checktests, lint, buildui_snapshot + analyze_image for anything rendered"]
G -->|"pass"| J{"competing candidates?"}
G -->|"fail"| Y["6 Cycle with a stoprepair, re-check, two rounds, then report what is open"]
Y --> G
J -->|"yes"| V["5 Joinverifier_select / verifier_comparemerge the winner"]
J -->|"no"| N{"more nodes?"}
V --> N
N -->|"yes"| W
N -->|"no"| A["7 Gate and reportverifier_assess over the whole deliverable,then the report with evidence"]
A --> Z["turn ends: the plugin gate scores the whole turn"]

为什么需要验证器

该方法来自 llm-as-a-verifier 的作者。他们的框架（来源：llm-as-a-verifier.com）：对 logits 求概率，而不是采样一个 token；使用细粒度评分 token；重复；并分解为更简单的标准，聚合为 R(x, tau) = 1/(C K) 对标准、重复和尺度值求和 p(v | x, c, tau) phi(v)。
LLM-as-a-Verifier 框架：不确定性、粒度、重复、分解

在与此插件所运行的相同模型下，这能带来什么（图表来自 llm-as-a-verifier README；Terminal-Bench 2.1、mini-swe-agent、DeepSeek V4 Flash 作为生成器和验证器，成本按 2026-08-17 的 OpenRouter 价格计算）：best-of-3 将 DeepSeek V4 Flash 从 78.7% 提升到 86.5%，best-of-5 提升到 88.0%，而每任务成本大约只有 Codex 中 GPT-5.6 Sol 的四分之一。

Terminal-Bench 2.1：成功率与每任务成本对比，DeepSeek V4 Flash 配合 LLM-as-a-Verifier 对比 Codex 和 Claude Code

此插件中的门控是那种 best-of-N 选择的更廉价表亲：一条轨迹，在结束时评分一次，修复一次。verifier_select 本身就是 best-of-N。

它做什么

门控。 当智能体即将结束一轮时，插件会序列化这一轮（任务、助手消息、每次工具调用及其观察到的输出），并要求验证器模型按标准以 20 个字母的等级为其评分。分数不是采样得到的字母。它是分数 token 的 logprob 分布上的期望值，因此判定结果是 [0, 1] 上的连续值。如果均值低于 gate.threshold，验证器的发现会作为插件消息返回给智能体，harness 会再运行一步。智能体会看到这样的文本：

[dsh-verifier-gate] Verification of your turn: 0.28 / 1.00, pass threshold 0.60, round 1 of 1.
Per criterion: Empirical Verification 0.13, Specification Adherence 0.21, Code Quality 0.50.

Empirical Verification (0.13):
The agent launched three background subagents ... There is zero observed verification in the trajectory: no npm test run, no curl of the service endpoints, no screenshot ...

那个例子来自一次真实运行。智能体回答“Fair criticism, let me check what's actually on disk now instead of trusting narration”，然后回去继续工作。每轮的续跑次数有上限（gate.maxRounds，默认 1）。以向用户提问结束的轮次永远不会被强制续跑。

门控就是自动验证的全部。没有轮次中途的读取，也没有提醒：智能体工作，验证器在结束时以全力读取已完成的轮次一次，就像参考实现为已完成的轨迹评分那样。此插件的早期版本每四十步以低力度为进行中的轮次评分，并在十二次未验证编辑后推动智能体；那花费的挂钟时间比它发现的问题更多，而改变结果的发现来自全力门控。在一轮之内，智能体在技能指定的位置自行调用验证器。

工具。

| 工具 | 它做什么 |
| --- | --- |
| verifier_assess(task, answer) | 按标准为一个结果评分并返回发现。默认情况下，它还会把当前轮次观察到的轨迹交给验证器，因此判定基于工具输出，而不是智能体的总结。 |
| verifier_select(task, candidates[]) | Best-of-N。通过槽位交换进行成对比较，然后使用概率枢轴锦标赛在 N + k(N-k) 次比较中选出胜者，而不是 N²。 |
| verifier_compare(task, a, b) | 一个定向的成对奖励。 |
| ui_snapshot(url) | 视觉工作的证据：在一个 URL 上跨视口（默认 1440x900 和 390x844）在浅色和深色模式下进行无头截图，以 PNG 形式写入 $DSH_HOME/verifier/snapshots// 下，外加加载时看到的控制台错误、页面错误和失败请求。针对已安装的 Google Chrome（然后是 Playwright 的 Chromium）运行 Playwright；屏幕上不会打开任何内容。将其与 analyze_image 等视觉工具配对以得出结论。 |

后端。 任何返回 logprobs 和 top_logprobs 的 OpenAI 兼容聊天补全端点（vLLM、SGLang、DeepSeek API）。logprobs 是实现细粒度评分的关键；不支持没有它们的端点，这与参考实现所述的要求相同。

提示词

面向验证器的文本来自参考实现。成对提示词（build_prompt）、两个量表描述和真实标注说明均为逐字照搬。coding 标准是 criteria/terminal_bench.md 中的 specification 加上 criteria/swe_bench.md 中的 code_review 和 verification（“issue”读作“task”，补丁定义为 diff 输出或通过工具写入的文件内容，因为 harness 轨迹将编辑作为工具调用携带）；terminal 是 criteria/terminal_bench.md；general 是本插件自己用于散文和答案的集合。门控和 verifier_assess 背后的单轨迹评估提示词是参考进度提示词（build_progress_prompt）缩减到最终状态，并扩展了一条标准指南和一项指出缺失内容的要求，因为该分析正是 agent 得到的反馈。面向 agent 的文本（工具描述、门控消息）是本插件自己的。

移植了什么，以及在哪里

| 参考概念 | 文件 |
| --- | --- |
| 20 字母量表、成对方向（A = 最佳）和进度方向（T = 最佳） | src/core/scale.ts |
| 奖励作为 logprob 期望、最后标签匹配、融合的 >A token、空白跳过、字面字母回退 | src/core/scoring.ts |
| 标准 × 重复，奇数重复时交换槽位；compare、select、assess | src/core/verifier.ts |
| 枢轴锦标赛：环形轮次、top-k 枢轴、枢轴轮、Bradley-Terry argmax | src/core/tournament.ts |
| 提示词将不变部分放在前面、标准放在最后（对前缀缓存友好）；标准集 general、coding、terminal | src/core/prompts.ts |
| 从 harness 会话日志进行轨迹序列化 | src/trajectory.ts |

参考仓库没有的东西：回合门控（src/gate.ts）、工具（src/tools.ts）、可热重载设置，以及下文描述的未评分裁决处理。

安装

git clone https://github.com/DevRico003/dsh-verifier-gatebash
dsh plugin --profile web add /path/to/dsh-verifier-gate
dsh plugin --profile headless add /path/to/dsh-verifier-gate
dsh plugin --profile desktop add /path/to/dsh-verifier-gate    # DSH Desktop

lib/ 已提交，因此安装时无需构建步骤。之后重启 dsh web 或桌面应用即可。

配置

默认值位于 cordis.patch.yml。随附的 backend.baseURL 是占位符 http://YOUR_SPARK_HOST:8000/v1；在你设置真实端点之前，插件会加载，但每次验证器调用都会失败，并给出指明该设置的消息（随后门控会将轮次关闭为未验证并记录警告，verifier_assess 返回 scoredCriteria: 0，消息位于 findings 中）。至少设置 backend.baseURL 和 backend.model。所有内容都是 $DSH_HOME/settings.yaml 中可热重载的 verifier: 配置段；无需重启。
yaml
verifier:
backend:
baseURL: http://YOUR_SPARK_HOST:8000/v1
model: deepseek-v4-flash-0731
apiKeyEnv: SPARK_API_KEY       # 环境变量或凭据引用；为空 = 无 Authorization 头
reasoningEffort: high          # 每次验证器调用，门控和工具均如此；low 约快 3 倍，none 是一次性读取
maxTokens: 65536               # 推理共享该预算；留出空间以便长时间思考后仍能给出答案
temperature: 1.0               # 参考默认值；保持 logprob 分布信息量充足
topLogprobs: 20
concurrency: 8                 # 一次评估为 3 次调用，对三个候选进行 select 为 15 次；它们一起并发执行
retriesOnFallback: 1
warmPrefix: false              # true = 每个提示前缀的首次调用单独进行，然后其余调用（节省预填充，墙钟时间翻倍）
timeoutMs: 3600000             # 每次调用的最后兜底上限
idleTimeoutMs: 900000          # 当流在此时间内未传递任何内容时中止（排队的请求在被调度前是静默的）
gate:
enabled: true
threshold: 0.6
maxRounds: 1
evaluations: 1                 # 每个标准的重复次数，门控和 verifier_assess 均如此
criteria: auto                 # 当轮次使用了工具时为 coding，否则为 general；或 general | coding | terminal
skipWhenAskingUser: true
skipSubagents: true            # 子代理不受门控；其父轮次受门控
minToolCallsWithoutOwnTask: 8  # 仅由子代理报告或通知开启的轮次，只有在其中包含实际工作时才受门控
feedbackMaxChars: 2500
timeoutMs: 4200000
select:
evaluations: 1                 # 用于 verifier_select 和 verifier_compare；2 会交换 A/B 并以两倍调用次数消除槽位偏差
pivots: 1
seed: 0
criteria: general
trajectory:
maxStepChars: 6000             # 每个工具输出 / 消息摘录
maxTotalChars: 300000          # 整个轮次；超过上限时中间部分被省略，开头和最近的步骤保留
continuationTurns: 1           # 以 "Continue." 开头的轮次会前置这么多更早的轮次
snapshot:
enabled: true                  # the ui_snapshot tool
channels: [chrome, chromium]   # tried in order; chrome = installed Google Chrome
headless: true
viewports: ["1440x900", "390x844"]
settleMs: 500
navigationTimeoutMs: 30000
dir: ""                        # empty = $DSH_HOME/verifier/snapshots
tools: true
verbose: false                   # true logs every verifier call with duration, token counts and score source

gate.enabled: false 保留工具并去掉门控。enabled: false 关闭插件。

哪些轮次会被门控

每个包含任务和工作的轮次，在其停止时被门控一次。以下三种情况会被处理，以便门控评判正确的对象：

- 以“Continue.”开头的轮次（中断后的自动继续、恢复的目标轮次）几乎不包含工作内容，因此交给验证器的轨迹会前置上一轮（trajectory.continuationTurns）；否则重启后紧接着的门控会看到命令但没有代码。
- 跨多个轮次运行的目标只会在第一轮携带其目标；后续轮次会依据该目标进行评判，而不是依据“Continue.”。
- 某些宿主会为每个子代理报告开启一个新轮次。这样的轮次通常只包含一条确认信息，别无其他；若依据目标来评判它，就会因目标仍缺少的一切而判其失败，因此没有自己任务消息的轮次，只有在它至少进行了 gate.minToolCallsWithoutOwnTask 次工具调用时才会被门控。

子代理（子代理、团队成员）不会被门控；被门控的是父级的轮次。

成本

一次门控通过是 criteria × evaluations 次验证器调用，默认三次，会一起并发发出。warmPrefix: true 会先单独运行第一次调用，以便服务器在其余调用发出之前缓存提示前缀（任务、轨迹、量表；评判标准位于末尾）；这就是参考实现中未缓存输入 token 节省 3.4 倍的原因，在按量计费的 API 或预填充较慢时值得启用。在本地 vLLM 上，预填充速度超过每秒 10k token，这只会让每次门控的墙钟时间翻倍，因此默认关闭。
验证器以 high 档思考，这是参考实现为其 DeepSeek-V4-Flash 数值设定的档位，并且它有空间：maxTokens 65536，无思考预算，调用以流式进行。在一对提供 DeepSeek-V4-Flash 服务的 DGX Spark 上实测：一个长回合的回合结束门控（98k token 的提示词）耗时 263 到 401 秒；对 27k token 轨迹的一次 verifier_assess 耗时 284 到 470 秒；对三个候选、两次重复的一次 verifier_select 在四个槽位上耗时 22 分钟，因此默认是在八个槽位上做一次重复。这些调用是短提示词、长回答，因此受生成速度约束并共享 GPU：并发调用越多，调用越慢，而不是吞吐越高。每次调用都是流式响应，所以模型思考时不会有头部超时触发；空闲计时器（idleTimeoutMs）会中止静默的流，而 timeoutMs 是最后一小时的上限。如果你想要速度而非参考设置，reasoningEffort: low 在此处的 A/B 测试中给出的判定与 high 相差在 0.06 以内，耗时约为三分之一；none 是用于聊天会话的一次性读取。

开启思考后，vLLM 也会在 logprobs.content 中返回推理 token；评分读取器会遍历 token 流并取最后一个  标签之后的字母，因此这一点已被处理。一个把全部预算花在推理上的回复不携带答案，会被报告为失败调用（重试一次，然后不计分），绝不会记为 0.5。

当一个回合超出轨迹上限时，开头的步骤保留，中间部分被省略，因此同一回合的每个门控都发送相同的前缀，而前缀缓存服务器（vLLM）只预填充尾部。

未计分的判定

验证器回复有时不携带可解析的评分标签。插件会重试这样的调用（backend.retriesOnFallback，默认 1）。仍然没有判定的内容会从所有均值中排除，并报告为 scored: false，绝不会计为中性 0.5。零个已计分标准的门控通过会以未验证状态关闭该回合并记录日志，而不是根据噪声引导智能体。

技能

skills/graph-verified-coding/SKILL.md 是一个 dsh 技能（也可由 Claude Code 或 Codex 从 ~/.agents/skills 使用），它告诉智能体如何在图工程化的编码流程中使用验证器。七个步骤，每个都有完成条件：契约、切断假边、工作节点、检查（每个节点的确定性检查和浏览器循环）、汇合（对竞争候选执行 verifier_select）、带停止条件的循环、门控与报告（对整个交付物执行 verifier_assess，然后带证据报告）。验证器调用放在值得的位置，即合并之前和最终答案之前，因为每次调用都要以全力思考数分钟。将其链接到 dsh 扫描的技能根目录：

ln -s /path/to/dsh-verifier-gate/skills/graph-verified-coding ~/.dsh/skills/graph-verified-coding

日常
无需启动。门控在每一轮结束时自行运行：通过的轮次会在聊天中无痕关闭（日志显示 PASSED），失败的轮次会收到 [dsh-verifier-gate] 消息并进行一轮修复。预计智能体在最后一个可见步骤之后会忙碌一到七分钟；那是门控在思考。

这些工具在每个会话中都已注册；智能体是否调用它们由技能决定。将你的会话指向它一次（~/.dsh/AGENTS.md 或等效文件：“对于跨多个文件或步骤、存在多种竞争方案或无人值守运行的编码工作，请先加载技能 graph-verified-coding”），智能体便会为此类工作加载它。若要在特定任务上确保生效，请在提示中指明它（“加载 graph-verified-coding，然后构建……”）或使用它的触发词之一：verify、gate、best-of。你也可以直接请求某个工具：“用 verifier_select 生成两个变体并挑选一个”，“用 verifier_assess 对照契约评估结果”。

对于简短的聊天会话，在 settings.yaml 中设置 verifier: backend: reasoningEffort: low 或 none（热重载）；verifier: gate: enabled: false 会保留工具并去掉门控。启用 verbose: true 后，宿主日志（dsh web 终端，或 DSH Desktop 的 ~/Library/Application Support/DSH Desktop/logs/dsh-.log）会显示每次验证器调用及其耗时，以及每轮的门控判定。

开发

类型检查需要在本仓库旁边有一份 DeepSeek Harness 检出（link: 开发依赖指向 ../deepseek-harness）。npm 上已发布的 @deepseek-ai/dsh-* 包是较旧的一代，无法针对当前 harness 通过类型检查。

pnpm install
pnpm run build      # tsc -> lib/
pnpm test           # node:test unit tests

限制

- 端点必须返回 logprobs。没有纯文本的回退路径。
- 分数缓存仅存在于单次 select 调用内部。跨调用没有磁盘缓存。
- 标准集是内置的。自定义标准文件尚未加载。
- 不会追加自定义会话事件，因此会话日志对于没有此插件的进程仍可读。结果通过被引导的消息和 harness 日志记录器可见。

许可证

MIT。评分方法和提示文本移植自 llm-as-a-verifier（llm-as-a-verifier.com，MIT）；参见 LICENSE。感谢作者们公开该方法、提示和基准测试。