pi-model-manager 0.1.0

package/common.ts

@@ -0,0 +1,66 @@
+// 通用小工具：JSON 解析、字符串处理、错误格式化、克隆。
+// 与 pi-model-add/common.ts 等价；后续 step 不再依赖旧插件。
+
+export function isObjectRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function stripJsonNoise(source: string): string {
+	return source
+		.replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (match) => (match.startsWith('"') ? match : ""))
+		.replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (match, tail) => tail ?? (match.startsWith('"') ? match : ""));
+}
+
+export function trimOrFallback(value: string | undefined, fallback: string): string {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : fallback;
+}
+
+export function trimSingleLine(value: string): string {
+	return value.replace(/[\r\n]+/g, " ").trim();
+}
+
+export function trimSingleLineOrFallback(value: string | undefined, fallback: string): string {
+	const singleLine = value?.replace(/[\r\n]+/g, " ").trim();
+	return singleLine ? singleLine : fallback;
+}
+
+export function formatUnknownError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function cloneStringRecord(record: Record<string, string> | undefined): Record<string, string> {
+	return { ...(record ?? {}) };
+}
+
+export function hasStringRecordEntries(record: Record<string, string> | undefined): boolean {
+	return record !== undefined && Object.keys(record).length > 0;
+}
+
+export function parseStringRecordJson(source: string, label: string): Record<string, string> {
+	const parsed = JSON.parse(stripJsonNoise(source));
+	if (!isObjectRecord(parsed)) throw new Error(`${label} JSON 必须是对象`);
+	const record: Record<string, string> = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value !== "string") throw new Error(`${label} ${key} 的值必须是字符串`);
+		const trimmedKey = key.trim();
+		if (trimmedKey) record[trimmedKey] = value;
+	}
+	return record;
+}
+
+export function stringifyJson(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function cloneJson<T>(value: T): T {
+	return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+
+export function slugifyName(name: string): string {
+	return name
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}

package/compat-settings.ts

@@ -0,0 +1,25 @@
+// Pi 会把 provider 级 compat 作为默认值，再由模型级 compat 覆盖。
+// 动态 registerProvider 不接受 provider.compat，因此插件注册前在这里复现相同合并语义。
+
+import { isObjectRecord } from "./common.ts";
+import type { CompatSettings } from "./types.ts";
+
+const NESTED_COMPAT_FIELDS = ["openRouterRouting", "vercelGatewayRouting", "chatTemplateKwargs"] as const;
+
+export function mergeCompatSettings(
+	providerCompat: CompatSettings | undefined,
+	modelCompat: CompatSettings | undefined,
+): CompatSettings | undefined {
+	if (!providerCompat && !modelCompat) return undefined;
+	const merged: CompatSettings = { ...providerCompat, ...modelCompat };
+	for (const field of NESTED_COMPAT_FIELDS) {
+		const providerValue = providerCompat?.[field];
+		const modelValue = modelCompat?.[field];
+		if (!isObjectRecord(providerValue) && !isObjectRecord(modelValue)) continue;
+		merged[field] = {
+			...(isObjectRecord(providerValue) ? providerValue : {}),
+			...(isObjectRecord(modelValue) ? modelValue : {}),
+		};
+	}
+	return merged;
+}

package/config-value-reference.ts

@@ -0,0 +1,51 @@
+// Pi 配置值允许字面量、!command，以及 $NAME/${NAME} 环境变量模板。
+// 这里只解析展示认证状态所需的引用信息，不执行命令或展开敏感值。
+
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_VAR_NAME_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+export function isCommandConfigValue(config: string): boolean {
+	return config.startsWith("!");
+}
+
+/** [喵喵喵]: 与 Pi 0.80.10 模板语义保持一致，包括嵌入引用和 $$/$! 转义 (2026-07-17) */
+export function getConfigValueEnvVarNames(config: string): string[] {
+	if (isCommandConfigValue(config)) return [];
+	const names: string[] = [];
+	let index = 0;
+	while (index < config.length) {
+		const dollarIndex = config.indexOf("$", index);
+		if (dollarIndex < 0) break;
+		const nextCharacter = config[dollarIndex + 1];
+		if (nextCharacter === "$" || nextCharacter === "!") {
+			index = dollarIndex + 2;
+			continue;
+		}
+		if (nextCharacter === "{") {
+			const endIndex = config.indexOf("}", dollarIndex + 2);
+			if (endIndex < 0) {
+				index = dollarIndex + 1;
+				continue;
+			}
+			const name = config.slice(dollarIndex + 2, endIndex);
+			if (ENV_VAR_NAME_PATTERN.test(name) && !names.includes(name)) names.push(name);
+			index = endIndex + 1;
+			continue;
+		}
+		const match = config.slice(dollarIndex + 1).match(ENV_VAR_NAME_PREFIX_PATTERN);
+		if (match) {
+			if (!names.includes(match[0])) names.push(match[0]);
+			index = dollarIndex + 1 + match[0].length;
+			continue;
+		}
+		index = dollarIndex + 1;
+	}
+	return names;
+}
+
+export function getSingleConfigValueEnvVarName(config: string): string | undefined {
+	const bracedMatch = config.match(/^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
+	if (bracedMatch) return bracedMatch[1];
+	const unbracedMatch = config.match(/^\$([A-Za-z_][A-Za-z0-9_]*)$/);
+	return unbracedMatch?.[1];
+}

package/configuration-persistence.ts

@@ -0,0 +1,72 @@
+// 模型管理保存边界：models.json 是模型权威源，state.json 仅承载插件 metadata。
+// 两个文件无法组成单一原子事务；写入完成后必须 reload 当前 registry，清除旧 models.json 配置层。
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatUnknownError } from "./common.ts";
+import {
+	syncModelRenameToModelsJson,
+	syncProviderRenameToModelsJson,
+	syncStateToModelsJson,
+} from "./models-json-sync.ts";
+import { invalidateStateCache } from "./state-cache.ts";
+import { writeState } from "./state-store.ts";
+import type { StateDocument } from "./types.ts";
+
+async function persistModelsThenMetadata(
+	ctx: ExtensionCommandContext,
+	document: StateDocument,
+	writeModelsJson: () => Promise<void>,
+): Promise<void> {
+	try {
+		await writeModelsJson();
+		invalidateStateCache();
+	} catch (error) {
+		throw new Error(`models.json 未写入：${formatUnknownError(error)}`);
+	}
+	try {
+		await writeState(document);
+		invalidateStateCache();
+	} catch (error) {
+		throw new Error(`models.json 已写入，但 state.json metadata 写入失败：${formatUnknownError(error)}`);
+	}
+	try {
+		await ctx.modelRegistry.refresh();
+	} catch (error) {
+		throw new Error(`models.json/state.json 已写入，但当前会话 registry 重载失败：${formatUnknownError(error)}。可执行 /reload 重试。`);
+	}
+}
+
+export async function persistManagedConfiguration(
+	ctx: ExtensionCommandContext,
+	document: StateDocument,
+	removedProviderIds: string[] = [],
+): Promise<void> {
+	await persistModelsThenMetadata(ctx, document, () => syncStateToModelsJson(document, removedProviderIds));
+}
+
+export async function persistProviderRenameConfiguration(
+	ctx: ExtensionCommandContext,
+	document: StateDocument,
+	oldProviderId: string,
+	newProviderId: string,
+): Promise<void> {
+	await persistModelsThenMetadata(
+		ctx,
+		document,
+		() => syncProviderRenameToModelsJson(document, oldProviderId, newProviderId),
+	);
+}
+
+export async function persistModelRenameConfiguration(
+	ctx: ExtensionCommandContext,
+	document: StateDocument,
+	providerId: string,
+	oldModelId: string,
+	newModelId: string,
+): Promise<void> {
+	await persistModelsThenMetadata(
+		ctx,
+		document,
+		() => syncModelRenameToModelsJson(document, providerId, oldModelId, newModelId),
+	);
+}

package/header-profile-mutations.ts

@@ -0,0 +1,46 @@
+// header-profile-mutations.ts
+//
+// 自定义请求头 profile 的事务层：集中处理 state/models.json 持久化和 runtime provider 刷新。
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { persistManagedConfiguration } from "./configuration-persistence.ts";
+import { registerAllFromState } from "./provider-registrar.ts";
+import { deleteRequestHeaderProfileFromDocument, upsertRequestHeaderProfileInDocument } from "./state-document.ts";
+import type { RequestHeaderProfileDraft, StateDocument } from "./types.ts";
+
+function notifyHeaderProfileRefresh(
+	ctx: ExtensionCommandContext,
+	successMessage: string,
+	warnings: string[],
+): void {
+	if (warnings.length === 0) {
+		ctx.ui.notify(successMessage, "info");
+		return;
+	}
+	ctx.ui.notify(`${successMessage}，但以下接入未能刷新，已保留上一版 runtime：\n- ${warnings.join("\n- ")}`, "warning");
+}
+
+export async function saveRequestHeaderProfileConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	state: StateDocument,
+	draft: RequestHeaderProfileDraft,
+	oldProfileId: string | undefined,
+): Promise<void> {
+	const nextState = upsertRequestHeaderProfileInDocument(state, oldProfileId, draft);
+	await persistManagedConfiguration(ctx, nextState);
+	const warnings = await registerAllFromState(pi, nextState);
+	notifyHeaderProfileRefresh(ctx, `已保存请求头 ${draft.profileId.trim()}`, warnings);
+}
+
+export async function deleteRequestHeaderProfileConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	state: StateDocument,
+	profileId: string,
+): Promise<void> {
+	const nextState = deleteRequestHeaderProfileFromDocument(state, profileId);
+	await persistManagedConfiguration(ctx, nextState);
+	const warnings = await registerAllFromState(pi, nextState);
+	notifyHeaderProfileRefresh(ctx, `已删除请求头 ${profileId}`, warnings);
+}

