DroneMind/voice_drone_assistant/docs/CLOUD_VOICE_FLIGHT_CONFIRM_v1.md

云端语音 · 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 建议确认窗内 可多句 直至超时，由机端实现决定）。
5. 超时 / 取消 固定中文播报见下表（机端本地 TTS，降低时延）：

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

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

---

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

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

---

7. 机端状态机（摘要）

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 须 带：

{
  "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）。