日期：2026 年 4 月 13 日 —— 4 月 19 日

项目：绘画 AI 博弈小游戏 —— 人机对抗绘画猜词与心理解读系统

一、本阶段整体进度

本周项目进入实时联机与功能联调阶段，团队围绕 WebSocket 房间管理、多人实时同步、AI 难度控制、前端功能稳定性优化 四大核心方向全面推进，实现从 “后端可用” 到 “多人可玩” 的关键升级。

本阶段核心成果：

• 完成 WebSocket 多人联机房间系统，实现房间生命周期完整管理
• 实现 房间实时同步：玩家进出、状态流转、列表刷新全双工推送
• 完成 AI 多档位难度控制（Prompt Engineering），支持 easy/medium/hard 三档博弈
• 前端 Canvas 画板、行为采集、游戏状态机 全面测试与 bug 修复
• 前后端完成 房间联调，验证创建 / 加入 / 满员 / 退出 / 状态同步等核心流程，部分bug修复

模块一：需求分析与方案设计

一、功能分析

本周核心目标是搭建稳定可靠的多人联机对战体系，重点实现：

1. 房间全生命周期管理：创建→等待→开始→游戏中→结束
2. 实时状态同步：玩家列表、房间状态、游戏阶段全局一致
3. 联机权限控制：房主才能开始游戏、人数校验、重复加入拦截
4. AI 猜词难度分级：通过提示词工程控制 AI 识别强度
5. 前端稳定运行：画板、撤销、橡皮擦、行为采集无异常
6. 数据可靠不重复：防重复猜词、防重复结束回合

二、技术方案架构

整体采用：

• 通信层：Flask-SocketIO 双工通信
• 房间层：Socket.IO 房间分组 + 内存状态缓存
• 数据层：SQLite 持久化 + active_rooms 高速缓存
• AI 层：Prompt Engineering 控制识别策略
• 前端层：Canvas 绘图 + 状态机驱动 + 模拟调试

---

模块二：WebSocket 多人联机房间管理

一、房间生命周期设计

完整六阶段状态流转：

1. waiting — 等待玩家加入
2. picking — 画家选词
3. drawing — 绘画中
4. guessing — 猜词中
5. result — 回合结果
6. finished — 游戏结束

所有状态统一由后端驱动，前端严格跟随，确保全局同步。

二、Socket.IO 核心事件模型

@socketio.on('join_room')     # 加入房间频道
@socketio.on('leave_room')    # 离开房间
@socketio.on('start_game')   # 房主开始游戏
@socketio.on('drawing_update')# 绘画同步
@socketio.on('submit_guess')  # 提交猜词

核心 API：

• join_room(room_id)：加入分组
• emit(..., to=room_id)：房间内广播
• include_self=False：不同步自己（绘画优化）

三、active_rooms 内存状态管理

active_rooms = {}

存储内容：

• phase 游戏阶段
• drawer_queue 画家队列
• timer_start 计时
• guessed_users 已猜用户（防重复）
• round_ended 防重复结束

为什么不全部存入数据库？

• 状态每秒多次变更，数据库写入太慢
• SQLite 高频写入会锁表、卡顿
• 内存读写速度提升 50~100 倍
• 游戏结束后可销毁，无需持久化

四、核心代码实现

1. 玩家加入房间

@socketio.on('join_room')
def handle_join_room(data):
    room_id = data.get('room_id')
    user_id = data.get('user_id')
    nickname = data.get('nickname')
    join_room(room_id)
    room = models.get_room(room_id)
    emit('room_update', {
        'type': 'player_joined',
        'player': {'user_id': user_id, 'nickname': nickname},
        'players': room['players']
    }, to=room_id)

2. 房主开始游戏

@socketio.on('start_game')
def handle_start_game(data):
    room_id = data.get('room_id')
    user_id = data.get('user_id')
    room = models.get_room(room_id)
    if room['host_id'] != user_id:
        return
    models.update_room_status(room_id, 'playing')
    drawer_queue = [p['id'] for p in room['players']]
    active_rooms[room_id]['drawer_queue'] = drawer_queue
    active_rooms[room_id]['phase'] = 'picking'
    emit('game_started', {...}, to=room_id)

