逐轮模型路由 YYTbit/dsh-plugin-jev-router

dsh-plugin-jev-router

为 DeepSeek Harness 提供逐轮模型与推理强度路由，由一道 Jev 选择题决定。

为什么需要它

编码智能体把每一轮都发给同一个模型、用同一个推理强度。第 41 轮只是重命名一个变量，第 42 轮要调试一个只在负载下才出现的竞态条件，两轮却按第 42 轮的价格计费。

turn 41 cat src/auth/refresh.ts 读一个文件 turn 42 the refresh test fails about one run in five 在脑子里记住一个交错 turn 43 rename expiresAt to expiresAtMs 机械式修改

第 41 轮和第 43 轮只需要读文件、改名字。按下方的候选表，每轮花 $0.000952，而不是 $0.008352。第 42 轮需要那个交错，应该继续用贵的候选。

基于规则的路由器做不出这种区分。「这一轮难吗？」不是关键词。一条规则去找 test 这个词，会在第 42 轮触发，也会在任何提到测试文件的请求上触发。一条规则去找 rename，能抓住第 43 轮，却漏掉「把 expiresAt 的名字到处都改掉」。每往一个方向加一条规则，另一个方向的准确率就下降，而错误的规则是无声的，所以没人会发现，直到账单或故障找上门。

路由器每轮针对实际配置的候选表，向 Jev 提一道 choice 问题。Jev 用一次前向传播作答，不输出任何 token，所以这次决策只花一次对摘要的传播，摘要上限 4 KB，也不产生补全。答案里带着选中的候选、每个候选的概率，以及一个校准过的置信度。低于置信度门槛的，以及任何失败，都路由到默认候选。

| | 基于规则的路由器 | 永远用贵的模型 | Jev 路由 |
| 决策输入 | 轮次文本里的关键词 | 无 | 针对已配置候选的一道校准选择题 |
| 难的一轮 | 某条规则碰巧匹配就升级 | 正确服务 | 正确服务 |
| 简单的一轮 | 某条规则匹配、且轮次里没有别的东西触发它，就降级 | 过度服务 | 降级 |
| 没见过的措辞 | 需要新规则，而每条规则都有反向风险 | 无影响 | 同一道题就能覆盖 |
| 决策花掉的输出 token | 0 | 0 | 0 |
| 失败模式 | 错误的规则无声且永久 | 预算 | 回退到默认候选 |

安装

dsh plugin --profile your-profile add dsh-plugin-jev-router

npm install dsh-plugin-jev-router

设置一次密钥和端点：

export JEV_API_KEY=...
export JEV_API_URL=https://api.typesafe.ai/v1/systemone # optional, this is the default

工作原理

一轮由第一条命中的规则来路由。
1. 升级。 escalateOn 里有模式匹配到了摘要，于是这一轮已知很难，不再询问 Jev。默认候选的模型以配置的最高 effort 接手，粘性保持重新武装。内置模式覆盖 Python 和 JavaScript 两种形式的堆栈跟踪、AssertionError、失败的测试计数、why does、竞态条件、flaky 与间歇性失败、死锁、迁移，以及跨代码库的重构。
2. 快速路径。 摘要小于 trivialMaxBytes，以只读动词开头，比如 cat、ls、show、grep 或 git diff，并且不含推理标记，比如 explain、debug 或 compare。最便宜的候选接手。推理守卫的作用，就是把 read the failing test output and explain why the assertion fails 挡在快速路径之外。
3. 粘性。 上一轮昂贵的路由仍被保持，于是同一个候选直接服务，不再询问 Jev。升级之后，或 Jev 在比最便宜选项更贵的选项上给出高置信度决定之后，候选会被保持 stickyTurns 轮。保持数递减，对最便宜候选做出决定即释放。快速路径和回退不会动它，所以只读的一轮或降级的端点无法钉住下一轮。由于被保持的一轮会完全跳过 Jev 请求，测试或调试 Jev 路径本身时请设 stickyTurns: 0，否则保持会在你的测试到达客户端之前就给出答案。
4. Jev。 针对候选标签提一个 choice 问题。状态是请求加上近期工具活动的简短摘要，正是这一点让失败的命令输出对决策可见。置信度达到或超过 minConfidence 即采纳该答案。
5. 回退。 低置信度答案、缺失的 key、非 200、超时，或未指明任何选项的响应，都会路由到 defaultCandidate 并记录原因。路由不会让一轮失败。

回执

设置 receiptPath 后，每一轮追加一行 JSON。

{
"ts": "2026-10-03T14:42:58.763Z",
"turn": 1,
"hash": "180adadcfbd4e7eb",
"bytes": 30,
"reason": "jev",
"chosen": "deepseek-v4-fast@low",
"chosenIndex": 0,
"confidence": 0.9,
"distribution": [0.9, 0.05, 0.03, 0.02],
"candidates": [{ "label": "deepseek-v4-fast@low", "effectiveCost": 0.000952 }],
"defaultLabel": "deepseek-reasoner@high",
"latencyMs": 214,
"cost": 0.000952,
"baselineCost": 0.008352,
"error": null
}

