@dp-bohrium/widget-cli 0.1.0 → 0.2.0

package/dist/cli.mjs

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import { a as resolveWidgetProjects, i as checkWidgetProject, n as scaffoldDshWidget, o as compileAuthorManifest, r as buildWidgetPackage, t as auditDshPlugin } from "./dsh-DgkNH7L-.mjs";
-import { createRequire } from "node:module";
+import { 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, writeFile } from "node:fs/promises";
+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";
@@ -76,9 +75,9 @@ const RESOURCE_BUDGET = {
 	},
 	retry: {
 		maxAttempts: 1,
-		initialDelayMs: 0,
-		maxDelayMs: 0,
-		totalMs: 0
+		initialDelayMs: 250,
+		maxDelayMs: 1e3,
+		totalMs: 5e3
 	},
 	failure: {
 		consecutiveFailures: 3,
@@ -172,11 +171,15 @@ function parseArgs(argv) {
 	};
 }
 function createWidgetDevError(error, context = {}) {
+	const code = error?.cliCode ?? error?.code;
 	return {
-		code: typeof error?.code === "string" && error.code.startsWith("WIDGET_DEV_") ? error.code : "WIDGET_DEV_FAILED",
+		code: typeof code === "string" && /^(?:WIDGET_DEV_|WIDGET_CLI_)/u.test(code) ? code : "WIDGET_DEV_FAILED",
 		message: error instanceof Error ? error.message : String(error),
-		context,
-		recovery: context.phase === "watch-build" ? "读取 status.lastBuildError，修复工程后重新保存源码或重新执行 build。" : "先读取 error.context 和 build 输出，修复工程或宿主连接后重试。"
+		context: {
+			...context,
+			...error?.context
+		},
+		recovery: error?.recovery ?? (context.phase === "watch-build" ? "读取 status.lastBuildError，修复工程后重新保存源码或重新执行 build。" : "先读取 error.context 和 build 输出，修复工程或宿主连接后重试。")
 	};
 }
 function secureHeaders(contentType) {
@@ -187,7 +190,7 @@ function secureHeaders(contentType) {
 		"x-content-type-options": "nosniff"
 	};
 }
