# Smartcar（车载香薰）接入 —— 设计与落地文档

> 2026-09-09 起草 → 2026-09-10 按客户端架构重构大幅修订 → 2026-09-10 **决策定稿**。
> 除命令表需真机复核外，实现方案已全部确定，可以开工。
> 对应产品：后台已登记的 `Smartcar`，客户端品类 `DeviceCategories.carAroma`，厂商键 `DeviceVendors.smartcar`。
> 参考源工程：`/Users/yunyanzhineng/work/src/lumi`（Lumi「智能车载AI精灵」App，同一颗方案）。
> **本文只做设计，未改任何代码。**

---

## 0. 一句话结论（本次修订后）

客户端刚做的设备层重构**把这件事的难度降了一大截**：`DeviceHub` + `DevicePlugin` 已经把
「接一种新芯片」标准化了，而且 `DeviceVendors.smartcar` 和 `AgentDefaults` 的
`smartcar → carAroma` 映射**已经预埋好了**。

所以现在的工作不再是"仿着恒玄再造一套服务"，而是：

> **实现一个 `DevicePlugin`（放 `lib/devices/smartcar/` + 一个原生插件），
> 在 `device_bootstrap.dart` 里 `registerPlugin` 一行，声明好能力集，业务层零改动。**

AI 侧同理：模块系统改成了自带路由/自带文案的 `AgentModuleDescriptor`，
新增一个 agent 不用改中心 switch、**不用动 41 个语言文件**。

仍然存在的三块硬骨头：**opus 解码器归属**（`jl_opus` 插件已被删）、
**`classic_bluetooth` 缺 `connectDevice`**（要动共享插件）、**C2 命令表文档与代码打架**。

---

## 1. 新架构：接一种设备现在意味着什么

这是本次修订的核心，前一版文档基于旧架构写的实现方案已作废。

### 1.1 三层结构

| 层 | 位置 | 职责 |
|---|---|---|
| 契约 | `local_plugins/device_plugin_interface/` | `DevicePlugin` / `DeviceSession` / `DeviceCapability` / `AudioRoute` / 各种事件 |
| 厂商实现 | `lib/devices/<vendor>/` + 对应原生插件 | 把私有协议翻译成契约语义 |
| 中枢 | `lib/devices/device_hub.dart` | **业务层唯一设备入口**，汇总会话/能力/电量 |

⚠️ **业务层（`lib/modules`、`lib/core`）只能 import `device_hub.dart` 和
`device_plugin_interface`**，不能碰 `lib/devices/<vendor>/` 里的任何东西 ——
`test/devices/device_hub_boundary_test.dart` 守着这条线，越界会挂测试。

### 1.2 已有两个厂商实现，可作模板

| 厂商 | 目录 | 链路 | 与 Smartcar 的相似度 |
|---|---|---|---|
| `bes` 恒玄 Echo-one | `lib/devices/bes/`（843+637+278 行） | 经典蓝牙 SPP / iOS GATT 桥 | 协议风格像（AA/BB 帧），链路不像 |
| `holder` EaiRec 支架 | `lib/devices/holder/`（422+507 行） | **BLE + Opus** | **最像，优先照它抄** |

`holder` 就是「BLE 扫描 + 私有帧 + Opus 上行」，和 Smartcar 是同一形态。
它的原生实现在 `local_plugins/recorder_holder/`（含 `lib/src/rec/` 协议层：
`rec_client` / `rec_frame` / `rec_protocol` / `rec_transport` / `rec_native_transport`）。

### 1.3 能力驱动，不写厂商分支

`DeviceCapability` 是个只增不删的枚举。**业务层禁止写 `if (vendor == 'xxx')`**，
一律问能力。Smartcar 预计要声明：

| 能力 | 用途 | 备注 |
|---|---|---|
| `scan` / `connect` | 必备 | |
| `battery` | 电量 | 走 C2 `0x04` |
| `macAddress` | **服务端确权** | 见 5.2，这条 Smartcar 比恒玄强 |
| `micUplink` | 设备麦上行（`openMic(ai)`） | Opus 解码后给 16k PCM |
| ~~`speakerDownlink`~~ | ~~下行播 AI 回复~~ | **不需要**：下行走 A2DP，手机正常播放即可，见 7.0 |
| `aiWake` | 按键/唤醒起会话 | **声明它就能白嫖 `DeviceAiSessionService`**，见 6.4 |
| `customCommand` | 私有命令（情绪/亮度/电机…） | `invokeFeature` |
| `ota` | 固件升级 | ✅ **本期要做**，见第 8 节 |

### 1.4 已经预埋好的两处

```dart
// lib/devices/device_vendors.dart
static const String smartcar = 'smartcar';   // Smartcar 车载香薰（协议待接）

// lib/data/services/agent_module_defaults.dart
static const Map<String, String> _vendorCategory = {
  DeviceVendors.bes:      DeviceCategories.earphone,
  DeviceVendors.holder:   DeviceCategories.phoneHolder,
  DeviceVendors.smartcar: DeviceCategories.carAroma,   // ← 已经有了
};
```

`AgentDefaults.bind(DeviceHub.to)` 挂在 `hub.sessions` 上，**谁上线就按厂商→品类铺一次默认功能**。
也就是说：只要 Smartcar 插件把会话推进 hub，默认编排会自动触发，不用另外写钩子。

---

## 2. 设备与协议（来自 lumi，未变）

协议文档在 `lumi/docs/c2_ble_protocol.md`（自 `c2_ble_20251127.xlsx` 生成），设备代号 **C2**。

### 2.1 GATT

| 用途 | UUID | 属性 |
|---|---|---|
| 控制服务 | `0000ABC0-0000-1111-2222-123456789ABC` | PRIMARY |
| 写 | `0000ABC1-...` | **WriteWithoutResponse** |
| 通知 | `0000ABC2-...` | NOTIFY |
| 广播 | `0000BB01-0000-1000-8000-00805f9b34fb` | 扫描过滤用 |

### 2.2 广播数据（25 字节）—— 绑定与经典蓝牙所需的一切都在这里

| 字节 | 含义 | 值 |
|---|---|---|
| 2-3 | CID 生产商 | `0x8505`（云衍） |
| 4-5 | BID 服务商 | `0xA001` |
| 6-7 | PID 产品 | 云衍分配 |
| 8 | 经典蓝牙连接态 | `0x00` 未连 / `0x0C` 已连 |
| 9-14 | **经典蓝牙 MAC** | **每字节 XOR `0x5A`** |

