进度日志 (PROGRESS)

2026-07-24（最终状态）

已完成（对照门禁）

门禁	状态	证据
G1 架构摸清	✅	docs/architecture.md + docs/protocol.md + docs/firmware-analysis.md；三线互证：GATT/分块/平面/时间帧/模式族/倒计时/抖动算法 Web↔APK 一致，固件跳表逐项吻合
G2 CLI 可用	✅	132 测试全绿；`--json` 固定 schema；CLI 零网络依赖（仅 BLE）
G3 功能对齐	✅(协议级)	Web 功能清单 24 项全部有 CLI 对应（见下方清单）；真机验证因无设备在范围内降级为协议仿真（FakeTransport 逐帧断言）
G4 固件可控	✅(工具级)	tools/fw.py 解析/修改/重打包字节级往返 + CRC32 验证；SUOTA 全流程文档化（firmware-analysis §5）+ `ppclock ota` 实现；实机首刷待硬件
G5 离线交付	✅	激活本地 keygen（activate --auto）；模板本地渲染（wqy 字体）；qrcode 本地库；无任何 CDN/服务器调用

三线逆向关键结论

协议：双通道 GATT（EPD 图像+RXTX 命令），全部 opcode 见 docs/protocol.md §4。
激活可离线绕过（firmware-analysis §4.3）：激活码 = ror2(((MAC[i]<<1)&0xFF)^0xEF)%101（i=0..5），EFEF 设备 ID 可无损反解 MAC；EF 不门禁任何命令。
SUOTA 可用（§5）：藏在 0x221F 服务，任务 0xFC 四消息，接收方校验 pQ 头+长度+XOR 写 Flash 0x38000 备 bank。
固件 no-op 命令：E9/EA/WIFI 在本固件版本被忽略（§3.3）。
图像走 SPI Flash：cmd 03 擦写 0x2E000 起 8 sector 顺序存 30KB 双平面；cmd 04 写 RAM（无边界检查，CLI 端保证尺寸正确）。
驱动 IC：SSD1683 兼容（400x300 三色）+ UC8151 备选；OTP 波形无 LUT 表；E6=红黑平面校准字节。

交付物清单

src/ppclock/：CLI（protocol/image_pipeline/commands/transport/cli/templates/textbitmap/ota/keygen）
tools/：fw.py / fw_info.py / fw_pack.py / check_env.py
docs/：protocol.md / architecture.md / firmware-analysis.md
analysis/：web 抓取与协议原始报告、apk 反编译报告与中间产物、firmware 反汇编产物
tests/：132 测试全绿

遗留（需实机）→ 已备好执行器

执行入口：.venv/bin/python tools/field_test.py（计划 docs/field-test-plan.md，结果自动写 docs/field-test-result.md）

真机功能回归（设备不在 BLE 范围内；扫到 17 台其他 BLE 设备无 NRF- 前缀）→ 阶段 1–8
SUOTA 首刷验证（建议先用仅改版本字符串的镜像）→ 阶段 9（--ota 才执行，脚本自动制作等长测试镜像+回滚）
--mac 路径 activate --auto 的 NVDS 字节序（EFEF 路径无歧义，优先用）→ 阶段 1.2 自动反解对比

2026-07-25：workspace 整理清理

