thedeveloper256/dsh-model-router

dsh-model-router

一个用于 DeepSeek Harness 的小型插件，它不再把每次模型调用都一视同仁。它把你的会话拆分成两个角色：

- 规划者（planner）——你的主智能体——默认使用 deepseek-flash（V4.1 Flash，原生多模态）。思考就发生在这里：理解你的意图、设计方案、审查结果、撰写最终答案。
- 执行者（executor）——它委派给的每个子智能体——同样默认使用 deepseek-flash。

在 V4.1-Pro 发布之前，两个角色共用同一个模型（V4.1 Flash 在性能、成本和速度上已经胜过 V4-Pro，因此 DeepSeek 正在淘汰 deepseek-v4-pro / deepseek-v4-flash / deepseek-v4-flash-vision-exp——这三者现在在服务端都路由到 V4.1 Flash）。角色拆分保留在配置中，所以以后要把规划者切回 Pro 只需改一行。你依然保持谨慎的规划/委派/审查节奏，而不必为每次工具调用都支付 Pro 的价格。

安装

把它添加到一个 profile 中（这里安装到 web profile；换一个名字即可安装到其他 profile）：

dsh plugin --profile web add dsh-model-router

这会从 npm 拉取，npm 上发布的是预构建版本——无需构建步骤。

更喜欢源码？用 git 安装也可以，但 pnpm 会在本地克隆并构建，并且会要求你批准一次构建脚本（把它打印出的 allowBuilds 键添加到该 profile 的 pnpm-workspace.yaml 中，然后重新运行）：

dsh plugin --profile web add git+https://github.com/thedeveloper256/dsh-model-router

安装完成后，重启该 profile。你应该能在 dsh web --dump-config 中的 model-router 下看到这一行。

它实际做了什么

三个小接口，一条规则：

1. 请求路由——每个模型请求都会被标记一个角色。根智能体获得规划者路由；委派子级（subagent、subagent_fork、workflow worker、ralph 轮次）获得执行者路由。在 V4.1-Pro 发布之前，两者都默认使用 deepseek-flash（V4.1 Flash），所以如今标记是统一的，而角色拆分仍可配置。重写位于请求流水线的最外层，因此它会生效——甚至优先于 harness 自身的默认模型，也优先于你在 UI 中为该会话选择的任何模型。这是有意为之：它就是那个“强制”旋钮。
2. 一个提示词片段——一段简短的说明，渲染在智能体人设之前，告诉规划者：你是思考者，把实现委派出去。没有这个，模型往往会自己把所有事情都做了。
3. 一个技能——pro-flash-routing 技能会出现在会话的技能目录中，并阐明工作节奏：规划、委派、审查、汇报。同样的约定，但可在智能体需要细节时按需加载。

角色是如何判定的

如果某个智能体带有 harness 在委派子级上标记的任一标记，它就是一个执行者：

- options.subagentDepth >= 1，或
- session.header.origin === "subagent"
其余的一切都是规划器。该逻辑以普通函数的形式存在于 src/policy.ts 中，因此易于推理和测试。

路由器会覆盖什么、不会覆盖什么

路由器始终会标记 provider + model。reasoningEffort 和 maxTokens 是按角色可选的：在配置中设置它们，它们就会对该角色强制执行；不设置它们，这些字段就会继承你会话中所选的设置。因此，在 UI 中选择“最大努力”但不在配置中固定 reasoningEffort，仍然会得到最大努力的思考——只是它发生在被路由的模型上。

关闭路由器

路由默认开启。有两种方式可以关闭它：

- GUI（Settings → Plugins → Model router）： 该插件会注册一个实时
设置区域；将 enabled 关闭即可。它会立即生效（无需重启），
持久化在 settings.yaml 的 model-router: 下，并且还会注销提示词
区域和技能。重新开启后，一切都会恢复。同一张卡片还承载
Vision 开关（v0.6.0+，见下文）。
- Patch 行： 在配置文件的 cordis.patch.yml 行中设置 enabled: false
（在下次启动时生效）。disabled: true 仍会完全跳过该行。

关闭路由器后，请求会使用会话中所选的模型（你的
agent-default-model 设置或基础默认值）——路由器只是不再
重写它们。

GUI 开关（v0.5.0+）

自 v0.5.0 起，该包附带一个浏览器端部分，并且 harness 会自动
提供它——无需额外配置。在安装（或更新到）v0.5.0+
并重启配置文件后，Settings → Plugins 会显示一张 Model router
卡片，其中有一个实时的 Enabled 开关、一个“Overridden”徽章，以及在你更改后出现的 Reset to
default 按钮、当前 planner/executor 路由和模式的只读视图，还有一个 Vision 区域（v0.6.0+），其中带有它自己的
实时 Vision 开关、Reset vision to default 按钮，以及只读的
vision-model 行。拨动开关会立即生效（无需
重启），并持久化在 settings.yaml 的 model-router: 下——这与
上文所述的 GUI 开关使用的是同一机制。

