使用 SpriteCook MCP…

当编辑器中已连接 SpriteCook MCP 工具、需要生成/导入/动画化游戏美术资产时，按此规范管理额度、异步任务、资产清单与凭证安全。

适用场景

解决思路

1. 开始批量或多资产工作流前，先用 `get_credit_balance` 检查额度。
2. 把每个资产的 `sprite_url` 作为规范的可下载图片 URL；仅在 `spritesheet_url` 存在且确实需要时才使用它。
3. 只要有可写工作区，就把重要的 `asset_id` 保存到本地清单中，除非用户明确只想要一次性结果。
4. 当工作流涉及同一主体的后续生成或动画时，先找出并复用规范的 `asset_id`，而不是从头重新生成。
5. 如果 agent 丢失了已生成资产的 ID，先用 `list_recent_assets(limit=...)` 恢复，再考虑报错。
6. 绝不要让用户把 SpriteCook API key 粘贴到聊天、提示词、代码块、shell 命令或生成的文件中。
7. 绝不要在 agent 输出中打印、持久化、回显或内联 API key 或 `Authorization` 头。
8. 优先使用 SpriteCook MCP 工具、预签名 URL，或一个在提示词之外处理认证的预配置本地连接器/辅助工具。
9. 如果必须发起原始 API 调用且没有已认证的辅助工具，停下来让用户先配置一个。
10. 把 `generate_game_art`、`generate_tileset`、`remove_background`、`generate_character`、`generate_character_animations`、`animate_game_art` 视为异步操作。
11. 按照返回的 `poll.tool` 及其确切的 `poll.arguments` 进行轮询；不要自创轮询端点或随意搜索响应字段。
12. 使用 `operation_id` 作为通用标识符，同时保留返回的 `job_id` 或 `run_id` 以匹配对应的轮询工具。
13. 仅在工具暴露 `wait_seconds` 且需要明确的有界等待时才传入它；正常默认是立即返回。
14. 在最终成功时，消费规范的 `assets`。如果响应包含 `warning.code="asset_output_unavailable"`，执行其提供的 `warning.recovery` 工具调用。
15. 当本地文件路径需要在动画、编辑、引用或 tileset 风格复用之前变成 SpriteCook 资产时，使用 `spritecook-upload-assets` 配合 `create_asset_upload` 和 `finalize_asset_upload`。
16. 仅当图片已经是小型 data URL 或原始 base64 值且可以在不打印它的情况下传递时，才使用 `import_asset(image=..., pixel=..., display_name=..., file_name=...)`。
17. 对需要透明抠图的已拥有 SpriteCook 资产使用 `remove_background(asset_id=...)`；仅当用户提供本地图片数据且不需要先得到可复用导入资产时，才使用 `remove_background(image=...)`。轮询返回的任务契约以获取清理后的资产。
18. 在生成、导入或清理之后，当更清晰的资产名称有助于项目清单或后续 agent 步骤时，使用 `update_asset_label(asset_id=..., label=...)`。
19. 当 SpriteCook MCP 工具可用时，不要告诉用户使用 SpriteCook HTTP API 或 API key 来导入本地图片；文件路径优先使用上传桥。
20. 使用 `spritecook-build-ui-kits` 处理完整 UI 屏幕和成套系统。先构建或选择一个概念，再从该共享视觉源生成 sheet 并提取组件。
21. 如果缺少 UI-kit MCP 工具，刷新或重新连接 SpriteCook 集成；不要悄悄用多个不相关的 `generate_game_art(mode="ui")` 调用来替代完整屏幕。
22. 当用户或 agent 已有合适的 SpriteCook 资产时，把它传给 `create_ui_kit(concept_asset_id=...)`；不要仅为进入 UI-kit 工作流而重新生成它。
23. 把 `generate_game_art(mode="ui")` 保留给单个孤立 UI 资产，如图标、徽章、控件、分隔线或装饰。
24. 把 UI-kit 概念和 sheet 生成视为多资产工作：先检查额度、保留 kit ID，并用 `get_ui_kit` 轮询直到排队任务结束。
25. UI-kit 模型默认保持 `gpt-image-2`；Gemini UI-kit 概念需要独立支持 2K 生成的账号。
26. 在最终确定前检查提取的 `quality_summary`，当它要求修正时遵循 `spritecook-build-ui-kits`。
27. 当用户说使用其保存的某个预设时，先调用 `list_presets(query=...)`，按标题、模式和状态找出最匹配的预设。
28. 然后调用 `get_preset_settings(preset_id=...)`，把返回的设置作为下一次 SpriteCook MCP 生成或编辑工具的指导。
29. 把预设视为保存的设置和参考指导，而不是一条独立的生成路径。
30. 私有草稿预设可能在 `settings.reference.styleAssetIds`、`contextAssetId` 和 `editAssetId` 中返回已拥有的参考资产 ID。
31. 对于静态图片生成，把 `settings.reference.styleAssetIds` 映射到 `generate_game_art` 的 `style_asset_ids`；最多使用 10 个 ID。
32. 把风格指南图片视为新相关资产的环境风格上下文；除非要指出特定视觉特征，agent 无需在提示词中重述它们。
33. 当预设提供一个特定视觉/上下文参考资产时，把 `settings.reference.contextAssetId` 映射到 `reference_asset_id`。
34. 当提示词引用一个特定来源或上下文资产（如某栋建筑、角色、道具或部件）时，使用 `reference_asset_id`。
35. 仅对正在被直接修改的那一个资产使用 `edit_asset_id`。
36. 已发布预设可能在 `settings.reference.styleUploadUrls`、`contextUploadUrl` 和 `editUploadUrl` 中返回冻结的预设媒体 URL；仅当目标 MCP 工具支持上传 URL 引用时才使用它们。
37. 仅当用户明确要求保存私有预设时才使用 `save_private_preset(...)`；它只创建私有草稿预设，不会发布、分享或提交审核。
38. 优先使用 `smart_crop_mode="tightest"` 以获得最佳默认结果；仅当用户明确要求时才使用 `"power_of_2"`。
39. 模型指导：`gemini-2.5-flash-image` 最便宜；`gemini-3.1-flash-image` 是普通静态图片生成的推荐默认；`gemini-3-pro-image` 最贵。
40. 聚焦工作流的默认值覆盖上述通用指导；特别是 UI kit 默认使用 `gpt-image-2`，因为其概念和 sheet 流水线使用 2K 输出。
41. 把 `asset_id` 视为主要的稳定标识符。
42. 为保存的本地文件存储 12 字符 SHA-256 前缀（`sha12`）。
43. 使用最小清单条目结构：`asset_id`、`sha12`、可选的 `label`。
44. 优先使用简单的机器可读文件，如 `spritecook-assets.json`，除非项目已有资产清单。
45. 在生成新的参考资产或向用户索要资产 ID 之前，先检查本地清单。
46. 在复用本地文件之前，计算其 `sha12` 并与清单匹配，以恢复正确的 `asset_id`。
47. 对于最近资产恢复流程，优先使用 `list_recent_assets(limit=...)`。
48. 把 `sprite_url` 视为用于检查、保存或交给下游工具的单一主要资产 URL。
49. 把 `spritesheet_url` 视为可选的次要产物；仅当它存在且你特别需要 spritesheet 导出时才使用。
50. 对于单资产检查流程，`get_asset_metadata(asset_id)` 也会暴露规范的 `asset_id`、`sprite_url` 和可选的 `spritesheet_url` 字段。
51. 把 `url`、`pixel_url` 和 `raw_url` 视为兼容性别名，而非主要契约。
52. 避免在面向 agent 的工作流中依赖 `_presigned_pixel_url` 或 `_presigned_url` 等底层内部字段，除非没有更高级字段可用。
53. 避免在技能驱动的工作流中使用直接认证下载端点，除非有辅助工具在带外处理认证。

适用边界 · 注意事项

• 未连接 SpriteCook MCP 服务器时（需先用 `npx spritecook-mcp setup` 或访问 spritecook.ai 配置）。
• 没有已认证辅助工具却需要发起原始 API 调用时，应停止并让用户先配置认证。
• 用户明确只想要一次性结果、不需要保存资产清单时，可不写本地清单。