android-context-builder

v2.2.1

Published

9 days ago

Figma + Swagger + 需求文档 → Android AI 上下文；内置 figma-android-mcp 高保真 UI 还原

Downloads

532

0High
0Medium
0Low

carlliu_333

android mcp figma figma-android-mcp swagger cursor claude viewbinding xml jetpack-compose

android-context-builder 使用手册

把 Swagger 接口文档 + 产品需求文档 + Figma 设计稿 接入 Cursor / Claude 等 AI 工具，让 Agent 写 Android 代码时有据可依，而不是猜接口、猜布局、猜需求。

npm install -g android-context-builder
cd 你的Android项目根目录
android-context-builder setup
# 改 android-context.config.json
android-context-builder run --swagger-only

这个工具能做什么

| 你想做的事 | 用什么 | |-----------|--------| | 拉接口文档、需求文档进项目 | run / run --swagger-only | | 让 Agent 查某个接口、读需求 | MCP android-project | | Swagger 和现有 ApiService 差在哪 | diff-api | | 按文档同步 Kotlin Bean | sync-beans | | 按 Figma 高保真还原 UI | MCP figma-android-mcp + Skill | | Figma 没出稿，先按原型出页面 | prototypes/ 目录 + MCP list_prototypes + Skill |

工具分两层：

| 组件 | 作用 | |------|------| | CLI | 拉文档、写 project_context.json、同步 Bean、对比 ApiService | | MCP | 在 Cursor 里直接查接口 / 读需求 / 拉 Figma 节点树与切图 |

v2 起内置 figma-android-mcp。Figma UI 必须走 get_figma_node（0.5.3+ 统一入口）+ Skill，旧版 get_figma_frame 已弃用。

1. 环境要求

1.1 本机软件

| 项 | 要求 | 用来干什么 | |----|------|-----------| | Node.js | ≥ 20.20 | CLI、figma-android-mcp（0.5.3+ 要求） | | npm | 随 Node 安装 | 全局安装本包 | | Python 3 | 3.8+ | 拉 Swagger、解析 docx、Bean 同步、MCP | | 网络 | 能访问 Swagger；做 UI 时还要能访问 Figma API | 拉取在线文档 |

检查：

node -v
npm -v
python3 --version

首次 run 会自动装 python-docx。失败时手动：

python3 -m pip install python-docx requests

1.2 密钥与地址

| 项 | 怎么拿 | 何时需要 | |----|--------|---------| | Swagger URL | 问后端，或 Swagger UI 里找 JSON 地址 | 始终需要，写入 config | | Figma Token | Figma → Settings → Personal access tokens，figd_ 开头 | 仅还原 Figma UI 时需要 |

export FIGMA_API_KEY=figd_xxxxxxxx

Token 只放环境变量，不要写进 Git。

1.3 项目侧要求

标准 Android Gradle 工程（有 app/src/main/java/...）
docs/ 下至少一个 .md 或 .docx 需求文档
用 diff-api 时：已有 Retrofit 接口文件，并在 config 填 apiServicePath
用 Bean 同步时：Bean 放在 app/src/main/java/{appPackage}/{beanDir}/ 下（见第 10 节）

1.4 编辑器

Cursor（推荐）或支持 MCP 的 Claude Code。需要能加载项目根目录的 .mcp.json。

2. 安装与升级

npm install -g android-context-builder
android-context-builder --version

升级后：

npm install -g android-context-builder@latest
android-context-builder setup-mcp   # 刷新 .mcp.json
# Cursor → Reload MCP

不用单独装 figma-android-mcp，已打包在本工具里。

3. 五分钟上手

在 Android 项目根目录（与 app/ 同级）执行。

① 初始化

android-context-builder setup

会创建 android-context.config.json、复制 Figma Skill、写入 .mcp.json（注册 android-project + figma-android-mcp）。

② 改配置

最少填两项：

{
  "swaggerUrl": "https://你的域名/v2/api-docs",
  "appPackage": "com.example.yourapp"
}

常用追加项：

{
  "apiServicePath": "./app/src/main/java/com/example/yourapp/network/ApiService.kt",
  "beanDir": "bean",
  "beanRequestSubdir": "request",
  "beanResponseSubdir": "response"
}

