docs: 项目级规则 review 打结——GOVERNANCE §2/§5 更新至 0.2.0-beta 现实、PROGRESS 快照标注、Task9 实机完成、DECISIONS 去重标注与留痕、README 依赖补 qrcode

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## [治理] — 2026-08-02
+
+项目级规则 review 打结（非产品变更）：GOVERNANCE §2 目录结构/§5 工具链更新至 0.2.0-beta 现实（jadx→androguard、pyproject 为依赖准绳、交付物扩展为 SDK+CLI+bridge+MCP+examples）、PROGRESS 首日快照误标"最终状态"更正、详细计划 Task 9 标实机完成、DECISIONS 条目 18 标注被取代、README 依赖声明补 qrcode。
+
+
 ## [0.2.0-beta] — 2026-07-31
 
 新增 **ppclock-mcp**：跑在蓝牙物理所在机器上的单层 MCP 服务器，agent 经 stdio 或

DECISIONS.md

@@ -15,7 +15,7 @@
 | 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 重试）跨窗口执行 |
-| 2026-07-29 | **SUOTA 状态码 8/16 = 会话信息码而非失败**（仅本固件） | 反汇编 MEM_DEV handler（0x07FCB6F8）：type 0x13 命中 bit4 位测试 → 发状态 16 且 SPOTA 状态保持（0x07FCB770-0x07fcb772）；type 0x12 → 状态 8 并清会话（0x07FCB780）；空镜像探针与正式烧录均先收 16 后流程完好 | bridge ota 对 8/16 记录并继续，块确认只认 2；APK 错误表未覆盖 16，以固件证据为准 |
+| 2026-07-29 | **SUOTA 状态码 8/16 = 会话信息码而非失败**（仅本固件）〔本条被 2026-07-29 第 5 条（状态码分两类）取代，保留溯源〕 | 反汇编 MEM_DEV handler（0x07FCB6F8）：type 0x13 命中 bit4 位测试 → 发状态 16 且 SPOTA 状态保持（0x07FCB770-0x07fcb772）；type 0x12 → 状态 8 并清会话（0x07FCB780）；空镜像探针与正式烧录均先收 16 后流程完好 | bridge ota 对 8/16 记录并继续，块确认只认 2；APK 错误表未覆盖 16，以固件证据为准 |
 | 2026-07-29 | bridge OTA 大请求需显式 StreamReader limit | asyncio 默认 64KiB 行限制，OTA 镜像 hex 请求 ~144KB 永不可达（三轮"静默停滞"根因）；空镜像探针 0.6s 全通证明管线无恙 | build 9: start_server(limit=4MiB)；教训：大载荷 RPC 协议设计必须考虑传输层帧限 |
 | 2026-07-29 | **SUOTA 状态码分两类：会话信息码（8/16）与流程错误码**；16=MEM_DEV type 0x13 位测试应答（固件 0x07FCB770），状态保持 | 反汇编 MEM_DEV handler + 三轮烧录对照（16 恒在 MEM_DEV 后 ~1s 到达，块未受影响） | bridge 对 8/16 记录继续、块确认只认 2；APK 表未覆盖 16，固件证据为准 |
 | 2026-07-29 | **SUOTA 状态 22/20 根因分层**：22=0x38000 产品头读电气失败（GPIO_MAP 引脚错）；20=读成功但非 'pR'（引脚有效、0x38000 疑为空） | GPIO 探针（max_blocks=2 安全模式）：A{00,00,06,05}→22、B{40,00,06,05}→22、C{05,06,00,40}→20；C=APK 整数 0x05060040 的 BE 字节，为唯一电气有效候选 | GPIO_MAP 采用 C（BE 序）；剩余阻断=0x38000 产品头（'pR'）缺失/无效，见下条 |
