一、速览：它到底解决什么问题

入门

做棋牌类游戏的人常遇到一个麻烦：真人玩家不好找，机器人又太蠢。写死的脚本对手三局就被看穿，测试平衡性时根本跑不出真实数据。

qmcloud/chess 想解决的就是这件事。它不是给你一副麻将，而是给你一桌永远在线、水平稳定的牌搭子——用大模型（LLM，可以理解成"会读上下文、会推理的对话大脑"）加上多个 AI 角色分工商量，让机器人的出牌更像真人。

核心卖点可以概括成三块：

  • 覆盖广：麻将 588 种、扑克 396 种、字牌 714 种，加上国际玩法共 2241 种，地方规则是它的重点
  • 决策像人：官方给出的 AI 水平参考是 ELO 1800+（一个衡量棋力的分数体系，1800 大致相当于业余高手）
  • 工程化完整：微服务架构、容器化部署、自带监控和日志方案，不是一份跑着玩的 demo 脚本

适合谁用：棋牌游戏开发团队做自动化测试和 AI 陪练、想研究多 Agent 决策的工程同学、以及需要给新手提供教学对手的产品方。

官方给出的性能指标是单次决策 < 10ms、单 Agent 内存 < 100MB、CPU 占用 < 5%。这些属于项目方自报数据，实际表现和你的规则复杂度、大模型调用方式强相关，评估时建议用自己的玩法实测。

qmcloud/chess 项目仓库封面

二、先搞清楚：为什么搜不到安装命令

入门

很多新手打开仓库第一件事是找 docker run，然后发现找不到——这不是你操作错了，而是这个项目的形态和普通开源软件不一样。

仓库里展示的是能力清单和演示入口，授权方式是商业授权，README 里也写了需要通过演示地址联系。换句话说，它更像一份"产品目录 + 技术方案书"，而不是一份可以直接下载安装的安装包。

所以正确的第一步不是折腾服务器，而是先确认三件事：

  • 看一遍官方文档和 B 站演示视频，确认它支持的玩法里有你要的那一种
  • 问清楚交付形态：是私有化部署的二进制包、Docker 镜像，还是源码授权
  • 问清楚大模型怎么接：用你自己的 API Key 还是对方提供，费用谁承担

建议把上面几个问题写成一封邮件或一段留言一次性问完，比来回挤牙膏效率高得多。因为棋牌 AI 这类系统往往需要按你的地方规则做适配，前期把需求说清楚能省掉大量返工。

另外必须提醒一句：README 里明确写了严禁用于赌博。这套东西的合法用途是游戏测试、AI 陪练、教学和数据分析，这条线不要踩。

三、部署前要准备哪些基础设施

进阶 · 推荐细读

即使拿到了交付包，它也不是装在一台小机器上就能跑的。这套系统的技术栈决定了它需要一整套配套服务。下面逐个说明，每个都配上生活化解释。

Docker（一种把软件连同运行环境打包成"集装箱"的工具，换台机器照样能开门用）。它是这类系统交付的主流方式，能省掉手动装依赖的折磨。

Kubernetes（简称 K8s，可以理解成码头的调度中心，负责把集装箱分配到哪条船上、坏了自动补一个）。如果你只做小规模测试，单机 Docker 通常够用；要压到官方说的十万级并发，就得靠它。

MySQL 8.0+ 或 PostgreSQL（账本，存放牌局记录、用户、配置这些不能丢的数据）。

Redis（前台便签，存牌局进行中的临时状态。要求是 Cluster 集群模式，因为单机会成为瓶颈）。

消息队列（RabbitMQ 或 Kafka，像传送带，把出牌事件、日志一条条排队送出去，避免高峰期堵死）。

InfluxDB（专门记"随时间变化的数据"，比如每秒的决策耗时，方便画曲线）。

还有一个前置条件容易被忽略：如果要自己编译后端，需要 Go 1.24 或更高版本。版本低了会因为语言特性不兼容而编译失败。

组件 作用 最低建议
Docker 容器运行环境 24.x 以上
MySQL / PostgreSQL 主数据库 MySQL 8.0+
Redis Cluster 牌局状态缓存 3 主 3 从起
WebSocket / gRPC 前后端通信通道 需要放行对应端口
大模型 API AI 决策大脑 需可访问外网或内网代理

如果你没有现成的运维同学，建议先用一台 4 核 8G 的云服务器跑通单机版本，确认玩法逻辑对了再往上加集群。一上来就上 K8s 会让排查问题变得非常痛苦。

