87 lines
6.3 KiB
Markdown
87 lines
6.3 KiB
Markdown
# 项目治理规则 (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`。
|