opencode-claude-code-ua 0.0.0-stage → 0.3.6

package/src/accounts.mjs

@@ -0,0 +1,281 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { AccountValidationError, createNewApiClient, NewApiError, normalizeAccountConfig, safeNewApiMessage } from './newapi.mjs';
+import { scheduleOccurrence } from './schedule.mjs';
+
+export { AccountValidationError } from './newapi.mjs';
+const MAX_ACCOUNTS = 100;
+const MAX_HISTORY = 90;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+// All managers sharing a file share the transaction queue and network deduplication.
+const sessions = new Map();
+const freshStatus = () => ({ stale: false, error: null, lastAttemptAt: null });
+const freshCheckin = () => ({ date: null, checkedAt: null, rewardQuota: null, state: 'unknown', message: '' });
+const identity = a => JSON.stringify([a.siteUrl, a.userId]);
+const missing = () => new AccountValidationError('账号不存在。', 404);
+const own = (state, id) => { const account = state.accounts.find(a => a.id === id); if (!account) throw missing(); return account; };
+const successful = result => ['success', 'already', 'already_checked'].includes(result?.state);
+const day = value => new Date(value).toISOString().slice(0, 10);
+const amount = (quota, divisor) => quota === null || quota === undefined || !Number.isFinite(quota / divisor) ? null : quota / divisor;
+
+function projectSnapshot(snapshot, divisor) {
+  if (!snapshot) return null;
+  return { at: snapshot.at, quota: snapshot.quota, usedQuota: snapshot.usedQuota, requestCount: snapshot.requestCount,
+    remaining: amount(snapshot.quota, divisor), used: amount(snapshot.usedQuota, divisor),
+    deltaBalance: amount(snapshot.deltaQuota, divisor), deltaUsed: amount(snapshot.deltaUsedQuota, divisor),
+    deltaRequests: snapshot.deltaRequests, reset: snapshot.reset };
+}
+
+function publicAccount(account) {
+  const config = normalizeAccountConfig(account);
+  return { id: account.id, revision: account.revision, ...config, accessToken: '', cookie: '', secrets: { accessToken: Boolean(account.accessToken), cookie: Boolean(account.cookie) },
+    snapshot: projectSnapshot(account.snapshot, account.quotaPerUnit),
+    history: account.history.map(item => projectSnapshot(item, account.quotaPerUnit)),
+    status: { ...account.status },
+    checkin: { date: account.checkin.date, checkedAt: account.checkin.checkedAt, rewardQuota: account.checkin.rewardQuota,
+      reward: amount(account.checkin.rewardQuota, account.quotaPerUnit), state: account.checkin.state, message: account.checkin.message } };
+}
+
+function totalsFor(accounts) {
+  const groups = new Map();
+  for (const account of accounts) {
+    if (!groups.has(account.unit)) groups.set(account.unit, []);
+    groups.get(account.unit).push(account);
+  }
+  return Object.fromEntries([...groups].map(([unit, configured]) => {
+    const unique = new Map();
+    for (const account of configured) {
+      const previous = unique.get(identity(account));
+      // Prefer a current successful snapshot; aliases never multiply money.
+      if (!previous || !previous.snapshot && account.snapshot || previous.status.stale && !account.status.stale && account.snapshot || previous.status.stale === account.status.stale && (account.snapshot?.at ?? '') > (previous.snapshot?.at ?? '')) unique.set(identity(account), account);
+    }
+    const entries = [...unique.values()];
+    const available = entries.filter(a => a.snapshot);
+    const total = key => {
+      if (!available.length || available.some(a => a.snapshot[key] === null)) return null;
+      const value = available.reduce((sum, a) => sum + a.snapshot[key], 0);
+      return Number.isFinite(value) ? value : null;
+    };
+    const delta = key => available.length === entries.length && entries.every(a => !a.status.stale && a.snapshot[key] !== null) ? total(key) : null;
+    return [unit, { remaining: total('remaining'), used: total('used'), deltaBalance: delta('deltaBalance'), deltaUsed: delta('deltaUsed'),
+      accountCount: entries.length, configuredCount: configured.length, availableCount: available.length, staleCount: entries.filter(a => a.status.stale).length }];
+  }));
+}
+
+/** Independent accounts.json; all methods are async, and no network occurs on CRUD. */
+export function createAccountManager({ path, fetchImpl, now = () => new Date(), uuid = randomUUID, client } = {}) {
+  if (typeof path !== 'string' || !isAbsolute(path)) throw new AccountValidationError('账号文件必须使用绝对路径。');
+  path = resolve(path);
+  const key = process.platform === 'win32' ? path.toLowerCase() : path;
+  if (!sessions.has(key)) sessions.set(key, { tail: Promise.resolve(), refreshes: new Map(), checkins: new Map() });
+  const session = sessions.get(key);
+  const api = client ?? createNewApiClient({ fetchImpl, now });
+  const timestamp = () => new Date(now()).toISOString();
+  const locked = task => {
+    const result = session.tail.then(task, task);
+    session.tail = result.catch(() => {});
+    return result;
+  };
+
+  async function read() {
+    try {
+      if ((await stat(path)).size > MAX_FILE_BYTES) throw new Error();
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state.version !== 1 || !Array.isArray(state.accounts) || state.accounts.length > MAX_ACCOUNTS) throw new Error();
+      const ids = new Set();
+      for (const account of state.accounts) {
+        if (!account || typeof account.id !== 'string' || !account.id || ids.has(account.id) || typeof account.revision !== 'string' || !Array.isArray(account.history) || account.history.length > MAX_HISTORY || !account.status || !account.checkin) throw new Error();
+        Object.assign(account, normalizeAccountConfig(account));
+        ids.add(account.id);
+      }
+      return state;
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { version: 1, accounts: [] };
+      throw new AccountValidationError('账号文件无法读取。', 500);
+    }
+  }
+
+  async function write(state) {
+    let temporary; let handle;
+    try {
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      temporary = `${path}.${randomUUID()}.tmp`;
+      handle = await open(temporary, 'wx', 0o600);
+      await handle.writeFile(JSON.stringify(state, null, 2), 'utf8');
+      await handle.sync();
+      await handle.close(); handle = null;
+      await rename(temporary, path); temporary = null;
+    } catch { throw new AccountValidationError('账号文件无法保存。', 500); }
+    finally { if (handle) await handle.close().catch(() => {}); if (temporary) await unlink(temporary).catch(() => {}); }
+  }
+
+  async function list() {
+    return locked(async () => { const accounts = (await read()).accounts.map(publicAccount); return { accounts, totals: totalsFor(accounts) }; });
+  }
+  async function get(id) { return locked(async () => publicAccount(own(await read(), id))); }
+
+  async function save(raw, clearSecrets = []) {
+    if (!Array.isArray(clearSecrets) || clearSecrets.some(name => !['accessToken', 'cookie'].includes(name))) throw new AccountValidationError('清除凭据的字段无效。');
+    const config = normalizeAccountConfig(raw);
+    return locked(async () => {
+      const state = await read();
+      const previous = raw.id === undefined ? null : own(state, raw.id);
+      if (!previous && state.accounts.length >= MAX_ACCOUNTS) throw new AccountValidationError('最多保存 100 个账号。', 409);
+      if (config.schedule.enabled && state.accounts.some(account => account !== previous
+        && identity(account) === identity(config) && account.schedule.enabled)) {
+        throw new AccountValidationError('自动签到设置冲突。', 400, {
+          'schedule.enabled': '同一站点账号的别名只能设置一份自动签到，请先关闭另一份',
+        });
+      }
+      const unchangedIdentity = previous && identity(previous) === identity(config);
+      for (const secret of ['accessToken', 'cookie']) config[secret] = config[secret] || (!unchangedIdentity || clearSecrets.includes(secret) ? '' : previous?.[secret] ?? '');
+      const account = { ...config, id: previous?.id ?? uuid(), revision: randomUUID(),
+        snapshot: unchangedIdentity ? previous.snapshot : null,
+        history: unchangedIdentity ? previous.history : [],
+        status: unchangedIdentity ? previous.status : freshStatus(),
+        checkin: unchangedIdentity ? previous.checkin : freshCheckin() };
+      if (typeof account.id !== 'string' || !account.id || state.accounts.some(a => a.id === account.id && a !== previous)) throw new AccountValidationError('无法创建唯一账号 ID。', 409);
+      if (previous) state.accounts[state.accounts.indexOf(previous)] = account;
+      else state.accounts.push(account);
+      await write(state);
+      return publicAccount(account);
+    });
+  }
+
+  async function remove(id) {
+    return locked(async () => { const state = await read(); own(state, id); state.accounts = state.accounts.filter(a => a.id !== id); await write(state); return { removed: true }; });
+  }
+
+  async function performRefresh(captured) {
+    const at = timestamp();
+    let reading; let failure;
+    try {
+      reading = await api.balance({ ...captured });
+      if (!reading || !Number.isSafeInteger(reading.quota) || !Number.isSafeInteger(reading.usedQuota) || reading.usedQuota < 0 || !Number.isSafeInteger(reading.requestCount) || reading.requestCount < 0) throw new NewApiError('response');
+    } catch (error) { failure = safeNewApiMessage(error); }
+    return locked(async () => {
+      const state = await read(); const current = own(state, captured.id);
+      if (current.revision !== captured.revision || identity(current) !== identity(captured)) return publicAccount(current);
+      current.status = { lastAttemptAt: at, stale: Boolean(failure), error: failure ?? null };
+      if (!failure) {
+        const prior = current.snapshot;
+        const usedReset = Boolean(prior && reading.usedQuota < prior.usedQuota);
+        const requestReset = Boolean(prior && reading.requestCount < prior.requestCount);
+        current.snapshot = { at: reading.at && Number.isFinite(Date.parse(reading.at)) ? new Date(reading.at).toISOString() : at,
+          quota: reading.quota, usedQuota: reading.usedQuota, requestCount: reading.requestCount,
+          deltaQuota: prior ? reading.quota - prior.quota : null,
+          deltaUsedQuota: prior && !usedReset ? reading.usedQuota - prior.usedQuota : null,
+          deltaRequests: prior && !requestReset ? reading.requestCount - prior.requestCount : null,
+          reset: usedReset || requestReset };
+        current.history = [...current.history, current.snapshot].slice(-MAX_HISTORY);
+      }
+      await write(state);
+      return publicAccount(current);
+    });
+  }
+
+  async function refresh(id) {
+    const captured = await locked(async () => structuredClone(own(await read(), id)));
+    if (!captured.enabled) return publicAccount(captured);
+    const requestKey = `${id}:${captured.revision}`;
+    if (!session.refreshes.has(requestKey)) {
+      const pending = performRefresh(captured).finally(() => { if (session.refreshes.get(requestKey) === pending) session.refreshes.delete(requestKey); });
+      session.refreshes.set(requestKey, pending);
+    }
+    return session.refreshes.get(requestKey);
+  }
+
+  function checkinResult(result, at) {
+    const states = ['success', 'already', 'disabled', 'requires_verification', 'unknown', 'error'];
+    const state = result?.state === 'already_checked' ? 'already' : states.includes(result?.state) ? result.state : 'error';
+    const validDate = /^\d{4}-\d{2}-\d{2}$/u.test(result?.date ?? '') && Number.isFinite(Date.parse(result.date)) && day(result.date) === result.date;
+    const messages = { success: '签到成功。', already: '今日已签到。', disabled: '站点未启用签到。', requires_verification: '请前往站点完成验证码后签到。', unknown: '签到结果未确认，请在站点确认记录；不会自动重试。', error: '签到未完成，请前往站点检查。' };
+    return { date: successful({ state }) ? validDate ? result.date : day(at) : null,
+      checkedAt: successful({ state }) ? at : null,
+      rewardQuota: successful({ state }) && Number.isSafeInteger(result.rewardQuota) && result.rewardQuota >= 0 ? result.rewardQuota : null,
+      state, message: messages[state],
+      // Returned site dates are authoritative; UTC is the explicit fallback when absent.
+      dedupeDay: successful({ state }) ? day(at) : null };
+  }
+
+  async function performCheckin(captured, aliases, options) {
+    const at = timestamp(); let result;
+    try { result = checkinResult(await api.checkin({ ...captured }, options), at); }
+    catch (error) {
+      const code = error instanceof NewApiError ? error.code : null;
+      const state = code === 'turnstile' ? 'requires_verification' : code === 'ambiguous' ? 'unknown' : 'error';
+      result = { ...checkinResult({ state }, at), message: safeNewApiMessage(error) };
+    }
+    const updated = await locked(async () => {
+      const state = await read(); const initiator = state.accounts.find(a => a.id === captured.id);
+      if (!initiator || initiator.revision !== captured.revision) return false;
+      for (const alias of aliases) {
+        const current = state.accounts.find(a => a.id === alias.id);
+        if (current && current.revision === alias.revision && identity(current) === identity(captured)) current.checkin = { ...result };
+      }
+      await write(state); return true;
+    });
+    if (updated && successful(result)) {
+      // A later refresh failure only marks the balance stale, never changes checkin success.
+      for (const alias of aliases) {
+        try {
+          const current = await locked(async () => own(await read(), alias.id));
+          if (current.revision === alias.revision) await refresh(alias.id);
+        } catch { /* A removed alias or a failed refresh cannot undo a confirmed checkin. */ }
+      }
+    }
+  }
+
+  async function checkin(id, { turnstileToken, expectedRevision } = {}) {
+    const selection = await locked(async () => {
+      const state = await read(); const captured = own(state, id);
+      if (expectedRevision !== undefined) {
+        if (expectedRevision !== captured.revision) throw new AccountValidationError('账号配置已更改，本次自动签到已取消。', 409);
+        if (!captured.schedule.enabled || !scheduleOccurrence(captured.schedule, new Date(now()))) {
+          throw new AccountValidationError('自动签到已关闭或已错过指定时间，本次未执行。', 409);
+        }
+      }
+      if (!captured.enabled || !captured.checkinEnabled) return { skip: publicAccount(captured) };
+      // Check the current id/revision before joining; identity, not revision, deduplicates POSTs.
+      const requestKey = identity(captured);
+      if (session.checkins.has(requestKey)) return { pending: session.checkins.get(requestKey) };
+      const sameIdentity = state.accounts.filter(a => identity(a) === identity(captured));
+      const known = sameIdentity.find(a => successful(a.checkin) && (a.checkin.dedupeDay ?? a.checkin.date) === day(timestamp()));
+      if (known && !api.authoritativeCheckinDay) {
+        if (captured !== known) { captured.checkin = { ...known.checkin }; await write(state); }
+        return { skip: publicAccount(captured) };
+      }
+      const aliases = sameIdentity.filter(a => a.enabled && a.checkinEnabled).map(a => ({ id: a.id, revision: a.revision }));
+      const pending = performCheckin(structuredClone(captured), aliases, { turnstileToken }).finally(() => {
+        if (session.checkins.get(requestKey) === pending) session.checkins.delete(requestKey);
+      });
+      session.checkins.set(requestKey, pending);
+      // Do not await network while holding the file transaction queue.
+      return { pending };
+    });
+    if (selection.skip) return selection.skip;
+    await selection.pending;
+    return get(id);
+  }
+
+  async function refreshAll() {
+    const { accounts } = await list();
+    for (const account of accounts.filter(a => a.enabled)) {
+      try { await refresh(account.id); } catch { /* Isolate deletion and individual account failures. */ }
+    }
+    return list();
+  }
+  async function checkinAll() {
+    const { accounts } = await list();
+    const attempted = new Set();
+    for (const account of accounts.filter(a => a.enabled && a.checkinEnabled)) {
+      const key = identity(account);
+      if (attempted.has(key)) continue;
+      attempted.add(key);
+      try { await checkin(account.id); } catch { /* Continue the explicitly requested batch. */ }
+    }
+    return list();
+  }
+  return { list, get, save, remove, refresh, checkin, refreshAll, checkinAll };
+}

