AIWerewolf 是一个单人狼人杀对局应用：浏览器里由玩家控制一个座位，其余座位由本地规则 AI 或 OpenAI 兼容模型驱动。默认不需要配置真实模型即可启动游玩。
当前版本：0.2.0。已包含标准 9 人局、12 人白狼王守卫局、中文/英文界面、暂停/继续、历史对局恢复、模型调用追踪、结算复盘和 JSON 复盘导出。
- 板子：标准 9 人局；12 人白狼王 + 守卫局。
- 角色：狼人、白狼王、平民、预言家、女巫、猎人、守卫。
- 对局流程：夜间行动、遗言、白天发言、投票放逐、胜负结算。
- AI：默认本地规则 AI；可配置全局或座位级 OpenAI 兼容 provider。
- 复盘：终局后显示胜负、身份、夜间因果、票型、关键事件，并可导出 JSON。
- 持久化：后端保存历史对局，前端可以继续未完成对局、查看已结束记录或删除不需要的记录。
- Python 3.11+
- Node.js 20+
- npm
- uv
在项目根目录安装依赖：
uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
npm ci --prefix frontend启动后端：
source .venv/bin/activate
npm run dev:backend另开一个终端启动前端：
npm run dev:frontend访问：
http://localhost:5173
健康检查：
http://localhost:8000/health
在项目根目录执行：
uv venv .venv
.\.venv\Scripts\Activate.ps1
uv pip install -e ".[dev]"
npm ci --prefix frontend如果 PowerShell 禁止激活脚本，先执行：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned启动后端：
.\.venv\Scripts\Activate.ps1
npm run dev:backend另开一个 PowerShell 终端启动前端：
npm run dev:frontend访问 http://localhost:5173。
使用 Docker Compose 构建并启动：
npm run dev:docker访问：
http://localhost:4173
后端会暴露在 http://localhost:8000。如果前端部署到额外 origin，把它加入 WEREWOLF_ALLOWED_ORIGINS，例如：
WEREWOLF_ALLOWED_ORIGINS=http://localhost:4173,http://127.0.0.1:4173 npm run dev:docker历史对局默认保存在后端的 backend/data/sessions.sqlite3。Docker Compose 会把 /app/backend/data 挂载到命名卷 backend-data，所以重建容器不会丢失历史；如需清空 Docker 历史数据，执行 docker compose down -v。
当前 Docker Compose 拓扑面向 single backend instance 部署。live WebSocket sessions and engine tasks are process-local，SQLite 只保存可恢复快照和历史记录；如果未来要水平扩展多个后端实例，需要先增加粘性会话和共享的实时会话/任务协调层。
不配置 .env 时，后端使用本地规则 AI。
要启用真实模型，复制模板并填写 provider：
cp .env.example .env常用变量：
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1-mini
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_TIMEOUT_SECONDS=30
LLM_MAX_RETRIES=2
OPENAI_REASONING_EFFORT=low
OPENAI_MAX_COMPLETION_TOKENS=220座位级覆盖使用 SEAT_<seat_id>_OPENAI_*，例如：
SEAT_2_OPENAI_API_KEY=sk-seat-2
SEAT_2_OPENAI_MODEL=gpt-4.1
SEAT_2_OPENAI_BASE_URL=https://api.openai.com/v1
SEAT_2_LLM_MAX_RETRIES=1STITCH_* 变量作为 OpenAI 兼容别名也被支持。进程环境变量优先于 .env 文件。Docker Compose 会在项目根目录 .env 存在时把它传给后端，因此全局和座位级 provider 配置在容器里同样生效。
本地 OpenAI 兼容服务默认被拦截；开发时需要显式允许：
OPENAI_ALLOW_LOCALHOST=true
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=qwen2.5:7b如果后端运行在 Docker 内、模型服务运行在宿主机，使用：
OPENAI_ALLOW_LOCALHOST=true
OPENAI_BASE_URL=http://host.docker.internal:11434/v1完整单元和组件测试：
npm test生产构建：
npm run build浏览器端到端烟测：
npm run test:e2e本地规则 AI 批量对局审计脚本：
node scripts/python-runner.mjs scripts/run_llm_game_batch.py --provider-mode local --games 10真实 provider 审计默认读取 .env 或进程环境：
node scripts/python-runner.mjs scripts/run_llm_game_batch.py --provider-mode env --games 10最近一次批量审计结果记录在 docs/llm-game-batch-findings.md。
backend/app/domain 角色、板子、玩家和对局上下文
backend/app/engine 狼人杀规则流程
backend/app/llm 本地和 OpenAI 兼容 LLM provider
backend/app/ws WebSocket 网关、会话持久化和复盘 payload
frontend/src React 前端、组件、状态和 WebSocket client
frontend/e2e Playwright 浏览器烟测
tests 后端单元与网关测试
scripts 测试/批量对局辅助脚本