MBTI Wolves · 16 型人格狼人杀

让 16 种 MBTI 人格的 LLM agent 在狼人杀里互相博弈，看看谁更会演、谁更会装、谁的胜率最高。

本项目是娱乐向 + 内容向，不主张 MBTI 在心理学上的科学有效性。如需严肃研究请使用 Big Five 等学界框架。

这是什么

一个前后端分离的全栈学习项目，包装在一个 16 MBTI agent 玩狼人杀的有趣场景外面：

• 场景：9 人局狼人杀（3 狼 / 1 预言家 / 1 女巫 / 1 猎人 / 3 村民）
• 玩家：16 种 MBTI 人格的 LLM agent，每种人格写进 system prompt
• 后端：Python + FastAPI + asyncio，调用小米 MiMo API（OpenAI 兼容协议）
• 前端：React 19 + TypeScript + Vite + Tailwind + shadcn/ui
• 实时通信：WebSocket（观战、人机对战）
• 运行：Mac Mini 24/7 跑批量对战 + 浏览器实时观战
• 产出：16×16 胜率热力图、对局回放页、金句墙、视频内容、可玩 Web demo

仓库结构

mbti-wolves/
├── backend/          # Python · FastAPI · 游戏引擎 · LLM 调用 · 批量 runner
│   ├── pyproject.toml
│   ├── .env.example
│   └── src/          # (Phase 1 创建)
├── frontend/         # React · TypeScript · Vite · Tailwind
│   └── package.json  # (Phase 4 创建)
├── docs/             # 架构文档、踩坑记录
├── CLAUDE.md         # Claude Code 工作约定
└── README.md

技术栈

层	选型
后端框架	FastAPI + uvicorn
后端 LLM	小米 MiMo mimo-v2.5（OpenAI 兼容）
后端异步	httpx + asyncio + aiolimiter
后端校验	pydantic
前端框架	React 19 + TypeScript + Vite (SWC)
前端样式	Tailwind CSS + shadcn/ui
前端服务端状态	TanStack Query
前端客户端状态	Zustand
实时通信	原生 WebSocket
图表	Recharts
包管理	后端 uv · 前端 pnpm（npm 也行）

一键启动

./dev.sh

同时起后端 (:8000) + 前端 (:5173)，输出按 [be] / [fe] 前缀混流。Ctrl-C 一起停。详细玩法看 docs/playbook.md / docs/playbook-frontend.md。

Roadmap

• Phase 0：repo 骨架 + 文档体系 + frontend 手写脚手架
• Phase 1：后端裸引擎（状态机 + 角色 + mock agent + JSONL 日志 + pytest，64 用例全绿）
• Phase 2：MiMo LLM 调用层（异步 client + RPM 限流 + 429 重试 + prompt cache 友好结构 + safe_act 失败兜底）
• Phase 2.5：实战调优——prompt 重排让 cross-agent cache hit 5.6%→24.5%（Token Plan SGP 上 39.6%）；private_thought 限长让 JSON 解析错误 6.6%→0%
• Phase 3：FastAPI 服务（REST /api/games /api/personas /api/stats + WS /ws/games/<id>，74 测试绿）
• Phase 4：前端骨架（React Router + TanStack Query + Zustand + Tailwind + openapi-typescript + 5 路由 + WS hook）
• Phase 5：回放页升级——时间轴拖动 / 自动播放（0.5-8×）/ 聊天气泡 / 9 色座位调色板 / 死亡状态联动 / Watch 共用同一套视觉
• Phase 6：Dashboard——/dashboard 路由：4 张总览卡 + Recharts 横向胜率排行 + 16×16 共局胜率热图（HSL 红→绿映射）+ MBTI×Role 表 + Runs 表，全部聚合自 progress.jsonl
• Phase 7：Web 实时观战——WebSocket 推送，弹幕式渲染（B 站录视频用）
• Phase 8：Web 人机对战——你浏览器扮演任一座位，AI 通过 LLM 出招（集大成）
• Phase 9：16 MBTI 人格 + 立得住验证——16 个 YAML（id/description/speaking_style/tendencies/few_shot/metadata）；scripts/verify_personas.py 让每个 persona 反向做 16 题 Likert 量表 × 3 轮，16/16 全部稳定回到正确 MBTI（48 calls / ¥0.12）
• Phase 10a：批量 runner（src/runner/batch.py：checkpoint + 预算上限 + 两段式 Ctrl-C 优雅停止）→ docs/playbook-phase10-laptop.md
• Phase 10b：Mac Mini launchd 部署 + 全速跑批 1400 局
• Phase 11：静态发布站（GitHub Pages）+ B 站/小红书内容产出

并发模型

瓶颈是小米 API 配额（RPM=100），不是本地 CPU/内存。本地全 async，所以"开多协程"对 Python 是免费的，真正的限制在服务端。

单局内部：

阶段	并行性
夜晚行动（狼刀 + 预言家查验 + 女巫救/毒）	asyncio.gather 同时发请求
白天发言	严格串行（每人发言依赖前面所有人）
投票	asyncio.gather 同时亮票

跨局：2 个对局 concurrent，aiolimiter 全局令牌桶限到 RPM=80（留 20% 给重试）。这样一天产能约 50 局，正好打满 token 预算。

关键约束

• Token 预算：7 亿 / 28 天（小米 MiMo，到期 ~2026-05-30，月底清零）
• RPM：100（账号级总配额，不是 per-key）
• TPM：10M（不会触顶）
• 目标局数：~1400 局（每局约 50 万 tokens）

本地开发

后端

cd backend
uv sync                         # 装依赖
cp .env.example .env            # 配置 XIAOMI_API_KEY 等
uv run python -m src.runner.batch --run-id $(date +%F) --target 30  # 跑批量对战，详见 docs/playbook-phase10-laptop.md
uv run uvicorn src.api.main:app --reload  # 起 API 服务（Phase 3 之后）

前端

cd frontend
pnpm install                    # 或 npm install
pnpm dev                        # 起开发服务器，默认 http://localhost:5173
pnpm build                      # 生产构建

设备分工

设备	角色
MacBook Air M4	主开发
9800X3D + 5080 (Win11)	数据分析 / 蒸馏副业
Mac Mini M4 (16+256)	7×24 部署跑实验 + API 服务

文档索引

• CLAUDE.md —— Claude Code 工作约定（包管理、命名、async、JSON schema、测试命令）
• docs/architecture.md —— 前后端架构图 + REST/WS 端点清单
• docs/pitfalls.md —— 踩坑记录，写给未来的自己

License

MIT