package/src/connection.mjs

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto';
+import { createDefaultProfile, normalizeProfile, targetOf } from './profile.mjs';
+import { buildHeaders } from './headers.mjs';
+
+export const AUTH_MARKER = 'magpie-claude-profile-configured';
+const text = value => typeof value === 'string' && value.trim() ? value.trim() : undefined;
+const sameTarget = (left, right) => targetOf(left) !== null && targetOf(left) === targetOf(right);
+
+/** defaults contains explicit global options only; credentials always come from the account or same-target saved profile. */
+export function connectionProfile(saved, auth, provider = {}, defaults) {
+  const key = auth?.type === 'api' && text(auth.key) !== AUTH_MARKER ? text(auth.key) : undefined;
+  const endpoint = text(auth?.metadata?.baseURL) ?? text(auth?.metadata?.endpoint) ?? text(auth?.endpoint) ??
+    text(provider.options?.baseURL) ?? text(provider.api) ?? text(provider.api?.url) ?? text(saved?.upstream?.baseUrl) ?? text(defaults?.upstream?.baseUrl);
+  const candidate = key ? auth?.metadata?.claudeProfile : undefined;
+  const scoped = candidate && sameTarget(endpoint, candidate.upstream?.baseUrl) ? candidate : undefined;
+  // A native key change is a separate connection, even at the same host and path.
+  const inherit = saved && sameTarget(endpoint, saved.upstream?.baseUrl) && (!key || saved.upstream?.apiKey === key);
+  const source = scoped ?? (inherit ? saved : undefined);
+  const base = createDefaultProfile();
+  const global = defaults ? normalizeProfile(defaults, { allowBlank: true }) : undefined;
+  const profile = structuredClone(source ?? global ?? base);
+  if (source && global) {
+    profile.client = { ...global.client, ...source.client };
+    profile.headers = { ...global.headers, ...source.headers, extra: [...global.headers.extra, ...(source.headers?.extra ?? [])] };
+    profile.parameters = { ...global.parameters, ...source.parameters };
+    profile.models = source.models ?? global.models;
+  }
+  profile.upstream = { ...base.upstream, ...(source?.upstream ?? {}), baseUrl: endpoint ?? '' };
+  if (key) {
+    profile.upstream.apiKey = key;
+    // Only account-scoped modes are explicit for native auth. Native default is x-api-key.
+    profile.upstream.authorizationMode = scoped?.upstream?.authorizationMode ?? 'api-key';
+    profile.upstream.authorizationValue = scoped?.upstream?.authorizationValue ?? '';
+  }
+  return normalizeProfile(profile);
+}
+
+export function modelRecords(profile, ids = profile.models, existing = {}) {
+  const npm = '@ai-sdk/anthropic';
+  return Object.fromEntries([...new Set(ids)].map(id => [id, {
+    ...(existing[id] ?? {}), name: existing[id]?.name ?? id,
+    api: { id: existing[id]?.api?.id ?? existing[id]?.id ?? id, url: profile.upstream.baseUrl, npm, ...(existing[id]?.api ?? {}) },
+    provider: { npm, api: profile.upstream.baseUrl, ...(existing[id]?.provider ?? {}) },
+  }]));
+}
+export class ModelDiscoveryError extends Error {
+  constructor(code, httpStatus) {
+    super(code === 'unauthorized' ? '模型列表拒绝了当前 API key，请重新登录' : '无法自动获取模型，请检查地址和 API key；也可在可选高级设置中填写模型 ID');
+    this.name = 'ModelDiscoveryError'; this.code = code;
+    if (httpStatus !== undefined) this.httpStatus = httpStatus;
+    if (code === 'unauthorized') this.signIn = 'expired';
+  }
+}
+function responseErrorCode(status) {
+  if (status >= 300 && status < 400) return 'redirect';
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 404 || status === 405) return 'unsupported-list';
+  if (status === 429) return 'rate-limited';
+  if (status >= 500 && status < 600) return 'upstream-error';
+  return status >= 200 && status < 300 ? 'invalid-response' : 'http-error';
+}
+async function requestModelRecords(profile, { fetchImpl, timeoutMs, requireStatus200 }) {
+  const url = `${profile.upstream.baseUrl.replace(/\/+$/, '')}/models`;
+  const headers = buildHeaders({ profile, stream: false });
+  for (const name of ['x-claude-code-session-id', 'session-id', 'x-client-request-id', 'x-request-id', 'request-id']) headers.delete(name);
+  headers.set('accept', 'application/json');
+  const controller = new AbortController();
+  let timeout, response, httpStatus, reader, cancelled = false;
+  const cancel = () => {
+    const body = reader ?? response?.body;
+    if (!body || cancelled) return;
+    cancelled = true;
+    try { void Promise.resolve(body.cancel()).catch(() => {}); } catch {}
+  };
+  const release = () => { try { reader?.releaseLock(); } catch {} reader = undefined; };
+  const deadline = new Promise((_, reject) => {
+    timeout = setTimeout(() => { reject(new ModelDiscoveryError('timeout', httpStatus)); controller.abort(); cancel(); release(); }, timeoutMs);
+  });
+  try {
+    return await Promise.race([deadline, (async () => {
+      try { response = await fetchImpl(url, { method: 'GET', headers, redirect: 'manual', signal: controller.signal }); }
+      catch { throw new ModelDiscoveryError('network'); }
+      if (controller.signal.aborted) { cancel(); throw new ModelDiscoveryError('timeout'); }
+      if (Number.isInteger(response.status) && response.status >= 100 && response.status <= 599) httpStatus = response.status;
+      if (response.redirected || (response.url && response.url !== url)) throw new ModelDiscoveryError('redirect', httpStatus);
+      if (!response.ok || (requireStatus200 && response.status !== 200)) throw new ModelDiscoveryError(responseErrorCode(response.status), httpStatus);
+      if (Number(response.headers.get('content-length')) > 1024 * 1024) throw new ModelDiscoveryError('too-large', httpStatus);
+      reader = response.body?.getReader();
+      if (!reader) throw new ModelDiscoveryError('invalid-shape', httpStatus);
+      const chunks = []; let size = 0;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (controller.signal.aborted) throw new ModelDiscoveryError('timeout', httpStatus);
+        if (done) break;
+        size += value.byteLength;
+        if (size > 1024 * 1024) throw new ModelDiscoveryError('too-large', httpStatus);
+        chunks.push(Buffer.from(value));
+      }
+      let data;
+      try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+      catch { throw new ModelDiscoveryError('invalid-json', httpStatus); }
+      if (!Array.isArray(data?.data)) throw new ModelDiscoveryError('invalid-shape', httpStatus);
+      const entries = data.data.filter(item => typeof item?.id === 'string' && item.id.trim() && !/[\u0000-\u001f\u007f]/.test(item.id)).slice(0, 2000);
+      if (!entries.length) throw new ModelDiscoveryError('empty-model-list', httpStatus);
+      const existing = Object.fromEntries(entries.map(item => {
+        const model = { name: text(item.display_name) ?? text(item.name) ?? item.id };
+        const context = item.limit?.context ?? item.context_window ?? item.context_length ?? item.max_context_tokens;
+        const output = item.limit?.output ?? item.max_output_tokens;
+        const limit = {};
+        if (Number.isSafeInteger(context) && context > 0) limit.context = context;
+        if (Number.isSafeInteger(output) && output > 0) limit.output = output;
+        if (Object.keys(limit).length) model.limit = limit;
+        return [item.id, model];
+      }));
+      return modelRecords(profile, entries.map(item => item.id), existing);
+    })()]);
+  } catch (error) {
+    cancel();
+    if (error instanceof ModelDiscoveryError) throw error;
+    throw new ModelDiscoveryError('network', httpStatus);
+  } finally { clearTimeout(timeout); release(); }
+}
+export function createModelDiscovery({ fetchImpl = globalThis.fetch, now = Date.now, ttlMs = 60000, timeoutMs = 15000 } = {}) {
+  const cache = new Map(); const pending = new Map();
+  return async function discover(raw, { force = false, ignoreConfigured = false, requireStatus200 = false } = {}) {
+    const profile = normalizeProfile(raw);
+    if (!ignoreConfigured && profile.models.length) return modelRecords(profile);
+    if (force) return requestModelRecords(profile, { fetchImpl, timeoutMs, requireStatus200 });
+    const key = createHash('sha256').update(JSON.stringify(profile)).digest('hex');
+    const hit = cache.get(key);
+    if (hit && now() - hit.at < ttlMs) return structuredClone(hit.models);
+    if (pending.has(key)) return structuredClone(await pending.get(key));
+    if (pending.size >= 32) throw new ModelDiscoveryError('rate-limited');
+    const task = (async () => {
+      const models = await requestModelRecords(profile, { fetchImpl, timeoutMs, requireStatus200 });
+      if (cache.size >= 32) cache.delete(cache.keys().next().value);
+      cache.set(key, { at: now(), models }); return models;
+    })();
+    pending.set(key, task);
+    try { return structuredClone(await task); }
+    finally { pending.delete(key); }
+  };
+}

