hearthstone-cli 0.1.0__tar.gz

hearthstone_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OstrichHermit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hearthstone_cli-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: hearthstone-cli
+Version: 0.1.0
+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)
+Author: OstrichHermit
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/OstrichHermit/hearthstone-cli
+Project-URL: Repository, https://github.com/OstrichHermit/hearthstone-cli
+Project-URL: Issues, https://github.com/OstrichHermit/hearthstone-cli/issues
+Keywords: hearthstone,deck,deckstring,cli,agent,card,log-parser,board
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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](README_EN.md) | [简体中文](README.md)
+
+---
+
+人类的组卡模拟器解决的是"可视化拖卡"，而 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](https://hearthstonejson.com/)，补丁日一条命令刷新
+
+## 持续维护
+
+本项目处于活跃维护状态：炉石每个新版本（扩展包 / 平衡补丁）上线后，会同步更新本地标准卡牌库与标准池白名单，卡组体检随版本跟进。若数据源变更导致问题，欢迎提 issue。
+
+## 安装
+
+要求：Python 3.10+（Windows / macOS / Linux）
+
+`hs image` 另需本机安装 Chrome 或 Edge（自动探测，可用环境变量 `CHROME_PATH` 指定）。
+
+```bash
+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 为例：
+
+```bash
+cp -r skills/hs-deck ~/.claude/skills/hs-deck
+```
+
+## 用法
+
+```bash
+# 刷新卡牌库（自动下载最新中文+英文 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` 格式：
+
+```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](https://github.com/OstrichHermit/hearthstone-cli/issues) 或直接 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](https://hearthstonejson.com/)（本地化文本遵循 CC BY 4.0）。构建提取自游戏文件，官方补丁上线当天或次日即可获取；预览季爆料的新卡要等补丁正式部署后才会入库。
+
+## 免责声明
+
+炉石传说是暴雪娱乐的商标。本项目与暴雪官方无关，仅供个人学习研究使用。
+
+## 许可
+
+[MIT](LICENSE)

hearthstone_cli-0.1.0/README.md

@@ -0,0 +1,209 @@
+# 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](README_EN.md) | [简体中文](README.md)
+
+---
+
+人类的组卡模拟器解决的是"可视化拖卡"，而 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](https://hearthstonejson.com/)，补丁日一条命令刷新
+
+## 持续维护
+
+本项目处于活跃维护状态：炉石每个新版本（扩展包 / 平衡补丁）上线后，会同步更新本地标准卡牌库与标准池白名单，卡组体检随版本跟进。若数据源变更导致问题，欢迎提 issue。
+
+## 安装
+
+要求：Python 3.10+（Windows / macOS / Linux）
+
+`hs image` 另需本机安装 Chrome 或 Edge（自动探测，可用环境变量 `CHROME_PATH` 指定）。
+
+```bash
+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 为例：
+
+```bash
+cp -r skills/hs-deck ~/.claude/skills/hs-deck
+```
+
+## 用法
+
+```bash
+# 刷新卡牌库（自动下载最新中文+英文 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` 格式：
+
+```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](https://github.com/OstrichHermit/hearthstone-cli/issues) 或直接 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](https://hearthstonejson.com/)（本地化文本遵循 CC BY 4.0）。构建提取自游戏文件，官方补丁上线当天或次日即可获取；预览季爆料的新卡要等补丁正式部署后才会入库。
+
+## 免责声明
+
+炉石传说是暴雪娱乐的商标。本项目与暴雪官方无关，仅供个人学习研究使用。
+
+## 许可
+
+[MIT](LICENSE)

hearthstone_cli-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hearthstone-cli"
+version = "0.1.0"
+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)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "OstrichHermit" }]
+keywords = ["hearthstone", "deck", "deckstring", "cli", "agent", "card", "log-parser", "board"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+]
+
+[project.urls]
+Homepage = "https://github.com/OstrichHermit/hearthstone-cli"
+Repository = "https://github.com/OstrichHermit/hearthstone-cli"
+Issues = "https://github.com/OstrichHermit/hearthstone-cli/issues"
+
+[project.scripts]
+hs = "hearthstone_cli.deck:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

hearthstone_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hearthstone_cli-0.1.0/src/hearthstone_cli/__init__.py

@@ -0,0 +1,3 @@
+"""hs-deck-cli — Hearthstone deck building CLI for AI agents."""
+
+__version__ = "0.1.0"