RFC: Android Edge Clips — 能力清单与实现规划

## 背景

clip-dock-android 规划中，Android 手机/平板作为 Edge Clip Provider 连入 Hub。本 Issue 系统梳理 Android 可释放的所有 Edge Clip 能力。

**Android 的核心优势**：AccessibilityService 可以读取和操控**任何 App** 的 UI，这是 iOS 完全做不到的。

---

## 总览

约 **130 个 commands**，分为 17 个 Edge Clip 模块。

```
Hub 视角:

Provider "android-pixel" (clip-dock-android)
  ├── android-screen       # 截图 + UI 树（AccessibilityService）
  ├── android-input        # 点击/滑动/输入/手势（AccessibilityService）
  ├── android-system       # 设备信息/电池/音量/亮度/WiFi/蓝牙/App 管理
  ├── android-telephony    # ★ 短信收发/电话/通话记录/SIM 信息
  ├── android-notifications # ★ 拦截所有 App 的通知
  ├── android-clipboard    # 剪贴板读写 + 监听
  ├── android-contacts     # 通讯录 + 日历
  ├── android-intent       # ★ 跨 App Intent 自动化
  ├── android-camera       # Camera2 / CameraX
  ├── android-location     # FusedLocationProvider + 地理围栏
  ├── android-sensors      # ★ 15+ 传感器（加速度/陀螺仪/气压/湿度/温度…）
  ├── android-audio        # TTS/STT/录音/播放/媒体控制
  ├── android-bluetooth    # BLE 扫描/连接/读写
  ├── android-nfc          # NFC 标签读写
  ├── android-health       # Health Connect API
  ├── android-files        # MediaStore + SAF
  └── android-biometrics   # 指纹/面部认证
```

★ = Android 独有优势（iOS 做不到或严重受限）

---

## 核心优势：AccessibilityService

Android 的 AccessibilityService 是**整个平台最强大的能力**：

- 接收**所有 App** 的 UI 元素树（实时、结构化）
- 对任意元素执行操作：点击、长按、滑动、输入文字
- 全局操作：返回、Home、最近任务、通知栏、快捷设置
- 复杂手势路径（缩放、自定义滑动）

这使得 AI Agent 可以**像人一样操控任何 App**，无需 API 对接：

```
场景："帮我在美团点我的常点"
1. android-screen.ui.tree → 获取美团 UI 树
2. LLM 推理 → 找到"再来一单"按钮
3. android-input.tap → 点击按钮
4. 重复直到下单完成
```

### vs iOS

| 能力 | Android | iOS |
|---|---|---|
| 读取其他 App UI 树 | ✅ AccessibilityService | ❌ 仅自身 App |
| 操控其他 App 元素 | ✅ 点击/输入/滑动 | ❌ |
| 全局操作 | ✅ 返回/Home/通知栏 | ❌ |
| 后台常驻 | ✅ Foreground Service | ❌ 后台挂起 |
| 通知拦截 | ✅ 所有 App 的通知 | ❌ 仅自身 |

---

## Phase 1: MVP — 基础 Agent 循环

### `android-screen` — 截图 + UI 树

| Command | 说明 | API |
|---|---|---|
| `screenshot()` | 截屏 | MediaProjection |
| `record.start()` / `stop()` | 录屏 | MediaProjection + MediaRecorder |
| `ui.tree(app?)` | 获取 UI 元素树 | AccessibilityService |
| `ui.snapshot()` | 截图 + UI 树（AI agent 用） | 组合 |
| `ui.find(query)` | 按文字/ID/类名查找元素 | AccessibilityNodeInfo |

### `android-input` — UI 交互

| Command | 说明 | API |
|---|---|---|
| `tap(x, y)` / `tap(node)` | 点击 | AccessibilityService |
| `longPress(x, y)` | 长按 | AccessibilityService |
| `swipe(x1, y1, x2, y2)` | 滑动 | AccessibilityService |
| `type(text)` | 输入文字 | AccessibilityService |
| `key(keyCode)` | 按键 | AccessibilityService |
| `scroll(direction)` | 滚动 | AccessibilityService |
| `gesture(path)` | 自定义手势 | GestureDescription |
| `global(action)` | 全局操作（返回/Home/最近/通知栏） | performGlobalAction |

### `android-system` — 设备信息与控制