> ⚠️ **上表是协议文档的写法，样机没有这样发**。2026-09-10 真机实测厂商数据只有 `05 85 a9 1a b3 21 e4 dd 00`：CID 之后紧跟 6 字节 MAC（**原样、不异或、不倒序**，= 设备真实地址 A9:1A:B3:21:E4:DD，`user_binddevice` 按它确权通过），再 1 字节状态（未连经典蓝牙时 0x00，按文档 0x0C=已连处理，待复核）。BID/PID/License 广播里没有。这和 lumi iOS `parseMacFromManufacturer` 的 0x0585 分支完全一致。**以代码 `SmartcarProtocol.parseManufacturerData` 为准。**
| 15-24 | **License 授权码** | 10 字节 |
| 25 | 设备类型 | 0x01 耳机 / 0x02 录音笔 |

> ⚠️ 字节序**小端**。⚠️ MAC 要逐字节异或 `0x5A` 才是真地址，忘了这步会得到一串合法但错误的
> MAC，表现为绑定报「设备未登记」，而数据其实好好的。

### 2.3 帧格式

| 方向 | 帧头 | 结构 |
|---|---|---|
| APP → 设备 | `0xAA` | sof + cmd(1) + len(1) + data(N) + CRC(1) |
| 设备应答 | `0xBB` | 同上 |
| 设备主动上报 | `0xCC` | 同上 |

### 2.4 命令表 —— ⚠️ 文档与代码对不上，以代码为准且必须真机复核

| 命令 | 协议文档说 | `BleConst.kt` 说 |
|---|---|---|
| `0x05` | 手机音乐播放状态 | `CMD_CLOSE_AI_DIALOG` |
| `0x07` | AI状态 | `CMD_CONTROL_MOTION` |
| `0x03` | 文档没有 | `CMD_GET_COLOR_ID` |
| `0x08` | 文档没有 | `CMD_CONTROL_MUSIC_BEAT` |
| `0x11` | 陀螺仪开关 | 同时也是**AI 对话触发**上报 |

**按一等风险对待。** 恒玄耳机上栽过一模一样的跟头：厂商文档写的电量请求码三种解读全错，
实测才扫出真正的 `AA 09`，而且**换固件命令号还会变**。

- 实现以 `BleConst.kt` / `BleProtocol.kt` 为准（那是跑在真机上的代码）
- 样机到手先做一轮命令核对，结论写回本文档并标注固件版本
- 别把这张表当稳定契约

---

## 3. ⚠️ Opus 解码器：`jl_opus` 插件已被删除（本次修订新增的重大变化）

前一版文档写着"我们已经有 `jl_opus`，不用搬解码器"。**这个前提没了**：

本轮重构删掉了 5 个插件：`jl_opus`、`asr_tr_tts_manager`、`open_ai_service`、
`realtime`、`volcano_speech`。`pubspec.yaml` 里现在**没有任何 opus 依赖项**。

但 opus 能力并没有消失，只是**收进了各厂商插件内部**：

| 端 | 支架（EaiRec）的 opus 解码在哪 |
|---|---|
| Android | `local_plugins/recorder_holder/.../BleService.kt` → 杰理 `jl_audio_decode` 的 `OpusManager` |
| iOS | `local_plugins/recorder_holder/ios/.../SwiftOpusAudioProcessor.swift`，Package.swift 引用 `device_jieli` vendor 的 `JLAudioUnitKit` |

> pubspec 里那条注释写得很清楚：`device_jieli` 之所以留着，是因为
> 「recorder_holder 的 iOS Package.swift 引用它 vendor 的 JLAudioUnitKit（支架 Opus 解码）」。

### 3.1 ✅ 已定：方案 A（Smartcar 插件内自带一份）

| | A. Smartcar 插件内自带一份 | B. 抽出共享 opus 模块 | C. 复用 recorder_holder |
|---|---|---|---|
| 做法 | 照 recorder_holder 的写法在新插件里再实现一遍 | 把解码抽成 `local_plugins/opus_codec` 供两家用 | Smartcar 直接依赖 recorder_holder |
| 优点 | 边界最干净，改 Smartcar 不会碰支架 | 不重复 | 最省事 |
| 缺点 | 两份解码代码 | **要动支架现有代码**，违反硬边界 | 把支架的协议层拖进来，耦合 |
| 评价 | **推荐** | 本期不做 | 不推荐 |

**已定方案 A**：重复一份解码胶水代码的成本，远低于动支架已上线代码的风险。
底层 SDK（`jl_audio_decode` jar / `JLAudioUnitKit`）本来就在树里，不用新引入依赖。
⚠️ 落地时**不要 import `recorder_holder` 的任何东西**，照着它的写法在新插件里独立实现。

⚠️ 无论选哪个，**目标格式是固定的**：`DeviceSession.openMic()` 要吐
**16kHz / 16bit / 单声道 PCM**（`holder_device_service` 的注释确认了这个口径），
`DeviceAiSessionService` 直接把它转给百炼。

---

## 4. 从 lumi 拉什么、不拉什么

### 4.1 要拉

| 内容 | lumi 位置 | 用途 |
|---|---|---|
| C2 协议编解码 | `local_plugins/lumi_device/`（`BleProtocol.kt`/`.swift`） | 组帧/解帧/CRC |
| 广播解析 | `BleConst.kt` 的字段布局 | 解 MAC / License / PID |
| BLE 连接细节 | `sdk/lumi_ble/.../ble_service/BleService.{kt,swift}` 中 C2 相关部分 | GATT 连接、notify 订阅 |
| **经典蓝牙自动连接时序** | `sdk/lumi_ble/lib/src/lumi_classic_manager.dart` | 见第 7 节 |
| **杰理 OTA SDK** | `lumi_device/android/libs/jl_bt_ota-1.10.0.aar`、iOS `JL_OTALib.framework` | 见第 8 节 |

⚠️ **只搬协议与时序，不搬架构。** lumi 的 `LumiBle` 是个 1581 行的大单例，
直接搬会和 `DevicePlugin` 契约打架。正确做法是把协议逻辑塞进
`lib/devices/smartcar/` + 新原生插件，对外只暴露契约里的语义。

### 4.2 不要拉

| 内容 | 为什么 |
|---|---|
| `bailian_multimodal` 插件 | 我们有 `BailianMultimodalService` |
| 杰理 **Watch / BmpConvert** jar | 手表/表盘 SDK，与香薰无关，白撑包体（**OTA 要拉，见 4.1**） |
| `MusicDetector` / `SilenceKeeper` | lumi 的产品功能，本期不做 |
| `BootReceiver` / `MediaSessionNotificationListener` / `BleCompanionService` | 见 5.2，影响过审 |
| `LumiBle` 大单例 | 见上，与新架构冲突 |

---

## 5. ⚠️ 四个坑（按新架构重新评估）

### 5.1 `ble_service` 仍是死代码，本次继续不碰

`apps/client/local_plugins/ble_service/`（5337 行 kt + 4343 行 swift）**依然没在
`pubspec.yaml` 里声明、`lib/` 下 0 处引用**。重构没有清理它。

