Serpent 插件开发与发布指南
本文面向准备实际开发、联调和发布 Serpent 插件的人类开发者。文档以当前仓库的
plugin-manifest.ts、plugin-sdk.ts、Plugin Manager API 和测试 fixture 为准;当前平台仍处于开发态,
未在本文中承诺尚未实现的能力。
相关文档:
| 文档 | 用途 |
|---|---|
| 本文 | Manifest、生命周期、Contribution、Job、设置、发布前测试 |
| 插件 API 参考 | serpent.* 方法、权限和错误码 |
| 插件分发与更新 | 安装通道、平台 token、GitHub Release 文件名 |
| 插件开发最佳实践 | 成品包、ZIP 路径、Job 进度、内容分块、原生二进制 |
| 官方插件参考实现 | Renamer(非受限模式 UI 插件)、MediaConverter(媒体转码与通用包)、ImageUpscaler(非受限原生二进制与分流包) |
1. 先了解插件模型
插件是长期运行的扩展,不是一次性脚本。它可以声明命令、菜单、工具栏、Inspector/Viewer 操作、快捷键、
设置、沙箱 iframe 页面、Hook、Job 和 Provider,并在 setup 中注册运行时 handler。
领域读写仍通过 serpent API 进入 Automation Gateway;Renderer 不加载插件后端代码,插件也不能获得任意
SQL 或宿主 DOM。
安装范围和实例范围是两件事:
- 安装范围
user或library决定包存放在哪里;它不决定实例数量。 runtime.instanceScope为global时,一个已解析版本在应用会话中只有一个实例,可服务多个库。runtime.instanceScope为library时,每个打开的库各有一个隔离实例。- 每个实例有自己的
pluginInstanceId;Contribution 按实例撤销,不能只按插件 ID 处理。
当前入口只有一对生命周期函数:setup(context) 和 dispose(reason)。没有 openLibrary、closeLibrary 等第二套
生命周期。库打开/关闭通过领域事件表达。
2. 最小可安装包
发布包是不可变成品,至少包含:
my-plugin/
serpent-plugin.json # 必需,Manifest v1
entry/main.js # 必需,runtime.entry 指向它
README.md # 建议;社区详情英文/回退
README.zh-CN.md # 建议;社区详情中文优先
LICENSE # 建议,发布包应提供
entry/ui/index.html # 可选,沙箱 UI 页面
入口可以由 TypeScript 编译生成,但安装和运行时只读取包内已生成的 JavaScript;安装过程不替插件执行
npm install、构建、postinstall 或 Shell。ZIP 条目必须是相对 POSIX 路径(entry/main.js),不要写成
./entry/main.js 或 entry\\main.js。细则与 Windows 打包方式见 最佳实践 §8
和 分发规范。
一个最小受限插件:
{
"manifestVersion": 1,
"id": "com.example.hello",
"version": "1.0.0",
"name": "Hello",
"description": "A small Serpent plugin.",
"author": "Example",
"license": "MIT",
"engines": {
"serpent": ">=0.1.0 <1.0.0",
"pluginApi": 1
},
"runtime": {
"mode": "restricted",
"entry": "entry/main.js",
"instanceScope": "library"
},
"permissions": ["library.read", "storage.read", "storage.write"],
"contributes": {
"commands": [],
"menus": {},
"toolbar": [],
"inspector": [],
"viewerActions": [],
"shortcuts": [],
"views": [],
"settings": [],
"hooks": [],
"jobs": [],
"providers": [],
"themes": []
}
}
contributes 的数组/对象可以省略,schema 会使用空默认值;发布包建议像上例一样完整写出,便于审查和维护。
Manifest 是 strict schema:未知字段、重复权限、重复 Contribution ID、无效包内路径都会被拒绝。
3. Manifest 完整字段
顶层字段如下:
| 字段 | 必需 | 当前约束 |
|---|---|---|
manifestVersion | 是 | 只能是 1 |
id | 是 | 3–64 字符,稳定的反向域名式 ID;发布后不要更改 |
version | 是 | SemVer |
name | 是 | 1–160 字符;英文或默认展示名 |
description | 是 | 1–2000 字符 |
locales | 否 | zh-CN / en 的 name、description。社区目录文案优先;未进目录时 Host 用清单 locales |
author | 是 | 1–160 字符 |
license | 是 | 1–160 字符 |
repository | 否 | HTTPS GitHub 仓库 URL,必须正好是 owner/repository |
engines | 是 | serpent 是显式比较符 SemVer range;pluginApi 当前只能为 1 |
runtime | 是 | 见下一节 |
ui | 否 | { "entry": "包内相对 HTML 路径" },作为插件 UI 包入口 |
permissions | 是 | 最多 64 个,不得重复;只声明当前确实需要的权限 |
contributes | 是 | 见第 5 节;各类 Contribution ID 在插件内必须唯一 |
mcp | 否 | { "expose": ["命令 local id"] },见第 10 节 |
所有路径必须是包内相对路径;不能是绝对路径、路径穿越或逃逸符号链接。runtime.entry 和 ui.entry 必须
指向包内文件。