| Command | 说明 |
|---|---|
| `info()` | 设备型号/OS/API level/RAM/存储 |
| `battery()` | 电量/充电状态/温度/健康度 |
| `volume(stream?, level?)` | 音量控制（媒体/铃声/闹钟/通知） |
| `brightness(level?)` | 亮度控制 |
| `screen(on/off/lock/unlock)` | 屏幕控制 |
| `wifi()` | WiFi 状态/SSID/IP/信号/扫描/连接 |
| `bluetooth(on/off)` | 蓝牙开关 |
| `airplane(on/off)` | 飞行模式 |
| `dnd(on/off)` | 勿扰模式 |
| `apps.list()` | 已安装 App 列表 |
| `apps.launch(pkg)` | 启动 App |
| `apps.kill(pkg)` | 强制停止 |
| `apps.usage()` | App 使用统计（屏幕时间） |
| `settings(key, value?)` | 系统设置读写 |

---

## Phase 2: 通信与数据

### `android-telephony` — 电话与短信 ★

| Command | 说明 |
|---|---|
| `sms.send(to, body)` | 发送短信 |
| `sms.list(box?, limit?)` | 读取短信收件箱/发件箱 |
| `sms.listen()` | 监听新短信 |
| `call.dial(number)` | 拨打电话 |
| `call.state()` | 当前通话状态 |
| `call.listen()` | 监听来电 |
| `call.log(limit?)` | 通话记录 |
| `sim.info()` | SIM 卡/运营商信息 |
| `ussd.execute(code)` | USSD 指令 |

**权限**: SEND_SMS, READ_SMS, RECEIVE_SMS, CALL_PHONE, READ_CALL_LOG, READ_PHONE_STATE

### `android-notifications` — 通知拦截 ★

| Command | 说明 |
|---|---|
| `list()` | 所有活跃通知 |
| `listen()` | 流式推送新通知 |
| `dismiss(key)` | 关闭通知 |
| `action(key, actionIndex)` | 执行通知操作（回复/标记已读等） |
| `post(title, body, channel?)` | 发送通知 |
| `history()` | 通知历史 (Android 11+) |

**服务**: NotificationListenerService（需系统设置中开启）

### `android-clipboard`

| Command | 说明 |
|---|---|
| `get()` | 读取剪贴板 |
| `set(content)` | 写入剪贴板 |
| `listen()` | 监听剪贴板变化 |

### `android-contacts` — 通讯录 + 日历

| Command | 说明 |
|---|---|
| `contacts.list(query?)` | 搜索联系人 |
| `contacts.add(data)` | 创建联系人 |
| `contacts.update(id, data)` | 更新联系人 |
| `calendar.list(dateRange?)` | 日历事件 |
| `calendar.add(event)` | 创建事件 |
| `calendar.update(id, event)` | 更新事件 |
| `calendar.delete(id)` | 删除事件 |
| `calendar.reminders(list?)` | 提醒事项 |

### `android-intent` — 跨 App 自动化 ★

| Command | 说明 |
|---|---|
| `send(action, uri?, extras?, pkg?)` | 发送 Intent |
| `broadcast(action, extras?)` | 发送广播 |
| `startActivity(intent)` | 启动 Activity |
| `share(content, targetPkg?)` | 分享内容 |
| `openUrl(url, browser?)` | 打开 URL |
| `deepLink(uri)` | 打开 Deep Link |

---

## Phase 3: 传感器与媒体

### `android-sensors` — 硬件传感器 ★

| Command | 说明 |
|---|---|
| `accelerometer(interval?)` | 三轴加速度 |
| `gyroscope(interval?)` | 三轴角速度 |
| `magnetometer(interval?)` | 三轴磁场 |
| `barometer()` | 气压 (hPa) |
| `proximity()` | 接近感应 |
| `light()` | 环境光 (lux) |
| `stepCounter()` | 累计步数 |
| `orientation()` | 方位角/俯仰/翻滚 |
| `gravity()` | 重力向量 |
| `linearAccel()` | 线性加速度 |
| `rotation()` | 旋转四元数 |
| `humidity()` | 相对湿度 |
| `temperature()` | 环境温度 |
| `stream(sensor, interval)` | 流式传感器数据 |
| `list()` | 枚举所有可用传感器 |

**框架**: SensorManager

### `android-camera`

| Command | 说明 |
|---|---|
| `photo(facing?)` | 拍照（后置/前置） |
| `video.start()` / `stop()` | 录像 |
| `preview(resolution?)` | 低分辨率预览流（agent 视觉用） |
| `flash(on/off)` | 手电筒 |
| `info()` | 相机能力（分辨率/变焦/焦距） |
| `qr.scan()` | 扫描二维码 |
| `torch(on/off)` | 闪光灯常亮 |

