docs/friend/data-flow.md

# Friend 数据流

本文档详细描述 Friend 系统中的四种核心数据流，以及 SSE 事件格式规范。

---

## 1. 文字对话流

用户在前端输入框输入文字，按下 Enter 发送。

```
用户输入文字
    │
    ▼
ChatInput.tsx  ── POST /plugins/friend/chat ──────────────────┐
    │                              { message: "你好" }         │
    │                                                          │
    ▼                                                          │
handleFriendApi()  ── friendService.start()                    │
    │                 friendService.sendText(message)           │
    ▼                                                          │
FriendService.sendText()                                       │
    │                                                          │
    ├── 通知 inboundListeners (bridge hook turn tracking)      │
    │                                                          │
    └── messageQueueManager.enqueue()                          │
        │  { mode: 'prompt', skipSlashCommands: true,          │
        │    bridgeOrigin: true, origin: { server: 'friend' }} │
        │                                                      │
        ▼                                                      │
    AI Provider (Anthropic/NVIDIA/OpenAI)                      │
        │                                                      │
        ├── 处理消息                                           │
        ├── 可调用 friend_emotion 工具设置表情                  │
        ├── 可调用 friend_screen_observe 观察屏幕               │
        │                                                      │
        ▼                                                      │
    AI 回复流回 (通过 useFriendBridge / REPL)                   │
        │                                                      │
        ▼                                                      │
    FriendService.broadcastResponse(text)                      │
        │                                                      │
        ├── broadcastToVrm({ text })                           │
        │       │                                              │
        │       ▼ SSE data                                     │
        │   TextBubble 收到                                     │
        │       │                                              │
        │       ├── 重置气泡，显示文字                          │
        │       ├── 启动打字机效果 (逐字符显示)                 │
        │       │   - CJK: 200ms/char (TTS开启) / 80ms (关闭)  │
        │       │   - English: 60ms/char (TTS开启) / 30ms (关闭)│
        │       ├── 打字机完成后渲染 Markdown                    │
        │       └── 1秒后触发 onMessage → VRMScene 表情动作    │
        │                                                      │
        ├── if TTS enabled:                                    │
        │   ├── generateTts(text)                              │
        │   │   ├── stripForTts() 清洗文本                     │
        │   │   └── EdgeTTS 或 QwenTTS 生成 MP3                │
        │   │                                                 │
        │   ├── broadcastToVrm({ audioUrl, sendFirstTts })     │
        │   │       │                                           │
        │   │       ▼ SSE data                                 │
        │   │   TextBubble 开始音频队列播放                     │
        │   │       │                                           │
        │   │       └── LipSync.playAudio(url)                 │
        │   │           ├── fetch 音频文件                      │
        │   │           ├── decodeAudioData                     │
        │   │           ├── 连接到 lipSyncNode (分析) + gainNode (扬声器) │
        │   │           └── 播放时实时更新 VRM 嘴形             │
        │   │                                                 │
        │   └── extendMuteForTts(audioId)                      │
        │       └── 精确计算 MP3 时长，更新静音定时器           │
        │                                                      │
        └── broadcastToVrm({ replyDone: true })                │
                │                                               │
                ▼ SSE data                                     │
            TextBubble 调度气泡隐藏 (2s 延迟)                  │
                或等待后续 appendText 消息                      │
```

---

## 2. 语音捕获流 (F2 通话模式)

用户按下 F2 进入连续语音通话模式，再次按下 F2 结束通话。

### 2.1 启动通话

```
用户按 F2
    │
    ▼
ChatInput.startVoiceCall()
    │
    ├── setVoiceCallActive(true)
    │
    └── useServerStt.startStreaming()
        │
        └── POST /plugins/friend/voice/start
            │
            ▼
        handleFriendApi()
            │
            └── friendService.startVoiceCapture()
                │
                ├── 检测 STT provider (Groq→Whisper→Anthropic→Doubao)
                │
                ├── startSttConnection() (8s 超时)
                │   ├── Groq: connectGroqStream()
                │   ├── Local: connectLocalWhisperStream()
                │   ├── Anthropic: connectVoiceStream()
                │   └── Doubao: connectDoubaoStream()
                │
                ├── loadAudioCapture()
                │   ├── 尝试 arecord (ALSA)
                │   │   args: -D default -r 16000 -f S16_LE -c 1 -t raw -q
                │   ├── 失败则尝试 parecord (PulseAudio)
                │   │   args: --raw --rate=16000 --format=s16le --channels=1
                │   └── 500ms 验证窗口: 确认子进程输出音频数据
                │
                ├── arecord 数据回调:
                │   ├── if not muted → 转发到 STT connection.send(chunk)
                │   └── if not muted → 转发到 VAD processAudio(float32)
                │
                └── vadInstance.start()
```

