前言¶

DSH 的对话模型要理解一份设计稿，常见的做法是把 Figma 链接贴给模型，让它去猜；或者自己写脚本调 Figma API，把返回的 JSON 再喂给模型。前者容易得出错误结论，后者要自己处理节点树、颜色、样式、限流和令牌。下面介绍的 figma-mcp-dsh 把这件事做成了 DSH 插件：模型在对话里直接调用工具读文件结构、颜色、字体、组件和样式，还能把指定 Frame 渲染成图片看。

它由 N107meow 维护，在社区目录里归类为联网工具（当前目录显示 1 stars），README 明确定位为「面向 DeepSeek Harness 的只读 Figma 插件」，许可证 MIT。

这是什么¶

一句话：figma-mcp-dsh 让 DSH 里的模型以只读方式理解 Figma 设计文件，而不是靠猜或靠你手工整理。

它解决三类具体问题：

1. 模型拿到链接也读不到文件内容，只能凭空推断布局、颜色和字体；
2. Figma 的节点树很深，一次性取回来会占满上下文；
3. 设计文件是云端资产，随意写回会造成事故。

插件只走 Figma 的只读接口，不修改云端文件。

核心能力¶

README 列出的能力，按用途归一下：

• 结构：读取文件、页面和节点结构；按 node id 读取子树。
• 视觉属性：提取颜色（含渐变各色标）、字体层级、布局与尺寸；识别自动布局的对齐与换行、遮罩、旋转角度，避免模型对倾斜或被裁剪的图层得出错误结论。
• 组件体系：识别本地组件、组件集、变体和样式。
• 图像：把指定 Frame 导出为图片，作为图片内容返回给模型，当轮可见。
• 上下文控制：自动限制读取深度；结果过大时返回摘要，完整结果写入本地 .figma/。
• 稳定性：处理限流、令牌失效、权限不足等常见问题。

模型侧只暴露两个工具：figma_capabilities（查看可用能力，传 detail="full" 拿完整参数说明）和 figma_call（执行具体读取，用 op 选能力、target 传链接）。

支持的 7 个 op：

分析单个页面或 Frame 时，README 推荐用 file_nodes 作为入口；链接含 node-id 时插件会自动解析节点，未指定深度时用 depth=2。

安装与启用¶

插件以 bundle 形式发布：装进 profile 后自动挂载，新安装不需要手工改 cordis.patch.yml。桌面 App 固定用 desktop profile，dsh web 默认用 web，两个 edition 的 profile 相互独立，要用两边就各装一次。

桌面版：桌面 App → Settings → Plugins → Add plugin → 输入 figma-mcp-dsh → Install / Enable；提示重启就重启。装完插件管理器会把 figma-mcp-dsh 写进 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles，再由包内的 cordis.patch.yml 插入 figma 行。

Web 版有两种入口，CLI 命令如下：

dsh plugin --profile web add figma-mcp-dsh

从 GitHub 装也可以，同样走 plugin manager，会自动加 bundle：

dsh plugin --profile web add github:N107meow/figma-mcp-dsh

装完确认已挂载：

dsh --profile web --dump-config | grep -A2 -- "- id: figma"

能看到 - id: figma / name: figma-mcp-dsh 就对了。旧版安装、link: 开发或自动加 bundle 失败时，需要在 ~/.dsh/profiles/<name>/cordis.patch.yml 手动追加：

- insert:
    - id: figma
      name: figma-mcp-dsh

注意：如果 bundle 已经在 dsh.profile.bundles 里，再加这一行会产生同 id 重复项，README 提到实测不报错但后者生效，仍应删掉重复项。

还有两条容易踩的路：

• pnpm add figma-mcp-dsh 只装依赖，不会把包选进 dsh.profile.bundles，插件不会被挂载，必须再手动加那一行。
• 升级不一定自动进 bundles。插件管理器只在「新装」时把它选进去，升级后建议按上面那条命令再确认一次。

版本门槛要留意：0.2.0 需要 DSH >= 0.2.0-rc.2（已实测桌面 App 0.2.1-rc.3、Web 版 0.2.1-rc.2 与 0.2.0-rc.2），DSH 0.1.x 请留在 figma-mcp-dsh@0.1.3，不要升级。DSH 会校验插件的 peerDependencies，不匹配时安装直接被拒绝，README 建议选对版本而不是用 dsh plugin allow-version 绕过。两个版本都能从 GitHub 装，对应 tag：

# 新版（bundle，自动挂载）
dsh plugin --profile web add github:N107meow/figma-mcp-dsh#v0.2.0

# 旧版（0.1.x 用户）
dsh plugin --profile web add github:N107meow/figma-mcp-dsh#v0.1.3

从 0.1.x 迁移时顺序重要：先确认新版本已装好且已在 dsh.profile.bundles 里，再从 cordis.patch.yml 删掉 0.1.x 时代手工加的 figma 行，顺序反了会出现「装了但没挂载」的状态。

配置 Figma 令牌¶

插件需要一个有目标文件访问权限的 Figma Personal Access Token，只读 scope 四个：

file_content:read
file_metadata:read
file_comments:read
file_dev_resources:read

凭据写到 ~/.dsh/.credentials.yaml，两个 edition 共享，只需要配一次：

refs:
  FIGMA_TOKEN: your_figma_token_here

也可以用环境变量 FIGMA_TOKEN。插件每次调用都重新读取凭据，换令牌不需要重启 DSH。

拿令牌的三步（细节见仓库的 docs/TOKEN_SETUP.md）：在 Figma 左上角点头像进设置；切到安全标签页，找到个人访问令牌，点生成新的令牌；填名称、选有效期（建议 90 days）、只勾上面四个只读 scope，生成后立刻复制——明文只显示一次。

典型用法¶

装完在 DSH 对话里贴链接、直接描述要看什么即可：

分析这个 Figma Frame 的布局、主要颜色和字体层级：
https://www.figma.com/design/your_file_key/project?node-id=12-345

也可以明确指派操作：

读取这个文件中定义的组件和变体。
把 node 101:202 渲染成图片并分析视觉层级。
列出这个设计文件中的颜色样式和文字样式。

需要直接调工具时，用 figma_call：

figma_call({
  op: "file_nodes",
  target: "https://www.figma.com/design/your_file_key/project?node-id=12-345",
})

适用场景与注意¶

适合已经在 DSH 上做设计稿分析、设计稿转实现、批量检查规范的人：模型需要真实结构而不是猜测，同时又不希望模型有写回云端文件的权限。它只读，正好卡在这个边界上。

几个使用上的点：

• 插件以当前 DSH 进程的权限运行。安装第三方插件前应自己打开源码核对，确认它只声明 GET 请求、不做重定向跟随、不把令牌带到非 Figma 域名。README 在「安全与隐私」一节逐条说明了这些约束，另有 npm run check:secrets 扫描待提交文件和 Git 历史里的令牌。
• 大型结果会先缩小深度重试一次，仍过大就返回摘要并把完整结果写入本地 .figma/（该目录不进 Git）；渲染图片保存在 .figma/images/，同时写入 DSH 附件存储并作为图片内容返回当前对话。
• 请求排队是故意的：插件用保守默认额度保护 Figma 配额，收到 429 后按响应头调整限流参数。
• 没有 Variables 能力：Figma Variables API 仅向 Enterprise 组织开放并要求额外权限，插件当前不提供。

链接¶

• 目录页：https://www.skillhub.cn/plugins/N107meow/figma-mcp-dsh
• GitHub：https://github.com/N107meow/figma-mcp-dsh

本项目与 Figma 无隶属关系，也未获得 Figma 官方背书。