Skip to main content

AIGC: Label: "1" ContentProducer: 001191440300708461136T1XGW3 ProduceID: df8dd3956ae26494b640a4aee7d3401d_98f865c7e0a311f19919525400638852 ReservedCode1: 86Pkik2YVSt+j/nqlpAeuQL+NAdIB0/bHycyAJqyR3G8mOjsYz8CeFBsH6jh6dkFK4xDRhmtrbzTe/TqnTk6jD+AN2hGlOeNh+iC3LBTEexqVFe7IietsJyymopw95x4txvhkvpwaJn2kFwJc9wcowBpj3y6i1doENEd1HHhmi+Jo1pBOOMHHpuc9t4= ContentPropagator: 001191440300708461136T1XGW3 PropagateID: df8dd3956ae26494b640a4aee7d3401d_98f865c7e0a311f19919525400638852 ReservedCode2: 86Pkik2YVSt+j/nqlpAeuQL+NAdIB0/bHycyAJqyR3G8mOjsYz8CeFBsH6jh6dkFK4xDRhmtrbzTe/TqnTk6jD+AN2hGlOeNh+iC3LBTEexqVFe7IietsJyymopw95x4txvhkvpwaJn2kFwJc9wcowBpj3y6i1doENEd1HHhmi+Jo1pBOOMHHpuc9t4=

android-build-agent

CI

把 Android 构建能力做成可被 AI Agent 调用的工程:一套 Python 实现,两个入口。

入口 给谁用 形态
MCP 服务 Claude Desktop / Cursor / Cline / 自研 Agent stdio + JSON-RPC 2.0,4 个工具
CLI 只能跑 shell 的 Agent android-build-agent build shiye --json,stdout 单行 JSON

设计原则:Agent 只能选项目和白名单任务,不能传任意命令;所有工具链、缓存、产物都落在 root 目录,不碰系统盘。

一、目录结构

android-build-agent/
├─ profiles.json              # 项目清单(唯一需要你改的文件)
├─ pyproject.toml             # 可 pip install -e .
├─ README.md
└─ android_build_agent/
   ├─ config.py               # profiles 解析 + 任务白名单 + 路径推导
   ├─ toolchain.py            # JDK17 / Gradle / Android SDK 下载安装(跨平台、幂等)
   ├─ builder.py              # 拉源码、写受控 gradle.properties、跑 Gradle、收集 APK + sha256
   ├─ cli.py                  # list / install / build / artifacts
   └─ mcp_server.py           # MCP stdio 服务

安装后目录(默认 root):

<root>/
├─ toolchain/   jdk-17、gradle-<版本>、sdk
├─ gradle-home/ 依赖缓存(设 GRADLE_USER_HOME,不落 C 盘)
├─ tmp/         构建临时目录
├─ projects/<name>/  源码与 build/
├─ out/         APK + <name>-last-build.json(最近一次结果,供 Agent 读取)
└─ downloads/   安装包缓存(可删)

默认 root:Windows 上优先 E:\android-build(没有 E 盘则 D 盘),macOS / Linux 用 ~/android-build;可用 --root 或 profiles.json 里的 root 覆盖。

二、安装

# 从 PyPI(发布后可用)
pip install android-build-agent

# 从源码(开发用)
pip install -e .

# 或者不装,直接跑
python -m android_build_agent.cli list --json
python -m android_build_agent.mcp_server

三、MCP 接入

3.1 Claude Desktop

claude_desktop_config.json(Windows 在 %APPDATA%\Claude\):

{
  "mcpServers": {
    "android-build": {
      "command": "python",
      "args": ["-m", "android_build_agent.mcp_server"],
      "cwd": "E:\\android-build\\android-build-agent"
    }
  }
}

3.2 Cursor / Cline / Continue

同样是「command + args + cwd」三件套,填 python -m android_build_agent.mcp_server,工作目录指到本工程根(profiles.json 所在目录)。若用 pip 安装过,可直接:

{ "command": "android-build-agent-mcp", "args": [] }

