@dp-bohrium/widget-cli 0.3.0 → 0.5.0

package/dist/cli.mjs

@@ -1,12 +1,13 @@
 #!/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-DbOeoKFJ.mjs";
+import { a as normalizeArchivePath, c as compileAuthorManifest, i as prepareWidgetPackage, n as scaffoldDshWidget, o as checkWidgetProject, s as resolveWidgetProjects, t as auditDshPlugin } from "./dsh-BkPMTfZ_.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 { constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
+import { isDeepStrictEqual } from "node:util";
 //#region ../../scripts/widget/widget-dev.mjs
 const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const DEFAULT_PORT = 4300;
@@ -56,7 +57,6 @@ const RESOURCE_BUDGET = {
 	},
 	files: {
 		readBytesPerRequest: 4194304,
-		readBytesPerRun: 16777216,
 		callsPerMinute: 120,
 		listPageSize: 100
 	},
@@ -285,7 +285,6 @@ function requestedGrants(requested = {}) {
 		name: "files.read",
 		limits: {
 			bytesPerRequest: 4194304,
-			bytesPerRun: 16777216,
 			callsPerMinute: 120
 		}
 	});
@@ -383,7 +382,7 @@ function panelDevelopmentDescriptor(generation, profileUrl, statusUrl) {
 		widgetId,
 		widgetVersionId,
 		snapshot: {
-			id,
+			panelType: id,
 			title: generation.manifest.name,
 			state: "complete",
 			data: {}
@@ -1126,9 +1125,10 @@ async function startWidgetDevelopment(projectRoot, options) {
 		session
 	};
 }
-function emitCliEnvelope(type, data, error = false) {
+function emitCliEnvelope(type, data, error = false, emit) {
 	const line = formatDevelopmentEvent(type, data);
-	if (error) console.error(line);
+	if (emit) emit(line, error);
+	else if (error) console.error(line);
 	else console.log(line);
 }
 async function runWidgetDevelopmentCli(argv = process.argv.slice(2), overrides = {}) {
@@ -1156,7 +1156,7 @@ async function runWidgetDevelopmentCli(argv = process.argv.slice(2), overrides =
 					projectRoot,
 					errors: check.errors
 				})
-			});
+			}, false, overrides.emit);
 			else {
 				console.error("Widget Dev 启动前 L0 check 失败：");
 				check.errors.forEach((error) => {
@@ -1175,7 +1175,7 @@ async function runWidgetDevelopmentCli(argv = process.argv.slice(2), overrides =
 			ok: false,
 			command: "dev",
 			error: createWidgetDevError(error, { input: argv[0] ?? null })
-		});
+		}, false, overrides.emit);
 		else console.error(`${String(error)}\n\n${usage$1()}`);
 		return 1;
 	}
@@ -1215,10 +1215,16 @@ function commandTopics(context) {
 		]
 	});
 	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> [选项]"],
+		description: "只读比较来源与 Agent 准备的当前工程候选，再安全复制到新目录；另提供 DSH 来源审计与脚手架。",
+		usage: [
+			"bohr-widget migrate project plan <source> [--candidate <候选目录>] --json",
+			"bohr-widget migrate project apply <source> --plan <plan.json> --out <新目录> --json",
+			"bohr-widget migrate dsh audit <plugin-dir> [选项]",
+			"bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [选项]"
+		],
 		arguments: [
-			"dsh                         当前唯一支持的迁移来源",
+			"project                     比较已准备候选，再按摘要绑定的计划创建新工程",
+			"dsh                         已审查来源的审计与脚手架",
 			"audit                       只读审计来源、指纹和能力缺口",
 			"scaffold                    使用匹配的已审查配方创建新工程"
 		],
@@ -1230,7 +1236,32 @@ function commandTopics(context) {
 			"使用 bohr-widget migrate dsh <audit|scaffold> --help 查看详细参数。"
 		]
 	};