一个 harness 范围内的注意事项（它适用于所有设置页面——Models、
Plugins、一切——而不是专门针对此插件）：harness 仅向 loopback 浏览器（localhost / 127.x）提供
设置页面。远程
浏览器可能根本获取不到设置页面；在卡片确实渲染出来的地方，它会
显示一条只读说明。在任何地方都可用的回退方案：

- Patch 行——在配置文件的 cordis.patch.yml 中设置 enabled: false
（在下次启动时生效），或者
- settings.yaml——在配置文件所使用的设置文件中的
model-router: { enabled: false } 下添加；这会实时生效，与 GUI 相同。

Vision 路由（v0.6.0+）

自 v0.6.0 起，路由器还可以处理带图像的请求。*它是选择加入
且默认关闭的（vision.enabled: false）。有两种方式可以开启它：

- GUI： 在同一张 Model router 卡片上，拨动 Vision 开关（实时，
无需重启，持久化在 settings.yaml 中），或者
- Patch 行 / 设置： 在插件的配置中设置 vision.enabled: true。

启用后，只要会话日志携带图像，期间发送的任何请求都会被标记为
视觉模型——默认是来自 deepseek-official 的 deepseek-flash
（V4.1 Flash 原生支持多模态，因此除非你另行指定，否则这与角色路由一致）
——来自所有角色：根（规划器）智能体以及所有委派的
子智能体。其他一切保持 pro/flash 角色路由不变。
视觉分支会优先检查，因此读取图像的子智能体仍会落到
视觉模型上，而不是 flash。可选的 vision.reasoningEffort /
vision.maxTokens 固定设置与各角色的设置完全一样。图像检测
读取会话事件日志（user/message、assistant/message 以及
tool/result，包括嵌套在 tool-result 块中的图像）：一旦图像
出现在日志中的任何位置，后续请求在本次会话剩余时间内都会停留在视觉模型上
（粘性——图像会一直留在请求上下文中，直到压缩或修剪将其丢弃）。检测
形态已对照真实会话日志验证：user/message 在 data.content 处携带图像，而
assistant/message 和 tool/result 在 data.message.content 处携带图像
（工具结果将其嵌套在 tool-result 块内）。可能的后续工作：
可选的 vision.historyLimit 用于将扫描范围限制在末尾 N 个事件
（未设置则保持当前的粘性全日志扫描）。

该插件在其自有的 cordis.patch.yml 中提供支持：

- 在 llm-deepseek 行上为 deepseek-flash 添加一个目录条目（带有
inputModalities: [text, image]、contextWindow: 1000000、maxTokens:
384000），以及已退役的 deepseek-v4-flash / deepseek-v4-pro /
deepseek-v4-flash-vision-exp id，在过渡期间保留为兼容别名，并且
- 提高 attachment-local 图像准入限制，以便普通截图
（约 8K、15MB）能够附加而不被拒绝（maxImageDimension: 8192、
maxImagePixels: 100000000、maxImageBytes: 15728640）。

两者都是默认值，你可以在配置文件的 cordis.patch.yml 中覆盖——
配置文件层在插件层之后应用，因此配置文件中针对
llm-deepseek 或 attachment-local 的 patch: 会生效。仍有一项硬性要求：
视觉模型必须存在于目录中并具有图像输入模态，否则提供方会在调用时
以 UNSUPPORTED_CONTENT 拒绝请求——随附的目录行正是满足该要求的内容。

调优

所有配置都位于插件行上。在配置文件的 cordis.patch.yml 中对其进行 patch：

- patch:
- id: model-router
config:
planner:            # 根智能体路由（在 V4.1-Pro 发布前为 deepseek-flash）
provider: deepseek-official
model: deepseek-flash
reasoningEffort: high   # off | low | high | max（省略则继承）
maxTokens: 8192         # 输出上限（省略则继承）
executor:           # 子智能体路由
provider: deepseek-official
model: deepseek-flash
reasoningEffort: high
escalateOnError: true   # 在一个步骤失败后……
escalateTo: max         #   ……为下一个请求提升 effort
recoverySteps: 2        #   ……在 N 个干净步骤后消退
mode: strict        # strict | plan（见下文）
promptSection: true # 注册始终启用的路由部分
skill: true         # 注册 pro-flash-routing 技能

