Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

18.0 KB
Raw Blame
/**
 * claudeSubscriptionUsage — Claude 订阅(Anthropic OAuth)账号余量的共享类型与纯函数。
 *
 * 数据有两个来源,口径不同,统一归一化成 `ClaudeSubscriptionUsageSnapshot`(utilization
 * 一律 0-100 已用百分比):
 *   1. `oauth-endpoint` — GET api.anthropic.com/api/oauth/usage(未文档化端点,Claude Code
 *      自己的 /usage 命令同源)。utilization 为 0-100;新 schema 以 `limits[]` 数组为准
 *      (kind: session / weekly_all / weekly_scoped,scoped 带 scope.model),旧 schema 的
 *      `five_hour` / `seven_day` / `seven_day_opus` / `seven_day_sonnet` /
 *      `seven_day_fable` 顶层键做兜底。
 *      仅端点源有分模型周窗口(Fable / Opus / Sonnet 各自独立)与 extra usage。
 *   2. `unified-headers` — 订阅直连响应上的 `anthropic-ratelimit-unified-*` headers
 *      (每次 API call 都带,由本地 proxy 旁路读取)。utilization 为 0.0-1.0 分数,
 *      解析时 ×100;只有 5h / 7d 总窗口,没有 scoped。
 *
 * 两源合并语义见 mergeClaudeSubscriptionUsageSnapshot:endpoint 全量替换,headers 只
 * 增量刷新 5h / 7d 与整体状态,保留 endpoint 独有的 scoped / extraUsage / 套餐信息。
 *
 * ⚠️ 这两个数据源都未文档化,解析必须 fail-safe:任何字段缺失 / 形状不符都跳过该字段
 * 而不是抛错;完全解析不出内容时返回 null,调用方按"无数据"处理(绝不从 token 用量反推)。
 */

import {
  matchScopedWindowForModel,
  scopedWindowBelongsToFamily,
  type ClaudeExtraUsageSnapshot,
  type ClaudeScopedUsageWindow,
  type ClaudeSubscriptionUsageSnapshot,
  type ClaudeUsageWindow,
} from '@cindy/maker-shared/subscription-usage';

// 快照契约与模型窗口匹配在 maker-shared,mobile 任务菜单复用同一份口径。
export type {
  ClaudeExtraUsageSnapshot,
  ClaudeScopedUsageWindow,
  ClaudeSubscriptionUsageSnapshot,
  ClaudeUsageWindow,
} from '@cindy/maker-shared/subscription-usage';
export { claudeModelFamily, matchScopedWindowForModel } from '@cindy/maker-shared/subscription-usage';

function isPlainObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

function toFiniteNumber(v: unknown): number | null {
  // Number(null) / Number('') 都是 0 —— 显式排除, null 语义必须保留为"无数据"。
  if (v === null || v === undefined || v === '') return null;
  const n = typeof v === 'number' ? v : Number(v);
  return Number.isFinite(n) ? n : null;
}

function clampPercent(v: number): number {
  return Math.min(100, Math.max(0, v));
}

/** ISO8601 字符串 / epoch 秒 → epoch 秒;解析不了 → null。 */
function toEpochSeconds(v: unknown): number | null {
  if (typeof v === 'number' && Number.isFinite(v) && v > 0) return Math.floor(v);
  if (typeof v === 'string' && v.length > 0) {
    const ms = Date.parse(v);
    if (Number.isFinite(ms) && ms > 0) return Math.floor(ms / 1000);
  }
  return null;
}

function toOptionalString(v: unknown): string | null {
  return typeof v === 'string' && v.trim().length > 0 ? v.trim() : null;
}

// ── oauth-endpoint 解析 ──────────────────────────────────────────────────────

/** limits[] 单条 → 窗口(utilization 取 percent 字段,0-100)。 */
function parseLimitEntryWindow(entry: Record<string, unknown>): ClaudeUsageWindow | null {
  const percent = toFiniteNumber(entry.percent);
  if (percent === null) return null;
  return {
    utilization: clampPercent(percent),
    resetsAt: toEpochSeconds(entry.resets_at),
    severity: toOptionalString(entry.severity),
  };
}

