@mbws/plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,28 +1,109 @@
 # @mbws/plugin-sdk
 
-Moye 插件开发 SDK——插件 panel/viewer 与宿主之间的类型定义与运行时端口适配。
+MBWS 数据加工插件协议 SDK——为插件面板提供 `createMbws()` 与宿主完成握手，返回带
+`data` / `runtime` / `storage` / `ui` / `panel` / `contract` 命名空间的客户端对象。
+通常你不需要手动安装本包：用 `pnpm create @mbws/plugin` 脚手架生成的工程已自带依赖；
+手动集成时再 `pnpm add @mbws/plugin-sdk`。
+
+## 安装
 
 ```bash
 pnpm add @mbws/plugin-sdk
 ```
 
-## 能力
+要求 Node ≥18（或现代浏览器环境）；包内零运行时依赖（类型与运行时均为自带实现）。
 
-- **类型**：`Manifest`（配置与权限声明）、端口调用契约等——`mbws.config.ts` 与面板代码
-  共用同一套类型源
-- **运行时**：宿主端口注入适配（桌面/网页宿主零感知），dev 环境自动降级 mock
-  （`data.read` 读 `samples/*.json`，本地 `pnpm dev` 即可跑通面板）
-- **校验**：`validateManifest`（构建期与装载期单一权威校验源）
+## 最小面板示例
 
