图像生成技能

在创建、重新生成或评审用于 Markdown、PDF、DOCX、网页、合并请求（MR）或发布制品（release artifacts）的图像、图表、截图或生成图形时，使用本技能。

claw-support !1 中发生了什么问题

图像评审循环失败，原因是：工作流在 SVG 与 PNG 格式之间反复切换；在保留所请求格式之前就对技术元数据进行了优化；且依据未匹配维护者期望输出的检查项来断言图像质量。请将此视为默认需防范的失败模式。

规则

• 严格保留请求的输出格式。若评审人要求 PNG，则不得擅自切换为 SVG，除非其明确接受该变更。
• 当被要求保留既有风格或早期格式时，须予以遵循。不得以“提升可读性”为由对图表进行重新设计。
• 光栅图像（raster images）须直接按最终源分辨率渲染。严禁将较小尺寸位图上采样后声称其为高分辨率图像。
• 面向 PDF 使用的 PNG 图像，须至少包含 300 DPI 元数据，并具备足够像素数以满足印刷/显示尺寸需求。
• 文本、线宽、箭头、边框、间距及图标等元素须统一缩放。大幅画布配极小文字仍会导致评审失败。
• 绘制图表时，优先采用类矢量（vector-like）绘图原语并直接渲染至最终 PNG 画布；除非截图本身即为图像主题，否则应避免使用截图或嵌套的光栅片段。
• 确保“事实来源”（source-of-truth）文件清晰明确：若交付物为 PNG，则构建流水线应直接消费 PNG 文件，避免隐藏的 SVG 依赖——除非 SVG 明确作为可编辑源文件存在。
• 使用 *.image.genai 提示文件作为仓库中生成图像的“意图来源”（source-of-intent）约定。例如对 example.image.genai，除任务明确限定输出格式外，应生成同级的 example.svg、example.png 和 example.webp 文件。
• 除非明确要求，否则不得将通用图像生成规则添加至仓库级 AGENTS.md。优先复用已有技能，或在任务本地添加说明。

工作流

1. 从 Issue 或 MR 讨论中准确读取目标制品路径、目标消费者及确切格式要求。
2. 编辑前先检查现有制品：尺寸、格式、DPI 元数据、原始生成器，以及各图像在何处被嵌入。
3. 若已存在 *.image.genai 文件，或需新建生成图像，则将该文件视作可编辑提示/简报（prompt/brief），并在其旁同步生成对应 .svg、.png 和 .webp 同级文件。
4. 仅实施满足评审人要求所需的最小变更：格式、分辨率、清晰度或嵌入方式。
5. 重建所有嵌入该图像的下游制品，包括 Markdown 预览、PDF、DOCX 文件及发布包（release bundles）。
6. 验证实际产出结果，而不仅限于源文件。

*.image.genai 约定

• 将该文件置于预期生成资产旁，例如 docs/architecture.image.genai。
• 在提示文件中记录图像简报（brief）、必需尺寸、样式约束、图像中必须出现的文字，以及下游消费者信息。
• 基于同一份简报生成全部同级格式：docs/architecture.svg、docs/architecture.png 和 docs/architecture.webp。
• 图表与可伸缩文档优先选用 SVG 同级文件；PDF 或需稳定光栅渲染的场景优先选用 PNG 同级文件；Web 交付优先选用 WebP 同级文件。
• 提示文件更新后，须同步再生全部同级格式，防止格式漂移（format drift）。
• 最终评审前，运行 {baseDir}/scripts/check-image-genai.py --root ，以检测：缺失生成图像同级文件的提示文件，以及生成图像时间早于其提示文件的情况。
• 在 MR 备注中注明提示文件名及所生成同级图像的尺寸。

验证检查清单

• 图像文件具有所请求的扩展名及 MIME 类型格式。
• 每个被修改的 *.image.genai 文件均拥有匹配的 .svg、.png 和 .webp 同级文件（除非 MR 明确说明某格式被有意省略）。
• 图像生成校验器（generated image checker）通过；通过时，在最终“完成定义”（Definition of Done）中添加 All Images generated 条目。
• PNG 文件按源尺寸生成，而非后期上采样所得。
• 面向 PDF 的 PNG 文件，在要求打印质量时，其像素尺寸须足以支撑显示尺寸，并附带约 300 DPI 元数据。
• 图像嵌入最终 PDF 或网页后，其中文本与细线仍清晰可读。
• PDF 或 DOCX 文件中包含预期图像对象，且不会静默丢弃不支持的格式。
• 当仓库已配置制品验证时，CI 检查须强制执行关键不变量（important invariants）。
• MR 备注须明确说明所用格式、尺寸、验证命令，以及任何尚未解决的限制条件。

GitLab 评审处理

针对图像相关的 MR 反馈，须首先响应最新评审人的请求。若新反馈与先前修复相矛盾，应立即停止延续原有方案，并显式回退或收窄至最新指定的格式。仅在最终制品完成重建并验证通过后，方可关闭相关讨论。