MCP 工具参考 - Flowstep

成功时，除 get-screen-image 外，每个工具都会返回两份结果：一份是 structuredContent（根据工具发布的输出架构进行验证），另一份是序列化为文本块的同一对象 { type: "text", text: "<json-string>" }，供不读取结构化内容的客户端使用。get-screen-image 仅返回一个 MCP 图片块：{ type: "image", data: "<base64>", mimeType: "image/png" }。失败时，会设置 isError: true，文本块中包含简短的错误信息。您可以据此采取行动的错误（例如删除时名称不匹配、Figma 链接无效、设计准则无效、附件问题或生成超时）会说明如何修复。其他失败则返回通用信息，例如 Failed to list files。

定价： 三个 AI 设计工具（ai-design-screens、ai-generate-screen-variant 和 ai-edit-screen-variant）与 Flowstep 应用共用相同的消息配额。所有其他工具均免费。请参阅用量限制。

每个工具还会发布 MCP 注解，让客户端了解其功能。delete-file、delete-screen、delete-design-guidelines、replace-screen-jsx、ai-design-screens 和 ai-edit-screen-variant 被标记为破坏性操作，因为它们会删除或覆盖现有内容。

文件工具

`list-files`

列出您的 Flowstep 文件的元数据。请先调用此工具，检查是否已有相关文件。它不返回屏幕内容，如需内容，请使用 get-screen-image 或 get-screen-jsx。输入

参数	类型	默认值	说明
`orderByCreation`	`boolean`	`true`	按 `created_at` 降序排列（最新在前，`true`），或按 `updated_at` 排列（`false`）。使用 `false` 可查找最近编辑过的文件
`limit`	`integer`（1–100）	`20`	返回的最大文件数。如果返回了完整的一页，则可能还有更多文件
`offset`	`integer`（≥0）	`0`	要跳过的文件数。下一页的 offset 为 `offset + limit`

输出：{ files }。

{
  "files": [
    {
      "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
      "name": "Dashboard redesign",
      "created_at": "2026-04-30T15:02:13.120152+00:00",
      "updated_at": "2026-04-30T15:02:13.120152+00:00",
      "organisation_id": "0b7f3c9e-2d4a-4f1b-9a5e-6c8d7e1f2a3b",
      "shared_with_me": false,
      "owner": true,
      "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
    }
  ]
}

owner：如果您创建了该文件，则为 true。
shared_with_me：如果该文件是直接与您共享的（而不只是通过您的组织共享），则为 true。
url：在 Flowstep 编辑器中打开该文件。

`get-file`

获取单个文件的元数据。此处有意省略了文件内容。如需检查屏幕，请使用 get-screen-image 或 get-screen-jsx；如需获取附加的设计准则，请使用 get-design-guidelines。如果您有该文件的待处理邀请，调用 get-file 会接受该邀请。输入

参数	类型	说明
`id`	`uuid`	文件 ID

输出：{ file, user_access_level }。

{
  "file": {
    "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
    "name": "Dashboard redesign",
    "created_at": "2026-04-30T15:02:13.120152+00:00",
    "updated_at": "2026-04-30T15:02:13.120152+00:00",
    "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d",
    "access_level": "private",
    "visibility": "private",
    "owner": true,
    "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
  },
  "user_access_level": "write"
}

access_level：private、read 或 write。
visibility：private、member 或 public。
user_access_level：您对该文件的访问权限：read 或 write。

`create-file`

创建一个不含任何屏幕的空白 Flowstep 文件。如需在一步中创建文件并生成屏幕，请改为调用不带 fileId 的 ai-design-screens。对于代码优先的工作流，请使用 create-file，然后使用 add-screen-jsx。输入

参数	类型	说明
`name`	`string`（最少 1 个字符）	新文件的显示名称

输出：{ file, user_access_level }，结构与 get-file 相同。owner 始终为 true，user_access_level 始终为 write。在后续的工具调用中，将返回的 file.id 用作 fileId。