/** 旧 schema 顶层键(five_hour 等)→ 窗口(utilization 字段,0-100)。 */
function parseLegacyWindow(v: unknown): ClaudeUsageWindow | null {
  if (!isPlainObject(v)) return null;
  const utilization = toFiniteNumber(v.utilization);
  if (utilization === null) return null;
  return {
    utilization: clampPercent(utilization),
    resetsAt: toEpochSeconds(v.resets_at),
  };
}

function parseExtraUsage(v: unknown): ClaudeExtraUsageSnapshot | null {
  if (!isPlainObject(v)) return null;
  const isEnabled = v.is_enabled === true;
  const utilization = toFiniteNumber(v.utilization);
  const usedCredits = toFiniteNumber(v.used_credits);
  const monthlyLimit = toFiniteNumber(v.monthly_limit);
  if (!isEnabled && utilization === null && usedCredits === null) return null;
  return {
    isEnabled,
    utilization: utilization === null ? null : clampPercent(utilization),
    usedCredits,
    monthlyLimit,
  };
}

/**
 * 解析 GET /api/oauth/usage 的响应 JSON。
 *
 * 优先走新 schema 的 `limits[]`(带 severity / scoped 模型信息);旧 schema 顶层键兜底。
 * 未知字段(实验性混淆键等)一律忽略。解析不出任何窗口时返回 null。
 */
export function parseClaudeOAuthUsageResponse(
  data: unknown,
  now: number,
): ClaudeSubscriptionUsageSnapshot | null {
  if (!isPlainObject(data)) return null;

  let fiveHour: ClaudeUsageWindow | null = null;
  let sevenDay: ClaudeUsageWindow | null = null;
  const scoped: ClaudeScopedUsageWindow[] = [];

  const limits = Array.isArray(data.limits) ? data.limits : [];
  for (const raw of limits) {
    if (!isPlainObject(raw)) continue;
    const window = parseLimitEntryWindow(raw);
    if (!window) continue;
    const kind = toOptionalString(raw.kind);
    if (kind === 'session') {
      fiveHour = window;
    } else if (kind === 'weekly_all') {
      sevenDay = window;
    } else if (kind === 'weekly_scoped') {
      const scope = isPlainObject(raw.scope) ? raw.scope : null;
      const model = scope && isPlainObject(scope.model) ? scope.model : null;
      const displayName = model ? toOptionalString(model.display_name) : null;
      if (displayName) {
        scoped.push({
          ...window,
          modelDisplayName: displayName,
          modelId: model ? toOptionalString(model.id) : null,
        });
      }
    }
    // 未知 kind(未来新窗口类型)静默跳过 —— fail-safe。
  }

  // 旧 schema 兜底:limits[] 没给的窗口再看顶层键。
  if (!fiveHour) fiveHour = parseLegacyWindow(data.five_hour);
  if (!sevenDay) sevenDay = parseLegacyWindow(data.seven_day);
  // 旧 schema 分模型周窗口兜底:按家族补 limits[] 没给 weekly_scoped 的家族,从顶层
  // seven_day_<model> 键取。不能用 `scoped.length === 0` 整体门控——混合/降级响应里
  // limits[] 可能只给了部分家族(如只有 Opus),其余家族(Fable)只通过顶层键下发;某家族
  // 的 weekly_scoped 畸形被跳过时同理。已由 limits[] 给出的家族以 limits[] 为准,不被
  // legacy 覆盖。家族归属统一走 scopedWindowBelongsToFamily,与 matchScopedWindowForModel
  // 同一份口径,避免两份 includes 规则漂移。Fable 是较新加的家族,旧兜底原先只列
  // Opus/Sonnet,走旧端点或降级快照时 Fable 周限丢失(issue #3244);Mythos/Haiku 端点
  // 目前不下发分模型周窗口,如未来新增在此追加。
  const legacyScoped: Array<[unknown, string]> = [
    [data.seven_day_opus, 'Opus'],
    [data.seven_day_sonnet, 'Sonnet'],
    [(data as { seven_day_fable?: unknown }).seven_day_fable, 'Fable'],
  ];
  for (const [raw, displayName] of legacyScoped) {
    const family = displayName.toLowerCase();
    if (scoped.some((w) => scopedWindowBelongsToFamily(w, family))) continue;
    const window = parseLegacyWindow(raw);
    if (window) scoped.push({ ...window, modelDisplayName: displayName });
  }

  if (!fiveHour && !sevenDay && scoped.length === 0) return null;

  return {
    fiveHour,
    sevenDay,
    scoped,
    extraUsage: parseExtraUsage(data.extra_usage),
    source: 'oauth-endpoint',
    updatedAt: now,
  };
}

// ── unified-headers 解析 ─────────────────────────────────────────────────────

const UNIFIED_HEADER_PREFIX = 'anthropic-ratelimit-unified-';

/** headers 的 utilization 是 0.0-1.0 分数(与端点的 0-100 不同),×100 归一化。 */
function parseHeaderUtilization(v: string | undefined): number | null {
  if (v === undefined) return null;
  const n = Number(v);
  if (!Number.isFinite(n)) return null;
  return clampPercent(n * 100);
}

function parseHeaderEpochSeconds(v: string | undefined): number | null {
  if (v === undefined) return null;
  const n = Number(v);
  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
}

/**
 * 解析 `anthropic-ratelimit-unified-*` 响应 headers(key 需已小写化)。
 *
 * 只认 5h / 7d 两个总窗口 + 整体 status / representative-claim;没有任何 unified
 * header 时返回 null(非订阅直连响应,如网关路由,天然没有这些头)。
 */
export function parseClaudeUnifiedRateLimitHeaders(
  headers: Readonly<Record<string, string>>,
  now: number,
): ClaudeSubscriptionUsageSnapshot | null {
  const fiveHourUtil = parseHeaderUtilization(headers[`${UNIFIED_HEADER_PREFIX}5h-utilization`]);
  const sevenDayUtil = parseHeaderUtilization(headers[`${UNIFIED_HEADER_PREFIX}7d-utilization`]);
  const status = toOptionalString(headers[`${UNIFIED_HEADER_PREFIX}status`]);
  const representativeClaim = toOptionalString(
    headers[`${UNIFIED_HEADER_PREFIX}representative-claim`],
  );

  if (fiveHourUtil === null && sevenDayUtil === null && !status) return null;

  return {
    fiveHour: fiveHourUtil === null
      ? null
      : {
        utilization: fiveHourUtil,
        resetsAt: parseHeaderEpochSeconds(headers[`${UNIFIED_HEADER_PREFIX}5h-reset`]),
      },
    sevenDay: sevenDayUtil === null
      ? null
      : {
        utilization: sevenDayUtil,
        resetsAt: parseHeaderEpochSeconds(headers[`${UNIFIED_HEADER_PREFIX}7d-reset`]),
      },
    rateLimitStatus: status,
    representativeClaim,
    source: 'unified-headers',
    updatedAt: now,
  };
}

/**
 * 解析 Claude Code SDK 的 `rate_limit_event.rate_limit_info`(CLI 从同一组 unified headers
 * 解析出的额度信息;订阅会话由 CLI 直连 Anthropic,host 只能从这里拿到余量)。
 *
 * 每条事件只描述一个窗口(rateLimitType);只认 5h / 7d 总窗口,分模型周窗口与 overage
 * 不在 headers 口径内,跳过。按 headers 源(`unified-headers`)的增量语义合并。
 * utilization 与 headers 同为 0.0-1.0 分数(>1 时按已是百分比处理);resetsAt 为 epoch
 * 秒(误给毫秒时折算)。无可用窗口也无状态时返回 null。
 */
