@dp-bohrium/widget-cli 0.5.1 → 0.6.0

package/dist/{dsh-BlpXm2Bv.mjs → dsh-BL6cMLrg.mjs}

@@ -5,7 +5,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region ../../.build/widget-stage-tools/tooling/compiler.mjs
 /** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
-const WIDGET_SDK_VERSION = "0.8.0";
+const WIDGET_SDK_VERSION = "0.9.0";
 function compiledContribution(contribution) {
 	switch (contribution.type) {
 		case "panel": return {
@@ -165,6 +165,490 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 /** GENERATED FILE. Do not edit directly. */
+const widgetDevelopmentPolicy = {
+	"required": [
+		"schemaVersion",
+		"source",
+		"code",
+		"phase",
+		"operation",
+		"severity",
+		"message"
+	],
+	"keys": [
+		"schemaVersion",
+		"source",
+		"code",
+		"sourceCode",
+		"phase",
+		"sourcePhase",
+		"operation",
+		"severity",
+		"message",
+		"retryable",
+		"correlationId",
+		"diagnostics",
+		"io"
+	],
+	"textMax": {
+		"code": 96,
+		"sourceCode": 96,
+		"sourcePhase": 96,
+		"operation": 96,
+		"message": 1024,
+		"field": 128,
+		"expected": 256,
+		"observed": 256,
+		"file": 256,
+		"excerpt": 1024
+	},
+	"maxDetails": 8,
+	"phases": [
+		"discovery",
+		"build",
+		"config",
+		"load",
+		"handshake",
+		"render",
+		"update",
+		"capability",
+		"dispose"
+	],
+	"severities": [
+		"warning",
+		"request-error",
+		"instance-failure"
+	],
+	"identifierPattern": "^[A-Za-z][A-Za-z0-9_.-]*$",
+	"filePattern": "^(?!/)(?!.*\\\\)(?!.*:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f]+$"
+};
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function keys(value, required, allowed = required) {
+	return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => allowed.includes(key));
+}
+const identifier = new RegExp(widgetDevelopmentPolicy.identifierPattern, "u");
+const sourceFile = new RegExp(widgetDevelopmentPolicy.filePattern, "u");
+function text(value, max, empty = false) {
+	return typeof value === "string" && (empty || value.length > 0) && [...value].length <= max;
+}
+function correlation(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function id(value) {
+	return text(value, widgetDevelopmentPolicy.textMax.code) && identifier.test(value);
+}
+function detail(value) {
+	if (!record(value)) return false;
+	if ("file" in value) return keys(value, [
+		"file",
+		"line",
+		"column"
+	], [
+		"file",
+		"line",
+		"column",
+		"excerpt"
+	]) && text(value["file"], widgetDevelopmentPolicy.textMax.file) && sourceFile.test(value["file"]) && Number.isSafeInteger(value["line"]) && Number(value["line"]) > 0 && Number.isSafeInteger(value["column"]) && Number(value["column"]) > 0 && (value["excerpt"] === void 0 || text(value["excerpt"], widgetDevelopmentPolicy.textMax.excerpt));
+	return keys(value, ["field"], [
+		"field",
+		"expected",
+		"observed"
+	]) && text(value["field"], widgetDevelopmentPolicy.textMax.field) && (value["expected"] === void 0 || text(value["expected"], widgetDevelopmentPolicy.textMax.expected, true)) && (value["observed"] === void 0 || text(value["observed"], widgetDevelopmentPolicy.textMax.observed, true));
+}
+function io(value) {
+	if (!record(value) || !keys(value, ["kind"], [
+		"kind",
+		"status",
+		"sourceCode"
+	]) || value["sourceCode"] !== void 0 && !id(value["sourceCode"])) return false;
+	if (value["kind"] === "http") return Number.isInteger(value["status"]) && Number(value["status"]) >= 100 && Number(value["status"]) <= 599 && !(Number(value["status"]) >= 200 && Number(value["status"]) < 300);
+	return (value["kind"] === "transport" || value["kind"] === "invalid-response") && value["status"] === void 0;
+}
+/** 与源头 Schema 同源限额的轻量边界判定，不加载 AJV 或 Runtime。 */
+function isWidgetGuestDiagnostic(value) {
+	if (!record(value) || !keys(value, widgetDevelopmentPolicy.required, widgetDevelopmentPolicy.keys) || value["schemaVersion"] !== 1 || value["source"] !== "sdk" || !id(value["code"]) || !id(value["operation"]) || !widgetDevelopmentPolicy.phases.some((phase) => phase === value["phase"]) || !widgetDevelopmentPolicy.severities.some((severity) => severity === value["severity"]) || !text(value["message"], widgetDevelopmentPolicy.textMax.message)) return false;
+	if (value["retryable"] !== void 0 && typeof value["retryable"] !== "boolean" || value["correlationId"] !== void 0 && !correlation(value["correlationId"]) || value["sourceCode"] !== void 0 && !id(value["sourceCode"]) || value["sourcePhase"] !== void 0 && !id(value["sourcePhase"])) return false;
+	return (value["diagnostics"] === void 0 || Array.isArray(value["diagnostics"]) && value["diagnostics"].length <= widgetDevelopmentPolicy.maxDetails && value["diagnostics"].every(detail)) && (value["io"] === void 0 || io(value["io"]));
+}
+/** 失败回执仍需 Host 再匹配实际已发送的 request/revision。 */
+function isWidgetRenderResult(value) {
+	if (!record(value) || !correlation(value["requestId"]) || !Number.isSafeInteger(value["revision"]) || Number(value["revision"]) < 1) return false;
+	if (value["outcome"] === "handled" || value["outcome"] === "superseded") return keys(value, [
+		"requestId",
+		"revision",
+		"outcome"
+	]);
+	return value["outcome"] === "failed" && keys(value, [
+		"requestId",
+		"revision",
+		"outcome",
+		"diagnostic"
+	]) && isWidgetGuestDiagnostic(value["diagnostic"]) && value["diagnostic"].correlationId === value["requestId"] && (value["diagnostic"].phase === "render" || value["diagnostic"].phase === "update");
+}
+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
+	};
+}
+/** GENERATED FILE. Do not edit directly. */
 const widgetRuntimeContractsSchema = {
 	"$schema": "https://json-schema.org/draft/2020-12/schema",
 	"$id": "widget-runtime-contracts.schema.json",
@@ -218,7 +702,15 @@ const widgetRuntimeContractsSchema = {
 		"hostUserProfileReadOutput": { "$ref": "#/$defs/HostUserProfileReadOutput" },
 		"hostUserEmailReadInput": { "$ref": "#/$defs/HostUserEmailReadInput" },
 		"hostUserEmailReadOutput": { "$ref": "#/$defs/HostUserEmailReadOutput" },
-		"hostUserServiceRequest": { "$ref": "#/$defs/HostUserServiceRequest" }
+		"hostUserServiceRequest": { "$ref": "#/$defs/HostUserServiceRequest" },
+		"widgetDevelopmentDiagnostic": { "$ref": "#/$defs/WidgetDevelopmentDiagnostic" },
+		"widgetRecoveryContext": { "$ref": "#/$defs/WidgetRecoveryContext" },
+		"widgetRecoveryPlan": { "$ref": "#/$defs/WidgetRecoveryPlan" },
+		"widgetRecoveryRule": { "$ref": "#/$defs/WidgetRecoveryRule" },
+		"widgetDevelopmentOffer": { "$ref": "#/$defs/WidgetDevelopmentOffer" },
+		"widgetDevelopmentConnect": { "$ref": "#/$defs/WidgetDevelopmentConnect" },
+		"widgetRenderResult": { "$ref": "#/$defs/WidgetRenderResult" },
+		"widgetDevelopmentMessage": { "$ref": "#/$defs/WidgetDevelopmentMessage" }
 	},
 	"$defs": {
 		"JsonValue": {
@@ -3398,6 +3890,650 @@ const widgetRuntimeContractsSchema = {
 					"cancelled"
 				] }
 			}
+		},
+		"WidgetDiagnosticDetail": {
+			"title": "WidgetDiagnosticDetail",
+			"description": "受控字段诊断或工程相对源码位置；不携带原始对象。",
+			"oneOf": [{
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["field"],
+				"properties": {
+					"field": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128
+					},
+					"expected": {
+						"type": "string",
+						"maxLength": 256
+					},
+					"observed": {
+						"type": "string",
+						"maxLength": 256
+					}
+				}
+			}, {
+				"type": "object",
+				"additionalProperties": false,
+				"required": [
+					"file",
+					"line",
+					"column"
+				],
+				"properties": {
+					"file": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 256,
+						"pattern": "^(?!/)(?!.*\\\\)(?!.*:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f]+$"
+					},
+					"line": {
+						"type": "integer",
+						"minimum": 1
+					},
+					"column": {
+						"type": "integer",
+						"minimum": 1
+					},
+					"excerpt": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024
+					}
+				}
+			}]
+		},
+		"WidgetDiagnosticIO": {
+			"title": "WidgetDiagnosticIO",
+			"description": "保留 transport、HTTP 与非法响应事实；不包含 URL 或原始响应。",
+			"oneOf": [{
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["kind"],
+				"properties": {
+					"kind": { "enum": ["transport", "invalid-response"] },
+					"sourceCode": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 96,
+						"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+					}
+				}
+			}, {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["kind", "status"],
+				"properties": {
+					"kind": { "enum": ["http"] },
+					"status": {
+						"type": "integer",
+						"minimum": 100,
+						"maximum": 599,
+						"not": {
+							"minimum": 200,
+							"maximum": 299
+						}
+					},
+					"sourceCode": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 96,
+						"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+					}
+				}
+			}]
+		},
+		"WidgetDevelopmentDiagnostic": {
+			"title": "WidgetDevelopmentDiagnostic",
+			"description": "可信出口的标准诊断；恢复指令和 scope 由宿主另行生成。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schemaVersion",
+				"source",
+				"code",
+				"phase",
+				"operation",
+				"severity",
+				"message"
+			],
+			"properties": {
+				"schemaVersion": { "const": 1 },
+				"source": { "enum": [
+					"sdk",
+					"host",
+					"toolchain"
+				] },
+				"code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"sourceCode": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"phase": { "enum": [
+					"discovery",
+					"build",
+					"config",
+					"load",
+					"handshake",
+					"render",
+					"update",
+					"capability",
+					"dispose"
+				] },
+				"sourcePhase": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"operation": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"severity": { "enum": [
+					"warning",
+					"request-error",
+					"instance-failure"
+				] },
+				"message": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 1024
+				},
+				"retryable": { "type": "boolean" },
+				"correlationId": { "$ref": "#/$defs/WidgetError/properties/correlationId" },
+				"diagnostics": {
+					"type": "array",
+					"maxItems": 8,
+					"items": { "$ref": "#/$defs/WidgetDiagnosticDetail" }
+				},
+				"io": { "$ref": "#/$defs/WidgetDiagnosticIO" }
+			}
+		},
+		"WidgetRecoveryAction": {
+			"title": "WidgetRecoveryAction",
+			"description": "恢复动作的语义及类型化参数；可信宿主绑定已有工具，不包含任意命令。",
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "inspect" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["area"],
+							"properties": { "area": { "enum": [
+								"toolchain",
+								"host-bridge",
+								"configuration",
+								"bundle",
+								"handshake",
+								"render",
+								"capability",
+								"lease",
+								"operation-outcome",
+								"runtime"
+							] } }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "wait" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["milestone"],
+							"properties": {
+								"milestone": { "enum": ["budget-reset", "connection-restored"] },
+								"retryAfterMs": {
+									"type": "integer",
+									"minimum": 1
+								}
+							}
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "edit-project" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["evidence"],
+							"properties": { "evidence": { "const": "diagnostics" } }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "build-project" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["target"],
+							"properties": { "target": { "const": "current-project" } }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "refresh-preview" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["target"],
+							"properties": { "target": { "const": "current-project" } }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "verify-scenario" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["target"],
+							"properties": {
+								"target": { "enum": ["current-attempt", "next-built-generation"] },
+								"scenarioId": {
+									"type": "string",
+									"minLength": 1,
+									"maxLength": 96,
+									"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+								}
+							}
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "request-external-action" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["reason"],
+							"properties": { "reason": { "enum": [
+								"authorization",
+								"host-support",
+								"host-start",
+								"credentials"
+							] } }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "params"],
+					"properties": {
+						"id": { "const": "stop-preview" },
+						"params": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["target"],
+							"properties": { "target": { "const": "current-preview" } }
+						}
+					}
+				}
+			]
+		},
+		"WidgetRecoveryVerification": {
+			"title": "WidgetRecoveryVerification",
+			"description": "恢复复验目标；下一成功构建须在取得回执后绑定实际产物。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["target", "milestone"],
+			"properties": {
+				"target": { "enum": [
+					"current-attempt",
+					"next-built-generation",
+					"original-operation"
+				] },
+				"milestone": { "enum": [
+					"diagnostics-updated",
+					"render-handled",
+					"scenario-passed",
+					"operation-confirmed"
+				] },
+				"scenarioId": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				}
+			}
+		},
+		"WidgetRecoveryPlan": {
+			"title": "WidgetRecoveryPlan",
+			"description": "可信宿主选择的恢复计划；不能由 Guest 的诊断 payload 指定。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schemaVersion",
+				"ruleId",
+				"ruleVersion",
+				"disposition",
+				"nextAction",
+				"verification",
+				"guidance",
+				"followUpActions"
+			],
+			"properties": {
+				"progress": { "$ref": "#/$defs/WidgetRecoveryProgress" },
+				"schemaVersion": { "const": 1 },
+				"ruleId": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"ruleVersion": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"disposition": { "enum": [
+					"retry",
+					"repair",
+					"inspect",
+					"external-action",
+					"stop"
+				] },
+				"nextAction": { "$ref": "#/$defs/WidgetRecoveryAction" },
+				"verification": { "$ref": "#/$defs/WidgetRecoveryVerification" },
+				"guidance": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 4096
+				},
+				"followUpActions": {
+					"description": "首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。",
+					"type": "array",
+					"maxItems": 8,
+					"items": { "$ref": "#/$defs/WidgetRecoveryAction" }
+				}
+			}
+		},
+		"WidgetRecoveryRule": {
+			"title": "WidgetRecoveryRule",
+			"description": "公共恢复规则目录条目；空 codes 仅用于显式 unknown 回退。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"id",
+				"version",
+				"sources",
+				"codes",
+				"disposition",
+				"nextAction",
+				"verification",
+				"guidance",
+				"followUpActions"
+			],
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 96,
+					"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+				},
+				"version": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"sources": {
+					"type": "array",
+					"minItems": 1,
+					"maxItems": 3,
+					"uniqueItems": true,
+					"items": { "enum": [
+						"sdk",
+						"host",
+						"toolchain"
+					] }
+				},
+				"codes": {
+					"type": "array",
+					"maxItems": 64,
+					"uniqueItems": true,
+					"items": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 96,
+						"pattern": "^[A-Za-z][A-Za-z0-9_.-]*$"
+					}
+				},
+				"disposition": { "enum": [
+					"retry",
+					"repair",
+					"inspect",
+					"external-action",
+					"stop"
+				] },
+				"nextAction": { "$ref": "#/$defs/WidgetRecoveryAction" },
+				"verification": { "$ref": "#/$defs/WidgetRecoveryVerification" },
+				"guidance": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 4096
+				},
+				"followUpActions": {
+					"description": "首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。",
+					"type": "array",
+					"maxItems": 8,
+					"items": { "$ref": "#/$defs/WidgetRecoveryAction" }
+				}
+			}
+		},
+		"WidgetDevelopmentExtension": {
+			"title": "WidgetDevelopmentExtension",
+			"description": "经 offer/connect 显式选择的开发扩展；不授予 capability。",
+			"const": "development-diagnostics-v1"
+		},
+		"WidgetDevelopmentOffer": {
+			"title": "WidgetDevelopmentOffer",
+			"description": "独立于旧 bootstrap-ready 的支持声明，接收方仍须校验 frame 来源和挂载尝试。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"type",
+				"protocolVersion",
+				"extensions"
+			],
+			"properties": {
+				"type": { "const": "widget-bootstrap-offer" },
+				"protocolVersion": { "const": 1 },
+				"extensions": {
+					"type": "array",
+					"minItems": 1,
+					"maxItems": 1,
+					"uniqueItems": true,
+					"items": { "$ref": "#/$defs/WidgetDevelopmentExtension" }
+				}
+			}
+		},
+		"WidgetDevelopmentConnect": {
+			"title": "WidgetDevelopmentConnect",
+			"description": "仅在收到当前 iframe 合法 offer 后使用的扩展 connect；旧形状保持不变。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"type",
+				"protocolVersion",
+				"channelId",
+				"initPayload",
+				"extensions"
+			],
+			"properties": {
+				"type": { "const": "widget-host-connect" },
+				"protocolVersion": { "const": 1 },
+				"channelId": {
+					"type": "string",
+					"minLength": 16
+				},
+				"initPayload": { "$ref": "#/$defs/InitPayload" },
+				"extensions": {
+					"type": "array",
+					"minItems": 1,
+					"maxItems": 1,
+					"uniqueItems": true,
+					"items": { "$ref": "#/$defs/WidgetDevelopmentExtension" }
+				}
+			}
+		},
+		"WidgetRenderResult": {
+			"title": "WidgetRenderResult",
+			"description": "仅表示受管渲染处理器的处理结果，不代表视觉或业务验收。",
+			"oneOf": [{
+				"type": "object",
+				"additionalProperties": false,
+				"required": [
+					"requestId",
+					"revision",
+					"outcome"
+				],
+				"properties": {
+					"requestId": { "$ref": "#/$defs/RenderRequestBase/properties/requestId" },
+					"revision": {
+						"type": "integer",
+						"minimum": 1
+					},
+					"outcome": { "enum": ["handled", "superseded"] }
+				}
+			}, {
+				"type": "object",
+				"additionalProperties": false,
+				"required": [
+					"requestId",
+					"revision",
+					"outcome",
+					"diagnostic"
+				],
+				"properties": {
+					"requestId": { "$ref": "#/$defs/RenderRequestBase/properties/requestId" },
+					"revision": {
+						"type": "integer",
+						"minimum": 1
+					},
+					"outcome": { "const": "failed" },
+					"diagnostic": { "$ref": "#/$defs/WidgetRenderFailureDiagnostic" }
+				}
+			}]
+		},
+		"WidgetDiagnosticMessage": {
+			"title": "WidgetDiagnosticMessage",
+			"description": "经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。",
+			"type": "object",
+			"allOf": [{ "$ref": "#/$defs/BridgeEnvelopeBase" }, {
+				"type": "object",
+				"required": ["type", "payload"],
+				"properties": {
+					"type": { "const": "diagnostic" },
+					"payload": { "$ref": "#/$defs/WidgetGuestDiagnostic" }
+				}
+			}],
+			"unevaluatedProperties": false
+		},
+		"WidgetRenderResultMessage": {
+			"title": "WidgetRenderResultMessage",
+			"description": "经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。",
+			"type": "object",
+			"allOf": [{ "$ref": "#/$defs/BridgeEnvelopeBase" }, {
+				"type": "object",
+				"required": ["type", "payload"],
+				"properties": {
+					"type": { "const": "render-result" },
+					"payload": { "$ref": "#/$defs/WidgetRenderResult" }
+				}
+			}],
+			"unevaluatedProperties": false
+		},
+		"WidgetDevelopmentMessage": {
+			"title": "WidgetDevelopmentMessage",
+			"description": "扩展 profile 下的 Widget → Host 消息；原 WidgetToHostMessage 不扩展。",
+			"oneOf": [
+				{ "$ref": "#/$defs/WidgetToHostMessage" },
+				{ "$ref": "#/$defs/WidgetDiagnosticMessage" },
+				{ "$ref": "#/$defs/WidgetRenderResultMessage" }
+			]
+		},
+		"WidgetRecoveryContext": {
+			"title": "WidgetRecoveryContext",
+			"description": "复用工具执行结果语义的可信恢复上下文；缺失字段表示未知，不能授权重放。",
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"progress": { "$ref": "#/$defs/WidgetRecoveryProgress" },
+				"executionState": { "enum": [
+					"not_started",
+					"finished",
+					"partial",
+					"unknown"
+				] },
+				"mayHaveExecuted": { "type": "boolean" }
+			}
+		},
+		"WidgetGuestDiagnostic": {
+			"title": "WidgetGuestDiagnostic",
+			"description": "Guest 仅声明 SDK 诊断事实，不得冒充 Host 或工具链。",
+			"allOf": [{ "$ref": "#/$defs/WidgetDevelopmentDiagnostic" }, {
+				"type": "object",
+				"required": ["source"],
+				"properties": { "source": { "const": "sdk" } }
+			}]
+		},
+		"WidgetRenderFailureDiagnostic": {
+			"title": "WidgetRenderFailureDiagnostic",
+			"description": "失败处理回执的 SDK 请求诊断；接收方还须匹配当前 requestId。",
+			"allOf": [{ "$ref": "#/$defs/WidgetGuestDiagnostic" }, {
+				"type": "object",
+				"required": ["correlationId"],
+				"properties": {
+					"correlationId": { "$ref": "#/$defs/WidgetDevelopmentDiagnostic/properties/correlationId" },
+					"phase": { "enum": ["render", "update"] }
+				}
+			}]
+		},
+		"WidgetRecoveryProgress": {
+			"title": "WidgetRecoveryProgress",
+			"description": "可信宿主观察到的恢复进展；重复故障无新证据时不能重复同一修复。",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["repeated", "hasNewEvidence"],
+			"properties": {
+				"repeated": { "type": "boolean" },
+				"hasNewEvidence": { "type": "boolean" }
+			}
 		}
 	}
 };
@@ -10800,6 +11936,11 @@ compileDefinition("WidgetToHostMessage");
 compileDefinition("CapabilityRequest");
 const capabilityResultValidator = compileDefinition("CapabilityResult");
 compileDefinition("WidgetError");
+const developmentDiagnosticValidator = compileDefinition("WidgetDevelopmentDiagnostic");
+compileDefinition("WidgetDevelopmentOffer");
+compileDefinition("WidgetDevelopmentConnect");
+compileDefinition("WidgetDevelopmentMessage");
+compileDefinition("WidgetRecoveryPlan");
 compileDefinition("ResourceBudget");
 compileDefinition("GrantedCapability");
 compileDefinition("PublicWidgetEvent");
@@ -10827,10 +11968,17 @@ function validateRenderRequest(value) {
 function validateCapabilityResult(value) {
 	return validateContract(capabilityResultValidator, value);
 }
+/** 内部/Host 工具按源头 Schema 校验开发合同，不增加浏览器校验器入口。 */
+function validateWidgetDevelopmentDiagnostic(value) {
+	return validateContract(developmentDiagnosticValidator, value);
+}
 //#endregion
 //#region src/project/validate.mjs
 function loadContractValidators() {
 	return Promise.resolve({
+		validateWidgetDevelopmentDiagnostic,
+		createWidgetRecoveryPlan,
+		isWidgetRenderResult,
 		validateWidgetManifest(value) {
 			return validateWidgetManifest(value);
 		},
@@ -11690,4 +12838,4 @@ async function scaffoldDshWidget(input, output, options) {
 	};
 }
 //#endregion
-export { normalizeArchivePath as a, compileAuthorManifest as c, prepareWidgetPackage as i, scaffoldDshWidget as n, checkWidgetProject as o, buildWidgetPackage as r, resolveWidgetProjects as s, auditDshPlugin as t };
+export { normalizeArchivePath as a, loadContractValidators as c, prepareWidgetPackage as i, compileAuthorManifest as l, scaffoldDshWidget as n, checkWidgetProject as o, buildWidgetPackage as r, resolveWidgetProjects as s, auditDshPlugin as t };