From: SnickerSun Date: Sun, 17 May 2026 16:24:12 +0000 (+0800) Subject: 补充漏提交文档 X-Git-Url: http://git.snicker.com.cn/css/static/gitweb.css?a=commitdiff_plain;h=e3b4d7049655c2f903aa927b95399f4168d15468;p=mirrors%2FASR1603_G5.git 补充漏提交文档 --- diff --git "a/1.doc/AI\345\220\212\345\235\240\357\274\210\345\217\214\346\214\211\351\224\256+\344\270\211\350\211\262\346\214\207\347\244\272\347\201\257\357\274\211\350\257\246\350\256\276-\345\257\271\347\205\247\344\270\216\345\206\263\347\255\226.md" "b/1.doc/AI\345\220\212\345\235\240\357\274\210\345\217\214\346\214\211\351\224\256+\344\270\211\350\211\262\346\214\207\347\244\272\347\201\257\357\274\211\350\257\246\350\256\276-\345\257\271\347\205\247\344\270\216\345\206\263\347\255\226.md" index 1b08cf34..fe4ce5ec 100644 --- "a/1.doc/AI\345\220\212\345\235\240\357\274\210\345\217\214\346\214\211\351\224\256+\344\270\211\350\211\262\346\214\207\347\244\272\347\201\257\357\274\211\350\257\246\350\256\276-\345\257\271\347\205\247\344\270\216\345\206\263\347\255\226.md" +++ "b/1.doc/AI\345\220\212\345\235\240\357\274\210\345\217\214\346\214\211\351\224\256+\344\270\211\350\211\262\346\214\207\347\244\272\347\201\257\357\274\211\350\257\246\350\256\276-\345\257\271\347\205\247\344\270\216\345\206\263\347\255\226.md" @@ -1,307 +1,307 @@ -# AI吊坠(双按键+三色指示灯)详设 — 对照与决策 - -> **需求文档**:[交互规范_new](./AI吊坠(双按键+三色指示灯)交互规范_new.md)(产品行为准绳) -> **场景详设**:[详设-场景与协议流程](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)(按键/协议步骤展开) -> **实现真源**:`2.sdk/Helios_SDK/services/microPython/ports/quectel/core/ai_VC.py`(`AI_led`、`AI_hw_status`、`AI_dev`) - ---- - -## 0. 如何使用本文档 - -### 0.1 三角对照 - - -| 角 | 文档 | 回答的问题 | -| ------ | ------------------------------ | -------- | -| **需求** | `交互规范_new.md` + `REQ-`* | 用户要什么? | -| **设计** | 本文第 2 ç«  `DES-`*、场景 `DES-SCN-`* | 固件应怎么做? | -| **实现** | `ai_VC.py` 等 | 代码现在怎么做? | - - -评审流程:**第 3 章矩阵** 标 `状态` → 不一致项查 **第 4 ç«  GAP** → 在 **决策** 列填 `采纳甲` / `采纳乙` / `搁置` / `改需求` → 再改代码或改需求,避免三方漂移。 - -### 0.2 准绳优先级 - -1. 你已勾选的 GAP **决策**(最高) -2. 需求文档(产品对外承诺) -3. 本文设计规格(工程应然) -4. 当前代码(现状,直至按决策修改) - -### 0.3 要点摘要(评审速览) - -- **长对话**:短按打断 TTS / **思考中** → `RequestToSpeak` → `VC_init` → `cancel` → `canceled` → `uplink_start`(见 `DES-SCN-010.2`~`010.4`、`DES-SCN-011`)。 -- **单对话**:长按开录 / 松手 `audio.completed`;TTS 中短按仅停播,续聊须再长按(见 `DES-SCN-020.6`)。 -- **待机灯**:正常待机 **灭灯**(`LED_IDLE_MODE=off`,GAP-005 方案甲)。 -- **电量阈值**:低电 `soc<30%`、空电 `soc<10%`(GAP-007 方案甲)。 -- **异常灯**:`set_led_state.alert=rb_flash_2` 红蓝快闪 2 次后回表(GAP-006 已落实 ASR 空结果、thinking 超时)。 - ---- - -## 1. 系统架构(一页) - -```mermaid -flowchart TB - gpio[GPIO_btn_device] - dev[AI_dev_去抖串行] - vc[AI_VC_按键与VCStateMachine] - ws[WebSocket_V2_5] - aud[录音播放队列] - led[AI_led] - hw[AI_hw_status] - gpio -->|EventMesh| dev - dev -->|AI_key_press等| vc - vc --> ws - vc --> aud - vc -->|set_led_state| led - hw -->|set_led_state| led -``` - - - -### 1.1 模块职责 - - -| 模块 | 文件 | 职责 | -| ---------------- | ---------- | ------------------------------------------ | -| `AI_dev` | `ai_VC.py` | 按键 ExtInt、去抖、`publish_AI_btnInfo` 串行执行 | -| `AI_VC` | `ai_VC.py` | WebSocket 会话、按键路由、音频上下行 | -| `VCStateMachine` | `ai_VC.py` | `session` / `turn` / `tts_rx_phase` 唯一轮次真源 | -| `AI_hw_status` | `ai_VC.py` | 10s 轮询 + `hw_usb_state` → 充电/电量/信号 | -| `AI_led` | `ai_VC.py` | `set_led_state` 聚合 → GPIO 灯效 | - - -### 1.2 EventMesh 主题(常用) - - -| 主题 | 发布方 | 订阅方 | 说明 | -| ------------------------------------------------------- | ---------------------- | -------------- | ------------------- | -| `AI_key_press` / `AI_key_long_press` / `AI_key_release` | `AI_dev` | `AI_VC` | AI 键 | -| `pwk_key_double_press` | 电源键模块 | `AI_VC` | Power 双击切 `VC_mode` | -| `set_led_state` | `AI_VC`、`AI_hw_status` | `AI_led` | LED 唯一入口 | -| `hw_usb_state` | 底层 | `AI_hw_status` | USB 插拔即时刷新 | -| `get_led_debug_state` | 调试 | `AI_led` | 返回聚合灯态 | - - -### 1.3 设计原则(文档化) - -- 轮次/会话判断只读 `fsm.*`,不引入并行整型状态。 -- 打断 TTS:**先** `VC_init`(本地停播清队列)**再** `cancel` / `audio.create`(见 `DES-SCN-003`)。 -- LED 只经 `set_led_state`;AI 阶段灯优先于充电/电量(见 `DES-L3-01`)。 - ---- - -## 2. 设计规格(按层) - -### 2.1 L1 输入与按键(`DES-L1`) - - -| ID | 规格 | 实现锚点 | -| --------- | ----------------------------------------- | ------------------------------------------------ | -| DES-L1-01 | 长对话:AI **短按** 唤醒/打断/续聊 | `AI_key_press` → `_ai_key_press_long_dialogue_`* | -| DES-L1-02 | 单对话:AI **长按** 开录、**松开** `audio.completed` | `ptt_begin`、`_ai_key_release_handle_ptt` | -| DES-L1-03 | 单对话:TTS 中 **短按** 仅停播,不开录 | `_ai_key_press_ptt_mode` | -| DES-L1-04 | Power **双击** 切换 `VC_mode` å¹¶ TTS 播报 | `pwk_key_double_press` | -| DES-L1-05 | Power 交互中 **短按** `Close` 断会话进待机 | `pwk_key_press` 等 | - - -### 2.2 L2 会话与协议(`DES-L2`) - - -| ID | 规格 | 实现锚点 | -| --------- | ------------------------------------------------------- | ------------------------------------------ | -| DES-L2-01 | `VC_mode=0`:VAD 开,一般无 `audio.create`/`completed` | `VCMode.Realtime` | -| DES-L2-02 | `VC_mode=1`:VAD 关,必须 `audio.create`→帧→`audio.completed` | `VCMode.PushToTalk` | -| DES-L2-03 | 会话层:`Disconnected`→`Connecting`→`Starting`→`Started` | `VCSessionState` | -| DES-L2-04 | 轮次层:`Idle`→`Listening`→…→`Playing`→续轮 | `VCTurnState`、`VCStateMachine` | -| DES-L2-05 | 长对话打断 TTS:`cancel`→`canceled`→`uplink_start` | `RequestToSpeak`、`on_server_canceled` | -| DES-L2-06 | 长对话播完门控:`audio.played` 后可自动开麦 | `fsm.await_played`、`on_local_audio_played` | - - -步骤级展开见 [场景详设](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)。 - -### 2.3 L3 呈现:灯 / 音 / 硬件态(`DES-L3`) - -#### DES-L3-01 LED 优先级(`AI_led._apply_by_table`) - - -| 优先级 | 输入 | 取值 | 灯效 | `period_ms` | -| --- | ---------- | ------------- | ----- | ------------------------- | -| P1 | `ai_state` | `playing` | 绿常亮 | — | -| P2 | `ai_state` | `thinking` | 蓝绿交替 | 500 | -| P3 | `ai_state` | `listening` | 蓝慢闪 | 1000 | -| B1 | `charging` | `full` | 绿常亮 | — | -| B2 | `charging` | `charging` | 红常亮 | — | -| B3 | `battery` | `low`/`empty` | 红慢闪 | 1000 | -| B4 | `signal` | `weak` | 蓝绿慢交替 | 1000 | -| 默认 | — | `idle` | **灭灯** | `LED_IDLE_MODE=off`(可选 `green_blink`) | -| P0 | `alert` | `rb_flash_2` | 红蓝快闪 2 次 | `250`(约 2 次/秒)后回表 | - - -`set_led_state` 键:`ai_state` / `charging` / `battery` / `signal` / `alert`。 - -#### DES-L3-02 硬件态采样(`AI_hw_status`) - - -| USB | SoC(非充电) | `charging` | `battery` | -| --- | -------- | ----------------- | ---------- | -| 否 | ≥30% | `none` | `normal` | -| 否 | 10%~30% | `none` | `low` | -| 否 | <10% | `none` | `empty` | -| 是 | — | `charging`/`full` | 不按 SoC 刷低电 | - - -弱网:`0 ≤ CSQ < SIGNAL_WEAK_CSQ`(默认 10)→ `signal=weak`。 - -#### DES-L3-03 灯与 FSM 对应 - - -| `ai_state` | 典型触发 | -| ----------- | ------------------- | -| `listening` | 开麦、续聊 | -| `thinking` | `llm.created` | -| `playing` | `tts.started` / 本地播 | -| `idle` | 交互结束、异常恢复 | - - ---- - -## 3. 需求 — 设计 — 实现对照矩阵 - - -| REQ-ID | 需求摘要 | 设计规格 | 实现锚点 | 状态 | GAP-ID | -| ----------- | ------------------------- | ----------------------- | ---------------------------- | ----- | ------- | -| REQ-PWR-01 | 关机时长按 Power 3s 开机,绿灯常亮 3s | (电源模块) | 电源键 / `ui` | 需求未定义 | — | -| REQ-PWR-02 | 死机长按 8s 强制关机,无灯无音 | (电源模块) | 电源键 | 需求未定义 | — | -| REQ-PWR-03 | 待机短按 Power 进休眠,无灯 | DES-L1-05 | `pm.autosleep` 等 | 部分一致 | — | -| REQ-PWR-04 | AI 交互中短按 Power 停对话进待机,绿慢闪 | DES-L1-05 | `Close` | 部分一致 | — | -| REQ-PWR-05 | Power 双击切换单/长对话并播报 | DES-L1-04 | `pwk_key_double_press` | 一致 | — | -| REQ-AI-01 | 长对话待机短按:蓝慢闪+滴,开麦 | DES-L1-01、DES-SCN-010.5 | `_ai_key_press_long_dialogue_wake`→`AI_VC_start` | 一致 | GAP-002 | -| REQ-AI-02 | 长对话聆听中短按:重开麦 | DES-SCN-010.3 | `request_uplink_start` | 一致 | — | -| REQ-AI-03 | 长对话 TTS 中短按:打断并聆听 | DES-SCN-010.2 | `_ai_key_press_long_dialogue_interrupt` | 一致 | — | -| REQ-AI-04 | 长对话思考中短按:打断并聆听 | DES-SCN-010.4 | `_ai_key_press_long_dialogue_interrupt` | 一致 | GAP-001 | -| REQ-AI-05 | 单对话 TTS 中短按:仅停播 | DES-L1-03、DES-SCN-020.3 | `_ai_key_press_ptt_mode` | 一致 | — | -| REQ-AI-06 | 单对话非 TTS 短按:无操作 | DES-L1-03 | `return True` 吞掉 | 一致 | GAP-003 | -| REQ-AI-07 | 单对话长按:蓝快闪+开录音 | DES-L1-02、DES-SCN-020.2 | `ptt_begin` | 一致 | — | -| REQ-AI-08 | 单对话松手:思考灯+层音+completed | DES-L1-02 | `AI_client_VC_end_speech` | 一致 | — | -| REQ-BAT-01 | 正常待机灯灭 | DES-L3-01 默认 | `_set_off`(`LED_IDLE_MODE=off`) | 一致 | GAP-005 | -| REQ-BAT-02 | 低电 10%~30% 红慢闪+双滴 | DES-L3-02 | `battery=low`(SoC<30%) | 一致 | GAP-007 | -| REQ-BAT-03 | 电量<10% 红快闪 3 次后关机 | DES-L3-02 | `battery=empty`(SoC<10%) | 一致 | GAP-007 | -| REQ-BAT-04 | 充电中红常亮+æ»´ | DES-L3-02 | `charging=charging` | 一致 | GAP-008 | -| REQ-BAT-05 | 充满红→绿常亮+长滴 | DES-L3-02 | `charging=full` | 一致 | — | -| REQ-ERR-01 | ASR 失败:红蓝快闪 2 次→待机灭 | DES-L3 P0 `alert` | `_vc_led_alert_rb_flash`(asr 空) | 一致 | GAP-006 | -| REQ-ERR-02 | 网络异常:蓝绿慢交替+语音循环 | DES-L3-02 B4 | `websocket_error`、`bg_alt` | 部分一致 | GAP-006 | -| REQ-ERR-03 | AI 超时:蓝常亮→红蓝闪→灭 | DES-L3 P0 `alert` | `thinking_timeout`→`alert` | 部分一致 | GAP-006 | -| REQ-NOTE-01 | 备注:会话空闲后进入休眠前灯态 | DES-L3 默认灭灯;可选绿闪 | `LED_IDLE_MODE` | 已对齐 part3 | GAP-005 | -| REQ-NOTE-02 | 备注:聆听蓝闪、思考交替、播放绿闪 | DES-L3-01 P2/P3/P1 | `set_led_state` | 部分一致 | — | -| REQ-NOTE-03 | 休眠无灯光 | (休眠策略) | `ui.py` / `pm` | 部分一致 | — | -| REQ-SUP-01 | 充电中 AI 交互优先 AI 灯 | DES-L3-01 | `_apply_by_table` | 一致 | GAP-008 | -| REQ-SUP-02 | 按键后灯音延迟≤100ms | DES-SCN-003 | `VC_init` 优先 | 一致 | — | - - ---- - -## 4. 差异登记簿(GAP) - -> **决策**列请产品/固件填写:`采纳甲` | `采纳乙` | `搁置` | `改需求` - - -| GAP-ID | 需求 | 设计目标 | 实现现状 | 风险 | 方案甲:架构精简·安全·实用 | 方案乙:改动最小 | 决策 | 影响面 | -| ------- | --------------------- | ------------------ | ---------------------------------------------- | --------- | ----------------------------------------------- | -------------------------------------- | -------------------------------- | -------------------------------------- | -| GAP-001 | REQ-AI-04 | 思考中短按统一打断并开麦 | 仅 TTS 忙走 `cancel`;纯 `Thinking` 可能 `Deny START` | 用户按了没反应 | `turn==Thinking` èµ° `RequestToSpeak`→`cancel`→开麦 | 详设标注限制;或单行门控热修 | **采纳甲**(已改代码) | `AI_key_press`、`_ai_key_press_long_dialogue_interrupt` | -| GAP-002 | REQ-AI-01 | 待机短按直达唤醒 | 兜底 `Close`+`AI_VC_start`+`sleep(500)` | 唤醒慢/偶发断链感 | 去掉兜底 `Close`;未连接单一路径 `AI_VC_start` | 保留现状,联调看 `[KEY]` | **采纳甲**(已改代码) | `AI_key_press`、`_ai_key_press_long_dialogue_wake` | -| GAP-003 | REQ-AI-06 | 单对话非 TTS 短按无操作 | 非播放态 `return True` 吞掉 | 低(防误触) | 保持为设计,REQ 已对齐 | 若需短按开录:改 `_ai_key_press_ptt_mode`+改需求表 | **采纳甲** | `_ai_key_press_ptt_mode` | -| GAP-005 | REQ-BAT-01 vs NOTE-01 | part3 灯灭 vs 备注绿灯慢闪 | idle 默认 `green_blink` | 产品表述冲突 | `AI_led` idle 灭灯 | **改需求** part3 为绿灯慢闪 | **采纳甲**(`LED_IDLE_MODE=off`) | `AI_led._apply_by_table` | -| GAP-006 | REQ-ERR-01~03 | 红蓝快闪等专用灯序 | 无 `alert` 模式;TTS/弱网替代 | 异常辨识度弱 | 新增 `alert` 键+优先级+业务触发 | 需求降级为语音+弱网灯;接受现状 | **采纳甲**(ASR 空、thinking 超时已接 alert) | `AI_led`、`ai_VC` 异常分支 | -| GAP-007 | REQ-BAT-02~03 | 10%/30% 阈值 | SoC 5%/20% 工程档 | 提醒时机偏差 | `AI_hw_status` 阈值可配置并对齐需求 | 需求脚注「以 OCV/工程档为准」 | **采纳甲**(30%/10%) | `default_config`、`AI_hw_status` | -| GAP-008 | REQ-BAT-04、SUP-01 | 充电红常亮 vs AI 覆盖 | AI 非 idle 盖住充电灯 | 充电中不易见红常亮 | 保持 AI 优先(交互反馈优先) | 充电中插入充电指示(需产品确认) | **采纳甲** | `AI_led` 优先级 | - - -### 4.1 整体姿态对比(选默认路线) - - -| 维度 | 姿态 A:架构精简·安全·实用 | 姿态 B:改动最小 | -| ------ | -------------------- | ------------------ | -| 目标 | 需求↔实现长期一致 | 冻结现状,文档吸收差异 | -| LED/异常 | 倾向 GAP-005/006 **甲** | 倾向 **乙**(改需求或接受现状) | -| 按键/FSM | 倾向 GAP-001/002 **甲** | 倾向 **乙**(标注已知限制) | -| 代码工作量 | 中~高 | 低(0~2 处热修) | - - -**建议**:先填齐上表 **决策** 列,再批量改需求或 `ai_VC.py`。 - -### 4.2 GAP-001:为何 `RequestToSpeak` 必须先 `cancel` 再开麦 - -长对话在 `turn==Thinking` 或 TTS 播放中,若直接 `uplink_start`,`_uplink_request_start` 会因 `turn` 非 `Listening/SpeechEnded` 而 **Deny START**;若先开麦再 `cancel`,本地/服务端旧轮下行可能与新一轮上行竞态。 - -**方案甲时序(与 DES-SCN-010.2/010.4 一致)**: - -1. 短按 → `AI_client_VC_RequestToSpeak`:`VC_init` 停播清队列 + WebSocket 发 `cancel`。 -2. 服务端 `server.canceled` → `on_server_canceled` 将 `turn` 置为 `Listening`。 -3. `on_server_event("canceled")` 追加 `uplink_start` → 开麦、蓝慢闪。 - -因此「cancel 在后」是指 **开麦动作在 canceled 事件之后**,而非不发 cancel。 - ---- - -## 5. 联调索引 - -### 5.1 检查清单(原 E8) - - -| # | 检查项 | 长对话 | 单对话 | -| --- | ---------------------- | ----------------------------------- | ---------------------- | -| 1 | TTS 中按键后 500ms 内无残余播报 | 短按+cancel | 长按 `ptt_begin` | -| 2 | `AI_audio_queue` 深度为 0 | `VC_init` 后 `[VC] init audio_queue` | 同左 | -| 3 | 开录前已 `started` | 是 | 否则 `audio.create` SKIP | -| 4 | 开录提示音不叠按键音 | 短按提示音已关 | `ptt_begin` 内不叠短嘟 | -| 5 | 打断后能快速第二轮 | `canceled`→开麦 | 松手→播完→再长按 | -| 6 | 串口日志 | `[KEY]`、`[FSM]`、`[VC][proto]` | 同左 | - - -### 5.2 日志关键字(原 E12) - - -| 日志 | 含义 | -| ------------------------------------------------ | ------------------------- | -| `[KEY] AI_key_press VC_mode=` | 按键模式与 FSM 快照 | -| `[PTT] cancel before new uplink` | PTT 长按前已发 cancel | -| `[PTT] wait server.started` | 等 started 后再 audio.create | -| `[VC][proto] audio.create send` / `SKIP` | PTT 开轮是否成功 | -| `[VC][uplink_ctrl] Request START` / `Deny START` | 长对话开麦门控 | -| `[FSM] server.canceled` | 打断成功,长对话可续麦 | -| `[VC] init audio_queue` | 清播放队列成功 | - - -### 5.3 调试 API - -`EventMesh.publish("get_led_debug_state")` → `{ ai, charging, battery, signal, mode, period_ms }` - ---- - -## 6. 引用与场景索引 - - -| 文档 | 路径 | -| -------- | ------------------------------------------------------------------- | -| 需求规范 | [交互规范_new.md](./AI吊坠(双按键+三色指示灯)交互规范_new.md) | -| 场景详设 | [详设-场景与协议流程.md](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md) | -| 源码 | `2.sdk/Helios_SDK/services/microPython/ports/quectel/core/ai_VC.py` | -| 旧附录(已迁移) | [交互规范_附录-工程与代码审查.md](./AI吊坠(双按键+三色指示灯)交互规范_附录-工程与代码审查.md) | - - -### 6.1 场景详设索引(`DES-SCN-`*) - - -| ID | 内容 | -| ----------- | --------------------------- | -| DES-SCN-000 | 场景速查与索引 | -| DES-SCN-001 | 模式总览 | -| DES-SCN-002 | 协议消息语义 | -| DES-SCN-003 | 打断 TTS 本地清缓存顺序 | -| DES-SCN-010 | 长对话 AI 键(含 010.2~010.7 子场景) | -| DES-SCN-011 | 长对话打断 TTS 时序图 | -| DES-SCN-020 | 单对话 PTT(含 020.2~020.8) | -| DES-SCN-030 | 与 Power 键、模式切换边界 | -| DES-SCN-050 | 服务端事件对照 | - - +# AI吊坠(双按键+三色指示灯)详设 — 对照与决策 + +> **需求文档**:[交互规范_new](./AI吊坠(双按键+三色指示灯)交互规范_new.md)(产品行为准绳) +> **场景详设**:[详设-场景与协议流程](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)(按键/协议步骤展开) +> **实现真源**:`2.sdk/Helios_SDK/services/microPython/ports/quectel/core/ai_VC.py`(`AI_led`、`AI_hw_status`、`AI_dev`) + +--- + +## 0. 如何使用本文档 + +### 0.1 三角对照 + + +| 角 | 文档 | 回答的问题 | +| ------ | ------------------------------ | -------- | +| **需求** | `交互规范_new.md` + `REQ-`* | 用户要什么? | +| **设计** | 本文第 2 ç«  `DES-`*、场景 `DES-SCN-`* | 固件应怎么做? | +| **实现** | `ai_VC.py` 等 | 代码现在怎么做? | + + +评审流程:**第 3 章矩阵** 标 `状态` → 不一致项查 **第 4 ç«  GAP** → 在 **决策** 列填 `采纳甲` / `采纳乙` / `搁置` / `改需求` → 再改代码或改需求,避免三方漂移。 + +### 0.2 准绳优先级 + +1. 你已勾选的 GAP **决策**(最高) +2. 需求文档(产品对外承诺) +3. 本文设计规格(工程应然) +4. 当前代码(现状,直至按决策修改) + +### 0.3 要点摘要(评审速览) + +- **长对话**:短按打断 TTS / **思考中** → `RequestToSpeak` → `VC_init` → `cancel` → `canceled` → `uplink_start`(见 `DES-SCN-010.2`~`010.4`、`DES-SCN-011`)。 +- **单对话**:长按开录 / 松手 `audio.completed`;TTS 中短按仅停播,续聊须再长按(见 `DES-SCN-020.6`)。 +- **待机灯**:正常待机 **灭灯**(`LED_IDLE_MODE=off`,GAP-005 方案甲)。 +- **电量阈值**:低电 `soc<30%`、空电 `soc<10%`(GAP-007 方案甲)。 +- **异常灯**:`set_led_state.alert=rb_flash_2` 红蓝快闪 2 次后回表(GAP-006 已落实 ASR 空结果、thinking 超时)。 + +--- + +## 1. 系统架构(一页) + +```mermaid +flowchart TB + gpio[GPIO_btn_device] + dev[AI_dev_去抖串行] + vc[AI_VC_按键与VCStateMachine] + ws[WebSocket_V2_5] + aud[录音播放队列] + led[AI_led] + hw[AI_hw_status] + gpio -->|EventMesh| dev + dev -->|AI_key_press等| vc + vc --> ws + vc --> aud + vc -->|set_led_state| led + hw -->|set_led_state| led +``` + + + +### 1.1 模块职责 + + +| 模块 | 文件 | 职责 | +| ---------------- | ---------- | ------------------------------------------ | +| `AI_dev` | `ai_VC.py` | 按键 ExtInt、去抖、`publish_AI_btnInfo` 串行执行 | +| `AI_VC` | `ai_VC.py` | WebSocket 会话、按键路由、音频上下行 | +| `VCStateMachine` | `ai_VC.py` | `session` / `turn` / `tts_rx_phase` 唯一轮次真源 | +| `AI_hw_status` | `ai_VC.py` | 10s 轮询 + `hw_usb_state` → 充电/电量/信号 | +| `AI_led` | `ai_VC.py` | `set_led_state` 聚合 → GPIO 灯效 | + + +### 1.2 EventMesh 主题(常用) + + +| 主题 | 发布方 | 订阅方 | 说明 | +| ------------------------------------------------------- | ---------------------- | -------------- | ------------------- | +| `AI_key_press` / `AI_key_long_press` / `AI_key_release` | `AI_dev` | `AI_VC` | AI 键 | +| `pwk_key_double_press` | 电源键模块 | `AI_VC` | Power 双击切 `VC_mode` | +| `set_led_state` | `AI_VC`、`AI_hw_status` | `AI_led` | LED 唯一入口 | +| `hw_usb_state` | 底层 | `AI_hw_status` | USB 插拔即时刷新 | +| `get_led_debug_state` | 调试 | `AI_led` | 返回聚合灯态 | + + +### 1.3 设计原则(文档化) + +- 轮次/会话判断只读 `fsm.*`,不引入并行整型状态。 +- 打断 TTS:**先** `VC_init`(本地停播清队列)**再** `cancel` / `audio.create`(见 `DES-SCN-003`)。 +- LED 只经 `set_led_state`;AI 阶段灯优先于充电/电量(见 `DES-L3-01`)。 + +--- + +## 2. 设计规格(按层) + +### 2.1 L1 输入与按键(`DES-L1`) + + +| ID | 规格 | 实现锚点 | +| --------- | ----------------------------------------- | ------------------------------------------------ | +| DES-L1-01 | 长对话:AI **短按** 唤醒/打断/续聊 | `AI_key_press` → `_ai_key_press_long_dialogue_`* | +| DES-L1-02 | 单对话:AI **长按** 开录、**松开** `audio.completed` | `ptt_begin`、`_ai_key_release_handle_ptt` | +| DES-L1-03 | 单对话:TTS 中 **短按** 仅停播,不开录 | `_ai_key_press_ptt_mode` | +| DES-L1-04 | Power **双击** 切换 `VC_mode` å¹¶ TTS 播报 | `pwk_key_double_press` | +| DES-L1-05 | Power 交互中 **短按** `Close` 断会话进待机 | `pwk_key_press` 等 | + + +### 2.2 L2 会话与协议(`DES-L2`) + + +| ID | 规格 | 实现锚点 | +| --------- | ------------------------------------------------------- | ------------------------------------------ | +| DES-L2-01 | `VC_mode=0`:VAD 开,一般无 `audio.create`/`completed` | `VCMode.Realtime` | +| DES-L2-02 | `VC_mode=1`:VAD 关,必须 `audio.create`→帧→`audio.completed` | `VCMode.PushToTalk` | +| DES-L2-03 | 会话层:`Disconnected`→`Connecting`→`Starting`→`Started` | `VCSessionState` | +| DES-L2-04 | 轮次层:`Idle`→`Listening`→…→`Playing`→续轮 | `VCTurnState`、`VCStateMachine` | +| DES-L2-05 | 长对话打断 TTS:`cancel`→`canceled`→`uplink_start` | `RequestToSpeak`、`on_server_canceled` | +| DES-L2-06 | 长对话播完门控:`audio.played` 后可自动开麦 | `fsm.await_played`、`on_local_audio_played` | + + +步骤级展开见 [场景详设](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)。 + +### 2.3 L3 呈现:灯 / 音 / 硬件态(`DES-L3`) + +#### DES-L3-01 LED 优先级(`AI_led._apply_by_table`) + + +| 优先级 | 输入 | 取值 | 灯效 | `period_ms` | +| --- | ---------- | ------------- | ----- | ------------------------- | +| P1 | `ai_state` | `playing` | 绿常亮 | — | +| P2 | `ai_state` | `thinking` | 蓝绿交替 | 500 | +| P3 | `ai_state` | `listening` | 蓝慢闪 | 1000 | +| B1 | `charging` | `full` | 绿常亮 | — | +| B2 | `charging` | `charging` | 红常亮 | — | +| B3 | `battery` | `low`/`empty` | 红慢闪 | 1000 | +| B4 | `signal` | `weak` | 蓝绿慢交替 | 1000 | +| 默认 | — | `idle` | **灭灯** | `LED_IDLE_MODE=off`(可选 `green_blink`) | +| P0 | `alert` | `rb_flash_2` | 红蓝快闪 2 次 | `250`(约 2 次/秒)后回表 | + + +`set_led_state` 键:`ai_state` / `charging` / `battery` / `signal` / `alert`。 + +#### DES-L3-02 硬件态采样(`AI_hw_status`) + + +| USB | SoC(非充电) | `charging` | `battery` | +| --- | -------- | ----------------- | ---------- | +| 否 | ≥30% | `none` | `normal` | +| 否 | 10%~30% | `none` | `low` | +| 否 | <10% | `none` | `empty` | +| 是 | — | `charging`/`full` | 不按 SoC 刷低电 | + + +弱网:`0 ≤ CSQ < SIGNAL_WEAK_CSQ`(默认 10)→ `signal=weak`。 + +#### DES-L3-03 灯与 FSM 对应 + + +| `ai_state` | 典型触发 | +| ----------- | ------------------- | +| `listening` | 开麦、续聊 | +| `thinking` | `llm.created` | +| `playing` | `tts.started` / 本地播 | +| `idle` | 交互结束、异常恢复 | + + +--- + +## 3. 需求 — 设计 — 实现对照矩阵 + + +| REQ-ID | 需求摘要 | 设计规格 | 实现锚点 | 状态 | GAP-ID | +| ----------- | ------------------------- | ----------------------- | ---------------------------- | ----- | ------- | +| REQ-PWR-01 | 关机时长按 Power 3s 开机,绿灯常亮 3s | (电源模块) | 电源键 / `ui` | 需求未定义 | — | +| REQ-PWR-02 | 死机长按 8s 强制关机,无灯无音 | (电源模块) | 电源键 | 需求未定义 | — | +| REQ-PWR-03 | 待机短按 Power 进休眠,无灯 | DES-L1-05 | `pm.autosleep` 等 | 部分一致 | — | +| REQ-PWR-04 | AI 交互中短按 Power 停对话进待机,绿慢闪 | DES-L1-05 | `Close` | 部分一致 | — | +| REQ-PWR-05 | Power 双击切换单/长对话并播报 | DES-L1-04 | `pwk_key_double_press` | 一致 | — | +| REQ-AI-01 | 长对话待机短按:蓝慢闪+滴,开麦 | DES-L1-01、DES-SCN-010.5 | `_ai_key_press_long_dialogue_wake`→`AI_VC_start` | 一致 | GAP-002 | +| REQ-AI-02 | 长对话聆听中短按:重开麦 | DES-SCN-010.3 | `request_uplink_start` | 一致 | — | +| REQ-AI-03 | 长对话 TTS 中短按:打断并聆听 | DES-SCN-010.2 | `_ai_key_press_long_dialogue_interrupt` | 一致 | — | +| REQ-AI-04 | 长对话思考中短按:打断并聆听 | DES-SCN-010.4 | `_ai_key_press_long_dialogue_interrupt` | 一致 | GAP-001 | +| REQ-AI-05 | 单对话 TTS 中短按:仅停播 | DES-L1-03、DES-SCN-020.3 | `_ai_key_press_ptt_mode` | 一致 | — | +| REQ-AI-06 | 单对话非 TTS 短按:无操作 | DES-L1-03 | `return True` 吞掉 | 一致 | GAP-003 | +| REQ-AI-07 | 单对话长按:蓝快闪+开录音 | DES-L1-02、DES-SCN-020.2 | `ptt_begin` | 一致 | — | +| REQ-AI-08 | 单对话松手:思考灯+层音+completed | DES-L1-02 | `AI_client_VC_end_speech` | 一致 | — | +| REQ-BAT-01 | 正常待机灯灭 | DES-L3-01 默认 | `_set_off`(`LED_IDLE_MODE=off`) | 一致 | GAP-005 | +| REQ-BAT-02 | 低电 10%~30% 红慢闪+双滴 | DES-L3-02 | `battery=low`(SoC<30%) | 一致 | GAP-007 | +| REQ-BAT-03 | 电量<10% 红快闪 3 次后关机 | DES-L3-02 | `battery=empty`(SoC<10%) | 一致 | GAP-007 | +| REQ-BAT-04 | 充电中红常亮+æ»´ | DES-L3-02 | `charging=charging` | 一致 | GAP-008 | +| REQ-BAT-05 | 充满红→绿常亮+长滴 | DES-L3-02 | `charging=full` | 一致 | — | +| REQ-ERR-01 | ASR 失败:红蓝快闪 2 次→待机灭 | DES-L3 P0 `alert` | `_vc_led_alert_rb_flash`(asr 空) | 一致 | GAP-006 | +| REQ-ERR-02 | 网络异常:蓝绿慢交替+语音循环 | DES-L3-02 B4 | `websocket_error`、`bg_alt` | 部分一致 | GAP-006 | +| REQ-ERR-03 | AI 超时:蓝常亮→红蓝闪→灭 | DES-L3 P0 `alert` | `thinking_timeout`→`alert` | 部分一致 | GAP-006 | +| REQ-NOTE-01 | 备注:会话空闲后进入休眠前灯态 | DES-L3 默认灭灯;可选绿闪 | `LED_IDLE_MODE` | 已对齐 part3 | GAP-005 | +| REQ-NOTE-02 | 备注:聆听蓝闪、思考交替、播放绿闪 | DES-L3-01 P2/P3/P1 | `set_led_state` | 部分一致 | — | +| REQ-NOTE-03 | 休眠无灯光 | (休眠策略) | `ui.py` / `pm` | 部分一致 | — | +| REQ-SUP-01 | 充电中 AI 交互优先 AI 灯 | DES-L3-01 | `_apply_by_table` | 一致 | GAP-008 | +| REQ-SUP-02 | 按键后灯音延迟≤100ms | DES-SCN-003 | `VC_init` 优先 | 一致 | — | + + +--- + +## 4. 差异登记簿(GAP) + +> **决策**列请产品/固件填写:`采纳甲` | `采纳乙` | `搁置` | `改需求` + + +| GAP-ID | 需求 | 设计目标 | 实现现状 | 风险 | 方案甲:架构精简·安全·实用 | 方案乙:改动最小 | 决策 | 影响面 | +| ------- | --------------------- | ------------------ | ---------------------------------------------- | --------- | ----------------------------------------------- | -------------------------------------- | -------------------------------- | -------------------------------------- | +| GAP-001 | REQ-AI-04 | 思考中短按统一打断并开麦 | 仅 TTS 忙走 `cancel`;纯 `Thinking` 可能 `Deny START` | 用户按了没反应 | `turn==Thinking` èµ° `RequestToSpeak`→`cancel`→开麦 | 详设标注限制;或单行门控热修 | **采纳甲**(已改代码) | `AI_key_press`、`_ai_key_press_long_dialogue_interrupt` | +| GAP-002 | REQ-AI-01 | 待机短按直达唤醒 | 兜底 `Close`+`AI_VC_start`+`sleep(500)` | 唤醒慢/偶发断链感 | 去掉兜底 `Close`;未连接单一路径 `AI_VC_start` | 保留现状,联调看 `[KEY]` | **采纳甲**(已改代码) | `AI_key_press`、`_ai_key_press_long_dialogue_wake` | +| GAP-003 | REQ-AI-06 | 单对话非 TTS 短按无操作 | 非播放态 `return True` 吞掉 | 低(防误触) | 保持为设计,REQ 已对齐 | 若需短按开录:改 `_ai_key_press_ptt_mode`+改需求表 | **采纳甲** | `_ai_key_press_ptt_mode` | +| GAP-005 | REQ-BAT-01 vs NOTE-01 | part3 灯灭 vs 备注绿灯慢闪 | idle 默认 `green_blink` | 产品表述冲突 | `AI_led` idle 灭灯 | **改需求** part3 为绿灯慢闪 | **采纳甲**(`LED_IDLE_MODE=off`) | `AI_led._apply_by_table` | +| GAP-006 | REQ-ERR-01~03 | 红蓝快闪等专用灯序 | 无 `alert` 模式;TTS/弱网替代 | 异常辨识度弱 | 新增 `alert` 键+优先级+业务触发 | 需求降级为语音+弱网灯;接受现状 | **采纳甲**(ASR 空、thinking 超时已接 alert) | `AI_led`、`ai_VC` 异常分支 | +| GAP-007 | REQ-BAT-02~03 | 10%/30% 阈值 | SoC 5%/20% 工程档 | 提醒时机偏差 | `AI_hw_status` 阈值可配置并对齐需求 | 需求脚注「以 OCV/工程档为准」 | **采纳甲**(30%/10%) | `default_config`、`AI_hw_status` | +| GAP-008 | REQ-BAT-04、SUP-01 | 充电红常亮 vs AI 覆盖 | AI 非 idle 盖住充电灯 | 充电中不易见红常亮 | 保持 AI 优先(交互反馈优先) | 充电中插入充电指示(需产品确认) | **采纳甲** | `AI_led` 优先级 | + + +### 4.1 整体姿态对比(选默认路线) + + +| 维度 | 姿态 A:架构精简·安全·实用 | 姿态 B:改动最小 | +| ------ | -------------------- | ------------------ | +| 目标 | 需求↔实现长期一致 | 冻结现状,文档吸收差异 | +| LED/异常 | 倾向 GAP-005/006 **甲** | 倾向 **乙**(改需求或接受现状) | +| 按键/FSM | 倾向 GAP-001/002 **甲** | 倾向 **乙**(标注已知限制) | +| 代码工作量 | 中~高 | 低(0~2 处热修) | + + +**建议**:先填齐上表 **决策** 列,再批量改需求或 `ai_VC.py`。 + +### 4.2 GAP-001:为何 `RequestToSpeak` 必须先 `cancel` 再开麦 + +长对话在 `turn==Thinking` 或 TTS 播放中,若直接 `uplink_start`,`_uplink_request_start` 会因 `turn` 非 `Listening/SpeechEnded` 而 **Deny START**;若先开麦再 `cancel`,本地/服务端旧轮下行可能与新一轮上行竞态。 + +**方案甲时序(与 DES-SCN-010.2/010.4 一致)**: + +1. 短按 → `AI_client_VC_RequestToSpeak`:`VC_init` 停播清队列 + WebSocket 发 `cancel`。 +2. 服务端 `server.canceled` → `on_server_canceled` 将 `turn` 置为 `Listening`。 +3. `on_server_event("canceled")` 追加 `uplink_start` → 开麦、蓝慢闪。 + +因此「cancel 在后」是指 **开麦动作在 canceled 事件之后**,而非不发 cancel。 + +--- + +## 5. 联调索引 + +### 5.1 检查清单(原 E8) + + +| # | 检查项 | 长对话 | 单对话 | +| --- | ---------------------- | ----------------------------------- | ---------------------- | +| 1 | TTS 中按键后 500ms 内无残余播报 | 短按+cancel | 长按 `ptt_begin` | +| 2 | `AI_audio_queue` 深度为 0 | `VC_init` 后 `[VC] init audio_queue` | 同左 | +| 3 | 开录前已 `started` | 是 | 否则 `audio.create` SKIP | +| 4 | 开录提示音不叠按键音 | 短按提示音已关 | `ptt_begin` 内不叠短嘟 | +| 5 | 打断后能快速第二轮 | `canceled`→开麦 | 松手→播完→再长按 | +| 6 | 串口日志 | `[KEY]`、`[FSM]`、`[VC][proto]` | 同左 | + + +### 5.2 日志关键字(原 E12) + + +| 日志 | 含义 | +| ------------------------------------------------ | ------------------------- | +| `[KEY] AI_key_press VC_mode=` | 按键模式与 FSM 快照 | +| `[PTT] cancel before new uplink` | PTT 长按前已发 cancel | +| `[PTT] wait server.started` | 等 started 后再 audio.create | +| `[VC][proto] audio.create send` / `SKIP` | PTT 开轮是否成功 | +| `[VC][uplink_ctrl] Request START` / `Deny START` | 长对话开麦门控 | +| `[FSM] server.canceled` | 打断成功,长对话可续麦 | +| `[VC] init audio_queue` | 清播放队列成功 | + + +### 5.3 调试 API + +`EventMesh.publish("get_led_debug_state")` → `{ ai, charging, battery, signal, mode, period_ms }` + +--- + +## 6. 引用与场景索引 + + +| 文档 | 路径 | +| -------- | ------------------------------------------------------------------- | +| 需求规范 | [交互规范_new.md](./AI吊坠(双按键+三色指示灯)交互规范_new.md) | +| 场景详设 | [详设-场景与协议流程.md](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md) | +| 源码 | `2.sdk/Helios_SDK/services/microPython/ports/quectel/core/ai_VC.py` | +| 旧附录(已迁移) | [交互规范_附录-工程与代码审查.md](./AI吊坠(双按键+三色指示灯)交互规范_附录-工程与代码审查.md) | + + +### 6.1 场景详设索引(`DES-SCN-`*) + + +| ID | 内容 | +| ----------- | --------------------------- | +| DES-SCN-000 | 场景速查与索引 | +| DES-SCN-001 | 模式总览 | +| DES-SCN-002 | 协议消息语义 | +| DES-SCN-003 | 打断 TTS 本地清缓存顺序 | +| DES-SCN-010 | 长对话 AI 键(含 010.2~010.7 子场景) | +| DES-SCN-011 | 长对话打断 TTS 时序图 | +| DES-SCN-020 | 单对话 PTT(含 020.2~020.8) | +| DES-SCN-030 | 与 Power 键、模式切换边界 | +| DES-SCN-050 | 服务端事件对照 | + +