插件开发指南

在 插件 → 插件管理 → 新建插件 选择 Hello、Webview 面板或 Seed&Key DLL。模板包含 plugin.json、src/extension.ts、tsconfig.json 和 types/。带面板的模板还包含 webview/。BeiniLink 会在激活时编译后台 TypeScript 或 JavaScript。

清单与激活

plugin.json 使用 manifestVersion: 1。填写小写点分隔的 id、name、version、publisher 和 engines.beinilink。清单 Schema 位于模板的 types/plugin.manifest.schema.json。使用 main 指定后台入口，在 contributes 声明命令、功能区按钮和面板。

description 可提供中英文。管理器读取清单声明的 PNG 图标（至多 256 KiB、1024 × 1024）及 Markdown 介绍（默认 README.md，至多 128 KiB）。资源路径相对于插件目录。

插件按命令、面板或声明的 onStartupFinished、onProjectOpen、onMeasurementStart 事件激活。在 activate(context) 注册的订阅放进 context.subscriptions。停用时宿主释放订阅，deactivate() 可关闭插件自己的资源。

工程与信任

全局插件位于应用数据的 plugins/，可从管理器打开。工程插件随 .blproj 放在同级的 plugins/，每个插件一个目录。存在相同 ID 时，工程条目优先。工程插件等待信任期间，同 ID 的全局插件显示为被覆盖。同一范围内的重复 ID 会标为无效。

工程插件可访问本机文件和运行程序。信任仅匹配此机的工程目录、插件 ID、版本和清单 SHA-256。更改清单后需要重新确认。管理器可补授或撤销信任。信任记录随本机配置保存。禁用状态按全局插件 ID 或工程目录和插件 ID 分别保存。信任并启用工程插件时，仅启用当前工程中的插件。

后台 API 与状态

后台通过 import * as bl from "beinilink" 使用 API。模板中的 types/beinilink.d.ts 包含完整签名。

• bl.commands.registerCommand 注册已声明命令。用 bl.window.createOutputChannel 或 console.log 输出调试信息。
• bl.measurement 订阅测量生命周期。bl.variables 读取变量。bl.signals 的后台缓存采用接收帧，Webview 的信号读取也包含发送帧。
• bl.bus.onCanFrame(0x100, callback) 匹配同 ID 的标准帧和扩展帧。可在回调里读取 msg.msgType.idType 区分。写变量、信号及发帧需要在线测量。
• bl.workspace.getProjectState() 读取当前工程中本插件的状态。调用 await bl.workspace.updateProjectState({ counter: 1 }) 会标记工程已修改。每个插件的状态须能序列化为不超过 1 MiB 的 JSON，保存工程时写入 pluginStates。
• 使用 context.storagePath 保存本机数据。工程插件按工程目录隔离本机数据，全局插件使用全局数据目录。

DBC/LDF 解析结果分别限 64 MiB。插件后台使用数据库的本地副本，内存占用随活动 Worker 数增加。

Webview

在 HTML 脚本中调用 acquireBeiniLinkApi()。等待 api.ready 后再读 getState()，用 setState() 保存当前打开面板的临时状态。用 postMessage / onMessage 和后台交换消息。关闭面板会结束该会话，持久化数据使用工程状态 API。

Seed&Key DLL

声明 "capabilities": { "native": true }。用 bl.native.dllArchitecture(path) 检测 x86 或 x64，再用 bl.native.computeSeedKey 传入绝对路径、Uint8Array 种子和安全级别。传入 options 时调用 GenerateKeyExOpt。两个宿主独立运行，默认超时 5 秒，最大 30 秒。

x86 自动模式先查 stdcall 修饰名，再按 cdecl 查未修饰名。如果 x86 stdcall DLL 导出未修饰名称，请显式设置 callingConvention: "stdcall"。该模式先查修饰名，再按 stdcall ABI 调用未修饰名。variant 和 options 按 UTF-8 传入，面向按 ANSI 读取参数的 DLL 时使用 ASCII。

调试与分发

修改源码后在管理器重载，编译和 Worker 错误会显示在信息窗口。用模板配套的 TypeScript 声明检查 API 参数。

将插件内容压成 ZIP，把扩展名改为 .blplugin。包内 plugin.json 可放在根目录或唯一顶层目录。使用 UTF-8 路径和普通文件，展开后至多 200 MiB、10,000 个条目。管理器导入到全局插件目录，已有同 ID 时先核对版本并确认覆盖。卸载全局插件时可选择一并删除其本机数据。