@mbws/plugin-sdk 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @mbws/plugin-sdk
+
+Moye 插件开发 SDK——插件 panel/viewer 与宿主之间的类型定义与运行时端口适配。
+
+```bash
+pnpm add @mbws/plugin-sdk
+```
+
+## 能力
+
+- **类型**：`Manifest`（配置与权限声明）、端口调用契约等——`mbws.config.ts` 与面板代码
+  共用同一套类型源
+- **运行时**：宿主端口注入适配（桌面/网页宿主零感知），dev 环境自动降级 mock
+  （`data.read` 读 `samples/*.json`，本地 `pnpm dev` 即可跑通面板）
+- **校验**：`validateManifest`（构建期与装载期单一权威校验源）
+
+## 工程起步
+
+用脚手架生成带本 SDK 的完整工程：
+
+```bash
+pnpm create @mbws/plugin my-tool
+```
+
+## 版本与平台受控构建
+
+平台在线构建时按任务钉定的版本经票据下发 tarball（版本受控，不跟 registry 走）；
+npm 上的本包供插件开发者本地开发与类型提示用。

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * createMbws() 工厂——SDK 侧协议客户端（设计稿 §6.1 / §6.3 的代码落地）。
+ *
+ * 时序真话：`mbws` 不是静态导出的对象——端口握手是异步的，插件代码零环境分支：
+ * - 生产（宿主 sandbox iframe 内）：等宿主经 window.postMessage 递来的 MessagePort
+ *   （校验 event.source === window.parent，防嵌套 iframe 抢端口）→ init 握手
+ *   → 按 grants 构造命名空间 → 返回 mbws。
+ * - 开发（harness/单测/直接起 dev server）：顶窗口或等待端口超时 → dev mock 降级。
+ *
+ * 传输约定（对 M1 starter 手写引导的收紧）：init 经窗口通道递端口是唯一一次
+ * window.postMessage；此后所有消息（含 init-ack / panel:* 生命周期）一律走端口。
+ *
+ * 安全定位：客户端只是包装不是防线——插件绕过客户端手发消息伪造调用，
+ * broker 对每条进入的消息仍按 manifest 独立校验（防线在宿主侧）。
+ */
+import { type FetchContractOptions, type PluginContract } from "./contract.js";
+import { type MbwsErrorCode } from "./errors.js";
+import type { MbwsErrorPayload } from "./protocol.js";
+/**
+ * createMbws() 的返回形态（设计稿 §6.3 命名空间方法面）。
+ * 未授予的命名空间在对象上不存在（未装/未授 → 属性 undefined）；caps.* 由能力包
+ * 动态注册（M3 起），协议固定面不硬编码。
+ */
+export interface MbwsClient {
+    /** 工人会话数据面：read 读 slot 值 / blob 拿签名 URL / apply 经 write gate 写回 */
+    data?: {
+        read(key: string): Promise<unknown>;
+        blob(key: string): Promise<{
+            url: string;
+            mime?: string;
+        }>;
+        apply(outputs: Record<string, unknown>): Promise<void>;
+    };
+    /** 运行时：进度上报 / 日志 / 取消信号（桥 mbws:event cancel） */
+    runtime?: {
+        progress(ratio?: number, message?: string): Promise<void>;
+        log(...args: unknown[]): Promise<void>;
+        signal(): AbortSignal;
+    };
+    /** per-plugin 配额 KV（落宿主存储，跨宿主刻意不同步） */
+    storage?: {
+        get(key: string): Promise<unknown>;
+        set(key: string, value: unknown): Promise<void>;
+    };
+    /** 宿主渲染的原生交互件 */
+    ui?: {
+        confirm(opts: {
+            title?: string;
+            message: string;
+        }): Promise<boolean>;
+        toast(message: string, opts?: {
+            type?: "info" | "success" | "error";
+        }): Promise<void>;
+    };
+    /** panel 生命周期便利面（panel:resize 等不是 invoke，是独立消息类型） */
+    panel: {
+        resize(height: number): void;
+        /** 注册 before-close 应答者；不注册则宿主超时后按「无未保存」直接关 */
+        onBeforeClose(cb: () => void): void;
+        /** 应答宿主的 before-close 询问（dirty=true 宿主先弹确认再关） */
+        replyBeforeClose(dirty: boolean): void;
+    };
+    /**
+     * 数据结构（契约）面：拉关联任务的最新契约。不经宿主端口——服务端按插件编号
+     * （manifest.id）公开派生，dev 预览/宿主内同一调用；故不随 grants 增减、恒在。
+     */
+    contract: {
+        get(opts?: FetchContractOptions): Promise<PluginContract>;
+    };
+}
+/** 调用被拒时抛出的规范错误（error.code 是 9 错误码之一） */
+export declare class MbwsInvokeError extends Error {
+    readonly code: MbwsErrorCode;
+    readonly data?: unknown;
+    constructor(payload: MbwsErrorPayload);
+}
+export interface CreateMbwsOptions {
+    /** 等宿主 init 端口的超时（ms），超时走 dev mock。默认 3000。 */
+    timeoutMs?: number;
+    /** 单次 invoke 的默认超时（ms），超时按 E_TIMEOUT 拒绝。默认 30_000。 */
+    invokeTimeoutMs?: number;
+}
+/**
+ * callId 生成走专用 uuid()（getRandomValues 直拼）——randomUUID 是 secure-context-only，
+ * 插件面板经 http 的 registry 代理装载（dev）时不存在，历史上已踩坑。
+ */
+/** 分层可测：纯端口逻辑（不碰 window），单测用 Node MessageChannel 直连 broker。 */
+export declare function connectMbwsPort(port: MessagePort, init: {
+    grants: string[];
+    theme?: Record<string, string>;
+}, opts?: Pick<CreateMbwsOptions, "invokeTimeoutMs">): MbwsClient;
+/**
+ * 生产引导的窗口层：等宿主 init（带端口），超时/顶窗口降级 dev mock。
+ * 抽成独立函数（接受窗口注入）以支持单测用假 window 驱动。
+ */
+export declare function bootstrapFromWindow(win: Pick<Window, "parent" | "addEventListener" | "removeEventListener"> & {
+    document?: Document;
+}, opts?: CreateMbwsOptions): Promise<MbwsClient>;
+export declare function createMbws(opts?: CreateMbwsOptions): Promise<MbwsClient>;

