dsh-account-pool 0.1.0

package/lib/upstream.js

@@ -0,0 +1,610 @@
+/**
+ * WorkBuddy 上游客户端。
+ *
+ * 职责：
+ *   - 把 DSH 发来的 OpenAI 请求改写成上游认的形态（强制流式、developer→system、tool_choice 压平）
+ *   - 带上 CLI 形态请求头，转发到 copilot.tencent.com / www.workbuddy.ai
+ *   - 拉模型目录，解析出上下文、输出上限、积分倍率、多模态、推理档位
+ *   - 把上游失败分类，供选号器决定「换号重试」还是「直接报错」
+ *
+ * 上游全部怪癖都集中在这一层，其他模块不需要知道。
+ */
+
+import { chatBaseOf, originOf } from './accounts.js'
+import { CLIENT_UA, DESKTOP_UA, IDE_UA, commonHeaders as baseHeaders } from './headers.js'
+
+/** 单次 JSON 请求超时。 */
+const JSON_TIMEOUT_MS = 30_000
+
+/** 错误响应体截断长度，避免把上游 HTML 整页塞进日志。 */
+const ERROR_BODY_LIMIT = 4096
+
+/** 国内版模型目录路径（国际版走别的路径，见下）。 */
+const MODELS_PATH = '/v2/enterprises/personal/models'
+
+/** 国际版模型目录路径：配置服务按客户端通道返回不同清单。 */
+const GLOBAL_CONFIG_PATH = '/v3/config'
+
+// ---------------------------------------------------------------------------
+// 失败分类
+// ---------------------------------------------------------------------------
+
+/** 积分/额度不足的文案标记（中英双语，上游两种都可能出现）。 */
+const HARD_CREDIT_MARKERS = [
+  'insufficient credit', 'no credit', 'credit exhausted', 'out of credit',
+  'quota exceeded', 'quota exhaust', 'payment required', 'credit not enough',
+  'not enough credit',
+  '积分不足', '额度不足', '余额不足', '积分用完', '额度用尽', '没有积分',
+]
+
+/** 会话失效标记：需要重新登录，换号也没用（但换号可以让别的账号顶上）。 */
+const SESSION_DEAD_MARKERS = ['Offline user session not found', '12153']
+
+/**
+ * 分类上游失败。顺序很重要：先看额度，再看会话，最后按状态码兜底。
+ * 分类结果直接决定选号器怎么处置这个账号。
+ *
+ * @returns {'hard_credit'|'soft_rate'|'session_dead'|'not_found'|'server'|'client'}
+ */
+export function classifyUpstreamError(status, body) {
+  if (status === 402) return 'hard_credit'
+  const lower = String(body ?? '').toLowerCase()
+  for (const marker of HARD_CREDIT_MARKERS) {
+    if (lower.includes(marker.toLowerCase()) || String(body ?? '').includes(marker)) return 'hard_credit'
+  }
+  for (const marker of SESSION_DEAD_MARKERS) {
+    if (String(body ?? '').includes(marker)) return 'session_dead'
+  }
+  if (status === 429) return 'soft_rate'
+  if (status === 404) return 'not_found'
+  if (status >= 500) return 'server'
+  return 'client'
+}
+
+/**
+ * 哪些失败值得换个账号重试。
+ *   - hard_credit  该号没钱了 → 换号
+ *   - soft_rate    该号被限流 → 换号
+ *   - session_dead 该号掉线 → 换号
+ *   - server/not_found  上游抖动 → 换号（别的号可能正常）
+ *   - client       请求本身有问题 → 换号也没用，不重试（否则白白又消耗一次）
+ */
+export function isRetryableWithAnotherAccount(kind) {
+  return kind === 'hard_credit' || kind === 'soft_rate' || kind === 'session_dead'
+    || kind === 'server' || kind === 'not_found'
+}
+
+// ---------------------------------------------------------------------------
+// 请求体改写
+// ---------------------------------------------------------------------------
+
+/**
+ * tool_choice 归一化：上游该字段只认字符串，对象形式会 400。
+ * DSH 可能发 {"type":"auto"} 这种，需要压平。
+ */
+function normalizeToolChoice(obj) {
+  const choice = obj.tool_choice
+  if (choice === undefined || choice === null) return
+  if (typeof choice === 'string') return
+  if (typeof choice === 'object') {
+    const type = choice.type
+    if (typeof type === 'string') {
+      obj.tool_choice = type
+      return
+    }
+  }
+  // 认不出来的形态直接删，总比让上游 400 好。
+  delete obj.tool_choice
+}
+
+/**
+ * 把 DSH 的请求体改写成上游能接受的形态：
+ *   1. 强制 stream:true——上游拒绝非流式
+ *   2. developer 角色改 system——上游不认 developer，会报「unapproved channel」
+ *   3. tool_choice 压平为字符串
+ *
+ * 解析失败时原样返回，让上游自己去报错，不在本地吞掉。
+ */
+export function prepareChatBody(source) {
+  let body
+  try {
+    body = JSON.parse(source)
+  } catch {
+    return source
+  }
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) return source
+
+  body.stream = true
+
+  if (Array.isArray(body.messages)) {
+    for (const message of body.messages) {
+      if (typeof message !== 'object' || message === null || Array.isArray(message)) continue
+      if (message.role === 'developer') message.role = 'system'
+    }
+  }
+
+  normalizeToolChoice(body)
+  return JSON.stringify(body)
+}
+
+// ---------------------------------------------------------------------------
+// 请求头
+// ---------------------------------------------------------------------------
+
+/** 所有上游请求共用的头。 */
+function commonHeaders(credential, overrides = {}) {
+  return baseHeaders({
+    origin: originOf(credential.domain),
+    // 区域直接取凭据字段（导入/登录时已判定），比按域名后缀猜更准。
+    region: credential.region === 'global' ? 'global' : 'cn',
+    uid: credential.uid,
+    ...overrides,
+  })
+}
+
+/**
+ * chat 请求头。
+ * 安全红线：绝不放 refresh token——它只在刷新端点出现。
+ */
+function chatHeaders(credential) {
+  const headers = {
+    ...commonHeaders(credential),
+    authorization: `Bearer ${credential.accessToken}`,
+    'x-product': 'SaaS',
+  }
+  // 上游用 X-No-* 表示「本字段确实为空」，而不是省略字段。
+  if (credential.uid) headers['x-user-id'] = credential.uid
+  else headers['x-no-user-id'] = '1'
+  if (credential.enterpriseId) headers['x-enterprise-id'] = credential.enterpriseId
+  else headers['x-no-enterprise-id'] = '1'
+  if (credential.domain) headers['x-domain'] = credential.domain
+  else headers['x-no-department-info'] = '1'
+  return headers
+}
+
+// ---------------------------------------------------------------------------
+// 模型目录
+// ---------------------------------------------------------------------------
+
+/** 从上游 `credits` 字符串（形如 "x0.71"）解析出数字倍率；解析不出返回 undefined。 */
+export function parseCreditMultiplier(raw) {
+  if (typeof raw !== 'string') return undefined
+  const match = /([0-9]*\.?[0-9]+)/.exec(raw)
+  if (match === null) return undefined
+  const value = Number(match[1])
+  return Number.isFinite(value) ? value : undefined
+}
+
+/**
+ * 单数 effort 形态（只有 `effort`，没有 supportedEfforts/defaultEffort/
+ * canDisableThinking）在实测中表示「不发 reasoning_effort 就完全不思考」，
+ * 也就是说这些模型其实接受整条档位阶梯。所以折成完整阶梯，并把声明的值
+ * 当作默认档——这个结论来自参照项目在真机上的探测，不是推测。
+ */
+const SINGULAR_EFFORT_LADDER = ['low', 'medium', 'high', 'xhigh', 'max']
+
+/** 是否是单数 effort 形态：只声明 effort，其余字段一个都没有。 */
+function isSingularEffortForm(raw) {
+  return typeof raw.effort === 'string'
+    && !Array.isArray(raw.supportedEfforts)
+    && typeof raw.defaultEffort !== 'string'
+    && typeof raw.canDisableThinking !== 'boolean'
+}
+
+/** 单数形态展开为阶梯；认不出的值就只留它自己。 */
+function singularEffortLadder(raw) {
+  const effort = typeof raw.effort === 'string' ? raw.effort : undefined
+  if (effort === undefined) return undefined
+  return SINGULAR_EFFORT_LADDER.includes(effort) ? [...SINGULAR_EFFORT_LADDER] : [effort]
+}
+
+/**
+ * 解析推理档位声明。上游有两种拼写：
+ *   - 复数形式 reasoning.supportedEfforts（完整清单）
+ *   - 单数形式 reasoning.effort（只声明默认档，实为完整阶梯）
+ *
+ * canDisableThinking 只在字段显式为布尔时采纳；单数形态下推定为可关闭。
+ * 绝不自己编造「可以关思考」——那会让 DSH 展示一个上游不支持的档位。
+ */
+function parseReasoning(raw) {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined
+  const effort = typeof raw.effort === 'string' ? raw.effort : undefined
+  const supported = Array.isArray(raw.supportedEfforts)
+    ? raw.supportedEfforts.filter(e => typeof e === 'string')
+    : singularEffortLadder(raw)
+  const defaultEffort = typeof raw.defaultEffort === 'string' ? raw.defaultEffort : effort
+  const canDisableThinking = typeof raw.canDisableThinking === 'boolean'
+    ? raw.canDisableThinking
+    : isSingularEffortForm(raw) ? true : undefined
+
+  if (supported === undefined && defaultEffort === undefined && canDisableThinking === undefined) {
+    return undefined
+  }
+  return {
+    supportedEfforts: supported === undefined || supported.length === 0 ? undefined : supported,
+    defaultEffort,
+    canDisableThinking,
+  }
+}
+
+/**
+ * 上游模型条目 → 内部模型描述。
+ *
+ * 字段缺失就留空，绝不编造——尤其：
+ *   - 上游标了 disabled 的模型直接丢弃
+ *   - 上下文/输出上限缺失导致无法定预算的模型也丢弃
+ *   - supportsToolCall 只在显式为布尔时才采纳（undefined 表示上游没说，
+ *     此时交给 pi-ai 的默认行为，不要替它下结论）
+ */
+export function parseUpstreamModel(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const id = String(raw.id ?? raw.model ?? '')
+  if (id === '' || raw.disabled === true) return undefined
+
+  const contextWindow = Number(raw.maxInputTokens ?? raw.contextLength ?? 0)
+  const maxTokens = Number(raw.maxOutputTokens ?? raw.max_output_tokens ?? 0)
+  // 两个上限都拿不到就没法定预算，这种条目宁可不要。
+  if (contextWindow <= 0 || maxTokens <= 0) return undefined
+
+  const name = typeof raw.name === 'string' && raw.name !== ''
+    ? raw.name
+    : id.replace(/^[a-z]+:/, '')
+
+  const supportsToolCall = typeof raw.supportsToolCall === 'boolean'
+    ? raw.supportsToolCall
+    : typeof raw.supports_tool_call === 'boolean' ? raw.supports_tool_call : undefined
+
+  return {
+    id,
+    name,
+    contextWindow,
+    maxTokens,
+    creditMultiplier: parseCreditMultiplier(raw.credits),
+    multimodal: raw.supportsImages === true || raw.supports_images === true,
+    reasoning: parseReasoning(raw.reasoning),
+    supportsToolCall,
+    descriptionZh: raw.descriptionZh ?? raw.description,
+  }
+}
+
+/** 在任意嵌套结构里找模型数组——两个区域的文档外层形状不同，内层条目一致。 */
+function isNonChatModel(id, maxOutputTokens, tags) {
+  const lowered = String(id ?? '').trim().toLowerCase()
+  for (const prefix of ['nes-', 'completion-', 'codewise-']) {
+    if (lowered.startsWith(prefix)) return true
+  }
+  if (typeof maxOutputTokens === 'number' && maxOutputTokens > 0 && maxOutputTokens <= 256) {
+    return true
+  }
+  if (Array.isArray(tags) && tags.includes('text-to-image')) return true
+  return false
+}
+
+/**
+ * 从文档里取出「CLI 通道认可的模型 id 清单」。
+ *
+ * 为什么不直接用 data.models 全量：同一个端点返回 30 个模型，但
+ * agents[cli].models 只列了 16 个。CLI 通道（我们扮演的就是 CLI）只认这 16 个，
+ * 其余属于 IDE 或其它 agent。混进来会出现「选了就报错」的条目——
+ * 实测 glm-4.6 返回 HTTP 400 code=11102「model service info not found」。
+ *
+ * roster 缺失或为空时返回 undefined，调用方据此回落到全量列表：
+ * roster 是上游实现细节，把它当硬性前提会让插件在目录变化时直接失效。
+ */
+function cliRosterOf(data) {
+  const agents = data?.agents
+  if (!Array.isArray(agents)) return undefined
+  for (const agent of agents) {
+    if (agent !== null && typeof agent === 'object' && agent.name === 'cli') {
+      const models = agent.models
+      if (Array.isArray(models) && models.length > 0) {
+        return models.filter(id => typeof id === 'string' && id !== '')
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * 第二路探测：/v3/config（IDE 通道）。
+ *
+ * 为什么需要第二路：企业端点的 cli roster 只有 16 个模型，而 IDE 通道还
+ * 额外提供 deepseek-v4-flash、hy4-preview-f 等。网关正是把两路取并集
+ * （v3 优先，企业端点补缺），才得到完整的 18 个。
+ *
+ * 失败时返回空数组而不抛错——第二路是增强，不该拖垮主路。
+ */
+async function fetchV3ConfigModels(credential) {
+  const headers = {
+    accept: 'application/json, text/plain, */*',
+    'x-requested-with': 'XMLHttpRequest',
+    authorization: `Bearer ${credential.accessToken}`,
+    'x-product': 'SaaS',
+    'user-agent': IDE_UA,
+  }
+  if (credential.uid) headers['x-user-id'] = credential.uid
+  if (credential.domain) headers['x-domain'] = credential.domain
+
+  try {
+    const response = await fetch(`${chatBaseOf(credential.domain)}/v3/config`, {
+      headers,
+      signal: AbortSignal.timeout(JSON_TIMEOUT_MS),
+    })
+    if (!response.ok) return []
+    const envelope = await response.json()
+    if (typeof envelope.code === 'number' && envelope.code !== 0) return []
+    const models = envelope.data?.models
+    if (!Array.isArray(models)) return []
+    // v3 面取全量（不按 cli roster 过滤），但仍剔除非对话模型。
+    return models
+      .filter(m => m !== null && typeof m === 'object')
+      .filter(m => {
+        const id = String(m.id ?? '')
+        return id !== '' && !isNonChatModel(id, m.maxOutputTokens, m.tags) && m.disabled !== true
+      })
+      .map(parseUpstreamModel)
+      .filter(m => m !== undefined)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 拉取某账号可见的模型目录。
+ * 国内版走 /v2/enterprises/personal/models；
+ * 国际版走 /v3/config 并伪装成桌面端通道（CLI 通道会漏掉部分模型）。
+ */
+export async function fetchModels(credential) {
+  const base = chatBaseOf(credential.domain)
+  const isGlobal = credential.region === 'global'
+  const path = isGlobal ? GLOBAL_CONFIG_PATH : MODELS_PATH
+
+  const headers = {
+    ...commonHeaders(credential, isGlobal ? { userAgent: DESKTOP_UA } : {}),
+    authorization: `Bearer ${credential.accessToken}`,
+  }
+  if (credential.uid) headers['x-user-id'] = credential.uid
+
+  const response = await fetch(`${base}${path}`, {
+    headers,
+    signal: AbortSignal.timeout(JSON_TIMEOUT_MS),
+  })
+  if (!response.ok) {
+    throw new Error(`拉取模型目录失败：HTTP ${response.status}`)
+  }
+  const envelope = await response.json()
+  if (typeof envelope.code === 'number' && envelope.code !== 0) {
+    throw new Error(`拉取模型目录失败：code=${envelope.code} ${envelope.msg ?? ''}`)
+  }
+
+  const data = envelope.data ?? envelope
+  const allModels = Array.isArray(data?.models) ? data.models : []
+  if (allModels.length === 0) throw new Error('模型目录里没有 models 数组')
+
+  // 先按 id 建表，便于按 roster 取回顺序与完整字段。
+  const byId = new Map()
+  for (const raw of allModels) {
+    if (raw === null || typeof raw !== 'object') continue
+    const id = String(raw.id ?? raw.model ?? '')
+    if (id === '') continue
+    // 非对话模型（嵌入/补全/文生图/超小输出）直接剔除，
+    // 它们不是给对话用的，选到只会报错。
+    if (isNonChatModel(id, raw.maxOutputTokens, raw.tags)) continue
+    // 明确标记 disabled 的也剔除。
+    if (raw.disabled === true) continue
+    byId.set(id, raw)
+  }
+
+  // 主路结果：有 cli roster 就按它筛（CLI 通道只认这些）；
+  // 没有就回落到全量，避免上游改结构后插件直接失效。
+  const roster = cliRosterOf(data)
+  const primaryRaw = roster === undefined
+    ? [...byId.values()]
+    : roster.map(id => byId.get(id)).filter(raw => raw !== undefined)
+  if (primaryRaw.length === 0) throw new Error('cli roster 与模型表没有交集')
+
+  const primary = primaryRaw.map(parseUpstreamModel).filter(m => m !== undefined)
+
+  // 国际版没有第二路（它走 /v3/config 本身就是完整目录）。
+  if (isGlobal) return primary
+
+  // 第二路：/v3/config（IDE 通道）补缺。企业端点的 cli roster 只有 16 个，
+  // IDE 通道还额外提供 deepseek-v4-flash、hy4-preview-f 等——网关正是靠
+  // 两路取并集才凑齐 18 个。合并规则：主路优先，第二路只补主路没有的 id。
+  const secondary = await fetchV3ConfigModels(credential)
+  if (secondary.length === 0) return primary
+
+  const seen = new Set(primary.map(m => m.id))
+  const merged = [...primary]
+  for (const model of secondary) {
+    if (seen.has(model.id)) continue
+    seen.add(model.id)
+    merged.push(model)
+  }
+  return merged
+}
+
+// ---------------------------------------------------------------------------
+// 对话流式转发
+// ---------------------------------------------------------------------------
+
+/**
+ * 发一次 chat 请求，返回上游原始 Response（SSE 流）。
+ *
+ * 不做账号选择——由调用方（shim）决定用哪个凭证，这样选号与传输职责分离。
+ *
+ * @returns {Promise<{ok:true,response:Response}|{ok:false,status:number,kind:string,message:string}>}
+ */
+export async function chatStream(credential, bodyJson, signal) {
+  let response
+  try {
+    response = await fetch(`${chatBaseOf(credential.domain)}/v2/chat/completions`, {
+      method: 'POST',
+      headers: chatHeaders(credential),
+      body: bodyJson,
+      signal,
+    })
+  } catch (error) {
+    // 网络层失败归为 server：值得换个账号再试。
+    return { ok: false, status: 0, kind: 'server', message: `网络错误：${error?.message ?? error}` }
+  }
+
+  if (response.ok) return { ok: true, response }
+
+  const text = (await response.text()).slice(0, ERROR_BODY_LIMIT)
+  return {
+    ok: false,
+    status: response.status,
+    kind: classifyUpstreamError(response.status, text),
+    message: text,
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// 积分查询
+// ---------------------------------------------------------------------------
+
+/** 国内版计费域。 */
+const CN_BILLING_BASE = 'https://www.codebuddy.cn'
+
+/** 计费接口的产品码（CodeBuddy）。 */
+const BILLING_PRODUCT_CODE = 'p_tcaca'
+
+/** 「即将到期」的判定窗口：3 天。 */
+const EXPIRING_SOON_MS = 3 * 24 * 3600 * 1000
+
+/** 计费域：国内版固定 codebuddy.cn；国际版跟随凭据自己的域。 */
+function billingBaseOf(credential) {
+  return credential.region === 'global' ? chatBaseOf(credential.domain) : CN_BILLING_BASE
+}
+
+/** 计费接口要的时间格式：YYYY-MM-DD HH:mm:ss（本地时区，无时区后缀）。 */
+function formatBillingTime(date) {
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+    + ` ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+}
+
+/** 日期字段可能是毫秒数或字符串，统一转成毫秒；认不出返回 undefined。 */
+function parseDateMs(raw) {
+  if (typeof raw === 'number' && raw > 1e12) return raw
+  if (typeof raw === 'string' && raw !== '') {
+    const parsed = Date.parse(raw)
+    if (!Number.isNaN(parsed)) return parsed
+  }
+  return undefined
+}
+
+/**
+ * 解析计费响应的嵌套结构。
+ *
+ * 真实层级是 data.Response.Data.Accounts——不是平铺的，直接取
+ * data.Accounts 会拿到空数组。字段名也要注意：剩余量叫 CapacityRemain，
+ * 而月包（CapacityType 4）要用 CycleCapacityRemain。
+ */
+function parseBillingAccounts(envelope) {
+  const wrapper = envelope?.data
+  if (wrapper === null || typeof wrapper !== 'object') return []
+  const response = wrapper.Response
+  if (response === null || typeof response !== 'object') return []
+  const inner = response.Data
+  if (inner === null || typeof inner !== 'object') return []
+  return Array.isArray(inner.Accounts) ? inner.Accounts : []
+}
+
+/**
+ * 查询一个账号的剩余积分，按套餐聚合。
+ *
+ * 为什么区分月包与一次性礼包：
+ *   CapacityType 4 是月包（每周期刷新、不过期），剩余看 CycleCapacityRemain；
+ *   其余是抵扣式礼包，剩余看 CapacityRemain，并且耗尽/过期的要丢掉，
+ *   否则「最近到期」列表会被一堆没用的零余额条目淹没。
+ *
+ * 注意：该端点必须带 Origin/Referer/User-Agent，否则上游直接 403。
+ */
+export async function fetchCredits(credential) {
+  const now = new Date()
+  const body = {
+    PageNumber: 1,
+    PageSize: 100,
+    ProductCode: BILLING_PRODUCT_CODE,
+    Status: [0, 3],
+    PackageEndTimeRangeBegin: formatBillingTime(now),
+    PackageEndTimeRangeEnd: formatBillingTime(new Date(now.getTime() + 365 * 101 * 24 * 3600 * 1000)),
+  }
+
+  const headers = {
+    ...commonHeaders(credential),
+    authorization: `Bearer ${credential.accessToken}`,
+  }
+  if (credential.uid) headers['x-user-id'] = credential.uid
+  if (credential.enterpriseId) {
+    headers['x-enterprise-id'] = credential.enterpriseId
+    headers['x-tenant-id'] = credential.enterpriseId
+  }
+  if (credential.domain) headers['x-domain'] = credential.domain
+
+  const response = await fetch(`${billingBaseOf(credential)}/v2/billing/meter/get-user-resource`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(JSON_TIMEOUT_MS),
+  })
+  if (!response.ok) throw new Error(`查询积分失败：HTTP ${response.status}`)
+
+  const envelope = await response.json()
+  if (typeof envelope.code === 'number' && envelope.code !== 0) {
+    throw new Error(`查询积分失败：code=${envelope.code} ${envelope.msg ?? ''}`)
+  }
+
+  let total = 0
+  let expiringSoon = 0
+  let nearestExpiryMs
+  const packages = []
+
+  for (const account of parseBillingAccounts(envelope)) {
+    if (account === null || typeof account !== 'object') continue
+    const numberOf = (key) => (typeof account[key] === 'number' ? account[key] : 0)
+
+    // 周期包/一次性包的判定用「数据驱动」的三档判据（对照网关实现的 switch），
+    // 不依赖 CapacityType 枚举值——上游对枚举的赋值不受我们控制。
+    // 第二档覆盖「周期刚好用完」的包：Size 归 0 但 Remain/Used 还有痕迹，
+    // 这时读 Capacity 字段会算出 0，漏算余额。
+    const cycleSize = numberOf('CycleCapacitySize')
+    const cycleRemain = numberOf('CycleCapacityRemain')
+    const cycleUsed = numberOf('CycleCapacityUsed')
+    const monthly = cycleSize > 0 || cycleRemain > 0 || cycleUsed > 0
+    const size = monthly ? cycleSize : numberOf('CapacitySize')
+    const rawRemain = monthly ? cycleRemain : numberOf('CapacityRemain')
+    const remain = rawRemain < 0 ? 0 : rawRemain
+
+    const cycleEndMs = parseDateMs(account.CycleEndTime)
+    const expiresAtMs = monthly ? undefined : (parseDateMs(account.ExpiredTime) ?? cycleEndMs)
+    const refreshAtMs = monthly && cycleEndMs !== undefined ? cycleEndMs + 1000 : undefined
+
+    // 一次性礼包：空的或已过期的丢掉，它们不贡献可用额度。
+    if (!monthly && (remain <= 0 || (expiresAtMs !== undefined && expiresAtMs <= Date.now()))) {
+      continue
+    }
+
+    total += remain
+    if (expiresAtMs !== undefined) {
+      if (nearestExpiryMs === undefined || expiresAtMs < nearestExpiryMs) nearestExpiryMs = expiresAtMs
+      if (expiresAtMs - Date.now() <= EXPIRING_SOON_MS) expiringSoon += remain
+    }
+    packages.push({
+      packageName: typeof account.PackageName === 'string' ? account.PackageName : '(未命名)',
+      remain,
+      size,
+      monthly,
+      refreshAtMs,
+      expiresAtMs,
+    })
+  }
+
+  // 总量与已用一起给出：界面的悬停提示要展示「总量 / 已用 / 剩余」构成。
+  // size 求和与 remain 同源（同一批包），已用 = 总量 − 剩余。
+  const totalSize = packages.reduce((sum, pkg) => sum + (pkg.size || 0), 0)
+  return { total, size: totalSize, packages, expiringSoon, nearestExpiryMs }
+}