扩展开发指南

Saba-chan 实际的 10 个钩子与 manifest.json 规范、GUI 插槽注入,以及内置扩展的实现要点。

扩展开发指南

扩展(插件)是一种附加组件,它不绑定特定游戏,而是在全局范围挂接到守护进程的生命周期,或向 GUI 注入组件。Saba-chan 守护进程会在以下 10 个时间点(钩子)把控制权交给已启用的扩展。目前内置的扩展有 SteamCMD 安装/更新(steamcmd)和 UE4 INI 解析器(ue4-ini)。

本文档的内容基于 saba-chan-extensions 仓库中实际的 manifest.json 文件以及守护进程端的扩展系统(src/extension/mod.rs)。


1. 文件结构

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.json必需。声明钩子、依赖、字段必需。声明钩子、依赖、字段
  • __init__.py让模块可以以 extensions.<name> 导入让模块可以以 extensions.<name> 导入
  • <python_modules>.pymanifest.json 中 python_modules 引用的文件manifest.json 中 python_modules 引用的文件
  • icon.png可选可选
  • gui/可选。GUI 包 (UMD) 的源码和构建产物可选。GUI 包 (UMD) 的源码和构建产物
  • i18n/可选。用 manifest 中的 i18n_dir 设置 (<locale>.json)可选。用 manifest 中的 i18n_dir 设置 (<locale>.json)
  • test_<name>.py推荐。pytest 测试推荐。pytest 测试
  • 文件夹名称必须与 manifest 的 id 一致。也接受把 id 中的连字符替换为下划线的名称(例如 id ue4-ini → 文件夹 ue4_ini)。否则守护进程不会加载它,并在 GET /api/extensions 的 failed 中列出。
  • id 只能包含字母、数字、- 和 _。

2. manifest.json 规范

SteamCMD 扩展的实际 manifest:

{
  "schema_version": 1,                    // 为 1 时,未知键和从不触发的钩子会报错
  "id": "steamcmd",                       // 与文件夹名称一致
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // 对其他扩展的依赖 (数组或 { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // 逻辑名称 → 文件路径
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

字段摘要:

  • schema_version:为 1 时,未知键、不在 FIRED_HOOKS 中的钩子名称以及对不存在的 python_modules 的引用都会报错。不指定时(0)只会产生警告。
  • id、name、version:必需。version 用于更新和依赖比较。
  • description / descriptions:英文描述和各语言描述。列表 API 会选择与 GUI 语言匹配的描述。
  • min_app_version:在更旧的 Saba-chan 上无法启用或安装该扩展。
  • dependencies:对其他扩展(或 saba-core)的依赖。版本要求仅支持 >=。启用时会检查依赖是否已启用,但不会自动启用它们。
  • python_modules:以逻辑名称注册钩子和命令引用的 Python 文件。未在此注册的文件无法被钩子调用。
  • hooks.<钩子名称>
    • module:在 python_modules 中声明的逻辑名称
    • function:该文件中的函数名
    • condition(可选):只支持 instance.ext_data.<key> 形式。只有该值为 true、非零数字或非空字符串的实例才会运行该钩子。
  • instance_fields:此扩展使用的每个实例的值(extension_data)。只要有任何实例设置了值,禁用或移除该扩展就会被拒绝(in_use)。
  • config_fields:扩展的全局设置字段。值保存在 config.json 的 extensions.settings.<id> 中。
  • gui:bundle(UMD 包路径)、styles(CSS 路径)。见下文第 5 节。
  • cli:CLI 插槽声明(cli.slots)。
  • commands:添加到实例命令列表中的命令(name、label、risk、inputs、module、function、condition)。
  • priority:多个扩展拥有同一钩子时的顺序(数值小的先运行,默认 100)。
  • i18n_dir:翻译文件文件夹。
  • permissions:声明代码使用的高风险能力(与模块的 [permissions] 表相同)。

钩子没有 async 字段,manifest 中也没有 manifest_url。扩展列表和更新只来自 Saba-chan 的已签名版本清单。


3. 实际的 10 个钩子

钩子函数的运行方式与模块相同。守护进程启动 python <file>.py <函数名>,将上下文 JSON 写入 stdin,并读取 stdout 上的 JSON(整体或最后一行)作为结果。退出码必须为 0。下表与守护进程代码中的 FIRED_HOOKS 相同。

钩子名称调用时机结果的用途执行方式
daemon.startup守护进程启动后立即 / 扩展启用后立即(仅该扩展)success/message 写入初始化状态(/api/extensions/init-status)后台
daemon.shutdown守护进程关闭前仅记录日志同步
server.pre_start服务器启动前handled: true 会替代默认启动(此时若 success 不为 true,启动失败)同步
server.stop服务器停止前handled: true 接管停止同步
server.status查询单个服务器状态时handled: true 原样返回该结果同步
server.list_enrich列出实例时handled: true 填充 status 和 extension_status。10 秒超时,30 秒 TTL 缓存同步
server.post_create实例创建后立即不使用结果后台
server.pre_delete实例删除前若 handled,会稍作等待以释放文件锁同步
server.settings_changed实例设置保存后不使用结果同步
server.check_update请求检查更新时第一个成功的结果作为响应同步

server.pre_create、server.pre_install、server.post_install、server.post_start、module.parse_settings、module.write_settings 等名称并不存在;在 schema_version = 1 的 manifest 中使用它们会导致加载失败。

3.1 上下文与入口点

钩子函数接收一个上下文字典并返回一个字典。根据钩子不同,上下文包含 instance_id、instance_name、module、instance_dir、extension_data 等,每个钩子还会以 extension_config 的形式收到扩展的全局设置。Python 文件必须在 __main__ 中自行处理函数名和 stdin。以下是 steamcmd.py 结构的简化示例:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    ctx 示例 (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # 日志输出到 stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # 失败也返回 JSON + 退出码 0

3.2 handled 与执行顺序

  • 拥有同一钩子的扩展按 priority、再按 id 的顺序逐个运行。
  • 如果结果包含 handled: true,其余扩展会被跳过。除非你要替代该钩子的默认行为,否则不要包含 handled。
  • 如果某个扩展失败,会记录错误并运行下一个扩展。
  • 默认时限为 120 秒。钩子路径不显示进度(PROGRESS:)。

3.3 server.list_enrich 的 TTL 缓存

每次请求实例列表时,这个钩子可能会对每个拥有 extension_data 的实例依次调用,因此守护进程会将成功的结果缓存 30 秒。缓存有效期间,会直接复用上次的结果而不启动 Python 进程。每次调用有 10 秒超时,请设计为能快速完成。结果中的 status_line 是显示在 Discord 状态显示中的简短单行状态,请不要在其中放入路径或敏感信息。


4. 三个内置扩展

steamcmd

  • id:steamcmd
  • Python:steamcmd.py(SteamCMD 类:便携版 SteamCMD 安装、游戏服务器安装/更新、更新检查)
  • 钩子:仅 server.check_update(condition: instance.ext_data.install_method_steamcmd)。
  • 实际安装由模块的 install_server 通过 from extensions.steamcmd import SteamCMD 直接完成。
  • instance_fields:install_method_steamcmd、steamcmd_app_id、steamcmd_anonymous、steamcmd_beta、steamcmd_platform。守护进程按通用规则(install_method_<method>、<method>_<field>)从模块的 [install] 部分填充它们。
  • 没有 GUI。

ue4-ini

  • id:ue4-ini(文件夹名称 ue4_ini)
  • Python:ue4_ini.py(parse_option_settings、write_option_settings)
  • 用途:为模块提供读写 Palworld 等 UE4 游戏的 INI OptionSettings=(...) 的工具。
  • 它是一个不声明任何钩子的纯库;模块以 extensions.ue4_ini 导入它。

xna

  • id:xna
  • Python:xna.py(install、present、XnaError)
  • 用途:不在电脑上安装 Microsoft XNA Framework 4.0 Refresh 的固定版本,而是放在游戏服务器文件夹旁边。Terraria 的 Windows 服务器会用到。下载一次官方发布的 MSI,用固定的 SHA-256 校验后,只取出需要的文件。
  • 它是一个不声明任何钩子的纯库;模块以 from extensions.xna import install, present 使用它。

模块无法导入已禁用的扩展。守护进程的导入守卫会拦截对不在 SABA_ENABLED_EXTENSIONS 中的任何 extensions.<name> 的导入。


5. GUI 包(插槽注入)

如果 manifest.json 声明了 gui.bundle,GUI 会通过 GET /api/extensions/:id/gui 获取该文件并运行(如果设置了 gui.styles,也会注入 CSS)。

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // 示例路径
  • 包必须是 UMD 格式,并创建全局变量 window.SabaExt<PascalCase 形式的 id>。去掉 id 中的 - 和 _,并将其后的字母大写(例如 steamcmd → window.SabaExtSteamcmd,ue4-ini → window.SabaExtUe4Ini)。
  • 当该全局变量的 registerSlots() 返回 { slotId: Component | Component[] } 时,GUI 会把它们挂载到对应的插槽中。
  • React 以 external 形式引用宿主的 window.React。组件必须只依靠插槽传入的 props 工作。
  • 翻译通过 GET /api/extensions/:id/i18n/:locale 加载到 ext_<id> 命名空间中。
插槽 id位置props
ServerCard.badge服务器卡片徽章server
ServerCard.headerGauge服务器卡片头部仪表server
ServerCard.provision部署中的服务器卡片server, provisionProgress, onDismiss, t
ServerCard.expandedStats展开的服务器卡片统计server, t
ServerSettings.tab服务器设置标签页server, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.options添加服务器选项t

server 是来自 /api/servers 的服务器信息;组件可以读取 extension_data 和 extension_status[<extension_id>](server.list_enrich 的结果)。


6. 通过 REST API 管理扩展

GET    /api/extensions                   已安装列表 (+ 加载失败项)
GET    /api/extensions/init-status       daemon.startup 结果
POST   /api/extensions/rescan            重新读取文件夹
GET    /api/extensions/manifest          远程目录 (已签名版本清单)
GET    /api/extensions/updates           更新列表
POST   /api/extensions/:id/install       安装 (从目录安装,校验 sha256)
POST   /api/extensions/:id/enable        启用 → 运行该扩展的 daemon.startup
POST   /api/extensions/:id/disable       禁用
POST   /api/extensions/:id/mount         注册到内存
POST   /api/extensions/:id/unmount       从内存注销
DELETE /api/extensions/:id               移除
GET    /api/extensions/:id/config        config_fields 的值
PUT    /api/extensions/:id/config        更新值
GET    /api/extensions/:id/gui           GUI 包 (JS)
GET    /api/extensions/:id/gui/styles    GUI 样式 (CSS)
GET    /api/extensions/:id/icon          图标
GET    /api/extensions/:id/audit         比较代码使用的能力与 permissions
GET    /api/extensions/:id/i18n/:locale  语言 JSON

已启用列表保存在 config.json 的 extensions.enabled 中,全局设置值保存在 extensions.settings 中。


7. 开发规则

  • 扩展同样不得依赖守护进程代码。只使用守护进程传入的上下文和环境变量。
  • 用 os.path.join 构建路径;不要硬编码。
  • 钩子函数同样以 JSON(success: false 和原因)及退出码 0 应答失败,并将日志和回溯输出到 stderr。
  • condition 只使用 instance.ext_data.<key> 形式。其他任何形式都始终视为 false。
  • Python 依赖使用守护进程的共享环境。没有按扩展声明 requirements 的机制。
  • 未验证的扩展:不是从已签名目录下载的扩展,或下载后被修改过的扩展,会和模块一样在隔离环境(Windows 的 AppContainer、Linux 的 bubblewrap)中运行。不会用杀毒软件扫描。以下以 Windows 为准。它们无法访问回环地址(例如守护进程 API),不会收到 SABA_TOKEN_PATH,并且对实例文件夹只有读取权限。需要写入的数据请放在 SABA_EXTENSION_DATA_DIR 环境变量指向的专用文件夹中。
  • 在仓库根目录用 pytest 运行测试。