@@ -30,3 +30,4 @@
 | 2026-07-31 | `--allowed-hosts ""` 空串按 None 处理 | 空串逗号拆分得空列表，`TransportSecuritySettings(allowed_hosts=[])` 启用防护后连 localhost 族也 421（自锁） | main() 解析层 `_parse_allowed_hosts` 以 `or None` 归一，保持 mcp 默认 localhost 族；含回归测试 |
 | 2026-07-31 | **双 TransportError 历史包袱在 MCP 层适配，SDK 零改动** | `transports.base.TransportError` 与 `transports.local.TransportError` 同名但互不继承（历史包袱）；真实 bleak 写/读路径还裸抛 `BleakError` 不包装 | 改 SDK 会动公开语义、风险大于收益；MCP 层 `device_manager.py:19-26` 以 `TRANSPORT_ERRORS` 全家捕获兜底（base/local 两类 + BleakError + OSError + asyncio.TimeoutError），掉线判定不漏形态 |
 | 2026-08-01 | 建立 Gitea 远端（chenwei/qianbian）并增补 Git 协作治理（GOVERNANCE §6） | 用户要求版本控制上云 + 后续治理迭代；此前仓库仅本地 | main 主干直提、分支短命、身份诚实不改写、推送前三项检查（净树/全绿/无 secret）、大文件仅原始输入随库。**远端落地**：origin=git@git.b.aeroprop.xyz:chenwei/qianbian.git（实例 git.b.aeroprop.xyz，展示域 git.banytech.com）；认证=本机 ~/.ssh/id_ed25519（Gitea key 名 chenwei@bany.tech@openclaw-server）；2026-08-02 全历史已推送（ls-remote 校验一致） |
+| 2026-08-02 | 项目级规则 review 打结：8 项不一致修复（PROGRESS 首日快照误标"最终状态"、GOVERNANCE §2 目录/§5 工具过期、PLAN P0 jadx、详细计划 Task 9 终态、DECISIONS 条目 18/20 重复标注、README 依赖缺 qrcode） | 用户要求规则 review；项目已从 0.1.0 演进至 0.2.0-beta（SDK/MCP/bridge/实机验证），多文档口径落后于现实 | 规则文件必须与交付现实一致；不改写历史（快照保留标注、重复条目保留溯源），仅修正指向与口径；GOVERNANCE 变更按 §4 留痕本条 |

GOVERNANCE.md

@@ -18,25 +18,35 @@ qianbian/
 ├── PLAN.md                # 总体规划与阶段验收标准（指向 docs/superpowers/plans/）
 ├── PROGRESS.md            # 实时进度日志：每次工作会话结束必须更新
 ├── DECISIONS.md           # 决策日志：每条决策含日期、背景、结论、理由
+├── CHANGELOG.md           # 产品变更记录（release 口径）
+├── llms.txt               # AI 消费向项目卡（随发布同步）
 ├── app/                   # 原始输入物（APK、固件，只读，不得修改）
 ├── docs/                  # 所有分析文档
 │   ├── architecture.md        # 软硬件架构总述
 │   ├── protocol.md            # BLE 协议规范（最终单一事实来源）
 │   ├── firmware-analysis.md   # 固件逆向笔记
-│   └── superpowers/plans/     # 详细实现计划
+│   ├── firmware-layout.md     # 闪存布局（裸/工厂）与 SUOTA 门禁
+│   ├── field-test-plan.md / field-test-result.md  # 全链路测试计划与实测
+│   ├── sdk/                   # API.md（签名级）/ MCP.md（MCP 服务器）
+│   └── superpowers/{plans,specs}/  # 详细实施计划与设计规格
 ├── analysis/              # 逆向中间产物（反编译输出、脚本、抓包等）
 │   ├── apk/                   # APK 反编译产物（不入库的大文件除外）
 │   ├── firmware/              # 固件反汇编/提取产物
 │   └── web/                   # Web 上位机抓取产物
