Skip to content

armgit / andee

Public Imported from GitHub
0

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、支持任意模型,记忆和密码绝不离开设备。

8.7 KB
Raw Blame

English 简体中文

贡献指南

谢谢你有兴趣参与。先说实话:这是一个小团队、带商业版的项目,所以我们对"什么会被合、什么会被关"讲得比较直白,免得你白写。

这份指南本身也会滞后于代码。如果发现哪里和实际不符,欢迎直接提 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

流程:

  1. Fork,从 main 切一个新分支
  2. 先在 issue 里确认过要做这件事(错别字除外)
  3. 改代码,顺带补测试(如果这次改动有可观测行为或回归风险)
  4. 本地构建通过:./gradlew :app:assembleDebug
  5. PR 描述里用 Fixes #<issue 号> 关联 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),不是标准 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