sandbox_architecture

動手做之前先畫各部分怎麼接：每個 app、服務、資料庫、佇列或外部 API 一個方塊，誰呼叫誰一條箭頭，自動由上往下排成一張乾淨的一般架構圖（直線箭頭、圓角方塊，新的是藍色），圖回到工具結果，也出現在人的 app 裡這份設計的頁面。不需要箱子。

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

什麼時候用

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

這次工作會加或改服務（新的 worker、佇列、呼叫外部 API、某個服務改成去呼叫另一個）、或人要架構圖、流程圖（架構圖、構成図）時，用 sandbox_architecture。不要改寫 Mermaid、HTML、SVG 或圖片檔來代替：這個工具會畫、會留下每一版，也給人回報用的工具。

除了畫的東西，其他都跟 sandbox_draft 一樣：不需要箱子，設計屬於帳號和這段對話，箱子停掉也還在。id 選填：傳這段工作的箱子，設計也會出現在那個箱子頁；畫圖在伺服器上做，從不叫醒凍結的箱子，id 指的是還沒停掉的箱子時，畫成功就算對它的一次使用，呼叫的對話就是拿著它的對話（sandbox_draft）。

畫什麼

new: true 標的是跟現在比起來新的或不一樣的方塊和箭頭，畫成藍色；其他是灰色，代表原樣。整張圖不用紅色。比的是現在的系統，不是上一版：跟上一版比改了什麼寫在 note，用藍字寫在標題下面。右上角的圖例（藍色是新的或改的，黑色、灰色是原樣）和 note 前面的字跟帳號的語言（圖上的固定字）。方塊照箱子裡的服務取名，sub 寫那個服務的名字（sandbox_start 宣告的名字；還沒宣告就寫之後要用的名字），人才對得起來。字用人讀的語言寫。

nodes：

edges：

畫法是一般的專業架構圖，不是手繪風：白底、灰外框加很淡灰底的圓角方塊、直線加實心箭頭（尖端碰到方塊邊）、一般的無襯線字。不用給座標。方塊由上往下分層：沒有箭頭指進來的、沒接線的放最上層，其他照從最上層走過來最長要幾步決定第幾層。繞圈的箭頭照樣畫。同一層的順序會調成交叉最少，跨好幾層的箭頭從方塊之間的空隙穿過，箭頭標籤墊白底放在線旁邊。整張圖最窄 1200 px；超過 2400 px 寬就整張縮小，縮到 60% 以下時 warnings 會建議拆成兩張。字型裡沒有的字（例如 emoji）會畫成方框，warnings 會列出來：換掉再畫一次。

拼錯或多給的欄位一律報錯，錯誤會列出允許的欄位；不會默默忽略。整個呼叫除了 id、topic、note 以外的部分是繪圖的規格，JSON 最大 64 KB。

範例

{
  "topic": "訂課＋提醒",
  "nodes": [
    { "id": "web", "label": "手機網頁", "sub": "flowday-web" },
    { "id": "api", "label": "API", "sub": "flowday-api" },
    { "id": "db", "label": "Postgres" },
    { "id": "worker", "label": "提醒", "sub": "flowday-worker", "new": true }
  ],
  "edges": [
    { "from": "web", "to": "api", "label": "HTTPS" },
    { "from": "api", "to": "db", "label": "讀寫" },
    { "from": "api", "to": "worker", "label": "排程", "new": true },
    { "from": "worker", "to": "db", "label": "讀名單", "new": true }
  ]
}

回傳、人的回報與下一版

• 圖以 image content 接在 JSON 後面：先看過圖，再用一句話告訴人要看哪裡。designId（dsg_ 開頭）是這份設計，這個 topic 的每一版都一樣，reviewId（dsn_ 開頭）是這一版的 id，version 照帳號、種類、topic 各自編號（不管傳哪個箱子或沒傳），appUrl 是 app 裡這份設計的頁面 /design/<designId>（拿到連結就打得開，只有帳號本人能回報），boxId 是你傳的 id 那個箱子（沒傳就沒有），imageUrls 是一小時有效的下載網址，warnings 會說圖被縮小了或有字型沒有的字。
• 人在 app 裡這份設計的頁面和「設計」清單看到它，有傳箱子 id 時也在那個箱子頁的「架構圖」那一格；點圖會整張放大、可以兩指縮放，圖底下的「回報這裡」用來回報。人對某一版的回報會回到畫那一版的對話，照驗收回饋的方式回來，有沒有箱子都一樣：叫醒設定好接收 app 回饋的對話，或在這個對話下一次呼叫設計工具或對任何箱子呼叫工具時以 fromHuman 回來，或經由 複製給 AI 的訊息；用 sandbox_report 只帶 reportId 讀，不帶 id。訊息會寫 Feedback on architecture "<topic>" v<n>: …；先看圈過的圖、語音逐字稿和人在圖上打的字（notes[].labels）。訊息最後是 Change it as asked, then call sandbox_architecture again with the same topic for the next version.。要自動回到這個對話，轉接器要 0.6.0 以上（有傳箱子 id 時 0.5.4 以上），Claude Code 與 Gemini CLI 的回饋 hook 也要是 0.5.4 以上裝的（自動回到對話的條件）。細節見 sandbox_draft。
• 沒有核准或定案的步驟。照人說的改，再用同一個 topic（傳過 id 就帶同一個 id）呼叫一次 sandbox_architecture，規格整份重給，加一句 note 說跟上一版比改了什麼：這就是下一版（v2、v3…），不管從哪個箱子或沒有箱子。

錯誤

呼叫失敗時訊息會指出是哪個欄位；什麼都不會存，也不算使用任何箱子：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，或繪圖不接受的東西，格式是 <路徑>: <問題>，路徑就是你呼叫裡的參數：

• edges[0].to: "queue" is not a node id (ids: web, api, db)
• nodes[1].id: duplicate id "api" (also used by spec.nodes[0])：括號裡的 spec.nodes[0] 就是你呼叫裡的 nodes[0]
• edges[2]: from and to are the same node "api"; self-loops are not supported
• spec: unknown field "edge" (allowed: nodes, edges)：多給或拼錯的最上層參數（除了 id、topic、note 以外的參數都會交給繪圖，繪圖把它們合稱 spec）

改好那個欄位再呼叫一次。

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