autoSpire — AI 自动爬塔

杀戮尖塔 2 的 AI 自走 mod。嵌入式 HTTP 服务 + MCP 协议，让 Claude Code 驱动游戏决策。

架构

AI (Claude Code) ←─ MCP stdio ─→ mcp/server.py ←─ HTTP ─→ C# GameHookServer (游戏内)

• C# GameHookServer：嵌入游戏进程，主线程每帧刷新状态快照 + 消费 HTTP 动作队列
• Python MCP 适配器：将 HTTP API 封装为 MCP 工具（get_state / take_action），纯透传无业务逻辑
• Godot Mod：[ModInitializer] 入口，注册 Harmony patch + 启动 HTTP 服务

快速开始

前置条件

• Slay the Spire 2
• Python 3.10+
• Claude Code（推荐）、Codex 或 OpenCode

三步上手

① 解压安装

从 Releases 下载 autoSpire-vX.X.X.zip 解压。将 autoSpire/ 放入游戏 mod 目录，然后安装 Python 依赖：

将 autoSpire/ 复制到 <Steam库>\...\Slay the Spire 2\mods\autoSpire\
pip install -r mcp/requirements.txt

解压后结构：

├── .mcp.json              # MCP 配置（Claude Code 打开即用）
├── autoSpire/
│   ├── autoSpire.dll      # Mod 本体
│   └── autoSpire.json     # Mod 清单
└── mcp/
    ├── server.py           # MCP 适配器
    └── requirements.txt    # Python 依赖

② Agent 打开文件夹

解压目录已包含 .mcp.json，Claude Code 打开文件夹即自动发现 MCP Server。

其他 Agent 参照该文件配置即可，本质是注册一个 stdio MCP Server：

{
  "mcpServers": {
    "autospire": {
      "type": "stdio",
      "command": "python",
      "args": ["mcp/server.py"]
    }
  }
}

双人联机：.mcp.json 已内置 autospire2（端口 8766），启动第二个游戏客户端即可双人爬塔。

③ 开始使用

启动游戏，确认日志 [autoSpire] autoSpire mod initialized!，然后在 Agent 中：

> 开始一局标准单机游戏

自行编译

# 修改 autoSpire.csproj 中的 <Sts2Dir> 为游戏路径，然后：
dotnet build

API

GET /state — 游戏状态快照

返回 GameStateSnapshot JSON。根据 phase 字段，仅当前场景对应子快照非 null：

Phase	字段	内容
combat	combat	手牌/能量/敌人(意图+buff)/药水/牌堆计数/卡牌选牌状态
map	map	当前节点 + 下一层可选 + 全地图节点
shop	shop	金币 + 商品列表(卡牌/遗物/药水/删牌)
reward	reward	奖励项列表 + 可选卡牌/遗物
rest	rest	休息选项 + 升级/移除选牌界面
event	event	事件名称/描述/选项(含关联卡牌/遗物预览)
treasure	treasure	宝箱状态/可选遗物/投票
game_over	—	游戏结束结算界面（死亡/通关）
menu	menu	游戏外界面(主菜单/角色选择/子菜单等)

所有阶段均有 run 字段：章节/层数/金币/牌组。

POST /action — 提交动作

返回 ActionResult JSON：

{
  "success": true,
  "error": null,
  "played_card_name": "打击",          // 仅 play_card
  "played_card_target": {              // 仅 play_card
    "type": "enemy",                   // enemy / self / none
    "combat_id": 2,
    "name": "小啃兽"
  },
  "hand_card_selection": { ... },      // 仅 pick_card / confirm_selection
  "card_selection": { ... }            // 仅 pick_card / confirm_selection
}

动作	必填参数	可选参数	说明
play_card	hand_index	target_id	出牌。支持 AOE/随机目标（无需 target_id）。返回 played_card_name + played_card_target
multi_play	cards	—	一次出多张牌。cards 为 [{hand_index, target_id?}] 数组。返回 played_card_name（尝试列表）
end_turn	—	—	结束回合
use_potion	slot_index	target_id	使用药水
pick_card	card_index	—	通用选牌（手牌选择 / overlay 选牌）。返回最新选牌状态
confirm_selection	—	—	确认手牌选择（净化等多选手动确认）
move_to_map_coord	col, row	—	选路线
pick_reward	choice_index, choice_type	card_index	选奖励（card/relic/gold/skip）；有 CardSelection 子界面时传 card_index
rest_action	option_index	card_index	休息点操作
shop_action	—	—	商店操作（buy/remove_card/leave）
treasure_action	—	—	宝箱操作（pick_relic/skip/leave，自动开箱）
event_action	option_index	—	事件选项（支持多人投票、选牌）
menu_action	—	—	游戏外操作：continue_run/singleplayer/multiplayer/standard/daily/custom/select_character/set_ascension/embark/back/abandon_run/confirm/cancel 等

