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

package/src/plugin.mjs

@@ -0,0 +1,344 @@
+import { createProfileStore } from './store.mjs';
+import { startSetupServer } from './setup-server.mjs';
+import { resolveProfilePath } from './runtime.mjs';
+import { createUAStore } from './ua-store.mjs';
+import { createUAService } from './ua-service.mjs';
+import { createTransport } from './transport.mjs';
+import { normalizeProfile } from './profile.mjs';
+import { connectionProfile, createModelDiscovery, modelRecords, AUTH_MARKER } from './connection.mjs';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createAccountManager } from './accounts.mjs';
+import { ensureCheckinScheduler } from './scheduler.mjs';
+import { createConnectionDiagnostics } from './diagnostics.mjs';
+import { createAccountProfileStore } from './account-profile.mjs';
+import { isDeepStrictEqual } from 'node:util';
+import { pluginOptions, optionProfile } from './options.mjs';
+import { accountUsage, accountCheckin } from './account-usage.mjs';
+
+export const PROVIDER_ID = 'claude-code-ua';
+function modelsFor(profile) {
+  return modelRecords(profile);
+}
+
+function npmFor(profile) {
+  return '@ai-sdk/anthropic';
+}
+
+function waitForSetup(session, signal) {
+  if (signal?.aborted) return Promise.resolve({ status: 'cancelled' });
+  if (!signal) return session.finished;
+  return new Promise((resolve, reject) => {
+    const abort = () => resolve({ status: 'cancelled' });
+    signal.addEventListener('abort', abort, { once: true });
+    session.finished.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+  });
+}
+
+export async function createPlugin(input, rawOptions, dependencies = {}) {
+  const options = pluginOptions(rawOptions);
+  const store = dependencies.store ?? createProfileStore(resolveProfilePath({ configPath: options.profileFile }));
+  const startSetup = dependencies.startSetup ?? startSetupServer;
+  const accountManager = dependencies.accountManager ?? createAccountManager({ path: join(dirname(store.path), 'accounts.json'), fetchImpl: dependencies.accountFetch ?? globalThis.fetch });
+  const seed = optionProfile(options);
+  if (input?.magpie) {
+    const startScheduler = dependencies.startScheduler ?? ensureCheckinScheduler;
+    startScheduler({ accountManager, stateDirectory: join(dirname(store.path), 'schedule-claims'),
+      onError: (message) => input.client?.app?.log?.({ body: { service: 'claude-code-ua', level: 'warn', message } }),
+    });
+  }
+  const discoverModels = createModelDiscovery({ fetchImpl: dependencies.fetchImpl ?? globalThis.fetch });
+  const checkConnection = createConnectionDiagnostics({ fetchImpl: dependencies.fetchImpl ?? globalThis.fetch });
+  const readProfile = async () => {
+    const profile = await store.load();
+    return profile ? normalizeProfile(profile) : null;
+  };
+  let declaredProvider = options.baseURL ? { api: seed.upstream.baseUrl } : {};
+  let hostModelsExplicit = false;
+  let generatedModels = {};
+  let activeSetup;
+  let startingSetup;
+  const contextHeader = `x-magpie-profile-context-${randomBytes(12).toString('hex')}`;
+  const contexts = new Map();
+
+  function extractHostContext(headers) {
+    const token = headers.get(contextHeader);
+    headers.delete(contextHeader);
+    const saved = contexts.get(token);
+    contexts.delete(token);
+    return saved?.value ?? {};
+  }
+
+  async function recordConfigured() {
+    if (!input?.client?.auth?.set) return;
+    await input.client.auth.set({ path: { id: PROVIDER_ID }, body: { type: 'api', key: AUTH_MARKER, metadata: { profileFile: store.path } } });
+  }
+
+  async function boundAccount(getAuth) {
+    const auth = typeof getAuth === 'function' ? await getAuth() : null;
+    const fromAuth = auth?.metadata?.newApiAccountId;
+    if (typeof fromAuth === 'string') return fromAuth.trim() || null;
+    const slot = input?.magpie?.account?.(PROVIDER_ID);
+    return typeof slot === 'string' && Object.hasOwn(options.accountBindings, slot) ? options.accountBindings[slot] : null;
+  }
+
+  async function currentHostAuth(account = input?.magpie?.account?.(PROVIDER_ID) ?? PROVIDER_ID) {
+    try {
+      const all = dependencies.readHostAuth ? await dependencies.readHostAuth() : input?.directory ? JSON.parse(await readFile(join(input.directory, 'plugin-auth.json'), 'utf8')) : {};
+      return all[account] ? structuredClone(all[account]) : null;
+    } catch (error) {
+      if (error.code === 'ENOENT') return null;
+      throw new Error('无法读取当前登录信息，已停止操作以保留原凭据');
+    }
+  }
+
+  async function ensureAuthMarker() {
+    if (!input?.client?.auth?.set) return;
+    let auth;
+    try {
+      if (dependencies.readHostAuth) auth = await dependencies.readHostAuth();
+      else {
+        if (!input.directory) throw new Error();
+        auth = JSON.parse(await readFile(join(input.directory, 'plugin-auth.json'), 'utf8'));
+      }
+      if (!auth || typeof auth !== 'object' || Array.isArray(auth)) throw new Error();
+    } catch (error) {
+      if (error.code === 'ENOENT') auth = {};
+      else throw new Error('无法检查宿主认证记录；拒绝启用 Provider，避免使用 SDK 默认上游');
+    }
+    if (!Object.hasOwn(auth, PROVIDER_ID)) await recordConfigured();
+  }
+
+  const uaStore = dependencies.uaStore ?? createUAStore(join(dirname(store.path), 'ua-pro.json'));
+  const uaService = dependencies.uaService ?? createUAService({
+    store: uaStore, legacyStore: store, accountManager,
+    readAuth: (provider, account) => currentHostAuth(account || provider),
+    fetchImpl: dependencies.fetchImpl ?? globalThis.fetch,
+  });
+
+  async function setupSession() {
+    if (activeSetup) return activeSetup;
+    if (startingSetup) return startingSetup;
+    startingSetup = startSetup({ store, accountManager, checkConnection, uaService, finishOnSave: false }).then((session) => {
+      activeSetup = session;
+      session.finished.finally(() => {
+        if (activeSetup === session) activeSetup = undefined;
+      }).catch(() => {});
+      return session;
+    }).finally(() => { startingSetup = undefined; });
+    return startingSetup;
+  }
+
+  // The retired first-load option remains accepted, but setup is now explicit.
+  // Opening management must never manufacture a signed-in legacy account.
+
+  return {
+    async config(config) {
+      const profile = await readProfile();
+      if (profile) await ensureAuthMarker();
+      config.provider ??= {};
+      hostModelsExplicit = Object.hasOwn(config.provider[PROVIDER_ID] ?? {}, 'models');
+      generatedModels = options.models ? structuredClone(options.models) : profile ? modelsFor(profile) : {};
+      const defaults = {
+        name: 'Claude Code Profile',
+        npm: npmFor(profile),
+        searches: options.searches ?? false,
+        models: structuredClone(generatedModels),
+        ...(profile ? { api: profile.upstream.baseUrl } : options.baseURL ? { api: seed.upstream.baseUrl } : {}),
+      };
+      config.provider[PROVIDER_ID] ??= {};
+      for (const [key, value] of Object.entries(defaults)) config.provider[PROVIDER_ID][key] ??= value;
+      declaredProvider = config.provider[PROVIDER_ID];
+    },
+    auth: {
+      provider: PROVIDER_ID,
+      options: [
+        { key: 'open-setup-on-first-load', label: '首次自动设置（已停用）', description: '兼容旧选项；请手动打开 UA PRO 统一管理。原生 API key 登录继续可用。', default: false },
+      ],
+      methods: [
+        {
+          type: 'api',
+          label: 'API key 连接（推荐）',
+          placeholder: '粘贴服务提供的 API key',
+          prompts: [{
+            type: 'text', key: 'baseURL', message: 'API 基础地址（已在 Provider 配置时可留空）', placeholder: '粘贴服务方提供的 Base URL',
+            validate(value) {
+              if (!String(value ?? '').trim()) return undefined;
+              try { connectionProfile(null, { type: 'api', key: 'validation-only', metadata: { endpoint: String(value) } }); return undefined; }
+              catch { return '请填写有效的 API 基础地址，不要填写 API key 或具体请求路径'; }
+            },
+          }],
+        },
+        {
+          type: 'oauth',
+          label: 'UA PRO 统一管理与旧配置迁移',
+          async authorize() {
+            const account = input?.magpie?.account?.(PROVIDER_ID) ?? PROVIDER_ID;
+            const originalAuth = await currentHostAuth(account);
+            const native = originalAuth?.type === 'api' && typeof originalAuth.key === 'string' && originalAuth.key.trim() && originalAuth.key !== AUTH_MARKER;
+            const accountStore = native ? createAccountProfileStore({
+              auth: originalAuth,
+              savedProfile: await readProfile(),
+              defaults: seed,
+              provider: declaredProvider,
+              path: input?.directory ? join(input.directory, 'plugin-auth.json') : store.path,
+              readAuth: () => currentHostAuth(account),
+              writeAuth: async (body) => {
+                if (!input?.client?.auth?.set) throw new Error('当前宿主不支持保存账号配置');
+                const response = await input.client.auth.set({ path: { id: account }, body });
+                if (response?.data !== true || !isDeepStrictEqual(await currentHostAuth(account), body)) throw new Error('宿主未确认账号配置已保存');
+              },
+            }) : null;
+            // The account store remains available only for backend compatibility clients.
+            const session = accountStore ? await startSetup({ store: accountStore, accountManager, checkConnection, uaService, finishOnSave: false }) : await setupSession();
+            return {
+              url: session.url,
+              method: 'auto',
+              opened: false,
+              instructions: '在 UA PRO 统一管理连接与模板；旧独立 Claude 配置可在“设置”中预览迁移。原生 API key 登录继续可用。管理页保存独立的 UA PRO 配置，完成后请返回 UA PRO 供应商并重载核对。Docker 或远程宿主请使用同端口 SSH 隧道访问。',
+              async callback(_code, options = {}) {
+                try {
+                  const result = await waitForSetup(session, options.signal);
+                  if (result.status === 'timeout') return { type: 'failed', error: 'UA PRO 管理已超时，已保存的配置仍保留' };
+                  if (options.signal?.aborted || !['saved', 'managed', 'cancelled'].includes(result.status)) return { type: 'failed', error: 'UA PRO 管理已取消，原账号凭据保留' };
+                  const expectedAuth = accountStore ? accountStore.getAuth() : originalAuth;
+                  if (!isDeepStrictEqual(await currentHostAuth(account), expectedAuth)) return { type: 'failed', error: '账号已在其他位置变更，请重新打开配置；不会恢复旧凭据' };
+                  // Management never returns a key: host save() would otherwise rebuild the record.
+                  if (expectedAuth) return { type: 'success' };
+                  return { type: 'failed', error: 'UA PRO 管理已关闭，已保存的更改保留；请使用 UA PRO 供应商。当前 Claude 兼容账号尚未登录，请使用 API key 连接。' };
+                } finally {
+                  await new Promise((resolve) => setTimeout(resolve, 150));
+                  if (session.retire) await session.retire();
+                  else await session.close();
+                }
+              },
+            };
+          },
+        },
+        {
+          type: 'oauth',
+          label: '管理 New API 账号、余额与签到（可选）',
+          async authorize() {
+            const account = input?.magpie?.account?.(PROVIDER_ID) ?? PROVIDER_ID;
+            const originalAuth = await currentHostAuth(account);
+            const hostBinding = originalAuth ? { account, selected: originalAuth.metadata?.newApiAccountId ?? null, changed: false } : undefined;
+            const session = await startSetup({ store, accountManager, hostBinding, checkConnection, uaService });
+            return {
+              url: new URL('accounts', session.url).href,
+              method: 'auto',
+              instructions: '在账号管理页添加站点账号，刷新余额或签到。账号独立保存，完成后点击“完成并关闭”。这不会修改模型路由凭据。',
+              async callback(_code, options = {}) {
+                try {
+                  const result = await waitForSetup(session, options.signal);
+                  if (!['managed', 'saved'].includes(result.status)) return { type: 'failed', error: '账号管理已取消或超时，已保存的账号仍保留' };
+                  let latest;
+                  try { latest = await currentHostAuth(account); }
+                  catch { return { type: 'failed', error: '无法读取当前账号，原凭据保留；请重新打开页面' }; }
+                  if (!isDeepStrictEqual(latest, originalAuth)) {
+                    return { type: 'failed', error: '当前账号已发生变化，请重新打开页面；不会覆盖现有凭据' };
+                  }
+                  if (!originalAuth) {
+                    if (await readProfile()) return { type: 'success', key: AUTH_MARKER, metadata: { profileFile: store.path } };
+                    return { type: 'failed', error: '站点账号已保存；聊天连接尚未设置，请使用 API key 连接' };
+                  }
+                  if (hostBinding.changed) {
+                    if (!input?.client?.auth?.set) return { type: 'failed', error: '当前宿主不支持保存账号配置，绑定未保存' };
+                    const nextAuth = { ...latest, metadata: { ...latest.metadata, newApiAccountId: hostBinding.selected ?? '' } };
+                    let response;
+                    try {
+                      response = await input.client.auth.set({ path: { id: account }, body: structuredClone(nextAuth) });
+                    } catch {
+                      return { type: 'failed', error: '账号配置保存失败，请重试；原凭据保留' };
+                    }
+                    if (response?.data !== true) return { type: 'failed', error: '宿主未确认账号配置已保存，请重试' };
+                    let confirmed;
+                    try { confirmed = await currentHostAuth(account); }
+                    catch { return { type: 'failed', error: '无法确认账号配置已保存，请重试' }; }
+                    if (!isDeepStrictEqual(confirmed, nextAuth)) return { type: 'failed', error: '宿主未确认账号配置已保存，请重试' };
+                  }
+                  // The account already exists. Returning a key would make the host save() rebuild it.
+                  return { type: 'success' };
+                } finally {
+                  await new Promise((resolve) => setTimeout(resolve, 150));
+                  if (session.retire) await session.retire();
+                  else await session.close();
+                }
+              },
+            };
+          },
+        },
+      ],
+      async usage(getAuth) {
+        const id = await boundAccount(getAuth);
+        if (!id) return { signIn: 'kept', windows: [{ name: '可选余额', display: '当前宿主账号未绑定站点账号；聊天不受影响', aside: true }] };
+        let account;
+        try { account = await accountManager.refresh(id); }
+        catch { return { signIn: 'kept', windows: [{ name: '可选余额', display: '绑定的站点账号不可用，请检查账号管理', aside: true }] }; }
+        return accountUsage(account);
+      },
+      async checkin(getAuth) {
+        const id = await boundAccount(getAuth);
+        if (!id) return { outcome: 'inactive', message: '当前宿主账号未绑定站点账号，未发起签到' };
+        let account;
+        try {
+          account = await accountManager.checkin(id);
+        } catch { return { outcome: 'failed', message: '绑定的站点账号签到未完成，请检查账号管理' }; }
+        return accountCheckin(account);
+      },
+      async loader(getAuth, provider) {
+        const auth = await getAuth();
+        if (auth?.type !== 'api' || typeof auth.key !== 'string' || !auth.key.trim()) return {};
+        const getProfile = async () => {
+          const current = await getAuth();
+          if (current?.type !== 'api' || typeof current.key !== 'string' || !current.key.trim()) throw new Error('No API key available; sign in again');
+          return connectionProfile(await readProfile(), current, { ...declaredProvider, ...provider }, seed);
+        };
+        const profile = await getProfile();
+        return {
+          baseURL: profile.upstream.baseUrl,
+          apiKey: ['api-key', 'bearer'].includes(profile.upstream.authorizationMode) ? profile.upstream.apiKey : AUTH_MARKER,
+          fetch: createTransport({ getProfile, extractHostContext, fetchImpl: dependencies.fetchImpl ?? globalThis.fetch }),
+        };
+      },
+    },
+    provider: {
+      id: PROVIDER_ID,
+      async models(provider = {}, { auth } = {}) {
+        const saved = await readProfile();
+        if (!saved && !auth) return provider.models ?? {};
+        if (hostModelsExplicit) return provider.models ?? {};
+        const profile = connectionProfile(saved, auth, { ...declaredProvider, ...provider }, seed);
+        const models = await discoverModels(profile);
+        const records = modelRecords(profile, Object.keys(models), { ...models, ...options.models, ...provider.models });
+        const scopedUrl = auth?.metadata?.claudeProfile?.upstream?.baseUrl;
+        let scopedTarget = false;
+        try {
+          scopedTarget = auth?.type === 'api' && auth.key !== AUTH_MARKER && Boolean(auth.key) &&
+            new URL(scopedUrl).href.replace(/\/+$/, '') === new URL(profile.upstream.baseUrl).href.replace(/\/+$/, '');
+        } catch { /* No matching account-scoped configuration. */ }
+        for (const [id, model] of Object.entries(records)) {
+          const generated = generatedModels[id];
+          const generatedRoute = generated && model.api.url === generated.api?.url && model.api.npm === generated.api?.npm &&
+            model.provider.api === generated.provider?.api && model.provider.npm === generated.provider?.npm;
+          if (scopedTarget || generatedRoute) {
+            model.api = { ...model.api, url: profile.upstream.baseUrl, npm: npmFor(profile) };
+            model.provider = { ...model.provider, api: profile.upstream.baseUrl, npm: npmFor(profile) };
+          }
+        }
+        return records;
+      },
+    },
+    async 'chat.headers'(context, output) {
+      if (context?.model?.providerID !== PROVIDER_ID && context?.provider?.info?.id !== PROVIDER_ID) return;
+      const now = Date.now();
+      for (const [token, saved] of contexts) {
+        if (now - saved.created > 60000) contexts.delete(token);
+      }
+      if (contexts.size >= 2048) contexts.delete(contexts.keys().next().value);
+      const token = randomUUID();
+      contexts.set(token, { created: now, value: { sessionID: context.sessionID, model: context.model } });
+      output.headers[contextHeader] = token;
+    },
+  };
+}

