企业官网建设流程全解析

Roo Code generate_image 工具指南：从文生图到图像编辑的完整实战

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

generate_image是 Roo Code 提供的实验性 AI 图像工具，可通过文本提示词直接生成新图片，或对工作区内已有图片进行编辑与风格转换，并将结果保存到指定路径。本文以该工具为核心，完整讲解其参数、工作流程、配置前提与源码级实现原理，帮助你快速掌握在 Roo Code 中完成文生图、图生图、高清增强等视觉任务的能力。

工具概览

generate_image是 Roo Code 内置工具之一，其声明位于 packages/types/src/tool.ts 的工具名枚举中。它依托 AI 模型实现两类核心操作：

• 文生图（Text-to-Image）：仅提供提示词，从零生成新图像；
• 图生图（Image-to-Image）：提供提示词与输入图片路径，按提示词对原图进行编辑与变换（如风格迁移、增强、修复）。

该能力由OpenRouter提供模型接入。注意：此功能为实验性特性，需在设置中手动开启后才能调用（见下文"配置与前置条件"）。

参数说明

工具接受三个参数，其中prompt与path为必填：

从源码 GenerateImageTool.ts 可以看出，prompt与path缺失时会被视为工具使用错误（consecutiveMistakeCount计数递增并记录recordToolError），并触发缺少参数的错误提示。因此两个必填参数必须严格提供。

输入图片格式校验

当提供image参数时，工具会先读取文件并校验扩展名。源码中硬编码的支持列表为：

const supportedFormats = ["png", "jpg", "jpeg", "gif", "webp"]

（见 GenerateImageTool.ts）

不在列表内的格式会直接报错终止。读取成功后，图片会被转换为 Base64 的 data URL（data:image/...;base64,...）随请求发送给模型，其中jpg会按jpeg处理 MIME 类型。

输出扩展名自动补全

保存结果时，工具会检测path是否已包含png、jpg、jpeg扩展名；若未包含，则根据模型实际返回的图片格式自动追加.png或.jpg：

if (!finalPath.match(/\.(png|jpg|jpeg)$/i)) { finalPath = `${finalPath}.${imageFormat === "jpeg" ? "jpg" : imageFormat}` }

（见 GenerateImageTool.ts）

因此你在指定path时既可以直接写images/sunset.png，也可以只写目录与文件名（如images/sunset）让工具自动补全。

使用场景

generate_image适用于以下典型场景：

• 为文档、原型或 Mockup 创建视觉素材；
• 生成占位图与插图；
• 对已有图片进行变换（风格迁移、清晰度增强、内容修改）；
• 根据文字描述绘制示意图或可视化说明；
• 快速进行 UI 元素的视觉原型设计。

结合功能文档（image-generation.md）中的前后对比，该工具最大的价值在于把"外部站点生成→下载→导入工作区"的繁琐链路，收敛为对话内一步完成：直接向 Roo 提出需求、审批通过后，图片即保存进项目目录，可继续在项目中编辑使用。

工作流程（How It Works）

当generate_image被调用时，其执行链路（GenerateImageTool.ts）分为以下阶段：

1. 实验开关校验：检查IMAGE_GENERATION实验特性是否已启用，未启用则直接返回错误提示（见 experiments.ts 中的EXPERIMENT_IDS.IMAGE_GENERATION）。
2. 参数校验：验证必填的prompt与path。
3. 访问控制校验：输出路径与输入图片路径都需通过.rooignore的访问检查（rooIgnoreController.validateAccess），被屏蔽的路径无法读写。
4. 模式选择：若提供image参数则进入编辑模式（读取图片并转 Base64）；否则进入生成模式。
5. 模型与 Provider 解析：通过getImageGenerationProvider确定 Provider，并从IMAGE_GENERATION_MODELS中选择模型（见下文"模型选择"）。
6. API Key 校验：使用 OpenRouter 时必须已配置 API Key。
7. 用户审批：通过askApproval请求用户确认（写入保护路径或工作区外路径时会有相应标记）。
8. API 请求：调用OpenRouterHandler.generateImage向 OpenRouter 发送请求（含提示词与可选输入图）。
9. 结果处理与保存：校验返回的 Base64 数据，创建目录并写文件，同时记录文件上下文（trackFileContext）。
10. 反馈与预览：在对话中展示图片预览（带缓存戳的 webview URI），并返回保存路径。

底层调用链

GenerateImageTool.execute中通过new OpenRouterHandler({} as any).generateImage(...)发起请求（GenerateImageTool.ts）。该方法的实现位于 src/api/providers/openrouter.ts：

• 默认请求基地址为https://openrouter.ai/api/v1，可通过openRouterBaseUrl配置覆盖；
• OpenRouter只支持 chat completions 方式生成图片，不支持/images/generations端点。

实际 HTTP 请求由共享实现generateImageWithProvider完成（src/api/providers/utils/image-generation.ts）：