### 2.2 语音检测与转录

```
麦克风音频流 (16kHz S16LE)
    │
    ├──► STT Connection.send(chunk)  (实时流式转录)
    │
    └──► SileroVad.processAudio(float32)
            │
            ├── RMS 预过滤 (阈值 0.004)
            │   ├── < 阈值 → 概率 = 0 (跳过推理)
            │   └── >= 阈值 → ONNX 推理
            │
            ├── 状态机
            │   ├── pre-speech: 需要连续 10 帧 (~320ms) 确认说话
            │   ├── speaking: 语音持续中
            │   └── silence redemption: 连续 20 帧 (~640ms) 静音触发 endSpeech
            │
            └── onSpeechEnd callback
                │
                ▼
            FriendService._flushVadSegment()
                │
                ├── 创建新的 STT 连接 (旧的连接继续处理)
                │
                ├── 等待旧连接 finalize()
                │   └── 获取转录文本推入 captureTranscripts
                │
                ├── if 有转录文本:
                │   ├── this.sendText(transcript)
                │   │       │
                │   │       ▼
                │   │   messageQueueManager.enqueue() → AI 开始处理
                │   │
                │   └── this.startAiTurnMute()
                │       ├── muted = true
                │       ├── VAD pause
                │       └── 30s 超时安全性定时器
                │
                └── 循环继续监听下一段语音
```

### 2.3 AI 回复与静音解除

```
AI 处理完成
    │
    ▼
FriendService.broadcastResponse(text)
    │
    ├── broadcastToVrm({ text })          // 显示文字
    │
    ├── if TTS enabled:
    │   ├── generateTts(text)
    │   │       │
    │   │       ▼
    │   ├── broadcastToVrm({ audioUrl, sendFirstTts: true })
    │   │
    │   └── extendMuteForTts(audioId)
    │       ├── getMp3DurationMs() 精确计算
    │       ├── 取消 30s 安全性定时器
    │       └── 设定精确的播放时长定时器
    │
    └── broadcastToVrm({ replyDone: true })
        │
        ▼
    播放完成后 → unmute()
        ├── muted = false
        └── VAD resume (可继续接收语音)
```

### 2.4 结束通话

```
用户按 F2 (再次)
    │
    ▼
ChatInput.endVoiceCall()
    │
    └── useServerStt.stopStreaming()
        │
        └── POST /plugins/friend/voice/stop
            │
            ▼
        friendService.stopVoiceCapture()
            │
            ├── arecord.kill('SIGTERM') → 2s 后 SIGKILL
            ├── capturing = false
            ├── clearMute()
            ├── VAD reset()
            ├── STT connection.finalize() + close()
            ├── 发送剩余转录文本
            └── 返回完整转录
```

---

## 3. 情绪表情流

LLM 调用 `friend_emotion` 工具触发情绪更新。

```
LLM 处理完成，调用 friend_emotion 工具
    │
    ▼
FriendEmotionTool.call({ emotion: 'happy', intensity: 0.8, mood_delta: 2 })
    │
    ├── broadcastToVrm({ emotion: 'happy', emotionIntensity: 0.8 })
    │       │
    │       ▼ SSE data
    │   App.tsx handleVrmMessage
    │       │
    │       ├── emotionActionMap['happy'] = 'happy'
    │       │
    │       ├── sceneRef.current.setEmotionWithReset('happy', 5000, 0.8)
    │       │       │
    │       │       ▼
    │       │   VRMScene.setEmotionWithReset (via forwardRef)
    │       │       │
    │       │       └── EmoteController.setEmotionWithReset('happy', 5000, 0.8)
    │       │           ├── setEmotion('happy', 0.8)
    │       │           │   ├── 获取 happy 的 blend shapes: [{name:'happy', val:0.2}, {name:'aa', val:0.8}]
    │       │           │   ├── 应用 intensity: aa = 0.8*0.8 = 0.64, happy = 0.2*0.8 = 0.16
    │       │           │   ├── isTransitioning = true
    │       │           │   └── 记录目标 blendshape 值
    │       │           │
    │       │           └── setTimeout(5000ms → setEmotion('neutral'))
    │       │
    │       └── sceneRef.current.playAction('happy')
    │               │
    │               ▼
    │           MotionController.playAction('happy')
    │               ├── loadClip('happy.fbx')
    │               ├── crossFadeTo(clip, 0.3s)
    │               ├── LoopOnce + clampWhenFinished
    │               └── 完成后 crossFade 回 idle 动画
    │
    ├── 处理 mood_delta
    │   ├── 读取当前 moodIndex = 60
    │   ├── newMood = clamp(60 + 2, 0, 100) = 62
    │   ├── 持久化到 prefs
    │   └── broadcastToVrm({ moodDelta: 2, moodIndex: 62 })
    │           │
    │           ▼ SSE data
    │       MoodIndicator 收到
    │           ├── 显示心情数值变化气泡 (+2)
    │           ├── Canvas 动画: displayPercent 从 60 → 62 渐变
    │           └── 5s 后自动隐藏
    │
    └── 返回 tool result
```

