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           # 决策日志：每条决策含日期、背景、结论、理由
├── app/                   # 原始输入物（APK、固件，只读，不得修改）
├── docs/                  # 所有分析文档
│   ├── architecture.md        # 软硬件架构总述
│   ├── protocol.md            # BLE 协议规范（最终单一事实来源）
│   ├── firmware-analysis.md   # 固件逆向笔记
│   └── superpowers/plans/     # 详细实现计划
├── analysis/              # 逆向中间产物（反编译输出、脚本、抓包等）
│   ├── apk/                   # APK 反编译产物（不入库的大文件除外）
│   ├── firmware/              # 固件反汇编/提取产物
│   └── web/                   # Web 上位机抓取产物
├── src/ppclock/           # 本地 CLI 上位机（交付物）
├── tools/                 # 固件处理等辅助工具（交付物）
└── tests/                 # CLI 与工具的自动化测试

规则：

• app/ 内原始文件只读；所有修改副本放 analysis/。
• 每个分析结论必须写明证据（文件偏移 / 代码位置 / 抓包数据），禁止无证据断言。
• 交付物只有两类：src/ppclock（CLI）与 tools/（固件工具）+ 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/）、jadx、capstone、bleak。
• 依赖锁定：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。