package/index.ts

@@ -0,0 +1,82 @@
+// pi-model-manager 主入口
+//
+// factory 阶段（pi 会等待）读取配置并注册模型 catalog，但不启动长生命周期本地代理。
+// session_start 再激活完整 provider transport，session_shutdown 幂等关闭代理服务。
+//
+// models.json 是模型定义唯一来源；state.json 只保存请求头 profile、抓包缓存、service_tier 等插件私有元数据。
+// 启动期通知用 session_start 事件 + ctx.ui.notify（factory 期没有 ctx）。
+//
+// 命令：/model-manager → TUI 面板
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatUnknownError } from "./common.ts";
+import { resetClaudeCodeMetadataSession } from "./claude-code-compat.ts";
+import { closeLocalProxyServer } from "./local-proxy-service.ts";
+import { registerAllFromState, registerCatalogFromState } from "./provider-registrar.ts";
+import { createRequestPipeline } from "./request-pipeline.ts";
+import { createEmptyState, readState } from "./state-store.ts";
+import { runDashboard } from "./tui/dashboard.ts";
+
+interface StartupSummary {
+	startupErrors: string[];
+}
+
+export default async function modelManagerExtension(pi: ExtensionAPI): Promise<void> {
+	const summary: StartupSummary = { startupErrors: [] };
+
+	// ---- 1. 读原生模型配置 + 插件元数据 ----
+	try {
+		const stateForStartup = await readState().catch((error) => {
+			summary.startupErrors.push(`读取 models.json/state.json 失败：${formatUnknownError(error)}（本次启动仅使用内存空配置，不覆盖原文件）`);
+			return createEmptyState();
+		});
+		for (const warning of await registerCatalogFromState(pi, stateForStartup)) {
+			summary.startupErrors.push(`注册模型目录失败：${warning}`);
+		}
+	} catch (error) {
+		summary.startupErrors.push(`读取/注册模型配置失败：${formatUnknownError(error)}`);
+	}
+
+	// ---- 2. session_start 激活 transport 并汇报 ----
+	let notified = false;
+	const requestPipeline = createRequestPipeline();
+	pi.on("session_start", async (event, ctx) => {
+		resetClaudeCodeMetadataSession();
+		const transportErrors: string[] = [];
+		try {
+			const currentState = await readState();
+			for (const warning of await registerAllFromState(pi, currentState)) {
+				transportErrors.push(`激活模型接入失败：${warning}`);
+			}
+		} catch (error) {
+			transportErrors.push(`读取或激活模型配置失败：${formatUnknownError(error)}`);
+		}
+
+		if (event.reason === "startup" && !notified) {
+			notified = true;
+			for (const error of summary.startupErrors) {
+				ctx.ui.notify(`[pi-model-manager] ${error}`, "error");
+			}
+		}
+		for (const error of transportErrors) {
+			ctx.ui.notify(`[pi-model-manager] ${error}`, "error");
+		}
+	});
+
+	pi.on("before_provider_request", async (event, ctx) => requestPipeline.transform(event.payload, ctx));
+	pi.on("session_shutdown", async () => {
+		await closeLocalProxyServer();
+	});
+
+	// ---- 3. 命令：/model-manager → TUI 面板 ----
+	pi.registerCommand("model-manager", {
+		description: "模型接入与请求配置",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/model-manager 需要 TUI 交互模式", "error");
+				return;
+			}
+			await runDashboard(pi, ctx);
+		},
+	});
+}

