Android 自动化开发方案基于本地接口文档本方案适用于使用 Android Studio CC GUI 插件 android-context-builder通过本地 Markdown 接口文档实现从设计到代码的自动化开发流程。 目录环境准备项目初始化配置与拉取上下文配置 AI 工具MCP 服务开始自动化开发持续迭代注意事项第一阶段环境准备1. 安装 Node.js≥ 20.20android-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-buildernpminstall-gandroid-context-builder安装后验证android-context-builder--version4. 在 Android Studio 中安装 CC GUI 插件打开 Android Studio进入 File → SettingsmacOSAndroid 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-builderandroid-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],// // 六、文档与原型目录// /** * 需求文档/接口文档存放目录 * - 支持 .mdMarkdown和 .docxWord格式 * - 执行 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}配置说明接口文档配置swaggerUrl用于在线 Swagger 文档如无则留空工具会读取本地 docs/ 目录文档项目基础信息appPackage必须与项目的applicationId一致数据模型配置beanDir、beanRequestSubdir、beanResponseSubdir决定了生成的 Kotlin 数据类存放位置UI 框架配置ui.platform是关键切换点views生成 XML/ViewBinding 代码compose生成 Jetpack Compose 代码Bean 同步模式推荐update模式避免误删手动添加的字段其他配置根据项目实际情况调整大部分配置都有合理的默认值保存配置文件后继续执行后续步骤。9. 可选配置 Figma 访问令牌如果后续需要使用 Figma 设计稿还原 UI请设置环境变量exportFIGMA_API_KEYfigd_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”ID26071。点击 Install安装后重启 IDE。重启后在 Android Studio 右下角会出现 MCP 服务图标点击启动默认本地端口。12. 配置 CC GUI 的 MCP 连接CC GUI 支持通过 MCPModel 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”ID28562。安装并重启 Android Studio。顶部菜单栏选择 Tools → Focus Cursor CLI Terminal侧边栏会出现 Cursor 对话窗口。第五阶段开始自动化开发14. 在 CC GUI 中编写开发计划打开 CC GUI 侧边栏通常在 Android Studio 右侧或底部在对话框中用自然语言描述你要实现的功能。由于已经执行过 android-context-builder runAI 能够自动读取 project_context.json 中的接口文档和需求文档无需手动提供。示例指令“根据项目 docs/ 中的接口文档为‘用户登录’接口生成 Retrofit 的 ApiService 代码和对应的 Kotlin 数据类。”15. 执行自动化开发CC GUI 通过其 Agent 系统 可以自动执行多步骤任务例如读取接口文档生成数据模型Bean编写网络请求层Retrofit ApiService生成 UI 布局常用技能Skills命令在 CC GUI 对话框中输入命令作用/init项目初始化让 AI 理解整体结构/plan进入计划模式先规划再编码/review对当前修改进行代码审查16. 持续迭代当接口文档更新后重新导出 .md 文件覆盖 docs/ 目录然后再次执行 android-context-builder run 更新上下文。在 CC GUI 中继续通过对话让 AI 修改或优化代码。所有代码变更会以 DIFF 视图展示支持逐行审查和一键接受/拒绝。⚠️ 注意事项首次运行 run 可能会自动安装 python-docx 依赖如果失败可手动执行python3-mpipinstallpython-docx requestsFigma Token 务必使用环境变量不要硬编码到任何项目文件中。接口文档格式推荐使用 .mdMarkdown以便版本控制和 AI 解析.docx 也支持但解析可能稍慢。MCP 服务是核心android-context-builder run 只是生成上下文数据真正让 AI 能读懂项目依赖 MCP 服务的正确配置。网络环境如果公司网络受限可能需要配置代理或镜像源请提前确保 npm 和 pip 能正常访问外网。 完整流程速查表阶段步骤关键操作产出环境准备1-2安装 Node.js 20、Python 3.8运行环境3npm install -g android-context-builderCLI 工具4Android Studio 安装 CC GUI 插件IDE 插件项目初始化5-6cd 项目根目录 → setup配置文件7接口文档 .md 放入 docs/本地文档拉取上下文8-9修改 config.json、设置 Figma Token可选配置完成10android-context-builder runproject_context.json配置 MCP11-12安装 MCP Server 插件配置 CC GUI 的 MCPAI 可读上下文开始开发13-15在 CC GUI 中输入自然语言指令AI 自动生成代码迭代优化16更新文档 → 重新 run → 继续对话持续交付