qianbian/GOVERNANCE.md

项目治理规则 (GOVERNANCE)

本文件是本项目的最高工作准则。任何会话、任何子代理开始工作前必须先读本文件与 PLAN.md。 修改本文件需在 DECISIONS.md 中记录理由。

1. 项目目标（来自 任务说明.md，不得偏离）

1. 依据现有资料、固件与 APK，摸清 4.2 寸墨水屏设备（DA14585）的软硬件架构，并在此基础上实现改进功能。
2. 在已有架构基础上实现本地化（无需互联网）、可 CLI（面向 agent 化），并在已实现功能基础上添加必要功能。
3. 实现软硬件（硬件指 firmware）可控。

2. 目录结构与归属

qianbian/
├── 任务说明.md            # 原始需求（只读，不得修改）
├── GOVERNANCE.md          # 本文件
├── 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   # 固件逆向笔记
│   ├── 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/           # 交付物：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（SDK+CLI+bridge+MCP）、tools/、examples/、docs/。

3. 验证门禁（每个阶段必须满足才算完成）

门禁	标准
G1 架构摸清	docs/architecture.md + docs/protocol.md 完成；三个来源（Web/APK/固件）对协议关键字段互证一致，不一致处显式标注
G2 CLI 可用	pytest 全绿；CLI 在无网络环境（除 BLE 外）完成全部核心命令；--json 输出稳定 schema
G3 功能对齐	CLI 覆盖 Web 上位机已实现的全部功能（对照 docs/protocol.md 功能清单逐项勾选）
G4 固件可控	能解析固件镜像结构、能修改并重新生成可烧录镜像（校验和正确），SUOTA 流程文档化
G5 离线交付	交付物运行不依赖任何互联网资源；安装/使用文档本地化

4. 工作纪律

1. 版本控制：一切入 git。每个任务完成即提交；提交信息说明"做了什么、证据是什么"。
2. TDD：CLI 协议编解码层先写测试再写实现；测试向量必须来自真实证据（反编译代码或抓包），禁止臆造。
3. 文档同步：协议/架构发现先落文档再写代码；发现与既有文档冲突时，以新证据为准并立即改文档。
4. 进度日志：每次会话结束更新 PROGRESS.md（做了什么、下一步、阻塞点）。
5. 原始输入保护：不修改 app/ 与 任务说明.md。
6. 安全边界：分析仅限本项目提供的设备/固件/APK；不攻击厂商服务器、不绕过激活码服务器的线上逻辑（激活机制仅做本地分析与本机绕过研究，用于脱离云依赖）。
7. 语言：文档与提交信息用中文；标识符用英文。

5. 工具与环境

• 分析环境：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）

1. 远端：Gitea 实例，chenwei 账户下同名仓库 qianbian（remote 名 origin）。URL 见 DECISIONS.md 2026-08-01 条目。
2. 分支策略：main 为唯一主干，直接提交；实验性大改动用 <topic> 短分支，回合并即删。不使用 force push 改写 main 历史。
3. 提交身份：agent 工作用 agent <agent@local>，人工工作用本人身份——不混用、不改写历史身份，保证溯源诚实。
4. 推送前检查：工作树干净、pytest 全绿、无新增 secret（token/私钥/真实密码）。测试用口令（如 pw123456）允许但必须在测试/文档语境。
5. 大文件：app/ 原始输入（APK 9.3MB、固件 72KB）随库分发（项目自包含要求）；其余 >1MB 产物须为文档/证据类文本，二进制中间产物一律 gitignore + 再生方法入库（analysis/README.md）。
6. 同步纪律：每个工作会话开始先 git pull --ff-only；结束前提交并 git push。冲突时以远端为准 rebase 本地未提交改动，禁止 --force。