@dp-bohrium/widget-sdk 0.7.0 → 0.9.0

package/dist/{runtime-DZA7Gqzl.js → runtime-9g5MfsgK.js}

@@ -1,8 +1,8 @@
-import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-CDz-YDGT.js";
+import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-DbT0OJNu.js";
 //#endregion
 //#region src/runtime/version.ts
 /** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
-const WIDGET_SDK_VERSION = "0.7.0";
+const WIDGET_SDK_VERSION = "0.9.0";
 //#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
@@ -308,6 +308,7 @@ var WidgetClient = class {
 	endpoint;
 	widgetSdkVersion;
 	channelId;
+	developmentDiagnostics;
 	handshakeTimeoutMs;
 	capabilityTimeoutMs;
 	createMessageId;
@@ -327,6 +328,7 @@ var WidgetClient = class {
 	constructor(options, events = {}) {
 		this.widgetSdkVersion = options.widgetSdkVersion;
 		this.channelId = options.channelId;
+		this.developmentDiagnostics = options.developmentDiagnostics === true;
 		this.hostApiVersion = options.hostApiVersion ?? 1;
 		this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5e3;
 		this.capabilityTimeoutMs = options.capabilityTimeoutMs ?? 5e3;
@@ -538,6 +540,18 @@ var WidgetClient = class {
 			this.failHandshake(toError$1(reason, "widget initialization failed"), "initialization-failed", "WIDGET_CRASHED");
 		}
 	}
+	reportDevelopmentDiagnostic(diagnostic) {
+		if (this.developmentDiagnostics && this.state === "ready") this.endpoint.send({
+			type: "diagnostic",
+			payload: diagnostic
+		});
+	}
+	reportRenderResult(result) {
+		if (this.developmentDiagnostics && this.state === "ready") this.endpoint.send({
+			type: "render-result",
+			payload: result
+		});
+	}
 	send(message) {
 		this.endpoint.send(message);
 	}
@@ -1071,6 +1085,11 @@ var WidgetRuntimeClient = class {
 		this.runtimeWindow.addEventListener("message", this.messageListener);
 		this.connectionTimer = setTimeout(() => this.failConnection(/* @__PURE__ */ new Error("widget connection timed out")), options.connectionTimeoutMs ?? options.handshakeTimeoutMs ?? 5e3);
 		try {
+			this.runtimeWindow.parent.postMessage({
+				type: "widget-bootstrap-offer",
+				protocolVersion: 1,
+				extensions: ["development-diagnostics-v1"]
+			}, "*");
 			this.runtimeWindow.parent.postMessage({
 				type: WIDGET_BOOTSTRAP_READY,
 				protocolVersion: 1
@@ -1232,16 +1251,25 @@ var WidgetRuntimeClient = class {
 		if (this.disposed || this.client) return;
 		if (event.source !== this.runtimeWindow.parent) return;
 		if (this.options.expectedHostOrigin !== void 0 && event.origin !== this.options.expectedHostOrigin) return;
-		if (!isWidgetHostConnectMessage(event.data)) return;
+		const extended = isRecord(event.data) && Array.isArray(event.data["extensions"]) && event.data["extensions"].length === 1 && event.data["extensions"][0] === "development-diagnostics-v1" && hasExactKeys(event.data, [
+			"type",
+			"protocolVersion",
+			"channelId",
+			"initPayload",
+			"extensions"
+		]);
+		const candidate = extended ? Object.fromEntries(Object.entries(event.data).filter(([key]) => key !== "extensions")) : event.data;
+		if (!isWidgetHostConnectMessage(candidate)) return;
 		const port = event.ports?.[0];
 		if (!port) return;
 		this.removeConnectionListener();
 		try {
 			const clientOptions = {
 				transport: new MessagePortTransport(port),
-				channelId: event.data.channelId,
+				channelId: candidate.channelId,
 				widgetSdkVersion: this.options.widgetSdkVersion ?? WIDGET_SDK_VERSION,
-				initialPayload: event.data.initPayload,
+				initialPayload: candidate.initPayload,
+				developmentDiagnostics: extended,
 				...this.options.hostApiVersion === void 0 ? {} : { hostApiVersion: this.options.hostApiVersion },
 				...this.options.capabilityTimeoutMs === void 0 ? {} : { capabilityTimeoutMs: this.options.capabilityTimeoutMs },
 				...this.options.handshakeTimeoutMs === void 0 ? {} : { handshakeTimeoutMs: this.options.handshakeTimeoutMs },
@@ -1259,6 +1287,12 @@ var WidgetRuntimeClient = class {
 			this.failConnection(toError(reason));
 		}
 	}
+	reportDevelopmentDiagnostic(diagnostic) {
+		this.client?.reportDevelopmentDiagnostic(diagnostic);
+	}
+	reportRenderResult(result) {
+		this.client?.reportRenderResult(result);
+	}
 	requireClient() {
 		if (this.disposed) throw new Error("client is disposed");
 		if (!this.client) throw new Error("widget host connection is not ready");

package/dist/widget-recovery-BF_sSUZX.js

@@ -0,0 +1,472 @@
+//#region src/protocol/plugin-manifest.ts
+/**
+* Widget Host 公开的固定激活事件。数组同时作为清单编辑器文档和 Host
+* 运行时校验的单一事实源；带工具名的事件使用下方的动态形式。
+*/
+const WIDGET_ACTIVATION_EVENTS = [
+	"session.start",
+	"turn-start",
+	"turn-end",
+	"step-start",
+	"step-end",
+	"tool-call-generating",
+	"tool-call-waiting",
+	"tool-call-running",
+	"tool-call-result",
+	"tool-call-error",
+	"workspace-file-changed",
+	"workspace-tree-refresh",
+	"workspace-file-opened",
+	"ui-tool-opened",
+	"ui-panel-focused",
+	"host-surface-changed"
+];
+const TOOL_EVENT_PATTERN = /^(?:tool-call-(?:generating|waiting|running|result|error)):[A-Za-z0-9_.:-]+$/u;
+/**
+* 判断一个字符串是否为合法激活事件（固定事件或带工具名的动态形式）。
+* @param value 待检查的字符串。
+* @returns 若命中固定目录或工具事件模式则收窄为 `WidgetActivationEvent`。
+*/
+function isWidgetActivationEvent(value) {
+	return typeof value === "string" && (WIDGET_ACTIVATION_EVENTS.includes(value) || TOOL_EVENT_PATTERN.test(value));
+}
+//#endregion
+//#region src/protocol/widget-events.ts
+/**
+* Host 主动推送给已激活 Widget 的实时事件。`session.start` 只用于激活索引，
+* 不属于这组运行期事件；激活后首个可用快照通过 `context.render` 交付。
+*/
+const WIDGET_EVENT_NAMES = [
+	"turn-start",
+	"turn-end",
+	"step-start",
+	"step-end",
+	"tool-call-generating",
+	"tool-call-waiting",
+	"tool-call-running",
+	"tool-call-result",
+	"tool-call-error",
+	"workspace-file-changed",
+	"workspace-tree-refresh",
+	"workspace-file-opened",
+	"ui-tool-opened",
+	"ui-panel-focused",
+	"host-surface-changed"
+];
+/**
+* 判断一个字符串是否为合法的实时事件名。
+* @param value 待检查的字符串。
+* @returns 若 `value` 命中 `WIDGET_EVENT_NAMES` 则收窄为 `WidgetEventName`。
+*/
+function isWidgetEventName(value) {
+	return typeof value === "string" && WIDGET_EVENT_NAMES.includes(value);
+}
+//#endregion
+//#region src/protocol/widget-recovery.ts
+function rule(input) {
+	const followUpActions = input.disposition === "repair" ? [
+		{
+			id: "build-project",
+			params: { target: "current-project" }
+		},
+		{
+			id: "refresh-preview",
+			params: { target: "current-project" }
+		},
+		{
+			id: "verify-scenario",
+			params: { target: "next-built-generation" }
+		}
+	] : [];
+	const value = {
+		id: input.id,
+		version: 1,
+		sources: [input.source],
+		codes: input.codes,
+		disposition: input.disposition ?? "inspect",
+		nextAction: input.nextAction ?? {
+			id: "inspect",
+			params: { area: input.area }
+		},
+		verification: input.verification ?? {
+			target: "current-attempt",
+			milestone: "diagnostics-updated"
+		},
+		guidance: input.guidance,
+		followUpActions
+	};
+	Object.freeze(value.sources);
+	Object.freeze(value.codes);
+	Object.freeze(value.nextAction.params);
+	Object.freeze(value.nextAction);
+	Object.freeze(value.verification);
+	for (const action of followUpActions) {
+		Object.freeze(action.params);
+		Object.freeze(action);
+	}
+	Object.freeze(followUpActions);
+	return Object.freeze(value);
+}
+/** 通用恢复目录；宿主绑定已有工具及权限，Guest 不指定这些规则。 */
+const STANDARD_RULES = Object.freeze([
+	rule({
+		id: "runtime-render",
+		source: "sdk",
+		codes: ["RENDER_FAILED", "UPDATE_FAILED"],
+		area: "render",
+		disposition: "repair",
+		nextAction: {
+			id: "edit-project",
+			params: { evidence: "diagnostics" }
+		},
+		verification: {
+			target: "next-built-generation",
+			milestone: "scenario-passed"
+		},
+		guidance: "读取当前请求的源码诊断，修复处理器后构建并刷新预览，再重跑原失败场景；ready 不代表恢复。"
+	}),
+	rule({
+		id: "bundle-load",
+		source: "sdk",
+		codes: ["BUNDLE_LOAD_FAILED", "DIGEST_MISMATCH"],
+		area: "bundle",
+		guidance: "检查入口资源、响应类型、实际摘要、模块依赖及 CSP 证据，再选择修复；不能从超时猜测根因。"
+	}),
+	rule({
+		id: "runtime-lease",
+		source: "sdk",
+		codes: ["RUNTIME_CONFIG_EXPIRED", "FILE_REFERENCE_INVALID"],
+		area: "lease",
+		guidance: "核对当前 scope、配置和引用；通过已授权的 acquire/续期取得新凭据，不重用一次性票据。"
+	}),
+	rule({
+		id: "runtime-authorization",
+		source: "sdk",
+		codes: ["WIDGET_VERSION_REVOKED", "FILE_PERMISSION_DENIED"],
+		area: "capability",
+		disposition: "external-action",
+		nextAction: {
+			id: "request-external-action",
+			params: { reason: "authorization" }
+		},
+		guidance: "保留现场并请求目标授权恢复；不要重试被撤销资源或绕过权限。继续不受影响的工作。"
+	}),
+	rule({
+		id: "runtime-profile",
+		source: "sdk",
+		codes: ["HOST_API_UNSUPPORTED"],
+		area: "configuration",
+		guidance: "核对实际 Host 兼容声明与工具链；按声明选择迁移或宿主升级，不修改版本字段伪装支持。"
+	}),
+	rule({
+		id: "runtime-handshake",
+		source: "sdk",
+		codes: ["HANDSHAKE_TIMEOUT"],
+		area: "handshake",
+		guidance: "先确认资源加载，再检查 profile、frame 来源与连接阶段；补充证据后再建立新 attempt。"
+	}),
+	rule({
+		id: "runtime-protocol",
+		source: "sdk",
+		codes: [
+			"MESSAGE_INVALID",
+			"CHANNEL_MISMATCH",
+			"MESSAGE_TOO_LARGE",
+			"MESSAGE_RATE_LIMITED",
+			"TOO_MANY_PENDING_REQUESTS"
+		],
+		area: "runtime",
+		guidance: "检查协议、消息大小、频率及 pending 诊断；保留既有保护，修复生产方后再连接，不能提高预算掩盖错误。"
+	}),
+	rule({
+		id: "runtime-capability",
+		source: "sdk",
+		codes: [
+			"CAPABILITY_UNDECLARED",
+			"CAPABILITY_DENIED",
+			"CAPABILITY_UNSUPPORTED",
+			"CAPABILITY_TIMEOUT",
+			"RESOURCE_LIMIT"
+		],
+		area: "capability",
+		guidance: "区分未声明、未授权、未接线、预算与超时；检查操作是否可能已执行，再选择声明修复、可用替代或授权流程。"
+	}),
+	rule({
+		id: "runtime-lifetime",
+		source: "sdk",
+		codes: ["WIDGET_CRASHED", "INSTANCE_DISPOSED"],
+		area: "runtime",
+		guidance: "查询当前挂载尝试和末次诊断；区分正常释放与崩溃，修复后创建新 attempt，不复活旧实例。"
+	}),
+	rule({
+		id: "capability-authorization",
+		source: "host",
+		codes: [
+			"permission-denied",
+			"network-consent-denied",
+			"network-credential-unavailable"
+		],
+		area: "capability",
+		disposition: "external-action",
+		nextAction: {
+			id: "request-external-action",
+			params: { reason: "authorization" }
+		},
+		guidance: "按具体 operation 核对授权或凭据可用性；使用既有授权入口，不从聊天索取凭据或绕过拒绝。"
+	}),
+	rule({
+		id: "capability-policy",
+		source: "host",
+		codes: [
+			"unsupported",
+			"network-policy-denied",
+			"network-redirect-denied",
+			"network-scope-invalid",
+			"network-dns-denied"
+		],
+		area: "capability",
+		guidance: "核对宿主接线、当前作用域和网络策略；选择允许的操作或替代路径，不反复原样调用。"
+	}),
+	rule({
+		id: "capability-budget",
+		source: "host",
+		codes: [
+			"resource-limit",
+			"network-request-too-large",
+			"network-response-too-large"
+		],
+		area: "capability",
+		guidance: "读取已知预算维度，缩小请求或分块；未知维度继续排查，不销毁健康 Bridge 或自动提高额度。"
+	}),
+	rule({
+		id: "capability-rate",
+		source: "host",
+		codes: ["network-rate-limited"],
+		area: "capability",
+		disposition: "retry",
+		nextAction: {
+			id: "wait",
+			params: { milestone: "budget-reset" }
+		},
+		guidance: "仅在确认原操作未执行且允许重试时，按宿主预算等待；预算未知时先 inspect，不能忙轮询。"
+	}),
+	rule({
+		id: "capability-reference",
+		source: "host",
+		codes: ["invalid-reference"],
+		area: "lease",
+		guidance: "重新校验当前作用域与文件引用，通过已有授权入口取得有效引用。"
+	}),
+	rule({
+		id: "capability-conflict",
+		source: "host",
+		codes: [
+			"revision-conflict",
+			"mutation-conflict",
+			"write-outcome-unknown"
+		],
+		area: "operation-outcome",
+		verification: {
+			target: "original-operation",
+			milestone: "operation-confirmed"
+		},
+		guidance: "按原 revision 和 mutation 身份核对资源及操作结果，再决定是否提交新修改；不自动重放写入。"
+	}),
+	rule({
+		id: "capability-transport",
+		source: "host",
+		codes: [
+			"timeout",
+			"internal-error",
+			"network-transport-unavailable",
+			"network-error"
+		],
+		area: "operation-outcome",
+		guidance: "保留 transport/HTTP/格式分类，先确认原操作是否执行；无响应不等于未产生副作用。"
+	}),
+	rule({
+		id: "toolchain-build",
+		source: "toolchain",
+		codes: [
+			"WIDGET_CLI_BUILD_FAILED",
+			"WIDGET_CLI_BUILD_UNRESOLVED_IMPORT",
+			"WIDGET_DEV_BUILD_FAILED"
+		],
+		area: "toolchain",
+		disposition: "repair",
+		nextAction: {
+			id: "edit-project",
+			params: { evidence: "diagnostics" }
+		},
+		verification: {
+			target: "next-built-generation",
+			milestone: "scenario-passed"
+		},
+		guidance: "读取编译器与相对源码诊断，修复后用原执行工具构建，核对回执与新产物，再刷新并复验。"
+	}),
+	rule({
+		id: "toolchain-validation",
+		source: "toolchain",
+		codes: [
+			"WIDGET_CLI_MANIFEST_INVALID",
+			"WIDGET_CLI_VALIDATION_FAILED",
+			"WIDGET_CLI_PACK_VALIDATION_FAILED",
+			"WIDGET_DEV_PROJECT_INVALID"
+		],
+		area: "configuration",
+		disposition: "repair",
+		nextAction: {
+			id: "edit-project",
+			params: { evidence: "diagnostics" }
+		},
+		verification: {
+			target: "next-built-generation",
+			milestone: "scenario-passed"
+		},
+		guidance: "依据字段与预期值修复工程清单、入口或样例，再检查并构建；不要打包不完整产物。"
+	}),
+	rule({
+		id: "toolchain-profile",
+		source: "toolchain",
+		codes: [
+			"WIDGET_CLI_PROJECT_TOOLCHAIN_REQUIRED",
+			"WIDGET_CLI_PROJECT_PROFILE_MISMATCH",
+			"WIDGET_CLI_PROJECT_SDK_MISMATCH",
+			"WIDGET_CLI_BUILD_RECEIPT_MISMATCH",
+			"WIDGET_CLI_HOST_PROFILE_UNSUPPORTED",
+			"WIDGET_CLI_HOST_COMPAT_INVALID",
+			"WIDGET_CLI_NO_WIDGET_PROJECT"
+		],
+		area: "toolchain",
+		guidance: "运行 doctor/integration 并核对当前工程与目标宿主；显式采用或迁移工具链，再构建，不伪造 receipt。"
+	}),
+	rule({
+		id: "development-host",
+		source: "toolchain",
+		codes: [
+			"WIDGET_DEV_FAILED",
+			"WIDGET_DEV_UNAUTHORIZED",
+			"WIDGET_DEV_CLAIM_REJECTED",
+			"WIDGET_DEV_PROFILE_NOT_FOUND"
+		],
+		area: "host-bridge",
+		guidance: "读取失败阶段、端点状态和具体响应；区分未监听、403、超时与不兼容，再检查目标宿主。"
+	})
+]);
+const UNKNOWN_RULE = rule({
+	id: "unknown",
+	source: "host",
+	codes: [],
+	area: "runtime",
+	guidance: "查询当前状态、实际产物和最后失败阶段，补充证据后选择恢复路径；不要猜测命令或反复执行。"
+});
+const OUTCOME_RULE = rule({
+	id: "operation-outcome",
+	source: "host",
+	codes: [],
+	area: "operation-outcome",
+	verification: {
+		target: "original-operation",
+		milestone: "operation-confirmed"
+	},
+	guidance: "原操作可能已执行或部分完成。先按原操作身份核对资源，再决定后续动作，不自动重放。"
+});
+const REPEATED_RULE = rule({
+	id: "repeated-without-progress",
+	source: "host",
+	codes: [],
+	area: "runtime",
+	guidance: "相同故障没有新证据或产物，先补充诊断或改变排查策略，不重复同一编辑、构建或重试。"
+});
+/** 包含 unknown 与操作核对规则，Agent 可按 plan.ruleId 定位每个实际计划。 */
+const WIDGET_RECOVERY_RULES = Object.freeze([
+	...STANDARD_RULES,
+	UNKNOWN_RULE,
+	OUTCOME_RULE,
+	REPEATED_RULE
+]);
+/** 根据稳定码选择通用规则；未知码明确走排查，不匹配自由文本。 */
+function findWidgetRecoveryRule(diagnostic) {
+	return WIDGET_RECOVERY_RULES.find((value) => value.sources.includes(diagnostic.source) && value.codes.includes(diagnostic.code)) ?? UNKNOWN_RULE;
+}
+/** 纯规则选择，不运行工具；宿主仍须校验实际能力、权限、scope 与恢复预算。 */
+function createWidgetRecoveryPlan(diagnostic, context = {}) {
+	let selected = findWidgetRecoveryRule(diagnostic);
+	if (context.executionState === "unknown" || context.executionState === "partial" || context.mayHaveExecuted === true && context.executionState !== "finished") selected = OUTCOME_RULE;
+	else if (context.progress?.repeated && !context.progress.hasNewEvidence) selected = REPEATED_RULE;
+	else if (selected.disposition === "retry" && (diagnostic.retryable !== true || context.executionState !== "not_started" || context.mayHaveExecuted !== false)) selected = OUTCOME_RULE;
+	if (selected.disposition === "repair" && !diagnostic.diagnostics?.length) return {
+		schemaVersion: 1,
+		ruleId: selected.id,
+		ruleVersion: selected.version,
+		...context.progress ? { progress: { ...context.progress } } : {},
+		disposition: "inspect",
+		nextAction: {
+			id: "inspect",
+			params: { area: diagnostic.source === "toolchain" ? "toolchain" : "render" }
+		},
+		followUpActions: [],
+		verification: {
+			target: "current-attempt",
+			milestone: "diagnostics-updated"
+		},
+		guidance: "缺少可定位的诊断，先查询编译或源码证据，再修复；不能仅凭错误码猜测补丁。"
+	};
+	return {
+		schemaVersion: 1,
+		ruleId: selected.id,
+		ruleVersion: selected.version,
+		disposition: selected.disposition,
+		...context.progress ? { progress: { ...context.progress } } : {},
+		nextAction: structuredClone(selected.nextAction),
+		followUpActions: structuredClone(selected.followUpActions),
+		verification: { ...selected.verification },
+		guidance: selected.guidance
+	};
+}
+/** 只投影已校验的稳定字段；Guest message、context 和恢复文字不进入可信诊断。 */
+function projectWidgetRuntimeDiagnostic(error, operation, diagnostics) {
+	return {
+		schemaVersion: 1,
+		source: "sdk",
+		code: error.code,
+		phase: error.phase,
+		operation,
+		severity: error.code === "RENDER_FAILED" || error.code === "UPDATE_FAILED" ? "request-error" : "instance-failure",
+		message: "Widget runtime operation failed",
+		retryable: error.retryable,
+		correlationId: error.correlationId,
+		...diagnostics ? { diagnostics: structuredClone(diagnostics) } : {}
+	};
+}
+/** 能力拒绝只影响当前请求；不把它投影为实例终态。 */
+function projectWidgetCapabilityDiagnostic(failure, operation) {
+	return {
+		schemaVersion: 1,
+		source: "host",
+		code: failure.reason,
+		phase: "capability",
+		operation,
+		severity: "request-error",
+		message: "Host capability request failed",
+		retryable: failure.retryable
+	};
+}
+/** 工程错误仅提取稳定 code；原始 stdout/stderr 由可信工具单独脱敏投影。 */
+function projectWidgetToolchainDiagnostic(error, operation, phase) {
+	return {
+		schemaVersion: 1,
+		source: "toolchain",
+		code: error.code,
+		phase,
+		operation,
+		severity: "request-error",
+		message: "Widget project operation failed"
+	};
+}
+/** 仅选择双方声明的扩展；实际 frame 来源和当前 attempt 仍由 Host 校验。 */
+function selectWidgetDevelopmentExtensions(offer, supported) {
+	return offer?.extensions.includes("development-diagnostics-v1") && supported.includes("development-diagnostics-v1") ? ["development-diagnostics-v1"] : [];
+}
+//#endregion
+export { projectWidgetRuntimeDiagnostic as a, WIDGET_EVENT_NAMES as c, isWidgetActivationEvent as d, projectWidgetCapabilityDiagnostic as i, isWidgetEventName as l, createWidgetRecoveryPlan as n, projectWidgetToolchainDiagnostic as o, findWidgetRecoveryRule as r, selectWidgetDevelopmentExtensions as s, WIDGET_RECOVERY_RULES as t, WIDGET_ACTIVATION_EVENTS as u };

package/llms.txt

@@ -28,7 +28,10 @@
 - 先在 Manifest 声明 capability，再等待 Host grant。
 - 用 `WidgetError` 的 `code/phase/retryable/correlationId` 诊断启动、渲染和能力失败。
 - `context.render` 异常通过 `runWidgetHost` 的既有 `onError` / `events.onError` 和 Guest console
-  本地报告，不自动终止或重试；不要改成向旧 Host 发送致命协议 `error`。
+  本地报告，不自动终止或重试。Host 协商 `development-diagnostics-v1` 后还会收到与请求关联的
+  `render-result`；使用 Host 的查询入口取得标准诊断与 SDK 恢复规则。旧 Host 不接收新增消息。
+- 修复后构建并刷新当前预览，再查新代际回执。`handled` 证明当前处理器完成，仍需验收实际 DOM
+  和业务场景；`ready`、`unknown`、`unsupported` 和等待超时都不是恢复成功。
 - `ok=false` 的能力结果是可处理状态，不要直接重试或绕过 Host。
 - 文件读写使用 `context.files.read(input, options)` / `write(input, options)`；Manifest
   分别申请 `files.read` / `files.write`。file-preview 的引用来自当前文件；Panel 只有获得
@@ -43,3 +46,12 @@
   write-outcome-unknown，不自动重试；保留内容和同一 mutationId 核对结果，成功回执后才标记已保存。
 - revision-conflict 需重读并合并；mutation-conflict 表示同一 mutationId 被用于不同内容。
 - SDK 本地通过不等于 iframe 已真实渲染、Bundle 已发布或 Agent 已绑定。
+
+## Widget 尺寸与滚动
+
+- `panel` 和使用填充布局的 `file-preview` 由 Host 分配 iframe 高度。为 `html`、`body` 和挂载根设置 `height: 100%`，让滚动区或画布容器使用 `flex: 1; min-height: 0`。
+- 按内容定高的嵌入式 `file-preview` 可以在第一次 `context.render` 中用 `context.resize(width, height)` 请求合适的初始尺寸。`request.context.viewport` 表示 Host 报告的当前视口，避免把视口或 iframe 测量值回报给 Host。
+- 观察实际画布容器的大小并重绘。用真实 Host 改变窗口高度，核对内容区、iframe 和滚动区或画布的高度。
+
+生成工程的 `src/widget.ts` 或 `src/widget.tsx` 带有布局示例。完整说明见
+[样式指南](https://dev.dp.tech/bohrium-widget-sdk/guides/styling#面板高度与滚动)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
   },
   "files": [
     "dist",
+    "!dist/validation",
     "assets",
     "schemas",
     "conformance",
@@ -66,26 +67,26 @@
     "tsdown": "0.22.14",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@dp-bohrium/widget-contracts": "0.7.0",
-    "@dp-bohrium/widget-contract-testing": "0.1.0-alpha.0"
+    "ajv": "^8.17.1"
   },
   "scripts": {
-    "build:runtime": "pnpm --filter @dp-bohrium/widget-contracts run build && tsdown && tsc -b tsconfig.build.json --force --pretty false && node ../../scripts/schema/build-sdk-assets.mjs",
-    "build:cli": "node ../../scripts/schema/build-sdk-cli-assets.mjs && tsdown --config widget-cli.tsdown.config.ts && node --check dist/cli.mjs",
-    "build": "pnpm build:runtime && pnpm --filter @dp-bohrium/widget-contract-testing build && pnpm build:cli",
-    "typecheck": "tsc --noEmit",
+    "build:runtime": "node ../../scripts/build/widget-build.mjs runtime",
+    "build": "node ../../scripts/build/widget-build.mjs sdk",
+    "typecheck": "pnpm schema:check && tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage --coverage.thresholds.lines=80 --coverage.thresholds.functions=80 --coverage.thresholds.statements=80 --coverage.thresholds.branches=70",
     "test:watch": "vitest",
-    "fixture:build": "tsdown --config minimal-widget.tsdown.config.ts",
-    "fixture:pack": "node ../../scripts/fixtures/pack-minimal-sdk-widget.mjs",
+    "fixture:build": "node ../../scripts/build/with-build.mjs sdk -- tsdown --config minimal-widget.tsdown.config.ts",
+    "fixture:pack": "node ../../scripts/build/with-build.mjs sdk -- node ../../scripts/fixtures/pack-minimal-sdk-widget.mjs",
     "fixture:pack:test": "node --test ../../scripts/fixtures/pack-minimal-sdk-widget.test.mjs",
-    "fixture:check": "node ../../scripts/fixtures/check-minimal-sdk-widget.mjs",
+    "fixture:check": "node ../../scripts/build/with-build.mjs sdk -- node ../../scripts/fixtures/check-minimal-sdk-widget.mjs",
     "lint": "biome check src test",
     "format:check": "biome check --linter-enabled=false src test",
     "package:contents": "node ../../scripts/quality/check-sdk-package-contents.mjs ../../.artifacts/dp-bohrium-widget-sdk-*.tgz",
     "consumer:canary": "node ../../scripts/consumer/consumer-sdk-install.mjs ../../.artifacts/dp-bohrium-widget-sdk-*.tgz",
     "release:check-version": "WIDGET_PACKAGE_NAME=@dp-bohrium/widget-sdk node ../../scripts/release/check-registry-version.mjs",
-    "check": "pnpm typecheck && pnpm test && pnpm fixture:build && pnpm fixture:pack:test && pnpm lint && pnpm format:check && pnpm --filter @dp-bohrium/widget-contract-testing build && pnpm build && pnpm fixture:pack && pnpm fixture:check"
+    "check": "pnpm typecheck && pnpm test && pnpm fixture:build && pnpm fixture:pack:test && pnpm lint && pnpm format:check && pnpm build && pnpm fixture:pack && pnpm fixture:check",
+    "schema:check": "node ../../scripts/schema/generate-types.mjs --check && node ../../scripts/schema/check-drift.mjs",
+    "build:tools": "node ../../scripts/build/widget-build.mjs tools"
   }
 }