Android 自动化开发方案（基于本地接口文档）

Android 自动化开发方案（基于本地接口文档）

本方案适用于：使用 Android Studio + CC GUI 插件 + android-context-builder，通过本地 Markdown 接口文档实现从设计到代码的自动化开发流程。

📋 目录

• 环境准备
• 项目初始化
• 配置与拉取上下文
• 配置 AI 工具（MCP 服务）
• 开始自动化开发
• 持续迭代
• 注意事项

第一阶段：环境准备

1. 安装 Node.js（≥ 20.20）

android-context-builder依赖 Node.js 20.20 或更高版本。

# 检查当前版本node-vnpm-v

若版本过低，请到 nodejs.org 下载安装最新的 LTS 版本。

2. 安装 Python 3（≥ 3.8）

用于解析接口文档和同步 Bean 数据类。

# 检查 Python 版本python3--version

若未安装，请根据操作系统安装 Python 3.8+。

3. 全局安装 android-context-builder

npminstall-gandroid-context-builder

安装后验证：

android-context-builder--version

4. 在 Android Studio 中安装 CC GUI 插件

打开 Android Studio，进入 File → Settings（macOS：Android Studio → Preferences）。

选择 Plugins → Marketplace。

搜索 “CC GUI (Claude or Codex)”。

点击 Install，安装完成后重启 Android Studio。

第二阶段：项目初始化

5. 进入 Android 项目根目录

cd你的Android项目根目录

确保项目是标准的 Android Gradle 工程（包含 app/src/main/java/… 等目录）。

6. 初始化 android-context-builder

android-context-builder setup

该命令会在项目根目录生成配置文件 android-context.config.json。

7. 将接口文档放入 docs/ 目录

在项目根目录下创建（或确认存在） docs/ 文件夹。

将从钉钉导出的接口文档（Markdown 格式，即 .md 文件）放入该目录。

如果有多份文档，可全部放入，工具会自动扫描并整合。

工具也支持 .docx 格式，但推荐使用 .md 以便版本控制。

第三阶段：配置与拉取上下文

8. 修改配置文件 android-context.config.json

编辑项目根目录下的 android-context.config.json，根据实际项目填写关键字段：

