补充漏提交文档
authorSnickerSun <snickersun@163.com>
Sun, 17 May 2026 16:24:12 +0000 (00:24 +0800)
committerSnickerSun <snickersun@163.com>
Sun, 17 May 2026 16:24:12 +0000 (00:24 +0800)
1.doc/AI吊坠(双按键+三色指示灯)详设-对照与决策.md

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