使用说明

AI快乐设计

让AI完全控制你的Figma画布。

一个Go二进制文件，可用作 ahd-figma 以及遗产 ai-happy-design 命令，通过本地WebSocket中继将任何AI（Claude、GPT、Gemini等）连接到Figma。从自然语言进行设计、检查、编辑和导出。

由……制造阿什拉夫·阿里 | GitHub |MIT许可证

截图

建筑

AI / LLM              CLI (scripting)
   |                    |
   v                    v
[MCP Server] -----> [WebSocket Relay] <-----> [Figma Plugin]
                    localhost:3055

一个二进制。三种模式：

MCP服务器 --AI编辑器（Claude Code、Cursor、Windsurf等）的模式支持集成
命令行界面 --直接命令和批处理有效载荷。 批量操作比MCP快10-50x 因为它通过一个WebSocket连接发送单个批有效载荷，而不是单独的MCP工具调用。AI代理可以使用CLI进行繁重的工作。
中继 --WebSocket桥接到Figma插件

包含内容

15个工具域：绘画、形状、文本、布局、节点、图层、组件、样式、变量、效果、布尔值、页面、文档、导出、设计
模式支持的MCP: ahd-figma mcp 公开与CLI相同的命令模式，以及模式、工具和设计指南的资源
当前Figma上下文API：使用以下命令检查以开发模式为中心的节点 document.get_focused_node 并生成CSS node.get_css
批量操作：在一个有效载荷中使用步进插值连接150+个命令(${{steps.name.result.id}})，每次操作定时统计，约27次操作/秒
智能画布放置: document.find_free_space 扫描现有帧并返回精确坐标——人工智能从不猜测在哪里放置新设计
设计代币: design.compute_tokens 自动计算任何画布大小的字体、间距、填充和布局，无需Figma连接
设计智能：AI可以调用内置设计指南来学习排版、平衡、视觉层次和CSS到Figma的翻译
自动注册: ahd-figma register 检测已安装的AI编辑器并自动配置MCP
Unicode安全：完全支持表情符号、CJK、重音字符、em破折号和特殊字符
仅限本地：所有内容都在本地主机上。没有任何东西离开你的机器。

快速开始

1.安装

从下载最新二进制文件 GitHub发布:

# macOS (Apple Silicon)
curl -L https://github.com/nerveband/ai-happy-design/releases/latest/download/ai-happy-design_Darwin_arm64.tar.gz | tar xz
sudo mv ai-happy-design /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/nerveband/ai-happy-design/releases/latest/download/ai-happy-design_Darwin_x86_64.tar.gz | tar xz
sudo mv ai-happy-design /usr/local/bin/

# Linux
curl -L https://github.com/nerveband/ai-happy-design/releases/latest/download/ai-happy-design_Linux_x86_64.tar.gz | tar xz
sudo mv ai-happy-design /usr/local/bin/

从源头建设？ 跑 codesign -s - ai-happy-design 在macOS上构建后。发布二进制文件已预先签名。

2.安装插件

ahd-figma setup

这会提取嵌入式Figma插件，并打开Finder到清单文件。

Figma桌面→ 插件>开发>从清单导入插件
选择显示的 manifest.json
运行： 插件>AI快乐设计

3.向您的AI编辑器注册

ahd-figma register

自动检测已安装的编辑器（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed）并注册MCP服务器。或向特定编辑注册：

ahd-figma register --editor "Claude Code"
ahd-figma register --editor "Cursor"

手动设置 （如果你愿意的话）：

Claude Code

claude mcp add ahd-figma -- ahd-figma mcp

或添加到 ~/.claude.json:

{
  "mcpServers": {
    "ahd-figma": {
      "type": "stdio",
      "command": "ahd-figma",
      "args": ["mcp"]
    }
  }
}

Claude Desktop / Cursor / Windsurf

添加到MCP配置文件中：

{
  "mcpServers": {
    "ahd-figma": {
      "command": "ahd-figma",
      "args": ["mcp"]
    }
  }
}

注册后重新启动编辑器。MCP服务器会自动检测中继是否已在运行并作为客户端连接，无需单独启动中继。

3.5可选：安装AI技能包

如果你想要一个现成的技能来帮助AI代理调用CLI并遵循发现优先的工作流程，请使用打包的捆绑包：

ai-happy-design.skill （回购根，也适合作为发布资产）

