擴充功能開發指南

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 <函式名稱>,將 context 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 Context 與進入點

掛鉤函式接受一個 context 字典並回傳字典。依掛鉤不同,context 會包含 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. 3 個內建擴充功能

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 以外部參照的方式引用主程式的 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. 開發規則

  • 擴充功能同樣不得依賴常駐程式程式碼。只使用常駐程式傳入的 context 與環境變數。
  • 用 os.path.join 組合路徑;不要寫死。
  • 掛鉤函式的失敗也以 JSON(success: false 與原因)及結束代碼 0 回應,並將記錄與例外追蹤送到 stderr。
  • condition 只使用 instance.ext_data.<key> 形式。其他任何形式都一律評估為 false。
  • Python 相依套件使用常駐程式的共用環境。沒有各擴充功能專屬的 requirements 宣告。
  • 未驗證的擴充功能:不是從已簽章目錄下載的擴充功能,或下載後有變更的擴充功能,會與模組一樣在隔離環境(Windows AppContainer、Linux bubblewrap)中執行。不會進行防毒軟體掃描。以下以 Windows 為準。它們無法連到 loopback(例如常駐程式 API),不會收到 SABA_TOKEN_PATH,且只能讀取實例資料夾。需要寫入的資料請放在 SABA_EXTENSION_DATA_DIR 環境變數所指的專用資料夾中。
  • 在儲存庫根目錄以 pytest 執行測試。