feat: init project with PRD document

AI剧本杀PRD.md

@@ -0,0 +1,777 @@
+# AI 剧本杀 — 产品需求文档（PRD）
+
+> 版本：V1.0 | 日期：2026年7月 | 状态： Draft
+> 目标读者：开发团队、设计师、产品经理
+> 本文档用于指导 Vibe Coding 全流程开发，按模块拆分，可直接落地。
+
+---
+
+## 一、产品概述
+
+### 1.1 产品定位
+
+AI 剧本杀是一个以 AI 驱动的线上剧本杀平台，核心解决"**凑不齐人就玩不了**"的终极痛点。1 位真人玩家即可开局（AI NPC 补位），多人模式空缺角色也由 AI 自动填充。
+
+### 1.2 产品 slogan
+
+**随时开局，人人都是主角。**
+
+### 1.3 核心指标（KPI）
+
+| 指标 | MVP 目标 | V1.0 目标 |
+|------|----------|-----------|
+| 单局完成率 | > 60% | > 80% |
+| 平均游戏时长 | 45-90 min | 可配置（30min - 4h） |
+| NPS（净推荐值） | > 30 | > 50 |
+| NPC 回复合理率 | > 70% | > 85% |
+| 防剧透漏出率 | < 5% | < 1% |
+
+---
+
+## 二、用户角色与场景
+
+### 2.1 用户画像
+
+| 角色 | 描述 | 核心需求 |
+|------|------|----------|
+| **独狼玩家** | 喜欢剧本杀但凑不到人 | 单人也能玩，不需要社交等待 |
+| **异地好友** | 朋友分散在不同城市 | 线上一起玩，AI 补位凑满 |
+| **新手小白** | 没玩过剧本杀怕尴尬 | AI 陪练无压力，有引导 |
+| **硬核推土机** | 推理爱好者，追求逻辑挑战 | 高难度剧本 + 严谨推理体验 |
+| **创作者** | 剧本作者，想变现 | 上传剧本 + 分成收入 |
+| **门店老板** | 线下剧本杀店主 | AI DM 降本增效 |
+
+### 2.2 核心用户场景
+
+| 编号 | 场景 | 用户 | 频率 |
+|------|------|------|------|
+| S01 | 晚上在家无聊，想玩一局剧本杀但凑不到人 | 独狼玩家 | 高频 |
+| S02 | 和异地朋友约好线上玩，但只有 3 个人凑不满 | 异地好友 | 中频 |
+| S03 | 第一次接触剧本杀，想试试但又不好意思去线下 | 新手小白 | 低频/一次 |
+| S04 | 周末想挑战高难度推理本，找不到合适的局 | 硬核推土机 | 中频 |
+| S05 | 写了一个剧本想分享并赚钱 | 创作者 | 低频 |
+| S06 | 门店 DM 不够用，用 AI 辅助带本 | 门店老板 | 高频 |
+
+---
+
+## 三、功能需求（按模块）
+
+> 优先级标记：P0 = MVP 必须，P1 = V1.0 必须，P2 = 后续迭代
+
+---
+
+### 3.1 用户系统
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| U-01 | 邮箱/手机号注册登录 | 基本账号体系 | P0 |
+| U-02 | 游客模式 | 不登录可体验 1 局 | P0 |
+| U-03 | 用户画像填写 | 推理偏好、情感类型、经验等级 | P1 |
+| U-04 | 多设备登录 | 同一账号可切换设备 | P1 |
+| U-05 | 历史记录 | 已完成游戏列表 + 复盘入口 | P0 |
+
+### 3.2 剧本系统
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| S-01 | 内置剧本库 | 预制 5 个剧本（含不同风格） | P0 |
+| S-02 | 剧本详情页 | 展示类型、人数、时长、难度、简介 | P0 |
+| S-03 | AI 生成剧本 | 用户输入主题/风格/人数，AI 生成完整剧本 | P1 |
+| S-04 | 上传解析剧本 | 支持上传 TXT/Markdown/PDF，AI 结构化提取 | P1 |
+| S-05 | 剧本质检 | 自动检测逻辑漏洞、线索链完整性 | P2 |
+| S-06 | 剧本评分/评价 | 玩家玩后可评分 + 文字评价 | P1 |
+| S-07 | 创作者上传 | 创作者直接上传结构化剧本到平台 | P2 |
+
+#### 剧本数据结构
+
+```json
+{
+  "id": "string",
+  "title": "剧本标题",
+  "type": "hardcore | emotional |欢乐 | 阵营 | 恐怖 | 还原",
+  "difficulty": 1-5,
+  "playerCount": { "min": 4, "max": 8 },
+  "duration": "2-3h",
+  "background": "公共背景故事",
+  "phases": [
+    {
+      "name": "第一幕",
+      "description": "场景描述",
+      "publicInfo": "所有玩家可见信息",
+      "clues": ["线索id1", "线索id2"]
+    }
+  ],
+  "roles": [
+    {
+      "id": "role_1",
+      "name": "角色名",
+      "avatar": "头像URL",
+      "publicProfile": "公开身份",
+      "secretProfile": "私密背景",
+      "secret": "隐藏的秘密",
+      "goal": "胜利目标",
+      "winCondition": "胜利条件"
+    }
+  ],
+  "clues": [
+    {
+      "id": "clue_1",
+      "name": "线索名",
+      "description": "线索描述",
+      "imagePrompt": "用于AI生图的提示词",
+      "phase": 1,
+      "triggerCondition": "触发条件" // 可选
+    }
+  ],
+  "truth": "完整真相"
+}
+```
+
+---
+
+### 3.3 游戏引擎（核心）
+
+#### 3.3.1 游戏流程控制
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| G-01 | 选本 | 浏览剧本库 → 选择剧本 | P0 |
+| G-02 | 选角 | 玩家选择角色，AI 分配剩余 NPC 角色 | P0 |
+| G-03 | 分幕推进 | DM Agent 按剧本分幕推进流程 | P0 |
+| G-04 | 公共讨论 | 所有角色（含 AI NPC）在公屏发言 | P0 |
+| G-05 | 私聊 | 玩家可与任一 AI NPC 一对一私聊 | P0 |
+| G-06 | 搜证 | DM 发放线索卡，玩家查看 | P0 |
+| G-07 | 举证 | 玩家在公屏出示线索卡质询 NPC | P0 |
+| G-08 | 投票 | 投票指认凶手或做出关键选择 | P0 |
+| G-09 | 复盘 | 展示真相、全角色秘密、对话回放 | P0 |
+
+#### 3.3.2 DM Agent
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| D-01 | 开场引导 | 朗读背景，介绍角色，说明规则 | P0 |
+| D-02 | 阶段推进 | 根据剧本分幕自动推进，切换场景 | P0 |
+| D-03 | 线索发放 | 按剧本配置 + 玩家进度发放线索卡 | P0 |
+| D-04 | 梯度扶车 | 玩家卡壳 20s 以上 → 微妙暗示 → 明确引导 | P1 |
+| D-05 | 节奏控制 | 超时自动推进，可缩短/延长阶段 | P1 |
+| D-06 | 投票管理 | 发起投票、统计结果、判定胜负 | P0 |
+| D-07 | 复盘生成 | 生成完整复盘报告 | P0 |
+| D-08 | 难度自适应 | 根据玩家推理表现动态调整复杂度 | P2 |
+
+#### 3.3.3 NPC Agent
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| N-01 | 信息隔离 | 仅知晓公共剧本 + 自己的私密剧本 | P0 |
+| N-02 | 角色扮演 | 按人设语气、风格发言，不串角色 | P0 |
+| N-03 | 策略行为 | 可撒谎、隐瞒、引导、反问 | P1 |
+| N-04 | 多轮记忆 | 记住玩家之前说过什么，跨轮一致 | P1 |
+| N-05 | 主动发言 | 在公共讨论中主动接话、点名回应 | P1 |
+| N-06 | 私聊回应 | 玩家私聊时以角色身份回应 | P0 |
+| N-07 | 线索反应 | 被举证时做出合理反应 | P1 |
+
+#### 3.3.4 特殊游戏类型支持
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| T-01 | 硬核推理流程 | 含中间推理节点、时间线梳理 | P1 |
+| T-02 | 情感沉浸流程 | 情感触发事件、角色内心独白 | P1 |
+| T-03 | 欢乐机制流程 | 随机事件卡、小游戏机制 | P2 |
+| T-04 | 阵营对抗流程 | 分组、结盟、背刺机制 | P2 |
+| T-05 | 恐怖流程 | 生存判定、心跳节奏 | P2 |
+| T-06 | 还原流程 | 碎片逐步披露、世界观拼合 | P1 |
+
+---
+
+### 3.4 沉浸式交互
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| I-01 | 文字聊天 | 全流程文字交互 | P0 |
+| I-02 | 语音合成（TTS） | AI 发言自动朗读，角色分音色 | P1 |
+| I-03 | 语音输入（ASR） | 玩家可直接说话输入 | P2 |
+| I-04 | 线索证据卡 UI | 图片+文字，公屏渲染，右侧牌堆 | P0 |
+| I-05 | 阶段共识板 | 显示已形成共识/分歧点/待核查 | P1 |
+| I-06 | 随身剧本册 | 随时查看自己的角色信息 | P0 |
+| I-07 | 头像/角色状态 | Agent 状态可视化（思考中/发言中） | P1 |
+| I-08 | 背景主题 | 根据剧本主题变换 UI 风格 | P2 |
+
+### 3.5 商用功能
+
+| 编号 | 功能 | 描述 | 优先级 |
+|------|------|------|--------|
+| B-01 | 付费墙 | 免费体验 1 局后引导付费 | P1 |
+| B-02 | 单局支付 | 支付宝/微信支付单局费用 | P1 |
+| B-03 | 订阅系统 | 月卡/季卡/年卡，自动续费 | P2 |
+| B-04 | 积分系统 | 签到、分享、评价赚积分 | P2 |
+| B-05 | 创作者收益 | 创作者查看收益、提现 | P2 |
+
+---
+
+## 四、非功能需求
+
+### 4.1 性能要求
+
+| 指标 | 要求 |
+|------|------|
+| AI 回复延迟 | < 3s（含 LLM 推理时间） |
+| 消息推送延迟 | < 500ms |
+| 并发支持 | MVP 支持 1000 局同时进行 |
+| 剧本加载时间 | < 2s |
+| 页面首屏加载 | < 3s |
+
+### 4.2 安全要求
+
+| 编号 | 要求 |
+|------|------|
+| SEC-01 | 用户密码加密存储（bcrypt） |
+| SEC-02 | API 请求鉴权（JWT） |
+| SEC-03 | 用户数据隔离，不能访问他人游戏数据 |
+| SEC-04 | AI 内容合规过滤（敏感词库 + 审核） |
+| SEC-05 | 防剧透：NPC 不能泄露私密剧本信息 |
+| SEC-06 | API 限流，防止滥用 |
+
+### 4.3 可用性要求
+
+- 系统可用时间 > 99.5%
+- 支持 7x24 小时运行
+- 关键操作有 Loading 状态反馈
+- 网络断开时提示用户，自动重连
+- 游戏中间可暂停，下次继续
+
+### 4.4 兼容性要求
+
+| 平台 | MVP | V1.0 |
+|------|-----|------|
+| Web (Chrome/Firefox/Edge) | ✅ | ✅ |
+| 移动端 H5 | ✅ | ✅ |
+| 微信小程序 | ❌ | ✅ |
+| iOS App | ❌ | ✅ |
+| Android App | ❌ | ✅ |
+
+---
+
+## 五、AI Agent 详细设计
+
+### 5.1 Agent 通信架构
+
+```
+玩家输入
+    │
+    ▼
+Agent Orchestrator
+    │
+    ├─→ DM Agent (负责主持、控场、线索)
+    │      │
+    │      ├─→ 判断当前阶段 → 执行阶段动作
+    │      ├─→ 检测玩家进度 → 判断是否扶车
+    │      └─→ 管理线索发放队列
+    │
+    ├─→ NPC Agent Pool
+    │      │
+    │      ├─→ NPC_1 (信息边界: 公共+私密1)
+    │      ├─→ NPC_2 (信息边界: 公共+私密2)
+    │      ├─→ NPC_3 ...
+    │      └─→ NPC_n ...
+    │
+    └─→ 输出分发 → 玩家可见 + 相应NPC可见
+```
+
+### 5.2 DM Agent Prompt 结构
+
+```
+系统指令:
+  你是剧本杀主持人（DM），负责主持一场完整的剧本杀游戏。
+  你的职责：
+  1. 引导流程：按剧本分幕推进，朗读场景描述
+  2. 发放线索：在适当时机发放线索卡
+  3. 控场节奏：维持讨论热度，适时推进
+  4. 扶车引导：玩家卡壳时提供提示
+  5. 保持公正：不偏袒任何角色
+
+  当前剧本: {剧本标题}
+  当前阶段: {阶段名称}
+  已发放线索: {线索列表}
+  玩家进度: {进度评估}
+
+  回复格式: 严格 JSON
+  {
+    "action": "narrate | release_clue | prompt | advance_phase | vote | complete",
+    "content": "你的发言内容",
+    "clue_id": "如果是release_clue,这里填线索id",
+    "next_phase": "如果是advance_phase,这里填下一阶段"
+  }
+```
+
+### 5.3 NPC Agent Prompt 结构
+
+```
+系统指令:
+  你是剧本杀中的一个角色。玩家正在调查一桩案件，你需要以角色身份参与。
+
+  角色信息:
+  - 姓名: {角色姓名}
+  - 公开身份: {公开信息}
+  - 你的秘密: {私密信息}（绝对不要主动透露！）
+  - 你的目标: {个人目标}
+  - 人物性格: {性格描述}
+
+  行为规则:
+  1. 始终保持角色身份发言
+  2. 你的秘密绝对不能主动说出
+  3. 被问到时可以撒谎、回避、转移话题
+  4. 不要全知视角，你只知道自己的信息
+  5. 记住玩家之前问过你什么
+
+  当前上下文:
+  - 阶段: {阶段名称}
+  - 公共已知信息: {公共信息}
+  - 最近发言: {最近几轮消息}
+
+  回复格式: 严格 JSON
+  {
+    "content": "你的发言",
+    "action": "speak |  remain_silent"
+  }
+```
+
+### 5.4 扶车梯度算法
+
+```
+Level 1 - 微妙提示 (玩家卡壳 20-40s):
+  "你们有没有注意到某条线索的某个细节？"
+  "要不大家复盘一下时间线？"
+
+Level 2 - 明确引导 (玩家卡壳 40-60s):
+  "我觉得线索 3 和角色 A 的发言之间有矛盾"
+  "建议大家重点讨论一下案发时间段每个人的动向"
+
+Level 3 - 直接揭示 (玩家卡壳 > 60s):
+  "如果你们把线索 1 和线索 5 放在一起看……"
+  直接指出关键逻辑链
+```
+
+### 5.5 防剧透三层校验
+
+```
+Layer 1 - 初始生成:
+  NPC 的 System Prompt 中只包含：
+  - 公共剧本（所有玩家可见）
+  - 该角色的私密剧本（仅该角色可见）
+  - 不包含任何其他角色的私密信息
+
+Layer 2 - 批评检测:
+  NPC 生成回复后，用独立检测 Agent 检查：
+  - 是否泄露了私密剧本中的关键信息
+  - 是否出现了全知视角
+  - 如有问题 → 拦截并重新生成
+
+Layer 3 - 智能修订:
+  如果检测到轻微泄露倾向，自动修订回复：
+  - 替换为模糊表述
+  - 转向其他话题
+  - 用反问化解
+```
+
+---
+
+## 六、数据库表结构（核心表）
+
+### 6.1 users
+
+```sql
+CREATE TABLE users (
+  id            UUID PRIMARY KEY,
+  email         VARCHAR(255) UNIQUE,
+  nickname      VARCHAR(50),
+  avatar_url    TEXT,
+  password_hash VARCHAR(255),
+  role          ENUM('player', 'creator', 'admin') DEFAULT 'player',
+  preferences   JSONB,        -- 推理偏好、情感类型等画像
+  game_count    INT DEFAULT 0,
+  token_version INT DEFAULT 0,
+  created_at    TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.2 scripts
+
+```sql
+CREATE TABLE scripts (
+  id              UUID PRIMARY KEY,
+  title           VARCHAR(200),
+  type            VARCHAR(50),   -- hardcore/emotional/欢乐/阵营/恐怖/还原
+  difficulty      INT CHECK(1-5),
+  min_players     INT,
+  max_players     INT,
+  duration_min    INT,           -- 预计时长(分钟)
+  background      TEXT,          -- 公共背景故事
+  config          JSONB,         -- 完整剧本数据结构(含roles/clues/phases)
+  source          ENUM('builtin', 'ai_generated', 'uploaded', 'creator'),
+  creator_id      UUID REFERENCES users,
+  status          ENUM('draft', 'published', 'disabled'),
+  rating_avg      DECIMAL(2,1),
+  play_count      INT DEFAULT 0,
+  created_at      TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.3 game_sessions
+
+```sql
+CREATE TABLE game_sessions (
+  id            UUID PRIMARY KEY,
+  script_id     UUID REFERENCES scripts,
+  status        ENUM('waiting', 'playing', 'paused', 'completed'),
+  phase         VARCHAR(100),     -- 当前阶段
+  phase_index   INT DEFAULT 0,
+  started_at    TIMESTAMP,
+  completed_at  TIMESTAMP,
+  config        JSONB,            -- 游戏配置(计时设置等)
+  created_at    TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.4 session_players
+
+```sql
+CREATE TABLE session_players (
+  id            UUID PRIMARY KEY,
+  session_id    UUID REFERENCES game_sessions,
+  user_id       UUID REFERENCES users,
+  role_id       VARCHAR(100),    -- 剧本中的角色id
+  is_human      BOOLEAN DEFAULT TRUE,
+  is_ready      BOOLEAN DEFAULT FALSE,
+  agent_id      VARCHAR(100),    -- 如果是AI,对应的agent实例id
+  status        ENUM('active', 'left', 'eliminated'),
+  joined_at     TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.5 chat_messages
+
+```sql
+CREATE TABLE chat_messages (
+  id              UUID PRIMARY KEY,
+  session_id      UUID REFERENCES game_sessions,
+  sender_role_id  VARCHAR(100),     -- 发言者角色id
+  message_type    ENUM('public', 'private', 'system', 'clue'),
+  content         TEXT,
+  target_role_id  VARCHAR(100),     -- 私聊目标(public时为null)
+  clue_id         VARCHAR(100),     -- 如果是举证消息
+  phase_index     INT,
+  created_at      TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.6 clues_state
+
+```sql
+CREATE TABLE clues_state (
+  id            UUID PRIMARY KEY,
+  session_id    UUID REFERENCES game_sessions,
+  clue_id       VARCHAR(100),      -- 剧本中的线索id
+  status        ENUM('unreleased', 'released', 'revealed'),
+  revealed_by   VARCHAR(100),      -- 谁发现的
+  released_at   TIMESTAMP,
+  created_at    TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 6.7 votes
+
+```sql
+CREATE TABLE votes (
+  id            UUID PRIMARY KEY,
+  session_id    UUID REFERENCES game_sessions,
+  round         INT,               -- 第几轮投票
+  voter_id      UUID REFERENCES session_players,
+  target_id     UUID REFERENCES session_players,
+  reason        TEXT,
+  created_at    TIMESTAMP DEFAULT NOW()
+);
+```
+
+---
+
+## 七、API 设计（核心接口）
+
+### 7.1 用户接口
+
+```
+POST   /api/auth/register         注册
+POST   /api/auth/login            登录
+POST   /api/auth/logout           登出
+GET    /api/user/profile          获取用户信息
+PUT    /api/user/profile          更新用户信息
+GET    /api/user/history          游戏历史
+```
+
+### 7.2 剧本接口
+
+```
+GET    /api/scripts               剧本列表（带过滤/搜索/排序）
+GET    /api/scripts/:id           剧本详情
+POST   /api/scripts/generate      AI 生成剧本 {theme, style, players}
+POST   /api/scripts/upload        上传解析剧本 (multipart)
+POST   /api/scripts/:id/submit    创作者提交剧本（审核）
+```
+
+### 7.3 游戏接口
+
+```
+POST   /api/games/create          创建游戏房间 {script_id, mode}
+GET    /api/games/:id             获取游戏状态
+POST   /api/games/:id/join        加入游戏 {role_id}
+POST   /api/games/:id/start       开始游戏（DM 就绪后）
+POST   /api/games/:id/chat        发送消息 {type, content, target_id}
+POST   /api/games/:id/clue/:cli_id/reveal  举证线索
+POST   /api/games/:id/vote        投票 {target_id, reason}
+POST   /api/games/:id/pause       暂停
+POST   /api/games/:id/resume      继续
+POST   /api/games/:id/skip        跳过当前阶段
+GET    /api/games/:id/replay      获取复盘数据
+```
+
+### 7.4 WebSocket 接口
+
+```
+连接: ws://host/ws?game_id=&user_id=&token=
+
+服务端 → 客户端消息:
+{
+  "type": "chat_message" | "clue_released" | "phase_change" | "vote_start" | "vote_result" | "game_end" | "npc_status" | "consensus_update",
+  "data": { ... }
+}
+
+客户端 → 服务端消息:
+{
+  "type": "chat" | "vote" | "reveal_clue" | "request_hint" | "request_summary",
+  "data": { ... }
+}
+```
+
+---
+
+## 八、UI/UX 设计规范
+
+### 8.1 设计风格
+
+- **整体风格**：暗色主题，沉浸式推理氛围
+- **主色调**：#1a1a2e（深蓝黑）、#16213e（藏蓝）、#0f3460（普鲁士蓝）、#e94560（戏剧红）
+- **字体**：系统字体栈，中文用 Microsoft YaHei / PingFang SC
+- **布局**：左中右三栏（左侧角色列表，中间主聊天区，右侧线索/共识面板）
+
+### 8.2 页面结构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  顶部导航: Logo | 剧本库 | 历史 | 商城 | 用户菜单        │
+├──────┬──────────────────────────────────┬────────────────┤
+│      │                                  │                │
+│ 角色  │      主聊天区（公共+私聊频道）       │   线索牌堆     │
+│ 列表  │                                  │   (证据卡)     │
+│      │  ┌────────────────────────────┐  │                │
+│ NPC1 │  │  DM: 欢迎来到雾港庄园...    │  │ 线索1 [图片]   │
+│ NPC2 │  │  玩家A: 我觉得凶手是XX      │  │ 线索2 [图片]   │
+│ NPC3 │  │  NPC1: 你凭什么怀疑我？     │  │ 线索3 [图片]   │
+│ 玩家 │  │  ...                       │  │                │
+│      │  └────────────────────────────┘  │  共识板         │
+│      │                                  │  已形成: xxx    │
+│      │  输入框 [ 请输入... ] [发送] 🎤 │  分歧: xxx      │
+│      │                                  │                │
+├──────┴──────────────────────────────────┴────────────────┤
+│  底部状态: 阶段: 第一幕讨论中 | 已用时间: 35min | DM状态: 正常 │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 8.3 核心交互流程
+
+```
+首页
+ ├─ 快速开始（推荐热门剧本）
+ ├─ 剧本库（浏览/搜索/筛选）
+ │    └─ 剧本详情 → 选择角色 → 确认开始
+ ├─ 历史记录 → 继续/复盘
+ └─ 个人中心 → 画像/设置/订阅
+
+游戏中:
+  DM开场 → 玩家读本 → 自我介绍 → 分幕推进
+      ↓                              ↓
+  私聊 ← → 公聊 ← → 搜证/举证    DM扶车
+      ↓
+  投票 → 结局判定 → 复盘
+```
+
+### 8.4 关键 UI 组件
+
+| 组件 | 说明 |
+|------|------|
+| **剧本卡片** | 封面图+类型标签+难度星+时长+人数 |
+| **角色选择器** | 角色头像/名称/一句话简介/适合人群标签 |
+| **聊天消息** | 头像+角色名+时间+内容；DM 消息特殊样式 |
+| **线索卡** | AI 生成图片 + 标题 + 描述，可点击放大 |
+| **共识板** | 左侧栏，分"已形成共识/分歧点/待核查"三区 |
+| **投票面板** | Modal 弹窗，选择目标 + 填写理由 |
+| **复盘报告** | 时间线 + 真相 + 角色秘密全公开 + 投票记录 |
+
+---
+
+## 九、开发优先级与里程碑
+
+### 9.1 MVP 范围（Month 1-3）
+
+**必须完成**：
+- [ ] 用户注册登录（邮箱 + 游客）
+- [ ] 内置 5 个预制剧本
+- [ ] 单人模式（1 真人 + N AI NPC）
+- [ ] DM Agent：分幕推进、线索发放、投票管理、复盘
+- [ ] NPC Agent（3-5 个）：信息隔离、角色扮演、私聊
+- [ ] 公共聊天 + 私聊
+- [ ] 线索证据卡（文字+图片）
+- [ ] 投票系统
+- [ ] 复盘（真相+投票记录）
+- [ ] 响应式 Web 界面
+
+**不纳入 MVP**：
+- ❌ AI 生成剧本
+- ❌ 上传解析剧本
+- ❌ 语音交互（TTS/ASR）
+- ❌ 多人模式
+- ❌ 付费系统
+- ❌ 类型特化流程（情感/欢乐/阵营/恐怖）
+- ❌ 共识板
+- ❌ 梯度扶车
+
+### 9.2 V1.0 范围（Month 4-6）
+
+在 MVP 基础上增加：
+- [ ] AI 生成剧本（输入主题+风格生成完整剧本）
+- [ ] 上传解析剧本（TXT/Markdown/PDF）
+- [ ] 多人模式（含 AI 补位）
+- [ ] 全部 6 种游戏类型流程
+- [ ] TTS 语音朗读
+- [ ] 共振板
+- [ ] 梯度扶车
+- [ ] 付费系统（单局付费）
+- [ ] 微信小程序
+
+### 9.3 后续迭代（Month 7+）
+
+- ASR 语音输入
+- 创作者 UGC 平台
+- 订阅系统
+- iOS/Android App
+- B 端 SaaS
+- VR 版本预研
+
+---
+
+## 十、技术实现要点
+
+### 10.1 LLM 选型建议
+
+| 用途 | 推荐模型 | 原因 |
+|------|----------|------|
+| DM Agent | Claude Sonnet 4 / GPT-4o | 需长上下文、结构化输出 |
+| NPC Agent | Claude Haiku / DeepSeek | 高频调用，性价比优先 |
+| 剧本生成 | Claude Opus / GPT-4 | 需创造力和逻辑性 |
+| 防剧透检测 | GPT-4o-mini / DeepSeek | 低成本高频 |
+| 本地兜底 | Ollama + Qwen2.5 | 离线、低成本 |
+
+### 10.2 成本控制策略
+
+| 策略 | 说明 |
+|------|------|
+| **小模型兜底** | 简单回复用本地小模型，复杂推理用大模型 |
+| **响应缓存** | 相似问题命中缓存，减少 LLM 调用 |
+| **批量生成** | NPC 发言队列化，合并请求 |
+| **流式输出** | SSE 流式推送，降低用户感知延迟 |
+| **Token 预算** | 每个 Agent 严格限制 max_tokens |
+
+### 10.3 游戏状态管理
+
+```
+状态机:
+  WAITING → READING → INTRO → PHASE_1 → DISCUSSION_1
+    → SEARCH → DISCUSSION_2 → ... → VOTE → RESULT → REPLAY
+
+每个阶段的状态:
+{
+  "session_id": "...",
+  "phase": "PHASE_1",
+  "phase_started_at": "2026-07-28T12:00:00Z",
+  "time_limit": 1800,    // 秒
+  "is_paused": false,
+  "clues_released": ["clue_1"],
+  "consensus": {
+    "formed": ["xx是凶手"],
+    "disagreements": ["作案动机"],
+    "to_check": ["时间线"]
+  }
+}
+```
+
+### 10.4 参考开源项目
+
+| 项目 | 地址 | 可复用部分 |
+|------|------|-----------|
+| **SoloPlay** | github.com/pengcong2020520/soloplay | Agent 架构、信息隔离机制、TTS 集成、共识板 |
+| **AI Murder Mystery** | github.com/ScottishFold007/ai-murder-mystery | 防泄露三层校验、多 LLM 路由、自定义剧本 |
+| **MysteryHost AI Lite** | github.com/yuuu956/mysteryhost-ai-lite | 防剧透设计、Prompt 模块化、评测体系 |
+
+---
+
+## 十一、验收标准
+
+### 11.1 MVP 验收
+
+| 验收项 | 标准 |
+|--------|------|
+| 单人完成一局完整剧本杀 | 选本→选角→分幕→讨论→搜证→投票→复盘 全流程跑通 |
+| AI NPC 正常对话 | 4 个 NPC 均在公聊/私聊中合理回应 |
+| DM 正常主持 | 分幕推进、线索发放、投票引导正常 |
+| 信息隔离通过 | NPC 不会说出其他角色的秘密 |
+| 复盘正常 | 真相展示 + 投票记录 |
+
+### 11.2 质量验收
+
+| 验收项 | 标准 |
+|--------|------|
+| NPC 回复延迟 | 平均 < 3s，P95 < 5s |
+| 防剧透漏出率 | < 5%（人工抽检 100 条 NPC 回复） |
+| 游戏完成率 | > 60%（用户不主动退出的比例） |
+| 用户满意度 | 内测 NPS > 30 |
+
+---
+
+## 十二、附录
+
+### 12.1 术语表
+
+| 术语 | 说明 |
+|------|------|
+| DM | 游戏主持人，负责控场、发线索、推进流程 |
+| NPC | 非玩家角色，由 AI 扮演 |
+| Agent | 智能体，LLM + Prompt 驱动的自主角色 |
+| 扶车 | DM 在玩家卡壳时提供提示引导 |
+| 信息隔离 | NPC 只能看到自己的信息，不能全知视角 |
+| 防剧透 | 防止 AI NPC 意外泄露关键信息 |
+| 公聊 | 所有玩家可见的公开讨论 |
+| 私聊 | 两人之间的一对一秘密交流 |
+| 举证 | 出示线索卡质询其他角色 |
+| 复盘 | 游戏结束后回顾真相和过程 |
+
+### 12.2 MVP 剧本需求（5 个内置剧本）
+
+| 编号 | 名称 | 类型 | 角色数 | 预计时长 | 难度 |
+|------|------|------|--------|----------|------|
+| 1 | 雾港庄园谋杀案 | 推理（本格） | 5 人 | 60-90min | ⭐⭐ |
+| 2 | 零号舱的悖论 | 硬核（新本格） | 5 人 | 90-120min | ⭐⭐⭐⭐ |
+| 3 | 遗忘照相馆 | 情感（亲情） | 4 人 | 45-60min | ⭐ |
+| 4 | 翡翠城的交易 | 欢乐机制 | 6 人 | 60-90min | ⭐⭐ |
+| 5 | 阴雨公寓 | 恐怖还原 | 5 人 | 60-90min | ⭐⭐⭐ |
+
+---
+
+> **说明**：本 PRD 采用"渐进式交付"策略。MVP 阶段只做单人硬核推理本闭环，验证核心 AI Agent 能力；V1.0 扩展到全类型和多人模式；后续迭代叠加商用和生态能力。每个阶段的开发遵循"先跑通、再优化"原则。