### 每帧更新循环 (VRMScene animate)

```
requestAnimationFrame 循环 (约 60fps)
    │
    ├── 1. MotionController.update(delta)
    │   └── AnimationMixer.update(delta)
    │
    ├── 2. 应用 Relaxed Hand Pose (非舞蹈状态)
    │   └── 手指自然弯曲 + 微妙颤动
    │
    ├── 3. Humanoid.update()
    │
    ├── 4. 眼球追踪 (camera 模式)
    │   └── lookAtTarget = camera.position
    │
    ├── 5. LookAt.update(delta)
    │
    ├── 6. Eye Saccades Controller.update()
    │   └── 每隔 400-1200ms 添加随机眼球微动偏移
    │
    ├── 7. Blink State Machine.update()
    │   └── 随机眨眼 (间隔 1-6s, 时长 150ms, sin 曲线)
    │
    ├── 8. EmoteController.update(delta)
    │   └── cubic ease 过渡到目标 blendshape 值
    │
    ├── 9. LipSync.update(vrm, delta)
    │   ├── 读取 wlipsync 音频分析节点的音素权重
    │   ├── 选择胜者/亚军音素
    │   ├── Attack/Release 平滑 (50/30)
    │   └── 设置 VRM 嘴形 blendshapes (aa, ee, ih, oh, ou)
    │
    ├── 10. ExpressionManager.update()
    │
    └── 11. SpringBoneManager.update(delta)
        └── 物理头发/衣服/饰品模拟
```

---

## 4. SSE 事件格式

所有前端 SSE 事件通过 `GET /plugins/friend/events` 接收，格式为标准 SSE (`data: {json}\n\n`)。

### 4.1 VrmBroadcastPayload 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` | string | 否 | AI 回复文字，TextBubble 显示并启动打字机效果 |
| `emotion` | string | 否 | VRM 表情名，触发 EmoteController 切换 blend shapes |
| `emotionIntensity` | number | 否 | 表情强度 0-1，默认 1 |
| `audioUrl` | string | 否 | TTS 音频 URL，TextBubble 触发 LipSync 播放 |
| `audioIndex` | number | 否 | 音频播放顺序索引，用于多句排序 |
| `clearText` | boolean | 否 | 清空气泡文字和音频队列 |
| `imageUrl` | string | 否 | 图片 URL，在气泡中显示 |
| `moodDelta` | number | 否 | 心情变化量，MoodIndicator 显示浮动气泡 |
| `moodIndex` | number | 否 | 当前心情指数 0-100，MoodIndicator Canvas 更新 |
| `sendFirstTts` | boolean | 否 | 开始 TTS 播放的信号，重置音频队列 |
| `appendText` | boolean | 否 | 追加文字模式，后续句子的文字和音频配对 |
| `replyDone` | boolean | 否 | 回复完成信号，TextBubble 调度气泡隐藏 |

### 4.2 典型回复序列

```
1. { text: "你好！今天心情不错啊！", replyDone: true }
    → 显示文字，打字机效果，1s 后触发表情

2. { text: "一起玩吧！" }
   { audioUrl: "http://127.0.0.1:3456/plugins/friend/audio/123-1", sendFirstTts: true }
   { replyDone: true }
    → 显示文字 + 播放 TTS + 语音结束后隐藏气泡

3. { text: "今天天气真好。" }
   { audioUrl: "...", sendFirstTts: true, emotion: "happy", emotionIntensity: 0.8 }
   { appendText: true, text: "要不要出去走走？", audioUrl: "...", audioIndex: 1 }
   { appendText: true, text: "我知道一个好地方。", audioUrl: "...", audioIndex: 2 }
   { replyDone: true }
    → 多句子回复，每句独立音频，按索引顺序播放
    → 第一句发送时触发 happy 表情

4. { emotion: "think", emotionIntensity: 0.7 }
    → 思考阶段的表情更新（LLM 处理中）

5. { clearText: true }
    → 清空气泡（新会话）

6. { moodDelta: 3, moodIndex: 63 }
    → 心情更新，显示 +3 浮动气泡，Canvas 液态填充变化
```