growork 1.0.1 → 1.1.1

package/test/backend-ai.md

@@ -1,539 +0,0 @@
-# Bloomo AI 客户端对接文档
-
-## 概述
-
-
-Bloomo AI 是一个基于 LiveKit 的实时语音塔罗解读助手。系统包含三个核心 Agent，通过智能状态管理实现问题澄清、牌阵选择、抽牌、解读的完整流程。**支持单个 Session 内无限轮次的塔罗解读。**
-
-
-## 多轮会话设计
-
-
-### 轮次 (Round) 概念
-
-
-- **Session**：用户与 AI 的一次完整会话，包含多个轮次
-- **Round**：单次问题澄清 + 抽牌 + 解读的完整流程
-- **round_id 格式**：`{session_id}_round_{n}`，如 `session-abc-123_round_0`、`session-abc-123_round_1`
-
-### 轮次生命周期
-
-
-| 阶段 | 动作 | round_id 状态 |
-| --- | --- | --- |
-| Session 创建 | 初始化 | `{session_id}_round_0` |
-| 问题澄清 | pushMessage | 使用当前 round_id |
-| 抽牌解读 | pushMessage | 使用当前 round_id |
-| 解读完成 | 推送推荐问题 + 创建摘要 | 使用当前 round_id |
-| 用户新问题 | 自动开启新轮次 | `{session_id}_round_1` |
-
-
-### 多轮流程图
-
-
-```plaintext
-Session 开始
-    ↓
-┌─────────────────────────────────────┐
-│  Round N                            │
-│  ┌─────────────────────────────┐    │
-│  │ 1. CLARIFYING（问题澄清）    │    │
-│  │ 2. SPREAD_CHOOSING（牌阵选择）│   │
-│  │ 3. DRAWING_CARDS（抽牌）     │    │
-│  │ 4. READING（解读）           │    │
-│  └─────────────────────────────┘    │
-│              ↓                       │
-│  解读完成，Agent 进入 LISTENING     │
-│              ↓                       │
-│  用户发送新问题                      │
-│              ↓                       │
-│  自动开启 Round N+1                  │
-└─────────────────────────────────────┘
-    ↓
-Session 结束
-```
-
-
-## Agent 说明
-
-
-### 1. QuestionClarificationAssistant（问题澄清助手）
-
-**作用**：通过引导式对话帮助用户明确塔罗咨询问题
-
-- 与用户进行语音对话
-- 理解和澄清用户的咨询意图
-- 完成后触发牌阵选择流程
-
-### 2. SpreadChoosingAssistant（牌阵选择助手）
-
-**作用**：根据用户问题智能选择合适的塔罗牌阵
-
-- 分析用户问题的类型和需求
-- 从多种牌阵中选择最合适的牌阵
-- 通知客户端选择的牌阵类型
-
-### 3. TarotReadingAssistant（塔罗解读助手）
-
-**作用**：基于用户问题和抽取的塔罗牌提供专业解读
-
-- 接收用户问题和牌面信息
-- 生成结构化的塔罗解读
-- 支持分段发送解读内容
-
-## 工作流程
-
-
-### 抽牌流程对比
-
-
-| 步骤 | 旧流程 | 新流程 |
-| --- | --- | --- |
-| 1 | 问题澄清完成 | 问题澄清完成 |
-| 2 | AI 发送 `draw_cards_ready` | AI **立即**切换到牌阵选择 Agent |
-| 3 | 客户端展示"是/不是我的问题" | AI 发送 `spread_chosen` |
-| 4 | 用户选择"是" → 发送   | 客户端展示牌阵外化 + "开始抽牌/不是我的问题" |
-| 5 | AI 切换到牌阵选择 Agent | 用户选择"开始抽牌" → 抽牌 |
-| 6 | AI 发送 `spread_chosen` | 用户选择"不是我的问题" → 发送 `not_my_question` |
-| 7 | 客户端抽牌 → 发送 `cards_drawn` | 抽牌完成 → 发送 `cards_drawn` |
-
-
-**主要变化**：
-
-- 移除了 `draw_cards_ready` 和 `start_draw_cards` 消息
-- 问题澄清完成后立即进入牌阵选择，减少一次交互
-- "不是我的问题"的判断时机从问题澄清后移到牌阵选择后
-
-### 当前流程（新流程）
-
-
-```plaintext
-- 单轮阶段流程
-1. CLARIFYING（问题澄清）
-   ↓ AI 确认是一个有效问题
-   ↓ AI 立即切换到牌阵选择 Agent
-2. SPREAD_CHOOSING（牌阵选择，AI 自动处理）
-   ↓ AI 发送：spread_chosen + 牌阵类型
-   ↓ 客户端可展示牌阵外化消息
-3. DRAWING_CARDS（用户选择阶段）
-   - 用户选择"开始抽牌"：客户端处理抽牌
-     ↓ 客户端发送：cards_drawn + 牌面信息 + 牌阵类型
-   - 用户选择"不是我的问题"：
-     ↓ 客户端发送：not_my_question
-     ↓ 回到步骤 1
-4. READING（塔罗解读）
-   - AI 发送第一段解读
-   ↓ AI 发送：reading_paragraph_sent
-   ↓ 客户端发送：continue_reading（语音模式）
-   - AI 发送下一段解读
-   ↓ 重复直到完成
-5. 解读完成
-   ↓ Agent 状态变为 LISTENING
-   ↓ AI 发送：text_reading_completed（文本解读完成，仅文本模式）
-   ↓ AI 发送：recommended_questions（推荐问题，仅文本模式）
-   ↓ 用户发送新问题
-   ↓ 自动开启新轮次，回到步骤 1
-
-- 其他
-1. 会话创建完成
-  ↓ AI 发送：session_created
-2. Agent 状态变化
-  ↓ AI 发送：agent_state_changed
-3. 按句转录发送句子文本
-  ↓ AI 发送：sentence_text
-  ↓ 客户端发送：stream_text_output_finished（仅文本模式下文本动画播放完成）
-4. 过渡提示语
-  ↓ 客户端发送：hint_speech
-  ↓ AI 发送：hint_speech_played
-5. 推荐问题（仅文本模式）
-  ↓ AI 发送：recommended_questions
-```
-
-
-## 消息通信协议
-
-
-### AI → 客户端（接收）
-
-
-通过 `room.on("data_received")` 接收 JSON 格式消息：
-
-
-#### 1. 牌阵选择通知
-
-```json
-{
-  "type": "spread_chosen",
-  "spread_type": "three_card"
-}
-```
-
-**说明**：问题澄清完成后，AI 立即选择合适的牌阵并发送此消息。客户端收到后：
-
-1. 可展示牌阵外化消息（解释为什么选择这个牌阵）
-1. 展示两个选项："开始抽牌" 和 "不是我的问题"
-
-**牌阵类型枚举**：
-
-- `three_card` - 三牌阵/时间之流牌阵（3张牌）
-- `general_fortune` - 综合运势牌阵（3张牌）
-- `root_cause` - 追本溯源牌阵（4张牌）
-- `relation_cross` - 关系十字牌阵/大十字牌阵（5张牌）
-- `two_choose_one` - 二择一牌阵（6张牌）
-
-#### 2. 段落发送完成通知
-
-```json
-{
-  "type": "reading_paragraph_sent",
-  "paragraph_index": 1,
-  "total_paragraphs": 3,
-  "is_last": false
-}
-```
-
-**说明**：每段解读发送完成后的通知，客户端可据此展示"继续"按钮
-
-#### 3. 会话创建完成通知
-
-```json
-{
-  "type": "session_created",
-  "session_id": "str"
-}
-```
-
-**说明**：每次创建会话，由 Agent 生成 session_id 通知客户端，客户端可在此时根据当前 session_id 查询历史 session
-
-#### 4. Agent 状态变化通知
-
-```json
-{
-  "type": "agent_state_changed",
-  "state": "str", 
-  "old_state": "str",
-  "reason": "str"
-}
-```
-
-**说明**：Agent 状态变化时，枚举如下
-
-```plaintext
-class AgentState(Enum):
-    """Agent 状态枚举"""
-    IDLE = "idle"           # 空闲状态
-    THINKING = "thinking"   # 思考/生成回复中
-    SPEAKING = "speaking"   # 正在说话
-    LISTENING = "listening" # 正在聆听
-```
-
-#### 5. 按句转录发送句子文本
-
-```json
-{
-  "type": "sentence_text",
-  "text": "str", 
-  "sentence_index": 0, 
-  "total_sentences": 3, 
-  "stage": "str",         //clarification/reading
-  "message_id": "str"     //当前整段 message_id
-}
-```
-
-**说明**：自定义按句转录逻辑，需要将 LLM 生成的 message 按句拆分，顺序转录到客户端展示
-
-#### 6. 提示语发送完成通知
-
-```json
-{
-  "type": "hint_speech_played",
-  "id": "str"
-}
-```
-
-**说明**：客户端调用 tts 播放提示语，AI 播放完成后通知客户端
-
-
-#### 7. 推荐问题通知（仅文本模式）
-
-```json
-{
-  "type": "recommended_questions",
-  "questions": ["问题1", "问题2", "问题3"]
-}
-```
-
-**说明**：解读完成后，AI 推送 3-5 个推荐问题引导用户继续探索。客户端可展示为可点击的问题列表，用户点击后直接发送该问题开启新轮次。
-
-
-#### 8. 文本解读完成通知（仅文本模式）
-
-```json
-{
-  "type": "text_reading_completed",
-  "round_id": "session-abc-123_round_0"
-}
-```
-
-**说明**：文本模式下塔罗解读完成后发送，包含当前轮次的 `round_id`。客户端可据此标识本轮解读已结束，准备接收用户新问题开启下一轮。
-
-
-
-### 客户端 → AI（发送）
-
-
-通过 `room.local_participant.publish_data()` 发送 JSON 格式消息：
-
-
-#### 1. 不是想要的问题
-
-```json
-{
-  "type": "not_my_question"
-}
-```
-
-**说明**：在牌阵选择完成后（收到 `spread_chosen`），用户选择"不是我的问题"，系统会返回问题澄清阶段重新开始
-
-
-#### 2. 抽牌完成
-
-```json
-{
-  "type": "cards_drawn",
-  "spread_type": "three_card",
-  "cards": [
-    {
-      "card_name": "The Fool",
-      "reversed": false
-    },
-    {
-      "card_name": "The Magician",
-      "reversed": true
-    },
-    {
-      "card_name": "The High Priestess",
-      "reversed": false
-    }
-  ]
-}
-```
-
-**说明**：用户完成抽牌后发送，必须包含 `spread_type` 字段（与 AI 发送的 `spread_chosen` 中的值不一定一致，超时客户端会兜底 three_card 牌阵），触发 AI 开始解读
-
-
-#### 3. 继续解读
-
-```json
-{
-  "type": "continue_reading"
-}
-```
-
-**说明**：用户准备听下一段解读时发送
-
-
-#### 4. 文本动画播放完成
-
-```json
-{
-  "type": "stream_text_output_finished",
-  "message_id": "str"
-}
-```
-
-**说明**：**仅在文本模式 (TEXT) 下使用**。客户端收到 `sentence_text` 后，在文本动画播放完成时发送此消息通知 AI，AI 会继续发送下一句。语音模式 (VOICE) 下不需要发送此消息，AI 会在语音播放完成后自动继续。
-
-
-#### 5. tts 播放提示语
-
-```json
-{
-  "type": "hint_speech",
-  "text": "str", 
-  "id": "str"
-}
-```
-
-**说明**：客户端通知 AI tts 播放提示语
-
-
-
-## 会话配置 (Metadata)
-
-
-客户端可通过 LiveKit 的 participant metadata 传递会话配置给 AI：
-
-
-### Metadata 字段
-
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `interaction_mode` | string | 否 | 交互模式，`voice` 或 `text`，默认 `voice` |
-| `default_spread` | string | 否 | 默认牌阵类型，首次解读时跳过 LLM 选择直接使用 |
-
-
-### Metadata 示例
-
-
-```json
-{
-  "interaction_mode": "voice",
-  "default_spread": "relation_cross"
-}
-```
-
-
-### default_spread 说明
-
-
-- **作用**：用户在进入会话前已选择牌阵时，可通过此字段指定首次解读使用的牌阵
-- **生效范围**：仅对 Session 中的**第一次解读**生效，使用后自动清空
-- **后续轮次**：第二轮及之后的解读会通过 LLM 自动选择牌阵
-- **无效值处理**：如果传入无效的牌阵类型，会回退到 LLM 选择
-
-**牌阵类型枚举**：
-
-- `three_card` - 三牌阵/时间之流牌阵（3张牌）
-- `general_fortune` - 综合运势牌阵（3张牌）
-- `root_cause` - 追本溯源牌阵（4张牌）
-- `relation_cross` - 关系十字牌阵/大十字牌阵（5张牌）
-- `two_choose_one` - 二择一牌阵（6张牌）
-
-
-## 交互模式 (InteractionModeType)
-
-
-系统支持两种交互模式，通过 LiveKit 的 participant attributes 或 metadata 传递给 AI：
-
-
-### 模式类型
-
-
-```rpm
-class InteractionModeType(Enum):
-    VOICE = "voice"  # 语音模式
-    TEXT = "text"    # 文本模式
-```
-
-
-### 模式差异
-
-
-| 特性 | 语音模式 (VOICE) | 文本模式 (TEXT) |
-| --- | --- | --- |
-| **文本发送方式** | 按句发送 + 播放语音 | 一次性发送完整文本 |
-| **sentence_text** | 逐句发送，每句播放语音 | 一次性发送全部文本，不播放语音 |
-| **stream_text_output_finished** | ❌ 不需要（AI 根据语音播放完成自动继续） | ✅ **必须发送**（AI 等待客户端文本动画完成） |
-| **语音播放** | ✅ AI 自动播放 TTS | ❌ 不播放 |
-| **用户输入** | 🎤 语音输入 | ⌨️ 文本输入 |
-| **Agent 音频订阅** | ✅ 订阅用户麦克风 | ❌ 不订阅 |
-
-
-
-## 注意事项
-
-
-1. **可靠传输**：数据消息可使用 `reliable: true` 确保送达
-1. **状态同步**：客户端应根据接收到的消息类型维护当前状态
-1. **错误处理**：网络异常时应有重试机制或友好提示
-1. **语音交互**：系统通过 LiveKit 的 STT/TTS 自动处理语音，客户端只需处理数据消息
-1. **交互模式**：
-  - 语音模式下，客户端无需发送 `stream_text_output_finished`
-  - 文本模式下，**必须**在文本动画完成后发送 `stream_text_output_finished`
-1. **message_id 匹配**：`stream_text_output_finished` 中的 `message_id` 必须与对应的 `sentence_text` 消息一致
-1. **多轮会话**：
-  - 单个 Session 支持无限轮次解读
-  - 解读完成后 Agent 进入 `LISTENING` 状态，用户发送新问题自动开启新轮次
-  - 每轮解读独立生成摘要，历史记录按轮次分组展示
-  - 推荐问题仅在文本模式下推送
-1. **新抽牌流程**：
-  - 问题澄清完成后，AI 立即选择牌阵并发送 `spread_chosen`
-  - 客户端收到后展示牌阵外化消息和选项按钮
-  - 用户选择"开始抽牌"后完成抽牌发送 `cards_drawn`
-  - 用户选择"不是我的问题"则发送 `not_my_question` 返回问题澄清
-
-## Agent 与业务后端 (Java) 交互
-
-
-Agent 会在特定时机向 Java 业务后端推送事件，用于同步状态和触发业务逻辑。
-
-
-### 事件推送接口
-
-
-**路径**：`POST /agent/event`
-
-
-**请求参数**：
-
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `eventType` | string | 是 | 事件类型 |
-| `businessId` | string | 否 | 业务ID，通常为 `round_id` |
-| `extra` | object | 否 | 扩展数据 |
-
-
-### 事件类型
-
-
-#### 1. deep_dive_start（深度解读开始）
-
-
-**触发时机**：塔罗解读 LLM 生成完成后
-
-
-**参数**：
-
-```json
-{
-  "eventType": "deep_dive_start",
-  "businessId": "session-abc-123_round_0",
-  "extra": {}
-}
-```
-
-
-**说明**：通知业务后端开始深度解读，用于状态同步。
-
-
-#### 2. start_draw_cards（牌阵确认）
-
-
-**触发时机**：塔罗解读 LLM 生成完成后（与 `deep_dive_start` 同时发送）
-
-
-**参数**：
-
-```json
-{
-  "eventType": "start_draw_cards",
-  "businessId": "session-abc-123_round_0",
-  "extra": {
-    "spreadType": "relation_cross"
-  }
-}
-```
-
-
-**说明**：通知业务后端牌阵确认，Java 端可据此累计次数。`spreadType` 为本次解读使用的牌阵类型。
-
-
-**牌阵类型枚举**：
-
-- `three_card` - 三牌阵/时间之流牌阵
-- `general_fortune` - 综合运势牌阵
-- `root_cause` - 追本溯源牌阵
-- `relation_cross` - 关系十字牌阵/大十字牌阵
-- `two_choose_one` - 二择一牌阵
-
-
-## 完整示例
-
-
-参考官方 LiveKit 前端模板：
-
-- iOS: [agent-starter-swift](https%3A%2F%2Fgithub.com%2Flivekit-examples%2Fagent-starter-swift)
-- Flutter: [agent-starter-flutter](https%3A%2F%2Fgithub.com%2Flivekit-examples%2Fagent-starter-flutter)