Deploy 76de60b to Docker Space

Source: MisonL/gpt-image-playground-customer@76de60b42bdc80653167d4bceed12f29c472ac6d

.env.agent.example

@@ -21,10 +21,11 @@ AGENT_REQUEST_LEASE_MS=600000
 AGENT_REQUEST_TTL_SECONDS=86400
 AGENT_RECOVERY_INTERVAL_MS=30000
 
-# 可选：供 OpenAPI 客户端使用的公开基础地址。
+# 可选：供 OpenAPI 客户端使用的公开基础地址。必须是不含凭据、查询参数和片段的 http/https 绝对 URL。
 # AGENT_PUBLIC_BASE_URL=http://localhost:4783
 
 # 现有应用配置仍然生效。
 OPENAI_API_KEY=
+# OpenAI 兼容接口根地址，通常以 /v1 结尾。支持不含凭据、查询参数和片段的 http/https 绝对 URL。
 OPENAI_API_BASE_URL=https://api.openai.com/v1
 APP_PASSWORD=

.env.example

@@ -5,6 +5,8 @@
 OPENAI_API_KEY=
 
 # 可选：OpenAI 兼容接口根地址，通常以 /v1 结尾。
+# 默认要求 https；本机 loopback HTTP 可直接用于本地 fixture。
+# 远程 HTTP 必须加入 OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS。
 # 示例：https://api.openai.com/v1
 OPENAI_API_BASE_URL=
 
@@ -21,6 +23,8 @@ OPENAI_API_BASE_URL=
 # - N 从 1 开始递增，例如 OPENAI_CHANNEL_1_*、OPENAI_CHANNEL_2_*。
 # - ID 只用于日志排查，不会暴露 API Key。
 # - BASE_URL 是 OpenAI 兼容接口根地址，通常以 /v1 结尾。
+# - BASE_URL 默认要求 https；本机 loopback HTTP 可直接用于本地 fixture。
+# - 远程 HTTP 必须加入 OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS。
 # - API_KEYS 支持一个或多个 key，多个 key 用英文逗号分隔。
 # - FAILURE_COOLDOWN_MS 可选，覆盖该渠道失败后的冷却时间。
 # - API Key 本身不要包含逗号。
@@ -34,14 +38,27 @@ OPENAI_API_BASE_URL=
 # OPENAI_CHANNEL_2_ID=backup
 # OPENAI_CHANNEL_2_BASE_URL=https://your-compatible-api.example.com/v1
 # OPENAI_CHANNEL_2_API_KEYS=sk-backup-1
+#
+# 可选：远程明文 HTTP 兼容接口 allowlist。默认只允许 HTTPS 和本机 loopback HTTP。
+# 多个完整 base URL 用英文逗号分隔，仅在确认网络边界安全时启用。
+# OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS=http://your-internal-compatible-api.example.com/v1
 
-# 可选：并发流式批处理。默认关闭。
-# 开启后，流式模式下 n>1 会拆成多个 n=1 的独立流式任务，并按服务端 key 容量并发执行。
+# 可选：并发流式批处理容量。
+# 页面提供显式“并发批量”开关；开启后，流式模式下 n>1 会拆成多个 n=1 的独立流式任务，并按服务端 key 容量并发执行。
 # 默认 sticky 路由按单个 credential 容量推荐并发；round_robin/random 才会使用完整 credential 池。
 # key 出现鉴权、额度或限流类错误后会短暂冷却；渠道出现 5xx、CDN 超时或连接错误后会冷却整个渠道。
-# ENABLE_STREAMING_BATCH=true
 # OPENAI_MAX_STREAMS_PER_CREDENTIAL=1
 # OPENAI_CHANNEL_FAILURE_COOLDOWN_MS=60000
+#
+# 可选：服务端渠道恢复探测。存在服务端凭证时默认开启，并要求冷却到期的
+# credential/channel 先通过后台 GET /models 探测，成功后才重新进入用户生图流量。
+# 探测不调用 /images/generations，不触发生图费用；MAX_PER_TICK 用于限制探测流量。
+# OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED=true
+# 如果设为 true，OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED 也必须启用。
+# OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY=true
+# OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS=60000
+# OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS=5000
+# OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK=1
 
 # 可选：多上游图片兼容层默认策略。默认保持 Images API JSON 基线。
 # IMAGE_GENERATION_BACKEND=images-api
@@ -64,7 +81,7 @@ OPENAI_API_BASE_URL=
 # IMAGE_REAL_SMOKE_SUB2API_API_KEY=
 # IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL=https://sub2api.example.com/v1
 # IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY=
-# IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://gpt2image.example.com/v1
+# IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://gpt2image.superapi.buzz/v1
 # IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=
 # IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4
 # IMAGE_REAL_SMOKE_TIMEOUT_MS=240000

.env.real-smoke.example

@@ -1,6 +1,7 @@
 # Independent real upstream smoke targets.
 # Copy this file to .env.real-smoke.local and fill only the targets you can run.
 # Do not commit .env.real-smoke.local.
+# Every *_BASE_URL must be a http/https absolute URL without credentials, query parameters, or fragments.
 # Final gate:
 # npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable
 
@@ -34,7 +35,7 @@ IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY=
 # IMAGE_REAL_SMOKE_SUB2API_RESPONSES_QUALITY=low
 
 # GPT2Image style Responses image_generation SSE.
-IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=
+IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://gpt2image.superapi.buzz/v1
 IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=
 # IMAGE_REAL_SMOKE_GPT2IMAGE_MODEL=gpt-image-2
 IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4

.github/workflows/hf-space-keepalive.yml

@@ -16,6 +16,8 @@ jobs:
       HF_SPACE_KEEPALIVE_URL: ${{ vars.HF_SPACE_KEEPALIVE_URL || 'https://misonl-gpt-image-playground-customer.hf.space' }}
       HF_SPACE_KEEPALIVE_PATH: /api/auth-status
       HF_SPACE_KEEPALIVE_TIMEOUT_MS: '30000'
+      HF_SPACE_KEEPALIVE_MAX_ATTEMPTS: '3'
+      HF_SPACE_KEEPALIVE_RETRY_DELAY_MS: '5000'
       HF_SPACE_KEEPALIVE_EXPECT_PASSWORD_REQUIRED: 'true'
     steps:
       - name: Checkout repository

CHANGELOG.md

@@ -8,27 +8,45 @@
 
 ### 新增
 
+- WebUI 增加 `图像手记` 工作台的显式批量模式：多条提示词逐行形成独立任务，批量进度、暂停、失败项复用和批次历史保持可追溯。
+- WebUI 在省心模式和专业模式中展示“并发批量”状态；只有用户手动启用且当前流式策略、任务数量和渠道容量满足条件时，才会把多图或多提示词拆成并发流式任务。
+- Agent skill 批量脚本支持 `--concurrency N` 并发执行、append-only manifest、续跑、尺寸校验、失败重试和页面 SSE 原始事件留档。
+
+### 变更
+
+- API URL 校验允许无凭据、无查询参数和无片段的 `http` 或 `https` OpenAI 兼容根地址；自定义 API URL 仍必须与自定义 API Key 成对提供，避免服务端密钥转发到未知地址。
+- WebUI 结果区和最近生成记录补齐连续工作流动作：继续编辑、做变体、复用提示词、对比、收藏和批次折叠，批量模式的底部提示词动作以当前可见批量提示词为准。
+
+## [1.4.0] - 2026-05-27
+
+### 新增
+
 - 增加 API 错误排查建议，针对鉴权失败、限流、上游 5xx 和 Cloudflare 524 返回更明确的用户提示。
 - 增加图片请求默认质量、错误建议和批量部分失败明细的单元测试。
 - 增加上游图片流事件适配层，兼容官方 OpenAI Images 流式事件和 OtokAPI `image.generation.*` 事件。
 - 增加 `/api/images` 流式路由契约测试，覆盖兼容上游 SSE 到前端稳定事件的映射、多图结果、缺图错误和上游断流。
 - 增加受 `ENABLE_RESPONSES_IMAGE_BACKEND` 保护的实验 Responses API 图片后端，显式请求 `imageBackend=responses` 且配置独立 Responses 顶层模型时读取 `image_generation_call.result`。
+- Agent capabilities 和 OpenAPI 增加机器可读 `routing_rules`、页面 SSE metadata、运行态启用后端和 job polling 语义，辅助脚本支持 `--page-sse`、`--agent`、`--job` 显式路由。
 
 ### 变更
 
 - 图片生成默认质量从 `auto` 调整为 `high`，前端、Agent API 默认值和 OpenAPI 描述保持一致。
-- 页面默认开启流式预览；单图流式失败会显式展示原始错误和建议，不再自动改用非流式请求。
+- 页面默认不发送流式请求；用户显式开启流式预览后，单图流式失败会显式展示原始错误和建议，不再自动改用非流式请求。
 - 抽取服务端流式图片响应处理，生成和编辑共用同一套 SSE 输出、图片保存、provider dialect 诊断和扣费解析逻辑。
 - 运行时能力接口增加实验 Responses API 图片后端开关状态，默认关闭且不影响现有 Images API 路径。
 - Agent API、图片接口、脚本和文档中的用户可见错误文案统一为中文。
 - Agent skill 文档改为先定位服务地址，再按 `/api/agent/*` 契约调用，避免默认假设服务只在 `localhost:4783`。
 
+### 修复
+
+- 收紧 Responses `image_generation` 结果解析，只有标准 base64 或常见位图 `data:image/...;base64,` payload 会被当作可保存图片。
+
 ## [1.3.0] - 2026-05-12
 
 ### 新增
 
 - 增加服务端运行时能力接口 `/api/runtime-capabilities`，用于返回流式批处理开关、推荐并发和渠道健康状态。
-- 增加 `ENABLE_STREAMING_BATCH` 与 `OPENAI_MAX_STREAMS_PER_CREDENTIAL`，支持在流式模式下把 `n>1` 拆成多个 `n=1` 任务并发执行。
+- 增加运行时并发流式批处理能力与 `OPENAI_MAX_STREAMS_PER_CREDENTIAL`，支持在流式模式下把 `n>1` 拆成多个 `n=1` 任务并发执行。
 - 增加前端流式批处理执行链路，支持并发调度、SSE 完成事件聚合、预览图索引映射、用量合并和部分失败提示。
 - 生成和编辑表单在服务端允许批处理时支持 `n>1` 开启流式预览，并补充中英文提示文案。
 - 增加服务端 credential/channel 失败冷却机制，支持按渠道覆盖冷却窗口。
@@ -93,7 +111,8 @@
 - 支持基于 OpenAI 兼容 Images API 的本地图片生成和编辑流程。
 - 增加 Docker 部署支持和多平台启动脚本。
 
-[未发布]: https://github.com/MisonL/gpt-image-playground-customer/compare/v1.3.0...HEAD
+[未发布]: https://github.com/MisonL/gpt-image-playground-customer/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/MisonL/gpt-image-playground-customer/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/MisonL/gpt-image-playground-customer/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/MisonL/gpt-image-playground-customer/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/MisonL/gpt-image-playground-customer/compare/dc7c8f5855e80cb9507517b5748c718e7155df52...v1.1.0

README.md

@@ -5,7 +5,7 @@ app_port: 4783
 
 # GPT Image Playground
 
-![Version](https://img.shields.io/badge/version-1.3.0-blue)
+![Version](https://img.shields.io/badge/version-1.4.0-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Node](https://img.shields.io/badge/node-%3E%3D20-339933)
 
@@ -51,8 +51,7 @@ OPENAI_CHANNEL_2_ID=backup
 OPENAI_CHANNEL_2_BASE_URL=https://your-compatible-api.example.com/v1
 OPENAI_CHANNEL_2_API_KEYS=sk-backup-a,sk-backup-b
 
-# 可选：开启并发流式批处理。默认关闭。
-ENABLE_STREAMING_BATCH=true
+# 可选：页面“并发批量”开关使用的服务端容量。
 OPENAI_MAX_STREAMS_PER_CREDENTIAL=1
 ```
 
@@ -125,11 +124,13 @@ http://localhost:4783
 - `gpt-image-2` 图片编辑：上传源图后用提示词修改图片，可选遮罩。
 - Agent API：为 Codex、Claude Code、Gemini 等 Agent 提供强契约接口、幂等重试、结构化错误和产物追踪。
 - 内置遮罩工具：直接在图片上绘制遮罩，也可以上传 PNG 遮罩。
+- `图像手记` 工作台：提供文生图、图生图、批量和复用历史四种入口，中央预览、右侧灵感相册和最近生成围绕连续创作流程组织。
 - 完整参数控制：模型、尺寸、质量、输出格式、压缩、背景、审核级别、生成数量。
 - 4K 与自定义尺寸：支持 2K/4K 预设和手动输入宽高，并在前端校验尺寸约束。
 - 流式输出：用户显式开启后支持生成和编辑过程中的局部图片预览。
+- 显式并发批量：用户手动启用后，多图或多提示词任务会按当前渠道容量拆成独立流式任务并发执行；未启用时，普通多图保持单次 `n>1` 请求，批量提示词保持逐条顺序执行。
 - 历史记录：保留提示词、参数、图片、耗时、token 使用量和估算费用。
-- 发送到编辑：从生成结果或历史记录直接进入编辑模式。
+- 连续工作流：从生成结果或历史记录继续编辑、做变体、复用提示词、对比、下载、分享或保存为灵感。
 - 下载与分享：单图结果可直接下载，分享链接支持访问码和有效期。
 - 页面访问保护：可通过 `APP_PASSWORD` 给网页和受保护图片访问加访问码。
 - Agent 状态后端：支持 `memory`、`sqlite`、`postgres`，覆盖临时演示、单实例和集中状态库场景。
@@ -139,24 +140,26 @@ http://localhost:4783
 ## 默认行为
 
 - 图片生成默认使用 `quality=high`。如需降低成本或让上游自行选择质量，可在页面或 Agent 请求中显式改为 `auto`、`medium` 或 `low`。
-- 页面默认不发送流式请求；用户显式开启流式预览后，才会走 SSE 路径。并发流式批处理仍默认关闭，只有设置 `ENABLE_STREAMING_BATCH=true` 后才会把 `n>1` 拆成多个流式任务。
+- 页面默认使用 `stream_mode=auto`。auto 会优先尝试 SSE；如果上游流式没有最终图，会在同一响应里显式回退到非流式并暴露 `fallback_used`。`stream` 强制流式，`non_stream` 直接走非流式 JSON。普通多图请求默认保持单次 `n>1` 上游请求；批量提示词默认按 `concurrency=1` 逐条执行。用户在页面显式勾选“并发批量”后，才会把多图或多提示词批次拆成多个 `n=1` 流式任务。
+- 批量模式下，每行提示词会形成一条独立任务，统一使用当前尺寸、质量、格式、模型和路由设置；底部提示词动作、批次历史、失败项复用和暂停状态都以当前可见批量提示词为准。
 - 服务端会把官方 OpenAI Images 流式事件、gaoren002/new-api 与 sub2api 图片 SSE、OtokAPI `image.generation.*`、Responses `image_generation_call` 事件统一映射为前端稳定的 `partial_image`、`completed`、`done`、`error` 事件。
-- 流式请求失败时会显示原始错误状态和排查建议，不会自动改用非流式请求，以避免隐藏网关、限流或上游故障。
+- `stream` 模式失败时会显示原始错误状态和排查建议，不会自动改用非流式请求。`auto` 模式只在可观测回退路径中降级，并通过响应字段和 runtime capabilities 暴露状态。
 
 ## 图片后端路径
 
 - 默认路径是服务端中继 OpenAI Images API：`/api/images` 调用上游 `/images/generations` 或 `/images/edits`，再返回本项目稳定的 JSON 或 SSE 协议。原版 new-api 和 sub2api 普通 JSON 能力保持这个基线。
-- 流式能力由请求字段或环境变量显式控制：`off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。`auto` 不会凭仓库名假设上游能力；Agent 辅助脚本对 `max_edge>2048` 的单次文生图默认优先使用页面端 `/api/images` SSE，失败后先诊断，再显式选择 Agent JSON 或 job 路径。
+- 流式策略由请求字段或环境变量控制：`off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。请求级 `stream_mode` 支持 `auto`、`stream`、`non_stream`；`IMAGE_STREAMING_STRATEGY=off` 时页面会切到 `non_stream`。Agent ���助脚本对 `max_edge>2048` 的单次文生图默认优先使用页面端 `/api/images` SSE，失败后先诊断，再显式选择 Agent JSON 或 job 路径。
 - 流式请求在没有 partial image 前只显示连接保持状态，不会把 keepalive 当成图片预览或成功结果。
-- gaoren002/new-api、sub2api、OtokAPI 与 GPT2Image 风格 Responses 兼容仅发生在事件适配层：partial image 只作为预览，只有最终 completed base64 才会保存为 artifact；缺最终 base64 或仅返回远程 URL 会显式失败。
+- gaoren002/new-api、sub2api、OtokAPI 与 GPT2Image 风格 Responses 兼容发生在事件和结果适配层：partial image 只作为预览，最终 completed 可返回 base64、图片 data URL 或与上游 `BASE_URL` 同源的图片 URL。同源 URL 会由服务端下载并保存；跨源 URL、非图片响应或超过大小限制会显式失败。
 - Responses API image generation 是实验路径，默认关闭。只有同时设置 `ENABLE_RESPONSES_IMAGE_BACKEND=true`、配置 `OPENAI_RESPONSES_API_MODEL`，并在请求中显式传入 `image_backend=responses-image-generation` 或兼容别名 `imageBackend=responses` 时，服务端才会调用 `/responses` 并读取 `image_generation_call.result`。
 - Agent capabilities 会同时暴露 `supported.image_backends` 枚举和 `supported.enabled_image_backends` 当前启用后端；自动化脚本应以后者和 `image_backend_requirements` 判断 runtime 是否已准备好。
-- Responses API 的顶层模型由 `OPENAI_RESPONSES_API_MODEL` 或请求字段 `responsesModel` 指定；页面表单里的图片模型只传给 `image_generation` 工具。
-- Responses API 实验路径支持单张 `generate` 的非流式和上游 SSE 消费，不替换默认 Images API，不接入编辑表单。Agent generate 对外仍返回最终 JSON，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用服务端内部上游 SSE 消费。
+- Responses API 的顶层模型由 `OPENAI_RESPONSES_API_MODEL` 或请求字段 `responsesModel` 指定；兼容字段 `gptModel`/`gpt_model` 也可覆盖顶层模型。页面表单里的图片模型只传给 `image_generation` 工具。
+- GPT2Image 兼容字段会尽量透传：文生图和图生图页面高级参数都可按后端选择提交字段；Responses 图片后端支持 `output_compression`、`promptOptimization`/`prompt_optimization` 和 `thinking`；Images API 路径支持 `force_web`/`forceWeb`。这些字段最终是否生效取决于命中的上游后端。
+- Responses API 实验路径支持单张 `generate` 和 `edit` 的非流式与上游 SSE 消费，不替换默认 Images API。页面文生图和图生图表单都可显式选择 Responses 图片后端；Agent generate/edit 对外仍返回最终 JSON；generate 可通过 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images` 控制服务端内部上游 SSE 消费，edit 仅支持 `stream_mode`、`streaming_strategy`、`partial_images`。
 
 ## 编辑与遮罩
 
-编辑模式支持最多 10 张源图。遮罩必须与源图尺寸一致，绘制或上传后会随编辑请求一起提交。
+编辑模式支持最多 10 张源图，上传字段必须使用 `image_0` 到 `image_9`。遮罩必须与源图尺寸一致，绘制或上传后会随编辑请求一起提交。
 
 <p align="center">
   <img src="./readme-images/mask-creation.jpg" alt="遮罩创建" width="460"/>
@@ -181,20 +184,22 @@ http://localhost:4783
 | 配置 | 说明 |
 | --- | --- |
 | API Key | OpenAI 或兼容接口的密钥。 |
-| API URL | OpenAI 兼容接口根地址，通常以 `/v1` 结尾。 |
+| API URL | OpenAI 兼容接口根地址，通常以 `/v1` 结尾；支持无凭据、无查询参数和无片段的 `http` 或 `https` 绝对地址。 |
 
 常见填写方式：
 
 ```text
 https://api.openai.com/v1
 https://your-compatible-api.example.com/v1
+http://your-internal-compatible-api.example.com/v1
 ```
 
-不要填写管理后台首页或网页地址。如果接口返回 HTML，应用会提示 API URL 不是 OpenAI Images JSON 响应。
+自定义 API URL 必须同时填写自定义 API Key，避免服务器密钥被发送到未知接口。不要填写管理后台首页或网页地址。如果接口返回 HTML，应用会提示 API URL 不是 OpenAI Images JSON 响应。
 
 ## Agent API
 
 Agent API 面向自动化调用，不要求 Agent 模拟网页表单。接口统一使用结构化错误、`Idempotency-Key` 和产物 ID。
+自动化客户端应先读取 `GET /api/agent/capabilities`，按其中的 `routing_rules`、`agent_streaming`、`agent_jobs`、`supported.enabled_image_backends` 和 `supported.image_backend_requirements` 选择路径，不要硬编码当前部署默认值。
 
 | 接口 | 用途 |
 | --- | --- |
@@ -217,10 +222,43 @@ Authorization: Bearer your-agent-token
 
 `AGENT_API_TOKEN` 存在时 Agent API 只接受 Bearer token，不会回退到页面访问码哈希。只有未设置 `AGENT_API_TOKEN` 且设置了 `APP_PASSWORD` 时，Agent API 才接受 `X-App-Password-Hash`；实际可用方案以 `/api/agent/capabilities` 的 `auth.schemes` 为准。
 
+页面端 `/api/images` SSE 是独立的 form-data 路径，不属于 `/api/agent/*` JSON 响应契约。`agent_streaming.page_sse.auth.required=true` 时，脚本需要把 `GPT_IMAGE_APP_PASSWORD_HASH` 作为 form-data `passwordHash` 发送；同一个业务 key 会作为 `clientRequestId` 发送，长度不得超过 capabilities 声明的 `agent_streaming.page_sse.client_request_id.max_length`。
+
 同一个 `Idempotency-Key` 如果已进入终态 `failed`，再次请求只会回放该失败，不会重新执行。终态失败回放会返回 `retryable=false`，并保留错误码、上游状态和脱敏诊断字段；需要重新尝试时，应创建新的业务操作和新的 `Idempotency-Key`。
 
 Job polling 当前是同一 Next.js 服务实例内的后台任务，结果和错误会写入 Agent 状态后端；它不是跨实例持久队列。若服务进程在 job 结束前重启，客户端应继续按状态端点和结构化错误处理，必要时用相同 `Idempotency-Key` 重建同一业务操作。
 运行中的 job 会定时刷新请求 lease，避免高质量长耗时上游调用仍在执行时被 recovery 误判为孤儿请求。
+`POST /api/agent/images/generate` 对外始终是最终 JSON；`max_edge>2048` 的单次文生图默认建议按 `/api/agent/capabilities` 使用页面端 `/api/images` SSE。显式传 `--agent` 或 `streaming_strategy=off` 时才走 Agent JSON 非流式路径，用于诊断对照。
+仓库辅助脚本支持 `--page-sse`、`--agent` 和 `--job` 显式选择路径。`--page-sse` 使用页面 SSE，`--agent` 强制 Agent generate/edit 最终 JSON，`--job` 使用 Agent generate job polling。页面流式失败后不会自动二次计费回退，需先按结构化错误和诊断字段确认原因，再选择新的业务操作和新的 `Idempotency-Key`。
+Agent 请求字段 `stream_mode=auto|stream|non_stream` 用于控制服务端内部上游流式消费：`auto` 是默认值并允许显式可观测回退，`stream` 强制上游流式并直接暴露失败，`non_stream` 直接非流式。`GET /api/runtime-capabilities` 会返回当前默认 stream mode、流式不可用标记 scope 和 availability summary。
+上游 SSE 字段边界以 `agent_streaming.upstream_sse.request_fields_by_mode` 为准：`generate` 可发送 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images`；`edit` 只可发送 `stream_mode`、`streaming_strategy`、`partial_images`。
+
+批量自动化可使用仓库 skill 脚本：
+
+```bash
+node skills/gpt-image-playground-agent/scripts/batch-images.mjs \
+  --input tasks.jsonl \
+  --ordered-prefix product-set
+```
+
+默认 dry-run 只解析 JSONL 和输出计划，不联网、不计费。真实执行必须加 `--allow-billable`，并可配合 `--manifest`、`--resume`、`--dimension-check`、`--max-attempts`、`--concurrency`、`--max-consecutive-failures` 和任务级 `sse_log_path` 做 append-only 续跑、PNG/JPEG/WebP 尺寸校验、失败重试、并发执行、连续失败熔断和页面 SSE 原始事件留档。`--max-consecutive-failures` 只能与顺序执行的 `--concurrency 1` 同用。
+
+并发脚本示例：
+
+```bash
+node skills/gpt-image-playground-agent/scripts/batch-images.mjs \
+  --allow-billable \
+  --input tasks.jsonl \
+  --manifest runs/product-set.manifest.jsonl \
+  --resume \
+  --dimension-check \
+  --max-attempts 2 \
+  --concurrency 3
+```
+
+`--concurrency` 默认是 `1`。大于 `1` 时会并发执行任务并按输入顺序输出结果；连续失败熔断需要严格顺序语义，因此只能与 `--concurrency 1` 同用。
+
+批量 JSONL 中，`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径，其中 edit 任务传入这些高级字段时会显式选择 `/api/images` form-data SSE，因为 Agent JSON edit 不接收这些字段。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。PNG 搭配 `output_compression` 会在 dry-run 输出 `normalizations.output_compression_ignored_for_png=true`，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
 
 生成示例：
 
@@ -296,13 +334,18 @@ Web 流式 `/api/images` 事件会同时提供 camelCase 字段和旧 snake_case
 | 变量 | 是否必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `OPENAI_API_KEY` | 条件必填 | 无 | 服务端默认 API Key。也可以在页面 `API 设置` 中填写。 |
-| `OPENAI_API_BASE_URL` | 否 | OpenAI 官方地址 | OpenAI 兼容接口根地址。 |
+| `OPENAI_API_BASE_URL` | �� | OpenAI 官方地址 | OpenAI 兼容接口根地址；默认要求 `https`。仅本机 loopback HTTP 可直接使用，远程 HTTP 必须显式加入 `OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS`。 |
+| `OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS` | 否 | 无 | 远程明文 HTTP 兼容接口 allowlist，多个完整 base URL 用英文逗号分隔。只用于必须明文接入且已确认网络边界安全的上游。 |
 | `OPENAI_ROUTING_STRATEGY` | 否 | `sticky` | 服务端多渠道路由策略，可选 `sticky`、`round_robin`、`random`。 |
 | `OPENAI_CHANNEL_N_ID` | 否 | 无 | 第 N 个服务端渠道标识，只用于日志排查。 |
-| `OPENAI_CHANNEL_N_BASE_URL` | 否 | 无 | 第 N 个 OpenAI 兼容接口根地址，通常以 `/v1` 结尾。 |
+| `OPENAI_CHANNEL_N_BASE_URL` | 否 | 无 | 第 N 个 OpenAI 兼容接口根地址，通常以 `/v1` 结尾；默认要求 `https`。仅本机 loopback HTTP 可直接使用，远程 HTTP 必须显式加入 `OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS`。 |
 | `OPENAI_CHANNEL_N_API_KEYS` | 否 | 无 | 第 N 个渠道的一个或多个 API Key，多个 key 用英文逗号分隔。 |
 | `OPENAI_CHANNEL_N_FAILURE_COOLDOWN_MS` | 否 | 继承全局值 | 第 N 个渠道的失败冷却时间。 |
-| `ENABLE_STREAMING_BATCH` | 否 | `false` | 显式设为 `true` 后，流式模式下 `n>1` 会拆成多个 `n=1` 任务并发执行。 |
+| `OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED` | 否 | `true` | 服务端渠道恢复探测开关。存在服务端凭证时默认开启，只请求对应上游 `GET /models`。 |
+| `OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY` | 否 | 跟随恢复探测开关 | 是否要求冷却到期的 credential/channel 先通过恢复探测，成功后才回到用户流量。设为 `true` 时，`OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED` 也必须启用。 |
+| `OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS` | 否 | `60000` | 后台恢复探测 tick 间隔。 |
+| `OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS` | 否 | `5000` | 单次 `/models` 探测超时。 |
+| `OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK` | 否 | `1` | 每个 tick 最多探测的恢复候选数量，用于限制低成本探测流量。 |
 | `IMAGE_GENERATION_BACKEND` | 否 | `images-api` | 服务端默认图片后端，可选 `images-api` 或 `responses-image-generation`。请求字段可覆盖。 |
 | `IMAGE_STREAMING_STRATEGY` | 否 | `auto` | 服务端默认流式兼容策略，可选 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。请求字段可覆盖。 |
 | `ENABLE_RESPONSES_IMAGE_BACKEND` | 否 | `false` | 实验开关。显式设为 `true` 后，`image_backend=responses-image-generation` 或兼容别名 `imageBackend=responses` 请求才可调用 Responses API image generation。 |
@@ -342,17 +385,23 @@ Web 流式 `/api/images` 事件会同时提供 camelCase 字段和旧 snake_case
 | --- | --- |
 | `OPENAI_ROUTING_STRATEGY` | 可选 `sticky`、`round_robin`、`random`。不填默认 `sticky`。 |
 | `OPENAI_CHANNEL_N_ID` | 渠道标识，只用于日志与排查，不会暴露 API Key。 |
-| `OPENAI_CHANNEL_N_BASE_URL` | 兼容接口根地址，通常以 `/v1` 结尾。 |
+| `OPENAI_CHANNEL_N_BASE_URL` | 兼容接口根地址，通常以 `/v1` 结尾；支持无凭据、无查询参数和无片段的 `http` 或 `https` 绝对地址。 |
 | `OPENAI_CHANNEL_N_API_KEYS` | 当前渠道下的一个或多个 API Key，多个 key 用英文逗号分隔。 |
 | `OPENAI_CHANNEL_N_FAILURE_COOLDOWN_MS` | 可选，覆盖单个渠道的失败冷却窗口。 |
 
-并发流式批处理默认关闭。开启 `ENABLE_STREAMING_BATCH=true` 后，页面允许在流式模式下选择多张图片；应用会把批次拆成多个独立 `n=1` 流式请求。推荐并发窗口由服务端运行时能力接口返回：默认 `sticky` 路由按单个 credential 容量计算，`round_robin` / `random` 路由按完整 credential 池计算。
+并发流式批处理默认不自动启用。页面允许在流式模式下选择多张图片或进入批量提示词模式；用户显式勾选“并发批量”后，应用会把批次拆成多个独立 `n=1` 流式请求。省心模式会显示当前并发状态摘要，专业模式的流式分组提供开关和不可用原因。推荐并发窗口由服务端运行时能力接口返回：默认 `sticky` 路由按单个 credential 容量计算，`round_robin` / `random` 路由按完整 credential 池计算。
 
 `OPENAI_MAX_STREAMS_PER_CREDENTIAL` 默认是 `1`，建议只在真实上游探针验证单 key 可承受更高并发后再调大。
 
 如果服务端 credential 返回鉴权失败、额度不足或限流错误，应用会把该 credential 标记为短暂不可用。若渠道返回 5xx、Cloudflare 520/522/523/524、连接失败或超时，应用会冷却整个 channel，并在冷却窗口内跳过该 channel 下所有 key。若兼容网关把 `invalid_api_key`、`insufficient_quota` 等 credential 错误包在 5xx 中返回，credential 错误优先，不会误冷却整个 channel。所有 credential 都在冷却中时，请求会显式失败��不会伪造成功或静默降级。
 
-运行时能力接口会返回健康 credential/channel 数量与最近一次失败摘要（status、code、requestId），用于诊断和前端并发窗口刷新；不会返回 API Key 或上游错误消息。
+默认情况下，冷却到期不会直接把 credential/channel 放回用户生图流量。服务端会启动低频后台恢复探测，只对待恢复候选请求对应上游的 `GET /models`；HTTP 200 且响应包含 `data` 数组后才恢复。探测不会调用 `/images/generations`，不触发生图费用。探测失败会继续隔离该 credential/channel 并重新进入冷却窗口。可用 `OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK` 限制每个 tick 的探测数量，默认每分钟最多探测 1 个候选。
+
+恢复探测调度器运行在当前 Node.js 进程内，适合 Docker 或 standalone 单实例部署。Serverless 环境可能在请求结束后冻结进程；多副本部署也会各自维护内存健康状态。此类部署如需严格恢复控制，应使用常驻实例、共享健康状态或外部定时探测；大规模 credential 池可按可接受恢复速度调大 `OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK`，但不要超过上游 `/models` 的限流承受能力。
+
+恢复探测带有状态版本锚点：如果某次 `/models` 探测请求发出后，同一个 credential/channel 又被新的用户请求失败重新冷却，旧探测成功不会覆盖这次更新后的失败状态。
+
+运行时能力接口会返回健康 credential/channel 数量、待恢复探测数量、已到期候选数量、按当前 `MAX_PER_TICK` 估算的最少 drain tick/时间、探测配置和最近一次失败摘要（status、code、requestId），用于诊断和前端并发窗口刷新；不会返回 API Key 或上游错误消息。
 
 三种策略：
 
@@ -483,7 +532,15 @@ npm run deploy:space
 npm run agent:doctor
 ```
 
-`status` 只读输出 git、Node、固定 Space 目标、Agent capabilities 路径、仓库 Skill 入口和独立真实图片上游 smoke 配置摘要。它会按 shell 环境变量、`.env.real-smoke.local`、`.env.local` 的优先级判断真实 smoke 配置是否齐全，但不会输出 URL 或 API Key；`doctor` 汇总本机与 HF Space 诊断；`verify` 执行提交前基线，需要真实 PostgreSQL gate 时加 `--postgres`；`deploy:local` 重建本地 Docker 并探测真实端点；`deploy:space` 是 HF Space 发布的稳定别名；`agent:doctor` 对当前 Agent API 做只读契约检查。
+`status` 只读输出 git、Node、固定 Space 目标、Agent capabilities 路径、仓库 Skill 入口和独立真实图片上游 smoke 配置摘要。它会按 shell 环境变量、`.env.real-smoke.local`、`.env.local` 的优先级判断真实 smoke 配置是否齐全，但不会输出 URL 或 API Key；`doctor` 汇总本机与 HF Space 诊断；`verify` 执行提交前基线，需要真实 PostgreSQL gate 时加 `--postgres`；`deploy:local` 重建本地 Docker 并探测真实端点；`deploy:space` 是 HF Space 发布的稳定别名；`agent:doctor` 默认做非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend、Responses/GPT2Image readiness，并把真实生图 smoke 标记为 skipped。
+
+如需让 `agent:doctor` 执行真实计费 smoke，必须显式传入：
+
+```bash
+npm run agent:doctor -- --allow-billable --edit-image /path/to/reference.png
+```
+
+其中 1K 文生图、1K 图生图和 2K page SSE edit 会按真实上游路径执行；未传 `--allow-billable` 时不会触发生图。
 
 如果只想诊断 HF Space 前置条件，可运行：
 
@@ -563,7 +620,7 @@ docker logs -f gpt-image-playground-customer
 | `npm run verify` | 执行提交前基线：测试、lint、脚本语法、构建和 `git diff --check`；加 `-- --postgres` 会包含 live PostgreSQL gate。 |
 | `npm run deploy:local` | 重建本地 Docker 服务并探测 `/api/auth-status`、`/api/runtime-capabilities`、`/api/agent/capabilities`；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。 |
 | `npm run deploy:space` | 上传当前干净 git HEAD 到固定 HF Space，并做只读公网验证。 |
-| `npm run agent:doctor` | 通过仓库 Skill 脚本执行只读 Agent API 契约检查，不触发真实生图。 |
+| `npm run agent:doctor` | 执行非计费 Agent 分层诊断，真实 1K/2K smoke 必须显式加 `-- --allow-billable`。 |
 | `npm run deploy:hf-space` | 使用官方 `hf` CLI 上传当前干净 git HEAD 到固定 Space 并做只读公网验证。 |
 | `npm run doctor:hf-space` | 只读诊断 HF Space 部署前置条件、固定 Space 目标和远端配置。 |
 | `npm run keepalive:hf-space` | 访问 HF Space 只读状态端点，用于 keepalive 验证。 |
@@ -577,9 +634,12 @@ docker logs -f gpt-image-playground-customer
 
 真实上游 smoke 使用以下环境变量前缀逐类配置：`IMAGE_REAL_SMOKE_ORIGINAL_*`、`IMAGE_REAL_SMOKE_GAOREN_*`、`IMAGE_REAL_SMOKE_SUB2API_*`、`IMAGE_REAL_SMOKE_SUB2API_RESPONSES_*`、`IMAGE_REAL_SMOKE_GPT2IMAGE_*`。每类至少提供 `BASE_URL` 和 `API_KEY`；Responses 场景还必须提供 `/responses` 顶层模型。可选覆盖图片 `MODEL`、`SIZE`、`QUALITY`。`BASE_URL` 必须是无凭据、无查询参数、无片段的 `http`/`https` 绝对 URL。默认不触发计费请求，必须显式加 `-- --allow-billable`。可复制 `.env.real-smoke.example` 为未跟踪的 `.env.real-smoke.local`，再通过 `-- --env-file .env.real-smoke.local` 加载；shell 环境变量优先级高于 `--env-file`，`--env-file` 优先级高于 `.env.local`。
 
+GPT2Image 付费站的真实上游地址应配置为 `https://gpt2image.superapi.buzz/v1`，不要使用站点首页 URL。该场景会通过 Responses image_generation SSE 验证 URL 结果物化和最终图片保存。
+
 `npm run smoke:image-upstream-local` 会临时启动仓库内置 fixture，把 5 个独立场景全部指向本机 `/v1` 兼容服务，并调用同一个 `smoke:image-upstream-real -- --require-independent-targets --allow-billable` 门禁路径。该命令用于验证本项目的 final-gate 脚本、事件归一化和本地可复现环境；输出会标记 `local_fixture=true`。它不证明原版 new-api、gaoren/new-api、sub2api 或 GPT2Image 第三方部署当前可访问，真实验收仍需配置 `.env.real-smoke.local` 后运行真实上游门禁。
 
 若只需要验证当前 `.env.local` 中的 `OPENAI_API_KEY` 或 `OPENAI_CHANNEL_N_*` 服务端渠道，可追加 `-- --include-server-channel`。该模式不会把服务端 API Key 写入表单或输出，真实执行仍需同时追加 `--allow-billable`；可覆盖 Images JSON、Images SSE、Responses JSON、Responses SSE、Agent 内部 Images SSE 和 Agent 内部 Responses SSE 场景。可用 `IMAGE_REAL_SMOKE_SERVER_MODEL`、`IMAGE_REAL_SMOKE_SERVER_SIZE`、`IMAGE_REAL_SMOKE_SERVER_QUALITY`、`IMAGE_REAL_SMOKE_SERVER_RESPONSES_MODEL` 覆盖模型、尺寸、质量和 Responses 顶层模型。单场景默认超时 `240000ms`，可用 `--timeout-ms` 或 `IMAGE_REAL_SMOKE_TIMEOUT_MS` 调整。
+服务端渠道 smoke 只证明当前配置和上游账号池在请求时可用；如果上游返回 `503` 或 `No available compatible accounts`，应归类为上游渠道当前不可用，不要把它记成本地路由或脚本成功。
 
 dry-run 输出中的 `independent_targets` 会汇总必跑、已选、未选、已配置和缺失的独立真实上游场景，并给出最终门禁命令；`required_count` 和 `unselected_required_count` 用于区分必跑总数和未选择数量，`configuration_complete=true` 只表示 5 个必跑场景都已选中且配置齐全，不代表已经执行计费生图。顶层 `final_gate_satisfied=true` 才表示最终独立真实上游门禁已实际执行并通过。`missing_env_any` 表示每组任选一个环境变量即可补齐该缺失项。例如 `sub2api-responses-json` 的 `BASE_URL` 和 `API_KEY` 可单独配置 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_*`，也可以复用 `IMAGE_REAL_SMOKE_SUB2API_*`；它的 `/responses` 顶层模型必须使用 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL`，避免和图片模型 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL` 混淆。
 
@@ -607,7 +667,7 @@ dry-run 输出中的 `independent_targets` 会汇总必跑、已选、未选、
 
 ### API 返回 HTML 页面
 
-说明 API URL 填成了网页或管理后台地址。请填写 OpenAI 兼容接口根地址，通常以 `/v1` 结尾。
+说明 API URL 填成了网页或管理后台地址。请填写 OpenAI 兼容接口根地址，通常以 `/v1` 结尾；地址必须是无凭据、无查询参数和无片段的 `http` 或 `https` 绝对 URL。
 
 ### 生成接口提示需要 API Key
 

docs/deployment/huggingface-space-free.md

@@ -153,6 +153,8 @@ APP_PASSWORD=<page-access-code>
 AGENT_API_TOKEN=<long-random-agent-token>
 ```
 
+`OPENAI_API_BASE_URL` 和 `OPENAI_CHANNEL_N_BASE_URL` 必须是无凭据、无查询参数和无片段的 `http` 或 `https` 绝对地址，通常以 `/v1` 结尾。公网 Space 推荐使用 `https` 上游；只有内网、专用代理或已确认的兼容渠道需要 `http` 时才配置 `http`。
+
 公网部署建议至少设置访问码 `APP_PASSWORD` 和 `AGENT_API_TOKEN`。如果不设置 `APP_PASSWORD`，任何人都可以打开网页并消耗服务端 API Key。
 
 如果使用服务端渠道池，改用 `OPENAI_CHANNEL_N_*` Secrets：
@@ -194,6 +196,10 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 脚本会先读取 `GET /api/agent/capabilities`，再调用 Agent API。成功响应会保留相对 `content_url`，同时补充 `absolute_content_url` 和 `absolute_metadata_url`，便于在桌面环境直接下载产物。
 
+远端 Agent 调用不要硬编码路径。脚本会按 capabilities 中的 `routing_rules`、`agent_streaming` 和 `agent_jobs` 判断默认路径：普通小图走 Agent JSON，`max_edge>2048` 的单次文生图和高分辨率 edit 默认优先走页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再显式回退到 Agent JSON、Agent edit 或 job 路径。job polling 只在显式选择时使用。需要诊断对照时可用 `--agent` 或 `--streaming-strategy off` 强制 Agent JSON，也可用 `--page-sse` 或 `--job` 显式选择路径。
+
+如果 Space 同时配置了 `APP_PASSWORD` 和 `AGENT_API_TOKEN`，Agent JSON 端点用 `GPT_IMAGE_AGENT_TOKEN` 发送 Bearer token；页面端 `/api/images` SSE 仍按 capabilities 的 `agent_streaming.page_sse.auth` 判断，可能需要额外设置 `GPT_IMAGE_APP_PASSWORD_HASH`，并通过 form-data `passwordHash` 发送页面访问码哈希。页面 SSE 会把业务 key 写入 `clientRequestId`，长度上限以 capabilities 中的 `agent_streaming.page_sse.client_request_id.max_length` 为准。
+
 ## 本地 HF 近似 smoke
 
 提交前运行：
@@ -226,6 +232,7 @@ npm run smoke:hf-space
 - 工作流文件：`.github/workflows/hf-space-keepalive.yml`
 - 默认频率：每 6 小时一次，可手动触发 `workflow_dispatch`
 - 默认目标：`https://misonl-gpt-image-playground-customer.hf.space/api/auth-status`
+- GitHub Actions 中默认最多请求 3 次，每次超时 30 秒，重试间隔 5 秒。失败日志会记录每次尝试，不把超时伪装成成功。
 - 行为边界：只访问只读鉴权状态端点，不携带 `APP_PASSWORD`、`AGENT_API_TOKEN` 或 OpenAI Key，不触发生图、不访问 Agent 生成接口。
 
 如果 Space 地址变化，在 GitHub 仓库 Variables 中设置：
@@ -239,6 +246,7 @@ HF_SPACE_KEEPALIVE_URL=https://<user>-<space>.hf.space
 ```bash
 HF_SPACE_KEEPALIVE_URL=https://<user>-<space>.hf.space \
 HF_SPACE_KEEPALIVE_EXPECT_PASSWORD_REQUIRED=true \
+HF_SPACE_KEEPALIVE_MAX_ATTEMPTS=3 \
 npm run keepalive:hf-space
 ```
 

docs/reviews/CR-AGENT-ROUTING-LOCAL-FINAL-GATE-2026-05-22.md

@@ -9,7 +9,7 @@
 ## 审计结论
 
 - `/api/agent/capabilities` 现在暴露机器可读 `routing_rules`，`schema_version=2026-05-22`。
-- 高分辨率 Agent edit 请求在 route 层 `snapshotAgentEditFormData` 前被拒绝，服务层也在读取服务端 API 凭据前保留二道校验。
+- 当前路由口径已更新：高分辨率 edit 默认优先走页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再显式回退到 Agent edit。
 - partial-only 上游 SSE 失败会保留 `upstream_event_type` 与 `partial_image_count`，但不会泄漏 partial base64。
 - 已进入终态 `failed` 的 Agent/job 回放会移除 `retry_after_seconds` 并返回 `retryable=false`。
 - 本地 final gate 启动仓库 fixture 后复用真实 smoke 脚本，跑满 5 个独立场景并要求 `final_gate_satisfied=true`。

docs/ui/literary-young-women-workbench-design.md

@@ -0,0 +1,550 @@
+# 图像手记 UI 设计基线
+
+## 1. 定稿结论
+
+本项目 Web UI 后续重构以 `女青年文艺风功能交互稿` 为唯一设计基线。
+
+- 当前实现名称：`图像手记` 工作台。
+- 定稿图：`/tmp/gipc-literary-young-women-functional-v5.png`
+- 产品名称：`图像手记`
+- 产品副标题：`今天想做什么画面？`
+- 核心定位：面向中文用户的 AI 图像创作工作台，强调文艺、柔和、清爽、可持续使用。
+- 设计目标：文艺但能干活，柔和但不牺牲参数能力。
+
+本基线明确排除古风、传统器物化、普通 SaaS 仪表盘和过度 AI 科技风。
+
+## 2. 目标用户与气质
+
+目标用户是中文创作者，尤其偏向年轻女性、独立杂志读者、小红书内容创作者、摄影和设计爱好者、手账和咖啡馆工作流用户。
+
+目标气质：
+
+- 现代女青年文艺风。
+- 独立杂志、咖啡馆手账、胶片摄影、艺术书、生活方式创作工具。
+- 温柔、轻盈、清新、有个人感，但仍然专业和高效。
+- 中文优先，文案自然，不暴露过多工程词。
+
+避免气质：
+
+- 古风、国风器物、传统书画、宣纸卷轴、印章、毛笔、砚台、灯笼、宫廷或寺庙感。
+- 深色科技仪表盘、霓虹、赛博朋克、玻璃拟态、紫色渐变。
+- 企业后台、金融 SaaS、模板化 bento grid。
+- 低幼粉色、过度贴纸化、装饰大于功能。
+
+## 3. 视觉系统
+
+### 3.1 色彩
+
+主色按温柔浅色系组织，保持低疲劳和长时间可用。
+
+- 页面基底：奶油米白、淡奶茶色、浅亚麻纸色。
+- 主要文字：炭黑、咖啡棕。
+- 次级文字：灰褐色、柔和橄榄灰。
+- 辅助面：浅粉、鼠尾草绿、淡黄油色。
+- 主操作色：珊瑚番茄红，用于 `生成图像`。
+- 状态点缀：少量蓝灰，用于 API、模型和流式状态。
+
+色彩比例建议：
+
+- 60%：奶油米白和淡奶茶背景。
+- 30%：纸卡、浅粉、鼠尾草绿、米色分层。
+- 10%：珊瑚红按钮、蓝灰状态、淡黄提示。
+
+禁止使用：
+
+- 大面积紫色、紫蓝渐变。
+- 大面积深蓝、深灰、黑色科技底。
+- 仿古黄、旧羊皮纸、朱砂印章红。
+
+### 3.2 材质
+
+界面材质来自现代纸张和生活方式视觉，不来自古代书画。
+
+- 细腻亚麻纸纹理。
+- 胶片照片缩略图。
+- 淡淡纸层阴影。
+- 轻量贴纸感样式标签。
+- 杂志剪贴和手账排版暗示。
+- 细线网格和裁切标记。
+
+所有材质必须克制，不能影响可读性和操作效率。
+
+### 3.3 字体与排版
+
+中文优先，整体像现代独立杂志和创意工具。
+
+- 标题：可使用更有编辑感的中文标题样式，字重中等或偏细。
+- 正文与控件：使用清晰现代无衬线中文字体。
+- 行高：保持舒展，避免压迫。
+- 标签：短句优先，避免工程缩写。
+- 英文仅用于模型名、技术名和必要状态，例如 `gpt-image-2`。
+
+排版原则：
+
+- 中心画布最大，操作围绕画布服务。
+- 左侧信息密度中等，保持创作单的顺序。
+- 右侧卡片轻量，避免历史列表压迫主画布。
+- 不使用超大营销标题，不做 landing page。
+
+### 3.4 圆角与阴影
+
+- 圆角最大建议 `8px`，避免全圆角玩具感。
+- 主卡片可使用 `6px` 到 `8px`。
+- 按钮和输入框保持一致半径。
+- 阴影只模拟轻纸层，不能做厚重浮层或玻璃感。
+
+## 4. 信息架构
+
+页面是一个完整工作台，不是宣传页。
+
+主结构：
+
+```text
++-------------------------------------------------------------+
+| 顶部状态栏：图像手记 / 模型 / 渠道 / 费用 / 设置             |
++--------------+------------------------------+---------------+
+| 左侧创作单    | 中央画面预览                   | 右侧相册记录   |
+| 模式入口      | 生成状态                       | 灵感相册       |
+| 提示词        | 结果动作链                     | 最近生成       |
+| 基础参数      | 对比与编辑                     | 生成动态       |
+| 生成按钮      |                              |               |
++--------------+------------------------------+---------------+
+| 高级设置抽屉：省心模式 / 专业模式 / 输出 / 模型 / 流式 / 路由 |
++-------------------------------------------------------------+
+```
+
+信息优先级：
+
+1. 中央画面预览。
+2. 左侧创作单和生成按钮。
+3. 结果后的编辑动作链。
+4. 右侧灵感与历史。
+5. 高级参数和日志。
+
+## 5. 顶部状态栏
+
+顶部状态栏用于建立当前环境和全局入口，不承载主要创作流程。
+
+内容：
+
+- 产品名：`图像手记`
+- 副标题：`今天想做什么画面？`
+- 当前模型：例如 `gpt-image-2`
+- 渠道状态：例如 `流式可用`
+- 费用状态：例如 `预计 0.12 积分`
+- API 状态：例如 `API 正常`
+- 设置入口。
+
+要求：
+
+- 视觉安静，不抢主按钮。
+- 状态信息可读但不显得像运维面板。
+- 技术状态尽量转译为用户可理解语言。
+
+## 6. 左侧创作单
+
+左侧是完整创作入口，采用从上到下的自然创作顺序。
+
+### 6.1 模式入口
+
+使用清晰分段控件，放在左侧创作单顶部。
+
+四个模式：
+
+- `文生图`
+- `图生图`
+- `批量`
+- `复用历史`
+
+默认选中 `文生图`。
+
+设计要求：
+
+- 模式切换必须明显，不隐藏在高级设置里。
+- 每种模式切换后，左侧表单内容按任务调整。
+- 不使用工程模式名，例如 `generate`、`edit`、`batch`。
+
+### 6.2 提示词输入
+
+模块标题：`写下灵感`
+
+提示词输入区域应像现代笔记本或创作卡片，而不是普通后台 textarea。
+
+示例文案方向：
+
+```text
+午后咖啡馆窗边，一束粉白花，胶片感，柔和自然光，松弛的生活杂志封面
+```
+
+要求：
+
+- 输入区高度足够，适合长提示词。
+- 支持多行自然书写。
+- 周围可有轻微手账感，但不能影响文字输入。
+- 空状态文案应鼓励创作，不做教程式说明。
+
+### 6.3 风格标签
+
+风格标签采用轻贴纸视觉，服务于快速构造提示词。
+
+建议标签：
+
+- `胶片感`
+- `奶油色`
+- `日杂`
+- `花束`
+- `清透`
+- `松弛`
+- `复古咖啡`
+- `夏日窗边`
+
+行为要求：
+
+- 点击后追加或融合到提示词。
+- 已选标签要有明确状态。
+- 标签数量不宜一次展示过多，可横向滚动或折叠。
+
+### 6.4 基础参数
+
+基础参数只保留高频项：
+
+- `尺寸`
+- `数量`
+- `清晰度`
+- `格式`
+
+要求：
+
+- 使用紧凑但清晰的控件。
+- 参数命名面向用户，不暴露 API 字段名。
+- 默认值应能覆盖大多数使用场景。
+- 复杂参数放入专业模式。
+
+### 6.5 生成动作区
+
+生成动作区必须贴近费用、模型和渠道状态，避免用户点按钮前不清楚成本和路径。
+
+内容：
+
+- 状态 chip：`gpt-image-2`
+- 状态 chip：`流式可用`
+- 费用 chip：`预计 0.12 积分`
+- 主按钮：`生成图像`
+- 次级操作：`存为灵感`
+- 次级操作：`随便来点`
+
+要求：
+
+- `生成图像` 使用珊瑚番茄红。
+- 费用和模型信息必须在按钮附近。
+- 禁用状态要说明原因，例如缺少提示词、图片未上传、尺寸无效。
+
+## 7. 中央画面预览
+
+中央是页面视觉和功能重心。
+
+模块标题：`画面预览`
+
+状态：
+
+- 空状态：`还没有生成图像`
+- 生成中：`正在生成`，可显示进度或流式预览。
+- 成功：显示当前结果。
+- 失败：显示明确错误和重试入口。
+
+视觉要求：
+
+- 大面积留白和画廊板感。
+- 图片区域可带轻裁切标记和细线网格。
+- 不放入厚重卡片套卡片。
+- 预览图优先，工具条围绕图片轻量排布。
+
+### 7.1 结果动作链
+
+结果出现后必须提供连续工作流，不让用户只看到一张图。
+
+动作：
+
+- `下载`
+- `继续编辑`
+- `做变体`
+- `复用提示词`
+- `对比`
+
+行为要求：
+
+- `下载`：保存当前图片。
+- `继续编辑`：切换到图生图或编辑模式，并带入当前图片。
+- `做变体`：保留提示词和基础参数，生成新变体。
+- `复用提示词`：把历史或当前提示词带回左侧创作单。
+- `对比`：支持与上一张或选中历史图对比。
+
+这些动作应在结果附近，而不是只藏在历史列表里。
+
+## 8. 右侧相册与记录
+
+右侧分为灵感和历史，避免概念混淆。
+
+### 8.1 标签页
+
+两个主要标签：
+
+- `灵感相册`
+- `最近生成`
+
+区别：
+
+- `灵感相册`：保存模板、风格、参考提示词和收藏。
+- `最近生成`：真实生成记录、图片和参数。
+
+### 8.2 灵感相册
+
+卡片内容：
+
+- 缩略图或风格封面。
+- 风格名。
+- 简短提示词片段。
+- 收藏或固定入口。
+- `套用` 动作。
+
+视觉：
+
+- 胶片照片或杂志剪贴感。
+- 小面积纸层，不要重卡片。
+
+### 8.3 最近生成
+
+卡片内容：
+
+- 缩略图。
+- 时间或批次信息。
+- 模型和尺寸。
+- 提示词片段。
+- 收藏、复用、继续编辑入口。
+
+要求：
+
+- 历史记录支持快速回到创作单。
+- 批量结果可折叠成批次。
+- 失败记录应能看到原因，但不要占据主界面。
+
+### 8.4 生成动态
+
+生成动态是低干扰日志，不是开发者控制台。
+
+显示内容：
+
+- 请求开始。
+- 流式预览更新。
+- 图片保存完成。
+- 失败原因和重试建议。
+
+文案要求：
+
+- 用户可理解。
+- 不展示原始堆栈。
+- 技术细节放到专业模式或调试详情。
+
+## 9. 高级设置
+
+高级设置不能堆在主界面。
+
+入口：
+
+- `省心模式`
+- `专业模式`
+
+默认使用 `省心模式`。
+
+专业模式分组：
+
+- `输出`
+- `模型`
+- `流式`
+- `路由`
+
+要求：
+
+- 主界面只显示高频参数。
+- 专业模式可展开，但不要一次铺满所有字段。
+- 工程词在主界面减少暴露，专业模式中可保留必要精确项。
+- 当前选择会影响费用或稳定性时，应显示解释。
+- 当前实现中，桌面端高级设置位于底部 Pro Dock。`省心模式` 展示模型、流式、格式和尺寸摘要；启用并发批量时，流式摘要必须显示并发状态。
+- 当前实现中，`专业模式` 包含 `输出`、`模型`、`流式`、`路由` 分组。`并发批量` 开关位于流式分组；当流式策略关闭、任务数不足或服务端容量不可用时，开关保持禁用并显示原因。
+
+## 10. 模式交互
+
+### 10.1 文生图
+
+默认模式。
+
+主流程：
+
+1. 写提示词。
+2. 选择风格标签。
+3. 调整尺寸、数量、清晰度和格式。
+4. 确认模型、流式状态和预计费用。
+5. 点击 `生成图像`。
+6. 在中央查看结果。
+7. 下载、编辑、变体、复用或对比。
+
+### 10.2 图生图
+
+图生图需要明确上传入口和参考图状态。
+
+新增区域：
+
+- 图片上传。
+- 多图列表。
+- 遮罩或局部编辑入口。
+- 参考强度或编辑说明。
+
+要求：
+
+- 上传图出现在中央或左侧明确位置。
+- 不让用户误以为还在纯文生图。
+- 结果仍进入同一动作链。
+
+### 10.3 批量
+
+批量模式面向多提示词或多尺寸任务。
+
+新增区域：
+
+- 批量提示词列表。
+- 批次设置。
+- 失败重试策略。
+- 进度和失败汇总。
+
+要求：
+
+- 批量进度不挤占单张预览主区域。
+- 支持暂停、重试、复用失败项。
+- 结果按批次进入最近生成。
+- 当前实现中，批量模式按“每行提示词一条任务”执行，每条任务使用当前统一的尺寸、清晰度、格式、模型、流式和路由设置。
+- 批量模式默认顺序执行。只有用户显式启用 `并发批量`，且当前任务数大于 1、流式策略可用、服务端或用户自填 API Key 有并发容量时，才会并发执行。
+- 暂停批量时，已开始任务继续完成，未开始任务保留为失败项，便于用户复用失败项后再次提交。
+- 底部提示词动作必须使用当前可见的批量提示词文本，不得回退到隐藏的单条文生图提示词。
+
+### 10.4 复用历史
+
+复用历史让用户从右侧记录反向进入创作。
+
+能力：
+
+- 从历史图恢复提示词。
+- 从历史图恢复参数。
+- 从收藏模板套用风格。
+- 从某张图进入继续编辑。
+
+要求：
+
+- 明确显示复用了哪些内容。
+- 用户可以修改后再生成。
+
+## 11. 移动端原则
+
+移动端不能简单压缩三栏。
+
+移动端结构：
+
+- 画布优先。
+- 底部抽屉承载创作单。
+- 横向滑动相册。
+- 顶部只保留标题、状态和设置。
+
+移动端顺序：
+
+1. 画面预览。
+2. 底部 `生成图像` 主按钮。
+3. 上滑展开创作单。
+4. 横滑查看灵感和历史。
+5. 专业模式放二级抽屉。
+
+要求：
+
+- 主按钮始终易触达。
+- 不让参数挤压图片预览。
+- 图生图上传和结果动作链要适配触控。
+
+## 12. 文案规范
+
+整体文案中文优先，少工程味，少教程感。
+
+推荐文案：
+
+- `图像手记`
+- `今天想做什么画面？`
+- `写下灵感`
+- `生成图像`
+- `存为灵感`
+- `随便来点`
+- `画面预览`
+- `还没有生成图像`
+- `灵感相册`
+- `最近生成`
+- `生成动态`
+- `继续编辑`
+- `做变体`
+- `复用提示词`
+- `省心模式`
+- `专业模式`
+
+避免文案：
+
+- `Generate`
+- `Edit`
+- `Debug`
+- `Routing`
+- `Backend`
+- `SSE`
+- `Responses`
+
+必要技术名可以放入专业模式，例如 `Responses`、`SSE`、`image backend`，但主界面应转译为用户可理解的状态。
+
+## 13. 实现注意
+
+后续开发时应保持以下边界：
+
+- 不直接照搬生成图中的错字或不稳定小字，以本文档为准。
+- 不为了装饰牺牲表单可访问性和键盘操作。
+- 不把高级参数重新堆回主界面。
+- 不使用古风素材或传统器物隐喻。
+- 不提交临时生成图，除非后续明确把某张图作为正式设计资产。
+- 每次 UI 实现后需要做桌面和移动端截图复核。
+- 结果区动作链和右侧最近生成都必须保留真实可操作入口：下载、继续编辑、做变体、复用提示词、对比和保存为灵感。批量历史默认折叠多图缩略图，避免右侧列表被单个批次撑开。
+- 最近生成标签页在有生成历史且没有灵感项时应自动进入最近生成视图；失败记录显示原因但不伪造缩略图。
+
+建议实现拆分：
+
+1. 先建立新的页面信息架构和状态模型。
+2. 再重构左侧创作单。
+3. 再重构中央画布和结果动作链。
+4. 再重构右侧灵感相册和最近生成。
+5. 最后接入专业模式抽屉和移动端布局。
+
+## 14. 验收清单
+
+视觉验收：
+
+- 页面第一印象是现代女青年文艺风，而不是古风或普通后台。
+- 米黄色基底清爽，不显旧、不显脏。
+- 柔粉、鼠尾草绿、咖啡��和珊瑚红比例克制。
+- 装饰来自现代手账、胶片、杂志和生活方式，不来自传统器物。
+
+功能验收：
+
+- 文生图、图生图、批量、复用历史入口清晰。
+- 用户点生成前能看到模型、渠道和预计费用。
+- 生成后能直接下载、继续编辑、做变体、复用提示词和对比。
+- 灵感相册与最近生成概念分离。
+- 高级参数默认收纳，但可被专业用户找到。
+- 移动端以画布优先，不是三栏硬压缩。
+
+工程验收：
+
+- 主界面无装饰性 Unicode 符号。
+- 文案中文优先。
+- 核心表单可键盘操作。
+- 响应式下文本不重叠。
+- `npm test`、`npm run lint`、`npm run lint:scripts`、`npm run build` 和 `git diff --check` 作为实现收尾基线。

package-lock.json

@@ -1,12 +1,13 @@
 {
   "name": "gpt-image-playground",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "gpt-image-playground",
-      "version": "1.3.0",
+      "version": "1.4.0",
+      "license": "MIT",
       "dependencies": {
         "@radix-ui/react-checkbox": "^1.3.2",
         "@radix-ui/react-dialog": "^1.1.11",

package.json

@@ -1,13 +1,14 @@
 {
   "name": "gpt-image-playground",
-  "version": "1.3.0",
+  "version": "1.4.0",
+  "license": "MIT",
   "private": true,
   "scripts": {
     "dev": "next dev --turbopack -p 4783",
     "prebuild": "node scripts/clean-standalone.mjs",
     "build": "next build",
     "postbuild": "node scripts/patch-standalone-runtime.mjs",
-    "test": "node --test --import tsx \"src/**/*.test.ts\" \"scripts/**/*.test.mjs\"",
+    "test": "node --test --import tsx \"src/**/*.test.ts\" \"src/**/*.test.tsx\" \"scripts/**/*.test.mjs\"",
     "test:scripts": "node --test \"scripts/**/*.test.mjs\"",
     "test:postgres": "node scripts/test-postgres-live.mjs",
     "doctor": "node scripts/doctor.mjs",

scripts/agent-doctor.mjs

@@ -5,52 +5,339 @@ import { fileURLToPath } from 'node:url';
 import { isMainModule, parseJsonPayload, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
 
 const GENERATE_SCRIPT = fileURLToPath(new URL('../skills/gpt-image-playground-agent/scripts/generate-image.mjs', import.meta.url));
+const EDIT_SCRIPT = fileURLToPath(new URL('../skills/gpt-image-playground-agent/scripts/edit-image.mjs', import.meta.url));
 const AGENT_DOCTOR_TIMEOUT_MS = 75_000;
+const DEFAULT_BASE_URL = 'http://localhost:4783';
 
 export function buildAgentDoctorArgs() {
     return [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000', 'contract check'];
 }
 
 function parseArgs(argv) {
-    const unknown = argv.find((arg) => !['--help', '-h'].includes(arg));
-    if (unknown) throw new Error(`Unknown option: ${unknown}`);
-    return {
-        help: argv.includes('--help') || argv.includes('-h')
+    const parsed = {
+        help: false,
+        allowBillable: false,
+        timeoutMs: 60_000,
+        editImage: undefined
     };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') parsed.help = true;
+        else if (arg === '--allow-billable') parsed.allowBillable = true;
+        else if (arg === '--timeout-ms') parsed.timeoutMs = readPositiveInteger(readOptionValue(argv, (index += 1), arg), '--timeout-ms');
+        else if (arg === '--edit-image') parsed.editImage = readOptionValue(argv, (index += 1), arg);
+        else throw new Error(`Unknown option: ${arg}`);
+    }
+    return parsed;
 }
 
 function printHelp() {
     console.log(`Usage:
   npm run agent:doctor
+  npm run agent:doctor -- --allow-billable --edit-image /path/to/reference.png
 
 Environment:
   GPT_IMAGE_PLAYGROUND_URL       Service base URL, defaults to http://localhost:4783.
   GPT_IMAGE_AGENT_TOKEN          Bearer token when capabilities require bearer auth.
-  GPT_IMAGE_APP_PASSWORD_HASH    Password hash when capabilities require page password auth.`);
+  GPT_IMAGE_APP_PASSWORD_HASH    Password hash when capabilities require page password auth.
+
+By default agent:doctor is read-only and non-billable. Billable generate/edit smoke checks require --allow-billable.`);
 }
 
-function main() {
+async function main() {
     const options = parseArgs(process.argv.slice(2));
     if (options.help) {
         printHelp();
         return;
     }
 
+    const baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || DEFAULT_BASE_URL);
+    const contract = runContractCheck();
+    const capabilities = await readJsonLayer('capabilities', `${baseUrl}/api/agent/capabilities`, options.timeoutMs);
+    const runtime = await readJsonLayer('runtime', `${baseUrl}/api/runtime-capabilities`, options.timeoutMs);
+    const smoke = options.allowBillable ? runBillableSmoke(options) : buildSkippedSmoke(options);
+    const layers = buildLayers({ capabilities, runtime, contract, smoke });
+
+    printJson({
+        ok: layers.every((layer) => layer.ok || layer.skipped),
+        command: 'agent:doctor',
+        billable: options.allowBillable,
+        base_url: redactBaseUrl(baseUrl),
+        layers,
+        summary: buildSummary({ capabilities, runtime, contract, smoke })
+    });
+    if (layers.some((layer) => !layer.ok && !layer.skipped)) process.exit(1);
+}
+
+function runContractCheck() {
     const result = runCommand(process.execPath, buildAgentDoctorArgs(), {
         env: { ...process.env, GPT_IMAGE_AGENT_CONTRACT_CHECK: '1' },
         timeoutMs: AGENT_DOCTOR_TIMEOUT_MS
     });
     if (!result.ok) {
-        printJson({ ok: false, command: 'agent:doctor', output: pickFailureOutput(result) });
-        process.exit(1);
+        return { ok: false, output: pickFailureOutput(result), elapsed_ms: result.elapsed_ms };
+    }
+    return {
+        ok: true,
+        elapsed_ms: result.elapsed_ms,
+        body: result.stdout ? parseJsonPayload(result.stdout, 'agent contract check') : {}
+    };
+}
+
+async function readJsonLayer(name, url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { headers: authHeaders(), signal: controller.signal });
+        const text = await response.text();
+        if (!response.ok) throw new Error(`${safePathname(url)} failed with HTTP ${response.status}${formatBodySnippet(text)}`);
+        return { ok: true, body: text ? JSON.parse(text) : {} };
+    } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error), name };
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+function buildSkippedSmoke(options) {
+    return {
+        ok: true,
+        skipped: true,
+        reason: 'requires --allow-billable',
+        checks: [
+            { name: 'generate_1k', skipped: true, reason: 'requires --allow-billable' },
+            {
+                name: 'edit_1k',
+                skipped: true,
+                reason: options.editImage ? 'requires --allow-billable' : 'requires --allow-billable and --edit-image'
+            },
+            {
+                name: 'page_sse_edit_2k',
+                skipped: true,
+                reason: options.editImage ? 'requires --allow-billable' : 'requires --allow-billable and --edit-image'
+            }
+        ]
+    };
+}
+
+function runBillableSmoke(options) {
+    const checks = [
+        runSmokeCommand('generate_1k', [
+            GENERATE_SCRIPT,
+            '--allow-billable',
+            '--agent',
+            '--timeout-ms',
+            String(options.timeoutMs),
+            '--size',
+            '1024x1024',
+            '--quality',
+            'low',
+            '--idempotency-key',
+            `agent-doctor-generate-${Date.now()}`,
+            'agent doctor 1k generate smoke'
+        ])
+    ];
+    if (options.editImage) {
+        checks.push(
+            runSmokeCommand('edit_1k', [
+                EDIT_SCRIPT,
+                '--allow-billable',
+                '--agent',
+                '--timeout-ms',
+                String(options.timeoutMs),
+                '--size',
+                '1024x1024',
+                '--quality',
+                'low',
+                '--idempotency-key',
+                `agent-doctor-edit-${Date.now()}`,
+                options.editImage,
+                'agent doctor 1k edit smoke'
+            ])
+        );
+        checks.push(
+            runSmokeCommand('page_sse_edit_2k', [
+                EDIT_SCRIPT,
+                '--allow-billable',
+                '--page-sse',
+                '--timeout-ms',
+                String(options.timeoutMs),
+                '--size',
+                '2048x2048',
+                '--quality',
+                'low',
+                '--idempotency-key',
+                `agent-doctor-page-sse-edit-${Date.now()}`,
+                options.editImage,
+                'agent doctor 2k page SSE edit smoke'
+            ])
+        );
+    } else {
+        checks.push({ name: 'edit_1k', ok: true, skipped: true, reason: 'requires --edit-image' });
+        checks.push({ name: 'page_sse_edit_2k', ok: true, skipped: true, reason: 'requires --edit-image' });
     }
+    return { ok: checks.every((check) => check.ok || check.skipped), skipped: false, checks };
+}
+
+function runSmokeCommand(name, args) {
+    const result = runCommand(process.execPath, args, {
+        env: process.env,
+        timeoutMs: AGENT_DOCTOR_TIMEOUT_MS
+    });
+    return {
+        name,
+        ok: result.ok,
+        elapsed_ms: result.elapsed_ms,
+        ...(result.ok ? {} : { output: pickFailureOutput(result) })
+    };
+}
+
+function buildLayers({ capabilities, runtime, contract, smoke }) {
+    return [
+        {
+            name: 'capabilities',
+            ok: capabilities.ok,
+            endpoint: '/api/agent/capabilities',
+            ...(capabilities.ok ? summarizeCapabilities(capabilities.body) : { error: capabilities.error })
+        },
+        {
+            name: 'contract_check',
+            ok: contract.ok,
+            billable: false,
+            ...(contract.ok ? { checks: contract.body.checks || [] } : { error: contract.output })
+        },
+        {
+            name: 'runtime_backend',
+            ok: runtime.ok,
+            endpoint: '/api/runtime-capabilities',
+            ...(runtime.ok ? summarizeRuntime(runtime.body) : { error: runtime.error })
+        },
+        {
+            name: 'state_backend',
+            ok: capabilities.ok,
+            ...(capabilities.ok ? summarizeStateBackend(capabilities.body) : { error: capabilities.error })
+        },
+        {
+            name: 'responses_gpt2image_readiness',
+            ok: capabilities.ok && runtime.ok,
+            ...(capabilities.ok && runtime.ok
+                ? summarizeResponsesReadiness(capabilities.body, runtime.body)
+                : { error: 'requires capabilities and runtime layers' })
+        },
+        {
+            name: 'billable_smoke',
+            ok: smoke.ok,
+            skipped: smoke.skipped,
+            checks: smoke.checks,
+            ...(smoke.reason ? { reason: smoke.reason } : {})
+        }
+    ];
+}
+
+function summarizeCapabilities(body) {
+    return {
+        page_sse: body?.agent_streaming?.page_sse?.supported === true,
+        agent_jobs: body?.agent_jobs?.supported === true,
+        routing_rules: Boolean(body?.routing_rules),
+        executable_routing_rules: Boolean(body?.routing_rules?.high_resolution_edit?.conditions)
+    };
+}
+
+function summarizeRuntime(body) {
+    return {
+        default_stream_mode: body?.streaming?.defaultMode,
+        streaming_unavailable_scope: body?.streaming?.unavailableMarkScope,
+        responses_image_backend: body?.responsesImageBackend?.enabled === true,
+        streaming_batch_enabled: body?.streamingBatch?.enabled === true
+    };
+}
+
+function summarizeStateBackend(body) {
+    return {
+        backend: body?.defaults?.state_backend,
+        image_storage_mode: body?.storage?.image_storage_mode,
+        postgres_configured: body?.storage?.postgres_configured === true
+    };
+}
+
+function summarizeResponsesReadiness(capabilities, runtime) {
+    const requirements = capabilities?.supported?.image_backend_requirements?.['responses-image-generation'];
+    return {
+        backend_supported: requirements?.supported === true,
+        backend_enabled: requirements?.enabled === true,
+        runtime_enabled: runtime?.responsesImageBackend?.enabled === true,
+        missing_env: requirements?.missing_env || [],
+        gpt2image_real_smoke_case: 'gpt2image-responses-sse',
+        real_smoke_gate:
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+    };
+}
+
+function buildSummary({ capabilities, runtime, contract, smoke }) {
+    return {
+        capabilities: capabilities.ok ? 'ok' : 'failed',
+        contract_check: contract.ok ? 'ok' : 'failed',
+        runtime: runtime.ok ? 'ok' : 'failed',
+        state_backend: capabilities.ok ? capabilities.body?.defaults?.state_backend : 'unknown',
+        responses_gpt2image_ready:
+            capabilities.ok && runtime.ok
+                ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true &&
+                  runtime.body?.responsesImageBackend?.enabled === true
+                : false,
+        billable_smoke: smoke.skipped ? 'skipped' : smoke.ok ? 'ok' : 'failed'
+    };
+}
+
+function authHeaders() {
+    if (process.env.GPT_IMAGE_AGENT_TOKEN) return { Authorization: `Bearer ${process.env.GPT_IMAGE_AGENT_TOKEN}` };
+    if (process.env.GPT_IMAGE_APP_PASSWORD_HASH) return { 'X-App-Password-Hash': process.env.GPT_IMAGE_APP_PASSWORD_HASH };
+    return {};
+}
+
+function readOptionValue(argv, index, name) {
+    const value = argv[index];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value.`);
+    return value;
+}
+
+function readPositiveInteger(value, name) {
+    if (!/^\d+$/.test(String(value))) throw new Error(`${name} must be a positive integer.`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${name} must be a positive integer.`);
+    return parsed;
+}
+
+function normalizeBaseUrl(value) {
+    const normalized = String(value || '').trim().replace(/\/+$/, '');
+    const parsed = new URL(normalized);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('base URL must use http or https.');
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error('base URL must not include credentials, query parameters, or fragments.');
+    }
+    return normalized;
+}
+
+function redactBaseUrl(value) {
+    const parsed = new URL(value);
+    return `${parsed.protocol}//${parsed.host}`;
+}
+
+function safePathname(url) {
+    try {
+        return new URL(url).pathname;
+    } catch {
+        return String(url);
+    }
+}
 
-    const body = result.stdout ? parseJsonPayload(result.stdout, 'agent contract check') : {};
-    printJson({ ok: true, command: 'agent:doctor', contract: body });
+function formatBodySnippet(text) {
+    return text ? `: ${text.slice(0, 100)}` : '';
 }
 
 try {
-    if (isMainModule(import.meta.url, process.argv[1])) main();
+    if (isMainModule(import.meta.url, process.argv[1])) await main();
 } catch (error) {
     printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
     process.exit(1);

scripts/command-center.test.mjs

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
 import { createServer } from 'node:http';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
@@ -318,6 +319,101 @@ describe('Command center scripts', () => {
         assert.deepEqual(args.slice(1), ['--contract-check', '--timeout-ms', '60000', 'contract check']);
     });
 
+    it('reports layered agent:doctor diagnostics without billable smoke by default', async () => {
+        await withServer(
+            (request, response) => {
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            defaults: { state_backend: 'memory' },
+                            storage: { image_storage_mode: 'indexeddb', postgres_configured: false },
+                            agent_streaming: {
+                                page_sse: { supported: true }
+                            },
+                            agent_jobs: { supported: true },
+                            routing_rules: {
+                                high_resolution_edit: {
+                                    conditions: { operation: 'edit', max_edge: { operator: 'gt', value: 2048 } }
+                                }
+                            },
+                            supported: {
+                                image_backend_requirements: {
+                                    'responses-image-generation': {
+                                        supported: true,
+                                        enabled: true,
+                                        missing_env: []
+                                    }
+                                }
+                            }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/runtime-capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            streaming: {
+                                defaultMode: 'auto',
+                                unavailableMarkScope: 'channel+backend+strategy+operation'
+                            },
+                            streamingBatch: { enabled: true },
+                            responsesImageBackend: { enabled: true, mode: 'experimental' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(400, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            error: {
+                                code: 'idempotency_key_required',
+                                message: 'missing key',
+                                retryable: false
+                            }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/jobs/images/generate') {
+                    response.writeHead(400, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            error: {
+                                code: 'idempotency_key_required',
+                                message: 'missing key',
+                                retryable: false
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runNodeCommandAsync(['scripts/agent-doctor.mjs'], {
+                    env: { ...process.env, GPT_IMAGE_PLAYGROUND_URL: baseUrl },
+                    timeoutMs: 15_000
+                });
+
+                assert.equal(result.ok, true);
+                const body = parseJsonPayload(result.stdout, 'agent doctor');
+                assert.equal(body.ok, true);
+                assert.equal(body.billable, false);
+                assert.equal(body.summary.capabilities, 'ok');
+                assert.equal(body.summary.runtime, 'ok');
+                assert.equal(body.summary.state_backend, 'memory');
+                assert.equal(body.summary.responses_gpt2image_ready, true);
+                assert.equal(body.summary.billable_smoke, 'skipped');
+                assert.equal(body.layers.find((layer) => layer.name === 'billable_smoke').skipped, true);
+                assert.equal(body.layers.find((layer) => layer.name === 'capabilities').executable_routing_rules, true);
+            }
+        );
+    });
+
     it('preserves raw child output for command consumers', () => {
         const result = runCommand(process.execPath, ['-e', 'process.stdout.write(" M README.md\\n")']);
 
@@ -427,3 +523,53 @@ describe('Command center scripts', () => {
         });
     });
 });
+
+async function withServer(handler, run) {
+    const server = createServer(handler);
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    try {
+        assert.equal(typeof address, 'object');
+        assert.ok(address);
+        await run(`http://127.0.0.1:${address.port}`);
+    } finally {
+        await new Promise((resolve) => server.close(resolve));
+    }
+}
+
+function runNodeCommandAsync(args, options = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, args, {
+            cwd: process.cwd(),
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        const startedAt = Date.now();
+        const timeout = options.timeoutMs
+            ? setTimeout(() => {
+                  child.kill('SIGTERM');
+              }, options.timeoutMs)
+            : undefined;
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('close', (status, signal) => {
+            if (timeout) clearTimeout(timeout);
+            resolve({
+                ok: status === 0,
+                status,
+                signal,
+                stdout,
+                stderr,
+                elapsed_ms: Date.now() - startedAt
+            });
+        });
+    });
+}

scripts/keepalive-hf-space.mjs

@@ -6,6 +6,9 @@ import { validateSpaceUrl } from './hf-space-doctor-utils.mjs';
 const DEFAULT_SPACE_URL = 'https://misonl-gpt-image-playground-customer.hf.space';
 const DEFAULT_KEEPALIVE_PATH = '/api/auth-status';
 const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 1;
+const DEFAULT_RETRY_DELAY_MS = 5_000;
+
 function normalizeUrl(rawUrl, path) {
     const urlError = validateSpaceUrl(rawUrl);
     if (urlError) {
@@ -34,18 +37,36 @@ async function readJsonResponse(response) {
     }
 }
 
-async function pingKeepaliveEndpoint() {
+function readKeepaliveConfig() {
     const spaceUrl = process.env.HF_SPACE_KEEPALIVE_URL?.trim() || DEFAULT_SPACE_URL;
     const path = process.env.HF_SPACE_KEEPALIVE_PATH?.trim() || DEFAULT_KEEPALIVE_PATH;
     const timeoutMs = readPositiveIntegerEnv('HF_SPACE_KEEPALIVE_TIMEOUT_MS', DEFAULT_TIMEOUT_MS, 1_000);
+    const maxAttempts = readPositiveIntegerEnv('HF_SPACE_KEEPALIVE_MAX_ATTEMPTS', DEFAULT_MAX_ATTEMPTS);
+    const retryDelayMs = readPositiveIntegerEnv('HF_SPACE_KEEPALIVE_RETRY_DELAY_MS', DEFAULT_RETRY_DELAY_MS);
     const expectedPasswordRequired = readExpectedPasswordRequired();
     const url = normalizeUrl(spaceUrl, path);
+
+    return { url, timeoutMs, maxAttempts, retryDelayMs, expectedPasswordRequired };
+}
+
+function formatKeepaliveError(error, timeoutMs) {
+    if (error?.name === 'AbortError') {
+        return `Keepalive request timed out after ${timeoutMs}ms`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+
+async function waitBeforeRetry(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function pingKeepaliveEndpointOnce(config, attemptLabel) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
     const startedAt = Date.now();
 
     try {
-        const response = await fetch(url, {
+        const response = await fetch(config.url, {
             headers: {
                 'User-Agent': 'gpt-image-playground-keepalive/1.0'
             },
@@ -57,18 +78,22 @@ async function pingKeepaliveEndpoint() {
         if (!response.ok) {
             throw new Error(`Keepalive endpoint failed with HTTP ${response.status}`);
         }
-        if (expectedPasswordRequired !== undefined && body?.passwordRequired !== expectedPasswordRequired) {
-            throw new Error(`passwordRequired expected ${expectedPasswordRequired}, got ${body?.passwordRequired}`);
+        if (
+            config.expectedPasswordRequired !== undefined &&
+            body?.passwordRequired !== config.expectedPasswordRequired
+        ) {
+            throw new Error(`passwordRequired expected ${config.expectedPasswordRequired}, got ${body?.passwordRequired}`);
         }
 
         console.log(
             JSON.stringify(
                 {
                     ok: true,
-                    url,
+                    url: config.url,
                     status: response.status,
                     elapsedMs,
-                    passwordRequired: body?.passwordRequired
+                    passwordRequired: body?.passwordRequired,
+                    attempt: attemptLabel
                 },
                 null,
                 2
@@ -79,16 +104,41 @@ async function pingKeepaliveEndpoint() {
     }
 }
 
+async function pingKeepaliveEndpoint() {
+    const config = readKeepaliveConfig();
+    let lastError;
+
+    for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
+        try {
+            const attemptLabel = `${attempt}/${config.maxAttempts}`;
+            await pingKeepaliveEndpointOnce(config, attemptLabel);
+            return;
+        } catch (error) {
+            lastError = error;
+            console.error(
+                JSON.stringify(
+                    {
+                        ok: false,
+                        attempt: `${attempt}/${config.maxAttempts}`,
+                        error: formatKeepaliveError(error, config.timeoutMs)
+                    },
+                    null,
+                    2
+                )
+            );
+            if (attempt < config.maxAttempts) {
+                await waitBeforeRetry(config.retryDelayMs);
+            }
+        }
+    }
+
+    throw new Error(`Keepalive attempt already reported: ${formatKeepaliveError(lastError, config.timeoutMs)}`);
+}
+
 pingKeepaliveEndpoint().catch((error) => {
-    console.error(
-        JSON.stringify(
-            {
-                ok: false,
-                error: error instanceof Error ? error.message : String(error)
-            },
-            null,
-            2
-        )
-    );
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.startsWith('Keepalive attempt already reported: ')) {
+        console.error(JSON.stringify({ ok: false, error: message }, null, 2));
+    }
     process.exit(1);
 });

scripts/keepalive-hf-space.test.mjs

@@ -1,11 +1,20 @@
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
-import { describe, it } from 'node:test';
+import { after, describe, it } from 'node:test';
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url));
 const scriptPath = join(repoRoot, 'scripts/keepalive-hf-space.mjs');
+const tempDirectories = [];
+
+after(() => {
+    for (const directory of tempDirectories) {
+        rmSync(directory, { recursive: true, force: true, maxRetries: 3 });
+    }
+});
 
 describe('HF Space keepalive script validation', () => {
     it('rejects non-integer timeout env values before network access', () => {
@@ -17,6 +26,15 @@ describe('HF Space keepalive script validation', () => {
         assert.equal(result.stdout.trim(), '');
     });
 
+    it('rejects non-integer retry attempt values before network access', () => {
+        const result = runKeepalive({ HF_SPACE_KEEPALIVE_MAX_ATTEMPTS: 'two' });
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /HF_SPACE_KEEPALIVE_MAX_ATTEMPTS/);
+        assert.match(result.stderr, /integer/);
+        assert.equal(result.stdout.trim(), '');
+    });
+
     it('rejects keepalive URLs with embedded credentials before network access', () => {
         const result = runKeepalive({ HF_SPACE_KEEPALIVE_URL: 'https://user:secret@example-demo.hf.space' });
 
@@ -26,12 +44,77 @@ describe('HF Space keepalive script validation', () => {
         assert.doesNotMatch(result.stderr, /secret/);
         assert.equal(result.stdout.trim(), '');
     });
+
+    it('retries failed keepalive attempts before reporting success', () => {
+        const preloadPath = writeFetchStub(`
+            let count = 0;
+            globalThis.fetch = async () => {
+                count += 1;
+                if (count === 1) {
+                    return new Response(JSON.stringify({ error: 'warming' }), {
+                        status: 503,
+                        headers: { 'Content-Type': 'application/json' }
+                    });
+                }
+                return new Response(JSON.stringify({ passwordRequired: true }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' }
+                });
+            };
+        `);
+        const result = runKeepalive(
+            {
+                HF_SPACE_KEEPALIVE_URL: 'https://misonl-gpt-image-playground-customer.hf.space',
+                HF_SPACE_KEEPALIVE_PATH: '/api/auth-status',
+                HF_SPACE_KEEPALIVE_MAX_ATTEMPTS: '2',
+                HF_SPACE_KEEPALIVE_RETRY_DELAY_MS: '1',
+                HF_SPACE_KEEPALIVE_TIMEOUT_MS: '1000'
+            },
+            ['--import', preloadPath]
+        );
+
+        assert.equal(result.status, 0);
+        assert.match(result.stderr, /"attempt": "1\/2"/);
+        assert.match(result.stdout, /"ok": true/);
+        assert.match(result.stdout, /"attempt": "2\/2"/);
+    });
+
+    it('prints a timeout-specific final error when every attempt aborts', () => {
+        const preloadPath = writeFetchStub(`
+            globalThis.fetch = async (url, options) =>
+                new Promise((resolve, reject) => {
+                    options.signal.addEventListener('abort', () => {
+                        reject(new DOMException('This operation was aborted', 'AbortError'));
+                    });
+                });
+        `);
+        const result = runKeepalive(
+            {
+                HF_SPACE_KEEPALIVE_MAX_ATTEMPTS: '1',
+                HF_SPACE_KEEPALIVE_TIMEOUT_MS: '1000'
+            },
+            ['--import', preloadPath]
+        );
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /Keepalive request timed out after 1000ms/);
+        assert.doesNotMatch(result.stderr, /This operation was aborted/);
+        assert.equal((result.stderr.match(/"ok": false/g) || []).length, 1);
+    });
 });
 
-function runKeepalive(env) {
-    return spawnSync(process.execPath, [scriptPath], {
+function runKeepalive(env, nodeArgs = []) {
+    return spawnSync(process.execPath, [...nodeArgs, scriptPath], {
         cwd: repoRoot,
         encoding: 'utf8',
         env: { ...process.env, ...env }
     });
 }
+
+function writeFetchStub(source) {
+    const directory = mkdtempSync(join(tmpdir(), 'hf-keepalive-fetch-'));
+    tempDirectories.push(directory);
+    const filePath = join(directory, 'fetch-stub.mjs');
+    writeFileSync(filePath, source);
+    return filePath;
+}

scripts/local-image-upstream-fixture.mjs

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url';
 export const FIXTURE_IMAGE_BASE64 =
     'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
 export const MAX_JSON_BODY_BYTES = 1024 * 1024;
+export const FIXTURE_IMAGE_PATH = '/api/storage/generations/fixture.png';
 
 class PayloadTooLargeError extends Error {
     constructor() {
@@ -75,6 +76,12 @@ function sendJson(response, status, body) {
     response.end(JSON.stringify(body));
 }
 
+function sendFixtureImage(response) {
+    const buffer = Buffer.from(FIXTURE_IMAGE_BASE64, 'base64');
+    response.writeHead(200, { 'Content-Type': 'image/png', 'Content-Length': String(buffer.byteLength) });
+    response.end(buffer);
+}
+
 function writeSse(response, event, payload) {
     if (event) response.write(`event: ${event}\n`);
     response.write(`data: ${JSON.stringify(payload)}\n\n`);
@@ -119,13 +126,20 @@ function sendResponsesStream(response) {
             id: 'ig_fixture',
             type: 'image_generation_call',
             status: 'completed',
-            result: FIXTURE_IMAGE_BASE64
+            result: FIXTURE_IMAGE_PATH
         }
     });
     writeSse(response, 'response.completed', {
         type: 'response.completed',
         response: {
-            output: [{ id: 'ig_fixture', type: 'image_generation_call', status: 'completed', result: FIXTURE_IMAGE_BASE64 }]
+            output: [
+                {
+                    id: 'ig_fixture',
+                    type: 'image_generation_call',
+                    status: 'completed',
+                    result: FIXTURE_IMAGE_PATH
+                }
+            ]
         }
     });
     response.end('data: [DONE]\n\n');
@@ -153,7 +167,7 @@ function responsesJsonResponse(body) {
         id: 'resp_fixture',
         object: 'response',
         model: typeof body.model === 'string' ? body.model : 'gpt-5.4',
-        output: [{ id: 'ig_fixture', type: 'image_generation_call', status: 'completed', result: FIXTURE_IMAGE_BASE64 }],
+        output: [{ id: 'ig_fixture', type: 'image_generation_call', status: 'completed', result: FIXTURE_IMAGE_PATH }],
         usage: {
             input_tokens: 1,
             output_tokens: 1,
@@ -182,6 +196,10 @@ async function handleRequest(request, response) {
         sendJson(response, 200, modelsResponse());
         return;
     }
+    if (request.method === 'GET' && url.pathname === FIXTURE_IMAGE_PATH) {
+        sendFixtureImage(response);
+        return;
+    }
     if (request.method === 'POST' && url.pathname === '/v1/images/generations') {
         const body = await readJsonBody(request);
         if (body.stream === true) {

scripts/local-image-upstream-fixture.test.mjs

@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-import { FIXTURE_IMAGE_BASE64, MAX_JSON_BODY_BYTES, createFixtureServer } from './local-image-upstream-fixture.mjs';
+import {
+    FIXTURE_IMAGE_BASE64,
+    FIXTURE_IMAGE_PATH,
+    MAX_JSON_BODY_BYTES,
+    createFixtureServer
+} from './local-image-upstream-fixture.mjs';
 
 describe('local image upstream fixture', () => {
     it('serves Images API JSON responses', async () => {
@@ -71,7 +76,11 @@ describe('local image upstream fixture', () => {
             const body = await response.json();
             assert.equal(body.id, 'resp_fixture');
             assert.equal(body.output[0].type, 'image_generation_call');
-            assert.equal(body.output[0].result, FIXTURE_IMAGE_BASE64);
+            assert.equal(body.output[0].result, FIXTURE_IMAGE_PATH);
+            const imageResponse = await fetch(`${fixture.baseUrl}${FIXTURE_IMAGE_PATH}`);
+            assert.equal(imageResponse.status, 200);
+            assert.match(imageResponse.headers.get('content-type') || '', /^image\/png\b/);
+            assert.equal(Buffer.from(await imageResponse.arrayBuffer()).toString('base64'), FIXTURE_IMAGE_BASE64);
         } finally {
             await fixture.close();
         }
@@ -105,8 +114,8 @@ describe('local image upstream fixture', () => {
             );
             assert.equal(events[0].data.partial_image_b64, FIXTURE_IMAGE_BASE64);
             assert.equal(events[1].data.item.type, 'image_generation_call');
-            assert.equal(events[1].data.item.result, FIXTURE_IMAGE_BASE64);
-            assert.equal(events[2].data.response.output[0].result, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[1].data.item.result, FIXTURE_IMAGE_PATH);
+            assert.equal(events[2].data.response.output[0].result, FIXTURE_IMAGE_PATH);
             assert.equal(events[3].done, true);
         } finally {
             await fixture.close();

scripts/smoke-image-upstream-local-final-gate.mjs

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
 import { commandFailureMessage, parseJsonPayload, printJson } from './command-center-utils.mjs';
 import { createFixtureServer } from './local-image-upstream-fixture.mjs';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const REAL_SMOKE_SCRIPT = fileURLToPath(new URL('./smoke-image-upstream-real.mjs', import.meta.url));
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LOCAL_FINAL_GATE_CASE_COUNT = 5;
 const LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS = 15_000;
+const MAX_LOCAL_FINAL_GATE_CASE_TIMEOUT_MS = Math.floor(
+    (Number.MAX_SAFE_INTEGER - LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS) / LOCAL_FINAL_GATE_CASE_COUNT
+);
 
 function parseArgs(argv) {
     const parsed = { help: false, timeoutMs: DEFAULT_TIMEOUT_MS };
@@ -66,17 +67,35 @@ async function main() {
 }
 
 function runLocalFinalGate(baseUrl, timeoutMs) {
+    const parentTimeoutMs = readLocalFinalGateParentTimeoutMs(timeoutMs);
     return runCommandAsync(
         process.execPath,
-        ['--import', 'tsx', REAL_SMOKE_SCRIPT, '--allow-billable', '--require-independent-targets', '--timeout-ms', String(timeoutMs)],
+        [
+            '--import',
+            'tsx',
+            REAL_SMOKE_SCRIPT,
+            '--allow-billable',
+            '--require-independent-targets',
+            '--timeout-ms',
+            String(timeoutMs)
+        ],
         {
             cwd: REPO_ROOT,
             env: buildLocalFinalGateEnv(baseUrl, timeoutMs),
-            timeoutMs: timeoutMs * LOCAL_FINAL_GATE_CASE_COUNT + LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS
+            timeoutMs: parentTimeoutMs
         }
     );
 }
 
+function readLocalFinalGateParentTimeoutMs(timeoutMs) {
+    if (timeoutMs > MAX_LOCAL_FINAL_GATE_CASE_TIMEOUT_MS) {
+        throw new Error(
+            `--timeout-ms 过大，local final gate 父进程超时会超过安全整数上限；最大允许 ${MAX_LOCAL_FINAL_GATE_CASE_TIMEOUT_MS}。`
+        );
+    }
+    return timeoutMs * LOCAL_FINAL_GATE_CASE_COUNT + LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS;
+}
+
 function runCommandAsync(command, args, options = {}) {
     const startedAt = Date.now();
     return new Promise((resolve) => {
@@ -197,7 +216,8 @@ function closeServer(server) {
 }
 
 function assertFinalGateReport(report) {
-    if (report?.final_gate_satisfied !== true) throw new Error('local final gate did not satisfy final_gate_satisfied=true');
+    if (report?.final_gate_satisfied !== true)
+        throw new Error('local final gate did not satisfy final_gate_satisfied=true');
     if (!Array.isArray(report.results) || report.results.length !== 5) {
         throw new Error('local final gate did not run all five independent upstream cases');
     }
@@ -227,6 +247,11 @@ function readArgValue(argv, index, flag) {
 function readTimeoutMs(value, source) {
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 1000) throw new Error(`${source} 必须是不小于 1000 的整数毫秒。`);
+    if (parsed > MAX_LOCAL_FINAL_GATE_CASE_TIMEOUT_MS) {
+        throw new Error(
+            `${source} 过大，local final gate 父进程超时会超过安全整数上限；最大允许 ${MAX_LOCAL_FINAL_GATE_CASE_TIMEOUT_MS}。`
+        );
+    }
     return parsed;
 }
 

scripts/smoke-image-upstream-local-final-gate.test.mjs

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url));
 const scriptPath = fileURLToPath(new URL('./smoke-image-upstream-local-final-gate.mjs', import.meta.url));
@@ -32,8 +32,14 @@ describe('local image upstream final gate smoke launcher', () => {
                 'gpt2image-responses-sse'
             ]
         );
-        assert.equal(report.results.every((item) => item.status === 200), true);
-        assert.equal(report.results.every((item) => item.first_b64_length === 92), true);
+        assert.equal(
+            report.results.every((item) => item.status === 200),
+            true
+        );
+        assert.equal(
+            report.results.every((item) => item.first_b64_length === 92),
+            true
+        );
     });
 
     it('prints help without starting the fixture', () => {
@@ -46,4 +52,17 @@ describe('local image upstream final gate smoke launcher', () => {
         assert.match(result.stdout, /smoke:image-upstream-local/);
         assert.match(result.stdout, /local fixture gate/);
     });
+
+    it('rejects unsafe parent timeout values before starting the fixture', () => {
+        const result = spawnSync(process.execPath, [scriptPath, '--timeout-ms', String(Number.MAX_SAFE_INTEGER)], {
+            cwd: repoRoot,
+            encoding: 'utf8'
+        });
+
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.ok, false);
+        assert.match(body.error, /父进程超时会超过安全整数上限/);
+    });
 });

skills/gpt-image-playground-agent/SKILL.md

@@ -1,34 +1,45 @@
 ---
 name: gpt-image-playground-agent
-description: 当用户需要通过 API 调用已部署的 GPT Image Playground 批量请求图片生成时使用；支持文字生成图片、文字加图片生成图片，并返回可下载图片产物、metadata、base64 或 job 结果。
+description: 当用户需要通过已部署的 GPT Image Playground 生成、编辑、批量生成或诊断图片接口时使用；必须优先运行本 Skill 内置 scripts/generate-image.mjs、edit-image.mjs、batch-images.mjs 或 probe-upstream-image.mjs，而不是临时编写 API 调用脚本。
 ---
 
 # GPT Image Playground Agent
 
-通过用户已部署的 GPT Image Playground `/api/agent/*` 接口生成或编辑图片。不要假设服务一定在本机；不要模拟网页表单；直接使用 Agent API 契约、幂等键和产物 URL。
+通过用户已部署的 GPT Image Playground 生成、编辑、批量处理或诊断图片接口。不要假设服务一定在本机；不要模拟网页表单；优先运行本 Skill 内置脚本，让脚本处理 Agent API 契约、capabilities、幂等键、路由选择和产物 URL。
 
-## 路由硬规则
+## 脚本优先规则
+
+- 生成单张或少量图片：优先运行 `scripts/generate-image.mjs`。
+- 编辑图片：优先运行 `scripts/edit-image.mjs`。
+- 批量 generate/edit：优先运行 `scripts/batch-images.mjs`，用 JSONL 输入和 append-only manifest 管理续跑。
+- 诊断上游图片接口：优先运行 `scripts/probe-upstream-image.mjs`。
+- 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
+- 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 `scripts/` 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
+- 先用 dry-run 或 `--contract-check` 检查请求、路由和鉴权；只有用户明确允许真实计费时才加 `--allow-billable`。
+
+## 路由规则
 
 - 先读取 `GET /api/agent/capabilities` 的 `routing_rules`，按机器可读规则选择端点。
-- `edit` 且 `max(width,height)>2048` 时，必须使用页面端 `POST /api/images` form-data SSE 路径，不要走非流式 `/api/agent/images/edit`。
-- 复杂 UI 批量出图优先使用页面端 `POST /api/images` SSE，并记录切换原因、失败清单和续跑锚点。
+- `edit` 且 `max(width,height)>2048` 时，默认优先使用页面端 `POST /api/images` form-data SSE 路径；如果页面流式不可用或失败，先诊断结构化错误，再显式回退到 Agent edit。
+- 复杂 UI 批量出图优先使用页面端 `POST /api/images` SSE；需要并发时显式设置 `--concurrency N` 或页面“并发批量”开关，并记录切换原因、失败清单和续跑锚点。
 - 长图恢复或需要续跑锚点的生产请求优先使用页面端 `POST /api/images` SSE，保留局部进度和缺最终图诊断。
 - 普通小图单次文生图使用 `/api/agent/images/generate`；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE，流式失败后先诊断，再显式选择 Agent JSON 或 job 路径，不自动回退。
 - 同一个已进入终态 `failed` 的 `Idempotency-Key` 只会回放失败；重新尝试必须先诊断原因，再创建新的业务操作和新的 key。
 
 ## 执行流程
 
-1. 先定位服务基础地址。优先使用用户明确提供的 URL；其次使用 `GPT_IMAGE_PLAYGROUND_URL`；都没有时尝试默认地址 `http://localhost:4783`。
-2. 用候选基础地址请求 `GET /api/agent/capabilities`。如果默认地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，向用户询问实际部署地址、端口、域名和是否需要鉴权。
-3. 读取 capabilities 中的认证方式、模型、模型级限制、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
-4. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
-5. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点对外始终返回最终 `AgentImageResponse` JSON；如 capabilities 声明 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用内部上游 SSE 消费。
-6. 图片编辑使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段使用 `image_0..image_9`。该 Agent 端点同样是非流式端点。
-7. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
-8. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、��图单次文生图、复杂 UI 批量、长图恢复或明确诊断后切换。
-9. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
-10. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
-11. 返回结果时优先给出 `content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。
+1. 先按任务类型选择内置脚本，不要从零写 API 调用代码。
+2. 定位服务基础地址。优先使用用户明确提供的 URL；其次使用 `GPT_IMAGE_PLAYGROUND_URL`；都没有时尝试默认地址 `http://localhost:4783`。
+3. 让脚本请求 `GET /api/agent/capabilities`。如果默认地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，向用户询问实际部署地址、端口、域名和是否需要鉴权。
+4. 读取 capabilities 中的认证方式、模型、模型级限制、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
+5. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
+6. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点对外始终返回最终 `AgentImageResponse` JSON；如 capabilities 声明 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images` 控制内部上游 SSE 消费。
+7. 图片编辑使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段必须使用 `image_0..image_9`，类似 `image_10`、`image_01` 或 `image_foo` 的字段会被显式拒绝。该 Agent 端点同样是非流式端点；上游 SSE 字段按 `agent_streaming.upstream_sse.request_fields_by_mode.edit` 发送，不要给 edit 传 `image_backend`。
+8. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
+9. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复或明确诊断后切换。
+10. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
+11. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
+12. 返回结果时优先给出 `content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。
 
 ## 鉴权
 
@@ -45,6 +56,8 @@ Authorization: Bearer <token>
 ## 调用约束
 
 - 不要把 API Key、token 或访问码写入源码、文档示例、日志或测试快照。
+- Skill 必须保持自包含和可迁移：脚本、示例和说明不得写入本机绝对路径或仓库绝对路径；运行脚本时以当前已安装 Skill 目录为根解析 `scripts/`，不要依赖某台机器上的 checkout 位置。
+- Skill 必须兼容 Windows、Linux 和 macOS：脚本只用 Node.js 20+ 与跨平台 `node:` 标准库；文档示例用 `node "<skill-root>/scripts/..."`，不依赖 bash、sh、chmod、可执行位、POSIX inline env 或反斜杠续行。
 - 不要把 `localhost:4783` 当作唯一部署位置；它只是无明确地址时的探测默认值。
 - 不要在模型上下文中展开大体积 base64，除非用户明确要求。
 - 不要把 `error.message` 当成唯一判断依据；稳定分支以 `error.code` 和 HTTP 状态为准。
@@ -69,11 +82,15 @@ Authorization: Bearer <token>
 
 ## 可用脚本
 
-- `skills/gpt-image-playground-agent/scripts/generate-image.mjs`：JSON 文生图调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实生图。
-- `skills/gpt-image-playground-agent/scripts/edit-image.mjs`：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。
-- `skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
+以下脚本都位于当前 Skill 目录的 `scripts/` 下。不要硬编码本机安装路径；由运行环境按当前 `SKILL.md` 所在目录解析脚本路径。
+
+- `scripts/generate-image.mjs`：JSON 文生图调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实生图。
+- `scripts/edit-image.mjs`：multipart 编���调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。
+- `scripts/batch-images.mjs`：JSONL 批量 generate/edit 调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实执行，支持 append-only manifest、`--resume`、`--ordered-prefix`、`--dimension-check`、`--max-attempts`、`--concurrency` 和顺序执行下的 `--max-consecutive-failures`。`--concurrency` 默认 `1`，大于 `1` 时并发执行并按输入顺序输出结果。
+- `scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
 
 生成和编辑脚本的 dry-run 输出会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。
+所有脚本在 dry-run 或真实请求前都会校验尺寸参数。`gpt-image-2` 支持 `auto` 或 `WIDTHxHEIGHT`，且宽高必须为 `16` 的倍数、单边不超过 `3840`、宽高比不超过 `3:1`。最低分辨率按总像素 `min_pixels=655360` 判断，最高分辨率同时受 `max_pixels=8294400` 和 `max_edge=3840` 约束。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
 
@@ -82,53 +99,62 @@ Authorization: Bearer <token>
 - `npm run verify`：运行提交前基线；需要真实 PostgreSQL gate 时加 `-- --postgres`。
 - `npm run deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。
 - `npm run deploy:space`：部署干净 git HEAD 到固定 Space，并做只读公网验证。
-- `npm run agent:doctor`：执行只读 Agent API 契约检查，不触发真实生图。
+- `npm run agent:doctor`：执行非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend 和 Responses/GPT2Image readiness；真实 1K/2K smoke 必须显式加 `-- --allow-billable`。
 
 生成脚本常用参数：
 
-```bash
-node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
-  --size 2048x2048 \
-  --quality high \
-  --response-mode path \
-  --idempotency-key stable-operation-key \
-  "a product photo of a ceramic mug"
+```text
+node "<skill-root>/scripts/generate-image.mjs" --size 2048x2048 --quality high --response-mode path --idempotency-key stable-operation-key "a product photo of a ceramic mug"
 ```
 
 启用 Agent 内部上游 SSE 时，必须显式传策略字段；脚本仍只输出最终 JSON：
 
-```bash
-node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
-  --allow-billable \
-  --image-backend images-api \
-  --streaming-strategy newapi-keepalive-sse \
-  --partial-images 2 \
-  --size 4096x4096 \
-  --quality high \
-  "a product photo of a ceramic mug"
+```text
+node "<skill-root>/scripts/generate-image.mjs" --allow-billable --image-backend images-api --stream-mode auto --streaming-strategy newapi-keepalive-sse --partial-images 2 --size 3840x2160 --quality high "a product photo of a ceramic mug"
 ```
 
 真实生图必须显式开启：
 
-```bash
-node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
-  --allow-billable \
-  --timeout-ms 420000 \
-  --size 2048x2048 \
-  "a product photo of a ceramic mug"
+```text
+node "<skill-root>/scripts/generate-image.mjs" --allow-billable --timeout-ms 420000 --size 2048x2048 "a product photo of a ceramic mug"
 ```
 
-生成脚本会对 `max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE；如果 capabilities 未声明 `agent_streaming.page_sse.supported=true`，脚本会显式失败，不会静默降级到 Agent JSON。如果页面流式失败，脚本会返回结构化失败结果，先诊断再决定是否用 `--agent` 或 `--job` 重新执行，不会自动发起第二次请求。也可以用 `--page-sse` 强制页面流式，或用 `--agent` 强制非流式 Agent generate，`--job` 仍可显式选择 job 路径。上游流式字段支持 `--image-backend`、`--streaming-strategy`、`--partial-images`；默认不发送这些字段，保持服务端默认非流式基线。
+生成脚本会对 `max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE；如果 capabilities 未声明 `agent_streaming.page_sse.supported=true`，脚本会显式失败，不会静默降级到 Agent JSON。如果页面流式失败，脚本会返回结构化失败结果，先诊断再决定是否用 `--agent` 或 `--job` 重新执行，不会自动发起第二次请求。编辑脚本对高分辨率 edit 也采用同样口径：默认页面流式，有问题再显式回退到 Agent edit 诊断或执行。也可以用 `--page-sse` 强制页面流式，或用 `--agent` 强制 Agent generate/edit 最终 JSON，`--job` 仍可显式选择 generate job 路径。显式传 `--streaming-strategy off` 或 `--stream-mode non_stream` 时，大图请求保持 Agent JSON 非流式路径，用于和页面 SSE 做诊断对照。上游流式字段优先读取 `agent_streaming.upstream_sse.request_fields_by_mode`：generate 支持 `--image-backend`、`--stream-mode`、`--streaming-strategy`、`--partial-images`；edit 只支持 `--stream-mode`、`--streaming-strategy`、`--partial-images`。不发送时使用服务端 capabilities 声明的默认值。
 
-编辑脚本支持 `--model`、`--size`、`--quality`、`--response-mode`、`--timeout-ms`、`--idempotency-key`、`--dry-run` 和 `--allow-billable`。
+批量脚本 JSONL 每行是一个 generate 或 edit 任务。示例：
+
+```jsonl
+{"id":"hero-01","mode":"generate","prompt":"a product photo of a ceramic mug","size":"1024x1024","response_mode":"path"}
+{"id":"edit-01","mode":"edit","prompt":"replace the background","image_path":"./source.png","size":"1024x1024","response_mode":"path"}
+```
+
+默认 dry-run 只解析 JSONL、生成稳定幂等键并输出计划，不请求服务：
+
+```text
+node "<skill-root>/scripts/batch-images.mjs" --input tasks.jsonl --ordered-prefix product-set
+```
+
+真实批量执行必须显式允许计费。需要并发时添加 `--concurrency N`；需要严格连续失败熔断时保持 `--concurrency 1`：
+
+```text
+node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --max-consecutive-failures 3
+node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --concurrency 3
+```
+
+`--manifest` 使用 JSONL append-only 记录每条任务的 `index`、`id`、`idempotency_key`、`attempt`、`status`、响应或错误；`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会并发执行任务并按输入顺序输出结果。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存，便于区分上游未给终图和解析/断流问题。
+
+批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径；edit 任务使用这些高级字段会显式走 `/api/images`，因为 Agent JSON edit 不接收它们。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。
+
+编辑脚本支持 `--model`、`--size`、`--quality`、`--response-mode`、`--stream-mode`、`--streaming-strategy`、`--partial-images`、`--timeout-ms`、`--idempotency-key`、`--page-sse`、`--agent`、`--dry-run` 和 `--allow-billable`。
 
 直连上游诊断：
 
-```bash
-OPENAI_API_KEY=... node skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs \
-  --base-url https://api.openai.com/v1
+```text
+node "<skill-root>/scripts/probe-upstream-image.mjs" --base-url https://api.openai.com/v1
 ```
 
+调用前按当前系统和 shell 设置 `OPENAI_API_KEY` 或 `GPT_IMAGE_UPSTREAM_API_KEY`，不要把 key 写进命令历史或文档。
+
 诊断脚本只输出状态、耗时、脱敏错误摘要、白名单响应头和 base64 长度，不输出 API key 或完整图片数据。
 
 上游探针脚本支持 `--base-url`、`--model`、`--prompt`、`--size`、`--quality`、`--format`、`--timeout-ms` 和 `--allow-billable`。默认读取 `GPT_IMAGE_UPSTREAM_BASE_URL` 或 `OPENAI_API_BASE_URL`，API Key 读取 `GPT_IMAGE_UPSTREAM_API_KEY` 或 `OPENAI_API_KEY`。上游 base URL 同样必须是无凭据、无查询参数、无片段的 `http`/`https` 绝对 URL。

skills/gpt-image-playground-agent/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "GPT Image Agent API"
-  short_description: "定位部署地址后调用 Agent API 生成和编辑图片"
-  default_prompt: "使用 $gpt-image-playground-agent 先确认 GPT Image Playground 服务地址，再通过 Agent API 生成或编辑图片并返回产物 URL 和关键元数据。"
+  short_description: "使用内置脚本调用图片 Agent API"
+  default_prompt: "使用 $gpt-image-playground-agent 先选择并运行内置脚本，不要临时编写 API 调用脚本。"

skills/gpt-image-playground-agent/references/api.md

@@ -12,17 +12,23 @@
 
 ## 辅助脚本
 
-- `skills/gpt-image-playground-agent/scripts/generate-image.mjs`：JSON 文生图调用。
-- `skills/gpt-image-playground-agent/scripts/edit-image.mjs`：multipart 编辑调用。
-- `skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs`：上游图片接口连通性探针。
+脚本位于当前 Skill 目录的 `scripts/` 下。不要硬编码本机安装路径或仓库 checkout 路径；由运行环境按当前 `SKILL.md` 所在目录解析脚本路径。
+脚本必须通过 `node "<skill-root>/scripts/..."` 调用，以兼容 Windows、Linux 和 macOS；示例不要依赖 bash、sh、chmod、可执行位、POSIX inline env 或反斜杠续行。
+生成、编辑、批量和上游诊断都应先使用这些内置脚本；不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现同一套 API 调用。
 
-生成和编辑脚本默认只做 dry-run，不触发真实生图或编辑。必须显式添加 `--allow-billable` 才会调用 `/api/agent/images/generate` 或 `/api/agent/images/edit`。
+- `scripts/generate-image.mjs`：JSON 文生图调用。
+- `scripts/edit-image.mjs`：multipart 编辑调用。
+- `scripts/batch-images.mjs`：JSONL 批量 generate/edit 调用。
+- `scripts/probe-upstream-image.mjs`：上游图片接口连通性探针。
+
+生成、编辑和批量脚本默认只做 dry-run，不触发真实生图或编辑。必须显式添加 `--allow-billable` 才会按 capabilities 路由规则调用 `/api/agent/images/generate`、`/api/agent/images/edit`、`/api/agent/jobs/images/generate` 或页面端 `/api/images` SSE。
 上游探针默认只检查 DNS、TLS 和 `/models`，必须显式添加 `--allow-billable` 才会调用上游 `/images/generations`。
 脚本支持 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 或 `--contract-check` 做只读契约检查，不触发真实生图或编辑。
 Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，Agent 端点才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。页面端 `/api/images` SSE 另看 `agent_streaming.page_sse.auth`；当其声明 `required=true` 时，form-data 必须包含 `passwordHash`。
 当服务返回相对 `content_url`、`metadata_url` 或页面 SSE `path` 时，辅助脚本会额外输出 `absolute_content_url`、`absolute_metadata_url` 或 `absolute_path`。
 同一个 `Idempotency-Key` 如果已经进入终态 `failed`，再次调用 generate/edit 或 job result/status 只会回放该失败，且 `retryable=false`。需要重新尝试时应创建新的业务操作和新的 `Idempotency-Key`。
 页面端 `/api/images` SSE 会把同一个业务 key 复用到 `clientRequestId`，因此脚本使用的 `Idempotency-Key` 不能超过 capabilities 中 `agent_streaming.page_sse.client_request_id.max_length` 声明的字符数；超长时会直接报错，不会静默截断。
+脚本会在 dry-run 和真实请求前前置校验 `--size` 或 JSONL `size`。`gpt-image-2` 支持 `auto` 或 `WIDTHxHEIGHT`，且宽高必须为 `16` 的倍数、单边不超过 `3840`、宽高比不超过 `3:1`。最低分辨率按总像素 `min_pixels=655360` 判断，最高分辨率同时受 `max_pixels=8294400` 和 `max_edge=3840` 约束。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。
 
 生成脚本参数：
 
@@ -32,23 +38,65 @@ Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API
 - `--n`：默认 `1`。
 - `--format`：默认 `png`，`jpg` 会规范化为 `jpeg`。
 - `--response-mode`：默认 `path`。
+- `--image-backend`：可选，显式选择 `images-api`、`images`、`responses` 或 `responses-image-generation`。
+- `--stream-mode`：可选，显式选择 `auto`、`stream` 或 `non_stream`。
+- `--streaming-strategy`：可选，显式选择 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse` 或 `force-sse`。
+- `--partial-images`：可选，显式设置上游 SSE partial image 数量，范围 `1` 到 `3`。
 - `--timeout-ms`：默认 `420000`。
 - `--prompt-file`：从文本文件读取 prompt。
 - `--idempotency-key`：指定稳定幂等键。
+- `--page-sse`：强制使用页面端 `/api/images` form-data SSE。
+- `--agent`：强制使用 `/api/agent/images/generate` 非流式 JSON。
+- `--job`：强制使用 Agent job polling。
 - `--dry-run`：只输出将要发送的 JSON。
 - `--allow-billable`：允许真实调用生图端点。
 
+`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE；如果显式传 `--streaming-strategy off`，即使是大图也保持 `/api/agent/images/generate` 非流式 JSON 路径，用于诊断对照。
+当服务端默认 `IMAGE_STREAMING_STRATEGY=off` 且请求未覆盖 `streaming_strategy` 时，运行时默认策略为 `off`；WebUI 会把 server-default 流式请求切到 `non_stream`，并发批量开关不可用。脚本显式传 `--streaming-strategy off` 时同样保持非流��诊断路径。
+
 编辑脚本参数：
 
 - `--model`
 - `--size`
 - `--quality`
 - `--response-mode`
+- `--stream-mode`
+- `--streaming-strategy`
+- `--partial-images`
 - `--timeout-ms`
 - `--idempotency-key`
+- `--page-sse`
+- `--agent`
+- `--dry-run`
+- `--allow-billable`
+
+普通 edit 默认调用 `/api/agent/images/edit`，客户端拿到最终 JSON；`--stream-mode`、`--streaming-strategy` 和 `--partial-images` 只控制 Agent 内部上游流式兼容字段，不代表客户端响应会变成页面 SSE。
+`max_edge>2048` 的高分辨率 edit 默认优先走页面端 `/api/images` form-data SSE；失败后脚本输出结构化失败和备用端点建议，由下一步用 `--agent` 显式回退到 `/api/agent/images/edit` 诊断或执行，不会在同一次请求里静默二次调用。显式 `--page-sse` 会强制页面流式；显式 `--agent` 或 `stream_mode=non_stream` / `streaming_strategy=off` 会走 Agent edit 最终 JSON。
+
+批量脚本参数：
+
+- `--input`：JSONL 任务文件路径，也可作为唯一位置参数。
+- `--manifest`：append-only JSONL manifest 路径，默认 `<input>.manifest.jsonl`。
+- `--resume`：读取 manifest 中已 `succeeded` 的 `id` 或 `idempotency_key` 并跳过。
+- `--ordered-prefix`：未显式提供 `idempotency_key` 时构造稳定有序 key 的前缀，默认 `batch`。
+- `--dimension-check`：读取响应 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸等于任务 `size`。
+- `--max-attempts`：失败任务最大尝试次数。第二次及后续尝试会追加新的 attempt 级 `Idempotency-Key`，避免复用终态失败 key。
+- `--concurrency`：并发执行窗口，默认 `1`。大于 `1` 时会并发执行任务并按输入顺序输出结果；适合已确认渠道容量的批量生产。
+- `--max-consecutive-failures`：顺序执行下的连续失败熔断阈值，默认 `0` 表示不熔断。只能与 `--concurrency 1` 同用。
+- `--timeout-ms`
 - `--dry-run`
 - `--allow-billable`
 
+批量 JSONL 每行字段按 `mode` 区分。`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径；edit 任务使用这些高级字段会显式走 `/api/images`，因为 Agent JSON edit 不接收这些字段。`responsesModel` 会选择页面 SSE 路径，且必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`，因为 Agent JSON 不接收请求级 Responses 顶层模型。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
+
+并发批量示例：
+
+```text
+node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --concurrency 3
+```
+
+连续失败熔断需要严格顺序语义，不能与并发窗口大于 `1` 的批量执行同时使用。
+
 上游探针脚本参数：
 
 - `--base-url`
@@ -60,7 +108,7 @@ Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API
 - `--timeout-ms`
 - `--allow-billable`
 
-上游探针读取 `GPT_IMAGE_UPSTREAM_BASE_URL` 或 `OPENAI_API_BASE_URL` 作为上游地址，读取 `GPT_IMAGE_UPSTREAM_API_KEY` 或 `OPENAI_API_KEY` 作为上游鉴权。输出不会包含 key，也不会输出完整 base64。
+上游探针读取 `GPT_IMAGE_UPSTREAM_BASE_URL` 或 `OPENAI_API_BASE_URL` 作为上游地址，读取 `GPT_IMAGE_UPSTREAM_API_KEY` 或 `OPENAI_API_KEY` 作为上游鉴权。base URL 必须是无凭据、无查询参数和无片段的 `http`/`https` 绝对 URL。输出不会包含 key，也不会输出完整 base64。
 
 ## 能力查询
 
@@ -83,33 +131,41 @@ GET /api/agent/capabilities
 - `model_limits.gpt-image-2.large_image_risk`：大尺寸请求的长耗时风险说明，当前适用于 `max_edge>2048`。
 - `agent_streaming.generate.mode`：当前为 `non_streaming_only`。
 - `agent_streaming.edit.mode`：当前为 `non_streaming_only`。
-- `agent_streaming.upstream_sse`：Agent generate 内部消费上游 SSE 的能力，客户端响应仍是最终 `AgentImageResponse` JSON。
+- `agent_streaming.upstream_sse`：Agent generate/edit 内部消费上游 SSE 的能力，客户端响应仍是最终 `AgentImageResponse` JSON。
+- `agent_streaming.upstream_sse.supported`：布尔值；当服务端支持 Agent 内部上游 SSE 消费时为 `true`，否则为 `false`。客户端只在为 `true` 时发送上游流式控制字段。
+- `agent_streaming.upstream_sse.request_fields`：兼容旧客户端的字段合集，当前为 `image_backend`��`stream_mode`、`streaming_strategy`、`partial_images`。
+- `agent_streaming.upstream_sse.request_fields_by_mode.generate`：generate 可发送的上游 SSE 控制字段，当前为 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images`。
+- `agent_streaming.upstream_sse.request_fields_by_mode.edit`：edit 可发送的上游 SSE 控制字段，当前为 `stream_mode`、`streaming_strategy`、`partial_images`。
 - `agent_streaming.upstream_sse.image_backends`：支持 `images-api`、`responses-image-generation`。
 - `agent_streaming.upstream_sse.enabled_image_backends`：当前运行时可直接使用的 Agent 上游 SSE 后端；`responses-image-generation` 只有在所需环境变量齐备时才出现。
 - `agent_streaming.upstream_sse.streaming_strategies`：支持 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
-- `agent_streaming.upstream_sse.activation_strategies`：会真正向上游发送 `stream=true` 的策略，当前为 `openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
+- `agent_streaming.upstream_sse.stream_modes`：支持 `auto`、`stream`、`non_stream`。
+- `agent_streaming.upstream_sse.activation_strategies`：会真正向上游发送 `stream=true` 的策略，当前包含 `auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
 - `agent_streaming.page_sse`：页面端 `/api/images` 的 form-data SSE 能力，不代表 Agent generate/edit 支持流式。
 - `agent_streaming.page_sse.auth`：页面 SSE 的独立表单鉴权。`APP_PASSWORD` 已配置时为 `required=true`、`schemes=["form-password-hash"]`、`form_field="passwordHash"`。
 - `agent_streaming.page_sse.client_request_id`：页面 SSE 的请求 ID 契约。脚本会把 `Idempotency-Key` 写入 form-data `clientRequestId`，最大长度以 `max_length` 为准，当前为 `128`。
-- `routing_rules.high_resolution_edit`：`edit` 且最大边大于 `2048` 时必须使用页面端 `/api/images` SSE。
+- `routing_rules.high_resolution_edit`：`edit` 且最大边大于 `2048` 时默认优先使用页面端 `/api/images` SSE，页面流式有问题时显式回退。
 - `routing_rules.complex_ui_batch`：复杂 UI 批量出图推荐使用页面端 `/api/images` SSE。
 - `routing_rules.long_image_recovery`：长图恢复或续跑锚点场景推荐使用页面端 `/api/images` SSE。
 - `routing_rules.agent_generate_small_smoke`：普通小图单次文生图默认使用 `/api/agent/images/generate`。
 - `routing_rules.page_sse_large_generate`：`max_edge>2048` 的单次文生图推荐优先使用 `/api/images` SSE，失败后先诊断，再显式选择 `/api/agent/images/generate` 或 job 路径。
 - `routing_rules.retry_recovery`：终态失败不会用同一 `Idempotency-Key` 重新执行，必须诊断后创建新的业务操作和新的 key。
+- 批量 JSONL 路由控制字段：`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`；脚本会在 dry-run 阶段拒绝字符串布尔值和未知 transport。
 - `defaults.image_backend`：Agent generate 默认 `images-api`。
-- `defaults.streaming_strategy`：Agent generate 默认 `off`，不会默认向上游发送 `stream=true`。
-- `defaults.partial_images`：Agent generate 默认 `2`，仅在显式启用上游 SSE 时使用。
+- `defaults.stream_mode`：Agent generate 默认 `auto`。auto 会先尝试内部上游 SSE；无法产出最终图时显式回退并暴露可观测标记。
+- `defaults.streaming_strategy`：Agent generate 默认 `auto`。
+- `defaults.partial_images`：Agent generate 默认 `2`，在 `stream_mode` 不为 `non_stream` 时使用。
 - `supported.image_backends`：机器可读的图片后端枚举。
 - `supported.enabled_image_backends`：当前运行时可直接使用的图片后端。
 - `supported.image_backend_requirements`：每个图片后端的 required env、missing env 和 enabled 状态；Responses 后端需要 `ENABLE_RESPONSES_IMAGE_BACKEND` 与 `OPENAI_RESPONSES_API_MODEL`。
 - `supported.streaming_strategies`：机器可读的流式兼容策略枚举。
+- `supported.stream_modes`：机器可读的 `auto`、`stream`、`non_stream` 枚举。
 - `agent_jobs.supported`：当前为 `true`，表示可使用 job polling。
 - `agent_jobs.mode`：当前为 `job_polling`。
 - `agent_jobs.endpoints`：路径为 `POST /api/agent/jobs/images/generate`、`GET /api/agent/jobs/{id}`、`GET /api/agent/jobs/{id}/result`。
 - `agent_jobs.states`：状态机为 `queued`、`running`、`succeeded`、`failed`、`expired`。
 
-当 `agent_jobs.supported=true` 且 `mode=job_polling` 时，job 路径仍然可用，但普通大图单次文生图的默认路径已经切到页面端 `/api/images` SSE。高分辨率 edit 和复杂 UI 批量生产不应走 Agent 非流式 edit，优先按 `routing_rules` 使用页面端 `/api/images` SSE。当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。大图页面流式失败后不自动回退，先诊断再显式选新路径。
+当 `agent_jobs.supported=true` 且 `mode=job_polling` 时，job 路径仍然可用，但普通大图单次文生图的默认路径已经切到页面端 `/api/images` SSE。高分辨率 edit 和复杂 UI 批量生产默认优先按 `routing_rules` 使用页面端 `/api/images` SSE；页面流式有问题时，先诊断再显式选择 Agent JSON、Agent edit 或 job 路径。当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。大图页面流式失败后不自动回退，先诊断再显式选新路径。
 
 ## Job Polling
 
@@ -180,12 +236,20 @@ Content-Type: application/json
   "moderation": "auto",
   "response_mode": "path",
   "image_backend": "images-api",
-  "streaming_strategy": "off",
+  "stream_mode": "auto",
+  "streaming_strategy": "auto",
   "partial_images": 2
 }
 ```
 
-Agent 生成端点对外始终返回最终 JSON，不会对客户端返回 SSE。不要向该端点发送 `stream: true`；页面 SSE 使用独立的 `POST /api/images` form-data 路径。若 capabilities 中 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用服务端内部上游 SSE 消费，最终响应仍是 `AgentImageResponse`。
+Agent 生成端点对外始终返回最终 JSON，不会对客户端返回 SSE。不要向该端点发送 `stream: true`。
+
+- 页面 SSE 使用独立的 `POST /api/images` form-data 路径。
+- 若 capabilities 中 `agent_streaming.upstream_sse.supported=true`，generate 可通过 `request_fields_by_mode.generate` 声明的字段控制服务端内部上游 SSE 消费。`image_backend=responses-image-generation` 当前只支持 generate。
+- Agent 生成端点最终响应仍是 `AgentImageResponse`。
+- `stream_mode=stream` 强制流式并直接暴露失败。
+- `stream_mode=non_stream` 直接非流式。
+- `stream_mode=auto` 允许显式可观测回退。
 
 响应：
 
@@ -229,10 +293,15 @@ Content-Type: multipart/form-data
 - `size`：`auto` 或支持的尺寸。
 - `quality`：`low`、`medium`、`high` 或 `auto`。
 - `response_mode`：`path`、`base64` 或 `both`。
-- `image_0..image_9`：源图片。
+- `stream_mode`：可选，`auto`、`stream` 或 `non_stream`。
+- `streaming_strategy`：可选，`off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse` 或 `force-sse`。
+- `partial_images`：可选，`1..3`。
+- `image_0..image_9`：源图片。类似 `image_10`、`image_01` 或 `image_foo` 的图片字段会被显式拒绝。
 - `mask`：可选 PNG 遮罩。
 
-当 `size` 的最大边大于 `2048` 时，Agent edit 端点会返回 `validation_error`，不会联系上游；该场景必须按 `routing_rules.high_resolution_edit` 使用页面端 `/api/images` form-data SSE 路径。
+Agent edit 不接受 `image_backend`/`imageBackend`、`output_format`/`outputFormat`/`format`、`output_compression`/`outputCompression`、`responses_model`/`responsesModel`、`background` 或 `moderation`。编辑输出格式固定为 PNG；Responses image_generation 后端当前只支持 generate。
+
+当 `size` 的最大边大于 `2048` 时，默认按 `routing_rules.high_resolution_edit` 使用页面端 `/api/images` form-data SSE 路径；如果页面流式不可用或失败，可显式回退到 Agent edit 最终 JSON 路径进行诊断或执行。
 
 ## 产物元数据
 

skills/gpt-image-playground-agent/scripts/batch-images.mjs

@@ -0,0 +1,1226 @@
+#!/usr/bin/env node
+import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
+import {
+  errorMessage,
+  assertValidImageSizeForModel,
+  normalizeBaseUrl,
+  normalizeOutputFormat,
+  parseImageSizeValue,
+  readConfiguredPositiveInteger,
+  readMaxImageEdge,
+  readOptionValue,
+  resolveSameOriginUrl
+} from './lib/script-utils.mjs';
+import {
+  PAGE_SSE_ENDPOINT,
+  assertPageSseReady,
+  buildPageSseFailureOutput,
+  formatPageSseOutput,
+  normalizeImageBackendForPage,
+  postPageSse
+} from './lib/page-sse-client.mjs';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IMAGE_BACKENDS = new Set(['images-api', 'images', 'responses', 'responses-image-generation']);
+const MODELS = new Set(['gpt-image-1', 'gpt-image-1-mini', 'gpt-image-1.5', 'gpt-image-2']);
+const OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp']);
+const QUALITIES = new Set(['low', 'medium', 'high', 'auto']);
+const BACKGROUNDS = new Set(['transparent', 'opaque', 'auto']);
+const MODERATIONS = new Set(['low', 'auto']);
+const RESPONSE_MODES = new Set(['path', 'base64', 'both']);
+const STREAM_MODES = new Set(['auto', 'stream', 'non_stream']);
+const STREAMING_STRATEGIES = new Set([
+  'off',
+  'auto',
+  'openai-sse',
+  'newapi-keepalive-sse',
+  'responses-sse',
+  'force-sse'
+]);
+const MAX_EDIT_IMAGES = 10;
+const MIN_PARTIAL_IMAGES = 1;
+const MAX_PARTIAL_IMAGES = 3;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
+const DEFAULT_BATCH_MAX_ATTEMPTS = 1;
+const DEFAULT_MAX_CONSECUTIVE_FAILURES = 0;
+const DEFAULT_BATCH_CONCURRENCY = 1;
+const GENERATE_ONLY_FIELDS = [
+  'background'
+];
+const PAGE_ADVANCED_FIELDS = [
+  'output_format',
+  'format',
+  'output_compression',
+  'moderation',
+  'image_backend',
+  'responsesModel',
+  'gptModel',
+  'gpt_model',
+  'thinking',
+  'promptOptimization',
+  'prompt_optimization',
+  'force_web',
+  'forceWeb',
+  'sse_log_path'
+];
+const EDIT_ONLY_FIELDS = ['image_path', 'image_paths', 'mask_path'];
+const BOOLEAN_ROUTING_FIELDS = ['page_sse', 'complex_ui', 'long_image', 'resume_or_recover'];
+const THINKING_VALUES = new Set(['minimal', 'none', 'low', 'medium', 'high', 'xhigh']);
+const TASK_FIELDS = new Set([
+  'id',
+  'mode',
+  'prompt',
+  'idempotency_key',
+  'model',
+  'n',
+  'size',
+  'quality',
+  'response_mode',
+  'stream_mode',
+  'streaming_strategy',
+  'partial_images',
+  'page_sse',
+  'transport',
+  'complex_ui',
+  'long_image',
+  'resume_or_recover',
+  ...GENERATE_ONLY_FIELDS,
+  ...PAGE_ADVANCED_FIELDS,
+  ...EDIT_ONLY_FIELDS
+]);
+
+const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
+const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
+
+let options;
+try {
+  options = parseArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(errorMessage(error));
+  printUsage();
+  process.exit(2);
+}
+if (options.help) {
+  printUsage();
+  process.exit(0);
+}
+
+let baseUrl;
+let tasks;
+let timeoutMs;
+let capabilities;
+let capabilitiesPromise;
+try {
+  if (!options.input) throw new Error('--input 需要 JSONL 文件路径。');
+  baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+  timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
+  options.maxAttempts = readConfiguredPositiveInteger(
+    options.maxAttempts ?? DEFAULT_BATCH_MAX_ATTEMPTS,
+    '--max-attempts',
+    DEFAULT_BATCH_MAX_ATTEMPTS
+  );
+  options.maxConsecutiveFailures = readNonNegativeInteger(
+    options.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES,
+    '--max-consecutive-failures'
+  );
+  options.concurrency = readConfiguredPositiveInteger(
+    options.concurrency ?? DEFAULT_BATCH_CONCURRENCY,
+    '--concurrency',
+    DEFAULT_BATCH_CONCURRENCY
+  );
+  if (options.concurrency > 1 && options.maxConsecutiveFailures > 0) {
+    throw new Error('--concurrency 大于 1 时不能同时使用 --max-consecutive-failures；请使用 --concurrency 1 保持严格顺序熔断。');
+  }
+  tasks = readJsonlTasks(options.input);
+} catch (error) {
+  console.error(errorMessage(error));
+  process.exit(2);
+}
+
+const manifestPath = options.manifest || `${options.input}.manifest.jsonl`;
+let planned;
+try {
+  planned = tasks.map((task, index) => normalizeTask(task, index, options));
+} catch (error) {
+  console.error(errorMessage(error));
+  process.exit(2);
+}
+
+if (!options.allowBillable || options.dryRun) {
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        billable: false,
+        dry_run: true,
+        input: options.input,
+        manifest: manifestPath,
+        total: planned.length,
+        max_attempts: options.maxAttempts,
+        max_consecutive_failures: options.maxConsecutiveFailures,
+        concurrency: options.concurrency,
+        tasks: planned.map((task) => {
+          const routing = buildTaskRouting(task);
+          return {
+            index: task.index,
+            id: task.id,
+            mode: task.mode,
+            idempotency_key: task.idempotencyKey,
+            endpoint: routing.endpoint,
+            routing,
+            request: buildDryRunRequestPreview(task, routing)
+          };
+        }),
+        next_step: '重新执行并添加 --allow-billable 才会发起真实批量请求。'
+      },
+      null,
+      2
+    )
+  );
+  process.exit(0);
+}
+
+try {
+  const completed = options.resume ? readCompletedManifestKeys(manifestPath) : new Set();
+  const { results, failedTasks } = await runPlannedTasks(planned, completed);
+  const failed = results.filter((result) => !result.ok).length;
+  console.log(
+    JSON.stringify(
+      {
+        ok: failed === 0,
+        total: results.length,
+        failed,
+        manifest: manifestPath,
+        max_attempts: options.maxAttempts,
+        max_consecutive_failures: options.maxConsecutiveFailures,
+        concurrency: options.concurrency,
+        failure_summary: buildFailureSummary(failedTasks),
+        resume_fix_list: buildResumeFixList(failedTasks),
+        results
+      },
+      null,
+      2
+    )
+  );
+  process.exit(failed === 0 ? 0 : 1);
+} catch (error) {
+  console.error(errorMessage(error));
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    input: undefined,
+    manifest: undefined,
+    orderedPrefix: 'batch',
+    timeoutMs: undefined,
+    maxAttempts: undefined,
+    maxConsecutiveFailures: undefined,
+    concurrency: undefined,
+    allowBillable: false,
+    dryRun: false,
+    resume: false,
+    dimensionCheck: false,
+    help: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--allow-billable') parsed.allowBillable = true;
+    else if (arg === '--dry-run') parsed.dryRun = true;
+    else if (arg === '--resume') parsed.resume = true;
+    else if (arg === '--dimension-check') parsed.dimensionCheck = true;
+    else if (arg === '--help' || arg === '-h') parsed.help = true;
+    else if (arg === '--input') parsed.input = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--manifest') parsed.manifest = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--ordered-prefix') parsed.orderedPrefix = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--max-attempts') parsed.maxAttempts = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--max-consecutive-failures') {
+      parsed.maxConsecutiveFailures = readOptionValue(argv, (index += 1), arg);
+    }
+    else if (arg === '--concurrency') parsed.concurrency = readOptionValue(argv, (index += 1), arg);
+    else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
+    else if (!parsed.input) parsed.input = arg;
+    else throw new Error(`未知位置参数：${arg}`);
+  }
+  return parsed;
+}
+
+function readJsonlTasks(filePath) {
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split(/\r?\n/)
+    .map((line, index) => ({ line: line.trim(), index }))
+    .filter((item) => item.line && !item.line.startsWith('#'))
+    .map((item) => {
+      try {
+        return JSON.parse(item.line);
+      } catch (error) {
+        throw new Error(`${filePath}:${item.index + 1} 不是有效 JSON：${errorMessage(error)}`);
+      }
+    });
+}
+
+function normalizeTask(raw, index, parsedOptions) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`第 ${index + 1} 行必须是 JSON 对象。`);
+  }
+  const mode = normalizeMode(raw.mode, index);
+  const id = normalizeTaskId(raw.id, mode, index);
+  if (typeof raw.prompt !== 'string' || !raw.prompt.trim()) {
+    throw new Error(`${id} 缺少 prompt。`);
+  }
+  validateTaskFields(raw, id, mode);
+  validateTaskSize(raw, id, mode, parsedOptions.dimensionCheck);
+  validateTaskRoutingFields(raw, id);
+  if (mode === 'edit') validateEditImages(raw, id);
+  return {
+    id,
+    index,
+    mode,
+    raw,
+    idempotencyKey: normalizeIdempotencyKey(raw.idempotency_key, parsedOptions.orderedPrefix, index, id)
+  };
+}
+
+function normalizeTaskId(value, mode, index) {
+  if (value === undefined || value === null || value === '') return `${mode}-${index + 1}`;
+  return String(value);
+}
+
+function normalizeMode(value, index) {
+  if (value === undefined || value === null || value === '' || value === 'generate') return 'generate';
+  if (value === 'edit') return 'edit';
+  throw new Error(`第 ${index + 1} 行 mode 必须是 generate 或 edit。`);
+}
+
+function normalizeIdempotencyKey(value, orderedPrefix, index, id) {
+  if (value === undefined || value === null || value === '') return buildOrderedKey(orderedPrefix, index, id);
+  if (typeof value !== 'string') throw new Error(`${id} idempotency_key 必须是字符串。`);
+  return value;
+}
+
+function validateTaskSize(raw, id, mode, dimensionCheck) {
+  if (raw.size !== undefined) {
+    assertValidImageSizeForModel(raw.size, raw.model || 'gpt-image-2', `${id}.size`);
+  }
+  if (!dimensionCheck) return;
+  const size = raw.size || (mode === 'generate' ? '1024x1024' : undefined);
+  if (!parseExpectedSize(size)) {
+    throw new Error(`${id} --dimension-check 需要 size 为 WIDTHxHEIGHT。`);
+  }
+}
+
+function validateEditImages(raw, id) {
+  const imagePaths = readEditImagePaths(raw, id);
+  if (imagePaths.length === 0) throw new Error(`${id} edit 任务必须提供 image_path 或 image_paths。`);
+  if (imagePaths.length > MAX_EDIT_IMAGES) throw new Error(`${id} edit 任务最多支持 ${MAX_EDIT_IMAGES} 张源图。`);
+  if (hasOwn(raw, 'mask_path')) readNonEmptyString(raw.mask_path, `${id}.mask_path`);
+}
+
+function validateTaskFields(raw, id, mode) {
+  validateKnownTaskFields(raw, id);
+  validateModeSpecificFields(raw, id, mode);
+  validateRoutingControlFields(raw, id);
+  validateAmbiguousAliasFields(raw, id);
+  if (hasOwn(raw, 'model')) normalizeEnumValue(raw.model, MODELS, `${id}.model`);
+  if (raw.n !== undefined) readConfiguredPositiveInteger(raw.n, `${id}.n`, 1);
+  if (hasOwn(raw, 'quality')) normalizeEnumValue(raw.quality, QUALITIES, `${id}.quality`);
+  if (hasOwn(raw, 'response_mode')) normalizeEnumValue(raw.response_mode, RESPONSE_MODES, `${id}.response_mode`);
+  if (hasOwn(raw, 'image_backend')) normalizeEnumValue(raw.image_backend, IMAGE_BACKENDS, `${id}.image_backend`);
+  if (hasOwn(raw, 'background')) normalizeEnumValue(raw.background, BACKGROUNDS, `${id}.background`);
+  if (hasOwn(raw, 'moderation')) normalizeEnumValue(raw.moderation, MODERATIONS, `${id}.moderation`);
+  if (hasOwn(raw, 'thinking')) normalizeEnumValue(raw.thinking, THINKING_VALUES, `${id}.thinking`);
+  readPromptOptimization(raw, id);
+  if (hasOwn(raw, 'force_web')) readBooleanAlias(raw.force_web, `${id}.force_web`);
+  if (hasOwn(raw, 'forceWeb')) readBooleanAlias(raw.forceWeb, `${id}.forceWeb`);
+  if (hasOwn(raw, 'sse_log_path')) readNonEmptyString(raw.sse_log_path, `${id}.sse_log_path`);
+  validateResponsesModelField(raw, id);
+  if (hasOwn(raw, 'stream_mode')) normalizeEnumValue(raw.stream_mode, STREAM_MODES, `${id}.stream_mode`);
+  if (hasOwn(raw, 'streaming_strategy')) {
+    normalizeEnumValue(raw.streaming_strategy, STREAMING_STRATEGIES, `${id}.streaming_strategy`);
+  }
+  if (hasOwn(raw, 'partial_images')) readPartialImages(raw.partial_images, `${id}.partial_images`);
+  if (hasOwn(raw, 'output_format') || hasOwn(raw, 'format')) {
+    normalizeEnumValue(readOutputFormatField(raw, id), OUTPUT_FORMATS, `${id}.output_format`);
+  }
+  validateBackgroundForModel(raw, id);
+  validateOutputCompression(raw, id);
+}
+
+function validateAmbiguousAliasFields(raw, id) {
+  if (hasOwn(raw, 'output_format') && hasOwn(raw, 'format')) {
+    throw new Error(`${id}.output_format 与 format 不能同时设置。`);
+  }
+  if (hasOwn(raw, 'image_path') && hasOwn(raw, 'image_paths')) {
+    throw new Error(`${id}.image_path 与 image_paths 不能同时设置。`);
+  }
+}
+
+function validateKnownTaskFields(raw, id) {
+  for (const field of Object.keys(raw)) {
+    if (!TASK_FIELDS.has(field)) {
+      throw new Error(`${id}.${field} 不是支持的 batch JSONL 字段。`);
+    }
+  }
+}
+
+function validateModeSpecificFields(raw, id, mode) {
+  const fields = mode === 'edit' ? GENERATE_ONLY_FIELDS : EDIT_ONLY_FIELDS;
+  const expectedMode = mode === 'edit' ? 'generate' : 'edit';
+  for (const field of fields) {
+    if (hasOwn(raw, field)) {
+      throw new Error(`${id}.${modeSpecificFieldLabel(field)} 仅适用于 ${expectedMode} 任务。`);
+    }
+  }
+}
+
+function modeSpecificFieldLabel(field) {
+  return field === 'format' ? 'output_format' : field;
+}
+
+function validateRoutingControlFields(raw, id) {
+  for (const field of BOOLEAN_ROUTING_FIELDS) {
+    if (hasOwn(raw, field) && typeof raw[field] !== 'boolean') {
+      throw new Error(`${id}.${field} 必须是布尔值。`);
+    }
+  }
+  if (hasOwn(raw, 'transport') && raw.transport !== 'page_sse') {
+    throw new Error(`${id}.transport 必须是 page_sse。`);
+  }
+}
+
+function validateBackgroundForModel(raw, id) {
+  if (!hasOwn(raw, 'background')) return;
+  const model = hasOwn(raw, 'model') ? String(raw.model) : 'gpt-image-2';
+  if (model === 'gpt-image-2' && String(raw.background) === 'transparent') {
+    throw new Error(`${id}.background 对 gpt-image-2 无效：gpt-image-2 不支持 transparent 背景。`);
+  }
+}
+
+function validateOutputCompression(raw, id) {
+  readOutputCompression(raw, id);
+}
+
+function validateResponsesModelField(raw, id) {
+  const responsesModel = readResponsesModel(raw, id);
+  if (!responsesModel) return;
+  if (!hasOwn(raw, 'image_backend')) {
+    throw new Error(`${id}.responsesModel 必须同时设置 image_backend=responses-image-generation。`);
+  }
+  const imageBackend = normalizeEnumValue(raw.image_backend, IMAGE_BACKENDS, `${id}.image_backend`);
+  if (imageBackend !== 'responses-image-generation' && imageBackend !== 'responses') {
+    throw new Error(`${id}.responsesModel 仅适用于 image_backend=responses-image-generation。`);
+  }
+}
+
+function readResponsesModel(raw, id) {
+  const fields = ['responsesModel', 'gptModel', 'gpt_model'];
+  const present = fields.filter((field) => hasOwn(raw, field));
+  if (present.length === 0) return undefined;
+  if (present.length > 1) throw new Error(`${id}.responsesModel、gptModel 与 gpt_model 不能同时设置。`);
+  return readNonEmptyString(raw[present[0]], `${id}.${present[0]}`);
+}
+
+function readPromptOptimization(raw, id) {
+  const fields = ['promptOptimization', 'prompt_optimization'];
+  const present = fields.filter((field) => hasOwn(raw, field));
+  if (present.length === 0) return undefined;
+  if (present.length > 1) throw new Error(`${id}.promptOptimization 与 prompt_optimization 不能同时设置。`);
+  return readBooleanAlias(raw[present[0]], `${id}.${present[0]}`);
+}
+
+function readForceWeb(raw, id) {
+  const fields = ['force_web', 'forceWeb'];
+  const present = fields.filter((field) => hasOwn(raw, field));
+  if (present.length === 0) return undefined;
+  if (present.length > 1) throw new Error(`${id}.force_web 与 forceWeb 不能同时设置。`);
+  return readBooleanAlias(raw[present[0]], `${id}.${present[0]}`);
+}
+
+function readBooleanAlias(value, name) {
+  if (typeof value === 'boolean') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new Error(`${name} 必须是布尔值。`);
+}
+
+function readOutputCompression(raw, id) {
+  if (!hasOwn(raw, 'output_compression')) return undefined;
+  const outputFormat = hasOwn(raw, 'output_format') || hasOwn(raw, 'format')
+    ? readOutputFormatField(raw, id)
+    : 'png';
+  if (outputFormat === 'png') {
+    return undefined;
+  }
+  const value = raw.output_compression;
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : NaN;
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 100) {
+    throw new Error(`${id}.output_compression 必须是 0 到 100 之间的整数。`);
+  }
+  return parsed;
+}
+
+function readTaskNormalizations(raw, id) {
+  if (!hasOwn(raw, 'output_compression')) return undefined;
+  const outputFormat = hasOwn(raw, 'output_format') || hasOwn(raw, 'format')
+    ? readOutputFormatField(raw, id)
+    : 'png';
+  if (outputFormat !== 'png') return undefined;
+  return { output_compression_ignored_for_png: true };
+}
+
+function readOutputFormatField(raw, id) {
+  const value = raw.output_format ?? raw.format;
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${id}.output_format 必须是字符串。`);
+  }
+  return normalizeOutputFormat(value);
+}
+
+function validateTaskRoutingFields(raw, id) {
+  if ((raw.page_sse === true || raw.transport === 'page_sse') && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
+    throw new Error(`${id} stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。`);
+  }
+  if (readResponsesModel(raw, id) && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
+    throw new Error(`${id}.responsesModel 需要页面 SSE 路径，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。`);
+  }
+  if (hasOwn(raw, 'sse_log_path') && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
+    throw new Error(`${id}.sse_log_path 需要页面 SSE 路径，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。`);
+  }
+  if (hasPageAdvancedFields(raw) && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off') && raw.mode === 'edit') {
+    throw new Error(`${id} 图生图高级参数需要页面 SSE，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。`);
+  }
+}
+
+function hasPageAdvancedFields(raw) {
+  return PAGE_ADVANCED_FIELDS.some((field) => hasOwn(raw, field));
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function readEditImagePaths(raw, id = 'edit') {
+  if (Array.isArray(raw.image_paths)) {
+    if (raw.image_paths.length === 0) throw new Error(`${id}.image_paths 必须是非空字符串数组。`);
+    return raw.image_paths.map((value, index) => readNonEmptyString(value, `${id}.image_paths[${index}]`));
+  }
+  if (hasOwn(raw, 'image_paths')) throw new Error(`${id}.image_paths 必须是非空字符串数组。`);
+  if (hasOwn(raw, 'image_path')) return [readNonEmptyString(raw.image_path, `${id}.image_path`)];
+  return [];
+}
+
+function readNonEmptyString(value, name) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${name} 必须是非空字符串。`);
+  }
+  return value;
+}
+
+function buildOrderedKey(prefix, index, id) {
+  const safePrefix = sanitizeKeyPart(prefix || 'batch');
+  const safeId = sanitizeKeyPart(id || `item-${index + 1}`);
+  return `${safePrefix}-${String(index + 1).padStart(4, '0')}-${safeId}`.slice(0, 200);
+}
+
+function sanitizeKeyPart(value) {
+  return String(value)
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'item';
+}
+
+function authHeaders() {
+  if (token) return { Authorization: `Bearer ${token}` };
+  if (passwordHash) return { 'X-App-Password-Hash': passwordHash };
+  return {};
+}
+
+async function readCapabilities() {
+  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.capabilities}`, { headers: authHeaders() });
+  if (!response.ok) throw new Error(`capabilities 请求失败，状态码 ${response.status}：${text}`);
+  return result;
+}
+
+async function ensureCapabilities() {
+  if (capabilities) return capabilities;
+  capabilitiesPromise ??= readCapabilities();
+  try {
+    capabilities = await capabilitiesPromise;
+  } catch (error) {
+    capabilitiesPromise = undefined;
+    throw error;
+  }
+  return capabilities;
+}
+
+async function runTask(task) {
+  const routing = buildTaskRouting(task);
+  try {
+    const response =
+      routing.transport === 'page_sse'
+        ? await postPageSseTask(task, routing)
+        : task.mode === 'edit'
+          ? await postEditTask(task)
+          : await postGenerateTask(task);
+    if (options.dimensionCheck) await assertDimensions(task, response);
+    const output = { ok: true, status: 'succeeded', id: task.id, idempotency_key: task.idempotencyKey, routing, response };
+    appendManifest(manifestPath, { ...baseManifestEntry(task), status: 'succeeded', routing, response: sanitizeResponse(response) });
+    return output;
+  } catch (error) {
+    const failure = buildTaskFailureOutput(error, routing);
+    const output = { ok: false, status: 'failed', id: task.id, idempotency_key: task.idempotencyKey, ...failure };
+    appendManifest(manifestPath, { ...baseManifestEntry(task), status: 'failed', ...failure });
+    return output;
+  }
+}
+
+async function runTaskWithAttempts(task) {
+  let lastResult;
+  for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+    const attemptTask = buildAttemptTask(task, attempt);
+    const result = await runTask(attemptTask);
+    lastResult = addAttemptMetadata(result, task, attempt);
+    if (result.ok) return lastResult;
+  }
+  return lastResult;
+}
+
+async function runPlannedTasks(plannedTasks, completed) {
+  const results = new Array(plannedTasks.length);
+  const failedTasks = [];
+  let consecutiveFailures = 0;
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < plannedTasks.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const task = plannedTasks[index];
+
+      if (completed.has(task.idempotencyKey) || completed.has(task.id)) {
+        results[index] = handleResumeSkippedTask(task);
+        continue;
+      }
+
+      if (options.maxConsecutiveFailures > 0 && consecutiveFailures >= options.maxConsecutiveFailures) {
+        results[index] = handleCircuitBreakerSkippedTask(task, consecutiveFailures);
+        continue;
+      }
+
+      const result = await runTaskWithAttempts(task);
+      results[index] = result;
+      if (result.ok) {
+        consecutiveFailures = 0;
+      } else {
+        consecutiveFailures += 1;
+        failedTasks.push(buildFailedTaskSummary(result, task));
+      }
+    }
+  }
+
+  const workerCount = Math.min(options.concurrency, plannedTasks.length);
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  failedTasks.sort((left, right) => left.index - right.index);
+  return { results, failedTasks };
+}
+
+function handleResumeSkippedTask(task) {
+  const skipped = {
+    ok: true,
+    status: 'skipped',
+    id: task.id,
+    idempotency_key: task.idempotencyKey,
+    billable: false,
+    skipped_reason: 'resume'
+  };
+  appendManifest(manifestPath, {
+    ...baseManifestEntry(task),
+    status: 'skipped',
+    billable: false,
+    skipped_reason: 'resume'
+  });
+  return skipped;
+}
+
+function handleCircuitBreakerSkippedTask(task, consecutiveFailures) {
+  const skipped = buildCircuitBreakerSkippedTask(task, consecutiveFailures);
+  appendManifest(manifestPath, { ...baseManifestEntry(task), ...skipped });
+  return { ok: true, id: task.id, idempotency_key: task.idempotencyKey, ...skipped };
+}
+
+function buildAttemptTask(task, attempt) {
+  if (attempt === 1) return { ...task, attempt, rootIdempotencyKey: task.idempotencyKey };
+  return {
+    ...task,
+    attempt,
+    rootIdempotencyKey: task.idempotencyKey,
+    idempotencyKey: buildAttemptIdempotencyKey(task.idempotencyKey, attempt)
+  };
+}
+
+function buildAttemptIdempotencyKey(idempotencyKey, attempt) {
+  const suffix = `-attempt-${attempt}`;
+  if (idempotencyKey.length + suffix.length <= MAX_IDEMPOTENCY_KEY_LENGTH) {
+    return `${idempotencyKey}${suffix}`;
+  }
+  const digest = crypto.createHash('sha256').update(idempotencyKey).digest('hex').slice(0, 12);
+  const hashedSuffix = `-${digest}${suffix}`;
+  return `${idempotencyKey.slice(0, MAX_IDEMPOTENCY_KEY_LENGTH - hashedSuffix.length)}${hashedSuffix}`;
+}
+
+function addAttemptMetadata(result, rootTask, attempt) {
+  return {
+    ...result,
+    attempt,
+    max_attempts: options.maxAttempts,
+    ...(attempt > 1 ? { root_idempotency_key: rootTask.idempotencyKey } : {})
+  };
+}
+
+function buildTaskFailureOutput(error, routing) {
+  if (error?.pageSseFailure && typeof error.pageSseFailure === 'object') {
+    return {
+      billable: error.pageSseFailure.billable,
+      error: error.pageSseFailure.error,
+      routing: error.pageSseFailure.routing || routing,
+      next_step: error.pageSseFailure.next_step
+    };
+  }
+  return { error: errorMessage(error), routing };
+}
+
+function buildCircuitBreakerSkippedTask(task, consecutiveFailures) {
+  return {
+    status: 'skipped',
+    billable: false,
+    skipped_reason: 'max_consecutive_failures',
+    consecutive_failures: consecutiveFailures,
+    next_step: '先处理 failure_summary 中的失败任务，再用 --resume 续跑剩余任务。'
+  };
+}
+
+function buildFailedTaskSummary(result, task) {
+  const error = normalizeFailureError(result.error);
+  return {
+    index: task.index,
+    id: task.id,
+    idempotency_key: task.idempotencyKey,
+    attempt: result.attempt,
+    route: result.routing?.transport,
+    endpoint: result.routing?.endpoint,
+    billable: result.billable !== false,
+    code: error.code,
+    message: error.message,
+    next_step: result.next_step || buildFailureNextStep(error)
+  };
+}
+
+function normalizeFailureError(error) {
+  if (error && typeof error === 'object') {
+    return {
+      code: typeof error.code === 'string' ? error.code : 'batch_task_failed',
+      message: typeof error.message === 'string' ? error.message : JSON.stringify(error)
+    };
+  }
+  return { code: 'batch_task_failed', message: String(error || '任务失败。') };
+}
+
+function buildFailureNextStep(error) {
+  if (error.code === 'page_sse_request_rejected') return '修正请求参数或鉴权后，使用新的 Idempotency-Key 重试失败任务。';
+  if (error.code === 'page_sse_unavailable') return '补齐 page_sse capability 或显式改用 Agent JSON，再重试失败任务。';
+  return '诊断失败原因后，用新的 Idempotency-Key 重试失败任务；不要复用终态失败 key。';
+}
+
+function buildFailureSummary(failedTasks) {
+  return {
+    count: failedTasks.length,
+    billable_count: failedTasks.filter((task) => task.billable).length,
+    non_billable_count: failedTasks.filter((task) => !task.billable).length,
+    tasks: failedTasks
+  };
+}
+
+function buildResumeFixList(failedTasks) {
+  return failedTasks.map((task) => ({
+    id: task.id,
+    previous_idempotency_key: task.idempotency_key,
+    suggested_idempotency_key: buildAttemptIdempotencyKey(task.idempotency_key, (task.attempt || 1) + 1),
+    route: task.route,
+    next_step: task.next_step
+  }));
+}
+
+function buildTaskRouting(task) {
+  if (shouldUsePageSseForTask(task)) {
+    const reason = buildPageSseRoutingReason(task);
+    return {
+      endpoint: PAGE_SSE_ENDPOINT,
+      transport: 'page_sse',
+      strength: task.mode === 'edit' && readTaskMaxEdge(task) > 2048 ? 'default' : 'recommended',
+      fallback_endpoint: task.mode === 'edit' ? AGENT_ENDPOINTS.edit : AGENT_ENDPOINTS.generate,
+      fallback_mode: 'manual_after_diagnosis',
+      reason
+    };
+  }
+  return {
+    endpoint: task.mode === 'edit' ? AGENT_ENDPOINTS.edit : AGENT_ENDPOINTS.generate,
+    transport: 'agent_json',
+    strength: 'default',
+    reason: 'Normal batch tasks use the Agent JSON response contract.'
+  };
+}
+
+function buildPageSseRoutingReason(task) {
+  if (task.raw.sse_log_path) {
+    return 'Task requested raw SSE event logging, so it uses page form-data SSE for observable diagnostics.';
+  }
+  if (task.mode === 'edit' && hasPageAdvancedFields(task.raw)) {
+    return 'GPT2Image-compatible edit options require page form-data SSE; Agent JSON edit does not accept those fields.';
+  }
+  if (task.mode === 'edit' && readTaskMaxEdge(task) > 2048) {
+    return 'High-resolution edit defaults to page form-data SSE; fall back explicitly after diagnosis if streaming has issues.';
+  }
+  return 'Large or complex batch image tasks should use page form-data SSE for observability and recovery.';
+}
+
+function buildDryRunRequestPreview(task, routing) {
+  if (routing.transport === 'page_sse') return buildPageSseRequestPreview(task);
+  if (task.mode === 'edit') return buildAgentEditRequestPreview(task.raw);
+  return buildGenerateBody(task.raw);
+}
+
+function buildAgentEditRequestPreview(raw) {
+  validateEditStrategyFields(raw);
+  const preview = {};
+  const fields = ['prompt', 'model', 'n', 'size', 'quality', 'response_mode', 'stream_mode', 'streaming_strategy', 'partial_images'];
+  for (const field of fields) {
+    if (raw[field] !== undefined) preview[field] = raw[field];
+  }
+  if (!raw.model) preview.model = 'gpt-image-2';
+  if (!raw.response_mode) preview.response_mode = 'path';
+  preview.image_fields = readEditImagePaths(raw, String(raw.id || 'edit')).map((_, index) => `image_${index}`);
+  if (raw.mask_path) preview.mask = 'provided';
+  return preview;
+}
+
+function buildPageSseRequestPreview(task) {
+  const raw = task.raw;
+  const preview = {
+    mode: task.mode,
+    prompt: raw.prompt,
+    model: raw.model || 'gpt-image-2',
+    size: raw.size || (task.mode === 'generate' ? '1024x1024' : 'auto'),
+    quality: raw.quality || (task.mode === 'generate' ? 'high' : 'auto'),
+    response_mode: readResponseMode(raw),
+    clientRequestId: task.idempotencyKey,
+    stream: 'true'
+  };
+  if (raw.n !== undefined) preview.n = readConfiguredPositiveInteger(raw.n, `${task.id}.n`, 1);
+  if (raw.stream_mode) preview.stream_mode = String(raw.stream_mode);
+  if (raw.streaming_strategy) preview.image_streaming_strategy = String(raw.streaming_strategy);
+  if (raw.partial_images !== undefined) preview.partial_images = readPartialImages(raw.partial_images, `${task.id}.partial_images`);
+  if (raw.image_backend) preview.image_backend = normalizeImageBackendForPage(String(raw.image_backend));
+  if (readResponsesModel(raw, task.id)) preview.responsesModel = readResponsesModel(raw, task.id);
+  if (raw.thinking) preview.thinking = String(raw.thinking);
+  if (readPromptOptimization(raw, task.id) !== undefined) preview.promptOptimization = readPromptOptimization(raw, task.id);
+  if (readForceWeb(raw, task.id) !== undefined) preview.force_web = readForceWeb(raw, task.id);
+  if (raw.sse_log_path) preview.sse_log_path = readNonEmptyString(raw.sse_log_path, `${task.id}.sse_log_path`);
+  if (raw.background) preview.background = String(raw.background);
+  if (raw.moderation) preview.moderation = String(raw.moderation);
+  if (raw.output_compression !== undefined) preview.output_compression = readOutputCompression(raw, task.id);
+  if (readTaskNormalizations(raw, task.id)) preview.normalizations = readTaskNormalizations(raw, task.id);
+  if (task.mode === 'edit') {
+    preview.image_fields = readEditImagePaths(raw, task.id).map((_, index) => `image_${index}`);
+    if (raw.mask_path) preview.mask = 'provided';
+  }
+  preview.output_format = readOutputFormat(raw);
+  return preview;
+}
+
+function shouldUsePageSseForTask(task) {
+  const pageSseAllowed = isPageSseAllowedForTask(task);
+  if (task.raw.page_sse === true || task.raw.transport === 'page_sse') {
+    if (!pageSseAllowed) {
+      throw new Error(`${task.id} stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。`);
+    }
+    return true;
+  }
+  if (!pageSseAllowed) return false;
+  if (task.raw.complex_ui === true || task.raw.long_image === true || task.raw.resume_or_recover === true) return true;
+  if (readResponsesModel(task.raw, task.id)) return true;
+  if (task.raw.sse_log_path) return true;
+  if (task.mode === 'edit' && hasPageAdvancedFields(task.raw)) return true;
+  if (task.mode === 'edit' && readTaskMaxEdge(task) > 2048) return true;
+  if (task.mode === 'generate' && readTaskMaxEdge(task) > 2048) {
+    return true;
+  }
+  return false;
+}
+
+function isPageSseAllowedForTask(task) {
+  return task.raw.streaming_strategy !== 'off' && task.raw.stream_mode !== 'non_stream';
+}
+
+async function postGenerateTask(task) {
+  const body = buildGenerateBody(task.raw);
+  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Idempotency-Key': task.idempotencyKey, ...authHeaders() },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) throw new Error(readErrorMessage(result) || `generate 请求失败，状态码 ${response.status}：${text}`);
+  return enrichImageUrls(result);
+}
+
+async function postEditTask(task) {
+  const formData = new FormData();
+  appendEditFields(formData, task.raw);
+  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.edit}`, {
+    method: 'POST',
+    headers: { 'Idempotency-Key': task.idempotencyKey, ...authHeaders() },
+    body: formData
+  });
+  if (!response.ok) throw new Error(readErrorMessage(result) || `edit 请求失败，状态码 ${response.status}：${text}`);
+  return enrichImageUrls(result);
+}
+
+async function postPageSseTask(task, routing) {
+  const pageSseCapabilities = await ensureCapabilities();
+  try {
+    assertPageSseReady({
+      capabilities: pageSseCapabilities,
+      passwordHash,
+      idempotencyKey: task.idempotencyKey
+    });
+    const formData = buildPageSseTaskFormData(task);
+    const result = await postPageSse({
+      url: `${baseUrl}${PAGE_SSE_ENDPOINT}`,
+      formData,
+      timeoutMs,
+      sseLogPath: task.raw.sse_log_path,
+      errorMessage
+    });
+    return formatPageSseOutput({
+      result,
+      baseUrl,
+      responseMode: readResponseMode(task.raw),
+      defaultOutputFormat: readOutputFormat(task.raw)
+    });
+  } catch (error) {
+    const pageSseFailure = buildPageSseFailureOutput({
+      error,
+      fallbackEndpoint: routing.fallback_endpoint,
+      errorMessage
+    });
+    const taskError = new Error(pageSseFailure.error?.message || errorMessage(error));
+    taskError.pageSseFailure = pageSseFailure;
+    throw taskError;
+  }
+}
+
+function buildGenerateBody(raw) {
+  const outputFormat = hasOwn(raw, 'output_format') || hasOwn(raw, 'format')
+    ? normalizeOutputFormat(raw.output_format ?? raw.format)
+    : 'png';
+  const outputCompression = readOutputCompression(raw, String(raw.id || 'generate'));
+  const body = {
+    prompt: raw.prompt,
+    model: raw.model || 'gpt-image-2',
+    n: readConfiguredPositiveInteger(raw.n, 'n', 1),
+    size: raw.size || '1024x1024',
+    quality: raw.quality || 'high',
+    output_format: normalizeEnumValue(outputFormat, OUTPUT_FORMATS, 'output_format'),
+    response_mode: normalizeEnumValue(hasOwn(raw, 'response_mode') ? raw.response_mode : 'path', RESPONSE_MODES, 'response_mode'),
+    ...(outputCompression !== undefined ? { output_compression: outputCompression } : {}),
+    ...(raw.background ? { background: raw.background } : {}),
+    ...(raw.moderation ? { moderation: raw.moderation } : {}),
+    ...(hasOwn(raw, 'image_backend') ? { image_backend: normalizeEnumValue(raw.image_backend, IMAGE_BACKENDS, 'image_backend') } : {}),
+    ...(hasOwn(raw, 'stream_mode') ? { stream_mode: normalizeEnumValue(raw.stream_mode, STREAM_MODES, 'stream_mode') } : {}),
+    ...(hasOwn(raw, 'streaming_strategy')
+      ? { streaming_strategy: normalizeEnumValue(raw.streaming_strategy, STREAMING_STRATEGIES, 'streaming_strategy') }
+      : {}),
+    ...(hasOwn(raw, 'partial_images') ? { partial_images: readPartialImages(raw.partial_images, 'partial_images') } : {})
+  };
+  const normalizations = readTaskNormalizations(raw, String(raw.id || 'generate'));
+  return normalizations ? { ...body, normalizations } : body;
+}
+
+function buildPageSseTaskFormData(task) {
+  const raw = task.raw;
+  const formData = new FormData();
+  formData.append('mode', task.mode);
+  formData.append('prompt', raw.prompt);
+  formData.append('model', raw.model || 'gpt-image-2');
+  formData.append('size', raw.size || (task.mode === 'generate' ? '1024x1024' : 'auto'));
+  formData.append('quality', raw.quality || (task.mode === 'generate' ? 'high' : 'auto'));
+  formData.append('response_mode', readResponseMode(raw));
+  formData.append('clientRequestId', task.idempotencyKey);
+  formData.append('stream', 'true');
+  if (raw.n !== undefined) formData.append('n', String(readConfiguredPositiveInteger(raw.n, `${task.id}.n`, 1)));
+  if (raw.stream_mode) formData.append('stream_mode', String(raw.stream_mode));
+  if (raw.streaming_strategy) formData.append('image_streaming_strategy', String(raw.streaming_strategy));
+  if (raw.partial_images !== undefined) formData.append('partial_images', String(readPartialImages(raw.partial_images, `${task.id}.partial_images`)));
+  if (raw.image_backend) formData.append('image_backend', normalizeImageBackendForPage(String(raw.image_backend)));
+  if (readResponsesModel(raw, task.id)) formData.append('responsesModel', readResponsesModel(raw, task.id));
+  if (raw.thinking) formData.append('thinking', String(raw.thinking));
+  if (readPromptOptimization(raw, task.id) !== undefined) {
+    formData.append('promptOptimization', String(readPromptOptimization(raw, task.id)));
+  }
+  if (readForceWeb(raw, task.id) !== undefined) formData.append('force_web', String(readForceWeb(raw, task.id)));
+  if (raw.background) formData.append('background', String(raw.background));
+  if (raw.moderation) formData.append('moderation', String(raw.moderation));
+  if (readOutputCompression(raw, task.id) !== undefined) {
+    formData.append('output_compression', String(readOutputCompression(raw, task.id)));
+  }
+  if (passwordHash) formData.append('passwordHash', passwordHash);
+  if (task.mode === 'edit') {
+    readEditImagePaths(raw, task.id).forEach((filePath, index) => appendFile(formData, `image_${index}`, filePath));
+    if (raw.mask_path) appendFile(formData, 'mask', raw.mask_path);
+  }
+  formData.append('output_format', readOutputFormat(raw));
+  return formData;
+}
+
+function readResponseMode(raw) {
+  return normalizeEnumValue(hasOwn(raw, 'response_mode') ? raw.response_mode : 'path', RESPONSE_MODES, 'response_mode');
+}
+
+function readOutputFormat(raw) {
+  const outputFormat = hasOwn(raw, 'output_format') || hasOwn(raw, 'format')
+    ? normalizeOutputFormat(raw.output_format ?? raw.format)
+    : 'png';
+  return normalizeEnumValue(outputFormat, OUTPUT_FORMATS, 'output_format');
+}
+
+function appendEditFields(formData, raw) {
+  validateEditStrategyFields(raw);
+  const fields = ['prompt', 'model', 'n', 'size', 'quality', 'response_mode', 'stream_mode', 'streaming_strategy', 'partial_images'];
+  for (const field of fields) {
+    if (raw[field] !== undefined) formData.append(field, String(raw[field]));
+  }
+  if (!raw.model) formData.append('model', 'gpt-image-2');
+  if (!raw.response_mode) formData.append('response_mode', 'path');
+  readEditImagePaths(raw, String(raw.id || 'edit')).forEach((filePath, index) => appendFile(formData, `image_${index}`, filePath));
+  if (raw.mask_path) appendFile(formData, 'mask', raw.mask_path);
+}
+
+function readTaskMaxEdge(task) {
+  return readMaxImageEdge(task.raw.size || (task.mode === 'generate' ? '1024x1024' : undefined));
+}
+
+function validateEditStrategyFields(raw) {
+  if (hasOwn(raw, 'response_mode')) normalizeEnumValue(raw.response_mode, RESPONSE_MODES, 'response_mode');
+  if (hasOwn(raw, 'stream_mode')) normalizeEnumValue(raw.stream_mode, STREAM_MODES, 'stream_mode');
+  if (hasOwn(raw, 'streaming_strategy')) {
+    normalizeEnumValue(raw.streaming_strategy, STREAMING_STRATEGIES, 'streaming_strategy');
+  }
+  if (hasOwn(raw, 'partial_images')) readPartialImages(raw.partial_images, 'partial_images');
+}
+
+function normalizeEnumValue(value, allowed, name) {
+  const normalized = String(value);
+  if (allowed.has(normalized)) return normalized;
+  throw new Error(`${name} 的值无效：${normalized}`);
+}
+
+function readPartialImages(value, name) {
+  const parsed = readConfiguredPositiveInteger(value, name, 2);
+  if (parsed < MIN_PARTIAL_IMAGES || parsed > MAX_PARTIAL_IMAGES) {
+    throw new Error(`${name} 必须是 1 到 3 的整数。`);
+  }
+  return parsed;
+}
+
+function readNonNegativeInteger(value, name) {
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : NaN;
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${name} 必须是非负整数。`);
+  }
+  return parsed;
+}
+
+function appendFile(formData, field, filePath) {
+  const buffer = fs.readFileSync(filePath);
+  formData.append(field, new Blob([buffer], { type: mimeTypeForPath(filePath) }), path.basename(filePath));
+}
+
+async function fetchJson(url, init) {
+  const { response, text } = await fetchText(url, init);
+  let result = null;
+  try {
+    result = text ? JSON.parse(text) : null;
+  } catch (error) {
+    if (response.ok) throw new Error(`响应不是有效 JSON：${errorMessage(error)}`);
+  }
+  return { response, result, text };
+}
+
+async function fetchText(url, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    return { response, text: await response.text() };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readErrorMessage(result) {
+  if (typeof result?.error === 'string') return result.error;
+  if (typeof result?.error?.message === 'string') return result.error.message;
+  return undefined;
+}
+
+function enrichImageUrls(result) {
+  if (!result || !Array.isArray(result.images)) return result;
+  return {
+    ...result,
+    images: result.images.map((image) => ({
+      ...image,
+      ...(image.content_url ? { absolute_content_url: new URL(image.content_url, `${baseUrl}/`).toString() } : {}),
+      ...(image.metadata_url ? { absolute_metadata_url: new URL(image.metadata_url, `${baseUrl}/`).toString() } : {})
+    }))
+  };
+}
+
+async function assertDimensions(task, response) {
+  const expected = parseExpectedSize(task.raw.size || (task.mode === 'generate' ? '1024x1024' : undefined));
+  if (!expected) throw new Error(`${task.id} --dimension-check 需要 size 为 WIDTHxHEIGHT。`);
+  if (!Array.isArray(response.images)) return;
+  for (const image of response.images) {
+    const bytes = await readImageBytes(image);
+    const actual = readImageDimensions(bytes);
+    if (actual.width !== expected.width || actual.height !== expected.height) {
+      throw new Error(`${task.id} 尺寸校验失败：期望 ${expected.width}x${expected.height}，实际 ${actual.width}x${actual.height}。`);
+    }
+  }
+}
+
+async function readImageBytes(image) {
+  if (image.b64_json) return Buffer.from(image.b64_json, 'base64');
+  const url = image.absolute_content_url || image.content_url;
+  if (!url) throw new Error('dimension-check 需要 b64_json 或 content_url。');
+  const resolved = resolveSameOriginUrl(baseUrl, url, 'content_url');
+  const { response, bytes } = await fetchBytes(resolved, { headers: authHeaders() });
+  if (!response.ok) throw new Error(`下载产物失败，状态码 ${response.status}。`);
+  return bytes;
+}
+
+function parseExpectedSize(size) {
+  return parseImageSizeValue(size);
+}
+
+function readImageDimensions(buffer) {
+  if (buffer.length >= 24 && buffer.toString('ascii', 1, 4) === 'PNG') {
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  }
+  if (buffer.length >= 12 && buffer.toString('ascii', 0, 4) === 'RIFF' && buffer.toString('ascii', 8, 12) === 'WEBP') {
+    return readWebpDimensions(buffer);
+  }
+  return readJpegDimensions(buffer);
+}
+
+async function fetchBytes(url, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    return { response, bytes: Buffer.from(await response.arrayBuffer()) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readJpegDimensions(buffer) {
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) break;
+    const marker = buffer[offset + 1];
+    const length = buffer.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xc3) {
+      return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) };
+    }
+    offset += 2 + length;
+  }
+  throw new Error('无法读取图片尺寸。');
+}
+
+function readWebpDimensions(buffer) {
+  const chunk = buffer.toString('ascii', 12, 16);
+  if (chunk === 'VP8X') {
+    return { width: 1 + buffer.readUIntLE(24, 3), height: 1 + buffer.readUIntLE(27, 3) };
+  }
+  if (chunk === 'VP8L') {
+    const bits = buffer.readUInt32LE(21);
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === 'VP8 ') return { width: buffer.readUInt16LE(26) & 0x3fff, height: buffer.readUInt16LE(28) & 0x3fff };
+  throw new Error('无法读取 WebP 图片尺寸。');
+}
+
+function readCompletedManifestKeys(filePath) {
+  if (!fs.existsSync(filePath)) return new Set();
+  const keys = new Set();
+  for (const line of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.status === 'succeeded') {
+      if (entry.id) keys.add(entry.id);
+      if (entry.idempotency_key) keys.add(entry.idempotency_key);
+    }
+  }
+  return keys;
+}
+
+function appendManifest(filePath, entry) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+}
+
+function baseManifestEntry(task) {
+  return {
+    at: new Date().toISOString(),
+    index: task.index,
+    id: task.id,
+    mode: task.mode,
+    idempotency_key: task.idempotencyKey,
+    attempt: task.attempt || 1,
+    ...(task.rootIdempotencyKey && task.rootIdempotencyKey !== task.idempotencyKey
+      ? { root_idempotency_key: task.rootIdempotencyKey }
+      : {})
+  };
+}
+
+function sanitizeResponse(response) {
+  if (!response || !Array.isArray(response.images)) return response;
+  return {
+    ...response,
+    images: response.images.map((image) => ({
+      ...image,
+      ...(image.b64_json ? { b64_json_length: image.b64_json.length, b64_json: undefined } : {})
+    }))
+  };
+}
+
+function mimeTypeForPath(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.webp') return 'image/webp';
+  return 'image/png';
+}
+
+function printUsage() {
+  console.error('用法：batch-images.mjs --input tasks.jsonl [options]');
+  console.error('默认只输出 dry-run；添加 --allow-billable 才会按 routing rules 逐行真实请求 Agent API 或页面 SSE。');
+  console.error('常用参数：--manifest --resume --ordered-prefix --dimension-check --max-attempts --max-consecutive-failures --concurrency --timeout-ms --dry-run --allow-billable');
+}

skills/gpt-image-playground-agent/scripts/edit-image.mjs

@@ -4,12 +4,40 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
   errorMessage,
+  assertValidImageSizeForModel,
   normalizeBaseUrl,
+  normalizeOutputFormat,
   parseRetryAfterValue,
   readConfiguredPositiveInteger,
+  readMaxImageEdge,
   readOptionValue,
   sleep
 } from './lib/script-utils.mjs';
+import {
+  PAGE_SSE_ENDPOINT,
+  assertPageSseReady,
+  assertPageSseStreamingAllowed,
+  buildPageSseFailureOutput,
+  formatPageSseOutput,
+  normalizeImageBackendForPage,
+  postPageSse
+} from './lib/page-sse-client.mjs';
+
+const STREAM_MODES = new Set(['auto', 'stream', 'non_stream']);
+const STREAMING_STRATEGIES = new Set([
+  'off',
+  'auto',
+  'openai-sse',
+  'newapi-keepalive-sse',
+  'responses-sse',
+  'force-sse'
+]);
+const IMAGE_BACKENDS = new Set(['images-api', 'images', 'responses', 'responses-image-generation']);
+const OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp']);
+const MODERATIONS = new Set(['low', 'auto']);
+const THINKING_VALUES = new Set(['minimal', 'none', 'low', 'medium', 'high', 'xhigh']);
+const MIN_PARTIAL_IMAGES = 1;
+const MAX_PARTIAL_IMAGES = 3;
 
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
@@ -29,6 +57,15 @@ if (options.help) {
   process.exit(0);
 }
 
+try {
+  validateUpstreamStreamingOptions(options);
+  options.size = assertValidImageSizeForModel(options.size, options.model, '--size');
+} catch (error) {
+  console.error(errorMessage(error));
+  printUsage();
+  process.exit(2);
+}
+
 let maxAttempts;
 let timeoutMs;
 try {
@@ -62,7 +99,7 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
         ok: true,
         billable: false,
         dry_run: true,
-        endpoint: `${baseUrl}/api/agent/images/edit`,
+        endpoint: `${baseUrl}${routingGuidance.recommended_endpoint}`,
         routing_guidance: routingGuidance,
         idempotency_key: idempotencyKey,
         request: {
@@ -71,7 +108,21 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
           model: options.model,
           size: options.size,
           quality: options.quality,
-          response_mode: options.responseMode
+          response_mode: options.responseMode,
+          ...(options.streamMode ? { stream_mode: options.streamMode } : {}),
+          ...(options.streamingStrategy ? { streaming_strategy: options.streamingStrategy } : {}),
+          ...(options.partialImages ? { partial_images: readPartialImages(options.partialImages) } : {}),
+          ...(options.format ? { output_format: readOutputFormat(options) } : {}),
+          ...(readOutputCompression(options) !== undefined ? { output_compression: readOutputCompression(options) } : {}),
+          ...(options.moderation ? { moderation: options.moderation } : {}),
+          ...(options.imageBackend ? { image_backend: normalizeImageBackendForPage(options.imageBackend) } : {}),
+          ...(options.responsesModel ? { responsesModel: readNonEmptyString(options.responsesModel, '--responses-model') } : {}),
+          ...(options.thinking ? { thinking: options.thinking } : {}),
+          ...(options.promptOptimization !== undefined
+            ? { promptOptimization: readBooleanOption(options.promptOptimization, '--prompt-optimization') }
+            : {}),
+          ...(options.forceWeb !== undefined ? { force_web: true } : {}),
+          ...(readEditNormalizations(options) ? { normalizations: readEditNormalizations(options) } : {})
         },
         next_step: '重新执行并添加 --allow-billable 才会发起真实图片编辑请求。'
       },
@@ -83,20 +134,13 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
 }
 
 const routingGuidance = buildEditRoutingGuidance(options);
-if (routingGuidance.strength === 'must_use') {
-  console.error(
-    JSON.stringify(
-      {
-        ok: false,
-        billable: false,
-        error: '当前请求命中高分辨率 edit 路由硬规则；请使用页面端 /api/images form-data SSE 路径。',
-        routing_guidance: routingGuidance
-      },
-      null,
-      2
-    )
-  );
-  process.exit(2);
+if (routingGuidance.transport === 'page_sse') {
+  try {
+    assertPageSseStreamingAllowed(options);
+  } catch (error) {
+    console.error(errorMessage(error));
+    process.exit(2);
+  }
 }
 
 function parseArgs(argv) {
@@ -105,6 +149,19 @@ function parseArgs(argv) {
     size: 'auto',
     quality: 'auto',
     responseMode: 'path',
+    routeMode: 'auto',
+    streamMode: undefined,
+    streamingStrategy: undefined,
+    partialImages: undefined,
+    format: undefined,
+    outputCompression: undefined,
+    moderation: undefined,
+    imageBackend: undefined,
+    responsesModel: undefined,
+    thinking: undefined,
+    promptOptimization: undefined,
+    forceWeb: undefined,
+    sseLogPath: undefined,
     timeoutMs: undefined,
     idempotencyKey: undefined,
     imagePath: undefined,
@@ -123,6 +180,20 @@ function parseArgs(argv) {
     else if (arg === '--size') parsed.size = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--quality') parsed.quality = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--response-mode') parsed.responseMode = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--agent') parsed.routeMode = 'agent';
+    else if (arg === '--page-sse') parsed.routeMode = 'page_sse';
+    else if (arg === '--stream-mode') parsed.streamMode = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--streaming-strategy') parsed.streamingStrategy = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--partial-images') parsed.partialImages = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--format' || arg === '--output-format') parsed.format = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--output-compression') parsed.outputCompression = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--moderation') parsed.moderation = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--image-backend') parsed.imageBackend = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--responses-model' || arg === '--gpt-model') parsed.responsesModel = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--thinking') parsed.thinking = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--prompt-optimization') parsed.promptOptimization = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--force-web') parsed.forceWeb = true;
+    else if (arg === '--sse-log') parsed.sseLogPath = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
     else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
@@ -144,12 +215,37 @@ function absoluteUrl(value) {
 }
 
 function buildEditRoutingGuidance(parsed) {
-  if (readMaxImageEdge(parsed.size) > 2048) {
+  if (parsed.routeMode === 'agent') {
+    assertNoPageOnlyEditOptions(parsed, 'Agent edit');
+    return {
+      recommended_endpoint: '/api/agent/images/edit',
+      transport: 'agent_json',
+      strength: 'default',
+      reason: 'Explicit --agent requests use the Agent JSON edit response contract.'
+    };
+  }
+  if (parsed.routeMode === 'page_sse') {
     return {
       recommended_endpoint: '/api/images',
       transport: 'page_sse',
-      strength: 'must_use',
-      reason: 'Agent edit is non-streaming; high-resolution edit should use the page form-data SSE endpoint.'
+      strength: 'default',
+      reason: 'Explicit --page-sse requests use the page form-data SSE endpoint.'
+    };
+  }
+  if (hasPageOnlyEditOptions(parsed) && isPageSseAllowed(parsed)) {
+    return {
+      recommended_endpoint: '/api/images',
+      transport: 'page_sse',
+      strength: 'default',
+      reason: 'GPT2Image-compatible edit options require the page form-data SSE endpoint; Agent JSON edit does not accept those fields.'
+    };
+  }
+  if (readMaxImageEdge(parsed.size) > 2048 && isPageSseAllowed(parsed)) {
+    return {
+      recommended_endpoint: '/api/images',
+      transport: 'page_sse',
+      strength: 'default',
+      reason: 'High-resolution edit defaults to the page form-data SSE endpoint; if streaming has issues, diagnose first and explicitly fall back to Agent edit.'
     };
   }
   return {
@@ -160,13 +256,6 @@ function buildEditRoutingGuidance(parsed) {
   };
 }
 
-function readMaxImageEdge(size) {
-  if (typeof size !== 'string') return 0;
-  const match = size.match(/^(\d+)x(\d+)$/);
-  if (!match) return 0;
-  return Math.max(Number(match[1]), Number(match[2]));
-}
-
 function enrichImageUrls(result) {
   if (!result || !Array.isArray(result.images)) return result;
   return {
@@ -196,10 +285,117 @@ async function readCapabilities() {
   return response.json();
 }
 
+function assertPageSseReadyForEdit(capabilities) {
+  assertPageSseReady({
+    capabilities,
+    passwordHash,
+    idempotencyKey
+  });
+}
+
 function shouldRetry(result) {
   return Boolean(result?.error?.retryable);
 }
 
+function validateUpstreamStreamingOptions(parsed) {
+  if (parsed.streamMode && !STREAM_MODES.has(parsed.streamMode)) {
+    throw new Error('--stream-mode 必须是 auto、stream 或 non_stream。');
+  }
+  if (parsed.streamingStrategy && !STREAMING_STRATEGIES.has(parsed.streamingStrategy)) {
+    throw new Error(
+      '--streaming-strategy 必须是 off、auto、openai-sse、newapi-keepalive-sse、responses-sse 或 force-sse。'
+    );
+  }
+  if (parsed.routeMode === 'page_sse') {
+    assertPageSseStreamingAllowed(parsed);
+  }
+  if (hasPageOnlyEditOptions(parsed) && !isPageSseAllowed(parsed)) {
+    throw new Error('图生图高级参数需要页面 SSE，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。');
+  }
+  if (parsed.routeMode === 'agent') {
+    assertNoPageOnlyEditOptions(parsed, 'Agent edit');
+  }
+  if (parsed.format && !OUTPUT_FORMATS.has(readOutputFormat(parsed))) {
+    throw new Error('--format 必须是 png、jpeg 或 webp。');
+  }
+  if (parsed.outputCompression !== undefined) readOutputCompression(parsed);
+  if (parsed.moderation && !MODERATIONS.has(parsed.moderation)) {
+    throw new Error('--moderation 必须是 low 或 auto。');
+  }
+  if (parsed.imageBackend && !IMAGE_BACKENDS.has(parsed.imageBackend)) {
+    throw new Error('--image-backend 必须是 images-api、images、responses 或 responses-image-generation。');
+  }
+  if (parsed.responsesModel !== undefined) readNonEmptyString(parsed.responsesModel, '--responses-model');
+  if (parsed.thinking && !THINKING_VALUES.has(parsed.thinking)) {
+    throw new Error('--thinking 必须是 minimal、none、low、medium、high 或 xhigh。');
+  }
+  if (parsed.promptOptimization !== undefined) readBooleanOption(parsed.promptOptimization, '--prompt-optimization');
+  if (parsed.partialImages) readPartialImages(parsed.partialImages);
+}
+
+function hasPageOnlyEditOptions(parsed) {
+  return Boolean(
+    parsed.format ||
+      parsed.outputCompression !== undefined ||
+      parsed.moderation ||
+      parsed.imageBackend ||
+      parsed.responsesModel ||
+      parsed.thinking ||
+      parsed.promptOptimization !== undefined ||
+      parsed.forceWeb !== undefined
+  );
+}
+
+function assertNoPageOnlyEditOptions(parsed, context) {
+  if (!hasPageOnlyEditOptions(parsed)) return;
+  throw new Error(`${context} 不接受图生图高级页面字段；请去掉这些字段或使用 --page-sse。`);
+}
+
+function readOutputFormat(parsed) {
+  return parsed.format ? normalizeOutputFormat(parsed.format) : 'png';
+}
+
+function readOutputCompression(parsed) {
+  if (parsed.outputCompression === undefined) return undefined;
+  const outputFormat = readOutputFormat(parsed);
+  if (outputFormat === 'png') return undefined;
+  const value = String(parsed.outputCompression);
+  if (!/^\d+$/.test(value)) throw new Error('--output-compression 必须是 0 到 100 之间的整数。');
+  const parsedValue = Number(value);
+  if (!Number.isInteger(parsedValue) || parsedValue < 0 || parsedValue > 100) {
+    throw new Error('--output-compression 必须是 0 到 100 之间的整数。');
+  }
+  return parsedValue;
+}
+
+function readEditNormalizations(parsed) {
+  if (parsed.outputCompression === undefined || readOutputFormat(parsed) !== 'png') return undefined;
+  return { output_compression_ignored_for_png: true };
+}
+
+function readBooleanOption(value, name) {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  throw new Error(`${name} 必须是 true 或 false。`);
+}
+
+function readNonEmptyString(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} 必须是非空字符串。`);
+  return value.trim();
+}
+
+function isPageSseAllowed(parsed) {
+  return parsed.streamMode !== 'non_stream' && parsed.streamingStrategy !== 'off';
+}
+
+function readPartialImages(value) {
+  const parsed = readConfiguredPositiveInteger(value, '--partial-images', 2);
+  if (parsed < MIN_PARTIAL_IMAGES || parsed > MAX_PARTIAL_IMAGES) {
+    throw new Error('--partial-images 必须是 1 到 3 的整数。');
+  }
+  return parsed;
+}
+
 async function fetchWithTimeout(url, init) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -213,12 +409,13 @@ async function fetchWithTimeout(url, init) {
 function printUsage() {
   console.error('用法：edit-image.mjs [options] <image-path> <prompt>');
   console.error('默认只输出 dry-run；添加 --allow-billable 才会真实编辑图片。');
-  console.error('常用参数：--model --size --quality --response-mode --timeout-ms --idempotency-key --dry-run --allow-billable');
+  console.error('常用参数：--model --size --quality --response-mode --format --output-compression --moderation --image-backend --responses-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --idempotency-key --page-sse --agent --dry-run --allow-billable');
   console.error('契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 edit-image.mjs 或 edit-image.mjs --contract-check');
 }
 
+let capabilities;
 try {
-  await readCapabilities();
+  capabilities = await readCapabilities();
 } catch (error) {
   console.error(errorMessage(error));
   process.exit(1);
@@ -265,10 +462,74 @@ function buildFormData() {
   formData.append('size', options.size);
   formData.append('quality', options.quality);
   formData.append('response_mode', options.responseMode);
+  if (options.streamMode) formData.append('stream_mode', options.streamMode);
+  if (options.streamingStrategy) formData.append('streaming_strategy', options.streamingStrategy);
+  if (options.partialImages) formData.append('partial_images', String(readPartialImages(options.partialImages)));
   formData.append('image_0', new Blob([imageBuffer], { type: imageType }), path.basename(imagePath));
   return formData;
 }
 
+function buildPageSseFormData() {
+  const formData = new FormData();
+  formData.append('mode', 'edit');
+  formData.append('prompt', prompt);
+  formData.append('model', options.model);
+  formData.append('size', options.size);
+  formData.append('quality', options.quality);
+  formData.append('response_mode', options.responseMode);
+  formData.append('clientRequestId', idempotencyKey);
+  formData.append('stream', 'true');
+  if (options.format) formData.append('output_format', readOutputFormat(options));
+  if (readOutputCompression(options) !== undefined) {
+    formData.append('output_compression', String(readOutputCompression(options)));
+  }
+  if (options.moderation) formData.append('moderation', options.moderation);
+  if (options.imageBackend) formData.append('image_backend', normalizeImageBackendForPage(options.imageBackend));
+  if (options.responsesModel) formData.append('responsesModel', readNonEmptyString(options.responsesModel, '--responses-model'));
+  if (options.thinking) formData.append('thinking', options.thinking);
+  if (options.promptOptimization !== undefined) {
+    formData.append('promptOptimization', String(readBooleanOption(options.promptOptimization, '--prompt-optimization')));
+  }
+  if (options.forceWeb !== undefined) formData.append('force_web', 'true');
+  if (options.streamMode) formData.append('stream_mode', options.streamMode);
+  if (options.streamingStrategy) formData.append('image_streaming_strategy', options.streamingStrategy);
+  if (options.partialImages) formData.append('partial_images', String(readPartialImages(options.partialImages)));
+  if (passwordHash) formData.append('passwordHash', passwordHash);
+  formData.append('image_0', new Blob([imageBuffer], { type: imageType }), path.basename(imagePath));
+  return formData;
+}
+
+async function runPageSseEdit() {
+  assertPageSseReadyForEdit(capabilities);
+  const result = await postPageSse({
+    url: `${baseUrl}${PAGE_SSE_ENDPOINT}`,
+    formData: buildPageSseFormData(),
+    timeoutMs,
+    sseLogPath: options.sseLogPath,
+    errorMessage
+  });
+  console.log(
+    JSON.stringify(
+      {
+        ...formatPageSseOutput({
+          result,
+          baseUrl,
+          responseMode: options.responseMode,
+          defaultOutputFormat: 'png'
+        }),
+        routing: {
+          transport: 'page_sse',
+          endpoint: PAGE_SSE_ENDPOINT,
+          fallback_endpoint: '/api/agent/images/edit',
+          fallback_mode: 'manual_after_diagnosis'
+        }
+      },
+      null,
+      2
+    )
+  );
+}
+
 function mimeTypeForPath(filePath) {
   const ext = path.extname(filePath).toLowerCase();
   if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
@@ -279,6 +540,26 @@ function mimeTypeForPath(filePath) {
 let lastResult;
 let lastRetryAfter = null;
 
+if (routingGuidance.transport === 'page_sse') {
+  try {
+    await runPageSseEdit();
+    process.exit(0);
+  } catch (error) {
+    console.error(
+      JSON.stringify(
+        buildPageSseFailureOutput({
+          error,
+          fallbackEndpoint: '/api/agent/images/edit',
+          errorMessage
+        }),
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+}
+
 for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
   let response;
   let result;

skills/gpt-image-playground-agent/scripts/generate-image.mjs

@@ -1,46 +1,51 @@
 #!/usr/bin/env node
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import { AGENT_ENDPOINTS, buildAgentJobResultPath } from '../../../src/lib/agent-api-paths.mjs';
+import { AGENT_ENDPOINTS, buildAgentJobResultPath } from './lib/agent-api-paths.mjs';
 import {
-  errorMessage,
-  normalizeBaseUrl,
-  normalizeOutputFormat,
-  parseRetryAfterValue,
-  readConfiguredPositiveInteger,
-  readOptionValue,
-  resolveSameOriginUrl,
-  sleep
+    errorMessage,
+    assertValidImageSizeForModel,
+    normalizeBaseUrl,
+    normalizeOutputFormat,
+    parseRetryAfterValue,
+    readConfiguredPositiveInteger,
+    readMaxImageEdge,
+    readOptionValue,
+    resolveSameOriginUrl,
+    sleep
 } from './lib/script-utils.mjs';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 
 const IMAGE_BACKENDS = new Set(['images-api', 'images', 'responses', 'responses-image-generation']);
 const RESPONSE_MODES = new Set(['path', 'base64', 'both']);
 const STREAMING_STRATEGIES = new Set([
-  'off',
-  'auto',
-  'openai-sse',
-  'newapi-keepalive-sse',
-  'responses-sse',
-  'force-sse'
+    'off',
+    'auto',
+    'openai-sse',
+    'newapi-keepalive-sse',
+    'responses-sse',
+    'force-sse'
 ]);
+const STREAM_MODES = new Set(['auto', 'stream', 'non_stream']);
 const MIN_PARTIAL_IMAGES = 1;
 const MAX_PARTIAL_IMAGES = 3;
-const MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH = 128;
+const DEFAULT_PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH = 128;
 const PAGE_SSE_ENDPOINT = '/api/images';
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 const contractCheck = process.env.GPT_IMAGE_AGENT_CONTRACT_CHECK === '1' || process.argv.includes('--contract-check');
+let pageSseClientRequestIdMaxLength = DEFAULT_PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH;
 let options;
 try {
-  options = parseArgs(process.argv.slice(2));
+    options = parseArgs(process.argv.slice(2));
 } catch (error) {
-  console.error(errorMessage(error));
-  printUsage();
-  process.exit(2);
+    console.error(errorMessage(error));
+    printUsage();
+    process.exit(2);
 }
 if (options.help) {
-  printUsage();
-  process.exit(0);
+    printUsage();
+    process.exit(0);
 }
 
 let prompt;
@@ -49,908 +54,1017 @@ let timeoutMs;
 let idempotencyKey;
 let requestBody;
 try {
-  maxAttempts = readConfiguredPositiveInteger(process.env.GPT_IMAGE_AGENT_MAX_ATTEMPTS, 'GPT_IMAGE_AGENT_MAX_ATTEMPTS', 3);
-  timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
-  idempotencyKey = options.idempotencyKey || process.env.GPT_IMAGE_AGENT_IDEMPOTENCY_KEY || `agent-generate-${crypto.randomUUID()}`;
-  if (isNonBillableDryRun(options, contractCheck)) {
-    if (!hasPromptSource(options)) {
-      printUsage();
-      process.exit(2);
-    }
-    requestBody = buildDryRunRequestBody(options);
-  } else {
-    prompt = readPrompt(options, { readPromptFile: !contractCheck });
-    requestBody = buildRequestBody(prompt, options);
-  }
+    maxAttempts = readConfiguredPositiveInteger(
+        process.env.GPT_IMAGE_AGENT_MAX_ATTEMPTS,
+        'GPT_IMAGE_AGENT_MAX_ATTEMPTS',
+        3
+    );
+    timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
+    idempotencyKey =
+        options.idempotencyKey ||
+        process.env.GPT_IMAGE_AGENT_IDEMPOTENCY_KEY ||
+        `agent-generate-${crypto.randomUUID()}`;
+    if (isNonBillableDryRun(options, contractCheck)) {
+        if (!hasPromptSource(options)) {
+            printUsage();
+            process.exit(2);
+        }
+        requestBody = buildDryRunRequestBody(options);
+    } else {
+        prompt = readPrompt(options, { readPromptFile: !contractCheck });
+        requestBody = buildRequestBody(prompt, options);
+    }
 } catch (error) {
-  console.error(errorMessage(error));
-  printUsage();
-  process.exit(2);
+    console.error(errorMessage(error));
+    printUsage();
+    process.exit(2);
 }
 
 if (!isNonBillableDryRun(options, contractCheck) && !prompt && !contractCheck) {
-  printUsage();
-  process.exit(2);
+    printUsage();
+    process.exit(2);
 }
 
 let baseUrl;
 try {
-  baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+    baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
 } catch (error) {
-  console.error(errorMessage(error));
-  process.exit(2);
+    console.error(errorMessage(error));
+    process.exit(2);
 }
 
 if (isNonBillableDryRun(options, contractCheck)) {
-  console.log(
-    JSON.stringify(
-      {
-        ok: true,
-        billable: false,
-        dry_run: true,
-        endpoint: dryRunEndpoint(requestBody, options.routeMode),
-        route_mode: options.routeMode,
-        routing_guidance: buildGenerateRoutingGuidance(requestBody, options.routeMode),
-        idempotency_key: idempotencyKey,
-        request: requestBody,
-        next_step: '重新执行并添加 --allow-billable 才会发起真实生图请求。'
-      },
-      null,
-      2
-    )
-  );
-  process.exit(0);
+    console.log(
+        JSON.stringify(
+            {
+                ok: true,
+                billable: false,
+                dry_run: true,
+                endpoint: dryRunEndpoint(requestBody, options.routeMode),
+                route_mode: options.routeMode,
+                routing_guidance: buildGenerateRoutingGuidance(requestBody, options.routeMode),
+                idempotency_key: idempotencyKey,
+                request: requestBody,
+                next_step: '重新执行并添加 --allow-billable 才会发起真实生图请求。'
+            },
+            null,
+            2
+        )
+    );
+    process.exit(0);
 }
 
-try {
-  var capabilities = await readCapabilities();
-} catch (error) {
-  if (isScriptError(error)) {
-    console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
-    process.exit(1);
-  }
-  console.error(errorMessage(error));
-  process.exit(1);
-}
+const capabilities = await readCapabilitiesOrExit();
+applyCapabilitiesRuntimeValues(capabilities);
 
 if (contractCheck) {
-  await runContractCheck(capabilities);
-  process.exit(0);
+    await runContractCheck(capabilities);
+    process.exit(0);
 }
 
 try {
-  if (shouldUseJobPolling(capabilities, options.routeMode)) {
-    await runGenerateJob();
-  } else if (shouldUsePageSse(capabilities, requestBody, options.routeMode)) {
-    try {
-      const result = await runPageSseRequest();
-      console.log(
-        JSON.stringify(
-          buildSuccessOutput(formatPageSseOutput(result), { transport: 'page_sse', endpoint: PAGE_SSE_ENDPOINT }),
-          null,
-          2
-        )
-      );
-      process.exit(0);
-    } catch (error) {
-      console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
-      process.exit(1);
+    if (shouldUseJobPolling(capabilities, options.routeMode)) {
+        await runGenerateJob();
+    } else if (shouldUsePageSse(capabilities, requestBody, options.routeMode)) {
+        try {
+            const result = await runPageSseRequest();
+            console.log(
+                JSON.stringify(
+                    buildSuccessOutput(formatPageSseOutput(result), {
+                        transport: 'page_sse',
+                        endpoint: PAGE_SSE_ENDPOINT
+                    }),
+                    null,
+                    2
+                )
+            );
+            process.exit(0);
+        } catch (error) {
+            console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+            process.exit(1);
+        }
+    } else {
+        await runGenerateRequest({ routing: { transport: 'agent_json', endpoint: AGENT_ENDPOINTS.generate } });
     }
-  } else {
-    await runGenerateRequest({ routing: { transport: 'agent_json', endpoint: AGENT_ENDPOINTS.generate } });
-  }
 } catch (error) {
-  if (isScriptError(error)) {
-    console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+    if (isScriptError(error)) {
+        console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+        process.exit(1);
+    }
+    console.error(errorMessage(error));
     process.exit(1);
-  }
-  console.error(errorMessage(error));
-  process.exit(1);
 }
 
 function parseArgs(argv) {
-  const parsed = {
-    model: 'gpt-image-2',
-    size: '1024x1024',
-    quality: 'high',
-    n: '1',
-    format: 'png',
-    responseMode: 'path',
-    imageBackend: undefined,
-    streamingStrategy: undefined,
-    partialImages: undefined,
-    timeoutMs: undefined,
-    promptFile: undefined,
-    idempotencyKey: undefined,
-    routeMode: 'auto',
-    dryRun: false,
-    allowBillable: false,
-    help: false,
-    promptParts: []
-  };
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === '--dry-run') parsed.dryRun = true;
-    else if (arg === '--allow-billable') parsed.allowBillable = true;
-    else if (arg === '--job') parsed.routeMode = 'job';
-    else if (arg === '--no-job' || arg === '--agent') parsed.routeMode = 'agent';
-    else if (arg === '--page-sse') parsed.routeMode = 'page_sse';
-    else if (arg === '--help' || arg === '-h') parsed.help = true;
-    else if (arg === '--contract-check') continue;
-    else if (arg === '--model') parsed.model = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--size') parsed.size = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--quality') parsed.quality = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--n') parsed.n = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--format') parsed.format = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--response-mode') parsed.responseMode = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--image-backend') parsed.imageBackend = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--streaming-strategy') parsed.streamingStrategy = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--partial-images') parsed.partialImages = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--prompt-file') parsed.promptFile = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
-    else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
-    else parsed.promptParts.push(arg);
-  }
-  return parsed;
+    const parsed = {
+        model: 'gpt-image-2',
+        size: '1024x1024',
+        quality: 'high',
+        n: '1',
+        format: 'png',
+        responseMode: 'path',
+        imageBackend: undefined,
+        streamMode: undefined,
+        streamingStrategy: undefined,
+        partialImages: undefined,
+        sseLogPath: undefined,
+        timeoutMs: undefined,
+        promptFile: undefined,
+        idempotencyKey: undefined,
+        routeMode: 'auto',
+        dryRun: false,
+        allowBillable: false,
+        help: false,
+        promptParts: []
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--dry-run') parsed.dryRun = true;
+        else if (arg === '--allow-billable') parsed.allowBillable = true;
+        else if (arg === '--job') parsed.routeMode = 'job';
+        else if (arg === '--no-job' || arg === '--agent') parsed.routeMode = 'agent';
+        else if (arg === '--page-sse') parsed.routeMode = 'page_sse';
+        else if (arg === '--help' || arg === '-h') parsed.help = true;
+        else if (arg === '--contract-check') continue;
+        else if (arg === '--model') parsed.model = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--size') parsed.size = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--quality') parsed.quality = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--n') parsed.n = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--format') parsed.format = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--response-mode') parsed.responseMode = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--image-backend') parsed.imageBackend = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--stream-mode') parsed.streamMode = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--streaming-strategy') parsed.streamingStrategy = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--partial-images') parsed.partialImages = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--sse-log') parsed.sseLogPath = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--prompt-file') parsed.promptFile = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
+        else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
+        else parsed.promptParts.push(arg);
+    }
+    return parsed;
 }
 
 function readPrompt(parsed, { readPromptFile }) {
-  if (parsed.promptFile) {
-    if (readPromptFile) {
-      return fs.readFileSync(parsed.promptFile, 'utf8');
+    if (parsed.promptFile) {
+        if (readPromptFile) {
+            return fs.readFileSync(parsed.promptFile, 'utf8');
+        }
+        return parsed.promptParts.join(' ') || 'contract check';
     }
-    return parsed.promptParts.join(' ') || 'contract check';
-  }
-  return parsed.promptParts.join(' ');
+    return parsed.promptParts.join(' ');
 }
 
 function buildRequestBody(promptValue, parsed) {
-  return addUpstreamStrategyFields(
-    {
-      prompt: promptValue || 'contract check',
-      model: parsed.model,
-      n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
-      size: parsed.size,
-      quality: parsed.quality,
-      output_format: normalizeOutputFormat(parsed.format),
-      response_mode: parsed.responseMode
-    },
-    parsed
-  );
+    return addUpstreamStrategyFields(
+        {
+            prompt: promptValue || 'contract check',
+            model: parsed.model,
+            n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
+            size: assertValidImageSizeForModel(parsed.size, parsed.model, '--size'),
+            quality: parsed.quality,
+            output_format: normalizeOutputFormat(parsed.format),
+            response_mode: parsed.responseMode
+        },
+        parsed
+    );
 }
 
 function buildDryRunRequestBody(parsed) {
-  const body = addUpstreamStrategyFields(
-    {
-      model: parsed.model,
-      n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
-      size: parsed.size,
-      quality: parsed.quality,
-      output_format: normalizeOutputFormat(parsed.format),
-      response_mode: parsed.responseMode
-    },
-    parsed
-  );
-  if (parsed.promptFile) {
-    return { ...body, prompt_file: parsed.promptFile };
-  }
-  return { ...body, prompt: parsed.promptParts.join(' ') };
+    const body = addUpstreamStrategyFields(
+        {
+            model: parsed.model,
+            n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
+            size: assertValidImageSizeForModel(parsed.size, parsed.model, '--size'),
+            quality: parsed.quality,
+            output_format: normalizeOutputFormat(parsed.format),
+            response_mode: parsed.responseMode
+        },
+        parsed
+    );
+    if (parsed.promptFile) {
+        return { ...body, prompt_file: parsed.promptFile };
+    }
+    return { ...body, prompt: parsed.promptParts.join(' ') };
 }
 
 function addUpstreamStrategyFields(body, parsed) {
-  validateUpstreamStrategyOptions(parsed);
-  return {
-    ...body,
-    ...(parsed.imageBackend ? { image_backend: parsed.imageBackend } : {}),
-    ...(parsed.streamingStrategy ? { streaming_strategy: parsed.streamingStrategy } : {}),
-    ...(parsed.partialImages ? { partial_images: readPartialImages(parsed.partialImages) } : {})
-  };
+    validateUpstreamStrategyOptions(parsed);
+    return {
+        ...body,
+        ...(parsed.imageBackend ? { image_backend: parsed.imageBackend } : {}),
+        ...(parsed.streamMode ? { stream_mode: parsed.streamMode } : {}),
+        ...(parsed.streamingStrategy ? { streaming_strategy: parsed.streamingStrategy } : {}),
+        ...(parsed.partialImages ? { partial_images: readPartialImages(parsed.partialImages) } : {})
+    };
 }
 
 function validateUpstreamStrategyOptions(parsed) {
-  if (!RESPONSE_MODES.has(parsed.responseMode)) {
-    throw new Error('--response-mode 必须是 path、base64 或 both。');
-  }
-  if (parsed.imageBackend && !IMAGE_BACKENDS.has(parsed.imageBackend)) {
-    throw new Error('--image-backend 必须是 images-api、images、responses 或 responses-image-generation。');
-  }
-  if (parsed.streamingStrategy && !STREAMING_STRATEGIES.has(parsed.streamingStrategy)) {
-    throw new Error('--streaming-strategy 必须是 off、auto、openai-sse、newapi-keepalive-sse、responses-sse 或 force-sse。');
-  }
-  if (parsed.routeMode === 'page_sse' && parsed.streamingStrategy === 'off') {
-    throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
-  }
+    if (!RESPONSE_MODES.has(parsed.responseMode)) {
+        throw new Error('--response-mode 必须是 path、base64 或 both。');
+    }
+    if (parsed.imageBackend && !IMAGE_BACKENDS.has(parsed.imageBackend)) {
+        throw new Error('--image-backend 必须是 images-api、images、responses 或 responses-image-generation。');
+    }
+    if (parsed.streamMode && !STREAM_MODES.has(parsed.streamMode)) {
+        throw new Error('--stream-mode 必须是 auto、stream 或 non_stream。');
+    }
+    if (parsed.streamingStrategy && !STREAMING_STRATEGIES.has(parsed.streamingStrategy)) {
+        throw new Error(
+            '--streaming-strategy 必须是 off、auto、openai-sse、newapi-keepalive-sse、responses-sse 或 force-sse。'
+        );
+    }
+    if (parsed.routeMode === 'page_sse' && (parsed.streamingStrategy === 'off' || parsed.streamMode === 'non_stream')) {
+        throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。');
+    }
 }
 
 function readPartialImages(value) {
-  const parsed = readConfiguredPositiveInteger(value, '--partial-images', 2);
-  if (parsed < MIN_PARTIAL_IMAGES || parsed > MAX_PARTIAL_IMAGES) {
-    throw new Error('--partial-images 必须是 1 到 3 的整数。');
-  }
-  return parsed;
+    const parsed = readConfiguredPositiveInteger(value, '--partial-images', 2);
+    if (parsed < MIN_PARTIAL_IMAGES || parsed > MAX_PARTIAL_IMAGES) {
+        throw new Error('--partial-images 必须是 1 到 3 的整数。');
+    }
+    return parsed;
 }
 
 function hasPromptSource(parsed) {
-  return Boolean(parsed.promptFile || parsed.promptParts.length > 0);
+    return Boolean(parsed.promptFile || parsed.promptParts.length > 0);
 }
 
 function isNonBillableDryRun(parsed, isContractCheck) {
-  return parsed.dryRun || (!isContractCheck && !parsed.allowBillable);
+    return parsed.dryRun || (!isContractCheck && !parsed.allowBillable);
 }
 
 function authHeaders() {
-  if (token) return { Authorization: `Bearer ${token}` };
-  if (passwordHash) return { 'X-App-Password-Hash': passwordHash };
-  return {};
+    if (token) return { Authorization: `Bearer ${token}` };
+    if (passwordHash) return { 'X-App-Password-Hash': passwordHash };
+    return {};
 }
 
 function absoluteUrl(value) {
-  if (typeof value !== 'string' || !value) return undefined;
-  return new URL(value, `${baseUrl}/`).toString();
+    if (typeof value !== 'string' || !value) return undefined;
+    return new URL(value, `${baseUrl}/`).toString();
 }
 
 function enrichImageUrls(result) {
-  if (!result || !Array.isArray(result.images)) return result;
-  return {
-    ...result,
-    images: result.images.map((image) => ({
-      ...image,
-      ...(image.content_url ? { absolute_content_url: absoluteUrl(image.content_url) } : {}),
-      ...(image.metadata_url ? { absolute_metadata_url: absoluteUrl(image.metadata_url) } : {})
-    }))
-  };
+    if (!result || !Array.isArray(result.images)) return result;
+    return {
+        ...result,
+        images: result.images.map((image) => ({
+            ...image,
+            ...(image.content_url ? { absolute_content_url: absoluteUrl(image.content_url) } : {}),
+            ...(image.metadata_url ? { absolute_metadata_url: absoluteUrl(image.metadata_url) } : {})
+        }))
+    };
 }
 
 function dryRunEndpoint(body, routeMode) {
-  if (routeMode === 'job') return `${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`;
-  if (routeMode === 'agent') return `${baseUrl}${AGENT_ENDPOINTS.generate}`;
-  if (routeMode === 'page_sse') return `${baseUrl}${PAGE_SSE_ENDPOINT}`;
-  return isLargeGenerate(body) && isPageSseAllowed(body)
-    ? `${baseUrl}${PAGE_SSE_ENDPOINT}`
-    : `${baseUrl}${AGENT_ENDPOINTS.generate}`;
+    if (routeMode === 'job') return `${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`;
+    if (routeMode === 'agent') return `${baseUrl}${AGENT_ENDPOINTS.generate}`;
+    if (routeMode === 'page_sse') return `${baseUrl}${PAGE_SSE_ENDPOINT}`;
+    return isLargeGenerate(body) && isPageSseAllowed(body)
+        ? `${baseUrl}${PAGE_SSE_ENDPOINT}`
+        : `${baseUrl}${AGENT_ENDPOINTS.generate}`;
 }
 
 function buildGenerateRoutingGuidance(body, routeMode) {
-  if (routeMode === 'job') {
-    return {
-      recommended_endpoint: AGENT_ENDPOINTS.create_generate_job,
-      transport: 'agent_job_polling',
-      strength: 'recommended',
-      reason: 'Explicit --job requests use Agent job polling.'
-    };
-  }
-  if (routeMode === 'page_sse' && !isPageSseAllowed(body)) {
-    throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
-  }
-  if ((routeMode === 'page_sse' || (routeMode !== 'agent' && isLargeGenerate(body))) && isPageSseAllowed(body)) {
+    if (routeMode === 'job') {
+        return {
+            recommended_endpoint: AGENT_ENDPOINTS.create_generate_job,
+            transport: 'agent_job_polling',
+            strength: 'recommended',
+            reason: 'Explicit --job requests use Agent job polling.'
+        };
+    }
+    if (routeMode === 'page_sse' && !isPageSseAllowed(body)) {
+        throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。');
+    }
+    if ((routeMode === 'page_sse' || (routeMode !== 'agent' && isLargeGenerate(body))) && isPageSseAllowed(body)) {
+        return {
+            recommended_endpoint: PAGE_SSE_ENDPOINT,
+            transport: 'page_sse',
+            strength: 'recommended',
+            fallback_endpoint: AGENT_ENDPOINTS.generate,
+            fallback_mode: 'manual_after_diagnosis',
+            reason: 'Generate requests with max_edge>2048 should use page form-data SSE first; if the stream fails, diagnose first and rerun manually with Agent JSON.'
+        };
+    }
     return {
-      recommended_endpoint: PAGE_SSE_ENDPOINT,
-      transport: 'page_sse',
-      strength: 'recommended',
-      fallback_endpoint: AGENT_ENDPOINTS.generate,
-      fallback_mode: 'manual_after_diagnosis',
-      reason: 'Generate requests with max_edge>2048 should use page form-data SSE first; if the stream fails, diagnose first and rerun manually with Agent JSON.'
+        recommended_endpoint: AGENT_ENDPOINTS.generate,
+        transport: 'agent_json',
+        strength: 'default',
+        reason: 'Normal single-image generate requests use the Agent JSON response contract.'
     };
-  }
-  return {
-    recommended_endpoint: AGENT_ENDPOINTS.generate,
-    transport: 'agent_json',
-    strength: 'default',
-    reason: 'Normal single-image generate requests use the Agent JSON response contract.'
-  };
 }
 
 async function readCapabilities() {
-  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.capabilities}`, {
-    headers: authHeaders(),
-    timeoutMs
-  });
-  if (!response.ok) {
-    throw new Error(`capabilities 请求失败，状态码 ${response.status}：${text}`);
-  }
-  return result;
+    const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.capabilities}`, {
+        headers: authHeaders(),
+        timeoutMs
+    });
+    if (!response.ok) {
+        throw new Error(`capabilities 请求失败，状态码 ${response.status}：${text}`);
+    }
+    return result;
 }
 
-async function runGenerateRequest(options = {}) {
-  let lastResult;
-  let lastRetryAfter = null;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Idempotency-Key': idempotencyKey,
-        ...authHeaders()
-      },
-      body: JSON.stringify(requestBody),
-      timeoutMs
-    });
+async function readCapabilitiesOrExit() {
+    try {
+        return await readCapabilities();
+    } catch (error) {
+        if (isScriptError(error)) {
+            console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+            process.exit(1);
+        }
+        console.error(errorMessage(error));
+        process.exit(1);
+    }
+}
 
-    if (response.ok) {
-      console.log(JSON.stringify(buildSuccessOutput(enrichImageUrls(result), options.routing), null, 2));
-      process.exit(0);
+function applyCapabilitiesRuntimeValues(capabilitiesValue) {
+    const maxLength = capabilitiesValue?.agent_streaming?.page_sse?.client_request_id?.max_length;
+    if (Number.isSafeInteger(maxLength) && maxLength > 0) {
+        pageSseClientRequestIdMaxLength = maxLength;
     }
+}
 
-    const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
-    lastResult = result;
-    lastRetryAfter = retryAfter;
-    if (!shouldRetry(result) || attempt === maxAttempts) break;
-    await sleep(retryAfter);
-  }
+async function runGenerateRequest(options = {}) {
+    let lastResult;
+    let lastRetryAfter = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Idempotency-Key': idempotencyKey,
+                ...authHeaders()
+            },
+            body: JSON.stringify(requestBody),
+            timeoutMs
+        });
+
+        if (response.ok) {
+            console.log(JSON.stringify(buildSuccessOutput(enrichImageUrls(result), options.routing), null, 2));
+            process.exit(0);
+        }
+
+        const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
+        lastResult = result;
+        lastRetryAfter = retryAfter;
+        if (!shouldRetry(result) || attempt === maxAttempts) break;
+        await sleep(retryAfter);
+    }
 
-  console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
-  process.exit(1);
+    console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
+    process.exit(1);
 }
 
 async function runPageSseRequest() {
-  const url = `${baseUrl}${PAGE_SSE_ENDPOINT}`;
-  const formData = buildPageSseFormData();
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    let response;
+    const url = `${baseUrl}${PAGE_SSE_ENDPOINT}`;
+    const formData = buildPageSseFormData();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      response = await fetch(url, {
-        method: 'POST',
-        body: formData,
-        signal: controller.signal
-      });
-    } catch (error) {
-      throw new Error(`请求失败：${url}。${errorMessage(error)}`);
-    }
-    try {
-      const contentType = response.headers.get('content-type') || '';
-      if (contentType.includes('text/event-stream')) {
-        return await collectPageSseResult(response, controller.signal);
-      }
-      const text = await response.text();
-      if (!response.ok) {
-        throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
-      }
-      return parseJsonResponse(text, true, url);
-    } catch (error) {
-      if (controller.signal.aborted) {
-        throw new Error(`请求失败：${url}。${errorMessage(error)}`);
-      }
-      throw error;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                body: formData,
+                signal: controller.signal
+            });
+        } catch (error) {
+            throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+        }
+        try {
+            const contentType = response.headers.get('content-type') || '';
+            if (contentType.includes('text/event-stream')) {
+                return await collectPageSseResult(response, controller.signal);
+            }
+            const text = await response.text();
+            if (!response.ok) {
+                throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
+            }
+            return parseJsonResponse(text, true, url);
+        } catch (error) {
+            if (controller.signal.aborted) {
+                throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+            }
+            throw error;
+        }
+    } finally {
+        clearTimeout(timeout);
     }
-  } finally {
-    clearTimeout(timeout);
-  }
 }
 
 function assertPageSseReady(capabilitiesValue) {
-  const pageSse = capabilitiesValue?.agent_streaming?.page_sse;
-  if (!supportsPageSse(capabilitiesValue)) {
-    throw createScriptError(
-      'page_sse_unavailable',
-      '大图默认路由需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级到 Agent JSON。'
-    );
-  }
-  if (pageSse?.auth?.required === true && !passwordHash) {
-    throw createScriptError(
-      'page_sse_auth_required',
-      '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
-    );
-  }
+    const pageSse = capabilitiesValue?.agent_streaming?.page_sse;
+    if (!supportsPageSse(capabilitiesValue)) {
+        throw createScriptError(
+            'page_sse_unavailable',
+            '大图默认路由需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级到 Agent JSON。'
+        );
+    }
+    if (pageSse?.auth?.required === true && !passwordHash) {
+        throw createScriptError(
+            'page_sse_auth_required',
+            '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
+        );
+    }
 }
 
 function buildPageSseFormData() {
-  const formData = new FormData();
-  assertPageSseClientRequestIdLength(idempotencyKey);
-  formData.append('mode', 'generate');
-  formData.append('prompt', requestBody.prompt);
-  formData.append('model', requestBody.model);
-  formData.append('n', String(requestBody.n));
-  formData.append('size', requestBody.size);
-  formData.append('quality', requestBody.quality);
-  formData.append('output_format', requestBody.output_format);
-  formData.append('response_mode', requestBody.response_mode);
-  formData.append('clientRequestId', idempotencyKey);
-  formData.append('stream', 'true');
-  formData.append('partial_images', String(requestBody.partial_images || 2));
-  if (requestBody.image_backend) formData.append('image_backend', normalizeImageBackendForPage(requestBody.image_backend));
-  if (requestBody.streaming_strategy) {
-    formData.append('image_streaming_strategy', requestBody.streaming_strategy);
-  }
-  if (requestBody.background) formData.append('background', requestBody.background);
-  if (requestBody.moderation) formData.append('moderation', requestBody.moderation);
-  if (requestBody.output_compression !== undefined) {
-    formData.append('output_compression', String(requestBody.output_compression));
-  }
-  if (passwordHash) formData.append('passwordHash', passwordHash);
-  return formData;
+    const formData = new FormData();
+    assertPageSseClientRequestIdLength(idempotencyKey);
+    formData.append('mode', 'generate');
+    formData.append('prompt', requestBody.prompt);
+    formData.append('model', requestBody.model);
+    formData.append('n', String(requestBody.n));
+    formData.append('size', requestBody.size);
+    formData.append('quality', requestBody.quality);
+    formData.append('output_format', requestBody.output_format);
+    formData.append('response_mode', requestBody.response_mode);
+    formData.append('clientRequestId', idempotencyKey);
+    formData.append('stream', 'true');
+    if (requestBody.stream_mode) formData.append('stream_mode', requestBody.stream_mode);
+    formData.append('partial_images', String(requestBody.partial_images || 2));
+    if (requestBody.image_backend)
+        formData.append('image_backend', normalizeImageBackendForPage(requestBody.image_backend));
+    if (requestBody.streaming_strategy) {
+        formData.append('image_streaming_strategy', requestBody.streaming_strategy);
+    }
+    if (requestBody.background) formData.append('background', requestBody.background);
+    if (requestBody.moderation) formData.append('moderation', requestBody.moderation);
+    if (requestBody.output_compression !== undefined) {
+        formData.append('output_compression', String(requestBody.output_compression));
+    }
+    if (passwordHash) formData.append('passwordHash', passwordHash);
+    return formData;
 }
 
 function assertPageSseClientRequestIdLength(clientRequestId) {
-  if (clientRequestId.length > MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH) {
-    throw createScriptError(
-      'page_sse_client_request_id_too_long',
-      `页面 SSE 的 clientRequestId 不能超过 ${MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH} 个字符；请缩短 Idempotency-Key。`
-    );
-  }
+    if (clientRequestId.length > pageSseClientRequestIdMaxLength) {
+        throw createScriptError(
+            'page_sse_client_request_id_too_long',
+            `页面 SSE 的 clientRequestId 不能超过 ${pageSseClientRequestIdMaxLength} 个字符；请缩短 Idempotency-Key。`
+        );
+    }
 }
 
 function formatPageSseOutput(result) {
-  if (!result || !Array.isArray(result.images)) return result;
-  return {
-    ...result,
-    images: result.images.map((image) => formatPageSseImage(image))
-  };
+    if (!result || !Array.isArray(result.images)) return result;
+    return {
+        ...result,
+        images: result.images.map((image) => formatPageSseImage(image))
+    };
 }
 
 function formatPageSseImage(image) {
-  const output = { ...image };
-  if (output.path) {
-    output.absolute_path = absoluteUrl(output.path);
-    if (requestBody.response_mode === 'path') {
-      delete output.b64_json;
+    const output = { ...image };
+    if (output.path) {
+        output.absolute_path = absoluteUrl(output.path);
+        if (requestBody.response_mode === 'path') {
+            delete output.b64_json;
+        }
     }
-  }
-  return output;
+    return output;
+}
+
+function createPageSseState() {
+    return {
+        completedImages: [],
+        usage: undefined,
+        actualCost: undefined,
+        doneReceived: false,
+        completedEventCount: 0,
+        partialImageCount: 0,
+        lastEventType: undefined
+    };
 }
 
 function normalizeImageBackendForPage(value) {
-  if (value === 'images') return 'images-api';
-  if (value === 'responses') return 'responses-image-generation';
-  return value;
+    if (value === 'images') return 'images-api';
+    if (value === 'responses') return 'responses-image-generation';
+    return value;
 }
 
 function readPageSseClientRequestId(event) {
-  if (typeof event.clientRequestId === 'string') return event.clientRequestId;
-  if (typeof event.client_request_id === 'string') return event.client_request_id;
-  return undefined;
+    if (typeof event.clientRequestId === 'string') return event.clientRequestId;
+    if (typeof event.client_request_id === 'string') return event.client_request_id;
+    return undefined;
 }
 
 function normalizePageSseImage(image, fallbackClientRequestId) {
-  const clientRequestId = image.clientRequestId || image.client_request_id || fallbackClientRequestId;
-  return {
-    ...image,
-    output_format: image.outputFormat || image.output_format || requestBody.output_format,
-    ...(clientRequestId ? { clientRequestId } : {})
-  };
+    const clientRequestId = image.clientRequestId || image.client_request_id || fallbackClientRequestId;
+    return {
+        ...image,
+        output_format: image.outputFormat || image.output_format || requestBody.output_format,
+        ...(clientRequestId ? { clientRequestId } : {})
+    };
 }
 
 function mergePageSseDoneImages(doneImages, completedImages, fallbackClientRequestId) {
-  if (!Array.isArray(doneImages) || doneImages.length === 0) {
-    return completedImages.map((image) => normalizePageSseImage(image, fallbackClientRequestId));
-  }
-  const imageCount = Math.max(doneImages.length, completedImages.length);
-  return Array.from({ length: imageCount }, (_, index) =>
-    normalizePageSseImage({ ...(completedImages[index] || {}), ...(doneImages[index] || {}) }, fallbackClientRequestId)
-  );
+    if (!Array.isArray(doneImages) || doneImages.length === 0) {
+        return completedImages.map((image) => normalizePageSseImage(image, fallbackClientRequestId));
+    }
+    const imageCount = Math.max(doneImages.length, completedImages.length);
+    return Array.from({ length: imageCount }, (_, index) =>
+        normalizePageSseImage(
+            { ...(completedImages[index] || {}), ...(doneImages[index] || {}) },
+            fallbackClientRequestId
+        )
+    );
 }
 
 async function collectPageSseResult(response, signal) {
-  const reader = response.body?.getReader();
-  if (!reader) throw new Error('页面 SSE 响应缺少 body。');
-  const decoder = new TextDecoder();
-  const state = { completedImages: [], usage: undefined, actualCost: undefined, doneReceived: false };
-  let buffer = '';
-  while (true) {
-    const { done, value } = await readPageSseChunk(reader, signal);
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    const events = buffer.split(/\r?\n\r?\n/);
-    buffer = events.pop() || '';
-    for (const rawEvent of events) {
-      applyPageSseEvent(state, rawEvent);
-    }
-  }
-  buffer += decoder.decode();
-  if (buffer.trim()) applyPageSseEvent(state, buffer);
-  if (state.completedImages.length === 0) {
-    throw new Error('页面 SSE 未返回最终图片。');
-  }
-  if (!state.doneReceived) {
-    throw new Error('页面 SSE 缺少最终 done 事件，流式响应可能已提前中断。');
-  }
-  return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost };
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error('页面 SSE 响应缺少 body。');
+    const decoder = new TextDecoder();
+    const state = createPageSseState();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await readPageSseChunk(reader, signal);
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const events = buffer.split(/\r?\n\r?\n/);
+        buffer = events.pop() || '';
+        for (const rawEvent of events) {
+            appendPageSseLog(rawEvent);
+            applyPageSseEvent(state, rawEvent);
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim()) {
+        appendPageSseLog(buffer);
+        applyPageSseEvent(state, buffer);
+    }
+    if (state.completedImages.length === 0) {
+        throw withPageSseDiagnostics(new Error('页面 SSE 未返回最终图片。'), state);
+    }
+    if (!state.doneReceived) {
+        throw withPageSseDiagnostics(new Error('页面 SSE 缺少最终 done 事件，流式响应可能已提前中断。'), state);
+    }
+    return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost, sse_diagnostics: buildPageSseDiagnostics(state) };
+}
+
+function appendPageSseLog(rawEvent) {
+    if (!options.sseLogPath || !rawEvent.trim()) return;
+    try {
+        fs.mkdirSync(path.dirname(options.sseLogPath), { recursive: true });
+        fs.appendFileSync(options.sseLogPath, `${JSON.stringify({ at: new Date().toISOString(), raw_event: rawEvent })}\n`);
+    } catch (error) {
+        console.warn(`SSE log write failed: ${errorMessage(error)}`);
+    }
 }
 
 function readPageSseChunk(reader, signal) {
-  if (!signal) return reader.read();
-  if (signal.aborted) {
-    return Promise.reject(new Error('请求超时。'));
-  }
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(new Error('请求超时。'));
-    signal.addEventListener('abort', onAbort, { once: true });
-    reader.read().then(resolve, reject).finally(() => {
-      signal.removeEventListener('abort', onAbort);
+    if (!signal) return reader.read();
+    if (signal.aborted) {
+        return Promise.reject(new Error('请求超时。'));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error('请求超时。'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        reader
+            .read()
+            .then(resolve, reject)
+            .finally(() => {
+                signal.removeEventListener('abort', onAbort);
+            });
     });
-  });
 }
 
 function applyPageSseEvent(state, rawEvent) {
-  const event = parsePageSseEvent(rawEvent);
-  if (!event) return;
-  if (event.type === 'error') {
-    throw createPageSseStreamError(event);
-  }
-  if (event.type === 'completed' && event.filename) {
-    state.completedImages.push(
-      normalizePageSseImage(
-        {
-          filename: event.filename,
-          b64_json: event.b64_json,
-          path: event.path,
-          output_format: event.outputFormat || event.output_format || requestBody.output_format
-        },
-        readPageSseClientRequestId(event)
-      )
-    );
-    return;
-  }
-  if (event.type === 'done') {
-    state.doneReceived = true;
-    const clientRequestId = readPageSseClientRequestId(event);
-    state.completedImages = mergePageSseDoneImages(event.images, state.completedImages, clientRequestId);
-    state.usage = event.usage;
-    state.actualCost = event.actualCost !== undefined ? event.actualCost : event.actual_cost;
-  }
+    const event = parsePageSseEvent(rawEvent);
+    if (!event) return;
+    const eventType = readPageSseEventType(event);
+    state.lastEventType = eventType;
+    if (isPartialPageSseEvent(event, eventType)) state.partialImageCount += 1;
+    if (event.type === 'error') {
+        throw createPageSseStreamError(event, state);
+    }
+    if (event.type === 'completed' && event.filename) {
+        state.completedEventCount += 1;
+        state.completedImages.push(
+            normalizePageSseImage(
+                {
+                    filename: event.filename,
+                    b64_json: event.b64_json,
+                    path: event.path,
+                    output_format: event.outputFormat || event.output_format || requestBody.output_format
+                },
+                readPageSseClientRequestId(event)
+            )
+        );
+        return;
+    }
+    if (event.type === 'done') {
+        state.doneReceived = true;
+        const clientRequestId = readPageSseClientRequestId(event);
+        state.completedImages = mergePageSseDoneImages(event.images, state.completedImages, clientRequestId);
+        state.usage = event.usage;
+        state.actualCost = event.actualCost !== undefined ? event.actualCost : event.actual_cost;
+    }
+}
+
+function readPageSseEventType(event) {
+    if (typeof event.type === 'string' && event.type.trim()) return event.type;
+    if (typeof event.event === 'string' && event.event.trim()) return event.event;
+    return undefined;
+}
+
+function isPartialPageSseEvent(event, eventType) {
+    if (typeof eventType === 'string' && eventType.includes('partial_image')) return true;
+    return Boolean(event.partial_image || event.partialImage || event.partial_image_b64 || event.partialImageB64);
 }
 
 function formatPageSseError(value) {
-  if (typeof value === 'string' && value.trim()) return value;
-  if (value && typeof value === 'object') {
-    if (typeof value.message === 'string' && value.message.trim()) return value.message;
-    if (typeof value.code === 'string' && value.code.trim()) return value.code;
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return '页面 SSE 返回错误事件。';
+    if (typeof value === 'string' && value.trim()) return value;
+    if (value && typeof value === 'object') {
+        if (typeof value.message === 'string' && value.message.trim()) return value.message;
+        if (typeof value.code === 'string' && value.code.trim()) return value.code;
+        try {
+            return JSON.stringify(value);
+        } catch {
+            return '页面 SSE 返回错误事件。';
+        }
     }
-  }
-  return '页面 SSE 返回错误事件。';
+    return '页面 SSE 返回错误事件。';
 }
 
-function createPageSseStreamError(event) {
-  const error = new Error(formatPageSseError(event.error));
-  const status = readPageSseStreamStatus(event);
-  if (Number.isInteger(status)) {
-    error.streamStatus = status;
-  }
-  return error;
+function createPageSseStreamError(event, state) {
+    const error = new Error(formatPageSseError(event.error));
+    const status = readPageSseStreamStatus(event);
+    if (Number.isInteger(status)) {
+        error.streamStatus = status;
+    }
+    return withPageSseDiagnostics(error, state);
 }
 
 function readPageSseStreamStatus(event) {
-  if (Number.isInteger(event.status)) return event.status;
-  if (event.error && typeof event.error === 'object' && Number.isInteger(event.error.status)) {
-    return event.error.status;
-  }
-  return undefined;
+    if (Number.isInteger(event.status)) return event.status;
+    if (event.error && typeof event.error === 'object' && Number.isInteger(event.error.status)) {
+        return event.error.status;
+    }
+    return undefined;
 }
 
 function parsePageSseEvent(rawEvent) {
-  const lines = rawEvent.split(/\r?\n/);
-  const data = lines
-    .filter((line) => line.startsWith('data: '))
-    .map((line) => line.slice(6))
-    .join('\n')
-    .trim();
-  if (!data || data === '[DONE]') return undefined;
-  try {
-    return JSON.parse(data);
-  } catch (error) {
-    throw new Error(`页面 SSE 事件不是有效 JSON：${errorMessage(error)}`);
-  }
+    const lines = rawEvent.split(/\r?\n/);
+    const data = lines
+        .filter((line) => line.startsWith('data: '))
+        .map((line) => line.slice(6))
+        .join('\n')
+        .trim();
+    if (!data || data === '[DONE]') return undefined;
+    try {
+        return JSON.parse(data);
+    } catch (error) {
+        throw new Error(`页面 SSE 事件不是有效 JSON：${errorMessage(error)}`);
+    }
 }
 
 function buildSuccessOutput(result, routing) {
-  return routing ? { ...result, routing } : result;
+    return routing ? { ...result, routing } : result;
 }
 
 function buildPageSseFailureOutput(error) {
-  if (isScriptError(error)) {
-    return buildPageSseScriptFailure(error);
-  }
-  if (isPageSseRequestRejected(error)) {
-    return buildPageSseRequestRejectedFailure(error);
-  }
-  return buildBillablePageSseFailure(error);
+    const diagnostics = readPageSseDiagnostics(error);
+    if (isScriptError(error)) {
+        return buildPageSseScriptFailure(error, diagnostics);
+    }
+    if (isPageSseRequestRejected(error)) {
+        return buildPageSseRequestRejectedFailure(error, diagnostics);
+    }
+    return buildBillablePageSseFailure(error, diagnostics);
 }
 
 function buildPageSseRouting(fallbackMode) {
-  return {
-    transport: 'page_sse',
-    endpoint: PAGE_SSE_ENDPOINT,
-    fallback_endpoint: AGENT_ENDPOINTS.generate,
-    fallback_mode: fallbackMode
-  };
-}
-
-function buildPageSseScriptFailure(error) {
-  return {
-    ok: false,
-    billable: false,
-    error: {
-      code: error.scriptCode,
-      message: errorMessage(error)
-    },
-    routing: buildPageSseRouting('manual_after_diagnosis'),
-    next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到 Agent JSON。'
-  };
-}
-
-function buildPageSseRequestRejectedFailure(error) {
-  return {
-    ok: false,
-    billable: false,
-    error: {
-      code: 'page_sse_request_rejected',
-      status: error.status,
-      message: errorMessage(error)
-    },
-    routing: buildPageSseRouting('fix_request_before_retry'),
-    next_step: '先修正页面端拒绝的请求参数或鉴权，再重新执行；这类本地 4xx 不应按上游计费失败处理。'
-  };
-}
-
-function buildBillablePageSseFailure(error) {
-  return {
-    ok: false,
-    billable: true,
-    error: {
-      code: 'page_sse_failed',
-      ...buildPageSseFailureStatus(error),
-      message: errorMessage(error)
-    },
-    routing: buildPageSseRouting('manual_after_diagnosis'),
-    next_step:
-      '先诊断页面流式失败原因，再决定是否用 --agent 重新执行同一业务请求；不要自动重试同一个请求。'
-  };
+    return {
+        transport: 'page_sse',
+        endpoint: PAGE_SSE_ENDPOINT,
+        fallback_endpoint: AGENT_ENDPOINTS.generate,
+        fallback_mode: fallbackMode
+    };
 }
 
-function buildPageSseFailureStatus(error) {
-  if (error && typeof error === 'object') {
-    if (Number.isInteger(error.streamStatus)) return { status: error.streamStatus };
-    if (Number.isInteger(error.status)) return { status: error.status };
-  }
-  return {};
+function buildPageSseScriptFailure(error, diagnostics) {
+    return {
+        ok: false,
+        billable: false,
+        error: {
+            code: error.scriptCode,
+            message: errorMessage(error),
+            ...(diagnostics ? { diagnostics } : {})
+        },
+        routing: buildPageSseRouting('manual_after_diagnosis'),
+        next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到 Agent JSON。'
+    };
 }
 
-async function runGenerateJob() {
-  let lastResult;
-  let lastRetryAfter = null;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Idempotency-Key': idempotencyKey,
-        ...authHeaders()
-      },
-      body: JSON.stringify(requestBody),
-      timeoutMs
-    });
+function buildPageSseRequestRejectedFailure(error, diagnostics) {
+    return {
+        ok: false,
+        billable: false,
+        error: {
+            code: 'page_sse_request_rejected',
+            status: error.status,
+            message: errorMessage(error),
+            ...(diagnostics ? { diagnostics } : {})
+        },
+        routing: buildPageSseRouting('fix_request_before_retry'),
+        next_step: '先修正页面端拒绝的请求参数或鉴权，再重新执行；这类本地 4xx 不应按上游计费失败处理。'
+    };
+}
 
-    if (response.ok) {
-      const jobResult = await pollJobResult(result?.job);
-      console.log(JSON.stringify(enrichImageUrls(jobResult), null, 2));
-      process.exit(0);
+function buildBillablePageSseFailure(error, diagnostics) {
+    return {
+        ok: false,
+        billable: true,
+        error: {
+            code: 'page_sse_failed',
+            ...buildPageSseFailureStatus(error),
+            message: errorMessage(error),
+            ...(diagnostics ? { diagnostics } : {})
+        },
+        routing: buildPageSseRouting('manual_after_diagnosis'),
+        next_step: '先诊断页面流式失败原因，再决定是否用 --agent 重新执行同一业务请求；不要自动重试同一个请求。'
+    };
+}
+
+function buildPageSseFailureStatus(error) {
+    if (error && typeof error === 'object') {
+        if (Number.isInteger(error.streamStatus)) return { status: error.streamStatus };
+        if (Number.isInteger(error.status)) return { status: error.status };
     }
+    return {};
+}
+
+function withPageSseDiagnostics(error, state) {
+    error.pageSseDiagnostics = buildPageSseDiagnostics(state);
+    return error;
+}
 
-    const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
-    lastResult = result;
-    lastRetryAfter = retryAfter;
-    if (!shouldRetry(result) || attempt === maxAttempts) break;
-    await sleep(retryAfter);
-  }
+function readPageSseDiagnostics(error) {
+    if (!error || typeof error !== 'object' || !error.pageSseDiagnostics) return undefined;
+    return error.pageSseDiagnostics;
+}
 
-  console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
-  process.exit(1);
+function buildPageSseDiagnostics(state) {
+    return {
+        partial_image_count: state.partialImageCount,
+        completed_event_count: state.completedEventCount,
+        done_received: state.doneReceived,
+        final_image_count: state.completedImages.length,
+        ...(state.lastEventType ? { last_upstream_event_type: state.lastEventType } : {})
+    };
 }
 
-async function pollJobResult(job) {
-  if (!job || typeof job.id !== 'string') {
-    throw new Error('创建 job 的响应缺少 job.id。');
-  }
-  const resultUrl = resolveSameOriginUrl(baseUrl, job.result_url || buildAgentJobResultPath(job.id), 'job.result_url');
-  const deadlineMs = Date.now() + timeoutMs;
-  let lastResult;
-  let lastRetryAfter = job.retry_after_seconds || 1;
-
-  while (Date.now() < deadlineMs) {
-    const { response, result } = await fetchJson(resultUrl, {
-      headers: authHeaders(),
-      timeoutMs
-    });
-    if (response.ok) return result;
+async function runGenerateJob() {
+    let lastResult;
+    let lastRetryAfter = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Idempotency-Key': idempotencyKey,
+                ...authHeaders()
+            },
+            body: JSON.stringify(requestBody),
+            timeoutMs
+        });
+
+        if (response.ok) {
+            const jobResult = await pollJobResult(result?.job);
+            console.log(JSON.stringify(enrichImageUrls(jobResult), null, 2));
+            process.exit(0);
+        }
+
+        const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
+        lastResult = result;
+        lastRetryAfter = retryAfter;
+        if (!shouldRetry(result) || attempt === maxAttempts) break;
+        await sleep(retryAfter);
+    }
 
-    const retryAfter = parseRetryAfterValue(response.headers.get('retry-after')) || lastRetryAfter;
-    lastResult = result;
-    lastRetryAfter = retryAfter;
-    if (result?.error?.code !== 'request_in_progress' || !result?.error?.retryable) break;
-    await sleep(retryAfter);
-  }
+    console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
+    process.exit(1);
+}
 
-  console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
-  process.exit(1);
+async function pollJobResult(job) {
+    if (!job || typeof job.id !== 'string') {
+        throw new Error('创建 job 的响应缺少 job.id。');
+    }
+    const resultUrl = resolveSameOriginUrl(
+        baseUrl,
+        job.result_url || buildAgentJobResultPath(job.id),
+        'job.result_url'
+    );
+    const deadlineMs = Date.now() + timeoutMs;
+    let lastResult;
+    let lastRetryAfter = job.retry_after_seconds || 1;
+
+    while (Date.now() < deadlineMs) {
+        const { response, result } = await fetchJson(resultUrl, {
+            headers: authHeaders(),
+            timeoutMs
+        });
+        if (response.ok) return result;
+
+        const retryAfter = parseRetryAfterValue(response.headers.get('retry-after')) || lastRetryAfter;
+        lastResult = result;
+        lastRetryAfter = retryAfter;
+        if (result?.error?.code !== 'request_in_progress' || !result?.error?.retryable) break;
+        await sleep(retryAfter);
+    }
+
+    console.error(JSON.stringify({ ...lastResult, retry_after: lastRetryAfter }, null, 2));
+    process.exit(1);
 }
 
 async function runContractCheck(capabilitiesValue) {
-  const checks = [];
-  const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      ...authHeaders()
-    },
-    body: JSON.stringify(requestBody),
-    timeoutMs
-  });
-  if (response.status === 400 && result?.error?.code === 'idempotency_key_required') {
-    checks.push({ endpoint: AGENT_ENDPOINTS.generate, status: response.status, error_code: result.error.code });
-  } else {
-    console.error(JSON.stringify({ ok: false, billable: false, status: response.status, result }, null, 2));
-    process.exit(1);
-  }
-
-  if (supportsJobPolling(capabilitiesValue)) {
-    const jobCheck = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...authHeaders()
-      },
-      body: JSON.stringify(requestBody),
-      timeoutMs
-    });
-    if (jobCheck.response.status !== 400 || jobCheck.result?.error?.code !== 'idempotency_key_required') {
-      console.error(
-        JSON.stringify({ ok: false, billable: false, status: jobCheck.response.status, result: jobCheck.result }, null, 2)
-      );
-      process.exit(1);
-    }
-    checks.push({
-      endpoint: AGENT_ENDPOINTS.create_generate_job,
-      status: jobCheck.response.status,
-      error_code: jobCheck.result.error.code
+    const checks = [];
+    const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...authHeaders()
+        },
+        body: JSON.stringify(requestBody),
+        timeoutMs
     });
-  }
+    if (response.status === 400 && result?.error?.code === 'idempotency_key_required') {
+        checks.push({ endpoint: AGENT_ENDPOINTS.generate, status: response.status, error_code: result.error.code });
+    } else {
+        console.error(JSON.stringify({ ok: false, billable: false, status: response.status, result }, null, 2));
+        process.exit(1);
+    }
 
-  console.log(JSON.stringify({ ok: true, billable: false, checks }, null, 2));
+    if (supportsJobPolling(capabilitiesValue)) {
+        const jobCheck = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...authHeaders()
+            },
+            body: JSON.stringify(requestBody),
+            timeoutMs
+        });
+        if (jobCheck.response.status !== 400 || jobCheck.result?.error?.code !== 'idempotency_key_required') {
+            console.error(
+                JSON.stringify(
+                    { ok: false, billable: false, status: jobCheck.response.status, result: jobCheck.result },
+                    null,
+                    2
+                )
+            );
+            process.exit(1);
+        }
+        checks.push({
+            endpoint: AGENT_ENDPOINTS.create_generate_job,
+            status: jobCheck.response.status,
+            error_code: jobCheck.result.error.code
+        });
+    }
+
+    console.log(JSON.stringify({ ok: true, billable: false, checks }, null, 2));
 }
 
 async function fetchJson(url, init) {
-  try {
-    const response = await fetchWithTimeout(url, init);
-    const text = await response.text();
-    const result = parseJsonResponse(text, response.ok, url);
-    return { response, result, text };
-  } catch (error) {
-    const message = errorMessage(error);
-    if (message.startsWith(`请求失败：${url}。`)) {
-      throw error;
+    try {
+        const response = await fetchWithTimeout(url, init);
+        const text = await response.text();
+        const result = parseJsonResponse(text, response.ok, url);
+        return { response, result, text };
+    } catch (error) {
+        const message = errorMessage(error);
+        if (message.startsWith(`请求失败：${url}。`)) {
+            throw error;
+        }
+        throw new Error(`请求失败：${url}。${message}`);
     }
-    throw new Error(`请求失败：${url}。${message}`);
-  }
 }
 
 async function fetchWithTimeout(url, init) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? timeoutMs);
-  try {
-    const fetchInit = { ...init };
-    delete fetchInit.timeoutMs;
-    return await fetch(url, { ...fetchInit, signal: controller.signal });
-  } catch (error) {
-    const message = errorMessage(error);
-    throw new Error(`请求失败：${url}。${message}`);
-  } finally {
-    clearTimeout(timeout);
-  }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? timeoutMs);
+    try {
+        const fetchInit = { ...init };
+        delete fetchInit.timeoutMs;
+        return await fetch(url, { ...fetchInit, signal: controller.signal });
+    } catch (error) {
+        const message = errorMessage(error);
+        throw new Error(`请求失败：${url}。${message}`);
+    } finally {
+        clearTimeout(timeout);
+    }
 }
 
 function readErrorFromJsonText(text) {
-  let result;
-  try {
-    result = parseJsonResponse(text, false, '');
-  } catch {
+    let result;
+    try {
+        result = parseJsonResponse(text, false, '');
+    } catch {
+        return undefined;
+    }
+    if (typeof result?.error === 'string') return result.error;
+    if (typeof result?.error?.message === 'string') return result.error.message;
     return undefined;
-  }
-  if (typeof result?.error === 'string') return result.error;
-  if (typeof result?.error?.message === 'string') return result.error.message;
-  return undefined;
 }
 
 function parseJsonResponse(text, isOk, url) {
-  if (!text) return null;
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    if (!isOk) return null;
-    const message = errorMessage(error);
-    throw new Error(`响应不是有效 JSON：${url}。${message}`);
-  }
+    if (!text) return null;
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        if (!isOk) return null;
+        const message = errorMessage(error);
+        throw new Error(`响应不是有效 JSON：${url}。${message}`);
+    }
 }
 
 function shouldRetry(result) {
-  return Boolean(result?.error?.retryable);
+    return Boolean(result?.error?.retryable);
 }
 
 function supportsJobPolling(capabilitiesValue) {
-  return Boolean(capabilitiesValue?.agent_jobs?.supported === true && capabilitiesValue.agent_jobs.mode === 'job_polling');
+    return Boolean(
+        capabilitiesValue?.agent_jobs?.supported === true && capabilitiesValue.agent_jobs.mode === 'job_polling'
+    );
 }
 
 function supportsPageSse(capabilitiesValue) {
-  return Boolean(capabilitiesValue?.agent_streaming?.page_sse?.supported === true);
+    return Boolean(capabilitiesValue?.agent_streaming?.page_sse?.supported === true);
 }
 
 function shouldUseJobPolling(capabilitiesValue, routeMode) {
-  if (routeMode !== 'job') return false;
-  if (!supportsJobPolling(capabilitiesValue)) {
-    throw new Error('服务 capabilities 未声明 agent_jobs.supported=true，不能调用 job endpoint。');
-  }
-  return true;
+    if (routeMode !== 'job') return false;
+    if (!supportsJobPolling(capabilitiesValue)) {
+        throw new Error('服务 capabilities 未声明 agent_jobs.supported=true，不能调用 job endpoint。');
+    }
+    return true;
 }
 
 function shouldUsePageSse(capabilitiesValue, request, routeMode) {
-  if (routeMode === 'agent' || routeMode === 'job') return false;
-  if (!isPageSseAllowed(request)) {
-    if (routeMode === 'page_sse') {
-      throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
+    if (routeMode === 'agent' || routeMode === 'job') return false;
+    if (!isPageSseAllowed(request)) {
+        if (routeMode === 'page_sse') {
+            throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。');
+        }
+        return false;
+    }
+    if (routeMode === 'page_sse' || isLargeGenerate(request)) {
+        assertPageSseReady(capabilitiesValue);
+        return true;
     }
     return false;
-  }
-  if (routeMode === 'page_sse' || isLargeGenerate(request)) {
-    assertPageSseReady(capabilitiesValue);
-    return true;
-  }
-  return false;
 }
 
 function isLargeGenerate(request) {
-  return readMaxImageEdge(request.size) > 2048;
+    return readMaxImageEdge(request.size) > 2048;
 }
 
 function isPageSseAllowed(request) {
-  return request.streaming_strategy !== 'off';
-}
-
-function readMaxImageEdge(size) {
-  if (typeof size !== 'string') return 0;
-  const match = size.match(/^(\d+)x(\d+)$/);
-  if (!match) return 0;
-  return Math.max(Number(match[1]), Number(match[2]));
+    return request.streaming_strategy !== 'off' && request.stream_mode !== 'non_stream';
 }
 
 function createScriptError(code, message) {
-  const error = new Error(message);
-  error.scriptCode = code;
-  return error;
+    const error = new Error(message);
+    error.scriptCode = code;
+    return error;
 }
 
 function isScriptError(error) {
-  return Boolean(error && typeof error === 'object' && typeof error.scriptCode === 'string');
+    return Boolean(error && typeof error === 'object' && typeof error.scriptCode === 'string');
 }
 
 function createPageSseHttpError(status, detail) {
-  const message = detail ? `页面 SSE 请求失败，状态码 ${status}：${detail}` : `页面 SSE 请求失败，状态码 ${status}。`;
-  const error = new Error(message);
-  error.status = status;
-  return error;
+    const message = detail ? `页面 SSE 请求失败，状态码 ${status}：${detail}` : `页面 SSE 请求失败，状态码 ${status}。`;
+    const error = new Error(message);
+    error.status = status;
+    return error;
 }
 
 function isPageSseRequestRejected(error) {
-  return Boolean(
-    error &&
-      typeof error === 'object' &&
-      Number.isInteger(error.status) &&
-      error.status >= 400 &&
-      error.status < 500
-  );
+    return Boolean(
+        error &&
+            typeof error === 'object' &&
+            Number.isInteger(error.status) &&
+            error.status >= 400 &&
+            error.status < 500
+    );
 }
 
 function printUsage() {
-  console.error('用法：generate-image.mjs [options] <prompt>');
-  console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
-  console.error(
-    '常用参数：--model --size --quality --n --format --response-mode --image-backend --streaming-strategy --partial-images --timeout-ms --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
-  );
-  console.error('契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 generate-image.mjs 或 generate-image.mjs --contract-check');
+    console.error('用法：generate-image.mjs [options] <prompt>');
+    console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
+    console.error(
+        '常用参数：--model --size --quality --n --format --response-mode --image-backend --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
+    );
+    console.error(
+        '契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 generate-image.mjs 或 generate-image.mjs --contract-check'
+    );
 }

skills/gpt-image-playground-agent/scripts/lib/agent-api-paths.mjs

@@ -0,0 +1,30 @@
+export const AGENT_ENDPOINTS = Object.freeze({
+    capabilities: '/api/agent/capabilities',
+    openapi: '/api/agent/openapi.json',
+    generate: '/api/agent/images/generate',
+    edit: '/api/agent/images/edit',
+    create_generate_job: '/api/agent/jobs/images/generate',
+    job: '/api/agent/jobs/{id}',
+    job_result: '/api/agent/jobs/{id}/result',
+    artifact_metadata: '/api/agent/artifacts/{id}',
+    artifact_content: '/api/agent/artifacts/{id}/content',
+    artifact_delete: '/api/agent/artifacts/{id}'
+});
+
+export const AGENT_JOB_ENDPOINTS = Object.freeze({
+    create_generate_job: AGENT_ENDPOINTS.create_generate_job,
+    get_job: AGENT_ENDPOINTS.job,
+    get_job_result: AGENT_ENDPOINTS.job_result
+});
+
+export function buildAgentJobPath(jobId) {
+    return AGENT_ENDPOINTS.job.replace('{id}', encodePathValue(jobId));
+}
+
+export function buildAgentJobResultPath(jobId) {
+    return AGENT_ENDPOINTS.job_result.replace('{id}', encodePathValue(jobId));
+}
+
+function encodePathValue(value) {
+    return encodeURIComponent(String(value));
+}

skills/gpt-image-playground-agent/scripts/lib/page-sse-client.mjs

@@ -0,0 +1,407 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PAGE_SSE_ENDPOINT = '/api/images';
+export const DEFAULT_PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH = 128;
+
+export function readPageSseClientRequestIdMaxLength(capabilities) {
+  const maxLength = capabilities?.agent_streaming?.page_sse?.client_request_id?.max_length;
+  if (Number.isSafeInteger(maxLength) && maxLength > 0) return maxLength;
+  return DEFAULT_PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH;
+}
+
+export function assertPageSseReady({ capabilities, passwordHash, idempotencyKey }) {
+  const pageSse = capabilities?.agent_streaming?.page_sse;
+  if (pageSse?.supported !== true) {
+    throw createPageSseScriptError(
+      'page_sse_unavailable',
+      '当前路由需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级。'
+    );
+  }
+  if (pageSse?.auth?.required === true && !passwordHash) {
+    throw createPageSseScriptError(
+      'page_sse_auth_required',
+      '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
+    );
+  }
+  const maxLength = readPageSseClientRequestIdMaxLength(capabilities);
+  if (idempotencyKey.length > maxLength) {
+    throw createPageSseScriptError(
+      'page_sse_client_request_id_too_long',
+      `页面 SSE 的 clientRequestId 不能超过 ${maxLength} 个字符；请缩短 Idempotency-Key。`
+    );
+  }
+}
+
+export async function postPageSse({ url, formData, timeoutMs, errorMessage, sseLogPath }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        body: formData,
+        signal: controller.signal
+      });
+    } catch (error) {
+      throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('text/event-stream')) {
+      return await collectPageSseResult(response, controller.signal, errorMessage, sseLogPath);
+    }
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
+    }
+    return parseJsonResponse(text, true, url, errorMessage);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function formatPageSseOutput({ result, baseUrl, responseMode = 'path', defaultOutputFormat = 'png' }) {
+  if (!result || !Array.isArray(result.images)) return result;
+  return {
+    ...result,
+    images: result.images.map((image) =>
+      formatPageSseImage({ image, baseUrl, responseMode, defaultOutputFormat })
+    )
+  };
+}
+
+export function buildPageSseFailureOutput({ error, fallbackEndpoint, fallbackMode = 'manual_after_diagnosis', errorMessage }) {
+  const diagnostics = readPageSseDiagnostics(error);
+  if (isPageSseScriptError(error)) {
+    return {
+      ok: false,
+      billable: false,
+      error: {
+        code: error.scriptCode,
+        message: errorMessage(error),
+        ...(diagnostics ? { diagnostics } : {})
+      },
+      routing: buildPageSseRouting(fallbackEndpoint, fallbackMode),
+      next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到 Agent JSON。'
+    };
+  }
+  if (isPageSseRequestRejected(error)) {
+    return {
+      ok: false,
+      billable: false,
+      error: {
+        code: 'page_sse_request_rejected',
+        status: error.status,
+        message: errorMessage(error),
+        ...(diagnostics ? { diagnostics } : {})
+      },
+      routing: buildPageSseRouting(fallbackEndpoint, 'fix_request_before_retry'),
+      next_step: '先修正页面端拒绝的请求参数或鉴权，再重新执行；这类本地 4xx 不应按上游计费失败处理。'
+    };
+  }
+  return {
+    ok: false,
+    billable: true,
+    error: {
+      code: 'page_sse_failed',
+      ...buildPageSseFailureStatus(error),
+      message: errorMessage(error),
+      ...(diagnostics ? { diagnostics } : {})
+    },
+    routing: buildPageSseRouting(fallbackEndpoint, fallbackMode),
+    next_step: '先诊断页面流式失败原因，再决定是否显式选择备用路径；不要自动重试同一个请求。'
+  };
+}
+
+export function normalizeImageBackendForPage(value) {
+  if (value === 'images') return 'images-api';
+  if (value === 'responses') return 'responses-image-generation';
+  return value;
+}
+
+export function isPageSseDisabledByStreamingOptions(value) {
+  return value?.streamMode === 'non_stream' || value?.streamingStrategy === 'off';
+}
+
+export function assertPageSseStreamingAllowed(value) {
+  if (isPageSseDisabledByStreamingOptions(value)) {
+    throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能使用页面 SSE。');
+  }
+}
+
+function buildPageSseRouting(fallbackEndpoint, fallbackMode) {
+  return {
+    transport: 'page_sse',
+    endpoint: PAGE_SSE_ENDPOINT,
+    fallback_endpoint: fallbackEndpoint,
+    fallback_mode: fallbackMode
+  };
+}
+
+function createPageSseScriptError(code, message) {
+  const error = new Error(message);
+  error.scriptCode = code;
+  return error;
+}
+
+function isPageSseScriptError(error) {
+  return Boolean(error && typeof error === 'object' && typeof error.scriptCode === 'string');
+}
+
+function isPageSseRequestRejected(error) {
+  return Boolean(error && typeof error === 'object' && Number.isInteger(error.status) && error.status >= 400 && error.status < 500);
+}
+
+function createPageSseHttpError(status, message) {
+  const error = new Error(formatErrorValue(message));
+  error.status = status;
+  return error;
+}
+
+function formatErrorValue(value) {
+  if (typeof value === 'string' && value.trim()) return value;
+  if (value && typeof value === 'object') {
+    if (typeof value.message === 'string' && value.message.trim()) return value.message;
+    if (typeof value.code === 'string' && value.code.trim()) return value.code;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '页面 SSE 返回错误。';
+    }
+  }
+  return '页面 SSE 返回错误。';
+}
+
+function readErrorFromJsonText(text) {
+  try {
+    const value = text ? JSON.parse(text) : null;
+    if (typeof value?.error === 'string') return value.error;
+    return value?.error || value;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseJsonResponse(text, allowEmpty, url, errorMessage) {
+  if (!text && allowEmpty) return {};
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`响应不是有效 JSON：${url}。${errorMessage(error)}`);
+  }
+}
+
+async function collectPageSseResult(response, signal, errorMessage, sseLogPath) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('页面 SSE 响应缺少 body。');
+  const decoder = new TextDecoder();
+  const state = createPageSseState();
+  let buffer = '';
+  while (true) {
+    const { done, value } = await readPageSseChunk(reader, signal);
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const events = buffer.split(/\r?\n\r?\n/);
+    buffer = events.pop() || '';
+    for (const rawEvent of events) {
+      appendPageSseLog(sseLogPath, rawEvent);
+      applyPageSseEvent(state, rawEvent, errorMessage);
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) {
+    appendPageSseLog(sseLogPath, buffer);
+    applyPageSseEvent(state, buffer, errorMessage);
+  }
+  if (state.completedImages.length === 0) {
+    throw withPageSseDiagnostics(new Error('页面 SSE 未返回最终图片。'), state);
+  }
+  if (!state.doneReceived) {
+    throw withPageSseDiagnostics(new Error('页面 SSE 缺少最终 done 事件，流式响应可能已提前中断。'), state);
+  }
+  return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost, sse_diagnostics: buildPageSseDiagnostics(state) };
+}
+
+function appendPageSseLog(filePath, rawEvent) {
+  if (!filePath || !rawEvent.trim()) return;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify({ at: new Date().toISOString(), raw_event: rawEvent })}\n`);
+  } catch (error) {
+    console.warn(`SSE log write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function createPageSseState() {
+  return {
+    completedImages: [],
+    usage: undefined,
+    actualCost: undefined,
+    doneReceived: false,
+    completedEventCount: 0,
+    partialImageCount: 0,
+    lastEventType: undefined
+  };
+}
+
+function readPageSseChunk(reader, signal) {
+  if (!signal) return reader.read();
+  if (signal.aborted) return Promise.reject(new Error('请求超时。'));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(new Error('请求超时。'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    reader
+      .read()
+      .then(resolve, reject)
+      .finally(() => {
+        signal.removeEventListener('abort', onAbort);
+      });
+  });
+}
+
+function applyPageSseEvent(state, rawEvent, errorMessage) {
+  const event = parsePageSseEvent(rawEvent, errorMessage);
+  if (!event) return;
+  const eventType = readPageSseEventType(event);
+  state.lastEventType = eventType;
+  if (isPartialPageSseEvent(event, eventType)) state.partialImageCount += 1;
+  if (event.type === 'error') {
+    throw createPageSseStreamError(event, state);
+  }
+  if (event.type === 'completed' && event.filename) {
+    state.completedEventCount += 1;
+    state.completedImages.push(
+      normalizePageSseImage(
+        {
+          filename: event.filename,
+          b64_json: event.b64_json,
+          path: event.path,
+          output_format: event.outputFormat || event.output_format
+        },
+        readPageSseClientRequestId(event)
+      )
+    );
+    return;
+  }
+  if (event.type === 'done') {
+    state.doneReceived = true;
+    const clientRequestId = readPageSseClientRequestId(event);
+    state.completedImages = mergePageSseDoneImages(event.images, state.completedImages, clientRequestId);
+    state.usage = event.usage;
+    state.actualCost = event.actualCost !== undefined ? event.actualCost : event.actual_cost;
+  }
+}
+
+function readPageSseEventType(event) {
+  if (typeof event.type === 'string' && event.type.trim()) return event.type;
+  if (typeof event.event === 'string' && event.event.trim()) return event.event;
+  return undefined;
+}
+
+function isPartialPageSseEvent(event, eventType) {
+  if (typeof eventType === 'string' && eventType.includes('partial_image')) return true;
+  return Boolean(event.partial_image || event.partialImage || event.partial_image_b64 || event.partialImageB64);
+}
+
+function parsePageSseEvent(rawEvent, errorMessage) {
+  const lines = rawEvent.split(/\r?\n/);
+  const data = lines
+    .filter((line) => line.startsWith('data: '))
+    .map((line) => line.slice(6))
+    .join('\n')
+    .trim();
+  if (!data || data === '[DONE]') return undefined;
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    throw new Error(`页面 SSE 事件不是有效 JSON：${errorMessage(error)}`);
+  }
+}
+
+function createPageSseStreamError(event, state) {
+  const error = new Error(formatErrorValue(event.error));
+  const status = readPageSseStreamStatus(event);
+  if (Number.isInteger(status)) error.streamStatus = status;
+  return withPageSseDiagnostics(error, state);
+}
+
+function readPageSseStreamStatus(event) {
+  if (Number.isInteger(event.status)) return event.status;
+  if (event.error && typeof event.error === 'object' && Number.isInteger(event.error.status)) {
+    return event.error.status;
+  }
+  return undefined;
+}
+
+function readPageSseClientRequestId(event) {
+  if (typeof event.clientRequestId === 'string') return event.clientRequestId;
+  if (typeof event.client_request_id === 'string') return event.client_request_id;
+  return undefined;
+}
+
+function normalizePageSseImage(image, fallbackClientRequestId) {
+  const clientRequestId = image.clientRequestId || image.client_request_id || fallbackClientRequestId;
+  return {
+    ...image,
+    ...(image.output_format ? { output_format: image.output_format } : {}),
+    ...(clientRequestId ? { clientRequestId } : {})
+  };
+}
+
+function mergePageSseDoneImages(doneImages, completedImages, fallbackClientRequestId) {
+  if (!Array.isArray(doneImages) || doneImages.length === 0) {
+    return completedImages.map((image) => normalizePageSseImage(image, fallbackClientRequestId));
+  }
+  const imageCount = Math.max(doneImages.length, completedImages.length);
+  return Array.from({ length: imageCount }, (_, index) =>
+    normalizePageSseImage(
+      { ...(completedImages[index] || {}), ...(doneImages[index] || {}) },
+      fallbackClientRequestId
+    )
+  );
+}
+
+function formatPageSseImage({ image, baseUrl, responseMode, defaultOutputFormat }) {
+  const output = {
+    ...image,
+    output_format: image.outputFormat || image.output_format || defaultOutputFormat
+  };
+  if (output.path) {
+    output.absolute_path = new URL(output.path, `${baseUrl}/`).toString();
+    output.content_url = output.content_url || output.path;
+    output.absolute_content_url = output.absolute_content_url || output.absolute_path;
+    if (responseMode === 'path') delete output.b64_json;
+  }
+  return output;
+}
+
+function buildPageSseFailureStatus(error) {
+  if (error && typeof error === 'object') {
+    if (Number.isInteger(error.streamStatus)) return { status: error.streamStatus };
+    if (Number.isInteger(error.status)) return { status: error.status };
+  }
+  return {};
+}
+
+function withPageSseDiagnostics(error, state) {
+  error.pageSseDiagnostics = buildPageSseDiagnostics(state);
+  return error;
+}
+
+function readPageSseDiagnostics(error) {
+  if (!error || typeof error !== 'object' || !error.pageSseDiagnostics) return undefined;
+  return error.pageSseDiagnostics;
+}
+
+function buildPageSseDiagnostics(state) {
+  return {
+    partial_image_count: state.partialImageCount,
+    completed_event_count: state.completedEventCount,
+    done_received: state.doneReceived,
+    final_image_count: state.completedImages.length,
+    ...(state.lastEventType ? { last_upstream_event_type: state.lastEventType } : {})
+  };
+}

skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs

@@ -1,9 +1,12 @@
-import {
-  CHINESE_POSITIVE_INTEGER_MESSAGES,
-  parsePositiveIntegerConfig
-} from '../../../../src/lib/positive-integer-config.mjs';
-
 const MAX_RETRY_AFTER_SECONDS = 60;
+const DIGITS_PATTERN = /^\d+$/;
+const IMAGE_SIZE_PATTERN = /^(\d+)x(\d+)$/;
+const LEGACY_IMAGE_SIZES = new Set(['auto', '1024x1024', '1536x1024', '1024x1536']);
+const GPT_IMAGE_2_MIN_PIXELS = 655_360;
+const GPT_IMAGE_2_MAX_PIXELS = 8_294_400;
+const GPT_IMAGE_2_MAX_EDGE = 3840;
+const GPT_IMAGE_2_EDGE_MULTIPLE = 16;
+const GPT_IMAGE_2_MAX_ASPECT = 3;
 
 export function readOptionValue(argv, index, name) {
   const value = argv[index];
@@ -14,9 +17,16 @@ export function readOptionValue(argv, index, name) {
 }
 
 export function readConfiguredPositiveInteger(value, name, fallback) {
-  return parsePositiveIntegerConfig(value, name, fallback, {
-    messages: CHINESE_POSITIVE_INTEGER_MESSAGES
-  });
+  const rawValue = value === undefined || value === null ? '' : String(value).trim();
+  if (!rawValue) return fallback;
+  if (!DIGITS_PATTERN.test(rawValue)) {
+    throw new Error(`${name} 必须是正整数。`);
+  }
+  const parsed = Number(rawValue);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error(`${name} 必须是正整数。`);
+  }
+  return parsed;
 }
 
 export function normalizeBaseUrl(value) {
@@ -40,6 +50,34 @@ export function normalizeOutputFormat(value) {
   return value.toLowerCase() === 'jpg' ? 'jpeg' : value.toLowerCase();
 }
 
+export function assertValidImageSizeForModel(value, model, label = 'size') {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} 必须是字符串。`);
+  }
+  if (model !== 'gpt-image-2') {
+    if (!LEGACY_IMAGE_SIZES.has(value)) {
+      throw new Error(`${label} 对 ${model} 无效；非 gpt-image-2 只支持 auto、1024x1024、1536x1024、1024x1536。`);
+    }
+    return value;
+  }
+  if (value === 'auto') return value;
+  const size = parseImageSizeValue(value);
+  if (!size) throw new Error(`${label} 必须是 auto 或 WIDTHxHEIGHT。`);
+  assertValidGptImage2Dimensions(size.width, size.height, label);
+  return value;
+}
+
+export function parseImageSizeValue(value) {
+  if (typeof value !== 'string') return undefined;
+  const match = IMAGE_SIZE_PATTERN.exec(value);
+  return match ? { width: Number(match[1]), height: Number(match[2]) } : undefined;
+}
+
+export function readMaxImageEdge(value) {
+  const size = parseImageSizeValue(value);
+  return size ? Math.max(size.width, size.height) : 0;
+}
+
 export function parseRetryAfterValue(value, fallback = 1) {
   if (!value || !/^\d+$/.test(value)) return clampRetryAfterSeconds(fallback);
   const parsed = Number(value);
@@ -68,3 +106,30 @@ export function resolveSameOriginUrl(baseUrl, value, label) {
 export function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+function assertValidGptImage2Dimensions(width, height, label) {
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new Error(`${label} 的宽度和高度必须是正数。`);
+  }
+  if (!Number.isInteger(width) || !Number.isInteger(height)) {
+    throw new Error(`${label} 的宽度和高度必须是整数。`);
+  }
+  if (width % GPT_IMAGE_2_EDGE_MULTIPLE !== 0 || height % GPT_IMAGE_2_EDGE_MULTIPLE !== 0) {
+    throw new Error(`${label} 的宽边和高边都必须是 ${GPT_IMAGE_2_EDGE_MULTIPLE} 的倍数。`);
+  }
+  if (width > GPT_IMAGE_2_MAX_EDGE || height > GPT_IMAGE_2_MAX_EDGE) {
+    throw new Error(`${label} 的最大单边不能超过 ${GPT_IMAGE_2_MAX_EDGE}px。`);
+  }
+  const long = Math.max(width, height);
+  const short = Math.min(width, height);
+  if (long / short > GPT_IMAGE_2_MAX_ASPECT) {
+    throw new Error(`${label} 的宽高比（长边:短边）必须小于等于 ${GPT_IMAGE_2_MAX_ASPECT}:1。`);
+  }
+  const pixels = width * height;
+  if (pixels < GPT_IMAGE_2_MIN_PIXELS) {
+    throw new Error(`${label} 的总像素必须至少为 ${GPT_IMAGE_2_MIN_PIXELS.toLocaleString()}。`);
+  }
+  if (pixels > GPT_IMAGE_2_MAX_PIXELS) {
+    throw new Error(`${label} 的总像素不能超过 ${GPT_IMAGE_2_MAX_PIXELS.toLocaleString()}。`);
+  }
+}

skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs

@@ -3,6 +3,7 @@ import dns from 'node:dns/promises';
 import tls from 'node:tls';
 import {
   errorMessage,
+  assertValidImageSizeForModel,
   normalizeBaseUrl,
   normalizeOutputFormat,
   readConfiguredPositiveInteger,
@@ -36,6 +37,7 @@ const apiKey = process.env.GPT_IMAGE_UPSTREAM_API_KEY || process.env.OPENAI_API_
 let timeoutMs;
 try {
   timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 30000);
+  options.size = assertValidImageSizeForModel(options.size, options.model, '--size');
 } catch (error) {
   console.error(errorMessage(error));
   printUsage();

src/app/api/agent/agent-routes.test.ts

@@ -38,8 +38,17 @@ beforeEach(async () => {
     process.env.NEXT_PUBLIC_IMAGE_STORAGE_MODE = 'fs';
     delete process.env.APP_PASSWORD;
     delete process.env.AGENT_API_TOKEN;
+    delete process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_1_ID;
     delete process.env.OPENAI_CHANNEL_1_API_KEYS;
     delete process.env.OPENAI_CHANNEL_1_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK;
+    delete process.env.OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY;
+    delete process.env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS;
 });
 
 afterEach(async () => {
@@ -99,6 +108,10 @@ describe('Agent route integration', () => {
             'images-api',
             'responses-image-generation'
         ]);
+        assert.deepEqual(body.agent_streaming.upstream_sse.request_fields_by_mode, {
+            generate: ['image_backend', 'stream_mode', 'streaming_strategy', 'partial_images'],
+            edit: ['stream_mode', 'streaming_strategy', 'partial_images']
+        });
     });
 
     it('generates through a compatible upstream once and replays the cached response for the same idempotency key', async () => {
@@ -161,6 +174,38 @@ describe('Agent route integration', () => {
         }
     });
 
+    it('uses Agent auto stream mode as an internal upstream stream by default', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        const { getServerChannelState } = await import('@/lib/server-channel-router');
+        let upstreamBody = '';
+        const upstream = await startImageUpstream((body) => {
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-default-auto-stream-key', {
+                    prompt: 'agent default auto stream',
+                    stream_mode: 'auto'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.images[0].content_url.startsWith('/api/agent/artifacts/'), true);
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, true);
+            assert.equal(upstreamJson.partial_images, 2);
+            assert.equal(getServerChannelState().streamingAvailability.summary().mark_count, 1);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('consumes upstream image SSE internally while keeping the Agent generate response non-streaming', async () => {
         const { generateImage } = await loadAgentRoutes();
         let upstreamBody = '';
@@ -408,6 +453,7 @@ describe('Agent route integration', () => {
                 agentJsonRequest('agent-responses-upstream-sse-partial-only-key', {
                     prompt: 'agent responses upstream sse partial only',
                     image_backend: 'responses-image-generation',
+                    stream_mode: 'stream',
                     streaming_strategy: 'responses-sse',
                     partial_images: 2
                 })
@@ -454,6 +500,7 @@ describe('Agent route integration', () => {
                 agentJsonRequest('agent-responses-upstream-sse-failed-call-key', {
                     prompt: 'agent responses upstream sse failed call',
                     image_backend: 'responses-image-generation',
+                    stream_mode: 'stream',
                     streaming_strategy: 'responses-sse',
                     partial_images: 2
                 })
@@ -483,6 +530,7 @@ describe('Agent route integration', () => {
             const response = await generateImage(
                 agentJsonRequest('agent-upstream-sse-partial-only-key', {
                     prompt: 'agent upstream sse partial only',
+                    stream_mode: 'stream',
                     streaming_strategy: 'newapi-keepalive-sse',
                     partial_images: 2
                 })
@@ -772,6 +820,7 @@ describe('Agent route integration', () => {
             const created = await createGenerateJob(
                 agentJobJsonRequest('route-job-images-missing-final-key', {
                     prompt: 'agent job images partial only',
+                    stream_mode: 'stream',
                     streaming_strategy: 'newapi-keepalive-sse',
                     partial_images: 2
                 })
@@ -908,6 +957,7 @@ describe('Agent route integration', () => {
                 agentJobJsonRequest('route-job-responses-missing-final-key', {
                     prompt: 'agent job responses partial only',
                     image_backend: 'responses-image-generation',
+                    stream_mode: 'stream',
                     streaming_strategy: 'responses-sse',
                     partial_images: 2
                 })
@@ -1311,8 +1361,44 @@ describe('Agent route integration', () => {
         await upstream.close();
     });
 
+    it('can consume Agent edit upstream SSE internally while returning final JSON', async () => {
+        const { editImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'image_edit.completed',
+                    data: { type: 'image_edit.completed', b64_json: PNG_BASE64 }
+                }
+            ];
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await editImage(
+                agentEditRequest('route-edit-upstream-sse-key', 'agent edit stream', {}, {
+                    stream_mode: 'stream',
+                    streaming_strategy: 'openai-sse',
+                    partial_images: '2'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.images[0].content_url.startsWith('/api/agent/artifacts/'), true);
+            assert.match(upstreamBody, /name="stream"/);
+            assert.match(upstreamBody, /name="partial_images"/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('aborts Agent edit upstream calls when the client request signal aborts', async () => {
         const { editImage } = await loadAgentRoutes();
+        const { getServerChannelState } = await import('@/lib/server-channel-router');
         const upstream = await startHangingImageEditUpstream();
         process.env.OPENAI_API_KEY = 'test-key';
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
@@ -1320,9 +1406,13 @@ describe('Agent route integration', () => {
 
         try {
             const responsePromise = editImage(
-                agentEditRequest('route-edit-abort-key', 'agent edit abort', {}, 'path', {
-                    signal: abortController.signal
-                })
+                agentEditRequest(
+                    'route-edit-abort-key',
+                    'agent edit abort',
+                    {},
+                    { stream_mode: 'auto', streaming_strategy: 'openai-sse' },
+                    { signal: abortController.signal }
+                )
             );
             await waitFor(() => upstream.requests === 1);
             abortController.abort();
@@ -1335,6 +1425,7 @@ describe('Agent route integration', () => {
             ]);
 
             assert.notEqual(response.status, 200);
+            assert.equal(getServerChannelState().streamingAvailability.summary().mark_count, 0);
         } finally {
             abortController.abort();
             await upstream.close();
@@ -1359,7 +1450,7 @@ describe('Agent route integration', () => {
         await upstream.close();
     });
 
-    it('rejects high-resolution Agent edit requests before contacting upstream', async () => {
+    it('rejects unsupported fields on Agent edit requests before calling upstream', async () => {
         const { editImage } = await loadAgentRoutes();
         let upstreamCalls = 0;
         const upstream = await startImageUpstream(() => {
@@ -1371,20 +1462,95 @@ describe('Agent route integration', () => {
 
         try {
             const response = await editImage(
-                agentEditRequest('route-edit-high-resolution-key', 'high resolution edit', {}, { size: '3072x2048' })
+                agentEditRequest('route-edit-generate-only-fields-key', 'agent edit invalid fields', {}, {
+                    imageBackend: 'responses-image-generation',
+                    image_backend: 'responses-image-generation',
+                    format: 'webp',
+                    outputFormat: 'jpeg',
+                    output_format: 'jpeg',
+                    outputCompression: '80',
+                    output_compression: '80',
+                    responsesModel: 'gpt-4.1',
+                    responses_model: 'gpt-4.1',
+                    background: 'opaque',
+                    moderation: 'auto'
+                })
             );
 
             assert.equal(response.status, 422);
             const body = await response.json();
             assert.equal(body.error.code, 'validation_error');
-            assert.match(body.error.message, /\/api\/images/);
+            assert.match(body.error.details.fields.imageBackend, /不接受该字段/);
+            assert.match(body.error.details.fields.image_backend, /不接受该字段/);
+            assert.match(body.error.details.fields.format, /不接受该字段/);
+            assert.match(body.error.details.fields.outputFormat, /不接受该字段/);
+            assert.match(body.error.details.fields.output_format, /不接受该字段/);
+            assert.match(body.error.details.fields.outputCompression, /不接受该字段/);
+            assert.match(body.error.details.fields.output_compression, /不接受该字段/);
+            assert.match(body.error.details.fields.responsesModel, /不接受该字段/);
+            assert.match(body.error.details.fields.responses_model, /不接受该字段/);
+            assert.match(body.error.details.fields.background, /不接受该字段/);
+            assert.match(body.error.details.fields.moderation, /不接受该字段/);
             assert.equal(upstreamCalls, 0);
         } finally {
             await upstream.close();
         }
     });
 
-    it('rejects high-resolution Agent edit requests before reading files or API credentials', async () => {
+    it('rejects page-only streaming strategy fields on Agent edit requests before calling upstream', async () => {
+        const { editImage } = await loadAgentRoutes();
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream(() => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await editImage(
+                agentEditRequest('route-edit-page-streaming-field-key', 'agent edit invalid page streaming field', {}, {
+                    image_streaming_strategy: 'force-sse',
+                    imageStreamingStrategy: 'force-sse'
+                })
+            );
+
+            assert.equal(response.status, 422);
+            const body = await response.json();
+            assert.equal(body.error.code, 'validation_error');
+            assert.match(body.error.details.fields.image_streaming_strategy, /streaming_strategy/);
+            assert.match(body.error.details.fields.imageStreamingStrategy, /streaming_strategy/);
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('allows high-resolution Agent edit requests as an explicit fallback path', async () => {
+        const { editImage } = await loadAgentRoutes();
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream(() => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await editImage(
+                agentEditRequest('route-edit-high-resolution-key', 'high resolution edit', {}, { size: '3072x2048' })
+            );
+
+            assert.equal(response.status, 200);
+            const body = await response.json();
+            assert.equal(body.images[0].output_format, 'png');
+            assert.equal(upstreamCalls, 1);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('reports missing image files for high-resolution Agent edit before API credentials', async () => {
         const { editImage } = await loadAgentRoutes();
         delete process.env.OPENAI_API_KEY;
         delete process.env.OPENAI_API_BASE_URL;
@@ -1408,12 +1574,11 @@ describe('Agent route integration', () => {
         assert.equal(response.status, 422);
         const body = await response.json();
         assert.equal(body.error.code, 'validation_error');
-        assert.match(body.error.message, /\/api\/images/);
-        assert.equal(body.error.details?.fields?.image_0, undefined);
-        assert.doesNotMatch(body.error.message, /API Key|图片文件/);
+        assert.match(body.error.message, /图片文件/);
+        assert.doesNotMatch(body.error.message, /API Key/);
     });
 
-    it('rejects auto-size Agent edit when the uploaded source image is high resolution', async () => {
+    it('allows auto-size Agent edit when the uploaded source image is high resolution', async () => {
         const { editImage } = await loadAgentRoutes();
         let upstreamCalls = 0;
         const upstream = await startImageUpstream(() => {
@@ -1436,11 +1601,10 @@ describe('Agent route integration', () => {
                 )
             );
 
-            assert.equal(response.status, 422);
+            assert.equal(response.status, 200);
             const body = await response.json();
-            assert.equal(body.error.code, 'validation_error');
-            assert.match(body.error.message, /\/api\/images/);
-            assert.equal(upstreamCalls, 0);
+            assert.equal(body.images[0].output_format, 'png');
+            assert.equal(upstreamCalls, 1);
         } finally {
             await upstream.close();
         }
@@ -1967,6 +2131,8 @@ function asNextRequest(request: Request): NextRequest {
 }
 
 function agentJsonRequest(idempotencyKey: string, body: Record<string, unknown>, headers: Record<string, string> = {}) {
+    const requestBody =
+        'stream_mode' in body || 'streaming_strategy' in body ? body : { ...body, stream_mode: 'non_stream' };
     return new Request('http://localhost/api/agent/images/generate', {
         method: 'POST',
         headers: {
@@ -1974,7 +2140,7 @@ function agentJsonRequest(idempotencyKey: string, body: Record<string, unknown>,
             'Idempotency-Key': idempotencyKey,
             ...headers
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(requestBody)
     });
 }
 
@@ -1983,6 +2149,8 @@ function agentJobJsonRequest(
     body: Record<string, unknown>,
     headers: Record<string, string> = {}
 ) {
+    const requestBody =
+        'stream_mode' in body || 'streaming_strategy' in body ? body : { ...body, stream_mode: 'non_stream' };
     return new Request('http://localhost/api/agent/jobs/images/generate', {
         method: 'POST',
         headers: {
@@ -1990,7 +2158,7 @@ function agentJobJsonRequest(
             'Idempotency-Key': idempotencyKey,
             ...headers
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(requestBody)
     });
 }
 
@@ -2010,6 +2178,9 @@ function agentEditRequest(
         typeof responseModeOrFields === 'string'
             ? { response_mode: responseModeOrFields }
             : { response_mode: 'path', ...responseModeOrFields };
+    if (!('stream_mode' in fields) && !('streaming_strategy' in fields)) {
+        fields.stream_mode = 'non_stream';
+    }
     const imageBuffer = fields.image_0 ?? Buffer.from(PNG_BASE64, 'base64');
     const formData = new FormData();
     formData.append('prompt', prompt);
@@ -2117,7 +2288,9 @@ async function startStreamingImageUpstream(
     ) => Array<{ event?: string; data: unknown }> | Promise<Array<{ event?: string; data: unknown }>>
 ): Promise<{ baseUrl: string; close: () => Promise<void> }> {
     const server = http.createServer(async (request, response) => {
-        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+        const isImageStreamPath =
+            request.url?.endsWith('/images/generations') || request.url?.endsWith('/images/edits');
+        if (request.method !== 'POST' || !isImageStreamPath) {
             response.writeHead(404, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify({ error: { message: 'not found' } }));
             return;

src/app/api/agent/images/edit/route.ts

@@ -1,7 +1,6 @@
 import { readAgentLeaseMs, readAgentRequestTtlSeconds } from '@/lib/agent-api-contracts';
 import { assertAgentAuthorized } from '@/lib/agent-auth';
 import {
-    assertAgentEditRouteAllowedFromFormData,
     buildEditRequestHashFromSnapshot,
     completeAgentExecutionState,
     createArtifactPersistenceError,
@@ -31,7 +30,6 @@ export async function POST(request: NextRequest) {
     try {
         assertAgentAuthorized(request.headers);
         const formData = await parseAgentEditFormData(request);
-        await assertAgentEditRouteAllowedFromFormData(formData);
         const idempotencyKey = readIdempotencyKey(request.headers);
         const requestSnapshot = await snapshotAgentEditFormData(formData);
         const store = await ensureAgentStateStoreReady();

src/app/api/images/route-test-helpers.ts

@@ -14,10 +14,19 @@ export function imageFormRequest(input: {
     mode?: 'generate' | 'edit';
     imageBackend?: 'images' | 'responses' | 'images-api' | 'responses-image-generation';
     imageStreamingStrategy?: 'off' | 'auto' | 'openai-sse' | 'newapi-keepalive-sse' | 'responses-sse' | 'force-sse';
+    imageStreamingStrategyField?: 'imageStreamingStrategy' | 'image_streaming_strategy';
+    streamMode?: 'auto' | 'stream' | 'non_stream';
     size?: string;
     n?: string;
     responsesModel?: string;
+    outputFormat?: 'png' | 'jpeg' | 'webp';
+    outputCompression?: string;
+    promptOptimization?: string;
+    gptModel?: string;
+    thinking?: string;
+    forceWeb?: string;
     clientRequestId?: string;
+    signal?: AbortSignal;
 }): NextRequest {
     const formData = new FormData();
     formData.append('mode', input.mode || 'generate');
@@ -25,15 +34,33 @@ export function imageFormRequest(input: {
     formData.append('model', 'gpt-image-2');
     formData.append('n', input.n || '1');
     formData.append('size', input.size || '1024x1024');
-    formData.append('output_format', 'png');
+    formData.append('output_format', input.outputFormat || 'png');
     formData.append('apiBaseUrl', input.apiBaseUrl);
     formData.append('apiKey', input.apiKey);
     formData.append('clientRequestId', input.clientRequestId ?? 'client-route-stream');
+    if (input.outputCompression) {
+        formData.append('output_compression', input.outputCompression);
+    }
+    if (input.promptOptimization) {
+        formData.append('promptOptimization', input.promptOptimization);
+    }
+    if (input.gptModel) {
+        formData.append('gptModel', input.gptModel);
+    }
+    if (input.thinking) {
+        formData.append('thinking', input.thinking);
+    }
+    if (input.forceWeb) {
+        formData.append('forceWeb', input.forceWeb);
+    }
     if (input.imageBackend) {
         formData.append('imageBackend', input.imageBackend);
     }
     if (input.imageStreamingStrategy) {
-        formData.append('imageStreamingStrategy', input.imageStreamingStrategy);
+        formData.append(input.imageStreamingStrategyField || 'imageStreamingStrategy', input.imageStreamingStrategy);
+    }
+    if (input.streamMode) {
+        formData.append('stream_mode', input.streamMode);
     }
     if (input.responsesModel) {
         formData.append('responsesModel', input.responsesModel);
@@ -47,7 +74,8 @@ export function imageFormRequest(input: {
     }
     return new Request('http://localhost/api/images', {
         method: 'POST',
-        body: formData
+        body: formData,
+        signal: input.signal
     }) as NextRequest;
 }
 
@@ -85,10 +113,21 @@ export async function startStreamingImageUpstream(
 }
 
 export async function startImagesJsonUpstream(
-    handler: (body: string, url: string) => Promise<unknown>
+    handler: (body: string, url: string) => Promise<unknown | Buffer>
 ): Promise<{ baseUrl: string; close: () => Promise<void> }> {
     const server = http.createServer(async (request, response) => {
         const isImagePath = request.url?.endsWith('/images/generations') || request.url?.endsWith('/images/edits');
+        if (request.method === 'GET') {
+            const payload = await handler('', request.url || '');
+            if (Buffer.isBuffer(payload)) {
+                response.writeHead(200, { 'Content-Type': 'image/png', 'Content-Length': String(payload.byteLength) });
+                response.end(payload);
+                return;
+            }
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
         if (request.method !== 'POST' || !isImagePath) {
             response.writeHead(404, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify({ error: { message: 'not found' } }));
@@ -98,12 +137,112 @@ export async function startImagesJsonUpstream(
         request.on('data', (chunk: Buffer) => chunks.push(chunk));
         await new Promise<void>((resolve) => request.on('end', resolve));
         const payload = await handler(Buffer.concat(chunks).toString('utf8'), request.url || '');
+        if (Buffer.isBuffer(payload)) {
+            response.writeHead(200, { 'Content-Type': 'image/png', 'Content-Length': String(payload.byteLength) });
+            response.end(payload);
+            return;
+        }
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify(payload));
     });
     return listen(server);
 }
 
+export async function startImagesStreamFallbackUpstream(): Promise<{
+    baseUrl: string;
+    calls: Array<{ stream?: boolean; partial_images?: number }>;
+    close: () => Promise<void>;
+}> {
+    const calls: Array<{ stream?: boolean; partial_images?: number }> = [];
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const payload = JSON.parse(Buffer.concat(chunks).toString('utf8')) as {
+            stream?: boolean;
+            partial_images?: number;
+        };
+        calls.push({ stream: payload.stream, partial_images: payload.partial_images });
+        if (payload.stream) {
+            response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+            response.write(
+                `event: image_generation.partial_image\ndata: ${JSON.stringify({
+                    type: 'image_generation.partial_image',
+                    b64_json: 'partial-before-fallback'
+                })}\n\n`
+            );
+            response.write('data: [DONE]\n\n');
+            response.end();
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ data: [{ b64_json: PNG_BASE64 }] }));
+    });
+    const result = await listen(server);
+    return { ...result, calls };
+}
+
+export async function startHangingImagesStreamUpstream(): Promise<{
+    baseUrl: string;
+    calls: Array<{ stream?: boolean; partial_images?: number }>;
+    waitForStreamRequest: () => Promise<void>;
+    close: () => Promise<void>;
+}> {
+    const calls: Array<{ stream?: boolean; partial_images?: number }> = [];
+    const activeResponses = new Set<http.ServerResponse>();
+    let resolveStreamRequest: () => void = () => {};
+    const streamRequest = new Promise<void>((resolve) => {
+        resolveStreamRequest = resolve;
+    });
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const payload = JSON.parse(Buffer.concat(chunks).toString('utf8')) as {
+            stream?: boolean;
+            partial_images?: number;
+        };
+        calls.push({ stream: payload.stream, partial_images: payload.partial_images });
+        if (!payload.stream) {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ data: [{ b64_json: PNG_BASE64 }] }));
+            return;
+        }
+        activeResponses.add(response);
+        response.on('close', () => activeResponses.delete(response));
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        response.write(
+            `event: image_generation.partial_image\ndata: ${JSON.stringify({
+                type: 'image_generation.partial_image',
+                b64_json: 'partial-before-abort'
+            })}\n\n`
+        );
+        resolveStreamRequest();
+    });
+    const result = await listen(server);
+    return {
+        ...result,
+        calls,
+        waitForStreamRequest: () => streamRequest,
+        close: async () => {
+            for (const response of activeResponses) {
+                response.destroy();
+            }
+            await result.close();
+        }
+    };
+}
+
 export async function startResponsesImageUpstream(
     handler: (body: string) => Promise<unknown>
 ): Promise<{ baseUrl: string; close: () => Promise<void> }> {
@@ -123,6 +262,45 @@ export async function startResponsesImageUpstream(
     return listen(server);
 }
 
+export async function startResponsesStreamFailureThenJsonUpstream(): Promise<{
+    baseUrl: string;
+    calls: Array<{ stream?: boolean }>;
+    close: () => Promise<void>;
+}> {
+    const calls: Array<{ stream?: boolean }> = [];
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/responses')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const payload = JSON.parse(Buffer.concat(chunks).toString('utf8')) as { stream?: boolean };
+        calls.push({ stream: payload.stream });
+        if (payload.stream) {
+            response.writeHead(500, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'stream setup failed' } }));
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(
+            JSON.stringify({
+                output: [
+                    {
+                        type: 'image_generation_call',
+                        status: 'completed',
+                        result: PNG_BASE64
+                    }
+                ]
+            })
+        );
+    });
+    const result = await listen(server);
+    return { ...result, calls };
+}
+
 export async function startStreamingResponsesImageUpstream(
     handler: (body: string) => Promise<Array<{ event?: string; data: unknown }>>
 ): Promise<{ baseUrl: string; close: () => Promise<void> }> {

src/app/api/images/route.test.ts

@@ -2,8 +2,11 @@ import {
     PNG_BASE64,
     imageFormRequest,
     readSseEvents,
+    startHangingImagesStreamUpstream,
     startImagesJsonUpstream,
+    startImagesStreamFallbackUpstream,
     startResponsesImageUpstream,
+    startResponsesStreamFailureThenJsonUpstream,
     startStreamingResponsesImageUpstream,
     startStreamingImageUpstream
 } from './route-test-helpers';
@@ -32,8 +35,15 @@ beforeEach(() => {
     delete process.env.APP_PASSWORD;
     delete process.env.OPENAI_API_KEY;
     delete process.env.OPENAI_API_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_1_ID;
     delete process.env.OPENAI_CHANNEL_1_API_KEYS;
     delete process.env.OPENAI_CHANNEL_1_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK;
+    delete process.env.OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY;
+    delete process.env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS;
     delete process.env.ENABLE_RESPONSES_IMAGE_BACKEND;
     delete process.env.IMAGE_GENERATION_BACKEND;
     delete process.env.OPENAI_RESPONSES_API_MODEL;
@@ -137,6 +147,7 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         const { POST } = await import('./route');
         let upstreamBody = '';
         const upstream = await startImagesJsonUpstream(async (body) => {
+            if (!body) return { ok: true };
             upstreamBody = body;
             return { data: [{ b64_json: PNG_BASE64 }] };
         });
@@ -169,6 +180,113 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('falls back from auto streaming without a final image and skips streaming for the same mark', async () => {
+        const { POST } = await import('./route');
+        const { getServerChannelState } = await import('@/lib/server-channel-router');
+        const upstream = await startImagesStreamFallbackUpstream();
+        const otherUpstream = await startImagesStreamFallbackUpstream();
+
+        try {
+            const first = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    streamMode: 'auto',
+                    clientRequestId: 'client-route-auto-fallback-1'
+                })
+            );
+
+            assert.equal(first.status, 200);
+            assert.equal(first.headers.get('content-type'), 'text/event-stream');
+            const events = await readSseEvents(first);
+            assert.deepEqual(
+                events.map((event) => event.type),
+                ['partial_image', 'completed', 'done']
+            );
+            assert.equal(events[2].fallback_used, true);
+            assert.deepEqual(
+                upstream.calls.map((call) => call.stream),
+                [true, false]
+            );
+            assert.equal(getServerChannelState().streamingAvailability.summary().mark_count, 1);
+
+            const second = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    streamMode: 'auto',
+                    clientRequestId: 'client-route-auto-fallback-2'
+                })
+            );
+
+            assert.equal(second.status, 200);
+            assert.notEqual(second.headers.get('content-type'), 'text/event-stream');
+            const body = (await second.json()) as { images?: Array<Record<string, unknown>> };
+            assert.equal(body.images?.[0]?.b64_json, PNG_BASE64);
+            assert.deepEqual(
+                upstream.calls.map((call) => call.stream),
+                [true, false, false]
+            );
+
+            const third = await POST(
+                imageFormRequest({
+                    apiBaseUrl: otherUpstream.baseUrl,
+                    apiKey: 'test-key',
+                    streamMode: 'auto',
+                    clientRequestId: 'client-route-auto-fallback-3'
+                })
+            );
+
+            assert.equal(third.status, 200);
+            assert.equal(third.headers.get('content-type'), 'text/event-stream');
+            await readSseEvents(third);
+            assert.deepEqual(
+                otherUpstream.calls.map((call) => call.stream),
+                [true, false]
+            );
+        } finally {
+            await upstream.close();
+            await otherUpstream.close();
+        }
+    });
+
+    it('does not mark auto streaming unavailable when the page SSE request is aborted', async () => {
+        const { POST } = await import('./route');
+        const { getServerChannelState } = await import('@/lib/server-channel-router');
+        const upstream = await startHangingImagesStreamUpstream();
+        const abortController = new AbortController();
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    streamMode: 'auto',
+                    clientRequestId: 'client-route-auto-abort',
+                    signal: abortController.signal
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.equal(response.headers.get('content-type'), 'text/event-stream');
+            const reader = response.body?.getReader();
+            assert.ok(reader);
+            await upstream.waitForStreamRequest();
+            abortController.abort();
+            await reader.cancel();
+            await new Promise((resolve) => setTimeout(resolve, 25));
+
+            assert.deepEqual(
+                upstream.calls.map((call) => call.stream),
+                [true]
+            );
+            assert.equal(getServerChannelState().streamingAvailability.summary().mark_count, 0);
+        } finally {
+            abortController.abort();
+            await upstream.close();
+        }
+    });
+
     it('returns an explicit SSE error when the upstream completed event has no image payload', async () => {
         const { POST } = await import('./route');
         const upstream = await startStreamingImageUpstream(async () => [
@@ -285,6 +403,48 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('accepts snake_case image streaming strategy on page SSE edit requests', async () => {
+        const { POST } = await import('./route');
+        let upstreamUrl = '';
+        let upstreamBody = '';
+        const upstream = await startStreamingImageUpstream(async (body, url) => {
+            upstreamUrl = url;
+            upstreamBody = body;
+            return [
+                {
+                    event: 'image_edit.completed',
+                    data: { type: 'image_edit.completed', b64_json: PNG_BASE64 }
+                }
+            ];
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    mode: 'edit',
+                    stream: true,
+                    imageStreamingStrategy: 'force-sse',
+                    imageStreamingStrategyField: 'image_streaming_strategy'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.equal(response.headers.get('content-type'), 'text/event-stream');
+            const events = await readSseEvents(response);
+            assert.deepEqual(
+                events.map((event) => event.type),
+                ['completed', 'done']
+            );
+            assert.equal(upstreamUrl, '/v1/images/edits');
+            assert.match(upstreamBody, /name="stream"/);
+            assert.match(upstreamBody, /name="partial_images"/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('rejects explicit image stream requests when the server strategy disables streaming', async () => {
         process.env.IMAGE_STREAMING_STRATEGY = 'off';
         const { POST } = await import('./route');
@@ -435,12 +595,13 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
     it('rejects the experimental Responses API backend when the feature flag is disabled', async () => {
         const { POST } = await import('./route');
         const response = await POST(
-            imageFormRequest({
-                apiBaseUrl: 'http://127.0.0.1:1/v1',
-                apiKey: 'test-key',
-                stream: false,
-                imageBackend: 'responses'
-            })
+                imageFormRequest({
+                    apiBaseUrl: 'http://127.0.0.1:1/v1',
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses'
+                })
         );
 
         assert.equal(response.status, 400);
@@ -452,12 +613,13 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
         const { POST } = await import('./route');
         const response = await POST(
-            imageFormRequest({
-                apiBaseUrl: 'http://127.0.0.1:1/v1',
-                apiKey: 'test-key',
-                stream: false,
-                imageBackend: 'responses'
-            })
+                imageFormRequest({
+                    apiBaseUrl: 'http://127.0.0.1:1/v1',
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses'
+                })
         );
 
         assert.equal(response.status, 400);
@@ -471,28 +633,36 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         const { POST } = await import('./route');
 
         const multiImage = await POST(
-            imageFormRequest({
-                apiBaseUrl: 'http://127.0.0.1:1/v1',
-                apiKey: 'test-key',
-                stream: false,
-                imageBackend: 'responses',
-                n: '2'
-            })
+                imageFormRequest({
+                    apiBaseUrl: 'http://127.0.0.1:1/v1',
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses',
+                    n: '2'
+                })
         );
         assert.equal(multiImage.status, 400);
         assert.match(String(((await multiImage.json()) as Record<string, unknown>).error), /单张生成/);
+    });
 
+    it('rejects multi-image edit requests for the Responses API backend before contacting upstream', async () => {
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1';
+        const { POST } = await import('./route');
         const edit = await POST(
-            imageFormRequest({
-                apiBaseUrl: 'http://127.0.0.1:1/v1',
-                apiKey: 'test-key',
-                stream: false,
-                imageBackend: 'responses',
-                mode: 'edit'
-            })
+                imageFormRequest({
+                    apiBaseUrl: 'http://127.0.0.1:1/v1',
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses',
+                    n: '2',
+                    mode: 'edit'
+                })
         );
         assert.equal(edit.status, 400);
-        assert.match(String(((await edit.json()) as Record<string, unknown>).error), /只支持 generate/);
+        assert.match(String(((await edit.json()) as Record<string, unknown>).error), /单张编辑/);
     });
 
     it('uses the Responses API image backend only when the flag and request opt-in are both present', async () => {
@@ -520,6 +690,7 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
                     stream: false,
+                    streamMode: 'non_stream',
                     imageBackend: 'responses-image-generation'
                 })
             );
@@ -565,6 +736,7 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
                     stream: false,
+                    streamMode: 'non_stream',
                     imageBackend: 'responses-image-generation'
                 })
             );
@@ -588,13 +760,14 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                 imageFormRequest({
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
-                    stream: false
+                    stream: false,
+                    streamMode: 'non_stream'
                 })
             );
 
             assert.equal(response.status, 502);
             const body = (await response.json()) as Record<string, unknown>;
-            assert.match(String(body.error), /base64/);
+            assert.match(String(body.error), /同源/);
             assert.equal(JSON.stringify(body).includes('https://example.test/final.png'), false);
         } finally {
             await upstream.close();
@@ -841,7 +1014,8 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                 imageFormRequest({
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
-                    stream: false
+                    stream: false,
+                    streamMode: 'non_stream'
                 })
             );
 
@@ -856,12 +1030,68 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('downloads same-origin GPT2Image URL results before persisting Images API JSON responses', async () => {
+        const { POST } = await import('./route');
+        let imageDownloadCount = 0;
+        const upstream = await startImagesJsonUpstream(async (_body, url) => {
+            if (url === '/generated/final.png') {
+                imageDownloadCount += 1;
+                return Buffer.from(PNG_BASE64, 'base64');
+            }
+            return { data: [{ url: '/generated/final.png' }] };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const body = (await response.json()) as { images?: Array<Record<string, unknown>> };
+            assert.equal(body.images?.[0]?.b64_json, PNG_BASE64);
+            assert.equal(imageDownloadCount, 1);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('rejects cross-origin GPT2Image URL results before downloading them', async () => {
+        const { POST } = await import('./route');
+        const upstream = await startImagesJsonUpstream(async () => {
+            return { data: [{ url: 'https://other.example.test/generated/final.png' }] };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream'
+                })
+            );
+
+            assert.equal(response.status, 502);
+            const body = (await response.json()) as Record<string, unknown>;
+            assert.match(String(body.error), /同源/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('does not apply the generate backend env default to edit requests', async () => {
         process.env.IMAGE_GENERATION_BACKEND = 'responses';
         const { POST } = await import('./route');
         let upstreamUrl = '';
         const upstream = await startImagesJsonUpstream(async (_body, url) => {
-            upstreamUrl = url;
+            if (url !== '/api/log/token') {
+                upstreamUrl = url;
+            }
             return { data: [{ b64_json: PNG_BASE64 }] };
         });
 
@@ -871,7 +1101,8 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
                     mode: 'edit',
-                    stream: false
+                    stream: false,
+                    streamMode: 'non_stream'
                 })
             );
 
@@ -953,6 +1184,22 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('rejects remote plain-http API base URLs before forwarding API keys', async () => {
+        const { POST } = await import('./route');
+
+        const response = await POST(
+            imageFormRequest({
+                apiBaseUrl: 'http://api.example.com/v1',
+                apiKey: 'test-key',
+                stream: false
+            })
+        );
+
+        assert.equal(response.status, 400);
+        const body = (await response.json()) as Record<string, unknown>;
+        assert.match(String(body.error), /远程 HTTP API URL/);
+    });
+
     it('treats blank APP_PASSWORD as disabled for page SSE auth', async () => {
         process.env.APP_PASSWORD = '   ';
         const { POST } = await import('./route');
@@ -1010,7 +1257,7 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
-    it('rejects invalid gpt-image-2 custom sizes before contacting upstream', async () => {
+    it('rejects invalid gpt-image-2 custom size boundaries before contacting upstream', async () => {
         const { POST } = await import('./route');
         let upstreamCalls = 0;
         const upstream = await startImagesJsonUpstream(async () => {
@@ -1018,26 +1265,70 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
             return { data: [{ b64_json: PNG_BASE64 }] };
         });
 
+        try {
+            for (const { size, pattern } of [
+                { size: '512x512', pattern: /至少/ },
+                { size: '3840x3840', pattern: /不能超过/ },
+                { size: '2049x2048', pattern: /16 的倍数/ }
+            ]) {
+                const response = await POST(
+                    imageFormRequest({
+                        apiBaseUrl: upstream.baseUrl,
+                        apiKey: 'test-key',
+                        size
+                    })
+                );
+
+                assert.equal(response.status, 400);
+                const body = (await response.json()) as Record<string, unknown>;
+                assert.match(String(body.error), /size 对 gpt-image-2 无效/);
+                assert.match(String(body.error), pattern);
+            }
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('lets request responsesModel override the experimental backend env model', async () => {
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1-env';
+        const { POST } = await import('./route');
+        let upstreamBody = '';
+        const upstream = await startResponsesImageUpstream(async (body) => {
+            upstreamBody = body;
+            return {
+                output: [
+                    {
+                        type: 'image_generation_call',
+                        status: 'completed',
+                        result: PNG_BASE64
+                    }
+                ]
+            };
+        });
+
         try {
             const response = await POST(
                 imageFormRequest({
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
-                    size: '2049x2048'
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses',
+                    responsesModel: 'gpt-4.1-request'
                 })
             );
 
-            assert.equal(response.status, 400);
-            const body = (await response.json()) as Record<string, unknown>;
-            assert.match(String(body.error), /size 对 gpt-image-2 无效/);
-            assert.match(String(body.error), /16 的倍数/);
-            assert.equal(upstreamCalls, 0);
+            assert.equal(response.status, 200);
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.model, 'gpt-4.1-request');
         } finally {
             await upstream.close();
         }
     });
 
-    it('lets request responsesModel override the experimental backend env model', async () => {
+    it('passes GPT2Image-compatible extended fields to the Responses image backend', async () => {
         process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
         process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1-env';
         const { POST } = await import('./route');
@@ -1061,14 +1352,178 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
                     apiBaseUrl: upstream.baseUrl,
                     apiKey: 'test-key',
                     stream: false,
+                    streamMode: 'non_stream',
                     imageBackend: 'responses',
-                    responsesModel: 'gpt-4.1-request'
+                    size: '1536x864',
+                    outputFormat: 'webp',
+                    outputCompression: '85',
+                    promptOptimization: 'false',
+                    gptModel: 'gpt-5.4-mini',
+                    thinking: 'high'
                 })
             );
 
             assert.equal(response.status, 200);
             const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
-            assert.equal(upstreamJson.model, 'gpt-4.1-request');
+            assert.equal(upstreamJson.model, 'gpt-5.4-mini');
+            const tools = upstreamJson.tools as Array<Record<string, unknown>>;
+            assert.equal(tools[0].size, '1536x864');
+            assert.equal(tools[0].output_format, 'webp');
+            assert.equal(tools[0].output_compression, 85);
+            assert.equal(tools[0].prompt_optimization, false);
+            assert.equal(tools[0].thinking, 'high');
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('passes GPT2Image-compatible edit fields to the Images API backend', async () => {
+        const { POST } = await import('./route');
+        let upstreamBody = '';
+        const upstream = await startImagesJsonUpstream(async (body) => {
+            if (!body) return { ok: true };
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    mode: 'edit',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    outputFormat: 'webp',
+                    outputCompression: '85',
+                    forceWeb: 'true'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.match(upstreamBody, /name="output_format"/);
+            assert.match(upstreamBody, /\r\nwebp\r\n/);
+            assert.match(upstreamBody, /name="output_compression"/);
+            assert.match(upstreamBody, /\r\n85\r\n/);
+            assert.match(upstreamBody, /name="force_web"/);
+            assert.match(upstreamBody, /\r\ntrue\r\n/);
+            assert.match(upstreamBody, /name="moderation"/);
+            assert.match(upstreamBody, /\r\nauto\r\n/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('passes reference images and GPT2Image-compatible fields to the Responses edit backend', async () => {
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1-env';
+        const { POST } = await import('./route');
+        let upstreamBody = '';
+        const upstream = await startResponsesImageUpstream(async (body) => {
+            upstreamBody = body;
+            return {
+                output: [
+                    {
+                        type: 'image_generation_call',
+                        status: 'completed',
+                        result: PNG_BASE64
+                    }
+                ]
+            };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    mode: 'edit',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    imageBackend: 'responses',
+                    size: '1536x864',
+                    outputFormat: 'webp',
+                    outputCompression: '85',
+                    promptOptimization: 'false',
+                    gptModel: 'gpt-5.4-mini',
+                    thinking: 'high'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.model, 'gpt-5.4-mini');
+            assert.equal(upstreamJson.stream, false);
+            const input = upstreamJson.input as Array<Record<string, unknown>>;
+            assert.equal(input[0].role, 'user');
+            const content = input[0].content as Array<Record<string, unknown>>;
+            assert.equal(content[0].type, 'input_text');
+            assert.equal(content[0].text, 'route stream contract');
+            assert.equal(content[1].type, 'input_image');
+            assert.match(String(content[1].image_url), /^data:image\/png;base64,/);
+            const tools = upstreamJson.tools as Array<Record<string, unknown>>;
+            assert.equal(tools[0].type, 'image_generation');
+            assert.equal(tools[0].size, '1536x864');
+            assert.equal(tools[0].output_format, 'webp');
+            assert.equal(tools[0].output_compression, 85);
+            assert.equal(tools[0].prompt_optimization, false);
+            assert.equal(tools[0].thinking, 'high');
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('falls back when Responses edit stream setup fails before returning SSE', async () => {
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1';
+        const { POST } = await import('./route');
+        const upstream = await startResponsesStreamFailureThenJsonUpstream();
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    mode: 'edit',
+                    streamMode: 'auto',
+                    imageBackend: 'responses'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.match(response.headers.get('content-type') || '', /application\/json/);
+            const body = (await response.json()) as { images?: Array<Record<string, unknown>> };
+            assert.equal(body.images?.[0]?.b64_json, PNG_BASE64);
+            assert.equal(upstream.calls[0]?.stream, true);
+            assert.equal(upstream.calls[upstream.calls.length - 1]?.stream, false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('passes GPT2Image force_web aliases through to the Images API backend', async () => {
+        const { POST } = await import('./route');
+        let upstreamBody = '';
+        const upstream = await startImagesJsonUpstream(async (body) => {
+            if (!body) return { ok: true };
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    stream: false,
+                    streamMode: 'non_stream',
+                    forceWeb: 'true'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.force_web, true);
         } finally {
             await upstream.close();
         }

src/app/api/images/route.ts

@@ -6,6 +6,7 @@ import {
     readCount,
     readMode,
     readModel,
+    readPlainHttpApiBaseUrlAllowlist,
     readRequiredText,
     readStorageMode,
     validateApiBaseUrl
@@ -30,22 +31,147 @@ import {
 } from '@/lib/image-service';
 import {
     readImageGenerationBackend,
+    readImageStreamMode,
     readImageStreamingStrategy,
-    resolveImageStreamEnabled
+    resolveImageStreamEnabled,
+    type ImageGenerationBackend,
+    type ImageStreamMode,
+    type ImageStreamingStrategy
 } from '@/lib/image-upstream-strategy';
 import { PAGE_PASSWORD_AUTH_ERROR_CODES } from '@/lib/page-password-auth';
 import { getServerChannelState } from '@/lib/server-channel-router';
+import type { StreamingAvailabilityKey, StreamingOperation } from '@/lib/streaming-availability';
 import { buildAccessCookie, readAffinityKey, verifyPasswordHash } from '@/lib/server-runtime';
+import crypto from 'crypto';
 import { NextRequest, NextResponse } from 'next/server';
 import OpenAI from 'openai';
 
+type StreamResolutionInput = {
+    streamMode: ImageStreamMode;
+    imageBackend: ImageGenerationBackend;
+    streamingStrategy: ImageStreamingStrategy;
+    operation: StreamingOperation;
+    selectedCredential?: ChannelCredential;
+    sourceId?: string;
+};
+
+type StreamResolution = {
+    availabilityKey: StreamingAvailabilityKey;
+    streamEnabled: boolean;
+    streamFallbackEnabled: boolean;
+    streamingMarkedUnavailable: boolean;
+};
+
+function readErrorStatus(error: unknown): number | undefined {
+    if (typeof error !== 'object' || error === null) return undefined;
+    if ('status' in error && typeof error.status === 'number') return error.status;
+    if ('statusCode' in error && typeof error.statusCode === 'number') return error.statusCode;
+    return undefined;
+}
+
+function readErrorCode(error: unknown): string | undefined {
+    if (typeof error !== 'object' || error === null) return undefined;
+    if ('code' in error && typeof error.code === 'string') return error.code;
+    if ('error' in error && typeof error.error === 'object' && error.error !== null) {
+        const nested = error.error as Record<string, unknown>;
+        return typeof nested.code === 'string' ? nested.code : undefined;
+    }
+    return undefined;
+}
+
+function createAvailabilityKey(input: StreamResolutionInput): StreamingAvailabilityKey {
+    return {
+        channelId: input.selectedCredential?.channelId,
+        sourceId: input.selectedCredential ? undefined : input.sourceId,
+        imageBackend: input.imageBackend,
+        streamingStrategy: input.streamingStrategy,
+        operation: input.operation
+    };
+}
+
+function createAvailabilitySourceId(input: { selectedCredential?: ChannelCredential; baseUrl?: string }): string | undefined {
+    if (input.selectedCredential) return undefined;
+    const normalized = normalizeAvailabilityBaseUrl(input.baseUrl);
+    const digest = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+    return `upstream:${digest}`;
+}
+
+function normalizeAvailabilityBaseUrl(baseUrl: string | undefined): string {
+    const rawValue = baseUrl && baseUrl.trim() ? baseUrl.trim() : 'https://api.openai.com/v1';
+    try {
+        const parsed = new URL(rawValue);
+        const pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+        return `${parsed.protocol}//${parsed.host}${pathname}`.toLowerCase();
+    } catch {
+        return 'invalid-upstream';
+    }
+}
+
+function resolvePageStream(input: StreamResolutionInput): StreamResolution {
+    const availabilityKey = createAvailabilityKey(input);
+    const streamingAvailability = getServerChannelState().streamingAvailability;
+    if (input.streamMode === 'non_stream') {
+        return {
+            availabilityKey,
+            streamEnabled: false,
+            streamFallbackEnabled: false,
+            streamingMarkedUnavailable: streamingAvailability.isUnavailable(availabilityKey)
+        };
+    }
+
+    if (input.streamMode === 'auto' && input.streamingStrategy === 'off') {
+        return {
+            availabilityKey,
+            streamEnabled: false,
+            streamFallbackEnabled: false,
+            streamingMarkedUnavailable: streamingAvailability.isUnavailable(availabilityKey)
+        };
+    }
+
+    if (input.streamMode === 'auto' && streamingAvailability.isUnavailable(availabilityKey)) {
+        return {
+            availabilityKey,
+            streamEnabled: false,
+            streamFallbackEnabled: false,
+            streamingMarkedUnavailable: true
+        };
+    }
+
+    return {
+        availabilityKey,
+        streamEnabled: resolveImageStreamEnabled({
+            imageBackend: input.imageBackend,
+            requestedStream: true,
+            streamingStrategy: input.streamingStrategy
+        }),
+        streamFallbackEnabled: input.streamMode === 'auto',
+        streamingMarkedUnavailable: false
+    };
+}
+
+function markStreamingUnavailable(input: {
+    key: StreamingAvailabilityKey;
+    error?: unknown;
+    reason: string;
+    status?: number;
+}) {
+    const status = input.status ?? readErrorStatus(input.error);
+    getServerChannelState().streamingAvailability.markUnavailable({
+        ...input.key,
+        reason: input.reason,
+        ...(status !== undefined ? { status } : {}),
+        ...(readErrorCode(input.error) ? { code: readErrorCode(input.error) } : {})
+    });
+}
+
 export async function POST(request: NextRequest) {
     let selectedServerCredential: ChannelCredential | undefined;
     let clientRequestId: string | undefined;
     let requestLogContext: RequestLogContext | undefined;
     let accessCookie: AccessCookie | undefined;
     try {
-        const serverChannelRouter = getServerChannelState().router;
+        const serverChannelState = getServerChannelState();
+        const serverChannelRouter = serverChannelState.router;
         const contentType = request.headers.get('content-type') || '';
         if (
             !contentType.includes('multipart/form-data') &&
@@ -58,8 +184,11 @@ export async function POST(request: NextRequest) {
         requestLogContext = clientRequestId ? { clientRequestId } : undefined;
         const requestApiKey = String(formData.get('apiKey') || '').trim();
         const requestApiBaseUrl = String(formData.get('apiBaseUrl') || '').trim();
+        const allowedPlainHttpBaseUrls = readPlainHttpApiBaseUrlAllowlist(
+            process.env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS
+        );
         assertSafeApiOverride(requestApiKey, requestApiBaseUrl);
-        validateApiBaseUrl(requestApiBaseUrl);
+        validateApiBaseUrl(requestApiBaseUrl, { allowedPlainHttpBaseUrls });
         selectedServerCredential = requestApiKey
             ? undefined
             : serverChannelRouter?.select({ affinityKey: readAffinityKey(request.headers) });
@@ -73,7 +202,7 @@ export async function POST(request: NextRequest) {
             legacyBaseUrl: process.env.OPENAI_API_BASE_URL,
             selectedCredential: selectedServerCredential
         });
-        validateApiBaseUrl(effectiveApiBaseUrl || '');
+        validateApiBaseUrl(effectiveApiBaseUrl || '', { allowedPlainHttpBaseUrls });
 
         if (!effectiveApiKey) {
             appLogger.error('未设置 OPENAI_API_KEY，且请求未提供 API Key。', requestLogContext);
@@ -132,24 +261,34 @@ export async function POST(request: NextRequest) {
             requestLogContext
         );
 
-        const requestedStream = formData.get('stream') === 'true';
+        const streamMode = readImageStreamMode(formData, process.env);
         const partialImagesCount = readCount(formData, 'partial_images', 2, 1, 3) as 1 | 2 | 3;
-        const imageBackend = readImageGenerationBackend(formData, process.env, { useEnvDefault: mode === 'generate' });
+        const imageBackend = readImageGenerationBackend(formData, process.env, {
+            useEnvDefault: mode === 'generate'
+        });
         const streamingStrategy = readImageStreamingStrategy(formData, process.env, {
             useEnvDefault: mode === 'generate'
         });
-        const streamEnabled = resolveImageStreamEnabled({
+        const streamResolution = resolvePageStream({
+            streamMode,
             imageBackend,
-            requestedStream,
-            streamingStrategy
+            streamingStrategy,
+            operation: mode,
+            selectedCredential,
+            sourceId: createAvailabilitySourceId({
+                selectedCredential,
+                baseUrl: effectiveApiBaseUrl
+            })
         });
         assertResponsesImageBackendAllowed({ imageBackend, mode });
         appLogger.info('图片上游兼容策略。', {
             ...requestLogContext,
             imageBackend,
             streamingStrategy,
-            requestedStream,
-            streamEnabled
+            streamMode,
+            streamEnabled: streamResolution.streamEnabled,
+            streamFallbackEnabled: streamResolution.streamFallbackEnabled,
+            streamingMarkedUnavailable: streamResolution.streamingMarkedUnavailable
         });
 
         const modeResult =
@@ -159,7 +298,7 @@ export async function POST(request: NextRequest) {
                       openai,
                       model,
                       prompt,
-                      streamEnabled,
+                      streamEnabled: streamResolution.streamEnabled,
                       partialImagesCount,
                       imageBackend,
                       storageMode: effectiveStorageMode,
@@ -170,15 +309,25 @@ export async function POST(request: NextRequest) {
                       requestLogContext,
                       selectedCredential,
                       accessCookie,
-                      abortSignal: request.signal
+                      abortSignal: request.signal,
+                      streamFallbackEnabled: streamResolution.streamFallbackEnabled,
+                      onStreamUnavailable: (error, reason) =>
+                          markStreamingUnavailable({ key: streamResolution.availabilityKey, error, reason }),
+                      onStreamingDegraded: (reason) =>
+                          markStreamingUnavailable({
+                              key: streamResolution.availabilityKey,
+                              reason,
+                              status: 200
+                          })
                   })
                 : await handleEditImageMode({
                       formData,
                       openai,
                       model,
                       prompt,
-                      streamEnabled,
+                      streamEnabled: streamResolution.streamEnabled,
                       partialImagesCount,
+                      imageBackend,
                       storageMode: effectiveStorageMode,
                       apiBaseUrl: effectiveApiBaseUrl,
                       apiKey: effectiveApiKey,
@@ -187,7 +336,16 @@ export async function POST(request: NextRequest) {
                       requestLogContext,
                       selectedCredential,
                       accessCookie,
-                      abortSignal: request.signal
+                      abortSignal: request.signal,
+                      streamFallbackEnabled: streamResolution.streamFallbackEnabled,
+                      onStreamUnavailable: (error, reason) =>
+                          markStreamingUnavailable({ key: streamResolution.availabilityKey, error, reason }),
+                      onStreamingDegraded: (reason) =>
+                          markStreamingUnavailable({
+                              key: streamResolution.availabilityKey,
+                              reason,
+                              status: 200
+                          })
                   });
         if (modeResult instanceof Response) {
             return modeResult;
@@ -201,7 +359,10 @@ export async function POST(request: NextRequest) {
                 result,
                 outputFormat: responseOutputFormat,
                 storageMode: effectiveStorageMode,
-                includeBase64: true
+                includeBase64: true,
+                apiBaseUrl: effectiveApiBaseUrl,
+                apiKey: effectiveApiKey,
+                abortSignal: request.signal
             });
             const savedImagesData = savedImages.map((image) => ({
                 ...persistedImageToLegacyResponse(image),

src/app/api/runtime-capabilities/route.test.ts

@@ -17,24 +17,149 @@ function restoreProcessEnv(snapshot: NodeJS.ProcessEnv) {
 
 beforeEach(() => {
     originalEnv = { ...process.env };
+    process.env.npm_lifecycle_event = 'test';
     delete process.env.ENABLE_RESPONSES_IMAGE_BACKEND;
+    delete process.env.OPENAI_RESPONSES_API_MODEL;
+    delete process.env.IMAGE_STREAMING_STRATEGY;
+    delete process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_1_ID;
+    delete process.env.OPENAI_CHANNEL_1_API_KEYS;
+    delete process.env.OPENAI_CHANNEL_1_BASE_URL;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS;
+    delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK;
+    delete process.env.OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY;
+    delete process.env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS;
 });
 
-afterEach(() => {
+afterEach(async () => {
+    const { resetServerChannelStateForTests } = await import('@/lib/server-channel-router');
+    resetServerChannelStateForTests();
     restoreProcessEnv(originalEnv);
 });
 
-describe('GET /api/runtime-capabilities', () => {
-    it('exposes the experimental Responses image backend flag without enabling it by default', async () => {
+describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
+    it('exposes streaming batch capability by default without the removed env gate', async () => {
         const { GET } = await import('./route');
 
-        const disabled = (await (await GET()).json()) as Record<string, { enabled: boolean; mode?: string }>;
+        const body = (await (await GET()).json()) as Record<string, { enabled: boolean; recommendedConcurrency?: number }>;
+
+        assert.equal(body.streamingBatch.enabled, true);
+        assert.equal(typeof body.streamingBatch.recommendedConcurrency, 'number');
+    });
+
+    it('exposes the runtime default streaming strategy for client-side fanout decisions', async () => {
+        process.env.IMAGE_STREAMING_STRATEGY = 'off';
+        const { GET } = await import('./route');
+
+        const body = (await (await GET()).json()) as Record<string, { defaultMode?: string; defaultStrategy?: string }>;
+
+        assert.equal(body.streaming.defaultMode, 'non_stream');
+        assert.equal(body.streaming.defaultStrategy, 'off');
+    });
+
+    it('exposes recovery probe settings without API keys', async () => {
+        process.env.OPENAI_CHANNEL_1_ID = 'official';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = 'https://api.openai.com/v1';
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'sk-secret';
+        process.env.OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS = '120000';
+        process.env.OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS = '3000';
+        process.env.OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK = '1';
+        const { GET } = await import('./route');
+
+        const body = (await (await GET()).json()) as {
+            channelRecovery: {
+                requireProbeForRecovery: boolean;
+                pendingProbeCredentialCount: number;
+                pendingProbeChannelCount: number;
+                probe: {
+                    enabled: boolean;
+                    intervalMs: number;
+                    timeoutMs: number;
+                    maxPerTick: number;
+                    running: boolean;
+                };
+            };
+        };
+
+        assert.deepEqual(body.channelRecovery, {
+            requireProbeForRecovery: true,
+            pendingProbeCredentialCount: 0,
+            pendingProbeChannelCount: 0,
+            probe: {
+                enabled: true,
+                intervalMs: 120000,
+                timeoutMs: 3000,
+                maxPerTick: 1,
+                running: false,
+                pendingProbeCount: 0,
+                dueCandidateCount: 0,
+                estimatedMinimumDrainTickCount: 0,
+                estimatedMinimumDrainMs: 0,
+                lastCheckedCount: 0,
+                lastRecoveredCount: 0,
+                lastFailedCount: 0
+            }
+        });
+        assert.equal(JSON.stringify(body).includes('sk-secret'), false);
+    });
+
+    it('rejects requiring recovery probes when the prober is disabled', async () => {
+        process.env.OPENAI_CHANNEL_1_ID = 'official';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = 'https://api.openai.com/v1';
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'sk-secret';
+        process.env.OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED = 'false';
+        process.env.OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY = 'true';
+        const { GET } = await import('./route');
+
+        const response = await GET();
+        const body = (await response.json()) as { error?: string };
+
+        assert.equal(response.status, 500);
+        assert.match(body.error || '', /OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY/);
+        assert.equal(JSON.stringify(body).includes('sk-secret'), false);
+    });
+
+    it('exposes the experimental Responses image backend when the backend flag is enabled', async () => {
+        const { GET } = await import('./route');
+
+        const disabled = (await (await GET()).json()) as Record<
+            string,
+            {
+                enabled: boolean;
+                mode?: string;
+                requiredEnv?: string[];
+                optionalEnv?: string[];
+                hasDefaultModel?: boolean;
+                missingEnv?: string[];
+            }
+        >;
         assert.equal(disabled.responsesImageBackend.enabled, false);
         assert.equal(disabled.responsesImageBackend.mode, 'experimental');
+        assert.deepEqual(disabled.responsesImageBackend.requiredEnv, ['ENABLE_RESPONSES_IMAGE_BACKEND']);
+        assert.deepEqual(disabled.responsesImageBackend.optionalEnv, ['OPENAI_RESPONSES_API_MODEL']);
+        assert.equal(disabled.responsesImageBackend.hasDefaultModel, false);
+        assert.deepEqual(disabled.responsesImageBackend.missingEnv, ['ENABLE_RESPONSES_IMAGE_BACKEND']);
 
         process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
-        const enabled = (await (await GET()).json()) as Record<string, { enabled: boolean; mode?: string }>;
+        const requestModelAllowed = (await (await GET()).json()) as Record<
+            string,
+            { enabled: boolean; mode?: string; hasDefaultModel?: boolean; missingEnv?: string[] }
+        >;
+        assert.equal(requestModelAllowed.responsesImageBackend.enabled, true);
+        assert.equal(requestModelAllowed.responsesImageBackend.hasDefaultModel, false);
+        assert.deepEqual(requestModelAllowed.responsesImageBackend.missingEnv, []);
+
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1';
+        const enabled = (await (await GET()).json()) as Record<
+            string,
+            { enabled: boolean; mode?: string; hasDefaultModel?: boolean; missingEnv?: string[] }
+        >;
         assert.equal(enabled.responsesImageBackend.enabled, true);
         assert.equal(enabled.responsesImageBackend.mode, 'experimental');
+        assert.equal(enabled.responsesImageBackend.hasDefaultModel, true);
+        assert.deepEqual(enabled.responsesImageBackend.missingEnv, []);
     });
 });

src/app/api/runtime-capabilities/route.ts

@@ -1,17 +1,22 @@
 import { getChannelPoolSummary, toPublicChannelFailure } from '@/lib/channel-router';
+import { readImageStreamMode, readImageStreamingStrategy } from '@/lib/image-upstream-strategy';
 import { getServerChannelState } from '@/lib/server-channel-router';
 import { computeStreamingBatchRecommendation } from '@/lib/streaming-batch';
 import { readBooleanEnv, readPositiveIntegerEnv } from '@/lib/server-runtime';
 import { NextResponse } from 'next/server';
 
+const RESPONSES_IMAGE_BACKEND_REQUIRED_ENV = ['ENABLE_RESPONSES_IMAGE_BACKEND'] as const;
+const RESPONSES_IMAGE_BACKEND_OPTIONAL_ENV = ['OPENAI_RESPONSES_API_MODEL'] as const;
+
 export async function GET() {
     try {
         const serverChannelState = getServerChannelState();
         const summary = getChannelPoolSummary(serverChannelState.config);
         const healthSummary = serverChannelState.router?.getHealthSummary();
         const maxStreamsPerCredential = readPositiveIntegerEnv(process.env, 'OPENAI_MAX_STREAMS_PER_CREDENTIAL', 1);
-        const streamingBatchEnabled = readBooleanEnv(process.env, 'ENABLE_STREAMING_BATCH');
         const responsesImageBackendEnabled = readBooleanEnv(process.env, 'ENABLE_RESPONSES_IMAGE_BACKEND');
+        const responsesImageBackendHasDefaultModel = Boolean(process.env.OPENAI_RESPONSES_API_MODEL?.trim());
+        const responsesImageBackendMissingEnv = readResponsesImageBackendMissingEnv(process.env);
         const recommendedStreamingConcurrency = computeStreamingBatchRecommendation({
             credentialCount: healthSummary?.healthyCredentialCount ?? summary.credentialCount,
             maxStreamsPerCredential,
@@ -19,8 +24,14 @@ export async function GET() {
         });
 
         return NextResponse.json({
+            streaming: {
+                defaultMode: readImageStreamMode(new FormData(), process.env),
+                defaultStrategy: readImageStreamingStrategy(new FormData(), process.env),
+                unavailableMarkScope: 'channel+backend+strategy+operation',
+                availability: serverChannelState.streamingAvailability.summary()
+            },
             streamingBatch: {
-                enabled: streamingBatchEnabled,
+                enabled: true,
                 recommendedConcurrency: recommendedStreamingConcurrency,
                 requestCredentialConcurrency: maxStreamsPerCredential,
                 healthyCredentialCount: healthSummary?.healthyCredentialCount ?? summary.credentialCount,
@@ -30,9 +41,19 @@ export async function GET() {
                 unhealthyChannelCount: healthSummary?.unhealthyChannelCount ?? 0,
                 lastFailure: toPublicChannelFailure(healthSummary?.lastFailure)
             },
+            channelRecovery: {
+                requireProbeForRecovery: serverChannelState.channelRecovery.requireProbeForRecovery,
+                pendingProbeCredentialCount: healthSummary?.pendingRecoveryProbeCredentialCount ?? 0,
+                pendingProbeChannelCount: healthSummary?.pendingRecoveryProbeChannelCount ?? 0,
+                probe: serverChannelState.channelRecoveryProber?.summary()
+            },
             responsesImageBackend: {
                 enabled: responsesImageBackendEnabled,
-                mode: 'experimental'
+                mode: 'experimental',
+                requiredEnv: [...RESPONSES_IMAGE_BACKEND_REQUIRED_ENV],
+                optionalEnv: [...RESPONSES_IMAGE_BACKEND_OPTIONAL_ENV],
+                hasDefaultModel: responsesImageBackendHasDefaultModel,
+                missingEnv: responsesImageBackendMissingEnv
             }
         });
     } catch (error) {
@@ -42,3 +63,11 @@ export async function GET() {
         );
     }
 }
+
+function readResponsesImageBackendMissingEnv(env: Record<string, string | undefined>): string[] {
+    const missing: string[] = [];
+    if (!readBooleanEnv(env, 'ENABLE_RESPONSES_IMAGE_BACKEND')) {
+        missing.push('ENABLE_RESPONSES_IMAGE_BACKEND');
+    }
+    return missing;
+}

src/app/globals.css

@@ -44,75 +44,74 @@
 }
 
 :root {
-    --font-geist-sans:
-        Arial, Helvetica, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+    --font-geist-sans: Arial, Helvetica, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
     --font-geist-mono: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
-    --radius: 0.625rem;
-    --background: oklch(1 0 0);
-    --foreground: oklch(0.145 0 0);
-    --card: oklch(1 0 0);
-    --card-foreground: oklch(0.145 0 0);
-    --popover: oklch(1 0 0);
-    --popover-foreground: oklch(0.145 0 0);
-    --primary: oklch(0.205 0 0);
-    --primary-foreground: oklch(0.985 0 0);
-    --secondary: oklch(0.97 0 0);
-    --secondary-foreground: oklch(0.205 0 0);
-    --muted: oklch(0.97 0 0);
-    --muted-foreground: oklch(0.556 0 0);
-    --accent: oklch(0.97 0 0);
-    --accent-foreground: oklch(0.205 0 0);
-    --destructive: oklch(0.577 0.245 27.325);
-    --border: oklch(0.922 0 0);
-    --input: oklch(0.922 0 0);
-    --ring: oklch(0.708 0 0);
+    --radius: 0.5rem;
+    --background: oklch(0.956 0.023 80);
+    --foreground: oklch(0.225 0.026 56);
+    --card: oklch(0.992 0.01 84);
+    --card-foreground: oklch(0.225 0.026 56);
+    --popover: oklch(0.996 0.009 84);
+    --popover-foreground: oklch(0.225 0.026 56);
+    --primary: oklch(0.615 0.165 30);
+    --primary-foreground: oklch(0.99 0.016 84);
+    --secondary: oklch(0.892 0.044 122);
+    --secondary-foreground: oklch(0.255 0.034 66);
+    --muted: oklch(0.922 0.027 78);
+    --muted-foreground: oklch(0.505 0.031 58);
+    --accent: oklch(0.925 0.052 35);
+    --accent-foreground: oklch(0.285 0.037 52);
+    --destructive: oklch(0.56 0.17 25);
+    --border: oklch(0.858 0.03 74);
+    --input: oklch(0.858 0.03 74);
+    --ring: oklch(0.62 0.14 30);
     --chart-1: oklch(0.646 0.222 41.116);
     --chart-2: oklch(0.6 0.118 184.704);
     --chart-3: oklch(0.398 0.07 227.392);
     --chart-4: oklch(0.828 0.189 84.429);
     --chart-5: oklch(0.769 0.188 70.08);
-    --sidebar: oklch(0.985 0 0);
-    --sidebar-foreground: oklch(0.145 0 0);
-    --sidebar-primary: oklch(0.205 0 0);
-    --sidebar-primary-foreground: oklch(0.985 0 0);
-    --sidebar-accent: oklch(0.97 0 0);
-    --sidebar-accent-foreground: oklch(0.205 0 0);
-    --sidebar-border: oklch(0.922 0 0);
-    --sidebar-ring: oklch(0.708 0 0);
+    --sidebar: oklch(0.972 0.018 83);
+    --sidebar-foreground: oklch(0.205 0.024 58);
+    --sidebar-primary: oklch(0.48 0.125 38);
+    --sidebar-primary-foreground: oklch(0.985 0.018 86);
+    --sidebar-accent: oklch(0.884 0.071 64);
+    --sidebar-accent-foreground: oklch(0.26 0.035 55);
+    --sidebar-border: oklch(0.812 0.037 76);
+    --sidebar-ring: oklch(0.58 0.115 40);
 }
 
 .dark {
-    --background: oklch(0.145 0 0);
-    --foreground: oklch(0.985 0 0);
-    --card: oklch(0.205 0 0);
-    --card-foreground: oklch(0.985 0 0);
-    --popover: oklch(0.205 0 0);
-    --popover-foreground: oklch(0.985 0 0);
-    --primary: oklch(0.922 0 0);
-    --primary-foreground: oklch(0.205 0 0);
-    --secondary: oklch(0.269 0 0);
-    --secondary-foreground: oklch(0.985 0 0);
-    --muted: oklch(0.269 0 0);
-    --muted-foreground: oklch(0.708 0 0);
-    --accent: oklch(0.269 0 0);
-    --accent-foreground: oklch(0.985 0 0);
+    --background: oklch(0.19 0.025 57);
+    --foreground: oklch(0.93 0.026 84);
+    --card: oklch(0.245 0.028 58);
+    --card-foreground: oklch(0.93 0.026 84);
+    --popover: oklch(0.245 0.028 58);
+    --popover-foreground: oklch(0.93 0.026 84);
+    --primary: oklch(0.742 0.109 50);
+    --primary-foreground: oklch(0.18 0.023 55);
+    --secondary: oklch(0.315 0.035 96);
+    --secondary-foreground: oklch(0.915 0.025 82);
+    --muted: oklch(0.295 0.028 62);
+    --muted-foreground: oklch(0.735 0.028 78);
+    --accent: oklch(0.39 0.054 69);
+    --accent-foreground: oklch(0.93 0.026 84);
     --destructive: oklch(0.704 0.191 22.216);
-    --border: oklch(1 0 0 / 10%);
-    --input: oklch(1 0 0 / 15%);
-    --ring: oklch(0.556 0 0);
+    --border: oklch(0.45 0.035 68 / 52%);
+    --input: oklch(0.55 0.04 72 / 55%);
+    --ring: oklch(0.742 0.109 50);
     --chart-1: oklch(0.488 0.243 264.376);
     --chart-2: oklch(0.696 0.17 162.48);
     --chart-3: oklch(0.769 0.188 70.08);
     --chart-4: oklch(0.627 0.265 303.9);
     --chart-5: oklch(0.645 0.246 16.439);
-    --sidebar: oklch(0.205 0 0);
-    --sidebar-foreground: oklch(0.985 0 0);
-    --sidebar-primary: oklch(0.488 0.243 264.376);
-    --sidebar-primary-foreground: oklch(0.985 0 0);
-    --sidebar-accent: oklch(0.269 0 0);
-    --sidebar-accent-foreground: oklch(0.985 0 0);
-    --sidebar-border: oklch(1 0 0 / 10%);
-    --sidebar-ring: oklch(0.556 0 0);
+    --sidebar: oklch(0.245 0.028 58);
+    --sidebar-foreground: oklch(0.93 0.026 84);
+    --sidebar-primary: oklch(0.742 0.109 50);
+    --sidebar-primary-foreground: oklch(0.18 0.023 55);
+    --sidebar-accent: oklch(0.39 0.054 69);
+    --sidebar-accent-foreground: oklch(0.93 0.026 84);
+    --sidebar-border: oklch(0.45 0.035 68 / 52%);
+    --sidebar-ring: oklch(0.742 0.109 50);
 }
 
 @layer base {
@@ -123,3 +122,115 @@
         @apply bg-background text-foreground;
     }
 }
+
+@layer utilities {
+    .studio-paper {
+        background:
+            linear-gradient(105deg, oklch(0.988 0.013 86 / 0.96), oklch(0.95 0.024 78 / 0.86)),
+            linear-gradient(180deg, oklch(1 0 0 / 0.42), transparent 34rem),
+            repeating-linear-gradient(
+                90deg,
+                color-mix(in oklch, var(--border) 14%, transparent) 0 1px,
+                transparent 1px 14px
+            ),
+            repeating-linear-gradient(0deg, oklch(1 0 0 / 0.16) 0 1px, transparent 1px 3px), var(--background);
+    }
+
+    .paper-soft-shadow {
+        box-shadow: 0 12px 28px oklch(0.37 0.038 54 / 0.09);
+    }
+
+    .literary-scrollbar {
+        scrollbar-color: oklch(0.74 0.028 72 / 0.72) transparent;
+        scrollbar-width: thin;
+    }
+
+    .literary-scrollbar::-webkit-scrollbar {
+        width: 8px;
+        height: 8px;
+    }
+
+    .literary-scrollbar::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    .literary-scrollbar::-webkit-scrollbar-thumb {
+        border: 2px solid transparent;
+        border-radius: 999px;
+        background-clip: content-box;
+        background-color: oklch(0.74 0.028 72 / 0.62);
+    }
+
+    .scrollbar-none {
+        scrollbar-width: none;
+    }
+
+    .scrollbar-none::-webkit-scrollbar {
+        display: none;
+    }
+
+    .editorial-title {
+        font-family: 'Songti SC', 'STSong', 'Noto Serif CJK SC', serif;
+        letter-spacing: 0;
+    }
+
+    .workbench-panel {
+        background:
+            linear-gradient(180deg, oklch(0.998 0.007 86 / 0.98), oklch(0.976 0.017 82 / 0.92)),
+            repeating-linear-gradient(90deg, oklch(0.72 0.025 76 / 0.045) 0 1px, transparent 1px 9px), var(--card);
+        box-shadow:
+            0 1px 0 oklch(1 0 0 / 0.72) inset,
+            0 14px 35px oklch(0.37 0.036 54 / 0.1);
+    }
+
+    .photo-paper {
+        background: oklch(0.99 0.008 85);
+        box-shadow:
+            0 2px 0 oklch(0.82 0.026 74 / 0.48),
+            0 18px 38px oklch(0.35 0.036 54 / 0.16);
+    }
+
+    .photo-paper::before {
+        content: '';
+        position: absolute;
+        top: -1.25rem;
+        right: 7%;
+        z-index: 2;
+        width: 8rem;
+        height: 2.1rem;
+        rotate: 8deg;
+        border: 1px solid oklch(0.79 0.028 74 / 0.38);
+        background:
+            linear-gradient(90deg, oklch(0.9 0.025 75 / 0.82), oklch(0.78 0.024 75 / 0.64)),
+            repeating-linear-gradient(90deg, oklch(1 0 0 / 0.18) 0 2px, transparent 2px 7px);
+        box-shadow: 0 4px 10px oklch(0.35 0.036 54 / 0.08);
+    }
+
+    .preview-gallery-board {
+        background:
+            linear-gradient(
+                90deg,
+                transparent calc(50% - 0.5px),
+                oklch(0.78 0.022 76 / 0.14) 50%,
+                transparent calc(50% + 0.5px)
+            ),
+            linear-gradient(
+                0deg,
+                transparent calc(50% - 0.5px),
+                oklch(0.78 0.022 76 / 0.1) 50%,
+                transparent calc(50% + 0.5px)
+            ),
+            repeating-linear-gradient(90deg, oklch(0.78 0.022 76 / 0.055) 0 1px, transparent 1px 42px),
+            repeating-linear-gradient(0deg, oklch(0.78 0.022 76 / 0.045) 0 1px, transparent 1px 42px),
+            linear-gradient(180deg, oklch(0.995 0.007 85), oklch(0.972 0.016 80));
+    }
+
+    .preview-gallery-board::before {
+        content: '';
+        position: absolute;
+        inset: 1rem;
+        pointer-events: none;
+        border: 1px solid oklch(0.79 0.026 74 / 0.16);
+        border-radius: 6px;
+    }
+}

src/app/layout.tsx

@@ -4,8 +4,8 @@ import { I18nProvider } from '@/lib/i18n';
 import type { Metadata } from 'next';
 
 export const metadata: Metadata = {
-    title: 'GPT Image Playground',
-    description: '使用 OpenAI GPT Image 模型生成和编辑图片。',
+    title: '图像手记',
+    description: '面向中文创作者的 AI 图像创作工作台。',
     icons: {
         icon: '/favicon.svg'
     }

src/app/page-regressions.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { describe, it } from 'node:test';
+
+describe('page state regressions', () => {
+    it('uses the unified batch prompt setter when mobile random inspiration replaces batch text', async () => {
+        const source = await readFile(new URL('./page.tsx', import.meta.url), 'utf8');
+        const batchBranch = source.match(/if \(workbenchMode === 'batch'\) \{([\s\S]*?)\n\s*\}/)?.[1];
+
+        assert.ok(batchBranch, 'missing mobile random inspiration batch branch');
+        assert.match(batchBranch, /handleBatchPromptTextChange\(nextPrompt\)/);
+        assert.doesNotMatch(batchBranch, /setGenBatchPromptText\(nextPrompt\)/);
+    });
+});

src/components/api-settings-dialog.tsx

@@ -71,6 +71,11 @@ export function ApiSettingsDialog({ isOpen, onOpenChange, settings, onSave }: Ap
         }
     };
 
+    const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+        event.preventDefault();
+        handleSave();
+    };
+
     const handleClear = () => {
         const emptySettings = { apiKey: '', baseUrl: '' };
         try {
@@ -87,54 +92,72 @@ export function ApiSettingsDialog({ isOpen, onOpenChange, settings, onSave }: Ap
     return (
         <Dialog open={isOpen} onOpenChange={handleOpenChange}>
             <DialogContent className='sm:max-w-[520px]'>
-                <DialogHeader>
-                    <DialogTitle>{t('api.title')}</DialogTitle>
-                    <DialogDescription>{t('api.description')}</DialogDescription>
-                </DialogHeader>
-                <div className='grid gap-4 py-2'>
-                    <div className='grid gap-2'>
-                        <Label htmlFor='api-key-input'>{t('api.key')}</Label>
-                        <Input
-                            id='api-key-input'
-                            name='apiKey'
-                            type='password'
-                            autoComplete='off'
-                            spellCheck={false}
-                            placeholder='sk-...'
-                            value={draft.apiKey}
-                            onChange={(event) => setDraft((current) => ({ ...current, apiKey: event.target.value }))}
-                        />
-                    </div>
-                    <div className='grid gap-2'>
-                        <Label htmlFor='api-base-url-input'>{t('api.url')}</Label>
-                        <Input
-                            id='api-base-url-input'
-                            name='baseUrl'
-                            type='url'
-                            inputMode='url'
-                            autoComplete='off'
-                            spellCheck={false}
-                            placeholder='https://api.openai.com/v1'
-                            value={draft.baseUrl}
-                            onChange={(event) => setDraft((current) => ({ ...current, baseUrl: event.target.value }))}
-                        />
-                        <p className='text-muted-foreground text-xs leading-5'>{t('api.urlHint')}</p>
+                <form onSubmit={handleSubmit} className='grid gap-4'>
+                    <DialogHeader>
+                        <DialogTitle>{t('api.title')}</DialogTitle>
+                        <DialogDescription>{t('api.description')}</DialogDescription>
+                    </DialogHeader>
+                    <div className='grid gap-4 py-2'>
+                        <div className='grid gap-2'>
+                            <Label htmlFor='api-key-input'>{t('api.key')}</Label>
+                            <Input
+                                id='api-key-input'
+                                name='apiKey'
+                                type='password'
+                                autoComplete='off'
+                                spellCheck={false}
+                                placeholder='sk-...'
+                                value={draft.apiKey}
+                                className='min-h-11 sm:min-h-9'
+                                onChange={(event) =>
+                                    setDraft((current) => ({ ...current, apiKey: event.target.value }))
+                                }
+                            />
+                        </div>
+                        <div className='grid gap-2'>
+                            <Label htmlFor='api-base-url-input'>{t('api.url')}</Label>
+                            <Input
+                                id='api-base-url-input'
+                                name='baseUrl'
+                                type='url'
+                                inputMode='url'
+                                autoComplete='off'
+                                spellCheck={false}
+                                placeholder='https://api.openai.com/v1'
+                                value={draft.baseUrl}
+                                className='min-h-11 sm:min-h-9'
+                                onChange={(event) =>
+                                    setDraft((current) => ({ ...current, baseUrl: event.target.value }))
+                                }
+                            />
+                            <p className='text-muted-foreground text-xs leading-5'>{t('api.urlHint')}</p>
+                        </div>
                     </div>
-                </div>
-                <DialogFooter>
-                    {saveStatus === 'saved' && (
-                        <p className='mr-auto self-center text-sm text-emerald-600 dark:text-emerald-400' aria-live='polite'>{t('api.saved')}</p>
-                    )}
-                    {saveStatus === 'error' && (
-                        <p className='text-destructive mr-auto self-center text-sm' aria-live='polite'>{t('api.saveFailed')}</p>
-                    )}
-                    <Button type='button' variant='ghost' onClick={handleClear} className='text-muted-foreground hover:text-foreground'>
-                        {t('common.clear')}
-                    </Button>
-                    <Button type='button' onClick={handleSave} className='px-6'>
-                        {t('common.save')}
-                    </Button>
-                </DialogFooter>
+                    <DialogFooter>
+                        {saveStatus === 'saved' && (
+                            <p
+                                className='mr-auto self-center text-sm text-emerald-600 dark:text-emerald-400'
+                                aria-live='polite'>
+                                {t('api.saved')}
+                            </p>
+                        )}
+                        {saveStatus === 'error' && (
+                            <p className='text-destructive mr-auto self-center text-sm' aria-live='polite'>
+                                {t('api.saveFailed')}
+                            </p>
+                        )}
+                        <Button
+                            type='button'
+                            variant='ghost'
+                            onClick={handleClear}
+                            className='text-muted-foreground hover:text-foreground min-h-11 sm:min-h-9'>
+                            {t('common.clear')}
+                        </Button>
+                        <Button type='submit' className='min-h-11 px-6 sm:min-h-9'>
+                            {t('common.save')}
+                        </Button>
+                    </DialogFooter>
+                </form>
             </DialogContent>
         </Dialog>
     );

src/components/app-controls.tsx

@@ -1,63 +0,0 @@
-'use client';
-
-import { Button } from '@/components/ui/button';
-import { useI18n } from '@/lib/i18n';
-import { cn } from '@/lib/utils';
-import { Languages, Moon, Settings2, Sun } from 'lucide-react';
-import { useTheme } from 'next-themes';
-import * as React from 'react';
-
-type AppControlsProps = {
-    onOpenApiSettings: () => void;
-};
-
-export function AppControls({ onOpenApiSettings }: AppControlsProps) {
-    const { locale, setLocale, t } = useI18n();
-    const { resolvedTheme, setTheme } = useTheme();
-    const [isMounted, setIsMounted] = React.useState(false);
-    const effectiveTheme = isMounted ? resolvedTheme : 'light';
-    const isDark = effectiveTheme === 'dark';
-
-    React.useEffect(() => {
-        queueMicrotask(() => setIsMounted(true));
-    }, []);
-
-    return (
-        <div className='flex flex-wrap items-center justify-end gap-2'>
-            <div
-                className='border-border bg-card text-card-foreground inline-flex items-center gap-1 rounded-md border p-1'
-                aria-label={t('app.language')}>
-                <Languages className='text-muted-foreground ml-1 h-4 w-4' />
-                <Button
-                    type='button'
-                    variant={locale === 'zh-CN' ? 'default' : 'ghost'}
-                    size='sm'
-                    onClick={() => setLocale('zh-CN')}
-                    className='h-7 px-2'>
-                    中文
-                </Button>
-                <Button
-                    type='button'
-                    variant={locale === 'en-US' ? 'default' : 'ghost'}
-                    size='sm'
-                    onClick={() => setLocale('en-US')}
-                    className='h-7 px-2'>
-                    EN
-                </Button>
-            </div>
-            <Button
-                type='button'
-                variant='outline'
-                size='sm'
-                onClick={() => setTheme(isDark ? 'light' : 'dark')}
-                className={cn('h-9 gap-2', isDark ? 'border-border' : 'border-input')}>
-                {isDark ? <Moon className='h-4 w-4' /> : <Sun className='h-4 w-4' />}
-                {isDark ? t('app.themeDark') : t('app.themeLight')}
-            </Button>
-            <Button type='button' variant='outline' onClick={onOpenApiSettings} className='gap-2'>
-                <Settings2 className='h-4 w-4' />
-                {t('app.apiSettings')}
-            </Button>
-        </div>
-    );
-}

src/components/editing-form.test.tsx

@@ -0,0 +1,333 @@
+import { EditingForm, type EditingFormData } from './editing-form';
+import { I18nProvider } from '@/lib/i18n';
+import type { ImageStreamingStrategy } from '@/lib/image-upstream-strategy';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+type RenderOptions = {
+    backend: EditingFormData['image_backend'];
+    outputFormat?: EditingFormData['output_format'];
+    advancedOpen?: boolean;
+    advancedTab?: 'output' | 'model' | 'stream' | 'route';
+    reuseContext?: React.ComponentProps<typeof EditingForm>['reuseContext'];
+    allowStreamingBatch?: boolean;
+    enableParallelBatch?: boolean;
+    editN?: number[];
+    streamingStrategy?: EditingFormData['streaming_strategy'];
+    defaultStreamingStrategy?: ImageStreamingStrategy;
+    allowResponsesImageBackend?: boolean;
+    hasDefaultResponsesModel?: boolean;
+    editResponsesModel?: string;
+    editPrompt?: string;
+    imageFiles?: File[];
+};
+
+const noop = () => {};
+
+function renderEditingForm({
+    backend,
+    outputFormat = 'png',
+    advancedOpen = true,
+    advancedTab = 'route',
+    reuseContext = null,
+    allowStreamingBatch = false,
+    enableParallelBatch = false,
+    editN = [1],
+    streamingStrategy = 'server-default',
+    defaultStreamingStrategy = 'auto',
+    allowResponsesImageBackend = true,
+    hasDefaultResponsesModel = true,
+    editResponsesModel = '',
+    editPrompt = '',
+    imageFiles = []
+}: RenderOptions): string {
+    return renderToStaticMarkup(
+        <I18nProvider>
+            <EditingForm
+                onSubmit={noop}
+                isLoading={false}
+                currentMode='edit'
+                onModeChange={noop}
+                reuseContext={reuseContext}
+                onClearReuseContext={noop}
+                isPasswordRequiredByBackend={false}
+                clientPasswordHash={null}
+                onOpenPasswordDialog={noop}
+                editModel='gpt-image-2'
+                setEditModel={noop}
+                imageFiles={imageFiles}
+                sourceImagePreviewUrls={[]}
+                setImageFiles={noop}
+                setSourceImagePreviewUrls={noop}
+                maxImages={10}
+                editPrompt={editPrompt}
+                setEditPrompt={noop}
+                editN={editN}
+                setEditN={noop}
+                editSize='auto'
+                setEditSize={noop}
+                editCustomWidth={1024}
+                setEditCustomWidth={noop}
+                editCustomHeight={1024}
+                setEditCustomHeight={noop}
+                editQuality='auto'
+                setEditQuality={noop}
+                editOutputFormat={outputFormat}
+                setEditOutputFormat={noop}
+                editCompression={[85]}
+                setEditCompression={noop}
+                editModeration='auto'
+                setEditModeration={noop}
+                editBrushSize={[20]}
+                setEditBrushSize={noop}
+                editShowMaskEditor={false}
+                setEditShowMaskEditor={noop}
+                editGeneratedMaskFile={null}
+                setEditGeneratedMaskFile={noop}
+                editIsMaskSaved={false}
+                setEditIsMaskSaved={noop}
+                editOriginalImageSize={null}
+                setEditOriginalImageSize={noop}
+                editDrawnPoints={[]}
+                setEditDrawnPoints={noop}
+                editMaskPreviewUrl={null}
+                setEditMaskPreviewUrl={noop}
+                streamMode='auto'
+                setStreamMode={noop}
+                allowStreamingBatch={allowStreamingBatch}
+                enableParallelBatch={enableParallelBatch}
+                setEnableParallelBatch={noop}
+                partialImages={1}
+                setPartialImages={noop}
+                allowResponsesImageBackend={allowResponsesImageBackend}
+                hasDefaultResponsesModel={hasDefaultResponsesModel}
+                editImageBackend={backend}
+                setEditImageBackend={noop}
+                editStreamingStrategy={streamingStrategy}
+                defaultStreamingStrategy={defaultStreamingStrategy}
+                setEditStreamingStrategy={noop}
+                editResponsesModel={editResponsesModel}
+                setEditResponsesModel={noop}
+                editThinking='server-default'
+                setEditThinking={noop}
+                editPromptOptimization='server-default'
+                setEditPromptOptimization={noop}
+                editForceWeb={false}
+                setEditForceWeb={noop}
+                estimatedCostLabel='预计 0.12 积分'
+                initialAdvancedOpen={advancedOpen}
+                initialAdvancedTab={advancedTab}
+            />
+        </I18nProvider>
+    );
+}
+
+describe('EditingForm advanced upstream controls', () => {
+    it('keeps the full professional accordion available on desktop and mobile', () => {
+        const html = renderEditingForm({ backend: 'server-default', advancedTab: 'route' });
+
+        assert.match(
+            html,
+            /<div class="border-border bg-muted\/20 rounded-md border"><button[^>]*aria-controls="editing-advanced-panel"/
+        );
+        assert.doesNotMatch(
+            html,
+            /<div class="[^"]*lg:hidden[^"]*"><button[^>]*aria-controls="editing-advanced-panel"/
+        );
+    });
+
+    it('keeps model and streaming controls out of the default edit form surface', () => {
+        const html = renderEditingForm({ backend: 'server-default', advancedOpen: false });
+
+        assert.match(html, /参考图/);
+        assert.match(html, /修改想法/);
+        assert.match(html, /专业模式/);
+        assert.doesNotMatch(html, /edit-model-select/);
+        assert.doesNotMatch(html, /edit-stream-mode-select/);
+    });
+
+    it('translates the default backend into a user-facing route label near submit', () => {
+        const html = renderEditingForm({ backend: 'server-default', advancedOpen: false });
+
+        assert.match(html, /默认线路/);
+        assert.match(html, /预计 0\.12 积分/);
+    });
+
+    it('renders edit model controls only in the professional model tab', () => {
+        const html = renderEditingForm({ backend: 'server-default', advancedTab: 'model' });
+
+        assert.match(html, /edit-model-select/);
+        assert.match(html, /gpt-image-2 始终以高保真方式处理参考图/);
+        assert.doesNotMatch(html, /edit-image-backend-select/);
+    });
+
+    it('renders edit stream controls only in the professional stream tab', () => {
+        const html = renderEditingForm({ backend: 'server-default', advancedTab: 'stream' });
+
+        assert.match(html, /edit-stream-mode-select/);
+        assert.match(html, /edit-partial-1/);
+        assert.doesNotMatch(html, /edit-model-select/);
+    });
+
+    it('renders an explicit parallel batch toggle in edit stream settings', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true,
+            editN: [2]
+        });
+
+        assert.match(html, /并发批量/);
+        assert.match(html, /多张图或多条提示词会按当前渠道容量并发执行/);
+        assert.match(html, /id="edit-parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="true"/);
+    });
+
+    it('keeps edit parallel batch disabled for a single output image', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true
+        });
+
+        assert.match(html, /选择至少 2 张图片或 2 条提示词后可启用并发/);
+        assert.match(html, /id="edit-parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('keeps edit parallel batch disabled when streaming strategy is off', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true,
+            editN: [2],
+            streamingStrategy: 'off'
+        });
+
+        assert.match(html, /并发批量需要流式模式；非流式会保持顺序执行。/);
+        assert.match(html, /id="edit-parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('keeps edit parallel batch disabled when the server default streaming strategy is off', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true,
+            editN: [2],
+            defaultStreamingStrategy: 'off'
+        });
+
+        assert.match(html, /并发批量需要流式模式；非流式会保持顺序执行。/);
+        assert.match(html, /id="edit-parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('disables the edit stream mode selector when the server default streaming strategy is off', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'stream',
+            defaultStreamingStrategy: 'off'
+        });
+
+        assert.match(html, /<button[^>]*(?:disabled=""[^>]*id="edit-stream-mode-select"|id="edit-stream-mode-select"[^>]*disabled="")/);
+    });
+
+    it('renders Responses-specific edit controls when the Responses backend is selected', () => {
+        const html = renderEditingForm({ backend: 'responses-image-generation' });
+
+        assert.match(html, /图片生成后端/);
+        assert.match(html, /影响说明/);
+        assert.match(html, /Responses image_generation 需要实验开关和顶层模型/);
+        assert.match(html, /自动或服务端默认会优先使用当前推荐的流式策略/);
+        assert.match(html, /GPT 顶层模型/);
+        assert.match(html, /思考强度/);
+        assert.match(html, /提示词优化/);
+        assert.doesNotMatch(html, /优先 Web 账号/);
+    });
+
+    it('explains the resolved edit server default streaming strategy', () => {
+        const offHtml = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'route',
+            streamingStrategy: 'server-default',
+            defaultStreamingStrategy: 'off'
+        });
+        const forceHtml = renderEditingForm({
+            backend: 'server-default',
+            advancedTab: 'route',
+            streamingStrategy: 'server-default',
+            defaultStreamingStrategy: 'force-sse'
+        });
+
+        assert.match(offHtml, /关闭流式会减少长连接不稳定因素/);
+        assert.doesNotMatch(offHtml, /自动或服务端默认会优先使用当前推荐的流式策略/);
+        assert.match(forceHtml, /强制 SSE 会跳过自动判断/);
+        assert.doesNotMatch(forceHtml, /自动或服务端默认会优先使用当前推荐的流式策略/);
+    });
+
+    it('disables the experimental Responses backend when runtime capabilities do not allow it', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            allowResponsesImageBackend: false
+        });
+
+        assert.match(html, /当前运行时未启用 Responses image_generation/);
+        assert.doesNotMatch(html, /GPT 顶层模型/);
+    });
+
+    it('blocks Responses edits until a top-level model is available', () => {
+        const html = renderEditingForm({
+            backend: 'responses-image-generation',
+            hasDefaultResponsesModel: false,
+            editResponsesModel: '',
+            editPrompt: '用户真实编辑要求',
+            imageFiles: [new File(['x'], 'source.png', { type: 'image/png' })]
+        });
+
+        assert.match(html, /Responses image_generation 需要填写 GPT 顶层模型/);
+        assert.match(html, /<button[^>]*disabled=""[^>]*>[\s\S]*编辑图像[\s\S]*<\/button>/);
+    });
+
+    it('renders Images API edit controls and compression when JPEG output is selected', () => {
+        const html = renderEditingForm({ backend: 'images-api', outputFormat: 'jpeg', advancedTab: 'output' });
+
+        assert.match(html, /Images API/);
+        assert.match(html, /输出格式/);
+        assert.match(html, /压缩：85%/);
+        assert.match(html, /内容审核级别/);
+        assert.doesNotMatch(html, /GPT 顶层模型/);
+    });
+});
+
+describe('EditingForm reused history context', () => {
+    it('shows which history values were carried into edit mode', () => {
+        const html = renderEditingForm({
+            backend: 'server-default',
+            reuseContext: {
+                sourceLabel: '最近生成：2026/6/2 12:00:00',
+                restoredFields: ['参考图', '提示词', '模型', '尺寸', '数量'],
+                promptPreview: '用户真实编辑提示词'
+            }
+        });
+
+        assert.match(html, /已带入内容/);
+        assert.match(html, /最近生成：2026\/6\/2 12:00:00/);
+        assert.match(html, /参考图/);
+        assert.match(html, /提示词/);
+        assert.match(html, /模型/);
+        assert.match(html, /尺寸/);
+        assert.match(html, /数量/);
+        assert.match(html, /用户真实编辑提示词/);
+        assert.match(html, /这些内容已经写入编辑单，可以修改后再生成。/);
+    });
+});

src/components/generation-activity-timeline.tsx

@@ -0,0 +1,265 @@
+'use client';
+
+import type { GenerationActivityItem } from '@/lib/generation-activity';
+import type { HistoryMetadata } from '@/lib/history-metadata';
+import { cn } from '@/lib/utils';
+import Image from 'next/image';
+
+type ActivityTimelineProps = {
+    activityItems: GenerationActivityItem[];
+    history: HistoryMetadata[];
+    pendingActivityItems: GenerationActivityItem[];
+    onSelectImage: (item: HistoryMetadata) => void;
+    onClearHistory: () => void;
+    getImageSrc: (filename: string) => string | undefined;
+    formatStatusTime: (timestamp: number) => string;
+    formatDuration: (ms: number) => string;
+    t: (key: string, values?: Record<string, string | number>) => string;
+};
+
+function getActivityToneClass(tone: GenerationActivityItem['tone']): string {
+    if (tone === 'progress') return 'bg-[oklch(0.58_0.1_220)]';
+    if (tone === 'success') return 'bg-[oklch(0.58_0.1_145)]';
+    if (tone === 'warning') return 'bg-[oklch(0.62_0.13_38)]';
+    return 'bg-[oklch(0.72_0.05_86)]';
+}
+
+function getActivityToneLabel(tone: GenerationActivityItem['tone'], t: ActivityTimelineProps['t']): string {
+    if (tone === 'progress') return t('history.activityToneProgress');
+    if (tone === 'success') return t('history.activityToneSuccess');
+    if (tone === 'warning') return t('history.activityToneWarning');
+    return t('history.activityToneNeutral');
+}
+
+function getPendingStageLabel(id: string, t: ActivityTimelineProps['t']): string {
+    if (id === 'pending-request') return t('history.pendingRequestStage');
+    if (id === 'pending-streaming') return t('history.pendingStreamingStage');
+    if (id === 'pending-saved') return t('history.pendingSavedStage');
+    if (id === 'pending-failed') return t('history.pendingFailedStage');
+    return t('history.activityToneNeutral');
+}
+
+function GenerationActivityRows({
+    items,
+    t,
+    compact = false
+}: {
+    items: GenerationActivityItem[];
+    t: ActivityTimelineProps['t'];
+    compact?: boolean;
+}) {
+    return (
+        <>
+            {items.map((item, index) => (
+                <div
+                    key={item.id}
+                    className={cn(
+                        'grid grid-cols-[auto_auto_1fr] items-start gap-2 rounded-md px-2 text-left transition-[background-color]',
+                        index === 0 ? 'bg-[oklch(0.96_0.035_82)]' : 'bg-background/58',
+                        compact ? 'py-1.5' : 'py-2',
+                        item.tone === 'warning' && 'bg-destructive/5'
+                    )}>
+                    <span className='text-muted-foreground mt-0.5 w-10 shrink-0 text-right text-[10px] leading-4 tabular-nums'>
+                        {getActivityToneLabel(item.tone, t)}
+                    </span>
+                    <span className={cn('flex h-full w-3 justify-center', compact ? 'pt-1' : 'pt-1.5')}>
+                        <span className={cn('h-2 w-2 rounded-full', getActivityToneClass(item.tone))} />
+                    </span>
+                    <span className='min-w-0'>
+                        <span className='text-foreground block truncate text-xs font-medium'>{item.label}</span>
+                        <span
+                            className={cn(
+                                'text-muted-foreground block truncate text-[11px]',
+                                compact ? 'mt-0 leading-4' : 'mt-0.5'
+                            )}>
+                            {item.detail}
+                        </span>
+                    </span>
+                </div>
+            ))}
+        </>
+    );
+}
+
+function PendingActivityLine({ items, t }: { items: GenerationActivityItem[]; t: ActivityTimelineProps['t'] }) {
+    return (
+        <div className='activity-feed grid gap-1.5' aria-label={t('history.pendingActivityFeed')}>
+            {items.map((item, index) => (
+                <div
+                    key={item.id}
+                    className={cn(
+                        'grid grid-cols-[auto_auto_1fr] items-start gap-2 rounded-md px-2 py-1.5 text-xs',
+                        index === 1 ? 'bg-[oklch(0.955_0.04_86)]' : 'bg-background/58'
+                    )}>
+                    <span className='text-muted-foreground mt-0.5 w-10 shrink-0 text-right text-[10px] leading-4 tabular-nums'>
+                        {getPendingStageLabel(item.id, t)}
+                    </span>
+                    <span className='flex h-full w-3 justify-center pt-1'>
+                        <span className={cn('h-1.5 w-1.5 rounded-full', getActivityToneClass(item.tone))} />
+                    </span>
+                    <span className='min-w-0'>
+                        <span className='text-foreground block truncate font-medium'>{item.label}</span>
+                        <span className='text-muted-foreground mt-0.5 block truncate text-[11px] leading-4'>
+                            {item.detail}
+                        </span>
+                    </span>
+                </div>
+            ))}
+        </div>
+    );
+}
+
+function ActivityHistoryRow({
+    item,
+    index,
+    hasLiveActivity,
+    onSelectImage,
+    getImageSrc,
+    formatStatusTime,
+    formatDuration,
+    t
+}: {
+    item: HistoryMetadata;
+    index: number;
+    hasLiveActivity: boolean;
+    onSelectImage: (item: HistoryMetadata) => void;
+    getImageSrc: (filename: string) => string | undefined;
+    formatStatusTime: (timestamp: number) => string;
+    formatDuration: (ms: number) => string;
+    t: (key: string, values?: Record<string, string | number>) => string;
+}) {
+    const isLatestQuietActivity = index === 0 && !hasLiveActivity;
+    const isFailedItem = item.status === 'failed';
+    const activityLabel = isFailedItem
+        ? t('history.failedStatus')
+        : item.mode === 'edit'
+          ? t('history.statusEditDone')
+          : t('history.statusCreateDone');
+    const activityDetail = isFailedItem
+        ? item.failureMessage?.trim() || t('history.failedReasonUnavailable')
+        : t('history.statusBatchSummary', {
+              count: item.images.length,
+              duration: formatDuration(item.durationMs)
+          });
+
+    return (
+        <button
+            type='button'
+            onClick={() => onSelectImage(item)}
+            disabled={isFailedItem}
+            className={cn(
+                'grid w-full grid-cols-[auto_auto_1fr_auto] items-start gap-2 rounded-md px-2 py-2 text-left transition-[background-color,color,transform] hover:-translate-y-0.5 active:translate-y-0',
+                isLatestQuietActivity
+                    ? 'text-foreground bg-[oklch(0.95_0.04_86)]'
+                    : 'text-muted-foreground hover:text-foreground hover:bg-[oklch(0.965_0.025_84)]',
+                isFailedItem && 'cursor-default hover:translate-y-0'
+            )}>
+            <span className='text-muted-foreground mt-0.5 w-10 shrink-0 text-right text-[10px] leading-4 tabular-nums'>
+                {formatStatusTime(item.timestamp)}
+            </span>
+            <span className='flex h-full w-3 justify-center pt-1.5'>
+                <span
+                    className={cn(
+                        'h-2 w-2 rounded-full',
+                        isFailedItem
+                            ? 'bg-destructive'
+                            : isLatestQuietActivity
+                              ? 'bg-[oklch(0.62_0.13_38)]'
+                              : 'bg-[oklch(0.66_0.08_145)]'
+                    )}
+                />
+            </span>
+            <span className='min-w-0'>
+                <span className='flex min-w-0 items-center gap-2'>
+                    <span className='text-foreground truncate text-xs font-medium'>{activityLabel}</span>
+                </span>
+                <span className='text-muted-foreground mt-0.5 block truncate text-[11px]'>{activityDetail}</span>
+            </span>
+            <span className='hidden shrink-0 gap-1 sm:flex'>
+                {item.images.slice(0, 3).map((image) => {
+                    const source =
+                        item.storageModeUsed === 'indexeddb'
+                            ? getImageSrc(image.filename)
+                            : `/api/image/${image.filename}`;
+                    return source ? (
+                        <span
+                            key={image.filename}
+                            className='border-background bg-muted relative h-7 w-7 overflow-hidden rounded-sm border shadow-sm'>
+                            <Image
+                                src={source}
+                                alt={image.filename}
+                                fill
+                                sizes='28px'
+                                className='object-cover'
+                                unoptimized
+                            />
+                        </span>
+                    ) : null;
+                })}
+            </span>
+        </button>
+    );
+}
+
+export function ActivityTimeline({
+    activityItems,
+    history,
+    pendingActivityItems,
+    onSelectImage,
+    onClearHistory,
+    getImageSrc,
+    formatStatusTime,
+    formatDuration,
+    t
+}: ActivityTimelineProps) {
+    const hasActivity = activityItems.length > 0 || history.length > 0;
+
+    return (
+        <div className='border-border/60 bg-background/48 shrink-0 border-t p-3 lg:mt-1 lg:min-h-[16.5rem] lg:border-t-0 lg:bg-transparent'>
+            <div className='space-y-2 rounded-md border border-[oklch(0.86_0.035_78)] bg-[oklch(0.982_0.014_84)] p-2.5 shadow-[0_6px_16px_oklch(0.42_0.035_58/0.08)]'>
+                <div className='flex items-center justify-between gap-2'>
+                    <div className='min-w-0'>
+                        <div className='flex items-center gap-2'>
+                            <span className='h-2 w-2 rounded-full bg-[oklch(0.62_0.13_38)]' />
+                            <p className='text-sm font-medium'>{t('history.generationStatus')}</p>
+                        </div>
+                        <p className='text-muted-foreground mt-0.5 truncate text-[11px]'>
+                            {t('history.generationStatusHint')}
+                        </p>
+                    </div>
+                    {history.length > 0 ? (
+                        <button
+                            type='button'
+                            className='text-muted-foreground hover:text-foreground shrink-0 text-xs'
+                            onClick={onClearHistory}>
+                            {t('history.clear')}
+                        </button>
+                    ) : null}
+                </div>
+                {hasActivity ? (
+                    <div className='max-h-56 space-y-2 overflow-y-auto pr-1 text-xs lg:max-h-[12.5rem]'>
+                        <GenerationActivityRows items={activityItems} t={t} compact />
+                        {history.slice(0, 4).map((item, index) => (
+                            <ActivityHistoryRow
+                                key={item.timestamp}
+                                item={item}
+                                index={index}
+                                hasLiveActivity={activityItems.length > 0}
+                                onSelectImage={onSelectImage}
+                                getImageSrc={getImageSrc}
+                                formatStatusTime={formatStatusTime}
+                                formatDuration={formatDuration}
+                                t={t}
+                            />
+                        ))}
+                    </div>
+                ) : (
+                    <div className='space-y-1.5'>
+                        <p className='text-muted-foreground px-1 text-[11px]'>{t('history.statusEmpty')}</p>
+                        <PendingActivityLine items={pendingActivityItems} t={t} />
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}

src/components/generation-form.test.tsx

@@ -0,0 +1,406 @@
+import { GenerationForm, resolveGenerationFooterPromptTarget } from './generation-form';
+import { I18nProvider } from '@/lib/i18n';
+import type { ImageStreamingStrategy } from '@/lib/image-upstream-strategy';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+const noop = () => {};
+
+function renderGenerationForm(
+    options: {
+        currentMode?: 'generate' | 'edit' | 'batch' | 'reuse';
+        defaultAdvancedTab?: 'output' | 'model' | 'stream' | 'route';
+        failedBatchPrompts?: string[];
+        canPauseBatch?: boolean;
+        isBatchPauseRequested?: boolean;
+        defaultAdvancedOpen?: boolean;
+        omitPauseHandler?: boolean;
+        allowStreamingBatch?: boolean;
+        enableParallelBatch?: boolean;
+        streamingStrategy?: React.ComponentProps<typeof GenerationForm>['streamingStrategy'];
+        defaultStreamingStrategy?: ImageStreamingStrategy;
+        prompt?: string;
+        batchPromptText?: string;
+        canApplyRandomInspiration?: boolean;
+        allowResponsesImageBackend?: boolean;
+        hasDefaultResponsesModel?: boolean;
+        responsesModel?: string;
+        imageBackend?: React.ComponentProps<typeof GenerationForm>['imageBackend'];
+    } = {}
+) {
+    return renderToStaticMarkup(
+        <I18nProvider>
+            <GenerationForm
+                onSubmit={noop}
+                onSaveInspiration={noop}
+                canApplyRandomInspiration={options.canApplyRandomInspiration ?? true}
+                onPickRandomInspiration={() => '用户保存的真实提示词'}
+                isLoading={false}
+                currentMode={options.currentMode ?? 'generate'}
+                onModeChange={noop}
+                reuseContext={null}
+                onClearReuseContext={noop}
+                isPasswordRequiredByBackend={false}
+                clientPasswordHash={null}
+                onOpenPasswordDialog={noop}
+                model='gpt-image-2'
+                setModel={noop}
+                prompt={options.prompt ?? '用户真实提示词 A'}
+                setPrompt={noop}
+                batchPromptText={options.batchPromptText ?? '用户真实提示词 A\n用户真实提示词 B'}
+                setBatchPromptText={noop}
+                failedBatchPrompts={options.failedBatchPrompts}
+                canPauseBatch={options.canPauseBatch}
+                isBatchPauseRequested={options.isBatchPauseRequested}
+                onPauseBatch={options.omitPauseHandler ? undefined : noop}
+                n={[1]}
+                setN={noop}
+                size='auto'
+                setSize={noop}
+                customWidth={1024}
+                setCustomWidth={noop}
+                customHeight={1024}
+                setCustomHeight={noop}
+                quality='high'
+                setQuality={noop}
+                outputFormat='png'
+                setOutputFormat={noop}
+                compression={[100]}
+                setCompression={noop}
+                background='auto'
+                setBackground={noop}
+                moderation='auto'
+                setModeration={noop}
+                streamMode='auto'
+                setStreamMode={noop}
+                allowStreamingBatch={options.allowStreamingBatch ?? false}
+                enableParallelBatch={options.enableParallelBatch ?? false}
+                setEnableParallelBatch={noop}
+                partialImages={1}
+                setPartialImages={noop}
+                allowResponsesImageBackend={options.allowResponsesImageBackend ?? true}
+                hasDefaultResponsesModel={options.hasDefaultResponsesModel ?? true}
+                imageBackend={options.imageBackend ?? 'server-default'}
+                setImageBackend={noop}
+                streamingStrategy={options.streamingStrategy ?? 'server-default'}
+                defaultStreamingStrategy={options.defaultStreamingStrategy ?? 'auto'}
+                setStreamingStrategy={noop}
+                responsesModel={options.responsesModel ?? ''}
+                setResponsesModel={noop}
+                thinking='server-default'
+                setThinking={noop}
+                promptOptimization='server-default'
+                setPromptOptimization={noop}
+                forceWeb={false}
+                setForceWeb={noop}
+                estimatedCostLabel='预计 0.12 积分'
+                defaultAdvancedOpen={options.defaultAdvancedOpen}
+                defaultAdvancedTab={options.defaultAdvancedTab}
+            />
+        </I18nProvider>
+    );
+}
+
+describe('GenerationForm advanced groups', () => {
+    it('shows task-specific descriptions in the mode segmented control', () => {
+        const html = renderGenerationForm();
+
+        for (const label of ['从灵感开始', '带图继续改', '一次多张', '套用旧稿']) {
+            assert.match(html, new RegExp(label));
+        }
+    });
+
+    it('keeps the full professional accordion available on desktop and mobile', () => {
+        const html = renderGenerationForm({ defaultAdvancedTab: 'route' });
+
+        assert.match(
+            html,
+            /<div class="border-border bg-muted\/20 rounded-md border"><button[^>]*aria-controls="generation-advanced-panel"/
+        );
+        assert.doesNotMatch(
+            html,
+            /<div class="[^"]*lg:hidden[^"]*"><button[^>]*aria-controls="generation-advanced-panel"/
+        );
+    });
+
+    it('labels the collapsed mobile advanced drawer as easy mode', () => {
+        const html = renderGenerationForm();
+
+        assert.match(html, /省心模式/);
+        assert.match(html, /常用参数已放在基础设置里/);
+    });
+
+    it('translates the default backend into a user-facing route label near submit', () => {
+        const html = renderGenerationForm();
+
+        assert.match(html, /默认线路/);
+        assert.match(html, /预计 0\.12 积分/);
+    });
+
+    it('labels the expanded mobile advanced drawer as professional mode', () => {
+        const html = renderGenerationForm({ defaultAdvancedOpen: true });
+
+        assert.match(html, /专业模式/);
+        assert.match(html, /清晰度: 高, 输出格式: PNG, 服务端默认/);
+    });
+
+    it('renders route controls in a separate professional tab', () => {
+        const html = renderGenerationForm({ defaultAdvancedOpen: true, defaultAdvancedTab: 'route' });
+
+        for (const label of ['输出', '模型', '流式', '路由']) {
+            assert.match(html, new RegExp(label));
+        }
+        assert.match(html, /image-backend-select/);
+        assert.match(html, /streaming-strategy-select/);
+        assert.doesNotMatch(html, /model-select/);
+    });
+
+    it('explains route choices that affect stability and cost', () => {
+        const html = renderGenerationForm({ defaultAdvancedOpen: true, defaultAdvancedTab: 'route' });
+
+        assert.match(html, /影响说明/);
+        assert.match(html, /服务端默认会沿用当前部署配置/);
+        assert.match(html, /自动或服务端默认会优先使用当前推荐的流式策略/);
+        assert.match(html, /费用主要由模型、尺寸、数量和预览图数量决定/);
+    });
+
+    it('explains the resolved server default streaming strategy', () => {
+        const offHtml = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'route',
+            streamingStrategy: 'server-default',
+            defaultStreamingStrategy: 'off'
+        });
+        const forceHtml = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'route',
+            streamingStrategy: 'server-default',
+            defaultStreamingStrategy: 'force-sse'
+        });
+
+        assert.match(offHtml, /关闭流式会减少长连接不稳定因素/);
+        assert.doesNotMatch(offHtml, /自动或服务端默认会优先使用当前推荐的流式策略/);
+        assert.match(forceHtml, /强制 SSE 会跳过自动判断/);
+        assert.doesNotMatch(forceHtml, /自动或服务端默认会优先使用当前推荐的流式策略/);
+    });
+
+    it('disables the experimental Responses backend when runtime capabilities do not allow it', () => {
+        const html = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'route',
+            allowResponsesImageBackend: false
+        });
+
+        assert.match(html, /当前运行时未启用 Responses image_generation/);
+        assert.doesNotMatch(html, /GPT 顶层模型/);
+    });
+
+    it('blocks Responses generation until a top-level model is available', () => {
+        const html = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'route',
+            imageBackend: 'responses-image-generation',
+            hasDefaultResponsesModel: false,
+            responsesModel: ''
+        });
+
+        assert.match(html, /Responses image_generation 需要填写 GPT 顶层模型/);
+        assert.match(html, /<button[^>]*disabled=""[^>]*>[\s\S]*生成图像[\s\S]*<\/button>/);
+    });
+
+    it('allows Responses generation when the runtime has a default top-level model', () => {
+        const html = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'route',
+            imageBackend: 'responses-image-generation',
+            hasDefaultResponsesModel: true,
+            responsesModel: ''
+        });
+
+        assert.match(html, /GPT 顶层模型/);
+        assert.doesNotMatch(html, /Responses image_generation 需要填写 GPT 顶层模型/);
+    });
+
+    it('keeps the model selector out of the route group', () => {
+        const html = renderGenerationForm({ defaultAdvancedOpen: true, defaultAdvancedTab: 'model' });
+
+        assert.match(html, /model-select/);
+        assert.doesNotMatch(html, /image-backend-select/);
+    });
+
+    it('disables random inspiration when no saved prompt is available', () => {
+        const html = renderGenerationForm({ canApplyRandomInspiration: false });
+
+        assert.match(html, /随便来点/);
+        assert.match(html, /<button[^>]*disabled=""[^>]*>[\s\S]*随便来点[\s\S]*<\/button>/);
+        assert.doesNotMatch(html, /夏日窗边的奶油色房间/);
+    });
+
+    it('does not render built-in prompt style chips before the user enters real content', () => {
+        const html = renderGenerationForm();
+
+        assert.doesNotMatch(html, /风格偏好/);
+        assert.doesNotMatch(html, /胶片感/);
+        assert.doesNotMatch(html, /奶油色/);
+        assert.doesNotMatch(html, /夏日窗边/);
+    });
+});
+
+describe('GenerationForm batch mode', () => {
+    it('uses the visible batch prompt text for footer prompt actions', () => {
+        assert.deepEqual(
+            resolveGenerationFooterPromptTarget({
+                currentMode: 'batch',
+                prompt: 'hidden single prompt',
+                batchPromptText: 'first batch prompt\nsecond batch prompt'
+            }),
+            {
+                value: 'first batch prompt\nsecond batch prompt',
+                isEmpty: false
+            }
+        );
+        assert.deepEqual(
+            resolveGenerationFooterPromptTarget({
+                currentMode: 'generate',
+                prompt: 'visible single prompt',
+                batchPromptText: 'hidden batch prompt'
+            }),
+            {
+                value: 'visible single prompt',
+                isEmpty: false
+            }
+        );
+    });
+
+    it('renders a real batch prompt list only in batch mode', () => {
+        const html = renderGenerationForm({ currentMode: 'batch' });
+
+        assert.match(html, /批量提示词列表/);
+        assert.match(html, /2 条任务/);
+        assert.match(html, /batch-prompt-list/);
+        assert.doesNotMatch(html, /id="prompt"/);
+    });
+
+    it('shows a low-interruption task summary for batch jobs', () => {
+        const html = renderGenerationForm({ currentMode: 'batch' });
+
+        assert.match(html, /batch-task-summary/);
+        assert.match(html, /任务摘要/);
+        assert.match(html, /每一行会生成一张图/);
+        assert.match(html, /失败后处理/);
+        assert.match(html, /生成动态/);
+        assert.match(html, /不占用中央单张预览/);
+    });
+
+    it('shows a reusable failed-task entry for partial batch failures', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            failedBatchPrompts: ['用户真实提示词 B']
+        });
+
+        assert.match(html, /上次批量有 1 条未完成/);
+        assert.match(html, /只保留失败项/);
+    });
+
+    it('keeps the batch prompt list out of the default generate mode', () => {
+        const html = renderGenerationForm({ failedBatchPrompts: ['用户真实提示词 B'] });
+
+        assert.doesNotMatch(html, /batch-prompt-list/);
+        assert.doesNotMatch(html, /batch-task-summary/);
+        assert.doesNotMatch(html, /只保留失败项/);
+    });
+
+    it('shows a real pause action while a batch is loading', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            canPauseBatch: true
+        });
+
+        assert.match(html, /暂停批量/);
+        assert.match(html, /已开始的任务会完成，未开始的任务会保留为失败项再重试。/);
+    });
+
+    it('keeps the pause action renderable when the handler is omitted', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            canPauseBatch: true,
+            omitPauseHandler: true
+        });
+
+        assert.match(html, /暂停批量/);
+    });
+
+    it('switches the pause action into requested state after pause is requested', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            canPauseBatch: true,
+            isBatchPauseRequested: true
+        });
+
+        assert.match(html, /暂停中/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('renders an explicit parallel batch toggle in stream settings', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true
+        });
+
+        assert.match(html, /并发批量/);
+        assert.match(html, /多张图或多条提示词会按当前渠道容量并发执行/);
+        assert.match(html, /id="parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="true"/);
+    });
+
+    it('keeps the parallel batch toggle disabled for a single image request', () => {
+        const html = renderGenerationForm({
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true
+        });
+
+        assert.match(html, /选择至少 2 张图片或 2 条提示词后可启用并发/);
+        assert.match(html, /id="parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('keeps the parallel batch toggle disabled when streaming strategy is off', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true,
+            streamingStrategy: 'off'
+        });
+
+        assert.match(html, /并发批量需要流式模式；非流式会保持顺序执行。/);
+        assert.match(html, /id="parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+
+    it('keeps the parallel batch toggle disabled when the server default streaming strategy is off', () => {
+        const html = renderGenerationForm({
+            currentMode: 'batch',
+            defaultAdvancedOpen: true,
+            defaultAdvancedTab: 'stream',
+            allowStreamingBatch: true,
+            enableParallelBatch: true,
+            defaultStreamingStrategy: 'off'
+        });
+
+        assert.match(html, /并发批量需要流式模式；非流式会保持顺序执行。/);
+        assert.match(html, /id="parallel-batch-enabled"/);
+        assert.match(html, /aria-checked="false"/);
+        assert.match(html, /disabled=""/);
+    });
+});

src/components/history-panel.test.tsx

@@ -0,0 +1,236 @@
+import {
+    HistoryPanel,
+    resolveHistoryPanelTabSync,
+    type GenerationActivityItem,
+    type InspirationItem
+} from './history-panel';
+import type { HistoryMetadata } from '@/lib/history-metadata';
+import { I18nProvider } from '@/lib/i18n';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+const noop = () => {};
+const historyItem: HistoryMetadata = {
+    timestamp: Date.UTC(2026, 4, 31, 12, 15),
+    images: [{ filename: 'history-card.png', clientRequestId: 'request-1' }],
+    storageModeUsed: 'indexeddb',
+    durationMs: 1350,
+    quality: 'high',
+    background: 'auto',
+    moderation: 'auto',
+    prompt: '用户真实历史提示词',
+    mode: 'generate',
+    costDetails: null,
+    output_format: 'png',
+    model: 'gpt-image-2',
+    size: '2048x2048'
+};
+const batchHistoryItem: HistoryMetadata = {
+    ...historyItem,
+    images: [
+        { filename: 'batch-card-1.png', clientRequestId: 'batch-request-1' },
+        { filename: 'batch-card-2.png', clientRequestId: 'batch-request-2' },
+        { filename: 'batch-card-3.png', clientRequestId: 'batch-request-3' }
+    ]
+};
+const failedHistoryItem: HistoryMetadata = {
+    ...historyItem,
+    timestamp: Date.UTC(2026, 4, 31, 12, 35),
+    images: [],
+    status: 'failed',
+    failureMessage: '上游或 API 中转站异常。请稍后重试。',
+    durationMs: 2200,
+    prompt: '用户真实失败提示词'
+};
+const inspirationItem: InspirationItem = {
+    id: 1,
+    createdAt: Date.UTC(2026, 4, 31, 12, 20),
+    prompt: '用户保存的真实灵感提示词'
+};
+
+function renderHistoryPanel(
+    history: HistoryMetadata[],
+    inspirations: InspirationItem[] = [],
+    activityItems: GenerationActivityItem[] = []
+): string {
+    return renderToStaticMarkup(
+        <I18nProvider>
+            <HistoryPanel
+                history={history}
+                inspirations={inspirations}
+                activityItems={activityItems}
+                onSelectImage={noop}
+                onApplyPrompt={noop}
+                onSaveInspiration={noop}
+                onSendHistoryToEdit={noop}
+                onDeleteInspiration={noop}
+                onClearHistory={noop}
+                getImageSrc={() => '/api/image/history-card.png'}
+                onDeleteItemRequest={noop}
+                itemPendingDeleteConfirmation={null}
+                onConfirmDeletion={noop}
+                onCancelDeletion={noop}
+                deletePreferenceDialogValue={false}
+                onDeletePreferenceDialogChange={noop}
+            />
+        </I18nProvider>
+    );
+}
+
+describe('HistoryPanel recent history actions', () => {
+    it('switches to recent history when history appears and no inspirations exist', () => {
+        assert.equal(
+            resolveHistoryPanelTabSync({
+                activeTab: 'inspiration',
+                historyCount: 1,
+                inspirationCount: 0
+            }),
+            'history'
+        );
+        assert.equal(
+            resolveHistoryPanelTabSync({
+                activeTab: 'inspiration',
+                historyCount: 1,
+                inspirationCount: 1
+            }),
+            'inspiration'
+        );
+        assert.equal(
+            resolveHistoryPanelTabSync({
+                activeTab: 'history',
+                historyCount: 0,
+                inspirationCount: 1
+            }),
+            'inspiration'
+        );
+    });
+
+    it('renders visible save, reuse, and continue-edit actions on history cards', () => {
+        const html = renderHistoryPanel([historyItem]);
+
+        assert.match(html, /最近生成/);
+        assert.match(html, /用户真实历史提示词/);
+        assert.match(html, /数据库/);
+        assert.doesNotMatch(html, /Album/);
+        assert.doesNotMatch(html, /Local/);
+        assert.match(html, /收藏这条历史提示词/);
+        assert.match(html, /复用这条历史记录到创作单/);
+        assert.match(html, /用这条历史记录的首张图片继续编辑/);
+    });
+
+    it('renders recent history as a mobile horizontal snap album', () => {
+        const html = renderHistoryPanel([historyItem]);
+
+        assert.match(html, /snap-x snap-mandatory/);
+        assert.match(html, /w-\[min\(76vw,280px\)\]/);
+    });
+
+    it('keeps multi-image history batches collapsed by default with an expand control', () => {
+        const html = renderHistoryPanel([batchHistoryItem]);
+
+        assert.match(html, /展开批次/);
+        assert.match(html, /3 张图/);
+        assert.match(html, /aria-expanded="false"/);
+        assert.match(html, /aria-controls="history-batch-/);
+        assert.doesNotMatch(html, /batch-thumbnail-strip/);
+    });
+
+    it('shows failed recent history reasons without a fake thumbnail', () => {
+        const html = renderHistoryPanel([failedHistoryItem]);
+
+        assert.match(html, /生成失败/);
+        assert.match(html, /失败原因：/);
+        assert.match(html, /上游或 API 中转站异常。请稍后重试。/);
+        assert.match(html, /用户真实失败提示词/);
+        assert.doesNotMatch(html, /<img/);
+        assert.doesNotMatch(html, /新图已入册 0 张/);
+    });
+
+    it('renders inspirations as a mobile horizontal snap album', () => {
+        const html = renderHistoryPanel([], [inspirationItem]);
+
+        assert.match(html, /snap-x snap-mandatory/);
+        assert.match(html, /w-\[min\(84vw,360px\)\]/);
+        assert.match(html, /用户保存的真实灵感提示词/);
+        assert.match(html, /aria-label="套用灵感：用户保存的真实灵感提示词"/);
+        assert.doesNotMatch(html, /窗边的花与书/);
+        assert.doesNotMatch(html, /inspiration-flowers/);
+    });
+
+    it('does not render fake inspiration actions without handlers', () => {
+        const html = renderHistoryPanel([], [inspirationItem]);
+
+        assert.match(html, /已保存的灵感/);
+        assert.match(html, /套用首个模板/);
+        assert.match(html, /1 条灵感/);
+        assert.doesNotMatch(html, /aria-label="收藏"/);
+        assert.doesNotMatch(html, />管理</);
+    });
+
+    it('renders a non-fake pending activity timeline before the first generation', () => {
+        const html = renderHistoryPanel([], [inspirationItem]);
+
+        assert.match(html, /activity-feed/);
+        assert.match(html, /aria-label="待开始生成动态"/);
+        assert.match(html, /点击生成后，这里会记录创作过程。/);
+        assert.match(html, /准备/);
+        assert.match(html, /预览/);
+        assert.match(html, /保存/);
+        assert.match(html, /失败/);
+        assert.match(html, /等待请求开始/);
+        assert.match(html, /等待流式预览/);
+        assert.match(html, /等待保存结果/);
+        assert.match(html, /失败时显示原因/);
+        assert.doesNotMatch(html, /新图已入册/);
+    });
+
+    it('renders live generation activity before completed history', () => {
+        const html = renderHistoryPanel(
+            [historyItem],
+            [inspirationItem],
+            [
+                {
+                    id: 'generating',
+                    label: '正在生成',
+                    detail: '正在把当前创作单送去生成，完成后会进入最近生成。',
+                    tone: 'progress'
+                }
+            ]
+        );
+
+        assert.match(html, /正在生成/);
+        assert.match(html, /正在把当前创作单送去生成/);
+        assert.match(html, /新图已入册/);
+    });
+
+    it('keeps generation activity visible outside the inspiration tab content', () => {
+        const html = renderHistoryPanel([historyItem], [inspirationItem]);
+        const tabContentIndex = html.indexOf('用户保存的真实灵感提示词');
+        const activityIndex = html.indexOf('请求、预览、保存和失败会在这里轻量更新。');
+
+        assert.ok(tabContentIndex >= 0);
+        assert.ok(activityIndex > tabContentIndex);
+        assert.match(html, /最近生成/);
+        assert.match(html, /新图已入册/);
+    });
+
+    it('renders batch progress activity as user-facing copy', () => {
+        const html = renderHistoryPanel(
+            [historyItem],
+            [inspirationItem],
+            [
+                {
+                    id: 'batch-progress',
+                    label: '批量进度',
+                    detail: '已完成 2/3 条任务。',
+                    tone: 'progress'
+                }
+            ]
+        );
+
+        assert.match(html, /批量进度/);
+        assert.match(html, /已完成 2\/3 条任务。/);
+    });
+});

src/components/history-panel.tsx

@@ -1,8 +1,8 @@
 'use client';
 
-import type { HistoryMetadata } from '@/app/page';
+import { ActivityTimeline } from '@/components/generation-activity-timeline';
 import { Button } from '@/components/ui/button';
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Card, CardContent, CardHeader } from '@/components/ui/card';
 import { Checkbox } from '@/components/ui/checkbox';
 import {
     Dialog,
@@ -14,7 +14,10 @@ import {
     DialogFooter,
     DialogClose
 } from '@/components/ui/dialog';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { getModelRates, type GptImageModel } from '@/lib/cost-utils';
+import type { GenerationActivityItem } from '@/lib/generation-activity';
+import type { HistoryMetadata } from '@/lib/history-metadata';
 import { useI18n } from '@/lib/i18n';
 import { cn } from '@/lib/utils';
 import {
@@ -27,14 +30,25 @@ import {
     HardDrive,
     Database,
     FileImage,
-    Trash2
+    Trash2,
+    WandSparkles,
+    Bookmark,
+    Plus,
+    ChevronDown,
+    AlertTriangle
 } from 'lucide-react';
 import Image from 'next/image';
 import * as React from 'react';
 
 type HistoryPanelProps = {
     history: HistoryMetadata[];
+    inspirations: InspirationItem[];
+    activityItems?: GenerationActivityItem[];
     onSelectImage: (item: HistoryMetadata) => void;
+    onApplyPrompt: (prompt: string, source: PromptApplySource) => void;
+    onSaveInspiration: (prompt: string) => void;
+    onSendHistoryToEdit: (item: HistoryMetadata) => void | Promise<void>;
+    onDeleteInspiration: (id: number) => void;
     onClearHistory: () => void;
     getImageSrc: (filename: string) => string | undefined;
     onDeleteItemRequest: (item: HistoryMetadata) => void;
@@ -45,6 +59,40 @@ type HistoryPanelProps = {
     onDeletePreferenceDialogChange: (isChecked: boolean) => void;
 };
 
+type HistoryPanelTab = 'inspiration' | 'history';
+
+export function resolveHistoryPanelTabSync(input: {
+    activeTab: HistoryPanelTab;
+    historyCount: number;
+    inspirationCount: number;
+}): HistoryPanelTab {
+    if (input.activeTab === 'inspiration' && input.historyCount > 0 && input.inspirationCount === 0) {
+        return 'history';
+    }
+    if (input.activeTab === 'history' && input.historyCount === 0 && input.inspirationCount > 0) {
+        return 'inspiration';
+    }
+    return input.activeTab;
+}
+
+export type InspirationItem = {
+    id: number;
+    prompt: string;
+    createdAt: number;
+};
+
+export type { GenerationActivityItem } from '@/lib/generation-activity';
+
+export type PromptApplySource =
+    | {
+          type: 'inspiration';
+          title: string;
+      }
+    | {
+          type: 'history';
+          item: HistoryMetadata;
+      };
+
 const formatDuration = (ms: number): string => {
     if (ms < 1000) {
         return `${ms}ms`;
@@ -73,11 +121,18 @@ const calculateCost = (value: number, rate: number): string => {
 const formatMoney = (value: number): string => value.toFixed(4);
 const formatEstimatedTokenCost = (value: number, rate: number): string => `$${calculateCost(value, rate)}`;
 
+function getStorageLabel(storageMode: HistoryMetadata['storageModeUsed'], t: ReturnType<typeof useI18n>['t']): string {
+    return storageMode === 'fs' ? t('history.storageFile') : t('history.storageDb');
+}
+
 function getCostBadge(
     item: HistoryMetadata,
     labels: { actual: string; estimated: string; pending: string }
 ): { label: string; actual: boolean } | null {
-    if (item.actualCostDetails?.source === 'new-api-log-token' && typeof item.actualCostDetails.actualAmount === 'number') {
+    if (
+        item.actualCostDetails?.source === 'new-api-log-token' &&
+        typeof item.actualCostDetails.actualAmount === 'number'
+    ) {
         return { label: `${labels.actual} $${formatMoney(item.actualCostDetails.actualAmount)}`, actual: true };
     }
     if (item.actualCostDetails?.source === 'pending') {
@@ -112,7 +167,39 @@ function getHistoryClientRequestIds(item: HistoryMetadata): string[] {
     );
 }
 
-function getCostStatusLabel(item: HistoryMetadata, labels: { actual: string; pending: string; unavailable: string; estimated: string }) {
+function buildPendingActivityItems(t: (key: string) => string): GenerationActivityItem[] {
+    return [
+        {
+            id: 'pending-request',
+            label: t('history.pendingRequest'),
+            detail: t('history.pendingRequestDetail'),
+            tone: 'neutral'
+        },
+        {
+            id: 'pending-streaming',
+            label: t('history.pendingStreaming'),
+            detail: t('history.pendingStreamingDetail'),
+            tone: 'neutral'
+        },
+        {
+            id: 'pending-saved',
+            label: t('history.pendingSaved'),
+            detail: t('history.pendingSavedDetail'),
+            tone: 'neutral'
+        },
+        {
+            id: 'pending-failed',
+            label: t('history.pendingFailed'),
+            detail: t('history.pendingFailedDetail'),
+            tone: 'neutral'
+        }
+    ];
+}
+
+function getCostStatusLabel(
+    item: HistoryMetadata,
+    labels: { actual: string; pending: string; unavailable: string; estimated: string }
+) {
     if (item.actualCostDetails?.source === 'new-api-log-token') return labels.actual;
     if (item.actualCostDetails?.source === 'pending') return labels.pending;
     if (item.actualCostDetails?.source === 'unavailable') return labels.unavailable;
@@ -122,7 +209,13 @@ function getCostStatusLabel(item: HistoryMetadata, labels: { actual: string; pen
 
 function HistoryPanelImpl({
     history,
+    inspirations,
+    activityItems = [],
     onSelectImage,
+    onApplyPrompt,
+    onSaveInspiration,
+    onSendHistoryToEdit,
+    onDeleteInspiration,
     onClearHistory,
     getImageSrc,
     onDeleteItemRequest,
@@ -133,12 +226,22 @@ function HistoryPanelImpl({
     onDeletePreferenceDialogChange
 }: HistoryPanelProps) {
     const { locale, t } = useI18n();
+    const pendingActivityItems = React.useMemo(() => buildPendingActivityItems(t), [t]);
+    const [activeTab, setActiveTab] = React.useState<HistoryPanelTab>(() =>
+        history.length > 0 && inspirations.length === 0 ? 'history' : 'inspiration'
+    );
     const [openPromptDialogTimestamp, setOpenPromptDialogTimestamp] = React.useState<number | null>(null);
     const [openCostDialogTimestamp, setOpenCostDialogTimestamp] = React.useState<number | null>(null);
     const [isTotalCostDialogOpen, setIsTotalCostDialogOpen] = React.useState(false);
     const [copiedTimestamp, setCopiedTimestamp] = React.useState<number | null>(null);
     const [imageResolutions, setImageResolutions] = React.useState<Record<string, string>>({});
     const [failedThumbnails, setFailedThumbnails] = React.useState<Record<string, boolean>>({});
+    const [expandedBatchTimestamp, setExpandedBatchTimestamp] = React.useState<number | null>(null);
+    const effectiveActiveTab = resolveHistoryPanelTabSync({
+        activeTab,
+        historyCount: history.length,
+        inspirationCount: inspirations.length
+    });
 
     const { totalCost, totalImages } = React.useMemo(() => {
         let cost = 0;
@@ -169,18 +272,23 @@ function HistoryPanelImpl({
         (timestamp: number) => new Date(timestamp).toLocaleString(locale),
         [locale]
     );
-    const handleThumbnailLoad = React.useCallback(
-        (filename: string, event: React.SyntheticEvent<HTMLImageElement>) => {
-            const image = event.currentTarget;
-            if (!image.naturalWidth || !image.naturalHeight) return;
-            const resolution = `${image.naturalWidth}x${image.naturalHeight}`;
-            setImageResolutions((current) => {
-                if (current[filename] === resolution) return current;
-                return { ...current, [filename]: resolution };
-            });
-        },
-        []
+    const formatStatusTime = React.useCallback(
+        (timestamp: number) =>
+            new Date(timestamp).toLocaleTimeString(locale, {
+                hour: '2-digit',
+                minute: '2-digit'
+            }),
+        [locale]
     );
+    const handleThumbnailLoad = React.useCallback((filename: string, event: React.SyntheticEvent<HTMLImageElement>) => {
+        const image = event.currentTarget;
+        if (!image.naturalWidth || !image.naturalHeight) return;
+        const resolution = `${image.naturalWidth}x${image.naturalHeight}`;
+        setImageResolutions((current) => {
+            if (current[filename] === resolution) return current;
+            return { ...current, [filename]: resolution };
+        });
+    }, []);
     const handleThumbnailError = React.useCallback((filename: string) => {
         setFailedThumbnails((current) => {
             if (current[filename]) return current;
@@ -197,17 +305,16 @@ function HistoryPanelImpl({
     );
 
     return (
-        <Card className='bg-card text-card-foreground flex h-full w-full flex-col overflow-hidden rounded-lg border border-border'>
-            <CardHeader className='flex flex-row items-center justify-between gap-4 border-b border-border px-4 py-3'>
-                <div className='flex items-center gap-2'>
-                    <CardTitle className='text-lg font-medium'>{t('history.title')}</CardTitle>
-                    {totalCost > 0 && (
+        <Card className='workbench-panel text-card-foreground border-border flex h-full w-full flex-col gap-0 overflow-hidden rounded-lg border py-0'>
+            <CardHeader className='border-border/70 flex flex-col gap-2 border-b px-4 pt-3 !pb-3'>
+                {totalCost > 0 ? (
+                    <div className='flex items-center justify-end gap-3'>
                         <Dialog open={isTotalCostDialogOpen} onOpenChange={setIsTotalCostDialogOpen}>
-	                            <DialogTrigger asChild>
-	                                <button
-	                                    type='button'
-	                                    className='mt-0.5 flex cursor-pointer items-center gap-1 rounded-full bg-green-600/80 px-1.5 py-0.5 text-[12px] text-white transition-[background-color,transform] hover:-translate-y-0.5 hover:bg-green-500/90 active:translate-y-0'
-	                                    aria-label={t('history.showTotalCost')}>
+                            <DialogTrigger asChild>
+                                <button
+                                    type='button'
+                                    className='bg-secondary text-secondary-foreground hover:bg-secondary/80 mt-0.5 flex min-h-6 cursor-pointer items-center gap-1 rounded-full px-2 py-0.5 text-[12px] transition-[background-color,transform] hover:-translate-y-0.5 active:translate-y-0'
+                                    aria-label={t('history.showTotalCost')}>
                                     {t('history.totalCost', { cost: totalCost.toFixed(4) })}
                                 </button>
                             </DialogTrigger>
@@ -288,159 +395,302 @@ function HistoryPanelImpl({
                                             type='button'
                                             variant='secondary'
                                             size='sm'
-                                            className='border border-transparent shadow-sm hover:border-border hover:bg-accent hover:text-accent-foreground active:scale-[0.98]'>
+                                            className='hover:border-border hover:bg-accent hover:text-accent-foreground border border-transparent shadow-sm active:scale-[0.98]'>
                                             {t('common.close')}
                                         </Button>
                                     </DialogClose>
                                 </DialogFooter>
                             </DialogContent>
                         </Dialog>
-                    )}
-                </div>
-                {history.length > 0 && (
+                    </div>
+                ) : null}
+                <Tabs
+                    value={effectiveActiveTab}
+                    onValueChange={(value) => setActiveTab(value as 'inspiration' | 'history')}
+                    className='gap-0'>
+                    <TabsList className='border-border grid h-auto w-full grid-cols-2 rounded-none border-0 border-b bg-transparent p-0'>
+                        <TabsTrigger
+                            value='inspiration'
+                            className='data-[state=active]:border-primary data-[state=active]:text-primary min-h-11 rounded-none border-0 border-b-2 border-transparent bg-transparent px-1 shadow-none data-[state=active]:bg-transparent data-[state=active]:shadow-none lg:min-h-8'>
+                            {t('history.inspirationAlbum')}
+                        </TabsTrigger>
+                        <TabsTrigger
+                            value='history'
+                            className='data-[state=active]:border-primary data-[state=active]:text-primary min-h-11 rounded-none border-0 border-b-2 border-transparent bg-transparent px-1 shadow-none data-[state=active]:bg-transparent data-[state=active]:shadow-none lg:min-h-8'>
+                            {t('history.recentGenerated')}
+                        </TabsTrigger>
+                    </TabsList>
+                    <TabsContent value='inspiration' forceMount className='hidden' />
+                    <TabsContent value='history' forceMount className='hidden' />
+                </Tabs>
+                {history.length > 0 && effectiveActiveTab === 'history' && (
                     <Button
                         variant='ghost'
                         size='sm'
                         onClick={onClearHistory}
-                        className='text-muted-foreground h-auto rounded-md px-2 py-1 hover:text-foreground'>
+                        className='text-muted-foreground hover:text-foreground h-auto rounded-md px-2 py-1'>
                         {t('history.clear')}
                     </Button>
                 )}
             </CardHeader>
-            <CardContent className='flex-grow overflow-y-auto p-4'>
-                {history.length === 0 ? (
-                    <div className='text-muted-foreground flex min-h-24 items-center justify-center rounded-md border border-dashed border-border px-4 text-center text-sm'>
+            <CardContent className='literary-scrollbar min-h-0 p-3 lg:max-h-[calc(100%-17.5rem)] lg:overflow-y-auto lg:p-3 xl:flex-none'>
+                {effectiveActiveTab === 'inspiration' ? (
+                    <div className='space-y-3 lg:space-y-2'>
+                        {inspirations.length === 0 ? (
+                            <div className='text-muted-foreground border-border bg-muted/20 flex min-h-32 flex-col items-center justify-center gap-2 rounded-md border border-dashed px-4 text-center text-sm'>
+                                <WandSparkles className='h-5 w-5 opacity-70' />
+                                <p>{t('history.inspirationEmpty')}</p>
+                            </div>
+                        ) : (
+                            <div className='-mx-3 flex snap-x snap-mandatory gap-3 overflow-x-auto px-3 pb-1 lg:mx-0 lg:block lg:space-y-2 lg:overflow-visible lg:px-0 lg:pb-0'>
+                                {inspirations.map((item) => {
+                                    const title = item.prompt.trim() || t('history.inspirationAlbum');
+                                    return (
+                                        <div
+                                            key={item.id}
+                                            className='group border-border/70 bg-card/58 hover:border-primary/30 flex w-[min(84vw,360px)] shrink-0 snap-start items-stretch gap-3 rounded-md border p-2 shadow-sm transition-[border-color,box-shadow] hover:shadow-md lg:w-auto lg:gap-2 lg:p-1.5 2xl:p-1'>
+                                            <button
+                                                type='button'
+                                                onClick={() =>
+                                                    onApplyPrompt(item.prompt, { type: 'inspiration', title })
+                                                }
+                                                aria-label={t('history.applyInspirationPrompt', { title })}
+                                                className='border-border bg-muted/30 text-muted-foreground flex min-h-24 w-24 shrink-0 items-center justify-center rounded border shadow-sm lg:min-h-20 lg:w-20 2xl:min-h-18 2xl:w-18'>
+                                                <Bookmark className='h-5 w-5' />
+                                            </button>
+                                            <div className='flex min-w-0 flex-1 flex-col gap-1.5 pr-1 2xl:gap-1'>
+                                                <div className='flex items-start justify-between gap-1.5'>
+                                                    <div className='min-w-0'>
+                                                        <p
+                                                            className='line-clamp-2 text-[15px] leading-5 font-medium 2xl:text-sm'
+                                                            title={title}>
+                                                            {title}
+                                                        </p>
+                                                    </div>
+                                                    <div className='flex shrink-0 gap-0.5 opacity-65 transition-opacity group-hover:opacity-100'>
+                                                        <span
+                                                            className='text-primary flex h-11 w-11 items-center justify-center rounded-md lg:h-7 lg:w-7'
+                                                            aria-label={t('history.savedInspiration')}
+                                                            role='img'>
+                                                            <Bookmark className='h-3.5 w-3.5 fill-current' />
+                                                        </span>
+                                                        <Button
+                                                            type='button'
+                                                            variant='ghost'
+                                                            size='icon'
+                                                            className='text-muted-foreground hover:text-destructive h-11 w-11 lg:h-7 lg:w-7'
+                                                            onClick={() => onDeleteInspiration(item.id)}
+                                                            aria-label={t('history.deleteInspiration')}>
+                                                            <Trash2 className='h-3.5 w-3.5' />
+                                                        </Button>
+                                                    </div>
+                                                </div>
+                                                <div className='flex items-center justify-between gap-2'>
+                                                    <span className='text-muted-foreground text-[11px]'>
+                                                        {item.createdAt > 0
+                                                            ? formatTimestamp(item.createdAt)
+                                                            : t('history.template')}
+                                                    </span>
+                                                    <Button
+                                                        type='button'
+                                                        size='sm'
+                                                        variant='ghost'
+                                                        className='min-h-11 px-3 text-xs lg:min-h-7 lg:px-2'
+                                                        onClick={() =>
+                                                            onApplyPrompt(item.prompt, { type: 'inspiration', title })
+                                                        }>
+                                                        {t('history.applyInspiration')}
+                                                    </Button>
+                                                </div>
+                                            </div>
+                                        </div>
+                                    );
+                                })}
+                            </div>
+                        )}
+                        <div className='flex items-center justify-between rounded-md px-1 text-sm'>
+                            <button
+                                type='button'
+                                className='text-muted-foreground hover:text-primary focus-visible:ring-ring -ml-2 inline-flex min-h-11 items-center gap-1.5 rounded-md px-2 transition-[color,box-shadow] disabled:cursor-not-allowed disabled:opacity-50 focus-visible:ring-2 focus-visible:outline-none lg:ml-0 lg:min-h-8 lg:px-0'
+                                disabled={!inspirations[0]}
+                                onClick={() =>
+                                    inspirations[0] &&
+                                    onApplyPrompt(inspirations[0].prompt, {
+                                        type: 'inspiration',
+                                        title: t('history.inspirationAlbum')
+                                    })
+                                }>
+                                <Plus className='h-4 w-4' />
+                                {t('history.applyFirstTemplate')}
+                            </button>
+                            <span className='text-muted-foreground -mr-2 min-h-11 rounded-md px-2 py-3 lg:mr-0 lg:min-h-8 lg:py-1.5'>
+                                {t('history.inspirationCount', { count: inspirations.length })}
+                            </span>
+                        </div>
+                    </div>
+                ) : history.length === 0 ? (
+                    <div className='text-muted-foreground border-border flex min-h-24 items-center justify-center rounded-md border border-dashed px-4 text-center text-sm'>
                         <p>{t('history.empty')}</p>
                     </div>
                 ) : (
-                    <div className='grid grid-cols-2 gap-4 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5'>
+                    <div className='-mx-3 flex snap-x snap-mandatory gap-3 overflow-x-auto px-3 pb-1 lg:mx-0 lg:grid lg:grid-cols-1 lg:overflow-visible lg:px-0 lg:pb-0 2xl:grid-cols-2'>
                         {[...history].map((item) => {
                             const firstImage = item.images?.[0];
                             const imageCount = item.images?.length ?? 0;
+                            const isFailedItem = item.status === 'failed';
+                            const failureMessage = item.failureMessage?.trim();
                             const isMultiImage = imageCount > 1;
                             const itemKey = item.timestamp;
-	                            const originalStorageMode = item.storageModeUsed || 'fs';
-	                            const outputFormat = item.output_format || 'png';
-	                            const costBadge = getCostBadge(item, {
-	                                actual: t('history.actualCostShort'),
-	                                estimated: t('history.estimatedCostShort'),
-	                                pending: t('history.actualCostPending')
-	                            });
-	                            const requestIds = getHistoryClientRequestIds(item);
-	                            const filenames = item.images.map((image) => image.filename);
-	                            const costStatus = getCostStatusLabel(item, {
-	                                actual: t('history.actualCostShort'),
-	                                pending: t('history.actualCostPending'),
-	                                unavailable: t('history.actualCostUnavailable'),
-	                                estimated: t('history.estimatedCostShort')
-	                            });
+                            const hasPrompt = item.prompt.trim().length > 0;
+                            const originalStorageMode = item.storageModeUsed || 'fs';
+                            const outputFormat = item.output_format || 'png';
+                            const costBadge = getCostBadge(item, {
+                                actual: t('history.actualCostShort'),
+                                estimated: t('history.estimatedCostShort'),
+                                pending: t('history.actualCostPending')
+                            });
+                            const requestIds = getHistoryClientRequestIds(item);
+                            const filenames = item.images.map((image) => image.filename);
+                            const isBatchExpanded = expandedBatchTimestamp === item.timestamp;
+                            const costStatus = getCostStatusLabel(item, {
+                                actual: t('history.actualCostShort'),
+                                pending: t('history.actualCostPending'),
+                                unavailable: t('history.actualCostUnavailable'),
+                                estimated: t('history.estimatedCostShort')
+                            });
 
-	                            let thumbnailUrl: string | undefined;
-	                            if (firstImage) {
+                            let thumbnailUrl: string | undefined;
+                            if (firstImage) {
                                 if (originalStorageMode === 'indexeddb') {
                                     thumbnailUrl = getImageSrc(firstImage.filename);
                                 } else {
-	                                    thumbnailUrl = `/api/image/${firstImage.filename}`;
-	                                }
-	                            }
-	                            const isThumbnailUnavailable =
-	                                !thumbnailUrl || (firstImage ? failedThumbnails[firstImage.filename] : false);
+                                    thumbnailUrl = `/api/image/${firstImage.filename}`;
+                                }
+                            }
+                            const isThumbnailUnavailable =
+                                !thumbnailUrl || (firstImage ? failedThumbnails[firstImage.filename] : false);
 
-	                            return (
-	                                <div key={itemKey} className='flex flex-col'>
-	                                    <div className='group relative'>
-	                                        <button
-	                                            type='button'
-	                                            onClick={() => onSelectImage(item)}
-	                                            className='focus:ring-ring focus:ring-offset-background relative block aspect-square w-full cursor-pointer overflow-hidden rounded-t-md border border-border transition-[border-color,filter,transform,box-shadow] duration-150 hover:-translate-y-0.5 hover:border-foreground/20 hover:brightness-110 active:translate-y-0 focus:outline-none focus:ring-2 focus:ring-offset-2'
+                            return (
+                                <div
+                                    key={itemKey}
+                                    className='flex w-[min(76vw,280px)] shrink-0 snap-start flex-col lg:w-auto'>
+                                    <div className='group relative'>
+                                        <button
+                                            type='button'
+                                            onClick={() => onSelectImage(item)}
+                                            disabled={isFailedItem}
+                                            className={cn(
+                                                'focus:ring-ring focus:ring-offset-background border-border relative block aspect-square w-full overflow-hidden rounded-t-md border transition-[border-color,filter,transform,box-shadow] duration-150 focus:ring-2 focus:ring-offset-2 focus:outline-none active:translate-y-0',
+                                                isFailedItem
+                                                    ? 'cursor-default'
+                                                    : 'hover:border-foreground/20 cursor-pointer hover:-translate-y-0.5 hover:brightness-110'
+                                            )}
                                             aria-label={t('history.viewBatch', {
                                                 time: formatTimestamp(item.timestamp)
                                             })}>
-	                                            {!isThumbnailUnavailable && thumbnailUrl && firstImage ? (
-	                                                <Image
-	                                                    src={thumbnailUrl}
-	                                                    alt={t('history.previewBatch', {
+                                            {isFailedItem ? (
+                                                <div className='bg-destructive/5 text-muted-foreground flex h-full w-full flex-col items-center justify-center gap-2 px-4 text-center text-xs'>
+                                                    <AlertTriangle
+                                                        size={20}
+                                                        className='text-destructive'
+                                                        aria-hidden='true'
+                                                    />
+                                                    <span className='text-foreground font-medium'>
+                                                        {t('history.failedStatus')}
+                                                    </span>
+                                                    <span className='line-clamp-2'>
+                                                        {failureMessage || t('history.failedReasonUnavailable')}
+                                                    </span>
+                                                </div>
+                                            ) : !isThumbnailUnavailable && thumbnailUrl && firstImage ? (
+                                                <Image
+                                                    src={thumbnailUrl}
+                                                    alt={t('history.previewBatch', {
                                                         time: formatTimestamp(item.timestamp)
                                                     })}
                                                     width={150}
-	                                                    height={150}
-	                                                    className='h-full w-full object-cover'
-	                                                    onLoad={(event) => handleThumbnailLoad(firstImage.filename, event)}
-	                                                    onError={() => handleThumbnailError(firstImage.filename)}
-	                                                    unoptimized
-	                                                />
-	                                            ) : (
-	                                                <div className='bg-muted text-muted-foreground flex h-full w-full flex-col items-center justify-center gap-1 px-3 text-center text-xs'>
-	                                                    <FileImage size={18} className='text-muted-foreground' />
-	                                                    <span>{t('history.previewUnavailable')}</span>
-	                                                </div>
-	                                            )}
+                                                    height={150}
+                                                    className='h-full w-full object-cover'
+                                                    onLoad={(event) => handleThumbnailLoad(firstImage.filename, event)}
+                                                    onError={() => handleThumbnailError(firstImage.filename)}
+                                                    unoptimized
+                                                />
+                                            ) : (
+                                                <div className='bg-muted text-muted-foreground flex h-full w-full flex-col items-center justify-center gap-1 px-3 text-center text-xs'>
+                                                    <FileImage size={18} className='text-muted-foreground' />
+                                                    <span>{t('history.previewUnavailable')}</span>
+                                                </div>
+                                            )}
                                             <div
                                                 className={cn(
-                                                    'pointer-events-none absolute top-1 left-1 z-10 flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[11px] text-white',
-                                                    item.mode === 'edit' ? 'bg-orange-600/80' : 'bg-blue-600/80'
+                                                    'pointer-events-none absolute top-1 left-1 z-10 flex items-center gap-1 rounded-sm border px-1.5 py-0.5 text-[11px]',
+                                                    isFailedItem
+                                                        ? 'border-destructive/35 bg-destructive/90 text-destructive-foreground'
+                                                        : item.mode === 'edit'
+                                                          ? 'border-primary/30 bg-primary/88 text-primary-foreground'
+                                                          : 'border-secondary/40 bg-secondary/90 text-secondary-foreground'
                                                 )}>
-                                                {item.mode === 'edit' ? (
+                                                {isFailedItem ? (
+                                                    <AlertTriangle size={12} />
+                                                ) : item.mode === 'edit' ? (
                                                     <Pencil size={12} />
                                                 ) : (
                                                     <SparklesIcon size={12} />
                                                 )}
-                                                {item.mode === 'edit' ? t('history.modeEdit') : t('history.modeCreate')}
+                                                {isFailedItem
+                                                    ? t('history.failedStatus')
+                                                    : item.mode === 'edit'
+                                                      ? t('history.modeEdit')
+                                                      : t('history.modeCreate')}
                                             </div>
                                             {isMultiImage && (
-                                                <div className='pointer-events-none absolute right-1 bottom-1 z-10 flex items-center gap-1 rounded-full bg-black/70 px-1.5 py-0.5 text-[12px] text-white'>
+                                                <div className='pointer-events-none absolute right-1 bottom-1 z-10 flex items-center gap-1 rounded-sm bg-[oklch(0.28_0.028_58/0.78)] px-1.5 py-0.5 text-[12px] text-white'>
                                                     <Layers size={16} />
                                                     {imageCount}
                                                 </div>
                                             )}
                                             <div className='pointer-events-none absolute bottom-1 left-1 z-10 flex items-center gap-1'>
-                                                <div className='bg-background/85 text-muted-foreground flex items-center gap-1 rounded-full border border-border px-1 py-0.5 text-[11px]'>
+                                                <div className='bg-background/85 text-muted-foreground border-border flex items-center gap-1 rounded-sm border px-1 py-0.5 text-[11px]'>
                                                     {originalStorageMode === 'fs' ? (
                                                         <HardDrive size={12} className='text-muted-foreground' />
                                                     ) : (
-                                                        <Database size={12} className='text-blue-400' />
+                                                        <Database size={12} className='text-primary' />
                                                     )}
-                                                    <span>
-                                                        {originalStorageMode === 'fs'
-                                                            ? t('history.storageFile')
-                                                            : t('history.storageDb')}
-                                                    </span>
+                                                    <span>{getStorageLabel(originalStorageMode, t)}</span>
                                                 </div>
                                                 {item.output_format && (
-                                                    <div className='bg-background/85 text-muted-foreground flex items-center gap-1 rounded-full border border-border px-1 py-0.5 text-[11px]'>
+                                                    <div className='bg-background/85 text-muted-foreground border-border flex items-center gap-1 rounded-sm border px-1 py-0.5 text-[11px]'>
                                                         <FileImage size={12} className='text-muted-foreground' />
                                                         <span>{outputFormat.toUpperCase()}</span>
                                                     </div>
                                                 )}
                                             </div>
                                         </button>
-	                                        {costBadge && (
-	                                            <Dialog
-	                                                open={openCostDialogTimestamp === itemKey}
-	                                                onOpenChange={(isOpen) => !isOpen && setOpenCostDialogTimestamp(null)}>
-	                                                <DialogTrigger asChild>
-	                                                    <button
-	                                                        type='button'
-	                                                        onClick={(e) => {
-	                                                            e.stopPropagation();
-	                                                            setOpenCostDialogTimestamp(itemKey);
-	                                                        }}
-	                                                        className={cn(
-	                                                            'absolute top-7 right-1 z-20 flex min-h-6 cursor-pointer items-center gap-0.5 rounded-full px-2 py-0.5 text-[11px] text-white shadow-sm transition-[background-color,transform] hover:-translate-y-0.5 active:translate-y-0',
-	                                                            costBadge.actual
-	                                                                ? 'bg-green-600/80 hover:bg-green-500/90'
-	                                                                : 'bg-zinc-700/80 hover:bg-zinc-600/90'
-	                                                        )}
-	                                                        aria-label={`${t('history.showCost')} ${costBadge.label}`}>
-	                                                        <DollarSign size={12} />
-	                                                        {costBadge.label}
-	                                                    </button>
-	                                                </DialogTrigger>
+                                        {costBadge && (
+                                            <Dialog
+                                                open={openCostDialogTimestamp === itemKey}
+                                                onOpenChange={(isOpen) => !isOpen && setOpenCostDialogTimestamp(null)}>
+                                                <DialogTrigger asChild>
+                                                    <button
+                                                        type='button'
+                                                        onClick={(e) => {
+                                                            e.stopPropagation();
+                                                            setOpenCostDialogTimestamp(itemKey);
+                                                        }}
+                                                        className={cn(
+                                                            'absolute top-7 right-1 z-20 flex min-h-6 cursor-pointer items-center gap-0.5 rounded-sm px-2 py-0.5 text-[11px] text-white shadow-sm transition-[background-color,transform] hover:-translate-y-0.5 active:translate-y-0',
+                                                            costBadge.actual
+                                                                ? 'bg-secondary text-secondary-foreground hover:bg-secondary/85'
+                                                                : 'bg-foreground/80 text-background hover:bg-foreground/70'
+                                                        )}
+                                                        aria-label={`${t('history.showCost')} ${costBadge.label}`}>
+                                                        <DollarSign size={12} />
+                                                        {costBadge.label}
+                                                    </button>
+                                                </DialogTrigger>
                                                 <DialogContent className='sm:max-w-[450px]'>
                                                     <DialogHeader>
-                                                        <DialogTitle>
-                                                            {t('history.costBreakdown')}
-                                                        </DialogTitle>
+                                                        <DialogTitle>{t('history.costBreakdown')}</DialogTitle>
                                                         <DialogDescription className='sr-only'>
                                                             {t('history.costBreakdownDescription')}
                                                         </DialogDescription>
@@ -477,13 +727,15 @@ function HistoryPanelImpl({
                                                                 </div>
                                                                 <div className='text-muted-foreground space-y-2 py-4 text-sm'>
                                                                     {item.actualCostDetails && (
-                                                                        <div className='space-y-2 rounded-md border border-border bg-card/70 p-3'>
+                                                                        <div className='border-border bg-card/70 space-y-2 rounded-md border p-3'>
                                                                             <div className='flex justify-between gap-3'>
                                                                                 <span>{t('history.actualCost')}</span>
                                                                                 <span className='text-foreground font-medium'>
                                                                                     {formatActualCostLabel(
                                                                                         item,
-                                                                                        t('history.actualCostUnavailable'),
+                                                                                        t(
+                                                                                            'history.actualCostUnavailable'
+                                                                                        ),
                                                                                         t('history.actualCostPending')
                                                                                     )}
                                                                                 </span>
@@ -495,24 +747,35 @@ function HistoryPanelImpl({
                                                                                 </span>
                                                                             </div>
                                                                             <div className='flex justify-between gap-3'>
-                                                                                <span>{t('history.costConfidence')}</span>
-                                                                                <span>{item.actualCostDetails.confidence}</span>
+                                                                                <span>
+                                                                                    {t('history.costConfidence')}
+                                                                                </span>
+                                                                                <span>
+                                                                                    {item.actualCostDetails.confidence}
+                                                                                </span>
                                                                             </div>
-                                                                            {typeof item.actualCostDetails.actualQuota ===
-                                                                                'number' && (
+                                                                            {typeof item.actualCostDetails
+                                                                                .actualQuota === 'number' && (
                                                                                 <div className='flex justify-between gap-3'>
-                                                                                    <span>{t('history.actualQuota')}</span>
+                                                                                    <span>
+                                                                                        {t('history.actualQuota')}
+                                                                                    </span>
                                                                                     <span>
                                                                                         {item.actualCostDetails.actualQuota.toLocaleString()}
                                                                                     </span>
                                                                                 </div>
                                                                             )}
-                                                                            {typeof item.actualCostDetails.matchedLogId ===
-                                                                                'number' && (
+                                                                            {typeof item.actualCostDetails
+                                                                                .matchedLogId === 'number' && (
                                                                                 <div className='flex justify-between gap-3'>
-                                                                                    <span>{t('history.matchedLogId')}</span>
                                                                                     <span>
-                                                                                        {item.actualCostDetails.matchedLogId}
+                                                                                        {t('history.matchedLogId')}
+                                                                                    </span>
+                                                                                    <span>
+                                                                                        {
+                                                                                            item.actualCostDetails
+                                                                                                .matchedLogId
+                                                                                        }
                                                                                     </span>
                                                                                 </div>
                                                                             )}
@@ -526,25 +789,32 @@ function HistoryPanelImpl({
                                                                     {item.costDetails && (
                                                                         <>
                                                                             <div className='flex justify-between'>
-                                                                                <span>{t('history.textInputTokens')}</span>{' '}
+                                                                                <span>
+                                                                                    {t('history.textInputTokens')}
+                                                                                </span>{' '}
                                                                                 <span>
                                                                                     {item.costDetails.text_input_tokens.toLocaleString()}{' '}
                                                                                     (
                                                                                     {formatEstimatedTokenCost(
-                                                                                        item.costDetails.text_input_tokens,
+                                                                                        item.costDetails
+                                                                                            .text_input_tokens,
                                                                                         rates.textInputPerToken
                                                                                     )}
                                                                                     )
                                                                                 </span>
                                                                             </div>
-                                                                            {item.costDetails.image_input_tokens > 0 && (
+                                                                            {item.costDetails.image_input_tokens >
+                                                                                0 && (
                                                                                 <div className='flex justify-between'>
-                                                                                    <span>{t('history.imageInputTokens')}</span>{' '}
+                                                                                    <span>
+                                                                                        {t('history.imageInputTokens')}
+                                                                                    </span>{' '}
                                                                                     <span>
                                                                                         {item.costDetails.image_input_tokens.toLocaleString()}{' '}
                                                                                         (
                                                                                         {formatEstimatedTokenCost(
-                                                                                            item.costDetails.image_input_tokens,
+                                                                                            item.costDetails
+                                                                                                .image_input_tokens,
                                                                                             rates.imageInputPerToken
                                                                                         )}
                                                                                         )
@@ -552,12 +822,15 @@ function HistoryPanelImpl({
                                                                                 </div>
                                                                             )}
                                                                             <div className='flex justify-between'>
-                                                                                <span>{t('history.imageOutputTokens')}</span>{' '}
+                                                                                <span>
+                                                                                    {t('history.imageOutputTokens')}
+                                                                                </span>{' '}
                                                                                 <span>
                                                                                     {item.costDetails.image_output_tokens.toLocaleString()}{' '}
                                                                                     (
                                                                                     {formatEstimatedTokenCost(
-                                                                                        item.costDetails.image_output_tokens,
+                                                                                        item.costDetails
+                                                                                            .image_output_tokens,
                                                                                         rates.imageOutputPerToken
                                                                                     )}
                                                                                     )
@@ -565,8 +838,15 @@ function HistoryPanelImpl({
                                                                             </div>
                                                                             <hr className='border-border my-2' />
                                                                             <div className='text-foreground flex justify-between font-medium'>
-                                                                                <span>{t('history.totalEstimatedCost')}</span>
-                                                                                <span>${item.costDetails.estimated_cost_usd.toFixed(4)}</span>
+                                                                                <span>
+                                                                                    {t('history.totalEstimatedCost')}
+                                                                                </span>
+                                                                                <span>
+                                                                                    $
+                                                                                    {item.costDetails.estimated_cost_usd.toFixed(
+                                                                                        4
+                                                                                    )}
+                                                                                </span>
                                                                             </div>
                                                                         </>
                                                                     )}
@@ -580,7 +860,7 @@ function HistoryPanelImpl({
                                                                 type='button'
                                                                 variant='secondary'
                                                                 size='sm'
-                                                                className='border border-transparent shadow-sm hover:border-border hover:bg-accent hover:text-accent-foreground active:scale-[0.98]'>
+                                                                className='hover:border-border hover:bg-accent hover:text-accent-foreground border border-transparent shadow-sm active:scale-[0.98]'>
                                                                 {t('common.close')}
                                                             </Button>
                                                         </DialogClose>
@@ -590,17 +870,34 @@ function HistoryPanelImpl({
                                         )}
                                     </div>
 
-                                    <div className='text-muted-foreground bg-card/70 space-y-1 rounded-b-md border border-t-0 border-border p-2 text-xs'>
+                                    <div className='text-muted-foreground bg-card/70 border-border space-y-1 rounded-b-md border border-t-0 p-2 text-xs'>
                                         <p title={t('history.generatedOn', { time: formatTimestamp(item.timestamp) })}>
-                                            <span className='text-foreground font-medium'>{t('history.time')}</span>{' '}
-                                            {formatDuration(item.durationMs)}
+                                            <span className='text-foreground font-medium'>
+                                                {t('history.generatedAt')}
+                                            </span>{' '}
+                                            {formatStatusTime(item.timestamp)}
+                                            <span className='text-muted-foreground/70 px-1'>/</span>
+                                            {isFailedItem
+                                                ? `${t('history.failedStatus')}，${formatDuration(item.durationMs)}`
+                                                : t('history.statusBatchSummary', {
+                                                      count: imageCount,
+                                                      duration: formatDuration(item.durationMs)
+                                                  })}
                                         </p>
+                                        {isFailedItem && (
+                                            <p className='border-destructive/25 bg-destructive/5 text-destructive rounded-sm border px-2 py-1 leading-4'>
+                                                <span className='font-medium'>{t('history.failureReason')}</span>{' '}
+                                                {failureMessage || t('history.failedReasonUnavailable')}
+                                            </p>
+                                        )}
                                         <p>
                                             <span className='text-foreground font-medium'>{t('history.model')}</span>{' '}
                                             {item.model || 'gpt-image-1'}
                                         </p>
                                         <p>
-                                            <span className='text-foreground font-medium'>{t('history.resolution')}</span>{' '}
+                                            <span className='text-foreground font-medium'>
+                                                {t('history.resolution')}
+                                            </span>{' '}
                                             {formatResolution(item, firstImage)}
                                         </p>
                                         <p>
@@ -615,7 +912,130 @@ function HistoryPanelImpl({
                                             <span className='text-foreground font-medium'>{t('history.mod')}</span>{' '}
                                             {item.moderation}
                                         </p>
-                                        <div className='mt-2 flex items-center gap-1'>
+                                        <p
+                                            className='mt-2 max-h-8 min-h-8 overflow-hidden leading-4 break-words'
+                                            title={item.prompt || t('history.noPrompt')}>
+                                            {item.prompt || t('history.noPrompt')}
+                                        </p>
+                                        <div className='mt-2 grid grid-cols-3 gap-1'>
+                                            <Button
+                                                type='button'
+                                                variant='outline'
+                                                size='sm'
+                                                className='min-h-11 min-w-0 px-2 text-[11px] lg:h-7 lg:min-h-0 lg:px-1'
+                                                disabled={!hasPrompt}
+                                                onClick={() => onSaveInspiration(item.prompt)}
+                                                aria-label={t('history.saveHistoryPrompt')}>
+                                                <Bookmark className='h-3.5 w-3.5' />
+                                                <span className='truncate'>{t('history.saveToInspiration')}</span>
+                                            </Button>
+                                            <Button
+                                                type='button'
+                                                variant='outline'
+                                                size='sm'
+                                                className='min-h-11 min-w-0 px-2 text-[11px] lg:h-7 lg:min-h-0 lg:px-1'
+                                                disabled={!hasPrompt}
+                                                onClick={() => onApplyPrompt(item.prompt, { type: 'history', item })}
+                                                aria-label={t('history.reuseHistoryPrompt')}>
+                                                <WandSparkles className='h-3.5 w-3.5' />
+                                                <span className='truncate'>{t('history.reuseHistory')}</span>
+                                            </Button>
+                                            <Button
+                                                type='button'
+                                                variant='outline'
+                                                size='sm'
+                                                className='min-h-11 min-w-0 px-2 text-[11px] lg:h-7 lg:min-h-0 lg:px-1'
+                                                disabled={!firstImage || isFailedItem}
+                                                onClick={() => onSendHistoryToEdit(item)}
+                                                aria-label={t('history.continueHistoryEdit')}>
+                                                <Pencil className='h-3.5 w-3.5' />
+                                                <span className='truncate'>{t('history.continueEdit')}</span>
+                                            </Button>
+                                        </div>
+                                        {isMultiImage && (
+                                            <div className='mt-2 space-y-1.5'>
+                                                <Button
+                                                    type='button'
+                                                    variant='ghost'
+                                                    size='sm'
+                                                    className='text-muted-foreground hover:text-foreground min-h-11 w-full justify-between px-2 text-[11px] lg:h-7 lg:min-h-0'
+                                                    aria-expanded={isBatchExpanded}
+                                                    aria-controls={`history-batch-${item.timestamp}`}
+                                                    onClick={() =>
+                                                        setExpandedBatchTimestamp((current) =>
+                                                            current === item.timestamp ? null : item.timestamp
+                                                        )
+                                                    }>
+                                                    <span>
+                                                        {isBatchExpanded
+                                                            ? t('history.collapseBatch')
+                                                            : t('history.expandBatch')}
+                                                    </span>
+                                                    <span className='inline-flex items-center gap-1'>
+                                                        {t('history.batchImageCount', { count: imageCount })}
+                                                        <ChevronDown
+                                                            className={cn(
+                                                                'h-3.5 w-3.5 transition-transform',
+                                                                isBatchExpanded && 'rotate-180'
+                                                            )}
+                                                        />
+                                                    </span>
+                                                </Button>
+                                                {isBatchExpanded && (
+                                                    <div
+                                                        id={`history-batch-${item.timestamp}`}
+                                                        className='batch-thumbnail-strip grid grid-cols-3 gap-1.5'
+                                                        aria-label={t('history.batchThumbnails')}>
+                                                        {item.images.map((image, index) => {
+                                                            const imageSrc =
+                                                                originalStorageMode === 'indexeddb'
+                                                                    ? getImageSrc(image.filename)
+                                                                    : `/api/image/${image.filename}`;
+                                                            const unavailable =
+                                                                !imageSrc || failedThumbnails[image.filename];
+
+                                                            return (
+                                                                <button
+                                                                    key={`${item.timestamp}-${image.filename}`}
+                                                                    type='button'
+                                                                    onClick={() => onSelectImage(item)}
+                                                                    className='border-border bg-muted relative aspect-square overflow-hidden rounded-sm border'
+                                                                    aria-label={t('history.batchThumbnail', {
+                                                                        index: index + 1
+                                                                    })}>
+                                                                    {!unavailable ? (
+                                                                        <Image
+                                                                            src={imageSrc}
+                                                                            alt={t('history.batchThumbnail', {
+                                                                                index: index + 1
+                                                                            })}
+                                                                            fill
+                                                                            sizes='88px'
+                                                                            className='object-cover'
+                                                                            onLoad={(event) =>
+                                                                                handleThumbnailLoad(
+                                                                                    image.filename,
+                                                                                    event
+                                                                                )
+                                                                            }
+                                                                            onError={() =>
+                                                                                handleThumbnailError(image.filename)
+                                                                            }
+                                                                            unoptimized
+                                                                        />
+                                                                    ) : (
+                                                                        <span className='text-muted-foreground flex h-full items-center justify-center px-1 text-center text-[10px] leading-3'>
+                                                                            {t('history.previewUnavailable')}
+                                                                        </span>
+                                                                    )}
+                                                                </button>
+                                                            );
+                                                        })}
+                                                    </div>
+                                                )}
+                                            </div>
+                                        )}
+                                        <div className='mt-1 flex items-center gap-1'>
                                             <Dialog
                                                 open={openPromptDialogTimestamp === itemKey}
                                                 onOpenChange={(isOpen) =>
@@ -632,69 +1052,127 @@ function HistoryPanelImpl({
                                                 </DialogTrigger>
                                                 <DialogContent className='sm:max-w-[625px]'>
                                                     <DialogHeader>
-                                                        <DialogTitle>
-                                                            {t('history.details')}
-                                                        </DialogTitle>
+                                                        <DialogTitle>{t('history.details')}</DialogTitle>
                                                         <DialogDescription className='sr-only'>
                                                             {t('history.detailsDescription')}
                                                         </DialogDescription>
                                                     </DialogHeader>
                                                     <div className='space-y-3'>
-                                                        <dl className='grid grid-cols-2 gap-x-4 gap-y-3 rounded-md border border-border bg-card/70 p-3 text-sm sm:grid-cols-3'>
+                                                        <dl className='border-border bg-card/70 grid grid-cols-2 gap-x-4 gap-y-3 rounded-md border p-3 text-sm sm:grid-cols-3'>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.generatedAt')}</dt>
-                                                                <dd className='text-foreground font-medium'>{formatTimestamp(item.timestamp)}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.generatedAt')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {formatTimestamp(item.timestamp)}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.time')}</dt>
-                                                                <dd className='text-foreground font-medium'>{formatDuration(item.durationMs)}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.time')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {formatDuration(item.durationMs)}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.mode')}</dt>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.mode')}
+                                                                </dt>
                                                                 <dd className='text-foreground font-medium'>
-                                                                    {item.mode === 'edit' ? t('history.modeEdit') : t('history.modeCreate')}
+                                                                    {item.mode === 'edit'
+                                                                        ? t('history.modeEdit')
+                                                                        : t('history.modeCreate')}
                                                                 </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.model')}</dt>
-                                                                <dd className='text-foreground font-medium'>{item.model || 'gpt-image-1'}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.model')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {item.model || 'gpt-image-1'}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.resolution')}</dt>
-                                                                <dd className='text-foreground font-medium'>{formatResolution(item, firstImage)}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.resolution')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {formatResolution(item, firstImage)}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.quality')}</dt>
-                                                                <dd className='text-foreground font-medium'>{item.quality}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.quality')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {item.quality}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.bg')}</dt>
-                                                                <dd className='text-foreground font-medium'>{item.background}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.bg')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {item.background}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.mod')}</dt>
-                                                                <dd className='text-foreground font-medium'>{item.moderation}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.mod')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {item.moderation}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.imageCount')}</dt>
-                                                                <dd className='text-foreground font-medium'>{imageCount.toLocaleString(locale)}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.imageCount')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {imageCount.toLocaleString(locale)}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.outputFormat')}</dt>
-                                                                <dd className='text-foreground font-medium'>{outputFormat.toUpperCase()}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.outputFormat')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {outputFormat.toUpperCase()}
+                                                                </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.storage')}</dt>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.storage')}
+                                                                </dt>
                                                                 <dd className='text-foreground font-medium'>
-                                                                    {originalStorageMode === 'fs' ? t('history.storageFile') : t('history.storageDb')}
+                                                                    {originalStorageMode === 'fs'
+                                                                        ? t('history.storageFile')
+                                                                        : t('history.storageDb')}
                                                                 </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.costStatus')}</dt>
-                                                                <dd className='text-foreground font-medium'>{costStatus}</dd>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.costStatus')}
+                                                                </dt>
+                                                                <dd className='text-foreground font-medium'>
+                                                                    {costStatus}
+                                                                </dd>
                                                             </div>
+                                                            {isFailedItem && (
+                                                                <div>
+                                                                    <dt className='text-muted-foreground'>
+                                                                        {t('history.status')}
+                                                                    </dt>
+                                                                    <dd className='text-destructive font-medium'>
+                                                                        {t('history.failedStatus')}
+                                                                    </dd>
+                                                                </div>
+                                                            )}
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.actualCost')}</dt>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.actualCost')}
+                                                                </dt>
                                                                 <dd className='text-foreground font-medium'>
                                                                     {formatActualCostLabel(
                                                                         item,
@@ -704,29 +1182,52 @@ function HistoryPanelImpl({
                                                                 </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.totalEstimatedCost')}</dt>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.totalEstimatedCost')}
+                                                                </dt>
                                                                 <dd className='text-foreground font-medium'>
-                                                                    {item.costDetails ? `$${item.costDetails.estimated_cost_usd.toFixed(4)}` : '-'}
+                                                                    {item.costDetails
+                                                                        ? `$${item.costDetails.estimated_cost_usd.toFixed(4)}`
+                                                                        : '-'}
                                                                 </dd>
                                                             </div>
                                                         </dl>
-                                                        <dl className='space-y-2 rounded-md border border-border bg-card/70 p-3 text-sm'>
+                                                        {isFailedItem && (
+                                                            <div>
+                                                                <p className='mb-1 text-sm font-medium'>
+                                                                    {t('history.failureReason')}
+                                                                </p>
+                                                                <div className='border-destructive/25 bg-destructive/5 text-destructive max-h-[180px] overflow-y-auto rounded-md border p-3 text-sm break-words whitespace-pre-wrap'>
+                                                                    {failureMessage ||
+                                                                        t('history.failedReasonUnavailable')}
+                                                                </div>
+                                                            </div>
+                                                        )}
+                                                        <dl className='border-border bg-card/70 space-y-2 rounded-md border p-3 text-sm'>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.filename')}</dt>
-                                                                <dd className='text-foreground mt-1 break-all font-mono text-xs'>
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.filename')}
+                                                                </dt>
+                                                                <dd className='text-foreground mt-1 font-mono text-xs break-all'>
                                                                     {filenames.length > 0 ? filenames.join(', ') : '-'}
                                                                 </dd>
                                                             </div>
                                                             <div>
-                                                                <dt className='text-muted-foreground'>{t('history.requestId')}</dt>
-                                                                <dd className='text-foreground mt-1 break-all font-mono text-xs'>
-                                                                    {requestIds.length > 0 ? requestIds.join(', ') : '-'}
+                                                                <dt className='text-muted-foreground'>
+                                                                    {t('history.requestId')}
+                                                                </dt>
+                                                                <dd className='text-foreground mt-1 font-mono text-xs break-all'>
+                                                                    {requestIds.length > 0
+                                                                        ? requestIds.join(', ')
+                                                                        : '-'}
                                                                 </dd>
                                                             </div>
                                                         </dl>
                                                         <div>
-                                                            <p className='mb-1 text-sm font-medium'>{t('history.prompt')}</p>
-                                                            <div className='text-foreground bg-muted max-h-[320px] overflow-y-auto whitespace-pre-wrap break-words rounded-md border border-border p-3 py-4 text-sm'>
+                                                            <p className='mb-1 text-sm font-medium'>
+                                                                {t('history.prompt')}
+                                                            </p>
+                                                            <div className='text-foreground bg-muted border-border max-h-[320px] overflow-y-auto rounded-md border p-3 py-4 text-sm break-words whitespace-pre-wrap'>
                                                                 {item.prompt || t('history.noPrompt')}
                                                             </div>
                                                         </div>
@@ -750,7 +1251,7 @@ function HistoryPanelImpl({
                                                                 type='button'
                                                                 variant='secondary'
                                                                 size='sm'
-                                                                className='border border-transparent shadow-sm hover:border-border hover:bg-accent hover:text-accent-foreground active:scale-[0.98]'>
+                                                                className='hover:border-border hover:bg-accent hover:text-accent-foreground border border-transparent shadow-sm active:scale-[0.98]'>
                                                                 {t('common.close')}
                                                             </Button>
                                                         </DialogClose>
@@ -764,7 +1265,7 @@ function HistoryPanelImpl({
                                                 }}>
                                                 <DialogTrigger asChild>
                                                     <Button
-                                                        className='h-6 w-6 bg-red-700/60 text-white hover:bg-red-600/60'
+                                                        className='bg-destructive hover:bg-destructive/90 h-6 w-6 text-white'
                                                         onClick={(e) => {
                                                             e.stopPropagation();
                                                             onDeleteItemRequest(item);
@@ -775,9 +1276,7 @@ function HistoryPanelImpl({
                                                 </DialogTrigger>
                                                 <DialogContent className='sm:max-w-md'>
                                                     <DialogHeader>
-                                                        <DialogTitle>
-                                                            {t('history.confirmDeletion')}
-                                                        </DialogTitle>
+                                                        <DialogTitle>{t('history.confirmDeletion')}</DialogTitle>
                                                         <DialogDescription className='pt-2'>
                                                             {t('history.confirmDeletionDescription', {
                                                                 count: item.images.length
@@ -800,10 +1299,18 @@ function HistoryPanelImpl({
                                                         </label>
                                                     </div>
                                                     <DialogFooter className='gap-2 sm:justify-end'>
-                                                        <Button type='button' variant='outline' size='sm' onClick={onCancelDeletion}>
+                                                        <Button
+                                                            type='button'
+                                                            variant='outline'
+                                                            size='sm'
+                                                            onClick={onCancelDeletion}>
                                                             {t('common.cancel')}
                                                         </Button>
-                                                        <Button type='button' variant='destructive' size='sm' onClick={onConfirmDeletion}>
+                                                        <Button
+                                                            type='button'
+                                                            variant='destructive'
+                                                            size='sm'
+                                                            onClick={onConfirmDeletion}>
                                                             {t('common.delete')}
                                                         </Button>
                                                     </DialogFooter>
@@ -817,6 +1324,17 @@ function HistoryPanelImpl({
                     </div>
                 )}
             </CardContent>
+            <ActivityTimeline
+                activityItems={activityItems}
+                history={history}
+                pendingActivityItems={pendingActivityItems}
+                onSelectImage={onSelectImage}
+                onClearHistory={onClearHistory}
+                getImageSrc={getImageSrc}
+                formatStatusTime={formatStatusTime}
+                formatDuration={formatDuration}
+                t={t}
+            />
         </Card>
     );
 }