`update-file`

重命名文件。输入

参数	类型	说明
`id`	`uuid`	文件 ID
`name`	`string`（最少 1 个字符）	新的显示名称

输出：{ file, user_access_level }，结构与 get-file 相同。

`delete-file`

永久删除文件。删除前，您传入的 name 会与文件当前的显示名称进行核对。如果不匹配，删除将被中止。这可以防止误删错误的文件。代理会被指示先与您确认。输入

参数	类型	说明
`id`	`uuid`	文件 ID
`name`	`string`	文件当前的显示名称，必须匹配，否则删除将被中止

输出：{ "deleted": true }

此操作不可逆。文件中的所有屏幕都将被删除。

屏幕工具

`list-screens`

按画布顺序列出文件中的屏幕。在 list-files 之后调用，以查看文件中已有的内容。将返回的 screenId 值用于其他屏幕工具和 AI 设计工具。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID

输出：{ screens }。

{
  "screens": [
    {
      "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
      "name": "Mobile login screen",
      "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button",
      "fidelity": "ui"
    }
  ]
}

prompt：屏幕最近一次的生成提示词；如果从未生成过（例如通过 add-screen-jsx 添加的屏幕），则为空字符串。
fidelity：lofi、hifi 或 ui。

`get-screen-image`

将屏幕渲染为 PNG，并以内嵌图片的形式返回。需要支持图片内容块的客户端。对于由 AI 设计工具、add-screen-jsx、replace-screen-jsx 或 import-figma 返回的每个 screenId，分别调用一次。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID
`screenId`	`uuid`	来自 `list-screens` 的 `screenId`，或设计工具返回的 `screenIds` 数组中的值

输出：MCP 图片内容块（image/png）。data 是 PNG 字节的标准 base64 编码，而非数据 URI。此工具没有 structuredContent。

`get-screen-jsx`

将屏幕获取为 JSX，并附带其元数据，以便您据此在代码库中进行构建，或编辑后使用 replace-screen-jsx 写回。如需可视化预览，请改用 get-screen-image。输入

参数	类型	默认值	说明
`fileId`	`uuid`	—	文件 ID
`screenId`	`uuid`	—	来自 `list-screens` 的 `screenId`，或设计工具返回的 `screenIds` 数组中的值
`includeIds`	`boolean`	`false`	在 `jsx` 的元素上包含 `data-id` 属性。当您需要将元素 ID 作为 `elementIds` 传给 `ai-design-screens`（进行原地编辑或作为视觉参考）时使用

输出：{ fileId, screenId, name, prompt, fidelity, screenType, colorTheme, jsx, fragments }。

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0",
  "name": "World clock",
  "prompt": "A world clock screen with a city search and alert button",
  "fidelity": "ui",
  "screenType": "iphone-x-vertical",
  "colorTheme": "blue",
  "jsx": "<div className=\"bg-white text-zinc-950 w-full h-fit\">\n  <div className=\"flex p-6 flex-col gap-6\">\n    …\n  </div>\n</div>",
  "fragments": []
}

jsx：仅包含标记。只有当 includeIds 为 true 时，才会包含 data-id 属性。
prompt：最近一次的生成提示词；如果屏幕从未生成过，则为空字符串。
fragments：存储在屏幕上的共享外壳内容，例如导航栏、页眉或徽标，格式为 { purpose, markup } 对象。没有时为空。将其传回 replace-screen-jsx 即可保留或更新它们。

有关 fidelity、screenType 和 colorTheme 的取值，请参阅屏幕字段取值。

`add-screen-jsx`

