dsh-agentic-router 1.4.1 → 1.5.0

package/README.md

@@ -14,6 +14,12 @@ DeepSeek Harness（DSH）插件：**学习型智能路由（agentic router）+
 向会话日志追加 `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`。
+
 ## 架构
 
 ```

package/docs/DESIGN.md

@@ -226,3 +226,40 @@ dsh-agentic-router/
 - 离线回放：拿历史 session 日志重放，对比 shadow 路由与实际路由的评分分布
 - 影子期 A/B：shadow 评分 vs 默认路由评分，达标才切 active
 - 集成冒烟：mock ctx 注入 agent/request payload，验证 LlmCallConfig 替换与 next() 透传
+
+---
+
+## 13. v1.5.0 步骤级路由设计（已实现）
+
+### 13.1 动机
+
+回合级路由（v1.4.x）每回合决策一次、整回合同一模型。用户期望"单任务内简单步骤用 flash、复杂步骤用 pro"。步骤级路由在回合级基线之上做**按步骤升降档**。
+
+### 13.2 时序依据（为什么对下一步生效）
+
+loop 每步顺序：`inbox.claim()`（发 `agent/inbox/claimed`）→ `systemPrompt.assemble()`（快照模型）→ `agent/pre-step` waterfall → `buildRequest`。因此：
+
+- **inbox 决策**在组装之前 → 回合第一步即生效（零延迟，v1.4.x 主路径）
+- **pre-step 决策**在组装之后 → 追加 header 对**下一步**生效（一阶延迟，设计如此）
+
+### 13.3 信号：上一步的工具调用
+
+`session.deriveMessages()` 取最后一条 assistant 消息的 `tool-call` 块（只读叶子字段）：
+
+| 上一步工具 | 下一步档位 |
+|---|---|
+| 重型：bash/pwsh/write/edit/batch_edit/run_code/workflow/subagent/subagent_fork/terminal/pty/mcp | **strong（pro）** |
+| 轻量：read/glob/grep 等 | 回合基线档 |
+| 无工具（纯文本，通常回合收尾） | 保持现状 |
+
+### 13.4 决策与落盘
+
+- 步骤档位 → `resolveTier` → 目标模型 ≠ 当前模型 → 追加 `request/header`（reason: `router-step`）
+- 每步一条 `steps.jsonl`：`{turn, step, lastTools, stepTier, target, current, applied}`
+- stats 暴露 `stepSwitches` 与 `stepLog`（最近 20 条）
+
+### 13.5 边界与后续
+
+- 奖励飞轮仍按回合结算（回合基线的策略选择），步骤级是确定性规则；未来可把步骤级升降档纳入学习（如按工具调用频率学阈值）
+- 重型集合 `HEAVY_TOOLS` 是静态清单，可配置化
+- 降级方向：重型步骤后的轻量步骤会回到基线（简单任务场景：写代码阶段 pro、前后问答 flash）

package/dsh/index.js

@@ -54,6 +54,15 @@ function fallbackTiers() {
   return { providers, tiers }
 }
 
+// 当前 provider 有候选模型的档位列表（UCB/LinUCB/k-NN 只在这些档位间探索）。
+// provider 缺失或档位表不可用时回退到全部档位（保持专家函数原有行为）。
+function availableTiersFor(provider, modelTiers) {
+  const all = ['fast', 'mid', 'strong']
+  if (!modelTiers || !provider) return all
+  const has = all.filter((t) => tierTarget(t, provider, modelTiers))
+  return has.length ? has : all
+}
+
 function freshState() {
   return {
     mode: 'shadow',
@@ -68,6 +77,8 @@ function freshState() {
     recByTurn: new Map(),
     headerAppends: 0,
     lastActual: null,
+    stepLog: [],
+    counters: { stepSwitches: 0 },
     ucb: { total: 0, arms: {} },
     lin: {
       total: 0,
@@ -179,10 +190,10 @@ function currentProvider(session) {
   return c && typeof c.provider === 'string' ? c.provider : ''
 }
 
-// 核心切换：向会话日志追加 request/header（reason: 'router'），
+// 核心切换：向会话日志追加 request/header（reason: 'router' / 'router-step'），
 // 下一轮 prompt 组装即读到新模型。fast/mid 档去掉 reasoningEffort，
 // 让目标模型走自身默认 effort（避免 flash 不支持 max 而整步失败）。
-function appendRouterHeader(session, targetModel) {
+function appendRouterHeader(session, targetModel, reason = 'router') {
   try {
     const last = session.requestHeader()
     const header = {}
@@ -195,13 +206,40 @@ function appendRouterHeader(session, targetModel) {
     config.model = targetModel
     if (tierOf(targetModel) !== 'strong') delete config.reasoningEffort
     header.config = config
-    session.append('request/header', { header, reason: 'router' })
+    session.append('request/header', { header, reason })
     return true
   } catch (e) {
     return false
   }
 }
 
+// 步骤级路由（v1.5.0）：视为"重型工作"的工具调用——上一步出现它们时，
+// 下一步升级到 strong（pro）处理其结果/继续执行；轻量工具保持回合基线。
+const HEAVY_TOOLS = new Set([
+  'bash', 'pwsh', 'write', 'edit', 'batch_edit', 'run_code', 'workflow',
+  'subagent', 'subagent_fork', 'terminal', 'pty', 'mcp',
+])
+
+// 读取会话里最后一条 assistant 消息的工具调用名（只取叶子字段，不碰活数据）。
+function lastToolCalls(session) {
+  try {
+    const msgs = typeof session.deriveMessages === 'function' ? session.deriveMessages() : null
+    if (!Array.isArray(msgs)) return []
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const m = msgs[i]
+      if (!m || typeof m !== 'object' || m.role !== 'assistant') continue
+      const blocks = m.content
+      if (!Array.isArray(blocks)) return []
+      const out = []
+      for (const b of blocks) {
+        if (b && typeof b === 'object' && b.type === 'tool-call' && typeof b.name === 'string') out.push(b.name)
+      }
+      return out
+    }
+  } catch (e) { /* read-only observation */ }
+  return []
+}
+
 async function refreshModelTiers(llm) {
   if (!llm || typeof llm.listProviders !== 'function') return null
   const providers = await llm.listProviders()
@@ -310,11 +348,14 @@ export function apply(ctx, config = {}) {
     if (state.turnDecision[key]) return null
     const cls = classify(text)
     const f = featuresOf(cls, text)
+    // 只探索当前 provider 有候选模型的档位（跳过无候选的"幽灵档"，
+    // 如 mid 无模型时探索 mid 只会白费并回退到最贵的 strong）
+    const available = availableTiersFor(provider, state.modelTiers)
     const recs = {
       rule: recommendRule(cls),
-      ucb: recommendUcb(cls, state.ucb),
-      lin: recommendLin(cls, f, state.lin),
-      knn: recommendKnn(cls, f, state.knn),
+      ucb: recommendUcb(cls, state.ucb, available),
+      lin: recommendLin(cls, f, state.lin, available),
+      knn: recommendKnn(cls, f, state.knn, available),
     }
     if (state.forced) recs.rule = { tier: 'forced', reason: 'forced', conf: 1 }
     const exp3 = {
@@ -335,6 +376,8 @@ export function apply(ctx, config = {}) {
       currentModel: current, provider, costWeight, costCap,
       estInputTokens: Math.ceil(text.length / 1.5),
       target, applied: false, needsApply: false, actualModel: current,
+      // 回合级基线（供步骤级路由 v1.5.0 参考：无重型工具时保持该档）
+      turnTier: target ? tierOf(target) : null, turnTarget: target,
     }
     const record = {
       seq: state.seq,
@@ -417,6 +460,38 @@ export function apply(ctx, config = {}) {
     } catch (e) {
       log('pre-step capture failed: ' + String(e))
     }
+    // ---- 步骤级路由（v1.5.0）----
+    // pre-step 在组装之后触发 → 此处追加 header 对下一步生效（一阶延迟，设计如此）。
+    // 信号：上一步 assistant 消息的工具调用。重型工具（写代码/执行/子agent）→ 下一步
+    // 升级 strong（pro）；轻量/无工具 → 回到回合基线档。
+    try {
+      const session = sessionOf(payload)
+      if (!session) return next()
+      const key = fullKey(payload)
+      const td = state.turnDecision[key]
+      if (!td || td.finalized) return next()
+      const tools = lastToolCalls(session)
+      if (!tools.length) return next() // 上一步是纯文本（通常回合收尾），保持现状
+      const heavy = tools.some((n) => HEAVY_TOOLS.has(n))
+      const stepTier = heavy ? 'strong' : (td.turnTier || null)
+      if (!stepTier) return next()
+      const provider = td.provider || currentProvider(session) || ''
+      const resolved = resolveTier(stepTier, provider, state.modelTiers)
+      const target = resolved.target
+      const cur = currentModel(session)
+      const changed = target && target !== cur
+      // 注意：pre-step 在组装之后、buildRequest（loop 追加自己的 header）之前触发。
+      // 这里直接追加会被本步 buildRequest 的 change(旧模型) 覆盖（与 v1.4.0 冷启动同款竞态）。
+      // 因此只决策并挂起，真正追加推迟到 llm/stream 收尾（此时 loop 的 header 已落盘）。
+      if (changed) td.stepTarget = target
+      const stepRec = { turn: key, step: payload.step, lastTools: tools.slice(0, 5), stepTier, target, current: cur, applied: false, pending: changed, ts: Date.now() }
+      if (changed) td.stepRec = stepRec
+      state.stepLog.push(stepRec)
+      if (state.stepLog.length > 30) state.stepLog.shift()
+      try { store.appendJsonl('steps.jsonl', stepRec) } catch (e) { /* 落盘尽力而为 */ }
+    } catch (e) {
+      log('step routing failed: ' + String(e))
+    }
     return next()
   })
 
@@ -487,14 +562,25 @@ export function apply(ctx, config = {}) {
           const key = sid ? state.openTurns.get(sid) : null
           const td = key ? state.turnDecision[key] : null
           if (td && !td.finalized) {
-            // 兜底应用：request 路径决策未应用时，在 header 落盘后补切换
-            if (td.needsApply && !td.applied) {
-              let session = null
-              try {
-                const sessions = ctx.get('sessions')
-                if (sessions && typeof sessions.get === 'function') session = sessions.get(sid) || null
-              } catch (e) { session = null }
-              if (session) applyDecision(session, key, td, td.rec, td.target)
+            // 延迟应用（此时循环自身 header 已落盘，追加无竞态）：
+            // 1) 步骤级路由挂起的升降档（router-step）
+            // 2) request 路径兜底决策（needsApply）
+            let session = null
+            try {
+              const sessions = ctx.get('sessions')
+              if (sessions && typeof sessions.get === 'function') session = sessions.get(sid) || null
+            } catch (e) { session = null }
+            if (session) {
+              if (td.stepTarget && td.stepTarget !== currentModel(session)) {
+                const ok = appendRouterHeader(session, td.stepTarget, 'router-step')
+                if (ok) {
+                  state.counters.stepSwitches++
+                  if (td.stepRec) { td.stepRec.applied = true }
+                  log('STEP-SWAP -> ' + td.stepTarget + (td.stepRec ? ' (tools: ' + td.stepRec.lastTools.join(',') + ')' : ''))
+                }
+              }
+              td.stepTarget = null
+              if (td.needsApply && !td.applied) applyDecision(session, key, td, td.rec, td.target)
             }
             const u = td.usage || { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, reasoningTokens: 0, estimated: false }
             const model = (options && typeof options.model === 'string' && options.model) || td.currentModel || ''
@@ -620,9 +706,11 @@ export function apply(ctx, config = {}) {
         totalDecisions: state.seq,
         modelTiers: state.modelTiers,
         prices,
-        mechanism: 'request/header append (agent/inbox/claimed)',
+        mechanism: 'request/header append (inbox turn-level + pre-step step-level v1.5.0)',
         lastActual: state.lastActual,
         headerAppends: state.headerAppends,
+        stepSwitches: state.counters.stepSwitches,
+        stepLog: state.stepLog.slice(-20),
         flywheel: {
           ucb: state.ucb,
           lin: { total: state.lin.total, tierN: state.lin.tierN, tierW: state.lin.tierW },
@@ -633,7 +721,7 @@ export function apply(ctx, config = {}) {
           recentRewards: store.loadJsonl('rewards.jsonl').slice(-20),
         },
         recent: state.decisions.slice(-20),
-        note: '切换真实性验证：headerAppends 为本进程追加的 request/header 次数；lastActual 为最近一步真实出网模型；decisions[].applied=true 且 swapped=true 即真实切换成功',
+        note: '切换真实性验证：headerAppends 为本进程追加的 request/header 次数；stepSwitches 为步骤级升级/降级次数（stepLog 有明细）；lastActual 为最近一步真实出网模型',
       }
     },
   })

package/dsh/strategies.js

@@ -40,11 +40,13 @@ export function recommendRule(cls) {
   return { tier: want, reason: 'rule threshold complexity=' + cls.complexity, conf: 0.5 }
 }
 
-// UCB：mean + c·√(lnN/n)；未探索臂上界∞，多个∞平局时按总拉动数轮转（避免永远选 fast）
-export function recommendUcb(cls, ucbState) {
+// UCB：mean + c·√(lnN/n)；未探索臂上界∞，多个∞平局时按总拉动数轮转（避免永远选 fast）。
+// availableTiers 由调用方传入（当前 provider 有候选模型的档位）——不探索无候选的"幽灵档"
+// （如 mid 无模型时，探索 mid 只会白费并回退到最贵的 strong）。
+export function recommendUcb(cls, ucbState, availableTiers = ['fast', 'mid', 'strong']) {
   const arms = ucbState.arms
   const scores = []
-  for (const tier of ['fast', 'mid', 'strong']) {
+  for (const tier of availableTiers) {
     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 })
@@ -61,11 +63,12 @@ export function recommendUcb(cls, ucbState) {
   }
 }
 
-// LinUCB（近似实现）：每档线性权重 w·f + 探索项；梯度更新，探索项随档样本数衰减
-export function recommendLin(cls, f, linState) {
+// LinUCB（近似实现）：每档线性权重 w·f + 探索项；梯度更新，探索项随档样本数衰减。
+// availableTiers 同上：只评估有候选模型的档位。
+export function recommendLin(cls, f, linState, availableTiers = ['fast', 'mid', 'strong']) {
   const tn = linState.tierN
   let best = null
-  for (const tier of ['fast', 'mid', 'strong']) {
+  for (const tier of availableTiers) {
     const w = linState.tierW[tier] || []
     let dot = 0
     for (let i = 0; i < f.length; i++) dot += (w[i] || 0) * f[i]
@@ -80,8 +83,9 @@ export function recommendLin(cls, f, linState) {
   }
 }
 
-// k-NN：欧氏距离取 k=5 邻居，按邻居平均奖励选档
-export function recommendKnn(cls, f, knnState) {
+// k-NN：欧氏距离取 k=5 邻居，按邻居平均奖励选档。
+// availableTiers 同上：只从有候选模型的档位里选最佳。
+export function recommendKnn(cls, f, knnState, availableTiers = ['fast', 'mid', 'strong']) {
   const pool = knnState.pool
   if (pool.length < 5) return { tier: null, reason: 'knn cold (' + pool.length + '/5 seed)', conf: 0 }
   const scored = []
@@ -98,7 +102,7 @@ export function recommendKnn(cls, f, knnState) {
     if (agg[t]) { agg[t].n += 1; agg[t].s += scored[i].e.r }
   }
   let best = null
-  for (const tier of ['fast', 'mid', 'strong']) {
+  for (const tier of availableTiers) {
     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 }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-agentic-router",
-  "version": "1.4.1",
-  "description": "DeepSeek Harness plugin: learning agentic router — rule + UCB + LinUCB + k-NN experts under an EXP3 meta-selector, with a durable quality-reward flywheel and REAL model switching via the session request-header precedence chain (v1.4.1, cold-start fix)",
+  "version": "1.5.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, REAL model switching via the session request-header precedence chain, and STEP-LEVEL routing (v1.5.0)",
   "type": "module",
   "license": "MIT",
   "author": "lhl",