1. 项目概述:基于多智能体的剧本杀平台设计
作为一名参与过多个AI应用落地的开发者,当我第一次接触这个剧本杀平台项目时,立刻意识到其独特价值。这不是简单的聊天机器人集合,而是一个将游戏规则、角色扮演和推理逻辑系统化的复杂工程。我们团队将其命名为ScriptWorld,目标是打造一个既能保留剧本杀社交乐趣,又能通过智能体技术提升游戏流畅度的创新平台。
项目的核心挑战在于如何平衡"自由度"与"规则性"。传统剧本杀依赖真人主持控场,而我们要用多个AI智能体分别承担不同职责,同时确保游戏流程符合剧本设定。这需要精心设计的系统架构和清晰的角色分工,这也是我在项目中主要负责的部分。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 系统架构设计解析
2.1 四层架构设计思路
经过多次方案讨论,我们最终确定了四层架构方案,每一层都有明确的职责边界:
-
前端交互层(React+TypeScript)
- 采用Vite构建工具提升开发效率
- 实现游戏全流程界面:从登录注册到复盘页面
- 特别设计了"线索展示"组件,支持图片、文字混合呈现
- 使用WebSocket保持实时通信,确保消息及时性
-
后端服务层(FastAPI)
- 选择FastAPI因其异步特性适合实时交互场景
- 实现了JWT认证保障用户安全
- 设计了一套完整的房间管理API
- 开发了专门的Agent调度接口
-
游戏引擎层
- 独立开发的GameEngine模块
- 维护游戏核心状态:房间、玩家、线索等
- 实现阶段状态机管理
- 处理投票逻辑和结局判定
-
智能体协作层
- Lobby Agent:处理大厅交互
- DM Agent:担任游戏主持人
- NPC Agent:扮演非玩家角色
- AgentRunner:统一调度入口
提示:这种分层设计的关键在于明确各层职责,避免功能重叠。例如游戏引擎层只关心状态管理,不涉及具体AI生成逻辑。
2.2 架构图解析

架构图中清晰展示了数据流向:
- 用户操作通过前端发起API调用
- 后端服务处理请求并更新游戏状态
- 游戏引擎根据状态决定路由
- 相应Agent生成响应
- 结果通过SSE推送回前端
这种设计确保了系统的可扩展性,未来可以方便地添加新的Agent类型或游戏机制。
3. 多智能体系统设计细节
3.1 Agent职责划分
在ScriptWorld中,我们为每个Agent设定了明确的职责边界:
Lobby Agent
- 处理玩家匹配
- 剧本选择引导
- 角色分配
- 游戏准备检查
DM Agent
- 控制游戏流程
- 引导讨论方向
- 管理线索发放
- 组织投票环节
- 宣布游戏结果
NPC Agent
- 保持角色一致性
- 管理角色秘密信息
- 响应玩家提问
- 参与剧情互动
3.2 Agent交互协议
我们设计了一套标准的Agent通信协议:
json复制{
"message_id": "uuid",
"room_id": "string",
"sender_type": "player|dm|npc",
"sender_id": "string",
"recipient_type": "player|dm|npc|all",
"recipient_id": "string",
"content": "string",
"phase": "intro|investigation|voting...",
"timestamp": "ISO8601"
}
这种结构化消息格式确保了系统各组件能准确理解消息上下文。
3.3 状态机设计
剧本杀的核心在于阶段性推进,我们设计了精细的状态机:
mermaid复制stateDiagram-v2
[*] --> waiting
waiting --> intro: 所有玩家准备就绪
intro --> self_intro: DM完成背景介绍
self_intro --> investigation: 所有角色完成自我介绍
investigation --> discussion: 调查时间结束
discussion --> voting: DM发起投票
voting --> reveal: 投票完成
reveal --> complete: 结局公布
complete --> [*]
每个状态转换都有明确的触发条件,确保游戏按照剧本设计推进。
4. 关键技术实现方案
4.1 剧本数据结构设计
我们选择YAML作为剧本描述语言,因其兼具可读性和结构性。一个完整的剧本文件包含以下部分:
yaml复制meta:
title: "庄园谜案"
description: "一桩发生在贵族庄园的谋杀案"
difficulty: 3
duration: 120
min_players: 5
max_players: 8
roles:
- id: "butler"
display: "管家"
identity: "庄园的忠实仆人"
type: "npc"
public_info: "已在庄园工作30年"
hidden_info: "与受害者有债务纠纷"
faction: "neutral"
clues:
- id: "c1"
phase: "investigation"
location: "书房"
content: "发现撕碎的借条"
related_roles: ["butler"]
这种结构设计使策划人员可以独立维护剧本内容,无需开发介入。
4.2 Agent提示词工程
与传统聊天机器人不同,我们的提示词更注重行为约束。以DM Agent为例:
code复制你是一名专业的剧本杀主持人,必须严格遵守以下规则:
1. 按照当前游戏阶段({phase})引导流程
2. 只使用剧本({script})中提供的信息
3. 每次只推进一个明确的步骤
4. 保持中立,不透露关键信息
5. 控制每个阶段的时间在合理范围内
当前阶段目标:{phase_goal}
可用线索:{available_clues}
活跃角色:{active_roles}
玩家输入:{input}
这种提示设计确保Agent行为符合游戏规则,而非自由发挥。
4.3 实时消息系统
我们采用SSE(Server-Sent Events)实现实时消息推送,相比WebSocket更轻量:
python复制@app.get('/stream/{room_id}')
async def stream_updates(room_id: str):
def event_stream():
while True:
if new_messages := check_messages(room_id):
yield f"data: {json.dumps(new_messages)}\n\n"
await asyncio.sleep(0.1)
return StreamingResponse(event_stream(), media_type="text/event-stream")
前端通过EventSource接口监听消息,实现实时更新。
5. 开发经验与避坑指南
5.1 多团队协作要点
- 接口先行:前后端先定义API规范,再并行开发
- Mock数据:前端使用Mock服务模拟后端响应
- 版本控制:严格管理剧本YAML的版本变更
- 日志规范:统一日志格式便于问题追踪
5.2 性能优化技巧
- Agent响应缓存:对常见问题缓存回答
- 连接池管理:复用LLM连接减少延迟
- 批量处理:合并相邻时间段的SSE推送
- 预加载:提前加载下一阶段可能用到的资源
5.3 常见问题排查
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 消息延迟 | SSE连接中断 | 实现自动重连机制 |
| Agent响应不一致 | 提示词边界不清 | 强化角色约束条件 |
| 状态切换失败 | 条件判断不完整 | 添加详细的日志记录 |
| 内存泄漏 | 未释放房间资源 | 实现超时自动清理 |
6. 项目演进方向
目前我们已经实现了基础版本,未来计划:
- 增加语音交互支持
- 开发剧本编辑器工具
- 引入强化学习优化Agent行为
- 支持自定义规则扩展
- 实现跨房间联动剧情
这个项目的独特之处在于将游戏设计与AI技术深度结合。通过明确的分工和状态管理,我们让多个智能体能够协同工作,创造出连贯的游戏体验。在开发过程中,最关键的领悟是:好的AI应用不是追求最强大的模型,而是设计最合理的系统架构。
