@mbws/plugin-sdk 0.1.0

package/dist/dev-mock.js

@@ -0,0 +1,59 @@
+import { fetchContract } from "./contract.js";
+/**
+ * 创建 dev mock 客户端。四个固定命名空间全部构造（dev 无授权语义），
+ * panel 生命周期面上报/应答均无宿主可收，no-op 即可。
+ */
+export function createDevMockMbws() {
+    return {
+        data: {
+            read: async (key) => {
+                try {
+                    const response = await fetch(new URL(`samples/${key}.json`, document.baseURI));
+                    if (!response.ok)
+                        return undefined;
+                    return (await response.json());
+                }
+                catch (_error) {
+                    console.warn(`[mbws:dev] samples/${key}.json 读取失败，回 undefined`);
+                    return undefined;
+                }
+            },
+            blob: async (key) => {
+                console.info(`[mbws:dev] data.blob(${key}) no-op`);
+                return { url: `dev://samples/${key}` };
+            },
+            apply: async (outputs) => {
+                console.info("[mbws:dev] apply（不入库）", outputs);
+            },
+        },
+        runtime: {
+            progress: async () => { },
+            log: async (...args) => {
+                console.info("[mbws:dev] log", ...args);
+            },
+            signal: () => new AbortController().signal,
+        },
+        storage: {
+            get: async () => undefined,
+            set: async () => { },
+        },
+        ui: {
+            confirm: async (opts) => {
+                console.info(`[mbws:dev] ui.confirm：${opts.title ?? ""} ${opts.message}`);
+                return true;
+            },
+            toast: async (message) => {
+                console.info(`[mbws:dev] ui.toast：${message}`);
+            },
+        },
+        panel: {
+            resize: () => { },
+            onBeforeClose: () => { },
+            replyBeforeClose: () => { },
+        },
+        // 契约面不走 mock：dev 下同样 HTTP 直连服务端拉真值（samples 夹具只有 data.read）
+        contract: {
+            get: (opts = {}) => fetchContract(opts),
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * mbws 协议错误码（v1）。
+ *
+ * 用于 `mbws:reject` 消息的 `error.code`，以及宿主 broker 侧的审计归类。
+ * 错误码集合是协议契约的一部分：只增不改语义，破坏性变更随 PROTOCOL_VERSION 大版本走。
+ */
+export declare const MBWS_ERROR_CODES: {
+    /** 调用参数不符合方法签名（ns/method 存在但 args 不合法） */
+    readonly E_INVALID_ARGS: "E_INVALID_ARGS";
+    /** 调用了命名空间下不存在的方法 */
+    readonly E_UNKNOWN_METHOD: "E_UNKNOWN_METHOD";
+    /** manifest 未声明该权限，或用户/宿主未授予（broker 独立校验的第一道拒） */
+    readonly E_PERMISSION_DENIED: "E_PERMISSION_DENIED";
+    /** 配额超限（AI 次数/费用、指令预算、wall-clock 超时等） */
+    readonly E_QUOTA_EXCEEDED: "E_QUOTA_EXCEEDED";
+    /** apply 写回被 write gate 拒绝（key 越界 / outputSchema 校验失败 / 显式拒未知字段） */
+    readonly E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED";
+    /** 依赖的能力包未安装或版本不满足 */
+    readonly E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE";
+    /** 调用超时（宿主侧 wall-clock 预算） */
+    readonly E_TIMEOUT: "E_TIMEOUT";
+    /** 被取消（对齐 ffmpeg-cancel 语义，runtime.signal 触发后的在途调用收尾） */
+    readonly E_CANCELLED: "E_CANCELLED";
+    /** 消息本身违反协议（缺 v、未知 type、方向错误） */
+    readonly E_PROTOCOL_VIOLATION: "E_PROTOCOL_VIOLATION";
+};
+export type MbwsErrorCode = (typeof MBWS_ERROR_CODES)[keyof typeof MBWS_ERROR_CODES];

package/dist/errors.js

@@ -0,0 +1,26 @@
+/**
+ * mbws 协议错误码（v1）。
+ *
+ * 用于 `mbws:reject` 消息的 `error.code`，以及宿主 broker 侧的审计归类。
+ * 错误码集合是协议契约的一部分：只增不改语义，破坏性变更随 PROTOCOL_VERSION 大版本走。
+ */
+export const MBWS_ERROR_CODES = {
+    /** 调用参数不符合方法签名（ns/method 存在但 args 不合法） */
+    E_INVALID_ARGS: "E_INVALID_ARGS",
+    /** 调用了命名空间下不存在的方法 */
+    E_UNKNOWN_METHOD: "E_UNKNOWN_METHOD",
+    /** manifest 未声明该权限，或用户/宿主未授予（broker 独立校验的第一道拒） */
+    E_PERMISSION_DENIED: "E_PERMISSION_DENIED",
+    /** 配额超限（AI 次数/费用、指令预算、wall-clock 超时等） */
+    E_QUOTA_EXCEEDED: "E_QUOTA_EXCEEDED",
+    /** apply 写回被 write gate 拒绝（key 越界 / outputSchema 校验失败 / 显式拒未知字段） */
+    E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED",
+    /** 依赖的能力包未安装或版本不满足 */
+    E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE",
+    /** 调用超时（宿主侧 wall-clock 预算） */
+    E_TIMEOUT: "E_TIMEOUT",
+    /** 被取消（对齐 ffmpeg-cancel 语义，runtime.signal 触发后的在途调用收尾） */
+    E_CANCELLED: "E_CANCELLED",
+    /** 消息本身违反协议（缺 v、未知 type、方向错误） */
+    E_PROTOCOL_VIOLATION: "E_PROTOCOL_VIOLATION",
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @mbws/plugin-sdk —— Moye 加工工具插件平台的契约与 SDK 包。
+ *
+ * M1：契约基座（manifest / 协议消息族 / 错误码 / 版本常量）。
+ * M2：createMbws() 工厂与 dev mock。
+ * 后续里程碑在此包内扩展：CLI dev/build/sign（M4）、fns/DSL（M4）。
+ */
+export * from "./client.js";
+export * from "./config.js";
+export * from "./contract.js";
+export * from "./dev-mock.js";
+export * from "./errors.js";
+export * from "./manifest.js";
+export * from "./protocol.js";
+export * from "./uuid.js";
+export * from "./version.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @mbws/plugin-sdk —— Moye 加工工具插件平台的契约与 SDK 包。
+ *
+ * M1：契约基座（manifest / 协议消息族 / 错误码 / 版本常量）。
+ * M2：createMbws() 工厂与 dev mock。
+ * 后续里程碑在此包内扩展：CLI dev/build/sign（M4）、fns/DSL（M4）。
+ */
+export * from "./client.js";
+export * from "./config.js";
+export * from "./contract.js";
+export * from "./dev-mock.js";
+export * from "./errors.js";
+export * from "./manifest.js";
+export * from "./protocol.js";
+export * from "./uuid.js";
+export * from "./version.js";

package/dist/manifest.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 插件 manifest（合同）契约——设计稿 §3.2 的代码定稿。
+ *
+ * manifest 是插件与宿主之间唯一的静态合同：权限声明、能力依赖、自动化形态、入口组件。
+ * 宿主（broker / write gate / CSP 推导 / 权限预览文案）全部以此为数据源，逐字段强校验。
+ * 注意 I/O 契约不在其列——数据结构唯一权威在服务端（spec 引用 + 按编号实时派生），
+ * manifest 只留静态装载合同，不落地会过期的契约快照。
+ *
+ * 字段对齐三方现有事实：
+ * - 前端 `ActionDefinition`（automation/inputs/outputs/paramsSchema 语义同源）
+ * - spec 侧 `RecordActionEntry`（x-action 声明只引用 id+键映射，结构锁定在 manifest）
+ * - 后端 `validate_record_actions`（outputs 键集一致性校验的权威在 manifest.outputs）
+ */
+import { z } from "zod";
+/**
+ * 任意 JSON 值（递归）。inputs/outputs/paramsSchema 的叶子都是 JSON Schema 对象，
+ * 结构宽容透传（含 `x-modality`/`x-mime`/`x-storage`/`x-field-name` 等扩展键），
+ * 语义校验交给 write gate 的 outputSchema 校验，不在这里重复。
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export declare const ManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    artifactVersion: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        producer: "producer";
+        validator: "validator";
+    }>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>>;
+    outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>>;
+    paramsSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>;
+    requiresCapabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    automation: z.ZodEnum<{
+        batchable: "batchable";
+        "interactive-only": "interactive-only";
+    }>;
+    components: z.ZodOptional<z.ZodObject<{
+        panel: z.ZodOptional<z.ZodString>;
+        viewer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sdk: z.ZodOptional<z.ZodString>;
+    meta: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Manifest = z.output<typeof ManifestSchema>;
+export interface ManifestValidationOk {
+    ok: true;
+    manifest: Manifest;
+}
+export interface ManifestValidationErr {
+    ok: false;
+    errors: string[];
+}
+export type ManifestValidation = ManifestValidationOk | ManifestValidationErr;
+/** 校验 manifest：宽容入口（任意 unknown），失败返回逐字段错误清单而不抛异常。 */
+export declare function validateManifest(input: unknown): ManifestValidation;
+export {};

package/dist/manifest.js

@@ -0,0 +1,90 @@
+/**
+ * 插件 manifest（合同）契约——设计稿 §3.2 的代码定稿。
+ *
+ * manifest 是插件与宿主之间唯一的静态合同：权限声明、能力依赖、自动化形态、入口组件。
+ * 宿主（broker / write gate / CSP 推导 / 权限预览文案）全部以此为数据源，逐字段强校验。
+ * 注意 I/O 契约不在其列——数据结构唯一权威在服务端（spec 引用 + 按编号实时派生），
+ * manifest 只留静态装载合同，不落地会过期的契约快照。
+ *
+ * 字段对齐三方现有事实：
+ * - 前端 `ActionDefinition`（automation/inputs/outputs/paramsSchema 语义同源）
+ * - spec 侧 `RecordActionEntry`（x-action 声明只引用 id+键映射，结构锁定在 manifest）
+ * - 后端 `validate_record_actions`（outputs 键集一致性校验的权威在 manifest.outputs）
+ */
+import { z } from "zod";
+import { ARTIFACT_VERSION } from "./version.js";
+const jsonValue = z.lazy(() => z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.string(),
+    z.array(jsonValue),
+    z.record(z.string(), jsonValue),
+]));
+/** JSON Schema 根节点：对象或布尔（`true`/`false` 是合法的空 schema）。 */
+const JsonSchemaValue = z.union([z.boolean(), z.record(z.string(), jsonValue)]);
+/**
+ * 插件 id：小写字母数字 + 短横线/点分段。信任级用前缀约定（schema 不硬分，registry 赋级）：
+ * `internal.*` 项目组 / `org.*` 企业白名单 / `3p.*` 市场上架 / 无前缀或 `dev.*` 仅本机开发。
+ */
+const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+/** 能力依赖：`<域>.<名>` 可带版本约束，如 `media.ffmpeg@>=7`。 */
+const CAPABILITY_RE = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+(@.+)?$/;
+/**
+ * 权限声明，两种语法（CSP connect-src 与权限预览文案的推导输入，设计稿 §6.5）：
+ * - `ai.<purpose>`：走项目 AI 中心的调用（如 `ai.ocr`）
+ * - `net:<host>`：插件自有 key 直连的外部域名（如 `net:api.vendor.example.com`）
+ */
+const PERMISSION_RE = /^(ai\.[a-z][a-z0-9-]*|net:[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$)/;
+export const ManifestSchema = z.object({
+    /** I/O 契约锚点：spec 的 x-action 钉的是 id，同 id 多实现竞争 UX（设计稿 §3.4） */
+    id: z.string().regex(PLUGIN_ID_RE),
+    version: z.string().regex(SEMVER_RE),
+    /** 产物格式版本：宿主按版本兼容加载，升版本 = 破坏性变更 */
+    artifactVersion: z.literal(ARTIFACT_VERSION),
+    /** producer=加工插件（本文档主体）；validator=检测插件（另案，此处仅收枚举） */
+    kind: z.enum(["producer", "validator"]),
+    /**
+     * 输入/输出契约：可选——数据结构唯一权威在服务端（按插件编号实时派生），
+     * manifest 是静态装载合同，不落地会过期的契约快照（写了也没人负责更新）。
+     * 留 optional 兼容存量产物；插件运行期/宿主 write gate 一律经 by-plugin 拉实时值。
+     */
+    inputs: z.record(z.string(), JsonSchemaValue).optional(),
+    outputs: z.record(z.string(), JsonSchemaValue).optional(),
+    /** 参数位约束：宿主据此渲染参数表单（插件零 UI 代码即有参数面板） */
+    paramsSchema: JsonSchemaValue.optional(),
+    /** 能力依赖：机器未装/未授则 `mbws.caps.*` 命名空间不存在 */
+    requiresCapabilities: z.array(z.string().regex(CAPABILITY_RE)).default([]),
+    /** 权限逐条授予：consent 列表与 CSP 白名单的推导源 */
+    permissions: z.array(z.string().regex(PERMISSION_RE)).default([]),
+    /** interactive-only 不进入批量/自动驱动 */
+    automation: z.enum(["batchable", "interactive-only"]),
+    /** 产物组件的 html 相对路径，缺省 `panel.html` / `viewer.html` */
+    components: z
+        .object({
+        panel: z.string().optional(),
+        viewer: z.string().optional(),
+    })
+        .optional(),
+    /** build 写入的 SDK 版本（版本闸门用），手写无效——市场发布时以构建器写入为准 */
+    sdk: z.string().optional(),
+    meta: z.object({
+        title: z.string().min(1),
+        description: z.string().min(1),
+        icon: z.string().optional(),
+        vendor: z.string().optional(),
+        screenshots: z.array(z.string()).optional(),
+    }),
+});
+/** 校验 manifest：宽容入口（任意 unknown），失败返回逐字段错误清单而不抛异常。 */
+export function validateManifest(input) {
+    const parsed = ManifestSchema.safeParse(input);
+    if (parsed.success) {
+        return { ok: true, manifest: parsed.data };
+    }
+    return {
+        ok: false,
+        errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`),
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,127 @@
+/**
+ * mbws 协议 v1 消息族——设计稿 §6.6 的代码定稿。
+ *
+ * 统一 envelope：`{ v: 1, type, ...payload }`。`v` 是协议版本，每条消息必带、
+ * 与 PROTOCOL_VERSION 不符的消息按协议违规直接拒绝（不静默兼容）。
+ *
+ * 方向约定（防线在宿主 broker 对每条进入消息独立校验，本模块只是契约形状）：
+ * - plugin → host：调用（mbws:invoke）、生命周期上报（panel:ready / panel:resize / panel:before-close-reply / mbws:init-ack）
+ * - host → plugin：握手（mbws:init）、调用结果（mbws:resolve / mbws:reject）、事件（mbws:event）、
+ *   生命周期询问（panel:before-close）
+ */
+import { z } from "zod";
+import { type MbwsErrorCode } from "./errors.js";
+/**
+ * 调用命名空间白名单。data/runtime/storage/ui 是协议固定面；
+ * `caps.*` 由已装且已授予的能力包动态注册（如 `caps.video`），协议面不硬编码能力包 API。
+ */
+export declare const MBWS_NAMESPACES: readonly ["data", "runtime", "storage", "ui"];
+/** 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme） */
+export declare const MBWS_EVENT_KINDS: readonly ["progress", "log", "cancel", "theme"];
+export declare const MbwsMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:invoke">;
+    callId: z.ZodString;
+    ns: z.ZodString;
+    method: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:init">;
+    protocolVersion: z.ZodLiteral<1>;
+    grants: z.ZodArray<z.ZodString>;
+    theme: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:init-ack">;
+    sdkVersion: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:resolve">;
+    callId: z.ZodString;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:reject">;
+    callId: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            readonly E_INVALID_ARGS: "E_INVALID_ARGS";
+            readonly E_UNKNOWN_METHOD: "E_UNKNOWN_METHOD";
+            readonly E_PERMISSION_DENIED: "E_PERMISSION_DENIED";
+            readonly E_QUOTA_EXCEEDED: "E_QUOTA_EXCEEDED";
+            readonly E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED";
+            readonly E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE";
+            readonly E_TIMEOUT: "E_TIMEOUT";
+            readonly E_CANCELLED: "E_CANCELLED";
+            readonly E_PROTOCOL_VIOLATION: "E_PROTOCOL_VIOLATION";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"mbws:event">;
+    event: z.ZodEnum<{
+        progress: "progress";
+        log: "log";
+        cancel: "cancel";
+        theme: "theme";
+    }>;
+    payload: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"panel:ready">;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"panel:resize">;
+    height: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"panel:before-close">;
+}, z.core.$strip>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"panel:before-close-reply">;
+    dirty: z.ZodBoolean;
+}, z.core.$strip>], "type">;
+export type MbwsMessage = z.output<typeof MbwsMessageSchema>;
+/** 消息方向表：契约形状层即可判定，broker 在此之上再做权限/配额校验 */
+export declare const MESSAGE_DIRECTION: {
+    readonly "mbws:invoke": "plugin-to-host";
+    readonly "mbws:init": "host-to-plugin";
+    readonly "mbws:init-ack": "plugin-to-host";
+    readonly "mbws:resolve": "host-to-plugin";
+    readonly "mbws:reject": "host-to-plugin";
+    readonly "mbws:event": "host-to-plugin";
+    readonly "panel:ready": "plugin-to-host";
+    readonly "panel:resize": "plugin-to-host";
+    readonly "panel:before-close": "host-to-plugin";
+    readonly "panel:before-close-reply": "plugin-to-host";
+};
+export type MessageDirection = (typeof MESSAGE_DIRECTION)[keyof typeof MESSAGE_DIRECTION];
+export declare function isPluginToHost(message: MbwsMessage): boolean;
+export declare function isHostToPlugin(message: MbwsMessage): boolean;
+/** 各 variant 守卫（窄化用，形状已由 discriminatedUnion 保证 type 判别） */
+export declare function isMbwsInvoke(message: MbwsMessage): message is Extract<MbwsMessage, {
+    type: "mbws:invoke";
+}>;
+export declare function isMbwsResolve(message: MbwsMessage): message is Extract<MbwsMessage, {
+    type: "mbws:resolve";
+}>;
+export declare function isMbwsReject(message: MbwsMessage): message is Extract<MbwsMessage, {
+    type: "mbws:reject";
+}>;
+export declare function isMbwsEvent(message: MbwsMessage): message is Extract<MbwsMessage, {
+    type: "mbws:event";
+}>;
+/** reject 错误载荷（resolve 失败路径的规范形状） */
+export type MbwsErrorPayload = {
+    code: MbwsErrorCode;
+    message?: string;
+    data?: unknown;
+};
+/**
+ * 宽容解析：任意 unknown → 合法消息或 null。
+ * 线上收到的 postMessage 数据可能是任何东西，解析失败由调用方决定处置（记审计/静默丢弃）。
+ */
+export declare function parseMbwsMessage(input: unknown): MbwsMessage | null;

package/dist/protocol.js

@@ -0,0 +1,142 @@
+/**
+ * mbws 协议 v1 消息族——设计稿 §6.6 的代码定稿。
+ *
+ * 统一 envelope：`{ v: 1, type, ...payload }`。`v` 是协议版本，每条消息必带、
+ * 与 PROTOCOL_VERSION 不符的消息按协议违规直接拒绝（不静默兼容）。
+ *
+ * 方向约定（防线在宿主 broker 对每条进入消息独立校验，本模块只是契约形状）：
+ * - plugin → host：调用（mbws:invoke）、生命周期上报（panel:ready / panel:resize / panel:before-close-reply / mbws:init-ack）
+ * - host → plugin：握手（mbws:init）、调用结果（mbws:resolve / mbws:reject）、事件（mbws:event）、
+ *   生命周期询问（panel:before-close）
+ */
+import { z } from "zod";
+import { MBWS_ERROR_CODES } from "./errors.js";
+import { PROTOCOL_VERSION } from "./version.js";
+/**
+ * 调用命名空间白名单。data/runtime/storage/ui 是协议固定面；
+ * `caps.*` 由已装且已授予的能力包动态注册（如 `caps.video`），协议面不硬编码能力包 API。
+ */
+export const MBWS_NAMESPACES = ["data", "runtime", "storage", "ui"];
+const NS_RE = /^(data|runtime|storage|ui|caps(\.[a-z0-9-]+)?)$/;
+const nsField = z.string().regex(NS_RE);
+/** 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme） */
+export const MBWS_EVENT_KINDS = ["progress", "log", "cancel", "theme"];
+const InvokeMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:invoke"),
+    /** 调用流水号：resolve/reject 按此配对 */
+    callId: z.string().min(1),
+    ns: nsField,
+    method: z.string().min(1),
+    args: z.unknown().optional(),
+});
+const InitMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:init"),
+    /** 宿主侧协议版本（与 v 冗余校验，防中转篡改） */
+    protocolVersion: z.literal(PROTOCOL_VERSION),
+    /** 本次授予的能力清单：客户端只构造已授予的命名空间（按授权构造） */
+    grants: z.array(z.string()),
+    /** 主题 token 表（CSS 自定义属性 → 值），插件侧写入 :root 跟随宿主主题 */
+    theme: z.record(z.string(), z.string()).optional(),
+});
+const InitAckMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:init-ack"),
+    /** SDK 版本（审计用；与 manifest.sdk 交叉核对） */
+    sdkVersion: z.string().min(1),
+});
+const ResolveMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:resolve"),
+    callId: z.string().min(1),
+    value: z.unknown().optional(),
+});
+const RejectMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:reject"),
+    callId: z.string().min(1),
+    error: z.object({
+        code: z.enum(MBWS_ERROR_CODES),
+        message: z.string().optional(),
+        data: z.unknown().optional(),
+    }),
+});
+const EventMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("mbws:event"),
+    event: z.enum(MBWS_EVENT_KINDS),
+    payload: z.unknown().optional(),
+});
+const PanelReadyMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("panel:ready"),
+});
+const PanelResizeMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("panel:resize"),
+    /** 面板期望高度（px），宿主 clamp（自适应布局） */
+    height: z.number().positive(),
+});
+const PanelBeforeCloseMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("panel:before-close"),
+});
+const PanelBeforeCloseReplyMessage = z.object({
+    v: z.literal(PROTOCOL_VERSION),
+    type: z.literal("panel:before-close-reply"),
+    /** true = 有未保存修改，宿主先弹确认再关；不答则直接关 */
+    dirty: z.boolean(),
+});
+export const MbwsMessageSchema = z.discriminatedUnion("type", [
+    InvokeMessage,
+    InitMessage,
+    InitAckMessage,
+    ResolveMessage,
+    RejectMessage,
+    EventMessage,
+    PanelReadyMessage,
+    PanelResizeMessage,
+    PanelBeforeCloseMessage,
+    PanelBeforeCloseReplyMessage,
+]);
+/** 消息方向表：契约形状层即可判定，broker 在此之上再做权限/配额校验 */
+export const MESSAGE_DIRECTION = {
+    "mbws:invoke": "plugin-to-host",
+    "mbws:init": "host-to-plugin",
+    "mbws:init-ack": "plugin-to-host",
+    "mbws:resolve": "host-to-plugin",
+    "mbws:reject": "host-to-plugin",
+    "mbws:event": "host-to-plugin",
+    "panel:ready": "plugin-to-host",
+    "panel:resize": "plugin-to-host",
+    "panel:before-close": "host-to-plugin",
+    "panel:before-close-reply": "plugin-to-host",
+};
+export function isPluginToHost(message) {
+    return MESSAGE_DIRECTION[message.type] === "plugin-to-host";
+}
+export function isHostToPlugin(message) {
+    return MESSAGE_DIRECTION[message.type] === "host-to-plugin";
+}
+/** 各 variant 守卫（窄化用，形状已由 discriminatedUnion 保证 type 判别） */
+export function isMbwsInvoke(message) {
+    return message.type === "mbws:invoke";
+}
+export function isMbwsResolve(message) {
+    return message.type === "mbws:resolve";
+}
+export function isMbwsReject(message) {
+    return message.type === "mbws:reject";
+}
+export function isMbwsEvent(message) {
+    return message.type === "mbws:event";
+}
+/**
+ * 宽容解析：任意 unknown → 合法消息或 null。
+ * 线上收到的 postMessage 数据可能是任何东西，解析失败由调用方决定处置（记审计/静默丢弃）。
+ */
+export function parseMbwsMessage(input) {
+    const parsed = MbwsMessageSchema.safeParse(input);
+    return parsed.success ? parsed.data : null;
+}

package/dist/uuid.d.ts

@@ -0,0 +1,10 @@
+/**
+ * uuid 生成（RFC 4122 v4 格式）。
+ *
+ * 统一走 `crypto.getRandomValues`，**不用 `crypto.randomUUID`**——后者仅安全上下文
+ * 可用（插件面板经 http 的 registry 代理装载即缺失，dev 环境实测踩坑），前者任何
+ * 上下文都有。SDK 内需要 uuid 的一律从这里拿，禁止再手写 `crypto.randomUUID`。
+ * 实现与 @mbws/components 的 lib/uuid.ts 同款（SDK 零依赖独立发包，不能引包）。
+ */
+/** 生成 RFC 4122 v4 格式 uuid（xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx）。 */
+export declare function uuid(): string;

package/dist/uuid.js

@@ -0,0 +1,17 @@
+/**
+ * uuid 生成（RFC 4122 v4 格式）。
+ *
+ * 统一走 `crypto.getRandomValues`，**不用 `crypto.randomUUID`**——后者仅安全上下文
+ * 可用（插件面板经 http 的 registry 代理装载即缺失，dev 环境实测踩坑），前者任何
+ * 上下文都有。SDK 内需要 uuid 的一律从这里拿，禁止再手写 `crypto.randomUUID`。
+ * 实现与 @mbws/components 的 lib/uuid.ts 同款（SDK 零依赖独立发包，不能引包）。
+ */
+/** 生成 RFC 4122 v4 格式 uuid（xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx）。 */
+export function uuid() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    // version 4 + RFC variant 位固定，其余随机
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 平台版本常量——宿主与 SDK 共享的单一事实源。
+ *
+ * - ARTIFACT_VERSION：`.mbws-plugin` 产物格式版本（manifest.artifactVersion）。
+ *   宿主按此值决定兼容加载策略；升版本 = 产物结构破坏性变更，必须随宿主大版本走。
+ * - PROTOCOL_VERSION：mbws 协议（§6.6 消息族）版本。每条消息 envelope 都带 `v` 字段，
+ *   与此值不符的消息按协议违规直接拒绝（不静默兼容）。
+ */
+export declare const ARTIFACT_VERSION: 1;
+export declare const PROTOCOL_VERSION: 1;
+/**
+ * SDK 自身版本（与 package.json version 保持一致）。
+ * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
+ */
+export declare const SDK_VERSION = "0.0.1";

package/dist/version.js

@@ -0,0 +1,15 @@
+/**
+ * 平台版本常量——宿主与 SDK 共享的单一事实源。
+ *
+ * - ARTIFACT_VERSION：`.mbws-plugin` 产物格式版本（manifest.artifactVersion）。
+ *   宿主按此值决定兼容加载策略；升版本 = 产物结构破坏性变更，必须随宿主大版本走。
+ * - PROTOCOL_VERSION：mbws 协议（§6.6 消息族）版本。每条消息 envelope 都带 `v` 字段，
+ *   与此值不符的消息按协议违规直接拒绝（不静默兼容）。
+ */
+export const ARTIFACT_VERSION = 1;
+export const PROTOCOL_VERSION = 1;
+/**
+ * SDK 自身版本（与 package.json version 保持一致）。
+ * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
+ */
+export const SDK_VERSION = "0.0.1";