Skip to content
BranchesTags

Repository files navigation

Werewolf Game — AI 狼人杀多智能体系统

基于 Python + LangGraph 的 9 人狼人杀多智能体系统（预女猎版：3狼+预言家+女巫+猎人+3平民）。

每个玩家是独立 LLM Agent，具备 Think/Speak 两阶段推理、四维 Memory、阵营内有限通信。 现已支持 策略自进化、Prompt 对抗对比、赛后 Judge 全链路评分。

📄 课题汇报完整文档：飞书文档 — 基于LLM的狼人杀博弈多智能体系统

技术栈

层 技术
状态机 LangGraph (StateGraph)
数据模型 Pydantic v2
LLM 调用 httpx (async)，支持多 Provider 一键切换
持久化 PostgreSQL 16 (asyncpg) + 应用级 CheckpointManager
前端 Next.js 14 (App Router) + Tailwind CSS + Recharts
包管理 uv (Python) / npm (前端)

依赖安装

后端 (Python)

# 安装 uv（如未安装）
pip install uv

# 安装 Python 依赖
uv sync

# 安装 dev 依赖（测试用）
uv pip install pytest python-dotenv

前端 (Next.js)

cd werewolf-game-web-next
npm install        # 或 pnpm install

数据库 (PostgreSQL)

# 启动 PostgreSQL
docker compose up -d

# 停止
docker compose down

快速启动

1. 配置环境变量

# 从模板创建 .env（模板是 minimax）
cp .env.example .env

# 编辑 .env，填入 LLM_API_KEY

一键切换 LLM Provider：

bash scripts/switch_provider.sh deepseek   # DeepSeek v4-flash
bash scripts/switch_provider.sh minimax    # MiniMax-M2.7-highspeed
bash scripts/switch_provider.sh doubao     # 豆包 (Volcengine Ark)

你也可以直接编辑 .env，关键环境变量：

变量 说明 可选值
LLM_PROVIDER LLM 提供商 deepseek / minimax / doubao / mock
LLM_API_KEY API 密钥 —
LLM_DEFAULT_MODEL 模型名 MiniMax-M2.7-highspeed / deepseek-v4-flash 等
LLM_BASE_URL API 地址 https://api.minimaxi.com/v1 等
PROMPT_VERSION Prompt 版本 __working__ / v3-role-framework 等
DATABASE_URL 数据库连接 postgresql://werewolf:werewolf@localhost:5432/werewolf

2. 后端启动

# WebSocket 服务器模式（配合前端使用，推荐）
uv run python -m werewolf_game --server

# CLI 模式（终端直接运行一局）
uv run python -m werewolf_game

# 指定 Provider
uv run python -m werewolf_game --provider deepseek

# 指定配置文件
uv run python -m werewolf_game --config configs/custom.yaml

# 显示完整 Agent 思考过程（verbose）
uv run python -m werewolf_game --verbose

# 指定随机种子（固定角色分配，调试用）
uv run python -m werewolf_game --seed 42

服务器默认监听 http://localhost:8000，WebSocket 路径为 /ws。

3. 前端启动

cd werewolf-game-web-next
npm run dev

访问 http://localhost:3000。前端自动将 /api 和 /ws 请求代理到后端 localhost:8000。

调试模式

# 打印每次 LLM 调用的完整上下文（ContextBuilder 输入输出）
DEBUG_CONTEXT=true uv run python -m werewolf_game

# 结合 verbose 查看思考过程
DEBUG_CONTEXT=true uv run python -m werewolf_game --verbose

# 服务器模式也可用
DEBUG_CONTEXT=true uv run python -m werewolf_game --server

输出示例：

[DEBUG-HOOK] player=6 stage=think context_type=think
[CONTEXT DUMP] player=6 role=Role.WOLF ctx_type=think round=1
──────────────────────────────────────── [system] ─────────────────────────────
你正在参加一场 9 人狼人杀游戏...
──────────────────────────────────────── [user] ───────────────────────────────
[Task] 这是第 1 轮...
[State] 存活玩家: 1, 2, 3...
[Evidence] ...
[Memory] ...
[Output] ...

批量运行

