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 存业务检查点,激活后重读领域状态。