图片生成与编辑
翻译说明： 本页对应 英文源规格。代码、协议字段和标识符保持原文；如有歧义，以英文版本为准。
桌面通过 AppSettings.imageGeneration 保存当前默认生图绑定，并通过可选的 AppSettings.imageGenerationModels 保存已标记的生图模型列表。缺省候选列表时兼容旧数据，把单绑定视为唯一候选；providerId 和 modelId 仍是每个绑定的字段。host-core 使用现有设置存储校验并持久化，无需数据库版本升级。引用不再对应任何服务商行的绑定不会被持久化：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。凭据不会进入渲染进程或工具结果。
结果与恢复
成功结果显示在一张圆角图片卡片中。同一批次有多张成功图片时，主图旁显示缩略图列；选择缩略图会切换主图和对应下载目标，失败项仍单独显示。窄窗口中缩略图仍可操作。点击主图后打开全窗口预览，支持批次缩略图、方向键切换、缩放与适应窗口，也可返回现有文件面板。切换图片时不会在新选中状态下短暂显示上一张；已加载图片之间切换时，卡片和全窗口预览持续显示图片，不闪出空白占位。预览在下一张图片解码期间保持适配尺寸，快速连续操作以最后一次选择为准。选中缩略图使用浅灰色外框；关闭预览后，对话卡片保留选中的图片。卡片和预览都可从受限图片数据下载，文件名根据图片类型安全生成；预览中的“在文件夹中显示”通过受限 fs/reveal 接口执行。预览缺失或不可读时不提供下载，定位失败会提示错误；这些操作不会移动或覆盖 scratch 中的原图。
每项结果记录序号、状态（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 显式启用，仅限一次生成和一次编辑，不属于默认测试命令。
Pi 1.1.0 operation boundary
Image generation and edits execute through account-scoped Pi Models.generateImages. Use native OpenRouter images or a registered compatible OpenAI-images adapter, with JSON generations and multipart edits preserved. Each prompt is one physical operation; no automatic retry may duplicate a billable image request. Batch workers preserve output order, propagate cancellation/timeouts, and bound download sizes and URL safety. Returned text, response ID and operation usage survive the artifact projection. Multiple images from one response count as one operation.
The existing settings UI still excludes OAuth candidates. The internal adapter may accept OAuth only with an actual supported native image model and account auth resolver; it cannot fabricate entitlement or fall back to another account. Unknown pricing remains unknown. Images never route through the chat selector.
生图标记提示（#1789）
生图复选框旁提供说明：保存后模型从聊天和默认模型菜单移除，图片生成与图片输入 不同。折叠的模型行仍显示生图模型标记。未知自定义模型继续允许手动配置，提示只标记 端点确实支持生图的模型。