pi-model-manager 0.1.0

package/presets/client-headers.ts

@@ -0,0 +1,126 @@
+// 客户端请求头：5 个模式（recommended / disabled / claude-code / codex-cli / custom）。
+// ClaudeCode profile 的 body metadata 信号由 ../claude-code-compat.ts 在请求发送前补齐。
+//
+// [喵喵喵]: 内置值由私有抓包工具生成，公开插件不携带捕获能力 (2026-07-26)
+
+import { cloneStringRecord, hasStringRecordEntries } from "../common.ts";
+import type { ApiKind, BuiltInClientHeaderProfileId, ClientHeaderProfileId, CompatSettings, StoredClientHeaderCapture } from "../types.ts";
+import { CLAUDE_CODE_CLIENT_HEADERS, CODEX_CLI_CLIENT_HEADERS } from "./builtin-client-headers.ts";
+
+export const ANTHROPIC_INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
+
+
+export const CLIENT_HEADER_PROFILE_LABELS: Record<ClientHeaderProfileId, string> = {
+	recommended: "自动推荐",
+	disabled: "不添加",
+	"claude-code": "ClaudeCode",
+	"codex-cli": "Codex",
+	custom: "自定义请求头",
+};
+
+function removeAnthropicBetaFeature(headers: Record<string, string>, feature: string): void {
+	const betaHeaderKey = Object.keys(headers).find((name) => name.toLowerCase() === "anthropic-beta");
+	if (!betaHeaderKey) return;
+	const retained = headers[betaHeaderKey]!
+		.split(",")
+		.map((value) => value.trim())
+		.filter((value) => value && value !== feature);
+	if (retained.length > 0) headers[betaHeaderKey] = retained.join(",");
+	else delete headers[betaHeaderKey];
+}
+
+function cloneHeadersForCompat(
+	headers: Record<string, string>,
+	api: ApiKind,
+	compat?: CompatSettings,
+): Record<string, string> {
+	const cloned = cloneStringRecord(headers);
+	if (api === "anthropic-messages" && compat?.forceAdaptiveThinking === true) {
+		removeAnthropicBetaFeature(cloned, ANTHROPIC_INTERLEAVED_THINKING_BETA);
+	}
+	return cloned;
+}
+
+function deleteHeaderCaseInsensitive(headers: Record<string, string>, name: string): void {
+	const normalized = name.toLowerCase();
+	for (const existingName of Object.keys(headers)) {
+		if (existingName.toLowerCase() === normalized) delete headers[existingName];
+	}
+}
+
+/** 模型原生 headers 先保留，插件 profile 对同名字段拥有最终覆盖权。 */
+export function mergeModelRequestHeaders(
+	nativeHeaders: Record<string, string> | undefined,
+	profileHeaders: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+	const merged = cloneStringRecord(nativeHeaders);
+	for (const [name, value] of Object.entries(profileHeaders ?? {})) {
+		deleteHeaderCaseInsensitive(merged, name);
+		merged[name] = value;
+	}
+	return hasStringRecordEntries(merged) ? merged : undefined;
+}
+
+/** 读取 models.json 时剥离当前 profile 管理的字段，避免把生成值误当作用户原生 headers。 */
+export function stripManagedClientHeaders(
+	storedHeaders: Record<string, string> | undefined,
+	profileHeaders: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+	const nativeHeaders = cloneStringRecord(storedHeaders);
+	for (const name of Object.keys(profileHeaders ?? {})) deleteHeaderCaseInsensitive(nativeHeaders, name);
+	return hasStringRecordEntries(nativeHeaders) ? nativeHeaders : undefined;
+}
+
+export function getRecommendedClientHeaderProfile(api: ApiKind): ClientHeaderProfileId {
+	if (api === "anthropic-messages") return "claude-code";
+	if (api === "openai-completions" || api === "openai-responses") return "codex-cli";
+	return "disabled";
+}
+
+export function resolveClientHeaderProfile(profile: ClientHeaderProfileId, api: ApiKind): ClientHeaderProfileId {
+	return profile === "recommended" ? getRecommendedClientHeaderProfile(api) : profile;
+}
+
+export function getClientHeadersForProfile(
+	profile: ClientHeaderProfileId,
+	api: ApiKind,
+	customHeaders: Record<string, string>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>> = {},
+	compat?: CompatSettings,
+): Record<string, string> | undefined {
+	const resolved = resolveClientHeaderProfile(profile, api);
+	if (resolved === "disabled") return undefined;
+	if (resolved === "claude-code") {
+		const headers = hasStringRecordEntries(clientHeaderCaptures[resolved]?.headers)
+			? clientHeaderCaptures[resolved]!.headers
+			: CLAUDE_CODE_CLIENT_HEADERS;
+		return cloneHeadersForCompat(headers, api, compat);
+	}
+	if (resolved === "codex-cli") {
+		const headers = hasStringRecordEntries(clientHeaderCaptures[resolved]?.headers)
+			? clientHeaderCaptures[resolved]!.headers
+			: CODEX_CLI_CLIENT_HEADERS;
+		return cloneStringRecord(headers);
+	}
+	return hasStringRecordEntries(customHeaders) ? cloneHeadersForCompat(customHeaders, api, compat) : undefined;
+}
+
+export function normalizeClientHeaderProfile(value: unknown): ClientHeaderProfileId | undefined {
+	if (value === "recommended" || value === "protocol-default") return "recommended";
+	if (value === "disabled" || value === "claude-code" || value === "codex-cli" || value === "custom") return value;
+	return undefined;
+}
+
+export function inferClientHeaderProfile(stored: unknown, modelHeaders: Record<string, string> | undefined): ClientHeaderProfileId {
+	const normalized = normalizeClientHeaderProfile(stored);
+	if (normalized) return normalized;
+	return hasStringRecordEntries(modelHeaders) ? "custom" : "recommended";
+}
+
+export function getClientHeaderProfileDisplay(profile: ClientHeaderProfileId, api: ApiKind): string {
+	const resolved = resolveClientHeaderProfile(profile, api);
+	if (profile === "recommended") {
+		return `${CLIENT_HEADER_PROFILE_LABELS.recommended} → ${CLIENT_HEADER_PROFILE_LABELS[resolved]}`;
+	}
+	return CLIENT_HEADER_PROFILE_LABELS[profile];
+}