• 请求POST {baseURL}/chat/completions；
• 请求体中携带modalities: ["image", "text"]声明多模态输出；
• 当提供输入图片时，消息内容为[{type:"text", text: prompt}, {type:"image_url", image_url:{url: inputImage}}]结构，否则直接使用纯文本；
• 响应从choices[0].message.images[0].image_url.url中提取 Base64 图片数据；
• 若响应非 2xx 或返回错误对象，会通过 i18n 消息模板（见 i18n 资源）返回可读的错误信息。

此外，image-generation.ts 还实现了基于 OpenAI Images API（/images/generations）的generateImageWithImagesApi，用于支持 BFL（Black Forest Labs）类模型：当模型以bfl/开头时，输入图片通过providerOptions.blackForestLabs.inputImage传递，并支持size、quality、outputFormat等扩展参数。

使用示例

1. 生成新图片（文生图）

<generate_image> <prompt>A beautiful sunset over mountains with vibrant orange and purple colors</prompt> <path>images/sunset.png</path> </generate_image>

2. 编辑已有图片（图生图/风格迁移）

<generate_image> <prompt>Transform this image into a watercolor painting style</prompt> <path>images/watercolor-output.png</path> <image>images/original-photo.jpg</image> </generate_image>

3. 高清增强与细节优化

<generate_image> <prompt>Upscale this image to higher resolution, enhance details, improve clarity and sharpness while maintaining the original content and composition</prompt> <path>images/enhanced-photo.png</path> <image>images/low-res-photo.jpg</image> </generate_image>

4. 对话中的自然语言请求

在聊天中也可以直接以自然语言发起，例如：

• "Transformphotos/portrait.jpginto a watercolor painting and save asart/watercolor-portrait.png"
• "Upscale and enhanceimages/logo.pngto higher resolution"
• "Apply a vintage filter toscreenshots/app.png"

Roo 会据此生成对应的generate_image调用，并在需要时与你确认保存路径。

配置与前置条件

generate_image是 Image Generation 功能 的程序化接口，使用前需要完成以下配置：

1. 开启实验特性

• 位置：Settings（设置）> Experimental（实验性功能）
• 默认值：关闭
• 作用：只有开启后，工具调用才会被允许；否则工具会返回"Image generation is an experimental feature that must be enabled in settings"的错误。

2. 配置 OpenRouter API Key

• 默认值：空（必填）
• 作用：授权图片生成请求。在源码 GenerateImageTool.ts 中，当 Provider 为 OpenRouter 且未配置 Key 时，会直接报错终止。

3. 选择生成模型

• 默认值：Gemini 2.5 Flash Image（google/gemini-2.5-flash-image）
• 可用模型：以 packages/types/src/image-generation.ts 中IMAGE_GENERATION_MODELS常量为准，目前包括：

注意：功能文档编写时模型列表曾以 Gemini 2.5 Flash Image 及其免费变体为主，实际可选模型以当前仓库常量为准。源码中还存在模型回退逻辑：若所选模型与当前 Provider 不匹配或未选择模型，会自动选取该 Provider 的第一个可用模型（GenerateImageTool.ts）。getImageGenerationProvider（image-generation.ts）则负责 Provider 解析，并为旧用户保留向后兼容的默认行为。

4. 其他前提

• 网络可访问 OpenRouter API；
• 工作区文件夹已打开且可写；
• 输入/输出路径不被.rooignore屏蔽。

提高生成质量：提示词建议

功能文档给出了提升效果的提示词要素，建议在描述中包含：

• 风格（Style）：艺术媒介、艺术流派或特定艺术家风格；
• 情绪（Mood）：情感基调与氛围；
• 色彩（Color palette）：具体颜色或配色方案；
• 相机/光线（Camera/Lighting）：机位角度、透视与光照条件；
• 宽高比（Aspect ratio）：画面尺寸与方向。

提示词越具体，模型越容易产出符合预期的构图与质感。

限制与注意事项

综合工具文档与源码，使用该工具需注意以下限制：

• 实验性特性：行为可能在后续版本发生变化，且必须显式开启实验开关；
• 依赖 API 配置：必须配置 OpenRouter API Key，且使用量受 OpenRouter 计费规则约束，可能产生费用；
• 输出格式：每次请求生成一张图片，输出格式支持 PNG 或 JPG；
• 输入格式：仅支持 PNG、JPG、JPEG、GIF、WEBP 五种格式；
• 质量与耗时：生成质量取决于所选模型与提示词质量，耗时随复杂度与模型不同而波动；
• 结果不确定性：部分图像变换可能无法达到预期效果；
• 路径访问限制：被.rooignore屏蔽的路径无法读写；
• OpenRouter 端点限制：当前实现仅走 chat completions 通道（modalities方式），不受支持的模型可能在运行时返回错误。

小结

generate_image将 AI 图像能力以标准工具的形式嵌入 Roo Code 的开发闭环：开启实验开关、配置 OpenRouter Key、选定模型后，即可在对话中完成文生图、图生图和图片增强，结果直接落盘到工作区并实时预览。其核心实现分散在工具层（GenerateImageTool.ts）、模型常量层（packages/types/src/image-generation.ts）与请求层（src/api/providers/utils/image-generation.ts），理解这三层结构有助于你排查配置与调用问题。更多模型选型、最佳实践与故障排查信息，可继续阅读 Image Generation 功能文档。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code