Serpent 是一款面向游戏美术、VFX 与动效设计师的跨平台数字资产管理软件，用来集中管理图片、视频、音频、3D 模型等资源库。它的插件系统允许你在不修改任何资源库的前提下，为 Serpent 增加批量重命名、媒体转码、图像超分等新工具和新工作流——而且整个过程无需写一行代码：打开「插件社区」，浏览、确认权限、一键安装，3 步即可让插件为你所用。

💡 本文适合第一次接触 Serpent 插件的新手用户，全程以图形界面操作为主。

什么是 Serpent 插件

插件（Plugin）可以为 Serpent 增加新的工具、菜单或工作流程。它和脚本最大的区别在于：插件是长期运行的扩展，可以贡献命令、菜单、工具栏按钮、查看器操作、快捷键、设置页，甚至是插件自己的沙盒 UI；而插件不属于资源库中的普通资产，安装后可以随时启用或停用，不影响资源库本身。

几个新手最容易混淆的概念：

一键安装官方插件：3 步完成

1. 打开「设置」→「插件」，点击「打开插件社区」；
2. 浏览或搜索插件，点击卡片查看作者、版本、仓库、权限声明和详细说明，选择安装到「全局」或当前资源库，点击「安装」；
3. 安装完成后返回插件列表，在插件卡片上打开「启用」即可使用。

安装过程比看起来更"较真"：社区通道会按目录条目钉死的 Release 包下载，并逐一核对 SHA-256 校验和，哈希不符、缺少当前平台包都会明确提示失败原因，而不是静默装错包。这套目录机制的实现可参考 plugin-community-catalog.ts。

当前社区中就能看到带「官方」徽章的插件，例如使用 FFmpeg 批量转码视频、压缩图片的媒体转换插件，以及使用 Upscayl NCNN 模型放大图片的图像超分辨率插件。

高级安装：ZIP、文件夹或 GitHub 地址

如果你有插件作者直接分发的本地文件，或插件尚未收录进社区目录，可以使用「高级安装」（设置 → 插件 → 高级安装）：

• 安装 ZIP：选择符合规范的.zip插件包；
• 安装文件夹：选择已构建的插件目录；
• 粘贴 GitHub 仓库 / Release 地址：Serpent 会优先选取匹配当前平台的 Release 包。

高级安装的插件在安装时会显示未认证警告，请务必确认来源可靠。一个符合规范的插件包至少包含serpent-plugin.json清单、编译后的入口 JS 和 README，Serpent 安装时只校验成品包，不会在你机器上执行npm install或现场构建。

首次启用时的信任确认

• 处于受限模式的插件可直接启用；
• 无限制插件在首次启用前会询问是否信任它——它会申请更高的本地权限（外部进程、网络请求等），只有确认来源可靠时才选择信任；
• 修改插件设置后点击「重载」即可生效，不必重启 Serpent；
• 若同一插件同时存在全局版和资源库版，插件列表会提示当前使用的版本，可就地切换或停用。

更新、卸载与常见问题

更新：自动更新默认关闭（开启前会展示风险说明）。从插件社区安装的插件采用"版本钉死"策略，不会静默跟随 GitHub 最新 Release——目录中出现新版本后，你会在设置页收到更新提示，点击即可完成更新。

卸载：卸载插件不会删除它保存的个人设置。以后重装同一插件即可恢复原有配置；如果插件提供了自己的清理入口，优先使用它。

遇到问题：插件没出现在列表、启用后无反应时，先检查插件是否安装在正确的范围，并重新打开插件设置；仍无法使用时联系插件作者，附上 Serpent 版本、操作系统和插件名称即可（🔒 切勿在反馈中公开 API Key 等隐私信息）。更多细节见 插件使用文档。

写给想更进一步的你

Serpent 的插件管理实现集中在 src/plugins/ 目录：清单校验在 plugin-manifest.ts、安全与权限模型见 plugin-permission-capabilities.ts。如果你是开发者，可以继续阅读：

• 插件开发指南：Manifest、生命周期与发布前测试
• 插件开发最佳实践：成品包与 ZIP 打包规范
• 插件分发与更新：发布与申请官方认证收录的流程
• 插件 API 参考：serpent.*方法、权限和错误码

从插件社区一键安装开始，让 Serpent 随你的工作流一起成长吧 🚀