Skip to content

About

让 LLM Agent 直接在线调试安卓设备 —— 抽象 adb / ssh / UART 多种传输,通过 MCP / CLI / Web API 三层接入大模型。

doc.tbusos.com/android-llm-bridge/

Topics

ai-agentsai-toolingandroidclidebuggingllmmcpmcp-serverpythonstatus-stable

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

android-llm-bridge

让 LLM Agent 直接在线调试安卓设备 —— 一套可扩展的统一调试桥，抽象 adb / ssh / UART 串口多种传输，通过 MCP / CLI / Web API 三层接入大模型。

for Claude Code · Cursor · Codex · 任意支持 MCP 的 Agent

快速开始 · 方案对比 · 文档 · English

这是什么

android-llm-bridge（简称 alb）是一个面向大模型的安卓设备在线调试桥。核心定位：

让 AI Agent 像使用普通函数一样，安全、结构化地操作真实安卓设备 —— 不论设备怎么连接（USB adb / 无线 adb / 板子跑 sshd / 还是只有 UART 串口）。

为什么需要它

传统 adb/ssh 命令行给人用很好，但给大模型用会踩一堆坑：

  • 输出是自由文本，LLM 解析容易出错
  • 出错只有 stderr 一串英文，没有结构化 error code
  • 长会话积累大量 logcat，context 一下塞爆
  • 危险命令（rm -rf、reboot bootloader）没挡一层，LLM 误触就是一次刷机
  • 多种连接方式（USB/WiFi/串口）各有各的命令，LLM 要记一堆
  • 跑分、ANR、性能采集这些高级能力每次都要 LLM 自己拼命令

alb 解决这些问题：

  • 统一命令（alb shell / alb logcat / alb pull 等），自动选最合适的传输通道
  • 所有输出 --json 可选，返回 {ok, data, error, artifacts} 结构化
  • 内置权限系统，危险命令默认拦截，可配置 allow/ask/deny 多层策略
  • 长日志走 workspace 分层存储 + 换页机制，LLM 按需读取
  • MCP server 原生支持，Claude Code / Cursor 一行配置即可用

核心特性

特性 说明
多传输抽象 adb USB / adb WiFi / 板子 sshd / UART 串口 —— 上层命令一致，底层自动路由
LLM-first API 结构化返回、错误码、自描述 CLI、SKILL.md 自动生成
三层接入 CLI (alb) · MCP server (alb-mcp) · Web API (FastAPI)，共享同一套业务层
权限与安全 危险命令黑名单 + tool 级 check_permissions + 多层策略覆盖
产物规范化 logcat / ANR / bugreport / 性能数据 全部入 workspace/devices/<serial>/...
长日志友好 分层存储（热/温/冷）+ 搜索 + 归档，LLM 不怕 context 爆
Web 可视化（后续） 浏览器看设备状态、实时 log、性能曲线

支持的调试方案

第一版落地 A / B / C / G 四种方案，D / E / F 接口预留。

方案 通道 启动log u-boot 板子无网 板子死机 一句话定位
A · adb USB（+ SSH 反向隧道） adb 协议 ❌ ❌ ✅ ❌ 系统级基础，必装
B · adb WiFi TCP ❌ ❌ ❌ ❌ 无线临时调试
C · 板子内 sshd ssh ❌ ❌ ❌ ❌ 开发增强（rsync/tmux/sshfs）
G · UART 串口 串口 ✅ ✅ ✅ ✅ 最后底牌，bringup / panic 救援
D · USB 网络共享 IP-USB - - - - 预留
E · scrcpy 屏幕镜像 adb - - - - 预留
F · frp / 云中转 公网 - - - - 预留

按使用场景选：

场景 推荐方案 理由
系统刷机 / 进 recovery / 进 fastboot A adb 在 recovery 下仍可用，sshd 不可
开发日常：改代码 → 推板子 → 看效果 C + A rsync 增量快、长 session；A 兜底
大量设备 CI / 自动化 B + C 无线省线、多设备并发
板子起不来 / 内核 panic / u-boot 调试 G 只有串口能看到底层日志
客户现场远程调试 远程 agent（dial-home） 设备侧主动拨出 wss，hub 公网/反代可达即可
板子在 Windows 上，Linux 服务器调 远程 agent（dial-home） Windows 双击 run-agent.bat 拨出，免隧道、免入站端口

