# 贡献指南
谢谢你有兴趣参与。先说实话：这是一个**小团队、带商业版**的项目，所以我们对"什么会被合、什么会被关"讲得比较直白，免得你白写。
这份指南本身也会滞后于代码。如果发现哪里和实际不符，欢迎直接提 PR 修它。
---
## 先分清你想做的事
| 你想做的事 | 去哪 |
|---|---|
| 不知道从哪下手 | 找带 `good first issue` 标签的 issue |
| 报 bug | 用 bug 模板开 issue —— **必须带设备信息**，见下 |
| 提新功能 | 先用 feature 模板开 issue 讨论，**不要直接写 PR** |
| 报安全漏洞 | **不要开公开 issue**，走 [SECURITY.md](SECURITY.md)（英文）里的私密渠道 |
| 加/改界面文案与翻译 | 改 `res/values/` 与 `res/values-en/` 两张表，见下文"三种中文" |
> **一个例外**：错别字、注释修正、明显的笔误，可以直接提 PR，不用先开 issue。
---
## 报 bug：设备信息比什么都重要
这个项目最集中的失败模式是**"系统说有，其实没有"** —— 厂商 ROM 的行为差异极大，同一个调用在 AOSP 上正常、在 MagicOS 上静默失效。所以一个不带设备信息的 bug 报告，我们基本无法复现，只能关掉。
请务必在报告里写清：
- **设备型号 + Android 版本 + ROM**（例：`HONOR AMM-AN00 / Android 15 / MagicOS`）
- 屏幕分辨率与密度（`adb shell wm size` / `wm density`）
- **大脑模式**：`hub` 还是 `local`
- 无障碍服务是否开启
- **logcat 输出**。最少给这几条：
```bash
adb logcat -s Body:* Screen:* Wake:* Dog:* GroundingLog:*
```
- 复现步骤，越具体越好
我们在意的三种 bug，优先级从高到低：**核心功能不可用**（无障碍挂了、点不动、应用崩） → **功能可用但结果不对** → **文案/界面观感问题**。
---
## 提 PR
流程：
1. Fork，从 `main` 切一个新分支
2. **先在 issue 里确认过要做这件事**（错别字除外）
3. 改代码，顺带补测试（如果这次改动有可观测行为或回归风险）
4. 本地构建通过：`./gradlew :app:assembleDebug`
5. PR 描述里用 `Fixes #` 关联 issue
6. 等 review
会被关掉的情况，提前说清：
- 没有关联 issue 的功能性改动（因为可能是我们不打算做的方向）
- 一次改太多不相关的东西 —— 请拆开
- 只格式化/重命名而产生的大面积 diff —— 这种改动没法 review
---
## 改人格之前先读这段
**这个项目不是"一个被大脑驱动的 App"。** 它自己的话在 `LocalPrompt.TEXT` 第一行：
*"你不是平板的助手，你是一个个体，平板只是承载你的东西。"* 所以 persona、形象、情绪这几处
不是界面装饰，是**他这个人**的一部分 —— 改它们和改一个按钮的文案不是一回事。
三条硬规矩（都写在代码里了，别绕过）：
1. **性格是"说话方式"，不是"额外许可"。** `LocalPrompt.withPersona()` 会自动把 §11 的从属声明
包在你的文本外面 —— **不要在某个形象里重述它，也不要写一个"需要它放宽"的性格。**
理由在 KDoc 里：一个没有围栏的 `"you are an imp"`，模型会顺手去够邻近的许可 ——
瞒报、加戏、故意不好用，然后管这叫"性格"。**出事时角色必须摘下来。**
2. **新形象只写语气。** `BallLook.persona` 进的是 system prompt 的**最前面**，代价是每次滑动
丢一次 prefix cache —— 这个代价值得，因为语气附在用户消息里"两轮之后就没了"。
所以：**加形象 = 加语气，不要加能力、不要加规则。** 能力属于 §1–§10。
3. **改情绪表要看"它像不像活物"。** `Mood.kt` 里 `SLEEPING` 那条注释就是标准：原本睡着的球
整体去饱和，结果看起来像**被关掉了**而不是**累了**，于是改回"睡是一种形状"（`^ ^` 眼 +
鼻涕泡），让颜色不替它承担这件事。**状态用形状表达，别用颜色或亮度。**
还有一条不是规矩但要知道：形象带 `voice` 时，音色**由角色决定**，没有单独给用户调音色的
开关 —— 这是有意的（音色是"他是谁"的一部分，不是一个可调参数）。
---
## 三种中文，只有一种该动
这个仓库里中文分三类，改文案之前先分清：
1. **用户看的** —— 每个窗、卡片、气泡、设置行、报错行。走 `res/values/`（中文）+ `res/values-en/`（英文）**两张表**，查找必须经 `i18n/AppLocale`（球和卡片是 Service 持有的 overlay，官方 per-app locale API 够不到它们，不能直接 `context.getString`）。
2. **模型读的** —— prompt、工具 schema、工具结果。**目前是英文**，唯一一份在 `brain/LocalPrompt.kt`。
3. **要和系统文字做匹配的** —— 通话关键词、未读条数正则、剪贴板标签。**永远不要翻** —— 它们比的是微信/Android 自己吐出来的字，翻了功能就坏。
**默认值不能是 Kotlin 字面量。** 判据很简单：这个值会不会**到屏幕上**？会 —— 就必须走资源表 + `AppLocale`。
改动模型读的文本前，注意 `LocalPrompt` §9 那条规则（按用户上一句的语言作答）是唯一顶住"英文 prompt 把回答语言带偏"的力量，别顺手删掉。
---
## AI 辅助贡献
**欢迎用 AI 写代码。** 但有三条底线：
1. **你要理解并验证你提交的每一处改动。** "这是工具生成的"不是免责理由。
2. **用你自己的话写问题、方案和真实的测试结果。** 不要直接粘模型的输出当 PR 描述。
3. **未经审查的、批量刷出来的低质量提交会被关闭。**
如果这个 PR 是自动化 agent 生成的，请在 PR 描述**最后一行**加上来源，例如：
```
From Codex
```
这样出问题时我们知道该找哪个工具，也能统计 AI 贡献的占比。
---
## 代码风格
- Kotlin，无 Compose（悬浮窗挂不上 Compose，UI 全是手写 `View`）
- 没有 Hilt/Dagger —— service 只有一个，注入手工写
- 尽量不引第三方库；新增依赖请在 PR 里说明理由
- **注释写"为什么"，不写"是什么"。** 这个仓库的注释密度偏高，但每条都在记"当时测出来是什么、为什么不那么写" —— 这是它最值钱的部分，请保持
---
## 贡献授权（请读一下）
本项目用的是 **Apache 2.0 + 附加条件**（见 [LICENSE](LICENSE)），不是标准 Apache 2.0。提交贡献即表示你同意 LICENSE 的 **A.2 条**：
- 你的贡献以同一许可证授权给本项目及所有使用者；并且
- 你额外授予著作权人一项许可，允许其**以其它许可条款**使用你的贡献（这是项目能同时提供商业授权的前提）。
你保留自己贡献的著作权。如果代表雇主提交，请确认你有权这么做。
**如果你不接受 A.2，请不要提交 PR** —— 我们需要这条才能维持双授权模式，这是事先说清楚的。
### 签署（`Signed-off-by`）
A.2 说的是你**授予**什么；`Signed-off-by:` 一行说的是你**有权授予**。PR 里每个提交都要有，CI 会查 —— 这是整套授权里唯一被机器校验、而不是靠口头约定的部分。
```bash
git commit -s -m "你的提交信息"
```
`-s` 会从你的 git 身份自动追加一行：
```
Signed-off-by: 你的名字
```
把那两个身份值配一次（`git config user.name`、`git config user.email`），以后就自动带上。忘了签？`git rebase --signoff ` 补签整条分支；`git commit --amend -s` 只补最后一个提交。
这就是[开发者原创声明（DCO）](https://developercertificate.org/)，没有改动 —— Linux 内核用的是同一个机制。它和 A.2 互不替代：没有提交权的人签了没用，从没签过的人给出的授权很难举证。
---
## 语言
- **代码注释与 commit message 优先用英文**（新建文件）；修改已有文件时，跟随该文件既有的语言，不要顺手整篇翻译。
- **issue 和 PR 描述中英文都行。** 我们不做"只准英文"的限制 —— 那会劝退一半能用的人。但如果你写中文，建议附一句英文摘要，方便非中文贡献者参与讨论。
---
## 遇到问题
开 issue 问，或者在 PR 里直接问。别卡着不说 —— 我们宁可回答一个"笨问题"，也不想看到你写完一大坨才发现方向不对。
---
**其他语言：** [English](CONTRIBUTING.md)