安装要求

• AstrBot 框架 >= 3.4.0
• Python 3.10+
• aiosqlite >= 0.19.0
• aiohttp >= 3.8.0

安装步骤

从AstrBot插件市场安装

1. 在AstrBot管理面板中进入插件市场
2. 搜索"astrbot_plugin_poker_game"
3. 点击安装，依赖包会自动安装
4. 重启AstrBot或重新加载插件

安装验证

安装完成后，在聊天中输入 /poker 命令，如果显示帮助信息则安装成功。

平台兼容性

推荐配置：

• 最佳体验：QQ个人号 + NapCat（支持所有功能，私聊发牌体验最佳）

• 完整的德州扑克规则实现
• 支持 2-6 人房间
• 多级盲注系统 (1/2, 2/4, 5/10, 10/20, 25/50, 50/100)
• 自动发牌和奖池分配
• 实时游戏状态显示
• 私聊发送手牌，提高博弈的不确定性以及刺激性
• 智能超时机制（90秒警告，120秒自动弃牌）
• 完整的游戏结算显示（公共牌、手牌、牌型）

• 20+ 种成就类型
• 成就装备系统（在个人状态中展示）
• 进度追踪显示（带进度条）
• 奖励机制
• 支持翻页查看
• 显示成就ID便于装备

• 详细的玩家统计
• 胜率和盈亏计算
• 最佳牌型记录
• 连胜记录追踪
• 排行榜系统（按胜率排序）
• 支持翻页查看排行榜

• 玩家封禁/解封系统
• 封禁玩家列表查看
• 筹码管理
• 数据备份
• 详细统计面板
• 封禁状态实时监控

✨ 新功能

• 🏆 排行榜系统: 支持翻页的玩家排行榜，按胜率排序
• 🎯 装备成就展示: 装备的成就现在会在个人状态中显示
• 🚫 增强封禁管理: 新增封禁玩家列表查看功能
• 📊 成就系统优化: 支持翻页，显示成就ID和奖励信息

🔧 修复内容

• 修复装备成就时的递归错误
• 修复成就页面没有显示ID的问题
• 修复封禁玩家仍能创建房间的漏洞
• 修复poker_stats中的统计属性错误
• 优化游戏结算显示，增加手牌和牌型信息
• 修复游戏状态显示错误（局数和阶段）
• 优化加注逻辑显示，修复负数增量问题
• 完善超时提醒机制，删除自动过牌逻辑
• 增强房间清理逻辑，确保玩家真正退出
• 调整初始筹码为3000，更平衡的游戏体验
• 修复封禁系统时间显示错误：修复封禁参数顺序错误导致的时间显示问题
• 新增自动解封机制：系统会自动检查并解封到期的玩家
• 自动解封通告：解封时会记录日志并通知管理员
• ......

💎 界面优化

• 美化盲注级别说明界面
• 优化帮助文档的可读性
• 增加进度条显示成就进度
• 统一游戏状态显示格式

基础指令

房间管理

游戏操作

管理员指令

基本流程

1. 创建/加入房间: 选择合适的盲注级别
2. 开始游戏: 需要至少2人
3. 发牌阶段: 每人获得2张底牌
4. 下注轮次:
   • Pre-flop (翻牌前)
   • Flop (翻牌，3张公共牌)
   • Turn (转牌，第4张公共牌)
   • River (河牌，第5张公共牌)
5. 摊牌: 比较牌型大小
6. 结算: 分配奖池

牌型大小 (从大到小)

1. 皇家同花顺 (Royal Flush)
2. 同花顺 (Straight Flush)
3. 四条 (Four of a Kind)
4. 葫芦 (Full House)
5. 同花 (Flush)
6. 顺子 (Straight)
7. 三条 (Three of a Kind)
8. 两对 (Two Pair)
9. 一对 (One Pair)
10. 高牌 (High Card)

盲注系统

• 小盲注: 每轮强制下注的较小金额
• 大盲注: 小盲注的2倍
• 盲注级别: 1-6 级可选，影响游戏节奏

成就分类

基础成就

• 🎮 初出茅庐: 完成第一局游戏
• 🎯 小试牛刀: 完成10局游戏
• 🎲 老手: 完成50局游戏
• ⭐ 经验丰富: 完成100局游戏

胜利成就

• 🏆 首胜: 赢得第一局游戏
• 👑 胜利者: 赢得5局游戏
• 🎖️ 常胜将军: 赢得20局游戏

连胜成就

• 🔥 三连胜: 获得3连胜
• ⚡ 连胜高手: 获得5连胜
• 💫 连胜之王: 获得10连胜

财富成就

• 💰 小富翁: 拥有5000+筹码
• 💎 土豪: 拥有10000+筹码
• 👑 百万富翁: 拥有100000+筹码

牌技成就

• 🌟 同花大师: 用同花获胜
• 🎪 顺子专家: 用顺子获胜3次
• 👑 皇家同花顺: 获得皇家同花顺

装备成就

• 在个人状态中展示已装备的成就
• 使用 /poker_equip [成就ID] 装备解锁的成就
• 装备的成就会在您的个人信息中显示

个人统计

• 总游戏局数
• 胜负场次和胜率
• 总盈亏统计
• 最佳牌型记录
• 最长连胜记录
• 成就解锁情况

系统统计

• 总玩家数和活跃度
• 总游戏局数
• 筹码流通统计
• 房间使用情况

