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

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）