-function json(response, status, value, extraHeaders = {}) {
+function json$1(response, status, value, extraHeaders = {}) {
 	const body = JSON.stringify(value);
 	response.writeHead(status, {
 		...secureHeaders("application/json; charset=utf-8"),
@@ -406,9 +409,9 @@ function panelDevelopmentDescriptor(generation, profileUrl, statusUrl) {
 		presentationRequests
 	};
 }
-function readProject(projectRoot) {
+function readProject(projectRoot, manifestOptions = {}) {
 	const sourceManifest = JSON.parse(readFileSync(join(projectRoot, "manifest.json"), "utf8"));
-	const manifest = compileAuthorManifest(sourceManifest);
+	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`);
@@ -458,8 +461,8 @@ function collectGenerationAssets(projectRoot, entryPath, limits) {
 		};
 	}).sort((a, b) => a.path.localeCompare(b.path));
 }
-function createDevelopmentGeneration(projectRoot, number = 0, limits = GENERATION_LIMITS) {
-	const { manifest, entryPath } = readProject(projectRoot);
+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");
@@ -720,9 +723,28 @@ function runBuild(projectRoot, { capture = false } = {}) {
 	});
 }
 async function startWidgetDevelopment(projectRoot, options) {
+	const buildProject = options.buildProject ?? runBuild;
 	const emit = options.emit ?? ((line, error = false) => error ? console.error(line) : console.log(line));
-	if (options.build) await runBuild(projectRoot, { capture: options.json });
-	let successfulGeneration = createDevelopmentGeneration(projectRoot, 0);
+	const 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,
@@ -754,7 +776,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		for (const response of eventClients.keys()) response.write(frame);
 		if (options.json) emit(formatDevelopmentEvent(type, data), type === "generation-failed");
 	};
-	const unauthorized = (response) => json(response, 401, {
+	const unauthorized = (response) => json$1(response, 401, {
 		ok: false,
 		error: {
 			code: "WIDGET_DEV_UNAUTHORIZED",
@@ -798,14 +820,14 @@ async function startWidgetDevelopment(projectRoot, options) {
 			return;
 		}
 		if (url.pathname === DESCRIPTOR_PATH && request.method === "GET") {
-			json(response, 200, session.descriptor);
+			json$1(response, 200, session.descriptor);
 			return;
 		}
 		if (url.pathname === CLAIM_PATH && request.method === "POST") {
 			try {
-				json(response, 200, session.claim(bearer(request.headers.authorization)));
+				json$1(response, 200, session.claim(bearer(request.headers.authorization)));
 			} catch (error) {
-				json(response, 401, {
+				json$1(response, 401, {
 					ok: false,
 					error: {
 						code: "WIDGET_DEV_CLAIM_REJECTED",
@@ -820,7 +842,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			return;
 		}
 		if (url.pathname === V1_STATUS_PATH && request.method === "GET") {
-			json(response, 200, developmentSnapshot());
+			json$1(response, 200, developmentSnapshot());
 			return;
 		}
 		if (url.pathname === EVENTS_PATH && request.method === "GET") {
@@ -861,13 +883,13 @@ async function startWidgetDevelopment(projectRoot, options) {
 						sendEvent("disconnected", { reason: "host-request" });
 						session.disconnect();
 					} else sendEvent("reload-requested", { generation: state.generation });
-					json(response, 200, {
+					json$1(response, 200, {
 						ok: true,
 						protocolVersion: 1,
 						action: control.action
 					});
 				} catch (error) {
-					json(response, 400, {
+					json$1(response, 400, {
 						ok: false,
 						error: { message: String(error) }
 					});
@@ -881,7 +903,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			const panelId = url.searchParams.get("id");
 			const manifestContribution = successfulGeneration.manifest.widgetConfig.contribution;
 			if (!(!contribution || contribution === manifestContribution.type && (contribution !== "panel" || !panelId || panelId === manifestContribution.id))) {
-				json(response, 404, {
+				json$1(response, 404, {
 					ok: false,
 					error: {
 						code: "WIDGET_DEV_PROFILE_NOT_FOUND",
@@ -896,7 +918,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			}
 			const origin = `http://127.0.0.1:${server.address().port}`;
 			const launchUrl = `${origin}${guestGenerationRoot(successfulGeneration)}/launch.html`;
-			json(response, 200, createDevelopmentConfig({
+			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
 				runId,
 				origin,
@@ -908,7 +930,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		if (url.pathname === PROFILE_PATH) {
 			const runId = url.searchParams.get("runId") || "widget-dev-run";
 			const origin = `http://127.0.0.1:${server.address().port}`;
-			json(response, 200, createDevelopmentConfig({
+			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
 				runId,
 				origin,
@@ -918,7 +940,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			return;
 		}
 		if (url.pathname === STATUS_PATH) {
-			json(response, 200, {
+			json$1(response, 200, {
 				ok: state.phase === "ready",
 				command: "dev",
 				profile: PROFILE_PATH,
@@ -1021,8 +1043,14 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 		building = true;
 		try {
-			const build = await runBuild(projectRoot, { capture: options.json });
-			const candidate = createDevelopmentGeneration(projectRoot, successfulGeneration.number + 1);
+			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);
@@ -1103,15 +1131,22 @@ function emitCliEnvelope(type, data, error = false) {
 	if (error) console.error(line);
 	else console.log(line);
 }
-async function runWidgetDevelopmentCli(argv = process.argv.slice(2)) {
+async function runWidgetDevelopmentCli(argv = process.argv.slice(2), overrides = {}) {
 	try {
-		const options = parseArgs(argv);
+		const options = {
+			...parseArgs(argv),
+			...overrides
+		};
 		if (options.help) {
 			console.log(usage$1());
 			return 0;
 		}
 		const [projectRoot] = resolveWidgetProjects(options.project);
-		const check = await checkWidgetProject(projectRoot, { requireBuiltEntry: false });
+		const checkProject = options.checkProject ?? checkWidgetProject;
+		const check = await checkProject(projectRoot, {
+			...options.manifestOptions,
+			requireBuiltEntry: false
+		});
 		if (!check.ok) {
 			if (options.json) emitCliEnvelope("error", {
 				ok: false,
@@ -1130,7 +1165,10 @@ async function runWidgetDevelopmentCli(argv = process.argv.slice(2)) {
 			}
 			return 1;
 		}
-		await startWidgetDevelopment(projectRoot, options);
+		await startWidgetDevelopment(projectRoot, {
+			...options,
+			checkProject
+		});
 		return 0;
 	} catch (error) {
 		if (argv.includes("--json")) emitCliEnvelope("error", {
@@ -1143,6 +1181,334 @@ async function runWidgetDevelopmentCli(argv = process.argv.slice(2)) {
 	}
 }
 //#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` 清单）的本地静态检查。
@@ -1233,8 +1599,371 @@ function lintAuthorManifest(manifest, options = {}) {
 	};
 }
 //#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";
@@ -1242,9 +1971,9 @@ import type { RenderRequest } from "@dp-bohrium/widget-contracts";
 function WidgetView({ request }: { request?: RenderRequest }) {
   const data = request?.content ?? { state: "等待 Host 提供数据" };
   return (
-    <main style={{ fontFamily: "system-ui", padding: 20 }}>
-      <h1>Widget 面板</h1>
-      <pre style={{ whiteSpace: "pre-wrap" }}>
+    <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>
@@ -1252,21 +1981,23 @@ function WidgetView({ request }: { request?: RenderRequest }) {
 }
 
 function activate(context: WidgetContext) {
-  const host = document.createElement("main");
+${layoutSource()}  const host = document.createElement("div");
+  host.className = "widget-root";
   document.body.replaceChildren(host);
   const root = createRoot(host);
-  let renderRequest: RenderRequest | undefined;${reportSize ? "\n  let resized = false;" : ""}
+  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();${reportSize ? `
-    if (!resized) {
-      context.resize(640, 360);
-      resized = true;
-    }` : ""}
+    render();${resizeCall}
+  });
+  context.subscriptions.add(() => {
+    root.unmount();
+    host.remove();
   });
-  context.subscriptions.add(() => root.unmount());
 }
 
 export { activate };
@@ -1276,7 +2007,13 @@ function hostSource({ sourceFile }) {
 	return `import { runWidgetHost } from "@dp-bohrium/widget-sdk";
 import * as widget from "./${sourceFile.split("/").at(-1)}";
 
-runWidgetHost(widget);
+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({
@@ -1307,12 +2044,20 @@ const TEMPLATES = Object.freeze({
 		source: `import type { WidgetContext } from "@dp-bohrium/widget-sdk";
 
 function activate(context: WidgetContext) {
-  const root = document.createElement("main");
-  root.textContent = "等待 Host 提供面板数据";
+${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;
-    root.textContent = JSON.stringify(
+    display.textContent = JSON.stringify(
       "data" in content ? content.data : content,
       null,
       2,
@@ -1405,11 +2150,19 @@ export { activate };
 		source: `import type { WidgetContext } from "@dp-bohrium/widget-sdk";
 
 function activate(context: WidgetContext) {
-  const root = document.createElement("main");
+${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) => {
-    root.textContent = JSON.stringify(request.content ?? {}, null, 2);
+    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;
@@ -1466,43 +2219,58 @@ export { activate };
 	}
 });
 //#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 require = createRequire(import.meta.url);
-const packageJson = require("../package.json");
-const sdkPackage = require("@dp-bohrium/widget-sdk/package.json");
-const contractsPackage = require("@dp-bohrium/widget-contracts/package.json");
-const COMMANDS = [
-	"create",
-	"check",
-	"validate",
-	"build",
-	"dev",
-	"pack",
-	"doctor",
-	"schema",
-	"migrate",
-	"version",
-	"help"
-];
-function usage() {
-	return `bohr-widget — Bohrium Widget 插件工具
-
-用法：
-  bohr-widget create <目录> [--template panel|file-preview] [--ui vanilla|react] [--panel-id <id>]
-  bohr-widget check <目录|manifest.json|all> [--json]
-  bohr-widget validate <目录|manifest.json|all> [--json]
-  bohr-widget build <目录> [--json]
-  bohr-widget dev <目录> [--open] [--watch] [--no-build] [--json] [--port <端口>] [--scheme <scheme>] [--bridge <url>]
-  bohr-widget pack <目录> [--out <zip>] [--include-preview-fixtures] [--no-build] [--json]
-  bohr-widget doctor [目录] [--json]
-  bohr-widget schema
-  bohr-widget migrate dsh audit <plugin-dir> [--json]
-  bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [--json]
-  bohr-widget version [--json]
-  bohr-widget help | -h | --help
-
---json 只输出一个 JSON 文档；check all --json 输出 checked/passed/failed/results[] 汇总。
-`;
+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 = [];
@@ -1518,7 +2286,9 @@ function parseOptions(argv) {
 		port: 4300,
 		scheme: "widget-host",
 		bridge: null,
-		panelId: void 0
+		panelId: void 0,
+		hostCompat: void 0,
+		project: void 0
 	};
 	for (let index = 0; index < argv.length; index += 1) {
 		const argument = argv[index];
@@ -1537,7 +2307,12 @@ function parseOptions(argv) {
 			options.output = argv[++index];
 			if (!options.output) throw new Error("--out 需要输出路径");
 		} else if (argument === "--open") options.open = true;
-		else if (argument === "--watch") options.watch = true;
+		else if (argument === "--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];
@@ -1585,10 +2360,65 @@ function commandError(command, error, context = {}) {
 	return structuredError({
 		code: typeof error?.cliCode === "string" ? error.cliCode : typeof error?.code === "string" && error.code.startsWith("WIDGET_") ? error.code : `WIDGET_CLI_${commandCode(command)}_FAILED`,
 		message: error instanceof Error ? error.message : String(error),
-		context,
-		recovery: commandRecovery(command, error)
+		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 会直接违反作者清单契约。
@@ -1599,6 +2429,7 @@ function deriveWidgetName(directoryName) {
 	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}`);
@@ -1632,22 +2463,14 @@ async function commandCreate(directory, options) {
 	await writeFile(join(root, sourceFile), source);
 	await writeFile(join(root, hostFile), template.hostSource({ sourceFile }));
 	await writeFile(join(root, "scripts/rename-iife.mjs"), `import { rename } from "node:fs/promises";\n\nawait rename("dist/widget.iife.js", "dist/widget.js");\n`);
-	await writeFile(join(root, ".gitignore"), "node_modules/\ndist/\n.artifacts/\n*.zip\n");
-	await writeFile(join(root, "README.md"), `# ${name}
-
-Bohrium Widget ${options.template} 插件工程（${options.ui}）。
-
-\`\`\`bash
-pnpm install
-pnpm build
-bohr-widget check .
-bohr-widget pack .
-\`\`\`
-
-- 源码入口：${sourceFile}，由 ${hostFile} 调用 SDK 的 runWidgetHost 启动
-- manifest.json 是作者清单，打包时由 CLI 编译为宿主清单
-- 构建产物 dist/widget.js 不提交到版本库
-`);
+	await writeFile(join(root, ".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",
@@ -1663,29 +2486,15 @@ bohr-widget pack .
 		include: ["src"]
 	}, null, 2)}\n`);
 	await writeFile(join(root, "tsdown.config.ts"), `import { defineConfig } from "tsdown";\n\nexport default defineConfig({\n  entry: { widget: "${hostFile}" },\n  format: ["iife"],\n  platform: "browser",\n  target: "es2022",\n  ${options.ui === "react" ? "jsx: \"automatic\"," : ""}\n  dts: false,\n  outDir: "dist",\n  outExtensions: () => ({ js: ".js" }),\n  clean: true,\n  sourcemap: false,\n  minify: true,\n  deps: {\n    alwaysBundle: ["@dp-bohrium/widget-sdk"${options.ui === "react" ? ", \"react\", \"react-dom\", \"react-dom/client\", \"react/jsx-runtime\"" : ""}],\n    onlyBundle: false,\n  },\n});\n`);
-	await writeFile(join(root, "package.json"), `${JSON.stringify({
-		name: `@dp-bohrium/widget-example-${name}`,
-		private: true,
-		type: "module",
-		scripts: { build: "tsc --noEmit && tsdown && node scripts/rename-iife.mjs" },
-		dependencies: {
-			"@dp-bohrium/widget-sdk": sdkPackage.version,
-			...options.ui === "react" ? {
-				react: "^19.0.0",
-				"react-dom": "^19.0.0"
-			} : {}
-		},
-		devDependencies: {
-			"@dp-bohrium/widget-contracts": contractsPackage.version,
-			tsdown: "0.22.14",
-			typescript: "5.9.3",
-			...options.ui === "react" ? {
-				"@types/react": "^19.0.0",
-				"@types/react-dom": "^19.0.0"
-			} : {}
-		}
-	}, null, 2)}\n`);
+	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 = {
@@ -1699,13 +2508,15 @@ bohr-widget pack .
 		...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("下一步：pnpm install && pnpm build && bohr-widget check .");
+		console.log(`下一步：cd ${JSON.stringify(root)}，执行 pnpm install，再执行 pnpm exec bohr-widget build . --json 和 pnpm exec bohr-widget check . --json。`);
 	}
 	return result;
 }
@@ -1841,7 +2652,28 @@ async function commandCheck(input, options, commandName = "check") {
 			projectRoot: project
 		};
 		else {
-			result = applyCliProjectPolicies(await checkWidgetProject(project, { label }));
+			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。"];
 		}
@@ -1850,7 +2682,7 @@ async function commandCheck(input, options, commandName = "check") {
 		if (input !== "all") printResult(options.json ? {
 			command: commandName,
 			...result,
-			...result.ok ? {} : { error: structuredError({
+			...result.ok ? {} : { error: result.compatibilityError ?? structuredError({
 				code: result.lintErrors ? "WIDGET_CLI_MANIFEST_INVALID" : "WIDGET_CLI_VALIDATION_FAILED",
 				message: "Widget 工程校验失败。",
 				context: {
@@ -1914,9 +2746,9 @@ function detectPackageManager(root, projectPackage) {
 	for (const [lockfile, manager] of LOCKFILE_MANAGERS) if (existsSync(join(root, lockfile))) return manager;
 	return "npm";
 }
-function firstFailureLine(output) {
-	const lines = String(output ?? "").split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
-	const line = lines.find((item) => !/^(?:npm|pnpm|yarn)\s+(?:warn|warning)\b/iu.test(item)) ?? lines[0];
+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 = [
@@ -1969,7 +2801,7 @@ async function runProjectBuild(root, { capture = false } = {}) {
 				Object.assign(error, result, { cliCode: "WIDGET_CLI_BUILD_UNRESOLVED_IMPORT" });
 				reject(error);
 			} else {
-				const detail = firstFailureLine(stderr) ?? firstFailureLine(stdout);
+				const detail = firstFailureLine(stderr, stdout);
 				const error = /* @__PURE__ */ new Error(`构建失败（exit ${code ?? signal ?? "unknown"}）${detail ? `：${detail}` : ""}`);
 				Object.assign(error, result);
 				reject(error);
@@ -1981,13 +2813,21 @@ 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
+			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) {
@@ -2017,8 +2857,23 @@ async function commandBuild(directory, options = {}) {
 		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,
@@ -2038,7 +2893,10 @@ async function commandPack(directory, options) {
 			return build;
 		}
 	}
-	const result = applyCliProjectPolicies(await checkWidgetProject(resolve(directory), { requireBuiltEntry: true }));
+	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({
@@ -2071,7 +2929,9 @@ async function commandPack(directory, options) {
 	const warnings = [];
 	if (options.includePreviewFixtures && !hasFixtures) warnings.push("使用了 --include-preview-fixtures，但 preview/fixtures.json 不存在，ZIP 未包含任何 fixtures。");
 	else if (hasFixtures && !options.includePreviewFixtures) warnings.push("工程包含 preview/fixtures.json，未使用 --include-preview-fixtures，ZIP 未包含 fixtures。");
-	const bundle = buildWidgetPackage(result, { includePreviewFixtures: fixturesIncluded });
+	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 = {
@@ -2086,9 +2946,11 @@ async function commandPack(directory, options) {
 			sdk: sdkPackage.version,
 			contracts: contractsPackage.version
 		},
+		...compatibility,
+		hostCompatibility: await assertHostCompatibility(options.hostCompat, toolchain),
 		manifest: {
 			name: result.manifest.name,
-			entry: result.manifest.widgetConfig.entry,
+			entry: normalizeArchivePath(result.manifest.widgetConfig.entry),
 			contribution: result.manifest.widgetConfig.contribution,
 			sampleIds: (result.manifest.widgetConfig.samples ?? []).map((sample) => sample.id)
 		},
@@ -2124,10 +2986,14 @@ async function commandMigrate(positional, options) {
 	}
 	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;
@@ -2139,6 +3005,7 @@ async function commandDoctor(directory, options) {
 	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,
@@ -2164,6 +3031,36 @@ async function commandDoctor(directory, options) {
 	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 脚本。`);
@@ -2176,7 +3073,7 @@ async function commandDoctor(directory, options) {
 	if (!report.ok) process.exitCode = 1;
 }
 function commandSchema() {
-	console.log(require.resolve("@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json"));
+	console.log(getSchemaPath("widget-plugin-manifest.schema.json"));
 }
 function commandVersion(options) {
 	const result = {
@@ -2191,17 +3088,43 @@ function commandVersion(options) {
 	return result;
 }
 async function main(argv) {
-	if (argv.includes("--help") || argv.includes("-h")) return console.log(usage());
+	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 exitCode = await runWidgetDevelopmentCli(argv.slice(1));
+		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 === "help") return console.log(usage());
 	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);