DroidAgentKit

DroidAgentKit

通过本地、权限受控的 MCP 服务，为 AI 编码 Agent 提供真正的 Android 工具——Gradle、adb、logcat、lint、崩溃排查等，而不是让其直接访问原始 shell。

DroidAgentKit 可帮助你借助 AI Agent 开发 Android 项目。它在你的计算机上运行，可与 Gradle 项目树通信，并且在你允许时与模拟器或设备通信，为 Agent 提供结构化结果，而不是原始 shell 输出。

专为 Android 打造。 跨平台自动化服务也支持 iOS，但功能止步于屏幕点击。DroidAgentKit 则深入 Android 构建系统和工具链——Gradle 任务允许列表、lint、R8 崩溃排查、Perfetto 跟踪、应用存储、Compose 视觉回归。不支持 iOS，未来也没有相关计划。

一切都在本地进行。命令通过允许列表执行。输出在返回给 Agent 前会经过脱敏。默认情况下，生成的文件会保存在 build/droidagentkit 下。

你将获得

三个部分，可单独使用，也可组合使用：

MCP 服务 — Agent 可调用的 Model Context Protocol 服务。检查项目、运行安全的 Gradle 任务、采集日志和屏幕截图、排查崩溃、运行 lint、分析构建性能等。可选功能组还支持设备诊断、有限的设备控制、Perfetto 跟踪、视觉回归、只读应用存储检查，以及实验性的模拟器网络捕获。

就绪度审计工具 — 评估代码仓库对 Agent 的友好程度、列出风险，并可生成 AGENTS.md、项目技能文件和初始 .droidagentkit/config.yaml。需要生成可安全分享的报告时，请使用 --redact-public。

视觉回归工具包 — 为 Compose/UI 截图生成像素差异报告，并提供 Gradle 插件和 JUnit 规则。MCP 工具可比较基准图像、生成报告，并在你明确确认后更新基准图像。

MCP 工具一览

核心组默认启用（18 个工具）：项目检查、允许列表中的 Gradle 运行、设备列表、安装/启动、logcat、屏幕截图、无障碍快照、报告包、lint、崩溃排查、依赖项检查、构建性能、测试运行、构建诊断、APK 大小分析、UI 元素查找，以及 android_doctor（当某项功能因不明原因失败时，可运行此环境预检）。

启动服务时，通过公开工具组启用更多工具（参见安全模型）：

组	新增内容
device_read	权限审计、dumpsys 摘要、内存/电池信息、bugreport、流式 logcat 任务
device_control	模拟器控制、应用卸载/清除、intent、权限、点击/滑动/输入、按标签点击、文件推送/拉取、小型操作流程、流程录制
perfetto	轨迹捕获和 Trace Processor 分析（卡顿、CPU、争用、binder 延迟，……）
visuals	像素差异、视觉报告、黄金图更新
storage	针对可调试应用的只读 SQLite、SharedPreferences 和文件树
network_experimental	仅限模拟器的 mitmproxy 捕获和脱敏 HAR 查询（需要你自己的调试 CA）

危险操作（卸载、清除数据、代理安装、覆盖黄金图等）需要在配置中具备相应能力，并且在调用时设置 confirmDestructive=true。能力才是真正的边界——confirmDestructive 用于防止意外调用，而非恶意调用，因为该参数由 Agent 提供。参见威胁模型。

报告包包含能力摘要：公开了哪些组、启用了哪些能力，以及还需要安装哪些内容（adb、trace processor、mitmproxy 等）。此摘要仅供参考，不会改变就绪度评分。

完整工具列表和能力 ID：docs/security-and-permissions.md。

快速开始

**前置条件：**Node 18+（仅启动器在安装时需要）。如果你有 JDK 17+，则会使用它——它可以位于 PATH 中、由 JAVA_HOME 指定，或由 DROIDAGENT_JAVA 指定；否则会下载一次固定版本的 Eclipse Temurin JRE，验证 SHA-256 后缓存到 ~/.droidagentkit/jre。可选：设备工具需要 Android adb / platform-tools；设置 ANDROID_HOME 或在用户策略（~/.droidagentkit/policy.yaml）中配置 adbPath。运行 doctor 检查以上所有项目。

@droidagentkit/launcher npm 包首次运行时，会从 GitHub Releases 下载并缓存匹配的 droidagent-cli jar，并在执行前验证其 SHA-256。

npx -y @droidagentkit/launcher --version

直接运行以启动 MCP 服务，或将任何 CLI 命令直接传递给它：

npx -y @droidagentkit/launcher doctor
npx -y @droidagentkit/launcher init --profile device-control
npx -y @droidagentkit/launcher audit --project /path/to/android --write-agents

