bigwo/test2/FC_CALLBACK_FIX.md

# FC 回调知识库语音播放修复方案

## 问题描述

用户通过语音通话提问 → LLM 触发 `search_knowledge` 工具 → FC 回调执行知识库查询 → **结果无法通过 S2S 语音播放给用户**。

---

## 根因分析

### 根因 1：ExternalTextToSpeech 200 字符限制

**官方文档明确规定**（[自定义语音播放](https://www.volcengine.com/docs/6348/1449206)）：

> Message: 要播报的文本内容，**长度不超过 200 个字符**。

知识库返回内容通常 500~2000 字符，远超此限制，导致 API **静默拒绝或截断**。

### 根因 2：Command:"function" 在混合模式下不可靠

在 S2S+LLM 混合模式（`OutputMode=1`）下：
- `Command:"function"` 将工具结果返回给 LLM 处理
- 但 LLM 润色后的回复**可能不通过 S2S 管道播放**
- LLM 认为工具未返回结果，触发**无限重试**（日志中同一问题出现 3 个不同 `call_id`）

### 根因 3：TaskId 不匹配

- FC 回调中的 `TaskID` 是 RTC 内部 UUID（如 `f6c8cddf-...`）
- `StartVoiceChat` 的 `TaskId` 是自定义格式（如 `task_xxx_timestamp`）
- 导致 `UpdateVoiceChat` 命令发送到错误的 Task

### 根因 4：延迟瓶颈

原始串行流程耗时约 18 秒：
```
1s chunk收集 → 0.5s interrupt → 0.5s 安抚语 → 15s KB查询 → 1s TTS = ~18s
```

---

## 修复方案

### 修复 1：分段 TTS 播放（解决 200 字符限制）

**文件**: `server/routes/voice.js`

将 KB 结果按自然断句拆分为 ≤200 字符的段落，逐段通过 `ExternalTextToSpeech` 播放：

```javascript
// 分段函数：在句号、问号、感叹号等自然断点处拆分
const MAX_TTS_LEN = 200;   // 官方限制
const MAX_TOTAL_LEN = 800; // 总内容上限，避免播放过久

const splitForTTS = (text, maxLen) => {
  const segments = [];
  let remaining = text;
  while (remaining.length > 0) {
    if (remaining.length <= maxLen) { segments.push(remaining); break; }
    let cutAt = -1;
    const breakChars = ['。', '！', '？', '；', '\n', '，', '、'];
    for (const ch of breakChars) {
      const idx = remaining.lastIndexOf(ch, maxLen - 1);
      if (idx > cutAt) cutAt = idx;
    }
    if (cutAt <= 0) cutAt = maxLen;
    else cutAt += 1;
    segments.push(remaining.substring(0, cutAt));
    remaining = remaining.substring(cutAt).trim();
  }
  return segments.filter(s => s.length > 0);
};
```

播放策略：
- **第一段** `InterruptMode: 1`（高优先级，打断安抚语）
- **后续段** `InterruptMode: 2`（中优先级，排队播放）

### 修复 2：Command:function 异步通知 LLM（解决无限重试）

在 `ExternalTextToSpeech` 播放后，**异步**发送 `Command:"function"` 让 LLM 知道工具已返回结果，停止重试：

```javascript
if (b.id) {
  volcengine.updateVoiceChat({
    Command: 'function',
    Message: JSON.stringify({ ToolCallID: b.id, Content: contentText.substring(0, 2000) }),
  }).catch(e => console.warn('Command:function failed (non-critical):', e.message));
}
```

### 修复 3：30 秒 Cooldown 防重试（解决 LLM 无限重试）

**文件**: `server/routes/voice.js`

在工具结果发送后，设置 30 秒 cooldown，期间忽略相同 TaskId 的重复调用：

```javascript
const cooldownMs = existing.resultSentAt ? 30000 : 15000;
const elapsed = existing.resultSentAt
  ? (Date.now() - existing.resultSentAt)
  : (Date.now() - existing.createdAt);
if (elapsed < cooldownMs) {
  console.log(`Cooldown active, ignoring retry`);
  return;
}
```

### 修复 4：TaskId 解析优先级（解决 TaskId 不匹配）

使用三级回退策略解析正确的 TaskId：

```javascript
const s2sTaskId = roomToTaskId.get(b.RoomID) || b.S2STaskID || effectiveTaskId;
```

- **优先**：`roomToTaskId`（从 StartVoiceChat 响应中捕获的服务端 TaskId）
- **其次**：回调中的 `S2STaskID`
- **兜底**：回调中的原始 `TaskID`

### 修复 5：延迟优化（减少 ~1.5 秒等待）

**文件**: `server/routes/voice.js`

| 优化项 | 修改前 | 修改后 | 节省 |
|--------|--------|--------|------|
| chunk 收集超时 | 1000ms | 500ms | 500ms |
| interrupt 命令 | 单独发送 ~500ms | 移除（InterruptMode:1 已含打断） | 500ms |
| 安抚语 vs KB 查询 | 串行等待 | `Promise.all` 并行 | ~500ms |

优化后流程：
```
0.5s chunk收集 → [安抚语 + KB查询 并行] → 1s TTS分段 = ~16.5s
```

```javascript
// 并行执行：安抚语 + KB 查询同时进行
const waitingPromptPromise = volcengine.updateVoiceChat({
  Command: 'ExternalTextToSpeech',
  Message: '正在查询知识库，请稍候。',
  InterruptMode: 1,
}).catch(err => console.warn('Waiting prompt failed:', err.message));

const kbQueryPromise = ToolExecutor.execute(toolName, parsedArgs);

const [, kbResult] = await Promise.all([waitingPromptPromise, kbQueryPromise]);
```

### 修复 6：Ark KB 超时缩短

**文件**: `server/services/toolExecutor.js`

```javascript
timeout: 15000, // 从 30s 减到 15s，减少等待
```

---

## 修改文件清单

| 文件 | 修改内容 |
|------|---------|
| `server/routes/voice.js` | FC 回调处理：分段 TTS、并行执行、cooldown、TaskId 解析 |
| `server/services/toolExecutor.js` | Ark KB 超时从 30s 减到 15s |
| `server/.env` | FC_SERVER_URL 更新为部署域名 |

---

## 关键参考文档

- [自定义语音播放（ExternalTextToSpeech）](https://www.volcengine.com/docs/6348/1449206) — **200 字符限制**
- [Function Calling](https://www.volcengine.com/docs/6348/1554654) — FC 回调机制
- [接入知识库 RAG](https://www.volcengine.com/docs/6348/1557771) — 官方推荐 Coze/MCP 方式
- [UpdateVoiceChat API](https://www.volcengine.com/docs/6348/2011497) — Command 参数说明

---

## 后续优化方向

如果当前方案的 15s KB 查询延迟仍然不可接受，可考虑：

1. **迁移到 Coze Bot 内置知识库**：`LLMConfig.Mode="CozeBot"`，知识库查询由 Coze 内部完成，减少网络往返
2. **接入 MCP Server**：通过 Viking 知识库 MCP 直接集成
3. **本地知识库缓存**：对高频问题预加载结果，命中缓存时延迟 <1s