@clipbus/plugin-sdk 0.7.0

package/docs/capability-detection.md

@@ -0,0 +1,105 @@
+# 能力检测 / Capability detection
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+---
+
+## 什么时候做能力检测
+
+**只对「可能晚于宿主出现的新能力」做门控**（如 `infoPanel.open`）。`clipbus.action.complete`、`clipbus.clipboard.copyText` 等 baseline 老能力直接调即可，无需门控。
+
+加门控的信号：能力在较新版宿主才引入，插件需在老宿主上也能降级运行。
+
+---
+
+## UI 侧（WebView）
+
+### 调用前门控
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+// has() 接受类型化的 capability 名称（CapabilityMethodName）
+if (clipbus.capabilities.has('infoPanel.open')) {
+  await clipbus.infoPanel.open({ document: { … } });
+} else {
+  // 降级：隐藏按钮或显示提示
+}
+```
+
+老宿主未注入能力清单时，`has()` 恒返回 `false`，安全降级。
+
+### 调用兜底（catch）
+
+若需要在调用处做二次防御（例如按钮在渲染后宿主降级），UI 侧可用 `instanceof`——错误在插件 bundle 内由 `parseReplyError` 构造（未跨 realm），且每个 UI bundle 只打包一份 SDK，故 `instanceof` 可靠：
+
+```ts
+import { clipbus, CapabilityUnsupportedError } from '@clipbus/plugin-sdk/ui';
+
+try {
+  await clipbus.infoPanel.open({ document: { … } });
+} catch (err) {
+  if (err instanceof CapabilityUnsupportedError) {
+    // err.capability 包含不支持的 capability 名称
+    console.warn('infoPanel not supported:', err.capability);
+    return;
+  }
+  throw err;
+}
+```
+
+---
+
+## Node runtime 侧
+
+### 调用前门控
+
+```ts
+import type { PluginActionHandler } from '@clipbus/plugin-sdk/runtime';
+
+const action: PluginActionHandler = {
+  async runAutoAction(input, ctx) {
+    if (ctx.host.capabilities.has('item.setTags')) {
+      await ctx.host.item.setTags({ itemID: input.item.id, tags: ['processed'] });
+    }
+    // 不支持时跳过，不报错
+  },
+};
+```
+
+### 调用兜底（catch）
+
+Node 侧错误来自**跨进程 IPC**，抛出的是反序列化的普通对象，**不是 SDK 的类实例**——`instanceof CapabilityUnsupportedError` 在这里不可靠。改用结构化判断：
+
+```ts
+try {
+  await ctx.host.item.setTags({ itemID: input.item.id, tags: ['processed'] });
+} catch (err: unknown) {
+  const e = err as { name?: string; data?: { capability?: string } };
+  if (e.name === 'PluginCapabilityUnsupported') {
+    // e.data?.capability 包含不支持的能力名
+    return;
+  }
+  throw err;
+}
+```
+
+> **UI / Node 差异总结：**
+> - UI 侧：用 `instanceof CapabilityUnsupportedError`（SDK 保证同一类实例）
+> - Node 侧：用 `err.name === 'PluginCapabilityUnsupported'` + `err.data?.capability`（跨进程，不能用 instanceof）
+
+---
+
+## 老宿主行为
+
+宿主未注入能力清单（老版本）→ `has()` 恒返回 `false` → 门控分支跳过 → 安全降级，无需额外处理。
+
+---
+
+## 完整示例
+
+模板插件的 `capability-gallery` feature 演示了完整的门控写法：
+
+- **门控渲染**：`plugins/template-plugin/src/features/capability-gallery/draft-action-ui/app.vue`
+  — `infoPanelSupported = clipbus.capabilities.has('infoPanel.open')`，控制 infoPanel 按钮的 v-if
+- **调用兜底**：同文件 `openInfoPanel()` 函数中的 `catch (err instanceof CapabilityUnsupportedError)` 分支

package/docs/concepts.md

@@ -0,0 +1,80 @@
+# 架构
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+## 两个执行上下文
+
+一个 v2 插件运行在两个完全隔离的环境：
+
+| 环境 | 入口 | 负责 |
+|---|---|---|
+| **Node runtime** | `manifest.runtime.nodeEntry` | detector、`resolveAttachment`、`resolveSession`、`runAutoAction`、`messageHandlers` |
+| **WebView UI** | `manifest.<thing>.uiEntry` HTML | 卡片/表单渲染、用户交互、最终结果提交 |
+
+两边通过 SDK 暴露的高阶 API 通信：
+
+- Runtime 侧用 `host.*`（来自 `@clipbus/plugin-sdk/runtime`）调宿主能力
+- UI 侧用 `clipbus.*`（来自 `@clipbus/plugin-sdk/ui`）调宿主能力
+- UI ↔ Runtime 之间用 `clipbus.runtime.invoke` ↔ `messageHandlers` 桥接
+
+宿主与插件之间的传输层（postMessage / Node IPC / 宿主事件 envelope）由 SDK 完全封装，**插件作者不需要关心**底层 wire 形状。
+
+## 三类产物
+
+| 产物 | 在哪运行 | runtime 入口 | UI 入口 |
+|---|---|---|---|
+| **detector** | 仅 Node runtime | `detect(input, ctx)` | — |
+| **attachment renderer** | Node runtime + WebView | `resolveAttachment(input, ctx)` | `manifest.attachmentRenderers[].uiEntry` |
+| **action（auto-run）** | 仅 Node runtime | `runAutoAction(input, ctx)` | — |
+| **action（draft）** | Node runtime + WebView | `resolveSession(input, ctx)`（可选） | `manifest.actions[].uiEntry` |
+
+> 历史上的 `invokeOperation` 入口已被**完全移除**。`definePlugin` 在 setup 阶段就会拦截带 `invokeOperation` 的 handler 并抛错。所有按钮副作用与 draft 提交都通过 UI verb 完成。
+
+## 数据流总图
+
+```
+┌─────────────────────────────────────┐
+│           Clipbus Host                │
+└───────────┬─────────────┬───────────┘
+            │             │
+   ┌────────▼─────────┐  ┌▼─────────────────────────┐
+   │  Node Runtime    │  │     WebView UI            │
+   │                  │  │                           │
+   │  definePlugin()  │  │  import { clipbus }         │
+   │   detect         │  │    from '@clipbus/plugin-   │
+   │   resolveAttach… │  │           sdk/ui'         │
+   │   resolveSession │  │                           │
+   │   runAutoAction  │  │  clipbus.item.current()     │
+   │   messageHandlers│  │  clipbus.action.*           │
+   │                  │  │  clipbus.attachmentRenderer.│
+   │  host.item.*     │  │  clipbus.runtime.invoke()   │
+   │  host.clipboard. │  │  …                        │
+   │  host.action.*   │  │                           │
+   │  …               │  │                           │
+   └────────▲─────────┘  └───────────────────────────┘
+            │                          │
+            └──────────────────────────┘
+              clipbus.runtime.invoke
+              ↔ messageHandlers
+```
+
+**Host → Plugin（推送）：**
+- 宿主调 Node runtime 的 handler：`detect` / `resolveAttachment` / `resolveSession` / `runAutoAction`
+- 宿主向 WebView 推送 topic 状态：UI 用 `clipbus.<domain>.on(fn)` 订阅
+- 宿主派发按钮点击：UI 用 `clipbus.action.onHostInvoke(fn)` / `clipbus.attachmentRenderer.onHostInvoke(fn)` 订阅
+
+**Plugin → Host（请求）：**
+- Runtime 用 `host.*` 调宿主（Node IPC，真 RPC，返回 `Promise<Result>`）
+- UI 用 `clipbus.*` verb 调宿主（WebView postMessage，同样是 `Promise<Result>`）
+
+## Host → WebView 状态形状
+
+UI 侧拿到的所有宿主状态遵守三种形状之一（capability 完整签名见 [API.md](../API.md)）：
+
+| 形状 | 接口 | 适用 | 举例 |
+|---|---|---|---|
+| **Topic\<T\>** | `.current(): T \| undefined` + `.on(fn)` | 有快照的持续状态 | `clipbus.item`、`clipbus.theme` |
+| **OptionalTopic\<T\>** | 同上，但 `.current()` 可能 `undefined` | 上下文相关的状态 | `clipbus.item.attachment`、`clipbus.action.draft` |
+| **Stream\<T\>** | `.on(fn)` only | 离散事件流 | `clipbus.attachmentRenderer.onHostInvoke`、`clipbus.action.onHostInvoke` |
+
+> **重要：SDK 没有 `clipbus.ready()`**。监听器可以在模块加载时立即注册——宿主会在 bootstrap 推送时唤起它们。`.current()` 在 bootstrap 之前可能返回 `undefined`，用 `?.` / `??` / 早返回防御即可。

package/docs/entry.md

@@ -0,0 +1,137 @@
+# SDK 入口与初始化
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+SDK 暴露两个 subpath。每个入口导出的符号**完全由 codegen 生成**，精确签名见 [API.md](../API.md)。
+
+## Runtime 入口
+
+```ts
+// CommonJS（推荐与现行 bundler 配合）
+const { definePlugin, host, actionResult, defineMessage } = require('@clipbus/plugin-sdk/runtime');
+
+// ESM（types）
+import type { PluginAttachmentRendererHandler, PluginAutoRunActionHandler, PluginDetectorHandler } from '@clipbus/plugin-sdk/runtime';
+```
+
+入口导出：
+
+- `definePlugin` —— 注册 handler；本地校验 registry 形状
+- `host` —— 直接调宿主能力的单例（`host.<domain>.<verb>(payload)`）。**推荐写法**是从 handler 收到的 `ctx.host` 调用（同一个对象，但写在 handler 内更显式）。
+- `actionResult` —— `runAutoAction` 的返回值构造器
+- `defineMessage` —— UI ↔ Runtime RPC 的类型契约
+
+## UI 入口
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+import { defineMessage } from '@clipbus/plugin-sdk/ui';
+import { PluginContextError } from '@clipbus/plugin-sdk/ui';
+```
+
+`clipbus` 的命名空间一览：
+
+| Namespace | 形态 | 说明 |
+|---|---|---|
+| `clipbus.item` | Topic | `current()`, `on()`, `readAttachment()`，子 OptionalTopic `clipbus.item.attachment` |
+| `clipbus.asset` | Verb | `currentItemImageUrl()`、`pathReferenceImageUrl({index})` —— 按身份取本地图片的 `clipbus-asset://` URL 供 WebView `<img>` 渲染（真实路径不出宿主）；Node 产图经 `host.asset.registerImage({path})` |
+| `clipbus.theme` | Topic | `current()`, `on()` |
+| `clipbus.pluginContext` | Topic | `current()`, `on()`，返回 `{mode, pluginID}` |
+| `clipbus.action` | Verb + OptionalTopic | action 上下文专属；`setButtons`、`complete`、`draft`、`onHostInvoke` |
+| `clipbus.attachmentRenderer` | Verb + Stream | attachment 上下文专属；`setButtons`、`onHostInvoke` |
+| `clipbus.window` | Verb | `setHeight`, `autoFit` |
+| `clipbus.clipboard` | Verb | `copyText` |
+| `clipbus.navigation` | Verb | `openUrl`, `revealInFinder`, `openFilePath` |
+| `clipbus.settings` | Verb | `get`, `getAll` |
+| `clipbus.console` | Verb | `log({level, message})` |
+| `clipbus.textInput` | Verb | `stateChanged({isFocused, isComposing})` |
+| `clipbus.runtime` | Verb | `invoke<TResp>({key, payload, timeoutMs?})` |
+
+每个方法的精确 payload / response 形状以 [API.md](../API.md) 为准。
+
+## 没有 `clipbus.ready()`
+
+SDK **不**导出 `clipbus.ready()`。订阅者（`clipbus.<domain>.on(fn)`）可在模块加载时立即注册——监听是 context-neutral 的，宿主推送 bootstrap 时会自动触发回调。
+
+如果需要在初始数据到达后做同步动作，常见模式是：
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+const item = clipbus.item.current(); // bootstrap 已到时直接拿到
+if (item) {
+  init(item);
+} else {
+  const unsub = clipbus.item.on(initialItem => {
+    init(initialItem);
+    unsub();
+  });
+}
+```
+
+## Context guards
+
+部分 verb 只在特定 WebView 上下文有意义，在错误上下文调用会以 `PluginContextError` reject：
+
+| Verb | 必须的上下文 |
+|---|---|
+| `clipbus.action.complete(...)` | action |
+| `clipbus.action.setButtons(...)` | action |
+| `clipbus.attachmentRenderer.setButtons(...)` | attachmentRenderer |
+
+捕获方式：
+
+```ts
+import { PluginContextError } from '@clipbus/plugin-sdk/ui';
+
+try {
+  await clipbus.action.complete({ result: { resultKind: 'none' } });
+} catch (e) {
+  if ((e as Error).name === 'PluginContextError') {
+    // 当前 WebView 不是 action 上下文
+  }
+}
+```
+
+订阅类 verb（`clipbus.action.draft.on`、`clipbus.attachmentRenderer.onHostInvoke.on` 等）是 context-neutral 的：在错误上下文订阅不会抛错，监听器只是永远不会被触发。
+
+## `definePlugin`
+
+```ts
+const { definePlugin } = require('@clipbus/plugin-sdk/runtime');
+
+module.exports = definePlugin({
+  attachmentRenderers: {
+    'sample-card': createSampleRenderer(),
+  },
+  detectors: {
+    'sample-detector': createSampleDetector(),
+  },
+  actions: {
+    'sample-apply': createSampleAction(),
+  },
+  messageHandlers: {
+    'sample.applyMetadata': async (req, ctx) => {
+      await ctx.host.item.setTags({ tags: req.tags });
+      return { ok: true };
+    },
+  },
+});
+```
+
+注册项的 key **必须**与 `manifest.json` 中对应 `id` 完全一致，否则宿主无法寻址。manifest 结构详见 [manifest.md](./manifest.md)。
+
+`definePlugin` 同时接受 setup 函数形式：
+
+```ts
+module.exports = definePlugin({
+  setup() {
+    return { attachmentRenderers, detectors, actions, messageHandlers };
+  },
+});
+```
+
+校验规则（在 setup 阶段 throw）：
+
+- renderer / action 注册项若包含 `invokeOperation` 立刻抛错（该入口已删除）
+- 其他 registry 形状由 TypeScript 在编译期约束

package/docs/faq.md

@@ -0,0 +1,65 @@
+# 常见坑点 Q&A
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+---
+
+**Q：监听器要等 `clipbus.ready()` 才能注册吗？**
+
+A：不要。**SDK 没有 `clipbus.ready()`**。监听器在模块加载时就注册——宿主 bootstrap 推送到达时会自动触发。同步读快照用 `.current()`，可能返回 `undefined`，用 `?.` / `??` 防御即可。
+
+**Q：`clipbus.action.draft.update` 在哪？**
+
+A：**不存在**。Draft 是只读 OptionalTopic：UI 通过 `current()` / `on()` 读 `initialDraft`，之后自管表单本地状态，最终通过 `clipbus.action.complete(...)` 提交。这是 plugin-api-shrink 的主动设计——宿主不需要知道每次按键。
+
+**Q：`clipbus.theme.refresh()` / `clipbus.theme.getThemeSnapshot()` 在哪？**
+
+A：**不存在**。`clipbus.theme` 只有 `current()` 和 `on(fn)`。宿主在 WebView 启动时通过 `__CLIPBUS_PLUGIN_THEME__` window global 注入快照，并通过 `clipbus-plugin-theme` host event 推送更新，SDK 自动维护 Topic。
+
+**Q：旧版的 `clipbus.action.allocateImageTempPath` 还在吗？**
+
+A：**已从 UI 端移除**。临时路径只能由 runtime 端通过 `host.action.allocateImageTempPath({formatHint?})` 申请，再由 runtime 写文件。如果 UI 需要触发，按 [authoring.md](./authoring.md) 中的 draft action 模式：UI 调 `clipbus.runtime.invoke(...)` → 自己的 `messageHandlers` → 在 runtime 里申请路径 + 写文件 + 把路径返回给 UI → UI 用 `clipbus.action.complete({result: {resultKind: 'image', imageTempPath}})` 提交。
+
+**Q：旧版的 `ctx.host.capabilities.setTags` 检查在哪？**
+
+A：**已移除**。如果调用未授权的 verb，宿主侧 reject，错误会通过 `host.item.setTags(...)` 的 Promise 抛回来。在调用点 `try/catch` 即可。如果需要在执行前做条件分支，直接看 `manifest.json` 的 `permissions` 数组——它就是真相源。详见 [permissions.md](./permissions.md)。
+
+**Q：`actionResult.image` 的参数形状到底是什么？**
+
+A：第一个参数是 **`imageTempPath: string`**（不是对象）。选项里用 `imageFormatHint`：
+
+```ts
+actionResult.image(tempPath, { imageFormatHint: 'png', userMessage: 'Saved' });
+```
+
+**Q：`actionResult.none()` 返回值还有 `text: null` 吗？**
+
+A：没有。当前实现：`{ result: { resultKind: 'none' }, userMessage }`。
+
+**Q：detector 返回值是数组还是对象？**
+
+A：**数组**：`Promise<PluginDetectorArtifact[]>`。直接 `return [artifact1, artifact2]`，不要 `return { artifacts: [...] }`。未命中返回 `[]`。
+
+**Q：detector 也能调 `materializeImagePath` 吗？**
+
+A：可以。但 detector 的超时较短（3 秒级），大图拷贝可能超时，请酌情使用。
+
+**Q：`input.content.payload.text` 还存在吗？**
+
+A：不存在。`content` 的字段**平铺**在顶层：`content.text`（text）/`content.{width,height,format,bytes}`（image）/`content.entries`（path_reference）。
+
+**Q：`PluginPathEntry` 还存在吗？**
+
+A：是。`{kind: 'file' | 'folder', path: string, displayName: string}`，导出自生成的 `data.generated.ts`。被废弃的是无前缀的便利别名 `PathEntry`。
+
+**Q：临时目录什么时候清理？**
+
+A：invocation 结束后宿主同步删除。宿主启动时还会扫描 1 小时以上的遗留目录兜底清理。
+
+**Q：handler key 拼错了会怎样？**
+
+A：宿主无法寻址该 capability，调用静默失败或宿主侧报"未注册"。务必保证 `manifest.json` 的 `id` 与 `definePlugin({...})` 中 registry 的 key **完全一致**。详见 [manifest.md](./manifest.md)。
+
+**Q：怎么给 capability/host event 加新能力？**
+
+A：见 SDK 包内 [SPECIFICATION.md](../SPECIFICATION.md) 第 3 章。简而言之：改 `protocol/plugin/src/catalog.ts` → 跑 `npm run codegen` → 在宿主端实现新方法 → 添测试。SDK 表面由 codegen 自动暴露。

package/docs/item-context.md

@@ -0,0 +1,186 @@
+# 入参形状（ItemContext envelope）
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
+
+每个 handler 的 `input` 都遵守 **ItemContext envelope**：
+
+```ts
+interface ItemContext {
+  item: PluginClipboardItem;
+  content: PluginContentEnvelope;
+  attachments: PluginAttachmentRef[];
+}
+```
+
+各 handler 在此之上附加专属字段，详见 [entry.md](./entry.md)。
+
+## `PluginContentEnvelope`：三种 kind，字段平铺在顶层
+
+### 字段结构
+
+**关键：字段直接挂在 `content` 上，没有 `.payload.` 间接层。**
+
+| kind | 字段 |
+|---|---|
+| `'text'` | `content.text: string` |
+| `'image'` | `content.width: number`, `content.height: number`, `content.format: string`, `content.bytes: number` |
+| `'path_reference'` | `content.entries: PluginPathEntry[]` |
+
+```ts
+switch (input.content.kind) {
+  case 'text':
+    console.log(input.content.text);
+    break;
+  case 'image':
+    console.log(`${input.content.width}x${input.content.height} ${input.content.format}`);
+    // input.content 不含像素数据，需要时调 host.item.materializeImagePath（见下方「图片懒副本机制」）
+    break;
+  case 'path_reference':
+    for (const entry of input.content.entries) {
+      console.log(entry.kind, entry.path, entry.displayName);
+    }
+    break;
+}
+```
+
+`PluginPathEntry` 形状：
+
+```ts
+interface PluginPathEntry {
+  kind: 'file' | 'folder';
+  path: string;
+  displayName: string;
+}
+```
+
+## `PluginClipboardItem`
+
+```ts
+interface PluginClipboardItem {
+  id: string;
+  type: string;          // 'text' | 'image' | 'path_reference'
+  tags: string[];
+  sourceAppID: string;
+}
+```
+
+> **历史变更：** 旧版 SDK 在 `item` 上有 `text`。新版**已移除**——文本走 `input.content.text`（且仅在 `kind === 'text'` 时存在）。
+
+## 图片懒副本机制
+
+`input.content`（image 情形）只携带元信息，不带像素。当 detector / action 需要读字节时：
+
+```ts
+const { path } = await ctx.host.item.materializeImagePath();
+// path 是宿主复制到临时目录的副本，invocation 结束后宿主自动清理。
+```
+
+同一 invocation 多次调用幂等返回同一路径。
+
+## Attachment 按需读
+
+```ts
+const { payloadJson } = await ctx.host.item.readAttachment({
+  attachmentType: 'plugin.example.sample.card',
+  attachmentKey: 'card-1',
+});
+if (payloadJson) {
+  const payload = JSON.parse(payloadJson);
+}
+```
+
+`input.attachments` 给出当前 item 已有的附件引用列表（`{attachmentType, attachmentKey}`）。`readAttachment` 按需拉取真正内容，避免把所有附件塞进入参。
+
+## Action 返回图片
+
+字节写入由 **runtime 端**完成，**不要**让 UI 写文件。两种推荐写法：
+
+**A. Auto-run action — runtime 一气呵成：**
+
+```ts
+const { definePlugin, actionResult } = require('@clipbus/plugin-sdk/runtime');
+const fs = require('node:fs/promises');
+
+module.exports = definePlugin({
+  actions: {
+    'generate-image': {
+      async runAutoAction(input, ctx) {
+        const { path } = await ctx.host.action.allocateImageTempPath({ formatHint: 'png' });
+        await fs.writeFile(path, await generateImageBytes(input));
+        return actionResult.image(path, { imageFormatHint: 'png' });
+      },
+    },
+  },
+});
+```
+
+**B. Draft action — UI 触发 runtime 产文件，再由 UI 调 `complete`：** 见 [entry.md](./entry.md) 中的 draft action 示例。
+
+## 在 WebView 中展示本地图片（`clipbus-asset://`）
+
+上方「图片懒副本机制」和「Action 返回图片」讲的是 **runtime 侧**读写图片字节、产出图片**结果**。如果你要在 renderer 卡片或 draft action 表单里**把一张本地图片显示出来**（`<img>`），用 `clipbus.asset.*`。
+
+WebView 沙箱禁止 `file://`，且 SDK **从不**把真实文件路径暴露给 JS。`clipbus.asset.*` 返回一个 `clipbus-asset://` URL——一个会话级、不透明的 token，直接塞进 `<img src>` 即可渲染，宿主在内部把 token 解析回真实文件。
+
+| 能力 | 侧 | 入参 | 返回 | 用途 |
+|---|---|---|---|---|
+| `clipbus.asset.currentItemImageUrl()` | UI | `{}` | `{ url?: string }` | 当前 item **自身**的图（item 非 image kind → `url` 缺失） |
+| `clipbus.asset.pathReferenceImageUrl({ index })` | UI | `{ index }` | `{ url?: string }` | 当前 item 第 `index` 个 `path_reference` 条目的图（越界 / 非图片文件 → `url` 缺失） |
+| `host.asset.registerImage({ path })` | runtime | `{ path }` | `{ url: string }` | 把 **Node 产出 / 已有**的本地图注册进当前 session，签发 URL |
+
+capability 完整签名见 [API.md](../API.md)。
+
+> `currentItemImageUrl` / `pathReferenceImageUrl` 按**身份**取图（当前 item、`path_reference` 下标），UI 不需要、也拿不到真实路径。任意路径 / 动态生成的图**只能**在 runtime 侧经 `host.asset.registerImage` 签发——这样即使 WebView 被 XSS，也无法把任意文件变成可渲染 URL。
+
+**A. 展示当前 item 的图（纯 UI）：**
+
+```vue
+<template>
+  <img v-if="url" :src="url" alt="current image" />
+  <p v-else>not an image item</p>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+const url = ref<string | null>(null);
+onMounted(async () => {
+  const { url: u } = await clipbus.asset.currentItemImageUrl();
+  url.value = u ?? null;        // 非图片 item 时 u 为 undefined
+});
+</script>
+```
+
+`path_reference` 条目同理，换成 `clipbus.asset.pathReferenceImageUrl({ index })`。
+
+**B. 展示 Node 产出的图（runtime 产图 → UI 渲染）：**
+
+图片字节由 **runtime 侧**生成或读取（不要把字节经 postMessage 回传），注册后只把 URL 经 RPC 交给 UI。RPC 消息定义模式详见 [rpc.md](./rpc.md)：
+
+```ts
+// shared/contracts.ts
+import { defineMessage } from '@clipbus/plugin-sdk/runtime';  // 或 /ui，类型相同
+export const GenerateImage = defineMessage<Record<string, never>, { url: string }>('generate-image');
+
+// runtime —— 生成 / 拿到一个本地文件后注册，拿回 clipbus-asset:// URL
+const { definePlugin } = require('@clipbus/plugin-sdk/runtime');
+const { GenerateImage } = require('../shared/contracts');
+module.exports = definePlugin({
+  messageHandlers: Object.fromEntries([
+    GenerateImage.handle(async (_req, ctx) => {
+      const tmpPath = await writeSomePng();                 // 你的产图逻辑，写到临时文件
+      const { url } = await ctx.host.asset.registerImage({ path: tmpPath });
+      return { url };                                       // 只回传 URL，不回传字节
+    }),
+  ]),
+});
+
+// UI —— 调 runtime 拿 URL，直接渲染
+import { GenerateImage } from '../shared/contracts';
+const { url } = await GenerateImage.invoke({});
+imageUrl.value = url;   // <img :src="imageUrl">
+```
+
+> **token 生命周期：** URL 绑定当前 session owner，invocation / WebView 释放时一并失效，且跨 owner 隔离——不要持久化或跨会话复用。
+> **何时用哪个：** 显示「当前剪贴板项的图」用 `currentItemImageUrl`；显示「`path_reference` 里的某张图」用 `pathReferenceImageUrl`；显示「插件自己算出来 / 从别处读来的图」用 runtime `registerImage`。