dsh-switchman 1.3.1 → 1.6.0

package/host/vision.js

@@ -0,0 +1,367 @@
+/**
+ * Vision dispatch gate: the /vision command + vision-state helper.
+ *
+ * DSH refuses plain prompts containing images while the session model
+ * reports no image input (MODEL_DOES_NOT_SUPPORT_IMAGES, thrown at
+ * prompt admission — the composer never blocks attaching). The command
+ * channel is the sanctioned unlock: a command declaring
+ * input.attachments: true passes NO model-capability check (the same
+ * channel /goal and /plan use), so /vision admits pasted images on a
+ * text-only session, resolves each admitted object's host path through
+ * the attachment store, and re-emits them as a TEXT followup — paths
+ * plus dispatch instructions — that any model can act on by delegating
+ * to the vision pool. The store's content-addressed objects carry NO
+ * file extension, which MCP image-analysis tools reject on sight
+ * ("Unsupported image format"), and normalization may hand us formats
+ * some tools refuse outright (e.g. image/webp) — so each image is
+ * first materialized into <DSH_HOME>/dsh-switchman/vision/ as a
+ * durable, extension-named copy (native copy for PNG/JPEG, transcoded
+ * to PNG via the first available converter for everything else).
+ * Calling read_image in a text-only context would only yield a
+ * placeholder, so the followup forbids that. With an empty vision
+ * pool the command refuses with setup guidance instead, and the client
+ * composer-dock hint (fed by GET /api/dsh-switchman/vision-state)
+ * points at the same setting. The hint's imageCapable verdict normally
+ * reads the first root session's model; the route's optional `session`
+ * query parameter judges the named session's own model instead (via the
+ * session-query observeSession channel shared with host/subagent-model.js),
+ * so a child session on a different route no longer misreports — unknown
+ * sessions fall back to the root verdict.
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, copyFile, mkdir, open, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { dshHome } from "./lib/dsh-home.js";
+import { sessionModelSelectionOf } from "./subagent-model.js";
+import { reportedUiLocale } from "./ui-locale.js";
+
+const execFile = promisify(execFileCb);
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Read one volatile settings field's plain value (live `.get()` ref or raw). */
+function readPool(field) {
+	const value =
+		field !== null && typeof field === "object" && typeof field.get === "function" ? field.get() : field;
+	return Array.isArray(value) ? value : [];
+}
+
+/** Host path of one admitted normalized image object: prefer the store's
+ * authoritative imageHostPath, else derive the content-addressed path
+ * from the attachmentId (sha256 of the NORMALIZED bytes — mediaType and
+ * dimensions on the ref also describe the normalized object, not the
+ * user's original file). Returns undefined when neither works. */
+function imageHostPathOf(store, ref) {
+	const viaStore = store?.imageHostPath?.(ref);
+	if (typeof viaStore === "string") return viaStore;
+	const match = /^sha256:([a-f0-9]{64})$/.exec(String(ref?.attachmentId ?? ""));
+	if (match === null) return undefined;
+	return join(dshHome(), "attachments", "v1", "objects", match[1].slice(0, 2), match[1]);
+}
+
+/** Formats MCP image tools accept verbatim — copied as-is with their
+ * native extension. Everything else gets transcoded to PNG. */
+const NATIVE_EXT = new Map([
+	["image/png", "png"],
+	["image/jpeg", "jpg"],
+	["image/pjpeg", "jpg"],
+]);
+
+/** Extension for the best-effort raw fallback when no converter exists. */
+const FALLBACK_EXT = new Map([
+	["image/webp", "webp"],
+	["image/gif", "gif"],
+	["image/bmp", "bmp"],
+	["image/tiff", "tiff"],
+	["image/avif", "avif"],
+]);
+
+/** Transcode-to-PNG chain, first executable wins (sips: macOS built-in;
+ * magick/ffmpeg: common cross-platform installs). */
+const CONVERTERS = [
+	{ bin: "sips", args: (src, dst) => ["-s", "format", "png", src, "--out", dst] },
+	{ bin: "magick", args: (src, dst) => [src, dst] },
+	{ bin: "ffmpeg", args: (src, dst) => ["-y", "-i", src, dst] },
+];
+
+const exists = (path) =>
+	access(path, constants.F_OK)
+		.then(() => true)
+		.catch(() => false);
+
+/** First-8-bytes PNG signature check — a converter killed mid-write
+ * (timeout, full disk) or exiting 0 with garbage output must not leave
+ * a corrupt file behind that the exists() cache would serve forever. */
+async function looksLikePng(path) {
+	let handle;
+	try {
+		handle = await open(path, "r");
+		const buf = Buffer.alloc(8);
+		const { bytesRead } = await handle.read(buf, 0, 8, 0);
+		return bytesRead === 8 && buf.equals(PNG_MAGIC);
+	} catch {
+		return false;
+	} finally {
+		await handle?.close?.().catch(() => {});
+	}
+}
+
+const drop = (path) => rm(path, { force: true }).catch(() => {});
+
+/** Materialize one admitted image into <DSH_HOME>/dsh-switchman/vision/
+ * as an extension-named, tool-readable copy keyed by its content hash
+ * (re-admitting the same object reuses the same file). PNG/JPEG copy
+ * natively; other formats transcode to PNG when a converter is
+ * available, else fall back to a native-extension copy the followup
+ * flags for manual conversion. Absolute last resort: the extension-less
+ * store path itself, clearly marked.
+ * @returns {Promise<{path: string, note?: string} | undefined>}
+ *     undefined only when the store path itself is unresolvable. */
+async function materializeImage(store, ref, warn) {
+	const src = imageHostPathOf(store, ref);
+	if (src === undefined) return undefined;
+	const idMatch = /^sha256:([a-f0-9]{64})$/.exec(String(ref?.attachmentId ?? ""));
+	const hash =
+		idMatch?.[1] ??
+		(String(ref?.attachmentId ?? "").replace(/[^A-Za-z0-9_-]/g, "") || randomUUID());
+	const dir = join(dshHome(), "dsh-switchman", "vision");
+	const native = NATIVE_EXT.get(String(ref?.mediaType ?? "").toLowerCase());
+
+	// Native PNG/JPEG: a plain copy is exactly what image tools want.
+	if (native !== undefined) {
+		const dst = join(dir, `${hash}.${native}`);
+		if (await exists(dst)) return { path: dst };
+		try {
+			await mkdir(dir, { recursive: true });
+			await copyFile(src, dst);
+			return { path: dst };
+		} catch (error) {
+			warn(`vision: native copy failed (${error?.message ?? error})`);
+			return {
+				path: src,
+				note: "extension-less store path — copy it to a .png/.jpg file before image tools can read it",
+			};
+		}
+	}
+
+	// Everything else: transcode to PNG via the first usable converter.
+	const dst = join(dir, `${hash}.png`);
+	if (await exists(dst)) {
+		if (await looksLikePng(dst)) return { path: dst, note: "transcoded to PNG" };
+		await drop(dst); // cached file is corrupt — rebuild it
+	}
+	try {
+		await mkdir(dir, { recursive: true });
+	} catch (error) {
+		warn(`vision: vision dir unavailable (${error?.message ?? error})`);
+		return {
+			path: src,
+			note: "extension-less store path — copy it to a .png file before image tools can read it",
+		};
+	}
+	for (const { bin, args } of CONVERTERS) {
+		try {
+			await execFile(bin, args(src, dst), { timeout: 20_000, windowsHide: true });
+		} catch {
+			// Converter missing or failed on this input — drop any partial
+			// output, then try the next one.
+			await drop(dst);
+			continue;
+		}
+		if (await looksLikePng(dst)) return { path: dst, note: `transcoded to PNG via ${bin}` };
+		await drop(dst); // exited 0 but output is not a PNG — keep trying
+	}
+
+	// No converter: best-effort native-extension copy + explicit flag.
+	const ext = FALLBACK_EXT.get(String(ref?.mediaType ?? "").toLowerCase()) ?? "img";
+	const raw = join(dir, `${hash}.${ext}`);
+	try {
+		await copyFile(src, raw);
+		warn(`vision: no PNG converter available; kept ${ref?.mediaType} copy at ${raw}`);
+		return {
+			path: raw,
+			note: "not transcoded — some image tools reject this format; convert it to PNG yourself first (e.g. sips -s format png <path> --out <out>.png)",
+		};
+	} catch (error) {
+		warn(`vision: fallback copy failed (${error?.message ?? error})`);
+		return {
+			path: src,
+			note: "extension-less store path — copy it to a .png file before image tools can read it",
+		};
+	}
+}
+
+/** Whether ONE exact model route accepts image input — the shared core of
+ *  the root and per-session verdicts. Mirrors the prompt-admission gate's
+ *  exact semantics: undefined inputModalities pass (no restriction
+ *  declared); anything else must include "image". Returns null when
+ *  unknowable (bad route, no llm service, resolution failure) — callers
+ *  treat null as "don't know", never as capable/incapable. */
+async function modelImageCapableOf(ctx, provider, model) {
+	try {
+		if (typeof provider !== "string" || provider === "" || typeof model !== "string" || model === "") return null;
+		const resolveModelInfo = ctx.get?.("llm", false)?.resolveModelInfo;
+		if (typeof resolveModelInfo !== "function") return null;
+		const info = await resolveModelInfo(provider, model);
+		if (info?.inputModalities === undefined) return true;
+		return Array.isArray(info.inputModalities) && info.inputModalities.includes("image");
+	} catch {
+		return null;
+	}
+}
+
+/** Whether the first root session's selected model accepts image input.
+ * Null when unknowable (no root, no usable selection). */
+async function rootImageCapableOf(ctx) {
+	try {
+		const root = ctx.agents?.roots?.()?.[0];
+		if (root === undefined) return null;
+		const current = ctx.agents?.selectionFor?.(root)?.current;
+		if (!current?.provider || !current?.model) return null;
+		return modelImageCapableOf(ctx, current.provider, current.model);
+	} catch {
+		return null;
+	}
+}
+
+/** Whether ONE named session's effective model accepts image input, via the
+ *  session-query observeSession channel (shared with host/subagent-model.js;
+ *  cold sessions resolve without activating the child). Null when the
+ *  session is unknown, unreadable, or carries no selection yet — callers
+ *  fall back to the root verdict. */
+async function sessionImageCapableOf(ctx, sessionId) {
+	const selection = await sessionModelSelectionOf(ctx, sessionId);
+	if (selection === null) return null;
+	return modelImageCapableOf(ctx, selection.provider, selection.model);
+}
+
+/**
+ * Live vision-gate state for the client hint route. `sessionId` (an optional
+ * child session id, from the vision-state route's `session` query parameter)
+ * judges image capability against THAT session's model; a missing/unknown
+ * session falls back to the first root session's verdict.
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ * @param {object} config - this plugin's live volatile config.
+ * @param {string | null} [sessionId] - session to judge instead of the root.
+ * @returns {Promise<{poolConfigured: boolean, imageCapable: boolean | null}>}
+ */
+export async function visionStateOf(ctx, config, sessionId = null) {
+	let imageCapable = typeof sessionId === "string" && sessionId !== "" ? await sessionImageCapableOf(ctx, sessionId) : null;
+	if (imageCapable === null) imageCapable = await rootImageCapableOf(ctx);
+	return {
+		poolConfigured: readPool(config.poolVision).length > 0,
+		imageCapable,
+	};
+}
+
+/** Localized (zh/en) helper for user-facing command result text. */
+const isZh = () => (reportedUiLocale() ?? "").toLowerCase().startsWith("zh");
+
+/**
+ * Mount the /vision command (global, plain-context registration).
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ * @param {object} config - this plugin's live volatile config.
+ */
+export function applyVision(ctx, config) {
+	const warn = (message) => ctx.logger?.warn?.(`dsh-switchman: ${message}`);
+	ctx.commands?.register?.({
+		name: "vision",
+		description:
+			"Send pasted images with a text-only session model: admits the attachments, hands their host paths to the agent, and instructs vision-pool dispatch.",
+		input: { hint: "[message to accompany the images]", attachments: true },
+		handler: async (invocation) => {
+			const agent = invocation?.agent;
+			const attachments = Array.isArray(invocation?.attachments) ? invocation.attachments : [];
+			const message = (invocation?.rawInput ?? "").trim();
+			// Defensive (the frozen CommandInvocation contract always carries
+			// agent): a missing followup must NOT yield a false success below.
+			if (typeof agent?.followup !== "function") {
+				return {
+					kind: "error",
+					text: isZh() ? "/vision：当前会话不可用，未发送。" : "/vision: no usable session agent; nothing was sent.",
+				};
+			}
+			const images = attachments.filter((block) => block?.type === "image" && block.attachment);
+			if (attachments.some((block) => block?.type === "file")) {
+				return {
+					kind: "error",
+					text: isZh()
+						? "/vision：仅接受图片附件。普通文件不受模型读图限制，直接随普通消息发送即可。"
+						: "/vision: image attachments only. Generic files are not gated by image support — send them with a normal message.",
+				};
+			}
+			if (images.length === 0) {
+				return {
+					kind: "error",
+					text: isZh()
+						? "/vision：没有图片附件。请先粘贴或拖入图片，再发送本命令。"
+						: "/vision: no image attachments. Paste or drop images before sending this command.",
+				};
+			}
+			if (readPool(config.poolVision).length === 0) {
+				return {
+					kind: "error",
+					text: isZh()
+						? "/vision：视觉池未配置模型。当前会话模型不支持读图——请先在 设置 → dsh-switchman → 派发池与模型排序 的「视觉池 · vision」中添加模型，再重新发送。"
+						: "/vision: the vision pool has no models. This session model cannot read images — add vision-pool models under Settings → dsh-switchman → dispatch pools, then resend.",
+				};
+			}
+			const store = ctx.get?.("attachments", false);
+			const lines = [];
+			for (const block of images) {
+				const material = await materializeImage(store, block.attachment, warn);
+				if (material === undefined) {
+					warn("vision: could not resolve host path for admitted image");
+					return {
+						kind: "error",
+						text: isZh()
+							? "/vision：无法解析某张已收图片的宿主路径（附件存储不可达且推导失败），本次未发送。"
+							: "/vision: could not resolve the host path of an admitted image (attachment store unreachable and derivation failed); nothing was sent.",
+					};
+				}
+				const ref = block.attachment;
+				const name = typeof ref.name === "string" && ref.name !== "" ? `, ${ref.name}` : "";
+				const note = material.note === undefined ? "" : ` — ${material.note}`;
+				lines.push(`- ${material.path} (${ref.mediaType}${name}, ${ref.width}x${ref.height}${note})`);
+			}
+			const followup = [
+				"[SWITCHMAN:VISION] The user sent image attachment(s) that this session model cannot read directly.",
+				`User message: ${message === "" ? "(none)" : message}`,
+				"Admitted normalized objects, already materialized as extension-named readable copies (absolute host paths):",
+				...lines,
+				"Read them by delegating to the vision pool (vision lane): pass a local file path above to an MCP image-analysis tool that accepts paths (e.g. analyze_image with image_source=<path>). Each path already carries a proper file extension (non-PNG/JPEG formats were transcoded to PNG where a converter was available), so image tools accept the paths directly — do not re-copy files yourself unless a per-file note asks you to. Do NOT call read_image on them yourself — a text-only context would only receive a placeholder. Then answer the user in their language.",
+			].join("\n");
+			try {
+				agent?.followup?.({
+					// The gateway's stored-session validation (assertMessageEventShape)
+					// rejects a user/message whose record lacks a non-empty id/role —
+					// an id-less synthetic message bricks the session on reload
+					// ("session event at seq N lacks an identified message").
+					id: randomUUID(),
+					role: "user",
+					content: [{ type: "text", text: followup }],
+					source: { kind: "user" },
+				});
+				await ctx.sessions?.flush?.(agent?.session);
+			} catch (error) {
+				warn(`vision: followup failed: ${error?.message ?? error}`);
+				return {
+					kind: "error",
+					text: isZh()
+						? `/vision：消息回注失败（${error?.message ?? error}），图片未送达会话。`
+						: `/vision: followup failed (${error?.message ?? error}); the images were not delivered.`,
+				};
+			}
+			return {
+				kind: "success",
+				text: isZh()
+					? `[SWITCHMAN:VISION] 已放行 ${images.length} 张图片，并把带扩展名的可读副本+视觉派发指令注入会话。`
+					: `[SWITCHMAN:VISION] ${images.length} image(s) admitted; extension-named readable copies + vision-dispatch instructions injected into the session.`,
+			};
+		},
+	});
+}

