Aider + Figma — 基于上下文包的 UI 结对编程

Aider 是一款基于终端的 AI 结对编程工具。它读取你指定的文件，以统一差异（unified diff）格式生成编辑内容，并将修改直接应用到代码库中。每次变更在落地前都可以审查。这种差异优先的工作流与 Token 感知的设计交付完美契合——你可以清楚地看到生成的代码是否使用了 Token 文件中的 spacing.16，还是已经偏移到了硬编码的 16px。

本指南涵盖 Aider + figmascope 的完整流程：生成包、加载到 Aider 会话、使用 Architect 模式完成初始脚手架，以及通过有针对性的编辑提示词进行迭代。

前置条件

如果尚未安装 Aider，请先安装：

pip install aider-chat
# 或
brew install aider

Aider 支持多种模型后端。以下示例使用通过 Anthropic API 的 Claude Sonnet，但工作流与 OpenAI 或本地模型完全相同。

export ANTHROPIC_API_KEY=sk-ant-...
# 或使用 OPENAI_API_KEY（GPT-4o）

第一步：生成包

前往 figmascope.dev，粘贴你的 Figma 文件 URL，点击导出 Agent 上下文。导出程序在浏览器中运行——你的 Figma 个人访问令牌存储在 localStorage 中，永远不会离开你的设备。

下载文件为 context-bundle.zip。

第二步：解压到项目目录

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

第三步：启动 Aider 并加载包文件

在命令行中传入所需的包文件。Aider 将其作为只读上下文加载——模型可以引用这些文件，但除非你明确使用 /add 将其提升为可编辑文件，否则不会对其进行修改。

aider \
  --read design/CONTEXT.md \
  --read design/tokens.json \
  --read design/strings.json \
  design/screens/home.json \
  src/screens/HomeScreen.kt

规则：--read 用于包文件（仅上下文，不可编辑），位置参数用于你希望 Aider 修改的源文件。这样可以保持包文件干净——Aider 的差异机制不会尝试编辑 tokens.json。

如果你希望 Aider 创建新文件而不是编辑已有文件，只需指定一个尚不存在的目标路径即可，Aider 会自动创建。

第四步：添加参考 PNG

Aider 可以将图片作为多模态模型的上下文。启动后使用 /add 命令：

/add design/screens/home.png

PNG 是来自 Figma 的 2× 渲染图。对于多模态模型（Claude Sonnet、GPT-4o），Aider 会将其作为视觉参考。在审查时用于合理性检验——规范来源是 JSON，而非图片。

第五步：Architect 模式——初始脚手架

Aider 的 /architect 命令使用两步模型：一次规划，一次实现。这是处理完整屏幕的正确起点，在编辑各个细节之前，你需要一个连贯的整体结构。

/architect 将 design/screens/home.json 实现为 Jetpack Compose 屏幕。

上下文：
- 读取 CONTEXT.md 获取框架约束和目标规范。
- 所有间距、颜色和圆角值均来自 tokens.json。
  直接映射 Token 键：spacing.16 → 16.dp，color.7f5cfe → Color(0xFF7F5CFE)。
- 使用 strings.json 中的字符串键，通过 stringResource() 调用，以 fallback 字段作为字面量兜底。
- IR 节点类型：stack(vertical)→Column，stack(horizontal)→Row，overlay→Box，
  absolute→Box+Modifier.offset，leaf(text)→Text，leaf(rect)→Box+Modifier.background。
- 不要硬编码任何有 Token 对应的值。

输出至：src/screens/HomeScreen.kt

Aider 先生成规划并展示给你，然后生成差异。审查规划——如果节点映射看起来有误，在实现步骤运行前进行纠正。

第六步：使用 Token 引用编辑特定文件

脚手架就位后，使用有针对性的 /edit 提示词修复特定问题。这正是 Aider 差异工作流的亮点——每次编辑都是一个小而可审查的变更，而不是完整的重新生成。

HomeScreen.kt 中的卡片组件对圆角使用了硬编码的 12dp。
检查 tokens.json 中正确的圆角 Token 并替换。

Aider 生成一个最小差异：只改动一两行，其他内容不受影响。你可以清楚地看到改动了什么。

对整个文件进行间距审计：

审计 src/screens/HomeScreen.kt 中的每个 .dp 值，与 design/tokens.json 中的间距 Token 对照。
生成差异，将有 Token 对应的硬编码值替换为 Token 引用。
对没有匹配间距 Token 的值留下 // TODO 注释。

第七步：对照规范审查差异

Aider 的差异视图是审查界面。在接受任何变更之前，检查：

• 新增行是否引用 Token 键而非字面量？
• 字符串字面量是否出现在 strings.json 中，还是硬编码的 UI 文案？
• 生成代码中的节点嵌套是否与 IR JSON 中的父子顺序匹配？

如果差异看起来有误，在提示符处输入 n 拒绝，然后告诉 Aider 需要修复什么。短循环反馈——提示、差异、接受/拒绝、优化——意味着你能立即发现偏移，而不是等到大段代码落地后才发现。

为什么 Aider 的差异工作流与包配合良好

Token 偏移在差异中一目了然。如果某一行写的是 color = Color(0xFF7F5CFE) 而非 color = tokens.colorPrimary，你在合并前就能看到。没有"留到后面再检查"——审查就在内联进行。

迭代优化成本低。每次变更不需要重新生成整个屏幕。每个后续提示都产生有针对性的差异。包提供稳定的上下文，Aider 提供精准的编辑能力。

包与代码一起做版本控制。当设计更新时，从 figmascope 重新导出包，与上一版本进行差异比较，然后让 Aider 只应用已变更的节点。这一工作流可以跨多次设计迭代扩展，无需完整重新实现。

常见模式与注意事项

不要一次加载所有屏幕。每次只传入一个屏幕 JSON。更多上下文并不总是更好——Aider（以及底层模型）在聚焦的上下文下表现更好，而不是把文件中所有屏幕全部堆进去。

对包使用 --read，而非位置参数。如果以位置参数传入 tokens.json，Aider 可能会尝试编辑它。使用 --read 将其标记为只读上下文。

在第一次提示前检查 _meta.json。warnings 数组列出了导出器无法完全解析的填充和效果。提前告知 Aider，避免它静默地进行近似处理：

cat design/_meta.json | python3 -c "import sys,json; w=json.load(sys.stdin).get('warnings',[]); print('\n'.join(w))"

在 Architect 提示词中包含任何警告："跳过英雄背景填充——渐变不受支持。留下 TODO 注释。"

Aider 适合精准、可审查的编辑——当你需要跨多个文件的完整会话上下文时，请使用 Cursor 或 Claude Code。三种工作流的起点相同：figmascope 主应用在浏览器中处理导出。