Clipbus 插件

插件让 Clipbus 对你复制的内容采取行动 — 检测内容、渲染富内联预览、添加快捷 action。它们基于开放的 @clipbus/plugin-sdk 构建，UI 为 web 页面（官方模板与示例基于 Vue 3）。

概览

Clipbus 插件是一个挂入剪贴板的小模块。每个插件最多可提供三种能力 — 按需实现即可，不必全部实现。

工作原理

每次复制时，Clipbus 会对内容运行已注册的 detector。识别到内容的 detector 返回一个或多个 artifact — 即类型化的数据载体，成为剪贴板 item 的 attachment。然后 renderer 为每个 attachment 绘制卡片，显示在 item 下方的附件面板中。

卡片可折叠：chip 标注类型，单行预览紧邻复制和展开控件，展开后显示完整结果。

Runtime 与 UI

一个插件横跨两个相互隔离的上下文。你的 Node 代码通过一次 definePlugin({ detectors, attachmentRenderers, actions, messageHandlers }) 调用注册，无界面运行；每个可见的界面都是 manifest 中以 uiEntry 声明的独立 HTML 页面。两侧不共享内存，通过桥接通信：UI 调用 clipbus.runtime.invoke()，runtime 用它的 messageHandlers 应答。

并非每种能力都需要两侧 —— 这正是关键区别：

Detector

Detector 将原始剪贴板输入转化为类型化的 artifact。它接收输入并返回一个数组 — 不匹配时返回空数组，因此多个 detector 可以共存。Detector 通常按优先级链依次尝试，命中即停。

// detect(input) -> artifact[]
export const decodeDetector = {
  async detect(input) {
    if (input.content.kind !== "text") return [];
    const { header, payload } = tryDecodeJwt(input.content.text);
    if (!header) return [];
    return [{
      attachmentType: "plugin.example.decode.preview",
      attachmentKey: input.item.id,
      payloadJson: JSON.stringify({ header, payload }),
    }];
  },
};

  // 不匹配 — 返回空数组；其他 detector 仍会继续运行
  return [];

Renderer

Renderer 负责处理一种 attachment 类型。其运行时侧 resolveAttachment 返回卡片的显示名称和预置按钮。其 UI 侧是 manifest 里声明的 uiEntry HTML，负责绘制卡片 — 官方模板使用 Vue 3。

export const decodeRenderer = {
  async resolveAttachment(input) {
    const payload = JSON.parse(input.attachment.payloadJson);
    return {
      displayName: "JWT",
      buttons: [{ id: "copy", label: "Copy" }],
    };
  },
};

每个 renderer 在 manifest 条目中设置 height — 固定数值（1–800）、"auto"（内容驱动，默认边界 80–800）、显式的 { min, max }，或省略（默认 80–400）。使用 "auto" 或 { min, max } 时，卡片 UI 需调用 clipbus.window.autoFit()，这是 SDK 提供的 DOM helper，它会观察内容尺寸并调用 window.setHeight。

Action

Action 按需对单条 item 执行操作。lifecycle: 'auto-run' 通过 runAutoAction 无 UI 运行；lifecycle: 'draft' 则打开由 resolveSession 驱动的 uiEntry 表单。开发期间可用 ?view=action 预览 draft 表单，与 renderer 使用 ?view=renderer 的方式相同。

Toolbox 插件

开源的 plugin.clipbus.toolbox（github.com/scubers/clipbus-toolbox-plugin）是一个完整的真实示例，展示了全部三种能力。

Detector + Renderer — 解码预览

decode-detector（supportedInputKinds: ["text"]）产出 plugin.clipbus.toolbox.decode.preview attachment。其 renderer 卡片使用 height: { min: 32, max: 480 }。Detector 按优先级链运行，命中即停：

折叠卡片显示类型 chip、单行预览、复制按钮和展开箭头。展开后显示完整解码内容（含 JSON 高亮）或时间详情 — 本地 / UTC / ISO / epoch — 使用 toolbox 自身的默认格式 yyyy-MM-dd HH:mm:ss。

