dsh-account-pool 0.1.0

package/lib/index.js

@@ -0,0 +1,1142 @@
+/**
+ * dsh-account-pool — Host 半边入口。
+ *
+ * 把多个 WorkBuddy 账号接入 DSH 的模型选择器，并在账号之间自动切换。
+ *
+ * 数据流：
+ *
+ *   DSH LLM seam
+ *     → pi-ai adapter（本插件注册的 provider 路由）
+ *     → loopback shim（127.0.0.1:随机端口，本插件自带）
+ *         ├─ 选号器：决定这次用哪个账号（三因子加权 + 冷却 + 熔断 + 会话粘性）
+ *         └─ 失败自动换号重试
+ *     → copilot.tencent.com / www.workbuddy.ai
+ *
+ * 两个区域各一套完整栈（凭据库 / 选号器 / shim）：
+ *   workbuddy        国内版
+ *   workbuddy-global 国际版
+ * 两边账号互不覆盖，可同时在线，不同会话各选一边。
+ *
+ * 不依赖任何外部网关——「网关」角色由本插件的 shim 承担。
+ */
+
+import { createProvider } from '@earendil-works/pi-ai'
+import { randomBytes } from 'node:crypto'
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy'
+import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { dirname, join } from 'node:path'
+import z from '@deepseek-ai/schemastery'
+
+import { openStore, clearStore, startDeviceLogin, pollDeviceLogin, parseAuthFile } from './accounts.js'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { fetchModels, fetchCredits } from './upstream.js'
+import { AccountPicker } from './selector.js'
+import { createShim } from './shim.js'
+import { UsageRecorder } from './usage.js'
+import { runDailyTasks, fetchStreak, fetchBuddy, fetchLottery, travelStatus as fetchTravelStatus } from './tasks.js'
+import { openTraeStore, accountIdOf as accountIdOfTrae } from './trae-accounts.js'
+import { parseTraeStorage } from './trae-storage.js'
+import {
+  chatStream as traeChatStream,
+  prepareChatBody as traePrepareBody,
+  isRetryableWithAnotherAccount as traeRetryable,
+  fetchModels as traeFetchModels,
+  runDailyTasks as traeRunDailyTasks,
+  readStatus as traeReadStatus,
+  fetchCredits as traeFetchCredits,
+} from './trae-upstream.js'
+
+export const name = 'account-pool'
+
+/** 声明硬依赖：没有 llm 服务就没法注册 provider，没有 settings 就没法挂发现器。 */
+export const inject = ['llm', 'settings']
+
+/** 区域 → provider 路由 id。 */
+export const REGION_PROVIDERS = {
+  cn: 'workbuddy',
+  global: 'workbuddy-global',
+  // Trae 是完全不同的上游（字节 TRAE SOLO），照旧当成一个「区域」接入：
+  // 选号、重试、用量、shim 全部复用，只有上游适配器不同。
+  trae: 'trae',
+}
+
+/** 区域 → 在 DSH 模型选择器里显示的名字。 */
+const REGION_DISPLAY_NAMES = {
+  cn: 'WorkBuddy',
+  global: 'WorkBuddy Global',
+  trae: 'Trae',
+}
+
+/** 所有合法的区域标识。 */
+const REGION_IDS = Object.keys(REGION_PROVIDERS)
+
+/**
+ * 把外部传来的 region 归一化成合法值，非法值退回 'cn'。
+ *
+ * 抽出来是因为原来 8 个路由各写一遍 `x === 'global' ? 'global' : 'cn'`，
+ * 加 trae 时漏改一处，Trae 面板就会静默显示成 WorkBuddy 的账号
+ * ——这种「重复代码 + 静默降级」的组合最容易出隐蔽 bug。
+ */
+function normalizeRegion(value) {
+  const text = String(value ?? '')
+  return REGION_IDS.includes(text) ? text : 'cn'
+}
+
+/**
+ * 本插件自己的 settings 命名空间。
+ *
+ * 必须是自己的名字，不能借用官方的 `llm-pi-ai`——那个命名空间归
+ * dsh-llm-pi-ai 所有，而且 dsh-llm 的 registerModelDiscovery 按命名空间
+ * 索引，重名会直接抛 DUPLICATE_DISCOVERY 把官方功能搞坏。
+ *
+ * 这一节同时承担两个职责：
+ *   1. 让设置页的「模型」界面能对这个 provider 做模型发现
+ *      （否则会报 "pi-ai ships no catalog for provider ..."）；
+ *   2. 存住上次拉到的模型目录，供发现器在账号不可用时兜底。
+ */
+const SETTINGS_NS = 'account-pool'
+
+/** 设置命名空间的结构：每个区域一份模型目录快照。 */
+const Config = z.object({
+  // 各区域最近一次成功拉取的模型目录，用于发现器兜底
+  catalog: z.dict(z.array(z.object({
+    id: z.string().required(),
+    name: z.string(),
+    contextWindow: z.number().step(1).min(1),
+    maxTokens: z.number().step(1).min(1),
+    multimodal: z.boolean(),
+  }))).default({}),
+})
+
+/** 流式读取空闲上限。 */
+const STREAM_IDLE_TIMEOUT_MS = 300_000
+
+/** pi-ai 图片预算（对齐 dsh-llm-pi-ai 的默认值）。 */
+const REQUEST_IMAGE_BUDGETS = {
+  maxRequestImageBytes: 20_971_520,
+  requestImagePixelBudget: 4_194_304,
+  requestImageMaxBytes: 1_048_576,
+}
+
+/**
+ * 惰性的 pi-ai 认证面。
+ * 本插件路由只认 shim 的进程内 secret（由 resolveApiKey 提供），
+ * 所以 pi-ai 自己的凭据发现必须一问三不知——否则它会从环境变量里
+ * 找到不相干的 key 拿来用。
+ */
+const INERT_AUTH = {
+  credentials: {
+    async read() { return undefined },
+    async list() { return [] },
+    async modify() { throw new Error('account-pool: 该路由没有 pi-ai 凭据生命周期') },
+    async delete() {},
+  },
+  authContext: {
+    async env() { return undefined },
+    async fileExists() { return false },
+  },
+}
+
+/** 订阅制额度无法按 token 计价，一律报 0（不代表免费）。 */
+const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+
+/** DSH 的思考档位阶梯。 */
+const THINKING_LEVELS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+
+/**
+ * 把上游声明的推理档位翻译成 DSH 的思考档位映射。
+ * 上游没声明的档位必须显式置 null，否则 DSH 会以为可以选择。
+ */
+function thinkingLevelMapOf(info) {
+  const supported = info.reasoning?.supportedEfforts?.filter(e => THINKING_LEVELS.includes(e))
+  if (supported === undefined || supported.length === 0) return undefined
+  const map = {}
+  for (const level of THINKING_LEVELS) {
+    map[level] = supported.includes(level) ? level : null
+  }
+  // 只有上游明确允许「不思考」时才开放 off 档。
+  if (info.reasoning?.canDisableThinking !== true) map.off = null
+  return map
+}
+
+/** 展示名带积分倍率，与 WorkBuddy 自己的选择器一致：`GLM-5.3 · x0.79`。 */
+function displayNameOf(info) {
+  return info.creditMultiplier === undefined
+    ? info.name
+    : `${info.name} · x${info.creditMultiplier.toFixed(2)}`
+}
+
+/** 构造一个 pi-ai 模型描述符，指向本插件的 shim。 */
+function toPiModel(info, baseUrl, providerId) {
+  const thinkingLevelMap = thinkingLevelMapOf(info)
+  return {
+    id: info.id,
+    name: displayNameOf(info),
+    api: 'openai-completions',
+    provider: providerId,
+    baseUrl,
+    // 上游说支持图片才给 image；否则 DSH 会先把图片拦掉。
+    input: info.multimodal === true ? ['text', 'image'] : ['text'],
+    cost: NO_COST,
+    contextWindow: info.contextWindow,
+    maxTokens: info.maxTokens,
+    reasoning: thinkingLevelMap !== undefined,
+    ...(thinkingLevelMap === undefined ? {} : { thinkingLevelMap }),
+    compat: { supportsReasoningEffort: thinkingLevelMap !== undefined },
+  }
+}
+
+/**
+ * 为一个区域装配完整的一套：store → picker → shim → adapter。
+ *
+ * 顺序很关键：必须先起 shim 拿到端口，才能构造带 baseUrl 的模型描述符。
+ */
+async function createRegionStack({ region, dshHome, config, logger, ctx }) {
+  const providerId = REGION_PROVIDERS[region]
+  // Trae 是独立上游：凭据格式、刷新端点、对话协议都不同，
+  // 所以用自己的一份 store 与适配器；其余（选号/重试/用量/shim）完全复用。
+  const isTrae = region === 'trae'
+  const store = isTrae ? openTraeStore(dshHome) : openStore(dshHome, region)
+  /** 上游适配器：shim 通过它屏蔽两家协议的差异。 */
+  const upstreamAdapter = isTrae
+    ? { chatStream: traeChatStream, prepareBody: traePrepareBody, retryable: traeRetryable }
+    : undefined
+  /** 拉模型目录：两家端点不同。 */
+  const fetchCatalog = isTrae ? traeFetchModels : fetchModels
+  /** 查积分：两家端点/认证方式都不同。漏分流会让 Trae 的 token
+   *  打到 WorkBuddy 的接口上——401，积分列永远显示「—」。 */
+  const fetchRegionCredits = isTrae ? traeFetchCredits : fetchCredits
+  /** 每日任务：Trae 只有签到与积分。 */
+  const runTasks = isTrae ? traeRunDailyTasks : runDailyTasks
+  // 用量记录器按区域分文件，与凭据分离。
+  const usage = new UsageRecorder({
+    file: join(dshHome, `.account-pool.usage.${region}.json`),
+    // 插件改名前的用量文件：只读回落，避免历史用量"归零"
+    legacyFiles: [
+      join(dshHome, `.workbuddy-pool.usage.${region}.json`),
+      join(dirname(dshHome), `.workbuddy-pool.usage.${region}.json`),
+    ],
+  })
+  await usage.load()
+  const picker = new AccountPicker({
+    softCooldownMs: (config.softCooldownSeconds ?? 600) * 1000,
+    breakerThreshold: config.breakerThreshold ?? 3,
+  })
+
+  /** 本区域最近一次拉到的模型目录。 */
+  let catalog = []
+
+  const shim = await createShim({
+    logger,
+    picker,
+    usage,
+    adapter: upstreamAdapter,
+    // 每次请求现读账号 + 现取可用 token，保证用最新凭证。
+    listAccounts: async () => {
+      const list = await store.list()
+      const out = []
+      for (const account of list) {
+        try {
+          out.push({ id: account.id, credential: await store.usable(account.id) })
+        } catch (error) {
+          logger.warn(`账号 ${account.id} 取凭据失败：${error?.message ?? error}`)
+        }
+      }
+      return out
+    },
+  })
+
+  const buildModels = () => catalog.map(info => toPiModel(info, `${shim.baseUrl()}/v1`, providerId))
+
+  const base = createProvider({
+    id: providerId,
+    name: REGION_DISPLAY_NAMES[region],
+    auth: {
+      apiKey: {
+        name: 'WorkBuddy loopback shim secret',
+        async resolve({ credential }) {
+          const key = credential?.key
+          return key === undefined || key.length === 0
+            ? undefined
+            : { auth: { apiKey: key }, source: 'WorkBuddy' }
+        },
+      },
+    },
+    models: buildModels(),
+    api: openAICompletionsApi(),
+  })
+
+  // getModels 走实时读取：目录刷新后不必重建 provider。
+  const provider = { ...base, getModels: () => buildModels() }
+
+  const profile = {
+    provider: providerId,
+    displayName: REGION_DISPLAY_NAMES[region],
+    streamIdleTimeoutMs: STREAM_IDLE_TIMEOUT_MS,
+    retryPolicy: resolveRetryPolicy(undefined, 'account-pool retryPolicy'),
+    configuredMaxTokens: new Map(),
+    modelErrors: new Map(),
+    ...REQUEST_IMAGE_BUDGETS,
+    piProvider: provider,
+  }
+
+  let profiles = new Map([[providerId, profile]])
+  const adapter = new PiAiAdapter({
+    profiles: () => profiles,
+    auth: INERT_AUTH,
+    // pi-ai 把这个值当 apiKey 发成 Bearer，shim 校验它；
+    // 真实 WorkBuddy token 由 shim 自己从 store 取，不经过 pi-ai。
+    resolveApiKey: async () => shim.token(),
+    ...(ctx.get('attachments') === undefined ? {} : { resolveAttachments: () => ctx.get('attachments') }),
+  })
+
+  /**
+   * 积分缓存：积分变化很慢（签到/消耗才动），而设置页会频繁刷新，
+   * 所以缓存 60 秒，避免每次刷新都打上游计费接口。
+   */
+  let creditsCache = { at: 0, value: null }
+
+  /** 查各账号积分（带缓存）；单个账号失败不影响其他账号。 */
+  const loadCredits = async (force = false) => {
+    const now = Date.now()
+    if (!force && creditsCache.value !== null && now - creditsCache.at < 60_000) {
+      return creditsCache.value
+    }
+    const out = {}
+    for (const account of await store.list()) {
+      try {
+        const credential = await store.usable(account.id)
+        out[account.id] = await fetchRegionCredits(credential)
+        // 顺手把总积分喂给选号器，让加权用上真实余额。
+        picker.setCredits(account.id, out[account.id].total)
+      } catch (error) {
+        logger.warn(`账号 ${account.id} 查询积分失败：${error?.message ?? error}`)
+      }
+    }
+    creditsCache = { at: now, value: out }
+    return out
+  }
+
+  /** 拉一次模型目录；没有账号就清空。 */
+  const refreshCatalog = async () => {
+    const list = await store.list()
+    if (list.length === 0) {
+      catalog = []
+      return []
+    }
+    // 用第一个可用账号拉目录——目录是账号级而非全局的。
+    const credential = await store.usable(list[0].id)
+    catalog = await fetchCatalog(credential)
+    return catalog
+  }
+
+  return {
+    region,
+    providerId,
+    isTrae,
+    runTasks,
+    // 只读状态：Trae 用 readStatus，WorkBuddy 用现有的那组查询
+    readStatus: isTrae ? traeReadStatus : undefined,
+    store,
+    picker,
+    shim,
+    adapter,
+    usage,
+    refreshCatalog,
+    loadCredits,
+    getCatalog: () => catalog,
+  }
+}
+
+/**
+ * 插件入口。
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object} config cordis.patch.yml 提供的配置
+ */
+export function apply(ctx, config = {}) {
+  const regions = Array.isArray(config.regions) && config.regions.length > 0
+    ? config.regions.filter(r => r === 'cn' || r === 'global' || r === 'trae')
+    : ['cn']
+  const logger = config.logger ?? {
+    info: (...args) => console.log('[account-pool]', ...args),
+    warn: (...args) => console.warn('[account-pool]', ...args),
+    error: (...args) => console.error('[account-pool]', ...args),
+  }
+  // 用官方的 resolveDshHome：它认识 DSH_HOME、HOME 与平台默认值。
+  // 之前用 process.env.DSH_HOME ?? process.cwd() 是错的——宿主进程里
+  // DSH_HOME 常常没设，cwd 又不是 .dsh，导致凭证落到别处、读不回来。
+  const dshHome = resolveDshHome()
+
+  /** @type {Map<string, object>} providerId → stack */
+  const stacks = new Map()
+  let stopped = false
+
+  // ---- shim 与 adapter 装配 ----
+  // 先起 shim（拿端口），再构造 adapter，最后注册路由。
+  const assembly = Promise.all(regions.map(async region => {
+    const stack = await createRegionStack({ region, dshHome, config, logger, ctx })
+    if (stopped) {
+      await stack.shim.close()
+      return undefined
+    }
+    stacks.set(stack.providerId, stack)
+    // 起完再异步拉目录，不拖慢插件加载。
+    void stack.refreshCatalog()
+      .then(models => logger.info(`区域 ${region} 就绪，${models.length} 个模型`))
+      .catch(error => logger.warn(`区域 ${region} 拉目录失败：${error?.message ?? error}`))
+    return stack
+  }))
+
+  /** 供 web 路由与工具使用的「等到装配完成」。 */
+  const ready = assembly.then(list => list.filter(s => s !== undefined))
+
+  // ---- 注册 settings 命名空间 + 模型发现器 ----
+  //
+  // 设置页的「模型」界面会遍历可配置 provider 并调用模型发现。我们的
+  // provider 是运行时注册的、没有配置式 baseURL，若不注册发现器，
+  // 界面就会报 "pi-ai ships no catalog for provider ..."。
+  //
+  // 发现顺序：先用在线账号实时拉（拿得到最新清单），失败则回落到
+  // 上次保存的目录快照，都没有就返回空数组——让界面显示「暂无模型」
+  // 而不是抛错。
+  ctx.effect(() => {
+    let scope
+    try {
+      scope = ctx.settings.register(SETTINGS_NS, Config, { applies: 'live' })
+    } catch (error) {
+      logger.error(`注册 settings 命名空间 ${SETTINGS_NS} 失败：${error?.message ?? error}`)
+      return
+    }
+
+    const releaseDiscovery = ctx.llm.registerModelDiscovery(SETTINGS_NS, async (request) => {
+      const list = await ready
+      const stack = list.find(s => s.providerId === request.provider)
+      if (stack === undefined) return []
+
+      // 先试实时拉取：能拿到就顺手回写快照，供下次离线兜底。
+      try {
+        const models = await stack.refreshCatalog()
+        if (models.length > 0) {
+          persistCatalog(scope, stack.region, models)
+          return models.map(toDiscoveredModel)
+        }
+      } catch (error) {
+        logger.warn(`发现 ${request.provider} 模型失败，改用缓存：${error?.message ?? error}`)
+      }
+
+      // 实时拉不到（没账号 / 网络不通）→ 用上次的快照。
+      const saved = scope.get()?.catalog?.[stack.region]
+      return Array.isArray(saved) ? saved.map(toDiscoveredModel) : []
+    })
+
+    // 命名空间与发现器都跟着本 effect 的生命周期自动注销，无需手动 dispose。
+    return () => {
+      releaseDiscovery()
+    }
+  })
+
+  // ---- 注册 provider 路由 ----
+  ctx.effect(() => {
+    let releases = []
+    void ready.then(list => {
+      if (stopped) return
+      // 单个区域注册失败不能拖垮另一个区域。
+      for (const stack of list) {
+        try {
+          releases.push(ctx.llm.registerAdapter([stack.providerId], stack.adapter))
+        } catch (error) {
+          logger.error(`注册 provider ${stack.providerId} 失败：${error?.message ?? error}`)
+        }
+      }
+      try {
+        ctx.llm.registerConfigurableProviders(list.map(stack => ({
+          provider: stack.providerId,
+          displayName: REGION_DISPLAY_NAMES[stack.region],
+          settingsNs: SETTINGS_NS,
+          settingsPath: [],
+          declared: false,
+        })))
+      } catch (error) {
+        logger.warn(`登记可配置 provider 失败：${error?.message ?? error}`)
+      }
+    })
+    return () => {
+      for (const release of releases) release()
+      releases = []
+    }
+  })
+
+  // ---- 卸载清理：关 shim、落盘用量、注销 adapter ----
+  ctx.effect(() => () => {
+    stopped = true
+    for (const stack of stacks.values()) {
+      void stack.shim.close()
+      // 用量数据要落盘，否则重启丢统计
+      void stack.usage.close()
+    }
+    stacks.clear()
+  })
+
+  // 粘性绑定定期清理，防止 Map 无限增长。
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      for (const stack of stacks.values()) stack.picker.sweepSticky()
+    }, 5 * 60_000)
+    // unref：定时器不该拖住宿主进程退出（保活定时器同样处理）。
+    timer.unref?.()
+    return () => clearInterval(timer)
+  })
+
+  // ---- 凭证保活：避免闲置太久导致到期 ----
+  //
+  // 只在「有请求」时刷新的话，闲置超过 access token 有效期就只剩 refresh
+  // token 能救；再久一点连 refresh token 也过期，账号彻底作废。
+  // 这里每 6 小时检查一次，把剩余不足 7 天的账号提前续上。
+  ctx.effect(() => {
+    const KEEPALIVE_INTERVAL_MS = 6 * 3600_000
+    const runKeepAlive = async () => {
+      for (const [providerId, stack] of stacks) {
+        try {
+          const result = await stack.store.keepAlive(7)
+          if (result.refreshed > 0 || result.failed > 0) {
+            logger.info(`保活 ${providerId}：续期 ${result.refreshed}，失败 ${result.failed}，跳过 ${result.skipped}`)
+          }
+        } catch (error) {
+          logger.warn(`保活 ${providerId} 异常：${error?.message ?? error}`)
+        }
+      }
+    }
+    // 启动后先跑一次（延迟 30 秒，避免和插件装配、拉目录抢资源）
+    const initial = setTimeout(() => { void runKeepAlive() }, 30_000)
+    initial.unref?.()
+    const timer = setInterval(() => { void runKeepAlive() }, KEEPALIVE_INTERVAL_MS)
+    timer.unref?.()
+    return () => {
+      clearTimeout(initial)
+      clearInterval(timer)
+    }
+  })
+
+  // ---- 同源 web 路由：设置页靠它读状态、拉二维码、加账号 ----
+  ctx.inject(['webServer'], (webCtx) => {
+    const logger2 = logger
+    /**
+     * 判断这次请求是不是「从这台机器本身上」发起的。
+     *
+     * 用途：Trae 回调写死 127.0.0.1（浏览器所在机器）。只有当用户
+     * 就在这台机器上用浏览器时，自动回调才有意义。
+     *
+     * 判据是请求的 Host 是否为回环地址——用户用 `127.0.0.1:3081`
+     * 打开页面时 Host 就是回环；用 NAS 的 IP 打开时是内网 IP。
+     *
+     * 注意：DSH 前面可能挂透明代理（把 Host 改写成 127.0.0.1），
+     * 那种情况下这个判断会失效并倾向于「自动可用」。那时如果实际
+     * 收不到回调，用户仍可点对话框里的「改用手动粘贴」兜底。
+     */
+    const effectiveHost = (req) => {
+      // 优先看 x-forwarded-host：DSH 前面可能挂透明代理（本部署就是），
+      // 它会把 host 改写成 127.0.0.1:<port>，只看 host 会一律误判成「本机」。
+      // 原始 Host 被代理保存在 x-forwarded-host 里。
+      const forwarded = req.headers['x-forwarded-host']
+      return String(
+        (Array.isArray(forwarded) ? forwarded[0] : forwarded)
+        ?? req.headers.host
+        ?? '',
+      )
+    }
+
+    const isSameMachineRequest = (req) => {
+      const host = effectiveHost(req)
+      const hostname = host.startsWith('[')
+        ? host.slice(0, host.indexOf(']') + 1)
+        : host.split(':')[0]
+      return hostname === 'localhost' || hostname === '127.0.0.1'
+        || hostname === '[::1]' || hostname === '::1'
+    }
+
+    /**
+     * 请求来源校验：**只放行同源请求**。
+     *
+     * 目的：防止别的网站（CSRF）偷偷调用这些接口去动你的账号。
+     *
+     * 早期实现只认 `127.0.0.1`，这在「DSH 装在服务器、用局域网地址访问」
+     * 的部署下会把用户自己的所有请求都拒掉（用 `192.0.2.10:3080` 这类
+     * 非回环地址打开时，接口会全部 403）。
+     *
+     * 正确判据是「Origin 与本次请求的 Host 是否一致」——
+     * 用户自己打开的那个页面发起的请求天然同源；而 evil.com 发的
+     * 跨源请求 Host 对不上，会被拒。
+     *
+     * 没有 Origin 头时不拒：那是非浏览器客户端（curl / 本地工具），
+     * 不存在 CSRF 场景。
+     */
+    const loopbackOrigin = (req) => {
+      const origin = req.headers.origin
+      if (origin === undefined || origin === '') return true
+
+      let from
+      try {
+        from = new URL(origin)
+      } catch {
+        return false
+      }
+      // 非 http(s) 来源一律拒（file:、null 等）
+      if (from.protocol !== 'http:' && from.protocol !== 'https:') return false
+
+      // 回环地址始终放行：本机工具、SSH 隧道等场景
+      const loopback = ['localhost', '127.0.0.1', '[::1]', '::1']
+      if (loopback.includes(from.hostname)) return true
+
+      // 同源判定：Origin 的 host:port 要和请求的 Host 一致
+      const host = String(req.headers.host ?? '')
+      if (host === '') return false
+      return from.host === host
+    }
+    /** 错误信息脱敏后再给浏览器，避免把 token 带出去。 */
+    const safeMessage = (error) => String(error?.message ?? error)
+      .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, '[redacted token]')
+      .slice(0, 500)
+
+    const json = (res, status, body) => {
+      const payload = JSON.stringify(body)
+      res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) })
+      res.end(payload)
+    }
+
+    const readBody = async (req) => {
+      const chunks = []
+      for await (const chunk of req) chunks.push(chunk)
+      if (chunks.length === 0) return {}
+      try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      } catch {
+        return {}
+      }
+    }
+
+    /** /account-pool/state —— 一次拿全：账号列表 + 各账号健康状态 + 目录大小。 */
+    const disposeState = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/state',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const list = await ready
+          const out = {}
+          for (const stack of list) {
+            const snapshot = stack.picker.snapshot()
+            out[stack.region] = {
+              provider: stack.providerId,
+              displayName: REGION_DISPLAY_NAMES[stack.region],
+              models: stack.getCatalog().length,
+              accounts: (await (async () => {
+                const listed = await stack.store.list()
+                const credits = await stack.loadCredits()
+                return listed.map(account => ({
+                  id: account.id,
+                  nickname: account.nickname,
+                  uid: account.uid,
+                  domain: account.domain,
+                  expiresAtMs: account.expiresAtMs,
+                  ...snapshot[account.id],
+                  cooling: snapshot[account.id]?.cooling ?? false,
+                  // 积分：剩余 + 总量 + 套餐明细（界面展示用）。
+                  // size 供悬停提示展示「总量 / 已用 / 剩余」构成。
+                  credits: credits[account.id]?.total,
+                  creditsSize: credits[account.id]?.size,
+                  creditPackages: credits[account.id]?.packages?.slice(0, 5) ?? [],
+                }))
+              })()),
+            }
+          }
+          json(res, 200, { ok: true, regions: out })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/login/start —— 申请授权链接。 */
+    const disposeLoginStart = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/login/start',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = req.method === 'POST' ? await readBody(req) : {}
+          const region = normalizeRegion(body.region)
+          const { state, authUrl } = await startDeviceLogin(region)
+          json(res, 200, { ok: true, state, authUrl, region })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/login/poll —— 轮询登录是否完成，完成则落盘。 */
+    const disposeLoginPoll = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/login/poll',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+          const region = normalizeRegion(url.searchParams.get('region'))
+          const state = url.searchParams.get('state') ?? ''
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+
+          const result = await pollDeviceLogin(region, state)
+          if (result.pending) { json(res, 200, { ok: true, pending: true }); return }
+
+          await stack.store.save(result.credential)
+          // 新账号进来后立刻刷目录，让模型马上可选。
+          await stack.refreshCatalog().catch(error => logger2.warn(`刷新目录失败：${error?.message ?? error}`))
+          json(res, 200, {
+            ok: true,
+            pending: false,
+            account: { id: result.credential.id, nickname: result.credential.nickname ?? result.credential.uid },
+          })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /**
+     * /account-pool/trae/import —— 导入 Trae 桌面端凭证。
+     *
+     * 为什么要导入文件而不是网页登录：Trae 授权页把 token fetch 投递到
+     * `127.0.0.1:18080`。DSH 在 NAS、浏览器在另一台电脑时，那个 127.0.0.1
+     * 指用户自己的电脑——请求被拒，页面报「网络错误」；又因为是 fetch
+     * 而非导航，地址栏不会出现带 token 的链接，连复制都拿不到。
+     *
+     * 所以改为：用户在 Windows/macOS 上登录 Trae，把 storage.json 内容
+     * 粘过来（或给出服务器上的文件路径）。解密不依赖本机硬件。
+     */
+    const disposeTraeImport = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/trae/import',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+
+          // 两条来源：直接粘贴内容，或给服务器上的路径
+          let content = String(body.content ?? '').trim()
+          const filePath = String(body.path ?? '').trim()
+          if (content === '' && filePath !== '') {
+            try {
+              content = (await readFile(filePath, 'utf8')).trim()
+            } catch (error) {
+              json(res, 400, { ok: false, error: `读取文件失败：${safeMessage(error)}` }); return
+            }
+          }
+          if (content === '') { json(res, 400, { ok: false, error: '请粘贴 storage.json 内容，或给出文件路径' }); return }
+
+          let parsed
+          try {
+            parsed = parseTraeStorage(content)
+          } catch (error) {
+            json(res, 400, { ok: false, error: safeMessage(error) }); return
+          }
+
+          const list = await ready
+          const stack = list.find(s => s.region === 'trae')
+          if (stack === undefined) { json(res, 503, { ok: false, error: 'Trae 区域未启用（检查 config.regions）' }); return }
+
+          // 归一化成插件内部的凭证结构
+          const credential = {
+            id: accountIdOfTrae(parsed.userId !== '' ? parsed.userId : parsed.accountName),
+            uid: parsed.userId,
+            nickname: parsed.accountName !== '' ? parsed.accountName : parsed.userId,
+            accessToken: parsed.accessToken,
+            refreshToken: parsed.refreshToken,
+            expiresAtMs: parsed.expiresAtMs,
+            region: parsed.region,
+            machineId: parsed.machineId,
+            deviceId: parsed.deviceId,
+          }
+          await stack.store.save(credential)
+          await stack.refreshCatalog().catch(error => logger.warn(`Trae 刷新目录失败：${error?.message ?? error}`))
+
+          json(res, 200, {
+            ok: true,
+            account: { id: credential.id, nickname: credential.nickname },
+            // 顺带回报一些信息，便于用户确认导入的是哪个账号
+            region: parsed.region,
+            hasRefreshToken: parsed.refreshToken !== '',
+            expiresAtMs: parsed.expiresAtMs,
+          })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+        /** /account-pool/login/import —— 从 auth 文件导入账号（粘贴内容或给路径）。 */
+    const disposeImport = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/login/import',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+
+          // 两种来源：content（粘贴的 JSON）或 path（服务器上的文件/目录）
+          let texts = []
+          if (typeof body.content === 'string' && body.content.trim() !== '') {
+            texts.push({ source: '粘贴内容', text: body.content })
+          } else if (typeof body.path === 'string' && body.path.trim() !== '') {
+            const path = body.path.trim()
+            // 注意变量名：这里叫 info，不能用 stat——那会遮蔽从 fs 导入的
+            // stat 函数，导致 await stat(path) 调用到未初始化的局部变量。
+            let info
+            try {
+              info = await stat(path)
+            } catch {
+              json(res, 400, { ok: false, error: `路径不存在或无法访问：${path}` })
+              return
+            }
+            if (info.isDirectory()) {
+              // 目录：把所有 *.json 都当候选，逐个试
+              const entries = await readdir(path)
+              for (const name of entries.filter(n => n.endsWith('.json')).sort()) {
+                try {
+                  texts.push({ source: name, text: await readFile(join(path, name), 'utf8') })
+                } catch {
+                  // 单个文件读不了就跳过
+                }
+              }
+              if (texts.length === 0) {
+                json(res, 400, { ok: false, error: `目录里没有 .json 文件：${path}` })
+                return
+              }
+            } else {
+              texts.push({ source: path.split('/').pop() || path, text: await readFile(path, 'utf8') })
+            }
+          } else {
+            json(res, 400, { ok: false, error: '请提供 content（粘贴 JSON）或 path（文件/目录路径）' })
+            return
+          }
+
+          // 逐个解析并落盘；失败的收集起来如实回报，不假装成功。
+          const imported = []
+          const failed = []
+          for (const { source, text } of texts) {
+            try {
+              const credential = parseAuthFile(text, source)
+              // 区域不匹配的跳过：国际版凭证进国内版池子只会一直失败。
+              if (credential.region !== region) {
+                failed.push({ source, error: `属于 ${credential.region} 区域，与当前 ${region} 不符` })
+                continue
+              }
+              await stack.store.save(credential)
+              imported.push({
+                id: credential.id,
+                nickname: credential.nickname ?? credential.uid ?? credential.id.slice(0, 8),
+              })
+            } catch (error) {
+              failed.push({ source, error: error?.message ?? String(error) })
+            }
+          }
+
+          // 有新账号就刷新目录与积分
+          if (imported.length > 0) {
+            await stack.refreshCatalog().catch(error => logger.warn(`导入后刷新目录失败：${error?.message ?? error}`))
+          }
+
+          json(res, 200, { ok: true, imported, failed })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/remove —— 移除账号。 */
+    const disposeRemove = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/remove',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+          const removed = await stack.store.remove(String(body.accountId ?? ''))
+          await stack.refreshCatalog().catch(() => {})
+          json(res, 200, { ok: true, removed })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/revive —— 手动解冻账号。 */
+    const disposeRevive = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/revive',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+          stack.picker.revive(String(body.accountId ?? ''))
+          json(res, 200, { ok: true })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/tasks/daily —— 对指定区域的全部账号执行每日任务。 */
+    const disposeTasksDaily = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/tasks/daily',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+
+          const accounts = await stack.store.list()
+          if (accounts.length === 0) { json(res, 200, { ok: true, results: [] }); return }
+
+          // 账号间串行：上游对短时间内的密集请求有风控，串行更稳。
+          const results = []
+          for (const account of accounts) {
+            try {
+              const credential = await stack.store.usable(account.id)
+              // 任务因上游而异：Trae 只有签到+积分，WorkBuddy 还有旅行/兑换/抽奖
+              results.push(await stack.runTasks(credential))
+            } catch (error) {
+              results.push({
+                accountId: account.id,
+                nickname: account.nickname,
+                error: safeMessage(error),
+              })
+            }
+          }
+
+          // 任务跑完刷新积分与目录
+          await stack.loadCredits(true).catch(() => {})
+          json(res, 200, { ok: true, results })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/tasks/status —— 只读：各账号的连登/猫/旅行状态。 */
+    const disposeTasksStatus = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/tasks/status',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+          // 三个区域都要认：之前只认 global/cn，传 trae 会被静默当成 cn，
+          // 导致 Trae 面板显示 WorkBuddy 的账号。
+          const region = normalizeRegion(url.searchParams.get('region'))
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+
+          const out = []
+          for (const account of await stack.store.list()) {
+            try {
+              const credential = await stack.store.usable(account.id)
+
+              // Trae 是另一套任务体系，且**有只读的签到状态接口**，
+              // 所以它连签到都不用靠「上次执行结果」猜。
+              if (stack.readStatus !== undefined) {
+                const status = await stack.readStatus(credential)
+                out.push({
+                  accountId: account.id,
+                  nickname: account.nickname ?? credential.uid,
+                  checkin: status.checkin,
+                  credits: status.credits,
+                  creditsSize: status.creditsSize,
+                  ...(status.checkinError === undefined ? {} : { checkinError: status.checkinError }),
+                  ...(status.creditsError === undefined ? {} : { creditsError: status.creditsError }),
+                })
+                continue
+              }
+
+              // WorkBuddy：全部是只读查询，不签到、不派出、不兑换。
+              // 签到没有只读状态接口，所以这里不查它——由前端显示上次执行结果。
+              const [streak, buddy, travelNow, lottery] = await Promise.all([
+                fetchStreak(credential),
+                fetchBuddy(credential),
+                fetchTravelStatus(credential),
+                fetchLottery(credential),
+              ])
+              out.push({
+                accountId: account.id,
+                nickname: account.nickname ?? credential.uid,
+                streak,
+                buddy,
+                travel: travelNow,
+                lottery,
+                ...(credential.expiresAtMs === undefined ? {} : { expiresAtMs: credential.expiresAtMs }),
+              })
+            } catch (error) {
+              out.push({ accountId: account.id, nickname: account.nickname, error: safeMessage(error) })
+            }
+          }
+          json(res, 200, { ok: true, accounts: out })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/usage —— 用量统计（小时/日桶聚合视图）。 */
+    const disposeUsage = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/usage',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+          const hours = Number(url.searchParams.get('hours')) || 72
+          const list = await ready
+          const out = {}
+          for (const stack of list) {
+            out[stack.region] = stack.usage.snapshot(hours)
+          }
+          json(res, 200, { ok: true, regions: out })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/credits —— 强制刷新积分（绕过缓存）。 */
+    const disposeCredits = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/credits',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const list = await ready
+          for (const stack of list) await stack.loadCredits(true)
+          json(res, 200, { ok: true })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/refresh —— 重新拉模型目录。 */
+    const disposeRefresh = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/refresh',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack === undefined) { json(res, 503, { ok: false, error: '该区域尚未初始化' }); return }
+          const models = await stack.refreshCatalog()
+          json(res, 200, { ok: true, models: models.length })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    /** /account-pool/logout —— 清空某区域全部账号。 */
+    const disposeLogout = webCtx.webServer.register({
+      kind: 'exact',
+      path: '/account-pool/logout',
+      handler: async (req, res) => {
+        if (!loopbackOrigin(req)) { json(res, 403, { ok: false, error: '仅允许本机访问' }); return }
+        try {
+          const body = await readBody(req)
+          const region = normalizeRegion(body.region)
+          await clearStore(dshHome, region)
+          const list = await ready
+          const stack = list.find(s => s.region === region)
+          if (stack !== undefined) await stack.refreshCatalog().catch(() => {})
+          json(res, 200, { ok: true })
+        } catch (error) {
+          json(res, 500, { ok: false, error: safeMessage(error) })
+        }
+      },
+    })
+
+    webCtx.effect(() => () => {
+      disposeState()
+      disposeLoginStart()
+      disposeLoginPoll()
+      disposeImport()
+      disposeTraeImport()
+      disposeRemove()
+      disposeRevive()
+      disposeTasksDaily()
+      disposeTasksStatus()
+      disposeUsage()
+      disposeCredits()
+      disposeRefresh()
+      disposeLogout()
+    })
+  })
+}
+
+/**
+ * 内部模型描述 → DSH 模型发现接口要的形状。
+ * 只带发现接口认识的字段。
+ */
+function toDiscoveredModel(info) {
+  return {
+    id: info.id,
+    name: displayNameOf(info),
+    contextWindow: info.contextWindow,
+    maxTokens: info.maxTokens,
+    inputModalities: info.multimodal === true ? ['text', 'image'] : ['text'],
+  }
+}
+
+/**
+ * 把刚拉到的目录写进 settings 快照，供下次离线时兜底。
+ * 写失败不影响本次返回——快照只是优化，不是必需品。
+ */
+function persistCatalog(scope, region, models) {
+  try {
+    const current = scope.get()?.catalog ?? {}
+    const next = {
+      ...current,
+      [region]: models.map(m => ({
+        id: m.id,
+        name: m.name,
+        contextWindow: m.contextWindow,
+        maxTokens: m.maxTokens,
+        multimodal: m.multimodal === true,
+      })),
+    }
+    // update 可能返回 Promise，也可能同步；两种都容忍。
+    const result = scope.update({ catalog: next })
+    if (result && typeof result.catch === 'function') result.catch(() => {})
+  } catch {
+    // 忽略：快照写入失败不该影响模型发现本身
+  }
+}