QPDS 将量化投资的理性思维引入德州扑克决策制定。系统实时整理底牌、公共牌、底池与筹码信息，基于多因子模型计算关键指标，为玩家提供数据驱动的行动建议和详细解释。前端提供直观的双语交互界面，后端采用 Flask 架构，核心算法模块化设计，便于扩展与复用。
- 直观交互界面：浏览器内直接操作，选择牌面、调整底池筹码与风险偏好，实时查看输入摘要
- 策略近似引擎：整合胜率、底池赔率、SPR、听牌概率与位置等指标，输出混合行动频率、盈亏平衡权益和建议稳定性
- 完整双语支持：界面、提示与错误信息支持中英文无缝切换
- 模块化架构：
backend/core分离评估器、因子计算、决策引擎等组件，支持独立调用和测试 - 对手建模面板：滑块与输入快速刻画对手激进度、诈唬率、下注尺度，结果面板实时呈现画像与建议
- 牌桌终端 UI：石墨、绿色与红色区分状态和行动，支持桌面与移动端响应式操作
- 一键启动脚本：
run.py自动管理虚拟环境、依赖安装和服务启动，开箱即用
QPDS/
├── backend/
│ ├── api/ # Flask 入口与路由
│ └── core/ # 牌力评估、权益计算、因子/决策引擎
├── frontend/
│ ├── index.html # 纯 HTML/JS 前端界面
│ ├── package.json # Vite 构建与测试配置
│ └── tests/ # 静态前端契约测试
├── docs/ # 需求、设计与笔记
├── tests/ # pytest 单元测试
├── run.py # 快速启动脚本
└── requirements.txt # Python 依赖
选项1：Fork 项目（推荐用于开发）
- 点击页面右上角的 ⭐ Star 按钮收藏项目
- 点击 🍴 Fork 按钮将项目 fork 到你的 GitHub 账户
- 克隆你的 fork 到本地：
git clone https://github.com/你的用户名/QPDS.git
cd QPDS选项2：直接下载
git clone https://github.com/原作者用户名/QPDS.git
cd QPDSpython3 run.py脚本将自动完成：
- 检测并创建虚拟环境
venv/；失效的旧环境会先备份为venv.broken-时间戳 - 仅在运行依赖缺失时安装
requirements.txt - 启动后端 API 服务（默认监听 http://localhost:8080）
启动完成后，用浏览器打开 frontend/index.html 即可开始使用。保持脚本运行窗口打开，按 Ctrl+C 可随时停止服务。若页面提示「无法连接后端服务」，点击右上角 ⚙️ API配置 并填写 http://localhost:8080 即可恢复。
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
python -m pip install -r requirements.txt
python -m backend.api.app # 启动后端（默认端口 8080）前端同样通过直接打开 frontend/index.html 访问，如遇连接提示可通过 ⚙️ API配置 指向 http://localhost:8080。
兼容性提示：
requirements.txt的核心运行依赖为 Flask、flask-cors 与 NumPy。启动脚本不会删除损坏的环境，而会保留备份后重建。
- 可以线上尝试下这个系统：https://aphysickui.github.io/QPDS/
- 推荐使用 GitHub Pages + Render 组合：前端静态文件部署到 GitHub Pages，后端 Flask API 托管在 Render。
- 页面右上角新增
⚙️ API按钮，可在浏览器内填写 Render 提供的 HTTPS 地址，并保存在本地浏览器。 - 完整上线步骤与注意事项见
docs/deployment/github-pages-render.md。
- 启动系统：运行
python3 run.py，在浏览器打开frontend/index.html - 选择底牌：点击界面左上角的两个空槽，然后从牌堆中选择你的两张底牌
- 设置参数：
- 选择当前阶段（翻前/翻牌/转牌/河牌）
- 如果不是翻前，点击公共牌区域选择相应数量的公共牌
- 输入底池大小、需要跟注金额、你和对手的筹码量
- 选择你的位置（如果不确定，先选择按钮位BTN）
- 对手画像：在“对手建模”面板调整激进度、紧凶度、最近下注比例，并可记录最新动作/备注
- 获取建议：点击“获取决策建议”按钮，系统会给出推荐行动与对手画像说明
- 查看手册：点击右上角“🃏 游戏手册”了解详细规则和策略
- 底牌：选择一对A（AA）或A-K等强牌
- 阶段：从翻前开始练习
- 位置：选择按钮位（BTN），这是最有利的位置
- 底池：设置为100，跟注为20（简单的比例）
- 筹码：双方各500（常见的100大盲深度）
系统会告诉你：
- 推荐行动：加注/跟注/弃牌等
- 混合频率：在当前近似模型下各动作的相对权重
- 建议稳定性：因素轻微变化时主建议保持不变的启发式评分，不是统计置信度
- 估算 EV：基于当前范围、弃牌率和下注尺度假设的估算值
- 盈亏平衡权益：继续投入至少需要达到的权益阈值
- 关键因子：影响决策的重要数据（胜率、底池赔率等）
- 对手画像：激进度、下注压力、心理压强等指标及操作建议，帮助理解对手策略
德州扑克（Texas Hold'em）是一种流行的扑克变体，每位玩家发2张底牌，通过与5张公共牌结合组成最佳的5张牌型。
- 翻前（Pre-flop）：每位玩家获得2张底牌，根据牌力决定跟注、加注或弃牌
- 翻牌（Flop）：发出前3张公共牌，进行新一轮下注
- 转牌（Turn）：发出第4张公共牌，继续下注
- 河牌（River）：发出第5张公共牌，最后一轮下注
- 摊牌（Showdown）：比较牌型大小，最大牌型获胜
| 牌型 | 说明 | 示例 |
|---|---|---|
| 皇家同花顺 | A-K-Q-J-10同花色 | A♠ K♠ Q♠ J♠ 10♠ |
| 同花顺 | 连续5张同花色牌 | 9♥ 8♥ 7♥ 6♥ 5♥ |
| 四条 | 4张相同点数 | K♣ K♦ K♥ K♠ 3♦ |
| 葫芦 | 三条+对子 | Q♠ Q♥ Q♦ 7♣ 7♠ |
| 同花 | 5张同花色牌 | A♦ J♦ 9♦ 6♦ 2♦ |
| 顺子 | 连续5张牌 | 10♠ 9♥ 8♦ 7♣ 6♠ |
| 三条 | 3张相同点数 | 8♣ 8♦ 8♥ K♠ 4♦ |
| 两对 | 两个对子 | A♠ A♥ 5♣ 5♦ 9♠ |
| 一对 | 一个对子 | J♦ J♠ 10♥ 8♣ 3♦ |
| 高牌 | 无以上牌型 | A♠ K♦ Q♥ 8♣ 5♠ |
- 底池赔率（Pot Odds）：当前跟注所需筹码与底池大小的比例
- 隐含赔率（Implied Odds）：考虑后续可能赢得筹码的赔率
- 位置（Position）：相对于庄家位置，后位置有信息优势
- 筹码-底池比（SPR）：有效筹码除以底池大小
- 听牌（Draw）：需要特定牌才能成牌的牌型（如同花听牌、顺子听牌）
德州扑克中位置极其重要，决定了你的行动顺序和信息优势：
- UTG（枪口位）：翻前第一个行动，信息最少，需要最强的起手牌
- UTG+1, UTG+2：紧随其后的位置，仍需要较强手牌
- MP1, MP2, MP3：可以适当放宽手牌要求，观察前位行动
- LJ（劫匪位）, HJ（劫持位）：可以观察多数玩家行动后决策
- CO（截断位）：仅次于按钮位的优势位置
- BTN（按钮位）：翻后永远最后行动，最有利位置
- SB（小盲位）：翻后第一个行动，位置最差但已有投入
- BB（大盲位）：翻前最后行动权，需考虑底池赔率
新手提示：前位要紧，后位要松。按钮位可以用更宽的范围加注和偷盲，而UTG位置需要非常谨慎的手牌选择。
- 紧凶（TAG）：只玩强牌但玩得激进
- 松凶（LAG）：玩较多牌型且激进下注
- 价值下注：有强牌时下注获取价值
- 诈唬（Bluff）：用弱牌下注迫使对手弃牌
- 半诈唬：用听牌下注，既可能成牌也可能让对手弃牌
德州扑克没有一个可以直接套用到所有牌桌的完整“最优策略表”。目前研究结论需要按游戏类型区分：
- 单挑限注德州扑克（HULHE）：Cepheus 在 2015 年将其“基本弱解”；这意味着其策略在终身尺度上无法被人类显著击败，并不等于枚举了每个状态的唯一动作。
- 单挑无限注德州扑克（HUNL）：DeepStack 与 Libratus 达到超人水平，使用持续重求解、抽象和子博弈求解等方法；它们是强大的近似策略，不是完整博弈树的精确 Nash 解。
- 六人无限注德州扑克：Pluribus 达到超人水平，但多人非零和博弈更难定义和计算可利用度，也没有被完整求解。
QPDS 当前返回的 strategy_mode 是 heuristic_equilibrium_approximation。它用蒙特卡罗权益、多因子阈值与动作尺度抽象构造混合频率，不运行 CFR/子博弈求解器，也不能声称输出 GTO。confidence_kind=heuristic_stability 只描述建议稳定性；权益接口另行返回蒙特卡罗标准误与近似 95% 区间。
主要研究资料：
- Bowling et al., Heads-up limit hold'em poker is solved, Science, 2015.
- Moravcik et al., DeepStack: Expert-level artificial intelligence in heads-up no-limit poker, Science, 2017.
- Brown & Sandholm, Superhuman AI for heads-up no-limit poker: Libratus beats top professionals, Science, 2018.
- Brown & Sandholm, Superhuman AI for multiplayer poker, Science, 2019.
- Zinkevich et al., Regret Minimization in Games with Incomplete Information, NeurIPS 2007.
- 智能牌面选择器：支持自动灰化已选卡牌、点击移除等直观操作
- 阶段智能切换：翻前/翻牌/转牌/河牌切换时自动限制公共牌数量
- 实时参数汇总：底池、跟注金额、双方筹码、风险偏好等输入即时展示
- 本地化错误提示：指导用户补全必需信息，支持中英文
- 对手建模面板：滑块控制激进度、紧凶度与情绪，配合最近下注记录生成画像
POST /api/get_recommendation：基于当前局面分析，返回推荐行动、金额、期望值与详细解释POST /api/get_equity：针对给定牌面与对手范围进行蒙特卡罗胜率模拟，并返回迭代数、标准误与近似 95% 区间GET /health：服务健康状态检查- 完整因子详情：响应包含所有关键因子明细与对手画像，便于前端展示或第三方系统集成
- 策略透明字段：建议响应包含
action_distribution、break_even_equity、strategy_mode、confidence_kind与assumptions
| 因子名称 | 含义说明 | 取值范围 | 用途 |
|---|---|---|---|
equity |
对手范围下的胜率 | 0 ~ 1 | 基础牌力评估 |
pot_odds |
跟注所需最低胜率 | 0 ~ 1 | 数学期望计算 |
hand_strength |
当前牌力强度评分 | 0 ~ 1 | 摊牌价值判断 |
stack_to_pot_ratio |
有效筹码与底池比例 | 0 ~ ∞ | 资金管理指导 |
fold_equity |
估计对手弃牌概率 | 0 ~ 1 | 诈唬决策依据 |
pot_commitment |
底池投入承诺度 | 0 ~ 1 | 风险控制评估 |
position_factor |
位置优势系数 | 0 ~ 1 | 策略调整参考 |
opponent_aggression |
对手激进指数 | 0 ~ 1 | 判断对手进攻倾向与持续下注频率 |
opponent_tightness |
对手紧凶度 | 0 ~ 1 | 估计对手可持续的起手范围宽度 |
betting_pressure |
下注压力 | 0 ~ 1 | 评估对手当前街施压强度，指导反击/弃牌 |
board_pressure |
牌面压力 | 0 ~ 1 | 公共牌对对手范围的帮助程度 |
range_advantage |
范围优势 | 0 ~ 1 | 对比双方组合覆盖度，判断谁在牌面上受益 |
psychological_pressure |
心理压强 | 0 ~ 1 | 综合筹码差、下注节奏与气势，衡量心理博弈 |
bluff_tendency |
诈唬倾向 | 0 ~ 1 | 判断对手诈唬频率，辅助跟注/弃牌决策 |
运行完整测试套件：
source venv/bin/activate
pytest运行特定测试模块：
pytest tests/test_hand_evaluator.py # 测试牌力评估器
pytest -k "factor" # 运行所有因子相关测试
pytest -v # 详细输出模式测试覆盖牌型/听牌识别、权益与多人平分、缓存隔离、因子引擎、策略输出和 API 输入验证。前端测试锁定多人参数、零值展示、不确定性信息与对话框语义；它们不是完整的端到端浏览器测试。
Q: 依赖安装失败或旧虚拟环境无法运行 A: 再次运行启动脚本，它会将失效环境备份后重建。也可以手动创建新环境：
python3 -m venv venv-new
venv-new/bin/python -m pip install -r requirements.txtQ: 前端无法获取推荐结果 A: 请检查：
- 后端服务是否正常启动（访问 http://localhost:8080/health 应返回
{"status": "healthy", "service": "QPDS API"}） - 浏览器控制台是否有跨域或网络错误
- 页面右上角的
⚙️ API配置是否指向正在运行的后端（本地为http://localhost:8080，线上请填写 Render 的 HTTPS 地址）
Q: 界面显示异常或翻译缺失 A: 刷新页面或清除浏览器缓存，确保 JavaScript 正常加载。
Q: 对手建模面板应该如何填写？ A: 可以先根据直觉拖动滑块，例如激进度 0 表示极度被动，10 表示疯狂进攻。若掌握最近一手牌的下注金额，可在“最近动作”处注明金额与行动前底池；否则留空也会根据滑块生成画像。填写备注有助于未来牌局快速回忆对手习惯。
- 双语交互前端界面与牌局输入系统
- 多因子计算引擎与决策 REST API
- 德州扑克游戏规则集成与手册功能
- 对手建模（滑块调节 + 行为画像 + 心理因子）
- 移动端响应式输入、多人权益估算与策略近似透明字段
- 手牌历史分析：解析历史牌局数据，支持回放与复盘
- 对手建模进阶版：叠加多手牌历史、自动范围拟合
- 数据持久化：手牌记录存储与统计分析
- 回测系统：策略效果验证与优化建议
- 前端现代化：迁移至 Vue/React + TypeScript 架构
- 机器学习增强：基于大量手牌数据的策略优化
- 求解器基准：建立小型抽象子博弈，用 CFR/CFR+ 计算可利用度并校准启发式策略
- 多人策略模型：从多人权益估算扩展至位置、行动顺序与独立对手范围建模
本项目基于 MIT 协议开源，详情参见 LICENSE。
- 扑克牌力评估算法基于 Cactus Kev's evaluator 实现
- 蒙特卡罗模拟方法借鉴 PokerStove 设计思路
- 量化分析框架参考现代投资组合理论
如有问题或建议，欢迎在 GitHub 上提交 Issue。
也可以通过我的个人博客联系：https://akuiro24.xyz/
免责声明：本工具仅供教育学习使用。在使用扑克辅助工具前，请务必确认平台政策合规性。