dsh-agentic-router

🌐 语言切换 / Language: 简体中文 · English

DeepSeek Harness（DSH）插件：学习型智能路由（agentic router）+ 数据飞轮。

每回合开始时（agent/inbox/claimed）按任务类型与复杂度把请求路由到最合适的模型档位； 四个专家并行推荐、EXP3 元选择器决定听谁的；每回合按质量代理信号 （工具失败、模型重试、成本、延迟）计算奖励并回传，路由策略随使用越学越准。 全部决策与奖励落盘，可审计、可重放。

v1.4.0 起切换真实生效：v1.3.0 及之前通过 agent/request 返回替换后的配置切模型， 但该返回值会被 DSH 内置的模型选择监听器强制改回，实际不生效；v1.4.0 改为在回合开始 向会话日志追加 request/header 事件（reason: router），走 DSH 官方模型选择优先级链 （本进程选择 → 会话日志最新 header → 默认模型）真实切换。

v1.5.0 步骤级路由：在回合级基线之上，agent/pre-step 按上一步的工具调用做 步骤级调整——重型工具（写代码/执行/子 agent 等，见 HEAVY_TOOLS）→ 下一步升级 strong （pro）；轻量/纯文本 → 回到回合基线档。实现"简单步骤 flash、复杂步骤 pro"的近似形态 （步骤切换对下一步生效，一阶延迟）。步骤级决策落盘 steps.jsonl，agentic_router_stats 可见 stepSwitches 与 stepLog。

架构

用户输入 → 分类(规则,<1ms) → 四专家推荐 → EXP3 元选择 → request/header 追加(真实切换)
                                        ↑                        │
                 UCB/LinUCB/k-NN/EXP3 更新 ← 质量代理奖励 ← 回合收尾(工具失败/重试/成本/延迟)

设计细节与路线图见 docs/DESIGN.md。

安装

dsh plugin --profile web add dsh-agentic-router

--profile 必填。安装后重启 Web，工具 schema 才会进入 prompt 组装。

切换到真实切换（active）

默认是 shadow 模式（只记录与学习，不切换模型）。切到真实切换，最省事的方式：重启后在任意 DSH 会话里对 agent 说：

把 agentic router 切成 active 模式

agent 会调用 agentic_router_set_mode（mode=active），并把模式持久化到 ~/.dsh/storages/dsh-agentic-router/policy.json——重启后依然 active，无需每次设置。

也可以不走会话、首次启动即 active：在 profile 的 cordis.patch.yml 里给 agentic-router 条目加配置：

- id: agentic-router
  config:
    mode: active

（两种方式选其一；一旦用工具存过模式，policy.json 的取值优先于 config.mode。）

切换机制（v1.4.0）

DSH 的 agent 每步请求最终由模型选择逻辑决定，读取优先级为：

本进程选择 → 会话日志最新 request/header → 默认模型

• 直接改 agent/request waterfall 的返回值：会被 dsh-agent 自带监听器强制改回「选定模型」——无效（v1.3.0 及之前的缺陷）
• 改 llm/stream：agent-loop 请求到达时已深度冻结，无法改写

v1.4.0 的正确做法：在 agent/inbox/claimed（回合开始、prompt 组装之前）向会话日志追加 request/header 事件，下一轮组装自然读到新模型。agent/request 只做只读观测 （记录每步真实出网模型）；插件中途热加载时由 llm/stream 在循环自身 header 落盘后补一次应用。 切到 fast/mid 档会去掉 reasoningEffort，让目标模型走自身默认 effort。

工具

数据飞轮（落盘）

目录：${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router/（AGENTIC_ROUTER_HOME 可覆盖）

• decisions.jsonl — 每条决策：任务类型/复杂度/四专家推荐/元层选择/实际路由/是否切换
• rewards.jsonl — 每条奖励：明细（工具失败/重试/延迟）+ 特征向量，重启后重放恢复学习状态；人类反馈结算（feedback-settle 行）在重放时精确修正
• 人类反馈：回合结束 45s 后查询 messageFeedback（Web UI 的 👍/👎），点踩 −0.5、点赞 +0.1，修正已应用的奖励（UCB 均值/EXP3 权重精确回退）
• policy.json — 模式与强制模型（原子写）

奖励公式：干净收尾 1 分起，工具失败 −0.2/次（封顶 0.6）、模型重试 −0.2/次（封顶 0.4）、 成本 min(0.5, 20×回合成本元)、延迟 >30s −0.1 / >90s −0.3；出错回合记 0。

成本信号（token 计费）：透传 llm/stream，累加每个模型调用的 usage chunk （输入/输出/缓存读/推理 token）；无 usage 的 provider 按文本长度估算（标 estimated）。

价格表三级解析（元/百万 token）：provider→model 精确价 > provider→档位 价 > * 通用档位 > 保守兜底。未知 provider 绝不套用 DeepSeek 价格，用通用档位并标记 pricingSource（审计字段）。默认含 DeepSeek 官方口径，接入其他模型用 agentic_router_set_prices 工具配价（持久化到 policy.json），或安装时传 config.prices：

{ 'deepseek-official': { 'deepseek-v4-pro': { in: 1, out: 12 } },
  openai: { 'gpt-x-pro': { in: 15, out: 60 } },
  '*': { fast: { in: 1, out: 4 }, mid: { in: 2, out: 8 }, strong: { in: 3, out: 16 } } }

分类器（规则先验，<1ms）

6 类任务（code/write/summarize/research/agentic/qa）+ 复杂度 0~1： 类型先验分（code/agentic 0.3，research 0.2，write 0.15…）+ 长度 + 代码块 + 复杂词加分 − 简单词减分（"简单/复杂"同时出现不惩罚）。

已知边界

• 模型档位靠 id 关键词识别（flash→fast、pro→strong）；可用模型多于一档时路由才真正切换
• 反馈结算窗口 45s（可配置 settleDelayMs），窗口内无反馈按代理奖励结算；重启会丢失未结算的 pending 条目；晚到的反馈可能归属到其后的回合
• 反馈依赖部署的 Web UI 实际产生数据（本插件只读取，不写入）
• 毕业策略（LinUCB/k-NN）需要数十个回合样本才会进元层池

开发、测试与发布流程（维护者）见 docs/MAINTAINING.md。

License

MIT