package/src/diagnostics.mjs

@@ -0,0 +1,37 @@
+import { createModelDiscovery, ModelDiscoveryError } from './connection.mjs';
+import { normalizeProfile, ProfileValidationError } from './profile.mjs';
+const outcomes = new Map([
+  ['unauthorized', { title: '模型列表请求未获授权', message: '请核对 API 凭据后重新检查。', nextAction: 'edit-credentials' }],
+  ['forbidden', { title: '模型列表访问被拒绝', message: '服务拒绝了模型列表请求，请核对账户访问权限或联系服务方确认访问限制。', nextAction: 'edit-credentials' }],
+  ['unsupported-list', { title: '模型列表接口不可用', message: '服务未提供可用的模型列表接口。可手动填写模型 ID；生成能力尚未测试。', nextAction: 'enter-models' }],
+  ['empty-model-list', { title: '未获得可用的模型 ID', message: '模型列表未包含可用的模型 ID。可手动填写模型 ID；生成能力尚未测试。', nextAction: 'enter-models' }],
+  ['rate-limited', { title: '模型列表请求受到限流', message: '请稍后重新检查。', nextAction: 'retry' }],
+  ['redirect', { title: '模型列表请求发生重定向', message: '检查未接受重定向，请核对并填写服务的直接地址。', nextAction: 'edit-address' }],
+  ['upstream-error', { title: '上游服务暂时异常', message: '服务未能完成模型列表请求，请稍后重试。', nextAction: 'retry' }],
+  ['invalid-response', { title: '模型列表响应无效', message: '模型列表响应无法识别或超过大小限制，请核对服务地址。', nextAction: 'edit-address' }],
+  ['timeout', { title: '模型列表检查超时', message: '未能在限定时间内完整获取模型列表，请稍后重试。', nextAction: 'retry' }],
+  ['network', { title: '模型列表网络请求失败', message: '未能完整获取模型列表，请检查网络连接后重试。', nextAction: 'retry' }],
+  ['http-error', { title: '模型列表请求失败', message: '服务未接受模型列表请求，请确认服务状态后重试。', nextAction: 'retry' }],
+]);
+/** Checks only GET /models; never sends generation requests. */
+export function createConnectionDiagnostics({ fetchImpl = globalThis.fetch, timeoutMs = 15000, now = Date.now } = {}) {
+  const discover = createModelDiscovery({ fetchImpl, timeoutMs, now });
+  return async function check(raw) {
+    const profile = normalizeProfile(raw);
+    const credentials = [profile.upstream.apiKey, profile.upstream.authorizationValue].flatMap(value => [value, value.replace(/^\S+\s+/, '')]).filter(Boolean);
+    try {
+      const models = await discover(profile, { force: true, ignoreConfigured: true, requireStatus200: true });
+      const modelIds = Object.keys(models);
+      if (modelIds.some(id => credentials.some(secret => id.includes(secret)))) throw new ModelDiscoveryError('invalid-response', 200);
+      return { state: 'models-found', code: 'models-found', title: '已获取模型列表', message: '已获取模型列表；尚未测试生成或回复能力。', nextAction: 'save', modelIds,
+        checkedAt: new Date(now()).toISOString(), checks: { modelList: 'passed', generation: 'not-tested' }, httpStatus: 200 };
+    } catch (error) {
+      if (error instanceof ProfileValidationError) throw error;
+      const failure = error instanceof ModelDiscoveryError ? error : undefined;
+      const code = ['invalid-json', 'invalid-shape', 'too-large'].includes(failure?.code) ? 'invalid-response' : outcomes.has(failure?.code) ? failure.code : 'network';
+      const unavailable = code === 'unsupported-list' || code === 'empty-model-list';
+      return { state: unavailable ? 'models-unavailable' : 'failed', code, ...outcomes.get(code), modelIds: [], checkedAt: new Date(now()).toISOString(),
+        checks: { modelList: unavailable ? 'unavailable' : 'failed', generation: 'not-tested' }, ...(failure?.httpStatus === undefined ? {} : { httpStatus: failure.httpStatus }) };
+    }
+  };
+}

