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

chore(release): v0.5.0

booboosui143c7bd7c450
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd8f17d..6c2ed6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ Notable changes to Andee. The format follows [Keep a Changelog](https://keepacha
## Versioning policy
-- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`8` / `"0.4.1"`**.
+- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`9` / `"0.5.0"`**.
- Releases are tagged `vMAJOR.MINOR.PATCH`, `versionName` mirrors the tag without the leading `v`,
and `versionCode` increases by one per release. `versionCode` must increase **monotonically** or
Android refuses the upgrade; the same number must never be reused for two different builds.
@@ -28,6 +28,58 @@ hash into `versionName` at build time would close this hole; it is not implement
## [Unreleased]
+## [0.5.0] - 2026-10-16
+
+**A finished conversation is now something the device puts away and can read back.** That is the new
+capability this release is numbered for — a stretch of talking that has ended stops costing context on
+every later request, and stops being lost with it. Two smaller changes ride along: a choice card's
+question and answer now land in the scrollback, and the README explains what signing is actually
+protecting.
+
+### Added
+
+- **Topics: a finished stretch of conversation is folded away and can be picked back up.** A topic that
+ has ended was the most expensive thing in every later request and the least likely to be needed
+ again. The nightly review now marks where topics begin and end among the user's numbered turns
+ (`fold_topic`), the device validates the range and swaps it for a one-line marker **after the turn
+ it names**, and the verbatim conversation is archived so it can be read back. Three tools, all
+ `localOnly`: **`fold_topic`** (review-only — an ordinary turn that calls it is refused, because
+ folding is irreversible from the model's side and a request is not the moment to spend it),
+ **`list_topics`** (id, title, when it ended, how many messages), and **`get_topic`** (the whole
+ back-and-forth as plain text, truncated past a limit with `truncated` saying so).
+ The device refuses a fold **with a reason** — a turn number that is not in the list, a range that
+ ends at the latest turn (nothing has started after it, so nothing says it ended), something inside
+ still waiting on an answer, an overlap with a topic already put away, too short, or a scene active —
+ and the reason names the condition rather than inviting a retry. **At most three topics per review**,
+ and they are put away when the review ends rather than when the tool is called.
+ In the scrollback a folded topic is **a card standing where its messages stood** — the summary shown
+ by default, with **Continue**, **Transcript** and **Made here**. Continuing inlines the archived
+ conversation into the next turn; the transcript opens fullscreen (and says so honestly when the text
+ has been cleared and only the summary is left); *Made here* reopens the pages produced inside that
+ topic, each with its version. The summary's fourth line is deliberately **what the model left out**,
+ because a summary that reads complete is one whose details are lost — `list_topics`' own description
+ tells the model never to answer a question about a folded topic from its one-liner alone, and never
+ to say it did not happen. `debug.sweep` (loopback only) runs the review on demand for testing.
+
+### Fixed
+
+- **A choice card's question and answer now land in the scrollback.** `ui.ask` spoke the question and
+ handed the chosen option straight to the brain, so the card came and went and the conversation showed
+ the brain acting on a choice nobody could see being made. The question is an Andee row now and the
+ answer — the button, or the words said instead — is a row of the user's. A timeout writes nothing,
+ because nothing was chosen.
+
+### Changed
+
+- **The README says what signing is for.** The signature is the only thing stopping a fake "update"
+ from installing over a user's copy and inheriting the accessibility service, the secure-settings
+ grant and everything in the vault. That is now stated where signing is already discussed, along with
+ why a per-machine debug key is what produces `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
+- **The tool count in the READMEs and the DISCLAIMER is no longer a number.** Both said "sixty-odd
+ tools", which was accurate when written and had drifted to seventy-two. The sentences now describe
+ what the tools do and say "a few dozen", because a count in prose is a count that goes stale — the
+ same lesson the versioning policy above already learned once.
+
## [0.4.1] - 2026-10-15
A day of fixes and one feature pair, and the version number is **a deliberate departure from the
diff --git a/CLAUDE.md b/CLAUDE.md
index 74afcdf..47d59ca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,6 +98,21 @@ Consequence: **adding a tool means editing both `ToolSchemas.kt` and `CommandDis
⚠️ 存档里新增了 `group`/`version` 两个键,**`load()` 遇到缺 `group` 的旧记录必须 fallback 成它自己的 id**(`ChatHistory.kt:608` 的 `if (o.has("group")) o.optLong("group") else id`),**绝不能是 0** —— 那会把所有旧页面并成一个产物。`Entry` 上 `groupId = id` 的默认值同时是「新条目自成一组」的表达。
+### 话题:聊完的一段会被「收起」并可以读回来(`brain/TopicSplitter.kt` + `ChatHistory` 的 topics)
+
+**动机是上下文成本**:一段已经结束的对话,是之后每一次请求里最贵、又最不可能再用到的东西。
+`fold_topic`(**review-only**)让每晚复盘把用户编号回合里的起止标出来,设备**校验范围**后在**该回合之后**
+把它换成一行标记,逐字对话归档到 `ChatHistory` 的 topics(与 entries 分开的 `KEY_TOPICS`)。
+三个工具都 `localOnly`:`fold_topic` / `list_topics` / `get_topic`(读回全文,超 `TOPIC_TEXT_MAX = 40_000` 截断并带 `truncated`)。
+
+🔴 **几个不能踩的点**:
+- **`fold_topic` 只给复盘用**,普通回合调用会被**带理由拒绝** —— 收起在模型侧不可逆,用户提要求的那一刻不是花它的时机。
+- **设备拒绝时要「说清条件」,不是让模型重试**:编号不在列表里 / `to_turn` 是最新回合(后面没有任何东西开始,就没有东西说明它结束了)/ 里面还有等回答的东西 / 与已有话题重叠 / 太短 / 有情景在跑。
+- **最多 3 个/次**(`MAX_FOLDS_PER_REVIEW = 3`,`LocalBrain.kt:1667`,超了会**带理由拒绝**),**收起发生在复盘结束时而不是工具被调用时**;全局保留 `MAX_TOPICS = 60`(`ChatHistory.kt:350`,最旧的先删)。
+- 摘要的第 4 行**故意是「你漏掉了什么」** —— 读起来完整的摘要,就是细节已经丢了的那种。
+- `list_topics` 的描述里明确要求模型:**不许拿那一行摘要回答关于已收起话题的问题**,更不许说"这事没发生过"。
+- 回溯里折叠后的位置是一张**卡片**(`HistoryListView`),带 继续话题 / 对话记录 / 产出物;`debug.sweep`(**仅 loopback**)可按需触发复盘。
+
### The overlay-vs-gesture conflict
This is the subtlest invariant in the codebase. `ScreenController.tap/swipe/longPress` use `dispatchGesture`, which injects events into the **real touch pipeline** — so the app's own floating overlay would intercept them first. Every gesture-based command is therefore wrapped in `passthroughForGesture` (`CommandDispatcher`) or the equivalent in `ScreenBodyService.swipe`, which flips the overlay to non-touchable, **sleeps ~50 ms** (because `updateViewLayout` is posted to the UI thread and needs a frame or two to actually apply), runs the gesture, then restores. The window stays visible throughout.
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index 0730957..29d7ab5 100644
--- a/DISCLAIMER.md
+++ b/DISCLAIMER.md
@@ -46,14 +46,14 @@ The second row needs spelling out: **tool results are part of the conversation.*
**So "local mode" does not mean "processed locally."** Local mode swaps the hub for whichever provider you typed in. It does not keep a single byte on the device.
Therefore:
-- *"We do not monitor or store your data"* — **mostly true, but do not overclaim it.** No database, no behavioural analysis, and no reading of anything you send; the one exception is the version check, which tells us that some device of some model on some IP is running 0.4.1.
+- *"We do not monitor or store your data"* — **mostly true, but do not overclaim it.** No database, no behavioural analysis, and no reading of anything you send; the one exception is the version check, which tells us that some device of some model on some IP is running 0.5.0.
- *"Your data never leaves the device"* — **false. Do not claim it.**
## 3. What it can actually do (not hypotheticals — current state of the code)
**It can operate any app.** Its hands are "read the screen + tap by coordinates + type text + system actions," and the OS security policy does not stop a finger. §1 of the system prompt explicitly forbids it from treating "no dedicated tool" as "cannot be done," and lists what it reaches, including **ordering, booking and unsubscribing inside an app, changing a password, and filling in a form.**
-**It can spend money.** There is no payment tool — it does not need one; it can tap. The only thing standing between it and a completed payment is Android's own **`FLAG_SECURE`** (the screen blanks out on sensitive pages, so it cannot see). **That is the platform's protection, not this project's**, and not every app's payment flow sets it. This project has **no guardrail whatsoever** on completing a transfer by tapping: of sixty-odd tools, exactly one — `send_sms` — is marked sensitive.
+**It can spend money.** There is no payment tool — it does not need one; it can tap. The only thing standing between it and a completed payment is Android's own **`FLAG_SECURE`** (the screen blanks out on sensitive pages, so it cannot see). **That is the platform's protection, not this project's**, and not every app's payment flow sets it. This project has **no guardrail whatsoever** on completing a transfer by tapping: out of every tool it exposes, exactly one — `send_sms` — is marked sensitive.
**It can speak as you.** `send_sms`, `dial`, `open_url` (any link), and typing into any social or community app. Everything it sends is sent under your name.
diff --git a/DISCLAIMER.zh-CN.md b/DISCLAIMER.zh-CN.md
index c191fdc..b8dc994 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -45,14 +45,14 @@
**因此"本机模式"不等于"本地处理"** —— 本机模式只是把大脑从 hub 换成了你填的那个服务商。它没有让数据留在设备上,一个字都没有。
所以:
-- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.4.1"。
+- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.5.0"。
- 「您的数据不会离开设备」——**不成立,而且不要说**。
## 3. 它真的能做什么(以下都不是危言耸听,是代码里的现状)
**它能操作任何应用。** 它的手是"读屏 + 坐标点击 + 输入文字 + 系统动作",而系统的安全策略不会阻止一只手指。系统提示词 §1 明确要求它**不得**把"没有专门的工具"当成"做不到",并逐条列举了它能到达的地方,包括:**在 App 内下单、预约、退订、修改密码、填写表单**。
-**它能花钱。** 这个项目**没有**支付工具,但它不需要——它能点。唯一挡住支付最后一步的是 **Android 自己的 `FLAG_SECURE`**(敏感页面黑屏,它看不见)。**那是系统的保护,不是本项目的保护**,而且不是所有 App 的支付流程都设了它。项目对"用坐标点击完成转账"**零围栏**:全部 60 余个工具中,只有 `send_sms` 一个被标记为高危。
+**它能花钱。** 这个项目**没有**支付工具,但它不需要——它能点。唯一挡住支付最后一步的是 **Android 自己的 `FLAG_SECURE`**(敏感页面黑屏,它看不见)。**那是系统的保护,不是本项目的保护**,而且不是所有 App 的支付流程都设了它。项目对"用坐标点击完成转账"**零围栏**:它暴露的每一个工具里,只有 `send_sms` 一个被标记为高危。
**它能以你的名义说话。** `send_sms`(发短信)、`dial`(拨号)、`open_url`(打开任意链接),以及在任意社区/社交 App 里打字发布。它发出去的每一条,署名都是你。
diff --git a/README.md b/README.md
index 1740f82..1110145 100644
--- a/README.md
+++ b/README.md
@@ -145,7 +145,7 @@ On Android 13+ it types through the accessibility service's own input channel
`commitText` path a keyboard uses, into the focused field, **while your own keyboard stays active**.
Nothing to install, nothing to switch. Older devices fall back to ADBKeyboard.
-**3. Sixty-odd tools, held to honest failure.**
+**3. A few dozen tools, held to honest failure.**
Screen, input, notifications, SMS, calls, contacts, calendar, location, camera, meetings, TTS/ASR,
and the dog. Every one checks its runtime permission *before* acting and reports `denied("sms")` rather
than working around a refusal. Tools return what they saw, not what was hoped for.
@@ -181,6 +181,12 @@ it wrong?"* The notebook is **private** — the tools are `localOnly` and filter
payload, so habits and promises never leave the device. On top of it sits a real scheduler, under
a hard rule: the moment it says "I'll remind you", the task must already be set and confirmed. And it
is yours to read: **What it remembers** lists every memory and every scheduled task — all deletable.
+**Finished topics get put away, not deleted.** A conversation that has ended is the most expensive
+thing in every later request and the least likely to be needed again, so the nightly review folds it
+into a titled summary with a one-line marker left in its place — and the verbatim conversation is
+archived beside it. The scrollback shows a card where those messages stood, offering **Continue**,
+**Transcript** and **Made here**; it can read the full transcript back when you ask about a detail the
+summary left out, rather than answering from the summary or saying it never happened.
**8. It behaves the same when nobody is watching.**
After a conversation goes quiet the device sends a `(to yourself …)` turn — Andee reviewing the
@@ -573,7 +579,7 @@ Pure Kotlin, no Compose; the whole thing hangs off two pillars, `WindowManager`
| minSdk | 30 | Android 11 — `AccessibilityAction.ACTION_IME_ENTER` and `takeScreenshot` are both API 30+ |
| Java / Kotlin JVM target | 1.8 | `sourceCompatibility` 1.8, `jvmTarget = '1.8'` |
| **Build JDK** | **17–20** | see [Which JDK](#which-jdk) — this is the step people get stuck on |
-| versionCode / versionName | 8 / 0.4.1 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
+| versionCode / versionName | 9 / 0.5.0 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
| applicationId / namespace | `net.kuafuai.andee` | never changed from the template. It affects nothing |
**Runtime dependencies** (`app/build.gradle`):
@@ -1002,7 +1008,7 @@ Read it before redistributing: **the ML Kit barcode SDK and the `play-services-*
open-source**, and the barcode model is fetched from Google at runtime.
See [CHANGELOG.md](CHANGELOG.md) for what changed and for the versioning policy. The latest release is
-**`v0.4.1`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
+**`v0.5.0`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
## Related documents
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7d741cc..2d0e2e3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -128,7 +128,7 @@ https://github.com/user-attachments/assets/866e8333-e97b-4bf5-9525-540f9fdb01cd
Android 13 及以上,它通过无障碍服务自带的输入通道打字 —— 和键盘走同一条 `commitText` 路径,打进
当前焦点输入框,**而你自己的输入法一直保持在用**。不用装、不用切。更老的系统退回 ADBKeyboard。
-**3. 六十来个工具,且被要求诚实地失败。**
+**3. 几十个工具,且被要求诚实地失败。**
屏幕、输入、通知、短信、通话、通讯录、日历、位置、相机、会议录音、TTS/ASR,以及那只狗。每一个
在动手**之前**先检查自己的运行时权限,拒绝就返回 `denied("sms")`,而不是绕过去偷偷做。工具返回
它**看到**的,不是它**希望**的。
@@ -158,6 +158,10 @@ Android 13 及以上,它通过无障碍服务自带的输入通道打字 —
`localOnly`,在发往 hub 的载荷里被过滤掉,习惯和承诺从不离开设备。上面还有一个真的调度器,
规矩很硬:说出"我会提醒你"的那一刻,任务必须**已经设好并确认过**。而且这本笔记你看得到:
**「它记得的事」**里列着每一条记忆和每一个定时任务,每一条都可以删。
+**聊完的话题会被收起来,而不是删掉。** 一段结束了的对话,是之后每一次请求里最贵、又最不可能再被
+用到的东西。所以每晚的复盘会把它折成一段带标题的摘要,原地只留一行标记 —— 逐字的对话存档在旁边。
+回溯里那些消息变成一张卡片,上面有**继续话题**、**对话记录**和**产出物**。你问到摘要里没写的细节时,
+它会去读完整记录,而不是拿摘要硬答,也不会说"这事没发生过"。
**8. 没人看着的时候,他一样。**
对话安静下来之后,设备会发一个 `(to yourself …)` 的回合 —— Andee 独自复盘刚才的对话:
@@ -416,7 +420,7 @@ Google),再填该服务商的密钥。这是两个独立的服务,条款
| minSdk | 30 | Android 11 —— 因为要用 `AccessibilityAction.ACTION_IME_ENTER`(API 30+)和 `takeScreenshot`(API 30+) |
| Java / Kotlin JVM target | 1.8 | `sourceCompatibility` 1.8、`jvmTarget = '1.8'` |
| **构建用 JDK** | **17–20** | 见[配 JDK](#配-jdk),这是最容易卡住的一步 |
-| versionCode / versionName | 8 / 0.4.1 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
+| versionCode / versionName | 9 / 0.5.0 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
| applicationId / namespace | `net.kuafuai.andee` | 从模板里没改,不影响功能 |
**运行库依赖**(`app/build.gradle`):
@@ -879,7 +883,7 @@ CLAUDE.md 给 AI 编码助手看的架构说明(英文)
随包分发的第三方组件清单在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。再分发之前请先看:
**ML Kit 扫码 SDK 和 `play-services-*` 不是开源许可**,而且扫码模型是运行时从 Google 拉的。
-改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.4.1`**,故意停在
+改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.5.0`**,故意停在
pre-1.0:线上协议和构建开关都还在动。
## 相关文档
diff --git a/app/build.gradle b/app/build.gradle
index a30a29b..34a5803 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -34,8 +34,8 @@ android {
applicationId "net.kuafuai.andee"
minSdk 30
targetSdk 34
- versionCode 8
- versionName "0.4.1"
+ versionCode 9
+ versionName "0.5.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
diff --git a/docs/releases/v0.5.0.md b/docs/releases/v0.5.0.md
new file mode 100644
index 0000000..34bfb38
--- /dev/null
+++ b/docs/releases/v0.5.0.md
@@ -0,0 +1,191 @@
+# v0.5.0
+
+**A conversation that has finished is now put away rather than carried forever, and it can be read
+back when you ask about a detail.** That is the new capability this release is numbered for. Two
+smaller changes ride along: a choice card's question and answer now land in the scrollback, and the
+README explains what signing actually protects.
+
+> **The attached APK is the `debug` build, as a stopgap.** The release build type has no
+> `signingConfig` and there is no keystore in this repository, so `assembleRelease` emits
+> `app-<abi>-release-unsigned.apk`, which will not install until you sign it. Rather than ship nothing
+> while that decision is still open, the attached APK is the debug variant: signed with the standard
+> Android debug certificate, and it installs as-is. It is `debuggable`, it is larger than a signed
+> release build, and it is **bare** — no keys, English, CodeFlying off. See **[Download](#download)**
+> for the two keys you will have to supply yourself before it can do anything.
+
+## Highlights
+
+- **Finished topics get put away, not deleted.** A stretch of conversation that has ended was the most
+ expensive thing in every later request and the least likely to be needed again. It is now folded into
+ a titled summary with a one-line marker left in its place, and the verbatim conversation is archived
+ beside it. In the scrollback those messages become a card offering **Continue**, **Transcript** and
+ **Made here** — so you can pick the thread back up, read what was actually said, or reopen what was
+ produced in it.
+- **It reads a detail back instead of guessing.** Ask about something a summary left out and it opens
+ the archived conversation rather than answering from the one-liner or telling you it never happened.
+- **A choice card's question and answer stay in the conversation.** The card used to come and go, so
+ the scrollback showed the assistant acting on a choice nobody could see being made.
+- **The README says what signing is protecting** — and the tool count in it is no longer a number that
+ can go stale.
+
+## What's Changed
+
+### Added
+
+- **Topics: a finished stretch of conversation is folded away, and can be picked back up.** The nightly
+ review marks where topics begin and end among the user's numbered turns (`fold_topic`), the device
+ validates the range and swaps it for a one-line marker **after the turn it names**, and the verbatim
+ conversation is archived so it can be read back.
+ Three tools, all `localOnly`: **`fold_topic`** — **review-only**, and an ordinary turn that calls it
+ is refused, because folding is irreversible from the model's side and a request is not the moment to
+ spend it; **`list_topics`** — each folded topic's id, title, when it ended and how many messages it
+ covers; and **`get_topic`** — the whole back-and-forth as plain text, cut past a limit with
+ `truncated` saying so.
+ The device refuses a fold **with a reason** rather than a retry: a turn number not in the list, a
+ range ending at the latest turn (nothing has started after it, so nothing says it ended), something
+ inside still waiting on an answer, an overlap with a topic already put away, too short, or a scene
+ active. At most **three topics per review**, and they are put away when the review ends rather than
+ when the tool is called. The summary's fourth line is deliberately **what the model left out**,
+ because a summary that reads complete is one whose details are lost.
+ In the scrollback the folded topic is a card standing where its messages stood. **Continue** inlines
+ the archived conversation into the next turn; **Transcript** opens the full record, and says so
+ honestly when the text has been cleared and only the summary is left; **Made here** reopens the pages
+ produced inside that topic, each with its version.
+- **`debug.sweep`, for testing the review on demand.** Loopback only — it needs `adb forward` to reach,
+ and says so rather than vanishing.
+
+### Fixed
+
+- **A choice card's question and answer now land in the scrollback.** `ui.ask` spoke the question and
+ handed the chosen option straight to the brain, so the card came and went and the conversation showed
+ the brain acting on a choice nobody could see being made. The question is an assistant row now and
+ the answer — the button, or the words said instead — is a row of your own. A timeout writes nothing,
+ because nothing was chosen.
+
+### Changed
+
+- **The README says what signing is for.** The signature is the only thing stopping a fake "update" from
+ installing over a user's copy and inheriting the accessibility service, the secure-settings grant and
+ everything in the vault. That is now stated where signing is already discussed, along with why a
+ per-machine debug key is what produces `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
+- **The tool count in the READMEs and the DISCLAIMER is no longer a number.** Both said "sixty-odd
+ tools", which was accurate when written and had drifted as tools were added. The sentences now
+ describe what the tools do and say "a few dozen" — a count written into prose is a count that goes
+ stale, which is a lesson this project's own versioning policy had already learned once.
+- **Dark is still one tap away, and this release changes nothing about it.** Noted here only because
+ the previous release changed the default; nothing about appearance moved in this one.
+
+## Download
+
+Android 11+ (`minSdk 30`). The APK is **per-ABI** (`splits` in `app/build.gradle`), so pick the file
+that matches your device:
+
+| File | Take it if |
+|---|---|
+| `andee-0.5.0-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
+| `andee-0.5.0-debug-armeabi-v7a.apk` | an older 32-bit device |
+| `andee-0.5.0-debug-x86_64.apk` | an emulator |
+
+### This build is deliberately bare
+
+It is built from source with nothing configured — **verified against the generated `BuildConfig`, not
+assumed**:
+
+- `CODEFLYING_ENABLED` is `false`, and both `CODEFLYING_KEY` and `CODEFLYING_DOMAIN` are empty, so
+ **CodeFlying is not available in this build** and nothing is pre-wired to a hosted backend.
+- **The Google voice settings are empty too**, so this build comes up on **Volcengine** and has no
+ provider key of any kind baked in.
+- `DEFAULT_LANG` is `en`: a device that has never picked a language comes up in **English**.
+- The thinking default is off.
+
+### The two keys you have to supply yourself
+
+**The assistant cannot do anything until you give it two keys.** Open **⚙ → Backend → On-device** and
+fill in:
+
+1. **The model key (LLM)** — an OpenAI-compatible endpoint plus a model name. On an English UI these
+ default to `https://api.openai.com/v1` and `gpt-4o-mini`; a Chinese UI defaults to
+ `https://api.deepseek.com` and `deepseek-flash`.
+2. **The voice key** — speech recognition and synthesis. Pick the provider first (**Voice provider** →
+ Volcengine or Google), then fill in that provider's key: a Volcengine Speech key, or a Google Vertex
+ Express key plus a GCP project *number* and a location. Optional: without it the assistant is silent
+ but still works on screen.
+
+Then, in this order: grant **Overlay** → enable **Accessibility** → tap the ball. Until the keys are
+in, the card the assistant puts up will name what is missing — that is the self-check working, not a
+fault.
+
+> **Would you rather not configure keys at all?** Then this APK is the wrong door. Use the one-click
+> page instead — **[codeflying.app/andee](https://www.codeflying.app/andee)**, or
+> **[codeflying.net/andee](https://www.codeflying.net/andee)** in mainland China. Describe what you
+> want, tap the build button, and you get a package with the **tokens already configured** plus a QR
+> code to scan. Starting is free and the free token allowance is **finite — once it runs out, tokens
+> must be bought.** It is a separate service with no direct relationship to this project, with its own
+> terms, pricing and data handling.
+
+### Why a debug build, when the README says not to hand one out
+
+Because the alternative, today, is no binary at all. The README's advice still stands for anything you
+*distribute*: a debug APK is `debuggable`, and its certificate is the **shared Android debug key** —
+so it cannot install over a release-signed build, which means moving from this to a signed release
+takes an uninstall, and an uninstall takes the notebook and the vault with it. Use this to try the
+thing, not to hand it to someone who will depend on it.
+
+## Known issues
+
+- **Folding is only ever done by the nightly review.** There is no way for you to fold a topic by hand,
+ and a very long conversation therefore keeps costing context until the review next runs. `debug.sweep`
+ can trigger it, but it needs a cable.
+- **A folded topic's transcript can be cleared with nothing but the summary left** — the card says so
+ rather than opening an empty page, but the conversation is gone at that point.
+- **The wake threshold's margin is thin**, carried from `v0.3.2` and unchanged here: the eight measured
+ judgements sit in 1.47–2.05 with the line landing in the gap between 1.69 and 1.77 — 0.08 wide. There
+ is still no quality gate on enrolment takes.
+- **A light generated page still fades in over a dark stage.** `TextPage`, `TracePage`,
+ `Theme.Body.Fullscreen`'s window background and `HtmlActivity`'s WebView backdrop are all still dark.
+ Carried over from `v0.3.1`; the app's own default has been light since `v0.4.1`, so the contrast
+ between the two is more visible than it was.
+- **A build with CodeFlying compiled in but no API key can still raise the wrong complaint.** The
+ availability test looks at `CODEFLYING_ENABLED` and the domain rather than the key. Carried from
+ `v0.1.1` onward; not fixed by this release.
+- **`assets/andee_key.txt` is tracked by git and is not in `.gitignore`.** It ships empty, which is
+ correct — the per-user token is written in at package time. But a local build that fills it in would
+ be a key in a tracked file, and nothing currently stops that being committed.
+- The two issues `v0.1.0` listed are **unchanged and untouched in this release**:
+ `tools/verify_faces_lab.py` still reports 7/16 assertions passing against the committed
+ `reports/ball-faces-lab.html`, and the debug WebSocket server (`net/BodyWsServer`) still binds
+ `0.0.0.0:9008` with no authentication (documented in `SECURITY.md`).
+
+## Before you install
+
+Read **[DISCLAIMER.md](../../DISCLAIMER.md)** and
+**[docs/acceptable-use.md](../acceptable-use.md)** first. This app asks for accessibility, overlay,
+notification access, SMS and call log, and it can complete a payment by tapping. The only guardrail on
+that path is Android's `FLAG_SECURE`; the prompt-level checks on risky actions are instructions to the
+model, not enforcement.
+
+## Install from source
+
+If you would rather build it yourself — or need a *signed* release build, which is what you should
+actually distribute:
+
+```bash
+git clone https://github.com/kuafuai/andee
+cd andee
+git checkout v0.5.0
+./gradlew :app:assembleDebug # installs as-is, signed with the debug certificate
+```
+
+To reproduce the attached build exactly, leave `local.properties` with no `CODEFLYING_*` keys, no
+`GOOGLE_VOICE_*` keys, and `DEFAULT_LANG=en`; that is the whole configuration, and nothing is passed
+on the command line.
+
+`assembleRelease` needs your own keystore — the repo has none, so it produces an unsigned APK that
+will not install until you sign it. Full from-scratch setup, including the JDK traps, is in the
+README's **Provisioning** section.
+
+**Upgrading from v0.4.1:** `versionCode` moves `8 → 9`, so this installs over it normally. Nothing you
+configured is discarded, and nothing already on the device is folded — topics begin with the first
+review after this build is installed, so a conversation from before it is simply never put away.
+
+**Full Changelog**: https://github.com/kuafuai/andee/compare/v0.4.1...v0.5.0