使用您编写的 JSX 向文件添加新屏幕。这是代码优先的路径，且免费。如果您希望 Flowstep 的 AI 来设计屏幕，请使用 ai-design-screens。add-screen-jsx 始终创建新屏幕：如需覆盖现有屏幕，请使用 replace-screen-jsx。要展示您上传的图片，请参阅JSX 中的图片。如果新屏幕基于现有屏幕，请从 get-screen-jsx（不带 includeIds）中获取 name、fidelity、screenType、colorTheme 和 jsx，然后修改需要不同的部分。输入

参数	类型	默认值	说明
`fileId`	`uuid`	—	文件 ID
`name`	`string`（1–100 个字符）	—	可选的显示名称。省略时，屏幕将自动命名为 `Screen N`
`fidelity`	`string`	`"ui"`	屏幕保真度
`screenType`	`string`	—	必填：屏幕所针对的设备或视口
`colorTheme`	`string`	`"default"`	颜色主题
`jsx`	`string`	—	仅 JSX 标记。任何 `data-id` 属性都会被忽略，新屏幕会获得新的元素 ID

输出：{ fileId, screenId }。使用 screenId 调用 get-screen-image 即可查看结果。

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf"
}

`replace-screen-jsx`

使用您编写的 JSX 覆盖现有屏幕。该屏幕会保留其 screenId 及其在画布上的位置；嵌套元素将获得新的 ID。这是代码优先的路径，且免费。如需 AI 修改，请使用 ai-design-screens 或 ai-edit-screen-variant；如需创建新屏幕，请改用 add-screen-jsx。请从 get-screen-jsx（不带 includeIds）开始，然后修改需要不同的部分。要展示您上传的图片，请参阅JSX 中的图片。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID
`screenId`	`uuid`	要覆盖的屏幕
`jsx`	`string`	仅 JSX 标记。任何 `data-id` 属性都会被忽略
`name`	`string`（1–100 个字符）	可选。省略则保留当前名称
`fidelity`	`string`	可选。省略则保留当前保真度
`screenType`	`string`	可选。省略则保留当前屏幕类型
`colorTheme`	`string`	可选。省略则保留当前颜色主题
`fragments`	`{ purpose, markup }[]`	可选的共享外壳内容，来自 `get-screen-jsx`。省略则保留当前外壳内容，传入 `[]` 则清除它们

输出：{ fileId, screenId }。使用 screenId 调用 get-screen-image 即可查看结果。

此操作会就地替换屏幕的内容。

`rename-screen`

重命名屏幕在画布上的标签，即 list-screens 和编辑器中显示的名称。这只会更改标签，不会改变屏幕的布局、尺寸或内容。如需修改这些，请使用 ai-design-screens。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID
`screenId`	`uuid`	由 `list-screens` 返回的 `screenId`
`name`	`string`（1–100 个字符）	新的屏幕名称。首尾空白会被去除

输出：{ screenId, name }。

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Checkout — empty cart" }

`delete-screen`

永久删除文件中的某个屏幕。您传入的 name 会与屏幕当前的显示名称进行核对。如果不匹配，删除将被中止。代理会被指示先与您确认。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID
`screenId`	`uuid`	要删除的屏幕
`name`	`string`	屏幕当前的显示名称，必须匹配，否则删除将被中止

输出：{ "deleted": true }

JSX 中的图片

add-screen-jsx 和 replace-screen-jsx 接受 img 的 src 中的图片，或 className 中通过 bg-[url(...)] 设置的背景图片。请为每张图片编写 alt 文本，并根据其用途调整尺寸。要放置您自己的图片：

使用模式 A（mimeType + fileName）通过 upload-attachment 上传，并运行返回的 uploadCommand。
如果响应中的 type 为 "image"，请将其 assetUrl 原样粘贴到 img src 或 bg-[url(assetUrl)] 中。

其他图片 URL 请保持 get-screen-jsx 返回的原样。不要将 path、signedUrl 或 uploadCommand 放入 src。

<img src="ASSET_URL" alt="Team photo" className="w-full h-48 object-cover rounded-lg" />

屏幕字段取值

