模块开发指南

如何构建为 Saba-chan 添加新游戏的 Python 模块。涵盖 module.toml 规范以及 lifecycle.py 的实际函数约定与协议。

模块开发指南(Python)

Saba-chan 守护进程并不了解各个游戏的具体细节。每款游戏都由一个 Python 模块 来描述。添加一个模块,Saba-chan 就能管理一款新游戏。

本文档基于 saba-chan-modules 仓库中的实际模块(minecraft、palworld、zomboid)、带注释的模板 __example 以及守护进程代码。


1. 模块文件结构

%APPDATA%\saba-chan\modules\<module_name>\
  • 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 的项目是创建新服务器时选择的值(服务器类型、新世界设置等),由创建界面、网页和 CLI server 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
commandmethod = "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 中。概括如下:

  1. 使用守护进程管理的 Python 环境启动 python lifecycle.py <函数名>。
  2. 注入的环境变量:
    • PYTHONIOENCODING=utf-8、PYTHONUNBUFFERED=1
    • PYTHONPATH:存放共享文件(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)
  3. 向 stdin 写入一个 config JSON 对象后关闭。
  4. 将整个 stdout 解析为 JSON;如果失败,则使用最后一个非空行作为结果。
  5. stderr 是日志。以 PROGRESS: 开头的行会被解析为进度事件,用于显示安装进度。
  6. 退出码必须为 0。 否则即使 stdout 中包含 success: false,守护进程也会将此次调用视为一般错误。
  7. 每次调用后进程都会退出。默认时限为 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. 参考:内置模块

模块默认端口协议所需扩展备注
minecraft25565stdin(控制台)无download 安装、Java 自动检测/下载、强制关闭 RCON
palworld8211REST APIsteamcmd、ue4-ini没有控制台的游戏。credential_map 映射 rest_password ↔ AdminPassword
zomboid16261stdin(控制台)steamcmdstop_command = "quit"、[backup] hook = true
terraria7777stdin(伪控制台 pty)xna(Windows)download 安装、Windows・Linux 服务器、[backup] hook = true

它们都以 module.toml 和 lifecycle.py 为核心构建。创建新模块时,建议从 __example 或这四个中最接近的一个开始。


7. 开发规则(必须遵守)

模块 PR 必须遵守以下规则。

  1. 不依赖守护进程代码。 只使用守护进程提供的 config、环境变量和 API。
  2. 所有失败都返回 JSON + 退出码 0。 用 success: false 和原因应答。
  3. 日志输出到 stderr。 stdout 用于结果 JSON。异常回溯也要打印到 stderr;不要吞掉错误。
  4. 先用 stdin,再用 REST。 只有两者都没有的游戏才使用 RCON。游戏有控制台或 REST 时,关闭其 RCON 设置,并且不在 supported 中加入 "rcon"。
  5. 只通过守护进程给出的 pid 处理进程。 按可执行文件名结束进程会连同同一游戏的其他实例一起结束。
  6. 用 os.path.join 构建路径;不要硬编码。
  7. 核对字段名映射。 在 configure 和 import_settings 中都要确认每个 [[settings.fields]] 名称对应哪个游戏设置键。
  8. 测试。 在 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 让它重新加载。