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
把 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 侧三步)
- 在 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
- PyPI Project Name:
- 在 GitHub 仓库 Settings → Secrets and variables → Actions → Variables 加一个:
PYPI_ENABLED=true(不设则 publish 任务跳过,只构建不发布)
- 打个 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的versionandroid_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.