将 Agent 的 MCP 配置直接指向它，例如用于 Claude Code：

claude mcp add droidagentkit -- npx -y @droidagentkit/launcher

或者一键安装：

其他安装方式

brew install iVamsi/android-agent-kit/droidagent

每个版本还会附带一个 .mcpb bundle。将其放入支持一键安装的 MCP 主机中，服务便会自动注册。该 bundle 仅包含启动器——JVM 服务，以及在你没有 JDK 时所需的、经过验证的 Temurin JRE，都会在首次运行时获取——因此下载大小约为 10 KB，而非约 160 MB。

从源代码构建

如果你要贡献代码，或想运行尚未发布的版本：

./gradlew :cli:installDist
./cli/build/install/droidagent/bin/droidagent install-mcp

为你的 Agent 注册一次即可（Codex、Claude Code、Cursor、Zed、VS Code、Android Studio，……）。 使用 install-mcp --dry-run 预览，而不写入文件。对于 Android Studio，如果要配置同一文件夹下的多个项目：

droidagent install-mcp --targets android-studio --projects-root ~/Developer/StudioProjects

详情和各主机的配置路径：docs/easy-mcp-installation.md。 安全模型和完整的工具表： docs/security-and-permissions.md。 CLI 参考和故障排查：docs/cli-reference.md、docs/troubleshooting.md。

在聊天中试用

运行 install-mcp 后，打开一个 Android 项目并提出此类请求：

• “使用 DroidAgentKit 检查这个 Android 项目。”
• “为 app 模块运行安全的单元测试。”
• “审查此仓库是否已准备好供 Agent 使用，并编写 AGENTS.md。”
• “捕获 logcat 并排查崩溃原因。”（存在 R8 映射文件时，会自动对发布版本进行反混淆）
• “自上次构建以来，APK 为什么变大了？”
• “app 的 SQLite 架构包含什么？”（需启用 storage 和 app_data_read）
• “捕获 Perfetto 跟踪并总结帧卡顿情况。”（需启用 perfetto）
• “把你刚才执行的操作记录为可供我重放的流程。”（需启用 device_control）

你描述目标；Agent 会从启动时获取的工具列表中选择工具。

工作原理

1. Agent 启动 droidagent serve-mcp --transport stdio --project auto（或连接 Android Studio 在 macOS 上使用的 localhost HTTP 端点）。
2. MCP 握手（先执行 initialize，再执行 tools/list）。
3. Agent 通过 tools/call 调用 android_* 工具。你无需手动调用。
4. --project auto 会依次从 CLAUDE_PROJECT_DIR、CODEX_WORKSPACE / CODEX_PROJECT_DIR、GEMINI_PROJECT_DIR / GEMINI_WORKSPACE、CURSOR_PROJECT_DIR / CURSOR_WORKSPACE、PWD，然后是 cwd 中解析当前项目 — 一次安装即可供用户的多个项目使用。

非 Android Studio 主机还可使用可选的资源和工作流提示词。相关工具列表会包含 readOnlyHint 和 destructiveHint 等提示。

不通过 Agent 使用 CLI

droidagent inspect --project /path/to/android --format markdown
droidagent audit --project /path/to/android --write-agents
droidagent audit --project /path/to/android --redact-public
droidagent devices --format json
droidagent serve-mcp --transport stdio --project auto

运行 droidagent --help 或 droidagent <command> --help 查看标志。

生成配置文件

droidagent init                          # interactive: six yes/no prompts explaining risk per area
droidagent init --profile device-control # non-interactive, for scripted setup
droidagent init --profile full           # everything, including storage and network capture
droidagent init --list-profiles          # see all profile names without writing anything

默认仅启用 core 工具组（安全、只读）。droidagent init 是启用更多工具组的最快方式，无需手动编写 .droidagentkit/config.yaml — 请参阅 docs/security-and-permissions.md，了解各工具组和能力实际授予 Agent 的权限。

配置

在 Android 项目根目录中放置 .droidagentkit/config.yaml，以配置 Gradle 允许列表、adb 权限、能力标志、脱敏模式和报告输出路径。运行 audit --write-agents 时，审计器可以生成一份安全的默认配置。

状态

Alpha。MCP 工具名称和架构视为稳定，但随着我们从实际使用中积累经验，行为会逐步收紧。无遥测。核心工作流不依赖云服务。

更多文档

• 安全与权限 — 能力、工具组、破坏性操作、提示词注入场景示例
• 兼容性 — 哪些内容稳定、哪些可能变化、1.0 退出标准
• 轻松安装 MCP — 各主机的设置方法
• CLAUDE.md — 供贡献者参考的构建命令和架构说明