cowart-image-gen

Cowart 图像生成

当用户希望将 AI 生成的图像放到 Cowart 画布上时，使用此技能。选中的 AI 图片 占位框可以提供精确的尺寸和放置目标，但并非必需。默认情况下，选中的占位框是临时目标，应由生成的图像替换。

前提条件

确保此工作流所需的 cowart_mcp 工具可用。不要将调用 render_cowart_canvas_widget 作为常规前提：从 Cowart 小组件发送的请求已经打开了画布，而且现有小组件会从 MCP 支持的存储中同步插入的图像。如果用户另外要求打开、重新打开或明确刷新画布，则通过画布打开工作流处理一次该请求。

通过 Cowart MCP 工具读取和写入 Cowart 状态，而不是通过 localhost 浏览器服务。

新占位框是 tldraw frame 形状，带有：

{
  "type": "frame",
  "meta": {
    "cowartAiImageHolder": true
  }
}

较旧的画布可能仍包含带有相同 meta 标记的旧版 geo 矩形占位框。两种形状都要支持。

工作流

对于来自 Cowart 侧边栏画布的后续请求，所有 Cowart 工具都使用 Cowart 上下文/消息中的确切 projectDir 和 canvasDir。这些路径可能与对话的工作目录不同。在普通项目对话中，继续像以往一样使用当前用户项目。

1. 使用 MCP get_cowart_selection 工具从 Cowart 读取选中的形状。将当前用户项目目录作为 projectDir 传入。

2. 检查选中的形状中是否恰好有一个是 AI 图像占位框。符合以下任一条件的选中形状均为占位框：

   isAiImageHolder: true
   

   或：

   meta.cowartAiImageHolder: true
   

   如果是，则使用下方的占位框替换工作流。如果不是，不要要求用户选择占位框；使用下方的独立工作流，并将生成的图像插入当前 Cowart 页面。

3. 选择放置工作流。

   占位框替换工作流：将选中占位框的 props.w 和 props.h 作为生成和放置的尺寸约束。生成前，推导并记录以下值：

   • targetWidth：选中占位框的 props.w
   • targetHeight：选中占位框的 props.h
   • targetAspectRatio：约分后的 targetWidth:targetHeight 比例（如果可整除），以及小数形式的 targetWidth / targetHeight

   如果选中占位框符合 Cowart 比例预设，例如 1:1、3:2、2:3、4:3、3:4、16:9 或 9:16，则使用对应的预设标签作为易读的宽高比。生成的图像应按照此目标尺寸和宽高比进行构图，不应依赖后续拉伸或裁剪来适配占位框。

   生成的图像应替换选中占位框，成为普通的 tldraw 图像形状：

   • parentId：与占位框相同
   • x、y、rotation：与占位框相同
   • props.w、props.h：与占位框相同

   这样最终画布中会在占位框的位置显示一个图像形状，而不是包含图像的 AI 占位框。只有在用户明确要求保留可重复使用的插槽时，才保留占位框。

   独立工作流：未选中 AI 占位框时，仍然生成图像，并将其作为普通图像形状插入当前页面。优先使用 Cowart 视图状态中的当前页面；如果选中了一个非占位框形状且它可作为上下文，则将图像放在其旁边，否则将图像放在页面空白区域。如果用户指定了尺寸或宽高比，则将其传入生成过程，并按该尺寸和比例显示。否则，使用生成位图的自然宽高比，以及 512 个画布单位等实用显示宽度。