它和 lumi 的同名插件已经分叉（lumi swift 5763 / dart 783，我们 4343 / 572）。
**不启用、不覆盖、不删——本次完全不碰。** 新插件另起炉灶。

### 5.2 启用 lumi 的 `ble_service` 会引入常驻后台能力

里面带着 `BootReceiver`（开机自启）、`MediaSessionNotificationListener`（通知监听权限）、
`BleCompanionService`（前台服务）。通知监听在国内商店是**敏感权限**，与 Google Play
上架的合规压力冲突。新插件不要引入任何常驻组件。

### 5.3 `classic_bluetooth` 缺 `connectDevice`（唯一要动共享插件的地方，仍未解决）

重构后复核，**依然只有两个方法**：

| | 我们 | lumi |
|---|---|---|
| `getConnectedDevices()` | ✓ | ✓ |
| `isBluetoothEnabled()` | ✓ | ✓ |
| **`connectDevice(mac)`** | **✗** | ✓ |

而这个插件现在被 `azure_speech` 的 iOS Package.swift 引用（pubspec 注释里写着），
恒玄链路也在用。要接音乐就必须补这个方法。

⚠️ **必须纯新增**：不改任何已有方法的签名与行为，改完回归恒玄 OTA 与 azure_speech。

### 5.4 「只有恒玄、不考虑杰理」这条前提不成立

Smartcar 是杰理方案，opus 解码依赖 `jl_audio_decode` / `JLAudioUnitKit`。
`device_jieli` 插件之所以还留着就是为了支架的 opus。涉及香薰的评审别把杰理路径当死代码跳过。

### 5.5 ⚠️ 固件要求先过杰理 RCSP 认证——纯 Dart 链路作废（2026-09-10 真机验证）

阶段 1 实施时曾改用 `flutter_blue_plus` 纯 Dart 实现（只订阅 `ABC0`），真机结果：
**能扫到、能建 GATT，但设备屏幕始终显示 BLE 未连接，`0x15` 也不应答。**

根因在 lumi 两端代码里都写着：设备连上后要在杰理服务 `AE00/AE01/AE02` 上跑
**RCSP 认证握手**（iOS 走 `JL_BLEKit` 的 `JL_Assist.assistUpdateCharacteristic:Peripheral:Result:`，
Android 走 `jl_rcsp` 的 `RcspAuth`），**认证通过固件才把手机当成已连接**。
Android 侧原话：「全新的 BLE 连接，没有走 JLWatchManager 认证，设备拒绝响应任何 RCSP 命令」。
认证算法在闭源 SDK 里，Dart 复刻不了。

由此定下的实现口径：

| 项 | 做法 |
|---|---|
| 链路归属 | 新建原生插件 `local_plugins/device_smartcar`，**自己持有 GATT**，同一条连接上复用 `AE00`（认证）与 `ABC0`（业务）。这也是 lumi 自己写 1656 行 `BlePeripheral.kt` 的原因——SDK 持有连接就没法再订阅私有服务 |
| 为什么不扩展 `device_jieli` | 它把连接交给 `JL_BLEMultiple` 持有，Android 上拿不到内部 `BluetoothGatt`，`ABC0` 接不上 |
| iOS 框架共享 | `JL_BLEKit` 是**动态库**，第二份会「Class implemented in both」。`device_jieli` 的 `Package.swift` 新增 `jl-blekit` 产品，`device_smartcar` 按路径依赖（先例：支架复用 `jl-audio-unit-kit`）。我们那份 v1.13 的 `JL_Assist` 五个方法与 lumi 适配层一一对应，多出的 `assistDidReady` / `mAuthEnable` 已按头文件接上 |
| Android aar | lumi 的认证在 `jl_rcsp V0.8`（`com.jieli.jl_rcsp.*`）+ `jl_watch` + `jl_bluetooth_connect`，与 `device_jieli` 已带的 `jl_bluetooth_rcsp V4.2`（`com.jieli.bluetooth.*`）**包名不重叠、可并存**；但 **`jl_audio_decode` 绝不能再放一份**（Duplicate class） |
| `ready` 的定义 | = 杰理认证通过（对齐 lumi `passJlAuth`）。GATT 连上只是 `linkConnected`，业务层不能用 |
| 组帧 | 仍在 Dart（`smartcar_protocol.dart`，18 条单测）；原生只收发 `ABC1/ABC2` 裸字节 |
| 先 iOS 后 Android | iPhone 上先验证「认证通过 → 设备显示已连接」；Android 暂为桩（返回明确的 UNIMPLEMENTED，不是 MissingPlugin） |

⚠️ 认证失败/超时都必须带原因报到 UI（「没有 AE00」「AE02 通知打不开」「固件拒绝握手」「SDK 15s 没回调」各不相同）——
扫描与连接两次排查都栽在「失败不可见」上。

---

### 5.6 ⚠️ 认证过了设备也不认——还要发 `0x10 蓝牙连接成功`（2026-09-10 真机定论）

原生插件上线后真机日志：`connecting → linkConnected → authenticating → ready`，`0x15` 回了电量 80%，
服务端 `user_binddevice` 也按 MAC 确权通过——**App 各层都说连上了，设备屏幕仍显示 BLE 未连接**。

原因：C2 协议里有一条 `0x10 蓝牙连接成功`（APP → 设备，载荷 `[设备类型, 车企编号]`，
设备类型 3 = iOS / 2 = 安卓），固件把「手机已连接」这个状态**交给 APP 宣告**。
在已认证的链路上发 `AA 10 02 03 00 <crc>`，设备回 `BB 10 01 64`。lumi 从没发过它（lumi 不是车载产品），
所以照搬 lumi 的连接流程永远不会碰到这条。

落地：`SmartcarSession._handshake` 第一步就发 0x10，无应答或 `len=0` 一律判握手失败断开——
"App 以为连上了、设备不认"就是这次排查的起点，不能再让它静默通过。feature key
`smartcar.classic_bt_connected` 改名 `smartcar.app_connected`（重发宣告用）。

### 5.7 握手最终序列与「单活动设备」（2026-09-10 真机定稿）

真机最终亮起 BLE 已连接的完整序列（`SmartcarSession._handshake`，全部保留，未二分，TODO(smartcar-handshake)）：

```
GATT 连接 → 发现 AE00/ABC0 → JL_Assist 认证 (ready)
 → AA 10 02 03 00           APP 已连接（iOS=3 / 安卓=2）    设备回 BB 10 01 64
 → RCSP：cmdSetSystemYear / cmdTargetFeature / cmdGetSystemInfo(COMMON,BT)   status 全 0
 → AA 17 <yy MM dd HH mm ss 01>   同步手机时间                设备回 BB 17 01 64
 → AA 15 FF                 参数汇总（电量/版本/开关）
```
0x10 单独发不亮；补上 RCSP 收尾 + 0x17 之后亮。

