# 云端语音 · `dialog_result` 与飞控二次确认（v1）

供 **云端服务** 与 **机端 voice_drone_assistant** 同步实现。**尚无线上存量**：本文即 **`dialog_result` 的飞机位约定**，服务端可按 v1 直接改结构，无需迁就旧字段。

---

## 1. 目标

1. **`routing=chitchat`**：只走闲聊与对应 TTS，**不**下发可执行飞控负载。  
2. **`routing=flight_intent`**：携 **`flight_intent`（v1）** + **`confirm`**；机端是否立刻执行仅由 **`confirm.required`** 决定，并支持 **确认 / 取消 / 超时** 交互。  
3. **ASR**：飞控句是否改用云端识别见 **附录 A**；与 `confirm` 独立。

---

## 2. 术语

| 术语 | 含义 |
|------|------|
| **首轮** | 用户说一句；本轮 WS 收到 `dialog_result` 为止。 |
| **确认窗** | `confirm.required=true` 时，机端播完本轮 PCM 后 **仅收口令** 的时段，时长 **`confirm.timeout_sec`**。 |
| **`flight_intent`** | 见 `FLIGHT_INTENT_SCHEMA_v1.md`。 |

---

## 3. `dialog_result` 形状（云端 → 机端）

### 3.1 公共顶层（每轮必带）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `turn_id` | string | 是 | 与现有一致，关联本 turn。 |
| **`protocol`** | string | 是 | 固定 **`cloud_voice_dialog_v1`**，便于机端强校验、排障。 |
| `routing` | string | 是 | **`chitchat`** \| **`flight_intent`** |
| `user_input` | string | 建议 | 本回合用于生成回复的用户文本（可为云端 STT 结果）。 |

### 3.2 `routing=chitchat`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `chat_reply` | string | 是 | 闲聊文本（与 TTS 语义一致或由服务端定义）。 |
| `flight_intent` | — | **禁止** | 不得出现。 |
| `confirm` | — | **禁止** | 不得出现。 |

### 3.3 `routing=flight_intent`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `flight_intent` | object | 是 | v1：`is_flight_intent`、`version`、`actions`、`summary` 等。 |
| **`confirm`** | object | 是 | 见 §3.4；**每轮飞控必带**，机端拒收缺字段报文。 |

### 3.4 `confirm` 对象（`routing=flight_intent` 时必填）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| **`required`** | bool | 是 | `true`：进入确认窗，**首轮禁止**执行飞控；`false`：首轮允许按机端执行开关立即执行（调试/免确认策略）。 |
| **`timeout_sec`** | number | 是 | 确认窗秒数；建议默认 **10**。 |
| **`confirm_phrases`** | string[] | 是 | 非空；与口播一致，推荐 **`["确认"]`**。 |
| **`cancel_phrases`** | string[] | 是 | 非空；推荐 **`["取消"]`**。 |
| **`pending_id`** | string | 是 | 本轮待定意图 ID（建议 UUID）；日志、可选第二轮遥测（附录 B）。 |
| **`summary_for_user`** | string | 建议 | 与口播语义一致，供日志/本地 TTS 兜底；**最终以本轮 PCM 为准**。 |

---

## 4. 播报（理解与提示）

- **TTS**：仍用 **`tts_audio_chunk` + PCM**；内容示例：复述理解 + **「请回复确认或取消」**；服务端在 `confirm_*_phrases` 中与口播保持一致（推荐 **`确认` / `取消`**）。  
- 机端 **须** 在 **本轮 PCM 播放结束**（或播放管线给出「可收听下一句」）后再进入确认窗，避免抢话。

---

## 5. 机端短语匹配（确认窗内）

对用户 **一句** STT 规范化后，与 `confirm_phrases` / `cancel_phrases` 比对（机端实现见 `match_phrase_list`）：

1. **取消优先**：若命中 `cancel_phrases` 任一 → 取消本轮。  
2. **确认**：否则若命中 `confirm_phrases` 任一 → 执行 **`flight_intent`**。  
3. **规则要点**：**全等**（去尾标点）算命中；或对 **很短** 的句子（长度 ≤ 短语长+2）允许 **子串** 命中，以便「好的确认」类说法；**整句复述**云端长提示（如「请回复确认或取消」）不会因同时含「确认」「取消」子串而误匹配。  
4. **未命中**：可静候超时（v1 建议确认窗内 **可多句** 直至超时，由机端实现决定）。  
4. **超时 / 取消** 固定中文播报见下表（机端本地 TTS，降低时延）：

