@kukonce/dsh-loomy 0.0.0-stage → 0.3.1

package/src/account/desktop-session.js

@@ -0,0 +1,127 @@
+/**
+ * Adopt the login the Loomy desktop app already has.
+ *
+ * The desktop client keeps its session in an `electron-store` file called
+ * `auth-session.json`, next to its other per-user state. On Windows that state does
+ * not live in `%APPDATA%`: Loomy relocates it to
+ * `C:\Users\Public\Loomy\<sha256(username)[:12]>\userData\`, so the account
+ * directory has to be derived from the current user rather than guessed.
+ *
+ * That directory sits under `C:\Users\Public`, which is shared by every local account
+ * on the machine. Only this user's hashed directory is ever read: see
+ * `candidateDirectories` for why enumeration would be wrong. An explicit directory is
+ * honoured when the caller names one, because that is the user's own decision.
+ *
+ * The file is plain JSON (`{ session, userid, phone, updatedAt }`) — it is not
+ * encrypted, which is why this import is a convenience and not a security boundary.
+ *
+ * Nothing here writes to the desktop app's files: the import is read-only, and the
+ * copy this plugin keeps lives in its own directory.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { homedir, userInfo } from 'node:os'
+import { join } from 'node:path'
+
+const SESSION_FILE = 'auth-session.json'
+
+/** The hash Loomy derives its per-user config root from. */
+function userHash() {
+  try {
+    return createHash('sha256').update(userInfo().username).digest('hex').slice(0, 12)
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Candidate `userData` directories belonging to the current user, most specific first.
+ *
+ * Deliberately NOT a scan of `C:\Users\Public\Loomy\*`. That root is machine-wide, so
+ * every local user's session sits beside ours and "the most recently updated one" is
+ * simply "whoever ran Loomy last" — importing it would hand this plugin someone else's
+ * account. The hashed directory for the current username is ours by construction; the
+ * Electron default under `%APPDATA%` is per-user too.
+ *
+ * The un-hashed `C:\Users\Public\Loomy\userData` root is left out for the same reason.
+ * A user whose client really uses that layout can still point at it explicitly
+ * (`/loomy import <directory>`), which is a choice rather than a guess.
+ */
+function candidateDirectories() {
+  const dirs = []
+  if (process.platform === 'win32') {
+    const hash = userHash()
+    if (hash.length > 0) dirs.push(join('C:\\Users\\Public\\Loomy', hash, 'userData'))
+    // An older or differently-configured install may still use the Electron default,
+    // which is per-user and therefore safe to include.
+    const roaming = process.env.APPDATA
+    if (typeof roaming === 'string' && roaming.length > 0) dirs.push(join(roaming, 'Loomy'))
+  } else if (process.platform === 'darwin') {
+    dirs.push(join(homedir(), 'Library', 'Application Support', 'Loomy'))
+  } else {
+    dirs.push(join(homedir(), '.config', 'loomy'))
+  }
+  return dirs
+}
+
+/**
+ * Read one `auth-session.json` and answer a usable record, or `undefined`.
+ *
+ * A session without a `userid` is useless — the points API keys balances by user, and
+ * the model list is scoped per account — so it is treated as absent.
+ */
+function readSessionFile(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    const session = typeof parsed?.session === 'string' ? parsed.session.trim() : ''
+    const userid = typeof parsed?.userid === 'string' ? parsed.userid.trim() : String(parsed?.userid ?? '').trim()
+    if (session.length === 0 || userid.length === 0) return undefined
+    return {
+      session,
+      userid,
+      phone: typeof parsed?.phone === 'string' ? parsed.phone.trim() : '',
+      updatedAt: typeof parsed?.updatedAt === 'number' ? parsed.updatedAt : 0,
+      path
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** Accept a `userData` directory or the session file itself. */
+function asSessionFile(target) {
+  try {
+    if (statSync(target).isDirectory()) return join(target, SESSION_FILE)
+  } catch {
+    // missing path — let the read report it
+  }
+  return target
+}
+
+/**
+ * The most recently updated desktop session for this user, or `undefined`.
+ *
+ * `directory` is only used for an explicit, user-requested import; without it the
+ * search stays inside this user's own directories.
+ */
+export function findDesktopSession(directory) {
+  const explicit = typeof directory === 'string' ? directory.trim() : ''
+  if (explicit.length > 0) return readSessionFile(asSessionFile(explicit))
+
+  const candidates = []
+  for (const dir of candidateDirectories()) {
+    const record = readSessionFile(join(dir, SESSION_FILE))
+    if (record !== undefined) candidates.push(record)
+  }
+  if (candidates.length === 0) return undefined
+  // "Most recent" rather than "first": the hashed and the `%APPDATA%` layouts can both
+  // exist after an app update, and the stale one still parses cleanly.
+  candidates.sort((left, right) => right.updatedAt - left.updatedAt)
+  return candidates[0]
+}
+
+/** Where the desktop client keeps its state, for the panel's "not found" message. */
+export function describeSearchPaths() {
+  return candidateDirectories()
+}

package/src/account/models.js

@@ -0,0 +1,216 @@
+/**
+ * The live model catalog.
+ *
+ * `GET /api/v1/models` answers a **bare list**, not an envelope:
+ *
+ *   { object: "list", reasoning_catalog_version, data: [ { id, name, protocol,
+ *     context_length, max_output_tokens, capabilities: { reasoning, vision,
+ *     function_calling, streaming, system_message, input_modalities }, reasoning_efforts,
+ *     default_reasoning_effort, is_default_model, is_default_small_model } ] }
+ *
+ * Two things about it are easy to get wrong, so they are handled once here:
+ *
+ *   1. It authenticates with the `token` header, like the rest of the points API —
+ *      *not* with `Authorization: Bearer`. The gateway is the opposite.
+ *   2. The list is scoped to the account: a model this account may not use is simply
+ *      absent, so it is the only honest source of "what can I pick".
+ *
+ * The list is cached on disk for a day. A live failure then serves the last good copy
+ * instead of an empty picker, which is the difference between "your account is broken"
+ * and "the catalog endpoint had a bad minute".
+ */
+
+import { API_BASE_URL, CLIENT_VERSION } from '../core/endpoints.js'
+import { requestJson } from '../core/http.js'
+import { readJson, writeJson } from '../core/paths.js'
+
+const CATALOG_FILE = 'catalog.json'
+const CATALOG_TTL_MS = 20 * 60_000
+
+const finiteInt = (value) => (typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined)
+
+/** The levels every Loomy chat model answers, used when the catalog declares none. */
+const STANDARD_EFFORTS = Object.freeze(['none', 'low', 'medium', 'high', 'xhigh'])
+
+/**
+ * Normalize one raw catalog entry.
+ *
+ * `inputModalities` is read from `capabilities.input_modalities` because that is the
+ * field the harness's model picker actually consults; `capabilities.vision` is the
+ * older duplicate and is used only as a fallback.
+ */
+function normalizeEntry(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const id = String(raw.id ?? '').trim()
+  if (id.length === 0) return undefined
+  const capabilities = typeof raw.capabilities === 'object' && raw.capabilities !== null ? raw.capabilities : {}
+  const declared = Array.isArray(capabilities.input_modalities)
+    ? capabilities.input_modalities.filter((value) => typeof value === 'string')
+    : []
+  const input = declared.length > 0
+    ? declared
+    : (capabilities.vision === true ? ['text', 'image'] : ['text'])
+  /**
+   * The reasoning levels this model accepts.
+   *
+   * The harness validates a request's effort against exactly this set and rejects the
+   * whole call with `UNSUPPORTED_REASONING_EFFORT` when the requested level is absent —
+   * so an incomplete set does not degrade gracefully, it breaks the model outright.
+   *
+   * The catalog is not reliable here. `auto` (the router model) ships with no
+   * `reasoning_efforts` at all, yet the gateway accepts every level on it: measured
+   * 2026-11-11, all five of none/low/medium/high/xhigh answered 200 on `auto`, with the
+   * reasoning length changing between them, which is what proves the field is honoured
+   * rather than ignored. Reporting the declared empty set would have made the harness
+   * reject every attempt to use `auto`, so the standard five are used as the fallback.
+   * That is safe in both directions: a level a model truly does not support is ignored
+   * upstream (the gateway treats the field as advisory), while omitting it costs the
+   * user the ability to choose.
+   */
+  const declaredEfforts = Array.isArray(raw.reasoning_efforts)
+    ? raw.reasoning_efforts.filter((value) => typeof value === 'string' && value.length > 0)
+    : []
+  const efforts = declaredEfforts.length > 0 ? declaredEfforts : [...STANDARD_EFFORTS]
+  return {
+    id,
+    name: String(raw.name ?? id),
+    // The catalog's own classification. `image` entries are generation models that share
+    // the chat URL but answer 404 to it (measured 2026-11-11: all three image models
+    // returned "该模型暂未开放" on /chat/completions), so offering them in a chat picker
+    // is offering a model that cannot answer. Kept on the entry so the panel can list
+    // them separately rather than pretending they do not exist.
+    type: String(raw.type ?? 'chat'),
+    protocol: String(raw.protocol ?? 'openai_chat'),
+    contextLength: finiteInt(raw.context_length),
+    maxOutputTokens: finiteInt(raw.max_output_tokens),
+    input,
+    vision: input.includes('image'),
+    toolCalls: capabilities.function_calling === true,
+    reasoning: capabilities.reasoning === true,
+    efforts,
+    defaultEffort: typeof raw.default_reasoning_effort === 'string' ? raw.default_reasoning_effort : undefined,
+    isDefault: raw.is_default_model === true,
+    isDefaultSmall: raw.is_default_small_model === true
+  }
+}
+
+/**
+ * Whether an entry can serve a chat request.
+ *
+ * The gateway lists generation models in the same catalog; they are not chat models and
+ * must not reach the picker. `auto` declares no capabilities at all yet answers
+ * normally, so the test is "declared as image" rather than "declared as chat" — the
+ * negative form excludes only what is proven unusable.
+ */
+export function isChatModel(entry) {
+  return entry?.type !== 'image'
+}
+
+/** One entry for a model the catalog has never listed, so a known id stays callable. */
+export function placeholderEntry(model) {
+  return {
+    id: String(model ?? ''),
+    name: String(model ?? ''),
+    type: 'chat',
+    protocol: 'openai_chat',
+    input: ['text'],
+    vision: false,
+    toolCalls: true,
+    reasoning: false,
+    efforts: [],
+    isDefault: false,
+    isDefaultSmall: false
+  }
+}
+
+/** Fetch the live catalog for one account session. Throws on any failure. */
+export async function fetchCatalog(session) {
+  const { status, json } = await requestJson('GET', `${API_BASE_URL}/api/v1/models`, {
+    token: session,
+    Accept: 'application/json',
+    'loomy-version': CLIENT_VERSION
+  }, { timeoutMs: 30_000 })
+  if (status !== 200) {
+    const error = new Error(`取模型列表失败：HTTP ${status}`)
+    error.status = status
+    error.isAuthError = status === 401 || status === 403
+    throw error
+  }
+  const list = Array.isArray(json?.data) ? json.data : undefined
+  if (list === undefined) throw new Error('取模型列表失败：响应没有 data 数组')
+  const entries = list.map(normalizeEntry).filter((entry) => entry !== undefined)
+  return {
+    entries,
+    catalogVersion: typeof json?.reasoning_catalog_version === 'string' ? json.reasoning_catalog_version : '',
+    reasoningEnabled: json?.reasoning_enabled === true
+  }
+}
+
+/* ── the on-disk cache ─────────────────────────────────────────────────────── */
+
+/** `{ [accountId]: { savedAt, catalogVersion, entries } }`. */
+function readCache() {
+  const parsed = readJson(CATALOG_FILE)
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {}
+}
+
+/** The last good catalog for one account, or `undefined`. */
+export function readCachedCatalog(accountId) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  return readCache()[key]
+}
+
+/** Replace one account's cached catalog. Best effort: a cache write may never break a call. */
+export function writeCachedCatalog(accountId, catalog) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  try {
+    const cache = readCache()
+    cache[key] = {
+      savedAt: Date.now(),
+      catalogVersion: catalog.catalogVersion,
+      entries: catalog.entries
+    }
+    writeJson(CATALOG_FILE, cache, { mode: 0o600 })
+  } catch {
+    // the live answer is already in hand; the cache is only a fallback
+  }
+}
+
+/**
+ * The catalog for one account, live first and cached second.
+ *
+ * The live read always wins when it succeeds — a stale list that hides a newly granted
+ * model is worse than a slow picker. `source` reports which one answered, so the panel
+ * can say "本地缓存" rather than implying the list is current.
+ */
+export async function loadCatalog(accountId, session, { force = false } = {}) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  const cached = readCachedCatalog(key)
+  if (!force && cached !== undefined && Date.now() - cached.savedAt < CATALOG_TTL_MS) {
+    return { entries: cached.entries, source: 'cache-fresh', savedAt: cached.savedAt, catalogVersion: cached.catalogVersion }
+  }
+  try {
+    const live = await fetchCatalog(session)
+    writeCachedCatalog(key, live)
+    return { entries: live.entries, source: 'live', savedAt: Date.now(), catalogVersion: live.catalogVersion }
+  } catch (error) {
+    if (cached !== undefined) {
+      return {
+        entries: cached.entries,
+        source: 'cache-stale',
+        savedAt: cached.savedAt,
+        catalogVersion: cached.catalogVersion,
+        reason: error instanceof Error ? error.message : String(error),
+        isAuthError: error?.isAuthError === true
+      }
+    }
+    throw error
+  }
+}
+
+/** The best display name for an id, from the catalog, without doing any I/O. */
+export function nameFromCache(accountId, model) {
+  const cached = readCachedCatalog(accountId)
+  const entry = cached?.entries?.find((candidate) => candidate.id === model)
+  return entry?.name ?? model
+}

package/src/account/session.js

@@ -0,0 +1,115 @@
+/**
+ * The session string and how a stale one is handled.
+ *
+ * A Loomy session has no expiry field and no refresh endpoint: the only signal that it
+ * died is the server answering `100002` (points API) or `401/403` (model gateway).
+ * Those two paths therefore share one reaction here — mark the account as needing a
+ * re-login, and stop pretending it works — instead of each caller inventing its own.
+ *
+ * Marking rather than deleting is deliberate: an account whose session merely expired
+ * still has an id, a label and a masked phone, and the panel should show it as
+ * "登录已失效" with a re-login button rather than make it silently vanish.
+ */
+
+import { accountOf, readAccounts } from './auth.js'
+import { readJson, writeJson } from '../core/paths.js'
+import { responseCode, AUTH_ERROR_CODES } from '../core/http.js'
+
+const EXPIRED_FILE = 'expired.json'
+
+/** `{ [accountId]: { at, reason } }` — accounts whose last call was rejected as unauthorized. */
+function readExpired() {
+  const parsed = readJson(EXPIRED_FILE)
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {}
+}
+
+/** The session for one account, or an error naming what to do about it. */
+export function sessionOf(account) {
+  const session = typeof account?.session === 'string' ? account.session.trim() : ''
+  if (session.length === 0) {
+    throw new Error(`账号 ${account?.id ?? '?'} 尚未登录，请先在设置里登录 Loomy`)
+  }
+  return session
+}
+
+/** Session for an id, reading the table once. */
+export function sessionForId(id) {
+  const account = accountOf(id)
+  if (account === undefined) throw new Error(`未找到账号 "${String(id ?? '')}"`)
+  return { account, session: sessionOf(account) }
+}
+
+/** Record that an account's session was rejected, so the panel can say so. */
+export function markExpired(accountId, reason) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  if (key.length === 0) return
+  const expired = readExpired()
+  expired[key] = { at: Date.now(), reason: String(reason ?? '登录已失效') }
+  writeJson(EXPIRED_FILE, expired, { mode: 0o600 })
+}
+
+/** Clear the expired mark, after a successful re-login or a successful call. */
+export function clearExpired(accountId) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  const expired = readExpired()
+  if (!(key in expired)) return
+  delete expired[key]
+  writeJson(EXPIRED_FILE, expired, { mode: 0o600 })
+}
+
+/** Whether this account is currently marked as having a dead session. */
+export function isExpired(accountId) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  return key in readExpired()
+}
+
+/** The mark itself (timestamp + reason), or `undefined`. */
+export function expiredInfo(accountId) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  return readExpired()[key]
+}
+
+/**
+ * Whether a thrown error means "this session is no longer valid".
+ *
+ * Two different transports answer two different ways: the points API uses the string
+ * envelope code `100002`, while the gateway rejects the bearer with a plain 401/403.
+ * The adapter and the panel both need this predicate, so it lives here rather than
+ * being re-derived at each call site.
+ */
+export function isAuthFailure(error) {
+  if (typeof error !== 'object' || error === null) return false
+  if (error.isAuthError === true) return true
+  const code = responseCode(error)
+  if (code !== undefined && AUTH_ERROR_CODES.has(code)) return true
+  const status = Number(error.status)
+  return status === 401 || status === 403
+}
+
+/**
+ * Run one call that needs a session and react to an auth rejection.
+ *
+ * Success clears any stale expiry mark, so the panel does not keep saying "登录已失效"
+ * after a call that just worked.
+ */
+export async function withSession(accountId, run) {
+  const { account, session } = sessionForId(accountId)
+  try {
+    const value = await run(session, account)
+    clearExpired(account.id)
+    return value
+  } catch (error) {
+    if (isAuthFailure(error)) markExpired(account.id, error instanceof Error ? error.message : String(error))
+    throw error
+  }
+}
+
+/** Every account with its expiry mark folded in, for the panel's table. */
+export function accountsWithState() {
+  const expired = readExpired()
+  return readAccounts().map((account) => ({
+    ...account,
+    expiredAt: expired[account.id]?.at ?? 0,
+    expiredReason: expired[account.id]?.reason ?? ''
+  }))
+}

