dsh-api-dashboard 1.0.0

package/src/index.js

@@ -0,0 +1,1202 @@
+/**
+ * dsh-api-dashboard — server half (v3 完整版).
+ *
+ * 多平台 API 余额/用量看板。内置全部国内外平台预设，支持:
+ *   - 海外官方: DeepSeek / OpenAI / Claude / Gemini / Groq / Mistral / Together / OpenRouter / Ollama
+ *   - 国内平台: 智谱GLM / 通义Qwen / Kimi / 阶跃StepFun / 硅基流动 / 基元律动 / 小米MiMo / 百度千帆 / 阿里百炼 / 腾讯混元
+ *   - 中转站: one-api / new-api 系 quota, 通用 OpenAI 兼容中转站
+ *   - 自定义中转站: 用户填 base_url + api_key, 自动探测余额端点, 能查显示, 查不到标未开放。
+ *
+ * 学习 dsh-balance 架构:
+ *   - 服务端按 refreshIntervalMs 定时拉取各平台余额并缓存 (stale-while-error)。
+ *   - HTTP 路由 /api-dashboard/balances 提供只读缓存给前端。
+ *   - sessionProjections 单元 queryBalanceCost 估算本会话消耗 (按模型单价)。
+ */
+
+import Schema from '@deepseek-ai/schemastery'
+import { z } from 'zod'
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, rmSync, cpSync, statSync, readdirSync, realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join, dirname, basename } from 'node:path'
+
+export const name = 'dsh-api-dashboard'
+
+// ============================================================
+// 自动更新模块 (v0.6.0): GitHub 远端版本检查 + 一键自更新
+// 流程: check(api.github.com 读远端 manifest version)
+//      → install(codeload 下载 → 临时目录解压校验 → 备份 → 原子交换 → 回滚兜底)
+// 仅允许更新为「严格更新」版本, 不接受降级; 不接收任何路径类入参.
+// ============================================================
+const REPO_OWNER = '133563825as-ai'
+const REPO_NAME = 'dsh-api-dashboard'
+const REPO_BRANCH = 'main'
+const MANIFEST_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/contents/package.json?ref=${REPO_BRANCH}`
+const TARBALL_URL = `https://codeload.github.com/${REPO_OWNER}/${REPO_NAME}/tar.gz/refs/heads/${REPO_BRANCH}`
+
+/** 插件运行实体的安装根目录 (src/index.js 上两级; ESM 默认按 realpath 加载) */
+const SELF_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** 读取指定目录中 package.json 的 version, 异常返回 null */
+const readVersionAt = (dir) => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    return typeof pkg.version === 'string' && /^\d+\.\d+\.\d+/.test(pkg.version) ? pkg.version : null
+  } catch { return null }
+}
+
+/** 轻量 semver 比较: a>b 返回 1, a<b 返回 -1, 相等返回 0 (忽略预发布后缀) */
+export function semverCompare(a, b) {
+  const pa = String(a).split('-')[0].split('.').map(Number)
+  const pb = String(b).split('-')[0].split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const x = Number.isFinite(pa[i]) ? pa[i] : 0
+    const y = Number.isFinite(pb[i]) ? pb[i] : 0
+    if (x !== y) return x > y ? 1 : -1
+  }
+  return 0
+}
+
+/** 经 api.github.com Contents API 读取远端 main 分支的 package.json version */
+async function fetchRemoteVersion(timeoutMs = 8000) {
+  const res = await fetch(MANIFEST_API, {
+    headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'dsh-api-dashboard-updater' },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!res.ok) throw new Error(`GitHub API ${res.status}`)
+  const meta = await res.json()
+  const content = Buffer.from(meta.content ?? '', 'base64').toString('utf8')
+  const parsed = JSON.parse(content)
+  return typeof parsed.version === 'string' ? parsed.version : null
+}
+
+/**
+ * 下载并校验最新 tarball 到临时目录, 通过后对每个目标目录执行替换.
+ * 任一目标替换后校验失败即从本次备份自动回滚.
+ * @param {object} opts
+ * @param {string[]} opts.targets 待替换的插件根目录列表 (缺省自动探测; 测试可注入)
+ * @param {number} opts.timeoutMs 下载超时
+ * @param {string} [opts.remoteVersion] 测试注入口: 跳过 GitHub 版本查询
+ * @param {string} [opts.localTarball] 测试注入口: 使用本地 tarball 代替 codeload 下载
+ * @returns {{installed:string, targets:string[], backup:string}}
+ */
+export async function applyUpdate({ targets = null, timeoutMs = 30000, remoteVersion = null, localTarball = null } = {}) {
+  const currentVersion = readVersionAt(SELF_ROOT)
+  const wantVersion = remoteVersion !== null ? remoteVersion : await fetchRemoteVersion(timeoutMs).catch(() => null)
+  if (!wantVersion) throw new Error('remote version unavailable')
+  if (currentVersion && semverCompare(wantVersion, currentVersion) <= 0) {
+    throw new Error(`already up to date (${currentVersion})`)
+  }
+  // 待写入目录: 运行实体优先; 若经典源码目录 (/root/dsha-api-dashboard) 存在
+  // 且是与运行实体不同的另一条真实路径, 一并同步, 避免链接形态下两边版本漂移.
+  // (仅在缺省自动模式下探测; 显式注入 targets 的测试/调试调用不受影响)
+  const dirs = Array.isArray(targets) && targets.length ? [...new Set(targets)] : [SELF_ROOT]
+  if (!Array.isArray(targets)) {
+    try {
+      const legacyReal = realPathSafe('/root/dsha-api-dashboard')
+      const selfReal = realPathSafe(SELF_ROOT)
+      if (legacyReal && selfReal && legacyReal !== selfReal && existsSync(join(legacyReal, 'package.json'))) {
+        dirs.push(legacyReal)
+      }
+    } catch { /* 探测失败不影响主流程 */ }
+  }
+  for (const dir of dirs) {
+    if (!existsSync(join(dir, 'package.json'))) throw new Error(`target missing: ${dir}`)
+  }
+
+  // 1) 下载 tarball 到临时文件
+  const tmpBase = join(tmpdir(), `dshadb-update-${Date.now()}`)
+  mkdirSync(tmpBase, { recursive: true })
+  const tgzPath = join(tmpBase, 'pkg.tar.gz')
+  const extractDir = join(tmpBase, 'extract')
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)
+  let swapped = false
+  try {
+    if (localTarball) {
+      cpSync(localTarball, tgzPath)
+    } else {
+      const res = await fetch(TARBALL_URL, { signal: AbortSignal.timeout(timeoutMs) })
+      if (!res.ok) throw new Error(`download ${res.status}`)
+      writeFileSync(tgzPath, Buffer.from(await res.arrayBuffer()))
+    }
+    // 2) 解压 (--strip-components=1 剥离 codeload 顶层目录)
+    mkdirSync(extractDir, { recursive: true })
+    execFileSync('tar', ['xzf', tgzPath, '-C', extractDir, '--strip-components=1'], { timeout: 20000 })
+    // 3) 校验: 版本号匹配预期 + 关键文件齐全 (装坏了宁可拒绝, 保住回滚机会)
+    if (readVersionAt(extractDir) !== wantVersion) throw new Error('extracted version mismatch')
+    for (const rel of ['src/index.js', 'client/client.js', 'cordis.patch.yml']) {
+      if (!existsSync(join(extractDir, rel))) throw new Error(`missing file after extract: ${rel}`)
+    }
+    // 4) 备份每个目标目录 (tar 包存于其父目录旁, 不放包内避免自我包含)
+    for (const dir of dirs) {
+      execFileSync('tar', ['czf', `${dir}.preupdate-${stamp}.tar.gz`, '-C', dirname(dir), basename(dir)], { timeout: 20000 })
+    }
+    // 5) 交换: 删旧内容 → 拷新内容 (node_modules 保留, 避免重装依赖)
+    for (const dir of dirs) {
+      swapped = true
+      const keep = new Set(['node_modules'])
+      for (const entry of readdirSafe(dir)) {
+        if (!keep.has(entry)) rmSync(join(dir, entry), { recursive: true, force: true })
+      }
+      cpSync(extractDir, dir, { recursive: true })
+      if (readVersionAt(dir) !== wantVersion) throw new Error(`verify failed at ${dir}`)
+    }
+    return { installed: wantVersion, targets: dirs, backup: `${dirs[0]}.preupdate-${stamp}.tar.gz` }
+  } catch (err) {
+    // 回滚: 仅在已开始交换后才需要; 从本次备份整目录还原
+    if (swapped) {
+      for (const dir of dirs) {
+        try {
+          const bakTar = `${dir}.preupdate-${stamp}.tar.gz`
+          if (!existsSync(bakTar)) continue
+          rmSync(dir, { recursive: true, force: true })
+          mkdirSync(dir, { recursive: true })
+          execFileSync('tar', ['xzf', bakTar, '-C', dirname(dir)], { timeout: 20000 })
+        } catch { /* 回滚自身失败时保留备份 tar 供手动恢复 */ }
+      }
+    }
+    throw err
+  } finally {
+    // 临时区无论成败都清掉 (备份 tar 在 targets 旁边, 不受影响)
+    rmSync(tmpBase, { recursive: true, force: true })
+  }
+}
+
+/** 安全取真实路径: 不存在返回 null */
+function realPathSafe(p) {
+  try { return realpathSync(p) } catch { return null }
+}
+
+/** 安全列目录: 不存在/不可读返回空数组 */
+function readdirSafe(dir) {
+  try { return statSync(dir).isDirectory() ? readdirSync(dir) : [] } catch { return [] }
+}
+
+/** 更新检查结果内存缓存: 面板反复打开不重复请求 GitHub */
+let updateCache = { checkedAt: 0, result: null }
+const UPDATE_TTL_MS = 5 * 60 * 1000
+
+async function getUpdateStatus(force = false) {
+  const fresh = Date.now() - updateCache.checkedAt < UPDATE_TTL_MS
+  if (!force && fresh && updateCache.result) return updateCache.result
+  const current = readVersionAt(SELF_ROOT)
+  let result
+  try {
+    const remote = await fetchRemoteVersion()
+    result = { ok: true, current, remote, hasUpdate: current !== null && semverCompare(remote, current) > 0, checkedAt: Date.now() }
+  } catch {
+    // 错误信息固定文案, 不外泄内部异常细节 (沿用 v0.5.16 安全审计口径)
+    result = { ok: false, current, remote: null, hasUpdate: false, checkedAt: Date.now() }
+  }
+  updateCache = { checkedAt: Date.now(), result }
+  return result
+}
+
+// ============================================================
+// 配置持久化: 设置面板保存的配置写入独立状态文件, 重启后恢复
+// (不写回 cordis.patch.yml, 避免 YAML 写坏导致 dsh 起不来)
+// ============================================================
+const STATE_FILE = '/root/.dsh/dsh-api-dashboard.json'
+
+const loadPersistedState = () => {
+  try {
+    const raw = readFileSync(STATE_FILE, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch { return {} }
+}
+
+const savePersistedState = (state) => {
+  try {
+    writeFileSync(STATE_FILE + '.tmp', JSON.stringify(state, null, 2), 'utf8')
+    renameSync(STATE_FILE + '.tmp', STATE_FILE)
+    return true
+  } catch { return false }
+}
+
+// ============================================================
+// 工具函数
+// ============================================================
+const toAmount = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+// ============================================================
+// DeepSeek 峰谷计费引擎 (学习 dsh-balance)
+// 北京时间 09:00~12:00 / 14:00~18:00 为峰时(100%), 其余时段谷时特惠(5折)
+// ============================================================
+export const V4_RATES = {
+  CNY: {
+    peak: { 'deepseek-v4-flash': { cacheHit: 0.1, cacheMiss: 3, output: 9 }, 'deepseek-v4-pro': { cacheHit: 0.3, cacheMiss: 9, output: 27 } },
+    offPeak: { 'deepseek-v4-flash': { cacheHit: 0.05, cacheMiss: 1.5, output: 4.5 }, 'deepseek-v4-pro': { cacheHit: 0.15, cacheMiss: 4.5, output: 13.5 } },
+  },
+  USD: {
+    peak: { 'deepseek-v4-flash': { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 }, 'deepseek-v4-pro': { cacheHit: 0.044, cacheMiss: 1.32, output: 3.96 } },
+    offPeak: { 'deepseek-v4-flash': { cacheHit: 0.007, cacheMiss: 0.22, output: 0.66 }, 'deepseek-v4-pro': { cacheHit: 0.022, cacheMiss: 0.66, output: 1.98 } },
+  },
+}
+
+/**
+ * 当前是否处于 DeepSeek 峰时.
+ *  工作日(周一~周五): 北京时间 09-12 / 14-18 为峰时, 其余谷时。
+ *  周末(周六日): 整天都是谷时特惠。
+ */
+export const isPeakTime = (timestamp = Date.now()) => {
+  const d = new Date(timestamp)
+  const day = d.getUTCDay()
+  const hourBJT = (d.getUTCHours() + 8) % 24
+  // 周末(0=周日, 6=周六)整天谷时
+  if (day === 0 || day === 6) return false
+  return (hourBJT >= 9 && hourBJT < 12) || (hourBJT >= 14 && hourBJT < 18)
+}
+
+/** 当前是否周末 */
+export const isWeekend = (timestamp = Date.now()) => {
+  const d = new Date(timestamp)
+  const day = d.getUTCDay()
+  return day === 0 || day === 6
+}
+
+
+// ============================================================
+// 通用模型价格表 (CNY, 每百万token)
+// 用于 balanceCost 投影中非 DeepSeek 模型的计费估算.
+// 来源: 各平台官方定价 (2025-08), 仅做参考, 实际以平台为准.
+// ============================================================
+export const MODEL_PRICES = {
+  // OpenAI
+  'gpt-4o':               { cacheHit: 1.25,  cacheMiss: 2.5,  output: 10 },
+  'gpt-4o-mini':          { cacheHit: 0.075, cacheMiss: 0.15, output: 0.6 },
+  'gpt-4-turbo':          { cacheHit: 5,     cacheMiss: 10,   output: 30 },
+  'gpt-4':                { cacheHit: 15,    cacheMiss: 30,   output: 60 },
+  'o1':                   { cacheHit: 7.5,   cacheMiss: 15,   output: 60 },
+  'o1-mini':              { cacheHit: 0.55,  cacheMiss: 1.1,  output: 4.4 },
+  'o3-mini':              { cacheHit: 0.55,  cacheMiss: 1.1,  output: 4.4 },
+  // Claude
+  'claude-3-5-sonnet':    { cacheHit: 1.5,   cacheMiss: 3,    output: 15 },
+  'claude-3-5-haiku':     { cacheHit: 0.4,   cacheMiss: 0.8,  output: 4 },
+  'claude-3-opus':        { cacheHit: 7.5,   cacheMiss: 15,   output: 75 },
+  // Gemini
+  'gemini-2.0-flash':     { cacheHit: 0.05,  cacheMiss: 0.1,  output: 0.4 },
+  'gemini-2.0-pro':       { cacheHit: 1.25,  cacheMiss: 2.5,  output: 10 },
+  'gemini-1.5-pro':       { cacheHit: 1.75,  cacheMiss: 3.5,  output: 10.5 },
+  // DeepSeek (标准价兜底)
+  'deepseek-chat':        { cacheHit: 0.1,   cacheMiss: 1,    output: 2 },
+  'deepseek-reasoner':    { cacheHit: 0.2,   cacheMiss: 2,    output: 8 },
+  'deepseek-r1':          { cacheHit: 0.2,   cacheMiss: 2,    output: 8 },
+  // 智谱
+  'glm-4-plus':           { cacheHit: 2.5,   cacheMiss: 5,    output: 5 },
+  'glm-4-flash':          { cacheHit: 0.05,  cacheMiss: 0.1,  output: 0.1 },
+  // 通义千问
+  'qwen-plus':            { cacheHit: 0.4,   cacheMiss: 0.8,  output: 2 },
+  'qwen-max':             { cacheHit: 10,    cacheMiss: 20,   output: 60 },
+  'qwen-turbo':           { cacheHit: 0.15,  cacheMiss: 0.3,  output: 0.6 },
+  'qwen2.5-72b-instruct': { cacheHit: 2,     cacheMiss: 4,    output: 12 },
+  // Kimi
+  'moonshot-v1-8k':       { cacheHit: 0.6,   cacheMiss: 1.2,  output: 2.4 },
+  'moonshot-v1-32k':      { cacheHit: 1.2,   cacheMiss: 2.4,  output: 4.8 },
+  'moonshot-v1-128k':     { cacheHit: 3,     cacheMiss: 6,    output: 12 },
+  // 阶跃星辰
+  'step-1-flash':         { cacheHit: 0.5,   cacheMiss: 1,    output: 2 },
+  'step-1-8k':            { cacheHit: 2,     cacheMiss: 4,    output: 8 },
+  'step-1-32k':           { cacheHit: 4,     cacheMiss: 8,    output: 15 },
+  // 其他
+  'mistral-large':        { cacheHit: 1.5,   cacheMiss: 3,    output: 9 },
+  'groq-llama-3.3-70b':  { cacheHit: 0.29,  cacheMiss: 0.59, output: 0.79 },
+  'openrouter-auto':      { cacheHit: 0.5,   cacheMiss: 1,    output: 2 },
+}
+
+/** 解析模型单价, 仅 deepseek-v4-* 支持峰谷自动切换; chat/reasoner 等走通用价格表 */
+export const resolveModelPrice = (configOrGetter, model, timestamp = Date.now()) => {
+  const config = typeof configOrGetter === 'function' ? configOrGetter() : configOrGetter
+  const peak = isPeakTime(timestamp)
+
+  // 自定义价格优先
+  if (config?.prices && Object.prototype.hasOwnProperty.call(config.prices, model) && config.prices[model]) {
+    return config.prices[model]
+  }
+
+  // v0.5.3 修复: 原 startsWith('deepseek') 会把 deepseek-chat/reasoner 劫持进 V4 峰谷表,
+  // 导致其按 v4-flash 价格计费 (output 虚高至 4.5 倍)。仅精确匹配 v4 系列。
+  if (model === 'deepseek-v4-pro' || model === 'deepseek-v4-flash' || model.startsWith('deepseek-v4')) {
+    const currency = (config?.currency ?? 'CNY').toUpperCase() === 'USD' ? 'USD' : 'CNY'
+    const table = V4_RATES[currency] ?? V4_RATES.CNY
+    const key = model === 'deepseek-v4-pro' || model.startsWith('deepseek-v4-pro') ? 'deepseek-v4-pro' : 'deepseek-v4-flash'
+    return (peak ? table.peak[key] : table.offPeak[key]) ?? config?.defaultPrices
+  }
+  // 查询 MODEL_PRICES 表兜底 (优先匹配完整模型名, 再试前缀匹配)
+  const exact = MODEL_PRICES[model]
+  if (exact) return exact
+  const prefix = Object.keys(MODEL_PRICES).find(k => model.startsWith(k) || k.startsWith(model))
+  if (prefix) return MODEL_PRICES[prefix]
+  return config?.defaultPrices ?? { cacheHit: 0.1, cacheMiss: 1, output: 2 }
+}
+
+/** 通用 fetch 请求, 带超时。 */
+async function fetchWithTimeout(url, headers, timeoutMs, method = 'GET') {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, { method, headers, signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ============================================================
+// 平台预设 (完整清单)
+// ============================================================
+
+/**
+ * 每个平台:
+ *  id / label / icon(图标文件名) / color / category(官方|海外|国内|本地|中转站)
+ *  baseUrl / queryType(余额解析类型) / envKeys(可读取的key名) / noBalance(是否默认无余额接口)
+ */
+const PLATFORM_PRESETS = [
+  // ===== 国内平台（有公开余额/配额查询接口）=====
+  { id: 'deepseek', label: 'DeepSeek', icon: 'deepseek', color: '#4D6BFE', category: '国内',
+    baseUrl: 'https://api.deepseek.com', queryType: 'deepseek', envKeys: ['DEEPSEEK_API_KEY'] },
+  { id: 'zhipu', label: '智谱 GLM', icon: 'zhipu', color: '#3859FF', category: '国内',
+    // v0.5.5: 实测余额监控接口在 open.bigmodel.cn (api.z.ai 同路径 401); 补 ZAI_CODING_CN 等 key 别名
+    baseUrl: 'https://open.bigmodel.cn', queryType: 'glm', envKeys: ['ZHIPU_API_KEY', 'GLM_API_KEY', 'BIGMODEL_API_KEY', 'ZAI_CODING_CN_API_KEY', 'ZAI_API_KEY'] },
+  { id: 'moonshot', label: 'Kimi Moonshot', icon: 'moonshot', color: '#000000', category: '国内',
+    baseUrl: 'https://api.moonshot.cn', queryType: 'kimi', envKeys: ['MOONSHOT_API_KEY', 'KIMI_API_KEY'] },
+  { id: 'stepfun', label: '阶跃星辰 StepFun', icon: 'mistral', color: '#FA520F', category: '国内',
+    baseUrl: 'https://api.stepfun.com', queryType: 'stepfun', envKeys: ['STEPFUN_API_KEY'] },
+  { id: 'siliconflow', label: '硅基流动', icon: 'siliconflow', color: '#6E29F6', category: '国内',
+    baseUrl: 'https://api.siliconflow.cn', queryType: 'siliconflow', envKeys: ['SILICONFLOW_API_KEY', 'SILICON_API_KEY'] },
+  { id: 'minimax', label: 'MiniMax', icon: 'together', color: '#1E40AF', category: '国内',
+    baseUrl: 'https://api.minimaxi.com', queryType: 'minimax', envKeys: ['MINIMAX_API_KEY'] },
+
+  // ===== 海外平台（有公开余额/配额查询接口）=====
+  { id: 'openrouter', label: 'OpenRouter', icon: 'openrouter', color: '#6469FF', category: '海外',
+    baseUrl: 'https://openrouter.ai', queryType: 'openrouter', envKeys: ['OPENROUTER_API_KEY'] },
+  { id: 'novita', label: 'Novita AI', icon: 'together', color: '#FA520F', category: '海外',
+    baseUrl: 'https://api.novita.ai', queryType: 'novita', envKeys: ['NOVITA_API_KEY'] },
+  { id: 'xai', label: 'xAI Grok', icon: 'mistral', color: '#000000', category: '海外',
+    baseUrl: 'https://api.x.ai', queryType: 'openai', envKeys: ['XAI_API_KEY'] },
+]
+
+// ============================================================
+// Config Schema
+// ============================================================
+const RelaySchema = Schema.object({
+  id: Schema.string(),
+  name: Schema.string().required(),
+  baseUrl: Schema.string().required(),
+  apiKey: Schema.string().default(''),
+  queryType: Schema.string().default('auto'),
+})
+
+export const Config = Schema.object({
+  refreshIntervalMs: Schema.number().min(1000).default(5000),
+  clientPollIntervalMs: Schema.number().min(5000).default(5000),
+  timeoutMs: Schema.number().min(1000).default(8000),
+  presets: Schema.array(Schema.string()).default(PLATFORM_PRESETS.map(p => p.id)),
+  customRelays: Schema.array(RelaySchema).default([]),
+  /** 安全阈值: 余额 > safe 显示绿色, > warn 黄色, 否则红色 */
+  safeThreshold: Schema.number().min(0).default(50),
+  warnThreshold: Schema.number().min(0).default(10),
+  /** 计价货币 */
+  currency: Schema.string().default('CNY'),
+  prices: Schema.dict(Schema.object({
+    cacheHit: Schema.number().min(0).default(0.2),
+    cacheMiss: Schema.number().min(0).default(2),
+    output: Schema.number().min(0).default(8),
+  })).default({}),
+  defaultPrices: Schema.object({
+    cacheHit: Schema.number().min(0).default(0.1),
+    cacheMiss: Schema.number().min(0).default(1),
+    output: Schema.number().min(0).default(2),
+  }).default({}),
+})
+
+// ============================================================
+
+// ============================================================
+// 余额告警检测 (A3: 低于阈值时推送通知)
+// ============================================================
+let lastAlertState = {}
+
+function checkAlerts(balances, config, ctx) {
+  const safe = config.safeThreshold ?? 50
+  const warn = config.warnThreshold ?? 10
+  const newState = {}
+
+  for (const b of balances) {
+    if (b.status !== 'ok') continue
+    const id = b.platform
+    const val = b.percent != null ? b.percent : b.total
+    const prev = lastAlertState[id]
+    let level = val > safe ? 'ok' : val > warn ? 'warn' : 'err'
+
+    if (level === 'warn' && prev !== 'warn') {
+      newState[id] = 'warn'
+      try {
+        const name = b.name || id
+        const msg = `🔔 ${name} 余额偏低: ${val}${b.percent != null ? '%' : (b.currency || '')}`
+        if (ctx && typeof ctx.notify === 'function') {
+          ctx.notify({ title: '哦鲸鲸', message: msg, level: 'warning' })
+        } else if (ctx && ctx.get && typeof ctx.get('webServer')?.notify === 'function') {
+          ctx.get('webServer').notify({ title: '哦鲸鲸', message: msg, level: 'warning' })
+        }
+      } catch { /* 静默 */ }
+    } else if (level === 'err' && prev !== 'err') {
+      newState[id] = 'err'
+      try {
+        const name = b.name || id
+        const msg = `🚨 ${name} 余额不足: ${val}${b.percent != null ? '%' : (b.currency || '')}`
+        if (ctx && typeof ctx.notify === 'function') {
+          ctx.notify({ title: '哦鲸鲸', message: msg, level: 'error' })
+        } else if (ctx && ctx.get && typeof ctx.get('webServer')?.notify === 'function') {
+          ctx.get('webServer').notify({ title: '哦鲸鲸', message: msg, level: 'error' })
+        }
+      } catch { /* 静默 */ }
+    }
+  }
+  lastAlertState = newState
+}
+
+// 余额解析适配器
+// ============================================================
+
+function parseResponse(queryType, json) {
+  switch (queryType) {
+    case 'deepseek': {
+      const infos = Array.isArray(json?.balance_infos) ? json.balance_infos : []
+      const p = infos[0]
+      if (!p) return null
+      // total_balance 当前余额, granted_balance 赠送, topped_up_balance 充值
+      const total = toAmount(p.total_balance)
+      const grant = toAmount(p.granted_balance)
+      const topup = toAmount(p.topped_up_balance)
+      // 已用 = 充值 + 赠送 - 当前余额 (近似)
+      return { total, currency: p.currency || 'CNY', available: total, used: Math.max(0, topup + grant - total), topup, grant, note: '可用余额' }
+    }
+    case 'openai':
+    case 'openai-credit-grants': {
+      if (!json || typeof json !== 'object') return null
+      const hasAny = 'total_granted' in json || 'total_available' in json || 'total_used' in json
+      if (!hasAny) return null
+      const total = toAmount(json?.total_granted)
+      const used = toAmount(json?.total_used)
+      const available = toAmount(json?.total_available)
+      return { total: available || (total - used), currency: 'USD', available, used, note: 'OpenAI 兼容额度' }
+    }
+    case 'siliconflow': {
+      const d = json?.data
+      if (!d) return null
+      return { total: toAmount(d.totalBalance), currency: 'CNY', available: null, used: null, note: '硅基流动总余额' }
+    }
+    case 'openrouter': {
+      const d = json?.data
+      if (!d) return null
+      return { total: toAmount(d.total_credits) - toAmount(d.total_usage), currency: 'USD', available: toAmount(d.total_credits), used: toAmount(d.total_usage), note: 'OpenRouter 余额' }
+    }
+    case 'novita': {
+      if (!json || !('availableBalance' in json)) return null
+      const raw = toAmount(json?.availableBalance)
+      return { total: raw / 10000, currency: 'USD', available: null, used: null, note: 'Novita (0.0001单位)' }
+    }
+    case 'stepfun': {
+      if (!json || !('balance' in json)) return null
+      const b = toAmount(json?.balance)
+      return { total: b, currency: 'CNY', available: null, used: null, note: '阶梯星辰余额' }
+    }
+    case 'quota': {
+      const quota = toAmount(json?.data?.quota)
+      if (quota === 0 && !json?.data?.username) return null
+      return { total: quota / 500000, currency: 'USD', available: null, used: null, note: 'one-api quota (÷500000)' }
+    }
+    case 'openai-billing': {
+      const limit = toAmount(json?.hard_limit_usd)
+      if (limit === 0 && !json?.has_credit_card) return null
+      return { total: limit, currency: 'USD', available: limit, used: null, note: 'OpenAI 订阅硬上限' }
+    }
+    case 'glm': {
+      // 智谱 monitor 返回 data.limits[], 同时存在「套餐%」与「限流配额(五小时×2000 token)」。
+      // 判决口径(用户确认): 保留「百分比」显示——积分/套餐的 percentage 较准确。
+      // 仅当完全无 percentage 时才回退到 remaining(带"剩余 token"标注, 不冒充真实余额),
+      // 避免把「五小时限流窗口」误当账户余额误导用户。
+      const limits = Array.isArray(json?.data?.limits) ? json.data.limits : []
+      const num = (v) => { const n = Number(v); return Number.isFinite(n) ? n : null }
+      const pctOf = (l) => { const n = Number(l?.percentage ?? l?.remaining_percentage); return Number.isFinite(n) && n >= 0 && n <= 100 ? n : null }
+      const near = (a, b) => (Number(a?.nextResetTime) || 0) - (Number(b?.nextResetTime) || 0)
+      // 1) 优先: 百分比套餐
+      const pctCands = limits.map((l) => ({ l, p: pctOf(l) })).filter((x) => x.p !== null)
+      let pk = pctCands.find((x) => x.l.type === 'TOKENS_LIMIT') || (pctCands.sort((a, b) => near(b.l, a.l))[0] ?? null)
+      if (pk) {
+        const p = pk.p
+        return { total: p, currency: '%', available: p, used: 100 - p, note: '智谱剩余%', percent: true, resetAt: pk.l.nextResetTime ?? null }
+      }
+      // 2) 兜底: 无任何 percentage → 只剩配额/remaining 值; 明确标注是"剩余 token"而非金额余额
+      const rem = (l) => num(l?.remaining ?? l?.remaining_quota)
+      const balCands = limits.map((l) => ({ l, r: rem(l) })).filter((x) => x.r !== null && x.r > 0)
+      if (balCands.length > 0) {
+        const best = balCands.sort((a, b) => b.r - a.r)[0]
+        return { total: best.r, currency: 'tokens', available: best.r, used: null, note: '智谱剩余 token(限流配额)', percent: null, resetAt: best.l.nextResetTime ?? null }
+      }
+      return null
+    }
+
+    case 'kimi': {
+      const u = json?.usage
+      if (!u) return null
+      const limit = toAmount(u.limit), remaining = toAmount(u.remaining)
+      return { total: limit, currency: 'tokens', available: remaining, used: limit - remaining, note: 'Kimi 套餐剩余 tokens', percent: limit > 0 ? (remaining / limit) * 100 : null }
+    }
+    case 'minimax': {
+      const models = Array.isArray(json?.model_remains) ? json.model_remains : []
+      const m = models[0]
+      if (!m || !('remaining_credit' in m)) return null
+      return { total: toAmount(m.remaining_credit), currency: 'CNY', available: toAmount(m.remaining_credit), used: null, note: 'MiniMax 剩余额度' }
+    }
+    default:
+      return null
+  }
+}
+
+/** 某些类型无法用普通 API key 查询余额 (需 OAuth 等) */
+// ============================================================
+// 查询单个预设平台
+// ============================================================
+async function queryPreset(platform, apiKey, config) {
+  if (!apiKey) {
+    return {
+      platform: platform.id, name: platform.label, icon: platform.icon, color: platform.color,
+      category: platform.category, status: 'no-key', error: '未配置 API Key', noBalance: false,
+    }
+  }
+
+  // 端点构造
+  let url = '', headers = { Accept: 'application/json' }, method = 'GET'
+  let queryType = platform.queryType
+  const base = platform.baseUrl.replace(/\/+$/, '')
+
+  switch (platform.queryType) {
+    case 'deepseek': url = `${base}/user/balance`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'openai': url = `${base}/v1/dashboard/billing/credit_grants`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'siliconflow': url = `${base}/v1/user/info`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'openrouter': url = `${base}/api/v1/credits`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'novita': url = `${base}/v3/user/balance`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'stepfun': url = `${base}/v1/accounts`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'quota': url = `${base}/api/user/self`; headers['Authorization'] = `Bearer ${apiKey}`; method = 'POST'; break
+    case 'openai-billing': url = `${base}/v1/dashboard/billing/subscription`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'glm': url = `${base}/api/monitor/usage/quota/limit`; headers['Authorization'] = apiKey; break
+    case 'kimi': url = `${base}/coding/v1/usages`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    case 'minimax': url = `${base}/v1/api/openplatform/coding_plan/remains`; headers['Authorization'] = `Bearer ${apiKey}`; break
+    default: url = `${base}/v1/dashboard/billing/credit_grants`; headers['Authorization'] = `Bearer ${apiKey}`; queryType = 'openai'; break
+  }
+
+  try {
+    const res = await fetchWithTimeout(url, headers, config.timeoutMs || 8000, method)
+    if (!res.ok) {
+      const isAuth = res.status === 401 || res.status === 403
+      return {
+        platform: platform.id, name: platform.label, icon: platform.icon, color: platform.color,
+        category: platform.category,
+        status: isAuth ? 'auth-error' : (res.status === 404 || res.status === 405 ? 'no-balance-api' : 'error'),
+        error: `HTTP ${res.status}${isAuth ? ' (认证失败)' : res.status === 404 ? ' (未开放余额接口)' : ''}`,
+        noBalance: res.status === 404 || res.status === 405,
+      }
+    }
+
+    const text = await res.text()
+    let json
+    try { json = JSON.parse(text) } catch { json = null }
+    const parsed = parseResponse(queryType, json)
+
+    if (!parsed) {
+      return {
+        platform: platform.id, name: platform.label, icon: platform.icon, color: platform.color,
+        category: platform.category, status: 'parse-error', error: '无法解析余额数据', noBalance: true,
+      }
+    }
+
+    return {
+      platform: platform.id, name: platform.label, icon: platform.icon, color: platform.color,
+      category: platform.category, status: 'ok', total: parsed.total, currency: parsed.currency,
+      available: parsed.available, used: parsed.used, topup: parsed.topup, grant: parsed.grant,
+      note: parsed.note, percent: parsed.percent,
+      noBalance: false, fetchedAt: Date.now(),
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      platform: platform.id, name: platform.label, icon: platform.icon, color: platform.color,
+      category: platform.category,
+      status: 'error', error: message.includes('abort') ? '请求超时' : '网络错误', noBalance,
+    }
+  }
+}
+
+// ============================================================
+// 自定义中转站查询 (自动探测)
+// ============================================================
+function relayTypePath(queryType) {
+  switch (queryType) {
+    case 'openai-billing': return '/v1/dashboard/billing/subscription'
+    case 'openai': return '/v1/dashboard/billing/credit_grants'
+    case 'quota': return '/api/user/self'
+    case 'auto': return null
+    default: return '/v1/dashboard/billing/subscription'
+  }
+}
+
+async function queryCustomRelay(relay, config) {
+  const { id, name, baseUrl, apiKey, queryType } = relay
+  if (!apiKey) {
+    return { platform: id, name: name || '中转站', icon: 'relay', color: '#64748B', category: '中转站', status: 'no-key', error: '未配置 API Key', noBalance: true }
+  }
+  const base = (baseUrl || '').replace(/\/+$/, '')
+
+  // 候选端点探测
+  const candidates = []
+  if (queryType && queryType !== 'auto') {
+    candidates.push({ type: queryType, path: relayTypePath(queryType) })
+  } else {
+    candidates.push(
+      { type: 'openai-billing', path: '/v1/dashboard/billing/subscription' },
+      { type: 'quota', path: '/api/user/self' },
+      { type: 'openai', path: '/v1/dashboard/billing/credit_grants' },
+    )
+  }
+
+  for (const cand of candidates) {
+    const headers = { Accept: 'application/json', Authorization: `Bearer ${apiKey}` }
+    const method = cand.type === 'quota' ? 'POST' : 'GET'
+    try {
+      const res = await fetchWithTimeout(base + cand.path, headers, config.timeoutMs || 8000, method)
+      if (!res.ok) continue
+      const text = await res.text()
+      let json
+      try { json = JSON.parse(text) } catch { continue }
+      const parsed = parseResponse(cand.type, json)
+      if (parsed) {
+        return {
+          platform: id, name: name || '中转站', icon: 'relay', color: '#64748B', category: '中转站',
+          status: 'ok', total: parsed.total, currency: parsed.currency, available: parsed.available,
+          used: parsed.used, note: parsed.note || cand.type, percent: parsed.percent,
+          noBalance: false, queryType: cand.type, fetchedAt: Date.now(),
+        }
+      }
+    } catch { /* 尝试下一个 */ }
+  }
+
+  return {
+    platform: id, name: name || '中转站', icon: 'relay', color: '#64748B', category: '中转站',
+    status: 'no-balance-api', error: '该平台未开放余额查询', noBalance: true,
+  }
+}
+
+// ============================================================
+// 自定义模型余额查询 (用户自己提供余额接口)
+// 支持: 手动映射(totalPath/usedPath 点分路径) / 指定解析类型(queryType) / 自动探测(auto)
+// ============================================================
+export const dotGet = (obj, path) => {
+  if (!path || obj == null) return undefined
+  return String(path).split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
+}
+
+export async function queryCustomModel(model, config) {
+  const { id, name, apiUrl, apiKey, queryType, totalPath, usedPath, currency } = model
+  const base = { platform: id, name: name || '自定义模型', icon: 'relay', color: '#8B5CF6', category: '自定义' }
+  if (!apiUrl) {
+    return { ...base, status: 'no-key', error: '未配置接口 URL', noBalance: true }
+  }
+  const headers = { Accept: 'application/json' }
+  if (apiKey) headers['Authorization'] = apiKey.trim().startsWith('Bearer') ? apiKey.trim() : `Bearer ${apiKey.trim()}`
+  try {
+    const res = await fetchWithTimeout(apiUrl, headers, config.timeoutMs || 8000, 'GET')
+    if (!res.ok) {
+      const isAuth = res.status === 401 || res.status === 403
+      return { ...base, status: isAuth ? 'auth-error' : 'error', error: `HTTP ${res.status}${isAuth ? ' (认证失败)' : ''}`, noBalance: true }
+    }
+    const text = await res.text()
+    let json
+    try { json = JSON.parse(text) } catch { json = null }
+
+    // 1) 手动映射优先 (totalPath 点分路径, 如 data.balance)
+    if (totalPath) {
+      const total = toAmount(dotGet(json, totalPath))
+      if (Number.isFinite(total) && (total !== 0 || json != null)) {
+        const used = usedPath ? toAmount(dotGet(json, usedPath)) : null
+        return {
+          ...base, status: 'ok', total, currency: currency || 'CNY',
+          available: used != null && used >= 0 ? total - used : total, used,
+          note: '自定义映射', percent: null, noBalance: false, queryType: 'custom', fetchedAt: Date.now(),
+        }
+      }
+    }
+
+    // 2) 指定解析类型
+    if (queryType && queryType !== 'auto') {
+      const parsed = parseResponse(queryType, json)
+      if (parsed) {
+        return { ...base, status: 'ok', total: parsed.total, currency: parsed.currency, available: parsed.available, used: parsed.used, note: parsed.note, percent: parsed.percent, noBalance: false, queryType, fetchedAt: Date.now() }
+      }
+    } else {
+      // 3) auto: 尝试常见格式
+      for (const qt of ['openai', 'quota', 'deepseek', 'openai-billing']) {
+        const parsed = parseResponse(qt, json)
+        if (parsed) {
+          return { ...base, status: 'ok', total: parsed.total, currency: parsed.currency, available: parsed.available, used: parsed.used, note: parsed.note, percent: parsed.percent, noBalance: false, queryType: qt, fetchedAt: Date.now() }
+        }
+      }
+    }
+    return { ...base, status: 'parse-error', error: '无法解析余额数据', noBalance: true }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ...base, status: 'error', error: message.includes('abort') ? '请求超时' : '网络错误', noBalance: true }
+  }
+}
+
+// ============================================================
+// 会话消耗投影 (学习 dsh-balance queryBalanceCost)
+// ============================================================
+export function makeCostProjection(configOrGetter) {
+  const getConfig = () => typeof configOrGetter === 'function' ? configOrGetter() : configOrGetter
+  const zero = () => ({ uncachedInputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 })
+  const bucketsOf = (usage) => ({
+    uncachedInputTokens: usage.inputTokens,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+    cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+    outputTokens: usage.outputTokens,
+  })
+  const bucketsEqual = (a, b) =>
+    a.uncachedInputTokens === b.uncachedInputTokens && a.cacheReadTokens === b.cacheReadTokens &&
+    a.cacheWriteTokens === b.cacheWriteTokens && a.outputTokens === b.outputTokens
+  const addBuckets = (a, b) => ({
+    uncachedInputTokens: a.uncachedInputTokens + b.uncachedInputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+  })
+  const subBuckets = (a, b) => ({
+    uncachedInputTokens: a.uncachedInputTokens - b.uncachedInputTokens,
+    cacheReadTokens: a.cacheReadTokens - b.cacheReadTokens,
+    cacheWriteTokens: a.cacheWriteTokens - b.cacheWriteTokens,
+    outputTokens: a.outputTokens - b.outputTokens,
+  })
+  const round6 = (n) => Math.round(n * 1e6) / 1e6
+
+  return {
+    key: 'queryBalanceCost',
+    // 框架要求的投影定义 API: stateSchema(内部状态) + wire.{viewSchema,view}(客户端可见视图)。
+    // 旧版误用顶层 schema+view, 导致 wire 缺失, 服务端 drive 永不通知、客户端永远拿不到值。
+    stateSchema: z.object({
+      currentModel: z.string().nullable(),
+      last: z.object({
+        turn: z.number(),
+        step: z.number(),
+        model: z.string(),
+        buckets: z.object({
+          uncachedInputTokens: z.number(),
+          cacheReadTokens: z.number(),
+          cacheWriteTokens: z.number(),
+          outputTokens: z.number(),
+        }),
+      }).nullable(),
+      byModel: z.record(z.string(), z.object({
+        uncachedInputTokens: z.number(),
+        cacheReadTokens: z.number(),
+        cacheWriteTokens: z.number(),
+        outputTokens: z.number(),
+      })),
+      modelOrder: z.array(z.string()),
+    }),
+    init: () => ({ currentModel: null, last: null, byModel: {}, modelOrder: [] }),
+    apply: (state, event) => {
+      let nextModel = state.currentModel
+      if (event.type === 'request/header') {
+        const model = event.data.header?.config?.model
+        if (typeof model === 'string' && model !== '') nextModel = model
+      } else if (event.type === 'request/context') {
+        const model = event.data.model
+        if (typeof model === 'string' && model !== '') nextModel = model
+      }
+      let usage = null, turn = 0, step = 0
+      if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+        ({ turn, step } = event.data); usage = event.data.chunk.usage
+      } else if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+        ({ turn, step, usage } = event.data)
+      }
+      if (usage === null) return nextModel === state.currentModel ? state : { ...state, currentModel: nextModel }
+      const model = nextModel ?? 'unknown'
+      const buckets = bucketsOf(usage)
+      const prev = state.last !== null && state.last.turn === turn && state.last.step === step ? state.last : null
+      if (prev !== null && prev.model === model && bucketsEqual(prev.buckets, buckets)) {
+        return nextModel === state.currentModel ? state : { ...state, currentModel: nextModel }
+      }
+      const isNewModel = !(model in state.byModel)
+      let byModel = state.byModel
+      if (prev !== null) byModel = { ...byModel, [prev.model]: subBuckets(byModel[prev.model] ?? zero(), prev.buckets) }
+      byModel = { ...byModel, [model]: addBuckets(byModel[model] ?? zero(), buckets) }
+      return { ...state, currentModel: nextModel, last: { turn, step, model, buckets }, byModel, modelOrder: isNewModel ? [...state.modelOrder, model] : state.modelOrder }
+    },
+    wire: {
+      viewSchema: z.object({
+        models: z.array(z.string()),
+        // v0.5.3: 暴露当前会话正在使用的模型, 客户端据此自动切换选中平台
+        currentModel: z.string().nullable(),
+        cost: z.number(),
+        costByModel: z.record(z.string(), z.number().nonnegative()),
+        tokens: z.object({ uncachedInput: z.number().int().nonnegative(), cacheRead: z.number().int().nonnegative(), cacheWrite: z.number().int().nonnegative(), output: z.number().int().nonnegative() }).strict(),
+        tokensByModel: z.record(z.string(), z.object({ uncachedInputTokens: z.number().int().nonnegative(), cacheReadTokens: z.number().int().nonnegative(), cacheWriteTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative() }).strict()).optional(),
+        currency: z.string(),
+        isPeak: z.boolean().optional(),
+        waiting: z.boolean().optional(),
+      }).strict(),
+      view: (state) => {
+      const cfg = getConfig()
+      // 无事件时返回 waiting 标记, 客户端据此显示 "~—" 而非 "~¥0"
+      if (state.modelOrder.length === 0) {
+        return { models: [], currentModel: state.currentModel ?? null, cost: -1, costByModel: {}, tokens: { uncachedInput: 0, cacheRead: 0, cacheWrite: 0, output: 0 }, tokensByModel: {}, currency: cfg.currency ?? 'CNY', isPeak: isPeakTime(), waiting: true }
+      }
+      const tokens = { uncachedInput: 0, cacheRead: 0, cacheWrite: 0, output: 0 }
+      const costByModel = {}
+      let cost = 0
+      const defaultPrice = cfg.defaultPrices ?? { cacheHit: 0.1, cacheMiss: 1, output: 2 }
+      const peak = isPeakTime()
+      for (const model of state.modelOrder) {
+        const b = state.byModel[model] ?? zero()
+        tokens.uncachedInput += b.uncachedInputTokens
+        tokens.cacheRead += b.cacheReadTokens
+        tokens.cacheWrite += b.cacheWriteTokens
+        tokens.output += b.outputTokens
+        // 支持 DeepSeek 谷峰自动计费
+        const price = resolveModelPrice(cfg, model)
+        const c = ((b.uncachedInputTokens + b.cacheWriteTokens) * price.cacheMiss + b.cacheReadTokens * price.cacheHit + b.outputTokens * price.output) / 1e6
+        if (c > 0) costByModel[model] = round6(c)
+        cost += c
+      }
+      return { models: state.modelOrder, currentModel: state.currentModel ?? null, cost: round6(cost), costByModel, tokens, tokensByModel: state.byModel, currency: cfg.currency ?? 'CNY', isPeak: peak, waiting: false }
+      },
+    },
+    stateVersion: 1,
+  }
+}
+
+// ============================================================
+// 插件主体
+// ============================================================
+export function apply(ctx, config) {
+  // 用户保存的配置优先于 cordis.patch.yml 的默认 config (持久化状态)
+  const persisted = loadPersistedState()
+  const runtimeConfig = {
+    refreshIntervalMs: persisted.refreshIntervalMs ?? config.refreshIntervalMs ?? 5000,
+    clientPollIntervalMs: persisted.clientPollIntervalMs ?? config.clientPollIntervalMs ?? 5000,
+    timeoutMs: persisted.timeoutMs ?? config.timeoutMs ?? 8000,
+    presets: config.presets ?? PLATFORM_PRESETS.map(p => p.id),
+    customRelays: (persisted.customRelays ?? config.customRelays ?? []).map(r => ({ ...r })),
+    customModels: (persisted.customModels ?? config.customModels ?? []).map(m => ({ ...m })),
+    prices: config.prices ?? { 'deepseek-chat': { cacheHit: 0.1, cacheMiss: 1, output: 2 } },
+    defaultPrices: config.defaultPrices ?? { cacheHit: 0.1, cacheMiss: 1, output: 2 },
+    currency: persisted.currency ?? config.currency ?? 'CNY',
+    safeThreshold: persisted.safeThreshold ?? config.safeThreshold ?? 50,
+    warnThreshold: persisted.warnThreshold ?? config.warnThreshold ?? 10,
+  }
+
+  const getConfig = () => runtimeConfig
+
+  /** 解析预设平台的 API key (从环境变量、credentials 系统或直接读凭据文件) */
+  const resolvePresetKey = async (platform) => {
+    // 1) 环境变量
+    for (const name of platform.envKeys || []) {
+      if (process.env[name]) return process.env[name]
+    }
+    // 2) DSH credentials 服务
+    const creds = ctx.get('credentials')
+    if (creds !== undefined) {
+      for (const ref of (platform.envKeys || [])) {
+        try {
+          const hit = await creds.resolve(ref)
+          if (hit !== undefined) return hit.value
+        } catch { /* 忽略 */ }
+      }
+    }
+    // 3) 直接读 ~/.dsh/.credentials.yaml 文件兜底
+    try {
+      const { readFileSync } = await import('node:fs')
+      const { homedir } = await import('node:os')
+      const { join } = await import('node:path')
+      const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+      const raw = readFileSync(join(home, '.credentials.yaml'), 'utf8')
+      const lines = raw.split('\n')
+      let inRefs = false
+      for (const line of lines) {
+        if (line === 'refs:') { inRefs = true; continue }
+        if (inRefs) {
+          if (!line.startsWith('  ')) { inRefs = false; continue }
+          const idx = line.indexOf(':')
+          if (idx === -1) continue
+          const key = line.slice(0, idx).trim()
+          const val = line.slice(idx + 1).trim()
+          if (key && val && (platform.envKeys || []).includes(key)) return val
+        }
+      }
+    } catch { /* 忽略 */ }
+    return ''
+  }
+
+  let cache = { balances: [], fetchedAt: 0, error: null }
+  let inflight = null
+
+  const refreshAll = async () => {
+    if (inflight !== null) return inflight
+    inflight = (async () => {
+      const presetList = PLATFORM_PRESETS.filter(p => runtimeConfig.presets.includes(p.id))
+      const relayList = runtimeConfig.customRelays
+      const modelList = runtimeConfig.customModels
+      const tasks = [
+        ...presetList.map(async (p) => queryPreset(p, await resolvePresetKey(p), runtimeConfig)),
+        ...relayList.map(async (r) => queryCustomRelay(r, runtimeConfig)),
+        ...modelList.map(async (m) => queryCustomModel(m, runtimeConfig)),
+      ]
+      const results = await Promise.allSettled(tasks)
+      // v0.5.7: last-known-good 兜底 — 平台瞬时网络故障(超时/DNS抖动)不冲掉上次成功数据,
+      // 避免看板红闪「异常」; 标注 stale 提示用户这是暂存值
+      const prevBalances = Array.isArray(cache.balances) ? cache.balances : []
+      const prevOf = new Map(prevBalances.map((b) => [b.platform, b]))
+      const balances = results.map((r) => {
+        const cur = r.status === 'fulfilled' ? r.value : { platform: 'unknown', name: '未知', icon: 'relay', color: '#64748B', category: '中转站', status: 'error', error: '查询失败', noBalance: true }
+        if (cur && cur.status === 'error' && !String(cur.error || '').includes('认证')) {
+          const old = prevOf.get(cur.platform)
+          if (old && old.status === 'ok') {
+            return { ...old, fetchedAt: old.fetchedAt, staleNote: '暂用上次数据(本次查询失败)', error: undefined }
+          }
+        }
+        return cur
+      })
+      cache = {
+        balances, fetchedAt: Date.now(), error: null,
+        config: {
+          refreshIntervalMs: runtimeConfig.refreshIntervalMs,
+          clientPollIntervalMs: runtimeConfig.clientPollIntervalMs,
+          safeThreshold: runtimeConfig.safeThreshold,
+          warnThreshold: runtimeConfig.warnThreshold,
+          currency: runtimeConfig.currency,
+          isPeak: isPeakTime(),
+          isWeekend: isWeekend(),
+        },
+      }
+      // A3: 告警检测
+      checkAlerts(balances, runtimeConfig, ctx)
+    })().finally(() => { inflight = null })
+    return inflight
+  }
+
+  let loopTimer = null
+  const resetLoop = () => {
+    if (loopTimer !== null) { clearTimeout(loopTimer); loopTimer = null }
+    const run = () => { void refreshAll().then(() => { loopTimer = setTimeout(run, runtimeConfig.refreshIntervalMs) }) }
+    loopTimer = setTimeout(run, 0)
+  }
+
+  ctx.effect(() => {
+    resetLoop()
+    return () => { if (loopTimer !== null) clearTimeout(loopTimer) }
+  }, 'dsh-api-dashboard: refresh loop')
+
+  // HTTP 路由
+  ctx.inject(['webServer'], (webCtx) => {
+    const sendJson = (res, code, data) => {
+      const body = JSON.stringify(data)
+      res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'Content-Length': Buffer.byteLength(body) })
+      res.end(body)
+    }
+
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/balances',
+      async handler(req, res) {
+        if (!['GET', 'HEAD', 'POST'].includes(req.method)) { res.writeHead(405, { Allow: 'GET, HEAD, POST' }); res.end(); return }
+        const force = req.method === 'POST' || new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('force') === '1'
+        // 自动刷新: 缓存为空 或 缓存超过 refreshIntervalMs 时自动拉取最新 (解决进入页面要手动刷新)
+        const stale = Date.now() - cache.fetchedAt > (runtimeConfig.refreshIntervalMs || 300000)
+        if ((force || stale || cache.balances.length === 0) && (Date.now() - cache.fetchedAt > 2000 || cache.balances.length === 0)) await refreshAll()
+        // v0.5.0: ETag 协商缓存 — 轮询期间数据没变就 304 空响应, 省 JSON 序列化与流量
+        const etag = '"' + Number(cache.fetchedAt || 0).toString(36) + '"'
+        if (req.method === 'HEAD') { res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', ETag: etag }); res.end(); return }
+        if (!force && req.headers['if-none-match'] === etag && cache.balances.length > 0) {
+          res.writeHead(304, { ETag: etag })
+          res.end()
+          return
+        }
+        const body = JSON.stringify({ ok: true, balances: cache.balances, fetchedAt: cache.fetchedAt, config: cache.config })
+        res.writeHead(200, {
+          'Content-Type': 'application/json; charset=utf-8',
+          'Cache-Control': 'private, no-cache',
+          ETag: etag,
+          'Content-Length': Buffer.byteLength(body),
+        })
+        res.end(body)
+      },
+    }), 'dsh-api-dashboard: balances route')
+
+    // v0.5.5: 价格表 (DeepSeek 峰谷全量 + 平价模型), 供详情页标注
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/prices',
+      async handler(req, res) {
+        if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
+        const cfg = runtimeConfig
+        const cur = (cfg.currency ?? 'CNY').toUpperCase() === 'USD' ? 'USD' : 'CNY'
+        const table = V4_RATES[cur] ?? V4_RATES.CNY
+        const mk = (p) => p ? { cacheHit: p.cacheHit, cacheMiss: p.cacheMiss, output: p.output } : null
+        // v4 峰谷系列
+        const models = []
+        for (const key of ['deepseek-v4-flash', 'deepseek-v4-pro']) {
+          models.push({ model: key, peak: mk(table.peak[key]), offPeak: mk(table.offPeak[key]), peakValley: true })
+        }
+        sendJson(res, 200, { ok: true, currency: cfg.currency ?? 'CNY', peakNow: isPeakTime(), weekend: isWeekend(), models })
+      },
+    }), 'dsh-api-dashboard: prices route')
+
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/platforms',
+      async handler(req, res) {
+        if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
+        const presets = PLATFORM_PRESETS.filter(p => runtimeConfig.presets.includes(p.id)).map(p => ({
+          id: p.id, name: p.label, icon: p.icon, color: p.color, category: p.category, queryType: p.queryType,
+        }))
+        sendJson(res, 200, { ok: true, presets })
+      },
+    }), 'dsh-api-dashboard: platforms route')
+
+    // v0.6.0: 更新检查 (GET) — 对比远端 main 版本, 5 分钟内存缓存, ?force=1 绕过
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/update',
+      async handler(req, res) {
+        if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
+        const force = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('force') === '1'
+        try {
+          sendJson(res, 200, await getUpdateStatus(force))
+        } catch {
+          sendJson(res, 200, { ok: false, error: 'check failed', hasUpdate: false })
+        }
+      },
+    }), 'dsh-api-dashboard: update check route')
+
+    // v0.6.0: 执行自更新 (POST /install) — 下载+校验+备份+原子交换, 失败自动回滚
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/update/install',
+      async handler(req, res) {
+        if (req.method !== 'POST') { res.writeHead(405, { Allow: 'POST' }); res.end(); return }
+        try {
+          const result = await applyUpdate({})
+          updateCache = { checkedAt: Date.now(), result: { ok: true, current: result.installed, remote: result.installed, hasUpdate: false, checkedAt: Date.now() } }
+          sendJson(res, 200, { ok: true, installed: result.installed, targets: result.targets, backup: result.backup, needRestart: true })
+        } catch (err) {
+          const msg = /already up to date/.test(String(err?.message)) ? `already up to date`
+            : /GitHub API|download|remote version/.test(String(err?.message)) ? 'network failed'
+            : 'update failed'
+          sendJson(res, 500, { ok: false, error: msg })
+        }
+      },
+    }), 'dsh-api-dashboard: update install route')
+
+    // v0.7.1: 插件图标 (哦鲸鲸)
+    const ICON_PATH = join(SELF_ROOT, 'assets', 'icon.png')
+    let iconCache = null
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/icon',
+      async handler(req, res) {
+        if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
+        try {
+          if (!iconCache) {
+            const data = readFileSync(ICON_PATH)
+            iconCache = { data, mtime: statSync(ICON_PATH).mtimeMs }
+          }
+          res.writeHead(200, {
+            'Content-Type': 'image/png',
+            'Cache-Control': 'public, max-age=86400',
+            'Content-Length': iconCache.data.length,
+          })
+          res.end(iconCache.data)
+        } catch {
+          res.writeHead(404); res.end()
+        }
+      },
+    }), 'dsh-api-dashboard: icon route')
+
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact', path: '/api-dashboard/config',
+      async handler(req, res) {
+        if (req.method === 'GET') {
+          sendJson(res, 200, {
+            ok: true,
+            customRelays: runtimeConfig.customRelays.map(r => ({ ...r, apiKey: r.apiKey ? '***' : '' })),
+            customModels: runtimeConfig.customModels.map(m => ({ ...m, apiKey: m.apiKey ? '***' : '' })),
+            presets: runtimeConfig.presets,
+            refreshIntervalSec: Math.round(runtimeConfig.refreshIntervalMs / 1000),
+          })
+          return
+        }
+        if (req.method === 'POST') {
+          try {
+            let body = ''
+            for await (const chunk of req) { body += chunk }
+            body = body ? JSON.parse(body) : {}
+            if (Array.isArray(body.customRelays)) {
+              runtimeConfig.customRelays = body.customRelays.map(r => {
+                const prev = runtimeConfig.customRelays.find(x => x.id === r.id)
+                return {
+                  id: r.id || Math.random().toString(36).slice(2), name: r.name || '中转站',
+                  baseUrl: (r.baseUrl || '').replace(/\/+$/, ''), apiKey: r.apiKey && r.apiKey !== '***' ? r.apiKey : (prev?.apiKey || ''), queryType: r.queryType || 'auto',
+                }
+              })
+            }
+            if (Array.isArray(body.customModels)) {
+              runtimeConfig.customModels = body.customModels.map(m => {
+                const prev = runtimeConfig.customModels.find(x => x.id === m.id)
+                return {
+                  id: m.id || Math.random().toString(36).slice(2), name: m.name || '自定义模型',
+                  apiUrl: (m.apiUrl || '').trim(), apiKey: m.apiKey && m.apiKey !== '***' ? m.apiKey : (prev?.apiKey || ''),
+                  queryType: m.queryType || 'auto', totalPath: (m.totalPath || '').trim(), usedPath: (m.usedPath || '').trim(),
+                  currency: (m.currency || '').trim() || 'CNY',
+                }
+              })
+            }
+            // 自定义刷新时间 (5~60 秒, 最高一分钟)
+            if (typeof body.refreshIntervalSec === 'number' && Number.isFinite(body.refreshIntervalSec)) {
+              const sec = Math.min(Math.max(Math.round(body.refreshIntervalSec), 5), 60)
+              runtimeConfig.refreshIntervalMs = sec * 1000
+              runtimeConfig.clientPollIntervalMs = sec * 1000
+            }
+            // 更新安全阈值
+            if (typeof body.safeThreshold === 'number' && body.safeThreshold >= 0) runtimeConfig.safeThreshold = body.safeThreshold
+            if (typeof body.warnThreshold === 'number' && body.warnThreshold >= 0) runtimeConfig.warnThreshold = body.warnThreshold
+            if (typeof body.currency === 'string' && body.currency.trim()) runtimeConfig.currency = body.currency.trim().toUpperCase()
+            // 持久化: 写入状态文件, 重启后恢复 (用户配置优先)
+            savePersistedState({
+              refreshIntervalMs: runtimeConfig.refreshIntervalMs,
+              clientPollIntervalMs: runtimeConfig.clientPollIntervalMs,
+              timeoutMs: runtimeConfig.timeoutMs,
+              customRelays: runtimeConfig.customRelays,
+              customModels: runtimeConfig.customModels,
+              currency: runtimeConfig.currency,
+              safeThreshold: runtimeConfig.safeThreshold,
+              warnThreshold: runtimeConfig.warnThreshold,
+            })
+            resetLoop(); await refreshAll()
+            sendJson(res, 200, {
+              ok: true,
+              customRelays: runtimeConfig.customRelays.map(r => ({ ...r, apiKey: r.apiKey ? '***' : '' })),
+              customModels: runtimeConfig.customModels.map(m => ({ ...m, apiKey: m.apiKey ? '***' : '' })),
+              refreshIntervalSec: Math.round(runtimeConfig.refreshIntervalMs / 1000),
+            })
+          } catch (err) { sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) }) }
+          return
+        }
+        res.writeHead(405, { Allow: 'GET, POST' })
+        res.end()
+      },
+    }), 'dsh-api-dashboard: config route')
+  })
+
+  // 会话消耗投影
+  ctx.inject(['sessionProjections'], (projectionCtx) => {
+    projectionCtx.sessionProjections.register(makeCostProjection(getConfig))
+  })
+}