用 Claude Code 把 MasterGo 设计稿转成 Android 布局，我前几次得到的结果都不太能看：列表被生成了一坨静态重复布局，XML 里硬编码着 android:text="张三"，多样式的信息流只认出一种 item——每次改生成结果，花的时间比自己手写布局还多。
坑踩得多了才意识到，这些问题不是随机的。根因在于设计稿是静态视觉快照，AI 没法从稿子里猜出列表语义和动态数据。逐个案例去修补不可持续，得把规则前置：设计侧的命名规范、截图与 DSL 的阅读顺序、写进 CLAUDE.md 和 Skill 的生成与自检规则。
这篇文章把这套体系完整整理出来：基础问题覆盖边界识别和动态数据，进阶问题覆盖多 ViewType、嵌套 RV 与截图和 DSL 的阅读顺序。文中的命名规范、Prompt 模板、Skill 文件都可以直接拿去用。
一、问题根因总览
所有问题的本质是同一个矛盾：MasterGo 设计稿是“静态视觉快照”，而 Android 布局是“动态语义结构”。
| 问题类别 | 具体表现 | 根因 |
|---|---|---|
| RV 边界识别不准 | 把列表生成为静态重复布局，或漏掉滚动区域 | 设计稿只画了3~5条item，AI无法判断“这是列表还是固定布局” |
| 动态数据丢失 | XML中硬编码 android:text="张三" | 设计稿文字/图片全是占位符，AI默认照抄 |
| 多ViewType遗漏 | 只识别出一种item样式，其余被忽略或误判为独立区块 | 同一列表中不同样式的item在设计稿中视觉差异大，AI未关联 |
| 嵌套RV展平 | 内层横向列表被当成外层一部分，或变成静态LinearLayout | AI未理解“item内部还包含可滚动容器”的层级语义 |
| DSL与截图矛盾 | 生成的结构与视觉不符 | 单一输入源信息不完整，缺少交叉验证机制 |
二、核心解法体系（四层防线）
第一层：设计侧命名规范（成本最低、收益最高）
在 MasterGo 中建立统一的语义化命名体系，让 MCP 导出的 DSL 自带结构信息：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
? 推荐命名体系：
[RV/Outer] 首页信息流 → 外层纵向RecyclerView ├─ [RV-Item/Banner] 横幅卡片 → ViewType: BANNER ├─ [RV-Item/Product] 商品卡片 → ViewType: PRODUCT ├─ [RV-Item/Ad] 广告卡片 → ViewType: AD ├─ [RV-Item/Recommend] 推荐容器 │ └─ [RV/Inner] 横向推荐列表 → 嵌套横向RecyclerView │ ├─ [RV-Item] 推荐卡片A │ ├─ [RV-Item] 推荐卡片B │ └─ [RV-Item] 推荐卡片C └─ [RV-Item/Section] 分组标题 → ViewType: SECTION
[Fixed] 顶部搜索栏 → 固定Header，不随列表滚动 [Fixed] 底部TabBar → 固定Footer |
命名规则速查：
| 前缀 | 含义 | 示例 |
|---|---|---|
| [RV/Outer] | 外层RecyclerView | [RV/Outer] 商品列表 |
| [RV/Inner] | 嵌套RecyclerView | [RV/Inner] 横向推荐 |
| [RV-Item] | 单类型item | [RV-Item] 商品卡片 |
| [RV-Item/变体名] | 多ViewType item | [RV-Item/Banner] |
| [Fixed] | 固定区域 | [Fixed] 底部导航 |
| [Scroll] | ScrollView（非列表） | [Scroll] 协议文本 |
设计师花5分钟做好命名，开发侧能省2小时调试。MasterGo MCP导出的DSL会完整保留图层名，这是最可靠的语义信号。
第二层：截图与DSL的双通道阅读策略（关键流程）
核心原则：先截图（宏观语义）→ 再DSL（微观精确）→ 最后交叉验证
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
┌──────────────────────────────────────────────────────┐ │ 双通道阅读流程 │ │ │ │ Phase 1: 截图 → 宏观语义判断 │ │ ┌────────────────────────────────────────────────┐ │ │ │ • 区域划分：哪些是固定/滚动/嵌套 │ │ │ │ • 滚动判断：被屏幕边缘截断 → 可滚动 │ │ │ │ • 重复模式：视觉上重复的卡片 → 列表语义 │ │ │ │ • 嵌套检测：item内部有横向排列子元素 → 嵌套RV │ │ │ │ • 多类型：同一区域卡片结构明显不同 → 多ViewType │ │ │ │ │ │ │ │ 输出：结构分析表 │ │ │ │ ?? 暂停，等用户确认 │ │ │ └──────────────────────┬─────────────────────────┘ │ │ ▼ │ │ Phase 2: MCP DSL → 精确数值提取 │ │ ┌────────────────────────────────────────────────┐ │ │ │ • 精确尺寸/颜色/字体/间距 │ │ │ │ • 图层嵌套层级（父子关系） │ │ │ │ • Auto Layout方向和间距 │ │ │ │ • 与Phase 1结论交叉对比 │ │ │ │ │ │ │ │ 矛盾处理规则： │ │ │ │ • 截图显示滚动 + DSL未超出 → 仍按滚动处理 │ │ │ │ （设计稿可能只展示部分数据） │ │ │ │ • DSL中≥3个相同结构兄弟节点 → 强制识别为RV │ │ │ │ • DSL中节点被clip裁切 → 等同于"被截断" │ │ │ │ │ │ │ │ 输出：最终结构确认表 │ │ │ │ ?? 暂停，等用户确认 │ │ │ └──────────────────────┬─────────────────────────┘ │ │ ▼ │ │ Phase 3: 代码生成（基于确认后的结构+DSL数据） │ └──────────────────────────────────────────────────────┘ |
为什么这个顺序？
| 能力维度 | 截图能做（DSL不能） | DSL能做（截图不能） |
|---|---|---|
| 滚动判断 | ? 内容被屏幕截断 → 可滚动 | ? 无法感知视觉裁切 |
| 重复语义 | ? 视觉上“看起来是一组” | ? 只有节点树，无语义 |
| 整体层次 | ? 一眼看出固定/滚动/嵌套 | ? 需要逐层解析 |
| 精确数值 | ? 像素级估算误差大 | ? 精确px/hex/dp |
| 图层关系 | ? 遮挡/分组难以判断 | ? 明确的父子嵌套 |
| 样式参数 | ? 圆角/阴影/字重难辨 | ? 完整样式属性 |
截图回答“是什么”（语义），DSL回答“是多少”（精确）。两者互补，不能互相替代。
第三层：四大问题的具体解法
问题1：RecyclerView 边界识别
识别规则（写入 CLAUDE.md / Skill）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
## RecyclerView 边界判定规则
满足以下任一条件 → 生成 RecyclerView（而非静态布局）： 1. 同父容器下 ≥3 个结构完全相同的兄弟节点 2. 图层名称包含 [RV]、list、recycler、列表、卡片流 3. 内容被父容器 clip 裁切（DSL中overflow=hidden且子节点超出） 4. 截图中内容被屏幕边缘截断
滚动方向判定： - 重复节点纵向排列 → LinearLayoutManager(VERTICAL) - 重复节点横向排列 → LinearLayoutManager(HORIZONTAL) - 重复节点网格排列 → GridLayoutManager(spanCount=N) - 截断在水平方向 → 横向 - 截断在垂直方向 → 纵向 |
Prompt 模板（Phase 1 截图分析时使用）：
|
1 2 3 4 5 6 7 8 9 |
请观察这张设计稿截图，完成以下分析（不写代码）：
1. 哪些区域的内容被屏幕边缘截断？→ 标记为可滚动，标注截断方向 2. 哪些区域存在视觉上重复的卡片/行？→ 标记为列表 3. 哪些元素始终可见（顶栏/底栏）？→ 标记为固定 4. 某个重复单元内部是否还包含横向排列的子元素？→ 标记为嵌套RV
输出格式： | 区域 | 类型(RV/Fixed/Scroll) | 滚动方向 | Item类型数 | 含嵌套RV | 备注 | |
问题2：动态数据绑定
XML规范（写入 CLAUDE.md）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
## 动态数据绑定规范
1. 所有运行时动态赋值的文本： ? tools:text="示例商品名称" ? android:text="张三"
2. 所有运行时动态加载的图片： ? tools:src="@drawable/placeholder" ? android:src="@mipmap/avatar_zhangsan"
3. 条件显示/隐藏的View： ? android:visibility="gone" + tools:visibility="visible"
4. 每个需要数据绑定的View必须有明确id： ? android:id="@+id/tv_title" 命名规范：类型前缀_语义名（tv_title, iv_avatar, rv_list, btn_submit）
5. 提供数据模型时，字段与设计稿文本一一对应： ```json { "title": "string, 最多2行", "price": "double, 显示为¥{price}" } ``` |
问题3：多 ViewType RecyclerView
设计侧：用 [RV-Item/变体名] 命名区分不同类型
Prompt 侧：附带 ViewType 映射表
|
1 2 3 4 5 6 7 8 9 10 |
## 多ViewType声明
[RV/Outer] 首页信息流 → RecyclerView(VERTICAL)
| ViewType | 图层名 | 布局文件 | 数据模型 | 出现规律 | |----------|--------|---------|---------|---------| | TYPE_BANNER(0) | [RV-Item/Banner] | item_banner.xml | BannerData | 每10个出现1次 | | TYPE_PRODUCT(1) | [RV-Item/Product] | item_product.xml | ProductData | 主要数据 | | TYPE_AD(2) | [RV-Item/Ad] | item_ad.xml | AdData | 每5个插入1个 | | TYPE_SECTION(3) | [RV-Item/Section] | item_section.xml | SectionData | 分组时出现 | |
代码生成规范（写入 Skill）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
## 多ViewType生成规范
数据层：sealed class 作为基类 sealed class FeedItem { data class Banner(...) : FeedItem() data class Product(...) : FeedItem() ... }
Adapter： - 继承 ListAdapter<FeedItem, RecyclerView.ViewHolder> - getItemViewType(): when(item) 返回类型常量 - onCreateViewHolder(): 按viewType inflate不同布局 - onBindViewHolder(): when(holder) 分发绑定
DiffUtil： - areItemsTheSame: 按类型+id判断 - areContentsTheSame: data class自动equals
自检： - [ ] when分支覆盖所有ViewType？ - [ ] 每个ViewHolder只引用自己的ViewBinding？ - [ ] DiffUtil能区分不同类型？ |
问题4：嵌套 RecyclerView
设计侧：[RV-Item] 内部嵌套 [RV/Inner]
布局生成规范：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<!-- item_recommend_row.xml：外层item --> <LinearLayout orientation="vertical"> <TextView android:id="@+id/tv_section_title" tools:text="猜你喜欢" /> <androidx.recyclerview.widget.RecyclerView android:id="@+id/rv_inner" android:layout_width="match_parent" android:layout_height="wrap_content" tools:layoutManager="LinearLayoutManager" tools:orientation="horizontal" tools:listitem="@layout/item_recommend_card" /> </LinearLayout> |
Kotlin生成规范（写入 Skill）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
## 嵌套RV生成规范
外层Adapter的对应ViewHolder中： class RecommendRowHolder(binding: ItemRecommendRowBinding) : RecyclerView.ViewHolder(binding.root) { private val innerAdapter = RecommendCardAdapter() init { binding.rvInner.apply { layoutManager = LinearLayoutManager(context, HORIZONTAL, false) adapter = innerAdapter setHasFixedSize(true) isNestedScrollingEnabled = false } } fun bind(data: RecommendRowData) { binding.tvSectionTitle.text = data.title innerAdapter.submitList(data.cards) } }
性能优化（必须生成）： - 多个内层RV使用相同item类型 → 共享RecycledViewPool - 内层RV设置 isNestedScrollingEnabled = false - 嵌套深度限制：最多3层，超过提醒用户简化 |
第四层：Claude Code Skills 工程化
① 项目级CLAUDE.md（必做）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
# CLAUDE.md
## 项目信息 - 语言：Kotlin - 布局：XML + ViewBinding - 图片加载：Glide - 列表：RecyclerView + ListAdapter + DiffUtil
## MasterGo 转码规则 1. 优先使用 MCP DSL，截图作为语义补充 2. 阅读顺序：截图(宏观) → DSL(精确) → 交叉验证 3. ≥3个相同结构兄弟节点 → RecyclerView 4. 被clip裁切/屏幕截断 → 可滚动 5. [RV-Item/变体名] → 多ViewType 6. [RV-Item]内含[RV/Inner] → 嵌套RV 7. 动态文本一律用 tools:text，禁止硬编码 8. 尺寸换算：设计稿375px宽 → 360dp 9. 颜色提取到colors.xml，不内联 10. 输出路径：以用户输入的地址为准，不自行推断落盘位置
## 生成顺序（每步暂停确认） 结构分析 → XML布局 → 数据模型 → Adapter → 页面初始化 → 自检 |
② 输出路径规则（补充）
生成文件落盘位置：以用户输入的地址为准。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
## 输出路径规则
优先级（从高到低）： 1. 用户明确指定的路径（命令参数 / 对话中给出）→ 严格使用，不改动 2. 用户未指定时 → 先询问用户，确认后再生成，不自行选择默认目录
落盘结构： - 单平台：直接在用户指定路径下生成标准 res/ 结构 <用户路径>/res/layout/ 页面 + item 布局 <用户路径>/res/drawable/ shape 背景 <用户路径>/res/raw/ SVG 图标 <用户路径>/res/values/ colors.xml / dimens.xml / strings.xml - 多平台：在用户指定路径下先建平台文件夹（android/、ios/ …）， 各平台产物放入对应文件夹
禁止行为： - 禁止把文件写到用户未确认的位置 - 禁止生成后不告知最终落盘路径 - 生成完成后必须输出：本次写入的完整目录路径 + 文件清单 |
原因：布局产物最终要并入 Android 工程的 app/src/main/res/， 落盘位置不对会造成“生成了但找不到”的问题。以用户输入为唯一事实来源， 生成完毕必须回显完整路径供用户确认。
③ 完整 Skill 文件
.claude/skills/design-to-android/SKILL.md：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
--- name: design-to-android description: | 将 MasterGo 设计稿转换为 Android XML + Kotlin 代码。 支持：多ViewType、嵌套RecyclerView、动态数据绑定。 当用户提供设计稿链接或截图并要求生成Android布局时触发。 ---
# MasterGo → Android 布局转换
## 前置条件 - MasterGo MCP 已配置 - 用户提供：设计稿链接（带layerId）+ 可选截图
## 执行流程
### Phase 1: 视觉语义分析（截图优先） 输入：设计稿截图 任务：宏观结构判断 输出：区域划分表（类型/滚动方向/Item类型数/嵌套关系） ?? 暂停，等用户确认
### Phase 2: DSL精确提取（MCP结构化） 输入：MasterGo MCP getDsl 任务：精确数值提取 + 层级验证 交叉验证规则： - 截图显示滚动 + DSL未超出 → 仍按滚动处理 - DSL中≥3个相同结构兄弟节点 → 强制RV - DSL中节点被clip裁切 → 可滚动 - 同名前缀不同后缀 → 多ViewType - [RV]内嵌套[RV] → 嵌套列表 输出：最终结构确认表 ?? 暂停，等用户确认
### Phase 3: 代码生成 输入：确认后的结构 + DSL数据 生成顺序： 1. 主布局（activity/fragment） 2. 每个item布局（多ViewType则多个） 3. 嵌套的内层item布局 4. 数据模型（sealed class / data class） 5. Adapter（含多ViewType分发 + 嵌套RV初始化） 6. ViewHolder（每种类型一个） 7. 页面初始化代码
### Phase 4: 自检 - [ ] RV边界正确？（无静态重复布局） - [ ] 多ViewType全部覆盖？ - [ ] 嵌套RV独立Adapter + 性能优化？ - [ ] 所有动态文本用tools:？ - [ ] 滚动方向正确？ - [ ] 所有动态View有id？ - [ ] 颜色提取到colors.xml？
## 识别规则速查 | 信号 | 判定 | |------|------| | ≥3个相同结构兄弟节点 | RecyclerView | | 图层名含[RV] | RecyclerView | | 内容被clip裁切 | 可滚动 | | 截图内容被屏幕截断 | 可滚动 | | [RV-Item/A] + [RV-Item/B] | 多ViewType | | [RV-Item]内含[RV/Inner] | 嵌套RV | | 横向重复+超出宽度 | 横向RV | |
④ 斜杠命令（快速调用）
.claude/commands/d2a.md：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
根据以下设计稿生成 Android 布局代码：
设计稿链接：$ARGUMENTS
输出路径：以我在对话中指定的地址为准；若我未指定，先问我，确认后再生成。
请严格按照 design-to-android skill 的流程执行： 1. Phase 1: 先读截图做结构分析，输出分析表，等我确认 2. Phase 2: 再用MCP获取DSL，交叉验证，输出确认表，等我确认 3. Phase 3: 分步生成代码（XML → Model → Adapter → 初始化） 4. Phase 4: 自检报告
重点关注： - 被截断的区域 → RecyclerView - 重复结构的不同变体 → 多ViewType - item内部的横向列表 → 嵌套RV - 所有动态数据 → tools:属性 |
使用方式：/d2a https://mastergo.com/file/xxx?layer_id=yyy
⑤ MasterGo MCP 配置
|
1 |
claude mcp add mastergo -- npx -y @mastergo/magic-mcp --token=YOUR_MG_TOKEN |
Token获取：MasterGo → 个人设置 → 开发者 → Personal Access Token MCP走结构化DSL通道，远比截图识别准确，务必优先使用。
三、适用边界
这套体系不是万能 钥匙，效果建立在几个前提上，套用前先对照自己的情况：
- 技术栈是 XML + ViewBinding。 全部生成规范和代码模板都基于这套组合。Jetpack Compose 项目可以复用识别部分（命名规范、双通道阅读、RV 边界判定），但 Adapter 和多 ViewType 模板对应的是 LazyColumn + sealed class，生成规范需要重写。
- 依赖设计师配合命名。 设计师不加语义前缀时，第一层防线失效，只能靠双通道阅读和 Skill 规则兜底。结构仍然认得出来，但多 ViewType 和嵌套列表的出错会变多，Phase 1/2 的人工确认成本明显上升。
- 设计稿最好用了 Auto Layout。 Phase 2 的方向和间距都从 Auto Layout 里读。完全靠绝对定位摆出来的稿子，这些信号是缺失的，提取到的数值失真会比较大。
- 只有截图、拿不到 DSL 时效果打折。 “DSL 与截图矛盾”的根源就是单一输入源信息不完整。没有 MCP DSL 做交叉验证，结构判断只剩视觉线索，要做好人工确认轮次变多的心理准备。
- 深层嵌套和自绘控件不在覆盖范围内。 嵌套 RV 最多 3 层，超过就按生成规范提醒简化。自绘控件、复杂动画交互、ConstraintLayout 重度页面，本文的规则管不到，生成结果仍需要大量人工改写。
一句话：本文针对标准列表/信息流类页面（RecyclerView 为主、多 ViewType、嵌套列表）最有效，离这个画像越远，准确率预期就要打得越低。
四、实战 Checklist
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
设计侧 ────────────────────────────────────────────── ? 列表区域命名加 [RV/Outer] 或 [RV] 前缀 ? Item组件命名 [RV-Item] 或 [RV-Item/变体名] ? 嵌套列表标注 [RV/Inner] ? 固定区域标注 [Fixed] ? 设计稿只画2~3个重复item（不要画太多增加干扰）
Prompt 侧 ──────────────────────────────────────────── ? 先给截图做Phase 1结构分析 ? 附带区域标注表（哪里是列表/方向/数据源） ? 附带数据模型JSON Schema ? 多ViewType附带映射表 ? 嵌套RV明确声明层级关系和滚动方向
CLAUDE.md / Skill 侧 ──────────────────────────────── ? 写入RV识别规则（≥3重复/clip裁切/[RV]命名） ? 写入多ViewType生成规范（sealed class + when分发） ? 写入嵌套RV生成规范（独立Adapter + 性能优化） ? 写入tools:属性规范 ? 写入截图→DSL双通道阅读流程 ? 写入分步生成+暂停确认流程 ? 写入自检清单
生成流程 ──────────────────────────────────────────── ? 确认输出路径（以用户输入的地址为准，未指定则先询问） ? Phase 1: 截图结构分析 → 人工确认 ? Phase 2: DSL精确提取+交叉验证 → 人工确认 ? Phase 3: XML布局 → 数据模型 → Adapter → 初始化 ? Phase 4: 自检报告 ? 生成完毕回显：完整落盘路径 + 文件清单 |
五、写在最后
不要指望 AI 从设计稿里“猜”出所有语义。截图负责语义，DSL 负责数值，命名负责身份，Skill 负责方法，四者结合起来，设计稿转码的准确率才有保障。
