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

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

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

---

📋 目录

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

---

第一阶段：环境准备

1. 安装 Node.js（≥ 20.20）

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

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

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

2. 安装 Python 3（≥ 3.8）

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

# 检查 Python 版本
python3 --version

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

3. 全局安装 android-context-builder

npm install -g android-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，请设置环境变量：

export FIGMA_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 对话框中输入）：

命令	作用
/init	项目初始化，让 AI 理解整体结构
/plan	进入计划模式，先规划再编码
/review	对当前修改进行代码审查

16. 持续迭代

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

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

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

⚠️ 注意事项

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

python3 -m pip install python-docx requests

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

📊 完整流程速查表

阶段	步骤	关键操作	产出
环境准备	1-2	安装 Node.js 20+、Python 3.8+	运行环境
	3	npm install -g android-context-builder	CLI 工具
	4	Android Studio 安装 CC GUI 插件	IDE 插件
项目初始化	5-6	cd 项目根目录 → setup	配置文件
	7	接口文档 .md 放入 docs/	本地文档
拉取上下文	8-9	修改 config.json、设置 Figma Token（可选）	配置完成
	10	android-context-builder run	project_context.json
配置 MCP	11-12	安装 MCP Server 插件，配置 CC GUI 的 MCP	AI 可读上下文
开始开发	13-15	在 CC GUI 中输入自然语言指令	AI 自动生成代码
迭代优化	16	更新文档 → 重新 run → 继续对话	持续交付