get-screen-jsx 会返回以下取值，add-screen-jsx 和 replace-screen-jsx 也接受以下取值：

字段	取值
`fidelity`	`lofi`、`hifi`、`ui`
`screenType`	`web`、`desktop`、`desktop-large`、`desktop-medium`、`desktop-small`、`tablet`、`ipad-tablet-horizontal`、`ipad-tablet-vertical`、`android-tablet-horizontal`、`android-tablet-vertical`、`mobile_ios`、`mobile_android`、`iphone-vertical`、`iphone-horizontal`、`iphone-x-vertical`、`iphone-x-horizontal`、`android-vertical`、`android-horizontal`、`android-small-vertical`、`android-small-horizontal`
`colorTheme`	`default`、`defaultDark`、`blue`、`blueDark`、`ice`、`iceDark`、`grayscale`、`grayscaleDark`、`green`、`greenDark`、`orange`、`orangeDark`、`red`、`redDark`、`rose`、`roseDark`、`violet`、`violetDark`、`yellow`、`yellowDark`

设计准则工具

设计准则是存储在文件上的 DESIGN.md 文本。设置后，它们会被注入到该文件的每一次 AI 生成中。请参阅设计准则。

`get-design-guidelines`

获取附加到文件上的设计准则。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID

输出：{ guidelines }。

{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter"
}

如果尚未设置设计准则，guidelines 为 null。

`update-design-guidelines`

为文件设置或替换设计准则。请以纯字符串的形式传入准则，格式遵循 Google 的 DESIGN.md 格式，而不是对象或 JSON。如果您是从文件中读取的，请传入该文件的文本。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID
`designGuidelines`	`string`（最少 1 个字符）	准则的原始文本。必须是纯字符串，而非 JSON 编码的内容

验证规则

Frontmatter 必须正确打开和关闭
Frontmatter 行必须是有效的块样式 YAML
Markdown 正文不得包含重复的 ## 章节标题

如果验证失败，调用会返回以 Invalid design guidelines: 开头的错误。输出：{ updated, warnings? }。

{ "updated": true, "warnings": ["…"] }

warnings 列出了被接受但可能会被 AI 忽略的软验证问题（未知键、非十六进制颜色）。没有问题时将省略此字段。请将这些信息告知用户。

`delete-design-guidelines`

清除文件的设计准则。删除不存在的准则不会产生任何效果。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID

输出：{ "deleted": true }

对话工具

`get-chat-history`

获取与文件关联的设计对话，即该文件的 Flowstep 对话，而不是您 MCP 客户端的对话。可用于恢复该文件之前的工作。输入

参数	类型	说明
`fileId`	`uuid`	文件 ID

输出：{ messages }。如果您在该文件上没有设计对话，messages 为空。每条消息都包含 type（"request" 或 "response"）、author（"human" 或 "ai"）和 content_type。响应消息使用 "text"、"summary" 或 "followup"。

{
  "messages": [
    {
      "id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "type": "request",
      "status": "success",
      "content": "Generate a simple mobile login screen with email and password fields",
      "author": "human",
      "content_type": "text",
      "sequence": 1,
      "targets": [],
      "attachments": []
    },
    {
      "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf",
      "type": "response",
      "status": "success",
      "content": "Generated a mobile login screen with email and password input fields, a sign in button, and a sign up link.",
      "author": "ai",
      "content_type": "summary",
      "sequence": 7,
      "request_message_id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "targets": [{ "target_id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" }]
    }
  ]
}

附件工具

`upload-attachment`

上传参考文件，用作 ai-design-screens 的附件；或上传图片，以便通过 add-screen-jsx 或 replace-screen-jsx 放入您自己的 JSX。ai-generate-screen-variant 和 ai-edit-screen-variant 不接受附件。文件字节不会经过模型，服务器也绝不会代您抓取 URL。如需引用网页，请改为将其 URL 包含在 ai-design-screens 的 message 中。这里有两种模式，只能使用其中一种，不要组合使用。 模式 A：文件和图片（mimeType + fileName） 适用于任何图片、PDF 或较大文本文件的必需三步流程：