详见 docs/methods/00-comparison.md。

板子插在别的电脑上？→ 远程设备 agent（dial-home）

板子物理插在 Windows（或任何别的机器）上时，不需要 SSH 隧道、设备侧不用开 任何入站端口——agent 主动拨出连 hub：

  1. hub（跑 alb 的 Linux）：cd deploy/hub && cp hub.env.example hub.env （填共享 token；要串口再填 COM + 波特率）→ ./run-hub.sh
  2. 设备侧（Windows）：把 clients/windows-agent/ 拷过去， agent.conf.example 复制为 agent.conf 填 hub 地址 + token → 双击 run-agent.bat（每次启动自检环境，缺依赖自动装）

之后 adb / UART 串口 / Web 控制台 / MCP 全部从 hub 侧驱动，跟板子直接插在 hub 上一样。完整链路与逐跳排障：docs/dial-home-runbook.md； 设备侧操作手册（中文）：clients/windows-agent/README.md。

架构概览

┌────────────────────────────────────────────────────────┐
│  接入层（壳）                                            │
│  ├─ CLI (typer)          给人 / LLM 直接用              │
│  ├─ MCP Server           给 Claude/Cursor/Codex 调用    │
│  ├─ Web API (FastAPI)    给 Web UI / 外部集成           │
│  └─ Web UI (后续)         可视化                         │
├────────────────────────────────────────────────────────┤
│  业务能力层 Capabilities（M1 六个）                      │
│  shell │ logging │ filesync │ diagnose │ power │ app   │
├────────────────────────────────────────────────────────┤
│  ⭐ 传输抽象层 Transport                                 │
│  interface: shell / stream_read / push / pull /         │
│             forward / reboot / check_permissions        │
│  ├─ AdbTransport       (方案 A / B)                     │
│  ├─ SshTransport       (方案 C / D / F)                 │
│  ├─ SerialTransport    (方案 G)                         │
│  └─ HybridTransport    (智能路由：按命令类型选通道)       │
├────────────────────────────────────────────────────────┤
│  底层驱动 Drivers                                       │
│  adb · ssh · scp · rsync · pyserial · socat · 隧道管理  │
├────────────────────────────────────────────────────────┤
│  基础设施 Infra                                         │
│  config · workspace · profile · permissions · errors    │
│  event-bus · prompt-builder · memory (M2+)             │
└────────────────────────────────────────────────────────┘

关键设计：上层业务 / MCP server / Web API 共享同一 Python 函数定义，三层只是薄壳 —— 详见 docs/architecture.md。

快速开始

⚠️ 当前状态：M1 核心完成。四种传输（A adb USB / B adb WiFi / C sshd / G UART）全部 beta；六个能力（shell / logging / filesync / diagnose / power / app）可用；21 个 MCP tool 注册完毕。详见 docs/project-plan.md 和 CHANGELOG.md。

一键部署（推荐，完全用户态）

不需要 root，不碰系统 Python。uv 和 Python 3.11 装到 ~/.local/，其他用户和其他项目完全不受影响。

git clone https://github.com/<your>/android-llm-bridge
cd android-llm-bridge
./scripts/install.sh

装好后：

export PATH="$HOME/.local/bin:$PATH"

uv run alb describe          # 列出所有 transport 和 capability
uv run alb status            # 环境健康检查
uv run alb devices           # 列连接的设备

一键卸载：

./scripts/uninstall.sh               # 只删 .venv/ 和缓存
./scripts/uninstall.sh --purge-workspace --remove-uv  # 彻底清理

详细隔离原理 + 故障排查见 docs/install.md。

手动部署（如果已有 uv + Python 3.11）

cd android-llm-bridge
uv sync                    # 装依赖
uv run alb --help          # 看看能做什么
uv run pytest -q           # 跑测试（60+ 用例）

配一种传输方案

# 方案 A — adb USB（本地；或含 Xshell 反向隧道）
export ADB_SERVER_SOCKET=tcp:localhost:5037   # 仅远程 Xshell 场景需要
uv run alb setup adb                           # 引导式体检 + 验证
uv run alb devices
uv run alb shell "getprop ro.build.version.sdk"
uv run alb logcat --duration 30 --filter "*:E"
uv run alb diag bugreport

