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.3.2

booboosui7e639f468d2a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57437b6..0823782 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 **`5` / `"0.3.1"`**.
+- `versionCode` / `versionName` live in `app/build.gradle` and are currently **`6` / `"0.3.2"`**.
- 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.
@@ -27,6 +27,99 @@ hash into `versionName` at build time would close this hole; it is not implement
## [Unreleased]
+## [0.3.2] - 2026-10-14
+
+Wake word plus polish, and the first release that ships the APK with the release rather than telling
+the reader to build one — see *Added* and `docs/releases/v0.3.2.md`.
+
+### Added
+
+- **The wake word now listens with the screen off, and stops the tools that cannot work locked.** The
+ gate used to hold the microphone only while the screen was on — a rule with a real reason behind it,
+ since a dark tablet on a bedside table should not be listening all night, but the screen being off is
+ also the normal state of a phone in a pocket, so it meant the assistant could not be called from the
+ one place a person actually keeps their phone. The gate now asks `wakeListeningAllowed()` — *the
+ screen is on, or the user left 锁屏时也听 on* — and that setting **defaults to on**. Its cost is stated
+ on the row that flips it rather than left for the status bar to mention: the microphone stays open,
+ and so does the system's recording indicator.
+ Woken with the keyguard up, Andee can hear and answer — `tts.speak` needs nothing from the screen —
+ but it must not pretend it can act. A gesture aimed at a locked device is dropped by the input
+ pipeline and reports nothing; the lock screen's own `FLAG_SECURE` means there were never any logs to
+ search; `screen.ui_tree` returns the keyguard's empty placeholder, indistinguishable from the
+ blank-tree case; `device.launch` opens an Activity behind the lock screen where nobody sees it. Every
+ one of those would come back to the brain as "completed" and be repeated to the user as something
+ that happened, so `dispatch()` refuses them outright with a sentence saying why and what to do
+ instead. `screen.` is blocked by prefix so a new tool in that namespace inherits the guard; the names
+ outside it — `device.launch`, `open_url`, `scan`, `look`, `permissions.request`, `ui.ask`,
+ `ui.alert`, `ui.show_html` — are the same act by another road. `device.battery`, `device.volume`,
+ `tts.speak` and the whole `note.` namespace stay open, because they work perfectly well locked. Read
+ live rather than mirrored into a flag, because the caller that matters fires at any point of a turn:
+ locking the phone mid-answer is a normal thing to do, not a state transition to track. Verified on
+ the tablet over the 9008 tool port, including the device being unlocked again to prove the guard
+ reads the device rather than a memory of it.
+- **The voice segmenter now starts on the voice, not on the microphone.** Two symptoms reported
+ separately, neither with a log line to explain it — "it takes three tries to enrol, but if I wait
+ three seconds one is enough", and "it wakes on everything" — turned out to be one defect with two
+ faces. `VoiceSegmenter` decides an utterance has started when the level holds for `START_FRAMES`
+ frames, three of them, 30 ms, and the floor is seeded from the *first frame the microphone delivers*.
+ Three frames is a click, a tap on the tablet's edge, or the recorder's own first read, so the segment
+ started on the hardware rather than on the person. A segment that starts early comes out long and
+ dirty and, past `MAX_FRAMES`, was **dropped in silence** — the caller's latch never counted down and
+ the card sat on 听着… for the rest of the window. That is the second and third try. The fix slows the
+ decision down without throwing audio away: `START_FRAMES` 3 → 8 (80 ms) so a transient cannot open a
+ segment, and `PREROLL_FRAMES` 15 → 30 (300 ms) so the onset is still in the ring when the decision
+ lands. Delaying a decision is free; discarding the audio is not — which is why there is deliberately
+ no warm-up that drops the first 200 ms. The obvious fix was proposed and withdrawn: a user who taps
+ and speaks immediately would lose exactly the syllable the ring exists to protect.
+- **Five of the character's faces now run along the bottom of both cover images**
+ (`images/cover*.png`, `images/social-preview*.png`), one word under each — 听 看 想 做 说. They are
+ the app's own illustrations rather than drawings made for the web, and they are the *gesture* moods,
+ the set the web renderer cannot draw because they use props — so this is the first place the cover
+ shows the character instead of describing it. The row is confined to the left column by the head's own
+ geometry, which is why the whole column moved up 60 px rather than the band being full width.
+
+### Changed
+
+- **The APK now ships with the release.** Every release up to `0.3.1` said "no binary, on purpose",
+ and the reason has not changed — the release build type has no `signingConfig` and the repository
+ has no keystore, so `assembleRelease` emits an unsigned APK that will not install. What changed is
+ the trade: a reader who cannot install anything has no way to try the app at all short of
+ provisioning an Android SDK. The attached APK is the **debug** build — signed with the standard
+ Android debug certificate and installs as-is — and it is deliberately **bare**: `CODEFLYING_ENABLED`
+ is `false` with both `CODEFLYING_KEY` and `CODEFLYING_DOMAIN` empty, `DEFAULT_LANG` is `en`, and the
+ thinking default is off. All four were read back out of the generated `BuildConfig` rather than
+ assumed, and the artifacts were scanned for key material. **The cost is stated rather than buried**:
+ a debug APK is `debuggable` and is signed with the shared Android debug key, so it cannot install
+ over a release-signed build — moving from this to a signed release takes an uninstall, and an
+ uninstall takes the notebook and the vault with it. The READMEs' advice (*hand out a signed release
+ build, not the debug one*) is still right for anything actually distributed, and both now point at
+ this stopgap so the two do not read as a contradiction.
+- **The wake-word prose moved with the default.** `wake_done`, `check_detail_wake_on` and
+ `settings_wake_enrolled` all said the wake word works "while the screen is on" — in both languages —
+ and both READMEs said "it only listens while the screen is on, screen off hands the microphone
+ back". The default is the thing that changed, so every sentence describing it had to move with it or
+ it would have shipped stale.
+
+### Fixed
+
+- **The enrolment prompt appeared before the microphone existed.** 现在说吧 was set on the tapper's
+ thread, before a recorder existed, so the user was invited to speak into a microphone that had not
+ started. It now moves after `mic.start()` returns: the card reads 正在听… for the 100–300 ms the
+ recorder takes to come up, and the prompt appears once something is listening. Nothing is taken from
+ the user to pay for it.
+- **The wake threshold was anchored on the worst take rather than the closest.** `thresholdFor` was
+ anchored on the *worst* pair, so one dirty take set the door width for the whole system — 2.2755 and
+ 2.1083 against a measured band of non-wake speech at 2.21–2.59, with sixteen of sixty judgements
+ within 0.06 of the line. `bestDistance` returns the nearest template, so the question the door width
+ answers is "how far can a real attempt be from the nearest take" — and the evidence for that is the
+ takes that landed close, not the one that did not. `MAX_THRESHOLD` 2.8 → 1.8, which had been picked
+ as "the widest thing still callable a threshold" and never measured. Across three enrolments twenty
+ minutes apart the spread between takes fell from 0.42 to 0.12.
+- `VoiceSegmenter` gained a pure-Kotlin `Stats` (frames / loud / firstLoud / peak / floor / segments /
+ droppedShort / droppedLong) with no Android dependency, keeping the DSP half of the wake pipeline
+ JVM-testable; `WakeEnrollUi` logs it once per attempt and `WakeMic` logs the read that ends a capture
+ early, both under the `Wake` tag so one filter sees the whole pipeline.
+
## [0.3.1] - 2026-10-13
**A patch release by decision, against this file's own definition.** The delta carries six `feat`
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index 59628b0..dd49aeb 100644
--- a/DISCLAIMER.md
+++ b/DISCLAIMER.md
@@ -46,7 +46,7 @@ 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.3.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.3.2.
- *"Your data never leaves the device"* — **false. Do not claim it.**
## 3. What it can actually do (not hypotheticals — current state of the code)
diff --git a/DISCLAIMER.zh-CN.md b/DISCLAIMER.zh-CN.md
index 621d27e..02e80d7 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -45,7 +45,7 @@
**因此"本机模式"不等于"本地处理"** —— 本机模式只是把大脑从 hub 换成了你填的那个服务商。它没有让数据留在设备上,一个字都没有。
所以:
-- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.3.1"。
+- 「我们不会监控和存储您的数据」——**基本成立,但别把话说满**。不落库、不做行为分析、不看你发的内容;唯一的例外是版本自检,它让我们知道"某个 IP 上,有一台某个型号的设备在跑 0.3.2"。
- 「您的数据不会离开设备」——**不成立,而且不要说**。
## 3. 它真的能做什么(以下都不是危言耸听,是代码里的现状)
diff --git a/README.md b/README.md
index 8f7ef67..acd3800 100644
--- a/README.md
+++ b/README.md
@@ -556,7 +556,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 | 5 / 0.3.1 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
+| versionCode / versionName | 6 / 0.3.2 | 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`):
@@ -725,8 +725,8 @@ If any step does not line up, go back to that section's **Verify**.
If you would rather not tap the ball every time, teach it your voice: **⚙ → wake word → record wake
word**, and say the phrase you want to use three times as prompted (for example "Hey Andee" — any
-other phrase works too, as long as you say the same one each time). After that, saying it **while the
-screen is on** does exactly what tapping the ball does.
+other phrase works too, as long as you say the same one each time). After that, saying it does exactly
+what tapping the ball does — **the screen does not have to be on**, unless you turn that off.
A few things worth knowing first:
@@ -742,8 +742,13 @@ A few things worth knowing first:
- **Do not over-enunciate when you record.** The threshold is derived from the spread between your
three takes: pronounce it too perfectly and the threshold tightens so much that your ordinary voice
no longer matches.
-- **It only listens while the screen is on.** Screen off, Andee mid-sentence, and Andee recording you
- all hand the microphone back — a conversation always outranks the wake word.
+- **It listens with the screen off too, and that is a setting you can turn off.** Screen off no longer
+ hands the microphone back, because a screen being off is the normal state of a phone in a pocket —
+ **⚙ → wake word → the "listen while locked" row** controls it and ships **on**. The cost is that the
+ microphone stays open and so does the status-bar indicator below. Andee mid-sentence, and Andee
+ recording you, still hand it back either way: a conversation always outranks the wake word. With the
+ screen locked it can hear and answer, but it will not pretend it can act — screen and app-launch
+ tools refuse, and say why.
- From Android 12 on, a green dot appears in the status bar whenever the microphone is open. That is
the system, and it cannot be removed. If you never record a wake word, the listener never starts and
the dot never appears.
@@ -979,7 +984,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.3.1`** — pre-1.0 on purpose, because the wire contract and the build flags are still moving.
+**`v0.3.2`** — 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 632afa9..b119abd 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -403,7 +403,7 @@ OpenAI 兼容端点(`llm_api_key`,中文界面默认 `https://api.deepseek.c
| 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 | 5 / 0.3.1 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
+| versionCode / versionName | 6 / 0.3.2 | 策略见 [CHANGELOG.md](CHANGELOG.md) |
| applicationId / namespace | `net.kuafuai.andee` | 从模板里没改,不影响功能 |
**运行库依赖**(`app/build.gradle`):
@@ -628,7 +628,8 @@ adb shell pm grant net.kuafuai.andee android.permission.WRITE_SECURE_SETTINGS
## 唤醒词
不想每次都去点球,可以教它认自己的声音:**⚙ → 唤醒词 → 录入唤醒词**,照提示把你想用的词说 3
-遍(比如「嘿 Andee」,换成别的词也行,每遍说同一个)。之后**亮屏状态下**说这个词,效果和点一下球完全一样。
+遍(比如「嘿 Andee」,换成别的词也行,每遍说同一个)。之后说这个词,效果和点一下球完全一样 ——
+**不需要亮屏**,除非你自己把那条关掉。
几件值得先知道的事:
@@ -640,8 +641,11 @@ adb shell pm grant net.kuafuai.andee android.permission.WRITE_SECURE_SETTINGS
可能叫不醒;叫不醒就点球,不影响别的。
- **录的时候别刻意念清楚。** 判定阈值是从你那 3 遍之间的差距算出来的:念得过分标准,阈值会收得
很紧,平时那样叫反而认不出来。
-- **只在亮屏时监听。** 息屏、Andee 自己正在说话、以及正在录你说话的时候都会把麦克风让出来 ——
- 对话本身的麦克风优先级永远高于唤醒词。
+- **息屏时也在听,而这一条可以关。** 息屏不再把麦克风让出来 —— 手机揣在兜里时屏幕本来就黑着,
+ 这是它最该被叫醒的地方。开关在 **⚙ → 唤醒词 → 锁屏时也听**,默认**开启**;代价是麦克风会一直
+ 开着,下面说的状态栏提示也会一直显示。Andee 自己正在说话、以及正在录你说话的时候,两种设置下都会
+ 把麦克风让出来 —— 对话本身的优先级永远高于唤醒词。锁屏时它听得到、答得了,但**不会假装能动手**:
+ 碰屏幕和开 App 那类工具会直接拒绝,并说明原因。
- Android 12 以后,只要麦克风开着,状态栏就有个绿点,这是系统行为,去不掉。没录唤醒词的话监听
根本不启动,也就不会有绿点。
@@ -861,7 +865,7 @@ CLAUDE.md 给 AI 编码助手看的架构说明(英文)
随包分发的第三方组件清单在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。再分发之前请先看:
**ML Kit 扫码 SDK 和 `play-services-*` 不是开源许可**,而且扫码模型是运行时从 Google 拉的。
-改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.3.1`**,故意停在
+改了什么、以及版本号策略见 [CHANGELOG.md](CHANGELOG.md) —— 当前版本是 **`v0.3.2`**,故意停在
pre-1.0:线上协议和构建开关都还在动。
## 相关文档
diff --git a/app/build.gradle b/app/build.gradle
index bf71cf2..65c36ac 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -34,8 +34,8 @@ android {
applicationId "net.kuafuai.andee"
minSdk 30
targetSdk 34
- versionCode 5
- versionName "0.3.1"
+ versionCode 6
+ versionName "0.3.2"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md
index 1d1b098..ac53613 100644
--- a/docs/releases/v0.3.1.md
+++ b/docs/releases/v0.3.1.md
@@ -6,13 +6,10 @@ the policy would have made this `0.4.0`. It is recorded rather than left for som
from the history, because a version number that disagrees with its own policy is the kind of thing
that reads as an oversight later.
-> **This release carries an APK — 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.
+> **No APK is attached to this release, on purpose.** 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. Shipping a binary a
+> reader cannot install would be worse than shipping none. Build it yourself — see *Install* below.
## Highlights
@@ -134,58 +131,6 @@ that reads as an oversight later.
`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`).
-## 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.3.1-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
-| `andee-0.3.1-debug-armeabi-v7a.apk` | an older 32-bit device |
-| `andee-0.3.1-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.
-- `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 (Volcengine)** — speech recognition and synthesis. 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.net/andee](https://www.codeflying.net/andee)** (mainland China) or
-> **[codeflying.app/andee](https://www.codeflying.app/andee)** (everywhere else). 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.
-
## Before you install
Read **[DISCLAIMER.md](../../DISCLAIMER.md)** and
@@ -194,10 +139,10 @@ notification access, SMS and call log, and it can complete a payment by tapping.
that path is Android's `FLAG_SECURE`; the prompt-level checks on risky actions are instructions to the
model, not enforcement.
-## Install from source
+## Install
-If you would rather build it yourself — or need a *signed* release build, which is what you should
-actually distribute:
+Android 11+ (`minSdk 30`), arm64-v8a for anything bought in the last several years. There is no binary
+in this release; build one:
```bash
git clone https://github.com/kuafuai/andee
@@ -206,12 +151,10 @@ git checkout v0.3.1
./gradlew :app:assembleDebug # installs as-is, signed with the debug certificate
```
-To reproduce the attached build exactly, leave `local.properties` with no `CODEFLYING_*` 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.
+`assembleRelease` needs your own keystore — the repo has none, so it produces an unsigned APK. Either
+way the APK is **per-ABI** (`splits` in `app/build.gradle`), so pick the file that matches the device.
+Full from-scratch setup is in the README's **Provisioning** section. Then, in this order: grant
+Overlay → enable Accessibility → tap the ball → put in your own keys under ⚙.
**Upgrading from v0.3.0:** `versionCode` moves `4 → 5`, so this installs over it normally. With the
**local brain** (the out-of-box default), if your UI is in English and you never saved an LLM endpoint
diff --git a/docs/releases/v0.3.2.md b/docs/releases/v0.3.2.md
new file mode 100644
index 0000000..5d2bcbe
--- /dev/null
+++ b/docs/releases/v0.3.2.md
@@ -0,0 +1,182 @@
+# v0.3.2
+
+**Wake word plus polish — and the first release that ships an APK with the release** rather than
+telling the reader to build one.
+
+> **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
+
+- **The wake word works with the screen off now**, which is the state a phone is in when it is in your
+ pocket. **⚙ → wake word → 锁屏时也听** controls it and ships **on**; the microphone stays open while
+ it is, and the system's recording indicator shows it.
+- **It will not pretend it can act while you are locked out.** Woken with the keyguard up it can hear
+ and answer, but screen and app-launch tools refuse outright with a sentence saying why — instead of
+ reporting "completed" for a gesture the system silently dropped.
+- **Enrolment stopped needing three tries.** The segmenter was starting on the microphone rather than
+ on the voice, so the first take came out long and dirty and was dropped in silence. Across three
+ enrolments the spread between takes fell from 0.42 to 0.12.
+- **The cover shows the character instead of describing it** — five of its own gesture faces along the
+ bottom of both the README cover and the social card.
+
+## What's Changed
+
+### Added
+
+- **Wake word with the screen off**, gated by `wakeListeningAllowed()` — *the screen is on, or the
+ user left 锁屏时也听 on*, defaulting to on. The old rule (screen on only) had a real reason behind it
+ — a dark tablet on a bedside table should not listen all night — but it also meant the assistant
+ could not be called from the one place a person keeps their phone. The cost is stated on the row
+ that flips it rather than left for the status bar to mention.
+- **A locked device refuses the tools that cannot work there.** A gesture aimed at a locked device is
+ dropped by the input pipeline and reports nothing; the lock screen's own `FLAG_SECURE` means there
+ were never any logs to search; `screen.ui_tree` returns the keyguard's empty placeholder;
+ `device.launch` opens an Activity nobody sees. `dispatch()` now refuses them with a sentence saying
+ why. `screen.` is blocked by prefix so a new tool in that namespace inherits the guard, and the
+ names outside it (`device.launch`, `open_url`, `scan`, `look`, `permissions.request`, `ui.ask`,
+ `ui.alert`, `ui.show_html`) go with it. `device.battery`, `device.volume`, `tts.speak` and the whole
+ `note.` namespace stay open, because they work perfectly well locked. Read live rather than mirrored
+ into a flag: locking the phone mid-answer is a normal thing to do, not a state transition to track.
+- **Five gesture faces along the bottom of both cover images**, one word under each — 听 看 想 做 说.
+ They are the app's own illustrations, and specifically the *gesture* moods the web renderer cannot
+ draw.
+
+### Changed
+
+- **The release now carries an APK.** Every release up to `0.3.1` said "no binary, on purpose", and
+ the reason has not changed; what changed is the trade. A reader who cannot install anything has no
+ way to try the app short of provisioning an Android SDK. The build is deliberately bare and the
+ sizes, the keys and the debug certificate are all discussed under *Download* below.
+- **The prose about the wake word moved with the default.** `wake_done`, `check_detail_wake_on` and
+ `settings_wake_enrolled` all said it works "while the screen is on" — in both languages — and both
+ READMEs said screen-off hands the microphone back. Every sentence describing the old default would
+ have shipped stale.
+
+### Fixed
+
+- **The voice segmenter started on the microphone, not on the voice.** `START_FRAMES` 3 → 8 (80 ms) so
+ a transient cannot open a segment, and `PREROLL_FRAMES` 15 → 30 (300 ms) so the onset is still in
+ the ring when the decision lands. A segment that starts early comes out long and, past `MAX_FRAMES`,
+ was dropped in silence — the card simply sat on 听着…, which is what "it takes three tries" was.
+ Delaying a decision is free; discarding the audio is not, which is why there is deliberately no
+ warm-up that drops the first 200 ms.
+- **The enrolment prompt appeared before the microphone existed.** 现在说吧 was set on the tapper's
+ thread; it now waits for `mic.start()` to return, so the card reads 正在听… while the recorder comes
+ up and invites you to speak only once something is listening.
+- **The wake threshold was anchored on the worst take rather than the closest.** One dirty take used
+ to set the door width for the whole system — 2.2755 and 2.1083 against non-wake speech measured at
+ 2.21–2.59, with sixteen of sixty judgements within 0.06 of the line. `MAX_THRESHOLD` 2.8 → 1.8,
+ which had been picked as "the widest thing still callable a threshold" and never measured.
+- `VoiceSegmenter` gained a pure-Kotlin `Stats` with no Android dependency, keeping the DSP half of the
+ wake pipeline JVM-testable; `WakeEnrollUi` and `WakeMic` log under one `Wake` tag.
+
+## 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.3.2-debug-arm64-v8a.apk` | anything bought in the last several years — **this is the one for almost everyone** |
+| `andee-0.3.2-debug-armeabi-v7a.apk` | an older 32-bit device |
+| `andee-0.3.2-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.
+- `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 (Volcengine)** — speech recognition and synthesis. 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.net/andee](https://www.codeflying.net/andee)** (mainland China) or
+> **[codeflying.app/andee](https://www.codeflying.app/andee)** (everywhere else). 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
+
+- **The wake threshold's margin is thin.** After the fix, 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, which is the honest
+ state of it. There is also **no quality gate on enrolment takes**, so a future enrolment can still
+ contribute a bad one.
+- **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`; not addressed here.
+- **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 `kft_` 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.3.2
+./gradlew :app:assembleDebug # installs as-is, signed with the debug certificate
+```
+
+To reproduce the attached build exactly, leave `local.properties` with no `CODEFLYING_*` 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.3.1:** `versionCode` moves `5 → 6`, so this installs over it normally. **The wake
+word now keeps listening with the screen off** — if you have enrolled one, that is a new behaviour and
+a new battery cost, and **⚙ → wake word → 锁屏时也听** turns it off.
+
+**Full Changelog**: https://github.com/kuafuai/andee/compare/v0.3.1...v0.3.2