# 背景
文件名：2025-11-03_2_werewolf-game.md
创建于：2025-11-03_12:20:10
创建者：admin
主分支：main
任务分支：task/werewolf_2025-11-03_1
Yolo模式：Off

# 任务描述
在WPS Bot Game项目中添加狼人杀游戏系统，支持6-12人游戏，包含身份分配、私聊功能、技能使用等核心功能。

## 核心需求
1. 支持6-12人狼人杀游戏（配置：2-4狼 1预言家 1女巫 2-6平民）
2. 主持人开房：`.狼人杀 open`
3. 玩家加入：`.狼人杀 join`（必须注册用户名和个人URL）
4. 开始游戏：`.狼人杀 start`，自动分配身份并通过私聊发送
5. 私聊功能：`.狼人杀 <玩家代号> <消息>`
6. 狼人群聊：`.狼人杀 狼人 <消息>`
7. 技能系统：杀、验、救、毒
8. 游戏状态查询：`.狼人杀 status`
9. 结束游戏：`.狼人杀 end`

## 游戏规则
**人数配置**：
- 6人：2狼 1预言家 1女巫 2平民
- 8人：2狼 1预言家 1女巫 4平民
- 10人：3狼 1预言家 1女巫 5平民
- 12人：4狼 1预言家 1女巫 6平民

**胜利条件**：
- 狼人阵营：杀死所有神职和平民
- 好人阵营：消灭所有狼人

**技能**：
- 狼人：每晚投票刀人
- 预言家：每晚查验一个玩家身份
- 女巫：拥有一瓶解药（仅可使用一次）和一瓶毒药（仅可使用一次）
- 平民：无特殊技能

# 项目概览

## 项目结构
```
WPSBotGame/
├── app.py                    # FastAPI主应用
├── config.py                 # 配置管理
├── core/
│   ├── database.py          # SQLite数据库操作
│   ├── middleware.py        # 中间件
│   └── models.py            # 数据模型
├── routers/
│   ├── callback.py          # Callback路由处理
│   ├── health.py            # 健康检查
│   └── private.py           # 私聊相关API
├── games/                   # 游戏模块
│   ├── werewolf.py          # 狼人杀游戏（新增）
│   └── ...                 # 其他游戏
└── utils/
    ├── parser.py           # 指令解析
    └── message.py          # 消息发送
```

# 分析

## 当前状态
1. 已有私聊功能支持，用户可注册个人webhook URL
2. 已有游戏架构：BaseGame基类、数据库状态管理
3. 已有成语接龙等多人类游戏参考
4. 数据库支持game_states表存储游戏状态

## 关键技术点
1. **数据库层**: 
   - 使用game_states表存储游戏状态（user_id=0表示群级别状态）
   - 通过state_data JSON字段存储玩家列表、身份、阶段等信息

2. **私聊系统**:
   - 利用现有的send_private_message函数
   - 身份信息、技能结果等通过私聊发送
   - 支持发送者标识显示

3. **游戏状态管理**:
   - 游戏状态存储在state_data中
   - 包含：玩家列表、身份映射、狼人列表、技能使用记录等

4. **技能系统**:
   - 狼人刀人：投票机制
   - 预言家验人：私聊返回结果
   - 女巫用药：限制使用次数

5. **指令路由**:
   - 在parser.py注册.werewolf和.狼人杀指令
   - 在callback.py中导入并注册游戏处理器

# 提议的解决方案

## 方案概述
1. **创建狼人杀游戏类**：`games/werewolf.py`，继承BaseGame
2. **状态数据结构**：使用JSON存储在state_data中
3. **身份分配**：随机分配角色，狼人互相认识
4. **私聊通知**：游戏开始时通过私聊发送身份信息
5. **技能系统**：支持杀、验、救、毒四种技能
6. **指令注册**：添加解析和路由支持

## 设计决策
- 使用user_id=0存储群级别游戏状态（参考成语接龙）
- 通过私聊发送敏感信息（身份、技能结果）
- 简化实现：主持人手动推进阶段（暂不实现自动流转）
- 使用数字代号（1-N）标识玩家
- 支持狼人群聊功能

# 当前执行步骤："实施完成"

# 详细实施计划

## 文件1: games/werewolf.py（新建文件）

