dsh-model-rotator 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 User-visible changes, newest first. Commit hashes in brackets.
 
+## 0.2.6
+- **Fixed: other channels of the same model were deduplicated out of the walk.** This is the real problem 0.2.5 uncovered once the classification was right: when WorkBuddy met its quota wall, **buddy and trae — the same model on other channels — were healthy**, but "one channel per model family" kept them out of the candidate list entirely, so the turn ended on the quota error with a working route sitting one slot away. A family now keeps up to **two channels**: the ranked winner plus one proven-usable backup. A cooling backup is dropped, since dispatching it would walk into the same wall. The switch notice is already deduplicated by model id, so arriving at a second channel of the same model is not announced as "switched to the same model again".
+- Measured: before the fix the walk held one channel of `deepseek-v4.1-flash` and `buddy` (ok=1538, healthy) was absent; after it holds three and `buddy` is back. [`TBD`]
+
+## 0.2.5
+- **Fixed: an exhausted quota read as a rate limit, so the switch never happened.** WorkBuddy answers "可用账号均在限流中，最近一个将于 … 解禁" — every account exhausted. Classified as `rate-limit` it cooled for 60 seconds and retried the same wall; one evening accumulated 702 failures. An account pool that is entirely unavailable is now recognised as `quota` and rests like any other balance wall.
+- **New: the release time is parsed out of the message.** When the provider states when it comes back, that beats any calendar policy. `parseReleaseTime()` accepts `2026/10/18 00:29:52`, `2026-10-18 00:29:52` and ISO forms; a parsed time becomes the exact cooldown (measured here: 60 seconds became 1.7 hours), and only an unparseable message falls back to the next-day rule.
+- **Fixed: a switch was not persisted.** The switch notice was queued and then returned, so `scheduleStatsSave()` never ran — a restart showed the old model still in use. The save happens with the enqueue now.
+- **Improved: a pin defers while it cools.** A model pinned with `model_rotator_select` took the head on every turn even while cooling, so every turn opened by walking into the same wall. The pin now applies only while the model is healthy; the ranking decides during cooldown and the pin returns by itself afterwards. [`a2d5a0c`]
+
 ## 0.2.4
 - **Docs**: adds this bilingual changelog, listed in the manifest and gated by release-check; the README and repository description were refreshed too. The npm package now carries the changelog with each release. Also fixes a crash in this gate: the SHA check fed a comment line to readFileSync, so the gate died with ENOENT and hid every other check behind it. [`fc14e99`]
 

package/CHANGELOG.zh.md

@@ -4,6 +4,16 @@
 
 本文件按版本记录用户可感知的变化。方括号内为对应提交。
 
+## 0.2.6
+- **修复：同一模型的其它渠道被去重挡在候选之外**。这是 0.2.5 修好分类之后暴露出来的真问题：WorkBuddy 撞上额度墙时，**buddy 与 trae 这两个同模型的渠道是健康的**，但「每个模型家族只保留一个渠道」的规则让它们根本不在候选里，于是整轮以额度错误结束 —— 而可用线路就在旁边。现每个家族保留最多 **2 个渠道**（排名靠前的一个 + 一个经证实用可用的备份）；备份若正在冷却则不保留，因为那等于再撞一次同一堵墙。切换通知本就按模型 id 去重，所以落到同模型的第二个渠道不会被播报成「又切到同一模型」。
+- 实测：修复前候选列表里 `deepseek-v4.1-flash` 只占 1 个渠道，`buddy`（ok=1538，健康）缺失；修复后占 3 个，`buddy` 回到列表中。[`TBD`]
+
+## 0.2.5
+- **修复：额度耗尽被误判为限流，导致不切换**。WorkBuddy 的报错是「可用账号均在限流中，最近一个将于 … 解禁」，判成 `rate-limit` 就按 60 秒冷却反复重试同一堵墙（实测一晚累计 702 次失败）。现新增「账号池耗尽」识别归入 `quota`，与「余额不足」同一处置。
+- **新增：解析报错里的解禁时间**。提供方既然写明了何时恢复，就比任何日历策略都准。`parseReleaseTime()` 支持 `2026/10/18 00:29:52`、`2026-10-18 00:29:52` 与 ISO 形式；解析到就用作精确冷却（本次实测把 60 秒变成 1.7 小时），解析不到才回落到次日策略。
+- **修复：切换后未落盘**。切换通知入队后直接 `return`，`scheduleStatsSave()` 没有被调用，所以重启后看不到这次切换发生过。现在入队时一并保存。
+- **改进：pin 在冷却时让位**。此前被 `model_rotator_select` 置顶的模型即使正在冷却也每轮抢在第一位，于是每轮都先撞一次墙再切换。现只在模型健康时置顶，冷却期间交给排序，冷却结束后自动回到首位。[`a2d5a0c`]
+
 ## 0.2.4
 - **文档**：新增中英双语更新说明（本文件），并纳入发布清单与发布门；README 与仓库首页说明同步更新。npm 包开始随版本携带 CHANGELOG。同时修复发布门自身的一处崩溃：SHA 校验把清单注释行当成文件名读，导致整门以 ENOENT 中止、掩盖其余全部检查。[`fc14e99`]
 

