dsh-swarm-router

English | 中文

A DeepSeek Harness bundle that turns a batch of heterogeneous tasks into a sub-agent matrix swarm: it routes each task to the most suitable model from an OpenRouter-like gateway plus the cfgpu.com/llm/square catalog, then dispatches each assignment in parallel as a real in-process subagent (or a direct ctx.llm call) pinned to that model — quick tasks land on fast/cheap models, hard tasks on strong reasoning models. A formal design write-up lives in docs/PAPER.md.

子智能体矩阵蜂群：任务是行、候选模型是列，路由器为每一行选中一格，再通过 DSH 的 ctx.subagents 把每格变成一个绑定到所选模型的子智能体并行下放，按任务难度匹配模型、省时提效。论文见 docs/PAPER.zh.md。

The four contributions

	Contribution	What
①	Model aggregation registry + PR flow	models/registry.json is the canonical catalog; scripts/validate-registry.mjs enforces structure (CI-ready); CONTRIBUTING.md documents the add-a-model PR flow.
②	Plugin extension point	ctx.provide('swarmRouter', api) — other plugins inject: ['swarmRouter'] to register runtime models, custom task kinds, subscribe to feedback, read rankings/usage.
③	Real-task feedback + ranking	swarm_feedback records {correct, quality 1-5}, persisted to rankings.json; swarm_ranking shows per-model/per-kind success rate & quality; proven models are boosted in routing, failing ones demoted.
④	Token-consumption statistics (cfgpu highlighted)	direct mode captures exact per-call prompt/completion/total from ctx.llm.stream; subagent mode captures via a global llm/stream listener attributed by sessionId; persisted to usage.json; swarm_stats shows totals/byProvider/byModel/byKind + cfgpuHighlight.

Tools

Tool	Mode	Calls models?
swarm_route_preview	—	No (pure routing plan)
swarm_dispatch	subagent (default) | direct	Yes (parallel)
swarm_models	—	No (list registry)
swarm_feedback	—	No (records an outcome)
swarm_ranking	—	No (reads accumulated feedback)
swarm_stats	—	No (reads accumulated usage)

The router rules (how a task becomes a model)

A task is { id, kind, prompt, maxTokens? } where kind ∈ {reasoning, coding, longcontext, fast, general}. The router is pure and O(1) per task — it spends zero model-time deciding which model; the saving goes into parallel dispatch.

Step 1 — infer the kind. An explicit kind wins; otherwise the first truthy hint among {reasoning, coding, longContext, fast} is used, defaulting to general.

Step 2 — capability gate (hard filter). Each kind requires a capability tag; a model lacking it scores -∞ and is dropped:

• reasoning requires reasoning; coding requires coding; longcontext requires longContext; fast/general require nothing.

Step 3 — effort-matched weighted score. For the surviving models, a kind-specific linear score is computed from the catalog's 1–10 ranks (strength, speed, cost) and capacities (contextWindow, maxTokens):

kind	weight vector
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

…