仅使用 mimeType 和 fileName 调用 upload-attachment（例如 image/png 和 dog.png）。响应是一个已准备好的上传，而不是已存储的文件：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

将 uploadCommand 中的 LOCAL_FILE_PATH 替换为您文件的绝对路径，并在 shell 中运行该确切命令，它必须以退出码 0 结束。signedUrl 中的令牌仅授权这一次上传。跳过此步骤会导致存储为空，设计工具的预检将失败。
仅将 { id, path, type } 传入 ai-design-screens 的 attachments 数组，不要传入 signedUrl、uploadCommand 或 nextStep。如需在您自己的 JSX 中放置图片，请将 assetUrl 放入传给 add-screen-jsx 或 replace-screen-jsx 的 JSX 的 img src 或 bg-[url(...)] 中。请参阅JSX 中的图片。

如需附加远程文件，请先自行将其下载到本地路径（例如使用 curl），然后按相同的三个步骤操作。切勿将 URL 传给 upload-attachment。

参数	类型	说明
`mimeType`	枚举	文件 MIME 类型。取值之一：`image/jpeg`、`image/png`、`image/webp`、`application/pdf`、`text/markdown`、`text/plain`、`text/javascript`。对于 `.jsx`、`.tsx`、`.js`、`.ts` 文件，请使用 `text/javascript`
`fileName`	`string`（最少 1 个字符）	带扩展名的原始文件名，例如 `cat.png` 或 `design.md`

模式 B：短文本（text + mimeType） 上传已在上下文中的文本，无需 shell 命令。响应可直接使用：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "document",
  "mimeType": "text/plain"
}

参数	类型	说明
`text`	`string`（最多 64,000 个字符）	原始文本内容。仅适用于文本文件，请勿用于图片或 PDF。超过 64,000 个字符？请改用模式 A
`mimeType`	枚举	取值之一：`text/markdown`、`text/plain`、`text/javascript`

将得到的 { id, path, type } 传入 ai-design-screens 的 attachments 数组。两种模式的最大文件大小均为 3 MB，PDF 最多 100 页。输出：{ id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }。

type：图片文件为 "image"，PDF 和文本文件为 "document"。
assetUrl：已上传文件的 URL，两种模式下均会返回。仅当 type 为 "image" 且已运行模式 A 的 uploadCommand 之后，才可在 add-screen-jsx 或 replace-screen-jsx 的 JSX 中使用它。
signedUrl、uploadCommand、nextStep：仅在模式 A 中设置。请勿将它们传入设计工具。

Figma 工具

`import-figma`

将 Figma 框架导入 Flowstep 文件，作为其画布上的可编辑元素。每次导入都会新增一个屏幕。两次导入同一框架会得到两个屏幕，因此如果您本意是替换，请使用 delete-screen 删除旧屏幕。文件所属的组织必须已在 Flowstep 设置中连接 Figma。输入

参数	类型	说明
`fileId`	`uuid`	要导入框架的 Flowstep 文件。这不是 `figmaUrl` 中的 Figma 文件密钥
`figmaUrl`	`string`	指向特定 Figma 框架的链接，包含 `node-id`。在 Figma 中，右键点击框架并选择 Copy/Paste as → Copy link to selection。页面链接会导入该页面上的所有顶层框架（通过 MCP 最多 20 个）

输出：{ fileId, screenId, frameCount? }。screenId 为导入的屏幕，将其传给 get-screen-image 即可查看结果。当页面 URL 导入了多个框架时，screenId 为 null，并改为返回 frameCount。此时请调用 list-screens，然后对每个新屏幕调用 get-screen-image。

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe"
}

套餐与计费工具

