前言¶
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
