pi-cliproxyapi-autoconnect 0.0.0-stage → 1.2.0

package/index.ts

@@ -0,0 +1,1313 @@
+/**
+ * pi-cliproxyapi-autoconnect — CLIProxyAPI provider for pi
+ *
+ * Adds a "CLIProxy" entry to pi's /login flow (under "Sign in with an API key"):
+ *   1. ask for the bound domain (for example proxy.example.com)
+ *   2. ask for the API key
+ *   3. derive every compatible base URL and try them automatically,
+ *      OpenAI first, then Gemini, then Anthropic
+ *   4. register every returned model in /model
+ *
+ * If model discovery fails everywhere, the user picks one of the formatted
+ * compatible addresses (OpenAI / Anthropic / Gemini) or enters a custom base
+ * URL, and can type model IDs manually.
+ *
+ * The API key is stored by pi in ~/.pi/agent/auth.json. This extension only
+ * stores non-secret connection metadata in ~/.pi/agent/cliproxy.json.
+ *
+ * CLIProxyAPI reference: https://github.com/router-for-me/CLIProxyAPI
+ */
+
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	anthropicMessagesApi,
+	createProvider,
+	googleGenerativeAIApi,
+	openAICompletionsApi,
+	type Api,
+	type ApiKeyCredential,
+	type Model,
+	type Provider,
+	type ProviderAuthInteraction,
+	type ProviderStreams,
+	type RefreshModelsContext,
+} from "@earendil-works/pi-ai/compat";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const PROVIDER_ID = "cliproxy";
+const PROVIDER_NAME = "CLIProxy";
+const AUTH_NAME = "CLIProxy（域名 + API Key）";
+const CONFIG_FILE_NAME = "cliproxy.json";
+const CONFIG_VERSION = 2;
+const REQUEST_TIMEOUT_MS = 10_000;
+const PROBE_TIMEOUT_MS = 4_000;
+/** Reuse a fresh catalog for a few minutes unless a refresh is forced. */
+const MODEL_REFRESH_TTL_MS = 5 * 60_000;
+
+/** Last non-fatal error from a background model refresh, used by /cliproxy. */
+let lastRefreshError: string | undefined;
+
+type SupportedApi = "openai-completions" | "anthropic-messages" | "google-generative-ai";
+
+const PROVIDER_APIS: Readonly<Record<SupportedApi, string>> = {
+	"openai-completions": "OpenAI 兼容",
+	"anthropic-messages": "Anthropic 兼容",
+	"google-generative-ai": "Gemini 兼容",
+};
+
+// =============================================================================
+// Persisted configuration (never contains the API key)
+// =============================================================================
+
+interface StoredModel {
+	/** Upstream model ID exactly as returned by the proxy. */
+	id: string;
+	/** Optional display name. */
+	name?: string;
+	/** Optional upstream owner reported by /v1/models. */
+	ownedBy?: string;
+	/** Persisted capability metadata, so cliproxy.json is self-contained. */
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+interface CliproxyConfig {
+	version: number;
+	/** Domain exactly as the user typed it. */
+	domain: string;
+	/** Normalized root URL without a compatibility suffix, e.g. https://proxy.example.com */
+	rootUrl: string;
+	/** Base URL used by pi for every model, e.g. https://proxy.example.com/v1 */
+	baseUrl: string;
+	/** Wire protocol used by the configured base URL. */
+	api: SupportedApi;
+	models: StoredModel[];
+	/** Whether models came from automatic discovery or from manual IDs. */
+	source: "auto" | "manual";
+	updatedAt: number;
+	lastError?: string;
+}
+
+interface NormalizedDomain {
+	rootUrl: string;
+	implicitScheme: boolean;
+}
+
+/** One derivable compatible address, in the order it should be probed. */
+interface DiscoveryCandidate {
+	api: SupportedApi;
+	rootUrl: string;
+	baseUrl: string;
+}
+
+interface DiscoveryAttempt {
+	candidate: DiscoveryCandidate;
+	failure: FetchFailure;
+}
+
+type DiscoveryOutcome =
+	| { ok: true; candidate: DiscoveryCandidate; models: StoredModel[] }
+	| { ok: false; attempts: DiscoveryAttempt[]; empty?: DiscoveryCandidate };
+
+interface FetchedModels {
+	ok: true;
+	models: StoredModel[];
+}
+
+interface FetchFailure {
+	ok: false;
+	error: string;
+	kind: "auth" | "forbidden" | "not-found" | "server" | "network" | "format" | "http" | "unsupported";
+	status?: number;
+}
+
+type FetchResult = FetchedModels | FetchFailure;
+
+/** Capability metadata borrowed from an existing models.json entry with the same model ID. */
+interface ModelMetadata {
+	name?: string;
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+let metadataCache: { path: string; mtimeMs: number; metadata: Map<string, ModelMetadata> } | undefined;
+let storeMetadataCache: { path: string; mtimeMs: number; metadata: Map<string, ModelMetadata> } | undefined;
+let builtinMetadataCache: Map<string, ModelMetadata> | undefined;
+
+// =============================================================================
+// Config file
+// =============================================================================
+
+function configPath(): string {
+	return join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+function isSupportedApi(value: unknown): value is SupportedApi {
+	return value === "openai-completions" || value === "anthropic-messages" || value === "google-generative-ai";
+}
+
+function sanitizeModels(value: unknown): StoredModel[] {
+	if (!Array.isArray(value)) return [];
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object") continue;
+		const record = entry as Record<string, unknown>;
+		const id = typeof record.id === "string" ? record.id.trim() : "";
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const name = typeof record.name === "string" && record.name.trim() ? record.name.trim() : undefined;
+		const ownedBy = typeof record.ownedBy === "string" && record.ownedBy.trim() ? record.ownedBy.trim() : undefined;
+		const reasoning = typeof record.reasoning === "boolean" ? record.reasoning : undefined;
+		const input = Array.isArray(record.input)
+			? record.input.filter((value): value is "text" | "image" => value === "text" || value === "image")
+			: undefined;
+		const cost = readMetadataCost(record.cost);
+		const contextWindow =
+			typeof record.contextWindow === "number" && record.contextWindow > 0 ? record.contextWindow : undefined;
+		const maxTokens =
+			typeof record.maxTokens === "number" && record.maxTokens > 0 ? record.maxTokens : undefined;
+		models.push({
+			id,
+			...(name ? { name } : {}),
+			...(ownedBy ? { ownedBy } : {}),
+			...(reasoning !== undefined ? { reasoning } : {}),
+			...(input && input.length > 0 ? { input } : {}),
+			...(cost ? { cost } : {}),
+			...(contextWindow ? { contextWindow } : {}),
+			...(maxTokens ? { maxTokens } : {}),
+		});
+	}
+	return models;
+}
+
+function readConfig(): CliproxyConfig | undefined {
+	const path = configPath();
+	if (!existsSync(path)) return undefined;
+	try {
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		if (!parsed || typeof parsed !== "object") return undefined;
+		if (typeof parsed.rootUrl !== "string" || typeof parsed.baseUrl !== "string") return undefined;
+		if (!isSupportedApi(parsed.api)) return undefined;
+		const source = parsed.source === "manual" ? "manual" : "auto";
+		const lastError = typeof parsed.lastError === "string" && parsed.lastError ? parsed.lastError : undefined;
+		return {
+			version: typeof parsed.version === "number" ? parsed.version : CONFIG_VERSION,
+			domain: typeof parsed.domain === "string" ? parsed.domain : parsed.rootUrl,
+			rootUrl: parsed.rootUrl,
+			baseUrl: parsed.baseUrl,
+			api: parsed.api,
+			models: sanitizeModels(parsed.models),
+			source,
+			updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0,
+			...(lastError ? { lastError } : {}),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function writeConfig(config: CliproxyConfig): void {
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	// Keep one previous generation for manual recovery.
+	if (existsSync(path)) {
+		try {
+			copyFileSync(path, `${path}.bak`);
+		} catch {
+			// Backups are best effort; never fail the actual write because of one.
+		}
+	}
+	const data = `${JSON.stringify(config, null, 2)}\n`;
+	const temporaryPath = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporaryPath, data, { encoding: "utf8", mode: 0o600 });
+	try {
+		renameSync(temporaryPath, path);
+	} catch {
+		// Windows can refuse to replace an existing file while another process holds it.
+		writeFileSync(path, data, { encoding: "utf8", mode: 0o600 });
+		try {
+			unlinkSync(temporaryPath);
+		} catch {
+			// Best effort only.
+		}
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from models.json
+// =============================================================================
+
+function readMetadataCost(value: unknown): ModelMetadata["cost"] | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	const input = record.input;
+	const output = record.output;
+	const cacheRead = record.cacheRead;
+	const cacheWrite = record.cacheWrite;
+	if (typeof input !== "number" || typeof output !== "number") return undefined;
+	return {
+		input,
+		output,
+		cacheRead: typeof cacheRead === "number" ? cacheRead : 0,
+		cacheWrite: typeof cacheWrite === "number" ? cacheWrite : 0,
+	};
+}
+
+/**
+ * CLIProxyAPI's /v1/models only returns model IDs. If the user already has a
+ * models.json entry for the same ID (for example a hand-written provider that
+ * points at the same proxy), reuse its capability metadata instead of the
+ * conservative guesses below.
+ */
+function readModelsJsonMetadata(): Map<string, ModelMetadata> {
+	const path = join(getAgentDir(), "models.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		if (metadataCache && metadataCache.path === path && metadataCache.mtimeMs === mtimeMs) {
+			return metadataCache.metadata;
+		}
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const providers =
+			parsed.providers && typeof parsed.providers === "object"
+				? (parsed.providers as Record<string, unknown>)
+				: parsed;
+		const metadata = new Map<string, ModelMetadata>();
+		for (const provider of Object.values(providers)) {
+			if (!provider || typeof provider !== "object") continue;
+			const models = (provider as Record<string, unknown>).models;
+			if (!Array.isArray(models)) continue;
+			for (const value of models) {
+				if (!value || typeof value !== "object") continue;
+				const model = value as Record<string, unknown>;
+				if (typeof model.id !== "string" || !model.id.trim()) continue;
+				if (typeof model.type === "string" && model.type !== "chat") continue;
+				const id = model.id.trim();
+				if (metadata.has(id)) continue;
+				const entry: ModelMetadata = {};
+				if (typeof model.name === "string" && model.name.trim()) entry.name = model.name.trim();
+				if (typeof model.reasoning === "boolean") entry.reasoning = model.reasoning;
+				if (Array.isArray(model.input)) {
+					const input = model.input.filter(
+						(value): value is "text" | "image" => value === "text" || value === "image",
+					);
+					if (input.length > 0) entry.input = input;
+				}
+				const cost = readMetadataCost(model.cost);
+				if (cost) entry.cost = cost;
+				if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
+					entry.contextWindow = model.contextWindow;
+				}
+				if (typeof model.maxTokens === "number" && model.maxTokens > 0) {
+					entry.maxTokens = model.maxTokens;
+				}
+				if (Object.keys(entry).length > 0) metadata.set(id, entry);
+			}
+		}
+		metadataCache = { path, mtimeMs, metadata };
+		return metadata;
+	} catch {
+		if (metadataCache?.path === path) return metadataCache.metadata;
+		return new Map();
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from pi's models-store cache
+// =============================================================================
+
+function readModelsStoreMetadata(): Map<string, ModelMetadata> {
+	const path = join(getAgentDir(), "models-store.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		if (storeMetadataCache && storeMetadataCache.path === path && storeMetadataCache.mtimeMs === mtimeMs) {
+			return storeMetadataCache.metadata;
+		}
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const providerEntry = parsed[PROVIDER_ID];
+		const models =
+			providerEntry && typeof providerEntry === "object"
+				? (providerEntry as Record<string, unknown>).models
+				: undefined;
+		const metadata = new Map<string, ModelMetadata>();
+		if (Array.isArray(models)) {
+			for (const value of models) {
+				if (!value || typeof value !== "object") continue;
+				const model = value as Record<string, unknown>;
+				if (typeof model.id !== "string" || !model.id.trim()) continue;
+				if (typeof model.type === "string" && model.type !== "chat") continue;
+				const id = model.id.trim();
+				const entry: ModelMetadata = {};
+				if (typeof model.name === "string" && model.name.trim()) entry.name = model.name.trim();
+				if (typeof model.reasoning === "boolean") entry.reasoning = model.reasoning;
+				if (Array.isArray(model.input)) {
+					const input = model.input.filter(
+						(value): value is "text" | "image" => value === "text" || value === "image",
+					);
+					if (input.length > 0) entry.input = input;
+				}
+				const cost = readMetadataCost(model.cost);
+				if (cost) entry.cost = cost;
+				if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
+					entry.contextWindow = model.contextWindow;
+				}
+				if (typeof model.maxTokens === "number" && model.maxTokens > 0) {
+					entry.maxTokens = model.maxTokens;
+				}
+				if (Object.keys(entry).length > 0) metadata.set(id, entry);
+			}
+		}
+		storeMetadataCache = { path, mtimeMs, metadata };
+		return metadata;
+	} catch {
+		if (storeMetadataCache?.path === path) return storeMetadataCache.metadata;
+		return new Map();
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from pi's built-in catalog
+// =============================================================================
+
+function normalizeModelId(id: string): string {
+	// CLIProxy often exposes prefixes such as "global:", "cn:" or "models/".
+	return id
+		.trim()
+		.replace(/^models\//iu, "")
+		.replace(/^[a-z\d._-]+:/iu, "");
+}
+
+function readBuiltinMetadata(): Map<string, ModelMetadata> {
+	if (builtinMetadataCache) return builtinMetadataCache;
+	const metadata = new Map<string, ModelMetadata>();
+	try {
+		for (const provider of builtinProviders()) {
+			for (const model of provider.getModels()) {
+				if (model.type && model.type !== "chat") continue;
+				const entry: ModelMetadata = {
+					name: model.name,
+					reasoning: model.reasoning,
+					input: model.input,
+					cost: model.cost,
+					contextWindow: model.contextWindow,
+					maxTokens: model.maxTokens,
+				};
+				const normalized = normalizeModelId(model.id);
+				if (!metadata.has(model.id)) metadata.set(model.id, entry);
+				if (normalized && !metadata.has(normalized)) metadata.set(normalized, entry);
+			}
+		}
+	} catch {
+		// Built-in catalog is optional; heuristics remain available.
+	}
+	builtinMetadataCache = metadata;
+	return metadata;
+}
+
+// =============================================================================
+// Domain and URL formatting
+// =============================================================================
+
+function trimTrailingSlashes(value: string): string {
+	return value.replace(/\/+$/u, "");
+}
+
+function swapScheme(url: string): string | undefined {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol === "https:") {
+			parsed.protocol = "http:";
+			return trimTrailingSlashes(parsed.toString());
+		}
+		if (parsed.protocol === "http:") {
+			parsed.protocol = "https:";
+			return trimTrailingSlashes(parsed.toString());
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function isLocalHostname(hostname: string): boolean {
+	const host = hostname.toLowerCase();
+	return (
+		host === "localhost" ||
+		host === "127.0.0.1" ||
+		host === "::1" ||
+		host === "[::1]" ||
+		host.endsWith(".local") ||
+		host.endsWith(".lan") ||
+		/^127\./u.test(host) ||
+		/^10\./u.test(host) ||
+		/^192\.168\./u.test(host) ||
+		/^172\.(1[6-9]|2\d|3[01])\./u.test(host)
+	);
+}
+
+/**
+ * Accepts `proxy.example.com`, `https://proxy.example.com/`, a pasted
+ * `https://proxy.example.com/v1` or `.../v1/models`, and even a domain with a
+ * reverse-proxy path prefix. Returns the root URL used to derive compatible
+ * addresses.
+ */
+function normalizeDomain(input: string): NormalizedDomain {
+	const original = input.trim();
+	if (!original) throw new Error("未输入绑定域名");
+	const implicitScheme = !/^[a-z][a-z\d+.-]*:\/\//iu.test(original);
+	const withScheme = implicitScheme
+		? `${isLocalHostname(original.split("/")[0]?.split(":")[0] ?? "") ? "http" : "https"}://${original}`
+		: original;
+	let parsed: URL;
+	try {
+		parsed = new URL(withScheme);
+	} catch {
+		throw new Error(`无法解析域名："${input}"。示例：proxy.example.com 或 https://proxy.example.com`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(`仅支持 http/https 地址，收到：${parsed.protocol}`);
+	}
+	parsed.username = "";
+	parsed.password = "";
+	parsed.hash = "";
+	parsed.search = "";
+	let pathname = parsed.pathname.replace(/\/+$/u, "");
+	// Users often paste the complete compatible URL instead of the domain.
+	pathname = pathname.replace(/\/v1(?:beta|alpha)?\/models$/iu, "");
+	pathname = pathname.replace(/\/models$/iu, "");
+	pathname = pathname.replace(/\/v1(?:beta|alpha)?$/iu, "");
+	parsed.pathname = pathname;
+	const rootUrl = trimTrailingSlashes(parsed.toString());
+	return { rootUrl, implicitScheme };
+}
+
+function openAIBaseUrl(rootUrl: string): string {
+	return `${trimTrailingSlashes(rootUrl)}/v1`;
+}
+
+function anthropicBaseUrl(rootUrl: string): string {
+	// The Anthropic SDK appends /v1/messages to this value.
+	return trimTrailingSlashes(rootUrl);
+}
+
+function geminiBaseUrl(rootUrl: string): string {
+	return `${trimTrailingSlashes(rootUrl)}/v1beta`;
+}
+
+// =============================================================================
+// Network helpers
+// =============================================================================
+
+function abortSignalWithTimeout(signal: AbortSignal, timeoutMs: number): { signal: AbortSignal; cleanup: () => void } {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new Error("请求超时")), timeoutMs);
+	const onAbort = () => controller.abort(signal.reason);
+	if (signal.aborted) controller.abort(signal.reason);
+	else signal.addEventListener("abort", onAbort, { once: true });
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+		},
+	};
+}
+
+async function safeText(response: Response): Promise<string> {
+	try {
+		return (await response.text()).trim().slice(0, 500);
+	} catch {
+		return "";
+	}
+}
+
+function describeFetchError(error: unknown, ownSignal: AbortSignal, outerSignal: AbortSignal): string {
+	if (outerSignal.aborted) return "已取消";
+	if (ownSignal.aborted) return "请求超时";
+	if (error instanceof Error) {
+		const cause = error.cause;
+		if (cause instanceof Error && cause.message && cause.message !== error.message) {
+			return `${error.message}（${cause.message}）`;
+		}
+		return error.message;
+	}
+	return String(error);
+}
+
+function failureKindForStatus(status: number): FetchFailure["kind"] {
+	if (status === 401) return "auth";
+	if (status === 403) return "forbidden";
+	if (status === 404) return "not-found";
+	if (status === 429 || status >= 500) return "server";
+	return "http";
+}
+
+function makeHttpFailure(status: number, body: string): FetchFailure {
+	return {
+		ok: false,
+		error: `HTTP ${status}${body ? `：${body}` : ""}`,
+		kind: failureKindForStatus(status),
+		status,
+	};
+}
+
+async function probeCliproxy(rootUrl: string, signal: AbortSignal): Promise<string | undefined> {
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, PROBE_TIMEOUT_MS);
+	try {
+		const response = await fetch(`${trimTrailingSlashes(rootUrl)}/healthz`, {
+			headers: { Accept: "application/json" },
+			signal: requestSignal,
+		});
+		if (!response.ok) return undefined;
+		const body = (await response.json().catch(() => undefined)) as { status?: unknown } | undefined;
+		if (body?.status === "ok") return "已探测到 CLIProxyAPI（/healthz 正常）";
+		return "已探测到 /healthz，但响应不是 CLIProxyAPI 格式";
+	} catch {
+		return undefined;
+	} finally {
+		cleanup();
+	}
+}
+
+function parseOpenAIModelList(payload: unknown): StoredModel[] | undefined {
+	if (!payload || typeof payload !== "object") return undefined;
+	const record = payload as Record<string, unknown>;
+	const entries = Array.isArray(record.data) ? record.data : Array.isArray(record.models) ? record.models : undefined;
+	if (!entries) return undefined;
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const entry of entries) {
+		if (typeof entry === "string") {
+			const id = entry.trim();
+			if (id && !seen.has(id)) {
+				seen.add(id);
+				models.push({ id });
+			}
+			continue;
+		}
+		if (!entry || typeof entry !== "object") continue;
+		const item = entry as Record<string, unknown>;
+		const rawId = typeof item.id === "string" ? item.id : typeof item.name === "string" ? item.name : "";
+		const id = rawId.trim().replace(/^models\//iu, "");
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const name =
+			typeof item.display_name === "string" && item.display_name.trim()
+				? item.display_name.trim()
+				: typeof item.displayName === "string" && item.displayName.trim()
+					? item.displayName.trim()
+					: undefined;
+		const ownedBy = typeof item.owned_by === "string" && item.owned_by.trim() ? item.owned_by.trim() : undefined;
+		models.push({ id, ...(name ? { name } : {}), ...(ownedBy ? { ownedBy } : {}) });
+	}
+	return models;
+}
+
+async function fetchOpenAIModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const url = `${trimTrailingSlashes(baseUrl)}/models`;
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, {
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"User-Agent": "pi-cliproxyapi-autoconnect/1.2",
+			},
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "响应不是 OpenAI 兼容的模型列表（缺少 data 数组）", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+async function fetchGeminiModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const url = `${trimTrailingSlashes(baseUrl)}/models?key=${encodeURIComponent(apiKey)}`;
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, {
+			headers: { Accept: "application/json", "User-Agent": "pi-cliproxyapi-autoconnect/1.2" },
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "响应不是 Gemini 兼容的模型列表（缺少 models 数组）", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+/**
+ * Anthropic's public API does expose GET /v1/models, but CLIProxyAPI's
+ * Anthropic-compatible endpoint does not always proxy it. Try anyway so the
+ * automatic discovery can use Anthropic when it is available; callers fall
+ * back to manual model IDs when it is not.
+ */
+function anthropicModelsUrl(baseUrl: string): string {
+	const root = trimTrailingSlashes(baseUrl);
+	// Anthropic's list endpoint paginates (default 20); ask for the largest page.
+	return /\/v1$/u.test(root) ? `${root}/models?limit=1000` : `${root}/v1/models?limit=1000`;
+}
+
+async function fetchAnthropicModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(anthropicModelsUrl(baseUrl), {
+			headers: {
+				Accept: "application/json",
+				"x-api-key": apiKey,
+				// Some reverse proxies accept the key as a bearer token instead of
+				// Anthropic's x-api-key header; sending both is harmless upstream.
+				Authorization: `Bearer ${apiKey}`,
+				"anthropic-version": "2023-06-01",
+				"User-Agent": "pi-cliproxyapi-autoconnect/1.2",
+			},
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			if (response.status === 404 || response.status === 405 || response.status === 501) {
+				return {
+					ok: false,
+					error: `Anthropic 兼容接口没有可用的模型列表（HTTP ${response.status}）`,
+					kind: "unsupported",
+					status: response.status,
+				};
+			}
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "响应不是 Anthropic 兼容的模型列表（缺少 data 数组）", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+async function fetchModelsForApi(api: SupportedApi, baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	if (api === "google-generative-ai") return fetchGeminiModels(baseUrl, apiKey, signal);
+	if (api === "anthropic-messages") return fetchAnthropicModels(baseUrl, apiKey, signal);
+	return fetchOpenAIModels(baseUrl, apiKey, signal);
+}
+
+// =============================================================================
+// Model conversion
+// =============================================================================
+
+function guessLimits(api: SupportedApi, modelId: string): { contextWindow: number; maxTokens: number } {
+	const id = modelId.toLowerCase();
+	if (api === "anthropic-messages" || id.includes("claude")) return { contextWindow: 200_000, maxTokens: 64_000 };
+	if (api === "google-generative-ai" || id.includes("gemini")) return { contextWindow: 1_000_000, maxTokens: 65_536 };
+	if (/gpt-5|gpt-6|gpt-7/u.test(id)) return { contextWindow: 272_000, maxTokens: 128_000 };
+	if (/(^|[-_/])o[1-9](-|$)/u.test(id)) return { contextWindow: 200_000, maxTokens: 100_000 };
+	return { contextWindow: 131_072, maxTokens: 32_768 };
+}
+
+function toModel(
+	entry: StoredModel,
+	config: CliproxyConfig,
+	metadata: ReadonlyMap<string, ModelMetadata> = new Map(),
+	storeMetadata: ReadonlyMap<string, ModelMetadata> = new Map(),
+	builtin: ReadonlyMap<string, ModelMetadata> = new Map(),
+): Model<Api> {
+	const normalizedId = normalizeModelId(entry.id);
+	const meta = metadata.get(entry.id) ?? metadata.get(normalizedId);
+	const stored = storeMetadata.get(entry.id) ?? storeMetadata.get(normalizedId);
+	const builtinMeta = builtin.get(entry.id) ?? builtin.get(normalizedId);
+	const limits = guessLimits(config.api, entry.id);
+	return {
+		id: entry.id,
+		name: meta?.name ?? entry.name?.trim() ?? stored?.name ?? builtinMeta?.name ?? entry.id,
+		api: config.api,
+		provider: PROVIDER_ID,
+		baseUrl: config.baseUrl,
+		reasoning: meta?.reasoning ?? entry.reasoning ?? stored?.reasoning ?? builtinMeta?.reasoning ?? false,
+		input: meta?.input ?? entry.input ?? stored?.input ?? builtinMeta?.input ?? ["text"],
+		cost: meta?.cost ??
+			entry.cost ??
+			stored?.cost ??
+			builtinMeta?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow:
+			meta?.contextWindow ??
+			entry.contextWindow ??
+			stored?.contextWindow ??
+			builtinMeta?.contextWindow ??
+			limits.contextWindow,
+		maxTokens:
+			meta?.maxTokens ?? entry.maxTokens ?? stored?.maxTokens ?? builtinMeta?.maxTokens ?? limits.maxTokens,
+		type: "chat",
+	};
+}
+
+/** Freeze the effective capability metadata into cliproxy.json. */
+function enrichModel(
+	entry: StoredModel,
+	config: CliproxyConfig,
+	metadata: ReadonlyMap<string, ModelMetadata>,
+	storeMetadata: ReadonlyMap<string, ModelMetadata>,
+	builtin: ReadonlyMap<string, ModelMetadata>,
+): StoredModel {
+	const model = toModel(entry, config, metadata, storeMetadata, builtin);
+	return {
+		id: model.id,
+		name: model.name,
+		...(entry.ownedBy ? { ownedBy: entry.ownedBy } : {}),
+		reasoning: model.reasoning,
+		input: model.input,
+		cost: model.cost,
+		contextWindow: model.contextWindow,
+		maxTokens: model.maxTokens,
+	};
+}
+
+function parseManualModelIds(input: string): StoredModel[] {
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const part of input.split(/[,\s;，、]+/u)) {
+		const id = part.trim();
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		models.push({ id });
+	}
+	return models;
+}
+
+function credentialKey(credential: RefreshModelsContext["credential"]): string | undefined {
+	if (credential?.type === "api_key" && credential.key) return credential.key;
+	return undefined;
+}
+
+// =============================================================================
+// Login flow
+// =============================================================================
+
+function isAuthFailure(failure: FetchFailure | undefined): boolean {
+	return failure?.kind === "auth" || failure?.kind === "forbidden";
+}
+
+function authFailureMessage(failure: FetchFailure): string {
+	if (failure.error.includes("unsafe_example_api_key")) {
+		return "CLIProxy 服务端仍在使用示例 API Key（unsafe_example_api_key），请先修改服务端 access.api-keys 并重启 CLIProxyAPI。";
+	}
+	return `API Key 验证失败：${failure.error}`;
+}
+
+function normalizeApiKey(value: string): string {
+	return value.trim().replace(/^Bearer\s+/iu, "").trim();
+}
+
+function compactMessage(value: string, maxLength = 180): string {
+	const singleLine = value.replace(/\s+/gu, " ").trim();
+	return singleLine.length > maxLength ? `${singleLine.slice(0, maxLength)}…` : singleLine;
+}
+
+/**
+ * Probe every compatible address, but keep OpenAI first: all OpenAI candidates
+ * (primary scheme, then the implicit http/https alternative) run before Gemini,
+ * and Gemini runs before Anthropic. The first non-empty model list wins.
+ */
+function buildDiscoveryCandidates(roots: string[]): DiscoveryCandidate[] {
+	const candidates: DiscoveryCandidate[] = [];
+	for (const rootUrl of roots) {
+		candidates.push({ api: "openai-completions", rootUrl, baseUrl: openAIBaseUrl(rootUrl) });
+	}
+	for (const rootUrl of roots) {
+		candidates.push({ api: "google-generative-ai", rootUrl, baseUrl: geminiBaseUrl(rootUrl) });
+	}
+	for (const rootUrl of roots) {
+		candidates.push({ api: "anthropic-messages", rootUrl, baseUrl: anthropicBaseUrl(rootUrl) });
+	}
+	return candidates;
+}
+
+function summarizeDiscoveryAttempts(attempts: DiscoveryAttempt[]): string {
+	return attempts
+		.map(
+			({ candidate, failure }) =>
+				`${PROVIDER_APIS[candidate.api]} ${candidate.baseUrl}：${compactMessage(failure.error)}`,
+		)
+		.join("\n");
+}
+
+function firstAuthFailure(attempts: DiscoveryAttempt[]): FetchFailure | undefined {
+	return attempts.find(({ failure }) => isAuthFailure(failure))?.failure;
+}
+
+async function autoDiscoverModels(
+	candidates: DiscoveryCandidate[],
+	apiKey: string,
+	signal: AbortSignal,
+	onAttempt?: (candidate: DiscoveryCandidate, index: number, total: number) => void,
+): Promise<DiscoveryOutcome> {
+	const attempts: DiscoveryAttempt[] = [];
+	let emptySuccess: DiscoveryCandidate | undefined;
+
+	for (const [index, candidate] of candidates.entries()) {
+		onAttempt?.(candidate, index, candidates.length);
+		const result = await fetchModelsForApi(candidate.api, candidate.baseUrl, apiKey, signal);
+		if (result.ok) {
+			if (result.models.length > 0) return { ok: true, candidate, models: result.models };
+			emptySuccess ??= candidate;
+			continue;
+		}
+		attempts.push({ candidate, failure: result });
+	}
+
+	return { ok: false, attempts, ...(emptySuccess ? { empty: emptySuccess } : {}) };
+}
+
+async function runLogin(interaction: ProviderAuthInteraction): Promise<ApiKeyCredential> {
+	const domainInput = await interaction.prompt({
+		type: "text",
+		message: "CLIProxy 绑定域名（例如 proxy.example.com 或 https://proxy.example.com）",
+		placeholder: "proxy.example.com",
+	});
+	if (!domainInput.trim()) throw new Error("未输入绑定域名");
+
+	const { rootUrl: initialRootUrl, implicitScheme } = normalizeDomain(domainInput);
+	const promptForApiKey = async (message: string): Promise<string> => {
+		const value = normalizeApiKey(
+			await interaction.prompt({
+				type: "secret",
+				message,
+				placeholder: "sk-...",
+			}),
+		);
+		if (!value) throw new Error("未输入 API Key");
+		return value;
+	};
+	let apiKey = await promptForApiKey("CLIProxy API Key（保存在 pi 的 auth.json）");
+
+	// A bare host may be either http or https; only try the alternate scheme
+	// automatically when the user did not spell one out.
+	const roots = [initialRootUrl];
+	if (implicitScheme) {
+		const alternate = swapScheme(initialRootUrl);
+		if (alternate) roots.push(alternate);
+	}
+
+	let activeRoot = initialRootUrl;
+	let api: SupportedApi = "openai-completions";
+	let baseUrl = openAIBaseUrl(initialRootUrl);
+	let models: StoredModel[] = [];
+	let source: "auto" | "manual" = "auto";
+	let lastError: string | undefined;
+
+	const candidates = buildDiscoveryCandidates(roots);
+	const discover = async (): Promise<DiscoveryOutcome> =>
+		autoDiscoverModels(candidates, apiKey, interaction.signal, (candidate, index, total) => {
+			interaction.notify({
+				type: "progress",
+				message: `正在尝试 ${PROVIDER_APIS[candidate.api]}：${candidate.baseUrl}（${index + 1}/${total}）…`,
+			});
+		});
+
+	let outcome = await discover();
+
+	// A rejected key applies to every protocol, so only ask again after all
+	// compatible addresses have been tried. This keeps the login flow automatic
+	// while still surfacing a real credential problem instead of hiding it in
+	// the address picker.
+	if (!outcome.ok) {
+		let authFailure = firstAuthFailure(outcome.attempts);
+		if (authFailure?.error.includes("unsafe_example_api_key")) {
+			throw new Error(authFailureMessage(authFailure));
+		}
+		if (authFailure) {
+			interaction.notify({
+				type: "info",
+				message: `所有兼容地址都未能通过鉴权：${compactMessage(authFailure.error)}\n请重新输入一次 API Key。`,
+			});
+			apiKey = await promptForApiKey("重新输入 CLIProxy API Key");
+			outcome = await discover();
+			authFailure = outcome.ok ? undefined : firstAuthFailure(outcome.attempts);
+			if (authFailure) throw new Error(authFailureMessage(authFailure));
+		}
+	}
+
+	if (outcome.ok) {
+		activeRoot = outcome.candidate.rootUrl;
+		baseUrl = outcome.candidate.baseUrl;
+		api = outcome.candidate.api;
+		models = outcome.models;
+		lastError = undefined;
+		interaction.notify({
+			type: "info",
+			message: `自动选择 ${PROVIDER_APIS[api]}：${baseUrl}（${models.length} 个模型）。`,
+		});
+	} else if (outcome.empty) {
+		// Every address answered, but no upstream credentials are available.
+		// Picking another address would not help; go straight to manual IDs.
+		activeRoot = outcome.empty.rootUrl;
+		baseUrl = outcome.empty.baseUrl;
+		api = outcome.empty.api;
+		models = [];
+		lastError = "所有兼容地址均返回空模型列表";
+	} else {
+		const responding = outcome.attempts.find(({ failure }) => failure.kind !== "network");
+		activeRoot = responding?.candidate.rootUrl ?? initialRootUrl;
+		lastError = summarizeDiscoveryAttempts(outcome.attempts) || "未知错误";
+
+		const diagnostic = await probeCliproxy(activeRoot, interaction.signal);
+		interaction.notify({
+			type: "info",
+			message: `已自动尝试 ${outcome.attempts.length} 个兼容地址，均未获取到模型列表：\n${lastError}${diagnostic ? `\n${diagnostic}` : ""}`,
+		});
+
+		const choice = await interaction.prompt({
+			type: "select",
+			message: "请选择 CLIProxy 兼容地址",
+			options: [
+				{ id: "retry-openai", label: `重试 OpenAI 兼容地址：${openAIBaseUrl(activeRoot)}` },
+				{ id: "anthropic", label: `Anthropic 兼容地址：${anthropicBaseUrl(activeRoot)}` },
+				{ id: "gemini", label: `Gemini 兼容地址：${geminiBaseUrl(activeRoot)}` },
+				{ id: "custom", label: "自定义兼容地址…" },
+			],
+		});
+
+		if (choice === "retry-openai") {
+			api = "openai-completions";
+			baseUrl = openAIBaseUrl(activeRoot);
+			const retry = await fetchOpenAIModels(baseUrl, apiKey, interaction.signal);
+			if (!retry.ok && isAuthFailure(retry)) throw new Error(authFailureMessage(retry));
+			if (retry.ok) {
+				models = retry.models;
+				lastError = undefined;
+			} else {
+				lastError = retry.error;
+			}
+		} else if (choice === "anthropic") {
+			api = "anthropic-messages";
+			baseUrl = anthropicBaseUrl(activeRoot);
+			const anthropic = await fetchAnthropicModels(baseUrl, apiKey, interaction.signal);
+			if (!anthropic.ok && isAuthFailure(anthropic)) throw new Error(authFailureMessage(anthropic));
+			if (anthropic.ok) {
+				models = anthropic.models;
+				lastError = undefined;
+			} else {
+				lastError = anthropic.error;
+				if (anthropic.kind === "unsupported") {
+					interaction.notify({
+						type: "info",
+						message: "该 Anthropic 兼容地址没有模型列表端点，请在下一步手动输入模型 ID。",
+					});
+				}
+			}
+		} else if (choice === "gemini") {
+			api = "google-generative-ai";
+			baseUrl = geminiBaseUrl(activeRoot);
+			const gemini = await fetchGeminiModels(baseUrl, apiKey, interaction.signal);
+			if (!gemini.ok && isAuthFailure(gemini)) throw new Error(authFailureMessage(gemini));
+			if (gemini.ok) {
+				models = gemini.models;
+				lastError = undefined;
+			} else {
+				lastError = gemini.error;
+			}
+		} else {
+			const customInput = (
+				await interaction.prompt({
+					type: "text",
+					message: "自定义兼容地址（完整 base URL，例如 https://proxy.example.com/v1）",
+					placeholder: "https://proxy.example.com/v1",
+				})
+			).trim();
+			if (!customInput) throw new Error("未输入自定义地址");
+			const protocolChoice = await interaction.prompt({
+				type: "select",
+				message: "该地址使用的兼容协议",
+				options: [
+					{ id: "openai", label: "OpenAI 兼容（/v1/chat/completions）" },
+					{ id: "anthropic", label: "Anthropic 兼容（/v1/messages）" },
+					{ id: "gemini", label: "Gemini 兼容（/v1beta）" },
+				],
+			});
+			api =
+				protocolChoice === "anthropic"
+					? "anthropic-messages"
+					: protocolChoice === "gemini"
+						? "google-generative-ai"
+						: "openai-completions";
+			baseUrl = trimTrailingSlashes(customInput);
+			const retry = await fetchModelsForApi(api, baseUrl, apiKey, interaction.signal);
+			if (!retry.ok && isAuthFailure(retry)) throw new Error(authFailureMessage(retry));
+			if (retry.ok) {
+				models = retry.models;
+				lastError = undefined;
+			} else {
+				lastError = retry.error;
+			}
+		}
+	}
+
+	if (models.length === 0) {
+		const manual = await interaction.prompt({
+			type: "text",
+			message: "未获取到模型列表。可手动输入模型 ID（逗号或空格分隔，留空则暂不添加模型）",
+			placeholder: "claude-sonnet-4-5, gemini-2.5-pro",
+		});
+		models = parseManualModelIds(manual);
+		source = "manual";
+	}
+
+	const configBase: CliproxyConfig = {
+		version: CONFIG_VERSION,
+		domain: domainInput.trim(),
+		rootUrl: activeRoot,
+		baseUrl,
+		api,
+		models: [],
+		source,
+		updatedAt: 0,
+	};
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const enriched = models.map((entry) => enrichModel(entry, configBase, metadata, storeMetadata, builtin));
+	const config: CliproxyConfig = {
+		...configBase,
+		models: enriched,
+		updatedAt: Date.now(),
+		...(lastError && enriched.length === 0 ? { lastError } : {}),
+	};
+	try {
+		writeConfig(config);
+	} catch (error) {
+		throw new Error(
+			`CLIProxy 配置写入失败：${error instanceof Error ? error.message : String(error)}（${configPath()}）`,
+		);
+	}
+
+	if (models.length > 0) {
+		interaction.notify({
+			type: "info",
+			message: `CLIProxy 配置已保存：${baseUrl}（${models.length} 个模型，${PROVIDER_APIS[api]}）。`,
+		});
+	} else {
+		interaction.notify({
+			type: "info",
+			message: `CLIProxy 配置已保存：${baseUrl}，但暂未导入任何模型。可使用 /cliproxy refresh 重试。`,
+		});
+	}
+
+	return { type: "api_key", key: apiKey };
+}
+
+// =============================================================================
+// Dynamic model discovery
+// =============================================================================
+
+async function refreshProviderModels(context: RefreshModelsContext): Promise<readonly Model<Api>[]> {
+	const config = readConfig();
+	if (!config) return [];
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const cached = config.models.map((entry) => toModel(entry, config, metadata, storeMetadata, builtin));
+	const apiKey = credentialKey(context.credential);
+	if (!apiKey) return cached;
+
+	// Opening /model asks for a refresh every time. Reuse a recent snapshot
+	// unless the caller explicitly forces it (/cliproxy refresh) or it is stale.
+	const fresh = config.updatedAt > 0 && Date.now() - config.updatedAt < MODEL_REFRESH_TTL_MS;
+	if (!context.force && fresh) return cached;
+
+	const result = await fetchModelsForApi(config.api, config.baseUrl, apiKey, context.signal);
+	if (context.signal.aborted) return cached;
+	if (!result.ok) {
+		// CLIProxyAPI's Anthropic endpoint may not expose /v1/models at all.
+		// That is expected, not a refresh error; keep the cached catalog.
+		if (result.kind === "unsupported") return cached;
+		lastRefreshError = result.error;
+		if (config.lastError !== result.error) {
+			try {
+				writeConfig({ ...config, lastError: result.error });
+			} catch {
+				// Keep serving the cached catalog even if the error cannot be persisted.
+			}
+		}
+		return cached;
+	}
+	lastRefreshError = undefined;
+	const fetched = result.models;
+	// An empty upstream list is legitimate (no credentials/cooldown). Keep
+	// manually entered models but do honor real automatic empties.
+	if (fetched.length === 0 && config.source === "manual") {
+		try {
+			writeConfig({
+				...config,
+				updatedAt: Date.now(),
+				lastError: "上游返回的模型列表为空（保留手动模型）",
+			});
+		} catch {
+			// Best effort.
+		}
+		return cached;
+	}
+
+	const enriched = fetched.map((entry) => enrichModel(entry, config, metadata, storeMetadata, builtin));
+	const updated: CliproxyConfig = {
+		...config,
+		models: enriched,
+		source: "auto",
+		updatedAt: Date.now(),
+		...(enriched.length === 0 ? { lastError: "上游返回的模型列表为空" } : {}),
+	};
+	if (enriched.length > 0) delete updated.lastError;
+	try {
+		writeConfig(updated);
+	} catch {
+		// Model discovery still works in memory even if the cache cannot be persisted.
+	}
+	return enriched.map((entry) => toModel(entry, updated, metadata, storeMetadata, builtin));
+}
+
+// =============================================================================
+// Provider registration
+// =============================================================================
+
+function buildProvider(config: CliproxyConfig | undefined): Provider {
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const models = config
+		? config.models.map((entry) => toModel(entry, config, metadata, storeMetadata, builtin))
+		: [];
+	const api: Partial<Record<Api, ProviderStreams>> = {
+		"openai-completions": openAICompletionsApi(),
+		"anthropic-messages": anthropicMessagesApi(),
+		"google-generative-ai": googleGenerativeAIApi(),
+	};
+	return createProvider({
+		id: PROVIDER_ID,
+		name: PROVIDER_NAME,
+		auth: {
+			apiKey: {
+				name: AUTH_NAME,
+				login: runLogin,
+				resolve: async ({ credential }) =>
+					credential?.key
+						? { auth: { apiKey: credential.key }, source: "stored credential" }
+						: undefined,
+			},
+		},
+		// Baseline models come from cliproxy.json so offline startup and
+		// `pi --list-models` work without a models-store entry. Dynamic
+		// fetchModels() refreshes them; model-level baseUrl is authoritative.
+		models,
+		fetchModels: refreshProviderModels,
+		api,
+	});
+}
+
+// =============================================================================
+// Extension entry point
+// =============================================================================
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerProvider(buildProvider(readConfig()));
+
+	pi.registerCommand("cliproxy", {
+		description: "查看 CLIProxy 配置，或执行 /cliproxy refresh 刷新模型列表",
+		handler: async (args, ctx) => {
+			const subcommand = args.trim().toLowerCase();
+			const config = readConfig();
+
+			if (subcommand === "refresh") {
+				if (!config) {
+					ctx.ui.notify("尚未配置 CLIProxy。请运行 /login 并选择“Sign in with an API key” → CLIProxy。", "warning");
+					return;
+				}
+				let refreshError: string | undefined;
+				try {
+					const result = await ctx.modelRegistry.refresh({
+						providers: [PROVIDER_ID],
+						force: true,
+						signal: AbortSignal.timeout(20_000),
+					});
+					refreshError = result.errors.get(PROVIDER_ID)?.message;
+				} catch (error) {
+					refreshError = error instanceof Error ? error.message : String(error);
+				}
+				const count = ctx.modelRegistry.getAll().filter((model) => model.provider === PROVIDER_ID).length;
+				if (refreshError) {
+					ctx.ui.notify(`CLIProxy 模型刷新失败：${refreshError}`, "error");
+				} else if (lastRefreshError) {
+					ctx.ui.notify(`CLIProxy 模型刷新失败，继续使用缓存（共 ${count} 个）：${lastRefreshError}`, "warning");
+				} else if (count === 0) {
+					ctx.ui.notify("CLIProxy 已刷新，但仍未获取到模型。请检查 API Key 或运行 /login 重新配置。", "warning");
+				} else {
+					ctx.ui.notify(`CLIProxy 模型已刷新，共 ${count} 个。`, "info");
+				}
+				return;
+			}
+
+			if (!config) {
+				ctx.ui.notify(
+					`尚未配置 CLIProxy。\n请运行 /login → “Sign in with an API key” → CLIProxy，输入绑定域名和 API Key。\n配置将写入：${configPath()}`,
+					"info",
+				);
+				return;
+			}
+
+			const count = ctx.modelRegistry.getAll().filter((model) => model.provider === PROVIDER_ID).length;
+			const lastError = lastRefreshError ?? config.lastError;
+			const lines = [
+				`CLIProxy：${config.baseUrl}`,
+				`协议：${PROVIDER_APIS[config.api]}（${config.api}）`,
+				`模型：${count} 个${config.models.length !== count ? `（缓存 ${config.models.length} 个）` : ""}`,
+				`配置：${configPath()}`,
+				lastError ? `最近错误：${lastError}` : undefined,
+				"重新配置：/login → “Sign in with an API key” → CLIProxy",
+				"刷新模型：/cliproxy refresh",
+			].filter((line): line is string => Boolean(line));
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}