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