帮助零基础玩家从第一局开始学会掼蛋的网页游戏 —— 完整真实的掼蛋对局 + 实时讲解的 AI 教练，纯前端、零依赖、双击即玩。
掼蛋规则不难，难的是没人告诉你每手牌为什么这么打。本项目把「真实对局」和「教练讲解」合二为一：你打的是完整真实的掼蛋（两副牌 · 4 人两两组队 · 从 2 打到 A · 升级过 A 制），每次轮到你出牌时，右侧的 AI 教练给出出牌方案和通俗的中文理由；对手 BOT 分三档难度，从会犯错的入门陪练到会拆牌、留炸弹、压制报牌的高手教练。
全部逻辑在客户端实现（不调用任何外部 API），断网可玩，PWA「添加到主屏幕」后可原生全屏运行。
- 完整掼蛋流程：两副牌 108 张全发 → 级牌（打几）→ 轮流出牌 / 接风 → 头游定名次 → 升级制（双上 +3 / 头游三游 +2 / 头游末游 +1）→ 过 A 获胜
- 🎓 AI 教练侧边栏：局势概览 + 可折叠中文分析 + 可点选方案列表（推荐恒第一）；桌面停靠右侧，移动端为抽屉，打完自动收起
- 教学式纠错：选牌实时显示牌型与「是否压得上家」；非法牌型 / 压不过时用通俗中文解释；出牌按钮实时置灰
- 三档难度 BOT：🐣 入门（会犯错）/ ⚔️ 进阶（拆牌、留炸弹、偶尔忍牌）/ 🔥 高手（最少手数拆解、队友让牌、对手报牌压制）
- 学习辅助：内置新手教程（5 章节）、记牌器（含队友亮牌）、报牌红点（≤10 张）、接风提示、纵向智能理牌三模式、拖动批量选牌、跨场战绩统计（localStorage）
- 结算展示：本手名次表（🥇🥈🥉 徽章）、级牌推进图示（如「我方 5 ➜ 8（+3 级）」）、整场过 A 弹窗 + 胜利彩带
- 多端适配：桌面 / 窄屏抽屉 / 横屏手机紧凑档 / 竖屏旋转提示；启动门一键全屏 + 锁定横屏；WebAudio 合成 20 种场景音效 + 循环 BGM；支持 prefers-reduced-motion
- 组队：你与正上方对家一队（对家亮牌），对抗左右两侧对手
- 级牌：每手打一个点数（每场从 2 起），红桃级牌是逢人配万能配（可补成除王外任意牌型）
- 牌型：单张 / 对子 / 三同张 / 三带二 / 顺子（恰 5 张）/ 连对（≥3 对）/ 钢板（≥2 组三同张）/ 炸弹（4~8 张同点）/ 同花顺 / 四王炸
- 大小：大王 > 小王 > 级牌 > A > K > … > 2；炸弹压普通牌，张数多压张数少
- 胜负：头游方按队友名次升级；本方头游且队友非末游即过 A，先过 A 者赢下整场
- 接风：头游最后一手无人压时，由对家队友接风继续出牌
| 方式 | 操作 |
|---|---|
| 🌐 在线游玩 | studyguy.github.io/guandan-master-glm（GitHub Actions 自动发布） |
| 💻 直接游玩 | 克隆仓库后双击 index.html（已验证 file:// 协议可用） |
| 🖥️ 本地服务器 | npx http-server -p 8642 -c-1 或 python3 -m http.server 8642 |
运行测试（需 Node.js）：
node test/sim.js
# 39 项逻辑断言（牌型/压制链/万能配/走法/教练/收轮与接风回归）
# + 3 难度 × 20 手 4-BOT 对局仿真 + 1 场"从 2 打到过 A"整场升级验证AI 教练为纯客户端启发式算法（离线可玩）：
- 手牌拆解：把 27 张手牌拆成尽量少的「手数」，作为局势评估核心
- 方案生成：从合法走法中挑出 1~6 个候选（推荐 / 最小 / 最大 / 炸弹 / 让过徽章），推荐恒第一
- 决策：能一手跑完直接赢 → 对手报牌时压制 → 队友的牌让行 → 炸弹看时机；教练在决策之上输出中文讲解，并对你的每手出牌对比点评
规则开关（js/rules.js 的 DD.RULES，适配区域差异）：起始级牌随机、A2345 顺子、双王对、三带二禁王对、打 A 三败退回 2、报牌阈值、进贡/还贡/抗贡（预留）、结算展示。
调试钩子：?autotest=autoplay 全自动演示整场、&side=1 强制展开教练、?debug=1 输出元素包围盒。
guandan-master-glm/
├── index.html # 页面结构（主页 / 4 人牌桌 / 教程 / 结算）
├── css/style.css # 全部样式（卡牌纯 CSS 绘制，无图片资源）
├── js/
│ ├── rules.js # 规则开关集中配置 + 级牌序/升级表
│ ├── cards.js # 两副牌 108 张生成、洗牌、排序
│ ├── combos.js # 牌型识别（含逢人配）+ 压制比较
│ ├── movegen.js # 合法走法枚举（万能配受控展开）
│ ├── ai.js # 手牌拆解估算、三档 BOT、高手决策
│ ├── advisor.js # AI 教练：建议 + 中文讲解 + 方案点评
│ ├── sfx.js # WebAudio 合成音效
│ ├── game.js # 4 人 2 队对局状态机（事件驱动）
│ ├── ui.js # 牌桌渲染与交互
│ └── app.js # 主页、教程、自动演示与调试钩子
├── docs/ARCHITECTURE.md # 架构决策文档（继续开发前先读）
├── docs/img/ # 界面截图
├── test/sim.js # 逻辑断言 + 对局仿真 + 整场升级验证
└── PROGRESS.md # 开发进度与交接
逻辑层与表现层均已完成并通过验收（详见 PROGRESS.md）。唯一预留未实现的大项：进贡 / 还贡 / 抗贡（rules.gong 开关已预留，默认关闭）。
