# 决策日志 (DECISIONS)

| 日期 | 决策 | 背景 | 理由 |
|------|------|------|------|
| 2026-07-24 | 以 Web 上位机 JS 为协议第一证据源 | 三条证据线：Web JS / APK / 固件 | Web Bluetooth JS 通常未重度混淆，可读性最高，可 fastest path 拿到 UUID 与命令格式，再与 APK/固件互证 |
| 2026-07-24 | CLI 用 Python+bleak | 本地化+agent 化需求 | bleak 跨平台、无需 root 以外依赖；JSON I/O 便于 agent 编排；Pillow 覆盖全部抖动算法 |
| 2026-07-24 | 项目纳入 git 管理 | 治理规则要求 | 原始目录非 git 仓库；逆向产物多、需频繁提交与回溯 |
| 2026-07-24 | 倒计时前缀位图帧**不**复刻 JS 的 off-by-one | timedjs2.js:206-224 循环 `i < len-1` 丢末字节 | 判定为 JS 端笔误（设备缓冲兼容完整帧）；CLI 发完整 n*32 字节，避免在末字符右下角丢 8 像素 |
| 2026-07-24 | 倒计时日期/休眠小时采用 BCD 编码 | timedjs2.js:242-243 / ble.js:4013-4015 均为十进制字符串直拼后经 hexToBytes | 实测 JS 证据：month=12 → 字节 0x12，hour=23 → 0x23；与 setTime 的真 hex（intToHex）不同，需注意区分 |
| 2026-07-24 | 固件头格式确认（magic 'pQ'/flags 0x01AA/长度/CRC32(body)/64B 头/0x20 填充 0x00） | 以 zlib.crc32 反推验证 CRC 字段 = body 的 CRC32，重打包字节级往返一致 | fw_pack 可生成与原镜像格式一致的文件，是固件可控（G4）的基础 |
| 2026-07-24 | 中英混排 0.5 单位的倒计时前缀在 CLI 拒绝 | JS `'0'+charCount` 遇 3.5 生成非法 hex "03.5" | 属于上游 bug 路径，CLI 显式报错优于发送畸形帧 |
| 2026-07-28 | 真机测试阻塞定责：USB/IP 透传链路（hci0=vhci_hcd，源 192.168.61.35:3240 Intel AX200）在 BLE 连接数据窗口 ~3s 后硬停 | btmon 两次复现：连接建立成功→MTU 交换成功（设备 RX MTU 512）→服务发现推进→~19 个 ACL 包后悬崖式断流→Disconnect 0x08；对照设备（小米温湿度计 RSSI -27）同样失败 | 排除设备与协议软件问题（扫描/连接建立/ATT 初期均正常）；属 usbip-host 中断端点饥饿类故障；需在 usbip 源机原生运行或修 usbip，详见 PROGRESS.md 阻塞节 |
| 2026-07-28 | **结论修正**：根因 = **大 MTU GATT 流量触发链路断流**（非此前判断的"中断端点饥饿"），具体归因于 usbipd-win/VBoxUSB/VHCI/AX200 固件链中某一环，无法唯一归因 | 熠管家在 Windows 侧排查：76B 响应完整到达 guest、下一请求已被 AX200 接收；**ATT MTU=23 时全部服务+22 个 characteristic 发现成功、无监督超时**；usbipd-win 5.3.0 + Ubuntu 6.8.0-136 均为最新 | 不能全局降 MTU（EPD 图像帧 244B > MTU23），故转向 bridge 架构：BLE 在 host-win 原生执行，guest 经 RPC 调用（见下条） |
| 2026-07-28 | 引入 **bridge 能力**：host-win 原生跑 bleak(WinRT) 并以 JSONL/TCP 暴露 RPC，ubuntu-openclaw 的 ppclock 经 BridgeTransport 远程调用 | usbip 链路无法承载大 MTU GATT；Windows 原生 BLE 无此问题；NFS 仓库两边可达 | 交付：tools/bridge_server.py（单文件服务端）+ src/ppclock/bridge.py（与 BLETransport 同接口）+ CLI `--via bridge://host:port` / `PPCLOCK_VIA` 环境变量 |
| 2026-07-28 | **RXTX 命令通道 = 331f（非 web 文档的 1f1f）** | 实机 GATT 诊断（bridge services op）：1f1f(h=53) 仅 write 无 notify，写入 ATT-ACK 但设备不执行；331f(h=57) notify+write+read，经其实测 EFEF/模式/倒计时/停车牌全部生效 | ppclock 全栈切换（protocol.RXTX_CHAR_UUID=331f、BLETransport/BridgeTransport 写路径）；保留 1f1f 为 legacy 常量 |
| 2026-07-28 | **设备 ID 反解参数序实机校正**：snprintf 实参序为 MAC5,MAC4（非固件代理读的 MAC4,MAC5） | 实机 ID '81233F3C267112' 仅按 MAC5 在前才能反解出广播地址 18:BC:5A:5D:BF:28（NVDS 反转序）；按原序则掩码矛盾 | protocol.recover_mac_from_device_id 已修正并锁定实机向量测试；firmware-analysis §4.2 对应行以本条为准 |
| 2026-07-28 | 设备睡眠行为适配：广播窗口短（约 30-60s），连接态保持清醒 | 实测：空闲即停广播；单连接 batch 可在窗口内跑完全部命令 | 现场测试统一用 `ppclock batch` 单连接；唤醒守候循环（每 15-20s 重试）跨窗口执行 |