这是可选的；MCP服务器和CLI在没有它的情况下工作。

4.验证

ahd-figma tools --json       # List all tools
ahd-figma command document.get_info   # Test connection

5.升级

ahd-figma upgrade

每天自动检查更新并通知您。升级下载并安装新的二进制文件。

运作原理

与AI代理一起使用（推荐）

AI Happy Design附带了 技能档案 它教AI代理如何使用CLI。当您调用该技能时，代理将获得完整的命令引用、批处理格式、复合命令、设计标记和最佳实践。

选项A：调用技能 （如果通过技能共享或 ~/.claude/skills/):

“使用ai的快乐设计技巧，创建一个关于[主题]的5页Instagram旋转木马”

选项B：告诉AI直接使用CLI：

“使用ai happy设计CLI设计一个关于[主题]的Instagram帖子。运行 ahd-figma command design.compute_tokens 首先是尺寸。"

该技能是首选方法——它一次性为AI提供了所需的一切，包括复合命令格式、批别名、设计令牌工作流和常见陷阱。

安装技能

技能档案(SKILL.md)教导AI代理如何有效地调用CLI。

# If using skillshare (syncs to all AI tools automatically)
# The skill is already at ~/.claude/skills/ai-happy-design/SKILL.md

# Or copy manually for Claude Code
mkdir -p ~/.claude/skills/ai-happy-design
cp path/to/SKILL.md ~/.claude/skills/ai-happy-design/SKILL.md

技能教给人工智能什么

计算令牌 --获取目标画布的比例字体大小和间距
查找可用空间 --获得精确的坐标，这样设计就不会重叠
测量和拟合文本 --使用 text.measure 和 text.fit_box 在锁定密集布局之前
用CSS思考 --起草类似HTML/CSS的结构，然后将部分转换为Figma命令
批量创建 --编写复合命令， text.create_rich_block, layout.pricing_grid，或原始操作
导出和迭代 --与参考进行比较，调整批次，然后重新运行

CLI使用情况

CLI是驱动Figma操作的最快方式-- 建议AI代理进行批量工作.

单个命令

ahd-figma command paint.set_solid -p '{"nodeId":"1:2","color":"#2563EB"}'

批量操作（最快）

# From file — send 100+ operations in one shot:
ahd-figma batch -f payload.json

# Inline:
ahd-figma batch -o '[{"name":"card","command":"node.create_frame","params":{"width":320,"height":200}}]'

列出可用操作

ahd-figma actions           # All domains and actions
ahd-figma actions document  # Just document actions
ahd-figma tools --llm       # Full LLM-focused catalog with examples

中继管理

ai-happy-design relay start      # Background start
ai-happy-design relay status     # Check connection
ai-happy-design relay logs       # View logs
ai-happy-design relay stop       # Stop

通道分辨率顺序

定位参数
--channel 旗帜
AHD_CHANNEL env 是
继电器的活动通道（自动检测）

导出格式

将任何节点导出为PNG、JPG、SVG或PDF：

ahd-figma command export.image '{"nodeId":"47:765","format":"PNG","scale":2}' -o output.png
ahd-figma command export.image '{"nodeId":"47:765","format":"JPG","scale":1}' -o output.jpg
ahd-figma command export.svg '{"nodeId":"47:765"}' -o output.svg
ahd-figma command export.pdf '{"nodeId":"47:765"}' -o output.pdf

SVG导出保存为原始SVG文本。PNG/JPG/PDF是由base64编码的。这 -o flag指定输出路径；没有它，文件名将根据节点名称自动生成。

复合命令（v0.10+）

编写一个高级命令，得到一个完整的Figma幻灯片或横幅。复合材料通过设计标记、渐变和布局自动扩展为5-15个基本操作。

# One slide command → 7-15 Figma operations
ahd-figma batch '[{
  "name": "s1",
  "command": "slide",
  "params": {
    "canvas": "1080x1350",
    "color": "#0C1E2C",
    "gradient": {"type":"LINEAR","angle":150,"stops":[
      {"color":"#0C1E2C","position":0},{"color":"#14344A","position":1}
    ]},
    "elements": [
      {"type": "eyebrow", "text": "RAMADAN 2026", "color": "#7FBCD2"},
      {"type": "headline", "text": "The Care\nBehind\nthe Care", "tier": "hero"},
      {"type": "bar", "color": "#029056"},
      {"type": "body", "text": "250+ chaplains serve.", "color": "#FAFCFBB3"},
      {"type": "cta", "text": "Donate Now", "bg": "#029056"},
      {"type": "url", "text": "example.com/donate"}
    ]
  }
}]'