`get-plan-details`

获取您组织的 Flowstep 套餐、订阅状态、用量和剩余配额。无需输入，组织由已登录的用户决定。在调用 AI 设计工具之前，可用它检查您的配额。输出：{ plan, subscription, limits, usage, remaining }。

字段	说明
`plan`	`{ name, code, type }`。`type` 为 `"free"` 或 `"paid"`
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	按功能划分的限制（例如 `messages`）。每项都包含可选的 `daily` 和 `monthly` 对象，其中有 `max` 和 `warn` 值，以及一个 `unlimited` 标志
`usage`	各功能迄今的用量，格式为 `{ daily, monthly }`
`remaining`	各功能剩余的配额，格式为 `{ daily, monthly }`。对于不限量的功能则省略

限制因套餐而异，请参阅定价和用量限制。

AI 设计工具

这三个工具根据描述或预设进行设计，它们从不接受或复用 JSX。每次调用都会消耗与 Flowstep 应用相同的消息配额，并会阻塞直至生成完成或超时（180 秒）。

工具	用途
`ai-design-screens`	根据自由格式的描述生成新屏幕、原地修改现有屏幕，或两者兼而有之
`ai-generate-screen-variant`	为某个现有屏幕添加下一步、错误或空状态，或其平台变体
`ai-edit-screen-variant`	对某个完整的现有屏幕应用编辑或重新设计预设

这三个工具均返回 { status, fileId, screenIds, designGuidelinesUpdated }。针对每个 screenId 分别调用一次 get-screen-image 即可查看结果。

designGuidelinesUpdated：当本轮中文件的 DESIGN.md 设计准则被自动更新时，此处为变更的简要摘要；否则为 null。

`ai-design-screens`

根据文本描述，在一次调用中生成一个或多个新屏幕、原地修改现有屏幕，或两者兼而有之，例如新流程、主题、文案、布局，或跨多个屏幕的协调修改。这与 Flowstep 编辑器中聊天使用的设计代理相同：它会根据您的 message 和 elementIds 决定要构建什么、修改什么。省略 fileId 可开始一个新文件；传入 fileId 则在现有文件中工作。如果请求可能适用于您已有的文件，您的代理应先检查 list-files 和 list-screens。如需为某个屏幕生成下一步、错误或空状态，或平台变体，请使用 ai-generate-screen-variant。如需对某个屏幕进行预设编辑或重新设计，请使用 ai-edit-screen-variant。如果您已有 JSX，请改用 add-screen-jsx 或 replace-screen-jsx。输入

参数	类型	默认值	说明
`fileId`	`uuid`	—	目标文件。省略则创建新文件。设置 `elementIds` 时必填
`message`	`string`	—	要生成的屏幕和/或要进行的修改的描述。传入 `elementIds` 时，请说明是编辑它们还是将其用作参考。如需 Flowstep 参考的网页 URL，请包含在此处
`elementIds`	`uuid[]`	`[]`	可选。来自 `list-screens` 的 `screenId`，和/或来自 `get-screen-jsx`（带 `includeIds`）的元素 `data-id`，类似于编辑器中的选区。它们可以原地编辑，也可以作为新屏幕的视觉参考。`screenId` 会以整个屏幕为目标
`attachments`	`{ id, path, type }[]`（最多 5 个）	`[]`	来自 `upload-attachment` 的文件：图片、PDF，或代码及文本文件。请勿在消息中内联文件内容

示例：在一次调用中修改一个屏幕并添加另一个屏幕：

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "message": "Switch this sign-in screen to dark mode, then add a matching forgot-password screen.",
  "elementIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

输出：{ status, fileId, screenIds, designGuidelinesUpdated, reply? }。

{
  "status": "generated",
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": [
    "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0"
  ],
  "designGuidelinesUpdated": null
}