③ 放需求文档

mkdir -p docs
# 复制 .md 或 .docx 到 docs/

④ 拉上下文（推荐）

android-context-builder run --swagger-only

生成 project_context.json。

⑤ 启用 MCP

Cursor → Settings → MCP → Reload。

⑥ 验证

对 Agent 说：

调用 get_project_overview，再用 get_api_endpoints 查订单相关接口。

4. 配置文件

路径：android-context.config.json（项目根目录）

4.1 完整模板

{
  "swaggerUrl": "https://your-api-server.com/v2/api-docs",
  "appPackage": "com.example.yourapp",
  "beanDir": "bean",
  "beanRequestSubdir": "request",
  "beanResponseSubdir": "response",
  "apiServicePath": "./app/src/main/java/com/example/yourapp/network/ApiService.kt",
  "diffExcludeTags": ["im-controller", "系统配置信息(非API)"],
  "docsDir": "./docs",
  "prototypeDir": "./prototypes",
  "beanSyncMode": "update",
  "ui": { "platform": "views" },
  "figmaMcp": {
    "outputPlatform": "views",
    "skillsDir": "./figma-skills",
    "imageDir": ".",
    "defaultDensities": ["xxhdpi"]
  },
  "generateApiService": false
}

4.2 字段说明

| 字段 | 必填 | 说明 | |------|------|------| | swaggerUrl | 是 | Swagger / OpenAPI JSON 地址 | | appPackage | Bean / diff-api 时需要 | 应用包名 | | beanDir | 否 | Bean 根目录名，默认 bean | | beanRequestSubdir | 否 | 请求 Bean 子目录，默认 request | | beanResponseSubdir | 否 | 响应 Bean 子目录，默认 response | | apiServicePath | 用 diff-api 时必填 | Retrofit 接口文件，相对项目根 | | docsDir | 是 | 需求文档目录，默认 ./docs | | prototypeDir | 否 | App 原型目录，默认 ./prototypes；不存在则静默跳过（见第 9 节） | | diffExcludeTags | 否 | diff-api 忽略的 Swagger tag | | beanSyncMode | 否 | run 结束是否同步 Bean：update / new / skip | | ui.platform | 否 | views 或 compose | | figmaMcp.* | 否 | Figma MCP 输出平台、Skill 目录、切图密度等 | | generateApiService | 否 | 默认 false；true 时 run 生成 ApiService（见下） |

Bean 物理路径（默认）：

app/src/main/java/{appPackage}/bean/request/   ← 请求 Bean
app/src/main/java/{appPackage}/bean/response/  ← 响应 Bean

Kotlin 包名（默认）： com.example.yourapp.bean.request / .response

若你项目目录命名不同，只改 config 里三个 Bean 相关字段即可，不用改工具代码。

generateApiService: true 时，生成路径为：

app/src/main/java/{appPackage}/data/api/ApiService.kt

与 apiServicePath 无关；已有接口文件的项目请保持 false。

4.3 figmaFileId 要不要写？

| 场景 | 要不要 | |------|--------| | 还原某个 Figma 页面（粘贴链接给 Agent） | 不要，链接里自带 fileKey | | 日常只更新接口 + 需求 | 不要，用 run --swagger-only | | 想在 project_context.json 里有一份页面名称索引 | 要，配 figmaFileId 或 FIGMA_FILE_ID，再跑完整 run |

4.4 环境变量

| 环境变量 | 覆盖 config | |----------|------------| | FIGMA_API_KEY | Figma Token（仅环境变量） | | SWAGGER_URL | swaggerUrl | | APP_PACKAGE | appPackage | | BEAN_DIR | beanDir | | BEAN_REQUEST_SUBDIR | beanRequestSubdir | | BEAN_RESPONSE_SUBDIR | beanResponseSubdir | | API_SERVICE_PATH | apiServicePath | | PROTOTYPE_DIR | prototypeDir | | BEAN_SYNC_MODE | beanSyncMode | | FIGMA_FILE_ID | 完整 run 拉 Figma 索引时用 |

5. 功能地图

