@clipbus/plugin-sdk 0.7.0

package/dist/ui/index.js

@@ -0,0 +1,339 @@
+// src/generated/wireConstants.generated.ts
+var STRUCTURED_ERROR_PREFIX = "__clipbus_structured_error__:";
+var CAPABILITIES_GLOBAL = "__CLIPBUS_PLUGIN_CAPABILITIES__";
+var CAPABILITY_UNSUPPORTED_ERROR_NAME = "PluginCapabilityUnsupported";
+
+// src/internal/capabilities.ts
+var CapabilityUnsupportedError = class extends Error {
+  capability;
+  constructor(capability) {
+    super(`Capability not supported by host: ${capability}`);
+    this.name = "CapabilityUnsupportedError";
+    this.capability = capability;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function readInjectedCapabilities(global, key) {
+  const obj = global;
+  const raw = obj?.[key];
+  if (Array.isArray(raw?.capabilities)) {
+    return new Set(raw.capabilities);
+  }
+  return /* @__PURE__ */ new Set();
+}
+function createCapabilitiesApi(getSet) {
+  return {
+    has: (name) => getSet().has(name)
+  };
+}
+function mapToCapabilityError(err, unsupportedName) {
+  if (err.name === unsupportedName) {
+    const cap = err.data?.capability ?? "";
+    return new CapabilityUnsupportedError(cap);
+  }
+  const m = /^Unknown method:\s*(.+)$/.exec(err.message);
+  if (m) return new CapabilityUnsupportedError(m[1]);
+  return err;
+}
+
+// src/internal/runtimeInvokeClient.ts
+var HANDLER_NAME = "clipbusPluginCall";
+async function callRuntimeInvokeStrict(payload) {
+  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME];
+  if (!handler) {
+    throw new Error("runtime.invoke is only available inside a Clipbus plugin WebView");
+  }
+  const normalized = JSON.parse(JSON.stringify(payload));
+  let reply;
+  try {
+    reply = await handler.postMessage({ method: "runtime.invoke", payload: normalized });
+  } catch (err) {
+    throw parseReplyError(err);
+  }
+  return reply?.response;
+}
+function parseReplyError(raw) {
+  const message = extractMessage(raw);
+  if (message.startsWith(STRUCTURED_ERROR_PREFIX)) {
+    const json = message.slice(STRUCTURED_ERROR_PREFIX.length);
+    try {
+      const parsed = JSON.parse(json);
+      const err = new Error(typeof parsed.message === "string" ? parsed.message : "");
+      if (typeof parsed.name === "string" && parsed.name.length > 0) {
+        err.name = parsed.name;
+      }
+      if (parsed.data !== void 0) {
+        err.data = parsed.data;
+      }
+      return mapToCapabilityError(err, CAPABILITY_UNSUPPORTED_ERROR_NAME);
+    } catch {
+      return new Error(message);
+    }
+  }
+  return mapToCapabilityError(new Error(message), CAPABILITY_UNSUPPORTED_ERROR_NAME);
+}
+function extractMessage(raw) {
+  if (typeof raw === "string") return raw;
+  if (raw instanceof Error) return raw.message;
+  if (raw && typeof raw === "object" && "message" in raw) {
+    const m = raw.message;
+    if (typeof m === "string") return m;
+  }
+  return String(raw);
+}
+
+// src/generated/capabilityClients.generated.ts
+var HANDLER_NAME2 = "clipbusPluginCall";
+async function callPluginMethod(method, payload) {
+  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME2];
+  if (!handler) {
+    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
+    err.name = "PluginHostBridgeUnavailable";
+    throw err;
+  }
+  const normalized = JSON.parse(JSON.stringify(payload));
+  let reply;
+  try {
+    reply = await handler.postMessage({ method, payload: normalized });
+  } catch (err) {
+    throw parseReplyError(err);
+  }
+  return reply;
+}
+var callItemReadAttachment = (payload) => callPluginMethod("item.readAttachment", payload);
+var callAssetCurrentItemImageUrl = () => callPluginMethod("asset.currentItemImageUrl", {});
+var callAssetPathReferenceImageUrl = (payload) => callPluginMethod("asset.pathReferenceImageUrl", payload);
+var callClipboardCopyText = (payload) => callPluginMethod("clipboard.copyText", payload);
+var callNavigationOpenUrl = (payload) => callPluginMethod("navigation.openUrl", payload);
+var callNavigationRevealInFinder = (payload) => callPluginMethod("navigation.revealInFinder", payload);
+var callNavigationOpenFilePath = (payload) => callPluginMethod("navigation.openFilePath", payload);
+var callActionSetButtons = (payload) => callPluginMethod("action.setButtons", payload);
+var callActionComplete = (payload) => callPluginMethod("action.complete", payload);
+var callAttachmentRendererSetButtons = (payload) => callPluginMethod("attachmentRenderer.setButtons", payload);
+var callWindowSetHeight = (payload) => callPluginMethod("window.setHeight", payload);
+var callWindowAutoFit = () => callPluginMethod("window.autoFit", {});
+var callInfoPanelOpen = (payload) => callPluginMethod("infoPanel.open", payload);
+var callInfoPanelClose = (payload) => callPluginMethod("infoPanel.close", payload);
+var callSettingsGet = (payload) => callPluginMethod("settings.get", payload);
+var callSettingsGetAll = () => callPluginMethod("settings.getAll", {});
+var callConsoleLog = (payload) => callPluginMethod("console.log", payload);
+var callTextInputStateChanged = (payload) => callPluginMethod("textInput.stateChanged", payload);
+
+// src/internal/topic.ts
+function createTopic(initial) {
+  let value = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    current: () => value,
+    on(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    set(next) {
+      value = next;
+      for (const l of listeners) {
+        try {
+          l(value);
+        } catch {
+        }
+      }
+    }
+  };
+}
+function createStream() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    on(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    emit(event) {
+      for (const l of listeners) {
+        try {
+          l(event);
+        } catch {
+        }
+      }
+    }
+  };
+}
+function readWindowGlobal(key) {
+  if (typeof window === "undefined") return void 0;
+  return window[key];
+}
+
+// src/generated/topicSubscribers.generated.ts
+function onContext(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-context", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-context", handler);
+}
+function onItem(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-item", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-item", handler);
+}
+function onAttachment(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-attachment", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-attachment", handler);
+}
+function onDraft(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-draft", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-draft", handler);
+}
+function onTheme(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-theme", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-theme", handler);
+}
+function onAttachmentHostInvoke(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-attachment-host-invoke", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-attachment-host-invoke", handler);
+}
+function onActionHostInvoke(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-action-host-invoke", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-action-host-invoke", handler);
+}
+function onInfoPanelOnAction(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-info-panel-on-action", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-action", handler);
+}
+function onInfoPanelOnClose(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-info-panel-on-close", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-close", handler);
+}
+
+// src/generated/ui.bootstrap.generated.ts
+var _pluginContextTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_CONTEXT__"));
+onContext((p) => _pluginContextTopic.set(p));
+var _itemTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ITEM__"));
+onItem((p) => _itemTopic.set(p));
+var _itemAttachmentTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ATTACHMENT__"));
+onAttachment((p) => _itemAttachmentTopic.set(p));
+var _actionDraftTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_DRAFT__"));
+onDraft((p) => _actionDraftTopic.set(p));
+var _themeTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_THEME__"));
+onTheme((p) => _themeTopic.set(p));
+var _attachmentRendererOnHostInvokeStream = createStream();
+onAttachmentHostInvoke((p) => _attachmentRendererOnHostInvokeStream.emit(p));
+var _actionOnHostInvokeStream = createStream();
+onActionHostInvoke((p) => _actionOnHostInvokeStream.emit(p));
+var _infoPanelOnActionStream = createStream();
+onInfoPanelOnAction((p) => _infoPanelOnActionStream.emit(p));
+var _infoPanelOnCloseStream = createStream();
+onInfoPanelOnClose((p) => _infoPanelOnCloseStream.emit(p));
+var PluginContextError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginContextError";
+  }
+};
+function guardContext(expected, run) {
+  return (...args) => {
+    const current = _pluginContextTopic.current()?.mode;
+    if (current !== expected) {
+      throw new PluginContextError(
+        `This verb is not available in the current plugin context (expected: ${expected}, got: ${current || "unknown"})`
+      );
+    }
+    return run(...args);
+  };
+}
+
+// src/generated/ui.clipbus.generated.ts
+var clipbus = {
+  capabilities: createCapabilitiesApi(() => readInjectedCapabilities(globalThis, CAPABILITIES_GLOBAL)),
+  runtime: {
+    invoke: (payload) => callRuntimeInvokeStrict(payload)
+  },
+  item: {
+    current: () => _itemTopic.current(),
+    on: (fn) => _itemTopic.on(fn),
+    readAttachment: (payload) => callItemReadAttachment(payload),
+    attachment: {
+      current: () => _itemAttachmentTopic.current(),
+      on: (fn) => _itemAttachmentTopic.on(fn)
+    }
+  },
+  asset: {
+    currentItemImageUrl: () => callAssetCurrentItemImageUrl(),
+    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload)
+  },
+  clipboard: {
+    copyText: (payload) => callClipboardCopyText(payload)
+  },
+  navigation: {
+    openUrl: (payload) => callNavigationOpenUrl(payload),
+    revealInFinder: (payload) => callNavigationRevealInFinder(payload),
+    openFilePath: (payload) => callNavigationOpenFilePath(payload)
+  },
+  action: {
+    setButtons: guardContext("action", (payload) => callActionSetButtons(payload)),
+    complete: guardContext("action", (payload) => callActionComplete(payload)),
+    draft: {
+      current: () => _actionDraftTopic.current(),
+      on: (fn) => _actionDraftTopic.on(fn)
+    },
+    onHostInvoke: {
+      on: (fn) => _actionOnHostInvokeStream.on(fn)
+    }
+  },
+  attachmentRenderer: {
+    setButtons: guardContext("attachmentRenderer", (payload) => callAttachmentRendererSetButtons(payload)),
+    onHostInvoke: {
+      on: (fn) => _attachmentRendererOnHostInvokeStream.on(fn)
+    }
+  },
+  window: {
+    setHeight: (payload) => callWindowSetHeight(payload),
+    autoFit: () => callWindowAutoFit()
+  },
+  infoPanel: {
+    open: (payload) => callInfoPanelOpen(payload),
+    close: (payload) => callInfoPanelClose(payload),
+    onAction: {
+      on: (fn) => _infoPanelOnActionStream.on(fn)
+    },
+    onClose: {
+      on: (fn) => _infoPanelOnCloseStream.on(fn)
+    }
+  },
+  settings: {
+    get: (payload) => callSettingsGet(payload),
+    getAll: () => callSettingsGetAll()
+  },
+  console: {
+    log: (payload) => callConsoleLog(payload)
+  },
+  textInput: {
+    stateChanged: (payload) => callTextInputStateChanged(payload)
+  },
+  pluginContext: {
+    current: () => _pluginContextTopic.current(),
+    on: (fn) => _pluginContextTopic.on(fn)
+  },
+  theme: {
+    current: () => _themeTopic.current(),
+    on: (fn) => _themeTopic.on(fn)
+  }
+};
+
+// src/ui/defineMessage.ts
+function defineMessage(key) {
+  return {
+    key,
+    invoke: async (payload, options) => await clipbus.runtime.invoke({ key, payload, timeoutMs: options?.timeoutMs })
+  };
+}
+export {
+  CapabilityUnsupportedError,
+  PluginContextError,
+  clipbus,
+  defineMessage
+};

