Saccadic AI

糖化人工智能

用于构建Flutter应用程序的AI编码代理的视觉反馈系统 --将.pen/Figma设计与运行Flutter构建进行比较，获得可操作的反馈，并迭代到像素精度。

Saccadic AI使AI编码代理能够直观地感知他们构建的内容，将其与设计规范进行比较，并接收可操作的反馈。它协调了从完整设计到代码构建的过程 .pen 或具有并行页面执行和迭代细化的Figma文件。

快速开始

需求

• Dart SDK>=3.4.0
• 一个正在运行的Flutter应用程序 --observatory-port （用于VM服务连接）

安装

cd saccadic
dart pub get

构建

将MCP服务器编译为本机可执行文件：

dart compile exe bin/saccadic_mcp.dart -o saccadic-mcp

配置MCP服务器

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "saccadic-ai": {
      "command": "/path/to/saccadic-mcp"
    }
  }
}

或者直接运行而不编译：

{
  "mcpServers": {
    "saccadic-ai": {
      "command": "dart",
      "args": ["run", "bin/saccadic_mcp.dart"],
      "cwd": "/path/to/saccadic-ai/saccadic"
    }
  }
}

运行测试

cd saccadic
dart test          # 69 tests
dart analyze       # 0 issues

从.pen设计文件构建

从设计到像素精确Flutter代码的最快方法。

先决条件

用克劳德代码配置的两个MCP服务器：

1. 糖化人工智能 --可视化比较和构建编排
2. 铅笔MCP --阅读 .pen 设计文件并捕获参考截图

用法

在Claude Code中打开Flutter项目，并给出以下提示：

Build all pages from the design at [path/to/design.pen]

1. Call plan_build({ pencilFile: "[path/to/design.pen]" })
2. Start the Flutter app with --observatory-port
3. For each page in the plan, spawn a parallel sub-agent with that page's agentPrompt
4. Each sub-agent should:
   a. Capture a reference screenshot via Pencil MCP get_screenshot
   b. Build the Flutter widget with Key('nodeId') attributes matching design node IDs
   c. Call refine_build with the reference screenshot until status="pass" (95%+)
5. Report final scores for all pages when done

运作原理

You (prompt)                  Claude                          Saccadic MCP            Pencil MCP
────────────                  ──────                          ────────────            ──────────
"Build from design.pen" ───→  1. plan_build(pencilFile) ───→  Parses .pen file
                                                         ←──  Returns per-page plans
                                                               with agent prompts

                              2. Spawns parallel sub-agents
                                 (one per page, clean context)

                              Sub-agent per page:
                              ├─ 3. get_screenshot(frameId) ─────────────────────────→ Returns PNG
                              │                              ←─────────────────────────
                              ├─ 4. Builds Flutter widget with Key('nodeId') attributes
                              │
                              ├─ 5. refine_build(flutterUrl) ──→ Compares design vs build
                              │                              ←── Score, mismatches, fixes
                              ├─ 6. Applies fixes
                              ├─ 7. refine_build(iteration=2)──→ Re-checks
                              │                              ←── Improved score
                              └─ 8. Repeats until status="pass" (≥95%)

                              9. Collects results from all sub-agents
                         ←──  10. Reports final per-page scores

密钥（'nodeId'）约定

每个与设计节点对应的Flutter小部件都必须有一个 Key('nodeId'):

Container(
  key: Key('heroSection'),
  child: Column(children: [
    Text('Welcome', key: Key('heroTitle')),
    Text('Build something amazing', key: Key('heroSubtitle')),
  ]),
)

节点ID来自 plan_build 回应(pages[].nodeIds).

MCP工具

命令行界面

CLI也可用于手动使用：

# Compare a .pen design against a running Flutter app
dart run bin/saccadic.dart compare \
  --pen design.pen \
  --frame "Home" \
  --flutter-url ws://127.0.0.1:52341/ws

# Generate a build plan
dart run bin/saccadic.dart plan --pen design.pen

# Iterative refinement
dart run bin/saccadic.dart refine \
  --pen design.pen \
  --frame "Home" \
  --flutter-url ws://127.0.0.1:52341/ws

建筑

saccadic/
  bin/
    saccadic.dart           — CLI entry point (compare, plan, refine commands)
    saccadic_mcp.dart       — MCP server entry point (stdio transport)
  lib/
    saccadic.dart           — Barrel export
    src/
      core/
        types.dart          — Shared types, thresholds, viewport presets
        thresholds.dart     — Perceptual thresholds (CIEDE2000, Weber)
        color_science.dart  — Color conversion and CIEDE2000
      comparison/
        comparison_engine.dart  — Central orchestrator
        widget_comparator.dart  — 5-pass widget matching + property comparison
        pixel_comparator.dart   — Pixel diff with flood-fill region detection
      design/
        pencil_parser.dart  — .pen file parser (5-phase pipeline)
        figma_parser.dart   — Figma REST API parser
        design_source.dart  — Abstract design source interface
        pencil_types.dart   — .pen file type definitions
      flutter/
        flutter_inspector.dart — VM service connection, screenshot, widget tree
        widget_style.dart      — Extracted widget properties
      feedback/
        feedback_generator.dart   — Actionable feedback with cascade suppression
        cascade_suppression.dart  — Dedup dependent mismatches
        fix_suggester.dart        — Flutter-specific fix suggestions
      scoring/
        scorer.dart         — Multi-factor scoring (widget + pixel)
      plan/
        plan_generator.dart      — Per-page build plans from designs
        agent_prompt_builder.dart — AI agent prompts with Key('nodeId')
      mcp/
        server.dart         — MCP server (8 tools via mcp_dart)
        session.dart        — Refine session state (stall detection, history)
      cli/
        compare_command.dart — CLI compare command
        plan_command.dart    — CLI plan command
        refine_command.dart  — CLI refine command

小工具匹配（5遍）

1. 传递0:密钥 --精确匹配通过 Key('nodeId')
2. 第一关：IoU --交叉口超过联盟空间重叠
3. 第二部分：文本内容 --模糊文本匹配
4. 第三关：类型+视觉 --小部件类型+填充颜色+边界
5. 第四步：姓名回退 --小部件描述匹配

分级标准

配置

Figma访问令牌

对于Figma集成，请设置您的访问令牌：

export FIGMA_TOKEN=your_token_here

或者通过Dart定义： -DFIGMA_TOKEN=your_token_here

许可证

阿帕奇-2.0