插件 SDK 上手

2026-11-15

插件 SDK 是插件与宿主之间的全部接口面:后台入口 blc-plugin-sdk、页面入口 blc-plugin-sdk/browser,以及清单 Schema。SDK 以公开 npm 包发布(npm install blc-plugin-sdk),类型定义以随包提供的 index.d.ts、browser.d.ts 为准。接口主版本为 1,按修订递进提供能力:修订 1 新增文档分块导出,修订 2 新增明暗模式、页面就绪与用户入口声明,修订 3 新增文稿导航。本篇覆盖上手与核心概念;字段级细节见「SDK 清单 Schema」、「SDK 后台 API」与「SDK 页面 API」。

两个入口

入口 运行位置 引入方式 能力边界
blc-plugin-sdk 插件后台(Node 22 独立进程) import { definePlugin } from 'blc-plugin-sdk' 完整的 Node 文件、网络、子进程能力
blc-plugin-sdk/browser 插件页面(浏览器渲染进程) import { connect } from 'blc-plugin-sdk/browser' 仅本页视图会话与 SDK 接口;禁止导入 Node 模块

页面也可以直接从页面所在目录的 ./__sdk.mjs 导入宿主桥接(同步 connect)。后台与页面分别桥接到宿主,不共享内存;两个入口共享下文的「共享 API」。SDK 还提供辅助函数:PluginError(带机器可读 code 的错误类型)、waitForTask(轮询等待任务完成,默认超时 30 秒、间隔 150 毫秒,取消与超时不重放任务)、readDocument(封装分块导出、边界检查、超时与 SHA-256 完整性校验)。

Invocation 与任务状态

每个命令与服务方法都收到 invocation:

字段 说明
signal AbortSignal;长任务应定期 signal.throwIfAborted(),协作式取消
invocationId 本次调用唯一 ID
taskId 关联的宿主任务 ID(命令调用才有)
progress(value, message?) 上报 0–1 进度与消息
source 调用来源
workspaceId / workspaceSession 工作区身份与会话标识;工作区切换后旧会话调用被拒(WORKSPACE_CHANGED)
windowId / editorId / documentId / revision / selection 菜单触发时携带的窗口、编辑器、文档、版本与选区身份
sessionId / resource 会话与资源身份

任务由宿主持有:页面或 AI 会话关闭不结束后台任务。任务状态:waiting、running、cancelling、completed、failed、cancelled、interrupted、uncertain。取消、退出与超时可能留下 uncertain 的外部执行结果(另一端可能已执行),不自动重试有副作用的操作。命令没有统一的总时限,心跳只检测事件循环是否响应;取消超时会结束同一实例中的其他任务。

核心类型速查

interface DocumentSnapshot extends DocumentTarget {
  content: string
  format: 'markdown' | 'tiptap'
  formatVersion?: 1
  revision: string
  draftHash: string
  dirty: boolean
}
interface DocumentExportChunk {
  exportId: string; format: 'markdown'; formatVersion: 1
  chunk: string; offset: number; nextOffset: number; totalBytes: number
  hash: string; revision: string; draftHash: string; dirty: boolean
}
interface DocumentChange extends DocumentTarget {
  operationId: string
  revision: string
  draftHash: string
  content: string
}
interface Operation {
  operationId: string
  state: 'pending' | 'completed' | 'failed' | 'uncertain'
  result?: Json
  error?: string
}
interface Task {
  id: string; pluginId: string; version: string; generation: string; command: string
  context: InvocationContext
  state: 'waiting' | 'running' | 'cancelling' | 'completed' | 'failed'
    | 'cancelled' | 'interrupted' | 'uncertain'
  progress: number; hasResult: boolean; result?: Json; error?: string; errorCode?: string
}
interface ViewOptions {
  location?: 'tab' | 'panel' | 'window'
  context?: InvocationContext
  state?: Json
  instanceId?: string
}
interface ViewSession {
  pluginId: string; viewId: string; instanceId: string; title: string; location: string
  context: InvocationContext
  state?: Json; dirty: boolean; connected: boolean
  theme?: Record<string, string>
  colorScheme: 'light' | 'dark'
  uiReady: boolean
  timings?: Record<string, number>
}

DocumentTarget 为 { workspaceId, workspaceSession, documentId, editorId, windowId? };DocumentNavigationTarget(修订 3)为 { workspaceId, workspaceSession, documentId };ResourceRequest 为 { workspaceId, workspaceSession, path?, query?, offset?, limit?, content?, expectedHash?, operationId? };Json 为 null、boolean、number、string、数组或普通对象的递归类型。

标准错误码

错误码 含义
API_MISMATCH 清单 apiVersion 与宿主不符
NODE_MISMATCH Node/npm 版本不满足要求
BACKPRESSURE 并发请求超限
STALE_GENERATION 旧代次实例的响应失效
WORKSPACE_CHANGED 工作区已切换
DRAFT_CONFLICT 文档快照过期或草稿冲突
RESOURCE_CHANGED 读取期间资源发生变化
MESSAGE_TOO_LARGE 响应超过控制帧上限
DIRTY_VIEW 页面有未保存修改(如拒绝关闭)
SAVE_TIMEOUT 保存确认超时
OPERATION_CONFLICT 操作冲突(如相同 operationId 不同参数)
NAVIGATION_CANCELLED / NAVIGATION_TIMEOUT 文稿导航被取消 / 超时

PluginError.code 是机器可读错误码;插件抛错时也请使用稳定的字符串码,便于外部 AI 与诊断面板定位。

运行限制与配额

项 上限
插件后台进程 16 个
插件页面 32 个
未完成命令任务 128 个
安装/开发准备任务 8 个,脚本串行排队、可取消
页面恢复状态 64 KiB
控制帧 1 MiB
命令单次结果 小于 1 MiB
文档导出快照 每插件 4 份、宿主合计 64 MiB、2 分钟过期
文档导出分块 96 KiB/块,总量 32 MiB
资源写入 700 KiB/次
文本读取 512 KiB/次,累计 16 MiB
图片读取 384 KiB/段,累计 28 MiB,每页 100 张
服务调用 20 秒、深度 8
插件日志 每插件 500 条 / 256 KiB
V8 堆 默认 256 MiB
进程树内存 / 整机 CPU 512 MiB / 25%

Windows 用 Job Object 硬配额;macOS/Linux 每秒采样,CPU 连续 10 次超限才停止——采样阈值不是所有平台的内存硬上限。后台异常退出按 2 秒、4 秒退避最多自动重启两次,仅重新激活,不重放命令、事件或外部操作;连续故障计数跨应用重启保留,达到上限后需用户明确启用或重启才重置。页面建议构建目标 ES2022、Chromium 109 / Safari 16.4 及等效 WebKit;最终支持平台以宿主原生 UI 验收为准。

按需查阅