3.3 工具清单

工具 参数 返回
android_list_profiles 无 项目列表:repo、branch、task、SDK 版本、工具链是否就绪
android_install_toolchain profile(必填)、root、sdkPlatforms、buildTools、gradleVersion、buildAfter JDK/Gradle/SDK 路径;buildAfter=true 时附构建结果
android_build profile(必填)、task、clean、updateSource、timeoutSec ok / exitCode / durationSec / apks[](路径、大小、sha256)/ logTail
android_get_build_result profile(必填) 最近一次构建结果(读 out/<name>-last-build.json)

调用示例(Agent 视角):

{"name": "android_build", "arguments": {"profile": "shiye", "clean": true}}

返回(节选):

{
  "ok": true, "exitCode": 0, "durationSec": 76.4,
  "apks": [{"path": "E:\\android-build\\out\\shiye-app-debug.apk", "size": 57147133,
            "sha256": "6c9eec…", "variant": "debug"}],
  "logTail": "BUILD SUCCESSFUL in 1m 15s"
}

四、CLI 接入(给只有 shell 的 Agent)

android-build-agent list --json
android-build-agent install shiye --build --json
android-build-agent build shiye --clean --json
android-build-agent artifacts shiye --json

规则:加了 --json,stdout 只有一行 JSON,日志全部走 stderr,Agent 直接 json.loads(stdout) 即可。退出码 0 = 成功,1 = 构建失败,2 = 参数错误。

五、安全边界(为什么敢给 Agent 调用)

