# 入门指南

[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** 后端已经配置好。第一次用文字互动时，语音密钥不是必需的；但语音输入和朗读回复需要配置所选语音服务商。

火山语音服务这边，光有 key 不够。控制台里显示「已开通」的服务默认是**后付费**，而它只能在官网的体验页里用：程序走 API 会被拒绝，key 填对了也一样。要到控制台的**开通管理**页把该服务改成预付 / 预购，并在那里买一个流式语音识别的资源包。在这之前，语音会在这一轮的最开头就失败 —— 握手被直接拒绝，音频还没发出去；或者反过来，连接起来了，但第一次请求之后收到一个带授权错误码的错误帧。两种都不是网络问题。如果买的是并发版的包而不是时长版，还要把**识别资源 ID** 改成 `volc.bigasr.sauc.concurrent`；它默认是 `volc.bigasr.sauc.duration`，两者都会作为 `X-Api-Resource-Id` 头发送。这两个值属于 1.0 模型，而请求里也写死了模型（`model_name` 是 `bigmodel`），所以 **2.0** 的包（豆包流式语音识别 2.0，`volc.seedasr.*`）在这里用不了 —— 要另外把 1.0 的服务也开通。

现在点击悬浮球，输入一句简单的话，例如“你能看到这个屏幕上的什么？”，然后发送。悬浮球应该展开成对话卡片，返回答案，完成后再缩回悬浮球。这说明基本链路已经通了：应用在运行、大脑可连接、悬浮窗可见。第一次测试不要使用付款、发消息或其它有实际后果的任务。

## 4. 出问题时使用自检

自检是应用内的实时清单，不是另一套安装向导。在悬浮球控制条点击 **✓**；如果无障碍服务关闭，也可以重新启动 Andee 进入自检。每一行会点名缺少的准备项，并尽量直接打开对应的系统设置。修好一项后回到自检，再次检查。

README 说明了[自检入口在哪里](../README.zh-CN.md#它长什么样)，[权限说明](permissions.zh-CN.md)解释每一行权限的原因。构建或设备环境出错时，回到 README 的[构建配置](../README.zh-CN.md#构建配置)；如果安装成功但仍然连不上大脑，先在**后端 → 本机**检查端点和密钥，不要先改其它权限。

看到悬浮球，并且文字请求已经得到回答，第一次运行就完成了。更高级的装机、云端 / hub 模式、唤醒词和已知限制，继续以 README 为准。