<p align="center">
  <img src="assets/logo/logo-banner.png" alt="Android Bridge" width="700" />
</p>

# agent-Android-bridge

[简体中文](README.md) | [English](README.en.md) | [美术与设计资产 (Assets)](assets/ASSETS_INDEX.md)

agent-Android-bridge 是面向 AI Agent 的 Android 执行桥。它通过 MCP 暴露设备发现、应用与进程管理、UI 树、截图/OCR、输入手势、文件与 Shell 操作，以及按设备串行的异步命令队列。

当前主线是 2.0.0 架构，提供两种设备驱动：

- **ADB 驱动**：通过 USB 或 Wireless ADB 控制已授权设备，能力最完整。
- **Android Runner**：手机主动建立 WSS 连接，适合跨 NAT 场景；当前 APK 主要覆盖截图、UI 树、手势、文字和剪贴板能力。

当前源码注册 58 个 MCP 工具。工具列表以 MCP 客户端发现结果和 src/agent_android/mcp_server/server.py 为准。

> agent-Android-bridge 可以触发真实点击、消息发送、文件修改和应用操作。只控制自己拥有或获准控制的设备；付款、删除、发送等后果性动作应保留人工确认，并读取操作后的 UI 验证结果。

## 快速开始

要求：Windows、Python 3.11，以及 ADB 驱动路径所需的 Android Platform Tools。

`powershell
git clone https://github.com/xiaoran7/agent-Android-bridge.git agent-Android-bridge
cd agent-Android-bridge
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev,ocr]"
.\.venv\Scripts\agent-android-bridge.exe setup
`

连接手机并在设备上批准调试授权：

`powershell
.\.venv\Scripts\agent-android-bridge.exe devices
.\.venv\Scripts\agent-android-bridge.exe info "<device-id>"
`

启动本地 stdio MCP：

`powershell
.\.venv\Scripts\agent-android-bridge.exe mcp
`

Codex 注册示例：

`powershell
codex mcp add agent-android-bridge --env "ADB_PATH=C:\Android\platform-tools\adb.exe" -- "C:\path\to\agent-Android-bridge\.venv\Scripts\python.exe" -m agent_android.cli mcp
`

其他 stdio 客户端可参考 [.mcp.json.example](.mcp.json.example)。

## SSE 与 Android Runner

SSE 模式同时挂载 Android Runner 的 WebSocket 入口 /runner/ws：

`powershell
.\.venv\Scripts\agent-android-bridge.exe mcp --transport sse --host 127.0.0.1 --port 8765
`

Runner 必须连接到同一服务对应的 ws://.../runner/ws 或 wss://.../runner/ws。

### Runner 身份认证（tg-oauth）

Runner 握手支持 OAuth 2.0 Bearer 认证：APK 以 Authorization Code + PKCE 通过 TannerLab ID（tg-oauth）登录，WebSocket 握手携带 Authorization: Bearer <token>，网关经 RFC 7662 introspection 验证通过后才注册会话。

配置以下三项后认证**强制开启**（缺一项即回退为接受未认证设备，仅限本机开发）：

| 变量 | 用途 |
| --- | --- |
| AGENT_ANDROID_RUNNER_OAUTH_ISSUER | tg-oauth 发行者 URL，如 https://auth.tannerlab.cn |
| AGENT_ANDROID_RUNNER_OAUTH_CLIENT_ID | 网关使用的机密客户端 ID（调 introspection 用） |
| AGENT_ANDROID_RUNNER_OAUTH_CLIENT_SECRET | 上述机密客户端的 secret |
| AGENT_ANDROID_RUNNER_OAUTH_ALLOWED_CLIENTS | 允许接入的 Runner 客户端列表，默认 gent-android-runner,agent-android-bridge-runner,droidbridge-runner |

tg-oauth 侧需在部署环境变量 OAUTH_CLIENTS 注册两个客户端（公共客户端给 APK，机密客户端给网关；接入契约见 tg-oauth docs/INTEGRATION.md）：

`json
[
  {"client_id": "droidbridge-runner", "name": "agent-Android-bridge Runner", "description": "agent-Android-bridge Android Runner 设备端", "redirect_uris": ["agent-android-bridge://oauth/callback", "droidbridge://oauth/callback"]},
  {"client_id": "droidbridge-gateway", "name": "agent-Android-bridge Gateway", "description": "agent-Android-bridge Runner 接入网关（introspection）", "redirect_uris": ["https://mcp2.tannerlab.xyz/runner/callback"], "client_secret": "<与网关 env 一致>"}
]
`

