hearthstone-cli 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hearthstone-cli
3
- Version: 0.1.0
4
- Summary: Hearthstone toolbox for AI agents — two cores: deck building (validate, encode, filter, deck images) and match analysis (board parsing from game logs, action replay, AI advisor watcher)
3
+ Version: 0.2.0
4
+ Summary: Hearthstone toolbox for AI agents — deck building (validate, encode, filter, deck images, collection sync from game memory) and match analysis (board parsing from game logs, action replay, AI advisor watcher)
5
5
  Author: OstrichHermit
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://github.com/OstrichHermit/hearthstone-cli
@@ -44,9 +44,10 @@ A command-line toolbox for Hearthstone designed for AI agents, with two cores: d
44
44
  - **多职业与游客机制** — 按 `classes` 数组识别多职业卡(如六职业共用的灭世者死亡之翼),并完整实现胜地历险记游客三条规则:游客仅解锁目的地职业的该扩展卡牌、每套限一名游客、不可嵌套
45
45
  - **卡组库与版本体检** — 卡组本地存档,版本更新后一键体检,退环境卡逐条列出
46
46
  - **卡组长图** — 一条命令把卡组渲染成可分享的卡组长图(中/英版各自独立):法力曲线、稀有度配色(默认逐张列出,`--merge` 合并同名卡)、职业徽记、英雄与卡组代码,2x 渲染输出 1520px 宽,调用本地无头 Chrome/Edge
