mcpField
U
understand-figma

understand-figma

github.com/egonex-ai设计与 UI88.8k1.9k 次安装2 天前更新
代码仓库

关于 understand-figma

understand-figma 用于分析 Figma 文件，并在现有仪表板中生成交互式设计知识图谱。它通过 Figma API 扫描文件，再由 LLM 分析补充图谱信息。

主要功能

  1. 01扫描并解析 Figma 文件
  2. 02按页面分组分析设计节点
  3. 03合并并验证设计图谱
  4. 04在现有仪表板中展示

适用场景

  1. 01把 Figma 文件整理为设计图谱
  2. 02在仪表板中查看设计节点与关系

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/egonex-ai/understand-anything --skill understand-figma

安装后在 Claude Code 中输入/understand-figma确认已加载。

附带文件figma-merge.mjsfigma-scan.mjs

详细介绍

/understand-figma

分析 Figma 文件，并在现有仪表板中生成交互式设计知识图谱。

前置条件

  • FIGMA_TOKEN 环境变量 — Figma 个人访问令牌（在 https://www.figma.com/settings 创建）。如果缺少此变量，立即停止并告知用户：

    请先设置 Figma 令牌：在 figma.com/settings 创建令牌，然后运行 export FIGMA_TOKEN=<token>。

  • Node ≥ 22，pnpm ≥ 10。

安全性： 令牌只从环境中读取，并且仅通过 X-Figma-Token 请求标头传输。切勿将其写入图谱、meta.json、日志或中间文件。此技能会向 api.figma.com 发起外部请求 — 与 /understand 不同，它并非完全离线。只需告知用户一次。

阶段 0 — 预检

  1. 解析 $ARGUMENTS，获取 Figma URL 或裸文件键（非标志参数），以及可选的 --language <lang>。
  2. 将 PROJECT_ROOT 解析为当前工作目录。解析数据目录 $UA_DIR 一次，并在下方每次读取和写入时重复使用：UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)" — 如果旧版 .understand-anything/ 已存在，则使用它；否则使用新的 .ua/。由于每个阶段都可能在新的 shell 中运行，请像保留 $PROJECT_ROOT 一样保留 $UA_DIR；如果后续命令块需要重新解析，则使用相同的命令行。
  3. 解析 PLUGIN_ROOT，并确保 core 已构建（使用与 /understand 阶段 0.1.5 相同的逻辑）。如果 packages/core/dist/figma/index.js 不存在，则运行： 
    cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
  4. mkdir -p $UA_DIR/intermediate。

阶段 1 — 获取并解析（确定性）

运行捆绑的扫描脚本（<SKILL_DIR> 是此技能所在目录）：

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

脚本会写入 $UA_DIR/intermediate/scan-manifest.json 并输出节点数量。将数量告知用户。如果脚本以非零状态退出，则转达 stderr 并停止。

如果扫描输出 UP_TO_DATE，请报告“此 Figma 文件版本的设计图谱已是最新”并停止。若要强制完整重建，请在环境中设置 UNDERSTAND_FIGMA_FORCE=1 后重新运行。

阶段 2 — 分析（LLM 增强）

  1. 读取 scan-manifest.json。将节点分组为每批约 15 个，尽可能按页面分组。
  2. 对每个批次，使用 design-analyzer Agent 定义（agents/design-analyzer.md）分派一个子 Agent。传入：
    • 该批次的节点（id、type、name、figmaMeta、子节点名称、令牌用量），
    • 所有现有节点 ID 的完整列表，
    • $INTERMEDIATE_DIR = $UA_DIR/intermediate，
    • 用于输出文件命名的批次编号。 Agent 会写入 analysis-batch-<N>.json。 如果提供了 --language，请附加 $LANGUAGE_DIRECTIVE（重复使用 /understand 的指令文本）。
  3. 最多同时运行 5 个批次。如果某批次失败，记录警告并继续 — 清单是可靠的基础。

阶段 3 — 合并

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

此步骤会合并 scan-manifest.json 和 analysis-batch-*.json，运行 mergeDesignGraph（验证并重新附加 kind:"design"），然后写入 knowledge-graph.json 和 meta.json。转达输出的统计数据，以及任何非 auto-corrected 的问题。

阶段 4 — 保存并启动

  1. 清理中间文件，保留 scan-manifest.json： 
    INTER="$UA_DIR/intermediate"
find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +
  2. 汇总报告：项目名称、按节点类型统计的数量、按类型统计的边数、图层、导览步骤，以及路径 $UA_DIR/knowledge-graph.json。
  3. 调用 /understand-dashboard 技能自动启动仪表板。

评论

支持 Markdown