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 會被標記為 destructive（具破壞性），因為它們會移除或覆寫既有內容。

檔案工具

`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 + 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，而非 data 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`。省略則保留目前的 fragments，或傳入 `[]` 以清除

輸出：{ 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 文字，並依用途設定每張圖片的尺寸。若要放置你自己的圖片：

使用upload-attachment的模式 A（mimeType + fileName）上傳，並執行回傳的 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）必須正確開始與結束
前置資料的每一行都必須是有效的區塊式 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`	enum	檔案 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`	enum	可為 `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 已執行後，才可在 JSX 中用於 add-screen-jsx 或 replace-screen-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`	enum	必填——新畫面與既有畫面的關係

`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`	enum	必填——要套用的編輯或重新設計預設

`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`

已更名的工具