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

package/src/ua-model-catalog.mjs

@@ -0,0 +1,218 @@
+import * as fsPromises from "node:fs/promises"
+import { constants } from "node:fs"
+import { randomUUID } from "node:crypto"
+import { dirname, isAbsolute, resolve } from "node:path"
+
+const MAX_BYTES = 4 * 1024 * 1024
+const MAX_ENTRIES = 128
+const MAX_MODELS = 2048
+const MAX_ID = 256
+const MAX_NAME = 512
+const TTL = 24 * 60 * 60 * 1000
+const queues = new Map()
+const sources = new Set(["host", "management"])
+const controls = /[\u0000-\u001f\u007f-\u009f]/u
+
+function unsafe() {
+  // Filesystem/JSON errors can contain paths or file contents; never expose them.
+  return Object.assign(new Error("UA model catalog cannot be safely read or written"), { code: "ERR_UA_MODEL_CATALOG" })
+}
+
+function validScope(scope) {
+  return typeof scope === "string" && scope.length === 64 && /^[a-f0-9]+$/.test(scope)
+}
+
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function fields(value, names) {
+  return record(value) && Object.keys(value).length === names.length && names.every(name => Object.hasOwn(value, name))
+}
+
+function text(value, limit) {
+  if (typeof value !== "string" || controls.test(value)) return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 && trimmed.length <= limit ? trimmed : null
+}
+
+function timestamp(value, now) {
+  let date = new Date(NaN)
+  if (typeof value === "string" || typeof value === "number" || value instanceof Date) date = new Date(value)
+  if (!Number.isFinite(date.getTime())) date = new Date(now())
+  if (!Number.isFinite(date.getTime())) throw unsafe()
+  return date.toISOString()
+}
+
+function normalize(input, now) {
+  if (!record(input) || !Array.isArray(input.models) || !sources.has(input.source)) throw unsafe()
+  const models = []
+  const seen = new Set()
+  for (const model of input.models) {
+    if (!record(model)) continue
+    const id = text(model.id, MAX_ID)
+    if (!id || seen.has(id)) continue
+    seen.add(id)
+    models.push({ id, name: text(model.name, MAX_NAME) || id })
+    if (models.length === MAX_MODELS) break
+  }
+  return { models, checkedAt: timestamp(input.checkedAt, now), source: input.source }
+}
+
+function validate(document) {
+  if (!fields(document, ["schemaVersion", "entries"]) || document.schemaVersion !== 1 || !record(document.entries)) throw unsafe()
+  const entries = Object.entries(document.entries)
+  if (entries.length > MAX_ENTRIES) throw unsafe()
+  for (const [scope, entry] of entries) {
+    if (!validScope(scope) || !fields(entry, ["models", "checkedAt", "source"]) || !sources.has(entry.source)) throw unsafe()
+    const date = typeof entry.checkedAt === "string" ? new Date(entry.checkedAt) : new Date(NaN)
+    if (!Number.isFinite(date.getTime()) || date.toISOString() !== entry.checkedAt) throw unsafe()
+    if (!Array.isArray(entry.models) || entry.models.length > MAX_MODELS) throw unsafe()
+    const seen = new Set()
+    for (const model of entry.models) {
+      if (!fields(model, ["id", "name"]) || !model.id || !model.name || text(model.id, MAX_ID) !== model.id || text(model.name, MAX_NAME) !== model.name || seen.has(model.id)) throw unsafe()
+      seen.add(model.id)
+    }
+  }
+  return document
+}
+
+function regular(stat) {
+  if (!stat.isFile() || stat.isSymbolicLink() || !Number.isSafeInteger(stat.size) || stat.size < 0 || stat.size > MAX_BYTES) throw unsafe()
+  return stat
+}
+
+function sameFile(left, right) {
+  if (!left || !right) return left === right
+  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => left[key] === right[key])
+}
+
+function serialize(key, operation) {
+  const previous = queues.get(key) || Promise.resolve()
+  const task = previous.then(operation)
+  const settled = task.then(() => {}, () => {})
+  queues.set(key, settled)
+  return task.finally(() => {
+    if (queues.get(key) === settled) queues.delete(key)
+  })
+}
+
+function encode(entries, scope) {
+  // Reject individually oversized results; otherwise evict strictly by age.
+  if (Buffer.byteLength(JSON.stringify({ schemaVersion: 1, entries: { [scope]: entries[scope] } })) > MAX_BYTES) throw unsafe()
+  const oldest = Object.keys(entries).sort((a, b) => Date.parse(entries[a].checkedAt) - Date.parse(entries[b].checkedAt) || a.localeCompare(b))
+  let remaining = Object.keys(entries).length
+  while (remaining > MAX_ENTRIES) {
+    delete entries[oldest.shift()]
+    remaining--
+  }
+  let json = JSON.stringify({ schemaVersion: 1, entries })
+  while (Buffer.byteLength(json) > MAX_BYTES) {
+    const key = oldest.shift()
+    if (!key) throw unsafe()
+    delete entries[key]
+    json = JSON.stringify({ schemaVersion: 1, entries })
+  }
+  return json
+}
+
+/**
+ * Cache only normalized model names, timestamps, sources and caller-made SHA256 scopes.
+ * IDs are limited to 256 UTF-16 units and names to 512. Invalid names fall back to IDs.
+ * The queue coordinates this module's instances in one process, not other processes.
+ */
+export function createUAModelCatalog(statePath, { io = fsPromises, now = Date.now } = {}) {
+  if (typeof statePath !== "string" || !isAbsolute(statePath) || statePath.includes("\0")) throw unsafe()
+  const path = `${statePath}.models.json`
+  const absolute = resolve(path)
+  const queueKey = process.platform === "win32" ? absolute.toLowerCase() : absolute
+
+  async function inspect() {
+    let stat
+    try {
+      stat = await io.lstat(path)
+    } catch (error) {
+      if (error.code === "ENOENT") return null
+      throw error
+    }
+    return regular(stat)
+  }
+
+  async function load() {
+    const stat = await inspect()
+    if (!stat) return { stat: null, document: { schemaVersion: 1, entries: {} } }
+    // O_NOFOLLOW is used where supported; lstat/fstat checks also cover Windows.
+    const handle = await io.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+    try {
+      if (!sameFile(stat, regular(await handle.stat()))) throw unsafe()
+      // Read at most the observed length plus one byte, never an unbounded readFile.
+      const buffer = Buffer.allocUnsafe(stat.size + 1)
+      let length = 0
+      while (length < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, length, Math.min(64 * 1024, buffer.length - length), null)
+        if (!bytesRead) break
+        length += bytesRead
+      }
+      if (length !== stat.size || !sameFile(stat, regular(await handle.stat())) || !sameFile(stat, await inspect())) throw unsafe()
+      const json = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length))
+      return { stat, document: validate(JSON.parse(json)) }
+    } finally {
+      await handle.close()
+    }
+  }
+
+  async function guarded(scope, operation) {
+    if (!validScope(scope)) throw unsafe()
+    try {
+      return await serialize(queueKey, operation)
+    } catch {
+      throw unsafe()
+    }
+  }
+
+  return {
+    path,
+    async read(scope) {
+      return guarded(scope, async () => {
+        const { document } = await load()
+        const entry = document.entries[scope]
+        if (!entry) return null
+        const clock = now()
+        if (!Number.isFinite(clock)) throw unsafe()
+        return clock - Date.parse(entry.checkedAt) >= TTL ? null : entry
+      })
+    },
+    async write(scope, input) {
+      return guarded(scope, async () => {
+        const entry = normalize(input, now)
+        const original = await load()
+        const entries = { ...original.document.entries, [scope]: entry }
+        const json = encode(entries, scope)
+        await io.mkdir(dirname(path), { recursive: true, mode: 0o700 })
+        const temporary = `${path}.${randomUUID()}.tmp`
+        let handle
+        let owned = false
+        try {
+          handle = await io.open(temporary, "wx", 0o600)
+          owned = true
+          await handle.writeFile(json, "utf8")
+          await handle.sync()
+          await handle.close()
+          handle = null
+          // Revalidate immediately before replacing; this is not cross-process CAS.
+          const current = await load()
+          if (!sameFile(original.stat, current.stat)) throw unsafe()
+          await io.rename(temporary, path)
+          owned = false
+          return entry
+        } finally {
+          try {
+            if (handle) await handle.close()
+          } finally {
+            if (owned) await io.unlink(temporary)
+          }
+        }
+      })
+    },
+  }
+}