### `android-location`

| Command | 说明 |
|---|---|
| `current()` | 当前 GPS 坐标 |
| `track.start(interval)` / `stop()` | 持续定位 |
| `geocode(address)` | 地址 → 坐标 |
| `reverse(lat, lng)` | 坐标 → 地址 |
| `geofence.add(lat, lng, radius)` | 地理围栏 |
| `geofence.list()` | 围栏列表 |
| `speed()` | 当前速度 |
| `altitude()` | 海拔 |

### `android-audio`

| Command | 说明 |
|---|---|
| `tts(text, lang?)` | 语音合成（离线可用） |
| `stt.start()` / `stop()` | 语音识别 |
| `record.start(format?)` / `stop()` | 录音 |
| `play(path/url)` / `stop()` | 播放音频 |
| `media.info()` | 当前播放信息（MediaSession） |
| `media.control(action)` | 播放/暂停/上下曲 |
| `volume(stream, level)` | 音量 |
| `devices()` | 音频设备列表 |
| `setOutput(device)` | 切换输出设备 |

---

## Phase 4: 高级与 IoT

### `android-bluetooth`

| Command | 说明 |
|---|---|
| `scan(duration?)` | 扫描 BLE/经典蓝牙设备 |
| `connect(address)` | 连接 |
| `disconnect(address)` | 断开 |
| `paired()` | 已配对设备 |
| `write(address, char, data)` | 写 BLE 特征值 |
| `read(address, char)` | 读 BLE 特征值 |
| `subscribe(address, char)` | 订阅 BLE 通知 |

### `android-nfc`

| Command | 说明 |
|---|---|
| `scan()` | 读取 NFC 标签 (NDEF) |
| `write(records)` | 写入 NFC 标签 |
| `listen()` | 监听 NFC 标签发现 |

### `android-health` — Health Connect

| Command | 说明 |
|---|---|
| `steps(dateRange)` | 步数 |
| `heartRate(dateRange)` | 心率 |
| `sleep(dateRange)` | 睡眠 |
| `weight(dateRange)` | 体重 |
| `bloodOxygen(dateRange)` | 血氧 |
| `bloodPressure(dateRange)` | 血压 |
| `exercise(dateRange)` | 运动记录 |
| `nutrition(dateRange)` | 营养摄入 |
| `read(type, dateRange)` | 通用数据读取 |
| `write(type, value)` | 写入健康数据 |

### `android-files`

| Command | 说明 |
|---|---|
| `list(dir)` | 目录列表 |
| `read(path)` | 读文件 |
| `write(path, content)` | 写文件 |
| `delete(path)` | 删除 |
| `download(url, dest?)` | 下载 |
| `share(path)` | 系统分享面板 |
| `media.photos()` | MediaStore 照片 |
| `media.videos()` | MediaStore 视频 |

### `android-biometrics`

| Command | 说明 |
|---|---|
| `authenticate(reason)` | 生物认证（指纹/面部） |
| `available()` | 可用的生物识别硬件 |
| `enrolled()` | 是否已注册 |

---

## 实现架构

```
clip-dock-android (Kotlin/Compose)
├── Provider Service (Foreground Service)
│   ├── WebSocket Client → Hub (ProviderStream)
│   ├── Heartbeat Timer
│   └── Command Router → 各模块
├── AccessibilityService (系统授权)
│   ├── UI 树读取
│   └── 操作注入
├── NotificationListenerService (系统授权)
│   └── 通知拦截与转发
├── MediaProjection (用户授权)
│   └── 截图/录屏
└── Compose UI
    ├── Hub 连接配置
    ├── 权限管理面板
    └── 能力状态展示
```

### 关键挑战

| 挑战 | 方案 |
|---|---|
| OEM 杀后台 | Foreground Service + 引导关闭电池优化 + dontkillmyapp.com |
| AccessibilityService 掉线 | 健康监测 + 通知引导重新开启 |
| MediaProjection 每次需授权 | 启动时请求一次，保持 token |
| Android 碎片化 | minSdk 26, targetSdk 35, 能力检测 + 优雅降级 |
| Scoped Storage | MediaStore + SAF + App 私有目录 |

---

## 抽象 Clip 模式

```
notifications (Clip, Bun/TS)
  deps = ["android", "iphone"]
  list() → Android: 所有 App 通知 / iPhone: 仅自身

phone (Clip, Bun/TS)
  deps = ["android", "iphone"]
  sendSMS(to, body) → 路由到可用设备

ui-agent (Clip, Bun/TS)
  deps = ["android"]  ← Android 独有！iOS 做不到
  automate(task) → 用 screen + input 像人一样操作 App
```

