插件开发最佳实践
本文是 插件开发指南 的操作补充:不重复字段表,只写容易在真实插件里踩到的边界。契约以当前仓库的 Manifest schema 和 Host 实现为准。
官方提供的三类典型参考实现:
- 批量重命名插件:Serpent-Plugin-Renamer(非受限模式
unrestricted,基于 Host 对话框与多列列表控件实现输入防抖、实时改名规则计算与文件名批量重命名) - 通用媒体任务插件:Serpent-Plugin-MediaConverter(媒体转码与压缩,维护后台 Job 队列长任务生命周期与进度状态,采用
any通用包分发) - 原生二进制集成插件:Serpent-Plugin-ImageUpscaler(非受限模式
unrestricted,集成外部 AI 推理二进制可执行文件,按平台独立 ZIP 分流打 包)
用户安装通道:设置 → 插件 → 打开插件社区(目录仓 Serpent-Plugin-Pool);开发者测试通道:GitHub Release 平台 ZIP 或高级安装里的本地成品目录,不要对源码目录执行 npm install。
下文涉及复杂原生二进制分流时以「Image Upscaler」为例,涉及对话框与 UI 列表时以「Renamer」为例,涉及媒体计划与任务流时以「MediaConverter」为例。
1. 先定运行模式和实例范围
| 需要 | 选择 |
|---|---|
只用 serpent.* 读写领域对象、设置、通知 | runtime.mode: "restricted" |
子进程、原生 .node / .bin、自己的模型文件、任意 fs/net | runtime.mode: "unrestricted" |
| 命令/Job 在整个应用会话里注册一次,可服务多个库 | runtime.instanceScope: "global" |
| 每个打开的库各有一份隔离状态 | runtime.instanceScope: "library" |
unrestricted 仍必须走 Gateway 改资产。权限清单不能拦住插件直接调 Node,但 assets.readContent / stageContent / replaceContentBatch 仍然受权限和确认计划约束。不要用 fs 绕过 Gateway 直接覆盖资源库 Assets/ 或链接源目录。
Image Upscaler 使用 unrestricted + global:Upscayl 需要子进程和本地模型,命令与 Job handler 在会话内只注册一次,跨库时用 serpent.forLibrary(libraryId)。
2. 入口只使用 setup / dispose
当前入口是 setup(context) 和 dispose(reason)。不要写 activate / deactivate 或第二套 openLibrary 生命周期。
exports.setup = async function setup(context) {
const { serpent, subscriptions, signal } = context;
subscriptions.add(() => { /* 释放自己创建的资源 */ });
signal.addEventListener('abort', () => {
// 停掉外部进程、下载和循环
});
};
exports.dispose = async function dispose(reason) {
void reason;
};
global 实例没有「当前库」隐含值。命令 handler 从冻结的 context.invocation.libraryId 取值,再 serpent.forLibrary(libraryId)。不要把安装范围 user/library 当成目标库。
3. 命令、菜单与 Invocation
- 行为写 在
contributes.commands;菜单、工具栏、Inspector 只引用 command id。 when控制是否出现,enablement控制是否可点;插件负责自己的显示/置灰策略,Host 不提供accepts过滤,也不替插件过滤混合选中。两者只能读 Context Key。- 异步等待之后不要重新读取「当前选择」。handler 使用
context.invocation(libraryId、selection.assetIds、selection.assets等)。顶层targetLibraryId/assetIds只是兼容字段。当前选中资产的路径和mediaType在selection.assets里,不要再assets.list去找选中项。
Host 发布 selection.mediaKinds、selection.extensions、selection.mixed 和 library.writable 等 Context Key。Image Upscaler 的资产菜单用子菜单挂
1x/2x/4x,并用 selection.extensions intersects ['jpg','jpeg','png','webp'] 隐藏非图片选择;写库前检查 library.writable 以及选择中没有已删除/不可用资产。
图片与视频混合选中的处理规则由插件自己的 when/enablement 表达。
4. Job、进度与取消
Manifest 先声明 Job,recovery 只能是 idempotent 或 checkpoint。handler 在实例级 serpent.jobs.registerHandler 注册;enqueue / reportProgress 走目标库的 forLibrary(...)。
进度协议:
completed/total是 Host 进度条的权威来源。不要把「1 张图」报成total: 1然后在推理的几十秒里一直停在0/1。- 把可观察的工作拆成足够细的单元。Image Upscaler 对每张图使用 100 个单元,并把 Upscayl 输出的百分比映射进去。
phase和message是给用户看的短句,不要放绝对路径、资产 UUID 或协议细节。Host 会做长度限制和路径脱敏,但原文应由插件自己写清楚。- 提交写回前把进度报到 100%,并换成「正在提交」这类终态说明。不要把「等待确认」留在 Job 已经
succeeded之后还显示的最后一条进度上。
取消:把 Job signal 和 setup 的 context.signal 接到同一条中止链上,杀掉当前子进程,且不要对未完成批次调用 replaceContentBatch。应用退出后的 queued/running Job 会变成 Host 的 interrupted,不会自动重跑;需要用户或插件显式重试。
工作区画布上的活动条由 Host 绘制。插件不能隐藏进度条,也不能改标题(当前显示插件 ID 和 handler ID)。进度数字和阶段文案才是插件可控制的部分。
5. 内容读取、分块 staging 与一次确认
读:assets.readContent(assetId, { maxBytes })。写回资产:stageContent + replaceContentBatch(或单资产 replaceContent),支持托管资产与链接资产。写回走 Execution Plan,用户确认一次。