package/dist/client.js

@@ -0,0 +1,210 @@
+/**
+ * createMbws() 工厂——SDK 侧协议客户端（设计稿 §6.1 / §6.3 的代码落地）。
+ *
+ * 时序真话：`mbws` 不是静态导出的对象——端口握手是异步的，插件代码零环境分支：
+ * - 生产（宿主 sandbox iframe 内）：等宿主经 window.postMessage 递来的 MessagePort
+ *   （校验 event.source === window.parent，防嵌套 iframe 抢端口）→ init 握手
+ *   → 按 grants 构造命名空间 → 返回 mbws。
+ * - 开发（harness/单测/直接起 dev server）：顶窗口或等待端口超时 → dev mock 降级。
+ *
+ * 传输约定（对 M1 starter 手写引导的收紧）：init 经窗口通道递端口是唯一一次
+ * window.postMessage；此后所有消息（含 init-ack / panel:* 生命周期）一律走端口。
+ *
+ * 安全定位：客户端只是包装不是防线——插件绕过客户端手发消息伪造调用，
+ * broker 对每条进入的消息仍按 manifest 独立校验（防线在宿主侧）。
+ */
+import { fetchContract } from "./contract.js";
+import { createDevMockMbws } from "./dev-mock.js";
+import { MBWS_ERROR_CODES } from "./errors.js";
+import { parseMbwsMessage } from "./protocol.js";
+import { uuid } from "./uuid.js";
+import { PROTOCOL_VERSION, SDK_VERSION } from "./version.js";
+/** 调用被拒时抛出的规范错误（error.code 是 9 错误码之一） */
+export class MbwsInvokeError extends Error {
+    code;
+    data;
+    constructor(payload) {
+        super(payload.message ?? payload.code);
+        this.name = "MbwsInvokeError";
+        this.code = payload.code;
+        this.data = payload.data;
+    }
+}
+/**
+ * callId 生成走专用 uuid()（getRandomValues 直拼）——randomUUID 是 secure-context-only，
+ * 插件面板经 http 的 registry 代理装载（dev）时不存在，历史上已踩坑。
+ */
+/** 分层可测：纯端口逻辑（不碰 window），单测用 Node MessageChannel 直连 broker。 */
+export function connectMbwsPort(port, init, opts = {}) {
+    const invokeTimeoutMs = opts.invokeTimeoutMs ?? 30_000;
+    const pending = new Map();
+    const abortController = new AbortController();
+    let beforeCloseCb = null;
+    const post = (message) => {
+        port.postMessage(message);
+    };
+    const invoke = (ns, method, args) => new Promise((resolve, reject) => {
+        const callId = uuid();
+        const timer = setTimeout(() => {
+            pending.delete(callId);
+            reject(new MbwsInvokeError({
+                code: MBWS_ERROR_CODES.E_TIMEOUT,
+                message: `${ns}.${method} 调用超时`,
+            }));
+        }, invokeTimeoutMs);
+        pending.set(callId, { resolve, reject, timer });
+        post({
+            v: PROTOCOL_VERSION,
+            type: "mbws:invoke",
+            callId,
+            ns,
+            method,
+            ...(args !== undefined ? { args } : {}),
+        });
+    });
+    const has = (ns) => init.grants.includes(ns);
+    port.addEventListener("message", (event) => {
+        const message = parseMbwsMessage(event.data);
+        if (!message)
+            return;
+        switch (message.type) {
+            case "mbws:resolve": {
+                const call = pending.get(message.callId);
+                if (call) {
+                    pending.delete(message.callId);
+                    clearTimeout(call.timer);
+                    call.resolve(message.value);
+                }
+                break;
+            }
+            case "mbws:reject": {
+                const call = pending.get(message.callId);
+                if (call) {
+                    pending.delete(message.callId);
+                    clearTimeout(call.timer);
+                    call.reject(new MbwsInvokeError(message.error));
+                }
+                break;
+            }
+            case "mbws:event": {
+                // 取消事件桥到 AbortSignal；progress/log/theme 由宿主按需下发，客户端不消费
+                if (message.event === "cancel")
+                    abortController.abort();
+                break;
+            }
+            case "panel:before-close": {
+                beforeCloseCb?.();
+                break;
+            }
+            default:
+                break;
+        }
+    });
+    port.start();
+    // 握手次序：theme 已由窗口层写 :root → 端口回 init-ack → 端口发 panel:ready
+    post({ v: PROTOCOL_VERSION, type: "mbws:init-ack", sdkVersion: SDK_VERSION });
+    post({ v: PROTOCOL_VERSION, type: "panel:ready" });
+    return {
+        ...(has("data")
+            ? {
+                data: {
+                    read: (key) => invoke("data", "read", { key }),
+                    blob: (key) => invoke("data", "blob", { key }),
+                    apply: (outputs) => invoke("data", "apply", { outputs }),
+                },
+            }
+            : {}),
+        ...(has("runtime")
+            ? {
+                runtime: {
+                    progress: (ratio, message) => invoke("runtime", "progress", { ratio, message }),
+                    log: (...args) => invoke("runtime", "log", { args }),
+                    signal: () => abortController.signal,
+                },
+            }
+            : {}),
+        ...(has("storage")
+            ? {
+                storage: {
+                    get: (key) => invoke("storage", "get", { key }),
+                    set: (key, value) => invoke("storage", "set", { key, value }),
+                },
+            }
+            : {}),
+        ...(has("ui")
+            ? {
+                ui: {
+                    confirm: (confirmOpts) => invoke("ui", "confirm", confirmOpts),
+                    toast: (message, toastOpts) => invoke("ui", "toast", { message, ...toastOpts }),
+                },
+            }
+            : {}),
+        panel: {
+            resize: (height) => post({ v: PROTOCOL_VERSION, type: "panel:resize", height }),
+            onBeforeClose(cb) {
+                beforeCloseCb = cb;
+            },
+            replyBeforeClose: (dirty) => post({ v: PROTOCOL_VERSION, type: "panel:before-close-reply", dirty }),
+        },
+        // 契约面与端口无关（HTTP 直连），端口客户端/dev mock 同形，插件代码零分支
+        contract: {
+            get: (opts = {}) => fetchContract(opts),
+        },
+    };
+}
+/**
+ * 生产引导的窗口层：等宿主 init（带端口），超时/顶窗口降级 dev mock。
+ * 抽成独立函数（接受窗口注入）以支持单测用假 window 驱动。
+ */
+export function bootstrapFromWindow(win, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    // 顶窗口（不可能有宿主递端口）→ 直接 dev mock
+    if (win.parent === win) {
+        return Promise.resolve(createDevMockMbws());
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (client) => {
+            if (settled)
+                return;
+            settled = true;
+            win.removeEventListener("message", onMessage);
+            clearTimeout(timer);
+            resolve(client);
+        };
+        const timer = setTimeout(() => finish(createDevMockMbws()), timeoutMs);
+        const onMessage = (event) => {
+            // 防窃听伪造：只认直接父窗口递来的 init + 端口（设计稿 §6.1）
+            if (event.source !== win.parent)
+                return;
+            const message = parseMbwsMessage(event.data);
+            if (message?.type !== "mbws:init" || !event.ports?.[0])
+                return;
+            const port = event.ports[0];
+            // 主题 token 经 init 下发，写入 :root 跟随宿主主题（设计稿 §9.3）
+            if (message.theme && win.document) {
+                for (const [name, value] of Object.entries(message.theme)) {
+                    win.document.documentElement.style.setProperty(name, value);
+                }
+            }
+            finish(connectMbwsPort(port, { grants: message.grants, theme: message.theme }, opts));
+        };
+        win.addEventListener("message", onMessage);
+    });
+}
+/** 一次性守卫：与 VS Code acquireVsCodeApi 同心智，二次调用一律拒绝。 */
+let acquired = false;
+export async function createMbws(opts = {}) {
+    if (acquired) {
+        throw new MbwsInvokeError({
+            code: MBWS_ERROR_CODES.E_PROTOCOL_VIOLATION,
+            message: "createMbws() 只能调用一次（与 acquireVsCodeApi 同心智）",
+        });
+    }
+    acquired = true;
+    const win = typeof window !== "undefined" ? window : undefined;
+    // 无 window（纯 node）也走 dev mock（bootstrapFromWindow 内含顶窗口分支）
+    if (!win)
+        return createDevMockMbws();
+    return bootstrapFromWindow(win, opts);
+}

