插件 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 验收为准。
按需查阅
- 清单字段与贡献点:「SDK 清单 Schema」;
- 后台上下文、文档与资源、服务与定时任务:「SDK 后台 API」;
- 页面桥接、恢复状态、保存契约与文稿导航:「SDK 页面 API」。