Cherry Studio Agent 输出管线实战：generate_image 图片生成与 report_artifacts 产物声明

Cherry Studio Agent 输出管线实战：generate_image 图片生成与 report_artifacts 产物声明

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

导读

本文聚焦 Cherry Studio 为通用 Agent 提供的第一方输出能力：通过mcp__cherry-tools__generate_image使用用户配置的绘画模型渲染图片，以及通过mcp__cherry-tools__report_artifacts将最终交付文件登记到 Cherry 界面。你将掌握这两个 MCP 工具的触发前提、路由语义、参数契约与错误恢复规则，并理解它们在 Cherry 源码中的底层实现——从绘画模型解析、错误分类到产物登记的完整链路。

本文以 outputs.md 为骨架，它是 cherry-tool-guide 技能路由表（"Generate an image" 与 "Declare final deliverable file(s)" 两行）指向的领域参考。文中的工具名均为全限定形式（mcp__server__tool），精确的参数名、枚举与必填字段以会话内实时工具 Schema 为准，本指南只描述路由、前提与语义。

一、两个输出工具的分工概览

Cherry Studio 通过一个进程内 MCP 服务器cherry-tools（版本 1.0.0）向 Agent 会话注入第一方工具。输出领域的两个工具分别是：

从源码结构看，这两个工具都是"无状态内置工具"（stateless builtins）：它们不携带按 Agent 的授权信息，处理器签名只有(args, signal)，与领域工具（如cron/notify/config所属的 autonomy 组、kb_*知识库组）在服务器内部按协议分发，见 cherryBuiltinTools.ts。其中generate_image的处理器在每次调用时动态解析当前配置的绘画模型（resolveConfiguredPaintingModel()），这正是"工具常驻列表、但能力依赖配置"的根源。

关于参数形态的权威性：outputs.md与本文均不重复参数形状。每次调用前必须读取会话内的实时工具 Schema——cherry-tools服务器在ListTools时会根据当前绘画模型的能力块动态生成generate_image的入参 Schema，见下文第三节。

二、图片生成：mcp__cherry-tools__generate_image

该工具使用用户配置的绘画模型（painting model）将一段提示词渲染为图片。它是 Cherry 绘画能力的 MCP 桥接形态，与 AI-SDK 内置工具共享同一套绘图核心。

2.1 前提：绘画模型必须已配置

关键语义是——该工具始终出现在工具列表中，但只有在配置了绘画模型后才真正可用：

• 若未配置绘画模型，工具不会报错消失，而是返回一段说明性文字（note）而非图片；
• Agent 必须如实转发这段说明，并引导用户去配置绘画模型（Settings > Default Model），绝不能声称图片已生成；
• 未配置时的重试永远不可能成功，因此说明文字的作用是引导用户离开重试循环。

这一行为在源码中有非常明确的证据。绘图核心 painting.ts 定义了三类面向模型的错误说明常量：

// 临时性失败（provider/网络抖动）——重试可能成功 PAINTING_ERROR_NOTE = 'Image generation failed (provider error); retry or inform the user.' // 永久性失败：未配置绘画模型——重试不可能成功，必须引导配置 PAINTING_MODEL_NOT_CONFIGURED_NOTE = 'No painting model is configured. Tell the user to pick one in Settings > Default Model; do not retry — it cannot succeed until then.' // 模型不支持编辑 / 不支持无输入图生成 PAINTING_EDIT_NOT_SUPPORTED_NOTE / PAINTING_GENERATE_NOT_SUPPORTED_NOTE

绘画模型的解析路径是resolveConfiguredPaintingModel()：读取偏好项feature.paintings.default_model_id，若为空直接返回null；随后校验该模型在 ModelService 中仍存在，并从 ProviderRegistryService 查询其ImageGenerationSupport能力块（painting.ts）。MCP 服务器在resolveHandler/resolveHandlers中每次调用时都重新执行这一解析（cherryBuiltinTools.ts），因此"中途配置好模型后无需重启即可生效"。

