Flamo Design 插件

flamo-design 是 Flamo 的 Codex 插件，可创作、修改和检查设计，并协助导出组件接入你的产品。它通过 Flamo Design MCP 查询和修改 Artifact，无需 Figma。所有公开插件与安装方式见 插件中心。

安装插件

下载 Flamo Codex 插件包，解压后会得到 flamo-codex 文件夹。在该文件夹的上一级目录执行：

codex plugin marketplace add ./flamo-codex
codex plugin add flamo-design@flamo

终端需要能执行 codex 命令。安装或更新后重启 Codex 并新建对话，让插件和工具重新加载。公开插件包包含 Flamo Design 及其设计生成、矢量重建和审查技能。

插件包已经配置线上地址，不需要 Flamo 框架源码、Bun 或本地 Flamo Server：

插件	MCP 地址	用途
flamo-design	https://flamo.dev/mcp/design	Artifact 创作、验证及导出组件的宿主接入

登录与使用资格

1. 打开 Codex「设置 → 插件」，切换到「MCP」标签，在「来自插件」中找到 flamo-design，点击「进行身份验证」（英文为 Authenticate）。部分版本还提供独立的「MCP 服务器」设置入口。Codex 会在浏览器中打开 Flamo 登录授权页，无需输入授权命令。
2. 使用 Flamo 账号登录，确认页面显示的账号和插件名称，点击「授权连接」。浏览器随后返回 Codex 的本机回调地址。
3. 有效试用用户和付费订阅用户均可使用 MCP。资格沿用 Flamo 账号的试用与订阅状态；试用或订阅到期后，服务停止接受工具请求。
4. 对 Codex 说：“使用 flamo-design 列出我的 Flamo 工程，让我选择一个开始设计。”AI 会先调用 flamo_design_projects。

授权仅允许访问当前账号拥有的线上工程。你电脑里的本地目录不会自动成为线上工程；素材需要先保存或上传到对应的 Flamo 工程。需要 Runtime 截图或字体验证时，在 Studio 打开对应工程，并按工具返回的连接要求操作。

MCP 使用权限不包含 Codex 的模型额度，也不替代 Studio 的个人模型服务授权。不要在插件配置、对话或源码中填写账号密码、Studio token 或 MCP 访问令牌。

授权失效与撤销

访问令牌会短期过期，Codex 可使用刷新令牌自动续期；刷新授权最长保留 30 天。需要重新登录时，在 Codex「设置 → 插件 → MCP → 来自插件」中找到 flamo-design 并点击「进行身份验证」，随后在浏览器确认「授权连接」。重新打开应用不能恢复已撤销的授权。

如果这一行没有身份验证按钮，可以对 Codex 说：“请替我发起 Flamo Design 授权，打开浏览器让我确认，不要让我输入命令。”Codex 可以使用本机已安装的原生授权流程发起连接；账号登录和授权确认仍由你在浏览器完成。部分版本仅在状态为“未登录”时显示按钮，保存了失效凭据或网络发现失败时，按钮可能暂时缺失。

在 管理 MCP 连接 中可以撤销授权。撤销后，原客户端需要再次登录并确认授权。账号被禁用、试用结束或订阅失效时，现有连接也不能继续调用工具。

情况	处理方法
提示需要登录或授权失效	在「插件 → MCP」中点击「进行身份验证」，并在 Flamo 页面确认授权
插件行没有身份验证按钮	请 Codex 代为发起本机原生授权流程，在浏览器登录并确认；不要粘贴密码或令牌
已授权但发现工具或读取工程超时	检查本机到 Flamo 的网络与代理路由；授权成功和 MCP 实际可用需要分别验证
提示需要有效试用或订阅	在 Studio 查看账号状态
找不到工程或没有权限	确认登录账号，并使用工程列表返回的 canonical projectId
MCP 工具仍是旧版本	更新插件后新建 Codex 对话

授权完成后，让 Codex 列出你的 Flamo 工程并读取所选工程的能力。插件启用或显示 OAuth 状态，只能说明客户端配置与认证状态；实际读取成功才证明连接可用。

宿主集成导出组件

通过 MCP 导出

flamo_component_export 可直接把线上工程中的指定节点导出为 Web Component，无需打开 Studio 的导出菜单。AI 先读取节点和 Artifact revision，以相同 clientMutationId 依次提交 dryRun: true、dryRun: false。导出返回固定的 contractId、ZIP 字节数、SHA-256 和有效十分钟的下载地址；AI 可直接下载、校验并安装到你指定的宿主目录。

相同参数和请求 ID 的重试复用同一 ZIP。地址过期或服务重启后，重复原请求可取得新地址；工程版本冲突时需要重新核对源设计。临时地址只授权这一份 ZIP，请勿公开或提交到仓库。打包成功后仍需验证实际交互和画面。

插件操作范围是当前账号的用户工程和你授权的宿主目录。用户任务不能修改 Flamo 框架、官方库、服务器配置或部署文件；服务端没有隔离容器执行器时，会拒绝执行用户脚本并返回 TASK_ISOLATION_REQUIRED。框架缺陷应交给单独授权的框架维护任务。

