Metadata-Version: 2.4
Name: poker-cli
Version: 0.11.2
Summary: A privacy-safe, terminal Texas Hold'em game with optional LLM opponents and hand review.
Author: redearly123
License-Expression: MIT
Project-URL: Homepage, https://github.com/redearly123/terminal-poker
Project-URL: Repository, https://github.com/redearly123/terminal-poker
Project-URL: Issues, https://github.com/redearly123/terminal-poker/issues
Keywords: poker,texas-holdem,terminal,tui,codex,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich<15,>=14.1
Dynamic: license-file

# Terminal Poker

[![CI](https://github.com/redearly123/terminal-poker/actions/workflows/ci.yml/badge.svg)](https://github.com/redearly123/terminal-poker/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

## 核心能力

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

## 安装

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

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

本地开发安装：

```bash
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 复盘时需要。没有安装或登录，也能在
开局菜单选择“离线混合”正常游玩。

## 开始游戏

```bash
poker
```

一个页面完成全部设置：

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

牌桌操作：

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

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

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

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

## AI 对手与复盘

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

```bash
poker --online-policy key
```

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

```bash
poker --review tournament
poker --review hand
poker --review none
```

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

## 长期牌局记录

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

## 翻前范围表

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

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

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

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

## 常用参数

```bash
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                # 纯文本模式
```

完整参数：

```bash
poker --help
```

## 验证

```bash
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：

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

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

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

MIT Licensed.