2.2 参数契约：提示词与能力驱动参数

generate_image的入参 Schema 由 generateImageTool.ts 依据当前绘画模型的能力块动态构建，并非固定形状：

• prompt（必填）：字符串，trim 后长度 1–4000 字符，描述要求"生动、自包含，包含主体、风格、构图与氛围"；
• image_ids（按能力出现）：仅当模型能力包含edit模式时存在。它接收已有图片的FileEntry id（最多 1 张，MAX_INPUT_IMAGES = 1），用于编辑或以参考图形式生成；省略则生成全新图片。若模型只有编辑能力，该字段为必填（generateImageTool.ts）；
• 能力驱动参数（按模型支持动态出现）：来自 provider-registry 的IMAGE_PARAM_CATALOG规范化参数目录，类型包括enum（枚举值 + 默认值）、range（最小/最大值 + 步长 + 默认值）、size（WIDTHxHEIGHT格式且每边有范围）、switch、text。每个参数的描述文本直接由describeParam()生成并注入 Schema，使模型在调用时即可看到取值范围与默认值（generateImageTool.ts）。

工具描述（GENERATE_IMAGE_DESCRIPTION）还明确提示：生成通常需要10–60 秒，仅在编辑或参考已有图片时传image_ids（painting.ts）。

2.3 底层执行链路与结果形态

调用generate_image后，核心路径为generateImageFromPrompt()（painting.ts），它：

