@dp-bohrium/widget-cli 0.0.0-stage → 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,2251 @@
+#!/usr/bin/env node
+import { a as resolveWidgetProjects, i as checkWidgetProject, n as scaffoldDshWidget, o as compileAuthorManifest, r as buildWidgetPackage, t as auditDshPlugin } from "./dsh-DgkNH7L-.mjs";
+import { createRequire } from "node:module";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+//#region ../../scripts/widget/widget-dev.mjs
+const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const DEFAULT_PORT = 4300;
+const PROFILE_PATH = "/__widget/profile";
+const STATUS_PATH = "/__widget/status";
+const LAUNCH_PATH = "/__widget/launch.html";
+const V1_ROOT = "/__widget/v1";
+const DESCRIPTOR_PATH = `${V1_ROOT}/descriptor`;
+const CLAIM_PATH = `${V1_ROOT}/claim`;
+const V1_STATUS_PATH = `${V1_ROOT}/status`;
+const V1_PROFILE_PATH = `${V1_ROOT}/profile`;
+const EVENTS_PATH = `${V1_ROOT}/events`;
+const CONTROL_PATH = `${V1_ROOT}/control`;
+const GUEST_ROOT = "/__widget/guest";
+const DEVELOPMENT_PROTOCOL = "bohrium.widget-development-host";
+const CLI_PROTOCOL = "bohrium.widget-development-cli";
+const SESSION_HARD_TTL_MS = 864e5;
+const SSE_HEARTBEAT_INTERVAL_MS = 15e3;
+const RETAINED_GENERATIONS = 2;
+const GENERATION_LIMITS = Object.freeze({
+	fileCount: 256,
+	singleFileBytes: 25e6,
+	totalBytes: 1e8
+});
+const LOCAL_BRIDGE_HOST = "127.0.0.1";
+const LOCAL_BRIDGE_PORTS = [
+	47850,
+	47851,
+	47852,
+	47853,
+	47854
+];
+const OPEN_WIDGET_DEVELOPMENT_PATH = "/widget-host/desktop/open-widget-development";
+const LOCAL_BRIDGE_TIMEOUT_MS = 350;
+const RESOURCE_BUDGET = {
+	version: 1,
+	bundle: {
+		compressedBytes: 5e7,
+		expandedBytes: 1e8,
+		fileCount: 256,
+		singleFileBytes: 25e6
+	},
+	bridge: {
+		messageBytes: 256e3,
+		messagesPerSecond: 60,
+		pendingRequests: 32
+	},
+	files: {
+		readBytesPerRequest: 4194304,
+		readBytesPerRun: 16777216,
+		callsPerMinute: 120,
+		listPageSize: 100
+	},
+	timeouts: {
+		bundleLoadMs: 1e4,
+		handshakeMs: 1e4,
+		firstRenderMs: 1e4,
+		updateMs: 1e4,
+		capabilityMs: 15e3,
+		disposeGraceMs: 1e3
+	},
+	concurrency: {
+		activeIframesPerPage: 4,
+		activeIframesPerRun: 2,
+		hiddenRecycleMs: 6e4
+	},
+	retry: {
+		maxAttempts: 1,
+		initialDelayMs: 0,
+		maxDelayMs: 0,
+		totalMs: 0
+	},
+	failure: {
+		consecutiveFailures: 3,
+		windowMs: 6e4
+	}
+};
+const NETWORK_LIMITS = {
+	timeoutMs: 15e3,
+	maxRedirects: 4,
+	maxConcurrentRequests: 4,
+	callsPerMinute: 60,
+	requestHeaderBytes: 16384,
+	responseHeaderBytes: 32768,
+	requestBodyBytes: 1048576,
+	responseBodyBytes: 8388608
+};
+function usage$1() {
+	return `用法：pnpm widget:dev <project-dir|manifest.json> [选项]
+
+选项：
+  --open              启动后唤起宿主
+  --scheme <scheme>   deep link scheme（默认 widget-host；可按宿主配置覆盖）
+  --bridge <url>      指定宿主 loopback bridge；未指定时探测标准 bridge 端口
+  --json              输出机器可读启动结果和错误
+  --watch             监听 src、manifest.json 和 package.json，变化后重新 build
+  --no-build          使用现有的 manifest.widgetConfig.entry，不执行 build
+  --port <port>       固定 Profile 服务端口（默认 ${DEFAULT_PORT}）
+  --help              显示帮助
+
+开发流程：
+  1. 在 Widget 工程目录执行此命令。
+  2. 使用 --open（优先连接已运行的 host bridge），或复制命令输出的 <scheme>://widget-dev URL。
+  3. 在生产宿主中触发对应 Tool Result / File Preview / Panel。
+  4. 修改源码；--watch 会重建 Bundle。需要重新加载时，手动打开上方 Host URL。
+`;
+}
+function parseArgs(argv) {
+	const positional = [];
+	const options = {
+		open: false,
+		watch: false,
+		build: true,
+		port: DEFAULT_PORT,
+		scheme: "widget-host",
+		bridge: null,
+		json: false
+	};
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--help" || argument === "-h") return { help: true };
+		if (argument === "--json") options.json = true;
+		else if (argument === "--open") options.open = true;
+		else if (argument === "--watch") options.watch = true;
+		else if (argument === "--no-build") options.build = false;
+		else if (argument === "--scheme") {
+			const value = argv[++index];
+			if (!value || !/^[a-z][a-z0-9+.-]*$/u.test(value)) throw new Error("--scheme 必须是合法的 URI scheme");
+			options.scheme = value;
+		} else if (argument === "--bridge") {
+			const value = argv[++index];
+			if (!value) throw new Error("--bridge 需要一个 loopback bridge URL");
+			let bridge;
+			try {
+				bridge = new URL(value);
+			} catch {
+				throw new Error("--bridge 必须是合法的 HTTP(S) URL");
+			}
+			if (bridge.protocol !== "http:" && bridge.protocol !== "https:") throw new Error("--bridge 必须使用 HTTP(S) 协议");
+			if (![
+				"localhost",
+				"127.0.0.1",
+				"[::1]",
+				"::1"
+			].includes(bridge.hostname)) throw new Error("--bridge 必须指向 loopback 主机");
+			if (bridge.username || bridge.password || bridge.hash || bridge.search) throw new Error("--bridge 不得包含认证信息、query 或 hash");
+			const port = Number(bridge.port);
+			if (!bridge.port || !Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("--bridge 必须包含 1024 到 65535 之间的显式端口");
+			options.bridge = bridge.href;
+		} else if (argument === "--port") {
+			const value = Number(argv[++index]);
+			if (!Number.isInteger(value) || value < 1024 || value > 65535) throw new Error("--port 必须是 1024 到 65535 之间的整数");
+			options.port = value;
+		} else if (argument.startsWith("-")) throw new Error(`未知选项：${argument}`);
+		else positional.push(argument);
+	}
+	if (positional.length !== 1) throw new Error("需要一个 Widget 工程目录或 manifest.json");
+	return {
+		help: false,
+		project: positional[0],
+		...options
+	};
+}
+function createWidgetDevError(error, context = {}) {
+	return {
+		code: typeof error?.code === "string" && error.code.startsWith("WIDGET_DEV_") ? error.code : "WIDGET_DEV_FAILED",
+		message: error instanceof Error ? error.message : String(error),
+		context,
+		recovery: context.phase === "watch-build" ? "读取 status.lastBuildError，修复工程后重新保存源码或重新执行 build。" : "先读取 error.context 和 build 输出，修复工程或宿主连接后重试。"
+	};
+}
+function secureHeaders(contentType) {
+	return {
+		"cache-control": "no-store",
+		"content-type": contentType,
+		"referrer-policy": "no-referrer",
+		"x-content-type-options": "nosniff"
+	};
+}
+function json(response, status, value, extraHeaders = {}) {
+	const body = JSON.stringify(value);
+	response.writeHead(status, {
+		...secureHeaders("application/json; charset=utf-8"),
+		"content-length": Buffer.byteLength(body),
+		...extraHeaders
+	});
+	response.end(body);
+}
+function token() {
+	return randomBytes(32).toString("base64url");
+}
+function equalToken(actual, expected) {
+	if (typeof actual !== "string") return false;
+	const actualBytes = Buffer.from(actual);
+	const expectedBytes = Buffer.from(expected);
+	return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+function bearer(header) {
+	return /^Bearer ([A-Za-z0-9_-]+)$/u.exec(String(header ?? ""))?.[1] ?? null;
+}
+function formatDevelopmentEvent(type, data) {
+	return JSON.stringify({
+		protocol: CLI_PROTOCOL,
+		version: 1,
+		type,
+		data
+	});
+}
+function createWidgetDevelopmentSession({ origin, sessionId = token(), now = /* @__PURE__ */ new Date() }) {
+	const claimToken = token();
+	const accessToken = token();
+	const issuedAt = now.toISOString();
+	const expiresAt = new Date(now.getTime() + SESSION_HARD_TTL_MS).toISOString();
+	let claimed = false;
+	let disconnected = false;
+	const descriptor = Object.freeze({
+		protocol: DEVELOPMENT_PROTOCOL,
+		protocolVersion: 1,
+		sessionId,
+		issuedAt,
+		expiresAt,
+		origin,
+		endpoints: Object.freeze({
+			claim: CLAIM_PATH,
+			status: V1_STATUS_PATH,
+			events: EVENTS_PATH,
+			control: CONTROL_PATH,
+			profile: V1_PROFILE_PATH
+		})
+	});
+	return Object.freeze({
+		claimToken,
+		accessToken,
+		descriptor,
+		claim(candidate) {
+			if (claimed) throw new Error("Widget development session already claimed（已领取）");
+			if (Date.now() >= Date.parse(expiresAt)) throw new Error("claim token expired");
+			if (!equalToken(candidate, claimToken)) throw new Error("invalid claim token");
+			claimed = true;
+			return {
+				tokenType: "Bearer",
+				accessToken,
+				expiresAt
+			};
+		},
+		authorize(header) {
+			return !disconnected && Date.now() < Date.parse(expiresAt) && claimed && equalToken(bearer(header), accessToken);
+		},
+		disconnect() {
+			disconnected = true;
+		}
+	});
+}
+function slug(value) {
+	return String(value).toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "") || "widget";
+}
+function requestedGrants(requested = {}) {
+	const grants = [];
+	const files = requested.files ?? {};
+	if (files.list) grants.push({
+		name: "files.list",
+		limits: {
+			pageSize: 100,
+			callsPerMinute: 120
+		}
+	});
+	if (files.metadata) grants.push({
+		name: "files.metadata",
+		limits: { callsPerMinute: 120 }
+	});
+	if (files.read) grants.push({
+		name: "files.read",
+		limits: {
+			bytesPerRequest: 4194304,
+			bytesPerRun: 16777216,
+			callsPerMinute: 120
+		}
+	});
+	if (requested.events?.topics?.length) grants.push({
+		name: "events.read",
+		topics: [...requested.events.topics],
+		limits: {
+			callsPerMinute: 120,
+			pageSize: 100,
+			minPollMs: 1e3
+		}
+	});
+	if (requested.actions?.names?.length) grants.push({
+		name: "actions.invoke",
+		actions: [...requested.actions.names],
+		limits: { callsPerMinute: 120 }
+	});
+	if (requested.network?.fetch) grants.push({
+		name: "network.fetch",
+		limits: NETWORK_LIMITS
+	});
+	if (requested.presentation) grants.push({
+		name: "ui.presentation",
+		surfaces: [...requested.presentation.surfaces],
+		requiresHostConfirmation: true
+	});
+	return grants;
+}
+function createDevelopmentConfig({ manifest, runId, origin, launchUrl, digest, now = /* @__PURE__ */ new Date() }) {
+	const issuedAt = now.toISOString();
+	const expiresAt = new Date(now.getTime() + 6e5).toISOString();
+	const widgetId = slug(manifest.name);
+	return {
+		schemaVersion: 1,
+		hostApiVersion: 1,
+		configId: `widget-dev-${digest.slice(-12)}`,
+		runId,
+		mode: "preview",
+		issuedAt,
+		expiresAt,
+		recheckAt: new Date(now.getTime() + 3e5).toISOString(),
+		securityProfile: "runtime-security-profile-v1",
+		resourceBudget: RESOURCE_BUDGET,
+		runtime: {
+			origin,
+			catalogRevision: "widget-dev-local"
+		},
+		network: {
+			mode: "unavailable",
+			policyVersion: "widget-dev-local",
+			limits: NETWORK_LIMITS
+		},
+		bindings: [{
+			status: "loadable",
+			bindingId: `widget-dev-binding-${widgetId}`,
+			widgetId: `widget-dev-widget-${widgetId}`,
+			widgetVersionId: `widget-dev-version-${digest.slice(-12)}`,
+			digest,
+			manifest,
+			launch: {
+				url: launchUrl,
+				expiresAt
+			},
+			grantedCapabilities: requestedGrants(manifest.widgetConfig.requestedCapabilities)
+		}]
+	};
+}
+function createLaunchHtml(entryPath) {
+	return `<!doctype html><html><head><meta charset="utf-8"><title>Widget Development Host</title></head><body><script src="/${entryPath.split("/").map(encodeURIComponent).join("/")}"><\/script></body></html>`;
+}
+function guestGenerationRoot(generation) {
+	return `${GUEST_ROOT}/${generation.guestCapability}`;
+}
+function panelDevelopmentDescriptor(generation, profileUrl, statusUrl) {
+	const contribution = generation.manifest.widgetConfig.contribution;
+	const descriptor = {
+		profileUrl,
+		statusUrl
+	};
+	if (contribution.type !== "panel") return {
+		descriptor,
+		presentationRequests: []
+	};
+	const id = contribution.id;
+	const key = `widget-dev-panel-${slug(id)}`;
+	const runId = "widget-dev-run";
+	const widgetId = `widget-dev-widget-${slug(generation.manifest.name)}`;
+	const widgetVersionId = `widget-dev-version-${generation.digest.slice(-12)}`;
+	const requestedSurfaces = generation.manifest.widgetConfig.requestedCapabilities?.presentation?.surfaces;
+	const allowedSurfaces = ["workspace", ...Array.isArray(requestedSurfaces) ? requestedSurfaces : []].filter((surface, index, surfaces) => surfaces.indexOf(surface) === index);
+	const defaultSurface = allowedSurfaces[0];
+	const panel = {
+		key,
+		runId,
+		widgetId,
+		widgetVersionId,
+		snapshot: {
+			id,
+			title: generation.manifest.name,
+			state: "complete",
+			data: {}
+		},
+		presentation: {
+			allowedSurfaces,
+			defaultSurface,
+			movable: true,
+			resizable: true
+		}
+	};
+	const presentationRequests = [{
+		requestId: `widget-dev-present-${slug(id)}`,
+		key,
+		surface: defaultSurface
+	}];
+	return {
+		descriptor: {
+			...descriptor,
+			panel,
+			presentationRequests
+		},
+		presentationRequests
+	};
+}
+function readProject(projectRoot) {
+	const sourceManifest = JSON.parse(readFileSync(join(projectRoot, "manifest.json"), "utf8"));
+	const manifest = compileAuthorManifest(sourceManifest);
+	const entryPath = manifest.widgetConfig.entry;
+	const entryFile = join(projectRoot, entryPath);
+	if (!existsSync(entryFile) || statSync(entryFile).size === 0) throw new Error(`entry 不存在或为空：${entryPath}；先运行 build，或移除 --no-build`);
+	return {
+		manifest,
+		entryPath,
+		digest: `sha256:${createHash("sha256").update(readFileSync(entryFile)).digest("hex")}`
+	};
+}
+function contentType(path) {
+	if (path.endsWith(".js") || path.endsWith(".mjs")) return "text/javascript; charset=utf-8";
+	if (path.endsWith(".css")) return "text/css; charset=utf-8";
+	if (path.endsWith(".json")) return "application/json; charset=utf-8";
+	if (path.endsWith(".svg")) return "image/svg+xml";
+	if (path.endsWith(".png")) return "image/png";
+	if (path.endsWith(".jpg") || path.endsWith(".jpeg")) return "image/jpeg";
+	if (path.endsWith(".woff2")) return "font/woff2";
+	return "application/octet-stream";
+}
+function collectGenerationAssets(projectRoot, entryPath, limits) {
+	const rootName = entryPath.split("/")[0];
+	const assetRoot = resolve(projectRoot, rootName);
+	if (assetRoot !== projectRoot && !assetRoot.startsWith(`${projectRoot}${sep}`)) throw new Error(`entry 路径越界：${entryPath}`);
+	if (!existsSync(assetRoot) || !statSync(assetRoot).isDirectory()) throw new Error(`entry 资源目录不存在：${rootName}`);
+	const files = [];
+	const visit = (directory) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const file = join(directory, entry.name);
+			if (entry.isSymbolicLink() || lstatSync(file).isSymbolicLink()) throw new Error(`generation 不允许 symbolic link（符号链接）：${relative(projectRoot, file)}`);
+			if (entry.isDirectory()) visit(file);
+			else if (entry.isFile()) files.push(file);
+		}
+	};
+	visit(assetRoot);
+	if (files.length > limits.fileCount) throw new Error(`generation 资源数量超限：${files.length}/${limits.fileCount}`);
+	let totalBytes = 0;
+	return files.map((file) => {
+		const path = relative(projectRoot, file).replaceAll("\\", "/");
+		if (path.startsWith("../") || path.split("/").includes("..")) throw new Error(`generation 资源路径越界：${path}`);
+		const bytes = readFileSync(file);
+		if (bytes.byteLength > limits.singleFileBytes) throw new Error(`generation 单文件超限：${path}`);
+		totalBytes += bytes.byteLength;
+		if (totalBytes > limits.totalBytes) throw new Error(`generation 总字节数超限：${totalBytes}/${limits.totalBytes}`);
+		return {
+			path,
+			bytes
+		};
+	}).sort((a, b) => a.path.localeCompare(b.path));
+}
+function createDevelopmentGeneration(projectRoot, number = 0, limits = GENERATION_LIMITS) {
+	const { manifest, entryPath } = readProject(projectRoot);
+	const collected = collectGenerationAssets(projectRoot, entryPath, limits);
+	if (!collected.some(({ path }) => path === entryPath)) throw new Error(`entry 未进入 generation：${entryPath}`);
+	const hash = createHash("sha256");
+	const assets = [];
+	const assetBytes = /* @__PURE__ */ new Map();
+	for (const { path, bytes } of collected) {
+		const assetDigest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+		assets.push(Object.freeze({
+			path,
+			bytes: bytes.byteLength,
+			digest: assetDigest
+		}));
+		assetBytes.set(path, Buffer.from(bytes));
+		hash.update(path).update("\0").update(assetDigest).update("\0");
+	}
+	const digest = `sha256:${hash.digest("hex")}`;
+	return Object.freeze({
+		number,
+		digest,
+		guestCapability: token(),
+		manifest: Object.freeze(manifest),
+		entryPath,
+		assets: Object.freeze(assets),
+		getAsset(path) {
+			const bytes = assetBytes.get(path);
+			return bytes ? Buffer.from(bytes) : null;
+		}
+	});
+}
+function serveGenerationAsset(generation, path, response) {
+	const bytes = generation.getAsset(path);
+	if (!bytes) {
+		response.writeHead(404, secureHeaders("text/plain; charset=utf-8")).end("not found");
+		return;
+	}
+	response.writeHead(200, {
+		...secureHeaders(contentType(path)),
+		"content-length": bytes.byteLength,
+		etag: `"${generation.assets.find((asset) => asset.path === path).digest}"`
+	});
+	response.end(bytes);
+}
+function createWidgetDevelopmentBridgeUrl(profileUrl, bridge) {
+	const base = typeof bridge === "number" ? `http://${LOCAL_BRIDGE_HOST}:${bridge}${OPEN_WIDGET_DEVELOPMENT_PATH}` : bridge;
+	const url = new URL(base);
+	url.searchParams.set("profile", profileUrl);
+	return url.href;
+}
+function createWidgetDevelopmentV1BridgeUrl(bridge) {
+	return typeof bridge === "number" ? `http://${LOCAL_BRIDGE_HOST}:${bridge}/widget-host/desktop/v1/development-sessions` : bridge;
+}
+function createWidgetDevelopmentBridgeRequest({ descriptorUrl, session, expiresAt }) {
+	return {
+		protocol: DEVELOPMENT_PROTOCOL,
+		protocolVersion: 1,
+		sessionId: session.descriptor.sessionId,
+		descriptorUrl,
+		expiresAt
+	};
+}
+async function openViaLocalBridge(profileUrl, bridgeUrl, developmentSession = null, descriptorUrl = null, expiresAt = null) {
+	let origin;
+	try {
+		origin = new URL(profileUrl).origin;
+	} catch {
+		return {
+			ok: false,
+			mode: "bridge",
+			error: createWidgetDevError(/* @__PURE__ */ new Error("Profile URL 无效"), {
+				phase: "bridge",
+				profileUrl
+			})
+		};
+	}
+	const bridgeBases = bridgeUrl ? [bridgeUrl] : LOCAL_BRIDGE_PORTS.map((port) => `http://${LOCAL_BRIDGE_HOST}:${port}${OPEN_WIDGET_DEVELOPMENT_PATH}`);
+	for (const bridgeBase of bridgeBases) {
+		if (developmentSession && descriptorUrl) {
+			const v1Endpoint = createWidgetDevelopmentV1BridgeUrl(bridgeUrl ?? Number(new URL(bridgeBase).port));
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), LOCAL_BRIDGE_TIMEOUT_MS);
+			try {
+				const response = await fetch(v1Endpoint, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${developmentSession.claimToken}`,
+						"Content-Type": "application/json",
+						Origin: origin
+					},
+					body: JSON.stringify(createWidgetDevelopmentBridgeRequest({
+						descriptorUrl,
+						session: developmentSession,
+						expiresAt
+					})),
+					signal: controller.signal
+				});
+				const body = response.ok ? await response.json() : null;
+				if (body?.accepted === true && body.protocolVersion === 1 && body.sessionId === developmentSession.descriptor.sessionId) return {
+					ok: true,
+					mode: "bridge-v1",
+					endpoint: v1Endpoint
+				};
+			} catch {} finally {
+				clearTimeout(timeout);
+			}
+		}
+		const bridge = createWidgetDevelopmentBridgeUrl(profileUrl, bridgeBase);
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), LOCAL_BRIDGE_TIMEOUT_MS);
+		try {
+			const response = await fetch(bridge, {
+				headers: { Origin: origin },
+				signal: controller.signal
+			});
+			if (!response.ok) continue;
+			if ((await response.json())?.opened === true) return {
+				ok: true,
+				mode: "bridge-legacy",
+				endpoint: bridge,
+				warning: "宿主不支持 Widget Development Host v1，已回落 legacy profile。"
+			};
+		} catch {} finally {
+			clearTimeout(timeout);
+		}
+	}
+	return {
+		ok: false,
+		mode: "bridge",
+		error: createWidgetDevError(/* @__PURE__ */ new Error("未发现可用的 loopback host bridge"), {
+			phase: "bridge",
+			profileUrl,
+			endpoints: bridgeBases
+		})
+	};
+}
+async function openHost(url, profileUrl, bridgeUrl, { jsonOutput = false, developmentSession = null, descriptorUrl = null, expiresAt = null } = {}) {
+	const bridgeResult = await openViaLocalBridge(profileUrl, bridgeUrl, developmentSession, descriptorUrl, expiresAt);
+	if (bridgeResult.ok) {
+		if (!jsonOutput) {
+			console.log("已通过本地 host bridge 打开 Widget Development Host。\n");
+			if (bridgeResult.warning) console.warn(bridgeResult.warning);
+		}
+		return bridgeResult;
+	}
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	const args = process.platform === "win32" ? ["", url] : [url];
+	const result = spawnSync(command, args, {
+		encoding: "utf8",
+		shell: process.platform === "win32"
+	});
+	if (result.error || result.status !== 0) {
+		const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status}`;
+		const failure = {
+			ok: false,
+			mode: "deep-link",
+			url,
+			error: createWidgetDevError(new Error(detail), {
+				phase: "open-host",
+				scheme: new URL(url).protocol.slice(0, -1),
+				bridge: bridgeResult.error
+			})
+		};
+		if (!jsonOutput) {
+			console.error(`无法唤起宿主（scheme=${failure.error.context.scheme}）：${detail}`);
+			console.error("请确认生产宿主已安装并注册该 scheme，或复制上方 URL 手动打开。");
+		}
+		return failure;
+	}
+	return {
+		ok: true,
+		mode: "deep-link",
+		url,
+		bridge: bridgeResult.error
+	};
+}
+function projectFingerprint(projectRoot) {
+	const files = [];
+	const visit = (directory) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			if (entry.name === "node_modules" || entry.name === "dist" || entry.name.startsWith(".")) continue;
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) visit(path);
+			else if (entry.isFile()) {
+				const stat = statSync(path);
+				files.push(`${path}:${stat.mtimeMs}:${stat.size}`);
+			}
+		}
+	};
+	visit(projectRoot);
+	return files.sort().join("\n");
+}
+function shouldIgnoreProjectChange(filename, projectRoot = "") {
+	const normalized = String(filename).replaceAll("\\", "/");
+	const rootName = projectRoot.replaceAll("\\", "/").split("/").at(-1);
+	return normalized === "dist" || normalized.startsWith("dist/") || normalized.includes("/dist/") || normalized.includes("node_modules") || normalized.startsWith("_tmp_") || Boolean(rootName && normalized === rootName);
+}
+function createProjectWatcher(projectRoot, onChange) {
+	try {
+		const watcher = watch(projectRoot, { recursive: true }, (_event, filename) => {
+			if (!filename || shouldIgnoreProjectChange(filename, projectRoot)) return;
+			onChange();
+		});
+		return { close: () => watcher.close() };
+	} catch (error) {
+		console.warn(`递归文件监听不可用，改用轮询：${String(error)}`);
+		let previous = projectFingerprint(projectRoot);
+		const timer = setInterval(() => {
+			const current = projectFingerprint(projectRoot);
+			if (current === previous) return;
+			previous = current;
+			onChange();
+		}, 500);
+		return { close: () => clearInterval(timer) };
+	}
+}
+function runBuild(projectRoot, { capture = false } = {}) {
+	return new Promise((resolveBuild, rejectBuild) => {
+		const command = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+		const child = spawn(command, [
+			"--dir",
+			projectRoot,
+			"run",
+			"build"
+		], { stdio: capture ? [
+			"ignore",
+			"pipe",
+			"pipe"
+		] : "inherit" });
+		let stdout = "";
+		let stderr = "";
+		if (capture) {
+			child.stdout.on("data", (chunk) => {
+				stdout += String(chunk);
+			});
+			child.stderr.on("data", (chunk) => {
+				stderr += String(chunk);
+			});
+		}
+		child.once("error", (error) => {
+			error.code = "WIDGET_DEV_BUILD_FAILED";
+			error.stdout = stdout;
+			error.stderr = stderr;
+			rejectBuild(error);
+		});
+		child.once("exit", (code, signal) => {
+			if (code === 0) {
+				resolveBuild({
+					stdout,
+					stderr
+				});
+				return;
+			}
+			const error = /* @__PURE__ */ new Error(`Widget build 失败（exit ${code ?? signal ?? "unknown"}）`);
+			error.code = "WIDGET_DEV_BUILD_FAILED";
+			error.stdout = stdout;
+			error.stderr = stderr;
+			rejectBuild(error);
+		});
+	});
+}
+async function startWidgetDevelopment(projectRoot, options) {
+	const emit = options.emit ?? ((line, error = false) => error ? console.error(line) : console.log(line));
+	if (options.build) await runBuild(projectRoot, { capture: options.json });
+	let successfulGeneration = createDevelopmentGeneration(projectRoot, 0);
+	const retainedGenerations = /* @__PURE__ */ new Map([[successfulGeneration.guestCapability, successfulGeneration]]);
+	const initial = {
+		manifest: successfulGeneration.manifest,
+		entryPath: successfulGeneration.entryPath,
+		digest: successfulGeneration.digest
+	};
+	const state = {
+		phase: "ready",
+		generation: successfulGeneration.number,
+		watch: options.watch,
+		lastBuild: {
+			ok: true,
+			digest: successfulGeneration.digest,
+			assets: successfulGeneration.assets
+		},
+		lastBuildError: null
+	};
+	const eventClients = /* @__PURE__ */ new Map();
+	let eventId = 0;
+	let session;
+	const sendEvent = (type, data) => {
+		const event = {
+			protocolVersion: 1,
+			eventId: String(++eventId),
+			type,
+			data
+		};
+		const frame = `id: ${event.eventId}\nevent: ${type}\ndata: ${JSON.stringify(event)}\n\n`;
+		for (const response of eventClients.keys()) response.write(frame);
+		if (options.json) emit(formatDevelopmentEvent(type, data), type === "generation-failed");
+	};
+	const unauthorized = (response) => json(response, 401, {
+		ok: false,
+		error: {
+			code: "WIDGET_DEV_UNAUTHORIZED",
+			message: "Bearer token required"
+		}
+	});
+	const developmentSnapshot = () => {
+		const origin = `http://127.0.0.1:${server.address().port}`;
+		const development = panelDevelopmentDescriptor(successfulGeneration, `${origin}${V1_PROFILE_PATH}`, `${origin}${V1_STATUS_PATH}`);
+		return {
+			protocolVersion: 1,
+			state: state.phase,
+			sessionId: session.descriptor.sessionId,
+			revision: state.generation + 1,
+			generation: state.generation,
+			updateAvailable: false,
+			descriptor: development.descriptor,
+			presentationRequests: development.presentationRequests,
+			digest: successfulGeneration.digest,
+			assets: successfulGeneration.assets,
+			watch: state.watch,
+			lastBuild: state.lastBuild,
+			lastBuildError: state.lastBuildError
+		};
+	};
+	const generationReadyData = () => {
+		const snapshot = developmentSnapshot();
+		return {
+			generation: snapshot.generation,
+			revision: snapshot.revision,
+			digest: snapshot.digest,
+			assets: snapshot.assets,
+			descriptor: snapshot.descriptor,
+			presentationRequests: snapshot.presentationRequests
+		};
+	};
+	const server = createServer((request, response) => {
+		const url = new URL(request.url ?? "/", "http://127.0.0.1");
+		if (request.method === "OPTIONS") {
+			response.writeHead(405, secureHeaders("text/plain; charset=utf-8")).end();
+			return;
+		}
+		if (url.pathname === DESCRIPTOR_PATH && request.method === "GET") {
+			json(response, 200, session.descriptor);
+			return;
+		}
+		if (url.pathname === CLAIM_PATH && request.method === "POST") {
+			try {
+				json(response, 200, session.claim(bearer(request.headers.authorization)));
+			} catch (error) {
+				json(response, 401, {
+					ok: false,
+					error: {
+						code: "WIDGET_DEV_CLAIM_REJECTED",
+						message: String(error)
+					}
+				});
+			}
+			return;
+		}
+		if (url.pathname.startsWith(V1_ROOT) && !session.authorize(request.headers.authorization)) {
+			unauthorized(response);
+			return;
+		}
+		if (url.pathname === V1_STATUS_PATH && request.method === "GET") {
+			json(response, 200, developmentSnapshot());
+			return;
+		}
+		if (url.pathname === EVENTS_PATH && request.method === "GET") {
+			response.writeHead(200, {
+				...secureHeaders("text/event-stream; charset=utf-8"),
+				connection: "keep-alive"
+			});
+			const initialEvent = {
+				protocolVersion: 1,
+				eventId: String(++eventId),
+				type: "generation-ready",
+				data: generationReadyData()
+			};
+			response.write(`id: ${initialEvent.eventId}\nevent: generation-ready\ndata: ${JSON.stringify(initialEvent)}\n\n`);
+			const heartbeat = setInterval(() => {
+				if (!response.writableEnded) response.write(": heartbeat\n\n");
+			}, options.heartbeatIntervalMs ?? SSE_HEARTBEAT_INTERVAL_MS);
+			eventClients.set(response, heartbeat);
+			const removeEventClient = () => {
+				clearInterval(heartbeat);
+				eventClients.delete(response);
+			};
+			request.once("close", removeEventClient);
+			response.once("close", removeEventClient);
+			return;
+		}
+		if (url.pathname === CONTROL_PATH && request.method === "POST") {
+			let body = "";
+			request.on("data", (chunk) => {
+				body += String(chunk);
+				if (body.length > 16384) request.destroy();
+			});
+			request.on("end", () => {
+				try {
+					const control = JSON.parse(body || "{}");
+					if (control.protocolVersion !== 1 || !["reload", "disconnect"].includes(control.action)) throw new Error("invalid control action");
+					if (control.action === "disconnect") {
+						sendEvent("disconnected", { reason: "host-request" });
+						session.disconnect();
+					} else sendEvent("reload-requested", { generation: state.generation });
+					json(response, 200, {
+						ok: true,
+						protocolVersion: 1,
+						action: control.action
+					});
+				} catch (error) {
+					json(response, 400, {
+						ok: false,
+						error: { message: String(error) }
+					});
+				}
+			});
+			return;
+		}
+		if (url.pathname === V1_PROFILE_PATH && request.method === "GET") {
+			const runId = url.searchParams.get("runId") || "widget-dev-run";
+			const contribution = url.searchParams.get("contribution");
+			const panelId = url.searchParams.get("id");
+			const manifestContribution = successfulGeneration.manifest.widgetConfig.contribution;
+			if (!(!contribution || contribution === manifestContribution.type && (contribution !== "panel" || !panelId || panelId === manifestContribution.id))) {
+				json(response, 404, {
+					ok: false,
+					error: {
+						code: "WIDGET_DEV_PROFILE_NOT_FOUND",
+						message: "No development binding matches the requested contribution",
+						attempted: {
+							contribution,
+							id: panelId
+						}
+					}
+				});
+				return;
+			}
+			const origin = `http://127.0.0.1:${server.address().port}`;
+			const launchUrl = `${origin}${guestGenerationRoot(successfulGeneration)}/launch.html`;
+			json(response, 200, createDevelopmentConfig({
+				manifest: successfulGeneration.manifest,
+				runId,
+				origin,
+				launchUrl,
+				digest: successfulGeneration.digest
+			}));
+			return;
+		}
+		if (url.pathname === PROFILE_PATH) {
+			const runId = url.searchParams.get("runId") || "widget-dev-run";
+			const origin = `http://127.0.0.1:${server.address().port}`;
+			json(response, 200, createDevelopmentConfig({
+				manifest: successfulGeneration.manifest,
+				runId,
+				origin,
+				launchUrl: `${origin}${LAUNCH_PATH}`,
+				digest: successfulGeneration.digest
+			}));
+			return;
+		}
+		if (url.pathname === STATUS_PATH) {
+			json(response, 200, {
+				ok: state.phase === "ready",
+				command: "dev",
+				profile: PROFILE_PATH,
+				launch: LAUNCH_PATH,
+				...state
+			});
+			return;
+		}
+		if (url.pathname === LAUNCH_PATH) {
+			response.writeHead(200, secureHeaders("text/html; charset=utf-8"));
+			response.end(createLaunchHtml(successfulGeneration.entryPath));
+			return;
+		}
+		if (url.pathname.startsWith(`${GUEST_ROOT}/`)) {
+			const parts = url.pathname.slice(`${GUEST_ROOT}/`.length).split("/");
+			const capability = parts.shift();
+			const generation = retainedGenerations.get(capability);
+			if (!generation || parts.length === 0) {
+				response.writeHead(404, secureHeaders("text/plain; charset=utf-8")).end("not found");
+				return;
+			}
+			const guestPath = parts.join("/");
+			if (guestPath === "launch.html") {
+				response.writeHead(200, secureHeaders("text/html; charset=utf-8"));
+				response.end(createLaunchHtml(`${GUEST_ROOT.slice(1)}/${capability}/${generation.entryPath}`));
+				return;
+			}
+			if (guestPath.includes("\\") || guestPath.split("/").includes("..")) {
+				response.writeHead(403, secureHeaders("text/plain; charset=utf-8")).end("forbidden");
+				return;
+			}
+			serveGenerationAsset(generation, guestPath, response);
+			return;
+		}
+		let assetPath;
+		try {
+			assetPath = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+		} catch {
+			response.writeHead(400, secureHeaders("text/plain; charset=utf-8")).end("bad path");
+			return;
+		}
+		if (assetPath.includes("\\") || assetPath.split("/").includes("..")) {
+			response.writeHead(403, secureHeaders("text/plain; charset=utf-8")).end("forbidden");
+			return;
+		}
+		serveGenerationAsset(successfulGeneration, assetPath, response);
+	});
+	await new Promise((resolveListen, rejectListen) => {
+		server.once("error", rejectListen);
+		server.listen(options.port, "127.0.0.1", resolveListen);
+	});
+	const origin = `http://127.0.0.1:${server.address().port}`;
+	session = createWidgetDevelopmentSession({ origin });
+	const profileUrl = `${origin}${PROFILE_PATH}`;
+	const descriptorUrl = `${origin}${DESCRIPTOR_PATH}`;
+	const deepLink = `${options.scheme}://widget-dev?profile=${encodeURIComponent(profileUrl)}`;
+	const openResult = options.open ? await openHost(deepLink, profileUrl, options.bridge, {
+		jsonOutput: options.json,
+		developmentSession: session,
+		descriptorUrl,
+		expiresAt: session.descriptor.expiresAt
+	}) : {
+		ok: false,
+		mode: "manual",
+		reason: "not_requested",
+		url: deepLink
+	};
+	const startup = {
+		ok: true,
+		command: "dev",
+		protocolVersion: 1,
+		sessionId: session.descriptor.sessionId,
+		projectRoot,
+		origin,
+		descriptorUrl,
+		profileUrl,
+		statusUrl: `${origin}${STATUS_PATH}`,
+		hostUrl: deepLink,
+		digest: successfulGeneration.digest,
+		assets: successfulGeneration.assets,
+		watch: options.watch,
+		open: openResult
+	};
+	if (options.json) emit(formatDevelopmentEvent("session-ready", startup));
+	else {
+		emit(`\nWidget Development Host 已启动：${relative(repoRoot, projectRoot) || projectRoot}`);
+		emit(`Descriptor: ${descriptorUrl}`);
+		emit(`Profile:    ${profileUrl}`);
+		emit(`Status:     ${startup.statusUrl}`);
+		emit(`Host:       ${deepLink}`);
+		emit("\n将生产宿主用于 Widget 开发：复制 Host URL，或加 --open 自动唤起。\n");
+	}
+	let timer;
+	let building = false;
+	let pending = false;
+	const rebuild = async () => {
+		if (building) {
+			pending = true;
+			return;
+		}
+		building = true;
+		try {
+			const build = await runBuild(projectRoot, { capture: options.json });
+			const candidate = createDevelopmentGeneration(projectRoot, successfulGeneration.number + 1);
+			successfulGeneration = candidate;
+			retainedGenerations.set(candidate.guestCapability, candidate);
+			while (retainedGenerations.size > RETAINED_GENERATIONS) retainedGenerations.delete(retainedGenerations.keys().next().value);
+			state.generation = candidate.number;
+			state.lastBuild = {
+				ok: true,
+				digest: candidate.digest,
+				assets: candidate.assets,
+				stdout: build.stdout,
+				stderr: build.stderr
+			};
+			state.lastBuildError = null;
+			sendEvent("generation-ready", generationReadyData());
+			if (!options.json) emit("Widget 已重新构建；宿主可通过事件或 reload 获取新 generation。");
+		} catch (error) {
+			const redactProjectRoot = (value) => String(value ?? "").replaceAll(projectRoot, "<project>");
+			state.lastBuildError = createWidgetDevError(error, {
+				phase: "watch-build",
+				stdout: redactProjectRoot(error?.stdout),
+				stderr: redactProjectRoot(error?.stderr)
+			});
+			sendEvent("generation-failed", {
+				generation: successfulGeneration.number,
+				retainedDigest: successfulGeneration.digest,
+				error: state.lastBuildError
+			});
+			if (!options.json) emit(String(error), true);
+		} finally {
+			building = false;
+			if (pending) {
+				pending = false;
+				rebuild();
+			}
+		}
+	};
+	const watcher = options.watch ? createProjectWatcher(projectRoot, () => {
+		clearTimeout(timer);
+		timer = setTimeout(() => void rebuild(), 150);
+	}) : null;
+	let closed = false;
+	const close = (reason = "cli-stop") => {
+		if (closed) return;
+		closed = true;
+		state.phase = "stopping";
+		sendEvent("session-stopping", { reason });
+		session.disconnect();
+		clearTimeout(timer);
+		watcher?.close();
+		for (const [response, heartbeat] of eventClients) {
+			clearInterval(heartbeat);
+			response.end();
+		}
+		eventClients.clear();
+		server.close();
+	};
+	if (options.registerSignals !== false) {
+		process.once("SIGINT", () => {
+			close("signal");
+			process.exit(0);
+		});
+		process.once("SIGTERM", () => {
+			close("signal");
+			process.exit(0);
+		});
+	}
+	return {
+		server,
+		close,
+		rebuild,
+		initial,
+		startup,
+		state,
+		session
+	};
+}
+function emitCliEnvelope(type, data, error = false) {
+	const line = formatDevelopmentEvent(type, data);
+	if (error) console.error(line);
+	else console.log(line);
+}
+async function runWidgetDevelopmentCli(argv = process.argv.slice(2)) {
+	try {
+		const options = parseArgs(argv);
+		if (options.help) {
+			console.log(usage$1());
+			return 0;
+		}
+		const [projectRoot] = resolveWidgetProjects(options.project);
+		const check = await checkWidgetProject(projectRoot, { requireBuiltEntry: false });
+		if (!check.ok) {
+			if (options.json) emitCliEnvelope("error", {
+				ok: false,
+				command: "dev",
+				error: createWidgetDevError(/* @__PURE__ */ new Error("Widget Dev 启动前 L0 check 失败"), {
+					phase: "validate",
+					projectRoot,
+					errors: check.errors
+				})
+			});
+			else {
+				console.error("Widget Dev 启动前 L0 check 失败：");
+				check.errors.forEach((error) => {
+					console.error(`  - ${error}`);
+				});
+			}
+			return 1;
+		}
+		await startWidgetDevelopment(projectRoot, options);
+		return 0;
+	} catch (error) {
+		if (argv.includes("--json")) emitCliEnvelope("error", {
+			ok: false,
+			command: "dev",
+			error: createWidgetDevError(error, { input: argv[0] ?? null })
+		});
+		else console.error(`${String(error)}\n\n${usage$1()}`);
+		return 1;
+	}
+}
+//#endregion
+//#region src/manifest-lint.mjs
+/**
+* 作者清单（VS Code 风格 `contributes` 清单）的本地静态检查。
+*
+* `@dp-bohrium/widget-contracts` 的 host schema 只在 `compileAuthorManifest` 之后生效，
+* 而编译只保留宿主运行时需要的字段：作者的 `version`、`displayName` 和未知顶层键会被
+* 静默丢弃，于是"清单写错但 check 全绿"。这里只补下游永远看不到的作者侧约束，报错文案
+* 直接指向作者填的字段名。
+*
+* 边界：`contributes` / `capabilities` / `runtime` / `samples` / `description` 的结构
+* 在编译后仍由 host schema 校验，这里不重复实现，避免与
+* `widget-plugin-manifest.schema.json` 产生第二份真相。
+*/
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+const AUTHOR_MANIFEST_KEYS = Object.freeze([
+	"$schema",
+	"name",
+	"version",
+	"displayName",
+	"description",
+	"entry",
+	"activationEvents",
+	"contributes",
+	"capabilities",
+	"runtime",
+	"samples"
+]);
+const AUTHOR_MANIFEST_SCHEMA_ID = "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json";
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/** 有 `contributes` 就按作者清单处理；这也是 `compileAuthorManifest` 的输入前提。 */
+function looksLikeAuthorManifest(value) {
+	return isPlainObject(value) && "contributes" in value;
+}
+function suggestKey(key) {
+	const lower = key.toLowerCase();
+	const candidate = AUTHOR_MANIFEST_KEYS.find((allowed) => {
+		const normalized = allowed.toLowerCase();
+		return normalized === lower || normalized.startsWith(lower) || lower.startsWith(normalized);
+	});
+	return candidate && candidate !== key ? candidate : void 0;
+}
+/**
+* @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+*   `errors` 是作者必须修的清单错误；`warnings` 是可继续执行但值得提示的问题。
+*/
+function lintAuthorManifest(manifest, options = {}) {
+	const fileExists = options.fileExists;
+	const errors = [];
+	const warnings = [];
+	if (!isPlainObject(manifest)) return {
+		ok: false,
+		errors: ["manifest.json 必须是 JSON 对象"],
+		warnings
+	};
+	for (const key of Object.keys(manifest)) {
+		if (AUTHOR_MANIFEST_KEYS.includes(key)) continue;
+		const suggestion = suggestKey(key);
+		errors.push(`manifest.json 不允许多余字段 "${key}"${suggestion ? `，是否想写 "${suggestion}"？` : ""}（additionalProperties=false）`);
+	}
+	if (typeof manifest.name !== "string" || manifest.name.length === 0) errors.push("manifest.json 缺少必填字段 \"name\"（非空字符串）");
+	else if (manifest.name.length > 128) errors.push("manifest.json 的 \"name\" 超过 128 个字符");
+	if (manifest.version === void 0) errors.push("manifest.json 缺少必填字段 \"version\"（例如 \"0.1.0\"）");
+	else if (typeof manifest.version !== "string" || !VERSION_PATTERN.test(manifest.version)) errors.push(`manifest.json 的 "version" 必须是 semver，当前是 ${JSON.stringify(manifest.version)}`);
+	if (manifest.displayName !== void 0 && typeof manifest.displayName !== "string") errors.push(`manifest.json 的 "displayName" 必须是字符串，当前是 ${JSON.stringify(manifest.displayName)}`);
+	else if (typeof manifest.displayName === "string" && manifest.displayName.length > 128) errors.push("manifest.json 的 \"displayName\" 超过 128 个字符");
+	if (manifest.entry !== void 0) {
+		if (typeof manifest.entry !== "string" || manifest.entry.length === 0) errors.push("manifest.json 的 \"entry\" 必须是非空字符串");
+		else if (fileExists && !fileExists(manifest.entry)) warnings.push(`manifest.json 的 "entry" 指向的源文件不存在：${manifest.entry}（CLI 打包使用构建后的入口，此处仅提示）`);
+	}
+	if (isPlainObject(manifest.widgetConfig)) warnings.push("manifest.json 同时包含作者字段（contributes）和宿主字段（widgetConfig）；打包时以编译结果为准，建议只保留作者清单");
+	const contribution = manifest.contributes?.widget;
+	if (contribution?.type === "panel" && contribution.id === "workspace-files") {
+		const files = manifest.capabilities?.files;
+		const missing = [
+			"list",
+			"metadata",
+			"read"
+		].filter((capability) => files?.[capability] !== true);
+		if (missing.length > 0) errors.push(`contributes.widget.id 为 "workspace-files" 时必须申请 capabilities.files.${missing.join("、capabilities.files.")}；否则 Host 文件面板无法加载`);
+	}
+	if (errors.length > 0) errors.push(`作者清单结构以 ${AUTHOR_MANIFEST_SCHEMA_ID} 为准；执行 bohr-widget schema 可查看本地 Schema 路径。`);
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+//#endregion
+//#region src/templates.mjs
+function reactSource({ reportSize = false } = {}) {
+	return `import { createRoot } from "react-dom/client";
+import type { WidgetContext } from "@dp-bohrium/widget-sdk";
+import type { RenderRequest } from "@dp-bohrium/widget-contracts";
+
+function WidgetView({ request }: { request?: RenderRequest }) {
+  const data = request?.content ?? { state: "等待 Host 提供数据" };
+  return (
+    <main style={{ fontFamily: "system-ui", padding: 20 }}>
+      <h1>Widget 面板</h1>
+      <pre style={{ whiteSpace: "pre-wrap" }}>
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </main>
+  );
+}
+
+function activate(context: WidgetContext) {
+  const host = document.createElement("main");
+  document.body.replaceChildren(host);
+  const root = createRoot(host);
+  let renderRequest: RenderRequest | undefined;${reportSize ? "\n  let resized = false;" : ""}
+  const render = () => root.render(<WidgetView request={renderRequest} />);
+  render();
+  context.render((request) => {
+    renderRequest = request;
+    render();${reportSize ? `
+    if (!resized) {
+      context.resize(640, 360);
+      resized = true;
+    }` : ""}
+  });
+  context.subscriptions.add(() => root.unmount());
+}
+
+export { activate };
+`;
+}
+function hostSource({ sourceFile }) {
+	return `import { runWidgetHost } from "@dp-bohrium/widget-sdk";
+import * as widget from "./${sourceFile.split("/").at(-1)}";
+
+runWidgetHost(widget);
+`;
+}
+const TEMPLATES = Object.freeze({
+	panel: {
+		manifest: ({ name, panelId = name, ui = "vanilla" }) => ({
+			$schema: "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+			name,
+			version: "0.1.0",
+			displayName: name,
+			entry: ui === "react" ? "src/widget.tsx" : "src/widget.ts",
+			activationEvents: ["session.start"],
+			contributes: { widget: {
+				type: "panel",
+				id: panelId,
+				surfaces: ["workspace"]
+			} },
+			...panelId === "workspace-files" ? { capabilities: { files: {
+				list: true,
+				metadata: true,
+				read: true
+			} } } : {},
+			samples: [{
+				id: "default",
+				title: "默认样例",
+				request: "samples/default.json"
+			}]
+		}),
+		source: `import type { WidgetContext } from "@dp-bohrium/widget-sdk";
+
+function activate(context: WidgetContext) {
+  const root = document.createElement("main");
+  root.textContent = "等待 Host 提供面板数据";
+  document.body.replaceChildren(root);
+  context.render((request) => {
+    const content = request.content;
+    root.textContent = JSON.stringify(
+      "data" in content ? content.data : content,
+      null,
+      2,
+    );
+  });
+}
+
+export { activate };
+`,
+		reactSource,
+		hostSource,
+		sample: ({ name, panelId = name }) => ({
+			schemaVersion: 1,
+			requestId: `${name}-default`,
+			instanceId: name,
+			revision: 1,
+			contribution: "panel",
+			state: "complete",
+			content: {
+				contribution: "panel",
+				id: panelId,
+				title: name,
+				data: panelId === "workspace-files" ? { root: {
+					id: "workspace-root",
+					kind: "directory",
+					name: "workspace"
+				} } : { status: "ready" }
+			},
+			context: {
+				locale: "zh-CN",
+				theme: {
+					mode: "light",
+					tokens: {
+						background: "#fff",
+						foreground: "#111",
+						muted: "#eee",
+						mutedForeground: "#666",
+						border: "#ddd",
+						primary: "#06c",
+						danger: "#c00"
+					}
+				},
+				viewport: {
+					width: 640,
+					height: 360
+				},
+				capabilities: panelId === "workspace-files" ? [
+					{
+						name: "files.list",
+						limits: {
+							pageSize: 100,
+							callsPerMinute: 60
+						}
+					},
+					{
+						name: "files.metadata",
+						limits: { callsPerMinute: 60 }
+					},
+					{
+						name: "files.read",
+						limits: {
+							bytesPerRequest: 65536,
+							bytesPerRun: 262144,
+							callsPerMinute: 60
+						}
+					}
+				] : [],
+				correlationId: `${name}-default`
+			}
+		})
+	},
+	"file-preview": {
+		manifest: ({ name, ui = "vanilla" }) => ({
+			$schema: "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+			name,
+			version: "0.1.0",
+			displayName: name,
+			entry: ui === "react" ? "src/widget.tsx" : "src/widget.ts",
+			activationEvents: ["workspace-file-opened"],
+			contributes: { widget: {
+				type: "file-preview",
+				extensions: ["txt"]
+			} },
+			samples: [{
+				id: "default",
+				title: "默认样例",
+				request: "samples/default.json"
+			}]
+		}),
+		source: `import type { WidgetContext } from "@dp-bohrium/widget-sdk";
+
+function activate(context: WidgetContext) {
+  const root = document.createElement("main");
+  document.body.replaceChildren(root);
+  let resized = false;
+  context.render((request) => {
+    root.textContent = JSON.stringify(request.content ?? {}, null, 2);
+    if (!resized) {
+      context.resize(640, 360);
+      resized = true;
+    }
+  });
+}
+
+export { activate };
+`,
+		reactSource: (options) => reactSource({
+			...options,
+			reportSize: true
+		}),
+		hostSource,
+		sample: () => ({
+			schemaVersion: 1,
+			requestId: "sample-file-preview",
+			instanceId: "sample-file-preview",
+			revision: 1,
+			contribution: "file-preview",
+			state: "complete",
+			content: {
+				contribution: "file-preview",
+				file: {
+					id: "sample",
+					name: "README.txt",
+					extension: "txt",
+					kind: "file"
+				},
+				preview: { format: "text" }
+			},
+			context: {
+				locale: "en-US",
+				theme: {
+					mode: "light",
+					tokens: {
+						background: "#fff",
+						foreground: "#111",
+						muted: "#eee",
+						mutedForeground: "#666",
+						border: "#ddd",
+						primary: "#06c",
+						danger: "#c00"
+					}
+				},
+				viewport: {
+					width: 640,
+					height: 360
+				},
+				capabilities: [],
+				correlationId: "sample-file-preview"
+			}
+		})
+	}
+});
+//#endregion
+//#region src/cli.mjs
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+const sdkPackage = require("@dp-bohrium/widget-sdk/package.json");
+const contractsPackage = require("@dp-bohrium/widget-contracts/package.json");
+const COMMANDS = [
+	"create",
+	"check",
+	"validate",
+	"build",
+	"dev",
+	"pack",
+	"doctor",
+	"schema",
+	"migrate",
+	"version",
+	"help"
+];
+function usage() {
+	return `bohr-widget — Bohrium Widget 插件工具
+
+用法：
+  bohr-widget create <目录> [--template panel|file-preview] [--ui vanilla|react] [--panel-id <id>]
+  bohr-widget check <目录|manifest.json|all> [--json]
+  bohr-widget validate <目录|manifest.json|all> [--json]
+  bohr-widget build <目录> [--json]
+  bohr-widget dev <目录> [--open] [--watch] [--no-build] [--json] [--port <端口>] [--scheme <scheme>] [--bridge <url>]
+  bohr-widget pack <目录> [--out <zip>] [--include-preview-fixtures] [--no-build] [--json]
+  bohr-widget doctor [目录] [--json]
+  bohr-widget schema
+  bohr-widget migrate dsh audit <plugin-dir> [--json]
+  bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [--json]
+  bohr-widget version [--json]
+  bohr-widget help | -h | --help
+
+--json 只输出一个 JSON 文档；check all --json 输出 checked/passed/failed/results[] 汇总。
+`;
+}
+function parseOptions(argv) {
+	const positional = [];
+	const options = {
+		json: false,
+		template: "panel",
+		ui: "vanilla",
+		includePreviewFixtures: false,
+		output: void 0,
+		open: false,
+		watch: false,
+		build: true,
+		port: 4300,
+		scheme: "widget-host",
+		bridge: null,
+		panelId: void 0
+	};
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--json") options.json = true;
+		else if (argument === "--include-preview-fixtures") options.includePreviewFixtures = true;
+		else if (argument === "--template") {
+			options.template = argv[++index];
+			if (!options.template) throw new Error("--template 需要模板名");
+		} else if (argument === "--ui") {
+			options.ui = argv[++index];
+			if (!options.ui) throw new Error("--ui 需要 vanilla 或 react");
+		} else if (argument === "--panel-id") {
+			options.panelId = argv[++index];
+			if (!options.panelId) throw new Error("--panel-id 需要稳定的 Panel id");
+		} else if (argument === "--out") {
+			options.output = argv[++index];
+			if (!options.output) throw new Error("--out 需要输出路径");
+		} else if (argument === "--open") options.open = true;
+		else if (argument === "--watch") options.watch = true;
+		else if (argument === "--no-build") options.build = false;
+		else if (argument === "--port") options.port = Number(argv[++index]);
+		else if (argument === "--scheme") options.scheme = argv[++index];
+		else if (argument === "--bridge") options.bridge = argv[++index];
+		else if (argument.startsWith("-")) throw new Error(`未知选项：${argument}`);
+		else positional.push(argument);
+	}
+	return {
+		positional,
+		options
+	};
+}
+function printResult(result, json) {
+	if (json) console.log(JSON.stringify(result, null, 2));
+	else {
+		for (const check of result.checks ?? []) console.log(`${check.ok ? "✓" : "✗"} ${check.name}`);
+		for (const error of result.errors ?? []) console.error(`错误：${error}`);
+		console.log(result.ok ? "校验通过" : "校验失败");
+	}
+}
+function structuredError({ code, message, context = {}, recovery }) {
+	return {
+		code,
+		message,
+		context,
+		recovery
+	};
+}
+function commandRecovery(command, error) {
+	if (!COMMANDS.includes(command)) return "命令不存在或拼写有误：执行 bohr-widget help 查看支持的命令与参数。";
+	if (command === "create") return "确认目标目录不存在，且 --template 与 --ui 取值合法后重新执行 create。";
+	if (command === "build") {
+		if (error?.cliCode === "WIDGET_CLI_BUILD_UNRESOLVED_IMPORT") return "安装或修正 error.message 中的依赖，并确认 bundler 已把浏览器运行时依赖打进 dist/widget.js 后重新执行 build。";
+		return error?.code === 127 ? "工程缺少构建依赖：先在工程目录执行包管理器 install，再重新执行 build。" : "读取 error.stdout / error.stderr 定位构建错误，修复工程后重新执行 build。";
+	}
+	if (command === "pack") return "先执行 bohr-widget check <工程目录>，修复 manifest、entry、sample 或 fixtures 后重新打包。";
+	if (command === "check" || command === "validate") return "根据 errors 修复 Manifest、entry、sample 或 fixtures 后重新校验。";
+	return "根据错误上下文修复后重试；不确定时保留 command、error 和上下文交给上层 CLI。";
+}
+/** 命令名要进 error.code，必须净化成标识符片段（unknown-cmd → UNKNOWN_CMD）。 */
+function commandCode(command) {
+	return String(command ?? "").replace(/[^A-Za-z0-9]+/gu, "_").replace(/^_+|_+$/gu, "").toUpperCase() || "UNKNOWN";
+}
+function commandError(command, error, context = {}) {
+	return structuredError({
+		code: typeof error?.cliCode === "string" ? error.cliCode : typeof error?.code === "string" && error.code.startsWith("WIDGET_") ? error.code : `WIDGET_CLI_${commandCode(command)}_FAILED`,
+		message: error instanceof Error ? error.message : String(error),
+		context,
+		recovery: commandRecovery(command, error)
+	});
+}
+/**
+* 目录名 → Widget name（同时用作 panel id）。中文或纯符号目录名必须回退成合法标识符，
+* 不能净化成 "----" 这类空壳，否则 manifest 的 name/id 会直接违反作者清单契约。
+*/
+function deriveWidgetName(directoryName) {
+	const slug = String(directoryName ?? "").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+	if (slug.length === 0) return `widget-${createHash("sha256").update(String(directoryName ?? "")).digest("hex").slice(0, 8)}`;
+	return slug.slice(0, 64).replace(/-+$/gu, "");
+}
+async function commandCreate(directory, options) {
+	if (!directory) throw new Error("create 需要目标目录");
+	const template = TEMPLATES[options.template];
+	if (!template) throw new Error(`未知模板：${options.template}`);
+	if (!["vanilla", "react"].includes(options.ui)) throw new Error(`未知 UI 模式：${options.ui}，可选 vanilla 或 react`);
+	if (options.panelId && options.template !== "panel") throw new Error("--panel-id 只适用于 --template panel");
+	if (options.panelId && !/^[A-Za-z0-9_.:-]{1,128}$/u.test(options.panelId)) throw new Error("--panel-id 必须为 1-128 位，只能包含字母、数字、下划线、点、冒号和连字符");
+	const root = resolve(directory);
+	if (existsSync(root)) throw new Error(`目标目录已存在：${root}`);
+	const directoryName = basename(root);
+	const name = deriveWidgetName(directoryName);
+	const panelId = options.template === "panel" ? options.panelId ?? name : void 0;
+	const templateContext = {
+		name,
+		panelId,
+		sdkVersion: sdkPackage.version,
+		ui: options.ui
+	};
+	const manifest = template.manifest(templateContext);
+	const sample = template.sample(templateContext);
+	await mkdir(join(root, "src"), { recursive: true });
+	await mkdir(join(root, "samples"), { recursive: true });
+	await mkdir(join(root, "scripts"), { recursive: true });
+	await writeFile(join(root, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+	await writeFile(join(root, "samples/default.json"), `${JSON.stringify(sample, null, 2)}\n`);
+	const sourceFile = options.ui === "react" ? "src/widget.tsx" : "src/widget.ts";
+	const hostFile = "src/widget-host.ts";
+	const source = options.ui === "react" && template.reactSource ? template.reactSource({ name }) : typeof template.source === "function" ? template.source({
+		ui: options.ui,
+		name
+	}) : template.source;
+	await writeFile(join(root, sourceFile), source);
+	await writeFile(join(root, hostFile), template.hostSource({ sourceFile }));
+	await writeFile(join(root, "scripts/rename-iife.mjs"), `import { rename } from "node:fs/promises";\n\nawait rename("dist/widget.iife.js", "dist/widget.js");\n`);
+	await writeFile(join(root, ".gitignore"), "node_modules/\ndist/\n.artifacts/\n*.zip\n");
+	await writeFile(join(root, "README.md"), `# ${name}
+
+Bohrium Widget ${options.template} 插件工程（${options.ui}）。
+
+\`\`\`bash
+pnpm install
+pnpm build
+bohr-widget check .
+bohr-widget pack .
+\`\`\`
+
+- 源码入口：${sourceFile}，由 ${hostFile} 调用 SDK 的 runWidgetHost 启动
+- manifest.json 是作者清单，打包时由 CLI 编译为宿主清单
+- 构建产物 dist/widget.js 不提交到版本库
+`);
+	await writeFile(join(root, "tsconfig.json"), `${JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			module: "ESNext",
+			moduleResolution: "bundler",
+			lib: ["ES2022", "DOM"],
+			strict: true,
+			noEmit: true,
+			allowImportingTsExtensions: true,
+			skipLibCheck: true,
+			...options.ui === "react" ? { jsx: "react-jsx" } : {}
+		},
+		include: ["src"]
+	}, null, 2)}\n`);
+	await writeFile(join(root, "tsdown.config.ts"), `import { defineConfig } from "tsdown";\n\nexport default defineConfig({\n  entry: { widget: "${hostFile}" },\n  format: ["iife"],\n  platform: "browser",\n  target: "es2022",\n  ${options.ui === "react" ? "jsx: \"automatic\"," : ""}\n  dts: false,\n  outDir: "dist",\n  outExtensions: () => ({ js: ".js" }),\n  clean: true,\n  sourcemap: false,\n  minify: true,\n  deps: {\n    alwaysBundle: ["@dp-bohrium/widget-sdk"${options.ui === "react" ? ", \"react\", \"react-dom\", \"react-dom/client\", \"react/jsx-runtime\"" : ""}],\n    onlyBundle: false,\n  },\n});\n`);
+	await writeFile(join(root, "package.json"), `${JSON.stringify({
+		name: `@dp-bohrium/widget-example-${name}`,
+		private: true,
+		type: "module",
+		scripts: { build: "tsc --noEmit && tsdown && node scripts/rename-iife.mjs" },
+		dependencies: {
+			"@dp-bohrium/widget-sdk": sdkPackage.version,
+			...options.ui === "react" ? {
+				react: "^19.0.0",
+				"react-dom": "^19.0.0"
+			} : {}
+		},
+		devDependencies: {
+			"@dp-bohrium/widget-contracts": contractsPackage.version,
+			tsdown: "0.22.14",
+			typescript: "5.9.3",
+			...options.ui === "react" ? {
+				"@types/react": "^19.0.0",
+				"@types/react-dom": "^19.0.0"
+			} : {}
+		}
+	}, null, 2)}\n`);
+	const warnings = [];
+	if (name !== directoryName) warnings.push(`目录名 "${directoryName}" 不是合法标识符，manifest 的 name 已取 "${name}"；需要其他取值请直接编辑 manifest.json。`);
+	if (options.template === "panel" && panelId !== "workspace-files") warnings.push(`Panel id "${panelId}" 需要 Host 预先注册并绑定；工作区文件面板请使用 --panel-id workspace-files。`);
+	const result = {
+		ok: true,
+		command: "create",
+		projectRoot: root,
+		name,
+		template: options.template,
+		ui: options.ui,
+		entry: sourceFile,
+		...panelId ? { panelId } : {},
+		manifestPath: join(root, "manifest.json"),
+		packagePath: join(root, "package.json"),
+		...warnings.length === 0 ? {} : { warnings }
+	};
+	if (options.json) console.log(JSON.stringify(result, null, 2));
+	else {
+		console.log(`已创建 Widget 工程：${root}（manifest name: ${name}）`);
+		for (const warning of warnings) console.warn(`提示：${warning}`);
+		console.log("下一步：pnpm install && pnpm build && bohr-widget check .");
+	}
+	return result;
+}
+function projectLabel(projectRoot) {
+	const relativePath = relative(process.cwd(), projectRoot);
+	return !relativePath || relativePath.startsWith("..") ? projectRoot : relativePath;
+}
+/**
+* `check all` 以当前工作目录为根。发布形态下 CLI 位于消费者的 node_modules 内，
+* 用包自身位置反推仓库根只会得到空集合（旧行为：静默 exit 0，零覆盖）。
+*/
+function resolveProjectSet(input) {
+	if (input !== "all") return resolveWidgetProjects(input);
+	const base = resolve(process.cwd());
+	const catalogued = resolveWidgetProjects("all", base);
+	if (catalogued.length > 0) return catalogued;
+	return existsSync(join(base, "manifest.json")) ? [base] : [];
+}
+/** 作者清单里下游校验看不到的字段，先在这里给出精确错误。 */
+function lintProjectManifest(projectRoot) {
+	const manifestPath = join(projectRoot, "manifest.json");
+	if (!existsSync(manifestPath)) return null;
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch {
+		return null;
+	}
+	if (!looksLikeAuthorManifest(manifest)) return null;
+	return lintAuthorManifest(manifest, { fileExists: (declared) => existsSync(join(projectRoot, declared)) });
+}
+function fixtureContentBytes(value) {
+	if (!value || typeof value.content !== "string") return null;
+	try {
+		return value.encoding === "base64" ? Buffer.from(value.content, "base64").byteLength : Buffer.byteLength(value.content, "utf8");
+	} catch {
+		return null;
+	}
+}
+/** CLI 在共享 L0 契约之外补充当前 Host 与预览 fixture 的可运行性检查。 */
+function applyCliProjectPolicies(result) {
+	const widgetConfig = result.manifest?.widgetConfig;
+	if (!widgetConfig?.contribution) return result;
+	const contribution = widgetConfig.contribution;
+	const files = widgetConfig.requestedCapabilities?.files;
+	if (contribution.type === "panel" && contribution.id === "workspace-files") {
+		const missing = [
+			"list",
+			"metadata",
+			"read"
+		].filter((capability) => files?.[capability] !== true);
+		const ok = missing.length === 0;
+		result.checks.push({
+			name: "workspace-files 申请完整只读文件能力",
+			ok
+		});
+		if (!ok) result.errors.push(`workspace-files 缺少 capabilities.files.${missing.join("、capabilities.files.")}；Host 无法加载文件面板`);
+	}
+	if (result.fixtures && files?.read) {
+		const listedFiles = /* @__PURE__ */ new Map();
+		for (const listing of Object.values(result.fixtures.files?.list ?? {})) for (const item of listing?.items ?? []) if (item?.kind === "file" && typeof item.id === "string") listedFiles.set(item.id, item);
+		const readable = result.fixtures.files?.read ?? {};
+		const metadata = result.fixtures.files?.metadata ?? {};
+		const missing = [...listedFiles.keys()].filter((id) => readable[id] === void 0);
+		const sizeMismatches = [];
+		for (const [id, item] of listedFiles) {
+			const bytes = fixtureContentBytes(readable[id]);
+			if (bytes === null) continue;
+			for (const [source, size] of [["files.list", item.size], ["files.metadata", metadata[id]?.size]]) if (typeof size === "number" && size !== bytes) sizeMismatches.push(`${id} (${source}=${size}, read=${bytes})`);
+		}
+		const ok = missing.length === 0 && sizeMismatches.length === 0;
+		result.checks.push({
+			name: "fixtures 覆盖目录清单中的可点击文件",
+			ok,
+			detail: `${listedFiles.size} listed files`
+		});
+		if (missing.length > 0) result.errors.push(`preview/fixtures.json: files.read 缺少 files.list 中的文件：${missing.join(", ")}`);
+		if (sizeMismatches.length > 0) result.errors.push(`preview/fixtures.json: 文件大小与 read 内容字节数不一致：${sizeMismatches.join(", ")}`);
+	}
+	result.ok = result.errors.length === 0 && result.checks.every((check) => check.ok);
+	return result;
+}
+async function commandCheck(input, options, commandName = "check") {
+	if (!input) throw new Error("check 需要工程目录、manifest.json 或 all");
+	const base = resolve(process.cwd());
+	const projects = resolveProjectSet(input);
+	if (projects.length === 0) {
+		const result = {
+			ok: false,
+			command: commandName,
+			checked: 0,
+			base,
+			checks: [],
+			errors: [`${base} 下没有找到 Widget 工程（已查找 examples/sdk、examples/integration 和当前目录的 manifest.json）`],
+			error: structuredError({
+				code: "WIDGET_CLI_NO_WIDGET_PROJECT",
+				message: "check all 没有匹配到任何 Widget 工程，未校验任何文件。",
+				context: {
+					command: commandName,
+					input,
+					base
+				},
+				recovery: "在 Widget 工程目录内执行 bohr-widget check .；或在包含 examples/sdk|examples/integration 的工作区根目录执行 check all。"
+			})
+		};
+		if (options.json) console.log(JSON.stringify(result, null, 2));
+		else {
+			console.error(`错误：${result.errors[0]}`);
+			console.error(`恢复建议：${result.error.recovery}`);
+		}
+		process.exitCode = 1;
+		return result;
+	}
+	const results = [];
+	let passed = true;
+	for (const project of projects) {
+		const label = projectLabel(project);
+		const lint = lintProjectManifest(project);
+		let result;
+		if (lint && !lint.ok) result = {
+			ok: false,
+			label,
+			lintErrors: lint.errors,
+			checks: [{
+				name: "作者清单静态检查",
+				ok: false
+			}],
+			errors: lint.errors,
+			warnings: lint.warnings,
+			manifest: null,
+			sourceManifest: null,
+			manifestKind: "author",
+			projectRoot: project
+		};
+		else {
+			result = applyCliProjectPolicies(await checkWidgetProject(project, { label }));
+			if (lint?.warnings.length) result.warnings = [...lint.warnings, ...result.warnings ?? []];
+			if (!result.ok && result.manifestKind === "host" && looksLikeAuthorManifest(result.sourceManifest)) result.errors = [...result.errors, "manifest.json 含作者字段 contributes，却被按宿主清单校验：请补齐 version，并确认 contributes.widget.type 为 panel 或 file-preview。"];
+		}
+		results.push(result);
+		passed &&= result.ok;
+		if (input !== "all") printResult(options.json ? {
+			command: commandName,
+			...result,
+			...result.ok ? {} : { error: structuredError({
+				code: result.lintErrors ? "WIDGET_CLI_MANIFEST_INVALID" : "WIDGET_CLI_VALIDATION_FAILED",
+				message: "Widget 工程校验失败。",
+				context: {
+					projectRoot: result.projectRoot,
+					label
+				},
+				recovery: commandRecovery(commandName)
+			}) }
+		} : result, options.json);
+	}
+	if (input === "all") {
+		const failed = results.filter((result) => !result.ok);
+		const summary = {
+			ok: passed,
+			command: commandName,
+			base,
+			checked: results.length,
+			passed: results.length - failed.length,
+			failed: failed.length,
+			results: results.map((result) => ({
+				label: result.label,
+				projectRoot: result.projectRoot,
+				ok: result.ok,
+				checks: result.checks,
+				errors: result.errors,
+				...result.warnings?.length ? { warnings: result.warnings } : {}
+			})),
+			...passed ? {} : { error: structuredError({
+				code: "WIDGET_CLI_VALIDATION_FAILED",
+				message: "部分 Widget 工程校验失败。",
+				context: {
+					base,
+					failedProjects: failed.map((result) => result.projectRoot)
+				},
+				recovery: commandRecovery(commandName)
+			}) }
+		};
+		if (options.json) console.log(JSON.stringify(summary, null, 2));
+		else {
+			for (const result of results) printResult(result, false);
+			console.log(`\n已校验 ${summary.checked} 个工程：${summary.passed} 通过 / ${summary.failed} 失败`);
+		}
+	}
+	if (!passed) process.exitCode = 1;
+	return input === "all" ? void 0 : results[0];
+}
+const LOCKFILE_MANAGERS = [
+	["pnpm-lock.yaml", "pnpm"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"],
+	["npm-shrinkwrap.json", "npm"]
+];
+/** 用哪个包管理器跑工程构建：packageManager 优先，其次 lockfile，最后回退 npm。 */
+function detectPackageManager(root, projectPackage) {
+	const declaredManager = String(projectPackage.packageManager ?? "").split("@")[0];
+	if ([
+		"pnpm",
+		"yarn",
+		"npm"
+	].includes(declaredManager)) return declaredManager;
+	for (const [lockfile, manager] of LOCKFILE_MANAGERS) if (existsSync(join(root, lockfile))) return manager;
+	return "npm";
+}
+function firstFailureLine(output) {
+	const lines = String(output ?? "").split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
+	const line = lines.find((item) => !/^(?:npm|pnpm|yarn)\s+(?:warn|warning)\b/iu.test(item)) ?? lines[0];
+	return line ? line.slice(0, 300) : void 0;
+}
+const UNRESOLVED_BUILD_PATTERNS = [
+	/\[UNRESOLVED_IMPORT\]/u,
+	/Could not resolve ['"][^'"]+['"]/u,
+	/Module not found, treating it as an external dependency/u,
+	/No name was provided for external module/u
+];
+function unresolvedBuildDiagnostic(stdout, stderr) {
+	return `${stderr ?? ""}\n${stdout ?? ""}`.split("\n").map((line) => line.trim()).filter(Boolean).find((line) => UNRESOLVED_BUILD_PATTERNS.some((pattern) => pattern.test(line)))?.slice(0, 300);
+}
+async function runProjectBuild(root, { capture = false } = {}) {
+	const manager = detectPackageManager(root, JSON.parse(readFileSync(join(root, "package.json"), "utf8")));
+	const { spawn } = await import("node:child_process");
+	const command = process.platform === "win32" ? `${manager}.cmd` : manager;
+	return await new Promise((resolvePromise, reject) => {
+		const child = spawn(command, ["run", "build"], {
+			cwd: root,
+			stdio: capture ? [
+				"ignore",
+				"pipe",
+				"pipe"
+			] : "inherit"
+		});
+		let stdout = "";
+		let stderr = "";
+		if (capture) {
+			child.stdout.on("data", (chunk) => {
+				stdout += String(chunk);
+			});
+			child.stderr.on("data", (chunk) => {
+				stderr += String(chunk);
+			});
+		}
+		child.once("error", (error) => reject(error));
+		child.once("exit", (code, signal) => {
+			const result = {
+				code,
+				signal,
+				stdout,
+				stderr
+			};
+			if (code === 0) {
+				const unresolved = unresolvedBuildDiagnostic(stdout, stderr);
+				if (!unresolved) {
+					resolvePromise(result);
+					return;
+				}
+				const error = /* @__PURE__ */ new Error(`构建器退出码为 0，但存在未解析依赖：${unresolved}`);
+				Object.assign(error, result, { cliCode: "WIDGET_CLI_BUILD_UNRESOLVED_IMPORT" });
+				reject(error);
+			} else {
+				const detail = firstFailureLine(stderr) ?? firstFailureLine(stdout);
+				const error = /* @__PURE__ */ new Error(`构建失败（exit ${code ?? signal ?? "unknown"}）${detail ? `：${detail}` : ""}`);
+				Object.assign(error, result);
+				reject(error);
+			}
+		});
+	});
+}
+async function commandBuild(directory, options = {}) {
+	if (!directory) throw new Error("build 需要工程目录");
+	const root = resolve(directory);
+	try {
+		const build = await runProjectBuild(root, { capture: true });
+		const result = {
+			ok: true,
+			command: "build",
+			projectRoot: root,
+			stdout: build.stdout,
+			stderr: build.stderr
+		};
+		if (options.json && options.emit !== false) console.log(JSON.stringify(result, null, 2));
+		else if (options.emit !== false) {
+			if (build.stdout) process.stdout.write(build.stdout);
+			if (build.stderr) process.stderr.write(build.stderr);
+		}
+		return result;
+	} catch (error) {
+		const result = {
+			ok: false,
+			command: "build",
+			projectRoot: root,
+			error: commandError("build", error, {
+				projectRoot: root,
+				phase: "build"
+			}),
+			stdout: error?.stdout ?? "",
+			stderr: error?.stderr ?? ""
+		};
+		if (options.json && options.emit !== false) console.log(JSON.stringify(result, null, 2));
+		if (!options.json && options.emit !== false) {
+			if (result.stdout) process.stdout.write(result.stdout);
+			if (result.stderr) process.stderr.write(result.stderr);
+		}
+		process.exitCode = 1;
+		if (!options.json && options.emit !== false) throw error;
+		return result;
+	}
+}
+async function commandPack(directory, options) {
+	if (!directory) throw new Error("pack 需要工程目录");
+	if (options.build) {
+		const build = await commandBuild(directory, {
+			...options,
+			emit: false
+		});
+		if (!options.json) {
+			if (build.stdout) process.stdout.write(build.stdout);
+			if (build.stderr) process.stderr.write(build.stderr);
+		}
+		if (!build.ok) {
+			if (options.json) console.log(JSON.stringify({
+				...build,
+				command: "pack",
+				phase: "build"
+			}, null, 2));
+			process.exitCode = 1;
+			return build;
+		}
+	}
+	const result = applyCliProjectPolicies(await checkWidgetProject(resolve(directory), { requireBuiltEntry: true }));
+	if (!options.json) printResult(result, false);
+	if (!result.ok) {
+		if (options.json) console.log(JSON.stringify({
+			ok: false,
+			command: "pack",
+			projectRoot: result.projectRoot,
+			error: structuredError({
+				code: "WIDGET_CLI_PACK_VALIDATION_FAILED",
+				message: "Widget 工程校验失败，未生成可交付 Bundle。",
+				context: {
+					projectRoot: result.projectRoot,
+					phase: "validate"
+				},
+				recovery: commandRecovery("pack")
+			}),
+			checks: result.checks,
+			errors: result.errors
+		}, null, 2));
+		process.exitCode = 1;
+		return {
+			ok: false,
+			command: "pack",
+			projectRoot: result.projectRoot
+		};
+	}
+	const destination = resolve(options.output ?? join(result.projectRoot, `${result.manifest.name}.zip`));
+	const fixturesPath = join(result.projectRoot, "preview", "fixtures.json");
+	const hasFixtures = existsSync(fixturesPath);
+	const fixturesIncluded = hasFixtures && Boolean(options.includePreviewFixtures);
+	const warnings = [];
+	if (options.includePreviewFixtures && !hasFixtures) warnings.push("使用了 --include-preview-fixtures，但 preview/fixtures.json 不存在，ZIP 未包含任何 fixtures。");
+	else if (hasFixtures && !options.includePreviewFixtures) warnings.push("工程包含 preview/fixtures.json，未使用 --include-preview-fixtures，ZIP 未包含 fixtures。");
+	const bundle = buildWidgetPackage(result, { includePreviewFixtures: fixturesIncluded });
+	await mkdir(dirname(destination), { recursive: true });
+	await writeFile(destination, bundle);
+	const artifact = {
+		ok: true,
+		command: "pack",
+		projectRoot: result.projectRoot,
+		path: destination,
+		bytes: bundle.byteLength,
+		sha256: `sha256:${createHash("sha256").update(bundle).digest("hex")}`,
+		toolchain: {
+			cli: packageJson.version,
+			sdk: sdkPackage.version,
+			contracts: contractsPackage.version
+		},
+		manifest: {
+			name: result.manifest.name,
+			entry: result.manifest.widgetConfig.entry,
+			contribution: result.manifest.widgetConfig.contribution,
+			sampleIds: (result.manifest.widgetConfig.samples ?? []).map((sample) => sample.id)
+		},
+		checks: result.checks,
+		fixtures: {
+			path: fixturesPath,
+			requested: Boolean(options.includePreviewFixtures),
+			included: fixturesIncluded
+		},
+		...warnings.length === 0 ? {} : { warnings }
+	};
+	if (options.json) console.log(JSON.stringify(artifact, null, 2));
+	else {
+		console.log(`已生成可加载插件包：${destination}`);
+		for (const warning of warnings) console.warn(`提示：${warning}`);
+	}
+	return artifact;
+}
+async function commandMigrate(positional, options) {
+	if (positional[0] !== "dsh") throw new Error("migrate 目前只支持 dsh");
+	const action = positional[1];
+	const input = positional[2];
+	if (!input) throw new Error(`migrate dsh ${action ?? ""} 需要源插件目录`);
+	if (action === "audit") {
+		const report = await auditDshPlugin(input);
+		if (options.json) console.log(JSON.stringify({
+			ok: true,
+			command: "migrate dsh audit",
+			report
+		}, null, 2));
+		else console.log(`${report.migrationStatus}: ${report.source.name ?? "unknown"} (${report.compatibility.status})`);
+		return report;
+	}
+	if (action === "scaffold") {
+		if (!options.output) throw new Error("migrate dsh scaffold 需要 --out <widget-dir>");
+		const result = await scaffoldDshWidget(input, options.output, {
+			sdkVersion: sdkPackage.version,
+			contractsVersion: contractsPackage.version
+		});
+		if (options.json) console.log(JSON.stringify(result, null, 2));
+		else console.log(`已生成迁移 Widget：${result.projectRoot}`);
+		return result;
+	}
+	throw new Error(`未知 migrate dsh 操作：${action ?? ""}`);
+}
+async function commandDoctor(directory, options) {
+	const root = resolve(directory ?? ".");
+	const packagePath = join(root, "package.json");
+	const manifestPath = join(root, "manifest.json");
+	const report = {
+		cli: packageJson.version,
+		node: process.versions.node,
+		sdk: sdkPackage.version,
+		contracts: contractsPackage.version,
+		project: root,
+		packageJson: existsSync(packagePath),
+		manifest: existsSync(manifestPath),
+		nodeSupported: Number(process.versions.node.split(".")[0]) >= 20,
+		dependenciesInstalled: existsSync(join(root, "node_modules")),
+		manifestValid: false,
+		warnings: []
+	};
+	if (report.manifest) try {
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+		report.manifestValid = true;
+		report.manifestKind = manifest.contributes ? "plugin" : "host";
+		report.pluginName = manifest.name;
+		report.entryPath = manifest.widgetConfig?.entry;
+	} catch {
+		report.manifestKind = "invalid";
+	}
+	report.entryPath ??= "dist/widget.js";
+	report.entry = existsSync(join(root, report.entryPath));
+	report.ok = report.nodeSupported && report.packageJson && report.manifest && report.manifestValid;
+	report.ready = report.ok && report.dependenciesInstalled && report.entry;
+	if (report.manifest && !report.manifestValid) report.warnings.push("manifest.json 不是有效 JSON：修复语法后再执行 doctor、check 或 pack。");
+	if (!report.dependenciesInstalled) report.warnings.push("未找到 node_modules：先执行包管理器 install，build/pack 需要工程依赖。");
+	if (!report.entry) report.warnings.push(`未找到构建入口 ${report.entryPath}：先执行 bohr-widget build . 或工程 build 脚本。`);
+	if (options.json) console.log(JSON.stringify(report, null, 2));
+	else {
+		console.log(`${report.ok ? "✓" : "✗"} 环境检查${report.ok ? "通过" : "失败"}：Node ${report.node}，SDK ${report.sdk}，Contracts ${report.contracts}`);
+		console.log(`${report.ready ? "✓" : "✗"} 工程可直接 check/pack：${report.ready ? "是" : "否"}`);
+		for (const warning of report.warnings) console.warn(`提示：${warning}`);
+	}
+	if (!report.ok) process.exitCode = 1;
+}
+function commandSchema() {
+	console.log(require.resolve("@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json"));
+}
+function commandVersion(options) {
+	const result = {
+		ok: true,
+		command: "version",
+		cli: packageJson.version,
+		sdk: sdkPackage.version,
+		contracts: contractsPackage.version
+	};
+	if (options.json) console.log(JSON.stringify(result, null, 2));
+	else console.log(`${result.cli} (SDK ${result.sdk})`);
+	return result;
+}
+async function main(argv) {
+	if (argv.includes("--help") || argv.includes("-h")) return console.log(usage());
+	const command = argv[0] ?? "help";
+	if (command === "dev") {
+		const exitCode = await runWidgetDevelopmentCli(argv.slice(1));
+		if (exitCode !== 0) process.exitCode = exitCode;
+		return exitCode;
+	}
+	const { positional, options } = parseOptions(argv.slice(1));
+	if (!COMMANDS.includes(command)) throw new Error(`未知命令：${command}`);
+	if (command === "help") return console.log(usage());
+	if (command === "version") return commandVersion(options);
+	if (command === "create") return commandCreate(positional[0], options);
+	if (command === "check" || command === "validate") return commandCheck(positional[0], options, command);
+	if (command === "build") return commandBuild(positional[0], options);
+	if (command === "pack") return commandPack(positional[0], options);
+	if (command === "doctor") return commandDoctor(positional[0], options);
+	if (command === "migrate") return commandMigrate(positional, options);
+	if (command === "schema") return commandSchema();
+}
+/**
+* 是否直接执行本文件。npm/pnpm 的 node_modules/.bin/bohr-widget 是符号链接，
+* import.meta.url 已被 Node 解析为 realpath，而 process.argv[1] 保留调用时的路径；
+* 只做 resolve() 比较会让 `bohr-widget ...`、`npx bohr-widget ...` 静默空转（exit 0）。
+*/
+function isDirectInvocation() {
+	const entry = process.argv[1];
+	if (!entry) return false;
+	const normalize = (value) => {
+		let resolved;
+		try {
+			resolved = realpathSync(value);
+		} catch {
+			resolved = resolve(value);
+		}
+		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	};
+	return normalize(entry) === normalize(fileURLToPath(import.meta.url));
+}
+if (isDirectInvocation()) try {
+	await main(process.argv.slice(2));
+} catch (error) {
+	const argv = process.argv.slice(2);
+	const operands = argv.filter((argument) => !argument.startsWith("-"));
+	const command = operands[0] ?? "help";
+	if (argv.includes("--json")) console.log(JSON.stringify({
+		ok: false,
+		command,
+		error: commandError(command, error, {
+			input: operands[1] ?? null,
+			stdout: error?.stdout ?? "",
+			stderr: error?.stderr ?? ""
+		})
+	}, null, 2));
+	else console.error(`${error instanceof Error ? error.message : String(error)}\n\n${usage()}`);
+	process.exitCode = 1;
+}
+//#endregion
+export {};