前言¶
做智能体开发常会遇到这样的任务批次：一条是 17×23 的口算，一条要写代码、验证素数，另一条是长文翻译。全部丢给同一个模型，简单任务在旗舰模型上排队，浪费时间和 token；难题交给便宜模型又容易做错。逐个任务手动挑模型，任务一多就维护不动。
dsh-swarm-router 处理的就是这个问题：把一批异构任务组织成「子智能体矩阵蜂群」——任务是行、候选模型是列，路由器为每一行选中一格，再通过 DSH 的 ctx.subagents 把每一格变成绑定到所选模型的进程内子智能体并行下放。
这是什么¶
dsh-swarm-router 是 GitHub 用户 r600a-code 维护的 DSH 插件，当前版本 0.2.0，MIT 许可证。一句话定位：把每个任务路由到最合适的模型（OpenRouter 类网关 + cfgpu.com/llm/square 目录），并以进程内子智能体（或直接 ctx.llm 调用）绑定所选模型并行分发。
在 DSH「一切皆插件」的体系里，它以 dsh.bundle 清单打包：package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml。补丁新增 cfgpu-swarm、openrouter 两条独立的 LLM 路由，而不是改动机器原有的 cfgpu 配置，因此蜂群的模型目录不会干扰编排者自己的模型。
路由器怎么选模型¶
任务结构是 { id, kind, prompt, maxTokens? }，其中 kind ∈ {reasoning, coding, longcontext, fast, general}。路由是纯函数，每个任务 O(1)——它不花任何模型时间来决定「用哪个模型」，省下的开销全部投入并行分发。选模型分五步：
1、推断 kind：显式给出的 kind 优先；否则按 {reasoning, coding, longContext, fast} 的顺序取第一个非空提示；都没有就归为 general。
2、能力硬过滤（capability gate）：缺能力标签的模型直接记 −∞ 剔除。reasoning 要求 reasoning 标签，coding 要求 coding，longcontext 要求 longContext；fast 和 general 不设门槛。
3、按任务类型加权打分：对幸存模型，用目录里的 1–10 分评级（strength、speed、cost）和容量（contextWindow、maxTokens）算线性分：
| kind | 打分公式 |
|---|---|
reasoning |
reasoning×3 + strength×2 + coding×0.3 + contextWindow×0.000004 |
coding |
coding×3 + strength×2.5 + longContext×0.3 |
longcontext |
contextWindow×0.00002 + strength×0.5 + coding×0.3 |
fast |
speed×3 + cost×1.5 + strength×0.3 |
general |
strength×2 + speed×0.6 + cost×0.3 + coding×0.3 |
4、不对称惩罚：kind 不是 fast 而模型属于 fast 档，−2.0；general 任务撞上推理旗舰，−2.0（性能过剩，更慢也更贵）；coding 任务撞上推理模型，−0.5；目录采集期间路由不稳定的模型（unstable），−4；不可用的模型（例如没配 key 的 OpenRouter），−1000。开启 useRankings: true 时叠加排名反馈：成功率 ≥ 0.9 且试验数 ≥ 3 加 +1.5，成功率 ≤ 0.4 减 −3.0。
5、择优并解释：得分最高者胜出；平分时先比 strength、再按 id 字典序，结果确定。工具返回胜者，以及前 5 名候选的得分和可读的取舍理由。
这些数字是非对称的，而且是刻意的：在质量型任务上奖励便宜，正是这套设计要规避的失败模式。fast 惩罚与推理过剩惩罚（各 −2.0）大到足以翻转平局，又小到让真正强的便宜模型仍能在 general 上凭实力胜出；排名加成的幅度（+1.5/−3.0）小于静态惩罚，模型必须先跑出真实的好成绩，反馈才有资格覆盖目录评级。
核心能力¶
1、模型聚合注册表 + PR 流程：models/registry.json 是规范目录；scripts/validate-registry.mjs 校验结构，可直接接入 CI；CONTRIBUTING.md 记录了新增模型的 PR 流程。
2、插件扩展点：插件通过 ctx.provide('swarmRouter', api) 对外暴露 API。其他插件声明 inject: ['swarmRouter']，即可注册运行时模型、自定义任务类型、订阅反馈事件、读取排名与用量。
3、真实任务反馈与排名：swarm_feedback 记录 {correct, quality 1-5} 并持久化到 rankings.json；swarm_ranking 按模型、按任务类型展示成功率与质量分。实证表现好的模型在路由中被加权，表现差的被降权——静态目录评级只是作者的估计，真实任务结果才会覆盖它。
4、Token 消耗统计：direct 模式从 ctx.llm.stream 的 usage 块精确捕获每次调用的 prompt/completion/total（含 cfgpu 的 reasoning_tokens，若适配器输出）；subagent 模式通过全局 llm/stream 监听器捕获，按 sessionId == 子运行 id 归因到具体子智能体。数据持久化到 usage.json，swarm_stats 展示汇总、按 provider、按模型、按任务类型的明细，并附带 cfgpuHighlight 高亮。
工具一览¶
| 工具 | 模式 | 是否调用模型 |
|---|---|---|
swarm_route_preview |
— | 否，纯路由预览 |
swarm_dispatch |
subagent（默认）| direct |
是，并行调用 |
swarm_models |
— | 否，列出注册表 |
swarm_feedback |
— | 否，记录一次结果 |
swarm_ranking |
— | 否，读取累计反馈 |
swarm_stats |
— | 否，读取累计用量 |
「决定」与「执行」是分开的：先用 swarm_route_preview 不花一个 token 就能看到完整路由方案，确认后再用 swarm_dispatch 真正分发。subagent 模式走完整的智能体循环；direct 模式是一次性 ctx.llm.stream 调用，适合需要精确 token 记账的场景。
安装与启用¶
默认安装到 DSH_HOME（默认 ~/.dsh，需其中已有 cfgpu 凭据）：
dsh plugin --profile headless add github:r600a-code/dsh-swarm-router
验证安装是否生效，检查配置里是否出现 cfgpu-swarm 与 swarm-router：
dsh --profile headless --dump-config | grep -E 'cfgpu-swarm|swarm-router'
如果想与 ~/.dsh 隔离，可以先准备一个工作区级的 DSH_HOME，放入含 CFGPU_API_KEY 的 .credentials.yaml 和 settings.yaml，再从本地路径安装：
export DSH_HOME=/path/to/.dsh-home
dsh plugin --profile headless add /path/to/dsh-swarm-router
凭据要求：cfgpu 路由需要 $DSH_HOME/.credentials.yaml（或环境变量）中有 CFGPU_API_KEY；OpenRouter 路由需要 OPENROUTER_API_KEY，缺失时路由器会报告其不可用且绝不向其分发，profile 仍可正常启动。另外，package.json 的 peerDependencies 声明了 5 个 @deepseek-ai/* 包（cordis、dsh-tools、dsh-agent、dsh-llm、dsh-subagent），均为必选。
典型用法：跑一次内置基准¶
benchmark/benchmark.json 是最小基准集：5 个便宜、异构的任务，覆盖 fast/reasoning/coding/general。成功以内容判定（期望答案子串 / CJK），而不是运行完成就算数。
subagent 模式，5 个任务：
dsh --profile headless "$(cat benchmark/benchmark_prompt.txt)"
node benchmark/verify_benchmark.mjs # 27/27 green
direct 模式，3 个任务：
dsh --profile headless "$(cat benchmark/benchmark_direct_prompt.txt)"
node benchmark/verify_benchmark.mjs benchmark_direct_RESULT.json # 31/31 green
README 记录的结果：subagent 模式 5 个任务路由到 4 个不同的真实 cfgpu 模型且全部正确（17×23=391、bat-ball=0.05、真实的 is_prime、CJK 翻译、widgets=5）；direct 模式 3 个任务逐任务精确捕获了 token 消耗。一批任务分散到多个模型，distinctModels 汇总正是「路由在起作用」而非收敛到单模型的信号。
适用场景与注意¶
适合三类人：手头经常有难度差异大的任务批次、想按难度匹配模型的 DSH 用户；想积累真实任务反馈、让路由随使用变准的团队；以及想复用注册表和排名的其他插件开发者。想深入设计细节，仓库里有正式的设计文档 docs/PAPER.zh.md。
使用前注意：
1、插件以当前 dsh 进程的权限运行，安装前请自行检查源码与许可证（MIT）。
2、cfgpu 路由没有 CFGPU_API_KEY 就无法工作，安装前先把凭据放进 $DSH_HOME；OpenRouter 缺 key 只会导致该路由不可用，不影响启动。
3、基准数字以仓库 README 记录为准：subagent 校验 27/27，direct 校验 31/31。
小结¶
dsh-swarm-router 的思路可以概括成三步：把「选模型」做成零成本的纯函数，把「执行」交给并行下放的子智能体，再用真实任务反馈把静态目录修正成自己的排名。对经常跑异构任务批次的 DSH 用户来说，这是一个可以直接上手的路由方案。
- GitHub 仓库：https://github.com/r600a-code/dsh-swarm-router
- 社区目录页：https://www.skillhub.cn/plugins/r600a-code/dsh-swarm-router