export function parseClaudeSdkRateLimitInfo(
  info: unknown,
  now: number,
): ClaudeSubscriptionUsageSnapshot | null {
  if (!isPlainObject(info)) return null;
  const status = toOptionalString(info.status);
  const rateLimitType = toOptionalString(info.rateLimitType);
  const rawUtilization = toFiniteNumber(info.utilization);
  const utilization = rawUtilization === null
    ? null
    : clampPercent(rawUtilization <= 1 ? rawUtilization * 100 : rawUtilization);
  const rawResetsAt = toFiniteNumber(info.resetsAt);
  const resetsAt = rawResetsAt === null || rawResetsAt <= 0
    ? null
    : Math.floor(rawResetsAt > 1e12 ? rawResetsAt / 1000 : rawResetsAt);
  const window = utilization === null ? null : { utilization, resetsAt };
  const fiveHour = rateLimitType === 'five_hour' ? window : null;
  const sevenDay = rateLimitType === 'seven_day' ? window : null;
  if (!fiveHour && !sevenDay && !status) return null;
  return {
    fiveHour,
    sevenDay,
    rateLimitStatus: status,
    representativeClaim: rateLimitType === 'five_hour' || rateLimitType === 'seven_day' ? rateLimitType : null,
    source: 'unified-headers',
    updatedAt: now,
  };
}

// ── 双源合并 ─────────────────────────────────────────────────────────────────

/**
 * 双源合并:
 *   - incoming 为 headers 源 → 以 prev 为底做增量:只覆盖 headers 有的 5h / 7d 窗口与
 *     整体状态,保留 endpoint 独有的 scoped / extraUsage / subscriptionType / severity
 *     不被清掉(headers 没有这些维度,不代表它们消失了)。
 *   - incoming 为 endpoint 源 → 全量替换(endpoint 是权威全集),仅 subscriptionType /
 *     headers 独有的 rateLimitStatus 在 incoming 缺失时沿用 prev。
 */
export function mergeClaudeSubscriptionUsageSnapshot(
  prev: ClaudeSubscriptionUsageSnapshot | null,
  incoming: ClaudeSubscriptionUsageSnapshot,
): ClaudeSubscriptionUsageSnapshot {
  if (!prev) return incoming;

  // 归属指纹冲突(同机换号): prev 属于另一个 Claude 账号, 任何字段都不得沿用 ——
  // 否则 headers 增量会把上一个账号的 scoped / subscriptionType / extraUsage 串给
  // 新账号(owner 维度是 App 用户, 换 Claude 号时不变, prev 不会被 owner 逻辑清除)。
  // incoming 直接作为新账号的起点。
  if (
    prev.accountFingerprint
    && incoming.accountFingerprint
    && prev.accountFingerprint !== incoming.accountFingerprint
  ) {
    return incoming;
  }

  if (incoming.source === 'unified-headers') {
    return {
      ...prev,
      fiveHour: incoming.fiveHour ?? prev.fiveHour,
      sevenDay: incoming.sevenDay ?? prev.sevenDay,
      rateLimitStatus: incoming.rateLimitStatus ?? prev.rateLimitStatus,
      representativeClaim: incoming.representativeClaim ?? prev.representativeClaim,
      updatedAt: incoming.updatedAt ?? prev.updatedAt,
      accountFingerprint: incoming.accountFingerprint ?? prev.accountFingerprint,
      // 展示来源标为最近一次更新者;scoped / extraUsage 仍是 endpoint 的旧值。
      source: 'unified-headers',
    };
  }

  // endpoint 全量替换: headers-only 的 rateLimitStatus / representativeClaim 是
  // 瞬时信号, **不**沿用 —— 限额重置后若长期没有新直连响应(如 app 重启后仅端点
  // 轮询), 陈旧的 rejected / allowed_warning 会与端点刚带回的最新窗口数据矛盾,
  // chip 永久挂警示色。真实限流时下一次直连响应的 headers 会立即重新带回 status;
  // 端点源自身的窗口 severity 也表达告警。subscriptionType / accountFingerprint
  // 是稳定事实(凭证派生), 保留兜底。
  return {
    ...incoming,
    subscriptionType: incoming.subscriptionType ?? prev.subscriptionType,
    accountFingerprint: incoming.accountFingerprint ?? prev.accountFingerprint,
  };
}

// ── 告警判定(chip 变红的口径;tooltip 另有 status 分流,见 TodaySpendChip) ───