元素类型： eyebrow, headline, body, bar, cta, url, counter, stats, progress, arabicBanner命令支持 headline 和 subtitle.

HTML → Figma（v0.10+）

从样式化的HTML文件中直接提取幻灯片和横幅到Figma中：

# Parse HTML/CSS → composite batch JSON
ahd-figma extract social-posts.html --width 1080 --height 1350

# Full pipeline: HTML → Figma in one line
ahd-figma extract input.html -o /tmp/ops.json && ahd-figma batch /tmp/ops.json

extract命令解析 <style> 块、内联样式、渐变、颜色和字体权重。每 .slide 成为 slide 复合命令，每个 .email-banner 成为 banner.

对于从屏幕截图或HTML/CSS参考中获得的高保真娱乐，请使用测量的工作流程：

检查参考文献 node.get_css 当匹配现有的Figma节点时，或者自己总结HTML/CSS结构。
使用以下方法测量关键副本 text.measure；将受约束的标签与 text.fit_box.
使用 text.create_rich_block 用于分组标题、价格、项目符号和注释。
使用 layout.pricing_grid 用于类似CSS的卡片网格，而不是手动定位每个文本节点。
导出、直观比较，然后调整同一批处理文件中的间距、排版和内容。

看 docs/examples/html-css-recreation-workflow.json 用于紧凑的可执行样式有效负载。

基准测试（v0.10+）

提供程序-诊断性能测量-未内置LLM API调用：

# Time batch execution against Figma
ahd-figma benchmark exec ops.json --runs 3

# Time external LLM + execution (pipe any LLM output)
START=$(date +%s%N)
BATCH=$(curl -sS your-llm-api... | jq -r '.choices[0].message.content')
MS=$(( ($(date +%s%N) - START) / 1000000 ))
echo "$BATCH" | ahd-figma benchmark pipe --phase-a-ms $MS

演出

场景	时间	操作/秒
单滑（复合）	~1.4s	6-8
5滑转盘（20次操作）	~2.8秒	7.3秒
36帧战役（146次行动）	~18秒	8.1
E2E与Cerebras LLM（1张幻灯片）	~2.0s	--

CLI批处理通过一个WebSocket连接发送所有操作。MCP单独发送每个工具调用。对于具有20多个操作的设计，CLI批处理速度要快得多。

批量输出包括每次操作 elapsedMs 和一个 timing 总结与 totalMs, avgMs，以及 opsPerSec.

行为准则

做：

发现与 ahd-figma tools --llm --json，MCP tools/list，或 ahd_describe
呼叫 document.find_free_space 在创建新帧之前，它返回精确的坐标
呼叫 design.compute_tokens 调整画布的尺寸
使用CLI批处理进行多元素设计（3+个元素）
使用 document.get_focused_node 和 node.get_css 在匹配现有Figma上下文之前
使用 绝对x/y定位 用于主布局+仅用于徽章/按钮的自动布局
总是通过 lineHeightUnit: "PERCENT" 和 text.set_line_height （默认为像素）
以规模=2出口，以获得清晰的输出
以描述性的方式命名每个元素

不要：

猜测帧位置——始终使用 find_free_space
将卡片创建为带有浮动文本的矩形（使用带孩子的框架）
保留默认名称，如“Frame 47”
在1080px社交媒体画布上使用16px以下的文本
在兄弟卡之间混合填充/间距值
使用 lineHeight: 140 没有 lineHeightUnit: "PERCENT" （140像素！=140%）
跳过对兄弟元素的余额检查

故障排除

问题	修复
插件“已断开连接”	启动继电器： `ahd-figma relay start`
命令失败	运行 `ahd-figma tools --llm --json` 或MCP `tools/list` 重新发现工具
错误端口	在插件UI中编辑中继URL
通道不匹配	从插件复制密钥，传递 `--channel`
插件无法加载	运行 `ahd-figma setup --force` 重新提取
二进制在macOS上被终止（源代码构建）	运行 `codesign -s - /path/to/ahd-figma`
MCP未在编辑器中加载	运行 `ahd-figma register --force` 重新注册

先决条件