---

模块三：房间管理功能联调与测试

一、测试场景设计

1. 创建房间 → 生成唯一 6 位码
2. 加入房间 → 实时更新列表
3. 满员拒绝 → 超过 4 人返回错误
4. 退出房间 → 释放名额、同步列表
5. 状态同步 → 所有人阶段完全一致

二、前后端联调流程

1. 先用 Postman 测试 REST API
2. 再测试 WebSocket 事件同步
3. 多窗口模拟多人验证一致性

三、联调成果

房间联调测试

测试项	预期	实际	状态
创建房间	返回 room_id + code	✅	通过
加入房间（正常）	加入成功，广播更新	✅	通过
加入房间（已在）	返回"已在房间中"	✅	通过
加入房间（满员）	返回"房间已满"	✅	通过
加入房间（不存在）	返回"房间不存在"	✅	通过
玩家列表同步	所有人收到相同列表	✅	通过
离开房间	实时释放名额	✅	通过
房间消息延迟	≤300ms 传输	✅ ~100ms	通过

稳定性测试

测试项	操作	预期	实际	状态
防重复提交	快速点2次提交	只记录1次	✅	通过
防重复结束	自动 + 超时同时触发	只发送1条 round_result	✅	通过

• 房间码唯一性验证通过
• 玩家列表实时同步无误
• 房间状态流转统一
• 异常退出自动清理
• 人数限制、权限控制稳定

---

模块四：AI 猜词与 Prompt Engineering

一、三档难度控制策略

• easy：低提示、高置信阈值 → AI 容易错
• medium：标准提示、中等阈值
• hard：全提示、低置信阈值 → AI 几乎必对

二、提示词工程实现

根据难度动态构建提示：

• 简单：仅让 AI 猜测
• 中等：增加分类提示
• 困难：给出分类 + 候选词范围

强制 JSON 输出格式：

{"guess":"答案","confidence":0.9,"reasoning":"依据"}

三、效果

• 简单模式人类胜率大幅提升
• 困难模式接近 “开挂”
• 中等模式匹配正常游戏体验

---

模块五：前端 Canvas 画板调试与优化

一、核心功能测试

• 画笔、颜色、大小、橡皮擦、撤销、清空
• 多点触控、坐标转换、笔触平滑
• 撤销栈修复、清空逻辑优化

二、行为采集精度提升

• 拐点检测优化（角度 + 距离双重判断）
• 画布覆盖率、对称性、留白比缓存计算
• 采集性能提升，避免卡顿

三、游戏状态机模拟测试

在后端未完全就绪时，使用 mockSocket 模拟事件：

• pick_word_phase
• round_start
• guessing_phase
• round_result
• game_finished

验证所有阶段跳转、倒计时、按钮权限、视角区分全部正常。

---

模块六：团队协作与分工

成员1

• WebSocket 房间系统架构设计
• 房间生命周期与状态流转
• 内存状态管理
• 核心联机事件代码实现

成员2

• 房间管理功能联调与测试
• 玩家进出、状态同步、房间码唯一性验证
• 多窗口场景模拟与问题定位
• 房间状态不同步问题修复

成员3

• AI 多模态识别接入
• Prompt Engineering 难度分级
• JSON 格式约束与解析
• 三档难度测试与参数调优

成员4

• Canvas 画板功能调试
• 行为采集精度优化
• 游戏控制器状态机测试
• 前端模拟联调与 bug 修复

---

开发总结

本周完成了项目从单模块开发到多人联机可玩的关键跨越：

• 搭建完成稳定的 WebSocket 房间系统
• 实现 房间生命周期、状态流转、实时广播 完整机制
• 完成 AI 难度分级系统，大幅提升游戏可玩性
• 前端画板、状态机、行为采集全面稳定
• 全流程联调通过，支持 2–4 人实时联机对战