package/index.js

@@ -20,8 +20,19 @@
  *
  * Phase 3 mounts the context-watermark layer (host/context-watch.js): the
  * `[SWITCHMAN:WATERMARK]` tiered banner from the live token meter, a per-turn
- * read budget with deny/cap gates, force-tier fire-and-forget handover into
- * compaction, and the /ctx-pause, /ctx-resume, /ctx-handover commands.
+ * read budget with deny/cap gates, the four-step force-tier handover
+ * (backup fork + document + compaction + continuation) plus the
+ * ctx_handover agent tool, and the /ctx-pause, /ctx-resume,
+ * /ctx-handover commands.
+ *
+ * Teams mode mounts two more layers: host/teams.js carries the team clauses
+ * extracted from the cordis.patch.yml suffix in a `[SWITCHMAN:TEAMS]` section
+ * (order 10250, injected only while teamsMode is ON) plus the deferred ON
+ * orchestration (agent-team bundle enable, then the optional six-pool
+ * → DSH whitelist replace-sync); host/subagent-model.js annotates successful
+ * subagent / subagent_fork results with one `model: provider/model@effort`
+ * line from the child session's modelSelection projection (the same channel
+ * host/vision.js reuses for the per-session vision-state verdict).
  */
 
 import { readdirSync, readFileSync } from "node:fs";