status：屏幕已构建或修改时为 "generated"。当 Flowstep 回复但未构建或修改屏幕时为 "chat"，此时 reply 中包含其回答，且 screenIds 为空。如果您的需求描述不明确，代理应请您澄清，然后再次调用该工具。
screenIds：本次调用中构建或修改的每个屏幕，包括原地编辑的屏幕。如果调用在构建了部分屏幕后超时，它会返回这些屏幕，而不是错误。

您要求其编辑的屏幕会被就地覆盖。

`ai-generate-screen-variant`

基于恰好一个现有屏幕派生出一个新屏幕，即流程中的下一步、错误或空状态，或另一平台的版本。原屏幕保持不变。如需添加一个并非现有屏幕变体的屏幕（例如设置屏幕），请使用带 fileId 的 ai-design-screens。输入

参数	类型	说明
`fileId`	`uuid`	目标文件
`screenId`	`uuid`	用于派生的现有屏幕
`operationVariant`	枚举	必填：新屏幕与现有屏幕的关系

`operationVariant`	添加内容
`next_screen`	用户流程中的下一个屏幕
`error_state`	该屏幕的错误状态
`empty_state`	该屏幕的空状态
`web_version`	网页版本
`mobile_version`	移动版本
`tablet_version`	平板版本
`mobile_ios_version`	iOS 版本
`mobile_android_version`	Android 版本

输出：{ status, fileId, screenIds, designGuidelinesUpdated }。status 始终为 "generated"。

`ai-edit-screen-variant`

使用预设，原地修改恰好一个现有屏幕。可以对其进行主题化或润色，尝试不同的布局或视觉风格，或从头重新设计。如需自由格式的指令或对单个元素的精确修改，请使用 ai-design-screens。输入

参数	类型	说明
`fileId`	`uuid`	目标文件
`screenId`	`uuid`	要修改的现有屏幕
`operationVariant`	枚举	必填：要应用的编辑或重新设计预设

`operationVariant`	类型	效果
`dark_theme`	编辑	将屏幕切换为深色主题
`light_theme`	编辑	将屏幕切换为浅色主题
`make_pretty`	编辑	润色屏幕的视觉设计
`different_layout`	重新设计	尝试不同的布局
`different_style`	重新设计	尝试不同的视觉风格
`from_scratch`	重新设计	从头重新设计屏幕

输出：{ status, fileId, screenIds, designGuidelinesUpdated }。status 始终为 "generated"。

此操作会就地覆盖屏幕的内容。

已重命名的工具

工具名称于 2026 年 9 月和 10 月更改。如果您的提示词、脚本或代理指令仍使用旧名称，请进行更新：

旧名称	新名称
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`ai-generate-screens`	`ai-design-screens`
`ai-edit-screens`	`ai-design-screens`
`create-new-design`	`ai-design-screens`
`edit-design`（自由格式指令）	`ai-design-screens`
`edit-design`（带 `operationVariant` 预设）	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

输入参数也有变化：AI 设计工具接受 elementIds（变体工具则接受单个 screenId），而不再接受 targets；add-screen-jsx 接受 jsx 和明确的元数据字段，而不再接受带元数据注释的 jsxContent；create-file 接受 name，而不再接受 title；设计准则工具接受 fileId，而不再接受 resourceId 和 linkedTo。

​文件工具

​list-files

​get-file

​create-file

​update-file

​delete-file

​屏幕工具

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​JSX 中的图片

​屏幕字段取值

​设计准则工具

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​对话工具

​get-chat-history

​附件工具

​upload-attachment

​Figma 工具

​import-figma

​套餐与计费工具

​get-plan-details

​AI 设计工具

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​已重命名的工具

文件工具

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

屏幕工具

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

JSX 中的图片

屏幕字段取值

设计准则工具

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

对话工具

`get-chat-history`

附件工具

`upload-attachment`

Figma 工具

`import-figma`

套餐与计费工具

`get-plan-details`

AI 设计工具

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

已重命名的工具