插件与上下文

SkyNotePlugin

成员	契约
id	唯一字符串，注册资源与插件替换以此识别
name / version	名称与版本信息
install(ctx)	同步安装，注册节点、输入或派生能力
unmount?()	释放插件自己持有的资源与瞬态状态

import type { CanvasPluginContext, SkyNotePlugin } from '@skynote/core';

export class MyPlugin implements SkyNotePlugin {
  readonly id = 'example/my-plugin';
  readonly name = '示例插件';
  readonly version = '0.1.0';

  install(ctx: CanvasPluginContext): void {
    ctx.registerInputScope({ id: this.id, priority: 10, onKeyDown: () => false });
  }
}

Editor构造参数plugins在内置能力后安装，相同id会替换已安装者。不要依赖另一个插件的安装私有状态；需要组合时由宿主装配公开接口。

CanvasPluginContext 读取能力

属性 / 方法	能力与边界
document	文档查询和语义命令，写入经事务
entities	只读实体索引、父子关系、世界几何等
spatial	世界坐标空间查询
connectors	路由、预览、吸附和连线几何
nodeTypes / layouts	已注册类型和布局的只读入口
session	选区、视口、工具和主题会话
host	覆盖层、光标、指针捕获等宿主能力
hitTest(point)	最上层命中实体或null
hitTestNode(point, accept?)	按真实轮廓命中节点，支持筛选
hitTestConnector(point, tolerancePx?)	连线拾取，容差单位为屏幕像素

宿主尚未挂载时，host可能是空实现。插件不能在install时假定浏览器DOM存在；需要覆盖层时订阅onHostChange，宿主离开时清理已有会话。

注册能力

接口	注册内容 / 清理
registerNodeType	节点模型与声明式绘制
registerConnectorRouter / registerArrowMarker	线型与端点标记
registerLayout	布局策略
registerConnectorSource	派生连线来源；refreshConnectorSource(id)请求重算
registerCursor	统一光标
registerInputScope	键盘作用域，返回注销函数
registerPointerHooks(hooks, priority = 0)	指针、滚轮与右键钩子，返回注销函数
registerClipboardHandler(handler, priority = 0)	剪贴板处理，返回注销函数

经上下文注册的资源随插件卸载管理；自行创建的订阅、请求、计时器和对象URL仍由插件负责。临时功能可提前调用返回的注销函数，不必等整个插件卸载。

监听与异步

onDocumentChange(changes, record)和onSessionChange(change)通知已经发生的变化。监听中读取受影响集合并更新瞬态状态，避免同步提交新的文档事务形成级联。

insertImage、pasteNodesWithAssets等任务按AssetTaskResult反馈。插件不要自己把二进制写进文档，也不要把跨库资产引用当成一定可用。长任务使用取消或代次检查，插件退出后到达的结果不再落库。

完整节点实现见自定义节点教程，输入协作见InputScope。