导出的组件包含接入描述和 AGENTS.md，会指引 AI 使用 flamo-design，并提供精确的 projectId 与 contractId。AI 可据此调用 flamo_component_resolve、context、api、plan 和 verify，读取注释要求、生成宿主接入代码并核对浏览器观察。导出文件不能替你安装插件或完成登录；接入对应线上工程仍需工程所有者授权。

在线工程开发

需要动画、交互脚本或工程代码时，可以对 Codex 说：“使用 Flamo Design，在这个线上工程中实现飞鱼星空和紫色流星碰撞，并验证交互效果”，附上 Studio 工程链接即可。插件通过 flamo_project_task_* 工具调用服务器的 Codex 执行链，直接写入你的线上工程，不需要本地开发后再上传源码。

先在 Studio 左下角头像的模型配置中连接自己的模型服务。插件 OAuth 负责确认 Flamo 身份和工程归属，服务器执行使用这个账号配置的模型；两项授权用途不同。

工具	用途
flamo_project_task_capabilities	检查工程版本、模型准备状态、组件脚本能力和工程 API 快照
flamo_project_task_start	提交需求，立即取得后台任务 ID
flamo_project_task_status	分页读取进度、回复、修改文件和版本对应的验收状态
flamo_project_task_continue	在任务空闲后继续修改或修复
flamo_project_task_cancel	取消当前任务

每次操作都根据 OAuth 身份核对工程归属，任务还需匹配原用户和工程。提交和继续任务需要当前 Artifact revision 与稳定请求 ID，重复请求不会重复启动。排队期间工程发生更新时，任务会报告冲突；执行完毕也会检查工程是否被其他操作修改。

完成后回到对应 Studio 工程查看修改并运行 Preview。build-verified 表示编译和绑定检查通过，真实交互与画面验收需要对应版本的浏览器证据。服务器 Worker 只修改当前用户工程，框架源码修复属于独立的框架开发工作。

工作流

从 0.9.0 开始，插件读取 component-script-capabilities-v1 能力合同。flamo_design_capabilities 和 flamo_project_task_capabilities 的 componentScripts 描述相同的服务器能力，工程工具另返回 projectScriptApi 内容哈希对照。服务器写脚本的 AI 获得同一份指引；能力缺失或工程 API 不一致时先更新服务器、插件或完成授权的工程能力初始化，不走旧版回退。

0.10.0 增加 animation-p0-v1：仅封装 P0 骨骼与蒙皮、动态表面与显式遮罩、统一时间轴及明确格式的 Figma Motion 交换。插件通过 flamo_animation_capabilities 发现接口，flamo_animation_validate 校验数据，flamo_animation_plan 生成只读工程方案，再由 flamo_animation_start 提交隔离开发任务。任务沿用工程归属、revision 和幂等检查；方案或构建通过不等于浏览器画面验收。视频/语音生成、自动抠像以及后续实验动画能力不属于这个合同。客户端与服务端必须同时具备新工具；仅安装插件包不会升级服务端。

Flamo 支持自定义数值组件参数，通过声明的绑定或实例脚本驱动内部宽高。Figma 原生组件属性类型不是 Runtime 的上限，也不保证这些扩展能回写成 Figma 原生属性。脚本必须尊重每个轴的布局归属；Hug 与 Fill 的尺寸由布局推导。进度条应测量实际容器并响应缩放，避免用透明文字长度编码宽度。API 快照匹配仍需核对工程 Runtime 文件回执；能力说明和编译通过不能替代实际交互验收。

• flamo-design-generate：bounded query、typed node/hierarchy operation、asset/font 注册、exact Resource Export append、单资源 materialize 或多资源 DesignPlan compose；
• flamo-design-review：默认只读审查 Artifact revision、结构、资源 provenance、字体、Runtime capture、critic finding 和像素证据。
• flamo-design-develop：在线工程的动画、交互脚本和代码开发，以及后台任务的跟进、继续和取消。

生成与审查职责分开。用户只要求 review 时，不应为了让结果通过而自动修改 Artifact。

推荐生成流程

1. 查询项目 capabilities，并确认 canonical project id 与当前 Artifact revision。
2. 只读取目标页面、子树、资源、变量或组件投影，不请求完整 raw Artifact。
3. 优先搜索并 exact resolve 已验证的 Resource Pack；已有模板/组件能满足需求时，不从 primitive 重造。
4. 使用稳定 mutation id 与 expectedArtifactRevision 先 dry-run，再提交同一逻辑计划。
5. 重新查询受影响子树，检查 durable receipt 与 reload revision。
6. 运行 critic；只应用 critic 明确提供的 typed repair。
7. 执行 font probe、Runtime render 与 revision-bound verify。

完成口径

结构通过不等于视觉通过，截图成功也不等于来源一致。只有对 checksum-bound、approved Resource Pack reference 的 pixel verification 返回 passed，才能写“视觉已验收”；缺少参考图或在线 Runtime 时，应明确报告 evidence gap。

如需在 Figma 中创作 HMI 管道，可使用免费的 Flamo 管道插件。