From 30571dc0a57213b6cbaf9b2cea47491c3f2c9b0d Mon Sep 17 00:00:00 2001 From: agent Date: Fri, 24 Jul 2026 08:31:15 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=80=BB=E4=BD=93=E8=A7=84=E5=88=92/?= =?UTF-8?q?=E5=86=B3=E7=AD=96=E6=97=A5=E5=BF=97/=E8=BF=9B=E5=BA=A6?= =?UTF-8?q?=E6=97=A5=E5=BF=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DECISIONS.md | 7 + PLAN.md | 17 ++ PROGRESS.md | 21 +++ .../plans/2026-07-24-eink-4.2-reverse.md | 171 ++++++++++++++++++ 4 files changed, 216 insertions(+) create mode 100644 DECISIONS.md create mode 100644 PLAN.md create mode 100644 PROGRESS.md create mode 100644 docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md diff --git a/DECISIONS.md b/DECISIONS.md new file mode 100644 index 0000000..081dd42 --- /dev/null +++ b/DECISIONS.md @@ -0,0 +1,7 @@ +# 决策日志 (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 仓库；逆向产物多、需频繁提交与回溯 | diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..3d41192 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,17 @@ +# PLAN — 总体规划（入口） + +详细计划：[`docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md`](docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md) +治理规则：[`GOVERNANCE.md`](GOVERNANCE.md) ｜ 进度：[`PROGRESS.md`](PROGRESS.md) ｜ 决策：[`DECISIONS.md`](DECISIONS.md) + +## 阶段与门禁一览 + +| 阶段 | 目标 | 对应任务说明 | 门禁 | +|------|------|--------------|------| +| P0 工具链 | venv + jadx/androguard/capstone/bleak | — | 自检全 OK | +| P1 三线逆向 | Web JS → APK → 固件互证，产出 architecture.md + protocol.md | 目标1 | **G1** 三线互证一致 | +| P2 CLI 上位机 | 协议层/图像管线/命令层/CLI，功能对齐 Web 上位机 | 目标2 | **G2** 测试全绿+JSON schema；**G3** 功能全覆盖 | +| P3 增强+固件可控 | 本地模板渲染/批量/调度；固件解析重打包+SUOTA | 目标2增强、目标3 | **G4** 镜像可改可重生成；**G5** 断网验收 | + +## 当前状态 + +见 PROGRESS.md。 diff --git a/PROGRESS.md b/PROGRESS.md new file mode 100644 index 0000000..2f31bcb --- /dev/null +++ b/PROGRESS.md @@ -0,0 +1,21 @@ +# 进度日志 (PROGRESS) + +## 2026-07-24 + +### 已完成 +- 侦察：固件=DA14585 镜像（'pQ' 签名头，向量表基址 0x07FC0000，含 `H:mspppclock.tech` / `V:PP_da14585_4.2` / `WX:2549294317` / `MAC:%02X...` 字符串） +- 侦察：APK=Kotlin Compose Multiplatform（classes.dex 6.3MB + libapp.so/libeditor.so） +- 侦察：Web 上位机功能面（时钟/倒计时/传图6种抖动/6模板/睡眠/停车牌/WiFi配置/高级命令/固件下载） +- 建立 GOVERNANCE.md / PLAN.md / DECISIONS.md / 详细计划 docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md +- git init + 骨架提交 + +### 进行中 +- P0 工具链搭建 + +### 下一步 +1. 安装 jadx + Python 依赖（bleak/pillow/capstone/androguard/pytest） +2. 抓取 mspppclock.tech 全部 JS，提取 BLE UUID 与命令协议 +3. jadx 反编译 APK 互证 + +### 阻塞/风险 +- 真机是否可用未知；Task 9（真机对齐）可能降级为协议仿真验证 diff --git a/docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md b/docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md new file mode 100644 index 0000000..7170d94 --- /dev/null +++ b/docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md @@ -0,0 +1,171 @@ +# 4.2寸 e-ink 设备逆向与本地化改造 · 总体实现计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> 工作准则见根目录 `GOVERNANCE.md`；进度记录于 `PROGRESS.md`。 + +**Goal:** 摸清 4.2寸墨水屏设备（DA14585 BLE SoC）软硬件架构，交付离线可用的 agent 友好 CLI 上位机，并获得固件级可控能力。 + +**Architecture:** 三条证据线（Web 上位机 JS / Android APK / DA14585 固件镜像）互证还原 BLE GATT 协议与图像协议 → 以 Python+bleak 实现离线 CLI（JSON I/O，面向 agent）→ 固件镜像解析/修改/SUOTA 工具链实现软硬件可控。 + +**Tech Stack:** Python 3.12、bleak（BLE）、Pillow（图像抖动）、jadx/androguard（APK）、capstone（固件反汇编）、pytest。 + +## Global Constraints + +- 交付物运行**零互联网依赖**（仅本机 BLE）。（任务说明 目标2） +- CLI 面向 agent：所有命令支持 `--json` 机器可读输出。 +- 功能集必须先对齐 Web 上位机现有功能，再谈增强。（任务说明 目标2） +- 固件指 DA14585 镜像；可控 = 能解析、能修改、能重生成可烧录镜像、SUOTA 流程文档化。（任务说明 目标3 + GOVERNANCE G4） +- `app/` 原始输入只读；所有结论须附证据。 + +--- + +## 阶段总览与门禁 + +| 阶段 | 内容 | 门禁 | +|------|------|------| +| P0 | 治理+工具链 | git 就绪；jadx/androguard/capstone/bleak 可用 | +| P1 | 三线逆向（Web→APK→固件） | G1：architecture.md + protocol.md，三线互证 | +| P2 | CLI 上位机（功能对齐） | G2、G3：测试全绿，功能清单逐项覆盖 | +| P3 | 增强 + 固件可控 | G4、G5：镜像工具+SUOTA 文档；离线验收 | + +--- + +## P0：工具链（Task 1） + +### Task 1: 分析环境搭建 + +**Files:** +- Create: `requirements.txt`, `tools/check_env.py` + +- [ ] Step 1: 创建 venv 并安装依赖 + +```bash +python3 -m venv .venv && .venv/bin/pip install -q --upgrade pip +.venv/bin/pip install bleak pillow pytest capstone androguard +apt-get install -y jadx 2>/dev/null || (cd /opt && curl -sL -o jadx.zip https://github.com/skylot/jadx/releases/download/v1.5.1/jadx-1.5.1.zip && unzip -qo jadx.zip) +``` + +- [ ] Step 2: 写环境自检 `tools/check_env.py`（导入 bleak/pillow/capstone/androguard；检查 jadx 可执行；打印版本表） +- [ ] Step 3: 运行自检，预期全 OK +- [ ] Step 4: 冻结 `requirements.txt` 并提交 + +--- + +## P1：三线逆向（Task 2–4） + +### Task 2: Web 上位机协议提取（最快路径，先做） + +**Files:** +- Create: `analysis/web/fetch.sh`, `docs/protocol.md` + +- [ ] Step 1: 抓取站点全部 JS/HTML 到 `analysis/web/`（curl 递归，含 file_down.php 固件列表） +- [ ] Step 2: 提取并记录：BLE service/characteristic UUID、通知/写入选项、命令字节格式、图像分块与应答协议、模板/时钟/倒计时命令 +- [ ] Step 3: 写入 `docs/protocol.md`（每条注明来源文件与行号） +- [ ] Step 4: 提交 + +### Task 3: APK 反编译与互证 + +**Files:** +- Create: `analysis/apk/notes.md`, 修改 `docs/protocol.md` + +- [ ] Step 1: jadx 反编译到 `analysis/apk/jadx-out/`（不入库）；搜索 `BluetoothGattCharacteristic`、`writeCharacteristic`、UUID 常量、激活码网络请求 +- [ ] Step 2: 与 Web 端逐项比对协议字段；差异写 DECISIONS.md +- [ ] Step 3: 整理功能清单（时钟模式/倒计时/传图抖动算法/6 模板/睡眠/停车牌/WiFi 配置/高级命令）入 `docs/protocol.md` 附录 +- [ ] Step 4: 提取图像处理参数（4.2寸=400x300，三色屏 B/W/R 通道编码方式） +- [ ] Step 5: 提交 + +### Task 4: DA14585 固件分析 + +**Files:** +- Create: `analysis/firmware/disasm.py`, `docs/firmware-analysis.md`, 修改 `docs/architecture.md` + +- [ ] Step 1: 解析镜像头（0x70 0x51 'pQ' 签名、长度、校验），定位加载基址（向量表显示 0x07FCxxxx） +- [ ] Step 2: capstone 反汇编（Thumb, Cortex-M0），定位：GATT 属性表（UUID 字节型匹配）、命令解析跳转表、SPI 墨水屏驱动初始化序列、SUOTA 服务 +- [ ] Step 3: 与 protocol.md 互证命令集；记录墨水屏型号线索（4.2" 400x300 三色 → SSD16xx/UC81xx 系驱动 IC 初始化序列比对） +- [ ] Step 4: 写 `docs/firmware-analysis.md`（内存布局、关键函数偏移、镜像校验算法）+ `docs/architecture.md` +- [ ] Step 5: 提交；**G1 门禁检查** + +--- + +## P2：CLI 上位机（Task 5–9） + +### Task 5: BLE 传输层 + 协议编解码（TDD） + +**Files:** +- Create: `src/ppclock/protocol.py`, `src/ppclock/transport.py`, `tests/test_protocol.py` + +**Interfaces:** +- Produces: `encode_command(cmd: int, payload: bytes) -> bytes`、`decode_notification(data: bytes) -> dict`、`BLETransport.open/close/write/notify`（UUID 常量全部来自 docs/protocol.md） + +- [ ] Step 1: 用 Task 2/3 的真实测试向量写失败测试（编解码往返、分块序号、校验字节） +- [ ] Step 2: 跑测试确认失败 +- [ ] Step 3: 实现 protocol.py（纯函数，无 BLE 依赖） +- [ ] Step 4: 实现 transport.py（bleak 封装：扫描按名称/MAC 过滤、连接、MTU 协商、写+等通知） +- [ ] Step 5: 测试全绿后提交 + +### Task 6: 图像管线 + +**Files:** +- Create: `src/ppclock/image_pipeline.py`, `tests/test_image.py` + +- [ ] Step 1: 失败测试：400x300 输入 → 设备原生位平面字节流（对照 APK 提取的编码：B/W/R 通道映射、扫描方向、字节序） +- [ ] Step 2: 实现六种抖动（Floyd-Steinberg/Atkinson/Bayer/Stucki/Jarvis-Judice-Ninke/无抖动阈值）+ 亮度/对比度/饱和度/旋转/缩放 +- [ ] Step 3: 全绿提交 + +### Task 7: 功能命令层（时钟/日历/倒计时/模板/睡眠/停车牌/高级命令） + +**Files:** +- Create: `src/ppclock/commands.py`, `tests/test_commands.py` + +- [ ] Step 1: 逐功能写失败测试（参数→字节流，向量来自 protocol.md） +- [ ] Step 2: 实现全部功能命令 +- [ ] Step 3: 全绿提交 + +### Task 8: CLI 入口（agent 友好） + +**Files:** +- Create: `src/ppclock/cli.py`, `src/ppclock/__main__.py`, `tests/test_cli.py` + +- [ ] Step 1: argparse 子命令：`scan / clock / calendar / countdown / image / template / sleep / parking / wifi-config / raw / ota`；全局 `--json`、`--mac`、`--timeout` +- [ ] Step 2: `--json` 输出 schema 固定（`{"ok":bool,"cmd":str,"data":...,"error":...}`），错误码文档化 +- [ ] Step 3: mock transport 的 CLI 集成测试全绿；提交；**G2 门禁检查** + +### Task 9: 真机功能对齐验证 + +- [ ] Step 1: 对照 protocol.md 功能清单逐项在真机执行 CLI（每步记录结果与抓包） +- [ ] Step 2: 缺陷修复直至全部通过；**G3 门禁检查**；提交 + +--- + +## P3：增强与固件可控（Task 10–12） + +### Task 10: 功能增强 + +- [ ] Step 1: 本地模板渲染（Pillow 离屏渲染 6 模板 → image 推送，摆脱 App 画布） +- [ ] Step 2: `schedule` 子命令：定时/周期推送（cron 友好，单次执行语义，调度交给系统） +- [ ] Step 3: `batch` 子命令：JSONL 批量执行，面向 agent 编排 +- [ ] Step 4: 测试+提交 + +### Task 11: 固件可控工具链 + +**Files:** +- Create: `tools/fw_info.py`, `tools/fw_pack.py`, `tests/test_fw.py` + +- [ ] Step 1: 失败测试：解析原始镜像头字段与校验；重打包字节级一致 +- [ ] Step 2: 实现 fw_info（解析/校验）与 fw_pack（修改后重算校验生成可烧录镜像） +- [ ] Step 3: SUOTA 流程写入 docs/firmware-analysis.md（服务 UUID、握手、分块、CRC） +- [ ] Step 4: 全绿提交；**G4 门禁检查** + +### Task 12: 最终验收 + +- [ ] Step 1: 断网环境跑通 CLI 全部命令（除 apt/pip 外）→ **G5** +- [ ] Step 2: 写 README.md（安装/使用/离线说明）与 docs/architecture.md 终稿 +- [ ] Step 3: 对照任务说明三条目标逐项验收，更新 PROGRESS.md，提交 + +--- + +## Self-Review 记录 + +- 规格覆盖：任务说明目标1→P1；目标2→P2+P3-Task10；目标3→P1-Task4+P3-Task11。✔ +- 已知风险：真机不在手时 Task 9 降级为协议仿真测试（以 APK/Web 证据为准），在 PROGRESS.md 显式标注。 +- 占位符扫描：无 TBD/TODO。