SDK 后台 API
2026-11-15
本篇是插件后台(Node 进程)的 API 参考:上下文对象、文档与资源读写、服务与定时任务。概念与任务模型见「插件 SDK 上手」。
后台上下文 PluginContext
definePlugin(activate) 的 activate 接收上下文,可同步或异步返回清理函数,停用时执行:
export default definePlugin((context: PluginContext) => {
// 激活期注册清单声明的全部命令与服务
return async () => {
// 释放自己创建的连接、监听器等
}
})
| 属性 | 类型 | 说明 |
|---|---|---|
| apiVersion | 1 | 接口主版本 |
| apiRevision | number | 宿主支持的 API 修订号 |
| pluginId | string | 安装期分配的插件身份 |
| generation | string | 激活代次;故障重启后变化,旧代次的响应失效(STALE_GENERATION) |
| dataDir | string | 插件私有数据目录;更新前宿主会备份 |
commands
| 方法 | 签名 | 说明 |
|---|---|---|
| register | register(id, handler) | 注册命令,handler 收到 (args, invocation)。必须在激活时一次注册齐,与清单 contributes.commands 一致 |
命令返回值成为宿主持有任务的结果,单次结果须小于 1 MiB;大稿件与图片由插件自行分段传输。任务的生命周期与状态见下文「Invocation 与任务状态」。
services
| 方法 | 签名 | 说明 |
|---|---|---|
| provide | provide(id, methods) | 提供服务;methods 的键即清单 methods 声明的方法名,值为 (args, invocation) 的处理函数 |
| call | call(plugin, service, method, args, invocation?) | 调用其他插件的服务;传入 invocation 可传播调用链 |
| list | list() | 列出当前可用服务 |
服务调用限时 20 秒、调用深度 8,环路直接返回错误。通用导出契约 export.text v1:服务方法 transform({text, format: 'markdown', filename}, invocation) 返回 {text};用户在插件中心选择提供者后才使用,提供者故障时导出报错,不静默换回内置实现。
events
| 方法 | 签名 | 说明 |
|---|---|---|
| on | on(name, handler) | 订阅事件;handler 收到 (event, {signal}),event 含 id、name、workspaceId、payload |
| emit | emit(name, payload) | 发事件,自动加插件命名空间,实际名为 plugin:包名:事件名 |
可订阅的内置事件:startup、workspace.opened、document.committed,以及其他插件发出的 plugin:包名:事件名。工作区恢复也会发送打开事件;document.committed 只覆盖接入的提交路径,不是所有文件修改的广播。事件队列满时丢弃并记录事件 ID;事件通知不保证送达,消费者需要重读领域状态,业务检查点用 storage 自存。
credentials
| 方法 | 签名 | 说明 |
|---|---|---|
| get | get(key) | 读取凭据,返回 string 或 null |
| set | set(key, value) | 写入凭据 |
| delete | delete(key) | 删除凭据 |
凭据只存后台进程:Windows 用当前用户绑定的 DPAPI,macOS 用登录 Keychain,Linux 用系统凭据服务(Secret Service)。凭据不能进入清单、源码或页面恢复状态。
共享 API(后台与页面同名同义)
| 命名空间 | 方法 | 说明 |
|---|---|---|
| documents | snapshot(target) / export(request) / apply(change) / operation(operationId) | 核心文档读写;export 提供不可变 Markdown 快照的分块读取,见「文档操作」 |
| workspace | list() / resources(req) / read(req) / search(req) / import(req) | 工作区与资源文件,见「资源与图片」 |
| images | list(req) / read(req) | 图片库分页与分段读取,见「资源与图片」 |
| storage | get(key, workspaceId?) / set(key, value, workspaceId?) | 插件 KV 存储,值是 JSON;带 workspaceId 与不带是两个命名空间 |
| views | open(view, options?) | 打开页面返回 ViewSession;后台另有 close(instanceId),拒绝关闭脏页面 |
| ui | notify(message) / openFile(options?) / saveFile(options?) / openExternal(url) / openDocument(target) | 系统通知;文件打开/保存对话框返回所选路径;openExternal 只接受 HTTP(S),在系统默认浏览器打开;openDocument(修订 3)在主窗口定位并打开指定文稿 |
仅后台上下文另有 ai.run({conversationId, text}):向既有 AI 会话发送消息并返回 JSON 结果。
文档操作(documents)
核心文档(章节正文等)走乐观并发三步:先 snapshot,再携带 revision、draftHash 与唯一 operationId 调用 apply:
const snap = await ctx.documents.snapshot({
workspaceId, workspaceSession, documentId, editorId, windowId,
})
const op = await ctx.documents.apply({
workspaceId, workspaceSession, documentId, editorId, windowId,
operationId: crypto.randomUUID(),
revision: snap.revision,
draftHash: snap.draftHash,
content: nextText,
})
- 相同 operationId 与相同规范化参数返回原记录,不重复提交;不同参数被拒绝(
OPERATION_CONFLICT); - 文档、标签、工作区、草稿或持久化版本改变会产生可见冲突;其他脏编辑器、外部修改或标签切换也会;
- 变更经目标编辑器事务与现有保存流程提交,保留该编辑器已有的撤销能力;不承诺任意跨文件副作用可撤销;
- apply 超时后先
documents.operation(operationId)查询确认结果,不要重复提交;崩溃后的未确认操作变为uncertain; - 操作回执在当前日志目录最多保留 10000 份,到上限拒绝新操作;
- Node 直接文件写入绕过这些保证,需自行处理并发语义。
发布、阅读与导出场景优先用分块导出(修订 1):documents.export 创建不可变 Markdown v1 快照,按 UTF-8 字节偏移分块返回(每块至多 96 KiB,总量至多 32 MiB),带 SHA-256 校验;每插件最多 4 份未完成快照、宿主合计 64 MiB,最后一块读取后释放,未完成快照两分钟过期。辅助函数 readDocument(documents, target, options) 封装分块循环与完整性校验,返回完整 {content, hash, revision, draftHash, dirty}:
import { readDocument } from 'blc-plugin-sdk'
const doc = await readDocument(ctx.documents, target, { timeoutMs: 30000, signal })
// doc.content 是 Markdown v1,不需要插件理解宿主 Tiptap 节点
后打开页面可能卸载源编辑器,所以先 readDocument 捕获稿件,再 views.open 打开页面;不能依赖打开页面后原 editorId 仍可用。
资源与图片(workspace 与 images)
| 方法 | 说明 |
|---|---|
| workspace.list() | 列出可用工作区(WorkspaceRecord:id、rootPath、title、createdAt、lastOpenedAt) |
| workspace.read(req) | 读 UTF-8 文本文件,返回内容与 hash(供 import 的 expectedHash 使用);单次至多 512 KiB,文本文件累计至多 16 MiB |
| workspace.resources(req) | 按路径列资源,返回 ResourceEntry 列表(字段为已发布的 API 1 大小写:Rel、Parent、Name、Title、Kind、Editable、Ext、IsDir、Size、ModTimeUnix、Hash 等) |
| workspace.search(req) | 按关键词检索资源 |
| workspace.import(req) | 写 UTF-8 文本:带 expectedHash 是条件覆盖(哈希不匹配报错),不带则创建新文件、不能覆盖已存在文件;单次限 700 KiB,operationId 必填 |
| images.list(req) | 图片分页,每页至多 100 张,返回 {items: {id, name, src, width, height}, total} |
| images.read(req) | 图片转 data URL 分段返回(按 src 定位),每段至多 384 KiB、总量至多 28 MiB;把首段返回的 hash 传入后续读取,图片变化返回 RESOURCE_CHANGED |
ResourceEntry.ModTimeUnix 是 Unix 纳秒:转换 JavaScript 日期时先除以 1_000_000 得到毫秒,并在调用 toISOString() 前检查有效性。浏览器页面自动绑定所在工作区身份,可以不传 workspaceId/workspaceSession;Node 端必须显式传。工作区切换后,原页面的读取被拒绝。更大的资源或二进制文件直接用 Node 文件 API,自行处理并发语义。
自定义文件编辑器的典型写入:
const result = await sdk.workspace.import({
workspaceId, workspaceSession, path: 'notes/example.catnote',
expectedHash: loadedHash, content: nextText, operationId: crypto.randomUUID(),
})
定时任务(schedules)
清单 schedules 声明 {id, command, intervalSeconds, catchUp}。检查点写入安装索引、跨应用重启保留:超过间隔及 5 秒调度宽限后,skip 直接跳过、once 最多补一次;同一命令上次未结束时不重叠触发。先保存检查点再调度,保存失败不执行;两步之间崩溃可能跳过一轮,不保证恰好一次。长任务在事件订阅里用 storage 存业务检查点,激活后重读领域状态。