@@ -38,9 +49,17 @@ import { applyLanguage } from "./host/lang.js";
 // Dispatch-pool layer (pools recommendation section + enforce gate).
 import { applyDispatch } from "./host/dispatch.js";
 
+// Agent Teams layer (teams-mode doctrine section + bundle/whitelist
+// orchestration; the clause text extracted from the cordis.patch.yml suffix).
+import { applyTeams } from "./host/teams.js";
+// Subagent model-visibility layer (post-execute `model:` annotation).
+import { applySubagentModel } from "./host/subagent-model.js";
+
 // Context-watermark layer (banner + read budget + handover + /ctx-* commands).
 import { applyContextWatch } from "./host/context-watch.js";
-
+// Vision dispatch gate (/vision command + vision-state route for the
+// composer-dock hint): unlocks image sending on text-only models.
+import { applyVision } from "./host/vision.js";
 // Client-bridge routes (config snapshot/fenced write + model catalog for the
 // restricted browser half, which has no configForms/remote services).
 import { applyRoutes } from "./host/routes.js";
@@ -51,14 +70,23 @@ const name = "dsh-switchman";
 /** Services this plugin contributes to: the bundled-skill registry, the
  * system-prompt section registry, the settings store it writes back to, the
  * token meter and agent registry the watermark reads, the command registry
- * for /ctx-*, the subagents service the handover's backup fork goes through,
- * and the sessions persistence the handover's continuation flush uses.
+ * for /ctx-*, the tools registry for the ctx_handover agent tool, the
+ * subagents service the handover's backup fork goes through, the sessions
+ * persistence the handover's continuation flush uses, the plugin-manager
+ * service the teams layer's bundle enable goes through, and the session
+ * query engine the subagent model annotation + per-session vision verdicts
+ * read child modelSelection projections from. pluginManager and
+ * sessionQuery are profile-composition services (the plugin-manager bundle
+ * is disabled without profileContext; session-query ships in the base
+ * patch): deployments lacking them leave this fiber INACTIVE — a documented
+ * runtime precondition, not a degraded mode. The defensive ctx.get calls
+ * inside teams.js / subagent-model.js guard API drift, not absence.
  * Compaction is deliberately NOT injected: the desktop profile provides it
  * only inside each preset's per-agent isolated group (isolate: { compaction:
  * true }), never at this root — host/context-watch.js reaches it by borrowing
  * the session's own per-agent /compact handler through
  * ctx.commands.find(agent, "compact"). */
