# STT 丢失前半句诊断指南 ✅ 已修复

## ✅ 问题已解决

### 根本原因

STT引擎使用 `text`（已确认文本） + `stash`（缓冲区文本）两部分返回识别结果。

**旧代码问题：**
```python
# ❌ 只取 stash，丢失 text
text = response.get('stash', '')
```

**修复方案：**
```python
# ✅ 合并 text + stash
confirmed_text = response.get('text', '')
stash_text = response.get('stash', '')
full_text = confirmed_text + stash_text
```

---

## 问题现象（修复前）

**用户说：**
```
您好，您好，今天星期几啊？今天天气晴朗吗？
```

**STT识别（旧代码）：**
```
今天星期几啊？  ❌ 前半句丢失
```

**STT识别（修复后）：**
```
您好，您好，今天星期几啊？今天天气晴朗吗？  ✅ 完整
```

---

## 技术细节：STT 的 text 和 stash 机制

### 实际日志示例（第418行）

```json
{
    'event_id': 'event_NuDCx5B4dCYVpi7G5NysL',
    'type': 'conversation.item.input_audio_transcription.text',
    'content_index': 0,
    'text': '你好，你好，今天星期几啊？今天天气晴朗吗？',  ← 前面完整句子
    'stash': '今天星期几啊？'  ← 后面重复的话（当前缓冲区）
}
```

**说明：**
- 用户在 2.30秒 说完完整句子："您好，您好，今天星期几啊？今天天气晴朗吗？"
- 用户在 6.26秒 附近有停顿，然后继续说话（可能重复或纠正）
- STT引擎检测到停顿，将前面的内容放到 `text`（已确认），后面继续识别的放到 `stash`（缓冲区）

### 旧代码为什么丢失前半句

```python
# ❌ 旧代码只取 stash
def _handle_stash_text(self, response):
    text = response.get('stash', '')  # 只取 '今天星期几啊？'
    # 丢失了 text 字段中的 '你好，你好，今天星期几啊？今天天气晴朗吗？'
```

### 修复后的完整逻辑

```python
# ✅ 新代码合并 text + stash
def _handle_stash_text(self, response):
    confirmed_text = response.get('text', '')  # '你好，你好，今天星期几啊？今天天气晴朗吗？'
    stash_text = response.get('stash', '')     # '今天星期几啊？'
    full_text = confirmed_text + stash_text    # 合并完整文本
```

---

## 时间线分析（真实日志）

| 时间 | 事件 | 文本内容 |
|------|------|---------|
| 2.30秒 | 中间结果 | `stash`: "你好，你好，今天星期几啊？今天天气晴朗吗？" (21字 ✅) |
| 6.26秒 | 开始断句 | `text`: "你好" + `stash`: "，你好，今天星期" |
| 6.35秒 | 继续拆分 | `text`: "你好，你好，今天星期几啊？" + `stash`: "今天天气晴朗吗" |
| 6.41秒 | **最终拆分** | `text`: "你好，你好，今天星期几啊？今天天气晴朗吗？" + `stash`: "今天星期几啊？" |
| 7.58秒 | 录音结束 | 调用 `commit()` |
| commit后 | STT关闭 | ❌ 没有最终结果事件 |
| 超时 | **旧代码** | 只取 stash → "今天星期几啊？" (7字) ❌ **丢失前面21字！** |
| 超时 | **新代码** | 取 text + stash → "你好，你好，今天星期几啊？今天天气晴朗吗？今天星期几啊？" ✅ **完整！** |

---

## 🧪 验证修复

### 重启后端测试

```bash
cd /Users/wuzilong/work/00code/Tolan/backend
python main.py
```

### 期望的新日志格式

```
[xxx] 💬 STT识别(⏳中间): 您好，您好，今天星期几啊？今天天气晴朗吗？ (长度: 21字)
[xxx]    ├─ 已确认: 您好，您好，今天星期几啊？今天天气晴朗吗？ (21字)
[xxx]    └─ 缓冲区:  (0字)

（用户停顿后继续说话）

[xxx] 💬 STT识别(⏳中间): 您好，您好，今天星期几啊？今天天气晴朗吗？今天星期几啊？ (长度: 28字)
[xxx]    ├─ 已确认: 您好，您好，今天星期几啊？今天天气晴朗吗？ (21字)
[xxx]    └─ 缓冲区: 今天星期几啊？ (7字)
```

**现在会看到完整的识别结果！** ✅

---

## 💡 额外优化建议

如果后续发现用户重复说话导致文本冗余，可以考虑：

### 方案1：去重处理
```python
# 检测 stash 是否是 text 的子串（重复说话）
if stash_text in confirmed_text:
    full_text = confirmed_text  # 只用确认部分
else:
    full_text = confirmed_text + stash_text  # 合并
```

### 方案2：智能断句
- 检测句号、问号、感叹号
- 只在完整句子结束时更新

### 方案3：使用最终结果
- 当前主要依赖中间结果
- 可以优先等待 `transcript`（最终结果）