回执存的是摘要哈希和它的字节大小，从不存摘要文本，所以日志可以拿去分析而不暴露对话。由于完整分布和每个候选的成本都被记录，换一种成本偏好可以在同样的决策上重新套用，完全不用调用模型，这正是 jev-route replay 做的事。

Jev 传输格式

每一轮路由发一次 POST，沿用其他 Jev 插件的同一族形状。

{
"state": "<turn summary and the candidate table>",
"question": "<the routing instruction>",json
"type": "choice",
"options": [
"deepseek-v4-fast@low",
"deepseek-v4@low",
"deepseek-v4@high",
"deepseek-reasoner@high"
]
}

选择题的候选答案放在 options 里。levels 字段属于评分题，这里不发送。

读取响应时容错处理。probabilities 数组按选项排列、probabilities 对象以标签或索引为键、选中的 choice、option 或 index，以及 { "answer": { ... } } 这类外层包装，最终都归约为同一个答案。置信度按 [0, 1] 区间内的概率读取；如果端点没有报告置信度，就默认取分布的峰值。响应没有指明任何选项时，抛出 malformed，该轮回退。

配置 yaml
- id: jev-router
name: dsh-plugin-jev-router
inject: []
config:

Routing targets. The rates below are example list prices, in USD per

million tokens. Replace them with the rates you are billed.

candidates:
- { model: deepseek-v4-fast, effort: low, costPerMTokIn: 0.07, costPerMTokOut: 0.14 }
- { model: deepseek-v4, effort: low, costPerMTokIn: 0.28, costPerMTokOut: 0.42 }
- { model: deepseek-v4, effort: high, costPerMTokIn: 0.28, costPerMTokOut: 0.42 }
- { model: deepseek-reasoner, effort: high, costPerMTokIn: 0.55, costPerMTokOut: 2.19 }

Accepts a model@effort label, a bare model name, or a list index.

Default: the most expensive candidate, so an undecidable turn is never

under-served.

defaultCandidate: deepseek-reasoner@high

A Jev answer below this confidence routes to the default candidate.

minConfidence: 0.5

Turns a candidate stays pinned after an escalation or an expensive Jev

choice. 0 disables the hold, which is the setting to use when testing or

debugging the Jev path, since a held turn skips the request entirely.

stickyTurns: 1

Extra escalation patterns, appended to the built-in defaults.

escalateOn: []

Extra trivial patterns, appended to the built-in defaults.

trivialPatterns: []

Set false to route with only the patterns given above.

useDefaultPatterns: true

Byte cap for the trivial fast path.

trivialMaxBytes: 240

Byte cap on the summary sent to Jev.

maxSummaryBytes: 4000
endpoint: https://api.typesafe.ai/v1/systemone
apiKey: ''
timeoutMs: 2500
question: ''

Token profile used to turn per-million rates into a per-turn cost.

tokensInPerTurn: 12000
tokensOutPerTurn: 800

JSONL receipt log. Empty disables it.

receiptPath: ''

Inject the current route into the system prompt. Off by default because a

section that changes every turn rewrites the cached prefix.

promptSection: false

Cost weight used by jev-route replay --prefer cheap.

replayCostAversion: 2

配置里没有设置的字段，由环境变量补上。

| 变量 | 字段 |
| JEV_API_URL | endpoint |
| JEV_API_KEY | apiKey |
| JEV_ROUTER_RECEIPTS | receiptPath |
| JEV_ROUTER_CANDIDATES | candidates，JSON 数组 |

命令行 sh jev-route route "cat src/index.ts" jev-route route "the refresh test fails about one run in five" --json jev-route receipts ~/.dsh/jev-router/receipts.jsonl jev-route replay ~/.dsh/jev-router/receipts.jsonl --prefer cheap jev-route replay ~/.dsh/jev-router/receipts.jsonl --prefer cheap --lambda 3 --limit 50 jev-route doctor

route 打印决策结果，以及候选表上的分布。

Reason fast-path
Chosen deepseek-v4-fast@low
Confidence -
Sticky remaining 0 turn(s)
Cost $0.000952 (default baseline $0.008352)

Distribution
[0 ] deepseek-v4-fast@low p= - $0.000952/turn rank 0
[1 ] deepseek-v4@low p= - $0.003696/turn rank 1
[2 ] deepseek-v4@high p= - $0.003696/turn rank 2
[3 ] deepseek-reasoner@high p= - $0.008352/turn rank 3

receipts 汇总日志，给出路由原因分布、回退率，以及相比始终使用默认候选省下的成本。