package/src/headers.mjs

@@ -0,0 +1,60 @@
+import { CLIENT_PRESETS, HEADER_LIMIT_BYTES, normalizeProfile, isProtectedHeader, isSafeHeaderText } from './profile.mjs';
+export { HEADER_LIMIT_BYTES };
+export class HeaderBuildError extends Error {
+  constructor(message, field) { super(message); this.name = 'HeaderBuildError'; this.code = 'HEADER_BUILD_ERROR'; if (field !== undefined) this.field = field; }
+}
+function render(value, context, field) {
+  let missing = false;
+  const rendered = value.replace(/\{\{([^{}]+)\}\}/g, (_, name) => {
+    const [group, key] = name.split('.');
+    const item = context[name] ?? context[group]?.[key];
+    if ((typeof item !== 'string' || !item.trim()) && !(typeof item === 'number' && Number.isFinite(item)) && typeof item !== 'boolean') { missing = true; return ''; }
+    return String(item);
+  });
+  if (missing) return undefined;
+  if (!isSafeHeaderText(rendered) || rendered.length > HEADER_LIMIT_BYTES) throw new HeaderBuildError('请求头值含有非法字符或超过大小限制', field);
+  return rendered;
+}
+export function buildHeaders({ profile, baseHeaders, context = {}, stream } = {}) {
+  let p;
+  try { p = normalizeProfile(profile, { allowBlank: true }); }
+  catch { throw new HeaderBuildError('profile 配置无效'); }
+  let headers;
+  try { headers = new Headers(baseHeaders ?? undefined); }
+  catch { throw new HeaderBuildError('baseHeaders 不是有效的请求头集合'); }
+  for (const name of [...headers.keys()]) if (isProtectedHeader(name)) headers.delete(name);
+  const callerAccept = headers.get('accept');
+  const preset = CLIENT_PRESETS[p.client.preset];
+  const version = p.client.version.trim() || preset.version;
+  const variables = { ...context, 'client.version': version };
+  // All fourteen selected preset values win over caller headers. Explicit settings follow.
+  for (const [name, value] of Object.entries(preset.headers)) headers.set(name, value);
+  if (preset.userAgent && p.client.version.trim()) headers.set('user-agent', preset.userAgent.replace(`/${preset.version}`, `/${version}`));
+  const set = (name, value, field = name) => {
+    const text = render(value, variables, field);
+    if (text !== undefined && text.trim()) headers.set(name, text);
+  };
+  if (p.headers.acceptMode === 'json') headers.set('accept', 'application/json');
+  else if (p.headers.acceptMode === 'sse') headers.set('accept', 'text/event-stream');
+  else if (p.headers.acceptMode === 'auto') headers.set('accept', callerAccept ?? (stream === true ? 'text/event-stream' : 'application/json'));
+  else set('accept', p.headers.acceptValue, 'headers.acceptValue');
+  if (!headers.has('content-type')) headers.set('content-type', 'application/json');
+  for (const [field, name] of Object.entries({ userAgent: 'user-agent', contentType: 'content-type', anthropicVersion: 'anthropic-version', anthropicBeta: 'anthropic-beta', sessionId: 'x-claude-code-session-id', clientRequestId: 'x-client-request-id' })) {
+    if (field === 'clientRequestId' && p.headers[field] === '{{request.id}}' && headers.has(name)) continue;
+    if (field === 'sessionId' && p.headers[field] === '{{session.id}}' && headers.has(name)) continue;
+    if (p.headers[field]) set(name, p.headers[field], `headers.${field}`);
+  }
+  for (const [index, item] of p.headers.extra.entries()) {
+    if (!item.enabled) continue;
+    if (item.value === null) headers.delete(item.name);
+    else set(item.name, item.value, `headers.extra[${index}].value`);
+  }
+  const upstream = p.upstream;
+  if (upstream.authorizationMode === 'api-key' && upstream.apiKey.trim()) headers.set('x-api-key', upstream.apiKey);
+  else if (upstream.authorizationMode === 'bearer' && upstream.apiKey.trim()) headers.set('authorization', `Bearer ${upstream.apiKey}`);
+  else if (upstream.authorizationMode === 'custom' && upstream.authorizationValue.trim()) headers.set('authorization', upstream.authorizationValue);
+  let size = 0;
+  for (const [name, value] of headers) size += Buffer.byteLength(`${name}: ${value}\r\n`);
+  if (size > HEADER_LIMIT_BYTES) throw new HeaderBuildError('请求头总大小超过限制');
+  return headers;
+}