自动保存

• 游戏数据实时保存
• 定期自动备份
• 异常情况数据恢复

管理功能

• 手动数据备份
• 玩家数据重置
• 筹码调整

默认配置

初始筹码: 3000
每日奖励: 100
操作超时: 30秒
最大房间数: 20
玩家数限制: 2-6人

盲注级别

1. 级别1: 1/2
2. 级别2: 2/4
3. 级别3: 5/10
4. 级别4: 10/20
5. 级别5: 25/50
6. 级别6: 50/100

技术栈

• 框架: AstrBot Plugin Framework
• 语言: Python 3.10+
• 数据库: SQLite (aiosqlite)
• 异步: asyncio

项目结构

astrbot_plugin_poker_game/
├── main.py                 # 插件主文件
├── metadata.yaml          # 插件元数据
├── LICENSE                # MIT许可证文件
├── README.md              # 项目说明文档
├── requirements.txt       # 依赖包列表
├── models/                # 数据模型
│   ├── card_system.py     # 扑克牌系统
│   ├── game_engine.py     # 游戏引擎
│   ├── player_manager.py  # 玩家管理
│   └── room_manager.py    # 房间管理
└── utils/                 # 工具模块
    ├── data_persistence.py # 数据持久化
    └── ui_builder.py       # UI构建器

常见问题

Q: 无法创建房间

• 检查是否已在其他房间中
• 确认盲注级别有效 (1-6)
• 检查是否被封禁

Q: 游戏无法开始

• 确保房间有至少2人
• 检查所有玩家筹码充足
• 使用 /poker_start 手动开始

Q: 看不到手牌

• 确保开启私聊功能
• 检查机器人私聊权限
• 手牌会在游戏开始时发送

Q: 统计数据不准确

• 数据会在游戏结束后更新
• 使用管理员备份功能
• 联系管理员检查数据库

修复版本：v1.0.1 (修复了多个严重的游戏逻辑问题)

已修复的关键问题：

✅ 游戏轮转系统完全重构 - 解决了"同一玩家连续两个回合"的问题

• 移除了有问题的自动修复逻辑，重写了玩家轮转系统
• 修改游戏规则：新阶段玩家轮流先手，提高游戏公平性
• 增强轮转状态管理，防止状态冲突

✅ 游戏状态管理优化 - 修复了多个游戏流程bug

• 解决游戏状态异常变为"已结束"的问题
• 添加游戏结束状态检查，防止已结束游戏继续执行逻辑
• 优化阶段切换逻辑，确保状态一致性

✅ 性能和响应速度优化 - 大幅提升用户体验

• 离开房间响应时间从2-5秒优化到<100ms
• 解决第二个玩家需要发送两遍命令的问题
• 采用异步处理模式，分离快速操作和慢速操作

✅ 用户界面简化 - 提升普通玩家体验

• 调试功能改为管理员专用，避免普通用户界面混乱
• 紧急退出简化为单一命令 /poker_exit
• 优化帮助文档，突出核心功能

✅ 状态一致性增强 - 防止数据不同步

• 增加双重验证机制，确保玩家映射关系正确
• 实现即时状态清理，发现不一致立即修复
• 添加错误恢复机制，失败时自动恢复状态

本项目采用 MIT 许可证，详见 LICENSE 文件。

重要提示：请在使用本插件前仔细阅读以下免责声明。一旦使用，即表示您已完全理解并同意接受本声明的所有条款。

1. 性质声明
   本插件是一款纯粹的虚拟娱乐工具。插件内所有的扑克游戏均基于虚拟环境，不涉及任何形式的真实货币赌博、现金交易或财物兑换。本插件仅供用户休闲娱乐、学习扑克规则或与朋友进行虚拟社交之用。

2. 非赌博声明
   您知晓并同意：

本插件并非在线赌博平台。

所有游戏币、筹码、积分等虚拟物品均不具有任何现实货币价值，无法通过任何渠道兑换为真实货币、商品或服务。

严禁任何用户利用本插件组织或参与任何形式的非法赌博或财物竞猜活动。

3. 用户责任与风险自担
   您在使用本插件时，应出于个人娱乐目的，并自行承担所有风险：

您有责任确保您的使用行为符合您所在国家/地区的法律法规。对于因您使用本插件而可能产生的任何法律后果，由您自行承担全部责任。

开发者不对任何用户因沉迷游戏、误操作、或与他人因使用本插件而产生的任何纠纷负责。

开发者不对任何用户因试图将本插件用于非娱乐目的（如模拟赌博、练牌以进行真实赌博等）而导致的任何财务、法律或个人损失负责。

4. 年龄限制
   本插件仅面向法定成年人（通常为年满18周岁或您所在司法管辖区的法定成人年龄）提供。如果您是未成年人，请立即停止使用本插件。开发者不故意向未成年人提供任何与赌博形式相关的服务。

5. 服务变更与中断
   开发者保留随时修改、暂停或终止插件全部或部分服务的权利，无需事先通知用户。对于因服务变更、中断或终止造成的任何不便或损失，开发者不承担任何责任。

6. 免责范围
   在法律允许的最大范围内，开发者及其关联方不对任何直接、间接、偶然、特殊或后果性的损害承担责任，包括但不限于因使用或无法使用本插件、您的游戏数据丢失、或任何第三方的行为所导致的损失。

7. 最终解释权
   本声明的最终解释权归shannai37（开发者本人）所有。