# 云端语音 · `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 结果）。 |

> **兼容注**：仍可与既有 `proto_version`、`transport_profile`、`type` 等并列下发；机端若以本文强校验，至少校验 `protocol` 与 §3.2 / §3.3 字段约束。

### 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**。本仓库默认口播模板为：**「我将执行：{summary}。请回复确认或取消。」**（与 `confirm_phrases`/`cancel_phrases` 默认 `确认`/`取消` 对齐）；如需 LLM 重写口播，须保持与短语表一致。  
- 机端 **须** 在 **本轮 PCM 播放结束**（或播放管线给出「可收听下一句」）后再进入确认窗，避免抢话。

---

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

对用户 **一句** STT 结果规范化（去首尾空白等）后：

1. **取消**：若命中 `cancel_phrases` 任一（**推荐子串包含**），则 **取消优先**。  
2. **确认**：否则若命中 `confirm_phrases` 任一 → 执行 **`flight_intent`**（校验 + ROS/Socket，与现机端一致）。  
3. **未命中**：可继续听到超时，或 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 结构；机端若未声明，服务端可 **下发旧版 `dialog_result`**（无 `protocol`、嵌套 `user_input`、无 `confirm`）或返显式错误码（由部署策略决定）。本仓库默认：**已声明** → §3；**未声明** → 兼容旧形状。

---

## 9. 安全说明

二次确认减轻 **错词误飞**，不替代 **急停、遥控介入、场地规范**。

---

## 附录 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` 体 |
| `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md` | WS 总协议 |
| `PROJECT_SUMMARY_AND_DEPLOYMENT.md` | 部署 |

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