精选案例 · Agent / 实践案例
🎴 Cube Draft — 游戏王在线轮抽对战系统
这个案例围绕「🎴 Cube Draft — 游戏王在线轮抽对战系统」记录了一条真实 AI 实践线索，正文重点集中在「项目概述」「技术架构」，适合先按任务意图阅读再判断复用。
案例速读
README 标题「🎴 Cube Draft — 游戏王在线轮抽对战系统」下已经出现运行/配置路径、脚本或接口线索、结果证据，正文重点集中在「项目概述」「技术架构」，比纯概念介绍更适合进入精选阅读流。 这篇案例的阅读价值在于，它把真实任务、模型辅助过程和可迁移做法放在同一个上下文里，读者可以从 「🎴 Cube Draft — 游戏王在线轮抽对战系统」、「项目概述」、「技术架构」、「AI 辅助开发过程」 进入正文。
- 建议重点看 可参考其中的运行与配置路径、包含可迁移的命令、脚本或接口线索、已有结果或观测证据可用于判断复用价值。结合 Agent / 实践案例 和「任务驱动用户、AI 实践者」这一受众定位，它更适合作为任务检索后的精读材料，而不是只看一句短摘要后快速跳过。
- 正文目录和原始材料仍然是判断依据；导读只帮助你更快定位阅读重点。
- 看点
- 🎴 Cube Draft — 游戏王在线轮抽对战系统
- 读者
- 任务驱动用户、AI 实践者
- 复用
- 可参考其中的运行与配置路径
- 结构
- 12 个目录入口
原文内容
🎴 Cube Draft — 游戏王在线轮抽对战系统
项目地址：私有仓库
关键词：Node.js、WebSocket、WASM、ocgcore、neos-ts、ygopro 协议
项目概述
从零开发一套完整的游戏王（Yu-Gi-Oh!）在线轮抽（Cube Draft）系统，包含轮抽引擎、卡组构筑、卡牌数据库、在线对战等完整功能链。支持多人房间模式，所有流程均可在浏览器中完成。
技术架构
┌─────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ ┌─────────────┐ ┌──────────────────────────────┐ │
│ │ 轮抽/组卡 UI │ │ neos-ts 图形化对战前端 │ │
│ │ (HTML/CSS/JS)│ │ (TypeScript/React) │ │
│ └──────┬──────┘ └──────────────┬───────────────┘ │
│ │ │ │
└─────────┼────────────────────────┼────────────────────┘
│ HTTP/JSON │ ygopro 二进制 WS
▼ ▼
┌──────────────────────────────────────────────────────┐
│ Node.js 后端 │
│ ┌──────────┐ ┌────────────────┐ ┌───────────────┐ │
│ │ 轮抽引擎 │ │ 对战桌管理器 │ │ ygopro 协议 │ │
│ │ │ │ (座位/卡组验证) │ │ 适配器/relay │ │
│ └──────────┘ └────────┬───────┘ └───────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────┐ │
│ │ DuelSession (ocgcore WASM) │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ koishipro-core.js │ │ │
│ │ │ └─ libocgcore.wasm │ │ │
│ │ └───────────────────────┘ │ │
│ └─────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
AI 辅助开发过程
Phase 1：从零搭建轮抽引擎
用时：约 3 天
描述：从空白项目开始，先搭建基础框架。AI 生成了 WebSocket 通信层、房间管理和基本轮抽逻辑（卡包分配、轮转选牌、计时器）。这部分 AI 出力最大，因为需求描述可以非常精确。
典型 Prompt：
“用 Node.js 写一个 WebSocket 房间管理器，支持创建房间、加入房间、离开房间。房间有 owner、players 数组、状态（waiting/drafting/playing）。每个玩家有昵称和座位号。”
结果：AI 直接生成可工作的代码，只需要微调边界条件。轮抽引擎的卡包生成、洗牌、轮转算法也都是 AI 写的，只改了一次 bug（轮次方向反转）。
Phase 2：卡组构筑与 YDK
用时：约 2 天
描述：最繁琐但 AI 最擅长的部分——卡牌搜索、拖拽交互（drag & drop）、YDK 导入/导出格式解析、剪贴板集成。这些功能纯手工写很烦，但每个功能点都很清晰，AI 一口一个。
亮点：AI 生成的 YDK 导出代码直接兼容 YGOPro 的 .ydk 格式，无需任何修改。拖拽交互也是 AI 一手包办。
Phase 3：ocgcore 对战引擎集成
用时：约 5 天（最耗时）
描述：集成 koishipro-core.js（ocgcore 的 WASM 封装）需要处理大量底层细节：WASM 加载、卡牌数据注册、Lua 脚本加载、DuelSession 状态管理。这里 AI 生成的框架代码占了 ~70%，但调试花了大量时间。
关键 Bug 记录：
| Bug | 根因 | 修复 |
|---|---|---|
WASM newCard() 崩溃 |
Node 22 与旧版 Emscripten 不兼容 | 切到 Node 20 LTS |
| 卡牌 Abort | 224 张卡片中 20 张缺少 Lua 脚本 | 下载完整脚本包 + stub |
| “版本不匹配” 误导 | ErrorType 枚举值差 1 | 修正 +1 偏移 |
| 路径导致脚本加载失败 | __dirname 深度计算错误 |
修正 .. 层数 |
| CDN 资源加载失败 | neos.config 指向外网 CDN | 全部改为本地路径 |
Phase 4：ygopro 二进制协议适配器
用时：约 2 天
描述：最让我惊喜的部分。需要写一个二进制协议适配器，在 neos-ts 的 ygopro 二进制协议和 cube-draft 的 JSON 协议之间做翻译。
AI 直接生成的协议适配器代码（~300 行）几乎零修改就通过了测试。包括：
- Stoc 包编码（长度前缀 + 类型字节 + payload）
- 6 种 CTOS 消息的解析（PLAYER_INFO、JOIN_GAME、UPDATE_DECK、HS_READY、RESPONSE、SURRENDER）
- 8 种 STOC 消息的构建（JOIN_GAME、DUEL_START、GAME_MSG、DUEL_END 等）
为什么 AI 擅长这个？因为协议转换是"规则明确的翻译工作"——输入输出格式固定，没有模糊地带。AI 的 pattern matching 能力在这里完美发挥。
Phase 5：前端集成与 Bug 修复
用时：约 3 天
描述：集成 neos-ts 前端，解决各种真实环境问题。AI 在分析 crash 日志方面帮了大忙，发给 AI 几百行的 WASM 栈回溯，它能迅速提取关键信息。
最终成果
| 功能 | 状态 |
|---|---|
| 轮抽引擎（多人房间、计时、自动轮抽） | ✅ |
| 卡组构筑（拖拽、搜索、YDK 导入/导出） | ✅ |
| 卡牌数据库（SQLite + 卡图 API） | ✅ |
| 对战桌管理（座位分配、就绪检测、卡组提交） | ✅ |
| ocgcore 对战引擎（DuelSession 完整封装） | ✅ |
| ygopro 二进制协议适配 | ✅ |
| neos-ts 图形化对战前端 | ✅ |
| 轮抽→对战全流程打通 | ✅ |
一些数字
- 代码量：约 6000 行（新增）
- AI 生成占比：~80%
- 人工调试占比：~60%（时间上）
- Bug 总数：30-40 个
- 开发到 MVP：不到 2 周
- 效率提升：约 3-5x
经验和教训
AI 擅长的
- 翻译工作：二进制协议 ↔ JSON，跨语言 API 封装
- UI 交互：拖拽、弹窗、表单等标准交互
- 数据处理：卡组验证、格式解析、排序搜索
- 框架代码：WebSocket 处理器、路由、中间件
AI 不擅长的
- 架构决策：给出"合理但不最优"的方案，需要人工把关
- 环境兼容性：Node 版本、WASM 二进制兼容性——AI 的上下文不够
- 复杂状态调试：WebSocket 连接时序、多窗口同步——AI 视野有限
- 安全考虑：不会主动考虑端口暴露、输入验证、资源泄露
关键心得
需求描述的精度决定 AI 输出的质量。 同样是描述一个功能：
❌ “写一个 WebSocket 处理函数” ✅ “写一个 ygopro 二进制协议处理函数，接收 2 字节长度 + 1 字节类型 + payload，解析 CTOS_RESPONSE 消息并透传到 duel.setResponse()”
花时间打磨 prompt，比花时间修 AI 生成的 Bug 划算得多。