AI 剧本杀（JianWang97/jubensha-ai）

一句话定位：128★ 的中文「AI 剧本杀」全栈平台——AI 剧本生成走 WebSocket 分步 ReAct Agent 流程，全流程（背景→开场→调查→讨论→投票→揭晓）由 AI 角色演绎；OpenAI 兼容端点可配。 类型：多智能体 AI 剧本杀平台 · 开源 · 许可：MIT · 仓库：JianWang97/jubensha-ai

1. 项目概述

与 ai-murder-mystery 同赛道但工程规格更高：FastAPI + Next.js 15 全栈、PostgreSQL + MinIO（或目录存储）、JWT 认证、Alembic 迁移、WebSocket 游戏引擎。最大亮点是剧本生成 Agent 架构：不是黑盒 HTTP 请求，而是 WebSocket 上的分步 ReAct 流程——LLM 的 thought/tool call/observation 以事件流透出到前端时间线（step_start/thought/action/observation/step_end/done），每个生成步骤（剧本信息/背景故事/角色/地点/证物/游戏阶段）独立事务落库，校验失败作为 observation 回喂 LLM 自我修正。剧本对话式编辑同样走 ReAct Agent（先 plan 再逐个工具调用）。

2. 核心功能

• 全流程游戏：背景 → 开场 → 调查 → 讨论 → 投票 → 揭晓，六阶段可配置。
• AI 剧本生成（分步 Agent，带断线回放 get_script_generation_state）+ AI 对话式编辑（plan → 工具调用，SAVEPOINT 回滚校验）。
• 推理透出：reasoning_content 与正式内容分离（split_think_tags），支持 DeepSeek 类推理模型。
• 角色音色绑定（TTS：MiniMax/CozyVoice）、图像生成、证物系统。
• JWT 认证中间件（路径正则策略：NONE/OPTIONAL/REQUIRED/ADMIN）+ 自定义 DI 容器（singleton/scoped/transient）。
• 前端 Zustand 状态管理 + 自动生成 OpenAPI 客户端。

3. 技术架构

• 后端：Python 3.13+（我们环境的 3.11 不满足——需 uv 托管 Python 3.13）/ FastAPI / SQLAlchemy（sync）/ Alembic / asyncpg / WebSocket 消息路由（type → handler registry，session 映射）。
• LLM：LLM_PROVIDER + OPENAI_API_KEY + OPENAI_BASE_URL + OPENAI_MODEL——可指向本地 KoboldCpp。
• 存储：PostgreSQL + MinIO（或 FILE_STORAGE=dir 目录模式，开发免 MinIO）。
• 前端：Next.js 15 Pages Router + shadcn/ui + Tailwind。

4. 本机实测记录（📋 评估完成，未实装）

• 依赖齐备可行性：本机已有 PostgreSQL 16.8；FILE_STORAGE=dir 免 MinIO；OPENAI_BASE_URL 可接本地模型。
• 未实装原因：Python 3.13 需另下载托管解释器 + 依赖面大（langchain/dashscope/asyncpg/minio 等 30 项）；已由 ai-murder-mystery 完成同类管线验证，此项目留作后续（评估结论：可跑，投入约 30 分钟环境 + 构建时间）。
• 参考启动：cd backend && uv sync && uv run python main.py（:8010）；前端 cd frontend && npm run dev（:3001）；Postgres+MinIO 用 docker compose -f docker-compose.dev.yml up -d（本机可改指已有 PG）。

5. 优劣势分析

6. 参考链接

• 仓库：https://github.com/JianWang97/jubensha-ai
• 同类：ai-murder-mystery（04 号文档）、Murder-Mystery-Game-Agentscope、ScriptWorld（多智能体聊天室引擎）、MimirFW（对话游戏搭建框架）