# 项目治理规则 (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`。