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-Codegenerate_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为必填参数必填类型说明prompt是string描述要生成内容或编辑方式的文本提示词path是string生成/编辑结果的保存路径相对工作区缺少扩展名时工具会自动补全image否string待编辑/变换的输入图片路径相对工作区支持 PNG、JPG、JPEG、GIF、WEBP从源码 GenerateImageTool.ts 可以看出prompt与path缺失时会被视为工具使用错误consecutiveMistakeCount计数递增并记录recordToolError并触发缺少参数的错误提示。因此两个必填参数必须严格提供。输入图片格式校验当提供image参数时工具会先读取文件并校验扩展名。源码中硬编码的支持列表为const supportedFormats [png, jpg, jpeg, gif, webp]见 GenerateImageTool.ts不在列表内的格式会直接报错终止。读取成功后图片会被转换为 Base64 的 data URLdata:image/...;base64,...随请求发送给模型其中jpg会按jpeg处理 MIME 类型。输出扩展名自动补全保存结果时工具会检测path是否已包含png、jpg、jpeg扩展名若未包含则根据模型实际返回的图片格式自动追加.png或.jpgif (!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分为以下阶段实验开关校验检查IMAGE_GENERATION实验特性是否已启用未启用则直接返回错误提示见 experiments.ts 中的EXPERIMENT_IDS.IMAGE_GENERATION。参数校验验证必填的prompt与path。访问控制校验输出路径与输入图片路径都需通过.rooignore的访问检查rooIgnoreController.validateAccess被屏蔽的路径无法读写。模式选择若提供image参数则进入编辑模式读取图片并转 Base64否则进入生成模式。模型与 Provider 解析通过getImageGenerationProvider确定 Provider并从IMAGE_GENERATION_MODELS中选择模型见下文模型选择。API Key 校验使用 OpenRouter 时必须已配置 API Key。用户审批通过askApproval请求用户确认写入保护路径或工作区外路径时会有相应标记。API 请求调用OpenRouterHandler.generateImage向 OpenRouter 发送请求含提示词与可选输入图。结果处理与保存校验返回的 Base64 数据创建目录并写文件同时记录文件上下文trackFileContext。反馈与预览在对话中展示图片预览带缓存戳的 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用于支持 BFLBlack Forest Labs类模型当模型以bfl/开头时输入图片通过providerOptions.blackForestLabs.inputImage传递并支持size、quality、outputFormat等扩展参数。使用示例1. 生成新图片文生图generate_image promptA beautiful sunset over mountains with vibrant orange and purple colors/prompt pathimages/sunset.png/path /generate_image2. 编辑已有图片图生图/风格迁移generate_image promptTransform this image into a watercolor painting style/prompt pathimages/watercolor-output.png/path imageimages/original-photo.jpg/image /generate_image3. 高清增强与细节优化generate_image promptUpscale this image to higher resolution, enhance details, improve clarity and sharpness while maintaining the original content and composition/prompt pathimages/enhanced-photo.png/path imageimages/low-res-photo.jpg/image /generate_image4. 对话中的自然语言请求在聊天中也可以直接以自然语言发起例如Transformphotos/portrait.jpginto a watercolor painting and save asart/watercolor-portrait.pngUpscale and enhanceimages/logo.pngto higher resolutionApply a vintage filter toscreenshots/app.pngRoo 会据此生成对应的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 Imagegoogle/gemini-2.5-flash-image可用模型以 packages/types/src/image-generation.ts 中IMAGE_GENERATION_MODELS常量为准目前包括模型标识展示名google/gemini-2.5-flash-imageGemini 2.5 Flash Imagegoogle/gemini-3-pro-image-previewGemini 3 Pro Image Previewopenai/gpt-5-imageGPT-5 Imageopenai/gpt-5-image-miniGPT-5 Image Miniblack-forest-labs/flux.2-flexBlack Forest Labs FLUX.2 Flexblack-forest-labs/flux.2-proBlack Forest Labs FLUX.2 Pro注意功能文档编写时模型列表曾以 Gemini 2.5 Flash Image 及其免费变体为主实际可选模型以当前仓库常量为准。源码中还存在模型回退逻辑若所选模型与当前 Provider 不匹配或未选择模型会自动选取该 Provider 的第一个可用模型GenerateImageTool.ts。getImageGenerationProviderimage-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考