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 会话注入第一方工具。输出领域的两个工具分别是工具职责参考路由mcp__cherry-tools__generate_image用配置的绘画模型按提示词生成/编辑图片outputs.mdmcp__cherry-tools__report_artifacts将任务最终交付文件声明为 Cherry 界面可见的产物outputs.md从源码结构看这两个工具都是无状态内置工具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最小/最大值 步长 默认值、sizeWIDTHxHEIGHT格式且每边有范围、switch、text。每个参数的描述文本直接由describeParam()生成并注入 Schema使模型在调用时即可看到取值范围与默认值generateImageTool.ts。工具描述GENERATE_IMAGE_DESCRIPTION还明确提示生成通常需要10–60 秒仅在编辑或参考已有图片时传image_idspainting.ts。2.3 底层执行链路与结果形态调用generate_image后核心路径为generateImageFromPrompt()painting.ts它解析输入决定模式image_ids非空 →edit否则 →generatepainting.ts模式与模型能力不匹配时返回对应不支持说明不抛出edit模式下通过 FileManager 以 base64 读取参考图校验 MIME 必须为image/*失败返回PAINTING_INPUT_IMAGE_ERROR_NOTE委托AiService.generateImage携带uniqueModelId、提示词、模式、输入图、经buildParamsSchema校验的参数值以及cleanupPolicy: manual——注释说明该内置工具的输出只存在于工具调用的文本结果中不会注册为file类型的消息部分因此不参与*_file_ref表登记与自动回收painting.ts成功返回文件数组每项含id与name失败返回{ error }形状的对象而非抛出异常从而让外部 agentic loop 得以继续运转。结果在 MCP 边界上的投影值得注意成功时paintingModelOutput生成一行摘要Generated N image(s): name (id), ...同时服务器把刚持久化的图片读回为base64 内联图片内容块textimages类型随文本一起返回——因为 MCP 工具结果只携带content[]结构化 id 数组会在 SDK 边界被丢弃图片必须以内联 base64 形式随行cherryBuiltinTools.ts。读取单张图片失败只丢弃该图不会使整个生成失败。2.4 错误处理原则outputs.md明确两条铁律工具错误结果tool error result→ 阅读返回信息并修正调用不得静默重试未配置绘画模型 → 转发说明并引导配置不声称图片已产出。对应到源码未配置模型返回的是PAINTING_MODEL_NOT_CONFIGURED_NOTE这是模型可读的引导语而取消aborted signal是唯一会被重新抛出的异常——它被视作取消而非可重试错误避免请求已中止后工具循环仍在空转painting.ts。三、产物声明mcp__cherry-tools__report_artifactsreport_artifacts用于声明 Agent 为本次任务产出的最终交付文件使 Cherry 能在界面上向用户展示这些产物。3.1 使用顺序先产出后声明操作分两步顺序不可颠倒先用常规工具产出文件再调用mcp__cherry-tools__report_artifacts将其登记为交付物。REPORT_ARTIFACTS_DESCRIPTIONbuiltinTools.ts补充了边界条件在任务结束时调用一次等请求的文件真正完成后传入最终路径与可选一行摘要只列出最终交付物省略中间产物、草稿与临时文件如果任务根本没产出文件完全跳过此调用。3.2 输入形状reportArtifactsInputSchemabuiltinTools.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。按意图选择意图工具在 Cherry 界面陈列已完成文件report_artifacts通过已连接渠道把文件送达用户notify两者不可互换且对同一个文件可以合理地同时使用——先report_artifacts登记界面展示再notify推送渠道送达。从 autonomy 侧印证notify的前提是至少有一个已连接渠道且文件支持因渠道而异有的转发任意文件、有的仅图片、有的暂不支持工具会按渠道回报结果Agent 应如实转述autonomy.md。因此界面展示与渠道送达两条路径的可用性约束完全不同不能混为一谈。四、两个工具在 MCP 服务器中的实现位置如果你想深入源码可沿以下路径追查MCP 服务器装配与路由cherryBuiltinTools.ts——HANDLERS表注册report_artifactscreateGenerateImageHandler动态构建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 在使用这两个工具时应遵循调用前读实时 Schemagenerate_image的入参随绘画模型能力变化edit 模式、参数目录以ListTools返回为准不要凭记忆硬编码区分未配置与报错generate_image常驻工具列表未配置绘画模型时返回引导说明——如实转发并引导配置不要盲目重试或伪造成功工具错误结果则读取消息、修正参数后再调用先产文件再声明report_artifacts必须在最终文件完成之后调用仅列交付物、省略中间文件无文件产出则跳过按意图选工具界面陈列用report_artifacts渠道送达用notify两者不可互换也可对同一文件先后使用尊重能力边界编辑图片需模型支持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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考