package/presets/providers.ts

@@ -0,0 +1,80 @@
+// 4 种 API 协议的默认预设。新建接入/模型时用，便于一键填好常用字段。
+
+import type { ApiKind, ModelInputKind } from "../types.ts";
+
+export interface ProviderPreset {
+	api: ApiKind;
+	label: string;
+	shortLabel: string;
+	defaultProviderName: string;
+	baseUrl: string;
+	apiKey: string;
+	authHeader: boolean;
+	contextWindow: number;
+	maxTokens: number;
+	inputKinds: ModelInputKind[];
+	defaultReasoning: boolean;
+}
+
+export const PROVIDER_PRESETS: ProviderPreset[] = [
+	{
+		api: "openai-responses",
+		label: "OpenAI Responses — 标准 instructions / input",
+		shortLabel: "OpenAI Responses",
+		defaultProviderName: "openai-responses",
+		baseUrl: "https://api.openai.com/v1",
+		apiKey: "$OPENAI_API_KEY",
+		authHeader: false,
+		contextWindow: 200000,
+		maxTokens: 64000,
+		inputKinds: ["text", "image"],
+		defaultReasoning: true,
+	},
+	{
+		api: "openai-completions",
+		label: "OpenAI Chat Completions — 通用 OpenAI 兼容",
+		shortLabel: "OpenAI Chat",
+		defaultProviderName: "openai-chat",
+		baseUrl: "https://api.openai.com/v1",
+		apiKey: "$OPENAI_API_KEY",
+		authHeader: false,
+		contextWindow: 200000,
+		maxTokens: 64000,
+		inputKinds: ["text", "image"],
+		defaultReasoning: true,
+	},
+	{
+		api: "anthropic-messages",
+		label: "Anthropic Messages — Claude thinking",
+		shortLabel: "Anthropic Messages",
+		defaultProviderName: "anthropic",
+		baseUrl: "https://api.anthropic.com",
+		apiKey: "$ANTHROPIC_API_KEY",
+		authHeader: false,
+		contextWindow: 200000,
+		maxTokens: 64000,
+		inputKinds: ["text", "image"],
+		defaultReasoning: true,
+	},
+	{
+		api: "google-generative-ai",
+		label: "Google Generative AI — Gemini thinking",
+		shortLabel: "Google Generative AI",
+		defaultProviderName: "google",
+		baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+		apiKey: "$GEMINI_API_KEY",
+		authHeader: false,
+		contextWindow: 1048576,
+		maxTokens: 65536,
+		inputKinds: ["text", "image"],
+		defaultReasoning: true,
+	},
+];
+
+export function findPresetForApi(api: ApiKind | undefined): ProviderPreset {
+	return PROVIDER_PRESETS.find((preset) => preset.api === api) ?? PROVIDER_PRESETS[0]!;
+}
+
+export function getProtocolDisplayName(api: ApiKind): string {
+	return findPresetForApi(api).shortLabel;
+}

