hearthstone-cli — Hearthstone CLI Toolbox for AI Agents

面向 AI Agent 的炉石传说命令行工具箱，双核心：组卡（校验 / 编解码 / 筛卡 / 卡组库存档 / 版本体检 / 长图）+ 对局分析（解析客户端日志输出实时对局面板与战况回放，监听对局触发 AI 军师）。

A command-line toolbox for Hearthstone designed for AI agents, with two cores: deck building (validation, encoding, decoding, filtering, archiving, deck images) and match analysis (real-time board state & action replay parsed from client logs, plus an AI-counselor watcher).

English | 简体中文

---

人类的组卡模拟器解决的是"可视化拖卡"，而 Agent 组卡需要的是秒级试错：列 30 张卡 → 校验 → 出卡组代码 → 按报错修正 → 再来一轮。对局中 Agent 需要的则是结构化的完整战况：不是看一张截图，而是拿到双方状态、场面、手牌与逐回合行动的可解析文本。这两个问题，这个工具各给了一个答案。

功能特性

• 卡组代码编解码 — 完整支持炉石 deckstring 格式（含副牌库三元组），并对营地等平台在标准代码后附加的扩展字节做了容错
• 构筑规则校验 — 数量、同名限量（普通 2 张 / 传说 1 张）、职业限定、标准池白名单
• 动态卡组容量 — 裂魂者阿扎莉娜（套牌 20 张）、时空大盗拉法姆（40 张且恰含 10 张拉法姆）、常规 30 张
• 副牌库 — 乐队经理精英牛头人酋长的 3 张乐队，编码为 sideboard 三元组
• 多职业与游客机制 — 按 classes 数组识别多职业卡（如六职业共用的灭世者死亡之翼），并完整实现胜地历险记游客三条规则：游客仅解锁目的地职业的该扩展卡牌、每套限一名游客、不可嵌套
• 卡组库与版本体检 — 卡组本地存档，版本更新后一键体检，退环境卡逐条列出
• 卡组长图 — 一条命令把卡组渲染成可分享的卡组长图（中/英版各自独立）：法力曲线、稀有度配色（默认逐张列出，--merge 合并同名卡）、职业徽记、英雄与卡组代码，2x 渲染输出 1520px 宽，调用本地无头 Chrome/Edge
• 对局面板 — 解析炉石客户端日志 Power.log 全量重放，输出结构化实时面板：对局模式、总手数/回合/当前行动方、双方法力（含过载锁定）与先后手（后手标注硬币）、双方英雄血甲武器技能（含灌注/变形后的技能变更）、场面随从与地标（嘲讽/圣盾/风怒/冻结/休眠/金卡等状态标注）、我方手牌费用攻血（含兆示预览与已强化/不可打出标注）、双方牌库剩余/疲劳/尸体数、任务进度（与奥秘分流显示）、终局胜负与结束方式（斩杀/投降/疲劳）
• 战况回放 — 行动回顾事件流按回合重放双方每一步：出牌（附效果描述与战吼目标）、攻击（附目标与实际伤害）、英雄技能、抽弃牌、换牌保留替换、开局触发效果（如复制传说洗入牌库列全卡名）、亡语与触发结算（召唤带来源、伤害标致命、复生、治疗带来源）、发现/灾变类选择、预备减费、休眠囚禁与苏醒、亡语亮牌（区分已施放/仅亮出）、回合结束获得（带来源）、手牌满烧牌（报卡名），同名合并防刷屏；AI 无需查库即可理解新卡
• 军师监听 — hs watch 后台监听 Power.log，换牌阶段和轮到我方回合时向自建 IM 桥接器推送固定提示词，触发 AI 军师分析对局
• 对 Agent 友好 — 纯 JSON 输入、报错逐条列出便于自我修正、无任何交互式提示
• 本地双语卡牌库 — 中英双语卡牌数据源自 HearthstoneJSON，补丁日一条命令刷新

持续维护

本项目处于活跃维护状态：炉石每个新版本（扩展包 / 平衡补丁）上线后，会同步更新本地标准卡牌库与标准池白名单，卡组体检随版本跟进。若数据源变更导致问题，欢迎提 issue。

安装

要求：Python 3.10+（Windows / macOS / Linux）

hs image 另需本机安装 Chrome 或 Edge（自动探测，可用环境变量 CHROME_PATH 指定）。

git clone https://github.com/OstrichHermit/hearthstone-cli.git
cd hearthstone-cli
pip install .

开发模式用 pip install -e .（改动源码即时生效）。PyPI 发布：Coming soon。

数据目录默认 ~/.hearthstone-cli/（卡牌库、卡组库、卡组图都存这里），可用环境变量 HS_DECK_HOME 覆盖。装好后先跑一次 hs update 下载卡牌库。

安装为 Agent Skill（可选）

仓库内附带 Agent Skill（skills/hs-deck/SKILL.md），把它复制到你所用 AI Agent 的 skills 目录，Agent 即可自动掌握本工具的用法。以 Claude Code 为例：

cp -r skills/hs-deck ~/.claude/skills/hs-deck

