图像生成技能

在为 Markdown、PDF、DOCX、网页、合并请求或发布产物创建、重新生成或审查图像、图表、截图或生成的图形时，请使用此技能。

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

图像审查循环失败的原因是：工作内容在 SVG 和 PNG 之间来回切换，优先优化技术元数据而非保留指定格式，并基于与维护者期望输出不匹配的检查标准声称图像质量达标。请将此视为默认失败模式并加以避免。

规则

• 严格保留请求的输出格式。若评审者要求 PNG 格式，请勿在未明确获得同意的情况下切换为 SVG。
• 当被要求保留特定风格或原有格式时，请勿通过重新设计图表来应对可读性反馈。
• 将位图图像直接以最终源分辨率渲染。切勿放大较小的位图并称其为高分辨率。
• 对于用于 PDF 的 PNG 图像，应至少设置 300 DPI 的元数据，并确保像素数量足以满足打印或显示尺寸需求。
• 文本、线宽、箭头、边框、间距和图标需统一缩放。即使画布很大，但文字过小仍会导致审查失败。
• 在生成图表时，优先使用矢量类绘图原语直接渲染到最终的 PNG 画布上。除非截图本身就是实际主题，否则避免使用截图或嵌套的位图片段。
• 保持源文件清晰：若交付物为 PNG，构建流程应直接使用 PNG 文件，避免隐藏的 SVG 依赖项，除非 SVG 明确作为可编辑源文件。
• 使用 *.image.genai 提示文件作为仓库中生成图像的意图来源规范。对于 example.image.genai，除非任务明确限制输出格式，否则应生成同级的 example.svg、example.png 和 example.webp 文件。
• 除非被特别要求，否则不要将通用的图像生成规则添加到仓库的 AGENTS.md 中。建议使用可复用的技能或任务本地说明。

工作流程

1. 阅读问题或合并请求讨论中关于目标产物路径、目标消费者及确切格式的要求。
2. 在修改前检查现有产物：尺寸、格式、DPI 元数据、生成工具以及图像在何处被嵌入。
3. 若存在 *.image.genai 文件或需要生成新图像，则将该文件视为可编辑的提示/说明，并在其同级目录下创建对应的 .svg、.png 和 .webp 文件。
4. 仅做最小改动以满足评审者要求：格式、分辨率、清晰度或嵌入方式。
5. 重建所有引用该图像的下游产物，例如 Markdown 预览、PDF、DOCX 文件和发布包。
6. 验证实际输出结果，而不仅仅是源文件本身。

*.image.genai 命名规范

• 将文件放置在预期生成资产的附近，例如 docs/architecture.image.genai。
• 在提示文件中包含图像说明、所需尺寸、风格约束、必须出现在图像中的文本内容，以及下游使用者信息。
• 从同一份提示文件生成所有同级格式：docs/architecture.svg、docs/architecture.png 和 docs/architecture.webp。
• 优先使用 SVG 版本用于图表和可缩放文档；PNG 版本用于 PDF 或需要稳定位图渲染的场景；WebP 版本用于网页分发。
• 在提示文件更改后，一起重新生成所有同级格式，防止格式漂移。
• 在最终审查前，运行 {baseDir}/scripts/check-image-genai.py --root <workspace> 来查找缺少生成图像同级文件的提示文件，或生成图像比提示文件更旧的情况。
• 在合并请求备注中注明提示文件名称及生成图像的尺寸。

验证检查清单

• 图像文件具有请求的扩展名和 MIME 格式。
• 每个修改过的 *.image.genai 文件都应有对应的 .svg、.png 和 .webp 同级文件，除非合并请求明确解释为何某格式被有意省略。
• 图像生成检查器通过检测；当通过时，在最终“完成定义”中添加 All Images generated。
• PNG 文件以源尺寸生成，而非后期放大。
• 用于 PDF 的 PNG 文件具备足够的像素尺寸以满足显示大小，并在要求打印质量时设置约 300 DPI 的元数据。
• 图像嵌入最终 PDF 或网页后，文字和细线仍可清晰阅读。
• PDF 或 DOCX 文件包含预期的图像对象，不会静默丢弃不支持的格式。
• CI 检查在仓库已有产物验证机制时，强制执行关键不变量。
• 合并请求备注中需说明精确格式、尺寸、验证命令及任何剩余限制。

GitLab 审查处理

针对图像相关的合并请求反馈，优先响应最新的评审请求。若新反馈与先前修复冲突，应停止沿用之前方案，明确回退或缩小范围至最新要求的格式。在最终产物重建并验证完毕后，再解决讨论。