sandbox_draft

動手做畫面之前先畫草稿：你送 JSON，伺服器畫成手繪風的手機草稿（最多 3 張圖、每張最多 4 支手機），圖直接回到工具結果，也出現在人的 app 裡這份設計的頁面，人在上面圈線、講話、打字回報。不需要箱子。

工具標題（MCP 的 title，有的 client 用它顯示這個工具）是 Sketch screens；註記為 readOnlyHint: false（成功一次就存一版）、destructiveHint: false、openWorldHint: false。

什麼時候用

新做或要改的東西，開發順序是：sandbox_draft（畫面）→ sandbox_architecture（服務）→ sandbox_schema（存的資料）→ 在箱子裡做 → sandbox_review。只有這次工作碰不到的那一步才跳過：沒有畫面的改動就沒有草稿。

人要草稿、草圖、wireframe、mockup（草稿、ラフ）時就用 sandbox_draft；要做新畫面或改畫面之前也先用它，讓人先在手機上看版面和流程。不要改寫 HTML、SVG 或圖片檔來代替，也不要為了給人看長相先在箱子裡把畫面做出來：這個工具會畫、會留下每一版，也給人回報用的工具。

要改既有的畫面，先看過現在的畫面再畫（用 sandbox_shot 拍跑著的 app，或讀程式碼）。

箱子

設計不需要箱子。它屬於人的帳號和畫它的那段對話：不用 sandbox_start 也能畫、改版、收到人的回報；箱子停掉或它的圖被刪掉，設計都還在。

id 選填：傳這段工作的箱子，設計也會出現在那個箱子頁的「草稿」「架構圖」或「Schema」分頁；不傳，設計就自己獨立，在 app 裡它自己的頁面（appUrl）和「設計」清單。設計出現在最後一次跟它一起傳的那個箱子上：之後沒帶 id 的版本留在那個箱子，帶了另一個箱子 id 的版本就移到那個箱子。id 不是這個帳號的箱子時，呼叫會失敗。

畫圖在伺服器上做，不在箱子裡：這個呼叫不會叫醒凍結的箱子，也不在箱子裡跑任何東西。id 指的是還沒停掉的箱子時，畫成功就算對那個箱子的一次使用：會更新 lastUsedAt，把閒置凍結與收掉的時間往後推，呼叫它的對話就是拿著這個箱子的對話（箱子狀態），這一版也會是它 steps[] 裡的一步。失敗的呼叫、沒帶 id 的呼叫，都不使用任何箱子。

畫什麼

只畫人要判斷的東西。每張圖右上角都有同樣的圖例：紅色是新的或改的，黑色、灰色是原樣（圖例的字跟帳號的語言，見圖上的固定字）。

• new: true 標的是跟現在的產品比起來新的或不一樣的東西，畫成紅色。比的是現在的產品，不是上一版：第二版以後，跟現在的產品比還是新的東西繼續標 new: true；跟上一版比改了什麼寫在 note。
• 其他不設 new，畫成黑色和灰色。
• 不重要的字用 scribble（灰色塗鴉）代替：重要的才寫字。
• 整頁不動的手機設 unchanged: true：照你給的元件畫，剩下的地方畫灰色塗鴉，蓋一個「原樣」章（章上的字跟帳號的語言）。
• 每個字都用人讀的語言寫。

字型裡沒有的字（例如 emoji）會畫成方框，warnings 會列出來：換掉再畫一次。常見符號會自動換成字型有的（✓ 換成 √、✕ 換成 ×、➜ 換成 →、⭐ 換成 ★、≈ 換成 ～、≤ 換成 ≦、≥ 換成 ≧、☐ 換成 □、☑ 換成 ■）。

圖上的固定字

草稿與 sandbox_architecture 的架構圖上，有幾段字是繪圖器自己寫的，不是你給的。它們照帳號的語言畫（人在 app 帳號頁選的語言：繁體中文、English 或日本語；還沒選過就是繁體中文）。你寫的字（title、text、note、notes 等）照原樣畫，不會翻譯，所以用人讀的語言寫。warnings 與錯誤訊息一律是英文。sandbox_schema 是文字不是圖，它的少數固定字一律是英文。

boards

一張 board 畫成一張圖：標題前面有圓圈編號，手機由左到右排，註解寫在手機下面。

每支手機（欄位都是選填）：

手機螢幕高度固定。放不下的內容從最後一個放得下的元件之後截掉，手機底部寫還有幾項放不下，warnings 也會說：把它們移到另一支手機。字太長會自動換行，英文照單字斷行；title 裡有一個單字長到一行放不下時，整個標題先縮小字，還放不下才從單字中間拆開。按鈕、分段、分頁、下拉這類一行的元件會先縮小字，還放不下才截掉補「…」。

