doggy8088/imagegen-mai

针对 Microsoft Foundry MAI-Image 的图像生成技能

使用 Microsoft Foundry 中的 MAI-Image 部署来生成或编辑当前项目的图像（例如网站资源、游戏资源、UI 模型图、产品模型图、线框图、Logo 设计、照片级真实图像或信息图）。

在本文件中，<skill-dir> 指包含此 SKILL.md 的目录。

执行模式与规则

此技能使用捆绑在 <skill-dir>/scripts/image_gen.js 的 CLI。AI 代理宿主不为此工作流提供内置的图像生成或图像查看工具，因此请不要引用或尝试使用不存在的内置工具。

CLI 提供三个子命令：

• generate
• edit
• generate-batch

规则：

• 对于普通的图像生成和编辑请求，使用 scripts/image_gen.js。
• CLI 仅支持 MAI-Image 系列模型。切勿将 GPT Image、DALL-E 或其他模型路由到其中。
• 默认部署是 IMAGEGEN_MAI_IMAGE_DEPLOYMENT，如果未设置，则为 MAI-Image-2.6-Flash。除非用户已明确请求其他模型，否则不要默默切换到不同的部署。如有需要，请先询问用户。
• MAI 图像模型始终返回不透明的 PNG。对于透明图像，请使用下面的色度抠图工作流，并告知用户抠图是在本地完成的。
• 单独的 batch 这个词不需要使用 generate-batch。当多资源请求自然适合用 JSONL 批处理表示时，才使用 generate-batch；否则，请运行单个 CLI 命令。
• 实时 API 调用需要 MAI 凭证和网络访问权限。
• 使用捆绑的 scripts/image_gen.js 工作流。不要创建一次性的 SDK 运行器。
• 切勿修改 scripts/image_gen.js。如果缺少某些功能，请先询问用户，然后再进行其他操作。

输出策略：

• 将生成的资源直接写入请求的路径，如果用户未指定路径，则写入 output/imagegen/。
• 如果图像是用于当前项目的，在完成前将最终选定的图像保存到工作区中。
• 除非用户明确要求替换，否则不要覆盖现有资源；相反，创建带版本号的同级文件名，例如 hero-v2.png 或 item-icon-edited.png。

共享提示词指导位于 references/prompting.md 和 references/sample-prompts.md。

CLI 文档/资源：

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.js

本地后处理辅助工具：

• <skill-dir>/scripts/remove_chroma_key.js：从生成的图像中移除平坦的色度键背景，并写入带有 alpha 通道的 PNG。首选自动键采样、软蒙版和去溢色，以实现抗锯齿边缘。

何时使用

• 生成新图像（概念艺术、产品照片、封面、网站主图、海报）
• 生成依赖当前现实世界信息的新图像（使用 --web-grounding）
• 编辑现有图像（移除或替换对象、属性更改、修复、文本更新、光照或天气变化、伪影清理）
• 将最多五张参考图像组合成一个结果（产品、角色或品牌资产一致性）
• 为一个任务生成多个资产或变体

何时不应使用

• 扩展或匹配仓库中现有的 SVG/矢量图标集、Logo 系统或插画库
• 创建更适合直接用 SVG、HTML/CSS 或画布生成的简单形状、图表、线框图或图标
• 当源文件已以可编辑的原生格式存在时，进行微小的项目本地资产编辑
• 任何用户明确希望得到确定性代码原生输出而非生成位图的任务
• 输出尺寸超过约 1.5K（MAI-Image-2.6 上限为 2,359,296 像素，例如 1536x1536）；告知用户限制，而不是默默放大

决策树

思考两个独立的问题：

1. 意图：这是新图像还是对现有图像的编辑？
2. 执行策略：是一个资产还是多个资产/变体？

意图：

• 如果用户希望在保留现有图像部分内容的同时对其进行修改，则将此请求视为 edit。
• 如果用户提供图像作为样式、构图、情绪或主题的参考，并希望将这些反映在结果中，则使用 edit 并将这些图像作为参考（MAI 生成 API 不接受图像）。
• 如果用户未提供图像，则将此请求视为 generate。

