掼蛋陪练 (Guandan Coach)

有教练坐在旁边的掼蛋练习环境。

现有线上掼蛋游戏只有对战、没有教学;线下牌桌练不出技术。掼蛋陪练让你与规则 AI 打完整对局,AI 教练在每一手牌后即时点评——像有个教练坐在你旁边。

在线玩:wyhcipuc.github.io/guandan-coach(纯静态托管,加到手机主屏后断网也能玩)

牌桌与记牌面板	求指点	出牌后即时点评

它能教你什么

三层教练机制,层层可开关(设置里一键控制):

1. 出牌后即时点评——你每出一手,教练立刻给评价和理由:「打得漂亮!与 AI 首选一致,保持先手压力」「队友只剩 3 张,该送小单」……不只说该出什么,更说为什么。
2. 记牌面板——两副牌 108 张的实时剩余统计,显示 N 秒后自动隐藏,逼自己记牌;点一下可重新查看。
3. 求指点——犹豫时点一下,引擎给出当前局面下的建议出牌并高亮,附一句话理由。

特性

• 完整规则引擎:发牌、牌型识别(含逢人配万能牌组合穷举)、合法判定、进贡还贡、接风、升级与打 A,全部按官方竞赛规则实现,191 个单元测试 + 黄金文件驱动。
• 规则 AI 陪练:组牌分解、跟牌/首出决策、队友配合、残局处理,千局 AI 互打模拟验证引擎永不卡死。
• 离线 PWA:Service Worker 预缓存全部产物,二次访问零网络请求;对局中刷新/杀掉应用,重开可从中断局面继续。
• 纯前端、零依赖:运行时仅 Vue 一个框架,无任何 API 调用、无账号、不收集任何数据,IndexedDB 本地存储,隐私模式下降级内存存储。

规则基准

以《江苏省掼蛋竞赛规则(2023)》为准,《竞技掼蛋竞赛规则(试行)》补充,共定案 R1–R20 条款(详见 docs/rules-decisions.md)。注意几处与民间常见玩法不同的官方定案:

• 2 是最小的普通牌(而非大于 A);A 可作 1 组顺(A-2-3-4-5)。
• 连对恰好 3 对、钢板恰好 2 组;没有「飞机」牌型(官方牌型共 10 种)。
• 抗贡需进贡方合计抓到两张大王;还贡面值 ≤10。

与习惯不一致处的教学提示由教练文案承担。

快速开始

git clone https://github.com/WYHCIPUC/guandan-coach.git
cd guandan-coach
npm install
npm run dev        # 开发:http://localhost:5173
npm test           # 191 个测试(含千局模拟,约 40s)
npm run build      # 类型检查 + PWA 产物(dist/)

部署到任意静态托管即可,详见 docs/deploy.md。

架构

graph TD
    UI["ui 牌桌 (Vue 3)"] --> Coach["coach 教练<br/>点评/建议/文案"]
    UI --> Store["store 本地存储<br/>IndexedDB + 快照"]
    Coach --> Player["player 决策器<br/>RulePlayer"]
    Player --> Engine["engine 规则引擎<br/>纯函数集"]
    UI --> Engine

Loading

一切状态变更必经 engine.advance 纯函数;对局全历史不可变留存,供记牌器统计、教练点评与快照恢复。player 决策器与教练文案均为策略接口,为将来的 ONNX 决策器 / 远程讲解器预留注入点。模块依赖单向:ui → coach → player → engine。

src/
├── engine/    # 牌组·牌型识别(含逢人配)·judge·legalMoves·advance·贡还·升级
├── player/    # Player 接口 + RulePlayer(组牌分解/跟牌/首出)+ 模拟器用随机/贪心玩家
├── coach/     # review(出牌点评)·advise(求指点)·文案策略·开关状态机
├── store/     # IndexedDB 封装·内存降级·对局快照(SC7)
├── sim/       # AI 互打千局模拟
└── ui/        # Vue 3 牌桌组件(手牌/出牌区/记牌器/教练气泡/贡牌/结算)
tests/         # 与 src 同构镜像,191 用例 + 千局模拟 + 恢复集成测试

路线图

• 规则定案表(对照官方规则原文,20 条款)
• 引擎正确性:牌型 × 逢人配 × 贡还 × 升级边界全绿
• 稳定性:1000 局 AI 互打无异常、无死锁
• RulePlayer 对弈(AI 决策 <100ms)
• 三层教练可用
• 对局中断恢复
• PWA 离线 + 静态部署
• 真机验收(iOS Safari / 微信内置浏览器)
• 自用 ≥10 局,验证「点评对提高水平有帮助」(产品验证门)

已知问题

• 出牌后手牌重排偶发残影(牌离场动画时序,待修,不影响对局)。
• 微信内置浏览器对 Service Worker 支持受限,离线体验请在 Safari/Chrome 中加主屏使用。

文档

文档	内容
docs/plans/2026-08-28-guandan-coach-design.md	设计稿:目标、决策日志、架构、NFR、成功标准
docs/plans/2026-08-28-guandan-coach-implementation.md	实施计划:39 任务分解 + 测试用例表
docs/rules-decisions.md	规则定案表 R1–R20(引擎测试的唯一规则依据)
docs/deploy.md	部署说明(GitHub Pages / 任意静态托管)
docs/plans/2026-08-28-acceptance.md	真机验收清单
docs/plans/selfplay-log.md	自用验证记录模板

定位与许可

个人自用的练习工具雏形,不收集数据、无商业化组件。尚未设置开源许可证(保留所有权利);所引用规则文本的版权归原发布机构所有。