@clipbus/plugin-sdk 0.7.0

package/docs/manifest.md

@@ -0,0 +1,149 @@
+# manifest.json 规范
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+每个 Clipbus 插件的根目录必须包含一个 `manifest.json`，宿主在加载插件时读取该文件以确定身份、入口和能力声明。
+
+---
+
+## 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `schemaVersion` | `number` | 是 | 固定 `2` |
+| `plugin` | `object` | 是 | 插件身份信息 |
+| `install` | `object` | 否 | 安装期 hook 配置 |
+| `runtime` | `object` | 是 | runtime 与 UI 根目录 |
+| `permissions` | `string[]` | 否 | mutation 权限声明（缺省 `[]`） |
+| `attachmentRenderers` | `object[]` | 否 | attachment renderer 列表 |
+| `detectors` | `object[]` | 否 | detector 列表 |
+| `actions` | `object[]` | 否 | action 列表 |
+
+---
+
+## `plugin`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `plugin.id` | `string` | 是 | 稳定命名空间，建议反向域名（`plugin.example.demo`） |
+| `plugin.title` | `string` | 是 | 显示名称 |
+| `plugin.version` | `string` | 是 | 版本号；宿主按字符串处理 |
+
+---
+
+## `install`（可选）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `install.runtime` | `'node' \| 'bash'` | 是 | 安装脚本运行时 |
+| `install.entry` | `string` | 是 | 脚本路径，相对插件根目录，不允许逃出 |
+
+---
+
+## `runtime`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `runtime.nodeEntry` | `string` | 是 | Node runtime 入口（编译后 `.cjs`） |
+| `runtime.uiRoot` | `string` | 是 | UI 根目录；所有 `uiEntry` 相对此目录 |
+
+---
+
+## `permissions`
+
+仅 4 个合法值：`setTags`、`setPinned`、`setAttachment`、`setSearchExtension`。声明哪个就解锁哪组 runtime mutation verb；其余 verb（clipboard、navigation、settings 读、console、attachment 读取、图片临时路径等）默认就能调。
+
+完整的权限-到-verb 映射、声明示例与最小权限原则见 [permissions.md](./permissions.md)。
+
+---
+
+## `attachmentRenderers[]`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | `string` | 是 | 局部 ID，同插件内唯一 |
+| `title` | `string` | 是 | 显示名称 |
+| `attachmentType` | `string` | 是 | 该 renderer 负责的 attachment type，建议 `plugin.id + "."` 前缀 |
+| `height` | `number \| "auto" \| { min, max }` | 否 | 卡片高度策略，见下 |
+| `uiEntry` | `string` | 否 | HTML 入口，相对 `runtime.uiRoot` |
+
+**height 三种形态：**
+
+```json
+{ "height": 320 }                          // 固定高度（1–800 px）
+{ "height": "auto" }                       // 自适应，默认范围 [80, 800]
+{ "height": { "min": 120, "max": 480 } }   // 有界范围
+```
+
+省略 `height` 等价于 `{ "min": 80, "max": 400 }`。`"auto"` 与 `{ min, max }` 下，**UI 必须显式调用 `clipbus.window.autoFit()`**——SDK 不会自动启动。
+
+---
+
+## `detectors[]`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | `string` | 是 | 局部 ID |
+| `title` | `string` | 是 | 显示名称 |
+| `supportedInputKinds` | `string[]` | 是 | `'text' \| 'image' \| 'path_reference'`；非空 |
+| `attachmentTypes` | `string[]` | 是 | 可能产出的 attachment type；每项须在 `attachmentRenderers[]` 中有对应 renderer |
+
+---
+
+## `actions[]`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | `string` | 是 | 局部 ID |
+| `title` | `string` | 是 | 显示名称 |
+| `supportedItemTypes` | `string[]` | 是 | `'text' \| 'image' \| 'path_reference'`；非空 |
+| `lifecycle` | `'auto-run' \| 'draft'` | 是 | action 生命周期 |
+| `keywords` | `string[]` | 否 | Action catalog 搜索关键词 |
+| `uiEntry` | `string` | 否 | `lifecycle: 'draft'` 时必填 |
+
+---
+
+## 最小完整示例
+
+```json
+{
+  "schemaVersion": 2,
+  "plugin": {
+    "id": "plugin.example.sample",
+    "title": "Sample Plugin",
+    "version": "0.1.0"
+  },
+  "runtime": {
+    "nodeEntry": "dist/runtime/index.cjs",
+    "uiRoot": "dist/ui"
+  },
+  "permissions": ["setTags"],
+  "attachmentRenderers": [
+    {
+      "id": "sample-card",
+      "title": "Sample Card",
+      "attachmentType": "plugin.example.sample.card",
+      "height": 320,
+      "uiEntry": "renderers/sample/index.html"
+    }
+  ],
+  "detectors": [
+    {
+      "id": "sample-detector",
+      "title": "Sample Detector",
+      "supportedInputKinds": ["text"],
+      "attachmentTypes": ["plugin.example.sample.card"]
+    }
+  ],
+  "actions": [
+    {
+      "id": "sample-apply",
+      "title": "Apply Sample",
+      "supportedItemTypes": ["text"],
+      "lifecycle": "draft",
+      "keywords": ["sample", "apply"],
+      "uiEntry": "actions/sample/index.html"
+    }
+  ]
+}
+```

package/docs/permissions.md