注意：tg-oauth 的 seed 校验要求每条 
edirect_uris 非空，机密客户端也要至少登记一个占位回调地址。

公网部署必须同时具备受信任反代的 TLS 与此处认证；认证回答的是"这条会话是谁发起的"，设备授权与后果性动作确认仍由运营者自行保留。

Android APK 的构建、权限与当前能力见 [Runner README](apps/runner-android/README.md)。

## 推荐调用顺序

1. list_devices
2. screen_summary；无有效无障碍树时再用 screenshot 或 OCR
3. ind_element / wait_for_element
4. 执行最小必要动作
5. 再次读取 UI、前台应用或命令状态，确认真实结果

submit_action、get_command_status、list_commands 与 cancel_command 提供非阻塞命令票据。同一设备按提交顺序执行，不同设备可并行；只能取消仍处于 pending 的命令。

## Unicode 输入

ADB 路径的可靠 Unicode 输入需要用户自行提供并核验 ADBKeyBoard：

`powershell
.\scripts\install_adb_keyboard.ps1 -DeviceId "<device-id>" -ApkPath "C:\path\to\ADBKeyboard.apk"
`

input_text(method="auto") 在没有可靠输入后端时会明确失败。若显式使用 method="raw"，应接受输入法拦截、转义和 OEM 差异带来的不可靠性。Runner 使用无障碍输入，不依赖 ADBKeyBoard。

## 配置

| 变量 | 用途 |
| --- | --- |
| ADB_PATH | db 可执行文件路径 |
| AGENT_ANDROID_DATA_DIR | 设备记录和活动数据库目录 |
| AGENT_ANDROID_RUNTIME_DIR | 命令队列与进程锁目录 |
| AGENT_ANDROID_COMMANDS_DB | 命令队列 SQLite 文件 |
| AGENT_ANDROID_COMMAND_QUEUE_TIMEOUT | 命令开始前的排队超时 |
| AGENT_ANDROID_COMMAND_QUEUE_MAX_PENDING | 单设备待处理/运行命令上限 |
| AGENT_ANDROID_SCRCPY_SERVER_JAR | 开发时覆盖 scrcpy-server |
| AGENT_ANDROID_SCRCPY_SERVER_VERSION | 自定义 scrcpy-server 版本 |
| AGENT_ANDROID_SCRCPY_SERVER_SHA256 | 自定义 scrcpy-server 摘要 |
| AGENT_ANDROID_SCRCPY_MAX_SIZE | scrcpy 编码最长边 |
| AGENT_ANDROID_RUNNER_OAUTH_ISSUER | tg-oauth 发行者 URL；与 CLIENT_ID/SECRET 同时配置后 Runner 握手强制认证 |
| AGENT_ANDROID_RUNNER_OAUTH_CLIENT_ID | 网关 introspection 用的机密客户端 ID |
| AGENT_ANDROID_RUNNER_OAUTH_CLIENT_SECRET | 上述机密客户端的 secret |
| AGENT_ANDROID_RUNNER_OAUTH_ALLOWED_CLIENTS | 允许接入的 Runner 客户端列表 |

## 开发检查

`powershell
.\scripts\setup_venv.ps1
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m bandit -q -r src
.\.venv\Scripts\python.exe -m build
`

Android Runner 需要 Android Studio、JDK 17 和 Android SDK 35；仓库目前没有 Gradle Wrapper。

## 当前边界

- stdio 适合本机 Agent + ADB；Android Runner 需要 SSE 服务承载 WebSocket。
- Runner 握手认证依赖 tg-oauth introspection；未配置 issuer 时网关接受未认证设备，只应用于本机开发。
- Runner APK 只实现 MCP 表面的一个能力子集；未知动作会返回失败。
- 无障碍树可能缺失 Canvas、游戏或部分 WebView 内容，此时使用截图/OCR。
- Android OEM 的输入法、后台冻结、无线调试和无障碍策略差异较大。
- 命令队列只持久化脱敏参数和状态；可执行回调留在提交进程，进程退出后不能由其他进程重放。
- pyproject.toml 已是 2.0.0，但部分打包脚本和运行时版本常量仍在迁移；发布前必须完成一致性检查。

## 文档

- [文档索引](docs/README.md)
- [Agent 使用指南](docs/AGENT_USAGE.md)
- [架构](docs/ARCHITECTURE.md)
- [设备准备](docs/DEVICE_SETUP.md)
- [开发陷阱](docs/gotchas.md)
- [变更记录](CHANGELOG.md)
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)

代码采用 [MIT License](LICENSE)。内置 scrcpy-server 的来源与 Apache 2.0 许可见[第三方声明](THIRD_PARTY_NOTICES.md)。