@rexvane/piweb 0.3.20 → 0.3.22

package/src/lib/model-draft.ts

@@ -5,22 +5,83 @@ export interface ModelDraft {
 	name: string;
 	contextWindow?: number;
 	maxTokens?: number;
+	/** 输入模态里有 image（models.json 的 `input`）。undefined = 源里没写：pi 会当成只文本、把贴图换成占位文字 */
+	vision?: boolean;
 	source?: Readonly<Record<string, unknown>>;
+	/** 来自 modelOverrides：只覆盖内置模型的部分字段。缺省 = models[] 里的定义或新加的行 */
+	origin?: "override";
+}
+
+/**
+ * models.json 里模型的 `input` 字段（pi 用它判断能不能收图）。
+ * 没写 → pi 按只文本处理，而且提示语会说是「模型不支持图像」，很容易被当成模型能力问题。
+ */
+export function modelInputFor(vision: boolean): string[] {
+	return vision ? ["text", "image"] : ["text"];
+}
+
+/**
+ * pi 在 models[] 条目没写这些字段时用的值（provider-composer.js 的 modelFromJson：
+ * `contextWindow ?? 128000`、`maxTokens ?? 16384`、`input ?? ["text"]`）。只用来向用户解释「不填会被当成什么」。
+ *
+ * PiWeb 不替用户编容量：maxTokens 会原样当成请求的 max_tokens 发出去（pi-ai simple-options），
+ * contextWindow 决定 max_tokens 的钳制和自动压缩的时机——往大了猜，上游会直接拒绝请求；
+ * 往小了猜只是提前压缩。所以只写端点报的或用户填的值，缺的交给体检卡片提醒。
+ */
+export const PI_MODEL_FALLBACKS = { contextWindow: 128_000, maxTokens: 16_384 } as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 export function modelDraftFromConfig(value: unknown): ModelDraft {
-	const source = value && typeof value === "object" && !Array.isArray(value)
-		? value as Record<string, unknown>
-		: { id: typeof value === "string" ? value : "" };
+	const source = isRecord(value) ? value : { id: typeof value === "string" ? value : "" };
+	const input = Array.isArray(source.input)
+		? source.input.filter((item): item is string => typeof item === "string")
+		: undefined;
 	return {
 		id: String(source.id ?? ""),
 		name: typeof source.name === "string" ? source.name : "",
 		contextWindow: typeof source.contextWindow === "number" ? source.contextWindow : undefined,
 		maxTokens: typeof source.maxTokens === "number" ? source.maxTokens : undefined,
+		// 只有源里写了 input 才算「声明过」：没写 ≠ 只文本，而是「会被 pi 当只文本」
+		vision: input ? input.includes("image") : undefined,
 		source,
 	};
 }
 
