# Instruct 动态场景检测功能说明

> 更新时间：2026-06-14

---

## 概述

TTS 音频生成时，根据文本内容自动匹配最佳 Instruct 指令（场景/角色/身份/情感），使 CosyVoice 合成的语音更贴合内容语境。

---

## 分析策略（折中方案）

```
全文文本
  │
  ├─ 🥇 LLM 全文分析（一次调用，<4s超时）
  │     └─ 成功 → 用 LLM 结果生成每段 Instruct
  │
  └─ 🥈 关键词匹配降级（LLM超时/失败时）
        └─ 逐段关键词检测 → 生成每段 Instruct
```

### 对比

| | LLM 分析 | 关键词降级 |
|---|---|---|
| 调用次数 | 1次（全文本） | N次（逐段） |
| 延迟 | ~500ms | ~0ms |
| 成本 | ~¥0.001 | ¥0 |
| 否定词识别 | ✅ | ❌ |
| 语义理解 | ✅ | ❌ |
| 适用场景 | 主力 | 兜底 |



> 版本：2026-06-14 | 关联提交：`df6b3381`

## 功能概述

利用 CosyVoice 官方 Instruct 指令的 4 层能力（身份 / 角色 / 场景 / 情感），根据文本内容**动态匹配最佳指令**，替代之前"音色硬编码单一场景"的粗放模式。

## 4 层 Instruct 能力（优先级从高到低）

| 层级 | 格式 | 示例 | 适用内容 |
|------|------|------|----------|
| 身份 | `你正在以一个{身份}的身份说话，你说话的情感是{情感}。` | 故事机 | 童话、儿童故事 |
| 角色 | `你现在说话的角色是{角色}，你说话的情感是{情感}。` | 一个旁白 | 小说、叙事类 |
| 场景 | `你正在进行{场景}，你说话的情感是{情感}。` | 新闻播报 | 新闻、广告、解说等 |
| 仅情感 | `你说话的情感是{情感}。` | happy | 任意无场景匹配的文本 |

## 7 个官方场景 + 关键词特征

| 场景 | 触发关键词示例 |
|------|---------------|
| **新闻播报** | 据报道、记者从、新华社、数据显示、今日头条 |
| **广告促销** | 限时、特价、优惠、折扣、立即购买、扫码 |
| **比赛解说** | 比赛、进球、得分、冠军、绝杀、裁判 |
| **一些儿童内容解说** | 小朋友、小熊、童话、魔法、幼儿园 |
| **语音导航** | 前方、左转、路况、出口、公里 |
| **脱口秀表演** | 哈哈、段子、吐槽、笑死、你知道吗 |
| **闲聊互动** | 你好、今天、觉得、怎么样（默认兜底） |

## 角色 / 身份检测

### "一个旁白"（角色）
- 触发条件：文本含 "第一章"、"很久很久以前"、"从前"等叙事标记
- 效果：旁白朗讀模式，提升叙事感的自然度

### "故事机"（身份）
- 触发条件：文本含 "童话"、"小熊"、"魔法"、"小朋友"等儿童内容关键词
- **优先级高于角色**：检测到身份时不使用角色

## 逐段独立 Instruct

生成音频时，每段文本（≤1000字）**独立分析**，动态生成不同的 Instruct：
- 第1段是新闻 → "你正在进行新闻播报"
- 第2段是比赛 → "你正在进行比赛解说"
- 第3段是故事 → "你正在以一个故事机的身份说话"

## 前端展示

生成页面（`/pages/create/index`）"内容分析"卡片显示：
- 🎭 **情感**：检测到的情绪（😊快乐、😢悲伤…）
- 🎤 **推荐音色**：匹配的音色名称
- 🏷️ **场景**：匹配的场景类型（如"新闻播报"）
- 👤 **身份**：如检测到儿童内容则显示"故事机"
- 🎭 **角色**：如检测到叙事文本则显示"一个旁白"

## API 接口

### `POST /api/tts/detect-emotion`

响应新增字段：
```json
{
  "data": {
    "emotion": "happy",
    "scene": "一些儿童内容解说",
    "role": null,
    "identity": "故事机"
  }
}
```

## 核心代码文件

| 文件 | 改动 |
|------|------|
| `server/src/modules/tts/tts.service.ts` | `detectScene()`、`detectContentType()`、`generateSegmentInstruct()` |
| `server/src/modules/tts/tts.controller.ts` | detect-emotion 返回 scene/role/identity |
| `my-uniapp-vue3/src/pages/create/index.vue` | 前端展示场景/身份/角色信息 |

## 测试结果（2026-06-14）

| 测试内容 | 后端 detect-emotion | 逐段 Instruct | 前端显示 |
|----------|---------------------|---------------|----------|
| 故事类 | ✅ scene=儿童内容解说 identity=故事机 | ✅ 故事机身份 | ✅ 场景+身份正确 |
| 新闻类 | ✅ scene=新闻播报 | N/A(单段) | ✅ 场景正确 |
| 比赛类 | ✅ scene=比赛解说 | ✅ 比赛解说 | ✅ 场景正确 |
| 广告类 | ✅ scene=广告促销 | N/A | N/A |
| 脱口秀 | ✅ scene=脱口秀表演 | N/A | N/A |
| 导航类 | ✅ scene=语音导航 | N/A | N/A |
| 闲聊类 | ✅ scene=闲聊互动(兜底) | N/A | N/A |