元件：每個都有 type（必填）和選填的 new；卡片的 new 會套用到裡面所有東西。索引（primary、selected）從 0 開始。

該元件沒有的欄位、拼錯的欄位、不認得的 type 一律報錯，錯誤會列出允許的欄位；不會默默忽略。上限算的是字元數（中文一個字算 1）。選填字串給空字串等於沒給。Tab、控制字元與零寬字會被拿掉，只有 sub、para 的 text 和 note 保留 \n。整個呼叫除了 id、topic、note 以外的部分是繪圖的規格，JSON 最大 64 KB。

範例

{
  "topic": "登入頁",
  "boards": [
    {
      "title": "用 Email 登入",
      "phones": [
        {
          "items": [
            { "type": "title", "text": "登入" },
            { "type": "input", "label": "Email", "text": "you@example.com", "new": true },
            { "type": "buttons", "items": ["登入"], "primary": 0 }
          ],
          "notes": [ { "text": "Email 欄是新加的", "new": true } ]
        }
      ]
    }
  ]
}

回傳

• 圖以 image content 接在 JSON 後面，一張 board 一張：先看過圖再跟人說話。然後用一句話告訴人要看哪裡；next 也這樣寫。
• designId（dsg_ 開頭）是這份設計：帳號裡同一種、同一個 topic 的每一版都是同一個。reviewId（dsn_ 開頭）是這一版的 id。stdio 轉接器 parallelsandbox-mcp 會像登記 sandbox_review 那一輪一樣登記 reviewId，人對這一版的回報才會回到這個對話（自動回到對話的條件），並在結果最後多附一段文字，說回報會不會自動回到這個對話。
• version 照帳號、種類、topic 各自編號，不管傳哪個箱子或沒傳：新的 topic 是 1，之後 2、3…
• appUrl 是人的 ParallelSandbox app 裡這份設計的頁面，https://app.parallelsandbox.com/design/<designId>；不用登入就打得開，可以傳給任何人，只有人自己的帳號能圈線送回報。imageUrls 是同樣的圖的下載網址，一小時有效。
• boxId 是你傳的 id 那個箱子；沒傳就沒有這個欄位。
• warnings：圖畫出來了，但有地方要改：手機內容被截掉、字型沒有的字。

人在 app 看到的

每份設計在 app 裡都有自己的頁面（appUrl，/design/<designId>），列著它所有的版本。拿到連結的人不用登入就能看；別的帳號或沒登入的人只看得到各版，不能回報，也看不到它出現在哪個箱子。箱子清單上面有「沙盒／設計」切換；「設計」列出帳號裡每一份設計的最新一版，新的在上面，不管有沒有出現在箱子上、那個箱子在什麼狀態，停掉的也算。從「設計」點某一份進去就是它的頁面。

帶了箱子 id 的設計也會出現在那個箱子頁。每個箱子頁都是同樣的四格，是頁面上方一排四個分頁，照開發順序排：草稿、架構圖、Schema、沙盒。箱子還沒有的那一種，格子照樣在，進去是一句跟 app 語言的說明，講 AI 用哪個工具做了會出現在這裡：「還沒有草稿。AI 用 sandbox_draft 畫了會出現在這裡。」「還沒有架構圖。AI 用 sandbox_architecture 畫了會出現在這裡。」「還沒有 Schema。AI 用 sandbox_schema 寫了會出現在這裡。」從「沙盒」點進去停在「沙盒」那一格。

在設計的頁面上，或在箱子的某一格裡（同一種有好幾份時先選哪一份），人選版本（預設最新）、看這版改了什麼，在每張圖底下用「回報這裡」回報：在圖上圈線、講話、打字，然後送出。點草稿的圖會一次看一支手機（連同它底下的註解），從那張圖的第一支開始，手機上不用放大就看得清楚，太長就上下捲：點畫面右半看下一支、左半看上一支，第一張圖的手機由左到右看完接著第二張圖，到第一支、最後一支就停住（電腦上左右鍵也能換，Esc 關掉）。還不能一支一支看之前畫的草稿版本，點了是整張放大。架構圖點了整張放大，可以兩指縮放。Schema 是文字，不是圖（sandbox_schema）。

箱子卡片會顯示工作走到哪一步：最後出現在那個箱子上的是哪一種設計，在那之後呼叫過 sandbox_review 就是驗收。

人的回報

人對某一版送出回報後（從設計的頁面或箱子的某一格都一樣），會回到畫那一版的對話，照驗收回饋的方式回來，有沒有箱子都一樣：

