DroneMind/voicellmcloud/Client/voice_drone_assistant/docs/PROJECT_GUIDE.md

voice_drone_assistant — 项目说明与配置指南

面向部署与二次开发：目录结构、配置文件用法、启动与日常操作、与云端/飞控的关系。外场统一部署与双终端启动顺序见 docs/DEPLOYMENT_AND_OPERATIONS.md；协议细节以 docs/llmcon.md 为准。

---

1. 项目做什么

• 麦克风 → 预处理（降噪/AGC）→ VAD 切段 → SenseVoice STT → 唤醒词
• 关键词起飞（offboard 演示，默认关闭）：system.yaml → assistant.local_keyword_takeoff_enabled 或 ROCKET_LOCAL_KEYWORD_TAKEOFF=1 开启后，keywords.yaml 里 takeoff 词表（如「起飞演示」）→ 提示音 + offboard 脚本；飞控主路径推荐 云端 flight_intent + ROS 伴飞桥
• 其它语音：本地 Qwen + Kokoro，或 云端 WebSocket（LLM + TTS 上云，见 cloud_voice）
• 可选通过 TCP Socket 下发结构化飞控命令（VoiceCommandRecognizer 路径；TakeoffPrintRecognizer 默认不在启动时连 Socket，飞控多为云端 JSON + 可选 ROCKET_CLOUD_EXECUTE_FLIGHT）

---

2. 目录结构（仓库根 = voice_drone_assistant/）

路径	说明
main.py	程序入口（会 chdir 到本目录并跑 voice_drone.main_app）
with_system_alsa.sh	在 Conda/残缺 ALSA 环境下修正 LD_LIBRARY_PATH，建议始终包一层启动
requirements.txt	Python 依赖（含 websocket-client 等）
voice_drone/main_app.py	主流程：唤醒、问候/快路径、关麦、LLM/云端、TTS、offboard
voice_drone/core/	音频采集、预处理、VAD、STT、TTS、Socket、云端 WS、唤醒、命令、文本预处理、配置加载
voice_drone/flight_bridge/	伴飞桥（ROS1+MAVROS）：flight_intent → 飞控；说明见 docs/FLIGHT_BRIDGE_ROS1.md
voice_drone/config/	各类 YAML，见下文「配置文件」
voice_drone/logging_/	日志与彩色输出
voice_drone/tools/	config_loader 等工具
docs/	PROJECT_GUIDE.md（本文）、llmcon.md（云端协议）、clientguide.md（联调与示例）
scripts/	run_px4_offboard_one_terminal.sh；伴飞桥 run_flight_bridge_with_mavros.sh（含 MAVROS）、run_flight_intent_bridge_ros1.sh（仅桥）；另有 generate_wake_greeting_wav.py、bundle_for_device.sh
assets/tts_cache/	唤醒问候等预生成 WAV（可自动生成）
models/	STT/TTS/VAD ONNX 等（需自备或 bundle，见 models/README.txt）

---

3. 配置文件一览

配置由 voice_drone/core/configuration.py 在进程启动时读入；主文件为 voice_drone/config/system.yaml（路径相对 voice_drone_assistant 根目录）。

文件	作用
system.yaml	总控：audio（采样、设备、AGC、降噪）、vad、stt、tts、cloud_voice、socket_server、text_preprocessor、recognizer（VAD 能量门槛、尾静音、问候/TTS 关麦等）
wake_word.yaml	唤醒词主词、变体、模糊/部分匹配策略
keywords.yaml	命令关键词与同义词（供文本预处理映射到 Command）
command_.yaml	各飞行动作默认 distance/speed/duration（与 Command 联动）
cloud_voice_px4_context.yaml	云端 session.start.client 扩展：vehicle_class、mav_type、default_setpoint_frame、extras 等，供服务端 LLM 生成 PX4 相关指令；路径在 system.yaml → cloud_voice.px4_context_file，也可用环境变量 ROCKET_CLOUD_PX4_CONTEXT_FILE 覆盖

修改 YAML 后需重启 main.py 生效（SYSTEM_CLOUD_VOICE_PX4_CONTEXT 等在 import 时加载一次）。

---

4. system.yaml 常用区块（索引）

• audio：采样率、frame_size、input_device_index（null 则枚举设备）、prefer_stereo_capture（ES8388 等）、noise_reduce、agc*、agc_release_alpha
• vad：Silero 用阈值、end_frame 等（能量 VAD 时部分由 recognizer 覆盖）
• stt：SenseVoice 模型路径、ORT 线程等
• tts：Kokoro 目录、音色 voice、speed、output_device、playback_*
• cloud_voice：enabled、server_url、auth_token、device_id、timeout、fallback_to_local、px4_context_file
• socket_server：试飞控 TCP 地址、reconnect_interval、max_retries（-1 为断线持续重连直至成功）
• recognizer：trailing_silence_seconds、vad_backend（energy/silero）、energy_vad_*、energy_vad_utt_peak_decay、energy_vad_end_peak_ratio、pre_speech_max_seconds、ack_pause_mic_for_playback、应答 TTS 等

更细的参数含义以各 YAML 内注释为准。

---

5. 系统使用方式

5.1 推荐启动命令

在 voice_drone_assistant 根目录：

bash with_system_alsa.sh python main.py

或使用模块方式：

bash with_system_alsa.sh python -m voice_drone.main_app

录音设备：首次可交互选择；非交互时可设 ROCKET_INPUT_DEVICE_INDEX 或使用 main.py --input-index N / --non-interactive（详见 main_app 内 argparse 与文件头注释）。

5.2 典型工作流（默认 TakeoffPrintRecognizer）

1. 说唤醒词（如「无人机」）；若同句带指令，会跳过问候与滴声，直接关麦处理：命中 keywords.yaml 的 takeoff 则 offboard，否则走 LLM/云端。
2. 若只唤醒，则问候（或缓存 WAV）+ 可选滴声 → 再说一句指令。
3. 云端模式：指令以文本上云，TTS 多为服务端 PCM；本地模式：Qwen 推理 + Kokoro 播报。

5.3 云端语音（可选）

• system.yaml 里 cloud_voice.enabled: true，或环境变量 ROCKET_CLOUD_VOICE=1
• ROCKET_CLOUD_WS_URL、ROCKET_CLOUD_AUTH_TOKEN、可选 ROCKET_CLOUD_DEVICE_ID（可覆盖 yaml）
• PX4 语境：见 cloud_voice_px4_context.yaml / ROCKET_CLOUD_PX4_CONTEXT_FILE
• 协议与消息类型： docs/llmcon.md
• 飞控 JSON 是否机端执行： ROCKET_CLOUD_EXECUTE_FLIGHT=1；走 ROS 伴飞桥时再设 ROCKET_FLIGHT_INTENT_ROS_BRIDGE=1（详见 docs/DEPLOYMENT_AND_OPERATIONS.md）

5.4 本地大模型与 TTS

• GGUF：cache/ 默认路径或 ROCKET_LLM_GGUF
• 关闭对话：ROCKET_LLM_DISABLE=1
• 流式输出：ROCKET_LLM_STREAM=0 可改为整段生成后再播（调试）
• 详细列表见 voice_drone/main_app.py 文件头部注释。

5.5 其它实用环境变量（摘录）

变量	说明
ROCKET_ENERGY_VAD	1 时使用能量 VAD（板载麦常见）
ROCKET_PRINT_STT / ROCKET_PRINT_VAD	终端打印 STT/VAD 诊断
ROCKET_CLOUD_TURN_RETRIES	云端 WS 单轮失败重连重试次数（默认 3）
ROCKET_PRINT_LLM_STREAM	云端流式字 llm.text_delta 打印到终端
ROCKET_WAKE_PROMPT_BEEP	0 关闭问候后滴声
ROCKET_MIC_RESTART_SETTLE_MS	播完 TTS 恢复麦克风后的等待毫秒

---

6. 相关文档与代码入口

文档	内容
README.md	简版说明、bundle 到香橙派、与原仓库关系
docs/DEPLOYMENT_AND_OPERATIONS.md	部署与外场启动：拓扑、ROS_MASTER_URI、双终端启动顺序、环境变量速查、联调
docs/PROJECT_GUIDE.md	本文：目录、配置、使用方式总览
docs/FLIGHT_BRIDGE_ROS1.md	ROS1 伴飞桥、MAVROS、/input、rostopic pub
docs/llmcon.md	云端 WebSocket 消息类型与客户端约定
docs/CLOUD_VOICE_FLIGHT_CONFIRM_v1.md	云端 dialog_result v1（protocol=cloud_voice_dialog_v1，闲聊/飞控分流 + confirm）

能力	主要代码
音频采集/AGC	voice_drone/core/audio.py
能量/Silero VAD	voice_drone/core/recognizer.py、voice_drone/core/vad.py
STT	voice_drone/core/stt.py
本地 LLM 提示词	voice_drone/core/qwen_intent_chat.py（FLIGHT_INTENT_CHAT_SYSTEM）
云端会话	voice_drone/core/cloud_voice_client.py
主流程	voice_drone/main_app.py
配置聚合	voice_drone/core/configuration.py

---

7. 版本与维护

• 配置项会随功能迭代增加；若与运行日志或 llmcon 不一致，以当前仓库 YAML + 代码为准。
• 新增仅与云端相关的字段时，请同时通知服务端解析 session.start.client（含 PX4 扩展块）。

---

文档版本：与仓库同步维护；更新日期见 Git 提交。