SpriteCook Workflow Essentials 是一套共享工作流规则，用于在 SpriteCook MCP 工具可用时，配合 SpriteCook 的图像或动画技能一起使用。使用前提是 SpriteCook MCP 服务器已连接到编辑器，可通过 npx spritecook-mcp setup 设置，或参见 spritecook.ai。
预检清单 在开始批量或多素材工作流之前，先用 get_credit_balance 检查积分。每个素材的 sprite_url 应作为规范的可下载图像 URL；仅在 spritesheet_url 存在且确实需要时才使用它。只要存在可写工作区，就应把重要的 asset_id 保存到本地清单中，除非用户明确想要一次性结果。当工作流涉及同一主题的后续生成或动画时，应识别并复用规范的 asset_id，而不是从头重新生成。如果代理丢失了已生成的 asset ID，可在失败前用 list_recent_assets(limit=...) 恢复。
凭据安全 绝不要要求用户将 SpriteCook API 密钥粘贴到聊天、提示、代码块、shell 命令或生成的文件中。绝不要在代理输出中打印、持久化、回显或内联 API 密钥或 Authorization 头。优先使用 SpriteCook MCP 工具、预签名 URL，或在提示之外处理身份验证的预配置本地连接器/辅助工具。如果需要原始 API 调用且没有经过身份验证的辅助工具，应停止并请用户配置一个。
异步操作 generate_game_art、generate_tileset、remove_background、generate_character、generate_character_animations 和 animate_game_art 应视为异步操作。按照返回的 poll.tool 及其确切的 poll.arguments 执行。不要自行发明轮询端点或搜索任意响应字段。使用 operation_id 作为通用标识符，同时保留返回的 job_id 或 run_id 以匹配对应的轮询工具。仅当工具暴露 wait_seconds 且明确的有界等待有用时才传入它；正常默认是立即返回。在最终成功时，消费规范素材。如果响应包含 warning.code="asset_output_unavailable"，执行其提供的 warning.recovery 工具调用。
素材库工具 当本地文件路径需要在动画、编辑、引用或 tileset 风格复用之前成为 SpriteCook 素材时，使用 spritecook-upload-assets 加上 create_asset_upload 和 finalize_asset_upload。仅当图像已经是小型 data URL 或原始 base64 值且可以在不打印的情况下传递时，才使用 import_asset(image=..., pixel=..., display_name=..., file_name=...)。对于需要透明抠图的已拥有 SpriteCook 素材，使用 remove_background(asset_id=...)；仅当用户提供本地图像数据且不需要先创建可复用导入素材时，才使用 remove_background(image=...)。轮询返回的作业契约以获取清理后的素材。在生成、导入或清理后，当更清晰的素材名称有助于项目清单或未来代理步骤时，使用 update_asset_label(asset_id=..., label=...)。当 SpriteCook MCP 工具可用时，不要告诉用户使用 SpriteCook HTTP API 或 API 密钥进行本地图像导入；文件路径优先使用上传桥接。
UI Kit 工具 使用 spritecook-build-ui-kits 处理完整 UI 屏幕和一致的系统。先构建或选择一个概念，然后从该共享视觉源生成 sheet 并提取组件。如果缺少 UI-kit MCP 工具，刷新或重新连接 SpriteCook 集成。不要静默地用多个不相关的 generate_game_art(mode="ui") 调用来替代完整屏幕。当用户或代理已有合适的 SpriteCook 素材时，将现有已拥有概念传给 create_ui_kit(concept_asset_id=...)。不要仅仅为了进入 UI-kit 工作流而重新生成它。将 generate_game_art(mode="ui") 保留给单个隔离的 UI 素材，如图标、徽章、控件、分隔线或装饰。将 UI-kit 概念和 sheet 生成视为多素材工作：先检查积分，保留 kit ID，并用 get_ui_kit 轮询直到排队的作业完成。保持 gpt-image-2 作为 UI-kit 模型默认值。Gemini UI-kit 概念需要独立支持 2K 生成的账户。在最终确定前检查提取 quality_summary，并在 spritecook-build-ui-kits 要求更正时遵循它。
预设工具 当用户说使用其保存的某个预设时，先调用 list_presets(query=...) 并按标题、模式和状态识别最佳匹配预设。然后调用 get_preset_settings(preset_id=...) 并将返回的设置作为下一个 SpriteCook MCP 生成或编辑工具的指导。将预设视为保存的设置和参考指导，而不是单独的生成路径。私有草稿预设可以在 settings.reference.styleAssetIds、contextAssetId 和 editAssetId 中返回已拥有的参考素材 ID。对于静态图像生成，将 settings.reference.styleAssetIds 映射到 generate_game_art 上的 style_asset_ids；最多使用 10 个 ID。将风格指南图像视为新相关素材的环境风格上下文；代理无需在提示中重述它们，除非要指出特定视觉特征。当预设提供一个特定视觉/上下文参考素材时，将 settings.reference.contextAssetId 映射到 reference_asset_id。当提示引用一个特定源或上下文素材（如特定建筑、角色、道具或部件）时，使用 reference_asset_id。仅对正在直接修改的那一个素材使用 edit_asset_id。已发布预设可以在 settings.reference.styleUploadUrls、contextUploadUrl 和 editUploadUrl 中返回冻结的预设媒体 URL；仅当目标 MCP 工具支持上传 URL 引用时才使用这些。仅当用户明确要求保存私有预设时，才使用 save_private_preset(...)。它仅创建私有草稿预设，不会发布、共享或提交任何内容进行审核。
默认值 优先使用 smart_crop_mode="tightest" 以获得最佳默认结果。仅当用户明确要求时才使用 "power_of_2"。模型指导：gemini-2.5-flash-image 最便宜；gemini-3.1-flash-image 是普通静态图像生成的推荐默认值；gemini-3-pro-image 最贵。聚焦工作流默认值会覆盖此一般指导。特别是 UI kit 默认使用 gpt-image-2，因为其概念和 sheet 管道使用 2K 输出。
素材清单 将 asset_id 视为主要稳定标识符。为保存的本地文件存储 12 字符 SHA-256 前缀（sha12）。使用最小清单条目形状：asset_id、sha12、可选 label。优先使用简单的机器可读文件，如 spritecook-assets.json，除非项目已有素材清单。在生成新参考素材或向用户询问素材 ID 之前，先检查本地清单。在复用本地文件之前，计算其 sha12 并与清单匹配以恢复正确的 asset_id。
下载素材 对于最近素材恢复流程，优先使用 list_recent_assets(limit=...)。将 sprite_url 视为要检查、保存或交给下游工具的单一主要素材 URL。将 spritesheet_url 视为可选的次要产物。仅当存在且特别需要 spritesheet 导出时才使用它。对于单素材检查流程，get_asset_metadata(asset_id) 也暴露规范的 asset_id、sprite_url 和可选的 spritesheet_url 字段。将 url、pixel_url 和 raw_url 视为兼容性别名，而不是主要契约。避免在面向代理的工作流中依赖低级内部字段，如 _presigned_pixel_url 或 _presigned_url，除非没有更高级字段可用。避免在技能驱动的工作流中使用直接经过身份验证的下载端点，除非辅助工具在带外处理身份验证。