编辑语义：

• CLI 编辑模式通过重复的 --image 标志接受一到五个本地 PNG 或 JPEG 文件。
• 如果用户提供了来自对话的附加图像或参考，并且环境支持，请先将它们保存到本地；否则，请询问用户本地文件路径。
• 图像顺序很重要，因此在提示词中按索引和角色标记每个图像。
• 对于编辑，积极保留不变项，并默认以非破坏性方式保存。
• MAI-Image-2 和 MAI-Image-2e 不支持编辑功能，CLI 会阻止它们；请使用 MAI-Image-2.5 或 MAI-Image-2.6 部署进行编辑。

执行策略：

• 当 JSONL 批处理是最清晰的工作流时，对多个提示词/资产使用 CLI generate-batch 子命令。
• MAI API 每个请求返回一张图像，没有 n 参数。对于变体，请使用不同的 out 名称运行单独的命令或单独的批处理任务。
• 速率限制较低（例如，Tier 1 的 MAI-Image-2.6-Flash 每分钟 6 个请求）。除非用户知道自己的配额，否则将 --concurrency 保持为默认值 2。

除非用户明确要求更改现有图像，否则假定用户想要一张新图像。

工作流

1. 决定 CLI 子命令：generate、edit 或 generate-batch。
2. 决定输出是仅预览还是供当前项目使用。
3. 决定执行策略：单个资产、重复的 CLI 命令、或 CLI generate-batch。
4. 提前收集输入：提示词、精确文本（逐字）、约束/避免列表、目标尺寸或宽高比、以及任何输入图像。
5. 为每个输入图像明确标注其角色：
   • 参考图像
   • 编辑目标
   • 辅助插入/样式/合成输入
6. 如果用户要求的是照片、插画、精灵图、产品图片、横幅或任何其他明确的栅格样式资产，请使用此技能，而不是替换为 SVG/HTML/CSS 占位符。如果请求是图标、Logo 或 UI 图形，且应与现有仓库原生 SVG/矢量/代码资源匹配，则优先直接编辑这些资源。
7. 根据详细程度增强提示词：
   • 如果用户的提示词已经具体详细，则将其规范化为清晰的规格说明，不要添加创造性的要求。
   • 如果用户的提示词是通用的，则仅当能显著提高输出质量时，才添加有品位的增强内容。
8. 选择尺寸。对于已知目标，使用 --size WIDTHxHEIGHT；当构图应由模型决定时，使用 --auto-aspect-ratio（MAI-Image-2.6 系列）。当提示词依赖当前的现实世界实体、地点或事件时，添加 --web-grounding（MAI-Image-2.6 系列）。
9. 使用默认部署运行 scripts/image_gen.js。
10. 对于透明输出请求，请遵循下面的色度抠图工作流。
11. 检查输出并进行验证：主题、样式、构图、文本准确性以及不变项/避免项。
12. 通过单次有针对性的更改进行迭代，然后重新检查。
13. 对于仅预览的工作，写入 output/imagegen/，除非用户要求其他位置。
14. 对于项目绑定的工作，将资产写入工作区，并更新任何消费代码或引用。
15. 对于批处理或多资产请求，将每个请求的最终交付物持久化到工作区中，除非用户明确要求仅保留输出预览。丢弃的变体无需保留，除非用户要求。
16. 使用 CLI 文档了解部署、尺寸、auto_aspect_ratio、web_grounding、输出路径和网络设置。
17. 始终报告任何工作区绑定资产的最终保存路径，以及最终的提示词或提示词集。

透明图像请求

MAI 图像模型始终返回不透明的 PNG，并且没有透明背景选项。使用色度键源图像和本地移除来制作透明资产。

顺序：

1. 使用 scripts/image_gen.js generate（或 edit 用于现有图像）将请求的主题放在一个完全平坦的纯色色度键背景上。

2. 选择一个不太可能出现在主题中的键色：默认 #00ff00，对于绿色主题使用 #ff00ff，避免对蓝色主题使用 #0000ff。

3. 将色度键源图像保留在工作区或 tmp/imagegen/ 中。