-const inject = ["skills", "systemPrompt", "settings", "tokenMeter", "commands", "agents", "webServer", "subagents", "sessions"];
+const inject = ["skills", "systemPrompt", "settings", "tokenMeter", "commands", "tools", "agents", "webServer", "subagents", "sessions", "pluginManager", "sessionQuery"];
 
 /** Must equal `BUNDLED_SKILL_RANK` of @deepseek-ai/dsh-skill (packaged skill
  *  providers and local bundled roots; below user entries, above none). Not
@@ -130,8 +158,9 @@ function loadSkillCandidates(root, warn) {
 }
 
 /** Register the bundled dsh-switchman skill provider on `ctx.skills` and
- *  mount the language (lang), dispatch (dispatch), and watermark
- *  (context-watch) layers. */
+ *  mount the language (lang), dispatch (dispatch), teams (teams), watermark
+ *  (context-watch), vision (vision), subagent model visibility
+ *  (subagent-model), and client-bridge (routes) layers. */
 function apply(ctx, config) {
 	const root = fileURLToPath(new URL("./skills/", import.meta.url));
 	const warn = (message) => ctx.logger.warn(`dsh-switchman: ${message}`);
@@ -147,7 +176,10 @@ function apply(ctx, config) {
 	ctx.skills.registerProvider(() => provider);
 	applyLanguage(ctx, config);
 	applyDispatch(ctx, config);
+	applyTeams(ctx, config);
 	applyContextWatch(ctx, config);
+	applyVision(ctx, config);
+	applySubagentModel(ctx);
 	applyRoutes(ctx, config);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-switchman",
-	"version": "1.3.1",
+	"version": "1.6.0",
 	"description": "Autonomous Agent Teams doctrine for the four shipped DeepSeek Harness presets, plus language preferences, dispatch pools with model ranking, and context watermark control.",
 	"license": "MIT",
 	"keywords": [

package/skills/db-query/package.json

@@ -2,7 +2,7 @@
   "name": "db-query-skill",
   "version": "1.0.0",
   "private": true,
-  "description": "pi 技能：数据库只读查询核验（MySQL / Redis）",
+  "description": "Read-only database query verification skill (MySQL / Redis)",
   "engines": {
     "node": ">=18"
   },

package/skills/db-query/scripts/lib/cli.js

@@ -1,9 +1,9 @@
 'use strict';
 
 /**
- * 严格 CLI 参数解析器
- * 支持 --key=value、--key value、布尔 flag、-- 分隔 SQL/Redis 命令
- * 未知选项、重复冲突、越界数字 → 立即失败（fail-closed）
+ * Strict CLI argument parser
+ * Supports --key=value, --key value, boolean flags, and -- to separate SQL/Redis commands
+ * Unknown options, duplicate conflicts, out-of-range numbers → fail immediately (fail-closed)
  */
 
 class CliError extends Error {
@@ -11,16 +11,16 @@ class CliError extends Error {
 }
 
 /**
- * 解析 CLI 参数，返回 { options: {}, rest: string[] }
+ * Parse CLI arguments and return { options: {}, rest: string[] }
  * @param {string[]} argv - process.argv.slice(2)
- * @param {object} spec - 参数规格 { name: { type, default, min, max, alias } }
+ * @param {object} spec - option spec { name: { type, default, min, max, alias } }
  */
 function parseCli(argv, spec) {
   const options = {};
   const rest = [];
   const seen = new Set();
 
-  // 填充默认值
+  // Fill in defaults
   for (const [key, def] of Object.entries(spec)) {
     if (def.default !== undefined) options[key] = def.default;
   }
@@ -29,13 +29,13 @@ function parseCli(argv, spec) {
   while (i < argv.length) {
     const arg = argv[i];
 
-    // -- 分隔符：后续全部作为位置参数
+    // -- separator: everything after it is positional
     if (arg === '--') {
       rest.push(...argv.slice(i + 1));
       break;
     }
 
-    // --option=value 或 --option value 形式
+    // --option=value or --option value form
     if (arg.startsWith('--')) {
       let key, value;
       const eqIdx = arg.indexOf('=');
@@ -44,29 +44,29 @@ function parseCli(argv, spec) {
         value = arg.slice(eqIdx + 1);
       } else {
         key = arg.slice(2);
-        // 查找规格中该选项的类型
+        // Look up the option's type in the spec
         const s = findSpec(spec, key);
-        if (!s) throw new CliError(`未知选项: --${key}`);
+        if (!s) throw new CliError(`Unknown option: --${key}`);
         if (s.type === 'boolean') {
           value = true;
         } else {
           i++;
-          if (i >= argv.length) throw new CliError(`--${key} 需要值`);
+          if (i >= argv.length) throw new CliError(`--${key} requires a value`);
           value = argv[i];
         }
       }
 
       const resolved = resolveAlias(spec, key);
-      if (!resolved) throw new CliError(`未知选项: --${key}`);
+      if (!resolved) throw new CliError(`Unknown option: --${key}`);
 
-      // 重复选项检查
-      if (seen.has(resolved)) throw new CliError(`重复选项: --${resolved}`);
+      // Duplicate option check
+      if (seen.has(resolved)) throw new CliError(`Duplicate option: --${resolved}`);
       seen.add(resolved);
 
       const s = spec[resolved];
       options[resolved] = coerceValue(resolved, value, s);
     } else {
-      // 非选项参数 → 位置参数
+      // Non-option argument → positional
       rest.push(arg);
     }
     i++;
@@ -75,7 +75,7 @@ function parseCli(argv, spec) {
   return { options, rest };
 }
 
-/** 在 spec 或 alias 中查找选项名 */
+/** Find an option name in the spec or its aliases */
 function findSpec(spec, key) {
   if (spec[key]) return spec[key];
   for (const s of Object.values(spec)) {
@@ -84,7 +84,7 @@ function findSpec(spec, key) {
   return null;
 }
 
-/** 解析别名到规范名 */
+/** Resolve an alias to its canonical name */
 function resolveAlias(spec, key) {
   if (spec[key]) return key;
   for (const [name, s] of Object.entries(spec)) {
@@ -93,23 +93,23 @@ function resolveAlias(spec, key) {
   return null;
 }
 
-/** 类型转换 + 边界检查 */
+/** Type coercion + bounds checking */
 function coerceValue(key, raw, spec) {
   if (spec.type === 'boolean') {
     if (raw === 'true' || raw === true) return true;
     if (raw === 'false' || raw === false) return false;
-    throw new CliError(`--${key} 期望布尔值，收到: ${raw}`);
+    throw new CliError(`--${key} expects a boolean, got: ${raw}`);
   }
   if (spec.type === 'integer') {
     const n = Number(raw);
-    if (!Number.isInteger(n)) throw new CliError(`--${key} 期望整数，收到: ${raw}`);
-    if (spec.min !== undefined && n < spec.min) throw new CliError(`--${key} 最小值 ${spec.min}，收到: ${n}`);
-    if (spec.max !== undefined && n > spec.max) throw new CliError(`--${key} 最大值 ${spec.max}，收到: ${n}`);
+    if (!Number.isInteger(n)) throw new CliError(`--${key} expects an integer, got: ${raw}`);
+    if (spec.min !== undefined && n < spec.min) throw new CliError(`--${key} minimum is ${spec.min}, got: ${n}`);
+    if (spec.max !== undefined && n > spec.max) throw new CliError(`--${key} maximum is ${spec.max}, got: ${n}`);
     return n;
   }
   if (spec.type === 'string' && spec.choices) {
     const lower = String(raw).toLowerCase();
-    if (!spec.choices.includes(lower)) throw new CliError(`--${key} 必须为 ${spec.choices.join('|')} 之一，收到: ${raw}`);
+    if (!spec.choices.includes(lower)) throw new CliError(`--${key} must be one of ${spec.choices.join('|')}, got: ${raw}`);
     return lower;
   }
   return String(raw);