扩展开发指南
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. 文件结构
- 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 中的连字符替换为下划线的名称(例如 idue4-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运行测试。