dsh-agentic-router 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lhl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,76 @@
+# dsh-agentic-router
+
+> 🌐 Language / 语言切换: **[English](./README.en.md)** · **[简体中文](./README.md)**
+
+DeepSeek Harness (DSH) plugin: a **learning agentic router with a data flywheel**.
+
+It watches every model request, routes it to the most appropriate model tier by task type and complexity, asks four experts in parallel and lets an EXP3 meta-selector decide who to trust. Every turn is scored with **quality-proxy signals** (tool failures, model retries, latency) and the reward feeds back into the strategies — the router gets better as it runs. Every decision and reward is persisted locally: auditable and replayable.
+
+## Architecture
+
+```
+user input → classify (rules, <1ms) → 4 expert recommendations → EXP3 meta-pick → agent/request swap
+                                           ↑                              │
+              UCB/LinUCB/k-NN/EXP3 updates ← quality-proxy reward ← turn end (tool errors/retries/latency)
+```
+
+| Expert | Algorithm | Status |
+|---|---|---|
+| rule | deterministic thresholds (complexity ≤0.3→fast, ≥0.7→strong, else mid) | cold-start prior, always in pool |
+| UCB | cluster×tier multi-armed bandit; unexplored arms get ∞, ties rotate | active from day zero |
+| LinUCB | linear feature scoring + exploration bonus, gradient updates | shadow; graduates at 50 samples |
+| k-NN | k=5 nearest-neighbor aggregation over the experience pool | shadow; graduates at 30 experiences |
+| EXP3 | meta-selector, importance-weighted updates | always on; cold-start biased to rule (weight 2.5) |
+
+Design rationale and roadmap: [docs/DESIGN.md](./docs/DESIGN.md). The implementation was validated against a live runtime prototype first; eight defects found there are fixed and pinned as regression tests.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-agentic-router
+```
+
+> `--profile` is mandatory. Restart the session (or profile) after installing so the tool schemas join prompt assembly. Default mode is **shadow** (records and learns, never swaps); switch to active once the policy behaves.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `agentic_router_stats` | decision log, four-expert recommendations, EXP3 weights, flywheel state |
+| `agentic_router_set_mode` | shadow (default) / active (real swaps) / off (bypass) |
+| `agentic_router_force` | force a model id (active mode only); clear=true to release |
+| `agentic_router_reset` | wipe flywheel learning state, keep mode |
+
+## Data flywheel (persistence)
+
+Directory: `${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router/` (override with `AGENTIC_ROUTER_HOME`)
+
+- `decisions.jsonl` — one line per decision: task type/complexity, all four recommendations, meta pick, actual route, swapped?
+- `rewards.jsonl` — one line per reward with breakdown (tool errors/retries/latency) + feature vector; **replayed on startup to restore learning state**
+- `policy.json` — mode and forced model (atomic write)
+
+Reward: clean close starts at 1; tool failures −0.2 each (cap 0.6), model retries −0.2 each (cap 0.4), latency >30s −0.1 / >90s −0.3; errored turns score 0.
+
+## Known limits
+
+- Model tiers are recognized by id keywords (flash→fast, pro→strong); real swaps happen only when more than one tier exists
+- Rewards are proxies: a mediocre-but-successful answer still scores full marks, so wire up UI feedback (messageFeedback) for production use
+- LinUCB / k-NN need dozens of turns before they graduate into the meta pool
+
+## Development
+
+```sh
+npm test        # node --test, zero dependencies
+```
+
+## Publish
+
+```sh
+npm publish                                     # requires npm account
+git push origin main                            # after making the GitHub repo public
+# directory listing: add the dsh-plugin topic, or submit at dshmarketplace.dev/submit
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,83 @@
+# dsh-agentic-router
+
+> 🌐 语言切换 / Language: **[简体中文](./README.md)** · **[English](./README.en.md)**
+
+DeepSeek Harness（DSH）插件：**学习型智能路由（agentic router）+ 数据飞轮**。
+
+监听每次模型请求，按任务类型与复杂度把请求路由到最合适的模型档位；四个专家并行推荐、EXP3 元选择器决定听谁的；每回合按**质量代理信号**（工具失败、模型重试、延迟）计算奖励并回传，路由策略随使用越学越准。全部决策与奖励落盘，可审计、可重放。
+
+## 架构
+
+```
+用户输入 → 分类(规则,<1ms) → 四专家推荐 → EXP3 元选择 → agent/request 切换模型
+                                        ↑                        │
+                 UCB/LinUCB/k-NN/EXP3 更新 ← 质量代理奖励 ← 回合收尾(工具失败/重试/延迟)
+```
+
+| 专家 | 算法 | 状态 |
+|---|---|---|
+| rule | 确定性阈值表（复杂度 ≤0.3→fast，≥0.7→strong，其余 mid） | 冷启动先验，常驻兜底 |
+| UCB | 簇×档多臂老虎机，未探索臂上界∞、平局轮转 | 零样本即活跃 |
+| LinUCB | 特征线性打分 + 探索项，梯度更新 | 影子，50 样本毕业 |
+| k-NN | 经验池最近邻（k=5）聚合 | 影子，30 经验毕业 |
+| EXP3 | 元选择器，重要性加权更新 | 常驻，冷启动偏 rule（权重 2.5） |
+
+设计细节与路线图见 [docs/DESIGN.md](./docs/DESIGN.md)。本实现源自真实运行时上的动态原型验证（8 个实测缺陷已修复并固化为回归测试）。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-agentic-router
+```
+
+> `--profile` 必填。安装后重启会话（或 profile），工具 schema 才会进入 prompt 组装。默认 **shadow 模式**（只记录与学习，不切换模型），确认策略表现后再切 active。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `agentic_router_stats` | 查看决策记录、四专家推荐、EXP3 权重、飞轮状态 |
+| `agentic_router_set_mode` | 切换 shadow（默认）/ active（真切换）/ off（旁路） |
+| `agentic_router_force` | 强制指定模型 id（active 生效），clear=true 清除 |
+| `agentic_router_reset` | 清空飞轮学习状态，保留模式 |
+
+## 数据飞轮（落盘）
+
+目录：`${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router/`（`AGENTIC_ROUTER_HOME` 可覆盖）
+
+- `decisions.jsonl` — 每条决策：任务类型/复杂度/四专家推荐/元层选择/实际路由/是否切换
+- `rewards.jsonl` — 每条奖励：明细（工具失败/重试/延迟）+ 特征向量，**重启后重放恢复学习状态**
+- `policy.json` — 模式与强制模型（原子写）
+
+奖励公式：干净收尾 1 分起，工具失败 −0.2/次（封顶 0.6）、模型重试 −0.2/次（封顶 0.4）、延迟 >30s −0.1 / >90s −0.3；出错回合记 0。
+
+## 分类器（规则先验，<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）；可用模型多于一档时路由才真正切换
+- 奖励信号是"代理"：任务成功但质量平庸的情况（尤其模型池内质量差距大时）仍可能被记满分，正式场景建议接入 UI 反馈（messageFeedback）
+- 毕业策略（LinUCB/k-NN）需要数十个回合样本才会进元层池
+
+## 开发
+
+```sh
+npm test        # node --test，零依赖
+```
+
+回归用例覆盖实测缺陷：qa 祈使句、mid 档回退、UCB 冷启动轮转、agent 键隔离、奖励 JSON 合法性、飞轮重放恢复等。
+
+## 发布
+
+```sh
+npm publish                                     # 需 npm 账号
+git push origin main                            # GitHub 仓库公开后
+# 目录站：给仓库加 dsh-plugin topic 自动收录，或到 dshmarketplace.dev/submit 提交
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh bundle 层：挂载 dsh-agentic-router 插件（dsh/index.js，经 package.json exports）
+- insert:
+    - id: agentic-router
+      name: 'dsh-agentic-router'

package/docs/DESIGN.md

@@ -0,0 +1,226 @@
+# DSH Agentic Router 插件设计方案
+
+> 目标：在 DeepSeek Harness 里做一个**学习型智能路由**插件——监听用户输入，按任务类型与复杂度把请求路由到最合适的模型 / 子 agent / 工具组合；每次路由的**决策与结果全部落盘**，形成数据飞轮，让路由判断随使用越来越准、越来越快。
+
+## 0. 一句话架构
+
+```
+用户输入 → 特征提取(快) → 路由器决策 → 改写请求(agent/request waterfall) / 派发子 agent
+                ↑                                    ↓
+        策略(规则表+学习权重) ← 评分与在线学习 ← 结果回传(质量/成本/延迟落盘)
+```
+
+三个关键设计原则（对齐 DSH 架构文档）：
+
+1. **只走官方扩展点**：路由动作通过 `agent/request` / `agent/pre-step` waterfall 实现；决策记录通过 SessionEventMap 扩展进入会话日志（"model-visible means logged"）。
+2. **决策可解释、可撤销**：每次路由都写一条带理由的日志事件；提供 `router:force` 人工覆盖命令与开关。
+3. **先影子后接管**：上线先跑 shadow mode（只记录不干预），数据够之后再接管。
+
+## 1. 挂载点（引用自官方文档的确切签名）
+
+### 1.1 模型级路由：`agent/request`（waterfall）
+
+```ts
+'agent/request'(this: Scoped<Agent>, payload: {
+  agent: Agent; turn: number; step: number; signal: AbortSignal
+}, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+```
+
+> 官方语义：`await next()` 得到"机器本来会用的冻结调用配置"（首请求为 agent 选项，之后为已记录 header），**返回一个替代配置即可切换模型**；此 waterfall 不能改消息，模型可见内容必须走已记录通道。
+
+这是**模型路由的官方入口**：路由器在这里拿到默认 provider/model，然后返回替换后的 `LlmCallConfig`（换 provider、换 model、换 reasoning 档位、改 maxTokens）。
+
+### 1.2 输入监听与消息改写：`agent/pre-step`（waterfall）
+
+```ts
+'agent/pre-step'(this: Scoped<Agent>, payload: {
+  agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal
+}, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+```
+
+> 官方语义：拒绝一个提议 step 或**替换进入它的消息**；`next()` 保留当前消息。它是 request 派生前唯一的串行监听链。
+
+在这里：观察/缓存本轮输入特征、把"路由上下文"注入消息（可选）、极端情况下直接拒掉不适合本 agent 的请求。
+
+### 1.3 补充事件
+
+| 事件 | 用途 |
+|---|---|
+| `agent/inbox/claimed`（emit） | 感知新输入被认领，触发特征预计算 |
+| `agent/status` / `step/end` | 拿耗时、token 用量等结果信号 |
+| `subagent/start` / `subagent/end` | 子 agent 级路由的观测点 |
+| `turn/end`（durable） | 每个 turn 结束时做一次**结果评分与落盘** |
+
+## 2. 路由决策链路（每次 turn）
+
+```text
+turn/start
+  │ 1. 特征提取（<5ms，纯启发式）:
+  │    - 任务类型: 代码/写作/问答/检索/agentic(工具编排)/翻译/数学…
+  │    - 复杂度: 输入长度、是否含代码块、是否要求多步推理、历史轮次、
+  │      关键词(debug/优化/重构/分析/总结…) → 0~1 分数
+  │    - 上下文: agent preset、cwd、挂载工具集、会话历史长度
+  │    - 约束: 延迟预算、成本预算、可用模型清单(来自部署配置或
+  │      dsh-model-deploy 的容量数据)
+  ▼
+  │ 2. 路由决策（路由表 + 学习权重）
+  │    策略候选:
+  │      A 规则表: 任务类型×复杂度 → 候选路由集合(带成本/延迟先验)
+  │      B 经验检索(k-NN): 当前任务 embedding → 历史相似任务中
+  │        结果最好的路由(EvoRoute 思路)
+  │      C 置信度低时: 小模型/LLM-judge 裁决一次(带缓存)
+  │    输出: { target: model|agent|tools, reason, confidence }
+  ▼
+  │ 3. 执行路由
+  │    - 模型级: agent/request 返回替换的 LlmCallConfig
+  │    - 子agent级: 经 subagent provider 派发到对应 preset 的 agent
+  │    - 工具级: 按任务类型增删本 turn 的工具 schema(agent-scoped)
+  ▼
+  │ 4. 记录(durable)
+  │    routing/decision 事件: { taskType, complexity, features, chosen,
+  │        alternatives, reason, confidence, mode: shadow|active }
+  ▼
+turn/end
+  │ 5. 结果评分与回传(数据飞轮)
+  │    routing/outcome 事件: { decisionId, success, quality, latencyMs,
+  │        costTokens, retryCount, userEdited }
+  └──→ 写入本地 flywheel 存储 → 触发在线学习
+```
+
+## 3. 分类器设计（复杂度 + 任务类型）
+
+**第 1 层（默认，零延迟）**：确定性启发式 + 关键词/模式表。覆盖 90% 场景，<5ms。
+
+- 任务类型：代码（文件/报错/函数/重构）、创作、问答、总结、翻译、agentic（"帮我做/查一下/跑一下"）、数据分析
+- 复杂度信号：输入 token 数、代码块占比、工具调用历史、任务动词强度、是否需要多文件、会话历史长度
+- 输出 0~1 复杂度分 + 类型标签（多标签）
+
+**第 2 层（低置信度时，可关闭）**：小模型分类器（如 Flash 级）一次 prompt 分类，带结果缓存与超时（>300ms 放弃，回退第 1 层）。
+
+**第 3 层（学习型）**：基于飞轮数据定期训练/更新——简单做法是"embedding + k-NN 经验检索"（在线可做），进阶做法是离线训练一个小型路由打分器（周级更新）。
+
+## 4. 路由目标三层模型
+
+| 层级 | 动作 | 挂载点 | 适用 |
+|---|---|---|---|
+| L1 模型路由 | 替换 provider/model/reasoning | `agent/request` | 同能力不同成本/质量档位（Flash vs Pro） |
+| L2 子 agent 路由 | 派发给不同 preset 的 agent | subagent provider + `agent/pre-step` | 研究型 vs 编码型 vs 检索型任务 |
+| L3 工具/能力路由 | 增删本 turn 工具 schema | tools 注册（agent-scoped） | 按任务裁剪工具面，降 prompt 成本、提速 |
+
+**默认路由表（冷启动先验，随飞轮学习调整）**：
+
+| 任务类型 | 复杂度低 | 复杂度高 |
+|---|---|---|
+| 闲聊/简单问答 | Flash 模型 | Pro 模型 |
+| 创作/翻译 | Flash | Pro |
+| 代码/调试 | Flash + 代码工具 | Pro + 代码 agent 子 agent |
+| agentic 编排 | 本 agent 全工具 | Pro + workflow |
+| 研究/检索 | 检索子 agent | 研究子 agent |
+
+每个候选带 `成本(¥/1M tokens)、延迟先验(ms)、能力标签`，由配置声明，飞轮更新其**结果质量后验**。
+
+## 5. 数据飞轮（核心闭环）
+
+### 5.1 记录什么（durable，全部追加）
+
+```jsonc
+// routing/decision（turn 开始时）
+{ "taskType": ["code"], "complexity": 0.72, "features": {...},
+  "chosen": { "kind": "model", "provider": "…", "model": "…" },
+  "alternatives": [...], "reason": "rule#code-high + exp-kNN@0.81",
+  "confidence": 0.81, "mode": "shadow" }
+
+// routing/outcome（turn 结束时）
+{ "decisionId": "...", "success": true, "quality": 0.85,
+  "latencyMs": 8420, "costTokens": { "in": 2400, "out": 810 },
+  "retryCount": 0, "userEdited": false }
+```
+
+### 5.2 评分信号（怎么知道"路由好不好"）
+
+- **成功**：turn 正常结束、无 tool error、无重试
+- **质量代理**：用户是否编辑/重发消息、是否追加追问（正向）、是否中途打断（负向）
+- **效率**：端到端延迟、token 成本
+- 综合分：`score = α·quality + β·(1 - latency/预算) + γ·(1 - cost/预算)`，权重可配
+
+### 5.3 学习机制（从易到难，方案支持三级）
+
+1. **在线 Bandit**（上线即用）：每个"任务簇 × 候选路由"维护 UCB/ε-greedy 的收益估计；探索率随样本数衰减。简单、可解释、即时见效。
+2. **经验检索 k-NN**（EvoRoute 思路）：把 (任务特征, 路由, 结果) 存为向量库，新任务检索最相似的历史经验，选历史收益最高的路由。冷启动与 1 并用。
+3. **离线重训**（周级，可选）：用累积数据训练小型打分器/重排序器，替换第 2 层分类器。
+
+### 5.4 飞轮存储
+
+- 放在 DSH 数据目录下的插件专属存储（`~/.dsh/storages/dsh-agentic-router/`：`decisions.jsonl` 追加日志 + `policy.json` 可写回的策略权重 + 可选向量索引文件）
+- 全部为本地明文 JSON/JSONL——用户可导出、可审计、可迁移
+
+### 5.5 影子模式（安全启动的关键）
+
+`mode: shadow`：决策照算、事件照记，但 `agent/request` 里**返回 `await next()` 原样配置**。跑 N 天/请求数后对比"shadow 路由 vs 实际默认路由"的评分分布，达标后一键切 `active`。
+
+## 6. 存储与事件扩展
+
+- 新增 durable 事件：`routing/decision`、`routing/outcome`（扩展 SessionEventMap，走会话日志，UI 可从日志渲染路由卡片）
+- 模型可见的注入：`agent.inject()` 注入一行"本次已由 router 路由至 X（理由：…）"，模型可知情
+- 策略文件读写经插件自己的存储工具（幂等、原子写、带版本号，支持回滚）
+
+## 7. 工具与 UI
+
+**模型工具**（注册到 `ctx.tools`）：
+- `router_explain(turn?)` — 解释最近一次/指定 turn 的路由决策与依据
+- `router_stats` — 各任务簇 × 路由的收益统计（飞轮数据摘要）
+- `router_set_mode(mode, scope)` — shadow/active/off 切换
+
+**人工命令**（`ctx.commands`）：
+- `/router:force <模型|agent>` — 本次会话强制路由
+- `/router:report` — 导出飞轮报告
+
+**Client 侧（可选二期）**：路由卡片（复用 durable 事件渲染）+ 策略配置面板。
+
+## 8. 包结构（对齐 dsh-model-deploy 的打包格式）
+
+```
+dsh-agentic-router/
+├── package.json            # dsh.bundle.patch → cordis.patch.yml
+├── cordis.patch.yml        # insert row: dsh-agentic-router
+├── dsh/
+│   ├── index.js            # apply(): 注册事件监听 + 工具 + 命令
+│   ├── classify.js         # 第1/2层分类器（纯函数）
+│   ├── policy.js           # 路由表 + bandit/kNN 策略 + 影子模式
+│   ├── store.js            # 飞轮存储（jsonl 追加 + 原子写策略文件）
+│   └── events.js           # routing/decision、routing/outcome 定义
+├── test/                   # node --test：分类器/策略/存储/端到端 mock
+├── README.md / README.en.md
+└── LICENSE
+```
+
+`inject: ['tools', 'agents', 'commands']`；事件监听全部经 `ctx.on('agent/request', ...)` 注册（随插件卸载自动回收）。
+
+## 9. 分阶段路线图
+
+| 阶段 | 内容 | 验收 |
+|---|---|---|
+| P0 影子模式 | 特征+分类+决策+落盘，不改请求 | 日志出现 decision/outcome 事件；分类延迟 <5ms |
+| P1 规则接管 | agent/request 真正切换模型；force 命令 | 简单问答走 Flash、复杂代码走 Pro，可解释 |
+| P2 数据飞轮 | outcome 评分 + 在线 bandit + 统计 | 两周内成本/延迟下降且质量无回退（影子期数据可回放验证） |
+| P3 子 agent 路由 | subagent 派发 + 工具面裁剪 | 研究型任务自动进检索子 agent |
+| P4 学习升级 | k-NN 经验检索 + 策略热更新 UI | 新任务类型零配置自动学习出合理路由 |
+
+## 10. 风险与护栏
+
+- **误路由成本上限**：单会话/turn 成本预算，超限自动降级回默认模型
+- **分类器自身延迟**：>5ms 直接走默认；LLM 分类器带 300ms 超时
+- **可回退**：`/router:force default` 或全局 off；策略文件保留版本，支持一键回滚
+- **隐私**：飞轮数据全部本地落盘，默认不出机
+- **合规**：影子模式与 active 模式都写日志，任何路由可事后审计
+
+## 11. 与 dsh-model-deploy（选型分析器）的联动
+
+选型分析器提供**容量/成本先验**：部署里有哪些模型与硬件、各自 TTFT/吞吐/成本——这些直接作为路由表的候选集与成本/延迟先验；反过来，路由飞轮积累的**真实负载下的质量/延迟数据**可以回灌给选型分析器校准其估算系数。两者合起来就是"**规划（选型）→ 执行（路由）→ 反馈（飞轮）**"的完整闭环。
+
+## 12. 验证方式
+
+- 单元测试：分类器、策略、存储（node --test，零依赖）
+- 离线回放：拿历史 session 日志重放，对比 shadow 路由与实际路由的评分分布
+- 影子期 A/B：shadow 评分 vs 默认路由评分，达标才切 active
+- 集成冒烟：mock ctx 注入 agent/request payload，验证 LlmCallConfig 替换与 next() 透传

package/dsh/classify.js

@@ -0,0 +1,49 @@
+// 分类器：任务类型 + 复杂度（确定性规则，<1ms）
+// 所有规则都来自动态原型实测，回归用例见 test/classify.test.js
+
+const QA_IMPERATIVE = /(请|麻烦|帮我).{0,6}(回答|告诉|说)/
+const CODE_RE = /def |function |class |import |require\(|```|\.py|\.ts|\.js|\.go|\.rs\b|bug|error|exception|traceback|报错|代码|函数|接口|脚本/
+const WRITE_RE = /(写|创作|起草|润色|翻译|translate|write|blog|article|文案|邮件|报告)/
+const SUMMARIZE_RE = /(总结|概括|summar|摘要|要点)/
+const RESEARCH_RE = /(查|搜索|检索|research|调研|对比|最新|资料|文档)/
+const AGENTIC_RE = /(帮我|请|做|搭建|构建|部署|实现|写一个|生成|build|setup|deploy|implement|create)/
+const QA_RE = /[?？]|什么|为什么|怎么|如何|how|what|why|能否|是否/
+const COMPLEX_RE = /(重构|优化|设计|分析|架构|debug|调试|排查|review|方案|复杂|多步|逐步|implement|design|architecture)/
+const SIMPLE_RE = /(一句|简单|快速|quickly|short|hello|你好|谢谢)/
+
+// 任务类型基础复杂度先验（实测调参）：代码与 agentic 任务天然更重
+const PRIOR = { code: 0.3, agentic: 0.3, research: 0.2, write: 0.15, summarize: 0.05, qa: 0, other: 0 }
+
+export function classify(text) {
+  const t = text || ''
+  const lower = t.toLowerCase()
+  let type = 'other'
+  if (QA_IMPERATIVE.test(lower)) type = 'qa'
+  else if (CODE_RE.test(lower)) type = 'code'
+  else if (WRITE_RE.test(lower)) type = 'write'
+  else if (SUMMARIZE_RE.test(lower)) type = 'summarize'
+  else if (RESEARCH_RE.test(lower)) type = 'research'
+  else if (AGENTIC_RE.test(lower)) type = 'agentic'
+  else if (QA_RE.test(lower)) type = 'qa'
+
+  const complexKw = COMPLEX_RE.test(lower)
+  const simpleKw = SIMPLE_RE.test(lower)
+  let score = PRIOR[type] || 0
+  score += Math.min(t.length / 2000, 1) * 0.2
+  score += (t.match(/```/g) || []).length > 0 ? 0.25 : 0
+  if (complexKw) score += 0.25
+  // 同时出现"简单"与"复杂"关键词时不做简单惩罚（实测踩过的坑）
+  if (simpleKw && !complexKw) score -= 0.25
+  score = Math.max(0, Math.min(1, score))
+  return { type, complexity: Math.round(score * 100) / 100 }
+}
+
+const TYPES = ['code', 'write', 'summarize', 'research', 'agentic', 'qa']
+
+// LinUCB / k-NN 共享的特征向量：[1, 复杂度, 长度归一, 类型 one-hot ×6]
+export function featuresOf(cls, text) {
+  const t = text || ''
+  const f = [1, cls.complexity, Math.min(t.length, 4000) / 4000]
+  for (const ty of TYPES) f.push(cls.type === ty ? 1 : 0)
+  return f
+}

