@dp-bohrium/widget-cli 0.5.0 → 0.6.0

package/assets/toolchain.json

@@ -1,15 +1,15 @@
 {
   "formatVersion": 3,
   "packageName": "@dp-bohrium/widget-cli",
-  "cli": "0.5.0",
+  "cli": "0.6.0",
   "profile": {
-    "id": "widget-sdk-0.7.0",
-    "sdk": "0.7.0"
+    "id": "widget-sdk-0.9.0",
+    "sdk": "0.9.0"
   },
   "protocol": {
     "schemaVersion": 1,
     "hostApiVersion": 1,
-    "digest": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb"
+    "digest": "sha256:a4d13070cc867aa5ddb838201ed47eee8871c32d48fd1485ce6c531b7ebad2b9"
   },
   "hostAcceptance": "unknown",
   "documentation": {
@@ -20,9 +20,9 @@
     "llms": "https://dev.dp.tech/bohrium-widget-sdk/llms.txt"
   },
   "digests": {
-    "compiler": "sha256:6b6ac1585a3f2bc0f8b2717b2475584a502a9026045b840337547528b7a063b0",
-    "validators": "sha256:8712fb004d9decf1eeae56c1e7057092a8abc0eeae1093c29546bb56e3261922",
-    "schemas": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb",
-    "templates": "sha256:60f555788f33fb38d707525f571d13b6fa78875be7d2d87cb864db6926a52ccb"
+    "compiler": "sha256:a45a53ac079b9249e629ecdcfc78510aca276e8c3db786bd66daded8e75d08e3",
+    "validators": "sha256:27340218c481b2b3b3964b598533f07d4cec820de148ef7ad9d00adc2e8162f9",
+    "schemas": "sha256:a4d13070cc867aa5ddb838201ed47eee8871c32d48fd1485ce6c531b7ebad2b9",
+    "templates": "sha256:85be81d7ede0a1631c08a464ce7857ffcce71691bb8d75717d97513c6496a8e5"
   }
 }

package/dist/cli.mjs

@@ -1,13 +1,123 @@
 #!/usr/bin/env node