| 事件 | 文案 |
|------|------|
| 超时 | `未收到确认指令，请重新下发指令` |
| 取消 | `已取消指令，请重新唤醒后下发指令` |
| 确认并执行 | `开始执行飞控指令` |

若产品强制云端音色，见 **附录 C**。

---

## 6. 机端执行条件（归纳）

| 条件 | 行为 |
|------|------|
| `routing=chitchat` | 不执行飞控。 |
| `routing=flight_intent` 且 `confirm.required=false` 且机端已开执行开关 | 首轮校验通过后 **可立即** 执行。 |
| `routing=flight_intent` 且 `confirm.required=true` | **仅**在确认窗内命中确认短语后执行；**首轮绝不**执行。 |

---

## 7. 机端状态机（摘要）

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Chitchat: routing=chitchat
  Idle --> ExecNow: routing=flight_intent 且 confirm.required=false
  Idle --> ConfirmWin: routing=flight_intent 且 confirm.required=true

  ConfirmWin --> ExecIntent: 命中 confirm_phrases
  ConfirmWin --> SayCancel: 命中 cancel_phrases
  ConfirmWin --> SayTimeout: timeout_sec

  ExecNow --> Idle
  ExecIntent --> Idle
  SayCancel --> Idle
  SayTimeout --> Idle
  Chitchat --> Idle
```

---

## 8. 会话握手

**`session.start`**（或等价）的 `client` **须** 带：

```json
{
  "protocol": {
    "dialog_result": "cloud_voice_dialog_v1"
  }
}
```

服务端仅对声明该协议的客户端下发 §3 结构；机端若未声明，服务端可拒绝或返显式错误码（由服务端定义）。

---

## 9. 安全说明

二次确认减轻 **错词误飞**，不替代 **急停、遥控介入、场地规范**。  
TTS 若为「请回复确认或取消」，服务端请在 `confirm_phrases` / `cancel_phrases` 中下发 **`确认`**、**`取消`**（与口播一致）；**听与判均在机端**，云端无需再收一轮确认消息。

---

## 附录 A：云端 ASR（可选）

服务端可将飞控相关 utterance 改为 **云端 STT** 结果填入 `user_input`，与 `flight_intent` 解析同源；**执行仍以 `flight_intent` + `confirm` 为准**。

---

## 附录 B：第二轮 `turn`（可选遥测）

用户确认后机端可再发一轮文本（ASR 原文），payload 可带 `pending_id`、`phase: confirm_ack`；**执行成功与否不依赖**该轮响应。

---

## 附录 C：超时/取消走云端 TTS（可选）

若 `confirm.play_server_tts_on_timeout` 为真（服务端与机端扩展字段），则由云端推 PCM；**易增延迟**，v1 默认 **关**，以 §5 本地播报为准。

---

## 文档关系

| 文档 | 关系 |
|------|------|
| `FLIGHT_INTENT_SCHEMA_v1.md` | `flight_intent` 体 |
| `DEPLOYMENT_AND_OPERATIONS.md` | 部署 |

**版本**：`cloud_voice_dialog_v1`（本文）；后续 breaking 变更递增 `cloud_voice_dialog_v2` 等。

---

## 机端实现状态（voice_drone_assistant）

- **`CloudVoiceClient`**：`session.start.client` 已带 `protocol.dialog_result: cloud_voice_dialog_v1`；`run_turn` 返回含 `protocol`、`confirm`。  
- **`main_app.TakeoffPrintRecognizer`**：解析 `confirm`；`required=true` 且已开 `ROCKET_CLOUD_EXECUTE_FLIGHT` 时，播完本轮 PCM 后进入 **`FLIGHT_CONFIRM_LISTEN`**，本地匹配短语 / 超时文案见 **`voice_drone.core.cloud_dialog_v1`**。  
- **服务端未升级前**：若缺 `protocol` 或 `confirm`，机端 **不执行** 飞控（仍播 TTS）。