package/src/core/endpoints.js

@@ -0,0 +1,78 @@
+/**
+ * Every remote this plugin talks to, and the fixed client identity Loomy expects.
+ *
+ * Loomy is a desktop app (iFlytek "Loomy") whose model traffic is metered by the
+ * account's points balance. There is no public API key: an account logs in through
+ * iFlytek's CAccount service, receives a `session` string, and every later call
+ * carries that string — either as a `token` header (points/business API) or as both
+ * `Authorization: Bearer` and `token` (model gateway).
+ *
+ * Four hosts, and they are genuinely different services:
+ *
+ *   account   https://account.xfinfr.com      CAccount login (HMAC-SHA1 signed)
+ *   api       https://loomyad.xunfei.cn       points, models, onboarding, pet-work
+ *   gateway   https://loomyad.xunfei.cn/api/v1   OpenAI-compatible chat/completions
+ *   web       https://loomy.xunfei.cn         site pages (share, docs)
+ *
+ * The CAccount credentials below are the desktop client's own, shipped inside
+ * `resources/.env.prod` (encrypted with a passphrase that ships beside it). They
+ * identify the *client application*, not a user: a login still requires the user's
+ * own phone and an SMS code. They are accepted here because the alternative is
+ * "the plugin only works if you reverse-engineer your own copy of Loomy", and
+ * because they are inert without a user's credentials.
+ *
+ * All three can be overridden from the environment, which is what a build against
+ * a staging deployment needs.
+ */
+
+const env = (key, fallback) => {
+  const value = process.env[key]
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback
+}
+
+export const ACCOUNT_BASE_URL = env('LOOMY_ACCOUNT_BASE_URL', 'https://account.xfinfr.com')
+export const API_BASE_URL = env('LOOMY_API_BASE_URL', 'https://loomyad.xunfei.cn')
+export const WEB_BASE_URL = env('LOOMY_WEB_BASE_URL', 'https://loomy.xunfei.cn')
+
+/** The model gateway root; chat lives at `${GATEWAY_BASE_URL}/chat/completions`. */
+export const GATEWAY_BASE_URL = env('LOOMY_GATEWAY_BASE_URL', `${API_BASE_URL}/api/v1`)
+
+/** CAccount signing identity (the desktop client's application credentials). */
+export const ACCOUNT_ACCESS_KEY_ID = env('LOOMY_ACCOUNT_ACCESS_KEY_ID', '2thryby66wxi53sk')
+export const ACCOUNT_ACCESS_KEY_SECRET = env('LOOMY_ACCOUNT_ACCESS_KEY_SECRET', 'zsak6eadrbawz683wf5r3m2snrwj868r')
+export const ACCOUNT_APP_ID = env('LOOMY_ACCOUNT_APP_ID', 'GM3LOOMY')
+
+/**
+ * The `base` block every CAccount request carries. `modelid`/`devid` are the
+ * desktop client's placeholders; the server uses them for channel attribution, not
+ * for authentication, so the literal values are what matters rather than realism.
+ */
+export const ACCOUNT_CLIENT_UA = 'Loomy|Desktop|Electron|macOS'
+
+/** `loomy-version` header. The gateway logs it; no observed behaviour depends on it. */
+export const CLIENT_VERSION = env('LOOMY_CLIENT_VERSION', '0.9.39')
+
+/**
+ * The request-purpose protocol value the official client sends for a chat turn.
+ * The gateway uses it to attribute points consumption; an unknown value is dropped
+ * rather than rejected, so a caller that cannot classify a request sends nothing.
+ */
+export const PURPOSE_CHAT_MESSAGE = 'chat.message'
+
+/**
+ * A Loomy desktop login session, as parked by that app on this machine.
+ *
+ * Reading it is how a user can adopt an existing Loomy login instead of going
+ * through SMS again. The path is the Windows layout the desktop client uses
+ * (`C:\Users\Public\Loomy\<user-hash>\userData\auth-session.json`); on other
+ * platforms the same file lives under the app's userData directory, so the
+ * resolver walks the documented candidates and gives up quietly.
+ */
+export const LOOMY_DESKTOP_SESSION_PATTERNS = {
+  win32: [
+    'C:\\Users\\Public\\Loomy',
+    'C:\\Users\\Public\\Loomy\\userData'
+  ],
+  darwin: ['~/Library/Application Support/Loomy'],
+  linux: ['~/.config/loomy']
+}