┌──────────────────────────────────────────────────┐
│              android-context-builder              │
├──────────────┬──────────────┬────────────────────┤
│ 上下文        │ Bean / 接口   │ Figma UI           │
│ run          │ sync-beans   │ figma-android-mcp  │
│ project_ctx  │ diff-api     │ + android-layout   │
├──────────────┴──────────────┴────────────────────┤
│ MCP: android-project + figma-android-mcp         │
└──────────────────────────────────────────────────┘

| 能力 | CLI | MCP | |------|-----|-----| | 拉 Swagger + 需求 + Figma 索引 | run | — | | 只拉 Swagger + 需求 | run --swagger-only | — | | 查接口 | — | get_api_endpoints | | 查 Schema | — | get_api_schema | | 读需求 | — | get_requirement | | 项目概览 | — | get_project_overview | | 同步 Bean | sync-beans | sync_beans_from_swagger | | 对比 ApiService | diff-api | diff_api_service | | 列出 App 原型 | — | list_prototypes | | 读取某页原型 | — | get_prototype | | 列出待 Figma 替换的原型页 | — | list_prototype_pages | | Figma 节点树 | — | get_figma_node | | 导出切图 | — | download_figma_images | | 布局规则 | — | get_skill |

6. 命令行

均在项目根目录执行。

| 命令 | 一句话 | |------|--------| | setup | 新项目一键初始化（config + Skill + MCP） | | init | 只建 config 和 Skill | | setup-mcp | 只更新 .mcp.json | | run | 拉 Swagger + 需求 + Figma 索引 → project_context.json | | run --swagger-only | 只拉 Swagger + 需求（日常推荐） | | sync-beans | 单独同步 Bean | | diff-api | 对比 Swagger 与 ApiService | | diff-api --json | 同上，JSON 输出 | | help / --version | 帮助 / 版本号 |

6.1 `run`

android-context-builder run --swagger-only
android-context-builder run --bean-mode update   # 结束顺便同步 Bean

流程：检查 docs → 拉 Swagger →（可选）拉 Figma 索引 → 解析需求 → 写 project_context.json → 可选 Bean 同步。

| 报错 | 处理 | |------|------| | 缺 FIGMA_API_KEY | 加 --swagger-only，或 export FIGMA_API_KEY=... | | 缺 swaggerUrl | 改 config | | 需求文档为空 | 往 docs/ 放 .md / .docx |

6.2 `sync-beans`

android-context-builder sync-beans --bean-mode update

需先有 project_context.json。

| 模式 | 行为 | |------|------| | update | 匹配已有 Bean，更新字段，保留类名（推荐） | | new | 按 Schema 新建 Bean 文件 | | skip | 不同步 |

6.3 `diff-api`

android-context-builder diff-api
android-context-builder diff-api --json

需配置 apiServicePath + swaggerUrl（或已有 project_context.json）。详见第 11 节。

7. MCP 工具

setup 写入 .mcp.json，包含两个服务。

7.1 android-project

读 project_context.json + android-context.config.json。

| 工具 | 参数 | 返回 | |------|------|------| | get_project_overview | 无 | 技术栈、页面索引、API tag、需求列表 | | get_figma_workflow | 无 | Figma → Android 推荐步骤 | | get_api_endpoints | tag_or_prefix | 匹配接口列表 | | get_api_schema | schema_name | Schema 定义（可模糊） | | get_requirement | filename | 需求文档全文 | | sync_beans_from_swagger | mode: update/new | 同步结果 + warnings | | diff_api_service | 可选 api_service_path、swagger_url | JSON 差异报告 | | list_prototypes | 无 | 全部原型页（页面名 + 类型 image/url） | | get_prototype | page_name | 图片绝对路径（多模态读图）或 URL（浏览器打开） | | list_prototype_pages | 无 | layout 中带 @ui-source: prototype 标记的待替换页清单 |

已弃用（会返回跳转说明）：get_figma_page、get_figma_frame、get_design_system、generate_compose_screen。

7.2 figma-android-mcp

| 工具 | 参数 | 说明 | |------|------|------| | get_skill | android-layout / figma-android-mcp-skill / prototype-ui-skill | 写 UI 前必须先读 | | get_figma_node | fileKey、nodeId、includePreview? | 主入口（0.5.3+）：自动识别节点类型——FRAME/COMPONENT 出单节点数据；SECTION（多状态稿）出分组多帧数据 | | get_figma_data | fileKey、nodeId、includePreview? | 旧版主入口，0.5.3 仍可用（等价单节点路径） | | download_figma_images | 依赖上一步结果 | PNG → res/drawable-* |