边界 实现
只能构建登记过的项目 profiles.json 白名单;未知 profile 直接报错并列出可用项
不能执行任意命令 task 只允许 assemble* / bundle* / lint* / compileDebugKotlin / clean,可带 :module: 前缀;含 ; & | $ \ \n` 直接拒绝
不会写到系统目录 所有路径都由 root 派生;不调用 sudo / 管理员,不改系统环境变量与注册表
不碰项目原有配置 gradle.properties 只替换/追加 5 个受控键(堆、in-process、并行、workers、androidX),其余原样保留
可追溯 每次构建写 out/<name>-last-build.json:耗时、退出码、APK sha256、日志尾部

六、profiles.json

{
  "defaults": { "sdkPlatforms": ["android-33"], "buildTools": ["33.0.2"],
                "gradleVersion": "7.6.3", "task": "assembleDebug" },
  "projects": {
    "shiye": { "repo": "https://github.com/Tommyface/shiye-android.git", "branch": "main" },
    "myapp": { "repo": "https://github.com/me/myapp.git", "branch": "main",
               "sdkPlatforms": ["android-34"], "buildTools": ["34.0.0"], "gradleVersion": "8.7" },
    "bigapp": { "repo": "https://github.com/me/bigapp.git",
                "sdkPlatforms": ["android-35"], "buildTools": ["35.0.0"],
                "extraSdkPackages": ["ndk;26.1.10909125", "cmake;3.22.1"],
                "gradleVersion": "8.7", "task": ":app:assembleDebug" }
  }
}

路径优先级:命令行参数 > profile > defaults > 平台默认。

AGP ↔ Gradle:脚本会从 build.gradle / libs.versions.toml 读 AGP 版本,低于建议值时在结果里给 hint(不阻断构建)。

七、给 Agent 的系统提示(可直接粘)

你有 Android 构建能力,通过 android_* 工具调用。
- 先 android_list_profiles 看有哪些项目;
- 构建前若工具链未就绪,先 android_install_toolchain;
- 构建用 android_build(profile, clean?),失败时看返回的 logTail / errorTail;
- 不要尝试传自定义 shell 命令,task 只能是 assembleDebug/assembleRelease/bundleRelease/lint 等。

八、和 PowerShell 脚本的关系

场景 用什么
自己在 Windows 上双击编译 shiye-install.ps1 / android-install.ps1 那套 bat
Agent 自动构建、CI 里调用、跨平台 本工程(Python)

两者共用同一份 profiles.json 结构,root 目录也一致,可以混用:Agent 构建产出的 APK 同样落在 out/。

九、已知限制

  • 只支持 Gradle 项目(不处理 Ant / Bazel / Flutter 外壳)。
  • Release 签名需要项目自己配置好 signingConfigs,本工具不代管密钥。
  • 首次安装工具链需要下载约 1.1 GB(JDK 320 MB + Gradle 130 MB + SDK 约 600 MB),失败会自动换镜像重试。
  • MCP 走 stdio,没有网络端口;需要远程调用时请套 SSH 或自建 HTTP 网关。 (内容由AI生成,仅供参考)

十、测试与 CI

python tests/test_config.py     # 14 个单测:任务白名单、profile 解析、路径派生、注入拦截
python tests/smoke_mcp.py       # 起真实 stdio 进程跑 MCP 握手 + 工具调用 + 安全拦截

CI(.github/workflows/ci.yml)在 push / PR 时跑:Python 3.10 与 3.12 双版本(代码本身兼容 3.9) → 语法检查 → 单测 → MCP 冒烟 → CLI 冒烟 → 注入型 task 回归。

新增工具时,记得同步更新 tests/smoke_mcp.py 里的工具名断言,否则 CI 会红。

十一、发布到 PyPI

.github/workflows/publish.yml 已配好,采用 Trusted Publishing(OIDC),不需要在仓库里存 API Token。

首次配置(PyPI 侧三步)

  1. 在 https://pypi.org/manage/account/publishing/ 添加 pending publisher:
    • PyPI Project Name:android-build-agent
    • Owner:Tommyface
    • Repository name:android-build-agent
    • Workflow name:publish.yml
    • Environment name:pypi
  2. 在 GitHub 仓库 Settings → Secrets and variables → Actions → Variables 加一个:
    • PYPI_ENABLED = true(不设则 publish 任务跳过,只构建不发布)
  3. 打个 tag 触发:
git tag v1.0.1 && git push origin v1.0.1

流水线会先构建 sdist + wheel(并把 wheel 内的文件清单打印出来),再用 pypa/gh-action-pypi-publish 发布。发布成功后:

pip install android-build-agent

本地验证打包(可选,需要 pip)

pip install build
python -m build          # 产出 dist/android_build_agent-1.0.1-py3-none-any.whl 与 .tar.gz
python -m zipfile -l dist/android_build_agent-1.0.1-py3-none-any.whl

版本号怎么改

两处必须同步:

  • pyproject.toml 的 version
  • android_build_agent/__init__.py 的 __version__

mcp_server.py 的 serverInfo.version 直接读 __version__,不用另改。

Metadata

Release files for android-build-agent 1.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for android-build-agent 1.0.3
File Size Uploaded Provenance Actions
android_build_agent-1.0.3.tar.gz 24.9 kB With provenance Details for android_build_agent-1.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for android-build-agent 1.0.3
File Interpreter ABI Platform Actions
android_build_agent-1.0.3-py3-none-any.whl Python 3 none any Details for android_build_agent-1.0.3-py3-none-any.whl

Total release size: 48.1 kB

Release files / android_build_agent-1.0.3.tar.gz

Download URL android_build_agent-1.0.3.tar.gz
Size 24.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4fe6ff1bb1240f2df889e497731e7d9512087bb6775e744801c7d2e25d670386
BLAKE2b-256 checksum
How to use checksums
a34520121fdf30fd376f84198e272fbed29c1214ef87b64f8d7f8bfaea275a38
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / android_build_agent-1.0.3-py3-none-any.whl

Download URL android_build_agent-1.0.3-py3-none-any.whl
Size 23.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d96a4eb53f3df463daba2febdf7b51bc66841741e08c217f633ce57f24d16036
BLAKE2b-256 checksum
How to use checksums
87b2813d8d2bda1740be0b9952f993898ab7c0066ce32ee08c415146dde4c0c1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for android-build-agent 1.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for android_build_agent-1.0.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page