前言¶
用智能体驱动本地游戏时，常见做法是截图加视觉识别，或脚本模拟点击。这两种方式在状态漂移、动作是否合法、失败后是否重发上很难给出稳定契约。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