用法

# 刷新卡牌库（自动下载最新中文+英文 collectible 卡及中文全量库，全量库含英雄技能/token 供对局面板查名与描述）
hs update

# 筛卡
hs filter --class=战士 --set=CORE --cost=<=3 --text=嘲讽

# 解码卡组代码
hs decode AAECAQcGo6AE...

# 校验并输出卡组代码
hs validate deck.json

# 卡组入库（支持代码或网页 URL）
hs save my-deck AAECAQcGo6AE...
hs save from-web https://example.com/deck-page

# 查看卡组库
hs list
hs show my-deck

# 版本更新后体检（省略名字 = 检查全部）
hs check

# 生成卡组长图
hs image my-deck                          # 按卡组库名字
hs image AAECAQcGo6AE... --name=Turtle    # 直接给代码
hs image my-deck --lang=en                # 英文版（--lang=both 一次出中英两版）
hs image my-deck --merge                  # 同名卡合并为一行
hs image my-deck --name=龟甲防战 --name-en=Turtle Warrior

# 解析当前对局面板（默认自动发现最新日志：游戏目录 Logs 下 Hearthstone_* 子目录及标准目录）
hs board
hs board --log=D:\games\Hearthstone\Logs\Power.log   # 指定日志路径（也可指向日志目录自动发现）
hs board --player=鸵鸟居士                            # 自动判定我方不准时手动指定

# 军师监听：换牌阶段/轮到我方回合时，向 IM 桥接器 POST 提示词触发 AI 分析
hs watch start --channel=<Discord频道ID> --token=<桥接器token>   # 默认 --log=auto 自动发现
hs watch status                                      # 查看运行状态与最近触发事件
hs watch stop

标准卡组含非标准池卡时默认拦截不出图，--force 可强制渲染。

deck.json 格式：

{
  "format": "standard",
  "hero": "加尔鲁什·地狱咆哮",
  "cards": { "斩杀": 2, "#69535": 1 },
  "sideboard": { "owner": "乐队经理精英牛头人酋长", "cards": { "蓝鳃战士": 2 } }
}

卡名或 #dbfId 均可，副牌库可选。

报错逐条输出，Agent 可以按条机械修正：

校验失败:
  - 套牌必须30张, 当前27张
  - 奇利亚斯豪华版3000型 的系列 WHIZBANGS_WORKSHOP 不在当前标准池

hs board 输出的对局面板长这样（真实对局快照，对手昵称已脱敏）：

=== 炉石对局面板 ===
休闲·标准 | 构建号 253216
总第 17 手 | 我方第 9 回合 | 我的回合 | 我的法力 9/9（已用 0）
对方：遛弯的树懒（牧师）[后手+硬币] 手牌 10 奥秘 0 牌库 17 尸体 5 疲劳 0 法力 3/8（已用 5）
英雄：情报掮客拉祖尔 血 28/30 护甲 0 武器 无 技能 月亮的祝福(已用)
对方场面(2)：
  1. 逐月幼龙 3/6 [金]
  2. 凯洛斯的蛋 0/3
我方：鸵鸟居士（战士）[先手] 奥秘 0 牌库 23 尸体 4 疲劳 0
英雄：麦格尼·铜须 血 30/30 护甲 5 武器 无 技能 全副武装！(未用)
任务 走进失落之城 8/10
我方场面(3)：
  1. 破链灾星霍格 10/10 [嘲讽]
  2. 奥卓克希昂 6/4
  3. 拉格纳罗斯的士兵 2/1
我方手牌(6)：
  1. 屠灭 6费 法术
  2. 龟甲旋风 4费 法术
  3. 拉格纳罗斯，绝世烈火 8费 8/8 随从 <兆示：拉格纳罗斯之手>
  4. 放出鳄鱼 2费 法术
  5. 强固 3费 法术
  6. 为了荣耀！ 3费 法术
