ThumbAgent

Local-first platform that gives AI agents a real thumb on mobile devices. 本地优先的移动设备 Skills 平台——给 AI 一只真正的「拇指」。

中文 | English

用自然语言描述目标，ThumbAgent 的 Agent 在真实 Android 设备上自主完成 「观察 → 规划 → 操作 → 验证 → 恢复」的完整闭环，并产出可复现、可审计的执行报告：

自然语言目标
    → 任务规划（LLM Planner）
    → 设备操作（经 Schema / Capability / Policy 三重校验）
    → 状态观察（截图 + UI Tree）
    → 结果验证与异常恢复
    → 日志、性能和截图等现场采集
    → 可复现、可审计的执行报告

所有数据留在本地：无云端账号、无遥测、密钥只进系统钥匙串。

快速开始

方式一：下载安装包（推荐）

从 Releases 下载 ThumbAgent_x.x.x_aarch64.dmg（macOS Apple Silicon，已签名 + 公证），拖入「应用程序」。

首次启动后在设置页填写模型 Provider（Base URL / 模型名称 / API Key）即可开始。 API Key 只存入 macOS 钥匙串，永不落盘。

前提：一台开启 USB 调试的 Android 设备 + 本机已安装 ADB。

方式二：从源码运行

git clone https://github.com/LiuShiYi1027/ThumbAgent.git
cd ThumbAgent

make check          # Python 门禁：lint / typecheck / 测试 / Contract 检查
make run            # 启动 Runtime（默认 127.0.0.1:8765）

cd apps/desktop
npm install
npm run tauri dev   # 桌面工作台

要求 Python 3.11+、Node 20+、Rust stable、ADB。

Related MCP server: android-mcp

核心能力

• 自然语言任务：桌面工作台输入目标，Agent 多轮决策自主执行

• 真实设备闭环：设备发现、画面观察、点击/滑动/输入等基础动作、完成验证、瞬时故障有界重试

• 执行时间线与报告：逐轮截图、决策、动作与结果完整留痕，随时回看

• 人工接管：执行中在安全边界暂停 Agent，人工操作设备后恢复续跑，接管区间计入事件流

• 诊断证据：脱敏日志、聚合性能快照、性能对比、一键诊断证据包（带 SHA-256 清单的本地 ZIP）

• 数据治理：本地 Artifact 留存策略 + 两阶段授权清理

• 开放接口：Local HTTP API + MCP Server，可接入 Codex 等外部 Agent

桌面工作台

Tauri 2 原生应用，mono 编辑风设计：自动拉起并认证本地 Runtime、统一就绪诊断、 设备列表与实时画面（手机框呈现）、任务提交与执行时间线、设置页开箱配置。

安全设计

• 所有设备动作经过 Schema / Capability / Policy 三层校验，绑定明确 device_id

• 中高风险动作默认需要显式确认；支付、验证码、权限绕过直接拒绝

• 无任意 Shell、无 ADB 透传、无隐藏逃生口；安装/卸载/清理均为两阶段 Approval 流程

• 模型输出一律视为不可信输入：结构化解析 + allowlist 二次校验

• 密钥、令牌只存在于系统钥匙串与进程环境，不进代码、数据库、日志

架构

Clients / Interfaces（Desktop · CLI · MCP · Web）
        ↓
Application / Skills / Task Engine
        ↓
Domain / Policy / Contracts
        ↓
Device Gateway
        ↓
Platform Adapters（Android via ADB）

跨模块数据一律 Contract-first：contracts/schemas/ 定义 Schema，再生成语言类型。 详见架构边界。

文档

产品：产品定位 · V1 产品方案 · 技术设计

工程：开发规范 · 迭代索引 · 分发与发布 · 安全规范 · ADR

贡献：Agent 开发入口 · 贡献指南

路线图

V1 聚焦单台 Android 设备的本地 AI-to-Device 闭环（已完成 v0.1.0）。 后续方向：更多设备能力、评测套件完善、iOS 适配探索。详见迭代索引。

许可证

Apache-2.0