package/dist/config.d.ts

@@ -0,0 +1,112 @@
+/**
+ * mbws.config.ts 的类型与派生——插件工程的配置源（vite.config.ts 同款姿势）。
+ *
+ * 插件工程根放 `mbws.config.ts`：`export default defineConfig({...})`，TS 类型约束
+ * 可填字段（多余字段直接编译报错），动态开发配置（devKey / 后端地址 / 插件自有
+ * KV）与静态装载合同同住一个文件但**不进产物**——build 时经 buildManifest 派生
+ * manifest.json（宿主装载合同），配置本身不出现在 dist 里。
+ *
+ * 与 manifest 的分工：manifest.json 是 build 派生物（不是手写源），只含静态合同
+ * 面；I/O 契约两头都不落（服务端按编号实时派生，见 contract.ts）。
+ */
+import { z } from "zod";
+import { type Manifest } from "./manifest.js";
+/**
+ * 用户可填面 = manifest 静态合同 - 派生字段（artifactVersion/sdk 由构建注入）
+ * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）。
+ */
+declare const UserConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    kind: z.ZodEnum<{
+        producer: "producer";
+        validator: "validator";
+    }>;
+    paramsSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | {
+        [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null, unknown, z.core.$ZodTypeInternals<string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | {
+        [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null)[] | {
+        [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
+    } | null, 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>>;
+    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>;
+    devKey: z.ZodOptional<z.ZodString>;
+    apiBaseUrl: z.ZodOptional<z.ZodString>;
+    plugin: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** mbws.config.ts 的可填形状（带默认值的字段可省略） */
+export type MbwsUserConfig = z.input<typeof UserConfigSchema>;
+/** 动态开发配置三件（全部可选、不进产物）——交集回传让消费侧（vite.config 等）
+ *  在配置未写这些字段时类型上仍可安全访问到 undefined */
+type MbwsDynamicConfig = Pick<MbwsUserConfig, "devKey" | "apiBaseUrl" | "plugin">;
+/**
+ * mbws.config.ts 的入口：原样回传（类型与 IDE 补全由 TS 泛型提供），
+ * 运行时再过一遍 zod 校验兜底（防手滑/模板生成物），坏字段直接抛错。
+ */
+export declare function defineConfig<T extends MbwsUserConfig>(config: T): T & MbwsDynamicConfig;
+/** 导出给构建脚本/测试做独立校验（defineConfig 之外的编程入口） */
+export declare function validateUserConfig(input: unknown): MbwsUserConfig;
+/**
+ * config → 装载合同 manifest：注入 artifactVersion，剥掉全部动态开发字段，
+ * 补默认值后产出宿主装载所需的完整合同。build 写 dist、dev 虚拟供给共用此派生。
+ */
+export declare function buildManifest(config: MbwsUserConfig): Manifest;
+export {};

package/dist/config.js

@@ -0,0 +1,61 @@
+/**
+ * mbws.config.ts 的类型与派生——插件工程的配置源（vite.config.ts 同款姿势）。
+ *
+ * 插件工程根放 `mbws.config.ts`：`export default defineConfig({...})`，TS 类型约束
+ * 可填字段（多余字段直接编译报错），动态开发配置（devKey / 后端地址 / 插件自有
+ * KV）与静态装载合同同住一个文件但**不进产物**——build 时经 buildManifest 派生
+ * manifest.json（宿主装载合同），配置本身不出现在 dist 里。
+ *
+ * 与 manifest 的分工：manifest.json 是 build 派生物（不是手写源），只含静态合同
+ * 面；I/O 契约两头都不落（服务端按编号实时派生，见 contract.ts）。
+ */
+import { z } from "zod";
+import { ManifestSchema } from "./manifest.js";
+import { ARTIFACT_VERSION } from "./version.js";
+/**
+ * 用户可填面 = manifest 静态合同 - 派生字段（artifactVersion/sdk 由构建注入）
+ * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）。
+ */
+const UserConfigSchema = ManifestSchema.omit({
+    artifactVersion: true,
+    sdk: true,
+    inputs: true,
+    outputs: true,
+}).extend({
+    /** 开发者 key（预留：认领发放的开发验证凭证，契约拉取 X-Dev-Key 用）——不进产物 */
+    devKey: z.string().optional(),
+    /**
+     * 后端地址（插件工程里后端地址的唯一配置位）：dev 预览的 vite 代理目标，
+     * 契约拉取经同源代理转发到这里。SDK/模板不固化任何具体地址——地址是部署事实。
+     * 不进产物。
+     */
+    apiBaseUrl: z.string().optional(),
+    /** 插件自有配置（自由 KV，构建脚本/工具链自取；宿主不感知）——不进产物 */
+    plugin: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * mbws.config.ts 的入口：原样回传（类型与 IDE 补全由 TS 泛型提供），
+ * 运行时再过一遍 zod 校验兜底（防手滑/模板生成物），坏字段直接抛错。
+ */
+export function defineConfig(config) {
+    const parsed = UserConfigSchema.safeParse(config);
+    if (!parsed.success) {
+        const detail = parsed.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("；");
+        throw new Error(`mbws.config 无效：${detail}`);
+    }
+    return config;
+}
+/** 导出给构建脚本/测试做独立校验（defineConfig 之外的编程入口） */
+export function validateUserConfig(input) {
+    return UserConfigSchema.parse(input);
+}
+/**
+ * config → 装载合同 manifest：注入 artifactVersion，剥掉全部动态开发字段，
+ * 补默认值后产出宿主装载所需的完整合同。build 写 dist、dev 虚拟供给共用此派生。
+ */
+export function buildManifest(config) {
+    const { devKey: _devKey, apiBaseUrl: _apiBaseUrl, plugin: _plugin, ...contract } = UserConfigSchema.parse(config);
+    return ManifestSchema.parse({ ...contract, artifactVersion: ARTIFACT_VERSION });
+}

package/dist/contract.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 契约动态获取 —— 插件凭自己的编号（manifest.id）直连服务端拉关联任务的最新契约。
+ *
+ * 插件 ↔ 数据结构的对应关系在服务端维护（PluginDevTask.plugin_code 即关联记录）：
+ * 认领任务时发编号，manifest.id 对齐该编号；线上契约随需求变动时，再次拉取即得
+ * 最新值（updatedAt 作粗版本，供漂移自检：对比 manifest.outputs 键集发现过期）。
+ *
+ * 传输走普通 HTTP（Node ≥18 / 浏览器全局 fetch），不经宿主端口——开发期/工具链/
+ * 面板 dev 预览均可直接用。开发者 key（开发验证凭证）预留请求头位，服务端校验
+ * 后续接入。
+ */
+/** 服务端返回的任务契约（GET /api/plugin-dev-tasks/contract/by-plugin/{code}） */
+export interface PluginContract {
+    /** 契约 id（action_id，数据结构 id——需求侧标识） */
+    contractId: string;
+    title: string;
+    consumes: string[];
+    /** inputKey → JSON Schema */
+    inputs: Record<string, unknown>;
+    /** outputKey → JSON Schema（write gate 的对齐基准） */
+    outputs: Record<string, unknown>;
+    status: string;
+    /** 更新时间（ISO；粗版本，契约漂移检测用） */
+    updatedAt: string;
+}
+export interface FetchContractOptions {
+    /** 插件编号（= manifest.id）；缺省从本工程 manifest.json 读取（浏览器/dev server 场景） */
+    pluginCode?: string;
+    /**
+     * 后端地址；缺省**同源相对**（baseUrl = ""）：dev 预览经插件工程 vite 代理转发
+     * 到 mbws.config.ts 的 apiBaseUrl（免 CORS——插件 dev 端口不在后端 CORS 白名单）；
+     * 宿主内网络面由 CSP 锁定，契约拉取本就是 dev/工具链关注点；跨环境工具链
+     * （node/CLI）显式传。SDK 不内置任何具体后端地址——地址是部署事实，归配置管。
+     */
+    baseUrl?: string;
+    /** 预留：开发验证凭证，服务端校验后续接入 */
+    devKey?: string;
+    signal?: AbortSignal;
+}
+/** 按插件编号拉关联任务的最新契约。非 2xx 抛带状态码与后端 message 的 Error。 */
+export declare function fetchContract(opts?: FetchContractOptions): Promise<PluginContract>;

package/dist/contract.js

@@ -0,0 +1,68 @@
+/**
+ * 契约动态获取 —— 插件凭自己的编号（manifest.id）直连服务端拉关联任务的最新契约。
+ *
+ * 插件 ↔ 数据结构的对应关系在服务端维护（PluginDevTask.plugin_code 即关联记录）：
+ * 认领任务时发编号，manifest.id 对齐该编号；线上契约随需求变动时，再次拉取即得
+ * 最新值（updatedAt 作粗版本，供漂移自检：对比 manifest.outputs 键集发现过期）。
+ *
+ * 传输走普通 HTTP（Node ≥18 / 浏览器全局 fetch），不经宿主端口——开发期/工具链/
+ * 面板 dev 预览均可直接用。开发者 key（开发验证凭证）预留请求头位，服务端校验
+ * 后续接入。
+ */
+function injectedPluginCode() {
+    return typeof __MBWS_PLUGIN_CODE__ !== "undefined" ? __MBWS_PLUGIN_CODE__ : undefined;
+}
+/** manifest.id 按 baseURI 记忆化——同一页面重复调用不再多发 manifest 请求 */
+const manifestIdCache = new Map();
+/** 从本工程根读 manifest.id（dev server / 解包产物内 manifest.json 均在 baseURI 根） */
+async function readManifestId() {
+    try {
+        const cached = manifestIdCache.get(document.baseURI);
+        if (cached)
+            return cached;
+        const response = await fetch(new URL("manifest.json", document.baseURI));
+        if (!response.ok)
+            throw new Error(`manifest.json ${response.status}`);
+        const manifest = (await response.json());
+        if (typeof manifest.id === "string" && manifest.id) {
+            manifestIdCache.set(document.baseURI, manifest.id);
+            return manifest.id;
+        }
+        throw new Error("manifest.id 缺失");
+    }
+    catch (error) {
+        throw new Error(`无法从本工程读取 manifest.id（${error instanceof Error ? error.message : error}）；` +
+            "非浏览器环境请显式传 pluginCode");
+    }
+}
+/** 按插件编号拉关联任务的最新契约。非 2xx 抛带状态码与后端 message 的 Error。 */
+export async function fetchContract(opts = {}) {
+    const pluginCode = opts.pluginCode ?? injectedPluginCode() ?? (await readManifestId());
+    const baseUrl = (opts.baseUrl ?? "").replace(/\/+$/, "");
+    const headers = {};
+    if (opts.devKey)
+        headers["X-Dev-Key"] = opts.devKey;
+    const response = await fetch(`${baseUrl}/api/plugin-dev-tasks/contract/by-plugin/${encodeURIComponent(pluginCode)}`, { headers, signal: opts.signal });
+    if (!response.ok) {
+        let message = `契约拉取失败（HTTP ${response.status}）`;
+        try {
+            const body = (await response.json());
+            if (typeof body.message === "string" && body.message)
+                message = body.message;
+        }
+        catch {
+            // 非 JSON 错误体，保留状态码信息
+        }
+        throw new Error(message);
+    }
+    const data = (await response.json());
+    return {
+        contractId: String(data.contract_id ?? ""),
+        title: String(data.title ?? ""),
+        consumes: Array.isArray(data.consumes) ? data.consumes.map(String) : [],
+        inputs: data.inputs ?? {},
+        outputs: data.outputs ?? {},
+        status: String(data.status ?? ""),
+        updatedAt: String(data.updated_at ?? ""),
+    };
+}

package/dist/dev-mock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * dev mock——开发环境（harness/单测/dev server 直接起）无宿主端口时的降级实现（设计稿 §6.3）。
+ *
+ * 语义边界：data.read 回 `samples/` 夹具数据；data.apply 只在控制台输出、不入任何库；
+ * 其余命名空间 no-op。插件代码零环境分支——同一份代码在 harness 里跑 mock、在宿主里跑真端口。
+ */
+import type { MbwsClient } from "./client.js";
+/**
+ * 创建 dev mock 客户端。四个固定命名空间全部构造（dev 无授权语义），
+ * panel 生命周期面上报/应答均无宿主可收，no-op 即可。
+ */
+export declare function createDevMockMbws(): MbwsClient;