# AgentScope 三国狼人杀案例

本目录包含第六章 AgentScope 框架的完整实战案例，展示了如何使用 AgentScope 构建一个融合中国古典文化元素的多智能体在线游戏。

## 📁 文件说明

- `main_cn.py` - 主要游戏逻辑和控制器
- `prompt_cn.py` - 中文提示词管理
- `game_roles.py` - 游戏角色定义和配置
- `structured_output_cn.py` - 结构化输出模型定义
- `utils_cn.py` - 游戏工具函数和辅助方法
- `README.md` - 本说明文档

## 🎮 案例特点

- **消息驱动架构**：展示 AgentScope 的核心消息传递机制
- **并发协作**：演示多智能体同时在线的实时交互
- **角色扮演**：每个智能体具备双重身份（游戏角色+三国人物）
- **结构化输出**：通过 Pydantic 模型约束智能体行为
- **容错机制**：单个智能体异常不影响整体游戏流程

## 🛠️ 环境准备

### 1. 安装依赖

```bash
pip install agentscope
pip install dashscope
pip install pydantic
```

### 2. 配置环境变量

设置阿里云 DashScope API Key：

```bash
# Linux/Mac
export DASHSCOPE_API_KEY="your-api-key-here"

# Windows PowerShell
$env:DASHSCOPE_API_KEY="your-api-key-here"

# Windows CMD
set DASHSCOPE_API_KEY=your-api-key-here
```

获取 API Key：https://dashscope.console.aliyun.com/apiKey

### 3. 运行游戏

```bash
python main_cn.py
```

## 🎭 游戏角色说明

### 游戏角色
- **狼人**：夜晚击杀好人，白天隐藏身份
- **预言家**：每晚查验一名玩家身份
- **女巫**：拥有解药和毒药各一瓶
- **猎人**：被投票出局时可开枪带走一名玩家
- **村民**：通过推理和投票找出狼人

### 三国人物
- **刘备**：仁德宽厚，善于团结众人
- **关羽**：忠义刚烈，言辞直接
- **张飞**：性格豪爽，容易冲动
- **诸葛亮**：智慧超群，分析透彻
- **曹操**：雄才大略，善于权谋
- **司马懿**：深谋远虑，城府极深

## 🏗️ 架构设计

### 分层架构
```
游戏控制层 (ThreeKingdomsWerewolfGame)
    ├── 游戏状态管理
    ├── 流程控制
    └── 胜负判定

智能体交互层 (MsgHub)
    ├── 消息路由
    ├── 并发处理
    └── 状态同步

角色建模层 (DialogAgent)
    ├── 角色提示词
    ├── 结构化输出
    └── 行为约束
```

### 核心组件

**1. 消息中心 (MsgHub)**
```python
async with MsgHub(
    participants=self.werewolves,
    enable_auto_broadcast=True
) as hub:
    # 狼人夜晚讨论
    for wolf in self.werewolves:
        await wolf(structured_model=DiscussionModelCN)
```

**2. 结构化输出**
```python
class VoteModelCN(BaseModel):
    vote: str = Field(description="投票目标玩家姓名")
    reason: str = Field(description="投票理由")
    confidence: int = Field(ge=1, le=10, description="信心程度")
```

**3. 并发管道**
```python
vote_msgs = await fanout_pipeline(
    self.alive_players,
    msg=vote_announcement,
    structured_model=get_vote_model_cn(self.alive_players),
    enable_gather=False,
)
```

## 🎯 游戏流程

### 夜晚阶段
1. **狼人讨论**：狼人通过 MsgHub 协商击杀目标
2. **预言家查验**：预言家选择查验对象
3. **女巫行动**：女巫决定是否使用解药/毒药

### 白天阶段
1. **死亡公布**：公布夜晚死亡玩家
2. **自由讨论**：所有存活玩家参与讨论
3. **投票淘汰**：投票选择淘汰对象
4. **猎人技能**：被淘汰的猎人可开枪

## 🔧 自定义配置

### 修改游戏人数
```python
# 在 main_cn.py 中修改
await game.setup_game(player_count=8)  # 支持 6-12 人
```

### 添加新角色
```python
# 在 game_roles.py 中添加
ROLES["守护者"] = {
    "description": "守护者",
    "ability": "每晚可以守护一名玩家",
    "team": "好人阵营"
}
```

### 自定义提示词
```python
# 在 prompt_cn.py 中修改
def get_role_prompt(role: str, character: str) -> str:
    # 自定义角色提示词逻辑
    pass
```

## 🐛 常见问题

### Q: 游戏无法启动？
A: 检查以下几点：
- 确认 DASHSCOPE_API_KEY 环境变量已设置
- 验证 API Key 是否有效
- 检查网络连接是否正常

### Q: 智能体输出格式错误？
A: 可能原因：
- 模型理解能力限制
- 提示词设计不够清晰
- 结构化输出约束过于复杂

### Q: 游戏流程卡住？
A: 建议：
- 检查 MsgHub 的消息传递
- 验证并发管道的执行状态
- 查看控制台错误日志

## 📚 技术亮点

### 1. 消息驱动架构
- 智能体间完全通过消息交互
- 支持异步并发处理
- 天然的分布式能力

### 2. 结构化输出约束
- 游戏规则转化为代码约束
- 提升系统稳定性和可预测性
- 便于调试和监控

### 3. 双重角色建模
- 游戏角色 + 三国人物的创新设计
- 展现不同人格的策略差异
- 增强游戏的趣味性和真实感

## 🚀 扩展方向

- **增加游戏模式**：支持更多狼人杀变体
- **优化 AI 策略**：提升智能体的游戏水平
- **可视化界面**：开发 Web 或桌面客户端
- **实时观战**：支持人类玩家观战和互动
- **数据分析**：统计游戏数据和智能体表现

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request：
- 报告游戏 Bug 或异常
- 提出新功能建议
- 优化代码实现
- 完善文档说明

---

*本案例是 Hello-Agents 教程第六章的核心实战项目，展示了 AgentScope 框架在构建复杂多智能体应用方面的强大能力。*