# 贡献指南

[English version](CONTRIBUTING.en.md)

本仓是 DeepSeek Harness 的安卓壳。参与前先读 [`AGENTS.md`](AGENTS.md)：它描述壳侧项目地图、构建命令、设备验收规范与文档维护协议。

## 仓库边界

- 本仓负责壳侧 Kotlin、桥协议、无障碍与虚拟屏、Shizuku 通道、构建门禁与发布链。
- 引擎侧插件、注入层与快照配置在协调仓 `kelai141/dsh-mobile`（私有）。外部贡献者只需关注本仓；涉及协调仓的改动由维护者同步。
- 上游 `deepseek-harness` 只读，适配一律走补丁、插件或壳侧。

## 提交与分支

- 默认分支 `main`，禁止直接 push，所有改动走分支与 PR。
- 分支名 `<类型>/<短描述>`；提交信息 `<类型>: <描述>`，类型取 `feat` / `fix` / `docs` / `chore` / `refactor` / `test` / `ci`。
- 一个 PR 只做一件事，可以独立回退。

## 经验记录

坑位与排查结论不要全部堆进同一个文件。本仓的 `docs/AGENTS/gotchas.md` 是团队共用的汇总库，由维护者合并稳定结论；日常记录写在自己的文件里，按 GitHub 账号命名：

```
docs/contrib/<github-account>/YYYY-MM-DD-<topic>.md
```

一条记录写全四件事：现象、真因、修法与复验证据。只写「怎么做」的条目，下次遇到同一个坑仍然救不了人。与具体个人无关、可复用的结论由维护者汇总进 `docs/AGENTS/` 对应详档，原文保留并注明出处。

## 新增界面必须中英双语

项目的用户并不都读中文。凡**新增**的自定义界面（页面、面板、弹窗、浮层、设置项、通知渠道名与说明、错误提示、按钮与占位符）同时提供中文与英文：

- 页面侧插件走现有 locale 通道：同一 namespace 同时注册 `zh` 与 `en` 字典，键集合与占位符一致。
- 壳侧原生界面在 `strings.xml` 或 Kotlin 文案里补英文对应项。
- 语言切换后界面即时更新，不缓存启动时读取的一次性字符串。
- 机器码、内部 key、枚举值不上屏。只有中文的界面视为未完成。存量界面不强制回溯，但被你重写或扩写的那块要补齐两种语言。

## PR 要求

标题与描述用中文或中英双语，句子短、能读懂。描述说明改动、原因、验证与影响面；没有做打包后设备验证时明确写「未做设备验证」。PR 模板里的状态登记四栏照实填写，没有跨层状态改动就填「无」并说明理由。

证据按风险给最小但充分的一份：

| 改动类型 | 需要的证据 |
|---|---|
| 文档、注释 | 自检通过，无需构建 |
| 门禁、构建脚本 | 该门禁的 `--self-test` 加一条受控负控 |
| 安全敏感面（快照事务、签名、门禁判据、桥协议） | 代码层、CDP 层、ADB 用户层三层验收，当轮完成 |
| 界面、壳侧行为 | 模拟器三层验收，竖屏与横屏各一次 |

贴命令与关键输出。测试没跑就写没跑。

## 提交前自审

推送前把差异完整读一遍，只暂存本次涉及的文件（不要 `git add .`），并确认下面命令输出干净：

```powershell
git diff --check
git diff --stat
git status --short
git diff --cached --stat
```

检查项：没有调试残留与本机路径；没有凭据、设备序列号；新增界面在中英文下各看过一次；提交信息与改动一致；PR 描述里的验证确实跑过；标题与描述读得通；标签 1 到 3 个。

合并后删除分支。