-# 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