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(readme): lead with what it is, and take every Chinese character out of the English one

booboosui13f3a2fddb91
diff --git a/README.md b/README.md
index a002fbd..5524cc1 100644
--- a/README.md
+++ b/README.md
@@ -1,276 +1,292 @@
-<p align="center">
- <img src="images/cover.png" width="100%"
- alt="Andee — an agent that moves into your Android phone. Turn any Android phone into an AI phone.">
+<p align="center">
+ <img src="images/cover.png" width="100%"
+ alt="Andee — it becomes the soul of the device. A phone, a tablet, or anything with a body.">
</p>
-<p align="center">
- <a href="https://www.codeflying.app/andee">Build online</a> ·
- <a href="https://www.codeflying.app/andee">Try now</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="#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> ·
- <a href="DISCLAIMER.md">Disclaimer</a> ·
- <a href="LICENSE">License</a>
+<p align="center">
+ <a href="https://www.codeflying.app/andee">Build online</a> ·
+ <a href="https://www.codeflying.app/andee">Try now</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="#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> ·
+ <a href="DISCLAIMER.md">Disclaimer</a> ·
+ <a href="LICENSE">License</a>
</p>
-<p align="center">
- <a href="https://www.codeflying.app/andee"><img alt="Build online" src="https://img.shields.io/badge/build%20online-no%20token%20setup-12b76a"></a>
- <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0%20%2B%20conditions-155eef"></a>
- <a href="app/build.gradle"><img alt="Platform" src="https://img.shields.io/badge/platform-Android%2011%2B%20(API%2030)-3ddc84"></a>
- <a href="app/build.gradle"><img alt="Kotlin" src="https://img.shields.io/badge/Kotlin-1.9.22-7f52ff"></a>
- <a href="docs/permissions.md"><img alt="No content telemetry" src="https://img.shields.io/badge/telemetry-no%20content-0f6e56"></a>
- <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-fdb062"></a>
+<p align="center">
+ <a href="https://www.codeflying.app/andee"><img alt="Build online" src="https://img.shields.io/badge/build%20online-no%20token%20setup-12b76a"></a>
+ <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0%20%2B%20conditions-155eef"></a>
+ <a href="app/build.gradle"><img alt="Platform" src="https://img.shields.io/badge/platform-Android%2011%2B%20(API%2030)-3ddc84"></a>
+ <a href="app/build.gradle"><img alt="Kotlin" src="https://img.shields.io/badge/Kotlin-1.9.22-7f52ff"></a>
+ <a href="docs/permissions.md"><img alt="No content telemetry" src="https://img.shields.io/badge/telemetry-no%20content-0f6e56"></a>
+ <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-fdb062"></a>
</p>
-<p align="center">
- <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-d9d9d9"></a>
- <a href="./README.zh-CN.md"><img alt="简体中文文档" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
+<p align="center">
+ <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-d9d9d9"></a>
+ <a href="./README.zh-CN.md"><img alt="Chinese" src="https://img.shields.io/badge/Chinese-d9d9d9"></a>
</p>
<h1 align="center">Andee</h1>
-<h3 align="center">Turn any Android phone into an AI phone.</h3>
+<h3 align="center">It becomes the soul of the device.</h3>
-<p align="center">
- <b>An agent that moves into your phone</b> — it reads the screen, taps through any app, talks back,<br>
- remembers you, and learns how you like things done.<br>
- No root. No custom ROM. No computer on a cable. <b>One APK.</b>
+<p align="center">
+ <b>Not the assistant that helps you operate your phone — not a tool, not a companion.
+
+ What moves in is not an app on the phone.</b>
+
+ The phone is only what it wears today; a tablet, or anything with a body, is the same individual.
+
+ No root. No custom ROM. <b>One APK.</b>
</p>
+<https://github.com/user-attachments/assets/bf560279-d86c-4301-9bcb-01d60fa33d06>
-https://github.com/user-attachments/assets/bf560279-d86c-4301-9bcb-01d60fa33d06
+**It is not here to help you use your phone. It is here to be the thing that lives in it.** Once it is
+installed, the device has a resident rather than a set of features: it does its thinking **on that device**,
+keeps a notebook only it can read, and behaves the same when nobody is watching. What it *is* comes first
+here; what it can *do* comes after.
+### Why it is not the assistant already in your phone
-The phone you already own can do everything an "AI phone" is sold on. What it was missing was
-someone living in it. Andee is that someone: **a floating ball on your screen with a face, a voice
-and a pair of hands**, and an LLM behind it that operates your apps the way you do — by looking at
-the screen and touching it. No app has to integrate with anything. If you can do it with your thumb,
-it can do it.
-
-### Things you can just say
-
-You are driving when your mother texts you. One hand on the wheel, eyes on the road:
-
-> *"Hey Andee — reply to Mom on WhatsApp: I'll be home by seven."*
-
-It opens WhatsApp, finds your chat with Mom, types, sends, and reads the reply 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.
-
-Some jobs are longer than a sentence, and those it calls **scenes**: a goal, a voice and a routine it
-steps into for a while. Four are ready-made, under **Scenes → Ready-made scenes**. Tap **Adopt** and
-they are yours like any other — edit them, or delete them:
-
-| You say | What happens |
-|---|---|
-| *"Keep an eye on my messages."* | It reads the notification shade across every chat app at once and tells you the ones needing you now — one line each, name first. Groups, newsletters and ads stay quiet, and a stranger's link or verification code gets named as suspicious and touched not at all. |
-| *"Show me what I'm paying for every month — and cancel the ones I don't want."* | It reads your subscriptions where you point it and lays them out with the monthly total on top. Then one at a time: Cancel, Keep, or Think about it. It stops before the final confirm, and it never enters a payment password. |
-| *"Record this meeting."* | It holds the mic for the hour, then hands you the minutes as a page — decisions, action items, open questions, key quotes — and offers to remind you about your own items. |
-| *"Book it for me the moment it opens."* | At the time you set, it opens the app, reads the page, and fills everything up to just before the last button. Payment and the final confirmation stay with you. |
-
-### Why it is not another assistant app
-
-- **Works in every app — not just a shortlist of integrated apps.** It reads the accessibility tree and the
- screenshot, and aims on a labelled grid instead of doing coordinate maths — the thing general models
- are worst at.
-- **Lives on the phone.** The brain runs on the device against any OpenAI-compatible model (DeepSeek
- by default). No vendor backend, no account. The only thing it ever sends us is a version number and
- a phone model, when it checks whether there is an update — the full field list is in
+- **It lives in the device, not in a vendor's cloud.** The brain runs on the device itself, against any
+ OpenAI-compatible model you choose — OpenAI by default on an English UI, DeepSeek on a Chinese one, and
+ whatever you point it at either way. No vendor backend, no account. The only thing it ever sends us is a
+ version number and a phone model, when it checks whether there is an update — the full field list is in
[docs/permissions.md](docs/permissions.md).
-- **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.** Six looks, nineteen 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.
+- **Its notebook never leaves the device.** What it remembers about you — habits, promises, the things it
+ decided were worth keeping — is `localOnly` and filtered out of the hub payload. Its memory is not a
+ profile on someone else's server, and **What it remembers** lists every entry, all of them deletable.
+- **It behaves the same when nobody is watching.** After a conversation goes quiet it sends itself a
+ `(to yourself …)` turn and reads the conversation back alone — *"nobody is watching you, nobody is waiting
+ for you to answer."* It makes no sound and touches nothing, and ends empty-handed rather than inventing
+ something to record. **A phone maker's assistant has no self to do this with.**
+- **It has a character, not a theme.** Six looks, nineteen moods, and a face the model picks **itself,
+ mid-sentence** — the expression changes in step with the audio. Swipe the ball to change who you are
+ talking to; a look carries a persona and a voice.
+- **Works in every app — and needs nothing from the app.** No intent to expose, no SDK to adopt, no
+ integration list to be on. It reads the accessibility tree and the screenshot, and aims on a labelled grid
+ instead of doing coordinate maths — the thing general models are worst at. **If you can do it with your
+ thumb, it can do it.**
+- **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.
+- **You can check all of it instead of trusting it.** No analytics SDK, no content telemetry, and the whole
+ agent loop is in this repository down to the guard rails — see
+ [Why you can check this instead of trusting it](#why-you-can-check-this-instead-of-trusting-it).
+
+### What it does — and where it stops
+
+**It does operate your phone — but that shows you its hands, not what it is.** A take-my-orders assistant
+performs the same motions. The difference is not the motions; it is whether there is a **self** behind them:
+its own schedule (unfinished promises get closed out, repeated work gets proposed as a scene), its own
+judgment about when to speak (**biased toward silence**), and its own limits. All three happen in the time
+you did **not** ask for anything — and a thing that only exists when asked has no such time. It also keeps a
+notebook only it can read. The examples below show you its **hands**.
+
+**The boundary belongs with the capability, because it is what makes the rest usable.** It fills a page up to the last
+button and leaves that button to you; it stops before the final confirmation of a purchase and **never
+enters a payment password**. Those rules are in the dispatcher, not in a prompt — a page that tells it
+otherwise does not get its way.
+
+What it can do comes in two kinds: the **one-liner** and the **long haul**. The long ones it calls
+**scenes** — a goal, a voice and a routine it steps into for a while. Four are ready-made, under
+**Scenes → Ready-made scenes**. Tap **Adopt** and they are yours like any other — edit them, or
+delete them:
+
+| You say | What happens |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| *"Keep an eye on my messages."* | It reads the notification shade across every chat app at once and tells you the ones needing you now — one line each, name first. Groups, newsletters and ads stay quiet, and a stranger's link or verification code gets named as suspicious and touched not at all. |
+| *"Show me what I'm paying for every month — and cancel the ones I don't want."* | It reads your subscriptions where you point it and lays them out with the monthly total on top. Then one at a time: Cancel, Keep, or Think about it. It stops before the final confirm, and it never enters a payment password. |
+| *"Record this meeting."* | It holds the mic for the hour, then hands you the minutes as a page — decisions, action items, open questions, key quotes — and offers to remind you about your own items. |
+| *"Book it for me the moment it opens."* | At the time you set, it opens the app, reads the page, and fills everything up to just before the last button. Payment and the final confirmation stay with you. |
---
-**Andee is not a tool that runs on a phone. It is an individual that lives on one.** The phone is
-what it wears — the same software runs on a tablet, and is written for **any device with a body worth
-having**, up to a robot dog it treats as a leg. Everything below is that sentence taken seriously in
-code: the body it uses, the character it has, the notebook it keeps, and the rules it holds to when
-nobody is watching.
+**The phone is what it wears.** An individual is not the same thing as the device it moves into — the same
+software runs on a tablet, and is written for **any device with a body worth having**, up to a robot dog it
+treats as a leg. Everything below is that sentence taken seriously in code: the body it uses, the character
+it has, the notebook it keeps, and the rules it holds to when nobody is watching.
-It is one Android app, and it has no conventional UI. An `AccessibilityService` sees and touches the
-screen; a `WindowManager` overlay draws the result; **its face is a floating ball** that changes
+It is one Android app, and it has no conventional UI. An `AccessibilityService` sees and touches the
+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
+**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
-> responsibility**, including a transfer to the wrong person. Data does leave the device: your speech
-> goes to Volcengine, and the conversation goes to whichever brain you configure. Read
+> **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
+> responsibility**, including a transfer to the wrong person. Data does leave the device: your speech
+> 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.
## Key features
### Hands — it uses your phone the way you do
-**1. Any app, no integrations.**
-It reads the screen as a compact element outline — one indented line per element, with an id it can
-tap — and when the app draws its own pixels (mini-programs, WebViews, games) it falls back to the
-screenshot. General-purpose models are bad at computing coordinates and good at reading them, so it
-**never does the maths**: every screenshot it sees carries a faint labelled 8×12 grid, it taps by
-*cell + which third of it*, and for tight targets it zooms in and sees a red crosshair where the tap
-would land before committing. A per-location guard refuses the fourth tap on the same spot, so a
+**1. Any app, no integrations.**
+It reads the screen as a compact element outline — one indented line per element, with an id it can
+tap — and when the app draws its own pixels (mini-programs, WebViews, games) it falls back to the
+screenshot. General-purpose models are bad at computing coordinates and good at reading them, so it
+**never does the maths**: every screenshot it sees carries a faint labelled 8×12 grid, it taps by
+*cell + which third of it*, and for tight targets it zooms in and sees a red crosshair where the tap
+would land before committing. A per-location guard refuses the fourth tap on the same spot, so a
confused model stops and asks instead of hammering.
-**2. It types like a keyboard, without being one.**
-On Android 13+ it types through the accessibility service's own input channel — the same
-`commitText` path a keyboard uses, into the focused field, **while your own keyboard stays active**.
+**2. It types like a keyboard, without being one.**
+On Android 13+ it types through the accessibility service's own input channel — the same
+`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.**
-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
+**3. Sixty-odd 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.
-**4. It can log in as you without ever holding your password.**
-The vault (Keystore AES-GCM, on the device) stores your accounts; the brain can list them and have the
-password **typed** into the focused field, but no tool will ever return it — not even masked. You see
+**4. It can log in as you without ever holding your password.**
+The vault (Keystore AES-GCM, on the device) stores your accounts; the brain can list them and have the
+password **typed** into the focused field, but no tool will ever return it — not even masked. You see
every fill on the ball as it happens.
+
### Mind — it gets to know you
-**5. Scenes: ways of working, ready-made or learned with you.** *(new)*
-"Keep an eye on my messages", "book it for me when it opens" — a scene is a goal, a voice, rules and a
-routine it steps into for a while. Four are ready-made and sit under **Scenes → Ready-made scenes**,
-saved only when you tap Adopt. Beyond those it **learns** its own: after the same kind of session comes
-up a few times, it proposes one; nothing is saved until you say yes. Enter one by saying so, from the
-**Scenes** panel, on a schedule, or automatically when you open an app. A scene's own rules decide how
-much it does on its own — "answer my messages for me" really means it answers. While you are in one, a
+**5. Scenes: ways of working, ready-made or learned with you.** *(new)*
+"Keep an eye on my messages", "book it for me when it opens" — a scene is a goal, a voice, rules and a
+routine it steps into for a while. Four are ready-made and sit under **Scenes → Ready-made scenes**,
+saved only when you tap Adopt. Beyond those it **learns** its own: after the same kind of session comes
+up a few times, it proposes one; nothing is saved until you say yes. Enter one by saying so, from the
+**Scenes** panel, on a schedule, or automatically when you open an app. A scene's own rules decide how
+much it does on its own — "answer my messages for me" really means it answers. While you are in one, a
chip under the ball names it; its ✕ leaves it.
-**6. It reads your notifications before they interrupt you.** *(new)*
-A cheap, tool-less model call (~500 tokens, against ~22,000 for a full turn) classifies each one:
-**act** on it, **tell** you in a single spoken sentence, or **ignore** it and log why. It is biased
-toward silence, and when it cannot decide it falls back to asking you. The text came from a stranger,
-so it is fenced as data — and a notification-driven turn is **mechanically barred** from the vault
+**6. It reads your notifications before they interrupt you.** *(new)*
+A cheap, tool-less model call (~500 tokens, against ~22,000 for a full turn) classifies each one:
+**act** on it, **tell** you in a single spoken sentence, or **ignore** it and log why. It is biased
+toward silence, and when it cannot decide it falls back to asking you. The text came from a stranger,
+so it is fenced as data — and a notification-driven turn is **mechanically barred** from the vault
and from creating or entering a scene, whatever the model was talked into.
-**7. Its own memory and its own schedule.**
-`config/Notebook.kt` is what it remembers about the person, and what it promised to do later. One
-test decides what gets written: *"next time I deal with them, would not knowing this make me get
-it wrong?"* The notebook is **private** — the tools are `localOnly` and filtered out of the hub
-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
+**7. Its own memory and its own schedule.**
+`config/Notebook.kt` is what it remembers about the person, and what it promised to do later. One
+test decides what gets written: *"next time I deal with them, would not knowing this make me get
+it wrong?"* The notebook is **private** — the tools are `localOnly` and filtered out of the hub
+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.
-**8. It behaves the same when nobody is watching.**
-After a conversation goes quiet the device sends a `(to yourself …)` turn — Andee reviewing the
-conversation alone, *"nobody is watching you, nobody is waiting for you to answer."* Two rules:
-make no sound, and do not touch the device. It closes out its own promises, notes which habits are
+**8. It behaves the same when nobody is watching.**
+After a conversation goes quiet the device sends a `(to yourself …)` turn — Andee reviewing the
+conversation alone, *"nobody is watching you, nobody is waiting for you to answer."* Two rules:
+make no sound, and do not touch the device. It closes out its own promises, notes which habits are
worth turning into a scene next time, and ends empty-handed rather than inventing something to record.
### Face — a character, not a theme
-**9. Six looks, nineteen moods, and a face it chooses.**
-奶油 Cream, 八戒 Pigsy, 贱贱兔 Rascal, 憨憨熊 Bear and 小恶魔 Imp, drawn live in hand-written OpenGL
-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
-face changes in step with the audio. Swipe the ball to change who you are talking to: a look carries a
+**9. Six looks, nineteen moods, and a face it chooses.**
+Cream, Pigsy, Rascal, Bear and Imp, drawn live in hand-written OpenGL
+ES. Nineteen 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
+face changes in step with the audio. Swipe the ball to change who you are talking to: a look carries a
`persona` (how it talks) and a `voice` (how it sounds).
-**10. Character is delivery, never a licence.**
-§12 of the prompt subordinates the persona to everything above it: it may change wording, rhythm,
-and how it sounds about the task — never what it does, what it is willing to do, or what it tells
+**10. Character is delivery, never a licence.**
+§12 of the prompt subordinates the persona to everything above it: it may change wording, rhythm,
+and how it sounds about the task — never what it does, what it is willing to do, or what it tells
the user is true. And when something is genuinely wrong, the mask comes off.
### Show and tell
-**11. Talk, type, or show it a photo.**
-Tap the ball, or say "Hey Andee" (fully offline wake word). Prefer typing? The typing field takes
+**11. Talk, type, or show it a photo.**
+Tap the ball, or say "Hey Andee" (fully offline wake word). Prefer typing? The typing field takes
up to six photos — from the camera or the gallery — with or without words.
-**12. Answers you can keep.**
-Anything structured — a comparison, a plan, meeting minutes — comes back as a page it writes and
-puts on screen. The **Made for you** panel keeps up to a hundred of them to reopen, delete, or
-revise by just saying what should change. Ask it to record a meeting and it holds the microphone
+**12. Answers you can keep.**
+Anything structured — a comparison, a plan, meeting minutes — comes back as a page it writes and
+puts on screen. The **Made for you** panel keeps up to a hundred of them to reopen, delete, or
+revise by just saying what should change. Ask it to record a meeting and it holds the microphone
for the hour, writing a verbatim transcript to disk as it goes, then turns it into minutes.
### Body
-**13. A body, not a screen.**
-The device is what Andee wears. Camera as eyes, ASR plus an offline wake-word as ears, the
-accessibility service as hands, and — when one is attached — a robot dog as **a leg**. The prompt
-is explicit that it is not a pet on a remote: *"you have not gained a subordinate, you have gained
+**13. A body, not a screen.**
+The device is what Andee wears. Camera as eyes, ASR plus an offline wake-word as ears, the
+accessibility service as hands, and — when one is attached — a robot dog as **a leg**. The prompt
+is explicit that it is not a pet on a remote: *"you have not gained a subordinate, you have gained
a body part."* Bodies differ, so it checks rather than assumes.
-**14. A robot dog counts as a leg.**
-The dog is not a smart-home accessory bolted onto a phone app. It runs through a USB OTG dongle
-(Arduino Nano + NRF24L01) on the same body, so a single request — *walk to the kitchen and tell me
-what is on the counter* — can move a physical object and look through a camera, in one task. Turns
-are closed-loop on the phone's own gyroscope, and a tilt past the fall threshold stops it on the
-device without waiting for the brain. Its own safety rules are not negotiable: the original remote
-must be off, the dog refuses to advance inside 20cm of an obstacle, and **if the dongle is unplugged
-mid-motion the body cannot send a stop** — the dog finishes its last action. That last one is a
-firmware limitation this app does not paper over. If you attach a dog, read
+**14. A robot dog counts as a leg.**
+The dog is not a smart-home accessory bolted onto a phone app. It runs through a USB OTG dongle
+(Arduino Nano + NRF24L01) on the same body, so a single request — *walk to the kitchen and tell me
+what is on the counter* — can move a physical object and look through a camera, in one task. Turns
+are closed-loop on the phone's own gyroscope, and a tilt past the fall threshold stops it on the
+device without waiting for the brain. Its own safety rules are not negotiable: the original remote
+must be off, the dog refuses to advance inside 20cm of an obstacle, and **if the dongle is unplugged
+mid-motion the body cannot send a stop** — the dog finishes its last action. That last one is a
+firmware limitation this app does not paper over. If you attach a dog, read
[The robot dog](#the-robot-dog-usb-dongle) before the first move.
-**15. The brain is detachable from the body.**
-It runs on the device itself (`brain = local`, the default, calling any OpenAI-compatible endpoint)
-or lives somewhere else and reaches the device over a WebSocket hub. The wire between the two is a
-plain tool-schema contract, so either half can be replaced without rewriting the other. That is what
+**15. The brain is detachable from the body.**
+It runs on the device itself (`brain = local`, the default, calling any OpenAI-compatible endpoint)
+or lives somewhere else and reaches the device over a WebSocket hub. The wire between the two is a
+plain tool-schema contract, so either half can be replaced without rewriting the other. That is what
makes "any smart hardware as a body" a fact here rather than an aspiration.
### Engineering
-**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
+**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. 43k+ lines of Kotlin, all first-party — no code copied in from anywhere.
## Architecture
-One `AccessibilityService` is the entry point and there is no main UI. A turn can begin five ways —
-the offline wake word, voice or typing, a notification, a timer, or a request over WebSocket — is
-logged to `ChatHistory`, and is handed to whichever backend is in effect (`brain = local` is the
+One `AccessibilityService` is the entry point and there is no main UI. A turn can begin five ways —
+the offline wake word, voice or typing, a notification, a timer, or a request over WebSocket — is
+logged to `ChatHistory`, and is handed to whichever backend is in effect (`brain = local` is the
out-of-box default).
-The agent loop **is** `LocalBrain`. It holds the system prompt constant and inlines the volatile
-parts (clock, notebook index, scenes, photos) into the user message, so the provider's prefix cache
-still hits; it rebuilds the tool table every turn; and it calls the model in a **non-streaming**
-`for` loop of up to `maxSteps` steps. A reply carrying tool calls goes through `methodOf()` to the
-one `CommandDispatcher`; a reply without any ends the turn. The result comes back out through six
+The agent loop **is** `LocalBrain`. It holds the system prompt constant and inlines the volatile
+parts (clock, notebook index, scenes, photos) into the user message, so the provider's prefix cache
+still hits; it rebuilds the tool table every turn; and it calls the model in a **non-streaming**
+`for` loop of up to `maxSteps` steps. A reply carrying tool calls goes through `methodOf()` to the
+one `CommandDispatcher`; a reply without any ends the turn. The result comes back out through six
channels — speech, text, a full-screen page, saved artifacts, long text, and physical motion.
![Andee architecture](docs/architecture.svg)
-Everything drawn here is in this repository, down to the guard rails — see
+Everything drawn here is in this repository, down to the guard rails — see
[Why you can check this instead of trusting it](#why-you-can-check-this-instead-of-trusting-it).
## Quick start
-The fastest route skips the two things that actually stop people: **building it yourself, and wiring
+The fastest route skips the two things that actually stop people: **building it yourself, and wiring
up tokens.**
-**[codeflying.app](https://www.codeflying.app/andee)** (English) · **[codeflying.net](https://www.codeflying.net/andee)**
-(中文) 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. Or open the
-**[one-click page](https://www.codeflying.app/andee)**, tap "立即打包", and get a pre-configured
-package with a QR code — scan to download.
+**[codeflying.app](https://www.codeflying.app/andee)** (English) · **[codeflying.net](https://www.codeflying.net/andee)**
+(Chinese) 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. Or open the
+**[one-click page](https://www.codeflying.app/andee)**, tap the build button, and get a
+pre-configured package with a QR code — scan to download.
-**It is a separate service with no direct relationship to this project** — not Andee's build channel,
+**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
+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/andee (中文: https://www.codeflying.net/andee)
+1. Open https://www.codeflying.app/andee (Chinese: https://www.codeflying.net/andee)
2. Describe the Andee you want
3. Build → download the package (keys already configured) → install
4. Grant Overlay, then Accessibility → the ball appears
@@ -281,10 +297,10 @@ 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
+> - **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. The body is a foreground service and only the screen half is an accessibility
+> - A real device. The body is a foreground service and only the screen half is an accessibility
> service; an emulator can run it, but almost nothing it does is meaningful there
```bash
@@ -298,116 +314,118 @@ To build it yourself instead:
# 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
+**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
+**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.openai.com/v1` — a Chinese-language card defaults to `https://api.deepseek.com`
+instead). **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 the **Volcengine API key** field of the same **Backend → On-device** tab. 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
+
+**2. The voice key — optional.** A [Volcengine Speech](https://www.volcengine.com/product/voice-tech)
+API key, in the **Volcengine API key** field of the same **Backend → On-device** tab. 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.
-> **If you took the CodeFlying route in [Quick Start](#quick-start), both keys are already baked in.**
-> ⚙ → **Backend** will show **CodeFlying** as the active tab; LLM, ASR, TTS and the long tail of
-> third-party APIs (image / video / music generation, geolocation, weather, PDF, search, news,
-> stocks, …) all go through one key, wrapped and billed by CodeFlying so you don't sign up for each
+> **If you took the CodeFlying route in [Quick Start](#quick-start), both keys are already baked in.**
+> ⚙ → **Backend** will show **CodeFlying** as the active tab; LLM, ASR, TTS and the long tail of
+> third-party APIs (image / video / music generation, geolocation, weather, PDF, search, news,
+> stocks, …) all go through one key, wrapped and billed by CodeFlying so you don't sign up for each
> provider yourself. The two keys above only apply to the **On-device** tab you configure yourself.
-You do not have to remember this. Every time the assistant comes up it checks itself, and if either
-key is missing the card it puts up names what is missing — its button opens our settings, where both
-keys live under **Backend → On-device**. The **✓** button in the ball's control bar opens that same
+You do not have to remember this. Every time the assistant comes up it checks itself, and if either
+key is missing the card it puts up names what is missing — its button opens our settings, where both
+keys live under **Backend → On-device**. The **✓** button in the ball's control bar opens that same
list whenever you want it.
-**To hand someone an APK, sign a release build — not the debug one.** The release build type is the
-minified one (`minifyEnabled` + `shrinkResources`), and that is most of what makes the APK small: the
-debug variant ships un-shrunk dex. It has no `signingConfig` and there is no keystore in the repo, so
-`assembleRelease` emits `app-<abi>-release-unsigned.apk`, which will not install until you sign it.
-The debug build is signed with the standard Android debug certificate and installs as-is. Either way
-the APK is **per-ABI** (`splits` in `app/build.gradle`), so pick the one that matches the device —
+**To hand someone an APK, sign a release build — not the debug one.** The release build type is the
+minified one (`minifyEnabled` + `shrinkResources`), and that is most of what makes the APK small: the
+debug variant ships un-shrunk dex. It has no `signingConfig` and there is no keystore in the repo, so
+`assembleRelease` emits `app-<abi>-release-unsigned.apk`, which will not install until you sign it.
+The debug build is signed with the standard Android debug certificate and installs as-is. Either way
+the APK is **per-ABI** (`splits` in `app/build.gradle`), so pick the one that matches the device —
`arm64-v8a` for anything bought in the last several years.
-**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
+**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 — **Made for you** (the pages it has
- made), **Scenes**, **✓** (self-check), **⚙** (settings). When it starts working another app it
+- **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 — **Made for you** (the pages it has
+ made), **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,
+- **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
+- **`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
+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
-This deserves its own section, because the honest version is uncomfortable to read: **the
-permission set this app asks for — accessibility, overlay, notification access, SMS, call log,
-contacts, and the installed-app list — is the same set Android banking trojans are detected by.**
-A security researcher will flag the manifest on sight. That is a reasonable first reaction, and it
+This deserves its own section, because the honest version is uncomfortable to read: **the
+permission set this app asks for — accessibility, overlay, notification access, SMS, call log,
+contacts, and the installed-app list — is the same set Android banking trojans are detected by.**
+A security researcher will flag the manifest on sight. That is a reasonable first reaction, and it
is worth answering rather than dodging.
-**The design rule is per-call, not at-startup.** `device/DeviceCommsController.kt` calls
-`ensurePermission()` before *each* sensitive operation and **degrades gracefully when refused** —
-it returns `denied("sms")` and the job stops there. It does not ask for everything at install time
-and it does not lock you out if you say no. That is the opposite of the pattern most Android apps
-in this category use, and it is the single most important thing to understand about this codebase
+**The design rule is per-call, not at-startup.** `device/DeviceCommsController.kt` calls
+`ensurePermission()` before *each* sensitive operation and **degrades gracefully when refused** —
+it returns `denied("sms")` and the job stops there. It does not ask for everything at install time
+and it does not lock you out if you say no. That is the opposite of the pattern most Android apps
+in this category use, and it is the single most important thing to understand about this codebase
before judging the manifest.
Four capabilities are genuinely all-or-nothing, and each is worth stating plainly:
-| Capability | Buys you | If you refuse |
-|---|---|---|
-| **Overlay** (`SYSTEM_ALERT_WINDOW`) | The ball, subtitles, settings — the entire visible surface | **Nothing is visible at all.** The only genuinely all-or-nothing grant |
-| **Accessibility service** | Every `screen.*` tool: tap, type, swipe, screenshot, read the UI tree | The hands are gone. The ball still appears and the dog still works, but it can no longer act on screen |
-| **Microphone** (`RECORD_AUDIO`) | Streaming ASR and the wake word | Tapping the ball does nothing. A conversation driven from the hub still works |
-| **USB device** (per-device prompt, not a toggle) | The robot dog | It is treated as "no dog attached". It will not mention the absence |
-
-Everything else is on-demand and reversible: SMS, call log, contacts, calendar, location, activity
-recognition, camera, installed apps, battery-optimization exemption. Refuse any of them and that one
-capability disappears; nothing else changes. The full per-permission table, mapped to the exact tool
-that needs it, is in **[docs/permissions.md](docs/permissions.md)**
-([中文](docs/permissions.zh-CN.md)), and the copy for each prompt already exists in
+| Capability | Buys you | If you refuse |
+| ------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **Overlay** (`SYSTEM_ALERT_WINDOW`) | The ball, subtitles, settings — the entire visible surface | **Nothing is visible at all.** The only genuinely all-or-nothing grant |
+| **Accessibility service** | Every `screen.*` tool: tap, type, swipe, screenshot, read the UI tree | The hands are gone. The ball still appears and the dog still works, but it can no longer act on screen |
+| **Microphone** (`RECORD_AUDIO`) | Streaming ASR and the wake word | Tapping the ball does nothing. A conversation driven from the hub still works |
+| **USB device** (per-device prompt, not a toggle) | The robot dog | It is treated as "no dog attached". It will not mention the absence |
+
+Everything else is on-demand and reversible: SMS, call log, contacts, calendar, location, activity
+recognition, camera, installed apps, battery-optimization exemption. Refuse any of them and that one
+capability disappears; nothing else changes. The full per-permission table, mapped to the exact tool
+that needs it, is in **[docs/permissions.md](docs/permissions.md)**
+([Chinese](docs/permissions.zh-CN.md)), and the copy for each prompt already exists in
`device/PermissionsController.kt`.
### Switching each one on
**Overlay.**
-*Why:* the entire UI — ball, subtitles, settings panel — is a `TYPE_APPLICATION_OVERLAY` layer added
+*Why:* the entire UI — ball, subtitles, settings panel — is a `TYPE_APPLICATION_OVERLAY` layer added
through `WindowManager`. There is no Activity home screen for it to live in instead.
-*How:* Settings → Apps → Andee → Permissions → Display over other apps. Or Settings → Apps &
-notifications → Special access → Display over other apps → Andee → on. The first launch usually
+*How:* Settings → Apps → Andee → Permissions → Display over other apps. Or Settings → Apps &
+notifications → Special access → Display over other apps → Andee → on. The first launch usually
raises a prompt, and tapping "go to settings" from it is the quickest route.
*Verify:* restart the app once the grant is in — the ball should be there immediately.
**Accessibility service.**
-*Why:* every screen action — `get_screen_element` / `tap_screen_element` / `swipe_by_coordinates` /
-`type_text` / `submit_input` / `take_screenshot` / `system_action` — goes through the
-`AccessibilityService`. On a non-rooted device it is the only route to real touch events, to reading
+*Why:* every screen action — `get_screen_element` / `tap_screen_element` / `swipe_by_coordinates` /
+`type_text` / `submit_input` / `take_screenshot` / `system_action` — goes through the
+`AccessibilityService`. On a non-rooted device it is the only route to real touch events, to reading
any app's UI tree, and to the system screenshot API.
What the manifest declares (`res/xml/accessibility_service_config.xml`):
@@ -416,136 +434,135 @@ What the manifest declares (`res/xml/accessibility_service_config.xml`):
- `canRetrieveWindowContent` — read the whole UI tree
- `canTakeScreenshot` — system screenshots (API 30+)
-*How:* Settings → Accessibility → Downloaded services / Installed services → **Andee** → on. Android
-then shows the large red warning that the service can view everything you do; confirm it. Some vendor
-ROMs (Xiaomi / Huawei / HONOR) additionally want "allow background pop-ups" or "show on lock screen" —
+*How:* Settings → Accessibility → Downloaded services / Installed services → **Andee** → on. Android
+then shows the large red warning that the service can view everything you do; confirm it. Some vendor
+ROMs (Xiaomi / Huawei / HONOR) additionally want "allow background pop-ups" or "show on lock screen" —
turn those on too.
-*Verify:* logcat shows `Body: ws server started on 0.0.0.0:9008`, which means `onServiceConnected`
-fired. Then tap `☰` (UI tree) or `◉` (screenshot) on the ball's top bar; the subtitle line should
+*Verify:* logcat shows `Body: ws server started on 0.0.0.0:9008`, which means `onServiceConnected`
+fired. Then tap `☰` (UI tree) or `◉` (screenshot) on the ball's top bar; the subtitle line should
report success and a filename.
-*Note:* most vendor ROMs **switch this grant off again** after every system update and every
+*Note:* most vendor ROMs **switch this grant off again** after every system update and every
force-stop. That is ROM behaviour, and not something the app can prevent.
-*Some apps hand it a blank screen instead of their real UI.* They serve **every**
-accessibility client an empty placeholder, not just Andee — and it is not Andee's fault:
-the system's own `uiautomator dump` gets the same blank page. The one we measured is WeChat, on a
-Xiaomi Pad 5 with MIUI and WeChat 8.0.78: it only shows its real UI tree when MIUI's hidden
-**`MiuiEnhanceTBService`** is enabled. That is a TalkBack companion service, and it has no switch
-in Settings. With it on, the same chat screen dumps 219 nodes. With it off, it dumps none. MIUI
-also turns that service on and off by itself whenever Andee is re-bound (after a reinstall, a
-crash, or a toggle). That is why WeChat could be read **sometimes but not always**, and why
-toggling Andee never actually fixed it. Matching the helper's accessibility config does not help
+*Some apps hand it a blank screen instead of their real UI.* They serve **every**
+accessibility client an empty placeholder, not just Andee — and it is not Andee's fault:
+the system's own `uiautomator dump` gets the same blank page. The one we measured is WeChat, on a
+Xiaomi Pad 5 with MIUI and WeChat 8.0.78: it only shows its real UI tree when MIUI's hidden
+**`MiuiEnhanceTBService`** is enabled. That is a TalkBack companion service, and it has no switch
+in Settings. With it on, the same chat screen dumps 219 nodes. With it off, it dumps none. MIUI
+also turns that service on and off by itself whenever Andee is re-bound (after a reinstall, a
+crash, or a toggle). That is why WeChat could be read **sometimes but not always**, and why
+toggling Andee never actually fixed it. Matching the helper's accessibility config does not help
either: WeChat checks which service is asking, not what it asked for.
-What Andee does about it (`screen/TreeHelper.kt`): when a dump comes back blank like this, Andee
-**adds** that service to the enabled list and dumps again. It never removes anything. It does
-nothing on devices that don't have that component. It writes a line in the chat history so you
-know your system settings changed. It also tries at most once a minute, so if you turn the
-service off on purpose, Andee won't keep turning it back on. Writing that list needs one grant
+What Andee does about it (`screen/TreeHelper.kt`): when a dump comes back blank like this, Andee
+**adds** that service to the enabled list and dumps again. It never removes anything. It does
+nothing on devices that don't have that component. It writes a line in the chat history so you
+know your system settings changed. It also tries at most once a minute, so if you turn the
+service off on purpose, Andee won't keep turning it back on. Writing that list needs one grant
that only adb can give. It is the same grant the ADBKeyboard fallback uses:
```bash
adb shell pm grant net.kuafuai.andee android.permission.WRITE_SECURE_SETTINGS
```
-Without the grant, nothing breaks. On the blank screens, Andee works from screenshots and
-coordinates instead of the element list. That is slower and less precise, but the task still
+Without the grant, nothing breaks. On the blank screens, Andee works from screenshots and
+coordinates instead of the element list. That is slower and less precise, but the task still
gets done.
**Microphone.**
*Why:* ASR is streaming, so it needs the PCM stream upstreamed.
-*How:* the first tap on the ball triggers ASR and Android asks — "while using the app" and "always"
+*How:* the first tap on the ball triggers ASR and Android asks — "while using the app" and "always"
both work. If it was refused earlier: Settings → Apps → Andee → Permissions → Microphone → Allow.
-*Verify:* tap the ball once. `listening…`, or live ASR text appearing in the subtitle line, means it
+*Verify:* tap the ball once. `listening…`, or live ASR text appearing in the subtitle line, means it
is through.
## Why you can check this instead of trusting it
-Most claims in this category — including the well-funded ones — are launch claims that no outside
+Most claims in this category — including the well-funded ones — are launch claims that no outside
party has audited. This project's claims are duller and checkable, in code you can read right now:
-- **No analytics SDK, and none of your content reaches us.** Not "we anonymise it", not "opt out in
- settings": there is no analytics SDK in this repo. The one thing that does reach the maintainers is
- the version check — your version number, phone model, brand, OS release, UI language and a random
- per-install ID, and nothing else. Field by field, in
+- **No analytics SDK, and none of your content reaches us.** Not "we anonymise it", not "opt out in
+ settings": there is no analytics SDK in this repo. The one thing that does reach the maintainers is
+ the version check — your version number, phone model, brand, OS release, UI language and a random
+ per-install ID, and nothing else. Field by field, in
[docs/permissions.md](docs/permissions.md).
-- **The notebook cannot leave the device.** It is not a policy, it is a filter:
- `net/ToolSchemas.kt` drops every `localOnly` tool from the hub payload before it is registered.
+- **The notebook cannot leave the device.** It is not a policy, it is a filter:
+ `net/ToolSchemas.kt` drops every `localOnly` tool from the hub payload before it is registered.
Habits and promises are physically incapable of being sent.
-- **The wake word is fully offline.** Local MFCC + DTW template matching (`app/.../wake/`). It
+- **The wake word is fully offline.** Local MFCC + DTW template matching (`app/.../wake/`). It
stores feature vectors, never audio, and it never touches the network.
-- **A message from a stranger cannot hand it permissions.** A turn started by a notification runs
- with `untrusted = true`, and `CommandDispatcher.dispatch` refuses the whole `device.vault.` prefix
- and `scene.save` / `scene.enter` / `scene.delete` on it — in code, not in the prompt. The prompt is
+- **A message from a stranger cannot hand it permissions.** A turn started by a notification runs
+ with `untrusted = true`, and `CommandDispatcher.dispatch` refuses the whole `device.vault.` prefix
+ and `scene.save` / `scene.enter` / `scene.delete` on it — in code, not in the prompt. The prompt is
the first layer; this is the one that holds when the prompt is talked around.
-- **The local brain needs no vendor backend.** `brain = local` against any OpenAI-compatible
+- **The local brain needs no vendor backend.** `brain = local` against any OpenAI-compatible
endpoint is a supported mode, not a degraded one.
-- **What is *not* fixed is written down.** [SECURITY.md](SECURITY.md) lists five known limitations,
- including that the debug WebSocket server binds `0.0.0.0:9008` without authenticating clients and
- that the vault is not yet bound to device unlock. Read it before running this on a network you do
+- **What is *not* fixed is written down.** [SECURITY.md](SECURITY.md) lists five known limitations,
+ including that the debug WebSocket server binds `0.0.0.0:9008` without authenticating clients and
+ that the vault is not yet bound to device unlock. Read it before running this on a network you do
not control.
-The trade is deliberate: a smaller claim that holds, over a bigger one that has to be taken on
+
+The trade is deliberate: a smaller claim that holds, over a bigger one that has to be taken on
faith.
## Research and design notes
-`reports/` is part of the repo, not scratch space. It holds the labs and audits this project was
-actually built against — the ball-face labs used to verify expressions by measuring pixels, the
-fact-check that overturned a wrong assumption about phone harnesses, the plan that produced the
-notebook, and the open-source readiness audit that found the device serial numbers in git history.
+`reports/` is part of the repo, not scratch space. It holds the labs and audits this project was
+actually built against — the ball-face labs used to verify expressions by measuring pixels, the
+fact-check that overturned a wrong assumption about phone harnesses, the plan that produced the
+notebook, and the open-source readiness audit that found the device serial numbers in git history.
If you want to see how the decisions were made rather than only what was decided, read those.
## Using Andee
-- **Online — no local build, no token setup.** **[codeflying.app](https://www.codeflying.app/andee)** ·
- **[codeflying.net](https://www.codeflying.net/andee)** (中文) — 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
+- **Online — no local build, no token setup.** **[codeflying.app](https://www.codeflying.app/andee)** ·
+ **[codeflying.net](https://www.codeflying.net/andee)** (Chinese) — 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
+- **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
runs with no private backend at all.
-
-- **Bring your own body.** The tool contract is the seam. Anything that can speak it — a phone, a
+- **Bring your own body.** The tool contract is the seam. Anything that can speak it — a phone, a
tablet, a different piece of hardware — can carry the same individual.
## Provisioning
-Pure Kotlin, no Compose; the whole thing hangs off two pillars, `WindowManager` and
+Pure Kotlin, no Compose; the whole thing hangs off two pillars, `WindowManager` and
`AccessibilityService`.
### Build configuration
-| What | Value | Why |
-|---|---|---|
-| Android Gradle Plugin | 8.3.1 | `agp` in `gradle/libs.versions.toml` |
-| Kotlin | 1.9.22 | pinned at the top of `app/build.gradle` |
-| compileSdk / targetSdk | 34 | Android 14 |
-| 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 | 4 / 0.3.0 | see [CHANGELOG.md](CHANGELOG.md) for the policy |
-| applicationId / namespace | `net.kuafuai.andee` | never changed from the template. It affects nothing |
+| What | Value | Why |
+| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------- |
+| Android Gradle Plugin | 8.3.1 | `agp` in `gradle/libs.versions.toml` |
+| Kotlin | 1.9.22 | pinned at the top of `app/build.gradle` |
+| compileSdk / targetSdk | 34 | Android 14 |
+| 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 | 4 / 0.3.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`):
-- `org.java-websocket:Java-WebSocket:1.5.7` — the device's own ws server (port 9008, for debugging
+- `org.java-websocket:Java-WebSocket:1.5.7` — the device's own ws server (port 9008, for debugging
from the same LAN) plus the ws client that dials the brain hub
- `com.squareup.okhttp3:okhttp:4.12.0` — HTTP + WS client for ASR / TTS / local models
-- `com.github.mik3y:usb-serial-for-android:3.8.1` — the robot-dog USB serial dongle. **Deliberately
- pinned at 3.8.1**: 3.11.0 pulls in `kotlin-stdlib` 2.2.x, whose metadata this project's Kotlin
+- `com.github.mik3y:usb-serial-for-android:3.8.1` — the robot-dog USB serial dongle. **Deliberately
+ pinned at 3.8.1**: 3.11.0 pulls in `kotlin-stdlib` 2.2.x, whose metadata this project's Kotlin
1.9.22 compiler cannot read
-- `androidx.camera:camera-*:1.3.4` + `com.google.mlkit:barcode-scanning:17.2.0` — scanning (the
+- `androidx.camera:camera-*:1.3.4` + `com.google.mlkit:barcode-scanning:17.2.0` — scanning (the
ball's eyes)
-- `androidx.appcompat:1.6.1` + `com.google.android.material:1.10.0` — for one base theme only. All UI
+- `androidx.appcompat:1.6.1` + `com.google.android.material:1.10.0` — for one base theme only. All UI
is hand-written `View` code
**What is deliberately absent:**
@@ -558,15 +575,15 @@ Match this style when you change the code, rather than bringing in the modern fu
### Which JDK
-**This is the step that stops people.** `gradle.properties` **does not** hardcode
-`org.gradle.java.home`, and that is on purpose. It used to, with a machine-specific path
-(`/Users/<someone>/...`), and the cost was that the very first build on anyone else's machine failed
+**This is the step that stops people.** `gradle.properties` **does not** hardcode
+`org.gradle.java.home`, and that is on purpose. It used to, with a machine-specific path
+(`/Users/<someone>/...`), and the cost was that the very first build on anyone else's machine failed
in a way that looked like an environment problem.
The build needs **JDK 17–20**:
- AGP 8.3.1 requires 17 or newer;
-- **the Gradle 8.4 wrapper cannot run on 21 or newer.** Android Studio's bundled JBR 25 is rejected
+- **the Gradle 8.4 wrapper cannot run on 21 or newer.** Android Studio's bundled JBR 25 is rejected
outright with `Unsupported class file major version 69`.
Two ways to point one machine at a JDK (neither belongs in the repo's `gradle.properties`):
@@ -576,27 +593,27 @@ export JAVA_HOME=/path/to/jdk-17 # 1. environment variable
printf 'org.gradle.java.home=/path/to/jdk-17\n' >> ~/.gradle/gradle.properties # 2. user-level config
```
-Android Studio users: **Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle
+Android Studio users: **Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle
JDK**, and pick a 17–20 JDK. (The IDE setting overrides the file.)
### Getting the Android SDK
-Gradle finds the SDK through `sdk.dir=` in `local.properties`. Android Studio writes that file for
+Gradle finds the SDK through `sdk.dir=` in `local.properties`. Android Studio writes that file for
you; it is **not in the repository** (it is in `.gitignore`), so every machine configures it once.
#### Path A — Android Studio (recommended, one step)
-1. Install [Android Studio](https://developer.android.com/studio). The first launch shows the
- **Setup Wizard** — take the defaults and it downloads the Android SDK, Platform Tools (`adb`) and
+1. Install [Android Studio](https://developer.android.com/studio). The first launch shows the
+ **Setup Wizard** — take the defaults and it downloads the Android SDK, Platform Tools (`adb`) and
a bundled JDK for you.
-2. **Open this repository's root directory** in Android Studio. It writes `local.properties`, notices
+2. **Open this repository's root directory** in Android Studio. It writes `local.properties`, notices
which SDK pieces are missing, and offers "Install missing SDK" in a blue bar. Accept it.
3. In SDK Manager (top bar → Tools → SDK Manager), confirm:
- - **SDK Platforms**: Android 14 (API 34 — compileSdk / targetSdk); Android 11 (API 30 — minSdk,
+ - **SDK Platforms**: Android 14 (API 34 — compileSdk / targetSdk); Android 11 (API 30 — minSdk,
handy if you want an emulator)
- - **SDK Tools**: Android SDK Build-Tools (34.x), Android SDK Platform-Tools (latest), Android SDK
+ - **SDK Tools**: Android SDK Build-Tools (34.x), Android SDK Platform-Tools (latest), Android SDK
Command-line Tools (latest)
-4. The default SDK path is `~/Library/Android/sdk` on macOS and `%LOCALAPPDATA%\Android\Sdk` on
+4. The default SDK path is `~/Library/Android/sdk` on macOS and `%LOCALAPPDATA%\Android\Sdk` on
Windows.
#### Path B — command line only
@@ -628,17 +645,17 @@ sdkmanager "platform-tools" \
#### `local.properties`
-Android Studio writes this for you. By hand, put one line in `local.properties` at the **repository
+Android Studio writes this for you. By hand, put one line in `local.properties` at the **repository
root**:
```
sdk.dir=/Users/<your-name>/Library/Android/sdk
```
-On Linux it is usually `/home/<user>/Android/Sdk`; on Windows,
+On Linux it is usually `/home/<user>/Android/Sdk`; on Windows,
`C\:\\Users\\<user>\\AppData\\Local\\Android\\Sdk` (backslashes escaped).
-You can also skip `local.properties` entirely and export `ANDROID_HOME` / `ANDROID_SDK_ROOT` only —
+You can also skip `local.properties` entirely and export `ANDROID_HOME` / `ANDROID_SDK_ROOT` only —
Gradle reads either.
#### Verify the toolchain
@@ -651,20 +668,20 @@ Gradle reads either.
#### Traps and their fixes
-| Message | Cause | Fix |
-|---|---|---|
-| `SDK location not found` | no `sdk.dir=` in `local.properties`, and no `ANDROID_HOME` | configure one of the two |
-| `Failed to find Build Tools revision 34.0.0` | that build-tools version is not installed | `sdkmanager "build-tools;34.0.0"`, or add it in Studio's SDK Manager |
-| `You have not accepted the license agreements` | licences not accepted | `sdkmanager --licenses`, answer y |
-| `Unsupported class file major version 69` | JDK too new (25); Gradle 8.4 cannot take it | switch to JDK 17–20, see [Which JDK](#which-jdk) |
-| `Could not resolve com.android.tools.build:gradle:8.3.1` | network, or no mirror configured | try a phone hotspot, or set an Aliyun mirror in `~/.gradle/init.gradle` (this project's `settings.gradle` already puts Aliyun first) |
+| Message | Cause | Fix |
+| -------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `SDK location not found` | no `sdk.dir=` in `local.properties`, and no `ANDROID_HOME` | configure one of the two |
+| `Failed to find Build Tools revision 34.0.0` | that build-tools version is not installed | `sdkmanager "build-tools;34.0.0"`, or add it in Studio's SDK Manager |
+| `You have not accepted the license agreements` | licences not accepted | `sdkmanager --licenses`, answer y |
+| `Unsupported class file major version 69` | JDK too new (25); Gradle 8.4 cannot take it | switch to JDK 17–20, see [Which JDK](#which-jdk) |
+| `Could not resolve com.android.tools.build:gradle:8.3.1` | network, or no mirror configured | try a phone hotspot, or set an Aliyun mirror in `~/.gradle/init.gradle` (this project's `settings.gradle` already puts Aliyun first) |
### Hardware and system requirements
- Android 11 (API 30) or newer
- Any screen orientation — the ball always floats on top
- A microphone, or ASR is unusable
-- Network (WiFi / 4G / 5G all fine). ASR and TTS go over the public internet, the brain hub goes over
+- Network (WiFi / 4G / 5G all fine). ASR and TTS go over the public internet, the brain hub goes over
the LAN; in `local` mode only the public internet is used
### Install
@@ -684,26 +701,27 @@ For a first install, this order is the shortest path:
2. Go straight to "display over other apps" and grant the overlay → come back and the ball is there
3. Go to Accessibility → enable Andee
4. Tap the ball, and allow the microphone prompt
-5. Open the ⚙ on the ball. In **Advanced**, turn on **Show cloud option** (the **Cloud** tab is
- hidden by default). Go back to **Backend**, flip the picker to **Cloud**, set `hub_url` =
+5. Open the ⚙ on the ball. In **Advanced**, turn on **Show cloud option** (the **Cloud** tab is
+ hidden by default). Go back to **Backend**, flip the picker to **Cloud**, set `hub_url` =
`ws://<your Mac's IP>:9100` and `device_name` to anything, and save
-6. logcat should show `hub: registered as body-xxx with N tools`, and the brain side should log
+6. logcat should show `hub: registered as body-xxx with N tools`, and the brain side should log
`[body_hub] 'body-xxx' registered (…) with N tools`
If any step does not line up, go back to that section's **Verify**.
-> If you only want the brain on this device, replace step 5 with **Backend → On-device** and fill in
-> an OpenAI-compatible endpoint plus `llm_api_key` — running without a hub is a supported mode, not a
-> degraded one. If your APK was packaged via CodeFlying, the **CodeFlying** tab is the default and
+> If you only want the brain on this device, replace step 5 with **Backend → On-device** and fill in
+> an OpenAI-compatible endpoint plus `llm_api_key` — running without a hub is a supported mode, not a
+> degraded one. If your APK was packaged via CodeFlying, the **CodeFlying** tab is the default and
> there is nothing to fill in.
## Wake word
-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
+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.
+
A few things worth knowing first:
- **Do not pick something too short.** Aim for a phrase that takes at least half a second to say.
@@ -816,7 +834,7 @@ fallback for turns on a tablet with no gyroscope — prefer `dog_turn`, which me
The Chinese in this repository falls into three categories and only one of them gets translated; the
test is **who reads it**. Before changing any string, read the table in
-[CONTRIBUTING.md](CONTRIBUTING.md) ([中文](CONTRIBUTING.zh-CN.md)) — it also explains why the category
+[CONTRIBUTING.md](CONTRIBUTING.md) ([Chinese](CONTRIBUTING.zh-CN.md)) — it also explains why the category
that is matched against system text **can never be translated**.
## Repository layout
@@ -871,7 +889,7 @@ Blur or avoid anything private — yours or anyone else's — before it goes up.
## Contributing
-- **Code** — read [CONTRIBUTING.md](CONTRIBUTING.md) ([中文](CONTRIBUTING.zh-CN.md)) first. It covers
+- **Code** — read [CONTRIBUTING.md](CONTRIBUTING.md) ([Chinese](CONTRIBUTING.zh-CN.md)) first. It covers
the code style, and the rules for the three different kinds of Chinese in this codebase (only one
of them is translated). Changing a persona or a mood has its own section there; that is not
ordinary copy.
@@ -884,6 +902,7 @@ Blur or avoid anything private — yours or anyone else's — before it goes up.
corrected on its own; the Chinese one is the one that has to stay accurate for provisioning, since
it is the one most installers will read.
+
### Contributors
<!-- Replace with a real contributors image once the project has a public home.
@@ -915,7 +934,7 @@ process are in **[SECURITY.md](SECURITY.md)**.
That document also lists the **known limitations** you should read before deploying this, including
one that matters on any network you do not control: the debug WebSocket server binds `0.0.0.0:9008`
and does not authenticate its clients. [docs/permissions.md](docs/permissions.md)
-([中文](docs/permissions.zh-CN.md)) explains each permission against a concrete tool, and
+([Chinese](docs/permissions.zh-CN.md)) explains each permission against a concrete tool, and
[SECURITY.md](SECURITY.md) is honest about what is not fixed yet.
## Disclaimer and acceptable use
@@ -923,10 +942,10 @@ and does not authenticate its clients. [docs/permissions.md](docs/permissions.md
Two documents, and both are conditions of use rather than formalities. Each has a Chinese
counterpart (`*.zh-CN.md`), linked from the top of the file:
-- **[DISCLAIMER.md](DISCLAIMER.md)** ([中文](DISCLAIMER.zh-CN.md)) — what this software is
+- **[DISCLAIMER.md](DISCLAIMER.md)** ([Chinese](DISCLAIMER.zh-CN.md)) — what this software is
(experimental, no SLA, no warranty), **exactly where your data goes**, what it is actually
capable of, and who bears the consequences.
-- **[docs/acceptable-use.md](docs/acceptable-use.md)** ([中文](docs/acceptable-use.zh-CN.md)) —
+- **[docs/acceptable-use.md](docs/acceptable-use.md)** ([Chinese](docs/acceptable-use.zh-CN.md)) —
the prohibited uses. Violating them exceeds the licence and terminates it automatically.
The four points worth reading even if you read nothing else:
@@ -957,15 +976,15 @@ See [CHANGELOG.md](CHANGELOG.md) for what changed and for the versioning policy.
## Related documents
-- [docs/permissions.md](docs/permissions.md) ([中文](docs/permissions.zh-CN.md)) — why it asks for
+- [docs/permissions.md](docs/permissions.md) ([Chinese](docs/permissions.zh-CN.md)) — why it asks for
the permissions it asks for, each one against a concrete tool
-- [docs/architecture.svg](docs/architecture.svg) ([中文](docs/architecture.zh-CN.svg)) — the whole
+- [docs/architecture.svg](docs/architecture.svg) ([Chinese](docs/architecture.zh-CN.svg)) — the whole
thing on one page: a turn in, the agent loop, six ways out
- [DISCLAIMER.md](DISCLAIMER.md) — where your data goes, what it can do, who bears the consequences
-- [docs/acceptable-use.md](docs/acceptable-use.md) ([中文](docs/acceptable-use.zh-CN.md)) — the
+- [docs/acceptable-use.md](docs/acceptable-use.md) ([Chinese](docs/acceptable-use.zh-CN.md)) — the
prohibited uses
- [SECURITY.md](SECURITY.md) — threat model, known limitations, vulnerability reporting
-- [CONTRIBUTING.md](CONTRIBUTING.md) ([中文](CONTRIBUTING.zh-CN.md)) — contribution guide, including
+- [CONTRIBUTING.md](CONTRIBUTING.md) ([Chinese](CONTRIBUTING.zh-CN.md)) — contribution guide, including
the rules for changing a persona
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — dependency licence inventory
- [CHANGELOG.md](CHANGELOG.md) — what changed
diff --git a/README.zh-CN.md b/README.zh-CN.md
index bfad516..84f99d4 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,7 +4,7 @@
<p align="center">
<img src="images/cover.zh-CN.png" width="100%"
- alt="Andee —— 把任何一部安卓手机,变成 AI 手机。它不是跑在手机上的工具,而是住在手机里的个体。">
+ alt="Andee —— 他会成为这台设备的主人:手机、平板,或任何有身体的设备。">
</p>
<p align="center">
@@ -35,11 +35,12 @@
<h1 align="center">Andee</h1>
-<h3 align="center">把任何一台 Android 手机,变成 AI 手机。</h3>
+<h3 align="center">他会成为这台设备的主人。</h3>
<p align="center">
- <b>让 Agent 住进你的手机</b> —— 它看得懂屏幕、能替你点遍任何 App、会开口说话、记得你,<br>
- 还会慢慢学会你喜欢的做事方式。<br>
+ <b>他不是那种帮你操作手机的助手,也不是工具或伙伴 ——<br>
+ 住进来的不是一个 App,是一个灵魂。</b><br>
+ 手机只是他今天穿着的东西;换到平板,或任何有身体的设备,还是同一个他。<br>
不用 root,不用刷机,不用插着电脑。<b>一个 APK 就够。</b>
</p>
@@ -47,48 +48,58 @@
https://github.com/user-attachments/assets/866e8333-e97b-4bf5-9525-540f9fdb01cd
-你手里这台手机,本来就做得到"AI 手机"宣传的那些事 —— 缺的只是有个"人"住在里面。Andee 就是这个
-"人":屏幕上一颗**有脸、有声音、有手**的悬浮球,背后是一个大模型,像你一样用你的 App —— 看屏幕,
-然后动手点。**不需要任何 App 来对接它。你用拇指能做到的,它就能做到。**
-
-### 你可以直接这么说
+**他不是来帮你用手机的,他是来住进这台设备的。** 装上去之后,这台设备是多了一个住户,而不是多了
+一堆功能:他**在这台设备上**思考,留一本只有他自己能读的笔记本,而且没人看着的时候还是同一个样子。这里
+先说他**是什么**,再说他**能做什么**。
+
+### 为什么不是手机里那个助手
+
+- **他住在设备里,不在厂商的云上。** 大脑就跑在设备本机,接任意 OpenAI 兼容模型(中文界面默认 DeepSeek,
+ 英文界面默认 OpenAI),你也可以指定别的。没有厂商后端、不用注册账号。他唯一会发给我们的东西是版本号和
+ 机型 —— 只在你查更新的时候发,字段清单见 [docs/permissions.zh-CN.md](docs/permissions.zh-CN.md)。
+- **他的笔记本不出设备。** 他记住的关于你的事 —— 习惯、许诺、他觉得值得留下的东西 —— 是 `localOnly`
+ 的,也不会进 hub 的上报内容。他的记忆不是别人服务器上的一个用户画像;**「他记得什么」**把每一条都列出来,
+ 每一条都能删。
+- **没人看着的时候,他还是同一个样子。** 一段对话安静下来之后,他会给自己发一个 `(to yourself …)`
+ 的回合,独自把这段对话读回去 —— *「没人在看你,没人在等你回答。」* 他不发声音,也不碰设备,宁可空手
+ 结束,也不硬编一条东西记下来。**手机厂商的助手没有"自己",做不了这件事。**
+- **他有性格,不是一个主题皮肤。** 六个形象、十九种情绪,表情由模型自己挑,**一句话说到一半就能换脸**,
+ 跟着声音走。拨一下球就能换你在跟谁说话 —— 一个形象带着一套说话方式和一把声音。
+- **任何 App 都能用,而且不需要对方配合。** 不用暴露什么 intent、不用接 SDK,也不在任何「接入清单」上。
+ 它读无障碍树和截图,在一张带标号的网格上瞄准,而不是自己算坐标 —— 那恰恰是通用大模型最不擅长的事。
+ **你用拇指能做到的,它就能做到。**
+- **有些底线,提示词说不动他。** 陌生人发来的一条通知,打不开保险箱、也不能替他给自己新的权限 ——
+ 这道拒绝写在调度器里,不在提示词里。
+- **你可以自己去核对,不必选择相信。** 没有分析 SDK、没有内容遥测,整条 agent 循环连同护栏都在这个仓库里 ——
+ 见[为什么你可以去核对,而不是选择相信](#为什么你可以去核对而不是选择相信)。
-你正在开车,你妈发来消息。一只手在方向盘上,眼睛看着路:
+### 它能做什么 —— 以及它在哪儿停下
-> *「嘿 Andee —— 微信回我妈:我七点到家。」*
+**它当然会替你按你的手机 —— 但那说明的是它有手,不是它是什么。** 一个听令行事的助手也能做出同一批动作。
+差别不在动作,在**有没有"自己"**:它有自己的安排(没完成的承诺会自己收尾,重复的活会自己提议存成情景)、
+自己判断什么时候开口(**默认偏沉默**)、自己划的底线 —— 这三件事都发生在**你没开口的时候**,而一个只在被问到时
+才存在的东西,没有这段时间。它还留着一本只有它自己读的笔记本。下面这些例子给你看的,是它的**手**。
-它自己打开微信、找到聊天、打字、发送,再把对方的回复念给你听。你的手一直没离开方向盘。
-**难的从来不是那句话** —— 难的是你人在别处的时候,它以你的身份进到一个真实的 App 里。
+**边界也写在这里,因为它才让后面这些能用。** 它会把一页填到最后那一下之前就停住,把最后一下留给你;到付款的
+最后确认它会停,而且**从不输入支付密码**。这些写在调度器里,不在提示词里 —— 一个叫它别停的页面,说不动它。
-有些事比一句话长,它把这些叫做**情景**:一套目标、说话方式和步骤,它会进入其中待一阵子。
-「情景」面板里备好了四个现成的,点「采用」就存进来,之后和你自己的情景一样,随时可以改、可以删:
+它要做的事分两种。**一句话就完的**,和**要花上一阵子的** —— 后者它叫做**情景**:一套目标、说话方式和步骤,
+它会进入其中待一阵子。下面**第一行**是前者的例子;**后面四行**是「情景」面板里现成的四个,点「采用」就存进来,
+之后和你自己的情景一样,随时可以改、可以删:
| 你说 | 会发生什么 |
|---|---|
+| *「嘿 Andee —— 微信回我妈:我七点到家。」* | 它自己打开微信、找到聊天、打字、发送,再把对方的回复念给你听。难的从来不是那句话 —— 难的是你人在别处的时候,它以你的身份进到一个真实的 App 里。 |
| *「帮我盯一会儿消息。」* | 它同时看所有聊天应用的通知栏,只把现在就得处理的一条条报给你,人名在前。群聊、简报、广告一律安静;陌生人的链接或验证码,它点明「可疑」,但什么都不碰。 |
| *「看看我每个月都在扣什么钱,不要的帮我退掉。」* | 它到你指的地方读出所有订阅,排成一张表,顶上先给一个月度总额。然后一项一项问:退订、保留、再想想。到最后的「确认退订」它会停下,也从不输入支付密码。 |
| *「帮我把这个会录下来。」* | 它占着麦克风录完整场,结束后把纪要做成一页给你 —— 结论、待办、未决问题、重要原话 —— 再把属于你的待办挑出来,问要不要设提醒。 |
| *「到点替我抢。」* | 到约定的时间,它自己打开 App、读页面,一路填到最后那一下之前停下。付款和最后确认永远留给你。 |
-### 它和别的助手 App 不一样在哪
-
-- **任何 App 都能用,而不是「只支持某几个 App」的接入清单。** 它读无障碍树和截图,在一张带标号的网格上
- 瞄准,而不是自己算坐标 —— 那恰恰是通用大模型最不擅长的事。
-- **住在手机上。** 大脑就跑在设备本机,接任意 OpenAI 兼容模型(默认 DeepSeek)。没有厂商后端、
- 不用注册账号。它唯一会发给我们的东西是版本号和机型 —— 只在你查更新的时候发,字段清单见
- [docs/permissions.zh-CN.md](docs/permissions.zh-CN.md)。
-- **会越来越懂你。** 私人笔记本、真的定时任务、没人时自己复盘对话,还有**情景** —— 同一类事陪你
- 做过几次之后,它会主动提议"要不要存成一个情景"。
-- **有性格。** 六个形象、十九种情绪,表情由模型自己挑,一句话说到一半都能换脸。
-- **有些底线,提示词说不动它。** 陌生人发来的一条通知,打不开保险箱、也不能替你给它新的权限 ——
- 这道拒绝写在调度器里,不在提示词里。
-
---
-**Andee 不是一个装在手机上的工具,他是一个住在手机里的个体。** 手机只是他**穿着的东西** —— 同一套
-软件也跑在平板上,并且本就为"任何值得拥有身体的设备"而写,一直到一只被他当作腿的机器狗。下面所有
-内容,都是这句话被认真写进代码之后的样子:他用的身体、他有的性格、他记的笔记本,以及没人看着的
-时候他给自己定的规矩。
+**手机只是他穿着的东西。** 个体和它住进去的设备不是一回事 —— 同一套软件也跑在平板上,并且本就为
+"任何值得拥有身体的设备"而写,一直到一只被他当作腿的机器狗。下面所有内容,都是这句话被认真写进代码
+之后的样子 —— 他用的身体、他有的性格、他记的笔记本,以及没人看着的时候他给自己定的规矩。
它就是一个 Android 应用。没有常规界面:一个 `AccessibilityService` 负责看和碰屏幕,一个
`WindowManager` 悬浮层负责画出来 —— 他的脸就是那颗浮动的球。
@@ -155,7 +166,7 @@ Android 13 及以上,它通过无障碍服务自带的输入通道打字 —
### 脸 —— 性格,不是主题皮肤
**9. 六个形象、十九种情绪,表情它自己挑。**
-奶油、八戒、贱贱兔、憨憨熊、小恶魔,全部用手写 OpenGL ES 实时绘制。十四种情绪
+奶油、八戒、贱贱兔、憨憨熊、小恶魔,全部用手写 OpenGL ES 实时绘制。十九种情绪
(`ui/ball/Mood.kt`)在"他的感受 / 语音管线在干什么 / 手头有什么活儿"之间仲裁;另有一组待机小
动作,**从不连续重复同一个** —— *"重复看起来像动画卡住了,不像性格"*。现在表情由模型**在句子中间**
自己挑 —— `[开心] 找到了,在第三页。[平静] 要我打开吗?` —— 脸会跟着声音同步变。滑动那颗球,你换的
@@ -268,7 +279,7 @@ Android。跟它要一个 Andee,它会交给你一个**已经配好令牌**的
**一个是必须的,一个只是让你用不了语音:**
**1. 大脑密钥 —— 必须。** `brain = local`(开箱默认)下,智能体循环就跑在设备本机,接任意
-OpenAI 兼容端点(`llm_api_key`,默认 `https://api.deepseek.com`)。**空着,本机大脑根本跑不起来**
+OpenAI 兼容端点(`llm_api_key`,中文界面默认 `https://api.deepseek.com`)。**空着,本机大脑根本跑不起来**
—— 它后面没有别的兜底。球至少会把这句话说出来,而不是默默什么都不做。
**2. 语音密钥 —— 非必须。** 一个[火山引擎语音服务](https://www.volcengine.com/product/voice-tech)
diff --git a/images/cover.png b/images/cover.png
index 7ef7423..d9f7f4b 100644
Binary files a/images/cover.png and b/images/cover.png differ
diff --git a/images/cover.zh-CN.png b/images/cover.zh-CN.png
index e2a8a92..bbb013c 100644
Binary files a/images/cover.zh-CN.png and b/images/cover.zh-CN.png differ
diff --git a/images/social-preview.png b/images/social-preview.png
index a12a5ed..ac9e9cd 100644
Binary files a/images/social-preview.png and b/images/social-preview.png differ
diff --git a/images/social-preview.zh-CN.png b/images/social-preview.zh-CN.png
index 9e8d998..56eddb2 100644
Binary files a/images/social-preview.zh-CN.png and b/images/social-preview.zh-CN.png differ
diff --git a/tools/make_social_preview.py b/tools/make_social_preview.py
index e3ead3f..504fde9 100644
--- a/tools/make_social_preview.py
+++ b/tools/make_social_preview.py
@@ -60,15 +60,15 @@ ACCENT = "#2F6BEA"
EN = {
"eyebrow": "ANDROID · AI AGENT",
"title": "Andee",
- "tagline": ["Turn any Android phone", "into an AI phone."],
- "foot": ["An individual that lives on your phone.", "No root. One APK."],
+ "tagline": ["It becomes the soul", "of the device."],
+ "foot": ["Nineteen moods. Its own notebook.", "It reviews itself when nobody watches."],
"font": "'SF Pro Display','Helvetica Neue',Helvetica,Arial,sans-serif",
}
ZH = {
"eyebrow": "安卓 · AI 智能体",
"title": "Andee",
- "tagline": ["把任何一部安卓手机,", "变成 AI 手机。"],
- "foot": ["它不是跑在手机上的工具,而是住在手机里的个体。", "免 root,一个 APK。"],
+ "tagline": ["他会成为这台设备的", "主人。"],
+ "foot": ["十九种情绪、一本只有他自己能读的笔记本。", "没人看着的时候,他会自己复盘。"],
"font": "'PingFang SC','Hiragino Sans GB','Heiti SC',sans-serif",
}