4. 运行捆绑的帮助程序：

   node "<skill-dir>/scripts/remove_chroma_key.js" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. 验证输出是否具有 alpha 通道、透明的角落、合理的主题覆盖以及没有明显的键色边缘。在浅色和深色背景上合成以检查光晕。如果仍有细小的边缘，可以重试一次，使用 --edge-contract 1；只有当边缘明显出现锯齿且主题不是反光或反光材料时，才使用 --edge-feather 0.25。

6. 如果资产是项目绑定的，则将最终的 alpha PNG 保存在项目中。

像这样提示色度键请求：

Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
Keep the subject fully separated from the background with crisp edges and generous padding.
Do not use #00ff00 anywhere in the subject.
No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.

色度键抠图不适用于头发、毛皮、羽毛、烟雾、玻璃、液体、半透明材料、反光物体和软阴影。在承诺为这些主题提供干净抠图之前，请告知用户此限制。

提示词增强

将用户提示词重新格式化为结构化的、面向生产的规格说明。使用户的目标更清晰、更可操作，但不要盲目添加细节。

将此视为提示词塑造指导，而非封闭模式。只使用有帮助的行，并在能显著提高清晰度时添加一个简短的额外标签行。

详细程度策略

根据用户提示词的详细程度来决定添加多少增强内容：

• 如果提示词已经具体详细，请保留该详细程度，仅进行规范化/结构化。
• 如果提示词是通用的，你可以添加有品位的增强内容，前提是这能显著改善结果。

允许的增强内容：

• 构图或取景提示
• 润色级别或预期用途提示
• 实用的布局指导
• 支持所述请求的合理场景具体化

不允许的增强内容：

• 未由请求隐含的额外角色或对象
• 未由请求隐含的品牌名称、标语、调色板或叙事节拍
• 除非周围布局支持，否则不应有任意的特定侧放置

用例分类法（精确标识符）

将每个请求分类到以下类别之一，并在提示词和参考中保持标识符一致。

生成：

• photorealistic-natural：真实纹理和自然光线的纪实/编辑风格生活场景。
• product-mockup：产品/包装照片、目录图像、商品概念。
• ui-mockup：应用/网页界面模型图和线框图；指定所需的保真度。
• infographic-diagram：具有结构化布局和文本的图表/信息图。
• scientific-educational：课堂讲解器、科学图表和学习视觉效果，带有必需的标签和准确性约束。
• ads-marketing：具有受众、品牌定位、场景和确切标语/文案的活动概念和广告创意。
• productivity-visual：幻灯片、图表、工作流和数据密集的商业视觉效果。
• logo-brand：Logo/商标探索，矢量友好。
• illustration-story：漫画、儿童书籍艺术、叙事场景。
• stylized-concept：风格驱动的概念艺术、3D/风格化渲染。
• historical-scene：符合时期/世界知识的场景。

编辑：

• text-localization：翻译/替换图像内文本，保留布局。
• identity-preserve：试穿、人物在场景中；锁定面部/身体/姿势。
• precise-object-edit：移除/替换特定元素（包括内部交换）。
• lighting-weather：仅更改时间/季节/氛围。
• background-extraction：通过平坦的色度键背景进行干净抠图，加上本地的 scripts/remove_chroma_key.js 移除。
• style-transfer：应用参考样式，同时更改主题/场景。
• compositing：多图像插入/合并，匹配光照/透视（最多五张图像）。
• sketch-to-render：素描/线稿到照片级真实渲染。

共享提示词模式

在顶级模式下，使用以下带标签的规格说明作为共享提示词脚手架：

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

注意：

• Asset type 和 Input images 是提示词脚手架，非专用 CLI 标志。
• Scene/backdrop 指视觉设置。
• 执行说明如大小、auto_aspect_ratio、web_grounding 和输出路径属于 CLI 路径，而非提示词文本。

增强规则：

• 保持简短。
• 只添加那些能显著改善提示词的细节。
• 对于编辑，明确列出不变项（只更改 X；保持 Y 不变）。
• 如果缺少任何关键细节并会阻止成功，则提出一个问题；否则继续。

示例

...

[为翻译截断]