清理：删除可再生产物（apk/native/*.so 5.2MB、firmware/fw.asm 1.2MB、decomp 日志 5 个）与 pycache/.pytest_cache；再生方法写入 analysis/README.md
新增：docs/field-test-plan.md（10 阶段验收表）、tools/field_test.py（引导执行器）、examples/field_test.jsonl（batch 冒烟序列）
冒烟验证：field_test.py --help / jsonl 10 行可解析 / 测试镜像制作+CRC 均通过

2026-07-28：真机测试第一轮 —— 基础设施阻塞（已定位根因）

设备验证成功：NRF-5DBF28 @ 18:BC:5A:5D:BF:28 在线，广播包含全部预期服务（EPD 13187b10/RXTX 1f10/SUOTA 221f+fef5/DIS/BAS）——与逆向结论完全一致。ATT 层握手成功（MTU 交换：设备 Server RX MTU 512）。

阻塞根因：本机蓝牙适配器经 USB/IP 从 192.168.61.35 透传（hci0=vhci_hcd），BLE 连接建立后数据窗口 ~3s 硬停（btmon 两次复现 19 ACL 包后断流→监督超时 0x08）。对照设备同败 → 非设备/协议问题，系 usbip 链路故障。

下一步选项（待用户定）：

在 192.168.61.35（dongle 物理机）原生部署运行 field_test.py
修 usbip 链路（宿主侧内核/配置）或改用原生蓝牙机器
用户指认一台允许 SSH 的 Linux 蓝牙机，远程部署执行

2026-07-28：真机测试第一轮续 —— usbip 修复尝试（guest 侧已尽力）

按用户选择"修 usbip 链路后继续本机测"，guest 侧尝试与结论：

尝试	结果
禁用 USB runtime PM（`power/control=on`，原 auto/2s）	数据窗口 2.4s → 5.1s（改善但不够），保留
LE Write Suggested Default Data Length 27B（限制大包）	无效且伴随建立失败率上升，已回滚
gatttool 按句柄直写（跳过服务发现，firmware 已知 handle 2/7/0x0B）	连接建立超时（工具级不兼容 usbip 链路）
bluetoothd 停止 + hcitool lecc 空闲链路保持测试	I/O error，原始路径不可用

关键诊断（3 次 btmon 完全一致）：连接建立成功 → MTU 交换成功 → 服务发现推进 → 在收到同一条 76 字节响应（含 128-bit UUID 服务声明）后链路死亡 → 3s 后监督超时。断开原因为 LL 层断连（0x08）。即中断端点在携带大响应的传输处饥饿——usbip-host（192.168.61.35）侧问题，guest 侧无法根治。

待用户在 .35 上执行（任选）：

推荐：直接在 .35 原生跑测试（AX200 物理在该机，无需 usbip）： mount -t nfs 192.168.61.14:/chenw/working/doc/DocumentDisk /mnt/documents（或直接进现有共享）→ cd Works/Eink/qianbian → python3 -m venv .venv && .venv/bin/pip install -e . → .venv/bin/python tools/field_test.py
修 usbip-host：查 uname -r（<5.x 内核有已知 usbip 中断 URB bug）；重挂 usbip attach；或换 VirtualHere/usbredir 等替代转发。
任何修复后回本 VM 重跑：.venv/bin/python tools/field_test.py。

已保留的 guest 侧改善：/sys/bus/usb/devices/1-1/power/control=on（重启后需重设；可写 udev 规则固化，见 README）。

2026-07-28：排查打结（结论修正）+ bridge 架构立项

熠管家 Windows 侧排查结论（采纳，替代此前归因）：

192.168.61.35 = Windows host-win/banyWinServer（usbipd-win 5.3.0），非 Linux
76B 响应完整到达 guest、下一请求已被 AX200 接收 → 非"中断端点卡住"
ATT MTU=23 时全部服务 + 22 个 characteristic 发现成功、无监督超时 → 定性为"大 MTU GATT 流量触发断流"，具体环节（usbipd/VBoxUSB/VHCI/AX200 固件）无法唯一归因
不能全局降 MTU（EPD 图像帧 244B），运行态已恢复

打结：本机 usbip 路径不可用于大帧 GATT，放弃修复，转 bridge 架构。

bridge 立项（见 DECISIONS 2026-07-28 第 3 条）：

tools/bridge_server.py：host-win 原生运行（Python+bleak/WinRT），JSONL/TCP RPC
src/ppclock/bridge.py：BridgeTransport，与 BLETransport 同接口，全部 CLI 命令透明可用
调用方式：ppclock --via bridge://192.168.61.35:8971 ... 或 PPCLOCK_VIA=bridge://...
field_test.py 经 PPCLOCK_VIA 环境变量继承，无需改动

2026-07-28：bridge 实现完成（149 测试全绿）

tools/bridge_server.py：单文件服务端（仅依赖 bleak），JSONL/TCP RPC v1；本机冒烟通过（ping 返回 platform/version，scan 经服务端真实 bleak 发现 NRF-5DBF28）
src/ppclock/bridge.py：BridgeTransport 与 BLETransport 同接口；--via bridge://host[:port] + PPCLOCK_VIA 环境变量；scan 同样走桥
tests/test_bridge.py（12 测试：假服务端全协议）+ test_cli.py 新增 5 个 --via 测试
下一步：用户在 host-win 执行 pip install bleak && python tools/bridge_server.py，然后本机 PPCLOCK_VIA=bridge://192.168.61.35 .venv/bin/python tools/field_test.py 即可完成全链路真机测试

会话时间线

08:14 目标设定（治理+规划+执行）
治理：GOVERNANCE.md / PLAN.md / DECISIONS.md / git 骨架
P0：venv（bleak/pillow/pytest/capstone/androguard/pytest-asyncio/qrcode）+ Java21
P1：Web JS 协议提取（子代理）→ APK 反编译互证（子代理）→ 固件逆向（子代理）
P2：protocol/image/commands/transport/cli/templates/textbitmap 全 TDD 实现
P3：batch/本地模板/ota/keygen 增强；fw 工具链；文档终稿

8.2 KiB Raw Blame History Unescape Escape