poker-cli 0.11.2

A privacy-safe, terminal Texas Hold'em game with optional LLM opponents and hand review.

Terminal Poker

在终端里玩一届完整的德州扑克锦标赛。默认 6-max Sit & Go，由本机 Codex / Claude Code 登录态驱动 AI 对手，并在比赛结束后复盘你的决策。

核心能力

• 让 AI 当你的德扑搭子，也可以全程使用离线对手
• TUI 可视化牌桌：手牌、公共牌、筹码、动作、翻牌动画和摊牌
• 自动保存锦标赛进度，随时退出、继续
• 长期保存每手牌、公开行动、筹码变化和玩家决策
• 记录整届比赛的玩家决策，结束后由 AI 集中复盘
• 内置有明确来源的翻前范围表，支持导入自己的求解器数据
• 模型只会收到自己的底牌与公开信息，不会看到其他玩家手牌

安装

需要 Python 3.11+。推荐使用 pipx 安装成全局命令：

pipx install git+https://github.com/redearly123/terminal-poker.git
poker

本地开发安装：

git clone https://github.com/redearly123/terminal-poker.git
cd terminal-poker
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/poker

Codex / Claude Code 只在在线对手和 AI 复盘时需要。没有安装或登录，也能在 开局菜单选择“离线混合”正常游玩。

开始游戏

poker

一个页面完成全部设置：

• ↑/↓ 或 Tab：移动
• ←/→：切换选项
• Enter：开始
• Esc/Q：退出

牌桌操作：

1  Fold
2  Check / Call
3  Raise
4  翻前范围表
5  无法继续行动时快进本手

加注金额表示“本轮总下注到多少”。每手结算后按 1 继续，按 0 结束。

继续最近存档、查看长期记录和模型额度：

poker resume
poker history
poker history --limit 20
poker history path
poker usage

AI 对手与复盘

开局菜单可选择 Codex、Claude Code、混合在线或纯离线对手。程序复用本机 CLI 的现有登录态，不读取或复制凭据；Claude 默认使用较省额度的 Haiku。 在线对手默认每个行动都调用模型。开局页面会记住上一次成功确认的全部设置， 下次运行 poker 时自动恢复。需要更快的混合模式时，可改为只在大额跟注、 较大底池和转河关键节点调用模型；该模式全桌每手最多调用 3 次：

poker --online-policy key

默认在整届锦标赛结束后集中复盘，也可以改成逐手复盘或完全关闭：

poker --review tournament
poker --review hand
poker --review none

每次模型调用只包含该对手自己的底牌、公共牌、公开行动、筹码和合法动作。 完整引擎、牌堆及其他玩家底牌不会进入模型输入；调用失败时会自动切换到离线 策略，不中断牌局。

长期牌局记录

默认把每一手追加到本机 JSONL 历史中，包括牌面、完整公开行动、盲注、前后 筹码、结果和你的决策分析。对手底牌只在实际摊牌公开后记录；未亮出的牌不会 写入文件。开局菜单可关闭，命令行也可使用 --no-history。

翻前范围表

牌桌内按 4 打开。颜色分别表示 jam、raise、call、混合频率和 fold，并 标出当前手牌。

内置表来自 PokerCoaching 公开的 6-max 图表。 完全匹配显示 EXACT；人数、筹码或行动树不完全匹配时显示 REFERENCE 并说明偏差，不会把 100BB 现金桌参考冒充成精确短码或 ICM 解。

导入自己的 FreeBetRange / 求解器范围：

poker ranges example
poker ranges import ~/Downloads/my-ranges.json
poker ranges list

常用参数

poker --opponent mixed       # 纯离线
poker --coach codex          # Codex 复盘
poker --codex-model gpt-5.4-mini
poker --claude-model sonnet  # 更换 Claude 模型
poker --online-policy key    # 仅关键局面在线思考
poker --blind-speed turbo    # 加快升盲
poker --size compact         # 调整牌桌尺寸
poker --theme classic        # 更换皮肤
poker --plain                # 纯文本模式

完整参数：

poker --help

验证

PYTHONPATH=src python -m unittest discover -s tests -v

发布

main 用于持续开发，不会自动覆盖 PyPI。发布新版本只需打开 GitHub Actions 的 Release，点击 Run workflow，选择 patch、minor 或 major。工作流会自动修改版本、测试、提交、打 tag、创建 Release，并通过 Trusted Publishing 上传 PyPI。

首次发布前，仓库所有者只需在 PyPI 添加一次 Trusted Publisher：

Owner: redearly123
Repository: terminal-poker
Workflow: publish.yml
Environment: pypi

已安装用户仍需主动更新：

pipx upgrade poker-cli
# 或
python -m pip install --upgrade poker-cli

MIT Licensed.