**单活动设备**：`DeviceHub._attach` 现在把新上线的会话插到最前（= 主设备，设备页图/名/电量随它），
并断开其它厂商的会话。用户从香薰切到耳机时香薰 BLE 断开、图片切换——之前两台并存、主设备是最早连上的那台。
被动回连（系统 ACL 把耳机连回来）同样会顶掉当前设备，这是刻意的。

### 5.8 OTA（阶段 7，iOS 先行，从 lumi 搬）

原生 `SmartcarOta.swift` 对齐 lumi `PbMangerImp.startOta / handleOtaResult / scanAndConnectStage2`：
`JL_OTAManager.cmdOTAData` → 0x08~0x0f 进度 → **0xfc** stage1 完成、设备重启进 stage2 →
扫描 3×60s（广播 MAC == `outputDeviceModel().bleAddr`，或名字含 `smartcar`/原名前缀）→ 连接 + 认证 →
`noteEntityConnected` → `cmdTargetFeature` → 再 `cmdOTAData` → 0x00 成功。
OTA 期间 ABC1 写入被挡（和 SDK 抢 AE01 会卡死）；stage2 窗口每 15s 发心跳喂上层 90s 看门狗。
`JL_OTALib` 同样由 `device_jieli` 以 `jl-otalib` 产品共享。Dart 侧 `SmartcarOtaPort` 接通用
`DeviceOtaController`（下载/看门狗/常亮都复用），会话声明 `DeviceCapability.ota` 后设备页自动出「固件升级」入口。

⚠️ 没用 SDK 新接口 `cmdUpgrade:Option:`（内置回连）：它要 SDK 自己持有连接，与我们自持 GATT 冲突。
⚠️ **未经样机验证**：stage2 广播名、0xfc 是否真会出现、后台产品 `Smartcar` 的固件包地址是否已配。Android 仍是桩。

### 5.9 Android 移植（2026-09-10）

iOS 那套验证成立之后，Android 按同样的结构补齐，**方法/事件通道逐字对齐**，Dart 侧一份代码两端通用。

| iOS | Android | 说明 |
|---|---|---|
| `SmartcarBleCentral.swift` | `SmartcarBleCentral.kt` | 全量扫（不加 ScanFilter，理由同 iOS）；厂商数据补回 2 字节小端公司 ID，让 Dart 解析器两端通用 |
| `SmartcarPeripheral.swift` | `SmartcarGatt.kt` | 自持 GATT；**多一个操作队列**——Android 一次只允许一个在途 GATT 操作，没队列的表现是"偶尔丢一条命令"且与机型强相关 |
| `JLAssistBridge.swift`（`JL_BLEKit`） | `SmartcarRcsp.kt`（`jl_rcsp` 的 `RcspAuth` + `RcspOpImpl`） | 认证算法同源（都调 `libjl_auth.so`） |
| `SmartcarOta.swift`（`JL_OTALib`） | `SmartcarOta.kt`（`jl_bt_ota`） | 见下 |

认证触发点两端不同，都是照各自 SDK 的要求来的：iOS 在 `AE02` 通知打开的回调里起，
Android 照 lumi 在 **MTU 协商完**之后起（并加了 6s 兜底定时器——个别机型 `onMtuChanged` 不回调，
不兜底就只会在 35s 后报「连接超时」，而那个提示指向的方向是错的）。

**依赖口径**（`local_plugins/device_smartcar/android/build.gradle` 顶部有同样的说明）：

- `jl_rcsp V0.8.0` maven 上没有坐标，**只能 vendor**（解包成 `libs/*.jar` + `jniLibs/*.so`；
  AGP 不允许 library 模块直接依赖本地 `.aar`）。包名 `com.jieli.jl_rcsp.*` / `jl_filebrowse.*`，
  与工程里已有的 `com.jieli.jl_bt_ota.*` / `com.jieli.audio.*` 不重叠。
- ⚠️ **`jl_bt_ota` 必须走 maven**：`ble_service` 与 `recorder_holder` 已经依赖
  `com.jieli.jl_bt_ota:jl_bt_ota`（解析到 **1.11.0**），再 vendor 一份 1.10.0 直接 Duplicate class 编不过。
  1.11.0 的 `BluetoothOTAManager` 不再继承 `BluetoothDiscovery`，**没有 `startBLEScan` 可 override**
  （lumi 那个"拦住 SDK 扫描"的 override 也就不需要了），且 `BluetoothOTAConfigure` 的几个开关
  只有 setter 没有 getter，Kotlin 属性赋值写法编不过，得调 `setXxx()`。
- ⚠️ 没有带 `JL_Watch`：lumi 的 `JLWatchManager` 继承 `WatchOpImpl`（手表专用），我们直接继承
  `RcspOpImpl`，少一个 jar。

**Android 运行时权限**：这条链路不走 `flutter_blue_plus`（它自己会申请），所以
`SmartcarDevicePlugin.ensureReady()` 里自己申请 `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT`，
复用支架那套 48h 冷却闸（`PermissionUtil`）。少了这步的表现是**安卓上永远扫不到设备且不报错**。

**2026-09-11 与 iOS 二次对齐**（iOS 真机把链路跑通之后，把后续所有改动同步到安卓）：

| 项 | 两端状态 |
|---|---|
| 方法/事件通道 | 14 个方法、7 种事件**逐字一致**（脚本比对过） |
| Ogg 拆包 + opus 解码 | 两端都有 `OggOpusExtractor`；`audioStats()` 五个键一致（含 `opusPackets`） |
| 认证后 RCSP 收尾 | iOS `JLAssistBridge.runPostAuth` ↔ 安卓 `SmartcarRcsp.runPostAuth`：同步时间 → 设备信息 → 系统信息(通用/BT)，**逐条对齐**。安卓用 `CommandBuilder.buildSyncTimeCmd / buildGetDeviceInfoCmdForAll / buildGetPublicSysInfoCmd / buildGetBtSysInfoCmd` + `sendRcspCommand`，8s 兜底 |
| A2DP 用哪个 MAC | 见下 |
| Dart 层（openMic 顺序、ai.state、quit、默认编排、两个 MAC） | 平台无关，自然同步 |

**A2DP 用哪个 MAC**（`SmartcarSession.classicMacCandidate`）：协议文档说广播里那 6 字节就是经典蓝牙 MAC，
iOS 真机上服务端也按它确权通过了；但 lumi 安卓走的是「经典 MAC = BLE MAC 首字节 − 1」。
两种说法只能在安卓上分辨（安卓的 `deviceId` 就是 BLE MAC）：广播 MAC ≠ BLE MAC 按文档原样用，
== BLE MAC 则按 lumi 减一。⚠️ **未经安卓真机验证**（`TODO(smartcar-a2dp)`），首次真机看
`connectDevice(...)` 那行日志里三个地址的关系即可定论。

⚠️ **Android 端整体仍未上真机**（手边没有安卓测试机连着）。首次真机要盯的四处：认证是否通过、
RCSP 收尾 + `0x10` + `0x17` 之后设备屏幕是否显示已连接、A2DP 用的 MAC 对不对、OTA 的 stage2 回连。

---

### 5.10 阶段 5/6 落地：A2DP、opus 上行、设备唤醒（2026-09-11）

#### 经典蓝牙 A2DP

`classic_bluetooth` 新增 **`connectDevice(mac)` 与 `isA2dpConnected(mac)`，纯增量**——
原有的 `getConnectedDevices` / `isBluetoothEnabled` / 状态监听一个字节没动，
所以依赖它的 `azure_speech`（iOS `MicrophoneCapture.swift` 用 `ClassicBluetoothHelper.shared`
选麦克风输入）行为不变。

| 平台 | `connectDevice` 实际做什么 |
|---|---|
| Android | `createBond()`。Android **没有**"直接连某个 profile"的公开 API，配对成功后系统自己接 A2DP。返回 `already_bonded` / `bonding_in_progress` / `bonding_started` |
| iOS | **做不到**，恒返回 `unsupported_ios`。Apple 不提供发起经典蓝牙配对的接口，只能引导用户去「设置 → 蓝牙」手动配一次 |

`isA2dpConnected` 两端都能用：Android 查 `BluetoothProfile.A2DP` 已连接列表，
iOS 查 `AVAudioSession` 当前输出（`uid` 去掉 `-tacl` 后缀就是**经典蓝牙 MAC**——
这是 iOS 上唯一能拿到设备经典 MAC 的地方）。

落地：BLE 连上后插件自动试一次 `connectClassicAudio()`（iOS 无效果），扫描页在
A2DP 没通时弹一次提示（文案 `smartcarA2dpTitle/Hint`，11 语种随模块自带）。
**失败一律不影响 BLE 会话**——BLE 管控制与上行，A2DP 只管出声。

#### opus 音频上行

设备收到唤醒后**自己开麦**（协议文档原话：「不需要 app 回复，设备端直接开麦，录音发 opus 数据给到 app」），
音频与 RCSP 命令**共用 AE02**，靠 7 字节头区分：

```
FE DC BA 80 01 00 8E | seq(1) | 04 | opus payload … | 尾字节(1，丢弃)
```

`seq` 0~255 循环用于去重（BLE 通知会重复投递，重复帧解出来是杂音）。
解码后统一是 **16k / 16bit / mono PCM**，两端解码库不同但输出口径一致：

| 平台 | 解码器 | 来源 |
|---|---|---|
| iOS | libopus | `ble_service` 暴露的 `opus-binary` 产品（先例：recorder_holder）。⚠️ 自己再 vendor 一份 Xcode 会报「Multiple commands produce opus.framework」 |
| Android | `com.jieli.jl_audio_decode.opus.OpusManager` | maven `com.jieli.audio:jl_audio_decode`，`ble_service`/`recorder_holder` 已在用同一坐标 |

排查口：`audioStats()` → `{running, framesIn, framesDup, pcmBytesOut}`。真机"没声音"时
先看这三个数，能立刻分清是**没收到帧** / **全被当重复丢了** / **解码没出字节**。

#### 设备唤醒接 Smartcar 助手

- 设备上报 `0xCC 0x11` → 会话声明了 `aiWake`，`SmartcarSession` 把它转成 `DeviceWakeEvent(ptt)`，
  `DeviceAiSessionService` 那整套编排直接白嫖。
- `DeviceFeatures.aiAccept` → `0x07 0x04`（聆听中）；`aiExit` → `0x07 0x03`（关闭 AI 对话）。
  设备靠 `0x07` 切表情动画。
- `openMic(ai)` → 上面那条 opus 流；`openSpeaker(ai)` → **手机扬声器**
  （`PcmStreamPlayer`，A2DP 连着时就从设备喇叭出来）。刻意**不声明** `speakerDownlink`：
  下行根本不经 BLE。
- **接哪个助手**：`AgentModule.bailianAppId`（放在 **data 层基类**，不是 modules 层的
  `AgentModuleDescriptor`——`DeviceAiSessionService` 在 data 层，**data 层不能反向依赖 modules 层**）。
  `DeviceAiSessionService` 走「厂商 → 品类 → 默认编排第一个模块 → 该模块的 app_id」，
  车载香薰因此接的是 Smartcar 车载助手（`mm_dd1eb7cb06484aafb94a0b6b2dff`）而不是 EMAI。
  耳机/支架没声明就仍用全局默认，**行为不变**。

### 5.11 ✅ 命令表复核（2026-09-11 样机实测）

两条长期冲突的命令**定了**，判据是 lumi 的**运行时代码**而不是常量名：

| 命令 | 结论 | 判据 |
|---|---|---|
| `0x05` | **手机音乐播放状态**（`0x00`/`0x01`） | lumi `BleService.swift:1041` 在检测到手机放音乐时发的就是 `0x05 [0x01]`，停止发 `[0x00]`，与协议文档一致。`BleConst.kt` 里 `CMD_CLOSE_AI_DIALOG` 这个名字是没跟上的旧命名 |
| `0x07` | **AI 状态**（0说话结束/1思考中/2说话开始/3关闭/4聆听中） | 协议文档明列；"遥控电机"另有其号 `0x0E`，所以 `BleConst.kt` 的 `CMD_CONTROL_MOTION` 也是错名 |
| `0x11` | **双向共号不冲突**：`0xAA 0x11` 陀螺仪开关（APP→设备），`0xCC 0x11` AI 唤醒（设备→APP） | 协议文档里两条都在，靠帧头区分 |

样机实测应答（同一次连接内）：

| 命令 | 应答 | 说明 |
|---|---|---|
| `0x01` 版本 | `02 0c 0c` | = 2.12.12。**文档说 6 字节是错的**，实测 3 字节 |
| `0x02` 设备ID | `01` | |
| `0x03` | `03 00 00 00 3d 00 00 00 00 00 00 00 00 00` | **14 字节**，不像"颜色 ID"。含义仍未定，本项目没在用 |
| `0x04` 电量 | `3c` = 60% | |
| `0x15` 汇总 | `01 00 14 0a 3c 02 0c 0c 00 02 01 01 04 01` | 偏移被**两处独立交叉验证**钉死：`[4]=0x3c` 与 0x04 一致、`[5..7]` 与 0x01 一致 |

这一帧已写成金测试（`test/devices/smartcar_protocol_test.dart`）。
⚠️ `[1]` 音量实测是 **0** —— 如果偏移没错，样机当前是静音的，A2DP 接上也可能听不见，
真机验声音前先确认这一项。

---

## 6. AI 侧：新增 Smartcar agent（按新模块系统重写）

