用 AI 工具从零做一个完整掼蛋游戏

掼蛋是风靡长三角的四人扑克玩法（两副牌、对家配合、升级争上游）。我一直想有一款「浏览器双击即玩」的单机版，但传统开发要写 UI、状态机、AI、规则引擎，工作量不小。

这次我换了个思路：把 AI 编程工具当成高级协作者，从需求拆解到代码生成、调试、测试，全程让它参与。最终产出一个 guandan.html 单文件，打开即玩（玩家 vs 三个 AI）。本文复盘它的技术架构、开发流、踩过的坑与质量保障——既是案例，也是一份「AI 辅助做小游戏」的方法论。

要做什么

• 浏览器打开即玩的单机版：1 名玩家 + 3 个 AI 对手。
• 完整掼蛋规则：牌型、升级、进贡、逢人配（万能配）、记牌器。
• 友好的交互：智能提示、上下文选牌、公开倒计时。

给自己定的约束

• 单文件 一个 .html 包含所有 HTML/CSS/JS，可移植、可双击。
• 零依赖 不引入框架、不接后端、不需要 npm 构建。
• AI 协作 需求由人定，实现与测试尽量交给 AI 工具迭代。

极简到了极致：单文件 HTML + 原生 JavaScript + CSS。没有 React/Vue，没有打包器，状态集中在一个全局对象 G 上。

核心函数（均由 AI 工具生成并逐步打磨）：

• makeCard() / G.playedCards — 牌模型与已出牌追踪。
• analyzeCards(cards) — 返回 {type, value, length} 的牌型识别。
• detectFlushBombs(hand) — 同花顺炸弹（5 张同花色连续）检测。
• onHint() / autoRecommendPlay() — 智能提示排序。
• handleCardClick() — 统一选牌逻辑（组合整选 / 拆牌单选 / 错选提示）。
• startTurnTimer() — 倒计时（玩家 20s、管不住 5s、AI 1.5s）。

为什么坚持单文件？因为目标就是「发出去别人双击就能玩」——任何构建步骤都会抬高分享门槛。

整个过程是一个稳定的闭环：

# 每一轮
人 提需求 / 贴截图反馈  →  AI 实现代码
        ↓
人 在浏览器实测  →  发现遮挡 / 卡死 / 逻辑错
        ↓
AI 定位根因并修复  →  AI 补自动化测试锁定行为

例如下面这些是「贴图反馈 → AI 修」的真实轮次：

• 过牌按钮遮住了桌面已出的牌 → 控制栏移入底部固定、提 z-index。
• 开局首出点牌无按钮、无倒计时（卡死） → 修复启动流程与层级。
• 左侧手牌顶部被标签遮挡 → 限制列标签宽度 + 提层级。
• 同花顺炸弹提示按钮点了没反应 → 事件冒泡清空了选中（见第五节）。

关键心得：把「现象」描述清楚（最好带截图），AI 的定位和修复往往一次到位；而用自动化测试把修好的行为锁住，是避免回归的核心手段。

支持全部主流牌型：单张对子三张三带二木板(三连对)钢板(三顺)顺子炸弹同花顺炸弹，并处理逢人配（万能配）——级牌可当任意牌凑组合。

识别逻辑的核心示意（真实实现约为此结构的扩展）：

function analyzeCards(cards){
  const n = cards.length;
  if (n === 1) return {type:'single', value};
  if (n === 2 && sameRank) return {type:'pair', value};
  if (n === 3 && sameRank) return {type:'trio', value};
  // 木板: 三连对 / 钢板: 三顺 / 顺子: 连续单
  // 同花顺炸弹: 5张同花色连续 —— detectFlushBombs()
  return combo;
}

三家 AI 各自决策出牌 / 跟牌 / 压牌；右侧/旁显示公开倒计时徽章——玩家 20 秒、管不住 5 秒、AI 1.5 秒，让对局节奏透明。

提示不是「随便给一手」，而是按优先级给最小能管上家的牌，尽量不拆组合：

手动出牌时，系统结合上家牌型理解玩家意图：

• 跟单牌：点哪张选哪张，明确。
• 跟组合牌：点同类型组合→一次性选中整组；点不同类型→视为拆牌，点哪张选哪张。
• 选错类型且非炸弹→弹「选牌有误」提示。
• 同张牌再点→取消选中；首出点组合→整组选中。

• 记牌器：实时统计剩余牌，炸弹数标注「炸弹供参考」（因为同花顺炸弹/万能配会影响真实数量）。
• 选牌视觉：选中卡牌放大并加深边框。
• 倒计时：蓝色大字，正常出牌 20 秒。
• 布局修复：手牌/标签/竖排牌背的遮挡问题逐一解决（见第五节）。

每修一个 bug，都补一套自动化测试，避免回归。当前共 26 套测试，23 套通过——其中核心玩法 24 套全绿，未通过的 3 套是早期（8 月初）写的 DOM mock 脚手架过期，与玩法无关。

测试跑在 Node 下：把 HTML 里的脚本逻辑 eval 出来，用最小 DOM mock 驱动，断言牌型识别、提示排序、选牌规则、同花顺炸弹、计时超时、AI 跟炸等关键路径。

已实现功能：

• 完整牌型引擎（含逢人配万能配、同花顺炸弹）
• 三家 AI 出牌 / 跟牌 / 压牌 + 公开倒计时
• 智能提示（最小能管、同类型优先、炸弹兜底）
• 上下文选牌（组合整选 / 拆牌单选 / 错选提示）
• 记牌器、进贡、升级、选牌视觉反馈
• 布局与遮挡问题修复（按钮/首出/标签/竖线）

✅ AI 工具擅长

• 样板与规则代码：牌型判定、状态机这类逻辑密集但边界清晰的工作，生成又快又准。
• 调试与定位：给出现象（最好带截图），它能快速定位层级、事件冒泡、时序类问题。
• 测试编写：把修好的行为立刻固化成测试，防止回归。
• 快速迭代：从想法到可玩原型，门槛被压到了「一个下午」。

⚠️ AI 工具不擅长 / 需人把关

• 领域合规判断：哪些功能会踩监管红线，AI 不会主动提醒，必须人来判断（本项目的棋牌类合规边界就是典型）。
• 产品级决策：做什么、不做什么、为谁做，这类需要商业与风险判断的事，人得自己拿。
• 长期架构演进：多轮叠加后，重构与解耦的方向仍需人来定。