dsh-model-input-toggle 0.0.0-stage → 1.0.0

package/lib/index.js

@@ -0,0 +1,892 @@
+/**
+ * dsh-model-input-toggle — host half.
+ *
+ * Adds a "this model accepts images" switch to the官方 Models settings page by
+ * writing the modality declaration the adapters already understand:
+ *
+ *   llm-pi-ai      providers.<route>.models[].input         = ["text","image"]
+ *   llm-deepseek   models[].inputModalities                 = ["text","image"]
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `input` / `inputModalities` are pure DECLARATIONS. DSH uses them to decide
+ * whether to reject an image before it ever reaches the provider. Declaring
+ * image support therefore does not create it: if the endpoint cannot actually
+ * accept OpenAI-style `image_url` parts, the failure moves from "blocked by
+ * DSH" to "HTTP 400 from the endpoint". That is why this plugin ships a
+ * `verify` method that sends a real image-bearing request and reports what the
+ * endpoint actually did.
+ *
+ * WRITE STRATEGY (and why it is not array-indexed)
+ * ------------------------------------------------
+ * `ctx.settings.mutate` applies path ops through `applyPathOp`, which only
+ * descends into PLAIN OBJECTS. Any path that steps through an array silently
+ * stops at the deepest object, so `.../models/0/input` would write nothing.
+ * Every write here therefore targets a whole leaf the op can actually replace:
+ *
+ *   - an existing user `models` array is rebuilt (every other field preserved)
+ *     and written wholesale to `providers.<route>.models`;
+ *   - when the route carries NO user `models` list, the entry is written to
+ *     `providers.<route>.modelOverrides.<id>.input` instead.
+ *
+ * Those two branches matter: llm-pi-ai rejects `modelOverrides` as invalid when
+ * a `models` list is present ("models already replaces the served catalog"), and
+ * writing a full `models` list where the user had none would materialize the
+ * installed catalog into the user's config. Each branch is the minimal correct
+ * write for its shape.
+ *
+ * @module dsh-model-input-toggle
+ */
+
+/** Plugin identity for cordis.yml rows. */
+export const name = "dsh-model-input-toggle";
+
+/** Services required before mounting: the route table and its trust fence. */
+export const inject = ["webServer", "webRuntime"];
+
+/** Route prefix owned by this plugin. */
+const API_PREFIX = "/dsh-model-input-toggle/api";
+
+/** Settings namespace and model-field name for each supported adapter. */
+const PI = { ns: "llm-pi-ai", field: "input" };
+const DS = { ns: "llm-deepseek", field: "inputModalities" };
+
+/** Modality lists this plugin writes. */
+const TEXT = ["text"];
+const TEXT_IMAGE = ["text", "image"];
+
+/** Max accepted request body. */
+const MAX_BODY_BYTES = 256 * 1024;
+
+/** Wall-clock budget for one endpoint verification request. */
+const VERIFY_TIMEOUT_MS = 45000;
+
+/** A 1x1-ish solid PNG used as the probe image (valid, tiny, no network fetch). */
+const PROBE_PNG_B64 =
+	"iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAeklEQVR4nO3PUQkAIBTAwBfHiIY1jCH8OITBAtxm7fN1wwUNaEEDWtCAFjSgBQ1oQQNa0IAWNKAFDWhBA1rQgBY0oAUNaEEDWtCAFjSgBQ1oQQNa0IAWNKAFDWhBA1rQgBY0oAUNaEEDWtCAFjSgBQ1oQQNa0IAWPHYBhBLBWprx9KEAAAAASUVORK5CYII=";
+
+// ── small helpers ──────────────────────────────────────────────────────────
+
+/** A non-empty array of strings, or undefined. Empty means "not declared". */
+function nonEmpty(value) {
+	return Array.isArray(value) && value.length > 0 ? value : undefined;
+}
+
+/** Plain JSON deep clone (settings sections are always lossless JSON). */
+function clone(value) {
+	return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+/** Whether one resolved model declares image input. */
+function hasImage(list) {
+	return Array.isArray(list) && list.includes("image");
+}
+
+/** Append one model id to a list, ignoring blanks and duplicates. */
+function pushId(ids, id) {
+	if (typeof id === "string" && id.length > 0 && !ids.includes(id)) ids.push(id);
+}
+
+/** Best-effort human message from an unknown thrown value. */
+function messageOf(error) {
+	if (error === null || error === undefined) return "unknown error";
+	if (typeof error === "string") return error;
+	const message = error.message;
+	return typeof message === "string" && message.length > 0 ? message : String(error);
+}
+
+// ── trust fence (same contract as dsh-agconfig / dsh-agimage) ──────────────
+// Loopback-or-trusted Host header plus same-origin browser markers. This is a
+// DNS-rebinding / cross-site defense, not authentication: the route can write
+// settings and spend an endpoint request, so it must never be reachable from a
+// cross-site page.
+
+/** Normalized URL of a Host-header authority, or undefined when unparsable. */
+function parseAuthority(authority) {
+	try {
+		return new URL(`http://${authority}`);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Whether a normalized URL hostname names the local loopback authority. */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4
+		&& parts[0] === "127"
+		&& parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+
+/** Canonical authority form: hostname, or hostname:port when a port was written. */
+function canonicalAuthority(entry, entryUrl) {
+	const port = entryUrl.port !== "" ? entryUrl.port : new URL(`https://${entry}`).port;
+	return port === "" ? entryUrl.hostname : `${entryUrl.hostname}:${port}`;
+}
+
+/** Whether a trustedHosts entry matches this request authority. */
+function isTrustedAuthority(hostUrl, trustedHosts) {
+	return trustedHosts.some((entry) => {
+		const entryUrl = parseAuthority(entry);
+		if (entryUrl === undefined) return false;
+		return canonicalAuthority(entry, entryUrl) === entryUrl.hostname
+			? entryUrl.hostname === hostUrl.hostname
+			: entryUrl.host === hostUrl.host;
+	});
+}
+
+/** Whether one request may reach the plugin routes. */
+function isTrustedApiRequest(req, trustedHosts) {
+	const host = typeof req.headers.host === "string" ? req.headers.host : undefined;
+	if (host === undefined) return false;
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === undefined) return false;
+	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false;
+	if (req.headers["sec-fetch-site"] === "cross-site") return false;
+	const origin = req.headers.origin;
+	if (origin === undefined) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+
+// ── JSON body / response helpers ───────────────────────────────────────────
+
+const PAYLOAD_TOO_LARGE = Symbol("payload-too-large");
+
+/** Read a JSON request body, capped at MAX_BODY_BYTES. */
+function readJsonBody(req) {
+	return new Promise((resolve) => {
+		const chunks = [];
+		let size = 0;
+		let aborted = false;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > MAX_BODY_BYTES && !aborted) {
+				aborted = true;
+				req.destroy();
+				resolve(PAYLOAD_TOO_LARGE);
+				return;
+			}
+			if (!aborted) chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (aborted) return;
+			try {
+				resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+			} catch {
+				resolve(null);
+			}
+		});
+		req.on("error", () => {
+			if (!aborted) resolve(null);
+		});
+	});
+}
+
+/** Write a JSON response. */
+function writeJson(res, status, value) {
+	res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+	res.end(JSON.stringify(value));
+}
+
+/** A structured refusal the client turns into an inline message. */
+function fail(code, message) {
+	return { ok: false, code, message };
+}
+
+// ── settings access ────────────────────────────────────────────────────────
+
+/**
+ * Read one adapter namespace raw.
+ *
+ * `describe({ redactSecrets: false })` is the only surface that returns BOTH
+ * the resolved value (schema defaults + base + user, deep-frozen) and the raw
+ * user section this plugin must edit. The raw section is required because a
+ * faithful rewrite of a `models` array has to start from what the user wrote,
+ * not from the materialized resolution.
+ *
+ * @returns {{revision:number, value:object, user:object} | undefined}
+ */
+function readNamespace(settings, ns) {
+	let descriptors;
+	try {
+		descriptors = settings.describe({ redactSecrets: false });
+	} catch (error) {
+		throw new Error(`无法读取设置命名空间（${ns}）：${messageOf(error)}`);
+	}
+	const found = descriptors.find((entry) => entry.ns === ns);
+	if (found === undefined) {
+		throw new Error(`设置命名空间 "${ns}" 未注册：对应适配器插件没有挂载。`);
+	}
+	return {
+		revision: found.revision,
+		value: found.value !== null && typeof found.value === "object" ? found.value : {},
+		user: found.user !== null && typeof found.user === "object" ? found.user : {}
+	};
+}
+
+/** Resolve one credential reference through the service, then the environment. */
+async function resolveSecret(ctx, ref) {
+	if (typeof ref !== "string" || ref.length === 0) return undefined;
+	const credentials = ctx.get("credentials");
+	if (credentials !== undefined) {
+		try {
+			const resolved = await credentials.resolve(ref);
+			if (resolved !== undefined && typeof resolved.value === "string" && resolved.value.length > 0) {
+				return resolved.value;
+			}
+		} catch {
+			// fall through to the environment
+		}
+	}
+	const fromEnv = process.env[ref];
+	return typeof fromEnv === "string" && fromEnv.length > 0 ? fromEnv : undefined;
+}
+
+/**
+ * Resolve a model's effective modalities through the live registry.
+ *
+ * This is the authoritative answer: it is the same `resolveModelInfo` the
+ * request path uses to decide whether an image may be sent. Reading it back
+ * after a write is what turns "the YAML changed" into "the adapter agrees".
+ *
+ * @returns {Promise<string[] | undefined>} modalities, or undefined when the
+ *   route/model cannot be resolved yet.
+ */
+async function effectiveModalities(llm, provider, modelId) {
+	if (llm === undefined) return undefined;
+	try {
+		const info = await llm.resolveModelInfo(provider, modelId);
+		return Array.isArray(info.inputModalities) ? info.inputModalities.map(String) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// ── model inventory ────────────────────────────────────────────────────────
+
+/**
+ * Build the model inventory for one pi-ai provider route.
+ *
+ * Model ids come from the user's own `models` list when it exists (that list is
+ * the served catalog), then from `modelOverrides` keys, then from the live
+ * registry — so a catalog-backed route still lists what it actually serves.
+ */
+async function describePiAiRoute(llm, route, resolvedProvider, userProvider, catalogBacked) {
+	const defaultInput = nonEmpty(resolvedProvider?.defaultInput) ?? TEXT;
+	const resolvedModels = Array.isArray(resolvedProvider?.models) ? resolvedProvider.models : [];
+	const userModels = Array.isArray(userProvider?.models) ? userProvider.models : [];
+	const userOverrides = userProvider?.modelOverrides !== null && typeof userProvider?.modelOverrides === "object"
+		? userProvider.modelOverrides
+		: {};
+
+	const ids = [];
+	for (const model of resolvedModels) pushId(ids, model?.id);
+	for (const id of Object.keys(userOverrides)) pushId(ids, id);
+	// A catalog-backed route whose resolved config mirrors no `models` list has
+	// no enumerable source here, and `llm.resolveModelInfo` requires an exact
+	// id — so such a route renders no rows rather than guessing ids. Providers
+	// the user declared always list their models.
+
+	const models = [];
+	for (const id of ids) {
+		const findById = (model) => model !== null && typeof model === "object" && model.id === id;
+		const resolved = resolvedModels.find(findById);
+		const userModel = userModels.find(findById);
+		const userOverride = userOverrides[id];
+
+		// Where the model's image capability currently comes from:
+		//  - 'model'          the user declared `input` on a `models` entry
+		//  - 'modelOverrides' the user declared `input` in `modelOverrides`
+		//  - 'catalog'        only the installed pi-ai catalog declares it
+		//  - 'defaultInput'   nothing declares it; the provider default applies
+		// `locked` follows from that: a catalog declaration is product data this
+		// plugin refuses to overwrite, so such a row is shown checked and inert.
+		const declaredOnModel = nonEmpty(userModel?.[PI.field]) !== undefined;
+		const declaredOnOverride = nonEmpty(userOverride?.[PI.field]) !== undefined;
+		const source = declaredOnModel
+			? "model"
+			: declaredOnOverride
+				? "modelOverrides"
+				: catalogBacked
+					? "catalog"
+					: "defaultInput";
+
+		const declaredInput = nonEmpty(userModel?.[PI.field]) ?? nonEmpty(userOverride?.[PI.field]);
+		const effective = (await effectiveModalities(llm, route, id))
+			?? declaredInput
+			?? (catalogBacked ? nonEmpty(resolved?.[PI.field]) : undefined)
+			?? defaultInput;
+
+		models.push({
+			id,
+			name: typeof (userModel?.name ?? resolved?.name) === "string" ? (userModel?.name ?? resolved?.name) : id,
+			effective: [...effective],
+			source,
+			locked: source === "catalog"
+		});
+	}
+	return models;
+}
+
+/** Build the model inventory for the built-in llm-deepseek namespace. */
+async function describeDeepseekModels(ctx, llm, resolvedValue, userValue) {
+	const field = DS.field;
+	const resolvedModels = Array.isArray(resolvedValue?.models) ? resolvedValue.models : [];
+	const userModels = Array.isArray(userValue?.models) ? userValue.models : [];
+	const ids = [];
+	for (const model of resolvedModels) {
+		if (typeof model?.id === "string" && !ids.includes(model.id)) ids.push(model.id);
+	}
+	for (const model of userModels) {
+		if (typeof model?.id === "string" && !ids.includes(model.id)) ids.push(model.id);
+	}
+	const models = [];
+	for (const id of ids) {
+		const resolved = resolvedModels.find((model) => model?.id === id);
+		const userModel = userModels.find((model) => model?.id === id);
+		const declaredInput = nonEmpty(userModel?.[field]);
+		// No user declaration means the built-in catalog supplied it.
+		const source = declaredInput !== undefined ? "model" : "catalog";
+		const effective = (await effectiveModalities(llm, "deepseek-official", id))
+			?? declaredInput
+			?? nonEmpty(resolved?.[field])
+			?? TEXT;
+		models.push({
+			id,
+			name: typeof (userModel?.name ?? resolved?.name) === "string" ? (userModel?.name ?? resolved?.name) : id,
+			effective: [...effective],
+			source,
+			locked: source === "catalog"
+		});
+	}
+	return models;
+}
+
+/**
+ * Full inventory for the settings page: every provider route this plugin can
+ * extend, with each model's effective modalities, the source of that
+ * declaration, and whether the row is locked.
+ *
+ * Either adapter may legitimately be absent, so a missing namespace is not a
+ * failure; only "neither adapter is readable" is reported as one.
+ */
+async function listInventory(ctx) {
+	const settings = ctx.get("settings");
+	if (settings === undefined) {
+		return fail("no-settings", "settings 服务不可用：无法读取模型配置。");
+	}
+	const llm = ctx.get("llm");
+	const providers = [];
+	const problems = [];
+
+	// ── llm-pi-ai ──
+	try {
+		const pi = readNamespace(settings, PI.ns);
+		let directory = [];
+		if (llm !== undefined) {
+			try {
+				directory = llm.listConfigurableProviders();
+			} catch {
+				directory = [];
+			}
+		}
+		const routes = [];
+		for (const entry of directory) {
+			if (entry !== null && typeof entry === "object" && entry.settingsNs === PI.ns
+				&& typeof entry.provider === "string" && !routes.includes(entry.provider)) {
+				routes.push(entry.provider);
+			}
+		}
+		// A route the directory has not published (dormant declaration) still
+		// exists in the user's config, so union both sources.
+		for (const route of Object.keys(pi.user.providers ?? {})) {
+			if (!routes.includes(route)) routes.push(route);
+		}
+		const catalogBacked = new Map();
+		for (const entry of directory) {
+			if (entry !== null && typeof entry === "object" && typeof entry.provider === "string") {
+				// `declared === false` => the installed pi-ai catalog knows this
+				// route; anything else was declared by the user.
+				catalogBacked.set(entry.provider, entry.declared !== true);
+			}
+		}
+		for (const route of routes) {
+			const resolvedProvider = pi.value.providers?.[route];
+			const userProvider = pi.user.providers?.[route];
+			if (resolvedProvider === undefined && userProvider === undefined) continue;
+			providers.push({
+				router: "pi-ai",
+				namespace: PI.ns,
+				provider: route,
+				displayName: typeof resolvedProvider?.displayName === "string" ? resolvedProvider.displayName : route,
+				baseURL: typeof resolvedProvider?.baseURL === "string" ? resolvedProvider.baseURL : undefined,
+				api: typeof resolvedProvider?.api === "string" ? resolvedProvider.api : undefined,
+				apiKeyEnv: typeof resolvedProvider?.apiKeyEnv === "string" ? resolvedProvider.apiKeyEnv : undefined,
+				models: await describePiAiRoute(llm, route, resolvedProvider, userProvider, catalogBacked.get(route) === true)
+			});
+		}
+	} catch (error) {
+		problems.push(`llm-pi-ai: ${messageOf(error)}`);
+	}
+
+	// ── llm-deepseek ──
+	try {
+		const ds = readNamespace(settings, DS.ns);
+		const models = await describeDeepseekModels(ctx, llm, ds.value, ds.user);
+		if (models.length > 0) {
+			providers.push({
+				router: "deepseek",
+				namespace: DS.ns,
+				provider: "deepseek-official",
+				displayName: "DeepSeek",
+				baseURL: typeof ds.value?.baseURL === "string" ? ds.value.baseURL : undefined,
+				api: typeof ds.value?.protocol === "string" ? ds.value.protocol : undefined,
+				apiKeyEnv: typeof ds.value?.apiKeyEnv === "string" ? ds.value.apiKeyEnv : undefined,
+				models
+			});
+		}
+	} catch (error) {
+		problems.push(`llm-deepseek: ${messageOf(error)}`);
+	}
+
+	if (providers.length === 0 && problems.length > 0) {
+		return fail("unreadable", `无法读取模型配置。${problems.join("；")}`);
+	}
+	return { ok: true, providers, warnings: problems.length > 0 ? problems : undefined };
+}
+
+// ── the write ──────────────────────────────────────────────────────────────
+
+/**
+ * Compute the `mutate` ops for one toggle.
+ *
+ * @returns {{ops: object[]} | {error: object}}
+ */
+function planPiAiWrite(settings, provider, modelId, enable) {
+	const raw = readNamespace(settings, PI.ns);
+	const resolved = raw.value;
+	const user = raw.user;
+
+	const resolvedProvider = resolved.providers?.[provider];
+	const userProvider = user.providers?.[provider];
+	if (resolvedProvider === undefined && userProvider === undefined) {
+		return { error: fail("provider-missing", `provider "${provider}" 不存在于 llm-pi-ai 配置中。`) };
+	}
+
+	const desired = enable ? TEXT_IMAGE : TEXT;
+	const userModels = Array.isArray(userProvider?.models) ? userProvider.models : [];
+
+	if (userModels.length > 0) {
+		const index = userModels.findIndex((model) => model !== null && typeof model === "object" && model.id === modelId);
+		if (index < 0) {
+			return {
+				error: fail(
+					"model-missing",
+					`模型 "${modelId}" 不在 provider "${provider}" 的 models 列表中；请先在设置页添加该模型。`
+				)
+			};
+		}
+		// Rebuild the whole list so every sibling field survives verbatim. The
+		// op sets a leaf array, which is the deepest node applyPathOp can
+		// replace — an array index in the path would write nothing.
+		const models = clone(userModels);
+		models[index] = { ...models[index], [PI.field]: [...desired] };
+		return { ops: [{ op: "set", path: ["providers", provider, "models"], value: models }] };
+	}
+
+	// No user models list: llm-pi-ai serves this route from its catalog and
+	// allows per-model `modelOverrides`. (Declaring a full `models` list here
+	// would fold the installed catalog into the user's config.)
+	//
+	// No existence check is performed: the resolved config does not necessarily
+	// enumerate catalog models, so absence is not proof of nonexistence. An id
+	// the catalog genuinely does not describe is surfaced by the adapter's own
+	// diagnostics, and the post-write verification below reports it.
+	return {
+		ops: [{ op: "set", path: ["providers", provider, "modelOverrides", modelId, PI.field], value: [...desired] }]
+	};
+}
+
+/** Compute the `mutate` ops for one llm-deepseek toggle. */
+function planDeepseekWrite(settings, modelId, enable) {
+	const raw = readNamespace(settings, DS.ns);
+	const resolvedModels = Array.isArray(raw.value?.models) ? raw.value.models : [];
+	const userModels = Array.isArray(raw.user?.models) ? raw.user.models : [];
+	const desired = enable ? TEXT_IMAGE : TEXT;
+
+	if (userModels.length > 0) {
+		const index = userModels.findIndex((model) => model?.id === modelId);
+		if (index < 0) return { error: fail("model-missing", `模型 "${modelId}" 不存在于 llm-deepseek 的 models 列表中。`) };
+		const models = clone(userModels);
+		models[index] = { ...models[index], [DS.field]: [...desired] };
+		return { ops: [{ op: "set", path: ["models"], value: models }] };
+	}
+
+	// Nothing user-authored yet: materialize the resolved catalog with the one
+	// edited entry, because `models` has no per-entry override mechanism here.
+	const index = resolvedModels.findIndex((model) => model?.id === modelId);
+	if (index < 0) return { error: fail("model-missing", `模型 "${modelId}" 不存在于 llm-deepseek 中。`) };
+	const models = clone(resolvedModels);
+	models[index] = { ...models[index], [DS.field]: [...desired] };
+	return { ops: [{ op: "set", path: ["models"], value: models }] };
+}
+
+/**
+ * Set whether one model declares image input.
+ *
+ * Reads the current config, plans a minimal op, persists it with the revision
+ * it read (so a concurrent edit is detected rather than clobbered), retries
+ * once against a fresh read on conflict, then verifies the declaration through
+ * the live adapter.
+ */
+async function setModelImageInput(ctx, args) {
+	const settings = ctx.get("settings");
+	if (settings === undefined) return fail("no-settings", "settings 服务不可用：无法写入模型配置。");
+
+	const namespace = typeof args.namespace === "string" ? args.namespace : undefined;
+	const provider = typeof args.provider === "string" ? args.provider : undefined;
+	const modelId = typeof args.modelId === "string" ? args.modelId : undefined;
+	const enable = args.supportsImage === true;
+
+	if (namespace !== PI.ns && namespace !== DS.ns) {
+		return fail("unsupported-namespace", `不支持的设置命名空间 "${String(namespace)}"。`);
+	}
+	if (provider === undefined || provider.length === 0 || modelId === undefined || modelId.length === 0) {
+		return fail("bad-request", "provider 与 modelId 均为必填。");
+	}
+
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		let planned;
+		let revision;
+		try {
+			const descriptor = settings.describe({ redactSecrets: false }).find((entry) => entry.ns === namespace);
+			if (descriptor === undefined) return fail("no-namespace", `设置命名空间 "${namespace}" 未注册。`);
+			revision = descriptor.revision;
+			planned = namespace === PI.ns
+				? planPiAiWrite(settings, provider, modelId, enable)
+				: planDeepseekWrite(settings, modelId, enable);
+		} catch (error) {
+			return fail("read-failed", messageOf(error));
+		}
+		if (planned.error !== undefined) return planned.error;
+
+		try {
+			await settings.mutate(namespace, planned.ops, revision);
+		} catch (error) {
+			const code = error?.code;
+			if (code === "SETTINGS_CONFLICT" && attempt === 0) continue; // re-read and retry once
+			if (code === "SETTINGS_CONFLICT") {
+				return fail("conflict", "配置已被其它操作修改，重试后仍然冲突。请在设置页面手动刷新后重试。");
+			}
+			return fail("write-failed", messageOf(error));
+		}
+
+		// Verification: ask the adapter that will serve the request whether it
+		// now agrees. This is the difference between "we wrote a field" and
+		// "the image will no longer be intercepted".
+		const llm = ctx.get("llm");
+		const route = namespace === PI.ns ? provider : "deepseek-official";
+		const verified = await effectiveModalities(llm, route, modelId);
+		return {
+			ok: true,
+			namespace,
+			provider: route,
+			modelId,
+			requested: enable,
+			declared: verified === undefined ? undefined : [...verified],
+			verified: verified === undefined ? false : hasImage(verified) === enable,
+			verifiedReason: verified === undefined
+				? "适配器尚未返回该模型的元数据（provider 可能未激活）。配置已写入，重启或刷新后生效。"
+				: undefined
+		};
+	}
+	return fail("conflict", "配置冲突。");
+}
+
+// ── endpoint verification ──────────────────────────────────────────────────
+
+/** Map a pi-ai protocol name onto a chat-completions path, when supported. */
+function completionPath(api) {
+	switch (api) {
+		case "openai-completions":
+		case "openai-chat-completions":
+		case undefined:
+			return "/chat/completions";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Send one real image-bearing request to the configured endpoint.
+ *
+ * `input: ["text","image"]` only removes DSH's own interception. Whether the
+ * endpoint accepts an OpenAI-style `image_url` part is a separate, empirical
+ * fact — which is exactly what this measures. A 200 proves the endpoint
+ * accepted the payload; a 400 proves the declaration is a lie for this route.
+ */
+async function verifyEndpoint(ctx, args) {
+	const settings = ctx.get("settings");
+	if (settings === undefined) return fail("no-settings", "settings 服务不可用。");
+	const provider = typeof args.provider === "string" ? args.provider : "";
+	const modelId = typeof args.modelId === "string" ? args.modelId : "";
+	const namespace = typeof args.namespace === "string" ? args.namespace : "";
+	if (provider.length === 0 || modelId.length === 0) return fail("bad-request", "provider 与 modelId 均为必填。");
+
+	let baseURL;
+	let api;
+	let apiKeyEnv;
+	try {
+		if (namespace === PI.ns) {
+			const raw = readNamespace(settings, PI.ns);
+			const resolved = raw.value.providers?.[provider];
+			if (resolved === undefined) return fail("provider-missing", `provider "${provider}" 不存在。`);
+			baseURL = resolved.baseURL;
+			api = resolved.api ?? "openai-completions";
+			apiKeyEnv = resolved.apiKeyEnv;
+		} else {
+			const raw = readNamespace(settings, DS.ns);
+			if (!Array.isArray(raw.value?.models) || !raw.value.models.some((model) => model?.id === modelId)) {
+				return fail("model-missing", `模型 "${modelId}" 不存在于 llm-deepseek 中。`);
+			}
+			baseURL = raw.value.baseURL;
+			api = "openai-completions";
+			apiKeyEnv = raw.value.apiKeyEnv;
+		}
+	} catch (error) {
+		return fail("read-failed", messageOf(error));
+	}
+
+	if (typeof baseURL !== "string" || baseURL.length === 0) {
+		return fail("no-base-url", `provider "${provider}" 没有配置 baseURL，无法验证端点。`);
+	}
+	const path = completionPath(api);
+	if (path === undefined) {
+		return fail(
+			"unsupported-protocol",
+			`协议 "${String(api)}" 不支持自动验证（仅支持 openai-completions）。请改用带图片的真实请求手工验证。`
+		);
+	}
+
+	const key = await resolveSecret(ctx, apiKeyEnv);
+	if (key === undefined) {
+		return fail("no-credential", `未能解析凭据 "${String(apiKeyEnv)}"：请在设置页填写该 provider 的 API 密钥。`);
+	}
+
+	const url = baseURL.replace(/\/+$/, "") + path;
+	// Some gateways — this profile's jiuling/CodeBuddy proxy among them — reject
+	// any request whose first message is not a system prompt, before they ever
+	// look at the image. Leading with one keeps the probe about image support
+	// instead of about the gateway's envelope rules.
+	const SYS = { role: "system", content: "You are a helpful assistant." };
+	const imageRequest = {
+		model: modelId,
+		max_tokens: 16,
+		messages: [
+			SYS,
+			{
+				role: "user",
+				content: [
+					{ type: "text", text: "Reply with the single word: ok" },
+					{ type: "image_url", image_url: { url: `data:image/png;base64,${PROBE_PNG_B64}` } }
+				]
+			}
+		]
+	};
+	// The control request is identical except that it carries no image. It is
+	// what makes a non-200 answerable: a rejection that disappears when the
+	// image is removed proves the endpoint cannot take images, while a rejection
+	// of BOTH proves the probe never got far enough to test the image at all.
+	// Without this, any gateway or model-availability error would be misreported
+	// as "this model does not support images".
+	const controlRequest = {
+		model: modelId,
+		max_tokens: 16,
+		messages: [SYS, { role: "user", content: "Reply with the single word: ok" }]
+	};
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), VERIFY_TIMEOUT_MS);
+	try {
+		const attempt = async (payload) => {
+			const response = await fetch(url, {
+				method: "POST",
+				headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+				body: JSON.stringify(payload),
+				signal: controller.signal
+			});
+			return { status: response.status, ok: response.ok, text: await response.text() };
+		};
+		// Gateways frequently wrap the upstream error as a JSON *string* inside
+		// the message ("CodeBuddy 上游 HTTP 400：{"code":11128,"msg":"…"}"). Dumping
+		// that envelope buries the one useful sentence, so unwrap the outer JSON,
+		// then any JSON nested inside it, and prefer the most precise field.
+		const friendlyDetail = (raw) => {
+			const text = String(raw).replace(/\s+/g, " ").trim();
+			const start = text.indexOf("{");
+			if (start >= 0) {
+				try {
+					const inner = JSON.parse(text.slice(start));
+					const pick = (value) => (typeof value === "string" && value.length > 0 ? value : undefined);
+					const chosen = pick(inner?.msg)
+						?? pick(inner?.displayMsg?.zh)
+						?? pick(inner?.displayMsg?.en)
+						?? pick(inner?.error?.message);
+					if (chosen !== undefined) {
+						const prefix = text.slice(0, start).replace(/[：:]\s*$/, "").trim();
+						return (prefix.length > 0 ? `${prefix}：${chosen}` : chosen).slice(0, 300);
+					}
+				} catch {
+					// Not JSON, or truncated JSON: fall through to the raw text.
+				}
+			}
+			return text.slice(0, 300);
+		};
+		const detailOf = (text) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				parsed = undefined;
+			}
+			const message = typeof parsed?.error?.message === "string" ? parsed.error.message : text;
+			return friendlyDetail(message);
+		};
+
+		const probe = await attempt(imageRequest);
+		const detail = detailOf(probe.text);
+
+		if (probe.ok) {
+			return {
+				ok: true,
+				status: probe.status,
+				verdict: "supported",
+				message: "端点接受了带图片的请求（HTTP 200），该模型确实支持视觉输入。"
+			};
+		}
+		if (probe.status === 401 || probe.status === 403) {
+			return {
+				ok: false,
+				status: probe.status,
+				verdict: "unauthorized",
+				message: `凭据被拒绝（HTTP ${probe.status}）：请检查 API 密钥。`
+			};
+		}
+		if (probe.status === 404) {
+			return {
+				ok: false,
+				status: probe.status,
+				verdict: "not-found",
+				message: `端点不存在（HTTP 404）：请检查 baseURL 与协议。请求地址：${url}`
+			};
+		}
+
+		// Non-200. Decide whether the IMAGE is what failed by re-sending the same
+		// request with the image removed. Only an image-specific failure may be
+		// reported as "the endpoint does not accept images".
+		let control = null;
+		try {
+			control = await attempt(controlRequest);
+		} catch {
+			control = null;
+		}
+		if (control !== null && control.ok) {
+			return {
+				ok: true,
+				status: probe.status,
+				verdict: "rejected",
+				message: `端点拒绝了图片输入（HTTP ${probe.status}），而同一请求去掉图片后返回 HTTP 200：`
+					+ `该模型确实不支持视觉输入，建议取消勾选。端点说明：${detail}`
+			};
+		}
+		const controlNote = control === null
+			? "去掉图片的对照请求也未能完成"
+			: `去掉图片的同一请求仍然返回 HTTP ${control.status}`;
+		return {
+			ok: false,
+			status: probe.status,
+			verdict: "inconclusive",
+			message: `端点返回 HTTP ${probe.status}，但这与图片无关：${controlNote}，`
+				+ "说明该端点拒绝了这次请求本身（模型未开通、网关策略、参数不符等）。"
+				+ `请先确认该模型可正常对话，再验证图片能力。端点说明：${detail}`
+		};
+	} catch (error) {
+		const aborted = error?.name === "AbortError";
+		return {
+			ok: false,
+			status: -1,
+			verdict: aborted ? "timeout" : "network",
+			message: aborted
+				? `验证超时（${VERIFY_TIMEOUT_MS / 1000} 秒）。`
+				: `无法连接端点：${messageOf(error)}`
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+// ── route handling ─────────────────────────────────────────────────────────
+
+/** Dispatch one fenced API request. */
+async function handleApi(ctx, req, res) {
+	if (req.method !== "POST") {
+		writeJson(res, 405, fail("method-error", "method not allowed"));
+		return;
+	}
+	const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"].toLowerCase() : "";
+	if (!contentType.startsWith("application/json")) {
+		writeJson(res, 415, fail("unsupported-media-type", "content-type must be application/json"));
+		return;
+	}
+	const payload = await readJsonBody(req);
+	if (payload === PAYLOAD_TOO_LARGE) {
+		writeJson(res, 413, fail("payload-too-large", "request body too large"));
+		return;
+	}
+	if (payload === null || typeof payload !== "object" || typeof payload.method !== "string") {
+		writeJson(res, 400, fail("bad-request", "bad request"));
+		return;
+	}
+
+	switch (payload.method) {
+		case "list":
+			writeJson(res, 200, await listInventory(ctx));
+			return;
+		case "set":
+			writeJson(res, 200, await setModelImageInput(ctx, payload));
+			return;
+		case "verify":
+			writeJson(res, 200, await verifyEndpoint(ctx, payload));
+			return;
+		default:
+			writeJson(res, 404, fail("not-found", `unknown method "${payload.method}"`));
+	}
+}
+
+/**
+ * Host loader entry: mount the fenced settings bridge.
+ * @param ctx - host cordis context (webServer, webRuntime).
+ */
+export function apply(ctx) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: API_PREFIX,
+		handler: async (req, res) => {
+			if (!isTrustedApiRequest(req, ctx.webRuntime.trustedHosts)) {
+				writeJson(res, 403, fail("forbidden", "forbidden"));
+				return;
+			}
+			try {
+				await handleApi(ctx, req, res);
+			} catch (error) {
+				console.error("[dsh-model-input-toggle] api error:", error);
+				writeJson(res, 500, fail("internal", messageOf(error)));
+			}
+		}
+	}), "dsh-model-input-toggle: model input settings API");
+}