Figma桌面应用程序
转到1.21+（仅适用于从源代码构建）
Node.js 18+（仅用于从源代码构建）

所有命令

命令	描述
`ahd-figma setup`	解压并安装Figma插件
`ahd-figma register`	使用检测到的AI编辑器自动注册MCP
`ahd-figma mcp`	启动MCP服务器（用于AI编辑器的stdio传输）
`ahd-figma ws`	仅启动WebSocket中继
`ahd-figma command <action>`	执行单个命令
`ahd-figma batch`	执行一批命令
`ahd-figma actions`	列出所有域动作对
`ahd-figma tools`	打印工具目录
`ahd-figma extract <file.html>`	将HTML/CSS解析为批量JSON
`ahd-figma benchmark exec/pipe`	与提供商无关的性能基准测试
`ai-happy-design relay start/stop/status/logs`	管理中继过程
`ahd-figma upgrade`	升级至最新版本

使用场景

场景1：从提示中设计AI代理

调用技能，然后描述你想要什么：

你： “利用ai的快乐设计技巧，创建一个关于穆斯林牧师的5页Instagram旋转木马”

或者，如果技能是自动加载的（通过技能共享或克劳德代码设置）：

你： “设计一个关于菲马穆斯林牧师的5页Instagram旋转木马”

AI读取技能，然后使用CLI：

ahd-figma command design.compute_tokens '{"width":1080,"height":1350}' --尺寸
ahd-figma command document.find_free_space '{"width":1080,"height":1350}' --安置
写入复合 slide 命令转换为JSON文件
ahd-figma batch /tmp/slides.json --在Figma中创建一切
ahd-figma command export.image '{"nodeId":"...","scale":2}' --验证

场景2:JSON文件中的CLI批处理

编写（或让AI生成）一个JSON批处理文件并直接执行：

# Create a batch file with composite commands
cat > /tmp/slides.json << 'EOF'
[
  {"name":"s1","command":"slide","params":{"canvas":"1080x1350","color":"#1a1a2e",
    "elements":[
      {"type":"headline","text":"Hello World","tier":"hero"},
      {"type":"body","text":"Made with AI Happy Design","color":"#ffffffB3"}
    ]}}
]
EOF

# Execute against Figma
ahd-figma batch /tmp/slides.json

场景3:HTML文件→ Figma

有设计师的HTML规范吗？在一个管道中提取和执行：

# Two-step (inspect the JSON first)
ahd-figma extract mockup.html --width 1080 --height 1350 -o /tmp/ops.json
ahd-figma batch /tmp/ops.json

# One-liner
ahd-figma extract mockup.html -o /tmp/ops.json && ahd-figma batch /tmp/ops.json

场景4:LLM生成JSON，CLI执行

使用任何LLM（Cerebras、OpenAI、Claude API、本地模型）生成批处理JSON，然后将其管道传输到CLI：

# Cerebras (fast, cheap)
curl -sS https://api.cerebras.ai/v1/chat/completions \
  -H "Authorization: Bearer $CEREBRAS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen-3-235b-a22b-instruct-2507","messages":[
    {"role":"system","content":"Output ONLY a JSON array of slide composite commands."},
    {"role":"user","content":"Create a fundraiser slide, 1080x1350, dark blue theme"}
  ]}' | jq -r '.choices[0].message.content' | ahd-figma batch

# OpenAI
curl -sS https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o","messages":[
    {"role":"system","content":"Output ONLY a JSON array of slide composite commands."},
    {"role":"user","content":"Create a fundraiser slide"}
  ]}' | jq -r '.choices[0].message.content' | ahd-figma batch

场景5：多文件批处理

一次执行多个JSON文件或整个目录：

ahd-figma batch slides.json banners.json     # two files
ahd-figma batch ./campaign/                    # all .json in directory
ahd-figma batch *.json --parallel              # concurrent (max 4)

场景6：基准测试您的管道

衡量任何LLM提供商的端到端性能：

# Just measure execution speed
ahd-figma benchmark exec ops.json --runs 3

# Measure LLM generation + execution
START=$(date +%s%N)
JSON=$(curl -sS your-llm... | jq -r '.choices[0].message.content')
MS=$(( ($(date +%s%N) - START) / 1000000 ))
echo "$JSON" | ahd-figma benchmark pipe --phase-a-ms $MS

文档

看 docs/ 有关详细指南：

许可证

麻省理工学院——见许可证.