@dp-bohrium/widget-cli 0.4.0 → 0.5.1

package/dist/cli.mjs

@@ -1,6 +1,5 @@
 #!/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-BvnlfCRX.mjs";
-import { createRequire } from "node:module";
+import { a as normalizeArchivePath, c as compileAuthorManifest, i as prepareWidgetPackage, n as scaffoldDshWidget, o as checkWidgetProject, s as resolveWidgetProjects, t as auditDshPlugin } from "./dsh-BlpXm2Bv.mjs";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 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";
@@ -8,6 +7,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 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;
@@ -57,7 +57,6 @@ const RESOURCE_BUDGET = {
 	},
 	files: {
 		readBytesPerRequest: 4194304,
-		readBytesPerRun: 16777216,
 		callsPerMinute: 120,
 		listPageSize: 100
 	},
@@ -286,7 +285,6 @@ function requestedGrants(requested = {}) {
 		name: "files.read",
 		limits: {
 			bytesPerRequest: 4194304,
-			bytesPerRun: 16777216,
 			callsPerMinute: 120
 		}
 	});
@@ -384,7 +382,7 @@ function panelDevelopmentDescriptor(generation, profileUrl, statusUrl) {
 		widgetId,
 		widgetVersionId,
 		snapshot: {
-			id,
+			panelType: id,
 			title: generation.manifest.name,
 			state: "complete",
 			data: {}
@@ -1271,13 +1269,14 @@ function commandTopics(context) {
 			options: [
 				"--template <模板>           panel 或 file-preview（默认 panel）",
 				"--ui <模式>                 vanilla 或 react（默认 vanilla）",
-				"--panel-id <id>             仅用于 panel；默认取规范化后的工程名",
+				"--panel-id <id>             自定义面板标识，仅用于 panel；默认取规范化后的工程名",
 				"--extensions <列表>         仅用于 file-preview；逗号分隔扩展名（默认 txt）",
 				"--tool <名称>               按指定工具成功结果激活，不注册工具卡片",
 				HOST_OPTION,
 				JSON_OPTION
 			],
 			examples: [
+				"bohr-widget create my-widget --ui react --panel-id my-widget",
 				"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"
@@ -1285,8 +1284,9 @@ function commandTopics(context) {
 			notes: [
 				`默认组合为 panel + vanilla；生成工程的构建环境要求 Node.js ${context.generatedProjectNode}。`,
 				"不会自动安装依赖；创建后进入目录，运行 pnpm install 或 npm install。",
-				"workspace-files 会补齐 files.list、files.metadata、files.read 和目录引用样例；文件树逻辑与夹具需自行实现。",
-				"其他 Panel id 需要 Host 预先注册和绑定；更改 id 不会自动接管宿主界面。",
+				"Panel ID 可自定义，用于工作台识别面板；打包后按目标工作台的安装流程加载。",
+				"workspace-files 是可选的文件浏览面板预设，会补齐 files.list、files.metadata、files.read 和目录引用样例；文件树界面与逻辑需自行实现。",
+				"生成 README.md 和 AGENTS.md；先读取项目指引与公开文档，再安装依赖和执行工程命令。",
 				"将 widget-toolchain.json 与包管理器 lockfile 一起保存。"
 			],
 			quickStart: true
@@ -1382,7 +1382,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 不代表上传或发布许可。"
 			],
@@ -1395,7 +1395,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 后才写锁；不要求已构建入口。",
 				"不会自动升级依赖、迁移源码或修正协议字段；检查不通过时先修复工程。"
 			]
@@ -1412,7 +1412,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"],
@@ -1483,9 +1483,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, packageName = "@dp-bohrium/widget-cli", 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 或平台执行。
 
 用法：
@@ -1505,7 +1505,7 @@ SDK ${sdk} / contracts ${contracts}
   schema                           打印作者 Manifest Schema 的本地路径
   migrate project plan|apply        比较 Agent 准备的候选并安全复制到新目录
   migrate dsh audit|scaffold        审计 DSH 来源或按已审查配方生成工程
-  version                          查看 CLI 与固定的 SDK/contracts 版本
+  version                          查看 SDK 执行器与内置协议版本
   help [命令...]                   查看全局或指定主题帮助
 
 全局选项：
@@ -1521,7 +1521,7 @@ SDK ${sdk} / contracts ${contracts}
   CLI 要求 Node.js >=20；默认生成工程要求 Node.js ${generatedProjectNode}。
 
 典型开发流程：
-  pnpm dlx ${packageName} create my-widget --ui react --panel-id workspace-files
+  pnpm dlx ${packageName} create my-widget --template panel --ui react
   cd my-widget
   pnpm install
   pnpm exec bohr-widget build .
@@ -1556,7 +1556,7 @@ function renderHelp(path = [], context) {
 /**
 * 作者清单（VS Code 风格 `contributes` 清单）的本地静态检查。
 *
-* `@dp-bohrium/widget-contracts` 的 host schema 只在 `compileAuthorManifest` 之后生效，
+* SDK 的 host schema 只在 `compileAuthorManifest` 之后生效，
 * 而编译只保留宿主运行时需要的字段：作者的 `version`、`displayName` 和未知顶层键会被
 * 静默丢弃，于是"清单写错但 check 全绿"。这里只补下游永远看不到的作者侧约束，报错文案
 * 直接指向作者填的字段名。
@@ -1645,10 +1645,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), {
@@ -1722,12 +1719,12 @@ async function assertHostCompatibility(hostCompatPath, toolchain, { now = Date.n
 }
 function assertMatchingLock(lock, toolchain, root) {
 	const { profile } = toolchain;
-	if (!record$1(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
 	}, ["使用当前受支持的 CLI，并在新目录显式迁移工程与验收；不要回选旧 CLI 绕过 profile 差异。"]);
-	if (lock.sdk !== profile.sdk || lock.contracts !== profile.contracts) throw failure("PROJECT_SDK_MISMATCH", "工程锁定的 SDK/contracts 与当前 profile 不一致", {
+	if (lock.sdk !== profile.sdk || !isDeepStrictEqual(lock.protocol, toolchain.protocol)) throw failure("PROJECT_SDK_MISMATCH", "工程锁定的 SDK 或内置协议与当前 profile 不一致", {
 		projectRoot: root,
 		expected: profile,
 		actual: lock
@@ -1766,39 +1763,58 @@ function assertInstalledPackage(actual, name, expected, root) {
 		installed: actual?.version
 	}, ["按工程锁定信息恢复依赖并重新安装，再重新构建。"]);
 }
-/** 只接受 SDK 自身依赖或其安装目录中的提升依赖，不向工作区祖先借用。 */
-async function sdkContractsMetadata(sdkPath, root) {
-	const sdkRoot = dirname(await realpath(sdkPath));
-	const resolver = createRequire(join(sdkRoot, "package.json"));
-	const lookupRoots = /* @__PURE__ */ new Set([join(sdkRoot, "node_modules")]);
-	for (let current = sdkRoot; dirname(current) !== current; current = dirname(current)) if (basename(current) === "node_modules") {
-		lookupRoots.add(current);
-		break;
+/** 名称和字节同时参与摘要；禁止通过协议资产链接借用其他安装。 */
+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 resolvedPath = await realpath(resolver.resolve(`${PACKAGES.contracts}/package.json`));
-		for (const lookup of resolver.resolve.paths(PACKAGES.contracts) ?? []) {
-			if (!lookupRoots.has(lookup)) continue;
-			try {
-				if (await realpath(join(lookup, PACKAGES.contracts, "package.json")) === resolvedPath) return await json(resolvedPath, "PROJECT_SDK_MISMATCH", ["重新安装工程 SDK 及其配套 contracts 依赖。"]);
-			} catch (error) {
-				if (error.code !== "ENOENT") throw error;
-			}
-		}
+		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) {
-		if (error.cliCode) throw error;
+		throw failure("PROJECT_SDK_MISMATCH", "工程 SDK 缺少有效的自包含协议资产或摘要不一致", {
+			projectRoot: root,
+			package: PACKAGES.sdk,
+			cause: error.message
+		}, ["在当前工程安装正确的 SDK 完整包，再重新构建；不能借用祖先目录或旧 contracts 包。"]);
 	}
-	throw failure("PROJECT_SDK_MISMATCH", "工程 SDK 缺少自身可解析的配套 contracts，不能借用祖先目录或 CLI 的依赖", {
-		projectRoot: root,
-		package: PACKAGES.contracts
-	}, ["在该 Widget 工程目录重新安装依赖，并保留 SDK 自身的传递依赖。"]);
 }
-/** SDK 必须由工程直接安装，contracts 从该 SDK 的真实依赖核对。 */
+/** 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 依赖。"]);
 	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；协议从 SDK 的 /contracts 与 /schemas 出口读取。保留作者源码，在独立候选中移除重复依赖、重新安装和构建。"]);
 	const declared = {};
 	const installed = {};
 	for (const [key, name] of Object.entries(PACKAGES)) {
@@ -1821,53 +1837,22 @@ async function validateProjectToolchain(projectRoot, toolchain, { requireInstall
 		const actual = await json(path, "PROJECT_SDK_MISMATCH", ["在该 Widget 工程目录安装依赖，再重试；父目录或 CLI 的安装不能替代工程安装。"]);
 		assertInstalledPackage(actual, name, expected, root);
 		installed[key] = actual.version;
-		if (key === "sdk") {
-			const dependency = actual.dependencies?.[PACKAGES.contracts];
-			if (dependency !== toolchain.profile.contracts && dependency !== "workspace:*" && dependency !== `workspace:${toolchain.profile.contracts}`) throw failure("PROJECT_SDK_MISMATCH", "工程 SDK 的 contracts 依赖与固定 profile 不一致", {
-				projectRoot: root,
-				package: name,
-				expected: toolchain.profile.contracts,
-				declared: dependency
-			}, ["安装固定 profile 对应的 SDK；发布包的 contracts 依赖必须为精确版本。"]);
-			const contracts = await sdkContractsMetadata(path, root);
-			assertInstalledPackage(contracts, PACKAGES.contracts, toolchain.profile.contracts, root);
-			installed.contracts = contracts.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: declared.contracts ? [{
-			code: "WIDGET_CLI_DIRECT_CONTRACTS_DEPRECATED",
-			message: "独立消费者直接声明 contracts 的旧入口已废弃，将在统一入口切换发布 R1 前移除；协议类型与资产改从 SDK 导入。",
-			replacement: {
-				package: PACKAGES.sdk,
-				entryPoints: [
-					".",
-					"./contracts",
-					"./schemas/*.json",
-					"./conformance/*"
-				]
-			},
-			removal: {
-				release: "R1",
-				phase: "before-publish",
-				policyDocument: "docs/plans/2026-10-29-widget-sdk-forge-unified-entry.md",
-				prerequisites: [
-					"unified-sdk-entries-deliverable",
-					"agent-guided-project-migration-ready",
-					"bohr-and-hosts-upgraded"
-				]
-			},
-			migration: {
-				status: "agent-guided",
-				project: "migrate project plan/apply",
-				candidateRequired: true
-			},
-			recovery: ["先核实目标 SDK 的统一出口已公开，再迁移类型和 Schema 导入、删除工程直接 contracts 依赖，并重新安装、构建、校验和打包。", "由 Agent 或开发者依据当前 SDK 准备候选，再用 migrate project plan --candidate 只读审阅差异，确认 canApply 后在新目录 apply；不自动改写源码或依赖，adopt 只补锁。"]
-		}] : [],
+		deprecations: [],
 		dependenciesVerified: requireInstalled,
 		lock
 	};
@@ -1877,10 +1862,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 });
@@ -1921,6 +1906,7 @@ function receiptToolchain(toolchain) {
 	return {
 		cli: toolchain.cli,
 		profile: toolchain.profile,
+		protocol: toolchain.protocol,
 		digests: toolchain.digests
 	};
 }
@@ -1965,7 +1951,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,
@@ -1984,7 +1970,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$1(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 {
@@ -2429,11 +2415,35 @@ function projectPackage({ name, ui, sdkVersion }) {
 		}
 	};
 }
-function projectReadme({ name, template, ui, sourceFile, hostFile }) {
+function projectAgentGuide({ sdkVersion, sourceFile, hostFile, documentation, agentSetupUrl }) {
+	return `# 项目开发指引
+
+创建时 SDK：\`@dp-bohrium/widget-sdk@${sdkVersion}\`。
+
+以下路径均相对于本工程根目录：
+
+- \`${sourceFile}\`：本工程的 Widget 界面与业务逻辑，通常在这里修改功能。
+- \`${hostFile}\`：本工程的启动文件，调用 SDK 的 \`runWidgetHost\` 启动 Widget。
+- \`manifest.json\`：本工程的 Widget 声明。
+- \`samples/default.json\`：本工程的样例输入。
+
+本工程的依赖版本与工具链记录在 \`package.json\`、\`widget-toolchain.json\` 和包管理器 lockfile 中。
+
+阅读入口：
+
+- [README.md](./README.md)：本工程的环境、安装、命令和验收说明。
+- [开发 Agent 引导](${agentSetupUrl})：通用的能力选型与开发阅读路径。
+- [文档索引](${documentation.llms})：按当前任务查找指南、API 和示例。
+`;
+}
+function projectReadme({ name, template, ui, sourceFile, hostFile, sdkVersion, documentation, agentSetupUrl }) {
 	return `# ${name}
 
 Bohrium Widget ${template} 插件工程（${ui}）。
 
+创建时 SDK：\`@dp-bohrium/widget-sdk@${sdkVersion}\`。项目上下文与 Agent 阅读入口见 [AGENTS.md](./AGENTS.md)；安装依赖前即可读取[开发 Agent 引导](${agentSetupUrl})、[文档索引](${documentation.llms})和[快速开始](${documentation.quickStart})。
+文档独立更新；接口以本工程固定 SDK 和目标 Host 实际支持为准。
+
 默认构建器要求 Node.js \`${GENERATED_PROJECT_NODE}\`，高于执行器自身的 Node.js 20 要求。
 工程已经精确依赖提供命令的 \`${PROJECT_EXECUTOR_PACKAGE}\`；在本目录安装后使用本地命令，无需全局安装或源码仓库。
 
@@ -2447,7 +2457,7 @@ 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 启动。
+- Widget 界面与业务逻辑在 ${sourceFile} 中；本工程的 ${hostFile} 调用 SDK 的 runWidgetHost 启动 Widget。
 - 高度链、布局与滚动策略直接写在 ${sourceFile} 中，样式随 activate 安装并在释放时清理；JSON 展示元素单独处理换行。
 - manifest.json 是作者清单，打包时由 CLI 编译为宿主清单。
 - 提交 widget-toolchain.json 与依赖 lockfile；dist/widget.js 与生成的 ZIP 不提交。
@@ -2635,7 +2645,6 @@ export { activate };
 						name: "files.read",
 						limits: {
 							bytesPerRequest: 65536,
-							bytesPerRun: 262144,
 							callsPerMinute: 60
 						}
 					}
@@ -2758,12 +2767,11 @@ 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
@@ -2914,7 +2922,7 @@ async function commandIntegration(options) {
 	const result = {
 		ok: true,
 		command: "integration",
-		interfaceVersion: 2,
+		interfaceVersion: 3,
 		requirements: {
 			node: ">=20",
 			generatedProjectNode: GENERATED_PROJECT_NODE
@@ -3001,6 +3009,17 @@ async function commandCreate(directory, options) {
 	await writeFile(join(root, "samples/default.json"), `${JSON.stringify(sample, null, 2)}\n`);
 	const sourceFile = options.ui === "react" ? "src/widget.tsx" : "src/widget.ts";
 	const hostFile = "src/widget-host.ts";
+	const documentation = getDocumentation();
+	const agentSetupUrl = new URL("agent-setup/prompt.md", documentation.url).href;
+	const projectGuidance = {
+		sdkVersion: sdkPackage.version,
+		sourceFile,
+		hostFile,
+		documentation,
+		agentSetupUrl
+	};
+	const readmePath = join(root, "README.md");
+	const agentGuidePath = join(root, "AGENTS.md");
 	const source = options.ui === "react" && template.reactSource ? template.reactSource({ name }) : typeof template.source === "function" ? template.source({
 		ui: options.ui,
 		name
@@ -3009,13 +3028,13 @@ async function commandCreate(directory, options) {
 	await writeFile(join(root, hostFile), template.hostSource({ sourceFile }));
 	await writeFile(join(root, "scripts/rename-iife.mjs"), `import { rename } from "node:fs/promises";\n\nawait rename("dist/widget.iife.js", "dist/widget.js");\n`);
 	await writeFile(join(root, ".gitignore"), "node_modules/\ndist/\n.artifacts/\n.widget-build-receipt.json\n*.zip\n");
-	await writeFile(join(root, "README.md"), projectReadme({
+	await writeFile(readmePath, projectReadme({
+		...projectGuidance,
 		name,
 		template: options.template,
-		ui: options.ui,
-		sourceFile,
-		hostFile
+		ui: options.ui
 	}));
+	await writeFile(agentGuidePath, projectAgentGuide(projectGuidance));
 	await writeFile(join(root, "tsconfig.json"), `${JSON.stringify({
 		compilerOptions: {
 			target: "ES2022",
@@ -3039,7 +3058,60 @@ async function commandCreate(directory, options) {
 	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 nextSteps = [
+		{
+			cwd: root,
+			command: "pnpm",
+			args: ["install"]
+		},
+		{
+			cwd: root,
+			command: "pnpm",
+			args: [
+				"exec",
+				"bohr-widget",
+				"integration",
+				"--project",
+				".",
+				"--json"
+			]
+		},
+		{
+			cwd: root,
+			command: "pnpm",
+			args: [
+				"exec",
+				"bohr-widget",
+				"build",
+				".",
+				"--json"
+			]
+		},
+		{
+			cwd: root,
+			command: "pnpm",
+			args: [
+				"exec",
+				"bohr-widget",
+				"check",
+				".",
+				"--json"
+			]
+		},
+		{
+			cwd: root,
+			command: "pnpm",
+			args: [
+				"exec",
+				"bohr-widget",
+				"pack",
+				".",
+				"--out",
+				"artifacts/my-widget.zip",
+				"--json"
+			]
+		}
+	];
 	const result = {
 		ok: true,
 		command: "create",
@@ -3051,6 +3123,11 @@ async function commandCreate(directory, options) {
 		...panelId ? { panelId } : {},
 		manifestPath: join(root, "manifest.json"),
 		packagePath: join(root, "package.json"),
+		readmePath,
+		agentGuidePath,
+		documentation,
+		agentSetupUrl,
+		nextSteps,
 		profile: toolchain.profile,
 		hostCompatibility,
 		...warnings.length === 0 ? {} : { warnings }
@@ -3058,8 +3135,14 @@ async function commandCreate(directory, options) {
 	if (options.json) console.log(JSON.stringify(result, null, 2));
 	else {
 		console.log(`已创建 Widget 工程：${root}（manifest name: ${name}）`);
+		if (panelId) console.log(`Panel ID：${panelId}（可自定义）`);
+		console.log(`创建时 SDK：@dp-bohrium/widget-sdk@${sdkPackage.version}`);
+		console.log(`项目说明：${readmePath}\nAgent 指引：${agentGuidePath}`);
+		console.log(`文档站：${documentation.url}\nAgent 阅读入口：${agentSetupUrl}`);
+		console.log(`文档索引：${documentation.llms}`);
 		for (const warning of warnings) console.warn(`提示：${warning}`);
-		console.log(`下一步：cd ${JSON.stringify(root)}，执行 pnpm install，再执行 pnpm exec bohr-widget build . --json 和 pnpm exec bohr-widget check . --json。`);
+		console.log(`先读取项目指引和公开文档，再进入工程目录：${root}`);
+		console.log(`依次执行：\n${nextSteps.map((step) => [step.command, ...step.args].join(" ")).join("\n")}`);
 	}
 	return result;
 }
@@ -3482,9 +3565,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 = {
@@ -3492,12 +3575,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),
@@ -3553,10 +3636,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;
@@ -3575,7 +3655,7 @@ 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),
@@ -3650,7 +3730,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})`);