用 CLI 驱动《杀戮尖塔 2》实战：cli-anything-slay-the-spire-ii 有状态命令行桥接指南

用 CLI 驱动《杀戮尖塔 2》实战cli-anything-slay-the-spire-ii 有状态命令行桥接指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇技术指南围绕开源仓库 CLI-Anything 中slay_the_spire_ii/agent-harness子项目的核心文档展开系统讲解如何通过cli-anything-sts2命令行工具与正在运行的《Slay the Spire 2》Steam 版游戏进程交互读取归一化游戏状态、下发战斗/地图/奖励/事件等动作命令并将这套接口开放给 AI Agent 使用。读完本文你将掌握该 CLI 的全部命令用法、决策状态机路由逻辑、底层 HTTP 桥接原理以及面向 Agent 的编程式调用规范。一、项目定位从桥接 Mod到状态化命令行与 CLI-Anything 生态中大多数通过子进程包装桌面应用的 harness 不同slay_the_spire_ii 采用了一条独特的路径它直接与一个运行在游戏进程内的.NET桥接 ModSTS2_Bridge通信。该 Mod 在本地暴露 HTTP API默认http://localhost:15526CLI 通过该 API 读取归一化后的游戏状态并发送动作命令。也就是说这套方案是状态化的每次命令执行后游戏状态都会变化CLI 需要随时重新读取状态再做下一步决策。┌────────────────────────────────────────────┐ │ Slay the Spire 2 (Steam) │ │ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │ │ Combat │ │ Map │ │ Menu │ │ │ └─────┬────┘ └────┬─────┘ └────┬────┘ │ │ │ │ │ │ │ ┌─────┴─────────────┴─────────────┴─────┐ │ │ │ STS2_Bridge (.NET mod) │ │ │ │ Reads game state, executes actions │ │ │ └──────────────────┬────────────────────┘ │ │ │ │ │ http://localhost:15526 │ └─────────────────────┼──────────────────────┘ │ ┌─────────────┴────────────────┐ │ cli-anything-sts2 │ │ state · play-card · rest … │ └──────────────────────────────┘上述架构图与核心域划分详见 STS2.md。桥接 Mod 直接访问游戏内部状态与动作 API因此 CLI 到 HTTP 调用的翻译损耗很低Low Translation Gap唯一前提是游戏必须以启用STS2_BridgeMod 的状态运行并监听localhost:15526。二、安装与前置条件2.1 通过 PyPI 安装 CLIpip install cli-anything-slay-the-spire-ii安装包在 setup.py 中声明了控制台入口cli-anything-sts2其实现指向cli_anything.slay_the_spire_ii.slay_the_spire_ii_cli:main。从源码看该包还声明了以下关键元数据依赖click8.0.0命令行框架Python 版本要求3.10已声明兼容 3.10/3.11/3.12开发依赖pytest7.0.0、pytest-cov4.0.0打包数据随包携带skills/*.md即 AI Agent 的 SKILL 定义如果希望从仓库源码进行开发安装可进入slay_the_spire_ii/agent-harness目录后执行pip install -e .。2.2 前置条件清单前置条件说明Python 3.10CLI 运行环境Slay the Spire 2Steam游戏本体STS2_BridgeMod需在 Mod 管理器中安装并启用.NET 9 SDK仅在需要自行编译桥接 Mod 时用到桥接 Mod 编译与安装的详细说明位于 skills/SKILL.md包内随附的 Agent 技能定义以及 bridge 目录 下。若游戏数据目录无法被构建脚本自动探测可通过环境变量STS2_GAME_DATA_DIR显式指定路径。2.3 连通性验证启动游戏并启用 Mod 后运行cli-anything-sts2 state如果命令返回一段 JSON说明 CLI 与桥接 Mod 已成功连通。三、基本命令与交互模式# 显示所有可用命令 cli-anything-sts2 --help # 进入交互式 REPL 模式默认行为 cli-anything-sts2 # 读取归一化游戏状态含 decision 字段 cli-anything-sts2 state # 读取桥接插件原始 JSON cli-anything-sts2 raw-statecli-anything-sts2不带子命令时默认进入 REPL。从 slay_the_spire_ii_cli.py 的源码可以看到cli是一个invoke_without_commandTrue的 Click group当没有子命令被调用时会自动invoke(repl)。显式的repl子命令同样保留可用。REPL 会话示例cli-anything-sts2 # slay_the_spire_ii [http://localhost:15526] ❯ state # slay_the_spire_ii [http://localhost:15526] ❯ play-card 0 --target jaw_worm_0 # slay_the_spire_ii [http://localhost:15526] ❯ end-turn # slay_the_spire_ii [http://localhost:15526] ❯ exitREPL 内部把输入行经shlex.split拆分为参数后递归调用cli.main以--base-url和--timeout注入当前会话配置因此 REPL 内可用命令与命令行完全一致。它还支持help展示命令快捷说明、quit/exit退出遇到Ctrl-C/Ctrl-D会优雅打印告别信息相关实现见 utils/repl_skin.py 中的ReplSkin接口统一横幅、提示符、配色与错误输出。四、命令组全景详解以下命令均继承自原文档并结合源码slay_the_spire_ii_cli.py 与 core/action_adapter.py补充了实际请求载荷说明。4.1 状态检查State Inspection命令描述底层调用state打印带decision字段的归一化游戏状态get_state(formatjson)normalize_stateraw-state打印桥接插件的原始 JSONget_state(formatjson)原样输出4.2 主菜单Main Menu命令描述请求载荷continue-game继续存档局{action: continue_game}start-game --character IRONCLAD --ascension 0开启新对局{action: start_new_game, character: ..., ascension: ...}abandon-game放弃当前存档{action: abandon_game}return-to-main-menu从任意界面返回主菜单{action: return_to_main_menu}--character支持的值取自 skills/SKILL.md 与 STS2.mdIRONCLAD、SILENT、DEFECT、NECROBINDER、REGENT。--ascension为整数默认 0。4.3 战斗Combat命令描述请求载荷play-card index [--target enemy_id]从手牌打出指定索引的牌{action: play_card, card_index: ..., [target: ...]}use-potion slot [--target enemy_id]使用指定槽位的药水{action: use_potion, slot: ..., [target: ...]}end-turn结束当前回合{action: end_turn}值得注意的源码细节在 action_adapter.py 中play_card与use_potion只有在显式传入target时才会在载荷中携带target字段否则省略——该行为由单元测试test_play_card_without_target_omits_target_field明确锁定。4.4 地图与房间流转Map Room Flow命令描述请求载荷choose-map index选择地图节点{action: choose_map_node, index: ...}proceed离开当前房间{action: proceed}4.5 奖励Rewards命令描述请求载荷claim-reward index领取战斗奖励{action: claim_reward, index: ...}pick-card-reward index选取卡牌奖励{action: select_card_reward, card_index: ...}skip-card-reward跳过卡牌奖励{action: skip_card_reward}claim-treasure-relic index领取宝藏房遗物{action: claim_treasure_relic, index: ...}select-relic index选择遗物{action: select_relic, index: ...}skip-relic-selection跳过遗物选择{action: skip_relic_selection}4.6 事件与休息点Events Rest Sites命令描述请求载荷event index选择事件选项{action: choose_event_option, index: ...}advance-dialogue推进纯对话事件{action: advance_dialogue}rest index选择篝火行动{action: choose_rest_option, index: ...}4.7 商店Shop命令描述请求载荷shop-buy index购买商店物品{action: shop_purchase, index: ...}4.8 卡牌/遗物选择浮层Card/Relic Selection Overlays命令描述请求载荷select-card index在浮层中选择卡牌{action: select_card, index: ...}confirm-selection确认当前选择{action: confirm_selection}cancel-selection取消/跳过当前选择{action: cancel_selection}combat-select-card index战斗中浮层选牌{action: combat_select_card, card_index: ...}combat-confirm-selection确认战斗选牌{action: combat_confirm_selection}4.9 原始动作Raw Action命令描述请求载荷action name --kv keyvalue发送任意原始动作并附带载荷{action: name, ...键值对}--kv可多次传入格式为keyvalue。从 slay_the_spire_ii_cli.py 的_parse_kv_pairs/_coerce_value源码可知值会自动做类型推断纯数字含负号转为inttrue/false忽略大小写转为布尔值其余保持字符串。此外action_adapter.py 中的from_name工厂对所有已知动作名做了注册表分发遇到未知动作名会抛出ValueError(Unknown action name: ...)测试用例test_from_name_dispatches_and_rejects_unknown_actions验证了这一点。五、决策状态机状态驱动路由这是整套方案最核心的设计state命令返回的 JSON 中带有decision字段标识当前游戏画面类型Agent 或脚本应当根据它路由下一步命令。15 种决策类型如下完整映射见 skills/SKILL.md 与 state_adapter.py决策值含义典型下一步命令menu主菜单continue-game、start-gamecombat_play战斗中你的回合play-card、use-potion、end-turnhand_select卡牌选择浮层战斗中combat-select-card、combat-confirm-selectionmap_select地图节点选择choose-mapgame_over对局结束return-to-main-menucombat_rewards战后奖励claim-reward、proceedcard_reward卡牌奖励选择pick-card-reward、skip-card-rewardevent_choice事件界面event、advance-dialoguerest_site篝火restshop商店界面shop-buy、proceedcard_select卡牌选择界面select-card、confirm-selectionrelic_select遗物选择select-relic、skip-relic-selectiontreasure宝藏房claim-treasure-relic、proceedoverlay通用浮层视overlay内容而定unknown未知状态回退读取raw-state排查从源码看state_adapter.py 的normalize_state根据原始状态中的state_type分发到 14 个归一化函数每个函数产出结构化的字段战斗状态monster/elite/boss归一化为combat_play包含round、turn、is_play_phase、energy、max_energy、hand手牌列表、enemies敌人列表、draw_pile_count/discard_pile_count/exhaust_pile_count三堆计数并保留room_type区分普通怪/精英/Boss商店状态额外按category将物品分组为cards、relics、potions与card_removal见_normalize_shopstate_adapter.py每个归一化结果都携带context字段act、floor、ascension方便 Agent 感知进度上下文。对应测试见 tests/test_core.py例如test_normalize_combat_state构造一段原始战斗 JSON断言归一化后decision combat_play、room_type monster、energy 3、手牌首张牌名为Strike、敌人 ID 为slime_0test_normalize_shop_state_groups_items则验证商店物品的分类分组行为。六、配置参数选项默认值描述--base-urlhttp://localhost:15526桥接 Mod API 地址--timeout10.0HTTP 超时时间秒配置项定义于 slay_the_spire_ii_cli.py。--timeout为浮点类型两个参数会在 REPL 会话中持续注入到每条内部命令且 REPL 提示符会实时显示当前base-url如slay_the_spire_ii [http://localhost:15526] ❯。七、HTTP 桥接底层原理CLI 与游戏的通信完全由 utils/sts2_backend.py 中的Sts2RawClient承担实现细节值得展开端点GET/POST {base_url}/api/v1/singleplayerbase_url会被rstrip(/)规范化读状态get_state(formatjson)发起GET并附加formatjson查询参数返回解析后的 JSON 对象非 json 格式则返回原始文本发动作post_action(action, **payload)将action与其余载荷合并为{action: ..., ...}后POST到同一端点请求体以 UTF-8 JSON 发送并携带Content-Type: application/json错误语义HTTPError会抛出ApiError携带 HTTP 状态码与响应体摘要URLError连接失败会抛出提示语无法连接游戏桥接 API请确认游戏正在运行且桥接 Mod 已启用非 JSON 或非对象响应也会被显式拒绝。这套后端设计保证了 CLI 与游戏进程之间唯一的硬依赖就是桥接 HTTP 服务可达。八、面向 AI Agent 的编程式使用规范原文档针对 Agent/脚本调用给出了五条纪律这也是将 CLI 接入自动化决策循环时的关键约束每次先读state任何决策前先执行state获取当前decision字段明确处于哪个界面检查返回码返回码 0 表示成功非 0 表示出错务必据此判断命令是否生效解析 stdout 中的 JSON所有状态与动作命令均以 JSON 输出到 stdout由_print_json使用indent2输出slay_the_spire_ii_cli.py脚本可直接结构化消费每次动作后重新读取状态战斗过程中手牌索引与能量会实时变化上一次读到的手牌索引在下一次可能已失效文件操作使用绝对路径避免工作目录不一致导致路径解析失败。包内还随附了专为 Agent 设计的 skills/SKILL.md其 frontmatter 中定义了技能名cli-anything-sts2与描述使 AI 客户端如 Claude Code 类工具能够自动发现并正确调用这套 CLI。九、完整实战流程9.1 开启新对局cli-anything-sts2 start-game --character IRONCLAD --ascension 0 cli-anything-sts2 state9.2 打一场战斗cli-anything-sts2 state # 检查游戏状态 cli-anything-sts2 play-card 0 --target jaw_worm_0 # 打出第一张牌并指定目标 cli-anything-sts2 state # 出牌后重新检查状态 cli-anything-sts2 end-turn # 结束回合9.3 地图与事件导航cli-anything-sts2 choose-map 0 # 选择地图节点 cli-anything-sts2 event 1 # 选择事件选项 cli-anything-sts2 rest 0 # 篝火休息9.4 交互式 REPL 会话cli-anything-sts2 # slay_the_spire_ii [http://localhost:15526] ❯ state # slay_the_spire_ii [http://localhost:15526] ❯ play-card 2 # slay_the_spire_ii [http://localhost:15526] ❯ end-turn # slay_the_spire_ii [http://localhost:15526] ❯ exit十、源码结构一览cli_anything/slay_the_spire_ii/ ├── __init__.py # 版本号 __version__ 1.0.0 ├── __main__.py # python3 -m cli_anything.slay_the_spire_ii 入口 ├── slay_the_spire_ii_cli.py # CLI 入口Click 默认 REPL ├── core/ │ ├── __init__.py │ ├── action_adapter.py # 动作载荷工厂 from_name 分发 │ ├── state_adapter.py # 原始状态 → 归一化状态映射 │ └── types.py # JsonDict 别名、PlannedAction 数据类 ├── utils/ │ ├── __init__.py │ ├── sts2_backend.py # 桥接 API 的 HTTP 客户端 │ └── repl_skin.py # 共享 REPL 界面横幅/提示符/着色 ├── skills/ │ └── SKILL.md # AI Agent 技能定义 └── tests/ ├── test_core.py # action_adapter 与 state_adapter 单元测试 └── test_full_e2e.py # 端到端测试其中__main__.py支持以模块方式直接运行python3 -m cli_anything.slay_the_spire_ii与 console script 等价core/types.py定义了JsonDict dict[str, Any]类型别名与PlannedAction数据类含action、payload、reason三字段用于规划阶段描述动作意图。十一、更多参考架构分析与 SOPSTS2.mdCLI-Anything 整体方法论HARNESS.md包级说明与技能定义skills/SKILL.md当前仓库内该模块版本为1.0.0定义于init.py。综上所述cli-anything-sts2通过游戏内桥接 Mod 本地 HTTP API 归一化决策状态的架构把一款原生 Steam 游戏完整地纳入了命令行与 AI Agent 的可编程控制范围是 CLI-Anything 生态中极具代表性的游戏自动化 harness。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考