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

package/dist/cli.mjs

@@ -0,0 +1,3174 @@
+#!/usr/bin/env node
+import { a as normalizeArchivePath, c as resolveWidgetProjects, i as collectWidgetPackageFiles, l as compileAuthorManifest, n as scaffoldDshWidget, o as storedZip, s as checkWidgetProject, t as auditDshPlugin } from "./dsh-BzxDpEcZ.mjs";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
+import { mkdir, readFile, readdir, realpath, rm, stat, 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: 250,
+		maxDelayMs: 1e3,
+		totalMs: 5e3
+	},
+	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 = {}) {
+	const code = error?.cliCode ?? error?.code;
+	return {
+		code: typeof code === "string" && /^(?:WIDGET_DEV_|WIDGET_CLI_)/u.test(code) ? code : "WIDGET_DEV_FAILED",
+		message: error instanceof Error ? error.message : String(error),
+		context: {
+			...context,
+			...error?.context
+		},
+		recovery: error?.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$1(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, manifestOptions = {}) {
+	const sourceManifest = JSON.parse(readFileSync(join(projectRoot, "manifest.json"), "utf8"));
+	const manifest = compileAuthorManifest(sourceManifest, manifestOptions);
+	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, manifestOptions = {}) {
+	const { manifest, entryPath } = readProject(projectRoot, manifestOptions);
+	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 buildProject = options.buildProject ?? runBuild;
+	const emit = options.emit ?? ((line, error = false) => error ? console.error(line) : console.log(line));
+	const validateProject = async () => {
+		if (!options.checkProject) return;
+		const check = await options.checkProject(projectRoot, {
+			...options.manifestOptions,
+			requireBuiltEntry: true
+		});
+		if (!check.ok) {
+			const error = /* @__PURE__ */ new Error(`Widget Dev L0 check 失败：${check.errors.join("; ")}`);
+			error.code = "WIDGET_DEV_PROJECT_INVALID";
+			throw error;
+		}
+	};
+	await options.beforeBuild?.({
+		projectRoot,
+		initial: true,
+		build: options.build
+	});
+	if (options.build) await buildProject(projectRoot, { capture: options.json });
+	await validateProject();
+	let successfulGeneration = createDevelopmentGeneration(projectRoot, 0, GENERATION_LIMITS, options.manifestOptions);
+	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$1(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$1(response, 200, session.descriptor);
+			return;
+		}
+		if (url.pathname === CLAIM_PATH && request.method === "POST") {
+			try {
+				json$1(response, 200, session.claim(bearer(request.headers.authorization)));
+			} catch (error) {
+				json$1(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$1(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$1(response, 200, {
+						ok: true,
+						protocolVersion: 1,
+						action: control.action
+					});
+				} catch (error) {
+					json$1(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$1(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$1(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$1(response, 200, createDevelopmentConfig({
+				manifest: successfulGeneration.manifest,
+				runId,
+				origin,
+				launchUrl: `${origin}${LAUNCH_PATH}`,
+				digest: successfulGeneration.digest
+			}));
+			return;
+		}
+		if (url.pathname === STATUS_PATH) {
+			json$1(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 {
+			await options.beforeBuild?.({
+				projectRoot,
+				initial: false,
+				build: true
+			});
+			const build = await buildProject(projectRoot, { capture: options.json });
+			await validateProject();
+			const candidate = createDevelopmentGeneration(projectRoot, successfulGeneration.number + 1, GENERATION_LIMITS, options.manifestOptions);
+			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), overrides = {}) {
+	try {
+		const options = {
+			...parseArgs(argv),
+			...overrides
+		};
+		if (options.help) {
+			console.log(usage$1());
+			return 0;
+		}
+		const [projectRoot] = resolveWidgetProjects(options.project);
+		const checkProject = options.checkProject ?? checkWidgetProject;
+		const check = await checkProject(projectRoot, {
+			...options.manifestOptions,
+			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,
+			checkProject
+		});
+		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/help.mjs
+const COMMANDS = [
+	"create",
+	"check",
+	"validate",
+	"build",
+	"dev",
+	"pack",
+	"doctor",
+	"schema",
+	"migrate",
+	"version",
+	"integration",
+	"adopt",
+	"help"
+];
+const HELP_OPTION = "-h, --help                  显示当前命令帮助并退出";
+const JSON_OPTION = "--json                      输出单个 JSON 文档（默认输出文本）";
+const HOST_OPTION = "--host-compat <声明文件>      核对目标宿主的声明；默认不提供，兼容状态为 unknown";
+function commandTopics(context) {
+	const check = (name) => ({
+		description: name === "validate" ? "check 的别名；校验工程的清单、已构建入口、samples 和预览夹具。" : "校验作者清单、编译后的宿主清单、已构建入口、samples 和预览夹具。",
+		usage: [`bohr-widget ${name} <目录|manifest.json|all> [选项]`],
+		arguments: ["目录|manifest.json|all      必填；检查单个工程，或从当前目录发现示例工程"],
+		options: [HOST_OPTION, "--json                      单工程输出检查结果；all 输出单个汇总 JSON 文档"],
+		examples: [`bohr-widget ${name} ./my-widget --json`, `bohr-widget ${name} all --json`],
+		notes: [
+			"不执行构建；入口缺失时先运行 bohr-widget build <目录>。",
+			"all 从当前目录查找 examples/sdk 和 examples/integration；未发现时尝试当前目录的 manifest.json。",
+			"没有找到工程或任一工程校验失败时，退出码为 1。",
+			"校验通过只证明本地结构和声明符合要求；实际渲染与能力授权仍需在 Host 中验证。"
+		]
+	});
+	const migrationGroup = {
+		description: "审计 DeepSeek Harness（DSH）插件，并按已审查的来源配方生成 Widget 工程。",
+		usage: ["bohr-widget migrate dsh audit <plugin-dir> [选项]", "bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [选项]"],
+		arguments: [
+			"dsh                         当前唯一支持的迁移来源",
+			"audit                       只读审计来源、指纹和能力缺口",
+			"scaffold                    使用匹配的已审查配方创建新工程"
+		],
+		options: [],
+		examples: ["bohr-widget migrate dsh audit ./dsh-plugin --json", "bohr-widget migrate dsh scaffold ./dsh-plugin --out ./migrated-widget --json"],
+		notes: [
+			"先 audit，再读取报告决定是否 scaffold；源指纹变化或无匹配配方时不能直接生成。",
+			"不执行源插件安装脚本或 Cordis patch；Host adapter 工作仍需单独完成。",
+			"使用 bohr-widget migrate dsh <audit|scaffold> --help 查看详细参数。"
+		]
+	};
+	return {
+		create: {
+			description: "创建可独立安装、构建和打包的 Widget 工程，生成源码、样例和工具链锁定文件。",
+			usage: ["bohr-widget create <目录> [选项]"],
+			arguments: ["目录                        必填；目标目录必须不存在"],
+			options: [
+				"--template <模板>           panel 或 file-preview（默认 panel）",
+				"--ui <模式>                 vanilla 或 react（默认 vanilla）",
+				"--panel-id <id>             仅用于 panel；默认取规范化后的工程名",
+				HOST_OPTION,
+				JSON_OPTION
+			],
+			examples: ["bohr-widget create workspace-browser --ui react --panel-id workspace-files", "bohr-widget create text-preview --template file-preview --ui vanilla --json"],
+			notes: [
+				`默认组合为 panel + vanilla；生成工程的构建环境要求 Node.js ${context.generatedProjectNode}。`,
+				"不会自动安装依赖；创建后进入目录，运行 pnpm install 或 npm install。",
+				"workspace-files 会补齐 files.list、files.metadata、files.read 和目录引用样例；文件树逻辑与夹具需自行实现。",
+				"其他 Panel id 需要 Host 预先注册和绑定；更改 id 不会自动接管宿主界面。",
+				"将 widget-toolchain.json 与包管理器 lockfile 一起保存。"
+			],
+			quickStart: true
+		},
+		check: check("check"),
+		validate: check("validate"),
+		build: {
+			description: "执行工程自己的 build 脚本，核对依赖与构建结果，并记录可复用的构建 receipt。",
+			usage: ["bohr-widget build <目录> [选项]"],
+			arguments: ["目录                        必填；已安装依赖的 Widget 工程目录"],
+			options: [HOST_OPTION, JSON_OPTION],
+			examples: ["bohr-widget build ./my-widget", "bohr-widget build . --host-compat ./host.json --json"],
+			notes: [
+				"先安装工程依赖；使用 packageManager 指定的包管理器，其次按 lockfile 检测，最后回退 npm。",
+				"成功后写入 .widget-build-receipt.json；pack --no-build 会检查这份记录。",
+				"本命令不代替完整的 Manifest、samples 和 fixtures 校验；构建后继续运行 check。",
+				"失败时读取 error、stdout 和 stderr；构建器退出 0 但仍报告未解析依赖也会失败。"
+			]
+		},
+		dev: {
+			description: "启动本地 Profile 与资源服务，供支持 Widget 开发会话的 Host 加载和调试。",
+			usage: ["bohr-widget dev <目录|manifest.json> [选项]"],
+			arguments: ["目录|manifest.json          必填；要运行的 Widget 工程"],
+			options: [
+				"--watch                     监听源码与清单变化并重建（默认关闭）",
+				"--open                      连接或唤起 Widget 开发宿主（默认关闭）",
+				"--no-build                  跳过首次构建，使用现有入口（默认先构建）",
+				"--port <端口>               本地服务端口，1024–65535（默认 4300）",
+				"--scheme <scheme>           宿主 deep link scheme（默认 widget-host）",
+				"--bridge <url>              指定 loopback HTTP(S) bridge；默认探测标准端口",
+				HOST_OPTION,
+				"--json                      持续输出 NDJSON 事件流（默认输出文本）"
+			],
+			examples: ["bohr-widget dev . --watch --open", "bohr-widget dev ./my-widget --no-build --port 4301 --json"],
+			notes: [
+				"--open 打开的是目标 Host，不是浏览器预览；先连接 bridge，必要时尝试宿主 scheme。",
+				"不传 --open 时可使用输出的 Host URL；服务常驻，按 Ctrl+C 结束。",
+				"--no-build 不要求构建 receipt，但仍校验工具链与现有产物；搭配 --watch 时后续变化仍会构建。",
+				"--bridge 须带 1024–65535 的显式端口，且不能包含认证信息、query 或 hash。",
+				"--bridge 仅在使用 --open 时参与宿主连接。",
+				"dev --json 是逐行事件流；session-ready 含 profileUrl、statusUrl、hostUrl、digest 和连接结果。",
+				"当前本地开发文件能力只读；Manifest 申请或样例 grant 不代表目标 Host 已开放写入。",
+				"watch 构建失败时保留上一轮可用产物；从 statusUrl 查看 lastBuildError。"
+			],
+			quickStart: true
+		},
+		pack: {
+			description: "默认先构建和校验工程，再生成宿主可加载的 Widget ZIP 与 SHA-256 摘要。",
+			usage: ["bohr-widget pack <目录> [选项]"],
+			arguments: ["目录                        必填；要打包的 Widget 工程目录"],
+			options: [
+				"--out <zip>                 输出路径；默认 <工程目录>/<manifest.name>.zip",
+				"--no-build                  复用匹配的构建 receipt（默认重新构建）",
+				"--include-preview-fixtures  包含 preview/fixtures.json（默认不包含）",
+				HOST_OPTION,
+				JSON_OPTION
+			],
+			examples: ["bohr-widget pack . --out ./artifacts/widget.zip --json", "bohr-widget pack ./my-widget --no-build --include-preview-fixtures --out ./repro.zip"],
+			notes: [
+				"--out 相对调用时的当前目录解析，自动创建父目录；目标 ZIP 已存在时会覆盖。",
+				"--no-build 要求 .widget-build-receipt.json 与当前 CLI/profile、工具链摘要、实际依赖、输入和产物一致。",
+				"单独执行工程 build 脚本不生成 CLI receipt；需先运行 bohr-widget build <目录>。",
+				"携带预览夹具的 ZIP 用于本地复现，不作为上传 ZIP；上传包使用默认不含夹具的形式。",
+				"入口构建目录中的 chunk、CSS、WASM 等部署资源一并保留；不要将源码或凭据放入该目录。",
+				"--json 返回 path、bytes、sha256、toolchain、manifest 和 fixtures.included；后续交付使用同一份 ZIP 与摘要。",
+				"本命令不上传、不发布、不绑定 Agent；成功打包也不代表 Host 已实际渲染。"
+			]
+		},
+		doctor: {
+			description: "诊断 Node、清单、精确依赖、工具链锁和构建入口，解释工程尚未就绪的原因。",
+			usage: ["bohr-widget doctor [目录] [选项]"],
+			arguments: ["目录                        可选；默认当前目录（.）"],
+			options: [HOST_OPTION, JSON_OPTION],
+			examples: ["bohr-widget doctor --json", "bohr-widget doctor ./existing-widget --host-compat ./host.json --json"],
+			notes: [
+				"只检查状态，不安装依赖、不构建，也不写入工具链锁。",
+				"ok 表示环境、清单与候选 profile 检查通过；ready 还要求工具链锁、已安装依赖和构建入口。",
+				"尚未安装或构建时可能 ok=true、ready=false；先按 warnings 修复再继续。",
+				"ready 不保证 pack --no-build 的 receipt 可复用；doctor 只检查 CLI 的 Node 要求，不验证构建器环境。",
+				"旧工程缺少 widget-toolchain.json 时，先核对精确依赖并安装，再运行 adopt。"
+			]
+		},
+		integration: {
+			description: "发现固定工具链、执行器位置、Node 要求与文档入口，供 Agent 或其他 CLI 集成。",
+			usage: ["bohr-widget integration [选项]"],
+			options: [
+				"--project <目录>            可选；同时核对指定工程的锁定 profile 与依赖声明",
+				HOST_OPTION,
+				JSON_OPTION
+			],
+			examples: ["bohr-widget integration --json", "bohr-widget integration --project ./my-widget --host-compat ./host.json --json"],
+			notes: [
+				"不传 --project 时只发现 CLI 自带工具链，不检查当前目录是否为 Widget 工程。",
+				"传入工程时要求工具链锁；尚未安装依赖时先核对声明，已安装时同时核对实际版本。",
+				"JSON 使用 interfaceVersion=2、toolchain.formatVersion=2；返回 execution、profile、requirements 和 documentation。",
+				"调用方应使用 execution.executable 与 execution.entry 启动同一份 CLI，避免 PATH 指向另一版本。",
+				"宿主声明由调用方提供；unknown、snapshot、confirmed 不代表上传或发布许可。"
+			],
+			agentDocs: true
+		},
+		adopt: {
+			description: "核验旧工程与当前固定工具链匹配后，显式写入 widget-toolchain.json。",
+			usage: ["bohr-widget adopt <目录> [选项]"],
+			arguments: ["目录                        必填；待锁定的已有 Widget 工程"],
+			options: [HOST_OPTION, JSON_OPTION],
+			examples: ["bohr-widget adopt ./existing-widget --json", "bohr-widget adopt . --host-compat ./host.json --json"],
+			notes: [
+				"先运行 doctor，恢复当前 profile 的精确 SDK/contracts 依赖并安装。",
+				"核对实际依赖、Manifest 和 samples 后才写锁；不要求已构建入口。",
+				"不会自动升级依赖、迁移源码或修正协议字段；检查不通过时先修复工程。"
+			]
+		},
+		schema: {
+			description: "打印本 CLI 自带的作者插件 Manifest Schema 的本地绝对路径。",
+			usage: ["bohr-widget schema"],
+			options: [],
+			examples: ["bohr-widget schema", "bohr-widget schema > schema-path.txt"],
+			notes: [
+				"输出 widget-plugin-manifest.schema.json 的路径，不打印 Schema 正文。",
+				"不读取工程；即使传 --json，仍输出纯文本路径。",
+				"使用配套 contracts Schema 进行结构检查；通过 Schema 不代表 Host 授权。"
+			]
+		},
+		version: {
+			description: "查看当前 CLI 及其固定的 SDK/contracts 版本。",
+			usage: ["bohr-widget version [--json]", "bohr-widget --version [--json]"],
+			options: [JSON_OPTION],
+			examples: ["bohr-widget version --json", "bohr-widget -v"],
+			notes: [
+				`当前 CLI ${context.cli}，SDK ${context.sdk}，contracts ${context.contracts}。`,
+				"文本输出 CLI 与 SDK 版本；--json 同时包含 contracts，不访问 npm registry。",
+				"全局 -v / --version 等同版本查询，不执行工程操作。"
+			]
+		},
+		migrate: migrationGroup,
+		"migrate dsh": {
+			...migrationGroup,
+			arguments: migrationGroup.arguments.slice(1)
+		},
+		"migrate dsh audit": {
+			description: "只读审计 DSH 插件的来源指纹、已知配方与能力迁移缺口。",
+			usage: ["bohr-widget migrate dsh audit <plugin-dir> [选项]"],
+			arguments: ["plugin-dir                  必填；DSH 插件源目录"],
+			options: [JSON_OPTION],
+			examples: ["bohr-widget migrate dsh audit ./dsh-plugin", "bohr-widget migrate dsh audit ./dsh-plugin --json"],
+			notes: [
+				"不创建目标工程，不执行 Cordis patch 或源插件安装脚本。",
+				"JSON 的 report 包含来源指纹、配方兼容状态和能力分类；读取结论后再决定是否 scaffold。",
+				"审计命令执行成功不等于插件可自动迁移；未知来源或变化后的指纹需要人工审查。"
+			]
+		},
+		"migrate dsh scaffold": {
+			description: "按已审查且来源指纹一致的 DSH 配方创建 Widget 工程及迁移报告。",
+			usage: ["bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [选项]"],
+			arguments: ["plugin-dir                  必填；已完成审计的 DSH 插件源目录"],
+			options: [
+				"--out <widget-dir>          必填；要创建的新工程目录，不能已存在",
+				HOST_OPTION,
+				JSON_OPTION
+			],
+			examples: ["bohr-widget migrate dsh scaffold ./dsh-plugin --out ./migrated-widget", "bohr-widget migrate dsh scaffold ./dsh-plugin --out ./migrated-widget --host-compat ./host.json --json"],
+			notes: [
+				"先运行 audit；无已审查配方或迁移期间指纹变化时停止，不覆盖已有工程；目标的父目录须已存在。",
+				"输出 widget-toolchain.json 与 migration-report.json；随后安装依赖、build、check 和 pack。",
+				"工具、Skill、system prompt、文件和网络等 Host adapter 工作不会自动迁入 Widget。",
+				"生成成功只表示创建了工程，仍需目标 Host 验收。"
+			]
+		},
+		help: {
+			description: "查看全局命令概览，或查看某个命令及迁移子命令的详细帮助。",
+			usage: ["bohr-widget help [命令 [子命令...]]", "bohr-widget <命令> --help"],
+			arguments: ["命令 [子命令...]            可选；省略时显示全局帮助"],
+			options: [],
+			examples: ["bohr-widget help create", "bohr-widget migrate dsh scaffold --help"],
+			notes: ["不传参数、-h 和 --help 都可查看全局帮助；子命令后的 -h / --help 显示对应主题。", "帮助始终输出文本，不执行创建、构建或迁移操作。"]
+		}
+	};
+}
+function documentationLines(documentation, topic = {}) {
+	return [
+		...topic.quickStart ? [`快速开始：${documentation.quickStart}`] : [],
+		`命令参考：${documentation.cli}`,
+		...topic.agentDocs ? [
+			`文档站：${documentation.url}`,
+			`Agent 索引：${documentation.llms}`,
+			`完整文档：${documentation.llmsFull}`
+		] : []
+	];
+}
+function section(title, lines) {
+	return lines.length ? `\n${title}：\n${lines.map((line) => `  ${line}`).join("\n")}\n` : "";
+}
+function globalHelp(context) {
+	const { cli, sdk, contracts, generatedProjectNode, documentation } = context;
+	return `bohr-widget ${cli} — Bohrium Widget 插件工程工具
+SDK ${sdk} / contracts ${contracts}
+创建、校验、构建、开发调试与打包；上传、发布和 Agent 绑定由 Bohr CLI 或平台执行。
+
+用法：
+  bohr-widget <命令> [参数] [选项]
+  bohr-widget help [命令 [子命令...]]
+
+命令：
+  create <目录>                    创建 Widget 工程（默认 panel + vanilla）
+  check <目录|manifest.json|all>    校验清单、已构建入口、samples 和 fixtures
+  validate <目录|manifest.json|all> check 的别名
+  build <目录>                     执行工程构建并记录构建 receipt
+  dev <目录|manifest.json>         启动本地开发服务，供 Widget Host 加载
+  pack <目录>                      默认先构建、校验，再生成 Widget ZIP
+  doctor [目录]                    诊断环境和工程状态（默认当前目录）
+  integration                      发现工具链、执行器和文档入口
+  adopt <目录>                     核验旧工程并写入工具链锁
+  schema                           打印作者 Manifest Schema 的本地路径
+  migrate dsh audit|scaffold        审计 DSH 来源或按已审查配方生成工程
+  version                          查看 CLI 与固定的 SDK/contracts 版本
+  help [命令...]                   查看全局或指定主题帮助
+
+全局选项：
+  -h, --help                       显示全局或指定命令帮助并退出
+  -v, --version                    显示版本并退出；可搭配 --json
+  --json                           多数命令输出单个 JSON；dev 输出 NDJSON 事件流
+                                   check all 输出汇总；help 与 schema 始终输出文本
+
+调用方式：
+  工程内：pnpm exec bohr-widget ... 或 npx --no-install bohr-widget ...
+  未安装：pnpm dlx @dp-bohrium/widget-cli <命令> ...
+  下方示例中的 bohr-widget 可使用上述工程内调用前缀。
+  CLI 要求 Node.js >=20；默认生成工程要求 Node.js ${generatedProjectNode}。
+
+典型开发流程：
+  pnpm dlx @dp-bohrium/widget-cli create my-widget --ui react --panel-id workspace-files
+  cd my-widget
+  pnpm install
+  pnpm exec bohr-widget build .
+  pnpm exec bohr-widget check .
+  pnpm exec bohr-widget dev . --watch --open
+  pnpm run widget:pack
+
+  check 不执行构建；dev 按 Ctrl+C 结束后可继续打包。
+  Widget ZIP 使用 widget:pack 脚本；pnpm pack 是制作 npm .tgz 包的内置命令。
+  工程命令可用 --host-compat <声明文件> 核对宿主；未提供时兼容状态为 unknown。
+
+文档：
+  文档站：${documentation.url}
+  快速开始：${documentation.quickStart}
+  命令参考：${documentation.cli}
+  Agent 索引：${documentation.llms}
+  完整文档：${documentation.llmsFull}
+
+查看具体命令的参数、默认值和示例：bohr-widget <命令> --help
+`;
+}
+function renderHelp(path = [], context) {
+	if (path.length === 0) return globalHelp(context);
+	const key = path.join(" ");
+	const topics = commandTopics(context);
+	if (!Object.hasOwn(topics, key)) throw new Error(`未知帮助主题：${key}`);
+	const topic = topics[key];
+	return `bohr-widget ${key} — ${topic.description}\n` + section("用法", topic.usage) + section("参数", topic.arguments ?? []) + section("选项", [...topic.options, HELP_OPTION]) + section("示例", topic.examples) + section("说明", topic.notes) + section("文档", documentationLines(context.documentation, topic));
+}
+//#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/project-executor.mjs
+const PROJECT_TOOLCHAIN_FILE = "widget-toolchain.json";
+const BUILD_RECEIPT_FILE = ".widget-build-receipt.json";
+const PACKAGES = Object.freeze({
+	sdk: "@dp-bohrium/widget-sdk",
+	contracts: "@dp-bohrium/widget-contracts"
+});
+const EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+function failure(code, message, context, recovery) {
+	return Object.assign(new Error(message), {
+		cliCode: `WIDGET_CLI_${code}`,
+		context,
+		recovery
+	});
+}
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+async function json(path, code, recovery) {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw failure(code, `无法读取有效 JSON：${path}`, {
+			path,
+			cause: error.message
+		}, recovery);
+	}
+}
+function date(value) {
+	return typeof value === "string" && /T.*(?:Z|[+-]\d{2}:\d{2})$/u.test(value) ? Date.parse(value) : NaN;
+}
+/** A caller-provided observation is evidence, not a platform publication permit. */
+async function assertHostCompatibility(hostCompatPath, toolchain, { now = Date.now(), expectedHost, expectedEnvironment } = {}) {
+	const profileId = toolchain.profile.id;
+	if (!hostCompatPath) return {
+		status: "unknown",
+		profileId
+	};
+	const invalid = (reason) => {
+		throw failure("HOST_COMPAT_INVALID", `宿主兼容声明无效：${reason}`, {
+			path: resolve(hostCompatPath),
+			expectedHost,
+			expectedEnvironment
+		}, ["重新获取本次目标环境的宿主兼容声明，再通过 --host-compat 传入。"]);
+	};
+	const value = await json(hostCompatPath, "HOST_COMPAT_INVALID", ["重新获取本次目标环境的宿主兼容声明。"]);
+	if (!record(value) || !record(value.statement)) invalid("缺少 statement");
+	const { statement, observation } = value;
+	if (statement.formatVersion !== 1 || !text(statement.hostId) || !text(statement.environment) || !text(statement.revision) || !Array.isArray(statement.acceptedProfiles) || !statement.acceptedProfiles.every(text) || new Set(statement.acceptedProfiles).size !== statement.acceptedProfiles.length) invalid("statement 字段不符合 formatVersion=1");
+	if (expectedHost && statement.hostId !== expectedHost || expectedEnvironment && statement.environment !== expectedEnvironment) invalid("hostId/environment 与目标环境不符");
+	const issuedAt = date(statement.issuedAt);
+	const expiresAt = date(statement.expiresAt);
+	const observedNow = now instanceof Date ? now.getTime() : Number(now);
+	if (!Number.isFinite(observedNow) || !Number.isFinite(issuedAt) || !Number.isFinite(expiresAt) || expiresAt <= issuedAt || issuedAt > observedNow) invalid("声明时间无效或尚未生效");
+	if (!record(observation) || !["online", "snapshot"].includes(observation.source) || !Number.isFinite(date(observation.fetchedAt)) || date(observation.fetchedAt) < issuedAt || date(observation.fetchedAt) > observedNow) invalid("observation 必须包含有效 source 和 fetchedAt");
+	if (!statement.acceptedProfiles.includes(profileId)) throw failure("HOST_PROFILE_UNSUPPORTED", `宿主 ${statement.hostId}/${statement.environment} 未接受当前工具链 ${profileId}`, {
+		profileId,
+		hostId: statement.hostId,
+		environment: statement.environment,
+		revision: statement.revision,
+		acceptedProfiles: statement.acceptedProfiles
+	}, ["使用经该宿主验收的 Widget CLI，或完成宿主平台升级；不要修改 SDK 版本字符串绕过校验。"]);
+	const fresh = expiresAt > observedNow;
+	return {
+		status: observation.source === "online" && fresh ? "confirmed" : "snapshot",
+		profileId,
+		hostId: statement.hostId,
+		environment: statement.environment,
+		revision: statement.revision,
+		issuedAt: statement.issuedAt,
+		expiresAt: statement.expiresAt,
+		observation,
+		...!fresh ? { reason: "expired" } : {}
+	};
+}
+function assertMatchingLock(lock, toolchain, root) {
+	const { profile } = toolchain;
+	if (!record(lock) || lock.formatVersion !== 1 || lock.profileId !== profile.id) throw failure("PROJECT_PROFILE_MISMATCH", "工程锁定的 profile 与当前 Widget CLI 不一致", {
+		projectRoot: root,
+		expectedProfile: profile.id,
+		actualProfile: lock?.profileId
+	}, ["使用携带工程 profile 的 Widget CLI；跨 profile 迁移需显式修改和验收工程。"]);
+	if (lock.sdk !== profile.sdk || lock.contracts !== profile.contracts) throw failure("PROJECT_SDK_MISMATCH", "工程锁定的 SDK/contracts 与当前 profile 不一致", {
+		projectRoot: root,
+		expected: profile,
+		actual: lock
+	}, ["恢复正确的 widget-toolchain.json 和精确依赖，再重新安装工程依赖。"]);
+	return lock;
+}
+async function readLock(root, toolchain, required) {
+	const path = join(root, PROJECT_TOOLCHAIN_FILE);
+	let value;
+	try {
+		value = await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		if (!required) return null;
+		throw failure("PROJECT_TOOLCHAIN_REQUIRED", "工程缺少 widget-toolchain.json，需先显式确认工具链", {
+			projectRoot: root,
+			path
+		}, ["先执行 bohr-widget doctor，再执行 bohr-widget adopt <工程目录>。"]);
+	}
+	let lock;
+	try {
+		lock = JSON.parse(value);
+	} catch {
+		throw failure("PROJECT_PROFILE_MISMATCH", "widget-toolchain.json 不是有效 JSON", {
+			projectRoot: root,
+			path
+		}, ["从版本库恢复有效的工程锁定信息，不要直接改 profile 绕过校验。"]);
+	}
+	return assertMatchingLock(lock, toolchain, root);
+}
+/** Resolve from this project's node_modules, never from an ancestor or the CLI. */
+async function validateProjectToolchain(projectRoot, toolchain, { requireInstalled = true, requireLock = true } = {}) {
+	const root = resolve(projectRoot);
+	const lock = await readLock(root, toolchain, requireLock);
+	const pkg = await json(join(root, "package.json"), "PROJECT_SDK_MISMATCH", ["恢复工程 package.json 中的精确 SDK/contracts 依赖。"]);
+	if (!record(pkg)) throw failure("PROJECT_SDK_MISMATCH", "工程 package.json 必须是对象", { projectRoot: root }, ["恢复工程 package.json 中的精确 SDK/contracts 依赖。"]);
+	const declared = {};
+	const installed = {};
+	for (const [key, name] of Object.entries(PACKAGES)) {
+		const declarations = [
+			"dependencies",
+			"devDependencies",
+			"optionalDependencies"
+		].map((section) => pkg[section]?.[name]).filter((version) => version !== void 0);
+		const expected = toolchain.profile[key];
+		if (declarations.length === 0 || declarations.some((version) => typeof version !== "string" || !EXACT_VERSION.test(version) || version !== expected)) throw failure("PROJECT_SDK_MISMATCH", `${name} 必须精确声明为 ${expected}`, {
+			projectRoot: root,
+			package: name,
+			expected,
+			declared: declarations
+		}, ["按 widget-toolchain.json 恢复精确版本，再重新安装工程依赖；不要使用 ^、~、workspace 或 latest。"]);
+		declared[key] = expected;
+		if (!requireInstalled) continue;
+		const actual = await json(join(root, "node_modules", name, "package.json"), "PROJECT_SDK_MISMATCH", ["在该 Widget 工程目录安装依赖，再重试；父目录或 CLI 的安装不能替代工程安装。"]);
+		if (!record(actual) || actual.name !== name || actual.version !== expected) throw failure("PROJECT_SDK_MISMATCH", `${name} 实际安装版本与工程工具链不一致`, {
+			projectRoot: root,
+			package: name,
+			expected,
+			installed: actual?.version
+		}, ["按工程锁定信息恢复依赖并重新安装，再重新构建。"]);
+		installed[key] = actual.version;
+	}
+	return {
+		projectRoot: root,
+		profile: { ...toolchain.profile },
+		declared,
+		installed,
+		dependenciesVerified: requireInstalled,
+		lock
+	};
+}
+async function writeProjectToolchain(projectRoot, toolchain) {
+	const root = resolve(projectRoot);
+	const existing = await readLock(root, toolchain, false);
+	if (existing) return existing;
+	const value = {
+		formatVersion: 1,
+		profileId: toolchain.profile.id,
+		sdk: toolchain.profile.sdk,
+		contracts: toolchain.profile.contracts,
+		createdWithCli: toolchain.cli
+	};
+	await mkdir(root, { recursive: true });
+	try {
+		await writeFile(join(root, PROJECT_TOOLCHAIN_FILE), `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		return readLock(root, toolchain, true);
+	}
+	return value;
+}
+async function adoptProjectToolchain(projectRoot, toolchain) {
+	const result = await validateProjectToolchain(projectRoot, toolchain, { requireLock: false });
+	const check = await checkWidgetProject(result.projectRoot, {
+		requireBuiltEntry: false,
+		toolchain: { sdkVersion: toolchain.profile.sdk }
+	});
+	const lint = looksLikeAuthorManifest(check.sourceManifest) ? lintAuthorManifest(check.sourceManifest) : {
+		ok: true,
+		errors: []
+	};
+	if (!lint.ok || !check.ok || check.manifest?.widgetConfig?.widgetSdkVersion !== toolchain.profile.sdk) throw failure("PROJECT_PROFILE_MISMATCH", "工程 Manifest 或 samples 无法通过当前 profile 校验，不能直接 adopt", {
+		projectRoot: result.projectRoot,
+		profileId: toolchain.profile.id,
+		errors: [...lint.errors, ...check.errors],
+		manifestSdkVersion: check.manifest?.widgetConfig?.widgetSdkVersion
+	}, ["先按当前工具链修复 Manifest 和 samples；adopt 不会迁移 SDK、源码或协议字段。"]);
+	const lock = await writeProjectToolchain(result.projectRoot, toolchain);
+	return {
+		...result,
+		lock
+	};
+}
+function digest(value) {
+	return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function receiptToolchain(toolchain) {
+	return {
+		cli: toolchain.cli,
+		profile: toolchain.profile,
+		digests: toolchain.digests
+	};
+}
+const IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".widget-build",
+	".widget-dev"
+]);
+async function fingerprint(root, { outputs = false } = {}) {
+	const files = [];
+	const walk = async (directory, prefix, ancestors) => {
+		const actualDirectory = await realpath(directory);
+		if (ancestors.has(actualDirectory)) throw new Error(`文件目录存在符号链接循环：${prefix}`);
+		const nextAncestors = /* @__PURE__ */ new Set([...ancestors, actualDirectory]);
+		const entries = await readdir(directory, { withFileTypes: true });
+		for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name, "en"))) {
+			const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+			if (IGNORED_DIRECTORIES.has(entry.name) || !outputs && !prefix && entry.name === "dist" || entry.name === "widget-toolchain.json" || entry.name === ".widget-build-receipt.json" || /\.zip$/iu.test(entry.name)) continue;
+			const path = join(directory, entry.name);
+			const metadata = await stat(path);
+			if (metadata.isDirectory()) await walk(path, relativePath, nextAncestors);
+			else if (metadata.isFile()) files.push({
+				path: relativePath,
+				sha256: digest(await readFile(path))
+			});
+		}
+	};
+	await walk(outputs ? join(root, "dist") : root, "", /* @__PURE__ */ new Set());
+	return {
+		digest: digest(JSON.stringify(files)),
+		files
+	};
+}
+async function captureBuildInputs(projectRoot) {
+	return fingerprint(resolve(projectRoot));
+}
+async function writeBuildReceipt(projectRoot, toolchain, { inputsBefore } = {}) {
+	const result = await validateProjectToolchain(projectRoot, toolchain);
+	const inputs = await fingerprint(result.projectRoot);
+	if (inputsBefore && inputsBefore.digest !== inputs.digest) throw failure("BUILD_RECEIPT_MISMATCH", "构建期间源输入发生变化，不能确认产物对应当前工程", { projectRoot: result.projectRoot }, ["保存工程文件后重新执行 bohr-widget build；构建结束前不要继续修改输入文件。"]);
+	const outputs = await fingerprint(result.projectRoot, { outputs: true });
+	if (outputs.files.length === 0) throw failure("BUILD_RECEIPT_MISMATCH", "构建目录 dist 没有可记录的产物", { projectRoot: result.projectRoot }, ["执行标准 build，确认 dist 产物存在后再打包。"]);
+	const receipt = {
+		formatVersion: 1,
+		toolchain: receiptToolchain(toolchain),
+		dependencies: result.installed,
+		inputs,
+		outputs
+	};
+	await writeFile(join(result.projectRoot, BUILD_RECEIPT_FILE), `${JSON.stringify(receipt, null, 2)}\n`);
+	return receipt;
+}
+async function assertBuildReceipt(projectRoot, toolchain) {
+	const root = resolve(projectRoot);
+	const mismatch = (reason, context = {}) => {
+		throw failure("BUILD_RECEIPT_MISMATCH", `不能复用构建产物：${reason}`, {
+			projectRoot: root,
+			...context
+		}, ["重新执行 bohr-widget build 或去掉 pack 的 --no-build。"]);
+	};
+	const receipt = await json(join(root, BUILD_RECEIPT_FILE), "BUILD_RECEIPT_MISMATCH", ["先执行 bohr-widget build，或去掉 pack 的 --no-build。"]);
+	const project = await validateProjectToolchain(root, toolchain);
+	if (!record(receipt) || receipt.formatVersion !== 1 || JSON.stringify(receipt.toolchain) !== JSON.stringify(receiptToolchain(toolchain)) || JSON.stringify(receipt.dependencies) !== JSON.stringify(project.installed)) mismatch("receipt 工具链或实际依赖与本次执行不一致");
+	let inputs;
+	let outputs;
+	try {
+		inputs = await fingerprint(root);
+		outputs = await fingerprint(root, { outputs: true });
+	} catch (error) {
+		mismatch("无法读取构建输入或 dist", { cause: error.message });
+	}
+	if (receipt.inputs?.digest !== inputs.digest || receipt.outputs?.digest !== outputs.digest || outputs.files.length === 0) mismatch("源文件或 dist 内容已变化");
+	return receipt;
+}
+//#endregion
+//#region src/templates.mjs
+const GENERATED_PROJECT_NODE = "^22.18.0 || >=24.11.0";
+function projectPackage({ name, ui, cliVersion, sdkVersion, contractsVersion }) {
+	return {
+		name: `@dp-bohrium/widget-example-${name}`,
+		private: true,
+		type: "module",
+		engines: { node: GENERATED_PROJECT_NODE },
+		scripts: {
+			build: "tsc --noEmit && tsdown && node scripts/rename-iife.mjs",
+			check: "bohr-widget check .",
+			"widget:pack": "bohr-widget pack ."
+		},
+		dependencies: {
+			"@dp-bohrium/widget-sdk": sdkVersion,
+			...ui === "react" ? {
+				react: "^19.0.0",
+				"react-dom": "^19.0.0"
+			} : {}
+		},
+		devDependencies: {
+			"@dp-bohrium/widget-cli": cliVersion,
+			"@dp-bohrium/widget-contracts": contractsVersion,
+			tsdown: "0.22.14",
+			typescript: "5.9.3",
+			...ui === "react" ? {
+				"@types/react": "^19.0.0",
+				"@types/react-dom": "^19.0.0"
+			} : {}
+		}
+	};
+}
+function projectReadme({ name, template, ui, sourceFile, hostFile }) {
+	return `# ${name}
+
+Bohrium Widget ${template} 插件工程（${ui}）。
+
+默认构建器要求 Node.js \`${GENERATED_PROJECT_NODE}\`，高于 CLI 自身的 Node.js 20 要求。
+工程已经精确依赖创建它的 CLI 版本；在本目录安装后使用本地命令，无需全局安装或源码仓库。
+
+\`\`\`bash
+pnpm install
+pnpm exec bohr-widget build . --json
+pnpm exec bohr-widget check . --json
+pnpm run widget:pack --json
+\`\`\`
+
+使用 npm 时，安装后可执行 \`npm run build\`、\`npm run check\`、\`npm run widget:pack\`；需要构建 receipt 时执行 \`npx --no-install bohr-widget build .\`。
+Widget ZIP 使用 \`pnpm run widget:pack\` 或 \`npm run widget:pack\`；\`pnpm pack\` 是制作 npm \`.tgz\` 包的内置命令。
+
+- 源码入口：${sourceFile}，由 ${hostFile} 调用 SDK 的 runWidgetHost 启动。
+- 高度链、布局与滚动策略直接写在 ${sourceFile} 中，样式随 activate 安装并在释放时清理；JSON 展示元素单独处理换行。
+- manifest.json 是作者清单，打包时由 CLI 编译为宿主清单。
+- 提交 widget-toolchain.json 与依赖 lockfile；dist/widget.js 与生成的 ZIP 不提交。
+- check 只验证结构、声明和样例，不执行 JavaScript；pack 成功不代表首帧渲染、真实授权或业务验收成功。
+- 上传前至少运行首帧、一次事件后再 render、空数据、缺授权和尺寸/主题更新，并检查滚动区域实际可见。
+- 本地开发连接使用 \`pnpm exec bohr-widget dev . --open --watch\`，需要已安装且支持开发接入的目标 Host。
+
+通过 \`pnpm exec bohr-widget integration --project . --json\` 查看工具链和公开文档地址。
+本地创建、构建、校验与打包无需平台登录；平台上传和绑定由目标平台提供。
+`;
+}
+function layoutSource() {
+	return `  // 在作者源码中维护高度链与滚动策略，随本次 activate 一起释放。
+  const style = document.createElement("style");
+  style.textContent = \`
+* { box-sizing: border-box; }
+html, body { height: 100%; min-height: 0; margin: 0; }
+body { font-family: system-ui, sans-serif; overflow: hidden; }
+.widget-root { height: 100%; min-height: 0; min-width: 0; display: flex; flex-direction: column; overflow: hidden; }
+.widget-json { flex: 1; min-height: 0; min-width: 0; margin: 0; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
+\`;
+  document.head.append(style);
+  context.subscriptions.add(() => style.remove());
+`;
+}
+function reactSource({ reportSize = false } = {}) {
+	const resizeState = reportSize ? "\n  let resized = false;" : "";
+	const resizeCall = reportSize ? `
+    if (!resized) {
+      context.resize(640, 360);
+      resized = true;
+    }` : "";
+	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={{ flex: 1, minHeight: 0, minWidth: 0, display: "flex", flexDirection: "column", padding: 20 }}>
+      <h1 style={{ flexShrink: 0 }}>Widget 面板</h1>
+      <pre className="widget-json">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </main>
+  );
+}
+
+function activate(context: WidgetContext) {
+${layoutSource()}  const host = document.createElement("div");
+  host.className = "widget-root";
+  document.body.replaceChildren(host);
+  const root = createRoot(host);
+  let renderRequest: RenderRequest | undefined;${resizeState}
+  const render = () => root.render(<WidgetView request={renderRequest} />);
+  render();
+  context.render((request) => {
+    document.body.style.background = request.context.theme.tokens.background;
+    document.body.style.color = request.context.theme.tokens.foreground;
+    renderRequest = request;
+    render();${resizeCall}
+  });
+  context.subscriptions.add(() => {
+    root.unmount();
+    host.remove();
+  });
+}
+
+export { activate };
+`;
+}
+function hostSource({ sourceFile }) {
+	return `import { runWidgetHost } from "@dp-bohrium/widget-sdk";
+import * as widget from "./${sourceFile.split("/").at(-1)}";
+
+runWidgetHost(widget, {
+  events: { onError: (error) => console.error("Widget 协议错误", error) },
+  onStartupError: (error) => {
+    document.body.textContent = "Widget 初始化失败：" + error.message;
+    console.error("Widget 初始化失败", error);
+  },
+});
+`;
+}
+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) {
+${layoutSource()}  const root = document.createElement("main");
+  root.className = "widget-root";
+  root.style.padding = "20px";
+  const display = document.createElement("pre");
+  display.className = "widget-json";
+  display.textContent = "等待 Host 提供面板数据";
+  root.append(display);
+  document.body.replaceChildren(root);
+  context.subscriptions.add(() => root.remove());
+  context.render((request) => {
+    document.body.style.background = request.context.theme.tokens.background;
+    document.body.style.color = request.context.theme.tokens.foreground;
+    const content = request.content;
+    display.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) {
+${layoutSource()}  const root = document.createElement("main");
+  root.className = "widget-root";
+  root.style.padding = "20px";
+  const display = document.createElement("pre");
+  display.className = "widget-json";
+  root.append(display);
+  document.body.replaceChildren(root);
+  context.subscriptions.add(() => root.remove());
+  let resized = false;
+  context.render((request) => {
+    document.body.style.background = request.context.theme.tokens.background;
+    document.body.style.color = request.context.theme.tokens.foreground;
+    display.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/toolchain.mjs
+/** Both src/ and the published dist/ locate resources in this package. */
+function getAssetRoot() {
+	return fileURLToPath(new URL("../assets/", import.meta.url));
+}
+function getToolchain() {
+	const path = join(getAssetRoot(), "toolchain.json");
+	if (!existsSync(path)) throw new Error("缺少 Widget CLI 工具链资产；源码运行前请执行 pnpm --filter @dp-bohrium/widget-cli build:assets，发布包请重新安装。");
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+function getDocumentation() {
+	return getToolchain().documentation;
+}
+function getSchemaPath(name = "widget-manifest.schema.json") {
+	if (name !== basename(name) || !name.endsWith(".schema.json")) throw new Error(`不支持的 Schema 名称：${name}`);
+	const path = join(getAssetRoot(), "schemas", name);
+	if (!existsSync(path)) throw new Error(`Widget CLI Schema 不存在：${name}`);
+	return path;
+}
+//#endregion
+//#region src/cli.mjs
+const toolchain = getToolchain();
+const packageJson = { version: toolchain.cli };
+const sdkPackage = { version: toolchain.profile.sdk };
+const contractsPackage = { version: toolchain.profile.contracts };
+function usage(path = []) {
+	return renderHelp(path, {
+		cli: packageJson.version,
+		sdk: sdkPackage.version,
+		contracts: contractsPackage.version,
+		documentation: getDocumentation(),
+		generatedProjectNode: GENERATED_PROJECT_NODE
+	});
+}
+function requestedHelpPath(argv) {
+	const hasHelpFlag = argv.includes("--help") || argv.includes("-h");
+	if (argv.length > 0 && argv[0] !== "help" && !hasHelpFlag) return null;
+	const args = argv.filter((arg) => arg !== "--help" && arg !== "-h");
+	if (args[0] === "help") {
+		if (args.length === 1 && hasHelpFlag) return ["help"];
+		args.shift();
+	}
+	const command = args[0];
+	if (!command || command.startsWith("-")) return [];
+	if (command !== "migrate") return [command];
+	let positional;
+	try {
+		positional = parseOptions(args.slice(1)).positional;
+	} catch {
+		positional = args.slice(1).filter((arg) => !arg.startsWith("-"));
+	}
+	return [command, ...positional.slice(0, 2)];
+}
+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,
+		hostCompat: void 0,
+		project: 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 === "--host-compat" || argument === "--project") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) throw new Error(`${argument} 需要路径`);
+			if (argument === "--host-compat") options.hostCompat = value;
+			else options.project = value;
+		} 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: {
+			...context,
+			...error?.context
+		},
+		recovery: error?.recovery ?? commandRecovery(command, error)
+	});
+}
+async function projectPreflight(projectRoot, options = {}) {
+	const hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+	const project = await validateProjectToolchain(projectRoot, toolchain);
+	return {
+		profile: toolchain.profile,
+		hostCompatibility,
+		project
+	};
+}
+async function commandIntegration(options) {
+	const hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+	const project = options.project ? await validateProjectToolchain(resolve(options.project), toolchain, { requireInstalled: existsSync(join(resolve(options.project), "node_modules")) }) : void 0;
+	const result = {
+		ok: true,
+		command: "integration",
+		interfaceVersion: 2,
+		requirements: {
+			node: ">=20",
+			generatedProjectNode: GENERATED_PROJECT_NODE
+		},
+		execution: {
+			executable: process.execPath,
+			entry: fileURLToPath(import.meta.url)
+		},
+		profile: toolchain.profile,
+		toolchain,
+		assetRoot: getAssetRoot(),
+		documentation: getDocumentation(),
+		hostCompatibility,
+		...project ? { project } : {}
+	};
+	if (options.json) console.log(JSON.stringify(result, null, 2));
+	else console.log(`${toolchain.profile.id}\n${result.documentation.url}`);
+	return result;
+}
+async function commandAdopt(directory, options) {
+	if (!directory) throw new Error("adopt 需要工程目录");
+	const hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+	const projectRoot = resolve(directory);
+	const project = await adoptProjectToolchain(projectRoot, toolchain);
+	const result = {
+		ok: true,
+		command: "adopt",
+		projectRoot,
+		profile: toolchain.profile,
+		project,
+		hostCompatibility
+	};
+	if (options.json) console.log(JSON.stringify(result, null, 2));
+	else console.log(`已锁定工程工具链：${toolchain.profile.id}`);
+	return result;
+}
+/**
+* 目录名 → 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) {
+	const hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+	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.widget-build-receipt.json\n*.zip\n");
+	await writeFile(join(root, "README.md"), projectReadme({
+		name,
+		template: options.template,
+		ui: options.ui,
+		sourceFile,
+		hostFile
+	}));
+	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(projectPackage({
+		name,
+		ui: options.ui,
+		cliVersion: packageJson.version,
+		sdkVersion: sdkPackage.version,
+		contractsVersion: contractsPackage.version
+	}), null, 2)}\n`);
+	const warnings = [];
+	await writeProjectToolchain(root, toolchain);
+	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"),
+		profile: toolchain.profile,
+		hostCompatibility,
+		...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(`下一步：cd ${JSON.stringify(root)}，执行 pnpm install，再执行 pnpm exec bohr-widget build . --json 和 pnpm exec bohr-widget check . --json。`);
+	}
+	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 {
+			try {
+				const compatibility = await projectPreflight(project, options);
+				result = {
+					...applyCliProjectPolicies(await checkWidgetProject(project, {
+						label,
+						toolchain: { sdkVersion: toolchain.profile.sdk }
+					})),
+					...compatibility
+				};
+			} catch (error) {
+				result = {
+					ok: false,
+					label,
+					projectRoot: project,
+					checks: [{
+						name: "工程工具链与宿主兼容检查",
+						ok: false
+					}],
+					errors: [error.message],
+					compatibilityError: commandError(commandName, error, { projectRoot: project })
+				};
+			}
+			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: result.compatibilityError ?? 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(stderr, stdout) {
+	const lines = [stderr, stdout].flatMap((output) => 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, 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 compatibility = await projectPreflight(root, options);
+		await rm(join(root, BUILD_RECEIPT_FILE), { force: true });
+		const inputsBefore = await captureBuildInputs(root);
+		const build = await runProjectBuild(root, { capture: true });
+		await validateProjectToolchain(root, toolchain);
+		const receipt = await writeBuildReceipt(root, toolchain, { inputsBefore });
+		const result = {
+			ok: true,
+			command: "build",
+			projectRoot: root,
+			stdout: build.stdout,
+			stderr: build.stderr,
+			...compatibility,
+			hostCompatibility: await assertHostCompatibility(options.hostCompat, toolchain),
+			receipt
+		};
+		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;
+	}
+}
+const RUNTIME_MAX_ASSET_BYTES = 1048576;
+function oversizedAssetWarnings(files) {
+	const oversized = /* @__PURE__ */ new Map();
+	for (const [path, bytes] of files) if (bytes.byteLength > RUNTIME_MAX_ASSET_BYTES) oversized.set(normalizeArchivePath(path), bytes.byteLength);
+	return [...oversized].map(([path, size]) => `${path} 为 ${(size / 1048576).toFixed(2)} MiB（${size} 字节），超过 Widget Runtime 单资产 1 MiB 上限：上传 Shrimp 会被拒绝，云端也无法加载。请确认 tsdown.config.ts 已开启 minify: true，或拆分、移除体积较大的依赖。`);
+}
+async function commandPack(directory, options) {
+	if (!directory) throw new Error("pack 需要工程目录");
+	const root = resolve(directory);
+	const compatibility = await projectPreflight(root, options);
+	const lint = lintProjectManifest(root);
+	if (lint && !lint.ok) {
+		const error = new Error(lint.errors.join("\n"));
+		error.cliCode = "WIDGET_CLI_MANIFEST_INVALID";
+		throw error;
+	}
+	if (!options.build) await assertBuildReceipt(root, toolchain);
+	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,
+		toolchain: { sdkVersion: toolchain.profile.sdk }
+	}));
+	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 files = collectWidgetPackageFiles(result, { includePreviewFixtures: fixturesIncluded });
+	warnings.push(...oversizedAssetWarnings(files));
+	const bundle = storedZip(files);
+	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
+		},
+		...compatibility,
+		hostCompatibility: await assertHostCompatibility(options.hostCompat, toolchain),
+		manifest: {
+			name: result.manifest.name,
+			entry: normalizeArchivePath(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 hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+		const result = await scaffoldDshWidget(input, options.output, {
+			sdkVersion: sdkPackage.version,
+			contractsVersion: contractsPackage.version
+		});
+		await writeProjectToolchain(result.projectRoot, toolchain);
+		result.profile = toolchain.profile;
+		result.hostCompatibility = hostCompatibility;
+		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 = {
+		command: "doctor",
+		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;
+	report.profile = toolchain.profile;
+	report.toolchainLocked = existsSync(join(root, "widget-toolchain.json"));
+	report.hostCompatibility = await assertHostCompatibility(options.hostCompat, toolchain);
+	if (!report.toolchainLocked) {
+		report.ready = false;
+		report.warnings.push("工程尚未锁定工具链：安装依赖后执行 bohr-widget adopt .。");
+	}
+	if (report.packageJson) try {
+		report.projectToolchain = await validateProjectToolchain(root, toolchain, {
+			requireInstalled: report.dependenciesInstalled,
+			requireLock: false
+		});
+		const lint = lintProjectManifest(root);
+		const candidate = await checkWidgetProject(root, {
+			requireBuiltEntry: false,
+			toolchain: { sdkVersion: toolchain.profile.sdk }
+		});
+		if (lint && !lint.ok) candidate.errors.push(...lint.errors);
+		report.candidateProfile = candidate.ok && (!lint || lint.ok) ? toolchain.profile.id : null;
+		if (!report.candidateProfile) {
+			report.ok = false;
+			report.ready = false;
+			report.warnings.push(...candidate.errors);
+		}
+	} catch (error) {
+		report.ok = false;
+		report.ready = false;
+		report.error = commandError("doctor", error, { projectRoot: root });
+		report.warnings.push(error.message);
+	}
+	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(getSchemaPath("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) {
+	const helpPath = requestedHelpPath(argv);
+	if (helpPath !== null) return console.log(usage(helpPath));
+	if (argv.includes("--version") || argv.includes("-v")) return commandVersion({ json: argv.includes("--json") });
+	const command = argv[0] ?? "help";
+	if (command === "dev") {
+		const devArgs = [];
+		let hostCompat;
+		for (let index = 1; index < argv.length; index += 1) if (argv[index] === "--host-compat") {
+			hostCompat = argv[++index];
+			if (!hostCompat || hostCompat.startsWith("--")) throw new Error("--host-compat 需要声明文件路径");
+		} else devArgs.push(argv[index]);
+		const exitCode = await runWidgetDevelopmentCli(devArgs, {
+			beforeBuild: ({ projectRoot }) => projectPreflight(projectRoot, { hostCompat }),
+			buildProject: runProjectBuild,
+			checkProject: async (projectRoot, checkOptions) => {
+				await projectPreflight(projectRoot, { hostCompat });
+				const lint = lintProjectManifest(projectRoot);
+				if (lint && !lint.ok) {
+					const error = new Error(lint.errors.join("\n"));
+					error.cliCode = "WIDGET_CLI_MANIFEST_INVALID";
+					throw error;
+				}
+				return applyCliProjectPolicies(await checkWidgetProject(projectRoot, {
+					...checkOptions,
+					toolchain: { sdkVersion: toolchain.profile.sdk }
+				}));
+			},
+			manifestOptions: { sdkVersion: toolchain.profile.sdk }
+		});
+		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 === "version") return commandVersion(options);
+	if (command === "integration") return commandIntegration(options);
+	if (command === "adopt") return commandAdopt(positional[0], 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 {};