pi-model-manager 0.1.0

package/model-mutations.ts

@@ -0,0 +1,210 @@
+// model-mutations.ts
+//
+// /model-manager 的模型配置事务层。这里集中处理 models.json/state.json 持久化、
+// Pi runtime provider 注册同步、enabledModels 同步和模型救援；TUI 只负责收集用户意图。
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatUnknownError } from "./common.ts";
+import {
+	persistManagedConfiguration,
+	persistModelRenameConfiguration,
+	persistProviderRenameConfiguration,
+} from "./configuration-persistence.ts";
+import {
+	enableModelForNextPiStart,
+	removeModelFromNextPiStart,
+	replaceProviderInEnabledModelsForNextPiStart,
+	verifyNativeModelAvailable,
+} from "./models-json-sync.ts";
+import { reconcileProvider, unregisterManagedProvider } from "./provider-registrar.ts";
+import { withModelRescue } from "./rescue.ts";
+import { deleteModelFromDocument, deleteProviderFromDocument, getModelFullId, upsertModelInDocument, upsertProviderInDocument } from "./state-document.ts";
+import { readState } from "./state-store.ts";
+import type { StateDocument, StoredProvider } from "./types.ts";
+import type { createModelDraftForStoredProvider, createProviderDraft } from "./state-document.ts";
+
+type ProviderDraft = ReturnType<typeof createProviderDraft>;
+type ModelDraft = ReturnType<typeof createModelDraftForStoredProvider>;
+
+function formatEnableNote(mode: "all-enabled" | "updated" | "unchanged", scope?: "global" | "project"): string {
+	if (mode === "all-enabled") return "当前未限制 enabledModels，重启后默认可选";
+	if (mode === "updated") return `已写入${scope === "project" ? "项目" : "全局"} enabledModels`;
+	return "已在 enabledModels 中";
+}
+
+async function notifyModelAvailability(
+	ctx: ExtensionCommandContext,
+	providerId: string,
+	modelId: string,
+	replacedFullId?: string,
+	messagePrefix = "已保存并启用模型",
+): Promise<void> {
+	const fullId = getModelFullId(providerId, modelId);
+	try {
+		const enableOutcome = await enableModelForNextPiStart(ctx.cwd, fullId, replacedFullId);
+		const verification = await verifyNativeModelAvailable(ctx, providerId, modelId);
+		const enableNote = formatEnableNote(enableOutcome.mode, enableOutcome.scope);
+		if (verification.ok) {
+			ctx.ui.notify(`${messagePrefix} ${fullId}（${enableNote}）`, "info");
+		} else {
+			ctx.ui.notify(`已保存模型 ${fullId}，但启用校验有警告：\n- ${verification.warnings.join("\n- ")}`, "warning");
+		}
+	} catch (error) {
+		ctx.ui.notify(`已保存模型 ${fullId}，但启用同步/校验失败：${formatUnknownError(error)}`, "warning");
+	}
+}
+
+async function reconcilePersistedProviderRuntime(
+	pi: ExtensionAPI,
+	providerId: string,
+	provider: StoredProvider,
+	document: StateDocument,
+): Promise<void> {
+	try {
+		await reconcileProvider(pi, providerId, provider, document.requestHeaderProfiles, document.clientHeaderCaptures);
+	} catch (error) {
+		throw new Error(`models.json/state.json 已保存，但当前会话接入刷新失败：${formatUnknownError(error)}。可执行 /reload 重试。`);
+	}
+}
+
+export async function saveProviderConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	state: StateDocument,
+	draft: ProviderDraft,
+	oldProviderId: string | undefined,
+): Promise<void> {
+	const nextState = upsertProviderInDocument(state, oldProviderId, draft);
+	const stored = nextState.providers[draft.providerId]!;
+	const renamedCurrentModelId = oldProviderId
+		&& oldProviderId !== draft.providerId
+		&& ctx.model?.provider === oldProviderId
+		&& stored.models.some((model) => model.id === ctx.model?.id)
+		? ctx.model.id
+		: undefined;
+	if (oldProviderId && oldProviderId !== draft.providerId) {
+		await persistProviderRenameConfiguration(ctx, nextState, oldProviderId, draft.providerId);
+	} else {
+		await persistManagedConfiguration(ctx, nextState);
+	}
+	await reconcilePersistedProviderRuntime(pi, draft.providerId, stored, nextState);
+	if (oldProviderId && oldProviderId !== draft.providerId) unregisterManagedProvider(pi, oldProviderId);
+
+	ctx.ui.notify(`已保存接入 ${draft.providerId}`, "info");
+
+	if (oldProviderId && oldProviderId !== draft.providerId) {
+		try {
+			const outcome = await replaceProviderInEnabledModelsForNextPiStart(
+				ctx.cwd,
+				oldProviderId,
+				draft.providerId,
+			);
+			if (outcome.mode === "updated") {
+				ctx.ui.notify(`已同步${outcome.scope === "project" ? "项目" : "全局"} enabledModels 中的接入重命名`, "info");
+			}
+		} catch (error) {
+			ctx.ui.notify(`接入已保存，但 enabledModels 同步失败：${formatUnknownError(error)}`, "warning");
+		}
+		await withModelRescue(ctx, pi, { providerId: oldProviderId }, {
+			reason: `接入 ${oldProviderId} 已重命名为 ${draft.providerId}`,
+			preferred: renamedCurrentModelId
+				? { providerId: draft.providerId, modelId: renamedCurrentModelId }
+				: undefined,
+		});
+	}
+}
+
+export async function saveModelConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	state: StateDocument,
+	draft: ModelDraft,
+	replacedModelId: string | undefined,
+): Promise<void> {
+	const nextState = upsertModelInDocument(state, draft, { replacedModelId });
+	const stored = nextState.providers[draft.providerId]!;
+	const newModelId = draft.modelId.trim();
+	const oldFullId = replacedModelId && replacedModelId !== newModelId
+		? getModelFullId(draft.providerId, replacedModelId)
+		: undefined;
+	if (oldFullId && replacedModelId) {
+		await persistModelRenameConfiguration(ctx, nextState, draft.providerId, replacedModelId, newModelId);
+	} else {
+		await persistManagedConfiguration(ctx, nextState);
+	}
+	await reconcilePersistedProviderRuntime(pi, draft.providerId, stored, nextState);
+	const newFullId = getModelFullId(draft.providerId, newModelId);
+	await notifyModelAvailability(ctx, draft.providerId, newModelId, oldFullId);
+
+	if (oldFullId && replacedModelId) {
+		await withModelRescue(
+			ctx,
+			pi,
+			{ providerId: draft.providerId, modelId: replacedModelId },
+			{
+				reason: `模型 ${oldFullId} 已重命名为 ${newFullId}`,
+				preferred: { providerId: draft.providerId, modelId: draft.modelId.trim() },
+			},
+		);
+	}
+}
+
+export async function saveNewProviderWithModelConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	providerState: StateDocument,
+	providerDraft: ProviderDraft,
+	modelDraft: ModelDraft,
+): Promise<void> {
+	const nextState = upsertModelInDocument(providerState, modelDraft);
+	const stored = nextState.providers[providerDraft.providerId]!;
+	await persistManagedConfiguration(ctx, nextState);
+	await reconcilePersistedProviderRuntime(pi, providerDraft.providerId, stored, nextState);
+	await notifyModelAvailability(ctx, providerDraft.providerId, modelDraft.modelId.trim(), undefined, "已创建并启用模型");
+}
+
+export async function deleteProviderConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	providerId: string,
+	provider: StoredProvider,
+): Promise<void> {
+	const state = await readState();
+	const nextState = deleteProviderFromDocument(state, providerId);
+	await persistManagedConfiguration(ctx, nextState, [providerId]);
+	try {
+		for (const model of provider.models) {
+			await removeModelFromNextPiStart(ctx.cwd, getModelFullId(providerId, model.id));
+		}
+	} catch (error) {
+		ctx.ui.notify(`接入已删除，但 enabledModels 清理失败：${formatUnknownError(error)}`, "warning");
+	}
+	unregisterManagedProvider(pi, providerId);
+	ctx.ui.notify(`已删除接入 ${providerId}`, "info");
+	await withModelRescue(ctx, pi, { providerId }, { reason: `接入 ${providerId} 已删除` });
+}
+
+export async function deleteModelConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	providerId: string,
+	modelId: string,
+): Promise<void> {
+	const fullId = getModelFullId(providerId, modelId);
+	const state = await readState();
+	const nextState = deleteModelFromDocument(state, providerId, modelId);
+	if ((nextState.providers[providerId]?.models.length ?? 0) === 0) {
+		delete nextState.providers[providerId];
+	}
+	const stored = nextState.providers[providerId];
+	await persistManagedConfiguration(ctx, nextState, stored ? [] : [providerId]);
+	try {
+		await removeModelFromNextPiStart(ctx.cwd, fullId);
+	} catch (error) {
+		ctx.ui.notify(`模型已删除，但 enabledModels 清理失败：${formatUnknownError(error)}`, "warning");
+	}
+	if (stored) await reconcilePersistedProviderRuntime(pi, providerId, stored, nextState);
+	else unregisterManagedProvider(pi, providerId);
+	ctx.ui.notify(`已删除模型 ${fullId}`, "info");
+	await withModelRescue(ctx, pi, { providerId, modelId }, { reason: `模型 ${fullId} 已删除` });
+}

