前言¶
做智能體開發常會遇到這樣的任務批次：一條是 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
