前言¶
用智能體驅動本地遊戲時，常見做法是截圖加視覺識別，或腳本模擬點擊。這兩種方式在狀態漂移、動作是否合法、失敗後是否重發上很難給出穩定契約。DeepSeek Harness（DSH）社區裏把工作流類插件當作可複用的「控制面」；若你的 harness 能跑命令、讀 JSON，又需要驅動《殺戮尖塔 2》（Slay the Spire 2，下文 STS2），下面介紹維護者 enderzcx 的 spire-ctl：同一包既是 CLI，也可作爲 DSH 插件掛載原生工具。
這是什麼¶
spire-ctl 是面向 agent harness 的 STS2 控制面：提供 JSON 狀態契約、合法動作清單，以及不重放的執行層。它不截圖、不做視覺識別、不模擬點擊，而是通過本地 Mod 讀取結構化狀態，再調用遊戲原有的動作隊列。
數據流可以概括爲：
你的 agent（任何 harness）
↓ state / act / seq
spire-ctl：合法動作枚舉 → 校驗發送 → 結算覈對
↓ 遊戲原有動作隊列
STS2 本地橋接（Mod）
倉庫：GitHub — enderzcx/spire-ctl。社區目錄頁：skillhub.cn/plugins/enderzcx/spire-ctl。分類爲工作流；當前 package 版本 0.3.0，許可證 MIT，運行時要求 Node.js >= 22。核心實現零 npm 生產依賴；@deepseek-ai/dsh-tools 爲可選 peer 依賴，不裝 DSH 也可單獨用 CLI。
它保證什麼、不承諾什麼¶
價值重點在出錯時的行爲，而不是「能不能自動贏」：
| 保證 | 含義 |
|---|---|
| 拒絕舊狀態 | 狀態一變，舊標識立即失效，不能沿用上一輪的手牌索引 |
| 單寫者鎖 | 同一端口只允許一個操作者；兩個 agent 不會同時出牌 |
| 不自動重試 | 發送失敗或結果無法確認 → 持久停止，等人覈實，絕不重發 |
| 結算覈對 | 每個動作讀回確認；沒確認就不算完成 |
| 非法動作發不出去 | 動作只來自遊戲自己廣告的選項，不自造 ID |
| 算不清就停 | 未知機制、空意圖、無法覆蓋的致命攻擊 → 交回調用方，不猜 |
不是自動通關機器人。 決策歸調用方（或可選的快速決策模型）；spire-ctl 只保證「決定下來的動作被合法、可覈對地執行」。默認沒有取勝策略，也沒有勝率保證。
程序與調用方分工：等待動畫結算、合法性校驗、基於遊戲意圖的算術由程序負責；出哪張牌、路線、構築等由調用方負責；陌生意圖或結果無法確認時程序停下並交回。
安裝與啓用¶
1. DSH 插件（可選但省事）¶
同一包一條命令安裝控制器（同時是 CLI 和 DSH 插件）：
dsh plugin --profile web add github:enderzcx/spire-ctl
裝完後可直接調用 spire_state、spire_act、spire_seq、spire_advance 等原生工具，不必拼 shell。package.json 中 DSH 引擎要求爲 >=0.1.0-rc.1 <0.2.0-0。
安裝後建議體檢：找不到遊戲、Mod 未裝、橋接未起時會說明原因。
node bin/spire.mjs doctor
Mod 是唯一需要寫進遊戲目錄的步驟；doctor --install-mod 會先給計劃、校驗 SHA256，並在遊戲運行時拒絕寫入。
README 還提到：把倉庫內 安裝提示詞 整段複製給 agent，由 agent 自行安裝並驗證。
2. STS2 橋接 Mod（必需）¶
從 sts2-bridge Releases 下載對應平臺包，按包內 INSTALL.txt 放入 Mod 目錄。先關閉遊戲並備份存檔。
驗證橋接是否監聽本機：
curl --noproxy '*' http://127.0.0.1:15526/
# {"message":"Hello from STS2 MCP v0.4.0","status":"ok"}
Mod 只綁定迴環地址；不要把端口轉發到公網。
3. 權限與安全¶
插件與 CLI 以當前 DSH / shell 進程權限運行，會讀寫本地遊戲橋接與運行時文件。安裝前應閱讀源碼與 MIT 許可證；倉庫聲明不包含遊戲程序集、素材、個人存檔或憑據，日誌不含 API key。
典型用法¶
只讀狀態¶
state 不改變遊戲，返回當前局面、可選動作與狀態標識。操作細節見倉庫 docs/AGENT.md。
node bin/spire.mjs state
單步與序列執行¶
node bin/spire.mjs act STATE_ID OPTION_ID
node bin/spire.mjs seq STEPS.json
CLI 命令概覽：
| 命令 | 用途 |
|---|---|
state |
讀狀態、合法動作、路由原因、本次狀態標識 |
act STATE_ID OPTION_ID |
執行一個動作 |
seq STEPS.json |
執行一串已決定的動作，逐步重讀逐步校驗 |
plan PLAN.json |
帶預測的多卡前綴（預測不符即停） |
battle [MAX] [STRATEGY.json] |
可選快速決策模型連續打 |
advance [MAX] |
機械推進（領金幣、對話、固定按鈕） |
clear-halt STATE_ID |
覈實局面後清除停止標記 |
strategy / save-strategy |
查看/保存顯式續行條件 |
逐張 act 時，手牌 card_index 是位置，打掉一張後面索引會漂移。seq 可一次提交整回合，並按卡牌 id 指定，例如：
{
"expected_state_id": "…",
"steps": [
{"card": "FLAME_BARRIER"},
{"card": "TOXIC"},
{"card": "DEFEND_IRONCLAD"},
{"action": "end_turn"}
]
}
每一步從新結算狀態重新匹配遊戲廣告的動作，事務與 act 相同；任一步不再被廣告則序列在打出任何東西之前停下，並返回當時可用動作。非戰鬥界面同樣適用（例如一次買齊商店）。
從終局開新局¶
不碰存檔、設置與多人；menu 只廣告安全動作，abandon_run、quit、multiplayer 等不會出現。
node bin/spire.mjs state # game_over → 只有 main_menu
node bin/spire.mjs act STATE 0 # 回主菜單
# 依次 singleplayer → standard → 選角色 → embark
其他 harness 不裝 DSH 時，照舊使用 node bin/spire.mjs state 等命令；bin/ 與 src/ 不 import DSH 適配器，邊界由 test/boundary.test.mjs 測試守住。
適用場景與注意¶
適合： 已在 DSH 或其他 harness 裏編排 agent，需要 STS2 的結構化狀態與可覈對執行；希望用 seq 減少索引漂移；需要單寫者鎖與失敗即停，而不是靜默重試。
兼容與驗證： README 記錄在 macOS arm64、遊戲 v0.107.1 上驗證。遊戲或上游 Mod API 變化可能導致字段改名，控制器會明確報錯而非靜默繼續；範圍見 docs/VALIDATION.md。離線 npm test 不能代替對着運行中游戲的驗證。
併發： 多處可併發讀，但只能有一個操作者；鎖僅防本項目自身，擋不住手動出牌或其他工具直接操作遊戲。
卸載： 關閉遊戲，移走 Mod，從 Steam 重啓；不要用舊存檔覆蓋新進度。
結尾¶
spire-ctl 把 STS2 收成 JSON 狀態契約加合法動作執行層，讓任意能跑 Node CLI 的 harness 都能驅動同一套覈對流程；在 DSH 裏則多一層原生工具調用。決策仍在你或你的模型，控制面負責合法性與失敗時的可預期停止。
- 目錄頁：https://www.skillhub.cn/plugins/enderzcx/spire-ctl
- 源碼與文檔：https://github.com/enderzcx/spire-ctl
