EXP-01⭐ · 4 学时
需求分析（R1-R13）
拆解 R1-R13 需求体系与"检测→追踪→指令门控→描述选车→清除→事件日志"全流程，标注所有 fail-closed 节点。
- ① 问题引入：13 条需求到底管什么⭐4 学时 · 开始
- ② 动画：检测→追踪→门控→事件全流程⭐动画
- ③ 互动：需求条目速配台⭐交互
- ④ 实操：grep 命令通读需求文档⭐实操
- ⑤ 总结与思考：LLM 为什么不分配 ID⭐验证
👆 点击小节标题或右侧标签直达对应章节
9 个递进实验，从 R1-R13 需求体系出发，贯通 TrackEngine 单状态机架构与 track_config.yaml 配置方案，深入 DeepSORT 追踪底座、LLM 指令门控与 VLM 描述选目标，最终以语音流式打断、events.jsonl 故障降级与全功能验证收口 —— 每个实验均配原理讲解、动画演示与互动实验台。
先核对软硬件与知识准备，再进入第 1 章；缺任何一项都可能卡在后面的硬件实验里。
Python 编程（线程、队列、装饰器）、深度学习基础（目标检测与嵌入式模型概念）、Linux 命令行与 grep / sed 常用操作。
工控主机（RKNN 运行时）、RGB 深度相机（话题 /ascamera_hp60c/camera_publisher/rgb0/image）、XFM 六麦阵列（串口 /dev/ttyACM0）、扬声器（aplay · plughw:4,0）。
ROS2 Humble + car1_peripherals 相机 launch；zipformer ASR、Matcha-TTS + Vocos 播报；Qwen3.5-0.8B LLM/VLM rkllm 服务（端口 8080，首次加载约 30-60s）。
ros2_ws/src/xflz_eai_car1/app/object_tracking/ 就位；docs 十份文档、config/track_config.yaml、runs/logs/ 输出目录可写。
object_tracking 是一个"看—听—说—记"闭环的通用目标追踪应用，视觉与语音两条流水线在 TrackEngine 的同一个循环里协同。
帧 → YOLOv8n RKNN（COCO 80 类，class_filter=[car]）→ ReID 外观特征 → DeepSORT 级联匹配 → 确认框按 follow_ids 过滤绘制 → MJPEG 发布。
唤醒词 → ASR → LLM FunctionCall → _native_gate 门控 → tool_dispatch → submit_effect 入队（maxsize=8）→ 主循环 apply → 流式 TTS 分句播报。
文本（--text，stdin 喂指令、无麦克风）→ 语音（+录音/播放）→ 摄像头（+ROS 话题）。每级只叠加一层硬件依赖：先离线跑通，再逐步上硬件。
主入口 apps/track_app.py，离线演示 apps/track_demo.py；浏览器访问 http://<IP>:8088/track.mjpg 查看实时标注流，事件落盘 runs/logs/events.jsonl。
全部取自 config/track_config.yaml，实验中反复出现的数值边界先在这里混个脸熟。
score_thr=0.25 · iou_thr=0.45 · imgsz=640 · class_filter=[car]——第一级过滤，决定哪些框进入追踪。
use_reid=true · min_confidence=0.3 · min_box_w/h=32 · max_stale=15——第二级过滤与软保留阈值。
pause_wait=true · pause_timeout=30.0——指令挂起时只读帧不处理，30 秒看门狗自动恢复。
cell_cap=16 网格封顶 · vlm.fake_result_id=3 仅链路调试——超过 16 个候选直接 fail-closed。
port=8088 · stream_name=track.mjpg；LLM 服务端口 8080；指令队列 maxsize=8 满则丢最旧。
wake_words=[小飞小飞, 小飞同学] · kws.threshold=0.25 · 文本模式队列 maxsize=100（约 10 秒缓冲）。
源码路径 ros2_ws/src/xflz_eai_car1/app/object_tracking/，docs 目录十份文档与九个实验一一对应。
01_需求总览（R1-R13）、02_架构设计（七层模块与依赖方向）、05_流程与安全（fail-closed）、README 架构速览。
04_配置方案、10_程序参数详解——逐键解读 track_config.yaml 与 CLI 参数的覆盖规则。
03_开发模式与验证（五步验证法）、07_语音测试用例、08_视觉测试用例、09_事件与故障测试用例。
06_环境依赖——RKNN 运行时、ASR/TTS 模型、LLM 服务与硬件外设（相机、六麦、工控主机）清单。
一辆搭载摄像头与六麦麦克风的智能小车，怎么做到"听得懂、看得准、跟得住、坏得明明白白"。
摄像头画面进 YOLOv8n 检测与 DeepSORT 追踪，语音指令经 LLM FunctionCall 门控下发，VLM 用网格描述挑目标，全链路事件落盘 events.jsonl。
会读需求（R1-R13）、会读单状态机主循环、会改配置不炸锅、会解释每一次匹配与每一次降级，最终独立完成五步全功能验证。
工控主机 + 摄像头 + XFM 六麦阵列；Qwen3.5-0.8B（rkllm）、Qwen3.5-0.8B-vision、yolov8n.rknn、deepsort.rknn 四个模型协同工作。
追踪/清除/截图指令全部经门控生效，描述选目标可回映真实 ID，断网断模型时按降级链退化不崩溃，日志可完整复盘。
48 学时怎么分：架构 12 学时打底，模块集成 28 学时攻坚，验收 8 学时收官。
| 编号 | 实验名称 | 学时 | 难度 | 类型 | 核心产出 |
|---|---|---|---|---|---|
| EXP-01 | 需求分析（R1-R13） | 4 | ⭐ | 验证性 | 十三条需求分层表与量化约束清单 |
| EXP-02 | TrackEngine 单状态机架构 | 4 | ⭐⭐ | 设计性 | 七层依赖图与主循环五步节拍说明 |
| EXP-03 | track_config.yaml 配置详解 | 4 | ⭐⭐ | 设计性 | 顶层键速查表与 CLI 覆盖规则笔记 |
| EXP-04 | DeepSORT 追踪底座 | 8 | ⭐⭐⭐ | 综合性 | pytest 全绿 + track_demo 管道实测 |
| EXP-05 | LLM 指令门控（FunctionCall） | 4 | ⭐⭐⭐ | 综合性 | _native_gate 五分支判定表与三层防线 |
| EXP-06 | VLM 描述选目标 | 4 | ⭐⭐⭐ | 综合性 | 网格 dump 样例与编号回映验证日志 |
| EXP-07 | 语音交互（流式 TTS 打断） | 6 | ⭐⭐⭐ | 综合性 | VoiceLoop 三态走查与打断场景记录 |
| EXP-08 | 事件日志与故障降级 | 6 | ⭐⭐⭐ | 综合性 | 五类事件日志片段与故障注入记录 |
| EXP-09 | 全功能验证 | 8 | ⭐⭐⭐ | 综合性 | 离线 + 实时双链路闭环与五步核对表 |
每个实验页固定十节（01 引入 → 10 总结），建议按同一节奏推进。
弄清这个实验"为什么存在"：生活比喻讲原理，关联知识点接回理论课，实验目标就是最后的验收条目。
轨迹关联、门控分闸、网格回映、事件时间轴 —— 抽象流程先用动画建立直觉，再去源码对照行号锚点。
阈值、开关、判定分支随便拨 —— 互动台不烧板子不占机时，调出感觉后再上实机，一次到位。
代码块可直接复制到板端执行；先文本模式（--text）跑通逻辑，再逐步叠加语音与相机硬件。
报错先查坑表三分法 —— 现象 → 原因 → 解法；绝大多数现场问题在表格里有现成答案。
思考题刻意指向跨实验的联系（如 fail-closed 的普适性），答案能串起整条课程主线。
贯穿九个实验的核心词汇，先混个脸熟，后续章节会反复用到。
"拿不准就不放行"：门控、VLM 解析拿不到确定结果时一律拒绝执行，宁可不动也不乱动。
TrackEngine 只有一条 RUN 主循环（读帧→处理→排干指令→绘制→发布），像电梯调度统一排班，杜绝多线程抢状态。
LLM 不直接干活，只在 track_ids / clear_track / save_snapshot 三个原生工具里做选择题，由 _native_gate 把关。
VLM 网格描述选目标时最多切 16 格（448×448 缩略图），格子编号再映射回真实追踪 ID。
边长低于 32 像素的检测框不进追踪链，太小的框特征不可靠，进了只添乱。
新一轮语音播报使 epoch 递增，旧播报与迟到指令因编号过期被丢弃，解决"自说自话"。
清除指令或目标丢失导致追踪全部解除的事件，落盘 events.jsonl，是复盘"为什么跟丢了"的关键线索。
文本 → 语音 → 摄像头逐级叠加：任何功能先用 --text 跑通逻辑，再上硬件，出问题好定位。
看懂全项目的需求底座：R1-R13 需求体系、TrackEngine 单状态机与 track_config.yaml 配置方案。
拆解 R1-R13 需求体系与"检测→追踪→指令门控→描述选车→清除→事件日志"全流程，标注所有 fail-closed 节点。
七层模块依赖单向贯通，RUN 循环"读帧→处理→排干指令→计算绘制→发布"一条链；CommandWorker 独立线程不卡帧，pending 暂停 + 30s 看门狗。
13 个顶层配置段逐一拆解：detect/tracker/tracking/interaction/speech/server… ；REQUIRED 白名单校验与 CLI 覆盖规则，故意改错看真实 Traceback。
项目三大 AI 底座：DeepSORT 卡尔曼+ReID 追踪、LLM FunctionCall 指令门控、VLM 网格描述选目标。
8 维卡尔曼预测→级联匹配→IoU 兜底三步走；ReID 外观代价与马氏门控，min_box 32、min_confidence 0.3 两级过滤，97 项 pytest 回归护航。
NATIVE_TOOLS 三函数（track_ids / clear_track / save_snapshot），_native_gate 五步判定顺序即优先级；清除词强制短路，解析不出绝不 submit，规则兜底三层防线。
候选框拼 448×448 缩略网格、cell_cap=16 封顶，VLM 只答格子编号再映回绝对 ID；解析 0/99/越界一律 None 汇入 _vlm_none，拿不准宁不放行。
流式 TTS 打断闭环、events.jsonl 黑匣子与故障降级全景，最后五步法全功能验证收口整个项目。
IDLE→LISTENING→SPEAKING 状态机；XFM 六麦唤醒后才开录音，zipformer 端点检测，按句切分首句即播，epoch 递增丢弃迟到指令。
events.jsonl 黑匣子五类事件（lost/unlock_all/command/camera_stall/pause_timeout）；断 LLM 走规则兜底、ReID 挂了退纯 IoU、aplay 死了重启降级。
三级开发模式五步验证法：pytest 回归→离线文本链路→起相机→--camera 实时全链路→清理；MJPEG 流浏览器监视与日志锚点排障方法论。
48 学时 = 三个篇章递进；按实验类型区分"验证—设计—综合"三种动手强度。
EXP-01 ~ 03 各 4 学时：需求体系、单状态机架构与配置方案，全部是"读懂与跑通"级别的地基工作。
EXP-04 深度追踪独占 8 学时，EXP-05、06 各 4 学时：三大 AI 底座逐个集成测试，难度最高的核心章节。
EXP-07 语音 6 学时、EXP-08 事件与降级 6 学时、EXP-09 全功能验证 8 学时：系统级联调与验收收口。
验证性 1 个（EXP-01）、设计性 2 个（EXP-02、03）、综合性 6 个（EXP-04 ~ 09），动手强度逐级抬升。
出问题先分层定位：四类日志锚点覆盖音频、识别、指令、状态四层，缩小范围再复现。
音频层锚点：正常为 50 帧/5s（read(1600)=0.1s）；降到 30 帧以下触发 HEALTH_LOW_FPS 重开封禁逻辑。
识别层锚点：看 partial / final 是否出字；不出字先查解码方法是否 modified_beam_search、热词是否生效。
指令层锚点：逐分支打印门控走向（track_ids / 清除语义 / 回引导 / 非指令），一眼看出指令死在哪一步。
状态层黑匣子：camera_stall → 查相机；pause_timeout → 查 LLM；lost / unlock_all → 查追踪与锁定状态。
全课程围绕 object_tracking 真实工程展开，命令与参数全部取自实验讲义原文。
EXP-01 的 R1-R13 是全项目的"宪法"：每条后续实验遇到的行为（清除词、min_box、fail-closed）都能回溯到某条需求。
EXP-02、03 搞清"谁说了算"：RUN 循环与 _native_gate 决定一切指令的命运，配置文件决定所有数值的边界。
卡尔曼预测-修正、门控五步、VLM 网格这些抽象过程，先在动画和互动台里调一遍参数，再去命令行验证。
EXP-08、09 收口时记住：好系统不是不坏，而是坏了知道（events.jsonl）、坏了能退（规则兜底/纯 IoU）。