• 設定好接收 app 回饋的對話（用 parallelsandbox-agent 開的，或裝了 ParallelSandbox 回饋 hook 的 client；見 sandbox_review；設計的版本另有條件，見下面），回報會叫醒這個對話，訊息像這樣：The person sent feedback in the ParallelSandbox app on design version <reviewId>. Call the parallelsandbox sandbox_report tool with exactly {"reportId":"<reportId>"} to read it, change what they asked, then call the same design tool again with the same topic for the next version. 用 sandbox_report 只帶 reportId 讀，不帶 id。
• 其他情況，回報會以 fromHuman 夾在這個對話下一次呼叫設計工具（這個工具也算，有沒有帶 id 都算）或對任何箱子呼叫工具的結果裡，人也可以在 app 的收據按 複製給 AI 的訊息 貼到這裡，訊息會請你用 sandbox_report 讀回報（設計的回報給 { "reportId": "<reportId>" } 就夠；一起帶了箱子 id 也沒關係）。

訊息會寫是哪一份設計的第幾版：Feedback on draft "登入頁" v1: <人寫的字>. Read the attached report (annotated images, voice transcript, text written on the image in notes[].labels). Change it as asked, then call sandbox_draft again with the same topic for the next version. 人沒寫字時，<人寫的字> 是 N annotated notes and M recordings。改之前先看圈過的圖、語音逐字稿和人在圖上打的字（notes[].labels）。回報的 reviewId 是人看的那一版的 reviewId（dsn_ 開頭）。對設計的回報不會結束等待中的 sandbox_review 卡片。

自動回到對話的條件

• 沒帶 id 畫的設計要 stdio 轉接器 parallelsandbox-mcp 0.6.0 以上，帶箱子 id 畫的要 0.5.4 以上；parallelsandbox-agent 也在這個套件裡，用它開的對話條件一樣。0.6.0 以前的版本只會連同箱子一起登記設計的版本，0.5.4 以前的版本只登記 sandbox_review，這時對設計的回報只會照上面第二條回來（fromHuman 或 複製給 AI 的訊息）。只走 HTTP 端點、沒有轉接器的連線也一樣。
• Claude Code 和 Gemini CLI 另外要 ParallelSandbox 的回饋 hook 涵蓋設計工具。0.5.4 以前裝的 hook 只對 sandbox_review（Claude Code 是 sandbox_review 與 sandbox_report）觸發，收不到設計的回報。0.5.4 會把這種舊的 hook 當成還沒裝：server instructions 與設計工具的結果都會附上安裝命令，例如 npx -y parallelsandbox-mcp install claude-code（Gemini CLI 是 install gemini；照結果裡寫的命令跑）。改人的使用者設定要本人同意：先在對話裡問，同意了跑一次。它只換掉 ParallelSandbox 自己的 hook，其他設定留著，舊檔留一份備份，可以重跑。Claude Code 跑完就生效，Gemini CLI 下次啟動才生效。Cursor 的 hook 不用重裝（它跑的是同一個套件，套件 0.5.4 以上就行）；Codex 不用 hook。
• hook 裝好之後畫的版本，回報才會自動叫醒這個對話。裝好之前畫的那一版不會自動回來；adapter 0.5.5 起，結果附的安裝說明也這樣寫。0.5.4 的安裝說明裡「用 reviewId 呼叫 sandbox_review」那一步是給驗收卡片用的，設計的 dsn_ id 不要這樣用。那一版的回報請人在 app 按 複製給 AI 的訊息 貼過來，再用 sandbox_report 讀。

下一版

沒有核准或定案的步驟。照人說的改，再用同一個 topic（傳過 id 就帶同一個 id；箱子從來不是必要的）呼叫一次 sandbox_draft，規格整份重給（不是只給改的地方），加一個 note：一句話說跟上一版比改了什麼，會用紅字寫在標題下面（前面帶「這版改了什麼：」，跟帳號的語言），也是人在 app 第一個看到的。這次呼叫就是下一版（v2、v3…），不管從哪個箱子或沒有箱子；換一個 topic 從 v1 重新開始。

錯誤

呼叫失敗時訊息會指出是哪個欄位；什麼都不會存，也不算使用任何箱子：

• box not found (it must be one of yours; see sandbox_status or GET /v1/boxes)：你傳的 id 不是這個帳號的箱子。不帶 id 就能不用箱子畫。
• topic is required: …、topic is at most 80 characters、note is at most 300 characters、spec is at most 64 KB。
• 繪圖不接受的東西回 <路徑>: <問題>，路徑就是你呼叫裡的參數，例如 boards[0].phones[0].items[0]: unknown field "lable" (allowed: type, new, text, right, tag, bold)、boards[0].phones[0].tab: "C" is not one of tabs ["A", "B"]、boards[0].phones[0].items[2].primary: is 2 but there are only 1 items (0 = first)。除了 id、topic、note 以外的參數都會交給繪圖（繪圖把它們合稱 spec），所以多給或拼錯的最上層參數也會失敗：spec: unknown field "board" (allowed: boards)。改好那個欄位再呼叫一次。
• another version of "<topic>" was saved at the same time; call again。

所有工具與主題都列在工具參考。