package/src/ua-plugin.mjs

@@ -0,0 +1,207 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { AsyncResource } from 'node:async_hooks'
+import { readFile } from 'node:fs/promises'
+import { dirname, join, isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createUAStore } from './ua-store.mjs'
+import { createUAService } from './ua-service.mjs'
+import { createUAModelCatalog } from './ua-model-catalog.mjs'
+import { createUATransport, protocolForModel, SDK_BY_PROTOCOL, apiBase, discoverUA, siteRoot, modelQueryScope } from './ua-runtime.mjs'
+import { startSetupServer } from './setup-server.mjs'
+import { createProfileStore } from './store.mjs'
+import { createAccountManager } from './accounts.mjs'
+import { ensureCheckinScheduler } from './scheduler.mjs'
+import { isDeepStrictEqual } from 'node:util'
+import { createPlugin as createLegacyPlugin } from './plugin.mjs'
+import { resolveProfilePath } from './runtime.mjs'
+
+const PREFIX = 'ua-pro:connection:'
+const observed = new Map()
+const stores = new Map()
+const modelRoutes = new Map()
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 20)
+export function uaStorePath(options = {}, env = process.env) {
+  const path = options.uaFile ?? env.UA_PRO_FILE ?? fileURLToPath(new URL('../runtime/ua-pro.json', import.meta.url))
+  if (typeof path !== 'string' || !isAbsolute(path)) throw new Error('UA PRO 配置路径必须为绝对路径')
+  return path
+}
+function sharedStore(path) {
+  if (!stores.has(path)) stores.set(path, createUAStore(path))
+  return stores.get(path)
+}
+function providerOf(connection) { return connection.independent && connection.siteId ? `ua-pro-${connection.siteId}` : 'ua-pro' }
+function safeModel(model) { return typeof model === 'string' && model && !/[\x00-\x1f\x7f]/.test(model) }
+
+export async function createUAPlugin(input = {}, options = {}, dependencies = {}, siteId = '') {
+  const allowed = ['uaFile', 'profileFile', 'accountBindings', 'baseURL', 'userAgent', 'headers', 'models', 'parameters', 'searches']
+  if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(key => !allowed.includes(key))) throw new Error('UA PRO 插件选项无效')
+  const path = uaStorePath(options)
+  const store = dependencies.uaStore ?? sharedStore(path)
+  await store.initialize()
+  const id = siteId ? `ua-pro-${siteId}` : 'ua-pro'
+  const legacyStore = dependencies.legacyStore ?? createProfileStore(resolveProfilePath({ configPath: options.profileFile }))
+  const accountManager = dependencies.accountManager ?? createAccountManager({ path: join(dirname(path), 'accounts.json') })
+  if (input.magpie && !siteId) (dependencies.startScheduler ?? ensureCheckinScheduler)({ accountManager, stateDirectory: join(dirname(path), 'schedule-claims'), onError: () => {} })
+  const fetchImpl = dependencies.fetchImpl ?? globalThis.fetch
+  const modelCatalog = dependencies.modelCatalog ?? createUAModelCatalog(store.path)
+  const contexts = new Map()
+  const contextHeader = `x-magpie-ua-pro-context-${randomUUID()}`
+  const auths = async () => {
+    if (dependencies.readHostAuth) return dependencies.readHostAuth()
+    if (!input.directory) return {}
+    try { const value = JSON.parse(await readFile(join(input.directory, 'plugin-auth.json'), 'utf8')); if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(); return value }
+    catch (error) { if (error.code === 'ENOENT') return {}; throw new Error('无法读取宿主账号，停止操作以保护已有凭据') }
+  }
+  const readAuth = async (provider, account) => (await auths())[account || provider]
+  const register = async connection => {
+    if (!input.client?.auth?.set || connection.auth?.source === 'host') return
+    const provider = providerOf(connection)
+    const account = `${provider}#${digest(connection.id)}`
+    const existing = (await auths())[account]
+    const key = PREFIX + connection.id
+    if (existing && existing.key !== key) throw new Error('目标宿主账号已被其他凭据占用')
+    if (existing) return
+    const response = await input.client.auth.set({ path: { id: account }, body: { type: 'api', key, accountId: connection.name, metadata: { uaConnectionId: connection.id } } })
+    if (response?.data !== true) throw new Error('宿主未确认连接注册，请重载并核对')
+  }
+  const routeKey = scope => `${store.path}:${scope}`
+  const modelFetchFor = scope => {
+    const key = routeKey(scope)
+    const saved = modelRoutes.get(key)
+    if (saved && Date.now() - saved.at <= 15 * 60 * 1000) return saved.fetch
+    modelRoutes.delete(key)
+    return fetchImpl
+  }
+  const service = createUAService({ store, legacyStore, accountManager, fetchImpl, readAuth, modelCatalog, modelFetchFor, onConnectionSaved: input.client?.auth?.set ? register : undefined,
+    runtime: () => ({ mode: input.magpie ? 'host' : 'standalone', observed: [...observed.values()].filter(item => item.provider === id) }) })
+  let declared = {}
+  const getNativeConnection = async (auth, provider = {}) => {
+    if (auth?.type !== 'api' || typeof auth.key !== 'string' || !auth.key.trim()) return null
+    const snapshot = await store.snapshot({ secrets: true })
+    const selected = auth.metadata?.uaConnectionId ?? (auth.key.startsWith(PREFIX) ? auth.key.slice(PREFIX.length) : null)
+    if (selected) {
+      const connection = snapshot.connections.find(item => item.id === selected)
+      if (!connection || providerOf(connection) !== id || connection.enabled === false) throw new Error('此连接已移除、停用或属于其他站点')
+      return connection
+    }
+    const configuredSite = siteId ? snapshot.connections.find(item => item.siteId === siteId && item.independent) : null
+    const baseURL = configuredSite?.baseURL ?? auth.metadata?.baseURL ?? auth.metadata?.endpoint ?? provider.options?.baseURL ?? provider.api ?? declared.api ?? options.baseURL
+    if (!baseURL) throw new Error('请为当前账号填写上游 Base URL')
+    siteRoot(baseURL)
+    const connectionId = `host.${digest([id, baseURL, auth.key])}`
+    let connection = snapshot.connections.find(item => item.id === connectionId)
+    if (!connection) {
+      const all = await auths()
+      const scope = input.magpie?.account?.(id)
+      const matches = Object.entries(all).filter(([slot, saved]) => (slot === id || slot.startsWith(id + '#')) && saved.type === 'api' && saved.key === auth.key
+        && (saved.metadata?.baseURL ?? saved.metadata?.endpoint ?? baseURL) === (auth.metadata?.baseURL ?? auth.metadata?.endpoint ?? baseURL))
+      const account = scope && all[scope]?.key === auth.key ? scope : matches.length === 1 ? matches[0][0] : matches.length === 0 && !Object.keys(all).length ? id : null
+      if (!account) throw new Error('无法唯一识别当前宿主账号，请从明确的账号入口重新打开')
+      const result = await store.saveConnection({ connection: { id: connectionId, name: auth.accountId ?? `${id} 账号`, enabled: true, siteId, independent: Boolean(siteId),
+        baseURL, protocol: auth.metadata?.protocol ?? 'auto', apiPaths: {}, modelProtocols: {}, models: [],
+        auth: { source: 'host', mode: 'api-key', provider: id, account, key: '', value: '' }, modelBindings: {} } })
+      connection = result.connection
+    }
+    return connection
+  }
+  const executeWithAuth = (auth, connection, fallback = readAuth) => async (provider, account) => connection.auth.source === 'host' && connection.auth.provider === provider && connection.auth.account === account
+    ? { ...auth, metadata: { baseURL: connection.baseURL, ...auth.metadata } } : fallback(provider, account)
+  const management = async () => {
+    const account = input.magpie?.account?.(id)
+    const originalAuth = account ? (await auths())[account] : undefined
+    const hostBinding = originalAuth ? { account, selected: originalAuth.metadata?.newApiAccountId ?? null, changed: false } : undefined
+    const session = await (dependencies.startSetup ?? startSetupServer)({ store: legacyStore, accountManager, hostBinding, uaService: service, finishOnSave: false })
+    return { url: new URL('pro', session.url).href, method: 'auto', instructions: '在 UA PRO 中管理连接和模板；保存版本与应用连接分开。完成后关闭页面返回 Magpie。',
+      async callback(_code, { signal } = {}) {
+        let stop
+        try {
+          const result = await (signal ? Promise.race([session.finished, new Promise(resolve => { stop = () => resolve({ status: 'cancelled' }); if (signal.aborted) stop(); else signal.addEventListener('abort', stop, { once: true }) })]) : session.finished)
+          if (result.status === 'timeout') return { type: 'failed', error: '配置会话已超时；已保存的更改保留' }
+          if (signal?.aborted) return { type: 'failed', error: '配置已取消；此前保存的更改保留' }
+          if (hostBinding?.changed) {
+            const current = (await auths())[account]
+            if (!isDeepStrictEqual(current, originalAuth)) return { type: 'failed', error: '宿主账号已改变，余额绑定未写入；请重新打开核对' }
+            const updated = { ...current, metadata: { ...current.metadata, newApiAccountId: hostBinding.selected ?? '' } }
+            const written = await input.client?.auth?.set?.({ path: { id: account }, body: updated })
+            if (written?.data !== true || !isDeepStrictEqual((await auths())[account], updated)) return { type: 'failed', error: '宿主未确认余额绑定保存' }
+          }
+          return { type: 'success' }
+        } finally { if (stop) signal.removeEventListener('abort', stop); await session.close() }
+      } }
+  }
+  const usageHooks = await createLegacyPlugin({ ...input, magpie: undefined }, { profileFile: legacyStore.path, ...(options.accountBindings ? { accountBindings: options.accountBindings } : {}) }, { store: legacyStore, accountManager })
+  return {
+    async config(config) {
+      const snapshot = await store.snapshot({ secrets: true })
+      for (const connection of snapshot.connections.filter(item => item.enabled && providerOf(item) === id)) await register(connection)
+      config.provider ??= {}
+      config.provider[id] ??= { name: siteId ? `UA PRO · ${siteId}` : 'UA PRO', npm: '@ai-sdk/openai-compatible', models: {} }
+      declared = config.provider[id]
+    },
+    auth: {
+      provider: id,
+      methods: [{ type: 'api', label: '连接上游 API key', placeholder: '此上游的模型 API key', prompts: [{ type: 'text', key: 'baseURL', message: '上游 Base URL', placeholder: 'https://your-service.example', validate(value) { try { siteRoot(value); return undefined } catch { return '请填写有效的 HTTPS Base URL（本机可用 HTTP）' } } }] },
+        { type: 'oauth', label: '打开 UA PRO 管理', authorize: management }],
+      async loader(getAuth, provider) {
+        const auth = await getAuth()
+        const connection = await getNativeConnection(auth, provider)
+        if (!connection) return {}
+        return { baseURL: siteRoot(connection.baseURL) + '/v1', apiKey: '',
+          fetch: async (url, init = {}) => {
+            const current = await getAuth()
+            const bound = await getNativeConnection(current, provider)
+            if (!bound) throw new Error('当前账号未登录')
+            const headers = new Headers(init.headers)
+            const token = headers.get(contextHeader)
+            const host = contexts.get(token)?.value ?? {}
+            contexts.delete(token)
+            headers.delete(contextHeader)
+            const transport = createUATransport({ getSnapshot: () => store.snapshot({ secrets: true }), getConnection: snapshot => snapshot.connections.find(item => item.id === bound.id),
+              readAuth: executeWithAuth(current, bound), fetchImpl, getContext: () => host,
+              observe: value => { observed.set(`${id}:${bound.id}`, { ...value, provider: id, at: new Date().toISOString() }); if (observed.size > 256) observed.delete(observed.keys().next().value) } })
+            return transport(url, { ...init, headers })
+          } }
+      },
+      usage: usageHooks.auth.usage,
+      checkin: usageHooks.auth.checkin,
+    },
+    provider: { id, async models(provider = {}, { auth } = {}) {
+      const connection = await getNativeConnection(auth, provider)
+      if (!connection) return provider.models ?? {}
+      const queryAuth = executeWithAuth(auth, connection)
+      if (input.magpie) {
+        const key = routeKey(await modelQueryScope(connection, queryAuth))
+        // Keep the host's account proxy context for management callbacks. Never
+        // bind credentials here; queryUAModels resolves them for each request.
+        modelRoutes.delete(key)
+        modelRoutes.set(key, { at: Date.now(), fetch: AsyncResource.bind((url, init) => fetchImpl(url, init)) })
+        if (modelRoutes.size > 128) modelRoutes.delete(modelRoutes.keys().next().value)
+      }
+      const list = await discoverUA(connection, { fetchImpl, readAuth: queryAuth, catalog: modelCatalog, source: 'host' })
+      return Object.fromEntries(list.filter(item => safeModel(item.id)).map(item => {
+        const protocol = protocolForModel(connection, item.id)
+        const existing = provider.models?.[item.id] ?? {}
+        return [item.id, { ...existing, ...item, api: { ...(existing.api ?? {}), id: existing.api?.id ?? item.id, url: apiBase(connection, protocol), npm: SDK_BY_PROTOCOL[protocol] },
+          provider: { api: apiBase(connection, protocol), npm: SDK_BY_PROTOCOL[protocol] } }]
+      }))
+    } },
+    async 'chat.headers'(context, output) {
+      if (context?.model?.providerID !== id && context?.provider?.info?.id !== id) return
+      const now = Date.now()
+      for (const [key, item] of contexts) if (now - item.at > 60000) contexts.delete(key)
+      if (contexts.size >= 2048) contexts.delete(contexts.keys().next().value)
+      const token = randomUUID()
+      contexts.set(token, { at: now, value: { sessionID: context.sessionID, model: context.model?.id ?? context.model?.api?.id } })
+      output.headers[contextHeader] = token
+    },
+  }
+}
+
+export async function createUASite(input, options, slot) {
+  const store = sharedStore(uaStorePath(options))
+  await store.initialize()
+  const state = await store.snapshot()
+  const ids = [...new Set(state.connections.filter(item => item.independent && item.siteId).map(item => item.siteId))]
+  const id = ids[slot]
+  return id ? createUAPlugin(input, options, { uaStore: store }, id) : {}
+}