---

## 关联 Issue

- #21 clip-dock — 跨平台客户端（Portal + Edge Clip）
- #32 RFC: macOS Edge Clips
- #33 RFC: iPhone Edge Clips
- #30 RFC: Runtime 与 Provider 协议分离

能力	Android	iOS
读取其他 App UI 树	✅ AccessibilityService	❌ 仅自身 App
操控其他 App 元素	✅ 点击/输入/滑动	❌
全局操作	✅ 返回/Home/通知栏	❌
后台常驻	✅ Foreground Service	❌ 后台挂起
通知拦截	✅ 所有 App 的通知	❌ 仅自身

Command	说明	API
`screenshot()`	截屏	MediaProjection
`record.start()` / `stop()`	录屏	MediaProjection + MediaRecorder
`ui.tree(app?)`	获取 UI 元素树	AccessibilityService
`ui.snapshot()`	截图 + UI 树（AI agent 用）	组合
`ui.find(query)`	按文字/ID/类名查找元素	AccessibilityNodeInfo

Command	说明	API
`tap(x, y)` / `tap(node)`	点击	AccessibilityService
`longPress(x, y)`	长按	AccessibilityService
`swipe(x1, y1, x2, y2)`	滑动	AccessibilityService
`type(text)`	输入文字	AccessibilityService
`key(keyCode)`	按键	AccessibilityService
`scroll(direction)`	滚动	AccessibilityService
`gesture(path)`	自定义手势	GestureDescription
`global(action)`	全局操作（返回/Home/最近/通知栏）	performGlobalAction

Command	说明
`info()`	设备型号/OS/API level/RAM/存储
`battery()`	电量/充电状态/温度/健康度
`volume(stream?, level?)`	音量控制（媒体/铃声/闹钟/通知）
`brightness(level?)`	亮度控制
`screen(on/off/lock/unlock)`	屏幕控制
`wifi()`	WiFi 状态/SSID/IP/信号/扫描/连接
`bluetooth(on/off)`	蓝牙开关
`airplane(on/off)`	飞行模式
`dnd(on/off)`	勿扰模式
`apps.list()`	已安装 App 列表
`apps.launch(pkg)`	启动 App
`apps.kill(pkg)`	强制停止
`apps.usage()`	App 使用统计（屏幕时间）
`settings(key, value?)`	系统设置读写

Command	说明
`sms.send(to, body)`	发送短信
`sms.list(box?, limit?)`	读取短信收件箱/发件箱
`sms.listen()`	监听新短信
`call.dial(number)`	拨打电话
`call.state()`	当前通话状态
`call.listen()`	监听来电
`call.log(limit?)`	通话记录
`sim.info()`	SIM 卡/运营商信息
`ussd.execute(code)`	USSD 指令

Command	说明
`list()`	所有活跃通知
`listen()`	流式推送新通知
`dismiss(key)`	关闭通知
`action(key, actionIndex)`	执行通知操作（回复/标记已读等）
`post(title, body, channel?)`	发送通知
`history()`	通知历史 (Android 11+)

Command	说明
`get()`	读取剪贴板
`set(content)`	写入剪贴板
`listen()`	监听剪贴板变化

Command	说明
`contacts.list(query?)`	搜索联系人
`contacts.add(data)`	创建联系人
`contacts.update(id, data)`	更新联系人
`calendar.list(dateRange?)`	日历事件
`calendar.add(event)`	创建事件
`calendar.update(id, event)`	更新事件
`calendar.delete(id)`	删除事件
`calendar.reminders(list?)`	提醒事项

Command	说明
`send(action, uri?, extras?, pkg?)`	发送 Intent
`broadcast(action, extras?)`	发送广播
`startActivity(intent)`	启动 Activity
`share(content, targetPkg?)`	分享内容
`openUrl(url, browser?)`	打开 URL
`deepLink(uri)`	打开 Deep Link

Command	说明
`accelerometer(interval?)`	三轴加速度
`gyroscope(interval?)`	三轴角速度
`magnetometer(interval?)`	三轴磁场
`barometer()`	气压 (hPa)
`proximity()`	接近感应
`light()`	环境光 (lux)
`stepCounter()`	累计步数
`orientation()`	方位角/俯仰/翻滚
`gravity()`	重力向量
`linearAccel()`	线性加速度
`rotation()`	旋转四元数
`humidity()`	相对湿度
`temperature()`	环境温度
`stream(sensor, interval)`	流式传感器数据
`list()`	枚举所有可用传感器