1. 解析输入决定模式：image_ids非空 →edit，否则 →generate（painting.ts）；
2. 模式与模型能力不匹配时，返回对应不支持说明（不抛出）；
3. edit模式下通过 FileManager 以 base64 读取参考图，校验 MIME 必须为image/*，失败返回PAINTING_INPUT_IMAGE_ERROR_NOTE；
4. 委托AiService.generateImage，携带uniqueModelId、提示词、模式、输入图、经buildParamsSchema校验的参数值，以及cleanupPolicy: 'manual'——注释说明该内置工具的输出只存在于工具调用的文本结果中，不会注册为file类型的消息部分，因此不参与*_file_ref表登记与自动回收（painting.ts）；
5. 成功返回文件数组（每项含id与name）；失败返回{ error }形状的对象而非抛出异常，从而让外部 agentic loop 得以继续运转。

结果在 MCP 边界上的投影值得注意：成功时paintingModelOutput生成一行摘要（Generated N image(s): name (id), ...），同时服务器把刚持久化的图片读回为base64 内联图片内容块（text+images类型），随文本一起返回——因为 MCP 工具结果只携带content[]，结构化 id 数组会在 SDK 边界被丢弃，图片必须以内联 base64 形式随行（cherryBuiltinTools.ts）。读取单张图片失败只丢弃该图，不会使整个生成失败。

2.4 错误处理原则

outputs.md明确两条铁律：

1. 工具错误结果（tool error result）→ 阅读返回信息并修正调用，不得静默重试；
2. 未配置绘画模型 → 转发说明并引导配置，不声称图片已产出。

对应到源码，未配置模型返回的是PAINTING_MODEL_NOT_CONFIGURED_NOTE，这是模型可读的引导语；而取消（aborted signal）是唯一会被重新抛出的异常——它被视作取消而非可重试错误，避免请求已中止后工具循环仍在空转（painting.ts）。

三、产物声明：mcp__cherry-tools__report_artifacts

report_artifacts用于声明 Agent 为本次任务产出的最终交付文件，使 Cherry 能在界面上向用户展示这些产物。

3.1 使用顺序：先产出，后声明

操作分两步，顺序不可颠倒：

1. 先用常规工具产出文件；
2. 再调用mcp__cherry-tools__report_artifacts将其登记为交付物。

REPORT_ARTIFACTS_DESCRIPTION（builtinTools.ts）补充了边界条件：在任务结束时调用一次，等请求的文件真正完成后传入最终路径与可选一行摘要；只列出最终交付物，省略中间产物、草稿与临时文件；如果任务根本没产出文件，完全跳过此调用。

3.2 输入形状

reportArtifactsInputSchema（builtinTools.ts）结构为：

• artifacts（必填，至少 1 项），每项包含：
  • path（必填）：交付文件的绝对路径或工作区相对路径；
  • description（可选）：对该文件的一行说明；
• summary（可选）：对整个产出行的一句话总结。

处理器端的行为非常简单：解析入参后仅返回确认文本Recorded N artifact(s).。源码注释点明了它的本质——工具的价值在入参本身，那是一份面向消费者的数据契约（后续由渲染层的 artifacts 卡片消费），处理器只负责确认（cherryBuiltinTools.ts）。

3.3 它是"声明"，不是"传输"

这是本工具最重要的语义边界：

report_artifacts只让 Cherry 在 UI 中感知到交付物，它不会把文件推送到任何地方。

若需要把文件通过已连接的 IM 渠道实际发送给用户，应当改用mcp__cherry-tools__notify（详见 autonomy.md）。按意图选择：

两者不可互换，且对同一个文件可以合理地同时使用——先report_artifacts登记界面展示，再notify推送渠道送达。

从 autonomy 侧印证：notify的前提是至少有一个已连接渠道，且文件支持因渠道而异（有的转发任意文件、有的仅图片、有的暂不支持），工具会按渠道回报结果，Agent 应如实转述（autonomy.md）。因此"界面展示"与"渠道送达"两条路径的可用性约束完全不同，不能混为一谈。

四、两个工具在 MCP 服务器中的实现位置

如果你想深入源码，可沿以下路径追查：

• MCP 服务器装配与路由：cherryBuiltinTools.ts——HANDLERS表注册report_artifacts；createGenerateImageHandler动态构建generate_image处理器；ListTools时对 Schema 剥离$schema标记以免严格 MCP 客户端拒绝（cherryBuiltinTools.ts）；
• 绘图核心（运行时无关）：painting.ts——错误说明常量、绘画模型解析、模式判定、参数抽取与AiService.generateImage委托；
• 工具 Schema 构建：generateImageTool.ts——基于 provider-registry 能力块生成提示词与能力参数校验；
• 共享线协议（主进程与渲染层共用）：builtinTools.ts——REPORT_ARTIFACTS_TOOL_NAME、reportArtifactsInputSchema、REPORT_ARTIFACTS_DESCRIPTION，以及generate_image输出类型的再导出。

五、实战最佳实践清单

综合outputs.md与相关源码，Agent 在使用这两个工具时应遵循：

1. 调用前读实时 Schema：generate_image的入参随绘画模型能力变化（edit 模式、参数目录），以ListTools返回为准，不要凭记忆硬编码；
2. 区分"未配置"与"报错"：generate_image常驻工具列表，未配置绘画模型时返回引导说明——如实转发并引导配置，不要盲目重试或伪造成功；工具错误结果则读取消息、修正参数后再调用；
3. 先产文件再声明：report_artifacts必须在最终文件完成之后调用，仅列交付物、省略中间文件，无文件产出则跳过；
4. 按意图选工具：界面陈列用report_artifacts，渠道送达用notify；两者不可互换，也可对同一文件先后使用；
5. 尊重能力边界：编辑图片需模型支持edit模式且传入 FileEntry id（最多 1 张）；生成需支持generate模式，不支持时工具会给出明确说明，按说明调整而不是重复同样的调用。

结语

generate_image与report_artifacts分别回答了"如何产出图片"与"如何交付文件"两个问题：前者是依赖绘画模型配置的条件能力，失败时以模型可读的说明而非异常返回，保证 Agent 循环不中断；后者是纯粹的声明契约，把"界面展示"与"渠道送达"严格解耦。理解这两条边界，是 Agent 在 Cherry Studio 中正确完成绘图与交付任务、避免"假成功"与"静默重试"的关键。

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio