擴充功能開發指南
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 <函式名稱>,將 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執行測試。