四、功能导览：三类玩法怎么用

进阶 · 推荐细读

系统的玩法按四大类组织，接入时你只需要关心自己那一种。

麻将系列共 588 种，是地方规则的集中地，从各地麻将到带"癞子"的变体都覆盖在内。扑克系列 396 种，字牌系列 714 种，另外还有国际麻将、国际扑克、国际纸牌等。

真正值得讲的是它的决策方式。传统机器人是一套 if-else 规则，遇到没写过的情况就傻掉。这个框架用的是多 Agent 协同：可以理解成一桌四个性格不同的玩家，各自先想一版，再互相"商量"出一个结果。

用到的技术名词解释一下：

  • LLM：大语言模型，负责理解牌局上下文和对手习惯，是"会推理的那部分"
  • 强化学习（DQN / PPO / A3C）：让 AI 通过反复打牌自己总结经验，类似练球时不断调整手感
  • Actor 模型：每个 Agent 是一个独立小单元，互相发消息协作，不会因为一个卡住就全桌停摆

实际使用上，你需要关注的是难度调节。做测试时把 AI 调强，能快速暴露玩法漏洞；做新手教学时调弱，玩家才不会被劝退。

五、常见问题

入门

问：README 里找不到 docker-compose.yml 怎么办？
答：这是商业授权项目，部署物料通常随授权一起交付。建议直接向项目方索要部署文档，不要尝试从仓库里反推。

问：接大模型 API 会不会很贵？
答：会，这是这类方案最容易被低估的成本。一局牌里如果每个 Agent 都调用一次大模型，费用会随局数线性增长。建议先问清楚有没有"规则引擎兜底 + 大模型只在关键决策点介入"的模式。

问：端口冲突怎么排查？
答：这类系统通常要占用 HTTP/WebSocket 端口、gRPC 端口和监控端口。启动前用 ss -lntp 看一下端口有没有被占，冲突时优先改自己的配置，不要随手杀掉系统进程。

问：数据放在容器里会不会丢？
答：会。MySQL、Redis、InfluxDB 的数据目录必须挂载到宿主机磁盘上，否则容器一重建，牌局记录和训练数据全没了。这是新手最常见的翻车点。

问：反向代理是什么，为什么需要它？
答：反向代理像小区门卫，外面的人只知道门卫的电话，由他决定把请求转给里面哪一户。用 Nginx 做门卫，可以统一加 HTTPS 证书、限制访问频率、隐藏后端真实端口。

问：官方说的 10ms 延迟我达不到？
答：那个数字指的是规则引擎内部的决策耗时，不包括大模型网络往返。如果你的实现对每次出牌都远程调模型，实际延迟会高出不少，这是架构选择问题而非配置问题。

六、上线之后要盯什么

深入 · 老手可选

系统本身已经规划好了可观测性方案，你需要做的是把它用起来，而不是等出事再翻日志。

Prometheus + Grafana 负责指标监控，前者像不停打点的记录员，后者把记录画成仪表盘。重点盯三个数：决策延迟、在线牌局数、大模型调用失败率。

ELK（Elasticsearch + Logstash + Kibana）负责日志检索。牌局类系统的日志量很大，出问题时靠 grep 是翻不完的，必须能按牌局 ID 快速定位。

Jaeger 负责链路追踪，能看清一次出牌请求在各服务之间走了多久，用来找瓶颈特别有效。

备份策略上，MySQL 建议每天全量加实时 binlog，Redis 至少开启 AOF 持久化。大模型相关的策略配置和提示词文件建议一起纳入版本管理，这些东西丢了很难重建。

升级时不要一次性全量替换。先用小比例流量跑新版本，确认决策质量和延迟都在正常范围，再逐步扩大——棋牌 AI 的行为变化往往不是靠单元测试能发现的，得靠真实对局数据说话。

最后回到选型本身：如果你的需求是找一套能立刻 git clone 就跑的开源棋牌引擎，这个项目可能不是。但如果你需要的是覆盖大量地方玩法、并且希望 AI 对手像真人的商业方案，那把它列进评估清单，按本文第二节的清单去问一圈，能帮你很快判断值不值得继续谈。

项目信息

项目 值
仓库 qmcloud/chess
语言 JavaScript
Star 161
Fork 85
主页 https://docs.qq.com/doc/DWFBvTERET3h1a2pT

参考链接

延伸阅读

想继续探索？这些同领域的教程可能也适合你：