package/models-json-manager.ts

@@ -0,0 +1,238 @@
+// models-json-manager.ts
+//
+// 管理 pi 的 ~/.pi/agent/models.json：读 / 写 / 增 / 删 / 改。
+//
+// 主保存流程通过 models-json-sync.ts 同步 StateDocument；原始节点 mutation 在这里保留未知字段。
+// 写入后由调用方执行 ctx.modelRegistry.refresh()，保持 pi 原生 models.json 语义。
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteText } from "./atomic-write.ts";
+import { cloneJson, isObjectRecord, stringifyJson, stripJsonNoise } from "./common.ts";
+import type { TokenCost } from "./types.ts";
+
+export const MODELS_JSON_PATH = join(getAgentDir(), "models.json");
+
+// ========== schema ==========
+
+export interface ModelsJsonModelEntry {
+	id: string;
+	name?: string;
+	api?: string;
+	baseUrl?: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: Record<string, string | null>;
+	input?: ("text" | "image")[];
+	contextWindow?: number;
+	maxTokens?: number;
+	cost?: TokenCost;
+	headers?: Record<string, string>;
+	compat?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+export interface ModelsJsonProviderEntry {
+	name?: string;
+	baseUrl?: string;
+	api?: string;
+	apiKey?: string;
+	authHeader?: boolean;
+	headers?: Record<string, string>;
+	models?: ModelsJsonModelEntry[];
+	modelOverrides?: Record<string, unknown>;
+	compat?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+export interface ModelsJsonDocument {
+	providers: Record<string, ModelsJsonProviderEntry>;
+	[key: string]: unknown;
+}
+
+export interface FileSignature {
+	exists: boolean;
+	mtimeMs: number;
+	ctimeMs: number;
+	size: number;
+	ino: number;
+}
+
+export interface ModelsJsonSnapshot {
+	document: ModelsJsonDocument;
+	signature: FileSignature;
+}
+
+export interface StableTextFileSnapshot {
+	source: string | undefined;
+	signature: FileSignature;
+}
+
+// ========== IO ==========
+
+function createEmpty(): ModelsJsonDocument {
+	return { providers: {} };
+}
+
+const MISSING_FILE_SIGNATURE: FileSignature = { exists: false, mtimeMs: 0, ctimeMs: 0, size: -1, ino: 0 };
+
+function isNotFound(error: unknown): boolean {
+	return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+export async function readFileSignature(path: string): Promise<FileSignature> {
+	try {
+		const stats = await stat(path);
+		return { exists: true, mtimeMs: stats.mtimeMs, ctimeMs: stats.ctimeMs, size: stats.size, ino: stats.ino };
+	} catch (error) {
+		if (isNotFound(error)) return MISSING_FILE_SIGNATURE;
+		throw error;
+	}
+}
+
+export function sameFileSignature(a: FileSignature, b: FileSignature): boolean {
+	return a.exists === b.exists
+		&& a.mtimeMs === b.mtimeMs
+		&& a.ctimeMs === b.ctimeMs
+		&& a.size === b.size
+		&& a.ino === b.ino;
+}
+
+/** 文件在读取窗口内变化时重试，避免把旧内容和新签名组合成同一个 snapshot。 */
+export async function readStableTextFileSnapshot(path: string): Promise<StableTextFileSnapshot> {
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		const before = await readFileSignature(path);
+		if (!before.exists) {
+			const after = await readFileSignature(path);
+			if (sameFileSignature(before, after)) return { source: undefined, signature: after };
+			continue;
+		}
+		let source: string;
+		try {
+			source = await readFile(path, "utf8");
+		} catch (error) {
+			if (isNotFound(error)) continue;
+			throw error;
+		}
+		const after = await readFileSignature(path);
+		if (sameFileSignature(before, after)) return { source, signature: after };
+	}
+	throw new Error(`${path} 在读取期间持续变化；请停止其它写入后重试。`);
+}
+
+function parseModelsJson(source: string): ModelsJsonDocument {
+	const parsed = JSON.parse(stripJsonNoise(source));
+	if (!isObjectRecord(parsed)) throw new Error("models.json 根节点必须是对象");
+	const providers = isObjectRecord(parsed.providers) ? parsed.providers : {};
+	return { ...parsed, providers: providers as Record<string, ModelsJsonProviderEntry> };
+}
+
+export async function readModelsJsonSnapshot(): Promise<ModelsJsonSnapshot> {
+	const snapshot = await readStableTextFileSnapshot(MODELS_JSON_PATH);
+	return {
+		document: snapshot.source === undefined ? createEmpty() : parseModelsJson(snapshot.source),
+		signature: snapshot.signature,
+	};
+}
+
+export async function readModelsJson(): Promise<ModelsJsonDocument> {
+	return (await readModelsJsonSnapshot()).document;
+}
+
+export async function writeModelsJson(doc: ModelsJsonDocument): Promise<void> {
+	await atomicWriteText(MODELS_JSON_PATH, stringifyJson(doc));
+}
+
+export async function writeModelsJsonSnapshot(snapshot: ModelsJsonSnapshot, doc: ModelsJsonDocument): Promise<void> {
+	const current = await readFileSignature(MODELS_JSON_PATH);
+	if (!sameFileSignature(snapshot.signature, current)) {
+		throw new Error("models.json 已被其它进程或编辑器修改；请重新打开 /model-manager 后再保存。");
+	}
+	await writeModelsJson(doc);
+}
+
+export function getModelsJsonPath(): string {
+	return MODELS_JSON_PATH;
+}
+
+// ========== 文档操作（纯函数，深拷贝后改） ==========
+
+export function setProviderInDoc(
+	doc: ModelsJsonDocument,
+	providerId: string,
+	entry: ModelsJsonProviderEntry,
+): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	next.providers[providerId] = entry;
+	return next;
+}
+
+export function deleteProviderInDoc(doc: ModelsJsonDocument, providerId: string): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	delete next.providers[providerId];
+	return next;
+}
+
+/** [喵喵喵]: 重命名直接移动原始节点，避免未知原生字段在 StateDocument 往返时丢失 (2026-07-17) */
+export function renameProviderInDoc(
+	doc: ModelsJsonDocument,
+	oldProviderId: string,
+	newProviderId: string,
+): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	if (oldProviderId === newProviderId) return next;
+	const source = next.providers[oldProviderId];
+	if (!source) throw new Error(`models.json 中不存在待重命名接入：${oldProviderId}`);
+	if (next.providers[newProviderId]) throw new Error(`models.json 中已存在接入：${newProviderId}`);
+	next.providers[newProviderId] = source;
+	delete next.providers[oldProviderId];
+	return next;
+}
+
+export function setModelInDoc(
+	doc: ModelsJsonDocument,
+	providerId: string,
+	model: ModelsJsonModelEntry,
+	replacedModelId?: string,
+): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	const provider = next.providers[providerId];
+	if (!provider) throw new Error(`models.json 中不存在接入：${providerId}`);
+	const retained = (provider.models ?? []).filter(
+		(m) => m.id !== model.id && m.id !== replacedModelId,
+	);
+	provider.models = [...retained, model];
+	return next;
+}
+
+export function renameModelInDoc(
+	doc: ModelsJsonDocument,
+	providerId: string,
+	oldModelId: string,
+	newModelId: string,
+): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	if (oldModelId === newModelId) return next;
+	const provider = next.providers[providerId];
+	if (!provider) throw new Error(`models.json 中不存在接入：${providerId}`);
+	const models = provider.models ?? [];
+	const source = models.find((model) => model.id === oldModelId);
+	if (!source) throw new Error(`models.json 中不存在待重命名模型：${providerId}/${oldModelId}`);
+	if (models.some((model) => model.id === newModelId)) {
+		throw new Error(`models.json 中已存在模型：${providerId}/${newModelId}`);
+	}
+	source.id = newModelId;
+	return next;
+}
+
+export function deleteModelInDoc(
+	doc: ModelsJsonDocument,
+	providerId: string,
+	modelId: string,
+): ModelsJsonDocument {
+	const next = cloneJson(doc);
+	const provider = next.providers[providerId];
+	if (!provider) return next;
+	provider.models = (provider.models ?? []).filter((m) => m.id !== modelId);
+	return next;
+}

