人工智能AI 应用桌面应用代码智能体MCP Clients【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址https://gitcode.com/gh_mirrors/cl/cc-haha点击查看免费下载导读本文以 cc-haha 仓库内置的imagegen技能文档 src/skills/bundled/imagegen/SKILL.md 为核心骨架结合ImageGenTool工具实现、图像生成服务配置与配套测试用例系统讲解在桌面端如何正确调用ImageGen与ImageEdit两个原生工具从生成 / 编辑的请求形态判定、referenced_image_paths的安全来源约束到完整 art-direction 提示词撰写规范与输出参数aspect_ratio、resolution、count等的取值语义。读完本文你将掌握一套可复用的图像生成调用协议理解宿主如何托管鉴权、路由模型与落盘输出并能规避常见的路径伪造、轮次漂移与重试陷阱。imagegen是 cc-haha 桌面端内置bundled技能之一随对话自动注入到模型上下文当用户请求创建或生成一张图时该技能即被触发其注册逻辑位于 src/skills/bundled/imagegen.tsfrontmatter 中声明了allowed-tools: ImageGen, ImageEdit并仅在桌面会话配置了图像生成提供方getImageGenerationRuntimeConfig() ! null时启用见 imagegen.ts 与 ImageGenTool.ts。一、请求形态判定生成还是编辑原技能文档给出的第一决策原则是一个全新的视觉资产走ImageGen一个对既有视觉资产的保留、合成或修改走ImageEdit。这一分工在工具实现层面被严格固化ImageGen的输入 schema刻意不包含任何图片路径参数generationInputSchema仅由commonInputShape()构成工具描述也明确写道 This tool does not accept source-image paths; use ImageEdit for editsImageGenTool.ts。ImageEdit在公共参数之上追加了必填的referenced_image_paths类型为字符串数组min(1)、max(3)即单次调用最多接收 3 张源图ImageGenTool.ts。文档进一步要求一个独立提示词 一次工具调用count参数仅用于同一提示词的多张变体不同的概念必须拆分调用。从实现看count的取值范围是 1–4z.number().int().min(1).max(4).default(1)见 ImageGenTool.ts后端会按count生成多个请求体如 backend.ts 的buildCompatibleRequestBodies对每个 count 单独构造一次请求。多图编辑的正确姿势每张图独立编辑为多张互不相关的图做独立修改时一次调用处理一张图多图合成为同一目标只有用户明确希望将多图合成或作为共同参考时才把多张图放进同一次ImageEdit调用多轮编辑用上一轮返回的最新输出作为下一轮的edit_target即下一轮的referenced_image_paths并且每一轮都要重复声明身份、版式、文字与保持不变区域等全部约束防止编辑结果漂移。二、referenced_image_paths来源合法性与路径安全这是ImageEdit使用中最容易被误用、也是文档着墨最重的部分。原文档明确规定referenced_image_paths只能填入本会话中用户提供的图片合法来源仅有三类会话中由[Image source: ...]暴露出的附件路径用户通过明确附加的文件前序ImageGen调用返回的本地路径。严禁自行臆造、搜索或替换其他文件系统路径也严禁模型自己从磁盘读取图片作为输入如果用户指的是你手中没有路径的图应当请用户重新附加。该约束不是文档层面的软建议而是后端硬校验。在 backend.ts 的prepareInputImages中输入路径会先做realpath解析随后必须满足二选一的条件才被放行位于宿主托管的上传目录内会话上传目录、粘贴/拖入的图片存储目录、generated-images会话目录见defaultInputRootDirs()backend.ts或被isUserProvidedImage判定为用户显式提供的图片其余任何路径——模型 glob 出来的、从文件里扒出来的、猜测的——都会被拒绝并抛出 Image edit input was not provided by the user in this session 错误此外还会校验文件必须存在且是常规文件、非空且不超过20 MBMAX_INPUT_IMAGE_BYTES并以魔数检测确认为 PNG/JPEG/WebP 之一backend.ts。同时技能与工具的 prompt 都明确要求不要把 API Key 写进技能或提示词。测试 imagegen.test.ts 专门断言了技能 prompt 中会包含上述安全约束文本、绝不包含CC_HAHA_IMAGE_API_KEY等凭据。三、构建提示词一份完整的 art-direction 简报原文档要求把用户请求转译成一份完整的艺术指导简报并保留所有相关细节。建议覆盖以下要素用例与图像类型use case and image type主体、动作与关键属性subject, action, important attributes环境与上下文environment and context构图、取景与机位composition, framing, camera angle光线与氛围lighting and mood视觉风格或媒介visual style or medium色彩基调color palette必须出现在图内的精确文字exact text需要规避的元素与限制constraints and elements to avoid编辑类提示词的结构化写法以每个输入的编号角色开头如image 1: ...、image 2: ...随后写明change only X; keep Y unchanged明确保留区域合成场景下指明每个编号图像贡献的主体或视觉属性并保留请求的身份identity不要在工具提示词里依赖会话代词如 it、the previous one因为工具调用是独立执行的上下文代词会产生歧义。细分场景的补充指导人名与图上文字保留用户的原话与措辞图表类指定层级结构、阅读顺序、标签与连线关系写实类在必要时描述镜头焦段、景深、光照方向与材质细节。底层提示词兜底同样存在于工具定义中ImageGen的prompt()要求保留完整的用户规格、一次调用对应一个独立提示词、provider 与模型由会话决定而非工具参数、失败时不自动重试见 ImageGenTool.ts。四、输出参数aspect_ratio / resolution / count 等的取值语义ImageGen与ImageEdit共享同一套公共输入参数commonInputShape()ImageGenTool.ts参数类型 / 取值默认值说明promptstring非空必填完整的视觉提示词countint1–41同一提示词的变体数量aspect_ratio见下枚举无auto输出宽高比resolution1k|2k无仅在需要更高分辨率且受支持时使用2ksizeauto|1024x1024|1024x1536|1536x1024无OpenAI 兼容的 size 参数qualityauto|low|medium|high无质量档位backgroundauto|opaque|transparent无背景透明背景仅在用户明确需要可复用资产时使用output_formatpng|jpeg|webp无输出格式referenced_image_pathsstring[]1–3仅 ImageEdit有序的源图路径aspect_ratio的完整枚举为auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20ImageGenTool.ts。当用户描述的是方形、竖版、横版、横幅、手机壁纸等布局诉求时应优先用aspect_ratio表达。后端在面向 OpenAI 兼容接口时会做宽高比到尺寸的映射sizeForAspectRatiobackend.ts1:1→1024x1024竖版比例9:16、3:4、2:3、1:2、9:19.5、9:20→1024x1536其余横版比例 →1536x1024auto或未指定时不附加 size 字段交由提供方自行决定。而 Grok 路径则相反优先透传aspect_ratio/resolutionbuildGrokRequestBodybackend.ts。这提醒使用者不同提供方的参数偏好不同宿主层会做适配工具层则统一暴露上表语义。五、Provider 路由与凭据托管模型选择不由工具决定原文档反复强调Provider 与图像模型选择来自当前桌面会话两者都不属于工具参数。其实现机制是宿主通过环境变量注入图像生成运行时配置由 src/services/imageGeneration/config.ts 统一解析环境变量说明CC_HAHA_IMAGE_PROVIDER_KIND提供方类型openai_oauthChatGPT 登录|grok_oauthx.ai 登录|openai_imagesOpenAI 兼容自定义接口CC_HAHA_IMAGE_PROVIDER_ID提供方标识必填CC_HAHA_IMAGE_MODEL图像模型必填默认参考值gpt-image-2config.ts与grok-imagine-image-qualityconfig.tsCC_HAHA_IMAGE_BASE_URL自定义接口 Base URLopenai_images必填CC_HAHA_IMAGE_API_KEY自定义接口 API Keyopenai_images必填只有providerId、model均存在且kind合法时才返回配置openai_images额外要求 Base URL 与 API Key 齐全config.ts。内置 Provider 预设中也可见图像模型配置例如providerPresets.json中defaultImageGeneration给出了doubao-seedream-5-0的示例providerPresets.json。路由分派位于 backend.ts 的requestImagesopenai_oauth→ 走 ChatGPT Codex 端点以 SSE 流解析image_generation_call事件requestChatGPTImages/parseChatGPTImageStreambackend.ts令牌通过ensureFreshOpenAITokens自动续期grok_oauth→ 走https://api.x.ai/v1/images/generations或.../edits401 时自动强制刷新令牌并重放一次backend.tsopenai_images→ 走自定义 Base URL 的/images/generations或/images/editsURL 构建兼容.../v1、.../v1/images/generations等常见形态buildImagesApiUrlbackend.ts。鉴权、令牌刷新、模型路由与密钥存储全部由桌面宿主托管因此技能与提示词都要求永远不要让用户把 API Key 放进技能或提示词——这也是 imagegen.test.ts 验证的核心行为之一启用技能时 prompt 中不泄露fake-apismart-image-key。六、输出落盘与结果呈现不要重复嵌入本地路径每次成功调用后后端会把返回的图片数据base64 或受信任的下载 URL写入本地目录并返回绝对路径默认输出目录为~/.cc-haha/generated-images/{会话ID}defaultOutputDirbackend.ts目录以0o700权限创建文件以0o600权限写入落盘前做魔数检测确认是 PNG/JPEG/WebP 才会保存文件名形如{时间戳}-{序号}-{UUID}.{扩展名}persistImagebackend.ts单张图片上限30 MBMAX_IMAGE_BYTES整个请求超时上限10 分钟IMAGE_REQUEST_TIMEOUT_MS错误响应体最多保留 500 字符且自动脱敏 Bearer 令牌与sk-密钥safeUpstreamErrorbackend.ts。工具返回的结构化结果为image_generation_result包含operationgenerate/edit、inputImageCount、providerId、providerKind、model、prompt、images[]与durationMs字段ImageGenTool.ts。呈现规则宿主卡片已经负责展示并打开保存的图片因此最终回答中不要重复、链接或内嵌返回的本地路径也不要把 base64 数据带进对话流。文档的收尾要求是成功调用后用一句话简要总结创建了什么 / 改动了什么即可。七、错误处理与重试纪律原文档明确规定Provider 返回错误时不要自动重试图像工具而应解释失败原因把重试还是换 Provider的决定权交还给用户。这条纪律同样被固化进工具实现ImageGen/ImageEdit的prompt()都写入了 If a provider call fails, do not retry the image tool automatically; explain the error and wait for the user to decideImageGenTool.ts未配置图像提供方时工具调用会抛出 Image generation is not configured for the current provider. Enable it in provider settings.ImageGenTool.ts令牌失效等可恢复场景如 Grok 401由宿主层自动刷新重试一次但模型侧的自动重试被禁止——这正是宿主负责可靠性、模型负责决策的分层设计。八、与宿主界面的协同占位符与流式呈现文档还提到一个容易被忽略的交互细节宿主会为每个请求的图片显示一个占位符并在每张图片保存完成时逐个替换对应槽位The host displays one placeholder per requested image and replaces each slot as the saved image becomes available。这意味着在多图请求count 1或多张独立编辑场景下图片是异步、逐个出现在对话卡片中的模型的文字总结不应假定所有图片已同时就绪更不应尝试去读取尚未落盘的图片。总结imagegen技能把图像生成从一次性的 API 调用升级为一套有纪律的协作协议宿主托管鉴权与路由工具固化参数语义与路径安全模型负责提示词工程与请求形态决策。三条最值得记住的实战准则形态分明全新视觉走ImageGen无图参修改/合成走ImageEditreferenced_image_paths仅限会话内用户提供的最多 3 张图提示词即简报完整覆盖主体、构图、光线、风格、文字与规避项编辑场景用编号角色 change only X; keep Y unchanged并每轮重述全部约束不越权、不臆造不注入 API Key、不添加工具参数中不存在的 Provider/模型字段、不虚构源图路径、失败不自动重试、结果路径不重复嵌入对话。如需继续深入可分别阅读 ImageGenTool.ts工具 schema 与行为定义、backend.ts三家提供方的请求构造与安全落盘、config.ts运行时配置与环境变量以及配套测试 imagegen.test.ts 与 backend.test.ts覆盖 prompt 拼接、凭据不泄露、参数映射等行为契约。赞分享人工智能AI 应用桌面应用代码智能体MCP Clients【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址https://gitcode.com/gh_mirrors/cl/cc-haha点击查看免费下载相关推荐Codex imagegen 技能提示词工程最佳实践结构、特异性与迭代驱动的图像生成指南Codex imagegen 技能提示词工程最佳实践结构、特异性与迭代驱动的图像生成指南 导读 本文以 Skills Catalog 中 imagegen 技人工智能AI 技能AI 插件Codex CLI imagegen 技能提示词工程手册openinterpreter 中图像生成与编辑的 Prompt 最佳实践Codex CLI imagegen 技能提示词工程手册openinterpreter 中图像生成与编辑的 Prompt 最佳实践 本文以 openinter人工智能大模型AI Agent代码智能体AI 应用CLIOpenInterpreter imagegen 工具实战image_gen.imagegen 图像生成与编辑的完整指南OpenInterpreter imagegen 工具实战image_gen.imagegen 图像生成与编辑的完整指南 本文基于 OpenInterpret人工智能大模型AI Agent代码智能体AI 应用CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