Auto-run action — 大小写转换

六个 auto-run action 就地改写复制的文本：uppercase、lowercase、camelCase、pascalCase、snakeCase 和 kebabCase。均声明 supportedItemTypes: ["text"]。

Draft action — 图片编辑

Crop & Compress draft action（supportedItemTypes: ["image"]）打开 uiEntry 表单，供用户裁剪并重新压缩图片 item。

插件结构与 manifest

插件按功能拆分 — 每种能力位于独立文件夹。plugin.ts 是注册所有处理器的 definePlugin 入口。manifest.json 声明插件的身份、运行时配置与权限。

{
  "schemaVersion": 2,
  "plugin": {
    "id": "plugin.example.my-plugin",
    "title": "My Plugin",
    "version": "1.0.0"
  },
  "runtime": {
    "nodeEntry": "dist/plugin.js",
    "uiRoot": "dist/ui"
  },
  "install": "npm install --prefix . --ignore-scripts",
  "permissions": ["setTags", "setPinned", "setAttachment", "setSearchExtension"],
  "attachmentRenderers": [/* ... */],
  "detectors": [/* ... */],
  "actions": [/* ... */]
}

your-plugin/
├── manifest.json            # 插件 id、权限、install hook
├── package.json            # 依赖 @clipbus/plugin-sdk
├── src/
│   ├── features/<name>/
│   │   ├── payload.ts       # artifact / draft 类型
│   │   ├── detector.ts      # detect → artifact[]
│   │   ├── renderer.ts      # resolveAttachment
│   │   ├── action.ts        # runAutoAction / resolveSession
│   │   ├── app.vue          # 卡片 / 表单 UI
│   │   └── main.ts          # 或独立 UI 用 index.html
│   ├── shared/
│   ├── preview/
│   └── plugin.ts            # definePlugin — 注册所有处理器
└── tests/runtime/

快速开始

从 fork 官方模板开始：github.com/scubers/clipbus-template-plugin — 公开可 fork，与仓库内模板同源，最小化但覆盖全部扩展点（detector、紧凑 + 展开 renderer、auto-run action、draft action）。fork 后即得一个可直接投入开发的生产级骨架。

推荐 — 在模板上 vibe-coding。 模板自带完整文档 — 中英双语的 README / GUIDE 以及专为 AI 工具编写的 AGENTS.md — 并依赖 @clipbus/plugin-sdk，其 API.md / SPECIFICATION.md 为能力真相源。将这些随包文档指给 AI 助手，让它直接基于 fork 开发：上下文完整，无需翻阅 SDK 内部源码。

本地开发需要 Node.js ≥ 18。

npm install        # 拉取并编译 @clipbus/plugin-sdk
npm run dev        # Vite 预览工作台
#   ?view=renderer  → 预览 attachment 卡片
#   ?view=action    → 预览 draft action 表单
npm test           # 集成测试
npm run build      # 类型检查 + lint + 构建 → dist/

在应用内调试时，打开 Settings → Plugins → Developer Plugins，点击 Add Path 并指向包含 manifest.json 的目录。声明了 install 的插件会自动运行（cwd = 该目录）；日志写入 <AppData>/development-plugins/<id>/install-logs/，不污染 git 状态。使用 Reload 重新读取 manifest，Run Install 重新执行 install hook，View Logs 查看 install 失败时的日志。

API 参考（SDK）

作者可使用的所有内容均生成到 SDK 包中，始终与你安装的版本一致，不会与本页内容产生偏差。无需阅读 SDK 的内部源码。

• 文档索引 — node_modules/@clipbus/plugin-sdk/docs/README.md
• 能力真相源 — node_modules/@clipbus/plugin-sdk/API.md（生成；有冲突以此为准）
• 扩展能力 — SPECIFICATION.md，第 3 章
• npm — @clipbus/plugin-sdk · 通过 npm update @clipbus/plugin-sdk 更新

插件数量限制

免费版最多支持 3 个插件。Clipbus Pro 将上限提升至 无限制插件（同时包含云同步），为一次性买断。详见 定价页。