@mbws/plugin-sdk 0.1.0 → 0.1.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mbws/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Moye 插件开发 SDK——panel/viewer 与宿主的类型定义与运行时端口适配",
   "license": "MIT",
   "type": "module",
@@ -15,11 +15,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mobiwusi-dev/Union.git",
-    "directory": "packages/plugin-sdk"
-  },
   "files": [
     "dist"
   ],