package/index.js

@@ -392,6 +392,16 @@ export function isNonChatModelId(provider, id) {
 /** Hard ceiling on candidates considered per turn, regardless of config. */
 const HARD_MAX_CANDIDATES = 8
 
+/**
+ * How many channels of one model family may share the candidate walk.
+ *
+ * One per family was too few - a channel failing while its healthy siblings were
+ * unreachable is exactly the report this constant answers - and all of them is
+ * too many, because five channels of one model would spend the entire budget on
+ * a single model. Two keeps the representative and one proven-healthy backup.
+ */
+const FAMILY_CHANNELS_MAX = 2
+
 /**
  * Hard ceiling on same-model retries per candidate, regardless of config.
  *
@@ -703,6 +713,12 @@ const FAILURE_KIND_TESTS = [
   // that classification would cost the daily rest a dead balance needs.
   ['unsupported', /(does not support|doesn't support|unsupported|not supported|no such model|unknown model|model not found|invalid model|model is not available)/i],
   ['auth', /(invalid[ _-]*api[ _-]*key|api[ _-]*key[ _-]*(invalid|missing|expired)|unauthori[sz]ed|unauthenticated|authentication|credential|permission denied|forbidden|401|403|鉴权|密钥|授权失败|认证失败)/i],
+  // An account pool that is entirely unavailable is a quota wall wearing the
+  // word "rate limit". WorkBuddy answers "可用账号均在限流中，最近一个将于 … 解禁" —
+  // every account exhausted, with the release timestamp in the sentence. Classified
+  // as rate-limit it cooled for 60s and retried the same wall 702 times in one
+  // evening; as quota it rests until the pool actually comes back.
+  ['quota', /(?:可用)?账号[^。，,;；]{0,6}(?:均|全部|都)[^。，,;；]{0,8}(?:限流|不可用|耗尽|用尽)|均在限流|均不可用|all accounts?(?:[ _-]+\w+){0,3}[ _-]+(?:exhausted|unavailable|rate[ _-]*limited)|every account[ _-]+(?:is[ _-]+)?(?:exhausted|unavailable)/i],
   ['rate-limit', /(rate[ _-]*limit|too many requests|request[ _-]*limit|throttl|429|限流|请求过于频繁|过于频繁|qps)/i],
   ['server', /(internal[ _-]*server[ _-]*error|bad[ _-]*gateway|service[ _-]*unavailable|server[ _-]*(error|overload)|overloaded|gateway[ _-]*timeout|50[0-9])/i],
   ['network', /(econnreset|econnrefused|etimedout|enotfound|eai_again|socket|network|fetch failed|timed?[ _-]?out|timeout|disconnected|connection (closed|reset|refused)|aborted)/i],
@@ -768,9 +784,54 @@ export function quotaRestUntil(nowMs, cfg) {
   return Math.max(boundary.getTime(), nowMs + floor)
 }
 
+/**
+ * A release time the provider stated in its own words, in epoch ms, or 0.
+ *
+ * A quota message often says exactly when the pool comes back — WorkBuddy writes
+ * "最近一个将于 2026/10/18 00:29:52 解禁". That timestamp is strictly better than any
+ * policy we could invent: it is the provider telling us when to try again. Fixed
+ * midnight arithmetic ignored it and could either sleep far too long or wake into
+ * the same wall.
+ *
+ * Accepts the shapes that actually appear: `2026/10/18 00:29:52`, `2026-10-18
+ * 00:29:52`, and an ISO 8601 stamp. A date with no time is treated as that day's
+ * midnight. The value is read in the host's local zone, which is the zone these
+ * messages are written in.
+ *
+ * Returns 0 when nothing parseable is present, so the caller falls back to policy.
+ * Exported as a test seam: this is date arithmetic on prose, exactly the kind of
+ * thing that should be pinned by an offline assertion.
+ */
+export function parseReleaseTime(message) {
+  const text = String(message ?? '')
+  if (text === '') return 0
+  const patterns = [
+    /(\d{4})[/-](\d{1,2})[/-](\d{1,2})[ T](\d{1,2}):(\d{2})(?::(\d{2}))?/,
+    /(\d{4})[/-](\d{1,2})[/-](\d{1,2})/,
+  ]
+  for (const re of patterns) {
+    const m = text.match(re)
+    if (m === null) continue
+    const [, y, mo, d, h = '0', mi = '0', sec = '0'] = m
+    const at = new Date(
+      Number(y), Number(mo) - 1, Number(d),
+      Number(h), Number(mi), Number(sec), 0,
+    )
+    const ms = at.getTime()
+    // A provider sentence about the past is a stale copy, not a release time.
+    if (Number.isFinite(ms) && ms > 0) return ms
+  }
+  return 0
+}
+
 /** Instant until which this failure keeps the candidate out of the ranking. */
-function cooldownUntilFor(stat, cfg, nowMs, errorKind) {
-  if (errorKind === 'quota') return quotaRestUntil(nowMs, cfg)
+function cooldownUntilFor(stat, cfg, nowMs, errorKind, message) {
+  if (errorKind === 'quota') {
+    // The provider's own release timestamp outranks our calendar policy.
+    const stated = parseReleaseTime(message)
+    if (stated > nowMs) return stated
+    return quotaRestUntil(nowMs, cfg)
+  }
   return nowMs + cooldownFor(stat, cfg)
 }
 
@@ -1458,27 +1519,52 @@ export function apply(ctx, config = {}, runtime = {}) {
     }
     ranked.sort((a, b) => (b.score !== a.score ? b.score - a.score : a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
 
-    // One candidate per model *family*, not one per channel. The same model on
-    // five channels shares its fate - one quota wall, one dead endpoint - so
-    // keeping all five in the walk spends the whole candidate budget retrying
-    // what is effectively one model, and the switch notice then reads as
-    // "switched to the same model again". The best-scoring channel of each
-    // family survives; its siblings wait for another turn (no cooldown is
-    // written for them, so a later walk can still pick them).
-    const familySeen = new Set()
+    // A model family contributes more than one channel - but not all of them.
+    //
+    // The same model on five channels used to occupy five candidate slots, which
+    // spent the whole budget retrying what is effectively one model. Collapsing it
+    // to exactly one channel fixed that and introduced a worse failure: a channel is
+    // not the whole family. WorkBuddy met its quota wall while buddy and trae, the
+    // same model on other channels, were healthy and serving - and the walk could
+    // not reach them, because the family had already been represented by the channel
+    // that failed. The turn ended on the wall with a working route sitting one slot
+    // away.
+    //
+    // So a family keeps up to FAMILY_CHANNELS_MAX channels, ranked, and a sibling is
+    // only kept while it is actually usable. Cooling siblings are dropped: they would
+    // be dispatched into the same wall the representative just hit, and the walk
+    // already knows better. The switch-notice dedup keys on the model id, so arriving
+    // at a second channel of the same model does not announce "switched to the same
+    // model again" - the reason that motivated one-per-family in the first place is
+    // handled where it belongs.
+    const familyCount = new Map()
     const byFamily = []
     for (const row of ranked) {
       const family = String(row.pair.model).toLowerCase()
-      if (familySeen.has(family)) continue
-      familySeen.add(family)
+      const used = familyCount.get(family) ?? 0
+      if (used >= FAMILY_CHANNELS_MAX) continue
+      const stat = statFor(row.key)
+      // The family's first channel is always kept - it is the ranked winner and the
+      // representation of that model. Only the siblings have to prove they are usable.
+      if (used > 0 && stat.cooldownUntil > nowMs) continue
+      familyCount.set(family, used + 1)
       byFamily.push(row)
     }
     const ordered = [current, ...byFamily.map(row => row.pair)]
 
     // A pin short-circuits the ranking: the user asked for this head explicitly.
+    //
+    // Unless it is cooling down. A pin is a preference about which healthy model to
+    // try first, not a promise to walk into the same wall every turn: a pinned model
+    // that just failed would be dispatched first on every subsequent turn, fail
+    // again, and make the reader watch the same switch over and over. While it cools
+    // the ranking decides, and the model returns to the head by itself once the
+    // cooldown clears - the pin is not forgotten, only deferred.
     if (pinned !== '' && pinned !== current.provider + '/' + current.model) {
       const at = ordered.findIndex(pair => pair.provider + '/' + pair.model === pinned)
-      if (at > 0) ordered.unshift(ordered.splice(at, 1)[0])
+      const pinnedStat = at > 0 ? statFor(pinned) : null
+      const pinnedCooling = pinnedStat !== null && pinnedStat.cooldownUntil > nowMs
+      if (at > 0 && !pinnedCooling) ordered.unshift(ordered.splice(at, 1)[0])
     }
 
     return ordered.slice(0, Math.min(cfg.maxCandidates, HARD_MAX_CANDIDATES))
@@ -1836,6 +1922,11 @@ export function apply(ctx, config = {}, runtime = {}) {
                 to: { provider: pair.provider, model: pair.model, displayName: pair.displayName ?? '' },
                 reason: classifyFailureKind(String(lastFailure ?? '')),
               })
+              // The switch itself is the event worth persisting. Without this the
+              // counters above were written but the *decision* was not, so a restart
+              // showed the old model still in use and the switch looked like it had
+              // never happened.
+              scheduleStatsSave()
             }
           }
           return
@@ -1880,7 +1971,7 @@ export function apply(ctx, config = {}, runtime = {}) {
           // buries the provider's words under ours.
           if (!hostRefusal || trustedFailure) {
             stat.consecutiveFailures += 1
-            stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind)
+            stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind, failedBecause)
           }
           // The error chunk is already in the consumer's hands, so the walk ends
           // here either way - and it must, because a fault of ours would repeat
@@ -1924,7 +2015,7 @@ export function apply(ctx, config = {}, runtime = {}) {
         // route stays fully available to the next turn.
         if (!hostRefusal || trustedFailure) {
           stat.consecutiveFailures += 1
-          stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind)
+          stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind, failedBecause)
         }
 
         // A fault of ours ends the walk. Every further candidate would hit the
@@ -2625,7 +2716,7 @@ export function apply(ctx, config = {}, runtime = {}) {
           const failedKind = classifyFailureKind(failure)
           stat.failures += 1
           stat.consecutiveFailures += 1
-          stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind)
+          stat.cooldownUntil = cooldownUntilFor(stat, cfg, Date.now(), failedKind, failedBecause)
           stat.lastError = failure
           stat.lastErrorKind = failedKind
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-rotator",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Model auto-ranking and transparent failover for DeepSeek Harness: ranks discovered models by measured connectivity and speed, switches to the next candidate inside the same turn when the current one is unusable, and ships a grouped model list with per-channel switches. Never modifies model or provider configuration.",
   "type": "module",
   "main": "index.js",