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: add a getting-started guide

Matt Van Hornf771b5e09517
diff --git a/README.md b/README.md
index 88f76c6..97fc545 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
<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="docs/getting-started.md">Getting started</a> ·
<a href="#key-features">Features</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="#provisioning">Provisioning</a> ·
@@ -1156,6 +1157,7 @@ See [CHANGELOG.md](CHANGELOG.md) for what changed and for the versioning policy.
## Related documents
+- [docs/getting-started.md](docs/getting-started.md) ([Chinese](docs/getting-started.zh-CN.md)) — the short first-run path from installation to a basic interaction
- [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) ([Chinese](docs/architecture.zh-CN.svg)) — the whole
diff --git a/README.zh-CN.md b/README.zh-CN.md
index c024337..de35ab2 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -10,6 +10,7 @@
<p align="center">
<a href="https://www.codeflying.net/andee">在线构建</a> ·
<a href="https://www.codeflying.net/andee">立即体验</a> ·
+ <a href="docs/getting-started.zh-CN.md">入门指南</a> ·
<a href="#核心能力">核心能力</a> ·
<a href="#快速开始">快速开始</a> ·
<a href="#权限每一项为什么以及你拒绝了会怎样">权限</a> ·
@@ -997,6 +998,7 @@ pre-1.0:线上协议和构建开关都还在动。
## 相关文档
+- [docs/getting-started.zh-CN.md](docs/getting-started.zh-CN.md)([English](docs/getting-started.md))—— 从安装到第一次基本互动的最短路径
- [docs/permissions.zh-CN.md](docs/permissions.zh-CN.md)([English](docs/permissions.md))—— 权限为什么这么要
- [docs/architecture.zh-CN.svg](docs/architecture.zh-CN.svg)([English](docs/architecture.svg))—— 一页看全:一轮怎么进来、agent loop、六个出口
- [DISCLAIMER.zh-CN.md](DISCLAIMER.zh-CN.md) —— 免责声明:数据去哪、能做什么、出事谁担
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..9f957fa
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,40 @@
+# Getting started
+
+[简体中文](getting-started.zh-CN.md)
+
+This is the shortest path from a first look at Andee to seeing the ball and completing a basic interaction. Andee is experimental software that can read and operate your device; read the [disclaimer](../DISCLAIMER.md) before installing it.
+
+## 1. Choose how to install
+
+Pick the route that matches what you want to do:
+
+- **Try it without building:** use the [CodeFlying build page](https://www.codeflying.app/andee) for a pre-configured APK. This is a separate service, and its own terms and token limits apply.
+- **Try a repository build:** download the bare debug APK from the [latest release](https://github.com/kuafuai/andee/releases/latest). It has no credentials, so you must configure the on-device model and voice keys later.
+- **Build it yourself:** follow the Android requirements and commands in [Quick start](../README.md#quick-start), then use the detailed [Provisioning](../README.md#provisioning) reference if the toolchain is not ready.
+
+For a first run, use a real Android 11 (API 30) or newer device. An emulator can install the app, but most device-control features are not meaningful there.
+
+## 2. Install and make the ball appear
+
+After the APK is on the device, do these four things in order:
+
+1. **Install the APK.** If installation fails, check that the APK matches the device ABI and that an older copy was not signed with a different key. A debug build from another machine may need the old copy uninstalled.
+2. **Grant “Display over other apps” (Overlay).** The ball should appear when you return to Andee. If it does not, reopen the app and use Self-check; do not continue by guessing at later permissions.
+3. **Enable Andee under Accessibility.** This lets Andee see and touch the screen. If the service is off, the ball may be visible but it cannot operate another app. Android or a device manufacturer may turn this service off again after a force-stop or system update.
+4. **Tap the ball and allow the microphone.** If you refused it earlier, enable Microphone under Android Settings → Apps → Andee → Permissions. Without it, typing remains possible but voice input and wake-word use do not.
+
+The same order is summarized in the README’s [Provisioning order](../README.md#provisioning-order). The [Permissions reference](permissions.md) explains what each permission enables and what Andee does when you refuse it.
+
+## 3. Configure a brain and try one interaction
+
+Open ⚙ on the ball and choose **Backend → On-device**. Enter an OpenAI-compatible endpoint and `llm_api_key`; the local brain cannot run without the brain key. If you installed a CodeFlying package, its **CodeFlying** backend is already configured instead. A voice key is optional for a first typed interaction, but voice input and spoken replies need the selected voice provider configured too.
+
+Now tap the ball, type a simple request such as “What can you see on this screen?”, and send it. The ball should expand into the conversation card, answer, and return to the floating ball when it is done. This confirms the basic loop: the app is running, the brain is reachable, and the overlay is visible. Do not use a payment, messaging, or other consequential task as the first test.
+
+## 4. If something fails, use Self-check
+
+Self-check is the in-app checklist, not a second setup wizard. Open **✓** in the ball’s control bar, or launch Andee again when the accessibility service is off. Each failed row names the missing readiness item and, where possible, opens the relevant settings page. Fix one row, return to Self-check, and check again.
+
+The README describes where the [Self-check surface appears](../README.md#what-it-looks-like), and the full [Permissions reference](permissions.md) explains the rationale behind its permission rows. For build and device setup failures, return to [Provisioning](../README.md#provisioning); for a successful install that still cannot reach the configured brain, check the endpoint and key under **Backend → On-device** before changing permissions.
+
+When the ball is visible and the typed request has received an answer, the first-run path is complete. The README remains the reference for advanced provisioning, cloud/hub mode, wake word setup, and known limitations.
diff --git a/docs/getting-started.zh-CN.md b/docs/getting-started.zh-CN.md
new file mode 100644
index 0000000..1e9b9a9
--- /dev/null
+++ b/docs/getting-started.zh-CN.md
@@ -0,0 +1,40 @@
+# 入门指南
+
+[English](getting-started.md)
+
+这是从第一次看到 Andee,到看到悬浮球并完成一次基本互动的最短路径。Andee 是实验性软件,可以读取并操作你的设备;安装前请先读[免责声明](../DISCLAIMER.zh-CN.md)。
+
+## 1. 选择安装方式
+
+按你的目标选择一条路:
+
+- **不自己构建,先试用:** 使用 [CodeFlying 构建页](https://www.codeflying.net/andee) 获取已经配置好的 APK。这是独立服务,条款和 token 额度以它自己的规则为准。
+- **试用仓库构建包:** 从[最新 Release](https://github.com/kuafuai/andee/releases/latest)下载裸 debug APK。里面没有密钥,之后必须自己配置本机模型和语音密钥。
+- **自己构建:** 先按 [README 的快速开始](../README.zh-CN.md#快速开始)准备环境和执行命令;工具链没有配好时,再看详细的[装机配置](../README.zh-CN.md#构建配置)。
+
+第一次运行请使用 Android 11(API 30)或更新版本的真机。模拟器可以安装,但大多数设备操作功能在那里没有实际意义。
+
+## 2. 安装并让悬浮球出现
+
+APK 装到设备后,按下面四步进行:
+
+1. **安装 APK。** 如果安装失败,先确认 APK 的 ABI 与设备匹配,也确认旧版本是不是由另一把密钥签名的。另一台机器构建的 debug 包可能需要先卸载旧包。
+2. **打开“显示在其他应用上层”(悬浮窗)。** 回到 Andee 后应该能看到悬浮球。如果没有出现,重新打开 Andee 并使用自检,不要跳过这一步去猜后面的权限。
+3. **在系统“无障碍”里打开 Andee。** 这让 Andee 能看见并触碰屏幕。服务没开时,球可能出现,但不能操作其它 App。强制停止应用或系统更新后,部分厂商的系统会再次关闭它。
+4. **点击悬浮球并允许麦克风。** 如果之前拒绝过,到系统设置 → 应用 → Andee → 权限 → 麦克风里手动打开。没有麦克风仍然可以打字,但不能语音输入或使用唤醒词。
+
+同一顺序也列在 README 的[装机顺序建议](../README.zh-CN.md#装机顺序建议)里。[权限说明](permissions.zh-CN.md)解释每项权限能做什么,以及拒绝后 Andee 会怎样降级。
+
+## 3. 配置大脑并完成一次互动
+
+点击悬浮球上的 ⚙,进入**后端 → 本机**。填入一个 OpenAI 兼容端点和 `llm_api_key`;没有大脑密钥,本机大脑无法运行。如果安装的是 CodeFlying 包,**CodeFlying** 后端已经配置好。第一次用文字互动时,语音密钥不是必需的;但语音输入和朗读回复需要配置所选语音服务商。
+
+现在点击悬浮球,输入一句简单的话,例如“你能看到这个屏幕上的什么?”,然后发送。悬浮球应该展开成对话卡片,返回答案,完成后再缩回悬浮球。这说明基本链路已经通了:应用在运行、大脑可连接、悬浮窗可见。第一次测试不要使用付款、发消息或其它有实际后果的任务。
+
+## 4. 出问题时使用自检
+
+自检是应用内的实时清单,不是另一套安装向导。在悬浮球控制条点击 **✓**;如果无障碍服务关闭,也可以重新启动 Andee 进入自检。每一行会点名缺少的准备项,并尽量直接打开对应的系统设置。修好一项后回到自检,再次检查。
+
+README 说明了[自检入口在哪里](../README.zh-CN.md#它长什么样),[权限说明](permissions.zh-CN.md)解释每一行权限的原因。构建或设备环境出错时,回到 README 的[构建配置](../README.zh-CN.md#构建配置);如果安装成功但仍然连不上大脑,先在**后端 → 本机**检查端点和密钥,不要先改其它权限。
+
+看到悬浮球,并且文字请求已经得到回答,第一次运行就完成了。更高级的装机、云端 / hub 模式、唤醒词和已知限制,继续以 README 为准。