47
- - **对局面板** — 解析炉石客户端日志 Power.log 全量重放,输出结构化实时面板:对局模式、总手数/回合/当前行动方、双方法力(含过载锁定)与先后手(后手标注硬币)、双方英雄血甲武器技能(含灌注/变形后的技能变更)、场面随从与地标(嘲讽/圣盾/风怒/冻结/休眠/金卡等状态标注)、我方手牌费用攻血(含兆示预览与已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度(与奥秘分流显示)、终局胜负与结束方式(斩杀/投降/疲劳)
48
- - **战况回放** — 行动回顾事件流按回合重放双方每一步:出牌(附效果描述与战吼目标)、攻击(附目标与实际伤害)、英雄技能、抽弃牌、换牌保留替换、开局触发效果(如复制传说洗入牌库列全卡名)、亡语与触发结算(召唤带来源、伤害标致命、复生、治疗带来源)、发现/灾变类选择、预备减费、休眠囚禁与苏醒、亡语亮牌(区分已施放/仅亮出)、回合结束获得(带来源)、手牌满烧牌(报卡名),同名合并防刷屏;AI 无需查库即可理解新卡
47
+ - **对局面板** — 解析炉石客户端日志 Power.log 全量重放,输出结构化实时面板:对局模式、总手数/回合/当前行动方、双方法力(含过载锁定)与先后手(后手标注硬币)、双方英雄血甲武器技能(含灌注/变形后的技能变更)、场面随从与地标(嘲讽/圣盾/风怒/冻结/休眠等状态标注)、我方手牌费用攻血(含兆示预览与已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度(与奥秘分流显示)、终局胜负与结束方式(斩杀/投降/疲劳)
48
+ - **战况回放** — 行动回顾事件流按回合重放双方每一步:出牌(我方裸名、对方附效果描述,战吼目标都有)、攻击(附目标与实际伤害)、英雄技能、抽弃牌、换牌保留替换、开局触发效果(如复制传说洗入牌库列全卡名)、亡语与触发结算(召唤带来源、伤害标致命、复生、治疗带来源)、发现/灾变类选择、预备减费、休眠囚禁与苏醒、亡语亮牌(区分已施放/仅亮出)、回合结束获得(带来源与效果描述)、手牌满烧牌(报卡名),同名合并防刷屏;AI 无需查库即可理解新卡
49
49
  - **军师监听** — `hs watch` 后台监听 Power.log,换牌阶段和轮到我方回合时向自建 IM 桥接器推送固定提示词,触发 AI 军师分析对局
50
+ - **卡组收藏同步**(仅 Windows)— `hs collection` 从运行中的游戏内存读取收藏卡组,自动编码为卡组代码并同步到本地卡组库存档(export 手动导出 / watch 常驻监听自动同步)
50
51
  - **对 Agent 友好** — 纯 JSON 输入、报错逐条列出便于自我修正、无任何交互式提示
51
52
  - **本地双语卡牌库** — 中英双语卡牌数据源自 [HearthstoneJSON](https://hearthstonejson.com/),补丁日一条命令刷新
52
53
 
@@ -66,7 +67,7 @@ cd hearthstone-cli
66
67
  pip install .
67
68
  ```
68
69
 
69
- 开发模式用 `pip install -e .`(改动源码即时生效)。PyPI 发布:Coming soon。
70
+ 开发模式用 `pip install -e .`(改动源码即时生效)。也可直接从 PyPI 安装:`pip install hearthstone-cli`。
70
71
 
71
72
  数据目录默认 `~/.hearthstone-cli/`(卡牌库、卡组库、卡组图都存这里),可用环境变量 `HS_DECK_HOME` 覆盖。装好后先跑一次 `hs update` 下载卡牌库。
72
73
 
@@ -117,7 +118,8 @@ hs board --log=D:\games\Hearthstone\Logs\Power.log # 指定日志路径(也
117
118
  hs board --player=鸵鸟居士 # 自动判定我方不准时手动指定
118
119
 
119
120
  # 军师监听:换牌阶段/轮到我方回合时,向 IM 桥接器 POST 提示词触发 AI 分析
120
- hs watch start --channel=<Discord频道ID> --token=<桥接器token> # 默认 --log=auto 自动发现
121
+ # 先编辑 ~/.hearthstone-cli/config.json 配好 watch 节(channel_id/url/token 等),再启动
122
+ hs watch start # 配置好 config.json 的 watch 节后启动
121
123
  hs watch status # 查看运行状态与最近触发事件
122
124
  hs watch stop
123
125
  ```
@@ -150,47 +152,55 @@ hs watch stop
150
152
  ```
151
153
  === 炉石对局面板 ===
152
154
  休闲·标准 | 构建号 253216
153
- 总第 17 手 | 我方第 9 回合 | 我的回合 | 我的法力 9/9(已用 0)
154
- 对方:遛弯的树懒(牧师)[后手+硬币] 手牌 10 奥秘 0 牌库 17 尸体 5 疲劳 0 法力 3/8(已用 5)
155
- 英雄:情报掮客拉祖尔 血 28/30 护甲 0 武器 无 技能 月亮的祝福(已用)
156
- 对方场面(2):
157
- 1. 逐月幼龙 3/6 [金]
158
- 2. 凯洛斯的蛋 0/3
159
- 我方:鸵鸟居士(战士)[先手] 奥秘 0 牌库 23 尸体 4 疲劳 0
160
- 英雄:麦格尼·铜须 血 30/30 护甲 5 武器 无 技能 全副武装!(未用)
161
- 任务 走进失落之城 8/10
162
- 我方场面(3):
163
- 1. 破链灾星霍格 10/10 [嘲讽]
164
- 2. 奥卓克希昂 6/4
165
- 3. 拉格纳罗斯的士兵 2/1
166
- 我方手牌(6):
167
- 1. 屠灭 6费 法术
168
- 2. 龟甲旋风 4费 法术
169
- 3. 拉格纳罗斯,绝世烈火 8费 8/8 随从 <兆示:拉格纳罗斯之手>
170
- 4. 放出鳄鱼 2费 法术
171
- 5. 强固 3费 法术
172
- 6. 为了荣耀! 3费 法术
155
+ 【对局已结束】
156
+ 对局结束:我方胜利(斩杀,对方英雄阵亡)
157
+ 总第 19 手 | 我方第 10 回合 | 我的回合 | 我的法力 10/10(已用 0)
158
+ 对方:遛弯的树懒(牧师)[后手+硬币] 手牌 9 牌库 16 尸体 6 法力 1/9(已用 8)
159
+ 英雄:「情报掮客拉祖尔」血量 0/30 护甲 0 技能「月亮的祝福」(已用)
160
+ 对方场面(3):
161
+ 1.「心灵扫荡者」2/3
162
+ 2.「受难的恐翼巨龙」5/5
163
+ 3.「凯洛斯的蛋」0/3
164
+ 我方:鸵鸟居士(战士)[先手] 牌库 20 尸体 4
165
+ 英雄:「麦格尼·铜须」血量 30/30 护甲 5 技能「全副武装!」(未用)
166
+ 任务「走进失落之城」9/10
167
+ 我方场面(5):
168
+ 1.「奥卓克希昂」6/7
169
+ 2.「拉格纳罗斯的士兵」4/2
170
+ 3.「破链灾星霍格」10/10 [嘲讽]
171
+ 4.「奥卓克希昂」6/1
172
+ 5.「拉格纳罗斯的士兵」2/1
173
+ 我方手牌(7):
174
+ 1.「屠灭」6费 法术
175
+ 2.「龟甲旋风」4费 法术
176
+ 3.「拉格纳罗斯,绝世烈火」8费 8/8 随从 <兆示:「拉格纳罗斯之手」>
177
+ 4.「放出鳄鱼」2费 法术
178
+ 5.「强固」3费 法术
179
+ 6.「怒袭甲龙」3费 4/3 随从
180
+ 7.「城防守卫」4费 法术
173
181
  === 行动回顾 ===
174
- [第 14 回合·对方] 抽牌 1 张
175
- [第 14 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
176
- [第 14 回合·对方] 选择:受伤的侍者
177
- [第 14 回合·对方] 获得 受伤的侍者
178
- [第 14 回合·对方] 打出 随从「受伤的侍者」 [金] 3/8<吸血。战吼:对本随从造成4点伤害。>
179
- [第 14 回合·对方] 受伤的侍者效果 治疗 对方英雄 血28→30
180
- [第 14 回合·对方] 打出 随从「凯洛斯的蛋」 0/3<亡语:召唤一枚轻微开裂的蛋。(破壳5次即可孵化为一只20/20并具有嘲讽的野兽!)>
181
- [第 15 回合·我方] 抽牌 强固<获得3点护甲值。对一个敌方随从造成等同于你护甲值的伤害。>
182
- [第 15 回合·我方] 打出 随从「破链灾星霍格」 10/10<嘲讽。对战开始时:复制你套牌中所有其他传说卡牌。>
183
- [第 15 回合·我方] 攻击:奥卓克希昂 6/7 → 受伤的侍者 3/4
184
- [第 15 回合·我方] 死亡:受伤的侍者 3/0
185
- [第 15 回合·我方] 攻击:拉格纳罗斯的士兵 2/1 → 对方英雄
186
- [第 16 回合·对方] 抽牌 1 张
187
- [第 16 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
188
- [第 16 回合·对方] 选择:逐月幼龙
189
- [第 16 回合·对方] 获得 逐月幼龙
190
- [第 16 回合·对方] 打出 随从「逐月幼龙」 [金] 3/6<扰魔。在你的回合结束时,随机获取一张龙牌。>
191
- [第 16 回合·对方] 获得 1 张牌(逐月幼龙效果获得)
192
- [第 17 回合·我方] 抽牌 为了荣耀!<抽两张牌。你的对手每控制一个随从,本牌的法力值消耗便减少(1)点。>
193
- # 实体总数 103 | 解析起始行 2 | 日志总行 12200
182
+ [第 17 回合·我方]
183
+ 17-1 抽牌「为了荣耀!」<抽两张牌。你的对手每控制一个随从,本牌的法力值消耗便减少(1)点。>
184
+ 17-2 打出 法术「为了荣耀!」
185
+ 17-3 抽牌 2 张(「奥卓克希昂」<战吼:兆示X。使死亡之翼的法力值消耗减少(X)点。(随兆示的次数提升!)> / 「怒袭甲龙」<每当你获得护甲值,获得+2/+2并随机攻击一个敌方随从。>)
186
+ 17-4 打出 随从「奥卓克希昂」6/7(兆示「拉格纳罗斯的士兵」)
187
+ 17-5 召唤「拉格纳罗斯的士兵」4/2<亡语:随机对一个敌人造成X点伤害。兆示两次后升级。>
188
+ 17-6 攻击「奥卓克希昂」6/4 → 「逐月幼龙」3/6
189
+ 17-7 死亡「逐月幼龙」
190
+ 17-8 攻击「破链灾星霍格」10/10 → 对方英雄
191
+ 17-9 攻击「拉格纳罗斯的士兵」2/1 → 对方英雄
192
+ [第 18 回合·对方]
193
+ 18-1 手牌已满,烧掉「暗言术:毁」
194
+ 18-2 打出 随从「受难的恐翼巨龙」5/5<亡语:抽两张龙牌,其法力值消耗减少(1)点。>
195
+ 18-3 英雄技能「月亮的祝福」<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
196
+ 18-4 选择「心灵扫荡者」
197
+ 18-5 获得「心灵扫荡者」
198
+ 18-6 打出 随从「心灵扫荡者」2/3<战吼:如果你在本牌在你手牌中时使用过对手卡牌的复制,对所有敌方随从造成2点伤害。>
199
+ [第 19 回合·我方]
200
+ 19-1 抽牌「城防守卫」<召唤两个0/6并具有嘲讽的守卫。守卫在受到伤害时会获得+1攻击力。>
201
+ 19-2 攻击「破链灾星霍格」10/10 → 对方英雄
202
+ 19-3 攻击「奥卓克希昂」6/1 → 对方英雄
203
+ 19-4 死亡「情报掮客拉祖尔」
194
204
  ```
195
205
 
196
206
  ## 对局面板与军师监听(board / watch)
@@ -199,23 +209,80 @@ hs watch stop
199
209
 
200
210
  `hs board` 从日志里最后一个 `CREATE_GAME` 起全量重放 packet,输出当前时刻的完整面板,适合直接喂给 AI 分析。我方默认按"手牌可见方"自动判定(只有客户端本人能看到手牌内容),判不准时用 `--player=玩家名` 手动指定;也支持 `--stdin` 从管道读日志,方便测试。
201
211
 
202
- **面板层**:对局模式与构建号、总手数/回合/当前行动方、双方法力(`可用/总(已用 N)`,过载锁定单独标注)与先后手(后手标注+硬币)、双方英雄血/甲/武器/技能(技能被替换或灌注时显示新技能)、场面随从与地标(攻血 + 嘲讽/圣盾/风怒/冻结/休眠/潜行/扰魔/金卡等状态标注)、我方手牌费用攻血(含兆示预览 `<兆示:卡名>`、已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度槽(`任务名 x/y`,与奥秘分流计数,完成报奖励)、终局胜负行(斩杀/投降/疲劳;日志被游戏客户端截断时明确提示且不误报胜负)。换牌阶段面板同样输出开局发牌,可直接给留牌建议。
212
+ **面板层**:对局模式与构建号、总手数/回合/当前行动方、双方法力(`可用/总(已用 N)`,过载锁定单独标注)与先后手(后手标注+硬币)、双方英雄血/甲/武器/技能(技能被替换或灌注时显示新技能)、场面随从与地标(攻血 + 嘲讽/圣盾/风怒/冻结/休眠/潜行/扰魔等状态标注)、我方手牌费用攻血(含兆示预览 `<兆示:卡名>`、已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度槽(`任务「名」x/y`,与奥秘分流计数,完成报奖励)、终局胜负行(斩杀/投降/疲劳;日志被游戏客户端截断时明确提示且不误报胜负)。换牌阶段面板同样输出开局发牌,可直接给留牌建议。
203
213
 
204
- **行动回顾**:按回合边界自动带最近三个回合——我方上回合全部、对方上回合全部、我方本回合已发生(`--events=N` 调整带过的回合数,`--events=0` 关闭),事件按日志原始顺序稳定排序:
214
+ **行动回顾**:按回合边界自动带最近三个回合——我方上回合全部、对方上回合全部、我方本回合已发生(`--turns=N` 调整带过的回合数,`--turns=0` 关闭),事件按日志原始顺序稳定排序:
205
215
 
206
- - 出牌/召唤附卡牌效果描述(全量不截断,AI 无需查库)与事件时刻攻血快照、战吼目标;攻击附目标与实际伤害(含光环增幅后的真实数值);英雄技能附效果与自带护甲;死亡附复生信息
216
+ - 卡牌效果描述全量不截断,按“入手一次”挂载:我方随抽牌/获得/起手/换入给出,我方打出不重复;对方手牌不可见,打出行是唯一展示点必带;召唤无来源时附描述。附事件时刻攻血快照、战吼目标;攻击附目标与实际伤害(含光环增幅后的真实数值);英雄技能附效果与自带护甲;死亡附复生信息
207
217
  - 开局段带换牌语义(起手 → 保留/换掉/换入 → 后手硬币)与 START_OF_GAME 触发效果(如"对战开始时复制传说"列全卡名洗入牌库)
208
- - 引擎自动结算完整入流:亡语/触发的召唤带来源(同名合并 ×N 防刷屏)、亡语/触发伤害(致命标(致命))、治疗带来源、复生、休眠囚禁与苏醒、预备减费、发现/灾变类选择、洗入牌库汇总、回合结束获得(带来源)、亡语亮牌(区分已施放/仅亮出)、手牌满烧牌(报卡名)
218
+ - 引擎自动结算完整入流:亡语/触发的召唤带来源(同名合并 ×N 防刷屏)、亡语/触发伤害(致命标(致命))、治疗带来源、复生、休眠囚禁与苏醒、预备减费、发现/灾变类选择、洗入牌库汇总、回合结束获得(带来源与效果描述)、亡语亮牌(区分已施放/仅亮出)、手牌满烧牌(报卡名)
209
219
  - 隐私设计:对方抽牌只报张数不报卡名
210
220
 
211
221
  `hs watch start` 启动一个后台守护进程 tail Power.log,检测到换牌阶段或轮到我方回合时,向自建 IM 桥接器 `POST /api/external/message`(Bearer token 鉴权)注入固定提示词,由桥接器触发 Discord 军师频道的 AI 分析。说明:
212
222
 
223
+ - **桥接器是私有组件,不在本仓库内**(默认 `http://127.0.0.1:8088`)。不配置或连不上桥接器时,`hs watch` 单独使用只监听不发送——POST 失败自动重试 3 次后继续监听,不会崩溃,触发事件可用 `hs watch status --events=N` 查看
224
+ - 配置统一在 `~/.hearthstone-cli/config.json` 的 `watch` 节(`channel_id`/`url`/`token`/`log`/`mulligan_prompt`/`turn_prompt`),与 `hs collection` 共用同一个配置文件、按节管理;CLI 不提供配置参数,编辑文件后 `start` 生效;`--force` 可在残留进程时强制重启
225
+ - 提示词与 token 都在配置文件里改,token 也可用环境变量 `HS_WATCH_TOKEN` 传入
213
226
 
214
- `hs watch start` 启动一个后台守护进程 tail Power.log,检测到换牌阶段或轮到我方回合时,向自建 IM 桥接器 `POST /api/external/message`(Bearer token 鉴权)注入固定提示词,由桥接器触发 Discord 军师频道的 AI 分析。说明:
227
+ ## 卡组收藏同步(可选,仅 Windows)
215
228
 
216
- - **桥接器是私有组件,不在本仓库内**(默认 `http://127.0.0.1:8088`)。不配置或连不上桥接器时,`hs watch` 单独使用只监听不发送——POST 失败自动重试 3 次后继续监听,不会崩溃,触发事件可用 `hs watch status --events=N` 查看
217
- - 配置 merge 存于 `~/.hearthstone-cli/watch_config.json`,再次 `start` 不带参数沿用上次配置;`--force` 可在残留进程时强制重启
218
- - 提示词可用 `--mulligan-prompt=` / `--turn-prompt=` 自定义,token 也可用环境变量 `HS_WATCH_TOKEN` 传入
229
+ `hs collection` 通过一个内置的小型内存读取器(DeckExport)直接从运行中的炉石客户端读取收藏卡组,机制与 Hearthstone Deck Tracker 等社区工具同款:**只读游戏内存,不写入游戏进程**。读到的 standard/wild 卡组会自动编码为标准卡组代码,按 `hs save` 的存档格式写入卡组库,之后 `hs show` / `hs image` / `hs check` 等命令可直接使用。
230
+
231
+ 前置条件:
232
+
233
+ - Windows + 炉石客户端正在运行
234
+ - dotnet SDK 9(`winget install Microsoft.DotNet.SDK.9`),仅构建读取器时需要
235
+ - 补丁版 HearthMirror 源码缓存(`~/.hearthstone-cli/native/src/`;上游 HearthMirror_Decompiled 仓库源码无法直接编译,需自行修复编译错误后放到该路径,或从装好本工具的机器复制)
236
+
237
+ 常用命令:
238
+
239
+ ```bash
240
+ # 手动导出一次(首次运行检测到读取器缺失时会自动构建)
241
+ hs collection export
242
+
243
+ # 只对比不写存档(调试用)
244
+ hs collection export --check
245
+
246
+ # 常驻监听:游戏内卡组一有变化自动同步(默认每 5 秒轮询一次)
247
+ # 先编辑 ~/.hearthstone-cli/config.json 的 collection 节(interval 轮询秒数 / sync_delete 删除同步开关),再启动
248
+ hs collection watch start
249
+ hs collection watch status # 运行状态 + 最近同步事件
250
+ hs collection watch stop
251
+
252
+ # 编辑配置文件后 --force 重启已在运行的守护使其生效
253
+ hs collection watch start --force
254
+
255
+ # 手动构建 / 修复内存读取器
256
+ hs collection build
257
+ ```
258
+
259
+ 说明:
260
+
261
+ - 同步默认只增不删:游戏里删除的卡组,本地存档保留不动;在配置文件把 `sync_delete` 设为 `true` 后随游戏同步删除(仅删除此前由同步写入的存档,手动 `hs save` 导入的不受影响)
262
+ - 同名卡组(游戏允许多槽同名)第 2 个起自动加 `-<deckId 后 4 位>` 后缀,命名稳定可复现
263
+ - 经典 / 竞技场等非标准 / 狂野格式的卡组会被跳过并列出
264
+ - 炉石未运行时 export 友好提示退出;watch 则静默等待,游戏开启后自动恢复同步
265
+ - 卡组内出现卡牌库不认识的卡时整组跳过,跑 `hs update` 刷新卡牌库后再同步
266
+ - 配置唯一入口是 `~/.hearthstone-cli/config.json`,watch 与 collection 各占一节、互不影响,CLI 不再提供配置参数(操作类 `--force` / `--check` / `--events=N` 与路径定位 `--config=路径` 除外);watch.pid / watch.log / collection.pid / collection.log 与配置文件同目录,便于 `--config` 测试隔离。可复制仓库根目录的 `config.example.json` 起步。完整结构:
267
+
268
+ ```json
269
+ {
270
+ "watch": {
271
+ "channel_id": "<Discord 频道 ID>",
272
+ "url": "http://127.0.0.1:8088",
273
+ "token": "<IM 桥接器 token>",
274
+ "log": "auto",
275
+ "mulligan_prompt": "换牌阶段提示词",
276
+ "turn_prompt": "我方回合提示词"
277
+ },
278
+ "collection": {
279
+ "interval": 5,
280
+ "sync_delete": false
281
+ }
282
+ }
283
+ ```
284
+
285
+ - 旧的 `watch_config.json` / `collection_config.json` 在首次使用时自动迁移进统一文件的对应节(旧文件保留不删)
219
286
 
220
287
  ## 标准池维护
221
288
 
@@ -19,9 +19,10 @@ A command-line toolbox for Hearthstone designed for AI agents, with two cores: d
19
19
  - **多职业与游客机制** — 按 `classes` 数组识别多职业卡(如六职业共用的灭世者死亡之翼),并完整实现胜地历险记游客三条规则:游客仅解锁目的地职业的该扩展卡牌、每套限一名游客、不可嵌套
20
20
  - **卡组库与版本体检** — 卡组本地存档,版本更新后一键体检,退环境卡逐条列出
21
21
  - **卡组长图** — 一条命令把卡组渲染成可分享的卡组长图(中/英版各自独立):法力曲线、稀有度配色(默认逐张列出,`--merge` 合并同名卡)、职业徽记、英雄与卡组代码,2x 渲染输出 1520px 宽,调用本地无头 Chrome/Edge
22
- - **对局面板** — 解析炉石客户端日志 Power.log 全量重放,输出结构化实时面板:对局模式、总手数/回合/当前行动方、双方法力(含过载锁定)与先后手(后手标注硬币)、双方英雄血甲武器技能(含灌注/变形后的技能变更)、场面随从与地标(嘲讽/圣盾/风怒/冻结/休眠/金卡等状态标注)、我方手牌费用攻血(含兆示预览与已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度(与奥秘分流显示)、终局胜负与结束方式(斩杀/投降/疲劳)
23
- - **战况回放** — 行动回顾事件流按回合重放双方每一步:出牌(附效果描述与战吼目标)、攻击(附目标与实际伤害)、英雄技能、抽弃牌、换牌保留替换、开局触发效果(如复制传说洗入牌库列全卡名)、亡语与触发结算(召唤带来源、伤害标致命、复生、治疗带来源)、发现/灾变类选择、预备减费、休眠囚禁与苏醒、亡语亮牌(区分已施放/仅亮出)、回合结束获得(带来源)、手牌满烧牌(报卡名),同名合并防刷屏;AI 无需查库即可理解新卡
22
+ - **对局面板** — 解析炉石客户端日志 Power.log 全量重放,输出结构化实时面板:对局模式、总手数/回合/当前行动方、双方法力(含过载锁定)与先后手(后手标注硬币)、双方英雄血甲武器技能(含灌注/变形后的技能变更)、场面随从与地标(嘲讽/圣盾/风怒/冻结/休眠等状态标注)、我方手牌费用攻血(含兆示预览与已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度(与奥秘分流显示)、终局胜负与结束方式(斩杀/投降/疲劳)
23
+ - **战况回放** — 行动回顾事件流按回合重放双方每一步:出牌(我方裸名、对方附效果描述,战吼目标都有)、攻击(附目标与实际伤害)、英雄技能、抽弃牌、换牌保留替换、开局触发效果(如复制传说洗入牌库列全卡名)、亡语与触发结算(召唤带来源、伤害标致命、复生、治疗带来源)、发现/灾变类选择、预备减费、休眠囚禁与苏醒、亡语亮牌(区分已施放/仅亮出)、回合结束获得(带来源与效果描述)、手牌满烧牌(报卡名),同名合并防刷屏;AI 无需查库即可理解新卡
24
24
  - **军师监听** — `hs watch` 后台监听 Power.log,换牌阶段和轮到我方回合时向自建 IM 桥接器推送固定提示词,触发 AI 军师分析对局
25
+ - **卡组收藏同步**(仅 Windows)— `hs collection` 从运行中的游戏内存读取收藏卡组,自动编码为卡组代码并同步到本地卡组库存档(export 手动导出 / watch 常驻监听自动同步)
25
26
  - **对 Agent 友好** — 纯 JSON 输入、报错逐条列出便于自我修正、无任何交互式提示
26
27
  - **本地双语卡牌库** — 中英双语卡牌数据源自 [HearthstoneJSON](https://hearthstonejson.com/),补丁日一条命令刷新
27
28
 
@@ -41,7 +42,7 @@ cd hearthstone-cli
41
42
  pip install .
42
43
  ```
43
44
 
44
- 开发模式用 `pip install -e .`(改动源码即时生效)。PyPI 发布:Coming soon。
45
+ 开发模式用 `pip install -e .`(改动源码即时生效)。也可直接从 PyPI 安装:`pip install hearthstone-cli`。
45
46
 
46
47
  数据目录默认 `~/.hearthstone-cli/`(卡牌库、卡组库、卡组图都存这里),可用环境变量 `HS_DECK_HOME` 覆盖。装好后先跑一次 `hs update` 下载卡牌库。
47
48
 
@@ -92,7 +93,8 @@ hs board --log=D:\games\Hearthstone\Logs\Power.log # 指定日志路径(也
92
93
  hs board --player=鸵鸟居士 # 自动判定我方不准时手动指定
93
94
 
94
95
  # 军师监听:换牌阶段/轮到我方回合时,向 IM 桥接器 POST 提示词触发 AI 分析
95
- hs watch start --channel=<Discord频道ID> --token=<桥接器token> # 默认 --log=auto 自动发现
96
+ # 先编辑 ~/.hearthstone-cli/config.json 配好 watch 节(channel_id/url/token 等),再启动
97
+ hs watch start # 配置好 config.json 的 watch 节后启动
96
98
  hs watch status # 查看运行状态与最近触发事件
97
99
  hs watch stop
98
100
  ```
@@ -125,47 +127,55 @@ hs watch stop
125
127
  ```
126
128
  === 炉石对局面板 ===
127
129
  休闲·标准 | 构建号 253216
128
- 总第 17 手 | 我方第 9 回合 | 我的回合 | 我的法力 9/9(已用 0)
129
- 对方:遛弯的树懒(牧师)[后手+硬币] 手牌 10 奥秘 0 牌库 17 尸体 5 疲劳 0 法力 3/8(已用 5)
130
- 英雄:情报掮客拉祖尔 血 28/30 护甲 0 武器 无 技能 月亮的祝福(已用)
131
- 对方场面(2):
132
- 1. 逐月幼龙 3/6 [金]
133
- 2. 凯洛斯的蛋 0/3
134
- 我方:鸵鸟居士(战士)[先手] 奥秘 0 牌库 23 尸体 4 疲劳 0
135
- 英雄:麦格尼·铜须 血 30/30 护甲 5 武器 无 技能 全副武装!(未用)
136
- 任务 走进失落之城 8/10
137
- 我方场面(3):
138
- 1. 破链灾星霍格 10/10 [嘲讽]
139
- 2. 奥卓克希昂 6/4
140
- 3. 拉格纳罗斯的士兵 2/1
141
- 我方手牌(6):
142
- 1. 屠灭 6费 法术
143
- 2. 龟甲旋风 4费 法术
144
- 3. 拉格纳罗斯,绝世烈火 8费 8/8 随从 <兆示:拉格纳罗斯之手>
145
- 4. 放出鳄鱼 2费 法术
146
- 5. 强固 3费 法术
147
- 6. 为了荣耀! 3费 法术
130
+ 【对局已结束】
131
+ 对局结束:我方胜利(斩杀,对方英雄阵亡)
132
+ 总第 19 手 | 我方第 10 回合 | 我的回合 | 我的法力 10/10(已用 0)
133
+ 对方:遛弯的树懒(牧师)[后手+硬币] 手牌 9 牌库 16 尸体 6 法力 1/9(已用 8)
134
+ 英雄:「情报掮客拉祖尔」血量 0/30 护甲 0 技能「月亮的祝福」(已用)
135
+ 对方场面(3):
136
+ 1.「心灵扫荡者」2/3
137
+ 2.「受难的恐翼巨龙」5/5
138
+ 3.「凯洛斯的蛋」0/3
139
+ 我方:鸵鸟居士(战士)[先手] 牌库 20 尸体 4
140
+ 英雄:「麦格尼·铜须」血量 30/30 护甲 5 技能「全副武装!」(未用)
141
+ 任务「走进失落之城」9/10
142
+ 我方场面(5):
143
+ 1.「奥卓克希昂」6/7
144
+ 2.「拉格纳罗斯的士兵」4/2
145
+ 3.「破链灾星霍格」10/10 [嘲讽]
146
+ 4.「奥卓克希昂」6/1
147
+ 5.「拉格纳罗斯的士兵」2/1
148
+ 我方手牌(7):
149
+ 1.「屠灭」6费 法术
150
+ 2.「龟甲旋风」4费 法术
151
+ 3.「拉格纳罗斯,绝世烈火」8费 8/8 随从 <兆示:「拉格纳罗斯之手」>
152
+ 4.「放出鳄鱼」2费 法术
153
+ 5.「强固」3费 法术
154
+ 6.「怒袭甲龙」3费 4/3 随从
155
+ 7.「城防守卫」4费 法术
148
156
  === 行动回顾 ===
149
- [第 14 回合·对方] 抽牌 1 张
150
- [第 14 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
151
- [第 14 回合·对方] 选择:受伤的侍者
152
- [第 14 回合·对方] 获得 受伤的侍者
153
- [第 14 回合·对方] 打出 随从「受伤的侍者」 [金] 3/8<吸血。战吼:对本随从造成4点伤害。>
154
- [第 14 回合·对方] 受伤的侍者效果 治疗 对方英雄 血28→30
155
- [第 14 回合·对方] 打出 随从「凯洛斯的蛋」 0/3<亡语:召唤一枚轻微开裂的蛋。(破壳5次即可孵化为一只20/20并具有嘲讽的野兽!)>
156
- [第 15 回合·我方] 抽牌 强固<获得3点护甲值。对一个敌方随从造成等同于你护甲值的伤害。>
157
- [第 15 回合·我方] 打出 随从「破链灾星霍格」 10/10<嘲讽。对战开始时:复制你套牌中所有其他传说卡牌。>
158
- [第 15 回合·我方] 攻击:奥卓克希昂 6/7 → 受伤的侍者 3/4
159
- [第 15 回合·我方] 死亡:受伤的侍者 3/0
160
- [第 15 回合·我方] 攻击:拉格纳罗斯的士兵 2/1 → 对方英雄
161
- [第 16 回合·对方] 抽牌 1 张
162
- [第 16 回合·对方] 英雄技能 月亮的祝福<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
163
- [第 16 回合·对方] 选择:逐月幼龙
164
- [第 16 回合·对方] 获得 逐月幼龙
165
- [第 16 回合·对方] 打出 随从「逐月幼龙」 [金] 3/6<扰魔。在你的回合结束时,随机获取一张龙牌。>
166
- [第 16 回合·对方] 获得 1 张牌(逐月幼龙效果获得)
167
- [第 17 回合·我方] 抽牌 为了荣耀!<抽两张牌。你的对手每控制一个随从,本牌的法力值消耗便减少(1)点。>
168
- # 实体总数 103 | 解析起始行 2 | 日志总行 12200
157
+ [第 17 回合·我方]
158
+ 17-1 抽牌「为了荣耀!」<抽两张牌。你的对手每控制一个随从,本牌的法力值消耗便减少(1)点。>
159
+ 17-2 打出 法术「为了荣耀!」
160
+ 17-3 抽牌 2 张(「奥卓克希昂」<战吼:兆示X。使死亡之翼的法力值消耗减少(X)点。(随兆示的次数提升!)> / 「怒袭甲龙」<每当你获得护甲值,获得+2/+2并随机攻击一个敌方随从。>)
161
+ 17-4 打出 随从「奥卓克希昂」6/7(兆示「拉格纳罗斯的士兵」)
162
+ 17-5 召唤「拉格纳罗斯的士兵」4/2<亡语:随机对一个敌人造成X点伤害。兆示两次后升级。>
163
+ 17-6 攻击「奥卓克希昂」6/4 → 「逐月幼龙」3/6
164
+ 17-7 死亡「逐月幼龙」
165
+ 17-8 攻击「破链灾星霍格」10/10 → 对方英雄
166
+ 17-9 攻击「拉格纳罗斯的士兵」2/1 → 对方英雄
167
+ [第 18 回合·对方]
168
+ 18-1 手牌已满,烧掉「暗言术:毁」
169
+ 18-2 打出 随从「受难的恐翼巨龙」5/5<亡语:抽两张龙牌,其法力值消耗减少(1)点。>
170
+ 18-3 英雄技能「月亮的祝福」<选择一张可用的牧师随从牌或法术牌置入你的手牌,其法力值消耗减少(>
171
+ 18-4 选择「心灵扫荡者」
172
+ 18-5 获得「心灵扫荡者」
173
+ 18-6 打出 随从「心灵扫荡者」2/3<战吼:如果你在本牌在你手牌中时使用过对手卡牌的复制,对所有敌方随从造成2点伤害。>
174
+ [第 19 回合·我方]
175
+ 19-1 抽牌「城防守卫」<召唤两个0/6并具有嘲讽的守卫。守卫在受到伤害时会获得+1攻击力。>
176
+ 19-2 攻击「破链灾星霍格」10/10 → 对方英雄
177
+ 19-3 攻击「奥卓克希昂」6/1 → 对方英雄
178
+ 19-4 死亡「情报掮客拉祖尔」
169
179
  ```
170
180
 
171
181
  ## 对局面板与军师监听(board / watch)
@@ -174,23 +184,80 @@ hs watch stop
174
184
 
175
185
  `hs board` 从日志里最后一个 `CREATE_GAME` 起全量重放 packet,输出当前时刻的完整面板,适合直接喂给 AI 分析。我方默认按"手牌可见方"自动判定(只有客户端本人能看到手牌内容),判不准时用 `--player=玩家名` 手动指定;也支持 `--stdin` 从管道读日志,方便测试。
176
186
 
177
- **面板层**:对局模式与构建号、总手数/回合/当前行动方、双方法力(`可用/总(已用 N)`,过载锁定单独标注)与先后手(后手标注+硬币)、双方英雄血/甲/武器/技能(技能被替换或灌注时显示新技能)、场面随从与地标(攻血 + 嘲讽/圣盾/风怒/冻结/休眠/潜行/扰魔/金卡等状态标注)、我方手牌费用攻血(含兆示预览 `<兆示:卡名>`、已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度槽(`任务名 x/y`,与奥秘分流计数,完成报奖励)、终局胜负行(斩杀/投降/疲劳;日志被游戏客户端截断时明确提示且不误报胜负)。换牌阶段面板同样输出开局发牌,可直接给留牌建议。
187
+ **面板层**:对局模式与构建号、总手数/回合/当前行动方、双方法力(`可用/总(已用 N)`,过载锁定单独标注)与先后手(后手标注+硬币)、双方英雄血/甲/武器/技能(技能被替换或灌注时显示新技能)、场面随从与地标(攻血 + 嘲讽/圣盾/风怒/冻结/休眠/潜行/扰魔等状态标注)、我方手牌费用攻血(含兆示预览 `<兆示:卡名>`、已强化/不可打出标注)、双方牌库剩余/疲劳/尸体数、任务进度槽(`任务「名」x/y`,与奥秘分流计数,完成报奖励)、终局胜负行(斩杀/投降/疲劳;日志被游戏客户端截断时明确提示且不误报胜负)。换牌阶段面板同样输出开局发牌,可直接给留牌建议。
178
188
 
179
- **行动回顾**:按回合边界自动带最近三个回合——我方上回合全部、对方上回合全部、我方本回合已发生(`--events=N` 调整带过的回合数,`--events=0` 关闭),事件按日志原始顺序稳定排序:
189
+ **行动回顾**:按回合边界自动带最近三个回合——我方上回合全部、对方上回合全部、我方本回合已发生(`--turns=N` 调整带过的回合数,`--turns=0` 关闭),事件按日志原始顺序稳定排序:
180
190
 
181
- - 出牌/召唤附卡牌效果描述(全量不截断,AI 无需查库)与事件时刻攻血快照、战吼目标;攻击附目标与实际伤害(含光环增幅后的真实数值);英雄技能附效果与自带护甲;死亡附复生信息
191
+ - 卡牌效果描述全量不截断,按“入手一次”挂载:我方随抽牌/获得/起手/换入给出,我方打出不重复;对方手牌不可见,打出行是唯一展示点必带;召唤无来源时附描述。附事件时刻攻血快照、战吼目标;攻击附目标与实际伤害(含光环增幅后的真实数值);英雄技能附效果与自带护甲;死亡附复生信息
182
192
  - 开局段带换牌语义(起手 → 保留/换掉/换入 → 后手硬币)与 START_OF_GAME 触发效果(如"对战开始时复制传说"列全卡名洗入牌库)
183
- - 引擎自动结算完整入流:亡语/触发的召唤带来源(同名合并 ×N 防刷屏)、亡语/触发伤害(致命标(致命))、治疗带来源、复生、休眠囚禁与苏醒、预备减费、发现/灾变类选择、洗入牌库汇总、回合结束获得(带来源)、亡语亮牌(区分已施放/仅亮出)、手牌满烧牌(报卡名)
193
+ - 引擎自动结算完整入流:亡语/触发的召唤带来源(同名合并 ×N 防刷屏)、亡语/触发伤害(致命标(致命))、治疗带来源、复生、休眠囚禁与苏醒、预备减费、发现/灾变类选择、洗入牌库汇总、回合结束获得(带来源与效果描述)、亡语亮牌(区分已施放/仅亮出)、手牌满烧牌(报卡名)
184
194
  - 隐私设计:对方抽牌只报张数不报卡名
185
195
 
186
196
  `hs watch start` 启动一个后台守护进程 tail Power.log,检测到换牌阶段或轮到我方回合时,向自建 IM 桥接器 `POST /api/external/message`(Bearer token 鉴权)注入固定提示词,由桥接器触发 Discord 军师频道的 AI 分析。说明:
187
197
 
198
+ - **桥接器是私有组件,不在本仓库内**(默认 `http://127.0.0.1:8088`)。不配置或连不上桥接器时,`hs watch` 单独使用只监听不发送——POST 失败自动重试 3 次后继续监听,不会崩溃,触发事件可用 `hs watch status --events=N` 查看
199
+ - 配置统一在 `~/.hearthstone-cli/config.json` 的 `watch` 节(`channel_id`/`url`/`token`/`log`/`mulligan_prompt`/`turn_prompt`),与 `hs collection` 共用同一个配置文件、按节管理;CLI 不提供配置参数,编辑文件后 `start` 生效;`--force` 可在残留进程时强制重启
200
+ - 提示词与 token 都在配置文件里改,token 也可用环境变量 `HS_WATCH_TOKEN` 传入
188
201
 
189
- `hs watch start` 启动一个后台守护进程 tail Power.log,检测到换牌阶段或轮到我方回合时,向自建 IM 桥接器 `POST /api/external/message`(Bearer token 鉴权)注入固定提示词,由桥接器触发 Discord 军师频道的 AI 分析。说明:
202
+ ## 卡组收藏同步(可选,仅 Windows)
190
203
 
191
- - **桥接器是私有组件,不在本仓库内**(默认 `http://127.0.0.1:8088`)。不配置或连不上桥接器时,`hs watch` 单独使用只监听不发送——POST 失败自动重试 3 次后继续监听,不会崩溃,触发事件可用 `hs watch status --events=N` 查看
192
- - 配置 merge 存于 `~/.hearthstone-cli/watch_config.json`,再次 `start` 不带参数沿用上次配置;`--force` 可在残留进程时强制重启
193
- - 提示词可用 `--mulligan-prompt=` / `--turn-prompt=` 自定义,token 也可用环境变量 `HS_WATCH_TOKEN` 传入
204
+ `hs collection` 通过一个内置的小型内存读取器(DeckExport)直接从运行中的炉石客户端读取收藏卡组,机制与 Hearthstone Deck Tracker 等社区工具同款:**只读游戏内存,不写入游戏进程**。读到的 standard/wild 卡组会自动编码为标准卡组代码,按 `hs save` 的存档格式写入卡组库,之后 `hs show` / `hs image` / `hs check` 等命令可直接使用。
205
+
206
+ 前置条件:
207
+
208
+ - Windows + 炉石客户端正在运行
209
+ - dotnet SDK 9(`winget install Microsoft.DotNet.SDK.9`),仅构建读取器时需要
210
+ - 补丁版 HearthMirror 源码缓存(`~/.hearthstone-cli/native/src/`;上游 HearthMirror_Decompiled 仓库源码无法直接编译,需自行修复编译错误后放到该路径,或从装好本工具的机器复制)
211
+
212
+ 常用命令:
213
+
214
+ ```bash
215
+ # 手动导出一次(首次运行检测到读取器缺失时会自动构建)
216
+ hs collection export
217
+
218
+ # 只对比不写存档(调试用)
219
+ hs collection export --check
220
+
221
+ # 常驻监听:游戏内卡组一有变化自动同步(默认每 5 秒轮询一次)
222
+ # 先编辑 ~/.hearthstone-cli/config.json 的 collection 节(interval 轮询秒数 / sync_delete 删除同步开关),再启动
223
+ hs collection watch start
224
+ hs collection watch status # 运行状态 + 最近同步事件
225
+ hs collection watch stop
226
+
227
+ # 编辑配置文件后 --force 重启已在运行的守护使其生效
228
+ hs collection watch start --force
229
+
230
+ # 手动构建 / 修复内存读取器
231
+ hs collection build
232
+ ```
233
+
234
+ 说明:
235
+
236
+ - 同步默认只增不删:游戏里删除的卡组,本地存档保留不动;在配置文件把 `sync_delete` 设为 `true` 后随游戏同步删除(仅删除此前由同步写入的存档,手动 `hs save` 导入的不受影响)
237
+ - 同名卡组(游戏允许多槽同名)第 2 个起自动加 `-<deckId 后 4 位>` 后缀,命名稳定可复现
238
+ - 经典 / 竞技场等非标准 / 狂野格式的卡组会被跳过并列出
239
+ - 炉石未运行时 export 友好提示退出;watch 则静默等待,游戏开启后自动恢复同步
240
+ - 卡组内出现卡牌库不认识的卡时整组跳过,跑 `hs update` 刷新卡牌库后再同步
241
+ - 配置唯一入口是 `~/.hearthstone-cli/config.json`,watch 与 collection 各占一节、互不影响,CLI 不再提供配置参数(操作类 `--force` / `--check` / `--events=N` 与路径定位 `--config=路径` 除外);watch.pid / watch.log / collection.pid / collection.log 与配置文件同目录,便于 `--config` 测试隔离。可复制仓库根目录的 `config.example.json` 起步。完整结构:
242
+
243
+ ```json
244
+ {
245
+ "watch": {
246
+ "channel_id": "<Discord 频道 ID>",
247
+ "url": "http://127.0.0.1:8088",
248
+ "token": "<IM 桥接器 token>",
249
+ "log": "auto",
250
+ "mulligan_prompt": "换牌阶段提示词",
251
+ "turn_prompt": "我方回合提示词"
252
+ },
253
+ "collection": {
254
+ "interval": 5,
255
+ "sync_delete": false
256
+ }
257
+ }
258
+ ```
259
+
260
+ - 旧的 `watch_config.json` / `collection_config.json` 在首次使用时自动迁移进统一文件的对应节(旧文件保留不删)
194
261
 
195
262
  ## 标准池维护
196
263
 
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "hearthstone-cli"
7
- version = "0.1.0"
8
- description = "Hearthstone toolbox for AI agents — two cores: deck building (validate, encode, filter, deck images) and match analysis (board parsing from game logs, action replay, AI advisor watcher)"
7
+ version = "0.2.0"
8
+ description = "Hearthstone toolbox for AI agents — deck building (validate, encode, filter, deck images, collection sync from game memory) and match analysis (board parsing from game logs, action replay, AI advisor watcher)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
11
11
  license = "MIT"