@@ -0,0 +1,32 @@
+# 权限模型
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+## manifest 声明
+
+在插件 manifest 的 `permissions` 字段列出插件需要的权限：
+
+```json
+{ "permissions": ["setTags", "setPinned"] }
+```
+
+未声明的权限对应方法在宿主侧 reject。manifest 结构详见 [manifest.md](./manifest.md)。
+
+## 受门控的 Verb
+
+以下 `host.*` verb 需要在 manifest 中显式声明对应权限才能调用：
+
+| 权限 | runtime Verb |
+|---|---|
+| `setTags` | `host.item.setTags` / `addTags` / `removeTags` |
+| `setPinned` | `host.item.setPinned` |
+| `setAttachment` | `host.item.setAttachments` |
+| `setSearchExtension` | `host.item.setSearchExtension` |
+
+**不受门控：** `host.clipboard.*`、`host.navigation.*`、`host.settings.*`（只读）、`host.console.log`、`host.action.allocateImageTempPath`、`host.item.materializeImagePath`、`host.item.readAttachment`、所有 `clipbus.*` 中的 UI 专属 verb（`window.*`、`action.setButtons`、`action.complete`、`attachmentRenderer.setButtons` 等）。
+
+各 verb 的完整签名见 [API.md](../API.md)。
+
+## 最小权限原则
+
+只声明真正会调的权限。多声明不会导致功能异常，但会在宿主权限审查中显得可疑。

package/docs/rpc.md

@@ -0,0 +1,84 @@
+# UI ↔ Runtime RPC
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+让 UI 调用插件自己的 Node runtime 逻辑，无需写 native 桥接。
+
+## 直接接口
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+// clipbus.runtime.invoke<TResp> 直接返回 TResp（SDK 已自动解 wire envelope）
+const { title } = await clipbus.runtime.invoke<{ title: string }>({
+  key: 'fetch-title',
+  payload: { url: 'https://example.com' },
+  timeoutMs: 10_000,  // 可选；默认 30_000 ms
+});
+```
+
+Runtime 端：
+
+```ts
+const { definePlugin } = require('@clipbus/plugin-sdk/runtime');
+
+module.exports = definePlugin({
+  messageHandlers: {
+    'fetch-title': async (req, ctx) => {
+      const html = await fetch(req.url).then(r => r.text());
+      return { title: html.match(/<title>(.*?)<\/title>/)?.[1] ?? '' };
+    },
+  },
+});
+```
+
+## `defineMessage` —— 两端共享契约（推荐写法）
+
+`defineMessage<TReq, TResp>(key)` 把字符串 key + 类型一起钉死，两端导入同一契约：
+
+```ts
+// shared/contracts.ts —— 仅做类型，避免拼字符串
+import { defineMessage } from '@clipbus/plugin-sdk/runtime';   // 或 /ui，类型完全相同
+export const FetchTitle = defineMessage<{ url: string }, { title: string }>('fetch-title');
+
+// runtime/index.ts
+const { definePlugin } = require('@clipbus/plugin-sdk/runtime');
+const { FetchTitle } = require('../shared/contracts');
+
+module.exports = definePlugin({
+  messageHandlers: Object.fromEntries([
+    FetchTitle.handle(async (req, ctx) => {
+      const html = await fetch(req.url).then(r => r.text());
+      return { title: html.match(/<title>(.*?)<\/title>/)?.[1] ?? '' };
+    }),
+  ]),
+});
+
+// ui/app.ts
+import { FetchTitle } from '../shared/contracts';
+const { title } = await FetchTitle.invoke({ url: 'https://example.com' }, { timeoutMs: 10_000 });
+```
+
+## 超时与错误
+
+- 默认超时 **30 秒**；用 `options.timeoutMs` 覆盖
+- handler 中 `throw` 一个 Error，UI 侧 `await` reject，`name` 与 `data` 跨进程保留：
+
+```ts
+// runtime 端
+throw Object.assign(new Error('rate limited'), {
+  name: 'RateLimitError',
+  data: { retryAfterSec: 60 },
+});
+
+// UI 端
+try {
+  await FetchTitle.invoke({ url });
+} catch (err: any) {
+  if (err.name === 'RateLimitError') {
+    console.log('retry in', err.data.retryAfterSec, 's');
+  }
+}
+```
+
+- **不**支持通过此通道传图片字节（参见 [item-context.md](./item-context.md)）

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@clipbus/plugin-sdk",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
+  "keywords": [
+    "clipbus",
+    "plugin",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scubers/clipbus.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/runtime/index.cjs",
+  "exports": {
+    "./runtime": {
+      "import": {
+        "types": "./dist/runtime/index.d.ts",
+        "default": "./dist/runtime/index.js"
+      },
+      "require": {
+        "types": "./dist/runtime/index.d.cts",
+        "default": "./dist/runtime/index.cjs"
+      }
+    },
+    "./ui": {
+      "import": {
+        "types": "./dist/ui/index.d.ts",
+        "default": "./dist/ui/index.js"
+      },
+      "require": {
+        "types": "./dist/ui/index.d.cts",
+        "default": "./dist/ui/index.cjs"
+      }
+    },
+    "./dom": {
+      "import": {
+        "types": "./dist/dom/index.d.ts",
+        "default": "./dist/dom/index.js"
+      },
+      "require": {
+        "types": "./dist/dom/index.d.cts",
+        "default": "./dist/dom/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "prepare": "node ./scripts/build.mjs",
+    "build": "node ./scripts/build.mjs",
+    "pretest": "node ./scripts/build.mjs",
+    "test": "node --require ./tests/setup.cjs --test 'tests/**/*.test.cjs'",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "files": [
+    "dist",
+    "SPECIFICATION.md",
+    "README.md",
+    "API.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.0",
+    "esbuild": "^0.25.0",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.0.0"
+  }
+}