分层系统架构：六层依赖与双流水线

01问题引入：多模块系统靠什么"接口"对接

设想没有架构约束的写法：检测代码直接起线程录音、告警代码直接读摄像头帧、LLM 回复直接塞进 TTS —— 每处改动都要全局搜索，牵一发动全身。本工程用分层 + 接口解决：

02原理通俗讲解：六层像"医院的科室分工"

把系统想象成一家医院：挂号信息（配置）统一管理，检验科出报告（模型推理），主治医生下诊断（状态机），护士执行医嘱（TTS/告警），病历室留档（证据），门诊大厅是入口（apps）。六层依赖自下而上：

03关联知识点：monitor.py 三大接口与 voice_loop 双入口

04实验目标

• 能画出六层依赖图，说出每层的职责与工程对应模块
• 能复述 monitor.py 三大接口各自的签名职责、所在行号与调用方
• 能说明视觉流水线与语音流水线的交汇点与隔离点（为什么相机卡顿不堵录音）
• 能解释 feed_text 与音频通道为何必须共用同一台状态机（R12 的架构意义）
• 完成一次文本通道验证：用 text 驱动状态机走通"唤醒 → 询问 → 应答"最小闭环

05实验环境与准备

06动画讲解：分层数据流与双流水线协同

左半幅：一帧数据自上而下穿过六层（包沿线流动）；右半幅：视觉流水线与语音流水线平行推进，在状态机处交汇：

07互动讲解：六层职责与接口连线台

点击按钮，查看每个"接口合约"的承诺、调用方与被隔离的复杂度：

08实操步骤：精读关键行与统一通道验证

# ① 进入工程并自检
cd ~/ros2_ws/src/xflz_eai_car1/app/elderly_companion
python3 common/env_check.py --config config/fall_config.yaml
# 预期：[env] 自检通过（缺项时逐条 MISSING，EXIT 2）

# ② 定位三大接口（行号应与本课第 03 节一致）
grep -n "def process_frame\|def has_ask_session\|def on_kws" fall/monitor.py
# 247: def process_frame(...)      每帧入口
# 152: def has_ask_session(...)    询问会话只读查询
# 168: def on_kws(...)             硬件/KWS 唤醒回调

# ③ 定位语音状态机宿主与文本入口
grep -n "def run\|def feed_text" voice_loop.py
# 224: def run(...)     交互主循环
# 154: def feed_text(...)  文本通道 → 同一状态机（R12）

# ④ 文本通道跑最小闭环（无需麦克风/摄像头）
python3 apps/speech_text_demo.py
# 依次输入：小飞小飞 → （系统询问后）没事 / 救命

09重点与易错点

• 三大接口的职责边界：process_frame 管帧、has_ask_session 管查询、on_kws 管唤醒，不可互相挪用
• 文本与音频是同一台状态机的两个入口（feed_text L154–L181），不是两套逻辑
• 双流水线的隔离点在状态机：相机/LLM 的延迟不会阻塞另一条线
• _dispatch 是决策与执行的分界：状态机只给结论，不直接碰硬件

10总结与思考