package/dsh/index.js

@@ -0,0 +1,402 @@
+// dsh-agentic-router —— DeepSeek Harness 插件（Host 侧）
+//
+// 学习型智能路由：监听 agent/pre-step 与 agent/request，按任务类型与复杂度在
+// 模型档位（fast/mid/strong）之间路由；四个专家（规则表 / UCB / LinUCB / k-NN）
+// 并行推荐，EXP3 元选择器决定听谁的；回合结束时按质量代理信号
+// （工具失败 + 模型重试 + 延迟）计算奖励并回传飞轮。
+//
+// 架构依据 docs/architecture.md：
+//   - "Add a model-facing capability"    → ctx.tools 注册 4 个管理工具
+//   - "Intercept a request"              → agent/request waterfall 替换 LlmCallConfig
+//   - 所有监听经 ctx.on 注册，随插件卸载自动回收
+// 飞轮数据落盘 ${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router/，重启后重放恢复。
+
+import { classify, featuresOf } from './classify.js'
+import {
+  tierOf, tierTarget, resolveTier,
+  recommendRule, recommendUcb, recommendLin, recommendKnn,
+  rewardOf, applyReward,
+} from './strategies.js'
+import { metaPick, DEFAULT_WEIGHTS } from './meta.js'
+import { Store, defaultHome } from './store.js'
+
+export const name = 'agentic-router'
+export const inject = ['tools']
+
+const LIN_GRADUATION = 50   // LinUCB 毕业样本线
+const KNN_GRADUATION = 30   // k-NN 毕业经验线
+
+function freshState() {
+  return {
+    mode: 'shadow',
+    seq: 0,
+    decisions: [],
+    forced: null,
+    pending: new Map(),
+    modelTiers: null,
+    turnDecision: {},
+    openTurns: new Map(),
+    ucb: { total: 0, arms: {} },
+    lin: {
+      total: 0,
+      tierN: { fast: 0, mid: 0, strong: 0 },
+      tierW: { fast: new Array(9).fill(0), mid: new Array(9).fill(0), strong: new Array(9).fill(0) },
+    },
+    knn: { pool: [] },
+    exp3: { total: 0, weights: { ...DEFAULT_WEIGHTS } },
+  }
+}
+
+function now() {
+  try { return Date.now() } catch { return null }
+}
+
+function agentKey(payload) {
+  try {
+    const a = payload && payload.agent
+    if (a) {
+      if (typeof a.sessionId === 'string') return a.sessionId
+      if (typeof a.id === 'string') return a.id
+      const s = a.session
+      if (s && typeof s.id === 'string') return s.id
+    }
+  } catch {}
+  return 'agent-' + (payload && payload.turn)
+}
+
+function fullKey(payload) { return agentKey(payload) + '/' + payload.turn }
+
+function textOfMessages(messages) {
+  const parts = []
+  if (!Array.isArray(messages)) return ''
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue
+    const c = m.content
+    if (typeof c === 'string') parts.push(c)
+    else if (Array.isArray(c)) {
+      for (const b of c) {
+        if (b && typeof b === 'object' && b.type === 'text' && typeof b.text === 'string') parts.push(b.text)
+      }
+    }
+  }
+  return parts.join('\n').trim()
+}
+
+function isErrorResult(r) {
+  if (r == null || typeof r !== 'object') return false
+  if (r.ok === false || r.success === false) return true
+  if (r.status === 'error' || r.status === 'failed' || r.status === 'ERROR') return true
+  if (typeof r.error === 'object' && r.error !== null) return true
+  if (typeof r.error === 'string' && r.error !== '') return true
+  return false
+}
+
+function execAgentKey(exec) {
+  try {
+    if (!exec) return null
+    const a = exec.agent
+    if (a) {
+      if (typeof a.sessionId === 'string') return a.sessionId
+      if (typeof a.id === 'string') return a.id
+    }
+    if (typeof exec.sessionId === 'string') return exec.sessionId
+    if (typeof exec.agentId === 'string') return exec.agentId
+  } catch {}
+  return null
+}
+
+async function refreshModelTiers(llm) {
+  if (!llm || typeof llm.listProviders !== 'function') return null
+  const providers = await llm.listProviders()
+  const out = { providers: [], tiers: { fast: [], mid: [], strong: [] } }
+  for (const p of providers) {
+    const pid = p && (p.id || p.name || p.provider)
+    if (!pid) continue
+    let models = []
+    try { models = await llm.listModels(pid) } catch { models = [] }
+    const names = (models || []).map((m) => (m && (m.id || m.model || m.name)) || '').filter(Boolean)
+    out.providers.push({ provider: pid, models: names })
+    for (const n of names) out.tiers[tierOf(n)].push(pid + '/' + n)
+  }
+  return out
+}
+
+export function apply(ctx, config = {}) {
+  const tools = ctx.get('tools')
+  const llm = ctx.get('llm')
+  const store = new Store(config.home || defaultHome())
+  const policy = store.loadPolicy()
+
+  const state = freshState()
+  state.mode = policy.mode || config.mode || 'shadow'
+  if (typeof policy.forced === 'string') state.forced = policy.forced
+
+  // 飞轮恢复：重放 rewards.jsonl 重建 UCB/LinUCB/k-NN/EXP3
+  const rewards = store.loadJsonl('rewards.jsonl')
+  for (const rec of rewards) {
+    if (typeof rec.reward === 'number' && Array.isArray(rec.f)) applyReward(state, rec)
+  }
+  state.decisions = store.loadJsonl('decisions.jsonl').slice(-60)
+  state.seq = state.decisions.length ? state.decisions[state.decisions.length - 1].seq : 0
+
+  const log = (msg) => console.log('[agentic-router]', msg)
+  if (rewards.length) log('replayed ' + rewards.length + ' rewards; ucb.total=' + state.ucb.total)
+
+  // ---- 事件挂载 ----
+  ctx.on('agent/pre-step', (payload, next) => {
+    try {
+      const text = textOfMessages(payload && payload.messages)
+      if (text) state.pending.set(agentKey(payload) + ':' + payload.turn, text)
+    } catch (e) {
+      log('pre-step capture failed: ' + String(e))
+    }
+    return next()
+  })
+
+  ctx.on('agent/request', async (payload, next) => {
+    const cfg = await next()
+    if (!cfg || typeof cfg !== 'object') return cfg
+    try {
+      const key = fullKey(payload)
+      if (state.turnDecision[key]) return cfg
+      const pkey = agentKey(payload) + ':' + payload.turn
+      const text = state.pending.get(pkey) || ''
+      state.pending.delete(pkey)
+      const cls = classify(text)
+      const f = featuresOf(cls, text)
+      const current = typeof cfg.model === 'string' ? cfg.model : '(unknown)'
+      const provider = typeof cfg.provider === 'string' ? cfg.provider : ''
+      const recs = {
+        rule: recommendRule(cls),
+        ucb: recommendUcb(cls, state.ucb),
+        lin: recommendLin(cls, f, state.lin),
+        knn: recommendKnn(cls, f, state.knn),
+      }
+      if (state.forced) recs.rule = { tier: 'forced', reason: 'forced', conf: 1 }
+      const exp3 = {
+        ...state.exp3,
+        linGraduated: state.lin.total >= LIN_GRADUATION,
+        knnGraduated: state.knn.pool.length >= KNN_GRADUATION,
+      }
+      const meta = metaPick(recs, exp3)
+      const chosenRec = meta.byName[meta.chosen] || recs.rule
+      const resolved = state.forced
+        ? { target: state.forced, used: 'forced', note: 'forced' }
+        : resolveTier(chosenRec.tier, provider, state.modelTiers)
+      const target = resolved.target
+      state.seq += 1
+      const record = {
+        seq: state.seq,
+        turn: key,
+        mode: state.mode,
+        taskType: cls.type,
+        complexity: cls.complexity,
+        inputPreview: text.slice(0, 100),
+        currentModel: current,
+        recs: {
+          rule: recs.rule.tier + '(' + recs.rule.conf + ')',
+          ucb: recs.ucb.tier + '(' + recs.ucb.conf + ')',
+          lin: recs.lin.tier + '(' + recs.lin.conf + ')',
+          knn: recs.knn.tier + '(' + recs.knn.conf + ')',
+        },
+        metaChosen: meta.chosen,
+        metaProbs: meta.ps,
+        metaPool: meta.pool,
+        resolvedTier: resolved.used + (resolved.note ? ' [' + resolved.note + ']' : ''),
+        targetModel: state.mode === 'active' ? target : null,
+        swapped: false,
+      }
+      state.turnDecision[key] = {
+        clsType: cls.type, f, recs, meta, chosen: meta.chosen,
+        finalized: false, t0: now(), toolErrors: 0, retries: 0,
+      }
+      state.openTurns.set(agentKey(payload), key)
+      store.appendJsonl('decisions.jsonl', record)
+      if (state.mode === 'active' && target && target !== current) {
+        record.swapped = true
+        state.decisions.push(record)
+        if (state.decisions.length > 200) state.decisions.shift()
+        log('SWAP -> ' + target + ' | ' + meta.chosen + ' | ' + chosenRec.reason + ' | ' + resolved.note)
+        return { ...cfg, model: target }
+      }
+      state.decisions.push(record)
+      if (state.decisions.length > 200) state.decisions.shift()
+      log('decision #' + state.seq + ' type=' + cls.type + ' c=' + cls.complexity +
+        ' meta=' + meta.chosen + ' tier=' + resolved.used + ' recs=' + JSON.stringify(record.recs))
+    } catch (e) {
+      log('decide failed: ' + String(e))
+    }
+    return cfg
+  })
+
+  ctx.on('agent/request-error', (payload, next) => {
+    try {
+      const td = state.turnDecision[fullKey(payload)]
+      if (td && !td.finalized) {
+        td.retries = (td.retries || 0) + 1
+        log('retry on ' + fullKey(payload) + ' count=' + td.retries)
+      }
+    } catch (e) {
+      log('request-error hook failed: ' + String(e))
+    }
+    return next()
+  })
+
+  ctx.on('tools/result', (exec, result) => {
+    try {
+      if (!isErrorResult(result)) return
+      const ak = execAgentKey(exec)
+      if (!ak) return
+      const key = state.openTurns.get(ak)
+      if (!key) return
+      const td = state.turnDecision[key]
+      if (td && !td.finalized) {
+        td.toolErrors = (td.toolErrors || 0) + 1
+        log('tool error on ' + key + ' count=' + td.toolErrors)
+      }
+    } catch (e) {
+      log('tools/result hook failed: ' + String(e))
+    }
+  })
+
+  const finalize = (payload, tag) => {
+    try {
+      const key = fullKey(payload)
+      const td = state.turnDecision[key]
+      if (!td || td.finalized) return
+      td.finalized = true
+      const t1 = now()
+      const dtMs = t1 != null && td.t0 != null ? t1 - td.t0 : null
+      const r = rewardOf(td, tag, dtMs)
+      const rec = {
+        turn: key,
+        reward: r.reward,
+        tag,
+        breakdown: r.breakdown,
+        chosen: td.chosen,
+        pool: td.meta ? td.meta.pool : [],
+        pChosen: td.meta ? td.meta.ps[td.chosen] || 0 : 0,
+        clsType: td.clsType,
+        ucbTier: td.recs.ucb.tier,
+        linTier: td.recs.lin.tier,
+        f: td.f,
+      }
+      applyReward(state, rec)
+      store.appendJsonl('rewards.jsonl', rec)
+      const ak = agentKey(payload)
+      if (state.openTurns.get(ak) === key) state.openTurns.delete(ak)
+      log('reward ' + rec.reward + ' ' + tag + ' on ' + key + ' breakdown=' + JSON.stringify(r.breakdown))
+    } catch (e) {
+      log('finalize failed: ' + String(e))
+    }
+  }
+
+  ctx.on('agent/turn-stopping', (payload) => finalize(payload, 'clean-close'))
+  ctx.on('agent/error', (payload) => finalize(payload, 'error'))
+
+  refreshModelTiers(llm).then((t) => {
+    state.modelTiers = t
+    log('model tiers: ' + JSON.stringify(t))
+  })
+
+  // ---- 工具 ----
+  const OUT = (label) => ({
+    schema: { type: 'object', additionalProperties: true },
+    render: (_args, value) => [{ type: 'text', text: label + '\n' + JSON.stringify(value, null, 2) }],
+  })
+  const register = (def) => {
+    try {
+      tools.register(def)
+      log('tool registered: ' + def.name)
+    } catch (e) {
+      log('tool register FAILED: ' + def.name + ' -> ' + String(e))
+    }
+  }
+
+  register({
+    name: 'agentic_router_stats',
+    description: '查看 agentic router（UCB/LinUCB/k-NN 三策略 + EXP3 元选择器 + 质量代理奖励）的决策记录、策略权重与飞轮学习状态。',
+    parameters: { type: 'object', properties: {} },
+    output: OUT('agentic router 状态'),
+    isConcurrencySafe: () => true,
+    async execute() {
+      return {
+        mode: state.mode,
+        forcedModel: state.forced,
+        totalDecisions: state.seq,
+        modelTiers: state.modelTiers,
+        flywheel: {
+          ucb: state.ucb,
+          lin: { total: state.lin.total, tierN: state.lin.tierN, tierW: state.lin.tierW },
+          knnPoolSize: state.knn.pool.length,
+          exp3: state.exp3,
+          recentRewards: store.loadJsonl('rewards.jsonl').slice(-20),
+        },
+        recent: state.decisions.slice(-20),
+      }
+    },
+  })
+  register({
+    name: 'agentic_router_set_mode',
+    description: '切换 agentic router 模式：shadow（决策与学习照常，但不切换模型）、active（按元选择器结果真正切换）、off（旁路）。',
+    parameters: {
+      type: 'object',
+      properties: { mode: { type: 'string', enum: ['shadow', 'active', 'off'] } },
+      required: ['mode'],
+    },
+    output: OUT('agentic router 模式'),
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      state.mode = args.mode
+      store.savePolicy({ mode: state.mode, forced: state.forced })
+      return { mode: state.mode }
+    },
+  })
+  register({
+    name: 'agentic_router_force',
+    description: '强制后续请求使用指定模型 id（仅 active 模式生效）；clear=true 清除强制，恢复规则路由。',
+    parameters: {
+      type: 'object',
+      properties: {
+        model: { type: 'string', description: '目标模型 id（见 agentic_router_stats 的 modelTiers）' },
+        clear: { type: 'boolean', description: '清除强制' },
+      },
+    },
+    output: OUT('agentic router 强制路由'),
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      if (args && args.clear) {
+        state.forced = null
+        store.savePolicy({ mode: state.mode, forced: null })
+        return { forced: null }
+      }
+      if (args && typeof args.model === 'string') {
+        state.forced = args.model
+        store.savePolicy({ mode: state.mode, forced: args.model })
+        return { forced: args.model }
+      }
+      return { forced: state.forced, error: '需要 model 或 clear=true' }
+    },
+  })
+  register({
+    name: 'agentic_router_reset',
+    description: '清空飞轮学习状态（决策与奖励历史），保留当前模式；用于重新开始学习或清理测试数据。',
+    parameters: { type: 'object', properties: {} },
+    output: OUT('agentic router 重置'),
+    isConcurrencySafe: () => true,
+    async execute() {
+      store.resetFlywheel()
+      state.ucb = { total: 0, arms: {} }
+      state.lin = {
+        total: 0,
+        tierN: { fast: 0, mid: 0, strong: 0 },
+        tierW: { fast: new Array(9).fill(0), mid: new Array(9).fill(0), strong: new Array(9).fill(0) },
+      }
+      state.knn = { pool: [] }
+      state.exp3 = { total: 0, weights: { ...DEFAULT_WEIGHTS } }
+      state.seq = 0
+      state.decisions = []
+      return { reset: true, home: store.home }
+    },
+  })
+}