{// ============================================================// 一、接口文档配置// ============================================================/** * Swagger/OpenAPI 文档的 JSON 地址 * - 如果有后端提供的在线 Swagger 地址，填写后工具可直接拉取 * - 如果没有或不想用，留空 ""，工具会读取 docs/ 目录下的 .md/.docx 文件 * - 推荐：先用 docs/ 目录方式，更稳定可控 */"swaggerUrl":"",// ============================================================// 二、项目基础信息// ============================================================/** * 应用包名（Application ID） * - 对应你项目 build.gradle 中的 applicationId * - 用于生成代码时的包路径 * - 示例：com.yourcompany.client_android */"appPackage":"com.yourcompany.client_android",// ============================================================// 三、数据模型（Bean）生成配置// ============================================================/** * Bean 数据类的根目录 * - 相对于 app/src/main/java/ 包路径下的目录名 * - 如果填写 "model"，则生成到 app/src/main/java/com/xxx/xxx/model/ * - 如果你的 Bean 分散在各模块，可指定主模块的目录 */"beanDir":"model",/** * 请求 Bean 的子目录 * - 会在 beanDir 下创建 request 子包 * - 示例：生成到 model/request/ * - 建议保持与项目现有结构一致 */"beanRequestSubdir":"request",/** * 响应 Bean 的子目录 * - 会在 beanDir 下创建 response 子包 * - 示例：生成到 model/response/ * - 建议保持与项目现有结构一致 */"beanResponseSubdir":"response",// ============================================================// 四、网络接口代码配置（用于 diff-api 功能）// ============================================================/** * ApiService 接口文件的完整路径 * - 用于 diff-api 功能：对比接口文档与现有代码的差异 * - 多模块项目：填写 base 模块或主要业务模块的 ApiService.kt * - 如果不需要 diff-api 功能，留空 "" 即可 * - 不影响核心的上下文构建和代码生成能力 */"apiServicePath":"",// ============================================================// 五、差异对比排除配置// ============================================================/** * diff-api 对比时排除的接口 Tag * - 这些 Tag 下的接口不会被对比 * - 适用于：废弃接口、测试接口、非业务接口等 */"diffExcludeTags":["im-controller","系统配置信息（非API）"],// ============================================================// 六、文档与原型目录// ============================================================/** * 需求文档/接口文档存放目录 * - 支持 .md（Markdown）和 .docx（Word）格式 * - 执行 android-context-builder run 时自动扫描 * - 建议：接口文档、任务文档、PRD 都放这里 */"docsDir":"./docs",/** * 原型/设计稿存放目录（预留） * - 目前为预留字段，未来可能支持更多原型格式 */"prototypeDir":"./prototypes",// ============================================================// 七、Bean 同步模式// ============================================================/** * Bean 同步模式 * - "update" = 增量更新，保留已有字段，只增不减 * - "overwrite" = 全量覆盖，完全按文档重新生成 * - 推荐 "update"，避免误删手动添加的字段 */"beanSyncMode":"update",// ============================================================// 八、UI 框架配置（核心切换点）// ============================================================"ui":{/** * 平台 UI 框架类型 * * ✅ 当前配置（生成 Kotlin + XML/View 代码）： * "platform": "views" * * ⚠️ 如需切换到 Jetpack Compose，改为： * "platform": "compose" * * 影响范围： * - Figma 转 UI 代码的风格 * - 生成的布局文件类型 * - AI 生成代码时的推荐方案 */"platform":"views",/** * 注释说明（不影响运行，仅供阅读） */"comment":"views = XML/ViewBinding; compose = Jetpack Compose"},// ============================================================// 九、Figma MCP 服务配置（用于 Figma 设计稿转代码）// ============================================================"figmaMcp":{/** * Figma 输出平台类型 * * ✅ 当前配置（生成 XML 布局）： * "outputPlatform": "views" * * ⚠️ 如需切换到 Jetpack Compose，改为： * "outputPlatform": "compose" * * 注意：此值建议与 ui.platform 保持一致 */"outputPlatform":"views",/** * Figma Skill 存放目录 * - setup 时自动创建，一般不需要修改 */"skillsDir":"./figma-skills",/** * 图片资源导出目录 * - "." 表示导出到项目根目录 * - 通常会生成到 res/drawable-xxx/ 下 */"imageDir":".",/** * 导出的图片密度 * - 支持的密度：ldpi, mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi * - 建议至少包含 xxhdpi，适配主流设备 */"defaultDensities":["xxhdpi"]},// ============================================================// 十、其他控制开关// ============================================================/** * 是否自动生成 ApiService 接口代码 * - true = 根据接口文档自动生成 Retrofit ApiService * - false = 不自动生成，由 AI 按需生成 * - 建议 false，让 AI 更灵活地处理 */"generateApiService":false}

配置说明：

1. 接口文档配置：swaggerUrl用于在线 Swagger 文档，如无则留空，工具会读取本地 docs/ 目录文档
2. 项目基础信息：appPackage必须与项目的applicationId一致
3. 数据模型配置：beanDir、beanRequestSubdir、beanResponseSubdir决定了生成的 Kotlin 数据类存放位置
4. UI 框架配置：ui.platform是关键切换点，"views"生成 XML/ViewBinding 代码，"compose"生成 Jetpack Compose 代码
5. Bean 同步模式：推荐"update"模式，避免误删手动添加的字段
6. 其他配置：根据项目实际情况调整，大部分配置都有合理的默认值

保存配置文件后，继续执行后续步骤。

9. （可选）配置 Figma 访问令牌

如果后续需要使用 Figma 设计稿还原 UI，请设置环境变量：

exportFIGMA_API_KEY=figd_xxxxxxxx

重要：Token 只放在环境变量中，不要写入配置文件或提交到 Git。

10. 拉取项目上下文

android-context-builder run

执行后，工具会：

• 扫描 docs/ 目录下的所有 .md / .docx 文档。
• 整合生成 project_context.json 文件（供 AI 工具读取的知识库）。

如果只有 Swagger 格式的接口文档，也可以使用：

android-context-builder run --swagger-only

第四阶段：配置 AI 工具（MCP 服务）

这一步让 CC GUI 能够读取 project_context.json 并执行自动化任务。

11. 在 Android Studio 中安装 MCP Server 插件

打开 Android Studio → Plugins → Marketplace。

搜索 “MCP Server”（ID：26071）。

点击 Install，安装后重启 IDE。

重启后，在 Android Studio 右下角会出现 MCP 服务图标，点击启动（默认本地端口）。

12. 配置 CC GUI 的 MCP 连接

CC GUI 支持通过 MCP（Model Context Protocol）扩展 AI 能力。在 CC GUI 的设置界面中，找到 MCP 服务器管理，添加如下配置（参考格式）：

{"mcpServers":{"android-context":{"command":"android-context-builder","args":["mcp"]}}}

具体配置路径请查阅 CC GUI 插件设置中的 MCP Servers 选项。

13. （可选）安装 Cursor CLI Terminal 插件

如果想在 Android Studio 内直接使用 Cursor 的对话能力：

打开 Plugins → Marketplace，搜索 “Cursor CLI Terminal”（ID：28562）。

安装并重启 Android Studio。

顶部菜单栏选择 Tools → Focus Cursor CLI Terminal，侧边栏会出现 Cursor 对话窗口。

第五阶段：开始自动化开发

14. 在 CC GUI 中编写开发计划

打开 CC GUI 侧边栏（通常在 Android Studio 右侧或底部），在对话框中用自然语言描述你要实现的功能。

由于已经执行过 android-context-builder run，AI 能够自动读取 project_context.json 中的接口文档和需求文档，无需手动提供。

示例指令：

“根据项目 docs/ 中的接口文档，为‘用户登录’接口生成 Retrofit 的 ApiService 代码和对应的 Kotlin 数据类。”

15. 执行自动化开发

CC GUI 通过其 Agent 系统 可以自动执行多步骤任务，例如：

• 读取接口文档
• 生成数据模型（Bean）
• 编写网络请求层（Retrofit ApiService）
• 生成 UI 布局

常用技能（Skills）命令（在 CC GUI 对话框中输入）：

16. 持续迭代

当接口文档更新后，重新导出 .md 文件覆盖 docs/ 目录，然后再次执行 android-context-builder run 更新上下文。

在 CC GUI 中继续通过对话让 AI 修改或优化代码。

所有代码变更会以 DIFF 视图展示，支持逐行审查和一键接受/拒绝。

⚠️ 注意事项

• 首次运行 run 可能会自动安装 python-docx 依赖，如果失败可手动执行：

python3-mpipinstallpython-docx requests

• Figma Token 务必使用环境变量，不要硬编码到任何项目文件中。
• 接口文档格式：推荐使用 .md（Markdown），以便版本控制和 AI 解析；.docx 也支持，但解析可能稍慢。
• MCP 服务是核心：android-context-builder run 只是生成上下文数据，真正让 AI 能读懂项目，依赖 MCP 服务的正确配置。
• 网络环境：如果公司网络受限，可能需要配置代理或镜像源，请提前确保 npm 和 pip 能正常访问外网。

📊 完整流程速查表