dsh-packycode-api 1.1.8 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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.
+- A compatibility wrapper removes the unsupported `thinkingBudget` emitted for Argon by older pi-ai hosts and defaults both Gemini models to `MEDIUM` when no effort is supplied. The DSH profile continues to select `high` by default. Both models declare a 1,048,576-token context/input window and 65,536-token single-stream output limit, without automatic long-decode continuation. See the [Argon](https://ai.google.dev/gemini-api/docs/models/gemini-4-argon) and [Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) model pages.
+- Both models appear by default in the picker and settings coverage summary. Live checks include them; `--model MODEL [--with-vision]` also allows a bounded check of one model through the built host route. Credentials still come only from the plugin's stored key ring.
+- Flash tool continuations now resend once after one second when the gateway returns HTTP 400 `Corrupted thought signature` / `Invalid thought signature` before any stream event. Fixed-response experiments showed the same signed request being refused and later accepted; three fresh native roundtrips passed with at most one resend. The guard requires a current signed same-model call and matching result, preserves the model/key/signature/request, and does not retry after output, on unrelated failures, or for Argon. Cancellation stops the wait, and a second refusal remains unchanged for the host's normal failure/retry handling.
+- Added `scripts/gemini-tool-check.mjs`, which exercises the built route, DSH's message assembler and JSON-persisted replay state, checking HTTP resend counts and request-body equality without printing signatures or credentials.
+- Validation: 321 offline tests passed, both bundles rebuilt and the tarball generated. The built native Flash route passed three fresh `low` tool roundtrips and one `high` roundtrip; Argon passed its tool roundtrip, and Flash text/red/blue-image checks passed. These final live tool runs required no resend; the exact HTTP-400-then-success path is covered by a real SDK/host regression. A separate Flash Completions comparison passed three tool roundtrips. Both Gemini catalog models remain on the requested native protocol; the guard mitigates an intermittent gateway refusal and does not repair its server-side validator.
+
 ## 1.1.8
 
 - **Diagnosed an installation that mounts nothing, and made it reportable.** A profile that once had this plugin installed from a local path keeps a `node_modules` inside the installed package directory; a later registry install rewrites the package's files and leaves that tree in place. DSH resolves a plugin's imports from inside the profile first, so the plugin kept loading the old copies — `@deepseek-ai/schemastery` 3.18.2 has no `Schema.volatile()`, the module threw while it was imported, and the Loader created no fiber for the row. `@deepseek-ai/dsh-client-modules` skips a fiber-less entry, so the browser bundle was never composed and the only symptom was a settings page with no PackyCode section, no model route, no RPC channel, and a clean host log. The diagnosis was confirmed on the affected desktop profile: the composed entry `{"id":"packycode-api","name":"dsh-packycode-api"}` is present, the 67-row boot graph carries no bundle for it, `POST /packycode-api/status` is unregistered, and importing the installed package from a copy reproduces `TypeError: schema.volatile is not a function`.

package/README.en.md

@@ -31,8 +31,14 @@ 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" />
+<img width="575" height="522" alt="截屏2026-10-15 10 34 49" src="https://github.com/user-attachments/assets/3cf4d090-a4f9-49fe-9ab3-3aab21d6e909" />
+<img width="257" height="309" alt="截屏2026-10-15 10 37 21" src="https://github.com/user-attachments/assets/621cd800-17a2-42f6-8dfe-c1b4be09af61" />
+
+
 ## Install
 
 You need **DeepSeek Harness** and a **PackyCode (PackyAPI) API key**. For DSH setup, see the [official instructions](https://github.com/deepseek-ai/deepseek-harness#run).
@@ -45,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.8`.
+Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.2.0`.
 
 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.
 
@@ -57,14 +63,14 @@ Open **Settings → PackyCode**. Paste the API key under **Add a key**. A label
 
 ### 3. Select a model
 
-Choose a model from the `PackyCode` group. `deepseek-flash`, `gpt-6.1-sol`, `gpt-6-astra`, and `grok-4.7` use HTTP. The three Claude models also need the Claude Code CLI on this device; see below. Your key's groups must cover the selected model.
+Choose a model from the `PackyCode` group. `deepseek-flash`, `gpt-6.1-sol`, `gpt-6-astra`, `grok-4.7`, `gemini-4-argon`, and `gemini-3.8-flash` use HTTP. The three Claude models also need the Claude Code CLI on this device; see below. Your key's groups must cover the selected model.
 
 <details>
 <summary>Verify the install / other profiles / a local checkout</summary>
 
 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.8`. 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.0`. 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.
 
@@ -134,6 +140,22 @@ 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. CLI-backed Claude main turns currently bridge web search only; use an API conversation model supporting DSH tool calls for images.
+
+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 |
@@ -142,13 +164,19 @@ Claude Code CLI → temporary local MCP web_search → selected PackyCode DeepSe
 | `gpt-6.1-sol` | HTTP, Responses, images allowed | Cannot be off; `low` / `medium` / `high` / `xhigh` / `max` | `codex`, `codex-sale` |
 | `gpt-6-astra` | Same | Same | Same |
 | `grok-4.7` (Grok 4.7) | HTTP, Responses, text/image input; 500K context | Cannot be off; `low` / `medium` / `high` / `xhigh` | The Grok coverage read from the gateway in Settings |
+| `gemini-4-argon` (Gemini 4 Argon) | HTTP, native Gemini streaming, text/image input; 1,048,576 context, 65,536 output | Cannot be off; `low` / `medium` / `high` | `gemini-slb` |
+| `gemini-3.8-flash` (Gemini 3.8 Flash) | HTTP, native Gemini streaming, text/image input; 1,048,576 input, 65,536 output | Cannot be off; `low` / `medium` / `high` | `gemini-slb` |
 | `claude-opus-5-5` | Local Claude Code CLI | The picker offers the same levels; the CLI chooses the actual effort | A group the official CLI is allowed to use; see below |
 | `claude-sonnet-5-5` | Same | Same | Same |
 | `claude-haiku-5-5` | Same; session titles always use this model | Same | Same |
 
 A model in the list does not mean the current token group allows it. When changing groups, do not drop the group that serves the model you still want.
 
-All seven models in the current catalog declare text and image input. DeepSeek Flash follows the [official vision guide](https://api-docs.deepseek.com/guides/vision/); images are read through DSH's attachment service and sent with the Chat Completions request.
+All nine models in the current catalog declare text and image input. DeepSeek Flash follows the [official vision guide](https://api-docs.deepseek.com/guides/vision/); images are read through DSH's attachment service and sent with the Chat Completions request.
+
+Gemini capabilities and limits follow Google's model pages: [Gemini 4 Argon](https://ai.google.dev/gemini-api/docs/models/gemini-4-argon), [Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash). Both models use the native Gemini protocol through `/v1beta/models/{model}:streamGenerateContent`, streaming text, thinking and tool calls; images are read through DSH's attachment service. Thinking levels are sent with `thinkingLevel`. Both routes use the single-stream output limit without automatic continuation beyond 65,536 tokens. Available endpoints and groups follow the [PackyAPI live model catalog](https://www.packyapi.com/api/pricing).
+
+**Flash native tool continuation:** The gateway sometimes refuses an unchanged valid signature with `Corrupted thought signature` / `Invalid thought signature`. For a current signed tool continuation returning HTTP 400 before any stream event, the plugin waits one second and resends once with the same key, signature and request. A second failure is returned unchanged; the protocol and model stay the same. Text, images and tool continuation passed live checks. This mitigates intermittent gateway refusals, rather than repairing persistent upstream signature errors.
 
 Grok 4.7's context and reasoning levels follow the [official guide](https://docs.x.ai/developers/grok-4-7). There is no separate text-output limit; the plugin uses the context size as its numeric output ceiling, bounded by the remaining context per request.
 

package/README.md

@@ -31,9 +31,11 @@
 | **余额一眼可见** | 设置页列出每个 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="790" height="332" alt="截屏2026-10-13 10 08 27" src="https://github.com/user-attachments/assets/2faa7667-300c-4f12-bb94-aecc35c5cb7f" />
+<img width="774" height="455" alt="截屏2026-10-15 10 34 28" src="https://github.com/user-attachments/assets/060c4192-00ea-40e6-9b85-bbec605b5c31" />
+<img width="575" height="522" alt="截屏2026-10-15 10 34 49" src="https://github.com/user-attachments/assets/89cf89ca-fce3-427d-95cb-94fa2b05d6aa" />
 <img width="272" height="425" alt="截屏2026-10-13 10 07 46" src="https://github.com/user-attachments/assets/040fc57a-2dd2-4195-9bbc-5fa3357d1eb1" />
 
 
@@ -49,7 +51,7 @@
 dsh-packycode-api
 ```
 
-在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.1.8`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.2.0`。
 
 首次安装后**无需重启 DSH**，可直接打开**设置 → PackyCode** 添加 Key。更新已加载的旧版时，按「插件版本」卡片的重启提示操作。
 
@@ -61,14 +63,14 @@ dsh-packycode-api
 
 ### 3. 选择模型
 
-回到对话，在模型选择器里选 `PackyCode` 分组下的模型。`deepseek-flash`、`gpt-6.1-sol`、`gpt-6-astra` 和 `grok-4.7` 通过 HTTP 调用；三个 Claude 模型还需要本机装有 Claude Code CLI，见下文。Key 的分组必须覆盖所选模型。
+回到对话，在模型选择器里选 `PackyCode` 分组下的模型。`deepseek-flash`、`gpt-6.1-sol`、`gpt-6-astra`、`grok-4.7`、`gemini-4-argon` 和 `gemini-3.8-flash` 通过 HTTP 调用；三个 Claude 模型还需要本机装有 Claude Code CLI，见下文。Key 的分组必须覆盖所选模型。
 
 <details>
 <summary>检查安装 / 其它 profile / 本地目录</summary>
 
 桌面应用的**插件**页可以看到已安装状态与版本，也可以在那里启用、停用或卸载。
 
-**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.1.8`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
+**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.2.0`。不要对 `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 自带的包，插件看起来像没装，见「常见问题」。已经那样装过的话，先卸载再按上面的方式重装。
 
@@ -138,6 +140,22 @@ 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`。图片型号独立于对话型号，其他插件的图片工具仍可并存。CLI 执行的 Claude 主回合目前仅桥接网页搜索，生图请在支持 DSH 工具调用的 API 模型对话中使用。
+
+工具调用可将 `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)。
+
 ## 模型与分组
 
 | 模型 | 怎么调用 | 推理档位 | 适合的令牌分组 |
@@ -146,13 +164,19 @@ Claude Code CLI → 本机临时 MCP web_search → 插件选定的 DeepSeek/GPT
 | `gpt-6.1-sol` | HTTP，Responses，可带图 | 不能关；`low` / `medium` / `high` / `xhigh` / `max` | `codex`、`codex-sale` |
 | `gpt-6-astra` | 同上 | 同上 | 同上 |
 | `grok-4.7`（Grok 4.7） | HTTP，Responses，可带图；500k 上下文 | 不能关；`low` / `medium` / `high` / `xhigh` | 以设置页从网关读取的 Grok 分组覆盖为准 |
+| `gemini-4-argon`（Gemini 4 Argon） | HTTP，Gemini 原生流式，可带图；1,048,576 上下文，65,536 输出 | 不能关；`low` / `medium` / `high` | `gemini-slb` |
+| `gemini-3.8-flash`（Gemini 3.8 Flash） | HTTP，Gemini 原生流式，可带图；1,048,576 输入，65,536 输出 | 不能关；`low` / `medium` / `high` | `gemini-slb` |
 | `claude-opus-5-5` | 本机 Claude Code CLI | 选择器档位同上，实际档位由 CLI 决定 | 能给官方 CLI 用的分组，比如cc分组 |
 | `claude-sonnet-5-5` | 同上 | 同上 | 同上 |
 | `claude-haiku-5-5` | 同上；会话标题也固定走它 | 同上 | 同上 |
 
 列表里看得到模型，不代表当前令牌分组一定放行。换分组时不要把对应分组一起去掉。
 
-当前目录中的 7 个模型都声明了文字和图像输入。DeepSeek Flash 的识图能力按 [官方图像理解文档](https://api-docs.deepseek.com/zh-cn/guides/vision/) 配置；图片通过 DSH 附件服务读取，再随 chat/completions 请求发送。
+当前目录中的 9 个模型都声明了文字和图像输入。DeepSeek Flash 的识图能力按 [官方图像理解文档](https://api-docs.deepseek.com/zh-cn/guides/vision/) 配置；图片通过 DSH 附件服务读取，再随 chat/completions 请求发送。
+
+Gemini 的能力与限制来自 Google 官方模型页：[Gemini 4 Argon](https://ai.google.dev/gemini-api/docs/models/gemini-4-argon)、[Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash)。两款模型统一使用 Gemini 原生协议，通过 `/v1beta/models/{model}:streamGenerateContent` 流式返回文字、思考和工具调用，图片仍由 DSH 附件服务读取。思考档位通过 `thinkingLevel` 传入。两者均使用单次流式输出上限，不执行超过 65,536 token 的自动续写。可用端点与分组以 [PackyAPI 实时模型目录](https://www.packyapi.com/api/pricing) 为准。
+
+**Flash 原生工具续聊：** 网关偶尔会拒绝原样回传的有效签名，返回 `Corrupted thought signature` / `Invalid thought signature`。插件仅在当前工具续聊、HTTP 400 且尚未输出任何流事件时，等待 1 秒，用相同 Key、签名及请求原样重发一次；再次失败时仍返回原错误，不更换协议或模型。文字、图片和工具续聊均已实测；该处理缓解网关的间歇性拒绝，不能保证修复持续性的上游签名错误。
 
 Grok 4.7 的上下文与推理档位来自 [官方文档](https://docs.x.ai/developers/grok-4-7)。官方没有单独限制文字输出长度；插件将输出上限设为上下文大小，并按每次请求的剩余上下文收紧。
 

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`。