nodeId 从 Figma URL 的 node-id=1-2 取，传给 MCP 时用 1:2。

0.5.3 新增：get_figma_node 统一入口（含 SECTION 多状态路由）、overlays（自动识别 toast/dialog 浮层）、anchor（绝对定位锚点推断）。Skill 已覆盖这些字段的处理。

8. Figma UI 还原

project_context.json 里的 Figma 只有页面名索引，不够还原弹窗等复杂 UI。

标准流程：

1. get_skill("android-layout")
2. get_skill("figma-android-mcp-skill")
3. 粘贴 Figma 链接（含 node-id）
4. get_figma_node(fileKey, nodeId)
5. download_figma_images
6. 写 XML/Compose + 业务逻辑

硬性规则（摘要）：

禁止把 Figma 绝对尺寸直接写成固定 dp 宽高
有重叠用 FrameLayout，无重叠用 LinearLayout / ConstraintLayout
必下 export-tagged 切图；未下的用纯色占位，禁止 Vector 重画

完整规则：figma-skills/android-layout/SKILL.md。

Compose 项目： config 设 "ui": { "platform": "compose" }，figmaMcp.outputPlatform 同步，再 setup-mcp + Reload MCP。

9. 原型先行流程

Figma 设计稿还没出，但需求和接口已就绪？把原型放进 prototypes/，先出「简易页 + 正式业务逻辑」，Figma 出稿后只换 UI、不动逻辑。

9.1 目录约定

prototypes/
  还款成功页.png        ← 图片：文件名 = 页面名（png/jpg/jpeg/webp）
  首页.jpg
  links.md             ← URL 原型清单，每行「页面名: https://...」

links.md 示例：

申请页: https://modao.cc/app/xxx
设置页: https://www.figma.com/proto/yyy

目录由 config 的 prototypeDir 指定（默认 ./prototypes），不存在则静默跳过，不影响现有流程。

9.2 两阶段工作流

阶段一：原型 → 简易页（Figma 未出稿）

1. 把原型图/URL 放进 prototypes/，跑 run --swagger-only
2. Agent 调 list_prototypes / get_prototype 看原型
3. Agent 读 prototype-ui-skill，写带标记的简易布局：
   <!-- @ui-source: prototype -->
   <!-- @ui-page: 还款成功页 -->
4. ViewModel / 接口调用 / 跳转按正式规范实现（这部分以后不再改）

简易页规则：只用标准 Material 组件、不写死尺寸、图片纯色占位。完整规范见 figma-skills/prototype-ui-skill/SKILL.md。

阶段二：Figma 出稿 → 替换 UI

1. 粘贴 Figma 链接（含 node-id）+ 指明页面名
2. Agent 用 list_prototype_pages（或 grep @ui-page）定位原型布局
3. get_figma_node → download_figma_images → 只重写该 XML 与 res 资源
4. view id 沿用，Activity / Fragment / ViewModel / 接口调用零改动
5. 标记更新为 <!-- @ui-source: figma node-id=x:y -->

替换细节见 figma-skills/figma-android-mcp-skill/SKILL.md 的「替换原型页」章节。

9.3 何时不用这个流程

Figma 已出稿的页面：直接走第 8 节，不需要原型与标记
纯逻辑改动（无新页面）：与原型无关

10. Bean 同步

10.1 目录与包名

由 config 决定，工具不写死任何项目包名：

| config 字段 | 默认 | 作用 | |-------------|------|------| | beanDir | bean | Bean 根文件夹 | | beanRequestSubdir | request | 请求 Bean 子文件夹 | | beanResponseSubdir | response | 响应 Bean 子文件夹 |

new 模式生成的 Kotlin package 为：{appPackage}.{beanDir}.{子目录名}。

10.2 何时跑

run 结束时（beanSyncMode 控制）
sync-beans
MCP sync_beans_from_swagger

10.3 update 模式怎么匹配

按 Swagger Schema 与已有 .kt 的属性指纹、KDoc 里的接口地址匹配，保留原有类名，只增删字段。