脚本 用途
bash scripts/auto_game.sh 无限循环跑局，每局等 20 分钟
bash scripts/auto_game.sh --count 10 --interval 5 跑 10 局，间隔 5 分钟
uv run python scripts/run_evolve.py 批量跑局 + 自进化
uv run python scripts/run_evolve.py --games 50 --no-evolve 批量 50 局，关闭进化
uv run python scripts/run_prompt_battle.py --version-a __working__ --version-b v3 --rounds 10 Prompt 对抗局
uv run python scripts/run_batch.py --games 10 批量跑局（基础版）

后台运行：

nohup bash scripts/auto_game.sh > nohup.out 2>&1 &
tail -f nohup.out    # 实时查看

数据维护

脚本 用途
uv run python scripts/migrate_data.py --sqlite data/xxx.db SQLite → PostgreSQL 迁移
uv run python scripts/migrate_prompts.py YAML + ContextSpec → prompt_entries 表
uv run python scripts/manage_prompts.py snapshot --version v1 Prompt 版本快照
uv run python scripts/rerun_judge.py [game_id] 重新评分
uv run python scripts/clean_strategies.py 清洗 think 标签等 LLM 污染
uv run python scripts/seed_players.py 创建测试玩家

Mock 模式（无 API 测试）

# CLI 模式使用 mock
uv run python -m werewolf_game --provider mock

# 或在 .env 中设置
LLM_PROVIDER=mock

Mock Provider 返回预设回复，不消耗 API 额度，适合快速验证流程。

运行测试

uv run pytest tests/ -v
uv run pytest tests/ -v -k "test_vote"  # 运行特定测试

项目结构

src/werewolf_game/
├── domain/models/          # 核心实体: Player, Role, Camp, GameState
├── application/
│   ├── agent/
│   │   ├── base/           # Agent 抽象基类 + Think/Speak 模板方法
│   │   ├── roles/          # RolePolicy 声明式 + policies/（5 角色）
│   │   ├── context/        # ContextBuilder (GSSC 流水线)
│   │   └── tool/           # Tool 系统 (vote/kill/check/heal/poison/shoot)
│   ├── graph/
│   │   ├── main_graph.py   # 日夜循环主图
│   │   ├── engine.py       # 游戏引擎入口 + from_checkpoint()
│   │   ├── nodes/          # 法官节点 + 阶段节点
│   │   └── subgraphs/      # night_subgraph, day_subgraph
│   ├── judge/              # 四阶段 LLM 评分流水线
│   └── usecases/           # ExperienceExtractor（自进化 + 灌顶）
├── infrastructure/
│   ├── llm/                # LLMProvider 抽象 + DeepSeek + MiniMax + Doubao + Mock
│   ├── persistence/        # DatabaseManager + GameRecorder + Repository
│   └── logging/            # NarrativeLogger + GameLogger（双层日志）
└── interfaces/             # CLI 入口 + FastAPI WebSocket 服务器 + GameRunner
werewolf-game-web-next/      # Next.js 前端

核心设计

Think → Speak 两阶段推理

每个 Agent 每个阶段两次 LLM 调用：

  • Think：全量上下文 → 私有推理（存入 Memory，其他玩家不可见）
  • Speak：精简上下文 + Think 结论 → 公开发言

GSSC 上下文流水线

ContextBuilder 通过声明式 ContextSpec 组装 prompt：

Agent.think() / speak()
  └── ContextBuilder.build(ctx, context_type)
        ├── 1. Gather  — 按 sections 收集数据
        ├── 2. Select  — 分类型筛选（滑动窗口/重要性过滤/去重）
        ├── 3. Structure — 按 ordering 排列 → [Task][State][Strategy][Evidence][Memory][Output]
        └── 4. Compress — 超模型上限时截断

角色 Policy 插件化

加新角色只需新建文件 + 一行注册：

  1. 新建 application/agent/roles/policies/cupid.py 声明 RolePolicy
  2. 在 policies/__init__.py 加 from .cupid import CUPID_POLICY
  3. 工具注册统一入口：RoleRegistry.build_tool_registry()

自进化系统

赛后 ExperienceExtractor 五层 Reflection 流水线提炼策略，存入 strategy_versions 表。 跨局策略通过 [Strategy] 段落注入，支持灌顶（外部策略注入）和 Baseline Battle（进化 vs 白板对比）。

文档

About

ai 狼人杀游戏

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages