海豹手册

主题

扩展包与商店 v1.6.0 ​

扩展包是以 .sealpack 为后缀的安装包，可以同时携带 JavaScript 脚本、牌堆、自定义回复、帮助文档和规则模板。包内的 info.toml 声明名称、版本、海豹版本要求、依赖、权限和内容清单。

扩展包会执行第三方内容

扩展包可能发送网络请求、读写文件、启动 HTTP 服务，声明“危险操作”权限的包还可能执行外部程序。安装前应确认作者和来源，并在预览中检查权限、依赖和文件列表。

商店展示和权限声明不能代替代码审查。不要在生产骰子上安装来历不明的 .sealpack 文件。

打开扩展包管理 ​

在 WebUI 中进入「扩展功能 - 扩展包」。页面包含“已安装包”和“商店”，并提供上传安装、URL 安装和重载入口。

已安装包有以下状态：

  • 已安装：文件已保存，但内容尚未启用。
  • 已启用：包被允许参与下一次对应内容的加载。
  • 已禁用：包内容不再加载，临时缓存会被清理。
  • 错误：清单、依赖、版本或加载过程存在错误，应先查看详情和核心日志。

“安装”和“启用”是两个步骤。启用或禁用后，页面会显示待重载内容；完成重载后变更才会完整应用。

安装扩展包 ​

从商店安装 ​

在“商店”中打开扩展包详情，先检查版本、作者、说明、依赖、权限和文件。点击安装后仍会显示安装预览；确认内容无误后，可以选择“安装后启用”和“安装并启用后自动重载”。

“从清单安装”可以一次处理多个精确版本的扩展包，并逐项显示安装、启用和失败状态。批量安装前仍应逐个核对来源和权限。

上传 .sealpack ​

在“上传安装”中选择本地 .sealpack 文件。海豹会先解析清单并展示将安装的文件、版本变化、权限和选项，确认后才执行安装。

从 URL 安装 ​

在“URL 安装”中填写直接指向 .sealpack 文件的地址。远程内容可能随时变化，应只使用可信作者提供的固定版本地址，并仔细核对安装预览。

海豹会检查包格式、路径、版本约束和商店提供的哈希信息。检查通过只表示文件结构符合要求，不代表其中的脚本逻辑可信。

依赖与版本 ​

扩展包可以声明：

  • 适用的最低和最高海豹版本；
  • 依赖的其他扩展包 ID；
  • 依赖包需要满足的语义化版本范围。

依赖缺失或版本不符时，扩展包不能正常启用。商店或清单安装可以按依赖关系批量处理；手工上传时，应根据预览提示先安装正确版本的依赖。禁用或卸载被其他包依赖的扩展包前，也要检查受影响的包。

启用、禁用与重载 ​

在“已安装包”中可以启用或禁用单个包。状态变化后，点击页面顶部“重载扩展”，或从下拉菜单只重载指定内容：

  • 脚本；
  • 牌堆；
  • 自定义回复；
  • 帮助文档；
  • 规则模板。

只改动一种内容时，按类型重载可以减少等待时间。帮助文档和大量 JavaScript 插件的重载可能较慢；重载期间不要连续重复点击，也不要重启核心。

禁用包会清理运行缓存，但不会删除 .sealpack 源文件和用户数据。重新启用并重载后，内容会从包中重建。

卸载与用户数据 ​

卸载时可以选择：

  • full - 完全卸载：删除包文件、运行缓存、配置和用户数据。
  • keep_data - 保留数据：删除包文件和运行缓存，保留用户配置及运行数据，便于以后重新安装同一包。

扩展包的用户数据位于 data/extensions/<作者>/<包名>/_userdata/，其中可能包括 config.json 和插件自行保存的数据。重要数据应在卸载前备份；“完全卸载”不可通过 WebUI 撤销。

上传或商店安装的源包通常保存在 data/packages/，解压后的运行缓存位于 cache/packages/。如果源 .sealpack 丢失，页面会显示“仅缓存安装”；应放回源文件并刷新，而不是长期依赖缓存。

权限说明 ​

安装预览会显示包在 info.toml 中声明的权限：

  • 网络：允许发起 HTTP 请求；包可以进一步声明允许访问的域名白名单。
  • 文件读取：允许读取声明路径内的文件。未声明的读取请求会被包沙箱拒绝。
  • 文件写入：允许写入声明路径；未额外声明时默认只允许写入包自己的 _userdata 目录。
  • 危险操作：允许执行外部程序等高风险行为。只应授予经过代码审查的扩展包。
  • HTTP 服务：允许扩展包监听 HTTP 服务。启用前应检查监听地址、端口、防火墙和反向代理配置。
  • 扩展间通信：允许与清单列出的其他扩展包通信。

权限声明用于限制包通过扩展包接口发起的操作，但不是完整的恶意代码防护边界。涉及“危险操作”、广泛文件权限或不受限网络访问时，应在隔离环境中先行验证。

与其他扩展功能的关系 ​

扩展包是内容的分发和生命周期管理层：

  • 包内脚本加载后成为 JavaScript 扩展，并通过 .ext 管理群内启用状态。
  • 包内牌堆由 .draw 和文案中的 #{DRAW-牌组名} 使用。
  • 包内自定义回复与本地回复共同参与匹配；包被禁用后，相关回复在重载后停止生效。
  • 包内帮助文档进入 .help 和 .find 的搜索索引。
  • 包内规则模板可以注册游戏系统、属性别名、默认骰面和群名片模板，并可由 .set <规则名> 选用。

手工上传的本地文件仍在各自的牌堆、回复、帮助文档和 JS 页面管理。由扩展包提供的内容应优先通过扩展包页面升级、禁用或卸载，避免直接修改缓存文件；缓存会在重载或升级时重建。