# Hermes Live Show — 功能清单

## 一、剧本管理

| 功能 | 说明 |
|------|------|
| 自然语言剧本导入 | 粘贴文本，由 AI 自动解析为结构化数据（角色、线索、阶段） |
| JSON 剧本导入 | 精确导入 JSON 格式的剧本 |
| 剧本解析预览 | 上传后在确认导入前预览解析结果 |
| 剧本列表 | 查看所有已导入剧本，显示角色数量、创建时间 |
| 剧本选中 | 选择当前使用的剧本（高亮标记） |
| 剧本删除 | 删除不需要的剧本 |
| 解析降级兜底 | AI 解析失败时，用正则 fallback 提取角色名 |

---

## 二、AI 角色系统

| 功能 | 说明 |
|------|------|
| 自动角色生成 | 根据剧本中的角色名批量创建角色 |
| 随机凶手分配 | 自动随机指定 1 个 KILLER，其余为 SUSPECT |
| SOUL 人格配置 | 每个角色生成 `SOUL.md`（性格、说话风格、秘密、动机等） |
| Hermes Profile 管理 | 为每个角色创建独立的 AI persona（文件系统存储） |
| 角色 SOUL 编辑 | 手动更新角色的 SOUL 内容和知识库 |
| 角色状态管理 | 支持 ALIVE / DEAD / INACTIVE 三种状态切换 |
| 角色删除 | 删除角色及其 Hermes profile |
| 手动触发角色发言 | 输入提示词让指定角色即时回应 |

---

## 三、8 阶段游戏流程

```
intro → round1_speak → round1_search → round2_speak → round2_search → final_discuss → voting → reveal
```

| 阶段 | 说明 |
|------|------|
| intro | 开场介绍 |
| round1_speak | 第一轮发言 |
| round1_search | 第一轮搜证 |
| round2_speak | 第二轮发言 |
| round2_search | 第二轮搜证 |
| final_discuss | 最终讨论 |
| voting | 投票环节 |
| reveal | 揭晓真凶 |

- 前进 / 后退阶段
- 进度条百分比实时显示

---

## 四、AI 自动对话

| 功能 | 说明 |
|------|------|
| 自动轮流发言 | AI 角色按顺序依次发言，每人 2-4 句中文 |
| 上下文感知 | 基于最近 20 条消息构建上下文 |
| 可配置间隔 | 发言间隔默认 8 秒，可自定义 |
| 可配置轮数 | 支持多轮自动发言 |
| 随时启停 | 主播可随时开始/停止自动对话 |
| 自动投票 | 触发后所有 AI 角色根据讨论摘要投票选出凶手 |
| 投票 JSON 输出 | 每个角色返回 `{"target": "角色名", "reason": "理由"}` |
| 投票容错 | 解析失败时随机投给他人 |

---

## 五、主播控制台（ControlView）

| 功能 | 说明 |
|------|------|
| 阶段控制器 | 按钮式阶段切换、开始/暂停/恢复/重置游戏 |
| 手动注入消息 | 选择角色 → 输入提示词 → AI 即时回应 |
| 进度条 | 游戏进度可视化 |
| 角色列表面板 | 点击角色弹出详情弹窗（RoleModal） |
| 线索面板 | 查看所有线索及解锁状态 |
| 一键生成 Profiles | 为所有角色创建 AI 人格 |
| Socket 连接状态 | WebSocket 连接状态指示（绿点/红点） |
| 导航 | 可跳转到观众视角和剧本管理 |

---

## 六、观众视角（LiveView）

| 功能 | 说明 |
|------|------|
| 实时聊天日志 | 查看所有角色的实时发言 |
| LIVE 标识 | 游戏进行中有脉冲动画 LIVE 标识 |
| 阶段显示 | 当前阶段的中文标签（如"💬 第一轮发言"） |
| 登场角色列表 | 侧边栏展示角色名及首字母头像 |
| 已死亡角色灰显 | DEAD 状态角色降低透明度 |
| 已解锁线索 | 实时展示已解锁的线索 |
| 待解锁线索计数 | 提示剩余未解锁线索数量 |
| 进度条 | 游戏整体进度 |

---

## 七、线索系统

| 功能 | 说明 |
|------|------|
| 5 种线索类型 | PHYSICAL（物证）、TESTIMONY（证词）、MOTIVE（动机）、ALIBI（不在场证明）、FORENSIC（法医） |
| 线索归属 | 可指定线索属于某个角色 |
| 按阶段分配 | 线索绑定到 round1_search 或 round2_search |
| 3 种可见性 | ALL（全员可见）、SPECIFIC（指定角色可见）、HIDDEN（隐藏） |
| 线索解锁 | 通过 Socket 实时解锁并广播 |
| 解锁记录 | 记录谁、何时解锁了线索 |

---

## 八、投票系统

| 功能 | 说明 |
|------|------|
| 手动投票 | API 创建投票记录 |
| AI 自动投票 | 所有 AI 角色自动投票（带理由） |
| 多轮投票 | 支持 round_number 区分轮次 |
| 投票实时广播 | Socket 广播 `vote_cast` 和 `voting_results` 事件 |
| 投票查询 | 按轮次查询投票结果 |

---

## 九、实时通信（Socket.IO）

| 事件 | 方向 | 用途 |
|------|------|------|
| `new_message` | S→C | 新消息广播 |
| `state_change` | S→C | 游戏阶段/进度变更 |
| `speaker_change` | S→C | 当前发言者变更 |
| `vote_cast` | S→C | 投票投出 |
| `voting_results` | S→C | 投票结果汇总 |
| `clue_unlocked` | S→C | 线索解锁通知 |
| `system` | S→C | 系统消息 |
| `send_message` | C→S | 发送消息 |
| `dm_command` | C→S | 主播命令（阶段切换/自动对话/触发投票） |
| `request_state` | C→S | 请求当前游戏状态 |

---

## 十、AI 退化容错

| 场景 | 处理方式 |
|------|----------|
| Hermes 超时 / 连接失败 | 显示「AI引擎暂时不可用，请稍后再试」 |
| Profile 列表获取失败 | 回退到上次成功获取的列表 |
| JSON 解析失败 | 自动 fallback 到正则解析 |
| 投票目标无效 | 随机选择他人投票 |

---

## 十一、部署

- Docker Compose 一键启动 4 个服务（Postgres + Hermes + Backend + Frontend）
- 开发环境热重载（volume 挂载）
- 健康检查（Postgres pg_isready / Hermes /models 端点）