Command	说明
`steps(dateRange)`	步数
`heartRate(dateRange)`	心率
`sleep(dateRange)`	睡眠
`weight(dateRange)`	体重
`bloodOxygen(dateRange)`	血氧
`bloodPressure(dateRange)`	血压
`exercise(dateRange)`	运动记录
`nutrition(dateRange)`	营养摄入
`read(type, dateRange)`	通用数据读取
`write(type, value)`	写入健康数据

Command	说明
`photo(facing?)`	拍照（后置/前置）
`video.start()` / `stop()`	录像
`preview(resolution?)`	低分辨率预览流（agent 视觉用）
`flash(on/off)`	手电筒
`info()`	相机能力（分辨率/变焦/焦距）
`qr.scan()`	扫描二维码
`torch(on/off)`	闪光灯常亮

Command	说明
`current()`	当前 GPS 坐标
`track.start(interval)` / `stop()`	持续定位
`geocode(address)`	地址 → 坐标
`reverse(lat, lng)`	坐标 → 地址
`geofence.add(lat, lng, radius)`	地理围栏
`geofence.list()`	围栏列表
`speed()`	当前速度
`altitude()`	海拔

Command	说明
`tts(text, lang?)`	语音合成（离线可用）
`stt.start()` / `stop()`	语音识别
`record.start(format?)` / `stop()`	录音
`play(path/url)` / `stop()`	播放音频
`media.info()`	当前播放信息（MediaSession）
`media.control(action)`	播放/暂停/上下曲
`volume(stream, level)`	音量
`devices()`	音频设备列表
`setOutput(device)`	切换输出设备

Command	说明
`scan(duration?)`	扫描 BLE/经典蓝牙设备
`connect(address)`	连接
`disconnect(address)`	断开
`paired()`	已配对设备
`write(address, char, data)`	写 BLE 特征值
`read(address, char)`	读 BLE 特征值
`subscribe(address, char)`	订阅 BLE 通知

Command	说明
`scan()`	读取 NFC 标签 (NDEF)
`write(records)`	写入 NFC 标签
`listen()`	监听 NFC 标签发现

Command	说明
`list(dir)`	目录列表
`read(path)`	读文件
`write(path, content)`	写文件
`delete(path)`	删除
`download(url, dest?)`	下载
`share(path)`	系统分享面板
`media.photos()`	MediaStore 照片
`media.videos()`	MediaStore 视频

Command	说明
`authenticate(reason)`	生物认证（指纹/面部）
`available()`	可用的生物识别硬件
`enrolled()`	是否已注册

挑战	方案
OEM 杀后台	Foreground Service + 引导关闭电池优化 + dontkillmyapp.com
AccessibilityService 掉线	健康监测 + 通知引导重新开启
MediaProjection 每次需授权	启动时请求一次，保持 token
Android 碎片化	minSdk 26, targetSdk 35, 能力检测 + 优雅降级
Scoped Storage	MediaStore + SAF + App 私有目录

RFC: Android Edge Clips — 能力清单与实现规划 #34

Description

背景

总览

核心优势：AccessibilityService

vs iOS

Phase 1: MVP — 基础 Agent 循环

android-screen — 截图 + UI 树

android-input — UI 交互

android-system — 设备信息与控制

Phase 2: 通信与数据

android-telephony — 电话与短信 ★

android-notifications — 通知拦截 ★

android-clipboard

android-contacts — 通讯录 + 日历

android-intent — 跨 App 自动化 ★

Phase 3: 传感器与媒体

android-sensors — 硬件传感器 ★

android-camera

android-location

android-audio

Phase 4: 高级与 IoT

android-bluetooth

android-nfc

android-health — Health Connect

android-files

android-biometrics

实现架构

关键挑战

抽象 Clip 模式

关联 Issue

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`android-screen` — 截图 + UI 树

`android-input` — UI 交互

`android-system` — 设备信息与控制

`android-telephony` — 电话与短信 ★

`android-notifications` — 通知拦截 ★

`android-clipboard`

`android-contacts` — 通讯录 + 日历

`android-intent` — 跨 App 自动化 ★

`android-sensors` — 硬件传感器 ★

`android-camera`

`android-location`

`android-audio`

`android-bluetooth`

`android-nfc`

`android-health` — Health Connect

`android-files`

`android-biometrics`