<!-- docs-updated: 2026-11-12 -->

> 本指南介绍 Floe Android（Floe Agent 的安卓版本）的实际功能与操作步骤，重点是低版本安卓的本机 ADB 激活。本页按 1.0.0（versionCode 108）整理；截至 2026-11-12，该版本在 GitHub 标记为预发布，渠道状态以版本中心为准，仅通过 Full APK 独立分发；Google Play 线已于 2026-11-10 停止。最低要求 Android 9（API 28）、ARM64 设备。任务使用你自己配置的云端模型，不提供本地模型推理。

<!-- doc-anchor: section-1 -->
# Floe Android 使用指南

[English](ANDROID_GUIDE.md) · [文档目录](README.md) · [官网版本中心](https://www.floe-agent.com/releases?platform=android) · [GitHub Releases](https://github.com/JiangNanGenius/floe-agent/releases)

Floe Android 把手机变成一个轻量 Agent 工作台：云端模型任务、项目文件、设备控制、项目级 ARM64 Linux 终端与图形应用、网络工具和定时任务。本指南按实际发布的界面与文案编写；不同版本的菜单词句可能略有差异，以你安装版本的界面为准。

## 目录

**入门**

- [1. 安装与更新](#1-安装与更新)
- [2. 第一个云端模型与任务](#2-第一个云端模型与任务)
- [3. 本机 ADB：内嵌 ADB 访问](#3-本机-adb内嵌-adb-访问)
- [4. Root 访问（可选）](#4-root-访问可选)
- [5. 设备控制（无障碍）](#5-设备控制无障碍)

**工作区与工具**

- [6. 项目 Linux：终端与图形会话](#6-项目-linux终端与图形会话)
- [7. 文件与外部编辑器](#7-文件与外部编辑器)
- [8. 网络工具（更多 → 网络）](#8-网络工具更多--网络)
- [9. 定时与条件任务](#9-定时与条件任务)
- [10. 语音、记忆与技能](#10-语音记忆与技能)
- [11. 版本、诊断与反馈](#11-版本诊断与反馈)
- [12. 当前限制](#12-当前限制)

## 1. 安装与更新

### 1.1 安装

1. 在[官网版本中心](https://www.floe-agent.com/releases?platform=android)或 [GitHub Releases](https://github.com/JiangNanGenius/floe-agent/releases) 下载最新 Android Full APK（应用 ID `com.floe.agent.full`）。
2. 打开 APK 安装。覆盖安装会保留已有任务、项目和文件，无需卸载旧版。
3. 首次使用时，Floe 会提示安装 **Linux 运行组件**（与主应用同一次发布的配套组件包）。按系统安装器的提示确认即可；组件与主应用版本一一对应，请始终使用同一次发布的两个包。

### 1.2 应用内更新

打开 **设置 → 诊断与关于 → 应用更新**：

- **自动检查更新**开关控制是否自动发现新版本；也可随时点**检查更新**。
- **下载源**可选 GitHub 官方或 GHFast、GH-Proxy 等第三方镜像；使用镜像时安装包校验保持开启，校验失败会丢弃下载。
- 已安装版本正好是该增量补丁对应的基准版本时，优先使用更小的**增量补丁**；增量不可用或校验失败时自动回退完整包，也可以随时**下载完整更新**。
- 安装需要你在系统对话框中确认；Linux 运行组件同时更新时，Android 可能分别要求两次确认，逐次确认即可。安装会关闭应用，请先保存工作。

### 1.3 旧客户端升级

很久未更新的旧版本客户端如果应用内更新失败，直接从发布页下载最新完整 APK 覆盖安装一次即可，无需卸载，数据保留。

## 2. 第一个云端模型与任务

服务商配置、任务描述、成果检查与反馈方式见[模型、任务与文件（共通）](SHARED_GUIDE.zh-CN.md)。以下说明 Android 的实际菜单与操作。

Floe Android 不提供本地模型推理，任务使用你自己配置的云端模型服务。

### 2.1 配置模型提供商

1. 打开 **设置 → 模型与供应商**。
2. 点**添加提供商**，先选择用途（聊天模型 / 图像生成与编辑 / 视频生成）。
3. 填写供应商、协议、Base URL 和 API key。API key 只保存在本机安全存储中；如使用本地或私有地址的明文 HTTP，需单独开启对应选项。
4. 点**测试连接**确认可用，然后在**管理模型**中添加或刷新模型列表。
5. **模型路由**（同一设置页入口）可分别指定主模型、辅助模型、视觉模型等角色；不单独设置时按默认继承。

### 2.2 运行第一个任务

1. 在首页（新建任务）输入你的指令，例如“总结工作区里这份 PDF 的第三章”。
2. 在输入框的**模型**入口选择已配置的模型。
3. 发送后，Floe 会按计划执行任务；涉及工具调用时按任务授权，你可以查看每一步的产出。

## 3. 本机 ADB：内嵌 ADB 访问

**内嵌 ADB 访问**是 Floe 自带的本机 shell 权限服务：它让 Floe 在**你这台手机本机**获得 shell 级文件和系统操作能力。它不是 Root，不是 Shizuku 应用，也不是让电脑远程管理手机；服务由 Floe App 自己持有和调用。

请先分清三种互不相同的权限，按需只开启你需要的：

| 能力 | 入口 | 作用 |
| --- | --- | --- |
| 设备操作（无障碍） | 设置 → 设备 → 设备操作（无障碍） | 观察并操作你选定的应用界面（见第 5 节） |
| 内嵌 ADB 访问 | 设置 → 设备 → 内嵌 ADB 访问 | shell 级文件、系统文件夹（只读）、应用管理等（本节） |
| Root 访问 | 设置 → 设备 → Root 访问 | 设备已有 Root 授权时的最高权限操作（见第 4 节） |

仅仅在电脑上“连上 adb”不会给 Floe 任何能力；必须按下面的方式完成配对或初始化，让 Floe 自己的服务运行起来。

开启内嵌 ADB 后可以按需设置：

- **系统访问的共享文件夹**：下载、文档、图片、相机（DCIM）、音乐、影片；可单独允许或禁止修改。“允许修改所选文件夹”关闭时这些目录只读。
- **系统文件夹（只读）**：系统、厂商、产品、系统扩展、ODM、APEX；只查看，Floe 不会重新挂载或改动系统。
- **应用管理**：允许已授权任务通过系统服务强制停止应用；Floe 自身始终被拒绝。
- **其他应用数据（仅 Root）**：以绝对路径添加其他应用的数据文件夹，仅在 Root 运行时可用。

### 3.1 Android 11 及以上：无线配对

Android 11+ 使用系统的“无线调试”配对，全程在手机上完成，不需要电脑：

1. 打开 **设置 → 设备 → 内嵌 ADB 访问**，开启**内嵌 ADB**，点**与 Android 配对**。Floe 会打开系统的开发者选项。
2. 在系统设置中开启**无线调试**，进入后点**使用配对码配对设备**，屏幕显示 6 位配对码和**配对端口**。配对端口只在配对这一步使用，和下一步连接用的端口不是同一个。
3. 在 Floe 的**配对通知**中输入 6 位配对码（让 Android 的配对界面保持在前台）。如果通知被关闭，按提示允许配对通知；也可以使用分屏，在 Floe 页面内直接输入。Floe 会自动查找本机配对端口；找不到时按屏幕提示手动输入。
4. 配对成功后返回 Floe，点**启动服务**。Floe 通过本机回环地址（127.0.0.1）和**当前实际的连接端口**连接这台手机自己的调试服务——连接端口就是无线调试主页面显示的“IP 地址和端口”里的端口号，和配对端口不同。状态显示**服务运行中**并显示 Shell 身份（UID 2000）即表示成功。

注意：

- **没有固定端口**：重新开关无线调试、切换 Wi-Fi 后，连接端口可能变化，Floe 总是使用当前实际端口重新连接；自动发现不可用时，按界面提示以无线调试页面当前显示的端口为准。
- **重启手机后**：配对信任仍然保留，但需要重新开启无线调试并再次**启动服务**。
- 如果 Floe 提示需要本地网络访问权限，请允许，否则无法发现本机配对端口。

### 3.2 Android 9/10：电脑 USB 初始化

Android 9/10 没有系统无线配对，需要借助电脑做一次 USB 初始化。这里的目的是**让 Floe 连接这台手机自己的内嵌服务**，不是把电脑变成这台手机的管理器：

1. 在电脑上安装 [Android platform-tools](https://developer.android.com/tools/releases/platform-tools)（官方说明见 [Android 调试桥文档](https://developer.android.com/tools/adb)）。
2. 手机开启**开发者选项**和 **USB 调试**，用 USB 连接电脑，并在手机上允许这台电脑的调试授权。
3. 手机上打开 **设置 → 设备 → 内嵌 ADB 访问**，先开启**内嵌 ADB**，再点**复制 USB 初始化命令**。命令已复制到剪贴板。
4. 在电脑上先确认手机已就绪。在终端执行：

   ```bash
   adb devices
   ```

   正常情况下列表里只有这台手机且状态为 `device`。如果显示 `unauthorized`，请在手机上允许这台电脑的调试授权后重试；如果显示 `offline`，重新插拔 USB 或重新开启 USB 调试；如果列出了多台设备，请先断开其他设备，或在第 5 步把命令开头的 `adb` 换成 `adb -s <序列号>`（序列号就是上一步列表中该设备的第一列）。
5. 在电脑的 POSIX shell（macOS/Linux 终端；Windows 请使用 Git Bash 等 POSIX 环境，并确认 `adb` 在该 shell 的 PATH 中）粘贴剪贴板中的命令并执行一次。
6. 命令会通过手机上的 adb 会话启动 Floe 自带的系统服务（shell 身份）。回到手机，Floe 状态显示**服务运行中**（Shell 身份 UID 2000）即成功。

关于这条命令，需要知道：

- 它是**为当前安装版本和一次性握手动态生成的**，绑定你手机上的这个 Floe 安装；不要把它当作固定脚本保存复用。手机重启或服务停止后，重新点**复制 USB 初始化命令**获取与当前状态匹配的命令，再用电脑执行一次。
- 它**不会在手机上开启 5555 等 TCP 调试端口**。网上一些旧教程用 `adb tcpip 5555` 长期开启 TCP 调试——那不是 Floe 的流程，Floe 也不需要。这种常开方式只应在可信网络下按需使用；如果你曾按这类教程开启过，可在电脑上用 `adb usb` 切回 USB 模式，或关闭 USB 调试 / 重启手机来结束。

### 3.3 验证、撤销与排查

- **验证**：设置 → 设备 → 内嵌 ADB 访问，状态显示**服务运行中**即正常。
- **暂停使用**：点**停止服务**；**忘记配对**会删除已保存的配对并先停止服务（不影响其他应用）；关闭**内嵌 ADB**开关即整体停用。
- **重启后**：Android 11+ 重新开启无线调试并启动服务；Android 9/10 重新用电脑执行一次初始化命令。
- **常见提示**：找不到无线调试时，确认开发者选项中的无线调试已开启再启动服务；配对码不被接受时，核对 Android 配对界面显示的当前配对码重试；配对在系统设置中被移除后，重新配对即可恢复。

## 4. Root 访问（可选）

Root 访问**默认关闭**，只使用这台设备**已经存在**的 Root 授权；Floe 不会为手机获取 Root，也不会把 ADB 提升为 Root。

1. 打开 **设置 → 设备 → Root 访问**。
2. 点**检查 Root 授权**，按提示确认使用设备已有的 Root 授权；成功后即可启用 Root 访问。找不到授权时会明确提示“无 Root 授权”。
3. 开启后，只以 Root 执行你主动启动的操作；随时可以再次关闭。

内嵌 ADB 与 Root 同时只有一个作为活动后端：Root 成为活动后端时，已运行的 ADB 服务转为待命状态，反之亦然。

<!-- doc-anchor: 5-手机控制无障碍 -->
## 5. 设备控制（无障碍）

设备控制让任务在你**选定的应用**内观察界面并执行操作，基于 Android 无障碍服务。

### 5.1 开启与选择应用

1. 打开 **设置 → 设备 → 设备操作（无障碍）**，点**打开无障碍设置**，启用 Floe 的设备控制服务。如果系统阻止该服务，按提示在应用信息中允许“受限设置”后重新启用。
2. 在**Agent 可控制的应用**中**选择应用**：只有你选择的应用可以被查看或操作，不存在“全部应用”授权；前台切换到未选择的应用会被拒绝。
3. **屏幕内容**选择当前任务何时可以查看屏幕：**关闭 / 仅此任务 / 直到停止**。不会持续录制；仅在任务请求时截取正在观察的页面。

### 5.2 任务中使用与接管

- 每个任务需要明确**允许此任务使用设备控制**，Agent 不能自行开启。
- 任务运行中会显示状态（运行中 / 等待你 / 已接管 / 正在停止）；你随时可**接管**或**停止**。接管会阻止新动作，任务保留供你查看。
- 你正在使用手机时，执行会先暂停并等你确认。
- 边界：仅观察当前任务正在显示的页面；动作执行后会重新读取，不会盲目重放；安全窗口和锁屏界面仍受系统保护。

### 5.3 为任务自动解锁（已知密码）

如果你愿意，任务可以在本机输入你保存的设备 PIN 或密码来解锁：

- 在设置中开启**为任务自动解锁**，同意并保存到本机。凭据不会发送给模型，也不会进入诊断报告。
- 解锁失败会停下来等你处理，不会循环尝试；只有在任务解锁且你没有接管时，手机才会在任务结束后自动重新锁屏。
- **图案锁和部分系统界面需要手动处理**；不同机型和锁屏方式的自动解锁表现可能不同，观察、操作到结束后重新锁屏的完整链路仍在实测完善中，失败时按提示手动接管即可。

## 6. 项目 Linux：终端与图形会话

### 6.1 安装本地环境

1. 打开 **设置 → 执行环境 → 本地环境**，按提示下载并安装 Linux 环境。首次使用需先安装第 1.1 节的 Linux 运行组件。
2. 安装完成后显示**环境已安装**；终端任务即可用。如果显示不可用，按提示打开一次任务终端或点**重新检查**（只重新测量，不会重装或重新下载）。

### 6.2 任务终端

- 在任务的检查器（终端页签）中新建标签页，即可在该任务的 Linux 环境中执行命令；支持多个标签页。
- 模型的命令行操作优先在终端完成；终端会话结束时，文件变更会同步到工作区文件。

### 6.3 图形会话（Linux 应用）

1. 在任务的**工作区文件**页，点标题栏的**更多 → Linux 应用**。
2. 首次使用按提示安装一次基础图形组件；之后选择**单应用**或**桌面**模式，点**启动会话**。
3. 可**打开所选文件**、**选择应用**或安装新软件；**返回应用**在会话与 Floe 之间切换。
4. 关闭窗口不会结束会话；**停止会话**会关闭 Linux 应用并回传已保存的文件——请先在其中保存修改。

## 7. 文件与外部编辑器

### 7.1 工作区文件

任务的工作区文件页提供：新建文件/文件夹、文件操作（移动等）、源码（Git）、**网络存储**（WebDAV/SMB 服务器连接、复制与回传）、恢复副本和实时预览。Office 文档可直接在 Floe 内离线预览和编辑；CAD/三维文件提供预览查看。

Office 与 CAD 预览使用**可选预览组件**：首次打开这类文件时按提示安装，或到 **设置 → 数据管理 → 可选预览组件** 中安装。组件从发布渠道下载并校验后，经系统安装器确认；它与你的文件分开保存，卸载组件不影响文档。应用更新后 CAD 预览组件可能需要重新下载一次。

### 7.2 使用其他应用编辑

轻量文本、Markdown 和代码默认直接在 Floe 内编辑；专业编辑可交给安卓上的其他应用：

1. 在**工作区文件**页点**更多 → 使用其他应用编辑**，选择要编辑的项目文件。
2. 选择编辑器：有默认应用时直接打开，否则显示系统选择器；也可**选择其他应用**手动指定。
3. 在对方应用中保存后，修改会**自动回传到项目**；返回 Floe 可查看原始版本对比。
4. 如果原文件同时也被改动，两个版本都会保留，供你选择**保留当前文件**或**使用编辑副本**；处理完点**结束编辑**释放占用。

没有合适的安卓应用时，可改用第 6.3 节的 Linux 图形应用编辑。

## 8. 网络工具（更多 → 网络）

网络工作台在侧边栏 **更多 → 网络**（或 **设置 → 系统能力 → 网络诊断**）。所有测量都只在你点**开始**后执行，结果保存在本机；首次使用按提示允许网络/本地网络权限后重新**开始**。

- **Wi-Fi / 概览**：查看当前连接、信号、信道与 AP 分布。
- **DNS 查询 / Ping / 路由追踪 / TCP 连接 / HTTPS 请求**：对指定主机或地址做单项检测。
- **局域网发现**：查找广播服务的设备，或扫描你明确指定的私有 IPv4 子网（RFC1918 /24–/30）。mDNS 服务发现需要 Android 13 及以上；Android 9–12L 仍可使用子网扫描。不做任何自动扫描。
- **网速测试**：对你自己控制的 HTTPS 地址测下载、上传或双向；每方向有固定的数据量（1–32 MiB）和时间（1–15 秒）预算，不跟随跳转；使用计费网络时需你明确允许。
- **持续监测**：按 1–60 分钟时长、5–300 秒间隔监测连接状态、Ping 或 TCP；前台通知可随时**停止**；最多保留 720 条检测；Floe 进入后台后监测继续，但不会自行重启。
- **抓包与覆盖**：无需 Root 的 VPN 抓包在本机运行（不解密 TLS 加密内容）；开启内嵌 ADB 或 Root 后，还可使用 Full 版特有的原生抓包。

## 9. 定时与条件任务

在**任务中心**（或首页的定时任务卡片）进入**定时任务**：

- **新建定时任务**：填写标题和任务指令，选择重复方式：**一次 / 每天 / 每周 / 间隔 / 成功后**（在某个任务成功后运行）/ **开始充电时** / **连接网络时**。
- 选择工作区（每次运行新建独立工作区，或复用项目工作区）、模型、环境和审批方式（每次询问 / 自动 / 完全访问）。
- **精确时间**：需要准时运行的任务使用精确闹钟；未允许精确闹钟时可改用**灵活计划**（允许稍后运行）。
- **后台运行**：定时任务需要允许通知才能在后台保持受保护；电池优化设置决定 Android 是否允许任务在后台自行启动（设置中提供**应用电池设置**和**电池优化列表**入口）。被系统阻止时，打开 Floe 重试即可。
- **运行历史**查看每次运行的状态；可从历史或通知打开对应任务。

## 10. 语音、记忆与技能

- **语音**（设置 → 通用）：语音输入、朗读、媒体转写；输入和朗读可选**系统**或**云端**引擎，媒体转写使用已配置的云端提供商模型。
- **记忆与个性化**：管理 Floe 记住的内容、整理建议与个性化修订历史。
- **技能与连接器**：管理技能和连接器；**网页搜索**配置搜索提供商。
- **用量**：按天、模型、提供商查看 Token 用量。

## 11. 版本、诊断与反馈

- **查看版本**：设置 → 诊断与关于。页面显示版本号、分发渠道（Full）、共享核心状态和本地任务执行诊断（可**重新检查**）；应用内更新也在这里（见第 1.2 节）。
- **诊断与反馈**（设置 → 诊断与关于）：描述问题，可选附带最多 4 张截图（上传前会压缩，原图不变）和基础诊断信息；也可开启**自动上报应用故障**。报告默认在 Wi-Fi 下上传；上传失败的报告保存在本机并可重试。反馈是可选的诊断材料，**不保证个别回复**。
- **报告实际 bug**：请在 [GitHub Issues](https://github.com/JiangNanGenius/floe-agent/issues) 提交，附上版本号（诊断与关于页可见）、机型、系统版本和复现步骤。

## 12. 当前限制

- **仅 Full APK 独立分发**：Google Play 线已于 2026-11-10 停止，不再提供 Play 版本。
- **无本地模型推理**：任务依赖你自己配置的云端模型；未配置模型时任务无法运行。
- **Android 9/10 的内嵌 ADB** 每次服务启动都需要电脑执行一次 USB 初始化；系统无线配对仅 Android 11 及以上提供。Android 9 真机验收仍在推进，个别机型可能遇到问题，请通过反馈或 GitHub Issues 报告。
- **自动解锁**受机型和锁屏方式限制（见第 5.3 节）；图案锁等场景需要手动处理。
- **与 iOS 版功能不完全一致**：例如 CAD/三维在安卓上是按需安装的预览查看，不是 iOS 上的原生三维建模编辑器；各版本能力以[对应发布说明](https://www.floe-agent.com/releases?platform=android)为准。