dsh-account-pool 0.1.0

package/lib/selector.js

@@ -0,0 +1,343 @@
+/**
+ * 账号选号器：决定「这次请求用哪个账号」。
+ *
+ * 策略复刻自已验证的 Go 网关（workbuddy2api），三因子加权 + Top-5 抽签：
+ *
+ *   weight = 积分比例 × 10 + 闲置补偿 + 成功率 × 3
+ *
+ *   - 积分比例：该号积分 / 候选集最高积分。让积分多的多分担，但要和闲置、
+ *     成功率一起看，不是谁分高就一直用谁。
+ *   - 闲置补偿：闲置越久加权越高，防止某号长期轮不到。
+ *   - 成功率：成功次数 / 总次数，避免一直打故障号。
+ *
+ * 取权重最高的 5 个作为候选池，再在池内按权重加权随机抽签。这一步是为了
+ * 「打散热点」——只按权重降序取第一名的话，积分最高的号会被一直打。
+ *
+ * 失败处置：
+ *   - 429 限流   → 软冷却，600s 起指数退避
+ *   - 402 欠费   → 硬冷却到次日 04:00
+ *   - 连续失败   → 熔断，退避 30 分钟起
+ *   - 全部不可用 → 不报错，从冷却号里挑最早到期的顶上（兜底）
+ */
+
+/** 一天 04:00 这个恢复点：欠费账号的硬冷却目标时刻。 */
+function nextFourAM(now) {
+  const at = new Date(now)
+  at.setHours(4, 0, 0, 0)
+  if (at.getTime() <= now) at.setDate(at.getDate() + 1)
+  return at.getTime()
+}
+
+/** 数值夹取。 */
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * 单个账号的运行期状态。持久化部分（成功/失败计数）由调用方存取，
+ * 冷却与熔断是进程内状态，重启即重置——与网关行为一致。
+ */
+class AccountState {
+  constructor(accountId) {
+    this.accountId = accountId
+    /** 冷却截止时间戳；0 表示不冷却。 */
+    this.cooldownUntilMs = 0
+    /** 熔断截止时间戳；0 表示未熔断。 */
+    this.breakerUntilMs = 0
+    /** 连续失败次数，成功即清零。 */
+    this.consecutiveFails = 0
+    /** 软冷却连续触发次数，决定退避倍数。 */
+    this.softStreak = 0
+    /** 上次被选中的时刻，用于闲置补偿。 */
+    this.lastUsedAtMs = 0
+    /** 累计成功 / 失败次数，算成功率用。 */
+    this.successCount = 0
+    this.failCount = 0
+    /** 已知积分（用于加权）；未知时按中性值参与。 */
+    this.credits = 0
+    /**
+     * 最近一次被停用的原因：'breaker'（熔断）| 'hard_credit' | 'soft_rate'
+     * | 'session_dead' | null。前端据此显示准确的状态文字，不用靠
+     * 「连续失败次数」猜——阈值是可配置的，猜会猜错。
+     */
+    this.stopReason = null
+  }
+
+  /** 是否因冷却或熔断暂时不可用。 */
+  isCooling(now) {
+    return this.cooldownUntilMs > now || this.breakerUntilMs > now
+  }
+
+  /** 冷却截止时刻（取两者较晚者）。 */
+  cooldownEnd(now) {
+    return Math.max(this.cooldownUntilMs, this.breakerUntilMs)
+  }
+}
+
+/**
+ * 选号器。
+ *
+ * 用法：
+ *   const picker = new AccountPicker({ softCooldownMs, breakerThreshold, ... })
+ *   const id = picker.pick(候选账号 id 列表, 会话键)
+ *   picker.reportSuccess(id) / picker.reportFailure(id, kind)
+ */
+export class AccountPicker {
+  /**
+   * @param {object} options
+   * @param {number} options.softCooldownMs  软冷却基数（默认 600s）
+   * @param {number} options.softCooldownMaxMs 软冷却上限（默认 2h）
+   * @param {number} options.breakerThreshold 连续失败多少次熔断（默认 3）
+   * @param {number} options.breakerCooldownMs 熔断基数（默认 30m）
+   * @param {number} options.breakerCooldownMaxMs 熔断上限（默认 6h）
+   * @param {number} options.stickyTtlMs 会话粘性存活时间（默认 30m）
+   * @param {number} options.idleWeightPerHour 每小时闲置补偿（默认 0.5）
+   * @param {number} options.idleWeightMax 闲置补偿上限（默认 5）
+   * @param {() => number} options.now 取当前时间，便于测试注入
+   */
+  constructor(options = {}) {
+    this.softCooldownMs = options.softCooldownMs ?? 600_000
+    this.softCooldownMaxMs = options.softCooldownMaxMs ?? 2 * 3600_000
+    this.breakerThreshold = options.breakerThreshold ?? 3
+    this.breakerCooldownMs = options.breakerCooldownMs ?? 30 * 60_000
+    this.breakerCooldownMaxMs = options.breakerCooldownMaxMs ?? 6 * 3600_000
+    this.stickyTtlMs = options.stickyTtlMs ?? 30 * 60_000
+    this.idleWeightPerHour = options.idleWeightPerHour ?? 0.5
+    this.idleWeightMax = options.idleWeightMax ?? 5
+    this.now = options.now ?? (() => Date.now())
+
+    /** @type {Map<string, AccountState>} */
+    this.states = new Map()
+    /** 会话粘性：会话键 → { accountId, expiresAtMs } */
+    this.sticky = new Map()
+  }
+
+  /** 取（必要时创建）一个账号的状态。 */
+  stateOf(accountId) {
+    let state = this.states.get(accountId)
+    if (state === undefined) {
+      state = new AccountState(accountId)
+      this.states.set(accountId, state)
+    }
+    return state
+  }
+
+  /** 更新账号积分（拉余额后调用），只影响加权，不影响可用性。 */
+  setCredits(accountId, credits) {
+    this.stateOf(accountId).credits = Number(credits) || 0
+  }
+
+  /**
+   * 算某个账号的权重。三因子加权，理由见文件头注释。
+   * @param {AccountState} state
+   * @param {number} maxCredits 候选集里的最高积分，作为归一化基准
+   * @param {number} now
+   */
+  weightOf(state, maxCredits, now) {
+    const creditRatio = maxCredits > 0 ? state.credits / maxCredits : 1
+    const idleHours = state.lastUsedAtMs === 0
+      ? 24 // 从未用过 → 给满分闲置补偿，让它有机会上场
+      : (now - state.lastUsedAtMs) / 3600_000
+    const idleWeight = clamp(idleHours * this.idleWeightPerHour, 0, this.idleWeightMax)
+    const total = state.successCount + state.failCount
+    // 无记录给中性值 1.5（略高于 1，鼓励新号参与试错）
+    const successRate = total === 0 ? 1.5 : state.successCount / total
+    return creditRatio * 10 + idleWeight + successRate * 3
+  }
+
+  /**
+   * 选一个账号。
+   *
+   * @param {string[]} candidateIds 本次可用的账号 id 列表
+   * @param {string} [sessionKey] 会话键；给了就优先复用该会话已绑定的账号
+   * @returns {string|undefined} 选中的账号 id；一个都没有返回 undefined
+   */
+  pick(candidateIds, sessionKey) {
+    if (candidateIds.length === 0) return undefined
+    const now = this.now()
+
+    // 会话粘性：同一会话尽量复用同一账号，多轮对话不跳号。
+    if (sessionKey !== undefined && sessionKey !== '') {
+      const bound = this.sticky.get(sessionKey)
+      if (bound !== undefined) {
+        if (bound.expiresAtMs > now && candidateIds.includes(bound.accountId)) {
+          const state = this.stateOf(bound.accountId)
+          if (!state.isCooling(now)) {
+            // 续期：滚动延长，活跃会话不会中途被解绑。
+            bound.expiresAtMs = now + this.stickyTtlMs
+            state.lastUsedAtMs = now
+            return bound.accountId
+          }
+        }
+        if (bound.expiresAtMs <= now) this.sticky.delete(sessionKey)
+      }
+    }
+
+    // 过滤掉冷却中 / 熔断中的账号。
+    const usable = candidateIds.filter(id => !this.stateOf(id).isCooling(now))
+
+    if (usable.length === 0) {
+      // 兜底：全都在冷却时，挑最早到期的顶上，避免直接失败。
+      // 这是有意的降级——宁可让用户拿到可能限流的响应，也不要空手而归。
+      let earliest
+      let earliestEnd = Infinity
+      for (const id of candidateIds) {
+        const end = this.stateOf(id).cooldownEnd(now)
+        if (end < earliestEnd) {
+          earliestEnd = end
+          earliest = id
+        }
+      }
+      if (earliest !== undefined) this.bind(sessionKey, earliest, now)
+      return earliest
+    }
+
+    // 取 Top-5 候选（按权重降序），再在池内加权随机抽签。
+    const maxCredits = Math.max(...usable.map(id => this.stateOf(id).credits))
+    const weighted = usable
+      .map(id => ({ id, weight: this.weightOf(this.stateOf(id), maxCredits, now) }))
+      .sort((a, b) => b.weight - a.weight || a.id.localeCompare(b.id))
+      .slice(0, 5)
+
+    const totalWeight = weighted.reduce((sum, entry) => sum + entry.weight, 0)
+    let chosen = weighted[0].id
+    if (totalWeight > 0) {
+      let roll = Math.random() * totalWeight
+      for (const entry of weighted) {
+        roll -= entry.weight
+        if (roll <= 0) {
+          chosen = entry.id
+          break
+        }
+      }
+    }
+
+    this.stateOf(chosen).lastUsedAtMs = now
+    this.bind(sessionKey, chosen, now)
+    return chosen
+  }
+
+  /** 记一次会话粘性绑定。 */
+  bind(sessionKey, accountId, now) {
+    if (sessionKey === undefined || sessionKey === '') return
+    this.sticky.set(sessionKey, { accountId, expiresAtMs: now + this.stickyTtlMs })
+  }
+
+  /** 请求成功：清失败计数、清冷却、清软冷却退避。 */
+  reportSuccess(accountId) {
+    const state = this.stateOf(accountId)
+    state.successCount += 1
+    state.consecutiveFails = 0
+    state.cooldownUntilMs = 0
+    state.breakerUntilMs = 0
+    state.softStreak = 0
+    state.stopReason = null
+  }
+
+  /**
+   * 请求失败：按失败类型处置账号。
+   * @param {string} accountId
+   * @param {string} kind classifyUpstreamError 的返回值
+   * @returns {string} 人类可读的处置说明，用于日志
+   */
+  reportFailure(accountId, kind) {
+    const state = this.stateOf(accountId)
+    const now = this.now()
+    state.failCount += 1
+    state.consecutiveFails += 1
+
+    // 熔断判定优先于具体冷却：连续失败够多就先停一阵子。
+    if (state.consecutiveFails >= this.breakerThreshold) {
+      const backoff = clamp(
+        this.breakerCooldownMs * 2 ** (state.consecutiveFails - this.breakerThreshold),
+        this.breakerCooldownMs,
+        this.breakerCooldownMaxMs,
+      )
+      state.breakerUntilMs = now + backoff
+      state.stopReason = 'breaker'
+      return `连续失败 ${state.consecutiveFails} 次，熔断 ${Math.round(backoff / 60000)} 分钟`
+    }
+
+    if (kind === 'hard_credit') {
+      state.cooldownUntilMs = nextFourAM(now)
+      state.stopReason = 'hard_credit'
+      return '积分耗尽，冷却至次日 04:00'
+    }
+
+    if (kind === 'soft_rate') {
+      // 软冷却时长本身也指数退避：连续被限流的号越退越久。
+      const backoff = clamp(
+        this.softCooldownMs * 2 ** state.softStreak,
+        this.softCooldownMs,
+        this.softCooldownMaxMs,
+      )
+      state.softStreak += 1
+      state.cooldownUntilMs = now + backoff
+      state.stopReason = 'soft_rate'
+      return `限流，冷却 ${Math.round(backoff / 1000)} 秒`
+    }
+
+    if (kind === 'session_dead') {
+      // 掉线的号先短暂冷却；连续掉线会走到上面的熔断分支。
+      state.cooldownUntilMs = now + 60_000
+      state.stopReason = 'session_dead'
+      return '会话失效，冷却 60 秒'
+    }
+
+    return `失败（${kind}），换号重试`
+  }
+
+  /** 手动解冻一个账号（清全部冷却与失败计数）。 */
+  /**
+   * 手动解冻一个账号：清掉它的冷却、熔断与失败计数。
+   *
+   * 只解绑**该账号自己**的会话粘性，不动其他账号的绑定——
+   * 之前直接 `sticky.clear()` 会把所有会话的绑定一起清掉，
+   * 导致正在进行的多轮对话被踢到别的账号上。
+   *
+   * 注意不清 successCount / failCount：那是账号的历史统计，
+   * 解冻只该影响「当前是否可用」，不该抹掉历史。
+   */
+  revive(accountId) {
+    const state = this.stateOf(accountId)
+    state.cooldownUntilMs = 0
+    state.breakerUntilMs = 0
+    state.consecutiveFails = 0
+    state.softStreak = 0
+    state.stopReason = null
+
+    // 只解绑指向该账号的会话
+    for (const [sessionKey, bound] of this.sticky) {
+      if (bound.accountId === accountId) this.sticky.delete(sessionKey)
+    }
+  }
+
+  /** 导出各账号可观测状态，供设置页展示。 */
+  snapshot() {
+    const now = this.now()
+    const out = {}
+    for (const [id, state] of this.states) {
+      const cooling = state.isCooling(now)
+      out[id] = {
+        cooling,
+        cooldownUntilMs: cooling ? state.cooldownEnd(now) : 0,
+        // 停用原因：冷却中才给，供界面显示准确文字
+        stopReason: cooling ? state.stopReason : null,
+        consecutiveFails: state.consecutiveFails,
+        successCount: state.successCount,
+        failCount: state.failCount,
+        credits: state.credits,
+        lastUsedAtMs: state.lastUsedAtMs,
+      }
+    }
+    return out
+  }
+
+  /** 清理过期的粘性绑定，防止 Map 无限增长。 */
+  sweepSticky() {
+    const now = this.now()
+    for (const [key, bound] of this.sticky) {
+      if (bound.expiresAtMs <= now) this.sticky.delete(key)
+    }
+  }
+}