package/presets/thinking.ts

@@ -0,0 +1,81 @@
+// thinkingLevelMap 的协议默认值与持久化归一化。
+
+import type { ApiKind, CompatSettings, ThinkingLevelMap } from "../types.ts";
+
+const EXTENDED_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+	xhigh: "xhigh",
+	max: "max",
+};
+
+const OPENAI_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+	minimal: null,
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max",
+};
+
+// [喵喵喵]: Gemini 原生 ThinkingLevel 只有 MINIMAL/LOW/MEDIUM/HIGH；pi 的 xhigh/max 必须显式禁用。(2026-07-10)
+const GOOGLE_GENERATIVE_AI_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: null,
+	max: null,
+};
+
+function isLegacyShiftedMaxLadder(map: ThinkingLevelMap): boolean {
+	return map.minimal === "low"
+		&& map.low === "medium"
+		&& map.medium === "high"
+		&& map.high === "xhigh"
+		&& map.xhigh === "max"
+		&& map.max === undefined;
+}
+
+export function buildThinkingLevelMap(api: ApiKind, reasoning: boolean): ThinkingLevelMap | undefined {
+	if (!reasoning) return undefined;
+	if (api === "google-generative-ai") return { ...GOOGLE_GENERATIVE_AI_THINKING_LEVEL_MAP };
+	if (api === "openai-completions" || api === "openai-responses") return { ...OPENAI_THINKING_LEVEL_MAP };
+	return { ...EXTENDED_THINKING_LEVEL_MAP };
+}
+
+export function applyProtocolThinkingLevelLimits(
+	api: ApiKind,
+	thinkingLevelMap: ThinkingLevelMap | undefined,
+): ThinkingLevelMap | undefined {
+	if (api === "google-generative-ai") {
+		return { ...(thinkingLevelMap ?? {}), ...GOOGLE_GENERATIVE_AI_THINKING_LEVEL_MAP };
+	}
+	if (!thinkingLevelMap) return undefined;
+	return { ...thinkingLevelMap, ...EXTENDED_THINKING_LEVEL_MAP };
+}
+
+export function mergeThinkingLevelMap(
+	defaultMap: ThinkingLevelMap | undefined,
+	storedMap: ThinkingLevelMap | undefined,
+): ThinkingLevelMap | undefined {
+	const merged = { ...(defaultMap ?? {}), ...(storedMap ?? {}) };
+	return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+export function normalizeThinkingLevelMap(
+	api: ApiKind,
+	reasoning: boolean,
+	storedMap: ThinkingLevelMap | undefined,
+): ThinkingLevelMap | undefined {
+	if (!reasoning) return undefined;
+	const defaultMap = buildThinkingLevelMap(api, true);
+	if (storedMap && isLegacyShiftedMaxLadder(storedMap)) return defaultMap;
+	return applyProtocolThinkingLevelLimits(api, mergeThinkingLevelMap(defaultMap, storedMap));
+}
+
+export function mergeCompatSettings(
+	providerCompat: CompatSettings | undefined,
+	modelCompat: CompatSettings | undefined,
+): CompatSettings | undefined {
+	if (providerCompat && modelCompat) return { ...providerCompat, ...modelCompat };
+	return modelCompat ?? providerCompat;
+}

package/provider-registrar.ts

@@ -0,0 +1,281 @@
+// provider-registrar.ts
+//
+// StoredProvider → pi 的 ProviderConfig → pi.registerProvider 的统一桥梁。
+//
+// 设计要点：
+//   - factory 阶段只注册无需本地 server 的 catalog 配置；session_start 再激活代理 transport。
+//   - reconcileProvider 是保存后的完整 runtime 同步入口，统一处理 register/unregister 与回滚。
+//   - getClientHeadersForProfile 在这里调，把客户端请求头 profile 翻译成模型级 headers。
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isBuiltinProviderId } from "./builtin-model-catalog.ts";
+import { mergeCompatSettings } from "./compat-settings.ts";
+import { formatUnknownError } from "./common.ts";
+import {
+	getLocalProxyBaseUrl,
+	getProviderHttpProxyUrl,
+	isProviderHttpProxyEnabled,
+	removeProviderLocalProxyRoutes,
+	restoreProviderLocalProxyRoutes,
+	snapshotProviderLocalProxyRoutes,
+	type ProviderProxyRoute,
+} from "./local-proxy-service.ts";
+import { getClientHeadersForProfile, mergeModelRequestHeaders } from "./presets/client-headers.ts";
+import { resolveRuntimeBaseUrl } from "./runtime-base-url.ts";
+import type { ApiKind, BuiltInClientHeaderProfileId, StateDocument, StoredClientHeaderCapture, StoredModel, StoredProvider, StoredRequestHeaderProfile } from "./types.ts";
+
+// pi 的 ProviderConfig 类型从 d.ts 拿；这里用结构兼容 + as any 避免拉太多内部类型。
+// 关键字段：name / baseUrl / apiKey / api / authHeader / models
+type ProviderConfig = Parameters<ExtensionAPI["registerProvider"]>[1];
+type ProviderModelConfig = NonNullable<ProviderConfig["models"]>[number];
+
+const REGISTERED_PROVIDER_CONFIGS = new Map<string, ProviderConfig>();
+
+export function buildProviderConfig(
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile> = {},
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>> = {},
+): ProviderConfig {
+	const runtimeBaseUrl = resolveRuntimeBaseUrl(provider.api, provider.baseUrl);
+	return buildProviderConfigWithBaseUrl(provider, runtimeBaseUrl, requestHeaderProfiles, clientHeaderCaptures);
+}
+
+function buildProviderConfigWithBaseUrl(
+	provider: StoredProvider,
+	runtimeBaseUrl: string,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>,
+	modelRuntimeBaseUrls: ReadonlyMap<string, string> = new Map(),
+): ProviderConfig {
+	const apiKey = provider.apiKey?.trim();
+	return {
+		name: provider.name,
+		baseUrl: runtimeBaseUrl,
+		...(apiKey ? { apiKey } : {}),
+		api: provider.api,
+		headers: provider.headers,
+		authHeader: provider.authHeader,
+		models: provider.models.map((model) => buildModelConfig(
+			provider,
+			model,
+			requestHeaderProfiles,
+			clientHeaderCaptures,
+			modelRuntimeBaseUrls.get(model.id),
+		)),
+	};
+}
+
+async function buildRuntimeProviderConfig(
+	providerId: string,
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile> = {},
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>> = {},
+): Promise<ProviderConfig> {
+	const upstreamRuntimeBaseUrl = resolveRuntimeBaseUrl(provider.api, provider.baseUrl);
+	removeProviderLocalProxyRoutes(providerId);
+	if (!isProviderHttpProxyEnabled(provider)) {
+		return buildProviderConfigWithBaseUrl(provider, upstreamRuntimeBaseUrl, requestHeaderProfiles, clientHeaderCaptures);
+	}
+
+	const proxyUrl = getProviderHttpProxyUrl(provider);
+	const runtimeBaseUrl = await getLocalProxyBaseUrl(providerId, upstreamRuntimeBaseUrl, proxyUrl);
+	const modelRuntimeBaseUrls = new Map<string, string>();
+	for (const model of provider.models) {
+		const upstreamModelBaseUrl = resolveModelRuntimeBaseUrl(provider, model);
+		if (!upstreamModelBaseUrl) continue;
+		const routeId = `${providerId}/model/${model.id}`;
+		modelRuntimeBaseUrls.set(model.id, await getLocalProxyBaseUrl(routeId, upstreamModelBaseUrl, proxyUrl));
+	}
+	return buildProviderConfigWithBaseUrl(
+		provider,
+		runtimeBaseUrl,
+		requestHeaderProfiles,
+		clientHeaderCaptures,
+		modelRuntimeBaseUrls,
+	);
+}
+
+function asManagedApi(value: string | undefined, fallback: ApiKind): ApiKind {
+	if (value === "openai-completions" || value === "openai-responses"
+		|| value === "anthropic-messages" || value === "google-generative-ai") return value;
+	return fallback;
+}
+
+function resolveModelRuntimeBaseUrl(provider: StoredProvider, model: StoredModel): string | undefined {
+	if (!model.baseUrl) return undefined;
+	return resolveRuntimeBaseUrl(asManagedApi(model.api, provider.api), model.baseUrl);
+}
+
+export function buildModelRequestHeaders(
+	provider: StoredProvider,
+	model: StoredModel,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>,
+): Record<string, string> | undefined {
+	const customHeaders = provider.clientHeaderProfile === "custom"
+		? resolveProviderCustomHeaders(provider, requestHeaderProfiles)
+		: {};
+	const effectiveApi = asManagedApi(model.api, provider.api);
+	const effectiveCompat = mergeCompatSettings(provider.compat, model.compat);
+	const profileHeaders = getClientHeadersForProfile(
+		provider.clientHeaderProfile,
+		effectiveApi,
+		customHeaders,
+		clientHeaderCaptures,
+		effectiveCompat,
+	);
+	return mergeModelRequestHeaders(model.headers, profileHeaders);
+}
+
+function buildModelConfig(
+	provider: StoredProvider,
+	model: StoredModel,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>,
+	runtimeBaseUrl?: string,
+): ProviderModelConfig {
+	return {
+		id: model.id,
+		name: model.name ?? model.id,
+		api: model.api as ProviderModelConfig["api"],
+		baseUrl: runtimeBaseUrl ?? resolveModelRuntimeBaseUrl(provider, model),
+		reasoning: model.reasoning,
+		thinkingLevelMap: model.thinkingLevelMap,
+		input: model.input,
+		cost: model.cost,
+		contextWindow: model.contextWindow,
+		maxTokens: model.maxTokens,
+		headers: buildModelRequestHeaders(provider, model, requestHeaderProfiles, clientHeaderCaptures),
+		compat: mergeCompatSettings(provider.compat, model.compat) as ProviderModelConfig["compat"],
+	};
+}
+
+function resolveProviderCustomHeaders(
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+): Record<string, string> {
+	const profileId = provider.requestHeaderProfileId;
+	if (profileId && requestHeaderProfiles[profileId]) return requestHeaderProfiles[profileId].headers;
+	return provider.customClientHeaders ?? {};
+}
+
+/** 注销本扩展实际注册的动态 provider，并同步清理代理路由和回滚快照。 */
+export function unregisterManagedProvider(pi: ExtensionAPI, providerId: string): void {
+	removeProviderLocalProxyRoutes(providerId);
+	const wasRegistered = REGISTERED_PROVIDER_CONFIGS.delete(providerId);
+	if (wasRegistered) pi.unregisterProvider(providerId);
+}
+
+async function canRegisterManagedProvider(providerId: string, provider: StoredProvider): Promise<boolean> {
+	return provider.models.length > 0 && !(await isBuiltinProviderId(providerId));
+}
+
+function replaceManagedProviderConfig(
+	pi: ExtensionAPI,
+	providerId: string,
+	nextConfig: ProviderConfig,
+	previousRoutes: ReadonlyMap<string, ProviderProxyRoute>,
+): void {
+	const previousConfig = REGISTERED_PROVIDER_CONFIGS.get(providerId);
+	try {
+		if (previousConfig) pi.unregisterProvider(providerId);
+		pi.registerProvider(providerId, nextConfig);
+		REGISTERED_PROVIDER_CONFIGS.set(providerId, nextConfig);
+	} catch (error) {
+		restoreProviderLocalProxyRoutes(providerId, previousRoutes);
+		let rollbackError: unknown;
+		try {
+			if (previousConfig) {
+				pi.unregisterProvider(providerId);
+				pi.registerProvider(providerId, previousConfig);
+				REGISTERED_PROVIDER_CONFIGS.set(providerId, previousConfig);
+			} else {
+				REGISTERED_PROVIDER_CONFIGS.delete(providerId);
+			}
+		} catch (restoreError) {
+			rollbackError = restoreError;
+		}
+		const rollbackNote = rollbackError
+			? `；恢复上一版 runtime 也失败：${formatUnknownError(rollbackError)}`
+			: previousConfig
+				? "；已恢复上一版 runtime"
+				: "；新配置未注册到当前 runtime";
+		throw new Error(`${formatUnknownError(error)}${rollbackNote}`);
+	}
+}
+
+/** 同步一个 provider 到当前会话 transport。新配置会先完整构建；替换失败时恢复上一版动态配置。 */
+export async function reconcileProvider(
+	pi: ExtensionAPI,
+	providerId: string,
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile> = {},
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>> = {},
+): Promise<void> {
+	// registerProvider 的 models 会整体替换目录；内置 provider 必须保留 Pi 已合成的完整目录。
+	if (!(await canRegisterManagedProvider(providerId, provider))) {
+		unregisterManagedProvider(pi, providerId);
+		return;
+	}
+
+	const previousRoutes = snapshotProviderLocalProxyRoutes(providerId);
+	let nextConfig: ProviderConfig;
+	try {
+		nextConfig = await buildRuntimeProviderConfig(providerId, provider, requestHeaderProfiles, clientHeaderCaptures);
+	} catch (error) {
+		restoreProviderLocalProxyRoutes(providerId, previousRoutes);
+		throw error;
+	}
+	replaceManagedProviderConfig(pi, providerId, nextConfig, previousRoutes);
+}
+
+async function reconcileProviderCatalog(
+	pi: ExtensionAPI,
+	providerId: string,
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>,
+): Promise<void> {
+	if (!(await canRegisterManagedProvider(providerId, provider))) {
+		unregisterManagedProvider(pi, providerId);
+		return;
+	}
+	const previousRoutes = snapshotProviderLocalProxyRoutes(providerId);
+	removeProviderLocalProxyRoutes(providerId);
+	const nextConfig = buildProviderConfig(provider, requestHeaderProfiles, clientHeaderCaptures);
+	replaceManagedProviderConfig(pi, providerId, nextConfig, previousRoutes);
+}
+
+type StateProviderReconciler = (
+	pi: ExtensionAPI,
+	providerId: string,
+	provider: StoredProvider,
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>,
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>,
+) => Promise<void>;
+
+async function reconcileAllFromState(
+	pi: ExtensionAPI,
+	document: StateDocument,
+	reconcile: StateProviderReconciler,
+): Promise<string[]> {
+	const warnings: string[] = [];
+	for (const [providerId, provider] of Object.entries(document.providers)) {
+		try {
+			await reconcile(pi, providerId, provider, document.requestHeaderProfiles, document.clientHeaderCaptures);
+		} catch (error) {
+			warnings.push(`${providerId}: ${formatUnknownError(error)}`);
+		}
+	}
+	return warnings;
+}
+
+/** factory 阶段仅注册模型 catalog，不启动长生命周期本地代理。 */
+export async function registerCatalogFromState(pi: ExtensionAPI, document: StateDocument): Promise<string[]> {
+	return reconcileAllFromState(pi, document, reconcileProviderCatalog);
+}
+
+/** session_start 激活当前 state 的完整 provider transport。 */
+export async function registerAllFromState(pi: ExtensionAPI, document: StateDocument): Promise<string[]> {
+	return reconcileAllFromState(pi, document, reconcileProvider);
+}