功能状态

已完成 & 已测试（主客机双端）

• 战斗状态获取：手牌(含 Damage/Block/描述)/能量/敌人(HP+意图+buff)/药水(含描述)/牌堆计数/选牌状态
• 出牌：支持有目标(单敌)、自目标(技能/能力)、AOE/随机目标(AllEnemies/RandomEnemy/AllAllies)、卡牌选牌触发(净化/头槌/洁净)
• 批量出牌：multi_play 一次调用打出多张牌，减少 AI 调用次数。两阶段设计（先解析全部 CardModel 引用再入队）避免 index 偏移问题
• 用药水：自目标 + 敌方目标，药水选牌触发(灰水)
• 选牌：Overlay 选牌/手牌选择模式/奖励选牌/商店删牌选牌，描述含正确数值
• 选牌状态即时返回：pick_card 后 ActionResult 含更新后牌列表
• 出牌返回值：played_card_name + played_card_target（含目标类型/ID/名称）
• 地图状态 + 选路线(VoteForMapCoordAction)
• 奖励选择：card/gold/relic/potion/skip
• 休息点：回复/锻造/移除 + 升级/移除选牌界面
• 商店全链路：商品列表（角色卡/无色卡/遗物/药水/删牌含价格库存）+ buy / remove_card / leave（自动开/关界面）
• 事件全链路：事件描述 + 选项（含关联卡牌/遗物预览）+ 单人/合作多人投票 + 事件中选牌 + 古之民事件
• 宝箱房间：宝箱开启 + 遗物选择（单人/多人投票，自动分配）
• 游戏结束检测：死亡/通关后正确识别 game_over 阶段（不再误判为 map）
• 游戏外界面检测：主菜单 / 角色选择 / 单机子菜单 / 多人子菜单 / 建房 / 每日 / 自定义局 / 弹窗等 menu 阶段，20+ 种界面类型识别
• 游戏外操作：menu_action 支持从主菜单到开始游戏全流程（角色选择/进阶设置/每日挑战/自定义局），含放弃存档确认弹窗处理
• 图标清理：[img] 能量/星图标标签自动替换为文字
• Run 级别信息：遗物(名称+描述)、牌组(合并计数)
• JSON 输出优化：省略所有 null 字段，显著减少 token 消耗

多端支持

同一份 MCP 适配器通过 AUTOSPIRE_PORT 环境变量区分：

• autospire（8765）— 主机
• autospire2（8766）— 客机

若端口被占用，GameHookServer 自动递增（最多尝试 10 个端口）。

已知限制

• 出牌异步：play_card 通过 ActionQueueSynchronizer.RequestEnqueue 入队，卡牌选牌触发在后续帧处理，AI 需随后 get_state 检查
• 卡牌选牌触发后手牌索引变化：如净化每选一张牌后手牌索引重排，需依赖 pick_card 返回值中的最新索引
• 卡牌描述：:energyIcons / :starIcons 等特殊 formatter 输出 [img] 标签被替换为文字
• 事件选项：部分动态变量（如 {BatheCurses}）在选项描述中可能未注入，SafeFormat 回退到原始文本
• 多人联机：建房/加入的菜单操作已实现，但实际联网需要 Steam 网络层，尚未在真实多人环境下验证
• multi_play 出牌是异步的：RequestEnqueue 入队后卡牌异步处理，played_card_name 只反映尝试列表而非实际打出结果。AI 应在 multi_play 后紧跟 get_state 确认真实手牌和选牌状态
• multi_play + 选牌触发：若批中包含触发选牌的牌（生存者/净化等），选牌触发后同一批中的后续卡牌会被阻塞。AI 应单独 play_card 处理这类牌，或将它们放在批末尾