AI Werewolf - 项目计划书

1. 项目概述

本项目旨在开发一个基于大型语言模型（LLM）的命令行界面（CLI）狼人杀游戏。游戏中的所有玩家（除观察者外）均由 AI 代理扮演。核心设计目标是模拟真实狼人杀游戏中的信息不对称和社交推理过程，为 AI 行为和策略研究提供一个实验平台。

2. 核心特性

• 模块化角色系统: 轻松添加或修改角色（狼人、村民、预言家、女巫、猎人等）。
• 动态游戏流程: 由 GameMaster 模块自动驱动游戏按“夜晚-白天”的顺序进行，管理各个阶段和角色技能的结算。
• 严格信息隔离: AI 代理只能访问其角色在当前游戏状态下应知的信息，确保了信息不对称这一核心游戏机制。
• 基于 LLM 的决策: 每个 AI 代理都将利用 LLM，根据其角色、已知信息和历史对话，生成发言和决策（如投票、使用技能）。
• 清晰的交互界面: 在命令行中清晰地展示游戏进程、玩家发言、投票结果和最终结局，方便用户（作为“上帝”）观察。
• 可配置性: 通过配置文件管理游戏参数，例如玩家数量、角色分配和 API 密钥。

3. 技术架构设计

我们将采用模块化的 Python 应用架构，确保代码的可读性、可维护性和可扩展性。

3.1. 文件结构

/Werewolf
├── README.md           # 本文档
├── main.py             # 应用主入口
├── requirements.txt    # 项目依赖
├── .env                # 环境变量文件（用户手动创建）
├── config.py           # 配置加载模块，读取 .env 文件
├── game_master.py      # 游戏主控制器 (Game Master)
├── game_state.py       # 游戏状态管理器
└── agents/
    ├── __init__.py
    ├── base_agent.py   # AI 代理基类
    └── roles/
        ├── __init__.py
        ├── villager.py
        ├── werewolf.py
        ├── seer.py
        └── witch.py

3.2. 模块职责

• main.py:

  • 职责：初始化游戏，包括加载配置、创建 GameMaster 实例、启动游戏循环。
  • 这是项目的起点。

• config.py & .env:

  • 职责：config.py 负责从 .env 文件中安全地加载配置，特别是 API_KEY。.env 文件需由用户手动创建，并添加到 .gitignore 中以避免密钥泄露。
  • API 密钥将在此处集成。

• game_master.py (GameMaster):

  • 职责：作为游戏引擎的核心，驱动整个游戏流程。
  • 管理游戏阶段（夜晚、黎明、白天、投票、黄昏）。
  • 调用 AI 代理执行行动（发言、投票、使用技能）。
  • 信息分发中心：根据游戏规则，向每个 AI 代理精确分发其应得的信息。例如，在夜晚，只告诉预言家其查验的结果。

• game_state.py (GameState):

  • 职责：作为游戏世界的“真理”来源。
  • 存储所有游戏状态，包括：玩家列表、每个玩家的身份（角色）、存活状态、历史发言记录等。
  • GameMaster 会读取此模块的信息，但只会将过滤后的信息传递给 AI 代理。

• agents/base_agent.py (BaseAgent):

  • 职责：定义所有 AI 代理的通用接口和属性。
  • 包含 id, role, status (alive/dead) 等基本信息。
  • 定义 discuss(), vote(), night_action() 等需要被子类实现的方法。
  • 持有一个独立的 LLM 客户端实例。

• agents/roles/*.py:

  • 职责：实现具体角色的逻辑。
  • 例如，werewolf.py 中的 WerewolfAgent 在执行 night_action 时，会与其他狼人共同决定目标。seer.py 中的 SeerAgent 在 night_action 时会选择一名玩家进行查验。

3.3. 信息流与非对称性设计

这是项目的核心。GameMaster 将扮演信息壁垒的角色。

1. 初始化: GameMaster 创建所有 Agent 实例，并根据 GameState 分配角色。此时，每个 Agent 只知道自己的身份。
2. 狼人确认同伴: 在第一个夜晚，GameMaster 会获取所有狼人 Agent 的列表，并告诉他们彼此的身份。村民 Agent 不会收到任何信息。
3. 夜晚行动:
   • GameMaster 依次唤醒有技能的角色。
   • 当唤醒预言家时，GameMaster 会向预言家 Agent 提问：“你要查验谁？”。
   • 预言家 Agent 做出决策后，GameMaster 从 GameState 中查询该玩家的真实身份，然后仅将结果返回给该预言家 Agent。
   • 其他任何 Agent 都不会知道这次查验的发生和结果。
4. 白天讨论: GameMaster 宣布进入白天，并依次调用每个存活 Agent 的 discuss() 方法。每个 Agent 会根据自己掌握的私有信息（如狼人知道同伴，预言家知道查验结果）和公共信息（所有人的发言历史）来生成自己的发言。

通过这种方式，每个 AI 的决策都基于其独特的、受限的视角，从而实现了真实的非对称博弈。

5. 安装与运行

1. 克隆仓库 (未来步骤)

   git clone <repository_url>
   cd Werewolf

2. 安装依赖

   pip install -r requirements.txt

3. 配置 API 密钥
   • 在项目根目录 (/Werewolf) 手动创建一个名为 .env 的文件。
   • 在文件中添加以下内容，并将 your_api_key_here 替换为您的真实密钥：

     API_KEY="your_api_key_here"
     

4. 运行游戏

   python main.py

6. 开发路线图 (Roadmap)

• 第一阶段：基础框架搭建
  • 完成 README.md 的最终审核。
  • 创建项目文件结构。
  • 实现 config.py 和 main.py 的基本功能。
  • 实现 GameMaster 和 GameState 的核心数据结构和游戏循环逻辑（无角色技能）。
• 第二阶段：基础角色与决策
  • 实现 BaseAgent 以及基础角色：Villager 和 Werewolf。
  • 实现基本的夜晚行动（狼人投票杀人）和白天行动（所有玩家发言和投票）。
  • 对接 LLM API，实现初步的 AI 发言和投票决策。
• 第三阶段：特殊角色实现
  • 实现 Seer (预言家) 及其夜晚查验技能和信息获取逻辑。
  • 实现 Witch (女巫) 及其解药和毒药的使用逻辑。
• 第四阶段：测试与迭代
  • 进行完整的游戏流程测试。
  • 优化 AI 的 Prompt Engineering，使其行为更符合角色逻辑和人性。
  • 根据测试结果，迭代和优化代码。