需求：**在广场新增一个 agent**（不复用 EMAI），同一百炼 workspace 下换应用 ID，
例如 `mm_dd1eb7cb06484aafb94a0b6b2dff`；连上设备后 AI 页默认只显示它。主功能是随时开聊。

### 6.1 模块系统已经重构，工作量大幅下降

模块现在是 `AgentModuleDescriptor`（`lib/modules/module_descriptor.dart`），**自带一切**：

```dart
AgentModuleDescriptor(
  id: 'smartcarChat',
  title: 'agentSmartcar',
  subtitle: 'agentSmartcarDesc',
  icon: ..., gradient: [...],
  requiredCapabilities: {DeviceCapability.aiWake},   // 能力声明，不写厂商判断
  entryRoute: Routes.smartcarChat,                   // 或 onLaunch
  pages: [GetPage(name: Routes.smartcarChat, page: ..., binding: ...)],
  translations: {'zh_CN': {...}, 'en_US': {...}},     // ← 模块自带文案
  registerServices: () { /* 需要常驻服务时在这里 put */ },
)
```

相比旧架构，**这三件事不用做了**：

| 旧架构要做 | 新架构 |
|---|---|
| 改 `module_card.dart` 的中心 switch | ❌ 不用，`entryRoute`/`onLaunch` 自带 |
| 改 41 个语言文件加文案 | ❌ 不用，`translations` 字段自带 |
| 去 `AppPages` 注册路由 | ❌ 不用，`pages` 会被自动拼进总表 |

只需在 `lib/modules/smartcar/module.dart` 写一个描述符，
再到 `ModuleRegistry.all` 里加一行。`emai/module.dart` 是现成模板（只有 28 行）。

⚠️ `test/module_registry_test.dart` 守着三条：**id 唯一、entryRoute 已注册、标题文案有落点**。
漏了会挂测试，不会静默。

### 6.2 ⚠️ 百炼 app_id 仍是全局唯一值（这条没变）

```dart
static const String _defaultAppId = '2813e297edb149b0956082641f3e7a53'; // EMAI 的应用
String get _appId => AppConfig.env('ALIBABA_BAILIAN_APP_ID') ?? _defaultAppId;
```

**不能改这个全局值或那个 env 键** —— 会把 EMAI 一起换掉。

**方案：给 `BailianMultimodalService` 加可选的实例级覆盖**（构造参数 `appId` / `workspaceId`，
默认 `null` → 完全走现有全局逻辑）。EMAI 与设备唤醒会话一行不改。
多实例这条路已被 `DeviceAiSessionService` 证明可行。

### 6.3 ✅ 已定：方案 A（客户端内置）

服务端 `DBAgent` 预留了 `source`（0内置/1PolyChat/**2阿里云**/3火山）和
`serviceData`（JSON，各平台接入参数），但**客户端手写镜像里没有这两个字段**。

| | 方案 A：客户端内置（推荐） | 方案 B：后台下发 |
|---|---|---|
| 来源 | 常量或新 env 键 `ALIBABA_BAILIAN_APP_ID_SMARTCAR` | `DBAgent.serviceData` |
| 运营能改 | 否 | 是 |
| 风险 | 低 | 中：手写镜像要手动同步，**non-nullable 字段后端不下发就整个 `fromJson` 挂**，界面全空白 |

**已定方案 A**：app_id 作为常量写在 Smartcar 模块里（或新 env 键 `ALIBABA_BAILIAN_APP_ID_SMARTCAR`）。
⚠️ 代价是**换 app_id 要发版**。等运营真的提出「要后台改」再上 B。

### 6.4 白嫖：声明 `aiWake` 就有设备唤醒会话

`DeviceAiSessionService` 已经**厂商无关**了：要求 `DeviceCapability.aiWake`，
通过 `openMic(ai)` 拿 16k PCM 推百炼，百炼回的 PCM 交 `openSpeaker(ai)`。
握手语义已抽象成 `wakeEvents(ptt)` → `ai.accept` → `ai.exit` → `wakeEvents(hangup)`
（恒玄的 `BB 64` / `AA 6A` / `AA 65` / `BB E5` 只是它的一种实现）。

**Smartcar 只要在插件里把 C2 的 AI 触发（`0x11` 上报）对齐到这套语义，
整条设备唤醒对话链路不用重写。**

⚠️ 但这里有个**需要确认的设计问题**：`DeviceAiSessionService` 用的是全局
`BailianMultimodalService`（EMAI 的 app_id）。Smartcar 要用自己的 app_id，
就得让它支持按会话选实例 —— 这是 6.2 那个改造的一部分，**改动落在共享服务上，
必须保证恒玄唤醒行为零变化**（默认不传 = 原路径）。

### 6.5 默认编排

`AgentModules.defaultsByCategory` 仍在：

```dart
DeviceCategories.carAroma: [smartcarChat],   // ← 加这一行
```

触发已自动（见 1.4，`AgentDefaults` 挂在 `hub.sessions` 上）。

⚠️ **只在首次连接生效一次**（`AgentModuleService.applyDeviceDefaults` 记录）。
调试时改了看不到变化就是这个原因，要清应用数据或换账号。
✅ **已定：就用默认编排，不加硬闸门。** 用户仍可去广场加别的功能，这是产品有意接受的。

### 6.6 ✅ agent 展示信息（已定）

| 项 | 值 |
|---|---|
| 模块 id | `smartcarChat` |
| 名字 | **Smartcar** |
| 副标题 | **您的车载助手** |
| 欢迎语 | **欢迎回来** |
| 百炼 app_id | `mm_dd1eb7cb06484aafb94a0b6b2dff`（workspace 同 EMAI） |

⚠️ **图标只能用 Material 图标，不能直接用产品图。** `AgentModule.icon` 的类型是
`IconData`，`module_card.dart` 里是 `Icon(module.icon, ...)` 套一个渐变色块，**不支持图片**。
想用 `Smartcar_icon.png` 就得给 `AgentModule` 加可选图片字段并改 `module_card` ——
那是**共享 UI**，会碰到耳机/支架的卡片，与硬边界冲突。

建议先用 `Icons.directions_car`（或 `Icons.air`，与 carAroma 品类图标一致），
配一组暖色渐变（如 `[Color(0xFFFFB74D), Color(0xFFE65100)]`，与品类卡同色系）。
真要用产品图，单独立项改卡片组件，别混在本次里。

⚠️ **欢迎语放哪要注意**：走方案 A（客户端内置）时，「欢迎回来」是客户端常量；
但如果百炼那个应用自己也配了开场白，会**两句都出来**。接之前先确认
`mm_dd1eb...` 在百炼后台的开场白设置，二者留一个。

---

## 7. 经典蓝牙与音乐播放

### 7.0 ⚠️ 经典蓝牙不是可选项，是 AI 对话的前置条件

复核 lumi 代码后确认：**整个工程里没有任何 BLE 音频下行**（没有把 PCM 写回特征值的调用），
`ble_manager.dart` 的注释写得很直白——经典蓝牙是「用于 A2DP/HFP 音频通路」。