package/dsh/meta.js

@@ -0,0 +1,33 @@
+// EXP3 元选择器：把 {UCB, LinUCB, k-NN, rule} 当臂，按权重软最大采样，
+// 被选策略按重要性加权更新（reward / p_chosen）。
+
+const DEFAULT_WEIGHTS = { ucb: 1, linucb: 1, knn: 1, rule: 2.5 }
+
+export function metaPick(recs, exp3) {
+  const weights = exp3.weights
+  const pool = ['ucb']
+  const byName = { ucb: recs.ucb, rule: recs.rule }
+  if (exp3.linGraduated && recs.lin && recs.lin.tier) {
+    pool.push('linucb')
+    byName.linucb = recs.lin
+  }
+  if (exp3.knnGraduated && recs.knn && recs.knn.tier) {
+    pool.push('knn')
+    byName.knn = recs.knn
+  }
+  pool.push('rule')
+
+  let total = 0
+  for (const n of pool) total += weights[n] || 0
+  const ps = {}
+  for (const n of pool) ps[n] = (weights[n] || 0) / total
+  let r = Math.random()
+  let chosen = 'rule'
+  for (const n of pool) {
+    if (r < ps[n]) { chosen = n; break }
+    r -= ps[n]
+  }
+  return { chosen, ps, pool, byName }
+}
+
+export { DEFAULT_WEIGHTS }