package/src/ua-runtime.mjs

@@ -0,0 +1,229 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { transformRequest } from './ua-transform.mjs'
+import { resolveTemplate } from './ua-store.mjs'
+
+import { SDK_BY_PROTOCOL, PATHS, protocolForModel, siteRoot, apiBase, operationURL } from '../lib/ua-protocol.mjs'
+export { SDK_BY_PROTOCOL, protocolForModel, siteRoot, apiBase, operationURL } from '../lib/ua-protocol.mjs'
+const authHeaders = ['authorization', 'x-api-key', 'x-goog-api-key', 'api-key', 'cookie', 'proxy-authorization']
+const err = (message, status = 400) => Object.assign(new Error(message), { status })
+
+export function operationForURL(input) {
+  const path = new URL(input instanceof Request ? input.url : input).pathname
+  if (/\/messages\/count_tokens$/.test(path)) return { protocol: 'anthropic', operation: 'count_tokens' }
+  if (/\/messages$/.test(path)) return { protocol: 'anthropic', operation: 'messages' }
+  if (/\/responses$/.test(path)) return { protocol: 'responses', operation: 'responses' }
+  if (/\/chat\/completions$/.test(path)) return { protocol: 'chat-completions', operation: 'chat/completions' }
+  const gemini = /\/models\/(.+):(generateContent|streamGenerateContent|countTokens)$/.exec(path)
+  if (gemini) return { protocol: 'gemini', operation: gemini[2], model: decodeURIComponent(gemini[1]) }
+  throw err('请求路径不是支持的模型操作')
+}
+
+async function credential(connection, readAuth) {
+  let auth = connection.auth ?? {}
+  if (auth.source === 'host') {
+    const current = await readAuth?.(auth.provider, auth.account)
+    if (current?.type !== 'api' || typeof current.key !== 'string' || !current.key.trim()) throw err('当前宿主账号缺少 API key，请重新登录', 401)
+    const endpoint = current.metadata?.baseURL ?? current.metadata?.endpoint
+    if (!endpoint || new URL(endpoint).href.replace(/\/+$/, '') !== new URL(connection.baseURL).href.replace(/\/+$/, '')) throw err('宿主账号地址已改变，此旧连接不能使用当前凭据', 409)
+    auth = { ...auth, key: current.key }
+  }
+  if (['api-key', 'bearer'].includes(auth.mode) && !auth.key?.trim()) throw err('此连接缺少 API key', 400)
+  if (auth.mode === 'custom' && !auth.value?.trim()) throw err('此连接缺少自定义 Authorization', 400)
+  return auth
+}
+
+export function addAuthentication(headers, auth, protocol) {
+  const output = new Headers(headers)
+  for (const name of authHeaders) output.delete(name)
+  for (const name of [...output.keys()]) if (name.startsWith('x-magpie-')) output.delete(name)
+  if (auth.mode === 'bearer') output.set('authorization', `Bearer ${auth.key}`)
+  else if (auth.mode === 'custom') output.set('authorization', auth.value)
+  else if (auth.mode === 'api-key') output.set(protocol === 'anthropic' ? 'x-api-key' : protocol === 'gemini' ? 'x-goog-api-key' : 'authorization', ['responses', 'chat-completions'].includes(protocol) ? `Bearer ${auth.key}` : auth.key)
+  return output
+}
+
+function bodyModel(init) {
+  try {
+    const value = typeof init.body === 'string' ? JSON.parse(init.body) : ArrayBuffer.isView(init.body) && init.body.byteLength <= 2 * 1024 * 1024 ? JSON.parse(new TextDecoder().decode(init.body)) : undefined
+    return typeof value?.model === 'string' ? value.model : ''
+  } catch { return '' }
+}
+
+export async function prepareUpstream({ snapshot, connection, input, init = {}, context = {}, readAuth, template, templateRef, protocol: forcedProtocol, operation: forcedOperation, model: chosenModel }) {
+  if (!connection || connection.enabled === false) throw err('连接不存在或已停用', 404)
+  const incoming = new URL(input instanceof Request ? input.url : input)
+  const root = new URL(siteRoot(connection.baseURL))
+  const prefixes = [...new Set(Object.values(PATHS).concat(Object.values(connection.apiPaths ?? {})))].map(path => new URL(root.href.replace(/\/$/, '') + path.replace(/\/$/, '') + '/'))
+  if (incoming.origin !== root.origin || incoming.username || incoming.password || incoming.hash || !prefixes.some(prefix => incoming.pathname.startsWith(prefix.pathname))) throw err('拒绝发送凭据到此连接以外的路径')
+  const detected = operationForURL(input)
+  const protocol = forcedProtocol ?? detected.protocol
+  const operation = forcedOperation ?? detected.operation
+  if (detected.protocol !== protocol || detected.operation !== operation) throw err('请求协议与选定测试协议不匹配')
+  const model = chosenModel || context.model || bodyModel(init) || detected.model || ''
+  const target = new URL(operationURL(connection, protocol, operation, model || detected.model || ''))
+  target.search = incoming.search
+  if (protocol === 'gemini') target.searchParams.delete('key')
+  const selected = template !== undefined ? template : templateRef ? snapshot.templates.find(item => item.id === templateRef.id && item.revision === templateRef.revision) : resolveTemplate(snapshot, connection, protocol, model)
+  if (templateRef && !selected) throw err('指定模板版本不存在', 404)
+  const auth = await credential(connection, readAuth)
+  const scope = createHash('sha256').update(JSON.stringify([connection.baseURL, auth.mode, auth.key ?? '', auth.value ?? ''])).digest('hex')
+  const destination = target.href === incoming.href ? input : input instanceof Request ? new Request(target.href, input) : target.href
+  const transformed = await transformRequest({ template: selected, protocol, operation, input: destination, init,
+    context: { ...context, baseURL: connection.baseURL, credentialScope: scope, model: model || detected.model || '', requestId: context.requestId ?? randomUUID() } })
+  transformed.init = { ...transformed.init, headers: addAuthentication(transformed.init.headers, auth, protocol), redirect: 'manual' }
+  const result = { ...transformed, protocol, operation, model, generation: snapshot.generation, connectionId: connection.id }
+  Object.defineProperty(result, 'credentialValues', { value: [auth.key, auth.value].filter(Boolean), enumerable: false })
+  return result
+}
+
+export function createUATransport({ getSnapshot, getConnection, readAuth, fetchImpl = globalThis.fetch, getContext = () => ({}), observe = () => {} }) {
+  return async (input, init = {}) => {
+    const snapshot = await getSnapshot()
+    const connection = await getConnection(snapshot)
+    const prepared = await prepareUpstream({ snapshot, connection, input, init, context: await getContext(input, init), readAuth })
+    observe({ connectionId: connection.id, generation: snapshot.generation, templateId: prepared.summary?.templateId, revision: prepared.summary?.revision })
+    return fetchImpl(prepared.input, prepared.init)
+  }
+}
+
+export async function boundedResponse(response, { limit = 1024 * 1024, signal } = {}) {
+  if (Number(response.headers.get('content-length')) > limit) { await response.body?.cancel(); throw err('响应超过允许大小') }
+  const reader = response.body?.getReader()
+  if (!reader) return ''
+  let size = 0
+  const chunks = []
+  const stop = () => { void reader.cancel().catch(() => {}) }
+  signal?.addEventListener('abort', stop, { once: true })
+  try {
+    for (;;) {
+      signal?.throwIfAborted()
+      const { done, value } = await reader.read()
+      signal?.throwIfAborted()
+      if (done) break
+      size += value.byteLength
+      if (size > limit) throw err('响应超过允许大小')
+      chunks.push(Buffer.from(value))
+    }
+    return Buffer.concat(chunks).toString('utf8')
+  } finally {
+    signal?.removeEventListener('abort', stop)
+    stop()
+    reader.releaseLock()
+  }
+}
+
+export async function discoverUA(connection, options = {}) {
+  if (connection.models?.length) return connection.models.map(id => ({ id, name: id }))
+  return queryUAModels(connection, options)
+}
+
+export async function modelQueryScope(connection, readAuth) {
+  return (await prepareModelQuery(connection, readAuth)).scope
+}
+
+async function prepareModelQuery(connection, readAuth) {
+  const auth = await credential(connection, readAuth)
+  const protocol = protocolForModel(connection)
+  const headers = addAuthentication({ accept: 'application/json', 'anthropic-version': '2023-06-01' }, auth, protocol)
+  const url = apiBase(connection, protocol) + '/models'
+  // Scope the discovery record to the actual request, including the credential.
+  // Responses and auto may share a list only when URL and authentication agree.
+  const scope = createHash('sha256').update(JSON.stringify([url, [...headers], auth.source, auth.provider ?? '', auth.account ?? ''])).digest('hex')
+  return { url, headers, protocol, scope, secrets: [auth.key, auth.value].filter(Boolean) }
+}
+
+function catalogResult(entry) {
+  return { models: entry.models, count: entry.models.length, checkedAt: entry.checkedAt, source: `${entry.source}-cache`, cached: true, stale: true }
+}
+
+export async function readModelCatalog(connection, { catalog, readAuth } = {}) {
+  if (!catalog) return null
+  try {
+    const query = await prepareModelQuery(connection, readAuth)
+    const entry = await catalog.read(query.scope)
+    return entry ? catalogResult(entry) : null
+  } catch { return null }
+}
+
+function modelNetworkError(cause) {
+  const codes = []
+  for (let current = cause, depth = 0; current && depth < 4; current = current.cause, depth++) {
+    if (typeof current.code === 'string') codes.push(current.code)
+  }
+  const known = [
+    ['dns', ['ENOTFOUND', 'EAI_AGAIN', 'DNSLookupError'], '无法解析上游域名，请检查地址、DNS 或代理设置'],
+    ['connection-refused', ['ECONNREFUSED', 'ConnectionRefused'], '上游或代理拒绝连接，请检查服务地址和代理设置'],
+    ['connection-reset', ['ECONNRESET', 'EPIPE', 'ConnectionClosed', 'UND_ERR_SOCKET'], '上游或代理中断了连接，请检查网络和代理设置'],
+    ['timeout', ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT'], '连接上游超时，请检查网络和代理设置'],
+    ['tls', ['CERT_HAS_EXPIRED', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_SIGNATURE_FAILURE'], '上游 TLS 证书验证失败，请检查证书或代理配置'],
+  ]
+  const [code, , message] = known.find(([, matches]) => codes.some(value => matches.includes(value))) ?? ['network', [], '无法连接上游，请检查网络或代理设置']
+  return Object.assign(err(message), { code, catalogFallback: true })
+}
+
+async function fetchModelList(query, fetchImpl, signal) {
+  let response
+  try { response = await fetchImpl(query.url, { method: 'GET', headers: query.headers, signal, redirect: 'manual' }) }
+  catch (error) { signal.throwIfAborted(); throw modelNetworkError(error) }
+  if (!response.ok) {
+    void response.body?.cancel().catch(() => {})
+    const error = Object.assign(err(`模型列表返回 HTTP ${response.status}`, response.status), { code: 'upstream-http', catalogFallback: response.status >= 500 })
+    if (response.status === 401) error.signIn = 'expired'
+    throw error
+  }
+  let text
+  try { text = await boundedResponse(response, { signal }) }
+  catch (error) { signal.throwIfAborted(); if (error.status) throw error; throw modelNetworkError(error) }
+  let data
+  try { data = JSON.parse(text) } catch { throw Object.assign(err('模型列表不是有效的 JSON'), { code: 'invalid-model-response' }) }
+  const list = query.protocol === 'gemini' && Array.isArray(data?.models)
+    ? data.models.map(item => ({ id: typeof item?.name === 'string' ? item.name.replace(/^models\//, '') : '', display_name: item?.displayName, limit: { context: item?.inputTokenLimit, output: item?.outputTokenLimit } }))
+    : data?.data
+  if (!Array.isArray(list)) throw Object.assign(err('模型列表格式无效'), { code: 'invalid-model-response' })
+  const models = new Map()
+  const safeText = (value, limit = 512) => typeof value === 'string' && value.trim() && value.trim().length <= limit && !/[\x00-\x1f\x7f-\x9f]/.test(value) && !query.secrets.some(secret => value.includes(secret))
+  for (const item of list) {
+    if (!safeText(item?.id, 256)) continue
+    const id = item.id.trim()
+    if (models.has(id)) continue
+    const name = item.display_name ?? item.name
+    models.set(id, { id, name: safeText(name) ? name.trim() : id, ...(item.limit && typeof item.limit === 'object' ? { limit: item.limit } : {}) })
+    if (models.size > 2048) throw Object.assign(err('模型列表超过 2048 个，请使用手填模型缩小范围'), { code: 'invalid-model-response' })
+  }
+  return [...models.values()]
+}
+
+export async function lookupUAModels(connection, { readAuth, fetchImpl = globalThis.fetch, modelFetchFor, signal = AbortSignal.timeout(15000), catalog, source = 'management', allowCached = false } = {}) {
+  signal.throwIfAborted()
+  const query = await prepareModelQuery(connection, readAuth)
+  let models
+  try {
+    const send = await modelFetchFor?.(query.scope) ?? fetchImpl
+    signal.throwIfAborted()
+    models = await fetchModelList(query, send, signal)
+    signal.throwIfAborted()
+  }
+  catch (error) {
+    const timedOut = signal.aborted && signal.reason?.name === 'TimeoutError'
+    if (signal.aborted && !timedOut) signal.throwIfAborted()
+    if (timedOut) error = Object.assign(err('模型列表读取超时，请检查网络和代理设置', 408), { code: 'timeout', catalogFallback: true })
+    if (allowCached && error.catalogFallback && catalog) {
+      const entry = await catalog.read(query.scope).catch(() => null)
+      if (signal.aborted && !timedOut) signal.throwIfAborted()
+      if (entry) return { ...catalogResult(entry), refreshError: { code: error.code, message: error.message } }
+    }
+    throw error
+  }
+  const checkedAt = new Date().toISOString()
+  let catalogWarning
+  if (catalog) {
+    try { await catalog.write(query.scope, { models: models.map(({ id, name }) => ({ id, name })), checkedAt, source }) }
+    catch { catalogWarning = '模型目录未能保存，其他管理会话暂时无法共享本次结果；请检查目录权限或缓存文件' }
+  }
+  return { models, count: models.length, checkedAt, source: 'upstream', cached: false, stale: false, ...(catalogWarning ? { catalogWarning } : {}) }
+}
+
+export async function queryUAModels(connection, options = {}) {
+  const result = await lookupUAModels(connection, { ...options, allowCached: false })
+  return result.models
+}