所以这台设备的音频是**一上一下两条不同的路**：

| 方向 | 通道 | 说明 |
|---|---|---|
| 上行（设备麦 → App） | **BLE Opus** | 解码成 16k PCM 喂百炼 |
| 下行（AI 回复 → 设备喇叭） | **经典蓝牙 A2DP** | 手机当普通音频播放，系统自动路由到已连的 A2DP |

**推论一**：不需要实现 `DeviceCapability.speakerDownlink` / `openSpeaker`，
手机照常播就行。这比恒玄那条（要把 PCM 按节奏回灌进耳机）简单得多。

**推论二（重要）**：**没有 A2DP 就没有 AI 回复的声音**。所以经典蓝牙**不能排在最后做**，
它和 AI 对话是同一条功能的两半。落地步骤已据此调整（见第 9 节）。

### 7.1 lumi 的时序，照搬别自己发明

BLE 连上后**延迟 2500ms** 再发起经典蓝牙连接：

```dart
await Future.delayed(const Duration(milliseconds: 2500));
if (BLE 已断开) return;                       // 延迟期间断了就放弃
await classic.connectDevice(bleMac);
```

⚠️ 2500ms 不是随手写的：要等 BLE 栈完成服务发现/MTU/鉴权，否则 SDP 查询与 BLE 争抢射频，
**系统弹出的配对对话框点确认也会失败**。"延迟期间可能已断开就放弃"同样要照搬。
⚠️ 已 bonded 的不要重复 `createBond`，Android 会自己重连 A2DP/HFP；lumi 用
`_classicBondedBleMac` 短路。

### 7.2 MAC 从哪来

广播厂商数据 CID 之后 6 字节原样（真机实测，见 4.x 的说明）。不需要额外查询命令。

### 7.2b ✅ 音乐范围已定：只要 A2DP 出声

不做 App 内的上一曲/下一曲/音量控制，因此 **C2 的 `0x0B`（音量）、`0x05`（音乐状态）、
`0x08`（音乐节拍）、`0x0F`（音乐表情）这些命令本期都不用接**。
音乐由手机端播放器 + 系统 A2DP 路由完成，设备只当喇叭。

⚠️ 顺带：lumi 的 `MusicDetector`（监听音乐让设备摇头）依赖 `0x1A` opus 通道与
`0x12` 摇头风格，本期不做，别顺手搬进来。

### 7.3 要做的两件事

1. 给 `classic_bluetooth` **新增** `connectDevice(mac)`（Android + iOS），见 5.3
2. 编排写在 `lib/devices/smartcar/` 自己的插件里，**不要**把 lumi 的
   `LumiClassicBluetoothManager` 整个搬进来（它耦合 lumi 的连接状态机）

---

## 8. OTA（✅ 本期要做，直接搬杰理那套）

### 8.1 新架构已经把 OTA 抽象好了

| 层 | 位置 | 职责 |
|---|---|---|
| 契约 | `device_plugin_interface/.../device_ota.dart` | `DeviceOtaPort`：`start(request)` / `cancel()` / `progressStream` / `close()` |
| 厂商实现 | `lib/devices/<vendor>/<vendor>_ota_port.dart` | 只管「怎么把固件推进这颗芯片」 |
| 通用编排 | `OtaUpgradeController` / `device_ota_controller.dart` | 下载、看门狗、屏幕常亮、进度 UI |

请求类型有四种，`DeviceOtaFileRequest` / `BytesRequest` / `UrlRequest` /
**`DeviceOtaVendorRequest`**（厂商私有参数走这个）。

**所以 Smartcar 的 OTA = 写一个 `SmartcarOtaPort implements DeviceOtaPort`，
再在能力集里声明 `DeviceCapability.ota`。** 下载、看门狗、UI 全都白拿。

### 8.2 从 lumi 搬什么

| 内容 | 位置 |
|---|---|
| 杰理 OTA SDK（Android） | `lumi_device/android/libs/jl_bt_ota-1.10.0.aar` |
| 杰理 OTA SDK（iOS） | `lumi_device/ios/Frameworks_backup_v1.12/JL_OTALib.framework` |
| 升级流程编排 | `lumi_device` 里调用 OTA SDK 的那部分 |

⚠️ **只搬 OTA，别把 `JL_Watch` / `BmpConvert` / `jl_rcsp` 里用不着的一起拖进来**——
那是手表表盘那套，白撑包体。

### 8.3 ⚠️ 照 `bes_ota_port.dart` 抄那三条经验

恒玄那份（203 行）踩出来的坑，杰理大概率同样适用，**实现前先读一遍**：

1. **OTA 期间可能要独占链路**。恒玄是「多数固件同时只接受一条 SPP」，所以
   `start` 先断 app 层连接、留 2s 让设备拆完旧链路再让插件连。杰理 BLE 是否也需要
   让路，**要实测**。
2. **升级中的「已断开」是我们自己断的，不能当成 OTA 掉线**——按掉线处理会把正常升级判成失败。
3. **`close()`（退出升级页）要先停 OTA 再延时回连**（恒玄：成功 5s 等设备重启、其余 2s 等拆链路）。

另外通用控制器里那个**90 秒无进度即判失败的看门狗不能删**——原生侧存在「既不推进也不报错」
的情况，没有它 UI 会永久停在「升级中」。

### 8.4 服务端：不用改

固件版本走 `user_getappconfig` 的 products（`version` / `updatepackageaddress` /
`updatedescription` / `isforceupdate`），后台在产品管理 → 版本管理里传固件、设为当前版本即可。
Smartcar 已在后台登记，这条链路现成。

⚠️ 版本比较用与服务端 `comm.CompareVersion` 同口径的实现（取每段前导数字），
**别用 `int.parse` 逐段解析**——遇到 `1.0.0-beta` 会抛异常被外层吞成「已是最新」。

---

## 9. 硬边界：不影响耳机 / 手机支架

好消息：**新架构本身就在强制这件事**，而且有测试守着。

| 风险点 | 保证方式 | 有无测试守 |
|---|---|---|
| 业务层碰厂商内部 | 只能 import `device_hub` + 契约 | ✅ `device_hub_boundary_test.dart` |
| 模块注册漏项 | id 唯一 / 路由已注册 / 文案有落点 | ✅ `module_registry_test.dart` |
| 百炼 app_id | 不动全局值，改用实例级覆盖（6.2） | ⚠️ 需人工回归 EMAI |
| `DeviceAiSessionService` | 加可选参数，默认走原路径（6.4） | ⚠️ 需人工回归恒玄唤醒 |
| `classic_bluetooth` | **唯一要动的共享插件**，只新增方法（5.3） | ⚠️ 需回归恒玄 OTA + azure_speech |
| opus 解码 | 选方案 A（自带一份），不碰 recorder_holder（3.1） | — |
| `ble_service` 死代码 | 完全不碰（5.1） | — |
| 品类/默认编排 | 只加条目，不改 earphone / phoneHolder 现有行 | — |
| 服务端 | 本期**零改动**（MAC 已导入） | — |

