Driftcheck

Driftcheck

在用户发现 UI 偏差之前，先将其找出来。
你的 AI Agent 会将模拟器中的应用与其 Figma 设计进行比较，然后修复差异。

_{打开交互式报告 → · 设计：Marvilo 的 Paylo kit（CC BY 4.0）}

Driftcheck 是一个本地 MCP 服务。它会截取 Android 设备或 iOS 模拟器的屏幕，与 Figma 画板进行 1:1 对比，并为你的 Agent 提供弥合差距所需的信息：

• 差异内容：位置、尺寸、文本、字体、颜色、圆角、边框，以及缺失的图标或图像；还会根据图层的外观找出其中没有文本的图层。
• 修复方法：使用你的框架属性编写，例如 Margin、android:layout_marginTop、Modifier.padding、.frame、EdgeInsets……
• 保真度评分：跟踪每次修复前后的进度，并生成可与团队分享的 HTML 报告。

它适用于真实世界的设计套件（其中的图层名为 Frame 或 Text），并且无需 Figma 令牌；可通过 Driftcheck Figma 插件 使用。

快速开始

你需要 .NET 10 SDK，以及用于 Android 的 adb 或用于 iOS Simulator 的 Xcode。只需单击一次即可安装 Driftcheck：

VS Code 会要求你提供 Figma 令牌；若要改用 Figma 插件，请留空。在 Cursor 中，之后将令牌添加到服务配置中的 FIGMA_TOKEN。

或者，手动将其添加到任意 MCP 客户端；首次运行时，dotnet dnx 会从 NuGet 下载它：

{
  "mcpServers": {
    "driftcheck": {
      "command": "dotnet",
      "args": ["dnx", "Driftcheck", "--yes"],
      "env": { "FIGMA_TOKEN": "<your Figma token>" }
    }
  }
}

使用 Claude Code：

claude mcp add driftcheck -e FIGMA_TOKEN=<your Figma token> -- dotnet dnx Driftcheck --yes

然后运行你的应用并询问你的 Agent：

将模拟器中的应用与 https://www.figma.com/design/…?node-id=… 进行比较，并修复差异。

Agent 会获得什么

compare_screen 会返回一份 Agent 可据此采取行动的报告（摘自演示）：

**Fidelity: 75 %** — 15 of 20 elements as in Figma

| Element                    | Property   | Figma   | App     |
|----------------------------|------------|---------|---------|
| Nice to meet you           | height     | 31.5    | 25.5    |
| Text "Sign up with Google" | x          | 131.9   | 125     |
| Shape "Sign up"            | background | #DBC6F8 | #BAD1BB |

## How to fix it

- **Nice to meet you**
  - The glyphs don't measure the same as in Figma; check the font: in Figma it is Inter 32 weight 600.
    `FontFamily="Inter"`, `FontSize="32"`, `CharacterSpacing`