+	const projectMigration = (action) => ({
+		description: action === "apply" ? "重新核对已审阅计划、来源、候选和目标摘要，在新目录复制已准备候选。" : "只读比较完整来源和独立准备的候选，列出全部文件变更、阻断与人工步骤。",
+		usage: [action === "apply" ? `bohr-widget migrate project apply <source> --plan <plan.json> --out <新目录> [选项]` : `bohr-widget migrate project plan <source> [选项]`],
+		arguments: ["source                      必填；完整作者源码目录；只作为数据，不选择或执行旧工具链"],
+		options: [...action === "apply" ? [
+			"--plan <plan.json>          必填；plan --json 保存的完整对象",
+			"--out <新目录>              必填；与来源和候选目录树分离，不覆盖已有目录",
+			HOST_OPTION
+		] : ["--candidate <候选目录>      Agent 或开发者依据当前 SDK 独立准备的当前工程；不提供时 canApply=false"], JSON_OPTION],
+		examples: [action === "apply" ? `bohr-widget migrate project apply ./old-widget --plan ./plan.json --out ./new-widget --json` : `bohr-widget migrate project plan ./source --candidate ./prepared-current-project --json > plan.json`],
+		notes: [
+			"plan 的 ok 表示报告生成成功；只有 canApply=true 且 blockers 为空才能 apply。",
+			"没有自动版本转换或源码 codemod；Agent 先依据 SDK 模板、示例和文档准备并审阅独立候选。",
+			"不提供候选时只给准备步骤且 canApply=false；ZIP/编译产物需要先提供完整作者源码。",
+			"apply 只从计划读取候选路径，不接受 --candidate 覆盖；重算完整计划并核验来源/候选/目标摘要。",
+			"不执行任何来源或候选脚本；原字节复制候选源码、配置和依赖锁，校验仅覆盖结构与依赖声明。",
+			"复制结果仍须安装依赖、build、check、pack 与真实 Host 验收；不复用安装、构建产物或旧 receipt。"
+		]
+	});
 	return {
+		"migrate project": {
+			...projectMigration("plan"),
+			usage: ["bohr-widget migrate project plan|apply <source> [选项]"]
+		},
+		"migrate project plan": projectMigration("plan"),
+		"migrate project apply": projectMigration("apply"),
 		create: {
 			description: "创建可独立安装、构建和打包的 Widget 工程，生成源码、样例和工具链锁定文件。",
 			usage: ["bohr-widget create <目录> [选项]"],
@@ -1239,10 +1270,16 @@ function commandTopics(context) {
 				"--template <模板>           panel 或 file-preview（默认 panel）",
 				"--ui <模式>                 vanilla 或 react（默认 vanilla）",
 				"--panel-id <id>             仅用于 panel；默认取规范化后的工程名",
+				"--extensions <列表>         仅用于 file-preview；逗号分隔扩展名（默认 txt）",
+				"--tool <名称>               按指定工具成功结果激活，不注册工具卡片",
 				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"],
+			examples: [
+				"bohr-widget create workspace-browser --ui react --panel-id workspace-files",
+				"bohr-widget create text-preview --template file-preview --extensions txt,csv --ui vanilla --json",
+				"bohr-widget create search-panel --tool ScholarSearch --json"
+			],
 			notes: [
 				`默认组合为 panel + vanilla；生成工程的构建环境要求 Node.js ${context.generatedProjectNode}。`,
 				"不会自动安装依赖；创建后进入目录，运行 pnpm install 或 npm install。",
@@ -1327,6 +1364,7 @@ function commandTopics(context) {
 				"ok 表示环境、清单与候选 profile 检查通过；ready 还要求工具链锁、已安装依赖和构建入口。",
 				"尚未安装或构建时可能 ok=true、ready=false；先按 warnings 修复再继续。",
 				"ready 不保证 pack --no-build 的 receipt 可复用；doctor 只检查 CLI 的 Node 要求，不验证构建器环境。",
+				"deprecations 列出已废弃的作者用法；直接 contracts 依赖将在统一入口切换发布 R1 前移除，当前使用 Agent 引导的候选准备、plan 对比与 apply 复制流程，不自动转换旧源码。",
 				"旧工程缺少 widget-toolchain.json 时，先核对精确依赖并安装，再运行 adopt。"
 			]
 		},
@@ -1342,7 +1380,7 @@ function commandTopics(context) {
 			notes: [
 				"不传 --project 时只发现 CLI 自带工具链，不检查当前目录是否为 Widget 工程。",
 				"传入工程时要求工具链锁；尚未安装依赖时先核对声明，已安装时同时核对实际版本。",
-				"JSON 使用 interfaceVersion=2、toolchain.formatVersion=2；返回 execution、profile、requirements 和 documentation。",
+				"JSON 使用 interfaceVersion=3、toolchain.formatVersion=3；返回 execution、profile、requirements 和 documentation。",
 				"调用方应使用 execution.executable 与 execution.entry 启动同一份 CLI，避免 PATH 指向另一版本。",
 				"宿主声明由调用方提供；unknown、snapshot、confirmed 不代表上传或发布许可。"
 			],
@@ -1355,7 +1393,7 @@ function commandTopics(context) {
 			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 依赖并安装。",
+				"先运行 doctor，恢复当前 profile 的精确 SDK 依赖并安装。",
 				"核对实际依赖、Manifest 和 samples 后才写锁；不要求已构建入口。",
 				"不会自动升级依赖、迁移源码或修正协议字段；检查不通过时先修复工程。"
 			]
@@ -1372,7 +1410,7 @@ function commandTopics(context) {
 			]
 		},
 		version: {
-			description: "查看当前 CLI 及其固定的 SDK/contracts 版本。",
+			description: "查看当前 SDK 执行器及内置协议摘要。",
 			usage: ["bohr-widget version [--json]", "bohr-widget --version [--json]"],
 			options: [JSON_OPTION],
 			examples: ["bohr-widget version --json", "bohr-widget -v"],
@@ -1385,7 +1423,9 @@ function commandTopics(context) {
 		migrate: migrationGroup,
 		"migrate dsh": {
 			...migrationGroup,
-			arguments: migrationGroup.arguments.slice(1)
+			description: "审计 DSH 插件，并按已审查来源配方生成 Widget 工程。",
+			usage: migrationGroup.usage.filter((line) => line.includes("migrate dsh")),
+			arguments: migrationGroup.arguments.slice(2)
 		},
 		"migrate dsh audit": {
 			description: "只读审计 DSH 插件的来源指纹、已知配方与能力迁移缺口。",
@@ -1441,9 +1481,9 @@ 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;
+	const { cli, sdk, packageName = "@dp-bohrium/widget-cli", generatedProjectNode, documentation } = context;
 	return `bohr-widget ${cli} — Bohrium Widget 插件工程工具
-SDK ${sdk} / contracts ${contracts}
+SDK ${sdk}（协议与执行工具链均由 SDK 内置）
 创建、校验、构建、开发调试与打包；上传、发布和 Agent 绑定由 Bohr CLI 或平台执行。
 
 用法：
@@ -1461,8 +1501,9 @@ SDK ${sdk} / contracts ${contracts}
   integration                      发现工具链、执行器和文档入口
   adopt <目录>                     核验旧工程并写入工具链锁
   schema                           打印作者 Manifest Schema 的本地路径
+  migrate project plan|apply        比较 Agent 准备的候选并安全复制到新目录
   migrate dsh audit|scaffold        审计 DSH 来源或按已审查配方生成工程
-  version                          查看 CLI 与固定的 SDK/contracts 版本
+  version                          查看 SDK 执行器与内置协议版本
   help [命令...]                   查看全局或指定主题帮助
 
 全局选项：
@@ -1473,12 +1514,12 @@ SDK ${sdk} / contracts ${contracts}
 
 调用方式：
   工程内：pnpm exec bohr-widget ... 或 npx --no-install bohr-widget ...
-  未安装：pnpm dlx @dp-bohrium/widget-cli <命令> ...
+  未安装：pnpm dlx ${packageName} <命令> ...
   下方示例中的 bohr-widget 可使用上述工程内调用前缀。
   CLI 要求 Node.js >=20；默认生成工程要求 Node.js ${generatedProjectNode}。
 
 典型开发流程：
-  pnpm dlx @dp-bohrium/widget-cli create my-widget --ui react --panel-id workspace-files
+  pnpm dlx ${packageName} create my-widget --ui react --panel-id workspace-files
   cd my-widget
   pnpm install
   pnpm exec bohr-widget build .
@@ -1536,7 +1577,7 @@ const AUTHOR_MANIFEST_KEYS = Object.freeze([
 	"runtime",
 	"samples"
 ]);
-const AUTHOR_MANIFEST_SCHEMA_ID = "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json";
+const AUTHOR_MANIFEST_SCHEMA_ID = "@dp-bohrium/widget-sdk/schemas/widget-plugin-manifest.schema.json";
 function isPlainObject(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -1602,10 +1643,7 @@ function lintAuthorManifest(manifest, options = {}) {
 //#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 PACKAGES = Object.freeze({ sdk: "@dp-bohrium/widget-sdk" });
 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), {
@@ -1614,7 +1652,7 @@ function failure(code, message, context, recovery) {
 		recovery
 	});
 }
-function record(value) {
+function record$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function text(value) {
@@ -1648,7 +1686,7 @@ async function assertHostCompatibility(hostCompatPath, toolchain, { now = Date.n
 		}, ["重新获取本次目标环境的宿主兼容声明，再通过 --host-compat 传入。"]);
 	};
 	const value = await json(hostCompatPath, "HOST_COMPAT_INVALID", ["重新获取本次目标环境的宿主兼容声明。"]);
-	if (!record(value) || !record(value.statement)) invalid("缺少 statement");
+	if (!record$1(value) || !record$1(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 与目标环境不符");
@@ -1656,7 +1694,7 @@ async function assertHostCompatibility(hostCompatPath, toolchain, { now = Date.n
 	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 (!record$1(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,
@@ -1679,12 +1717,12 @@ async function assertHostCompatibility(hostCompatPath, toolchain, { now = Date.n
 }
 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 不一致", {
+	if (!record$1(lock) || lock.formatVersion !== 2 || lock.profileId !== profile.id) throw failure("PROJECT_PROFILE_MISMATCH", "工程锁定格式或 profile 与当前 SDK 不一致；旧工程需准备当前源码候选后迁移，不能复用历史执行器", {
 		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 不一致", {
+	}, ["使用当前受支持的 CLI，并在新目录显式迁移工程与验收；不要回选旧 CLI 绕过 profile 差异。"]);
+	if (lock.sdk !== profile.sdk || !isDeepStrictEqual(lock.protocol, toolchain.protocol)) throw failure("PROJECT_SDK_MISMATCH", "工程锁定的 SDK 或内置协议与当前 profile 不一致", {
 		projectRoot: root,
 		expected: profile,
 		actual: lock
@@ -1715,12 +1753,66 @@ async function readLock(root, toolchain, required) {
 	}
 	return assertMatchingLock(lock, toolchain, root);
 }
-/** Resolve from this project's node_modules, never from an ancestor or the CLI. */
+function assertInstalledPackage(actual, name, expected, root) {
+	if (!record$1(actual) || actual.name !== name || actual.version !== expected) throw failure("PROJECT_SDK_MISMATCH", `${name} 实际安装版本与工程工具链不一致`, {
+		projectRoot: root,
+		package: name,
+		expected,
+		installed: actual?.version
+	}, ["按工程锁定信息恢复依赖并重新安装，再重新构建。"]);
+}
+/** 名称和字节同时参与摘要；禁止通过协议资产链接借用其他安装。 */
+async function schemaDigest(directory) {
+	const hash = createHash("sha256");
+	const paths = [];
+	async function visit(path) {
+		const entry = await lstat(path);
+		if (entry.isSymbolicLink()) throw new Error("SDK 协议资产不允许符号链接");
+		if (entry.isDirectory()) for (const name of (await readdir(path)).sort()) await visit(join(path, name));
+		else if (entry.isFile()) paths.push(path);
+		else throw new Error("SDK 协议资产必须是普通文件");
+	}
+	await visit(directory);
+	if (!paths.length) throw new Error("SDK 协议资产为空");
+	for (const path of paths.sort()) {
+		const bytes = await readFile(path);
+		hash.update(relative(directory, path).split(sep).join("/"));
+		hash.update("\0");
+		hash.update(String(bytes.length));
+		hash.update("\0");
+		hash.update(bytes);
+	}
+	return `sha256:${hash.digest("hex")}`;
+}
+async function assertEmbeddedProtocol(sdkPath, toolchain, root) {
+	const sdkRoot = dirname(await realpath(sdkPath));
+	try {
+		const embedded = JSON.parse(await readFile(join(sdkRoot, "assets/toolchain.json"), "utf8"));
+		if (embedded.formatVersion !== 3 || embedded.packageName !== PACKAGES.sdk || embedded.cli !== toolchain.profile.sdk || !isDeepStrictEqual(embedded.profile, toolchain.profile) || !isDeepStrictEqual(embedded.protocol, toolchain.protocol) || !isDeepStrictEqual(embedded.digests, toolchain.digests) || embedded.protocol?.schemaVersion !== 1 || embedded.protocol?.hostApiVersion !== 1 || embedded.protocol?.digest !== embedded.digests?.schemas) throw new Error("SDK 内置协议或执行工具链元数据与当前执行器不一致");
+		for (const directory of ["schemas", "assets/schemas"]) if (await schemaDigest(join(sdkRoot, directory)) !== embedded.protocol.digest) throw new Error("SDK 内置协议资产已漂移");
+	} catch (error) {
+		throw failure("PROJECT_SDK_MISMATCH", "工程 SDK 缺少有效的自包含协议资产或摘要不一致", {
+			projectRoot: root,
+			package: PACKAGES.sdk,
+			cause: error.message
+		}, ["在当前工程安装正确的 SDK 完整包，再重新构建；不能借用祖先目录或旧 contracts 包。"]);
+	}
+}
+/** SDK 必须由工程直接安装；协议只能来自该 SDK 自己的冻结资产。 */
 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 pkg = await json(join(root, "package.json"), "PROJECT_SDK_MISMATCH", ["恢复工程 package.json 中的精确 SDK 依赖。"]);
+	if (!record$1(pkg)) throw failure("PROJECT_SDK_MISMATCH", "工程 package.json 必须是对象", { projectRoot: root }, ["恢复工程 package.json 中的精确 SDK 依赖。"]);
+	for (const section of [
+		"dependencies",
+		"devDependencies",
+		"optionalDependencies",
+		"peerDependencies"
+	]) for (const name of ["@dp-bohrium/widget-contracts", "@dp-bohrium/widget-cli"]) if (pkg[section]?.[name] !== void 0) throw failure("PROJECT_SDK_MISMATCH", "作者工程仍直接声明 contracts 或 CLI，需统一使用 SDK 入口", {
+		projectRoot: root,
+		package: name
+	}, ["作者工程统一依赖 SDK；独立 CLI 请在工具目录或通过 npx 使用，Contracts 独立包供 Host 等消费者使用。保留作者源码，在独立候选中移除重复依赖、重新安装和构建。"]);
 	const declared = {};
 	const installed = {};
 	for (const [key, name] of Object.entries(PACKAGES)) {
@@ -1730,28 +1822,35 @@ async function validateProjectToolchain(projectRoot, toolchain, { requireInstall
 			"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}`, {
+		if (key === "sdk" && 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。"]);
+		if (declarations.length === 0) continue;
 		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
-		}, ["按工程锁定信息恢复依赖并重新安装，再重新构建。"]);
+		const path = join(root, "node_modules", name, "package.json");
+		const actual = await json(path, "PROJECT_SDK_MISMATCH", ["在该 Widget 工程目录安装依赖，再重试；父目录或 CLI 的安装不能替代工程安装。"]);
+		assertInstalledPackage(actual, name, expected, root);
 		installed[key] = actual.version;
+		for (const name of ["@dp-bohrium/widget-contracts", "@dp-bohrium/widget-cli"]) if ([
+			"dependencies",
+			"optionalDependencies",
+			"peerDependencies"
+		].some((section) => actual[section]?.[name] !== void 0)) throw failure("PROJECT_SDK_MISMATCH", "工程 SDK 仍包含独立协议或 CLI 运行依赖，不符合当前自包含发布契约", {
+			projectRoot: root,
+			package: name
+		}, ["安装当前自包含 SDK 包，再重新构建。"]);
+		await assertEmbeddedProtocol(path, toolchain, root);
 	}
 	return {
 		projectRoot: root,
 		profile: { ...toolchain.profile },
 		declared,
 		installed,
+		deprecations: [],
 		dependenciesVerified: requireInstalled,
 		lock
 	};
@@ -1761,10 +1860,10 @@ async function writeProjectToolchain(projectRoot, toolchain) {
 	const existing = await readLock(root, toolchain, false);
 	if (existing) return existing;
 	const value = {
-		formatVersion: 1,
+		formatVersion: 2,
 		profileId: toolchain.profile.id,
 		sdk: toolchain.profile.sdk,
-		contracts: toolchain.profile.contracts,
+		protocol: toolchain.protocol,
 		createdWithCli: toolchain.cli
 	};
 	await mkdir(root, { recursive: true });
@@ -1805,6 +1904,7 @@ function receiptToolchain(toolchain) {
 	return {
 		cli: toolchain.cli,
 		profile: toolchain.profile,
+		protocol: toolchain.protocol,
 		digests: toolchain.digests
 	};
 }
@@ -1849,7 +1949,7 @@ async function writeBuildReceipt(projectRoot, toolchain, { inputsBefore } = {})
 	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,
+		formatVersion: 2,
 		toolchain: receiptToolchain(toolchain),
 		dependencies: result.installed,
 		inputs,
@@ -1868,7 +1968,7 @@ async function assertBuildReceipt(projectRoot, toolchain) {
 	};
 	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 工具链或实际依赖与本次执行不一致");
+	if (!record$1(receipt) || receipt.formatVersion !== 2 || JSON.stringify(receipt.toolchain) !== JSON.stringify(receiptToolchain(toolchain)) || JSON.stringify(receipt.dependencies) !== JSON.stringify(project.installed)) mismatch("receipt 工具链或实际依赖与本次执行不一致");
 	let inputs;
 	let outputs;
 	try {
@@ -1881,9 +1981,411 @@ async function assertBuildReceipt(projectRoot, toolchain) {
 	return receipt;
 }
 //#endregion
+//#region src/migration/source.mjs
+const MAX_FILES = 2e3;
+const MAX_FILE_BYTES = 8388608;
+const MAX_TOTAL_BYTES = 67108864;
+const DERIVED = /* @__PURE__ */ new Set([
+	".git",
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	".artifacts",
+	".widget-build-receipt.json",
+	"widget-migration.json",
+	".npmrc"
+]);
+function migrationError(code, message) {
+	return Object.assign(new Error(message), {
+		cliCode: `WIDGET_CLI_MIGRATION_${code}`,
+		recovery: "保留源目录与候选，依据当前 SDK 文档准备并审阅候选；重新生成 plan 后使用新的 --out 目录。"
+	});
+}
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+	return value;
+}
+function sha256(value) {
+	return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function objectSha256(value) {
+	return sha256(JSON.stringify(canonical(value)));
+}
+function inside(root, path) {
+	const child = relative(root, path);
+	return child === "" || !isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`);
+}
+/** 不跟随最终符号链接，读取前后核对同一普通文件。 */
+async function sourceFile(path, maxBytes = MAX_FILE_BYTES) {
+	const before = await lstat(path);
+	if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) throw migrationError("SOURCE_UNSAFE", "来源必须是预算内的普通文件，不接受符号链接。");
+	const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	try {
+		const info = await handle.stat();
+		if (!info.isFile() || info.dev !== before.dev || info.ino !== before.ino) throw migrationError("SOURCE_CHANGED", "读取期间来源文件身份发生变化。");
+		const bytes = await handle.readFile();
+		const after = await handle.stat();
+		if (bytes.length > maxBytes || before.size !== after.size || before.mtimeMs !== after.mtimeMs) throw migrationError("SOURCE_CHANGED", "读取期间来源文件发生变化。");
+		return bytes;
+	} finally {
+		await handle.close();
+	}
+}
+/** 捕获作者文件和依赖锁；安装、构建、本地环境及旧 receipt 明确排除。 */
+async function sourceSnapshot(input) {
+	const requested = resolve(typeof input === "string" ? input : fileURLToPath(input));
+	const info = await lstat(requested);
+	if (info.isSymbolicLink()) throw migrationError("SOURCE_UNSAFE", "来源不能是符号链接。");
+	const root = await realpath(requested);
+	if (!info.isDirectory()) throw migrationError("AUTHOR_SOURCE_REQUIRED", "迁移需要完整作者源码目录；ZIP 或编译产物不能还原源码，请先提供源码。");
+	const files = /* @__PURE__ */ new Map();
+	const modes = /* @__PURE__ */ new Map();
+	const excluded = [];
+	let total = 0;
+	async function visit(directory, prefix = "") {
+		for (const name of (await readdir(directory)).sort()) {
+			const path = prefix ? `${prefix}/${name}` : name;
+			if (DERIVED.has(name) && (!prefix || [
+				".git",
+				"node_modules",
+				".npmrc"
+			].includes(name)) || /^\.env(?:\.|$)/u.test(name)) {
+				excluded.push(path);
+				continue;
+			}
+			if (normalizeArchivePath(path) !== path) throw migrationError("SOURCE_UNSAFE", "来源含非规范路径。");
+			const full = join(root, path);
+			const entry = await lstat(full);
+			if (entry.isSymbolicLink()) throw migrationError("SOURCE_UNSAFE", `来源含符号链接：${path}`);
+			if (entry.isDirectory()) await visit(full, path);
+			else if (entry.isFile()) {
+				if (files.size >= MAX_FILES || total + entry.size > MAX_TOTAL_BYTES) throw migrationError("SOURCE_LIMIT", "来源超出扫描预算，请人工拆分工程。");
+				const bytes = await sourceFile(full);
+				total += bytes.length;
+				files.set(path, bytes);
+				modes.set(path, entry.mode & 73);
+			} else throw migrationError("SOURCE_UNSAFE", `来源含非普通文件：${path}`);
+		}
+	}
+	await visit(root);
+	return {
+		root,
+		kind: "directory",
+		files,
+		excluded,
+		sha256: filesSha256(files, modes),
+		modes
+	};
+}
+function filesSha256(files, modes = /* @__PURE__ */ new Map()) {
+	return objectSha256([...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([path, bytes]) => [
+		path,
+		sha256(bytes),
+		modes.get(path) ?? 0
+	]));
+}
+function jsonFile(files, path) {
+	if (!files.has(path)) return null;
+	try {
+		return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(files.get(path)));
+	} catch {
+		throw migrationError("SOURCE_JSON", `来源不是有效 UTF-8 JSON：${path}`);
+	}
+}
+function jsonBytes(value) {
+	return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+}
+async function sourceRulesSha256() {
+	return sha256(await sourceFile(fileURLToPath(import.meta.url), MAX_TOTAL_BYTES));
+}
+//#endregion
+//#region src/migration/project.mjs
+const RECEIPT = "widget-migration.json";
+const HASH_SCOPE = "作者文件与依赖锁的字节、执行权限；排除安装、根构建、本地环境、Git 和旧 receipt";
+const record = (value) => value && typeof value === "object" && !Array.isArray(value);
+function authorSource(snapshot) {
+	const manifest = jsonFile(snapshot.files, "manifest.json");
+	const pkg = jsonFile(snapshot.files, "package.json");
+	const hasSource = [...snapshot.files.keys()].some((path) => /\.[cm]?[jt]sx?$/u.test(path) && (path.startsWith("src/") || path === manifest?.entry));
+	if (!record(manifest) || !record(pkg) || !hasSource) throw migrationError("AUTHOR_SOURCE_REQUIRED", "需要包含 package.json、manifest.json 和作者源码的完整目录；编译产物不能代替源码。");
+	return manifest;
+}
+function snapshotDescription(snapshot, kind) {
+	return {
+		kind,
+		path: snapshot.root,
+		sha256: snapshot.sha256,
+		hashScope: HASH_SCOPE,
+		excluded: snapshot.excluded
+	};
+}
+function fileState(snapshot, path) {
+	const bytes = snapshot.files.get(path);
+	return bytes ? {
+		sha256: sha256(bytes),
+		executable: snapshot.modes.get(path) ?? 0
+	} : null;
+}
+function changesBetween(source, candidate) {
+	return [.../* @__PURE__ */ new Set([...source.files.keys(), ...candidate.files.keys()])].sort().flatMap((path) => {
+		const before = fileState(source, path);
+		const after = fileState(candidate, path);
+		if (JSON.stringify(before) === JSON.stringify(after)) return [];
+		return [{
+			path,
+			action: before ? after ? "update" : "delete" : "create",
+			before,
+			after
+		}];
+	});
+}
+function pendingValidation(reason) {
+	return {
+		status: "not-run",
+		ok: false,
+		scope: "structure-and-declarations",
+		installation: "not-run",
+		build: "not-run",
+		host: "not-run",
+		checks: [],
+		errors: [],
+		reason
+	};
+}
+/** 只检查已准备候选的当前声明和内容结构，不执行候选代码或安装脚本。 */
+async function candidateValidation(snapshot, toolchain) {
+	const validation = {
+		...pendingValidation("候选尚未校验"),
+		status: "completed"
+	};
+	delete validation.reason;
+	let manifest;
+	try {
+		manifest = authorSource(snapshot);
+		const lint = lintAuthorManifest(manifest);
+		if (!manifest.contributes || !lint.ok) {
+			validation.errors.push(...lint.errors.length ? lint.errors : ["候选必须使用当前 contributes 作者清单。"]);
+			return validation;
+		}
+		if (typeof manifest.entry !== "string" || normalizeArchivePath(manifest.entry) !== manifest.entry || !snapshot.files.has(manifest.entry)) {
+			validation.errors.push("候选 entry 必须指向安全快照中的作者源码。");
+			return validation;
+		}
+		const compiled = compileAuthorManifest(manifest, { sdkVersion: toolchain.profile.sdk });
+		for (const sample of compiled.widgetConfig?.samples ?? []) if (typeof sample.request !== "string" || normalizeArchivePath(sample.request) !== sample.request || !snapshot.files.has(sample.request)) {
+			validation.errors.push("候选 sample 不在安全源码快照中。");
+			return validation;
+		}
+		let component = snapshot.root;
+		const hostEntry = compiled.widgetConfig?.entry;
+		if (typeof hostEntry !== "string" || normalizeArchivePath(hostEntry) !== hostEntry) {
+			validation.errors.push("候选的编译入口不是规范相对路径。");
+			return validation;
+		}
+		for (const segment of hostEntry.split("/")) {
+			component = join(component, segment);
+			const entry = await lstat(component).catch((error) => {
+				if (error.code === "ENOENT") return null;
+				throw error;
+			});
+			if (!entry) break;
+			if (entry.isSymbolicLink()) throw migrationError("SOURCE_UNSAFE", "校验入口不能穿过符号链接。");
+		}
+		const project = await validateProjectToolchain(snapshot.root, toolchain, { requireInstalled: false });
+		const pkg = jsonFile(snapshot.files, "package.json");
+		const cliVersions = [
+			"dependencies",
+			"devDependencies",
+			"optionalDependencies",
+			"peerDependencies"
+		].flatMap((section) => pkg[section]?.["@dp-bohrium/widget-cli"] === void 0 ? [] : [pkg[section]["@dp-bohrium/widget-cli"]]);
+		if (cliVersions.length > 1 || cliVersions.some((version) => version !== toolchain.cli)) {
+			validation.errors.push("候选声明的 Widget CLI 必须是本次执行器的单一精确版本。");
+			return validation;
+		}
+		validation.checks.push({
+			name: "候选精确工具链锁与依赖声明",
+			ok: true
+		});
+		validation.toolchain = {
+			profile: project.profile,
+			declared: project.declared,
+			dependenciesVerified: false
+		};
+		const checked = await checkWidgetProject(snapshot.root, {
+			requireBuiltEntry: false,
+			sdkVersion: toolchain.profile.sdk
+		});
+		validation.checks.push(...checked.checks.map(({ name, ok }) => ({
+			name,
+			ok
+		})));
+		validation.errors.push(...checked.errors);
+		validation.ok = checked.ok;
+		return validation;
+	} catch (error) {
+		if (error.cliCode === "WIDGET_CLI_MIGRATION_SOURCE_UNSAFE") throw error;
+		validation.errors.push(error.message);
+		return validation;
+	}
+}
+async function prepare(source, candidatePath, toolchain) {
+	const snapshot = await sourceSnapshot(source);
+	authorSource(snapshot);
+	const report = {
+		ok: true,
+		command: "migrate project plan",
+		formatVersion: 2,
+		mode: "agent-guided",
+		canApply: false,
+		source: snapshotDescription(snapshot, "author-source"),
+		candidate: null,
+		target: {
+			cli: toolchain.cli,
+			profile: toolchain.profile,
+			execution: toolchain.digests,
+			migration: objectSha256([await sourceRulesSha256(), sha256(await sourceFile(fileURLToPath(import.meta.url), 67108864))])
+		},
+		changes: [],
+		blockers: [],
+		manualSteps: [
+			"依据当前 SDK 模板、示例和文档，在来源目录树之外独立准备并审阅候选；源码、依赖和锁由 Agent 或开发者明确修改，不自动转换旧格式。",
+			"使用 plan --candidate <候选目录> 保存并审阅来源/候选摘要和全部文件变更，再 apply 到与两者分离的新目录。",
+			"apply 不安装或运行来源与候选脚本；随后审查安装脚本、安装依赖、build、check、pack，并在真实 Host 验收。"
+		],
+		validation: pendingValidation("尚未提供已准备的当前工程候选。")
+	};
+	let candidate = null;
+	if (!candidatePath) report.blockers.push({
+		code: "WIDGET_CLI_MIGRATION_CANDIDATE_REQUIRED",
+		message: "没有自动源码迁移规则；请由 Agent 或开发者准备候选后用 --candidate 重新 plan。"
+	});
+	else {
+		candidate = await sourceSnapshot(candidatePath);
+		if (inside(snapshot.root, candidate.root) || inside(candidate.root, snapshot.root)) throw migrationError("CANDIDATE_UNSAFE", "候选必须独立于来源目录树，不能使用来源、子目录或祖先。");
+		report.candidate = snapshotDescription(candidate, "prepared-current-project");
+		report.changes = changesBetween(snapshot, candidate);
+		report.validation = await candidateValidation(candidate, toolchain);
+		if (!report.validation.ok) report.blockers.push({
+			code: "WIDGET_CLI_MIGRATION_CANDIDATE_INVALID",
+			message: "候选未通过当前工程锁、依赖声明或 Manifest/sample 结构校验；请修正候选后重新 plan。"
+		});
+		if ((await sourceSnapshot(candidate.root)).sha256 !== candidate.sha256) throw migrationError("CANDIDATE_CHANGED", "校验期间候选发生变化，请重新 plan。");
+	}
+	if ((await sourceSnapshot(snapshot.root)).sha256 !== snapshot.sha256) throw migrationError("SOURCE_CHANGED", "规划期间来源发生变化，请重新 plan。");
+	report.canApply = report.blockers.length === 0;
+	report.planSha256 = objectSha256(report);
+	return {
+		report,
+		snapshot,
+		candidate
+	};
+}
+async function planMigration(source, toolchain, candidate) {
+	return (await prepare(source, candidate, toolchain)).report;
+}
+function receiptFor(plan) {
+	return {
+		formatVersion: 2,
+		mode: "agent-guided",
+		planSha256: plan.planSha256,
+		source: plan.source,
+		candidate: plan.candidate,
+		target: plan.target,
+		outputSha256: plan.candidate.sha256
+	};
+}
+async function existingResult(out, plan) {
+	const info = await lstat(out);
+	if (!info.isDirectory() || info.isSymbolicLink()) throw migrationError("OUT_EXISTS", "目标已存在且不是可核验的同计划迁移目录。");
+	const current = await sourceSnapshot(out);
+	let receipt;
+	try {
+		receipt = JSON.parse((await sourceFile(join(out, RECEIPT))).toString("utf8"));
+	} catch {
+		throw migrationError("OUT_EXISTS", "目标已有内容但缺少有效迁移记录，拒绝覆盖。");
+	}
+	if (JSON.stringify(canonical(receipt)) !== JSON.stringify(canonical(receiptFor(plan))) || current.sha256 !== plan.candidate.sha256) throw migrationError("OUT_EXISTS", "目标已存在或迁移结果已改变，拒绝覆盖；请使用新的 --out。");
+	return true;
+}
+/** 候选路径只来自已审阅计划；全部写入私有阶段目录后排他发布，不执行代码。 */
+async function applyMigration(source, planPath, output, toolchain, hostCompat) {
+	if (!planPath || !output) throw migrationError("ARGUMENT", "apply 需要 --plan <plan.json> 和 --out <新目录>。");
+	const plan = JSON.parse((await sourceFile(resolve(planPath))).toString("utf8"));
+	if (plan.formatVersion !== 2 || plan.mode !== "agent-guided") throw migrationError("PLAN_MISMATCH", "需要当前 agent-guided 格式 v2 的完整计划，请重新 plan。");
+	const prepared = await prepare(source, plan.candidate?.path, toolchain);
+	if (JSON.stringify(canonical(plan)) !== JSON.stringify(canonical(prepared.report))) throw migrationError("PLAN_MISMATCH", "计划、来源、候选或目标执行器摘要已变化；请重新 plan 并审阅，不能修改计划绕过检查。");
+	if (!plan.canApply) throw migrationError("BLOCKED", "计划含 blockers，不能 apply；请先独立准备并校验候选。");
+	const hostCompatibility = await assertHostCompatibility(hostCompat, toolchain);
+	const requested = resolve(output);
+	const parent = await realpath(dirname(requested));
+	const out = join(parent, basename(requested));
+	for (const input of [prepared.snapshot.root, prepared.candidate.root]) if (inside(input, out) || inside(out, input)) throw migrationError("OUT_UNSAFE", "目标必须位于来源和候选目录树之外，不能覆盖任一输入、子目录或祖先。");
+	const stage = await mkdtemp(join(parent, ".widget-migration-"));
+	let reservation;
+	try {
+		for (const [path, bytes] of prepared.candidate.files) {
+			await mkdir(dirname(join(stage, path)), { recursive: true });
+			await writeFile(join(stage, path), bytes, { flag: "wx" });
+			await chmod(join(stage, path), 420 | (prepared.candidate.modes.get(path) ?? 0));
+		}
+		const checked = await candidateValidation({
+			...prepared.candidate,
+			root: stage
+		}, toolchain);
+		if (!checked.ok) throw migrationError("TARGET_INVALID", `复制后的候选未通过结构校验：${checked.errors.join("；")}`);
+		if ((await sourceSnapshot(stage)).sha256 !== prepared.candidate.sha256) throw migrationError("TARGET_CHANGED", "复制结果与已审阅候选不同，未发布结果。");
+		await writeFile(join(stage, RECEIPT), jsonBytes(receiptFor(plan)), { flag: "wx" });
+		if ((await sourceSnapshot(prepared.snapshot.root)).sha256 !== plan.source.sha256) throw migrationError("SOURCE_CHANGED", "生成期间来源发生变化；未发布结果，请重新 plan。");
+		if ((await sourceSnapshot(prepared.candidate.root)).sha256 !== plan.candidate.sha256) throw migrationError("CANDIDATE_CHANGED", "生成期间候选发生变化；未发布结果，请重新 plan。");
+		let reused = false;
+		try {
+			await mkdir(out);
+			reservation = await lstat(out);
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+			reused = await existingResult(out, plan);
+		}
+		if (!reused) {
+			const current = await lstat(out);
+			if (current.ino !== reservation.ino || current.dev !== reservation.dev || current.isSymbolicLink()) throw migrationError("OUT_CHANGED", "目标占位目录已被替换，拒绝写入。");
+			await rename(stage, out);
+			reservation = null;
+		}
+		return {
+			ok: true,
+			command: "migrate project apply",
+			formatVersion: 2,
+			mode: "agent-guided",
+			projectRoot: out,
+			planSha256: plan.planSha256,
+			source: plan.source,
+			candidate: plan.candidate,
+			target: plan.target,
+			outputSha256: plan.candidate.sha256,
+			reused,
+			hostCompatibility,
+			validation: checked,
+			nextSteps: plan.manualSteps
+		};
+	} finally {
+		await rm(stage, {
+			recursive: true,
+			force: true
+		});
+		if (reservation) {
+			const current = await lstat(out).catch(() => null);
+			if (current?.ino === reservation.ino && current?.dev === reservation.dev) await rmdir(out).catch(() => {});
+		}
+	}
+}
+//#endregion
 //#region src/templates.mjs
 const GENERATED_PROJECT_NODE = "^22.18.0 || >=24.11.0";
-function projectPackage({ name, ui, cliVersion, sdkVersion, contractsVersion }) {
+const PROJECT_EXECUTOR_PACKAGE = "@dp-bohrium/widget-sdk";
+function projectPackage({ name, ui, sdkVersion }) {
 	return {
 		name: `@dp-bohrium/widget-example-${name}`,
 		private: true,
@@ -1902,8 +2404,6 @@ function projectPackage({ name, ui, cliVersion, sdkVersion, contractsVersion })
 			} : {}
 		},
 		devDependencies: {
-			"@dp-bohrium/widget-cli": cliVersion,
-			"@dp-bohrium/widget-contracts": contractsVersion,
 			tsdown: "0.22.14",
 			typescript: "5.9.3",
 			...ui === "react" ? {
@@ -1918,8 +2418,8 @@ function projectReadme({ name, template, ui, sourceFile, hostFile }) {
 
 Bohrium Widget ${template} 插件工程（${ui}）。
 
-默认构建器要求 Node.js \`${GENERATED_PROJECT_NODE}\`，高于 CLI 自身的 Node.js 20 要求。
-工程已经精确依赖创建它的 CLI 版本；在本目录安装后使用本地命令，无需全局安装或源码仓库。
+默认构建器要求 Node.js \`${GENERATED_PROJECT_NODE}\`，高于执行器自身的 Node.js 20 要求。
+工程已经精确依赖提供命令的 \`${PROJECT_EXECUTOR_PACKAGE}\`；在本目录安装后使用本地命令，无需全局安装或源码仓库。
 
 \`\`\`bash
 pnpm install
@@ -1965,8 +2465,7 @@ function reactSource({ reportSize = false } = {}) {
       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";
+import type { RenderRequest, WidgetContext } from "@dp-bohrium/widget-sdk";
 
 function WidgetView({ request }: { request?: RenderRequest }) {
   const data = request?.content ?? { state: "等待 Host 提供数据" };
@@ -2018,13 +2517,13 @@ runWidgetHost(widget, {
 }
 const TEMPLATES = Object.freeze({
 	panel: {
-		manifest: ({ name, panelId = name, ui = "vanilla" }) => ({
-			$schema: "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+		manifest: ({ name, panelId = name, ui = "vanilla", tool }) => ({
+			$schema: "@dp-bohrium/widget-sdk/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"],
+			activationEvents: [tool ? `tool-call-result:${tool}` : "session.start"],
 			contributes: { widget: {
 				type: "panel",
 				id: panelId,
@@ -2120,7 +2619,6 @@ export { activate };
 						name: "files.read",
 						limits: {
 							bytesPerRequest: 65536,
-							bytesPerRun: 262144,
 							callsPerMinute: 60
 						}
 					}
@@ -2130,16 +2628,16 @@ export { activate };
 		})
 	},
 	"file-preview": {
-		manifest: ({ name, ui = "vanilla" }) => ({
-			$schema: "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+		manifest: ({ name, ui = "vanilla", extensions = ["txt"], tool }) => ({
+			$schema: "@dp-bohrium/widget-sdk/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"],
+			activationEvents: [tool ? `tool-call-result:${tool}` : "workspace-file-opened"],
 			contributes: { widget: {
 				type: "file-preview",
-				extensions: ["txt"]
+				extensions
 			} },
 			samples: [{
 				id: "default",
@@ -2177,7 +2675,7 @@ export { activate };
 			reportSize: true
 		}),
 		hostSource,
-		sample: () => ({
+		sample: ({ extensions = ["txt"] } = {}) => ({
 			schemaVersion: 1,
 			requestId: "sample-file-preview",
 			instanceId: "sample-file-preview",
@@ -2188,8 +2686,8 @@ export { activate };
 				contribution: "file-preview",
 				file: {
 					id: "sample",
-					name: "README.txt",
-					extension: "txt",
+					name: `README.${extensions[0]}`,
+					extension: extensions[0],
 					kind: "file"
 				},
 				preview: { format: "text" }
@@ -2226,7 +2724,7 @@ function getAssetRoot() {
 }
 function getToolchain() {
 	const path = join(getAssetRoot(), "toolchain.json");
-	if (!existsSync(path)) throw new Error("缺少 Widget CLI 工具链资产；源码运行前请执行 pnpm --filter @dp-bohrium/widget-cli build:assets，发布包请重新安装。");
+	if (!existsSync(path)) throw new Error("缺少 Widget 工具链资产；源码运行前请构建当前分发包的 CLI assets，发布包请重新安装。");
 	return JSON.parse(readFileSync(path, "utf8"));
 }
 function getDocumentation() {
@@ -2243,12 +2741,12 @@ function getSchemaPath(name = "widget-manifest.schema.json") {
 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,
+		protocol: toolchain.protocol,
+		packageName: toolchain.packageName,
 		documentation: getDocumentation(),
 		generatedProjectNode: GENERATED_PROJECT_NODE
 	});
@@ -2287,8 +2785,12 @@ function parseOptions(argv) {
 		scheme: "widget-host",
 		bridge: null,
 		panelId: void 0,
+		extensions: void 0,
+		tool: void 0,
 		hostCompat: void 0,
-		project: void 0
+		project: void 0,
+		plan: void 0,
+		candidate: void 0
 	};
 	for (let index = 0; index < argv.length; index += 1) {
 		const argument = argv[index];
@@ -2303,14 +2805,21 @@ function parseOptions(argv) {
 		} else if (argument === "--panel-id") {
 			options.panelId = argv[++index];
 			if (!options.panelId) throw new Error("--panel-id 需要稳定的 Panel id");
+		} else if (argument === "--extensions" || argument === "--tool") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) throw new Error(`${argument} 需要非空值`);
+			if (argument === "--extensions") options.extensions = value.split(",").map((item) => item.trim());
+			else options.tool = value;
 		} 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") {
+		else if (argument === "--host-compat" || argument === "--project" || argument === "--plan" || argument === "--candidate") {
 			const value = argv[++index];
 			if (!value || value.startsWith("--")) throw new Error(`${argument} 需要路径`);
 			if (argument === "--host-compat") options.hostCompat = value;
+			else if (argument === "--plan") options.plan = value;
+			else if (argument === "--candidate") options.candidate = value;
 			else options.project = value;
 		} else if (argument === "--watch") options.watch = true;
 		else if (argument === "--no-build") options.build = false;
@@ -2328,11 +2837,15 @@ function parseOptions(argv) {
 function printResult(result, json) {
 	if (json) console.log(JSON.stringify(result, null, 2));
 	else {
+		printDeprecations(result.deprecations);
 		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 printDeprecations(deprecations = []) {
+	for (const diagnostic of deprecations) console.warn(`废弃 [${diagnostic.code}]：${diagnostic.message}`);
+}
 function structuredError({ code, message, context = {}, recovery }) {
 	return {
 		code,
@@ -2373,7 +2886,8 @@ async function projectPreflight(projectRoot, options = {}) {
 	return {
 		profile: toolchain.profile,
 		hostCompatibility,
-		project
+		project,
+		deprecations: project.deprecations
 	};
 }
 async function commandIntegration(options) {
@@ -2382,7 +2896,7 @@ async function commandIntegration(options) {
 	const result = {
 		ok: true,
 		command: "integration",
-		interfaceVersion: 2,
+		interfaceVersion: 3,
 		requirements: {
 			node: ">=20",
 			generatedProjectNode: GENERATED_PROJECT_NODE
@@ -2396,10 +2910,14 @@ async function commandIntegration(options) {
 		assetRoot: getAssetRoot(),
 		documentation: getDocumentation(),
 		hostCompatibility,
+		deprecations: project?.deprecations ?? [],
 		...project ? { project } : {}
 	};
 	if (options.json) console.log(JSON.stringify(result, null, 2));
-	else console.log(`${toolchain.profile.id}\n${result.documentation.url}`);
+	else {
+		printDeprecations(result.deprecations);
+		console.log(`${toolchain.profile.id}\n${result.documentation.url}`);
+	}
 	return result;
 }
 async function commandAdopt(directory, options) {
@@ -2413,10 +2931,14 @@ async function commandAdopt(directory, options) {
 		projectRoot,
 		profile: toolchain.profile,
 		project,
+		deprecations: project.deprecations,
 		hostCompatibility
 	};
 	if (options.json) console.log(JSON.stringify(result, null, 2));
-	else console.log(`已锁定工程工具链：${toolchain.profile.id}`);
+	else {
+		printDeprecations(result.deprecations);
+		console.log(`已锁定工程工具链：${toolchain.profile.id}`);
+	}
 	return result;
 }
 /**
@@ -2435,6 +2957,9 @@ async function commandCreate(directory, options) {
 	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.extensions && options.template !== "file-preview") throw new Error("--extensions 只适用于 --template file-preview");
+	if (options.extensions && (options.extensions.length > 32 || new Set(options.extensions).size !== options.extensions.length || options.extensions.some((extension) => !/^[a-z0-9][a-z0-9.-]{0,31}$/u.test(extension)))) throw new Error("--extensions 需要 1-32 个不重复的小写扩展名，用逗号分隔且不带前导点");
+	if (options.tool && (!/^[A-Za-z0-9_.:-]+$/u.test(options.tool) || `tool-call-result:${options.tool}`.length > 128)) throw new Error("--tool 需要有效工具名，只能包含字母、数字、下划线、点、冒号和连字符，激活信号最长 128 位");
 	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}`);
@@ -2445,7 +2970,9 @@ async function commandCreate(directory, options) {
 		name,
 		panelId,
 		sdkVersion: sdkPackage.version,
-		ui: options.ui
+		ui: options.ui,
+		extensions: options.extensions,
+		tool: options.tool
 	};
 	const manifest = template.manifest(templateContext);
 	const sample = template.sample(templateContext);
@@ -2489,9 +3016,7 @@ async function commandCreate(directory, options) {
 	await writeFile(join(root, "package.json"), `${JSON.stringify(projectPackage({
 		name,
 		ui: options.ui,
-		cliVersion: packageJson.version,
-		sdkVersion: sdkPackage.version,
-		contractsVersion: contractsPackage.version
+		sdkVersion: sdkPackage.version
 	}), null, 2)}\n`);
 	const warnings = [];
 	await writeProjectToolchain(root, toolchain);
@@ -2708,6 +3233,7 @@ async function commandCheck(input, options, commandName = "check") {
 				ok: result.ok,
 				checks: result.checks,
 				errors: result.errors,
+				...result.deprecations?.length ? { deprecations: result.deprecations } : {},
 				...result.warnings?.length ? { warnings: result.warnings } : {}
 			})),
 			...passed ? {} : { error: structuredError({
@@ -2812,8 +3338,9 @@ async function runProjectBuild(root, { capture = false } = {}) {
 async function commandBuild(directory, options = {}) {
 	if (!directory) throw new Error("build 需要工程目录");
 	const root = resolve(directory);
+	let compatibility;
 	try {
-		const compatibility = await projectPreflight(root, options);
+		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 });
@@ -2831,6 +3358,7 @@ async function commandBuild(directory, options = {}) {
 		};
 		if (options.json && options.emit !== false) console.log(JSON.stringify(result, null, 2));
 		else if (options.emit !== false) {
+			printDeprecations(result.deprecations);
 			if (build.stdout) process.stdout.write(build.stdout);
 			if (build.stderr) process.stderr.write(build.stderr);
 		}
@@ -2840,6 +3368,7 @@ async function commandBuild(directory, options = {}) {
 			ok: false,
 			command: "build",
 			projectRoot: root,
+			...compatibility ? { deprecations: compatibility.deprecations } : {},
 			error: commandError("build", error, {
 				projectRoot: root,
 				phase: "build"
@@ -2849,6 +3378,7 @@ async function commandBuild(directory, options = {}) {
 		};
 		if (options.json && options.emit !== false) console.log(JSON.stringify(result, null, 2));
 		if (!options.json && options.emit !== false) {
+			printDeprecations(result.deprecations);
 			if (result.stdout) process.stdout.write(result.stdout);
 			if (result.stderr) process.stderr.write(result.stderr);
 		}
@@ -2884,6 +3414,7 @@ async function commandPack(directory, options) {
 			if (build.stderr) process.stderr.write(build.stderr);
 		}
 		if (!build.ok) {
+			if (!options.json) printDeprecations(build.deprecations);
 			if (options.json) console.log(JSON.stringify({
 				...build,
 				command: "pack",
@@ -2897,12 +3428,16 @@ async function commandPack(directory, options) {
 		requireBuiltEntry: true,
 		toolchain: { sdkVersion: toolchain.profile.sdk }
 	}));
-	if (!options.json) printResult(result, false);
+	if (!options.json) printResult({
+		...result,
+		deprecations: compatibility.deprecations
+	}, false);
 	if (!result.ok) {
 		if (options.json) console.log(JSON.stringify({
 			ok: false,
 			command: "pack",
 			projectRoot: result.projectRoot,
+			deprecations: compatibility.deprecations,
 			error: structuredError({
 				code: "WIDGET_CLI_PACK_VALIDATION_FAILED",
 				message: "Widget 工程校验失败，未生成可交付 Bundle。",
@@ -2929,9 +3464,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 files = collectWidgetPackageFiles(result, { includePreviewFixtures: fixturesIncluded });
-	warnings.push(...oversizedAssetWarnings(files));
-	const bundle = storedZip(files);
+	const prepared = prepareWidgetPackage(result, { includePreviewFixtures: fixturesIncluded });
+	warnings.push(...oversizedAssetWarnings(prepared.files));
+	const bundle = prepared.archive;
 	await mkdir(dirname(destination), { recursive: true });
 	await writeFile(destination, bundle);
 	const artifact = {
@@ -2939,12 +3474,12 @@ async function commandPack(directory, options) {
 		command: "pack",
 		projectRoot: result.projectRoot,
 		path: destination,
-		bytes: bundle.byteLength,
-		sha256: `sha256:${createHash("sha256").update(bundle).digest("hex")}`,
+		bytes: prepared.bytes,
+		sha256: prepared.sha256,
 		toolchain: {
 			cli: packageJson.version,
 			sdk: sdkPackage.version,
-			contracts: contractsPackage.version
+			protocol: toolchain.protocol
 		},
 		...compatibility,
 		hostCompatibility: await assertHostCompatibility(options.hostCompat, toolchain),
@@ -2970,7 +3505,20 @@ async function commandPack(directory, options) {
 	return artifact;
 }
 async function commandMigrate(positional, options) {
-	if (positional[0] !== "dsh") throw new Error("migrate 目前只支持 dsh");
+	if (positional[0] === "project") {
+		const [, action, source, ...extra] = positional;
+		if (!source || extra.length || !["plan", "apply"].includes(action)) throw new Error("用法：migrate project plan <source> [--candidate <候选目录>]；apply 另需 --plan 与 --out。");
+		if (action === "plan" && (options.plan || options.output || options.hostCompat)) throw new Error("plan 完全只读，不接受 --plan、--out 或 --host-compat；宿主声明在 apply 时核对。");
+		if (action === "apply" && options.candidate) throw new Error("apply 的候选只从已审阅计划读取，不接受 --candidate 覆盖");
+		const result = action === "plan" ? await planMigration(source, toolchain, options.candidate) : await applyMigration(source, options.plan, options.output, toolchain, options.hostCompat);
+		if (options.json) console.log(JSON.stringify(result, null, 2));
+		else if (action === "plan") {
+			console.log(result.canApply ? "计划可应用；审阅 JSON 后在新目录 apply。" : "迁移已阻断，请处理 blockers 并准备当前工程候选。");
+			for (const blocker of result.blockers) console.log(`[${blocker.code}] ${blocker.message}`);
+		} else console.log(`已${result.reused ? "核验已有" : "创建"}迁移工程：${result.projectRoot}`);
+		return result;
+	}
+	if (positional[0] !== "dsh") throw new Error("migrate 支持 project 或 dsh；Bundle/ZIP 请提供完整作者源码目录");
 	const action = positional[1];
 	const input = positional[2];
 	if (!input) throw new Error(`migrate dsh ${action ?? ""} 需要源插件目录`);
@@ -2987,10 +3535,7 @@ 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
-		});
+		const result = await scaffoldDshWidget(input, options.output, { sdkVersion: sdkPackage.version });
 		await writeProjectToolchain(result.projectRoot, toolchain);
 		result.profile = toolchain.profile;
 		result.hostCompatibility = hostCompatibility;
@@ -3009,14 +3554,15 @@ async function commandDoctor(directory, options) {
 		cli: packageJson.version,
 		node: process.versions.node,
 		sdk: sdkPackage.version,
-		contracts: contractsPackage.version,
+		protocol: toolchain.protocol,
 		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: []
+		warnings: [],
+		deprecations: []
 	};
 	if (report.manifest) try {
 		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -3043,6 +3589,8 @@ async function commandDoctor(directory, options) {
 			requireInstalled: report.dependenciesInstalled,
 			requireLock: false
 		});
+		report.deprecations = report.projectToolchain.deprecations;
+		report.warnings.push(...report.deprecations.map((diagnostic) => `[${diagnostic.code}] ${diagnostic.message}`));
 		const lint = lintProjectManifest(root);
 		const candidate = await checkWidgetProject(root, {
 			requireBuiltEntry: false,
@@ -3081,7 +3629,7 @@ function commandVersion(options) {
 		command: "version",
 		cli: packageJson.version,
 		sdk: sdkPackage.version,
-		contracts: contractsPackage.version
+		protocol: toolchain.protocol
 	};
 	if (options.json) console.log(JSON.stringify(result, null, 2));
 	else console.log(`${result.cli} (SDK ${result.sdk})`);
@@ -3095,15 +3643,35 @@ async function main(argv) {
 	if (command === "dev") {
 		const devArgs = [];
 		let hostCompat;
+		let deprecationsReported = false;
+		let deprecations = [];
 		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 devJson = devArgs.includes("--json");
 		const exitCode = await runWidgetDevelopmentCli(devArgs, {
-			beforeBuild: ({ projectRoot }) => projectPreflight(projectRoot, { hostCompat }),
+			...devJson ? { emit: (line, error = false) => {
+				const event = JSON.parse(line);
+				event.data = {
+					...event.data,
+					deprecations
+				};
+				if (error) console.error(JSON.stringify(event));
+				else console.log(JSON.stringify(event));
+			} } : {},
+			beforeBuild: async ({ projectRoot }) => {
+				const result = await projectPreflight(projectRoot, { hostCompat });
+				deprecations = result.deprecations;
+				if (!devJson && !deprecationsReported && deprecations.length) {
+					printDeprecations(result.deprecations);
+					deprecationsReported = true;
+				}
+				return result;
+			},
 			buildProject: runProjectBuild,
 			checkProject: async (projectRoot, checkOptions) => {
-				await projectPreflight(projectRoot, { hostCompat });
+				deprecations = (await projectPreflight(projectRoot, { hostCompat })).deprecations;
 				const lint = lintProjectManifest(projectRoot);
 				if (lint && !lint.ok) {
 					const error = new Error(lint.errors.join("\n"));
@@ -3121,6 +3689,8 @@ async function main(argv) {
 		return exitCode;
 	}
 	const { positional, options } = parseOptions(argv.slice(1));
+	if (options.candidate && !(command === "migrate" && positional[0] === "project" && positional[1] === "plan")) throw new Error("--candidate 只适用于 migrate project plan");
+	if (command !== "create" && (options.extensions || options.tool)) throw new Error("--extensions 和 --tool 只适用于 create");
 	if (!COMMANDS.includes(command)) throw new Error(`未知命令：${command}`);
 	if (command === "version") return commandVersion(options);
 	if (command === "integration") return commandIntegration(options);