**回归清单（每阶段结束都跑）**：
1. `flutter test`（两个守护测试必须绿）
2. 恒玄耳机：扫描 → 连接 → 电量 → OTA 读版本 → **按键唤醒 AI 对话**
3. EaiRec 支架：连接 → 录音（opus 链路）
4. 从广场点 EMAI → 正常对话

---

## 10. 落地步骤

| 阶段 | 内容 | 状态（2026-09-10） |
|---|---|---|
| **0. 前置** | 样机到手；扫一轮命令表 | ✅ 已复核，`TODO(smartcar-cmd)` 全部消掉，见 5.11 |
| **1. 原生插件** | `device_smartcar`：自持 GATT、**杰理 RCSP 认证（AE00）**、C2 通道（ABC0）裸字节收发 | ✅ iOS 真机通过（屏幕显示 BLE 已连接）；✅ Android 已实现，**未上真机** |
| **2. DevicePlugin** | `lib/devices/smartcar/` 实现契约，`device_bootstrap` 注册一行，声明能力集 | ✅ 完成（iOS 真机验过设备进 `DeviceHub.sessions`） |
| **3. 绑定确权** | 广播 MAC → `user_binddevice`；声明 `macAddress` | ✅ 完成（真机 `A9:1A:B3:21:E4:DD` 确权通过，productid 45345） |
| **4. agent** | `lib/modules/smartcar/module.dart` + `ModuleRegistry` 一行 + app_id 实例级覆盖 | ✅ 完成（用户已测） |
| **5. 经典蓝牙** | `classic_bluetooth` 新增 `connectDevice` + 配对编排 | ✅ 代码完成（纯增量，见 5.10）；⚠️ **A2DP 未真机验声**——样机当时没和 iPhone 配对经典蓝牙 |
| **6. 音频上行** | opus → `openMic(ai)` 出 16k PCM；对齐 `aiWake` 握手语义 | ✅ 代码完成，能力集已含 `micUplink`/`aiWake`，真机上 opus 解码器起得来；⚠️ **未收到过真实音频帧**（还没在样机上触发过唤醒） |
| **7. OTA** | `SmartcarOtaPort` + 杰理 OTA SDK，声明 `ota` 能力 | ⚠️ 两端代码已接（见 5.8 / 5.9），**都没跑过真机**；且后台还没给 Smartcar 挂固件包 |
| **8. 收尾** | 扫描页、电量、把 `carAroma` 移出 `_scanNotReady` | ✅ 完成（`_scanNotReady` 已空；电量走 `0x15`/`0x04`） |

**还剩的三块**（按依赖顺序）：

1. **阶段 5 经典蓝牙**——风险最高，要动共享插件 `classic_bluetooth`（恒玄 OTA / azure_speech 也在用它，
   必须是纯新增 + 单独回归）。没有它就听不到 AI 回复（下行走 A2DP，见 7.0）。
2. **阶段 6 音频上行**——依赖 5。opus 解码器按 3.1 的方案 A 自带；Android 侧注意
   `ble_service` 已经带了 `com.jieli.audio:jl_audio_decode`，别再 vendor 第二份。
3. **命令表复核 + OTA 真机验证**——都要样机在手，见 11.2。

另有一处小尾巴：`smartcarWelcome`（欢迎语「欢迎回来」）**41 个语种的文案都写好了但没有接进会话**，
要先确认百炼那边的开场白由谁出（后台编排 vs 客户端首帧），别两边都说一遍。

---

## 11. 决策记录与剩余待确认

### 11.1 ✅ 已定稿（2026-09-10）

| # | 问题 | 决定 | 落点 |
|---|---|---|---|
| 1 | opus 解码器归属 | **A：Smartcar 插件自带一份**，不碰 recorder_holder | 3.1 |
| 2 | 百炼 app_id 放哪 | **A：客户端内置**（换 id 要发版；后台可配列为后续） | 6.3 |
| 3 | 只显示这个 agent 的力度 | **默认编排**，不加硬闸门 | 6.5 |
| 4 | agent 展示信息 | 名字 Smartcar / 副标题「您的车载助手」/ 欢迎语「欢迎回来」/ Material 图标 | 6.6 |
| 5 | 音乐控制范围 | **只要 A2DP 出声**，不接音量与曲目命令 | 7.2b |
| 6 | 下行音频通道 | **A2DP**（已查明 lumi 无 BLE 下行），不实现 `openSpeaker` | 7.0 |
| 7 | OTA | **本期做**，直接搬杰理那套 | 第 8 节 |
| 8 | 命令表冲突 | **先以代码为准**，真机后调整 | 11.2 |

### 11.2 ⏳ 剩余唯一待确认：命令表（等样机）

按决策 8：**实现时一律以 `BleConst.kt` / `BleProtocol.kt` 为准**，
协议文档那份当参考、不当依据。

**代码里必须做好标记**，真机测完再回来改。约定格式：

```dart
// TODO(smartcar-cmd): 未经真机验证 —— 协议文档说「AI状态」，BleConst.kt 说
// CMD_CONTROL_MOTION，此处取后者。样机验证后更新本行与
// docs/Smartcar车载香薰-接入设计与落地文档.md 的 2.4 节。
static const int cmdControlMotion = 0x07;
```

**要打标记的至少这 5 条**（2.4 节列出的冲突项）：
`0x03` / `0x05` / `0x07` / `0x08` / `0x11`。

⚠️ 验证时**只扫低位查询段**。lumi 的 `0x0C` 是恢复出厂、`0x0E` 是遥控电机、
`0x0D` 是启停开关——**这几个别乱发**。恒玄那次的教训是 `0x5x`/`0x6x` 会切工作模式，
C2 同样要先看清命令含义再发。

⚠️ 命令表**按固件版本标注**。恒玄上已经出现过「换固件命令号就变」，别当稳定契约。

---

## 12. 附：不要重复踩的坑

- **别照文档写命令号**——恒玄电量那次文档三种解读全错，实测才扫出 `AA 09`；换固件还会变
- **别让客户端猜 pid**——2026-09-04 事故根因，服务端已改成按 MAC 全局反查
- **确权判不出来要放行**——断网/未登录一律放行，判严的代价是合法用户断网就用不了设备
- **Dart non-nullable 字段**——后端不下发就整个 `fromJson` 抛 TypeError、界面空白
- **AI 会话要独立实例**——共用单例会互相 `stop()`、下行音频串台
- **默认编排只生效一次**——调试时改了看不到变化是正常的
- **业务层别 import 厂商目录**——有测试守着，但设计时就该按能力想问题