- **Shape "Sign up"**
  - `BackgroundColor="#9E56FF"` (it renders as #DBC6F8 in the design: the layer or a container has opacity)

## Design non-text layers not found in the app (1)

- Icon (x=108.2 y=392.3 w=20 h=20) — Missing a 20×20 dp icon (the Figma layer is 24×24)

此外还会生成 report.html（上方的交互式报告：滑块、不透明度、差异图和并排对比）、side_by_side.png 和 diff.png。

支持的平台

设备	屏幕读取方式
Android 模拟器或设备	adb：screencap + uiautomator dump（AutomationId 对应 resource-id）
iOS Simulator（macOS）	simctl + 一个读取辅助功能树的 XCUITest 辅助程序（AutomationId 对应 accessibilityIdentifier）

修复建议针对 .NET MAUI、Android views、Jetpack Compose、UIKit、SwiftUI 和 Flutter 编写；如果不传入 framework，则会使用通俗表述。比较本身不依赖框架：它会根据屏幕上显示的内容进行比较。

MCP 工具

工具	用途
list_devices	已连接的 Android 设备和已启动的 iOS 模拟器
get_design_specs	画板的尺寸、颜色、文本和字体（编写 UI 代码前）
capture_screen	捕获屏幕及带有 AutomationId 的应用元素
compare_screen	完整的设计与应用对比：保真度、差异、修复方法和 report.html
import_design	导入 Figma 插件生成但未保存到 Downloads 文件夹中的 .driftcheck.json

工作原理

Driftcheck 会下载一次画面并将其保存在本地缓存中，重新计算 Figma 的自动布局，并通过 AutomationId、可见文本或位置将图层与应用元素匹配。文本按其可见字形而非文本框进行比较；非文本图层则根据外观在截图中查找；如果设备比画面略宽或略窄，则会将每个元素锚定在最合适的位置。完整的操作说明见Driftcheck 的比较方式。

Figma API 限制

Figma 限制了每个令牌可以发出的调用次数，而某些席位类型的配额非常低：配额用尽后，Figma 会返回 429，并要求等待数天。这就是为什么：

• 每个画面的 JSON 和 PNG 都会保存在本地缓存中，并在每次比较时重复使用。向 get_design_specs 或 compare_screen 传入 refresh=true，即可下载在 Figma 中已更改的画面。
• 如果 Figma 返回 429，错误信息会说明需要等待多久。
• 没有令牌或配额时，tools/figma-export-plugin 中的 Figma 插件会将画面（JSON + 2x 渲染图）导出到 .driftcheck.json 文件，无需使用 REST API。如果文件位于 Downloads 中，Driftcheck 会根据画面链接自动找到它；如果位于其他文件夹，请使用 import_design 导入。请参阅插件 README。

要求

• .NET 10 SDK
• 对于 Android：Android SDK 和 adb（从 ANDROID_HOME、ANDROID_SDK_ROOT 或 Windows 和 macOS 上的默认路径检测）
• 对于 iOS：安装了 Xcode 且已启动模拟器的 macOS。无需 idb 或 WebDriverAgent
• FIGMA_TOKEN 环境变量，值为 Figma Personal Access Token（范围为 File content: Read-only），或者使用 Figma 插件在没有 API 的情况下工作
• 可选：设置 DRIFTCHECK_OUTPUT 更改输出文件夹（默认为临时文件夹中的 driftcheck）
• 可选：设置 DRIFTCHECK_EXPORTS 更改查找插件导出文件的位置（默认为 Downloads）

当前限制

• 仅支持在模拟器上运行 iOS（不支持实体设备）。
• 仅检测可见区域（不支持滚动）。
• 不会测量应用中的字体大小（uiautomator 和 XCUITest 不会公开此信息）；get_design_specs 会提供该值作为参考。

从源代码运行

git clone https://github.com/wilsonvargas/Driftcheck.git
cd Driftcheck
dotnet build src/Driftcheck.Mcp

根目录下的 .mcp.json 会为打开此文件夹时读取该文件的 MCP 客户端注册服务。若要在其他项目中使用，请将该服务添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "driftcheck": {
      "command": "dotnet",
      "args": ["<repo path>/src/Driftcheck.Mcp/bin/Debug/net10.0/Driftcheck.Mcp.dll"]
    }
  }
}

仓库布局

• src/Driftcheck.Mcp — MCP 服务
• tools/ios-accessibility-helper — 用于导出 iOS Simulator 无障碍树的 UI 测试（构建时会复制到服务旁边）
• tools/figma-export-plugin — 可在不使用 REST API 的情况下导出画框的 Figma 插件
• samples/PayloMaui — MAUI 测试应用，包含 Marvilo 的 Paylo 套件中的屏幕（CC BY 4.0） 在 iOS Simulator 中：运行 dotnet build -f net10.0-ios -p:TargetFrameworks=net10.0-ios（限制 TargetFrameworks 可避免要求安装 Mac Catalyst 工作负载），然后运行 xcrun simctl install booted bin/Debug/net10.0-ios/iossimulator-arm64/PayloMaui.app 和 xcrun simctl launch booted com.companyname.paylomaui。Xcode 版本必须符合 iOS 工作负载的要求；如果安装了多个版本，请使用 DEVELOPER_DIR 选择所需版本。
• samples/PayloNative — 使用原生 Android 视图实现的相同注册屏幕（Java，不使用 MAUI 或 AndroidX），用于检查比较是否依赖 MAUI。./build.ps1 使用 SDK 工具构建该应用（不使用 Gradle）并将其安装到模拟器上
• samples/PayloIos — 使用原生 iOS 视图实现的相同屏幕（Swift 中的 UIKit，不使用 MAUI 或 storyboard）。./build.sh 使用 swiftc 构建该应用（不需要 Xcode 项目），并将其安装到已启动的模拟器上
• tests/Driftcheck.Tests — 使用合成屏幕进行的比较器测试
• docs — 详细的比较指南和发布在 GitHub Pages 上的演示报告

要比较示例应用，请在 Figma Community 中打开 Paylo 套件，将其复制到草稿中，选择画框 Component 113（注册屏幕），然后使用 Copy link to selection。接着在模拟器或仿真器上运行一个示例，并让你的 Agent 使用该链接进行比较。

参与贡献

欢迎提交问题和拉取请求。有关如何构建、测试和提出更改，请参阅 CONTRIBUTING.md；如需私下报告漏洞，请参阅 SECURITY.md。

许可证

Driftcheck 基于 MIT 许可证发布。示例应用中的第三方材料仍遵循各自的许可证：请参阅 THIRD_PARTY_NOTICES.md。