# YesOrNo

**Repository Path**: code_from_qh/yes-or-no

## Basic Information

- **Project Name**: YesOrNo
- **Description**: 双人联网猜词游戏
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 你想我猜

双人联网猜词游戏。FastAPI 后端 + Chrome 侧边栏扩展 + **微信小程序**。

## 目录

```
你想我猜游戏/
├── backend/                  FastAPI 后端（WebSocket + 房间管理 + LLM 裁判）
│   ├── app/
│   ├── tests/
│   ├── scripts/e2e_smoke.py
│   ├── pyproject.toml
│   ├── railway.json          Railway 部署配置
│   └── Dockerfile            备用容器镜像
├── extension/                Chrome 侧边栏扩展（MV3）
│   ├── manifest.json
│   ├── sidepanel.html / .js / .css
│   ├── background.js
│   ├── icons/
│   └── lib/
├── miniprogram/              微信小程序（手机端对战）
│   ├── pages/
│   │   ├── lobby/            首页：创建房间 / 加入房间
│   │   ├── room/             游戏房间：设词 / 提问 / 投降 / 问答流
│   │   ├── history/          历史战绩 + 排行榜
│   │   └── settings/         昵称 / 后端地址 / 重置 ID
│   ├── utils/
│   │   ├── api.js            REST API 封装
│   │   ├── websocket.js      WebSocket 客户端（自动重连 + 心跳）
│   │   └── state.js          玩家身份本地存储
│   └── assets/icons/         TabBar 图标
└── 需求文档.md
```

## 一、启动后端

需要 Python 3.11+ 和 `uv`。

```bash
cd backend

# 创建虚拟环境并安装依赖
uv venv .venv
source .venv/bin/activate
uv sync --extra dev

# 复制环境变量并填入你的 LLM key
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY（也可以后续再填，仅设词/裁判会降级为"无"）

# 启动服务（默认 127.0.0.1:8000）
uvicorn app.main:app --reload
```

健康检查：

```bash
curl http://127.0.0.1:8000/healthz
# {"ok":true,"service":"guess-the-word","llm_configured":true|false}
```

## 二、加载 Chrome 扩展

1. 打开 `chrome://extensions/`
2. 打开右上角「开发者模式」
3. 点击「加载已解压的扩展程序」，选择 `extension/` 目录
4. 工具栏出现「你想我猜」图标
5. **点击图标** 即可打开侧边栏开始游戏

> 两个玩家可以在两个 Chrome profile（不同 player_id）打开侧边栏，对战。

## 三、玩法

1. 在「大厅」点击「生成 6 位房间码」或输入对方房间码加入
2. 进入房间后，双方各自在心里想一个**公认词语**（中文/英文均可），输入提交
3. 通过是/否提问猜对方词语；也可以直接输入词
4. 投降按钮可主动认输
5. 一局结束自动结算积分（每玩家当天 1/2/3 胜 → +1/+5/+10 分）
6. 「历史」标签查看战绩 + 排行榜

## 四、LLM 配置

默认使用 OpenAI 兼容协议（base_url + api_key + model），可切换到任意兼容厂商：

- OpenAI：`OPENAI_API_BASE=https://api.openai.com/v1`
- OpenRouter：`OPENAI_API_BASE=https://openrouter.ai/api/v1`
- DeepSeek：`OPENAI_API_BASE=https://api.deepseek.com/v1`
- 智谱 GLM：`OPENAI_API_BASE=https://open.bigmodel.cn/api/paas/v4`

**未配置 LLM** 时的行为：
- 词语校验：放行（任意词都接受为"合法"）
- 裁判回答：固定返回 "无"

## 五、每日次数限制

- **按房间对**计算：同一 `room_code` 当天最多 3 局
- 第 4 局发起时广播 `limit_reached` 消息，前端显示红色提示
- 跨日 00:00（UTC+8）按 `date_local` 重新计数

## 六、运行测试

```bash
cd backend
pytest tests/ -v
```

应看到 8 个测试全部通过：
- 房间码生成唯一性
- 完整一局（猜中）
- 积分阶梯 1/5/10
- 每日 3 次限制
- 双方同时投降不得分
- 一方投降对方得 +1 分
- LLM 未配置时降级