+function positiveInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+/** 「获取可用模型」返回的一条 → 表单行：端点报了容量与视觉就带上，没报的留空（不猜） */
+export function modelDraftFromCatalog(entry: { id: string; name?: string; contextWindow?: number; maxTokens?: number; vision?: boolean }): ModelDraft {
+	const contextWindow = positiveInt(entry.contextWindow);
+	const maxTokens = positiveInt(entry.maxTokens);
+	return {
+		id: entry.id.trim(),
+		name: entry.name ?? "",
+		...(contextWindow === undefined ? {} : { contextWindow }),
+		...(maxTokens === undefined ? {} : { maxTokens }),
+		...(typeof entry.vision === "boolean" ? { vision: entry.vision } : {}),
+	};
+}
+
+/** modelOverrides 的一条：键是模型 ID，值只含要覆盖的字段 */
+export function modelDraftFromOverride(id: string, value: unknown): ModelDraft {
+	return { ...modelDraftFromConfig({ ...(isRecord(value) ? value : {}), id }), origin: "override" };
+}
+
+/** 内置 provider 的 models.json 条目 → 表单行：models[] 的定义在前，modelOverrides 的覆盖在后 */
+export function modelDraftsFromProviderConfig(config: unknown): ModelDraft[] {
+	const source = isRecord(config) ? config : {};
+	const definitions = Array.isArray(source.models) ? source.models.map(modelDraftFromConfig) : [];
+	const overrides = isRecord(source.modelOverrides)
+		? Object.entries(source.modelOverrides).map(([id, value]) => modelDraftFromOverride(id, value))
+		: [];
+	return [...definitions, ...overrides];
+}
+
 /** K/M use decimal units. Empty means the SDK default; NaN means invalid input. */
 export function parseCapacity(text: string): number | undefined {
 	const value = text.trim().toLowerCase();
@@ -52,13 +113,16 @@ export function validateModelDrafts(models: ModelDraft[]): { index: number; reas
 	return undefined;
 }
 
-/** Only edited form fields replace the source; unknown/nested configuration is opaque. */
+/**
+ * Only edited form fields replace the source; unknown/nested configuration is opaque.
+ * 容量留空就不写（交给 pi 的缺省，见 PI_MODEL_FALLBACKS），不替用户编值。
+ */
 export function serializeModelDraft(model: Omit<ModelDraft, "name"> & { name?: string }): Record<string, unknown> {
 	const result: Record<string, unknown> = { ...model.source };
 	const original = model.source ? modelDraftFromConfig(model.source) : undefined;
 	for (const field of ["id", "name", "contextWindow", "maxTokens"] as const) {
-		if (original && Object.is(model[field], original[field])) continue;
 		const value = model[field];
+		if (original && Object.is(value, original[field])) continue;
 		if (field === "id" || field === "name") {
 			const text = typeof value === "string" ? value.trim() : "";
 			if (field === "id" || text) result[field] = text;
@@ -66,6 +130,15 @@ export function serializeModelDraft(model: Omit<ModelDraft, "name"> & { name?: s
 		} else if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) result[field] = value;
 		else delete result[field];
 	}
+	// input 是数组：只在明确表态时写（端点报的或用户选的），不默认猜视觉
+	// （猜错会把图片发给不收图的上游；留空只是被 pi 当纯文本，体检卡片会提醒）
+	const vision = model.vision;
+	if (vision === undefined) {
+		// 源里声明过、现在选「未声明」= 明确取消这个声明（否则保留源值会让人取消不掉）
+		if (original?.vision !== undefined) delete result.input;
+	} else if (!Object.is(vision, original?.vision)) {
+		result.input = modelInputFor(vision);
+	}
 	return result;
 }
 
@@ -82,6 +155,8 @@ export function serializeProviderDraft(
 	source: Readonly<Record<string, unknown>>,
 	draft: ProviderDraft,
 	defaultApi?: string,
+	/** 内置 provider 的目录模型 ID：给了就按 splitBuiltinModels 把覆盖已有模型的行写进 modelOverrides */
+	catalogIds?: ReadonlySet<string>,
 ): Record<string, unknown> {
 	const result: Record<string, unknown> = { ...source };
 	for (const field of ["baseUrl", "name", "api"] as const) {
@@ -91,13 +166,186 @@ export function serializeProviderDraft(
 		else delete result[field];
 	}
 	if (draft.apiKey?.trim()) result.apiKey = draft.apiKey.trim();
+	const { definitions, overrides } = catalogIds
+		? splitBuiltinModels(draft.models, catalogIds)
+		: { definitions: draft.models.map((model) => serializeModelDraft(model)), overrides: undefined };
 	// An explicit empty array removes the overrides. Do not merge rows back by ID.
-	if (draft.models.length || Object.prototype.hasOwnProperty.call(source, "models")) {
-		result.models = draft.models.map(serializeModelDraft);
+	if (definitions.length || Object.prototype.hasOwnProperty.call(source, "models")) {
+		result.models = definitions;
+	}
+	// 表单载入了全部 modelOverrides，这里整体替换；删光了就去掉这个键
+	if (overrides) {
+		if (Object.keys(overrides).length) result.modelOverrides = overrides;
+		else delete result.modelOverrides;
 	}
-	// Supply an API only for newly introduced builtin model overrides, not existing rows.
-	if (draft.models.length && source.models === undefined && result.api === undefined && defaultApi) {
+	// Supply an API only for newly introduced builtin model definitions, not existing rows.
+	if (definitions.length && source.models === undefined && result.api === undefined && defaultApi) {
 		result.api = defaultApi;
 	}
 	return result;
 }
+
+/**
+ * 内置 provider 的表单行分流。models[] 里与内置模型同 ID 的条目会被 SDK 当成新定义整条重建
+ * （reasoning / 上下文 / 价格 / 思考档位回到默认值，provider 级 api 还会顶掉模型自己的协议），
+ * 所以覆盖已有模型要写 modelOverrides：只写填了的字段，其余沿用内置值。
+ * - 自带 api / baseUrl 的 models[] 条目是手写的完整定义，原样留在 models[]；
+ * - ID 在目录里，或来自 modelOverrides 且 ID 没改 → modelOverrides（没有要覆盖的字段就不写）；
+ * - 其余是新模型 → models[]。
+ */
+function splitBuiltinModels(models: ModelDraft[], catalogIds: ReadonlySet<string>): {
+	definitions: Record<string, unknown>[];
+	overrides: Record<string, unknown>;
+} {
+	const definitions: Record<string, unknown>[] = [];
+	const overrides: Array<[string, Record<string, unknown>]> = [];
+	for (const model of models) {
+		const id = model.id.trim();
+		const source = isRecord(model.source) ? model.source : undefined;
+		// 自带 api / baseUrl 的 models[] 条目是手写的完整定义，原样留在 models[]
+		const fullDefinition = model.origin !== "override" && (source?.api !== undefined || source?.baseUrl !== undefined);
+		const keptOverride = model.origin === "override" && source !== undefined && modelDraftFromConfig(source).id === id;
+		const asOverride = !fullDefinition && (catalogIds.has(id) || keptOverride);
+		const serialized = serializeModelDraft(model);
+		if (!asOverride) {
+			definitions.push(serialized);
+			continue;
+		}
+		const fields = { ...serialized };
+		delete fields.id;
+		if (Object.keys(fields).length) overrides.push([id, fields]);
+	}
+	// fromEntries 按数据属性写入，"__proto__" 这类 ID 也不会改原型
+	return { definitions, overrides: Object.fromEntries(overrides) };
+}
+
+/** 条目里只剩这些字段时，SDK 不认它（见 isInertProviderConfig） */
+const INERT_PROVIDER_FIELDS = new Set(["api", "name", "models", "modelOverrides"]);
+
+/**
+ * 内置 provider 的 models.json 条目是否「什么都没覆盖」。SDK 要求条目至少有非空的 models / modelOverrides、
+ * baseUrl、headers、compat、apiKey、oauth、authHeader 之一，否则报错、整份 models.json 存不进去；
+ * 只剩 api / name 这类只对 models[] 有用的字段时，删掉条目才等于「全用内置默认」。
+ * 有不认识的字段就交给 SDK 校验，不替用户删。注意前端拿到的配置已去掉 apiKey，调用方要另外排除存了密钥的条目。
+ */
+export function isInertProviderConfig(config: Readonly<Record<string, unknown>>): boolean {
+	if (Array.isArray(config.models) && config.models.length) return false;
+	if (isRecord(config.modelOverrides) && Object.keys(config.modelOverrides).length) return false;
+	return Object.keys(config).every((field) => INERT_PROVIDER_FIELDS.has(field));
+}
+
+export type CustomModelField = "contextWindow" | "maxTokens" | "input";
+
+/** 体检的一条：models[] 里有字段没写的模型（已写的值一并带上，界面要显示） */
+export interface CustomModelGap {
+	provider: string;
+	/** 在 models[] 里的位置：手写的文件可能有重复 ID，按位置定位才准 */
+	index: number;
+	id: string;
+	name: string | null;
+	contextWindow?: number;
+	maxTokens?: number;
+	vision?: boolean;
+	missing: CustomModelField[];
+}
+
+/**
+ * 体检：models.json 里哪些模型有字段没写、会落到 pi 的缺省上（见 PI_MODEL_FALLBACKS）。
+ * 只看 providers[].models[]——modelOverrides 覆盖的是内置模型，那些模型 pi 的目录里有真值。
+ * 读的是设置页已经载入的那份配置（密钥已去掉也不影响），保存后重新载入就自动刷新。
+ */
+export function customModelGaps(providers: Readonly<Record<string, unknown>>): CustomModelGap[] {
+	const gaps: CustomModelGap[] = [];
+	for (const [provider, config] of Object.entries(providers)) {
+		const models = isRecord(config) && Array.isArray(config.models) ? config.models : [];
+		models.forEach((model, index) => {
+			if (!isRecord(model)) return;
+			const id = typeof model.id === "string" ? model.id.trim() : "";
+			if (!id) return;
+			const missing: CustomModelField[] = [];
+			if (model.contextWindow === undefined) missing.push("contextWindow");
+			if (model.maxTokens === undefined) missing.push("maxTokens");
+			if (!Array.isArray(model.input)) missing.push("input");
+			if (!missing.length) return;
+			const declared = modelDraftFromConfig(model);
+			gaps.push({
+				provider,
+				index,
+				id,
+				name: typeof model.name === "string" && model.name.trim() ? model.name.trim() : null,
+				...(declared.contextWindow === undefined ? {} : { contextWindow: declared.contextWindow }),
+				...(declared.maxTokens === undefined ? {} : { maxTokens: declared.maxTokens }),
+				...(declared.vision === undefined ? {} : { vision: declared.vision }),
+				missing,
+			});
+		});
+	}
+	return gaps;
+}
+
+/** 用户在体检卡片里给某个模型填的值；没填的字段不带 */
+export interface ModelFieldFill {
+	provider: string;
+	index: number;
+	id: string;
+	contextWindow?: number;
+	maxTokens?: number;
+	vision?: boolean;
+}
+
+/**
+ * 按用户填的值补字段：只补空着的（已写的值不改），按 provider + 位置定位并核对 ID，对不上就跳过。
+ * 不改入参；返回新的 providers 与实际补了几个模型。
+ */
+export function fillModelFields(providers: Readonly<Record<string, unknown>>, fills: readonly ModelFieldFill[]): { providers: Record<string, unknown>; filled: number } {
+	const next = JSON.parse(JSON.stringify(providers)) as Record<string, unknown>;
+	let filled = 0;
+	for (const fill of fills) {
+		const config = Object.prototype.hasOwnProperty.call(next, fill.provider) ? next[fill.provider] : undefined;
+		const model = isRecord(config) && Array.isArray(config.models) ? config.models[fill.index] : undefined;
+		if (!isRecord(model) || typeof model.id !== "string" || model.id.trim() !== fill.id) continue;
+		let touched = false;
+		for (const key of ["contextWindow", "maxTokens"] as const) {
+			const value = positiveInt(fill[key]);
+			if (model[key] === undefined && value !== undefined) {
+				model[key] = value;
+				touched = true;
+			}
+		}
+		if (typeof fill.vision === "boolean" && !Array.isArray(model.input)) {
+			model.input = modelInputFor(fill.vision);
+			touched = true;
+		}
+		if (touched) filled += 1;
+	}
+	return { providers: next, filled };
+}
+
+/**
+ * 改一个模型的上下文窗口，写在 pi 实际取值的那一层（modelOverrides 最后套用，压过 models[]）：
+ * - 已有 modelOverrides.<id>.contextWindow → 改它；
+ * - 否则 models[] 里定义了这个 ID → 改那几条（设置页编辑表单显示的就是它们）；
+ * - 都没有（内置目录、远程目录、扩展补的模型）→ 写 modelOverrides.<id>.contextWindow，同一条覆盖的其它字段保留。
+ * 不改入参。
+ */
+export function withContextWindow(providers: Readonly<Record<string, unknown>>, provider: string, id: string, contextWindow: number): Record<string, unknown> {
+	const next = JSON.parse(JSON.stringify(providers)) as Record<string, unknown>;
+	const existing = Object.prototype.hasOwnProperty.call(next, provider) ? next[provider] : undefined;
+	const config: Record<string, unknown> = isRecord(existing) ? existing : {};
+	next[provider] = config;
+	const overrides = isRecord(config.modelOverrides) ? config.modelOverrides : undefined;
+	const override = overrides && Object.prototype.hasOwnProperty.call(overrides, id) ? overrides[id] : undefined;
+	if (isRecord(override) && override.contextWindow !== undefined) {
+		override.contextWindow = contextWindow;
+		return next;
+	}
+	const defined = Array.isArray(config.models) ? config.models.filter((model) => isRecord(model) && typeof model.id === "string" && model.id.trim() === id) : [];
+	if (defined.length) {
+		for (const model of defined as Record<string, unknown>[]) model.contextWindow = contextWindow;
+		return next;
+	}
+	const table = overrides ?? {};
+	config.modelOverrides = table;
+	table[id] = { ...(isRecord(override) ? override : {}), contextWindow };
+	return next;
+}

package/src/lib/model-endpoint.ts

@@ -0,0 +1,23 @@
+/**
+ * 模型目录地址判断（客户端安全，纯函数）。
+ *
+ * ⚠️ 只用于界面提示：进了本机/私网地址就自动勾上「允许访问本机/私有网络地址」，
+ * 免得用户对着 127.0.0.1 的网关反复点「获取可用模型」都被服务端挡回来。
+ * 真正的闸门在服务端 requestModelCatalog 里（allowPrivate / PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY），
+ * 这里判错也不影响安全。
+ */
+export function looksPrivateEndpoint(url: string): boolean {
+	try {
+		const host = new URL(url.trim()).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+		if (!host) return false;
+		if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) return true;
+		if (host.includes(":")) return host === "::1" || /^(fc|fd|fe80)/.test(host);
+		const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+		if (!v4) return false;
+		const a = Number(v4[1]);
+		const b = Number(v4[2]);
+		return a === 0 || a === 10 || a === 127 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 169 && b === 254);
+	} catch {
+		return false;
+	}
+}

package/src/lib/model-files.ts

@@ -0,0 +1,33 @@
+/**
+ * models.json / auth.json 的外部改动感知。不依赖 SDK（运行时作为 unknown 传入），方便直接测。
+ */
+import { statSync } from "node:fs";
+import path from "node:path";
+
+/** 两个文件的指纹（大小 + 修改时间，不读内容）：指纹变了才需要重新加载模型目录 */
+export function modelFilesFingerprint(agentDir: string): string {
+	return ["models.json", "auth.json"]
+		.map((name) => {
+			try {
+				const stat = statSync(path.join(agentDir, name));
+				return `${name}:${stat.size}:${stat.mtimeMs}`;
+			} catch {
+				return `${name}:-`;
+			}
+		})
+		.join("|");
+}
+
+/**
+ * SDK 的 auth 存储第一次读 auth.json 后就缓存在内存里，手改之后要让它重读。
+ * SDK 没有公开这个入口：运行时把存储包在 RuntimeCredentials.store 里，这里走这条路径调 reload()。
+ * 路径不存在（SDK 版本变了）就什么都不做，只剩 models.json 的刷新；tests/model-files.test.ts 会用真实 SDK 验证这条路径。
+ */
+export function reloadStoredCredentials(runtime: unknown): void {
+	const store = (runtime as { credentials?: { store?: { reload?: () => void } } }).credentials?.store;
+	try {
+		store?.reload?.();
+	} catch {
+		// auth.json 写坏了：保留旧缓存，错误由下一次读取报出来
+	}
+}