package/models-json-mutations.ts

@@ -0,0 +1,90 @@
+// models-json-mutations.ts
+//
+// 原生 models.json 面板的事务层：集中处理 models.json 写入、插件 metadata 回写、
+// runtime registry 刷新、enabledModels 清理和模型救援。
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatUnknownError } from "./common.ts";
+import { deleteModelInDoc, deleteProviderInDoc, readModelsJsonSnapshot, writeModelsJsonSnapshot } from "./models-json-manager.ts";
+import { removeModelFromNextPiStart } from "./models-json-sync.ts";
+import { reconcileProvider, unregisterManagedProvider } from "./provider-registrar.ts";
+import { withModelRescue } from "./rescue.ts";
+import { getModelFullId } from "./state-document.ts";
+import { invalidateStateCache } from "./state-cache.ts";
+import { readState, writeState } from "./state-store.ts";
+import type { StateDocument } from "./types.ts";
+
+async function refreshMetadataAfterNativeWrite(operation: string): Promise<StateDocument> {
+	try {
+		const state = await readState();
+		await writeState(state);
+		invalidateStateCache();
+		return state;
+	} catch (error) {
+		throw new Error(`${operation} 已写入 models.json，但 state.json metadata 清理失败：${formatUnknownError(error)}`);
+	}
+}
+
+async function refreshNativeMutationRuntime(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	operation: string,
+	state: StateDocument,
+	providerId: string,
+): Promise<void> {
+	try {
+		await ctx.modelRegistry.refresh();
+		const provider = state.providers[providerId];
+		if (provider) await reconcileProvider(pi, providerId, provider, state.requestHeaderProfiles, state.clientHeaderCaptures);
+		else unregisterManagedProvider(pi, providerId);
+	} catch (error) {
+		throw new Error(`${operation} 已写入 models.json/state.json，但当前会话 registry 刷新失败：${formatUnknownError(error)}。可执行 /reload 重试。`);
+	}
+}
+
+export async function deleteModelsJsonProviderConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	providerId: string,
+): Promise<void> {
+	const snapshot = await readModelsJsonSnapshot();
+	const doc = snapshot.document;
+	const removedModels = [...(doc.providers[providerId]?.models ?? [])].map((model) => model.id);
+	await writeModelsJsonSnapshot(snapshot, deleteProviderInDoc(doc, providerId));
+	invalidateStateCache();
+	const state = await refreshMetadataAfterNativeWrite(`删除 ${providerId}`);
+	await refreshNativeMutationRuntime(pi, ctx, `删除 ${providerId}`, state, providerId);
+	try {
+		for (const modelId of removedModels) {
+			await removeModelFromNextPiStart(ctx.cwd, getModelFullId(providerId, modelId));
+		}
+	} catch (error) {
+		ctx.ui.notify(`已删除 ${providerId}，但 enabledModels 清理失败：${formatUnknownError(error)}`, "warning");
+	}
+	ctx.ui.notify(`已删除 ${providerId}`, "info");
+	await withModelRescue(ctx, pi, { providerId }, { reason: `models.json 中的 ${providerId} 已删除` });
+}
+
+export async function deleteModelsJsonModelConfiguration(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	providerId: string,
+	modelId: string,
+): Promise<void> {
+	const fullId = getModelFullId(providerId, modelId);
+	const snapshot = await readModelsJsonSnapshot();
+	const doc = snapshot.document;
+	let nextDoc = deleteModelInDoc(doc, providerId, modelId);
+	if ((nextDoc.providers[providerId]?.models?.length ?? 0) === 0) nextDoc = deleteProviderInDoc(nextDoc, providerId);
+	await writeModelsJsonSnapshot(snapshot, nextDoc);
+	invalidateStateCache();
+	const state = await refreshMetadataAfterNativeWrite(`删除 ${fullId}`);
+	await refreshNativeMutationRuntime(pi, ctx, `删除 ${fullId}`, state, providerId);
+	try {
+		await removeModelFromNextPiStart(ctx.cwd, fullId);
+	} catch (error) {
+		ctx.ui.notify(`已删除 ${fullId}，但 enabledModels 清理失败：${formatUnknownError(error)}`, "warning");
+	}
+	ctx.ui.notify(`已删除 ${fullId}`, "info");
+	await withModelRescue(ctx, pi, { providerId, modelId }, { reason: `models.json 中的 ${fullId} 已删除` });
+}