poker-cli 0.11.2__py3-none-any.whl

poker_cli/cli.py

@@ -0,0 +1,1250 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import shutil
+import sys
+import termios
+import tty
+import uuid
+
+from rich import box
+from rich.align import Align
+from rich.console import Console, Group
+from rich.live import Live
+from rich.table import Table
+from rich.text import Text
+
+from .coach import CoachError, LocalCLICoach
+from .controllers import (
+    BOT_PROFILES,
+    HumanController,
+    LLMController,
+    LocalAgentCLIController,
+    OnlineDecisionBudget,
+    OfflineBot,
+)
+from .engine import HeadsUpGame
+from .models import HandResult
+from .history import (
+    HandHistoryStore,
+    HistoryError,
+    build_hand_record,
+    default_history_path,
+    format_history_summary,
+)
+from .ranges import RangeLibrary, RangePackError
+from .review import format_review, format_tournament_review
+from .savegame import (
+    SaveGameError,
+    load_tournament_save,
+    remove_save,
+    restore_tournament,
+    save_tournament,
+)
+from .settings import (
+    SettingsError,
+    apply_settings,
+    load_settings,
+    save_settings,
+    settings_from_namespace,
+)
+from .tournament import TournamentGame
+from .usage import ModelUsageTracker
+
+
+BLIND_SPEEDS = {
+    "turbo": 2,
+    "fast": 4,
+    "normal": 8,
+    "slow": 12,
+}
+
+CODEX_MODELS = (
+    "gpt-5.4-mini",
+    "gpt-5.4",
+    "gpt-5.6-terra",
+    "gpt-5.6-sol",
+)
+CLAUDE_MODELS = ("haiku", "sonnet", "opus")
+MIXED_MODEL_PRESETS = (
+    ("gpt-5.4-mini", "haiku"),
+    ("gpt-5.4", "sonnet"),
+    ("gpt-5.6-sol", "opus"),
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="在终端里玩带 AI 对手和赛后复盘的德州锦标赛",
+        epilog=(
+            "继续存档：poker resume｜长期记录：poker history｜"
+            "模型额度：poker usage"
+        ),
+    )
+    parser.add_argument(
+        "--opponent",
+        choices=(
+            "agent",
+            "codex",
+            "claude",
+            "local",
+            "mixed",
+            *BOT_PROFILES.keys(),
+            "llm",
+        ),
+        default="agent",
+        help="默认通过本地 Codex/Claude Code 登录态驱动对手；mixed 为纯离线",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("tournament", "heads-up"),
+        default="tournament",
+        help="默认是 6-max 单桌锦标赛",
+    )
+    parser.add_argument("--players", type=int, choices=range(2, 7), default=6, help="锦标赛人数")
+    parser.add_argument("--plain", action="store_true", help="关闭全屏牌桌，使用纯文本模式")
+    parser.add_argument(
+        "--speed",
+        choices=("fast", "normal", "slow"),
+        default="normal",
+        help="TUI 动画速度",
+    )
+    parser.add_argument(
+        "--size",
+        choices=("mini", "compact", "auto", "large"),
+        default="mini",
+        help="牌桌尺寸；默认 mini 使用最小布局",
+    )
+    parser.add_argument(
+        "--theme",
+        choices=("mono", "classic", "neon"),
+        default="mono",
+        help="牌桌皮肤；默认 mono 仅为红桃和方片保留颜色",
+    )
+    parser.add_argument(
+        "--coach",
+        choices=("none", "auto", "codex", "claude"),
+        default="none",
+        help="大模型教练；通过本地 CLI 复用登录态，调用频率由 --review 控制",
+    )
+    parser.add_argument(
+        "--codex-model",
+        default=os.getenv("POKER_CODEX_MODEL", "gpt-5.4-mini"),
+        help="Codex 模型；默认使用响应较快的 gpt-5.4-mini",
+    )
+    parser.add_argument(
+        "--claude-model",
+        default=os.getenv("POKER_CLAUDE_MODEL", "haiku"),
+        help="Claude Code 模型；默认 haiku，省额度，可改为 sonnet 等别名",
+    )
+    parser.add_argument(
+        "--review",
+        choices=("tournament", "hand", "none"),
+        default="tournament",
+        help="复盘频率；默认锦标赛结束后整体复盘，hand 为每手细节模式",
+    )
+    parser.add_argument("--list-opponents", action="store_true", help="列出 AI 与离线对手选项后退出")
+    parser.add_argument("--stack", type=int, default=1500, help="每位玩家起始筹码")
+    parser.add_argument("--small-blind", type=int, default=5)
+    parser.add_argument("--big-blind", type=int, default=10)
+    parser.add_argument("--hands", type=int, default=0, help="最多手数，0 表示持续游戏")
+    parser.add_argument(
+        "--blind-speed",
+        choices=tuple(BLIND_SPEEDS),
+        default="normal",
+        help="升盲速度：turbo=2、fast=4、normal=8、slow=12 手一级",
+    )
+    parser.add_argument(
+        "--hands-per-level",
+        type=int,
+        default=None,
+        help="自定义每个盲注级别持续手数，优先于 --blind-speed",
+    )
+    parser.add_argument("--no-save", action="store_true", help="关闭每手结束后的自动存档")
+    parser.add_argument(
+        "--no-history",
+        action="store_true",
+        help="不把已完成手牌追加到长期记录",
+    )
+    parser.add_argument(
+        "--online-policy",
+        choices=("key", "all"),
+        default="all",
+        help="key 仅在关键局面调用模型；all 每个 AI 行动都调用",
+    )
+    parser.add_argument("--seed", type=int, default=None, help="固定随机种子，便于测试")
+    return parser
+
+
+def _menu_choice(prompt: str, options: dict[str, str], default: str) -> str:
+    for key, label in options.items():
+        suffix = "（默认）" if key == default else ""
+        print(f"  {key}. {label}{suffix}")
+    while True:
+        try:
+            selected = input(f"{prompt} [{default}] > ").strip() or default
+        except EOFError:
+            return default
+        if selected in options:
+            return selected
+        print("请输入菜单前面的数字。")
+
+
+def _positive_number(prompt: str, default: int) -> int:
+    while True:
+        try:
+            raw = input(f"{prompt} [{default}] > ").strip()
+        except EOFError:
+            return default
+        if not raw:
+            return default
+        if raw.isdigit() and int(raw) > 0:
+            return int(raw)
+        print("请输入正整数。")
+
+
+def configure_quick_start(args: argparse.Namespace) -> argparse.Namespace:
+    if args.review != "none" and args.coach == "none":
+        args.coach = "auto"
+    if sys.stdin.isatty() and sys.stdout.isatty():
+        return _configure_keyboard_menu(args)
+    while True:
+        _print_setup_page(args)
+        try:
+            selected = input("修改编号；直接回车开桌；Q 退出 > ").strip().upper()
+        except EOFError:
+            selected = ""
+        if not selected:
+            _finalize_setup(args)
+            print("\n设置完成，正在开桌…")
+            return args
+        if selected == "Q":
+            args.setup_cancelled = True
+            return args
+        if selected not in {
+            *map(str, range(1, 10)),
+            "A",
+            "B",
+            "C",
+            "D",
+            "E",
+            "F",
+            "G",
+        }:
+            print("请输入页面左侧的设置编号。")
+            continue
+        _edit_setup_option(args, selected)
+
+
+def _finalize_setup(args: argparse.Namespace) -> None:
+    if args.mode == "heads-up":
+        args.players = 2
+    if args.review == "none":
+        args.coach = "none"
+
+
+def _model_for_provider(args: argparse.Namespace, provider: str) -> str:
+    return args.codex_model if provider == "codex" else args.claude_model
+
+
+def _model_setup_row(args: argparse.Namespace) -> tuple[str, str, str]:
+    if args.opponent == "codex":
+        return ("Codex模型", args.codex_model, "Mini / 5.4 / Terra / Sol")
+    if args.opponent == "claude":
+        return ("Claude模型", args.claude_model, "Haiku / Sonnet / Opus")
+    if args.opponent == "agent":
+        return (
+            "模型组合",
+            f"{args.codex_model} + {args.claude_model}",
+            "轻量 / 标准 / 强力",
+        )
+    return ("模型", "不使用", "离线对手不调用模型")
+
+
+def _setup_rows(args: argparse.Namespace) -> tuple[tuple[str, str, str, str], ...]:
+    opponent = {
+        "agent": "Codex + Claude",
+        "codex": "Codex",
+        "claude": "Claude",
+        "mixed": "离线混合",
+    }.get(args.opponent, args.opponent)
+    review = {
+        "tournament": "整届结束",
+        "hand": "每手",
+        "none": "关闭",
+    }[args.review]
+    coach = {
+        "auto": "自动",
+        "codex": "Codex",
+        "claude": "Claude",
+        "none": "本地",
+    }[args.coach]
+    level_hands = (
+        args.hands_per_level
+        if args.hands_per_level is not None
+        else BLIND_SPEEDS[args.blind_speed]
+    )
+    model_label, model_value, model_choices = _model_setup_row(args)
+    return (
+        ("1", "玩法", "锦标赛" if args.mode == "tournament" else "单挑", "锦标赛 / 单挑"),
+        ("2", "人数", str(args.players if args.mode == "tournament" else 2), "6 / 5 / 4 / 3 / 2"),
+        ("3", "对手", opponent, "混合在线 / Codex / Claude / 离线"),
+        ("4", model_label, model_value, model_choices),
+        ("5", "复盘", review, "整届 / 每手 / 关闭"),
+        ("6", "教练", coach, "自动 / Codex / Claude / 本地"),
+        ("7", "起始筹码", str(args.stack), "1500 / 3000 / 1000 / 自定义"),
+        ("8", "初始盲注", f"{args.small_blind}/{args.big_blind}", "5/10 / 10/20 / 15/30 / 自定义"),
+        ("9", "升盲", f"每 {level_hands} 手", "8 / 4 / 2 / 12 / 自定义"),
+        ("A", "显示", "纯文本" if args.plain else "TUI", "TUI / 纯文本"),
+        ("B", "牌桌大小", args.size, "Mini / Compact / Auto / Large"),
+        ("C", "皮肤", args.theme, "Mono / Classic / Neon"),
+        ("D", "动画", args.speed, "正常 / 快速 / 慢速"),
+        ("E", "自动存档", "关闭" if args.no_save else "开启", "开启 / 关闭"),
+        ("F", "长期记录", "关闭" if args.no_history else "开启", "开启 / 关闭"),
+        (
+            "G",
+            "AI 调用",
+            "关键局面" if args.online_policy == "key" else "每次行动",
+            "关键局面 / 每次行动",
+        ),
+    )
+
+
+def _setup_table(args: argparse.Namespace, selected: int | None = None) -> Table:
+    rows = _setup_rows(args)
+    table = Table(
+        title="TERMINAL HOLD'EM · 开局设置",
+        box=box.ROUNDED,
+        header_style="bold",
+        border_style="grey58",
+        padding=(0, 1),
+    )
+    table.add_column("编号", justify="center", no_wrap=True)
+    table.add_column("设置", no_wrap=True)
+    table.add_column("当前值", no_wrap=True)
+    table.add_column("可选值")
+    for index, (key, label, current, choices) in enumerate(rows):
+        table.add_row(
+            key,
+            label,
+            f"‹ {current} ›" if index == selected else current,
+            choices,
+            style="reverse bold" if index == selected else None,
+        )
+    return table
+
+
+def _print_setup_page(args: argparse.Namespace) -> None:
+    table = _setup_table(args)
+    Console().print(table)
+
+
+def _setup_menu_view(args: argparse.Namespace, selected: int) -> Group:
+    buttons = Text(justify="center")
+    buttons.append(" ENTER  开始游戏 ", style="reverse bold")
+    buttons.append("    ")
+    buttons.append(" ESC / Q  返回退出 ", style="bold")
+    help_text = Text(
+        "↑↓ / Tab 选择    ←→ 切换选项",
+        justify="center",
+        style="dim",
+    )
+    return Group(
+        Align.center(_setup_table(args, selected)),
+        Text(""),
+        Align.center(buttons),
+        Align.center(help_text),
+    )
+
+
+def _configure_keyboard_menu(args: argparse.Namespace) -> argparse.Namespace:
+    from .tui import read_navigation_key
+
+    console = Console()
+    descriptor = sys.stdin.fileno()
+    original = termios.tcgetattr(descriptor)
+    selected = 0
+    start_game = False
+    live = Live(
+        _setup_menu_view(args, selected),
+        console=console,
+        screen=True,
+        auto_refresh=False,
+    )
+    try:
+        tty.setcbreak(descriptor)
+        live.start(refresh=True)
+        while True:
+            key = read_navigation_key(descriptor)
+            if key in {"down", "\t"}:
+                selected = (selected + 1) % len(_setup_rows(args))
+            elif key in {"up", "shift_tab"}:
+                selected = (selected - 1) % len(_setup_rows(args))
+            elif key in {"right", " "}:
+                _cycle_setup_option(args, _setup_rows(args)[selected][0], 1)
+            elif key == "left":
+                _cycle_setup_option(args, _setup_rows(args)[selected][0], -1)
+            elif key in {"\r", "\n"}:
+                start_game = True
+                break
+            elif key in {"q", "\x1b"}:
+                break
+            elif key == "\x03":
+                raise KeyboardInterrupt
+            elif key == "\x04":
+                raise EOFError
+            live.update(_setup_menu_view(args, selected), refresh=True)
+    finally:
+        termios.tcsetattr(descriptor, termios.TCSADRAIN, original)
+        live.stop()
+    if start_game:
+        _finalize_setup(args)
+        print("设置完成，正在开桌…")
+    else:
+        args.setup_cancelled = True
+    return args
+
+
+def _cycle_value(current: object, options: tuple, direction: int) -> object:
+    try:
+        index = options.index(current)
+    except ValueError:
+        index = 0 if direction < 0 else -1
+    return options[(index + direction) % len(options)]
+
+
+def _cycle_setup_option(args: argparse.Namespace, selected: str, direction: int) -> None:
+    if selected == "1":
+        args.mode = _cycle_value(
+            args.mode, ("tournament", "heads-up"), direction
+        )
+        if args.mode == "heads-up":
+            args.players = 2
+    elif selected == "2":
+        args.players = _cycle_value(args.players, (6, 5, 4, 3, 2), direction)
+    elif selected == "3":
+        args.opponent = _cycle_value(
+            args.opponent, ("agent", "codex", "claude", "mixed"), direction
+        )
+    elif selected == "4":
+        if args.opponent == "codex":
+            args.codex_model = _cycle_value(
+                args.codex_model, CODEX_MODELS, direction
+            )
+        elif args.opponent == "claude":
+            args.claude_model = _cycle_value(
+                args.claude_model, CLAUDE_MODELS, direction
+            )
+        elif args.opponent == "agent":
+            args.codex_model, args.claude_model = _cycle_value(
+                (args.codex_model, args.claude_model),
+                MIXED_MODEL_PRESETS,
+                direction,
+            )
+    elif selected == "5":
+        args.review = _cycle_value(
+            args.review, ("tournament", "hand", "none"), direction
+        )
+    elif selected == "6":
+        args.coach = _cycle_value(
+            args.coach, ("auto", "codex", "claude", "none"), direction
+        )
+    elif selected == "7":
+        args.stack = _cycle_value(
+            args.stack, (1000, 1500, 2000, 3000, 5000), direction
+        )
+    elif selected == "8":
+        blinds = _cycle_value(
+            (args.small_blind, args.big_blind),
+            ((5, 10), (10, 20), (15, 30), (25, 50)),
+            direction,
+        )
+        args.small_blind, args.big_blind = blinds
+    elif selected == "9":
+        args.hands_per_level = _cycle_value(
+            (
+                args.hands_per_level
+                if args.hands_per_level is not None
+                else BLIND_SPEEDS[args.blind_speed]
+            ),
+            (2, 4, 6, 8, 12),
+            direction,
+        )
+    elif selected == "A":
+        args.plain = not args.plain
+    elif selected == "B":
+        args.size = _cycle_value(
+            args.size, ("mini", "compact", "auto", "large"), direction
+        )
+    elif selected == "C":
+        args.theme = _cycle_value(
+            args.theme, ("mono", "classic", "neon"), direction
+        )
+    elif selected == "D":
+        args.speed = _cycle_value(
+            args.speed, ("normal", "fast", "slow"), direction
+        )
+    elif selected == "E":
+        args.no_save = not args.no_save
+    elif selected == "F":
+        args.no_history = not args.no_history
+    elif selected == "G":
+        args.online_policy = _cycle_value(
+            args.online_policy, ("key", "all"), direction
+        )
+
+
+def _edit_setup_option(args: argparse.Namespace, selected: str) -> None:
+    if selected == "1":
+        choice = _menu_choice("玩法", {"1": "锦标赛", "2": "单挑"}, "1")
+        args.mode = {"1": "tournament", "2": "heads-up"}[choice]
+        if args.mode == "heads-up":
+            args.players = 2
+    elif selected == "2":
+        choice = _menu_choice(
+            "人数",
+            {"1": "6 人", "2": "5 人", "3": "4 人", "4": "3 人", "5": "2 人"},
+            "1",
+        )
+        args.players = {"1": 6, "2": 5, "3": 4, "4": 3, "5": 2}[choice]
+    elif selected == "3":
+        choice = _menu_choice(
+            "对手",
+            {
+                "1": "Codex / Claude Code 混合桌",
+                "2": "全部 Codex",
+                "3": "全部 Claude Code",
+                "4": "纯离线混合桌",
+            },
+            "1",
+        )
+        args.opponent = {"1": "agent", "2": "codex", "3": "claude", "4": "mixed"}[
+            choice
+        ]
+    elif selected == "4":
+        if args.opponent == "codex":
+            choice = _menu_choice(
+                "Codex 模型",
+                {
+                    "1": "gpt-5.4-mini：响应快",
+                    "2": "gpt-5.4：标准",
+                    "3": "gpt-5.6-terra：更强",
+                    "4": "gpt-5.6-sol：最强",
+                },
+                "1",
+            )
+            args.codex_model = CODEX_MODELS[int(choice) - 1]
+        elif args.opponent == "claude":
+            choice = _menu_choice(
+                "Claude Code 模型",
+                {
+                    "1": "Haiku：响应快",
+                    "2": "Sonnet：标准",
+                    "3": "Opus：最强",
+                },
+                "1",
+            )
+            args.claude_model = CLAUDE_MODELS[int(choice) - 1]
+        elif args.opponent == "agent":
+            choice = _menu_choice(
+                "混合桌模型",
+                {
+                    "1": "轻量：Codex mini + Claude Haiku",
+                    "2": "标准：Codex 5.4 + Claude Sonnet",
+                    "3": "强力：Codex Sol + Claude Opus",
+                },
+                "1",
+            )
+            args.codex_model, args.claude_model = MIXED_MODEL_PRESETS[
+                int(choice) - 1
+            ]
+    elif selected == "5":
+        choice = _menu_choice(
+            "复盘频率",
+            {"1": "整届结束后", "2": "每手细节", "3": "关闭"},
+            "1",
+        )
+        args.review = {"1": "tournament", "2": "hand", "3": "none"}[choice]
+    elif selected == "6":
+        choice = _menu_choice(
+            "复盘教练",
+            {"1": "自动", "2": "Codex", "3": "Claude Code", "4": "仅本地简评"},
+            "1",
+        )
+        args.coach = {"1": "auto", "2": "codex", "3": "claude", "4": "none"}[choice]
+    elif selected == "7":
+        choice = _menu_choice(
+            "起始筹码",
+            {"1": "1500", "2": "3000", "3": "1000", "4": "自定义"},
+            "1",
+        )
+        args.stack = (
+            _positive_number("输入每位玩家的起始筹码", args.stack)
+            if choice == "4"
+            else {"1": 1500, "2": 3000, "3": 1000}[choice]
+        )
+    elif selected == "8":
+        choice = _menu_choice(
+            "初始盲注",
+            {"1": "5 / 10", "2": "10 / 20", "3": "15 / 30", "4": "自定义"},
+            "1",
+        )
+        if choice == "4":
+            args.small_blind = _positive_number("输入小盲", args.small_blind)
+            args.big_blind = _positive_number("输入大盲", args.big_blind)
+            while args.big_blind <= args.small_blind:
+                print("大盲必须大于小盲。")
+                args.big_blind = _positive_number("重新输入大盲", args.small_blind * 2)
+        else:
+            args.small_blind, args.big_blind = {
+                "1": (5, 10),
+                "2": (10, 20),
+                "3": (15, 30),
+            }[choice]
+    elif selected == "9":
+        choice = _menu_choice(
+            "升盲速度",
+            {
+                "1": "正常：每 8 手",
+                "2": "快速：每 4 手",
+                "3": "极速：每 2 手",
+                "4": "慢速：每 12 手",
+                "5": "自定义",
+            },
+            "1",
+        )
+        if choice == "5":
+            args.hands_per_level = _positive_number("每个级别持续几手", 8)
+        else:
+            args.blind_speed = {
+                "1": "normal",
+                "2": "fast",
+                "3": "turbo",
+                "4": "slow",
+            }[choice]
+            args.hands_per_level = None
+    elif selected == "A":
+        args.plain = _menu_choice(
+            "显示方式", {"1": "TUI 可视化牌桌", "2": "纯文本"}, "1"
+        ) == "2"
+    elif selected == "B":
+        choice = _menu_choice(
+            "牌桌大小",
+            {"1": "Mini", "2": "Compact", "3": "Auto", "4": "Large"},
+            "1",
+        )
+        args.size = {"1": "mini", "2": "compact", "3": "auto", "4": "large"}[choice]
+    elif selected == "C":
+        choice = _menu_choice(
+            "皮肤", {"1": "Mono", "2": "Classic", "3": "Neon"}, "1"
+        )
+        args.theme = {"1": "mono", "2": "classic", "3": "neon"}[choice]
+    elif selected == "D":
+        choice = _menu_choice(
+            "动画速度", {"1": "正常", "2": "快速", "3": "慢速"}, "1"
+        )
+        args.speed = {"1": "normal", "2": "fast", "3": "slow"}[choice]
+    elif selected == "E":
+        args.no_save = _menu_choice(
+            "自动存档", {"1": "开启", "2": "关闭"}, "1"
+        ) == "2"
+    elif selected == "F":
+        args.no_history = _menu_choice(
+            "长期牌局记录", {"1": "开启", "2": "关闭"}, "1"
+        ) == "2"
+    elif selected == "G":
+        choice = _menu_choice(
+            "AI 调用频率",
+            {"1": "每次行动", "2": "仅关键局面（每手最多 3 次）"},
+            "1",
+        )
+        args.online_policy = {"1": "all", "2": "key"}[choice]
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    if raw_argv == ["usage"]:
+        tracker = ModelUsageTracker()
+        tracker.refresh_codex_quota()
+        print(tracker.detailed_summary(include_empty=False))
+        return 0
+    if raw_argv and raw_argv[0] == "ranges":
+        return ranges_command(raw_argv[1:])
+    if raw_argv and raw_argv[0] == "history":
+        return history_command(raw_argv[1:])
+    resume_payload = None
+    if raw_argv and raw_argv[0] == "resume":
+        if len(raw_argv) != 1:
+            print("继续游戏只需运行：poker resume", file=sys.stderr)
+            return 2
+        try:
+            resume_payload = load_tournament_save()
+        except SaveGameError as error:
+            print(error, file=sys.stderr)
+            return 2
+        args = build_parser().parse_args([])
+        for key, value in resume_payload["config"].items():
+            if hasattr(args, key):
+                setattr(args, key, value)
+    else:
+        args = build_parser().parse_args(raw_argv)
+    if not raw_argv:
+        apply_settings(args, load_settings())
+        args = configure_quick_start(args)
+        if getattr(args, "setup_cancelled", False):
+            return 0
+        try:
+            save_settings(settings_from_namespace(args))
+        except SettingsError as error:
+            print(f"开局设置未保存：{error}", file=sys.stderr)
+    if args.hands_per_level is not None and args.hands_per_level < 1:
+        print("--hands-per-level 必须至少为 1", file=sys.stderr)
+        return 2
+    if args.list_opponents:
+        print("可用对手：")
+        print("  agent      本地 Codex / Claude Code 混合桌（复用登录态）")
+        print("  codex      全部使用本地 Codex")
+        print("  claude     全部使用本地 Claude Code")
+        print("  mixed      混合桌｜五名不同风格的离线对手")
+        for profile in BOT_PROFILES.values():
+            print(f"  {profile.key:10} {profile.name}｜{profile.description}")
+        return 0
+    try:
+        usage_tracker = ModelUsageTracker()
+        coach = (
+            None
+            if args.coach == "none"
+            else LocalCLICoach(
+                args.coach,
+                codex_model=args.codex_model,
+                claude_model=args.claude_model,
+                usage_tracker=usage_tracker,
+            )
+        )
+        if args.mode == "tournament":
+            return run_tournament(
+                args,
+                coach,
+                resume_payload,
+                usage_tracker=usage_tracker,
+            )
+        if args.opponent in {"agent", "codex", "claude"}:
+            provider = _local_agent_providers(args.opponent)[0]
+            online_budget = (
+                OnlineDecisionBudget()
+                if args.online_policy == "key"
+                else None
+            )
+            opponent = LocalAgentCLIController(
+                provider,
+                "Mason",
+                thinking_sink=_plain_thinking,
+                notice_sink=print,
+                online_decision=(
+                    online_budget.claim if online_budget is not None else None
+                ),
+                model=_model_for_provider(args, provider),
+                usage_tracker=usage_tracker,
+            )
+            opponent_name = "Mason"
+        elif args.opponent == "llm":
+            opponent = LLMController()
+            opponent_name = "大模型对手"
+        else:
+            profile_key = "balanced" if args.opponent in {"local", "mixed"} else args.opponent
+            profile = BOT_PROFILES[profile_key]
+            bot_seed = None if args.seed is None else args.seed + 1
+            opponent = OfflineBot(profile_key, rng=random.Random(bot_seed))
+            opponent_name = profile.name
+        game = HeadsUpGame(
+            HumanController(),
+            opponent,
+            starting_stack=args.stack,
+            small_blind=args.small_blind,
+            big_blind=args.big_blind,
+            opponent_name=opponent_name,
+            seed=args.seed,
+        )
+    except (ValueError, CoachError) as error:
+        print(f"配置错误：{error}", file=sys.stderr)
+        return 2
+
+    print("终端德州（Heads-up No-Limit Hold'em）")
+    if args.opponent in {"agent", "codex", "claude"}:
+        print("AI 对手：复用本地 Codex / Claude Code 登录态")
+    elif args.opponent == "llm":
+        print(f"LLM 对手：{os.environ.get('POKER_LLM_MODEL')}（请求仅包含其手牌与公开信息）")
+    else:
+        print(f"离线对手：{opponent_name}（对局过程不访问网络）")
+    if coach is not None:
+        print(f"赛后教练：{coach.provider}（通过本地 CLI 登录态，仅在每手结束后调用）")
+    completed = 0
+    history_store = None if args.no_history else HandHistoryStore()
+    history_session_id = uuid.uuid4().hex
+    try:
+        while all(player.stack >= args.big_blind for player in game.players):
+            result = game.play_hand()
+            _record_hand(
+                history_store,
+                game,
+                result,
+                session_id=history_session_id,
+                mode="heads-up",
+            )
+            print(format_review(result))
+            if coach is not None:
+                print(f"\n── {coach.provider} 深度复盘 ──")
+                try:
+                    print(coach.review(result))
+                except CoachError as error:
+                    print(f"本手大模型复盘不可用：{error}")
+            print(f"\n筹码｜你 {game.players[0].stack}｜对手 {game.players[1].stack}")
+            completed += 1
+            if args.hands and completed >= args.hands:
+                break
+            if not args.hands and not _continue_next_hand():
+                break
+    except (EOFError, KeyboardInterrupt):
+        print("\n游戏已结束。")
+    print(f"\n── 模型用量 ──\n{usage_tracker.detailed_summary()}")
+    return 0
+
+
+def ranges_command(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="poker ranges",
+        description="管理带明确来源的翻前范围数据",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    import_parser = subparsers.add_parser("import", help="校验并导入 JSON 范围包")
+    import_parser.add_argument("file")
+    subparsers.add_parser("list", help="列出已经导入的来源和局面")
+    subparsers.add_parser("path", help="显示本机范围目录")
+    subparsers.add_parser("example", help="显示可导入 JSON 格式")
+    args = parser.parse_args(argv)
+    library = RangeLibrary()
+
+    if args.command == "path":
+        print(library.directory)
+        return 0
+    if args.command == "example":
+        print(
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "source": {
+                        "name": "Your FreeBetRange or solver export",
+                        "url": "https://help.freebetrange.com/Export/",
+                        "note": "User-owned export; do not label guessed data as solver output.",
+                    },
+                    "spots": [
+                        {
+                            "id": "6max-75bb-sb-vs-btn-open",
+                            "format": "MTT ChipEV",
+                            "players": 6,
+                            "stack_bb": 75,
+                            "ante_bb": 0,
+                            "position": "SB",
+                            "scenario": "VS_OPEN",
+                            "opener": "BTN",
+                            "open_size_bb": 2,
+                            "actions": {
+                                "raise": "AA,KK,AKs:0.5",
+                                "call": "AKs:0.5,QQ",
+                            },
+                        }
+                    ],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 0
+    if args.command == "list":
+        spots = library.spots()
+        if not spots:
+            print(f"尚未导入范围。目录：{library.directory}")
+            return 0
+        for spot in spots:
+            opener = f" {spot.opener}" if spot.opener else ""
+            print(
+                f"{spot.spot_id}｜{spot.source.name}｜{spot.players}-max｜"
+                f"{spot.position}｜{spot.stack_bb:g}BB｜{spot.scenario}{opener}｜"
+                f"ante {spot.ante_bb:g}BB"
+            )
+        return 0
+    try:
+        target, count = library.import_pack(args.file)
+    except RangePackError as error:
+        print(f"范围包无效：{error}", file=sys.stderr)
+        return 2
+    print(f"已校验并导入 {count} 个带来源局面：{target}")
+    return 0
+
+
+def history_command(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="poker history",
+        description="查看跨锦标赛保存的长期牌局记录",
+    )
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=("list", "stats", "path"),
+        default="list",
+    )
+    parser.add_argument("--limit", type=int, default=10)
+    args = parser.parse_args(argv)
+    store = HandHistoryStore()
+    if args.command == "path":
+        print(default_history_path())
+        return 0
+    if args.limit < 1:
+        print("--limit 必须至少为 1", file=sys.stderr)
+        return 2
+    try:
+        records = store.records()
+    except HistoryError as error:
+        print(error, file=sys.stderr)
+        return 2
+    print(format_history_summary(records, limit=args.limit))
+    print(f"\n原始记录：{store.path}")
+    return 0
+
+
+def run_tournament(
+    args: argparse.Namespace,
+    coach: LocalCLICoach | None,
+    resume_payload: dict | None = None,
+    *,
+    usage_tracker: ModelUsageTracker | None = None,
+) -> int:
+    usage_tracker = usage_tracker or ModelUsageTracker()
+    history_store = None if args.no_history else HandHistoryStore()
+    history_session_id = (
+        str(resume_payload["config"].get("tournament_id"))
+        if resume_payload is not None
+        and resume_payload["config"].get("tournament_id")
+        else uuid.uuid4().hex
+    )
+    use_tui = not args.plain and sys.stdin.isatty() and sys.stdout.isatty()
+    table = None
+    if use_tui:
+        try:
+            from .tui import RichHumanController, TournamentTUI
+        except ImportError:
+            print("未安装 Rich，已回退到纯文本模式。运行 pip install -e . 可启用牌桌。")
+            use_tui = False
+    if use_tui:
+        table = TournamentTUI(
+            animation_speed=args.speed,
+            theme=args.theme,
+            size=args.size,
+            usage_tracker=usage_tracker,
+        )
+        hero_controller = RichHumanController(table)
+        event_sink = table.log
+        state_sink = table.render
+        thinking_sink = table.set_thinking
+    else:
+        hero_controller = HumanController()
+        event_sink = print
+        state_sink = None
+        thinking_sink = _plain_thinking
+
+    bot_names = ("Mason", "Olivia", "Liam", "Chloe", "Ethan")
+    saved_profiles = (
+        resume_payload["config"].get("seat_profiles")
+        if resume_payload is not None
+        else None
+    )
+    if isinstance(saved_profiles, list) and len(saved_profiles) == 5:
+        mixed_profiles = [str(profile) for profile in saved_profiles]
+    else:
+        mixed_profiles = ["aggressive", "tight", "tricky", "balanced", "aggressive"]
+        profile_rng = random.Random(None if args.seed is None else args.seed + 10_000)
+        profile_rng.shuffle(mixed_profiles)
+    local_agent_providers = (
+        _local_agent_providers(args.opponent)
+        if args.opponent in {"agent", "codex", "claude"}
+        else []
+    )
+    online_budget = (
+        OnlineDecisionBudget()
+        if local_agent_providers and args.online_policy == "key"
+        else None
+    )
+    personas = (
+        "patient, position-aware, and capable of disciplined folds",
+        "assertive but selective, preferring initiative over loose calls",
+        "observant and deceptive, using traps sparingly",
+        "pragmatic and pot-control oriented with medium-strength hands",
+        "adaptive and pressure-oriented when stacks and position allow",
+    )
+    seats: list[tuple[str, object]] = [("你", hero_controller)]
+    for seat_index in range(1, args.players):
+        name = bot_names[seat_index - 1]
+        if local_agent_providers:
+            provider = local_agent_providers[(seat_index - 1) % len(local_agent_providers)]
+            controller = LocalAgentCLIController(
+                provider,
+                name,
+                thinking_sink=thinking_sink,
+                notice_sink=event_sink,
+                persona=personas[seat_index - 1],
+                online_decision=(
+                    online_budget.claim if online_budget is not None else None
+                ),
+                model=_model_for_provider(args, provider),
+                usage_tracker=usage_tracker,
+                fast_forward=(
+                    (lambda: table.fast_forward_requested)
+                    if table is not None
+                    else None
+                ),
+            )
+        elif args.opponent == "llm":
+            controller = LLMController()
+        else:
+            if args.opponent in {"local", "mixed"}:
+                profile_key = mixed_profiles[(seat_index - 1) % len(mixed_profiles)]
+            else:
+                profile_key = args.opponent
+            bot_seed = None if args.seed is None else args.seed + seat_index
+            controller = OfflineBot(
+                profile_key,
+                rng=random.Random(bot_seed),
+                samples=140,
+            )
+        seats.append((name, controller))
+
+    game = TournamentGame(
+        seats,  # type: ignore[arg-type]
+        starting_stack=args.stack,
+        small_blind=args.small_blind,
+        big_blind=args.big_blind,
+        hands_per_level=(
+            args.hands_per_level
+            if args.hands_per_level is not None
+            else BLIND_SPEEDS[args.blind_speed]
+        ),
+        seed=args.seed,
+        event_sink=event_sink,
+        state_sink=state_sink,
+    )
+    tournament_results = []
+    if resume_payload is not None:
+        try:
+            tournament_results = restore_tournament(game, resume_payload)
+        except SaveGameError as error:
+            print(f"无法继续游戏：{error}", file=sys.stderr)
+            return 2
+        print(
+            f"已继续存档｜第 {game.hand_id + 1} 手待开始｜"
+            f"盲注 {game.small_blind}/{game.big_blind}"
+        )
+    print(
+        f"单桌锦标赛｜{args.players} 人｜起始筹码 {game.starting_stack}｜"
+        f"每 {game.hands_per_level} 手升盲"
+    )
+    if coach is not None:
+        print(f"赛后教练：{coach.provider}")
+    if "codex" in local_agent_providers or (
+        coach is not None and coach.provider == "codex"
+    ):
+        usage_tracker.refresh_codex_quota_async(force=True)
+    save_config = _tournament_save_config(args, game, mixed_profiles)
+    save_config["tournament_id"] = history_session_id
+    autosave_enabled = not args.no_save
+    save_path = None
+    if autosave_enabled and resume_payload is None:
+        try:
+            save_path = save_tournament(game, tournament_results, save_config)
+        except SaveGameError as error:
+            autosave_enabled = False
+            print(f"自动存档不可用：{error}", file=sys.stderr)
+    completed = 0
+    try:
+        while game.hero_alive and not game.is_over:
+            if table is not None:
+                table.start()
+            result = game.play_hand()
+            tournament_results.append(result)
+            _record_hand(
+                history_store,
+                game,
+                result,
+                session_id=history_session_id,
+                mode="tournament",
+            )
+            continue_requested = True
+            if table is not None:
+                continue_requested = table.wait_for_next_hand()
+                table.stop()
+            if args.review == "hand" and result.hero_decisions:
+                print(format_review(result))
+                if coach is not None:
+                    print(f"\n── {coach.provider} 深度复盘 ──")
+                    try:
+                        print(coach.review(result))
+                    except CoachError as error:
+                        print(f"本手大模型复盘不可用：{error}")
+            standings = "｜".join(
+                f"{player.name} {player.stack}"
+                for player in sorted(game.players, key=lambda item: item.stack, reverse=True)
+            )
+            print(f"\n筹码榜｜{standings}")
+            completed += 1
+            if autosave_enabled:
+                try:
+                    save_path = save_tournament(
+                        game,
+                        tournament_results,
+                        save_config,
+                    )
+                except SaveGameError as error:
+                    autosave_enabled = False
+                    print(f"自动存档不可用：{error}", file=sys.stderr)
+            if args.hands and completed >= args.hands:
+                break
+            if not continue_requested:
+                break
+            if table is None and not args.hands and not _continue_next_hand():
+                break
+    except (EOFError, KeyboardInterrupt):
+        if table is not None:
+            table.stop()
+        print("\n锦标赛已暂停。")
+    finally:
+        if table is not None:
+            table.stop()
+
+    if game.is_over:
+        outcome = f"冠军：{game.champion}"
+        print(f"\n🏆 冠军：{game.champion}")
+    elif not game.hero_alive:
+        outcome = f"玩家最终名次：第 {game.hero_place} 名"
+        print(f"\n你已被淘汰，最终名次：第 {game.hero_place} 名")
+    else:
+        outcome = "锦标赛未完成，本次为阶段性总结"
+
+    if args.review == "tournament" and tournament_results:
+        print(format_tournament_review(tournament_results, outcome))
+        if coach is not None:
+            print(f"\n── {coach.provider} 锦标赛整体复盘 ──")
+            try:
+                print(coach.review_tournament(tournament_results, outcome))
+            except CoachError as error:
+                print(f"大模型整体复盘不可用：{error}")
+    if game.is_over or not game.hero_alive:
+        if autosave_enabled:
+            remove_save()
+    elif save_path is not None:
+        print(f"\n进度已保存｜下次运行 poker resume")
+    print(f"\n── 模型用量 ──\n{usage_tracker.detailed_summary()}")
+    return 0
+
+
+def _tournament_save_config(
+    args: argparse.Namespace,
+    game: TournamentGame,
+    seat_profiles: list[str],
+) -> dict:
+    keys = (
+        "opponent",
+        "mode",
+        "players",
+        "plain",
+        "speed",
+        "size",
+        "theme",
+        "coach",
+        "codex_model",
+        "claude_model",
+        "review",
+        "stack",
+        "small_blind",
+        "big_blind",
+        "hands",
+        "seed",
+        "blind_speed",
+        "online_policy",
+        "no_history",
+    )
+    config = {key: getattr(args, key) for key in keys}
+    config["hands_per_level"] = game.hands_per_level
+    config["seat_profiles"] = list(seat_profiles)
+    config["no_save"] = False
+    return config
+
+
+def _local_agent_providers(opponent: str) -> list[str]:
+    requested = ("codex", "claude") if opponent == "agent" else (opponent,)
+    providers = [provider for provider in requested if shutil.which(provider)]
+    if not providers:
+        names = "Codex 或 Claude Code" if opponent == "agent" else opponent
+        raise ValueError(f"找不到本地 {names} 命令")
+    return providers
+
+
+def _plain_thinking(actor: str, provider: str | None) -> None:
+    if provider is not None:
+        print(f"{actor}｜{provider.upper()} thinking…", flush=True)
+
+
+def _record_hand(
+    store: HandHistoryStore | None,
+    game: object,
+    result: HandResult,
+    *,
+    session_id: str,
+    mode: str,
+) -> None:
+    if store is None:
+        return
+    try:
+        store.append(
+            build_hand_record(
+                game,
+                result,
+                session_id=session_id,
+                mode=mode,
+            )
+        )
+    except HistoryError as error:
+        print(f"长期牌局记录不可用：{error}", file=sys.stderr)
+
+
+def _continue_next_hand() -> bool:
+    while True:
+        prompt = "\n下一手｜1 继续 / 0 结束 [1] > "
+        if not sys.stdin.isatty():
+            selected = input(prompt).strip()
+        else:
+            print(prompt, end="", flush=True)
+            descriptor = sys.stdin.fileno()
+            original = termios.tcgetattr(descriptor)
+            try:
+                tty.setcbreak(descriptor)
+                selected = sys.stdin.read(1)
+                if selected == "\x03":
+                    raise KeyboardInterrupt
+                if selected == "\x04":
+                    raise EOFError
+            finally:
+                termios.tcsetattr(descriptor, termios.TCSADRAIN, original)
+            if selected in {"\r", "\n"}:
+                selected = ""
+            print(selected)
+        if selected in {"", "1"}:
+            return True
+        if selected == "0":
+            return False
+        print("请输入 1 继续，或 0 结束。")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())