在使用者 Aseprite 視窗中即時工作
aseprite MCP 伺服器有兩種模式，每次呼叫時選擇：
- 即時：Aseprite 正在執行，並安裝了 Aseprite MCP Live 擴充功能，該擴充功能會連線到伺服器。每個工具都會在該視窗中、針對已開啟的精靈執行其腳本，畫布會立即重新繪製。
- 批次：沒有連線視窗。每個工具都會啟動一個隱藏的 Aseprite，編輯磁碟上的檔案後結束。開啟的視窗必須重新開啟檔案後才會顯示變更。
每次工作階段都以 live_status 開始
| 結果 | 處理方式 |
|---|---|
connected; active tab: <path> + saved | 將該路徑作為每個工具的 filename。 |
... UNSAVED | 詢問儲存位置，然後使用 save_active_sprite("<目錄>/<名稱>.aseprite")，並使用該路徑。 |
connected; no sprite is open | create_canvas 會在視窗中開啟一個新分頁。 |
Aseprite is not connected ... | 告知使用者。僅在使用者同意後才以批次模式工作。 |
一律在使用者已開啟的檔案中繪圖（嚴格執行）
每次繪圖都要在使用者開啟的分頁中進行：即 live_status 回報的作用中精靈。絕對不要將工作放在另一個檔案中。
- 絕不建立第二個精靈。 在使用者已開啟分頁時，不要呼叫
create_canvas，也絕對不要在run_lua_script中呼叫Sprite(w, h)。僅在live_status顯示未開啟任何精靈時才使用create_canvas。在 Lua 中，請編輯app.activeSprite。 - 如果畫布太小，請調整同一個檔案的大小。 例如，如果開啟的分頁是 64×64，但場景需要 160×112，請對該檔案呼叫
resize_canvas(<開啟檔案>, 160, 112)，然後再繪圖。影格數量的處理方式相同：使用add_frames將影格加入該檔案。 - 對於已有圖稿的畫布，需先徵詢使用者意見。
resize_canvas會縮放現有像素，因此在空白分頁上直接調整大小即可；但當分頁已有圖稿時，請先詢問使用者再調整。 - 如果分頁尚未儲存， 請使用
save_active_sprite儲存（詢問儲存位置），然後繼續在該檔案中工作。儲存不代表可以開始另一個檔案。 - 如果即時模式未連線， 請停止並告知使用者。除非使用者明確同意，否則不要改用磁碟上的新檔案。
此擴充功能會在伺服器首次啟動時自行安裝到 Aseprite 中。之後必須重新啟動 Aseprite 一次，且首次使用時會詢問是否允許腳本連線網路或寫入檔案。使用者必須在 Aseprite 中允許這些操作。絕對不要代為點擊這些提示。
即時繪圖時
- 一次工具呼叫就是一個復原步驟。 使用者可以按 Ctrl+Z 來復原其中一個步驟，因此請在適合時告知他們。
- 以可見的階段進行工作（草稿、平塗、陰影、細節、動畫），讓使用者看到作品逐步成形，並說明每個階段的內容。
- 每次呼叫只做一件小事。 視窗僅在呼叫返回時重新繪製，因此一次畫完整個場景的腳本會一次全部顯示。每次呼叫應只新增一個物件、一個圖層、一個陰影步驟或一個影格。撰寫一個腳本、執行它，然後再寫下一個。絕對不要先寫好所有腳本然後一次執行。
- 優先使用專用工具（
draw_rows、draw_rectangle_at、draw_ellipse_at、fill_area_at……）。每一個都是一個可見的步驟。 - 在即時模式中，
run_lua_script會拒絕超過 40 行程式碼的腳本。保持輔助函式簡短，因為每個腳本都必須重新定義自己的函式。 - 一個 64×64 的場景通常需要 10–25 次呼叫。這是預期的：使用者正在觀看作品的建構過程。
- 優先使用專用工具（
- 每個步驟都會儲存 到檔案中，這能讓
view_sprite和匯出工具保持同步。這些工具仍然透過隱藏的 Aseprite 讀取已儲存的檔案。 - 使用者也可能會自行編輯。 在重新繪製某個區域前，請先使用
view_sprite或read_rows檢查，若未經使用者同意，不要覆蓋他們的變更。 - 不要變更他們的視圖。 除非任務需要，否則避免切換視窗中的分頁、影格或圖層。
故障排除
- 工具因「可能開啟了對話方塊」而逾時。 Aseprite 正在等待使用者回應提示，例如權限請求。請要求使用者回應。
- 變更未顯示在視窗中。 執行
live_status。每次呼叫都會先從其他持有即時連線的 Claude 工作階段取得連線，因此如果仍然顯示未連線，表示 Aseprite 是在安裝擴充功能之前開啟的，需要重新啟動。請停止並告知使用者；不要繼續在磁碟上的檔案中繪圖。 - 絕對不要自行啟動 Aseprite。 不要使用 shell 指令在新視窗中開啟檔案。同時開啟兩個相同的檔案會導致不同步，且腳本只會傳送到最後連線的那個視窗。如果開啟的分頁已過時，請要求使用者使用「檔案」→「還原」。
- 會出現並關閉與精靈同名的分頁。 這是預期行為：某些分析工具會使用暫存副本，並在之後關閉。