package/dsh/store.js

@@ -0,0 +1,68 @@
+// 飞轮持久化：决策/奖励追加 JSONL，策略（模式/强制模型）原子写 policy.json
+// 默认目录：${DSH_HOME:-~/.dsh}/storages/dsh-agentic-router（可被 config.home 或
+// AGENTIC_ROUTER_HOME 环境变量覆盖）。全部本地明文，可导出可审计。
+
+import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, appendFileSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+
+export function defaultHome() {
+  if (process.env.AGENTIC_ROUTER_HOME) return process.env.AGENTIC_ROUTER_HOME
+  const base = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return join(base, 'storages', 'dsh-agentic-router')
+}
+
+export class Store {
+  constructor(home) {
+    this.home = home || defaultHome()
+    mkdirSync(this.home, { recursive: true })
+  }
+
+  policyPath() { return join(this.home, 'policy.json') }
+  jsonlPath(name) { return join(this.home, name) }
+
+  loadPolicy() {
+    try {
+      if (!existsSync(this.policyPath())) return {}
+      return JSON.parse(readFileSync(this.policyPath(), 'utf8'))
+    } catch {
+      return {}
+    }
+  }
+
+  savePolicy(policy) {
+    const p = this.policyPath()
+    mkdirSync(dirname(p), { recursive: true })
+    const tmp = p + '.tmp'
+    writeFileSync(tmp, JSON.stringify(policy, null, 2))
+    renameSync(tmp, p)
+  }
+
+  appendJsonl(name, obj) {
+    appendFileSync(this.jsonlPath(name), JSON.stringify(obj) + '\n')
+  }
+
+  loadJsonl(name) {
+    try {
+      if (!existsSync(this.jsonlPath(name))) return []
+      return readFileSync(this.jsonlPath(name), 'utf8')
+        .split('\n')
+        .filter((l) => l.trim())
+        .map((l) => JSON.parse(l))
+    } catch {
+      return []
+    }
+  }
+
+  // 清空飞轮（重置学习状态），保留 policy
+  resetFlywheel() {
+    for (const name of ['decisions.jsonl', 'rewards.jsonl']) {
+      const p = this.jsonlPath(name)
+      if (existsSync(p)) writeFileSync(p, '')
+    }
+  }
+
+  listFiles() {
+    try { return readdirSync(this.home) } catch { return [] }
+  }
+}