/**
 * 窗口进入告警的剩余水位:剩余 ≤10%(已用 ≥90%)。
 *
 * 兜的是 unified-headers 源没有 per-window `severity` 这个事实 —— 该源只给 utilization,
 * 光靠「打满」判定会让 chip 一直到 99.95% 才变红。用固定水位而不是 headers 的整体
 * `allowed_warning`:水位对着 chip 上正在显示的那个数字,「剩余 8%」是红的能自证;
 * 整体 status 综合了 chip 上没有的窗口,红了无从解释(见 isClaudeSubscriptionAlerting)。
 */
const WINDOW_ALERT_UTILIZATION_PERCENT = 90;

/**
 * 单个窗口告警:剩余水位见底,或服务端 severity 明确非 normal。
 *
 * utilization 走 Number.isFinite 而不只是 typeof —— 与本文件其它调用点同口径。解析层
 * (toFiniteNumber / parseHeaderUtilization)本就只放行有限数, 但持久化快照是 JSON.parse
 * 后直接断言成 snapshot 的(见 usageBroadcaster hydration), 不重新校验字段; 万一有脏值
 * 滑进来, +Infinity 会被 clampPercent 夹成 100 并误判成额度耗尽而染红。
 */
export function isClaudeUsageWindowAlerting(
  window: ClaudeUsageWindow | null | undefined,
): boolean {
  if (!window) return false;
  if (
    typeof window.utilization === 'number'
    && Number.isFinite(window.utilization)
    && clampPercent(window.utilization) >= WINDOW_ALERT_UTILIZATION_PERCENT
  ) {
    return true;
  }
  const severity = window.severity?.trim().toLowerCase();
  return Boolean(severity && severity !== 'normal');
}

/**
 * 影响当前会话的窗口是否告警:只看 5h / 总周限 / **当前模型**的 scoped 周限 ——
 * 其它模型的 scoped 窗口打满不限流当前会话(跑 Opus 时 Fable 周限见底与本会话无关),
 * 只在 tooltip 的全量窗口列表里可见,不参与判定。
 */
export function hasAlertingClaudeSessionWindow(
  snapshot: ClaudeSubscriptionUsageSnapshot | null,
  modelId: string | null | undefined,
): boolean {
  if (!snapshot) return false;
  return (
    isClaudeUsageWindowAlerting(snapshot.fiveHour)
    || isClaudeUsageWindowAlerting(snapshot.sevenDay)
    || isClaudeUsageWindowAlerting(matchScopedWindowForModel(snapshot.scoped, modelId))
  );
}

/**
 * chip 警示态(变红):只在当前会话**真的**受限时亮 —— 请求已被拒(headers 整体
 * status = rejected),或影响当前会话的窗口告警(见上)。
 *
 * headers 的 `allowed_warning` **不**单独染红:它是服务端综合全部窗口(含其它模型的
 * 分模型周限)给出的模糊信号,而 chip 只显示 5h + 周限两段 —— 拿 Fable 周限 87% 把跑
 * Opus 的会话染红,用户看到的是「剩余 91% / 56% 却是红的」,颜色与数字自相矛盾且无处
 * 解释(chip 上没有那个窗口)。真限流时 rejected 会立刻到,不需要它兜底;「接近限额」
 * 提示仍留在 tooltip —— 那里紧邻全量窗口列表,有上下文。
 *
 * 也没有走 `representativeClaim`(「只在 claim 指向 chip 上的窗口时才认 allowed_warning」):
 * 2026-07-25 实测快照里 claim=`five_hour`,而当时真正吃紧的是 Fable 周限(87%,
 * severity=warning),5h 只用了 10% —— 这个字段并不指向触发 warning 的窗口,以它为条件
 * 会原样退回误红。headers 源缺 severity 的预警缺口改由 WINDOW_ALERT_UTILIZATION_PERCENT
 * 的剩余水位兜住,判据始终是 chip 上看得见的那个数字。
 */
export function isClaudeSubscriptionAlerting(
  snapshot: ClaudeSubscriptionUsageSnapshot | null,
  modelId: string | null | undefined,
): boolean {
  if (!snapshot) return false;
  if (snapshot.rateLimitStatus?.trim().toLowerCase() === 'rejected') return true;
  return hasAlertingClaudeSessionWindow(snapshot, modelId);
}