4. 除非用户明确要求使用其他图像路径，否则使用内置的 imagegen skill 生成位图。如果请求的素材需要可见文案、标签、海报文字、广告文案、UI 文本或排版，请将这些文字直接写入图像生成提示词，让图像模型生成最终位图。除非用户明确要求本地排版、确定性文字叠加、SVG／矢量输出或其他非 imagegen 布局步骤，否则不要默认先生成无文字背景，再在本地添加文字。

   对于占位框工作流，图像生成请求必须明确包含所选占位框的目标尺寸和宽高比。将这些信息添加到模型提示词中，例如：

   Target canvas slot: 512 x 683 canvas units.
   Target aspect ratio: 3:4 (0.75 width/height).
   Compose the final bitmap for this portrait ratio so it fits the slot without cropping or stretching.
   

   如果图像生成工具或模型接受尺寸或宽高比参数，除了在提示词文本中说明外，也要传入最接近的受支持选项。如果只能提供提示词文本，则提示词文本中仍必须包含 targetWidth、targetHeight 和 targetAspectRatio。

   将图像插入 Cowart 前，仔细确认实际的本地输出图像。不要假设内置图像生成流程总会在 $CODEX_HOME/generated_images 下写入新文件。

   首选的查找顺序：

   • 如果当前图像生成工具调用返回了确切的本地图像路径，请使用该路径。
   • 如果没有返回新文件路径，请检查当前 Codex 会话的 JSONL，找到当前请求，并从最新的 image_generation_call.result 中提取 PNG／base64 载荷，然后将其写入带时间戳的输出文件。
   • 只有在能证明文件是由当前请求创建时，才使用 $CODEX_HOME/generated_images，例如确认其时间戳是在本次生成步骤之后。绝不要仅因某个文件是过期 generated_images 目录中最新的文件，就选用它。

   将解析出的文件插入 Cowart 前，请先目视检查本地位图，并确认它是为本次请求新生成的图像，而不是过期的生成素材。

   对于项目相关的输出，请将解析出的生成图像复制到所选页面的素材文件夹中：

   canvas/pages/<page-id-without-page-prefix>/assets/
   

5. 将生成的图像作为新的 tldraw 图像形状插入。

   对于占位框替换工作流，调用 insert_cowart_image 时，将占位框 ID 作为 anchorShapeId，并将 replaceAiImageHolder 留空或设为 true。MCP 工具会将图像精确放置在占位框原先的位置，并移除占位框形状：

   • type：image
   • parentId：与占位框父级相同
   • x、y、rotation：与占位框相同
   • props.w、props.h：与占位框相同
   • props.assetId：新图像素材 ID
   • meta.cowartGeneratedForAiImageHolder：占位框形状 ID
   • meta.cowartReplacedAiImageHolder：true

   如果用户明确要求保留 AI 占位框以便重复使用，则调用 insert_cowart_image 时设置 replaceAiImageHolder: false；对于框架占位框，此旧模式会将生成的图像插入为框架的子级。

   对于独立插入工作流，将图像作为普通图像插入当前页面：

   • type：image
   • parentId：当前页面 ID；除非需要将图像放在所选非占位框形状旁边，此时应使用相同的父级
   • x、y：页面上的清晰区域，或所选非占位框形状旁边
   • rotation：0
   • props.w、props.h：与生成位图宽高比相符的显示尺寸
   • props.assetId：新图像素材 ID
   • meta.cowartGeneratedStandalone：true

6. 默认在替换时删除所选占位框。在独立插入工作流中，除非用户明确要求，否则不要先创建占位框。

7. 通过 Cowart MCP 保存。优先使用 insert_cowart_image 插入生成的位图；只有在必须更新整个 tldraw 快照时，才使用 save_cowart_canvas_state。

   图像素材中优先使用页面本地素材 URL：

   /page-assets/<page-id-without-page-prefix>/<filename>
   

8. 让 Cowart 小组件从 MCP 支持的存储中刷新，然后确认插入的形状 ID、最终尺寸、目标宽高比、保存的资源路径，以及使用占位框替换工作流时被替换的占位框 ID。

注意

• 如果占位框是旧版旋转的 geo 矩形，请在替换图像上保留相同的 rotation。
• 如果占位框内已有由旧版 Cowart 生成的图像，则替换占位框时应移除占位框及其子图像形状，然后在占位框原来的位置创建一个普通图像形状。
• 不要仅仅因为未选中 AI 图片 占位框就拒绝生成。生成位图并将其插入当前 Cowart 页面。
• 切勿覆盖现有资源文件；请使用带时间戳的文件名。