## 七、端到端冒烟测试

启动后端（见第一节）后，在另一个终端：

```bash
BACKEND_URL=http://127.0.0.1:8000 \
python backend/scripts/e2e_smoke.py
```

会模拟两个玩家跑一局（设置词语 → 提问 → 猜中 → 结算 → 历史/排行榜），应看到 `[done] OK`。

## 八、API 摘要

| 方法 | 路径 | 说明 |
|------|------|------|
| GET  | `/healthz` | 健康检查 |
| POST | `/rooms` | 创建房间，返回 `{code}` |
| POST | `/rooms/{code}/join` | 加入房间（HTTP 预热） |
| GET  | `/rooms/{code}` | 房间基础信息 + 今日局数 |
| GET  | `/players/{id}/history` | 个人历史（最近 20 局） |
| GET  | `/leaderboard` | 排行榜（Top 50） |
| WS   | `/ws/{room_code}/{player_id}?nickname=...` | 游戏通道 |

WS 消息类型：`room_state` / `set_word` / `set_word_ack` / `set_word_rejected` / `ask` / `ask_broadcast` / `guess_correct` / `surrender` / `game_end` / `error` / `limit_reached` / `ping` / `pong`。

## 九、微信小程序部署（手机端）

### 9.1 部署后端到 Railway

Railway 部署让后端有公网 HTTPS URL，小程序才能访问。

**步骤 1：准备 GitHub 仓库**

将 `backend/` 目录推送到 GitHub（需要包含 `requirements.txt`，由 `railway.json` / `Dockerfile` 自动构建）。

```bash
cd backend
git init && git add .
git commit -m "init"
# 创建 GitHub 仓库后：
git remote add origin git@github.com:你的用户名/你的仓库.git
git push -u origin main
```

**步骤 2：在 Railway 创建项目**

1. 登录 [railway.app](https://railway.app)，New Project → Deploy from GitHub → 选择上述仓库
2. 在服务设置中指定 Root Directory 为 `backend`
3. 添加环境变量（Variables）：
   - `OPENAI_API_BASE` = `https://api.openai.com/v1`（或其他 LLM 供应商）
   - `OPENAI_API_KEY` = `sk-...`（你的 key）
   - `LLM_MODEL` = `gpt-4o-mini`（可选）
4. Railway 会自动检测 Dockerfile 或 requirements.txt 并部署
5. 等待部署完成，复制 Railway 给的 URL，例如 `https://xxx.up.railway.app`

**步骤 3：在小程序中填入后端地址**

打开小程序 → 「设置」→ 编辑后端地址，填入 Railway URL（末尾无斜杠）。

> **注意**：Railway 免费额度在无请求 30 分钟后会休眠，首次冷启动可能需要 30–60 秒。Railway 也有 Persistent Disk 功能，SQLite 数据库文件在 `$RAILWAY_VOLUME_MOUNT_PATH/data/game.db` 下可持久化。

### 9.2 在微信开发者工具导入小程序

1. 下载 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
2. 打开工具 → 「导入项目」→ 选择项目根目录（`你想我猜游戏/`）
3. AppID 填入你的小程序 AppID（需先在[微信公众平台](https://mp.weixin.qq.com)注册）
4. 确认后进入，点击顶部「真机调试」或「预览」扫描二维码测试

> **注意**：微信小程序要求后端域名在「开发管理」→「开发设置」→「服务器域名」中配置为 `request 合法域名` 和 `ws/wss 合法域名`。开发阶段可勾选「详情」→「本地设置」→「不校验合法域名」绕过。

## 十、注意事项 / 已知限制

- 数据库默认 SQLite（`backend/data/game.db`），适合本地开发；生产可改为 Postgres
- Chrome 扩展的 `host_permissions` 写死了 `127.0.0.1:8000`，部署到远端时需修改 `extension/manifest.json`
- 词语在数据库中以明文存储（按 MVP 设计），后续如需加密可在 `app/game/room.py` 的 `set_word_for_player` 中加解密层
- 投降无客户端二次确认中断；如需"倒计时撤销"可后续加 `surrender_pending` 状态