package/src/core/http.js

@@ -0,0 +1,124 @@
+/**
+ * Transport and envelope helpers shared by every Loomy call.
+ *
+ * Two different envelope families answer from the same host, and the difference matters:
+ *
+ *   `https://loomyad.xunfei.cn/api/v1/*`  → `{ code: "000000", desc, data, trace_id }`
+ *                                          (string code; "000000" is success)
+ *   `https://account.xfinfr.com/*`        → `{ code: "000000", desc, data }`  (iFlytek CAccount)
+ *   `https://loomyad.xunfei.cn/api/v1/models` → a bare `{ object: "list", data: [ ... ] }`
+ *
+ * Nothing here knows about accounts; it only normalizes the shapes so callers never
+ * have to guess between `desc` and `message`, or between `data` and `data.data`.
+ */
+
+export const REQUEST_TIMEOUT_MS = 60_000
+export const STATE_TIMEOUT_MS = 15_000
+
+/**
+ * JSON request that never throws for a non-JSON body: a proxy or a captcha page can
+ * still answer with HTML, and the caller's status handling is what decides the outcome.
+ */
+export async function requestJson(method, url, headers, options = {}) {
+  const signal = AbortSignal.timeout(options.timeoutMs ?? REQUEST_TIMEOUT_MS)
+  let response
+  try {
+    response = await fetch(url, {
+      method,
+      headers,
+      signal,
+      ...(options.body === undefined ? {} : { body: options.body })
+    })
+  } catch (error) {
+    throw new Error(`${method} ${url} failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  let json = null
+  try {
+    json = await response.json()
+  } catch {
+    json = null
+  }
+  return { status: response.status, json }
+}
+
+/** The envelope body, or `undefined` when the answer has none. */
+export function responseData(json) {
+  if (typeof json !== 'object' || json === null) return undefined
+  return typeof json.data === 'object' && json.data !== null ? json.data : undefined
+}
+
+/**
+ * The envelope's business code as a string, or `undefined` when there is no envelope.
+ *
+ * Returning a success value for an unparseable body made a timed-out or truncated 200
+ * read as success. Callers compare against `'000000'` explicitly, so `undefined` means
+ * "no answer" rather than "fine".
+ */
+export function responseCode(json) {
+  if (typeof json !== 'object' || json === null) return undefined
+  const code = json.code
+  if (typeof code === 'string') return code
+  if (typeof code === 'number' && Number.isFinite(code)) return String(code)
+  return undefined
+}
+
+export function responseMessage(json) {
+  if (typeof json !== 'object' || json === null) return ''
+  for (const key of ['desc', 'message', 'msg', 'error']) {
+    if (typeof json[key] === 'string' && json[key].length > 0) return json[key]
+  }
+  return ''
+}
+
+/** Business codes that mean "the login session is no longer valid". */
+export const AUTH_ERROR_CODES = new Set(['100002', '020002'])
+
+/**
+ * Throw for anything that is not a successful envelope, and answer the payload.
+ *
+ * `label` names the operation in the message, so a failure reads as "取模型列表失败：
+ * 未登录或登录已失效" rather than a bare server string.
+ */
+export function unwrap(json, label) {
+  const code = responseCode(json)
+  if (code === undefined) throw new Error(`${label}：响应不是合法 JSON`)
+  if (code !== '000000') {
+    const message = responseMessage(json) || `业务错误 ${code}`
+    const error = new Error(`${label}：${message}`)
+    error.code = code
+    error.isAuthError = AUTH_ERROR_CODES.has(code)
+    throw error
+  }
+  return json
+}
+
+export function readString(source, key) {
+  const value = source?.[key]
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  return ''
+}
+
+/** Local calendar day, used as the bookkeeping key for the daily credit grant. */
+export function localDayKey(now = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`
+}
+
+/** Milliseconds until the next local midnight. */
+export function msUntilNextMidnight(now = new Date()) {
+  const next = new Date(now)
+  next.setHours(24, 0, 0, 0)
+  return next.getTime() - now.getTime()
+}
+
+/** `setTimeout` that never keeps the host process alive. */
+export const sleep = (ms) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, ms)
+  timer.unref?.()
+})
+
+export function formatWhen(ms) {
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return '未知'
+  return new Date(ms).toLocaleString()
+}