-├── src/ppclock/           # 本地 CLI 上位机（交付物）
-├── tools/                 # 固件处理等辅助工具（交付物）
-└── tests/                 # CLI 与工具的自动化测试
+├── src/ppclock/           # 交付物：SDK+CLI（PPClient/ppclock）
+│   ├── transports/            # base/local(bleak)/bridge(RPC) 传输层
+│   ├── firmware/              # 镜像解析重打包 + SUOTA
+│   ├── bridge_server.py       # ppclock-bridge 服务端
+│   └── device_manager.py / mcp_server.py / mcp_tools.py  # ppclock-mcp
+├── tools/                 # 辅助工具（fw 垫片/field_test/gpio_probe 等）
+├── examples/              # 示例与测试夹具（jsonl 批量、测试图）
+└── tests/                 # 自动化测试（当前 208 项）
 ```
 
 规则：
 - `app/` 内原始文件**只读**；所有修改副本放 `analysis/`。
 - 每个分析结论必须写明证据（文件偏移 / 代码位置 / 抓包数据），禁止无证据断言。
-- 交付物只有两类：`src/ppclock`（CLI）与 `tools/`（固件工具）+ `docs/`（文档）。
+- 交付物：`src/ppclock`（SDK+CLI+bridge+MCP）、`tools/`、`examples/`、`docs/`。
 
 ## 3. 验证门禁（每个阶段必须满足才算完成）
 
@@ -60,8 +70,10 @@ qianbian/
 
 ## 5. 工具与环境
 
-- 分析环境：Python 3.12（venv 于 `.venv/`）、jadx、capstone、bleak。
-- 依赖锁定：`requirements.txt` 固定版本；新增依赖需记录于 DECISIONS.md。
+- 分析环境：Python 3.12（venv 于 `.venv/`）、androguard（APK）、capstone（固件反汇编）、bleak（BLE）。
+  （注：jadx 因下载策略未采用，APK 分析全程 androguard。）
+- 依赖声明以 `pyproject.toml` 为准（runtime：bleak/pillow/qrcode；extras：dev/mcp）；
+  `requirements.txt` 为其冻结镜像。新增/升级依赖需记录于 DECISIONS.md。
 - 外部工具一律装在本机，不修改系统关键组件。
 
 ## 6. Git 与远端协作（2026-08 增补，DECISIONS 2026-08-01）

PLAN.md

@@ -7,7 +7,7 @@
 
 | 阶段 | 目标 | 对应任务说明 | 门禁 |
 |------|------|--------------|------|
-| P0 工具链 | venv + jadx/androguard/capstone/bleak | — | 自检全 OK |
+| P0 工具链 | venv + 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

@@ -1,6 +1,10 @@
 # 进度日志 (PROGRESS)
 
-## 2026-07-24（最终状态）
+> **最终状态以 2026-07-29 收官节与后续各节为准**。本节（2026-07-24）为首日快照，
+> 其中 G3/G4 的"协议级/工具级"标注已被 2026-07-28/29 实机验证超越：G3 ✅实机（除 K1 停车牌待查）、
+> G4 ✅路径B达标、测试 132→208、交付物扩展为 SDK+CLI+bridge+MCP。
+
+## 2026-07-24（首日快照）
 
 ### 已完成（对照门禁）
 

README.md

@@ -12,7 +12,7 @@ Python SDK（`PPClient`）+ CLI（`ppclock`）+ BLE 桥（`ppclock-bridge`），
 
 ```bash
 python3 -m venv .venv
-.venv/bin/pip install -e ".[dev]"   # 依赖：bleak、pillow（dev: pytest、pytest-asyncio）
+.venv/bin/pip install -e ".[dev]"   # 依赖：bleak、pillow、qrcode（dev: pytest、pytest-asyncio）
 ```
 
 运行要求：蓝牙适配器（本机 bleak）**或** 他机蓝牙经 `ppclock-bridge` 桥接。**不需要互联网**。

docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md

@@ -130,9 +130,9 @@ apt-get install -y jadx 2>/dev/null || (cd /opt && curl -sL -o jadx.zip https://
 - [x] Step 2: `--json` 输出 schema 固定（`{"ok":bool,"cmd":str,"data":...,"error":...}`），错误码文档化
 - [x] Step 3: mock transport 的 CLI 集成测试全绿；提交；**G2 门禁检查**
 
-### Task 9: 真机功能对齐验证 —— ⚠ 降级（无设备在 BLE 范围内，2026-07-24）
+### Task 9: 真机功能对齐验证 —— ✅ 完成（2026-07-28/29 实机）
 
-- [ ] Step 1: 对照 protocol.md 功能清单逐项在真机执行 CLI（每步记录结果与抓包）——**待设备到场执行**
+- [x] Step 1: 对照 protocol.md 功能清单逐项在真机执行 CLI（每步记录结果与抓包）——**2026-07-28/29 经 bridge 实机完成**（六步全过+扩展 12 步+六抖动+六模板，记录 docs/field-test-result.md；K1 停车牌待查为唯一遗留）
 - [x] Step 2（降级）: 以 FakeTransport 逐帧断言 + 三线证据互证替代（tests/test_cli.py、test_commands.py）；G3 以协议级达标记录于 PROGRESS.md
 
 ---