AI Happy Design

AI快乐设计

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

一个Go二进制文件，通过本地WebSocket中继将任何AI（Claude、GPT、Gemini等）连接到Figma。设计、编辑和导出——全部来自自然语言。

由……制造 阿什拉夫·阿里 | |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插件

包含什么

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

快速开始

1.安装

从下载最新二进制文件 :

# 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.安装插件

ai-happy-design setup

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

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

3.向您的AI编辑器注册

ai-happy-design register

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

ai-happy-design register --editor "Claude Code"
ai-happy-design register --editor "Cursor"

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

Claude Code

claude mcp add ai-happy-design -- ai-happy-design mcp

或添加到 ~/.claude.json:

{
  "mcpServers": {
    "ai-happy-design": {
      "type": "stdio",
      "command": "ai-happy-design",
      "args": ["mcp"]
    }
  }
}

Claude Desktop / Cursor / Windsurf

添加到MCP配置文件中：

{
  "mcpServers": {
    "ai-happy-design": {
      "command": "ai-happy-design",
      "args": ["mcp"]
    }
  }
}

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

3.5可选：安装AI技能包

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

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

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

4.验证

ai-happy-design tools --json       # List all tools
ai-happy-design command document.get_info   # Test connection

5.升级

ai-happy-design upgrade

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

运作原理

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

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

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

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

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

“使用ai happy设计CLI设计一个关于\[主题\]的Instagram帖子。运行 ai-happy-design 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

技能教给人工智能什么

1. 计算令牌 --获取目标画布的比例字体大小和间距
2. 查找可用空间 --获得精确的坐标，这样设计就不会重叠
3. 用CSS思考 --在脑海中起草HTML/CSS，然后翻译成Figma命令
4. 批量创建 --写复合 slide/banner 命令或基本操作
5. 导出和验证 --目视检查结果

CLI使用情况

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

单个命令

ai-happy-design command paint.set_solid -p '{"nodeId":"1:2","color":"#2563EB"}'

批量操作（最快）

# From file — send 100+ operations in one shot:
ai-happy-design batch -f payload.json

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

列出可用操作

ai-happy-design actions           # All domains and actions
ai-happy-design actions document  # Just document actions
ai-happy-design 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

通道分辨率顺序

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

导出格式

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

ai-happy-design command export.image '{"nodeId":"47:765","format":"PNG","scale":2}' -o output.png
ai-happy-design command export.image '{"nodeId":"47:765","format":"JPG","scale":1}' -o output.jpg
ai-happy-design command export.svg '{"nodeId":"47:765"}' -o output.svg
ai-happy-design 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
ai-happy-design 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
ai-happy-design extract social-posts.html --width 1080 --height 1350

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

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

基准测试（v0.10+）

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

# Time batch execution against Figma
ai-happy-design 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" | ai-happy-design benchmark pipe --phase-a-ms $MS

演出

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

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

行为准则

做：

• 呼叫 describe(action="catalog") 在构建命令之前
• 呼叫 document.find_free_space 在创建新帧之前，它返回精确的坐标
• 呼叫 design.compute_tokens 调整画布的尺寸
• 使用批次(bulk.execute)用于多元素设计（3+元素）
• 使用 绝对x/y定位 用于主布局+仅用于徽章/按钮的自动布局
• 总是通过 lineHeightUnit: "PERCENT" 随着 text.set_line_height （默认为像素）
• 以规模=2出口，以获得清晰的输出
• 以描述性的方式命名每个元素

不要：

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

故障排除

先决条件

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

所有命令

使用场景

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

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

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

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

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

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

1. ai-happy-design command design.compute_tokens '{"width":1080,"height":1350}' --尺寸
2. ai-happy-design command document.find_free_space '{"width":1080,"height":1350}' --安置
3. 写入复合 slide 命令转换为JSON文件
4. ai-happy-design batch /tmp/slides.json --在Figma中创建一切
5. ai-happy-design 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
ai-happy-design batch /tmp/slides.json

场景3:HTML文件→ Figma

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

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

# One-liner
ai-happy-design extract mockup.html -o /tmp/ops.json && ai-happy-design 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' | ai-happy-design 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' | ai-happy-design batch

场景5：多文件批处理

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

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

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

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

# Just measure execution speed
ai-happy-design 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" | ai-happy-design benchmark pipe --phase-a-ms $MS

文档

看 docs/ 有关详细指南：

• 入门指南
• 大语言模型集成
• CLI批处理和有效负载
• 图像填充合同
• 故障排除

许可证

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