package/request-pipeline.ts

@@ -0,0 +1,88 @@
+// request-pipeline.ts
+//
+// 统一协调 before_provider_request payload transform。每个请求内共享一次
+// StateDocument；跨请求由 state-cache.ts 按配置文件签名复用状态。
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { injectClaudeCodeMetadata } from "./claude-code-compat.ts";
+import { formatUnknownError } from "./common.ts";
+import { normalizeManagedOpenAIResponsesPayload } from "./openai-responses-payload.ts";
+import { injectOpenAIServiceTier } from "./openai-service-tier.ts";
+import { readCachedState } from "./state-cache.ts";
+import type { StateDocument } from "./types.ts";
+
+type StateLoader = () => Promise<StateDocument>;
+
+type RequestTransform = {
+	id: string;
+	warning: string;
+	run(payload: unknown, ctx: ExtensionContext, loadState: StateLoader): Promise<unknown | undefined> | unknown | undefined;
+};
+
+function createRequestStateLoader(): StateLoader {
+	let statePromise: Promise<StateDocument> | undefined;
+	return () => {
+		statePromise ??= readCachedState();
+		return statePromise;
+	};
+}
+
+const REQUEST_TRANSFORMS: RequestTransform[] = [
+	{
+		id: "claude-code-metadata",
+		warning: "ClaudeCode metadata 注入失败，本次请求仅使用请求头",
+		async run(payload, ctx, loadState) {
+			if (!ctx.model || ctx.model.api !== "anthropic-messages") return undefined;
+			return injectClaudeCodeMetadata(payload, ctx.model, await loadState());
+		},
+	},
+	{
+		id: "openai-responses-instructions",
+		warning: "OpenAI Responses instructions 标准化失败，本次请求使用原始 payload",
+		async run(payload, ctx, loadState) {
+			if (!ctx.model || ctx.model.api !== "openai-responses") return undefined;
+			return normalizeManagedOpenAIResponsesPayload(payload, ctx.model, await loadState());
+		},
+	},
+	{
+		id: "openai-service-tier",
+		warning: "Fast mode 状态读取失败，本次请求未注入 service_tier",
+		async run(payload, ctx, loadState) {
+			if (!ctx.model || ctx.model.api !== "openai-responses") return undefined;
+			return injectOpenAIServiceTier(payload, ctx.model, await loadState());
+		},
+	},
+];
+
+export interface RequestPipeline {
+	transform(payload: unknown, ctx: ExtensionContext): Promise<unknown | undefined>;
+}
+
+export function createRequestPipeline(): RequestPipeline {
+	const notifiedTransformErrors = new Set<string>();
+
+	return {
+		async transform(initialPayload, ctx) {
+			let payload = initialPayload;
+			let changed = false;
+			const loadState = createRequestStateLoader();
+
+			for (const transform of REQUEST_TRANSFORMS) {
+				try {
+					const nextPayload = await transform.run(payload, ctx, loadState);
+					if (nextPayload !== undefined) {
+						payload = nextPayload;
+						changed = true;
+					}
+				} catch (error) {
+					if (!notifiedTransformErrors.has(transform.id) && ctx.hasUI) {
+						notifiedTransformErrors.add(transform.id);
+						ctx.ui.notify(`[pi-model-manager] ${transform.warning}：${formatUnknownError(error)}`, "warning");
+					}
+				}
+			}
+
+			return changed ? payload : undefined;
+		},
+	};
+}