在用户的 Aseprite 窗口中实时工作
aseprite MCP 服务器有两种模式，每次调用时可选择：
- 实时（Live）：Aseprite 正在运行，并安装了 Aseprite MCP Live 扩展，该扩展连接到服务器。每个工具都会在该窗口内的开放精灵上执行脚本，画布会立即重新绘制。
- 批量（Batch）：无窗口连接。每个工具会启动一个隐藏的 Aseprite，编辑磁盘上的文件后退出。打开中的窗口不会看到变化，直到文件重新打开。
每次会话以 live_status 开始
| 结果 | 操作 |
|---|---|
connected; active tab: <路径> + 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(<open file>, 160, 112)然后再绘制。帧数同理：使用add_frames为该文件添加帧。 - 已有艺术品的画布需先询问。
resize_canvas会缩放现有像素，因此在空白标签页上直接调整尺寸即可；当标签页已有艺术时，调整尺寸前需询问用户。 - 如果标签页未保存， 使用
save_active_sprite保存（询问保存位置），然后继续在该文件中工作。保存后不意味着要启动另一个文件。 - 如果实时模式未连接， 停止并告知用户。除非用户明确说明，否则不要回退到磁盘上的新文件。
该扩展在服务器首次启动时会自行安装到 Aseprite 中。之后需重启 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 命令在新窗口中打开文件。两个窗口操作同一文件会导致不同步，而脚本只会发送到最后连接的那个窗口。如果打开的标签页过时，请用户使用 文件 → 还原。
- 出现标题为精灵名称的标签页并关闭。 这很正常：某些分析工具会处理一个临时副本，之后会被关闭。