DroneMind/voicellmcloud/docs/CLOUD_VOICE_DIALOG_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 结果）。

兼容注：仍可与既有 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. 机端状态机（摘要）

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 结构；机端若未声明，服务端可 下发旧版 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 等。