=== 行动回顾 ===
[第 14 回合·对方] 抽牌 1 张
[第 14 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌，其法力值消耗减少（>
[第 14 回合·对方] 选择：受伤的侍者
[第 14 回合·对方] 获得 受伤的侍者
[第 14 回合·对方] 打出 随从「受伤的侍者」 [金] 3/8<吸血。战吼：对本随从造成4点伤害。>
[第 14 回合·对方] 受伤的侍者效果 治疗 对方英雄 血28→30
[第 14 回合·对方] 打出 随从「凯洛斯的蛋」 0/3<亡语：召唤一枚轻微开裂的蛋。（破壳5次即可孵化为一只20/20并具有嘲讽的野兽！）>
[第 15 回合·我方] 抽牌 强固<获得3点护甲值。对一个敌方随从造成等同于你护甲值的伤害。>
[第 15 回合·我方] 打出 随从「破链灾星霍格」 10/10<嘲讽。对战开始时：复制你套牌中所有其他传说卡牌。>
[第 15 回合·我方] 攻击：奥卓克希昂 6/7 → 受伤的侍者 3/4
[第 15 回合·我方] 死亡：受伤的侍者 3/0
[第 15 回合·我方] 攻击：拉格纳罗斯的士兵 2/1 → 对方英雄
[第 16 回合·对方] 抽牌 1 张
[第 16 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌，其法力值消耗减少（>
[第 16 回合·对方] 选择：逐月幼龙
[第 16 回合·对方] 获得 逐月幼龙
[第 16 回合·对方] 打出 随从「逐月幼龙」 [金] 3/6<扰魔。在你的回合结束时，随机获取一张龙牌。>
[第 16 回合·对方] 获得 1 张牌（逐月幼龙效果获得）
[第 17 回合·我方] 抽牌 为了荣耀！<抽两张牌。你的对手每控制一个随从，本牌的法力值消耗便减少（1）点。>
# 实体总数 103 | 解析起始行 2 | 日志总行 12200

对局面板与军师监听（board / watch）

质量保障：board 的解析覆盖经过多轮真实对局的全量审计与逐项回归验收（数值对账、事件溯源、特殊局样本如秒投/截断/英雄牌变形）。炉石日志格式随版本变动，若新版出现解析问题，欢迎提 issue 或直接 PR。

hs board 从日志里最后一个 CREATE_GAME 起全量重放 packet，输出当前时刻的完整面板，适合直接喂给 AI 分析。我方默认按"手牌可见方"自动判定（只有客户端本人能看到手牌内容），判不准时用 --player=玩家名 手动指定；也支持 --stdin 从管道读日志，方便测试。

面板层：对局模式与构建号、总手数/回合/当前行动方、双方法力（可用/总（已用 N），过载锁定单独标注）与先后手（后手标注+硬币）、双方英雄血/甲/武器/技能（技能被替换或灌注时显示新技能）、场面随从与地标（攻血 + 嘲讽/圣盾/风怒/冻结/休眠/潜行/扰魔/金卡等状态标注）、我方手牌费用攻血（含兆示预览 <兆示：卡名>、已强化/不可打出标注）、双方牌库剩余/疲劳/尸体数、任务进度槽（任务名 x/y，与奥秘分流计数，完成报奖励）、终局胜负行（斩杀/投降/疲劳；日志被游戏客户端截断时明确提示且不误报胜负）。换牌阶段面板同样输出开局发牌，可直接给留牌建议。

行动回顾：按回合边界自动带最近三个回合——我方上回合全部、对方上回合全部、我方本回合已发生（--events=N 调整带过的回合数，--events=0 关闭），事件按日志原始顺序稳定排序：

• 出牌/召唤附卡牌效果描述（全量不截断，AI 无需查库）与事件时刻攻血快照、战吼目标；攻击附目标与实际伤害（含光环增幅后的真实数值）；英雄技能附效果与自带护甲；死亡附复生信息
• 开局段带换牌语义（起手 → 保留/换掉/换入 → 后手硬币）与 START_OF_GAME 触发效果（如"对战开始时复制传说"列全卡名洗入牌库）
• 引擎自动结算完整入流：亡语/触发的召唤带来源（同名合并 ×N 防刷屏）、亡语/触发伤害（致命标（致命））、治疗带来源、复生、休眠囚禁与苏醒、预备减费、发现/灾变类选择、洗入牌库汇总、回合结束获得（带来源）、亡语亮牌（区分已施放/仅亮出）、手牌满烧牌（报卡名）
• 隐私设计：对方抽牌只报张数不报卡名

hs watch start 启动一个后台守护进程 tail Power.log，检测到换牌阶段或轮到我方回合时，向自建 IM 桥接器 POST /api/external/message（Bearer token 鉴权）注入固定提示词，由桥接器触发 Discord 军师频道的 AI 分析。说明：

hs watch start 启动一个后台守护进程 tail Power.log，检测到换牌阶段或轮到我方回合时，向自建 IM 桥接器 POST /api/external/message（Bearer token 鉴权）注入固定提示词，由桥接器触发 Discord 军师频道的 AI 分析。说明：

• 桥接器是私有组件，不在本仓库内（默认 http://127.0.0.1:8088）。不配置或连不上桥接器时，hs watch 单独使用只监听不发送——POST 失败自动重试 3 次后继续监听，不会崩溃，触发事件可用 hs watch status --events=N 查看
• 配置 merge 存于 ~/.hearthstone-cli/watch_config.json，再次 start 不带参数沿用上次配置；--force 可在残留进程时强制重启
• 提示词可用 --mulligan-prompt= / --turn-prompt= 自定义，token 也可用环境变量 HS_WATCH_TOKEN 传入

标准池维护

标准池白名单在源码 src/hearthstone_cli/deck.py 里的 STANDARD_SETS。新版本上线后：跑 hs update，把新系列代码加进去，再 hs check 体检卡组库。

数据源

卡牌数据来自社区项目 HearthstoneJSON（本地化文本遵循 CC BY 4.0）。构建提取自游戏文件，官方补丁上线当天或次日即可获取；预览季爆料的新卡要等补丁正式部署后才会入库。

免责声明

炉石传说是暴雪娱乐的商标。本项目与暴雪官方无关，仅供个人学习研究使用。

许可

MIT