模块开发指南
如何构建为 Saba-chan 添加新游戏的 Python 模块。涵盖 module.toml 规范以及 lifecycle.py 的实际函数约定与协议。
模块开发指南(Python)
Saba-chan 守护进程并不了解各个游戏的具体细节。每款游戏都由一个 Python 模块 来描述。添加一个模块,Saba-chan 就能管理一款新游戏。
本文档基于 saba-chan-modules 仓库中的实际模块(minecraft、palworld、zomboid)、带注释的模板 __example 以及守护进程代码。
1. 模块文件结构
- module.toml必需。声明 (schema v1)必需。声明 (schema v1)
- lifecycle.py必需。由 [module].entry 指定的入口文件必需。由 [module].entry 指定的入口文件
- icon.png可选。用 [module].icon 设置可选。用 [module].icon 设置
- locales/
- en.json基准语言基准语言
- ko.json
- ...UI 字符串UI 字符串
- test_lifecycle.py可选。pytest 单元测试 (推荐)可选。pytest 单元测试 (推荐)
- 文件夹名称应与
module.toml中的[module].name相同,使用小写英文。 - 守护进程只读取模块根目录下第一层、且包含
module.toml的文件夹;缺少[module].entry文件的模块不会被加载。 - 入门时,建议将
__example/__example__module.toml复制为module.toml,将__example/__example__lifecycle.py复制为lifecycle.py,再删除不需要的部分。
2. module.toml 规范
以下是实际 minecraft/module.toml 开头部分的简化示例:
[module]
schema_version = 1 # 必需。存在未知键或无效值会导致加载失败
name = "minecraft" # 与文件夹名称相同
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py" # 守护进程运行的 Python 文件
icon = "icon.png"
log_pattern = '^\[\d{2}:\d{2}:\d{2}(?:\] \[[^\]]*/| )(?P<level>INFO|WARN|ERROR|DEBUG|FATAL)\]'
[module.dependencies]
saba-core = ">=0.1.5" # 组件 → 最低版本 (仅支持 ">=")
[permissions]
network = true # 代码使用的能力
spawn_process = true
[protocols]
supported = ["stdin"] # 从 "stdin" / "rest" 中选择
default = "stdin"
interaction_mode = "console" # "console" 或 "commands"
[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say" # 用于公告的 [[commands.fields]] 名称
# 省略 stop_command 时默认为 "stop"
[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"
[install]
method = "download" # "manual" (默认) / "download" / 扩展 id (例如 "steamcmd")
[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]
各部分的含义:
[module]:元数据。name、version和entry为必需。log_pattern通过(?P<level>…)分组提取控制台行的日志级别。[module.dependencies]中的键为saba-core、ext-<扩展 id>等。[permissions]:声明代码使用的高风险能力(network、spawn_process、native_code、dynamic_code、env_secrets、fs_outside_instance)。[protocols]:supported接受"stdin"、"rest"和"rcon"。命令路径的顺序是 stdin、REST、RCON。只有既没有控制台也没有 REST API 的游戏才使用 RCON。这类游戏还必须声明rcon_port,守护进程会为每个实例分配端口和随机密码。游戏有控制台或 REST 时,模块会关闭其 RCON 设置。interaction_mode决定显示控制台界面(console)还是只显示命令按钮(commands)。[config]:server_executable、executable_path、process_name、default_port、stop_command(发送到控制台的停止命令,默认stop)、stop_timeout(秒,默认 30)、announce_command。游戏设置应写在[[settings.fields]]中,而不是这里。[[settings.fields]]:实例设置界面中的项目(name、type、label、default、options、group等)。用户修改的值保存为实例设置,并出现在每次函数调用的 config 中。install = true的项目是创建新服务器时选择的值(服务器类型、新世界设置等),由创建界面、网页和 CLIserver add询问。select 项目的install_options只列出 Saba-chan 可以新安装的值(其余options只在判定导入的服务器时使用)。[[commands.fields]]:游戏命令。method = "console"(+console_template)时命令发送到控制台(stdin),"rest"时发送到游戏的 REST API,"module"(默认)时发送到lifecycle.py中的command()。risk(safe/caution/danger)和description会被 AI 命令解析读取。[install]:安装方式、app_id、requires_extensions(所需扩展 id 列表)等。Palworld 需要["steamcmd", "ue4-ini"]。[detection]:识别现有服务器文件夹(dir_signatures)、查找进程(process_patterns、cmd_patterns)以及崩溃检测(graceful_exit_patterns、crash_artifacts)。只有被判定为崩溃的退出才会自动重启。[backup]:备份包含的路径(paths)、备份前执行的命令(save_command),以及路径由代码计算时的hook = true。[credential_map]:将守护进程的标准键映射到游戏设置键。Palworld 示例:rest_password = "AdminPassword"。- 此外还有
[launch]、[[agreements]]、[[presets]]、[[queries]]、[aliases]、[errors]、[[syntax_highlight.rules]]和[extensions.<id>]。完整的键列表请参阅saba-chan-modules仓库中的docs/module-spec.md。
3. lifecycle.py 函数约定
每当需要时,守护进程都会启动一个新的 Python 进程来调用此文件中的一个函数。每个函数接收一个 config: dict 并返回一个 dict,且必须登记在文件末尾的 FUNCTIONS 表中。模块没有 start 函数:守护进程会根据 get_launch_command 的结果自行启动服务器。
3.1 必需函数
唯一必需的函数是 get_launch_command。
import os
from daemon_rcon import config_value, run_lifecycle
def get_launch_command(config: dict) -> dict:
"""返回服务器的启动方式。进程由守护进程启动。"""
exe = config.get("server_executable", "")
if not exe or not os.path.exists(exe):
return {"success": False, "message": f"Server executable not found: {exe}"}
port = config_value(config, "port", 7777)
return {
"success": True,
"program": exe,
"args": [f"-port={port}"],
"working_dir": config.get("working_dir") or os.path.dirname(exe),
"env_vars": {},
}
FUNCTIONS = {"get_launch_command": get_launch_command}
if __name__ == "__main__":
run_lifecycle(FUNCTIONS)
- 守护进程会把实例设置(
module_settings)展开到 config 的顶层。用config_value(config, key, default)读取是安全的做法。 - 如果 config 中包含
extra_args(用户添加的启动参数),请把它们放到合适的位置并返回extra_args_placed: true。否则守护进程会把它们追加到args的末尾。 preview: true表示启动参数预览。不要写入设置文件,只返回启动信息。
3.2 可选函数
只实现你支持的功能;一旦实现,务必将其添加到 FUNCTIONS 表中。
| 函数 | 守护进程调用时机 | 返回值 |
|---|---|---|
validate | 启动前检查 | success、issues[](只要有一项为 severity: "critical",服务器就不会启动) |
stop | 停止没有控制台的服务器,以及非托管服务器 | success |
status | 非托管服务器的状态查询 | status、pid |
command | method = "module" 的命令 | success、message |
get_credentials | 需要 REST 连接信息时 | rest_username、rest_password |
configure / read_properties / reset_properties / reset_server | 设置界面的保存 / 读取 / 重置 | success(+ 读取的值) |
import_settings | 迁移现有服务器时读取设置 | settings{} |
list_versions / get_version_details | 版本列表 / 详情 | 版本信息 |
install_server | 安装和更新 | success、executable_path、install_path |
get_installed_version | 已安装版本查询 | version |
accept_agreements | 用户同意 [[agreements]] 之后 | success |
diagnose_log | 日志诊断 | success |
backup_paths | 备份(当 [backup] hook = true 时) | success、paths[] |
instance_commands | 命令列表(当 [commands] hook = true 时) | success、commands[] |
通用规则:
- 每个响应都包含
success: bool和message: str。如果需要用户操作,请包含action_required: "<code>"。 - 如果缺少所需的扩展,请用
error_code: "extension_required"和missing_extensions: [...]应答。 - 对于未知的函数名,应答
{"success": false, "message": "Unknown function: X"}(由run_lifecycle()处理)。
对于有控制台的托管服务器,守护进程会把
[config].stop_command发送到控制台(stdin)并等待,以此停止服务器。模块的stop()只在没有控制台时才会被调用;它必须遵循 正常停止请求 → 等待 → 强制结束 的顺序,并且只能处理守护进程传入的pid。
4. 子进程协议
守护进程调用模块函数的方式实现在 Saba-chan 仓库的 src/plugin/mod.rs 中。概括如下:
- 使用守护进程管理的 Python 环境启动
python lifecycle.py <函数名>。 - 注入的环境变量:
PYTHONIOENCODING=utf-8、PYTHONUNBUFFERED=1PYTHONPATH:存放共享文件(i18n.py、daemon_rcon.py)的模块文件夹,以及扩展文件夹的上级目录SABA_IPC_URL、SABA_IPC_PORT:守护进程 API 地址SABA_TOKEN_PATH:保存守护进程 API 令牌的文件路径SABA_LANG:GUI 语言SABA_ENABLED_EXTENSIONS:以逗号分隔的已启用扩展 id(例如steamcmd,ue4-ini)
- 向 stdin 写入一个 config JSON 对象后关闭。
- 将整个 stdout 解析为 JSON;如果失败,则使用最后一个非空行作为结果。
- stderr 是日志。以
PROGRESS:开头的行会被解析为进度事件,用于显示安装进度。 - 退出码必须为 0。 否则即使 stdout 中包含
success: false,守护进程也会将此次调用视为一般错误。 - 每次调用后进程都会退出。默认时限为 120 秒;只有在部署和更新期间的
install_server会获得更长的时间(1800 秒)。
未验证的模块:不是从 Saba-chan 签名目录获取、或下载后被修改的模块,在 Windows 的 AppContainer、Linux 的 bubblewrap 中运行。Saba-chan 不会用杀毒软件扫描它。在无法隔离的环境(没有 bubblewrap 或无法使用 bubblewrap 的 Linux、macOS)中,只有在你同意当前文件后才会运行。在隔离中,模块不能直接连接回环地址(使用公共辅助函数时由守护进程转发),不会收到
SABA_TOKEN_PATH,只能写入实例文件夹、工作文件夹、安装文件夹和data_roots中声明的文件夹。它也不能使用msiexec和tempfile.mkdtemp创建的文件夹。完整列表见 制作模块:从调研到发布。
4.1 进度报告示例
# 在 install_server 内部
import json, sys
def report(step, total, percent, msg):
sys.stderr.write("PROGRESS:" + json.dumps({
"step": step, "total": total, "percent": percent, "message": msg
}) + "\n")
sys.stderr.flush()
report(1, 3, 10, "开始下载")
# … 实际下载 …
report(2, 3, 70, "正在解压")
# …
report(3, 3, 100, "安装完成")
可识别的字段有 percent、message、step、total 和 label。
5. 共享工具
守护进程会把共享文件 i18n.py 和 daemon_rcon.py 放在模块文件夹中,并将其加入 PYTHONPATH。请不要把它们复制到你的模块文件夹中。
import os
from i18n import I18n
from daemon_rcon import daemon_stdin_command, wait_for_exit, force_kill
MODULE_DIR = os.path.dirname(os.path.abspath(__file__))
i18n = I18n(MODULE_DIR) # MODULE_DIR/locales/<SABA_LANG>.json
msg = i18n.t("errors.failed_to_stop", error="…") # 替换字符串中的 {{error}}
daemon_stdin_command(config["instance_id"], "save-all") # 向服务器控制台发送一行
daemon_rcon.py 只是出于历史原因保留了这个名称;它从不打开 RCON 套接字。主要辅助函数:
| 函数 | 用途 |
|---|---|
daemon_stdin_command(instance_id, line) | 向守护进程托管服务器的控制台发送命令 |
daemon_post(path, payload) | 调用其他守护进程 API(自动附加令牌) |
is_process_alive、wait_for_exit、force_kill | 按 PID 检查 / 等待 / 强制结束 |
config_value(config, key, default) | 在 config 中查找设置值 |
run_lifecycle(FUNCTIONS) | python lifecycle.py <function> 的入口点 |
已启用的扩展可以导入,例如 from extensions.steamcmd import SteamCMD 或 import extensions.ue4_ini。已禁用的扩展会被导入守卫拦截(ModuleNotFoundError),因此请在函数内部导入,失败时应答 extension_required。
6. 参考:内置模块
| 模块 | 默认端口 | 协议 | 所需扩展 | 备注 |
|---|---|---|---|---|
minecraft | 25565 | stdin(控制台) | 无 | download 安装、Java 自动检测/下载、强制关闭 RCON |
palworld | 8211 | REST API | steamcmd、ue4-ini | 没有控制台的游戏。credential_map 映射 rest_password ↔ AdminPassword |
zomboid | 16261 | stdin(控制台) | steamcmd | stop_command = "quit"、[backup] hook = true |
terraria | 7777 | stdin(伪控制台 pty) | xna(Windows) | download 安装、Windows・Linux 服务器、[backup] hook = true |
它们都以 module.toml 和 lifecycle.py 为核心构建。创建新模块时,建议从 __example 或这四个中最接近的一个开始。
7. 开发规则(必须遵守)
模块 PR 必须遵守以下规则。
- 不依赖守护进程代码。 只使用守护进程提供的 config、环境变量和 API。
- 所有失败都返回 JSON + 退出码 0。 用
success: false和原因应答。 - 日志输出到 stderr。 stdout 用于结果 JSON。异常回溯也要打印到 stderr;不要吞掉错误。
- 先用 stdin,再用 REST。 只有两者都没有的游戏才使用 RCON。游戏有控制台或 REST 时,关闭其 RCON 设置,并且不在
supported中加入"rcon"。 - 只通过守护进程给出的
pid处理进程。 按可执行文件名结束进程会连同同一游戏的其他实例一起结束。 - 用
os.path.join构建路径;不要硬编码。 - 核对字段名映射。 在
configure和import_settings中都要确认每个[[settings.fields]]名称对应哪个游戏设置键。 - 测试。 在
test_lifecycle.py中编写单元测试,并通过一致性测试套件(见下文第 8 节)。
8. 调试技巧
- 结果从 stdout 的最后一行读取,因此请把调试输出发送到 stderr。在结果 JSON 之后再打印任何内容都会破坏解析。
- 可以不经守护进程直接运行函数。请将 Saba-chan 仓库的
modules/加入PYTHONPATH,以便找到daemon_rcon。echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command - 用与守护进程相同的解析器检查
module.toml:saba-core module validate <模块文件夹> - 一致性测试套件:
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules(在saba-chan-modules仓库中运行) - 如果 GUI 中不显示进度,请检查 stderr 行是否恰好以
PROGRESS:开头,以及其后的 JSON 是否有效。 - 编辑模块后,也要把更改同步到数据文件夹下的
modules\<name>\,让守护进程使用最新代码。守护进程会缓存模块列表,因此如果修改了module.toml,请用POST /api/modules/refresh让它重新加载。