CLI-Anything Slay the Spire 2通过进程内 Bridge Mod 让真实 Steam 游戏 Agent 原生化的完整指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingCLI-Anything-Slay-the-Spire-2是 CLI-Anything 生态中面向Slay the Spire 2杀戮尖塔 2的 CLI 驱动harness它通过在真实 Steam 游戏进程内部署一个.NET 9桥接模组STS2_Bridge将游戏状态通过本地 HTTP API 暴露给命令行从而实现对真实运行中游戏的有状态控制。本文将从工作原理、安装链路、命令体系、源码级实现到排障方法完整讲解如何把这款 Roguelike 卡牌游戏变成Agent 原生的可编程环境。读完本文你将掌握桥接模组的构建与安装、cli-anything-sts2的全部常用命令、15 种归一化决策状态与角色映射、底层 HTTP API 的请求/响应格式以及如何从源码验证每一步的实际行为。工作原理不是模拟器也不是屏幕自动化与 CLI-Anything 中大多数包装独立桌面应用的 harness 不同本项目控制的是真实运行中的游戏本体。它既不使用无头模拟器也不依赖屏幕图像识别与键鼠注入而是采用进程内桥接 本地 HTTP API的架构游戏内桥接模组STS2_Bridge作为 mod 运行在游戏进程内部直接读取游戏的内部状态与动作 API模组在http://localhost:15526/api/v1/singleplayer暴露本地 HTTP 服务CLI 通过该 API 读取归一化状态并回传动作指令。这一架构的完整调用关系见 agent-harness/STS2.md 中的架构图以及桥接模组的说明文档 agent-harness/bridge/plugin/README.md。从源码看HTTP 监听由模组侧在游戏进程中创建BridgeMod.cs中初始化了HttpListener并同时绑定http://localhost:15526/与http://127.0.0.1:15526/两个前缀见 BridgeMod.cs。由于模组运行在游戏进程内部它天然拥有对游戏内部状态和动作 API 的直接访问权因此 CLI 到 HTTP 调用之间的翻译损耗极低——这正是本项目命名为low translation gap的原因。与其他 harness 的本质区别本 harness 无法脱离桥接模组工作模组必须被构建并安装进游戏。构建与安装脚本目前会自动探测默认的 macOS Steam 游戏路径若游戏安装在其他位置需要显式传参或用环境变量覆盖。环境要求与依赖清单依赖版本/说明用途Steam 版Slay the Spire 2已安装即可承载桥接模组的真实游戏本体Python 3.10运行 CLIsetup.py 中python_requires3.10见 setup.py.NET 9 SDK仅构建桥接模组时需要编译STS2_Bridge模组click 8.0.0CLI 唯一运行期依赖见 setup.py需要特别强调的是桥接模组构建脚本会自动探测游戏数据目录若自动探测失败需要设置STS2_GAME_DATA_DIR环境变量或直接传入目录路径。安装与联通从零到state返回 JSON第 1 步安装 CLI从仓库根目录进入 harness 目录并执行可编辑安装cd slay_the_spire_ii/agent-harness pip install -e .该命令会注册cli-anything-sts2控制台命令。入口点定义在 setup.py指向 slay_the_spire_ii_cli.py 中的main函数。第 2 步构建桥接模组cd slay_the_spire_ii/agent-harness/bridge/plugin ./build.sh脚本会尝试自动探测游戏数据目录并把构建产物刷新到本地安装包目录slay_the_spire_ii/agent-harness/bridge/install/bridge_plugin/该目录最终包含两个关键文件STS2_Bridge.dll与STS2_Bridge.jsonmanifest可参考当前仓库中已生成的 bridge_plugin/。若自动探测失败显式传入游戏数据目录STS2_GAME_DATA_DIR/path/to/data_sts2_macos_arm64 ./build.sh注意目标数据目录至少需要包含以下文件构建脚本才能链接成功sts2.dllGodotSharp.dll0Harmony.dll第 3 步安装模组到游戏cd slay_the_spire_ii/agent-harness/bridge/install ./install_bridge.sh默认安装目标为~/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/SlayTheSpire2.app/Contents/MacOS/mods/STS2_Bridge/从 install_bridge.sh 的源码可以看到脚本会创建mods/STS2_Bridge/目录并把STS2_Bridge.dll与STS2_Bridge.json复制进去。若游戏不在默认位置将游戏根目录作为参数传入./install_bridge.sh /path/to/Slay the Spire 2第 4 步在游戏中启用模组启动游戏确认STS2_Bridge已被加载并启用。启用后模组监听http://localhost:15526/模组启动时会在游戏控制台打印类似[STS2 Bridge] v1.0.0 server started on http://localhost:15526/的日志见 BridgeMod.cs可用于确认服务已就绪。第 5 步验证连通cli-anything-sts2 --help cli-anything-sts2 state如果cli-anything-sts2 state返回 JSON说明 CLI 与桥接模组已经正确连通。命令体系详解菜单、战斗、地图与奖励全流程cli-anything-sts2的命令全部由 click 定义在 slay_the_spire_ii_cli.py 中每条命令都映射到 action_adapter.py 里对应的动作 payload 工厂函数。从主菜单开始一局游戏cli-anything-sts2 state cli-anything-sts2 continue-game cli-anything-sts2 start-game --character IRONCLAD --ascension 0 cli-anything-sts2 abandon-game cli-anything-sts2 return-to-main-menustart-game的两个参数在 CLI 源码中均有默认值见 slay_the_spire_ii_cli.py--character默认为IRONCLAD--ascension默认为0。--character当前可识别的角色为角色说明IRONCLAD铁甲战士SILENT静默猎手DEFECT故障机器人NECROBINDER死灵缚者REGENT摄政者一局游戏中的手动控制cli-anything-sts2 state cli-anything-sts2 choose-map 0 cli-anything-sts2 play-card 0 --target jaw_worm_0 cli-anything-sts2 end-turn cli-anything-sts2 claim-reward 0 cli-anything-sts2 pick-card-reward 0 cli-anything-sts2 rest 0 cli-anything-sts2 event 0 cli-anything-sts2最后一条不带子命令的cli-anything-sts2会进入交互式 REPL 模式。从源码看slay_the_spire_ii_cli.pyREPL 会打印 banner支持help、quit/exit并把输入的每一行用shlex切分后以相同参数递归调用 CLI 主入口。常用命令分组速查分组命令状态查看state、raw-state菜单动作continue-game、start-game、abandon-game、return-to-main-menu战斗play-card、use-potion、end-turn地图与房间choose-map、event、advance-dialogue、rest、proceed奖励与覆盖层claim-reward、pick-card-reward、skip-card-reward、select-card、confirm-selection、select-relicplay-card的--target参数用于指定目标实体的entity_id如jaw_worm_0仅在卡牌需要指定任意敌人目标时必须提供use-potion的--target语义相同。两个命令的 payload 构造见 action_adapter.py。完整命令面可通过cli-anything-sts2 --help查看。配置项与源码对应关系CLI 配置参数默认值说明--base-urlhttp://localhost:15526本地桥接 API 基础地址--timeout10.0HTTP 请求超时秒示例cli-anything-sts2 --base-url http://127.0.0.1:15526 --timeout 20 state这两个参数在 slay_the_spire_ii_cli.py 中被注入CliRuntime再传给 HTTP 客户端Sts2RawClient。后者的singleplayer_url属性会拼出{base_url}/api/v1/singleplayer完整端点见 sts2_backend.py。桥接模组构建配置环境变量用途STS2_GAME_DATA_DIR当 build.sh 无法自动探测游戏数据目录时手动指定底层 HTTP API 参考状态读取与动作回传桥接模组暴露两个端点详见 raw_api.mdhttp://localhost:15526/api/v1/singleplayer— 单机模式http://localhost:15526/api/v1/multiplayer— 多人合作模式两个端点互斥在多人对局中调用单机端点反之亦然会返回 HTTP 409。这些端点面向本地使用设计没有认证或安全措施不应暴露到公网。GET /api/v1/singleplayer查询参数参数取值默认值说明formatjson、markdownjson响应格式返回的state_type字段标识当前所在界面monster/elite/boss战斗中、hand_select战斗内选牌、combat_rewards战后奖励、card_reward选卡奖励、map地图、rest_site休息点、shop商店、event事件/Ancient、card_select牌组选卡、relic_select遗物选择、treasure宝箱房、overlay兜底覆盖层防止卡死、menu无对局进行中。CLI 侧的state命令会通过 state_adapter.py 的normalize_state把上述原始状态进一步归一化为 15 种决策状态menu·combat_play·hand_select·map_select·game_over·combat_rewards·card_reward·event_choice·rest_site·shop·card_select·relic_select·treasure·overlay·unknown每种决策状态会附带统一格式的type、decision、context含act、floor、ascension与run字段并针对各自界面抽取关键决策数据——例如战斗状态会包含energy、hand、enemies、三堆牌库计数等方便 Agent 直接依据归一化 JSON 做决策而不必解析原始结构。raw-state命令则直接透传桥接模组的原始 JSON用于排查或调试。POST /api/v1/singleplayer请求体为 JSONaction字段标识动作名。以下为核心动作及参数语义动作关键参数说明play_cardcard_index手牌 0 基索引、target出牌target对AnyEnemy卡牌必填自目标/群体卡可省略use_potionslot药水槽索引、target使用药水target对AnyEnemy药水必填end_turn无结束回合combat_select_cardcard_index战斗内选择要消耗/丢弃的卡时选中卡牌combat_confirm_selection无确认战斗内卡牌选择需确认按钮可用claim_rewardindex领取战后奖励金币/药水/遗物即时领取卡牌奖励会进入card_reward界面select_card_rewardcard_index从卡牌奖励中加入牌组skip_card_reward无跳过卡牌奖励proceed无从奖励界面、休息点、商店自动关闭货架、宝箱房前进到地图事件界面请用choose_event_optionchoose_rest_optionindex休息点选项休息回血、锻造升级卡牌、遗物附加选项shop_purchaseindex购买商店物品需有货且买得起自动打开货架choose_event_optionindex普通事件与 Ancient 事件对话后选项advance_dialogue无点击 Ancient 事件对话需反复调用直到in_dialogue为falsechoose_map_nodeindex依据地图状态的next_options索引选择节点select_cardindex选卡界面变形/升级/移除等格子界面为切换选中选卡类界面即时选择confirm_selection无确认当前选卡升级/变形预览或主确认按钮选卡类界面无需调用cancel_selection无预览时返回格子选卡类界面点击跳过若可用否则关闭选卡界面select_relicindexBoss 遗物选择即时选择skip_relic_selection无跳过遗物选择claim_treasure_relicindex领取宝箱房已揭示的遗物宝箱在查询状态时自动开启continue_game/abandon_game/return_to_main_menu无菜单层对局管理start_new_gamecharacter、ascension从主菜单开启新对局所有错误响应统一返回{ status: error, error: Description of what went wrong }CLI 侧的 HTTP 客户端在收到非 JSON 响应或连接失败时会抛出带可读信息的ApiError见 sts2_backend.py例如无法连接游戏桥接 API游戏是否在运行且已启用桥接模组。从源码看 CLI 的执行链路一条命令的完整执行链路可以概括为用户输入cli-anything-sts2 play-card 0 --target jaw_worm_0click 解析参数后调用play_card命令处理器slay_the_spire_ii_cli.py_run_post从actions.play_card(card_index, target...)取得 payloadaction_adapter.py弹出action键后调用client.post_action(action, **payload)Sts2RawClient.post_action将action与其余字段合并为请求体POST 到单机端点sts2_backend.py响应以缩进 JSON 打印到标准输出。state命令则先通过get_state(formatjson)拉取原始状态再交给normalize_state归一化后输出。另外action命令提供了透传通道cli-anything-sts2 action name --kv keyvalue会把任意动作名和键值对原样 POST 给桥接模组--kv的值会自动做类型推断整数、布尔、字符串便于在 CLI 尚未覆盖新动作时应急使用见 slay_the_spire_ii_cli.py 与 action_adapter.py 的from_name注册表。Troubleshooting常见问题与处理cli-anything-sts2 state无法连接这通常意味着以下条件之一尚未满足游戏没有在运行STS2_Bridge未安装或未启用localhost:15526上的本地 API 尚未就绪。可以先在游戏内确认模组日志已打印server started再重试命令若端口被占用或地址有异可通过--base-url指向http://127.0.0.1:15526显式指定。build.sh找不到游戏目录确认游戏已安装然后显式传入数据目录STS2_GAME_DATA_DIR/path/to/data_sts2_macos_arm64 ./slay_the_spire_ii/agent-harness/bridge/plugin/build.sh安装脚本报插件文件缺失install_bridge.sh 会校验安装包内是否存在STS2_Bridge.dll与STS2_Bridge.json。若缺失说明尚未执行构建步骤先运行../plugin/build.sh生成安装包再重试。相关文档与进一步阅读agent-harness/STS2.md项目专属架构分析与 SOP含完整的桥接架构图、核心领域模块表与决策状态清单。agent-harness/bridge/plugin/README.md桥接模组的构建与安装说明。agent-harness/bridge/plugin/docs/raw_api.md原始 HTTP API 全量参考含单机/多人两种模式、全部动作与状态字段细节。agent-harness/cli_anything/slay_the_spire_ii/slay_the_spire_ii_cli.pyCLI 全部命令定义与 REPL 实现。agent-harness/cli_anything/slay_the_spire_ii/skills/SKILL.md面向 Agent 的安装与使用技能描述。agent-harness/setup.py包元数据、依赖与cli-anything-sts2入口点定义。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考