replay 按另一种偏好重新给已记录的分布打分，并报告哪些轮次的选择会改变。每个可重放的轮次都带有 Jev 给各候选分配的概率，以及各候选的每轮成本，所以重放后的选择是

argmax over i of p(i) - lambda * (cost(i) / cost(max))

--prefer quality 时 lambda 为 0，--prefer cheap 时取配置里的 replayCostAversion。两项都无量纲，落在 [0, 1] 区间，所以 lambda 直接表示一单位相对成本值多少单位概率。从未询问 Jev 的轮次没有分布，保留原选择。

doctor 报告端点、密钥是否存在、端点是否有响应、生效的候选表及其排名、模式计数，以及所有配置警告。密钥缺失或端点无响应时，退出码非零。

所有命令都接受 --config <path>，传入 JSON 对象，字段名与插件配置相同；也接受 --json，输出机器可读结果。

成本

按默认 token 配置档，每轮 12,000 输入 token、800 输出 token，一轮成本为

deepseek-v4-fast@low 12,000 x $0.07/M + 800 x $0.14/M = $0.000952
deepseek-v4@high 12,000 x $0.28/M + 800 x $0.42/M = $0.003696
deepseek-reasoner@high 12,000 x $0.55/M + 800 x $2.19/M = $0.008352

每天 200 轮，其中 120 轮走快速路径，55 轮由 Jev 送到中间候选，25 轮升级或保持默认：

routed 120 x $0.000952 + 55 x $0.003696 + 25 x $0.008352 = $0.5263/day
always default 200 x $0.008352 = $1.6704/day
always mid 200 x $0.003696 = $0.7392/day
路由相比始终使用默认基线，每天省下 $1.1441，即 68.5%；相比始终使用中档基线，每天省下 $0.2129，即 28.8%。节省幅度受限于能脱离默认档的轮次占比，而与始终中档的对比才是诚实的下限，因为在路由判断出错的那些轮次上，该配置本身就已经比路由后的混合更便宜。每次路由决策会多跑一次 Jev 前向传播，输入是一段上限 4 KB 的摘要，大约 1,000 个输入 token，没有输出 token。在你自己的日志上运行 jev-route receipts，得到匹配你实际流量的数字，而不是照搬这个示例。

Harness 集成

插件在宿主上下文的三处完成注册。

- ctx.jevRouter 始终接收路由实例。分发层调用 await ctx.jevRouter.routeTurn(summary)，再读取 decision.candidate.model 和 decision.candidate.effort。
- ctx.shellEnv 为当前轮次发布 DSH_JEV_ROUTER_MODEL、DSH_JEV_ROUTER_EFFORT、DSH_JEV_ROUTER_REASON 和 DSH_JEV_ROUTER_RECEIPTS。
- 预分发钩子按 ctx.dispatch.before、ctx.model.beforeDispatch、ctx.turn.before 的顺序探测。第一个接受处理器的槽位会拿到处理器，选中的槽位写入插件日志。构建这个插件时所依据的 harness 接口没有暴露模型选择钩子，所以探测通常报告没有可用槽位，日志会提示改用 ctx.jevRouter 驱动路由。等官方钩子名字出现时，只需把它加进 src/index.ts 里的 DISPATCH_SLOTS。

routeTurn 以自由函数形式导出，所以 harness 完全不加载插件也能路由。
ts
import { routeTurn } from 'dsh-plugin-jev-router'

const decision = await routeTurn(
{ request: 'rename expiresAt to expiresAtMs', digest: 'tool: grep expiresAt src/ (12 hits)' },
[
{ model: 'deepseek-v4-fast', effort: 'low', costPerMTokIn: 0.07, costPerMTokOut: 0.14 },
{ model: 'deepseek-v4', effort: 'high', costPerMTokIn: 0.28, costPerMTokOut: 0.42 },
{ model: 'deepseek-reasoner', effort: 'high', costPerMTokIn: 0.55, costPerMTokOut: 2.19 },
],
{ defaultCandidate: 'deepseek-reasoner@high' },
)

console.log(decision.candidate.model, decision.candidate.effort, decision.reason)

自由函数无状态。JevRouter 在此之上加了粘性保持、回执日志和实时指标，并在选项里或作为第二个参数接受 client，方便调用方自带。

相关项目

- metajev —— 这个插件每轮所做的事的通用形式。决策以状态、问题和模型为键；阈值与路由放在一份读取记录的策略里，所以改偏好不花任何模型调用。
- dsh-plugin-jev-compaction —— 同一个上下文问题的另一端。这个插件决定哪一模型服务某一轮；那个插件决定哪些消息能活下来送到模型面前。
- dsh-plugin-meta-memory —— 为 DeepSeek Harness 提供结构化长期记忆

许可证

MIT —— YYTbit