-## 工程起步
+```ts
+import { createMbws } from "@mbws/plugin-sdk";
 
-用脚手架生成带本 SDK 的完整工程：
+const mbws = await createMbws();
 
-```bash
-pnpm create @mbws/plugin my-tool
+// 读输入数据（key 见关联任务的契约 inputs）
+const value = await mbws.data.read("input");
+
+// 面板内容变化后按内容自适应高度，宿主会同步调整 iframe 高度
+mbws.panel.resize(document.body.scrollHeight);
+
+// 计算完成，写回输出（outputs 的 key 集须与契约 outputs 对齐，越界会被拒）
+await mbws.data.apply({ result: transform(value) });
+```
+
+注意 `createMbws()` 全局只能调用一次（与 VS Code `acquireVsCodeApi` 同心智），二次调用
+会抛 `MbwsInvokeError`（`E_PROTOCOL_VIOLATION`）。
+
+## API 速查
+
+握手成功后返回 `MbwsClient`。除 `panel` / `contract` 恒存在外，其余命名空间按
+manifest 权限授予情况存在——未声明/未授予的命名空间在对象上为 `undefined`，使用前
+建议判空。
+
+| 命名空间.方法 | 签名 | 用途 |
+| --- | --- | --- |
+| `data.read` | `read(key: string): Promise<unknown>` | 读当前任务 slot 的输入值 |
+| `data.blob` | `blob(key: string): Promise<{ url: string; mime?: string }>` | 拿文件类输入的签名访问 URL |
+| `data.apply` | `apply(outputs: Record<string, unknown>): Promise<void>` | 写回输出（经宿主 write gate 校验） |
+| `runtime.progress` | `progress(ratio?: number, message?: string): Promise<void>` | 上报进度（0~1）与状态文案 |
+| `runtime.log` | `log(...args: unknown[]): Promise<void>` | 写运行日志（宿主侧可查看） |
+| `runtime.signal` | `signal(): AbortSignal` | 取消信号——用户取消任务时 abort |
+| `storage.get` | `get(key: string): Promise<unknown>` | 读插件专属配额 KV |
+| `storage.set` | `set(key: string, value: unknown): Promise<void>` | 写插件专属配额 KV（配额超限抛错） |
+| `ui.confirm` | `confirm(opts: { title?: string; message: string }): Promise<boolean>` | 宿主渲染的确认弹窗 |
+| `ui.toast` | `toast(message: string, opts?: { type?: "info" \| "success" \| "error" }): Promise<void>` | 宿主渲染的轻提示 |
+| `panel.resize` | `resize(height: number): void` | 上报面板期望高度 |
+| `panel.onBeforeClose` | `onBeforeClose(cb: () => void): void` | 注册关闭前询问回调 |
+| `panel.replyBeforeClose` | `replyBeforeClose(dirty: boolean): void` | 应答关闭询问（dirty=true 宿主先弹确认） |
+| `contract.get` | `get(opts?: FetchContractOptions): Promise<PluginContract>` | 拉关联任务的最新数据契约 |
+
+`contract.get` 不经宿主端口，直接走 HTTP 按插件编号拉取：返回的
+`PluginContract` 含 `inputs` / `outputs`（key → JSON Schema，`data.read` / `data.apply`
+的对齐基准）、`title`、`status`、`updatedAt` 等。`FetchContractOptions` 可传
+`pluginCode`（缺省从工程 `manifest.json` 读）、`baseUrl`、`devKey`、`signal`。
+
+## 运行形态
+
+插件代码零环境分支——`createMbws()` 内部自动分辨：
+
+- **生产（宿主 sandbox iframe 内）**：等待宿主经 `window.postMessage` 递来的
+  `MessagePort`，完成 init 握手后按授权构造命名空间。此后所有调用都走端口消息。
+- **开发（本地 `pnpm dev` / 顶窗口 / 端口等待超时）**：自动降级为 dev mock——
+  `data.read` 读工程内 `samples/<key>.json` 夹具数据；`data.apply` 只在控制台打印不入库；
+  其余命名空间基本 no-op。`contract.get` 仍真实走 HTTP 拉线上契约。
+
+握手等待端口默认 3000ms（`createMbws({ timeoutMs })` 可调），单次调用默认 30s 超时
+（`invokeTimeoutMs` 可调）。
+
+## 错误处理
+
+调用被拒时抛 `MbwsInvokeError`（`Error` 子类），`error.code` 为以下九个错误码之一：
+
+| 错误码 | 含义 |
+| --- | --- |
+| `E_INVALID_ARGS` | 调用参数不符合方法签名 |
+| `E_UNKNOWN_METHOD` | 调用了命名空间下不存在的方法 |
+| `E_PERMISSION_DENIED` | manifest 未声明该权限，或宿主未授予 |
+| `E_QUOTA_EXCEEDED` | 配额超限（AI 次数/费用、指令预算、wall-clock 超时等） |
+| `E_WRITE_GATE_REJECTED` | `apply` 写回被拒（key 越界 / outputSchema 校验失败） |
+| `E_CAPABILITY_UNAVAILABLE` | 依赖的能力包未安装或版本不满足 |
+| `E_TIMEOUT` | 调用超时 |
+| `E_CANCELLED` | 任务被取消后的在途调用收尾 |
+| `E_PROTOCOL_VIOLATION` | 消息违反协议（含 `createMbws()` 二次调用） |
+
+```ts
+import { createMbws, MbwsInvokeError } from "@mbws/plugin-sdk";
+
+const mbws = await createMbws();
+try {
+  await mbws.data.apply({ result: 1 });
+} catch (error) {
+  if (error instanceof MbwsInvokeError && error.code === "E_WRITE_GATE_REJECTED") {
+    // outputs key 集与契约不对齐，按 error.data 提示修正
+  }
+}
 ```
 
-## 版本与平台受控构建
+## 另请参阅
 
-平台在线构建时按任务钉定的版本经票据下发 tarball（版本受控，不跟 registry 走）；
-npm 上的本包供插件开发者本地开发与类型提示用。
+- 工程脚手架：[`@mbws/create-plugin`](https://www.npmjs.com/package/@mbws/create-plugin)
+  （`pnpm create @mbws/plugin <目录>` 一条命令生成带本 SDK 的完整插件工程）

package/dist/contract.js

@@ -12,6 +12,9 @@
 function injectedPluginCode() {
     return typeof __MBWS_PLUGIN_CODE__ !== "undefined" ? __MBWS_PLUGIN_CODE__ : undefined;
 }
+function injectedDevContractBase() {
+    return typeof __MBWS_DEV_CONTRACT_BASE__ !== "undefined" ? __MBWS_DEV_CONTRACT_BASE__ : undefined;
+}
 /** manifest.id 按 baseURI 记忆化——同一页面重复调用不再多发 manifest 请求 */
 const manifestIdCache = new Map();
 /** 从本工程根读 manifest.id（dev server / 解包产物内 manifest.json 均在 baseURI 根） */
@@ -38,11 +41,12 @@ async function readManifestId() {
 /** 按插件编号拉关联任务的最新契约。非 2xx 抛带状态码与后端 message 的 Error。 */
 export async function fetchContract(opts = {}) {
     const pluginCode = opts.pluginCode ?? injectedPluginCode() ?? (await readManifestId());
-    const baseUrl = (opts.baseUrl ?? "").replace(/\/+$/, "");
+    // URL 前缀：dev 注入值优先（同源走插件中间件，免 CORS），否则 baseUrl（缺省同源相对）
+    const prefix = injectedDevContractBase() ?? (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 });
+    const response = await fetch(`${prefix}/api/plugin-dev-tasks/contract/by-plugin/${encodeURIComponent(pluginCode)}`, { headers, signal: opts.signal });
     if (!response.ok) {
         let message = `契约拉取失败（HTTP ${response.status}）`;
         try {

package/dist/vite.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "vite";
+import { type MbwsUserConfig } from "./config.js";
+export interface MbwsVitePluginOptions {
+    /** mbws.config.ts 的配置（defineConfig 回传值）——静态合同与动态开发配置同住 */
+    config: MbwsUserConfig;
+}
+/**
+ * mbws vite 插件。dev 预览下契约拉取同源化：SDK fetchContract 读到注入的
+ * `__MBWS_DEV_CONTRACT_BASE__` 后改打 `/__mbws__/api/...`，由本插件的中间件
+ * 转发到真实后端——插件 dev 端口不在后端 CORS 白名单的问题由此消解。
+ */
+export declare function mbwsVitePlugin(opts: MbwsVitePluginOptions): Plugin;

package/dist/vite.js

@@ -0,0 +1,145 @@
+/**
+ * 插件工程的 vite 插件——把平台机械（manifest 派生 / define 注入 / dev 虚拟供给与
+ * 后端转发）收敛进 SDK，工程 vite.config.ts 只留 `mbwsVitePlugin({ config })` 一行。
+ *
+ * 承担四件事（对齐原脚手架模板内联版语义）：
+ * - define 注入插件编号（build/serve 都注入），serve 额外注入 dev 契约前缀；
+ * - 缺省补 base: "./"（产物在 OSS 子目录 / registry 代理路径下托管）与双入口
+ *   rollupOptions.input（panel.html / viewer.html），用户已设项不覆盖；
+ * - dev 虚拟供给 /manifest.json（buildManifest 派生，与 build 产物同源）；
+ * - dev 转发 /__mbws__/api/* 到后端（Node 全局 fetch，不走 server.proxy——
+ *   用户自己的 proxy 配置自由，互不干扰）；
+ * - build 后往 dist/<id>@<version>/ 写 manifest.json（产物直出解包形态目录）。
+ *
+ * vite 只进 devDependencies 供类型与测试（type-only import），SDK 产物不依赖 vite。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { buildManifest } from "./config.js";
+/** dev 契约拉取的专属命名空间：同源走插件中间件转发，免 CORS */
+const DEV_CONTRACT_BASE = "/__mbws__";
+/** 后端缺省地址：插件开发者缺省连线上（拉线上 spec），本地联调走 env 或 apiBaseUrl */
+const DEFAULT_API_BASE = "https://union.mobiwusi.com";
+/** dev 转发目标：config.apiBaseUrl > shell env > 线上（发包即线上，地址不是工程配置项） */
+function resolveApiBase(config) {
+    return (config.apiBaseUrl ?? process.env.MBWS_API_BASE_URL ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+}
+/** 读请求体（POST 等带 body 的转发用；GET/HEAD 直接跳过） */
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/**
+ * mbws vite 插件。dev 预览下契约拉取同源化：SDK fetchContract 读到注入的
+ * `__MBWS_DEV_CONTRACT_BASE__` 后改打 `/__mbws__/api/...`，由本插件的中间件
+ * 转发到真实后端——插件 dev 端口不在后端 CORS 白名单的问题由此消解。
+ */
+export function mbwsVitePlugin(opts) {
+    const { config } = opts;
+    // 工程 root：config 钩子里记（用户显式 root 优先），closeBundle 写产物时用
+    let projectRoot = process.cwd();
+    // manifest 是纯派生物，构建/供给共用同一序列化姿势（尾换行对齐文件写习惯）
+    const manifestJson = () => `${JSON.stringify(buildManifest(config), null, 2)}\n`;
+    return {
+        name: "mbws-plugin",
+        config(userConfig, { command }) {
+            projectRoot = userConfig.root ?? process.cwd();
+            const define = {
+                __MBWS_PLUGIN_CODE__: JSON.stringify(config.id),
+            };
+            // dev 专用前缀只在 serve 注入——build 产物绝不含 /__mbws__（宿主内无此路由）
+            if (command === "serve") {
+                define.__MBWS_DEV_CONTRACT_BASE__ = JSON.stringify(DEV_CONTRACT_BASE);
+            }
+            // 增量配置（vite 浅合并，不覆盖用户已设项）
+            const incremental = { define };
+            // 相对 base：产物在 OSS 子目录 / registry 代理路径下托管，资源引用必须是 ./ 相对路径
+            if (!userConfig.base)
+                incremental.base = "./";
+            // 只打包宿主要装载的两个入口；根 index.html 欢迎页是 dev 导航，不进产物
+            if (!userConfig.build?.rollupOptions?.input) {
+                incremental.build = {
+                    rollupOptions: {
+                        input: [
+                            path.resolve(projectRoot, "panel.html"),
+                            path.resolve(projectRoot, "viewer.html"),
+                        ],
+                    },
+                };
+            }
+            // 依赖预构建不消费顶层 define，漏了 SDK 里的注入读取在 dev 侧失效
+            if (command === "serve") {
+                incremental.optimizeDeps = {
+                    esbuildOptions: { define: { __MBWS_PLUGIN_CODE__: JSON.stringify(config.id) } },
+                };
+            }
+            return incremental;
+        },
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const pathname = (req.url ?? "").split("?")[0];
+                if (pathname === "/manifest.json") {
+                    // dev 虚拟供给：SDK fetchContract 的 manifest 兜底读取在 dev/产物两形态行为一致
+                    res.setHeader("content-type", "application/json");
+                    res.end(manifestJson());
+                    return;
+                }
+                if (pathname.startsWith(`${DEV_CONTRACT_BASE}/api`)) {
+                    // 转发异步进行，失败交 next（connect 约定）；返回 promise 供测试 await
+                    return forwardApi(config, req, res).catch(next);
+                }
+                next();
+                return undefined;
+            });
+        },
+        closeBundle() {
+            // 产物直出解包形态目录 <id>@<version>/，桌面 MBWS_DEV_PLUGIN_DIR 指向 dist 即装载
+            const outDir = path.resolve(projectRoot, `dist/${config.id}@${config.version}`);
+            // mkdir 容错：在线构建场景 outDir 被平台覆盖，本目录可能不存在（写失败会炸构建）
+            fs.mkdirSync(outDir, { recursive: true });
+            fs.writeFileSync(path.join(outDir, "manifest.json"), manifestJson());
+        },
+    };
+}
+/** /__mbws__/<rest> → <apiBase>/<rest>：方法/头透传，响应状态码/content-type/body 透传 */
+async function forwardApi(config, req, res) {
+    const pathname = (req.url ?? "").split("?")[0];
+    const rest = pathname.slice(DEV_CONTRACT_BASE.length);
+    try {
+        // 头透传（host/connection 是逐跳头，指向 dev server 自身，不能带给后端）
+        const headers = {};
+        for (const [key, value] of Object.entries(req.headers)) {
+            if (value === undefined || key === "host" || key === "connection")
+                continue;
+            headers[key] = Array.isArray(value) ? value.join(", ") : String(value);
+        }
+        const method = req.method ?? "GET";
+        const body = method === "GET" || method === "HEAD"
+            ? undefined
+            : (await readRequestBody(req));
+        // 查询串原样保留（/api/x?k=v 转发不丢参）
+        const search = (req.url ?? "").slice(pathname.length);
+        const upstream = await fetch(`${resolveApiBase(config)}${rest}${search}`, {
+            method,
+            headers,
+            body,
+        });
+        res.statusCode = upstream.status;
+        const contentType = upstream.headers.get("content-type");
+        if (contentType)
+            res.setHeader("content-type", contentType);
+        res.end(Buffer.from(await upstream.arrayBuffer()));
+    }
+    catch (error) {
+        // 转发失败按网关错误处理：JSON 错误体对齐后端统一错误格式
+        res.statusCode = 502;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({
+            message: `mbws dev forward failed: ${error instanceof Error ? error.message : String(error)}`,
+        }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mbws/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Moye 插件开发 SDK——panel/viewer 与宿主的类型定义与运行时端口适配",
   "license": "MIT",
   "type": "module",
@@ -10,24 +10,27 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mobiwusi-dev/Union.git",
-    "directory": "packages/plugin-sdk"
-  },
   "files": [
     "dist"
   ],
   "dependencies": {
     "zod": "^4.4.3"
   },
+  "devDependencies": {
+    "vite": "^8.0.14"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
     "pack:sdk": "pnpm build && pnpm pack"
   }
 }