# 背景
文件名：2025-10-28_1_add-idiom-chain-game.md
创建于：2025-10-28_15:43:00
创建者：admin
主分支：main
任务分支：task/add-idiom-chain-game_2025-10-28_1
Yolo模式：Off

# 任务描述
在WPS Bot Game项目中新增一个成语接龙游戏功能。

## 核心需求
1. 群内多人游戏，机器人作为裁判和出题者
2. 允许按拼音接龙（包括谐音接龙）
3. 没有时间限制
4. 不需要提示功能
5. 游戏记录保存到.stats统计中
6. 不允许重复使用成语
7. 不需要难度分级（非人机对战）
8. 需要裁判指令用于接受/拒绝玩家回答

## 游戏玩法
- 机器人出题（给出起始成语）
- 群内玩家轮流接龙
- 机器人判断接龙是否有效（拼音/谐音匹配、未重复使用）
- 裁判可以手动接受或拒绝某个回答
- 记录每个玩家的成功接龙次数

# 项目概览

## 项目结构
```
WPSBotGame/
├── app.py                    # FastAPI主应用
├── config.py                 # 配置管理
├── core/
│   ├── database.py          # SQLite数据库操作
│   ├── middleware.py        # 中间件
│   └── models.py            # 数据模型
├── games/                   # 游戏模块
│   ├── base.py             # 游戏基类
│   ├── dice.py             # 骰娘游戏
│   ├── rps.py              # 石头剪刀布
│   ├── fortune.py          # 运势占卜
│   ├── guess.py            # 猜数字
│   └── quiz.py             # 问答游戏
├── data/                   # 数据文件
│   ├── bot.db             # SQLite数据库
│   ├── quiz.json          # 问答题库
│   └── fortunes.json      # 运势数据
├── routers/               # 路由处理
│   ├── callback.py       # WPS回调处理
│   └── health.py         # 健康检查
└── utils/                # 工具模块
    ├── message.py        # 消息发送
    ├── parser.py         # 指令解析
    └── rate_limit.py     # 限流控制
```

## 技术栈
- FastAPI：Web框架
- SQLite：数据存储
- WPS协作机器人API：消息接收与发送

## 现有游戏架构
1. 所有游戏继承`BaseGame`基类
2. 必须实现`handle(command, chat_id, user_id)`方法处理指令
3. 必须实现`get_help()`方法返回帮助信息
4. 游戏状态存储在数据库`game_states`表：`(chat_id, user_id, game_type)`作为联合主键
5. 游戏统计存储在`game_stats`表：记录`wins`, `losses`, `draws`, `total_plays`
6. 指令通过`CommandParser`解析，在`callback.py`中分发到对应游戏处理器

## 数据库设计
### game_states表
- chat_id: 会话ID
- user_id: 用户ID  
- game_type: 游戏类型
- state_data: JSON格式的游戏状态数据
- created_at/updated_at: 时间戳

### game_stats表
- user_id: 用户ID
- game_type: 游戏类型
- wins/losses/draws/total_plays: 统计数据

# 分析

## 关键技术挑战

### 1. 群级别vs个人级别状态管理
现有游戏（猜数字、问答）都是个人独立状态，使用`(chat_id, user_id, game_type)`作为主键。

成语接龙是群内共享游戏，需要：
- 群级别的游戏状态：当前成语、已用成语列表、接龙长度、当前轮到谁
- 个人级别的统计：每个玩家的成功接龙次数

**可能方案：**
- 使用特殊user_id（如0或-1）存储群级别游戏状态
- 或者在state_data中存储所有玩家信息

### 2. 成语词库准备
需要准备：
- 成语列表（至少500-1000个常用成语）
- 每个成语的拼音信息（用于判断接龙是否匹配）
- 数据格式：JSON文件，类似quiz.json

### 3. 拼音匹配逻辑
- 需要拼音库支持（pypinyin）
- 支持谐音匹配（声母韵母匹配）
- 处理多音字情况

### 4. 裁判指令设计
需要额外指令：
- `.idiom accept` - 接受上一个回答
- `.idiom reject` - 拒绝上一个回答
- 需要权限控制（谁可以当裁判？）

### 5. 游戏流程设计
```
1. 开始游戏：.idiom start
   - 机器人随机给出起始成语
   - 创建群级别游戏状态
   
2. 玩家接龙：.idiom [成语]
   - 检查是否在词库中
   - 检查拼音是否匹配（首字拼音 == 上一个成语尾字拼音）
   - 检查是否已使用过
   - 自动判断或等待裁判确认
   
3. 裁判操作：.idiom accept/reject
   - 手动接受或拒绝最近的回答
   
4. 查看状态：.idiom status
   - 显示当前成语、已用成语数量、参与人数
   
5. 结束游戏：.idiom stop
   - 显示统计信息
   - 更新每个玩家的game_stats
```

## 现有代码分析

### CommandParser (utils/parser.py)
需要添加成语接龙指令映射：
```python
'.idiom': 'idiom',
'.成语接龙': 'idiom',
```

### callback.py (routers/callback.py)
需要在`handle_command`函数中添加idiom游戏分支：
```python
if game_type == 'idiom':
    from games.idiom import IdiomGame
    game = IdiomGame()
    return await game.handle(command, chat_id, user_id)
```

### base.py (games/base.py)
需要更新`get_help_message()`和`get_stats_message()`，添加成语接龙信息。

### config.py
可能需要添加成语接龙相关配置：
```python
"idiom": {
    "auto_judge": True,  # 是否自动判断
    "require_approval": False,  # 是否需要裁判确认
}
```

# 提议的解决方案

（待INNOVATE模式填写）

# 当前执行步骤："1. 创建任务文件"

# 任务进度

## [2025-10-28 15:45:00]
- 已修改：requirements.txt, config.py, utils/parser.py, routers/callback.py, games/base.py
- 已创建：games/idiom.py
- 更改：
  1. 在requirements.txt中添加pypinyin==0.51.0依赖
  2. 在config.py的GAME_CONFIG中添加idiom配置（起始成语池、历史显示数量）
  3. 在utils/parser.py的COMMAND_MAP中添加.idiom、.成语接龙、.成语指令映射
  4. 创建games/idiom.py实现完整的成语接龙游戏逻辑：
     - IdiomGame类继承BaseGame
     - 实现handle()主指令分发方法
     - 实现_start_game()开始游戏
     - 实现_make_chain()玩家接龙
     - 实现_set_next_user()指定下一位
     - 实现_reject_idiom()裁判拒绝
     - 实现_show_status()显示状态
     - 实现_show_blacklist()显示黑名单
     - 实现_stop_game()结束游戏
     - 实现_get_pinyin()获取拼音（支持多音字）
     - 实现_check_pinyin_match()检查拼音匹配（忽略声调）
     - 实现_parse_mentioned_user()解析@用户
     - 实现_can_answer()权限检查（防连续、指定轮次）
     - 实现_validate_idiom()词语验证（4字、拼音匹配、未使用、未黑名单）
     - 实现get_help()帮助信息
  5. 在routers/callback.py的handle_command()中添加idiom游戏分支
  6. 在games/base.py的get_help_message()中添加成语接龙帮助信息
  7. 在games/base.py的get_stats_message()的game_names字典中添加idiom映射
- 原因：实现成语接龙游戏功能的所有核心代码
- 阻碍因素：无
- 状态：未确认

# 最终审查

（待REVIEW模式完成后填写）