package/dsh/strategies.js

@@ -0,0 +1,153 @@
+// 四专家策略 + 奖励计算 + 飞轮更新（纯函数，state 从外部传入）
+// 算法选择（见 docs/DESIGN.md）：
+//   UCB      —— 簇×档臂的多臂老虎机（冷启动上界∞，平局轮转探索）
+//   LinUCB   —— 特征线性打分 + 探索项（毕业线 50 样本）
+//   k-NN     —— 经验池最近邻聚合（毕业线 30 经验）
+//   rule     —— 确定性阈值表（冷启动先验与兜底）
+
+export const FAST_RE = /flash|lite|mini|small|fast|air|nano|tiny|light/
+export const STRONG_RE = /pro|max|ultra|plus|large|premium|reason|thinking/
+
+export function tierOf(model) {
+  if (!model) return 'unknown'
+  if (FAST_RE.test(model)) return 'fast'
+  if (STRONG_RE.test(model)) return 'strong'
+  return 'mid'
+}
+
+export function tierTarget(tier, provider, modelTiers) {
+  const list = modelTiers && modelTiers.tiers && modelTiers.tiers[tier] ? modelTiers.tiers[tier] : []
+  for (const s of list) if (s.indexOf(provider + '/') === 0) return s.slice(provider.length + 1)
+  return null
+}
+
+// 档位 → 模型 id 的解析；mid 档无候选时向上取 strong（保质量），再取 fast
+export function resolveTier(tier, provider, modelTiers) {
+  if (!modelTiers) return { target: null, used: tier, note: 'tiers-not-ready' }
+  const target = tierTarget(tier, provider, modelTiers)
+  if (target) return { target, used: tier, note: '' }
+  if (tier === 'mid') {
+    const strong = tierTarget('strong', provider, modelTiers)
+    if (strong) return { target: strong, used: 'strong', note: 'mid->strong fallback' }
+    const fast = tierTarget('fast', provider, modelTiers)
+    if (fast) return { target: fast, used: 'fast', note: 'mid->fast fallback' }
+  }
+  return { target: null, used: tier, note: 'no-candidate' }
+}
+
+export function recommendRule(cls) {
+  const want = cls.complexity >= 0.7 ? 'strong' : (cls.complexity <= 0.3 ? 'fast' : 'mid')
+  return { tier: want, reason: 'rule threshold complexity=' + cls.complexity, conf: 0.5 }
+}
+
+// UCB：mean + c·√(lnN/n)；未探索臂上界∞，多个∞平局时按总拉动数轮转（避免永远选 fast）
+export function recommendUcb(cls, ucbState) {
+  const arms = ucbState.arms
+  const scores = []
+  for (const tier of ['fast', 'mid', 'strong']) {
+    const arm = arms[cls.type + ':' + tier] || { n: 0, mean: 0 }
+    const ucb = arm.n > 0 ? arm.mean + 1.2 * Math.sqrt(Math.log(ucbState.total + 1) / arm.n) : Infinity
+    scores.push({ tier, ucb, arm })
+  }
+  let best = scores[0]
+  for (const s of scores) if (s.ucb > best.ucb) best = s
+  const infs = scores.filter((s) => s.ucb === Infinity)
+  if (infs.length > 1) best = infs[ucbState.total % infs.length]
+  return {
+    tier: best.tier,
+    reason: 'ucb ' + cls.type + ' n=' + best.arm.n + ' mean=' + (Math.round(best.arm.mean * 100) / 100) +
+      ' bound=' + (isFinite(best.ucb) ? Math.round(best.ucb * 100) / 100 : 'inf'),
+    conf: isFinite(best.ucb) ? 0.6 : 0.2,
+  }
+}
+
+// LinUCB（近似实现）：每档线性权重 w·f + 探索项；梯度更新，探索项随档样本数衰减
+export function recommendLin(cls, f, linState) {
+  const tn = linState.tierN
+  let best = null
+  for (const tier of ['fast', 'mid', 'strong']) {
+    const w = linState.tierW[tier] || []
+    let dot = 0
+    for (let i = 0; i < f.length; i++) dot += (w[i] || 0) * f[i]
+    const bonus = tn[tier] > 0 ? 0.8 * Math.sqrt(Math.log(linState.total + 1) / tn[tier]) : 0.3
+    const score = dot + bonus
+    if (!best || score > best.score) best = { tier, score, dot }
+  }
+  return {
+    tier: best.tier,
+    reason: 'linucb score=' + Math.round(best.score * 100) / 100 + ' (dot=' + Math.round(best.dot * 100) / 100 + ')',
+    conf: linState.total >= 50 ? 0.7 : 0.1,
+  }
+}
+
+// k-NN：欧氏距离取 k=5 邻居，按邻居平均奖励选档
+export function recommendKnn(cls, f, knnState) {
+  const pool = knnState.pool
+  if (pool.length < 5) return { tier: null, reason: 'knn cold (' + pool.length + '/5 seed)', conf: 0 }
+  const scored = []
+  for (const e of pool) {
+    let d = 0
+    for (let i = 0; i < f.length; i++) d += (e.f[i] - f[i]) * (e.f[i] - f[i])
+    scored.push({ d, e })
+  }
+  scored.sort((a, b) => a.d - b.d)
+  const k = Math.min(5, scored.length)
+  const agg = { fast: { n: 0, s: 0 }, mid: { n: 0, s: 0 }, strong: { n: 0, s: 0 } }
+  for (let i = 0; i < k; i++) {
+    const t = scored[i].e.tier
+    if (agg[t]) { agg[t].n += 1; agg[t].s += scored[i].e.r }
+  }
+  let best = null
+  for (const tier of ['fast', 'mid', 'strong']) {
+    const a = agg[tier]
+    if (!best || (a.n > 0 && a.s / a.n > best.score)) best = { tier, score: a.n > 0 ? a.s / a.n : -1 }
+  }
+  return { tier: best.tier, reason: 'knn k=' + k + ' neighbors score=' + Math.round(best.score * 100) / 100, conf: Math.min(0.8, pool.length / 100) }
+}
+
+// 质量代理奖励：干净收尾 1 分起，扣工具失败(0.2/次，封顶 0.6)、模型重试(0.2/次，封顶 0.4)、延迟(>90s −0.3, >30s −0.1)
+export function rewardOf(td, tag, dtMs) {
+  if (tag !== 'clean-close') {
+    return { reward: 0, breakdown: { base: 0, toolErrors: td.toolErrors || 0, retries: td.retries || 0, dtMs } }
+  }
+  let reward = 1
+  const toolPenalty = Math.min(0.6, 0.2 * (td.toolErrors || 0))
+  const retryPenalty = Math.min(0.4, 0.2 * (td.retries || 0))
+  reward -= toolPenalty
+  reward -= retryPenalty
+  if (dtMs != null) {
+    if (dtMs > 90000) reward -= 0.3
+    else if (dtMs > 30000) reward -= 0.1
+  }
+  return {
+    reward: Math.max(0, Math.round(reward * 100) / 100),
+    breakdown: { base: 1, toolErrors: td.toolErrors || 0, toolPenalty, retries: td.retries || 0, retryPenalty, dtMs },
+  }
+}
+
+// 把一条奖励记录应用到飞轮（UCB/LinUCB/k-NN/EXP3），replay 与实时更新共用
+export function applyReward(state, rec) {
+  const armKey = rec.clsType + ':' + rec.ucbTier
+  const arm = state.ucb.arms[armKey] || (state.ucb.arms[armKey] = { n: 0, mean: 0 })
+  arm.n += 1
+  arm.mean = arm.mean + (rec.reward - arm.mean) / arm.n
+  state.ucb.total += 1
+
+  const lw = state.lin.tierW[rec.linTier] || []
+  const lr = 1 / (1 + (state.lin.tierN[rec.linTier] || 0))
+  let dot = 0
+  for (let i = 0; i < rec.f.length; i++) dot += (lw[i] || 0) * rec.f[i]
+  for (let i = 0; i < rec.f.length; i++) lw[i] = (lw[i] || 0) + lr * (rec.reward - dot) * rec.f[i]
+  state.lin.tierW[rec.linTier] = lw
+  state.lin.tierN[rec.linTier] += 1
+  state.lin.total += 1
+
+  state.knn.pool.push({ f: rec.f, tier: rec.ucbTier, r: rec.reward })
+  if (state.knn.pool.length > 400) state.knn.pool.shift()
+
+  if (rec.pChosen > 0) {
+    state.exp3.weights[rec.chosen] = (state.exp3.weights[rec.chosen] || 0) *
+      Math.exp(0.3 * (rec.reward / rec.pChosen) / rec.pool.length)
+  }
+  state.exp3.total += 1
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dsh-agentic-router",
+  "version": "1.0.0",
+  "description": "DeepSeek Harness plugin: learning agentic router — rule + UCB + LinUCB + k-NN experts under an EXP3 meta-selector, with a durable quality-reward flywheel",
+  "type": "module",
+  "license": "MIT",
+  "author": "lhl",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "agentic-router",
+    "model-routing",
+    "bandit",
+    "exp3",
+    "flywheel",
+    "llm"
+  ],
+  "exports": {
+    ".": "./dsh/index.js",
+    "./dsh": "./dsh/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dsh",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}