图片生成与编辑
翻译说明： 本页对应 英文源规格。代码、协议字段和标识符保持原文；如有歧义，以英文版本为准。
桌面通过 AppSettings.imageGeneration 保存当前默认生图绑定，并通过可选的 AppSettings.imageGenerationModels 保存已标记的生图模型列表。缺省候选列表时兼容旧数据，把单绑定视为唯一候选；providerId 和 modelId 仍是每个绑定的字段。host-core 使用现有设置存储校验并持久化，无需数据库版本升级。每个候选独立于默认对话模型，引用已启用的 API-key 或免认证服务商及其已配置模型。
配置
保存服务商时，无论是否勾选或取消生图标记，成功提示都确认“服务已保存” 或“服务已更新”，避免取消标记后仍声称“已设为生图模型”。 从生图摘要菜单选择默认模型时，仍显示生图选择成功提示。
模型高级设置将“设为生图模型”与图片、文档附件能力放在同一能力组中，不再单独占一行；复选框支持多选，保存服务商表单后把所有勾选模型写入 imageGenerationModels，取消不会改变设置。保存候选不会替换默认对话模型。若当前默认生图模型所属服务商的生图勾选被全部取消，则清空该默认，即使其他服务商仍有可运行候选；模型页取消勾选，且不会自动改选其他候选。同一服务商仍保留其他生图勾选时，默认改到第一个可运行的已标记候选。取消标记的模型恢复为可选对话模型，重新打开设置后仍保持这一状态。保存其他服务商时保留仍可用的默认生图模型。默认模型下方同一面板中的“生图模型”显示当前默认，并提供菜单从所有已标记候选中选择一个。没有候选，或没有任何可选项时，隐藏摘要行。仍有其他可选候选时，已存在但服务商停用、缺少凭据或模型移除的当前默认仅显示“暂不可用”。OAuth 账户不适用，也不会自动回退。 所有已标记的服务商／模型组合都会从默认对话模型选择器、服务商快速设为默认操作和 Composer 模型菜单中排除。其他服务商的同名模型独立保留。已有会话绑定和历史不改写；仍绑定任一生图候选的会话必须选择对话模型才能发送，运行时也会在推理前拒绝所有已标记生图模型。
移除服务商模型
在服务商编辑器中主动移除已配置模型并保存时，即使没有操作生图能力复选框， 也会清除该模型的生图候选。如果它是当前默认生图模型，则清空默认值，即使其他服务商仍有可用候选。取消编辑保留模型列表和生图设置。 旧版单绑定配置遵循相同规则。生图选择未改变时保留原有服务商保存流程。 服务商的外部变化仍可能留下显示为“暂不可用”的绑定。 若当前聊天默认模型也被移除，仍按原有规则选择服务商的第一个剩余模型； 否则保留聊天默认值。
Agent 合约
GenerateImages({items: [{prompt, count?, images?}]}) 仅供 Agent 模式使用。count 默认为 1，支持不同提示词和同一提示词的多个变体，总输出为 1–10 张。每项可通过 images 提供 1–4 张本地参考图，之前生成的路径可用于迭代编辑。提示词最多 32,000 个字符；不支持或超限输入直接拒绝，不截断。Plan 和 Goal 不得执行此工具。
内置 pi-desktop/imagegen skill 可在普通会话中发现，并通过现有 Skill 工具加载。它说明提示词、批量、参考图编辑、保留原图、部分失败处理和项目素材交付，不授予权限，也不携带凭据。
可信桌面桥先使用相同身份、参数和权限范围调用 host-core tools.execute。host-core 应用现有高风险工具策略，仅返回授权结果；获得批准后桥才执行图片服务。宿主授权审计与 sidecar 的实际工具结果分开记录。取消会传递给待批准操作和网络请求；宿主断开或 sidecar 销毁时中止本地工作。
OpenAI Images 适配器
仅支持 OpenAI-compatible Images。根地址自动补充 /v1，显式路径前缀保留。生成通过 POST images/generations 发送 model、prompt 和 n: 1；编辑通过 POST images/edits 发送 multipart 图片、提示词、模型和 n: 1。不包含浏览器蒙版编辑器。服务商可能只支持生成；编辑错误直接报告，不悄悄改为生成或切换模型。
对于精确匹配的 DALL-E 2/3 模型 ID，生成请求显式发送 response_format: b64_json，支持的 DALL-E 编辑请求使用同名表单字段。GPT Image 和未知兼容模型省略该参数。编辑使用二进制 multipart 上传，单图字段为 image，多图为 image[]，Content-Type boundary 由传输层生成。
每批请求在分发前快照模型绑定和服务商，使用两个工作线程，并按输入顺序返回结果。每张输出的请求预算为 180 秒。请求不会自动重试；认证失败停止队列工作。取消停止队列并中止活动 HTTP 请求，但不能保证上游停止处理或收费。已完成的输出文件保留。
每次响应接受一张 Base64 图片或 HTTPS 图片地址。JSON 和下载响应体有大小限制；图片最多 16 MiB，只接受 PNG、JPEG、WebP 文件签名。下载使用已校验并固定的公网 DNS 地址，拒绝重定向和私网目标，也不携带服务商请求头。只有在“设置 → 通用 → 网络”明确开启代理 fake-IP 支持后，基准测试段 fake-IP 才会使用应用的代理感知传输；真实私网、回环、链路本地和元数据地址仍会被阻止。
编辑输入必须在 realpath 校验后属于会话项目、该会话 scratch 目录或附件存储。每组参考图最多 32 MiB，每批输入缓存预算为 64 MiB。凭据不会进入渲染进程或工具结果。
结果与恢复
每项结果记录序号、状态（succeeded、failed、cancelled）、成功路径/MIME 类型或安全错误码。输出以唯一文件名保存至会话 scratch，编辑不覆盖原图。工具结果和对话只保留文件引用，不保存 Base64；预览复用现有受限图片读取和文件查看器。
本地工具抛出的稳定 errorCode 跨真实 sidecar RPC 边界保留，独立于普通结构化工具失败结果。现有 RPC code、message 和 data 保留，不序列化任意 Error 属性；sidecar 接收端同时提供错误码与 data。
部分成功时仍展示成功图片和逐项失败。未配置返回结构化错误及“设置 → 模型”跳转操作。会话重载或重启后同一引用仍可显示。图片结果和配置操作显示在可折叠过程详情之外，展开工具详情不会重复图片列表。
生成文件绝对路径（包括 Windows 盘符路径）的 Markdown 图片引用通过现有受限宿主图片读取接口解析。URL 清理仍启用，宿主继续拒绝允许的工作区、scratch 和附件根目录之外的文件。
验证：node scripts/e2e-image-generation.mjs 覆盖宿主、stdio、HTTP 和存储；node scripts/e2e-image-generation-ui.mjs 使用 API 边界夹具覆盖真实 React/Chromium 交互。单元及服务测试覆盖限制、取消、部分失败、认证、超时、不安全路径和受限下载。
node scripts/e2e-image-chat.mjs 在隔离桌面中使用本地模型/图片 HTTP 夹具，覆盖相邻默认设置、Composer 提交、批量结果、引用生成文件编辑、收起详情和配置跳转。真实接口验证通过 scripts/test-image-generation-live.mjs 显式启用，仅限一次生成和一次编辑，不属于默认测试命令。