简介：一套用 JavaScript 实现的德州扑克机器人源码包，让 Slack 渠道或私人小组中的 2～10 名玩家直接通过 @机器人 指令完成发牌、底牌私发、动作询问、手牌判定与底池分配，适合对即时通讯机器人、棋牌规则引擎或 AI 打牌策略感兴趣的开发者。压缩包共 84 个文件，主体为 24 个 JavaScript 逻辑文件（牌堆、手牌评估、彩池管理、玩家交互、机器人 AI 等模块），辅以 52 张扑克牌面 PNG、JSON 配置、README 与测试文件，整体仅 1.71MB，结构清晰、便于快速阅读和二次开发。已有 464 人学习下载。源码包含 weakBot 与 aggroBot 两种简单 AI 策略，并自带基于 rx 的 Slack API 封装、牌面图片生成及完整 spec 测试用例，既能直接部署到 Heroku 或本地，也可作为理解复杂牌局状态机、概率比较与异步消息处理的实践参考。项目涵盖牌堆生成、手牌评估、底池管理等核心模块，目录与测试组织得当，可帮助开发者快速掌握完整机器人实现思路。

1. 把一桌德州扑克搬进 Slack 频道：这个 Java 开源 bot 到底解决了什么

先说服你再点下载。德州扑克的完整对局涉及并发玩家、复杂的先后顺序、大量回合状态，而这套系统开源的 java-slack-poker-bot 把整件事压进一个不需要公网 IP、不需要手工改造后端、直接在 Slack 客户端里跑完的机器人。它解决的不只是娱乐问题，也是三类工程问题的合集：事件驱动服务怎么接第三方平台、博弈状态机怎么在真实消息流里保持稳定、以及一套对局逻辑如何被多人重复调用的幂等设计。适合的读者很具体：想给团队加一个互动工具的后端开发者、初级 Java 工程师想读懂状态机与命令解析的完整实现，以及任何手里有一个 Slack 工作区、想在下班后开一局又不愿自己从零写发牌逻辑的人。文末我会把复现过程中最值得看的几个模块拆开讲。

2. 机器人核心设计：从 Slack 事件到牌桌状态机的完整流转

这个 bot 表面上是一堆“发牌、加注、弃牌”的对话，实际上是一个事件驱动的三明治结构：最外层接 Slack 的三个入口（消息提及、斜杠命令、按钮交互），中间层做文本解析和身份校验，最内层是一个维护整桌游戏状态的状态机。调试时最容易翻车的不是牌型判断，而是最外层和最内层之间的接口——谁先执行、谁后执行、状态什么时候变更，全在这一层决定。下面按接入选型、状态机、动作解析三个角度拆开。

2.1 Slack 接入选型：为什么 Socket Mode 是本地复现的主力

传统 Slack 应用的 Events API 需要你准备一个公网 HTTPS 回调地址，每次配置还要处理签名校验、回调超时、SSL 证书问题。对本地复现一个开源 bot 来说，这套流程能把半天时间耗在跟网络环境缠斗上。java-slack-poker-bot这类面向 Slack 交互的 bot 普遍改用 Socket Mode：Slack 主动建立一个 WebSocket 长连接，事件、斜杠命令、按钮交互全部从这条连接推给本地进程。你不需要公网 IP，不需要配置反向代理，本地gradlew bootRun起来就能收到真实频道的消息。

接入时注意两个 token 的区别，这是第一个常见的玄学坑。

• SLACK_APP_TOKEN（xapp-开头）：认证 Socket Mode 连接本身，只有这个 token 能让长连接建立成功。
• SLACK_BOT_TOKEN（xoxb-开头）：调用chat.postMessage这类 REST API 时用，发牌、通知、更新消息都需要它。

我一般会把两个 token 直接导出为环境变量，项目里只留占位符，避免源码被传开后 token 泄露。订阅事件方面，最小配置只需要app_mention（有人 @bot）、message.channels（监听频道消息）和斜杠命令/poker。如果之后要加按钮操作，再补block_actions交互回调。Socket Mode 下斜杠命令的请求 URL 可以留空，因为它不再走 HTTP 回调，这对本地调试是最大的省心点。

2.2 牌桌状态机：发牌、下注、摊牌五个状态的边界划分

