如何构建扑克手牌复盘 API 工作流?

构建一个牌局结束后的复盘流程：只接受一手已结束的牌局，由确定性的 API 提供 cards、牌面、equity 和 strategy 事实，然后在用户选定学习局面后附加 GTO 查询。

更新于 2026 年 7 月 28 日维护者 Pokerai API

简短答案: 让工作流异步且面向学习：解析或回放已结束的牌局、展示可验证的牌面语义和 equity，然后查询匹配的 GTO 局面用于解释。Pokerai API 提供事实；LLM 可以解释或编排，但不能替代 solver。高影响输出必须经人工审核，也不要把它变成真钱牌桌上的实时建议。

核心事实

手牌解析	`POST /v1/pokerkit/notation/parse` 会把公开 Poker Hand History notation 解析为结构化牌局数据。
回放	`POST /v1/pokerkit/games/state` 会为提交的 actions 返回含底池、筹码、牌面、手牌和合法行动的 snapshot。
语义	`POST /v1/pokerkit/hand-report` 会为手牌和牌面返回 texture、tier、draws、outs 和 blockers。
Equity	`POST /v1/pokerkit/equity` 返回 Monte-Carlo equities 和 sample count。
GTO 查询	`POST /v1/gto/preflop` 会为文档中的翻前行动线返回预求解的混合策略。

1. 解析或回放已结束的牌局

只在牌局结束后保存手牌，然后把 Poker Hand History 文本交给 notation parser。要展示复盘时间线，可将结构化配置和 actions 提交给 game-state endpoint；其 snapshot 为 UI 提供客观的底池、筹码、牌面、手牌和合法行动视图。

{"text": "variant = \"NT\"\nante_trimming_status = true\nantes = [0, 0]\nblinds_or_straddles = [1, 2]\nmin_bet = 2\nstarting_stacks = [200, 200]\nactions = [\"d dh p1 AhKh\", \"d dh p2 QsQd\", \"p1 cbr 6\", \"p2 cc\", \"d db Qh7c2d\"]\n"}

{"result": {"variant": "NT", "ante_trimming_status": true, "antes": [0, 0], "blinds_or_straddles": [1, 2], "bring_in": null, "small_bet": null, "big_bet": null, "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p1 cbr 6", "p2 cc", "d db Qh7c2d"], "automations": [{"name": "ANTE_POSTING", "value": "Ante posting"}, …], "author": null, "event": null, "day": null, "month": null, "year": null, "hand": null, "currency": null}}

2. 解释牌面和手牌语义

在选定街次，用玩家的 hole 和 board 调用 hand-report endpoint。将返回的 texture、成牌 tier、draws、outs 和 blockers 渲染为标签和证据；不要从这些描述字段推导出推荐行动。

{"hole": "JhTh", "board": "AsKsQs"}

{"result": {"texture": {"cards": ["As", "Ks", "Qs"], "wetness": {"name": "WET", "value": "Wet"}, "connectivity": {"name": "HIGH", "value": "High"}, "rank_band": {"name": "HIGH", "value": "High"}, "straight_draw": {"name": "OPEN_ENDED", "value": "Open-ended"}, "flush_draw": {"name": "LIVE", "value": "Live"}, "are_two_tone": false, "are_monotone": true, "are_rainbow": false}, "tier": {"category": {"name": "STRAIGHT", "value": "Straight"}, "is_nut": false, "pair_tier": null, "two_pair_tier": null, "three_of_a_kind_tier": null, "kicker_tier": null, "nut_rank": {"name": "NON_NUT", "value": "Non-nut"}}, "draws": {"straight_draw": null, "flush_draw": null, "nut_rank": null}, "outs": {"by_category": {}, "count": 0}}}

3. 连同抽样语境估算 equity

要做复盘比较，可把已知 ranges、board、sample count 和 seed 提交给 equity endpoint。每个 equity 都应与返回的 sample_count 一同展示；它只是给定范围和牌面的估算，不是对下一张牌的承诺，也不是下注指令。

{"ranges": [["AA"], ["KK"]], "board": "", "sample_count": 2000, "seed": 7}

{"result": {"equities": [0.8235, 0.1765], "sample_count": 2000}}

4. 为复盘解释附加 GTO 查询

把重建出的翻前行动线映射到文档中的 preflop lookup。将返回的 strategy array 展示为混合频率，并解释用户应按频率选择；该复盘步骤必须与实时游戏分离。

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"MP"},"preflop_version":"6max_RC_100bb_200NL",
       "preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},
                          {"position":"BB","action":"big blind","amount":1},
                          {"position":"UTG","action":"raise","amount":3}]}'

5. 构建解释 UI，而不是行动提示

按稳定顺序展示：手牌时间线、牌面和手牌事实、equity 估算、GTO 策略频率。标明输入、返回字段、街次和假设。展示备选行动与频率，而不是一个“立即行动”按钮。

仅限训练和复盘

只接受已经结束的牌局，并将此工作流用于一手牌结束后的训练、教学、手牌复盘、学习和研究。重要的教学或产品输出需要人工审核。禁止在真实资金牌桌上提供实时辅助。不要接入实时牌桌数据流、自动选择行动，或提供牌局进行中的推荐界面。