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

docs: lead with the features, fix four stale claims, and scope CodeFlying

booboosuidf3184e41a12
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 637e0ed..fcadd52 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -65,7 +65,7 @@ build time would close this hole; it is not implemented yet.)
contradicts the project's own first instruction, in `LocalPrompt.TEXT`: *"you are not a tablet's
assistant, you are an individual, and the tablet is only what carries you."* The docs now lead
with the individual, and give the body / persona / notebook mechanisms that back it up in code
- (fifteen moods and idle fidgets, `BallLook.persona` reaching the head of the system prompt, the
+ (fourteen moods and idle fidgets, `BallLook.persona` reaching the head of the system prompt, the
private `Notebook`, the `(to yourself …)` self-review turn, and §11's rule that the character is
delivery and never a licence). No code changed — the code was already right; the prose was not.
- `README.md` is now the **English** front page. The detailed Chinese provisioning guide moved to
@@ -88,6 +88,44 @@ build time would close this hole; it is not implemented yet.)
an English page. `SECURITY.md` and `CODE_OF_CONDUCT.md` have no Chinese edition; the Chinese docs
now say so explicitly instead of linking silently.
+- **Both READMEs restructured and fact-checked against the code.** The 16-item feature list now sits
+ above *Quick start* instead of below *What it looks like*, so the page leads with what the thing
+ does; both nav bars follow. Three claims were corrected against the source: the ball has
+ **fourteen** moods (`ui/ball/Mood.kt`), not fifteen; the tool list no longer names `files` (there
+ is no file tool — `location` does exist); and the Kotlin line count is now 43k+. The
+ two-credential block puts the **brain key first and marks it required**, with the voice key second
+ and optional — voice used to lead, which buried the one whose absence stops the brain from running
+ at all. The "Things you can just say" table no longer repeats the WeChat example: that one is told
+ as a single moment above the table ("you are driving when your mother messages you"), which is what
+ the rest of the list is a variation on. And a short note near the top now says plainly that
+ **Android is the only supported platform today** — the "any device with a body" line is about what
+ the software is written for, and was reading as though other platforms already shipped.
+
+- **Four documents corrected where they contradicted the code — no behaviour changed.**
+ `DISCLAIMER.md` / `DISCLAIMER.zh-CN.md` and `docs/permissions.md` / `docs/permissions.zh-CN.md` all
+ listed `brain=hub` first in their "data goes where" table's *Default* column, which read as though
+ the hub were the out-of-box mode. It is not: `VoiceConfig.brainConfig` reads
+ `getString("brain", BRAIN_LOCAL)`, and the `brain` picker lists 本机 leftmost for the same reason.
+ The row now reads `brain=local` (the default) → `api.deepseek.com`, with hub mode as the other
+ case. Separately, `CLAUDE.md`'s "Existing but not wired up" section claimed there was **no `tts.*`
+ dispatcher namespace** — there is one (`tts.speak`, `CommandDispatcher`); what it lacks is a
+ `ToolSchemas` entry, which is the actual reason the model cannot call it, and the distinction
+ matters because the fix for "let it choose to speak" is adding a schema, not a branch. The
+ matching comment at the head of `CommandDispatcher` ("will be added later") is corrected too. The
+ error was load-bearing in the disclaimer especially: a reader who believed hub was the default
+ would size the data-path risk wrongly.
+
+- **CodeFlying is now introduced as what it is, and disclaimed.** *Quick start* used to name
+ codeflying.app / codeflying.net as simply "the fastest route", which read as though it were this
+ project's own or affiliated build channel — an impression a reader could act on (and later hold
+ *this* project to). It is now described in its own terms first — **a general platform where you
+ describe the app you want and it develops and publishes it** — followed by one plain sentence:
+ **a separate service with no direct relationship to this project**, its own terms, pricing and data
+ handling. Same treatment in `## Using Andee` / `## 三种使用方式` and the Chinese
+ `## 从哪里开始看` table, so the three places it appears do not disagree. The practical guidance is
+ unchanged (still the shortest path; still an APK you have to install; the free token allowance is
+ still finite and then paid), because none of that was wrong — only the implied ownership was.
+
### Removed
- `brain/andee-system-prompt.md` — an unused mirror of the cloud brain's prompt. It had no runtime
diff --git a/CLAUDE.md b/CLAUDE.md
index 4f25b82..583c2f1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -542,5 +542,5 @@ Timed entry is not a mechanism: the model sets a `todo` whose text says `enter_s
Don't mistake these for live code paths or accidentally "fix" callers into existence:
- `BubbleUi`, `PillUi`, `MenuUi` — superseded by `FloatingWindowUi`, never instantiated.
-- `TtsController.speak()` is **live** — `ScreenBodyService`'s hub `onFinal` reads every final answer aloud. It is not a tool, though: there is no `tts.*` dispatcher namespace, so the brain cannot choose to speak or stay quiet. Anything that needs the device silent has to gate the call site (see the meeting recorder). The long-press that used to trigger a test utterance is now explicitly reserved.
+- `TtsController.speak()` is **live** — `ScreenBodyService`'s hub `onFinal` reads every final answer aloud. There **is** a `tts.speak` branch in `CommandDispatcher` (so a `tts.*` namespace exists), but **nothing in `ToolSchemas` backs it**, and the schema is the only list the model sees. So the brain still cannot choose to speak or stay quiet, and anything that needs the device silent still has to gate the call site (see the meeting recorder). The branch exists for the authoring/demo port — `tools/body.py tts.speak '{"text":"…"}'` — where a fixed line has to be heard on cue with the screen left alone. The long-press that used to trigger a test utterance is now explicitly reserved.
- `AudioIO`'s `startRecording`/`stop` buffer-everything path is MVP leftover; the ASR path uses `startStreaming` instead.
diff --git a/DISCLAIMER.md b/DISCLAIMER.md
index 746a288..c03ce6d 100644
--- a/DISCLAIMER.md
+++ b/DISCLAIMER.md
@@ -35,7 +35,7 @@ An **experimental** piece of software that you install on **your own device**. I
| What | Goes to | Default |
|---|---|---|
| Your speech (ASR) and its speech (TTS) | **Volcengine / ByteDance cloud** | `openspeech.bytedance.com` |
-| The conversation, **and every tool result** | The "brain" you configured | `brain=hub`; in local mode, `api.deepseek.com` |
+| The conversation, **and every tool result** | The "brain" you configured | `brain=local` (the out-of-box default) → `api.deepseek.com`; in hub mode, your own `hub_url` |
| The private notebook (`Notebook` — what it remembers about you, what it promised) | **On this device only** | Filtered out of the hub payload |
The second row needs spelling out: **tool results are part of the conversation.** The SMS text it read, your contacts, your call log, notification contents, your location, and its reading of the screen all travel to the endpoint you configured.
diff --git a/DISCLAIMER.zh-CN.md b/DISCLAIMER.zh-CN.md
index 660db93..a6195f7 100644
--- a/DISCLAIMER.zh-CN.md
+++ b/DISCLAIMER.zh-CN.md
@@ -34,7 +34,7 @@
| 什么数据 | 去哪 | 默认 |
|---|---|---|
| 你说的话(语音识别)、它说的话(语音合成) | **火山引擎(字节跳动)云端** | `openspeech.bytedance.com` |
-| 对话内容,**以及全部工具返回结果** | 你配置的"大脑" | `brain=hub`;本机模式默认 `api.deepseek.com` |
+| 对话内容,**以及全部工具返回结果** | 你配置的"大脑" | `brain=local`(开箱默认)→ `api.deepseek.com`;hub 模式下走你自己的 `hub_url` |
| 私人笔记本(`Notebook`:它记住的你、以及它答应过的事) | **只在本机** | 不进 hub 载荷,不外发 |
第二行必须说透:**工具返回结果就是对话的一部分**。它读到的短信正文、通讯录、通话记录、通知内容、定位、以及它对屏幕的"理解",都会随对话发到你配置的那个端点。
diff --git a/README.md b/README.md
index 33ed3aa..d0baf9a 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
<p align="center">
<a href="https://www.codeflying.app">Build online</a> ·
+ <a href="#key-features">Features</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="#provisioning">Provisioning</a> ·
<a href="#what-it-looks-like">What it looks like</a> ·
- <a href="#key-features">Features</a> ·
<a href="#permissions-why-each-one-and-what-happens-if-you-refuse">Permissions</a> ·
<a href="#why-you-can-check-this-instead-of-trusting-it">Verifiability</a> ·
<a href="SECURITY.md">Security</a> ·
@@ -45,9 +45,16 @@ it can do it.
### Things you can just say
+You are driving when your mother messages you. One hand on the wheel, eyes on the road:
+
+> *"Hey Andee — reply to Mom on WeChat: I'll be home by seven."*
+
+It opens WeChat, finds the chat, types, sends, and reads the answer back. Your hands never left the
+wheel. **The hard part was never the sentence** — it is getting into a real app, as you, while you
+are somewhere else. The rest of the list is the same job in other shapes:
+
| You say | What happens |
|---|---|
-| *"Reply to Mom on WeChat: I'll be home by seven."* | It opens WeChat, finds the chat, types, sends — while you watch the ball's face work. |
| *"Find this cheaper on Taobao and JD."* | It walks both shops itself and comes back with a comparison page. |
| *"Remind me to call the landlord at nine tomorrow."* | The alarm is set before it says "OK". At nine, it wakes up and tells you. |
| *"Record this meeting."* | It holds the mic for the hour, then hands you the minutes as a page. |
@@ -65,7 +72,7 @@ it can do it.
- **Gets to know you.** A private notebook, a real scheduler, a nightly review of its own
conversations, and **scenes** — ways of working it proposes after doing the same kind of thing with
you a few times.
-- **Has a character.** Five looks, fifteen moods, and a face the model picks itself, sentence by
+- **Has a character.** Five looks, fourteen moods, and a face the model picks itself, sentence by
sentence.
- **Holds lines a prompt cannot talk it out of.** A stranger's notification cannot unlock the vault or
grant it new permissions — that refusal is in the dispatcher, not in the prompt.
@@ -82,6 +89,9 @@ It is one Android app, and it has no conventional UI. An `AccessibilityService`
screen; a `WindowManager` overlay draws the result; **its face is a floating ball** that changes
expression while it works.
+**Today it is Android, and only Android — other bodies are planned, not shipped.** The tool contract
+is what would make a new one a port rather than a rewrite, but nothing outside Android exists yet.
+
> **Before you install this.** Andee taps, types and acts on your behalf. It can complete a payment,
> send messages under your name, read your messages, contacts and location, and — with a robot dog
> attached — physically move. It is experimental, carries no warranty, and **what it does is your
@@ -89,91 +99,6 @@ expression while it works.
> goes to Volcengine, and the conversation goes to whichever brain you configure. Read
> **[DISCLAIMER.md](DISCLAIMER.md)** and **[docs/acceptable-use.md](docs/acceptable-use.md)** first.
-## Quick start
-
-The fastest route skips the two things that actually stop people: **building it yourself, and wiring
-up tokens.** Andee can be built on [codeflying.app](https://www.codeflying.app) (English) or
-[codeflying.net](https://www.codeflying.net) (中文): describe the Andee you want, and it hands you an
-installable package with the keys already configured. You do not need to know anything about Android
-first.
-
-Two things it does **not** skip. **You still install the package** — the device side is still an APK
-that has to be put on the device. And **the free token allowance is finite**: it covers getting
-started, and once it runs out, tokens are purchased.
-
-```text
-1. Open https://www.codeflying.app (中文: https://www.codeflying.net)
-2. Describe the Andee you want
-3. Build → download the package (keys already configured) → install
-4. Grant Overlay, then Accessibility → the ball appears
-```
-
-To build it yourself instead:
-
-> **Requirements**
->
-> - Android 11 (API 30) or newer — `ACTION_IME_ENTER` and `takeScreenshot` are both API 30+
-> - **JDK 17–20.** AGP 8.3.1 needs 17+; the Gradle 8.4 wrapper cannot run on 21+ (Android Studio's
-> bundled JBR 25 is rejected with `Unsupported class file major version 69`)
-> - Android SDK with platform 34 and build-tools 34.0.0
-> - A real device. This app *is* the accessibility service; an emulator can run it, but almost
-> nothing it does is meaningful there
-
-```bash
-./gradlew clean :app:assembleDebug # → app/build/outputs/apk/debug/app-debug.apk
-./gradlew installDebug # build + install to an attached device
-
-# then, on the device, in this order:
-# 1. grant Overlay → the ball appears
-# 2. enable Accessibility → it can now see and touch the screen
-# 3. tap the ball → allow the microphone prompt
-# 4. open ⚙ and put in two keys of your own (see below)
-```
-
-**No credentials ship in this repository, and the two that are missing fail in ways that do not look
-like missing credentials.** Both go in ⚙ on the device:
-
-- **Voice** — a [Volcengine Speech](https://www.volcengine.com/product/voice-tech) API key, in
- 「语音密钥」 / *Voice API key*. Without it ASR and TTS fail during the WebSocket handshake, which
- surfaces as a **connect timeout** — the device looks like it has a network problem when what it has
- is a blank field. Everything else still works; it is just mute and deaf.
-- **Brain** — with `brain = local` (the default), an API key for any OpenAI-compatible endpoint.
- Blank means the local brain cannot run at all.
-
-You do not have to remember this: the first run is a stepped setup that walks you through both, and
-afterwards the **✓** button in the ball's control bar opens the self-check list, which says which of
-the two is missing and offers the button that fixes it.
-
-**Use `assembleDebug`, not `assembleRelease`.** The release build type has no `signingConfig` and
-there is no keystore in the repo, so `assembleRelease` emits `app-release-unsigned.apk`, which will
-not install. The debug build is signed with the standard Android debug certificate.
-
-**If the build does not work, the answer is almost always the JDK.** Full from-scratch setup — the
-JDK traps, the Android SDK two different ways (including a command-line-only path for CI), and a table
-of every error you are likely to hit — is in **[Provisioning](#provisioning)** below. Permissions are
-answered in **[Permissions](#permissions-why-each-one-and-what-happens-if-you-refuse)**, and the
-known limitations in **[SECURITY.md](SECURITY.md)** — read that last one before running this on a
-network you do not control.
-
-## What it looks like
-
-There is no home screen. What exists:
-
-- **A floating ball.** The entire UI is `TYPE_APPLICATION_OVERLAY` layers added through
- `WindowManager` (`ui/FloatingWindowUi`). Unfolded, it is a full-screen card: the ball's face on
- top, the conversation underneath, and a small control bar — **产物** (the pages it has made),
- **情景** (its scenes), **✓** (self-check), **⚙** (settings). When it starts working another app it
- folds itself into a ball in the corner and gets out of the way; tap to talk, long-press to unfold.
-- **The launcher icon opens two doors.** With the assistant running, it unfolds the card — exactly
- what a long-press on the ball does. With accessibility off, it shows the self-check card instead,
- because that is the one moment the phone has nothing else to tell you why it is doing nothing.
-- **`ScreenBodyService`** (`AccessibilityService`) — the whole job. It builds the object graph and
- starts both network paths.
-
-A handful of transient activities (`PermissionRequestActivity`, `ScanActivity`, `LookActivity`,
-`HtmlActivity`, `TextInputActivity`) exist only to borrow a system capability for a moment. They are
-not pages.
-
## Key features
### Hands — it uses your phone the way you do
@@ -193,8 +118,8 @@ On Android 13+ it types through the accessibility service's own input channel
Nothing to install, nothing to switch. Older devices fall back to ADBKeyboard.
**3. Sixty-odd tools, held to honest failure.**
-Screen, input, notifications, SMS, calls, contacts, calendar, files, camera, meetings, TTS/ASR, and
-the dog. Every one checks its runtime permission *before* acting and reports `denied("sms")` rather
+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.
**4. It can log in as you without ever holding your password.**
@@ -235,9 +160,9 @@ worth turning into a scene next time, and ends empty-handed rather than inventin
### Face — a character, not a theme
-**9. Five looks, fifteen moods, and a face it chooses.**
+**9. Five looks, fourteen moods, and a face it chooses.**
奶油 Cream, 八戒 Pigsy, 贱贱兔 Rascal, 憨憨熊 Bear and 小恶魔 Imp, drawn live in hand-written OpenGL
-ES. Fifteen moods (`ui/ball/Mood.kt`) arbitrate between what it feels, what the voice pipeline is
+ES. Fourteen moods (`ui/ball/Mood.kt`) arbitrate between what it feels, what the voice pipeline is
doing, and what work is in flight, plus an idle fidget pool that never repeats the same gesture twice
in a row, *"because a repeat reads as a stuck animation, not a personality."* The model now picks its
own expression **mid-sentence** — `[happy] Found it, page three. [calm] Want me to open it?` — and the
@@ -291,7 +216,102 @@ makes "any smart hardware as a body" a fact here rather than an aspiration.
**16. No Compose, no DI framework, no coroutines.**
Deliberately. Overlays cannot host Compose, so all UI is hand-written `View` code; there is one
service, so dependencies are constructor-injected by hand; concurrency is `Handler` plus dedicated
-executors. 42k+ lines of Kotlin, all first-party — no code copied in from anywhere.
+executors. 43k+ lines of Kotlin, all first-party — no code copied in from anywhere.
+
+## Quick start
+
+The fastest route skips the two things that actually stop people: **building it yourself, and wiring
+up tokens.**
+
+**[codeflying.app](https://www.codeflying.app)** (English) · **[codeflying.net](https://www.codeflying.net)**
+(中文) is a general platform for exactly that shape of problem — **you describe the app you want in
+words, and it develops and publishes it for you.** No Android knowledge required. Ask it for Andee and
+it hands you an installable package with the keys already configured.
+
+**It is a separate service with no direct relationship to this project** — not Andee's build channel,
+and not covered by anything in this repository. Its own terms, pricing and data handling apply.
+
+Two things it does **not** skip. **You still install the package** — the device side is still an APK
+that has to be put on the device. And **the free token allowance is finite**: it covers getting
+started, and once it runs out, tokens are purchased.
+
+```text
+1. Open https://www.codeflying.app (中文: https://www.codeflying.net)
+2. Describe the Andee you want
+3. Build → download the package (keys already configured) → install
+4. Grant Overlay, then Accessibility → the ball appears
+```
+
+To build it yourself instead:
+
+> **Requirements**
+>
+> - Android 11 (API 30) or newer — `ACTION_IME_ENTER` and `takeScreenshot` are both API 30+
+> - **JDK 17–20.** AGP 8.3.1 needs 17+; the Gradle 8.4 wrapper cannot run on 21+ (Android Studio's
+> bundled JBR 25 is rejected with `Unsupported class file major version 69`)
+> - Android SDK with platform 34 and build-tools 34.0.0
+> - A real device. This app *is* the accessibility service; an emulator can run it, but almost
+> nothing it does is meaningful there
+
+```bash
+./gradlew clean :app:assembleDebug # → app/build/outputs/apk/debug/app-debug.apk
+./gradlew installDebug # build + install to an attached device
+
+# then, on the device, in this order:
+# 1. grant Overlay → the ball appears
+# 2. enable Accessibility → it can now see and touch the screen
+# 3. tap the ball → allow the microphone prompt
+# 4. open ⚙ and put in two keys of your own (see below)
+```
+
+**No credentials ship in this repository, and the two that are missing fail in ways that do not look
+like missing credentials.** Both go in ⚙ on the device — **one is required, the other only costs you
+the voice:**
+
+**1. The brain key — required.** With `brain = local` (the out-of-box default) the agent loop runs on
+the device itself, against any OpenAI-compatible endpoint (`llm_api_key`, default
+`https://api.deepseek.com`). **Leave it empty and the local brain does not run at all** — nothing
+behind it falls back to something else. The ball does at least say so out loud, rather than silently
+doing nothing.
+
+**2. The voice key — optional.** A [Volcengine Speech](https://www.volcengine.com/product/voice-tech)
+API key, in 「语音密钥」 / *Voice API key*. Without it ASR and TTS fail during the WebSocket
+handshake, which surfaces as a **connect timeout** — the device looks like it has a network problem
+when what it has is a blank field. Everything else still works; it is just mute and deaf.
+
+You do not have to remember this: the first run is a stepped setup that walks you through both, and
+afterwards the **✓** button in the ball's control bar opens the self-check list, which says which of
+the two is missing and offers the button that fixes it.
+
+**Use `assembleDebug`, not `assembleRelease`.** The release build type has no `signingConfig` and
+there is no keystore in the repo, so `assembleRelease` emits `app-release-unsigned.apk`, which will
+not install. The debug build is signed with the standard Android debug certificate.
+
+**If the build does not work, the answer is almost always the JDK.** Full from-scratch setup — the
+JDK traps, the Android SDK two different ways (including a command-line-only path for CI), and a table
+of every error you are likely to hit — is in **[Provisioning](#provisioning)** below. Permissions are
+answered in **[Permissions](#permissions-why-each-one-and-what-happens-if-you-refuse)**, and the
+known limitations in **[SECURITY.md](SECURITY.md)** — read that last one before running this on a
+network you do not control.
+
+## What it looks like
+
+There is no home screen. What exists:
+
+- **A floating ball.** The entire UI is `TYPE_APPLICATION_OVERLAY` layers added through
+ `WindowManager` (`ui/FloatingWindowUi`). Unfolded, it is a full-screen card: the ball's face on
+ top, the conversation underneath, and a small control bar — **产物** (the pages it has made),
+ **情景** (its scenes), **✓** (self-check), **⚙** (settings). When it starts working another app it
+ folds itself into a ball in the corner and gets out of the way; tap to talk, long-press to unfold.
+- **The launcher icon opens two doors.** With the assistant running, it unfolds the card — exactly
+ what a long-press on the ball does. With accessibility off, it shows the self-check card instead,
+ because that is the one moment the phone has nothing else to tell you why it is doing nothing.
+- **`ScreenBodyService`** (`AccessibilityService`) — the whole job. It builds the object graph and
+ starts both network paths.
+
+A handful of transient activities (`PermissionRequestActivity`, `ScanActivity`, `LookActivity`,
+`HtmlActivity`, `TextInputActivity`) exist only to borrow a system capability for a moment. They are
+not pages.
## Permissions: why each one, and what happens if you refuse
@@ -409,10 +429,11 @@ If you want to see how the decisions were made rather than only what was decided
## Using Andee
- **Online — no local build, no token setup.** **[codeflying.app](https://www.codeflying.app)** ·
- **[codeflying.net](https://www.codeflying.net)** (中文). Describe the Andee you want, and it hands
- you an installable package with the keys already configured — nothing to compile locally, and
- nothing about Android to understand first. A free token allowance gets you started; it is finite,
- and once it runs out, tokens are purchased.
+ **[codeflying.net](https://www.codeflying.net)** (中文) — a general platform for describing an app
+ in words and having it developed and published. **A separate service, not part of this project.**
+ Describe the Andee you want, and it hands you an installable package with the keys already
+ configured — nothing to compile locally, and nothing about Android to understand first. A free
+ token allowance gets you started; it is finite, and once it runs out, tokens are purchased.
- **Self-hosted.** Clone, build, install. See [Quick start](#quick-start) and the provisioning
walkthrough in [Provisioning](#provisioning). Point it at any OpenAI-compatible endpoint and it
@@ -725,7 +746,7 @@ app/ the Android app (Kotlin, no Compose)
brain/ the agent loop — LocalBrain, LocalPrompt (the character's rulebook:
§§1–10 the job, §11 scenes, §12 the persona, §13 the active scene),
and NotificationTriage
- ui/ball/ the face — Mood (15 moods + idle fidgets), BallLook (five looks, each a character)
+ ui/ball/ the face — Mood (14 moods + idle fidgets), BallLook (five looks, each a character)
net/ BodyWsServer, BodyWsClient, ToolSchemas (the tool definitions)
device/ screen control, permissions, vault, robot dog
config/ VoiceConfig (settings), Notebook (memories, todos, scenes — encrypted)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 3581d9c..c15b01e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,9 +4,9 @@
<p align="center">
<a href="https://www.codeflying.net">在线构建</a> ·
- <a href="#快速开始">快速开始</a> ·
<a href="#从哪里开始看">从哪里开始看</a> ·
<a href="#核心能力">核心能力</a> ·
+ <a href="#快速开始">快速开始</a> ·
<a href="#权限每一项为什么以及你拒绝了会怎样">权限</a> ·
<a href="#为什么你可以去核对而不是选择相信">可核对</a> ·
<a href="SECURITY.md">安全</a> ·
@@ -46,9 +46,16 @@
### 你可以直接这么说
+你正在开车,你妈发来消息。一只手在方向盘上,眼睛看着路:
+
+> *「嘿 Andee —— 微信回我妈:我七点到家。」*
+
+它自己打开微信、找到聊天、打字、发送,再把对方的回复念给你听。你的手一直没离开方向盘。
+**难的从来不是那句话** —— 难的是你人在别处的时候,它以你的身份进到一个真实的 App 里。下面这些,
+是同一件事换了别的形状:
+
| 你说 | 会发生什么 |
|---|---|
-| *「微信回我妈:我七点到家。」* | 它自己打开微信、找到聊天、打字、发送 —— 你看着球的表情在干活。 |
| *「这个东西帮我在淘宝和京东比比价。」* | 它自己把两家店逛一遍,回来给你一页对比。 |
| *「明天九点提醒我给房东打电话。」* | 说"好"之前闹钟就已经设好了。九点一到,它自己醒来叫你。 |
| *「帮我把这个会录下来。」* | 它占着麦克风录完整场,结束后把会议纪要做成一页给你。 |
@@ -64,7 +71,7 @@
不用注册账号、**没有任何遥测**。
- **会越来越懂你。** 私人笔记本、真的定时任务、没人时自己复盘对话,还有**情景** —— 同一类事陪你
做过几次之后,它会主动提议"要不要存成一个情景"。
-- **有性格。** 五个形象、十五种情绪,表情由模型自己挑,一句话说到一半都能换脸。
+- **有性格。** 五个形象、十四种情绪,表情由模型自己挑,一句话说到一半都能换脸。
- **有些底线,提示词说不动它。** 陌生人发来的一条通知,打不开保险箱、也不能替你给它新的权限 ——
这道拒绝写在调度器里,不在提示词里。
@@ -78,6 +85,9 @@
它就是一个 Android 应用。没有常规界面:一个 `AccessibilityService` 负责看和碰屏幕,一个
`WindowManager` 悬浮层负责画出来 —— 他的脸就是那颗浮动的球。
+**今天它只有 Android,也只有 Android —— 别的身体是计划,不是已发布。** 工具契约是让新身体成为一次
+移植而不是重写的那个东西,但 Android 之外目前还不存在。
+
> **装之前先读这段。** Andee 会替你点击、输入、动手。他能完成一笔支付,能以你的名义发消息,能读你的
> 短信、通讯录和位置,接了机器狗还会**真的在地板上移动**。他是实验性的、不提供任何担保,而
> **他做的一切都算你的** —— 包括转错账。数据也会离开设备:语音走火山引擎,对话走你配置的那个大脑。
@@ -98,65 +108,7 @@
|---|---|
| **演示视频** | 一段 30~60 秒的真机录屏,正在制作中。在那之前,上面「你可以直接这么说」和下面的「核心能力」是这件事最好的文字说明。 |
| **截图** | 那颗球、在手机上跑任务、以及机器狗 —— 三张静帧待补。 |
-| **现在就能构建** | **[www.codeflying.net](https://www.codeflying.net)** —— **不用自己打包,也不用自己配令牌。** 描述你想要的 Andee,它交给你一个已经配好令牌的安装包。有免费额度,但额度有限:用完之后需要购买 token。 |
-
-## 快速开始
-
-**最快的一条路,省掉的是真正卡住人的那两件事:自己打包、自己配令牌。** 在
-[codeflying.net](https://www.codeflying.net)(中文)或 [codeflying.app](https://www.codeflying.app)
-(English)上描述你要的 Andee,它会交给你一个**已经配好令牌**的安装包。也不用先懂 Android。
-
-有两件事它省不掉。**装这一步省不掉** —— 设备那侧仍然是一个 APK,仍然要装到设备上。
-**免费 token 额度也是有限的** —— 够你上手,用完之后需要购买 token。
-
-```text
-1. 打开 https://www.codeflying.net (English: https://www.codeflying.app)
-2. 描述你想要的 Andee
-3. 构建 → 下载安装包(令牌已配好)→ 安装
-4. 开悬浮窗,再开无障碍 → 那颗球就出现了
-```
-
-想自己编译的话:
-
-> **环境要求**
->
-> - Android 11(API 30)或更新 —— `ACTION_IME_ENTER` 和 `takeScreenshot` 都是 API 30+
-> - **JDK 17–20。** AGP 8.3.1 要 17+;Gradle 8.4 的 wrapper 跑不了 21+(Android Studio 自带的
-> JBR 25 会被直接拒绝:`Unsupported class file major version 69`)
-> - Android SDK:platform 34 + build-tools 34.0.0
-> - **真机。** 这个应用本身就是那个无障碍服务;模拟器能跑,但它几乎什么都干不了
-
-```bash
-./gradlew clean :app:assembleDebug # 产物 app/build/outputs/apk/debug/app-debug.apk
-./gradlew installDebug # 构建并安装到已连接的设备
-
-# 然后在设备上,按这个顺序:
-# 1. 开悬浮窗 → 球出现
-# 2. 开无障碍 → 它能看、能碰屏幕了
-# 3. 点一下那颗球 → 允许麦克风
-# 4. 打开 ⚙,填两个你自己的 Key(见下)
-```
-
-**仓库里不带任何密钥,而这两个缺失的密钥,报出来的错都不像「缺密钥」。** 两个都填在设备的 ⚙ 里:
-
-- **语音** —— 一个[火山引擎语音服务](https://www.volcengine.com/product/voice-tech)的 API Key,填在
- 「语音密钥」。不填,识别和合成会在 WebSocket 握手阶段失败,**表现为连接超时** —— 看着像网络坏了,
- 其实是那一栏空着。其余功能照常,只是既听不见也说不出。
-- **大脑** —— `brain = local`(默认)下,任何 OpenAI 兼容接口的 API Key。空着,本机大脑根本跑不起来。
-
-这些不用记:第一次启动会有一个分步引导,带你把这两样填好;之后球的控制条上的 **✓** 会打开自检
-清单,直接告诉你缺哪一个,并给出去处理的按钮。
-
-**打包装 `assembleDebug`,别用 `assembleRelease`。** release 没有 `signingConfig`,仓库里也没有
-keystore,`assembleRelease` 产出的是 `app-release-unsigned.apk`,**装不上**。debug 包用 Android
-默认调试证书签名。
-
-#### 遇到问题
-
-装机流程、以及从零配 SDK 的完整说明(含纯命令行 / CI 路径)在本文下面的
-[Android SDK 下载与配置](#android-sdk-下载与配置)。权限为什么这么要、拒绝了会怎样 —— 在
-**[docs/permissions.zh-CN.md](docs/permissions.zh-CN.md)**。已知限制在 **[SECURITY.md](SECURITY.md)**(英文);
-如果你打算在**你控制不了的网络**上用,先读那一条。
+| **现在就能构建** | **[www.codeflying.net](https://www.codeflying.net)** —— 一个"描述需求、帮你开发并发布应用"的通用平台,**独立服务,与本项目无直接关系。** 不用自己打包,也不用自己配令牌:描述你想要的 Andee,它交给你一个已经配好令牌的安装包。有免费额度,但额度有限:用完之后需要购买 token。 |
## 核心能力
@@ -174,7 +126,7 @@ Android 13 及以上,它通过无障碍服务自带的输入通道打字 —
当前焦点输入框,**而你自己的输入法一直保持在用**。不用装、不用切。更老的系统退回 ADBKeyboard。
**3. 六十来个工具,且被要求诚实地失败。**
-屏幕、输入、通知、短信、通话、通讯录、日历、文件、相机、会议录音、TTS/ASR,以及那只狗。每一个
+屏幕、输入、通知、短信、通话、通讯录、日历、位置、相机、会议录音、TTS/ASR,以及那只狗。每一个
在动手**之前**先检查自己的运行时权限,拒绝就返回 `denied("sms")`,而不是绕过去偷偷做。工具返回
它**看到**的,不是它**希望**的。
@@ -211,8 +163,8 @@ Android 13 及以上,它通过无障碍服务自带的输入通道打字 —
### 脸 —— 性格,不是主题皮肤
-**9. 五个形象、十五种情绪,表情它自己挑。**
-奶油、八戒、贱贱兔、憨憨熊、小恶魔,全部用手写 OpenGL ES 实时绘制。十五种情绪
+**9. 五个形象、十四种情绪,表情它自己挑。**
+奶油、八戒、贱贱兔、憨憨熊、小恶魔,全部用手写 OpenGL ES 实时绘制。十四种情绪
(`ui/ball/Mood.kt`)在"他的感受 / 语音管线在干什么 / 手头有什么活儿"之间仲裁;另有一组待机小
动作,**从不连续重复同一个** —— *"重复看起来像动画卡住了,不像性格"*。现在表情由模型**在句子中间**
自己挑 —— `[开心] 找到了,在第三页。[平静] 要我打开吗?` —— 脸会跟着声音同步变。滑动那颗球,你换的
@@ -257,9 +209,76 @@ WebSocket hub 连到设备。两者之间只是一份普通的工具 schema 契
**16. 没有 Compose,没有 DI 框架,没有协程。**
这是有意的。悬浮窗挂不上 Compose,所以 UI 全是手写 `View`;service 只有一个,所以依赖是手工
-构造函数注入;并发是 `Handler` + 独立 `Executor`。四万两千多行 Kotlin,全部自研 —— 没有一行是从
+构造函数注入;并发是 `Handler` + 独立 `Executor`。四万三千多行 Kotlin,全部自研 —— 没有一行是从
别处拷来的。
+## 快速开始
+
+**最快的一条路,省掉的是真正卡住人的那两件事:自己打包、自己配令牌。**
+
+**[codeflying.app](https://www.codeflying.app)**(English)· **[codeflying.net](https://www.codeflying.net)**
+(中文)就是一个干这件事的通用平台 —— **你用一句话描述想要的应用,它帮你开发并发布。** 不需要先懂
+Android。跟它要一个 Andee,它会交给你一个**已经配好令牌**的安装包。
+
+**它是一个独立的服务,和本项目没有直接关系** —— 不是 Andee 的构建通道,本项目里的东西也管不到它。
+它自己的条款、定价和数据处理方式,都是它自己的。
+
+有两件事它省不掉。**装这一步省不掉** —— 设备那侧仍然是一个 APK,仍然要装到设备上。
+**免费 token 额度也是有限的** —— 够你上手,用完之后需要购买 token。
+
+```text
+1. 打开 https://www.codeflying.net (English: https://www.codeflying.app)
+2. 描述你想要的 Andee
+3. 构建 → 下载安装包(令牌已配好)→ 安装
+4. 开悬浮窗,再开无障碍 → 那颗球就出现了
+```
+
+想自己编译的话:
+
+> **环境要求**
+>
+> - Android 11(API 30)或更新 —— `ACTION_IME_ENTER` 和 `takeScreenshot` 都是 API 30+
+> - **JDK 17–20。** AGP 8.3.1 要 17+;Gradle 8.4 的 wrapper 跑不了 21+(Android Studio 自带的
+> JBR 25 会被直接拒绝:`Unsupported class file major version 69`)
+> - Android SDK:platform 34 + build-tools 34.0.0
+> - **真机。** 这个应用本身就是那个无障碍服务;模拟器能跑,但它几乎什么都干不了
+
+```bash
+./gradlew clean :app:assembleDebug # 产物 app/build/outputs/apk/debug/app-debug.apk
+./gradlew installDebug # 构建并安装到已连接的设备
+
+# 然后在设备上,按这个顺序:
+# 1. 开悬浮窗 → 球出现
+# 2. 开无障碍 → 它能看、能碰屏幕了
+# 3. 点一下那颗球 → 允许麦克风
+# 4. 打开 ⚙,填两个你自己的 Key(见下)
+```
+
+**仓库里不带任何密钥,而这两个缺失的密钥,报出来的错都不像「缺密钥」。** 两个都填在设备的 ⚙ 里 ——
+**一个是必须的,一个只是让你用不了语音:**
+
+**1. 大脑密钥 —— 必须。** `brain = local`(开箱默认)下,智能体循环就跑在设备本机,接任意
+OpenAI 兼容端点(`llm_api_key`,默认 `https://api.deepseek.com`)。**空着,本机大脑根本跑不起来**
+—— 它后面没有别的兜底。球至少会把这句话说出来,而不是默默什么都不做。
+
+**2. 语音密钥 —— 非必须。** 一个[火山引擎语音服务](https://www.volcengine.com/product/voice-tech)
+的 API Key,填在「语音密钥」。不填,识别和合成会在 WebSocket 握手阶段失败,**表现为连接超时** ——
+看着像网络坏了,其实是那一栏空着。其余功能照常,只是既听不见也说不出。
+
+这些不用记:第一次启动会有一个分步引导,带你把这两样填好;之后球的控制条上的 **✓** 会打开自检
+清单,直接告诉你缺哪一个,并给出去处理的按钮。
+
+**打包装 `assembleDebug`,别用 `assembleRelease`。** release 没有 `signingConfig`,仓库里也没有
+keystore,`assembleRelease` 产出的是 `app-release-unsigned.apk`,**装不上**。debug 包用 Android
+默认调试证书签名。
+
+#### 遇到问题
+
+装机流程、以及从零配 SDK 的完整说明(含纯命令行 / CI 路径)在本文下面的
+[Android SDK 下载与配置](#android-sdk-下载与配置)。权限为什么这么要、拒绝了会怎样 —— 在
+**[docs/permissions.zh-CN.md](docs/permissions.zh-CN.md)**。已知限制在 **[SECURITY.md](SECURITY.md)**(英文);
+如果你打算在**你控制不了的网络**上用,先读那一条。
+
## 权限:每一项为什么,以及你拒绝了会怎样
这一节必须有,因为诚实的版本读起来并不舒服:**这个应用申请的权限组合 —— 无障碍、悬浮窗、
@@ -311,8 +330,9 @@ WebSocket hub 连到设备。两者之间只是一份普通的工具 schema 契
## 三种使用方式
- **在线 —— 不用自己打包、不用自己配令牌。** **[codeflying.net](https://www.codeflying.net)**(中文)·
- **[codeflying.app](https://www.codeflying.app)**(English)。描述你想要的 Andee,它会给你一个
- 已经配好令牌的安装包;本地不用编译,也不用先懂 Android。免费额度够上手,用完之后需要购买 token。
+ **[codeflying.app](https://www.codeflying.app)**(English)—— 一个"用一句话描述应用、它帮你开发并
+ 发布"的通用平台,**是独立服务,不属于本项目。** 描述你想要的 Andee,它会给你一个已经配好令牌的
+ 安装包;本地不用编译,也不用先懂 Android。免费额度够上手,用完之后需要购买 token。
- **自己部署。** 克隆、构建、安装 —— 见[快速开始](#快速开始),以及本文下面完整的
[装机顺序建议](#装机顺序建议)。接任意 OpenAI 兼容端点即可运行,**不依赖任何私有后端**。
@@ -669,7 +689,7 @@ app/ Android 应用(Kotlin,无 Compose)
ScreenBodyService.kt 无障碍服务 —— 第一个该读的文件
brain/ 智能体循环 —— LocalBrain、LocalPrompt(角色的行为准则:
§1–§10 是活儿,§11 情景,§12 人格,§13 当前情景)、NotificationTriage(通知分诊)
- ui/ball/ 那张脸 —— Mood(15 种情绪 + 待机小动作)、BallLook(五个形象,每个都是一个角色)
+ ui/ball/ 那张脸 —— Mood(14 种情绪 + 待机小动作)、BallLook(五个形象,每个都是一个角色)
net/ BodyWsServer、BodyWsClient、ToolSchemas(工具定义)
device/ 屏幕控制、权限、保险箱、机器狗
config/ VoiceConfig(设置)、Notebook(记忆、待办、情景 —— 加密存储)
diff --git a/app/src/main/java/net/kuafuai/andee/net/CommandDispatcher.kt b/app/src/main/java/net/kuafuai/andee/net/CommandDispatcher.kt
index 725a662..34aca01 100644
--- a/app/src/main/java/net/kuafuai/andee/net/CommandDispatcher.kt
+++ b/app/src/main/java/net/kuafuai/andee/net/CommandDispatcher.kt
@@ -18,9 +18,11 @@ import java.util.concurrent.TimeUnit
/**
* Routes WS `request` messages (method + params) to controller methods.
*
- * All screen actions live under the `screen.*` namespace. TTS/ASR/audio
- * command routing will be added later under their own namespaces
- * (`tts.speak`, `asr.*`, etc.).
+ * All screen actions live under the `screen.*` namespace. `tts.speak` is the one
+ * voice method that exists — and it is deliberately **not** in [ToolSchemas], so
+ * it is reachable from the debug port but not from the model (see the branch's
+ * own comment). ASR/audio routing is still to come under its own namespace
+ * (`asr.*`).
*
* Contract: return a JSON-serializable value (usually JSONObject) or throw.
* Thrown exceptions become error responses in [BodyWsServer].
diff --git a/docs/permissions.md b/docs/permissions.md
index 4ec40e7..fe00a7c 100644
--- a/docs/permissions.md
+++ b/docs/permissions.md
@@ -103,7 +103,7 @@ Andee has a vault (`config/Vault.kt`) for the account passwords you enter yourse
| What | Where it goes | Default |
|---|---|---|
| Speech recognition (what you say), speech synthesis (what he says) | **Volcengine (ByteDance) cloud** | `openspeech.bytedance.com` |
-| Conversation content, **and every tool result** | The "brain" **you** configured | `brain=hub`; in local mode, `api.deepseek.com` by default |
+| Conversation content, **and every tool result** | The "brain" **you** configured | `brain=local` (the out-of-box default) → `api.deepseek.com`; in hub mode, your own `hub_url` |
| Private notebook (`config/Notebook.kt`: what he remembers about you, what he promised) | **On-device only** | It is `localOnly` and never enters the hub payload |
The second row deserves spelling out: **a tool result is part of the conversation.** The SMS bodies, contacts, call log, notification content and location he reads, along with his "reading" of the screen, all travel with the conversation to the endpoint you configured.
diff --git a/docs/permissions.zh-CN.md b/docs/permissions.zh-CN.md
index f694fd0..e66854c 100644
--- a/docs/permissions.zh-CN.md
+++ b/docs/permissions.zh-CN.md
@@ -103,7 +103,7 @@ Andee 有一个保险箱(`config/Vault.kt`),用来存你自己填进去的
| 什么数据 | 去哪 | 默认值 |
|---|---|---|
| 语音识别(你说的话)、语音合成(他说的) | **火山引擎(字节跳动)云端** | `openspeech.bytedance.com` |
-| 对话内容,**以及全部工具返回结果** | 你配置的"大脑" | `brain=hub`;本机模式默认 `api.deepseek.com` |
+| 对话内容,**以及全部工具返回结果** | 你配置的"大脑" | `brain=local`(开箱默认)→ `api.deepseek.com`;hub 模式下走你自己的 `hub_url` |
| 私人笔记本(`config/Notebook.kt`:记住的你、答应过的事) | **只在本机** | 是 `localOnly`,不进 hub 载荷 |
第二行要说透:**工具返回结果就是对话的一部分。** 他读到的短信正文、通讯录、通话记录、通知内容、定位,以及他对屏幕的"理解",都会随对话发到你配的那个端点。