package/local-proxy-service.ts

@@ -0,0 +1,313 @@
+// local-proxy-service.ts
+//
+// 插件内置的按接入点代理转发层。
+// 不修改 pi 本体：开启代理的接入点在运行时注册为 127.0.0.1 本地地址，
+// 本服务再通过用户配置的 HTTP/HTTPS 代理转发到真实上游。
+
+import http, { type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from "node:http";
+import https from "node:https";
+import { HttpProxyAgent } from "http-proxy-agent";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import type { StoredProvider } from "./types.ts";
+import { DEFAULT_PROVIDER_HTTP_PROXY_URL } from "./types.ts";
+
+export interface ProviderProxyRoute {
+	upstreamOrigin: string;
+	proxyUrl: string;
+}
+
+export interface TemporaryLocalProxyRoute {
+	url: string;
+	close(): void;
+}
+
+const ROUTES = new Map<string, ProviderProxyRoute>();
+let server: http.Server | undefined;
+let listenPromise: Promise<number> | undefined;
+let listenPort: number | undefined;
+let temporaryRouteSequence = 0;
+
+const HOP_BY_HOP_HEADERS = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade",
+]);
+
+function trimTrailingSlashes(value: string): string {
+	return value.replace(/\/+$/, "");
+}
+
+function normalizeHttpProxyUrl(proxyUrl: string | undefined): string {
+	return proxyUrl?.trim() || DEFAULT_PROVIDER_HTTP_PROXY_URL;
+}
+
+export function isProviderHttpProxyEnabled(provider: StoredProvider): boolean {
+	return provider.httpProxyEnabled === true;
+}
+
+export function getProviderHttpProxyUrl(provider: StoredProvider): string {
+	return normalizeHttpProxyUrl(provider.httpProxyUrl);
+}
+
+function stripHopByHopHeaders(headers: IncomingHttpHeaders): Record<string, string | string[]> {
+	const next: Record<string, string | string[]> = {};
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === undefined || HOP_BY_HOP_HEADERS.has(name.toLowerCase())) continue;
+		next[name] = value;
+	}
+	return next;
+}
+
+function getUrlPort(url: URL): number {
+	if (url.port) return Number.parseInt(url.port, 10);
+	return url.protocol === "https:" ? 443 : 80;
+}
+
+function getHostHeader(url: URL): string {
+	return url.host;
+}
+
+function ensureSupportedProxyProtocol(proxy: URL): void {
+	if (proxy.protocol !== "http:" && proxy.protocol !== "https:") {
+		throw new Error("代理地址目前只支持 http:// 或 https:// 代理");
+	}
+}
+
+function pipeResponse(upstreamResponse: IncomingMessage, response: ServerResponse): void {
+	const headers = stripHopByHopHeaders(upstreamResponse.headers);
+	response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.statusMessage, headers);
+	// 尽快把 SSE 响应头交给本地客户端，后续 body 由 Node 的 HTTP 栈处理 chunked/backpressure。
+	response.flushHeaders();
+	upstreamResponse.on("error", (error) => {
+		if (!response.destroyed) response.destroy(error);
+	});
+	upstreamResponse.pipe(response);
+}
+
+
+function formatProxyError(error: unknown): string {
+	if (error instanceof Error) {
+		const message = error.message.trim();
+		if (message) return message;
+		const cause = (error as Error & { code?: string }).code;
+		if (cause) return `代理请求失败：${cause}`;
+		if (error.stack?.trim()) return error.stack.trim().split("\n", 1)[0] ?? "未知代理错误";
+		return `${error.name || "Error"}（无错误消息）`;
+	}
+	const message = String(error).trim();
+	return message || "未知代理错误";
+}
+
+function writeProxyError(response: ServerResponse, error: unknown): void {
+	if (response.headersSent) {
+		response.destroy(error instanceof Error ? error : undefined);
+		return;
+	}
+	response.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+	response.end(`[pi-model-manager proxy] ${formatProxyError(error)}`);
+}
+
+function buildForwardRequestHeaders(target: URL, request: IncomingMessage): Record<string, string | string[]> {
+	const headers = stripHopByHopHeaders(request.headers);
+	headers.host = getHostHeader(target);
+	return headers;
+}
+
+function bindClientAbort(request: IncomingMessage, response: ServerResponse, upstreamRequest: http.ClientRequest): void {
+	const destroyUpstream = () => {
+		if (!upstreamRequest.destroyed) upstreamRequest.destroy();
+	};
+	const destroyUpstreamWithError = (error: Error) => {
+		if (!upstreamRequest.destroyed) upstreamRequest.destroy(error);
+	};
+	const onResponseClose = () => {
+		if (!response.writableEnded) destroyUpstream();
+	};
+	const cleanup = () => {
+		request.off("aborted", destroyUpstream);
+		request.off("error", destroyUpstreamWithError);
+		response.off("close", onResponseClose);
+	};
+	request.once("aborted", destroyUpstream);
+	request.once("error", destroyUpstreamWithError);
+	response.once("close", onResponseClose);
+	upstreamRequest.once("close", cleanup);
+}
+
+function writeUpstreamRequestError(response: ServerResponse, error: Error): void {
+	if (response.destroyed || response.writableEnded) return;
+	writeProxyError(response, error);
+}
+
+function forwardPlainHttp(target: URL, proxy: URL, request: IncomingMessage, response: ServerResponse): void {
+	ensureSupportedProxyProtocol(proxy);
+	const headers = buildForwardRequestHeaders(target, request);
+	const agent = new HttpProxyAgent(proxy);
+	const upstreamRequest = http.request({
+		hostname: target.hostname,
+		port: getUrlPort(target),
+		method: request.method,
+		path: `${target.pathname}${target.search}`,
+		headers,
+		agent,
+	}, (upstreamResponse) => pipeResponse(upstreamResponse, response));
+	upstreamRequest.once("close", () => agent.destroy());
+	bindClientAbort(request, response, upstreamRequest);
+	upstreamRequest.on("error", (error) => writeUpstreamRequestError(response, error));
+	// [喵喵喵]: 请求体直接流向上游，避免图像等大 payload 在本地代理中形成完整内存副本 (2026-07-17)
+	request.pipe(upstreamRequest);
+}
+
+function forwardHttps(target: URL, proxy: URL, request: IncomingMessage, response: ServerResponse): void {
+	ensureSupportedProxyProtocol(proxy);
+	const headers = buildForwardRequestHeaders(target, request);
+	const agent = new HttpsProxyAgent(proxy);
+	const upstreamRequest = https.request({
+		hostname: target.hostname,
+		port: getUrlPort(target),
+		method: request.method,
+		path: `${target.pathname}${target.search}`,
+		headers,
+		agent,
+	}, (upstreamResponse) => pipeResponse(upstreamResponse, response));
+	upstreamRequest.once("close", () => agent.destroy());
+	bindClientAbort(request, response, upstreamRequest);
+	upstreamRequest.on("error", (error) => writeUpstreamRequestError(response, error));
+	request.pipe(upstreamRequest);
+}
+
+function forwardRequest(route: ProviderProxyRoute, request: IncomingMessage, response: ServerResponse, routePath: string): void {
+	const target = new URL(routePath, route.upstreamOrigin);
+	const proxy = new URL(route.proxyUrl);
+	if (target.protocol === "http:") {
+		forwardPlainHttp(target, proxy, request, response);
+		return;
+	}
+	if (target.protocol === "https:") {
+		forwardHttps(target, proxy, request, response);
+		return;
+	}
+	throw new Error(`不支持的上游协议：${target.protocol}`);
+}
+
+function handleRequest(request: IncomingMessage, response: ServerResponse): void {
+	void (async () => {
+		try {
+			const localUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+			const [, encodedProviderId, ...rest] = localUrl.pathname.split("/");
+			if (!encodedProviderId) {
+				response.writeHead(404);
+				response.end("missing provider id");
+				return;
+			}
+			const providerId = decodeURIComponent(encodedProviderId);
+			const route = ROUTES.get(providerId);
+			if (!route) {
+				response.writeHead(404);
+				response.end(`unknown provider: ${providerId}`);
+				return;
+			}
+			const path = `/${rest.join("/")}${localUrl.search}`;
+			await forwardRequest(route, request, response, path);
+		} catch (error) {
+			writeProxyError(response, error);
+		}
+	})();
+}
+
+async function ensureServer(): Promise<number> {
+	if (listenPort !== undefined) return listenPort;
+	if (listenPromise) return listenPromise;
+	server = http.createServer(handleRequest);
+	listenPromise = new Promise((resolve, reject) => {
+		server!.once("error", reject);
+		server!.listen(0, "127.0.0.1", () => {
+			const address = server!.address();
+			if (!address || typeof address === "string") {
+				reject(new Error("本地代理转发服务监听地址异常"));
+				return;
+			}
+			listenPort = address.port;
+			server!.off("error", reject);
+			server!.unref();
+			resolve(address.port);
+		});
+	});
+	return listenPromise;
+}
+
+export async function getLocalProxyBaseUrl(routeId: string, upstreamRuntimeBaseUrl: string, proxyUrl: string): Promise<string> {
+	const upstream = new URL(upstreamRuntimeBaseUrl);
+	const proxy = new URL(normalizeHttpProxyUrl(proxyUrl));
+	ensureSupportedProxyProtocol(proxy);
+	const port = await ensureServer();
+	ROUTES.set(routeId, {
+		upstreamOrigin: upstream.origin,
+		proxyUrl: proxy.toString(),
+	});
+	const basePath = trimTrailingSlashes(upstream.pathname || "");
+	return `http://127.0.0.1:${port}/${encodeURIComponent(routeId)}${basePath}${upstream.search}`;
+}
+
+export async function openTemporaryLocalProxyRoute(
+	providerId: string,
+	upstreamUrl: string,
+	proxyUrl: string,
+): Promise<TemporaryLocalProxyRoute> {
+	const upstream = new URL(upstreamUrl);
+	const proxy = new URL(normalizeHttpProxyUrl(proxyUrl));
+	ensureSupportedProxyProtocol(proxy);
+	const port = await ensureServer();
+	const routeId = `${providerId}/model-list/${++temporaryRouteSequence}`;
+	const route = { upstreamOrigin: upstream.origin, proxyUrl: proxy.toString() };
+	ROUTES.set(routeId, route);
+	return {
+		url: `http://127.0.0.1:${port}/${encodeURIComponent(routeId)}${upstream.pathname}${upstream.search}`,
+		close(): void {
+			if (ROUTES.get(routeId) === route) ROUTES.delete(routeId);
+		},
+	};
+}
+
+function isProviderRouteId(routeId: string, providerId: string): boolean {
+	return routeId === providerId || routeId.startsWith(`${providerId}/`);
+}
+
+export function snapshotProviderLocalProxyRoutes(providerId: string): Map<string, ProviderProxyRoute> {
+	return new Map(
+		[...ROUTES.entries()]
+			.filter(([routeId]) => isProviderRouteId(routeId, providerId))
+			.map(([routeId, route]): [string, ProviderProxyRoute] => [routeId, { ...route }]),
+	);
+}
+
+export function restoreProviderLocalProxyRoutes(
+	providerId: string,
+	snapshot: ReadonlyMap<string, ProviderProxyRoute>,
+): void {
+	removeProviderLocalProxyRoutes(providerId);
+	for (const [routeId, route] of snapshot) ROUTES.set(routeId, { ...route });
+}
+
+export function removeProviderLocalProxyRoutes(providerId: string): void {
+	for (const routeId of ROUTES.keys()) {
+		if (isProviderRouteId(routeId, providerId)) ROUTES.delete(routeId);
+	}
+}
+
+export async function closeLocalProxyServer(): Promise<void> {
+	ROUTES.clear();
+	listenPromise = undefined;
+	listenPort = undefined;
+	const current = server;
+	server = undefined;
+	if (!current) return;
+	await new Promise<void>((resolve, reject) => {
+		current.close((error) => error ? reject(error) : resolve());
+	});
+}