dsh-packycode-api 1.1.9 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.2.1
+
+- **Generated image visible only inside tool details.** DSH 0.2 treats custom Turn/Step nodes as foldable process content, so the chat gallery disappeared when completed work was collapsed. PTC also logs successful child images as `tool/ptc-dispatch` without root presentation metadata, which the gallery previously ignored. The gallery now recognizes this plugin's successful native/PTC/CLI results and renders a Session-level card anchored beside its owning answer, independent of process folding. Stored conversations replay the same image references; no log rewrite or paid regeneration is needed. Duplicate results for the same call are projected once. Tool instructions also tell models to use automatic image presentation instead of inventing Markdown image links to host paths or attachment IDs.
+- Added regressions using DSH's real 0.1.5/0.2.0 conversation assemblers, the 0.2.0 chat grouping policy, native PTC ToolRuntime output and the built browser gallery/preview/viewer. The minimal reproduction showed a valid image in tool details with no main-chat card, plus an existing native gallery incorrectly classified as a collapsed process group; both now remain standalone visible image cards.
+- **Claude CLI image generation and editing.** CLI-backed Claude model turns and `claude_code` delegation can call a temporary MCP image tool backed by the existing host Images API service. Saved image model/quality, all three image engines, separate image credentials, original PNG storage and image-balance invalidation are shared with the native DSH tool. Only session-scoped image handles cross the input seam; neither keys nor arbitrary file/URL references are accepted. Generated images can be edited again within the same invocation.
+- The CLI's exact per-run image tool is allowed alongside search without widening shell permissions or changing user MCP configuration. Plan mode and titles expose no image tool. Requests are cancellable, bounded to five minutes and four attempts per invocation, with one active image request. Native MCP previews stay below 1 MiB and never duplicate base64 in textual results or DSH events.
+- Successful images are emitted as real assistant image blocks (or delegation tool image results), persisted by DSH, and projected into the chat gallery on replay. A later CLI failure preserves completed images and reports the failure instead of silently repeating paid work. The Create image button remains visible for Claude conversations.
+- Added service, transport, credential-isolation, composition, message assembly and replay regressions, plus `scripts/cli-image-check.mjs`. Its default checks run the real official CLI with local model/image fixtures across read-only/edit/full/plan/title modes; `--live` makes one real low-quality generation and one reference edit with the stored image key while Claude replies remain local fixtures.
+- Delegation output now declares the runner's token accounting fields, so DSH's actual output validator accepts both text and image results. PTC image forwarding uses the host's existing mechanism once, avoiding duplicate image contexts.
+- Validation, 2026-10-15: 377 offline tests, both bundles and the 1.2.1 tarball, including the built browser gallery and real DSH 0.1.5/0.2.0 replay/grouping regressions. Official CLI 2.1.295 passed image MCP fixtures in all five modes and existing search checks. A real `claude-haiku-5-5` upstream turn generated a blue teapot using Sunburst `low`, edited the generated reference to orange, and persisted both 1024×1024 images through DSH's message assembler in 33.078s; visual review confirmed preserved composition/background. A separate real-image/local-Claude check passed in 24.887s. Native and PTC ToolRuntime output validation/replay passed. The general gateway check passed five HTTP models; Astra first hit the script's 90-second deadline, then its focused repeat passed. No running desktop conversation was created or restarted for this verification; a physical Intel Mac retest is still needed.
+
+## 1.2.0
+
+- **New-image argument compatibility.** A desktop model repeatedly sent `referenceImages: []` with an unused, zero-valued mask reference for a new image. Treating field presence as an edit produced `PackyCode image edits require 1-16 reference images` before reaching the gateway. Empty arrays now mean no references, and only an entirely zero-valued empty/all-zero-ID mask placeholder is treated as absent. Nonempty reference/mask errors still fail; explicit `operation: edit` always requires references and explicit generation rejects real references. `model` and `quality` also accept `settings` to follow saved preferences rather than filling arbitrary defaults. Added tool-execution regressions from the actual desktop argument shape; a replay through the built tool with a public test prompt, a real image key and a local attachment adapter made exactly one generation request and returned a PNG in 12.267s.
+- **Image key balances.** The image settings card now shows per-key remaining/used quota, known limits, reset periods, usage bars and separate totals. It refreshes every minute and on demand, retaining and dating the last good reading when a refresh fails. New `images/balance` RPC uses only the dedicated image ring and skips account-wide billing. Image key/host changes and successful image generation invalidate its independent cache; conversation totals remain separate. Unknown limits display as unknown rather than zero. Shared quota UI keeps both cards consistent, and balance projections redact any credential echoed in upstream names or transport errors. A live read with the saved image key returned its quota from `/api/usage/token/`; a second read reused the cache without another request.
+- Added separate Images API support for `gpt-image-2`, `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`: JSON generation at `/v1/images/generations`, multipart edits at `/v1/images/edits`, reference images and optional PNG masks. The models stay outside the conversation picker and use the configured PackyCode API host.
+- **Dedicated image credentials.** Settings → PackyCode → Image generation and editing owns its own `packycode-api/image-keys` record, enable switch, model and quality selection. Conversation keys, environment credentials and subscription tokens are never image fallbacks. Adding/removing image keys and changing settings reconciles the tool without restarting the conversation route. The composer shortcut explicitly names `packycode_image_generate` when other image plugins are installed.
+- Quality follows the [official Images API](https://developers.openai.com/api/docs/guides/image-generation): Image 2 accepts `auto/low/medium/high`; the 2.5 models additionally accept `xhigh/max`. Invalid model/quality combinations fail before a paid request. Requests ask for one PNG and omit legacy `response_format` and `input_fidelity`; there is no automatic model/quality fallback or resend.
+- Requests refuse redirects and are bounded by cancellation, a five-minute deadline and response/input size limits. Edits resolve only references in the executing session; invalid edits never become new-image requests. Original PNGs are saved privately under `~/.dsh/packycode-api/images/`, alongside DSH-owned chat previews. Gateway errors never echo response bodies, credentials or transport causes.
+- Added offline wire/registration/credential tests, an [API research note](docs/research/image-api.md), and opt-in `scripts/image-check.mjs` (`--all --edit` checks all engines and one edit; `--model … --quality … --edit` checks a specific engine/quality pair on both endpoints). Logs now record reported model/quality and editing duration as well as generation duration, without raw upstream bodies.
+- **Live validation, 2026-10-15:** using only a stored `packycode-api/image-keys` credential, all three models passed generation and multipart editing at `low`; Sunburst additionally passed generation and editing at `xhigh` and `max`. All 10 requests returned valid 1024×1024 PNGs without retries, model substitution or quality downgrade. Visual review confirmed blue-to-orange edits preserving composition/background. Sunburst echoed both high quality values: xhigh took 43.130s / 48.064s (generate/edit), max 83.537s / 91.358s. Logs were checked for the complete credential and were secret-free. The restarted desktop showed the new image settings/key; full desktop flow, transparency, mask or custom-size live checks are not claimed. Offline validation: 354 tests, both bundles and the versioned tarball, including the native new-image argument regression, dedicated image-balance RPC, credential isolation, caching, secret-free quota projections and built settings rendering.
+
 ## 1.1.9
 
 - Added `gemini-4-argon` (**Gemini 4 Argon**) and `gemini-3.8-flash` (**Gemini 3.8 Flash**), both using `google-generative-ai` at `https://cf.api.fan/v1beta`. PackyCode's [live catalog](https://www.packyapi.com/api/pricing) and its support reply declare only the native `gemini` endpoint for Argon; Flash supports it too, keeping the Gemini family on one native route. Requests use streaming `streamGenerateContent`, with `thinkingLevel: LOW / MEDIUM / HIGH`, text/image input and native tool/signature replay.

package/README.en.md

@@ -31,6 +31,7 @@ The `PackyCode` model group ships with the plugin. No YAML edits and no separate
 | **Visible balance** | Settings lists each key's remaining, used, limit, reset period, and a usage bar, plus a total of those keys. The composer shows the active key's remaining balance |
 | **Claude through the local CLI** | `claude-opus-5-5`, `claude-sonnet-5-5`, and `claude-haiku-5-5` run the official Claude Code CLI on this device. Settings can detect it and install it |
 | **Web search through PackyCode** | Optional: DSH's `web_search` searches through PackyCode, with a DeepSeek or GPT backend, for every request or for PackyCode models only |
+| **Image generation and editing** | Separate image keys, GPT Image 2 / 2.5 Flare / 2.5 Sunburst, model and quality settings, reference edits and original PNG storage; generation and editing verified against the gateway |
 | **Credentials stay on the machine** | Keys live in the DSH credential file. The browser receives labels, state, and balances only |
 
 <img width="774" height="455" alt="截屏2026-10-15 10 34 28" src="https://github.com/user-attachments/assets/c5eaa535-dd1e-4e2f-be9f-c181404d4dd6" />
@@ -50,7 +51,7 @@ Open the desktop application's **Plugins** page, click **Add plugin**, and enter
 dsh-packycode-api
 ```
 
-Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.1.9`.
+Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.2.1`.
 
 A **first install requires no DSH restart**: open **Settings → PackyCode** and add a key immediately. When updating an already loaded older version, follow the restart guidance in the **Plugin version** card.
 
@@ -69,7 +70,7 @@ Choose a model from the `PackyCode` group. `deepseek-flash`, `gpt-6.1-sol`, `gpt
 
 The **Plugins** page shows the installed state and version, and is also where you enable, disable, or uninstall.
 
-**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.1.9`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
+**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.2.1`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
 
 For a local checkout, keep the `link:` prefix: `dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`. **Do not pass a bare path or `file:`** — that install copies the whole checkout, `node_modules` included, into the profile, where it then shadows the packages the DSH installation itself provides and the plugin looks uninstalled; see the FAQ. If you already installed that way, uninstall first and reinstall as above.
 
@@ -139,6 +140,26 @@ Claude Code CLI → temporary local MCP web_search → selected PackyCode DeepSe
 
 </details>
 
+### Image generation and editing
+
+Add the dedicated key under **Settings → PackyCode → Image generation and editing → Add an image key**. This credential record is separate from conversation keys. Image calls use only the selected image key. Adding one does not start a paid test.
+
+The image card shows each image key's remaining/used quota, limits when supplied, reset period, usage bar and separate totals. It refreshes every minute or with **Refresh**, preserving a dated last-good reading when a refresh fails. Image key changes and successful generation invalidate the independent balance cache. Only image key quotas are queried; account-wide billing and conversation key totals are kept separate.
+
+Choose the image model and quality, then click **Create image** in a PackyCode conversation or explicitly request `packycode_image_generate`. Attach references and describe changes to use `/v1/images/edits`; new images use `/v1/images/generations`. The image model is independent of the conversation model and other image plugins can coexist.
+
+All three CLI-backed Claude models and the `claude_code` delegation tool also support generation and editing through a temporary MCP image tool: `Claude Code CLI → local MCP → host image service → PackyCode Images API`. It shares the image preferences, dedicated image key and balance cache; the image key never reaches the CLI. References use host-scoped session handles (`referenceIds` / optional `maskId`), including images generated earlier in the same run. Successful images are persisted in DSH messages for chat replay, with original PNG files saved separately. Each run allows at most four image attempts, one at a time; cancellation aborts image work. Plan mode and session titles do not expose the paid image tool. **Create image** remains available in Claude conversations.
+
+**Image visible in tool details but unavailable in the final answer:** a standalone main-chat gallery remains visible when reasoning/tool details are collapsed, including PTC child calls. Reopening an existing conversation restores the gallery from its saved attachments without regenerating or spending image quota. An old invalid Markdown image link to a host path does not affect this gallery.
+
+Tool callers can set `model` and `quality` to `settings` to follow the saved preferences; `auto` is an explicit API quality. New images may omit `referenceImages` or pass an empty array. Explicit `operation: edit` requires valid references, and invalid real references are never discarded in favor of new-image generation.
+
+Image 2 accepts `auto / low / medium / high`; both 2.5 models also accept `xhigh / max`. These are Images API `quality` values, separate from text reasoning effort. There is no automatic model substitution, quality downgrade or paid retry. Each call returns one PNG; original bytes are saved under `~/.dsh/packycode-api/images/` (following `DSH_HOME` when set), alongside the chat preview. References and optional PNG masks must belong to the current session; file paths cannot replace attachment references.
+
+After adding the image key, `node scripts/image-check.mjs --all --edit` checks all three engines and one edit. Use `--model <id> --edit` for generation and editing on a specific engine, adding `--quality xhigh` or `--quality max` to check a quality. This consumes image quota, saves outputs under `.artifacts/`, and prints only a masked key tail plus the gateway-reported model/quality.
+
+Live checks on 2026-10-15 passed generation and editing at `low` on all three engines. Sunburst also passed both operations at `xhigh` and `max`, with matching quality values in the responses. All 10 requests succeeded without retries and returned 1024×1024 PNGs; visual inspection confirmed the requested color edits with composition preserved. Generate/edit times were about 43/48 seconds at xhigh and 84/91 seconds at max. These are built-client gateway checks; no desktop conversation was created to verify the full chat flow in this run. See the [protocol research and gateway results](docs/research/image-api.md) for scope and evidence.
+
 ## Models and groups
 
 | Model | How it runs | Effort | Token group |
@@ -247,6 +268,8 @@ pnpm run check
 
 `node scripts/cli-search-check.mjs` runs the real CLI against a local test gateway and MCP bridge; Claude responses and search data are mocked by default, with no quota consumed. It checks all three permission modes, native-search exclusion and temporary-resource cleanup. `--live --backend deepseek` or `--live --backend gpt` sends the read-only mode's one search to the real backend (edit/full remain mocked). This does not verify actual Claude upstream turns or a running DSH integration.
 
+`node scripts/cli-image-check.mjs` checks the real official CLI generating an image, editing its result, and persisting both through DSH's message assembler. Default model/image responses are local fixtures, covering read-only/edit/full/plan/title modes and temporary-config cleanup. `--live` makes one real Sunburst low-quality generation and one edit using the stored image key, while Claude replies remain local fixtures. `--with-claude` additionally uses a real Claude upstream turn (Haiku by default), consuming conversation quota too. Outputs go under `.artifacts/`; neither option starts DSH or claims a running desktop conversation was tested.
+
 `node scripts/cli-plan-check.mjs` checks plan mode with the real CLI and a local fake gateway: stdio handoff, concurrent plan ownership, invocation-only file fallback, stale-plan exclusion, actual denial limits and cleanup. It reads no real credentials, spends no quota and starts no DSH instance.
 
 `node scripts/install-check.mjs` diagnoses an installed plugin that never appears: it reads one profile, lists any host package shadowed by a leftover `node_modules` inside an installed package (with versions) plus the recovery steps, and exits 1 when it finds one. `--profile <name>`, `--home <dir>`, and `--json` are available.

package/README.md

@@ -31,6 +31,7 @@
 | **余额一眼可见** | 设置页列出每个 Key 的剩余、已用、额度、重置周期和用量条，并给出这些 Key 的合计；输入框右侧显示当前 Key 的剩余额度 |
 | **Claude 走本机 CLI** | `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5` 由本机官方 Claude Code CLI 执行；设置页可以检测并一键安装 |
 | **网页搜索可走 PackyCode** | 可选：DSH 的 `web_search` 改用 PackyCode 搜索，后端在 DeepSeek 与 GPT 之间切换；可只对 PackyCode 模型生效 |
+| **图片生成与编辑** | 独立图片 Key，支持 GPT Image 2 / 2.5 Flare / 2.5 Sunburst、型号与质量设置、参考图编辑和 PNG 原图保存；已通过网关生图与编辑实测 |
 | **凭据不离开本机** | Key 只存在 DSH 凭据文件里。浏览器只能看到备注、状态和余额，拿不到 Key |
 
 <img width="774" height="455" alt="截屏2026-10-15 10 34 28" src="https://github.com/user-attachments/assets/060c4192-00ea-40e6-9b85-bbec605b5c31" />
@@ -50,7 +51,7 @@
 dsh-packycode-api
 ```
 
-在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.1.9`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.1`。
 
 首次安装后**无需重启 DSH**，可直接打开**设置 → PackyCode** 添加 Key。更新已加载的旧版时，按「插件版本」卡片的重启提示操作。
 
@@ -69,7 +70,7 @@ dsh-packycode-api
 
 桌面应用的**插件**页可以看到已安装状态与版本，也可以在那里启用、停用或卸载。
 
-**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.1.9`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
+**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.2.1`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
 
 本地开发要加 `link:` 前缀：`dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`。**不要直接写路径（或 `file:`）** —— 那样的安装会把整个仓库目录（连同 `node_modules`）复制进 profile，之后它会在 profile 内部挡住 DSH 自带的包，插件看起来像没装，见「常见问题」。已经那样装过的话，先卸载再按上面的方式重装。
 
@@ -139,6 +140,26 @@ Claude Code CLI → 本机临时 MCP web_search → 插件选定的 DeepSeek/GPT
 
 </details>
 
+### 图片生成与编辑
+
+在 **设置 → PackyCode → 图片生成与编辑 → 添加图片 Key** 填入专用 Key。它与「账户与 Key」里的对话 Key 分开保存；图片请求只用此处选择的 Key。添加 Key 不会自动发起付费测试。
+
+图片卡片会显示每个图片 Key 的剩余、已用、限额（接口有提供时）、重置周期和使用进度，并单独汇总图片额度。余额每分钟更新，也可点卡片右上角的「刷新」；读取失败时保留上次余额并标出时间。图片 Key 变更或生图成功后会清理图片余额缓存。仅查询专用图片 Key 的额度，不叠加账户级账单，也不混入对话 Key 的合计。
+
+选择请求型号与质量后，可在 PackyCode 对话里点 **创建图片** 补充描述，或明确要求使用 `packycode_image_generate`。上传参考图后描述修改要求会调用 `/v1/images/edits`；新图调用 `/v1/images/generations`。图片型号独立于对话型号，其他插件的图片工具仍可并存。
+
+三个 Claude 模型走本机官方 CLI 时，以及 `claude_code` 委派时，均可通过临时 MCP 图片工具生图和编辑：`Claude Code CLI → 本机 MCP → 插件图片服务 → PackyCode Images API`。它复用同一份图片设置、独立图片 Key 和余额缓存；图片 Key 不会交给 CLI。CLI 只使用宿主提供的本会话图片句柄（`referenceIds` / 可选 `maskId`），可以继续编辑本轮刚生成的图片。成功结果作为图片保存进 DSH 会话，聊天重放也能展示，PNG 原图另存本机。每轮最多四次图片尝试、同一时间一张；请求取消时一并停止图片请求。计划模式和标题生成不开放生图工具。创建图片按钮在 Claude 对话中保留。
+
+**详情里有图、主聊天却显示「图片无法预览」：** 图片结果会在主聊天单独展示，收起思维链或工具详情时仍可见，包括 PTC 嵌套调用。修复版重新打开历史对话也会用已保存的附件补出图片卡片，无需再次生图；模型回复里遗留的无效本机路径图片链接不影响这张卡片。
+
+工具调用可将 `model` 和 `quality` 设为 `settings` 来跟随已保存的图片设置；`auto` 是一个明确的 API 质量档位。新图可省略 `referenceImages` 或传空数组；显式指定 `operation: edit` 时必须提供有效参考图，错误的真实参考图不会被丢弃后改生成新图。
+
+`gpt-image-2` 的质量为 `auto / low / medium / high`；两款 2.5 另支持 `xhigh / max`。质量按 Images API 的 `quality` 原样发送，不作为文字推理强度；不会自动换型号、降档或重试付费请求。输出先采用 PNG，每次一张，聊天预览之外的原图保存在 `~/.dsh/packycode-api/images/`（设置了 `DSH_HOME` 时跟随该目录）。参考图与可选 PNG mask 必须来自当前会话；不能用路径替代附件引用。
+
+用户填入图片 Key 后，可运行 `node scripts/image-check.mjs --all --edit` 验证三个型号与一次编辑；用 `--model <型号> --edit` 单独验证某个型号的生图和编辑，搭配 `--quality xhigh` 或 `--quality max` 验证质量。测试会消耗图片额度，输出写入 `.artifacts/`，日志只显示 Key 的掩码尾号，并记录网关回报的型号/质量。
+
+2026-10-15 实测：三个型号均通过 `low` 生图与编辑；Sunburst 额外通过 `xhigh`、`max` 生图与编辑，两档响应的 quality 均与请求一致。合计 10 次成功请求，无重试，全部返回 1024×1024 PNG；编辑正确改色并保留构图。xhigh 生成/编辑约 43/48 秒，max 约 84/91 秒。这是已构建图片 client 的网关验证；本轮未新建 DSH 对话验证完整聊天流程。完整范围和记录见[协议核查与网关实测](docs/research/image-api.md)。
+
 ## 模型与分组
 
 | 模型 | 怎么调用 | 推理档位 | 适合的令牌分组 |
@@ -247,6 +268,8 @@ pnpm run check
 
 Claude CLI 的 MCP 接口验证用 `node scripts/cli-search-check.mjs`：运行真实 CLI，普通 Claude 响应和搜索数据默认由本地测试服务模拟，不消费额度；会检查三种权限模式、原生搜索禁用和临时资源清理。加 `--live --backend deepseek` 或 `--live --backend gpt` 会让只读模式的那一次搜索走真实后端（其它两种模式仍模拟）。这不等于验证了真实 Claude 上游对话或运行中的 DSH 集成。
 
+图片 MCP 验证用 `node scripts/cli-image-check.mjs`：真实官方 CLI 依次生图、用生成结果编辑，并经 DSH 消息组装器验证持久化图片；默认 Claude 和图片网关响应均在本地模拟，同时检查只读/编辑/完全权限、计划模式、标题和临时配置清理。加 `--live` 会用已保存的独立图片 Key 向真实图片网关发出一次 Sunburst `low` 生图与一次编辑，结果写入 `.artifacts/`；Claude 回复仍由本地模拟网关提供。加 `--with-claude` 则连 Claude 也走真实网关，默认 Haiku，另消费对话额度；两者都不启动或重启 DSH，也不等于验证了运行中桌面会话。
+
 计划模式另用 `node scripts/cli-plan-check.mjs` 验证：真实 CLI 对接本地模拟网关，检查 stdio 计划提交、并发计划归属、本轮文件回退、旧计划隔离、实际拒绝次数上限和清理；不读取真实凭据、不消费额度、不启动 DSH。
 
 排查「装了却看不到插件」用 `node scripts/install-check.mjs`：它只读当前 profile，列出被包内残留 `node_modules` 挡住的宿主包（含版本）和对应的修复步骤，发现问题时以退出码 1 结束；`--profile <name>`、`--home <dir>` 可指定其它 profile，`--json` 输出结构化结果。

package/docs/research/image-api.md

@@ -0,0 +1,75 @@
+# GPT Image 2 / 2.5 Images API 核查
+
+核查日期：2026-10-15（Asia/Shanghai）。协议核查部分只查阅公开资料；末尾另记录用户添加独立图片 Key 并授权测试后的 PackyCode 网关结果。协议能力与实际网关结果分开记录，不记录任何完整凭据。
+
+## 模型与质量
+
+三个模型都可直接用于 `POST /v1/images/generations` 与 `POST /v1/images/edits`，不应送进文字模型的 Chat Completions 路由。生成请求为 JSON；编辑可以上传 multipart 图片，也可以发送 JSON 图片引用。[官方 OpenAPI：两个路径及请求 schema](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+| 模型 ID | `quality` | 默认值 |
+| --- | --- | --- |
+| `gpt-image-2` | `auto`、`low`、`medium`、`high` | `auto` |
+| `gpt-image-2.5-flare` | `auto`、`low`、`medium`、`high`、`xhigh`、`max` | `auto` |
+| `gpt-image-2.5-sunburst` | `auto`、`low`、`medium`、`high`、`xhigh`、`max` | `auto` |
+
+这张表同时适用于生成与编辑；`xhigh` / `max` 不能发给 `gpt-image-2`。质量是 Images API 的 `quality` 字段，不是文字模型的 `reasoning_effort`。[官方质量说明与 GPT Image 2 兼容章节](https://developers.openai.com/api/docs/guides/image-generation#customize-image-output)、[Sunburst 模型页](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)、[OpenAPI：CreateImageRequest / CreateImageEditRequest](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+## 尺寸和输出
+
+三个模型支持 `size: "auto"` 或 `WIDTHxHEIGHT`。推荐预设为 `1024x1024`、`1536x1024`、`1024x1536`；自定义值的两边须为 16 的倍数、每边不超过 3840、宽高比在 1:3 至 3:1 之间、总像素在 655,360 至 8,294,400 之间。高于 `2560x1440` 的分辨率为实验能力；4K 同时包括横向 `3840x2160` 和纵向 `2160x3840`。[官方尺寸说明](https://developers.openai.com/api/docs/guides/image-generation#customize-image-output)、[GPT Image 2 尺寸章节](https://developers.openai.com/api/docs/guides/image-generation#earlier-gpt-image-models)
+
+- `output_format` 支持 `png`（默认）、`jpeg`、`webp`；`output_compression` 为 0–100，仅用于 JPEG/WebP，PNG 请求应省略。[官方输出格式说明](https://developers.openai.com/api/docs/guides/image-generation#output-format)
+- `background` 支持 `auto`（默认）、`opaque`、`transparent`；透明输出必须使用 PNG/WebP。2.5 两款明确支持透明背景，`gpt-image-2` 的透明能力仍标为 preview。[官方 OpenAPI：background](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+- `n` 支持 1–10，默认 1；本插件可选择一次只生成一张以限制成本。[官方 OpenAPI：CreateImageRequest / CreateImageEditRequest](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+- GPT Image 非流式结果以 `data[].b64_json` 返回；`output_format` 决定解码后的图片类型。不要发送 legacy `response_format`，它不受 GPT Image 支持；官方也不为这些模型返回 `data[].url` 或 `revised_prompt`。[官方 OpenAPI：Image / ImagesResponse / response_format](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+- 两端点可返回 SSE；事件分别为 `image_generation.partial_image` / `image_generation.completed` 与 `image_edit.partial_image` / `image_edit.completed`。`partial_images` 范围 0–3，预览数量未必达到请求值；预览另计用量，首次实现可先采用非流式 JSON。[官方流式说明](https://developers.openai.com/api/docs/guides/image-generation#streaming)、[官方 OpenAPI：端点响应示例](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+## 编辑输入与 mask
+
+Multipart 使用 `image`（单图）或重复的 `image[]`（多图），最多 16 张；每张必须为 PNG、WebP 或 JPG，大小小于 50 MB。发送 `model`、`prompt` 和选定的质量等表单字段；让 HTTP 客户端为 FormData 自动设置带 boundary 的 Content-Type。[官方 multipart 示例](https://developers.openai.com/api/docs/guides/image-generation#edit-images)、[官方 OpenAPI：CreateImageEditRequest.image](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+`mask` 是可选 PNG，透明区域（alpha=0）指示要编辑的位置，尺寸须与第一张输入图一致；多图输入时只作用于第一张。模型把 mask 作为引导，不能保证修改区域与轮廓完全吻合。[官方 mask 说明](https://developers.openai.com/api/docs/guides/image-generation#edit-an-image-using-a-mask)、[官方 OpenAPI：CreateImageEditRequest.mask](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+官方资料存在一个明确差异：`CreateImageEditRequest.mask` 要求 **小于 4 MB**；指南的 Mask requirements 则写图与 mask 格式、尺寸一致且小于 50 MB。实现建议采用更严格的 PNG mask <4 MB，并在需要 mask 时使用相同尺寸的 PNG 输入，直到实际网关验证更宽限制；不要把指南的 50 MB 直接当作 mask 已确认上限。[OpenAPI mask schema](https://github.com/openai/openai-openapi/blob/main/openapi.json)、[指南 Mask requirements](https://developers.openai.com/api/docs/guides/image-generation#mask-requirements)
+
+JSON 编辑的字段为 `images: [{ image_url: "…" }]` 或 `images: [{ file_id: "…" }]`，每项二选一；`image_url` 可为完整 URL 或 data URL。JSON 的可选 mask 同样为图片引用对象。这是官方额外能力，不能据此假定 PackyCode 也支持它。[官方 OpenAPI：EditImageBodyJsonParam / ImageRefParam](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+`gpt-image-2` 必须省略 `input_fidelity`，其图片输入始终按高保真处理。当前通用 schema 只明确为 GPT Image 1 / 1.5 声明可调 high/low，没有明确说明 2.5 两款可调；本次集成建议三款均省略此字段，不推断 2.5 的未记载行为。[官方高保真说明](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity)、[官方 OpenAPI：InputFidelity](https://github.com/openai/openai-openapi/blob/main/openapi.json)
+
+## 本插件实现与后续实测建议
+
+以下是基于上面协议的工程建议，不是已通过的 PackyCode 运行结论：
+
+1. 将图片模型、图片 Key 和设置独立保存；只使用用户在本插件图片入口添加的 Key；请求、解码和错误处理均在宿主侧执行。
+2. UI 的质量菜单随模型变化；以 `auto` 为默认，切换到 `gpt-image-2` 时拒绝或显式清除不支持的 `xhigh` / `max`，不能暗中换模型。
+3. 先对接 JSON 生成和 multipart 编辑，发送 `quality` / `size` / `output_format` 等白名单字段；省略 `input_fidelity`、`response_format` 和旧 `style`。
+4. 用户填入独立图片 Key 后，逐模型生成一张低质量标准尺寸图片，再验证一次编辑；单独验证 2.5 高档质量、透明背景与 mask，记录实际接受的参数，不把构建成功当作网关成功。
+5. 对图片响应设大小、超时和取消边界；不在日志记录 Key、原始 Authorization 或可能回显凭据的响应体。错误按 HTTP 状态与稳定错误码分类，用户需修改输入的图片错误不自动重试。[官方图片错误处理说明](https://developers.openai.com/api/docs/guides/image-generation#handling-blocked-requests-and-other-errors)
+
+## PackyCode 网关实测（2026-10-15）
+
+用户自行重开 DSH 并在本插件中保存专用图片 Key 后，使用 `lib/index.js` 中已构建的图片 client 调用 `https://cf.api.fan`。凭据只从 `packycode-api/image-keys` 读取；没有写入或切换实际凭据、对话 Key、DSH 设置或会话。DSH 桌面设置页可见图片开关、Sunburst、max 和独立 Key，旧版 Host 缓存问题已解除。
+
+测试生成提示为白底居中的蓝色茶壶；编辑以该次生成的 PNG 为输入，只将茶壶改为橙色、保留构图和白底。每次输出请求 `1024x1024`、PNG、`n: 1`。生图使用 JSON generations；编辑使用 multipart edits；不自动换模型、降档或重试。
+
+| 请求型号 | 请求 quality | 生图 | 编辑 | 响应回报 quality |
+| --- | --- | --- | --- | --- |
+| `gpt-image-2` | `low` | 通过 | 通过 | 首组日志未记录此字段 |
+| `gpt-image-2.5-flare` | `low` | 通过 | 通过 | 首组日志未记录此字段 |
+| `gpt-image-2.5-sunburst` | `low` | 通过 | 通过 | 两次均为 `low` |
+| `gpt-image-2.5-sunburst` | `xhigh` | 通过 | 通过 | 两次均为 `xhigh` |
+| `gpt-image-2.5-sunburst` | `max` | 通过 | 通过 | 两次均为 `max` |
+
+共 10 次真实请求（5 次生图、5 次编辑），无失败、无重试，全部返回可解码的 1024×1024 PNG。10 张图片经视觉检查，生图为蓝色茶壶，编辑变为橙色，白底与构图保留；输出 SHA-256 也均不同。日志经宿主侧检查不含完整图片 Key。
+
+`xhigh` 生图用时 43.130 秒、编辑 48.064 秒；`max` 生图 83.537 秒、编辑 91.358 秒。两种高档质量的生成、编辑响应分别明确回报 `quality: "xhigh"` / `quality: "max"`。PNG 文件大小不用于推断质量档位。Sunburst 响应未提供可识别的 `model` 字段，结论是这些请求型号在当前 Key / 网关下可用，以及已回报的 quality 与请求一致，不据此独立证明网关内部的模型身份。
+
+本次是已构建插件图片 client 的真实网关测试；桌面确认了设置和 Key 加载，没有新建 DSH 对话来运行完整的模型 → 工具 → 聊天预览流程。透明背景、mask、自定义大尺寸及其它质量档位不在本轮范围内。测试日志与 PNG 保存在本地 `.artifacts/image-live-*.log` 和 `.artifacts/image-check-*/`；汇总记录（参数、耗时、质量回报、文件路径、SHA-256）为 `.artifacts/image-live-results-2026-10-15.json`。这些文件不进入 Git 或 npm 包。
+
+## 原生工具参数回放与兼容修复（2026-10-15）
+
+后续桌面对话暴露了 client 级验证未覆盖的参数问题：模型给新图请求填入 `referenceImages: []`，同时附带一个 `attachmentId` 全零、字节数与宽高均为 0 的占位 mask。工具按字段是否存在判断操作，反复报 `PackyCode image edits require 1-16 reference images`，请求尚未到网关。本地开发链接确实指向当前仓库；该错误在最新源码中同样可复现。
+
+回归测试先复现同样错误，再验证修复：空引用数组表示没有参考图；只把明确的零值、空 ID / 全零 ID 遮罩占位视为未提供。`operation: edit` 仍要求有效参考图，`operation: generate` 拒绝非空参考图，真实无效附件和真实遮罩不能变成新图请求。工具专用的 `model: settings` / `quality: settings` 可明确跟随已保存的设置，`settings` 不会发给网关。
+
+修复后，通过已构建的 `createPackyCodeImageTool().execute()` 回放原生参数结构（提示词替换为公共茶壶测试描述），只发出一次 `/v1/images/generations` 请求并成功返回 PNG，耗时 12.267 秒，`size: auto` 的实际图片为 1329×1183。结果可渲染成图片附件，日志和结果均不含完整 Key。该检查使用真实专用图片 Key、真实网关和本地附件测试适配器；它验证了工具参数路径，仍不等同于自动驱动整个桌面对话。记录在本地 `.artifacts/native-image-argument-replay-results.json`。