# guessing-draw

**Repository Path**: bolt/guessing-draw

## Basic Information

- **Project Name**: guessing-draw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 你画我猜

多人实时在线猜词游戏。玩家加入同一房间，一人绘画、多人猜词，支持 AI 辅助词库生成与绘画评分。

## 技术栈

- **前端**：原生 JavaScript + HTML5 Canvas 2D，托管于 EdgeOne Pages
- **后端**：EdgeOne Pages Edge Functions（V8 Isolate）
- **状态存储**：Edge KV（键值存储，TTL 自动清理）
- **AI**：Claude API（词库生成、绘画评分），由 Edge Function 代理调用
- **实时通信**：HTTP 轮询（画者 80ms batch 提交笔触，猜者 100ms 轮询拉取事件）

## 快速开始

```bash
# 安装依赖（含 EdgeOne CLI）
npm install

# 本地预览前端页面（Edge Functions 需部署到 EdgeOne 后才能联调）
npm run dev
```

## 部署

1. 在 [EdgeOne Pages 控制台](https://console.tencentcloud.com/edgeone) 创建项目
2. 绑定 Edge KV 命名空间到项目
3. 配置环境变量 `ANTHROPIC_API_KEY`
4. 部署代码（支持 Git 导入或直接上传）

## 项目结构

```
guessing-draw/
├── edge-functions/      # Edge Functions
│   ├── _shared/         # 共享模块
│   │   ├── types.js     # 类型定义与工具函数
│   │   ├── persistence.js # Edge KV 封装（乐观锁重试）
│   │   ├── gameEngine.js  # 游戏引擎（状态机、回合轮转、积分）
│   │   ├── wordBank.js    # 词库管理（内置 + AI 扩展）
│   │   ├── aiScoring.js   # AI 评分与词库生成代理
│   │   └── utils.js       # HTTP 工具函数
│   └── api/
│       ├── room.js      # POST /api/room（创建房间）
│       ├── room/[[default]].js # /api/room/:roomId/*（房间操作）
│       └── ai.js        # /api/ai/*（AI 评分与词库生成）
├── public/              # 前端静态资源
│   ├── index.html       # 首页（创建/加入房间）
│   ├── game.html        # 游戏页面
│   ├── css/style.css    # 样式
│   └── js/app.js        # 前端核心逻辑
├── docs/                # 文档（文档驱动开发）
│   ├── requirements/    # 需求文档
│   ├── design/          # 设计文档
│   └── adr/             # 架构决策记录
└── package.json
```

## 文档导航

- [核心需求文档](docs/requirements/core-features.md)
- [总体架构设计](docs/design/overall-architecture.md)
- [ADR-001：实时通信方案](docs/adr/001-websocket-socketio.md)
- [ADR-002：AI 调用模式](docs/adr/002-ai-proxy.md)
- [ADR-003：托管平台选择](docs/adr/003-edgeone-platform.md)

## 核心 API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/room` | POST | 创建房间 |
| `/api/room/:roomId` | GET | 获取房间状态（含超时/离线检测） |
| `/api/room/:roomId/join` | POST | 玩家加入房间 |
| `/api/room/:roomId/leave` | POST | 玩家离开房间 |
| `/api/room/:roomId/start` | POST | 房主开始游戏 |
| `/api/room/:roomId/stroke` | POST | 画者提交笔触 batch |
| `/api/room/:roomId/events` | GET | 轮询事件（`?since=lastEventId`） |
| `/api/room/:roomId/guess` | POST | 猜者提交猜词 |
| `/api/room/:roomId/heartbeat` | POST | 玩家心跳 |
| `/api/ai/score` | POST | AI 绘画评分 |
| `/api/ai/words` | POST | AI 动态生成词库 |

## 环境变量

| 变量名 | 说明 | 必填 |
|--------|------|------|
| `ANTHROPIC_API_KEY` | Claude API 密钥 | 是（AI 功能） |
| `ANTHROPIC_BASE_URL` | Claude API 自定义基础 URL（如使用代理） | 否 |
| `EDGE_KV` / `EDGEONE_KV` | Edge KV 绑定 | 是 |