mode 控制根 agent 的处理方式：strict 让它始终保持在 planner 路由上；plan 会将根 agent 发送到 executor 路由，除非 plan 模式处于活动状态，从而将 pro 保留给真正的规划。

错误驱动的升级（escalateOnError）：当某个路由的 agent 遇到失败的工具步骤时，下一个请求会提升到 escalateTo，并在 recoverySteps 个干净步骤后消退。它是确定性的且无状态的——路由器按请求折叠会话日志，因此只考虑先前的步骤（失败无法升级导致它的那个请求本身）。这是一个按路由的开关：在 executor 上启用它，让 flash 在一次搞砸的执行步骤后更努力地思考，而不影响基线。

默认值正是本页顶部的列表。要为某个会话关闭路由器，请禁用该行（disabled: true）或移除插件——dsh plugin --profile web remove dsh-model-router。

减少 token 使用量

在两个角色都使用 deepseek-flash 的情况下，账单已经远低于旧的基于 pro 的设置——剩余的大部分节省来自缩减开支：

- 降低 reasoningEffort。 框架默认以 max 运行，这会产生大量推理 token。在某个路由上使用 high（或 low）能以一小部分成本保持大部分质量。
- 限制输出，在 planner 路由上使用 maxTokens，这样冗长的回合就不会膨胀。
- 将 planner 路由保留给规划，使用 mode: plan——简单的问答和执行型回合不再触及 planner 路由（一旦 V4.1-Pro 落地且路由拆分，这一点又会变得重要）。
- 保持 planner 的上下文精简。 在推理之后，输入 token 占主导。积极委派并信任子 agent 的报告；不要在 planner 上重新读取大文件或完整记录。使用有针对性的读取，并让自动压缩（/compact）裁剪历史记录。
- 调整宿主 pruner。 工具结果 pruner 会在过大的结果到达模型之前将其截断（默认约 8 KB）；降低 tool-result-pruner → thresholdChars 会裁剪更多 planner 输入。那是框架配置，不是本插件的行。
- 利用 DeepSeek 的上下文缓存。 重复的前缀会以大幅折扣从缓存中提供，因此在回合之间保持系统提示和对话前缀稳定。

前三项是本插件行上的一行更改；后三项是纪律和宿主调优。

它有效吗？
对照真实会话日志进行验证。运行一个让 agent 规划并委派的任务，然后检查实际发起请求的是哪些模型：

zstd -d -c "$DSH_HOME"/sessions///session.jsonl.zstd \
| grep '"type":"assistant/message"' \
| grep -o '"model":"deepseek-[a-z-]"' | sort | uniq -c

该命令中有两个细节很重要：过滤 assistant/message 只统计真实的模型响应
（原始日志还会记录 request/header、会话标题和网页搜索调用，这些会虚增
计数），而 [a-z-] 模式会保留带连字符的模型名称
（deepseek-flash、旧版 deepseek-v4-flash-vision-exp）完整无损——单纯的
[a-z] 会悄悄截断它们。

自 v0.7.0 起，两个角色都记录 deepseek-flash（在 V4.1-Pro 落地且
planner 路由指向它之前保持统一）。作为参考，v4 时代的分工已对照生产日志
重新验证：一个带委派的根会话显示 170 个 pro / 182 个 flash 响应，而每个子会话
（delegationDepth >= 1）只显示 flash；启用视觉路由后，一个图片密集的会话记录了 508 个
deepseek-v4-flash-vision-exp 响应。

一条运维注意事项：路由重写是在 harness 启动时加载的。更新插件后（例如
0.6.3 → 0.7.0），请重启 profile——在更新期间持续运行的会话可能会继续按
旧代码运行，直到进程重新加载。

开发

这是一个普通的小型 TypeScript 包——没有框架魔法：

npm install
npm run typecheck
npm test
npm run build

prepare 脚本会自动构建 lib/，这正是让 git 安装无需在仓库中附带构建产物
就能工作的原因。package.json 中的 dsh.bundle 字段告诉
dsh plugin 如何将插件组合进 profile。

发布

仅推送 tag 并不会产生一个 release。每个版本都需要以下全部四项：

npm run typecheck && npm test && npm run build  # 先全部通过
git tag vX.Y.Z && git push origin main && git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z" --notes ""
npm publish --access public  # 需要登录 + 2FA（--otp）或发布 token

在回填旧版本时，请将 vX.Y.Z 标记为 Latest（gh release edit vX.Y.Z --latest）。注意：scripts/publish.sh 是用于全新仓库的一次性引导脚本，不是每次发布所用的路径。

许可证

MIT