一手德州扑克从开局到结算，至少要经历“等待入座 → 发底牌 → 翻牌 → 转牌 → 河牌 → 摊牌”六个阶段。如果只是用布尔变量标记“是否开局”，后面一定会被各种顺序问题缠住。更稳妥的做法是把牌桌生命周期定义成显式状态枚举，每次动作只允许在合法状态下发生。

public enum TableState { WAITING_PLAYERS, // 空闲等待，允许加入座位 PRE_FLOP, // 已发底牌，第一轮下注 FLOP, // 已翻三张公共牌，第二轮下注 TURN, // 已发第四张公共牌，第三轮下注 RIVER, // 已发第五张公共牌，最后一轮下注 SHOWDOWN, // 全部行动结束，进入摊牌判定 HAND_END; // 本局结算完成，等待下一手 }

每种状态都有明确的进入条件和离开条件。PRE_FLOP只有在至少两名玩家入座、并且已完成底注盲注之后才能进入；FLOP必须等所有存活玩家在PRE_FLOP轮都行动完毕才能进入。状态流转集中在一个同步方法里，比到处散落if (isPlaying)判断更容易排查。

public synchronized TableEvent transition(PlayerAction action) { if (action.actor() != this.currentActor) { return new TableEvent(REJECTED, "还没有轮到你行动"); } switch (this.state) { case PRE_FLOP, FLOP, TURN, RIVER -> applyBet(action); case SHOWDOWN -> { return settle(); } default -> { return new TableEvent(IGNORED, "本局尚未开始"); } } if (isAllActionsCompleted()) { moveToNextStreet(); } return new TableEvent(ACCEPTED, "行动成功"); }

这段代码有两个必须说清楚的参数行为。currentActor表示当前轮次内轮到谁行动，它在每次moveToNextStreet()时按座位顺序重新计算，而不是简单按玩家入座顺序排。synchronized修饰不能省，因为 Slack 事件重试和玩家快速连点可能让同一个方法被并发调用，如果不同步，两个玩家几乎同时 call 时可能造成底池金额重复累计。使用锁的代价极小，一桌最多几个玩家，完全构不成性能瓶颈。

2.3 文本指令解析器：从 “/poker raise 5” 到 ActionType

Slack 斜杠命令把消息文本传到 bot，但真正驱动桌游的是动作类型和金额。解析器要做的事很单纯：把字符串映射成结构化的PlayerAction。

public PlayerAction parse(SlashCommandInteraction cmd) { String text = cmd.getText().trim(); // 例如 "raise 5" 或 "fold" String[] parts = text.split("\\s+"); ActionType type = switch (parts[0].toLowerCase()) { case "fold" -> ActionType.FOLD; case "call" -> ActionType.CALL; case "check" -> ActionType.CHECK; case "raise", "bet" -> ActionType.RAISE; case "allin" -> ActionType.ALL_IN; default -> throw new IllegalArgumentException("未知动作"); }; int amount = 0; if (parts.length > 1) { amount = Integer.parseInt(parts[1]); } return new PlayerAction(cmd.getChannelId(), cmd.getUserId(), type, amount); }

解析本身不复杂，但amount的语义要特别留意。这套源码里的raise 5到底表示“把当前注额加到 5”还是“在当前基础上再加 5”，直接影响筹码计算。我在复现时专门去翻applyBet的实现，确认后发现很多开源实现把amount当作“加注后的目标总额”，而不是“加注增量”。你的玩法预期如果是后者，就需要在解析器里把amount改成currentBet + amount再传下去。新手照着写时最容易在这里出现“我明明只加了 5，筹码却扣了 20”的怪现象。

解析出的动作还要经过一层校验才能进入状态机：金额不能为负、不能超过玩家筹码、raise 不能低于最小加注步长。这层校验放在解析器里还是状态机里，各有利弊。放在解析器里可以让非法输入尽早返回报错文案，放在状态机里可以统一处理所有入口（包括以后加按钮交互）。我个人的做法是两边都做：解析器拦截明显的格式错误，状态机再做权威校验。

3. 把源码跑起来：从注册 Slack 应用到本地发牌实测

理论讲完，下一步是让这个 bot 在真实频道里跑起来。整个过程分三段：建 Slack 应用、配置 token、启动并验证一局牌。这里最花时间的不是 Java 代码，而是 Slack 应用管理后台里的几个配置项。它们的位置容易找，但漏掉任何一个，表现出的症状都像“代码没跑对”。

3.1 创建 Slack 应用：三个页面上的最小配置

打开 Slack 应用管理面板，创建一个新应用。这里有一个选择：用 manifest 配置还是手工逐项配置。手工配置更能理解每一项的作用，建议第一次复现不要偷懒。

1. 进入 “Socket Mode” 页面，开启 Socket Mode，此时会生成一个xapp-开头的 app-level token，保存到本地环境变量.env或 shell 里。
2. 进入 “OAuth & Permissions” 页面，添加 Bot Token Scopes：chat:write（发消息）、app_mentions:read（接收提及）、commands（注册斜杠命令）。然后点击 Install App 到工作区，拿到xoxb-开头的 bot token。
3. 进入 “Slash Commands” 页面，创建命令/poker，请求 URL 留空即可。Socket Mode 下，斜杠命令事件不再向外部 URL 发送，而是从 WebSocket 推给本地应用。
4. 进入 “Event Subscriptions” 页面，启用事件订阅，勾选app_mention和message.channels。如果你只希望 bot 在被 @ 时才响应，message.channels可以不开。

配置完成后，把 token 放进环境变量：

export SLACK_APP_TOKEN=xapp-1-xxx export SLACK_BOT_TOKEN=xoxb-xxx export TABLE_MAX_PLAYERS=6 export BIG_BLIND=10

这里多说一句：xapp-和xoxb-千万别混用。xapp-只能建立 Socket Mode 长连接，xoxb-只能调 REST API。很多本地跑不起来的现象，最终都是把xapp-填到了 bot token 的位置导致认证失败。

3.2 启动与首局验证：从命令行到 Slack 频道全路径

代码拉下来后，先看项目的构建文件是 Maven 还是 Gradle。这个项目用 Gradle，启动命令比较简单：

git clone <源码仓库地址> poker-bot cd poker-bot export SLACK_APP_TOKEN=xapp-1-xxx export SLACK_BOT_TOKEN=xoxb-xxx ./gradlew bootRun

启动成功的标志是日志出现类似Socket mode connected的输出，说明 WebSocket 已经建立。如果卡在连接阶段，基本是SLACK_APP_TOKEN不对，或者 Socket Mode 没在应用后台开启。

然后打开你的 Slack 工作区，在频道里发送：

/poker start

bot 会回复一个开局消息，通常是列出当前玩家列表和盲注大小。之后让至少一位同事或自己的另一个账号发送/poker join入座，凑够两人后发/poker deal发牌。后续每轮行动就输入/poker call、/poker raise 20、/poker fold。

如果不想在真实频道里反复试错，项目里一般还会留一个本地调试端点。我在复现时用这类接口快速验证流程，请求格式长这样：

curl -X POST http://localhost:8080/internal/test/deal \ -H 'Content-Type: application/json' \ -d '{"channel":"C123","user":"U456","text":"raise 10"}'

这个端点的作用是不经过 Slack，直接模拟一条玩家动作消息推进状态机。生产环境必须把这个端点关掉或拒绝外部访问，否则任何人都能往你的牌桌里塞假动作。

3.3 关键配置参数：一张表看清哪些值影响对局行为

复现过程中最值得提前设置的参数都集中在配置文件里。整理成表后，新手照着改就不容易改错：

MIN_RAISE_STEP值得特别注意。德州扑克规则要求每次加注至少不能低于当前最大注额的一半或一个盲注，如果设为 0，会出现“一个人无限加 1 筹码”的死循环。这个参数是规则层面防呆的一个重要关口。

4. 避坑与常见问题：我在调试中踩出的五个坑

复现这个 bot 的过程里，我大概有一半时间不是花在理解 Java 代码上，而是在跟 Slack 的事件机制周旋。下面五条是实打实的血泪经验，每条都按现象、原因、解决三步写，照着检查能省掉大量排查时间。

4.1 同一手牌被发两次：Slack 事件重试与幂等处理

现象：玩家刚收到底牌还没行动，频道里又弹出一手新牌，而且两张手牌一模一样；有时一手牌被完整结算两次。

原因：Slack 对应用事件有一个 ack 机制，如果应用在 3 秒内没有返回确认，Slack 会判定发送失败并重试同一个事件。很多处理器的写法是“先完整跑完摸牌流程，再返回 ack”，一旦摸牌过程涉及数据库或远程调用超过 3 秒，事件就会被重发。

解决：事件进入处理器时立刻 ack，再把真正的游戏逻辑放到异步线程。另外，给事件 ID 做本地去重缓存，处理过的event_id直接丢弃，双保险。

public void onEvent(SlackEvent event) { if (processedEventIds.contains(event.getId())) { return; // 重复事件，直接忽略 } processedEventIds.add(event.getId()); // 先返回 200，再异步处理 executorService.submit(() -> handleGameEvent(event)); }

这个方法对同样接入 Slack 的 bot 都适用，不只是扑克场景。把“接收”和“处理”分成两段，是避免事件重试引发重复操作的通用做法。

4.2 多桌并发串台：channel id 成为状态 key

现象：两个不同频道同时开盘，A 频道的玩家弃牌后，B 频道的牌桌也跟着强制弃牌；或者 bot 提示“还没有轮到你行动”，但实际发消息的人确实是当前行动者。

原因：牌桌状态被保存成单一实例字段，没有区分频道。第二个频道的开局直接覆盖了第一个频道的状态，所有玩家共用一个PokerTable对象。这是典型的状态 key 缺失。

解决：用channelId作为维度隔离牌桌。并发场景下用ConcurrentHashMap存放多张桌子，键是channelId + ":" + gameId。

private final ConcurrentHashMap<String, PokerTable> tables = new ConcurrentHashMap<>(); public PokerTable getTable(String channelId, String gameId) { return tables.computeIfAbsent( channelId + ":" + gameId, key -> new PokerTable(channelId, gameId) ); }

从那以后我每次写这类多玩家交互服务，都会先检查状态集合的 key 是否包含“频道 + 对局”两个维度。只有频道维度，跨频道串台是必然的事。

4.3 斜杠命令三秒超时：交互响应与游戏逻辑必须解耦

现象：玩家输入/poker start后，Slack 客户端转圈很久，最后显示“请求失败”；但服务端日志显示开局已经成功了。

原因：Slack 对斜杠命令的响应时间限制是 3 秒。如果命令处理器里同步完成了建桌、发牌、给全员发消息等多步操作，超过 3 秒就触发超时。服务端逻辑照常跑完了，但 Slack 已经放弃等待，把错误展示给用户。

解决：命令处理器只负责返回一个“已收到”的确认文本，把实际游戏动作提交到线程池或消息队列。这样响应时间保持在 3 秒以内，Slack 界面立即显示反馈，后续动作异步完成。

@SlashCommand("/poker") public String onPokerCommand(SlashCommandInteraction cmd) { String text = cmd.getText(); executorService.submit(() -> gameController.handle(cmd.getChannelId(), text)); return "正在处理中，稍等片刻..."; }

发牌、下注这些操作其实都是毫秒级事件，完全可以同步处理。真正拖慢的是向 Slack 逐个频道推送消息的网络开销。异步化之后，体验从“转圈 5 秒让你以为 bot 挂了”变成“几乎瞬间响应”。

4.4 洗牌用了 Random，牌堆被摸出规律

现象：连续几手牌的牌序异常相似，甚至能猜出下一张是大牌还是小牌。对局失去了随机性，玩家质疑 bot 作弊。

原因：源码的洗牌逻辑用了java.util.Random，并且对每个新牌组设置了固定种子。Random的线性同余算法在常规彩票类业务里够用，但在博弈场景里是可预测的——只要收集到一定数量的输出序列，就能反推出内部状态。固定种子洗出来的牌序完全确定。

解决：用SecureRandom作为Collections.shuffle的随机源，并且每手牌结束后把牌组对象直接丢弃，不重复使用。

List<Card> deck = buildDeck(); Collections.shuffle(deck, new SecureRandom());

SecureRandom的生成速度略慢，但一局牌最多洗 52 张卡片，性能损耗完全可以忽略。对博弈类接口来说，真正该担心的是随机数被预测，而不是多花几毫秒生成随机数。

4.5 点击 Block 按钮没反应：交互 endpoint 没接 block_actions

现象：在开局消息里点击“Fold”或“Call”按钮，界面没有任何变化，bot 也不响应；但用斜杠命令直接输入字母却正常。

原因：按钮是 Slack Block Kit 的交互组件，点击事件走的是interaction回调，和斜杠命令不是同一条链路。如果应用没有配置block_actions事件订阅，Slack 根本不会把按钮点击推送给 bot，表现为按钮“看起来像坏了”。

解决：在应用后台确认开启了 Interactive Components，并且在事件订阅里勾选block_actions。Socket Mode 下不需要额外配公网 URL，但要确保代码里注册了对应的事件处理器。调试时最容易误判成“代码没写按钮”，实际是事件根本没到应用里。

这五条坑有一个共同点：问题不在扑克规则本身，而在外部平台的事件机制。第一次接触这类 bot 的开发者，几乎都会在前三条里耗费不少时间。看日志时如果发现“收到了事件但没走游戏逻辑”，优先怀疑 ack 和事件订阅，而不是急着去改牌型判断代码。

5. 把 bot 改造成正式对局：自动判牌、确定性测试与对局复盘

当 bot 能正常开局、下注、摊牌之后，下一步让它真正“像样”的是三块进阶能力：自动识别最大牌型、可复现的对局测试、以及对局历史留痕。

5.1 自动判牌：从七张牌里选最大五张组合

德州扑克的判定核心是：玩家手里 2 张底牌 + 桌面上 5 张公共牌，共 7 张里挑出 5 张组成最大牌型。最高效的粗暴做法是枚举 7 选 5 的全部 21 种组合，逐一打分取最高分。牌型等级从皇家同花顺到高牌共 10 级，比较时先比等级，同等级再比关键牌点数。

public HandRank evaluate(List<Card> holeCards, List<Card> communityCards) { List<Card> all = Stream.concat(holeCards.stream(), communityCards.stream()).toList(); Rank best = null; for (int i = 0; i < all.size(); i++) { for (int j = i + 1; j < all.size(); j++) { List<Card> five = new ArrayList<>(all); five.remove(j); five.remove(i); Rank current = rankFive(five); if (best == null || current.compareTo(best) > 0) { best = current; } } } return best; }

这段代码的时间复杂度是常数级，21 种组合对现代 CPU 没有任何压力。真正的复杂度在rankFive方法里：同花判断、顺子判断、四条/葫芦/三条/两对/一对的降序比较，每一项都要写专门的判定函数。源码里这部分是独立的Rank类，建议不要跟状态机混在一起，方便后续单测。

5.2 确定性测试：用固定牌序复现整局对局

调试随机性功能时最大的痛苦是“上一手能复现，下一手复现不了”。解决办法是给洗牌环节留一个可选的固定种子入口。生产环境不设种子走SecureRandom，测试环境通过系统参数传入种子，每次跑出来的牌序完全一致。

public void shuffleDeck() { if (System.getProperty("SHUFFLE_SEED") != null) { Collections.shuffle(deck, new Random(Long.parseLong(System.getProperty("SHUFFLE_SEED")))); } else { Collections.shuffle(deck, new SecureRandom()); } }

这样做的价值在于：任何一个牌型 bug，只需要固定种子重现同一手脏牌，修改代码后再用相同种子验证修复是否生效。我在自己维护的一些随机性较强的服务里也保留同一个习惯。每拉下一个新项目，我会先确认它是否支持这种方式。不支持的话，我会手动加一个SHUFFLE_SEED环境变量，这比每次靠运气复现 bug 强得多。

如果想让 bot 从“能玩”升级到“能复盘”，最后一步是记录每手牌的对局流水：哪些玩家入池、每条街的下注额、翻牌前谁加注、最后谁赢走多少。数据落 sqlite 或者写到日志文件都行。有了这份数据，规则合理性、延迟、异常退出都能靠回放排查。从那以后，我每接一个开源 bot，都会强制自己先跑一遍固定牌序的完整对局，把从翻牌前到摊牌的路径全部走完，确认状态机没有吃事件重试的亏，再挂到正式频道上。希望帮到你。

本文还有配套的精品资源，点击获取