前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在多模型编排场景中，如何根据任务类型和复杂度自动选择最优的模型档位，是一个典型的工程问题。dsh-agentic-router 插件旨在解决这一问题，它通过引入多专家推荐与元选择机制，结合基于质量信号的奖励系统，实现路由策略的自动学习与优化。
安装¶
安装插件需要指定 DSH 的 profile。
dsh plugin --profile web add dsh-agentic-router
安装后需要重启 Web 服务，工具的 schema 才会进入 prompt 组装流程。
核心功能¶
路由架构¶
插件采用四专家并行推荐 + EXP3 元选择器的架构：
* 四个专家：rule（规则先验）、UCB（多臂老虎机）、LinUCB（线性上下文）、k-NN（最近邻）。
* EXP3 选择器：在回合开始时根据四个专家的推荐做出最终决策。
* 数据飞轮：每回合结束时，根据质量代理信号（工具失败、模型重试、成本、延迟）计算奖励并回传，更新策略权重。
模型真实切换 (v1.4.0+)¶
v1.4.0 修复了之前版本无法真实切换模型的缺陷。现在通过在 agent/inbox/claimed 阶段向会话日志追加 request/header 事件（reason: router），配合 DSH 的模型选择优先级链（本进程选择 → 会话日志最新 header → 默认模型），实现真实模型切换。
步骤级路由 (v1.5.0)¶
v1.5.0 引入了步骤级路由。在 agent/pre-step 阶段，插件会检查上一步调用的工具类型：
* 重型工具（如写代码、执行、子 agent）：在下一步升级到 strong 档位。
* 轻量/纯文本工具：回落到回合级设定的基线档位。
这种调整仅对下一步生效，数据落盘至 steps.jsonl。
工具集¶
插件提供了以下工具用于控制与观测：
* agentic_router_stats：查看决策记录、四专家推荐、EXP3 权重、飞轮状态。
* agentic_router_set_mode：切换模式（shadow/active/off）。
* agentic_router_force：强制指定模型 ID（active 模式下生效）。
* agentic_router_reset：清空飞轮学习状态。
* agentic_router_set_prices：配置模型价格。
配置与使用¶
模式切换¶
默认为 shadow 模式（只记录与学习，不切换模型）。可通过以下方式切换到 active 模式（真实切换）：
1. 会话内切换：在任意 DSH 会话中输入“把 agentic router 切成 active 模式”，插件会调用 agentic_router_set_mode 并持久化到 ~/.dsh/storages/dsh-agentic-router/policy.json。
2. 配置文件切换：在 profile 的 cordis.patch.yml 中配置：
- id: agentic-router
config:
mode: active
档位识别¶
模型档位通过模型 ID 的关键词识别：
* flash / fast：路由到 fast 档。
* pro / strong：路由到 strong 档。
* 其他：默认为 mid 档。
数据飞轮¶
数据落盘¶
所有决策与奖励落盘在 ${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router/ 目录：
* decisions.jsonl：记录每条决策的任务类型、复杂度、专家推荐、元层选择与实际路由。
* rewards.jsonl：记录每条奖励明细（工具失败/重试/延迟）与特征向量。重启后会重放恢复学习状态。
* policy.json：存储模式与强制模型配置。
反馈机制¶
- 结算窗口：反馈结算窗口为 45s（可配置
settleDelayMs）。 - 奖励计算：干净收尾 1 分起；工具失败 -0.2/次（封顶 0.6）；模型重试 -0.2/次（封顶 0.4）；成本 min(0.5, 20×回合成本元)；延迟 >30s -0.1 / >90s -0.3。
- 人类反馈：依赖 Web UI 的 👍/👎 按钮（点踩 -0.5，点赞 +0.1），用于修正已应用的奖励。
注意事项¶
- 重启丢失：重启会丢失未结算的 pending 反馈条目。
- 反馈依赖：反馈数据依赖部署的 Web UI 实际产生，插件只读不写。
- 专家毕业：LinUCB 和 k-NN 专家需要一定数量的回合样本（50/30）才会进入元层池。
- 必填参数：安装命令
--profile必填。
参考资料¶
- 插件目录：dsh-agentic-router
- 源码地址：GitHub