# 方案 B — adb WiFi（先经方案 A 授权一次）
uv run alb setup wifi 192.168.1.42            # 自动跑 tcpip + connect

# 方案 C — 板子内 sshd
uv run alb setup ssh 192.168.1.42 --key ~/.ssh/alb-device
ALB_SSH_HOST=192.168.1.42 uv run alb --transport ssh shell 'uname -a'
uv run alb fs rsync ~/out/system/ /system-dev/   # 方案 C 独占

# 方案 G — UART 串口（TCP via ser2net + Xshell）
uv run alb setup serial --tcp-host localhost --tcp-port 9001
uv run alb serial capture --duration 30       # 抓启动 / panic / u-boot 日志
uv run alb serial shell "dmesg | tail"

配置方式详见 docs/methods/。

接入 Claude Code（MCP）

// ~/.claude/mcp-settings.json
{
  "mcpServers": {
    "alb": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/android-llm-bridge", "alb-mcp"]
    }
  }
}

在 Claude Code 里直接让它"帮我看看板子最近的 ANR"、"拉一份 bugreport"、"监控 15 分钟的 CPU 占用"即可，无需手写 adb 命令。

文档导航

类别 文档 给谁看
起步 README.md / README.en.md 所有人
安装 / 卸载 docs/install.md 部署 / 运维
总览 docs/00-overview.md 先看这个
架构 docs/architecture.md 想了解内部设计
设计决策 docs/design-decisions.md 想知道为啥这么做
LLM 集成 docs/llm-integration.md Agent / AI 开发者
Agent 层设计 docs/agent.md 宿主端 agent / backend 选型
设备端模型选型 docs/on-device-model-selection.md 全球商用场景选型(许可 + SoC 硬件)
远程设备调试 docs/dial-home-runbook.md 板子在另一台电脑上：端到端搭建 + 排障
Windows 设备端 agent clients/windows-agent/README.md 板子所在 Windows 的操作者（中文）
权限系统 docs/permissions.md 安全 / 部署人员
错误码 docs/errors.md LLM / 排错时查表
Tool 写法 docs/tool-writing-guide.md 贡献者
项目计划 docs/project-plan.md 想了解里程碑进度
贡献指南 docs/contributing.md 贡献者
调试方案 docs/methods/ 按方案查手册
业务能力 docs/capabilities/ 按能力查手册

路线图

里程碑 交付内容 状态
M0 仓库骨架 + 完整技术方案文档 + 架构图 + 里程碑规划 ✅ 当前
M1 四种传输（A/B/C/G）+ 六能力（shell/logging/filesync/diagnose/power/app）+ 权限系统 + CLI + MCP 骨架 🚧 进行中
M2 Web API + 长任务框架（流式 logcat / 大文件传输）+ 子 Agent 并行 + 性能能力（perf）+ 跑分（benchmark） 📋 规划中
M3 Web UI（设备看板 / 实时日志 / 性能曲线）+ LLM-assisted 日志分析 + 方案 D/E/F 📋 规划中

详见 docs/project-plan.md。

贡献

欢迎贡献新的传输方案、业务能力、LLM 集成示例！开始前请阅读：

  1. docs/contributing.md —— 开发流程 / 代码风格 / PR checklist
  2. docs/tool-writing-guide.md —— LLM 友好 tool 怎么写
  3. llm/CLAUDE.md —— 如果用 Claude Code 协作开发

致谢

本项目在设计阶段参考了以下优秀项目的理念：

  • Claude Code —— 权限系统分层设计、tool schema、session memory 思想
  • MCP —— Anthropic Model Context Protocol，本项目的 LLM 接入标准
  • CLI-Anything —— SKILL.md 自动生成、core/CLI 解耦思路
  • 学术思想：MemGPT（分层上下文）、Evo-Memory（失败学习）、MemoryBank（衰减归档）

License

Apache License 2.0 © 2026 sky <[email protected]>,另见 NOTICE。 2026-10-10 之前发布的版本采用 MIT 许可,已经拿到的副本仍按 MIT 使用。

About

让 LLM Agent 直接在线调试安卓设备 —— 抽象 adb / ssh / UART 多种传输,通过 MCP / CLI / Web API 三层接入大模型。

doc.tbusos.com/android-llm-bridge/

Topics

ai-agentsai-toolingandroidclidebuggingllmmcpmcp-serverpythonstatus-stable

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages