全功能验证：五步验收，让整条链路闭环

01问题引入：最后一步为什么最难过

每个模块单测都过了，合成验收时却常遇到：

02原理通俗讲解：三档驾照与出车体检

03关联知识点：三模式与全链路验收

04实验目标

05实验环境与准备

实验前确认没有残留进程——8080/播放设备/串口都是独占资源，被占会直接启动失败：

cd ~/ros2_ws/src/xflz_eai_car1/app/object_tracking
ps aux | grep -E "track_app|llm_server|aplay" | grep -v grep   # 基线：应无残留
# 若有残留：pkill -f llm_server; pkill -9 aplay 后再进实验

06动画讲解：三级开发与五步验收

图：三档台阶逐级加硬件（绿箭头），顶部五盏验收灯按 Step1-5 顺序点亮（discrete 循环），黄色回退虚线 = 三级开发"前级永远可回归"的安全网，底部光点 = 数据在同一条链路上持续流动。

07互动讲解：五步验收步进台

← 从 Step1 开始按序点亮；验收灯 0/5，当前未开始

五步的通过判据（docs/03 Step1-5）：pytest 全绿 → 离线日志闭环 → 相机话题在线 → MJPEG 出流且 ID 稳定 → 事件完整且无残留进程。任何一步失败都回退到上一步，而不是往下硬闯。两个注入按钮演示最常见的两条失败分支及其定位路径。

08实操步骤：五步验证全链路

步骤 1 · pytest 全量回归（x86 可跑、无 RKNN/ROS 依赖）：

cd ~/ros2_ws/src/xflz_eai_car1/app/object_tracking
python3 -m pytest tests/ -v
# 覆盖 tools/ 门控 / VLM 虚测(vlm_fake 固定 fake_result_id=3) / 单帧 pipeline / 录音自愈
# 全绿才继续；实机出问题时也先复跑本回归，把框架缺陷与环境问题分开

步骤 2 · 离线视频文本全链路（三模式之一 --video，与音频同一状态机）：

python3 apps/track_app.py --video /home/iflytek/ros2_ws/src/xflz_eai_car1/vision/07_multi_object_tracking/test.mp4 --text
小飞小飞          # stdin 首行唤醒词才进 DIALOG（--text 已关 KWS/硬件唤醒）
追踪 id3          # 观察：唤醒 → 追踪锁定 → 出画 lost → 清除 unlock_all
# 核对 runs/logs/events.jsonl：command/lost/unlock_all 条目齐全；--text 走 feed_text 同一回调链

步骤 3-4 · 实时摄像头 + MJPEG 推流 + 标注帧落盘：

# 另一终端提供相机话题：
source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
ros2 launch car1_peripherals depth_camera.launch.py
# 主终端（--save 落盘标注帧，frames:1920 fps:10）：
python3 apps/track_app.py --camera --mjpeg --save
浏览器打开 http://<IP>:8088/track.mjpg   # 持续 MJPEG 流，ID 稳定由 min_confidence=0.3 + [car] 双闸压噪
小飞小飞 → 追踪红色皮卡 → 解除         # 语音链路闭环；headless 下 display.show 默认关，别强开 --show

步骤 5 · 五步核对 + 资源清理 + 排查锚点：

# 分层排查锚点：[diag] 录音 50 帧/5s（音频层）· [ASR 实时]（识别层）· [cmd] 逐分支（指令层）· jsonl（状态层）
#   pause_timeout → 查 LLM（pending 超 30s）；camera_stall → 查相机（连续 30 次读帧失败）
tail -f runs/logs/events.jsonl   # 收尾：状态变化齐全；runs/out 标注帧带 follow 过滤不空
pkill -f llm_server; pkill -9 aplay   # 独占资源：8080 / 播放设备 / 串口必须释放
ps aux | grep -E "track_app|llm_server|aplay" | grep -v grep   # 应无残留；回滚 git revert 前同样先 pkill

09重点与易错点

• 回归先于实机：全功能验证前 pytest 必须全绿，否则框架缺陷会混入功能问题，排查方向直接跑偏。
• stdin 首行是唤醒词：文本模式先输入"小飞小飞"才进 DIALOG；--text 已自动关闭 kws.enabled/hardware_wakeup.enabled。
• None 帧不进 pipeline：EOF/断流时 read() 返回 (False, None)，engine 只在成功读帧时才处理——这是输入层与算法层的隔离边界，改造代码时别绕过它。
• 相机话题必须在线：--camera 依赖 /ascamera_hp60c/camera_publisher/rgb0/image（rclpy 惰性导入），没起 depth_camera.launch.py 就会读帧失败累计出 camera_stall。
• MJPEG 是持续流不是图片：stream_name 默认 track.mjpg（name 不带 .mjpg 会自动补全）；端口 8088 预检被占用会明确报错退出，先清理再起。
• ID 跳变先查双闸：min_confidence=0.3 + class_filter:[car] 是实机 tuned 值——调低引入噪声 ID，调高漏检小车；别在验收阶段随手改。
• 事件日志/标注帧完整性是验收关键：产生的事件都要追加写入 jsonl；--save 落盘帧按 follow 过滤，锁定目标没画出来说明过滤链路出错。
• 收尾必清理：llm_server(8080)/aplay(播放设备)/XFM 串口都是独占资源，不清会直接害死下一次实验；回滚代码前也要先 pkill，避免旧进程旧逻辑混淆排查。

10总结与思考

本实验把九章内容合成一张验收单：三级开发（文本→语音→摄像头）保证每一层硬件都可独立回归，三模式入口（--video/--image/--camera）用统一的 FrameSource read() 契约把输入差异挡在算法层之外，五步验证（pytest → 离线 → 相机 → 实时 MJPEG → 清理）给出每步的通过判据，"缩小→复现→日志定位"给出故障时的行动地图，pkill 清理保证独占资源（8080/播放设备/串口）干净交接。从 exp01 的需求到 exp09 的全功能，事件链路里的多个 fail-closed 节点共同兜住了"不误导、不误锁"的底线。产出：pytest 全绿记录、离线/实时两条全链路日志、MJPEG 出流截图、五步核对表与清理后进程检查记录。