package/src/profile.mjs

@@ -0,0 +1,217 @@
+import { compileParameters, isObject } from '../lib/parameters.mjs';
+
+export const HEADER_LIMIT_BYTES = 16 * 1024;
+export const PROTECTED_HEADER_NAMES = Object.freeze([
+  'authorization', 'x-api-key', 'api-key', 'x-goog-api-key', 'cookie', 'set-cookie',
+  'host', 'content-length', 'content-encoding', 'connection', 'transfer-encoding',
+  'proxy-authorization', 'proxy-authenticate', 'proxy-connection', 'keep-alive', 'upgrade', 'te', 'trailer',
+  'x-openai-actor-authorization',
+]);
+export const VARIABLE_DEFINITIONS = Object.freeze([
+  Object.freeze({ name: 'session.id', description: '真实宿主会话 ID；缺失时省略' }),
+  Object.freeze({ name: 'request.id', description: '本次上游请求 ID；由插件生成' }),
+  Object.freeze({ name: 'client.version', description: '配置中的客户端版本' }),
+  Object.freeze({ name: 'model.id', description: '真实请求或宿主提供的模型 ID' }),
+  Object.freeze({ name: 'reasoning.effort', description: 'Messages output_config.effort 提供的推理强度' }),
+  Object.freeze({ name: 'timestamp', description: '本次请求的 Unix 毫秒时间戳' }),
+]);
+export const DEFAULT_METADATA_TEMPLATES = Object.freeze({});
+const BETA = 'claude-code-20250219,context-1m-2025-08-07,interleaved-thinking-2025-05-14,thinking-token-count-2026-05-13,context-management-2025-06-27,prompt-caching-scope-2026-01-05,per-turn-control-2026-07-01,mid-conversation-tool-changes-2026-07-01,advanced-tool-use-2025-11-20,effort-2025-11-24,dangerous-tool-use-2026-09-03,afk-mode-2026-01-31';
+const vscodeUA = 'claude-cli/2.1.316 (external, claude-vscode, agent-sdk/0.3.316)';
+const presetHeaders = Object.freeze({
+  accept: 'application/json',
+  'anthropic-beta': BETA,
+  'anthropic-dangerous-direct-browser-access': 'true',
+  'anthropic-version': '2023-06-01',
+  'user-agent': vscodeUA,
+  'x-app': 'cli',
+  'x-stainless-arch': 'x64',
+  'x-stainless-lang': 'js',
+  'x-stainless-os': 'Windows',
+  'x-stainless-package-version': '0.128.0',
+  'x-stainless-retry-count': '0',
+  'x-stainless-runtime': 'node',
+  'x-stainless-runtime-version': 'v26.12.1',
+  'x-stainless-timeout': '300',
+});
+export const CLIENT_PRESETS = Object.freeze({
+  'claude-vscode': Object.freeze({ label: 'Claude Code VS Code', version: '2.1.316', userAgent: vscodeUA, headers: presetHeaders }),
+  'claude-cli': Object.freeze({ label: 'Claude Code CLI', version: '2.1.316', userAgent: 'claude-cli/2.1.316 (external, cli)', headers: Object.freeze({ ...presetHeaders, 'user-agent': 'claude-cli/2.1.316 (external, cli)' }) }),
+  none: Object.freeze({ label: '无预设', version: '', userAgent: '', headers: Object.freeze({}) }),
+});
+export class ProfileValidationError extends Error {
+  constructor(fields, message = '配置验证失败') {
+    super(message); this.name = 'ProfileValidationError'; this.code = 'PROFILE_VALIDATION_ERROR'; this.fields = fields;
+  }
+}
+const protectedNames = new Set(PROTECTED_HEADER_NAMES);
+const variables = new Set(VARIABLE_DEFINITIONS.map(v => v.name));
+const token = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+export function isProtectedHeader(name) {
+  return protectedNames.has(name.toLowerCase()) || name.toLowerCase().startsWith('x-magpie-');
+}
+export function isSafeHeaderText(value) {
+  return typeof value === 'string' && !/[\u0000-\u001f\u007f]|[^\u0020-\u00ff]/u.test(value);
+}
+export function validateHeaderTemplate(value) {
+  if (!isSafeHeaderText(value) || value.length > HEADER_LIMIT_BYTES) return false;
+  let cursor = 0;
+  while (cursor < value.length) {
+    const open = value.indexOf('{{', cursor); const close = value.indexOf('}}', cursor);
+    if (open < 0 && close < 0) return true;
+    if (open < 0 || (close >= 0 && close < open)) return false;
+    const end = value.indexOf('}}', open + 2);
+    if (end < 0 || !variables.has(value.slice(open + 2, end))) return false;
+    cursor = end + 2;
+  }
+  return true;
+}
+export function targetOf(value) {
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) return null;
+    return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+  } catch { return null; }
+}
+export function createDefaultProfile() {
+  return {
+    version: 1,
+    upstream: { baseUrl: '', apiMode: 'anthropic', apiKey: '', authorizationMode: 'api-key', authorizationValue: '' },
+    models: [], client: { preset: 'claude-vscode', version: '' },
+    headers: { userAgent: '', acceptMode: 'json', acceptValue: '', contentType: '', anthropicVersion: '', anthropicBeta: '', sessionId: '{{session.id}}', clientRequestId: '{{request.id}}', extra: [] },
+    parameters: { defaults: {}, overrides: {}, remove: [] },
+  };
+}
+
+/** allowBlank is for an unconfigured UI/config draft only; transport/store use strict validation. */
+export function normalizeProfile(raw, { allowBlank = false } = {}) {
+  if (!isObject(raw)) throw new ProfileValidationError({ profile: '配置必须是对象' });
+  const fields = {}; const output = createDefaultProfile();
+  const error = (path, message) => { fields[path] ??= message; };
+  const known = (value, keys, path) => {
+    if (isObject(value) && Object.keys(value).some(key => !keys.includes(key))) error(path, '包含未知配置字段，请检查字段名称');
+  };
+  known(raw, ['version', 'upstream', 'models', 'client', 'headers', 'parameters'], 'profile');
+  known(raw.upstream, Object.keys(output.upstream), 'upstream');
+  known(raw.client, Object.keys(output.client), 'client');
+  known(raw.headers, Object.keys(output.headers), 'headers');
+  if (raw.version !== undefined && raw.version !== 1) error('version', '仅支持配置版本 1');
+  const upstream = raw.upstream;
+  if (upstream !== undefined && !isObject(upstream)) error('upstream', 'upstream 必须是对象');
+  const source = isObject(upstream) ? upstream : {};
+  const base = source.baseUrl ?? '';
+  if (typeof base !== 'string') error('upstream.baseUrl', '上游 Base URL 必须是字符串');
+  else if (!base.trim()) { if (!allowBlank) error('upstream.baseUrl', '上游 Base URL 不能为空'); }
+  else {
+    try {
+      const value = base.trim(); const url = new URL(value);
+      const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+      if (!/^https?:\/\/[^/?#]+/i.test(value) || !['http:', 'https:'].includes(url.protocol) ||
+        (url.protocol === 'http:' && !loopback) || url.username || url.password || value.includes('@') ||
+        value.includes('?') || value.includes('#') || /[\u0000-\u0020\u007f{}\\]/.test(value) ||
+        /\/(messages|responses|chat\/completions)\/?$/i.test(url.pathname)) throw new Error();
+      output.upstream.baseUrl = url.href.replace(/\/+$/, '');
+    } catch { error('upstream.baseUrl', '请填写 HTTPS Base URL（回环地址可用 HTTP），不要包含凭据、查询、片段或具体请求路径'); }
+  }
+  if (source.apiMode !== undefined && source.apiMode !== 'anthropic') error('upstream.apiMode', 'apiMode 必须是 anthropic');
+  for (const name of ['apiKey', 'authorizationValue']) {
+    if (source[name] === undefined) continue;
+    if (!isSafeHeaderText(source[name]) || source[name].length > HEADER_LIMIT_BYTES) error(`upstream.${name}`, '凭据必须是不含控制字符的 HTTP 头文本');
+    else output.upstream[name] = source[name];
+  }
+  if (source.authorizationMode !== undefined) {
+    if (!['api-key', 'bearer', 'custom', 'none'].includes(source.authorizationMode)) error('upstream.authorizationMode', '授权模式必须是 api-key、bearer、custom 或 none');
+    else output.upstream.authorizationMode = source.authorizationMode;
+  }
+  if (!allowBlank && ['api-key', 'bearer'].includes(output.upstream.authorizationMode) && !output.upstream.apiKey.trim()) error('upstream.apiKey', '当前授权模式必须填写 API key');
+  if (!allowBlank && output.upstream.authorizationMode === 'custom' && !output.upstream.authorizationValue.trim()) error('upstream.authorizationValue', 'custom 模式必须填写完整的 Authorization 值');
+  if (raw.models !== undefined) {
+    if (!Array.isArray(raw.models)) error('models', 'models 必须是字符串数组');
+    else {
+      const models = [];
+      raw.models.forEach((id, index) => {
+        if (typeof id !== 'string' || !id.trim() || /[\u0000-\u001f\u007f]/.test(id)) error(`models[${index}]`, '模型 ID 必须是不含控制字符的非空字符串');
+        else models.push(id.trim());
+      });
+      output.models = [...new Set(models)];
+    }
+  }
+  if (raw.client !== undefined && !isObject(raw.client)) error('client', 'client 必须是对象');
+  if (isObject(raw.client)) {
+    if (raw.client.preset !== undefined) {
+      if (typeof raw.client.preset !== 'string' || !Object.hasOwn(CLIENT_PRESETS, raw.client.preset)) error('client.preset', '请选择 claude-vscode、claude-cli 或 none');
+      else output.client.preset = raw.client.preset;
+    }
+    if (raw.client.version !== undefined) {
+      if (!isSafeHeaderText(raw.client.version)) error('client.version', '版本必须是不含控制字符的 HTTP 头文本');
+      else output.client.version = raw.client.version;
+    }
+  }
+  if (raw.headers !== undefined && !isObject(raw.headers)) error('headers', 'headers 必须是对象');
+  const headers = isObject(raw.headers) ? raw.headers : {};
+  for (const name of ['userAgent', 'acceptValue', 'contentType', 'anthropicVersion', 'anthropicBeta', 'sessionId', 'clientRequestId']) {
+    if (headers[name] === undefined) continue;
+    if (!validateHeaderTemplate(headers[name])) error(`headers.${name}`, '请求头文本或模板变量无效');
+    else output.headers[name] = headers[name];
+  }
+  if (headers.acceptMode !== undefined) {
+    if (!['json', 'auto', 'sse', 'custom'].includes(headers.acceptMode)) error('headers.acceptMode', 'Accept 模式必须是 json、auto、sse 或 custom');
+    else output.headers.acceptMode = headers.acceptMode;
+  }
+  if (output.headers.acceptMode === 'custom' && !output.headers.acceptValue.trim()) error('headers.acceptValue', 'custom 模式必须填写 Accept 值');
+  if (headers.extra !== undefined) {
+    if (!Array.isArray(headers.extra)) error('headers.extra', '附加请求头必须是数组');
+    else headers.extra.forEach((item, index) => {
+      const path = `headers.extra[${index}]`;
+      if (!isObject(item)) { error(path, '附加请求头必须是对象'); return; }
+      known(item, ['name', 'value', 'enabled'], path);
+      if (typeof item.name !== 'string' || !token.test(item.name) || isProtectedHeader(item.name)) error(`${path}.name`, '该请求头名称无效或受到保护');
+      if (item.value !== null && !validateHeaderTemplate(item.value)) error(`${path}.value`, '请求头值必须是有效文本、模板或 null');
+      if (item.enabled !== undefined && typeof item.enabled !== 'boolean') error(`${path}.enabled`, 'enabled 必须是布尔值');
+      output.headers.extra.push({ name: item.name, value: item.value, enabled: item.enabled ?? true });
+    });
+  }
+  try {
+    const plan = compileParameters(raw.parameters);
+    output.parameters = { defaults: plan.defaults, overrides: plan.overrides, remove: plan.remove.map(path => path.join('.')) };
+  } catch { error('parameters', 'Messages 参数设置无效，不能修改受保护字段或使用 Responses 参数'); }
+  if (Object.keys(fields).length) throw new ProfileValidationError(fields);
+  return output;
+}
+
+export function redactProfile(profile) {
+  let output;
+  try { output = normalizeProfile(profile, { allowBlank: true }); }
+  catch { output = createDefaultProfile(); }
+  output.upstream.apiKey = ''; output.upstream.authorizationValue = '';
+  return output;
+}
+
+export function mergeProfileSecrets(nextRaw, previousProfile, clearSecrets = []) {
+  if (!Array.isArray(clearSecrets) || clearSecrets.some(field => !['apiKey', 'authorizationValue'].includes(field))) throw new ProfileValidationError({ clearSecrets: 'clearSecrets 包含未知字段或格式无效' });
+  if (!isObject(nextRaw)) throw new ProfileValidationError({ profile: '配置必须是对象' });
+  const nextTarget = targetOf(nextRaw.upstream?.baseUrl); const oldTarget = targetOf(previousProfile?.upstream?.baseUrl);
+  const same = nextTarget !== null && nextTarget === oldTarget;
+  const draft = { ...nextRaw, upstream: isObject(nextRaw.upstream) ? { ...nextRaw.upstream } : nextRaw.upstream };
+  if (isObject(draft.upstream)) {
+    for (const field of ['apiKey', 'authorizationValue']) {
+      const value = draft.upstream[field];
+      if ((value === undefined || (typeof value === 'string' && !value.trim()))) draft.upstream[field] = same && !clearSecrets.includes(field) ? previousProfile?.upstream?.[field] ?? '' : '';
+      else if (!same && oldTarget && value === previousProfile?.upstream?.[field]) throw new ProfileValidationError({ [`upstream.${field}`]: '服务地址已改变，请重新填写该服务的凭据' });
+      if (clearSecrets.includes(field) && (value === undefined || value === '')) draft.upstream[field] = '';
+    }
+  }
+  const normalized = normalizeProfile(draft);
+  if (nextTarget && oldTarget && !same) {
+    const fields = {}; const defaults = createDefaultProfile().headers; const old = previousProfile?.headers ?? {};
+    for (const [key, value] of Object.entries(normalized.headers)) {
+      if (key === 'extra' || typeof value !== 'string' || value === defaults[key] || !value.trim()) continue;
+      if (typeof old[key] === 'string' && value.trim() === old[key].trim()) fields[`headers.${key}`] = '服务地址已改变，请移除旧服务的专用设置';
+    }
+    normalized.headers.extra.forEach((item, index) => {
+      if ((old.extra ?? []).some(entry => typeof entry?.name === 'string' && entry.name.toLowerCase() === item.name.toLowerCase() && entry.value === item.value)) fields[`headers.extra[${index}].value`] = '服务地址已改变，请移除旧服务的附加请求头';
+    });
+    if (Object.keys(fields).length) throw new ProfileValidationError(fields);
+  }
+  return normalized;
+}

package/src/runtime.mjs

@@ -0,0 +1,39 @@
+import { isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+export function resolveProfilePath({ configPath, env = process.env } = {}) {
+  const path = configPath ?? env.MAGPIE_CLAUDE_PROFILE_FILE ?? fileURLToPath(new URL('../runtime/profile.json', import.meta.url));
+  if (typeof path !== 'string' || !isAbsolute(path)) throw new Error('配置文件必须使用绝对路径');
+  return path;
+}
+export function parseSetupArgs(args) {
+  const result = { configPath: undefined, port: 0, open: true, help: false };
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === '--config') {
+      const path = args[++index];
+      if (!path || path.startsWith('--') || !isAbsolute(path)) throw new Error('--config 必须填写绝对路径');
+      result.configPath = path;
+    } else if (argument === '--port') {
+      const value = args[++index];
+      if (!/^\d+$/.test(value ?? '') || Number(value) > 65535) throw new Error('--port 必须是 0 到 65535 的端口');
+      result.port = Number(value);
+    } else if (argument === '--no-open') result.open = false;
+    else if (argument === '--help' || argument === '-h') result.help = true;
+    else throw new Error('未知参数，请运行 --help 查看用法');
+  }
+  return result;
+}
+export function openBrowser(url, { platform = process.platform, launch = spawn } = {}) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(parsed.hostname) || parsed.username || parsed.password) return Promise.reject(new Error('只允许打开当前回环配置页面'));
+  const command = platform === 'win32' ? 'rundll32.exe' : platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+  return new Promise(resolve => {
+    try {
+      const child = launch(command, args, { shell: false, detached: true, stdio: 'ignore' });
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => { child.unref(); resolve(true); });
+    } catch { resolve(false); }
+  });
+}