### 主要方法
1. **handle()** - 主处理逻辑，指令路由
2. **get_help()** - 帮助信息
3. **_open_game()** - 主持人开房
4. **_join_game()** - 玩家加入
5. **_start_game()** - 开始游戏，分配身份
6. **_send_identities()** - 私聊发送身份信息
7. **_private_chat()** - 玩家私聊
8. **_wolf_group_chat()** - 狼人群聊
9. **_handle_skill()** - 技能处理
10. **_wolf_kill()** - 狼人刀人
11. **_seer_check()** - 预言家验人
12. **_witch_save()** - 女巫救人
13. **_witch_poison()** - 女巫毒人
14. **_show_status()** - 显示游戏状态
15. **_end_game()** - 结束游戏

### 数据结构设计
```python
state_data = {
    'creator_id': int,  # 主持人ID
    'status': str,  # 'open', 'playing', 'finished'
    'players': [
        {
            'user_id': int,
            'name': str,  # 注册的用户名
            'id': int,  # 游戏内代号 1-N
            'role': str,  # 'wolf', 'seer', 'witch', 'civilian'
            'alive': bool,
            'id_label': str  # "1号玩家"
        }
    ],
    'phase': str,  # 当前阶段
    'round': int,  # 当前回合数
    'wolves': [int],  # 狼人ID列表
    'kill_target': int,  # 狼人票决目标
    'seer_result': {},  # 预言家验人结果
    'witch_save': bool,  # 女巫是否救人
    'witch_poison': int,  # 女巫毒杀目标
    'discussed': False,  # 讨论阶段是否完成
    'wolf_know_each_other': False
}
```

## 文件2: utils/parser.py

### 修改点：添加指令映射
在COMMAND_MAP中添加：
```python
'.werewolf': 'werewolf',
'.狼人杀': 'werewolf',
```

## 文件3: routers/callback.py

### 修改点：添加路由处理
在handle_command函数中添加：
```python
# 狼人杀系统
if game_type == 'werewolf':
    from games.werewolf import WerewolfGame
    game = WerewolfGame()
    return await game.handle(command, chat_id, user_id)
```

## 文件4: games/base.py

### 修改点：添加帮助信息
在get_help_message()函数中添加狼人杀帮助说明

# 任务进度

[2025-11-03_12:20:10]
- 已修改：
  1. games/werewolf.py - 新建狼人杀游戏类，实现所有核心功能
  2. utils/parser.py - 添加.werewolf和.狼人杀指令映射
  3. routers/callback.py - 添加狼人杀路由处理
  4. games/base.py - 添加狼人杀帮助信息

- 更改：
  1. 创建完整的狼人杀游戏系统
  2. 支持开房、加入、开始、私聊、技能使用等所有核心功能
  3. 实现6-12人游戏配置和角色分配
  4. 集成私聊系统发送身份信息
  5. 支持狼人群聊功能
  6. 添加帮助信息和指令注册

- 原因：
  实现完整的狼人杀游戏系统，支持多人游戏、身份隐藏、技能使用等核心功能

- 阻碍因素：
  无

- 状态：成功

[2025-11-04_17:41:14]
- 已修改：
  1. games/werewolf.py - 改进阶段提示和自动流转功能

- 更改：
  1. 添加阶段名称映射系统（phase_configs），定义各阶段的中文名称、行动角色和指令说明
  2. 实现阶段管理方法：_get_phase_description()、_get_next_phase()、_advance_phase()
  3. 改进游戏开始提示，明确显示"第一夜 - 狼人行动阶段"和操作指令
  4. 实现自动阶段流转：狼人刀人后自动进入预言家阶段，预言家验人后自动进入女巫阶段
  5. 新增女巫跳过功能：支持`.werewolf 跳过`指令，女巫可以选择不行动
  6. 改进状态显示：_show_status()现在显示中文阶段名称、当前行动角色和操作指令
  7. 更新身份说明和帮助信息，添加女巫跳过选项说明
  8. 各技能方法添加阶段验证，确保在正确的阶段使用技能

- 原因：
  解决用户反馈的游戏阶段不明显的问题，让玩家清楚知道当前是什么阶段、谁应该行动、下一步是什么阶段

- 阻碍因素：
  无

- 状态：成功

# 最终审查

待审查阶段完成...