10.4 跑完检查什么

编译是否通过
CLI/MCP 返回的 warnings
新增非空字段是否已赋值

11. diff-api 接口对比

回答：Swagger 文档和现有 Retrofit 代码差在哪？

android-context-builder diff-api

11.1 报告四段

| 段 | 含义 | 你怎么用 | |----|------|---------| | 1. Swagger 有 / 代码无 | 文档有、客户端没接 | 本迭代待开发清单 | | 2. 代码有 / Swagger 无 | 代码有、文档没了 | 疑似废弃 | | 3. 参数差异 | Query / Body 不一致 | 改 Retrofit 注解 | | 4. Bean 字段差异 | schema 与 Bean 字段不一致 | 先 sync-beans 再核对 |

11.2 迭代版本（自动识别）

当前迭代版本: v1.0.4（从 Swagger 接口文档自动识别）

扫描 summary / tags 里的 ⭐新增(v1.0.x)、✏️修改(v1.0.x)，不用在 config 写版本号。文档升到 v1.0.5 后重跑即可。

11.3 排除 tag

"diffExcludeTags": ["im-controller", "系统配置信息(非API)"]

12. project_context.json

run 后在项目根生成，不要手改，更新文档后重新 run。

{
  "figma": { "pages": [...], "design_system": {...} },
  "api": { "base_url": "...", "endpoints": [...], "schemas": {...} },
  "requirements": [{ "filename": "需求.md", "content": "..." }],
  "prototypes": [
    { "page": "还款成功页", "type": "image", "path": "prototypes/还款成功页.png" },
    { "page": "申请页", "type": "url", "url": "https://modao.cc/xxx" }
  ],
  "figma_ui": { "mcp": "figma-android-mcp", "skills": [...] }
}

| 字段 | 说明 | |------|------| | api.* | MCP 查接口、Bean 同步的数据源 | | requirements | MCP get_requirement 的数据源 | | figma.pages | 仅名称索引；高保真 UI 走 figma-android-mcp | | prototypes | prototypeDir 扫描结果；MCP list_prototypes / get_prototype 的数据源 |

建议加入 .gitignore（体积大、每人可本地 run 生成）。

13. 典型场景

新项目接入

android-context-builder setup
# 改 config
android-context-builder run --swagger-only
# Reload MCP

后端更新 Swagger

android-context-builder run --swagger-only --bean-mode update
android-context-builder diff-api

还原 Figma 弹窗

粘贴 Figma 链接 → get_skill → get_figma_node → download_figma_images → 写 XML。

Figma 没出稿，先按原型开发

原型图/URL 放 prototypes/ → run --swagger-only → Agent 按 prototype-ui-skill 出带标记的简易页 + 正式业务逻辑。Figma 出稿后粘贴链接走「替换原型页」流程（见第 9 节）。

迭代开工列接口

android-context-builder diff-api

看「## 1」里带 新增 v1.0.x 的条目。

CI 检查

android-context-builder diff-api --json > diff.json

14. 常见问题

MCP 工具看不到？
确认有 .mcp.json → setup-mcp → Cursor Reload → 检查 node / python3 在 PATH。

Figma 失败？
检查 FIGMA_API_KEY、链接是否含 node-id、文件权限。只是 run 报缺 figmaFileId 就改用 --swagger-only。

Swagger 失败？
浏览器能否打开 swaggerUrl；内网要 VPN。

Bean 同步后编译报错？
看 warnings；检查新字段默认值。

diff-api Body 误报？
multipart 接口（OCR/人脸）可能误报，以实际注解为准。

会覆盖 ApiService 吗？
默认不会（generateApiService: false）。

加项目 Skill？
在 figma-skills/xxx/SKILL.md 新建；setup 不覆盖已有 Skill。

15. 从 v1 迁移

npm install -g android-context-builder@latest
android-context-builder setup-mcp

| v1 | v2+ | |----|-----| | 仅 android-project | + figma-android-mcp | | get_figma_frame | get_figma_data + Skill | | 默认生成 ApiService | 默认不生成 |

链接

npm：android-context-builder
仓库：https://github.com/garyliu333/android-context-builder
依赖：figma-android-mcp

License

MIT