-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 { a as normalizeArchivePath, c as loadContractValidators, i as prepareWidgetPackage, l as compileAuthorManifest, n as scaffoldDshWidget, o as checkWidgetProject, s as resolveWidgetProjects, t as auditDshPlugin } from "./dsh-BL6cMLrg.mjs";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
-import { constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
+import { constants, existsSync, fstatSync, 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-development-observations.mjs
+const JOURNAL_CAPACITY = 32;
+const ATTEMPT_CAPACITY = 32;
+const ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/u;
+const exact = (value, keys) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+/** 每个 SDK 开发会话独占；只有受保护的 Host control 能写入。 */
+async function createDevelopmentObservations() {
+	const { validateWidgetDevelopmentDiagnostic, createWidgetRecoveryPlan, isWidgetRenderResult } = await loadContractValidators();
+	let cursor = 0;
+	let current = {
+		state: "unknown",
+		cursor
+	};
+	const attempts = /* @__PURE__ */ new Map();
+	const entries = [];
+	let previousFailure;
+	return {
+		snapshot(includeEntries = true) {
+			return structuredClone({
+				...current,
+				cursor,
+				oldestCursor: entries[0]?.cursor ?? cursor,
+				...includeEntries ? { entries } : {}
+			});
+		},
+		reset(generation) {
+			attempts.clear();
+			current = {
+				state: "unknown",
+				generation,
+				cursor
+			};
+		},
+		accept(input, generation) {
+			if (!exact(input, [
+				"generation",
+				"attemptId",
+				"instanceId",
+				"sequence",
+				"event"
+			]) || input.generation !== generation || typeof input.attemptId !== "string" || !ID_PATTERN.test(input.attemptId) || !(typeof input.instanceId === "string" && /^[a-zA-Z0-9_.:%-]{1,1024}$/u.test(input.instanceId)) || !Number.isSafeInteger(input.sequence) || input.sequence < 1) throw new Error("invalid observation identity");
+			const event = input.event;
+			const connected = exact(event, ["type", "supported"]) && event.type === "connected" && typeof event.supported === "boolean";
+			const diagnostic = exact(event, ["type", "diagnostic"]) && event.type === "diagnostic" && validateWidgetDevelopmentDiagnostic(event.diagnostic).ok;
+			const result = exact(event, ["type", "result"]) && event.type === "render-result" && isWidgetRenderResult(event.result);
+			if (!connected && !diagnostic && !result) throw new Error("invalid observation contract");
+			const known = attempts.get(input.attemptId);
+			if (known && (known.instanceId !== input.instanceId || input.sequence <= known.sequence)) throw new Error("stale observation");
+			if (!connected && (current.attemptId !== input.attemptId || !known)) throw new Error("inactive observation attempt");
+			if (!connected && !known.supported && (result || event.diagnostic.source === "sdk")) throw new Error("development extension was not negotiated");
+			if (connected && (known || attempts.size >= ATTEMPT_CAPACITY)) throw new Error("reused or excessive observation attempt");
+			attempts.set(input.attemptId, {
+				instanceId: input.instanceId,
+				sequence: input.sequence,
+				supported: connected ? event.supported : known.supported
+			});
+			if (connected) current = {
+				state: event.supported ? "connected" : "unsupported",
+				generation,
+				attemptId: input.attemptId,
+				instanceId: input.instanceId
+			};
+			const failure = diagnostic ? event.diagnostic : result && event.result.outcome === "failed" ? event.result.diagnostic : void 0;
+			if (failure) {
+				const fingerprint = JSON.stringify([
+					failure.source,
+					failure.code,
+					failure.phase,
+					failure.operation,
+					failure.diagnostics
+				]);
+				const repeated = previousFailure?.fingerprint === fingerprint && previousFailure.generation === generation;
+				const recovery = createWidgetRecoveryPlan(failure, {
+					executionState: "finished",
+					mayHaveExecuted: true,
+					progress: {
+						repeated,
+						hasNewEvidence: !repeated
+					}
+				});
+				previousFailure = {
+					fingerprint,
+					generation
+				};
+				current = {
+					...current,
+					state: "failed",
+					diagnostic: failure,
+					recovery,
+					renderResult: result ? event.result : void 0
+				};
+			} else if (result && event.result.outcome === "handled") {
+				const { diagnostic: _diagnostic, recovery: _recovery, ...identity } = current;
+				current = {
+					...identity,
+					state: "handled",
+					renderResult: event.result
+				};
+			}
+			const entry = {
+				cursor: ++cursor,
+				...input
+			};
+			entries.push(entry);
+			if (entries.length > JOURNAL_CAPACITY) entries.shift();
+			return this.snapshot(false);
+		}
+	};
+}
+//#endregion
 //#region ../../scripts/widget/widget-dev.mjs
 const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const DEFAULT_PORT = 4300;
@@ -105,6 +215,7 @@ function usage$1() {
   --watch             监听 src、manifest.json 和 package.json，变化后重新 build
   --no-build          使用现有的 manifest.widgetConfig.entry，不执行 build
   --port <port>       固定 Profile 服务端口（默认 ${DEFAULT_PORT}）
+  --listen-fd <fd>    接管宿主已监听的 IPv4 loopback TCP socket；仅与 --no-build 一起使用
   --help              显示帮助
 
 开发流程：
@@ -116,6 +227,7 @@ function usage$1() {
 }
 function parseArgs(argv) {
 	const positional = [];
+	let portSpecified = false;
 	const options = {
 		open: false,
 		watch: false,
@@ -160,10 +272,17 @@ function parseArgs(argv) {
 			const value = Number(argv[++index]);
 			if (!Number.isInteger(value) || value < 1024 || value > 65535) throw new Error("--port 必须是 1024 到 65535 之间的整数");
 			options.port = value;
+			portSpecified = true;
+		} else if (argument === "--listen-fd") {
+			const value = argv[++index];
+			const fd = Number(value);
+			if (!/^\d+$/u.test(value) || fd < 3 || fd > 2 ** 31 - 1) throw new Error("--listen-fd 需要宿主传入的文件描述符（fd ≥ 3）");
+			options.listenFd = fd;
 		} else if (argument.startsWith("-")) throw new Error(`未知选项：${argument}`);
 		else positional.push(argument);
 	}
 	if (positional.length !== 1) throw new Error("需要一个 Widget 工程目录或 manifest.json");
+	if (options.listenFd !== void 0 && (portSpecified || options.build || options.watch)) throw new Error("--listen-fd 必须与 --no-build 一起使用，不能与 --port 或 --watch 同用");
 	return {
 		help: false,
 		project: positional[0],
@@ -721,6 +840,28 @@ function runBuild(projectRoot, { capture = false } = {}) {
 		});
 	});
 }
+async function listenForDevelopment(server, { port, listenFd }) {
+	if (listenFd !== void 0 && !fstatSync(listenFd).isSocket()) throw new Error("--listen-fd 需要宿主传入已监听的 127.0.0.1 TCP socket");
+	await new Promise((resolveListen, rejectListen) => {
+		server.once("error", rejectListen);
+		const onListen = () => {
+			server.off("error", rejectListen);
+			resolveListen();
+		};
+		if (listenFd === void 0) server.listen(port, "127.0.0.1", onListen);
+		else server.listen({
+			fd: listenFd,
+			exclusive: true
+		}, onListen);
+	});
+	const address = server.address();
+	if (address?.family !== "IPv4" || address.address !== "127.0.0.1" || !address.port) {
+		server.close();
+		server.closeAllConnections();
+		throw new Error("--listen-fd 需要宿主传入已监听的 127.0.0.1 TCP socket");
+	}
+	return `http://${address.address}:${address.port}`;
+}
 async function startWidgetDevelopment(projectRoot, options) {
 	const buildProject = options.buildProject ?? runBuild;
 	const emit = options.emit ?? ((line, error = false) => error ? console.error(line) : console.log(line));
@@ -761,6 +902,8 @@ async function startWidgetDevelopment(projectRoot, options) {
 		},
 		lastBuildError: null
 	};
+	const observations = await createDevelopmentObservations();
+	observations.reset(state.generation);
 	const eventClients = /* @__PURE__ */ new Map();
 	let eventId = 0;
 	let session;
@@ -783,7 +926,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 	});
 	const developmentSnapshot = () => {
-		const origin = `http://127.0.0.1:${server.address().port}`;
+		const { origin } = session.descriptor;
 		const development = panelDevelopmentDescriptor(successfulGeneration, `${origin}${V1_PROFILE_PATH}`, `${origin}${V1_STATUS_PATH}`);
 		return {
 			protocolVersion: 1,
@@ -798,7 +941,8 @@ async function startWidgetDevelopment(projectRoot, options) {
 			assets: successfulGeneration.assets,
 			watch: state.watch,
 			lastBuild: state.lastBuild,
-			lastBuildError: state.lastBuildError
+			lastBuildError: state.lastBuildError,
+			runtime: observations.snapshot()
 		};
 	};
 	const generationReadyData = () => {
@@ -813,6 +957,10 @@ async function startWidgetDevelopment(projectRoot, options) {
 		};
 	};
 	const server = createServer((request, response) => {
+		if (!session) {
+			response.destroy();
+			return;
+		}
 		const url = new URL(request.url ?? "/", "http://127.0.0.1");
 		if (request.method === "OPTIONS") {
 			response.writeHead(405, secureHeaders("text/plain; charset=utf-8")).end();
@@ -877,8 +1025,30 @@ async function startWidgetDevelopment(projectRoot, options) {
 			request.on("end", () => {
 				try {
 					const control = JSON.parse(body || "{}");
-					if (control.protocolVersion !== 1 || !["reload", "disconnect"].includes(control.action)) throw new Error("invalid control action");
-					if (control.action === "disconnect") {
+					if (control.protocolVersion !== 1 || ![
+						"reload",
+						"disconnect",
+						"report-runtime",
+						"refresh-built-output"
+					].includes(control.action)) throw new Error("invalid control action");
+					if (control.action === "report-runtime") {
+						json$1(response, 200, {
+							ok: true,
+							protocolVersion: 1,
+							runtime: observations.accept(control.observation, state.generation)
+						});
+						return;
+					}
+					if (control.action === "refresh-built-output") {
+						const candidate = createDevelopmentGeneration(projectRoot, successfulGeneration.number + 1, GENERATION_LIMITS, options.manifestOptions);
+						successfulGeneration = candidate;
+						retainedGenerations.set(candidate.guestCapability, candidate);
+						while (retainedGenerations.size > RETAINED_GENERATIONS) retainedGenerations.delete(retainedGenerations.keys().next().value);
+						state.generation = candidate.number;
+						observations.reset(candidate.number);
+						state.lastBuildError = null;
+						sendEvent("generation-ready", generationReadyData());
+					} else if (control.action === "disconnect") {
 						sendEvent("disconnected", { reason: "host-request" });
 						session.disconnect();
 					} else sendEvent("reload-requested", { generation: state.generation });
@@ -915,7 +1085,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 				});
 				return;
 			}
-			const origin = `http://127.0.0.1:${server.address().port}`;
+			const { origin } = session.descriptor;
 			const launchUrl = `${origin}${guestGenerationRoot(successfulGeneration)}/launch.html`;
 			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
@@ -928,7 +1098,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}`;
+			const { origin } = session.descriptor;
 			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
 				runId,
@@ -987,11 +1157,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 		serveGenerationAsset(successfulGeneration, assetPath, response);
 	});
-	await new Promise((resolveListen, rejectListen) => {
-		server.once("error", rejectListen);
-		server.listen(options.port, "127.0.0.1", resolveListen);
-	});
-	const origin = `http://127.0.0.1:${server.address().port}`;
+	const origin = await listenForDevelopment(server, options);
 	session = createWidgetDevelopmentSession({ origin });
 	const profileUrl = `${origin}${PROFILE_PATH}`;
 	const descriptorUrl = `${origin}${DESCRIPTOR_PATH}`;
@@ -1054,6 +1220,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			retainedGenerations.set(candidate.guestCapability, candidate);
 			while (retainedGenerations.size > RETAINED_GENERATIONS) retainedGenerations.delete(retainedGenerations.keys().next().value);
 			state.generation = candidate.number;
+			observations.reset(candidate.number);
 			state.lastBuild = {
 				ok: true,
 				digest: candidate.digest,
@@ -1269,13 +1436,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"
@@ -1283,8 +1451,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
@@ -1313,6 +1482,7 @@ function commandTopics(context) {
 				"--open                      连接或唤起 Widget 开发宿主（默认关闭）",
 				"--no-build                  跳过首次构建，使用现有入口（默认先构建）",
 				"--port <端口>               本地服务端口，1024–65535（默认 4300）",
+				"--listen-fd <fd>            接管宿主的 IPv4 回环监听；须与 --no-build 同用，排除 --port 和 --watch",
 				"--scheme <scheme>           宿主 deep link scheme（默认 widget-host）",
 				"--bridge <url>              指定 loopback HTTP(S) bridge；默认探测标准端口",
 				HOST_OPTION,
@@ -1473,7 +1643,8 @@ function documentationLines(documentation, topic = {}) {
 		...topic.agentDocs ? [
 			`文档站：${documentation.url}`,
 			`Agent 索引：${documentation.llms}`,
-			`完整文档：${documentation.llmsFull}`
+			`完整文档：${documentation.llmsFull}`,
+			"工程内的作者指引见 node_modules/@dp-bohrium/widget-sdk/llms.txt。"
 		] : []
 	];
 }
@@ -1519,7 +1690,7 @@ SDK ${sdk}（协议与执行工具链均由 SDK 内置）
   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 .
@@ -1554,7 +1725,7 @@ function renderHelp(path = [], context) {
 /**
 * 作者清单（VS Code 风格 `contributes` 清单）的本地静态检查。
 *
-* `@dp-bohrium/widget-contracts` 的 host schema 只在 `compileAuthorManifest` 之后生效，
+* SDK 的 host schema 只在 `compileAuthorManifest` 之后生效，
 * 而编译只保留宿主运行时需要的字段：作者的 `version`、`displayName` 和未知顶层键会被
 * 静默丢弃，于是"清单写错但 check 全绿"。这里只补下游永远看不到的作者侧约束，报错文案
 * 直接指向作者填的字段名。
@@ -1812,7 +1983,7 @@ async function validateProjectToolchain(projectRoot, toolchain, { requireInstall
 	]) 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 等消费者使用。保留作者源码，在独立候选中移除重复依赖、重新安装和构建。"]);
+	}, ["作者工程统一依赖 SDK；协议从 SDK 的 /contracts 与 /schemas 出口读取。保留作者源码，在独立候选中移除重复依赖、重新安装和构建。"]);
 	const declared = {};
 	const installed = {};
 	for (const [key, name] of Object.entries(PACKAGES)) {
@@ -2413,11 +2584,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}\`；在本目录安装后使用本地命令，无需全局安装或源码仓库。
 
@@ -2431,8 +2626,9 @@ 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 展示元素单独处理换行。
+- 在 [SDK 本地索引](./node_modules/@dp-bohrium/widget-sdk/llms.txt) 查看「Widget 尺寸与滚动」。
 - manifest.json 是作者清单，打包时由 CLI 编译为宿主清单。
 - 提交 widget-toolchain.json 与依赖 lockfile；dist/widget.js 与生成的 ZIP 不提交。
 - check 只验证结构、声明和样例，不执行 JavaScript；pack 成功不代表首帧渲染、真实授权或业务验收成功。
@@ -2983,6 +3179,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
@@ -2991,13 +3198,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",
@@ -3021,7 +3228,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",
@@ -3033,6 +3293,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 }
@@ -3040,8 +3305,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;
 }