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

package/tools/test.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * dsh-model-input-toggle — run every test in this directory.
+ *
+ * The suites are plain Node scripts with no test framework, so this simply runs
+ * them in sequence and aggregates the exit status.
+ *
+ * Run: node tools/test.mjs
+ */
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const suites = ["test-host.mjs", "test-client.mjs"];
+
+let failed = 0;
+for (const suite of suites) {
+	process.stdout.write(`\n══════ ${suite} ══════\n`);
+	// `stdio: "inherit"` keeps the child's own output streaming straight through.
+	const result = spawnSync(process.execPath, [join(here, suite)], { stdio: "inherit" });
+	if (result.status !== 0) failed += 1;
+}
+
+process.stdout.write(`\n${failed === 0 ? "ALL SUITES PASSED" : `${failed} SUITE(S) FAILED`}\n`);
+process.exit(failed === 0 ? 0 : 1);

package/tools/verify-endpoint.mjs

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+/**
+ * dsh-verify-model-image — standalone endpoint capability checker.
+ *
+ * WHY A SEPARATE TOOL
+ * -------------------
+ * `input: ["text","image"]` and `inputModalities: ["text","image"]` are
+ * DECLARATIONS. They tell DSH "this model accepts images", which stops DSH from
+ * intercepting the message. They cannot make the endpoint accept it. If the
+ * remote API does not implement OpenAI-style `image_url` parts, the visible
+ * failure simply moves from a local block to `HTTP 400`.
+ *
+ * This script answers the only question that actually matters: does THIS
+ * endpoint, at THIS baseURL, with THIS key, accept a real image-bearing request
+ * for THIS model? It is deliberately independent of the DSH process, so it can
+ * be run before trusting a checkbox (in CI, in a shell, or from the plugin's
+ * 「验证端点」 button, which performs the same probe on the host side).
+ *
+ * It reads provider settings from $DSH_HOME/settings.yaml when available so the
+ * common case needs no arguments; explicit flags always win.
+ *
+ * USAGE
+ *   node tools/verify-endpoint.mjs --provider agnes --model agnes-3.0-flash
+ *   node tools/verify-endpoint.mjs --base-url https://api.example.com/v1 \
+ *        --model my-vision-model --api-key sk-...
+ *   node tools/verify-endpoint.mjs --provider jiuling --model buddy:glm-5.3-flash --json
+ *
+ * EXIT CODES
+ *   0  the endpoint accepted the image (200)
+ *   1  the endpoint rejected the image (400/422) — the declaration is a lie
+ *   2  the probe could not decide (auth, network, 404, timeout, bad input)
+ *
+ * @module dsh-model-input-toggle/tools/verify-endpoint
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** Solid 64x64 PNG. A valid image payload that costs almost no tokens. */
+const PROBE_PNG_B64 =
+	"iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAeklEQVR4nO3PUQkAIBTAwBfHiIY1jCH8OITBAtxm7fN1wwUNaEEDWtCAFjSgBQ1oQQNa0IAWNKAFDWhBA1rQgBY0oAUNaEEDWtCAFjSgBQ1oQQNa0IAWNKAFDWhBA1rQgBY0oAUNaEEDWtCAFjSgBQ1oQQNa0IAWPHYBhBLBWprx9KEAAAAASUVORK5CYII=";
+
+/** Sentinel returned instead of throwing, so every exit path is explicit. */
+const USAGE = `dsh-verify-model-image — 验证模型端点是否真的接受图片输入
+
+用法:
+  node tools/verify-endpoint.mjs --provider <route> --model <id> [选项]
+  node tools/verify-endpoint.mjs --base-url <url> --model <id> --api-key <key> [选项]
+
+选项:
+  --provider <route>   llm-pi-ai 中的 provider 路由名（从 settings.yaml 读取 baseURL/密钥）
+  --model <id>         要验证的模型 id（必填）
+  --base-url <url>     直接指定端点基址（覆盖 --provider 的读取结果）
+  --api-key <key>      直接指定密钥（覆盖凭据解析）
+  --api-key-env <name> 指定凭据环境变量名
+  --protocol <name>    协议，默认 openai-completions
+  --timeout <ms>       单次请求超时，默认 45000
+  --json               以 JSON 输出结果
+  -h, --help           显示本帮助
+
+退出码: 0=端点接受图片  1=端点拒绝图片(400/422)  2=无法判定
+`;
+
+/** Parse `--flag value` / `--flag=value` / boolean `--flag` argv. */
+function parseArgs(argv) {
+	const args = { _: [] };
+	for (let i = 0; i < argv.length; i += 1) {
+		const token = argv[i];
+		if (!token.startsWith("--") && token !== "-h") {
+			args._.push(token);
+			continue;
+		}
+		const eq = token.indexOf("=");
+		if (eq > 0) {
+			args[token.slice(2, eq)] = token.slice(eq + 1);
+			continue;
+		}
+		const key = token === "-h" ? "help" : token.slice(2);
+		const next = argv[i + 1];
+		if (next !== undefined && !next.startsWith("--")) {
+			args[key] = next;
+			i += 1;
+		} else {
+			args[key] = true;
+		}
+	}
+	return args;
+}
+
+/** Absolute path of the DSH home directory. */
+function dshHome() {
+	return process.env.DSH_HOME && process.env.DSH_HOME.length > 0
+		? process.env.DSH_HOME
+		: join(homedir(), ".dsh");
+}
+
+/**
+ * Extract one provider's `baseURL`, `apiKeyEnv` and `api` from settings.yaml.
+ *
+ * This is a deliberately narrow reader: it looks for the requested route under
+ * the `llm-pi-ai.providers` block and takes only flat scalar keys, so it never
+ * needs to understand the model lists. Anything it does not find stays
+ * undefined and the caller falls back to explicit flags.
+ *
+ * @returns {{baseURL?: string, apiKeyEnv?: string, api?: string}}
+ */
+function readProviderFromSettings(route) {
+	let text;
+	try {
+		text = readFileSync(join(dshHome(), "settings.yaml"), "utf8");
+	} catch {
+		return {};
+	}
+	const lines = text.split(/\r?\n/);
+	const found = {};
+	// Track indentation to find "<route>:" inside llm-pi-ai.providers.
+	let inPiAi = false;
+	let inProviders = false;
+	let inRoute = false;
+	let routeIndent = -1;
+	for (const line of lines) {
+		if (line.trim().length === 0 || line.trimStart().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		const trimmed = line.trim();
+		if (indent === 0) {
+			inPiAi = trimmed === "llm-pi-ai:";
+			inProviders = false;
+			inRoute = false;
+			continue;
+		}
+		if (!inPiAi) continue;
+		if (!inProviders) {
+			inProviders = trimmed === "providers:";
+			continue;
+		}
+		if (!inRoute) {
+			if (trimmed === `${route}:`) {
+				inRoute = true;
+				routeIndent = indent;
+			}
+			continue;
+		}
+		// A key at or below the route's own indent ends the route block.
+		if (indent <= routeIndent) {
+			inRoute = false;
+			continue;
+		}
+		const match = /^(baseURL|apiKeyEnv|api):\s*(.*)$/.exec(trimmed);
+		if (match === null) continue;
+		let value = match[2].trim();
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+		if (value.length > 0) found[match[1]] = value;
+	}
+	return found;
+}
+
+/** Resolve a credential from the environment, then the DSH credentials file. */
+function resolveApiKey(apiKeyEnv) {
+	if (apiKeyEnv === undefined) return undefined;
+	if (typeof process.env[apiKeyEnv] === "string" && process.env[apiKeyEnv].length > 0) {
+		return process.env[apiKeyEnv];
+	}
+	try {
+		const text = readFileSync(join(dshHome(), ".credentials.yaml"), "utf8");
+		// Minimal scan for "<ref>:" followed by a scalar value.
+		const lines = text.split(/\r?\n/);
+		for (let i = 0; i < lines.length; i += 1) {
+			const match = new RegExp(`^\\s*${apiKeyEnv.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*(.*)$`).exec(lines[i]);
+			if (match === null) continue;
+			let value = match[1].trim();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (value.length > 0) return value;
+		}
+	} catch {
+		// no credential store: the caller reports the miss
+	}
+	return undefined;
+}
+
+/** Map a protocol name onto a chat-completions path, when supported. */
+function completionPath(protocol) {
+	switch (protocol) {
+		case "openai-completions":
+		case "openai-chat-completions":
+		case undefined:
+			return "/chat/completions";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Extract the sentence a human should read from an endpoint response.
+ *
+ * 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 when the message contains JSON,
+ * pull out its `msg` (most precise) or localized `displayMsg` instead.
+ *
+ * @param {string} raw - response body, or an already-extracted message.
+ * @returns {string} a single-line, length-capped explanation.
+ */
+function 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);
+}
+
+/** Process exit code, recorded so the dispatcher can drain before exiting. */
+let exitCode = 0;
+
+/**
+ * Report the result. Deliberately does NOT call `process.exit()`: on Windows,
+ * terminating while undici is still tearing down the sockets of two sequential
+ * requests trips a libuv assertion (`UV_HANDLE_CLOSING`) and reports a garbage
+ * exit code. The code is recorded here and applied after the dispatcher closes.
+ *
+ * @param {number} code - intended process exit code.
+ */
+function finish(code, result, asJson) {
+	if (asJson) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+	} else {
+		const mark = result.verdict === "supported"
+			? "✓"
+			: result.verdict === "rejected"
+				? "✕"
+				: result.verdict === "inconclusive"
+					? "?"
+					: "!";
+		process.stdout.write(`${mark} ${result.message}\n`);
+		if (result.url !== undefined) process.stdout.write(`  请求地址: ${result.url}\n`);
+		if (result.model !== undefined) process.stdout.write(`  模型: ${result.model}\n`);
+		if (result.detail !== undefined) process.stdout.write(`  端点响应: ${result.detail}\n`);
+	}
+	exitCode = code;
+}
+
+/** Entry point. */
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const asJson = args.json === true;
+	if (args.help === true || args.model === undefined) {
+		process.stdout.write(USAGE);
+		process.exit(args.help === true ? 0 : 2);
+	}
+
+	const model = String(args.model);
+	const route = args.provider === undefined ? undefined : String(args.provider);
+	const fromSettings = route === undefined ? {} : readProviderFromSettings(route);
+
+	const baseURL = args["base-url"] !== undefined ? String(args["base-url"]) : fromSettings.baseURL;
+	const protocol = args.protocol !== undefined
+		? String(args.protocol)
+		: fromSettings.api ?? "openai-completions";
+	const apiKeyEnv = args["api-key-env"] !== undefined ? String(args["api-key-env"]) : fromSettings.apiKeyEnv;
+	const apiKey = args["api-key"] !== undefined ? String(args["api-key"]) : resolveApiKey(apiKeyEnv);
+	const timeoutMs = args.timeout === undefined ? 45000 : Number(args.timeout);
+
+	if (baseURL === undefined || baseURL.length === 0) {
+		finish(2, {
+			ok: false,
+			verdict: "no-base-url",
+			model,
+			message: route === undefined
+				? "缺少 --base-url，且未指定可读取配置的 --provider。"
+				: `provider "${route}" 在 settings.yaml 中没有 baseURL，请用 --base-url 指定。`
+		}, asJson);
+		return;
+	}
+
+	const path = completionPath(protocol);
+	if (path === undefined) {
+		finish(2, {
+			ok: false,
+			verdict: "unsupported-protocol",
+			model,
+			message: `协议 "${protocol}" 不支持本工具的探测（仅支持 openai-completions）。`
+		}, asJson);
+		return;
+	}
+
+	if (apiKey === undefined || apiKey.length === 0) {
+		finish(2, {
+			ok: false,
+			verdict: "no-credential",
+			model,
+			message: apiKeyEnv === undefined
+				? "未提供 --api-key，且该 provider 没有配置 apiKeyEnv。"
+				: `未能解析凭据 "${apiKeyEnv}"：请设置该环境变量或用 --api-key 指定。`
+		}, asJson);
+		return;
+	}
+
+	const url = `${baseURL.replace(/\/+$/, "")}${path}`;
+	// Lead with a system message: some gateways (the CodeBuddy proxy behind this
+	// profile's jiuling route, for one) reject any request whose first message is
+	// not a system prompt — before they ever inspect the image. Without this the
+	// probe measures the gateway's envelope rules instead of image support.
+	const SYS = { role: "system", content: "You are a helpful assistant." };
+	const body = {
+		model,
+		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}` } }
+				]
+			}
+		]
+	};
+	// Identical control request with no image, used to tell an image-specific
+	// rejection apart from a request the endpoint would have refused anyway.
+	const controlBody = {
+		model,
+		max_tokens: 16,
+		messages: [SYS, { role: "user", content: "Reply with the single word: ok" }]
+	};
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 45000);
+	try {
+		const attempt = async (payload) => {
+			const response = await fetch(url, {
+				method: "POST",
+				headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+				body: JSON.stringify(payload),
+				signal: controller.signal
+			});
+			return { status: response.status, ok: response.ok, text: await response.text() };
+		};
+		// Gateways nest the useful sentence inside wrapped JSON; collapse
+		// whitespace and cap it so the output stays readable.
+		// Unwrap the outer envelope first, then the JSON string gateways often
+		// nest inside `error.message`, so the reported detail is one readable
+		// sentence rather than a wall of escaped JSON.
+		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(body);
+		const detail = detailOf(probe.text);
+
+		if (probe.ok) {
+			finish(0, {
+				ok: true,
+				status: probe.status,
+				verdict: "supported",
+				model,
+				url,
+				message: `端点接受了带图片的请求（HTTP ${probe.status}）：该模型确实支持视觉输入。`
+			}, asJson);
+			return;
+		}
+		if (probe.status === 401 || probe.status === 403) {
+			finish(2, {
+				ok: false,
+				status: probe.status,
+				verdict: "unauthorized",
+				model,
+				url,
+				detail,
+				message: `凭据被拒绝（HTTP ${probe.status}）：请检查 API 密钥。`
+			}, asJson);
+			return;
+		}
+		if (probe.status === 404) {
+			finish(2, {
+				ok: false,
+				status: probe.status,
+				verdict: "not-found",
+				model,
+				url,
+				detail,
+				message: `端点不存在（HTTP 404）：请检查 baseURL 与协议。`
+			}, asJson);
+			return;
+		}
+
+		// Non-200: re-send without the image to find out whether the image is
+		// actually what failed. Only an image-specific failure is reported as
+		// "does not support images"; anything else is inconclusive, not a verdict.
+		let control = null;
+		try {
+			control = await attempt(controlBody);
+		} catch {
+			control = null;
+		}
+		if (control !== null && control.ok) {
+			finish(1, {
+				ok: true,
+				status: probe.status,
+				verdict: "rejected",
+				model,
+				url,
+				detail,
+				message: `端点拒绝了图片输入（HTTP ${probe.status}），而同一请求去掉图片后返回 HTTP 200：`
+					+ `该模型确实不支持视觉输入，建议取消勾选。`
+			}, asJson);
+			return;
+		}
+		const controlNote = control === null
+			? "去掉图片的对照请求也未能完成"
+			: `去掉图片的同一请求仍然返回 HTTP ${control.status}`;
+		finish(2, {
+			ok: false,
+			status: probe.status,
+			verdict: "inconclusive",
+			model,
+			url,
+			detail,
+			message: `端点返回 HTTP ${probe.status}，但这与图片无关：${controlNote}，`
+				+ "说明该端点拒绝了这次请求本身（模型未开通、网关策略、参数不符等）。"
+				+ "请先确认该模型可正常对话，再验证图片能力。"
+		}, asJson);
+	} catch (error) {
+		const aborted = error?.name === "AbortError";
+		finish(2, {
+			ok: false,
+			status: -1,
+			verdict: aborted ? "timeout" : "network",
+			model,
+			url,
+			message: aborted
+				? `验证超时（${(Number.isFinite(timeoutMs) ? timeoutMs : 45000) / 1000} 秒）。`
+				: `无法连接端点：${String(error?.message ?? error)}`
+		}, asJson);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+await main();
+
+// Close undici's dispatcher before letting the process end. Without this,
+// exiting while its sockets are still being torn down trips a libuv assertion
+// on Windows (`!(handle->flags & UV_HANDLE_CLOSING)`) and the shell sees a
+// garbage exit code such as -1073740791 instead of the intended one.
+try {
+	const dispatcher = globalThis[Symbol.for("undici.globalDispatcher.1")];
+	if (dispatcher !== undefined && typeof dispatcher.close === "function") {
+		await dispatcher.close();
+	}
+} catch {
+	// A dispatcher that refuses to close must not change the reported verdict.
+}
+process.exitCode = exitCode;