Skip to content

Latest commit

 

History

History
76 lines (44 loc) · 7.11 KB

plugin-development_cn.md

File metadata and controls

76 lines (44 loc) · 7.11 KB

使用活动安装内容开发插件

English | 简体中文

插件参考项目为 OpenTest-Plugins。宿主 pnpm dev、pnpm dev:backend、pnpm build 和 pnpm start 独立运行,不自动构建插件源码。先通过插件管理导入兼容的 .otplugin 并完整重启,再使用插件仓库的开发命令更新这一份活动安装内容。宿主运行时不会直接加载插件源码目录。

default-plugins.json 只列公开插件 fft-tools。需要准备该清单时,可显式运行 pnpm prepare:plugins。其源码来自 OpenTest-Plugins,目录通过 OPENTEST_PUBLIC_PLUGINS_SOURCE 指定,缺省为 ../OpenTest-Plugins,相对路径按宿主根目录解析。准备过程要求清单所需的源码与依赖已就绪。需要随宿主打包时,先独立构建最终插件包,再显式传入 --plugins-dir。--edition community 只随附清单内插件;--edition full 还接受 --plugins-dir 中其他兼容的业务插件包。

显式运行的批量准备过程校验开发包(dev-kit)摘要、宿主兼容范围及已安装依赖锁,使用现有前端依赖和增量 Maven 编译,不自动安装依赖或改写 SDK、锁文件。它会将宿主公开 Java API 及必要模块依赖安装到现有 Maven 本地仓库。默认准备跳过插件测试;需要完整检查时可使用 pnpm prepare:plugins --release。宿主打包接收已经构建完成的插件包,不重新编译插件。

显式准备的完整 .otplugin 和 index.json 保存在宿主 .runtime/bundled-plugins/。存在随附材料时,插件管理中的“打开随附插件目录”可定位它们。手动重新安装仍需预览、信任确认和完整重启。用户卸载过的插件不自动重装,禁用状态保留,较新已安装版本不降级;已通过开发命令修改的活动内容不被随附安装流程覆盖。

配置与启动

在插件仓库根目录复制其 plugin-development.example.json 为 Git 忽略的 plugin-development.json,将 runtimeDirectory 指向本宿主使用的运行根。相对路径按该配置文件所在目录解析,环境变量不覆盖它。

# opentest-plugins 根目录:构建并投递完整插件
pnpm dev fft-tools

# opentest 根目录:执行 Maven clean package,并以可变已安装内容策略启动 JAR
pnpm dev

不带插件名的插件命令处理全部插件。命令会读取宿主 plugins/state/active-plugins.json,使用其中的插件标识、安装版本和包摘要定位正常安装目录;未正常安装的插件逐项失败,但不阻止其他插件继续。开发命令不改写宿主状态或安装包原有的 files.sha256。

活动状态中的插件标识、安装版本和包摘要是安装身份,只负责定位目录并始终保持正式安装值。目录内实际 plugin.json 是本次运行清单,允许声明不同的运行版本;开发候选和登记报告中的 version 表示该运行版本,packageDigest 仍表示原正式安装摘要。二者不能重新组合成另一个安装目录坐标。

宿主 pnpm dev 和 pnpm dev:backend 只通过可执行 cry-daq.jar 启动,并显式使用 mutable 已安装内容策略。pnpm start、安装版和没有显式参数的 Java 启动保持 strict。

修改如何生效

改动 操作
Java 后端、plugin.json、贡献或 contracts 重新运行完整插件 pnpm dev <插件名>,成功后手动重启宿主后端,再完整刷新页面
前端或语言资源 运行一次完整插件命令,或保持 pnpm dev:watch <插件名>;投递成功后手动完整刷新页面
插件依赖或构建环境 准备依赖后重启插件命令;开发命令不会自动安装前端依赖

监听命令只构建并投递 frontend/ 和 locales/,不处理后端、清单或契约。前端没有 revision 轮询、插件级 dispose/re-activate 或自动刷新;完整页面刷新会重新建立模块图并读取实际安装内容。

失败、管理与恢复

  • 投递采用原地同步,没有 staging、备份或自动回滚。失败后活动目录可能是部分新旧内容;修复后重新运行完整插件命令,成功前不要启动后端或刷新页面。
  • 后端 JAR 覆盖失败不会阻止前端和语言资源继续尝试,命令仍整体失败并逐项报告真实结果。
  • 开发模式不禁用插件管理。安装、升级、启用、禁用和卸载继续按待生效操作及完整重启边界执行。
  • 若当前插件存在待升级、禁用或卸载,开发工具仍覆盖当前活动目录,并提示下一次完整重启可能替换或删除它。
  • 严格启动会拒绝被开发覆盖的正式包。没有专用恢复命令;通过正常插件管理卸载并重新安装 .otplugin 后再返回严格运行。

验证入口

插件构建、投递和监听行为在插件仓库通过 pnpm test:tools 验证。宿主侧通过已安装内容解析、运行生命周期、资源控制器、正常前端 bootstrap 和开发 JAR 启动测试验证;宿主不引用插件业务实现或测试 JAR。

宿主公开提供的 Jackson

插件可以直接使用宿主交付的 com.fasterxml.jackson.* 类,运行时与宿主共享同一份类型和版本。Maven 依赖使用与目标宿主匹配的版本并声明 provided;不要将 Jackson 类打入插件后端 JAR,普通条目和多版本 JAR 条目都会被拒绝。

此约定覆盖宿主实际交付的 Jackson 模块,不保证任意可选模块存在,也不开放其他第三方库或宿主私有实现。依赖交付边界见 宿主公开提供 Jackson。

测量编辑

配置、插件动作和结果参数写入由 DashboardProvider.editor() 返回的 MeasurementEditor 统一决定。新增业务规则使用 editCurrent / editSaved,不新增业务专用宿主回调;读和执行投影继续使用 ConfigurationProjection。规则迁移及验证边界见测量编辑契约。

Pipeline 文件输出

原始 WAV、外部 WAV/HDF5/PTI 和结果 crybin 由插件在自己的图中显式连接。公共节点、冻结输入、文件目标与完成边界见Pipeline 文件输出接入。

工程触发器引用

插件使用 SDK 专用类型声明引用,详见项目触发器引用。

Crybin 文件单位标识

结果定义通过 custom.fileUnitIdentity 声明 Y_ONLY(默认)或 X_AND_Y。只有文件必须按 X 单位区分的结果才声明后者,例如声品质中的 Hz/Bark 特殊结果。真实 X 单位与数值坐标始终保留。

标准文件及缩略图处理器使用 ResultFileUnitRules.fromRequirements(run.resultRequirements()),不要根据实时/录音模式选择命名规则。宿主把当前或已保存的结果声明绑定到执行需求与文件目标;ResultFileNames 接受同一 ResultFileUnitIdentity。历史读取仅匹配声明对应的文件身份。详见 ADR 0033。