From: snickersun Date: Mon, 18 May 2026 03:27:54 +0000 (+0800) Subject: 需求状态与设计实现文档整理 X-Git-Url: http://git.snicker.com.cn/css/static/gitweb.css?a=commitdiff_plain;h=ceb907be9c2b9ad785ecb81df43f79f952ff7d4d;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\344\272\244\344\272\222\350\247\204\350\214\203-\346\226\260\346\227\247\345\217\230\346\233\264\350\257\264\346\230\216.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\344\272\244\344\272\222\350\247\204\350\214\203-\346\226\260\346\227\247\345\217\230\346\233\264\350\257\264\346\230\216.md" new file mode 100644 index 00000000..d5eb29e8 --- /dev/null +++ "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\344\272\244\344\272\222\350\247\204\350\214\203-\346\226\260\346\227\247\345\217\230\346\233\264\350\257\264\346\230\216.md" @@ -0,0 +1,110 @@ +# AI吊坠(双按键+三色指示灯)交互规范 — 新旧变更说明 + +> **对比范围** +> - 旧版:[交互规范.md](./AI吊坠(双按键+三色指示灯)交互规范.md) +> - 新版:[交互规范_new.md](./AI吊坠(双按键+三色指示灯)交互规范_new.md) +> +> **说明**:下列仅列**产品行为 / 规则**差异。新增 REQ-ID 编号、LED `period_ms` 术语表、详设链接、实现状态摘要等**文档结构**不计入变更。 + +--- + +## 1. 基础约定 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| 按键分工 | 短按/双击均可用于唤醒、打断、**复读** | 短按 = 唤醒/打断;**仅 Power 双击**切换单/长对话;**取消 AI 双击业务** | + +--- + +## 2. 备注 / 待机 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| 正常待机 | 未单独约定 | 待机**指示灯灭**;约 **2 分钟**无交互进入**休眠**(休眠无灯、无音) | +| 播放灯 | 备注写「绿灯长亮」 | 统一为 TTS 时**绿灯常亮**(去掉易误解的「绿闪」表述) | + +--- + +## 3. Power 键 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| 长按 8s 强关 | **红快闪 3 次** + **三声短滴** 后关机 | **无灯、无提示音**,直接关机 | +| 待机短按 | **无操作**(灯、音均无变化) | **进入休眠模式** | +| AI 交互中短按 | 停对话进待机,灯**保持当前交互状态** | 停对话后进待机,灯**熄灭**(与正常待机灭灯一致) | +| 双击切模式 | 仅在**待机**下切换单/长对话 | **任意状态**可双击;若正在对话则**先停对话**再设模式并进待机 | + +--- + +## 4. AI 键 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| AI 双击复读 | 可选:TTS 结束后 1 分钟内双击,**复读上一轮 TTS** | **删除**该能力 | +| 单对话 + TTS 中短按 | 未单独规定 | **仅停播**,灯灭 idle;续聊须**再长按** | +| 单对话 + 非 TTS 短按 | 未单独规定 | **短按无效**(吞掉);开录只能**长按** | +| 单对话长按(松开) | 「曾——」约 1 秒长音,进入思考 | 「**层**」+ 蓝绿交替,协议 **`audio.completed`** 结束上行 | + +**未变更**:长对话下四条短按(待机 / 聆听 / TTS 播报 / 思考中 → 打断并开麦),新旧行为一致。 + +--- + +## 5. 电量 / 充电 + +**无实质行为变更**(低电 10%~30%、空电 <10%、充电红常亮、充满红→绿等与旧版一致)。 + +--- + +## 6. 异常 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| 网络异常 | 固定:蓝绿慢交替 + 「网络异常信号弱」**每 5 秒循环** | **分两种**:信号弱(CSQ)→ 蓝绿慢交替;**连接失败** → 以 **TTS 提示**为主;弱网灯由硬件状态采样 | +| AI 处理超时 | **先蓝常亮**,再红蓝快闪 2 次,再待机灭灯 | **思考阶段长时间无 TTS**:直接红蓝快闪 2 次,**重启会话**后待机灭灯(**不再要求**超时前先蓝常亮) | + +**未变更**:语音识别失败 → 红蓝快闪 2 次 → 待机灭灯,新旧一致。 + +--- + +## 7. 补充规范 + +| 变更 | 旧版 | 新版 | +|------|------|------| +| 误触 / 双击 | 已写「AI 无双击」 | 明确 **Power 双击**为唯一模式切换入口(与删除 AI 复读、单对话短按规则一致) | + +--- + +## 8. 变更项汇总(12 条) + +| # | 类别 | 变更摘要 | +|---|------|----------| +| 1 | 约定 | 取消 AI 双击及「复读」定位 | +| 2 | 待机 | 待机灭灯 + 约 2 分钟无交互进休眠(休眠无灯无音) | +| 3 | Power | 8s 强关:红闪+三声 → 无灯无声 | +| 4 | Power | 待机短按:无操作 → 进休眠 | +| 5 | Power | 交互中短按停对话:灯保持 → **熄灭** | +| 6 | Power | 双击切模式:仅待机 → 任意状态且可先停对话 | +| 7 | AI | 删除双击复读 TTS | +| 8 | AI | 单对话 TTS 中短按:仅停播 | +| 9 | AI | 单对话非 TTS 短按:无效,须长按开录 | +| 10 | AI | 单对话松手:「曾——」→「层」+ audio.completed | +| 11 | 异常 | 网络异常:单一描述 → CSQ 灯效 vs 断连 TTS | +| 12 | 异常 | AI 超时:去掉蓝常亮前置,改为思考超时红蓝闪+重启会话 | + +--- + +## 9. 不计入「新旧变更」的说明 + +| 话题 | 说明 | +|------|------| +| **开录专用提示音** | 旧版表内单对话长按为「滴」,**未**要求必须播放 `start.mp3`;备注附件为可选资源。工程 `RECORD_START_TONE_FILE=None` 为产品配置,**不是**相对旧版需求表的变更。 | +| **收音灯快慢闪** | 长对话聆听 **蓝慢闪**、单对话 **蓝快闪** 旧版表中已有(长对话各行 + 单对话长按行),新版在文首与 REQ-NOTE-02 **显式归纳**,属表述补全,非行为变更。 | + +--- + +## 相关文档 + +| 文档 | 说明 | +|------|------| +| [详设-对照与决策.md](./AI吊坠(双按键+三色指示灯)详设-对照与决策.md) | 需求—设计—实现矩阵;已实现 **IMP**、开放 **GAP** | +| [交互规范_new.md](./AI吊坠(双按键+三色指示灯)交互规范_new.md) | 当前产品需求正文(准绳) | 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\344\272\244\344\272\222\350\247\204\350\214\203_new.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\344\272\244\344\272\222\350\247\204\350\214\203_new.md" index a646477e..e5473187 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\344\272\244\344\272\222\350\247\204\350\214\203_new.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\344\272\244\344\272\222\350\247\204\350\214\203_new.md" @@ -31,21 +31,30 @@ | **慢交替/交替慢闪** | 约 **1 s 换一色** | `1000` | -**工程映射(默认)**:聆听蓝 **慢闪**、低电红 **慢闪**、正常待机 **灭灯**(`LED_IDLE_MODE=off`)→ 聆听/低电 `1000`;思考蓝绿 **交替** → `500`;弱网蓝绿 **慢交替** → `1000`;异常红蓝快闪 → `250`(约 2 次/秒)。正文若写「快闪 / 2 次/秒」等,表示周期短于「闪」,工程可按场景单独设 `period_ms`,与上表不冲突。 +**工程映射(默认)**:低电红 **慢闪**、正常待机 **灭灯**(`LED_IDLE_MODE=off`)→ `1000`;思考蓝绿 **交替** → `500`;弱网蓝绿 **慢交替** → `1000`;异常红蓝快闪 → `250`(约 2 次/秒)。 + +**收音态 `listening`(按对话模式区分,与代码一致)**: + +| 对话模式 | 灯效 | 默认 `period_ms` | 说明 | +| -------- | ---- | ---------------- | ---- | +| 长对话 | 蓝 **慢闪**(约 1 次/秒) | `1000` | 短按唤醒/打断后进聆听、VAD 开麦 | +| 单对话 | 蓝 **快闪**(约 2 次/秒) | `250` | 长按开录至松手前 | + +开录阶段**不以专用提示音表示**(`RECORD_START_TONE_FILE=None`);仅用上述灯效区分模式。正文若写「快闪 / 2 次/秒」等,表示周期短于「闪」,工程可按场景单独设 `period_ms`,与上表不冲突。 ## 备注 | REQ-ID | 说明 | | ------ | --- | | REQ-NOTE-03 | 休眠模式:无灯光,无提示音(最低电量消耗) | -| REQ-NOTE-02 | 聆听模式:蓝灯闪(1 分钟内无交互,自动进入待机模式) | +| REQ-NOTE-02 | 聆听/收音:长对话 **蓝慢闪**;单对话 **蓝快闪**(见文首「收音态 listening」) | | REQ-NOTE-02 | 思考模式:蓝绿交替闪 | -| REQ-NOTE-02 | 播放模式:绿灯闪 | +| REQ-NOTE-02 | 播放模式:绿灯常亮(TTS 播报,`ai_state=playing`) | | REQ-NOTE-01 | 正常待机(part3):指示灯灭;2 分钟无交互进入休眠(REQ-NOTE-03)。旧工程绿灯慢闪可通过 `LED_IDLE_MODE=green_blink` 恢复 | -进入聆听模式:单声“滴”(短促) +进入聆听模式(长对话短按唤醒等):可用短促「滴」作操作确认(与**开录专用提示音**无关;本产品线开录仅以灯提示,`RECORD_START_TONE_FILE` 关闭)。 -[请至钉钉文档查看附件《start.mp3》。](https://alidocs.dingtalk.com/i/nodes/KGZLxjv9VGj15aBlU1wKrXGzW6EDybno?iframeQuery=anchorId%3DX02moo4wrj78r6ita1utoy&utm_scene=person_space) +附件《start.mp3》为历史/可选资源,**非**强制开录提示音。 接入拾音/进入思考:单声“层”(短促,有尾音) @@ -63,7 +72,7 @@ | REQ-PWR-01 | Power键 长按3秒 | 关机状态 | 绿色灯常亮(持续3秒,同步长按时间),然后熄灭 | 现有设备开机提示音(后续视需求可修改) | 设备开机,进入正常待机状态 | | REQ-PWR-02 | Power键 长按8秒 | 任何状态(死机/卡死/异常) | 无变化 | 无提示音 | 设备关机,切断所有电源 | | REQ-PWR-03 | Power键 短按(单击) | 待机状态 | 无指示灯 | 无提示音 | 进入休眠模式 | -| REQ-PWR-04 | Power键 短按(单击) | AI交互中(聆听/处理/TTS) | 绿色慢闪 | 无提示音 | 停止对话,进入待机模式 | +| REQ-PWR-04 | Power键 短按(单击) | AI交互中(聆听/处理/TTS) | 指示灯灭(进入 idle,与 REQ-BAT-01 一致) | 无提示音 | 停止对话(`Close`),进入待机模式 | | REQ-PWR-05 | Power键 短按(双击) | 待机状态(任意状态) | 无变化 | 播报:单对话模式/长对话模式 | 如果对话时停止对话,设置对话模式,进入待机模式, 非对话模式,设置对话模式直接进入待机模式 | @@ -78,7 +87,7 @@ | REQ-AI-04 | AI键 短按1次 | 长对话模式 | 思考中(蓝绿交替闪) | 切换为蓝色慢闪 | 单声“滴”(短促) | 进入语音聆听状态,开始收音(用户可说话) | | REQ-AI-05 | AI键 短按1次 | 单对话模式 | TTS播报中(绿色常亮) | 灯灭→idle | 无(或极短停播) | **仅停播**,不开录;续聊须再 **长按**(见 [DES-SCN-020.3](AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)) | | REQ-AI-06 | AI键 短按1次 | 单对话模式 | 待机/思考/聆听(非TTS播放) | 无变化(短按吞掉) | 无 | 无业务;开录须 **长按**(见 [DES-SCN-020](AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)) | -| REQ-AI-07 | AI键 长按(按下) | 单对话模式 | 待机状态/思考状态/播报状态 | 蓝色快闪(频率加快,2次/秒) | 开录提示音(start.mp3) | 进入收音状态;TTS中重开见 [DES-SCN-020.2](AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md) | +| REQ-AI-07 | AI键 长按(按下) | 单对话模式 | 待机状态/思考状态/播报状态 | 蓝色快闪(约 2 次/秒) | **无开录提示音**(仅以灯表示收音) | 进入收音状态;TTS中重开见 [DES-SCN-020.2](AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md) | | REQ-AI-08 | AI键 长按(松开) | 单对话模式 | 聆听中(蓝快闪) | 蓝绿交替闪 | “层”(接入拾音/思考提示) | 结束上行,进入思考;协议 `audio.completed`(见 [DES-SCN-020.6](AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)) | @@ -100,8 +109,8 @@ | REQ-ID | 异常场景 | 指示灯状态 | 提示音 | 处理方式 | | ------ | ---------------- | ------------------------ | ------------------- | -------------------- | | REQ-ERR-01 | 语音识别失败(未听清/无法识别) | 红蓝快闪2次(2次/秒)→ 回到待机状态(灯灭) | “滴、滴”(2声短促,与灯光同步) | 用户可再次短按AI键,重新唤醒聆听 | -| REQ-ERR-02 | 网络异常(无法请求AI) | 蓝绿交替慢闪(1次/2秒),持续闪烁 | “网络异常信号弱”(每5秒1次,循环) | 检查网络连接,恢复网络后自动回到待机状态 | -| REQ-ERR-03 | AI处理超时 | 蓝色常亮→红蓝快闪2次→回到待机状态(灯灭) | “滴、滴”(2声短促) | 处理失败,用户可重新发起语音请求 | +| REQ-ERR-02 | 网络异常(无法请求AI) | CSQ 弱时蓝绿慢交替(`signal=weak`);连接失败时以 TTS 提示为主 | “网络异常/信号弱”类提示(`xinhaoruo1` 等,可循环) | 恢复网络后重连;弱网灯由 `AI_hw_status` 采样 | +| REQ-ERR-03 | AI处理超时(思考阶段无 TTS) | 红蓝快闪 2 次(2次/秒)→ 重启会话后待机灭灯 | “滴、滴”(2声短促,可选) | `thinking_timeout` 触发 `alert` 后 `AI_VC_start`;用户可重新发起语音 | ## 第五部分:补充规范(工程&用户体验) @@ -137,7 +146,21 @@ | 文档 | 用途 | | --- | --- | -| **[详设-对照与决策.md](./AI吊坠(双按键+三色指示灯)详设-对照与决策.md)** | 架构、需求-设计-实现矩阵、GAP 双轨决策(**评审入口**) | +| **[交互规范-新旧变更说明.md](./AI吊坠(双按键+三色指示灯)交互规范-新旧变更说明.md)** | 相对旧版 `交互规范.md` 的**实质行为变更**(不含 REQ-ID 等结构差异) | +| **[详设-对照与决策.md](./AI吊坠(双按键+三色指示灯)详设-对照与决策.md)** | 矩阵 §3、**已实现 IMP §4**、开放 GAP §5、状态报告 §8(**评审入口**) | | **[详设-场景与协议流程.md](./AI吊坠(双按键+三色指示灯)详设-场景与协议流程.md)** | 按键/协议步骤、时序图(联调深读) | -上表 `REQ-*` 编号与详设主文档第 3、4 章一一对应。 \ No newline at end of file +上表 `REQ-*` 编号与详设主文档第 3、4 章一一对应。 + +### 实现状态摘要(2026-05-16,需求已按 IMP 决策同步) + +| 类别 | 结论 | +| --- | --- | +| **AI 按键 / 单长对话** | REQ-AI-01~08 已实现(IMP-001~003) | +| **电量 / 待机灯** | REQ-BAT-01~05 已实现(IMP-005/007/008);PWR-04 停对话后灭灯(IMP-009) | +| **灯效措辞** | 播放绿**常亮**、待机**灭灯** 已与需求表对齐(IMP-009/010) | +| **异常灯** | ASR 空、thinking 超时 `rb_flash_2`(IMP-006);弱网见 REQ-ERR-02 开放项 | +| **Power 键** | 双击切模式已实现;3s/8s 开关机在电源模块(非 `ai_VC`) | +| **版本号** | `k8_V1.2_yyyy_MM_dd_HH_mm` + `version_util` frozen + 构建脚本已统一 | + +完整矩阵与 **IMP 实现项** 见 **[详设 §3~§4](./AI吊坠(双按键+三色指示灯)详设-对照与决策.md)**。 \ No newline at end of file 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 fe4ce5ec..b7e854e7 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" @@ -18,22 +18,23 @@ | **实现** | `ai_VC.py` 等 | 代码现在怎么做? | -评审流程:**第 3 章矩阵** 标 `状态` → 不一致项查 **第 4 ç«  GAP** → 在 **决策** 列填 `采纳甲` / `采纳乙` / `搁置` / `改需求` → 再改代码或改需求,避免三方漂移。 +评审流程:**第 3 章矩阵** 标 `状态` → 已关闭差异见 **第 4 ç«  IMP(实现项)** → 仍开放项见 **第 5 ç«  GAP**。 ### 0.2 准绳优先级 -1. 你已勾选的 GAP **决策**(最高) -2. 需求文档(产品对外承诺) -3. 本文设计规格(工程应然) -4. 当前代码(现状,直至按决策修改) +1. 已关闭的 **IMP 决策**(第 4 章,最高) +2. 需求文档 `交互规范_new.md`(已与 IMP 同步) +3. 本文设计规格 `DES-*`(工程应然) +4. 当前代码(开放 GAP 项除外,以 IMP 为准) ### 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 超时)。 +- **长对话**:短按打断 TTS / **思考中** → `RequestToSpeak` → `VC_init` → `cancel` → `canceled` → `uplink_start`(**IMP-001**,见 `DES-SCN-010.2`~`010.4`)。 +- **单对话**:长按开录 / 松手 `audio.completed`;TTS 中短按仅停播(**IMP-003**,见 `DES-SCN-020.6`)。 +- **待机 / 停对话灯**:正常待机与 Power 短按结束对话均为 **灭灯**(**IMP-005/009**)。 +- **播放灯**:TTS 阶段 **绿常亮**(**IMP-010**)。 +- **电量阈值**:低电 `soc<30%`、空电 `soc<10%`(**IMP-007**)。 +- **异常灯**:`alert=rb_flash_2`(**IMP-006**:ASR 空、thinking 超时)。 --- @@ -101,7 +102,7 @@ flowchart TB | 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` 等 | +| DES-L1-05 | Power 交互中 **短按** `Close` 断会话进待机(灯灭) | `_handle_pwk_short_release`→`Close`→`idle` | ### 2.2 L2 会话与协议(`DES-L2`) @@ -168,68 +169,56 @@ flowchart TB ## 3. 需求 — 设计 — 实现对照矩阵 -| REQ-ID | 需求摘要 | 设计规格 | 实现锚点 | 状态 | GAP-ID | +| REQ-ID | 需求摘要 | 设计规格 | 实现锚点 | 状态 | IMP-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-04 | AI 交互中短按 Power 停对话进待机,灯灭 | DES-L1-05 | `Close`→`ai_state=idle` | 一致 | IMP-009 | | 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-01 | 长对话待机短按:蓝慢闪+滴,开麦 | DES-L1-01、DES-SCN-010.5 | `_ai_key_press_long_dialogue_wake`→`AI_VC_start` | 一致 | IMP-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-04 | 长对话思考中短按:打断并聆听 | DES-SCN-010.4 | `_ai_key_press_long_dialogue_interrupt` | 一致 | IMP-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-06 | 单对话非 TTS 短按:无操作 | DES-L1-03 | `return True` 吞掉 | 一致 | IMP-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-01 | 正常待机灯灭 | DES-L3-01 默认 | `_set_off`(`LED_IDLE_MODE=off`) | 一致 | IMP-005 | +| REQ-BAT-02 | 低电 10%~30% 红慢闪+双滴 | DES-L3-02 | `battery=low`(SoC<30%) | 一致 | IMP-007 | +| REQ-BAT-03 | 电量<10% 红快闪 3 次后关机 | DES-L3-02 | `battery=empty`(SoC<10%) | 一致 | IMP-007 | +| REQ-BAT-04 | 充电中红常亮+æ»´ | DES-L3-02 | `charging=charging` | 一致 | IMP-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-ERR-01 | ASR 失败:红蓝快闪 2 次→待机灭 | DES-L3 P0 `alert` | `_vc_led_alert_rb_flash`(asr 空) | 一致 | IMP-006 | +| REQ-ERR-02 | 网络异常:弱网慢交替+语音提示 | DES-L3-02 B4 | `AI_hw_status`/`websocket_error` | 部分一致 | GAP-011 | +| REQ-ERR-03 | 思考超时:红蓝闪→重启/待机灭 | DES-L3 P0 `alert` | `thinking_timeout`→`alert`+`AI_VC_start` | 一致 | IMP-006 | +| REQ-NOTE-01 | 备注:会话空闲后进入休眠前灯态 | DES-L3 默认灭灯;可选绿闪 | `LED_IDLE_MODE` | 一致 | IMP-005 | +| REQ-NOTE-02 | 备注:聆听蓝闪、思考交替、播放绿常亮 | DES-L3-01 P2/P3/P1 | `set_led_state` | 一致 | IMP-010 | | REQ-NOTE-03 | 休眠无灯光 | (休眠策略) | `ui.py` / `pm` | 部分一致 | — | -| REQ-SUP-01 | 充电中 AI 交互优先 AI 灯 | DES-L3-01 | `_apply_by_table` | 一致 | GAP-008 | +| REQ-SUP-01 | 充电中 AI 交互优先 AI 灯 | DES-L3-01 | `_apply_by_table` | 一致 | IMP-008 | | REQ-SUP-02 | 按键后灯音延迟≤100ms | DES-SCN-003 | `VC_init` 优先 | 一致 | — | --- -## 4. 差异登记簿(GAP) +## 4. 已实现决策项(IMP) -> **决策**列请产品/固件填写:`采纳甲` | `采纳乙` | `搁置` | `改需求` +> 原 **GAP-001~010** 均已决策并关闭;需求文档 `交互规范_new.md` 已按下列决策同步(2026-05-16)。 -| 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` 优先级 | +| IMP-ID | 原 GAP | 决策摘要 | 关联 REQ | 落地说明 / 实现锚点 | +| ------- | ------ | ---- | ------ | ------------- | +| IMP-001 | GAP-001 | 采纳甲 | REQ-AI-04 | `turn==Thinking` èµ° `_ai_key_press_long_dialogue_interrupt`→`RequestToSpeak`→`cancel`→开麦 | +| IMP-002 | GAP-002 | 采纳甲 | REQ-AI-01 | `_ai_key_press_long_dialogue_wake` 直接 `AI_VC_start`,去掉 `Close`+`sleep` 兜底 | +| IMP-003 | GAP-003 | 采纳甲 | REQ-AI-06 | 单对话非 TTS 短按 `return True` 吞掉;需求表已写明 | +| IMP-005 | GAP-005 | 采纳甲 | REQ-BAT-01、NOTE-01 | `LED_IDLE_MODE=off`,待机灭灯 | +| IMP-006 | GAP-006 | 采纳甲 + 改需求 | REQ-ERR-01、ERR-03 | `alert=rb_flash_2`;ASR 空、thinking 超时;ERR-03 不再要求「蓝常亮前置」 | +| IMP-007 | GAP-007 | 采纳甲 | REQ-BAT-02、03 | `BATTERY_LOW_SOC_PERCENT=30`、`EMPTY=10` | +| IMP-008 | GAP-008 | 采纳甲 | REQ-BAT-04、SUP-01 | AI 交互灯优先于充电指示 | +| IMP-009 | GAP-009 | **改需求(乙)** | REQ-PWR-04 | 停对话后 **灭灯**(与 BAT-01 一致),非绿慢闪 | +| IMP-010 | GAP-010 | **改需求(乙)** | REQ-NOTE-02 | 播放阶段 **绿常亮**(`playing`→`green_on`),非绿闪 | - -### 4.1 整体姿态对比(选默认路线) - - -| 维度 | 姿态 A:架构精简·安全·实用 | 姿态 B:改动最小 | -| ------ | -------------------- | ------------------ | -| 目标 | 需求↔实现长期一致 | 冻结现状,文档吸收差异 | -| LED/异常 | 倾向 GAP-005/006 **甲** | 倾向 **乙**(改需求或接受现状) | -| 按键/FSM | 倾向 GAP-001/002 **甲** | 倾向 **乙**(标注已知限制) | -| 代码工作量 | 中~高 | 低(0~2 处热修) | - - -**建议**:先填齐上表 **决策** 列,再批量改需求或 `ai_VC.py`。 - -### 4.2 GAP-001:为何 `RequestToSpeak` 必须先 `cancel` 再开麦 +### 4.1 IMP-001:`RequestToSpeak` 必须先 `cancel` 再开麦 长对话在 `turn==Thinking` 或 TTS 播放中,若直接 `uplink_start`,`_uplink_request_start` 会因 `turn` 非 `Listening/SpeechEnded` 而 **Deny START**;若先开麦再 `cancel`,本地/服务端旧轮下行可能与新一轮上行竞态。 @@ -243,9 +232,23 @@ flowchart TB --- -## 5. 联调索引 +## 5. 开放差异(GAP) + +> 仅保留 **未关闭** 或需联调收敛项。新差异请用 GAP-012 起编号。 -### 5.1 检查清单(原 E8) + +| GAP-ID | 关联 REQ | 说明 | 建议 | +| ------- | -------- | --- | --- | +| GAP-011 | REQ-ERR-02 | 弱网:`AI_hw_status` 可驱动 `signal=weak`→蓝绿慢交替;`websocket_error` 以 TTS+重连为主,与「每 5 秒循环弱网语音」表述需联调确认 | 实机测 CSQ<10 与断网两种场景,必要时统一 TTS 间隔文案 | +| — | REQ-PWR-03 | 待机短按进休眠 vs `Close` 路径边界 | 对照 `ui.py`/`pm` 用例 | +| — | REQ-NOTE-03 | 2 分钟无交互进休眠、休眠无灯 | 测 `idle_L2` + `sys_sleep_cb` | +| — | REQ-PWR-01/02 | 3s 开机 / 8s 强关 | 电源模块单独需求,不在 `ai_VC` | + +--- + +## 6. 联调索引 + +### 6.1 检查清单(原 E8) | # | 检查项 | 长对话 | 单对话 | @@ -258,7 +261,7 @@ flowchart TB | 6 | 串口日志 | `[KEY]`、`[FSM]`、`[VC][proto]` | 同左 | -### 5.2 日志关键字(原 E12) +### 6.2 日志关键字(原 E12) | 日志 | 含义 | @@ -272,13 +275,13 @@ flowchart TB | `[VC] init audio_queue` | 清播放队列成功 | -### 5.3 调试 API +### 6.3 调试 API `EventMesh.publish("get_led_debug_state")` → `{ ai, charging, battery, signal, mode, period_ms }` --- -## 6. 引用与场景索引 +## 7. 引用与场景索引 | 文档 | 路径 | @@ -289,7 +292,7 @@ flowchart TB | 旧附录(已迁移) | [交互规范_附录-工程与代码审查.md](./AI吊坠(双按键+三色指示灯)交互规范_附录-工程与代码审查.md) | -### 6.1 场景详设索引(`DES-SCN-`*) +### 7.1 场景详设索引(`DES-SCN-`*) | ID | 内容 | @@ -305,3 +308,41 @@ flowchart TB | DES-SCN-050 | 服务端事件对照 | +--- + +## 8. 实现状态报告(代码审查) + +> **审查基准**:`2.sdk/project/7PIN_1_5/.../ai_VC.py` + `2.sdk/new_*.bat` +> **审查日期**:2026-05-16(**需求已与 IMP 决策同步**) +> **产品配置**:`product_k8.ini`,`PRODUCT_NAME=k8` + +### 8.1 总览 + + +| 维度 | 一致/已实现 | 部分一致 | 未定义/非本模块 | +| --- | ---: | ---: | ---: | +| 交互需求(第 3 章,不含 PWR-01/02) | **22** | **2**(PWR-03、NOTE-03) | 2 | +| IMP 已关闭(原 GAP-001~010) | **10** | 0 | — | +| 开放 GAP(第 5 章) | — | **1**(GAP-011) | 3 项联调备注 | +| 版本与构建链 | **8** ✅ | 1 ⚠️ 遗留脚本 | — | + + +**结论**:需求—设计—实现三角已对齐 **IMP-001~010**;`交互规范_new.md` 中 PWR-04、NOTE-02 播放行、ERR-02/03 已按决策改写。后续联调聚焦 **GAP-011(弱网)**、休眠(PWR-03/NOTE-03)、电源 3s/8s。 + +### 8.2 版本与构建(摘要) + +| 项 | 状态 | +| --- | --- | +| `k8_V1.2_yyyy_MM_dd_HH_mm` + `version_util` frozen | ✅ | +| `new_version.bat` 单次调用、`new_clean` release 路径、QP_LOG 默认关 | ✅ | +| `ai_VC_coze.py` / `usr/test1.py` 旧版本串 | ⚠️ 非主路径,建议清理 | + +### 8.3 联调优先级(更新) + +| 优先级 | 项 | +| ---: | --- | +| P0 | 长对话打断、单对话 PTT(IMP-001~003) | +| P1 | GAP-011 弱网 CSQ vs `websocket_error` | +| P1 | OTA 登记 `k8_V1.2_*` | +| P2 | PWR-03/NOTE-03 休眠;清理遗留版本脚本 | +