package/docs/README.md

@@ -0,0 +1,34 @@
+# @clipbus/plugin-sdk 开发文档
+
+这是 Clipbus 三方插件开发的**权威教程文档**，随 [`@clipbus/plugin-sdk`](https://www.npmjs.com/package/@clipbus/plugin-sdk) 一起发布——你安装/升级 SDK 时，这份文档就是与该版本匹配的最新版。
+
+> **capability 真相源是 [`../API.md`](../API.md)**（由 `protocol/plugin/src/catalog.ts` codegen 直出，保证与代码一致）。教程描述模式与约定，API.md 描述每个符号的精确 payload / response / wire path / context。**有冲突时以 `API.md` 为准。**
+
+## 文档地图
+
+按推荐阅读顺序：
+
+| 文档 | 内容 |
+|---|---|
+| [concepts.md](./concepts.md) | 架构：两个执行上下文（runtime / WebView）、三类产物（detector / renderer / action）、数据流、Host→WebView 状态形状 |
+| [manifest.md](./manifest.md) | `manifest.json` 规范：顶层字段、`plugin` / `install` / `runtime` / `permissions` / `attachmentRenderers[]` / `detectors[]` / `actions[]` |
+| [entry.md](./entry.md) | SDK 入口与初始化：runtime 入口、UI 入口、context guards、`definePlugin` |
+| [authoring.md](./authoring.md) | Detector / Renderer / Action 的开发约定与生命周期 |
+| [item-context.md](./item-context.md) | 入参形状（`PluginContentEnvelope`）、图片懒副本、Action 返回图片、在 WebView 展示本地图片（`clipbus-asset://`） |
+| [rpc.md](./rpc.md) | UI ↔ Runtime RPC：`clipbus.runtime.invoke`、`defineMessage` 共享契约、超时与错误 |
+| [permissions.md](./permissions.md) | 权限模型：manifest 声明、受门控的 verb、最小权限原则 |
+| [capability-detection.md](./capability-detection.md) | 能力检测：`has()` 门控、UI/Node 侧 catch 差异、老宿主降级 |
+| [faq.md](./faq.md) | 常见坑点 Q&A |
+
+## 同包参考
+
+| 文件 | 用途 |
+|---|---|
+| [`../API.md`](../API.md) | **capability 真相源**（generated）——capability / host event / Node IPC / 命名类型全表与精确签名 |
+| [`../README.md`](../README.md) | SDK 公共符号速查（导出、runtime 入口、UI 入口） |
+| [`../SPECIFICATION.md`](../SPECIFICATION.md) | SDK 形状规则、命名约定、扩展 capability 的流程 |
+
+## 给 AI / 工具的说明
+
+- 这份文档目录随 `npm update @clipbus/plugin-sdk` 刷新；它**始终对应你当前安装的 SDK 版本**。
+- 任何脚手架工程（template）内的代码与说明都是**示例**，可能滞后；**与本文档冲突时以本文档为准**，capability 签名以 [`../API.md`](../API.md) 为准。

package/docs/authoring.md

@@ -0,0 +1,288 @@
+# Detector / Renderer / Action 开发约定
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+---
+
+## Detector
+
+入参 `PluginDetectorInput`（完整字段见 [API.md](../API.md)）：
+
+```ts
+input.item            // PluginClipboardItem: {id, type, tags, sourceAppID}
+input.content         // PluginContentEnvelope（字段含义见 [item-context.md](./item-context.md)）
+input.attachments     // PluginAttachmentRef[]：当前 item 已有的附件引用
+```
+
+**返回值是 artifact 数组本身**（不是 `{artifacts}` 包装）：
+
+```ts
+import type { PluginDetectorHandler, PluginDetectorArtifact } from '@clipbus/plugin-sdk/runtime';
+
+const detector: PluginDetectorHandler = {
+  async detect(input, ctx) {
+    if (input.content.kind !== 'text') return [];
+
+    return [
+      {
+        attachmentType: 'plugin.example.sample.card',  // 必须已在 manifest 声明
+        attachmentKey: `card-${input.item.id}`,        // 稳定 key，不允许空字符串
+        payloadJson: JSON.stringify({ text: input.content.text }),
+        attachmentSyncScope: 'syncable',               // 'syncable' | 'local_only'
+        searchProjection: {                            // 可选
+          scope: 'sample',
+          searchText: input.content.text.slice(0, 80),
+          label: null,
+        },
+      },
+    ] satisfies PluginDetectorArtifact[];
+  },
+};
+```
+
+**约定：**
+
+- 未命中时返回 `[]`，不要返回半成品 artifact
+- Detector 内不应执行宿主 mutation（标签写入等）；那是 action 的职责
+- `attachmentType` 必须出自 manifest 的 `detectors[].attachmentTypes`（manifest 结构见 [manifest.md](./manifest.md)）
+
+---
+
+## Attachment Renderer
+
+Runtime 入口**只有** `resolveAttachment`。所有按钮副作用、用户交互都在 UI 侧完成。
+
+入参 `PluginResolveAttachmentInput`：
+
+```ts
+input.item                       // PluginClipboardItem
+input.content                    // PluginContentEnvelope
+input.attachments                // PluginAttachmentRef[]
+input.attachment                 // PluginAttachmentEntry：当前要渲染的附件
+   .historyID
+   .owner
+   .attachmentType
+   .attachmentKey
+   .payloadJson                  // 完整 JSON 字符串；插件自行解析
+```
+
+返回值 `PluginAttachmentResolveResult`：
+
+```ts
+return {
+  displayName: 'Sample Card',           // string | undefined；建议始终返回
+  tintHex: '#2563EB',                   // string | undefined；卡片强调色
+  shouldDisplay: true,                  // boolean | undefined（默认 true）
+  buttons: [                            // 可选首屏 seed
+    { id: 'copy-json', title: 'Copy JSON', isEnabled: true },
+  ],
+};
+```
+
+**`shouldDisplay` 语义：** 宿主在 WebView 启动**之前**读取它。
+
+- `true` / 省略 — 正常进入渲染队列
+- `false` — 宿主跳过该 attachment，**不**分配卡片位、**不**启动 WebView
+
+典型用法：payload 解析失败时静默退出，避免 UI 报错：
+
+```ts
+async resolveAttachment(input, ctx) {
+  let parsed;
+  try {
+    parsed = JSON.parse(input.attachment.payloadJson);
+  } catch {
+    return { shouldDisplay: false };
+  }
+  if (!parsed.kind) return { shouldDisplay: false };
+  return {
+    displayName: parsed.title ?? 'Sample Card',
+    buttons: [{ id: 'copy-json', title: 'Copy JSON', isEnabled: true }],
+  };
+}
+```
+
+**按钮 seed 与 UI 覆盖：** `resolveAttachment.buttons` 是首屏 seed（供宿主在 WebView 启动前渲染 native chrome）。UI 一旦调用 `clipbus.attachmentRenderer.setButtons([...])`，列表被**整体替换**，seed 永远不再生效。**没有差分更新**——UI 每次推送完整列表。
+
+### Renderer UI 典型生命周期
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+const attachment = clipbus.item.attachment.current();
+if (attachment) {
+  const payload = JSON.parse(attachment.payloadJson);
+  renderInitial(payload);
+}
+
+const unsub = clipbus.item.attachment.on(newAttachment => {
+  renderInitial(JSON.parse(newAttachment.payloadJson));
+});
+
+// 启用自适应高度（manifest height: { min, max } 时必须调用）；
+// 实际像素由 UI 之后通过 clipbus.window.setHeight({ height }) 持续上报，
+// 或使用 @clipbus/plugin-sdk/dom 的 autoFit 辅助函数自动做 ResizeObserver。
+await clipbus.window.autoFit();
+
+// 按需更新按钮（覆盖 seed）
+await clipbus.attachmentRenderer.setButtons({
+  buttons: [
+    { id: 'copy-json', title: 'Copy JSON', isEnabled: true },
+    { id: 'copy-raw', title: 'Copy Raw', isEnabled: false },
+  ],
+});
+
+// 订阅宿主派发的按钮点击
+const unsubClick = clipbus.attachmentRenderer.onHostInvoke.on(({ buttonID }) => {
+  if (buttonID === 'copy-json') {
+    clipbus.clipboard.copyText({ text: JSON.stringify(payload, null, 2) });
+  }
+});
+```
+
+UI 端完整 topic/verb 列表见 [API.md](../API.md)。
+
+---
+
+## Action
+
+按 lifecycle 分叉为两种形态，runtime 入口不同：
+
+| lifecycle | runtime 入口 | UI 入口 |
+|---|---|---|
+| `auto-run` | `runAutoAction(input, ctx)` | 无 |
+| `draft` | `resolveSession(input, ctx)`（可选） | 必填 `uiEntry`；UI 自管表单状态，最终调 `clipbus.action.complete(...)` 提交 |
+
+### resolveSession 入参
+
+```ts
+input.item                    // PluginClipboardItem
+input.content                 // PluginContentEnvelope
+input.attachments             // PluginAttachmentRef[]
+```
+
+### resolveSession 返回值
+
+```ts
+return {
+  displayName: 'Apply Metadata',         // string | undefined
+  buttons: [                              // 可选首屏 seed
+    { id: 'apply', title: 'Apply', isEnabled: true },
+  ],
+  defaultButtonID: 'apply',               // string | undefined
+  initialDraft: { subject: '', note: '' } // Record<string, JSONValue>
+};
+```
+
+`initialDraft` 由宿主存入 draft topic，UI 可通过 `clipbus.action.draft.current()` 读到。`auto-run` lifecycle 可省略 `resolveSession`，宿主按空 session 处理。
+
+### runAutoAction 入参
+
+```ts
+input.item                    // PluginClipboardItem
+input.content                 // PluginContentEnvelope
+input.attachments             // PluginAttachmentRef[]
+```
+
+### runAutoAction 返回值（用 `actionResult`）
+
+```ts
+const { actionResult } = require('@clipbus/plugin-sdk/runtime');
+
+// text 结果
+actionResult.text('hello world', { userMessage: 'Copied' });
+// → { result: { resultKind: 'text', text: 'hello world' }, userMessage: 'Copied' }
+
+// image 结果（注意：第一个参数是 imageTempPath 字符串，不是对象）
+actionResult.image(imageTempPath, { imageFormatHint: 'png', userMessage: 'Saved' });
+
+// 仅副作用，无输出
+actionResult.none({ userMessage: 'Applied' });
+```
+
+签名：
+
+```ts
+actionResult.text(text: string, options?: { userMessage?: string })
+actionResult.image(imageTempPath: string, options?: { imageFormatHint?: string; userMessage?: string })
+actionResult.none(options?: { userMessage?: string })
+```
+
+### Draft Action UI 生命周期（强类型）
+
+Draft 是**只读 OptionalTopic**：UI 通过 `current()` / `on()` 读宿主的 `initialDraft`。**SDK 不暴露 `draft.update()`**——UI 自管表单本地状态，最终通过 `clipbus.action.complete(...)` 提交结果。如果 runtime 端需要参与（例如生成图片），通过 `clipbus.runtime.invoke(...)` 桥接（RPC 机制详见 [rpc.md](./rpc.md)）。
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+interface MyDraft { subject: string; note: string; }
+
+// 读 initialDraft 作为表单初始状态
+const initial = clipbus.action.draft.current() as MyDraft | undefined;
+const form = reactive({ subject: initial?.subject ?? '', note: initial?.note ?? '' });
+
+// 订阅 host 推送的后续更新（罕见；通常 initialDraft 之后就由 UI 接管）
+clipbus.action.draft.on(next => {
+  Object.assign(form, next);
+});
+
+// 订阅按钮点击
+clipbus.action.onHostInvoke.on(({ buttonID }) => {
+  if (buttonID === 'apply') handleApply();
+});
+
+// 按需推送按钮列表（启用/禁用通过完整列表的 isEnabled 表达）
+await clipbus.action.setButtons({
+  buttons: [
+    { id: 'apply', title: 'Apply', isEnabled: form.subject.length > 0 },
+    { id: 'cancel', title: 'Cancel', isEnabled: true },
+  ],
+});
+
+async function handleApply() {
+  await clipbus.action.complete({
+    result: { resultKind: 'text', text: form.subject },
+    userMessage: 'Applied',
+  });
+}
+```
+
+### Draft Action：UI 需要 runtime 协助时
+
+`clipbus.action.complete` 接收 `{result: {resultKind: 'text' | 'image' | 'none', …}}`。**image 结果的 `imageTempPath` 必须由 runtime 端通过 `host.action.allocateImageTempPath` 分配**（UI 端没有这个能力），所以图片类 draft 的典型流程是：
+
+```ts
+// shared/contracts.ts —— 两端共享类型契约
+import { defineMessage } from '@clipbus/plugin-sdk/runtime';  // 或 /ui，类型相同
+export const GenerateImage = defineMessage<{ prompt: string }, { imageTempPath: string }>('generate-image');
+
+// runtime/index.ts
+const { definePlugin, host } = require('@clipbus/plugin-sdk/runtime');
+const fs = require('node:fs/promises');
+const { GenerateImage } = require('../shared/contracts');
+
+module.exports = definePlugin({
+  messageHandlers: Object.fromEntries([
+    GenerateImage.handle(async (req, ctx) => {
+      const { path } = await ctx.host.action.allocateImageTempPath({ formatHint: 'png' });
+      await fs.writeFile(path, await generateImage(req.prompt));
+      return { imageTempPath: path };
+    }),
+  ]),
+});
+
+// UI 端
+import { defineMessage, clipbus } from '@clipbus/plugin-sdk/ui';
+const GenerateImage = defineMessage<{ prompt: string }, { imageTempPath: string }>('generate-image');
+
+async function handleApplyImage(prompt: string) {
+  const { imageTempPath } = await GenerateImage.invoke({ prompt }, { timeoutMs: 60_000 });
+  await clipbus.action.complete({
+    result: { resultKind: 'image', imageTempPath, imageFormatHint: 'png' },
+  });
+}
+```
+
+> **不要**尝试通过 `runtime.invoke` 把图片字节传回 UI。postMessage 经 base64 + JSON 双重序列化，几 MB 图片就会卡顿数百 ms。让 runtime 直接写文件、只把路径返回给 UI。
+
+RPC 机制（`defineMessage` / `messageHandlers`）的完整说明见 [rpc.md](./rpc.md)。入参结构（`PluginContentEnvelope`、`PluginClipboardItem`）详见 [item-context.md](./item-context.md)。