Deploy e9050df to Docker Space

Source: MisonL/gpt-image-playground-customer@e9050df6c33f04cecaad6d1fcd2c7714a262bb12

README.md

@@ -91,23 +91,23 @@ start-windows.bat
 
 完整配置说明见 [.env.example](./.env.example)。README 只列常用项。
 
-| 场景 | 变量 | 说明 |
-| --- | --- | --- |
-| 默认上游 | `OPENAI_API_KEY`、`OPENAI_API_BASE_URL` | 服务端默认 OpenAI 或兼容接口配置。页面 `API 设置` 优先级更高。 |
-| 页面访问码 | `APP_PASSWORD` | 设置后访问页面和受保护图片需要访问码。公网部署建议开启。 |
-| Agent 鉴权 | `AGENT_API_TOKEN` | 设置后 `/api/agent/*` 需要 Bearer token。 |
-| Agent 公开地址 | `AGENT_PUBLIC_BASE_URL` | OpenAPI `servers[0].url` 和 Agent artifact 分享外链使用的公网 base URL。 |
-| 图片存储 | `NEXT_PUBLIC_IMAGE_STORAGE_MODE` | `fs` 或 `indexeddb`。Docker 默认使用 `fs`。 |
-| Agent 状态 | `AGENT_STATE_BACKEND` | `memory`、`sqlite` 或 `postgres`。Docker 默认使用 `sqlite`。 |
-| 默认后端 | `IMAGE_GENERATION_BACKEND` | 默认 `images-api`；可设为 `responses-image-generation`。 |
-| Responses 顶层模型 | `OPENAI_RESPONSES_API_MODEL` | 仅在 `responses-image-generation` 后端生效；作为 `/responses` 的顶层 `model`，例如 `gpt-5.4`。 |
-| 流式策略 | `IMAGE_STREAMING_STRATEGY` | 默认 `auto`；可设为 `off`、`openai-sse`、`responses-sse` 等。 |
-| 渠道请求方式 | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES` | 可选。声明全局或单渠道可用方式；未配置时默认只允许 `images-non-stream`。每个渠道只保留真实 smoke 通过且能被本服务消费的模式，结果必须是内联 `b64_json`、Responses `result` 或同源 artifact URL。新上游若 `/v1/responses` 返回 `403 Image generation is not enabled for this group`，就不要把 `responses-non-stream`、`responses-sse` 放进该渠道白名单。 |
-| 并发容量 | `OPENAI_MAX_STREAMS_PER_CREDENTIAL` | 单个渠道凭证允许同时执行的图片请求数，默认 `1`。 |
-| 渠道队列 | `OPENAI_CHANNEL_QUEUE_ENABLED`、`OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS`、`OPENAI_CHANNEL_QUEUE_MAX_SIZE` | 控制超出凭证容量时等待还是立即失败。 |
-| 失败冷却 | `OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED`、`OPENAI_CHANNEL_FAILURE_COOLDOWN_MS` | 控制失败渠道、凭证或已识别请求方式是否临时移出路由池。 |
-| 上游超时 | `IMAGE_UPSTREAM_TIMEOUT_MS`、`IMAGE_STREAM_DATA_INTERVAL_TIMEOUT_MS`、`IMAGE_UPSTREAM_MAX_RETRIES` | 默认按长耗时图片请求处理，SDK 自动重试默认关闭。 |
-| 日志窗口 | `APP_LOG_LEVEL`、`APP_LOG_MAX_ENTRIES` | 控制服务端日志等级和 Agent 诊断可回溯窗口。 |
+| 场景               | 变量                                                                                                | 说明                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 默认上游           | `OPENAI_API_KEY`、`OPENAI_API_BASE_URL`                                                             | 服务端默认 OpenAI 或兼容接口配置。页面 `API 设置` 优先级更高。                                                                                                                                                                                                                                                                                          |
+| 页面访问码         | `APP_PASSWORD`                                                                                      | 设置后访问页面和受保护图片需要访问码。公网部署建议开启。                                                                                                                                                                                                                                                                                                |
+| Agent 鉴权         | `AGENT_API_TOKEN`                                                                                   | 设置后 `/api/agent/*` 需要 Bearer token。                                                                                                                                                                                                                                                                                                               |
+| Agent 公开地址     | `AGENT_PUBLIC_BASE_URL`                                                                             | OpenAPI `servers[0].url` 和 Agent artifact 分享外链使用的公网 base URL。                                                                                                                                                                                                                                                                                |
+| 图片存储           | `NEXT_PUBLIC_IMAGE_STORAGE_MODE`                                                                    | `fs` 或 `indexeddb`。Docker 默认使用 `fs`。                                                                                                                                                                                                                                                                                                             |
+| Agent 状态         | `AGENT_STATE_BACKEND`                                                                               | `memory`、`sqlite` 或 `postgres`。Docker 默认使用 `sqlite`。                                                                                                                                                                                                                                                                                            |
+| 默认后端           | `IMAGE_GENERATION_BACKEND`                                                                          | 默认 `images-api`；可设为 `responses-image-generation`。                                                                                                                                                                                                                                                                                                |
+| Responses 顶层模型 | `OPENAI_RESPONSES_API_MODEL`                                                                        | 仅在 `responses-image-generation` 后端生效；作为 `/responses` 的顶层 `model`，例如 `gpt-5.4`。                                                                                                                                                                                                                                                          |
+| 流式策略           | `IMAGE_STREAMING_STRATEGY`                                                                          | 默认 `auto`；可设为 `off`、`openai-sse`、`responses-sse` 等。                                                                                                                                                                                                                                                                                           |
+| 渠道请求方式       | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`                                   | 可选。声明全局或单渠道可用方式；未配置时默认只允许 `images-non-stream`。每个渠道只保留真实 smoke 通过且能被本服务消费的模式，结果必须是内联 `b64_json`、Responses `result` 或同源 artifact URL。新上游若 `/v1/responses` 返回 `403 Image generation is not enabled for this group`，就不要把 `responses-non-stream`、`responses-sse` 放进该渠道白名单。 |
+| 并发容量           | `OPENAI_MAX_STREAMS_PER_CREDENTIAL`                                                                 | 单个渠道凭证允许同时执行的图片请求数，默认 `1`。                                                                                                                                                                                                                                                                                                        |
+| 渠道队列           | `OPENAI_CHANNEL_QUEUE_ENABLED`、`OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS`、`OPENAI_CHANNEL_QUEUE_MAX_SIZE` | 控制超出凭证容量时等待还是立即失败。                                                                                                                                                                                                                                                                                                                    |
+| 失败冷却           | `OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED`、`OPENAI_CHANNEL_FAILURE_COOLDOWN_MS`                     | 控制失败渠道、凭证或已识别请求方式是否临时移出路由池。                                                                                                                                                                                                                                                                                                  |
+| 上游超时           | `IMAGE_UPSTREAM_TIMEOUT_MS`、`IMAGE_STREAM_DATA_INTERVAL_TIMEOUT_MS`、`IMAGE_UPSTREAM_MAX_RETRIES`  | 默认按长耗时图片请求处理，SDK 自动重试默认关闭。                                                                                                                                                                                                                                                                                                        |
+| 日志窗口           | `APP_LOG_LEVEL`、`APP_LOG_MAX_ENTRIES`                                                              | 控制服务端日志等级和 Agent 诊断可回溯窗口。                                                                                                                                                                                                                                                                                                             |
 
 多渠道示例：
 
@@ -154,19 +154,19 @@ Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先
 
 常用入口：
 
-| 接口 | 用途 |
-| --- | --- |
-| `GET /api/agent/capabilities` | 查询模型、限制、认证方式和路由规则。 |
-| `GET /api/agent/openapi.json` | 获取 OpenAPI 描述。 |
-| `POST /api/agent/images/generate` | JSON 文生图（显式 Agent / 诊断）。 |
-| `POST /api/agent/images/edit` | multipart 图片编辑，支持源图和 mask。 |
-| `POST /api/agent/jobs/images/generate` | 创建文生图 job。 |
-| `GET /api/agent/jobs/{id}` | 查询 job 状态。 |
-| `GET /api/agent/jobs/{id}/result` | 读取成功 job 的标准图片响应。 |
-| `GET /api/agent/artifacts/{id}/content` | 下载产物图片。 |
-| `POST /api/agent/artifacts/{id}/share` | 为产物创建浏览器可访问的分享链接。 |
-| `POST /api/agent/diagnostics/page-requests` | 批量读取页面请求的脱敏日志诊断摘要。 |
-| `GET /api/agent/diagnostics/requests` | 按 request id 或幂等键查询诊断。 |
+| 接口                                        | 用途                                  |
+| ------------------------------------------- | ------------------------------------- |
+| `GET /api/agent/capabilities`               | 查询模型、限制、认证方式和路由规则。  |
+| `GET /api/agent/openapi.json`               | 获取 OpenAPI 描述。                   |
+| `POST /api/agent/images/generate`           | JSON 文生图（显式 Agent / 诊断）。    |
+| `POST /api/agent/images/edit`               | multipart 图片编辑，支持源图和 mask。 |
+| `POST /api/agent/jobs/images/generate`      | 创建文生图 job。                      |
+| `GET /api/agent/jobs/{id}`                  | 查询 job 状态。                       |
+| `GET /api/agent/jobs/{id}/result`           | 读取成功 job 的标准图片响应。         |
+| `GET /api/agent/artifacts/{id}/content`     | 下载产物图片。                        |
+| `POST /api/agent/artifacts/{id}/share`      | 为产物创建浏览器可访问的分享链接。    |
+| `POST /api/agent/diagnostics/page-requests` | 批量读取页面请求的脱敏日志诊断摘要。  |
+| `GET /api/agent/diagnostics/requests`       | 按 request id 或幂等键查询诊断。      |
 
 生成示例：
 
@@ -284,7 +284,7 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 - `GPT_IMAGE_AGENT_TOKEN` 只用于 `/api/agent/*`；页面 SSE `/api/images` 可能还需要 `GPT_IMAGE_APP_PASSWORD_HASH`。
 - 需要给用户浏览器访问图片时，不要公开原始 artifact 下载 URL。使用 `POST /api/agent/artifacts/{id}/share` 或 skill 的 `--share` 创建分享链接；创建动作需要 Agent 鉴权，返回的 `share_url` 使用随机分享 token，公开分享可直接打开，设置访问码的分享需要用户在分享页输入访问码。
 - dry-run 只验证本地请求构造；`verification_scope.mode=local_planning_only` 不是远端已可执行。需要只读读取远端 capabilities 和 runtime 时加 `--check-remote`，输出 `verification_scope.mode=remote_contract_and_local_planning`。远端合同检查用 `--contract-check`，真实执行必须加 `--allow-billable`。
-- 多张真实任务优先用 `batch-images.mjs`、`--manifest`、`--resume` 和 `--dimension-check`；不要手动并行启动多个单张脚本。需要并发时先看 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 和 `channelQueue.capacityPerCredential`。
+- 固定尺寸真实任务使用 `--dimension-check` 验收实际图片尺寸；单张生成、单张编辑和批量任务都会把尺寸偏差报告为结构化 `dimension_check_failed`，并保留产物 URL 与服务端选路摘要。多张真实任务优先用 `batch-images.mjs`、`--manifest`、`--resume` 和 `--dimension-check`；不要手动并行启动多个单张脚本。需要并发时先看 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 和 `channelQueue.capacityPerCredential`。
 - 选择 `responses-image-generation` 或兼容别名 `responses` 时，`partial_images` 必须优先按 `partial_images_by_backend["responses-image-generation"]` 校验，不能套用 Matsca Images API 的范围。
 - 页面 SSE 返回 503 或断流时，先用诊断脚本读取结构化摘要，再用新的幂等键显式选择备用路径。`page_sse_supported=true` 只是声明支持，不代表实测一定成功。Agent edit 输出格式和尺寸可能与页面 SSE 不完全一致，尺寸敏感任务必须重新校验或用 `--dimension-check`。
 - 排查环境配置时优先运行 `npm run env:summary`，不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。
@@ -320,11 +320,11 @@ npm run docker:cleanup-fixtures
 
 常见部署模式：
 
-| 模式 | 命令或配置 | 适用场景 |
-| --- | --- | --- |
-| SQLite | `docker-compose.yml` | 本地单实例和长期本地服务。 |
-| Memory | `docker-compose.yml` + `docker-compose.memory.yml` | Hugging Face Space 免费层或临时演示。 |
-| PostgreSQL | `docker-compose.yml` + `docker-compose.postgres.yml` | 高并发、多实例或集中状态库。 |
+| 模式       | 命令或配置                                           | 适用场景                              |
+| ---------- | ---------------------------------------------------- | ------------------------------------- |
+| SQLite     | `docker-compose.yml`                                 | 本地单实例和长期本地服务。            |
+| Memory     | `docker-compose.yml` + `docker-compose.memory.yml`   | Hugging Face Space 免费层或临时演示。 |
+| PostgreSQL | `docker-compose.yml` + `docker-compose.postgres.yml` | 高并发、多实例或集中状态库。          |
 
 图片默认保存在：
 
@@ -336,35 +336,35 @@ Hugging Face Space 免费层部署见 [docs/deployment/huggingface-space-free.md
 
 ## 常用命令
 
-| 命令 | 用途 |
-| --- | --- |
-| `npm run dev` | 启动本地开发服务，端口 `4783`。 |
-| `npm run build` | 执行生产构建。 |
-| `npm run start` | 启动 standalone 生产服务，需先执行 `npm run build`。 |
-| `npm test` | 运行全量测试。 |
-| `npm run test:postgres` | 运行真实 PostgreSQL gate。 |
-| `npm run lint` | 检查 `src/` 代码。 |
-| `npm run lint:scripts` | 检查仓库脚本和 skill 脚本语法。 |
-| `npm run version:check` | 检查版本、README badge 和 CHANGELOG 口径。 |
-| `npm run verify` | 运行提交前基线。 |
-| `npm run docker:cleanup-fixtures` | 清理遗留的整仓挂载 Docker fixture 容器。 |
-| `npm run first-run` | 首次配置就绪检查，默认中文摘要；加 `-- --json` 输出机器可读 JSON。 |
-| `npm run status` | 只读查看 git、Node、部署目标、Agent 摘要和真实 smoke 配置状态；不执行计费图片请求。 |
-| `npm run doctor` | 运行本机和部署诊断。 |
-| `npm run agent:doctor` | 非计费 Agent 分层诊断；支持 `-- --base-url <url>`。 |
-| `npm run deploy:space` | 上传干净 git HEAD 到固定 HF Space。 |
+| 命令                              | 用途                                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| `npm run dev`                     | 启动本地开发服务，端口 `4783`。                                                             |
+| `npm run build`                   | 执行生产构建。                                                                              |
+| `npm run start`                   | 启动 standalone 生产服务，需先执行 `npm run build`。                                        |
+| `npm test`                        | 运行默认单元和契约测试；本地上游 final gate 单独运行 `npm run smoke:image-upstream-local`。 |
+| `npm run test:postgres`           | 运行真实 PostgreSQL gate。                                                                  |
+| `npm run lint`                    | 检查 `src/` 代码。                                                                          |
+| `npm run lint:scripts`            | 检查仓库脚本和 skill 脚本语法。                                                             |
+| `npm run version:check`           | 检查版本、README badge 和 CHANGELOG 口径。                                                  |
+| `npm run verify`                  | 运行提交前基线。                                                                            |
+| `npm run docker:cleanup-fixtures` | 清理遗留的整仓挂载 Docker fixture 容器。                                                    |
+| `npm run first-run`               | 首次配置就绪检查，默认中文摘要；加 `-- --json` 输出机器可读 JSON。                          |
+| `npm run status`                  | 只读查看 git、Node、部署目标、Agent 摘要和真实 smoke 配置状态；不执行计费图片请求。         |
+| `npm run doctor`                  | 运行本机和部署诊断。                                                                        |
+| `npm run agent:doctor`            | 非计费 Agent 分层诊断；支��� `-- --base-url <url>`。                                         |
+| `npm run deploy:space`            | 上传干净 git HEAD 到固定 HF Space。                                                         |
 
 真实上游 smoke 默认不会触发计费；`npm run status` 只报告 `configuration_complete` 和 `smoke_state=not_run_by_status` 等配置口径。需要真实生图验证时必须显式传入 `--allow-billable`。
 
 ## 常见问题
 
-| 问题 | 处理 |
-| --- | --- |
-| 未检测到 Node.js | 安装 Node.js >=20.9.0。 |
-| 依赖安装失败 | 检查 npm 网络后重新执行 `npm install`。 |
-| API 返回 HTML | API URL 填成了网页或管理后台；应填写 OpenAI 兼容 `/v1` 根地址。 |
+| 问题             | 处理                                                                |
+| ---------------- | ------------------------------------------------------------------- |
+| 未检测到 Node.js | 安装 Node.js >=20.9.0。                                             |
+| 依赖安装失败     | 检查 npm 网络后重新执行 `npm install`。                             |
+| API 返回 HTML    | API URL 填成了网页或管理后台；应填写 OpenAI 兼容 `/v1` 根地址。     |
 | 提示需要 API Key | 在 `.env.local` 写入 `OPENAI_API_KEY`，或在页面 `API 设置` 中填写。 |
-| 端口被占用 | 默认端口是 `4783`，检查旧进程或旧容器。 |
+| 端口被占用       | 默认端口是 `4783`，检查旧进程或旧容器。                             |
 
 ## 文档
 

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "b908b02b1ca43bf88871a9ffb18a6bc9421263ad",
-  "created_at": "2026-07-03T18:03:10.848Z",
-  "deploy_id": "3662dde9-7453-4db4-872d-b86510c45633"
+  "local_sha": "e9050df6c33f04cecaad6d1fcd2c7714a262bb12",
+  "created_at": "2026-07-06T10:09:57.902Z",
+  "deploy_id": "572b33fc-af8f-417f-bc6f-70cf33b54c06"
 }

scripts/agent-doctor.mjs

@@ -1,16 +1,25 @@
 #!/usr/bin/env node
-
-import { fileURLToPath } from 'node:url';
-
-import { isMainModule, parseJsonPayload, pickFailureOutput, printJson, redactBaseUrl, runCommand } from './command-center-utils.mjs';
 import {
     loadPrivateAgentEnvFile,
     resolvePlaygroundBaseUrl
 } from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
 import { CHANNEL_REQUEST_MODES, CHANNEL_REQUEST_MODE_SMOKE_CASES } from '../src/lib/channel-request-mode-values.mjs';
+import {
+    isMainModule,
+    parseJsonPayload,
+    pickFailureOutput,
+    printJson,
+    redactBaseUrl,
+    runCommand
+} from './command-center-utils.mjs';
+import { fileURLToPath } from 'node:url';
 
-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 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 ORCHESTRATION_GENERATE_SMOKE_NAME = 'orchestration_generate_1k';
 const AGENT_GENERATE_SMOKE_NAME = 'agent_generate_1k';
@@ -40,7 +49,8 @@ function parseArgs(argv) {
         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 === '--timeout-ms')
+            parsed.timeoutMs = readPositiveInteger(readOptionValue(argv, (index += 1), arg), '--timeout-ms');
         else if (arg === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
         else if (arg === '--edit-image') parsed.editImage = readOptionValue(argv, (index += 1), arg);
         else throw new Error(`未知参数：${arg}`);
@@ -118,7 +128,8 @@ async function readJsonLayer(name, url, 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)}`);
+        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 };
@@ -425,11 +436,12 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
         }),
         responses_gpt2image_ready:
             capabilities.ok && runtime.ok
-                ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true &&
-                  runtime.body?.responsesImageBackend?.enabled === true
+                ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled ===
+                      true && runtime.body?.responsesImageBackend?.enabled === true
                 : false,
         responses_image_backend_declared_supported: capabilities.ok
-            ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.supported === true
+            ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.supported ===
+              true
             : false,
         billable_smoke: smoke.skipped ? 'skipped' : smoke.ok ? 'ok' : 'failed'
     };
@@ -445,7 +457,8 @@ function buildRuntimeEnvironmentSummary({ capabilities, runtime }) {
         orchestration_endpoint: capabilities?.orchestration?.endpoint || null,
         orchestration_transport_selection: capabilities?.orchestration?.transport_selection || null,
         request_mode_control_policy: capabilities?.request_mode_controls?.agent_client_policy || null,
-        request_mode_controls: runtime?.channelRouting?.requestModeControls || capabilities?.request_mode_controls || null,
+        request_mode_controls:
+            runtime?.channelRouting?.requestModeControls || capabilities?.request_mode_controls || null,
         runtime_strategy: runtime?.channelRouting?.strategy || null,
         effective_request_modes: readRequestModeList(runtime?.channelRouting?.effectiveRequestModes),
         streaming_batch_enabled: runtime?.streamingBatch?.enabled === true,
@@ -483,18 +496,172 @@ function buildRequestModeSummary({ capabilities, runtime, smoke }) {
     const supported = readRequestModeList(capabilities?.supported?.request_modes);
     const configured = readRequestModeList(runtime?.channelRouting?.configuredRequestModes);
     const effective = readRequestModeList(runtime?.channelRouting?.effectiveRequestModes);
+    const adminWhitelistByChannel = readCapabilitiesRequestModesByChannel(capabilities);
+    const effectiveByChannel = readRuntimeRequestModesByChannel(runtime);
+    const smokeSummary = Object.fromEntries(
+        CHANNEL_REQUEST_MODES.map((mode) => [mode, summarizeRequestModeSmoke(smoke, mode)])
+    );
+    const gaps = buildRequestModeGaps({
+        supported,
+        configured,
+        effective,
+        adminWhitelistByChannel,
+        effectiveByChannel,
+        smoke: smokeSummary
+    });
     return {
         supported,
         configured,
         effective,
-        admin_whitelist_by_channel: readCapabilitiesRequestModesByChannel(capabilities),
-        effective_by_channel: readRuntimeRequestModesByChannel(runtime),
-        smoke: Object.fromEntries(
-            CHANNEL_REQUEST_MODES.map((mode) => [mode, summarizeRequestModeSmoke(smoke, mode)])
-        )
+        admin_whitelist_by_channel: adminWhitelistByChannel,
+        effective_by_channel: effectiveByChannel,
+        smoke: smokeSummary,
+        gaps,
+        suggested_channel_env_key: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+        suggested_effective_value: buildSuggestedEffectiveRequestModes({ effective, smoke: smokeSummary }).join(','),
+        next_action: buildRequestModeNextAction({ effective, gaps, smoke: smokeSummary })
     };
 }
 
+function buildSuggestedEffectiveRequestModes({ effective, smoke }) {
+    if (Object.values(smoke).every((value) => value.state === 'skipped')) return effective;
+    return effective.filter((mode) => smoke[mode]?.state === 'passed');
+}
+
+function buildRequestModeGaps({
+    supported,
+    configured,
+    effective,
+    adminWhitelistByChannel,
+    effectiveByChannel,
+    smoke
+}) {
+    const supportedModes = Array.isArray(supported) ? supported : [];
+    const configuredModes = Array.isArray(configured) ? configured : [];
+    const effectiveModes = Array.isArray(effective) ? effective : [];
+    const adminChannels = normalizeRequestModeChannelEntries(adminWhitelistByChannel);
+    const effectiveChannels = normalizeRequestModeChannelEntries(effectiveByChannel);
+    const gaps = [];
+    if (effectiveModes.length === 0) {
+        gaps.push({
+            code: 'no_effective_request_modes',
+            severity: 'critical',
+            message: '当前服务没有可用上游请求方式；检查 OPENAI_CHANNEL_N_REQUEST_MODES、渠道健康和 API key。'
+        });
+    }
+    const unrecognizedModes = collectUnrecognizedRequestModes(
+        supportedModes,
+        configuredModes,
+        effectiveModes,
+        adminChannels.flatMap((channel) => channel.request_modes),
+        effectiveChannels.flatMap((channel) => channel.request_modes)
+    );
+    if (unrecognizedModes.length > 0) {
+        gaps.push({
+            code: 'unrecognized_request_modes',
+            severity: 'warning',
+            request_modes: unrecognizedModes,
+            message: '服务返回了当前 Agent 未识别的 request mode；升级 skill 或确认服务端模式名称。'
+        });
+    }
+    const unsupportedConfigured = configuredModes.filter((mode) => !supportedModes.includes(mode));
+    if (unsupportedConfigured.length > 0) {
+        gaps.push({
+            code: 'configured_unsupported_request_modes',
+            severity: 'warning',
+            request_modes: unsupportedConfigured,
+            message: '配置中包含服务不支持的 request mode。'
+        });
+    }
+    const configuredButIneffective = configuredModes.filter(
+        (mode) => supportedModes.includes(mode) && !effectiveModes.includes(mode)
+    );
+    if (configuredButIneffective.length > 0) {
+        gaps.push({
+            code: 'configured_request_modes_not_effective',
+            severity: 'warning',
+            request_modes: configuredButIneffective,
+            message: '部分已配置 request mode 没有在 runtime 生效；检查对应渠道 key、健康状态和白名单。'
+        });
+    }
+    const effectiveByChannelMap = new Map(
+        effectiveChannels.map((channel) => [channel.channel_id, channel.request_modes])
+    );
+    const channelsWithoutModes = [
+        ...adminChannels
+            .filter((channel) => channel.request_modes.length > 0)
+            .filter((channel) => (effectiveByChannelMap.get(channel.channel_id) || []).length === 0),
+        ...effectiveChannels.filter((channel) => channel.request_modes.length === 0)
+    ];
+    const uniqueChannelsWithoutModes = [
+        ...new Map(channelsWithoutModes.map((channel) => [channel.channel_id, channel])).values()
+    ];
+    if (uniqueChannelsWithoutModes.length > 0) {
+        gaps.push({
+            code: 'channels_without_effective_request_modes',
+            severity: 'warning',
+            channel_ids: uniqueChannelsWithoutModes.map((channel) => channel.channel_id),
+            message: '部分渠道没有生效 request mode。'
+        });
+    }
+    const failedSmokeModes = Object.entries(smoke)
+        .filter(([, value]) => value.state === 'failed')
+        .map(([mode]) => mode);
+    if (failedSmokeModes.length > 0) {
+        gaps.push({
+            code: 'request_mode_smoke_failed',
+            severity: 'critical',
+            request_modes: failedSmokeModes,
+            message: '真实 smoke 显示部分 request mode 不可用；不要写入渠道白名单。'
+        });
+    }
+    return gaps;
+}
+
+function normalizeRequestModeChannelEntries(value) {
+    if (!Array.isArray(value)) return [];
+    return value
+        .map((channel) => ({
+            channel_id: String(channel?.channel_id || ''),
+            request_modes: readRequestModeList(channel?.request_modes)
+        }))
+        .filter((channel) => channel.channel_id);
+}
+
+function collectUnrecognizedRequestModes(...modeLists) {
+    const unrecognized = [];
+    const seen = new Set();
+    for (const modes of modeLists) {
+        if (!Array.isArray(modes)) continue;
+        for (const mode of modes) {
+            if (CHANNEL_REQUEST_MODES.includes(mode) || seen.has(mode)) continue;
+            seen.add(mode);
+            unrecognized.push(mode);
+        }
+    }
+    return unrecognized;
+}
+
+function buildRequestModeNextAction({ effective, gaps, smoke }) {
+    if (effective.length === 0) {
+        return '先用 probe-upstream-image.mjs 或 npm run smoke:image-upstream-real -- --allow-billable 探测上游，再配置 OPENAI_CHANNEL_N_REQUEST_MODES。';
+    }
+    if (gaps.some((gap) => gap.code === 'request_mode_smoke_failed')) {
+        return '从 OPENAI_CHANNEL_N_REQUEST_MODES 移除 smoke 失败的 request mode，只保留通过的模式。';
+    }
+    if (
+        gaps.some((gap) =>
+            ['configured_request_modes_not_effective', 'channels_without_effective_request_modes'].includes(gap.code)
+        )
+    ) {
+        return '先修正未生效的渠道 request mode、API key 或健康状态，再用 --allow-billable smoke 验证真实可用性。';
+    }
+    if (Object.values(smoke).every((value) => value.state === 'skipped')) {
+        return '当前只验证了配置可见性；真实渠道可用性需要显式 --allow-billable smoke。';
+    }
+    return '当前 request mode 配置可见；以 effective 和 smoke passed 的交集作为管理员白名单候选。';
+}
+
 function summarizeRequestModeSmoke(smoke, mode) {
     const checks = CHANNEL_REQUEST_MODE_SMOKE_CASES[mode] || [];
     if (checks.length === 0) {
@@ -516,30 +683,43 @@ function readCapabilitiesRequestModesByChannel(body) {
     const channels = Array.isArray(body?.upstream_request_headers?.channels)
         ? body.upstream_request_headers.channels
         : [];
-    return channels.map((channel) => ({
-        channel_id: String(channel?.id || ''),
-        request_modes: readRequestModeList(channel?.request_modes)
-    })).filter((channel) => channel.channel_id);
+    return channels
+        .map((channel) => ({
+            channel_id: String(channel?.id || ''),
+            request_modes: readRequestModeList(channel?.request_modes)
+        }))
+        .filter((channel) => channel.channel_id);
 }
 
 function readRuntimeRequestModesByChannel(body) {
     const channels = Array.isArray(body?.channelRouting?.effectiveRequestModesByChannel)
         ? body.channelRouting.effectiveRequestModesByChannel
         : [];
-    return channels.map((channel) => ({
-        channel_id: String(channel?.channelId || ''),
-        request_modes: readRequestModeList(channel?.requestModes)
-    })).filter((channel) => channel.channel_id);
+    return channels
+        .map((channel) => ({
+            channel_id: String(channel?.channelId || ''),
+            request_modes: readRequestModeList(channel?.requestModes)
+        }))
+        .filter((channel) => channel.channel_id);
 }
 
 function readRequestModeList(value) {
     if (!Array.isArray(value)) return [];
-    return CHANNEL_REQUEST_MODES.filter((mode) => value.includes(mode));
+    const modes = [];
+    const seen = new Set();
+    for (const item of value) {
+        const mode = typeof item === 'string' ? item.trim() : '';
+        if (!mode || seen.has(mode)) continue;
+        seen.add(mode);
+        modes.push(mode);
+    }
+    return modes;
 }
 
 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 };
+    if (process.env.GPT_IMAGE_APP_PASSWORD_HASH)
+        return { 'X-App-Password-Hash': process.env.GPT_IMAGE_APP_PASSWORD_HASH };
     return {};
 }
 
@@ -557,7 +737,9 @@ function readPositiveInteger(value, name) {
 }
 
 function normalizeBaseUrl(value) {
-    const normalized = String(value || '').trim().replace(/\/+$/, '');
+    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.');

scripts/command-center.test.mjs

@@ -1,13 +1,4 @@
-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';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-
 import { buildAgentDoctorArgs, buildAgentDoctorContractArgs } from './agent-doctor.mjs';
-import { fetchJsonWithTimeout, parseJsonPayload, pickFailureOutput, runCommand } from './command-center-utils.mjs';
 import {
     buildAbsentReport,
     buildSkippedReport,
@@ -15,6 +6,8 @@ import {
     parseDockerInspectContainer,
     summarizeDockerMounts
 } from './cleanup-docker-fixtures.mjs';
+import { fetchJsonWithTimeout, parseJsonPayload, pickFailureOutput, runCommand } from './command-center-utils.mjs';
+import { assertLocalProbeMatchesMode, buildDockerComposeArgs, buildDockerComposeEnv } from './deploy-local.mjs';
 import { buildFirstRunReport, formatFirstRunText } from './first-run.mjs';
 import {
     buildAdminCommands,
@@ -24,8 +17,14 @@ import {
     readStatusEnvFromFiles,
     readRemoteStatusFromResult
 } from './status.mjs';
-import { assertLocalProbeMatchesMode, buildDockerComposeArgs, buildDockerComposeEnv } from './deploy-local.mjs';
 import { buildVerifyPlan } from './verify.mjs';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
 
 describe('Command center scripts', () => {
     it('exposes a small stable administrator command set', () => {
@@ -600,9 +599,18 @@ describe('Command center scripts', () => {
                         has_password_hash: false
                     });
                     assert.equal(report.service.ok, true);
-                    assert.equal(report.checks.find((check) => check.name === 'agent_auth_available_to_process').ok, true);
-                    assert.equal(report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').ok, false);
-                    assert.equal(report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').skipped, false);
+                    assert.equal(
+                        report.checks.find((check) => check.name === 'agent_auth_available_to_process').ok,
+                        true
+                    );
+                    assert.equal(
+                        report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').ok,
+                        false
+                    );
+                    assert.equal(
+                        report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').skipped,
+                        false
+                    );
                     assert.equal(
                         report.checks.find((check) => check.name === 'page_sse_auth_available_to_process')
                             .auth_in_private_env_file,
@@ -612,7 +620,10 @@ describe('Command center scripts', () => {
                     assert.equal(report.service.capabilities.page_sse_auth_form_field, 'passwordHash');
                     assert.equal(report.service.capabilities.page_sse_declared_supported, true);
                     assert.equal(report.service.capabilities.page_sse_real_smoke, 'not_run_by_first_run');
-                    assert.equal(report.service.capabilities.responses_image_backend_real_smoke, 'not_run_by_first_run');
+                    assert.equal(
+                        report.service.capabilities.responses_image_backend_real_smoke,
+                        'not_run_by_first_run'
+                    );
                     assert.deepEqual(report.service.capabilities.page_sse_real_smoke_status, {
                         state: 'not_run',
                         billable: false,
@@ -624,7 +635,10 @@ describe('Command center scripts', () => {
                         reason: 'first-run is non-billable and does not call Responses image generation'
                     });
                     assert.match(formatFirstRunText(report), /页面 SSE：声明支持，实测=未执行真实 smoke/);
-                    assert.match(formatFirstRunText(report), /Responses 后端：声明未支持，启用=否，实测=未执行真实 smoke/);
+                    assert.match(
+                        formatFirstRunText(report),
+                        /Responses 后端：声明未支持，启用=否，实测=未执行真实 smoke/
+                    );
                     assert.equal(
                         report.checks.find((check) => check.name === 'agent_auth_available_to_process')
                             .auth_in_private_env_file,
@@ -777,7 +791,10 @@ describe('Command center scripts', () => {
                     );
 
                     assert.equal(report.service_base_url, baseUrl);
-                    assert.equal(report.checks.find((check) => check.name === 'agent_auth_available_to_process').skipped, false);
+                    assert.equal(
+                        report.checks.find((check) => check.name === 'agent_auth_available_to_process').skipped,
+                        false
+                    );
                     assert.equal(report.checks.find((check) => check.name === 'service_reachable').status, 401);
                     assert.equal('runtime' in report.service, false);
                     assert.match(JSON.stringify(report.next_actions), /GPT_IMAGE_AGENT_TOKEN/);
@@ -824,6 +841,7 @@ describe('Command center scripts', () => {
                                 request_modes: [
                                     'images-non-stream',
                                     'images-sse',
+                                    'images-json',
                                     'responses-non-stream',
                                     'responses-sse'
                                 ],
@@ -960,11 +978,46 @@ describe('Command center scripts', () => {
                 assert.deepEqual(body.summary.request_modes.supported, [
                     'images-non-stream',
                     'images-sse',
+                    'images-json',
                     'responses-non-stream',
                     'responses-sse'
                 ]);
-                assert.deepEqual(body.summary.request_modes.configured, ['images-non-stream', 'images-sse', 'responses-sse']);
+                assert.deepEqual(body.summary.request_modes.configured, [
+                    'images-non-stream',
+                    'images-sse',
+                    'responses-sse'
+                ]);
                 assert.deepEqual(body.summary.request_modes.effective, ['images-non-stream', 'images-sse']);
+                assert.deepEqual(body.summary.request_modes.admin_whitelist_by_channel, [
+                    { channel_id: 'images', request_modes: ['images-non-stream', 'images-sse'] },
+                    { channel_id: 'responses', request_modes: ['responses-sse'] }
+                ]);
+                assert.deepEqual(body.summary.request_modes.effective_by_channel, [
+                    { channel_id: 'images', request_modes: ['images-non-stream', 'images-sse'] }
+                ]);
+                assert.deepEqual(body.summary.request_modes.gaps, [
+                    {
+                        code: 'unrecognized_request_modes',
+                        severity: 'warning',
+                        request_modes: ['images-json'],
+                        message: '服务返回了当前 Agent 未识别的 request mode；升级 skill 或确认服务端模式名称。'
+                    },
+                    {
+                        code: 'configured_request_modes_not_effective',
+                        severity: 'warning',
+                        request_modes: ['responses-sse'],
+                        message: '部分已配置 request mode 没有在 runtime 生效；检查对应渠道 key、健康状态和白名单。'
+                    },
+                    {
+                        code: 'channels_without_effective_request_modes',
+                        severity: 'warning',
+                        channel_ids: ['responses'],
+                        message: '部分渠道没有生效 request mode。'
+                    }
+                ]);
+                assert.equal(body.summary.request_modes.suggested_channel_env_key, 'OPENAI_CHANNEL_N_REQUEST_MODES');
+                assert.equal(body.summary.request_modes.suggested_effective_value, 'images-non-stream,images-sse');
+                assert.match(body.summary.request_modes.next_action, /先修正未生效的渠道 request mode/);
                 assert.deepEqual(body.summary.request_modes.smoke['responses-non-stream'].checks, [
                     'responses_agent_generate_1k'
                 ]);
@@ -1009,17 +1062,24 @@ describe('Command center scripts', () => {
                 assert.deepEqual(body.layers.find((layer) => layer.name === 'capabilities').request_modes_supported, [
                     'images-non-stream',
                     'images-sse',
+                    'images-json',
                     'responses-non-stream',
                     'responses-sse'
                 ]);
-                assert.deepEqual(body.layers.find((layer) => layer.name === 'runtime_backend').effective_request_modes, [
-                    'images-non-stream',
-                    'images-sse'
-                ]);
-                assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_declared_supported, true);
+                assert.deepEqual(
+                    body.layers.find((layer) => layer.name === 'runtime_backend').effective_request_modes,
+                    ['images-non-stream', 'images-sse']
+                );
+                assert.equal(
+                    body.layers.find((layer) => layer.name === 'capabilities').page_sse_declared_supported,
+                    true
+                );
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_required, true);
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_ready, false);
-                assert.equal(body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').declared_supported, true);
+                assert.equal(
+                    body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').declared_supported,
+                    true
+                );
                 assert.match(
                     body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').real_smoke_gate,
                     /gpt2image-responses-sse/
@@ -1271,6 +1331,7 @@ describe('Command center scripts', () => {
                             agent_jobs: { supported: true },
                             routing_rules: {},
                             supported: {
+                                request_modes: ['images-non-stream', 'responses-non-stream', 'responses-sse'],
                                 image_backend_requirements: {
                                     'responses-image-generation': {
                                         supported: true,
@@ -1278,6 +1339,18 @@ describe('Command center scripts', () => {
                                         missing_env: []
                                     }
                                 }
+                            },
+                            upstream_request_headers: {
+                                channels: [
+                                    {
+                                        id: 'images',
+                                        request_modes: ['images-non-stream']
+                                    },
+                                    {
+                                        id: 'responses',
+                                        request_modes: ['responses-non-stream', 'responses-sse']
+                                    }
+                                ]
                             }
                         })
                     );
@@ -1292,7 +1365,21 @@ describe('Command center scripts', () => {
                                 unavailableMarkScope: 'channel+backend+strategy+operation'
                             },
                             streamingBatch: { enabled: true },
-                            responsesImageBackend: { enabled: true, mode: 'experimental' }
+                            responsesImageBackend: { enabled: true, mode: 'experimental' },
+                            channelRouting: {
+                                configuredRequestModes: ['images-non-stream', 'responses-non-stream', 'responses-sse'],
+                                effectiveRequestModes: ['images-non-stream', 'responses-non-stream', 'responses-sse'],
+                                effectiveRequestModesByChannel: [
+                                    {
+                                        channelId: 'images',
+                                        requestModes: ['images-non-stream']
+                                    },
+                                    {
+                                        channelId: 'responses',
+                                        requestModes: ['responses-non-stream', 'responses-sse']
+                                    }
+                                ]
+                            }
                         })
                     );
                     return;
@@ -1405,6 +1492,24 @@ describe('Command center scripts', () => {
                 assert.equal(body.summary.request_modes.smoke['images-non-stream'].state, 'passed');
                 assert.equal(body.summary.request_modes.smoke['responses-non-stream'].state, 'passed');
                 assert.equal(body.summary.request_modes.smoke['responses-sse'].state, 'failed');
+                assert.deepEqual(body.summary.request_modes.effective, [
+                    'images-non-stream',
+                    'responses-non-stream',
+                    'responses-sse'
+                ]);
+                assert.equal(
+                    body.summary.request_modes.suggested_effective_value,
+                    'images-non-stream,responses-non-stream'
+                );
+                assert.deepEqual(
+                    body.summary.request_modes.gaps.find((gap) => gap.code === 'request_mode_smoke_failed'),
+                    {
+                        code: 'request_mode_smoke_failed',
+                        severity: 'critical',
+                        request_modes: ['responses-sse'],
+                        message: '真实 smoke 显示部分 request mode 不可用；不要写入渠道白名单。'
+                    }
+                );
                 assert.equal(body.summary.real_smoke_checks.page_sse_edit_2k, 'skipped');
                 const pageSseOutput = body.layers
                     .find((layer) => layer.name === 'billable_smoke')
@@ -1467,7 +1572,10 @@ describe('Command center scripts', () => {
     });
 
     it('preserves invalid URL fetch errors while building timeout diagnostics', async () => {
-        await assert.rejects(() => fetchJsonWithTimeout('not a url', { timeoutMs: 20 }), /Failed to parse URL|Invalid URL/i);
+        await assert.rejects(
+            () => fetchJsonWithTimeout('not a url', { timeoutMs: 20 }),
+            /Failed to parse URL|Invalid URL/i
+        );
     });
 
     it('includes a response snippet when HTTP probes return non-JSON bodies', async () => {

scripts/dimension-check.test.mjs

@@ -0,0 +1,307 @@
+import {
+    DimensionCheckError,
+    assertImageDimensions,
+    buildDimensionCheckFailureBody,
+    isDimensionCheckError,
+    parseExpectedDimensions,
+    sanitizeImageResponse
+} from '../skills/gpt-image-playground-agent/scripts/lib/dimension-check.mjs';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { test } from 'node:test';
+
+test('assertImageDimensions records dimensions for inline base64 images', async () => {
+    const response = {
+        images: [{ id: 'ok', b64_json: pngBase64(320, 240) }]
+    };
+
+    const checked = await assertImageDimensions({
+        response,
+        expected: { width: 320, height: 240 },
+        baseUrl: 'http://127.0.0.1:1',
+        authHeaders: {}
+    });
+
+    assert.deepEqual(checked.images[0].dimensions, { width: 320, height: 240 });
+    assert.equal(checked.images[0].b64_json, response.images[0].b64_json);
+});
+
+test('assertImageDimensions rejects mismatched dimensions with sanitized response', async () => {
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{ id: 'bad', b64_json: pngBase64(512, 512) }] },
+                expected: { width: 1024, height: 1024 },
+                baseUrl: 'http://127.0.0.1:1',
+                authHeaders: {}
+            }),
+        (error) => {
+            assert.equal(error instanceof DimensionCheckError, true);
+            assert.equal(error.code, 'dimension_check_failed');
+            assert.deepEqual(error.expectedDimensions, { width: 1024, height: 1024 });
+            assert.deepEqual(error.actualDimensions, { width: 512, height: 512 });
+            assert.equal(error.response.images[0].b64_json, undefined);
+            assert.equal(Object.prototype.hasOwnProperty.call(error.response.images[0], 'b64_json'), false);
+            assert.equal(error.response.images[0].b64_json_length, pngBase64(512, 512).length);
+            assert.deepEqual(error.response.images[0].dimensions, { width: 512, height: 512 });
+            return true;
+        }
+    );
+});
+
+test('assertImageDimensions rejects missing and empty image lists', async () => {
+    for (const response of [{}, { images: [] }]) {
+        await assert.rejects(
+            () =>
+                assertImageDimensions({
+                    response,
+                    expected: { width: 1024, height: 1024 },
+                    baseUrl: 'http://127.0.0.1:1',
+                    authHeaders: {}
+                }),
+            /响应中没有可验收的图片/
+        );
+    }
+});
+
+test('assertImageDimensions reads same-origin content URLs with auth headers', async () => {
+    const requests = [];
+    await withServer(
+        (request, response) => {
+            requests.push({ url: request.url, authorization: request.headers.authorization });
+            response.writeHead(200, { 'content-type': 'image/png' });
+            response.end(pngBuffer(640, 360));
+        },
+        async (baseUrl) => {
+            const checked = await assertImageDimensions({
+                response: { images: [{ id: 'url-image', content_url: '/artifact/url-image.png' }] },
+                expected: { width: 640, height: 360 },
+                baseUrl,
+                authHeaders: () => ({ Authorization: 'Bearer test-token' })
+            });
+
+            assert.deepEqual(checked.images[0].dimensions, { width: 640, height: 360 });
+            assert.equal(requests[0].url, '/artifact/url-image.png');
+            assert.equal(requests[0].authorization, 'Bearer test-token');
+        }
+    );
+});
+
+test('assertImageDimensions rejects path fields unless callers opt in explicitly', async () => {
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{ path: '/artifact/from-path.png' }] },
+                expected: { width: 1, height: 1 },
+                baseUrl: 'http://127.0.0.1:1',
+                authHeaders: {}
+            }),
+        /dimension-check 需要 b64_json 或 absolute_content_url 或 content_url/
+    );
+
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{}] },
+                expected: { width: 1, height: 1 },
+                baseUrl: 'http://127.0.0.1:1',
+                authHeaders: {},
+                readUrlFields: ['absolute_path', 'path']
+            }),
+        /dimension-check 需要 b64_json 或 absolute_path 或 path/
+    );
+});
+
+test('assertImageDimensions converts download failures and cross-origin URLs to dimension failures', async () => {
+    await withServer(
+        (_request, response) => {
+            response.writeHead(404, { 'content-type': 'application/json' });
+            response.end(JSON.stringify({ error: 'missing' }));
+        },
+        async (baseUrl) => {
+            await assert.rejects(
+                () =>
+                    assertImageDimensions({
+                        response: { images: [{ content_url: '/missing.png' }] },
+                        expected: { width: 1, height: 1 },
+                        baseUrl,
+                        authHeaders: {}
+                    }),
+                /下载产物失败，状态码 404/
+            );
+        }
+    );
+
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{ content_url: 'https://evil.example.test/image.png' }] },
+                expected: { width: 1, height: 1 },
+                baseUrl: 'https://space.example.test',
+                authHeaders: {}
+            }),
+        /不同 origin/
+    );
+
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{ absolute_content_url: 'https://evil.example.test/image.png' }] },
+                expected: { width: 1, height: 1 },
+                baseUrl: 'https://space.example.test',
+                authHeaders: {}
+            }),
+        /absolute_content_url 指向不同 origin/
+    );
+});
+
+test('assertImageDimensions times out stalled streamed downloads', async () => {
+    await withServer(
+        (_request, response) => {
+            response.writeHead(200, { 'content-type': 'image/png' });
+            response.write(pngBuffer(1, 1).subarray(0, 8));
+        },
+        async (baseUrl) => {
+            await assert.rejects(
+                () =>
+                    assertImageDimensions({
+                        response: { images: [{ content_url: '/stalled.png' }] },
+                        expected: { width: 1, height: 1 },
+                        baseUrl,
+                        authHeaders: {},
+                        timeoutMs: 25
+                    }),
+                /下载产物超时，已等待 25ms/
+            );
+        }
+    );
+});
+
+test('assertImageDimensions falls back to default URL fields for invalid readUrlFields', async () => {
+    await withServer(
+        (_request, response) => {
+            response.writeHead(200, { 'content-type': 'image/png' });
+            response.end(pngBuffer(16, 9));
+        },
+        async (baseUrl) => {
+            const checked = await assertImageDimensions({
+                response: { images: [{ content_url: '/default-field.png' }] },
+                expected: { width: 16, height: 9 },
+                baseUrl,
+                authHeaders: {},
+                readUrlFields: null
+            });
+
+            assert.deepEqual(checked.images[0].dimensions, { width: 16, height: 9 });
+        }
+    );
+});
+
+test('assertImageDimensions enforces the max image byte limit', async () => {
+    await assert.rejects(
+        () =>
+            assertImageDimensions({
+                response: { images: [{ b64_json: pngBase64(1, 1) }] },
+                expected: { width: 1, height: 1 },
+                baseUrl: 'http://127.0.0.1:1',
+                authHeaders: {},
+                maxImageBytes: 8
+            }),
+        /图片数据超过 8 字节限制/
+    );
+
+    await withServer(
+        (_request, response) => {
+            response.writeHead(200, {
+                'content-type': 'image/png',
+                'content-length': String(pngBuffer(1, 1).length)
+            });
+            response.end(pngBuffer(1, 1));
+        },
+        async (baseUrl) => {
+            await assert.rejects(
+                () =>
+                    assertImageDimensions({
+                        response: { images: [{ content_url: '/large.png' }] },
+                        expected: { width: 1, height: 1 },
+                        baseUrl,
+                        authHeaders: {},
+                        maxImageBytes: 8
+                    }),
+                /图片数据超过 8 字节限制/
+            );
+        }
+    );
+});
+
+test('dimension-check helpers expose stable structured failure bodies', () => {
+    const sanitized = sanitizeImageResponse({ images: [{ id: 'secret', b64_json: pngBase64(1, 1) }] });
+    assert.equal(sanitized.images[0].b64_json, undefined);
+    assert.equal(Object.prototype.hasOwnProperty.call(sanitized.images[0], 'b64_json'), false);
+    assert.equal(sanitized.images[0].b64_json_length, pngBase64(1, 1).length);
+    assert.deepEqual(parseExpectedDimensions('1024x768'), { width: 1024, height: 768 });
+    assert.equal(parseExpectedDimensions('auto'), undefined);
+    assert.equal(isDimensionCheckError(new Error('plain')), false);
+
+    const error = new DimensionCheckError('bad size', {
+        expected: { width: 10, height: 10 },
+        actual: { width: 8, height: 8 },
+        response: { images: [{ id: 'bad', b64_json: pngBase64(8, 8) }] },
+        nextStep: 'inspect'
+    });
+    const body = buildDimensionCheckFailureBody(error, { transport: 'agent_json' });
+    assert.equal(body.billable, true);
+    assert.equal(body.error.code, 'dimension_check_failed');
+    assert.deepEqual(body.error.expected_dimensions, { width: 10, height: 10 });
+    assert.deepEqual(body.error.actual_dimensions, { width: 8, height: 8 });
+    assert.equal(body.validation_failure_kind, 'generated_artifact_failed_dimension_check');
+    assert.deepEqual(body.routing, { transport: 'agent_json' });
+    assert.equal(body.response.images[0].b64_json, undefined);
+    assert.equal(Object.prototype.hasOwnProperty.call(body.response.images[0], 'b64_json'), false);
+    assert.equal(body.next_step, 'inspect');
+
+    const malformed = buildDimensionCheckFailureBody(
+        new DimensionCheckError('bad metadata', {
+            expected: { width: 'wide', height: 10 },
+            actual: { width: 8, height: 0 }
+        }),
+        undefined
+    );
+    assert.equal(malformed.error.expected_dimensions, null);
+    assert.equal(malformed.error.actual_dimensions, null);
+});
+
+function pngBase64(width, height) {
+    return pngBuffer(width, height).toString('base64');
+}
+
+function pngBuffer(width, height) {
+    const buffer = Buffer.alloc(24);
+    buffer[0] = 0x89;
+    buffer.write('PNG', 1, 'ascii');
+    buffer[4] = 0x0d;
+    buffer[5] = 0x0a;
+    buffer[6] = 0x1a;
+    buffer[7] = 0x0a;
+    buffer.writeUInt32BE(13, 8);
+    buffer.write('IHDR', 12, 'ascii');
+    buffer.writeUInt32BE(width, 16);
+    buffer.writeUInt32BE(height, 20);
+    return buffer;
+}
+
+async function withServer(handler, run) {
+    const server = createServer(handler);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    try {
+        await run(`http://127.0.0.1:${address.port}`);
+    } finally {
+        await new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        });
+    }
+}

scripts/image-dimensions.test.mjs

@@ -0,0 +1,121 @@
+import { readImageDimensions } from '../skills/gpt-image-playground-agent/scripts/lib/image-dimensions.mjs';
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+test('readImageDimensions reads PNG dimensions', () => {
+    assert.deepEqual(readImageDimensions(pngBuffer(3840, 2160)), { width: 3840, height: 2160 });
+});
+
+test('readImageDimensions reads JPEG dimensions', () => {
+    assert.deepEqual(readImageDimensions(jpegBuffer(1280, 720)), { width: 1280, height: 720 });
+});
+
+test('readImageDimensions reads progressive JPEG dimensions', () => {
+    assert.deepEqual(readImageDimensions(jpegBuffer(1600, 900, 0xc2)), { width: 1600, height: 900 });
+});
+
+test('readImageDimensions reads WebP VP8X dimensions', () => {
+    assert.deepEqual(readImageDimensions(webpVp8xBuffer(1024, 1024)), { width: 1024, height: 1024 });
+});
+
+test('readImageDimensions reads WebP VP8L dimensions', () => {
+    assert.deepEqual(readImageDimensions(webpVp8lBuffer(512, 768)), { width: 512, height: 768 });
+});
+
+test('readImageDimensions reads WebP VP8 dimensions', () => {
+    assert.deepEqual(readImageDimensions(webpVp8Buffer(640, 360)), { width: 640, height: 360 });
+});
+
+test('readImageDimensions rejects empty buffers', () => {
+    assert.throws(() => readImageDimensions(Buffer.alloc(0)), /图片数据为空/);
+});
+
+test('readImageDimensions rejects unknown formats', () => {
+    assert.throws(() => readImageDimensions(Buffer.from('not-an-image')), /无法识别图片格式/);
+});
+
+test('readImageDimensions rejects truncated PNG buffers', () => {
+    assert.throws(() => readImageDimensions(pngBuffer(1, 1).subarray(0, 16)), /PNG 图片数据截断/);
+});
+
+test('readImageDimensions rejects truncated JPEG buffers', () => {
+    assert.throws(() => readImageDimensions(Buffer.from([0xff, 0xd8, 0xff, 0xc0, 0x00])), /JPEG 图片数据截断/);
+});
+
+test('readImageDimensions rejects JPEG SOF segments without enough metadata for dimensions', () => {
+    assert.throws(() => readImageDimensions(jpegBuffer(1280, 720, 0xc0, 0x07)), /JPEG 图片数据截断/);
+});
+
+test('readImageDimensions rejects truncated WebP buffers', () => {
+    assert.throws(() => readImageDimensions(webpHeader('VP8X', 20)), /WebP 图片数据截断/);
+});
+
+function pngBuffer(width, height) {
+    const buffer = Buffer.alloc(24);
+    buffer[0] = 0x89;
+    buffer.write('PNG', 1, 'ascii');
+    buffer[4] = 0x0d;
+    buffer[5] = 0x0a;
+    buffer[6] = 0x1a;
+    buffer[7] = 0x0a;
+    buffer.writeUInt32BE(13, 8);
+    buffer.write('IHDR', 12, 'ascii');
+    buffer.writeUInt32BE(width, 16);
+    buffer.writeUInt32BE(height, 20);
+    return buffer;
+}
+
+function jpegBuffer(width, height, marker = 0xc0, length = 0x0b) {
+    return Buffer.from([
+        0xff,
+        0xd8,
+        0xff,
+        0xe0,
+        0x00,
+        0x04,
+        0x00,
+        0x00,
+        0xff,
+        marker,
+        0x00,
+        length,
+        0x08,
+        (height >> 8) & 0xff,
+        height & 0xff,
+        (width >> 8) & 0xff,
+        width & 0xff,
+        0x01,
+        0x01,
+        0x11,
+        0x00
+    ]);
+}
+
+function webpHeader(chunk, length) {
+    const buffer = Buffer.alloc(length);
+    buffer.write('RIFF', 0, 'ascii');
+    buffer.write('WEBP', 8, 'ascii');
+    buffer.write(chunk, 12, 'ascii');
+    return buffer;
+}
+
+function webpVp8xBuffer(width, height) {
+    const buffer = webpHeader('VP8X', 30);
+    buffer.writeUIntLE(width - 1, 24, 3);
+    buffer.writeUIntLE(height - 1, 27, 3);
+    return buffer;
+}
+
+function webpVp8lBuffer(width, height) {
+    const buffer = webpHeader('VP8L', 25);
+    const bits = ((height - 1) << 14) | (width - 1);
+    buffer.writeUInt32LE(bits, 21);
+    return buffer;
+}
+
+function webpVp8Buffer(width, height) {
+    const buffer = webpHeader('VP8 ', 30);
+    buffer.writeUInt16LE(width, 26);
+    buffer.writeUInt16LE(height, 28);
+    return buffer;
+}

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

@@ -6,65 +6,69 @@ 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));
 // The fixture gate covers several independent upstream modes; leave room for bounded accepted-task retry paths.
-const LOCAL_GATE_CASE_TIMEOUT_MS = '120000';
+const DEFAULT_LOCAL_GATE_CASE_TIMEOUT_MS = '120000';
+const LOCAL_GATE_CASE_TIMEOUT_MS =
+    process.env.LOCAL_IMAGE_UPSTREAM_GATE_TIMEOUT_MS || DEFAULT_LOCAL_GATE_CASE_TIMEOUT_MS;
+const RUN_LOCAL_FINAL_GATE = process.env.GPT_IMAGE_RUN_LOCAL_FINAL_GATE === '1';
 
 describe('local image upstream final gate smoke launcher', () => {
-    it('runs all independent upstream cases against the local fixture', () => {
-        const result = spawnSync(process.execPath, [scriptPath, '--timeout-ms', LOCAL_GATE_CASE_TIMEOUT_MS], {
-            cwd: repoRoot,
-            encoding: 'utf8'
-        });
+    it(
+        'runs all independent upstream cases against the local fixture',
+        {
+            skip: RUN_LOCAL_FINAL_GATE
+                ? false
+                : 'set GPT_IMAGE_RUN_LOCAL_FINAL_GATE=1 to run the local fixture final gate'
+        },
+        () => {
+            const result = spawnSync(process.execPath, [scriptPath, '--timeout-ms', LOCAL_GATE_CASE_TIMEOUT_MS], {
+                cwd: repoRoot,
+                encoding: 'utf8'
+            });
 
-        assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
-        assert.equal(result.stderr.trim(), '');
-        assert.doesNotMatch(result.stdout, /local-fixture-key/);
-        const report = JSON.parse(result.stdout);
-        assert.equal(report.ok, true);
-        assert.equal(report.local_fixture, true);
-        assert.equal(report.final_gate_satisfied, true);
-        assert.equal(report.independent_targets.configuration_complete, true);
-        assert.deepEqual(report.request_modes.passed, [
-            'images-non-stream',
-            'images-sse',
-            'responses-non-stream',
-            'responses-sse'
-        ]);
-        assert.equal(
-            report.suggested_channel_config,
-            'images-non-stream,images-sse,responses-non-stream,responses-sse'
-        );
-        assert.equal(report.results.length, 6);
-        assert.deepEqual(
-            report.results.map((item) => item.id),
-            [
-                'original-images-json',
-                'gaoren-images-sse',
-                'sub2api-images-sse',
-                'sub2api-responses-json',
-                'gpt2image-responses-sse',
-                'matsca-images-sse'
-            ]
-        );
-        assert.deepEqual(
-            report.results.map((item) => item.request_mode),
-            [
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.equal(result.stderr.trim(), '');
+            assert.doesNotMatch(result.stdout, /local-fixture-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, true);
+            assert.equal(report.local_fixture, true);
+            assert.equal(report.final_gate_satisfied, true);
+            assert.equal(report.independent_targets.configuration_complete, true);
+            assert.deepEqual(report.request_modes.passed, [
                 'images-non-stream',
                 'images-sse',
-                'images-sse',
                 'responses-non-stream',
-                'responses-sse',
-                'images-sse'
-            ]
-        );
-        assert.equal(
-            report.results.every((item) => item.status === 200),
-            true
-        );
-        assert.equal(
-            report.results.every((item) => item.first_b64_length === 92),
-            true
-        );
-    });
+                'responses-sse'
+            ]);
+            assert.equal(
+                report.suggested_channel_config,
+                'images-non-stream,images-sse,responses-non-stream,responses-sse'
+            );
+            assert.equal(report.results.length, 6);
+            assert.deepEqual(
+                report.results.map((item) => item.id),
+                [
+                    'original-images-json',
+                    'gaoren-images-sse',
+                    'sub2api-images-sse',
+                    'sub2api-responses-json',
+                    'gpt2image-responses-sse',
+                    'matsca-images-sse'
+                ]
+            );
+            assert.deepEqual(
+                report.results.map((item) => item.request_mode),
+                ['images-non-stream', 'images-sse', 'images-sse', 'responses-non-stream', 'responses-sse', 'images-sse']
+            );
+            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', () => {
         const result = spawnSync(process.execPath, [scriptPath, '--help'], {

scripts/smoke-image-upstream-real.mjs

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
+import { CHANNEL_REQUEST_MODES } from '../src/lib/channel-request-mode-values.mjs';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 
-import { CHANNEL_REQUEST_MODES } from '../src/lib/channel-request-mode-values.mjs';
-
 const originalEnv = { ...process.env };
 const CASES = [
     {
@@ -231,8 +230,12 @@ function buildRequestModeSummary(results) {
     const modes = Object.fromEntries(
         CHANNEL_REQUEST_MODES.map((mode) => {
             const cases = results.filter((item) => item.request_mode === mode);
-            const passedCases = cases.filter((item) => item.ok === true && item.skipped !== true && item.blocked !== true);
-            const failedCases = cases.filter((item) => item.ok !== true && item.skipped !== true && item.blocked !== true);
+            const passedCases = cases.filter(
+                (item) => item.ok === true && item.skipped !== true && item.blocked !== true
+            );
+            const failedCases = cases.filter(
+                (item) => item.ok !== true && item.skipped !== true && item.blocked !== true
+            );
             const skippedCases = cases.filter((item) => item.skipped === true);
             return [
                 mode,
@@ -432,7 +435,14 @@ async function runCase(loadRouteHandlersForBillable, testCase, preflight = {}) {
     const startedAt = Date.now();
     const abortController = new AbortController();
     return withCaseTimeout(
-        () => runBillableCaseAfterLoadingHandlers(loadRouteHandlersForBillable, testCase, target, startedAt, abortController.signal),
+        () =>
+            runBillableCaseAfterLoadingHandlers(
+                loadRouteHandlersForBillable,
+                testCase,
+                target,
+                startedAt,
+                abortController.signal
+            ),
         testCase,
         target,
         startedAt,
@@ -480,6 +490,7 @@ function withCaseTimeout(run, testCase, target, startedAt, abortController) {
         const timeout = setTimeout(() => {
             settled = true;
             abortController.abort();
+            clearTimeout(timeout);
             resolve({
                 id: testCase.id,
                 request_mode: testCase.requestMode,

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

@@ -37,12 +37,12 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 
 执行决策表：
 
-| 场景 | Agent 输入 | 服务端职责 | 结果字段 |
-| --- | --- | --- | --- |
-| 普通文生图 | prompt、尺寸、质量等业务意图 | 通过 `orchestration.endpoint` 选择 Agent/job、渠道、Images/Responses、SSE/非流式 | `summary.transport`、`summary.route_mode`、`summary.channel_request_mode`、`summary.route_decision` |
-| 自动上游流式 | `stream_mode=auto` 或默认值 | 若 SSE 渠道不可用，可在服务端显式退到非流式并标记 fallback | `summary.channel_request_mode_fallback_applied=true` |
-| 显式流式诊断 | `stream_mode=stream` 或显式 `--page-sse` | 失败必须显式返回错误，不静默改成非流式 | `summary.route_decision.no_channel_reason` 或结构化错误 |
-| 管理员渠道白名单 | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES` | 只约束服务端可选渠道，不授权 Agent 客户端自选 endpoint | `capabilities.request_mode_controls`、`agent:doctor.summary.request_modes` |
+| 场景             | Agent 输入                                                        | 服务端职责                                                                       | 结果字段                                                                                            |
+| ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| 普通文生图       | prompt、尺寸、质量等业务意图                                      | 通过 `orchestration.endpoint` 选择 Agent/job、渠道、Images/Responses、SSE/非流式 | `summary.transport`、`summary.route_mode`、`summary.channel_request_mode`、`summary.route_decision` |
+| 自动上游流式     | `stream_mode=auto` 或默认值                                       | 若 SSE 渠道不可用，可在服务端显式退到非流式并标记 fallback                       | `summary.channel_request_mode_fallback_applied=true`                                                |
+| 显式流式诊断     | `stream_mode=stream` 或显式 `--page-sse`                          | 失败必须显式返回错误，不静默改成非流式                                           | `summary.route_decision.no_channel_reason` 或结构化错误                                             |
+| 管理员渠道白名单 | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES` | 只约束服务端可选渠道，不授权 Agent 客户端自选 endpoint                           | `capabilities.request_mode_controls`、`agent:doctor.summary.request_modes`                          |
 
 - 默认 WebP edit 使用页面端 `POST /api/images` form-data SSE 路径，因为 Agent edit 不接收输出格式字段。需要 Responses image_generation edit 时也必须使用页面 SSE，不要用 `--agent`。显式 `--agent` 才使用 `/api/agent/images/edit` Agent multipart 最终 JSON，输出格式固定为 Agent 契约；如果页面流式不可用或失败，先诊断结构化错误，再用新的 `Idempotency-Key` 显式决定是否用 Agent edit 对照。Agent edit 只是对照路径，不保证与页面 SSE 的输出格式和像素尺寸完全一致；尺寸敏感任务必须用 `--dimension-check` 或下载后校验。
 - `capabilities` 里声明的 `page_sse_supported=true`、`agent_streaming.upstream_sse.supported=true` 只表示路径被声明支持，不表示当前渠道每次实测都能成功；如果页面 SSE、Responses 路径或服务端编排入口返回 `503`、断流，或 `summary` 里 `selected_channel_id`、`upstream_host` 为空，先诊断结构化错误，再用新的 `Idempotency-Key` 显式选择诊断路径，不自动回退。
@@ -119,14 +119,14 @@ Authorization: Bearer <token>
 
 以下脚本都位于当前 Skill 目录的 `scripts/` 下。不要硬编码本机安装路径；由运行环境按当前 `SKILL.md` 所在目录解析脚本路径。
 
-- `scripts/generate-image.mjs`：文生图调用。默认 dry-run，不消耗额度；真实执行默认提交到服务端编排入口，必须添加 `--allow-billable` 才会真实生图。需要浏览器可直接打开的用户外链时添加 `--share`，可选 `--share-expires-minutes`；私密分享访问码从 `GPT_IMAGE_SHARE_ACCESS_CODE` 读取，不放进命令行参数。
-- `scripts/edit-image.mjs`：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。
+- `scripts/generate-image.mjs`：文生图调用。默认 dry-run，不消耗额度；真实执行默认提交到服务端编排入口，必须添加 `--allow-billable` 才会真实生图。固定尺寸任务可添加 `--dimension-check`，从内联图片或同源 artifact URL 读取 PNG/JPEG/WebP 尺寸并把上游尺寸偏差判为结构化验收失败。需要浏览���可直接打开的用户外链时添加 `--share`，可选 `--share-expires-minutes`；私密分享访问码从 `GPT_IMAGE_SHARE_ACCESS_CODE` 读取，不放进命令行参数。
+- `scripts/edit-image.mjs`：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。固定尺寸任务可添加 `--dimension-check`，脚本会从内联图片或同源 artifact URL 读取 PNG/JPEG/WebP 尺寸，并把上游尺寸偏差判为结构化验收失败。
 - `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/convert-image-format.mjs`：本地 PNG/JPEG/WebP 互转。默认输出 WebP，质量 `100`；JPEG 会把透明背景铺成白色，PNG/WebP 保留透明。
 - `scripts/diagnose-request.mjs`：按一个或多个页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断；支持读取批量 manifest 和 `--base-url`，不触发生图计费。
 - `scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
 
-生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 添加 `--check-remote` 后会只读查询 `/api/agent/capabilities` 和 `/api/runtime-capabilities`，输出 `verification_scope.mode=remote_contract_and_local_planning`，仍不会发送真实生图请求。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`share_urls`、`direct_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`，便于人工审查。
+生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 添加 `--check-remote` 后会只读查询 `/api/agent/capabilities` 和 `/api/runtime-capabilities`，输出 `verification_scope.mode=remote_contract_and_local_planning`，仍不会发送真实生图请求。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。单张生成、单张编辑和批量任务都支持 `--dimension-check`；批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`share_urls`、`direct_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `transport`、`endpoint`、`route_mode`、`channel_request_mode`、`route_decision`、`selected_channel_id`、`upstream_host`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；失败摘要的渠道与路由字段优先读取 `error.diagnostics`，没有对应诊断字段时才回退到响应里的 `execution`。尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions` 和服务端 `execution` 选路字段，便于人工审查。
 所有生成、编辑、批量和探针脚本在 dry-run 或真实请求前都会校验尺寸参数。`gpt-image-2` 支持 `auto` 或任意正整数 `WIDTHxHEIGHT`；默认 OpenAI-compatible 上游的更严格尺寸边界由服务端 profile 或真实上游显式报错。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。生成、页面编辑、批量页面 SSE 和上游探针默认请求 `output_format=webp`、`output_compression=100`；普通 Agent edit 不发送输出格式字段，输出格式固定为 Agent 契约。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
@@ -141,27 +141,27 @@ Authorization: Bearer <token>
 
 首次配置和诊断输出字段速查：
 
-| 字段 | 出现位置 | 判断口径 |
-| --- | --- | --- |
-| `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
-| `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
-| `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
-| `agent_auth_process.has_token` | `first-run --json` | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
-| `page_sse_auth_available_to_process` | `first-run --json` | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。 |
-| `summary.page_sse_auth_ready` | `agent:doctor` | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。 |
-| `page_sse_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 `/api/images` smoke；`state=not_run` 且 `billable=false` 表示它只是只读就绪检查。 |
-| `responses_image_backend_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。 |
-| `summary.page_sse_real_smoke` | `agent:doctor` | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。 |
-| `summary.orchestration_generate_smoke` | `agent:doctor` | `--allow-billable` 时默认 generate 主链 `/api/agent/image-requests` 的真实 smoke 状态；这是普通 generate 在 server-owned orchestration 下的主编排口径。 |
-| `summary.agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时显式 `--agent` 的 Agent JSON 文生图 smoke 状态；用于诊断直连 Agent JSON，不代表默认主链。 |
-| `summary.responses_page_sse_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.responses_agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `orchestration_generate_1k`、`agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
-| `summary.request_modes` | `agent:doctor` | 管理员 request mode 的配置和真实 smoke 摘要；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
-| `request_mode_controls` | `capabilities` | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate ��� `agent_client_policy=diagnostics_only`。 |
-| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
-| `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
-| `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
+| 字段                                                                                         | 出现位置                                                                                   | 判断口径                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `service_base_url` / `verification_scope.service_base_url`                                   | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。                                                                                                                                                                                                                                                                        |
+| `service_base_url_source` / `verification_scope.service_base_url_source`                     | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。                                                                                                                                                                                 |
+| `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。                                                                                                                                                                                                                                          |
+| `agent_auth_process.has_token`                                                               | `first-run --json`                                                                         | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。                                                                                                                                                                                                                                                                  |
+| `page_sse_auth_available_to_process`                                                         | `first-run --json`                                                                         | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。                                                                                                                                                                                                                      |
+| `summary.page_sse_auth_ready`                                                                | `agent:doctor`                                                                             | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。                                                                                                                                                                                                                                      |
+| `page_sse_real_smoke_status`                                                                 | `first-run --json`                                                                         | 结构化说明 `first-run` 未执行真实 `/api/images` smoke；`state=not_run` 且 `billable=false` 表示它只是只读就绪检查。                                                                                                                                                                                             |
+| `responses_image_backend_real_smoke_status`                                                  | `first-run --json`                                                                         | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。                                                                                                                                                                                                                |
+| `summary.page_sse_real_smoke`                                                                | `agent:doctor`                                                                             | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。                                                                                                                                        |
+| `summary.orchestration_generate_smoke`                                                       | `agent:doctor`                                                                             | `--allow-billable` 时默认 generate 主链 `/api/agent/image-requests` 的真实 smoke 状态；这是普通 generate 在 server-owned orchestration 下的主编排口径。                                                                                                                                                         |
+| `summary.agent_generate_smoke`                                                               | `agent:doctor`                                                                             | `--allow-billable` 时显式 `--agent` 的 Agent JSON 文生图 smoke 状态；用于诊断直连 Agent JSON，不代表默认主链。                                                                                                                                                                                                  |
+| `summary.responses_page_sse_generate_smoke`                                                  | `agent:doctor`                                                                             | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。                                                                                                                                                                       |
+| `summary.responses_agent_generate_smoke`                                                     | `agent:doctor`                                                                             | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。                                                                                                                                                              |
+| `summary.real_smoke_checks`                                                                  | `agent:doctor`                                                                             | 各真实 smoke 的状态汇总，包含 `orchestration_generate_1k`、`agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。                                                                                                                        |
+| `summary.request_modes`                                                                      | `agent:doctor`                                                                             | 管理员 request mode 的配置和真实 smoke 摘要，包含 `supported`、`configured`、`effective`、`admin_whitelist_by_channel`、`effective_by_channel`、带 `severity` 的 `gaps`、`suggested_channel_env_key`、`suggested_effective_value` 和 `next_action`；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
+| `request_mode_controls`                                                                      | `capabilities`                                                                             | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`。                                                                                                                                           |
+| `private_agent_env.exists`                                                                   | `first-run --json`                                                                         | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。                                                                                                                                                                                                                            |
+| `capabilities.ok`                                                                            | `first-run --json`、`agent:doctor`                                                         | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。                                                                                                                                                                                                                                 |
+| `diagnostics_retention`                                                                      | `diagnose-request.mjs`                                                                     | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。                                                                                                                                                                                                                                                        |
 
 生成脚本常用参数：
 
@@ -227,7 +227,7 @@ node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.sp
 node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.space --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`、响应或错误以及机器可读 `summary`；Agent JSON 失败时 manifest 也会记录只读诊断补采样得到的 `agent_failure_diagnostics`。`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。dry-run 不写 manifest，输出会声明 `manifest_written=false`、`manifest_write_reason=dry_run` 和 `guardrails`；真实执行应复用 dry-run 中的同一个 `--ordered-prefix`，否则未显式写 `idempotency_key` 的任务会生成不同 key。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`；通过时成功摘要写入 `image_dimensions` 和单图 `actual_dimensions`，失败时 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`summary.expected_dimensions`、`summary.actual_dimensions`、`summary.dimension_check_failed=true` 会同时写入 manifest。固定尺寸任务没有开启时，dry-run 会在 `guardrails.dimension_check_recommended` 中提示。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`failure_summary` 会区分 `validation_failure_count` 和 `request_failure_count`，避免把已生成但验收失败误判为上游调用失败。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存；即使 fetch 或 SSE 收集阶段失败，也会记录 `request_started`、`request_failed`、`elapsed_ms`、`client_request_id` 和 `endpoint`，便于区分上游未给终图和解析/断流问题。
+`--manifest` 使用 JSONL append-only 记录每条任务的 `index`、`id`、`idempotency_key`、`attempt`、`status`、响应或错误以及机器可读 `summary`；Agent JSON 失败时 manifest 也会记录只读诊断补采样得到的 `agent_failure_diagnostics`。`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。dry-run 不写 manifest，输出会声明 `manifest_written=false`、`manifest_write_reason=dry_run` 和 `guardrails`；真实执行应复用 dry-run 中的同一个 `--ordered-prefix`，否则未显式写 `idempotency_key` 的任务会生成不同 key。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `absolute_content_url`/`content_url`/`absolute_path`/`path`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`；通过时成功摘要写入 `image_dimensions` 和单图 `actual_dimensions`，失败时 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`summary.expected_dimensions`、`summary.actual_dimensions`、`summary.dimension_check_failed=true` 会同时写入 manifest。固定尺寸任务没有开启时，dry-run 会在 `guardrails.dimension_check_recommended` 中提示。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`failure_summary` 会区分 `validation_failure_count` 和 `request_failure_count`，避免把已生成但验收失败误判为上游调用失败。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存；即使 fetch 或 SSE 收集阶段失败，也会记录 `request_started`、`request_failed`、`elapsed_ms`、`client_request_id` 和 `endpoint`，便于区分上游未给终图和解析/断流问题。
 
 批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。批量 generate 默认提交到 `/api/agent/image-requests`，`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 会作为 generate 意图字段随 JSON 发送给服务端编排入口。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images` 和上述 Responses 控制字段仍可用于页面 SSE edit 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。
 

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

@@ -23,7 +23,7 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 生成、编辑、批量和上游诊断都应先使用这些内置脚本；不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现同一套 API 调用。
 
 - `scripts/generate-image.mjs`：JSON 文生图调用。
-- `scripts/edit-image.mjs`：multipart 编辑调用。
+- `scripts/edit-image.mjs`：multipart 编辑调用；固定尺寸任务可添加 `--dimension-check` 验收真实产物尺寸。
 - `scripts/batch-images.mjs`：JSONL 批量 generate/edit 调用。
 - `scripts/convert-image-format.mjs`：本地 PNG/JPEG/WebP 互转。
 - `scripts/diagnose-request.mjs`：按页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断，支持 `--base-url` 固定目标服务。
@@ -43,11 +43,12 @@ Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 se
 npm run env:summary
 npm run env:summary -- --file .env.local --container gpt-image-playground-customer
 ```
+
 当服务返回相对 `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`；默认 OpenAI-compatible 上游的更严格尺寸边界由服务端 profile 或真实上游显式报错。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。生成、页面编辑、批量和上游探针默认请求 `output_format=webp`、`output_compression=100`。
-真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`share_urls`、`direct_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。`transport` 表示 Agent 对外访问的服务端端点形态，`route_mode` 表示 Agent/job/page SSE 路径，`channel_request_mode` 表示服务端实际调用上游的 Images/Responses 与 SSE/非流式组合，`route_decision` 记录 requested backend、preferred/fallback/selected request mode、fallback 是否发生、选中渠道、上游 host 或 no-channel 原因。`share_urls` 只在显式 `--share` 后出现，用于给用户浏览器打开分享页；`direct_content_urls` 只在显式 `--share` 后出现，用于分享后的内容直链；公开分享可直接打开 `direct_content_urls`，设置访问码时优先给用户 `share_urls`；`content_urls` 仍是需要 Agent 鉴权的 artifact 下载路径。失败摘要也稳定包含空数组或 `null` 形式的产物、路由、渠道和尺寸字段，便于 subagent 按同一模板汇报；尺寸门禁失败属于“上游已生成但本地验收失败”，失败摘要会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`。失败摘要还包含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`。Agent JSON 失败时脚本会按幂等键只读查询 Agent state；若命中，会把 `request_id`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、`transport_error_kind` 合并进首次失败摘要，并输出 `agent_failure_diagnostics`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
+真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`share_urls`、`direct_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。`transport` 表示 Agent 对外访问的服务端端点形态，`route_mode` 表示 Agent/job/page SSE 路径，`channel_request_mode` 表示服务端实际调用上游的 Images/Responses 与 SSE/非流式组合，`route_decision` 记录 requested backend、preferred/fallback/selected request mode、fallback 是否发生、选中渠道、上游 host 或 no-channel 原因。`share_urls` 只在显式 `--share` 后出现，用于给用户浏览器打开分享页；`direct_content_urls` 只在显式 `--share` 后出现，用于分享后的内容直链；公开分享可直接打开 `direct_content_urls`，设置访问码时优先给用户 `share_urls`；`content_urls` 仍是需要 Agent 鉴权的 artifact 下载路径。失败摘要也稳定包含空数组或 `null` 形式的产物、路由、渠道和尺寸字段，便于 subagent 按同一模板汇报；尺寸门禁失败属于“上游已生成但本地验收失败”，失败摘要会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`。失败摘要还包含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；渠道与路由诊断优先读取 `error.diagnostics`，没有对应诊断字段时才回退到响应里的 `execution`。Agent JSON 失败时脚本会按幂等键只读查询 Agent state；若命中，会把 `request_id`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、`transport_error_kind` 合并进首次失败摘要，并输出 `agent_failure_diagnostics`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
 
 生成脚本参数：
 
@@ -68,6 +69,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--partial-images`：可选，显式设置上游 SSE partial image 数量。generate 或页面 SSE 请求包含 `image_backend` 时优先按 capabilities 的 `limits.partial_images_by_backend[image_backend]` 校验；缺少 backend 专属范围时才使用 `limits.partial_images`。
 - `--share`：真实生图成功后，为每个 Agent artifact 调用 `POST /api/agent/artifacts/{id}/share` 创建用户可打开的分享链接，并在顶层 `shares`、`summary.share_urls` 和 `summary.direct_content_urls` 输出结果。
 - `--share-expires-minutes`：可选，设置分享有效期分钟数；省略时使用服务端默认值。
+- `--dimension-check`：读取响应 `b64_json` 或同 origin `absolute_content_url`/`content_url`/`absolute_path`/`path`，校验 PNG/JPEG/WebP 尺寸等于 `--size`；通过时 summary 写入实际尺寸，失败时写入 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`expected_dimensions` 和 `actual_dimensions`。这个失败表示上游已生成但本地验收未通过，不等于上游请求失败。
 - `GPT_IMAGE_SHARE_ACCESS_CODE`：可选，创建需要访问码的分享链接；访问码不会出现在返回 URL 中，也不会出现在命令行参数里。
 - `--timeout-ms`：未显式指定时，脚本先用 `420000ms` 读取 capabilities；真实请求会采用 `420000ms` 与 `capabilities.image_transport.upstream_timeout_ms` 中较大的值。
 - `--prompt-file`：从文本文件读取 prompt。
@@ -103,6 +105,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--sse-log`
 - `--timeout-ms`
 - `--idempotency-key`
+- `--dimension-check`
 - `--page-sse`
 - `--agent`
 - `--dry-run`
@@ -110,7 +113,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 
 图片路径可以用位置参数 `<image-path> <prompt>`，也可以用 `--image <path> <prompt>`；两者不能同时设置。
 默认 WebP edit 走页面端 `/api/images` form-data SSE，因为 Agent edit 不接收输出格式字段。显式 `--format`、`--output-compression`、`--image-backend responses-image-generation`、页面高级字段或 `--page-sse` 也会走页面 SSE；失败后脚本输出结构化失败和备用端点建议，不会在同一次请求里静默二次调用。
-显式 `--page-sse` 会强制页面流式；显式 `--agent` 会走 Agent edit 最终 JSON。Agent edit 不接受 `image_backend`、`output_format` 或 `output_compression`；强制 Agent edit 时输出格式固定为 PNG，`partial_images` 按默认 Images API/profile 范围校验。Agent edit 只是页面 SSE 失败后的显式对照路径，不保证与页面 SSE 的输出格式和像素尺寸完全一致；尺寸敏感任务必须使用批量 `--dimension-check` 或下载后校验。Responses image_generation edit 必须走页面 SSE，可显式设置 `--page-sse --image-backend responses-image-generation --streaming-strategy responses-sse`。如果运行时已显式配置 `IMAGE_GENERATION_BACKEND=responses-image-generation` 或兼容别名 `responses`，且 `IMAGE_STREAMING_STRATEGY=responses-sse`，也可依赖服务端默认值；Docker compose 本身不设置这两个默认值，未配置 `.env.local` 时仍是 `images-api` 和 `auto`。默认 WebP edit 与 `stream_mode=non_stream` / `streaming_strategy=off` 冲突时脚本会前置拒绝；需要 Agent JSON 对照时必须显式添加 `--agent`，并使用新的 `Idempotency-Key`。
+显式 `--page-sse` 会强制页面流式；显式 `--agent` 会走 Agent edit 最终 JSON。Agent edit 不接受 `image_backend`、`output_format` 或 `output_compression`；强制 Agent edit 时输出格式固定为 PNG，`partial_images` 按默认 Images API/profile 范围校验。Agent edit 只是页面 SSE 失败后的显式对照路径，不保证与页面 SSE 的输出格式和像素尺寸完全一致；尺寸敏感任务必须使用生成/编辑/批量 `--dimension-check` 或下载后校验。编辑 `--dimension-check` 会读取响应 `b64_json` 或同 origin `content_url`，通过时在图片和 summary 写入实际尺寸，失败时输出结构化 `dimension_check_failed`、`generated_artifact_failed_dimension_check`、产物 URL 和服务端选路摘要。Responses image_generation edit 必须走页面 SSE，可显式设置 `--page-sse --image-backend responses-image-generation --streaming-strategy responses-sse`。如果运行时已显式配置 `IMAGE_GENERATION_BACKEND=responses-image-generation` 或兼容别名 `responses`，且 `IMAGE_STREAMING_STRATEGY=responses-sse`，也可依赖服务端默认值；Docker compose 本身不设置这两个默认值，未配置 `.env.local` 时仍是 `images-api` 和 `auto`。默认 WebP edit 与 `stream_mode=non_stream` / `streaming_strategy=off` 冲突时脚本会前置拒绝；需要 Agent JSON 对照时必须显式添加 `--agent`，并使用新的 `Idempotency-Key`。
 
 批量脚本参数：
 
@@ -118,7 +121,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--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`；通过时 summary 写入实际尺寸，失败时写入 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`expected_dimensions` 和 `actual_dimensions`。这个失败表示上游已生成但本地验收未通过，不等于上游请求失败。
+- `--dimension-check`：读取响应 `b64_json` 或同 origin `absolute_content_url`/`content_url`/`absolute_path`/`path`，校验 PNG/JPEG/WebP 尺寸等于任务 `size`；通过时 summary 写入实际尺寸，失败时写入 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`expected_dimensions` 和 `actual_dimensions`。这个失败表示上游已生成但本地验收未通过，不等于上游请求失败。
 - `--max-attempts`：失败任务最大尝试次数。第二次及后续尝试会追加新的 attempt 级 `Idempotency-Key`，避免复用终态失败 key。
 - `--concurrency`：并发执行窗口，默认 `1`。大于 `1` 时会先读取 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 和 `channelQueue.capacityPerCredential`，把有效并发限制到服务端建议值后按输入顺序输出结果；适合已确认渠道容量的批量生产。
 - `--max-consecutive-failures`：顺序执行下的连续失败熔断阈值，默认 `0` 表示不熔断。只能与 `--concurrency 1` 同用。
@@ -133,7 +136,15 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 Responses edit JSONL 正例：
 
 ```jsonl
-{"id":"edit-responses","mode":"edit","prompt":"replace the background","image_path":"source.png","image_backend":"responses-image-generation","streaming_strategy":"responses-sse","partial_images":1}
+{
+    "id": "edit-responses",
+    "mode": "edit",
+    "prompt": "replace the background",
+    "image_path": "source.png",
+    "image_backend": "responses-image-generation",
+    "streaming_strategy": "responses-sse",
+    "partial_images": 1
+}
 ```
 
 dry-run 预期：`routing.transport=page_sse`、`endpoint=/api/images`、`request.image_backend=responses-image-generation`。
@@ -141,7 +152,13 @@ dry-run 预期：`routing.transport=page_sse`、`endpoint=/api/images`、`reques
 缺少 `image_backend` 的反例：
 
 ```jsonl
-{"id":"edit-responses-missing-backend","mode":"edit","prompt":"replace the background","image_path":"source.png","responsesModel":"gpt-4.1"}
+{
+    "id": "edit-responses-missing-backend",
+    "mode": "edit",
+    "prompt": "replace the background",
+    "image_path": "source.png",
+    "responsesModel": "gpt-4.1"
+}
 ```
 
 dry-run 预期退出码为 `2`，错误包含 `responsesModel 必须同时设置 image_backend=responses-image-generation`。
@@ -229,6 +246,7 @@ GET /api/agent/capabilities
 - `GET /api/runtime-capabilities` 不属于 Agent capabilities。它是页面工作台读取的运行态能力摘要，用于展示流式默认值、图片上游传输配置、渠道健康、渠道队列、并发建议、Responses 后端 enablement 和缺失环境变量，不进入 Agent OpenAPI。
 
 新增 probe、diagnostics 或健康摘要时，先把机器契约放进 capabilities、OpenAPI 或明确的 Agent 只读端点，再让脚本消费这些字段；不要让脚本自己拼 page API、runtime API 和 Agent API 的边界逻辑。
+
 - `defaults.image_backend`：Agent generate 默认 `images-api`。
 - `defaults.stream_mode`：Agent generate 默认 `auto`。auto 会先尝试内部上游 SSE；无法产出最终图时显式回退并暴露可观测标记。
 - `defaults.streaming_strategy`：Agent generate 默认 `auto`。
@@ -265,18 +283,18 @@ Content-Type: application/json
 
 ```json
 {
-  "job": {
-    "id": "job-request-uuid",
-    "request_id": "job-request-uuid",
-    "idempotency_key": "stable-key",
-    "mode": "generate",
-    "state": "running",
-    "created_at": "2026-05-20T00:00:00.000Z",
-    "updated_at": "2026-05-20T00:00:00.000Z",
-    "expires_at": "2026-05-21T00:00:00.000Z",
-    "result_url": "/api/agent/jobs/job-request-uuid/result",
-    "retry_after_seconds": 5
-  }
+    "job": {
+        "id": "job-request-uuid",
+        "request_id": "job-request-uuid",
+        "idempotency_key": "stable-key",
+        "mode": "generate",
+        "state": "running",
+        "created_at": "2026-05-20T00:00:00.000Z",
+        "updated_at": "2026-05-20T00:00:00.000Z",
+        "expires_at": "2026-05-21T00:00:00.000Z",
+        "result_url": "/api/agent/jobs/job-request-uuid/result",
+        "retry_after_seconds": 5
+    }
 }
 ```
 
@@ -322,20 +340,20 @@ Content-Type: application/json
 
 ```json
 {
-  "prompt": "a product photo of a ceramic mug",
-  "model": "gpt-image-2",
-  "n": 1,
-  "size": "1024x1024",
-  "quality": "high",
-  "output_format": "webp",
-  "output_compression": 100,
-  "background": "auto",
-  "moderation": "auto",
-  "response_mode": "path",
-  "image_backend": "images-api",
-  "stream_mode": "auto",
-  "streaming_strategy": "auto",
-  "partial_images": 2
+    "prompt": "a product photo of a ceramic mug",
+    "model": "gpt-image-2",
+    "n": 1,
+    "size": "1024x1024",
+    "quality": "high",
+    "output_format": "webp",
+    "output_compression": 100,
+    "background": "auto",
+    "moderation": "auto",
+    "response_mode": "path",
+    "image_backend": "images-api",
+    "stream_mode": "auto",
+    "streaming_strategy": "auto",
+    "partial_images": 2
 }
 ```
 
@@ -353,47 +371,47 @@ Agent JSON 生成端点对外始终返回最终 JSON，不会对客户端返回
 
 ```json
 {
-  "request_id": "uuid",
-  "idempotency_key": "stable-key",
-  "cached": false,
-  "images": [
-    {
-      "id": "artifact-uuid",
-      "filename": "1715400000000-abcdef1234567890-0.webp",
-      "content_url": "/api/agent/artifacts/artifact-uuid/content",
-      "metadata_url": "/api/agent/artifacts/artifact-uuid",
-      "output_format": "webp",
-      "mime_type": "image/webp",
-      "size_bytes": 12345,
-      "width": 1024,
-      "height": 1024
-    }
-  ],
-  "usage": {},
-  "created_at": "2026-05-12T00:00:00.000Z",
-  "timing": {
-    "started_at": "2026-05-12T00:00:00.000Z",
-    "completed_at": "2026-05-12T00:01:04.000Z",
-    "elapsed_ms": 64000,
-    "server_elapsed_ms": 64000
-  },
-  "execution": {
-    "transport": "agent_job_polling",
-    "endpoint": "/api/agent/image-requests",
-    "route_mode": "job",
-    "operation": "generate",
-    "image_backend": "images-api",
-    "stream_mode": "non_stream",
-    "streaming_strategy": "off",
-    "selected_channel_id": "default",
-    "upstream_host": "api.example.test",
-    "request_headers": {
-      "user_agent_effective": "gpt-image-playground/2.1.0",
-      "has_extra_headers": false,
-      "allowed_header_names": ["user-agent", "x-app-id", "x-app-secret"],
-      "configured_header_names": []
+    "request_id": "uuid",
+    "idempotency_key": "stable-key",
+    "cached": false,
+    "images": [
+        {
+            "id": "artifact-uuid",
+            "filename": "1715400000000-abcdef1234567890-0.webp",
+            "content_url": "/api/agent/artifacts/artifact-uuid/content",
+            "metadata_url": "/api/agent/artifacts/artifact-uuid",
+            "output_format": "webp",
+            "mime_type": "image/webp",
+            "size_bytes": 12345,
+            "width": 1024,
+            "height": 1024
+        }
+    ],
+    "usage": {},
+    "created_at": "2026-05-12T00:00:00.000Z",
+    "timing": {
+        "started_at": "2026-05-12T00:00:00.000Z",
+        "completed_at": "2026-05-12T00:01:04.000Z",
+        "elapsed_ms": 64000,
+        "server_elapsed_ms": 64000
+    },
+    "execution": {
+        "transport": "agent_job_polling",
+        "endpoint": "/api/agent/image-requests",
+        "route_mode": "job",
+        "operation": "generate",
+        "image_backend": "images-api",
+        "stream_mode": "non_stream",
+        "streaming_strategy": "off",
+        "selected_channel_id": "default",
+        "upstream_host": "api.example.test",
+        "request_headers": {
+            "user_agent_effective": "gpt-image-playground/2.1.0",
+            "has_extra_headers": false,
+            "allowed_header_names": ["user-agent", "x-app-id", "x-app-secret"],
+            "configured_header_names": []
+        }
     }
-  }
 }
 ```
 
@@ -473,15 +491,15 @@ Agent request diagnostics 来自 Agent state 后端，适用于 `/api/agent/imag
 
 ```json
 {
-  "target": { "type": "page_request", "id": "stable-operation-key" },
-  "feedback": {
-    "target_type": "page_request",
-    "target_id": "stable-operation-key",
-    "value": "usable",
-    "source": "webui",
-    "updated_at": "2026-05-12T00:00:00.000Z",
-    "note": "approved"
-  }
+    "target": { "type": "page_request", "id": "stable-operation-key" },
+    "feedback": {
+        "target_type": "page_request",
+        "target_id": "stable-operation-key",
+        "value": "usable",
+        "source": "webui",
+        "updated_at": "2026-05-12T00:00:00.000Z",
+        "note": "approved"
+    }
 }
 ```
 
@@ -491,7 +509,7 @@ Agent request diagnostics 来自 Agent state 后端，适用于 `/api/agent/imag
 
 ```json
 {
-  "ids": ["stable-operation-key", "stable-operation-key-2"]
+    "ids": ["stable-operation-key", "stable-operation-key-2"]
 }
 ```
 
@@ -501,8 +519,8 @@ Agent request diagnostics 来自 Agent state 后端，适用于 `/api/agent/imag
 
 ```json
 {
-  "ids": ["stable-operation-key", "stable-operation-key-2"],
-  "filenames": ["output.png"]
+    "ids": ["stable-operation-key", "stable-operation-key-2"],
+    "filenames": ["output.png"]
 }
 ```
 
@@ -512,50 +530,42 @@ Agent request diagnostics 来自 Agent state 后端，适用于 `/api/agent/imag
 
 ```json
 {
-  "scope": {
-    "request_ids": ["stable-operation-key"],
-    "filenames": ["output.png"],
-    "filename_matched_request_ids": [],
-    "copy_text": "requestIds=stable-operation-key filename=output.png"
-  },
-  "matched_log_count": 0,
-  "events": [],
-  "diagnostics_retention": {
-    "storage": "bounded_local_jsonl",
-    "max_entries": 300,
-    "default_max_entries": 300,
-    "min_entries": 100,
-    "max_configured_entries": 5000,
-    "configured_by": "APP_LOG_MAX_ENTRIES",
-    "persisted_across_process_restart": true,
-    "loss_modes": [
-      "entry_evicted_by_max_entries",
-      "log_level_filter",
-      "local_log_file_missing_or_cleared"
-    ],
-    "bounded": true,
-    "not_agent_state_backend": true
-  },
-  "diagnostics_note": {
-    "code": "no_matching_logs_in_retention_window",
-    "message": "没有匹配到页面请求日志；诊断只覆盖最近 300 条本地应用日志，日志可能已被保留条数淘汰、被日志级别过滤，或本地日志文件被清理。",
-    "retention": {
-      "storage": "bounded_local_jsonl",
-      "max_entries": 300,
-      "default_max_entries": 300,
-      "min_entries": 100,
-      "max_configured_entries": 5000,
-      "configured_by": "APP_LOG_MAX_ENTRIES",
-      "persisted_across_process_restart": true,
-      "loss_modes": [
-        "entry_evicted_by_max_entries",
-        "log_level_filter",
-        "local_log_file_missing_or_cleared"
-      ],
-      "bounded": true,
-      "not_agent_state_backend": true
+    "scope": {
+        "request_ids": ["stable-operation-key"],
+        "filenames": ["output.png"],
+        "filename_matched_request_ids": [],
+        "copy_text": "requestIds=stable-operation-key filename=output.png"
+    },
+    "matched_log_count": 0,
+    "events": [],
+    "diagnostics_retention": {
+        "storage": "bounded_local_jsonl",
+        "max_entries": 300,
+        "default_max_entries": 300,
+        "min_entries": 100,
+        "max_configured_entries": 5000,
+        "configured_by": "APP_LOG_MAX_ENTRIES",
+        "persisted_across_process_restart": true,
+        "loss_modes": ["entry_evicted_by_max_entries", "log_level_filter", "local_log_file_missing_or_cleared"],
+        "bounded": true,
+        "not_agent_state_backend": true
+    },
+    "diagnostics_note": {
+        "code": "no_matching_logs_in_retention_window",
+        "message": "没有匹配到页面请求日志；诊断只覆盖最近 300 条本地应用日志，日志可能已被保留条数淘汰、被日志级别过滤，或本地日志文件被清理。",
+        "retention": {
+            "storage": "bounded_local_jsonl",
+            "max_entries": 300,
+            "default_max_entries": 300,
+            "min_entries": 100,
+            "max_configured_entries": 5000,
+            "configured_by": "APP_LOG_MAX_ENTRIES",
+            "persisted_across_process_restart": true,
+            "loss_modes": ["entry_evicted_by_max_entries", "log_level_filter", "local_log_file_missing_or_cleared"],
+            "bounded": true,
+            "not_agent_state_backend": true
+        }
     }
-  }
 }
 ```
 
@@ -581,71 +591,71 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 
 首次配置和诊断输出字段速查：
 
-| 字段 | 出现位置 | 判断口径 |
-| --- | --- | --- |
-| `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
-| `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
-| `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
-| `agent_auth_process.has_token` | `first-run --json` | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
-| `page_sse_auth_available_to_process` | `first-run --json` | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。 |
-| `summary.page_sse_auth_ready` | `agent:doctor` | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。 |
-| `page_sse_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 `/api/images` smoke；`state=not_run` 且 `billable=false` 表示它只是只读就绪检查。 |
-| `responses_image_backend_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。 |
-| `summary.page_sse_real_smoke` | `agent:doctor` | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。 |
-| `summary.orchestration_generate_smoke` | `agent:doctor` | `--allow-billable` 时默认 generate 主链 `/api/agent/image-requests` 的真实 smoke 状态；这是普通 generate 在 server-owned orchestration 下的主编排口径。 |
-| `summary.agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时显式 `--agent` 的 Agent JSON 文生图 smoke 状态；用于诊断直连 Agent JSON，不代表默认主链。 |
-| `summary.responses_page_sse_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.responses_agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `orchestration_generate_1k`、`agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
-| `summary.request_modes` | `agent:doctor` | 管理员 request mode 的配置和真实 smoke 摘要；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
-| `request_mode_controls` | `capabilities` | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`。 |
-| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
-| `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
-| `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
+| 字段                                                                                         | 出现位置                                                                                   | 判断口径                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `service_base_url` / `verification_scope.service_base_url`                                   | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。                                                                                                                                                                                                                                                                        |
+| `service_base_url_source` / `verification_scope.service_base_url_source`                     | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。                                                                                                                                                                                 |
+| `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。                                                                                                                                                                                                                                          |
+| `agent_auth_process.has_token`                                                               | `first-run --json`                                                                         | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。                                                                                                                                                                                                                                                                  |
+| `page_sse_auth_available_to_process`                                                         | `first-run --json`                                                                         | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。                                                                                                                                                                                                                      |
+| `summary.page_sse_auth_ready`                                                                | `agent:doctor`                                                                             | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。                                                                                                                                                                                                                                      |
+| `page_sse_real_smoke_status`                                                                 | `first-run --json`                                                                         | 结构化说明 `first-run` 未执行真实 `/api/images` smoke；`state=not_run` 且 `billable=false` 表示它只是只读就绪检查。                                                                                                                                                                                             |
+| `responses_image_backend_real_smoke_status`                                                  | `first-run --json`                                                                         | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。                                                                                                                                                                                                                |
+| `summary.page_sse_real_smoke`                                                                | `agent:doctor`                                                                             | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。                                                                                                                                        |
+| `summary.orchestration_generate_smoke`                                                       | `agent:doctor`                                                                             | `--allow-billable` 时默认 generate 主链 `/api/agent/image-requests` 的真实 smoke 状态；这是普通 generate 在 server-owned orchestration 下的主编排口径。                                                                                                                                                         |
+| `summary.agent_generate_smoke`                                                               | `agent:doctor`                                                                             | `--allow-billable` 时显式 `--agent` 的 Agent JSON 文生图 smoke 状态；用于诊断直连 Agent JSON，不代表默认主链。                                                                                                                                                                                                  |
+| `summary.responses_page_sse_generate_smoke`                                                  | `agent:doctor`                                                                             | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。                                                                                                                                                                       |
+| `summary.responses_agent_generate_smoke`                                                     | `agent:doctor`                                                                             | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。                                                                                                                                                              |
+| `summary.real_smoke_checks`                                                                  | `agent:doctor`                                                                             | 各真实 smoke 的状态汇总，包含 `orchestration_generate_1k`、`agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。                                                                                                                        |
+| `summary.request_modes`                                                                      | `agent:doctor`                                                                             | 管理员 request mode 的配置和真实 smoke 摘要，包含 `supported`、`configured`、`effective`、`admin_whitelist_by_channel`、`effective_by_channel`、带 `severity` 的 `gaps`、`suggested_channel_env_key`、`suggested_effective_value` 和 `next_action`；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
+| `request_mode_controls`                                                                      | `capabilities`                                                                             | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`。                                                                                                                                           |
+| `private_agent_env.exists`                                                                   | `first-run --json`                                                                         | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。                                                                                                                                                                                                                            |
+| `capabilities.ok`                                                                            | `first-run --json`、`agent:doctor`                                                         | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。                                                                                                                                                                                                                                 |
+| `diagnostics_retention`                                                                      | `diagnose-request.mjs`                                                                     | 页面日志诊断的保留窗口��无匹配日志不等于请求一定没发生。                                                                                                                                                                                                                                                        |
 
 单条 Agent state 诊断响应示例：
 
 ```json
 {
-  "found": true,
-  "diagnostics": {
-    "request": {
-      "request_id": "req_abc",
-      "idempotency_key": "stable-operation-key",
-      "mode": "generate",
-      "status": "succeeded",
-      "cached": false,
-      "created_at": "2026-05-12T00:00:00.000Z",
-      "updated_at": "2026-05-12T00:01:04.000Z",
-      "expires_at": "2026-05-13T00:00:00.000Z"
-    },
-    "response": {
-      "image_count": 1,
-      "artifact_ids": ["artifact-uuid"],
-      "content_urls": ["/api/agent/artifacts/artifact-uuid/content"],
-      "timing": {
-        "elapsed_ms": 64000,
-        "server_elapsed_ms": 64000
-      },
-      "execution": {
-        "transport": "agent_json",
-        "endpoint": "/api/agent/images/generate",
-        "request_headers": {
-          "user_agent_effective": "gpt-image-playground/2.1.0",
-          "has_extra_headers": false,
-          "allowed_header_names": ["user-agent", "x-app-id", "x-app-secret"],
-          "configured_header_names": []
+    "found": true,
+    "diagnostics": {
+        "request": {
+            "request_id": "req_abc",
+            "idempotency_key": "stable-operation-key",
+            "mode": "generate",
+            "status": "succeeded",
+            "cached": false,
+            "created_at": "2026-05-12T00:00:00.000Z",
+            "updated_at": "2026-05-12T00:01:04.000Z",
+            "expires_at": "2026-05-13T00:00:00.000Z"
+        },
+        "response": {
+            "image_count": 1,
+            "artifact_ids": ["artifact-uuid"],
+            "content_urls": ["/api/agent/artifacts/artifact-uuid/content"],
+            "timing": {
+                "elapsed_ms": 64000,
+                "server_elapsed_ms": 64000
+            },
+            "execution": {
+                "transport": "agent_json",
+                "endpoint": "/api/agent/images/generate",
+                "request_headers": {
+                    "user_agent_effective": "gpt-image-playground/2.1.0",
+                    "has_extra_headers": false,
+                    "allowed_header_names": ["user-agent", "x-app-id", "x-app-secret"],
+                    "configured_header_names": []
+                }
+            }
+        },
+        "state_backend": "sqlite",
+        "diagnostics_retention": {
+            "storage": "agent_state",
+            "ttl_seconds": 86400,
+            "bounded": true,
+            "loss_modes": ["request_expired_by_ttl", "artifact_deleted_or_purged", "state_backend_reset"]
         }
-      }
-    },
-    "state_backend": "sqlite",
-    "diagnostics_retention": {
-      "storage": "agent_state",
-      "ttl_seconds": 86400,
-      "bounded": true,
-      "loss_modes": ["request_expired_by_ttl", "artifact_deleted_or_purged", "state_backend_reset"]
     }
-  }
 }
 ```
 
@@ -666,21 +676,21 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 
 ### 边界矩阵
 
-| 前端能力或端点 | 归属契约 | 进入 Agent OpenAPI | 自动化口径 |
-| --- | --- | --- | --- |
-| `POST /api/agent/image-requests`、`POST /api/agent/images/generate`、`POST /api/agent/images/edit`、Agent jobs、Agent artifacts、`POST /api/agent/artifacts/{id}/share` | Agent API | 是 | 普通 generate 默认用 image-requests；其他 Agent 端点通过 skill 脚本和 Agent 鉴权调用。分享创建需要 Agent 鉴权，返回的分享 URL 给用户浏览器访问。 |
-| `POST /api/images` | 页面 form-data SSE API | 否 | 仅在默认 WebP edit、复杂 UI 批量、页面高级字段或显式 `--page-sse` 诊断时由 skill 选择。 |
-| `GET /api/runtime-capabilities` | 页面运行态能力 API | 否 | 页面展示运行态默认值、图片上游传输配置、渠道健康和后端 enablement；不是 Agent capabilities。 |
-| `PUT/DELETE /api/feedback` | 页面结果反馈写入和清理 API | 否 | 页面写入最近生成的结果反馈；删除历史时清理对应反馈。 |
-| `POST /api/agent/page-requests/feedback` | Agent 结果反馈批量只读 API | 是 | 按多个页面 `clientRequestId` 批量查询最新反馈。 |
-| `GET /api/agent/page-requests/{id}/feedback` | Agent 结果反馈只读 API | 是 | 按页面 `clientRequestId` 查询最新反馈。 |
-| `POST /api/agent/diagnostics/page-requests` | Agent 日志诊断批量只读 API | 是 | 按多个页面 `clientRequestId` 批量查询脱敏日志摘要。 |
-| `GET /api/agent/diagnostics/page-requests/{id}` | Agent 日志诊断摘要 API | 是 | 按页面 `clientRequestId` 查询脱敏日志摘要，不直接读取 `/api/logs` SSE。 |
-| `POST /api/shares`、`GET /api/shares/{token}`、`GET/POST /api/shares/{token}/content` | 分享访问 API | 否 | `POST /api/shares` 是页面上传创建端点，不进入 Agent OpenAPI���`GET/POST /content` 使用分享 token 或访问码服务用户浏览器，不复用 Agent artifact 下载契约。Agent 只通过 `/api/agent/artifacts/{id}/share` 创建这类分享记录。 |
-| `GET /api/logs` | 页面日志 SSE API | 否 | 使用页面访问码哈希的 Bearer 头，不接受 `AGENT_API_TOKEN`。 |
-| `POST /api/image-delete` | 页面图片文件删除 API | 否 | 按页面文件名删除 `generated-images/` 文件，不删除 Agent 状态库 artifact。 |
-| 灵感相册 | 浏览器本地工作台状态 | 否 | 只服务页面提示词复用，不作为 Agent capabilities。 |
-| 历史复用 | 浏览器本地历史状态 | 否 | 只服务页面继续编辑、做变体和复用提示词。 |
+| 前端能力或端点                                                                                                                                                          | 归属契约                   | 进入 Agent OpenAPI | 自动化口径                                                                                                                                                                                                                |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /api/agent/image-requests`、`POST /api/agent/images/generate`、`POST /api/agent/images/edit`、Agent jobs、Agent artifacts、`POST /api/agent/artifacts/{id}/share` | Agent API                  | 是                 | 普通 generate 默认用 image-requests；其他 Agent 端点通过 skill 脚本和 Agent 鉴权调用。分享创建需要 Agent 鉴权，返回的分享 URL 给用户浏览器访问。                                                                          |
+| `POST /api/images`                                                                                                                                                      | 页面 form-data SSE API     | 否                 | 仅在默认 WebP edit、复杂 UI 批量、页面高级字段或显式 `--page-sse` 诊断时由 skill 选择。                                                                                                                                   |
+| `GET /api/runtime-capabilities`                                                                                                                                         | 页面运行态能力 API         | 否                 | 页面展示运行态默认值、图片上游传输配置、渠道健康和后端 enablement；不是 Agent capabilities。                                                                                                                              |
+| `PUT/DELETE /api/feedback`                                                                                                                                              | 页面结果反馈写入和清理 API | 否                 | 页面写入最近生成的结果反馈；删除历史时清理对应反馈。                                                                                                                                                                      |
+| `POST /api/agent/page-requests/feedback`                                                                                                                                | Agent 结果反馈批量只读 API | 是                 | 按多个页面 `clientRequestId` 批量查询最新反馈。                                                                                                                                                                           |
+| `GET /api/agent/page-requests/{id}/feedback`                                                                                                                            | Agent 结果反馈只读 API     | 是                 | 按页面 `clientRequestId` 查询最新反馈。                                                                                                                                                                                   |
+| `POST /api/agent/diagnostics/page-requests`                                                                                                                             | Agent 日志诊断批量只读 API | 是                 | 按多个页面 `clientRequestId` 批量查询脱敏日志摘要。                                                                                                                                                                       |
+| `GET /api/agent/diagnostics/page-requests/{id}`                                                                                                                         | Agent 日志诊断摘要 API     | 是                 | 按页面 `clientRequestId` 查询脱敏日志摘要，不直接读取 `/api/logs` SSE。                                                                                                                                                   |
+| `POST /api/shares`、`GET /api/shares/{token}`、`GET/POST /api/shares/{token}/content`                                                                                   | 分享访问 API               | 否                 | `POST /api/shares` 是页面上传创建端点，不进入 Agent OpenAPI；`GET/POST /content` 使用分享 token 或访问码服务用户浏览器，不复用 Agent artifact 下载契约。Agent 只通过 `/api/agent/artifacts/{id}/share` 创建这类分享记录。 |
+| `GET /api/logs`                                                                                                                                                         | 页面日志 SSE API           | 否                 | 使用页面访问码哈希的 Bearer 头，不接受 `AGENT_API_TOKEN`。                                                                                                                                                                |
+| `POST /api/image-delete`                                                                                                                                                | 页面图片文件删除 API       | 否                 | 按页面文件名删除 `generated-images/` 文件，不删除 Agent 状态库 artifact。                                                                                                                                                 |
+| 灵感相册                                                                                                                                                                | 浏览器本地工作台状态       | 否                 | 只服务页面提示词复用，不作为 Agent capabilities。                                                                                                                                                                         |
+| 历史复用                                                                                                                                                                | 浏览器本地历史状态         | 否                 | 只服务页面继续编辑、做变体和复用提示词。                                                                                                                                                                                  |
 
 ## 错误
 
@@ -688,39 +698,39 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 
 ```json
 {
-  "error": {
-    "code": "validation_error",
-    "message": "请求校验失败。",
-    "retryable": false,
-    "details": {
-      "fields": {
-        "n": "必须是 1 到 10 之间的整数"
-      }
-    },
-    "diagnostics": {
-      "elapsed_ms": 1234,
-      "selected_channel_id": "default",
-      "upstream_host": "api.example.test",
-      "upstream_status": 524,
-      "upstream_event_type": "image_generation.partial_image",
-      "partial_image_count": 1,
-      "transport_error": false,
-      "transport_error_kind": "upstream_timeout",
-      "retry_after_seconds": 15,
-      "retry_after_ms": 15000,
-      "cooldown_until": "2026-05-20T00:00:15.000Z",
-      "cooldown_target": {
-        "channel_id": "default",
-        "request_mode": "images-sse"
-      },
-      "channel_cooldown_scope": "channel",
-      "response_headers": {
-        "date": "Wed, 20 May 2026 00:00:00 GMT",
-        "cf-ray": "example"
-      }
-    },
-    "request_id": "uuid"
-  }
+    "error": {
+        "code": "validation_error",
+        "message": "请求校验失败。",
+        "retryable": false,
+        "details": {
+            "fields": {
+                "n": "必须是 1 到 10 之间的整数"
+            }
+        },
+        "diagnostics": {
+            "elapsed_ms": 1234,
+            "selected_channel_id": "default",
+            "upstream_host": "api.example.test",
+            "upstream_status": 524,
+            "upstream_event_type": "image_generation.partial_image",
+            "partial_image_count": 1,
+            "transport_error": false,
+            "transport_error_kind": "upstream_timeout",
+            "retry_after_seconds": 15,
+            "retry_after_ms": 15000,
+            "cooldown_until": "2026-05-20T00:00:15.000Z",
+            "cooldown_target": {
+                "channel_id": "default",
+                "request_mode": "images-sse"
+            },
+            "channel_cooldown_scope": "channel",
+            "response_headers": {
+                "date": "Wed, 20 May 2026 00:00:00 GMT",
+                "cf-ray": "example"
+            }
+        },
+        "request_id": "uuid"
+    }
 }
 ```
 

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

@@ -1,48 +1,55 @@
 #!/usr/bin/env node
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
+import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
 import {
-  errorMessage,
-  assertValidImageSizeForModel,
-  normalizeOutputFormat,
-  parseRetryAfterValue,
-  readCapabilitiesImageTransportTimeoutMs,
-  readConfiguredPositiveInteger,
-  readMaxImageEdge,
-  readOptionValue,
-  readPartialImages,
-  loadPrivateAgentEnvFile,
-  resolvePlaygroundBaseUrl,
-  sleep,
-  validateAgentEditRequestAgainstCapabilities
-} from './lib/script-utils.mjs';
+    assertImageDimensions,
+    buildDimensionCheckFailureBody,
+    isDimensionCheckError,
+    parseExpectedDimensions
+} from './lib/dimension-check.mjs';
 import {
-  attachSummary,
-  buildFailureSummary,
-  buildSuccessSummary,
-  completeScriptTiming,
-  startScriptTiming
+    PAGE_SSE_ENDPOINT,
+    assertPageSseReady,
+    assertPageSseStreamingAllowed,
+    buildPageSseFailureOutput,
+    formatPageSseOutput,
+    normalizeImageBackendForPage,
+    postPageSse
+} from './lib/page-sse-client.mjs';
+import {
+    attachSummary,
+    buildFailureSummary,
+    buildSuccessSummary,
+    completeScriptTiming,
+    startScriptTiming
 } from './lib/script-summary.mjs';
 import {
-  PAGE_SSE_ENDPOINT,
-  assertPageSseReady,
-  assertPageSseStreamingAllowed,
-  buildPageSseFailureOutput,
-  formatPageSseOutput,
-  normalizeImageBackendForPage,
-  postPageSse
-} from './lib/page-sse-client.mjs';
-import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
+    errorMessage,
+    assertValidImageSizeForModel,
+    normalizeOutputFormat,
+    parseImageSizeValue,
+    parseRetryAfterValue,
+    readCapabilitiesImageTransportTimeoutMs,
+    readConfiguredPositiveInteger,
+    readMaxImageEdge,
+    readOptionValue,
+    readPartialImages,
+    loadPrivateAgentEnvFile,
+    resolvePlaygroundBaseUrl,
+    sleep,
+    validateAgentEditRequestAgainstCapabilities
+} from './lib/script-utils.mjs';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 
 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'
+    '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']);
@@ -50,6 +57,9 @@ const MODERATIONS = new Set(['low', 'auto']);
 const THINKING_VALUES = new Set(['minimal', 'none', 'low', 'medium', 'high', 'xhigh']);
 const DEFAULT_PAGE_OUTPUT_FORMAT = 'webp';
 const DEFAULT_PAGE_OUTPUT_COMPRESSION = 100;
+const DIMENSION_CHECK_URL_FIELDS = ['absolute_content_url', 'content_url', 'absolute_path', 'path'];
+const EDIT_DIMENSION_CHECK_NEXT_STEP =
+    '确认当前编辑渠道是否支持请求尺寸，或调整任务接受实际返回尺寸；重新执行必须使用新的 Idempotency-Key。';
 
 loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
@@ -58,691 +68,774 @@ const contractCheck = process.env.GPT_IMAGE_AGENT_CONTRACT_CHECK === '1' || proc
 const scriptTiming = startScriptTiming();
 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);
 }
 const imagePath = options.imagePath;
 const prompt = options.promptParts.join(' ');
 if (options.help) {
-  printUsage();
-  process.exit(0);
+    printUsage();
+    process.exit(0);
 }
 
 try {
-  validateUpstreamStreamingOptions(options);
-  options.size = assertValidImageSizeForModel(options.size, options.model, '--size');
+    validateUpstreamStreamingOptions(options);
+    options.size = assertValidImageSizeForModel(options.size, options.model, '--size');
 } catch (error) {
-  console.error(errorMessage(error));
-  printUsage();
-  process.exit(2);
+    console.error(errorMessage(error));
+    printUsage();
+    process.exit(2);
 }
 
 let maxAttempts;
 let timeoutMs;
 try {
-  maxAttempts = readConfiguredPositiveInteger(process.env.GPT_IMAGE_AGENT_MAX_ATTEMPTS, 'GPT_IMAGE_AGENT_MAX_ATTEMPTS', 3);
-  timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
+    maxAttempts = readConfiguredPositiveInteger(
+        process.env.GPT_IMAGE_AGENT_MAX_ATTEMPTS,
+        'GPT_IMAGE_AGENT_MAX_ATTEMPTS',
+        3
+    );
+    timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
 } catch (error) {
-  console.error(errorMessage(error));
-  printUsage();
-  process.exit(2);
+    console.error(errorMessage(error));
+    printUsage();
+    process.exit(2);
 }
-const idempotencyKey = options.idempotencyKey || process.env.GPT_IMAGE_AGENT_IDEMPOTENCY_KEY || `agent-edit-${crypto.randomUUID()}`;
+const idempotencyKey =
+    options.idempotencyKey || process.env.GPT_IMAGE_AGENT_IDEMPOTENCY_KEY || `agent-edit-${crypto.randomUUID()}`;
 
 if ((!imagePath || !prompt) && !contractCheck) {
-  printUsage();
-  process.exit(2);
+    printUsage();
+    process.exit(2);
 }
 
 let baseUrl;
 let baseUrlInfo;
 try {
-  baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
-  baseUrl = baseUrlInfo.baseUrl;
+    baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+    baseUrl = baseUrlInfo.baseUrl;
 } catch (error) {
-  console.error(errorMessage(error));
-  process.exit(2);
+    console.error(errorMessage(error));
+    process.exit(2);
 }
 
 if (options.dryRun || (!contractCheck && !options.allowBillable)) {
-  const routingGuidance = buildEditRoutingGuidance(options);
-  console.log(
-    JSON.stringify(
-      {
-        ok: true,
-        billable: false,
-        dry_run: true,
-        verification_scope: buildDryRunVerificationScope(),
-        endpoint: `${baseUrl}${routingGuidance.recommended_endpoint}`,
-        routing_guidance: routingGuidance,
-        idempotency_key: idempotencyKey,
-        request: {
-          image_path: imagePath,
-          prompt,
-          model: options.model,
-          size: options.size,
-          quality: options.quality,
-          response_mode: options.responseMode,
-          ...(options.streamMode ? { stream_mode: options.streamMode } : {}),
-          ...(options.streamingStrategy ? { streaming_strategy: options.streamingStrategy } : {}),
-          ...(options.partialImages !== undefined
-            ? { partial_images: readPartialImages(options.partialImages, '--partial-images') }
-            : {}),
-          ...(usesPageOutputOptions(options, routingGuidance) ? { output_format: readOutputFormat(options) } : {}),
-          ...(usesPageOutputOptions(options, routingGuidance) && 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 才会发起真实图片编辑请求。'
-      },
-      null,
-      2
-    )
-  );
-  process.exit(0);
+    const routingGuidance = buildEditRoutingGuidance(options);
+    console.log(
+        JSON.stringify(
+            {
+                ok: true,
+                billable: false,
+                dry_run: true,
+                verification_scope: buildDryRunVerificationScope(),
+                endpoint: `${baseUrl}${routingGuidance.recommended_endpoint}`,
+                routing_guidance: routingGuidance,
+                idempotency_key: idempotencyKey,
+                request: {
+                    image_path: imagePath,
+                    prompt,
+                    model: options.model,
+                    size: options.size,
+                    quality: options.quality,
+                    response_mode: options.responseMode,
+                    ...(options.streamMode ? { stream_mode: options.streamMode } : {}),
+                    ...(options.streamingStrategy ? { streaming_strategy: options.streamingStrategy } : {}),
+                    ...(options.partialImages !== undefined
+                        ? { partial_images: readPartialImages(options.partialImages, '--partial-images') }
+                        : {}),
+                    ...(usesPageOutputOptions(options, routingGuidance)
+                        ? { output_format: readOutputFormat(options) }
+                        : {}),
+                    ...(usesPageOutputOptions(options, routingGuidance) && 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 } : {}),
+                    ...(options.dimensionCheck ? { dimension_check: true } : {}),
+                    ...(readEditNormalizations(options) ? { normalizations: readEditNormalizations(options) } : {})
+                },
+                next_step: '重新执行并添加 --allow-billable 才会发起真实图片编辑请求。'
+            },
+            null,
+            2
+        )
+    );
+    process.exit(0);
 }
 
 const routingGuidance = buildEditRoutingGuidance(options);
 if (routingGuidance.transport === 'page_sse') {
-  try {
-    assertPageSseStreamingAllowed(options);
-  } catch (error) {
-    console.error(errorMessage(error));
-    process.exit(2);
-  }
+    try {
+        assertPageSseStreamingAllowed(options);
+    } catch (error) {
+        console.error(errorMessage(error));
+        process.exit(2);
+    }
 }
 
 function parseArgs(argv) {
-  const parsed = {
-    model: 'gpt-image-2',
-    size: 'auto',
-    quality: 'auto',
-    responseMode: 'path',
-    routeMode: 'auto',
-    streamMode: undefined,
-    streamingStrategy: undefined,
-    partialImages: undefined,
-    format: DEFAULT_PAGE_OUTPUT_FORMAT,
-    formatSpecified: false,
-    outputCompression: undefined,
-    moderation: undefined,
-    imageBackend: undefined,
-    responsesModel: undefined,
-    thinking: undefined,
-    promptOptimization: undefined,
-    forceWeb: undefined,
-    sseLogPath: undefined,
-    timeoutMs: undefined,
-    baseUrl: undefined,
-    idempotencyKey: undefined,
-    imagePath: undefined,
-    imagePathSource: undefined,
-    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 === '--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 === '--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);
-      parsed.formatSpecified = true;
-    }
-    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 === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
-    else if (arg === '--image') {
-      if (parsed.imagePathSource === 'option') throw new Error('--image 只能设置一次。');
-      if (parsed.imagePath) throw new Error('--image 与位置参数 <image-path> 不能同时设置。');
-      parsed.imagePath = readOptionValue(argv, (index += 1), arg);
-      parsed.imagePathSource = 'option';
-    }
-    else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
-    else if (!parsed.imagePath) {
-      parsed.imagePath = arg;
-      parsed.imagePathSource = 'positional';
-    }
-    else parsed.promptParts.push(arg);
-  }
-  return parsed;
+    const parsed = {
+        model: 'gpt-image-2',
+        size: 'auto',
+        quality: 'auto',
+        responseMode: 'path',
+        routeMode: 'auto',
+        streamMode: undefined,
+        streamingStrategy: undefined,
+        partialImages: undefined,
+        format: DEFAULT_PAGE_OUTPUT_FORMAT,
+        formatSpecified: false,
+        outputCompression: undefined,
+        moderation: undefined,
+        imageBackend: undefined,
+        responsesModel: undefined,
+        thinking: undefined,
+        promptOptimization: undefined,
+        forceWeb: undefined,
+        dimensionCheck: false,
+        sseLogPath: undefined,
+        timeoutMs: undefined,
+        baseUrl: undefined,
+        idempotencyKey: undefined,
+        imagePath: undefined,
+        imagePathSource: undefined,
+        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 === '--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 === '--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);
+            parsed.formatSpecified = true;
+        } 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 === '--dimension-check') parsed.dimensionCheck = 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 === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--image') {
+            if (parsed.imagePathSource === 'option') throw new Error('--image 只能设置一次。');
+            if (parsed.imagePath) throw new Error('--image 与位置参数 <image-path> 不能同时设置。');
+            parsed.imagePath = readOptionValue(argv, (index += 1), arg);
+            parsed.imagePathSource = 'option';
+        } else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
+        else if (!parsed.imagePath) {
+            parsed.imagePath = arg;
+            parsed.imagePathSource = 'positional';
+        } else parsed.promptParts.push(arg);
+    }
+    return parsed;
 }
 
 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 buildDryRunVerificationScope() {
-  return {
-    mode: 'local_planning_only',
-    service_base_url: baseUrl,
-    service_base_url_source: baseUrlInfo.source,
-    interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
-    remote_capabilities_verified: false,
-    runtime_capacity_verified: false,
-    auth_verified: false,
-    billable_request_sent: false,
-    note: 'Dry-run validates local request construction and routing guidance only; run --contract-check or --allow-billable to verify the remote service.'
-  };
+    return {
+        mode: 'local_planning_only',
+        service_base_url: baseUrl,
+        service_base_url_source: baseUrlInfo.source,
+        interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+        remote_capabilities_verified: false,
+        runtime_capacity_verified: false,
+        auth_verified: false,
+        billable_request_sent: false,
+        note: 'Dry-run validates local request construction and routing guidance only; run --contract-check or --allow-billable to verify the remote service.'
+    };
 }
 
 function buildEditRoutingGuidance(parsed) {
-  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: '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 (usesDefaultPageOutput(parsed) && isPageSseAllowed(parsed)) {
-    return {
-      recommended_endpoint: '/api/images',
-      transport: 'page_sse',
-      strength: 'default',
-      reason: 'Default WebP edit output uses the page form-data SSE endpoint; Agent JSON edit has a fixed output contract.'
-    };
-  }
-  if (readMaxImageEdge(parsed.size) > 2048 && isPageSseAllowed(parsed)) {
+    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: '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 (usesDefaultPageOutput(parsed) && isPageSseAllowed(parsed)) {
+        return {
+            recommended_endpoint: '/api/images',
+            transport: 'page_sse',
+            strength: 'default',
+            reason: 'Default WebP edit output uses the page form-data SSE endpoint; Agent JSON edit has a fixed output contract.'
+        };
+    }
+    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 {
-      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.'
+        recommended_endpoint: '/api/agent/images/edit',
+        transport: 'agent_json',
+        strength: 'default',
+        reason: 'Agent edit uses a fixed output contract and should be selected explicitly with --agent.'
     };
-  }
-  return {
-    recommended_endpoint: '/api/agent/images/edit',
-    transport: 'agent_json',
-    strength: 'default',
-    reason: 'Agent edit uses a fixed output contract and should be selected explicitly with --agent.'
-  };
 }
 
 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) } : {})
+        }))
+    };
 }
 
 async function readCapabilities() {
-  let response;
-  try {
-    response = await fetchWithTimeout(`${baseUrl}/api/agent/capabilities`, {
-      headers: authHeaders()
-    });
-  } catch (error) {
-    const message = errorMessage(error);
-    throw new Error(`无法连接 GPT Image Playground：${baseUrl}。${message}`);
-  }
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`capabilities 请求失败，状态码 ${response.status}：${body}`);
-  }
-  return response.json();
+    let response;
+    try {
+        response = await fetchWithTimeout(`${baseUrl}/api/agent/capabilities`, {
+            headers: authHeaders()
+        });
+    } catch (error) {
+        const message = errorMessage(error);
+        throw new Error(`无法连接 GPT Image Playground：${baseUrl}。${message}`);
+    }
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`capabilities 请求失败，状态码 ${response.status}：${body}`);
+    }
+    return response.json();
 }
 
 function assertPageSseReadyForEdit(capabilities) {
-  assertPageSseReady({
-    capabilities,
-    passwordHash,
-    idempotencyKey
-  });
+    assertPageSseReady({
+        capabilities,
+        passwordHash,
+        idempotencyKey
+    });
 }
 
 function shouldRetry(result) {
-  return Boolean(result?.error?.retryable);
+    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' && usesDefaultPageOutput(parsed) && !isPageSseAllowed(parsed)) {
-    throw new Error('默认 WebP 图生图输出需要页面 SSE；若要使用 Agent JSON 固定输出，请添加 --agent。');
-  }
-  if (parsed.routeMode === 'agent') {
-    assertNoPageOnlyEditOptions(parsed, 'Agent edit');
-  }
-  if (parsed.formatSpecified && !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 !== undefined) readPartialImages(parsed.partialImages, '--partial-images');
+    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 (parsed.dimensionCheck && !parseImageSizeValue(parsed.size)) {
+        throw new Error('--dimension-check 需要 --size 为 WIDTHxHEIGHT。');
+    }
+    if (hasPageOnlyEditOptions(parsed) && !isPageSseAllowed(parsed)) {
+        throw new Error('图生图高级参数需要页面 SSE，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。');
+    }
+    if (parsed.routeMode !== 'agent' && usesDefaultPageOutput(parsed) && !isPageSseAllowed(parsed)) {
+        throw new Error('默认 WebP 图生图输出需要页面 SSE；若要使用 Agent JSON 固定输出，请添加 --agent。');
+    }
+    if (parsed.routeMode === 'agent') {
+        assertNoPageOnlyEditOptions(parsed, 'Agent edit');
+    }
+    if (parsed.formatSpecified && !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 !== undefined) readPartialImages(parsed.partialImages, '--partial-images');
 }
 
 function hasPageOnlyEditOptions(parsed) {
-  return Boolean(
-    parsed.formatSpecified ||
-      parsed.outputCompression !== undefined ||
-      parsed.moderation ||
-      parsed.imageBackend ||
-      parsed.responsesModel ||
-      parsed.thinking ||
-      parsed.promptOptimization !== undefined ||
-      parsed.forceWeb !== undefined
-  );
+    return Boolean(
+        parsed.formatSpecified ||
+            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。`);
+    if (!hasPageOnlyEditOptions(parsed)) return;
+    throw new Error(`${context} 不接受图生图高级页面字段；请去掉这些字段或使用 --page-sse。`);
 }
 
 function readOutputFormat(parsed) {
-  return parsed.format ? normalizeOutputFormat(parsed.format) : DEFAULT_PAGE_OUTPUT_FORMAT;
+    return parsed.format ? normalizeOutputFormat(parsed.format) : DEFAULT_PAGE_OUTPUT_FORMAT;
 }
 
 function usesPageOutputOptions(parsed, routingGuidance) {
-  return routingGuidance.transport === 'page_sse' || parsed.formatSpecified || parsed.outputCompression !== undefined;
+    return routingGuidance.transport === 'page_sse' || parsed.formatSpecified || parsed.outputCompression !== undefined;
 }
 
 function usesDefaultPageOutput(parsed) {
-  return !parsed.formatSpecified && parsed.outputCompression === undefined && readOutputFormat(parsed) === DEFAULT_PAGE_OUTPUT_FORMAT;
+    return (
+        !parsed.formatSpecified &&
+        parsed.outputCompression === undefined &&
+        readOutputFormat(parsed) === DEFAULT_PAGE_OUTPUT_FORMAT
+    );
 }
 
 function readOutputCompression(parsed) {
-  const outputFormat = readOutputFormat(parsed);
-  if (outputFormat === 'png') return undefined;
-  const value = parsed.outputCompression === undefined ? String(DEFAULT_PAGE_OUTPUT_COMPRESSION) : 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;
+    const outputFormat = readOutputFormat(parsed);
+    if (outputFormat === 'png') return undefined;
+    const value =
+        parsed.outputCompression === undefined
+            ? String(DEFAULT_PAGE_OUTPUT_COMPRESSION)
+            : 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 };
+    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。`);
+    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();
+    if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} 必须是非空字符串。`);
+    return value.trim();
+}
+
+async function assertDimensionsIfRequested(response) {
+    if (!options.dimensionCheck) return response;
+    return assertImageDimensions({
+        response,
+        expected: parseExpectedDimensions(options.size),
+        baseUrl,
+        authHeaders,
+        timeoutMs,
+        nextStep: EDIT_DIMENSION_CHECK_NEXT_STEP,
+        readUrlFields: DIMENSION_CHECK_URL_FIELDS
+    });
+}
+
+async function buildSuccessOutput(result, routing, { dimensionChecked = false } = {}) {
+    const checkedResult = dimensionChecked ? result : await assertDimensionsIfRequested(enrichImageUrls(result));
+    return attachSummary(
+        routing ? { ...checkedResult, routing } : checkedResult,
+        buildSuccessSummary({
+            result: checkedResult,
+            routing,
+            timing: completeScriptTiming(scriptTiming),
+            idempotencyKey,
+            billable: true
+        })
+    );
+}
+
+function buildFailureOutput(output, routing) {
+    return attachSummary(
+        output,
+        buildFailureSummary({
+            errorBody: output,
+            routing,
+            timing: completeScriptTiming(scriptTiming),
+            idempotencyKey,
+            billable: output?.billable !== false,
+            nextAction: output?.next_step
+        })
+    );
+}
+
+function buildDimensionCheckFailureOutput(error, routing) {
+    return buildFailureOutput(buildDimensionCheckFailureBody(error, routing), routing);
 }
 
 function isPageSseAllowed(parsed) {
-  return parsed.streamMode !== 'non_stream' && parsed.streamingStrategy !== 'off';
+    return parsed.streamMode !== 'non_stream' && parsed.streamingStrategy !== 'off';
 }
 
 async function fetchWithTimeout(url, init) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, { ...init, signal: controller.signal });
-  } finally {
-    clearTimeout(timeout);
-  }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+        clearTimeout(timeout);
+    }
 }
 
 function printUsage() {
-  console.error('用法：edit-image.mjs [options] <image-path> <prompt> 或 edit-image.mjs --image <path> [options] <prompt>');
-  console.error('默认只输出 dry-run；添加 --allow-billable 才会真实编辑图片。');
-  console.error('常用参数：--image --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 --base-url --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');
+    console.error(
+        '用法：edit-image.mjs [options] <image-path> <prompt> 或 edit-image.mjs --image <path> [options] <prompt>'
+    );
+    console.error('默认只输出 dry-run；添加 --allow-billable 才会真实编辑图片。');
+    console.error(
+        '常用参数：--image --model --size --quality --response-mode --format --output-compression --moderation --image-backend --responses-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --dimension-check --sse-log --timeout-ms --base-url --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 {
-  capabilities = await readCapabilities();
-  if (options.timeoutMs === undefined) {
-    timeoutMs = readCapabilitiesImageTransportTimeoutMs(capabilities, timeoutMs);
-  }
+    capabilities = await readCapabilities();
+    if (options.timeoutMs === undefined) {
+        timeoutMs = readCapabilitiesImageTransportTimeoutMs(capabilities, timeoutMs);
+    }
 } catch (error) {
-  console.error(errorMessage(error));
-  process.exit(1);
+    console.error(errorMessage(error));
+    process.exit(1);
 }
 
 try {
-  validateAgentEditRequestAgainstCapabilities(
-    {
-      n: 1,
-      partial_images:
-        options.partialImages !== undefined
-          ? readPartialImages(options.partialImages, '--partial-images')
-          : capabilities?.defaults?.partial_images,
-      imageCount: 1,
-      image_backend: options.imageBackend
-    },
-    capabilities
-  );
+    validateAgentEditRequestAgainstCapabilities(
+        {
+            n: 1,
+            partial_images:
+                options.partialImages !== undefined
+                    ? readPartialImages(options.partialImages, '--partial-images')
+                    : capabilities?.defaults?.partial_images,
+            imageCount: 1,
+            image_backend: options.imageBackend
+        },
+        capabilities
+    );
 } catch (error) {
-  console.error(errorMessage(error));
-  process.exit(2);
+    console.error(errorMessage(error));
+    process.exit(2);
 }
 
 if (contractCheck) {
-  const response = await fetchWithTimeout(`${baseUrl}/api/agent/images/edit`, {
-    method: 'POST',
-    headers: {
-      'Idempotency-Key': idempotencyKey,
-      'Content-Type': 'application/json',
-      ...authHeaders()
-    },
-    body: JSON.stringify({ prompt: 'contract check' })
-  });
-  const result = await response.json();
-  if (response.status === 415 && result?.error?.code === 'validation_error') {
-    console.log(JSON.stringify({ ok: true, billable: false, status: response.status, error_code: result.error.code }, null, 2));
-    process.exit(0);
-  }
-  console.error(JSON.stringify({ ok: false, billable: false, status: response.status, result }, null, 2));
-  process.exit(1);
+    const response = await fetchWithTimeout(`${baseUrl}/api/agent/images/edit`, {
+        method: 'POST',
+        headers: {
+            'Idempotency-Key': idempotencyKey,
+            'Content-Type': 'application/json',
+            ...authHeaders()
+        },
+        body: JSON.stringify({ prompt: 'contract check' })
+    });
+    const result = await response.json();
+    if (response.status === 415 && result?.error?.code === 'validation_error') {
+        console.log(
+            JSON.stringify(
+                { ok: true, billable: false, status: response.status, error_code: result.error.code },
+                null,
+                2
+            )
+        );
+        process.exit(0);
+    }
+    console.error(JSON.stringify({ ok: false, billable: false, status: response.status, result }, null, 2));
+    process.exit(1);
 }
 
 try {
-  const stats = fs.statSync(imagePath);
-  if (!stats.isFile()) {
-    console.error(`图片路径不是文件：${imagePath}`);
-    process.exit(2);
-  }
+    const stats = fs.statSync(imagePath);
+    if (!stats.isFile()) {
+        console.error(`图片路径不是文件：${imagePath}`);
+        process.exit(2);
+    }
 } catch (error) {
-  const message = errorMessage(error);
-  console.error(`无法读取图片文件：${imagePath}。${message}`);
-  process.exit(2);
+    const message = errorMessage(error);
+    console.error(`无法读取图片文件：${imagePath}。${message}`);
+    process.exit(2);
 }
 
 const imageBuffer = fs.readFileSync(imagePath);
 const imageType = mimeTypeForPath(imagePath);
 
 function buildFormData() {
-  const formData = new FormData();
-  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);
-  if (options.streamMode) formData.append('stream_mode', options.streamMode);
-  if (options.streamingStrategy) formData.append('streaming_strategy', options.streamingStrategy);
-  if (options.partialImages !== undefined) {
-    formData.append('partial_images', String(readPartialImages(options.partialImages, '--partial-images')));
-  } else if (capabilities?.defaults?.partial_images !== undefined) {
-    formData.append('partial_images', String(readPartialImages(capabilities.defaults.partial_images, 'capabilities.defaults.partial_images')));
-  }
-  formData.append('image_0', new Blob([imageBuffer], { type: imageType }), path.basename(imagePath));
-  return formData;
+    const formData = new FormData();
+    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);
+    if (options.streamMode) formData.append('stream_mode', options.streamMode);
+    if (options.streamingStrategy) formData.append('streaming_strategy', options.streamingStrategy);
+    if (options.partialImages !== undefined) {
+        formData.append('partial_images', String(readPartialImages(options.partialImages, '--partial-images')));
+    } else if (capabilities?.defaults?.partial_images !== undefined) {
+        formData.append(
+            'partial_images',
+            String(readPartialImages(capabilities.defaults.partial_images, 'capabilities.defaults.partial_images'))
+        );
+    }
+    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');
-  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 !== undefined) {
-    formData.append('partial_images', String(readPartialImages(options.partialImages, '--partial-images')));
-  } else if (capabilities?.defaults?.partial_images !== undefined) {
-    formData.append('partial_images', String(readPartialImages(capabilities.defaults.partial_images, 'capabilities.defaults.partial_images')));
-  }
-  if (passwordHash) formData.append('passwordHash', passwordHash);
-  formData.append('image_0', new Blob([imageBuffer], { type: imageType }), path.basename(imagePath));
-  return formData;
+    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');
+    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 !== undefined) {
+        formData.append('partial_images', String(readPartialImages(options.partialImages, '--partial-images')));
+    } else if (capabilities?.defaults?.partial_images !== undefined) {
+        formData.append(
+            'partial_images',
+            String(readPartialImages(capabilities.defaults.partial_images, 'capabilities.defaults.partial_images'))
+        );
+    }
+    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(
-      attachSummary({
-        ...formatPageSseOutput({
-          result,
-          baseUrl,
-          responseMode: options.responseMode,
-          defaultOutputFormat: DEFAULT_PAGE_OUTPUT_FORMAT
-        }),
-        routing: {
-          transport: 'page_sse',
-          endpoint: PAGE_SSE_ENDPOINT,
-          fallback_endpoint: '/api/agent/images/edit',
-          fallback_mode: 'manual_after_diagnosis'
-        }
-      }, buildSuccessSummary({
+    assertPageSseReadyForEdit(capabilities);
+    const result = await postPageSse({
+        url: `${baseUrl}${PAGE_SSE_ENDPOINT}`,
+        formData: buildPageSseFormData(),
+        timeoutMs,
+        sseLogPath: options.sseLogPath,
+        errorMessage
+    });
+    const routing = buildPageSseEditRouting();
+    const checkedResult = await assertDimensionsIfRequested(formatPageSseDimensionCheckInput(result));
+    console.log(
+        JSON.stringify(
+            await buildSuccessOutput(
+                formatPageSseOutput({
+                    result: checkedResult,
+                    baseUrl,
+                    responseMode: options.responseMode,
+                    defaultOutputFormat: DEFAULT_PAGE_OUTPUT_FORMAT
+                }),
+                routing,
+                { dimensionChecked: true }
+            ),
+            null,
+            2
+        )
+    );
+}
+
+function buildPageSseEditRouting() {
+    return {
+        transport: 'page_sse',
+        endpoint: PAGE_SSE_ENDPOINT,
+        fallback_endpoint: '/api/agent/images/edit',
+        fallback_mode: 'manual_after_diagnosis'
+    };
+}
+
+function formatPageSseDimensionCheckInput(result) {
+    return formatPageSseOutput({
         result,
-        routing: {
-          transport: 'page_sse',
-          endpoint: PAGE_SSE_ENDPOINT
-        },
-        timing: completeScriptTiming(scriptTiming),
-        idempotencyKey,
-        billable: true
-      })),
-      null,
-      2
-    )
-  );
+        baseUrl,
+        responseMode: 'both',
+        defaultOutputFormat: DEFAULT_PAGE_OUTPUT_FORMAT
+    });
 }
 
 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';
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+    if (ext === '.webp') return 'image/webp';
+    return 'image/png';
 }
 
 let lastResult;
 let lastRetryAfter = null;
 
 if (routingGuidance.transport === 'page_sse') {
-  try {
-    await runPageSseEdit();
-    process.exit(0);
-  } catch (error) {
-    const failureOutput = buildPageSseFailureOutput({
-      error,
-      fallbackEndpoint: '/api/agent/images/edit',
-      errorMessage
-    });
-    console.error(
-      JSON.stringify(
-        attachSummary(failureOutput, buildFailureSummary({
-          errorBody: failureOutput,
-          routing: {
-            transport: 'page_sse',
-            endpoint: PAGE_SSE_ENDPOINT
-          },
-          timing: completeScriptTiming(scriptTiming),
-          idempotencyKey,
-          billable: failureOutput.billable !== false
-        })),
-        null,
-        2
-      )
-    );
-    process.exit(1);
-  }
+    try {
+        await runPageSseEdit();
+        process.exit(0);
+    } catch (error) {
+        if (isDimensionCheckError(error)) {
+            console.error(JSON.stringify(buildDimensionCheckFailureOutput(error, buildPageSseEditRouting()), null, 2));
+            process.exit(1);
+        }
+        const failureOutput = buildPageSseFailureOutput({
+            error,
+            fallbackEndpoint: '/api/agent/images/edit',
+            errorMessage
+        });
+        console.error(JSON.stringify(buildFailureOutput(failureOutput, buildPageSseEditRouting()), null, 2));
+        process.exit(1);
+    }
 }
 
 async function buildAgentFailureOutput(output, routing) {
-  const summary = buildFailureSummary({
-    errorBody: output,
-    routing,
-    timing: completeScriptTiming(scriptTiming),
-    idempotencyKey,
-    billable: output?.billable !== false
-  });
-  const enriched = await enrichFailureWithAgentDiagnostics({
-    baseUrl,
-    authHeaders,
-    idempotencyKey,
-    failureOutput: attachSummary(output, summary),
-    summary,
-    timeoutMs
-  });
-  return attachSummary(enriched.failureOutput, enriched.summary);
+    const failure = buildFailureOutput(output, routing);
+    const enriched = await enrichFailureWithAgentDiagnostics({
+        baseUrl,
+        authHeaders,
+        idempotencyKey,
+        failureOutput: failure,
+        summary: failure.summary,
+        timeoutMs
+    });
+    return attachSummary(enriched.failureOutput, enriched.summary);
 }
 
 for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-  let response;
-  let result;
-  try {
-    response = await fetchWithTimeout(`${baseUrl}/api/agent/images/edit`, {
-      method: 'POST',
-      headers: {
-        'Idempotency-Key': idempotencyKey,
-        ...authHeaders()
-      },
-      body: buildFormData()
-    });
-    result = await response.json();
-  } catch (error) {
-    const message = errorMessage(error);
-    result = { error: { code: 'network_error', message, retryable: true } };
-    lastResult = result;
-    lastRetryAfter = 1;
-    if (attempt === maxAttempts) break;
-    await sleep(lastRetryAfter);
-    continue;
-  }
-  if (response.ok) {
-    console.log(
-      JSON.stringify(
-        attachSummary(
-          enrichImageUrls(result),
-          buildSuccessSummary({
-            result: enrichImageUrls(result),
-            routing: { transport: 'agent_json', endpoint: '/api/agent/images/edit' },
-            timing: completeScriptTiming(scriptTiming),
-            idempotencyKey,
-            billable: true
-          })
-        ),
-        null,
-        2
-      )
-    );
-    process.exit(0);
-  }
+    let response;
+    let result;
+    try {
+        response = await fetchWithTimeout(`${baseUrl}/api/agent/images/edit`, {
+            method: 'POST',
+            headers: {
+                'Idempotency-Key': idempotencyKey,
+                ...authHeaders()
+            },
+            body: buildFormData()
+        });
+        result = await response.json();
+    } catch (error) {
+        const message = errorMessage(error);
+        result = { error: { code: 'network_error', message, retryable: true } };
+        lastResult = result;
+        lastRetryAfter = 1;
+        if (attempt === maxAttempts) break;
+        await sleep(lastRetryAfter);
+        continue;
+    }
+    if (response.ok) {
+        try {
+            console.log(
+                JSON.stringify(
+                    await buildSuccessOutput(result, { transport: 'agent_json', endpoint: '/api/agent/images/edit' }),
+                    null,
+                    2
+                )
+            );
+            process.exit(0);
+        } catch (error) {
+            if (!isDimensionCheckError(error)) throw error;
+            console.error(
+                JSON.stringify(
+                    buildDimensionCheckFailureOutput(error, {
+                        transport: 'agent_json',
+                        endpoint: '/api/agent/images/edit'
+                    }),
+                    null,
+                    2
+                )
+            );
+            process.exit(1);
+        }
+    }
 
-  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'));
+    lastResult = result;
+    lastRetryAfter = retryAfter;
+    if (!shouldRetry(result) || attempt === maxAttempts) break;
+    await sleep(retryAfter);
 }
 
 const failureOutput = { ...lastResult, retry_after: lastRetryAfter };
 console.error(
-  JSON.stringify(
-    await buildAgentFailureOutput(failureOutput, { transport: 'agent_json', endpoint: '/api/agent/images/edit' }),
-    null,
-    2
-  )
+    JSON.stringify(
+        await buildAgentFailureOutput(failureOutput, { transport: 'agent_json', endpoint: '/api/agent/images/edit' }),
+        null,
+        2
+    )
 );
 process.exit(1);

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

@@ -1,10 +1,25 @@
 #!/usr/bin/env node
 import { AGENT_ENDPOINTS, buildAgentArtifactSharePath, buildAgentJobResultPath } from './lib/agent-api-paths.mjs';
 import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
+import {
+    assertImageDimensions,
+    buildDimensionCheckFailureBody,
+    isDimensionCheckError,
+    parseExpectedDimensions
+} from './lib/dimension-check.mjs';
+import { formatPageSseOutput as formatSharedPageSseOutput } from './lib/page-sse-client.mjs';
+import {
+    attachSummary,
+    buildFailureSummary,
+    buildSuccessSummary,
+    completeScriptTiming,
+    startScriptTiming
+} from './lib/script-summary.mjs';
 import {
     errorMessage,
     assertValidImageSizeForModel,
     normalizeOutputFormat,
+    parseImageSizeValue,
     parseRetryAfterValue,
     readCapabilitiesImageTransportTimeoutMs,
     readConfiguredPositiveInteger,
@@ -17,13 +32,6 @@ import {
     sleep,
     validateAgentGenerateRequestAgainstCapabilities
 } from './lib/script-utils.mjs';
-import {
-    attachSummary,
-    buildFailureSummary,
-    buildSuccessSummary,
-    completeScriptTiming,
-    startScriptTiming
-} from './lib/script-summary.mjs';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -45,6 +53,7 @@ const DEFAULT_OUTPUT_FORMAT = 'webp';
 const DEFAULT_OUTPUT_COMPRESSION = 100;
 const DEFAULT_PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH = 128;
 const PAGE_SSE_ENDPOINT = '/api/images';
+const DIMENSION_CHECK_URL_FIELDS = ['absolute_content_url', 'content_url', 'absolute_path', 'path'];
 const SERVER_ORCHESTRATED_TRANSPORT = 'server_orchestrated';
 const MIN_SHARE_ACCESS_CODE_LENGTH = 8;
 const MAX_SHARE_ACCESS_CODE_LENGTH = 128;
@@ -68,6 +77,7 @@ const GENERATE_PRESETS = {
         '2'
     ]
 };
+
 loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
@@ -209,22 +219,32 @@ try {
             }
         });
     } else if (shouldUsePageSse(capabilities, requestBody, options.routeMode)) {
+        const routing = {
+            ...buildPageSseSummaryRouting(),
+            fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
+            fallback_mode: 'manual_after_diagnosis'
+        };
         try {
             const result = await runPageSseRequest();
-            console.log(
-                JSON.stringify(
-                    await buildSuccessOutput(formatPageSseOutput(result), {
-                        ...buildPageSseSummaryRouting(),
-                        fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
-                        fallback_mode: 'manual_after_diagnosis'
-                    }, completeScriptTiming(scriptTiming)),
-                    null,
-                    2
-                )
+            const checkedResult = await assertDimensionsIfRequested(
+                formatPageSseOutput(result, { preserveBase64: true })
+            );
+            await writeSuccessOutputAndExit(
+                formatPageSseOutput(checkedResult),
+                routing,
+                completeScriptTiming(scriptTiming),
+                {
+                    dimensionChecked: true
+                }
             );
-            process.exit(0);
         } catch (error) {
-            console.error(JSON.stringify(buildPageSseFailureOutput(error, completeScriptTiming(scriptTiming)), null, 2));
+            if (isDimensionCheckError(error)) {
+                console.error(JSON.stringify(buildDimensionCheckFailureOutput(error, routing), null, 2));
+                process.exit(1);
+            }
+            console.error(
+                JSON.stringify(buildPageSseFailureOutput(error, completeScriptTiming(scriptTiming)), null, 2)
+            );
             process.exit(1);
         }
     } else {
@@ -256,6 +276,7 @@ function parseArgs(argv) {
         forceWeb: undefined,
         share: false,
         shareExpiresMinutes: undefined,
+        dimensionCheck: false,
         streamMode: undefined,
         streamingStrategy: undefined,
         partialImages: undefined,
@@ -285,18 +306,25 @@ function parseArgs(argv) {
         else if (arg === '--size') parsed.size = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--quality') parsed.quality = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--n') parsed.n = readOptionValue(expandedArgv, (index += 1), arg);
-        else if (arg === '--format' || arg === '--output-format') parsed.format = readOptionValue(expandedArgv, (index += 1), arg);
-        else if (arg === '--output-compression') parsed.outputCompression = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--format' || arg === '--output-format')
+            parsed.format = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--output-compression')
+            parsed.outputCompression = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--response-mode') parsed.responseMode = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--image-backend') parsed.imageBackend = readOptionValue(expandedArgv, (index += 1), arg);
-        else if (arg === '--responses-model' || arg === '--gpt-model') parsed.responsesModel = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--responses-model' || arg === '--gpt-model')
+            parsed.responsesModel = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--thinking') parsed.thinking = readOptionValue(expandedArgv, (index += 1), arg);
-        else if (arg === '--prompt-optimization') parsed.promptOptimization = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--prompt-optimization')
+            parsed.promptOptimization = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--force-web') parsed.forceWeb = true;
         else if (arg === '--share') parsed.share = true;
-        else if (arg === '--share-expires-minutes') parsed.shareExpiresMinutes = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--share-expires-minutes')
+            parsed.shareExpiresMinutes = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--dimension-check') parsed.dimensionCheck = true;
         else if (arg === '--stream-mode') parsed.streamMode = readOptionValue(expandedArgv, (index += 1), arg);
-        else if (arg === '--streaming-strategy') parsed.streamingStrategy = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--streaming-strategy')
+            parsed.streamingStrategy = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--partial-images') parsed.partialImages = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--sse-log') parsed.sseLogPath = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(expandedArgv, (index += 1), arg);
@@ -347,7 +375,9 @@ function buildRequestBody(promptValue, parsed) {
             size: assertValidImageSizeForModel(parsed.size, parsed.model, '--size'),
             quality: parsed.quality,
             output_format: normalizeOutputFormat(parsed.format),
-            ...(readOutputCompression(parsed) !== undefined ? { output_compression: readOutputCompression(parsed) } : {}),
+            ...(readOutputCompression(parsed) !== undefined
+                ? { output_compression: readOutputCompression(parsed) }
+                : {}),
             response_mode: parsed.responseMode
         },
         parsed
@@ -362,7 +392,9 @@ function buildDryRunRequestBody(parsed) {
             size: assertValidImageSizeForModel(parsed.size, parsed.model, '--size'),
             quality: parsed.quality,
             output_format: normalizeOutputFormat(parsed.format),
-            ...(readOutputCompression(parsed) !== undefined ? { output_compression: readOutputCompression(parsed) } : {}),
+            ...(readOutputCompression(parsed) !== undefined
+                ? { output_compression: readOutputCompression(parsed) }
+                : {}),
             response_mode: parsed.responseMode
         },
         parsed
@@ -378,7 +410,9 @@ function addUpstreamStrategyFields(body, parsed) {
     return {
         ...body,
         ...(parsed.imageBackend ? { image_backend: parsed.imageBackend } : {}),
-        ...(parsed.responsesModel ? { responsesModel: readNonEmptyString(parsed.responsesModel, '--responses-model') } : {}),
+        ...(parsed.responsesModel
+            ? { responsesModel: readNonEmptyString(parsed.responsesModel, '--responses-model') }
+            : {}),
         ...(parsed.thinking ? { thinking: parsed.thinking } : {}),
         ...(parsed.promptOptimization !== undefined
             ? { promptOptimization: readBooleanOption(parsed.promptOptimization, '--prompt-optimization') }
@@ -396,6 +430,9 @@ function validateUpstreamStrategyOptions(parsed) {
     if (!RESPONSE_MODES.has(parsed.responseMode)) {
         throw new Error('--response-mode 必须是 path、base64 或 both。');
     }
+    if (parsed.dimensionCheck && !parseImageSizeValue(parsed.size)) {
+        throw new Error('--dimension-check 需要 --size 为 WIDTHxHEIGHT。');
+    }
     if (parsed.imageBackend && !IMAGE_BACKENDS.has(parsed.imageBackend)) {
         throw new Error('--image-backend 必须是 images-api、images、responses 或 responses-image-generation。');
     }
@@ -446,7 +483,8 @@ function validateResponsesModelBackend(parsed) {
 function readOutputCompression(parsed) {
     const outputFormat = normalizeOutputFormat(parsed.format);
     if (outputFormat === 'png') return undefined;
-    const value = parsed.outputCompression === undefined ? String(DEFAULT_OUTPUT_COMPRESSION) : String(parsed.outputCompression);
+    const value =
+        parsed.outputCompression === undefined ? String(DEFAULT_OUTPUT_COMPRESSION) : 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) {
@@ -670,14 +708,11 @@ async function runGenerateRequest(options = {}) {
         });
 
         if (response.ok) {
-            console.log(
-                JSON.stringify(
-                    await buildSuccessOutput(enrichImageUrls(result), options.routing, completeScriptTiming(scriptTiming)),
-                    null,
-                    2
-                )
+            await writeSuccessOutputAndExit(
+                enrichImageUrls(result),
+                options.routing,
+                completeScriptTiming(scriptTiming)
             );
-            process.exit(0);
         }
 
         const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
@@ -825,23 +860,14 @@ function assertPageSseClientRequestIdLength(clientRequestId) {
     }
 }
 
-function formatPageSseOutput(result) {
-    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;
-        }
-    }
-    return output;
+function formatPageSseOutput(result, { preserveBase64 = false } = {}) {
+    return formatSharedPageSseOutput({
+        result,
+        baseUrl,
+        responseMode: requestBody.response_mode,
+        defaultOutputFormat: requestBody.output_format,
+        preserveBase64
+    });
 }
 
 function createPageSseState() {
@@ -924,14 +950,22 @@ async function collectPageSseResult(response, signal) {
         elapsed_ms: completeScriptTiming(scriptTiming).elapsed_ms,
         final_image_count: state.completedImages.length
     });
-    return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost, sse_diagnostics: buildPageSseDiagnostics(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`);
+        fs.appendFileSync(
+            options.sseLogPath,
+            `${JSON.stringify({ at: new Date().toISOString(), raw_event: rawEvent })}\n`
+        );
     } catch (error) {
         console.warn(`SSE log write failed: ${errorMessage(error)}`);
     }
@@ -941,7 +975,10 @@ function appendPageSseTrace(event, details) {
     if (!options.sseLogPath) return;
     try {
         fs.mkdirSync(path.dirname(options.sseLogPath), { recursive: true });
-        fs.appendFileSync(options.sseLogPath, `${JSON.stringify({ at: new Date().toISOString(), event, ...details })}\n`);
+        fs.appendFileSync(
+            options.sseLogPath,
+            `${JSON.stringify({ at: new Date().toISOString(), event, ...details })}\n`
+        );
     } catch (error) {
         console.warn(`SSE log write failed: ${errorMessage(error)}`);
     }
@@ -1054,11 +1091,12 @@ function parsePageSseEvent(rawEvent) {
     }
 }
 
-async function buildSuccessOutput(result, routing, timing) {
+async function buildSuccessOutput(result, routing, timing, { dimensionChecked = false } = {}) {
+    const checkedResult = dimensionChecked ? result : await assertDimensionsIfRequested(result);
     const output = attachSummary(
-        routing ? { ...result, routing } : result,
+        routing ? { ...checkedResult, routing } : checkedResult,
         buildSuccessSummary({
-            result,
+            result: checkedResult,
             routing,
             timing,
             idempotencyKey,
@@ -1069,7 +1107,32 @@ async function buildSuccessOutput(result, routing, timing) {
         return output;
     }
     const shareSummary = await maybeCreateShares(output);
-    return shareSummary ? attachSummary({ ...output, shares: shareSummary.share_results }, { ...output.summary, ...shareSummary }) : output;
+    return shareSummary
+        ? attachSummary({ ...output, shares: shareSummary.share_results }, { ...output.summary, ...shareSummary })
+        : output;
+}
+
+async function writeSuccessOutputAndExit(result, routing, timing, options = {}) {
+    try {
+        console.log(JSON.stringify(await buildSuccessOutput(result, routing, timing, options), null, 2));
+        process.exit(0);
+    } catch (error) {
+        if (!isDimensionCheckError(error)) throw error;
+        console.error(JSON.stringify(buildDimensionCheckFailureOutput(error, routing), null, 2));
+        process.exit(1);
+    }
+}
+
+async function assertDimensionsIfRequested(response) {
+    if (!options.dimensionCheck) return response;
+    return assertImageDimensions({
+        response,
+        expected: parseExpectedDimensions(requestBody.size),
+        baseUrl,
+        authHeaders,
+        timeoutMs,
+        readUrlFields: DIMENSION_CHECK_URL_FIELDS
+    });
 }
 
 async function maybeCreateShares(output) {
@@ -1092,7 +1155,11 @@ async function maybeCreateShares(output) {
 async function createShareForArtifact(artifactId) {
     const body = {};
     if (options.shareExpiresMinutes !== undefined) {
-        body.expires_in_minutes = readConfiguredPositiveInteger(options.shareExpiresMinutes, '--share-expires-minutes', 1);
+        body.expires_in_minutes = readConfiguredPositiveInteger(
+            options.shareExpiresMinutes,
+            '--share-expires-minutes',
+            1
+        );
     }
     if (process.env.GPT_IMAGE_SHARE_ACCESS_CODE !== undefined) {
         body.access_code = readShareAccessCodeFromEnv();
@@ -1177,14 +1244,17 @@ function buildPageSseScriptFailure(error, diagnostics, timing) {
         routing: buildPageSseRouting('manual_after_diagnosis'),
         next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到其他端点。'
     };
-    return attachSummary(output, buildFailureSummary({
-        errorBody: output,
-        routing: output.routing,
-        timing,
-        idempotencyKey,
-        billable: false,
-        nextAction: 'fix_capability_or_auth'
-    }));
+    return attachSummary(
+        output,
+        buildFailureSummary({
+            errorBody: output,
+            routing: output.routing,
+            timing,
+            idempotencyKey,
+            billable: false,
+            nextAction: 'fix_capability_or_auth'
+        })
+    );
 }
 
 function buildPageSseRequestRejectedFailure(error, diagnostics, timing) {
@@ -1200,14 +1270,17 @@ function buildPageSseRequestRejectedFailure(error, diagnostics, timing) {
         routing: buildPageSseRouting('fix_request_before_retry'),
         next_step: '先修正页面端拒绝的请求参数或鉴权，再重新执行；这类本地 4xx 不应按上游计费失败处理。'
     };
-    return attachSummary(output, buildFailureSummary({
-        errorBody: output,
-        routing: output.routing,
-        timing,
-        idempotencyKey,
-        billable: false,
-        nextAction: 'fix_request_before_retry'
-    }));
+    return attachSummary(
+        output,
+        buildFailureSummary({
+            errorBody: output,
+            routing: output.routing,
+            timing,
+            idempotencyKey,
+            billable: false,
+            nextAction: 'fix_request_before_retry'
+        })
+    );
 }
 
 function buildBillablePageSseFailure(error, diagnostics, timing) {
@@ -1224,14 +1297,17 @@ function buildBillablePageSseFailure(error, diagnostics, timing) {
         next_step:
             '先用 diagnose-request 诊断页面流式失败原因，再用新的 Idempotency-Key 显式选择服务端编排入口或其他诊断路径。'
     };
-    return attachSummary(output, buildFailureSummary({
-        errorBody: output,
-        routing: output.routing,
-        timing,
-        idempotencyKey,
-        billable: true,
-        nextAction: 'diagnose_then_new_idempotency_key'
-    }));
+    return attachSummary(
+        output,
+        buildFailureSummary({
+            errorBody: output,
+            routing: output.routing,
+            timing,
+            idempotencyKey,
+            billable: true,
+            nextAction: 'diagnose_then_new_idempotency_key'
+        })
+    );
 }
 
 function buildFailureOutput(output, routing) {
@@ -1242,11 +1318,16 @@ function buildFailureOutput(output, routing) {
             routing,
             timing: completeScriptTiming(scriptTiming),
             idempotencyKey,
-            billable: output?.billable !== false
+            billable: output?.billable !== false,
+            nextAction: output?.next_step
         })
     );
 }
 
+function buildDimensionCheckFailureOutput(error, routing) {
+    return buildFailureOutput(buildDimensionCheckFailureBody(error, routing), routing);
+}
+
 async function buildAgentFailureOutput(output, routing) {
     const failure = buildFailureOutput(output, routing);
     const enriched = await enrichFailureWithAgentDiagnostics({
@@ -1308,14 +1389,7 @@ async function runGenerateJob(options = {}) {
 
         if (response.ok) {
             const jobResult = await pollJobResult(result?.job);
-            console.log(
-                JSON.stringify(
-                    await buildSuccessOutput(enrichImageUrls(jobResult), routing, completeScriptTiming(scriptTiming)),
-                    null,
-                    2
-                )
-            );
-            process.exit(0);
+            await writeSuccessOutputAndExit(enrichImageUrls(jobResult), routing, completeScriptTiming(scriptTiming));
         }
 
         const retryAfter = parseRetryAfterValue(response.headers.get('retry-after'));
@@ -1325,16 +1399,7 @@ async function runGenerateJob(options = {}) {
         await sleep(retryAfter);
     }
 
-    console.error(
-        JSON.stringify(
-            buildFailureOutput(
-                { ...lastResult, retry_after: lastRetryAfter },
-                routing
-            ),
-            null,
-            2
-        )
-    );
+    console.error(JSON.stringify(buildFailureOutput({ ...lastResult, retry_after: lastRetryAfter }, routing), null, 2));
     process.exit(1);
 }
 
@@ -1419,7 +1484,9 @@ async function checkContractEndpoint(endpoint) {
         timeoutMs
     });
     if (response.status !== 400 || result?.error?.code !== 'idempotency_key_required') {
-        console.error(JSON.stringify({ ok: false, billable: false, endpoint, status: response.status, result }, null, 2));
+        console.error(
+            JSON.stringify({ ok: false, billable: false, endpoint, status: response.status, result }, null, 2)
+        );
         process.exit(1);
     }
     return { endpoint, status: response.status, error_code: result.error.code };
@@ -1444,7 +1511,13 @@ async function checkPageSseContract() {
         timeoutMs
     });
     if (response.status !== 400 || !text.includes('clientRequestId')) {
-        console.error(JSON.stringify({ ok: false, billable: false, endpoint: PAGE_SSE_ENDPOINT, status: response.status, text }, null, 2));
+        console.error(
+            JSON.stringify(
+                { ok: false, billable: false, endpoint: PAGE_SSE_ENDPOINT, status: response.status, text },
+                null,
+                2
+            )
+        );
         process.exit(1);
     }
     return {
@@ -1650,7 +1723,7 @@ function printUsage() {
     console.error('用法：generate-image.mjs [options] <prompt>');
     console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
     console.error(
-        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --share --share-expires-minutes --sse-log --timeout-ms --base-url --prompt-file --idempotency-key --check-remote --page-sse --agent --job --no-job(兼容别名)'
+        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --share --share-expires-minutes --dimension-check --sse-log --timeout-ms --base-url --prompt-file --idempotency-key --check-remote --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/dimension-check.mjs

@@ -0,0 +1,259 @@
+import { readImageDimensions } from './image-dimensions.mjs';
+import { errorMessage, parseImageSizeValue, resolveSameOriginUrl } from './script-utils.mjs';
+
+export const FAILURE_KIND_DIMENSION_CHECK = 'generated_artifact_failed_dimension_check';
+export const DEFAULT_DIMENSION_CHECK_MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+
+const DEFAULT_DIMENSION_CHECK_NEXT_STEP =
+    '确认当前渠道是否支持请求尺寸，或调整任务接受实际返回尺寸；重新执行必须使用新的 Idempotency-Key。';
+const DEFAULT_READ_URL_FIELDS = ['absolute_content_url', 'content_url'];
+
+export class DimensionCheckError extends Error {
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'DimensionCheckError';
+        this.code = 'dimension_check_failed';
+        this.retryable = false;
+        this.billable = true;
+        this.nextStep = details.nextStep || DEFAULT_DIMENSION_CHECK_NEXT_STEP;
+        this.expectedDimensions = details.expected;
+        this.actualDimensions = details.actual;
+        this.response = sanitizeImageResponse(details.response);
+    }
+}
+
+export function isDimensionCheckError(error) {
+    return Boolean(error && typeof error === 'object' && error.code === 'dimension_check_failed');
+}
+
+export function parseExpectedDimensions(size) {
+    return size && size !== 'auto' ? parseImageSizeValue(size) : undefined;
+}
+
+export function sanitizeImageResponse(response) {
+    if (!response || !Array.isArray(response.images)) return response;
+    return {
+        ...response,
+        images: response.images.map((image) => {
+            if (!image || typeof image !== 'object' || !Object.prototype.hasOwnProperty.call(image, 'b64_json')) {
+                return image;
+            }
+            const { b64_json: b64Json, ...safeImage } = image;
+            return {
+                ...safeImage,
+                ...(typeof b64Json === 'string' ? { b64_json_length: b64Json.length } : {})
+            };
+        })
+    };
+}
+
+export async function assertImageDimensions({
+    response,
+    expected,
+    baseUrl,
+    authHeaders,
+    timeoutMs,
+    maxImageBytes = DEFAULT_DIMENSION_CHECK_MAX_IMAGE_BYTES,
+    messagePrefix = '尺寸校验失败',
+    missingSizeMessage = '--dimension-check 需要 size 为 WIDTHxHEIGHT。',
+    nextStep,
+    readUrlFields = DEFAULT_READ_URL_FIELDS
+}) {
+    if (!expected) {
+        throw new DimensionCheckError(missingSizeMessage, { nextStep });
+    }
+    if (!Array.isArray(response?.images) || response.images.length === 0) {
+        throw new DimensionCheckError(`${messagePrefix}：响应中没有可验收的图片。`, {
+            expected,
+            response,
+            nextStep
+        });
+    }
+
+    const images = [];
+    let mismatch;
+    for (const image of response.images) {
+        let actual;
+        try {
+            const bytes = await readImageBytes({
+                image,
+                baseUrl,
+                authHeaders,
+                timeoutMs,
+                maxImageBytes,
+                readUrlFields
+            });
+            actual = readImageDimensions(bytes);
+        } catch (error) {
+            throw new DimensionCheckError(`${messagePrefix}：${errorMessage(error)}`, {
+                expected,
+                response: { ...response, images: [...images, sanitizeImageResponse({ images: [image] }).images[0]] },
+                nextStep
+            });
+        }
+        images.push({ ...image, dimensions: actual });
+        if (actual.width !== expected.width || actual.height !== expected.height) {
+            mismatch ??= actual;
+        }
+    }
+    if (mismatch) {
+        throw new DimensionCheckError(
+            `${messagePrefix}：期望 ${expected.width}x${expected.height}，实际 ${mismatch.width}x${mismatch.height}。`,
+            { expected, actual: mismatch, response: { ...response, images }, nextStep }
+        );
+    }
+    return { ...response, images };
+}
+
+export function buildDimensionCheckFailureBody(error, routing) {
+    return {
+        billable: error.billable !== false,
+        error: {
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+            expected_dimensions: readDimensionObject(error.expectedDimensions),
+            actual_dimensions: readDimensionObject(error.actualDimensions)
+        },
+        validation_failure_kind: FAILURE_KIND_DIMENSION_CHECK,
+        response: error.response,
+        routing,
+        ...(typeof error?.nextStep === 'string' ? { next_step: error.nextStep } : {})
+    };
+}
+
+async function readImageBytes({ image, baseUrl, authHeaders, timeoutMs, maxImageBytes, readUrlFields }) {
+    if (image.b64_json) {
+        assertBase64ImageSizeWithinLimit(image.b64_json, maxImageBytes);
+        const bytes = Buffer.from(image.b64_json, 'base64');
+        assertImageBytesWithinLimit(bytes.length, maxImageBytes);
+        return bytes;
+    }
+    const source = readFirstUrl(image, readUrlFields);
+    if (!source) throw new Error(`dimension-check 需要 b64_json 或 ${formatUrlFieldList(readUrlFields)}。`);
+    const resolved = resolveSameOriginUrl(baseUrl, source.url, source.field);
+    const headers = typeof authHeaders === 'function' ? authHeaders() : authHeaders;
+    const { response, bytes } = await fetchBytes(resolved, headers, timeoutMs, maxImageBytes);
+    if (!response.ok) throw new Error(`下载产物失败，状态码 ${response.status}。`);
+    return bytes;
+}
+
+function formatUrlFieldList(fields) {
+    const readable = normalizeUrlFields(fields);
+    return readable.length > 0 ? readable.join(' 或 ') : DEFAULT_READ_URL_FIELDS.join(' 或 ');
+}
+
+function readFirstUrl(image, fields) {
+    for (const field of normalizeUrlFields(fields)) {
+        if (typeof image?.[field] === 'string' && image[field]) return { field, url: image[field] };
+    }
+    return undefined;
+}
+
+function normalizeUrlFields(fields) {
+    return Array.isArray(fields)
+        ? fields.filter((field) => typeof field === 'string' && field)
+        : DEFAULT_READ_URL_FIELDS;
+}
+
+function readDimensionObject(value) {
+    if (!value || typeof value !== 'object') return null;
+    const width = Number(value.width);
+    const height = Number(value.height);
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) return null;
+    return { width, height };
+}
+
+async function fetchBytes(
+    url,
+    headers = {},
+    timeoutMs = 420000,
+    maxImageBytes = DEFAULT_DIMENSION_CHECK_MAX_IMAGE_BYTES
+) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const signal = controller.signal;
+        const response = await fetch(url, { headers, signal });
+        return { response, bytes: await readResponseBytes(response, { maxImageBytes, signal, timeoutMs }) };
+    } catch (error) {
+        if (error?.name === 'AbortError' || error?.code === 'download_timeout')
+            throw createDownloadTimeoutError(timeoutMs);
+        throw error;
+    } finally {
+        clearTimeout(timeout);
+    }
+}
+
+async function readResponseBytes(response, { maxImageBytes, signal, timeoutMs }) {
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isSafeInteger(contentLength)) assertImageBytesWithinLimit(contentLength, maxImageBytes);
+    if (!response.body) {
+        const bytes = Buffer.from(await response.arrayBuffer());
+        assertImageBytesWithinLimit(bytes.length, maxImageBytes);
+        return bytes;
+    }
+
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await readChunkWithAbort(reader, signal, timeoutMs);
+            if (done) break;
+            const chunk = Buffer.from(value);
+            total += chunk.length;
+            if (total > maxImageBytes) {
+                await reader.cancel();
+                assertImageBytesWithinLimit(total, maxImageBytes);
+            }
+            chunks.push(chunk);
+        }
+    } finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+}
+
+function readChunkWithAbort(reader, signal, timeoutMs) {
+    if (!signal) return reader.read();
+    if (signal.aborted) return Promise.reject(createDownloadTimeoutError(timeoutMs));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reader.cancel().catch(() => {});
+            reject(createDownloadTimeoutError(timeoutMs));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        reader
+            .read()
+            .then(resolve, reject)
+            .finally(() => {
+                signal.removeEventListener('abort', onAbort);
+            });
+    });
+}
+
+function createDownloadTimeoutError(timeoutMs) {
+    const error = new Error(`下载产物超时，已等待 ${timeoutMs}ms。`);
+    error.code = 'download_timeout';
+    return error;
+}
+
+function assertBase64ImageSizeWithinLimit(value, maxImageBytes) {
+    const estimatedBytes = estimateBase64DecodedBytes(value);
+    assertImageBytesWithinLimit(estimatedBytes, maxImageBytes);
+}
+
+function estimateBase64DecodedBytes(value) {
+    const normalized = String(value).replace(/\s/g, '');
+    const padding = normalized.endsWith('==') ? 2 : normalized.endsWith('=') ? 1 : 0;
+    return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
+}
+
+function assertImageBytesWithinLimit(byteLength, maxImageBytes) {
+    if (!Number.isSafeInteger(maxImageBytes) || maxImageBytes < 1) {
+        throw new Error('dimension-check 图片大小上限配置无效。');
+    }
+    if (byteLength <= maxImageBytes) return;
+    throw new Error(`图片数据超过 ${maxImageBytes} 字节限制。`);
+}

skills/gpt-image-playground-agent/scripts/lib/image-dimensions.mjs

@@ -0,0 +1,122 @@
+export function readImageDimensions(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length === 0) {
+        throw new Error('图片数据为空，无法读取尺寸。');
+    }
+    if (hasPngSignature(buffer)) {
+        return readPngDimensions(buffer);
+    }
+    if (hasWebpSignature(buffer)) {
+        return readWebpDimensions(buffer);
+    }
+    if (hasJpegSignature(buffer)) {
+        return readJpegDimensions(buffer);
+    }
+    throw new Error('无法识别图片格式。');
+}
+
+function hasPngSignature(buffer) {
+    return (
+        buffer.length >= 8 &&
+        buffer[0] === 0x89 &&
+        buffer.toString('ascii', 1, 4) === 'PNG' &&
+        buffer[4] === 0x0d &&
+        buffer[5] === 0x0a &&
+        buffer[6] === 0x1a &&
+        buffer[7] === 0x0a
+    );
+}
+
+function hasWebpSignature(buffer) {
+    return (
+        buffer.length >= 12 && buffer.toString('ascii', 0, 4) === 'RIFF' && buffer.toString('ascii', 8, 12) === 'WEBP'
+    );
+}
+
+function hasJpegSignature(buffer) {
+    return buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xd8;
+}
+
+function readPngDimensions(buffer) {
+    if (buffer.length < 24) throw new Error('PNG 图片数据截断，无法读取尺寸。');
+    if (buffer.toString('ascii', 12, 16) !== 'IHDR') throw new Error('无法读取 PNG 图片尺寸。');
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    assertPositiveDimensions(width, height, 'PNG');
+    return { width, height };
+}
+
+function readJpegDimensions(buffer) {
+    let offset = 2;
+    while (offset < buffer.length) {
+        while (offset < buffer.length && buffer[offset] === 0xff) offset += 1;
+        if (offset >= buffer.length) throw new Error('JPEG 图片数据截断，无法读取尺寸。');
+
+        const marker = buffer[offset];
+        offset += 1;
+        if (marker === 0xd9 || marker === 0xda) break;
+        if (isStandaloneJpegMarker(marker)) continue;
+
+        if (offset + 2 > buffer.length) throw new Error('JPEG 图片数据截断，无法读取尺寸。');
+        const length = buffer.readUInt16BE(offset);
+        if (length < 2) throw new Error('JPEG 图片段长度无效，无法读取尺寸。');
+        const segmentStart = offset + 2;
+        const segmentEnd = offset + length;
+        if (segmentEnd > buffer.length) throw new Error('JPEG 图片数据截断，无法读取尺寸。');
+
+        if (isJpegStartOfFrame(marker)) {
+            if (length < 8) throw new Error('JPEG 图片数据截断，无法读取尺寸。');
+            const height = buffer.readUInt16BE(segmentStart + 1);
+            const width = buffer.readUInt16BE(segmentStart + 3);
+            assertPositiveDimensions(width, height, 'JPEG');
+            return { width, height };
+        }
+        offset = segmentEnd;
+    }
+    throw new Error('无法读取 JPEG 图片尺寸。');
+}
+
+function isStandaloneJpegMarker(marker) {
+    return marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8);
+}
+
+function isJpegStartOfFrame(marker) {
+    return (
+        (marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf)
+    );
+}
+
+function readWebpDimensions(buffer) {
+    if (buffer.length < 16) throw new Error('WebP 图片数据截断，无法读取尺寸。');
+    const chunk = buffer.toString('ascii', 12, 16);
+    if (chunk === 'VP8X') {
+        if (buffer.length < 30) throw new Error('WebP 图片数据截断，无法读取尺寸。');
+        const width = 1 + buffer.readUIntLE(24, 3);
+        const height = 1 + buffer.readUIntLE(27, 3);
+        assertPositiveDimensions(width, height, 'WebP');
+        return { width, height };
+    }
+    if (chunk === 'VP8L') {
+        if (buffer.length < 25) throw new Error('WebP 图片数据截断，无法读取尺寸。');
+        const bits = buffer.readUInt32LE(21);
+        const width = (bits & 0x3fff) + 1;
+        const height = ((bits >> 14) & 0x3fff) + 1;
+        assertPositiveDimensions(width, height, 'WebP');
+        return { width, height };
+    }
+    if (chunk === 'VP8 ') {
+        if (buffer.length < 30) throw new Error('WebP 图片数据截断，无法读取尺寸。');
+        const width = buffer.readUInt16LE(26) & 0x3fff;
+        const height = buffer.readUInt16LE(28) & 0x3fff;
+        assertPositiveDimensions(width, height, 'WebP');
+        return { width, height };
+    }
+    throw new Error('无法读取 WebP 图片尺寸。');
+}
+
+function assertPositiveDimensions(width, height, format) {
+    if (width > 0 && height > 0) return;
+    throw new Error(`${format} 图片尺寸无效。`);
+}

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

@@ -5,461 +5,483 @@ 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;
+    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；请在本机私有 .env.agent.local 中设置 GPT_IMAGE_APP_PASSWORD_HASH，或导出该环境变量后重试。只有 GPT_IMAGE_AGENT_TOKEN 不能用于页面 SSE 表单鉴权。'
-    );
-  }
-  const maxLength = readPageSseClientRequestIdMaxLength(capabilities);
-  if (idempotencyKey.length > maxLength) {
-    throw createPageSseScriptError(
-      'page_sse_client_request_id_too_long',
-      `页面 SSE 的 clientRequestId 不能超过 ${maxLength} 个字符；请缩短 Idempotency-Key。`
-    );
-  }
+    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；请在本机私有 .env.agent.local 中设置 GPT_IMAGE_APP_PASSWORD_HASH，或导出该环境变量后重试。只有 GPT_IMAGE_AGENT_TOKEN 不能用于页面 SSE 表单鉴权。'
+        );
+    }
+    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);
-  const startedAtMs = Date.now();
-  appendPageSseTrace(sseLogPath, 'request_started', {
-    client_request_id: readFormDataString(formData, 'clientRequestId'),
-    endpoint: PAGE_SSE_ENDPOINT
-  });
-  try {
-    let response;
-    try {
-      response = await fetch(url, {
-        method: 'POST',
-        body: formData,
-        signal: controller.signal
-      });
-    } catch (error) {
-      appendPageSseTrace(sseLogPath, 'request_failed', {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const startedAtMs = Date.now();
+    appendPageSseTrace(sseLogPath, 'request_started', {
         client_request_id: readFormDataString(formData, 'clientRequestId'),
-        endpoint: PAGE_SSE_ENDPOINT,
-        elapsed_ms: Date.now() - startedAtMs,
-        error: errorMessage(error)
-      });
-      throw new Error(`请求失败：${url}。${errorMessage(error)}`);
-    }
-
-    const contentType = response.headers.get('content-type') || '';
-    if (contentType.includes('text/event-stream')) {
-      try {
-        return await collectPageSseResult(response, controller.signal, errorMessage, sseLogPath, {
-          startedAtMs,
-          clientRequestId: readFormDataString(formData, 'clientRequestId')
-        });
-      } catch (error) {
-        appendPageSseTrace(sseLogPath, 'request_failed', {
-          client_request_id: readFormDataString(formData, 'clientRequestId'),
-          endpoint: PAGE_SSE_ENDPOINT,
-          elapsed_ms: Date.now() - startedAtMs,
-          error: errorMessage(error)
+        endpoint: PAGE_SSE_ENDPOINT
+    });
+    try {
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                body: formData,
+                signal: controller.signal
+            });
+        } catch (error) {
+            appendPageSseTrace(sseLogPath, 'request_failed', {
+                client_request_id: readFormDataString(formData, 'clientRequestId'),
+                endpoint: PAGE_SSE_ENDPOINT,
+                elapsed_ms: Date.now() - startedAtMs,
+                error: errorMessage(error)
+            });
+            throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+        }
+
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('text/event-stream')) {
+            try {
+                return await collectPageSseResult(response, controller.signal, errorMessage, sseLogPath, {
+                    startedAtMs,
+                    clientRequestId: readFormDataString(formData, 'clientRequestId')
+                });
+            } catch (error) {
+                appendPageSseTrace(sseLogPath, 'request_failed', {
+                    client_request_id: readFormDataString(formData, 'clientRequestId'),
+                    endpoint: PAGE_SSE_ENDPOINT,
+                    elapsed_ms: Date.now() - startedAtMs,
+                    error: errorMessage(error)
+                });
+                throw error;
+            }
+        }
+
+        const text = await response.text();
+        if (!response.ok) {
+            appendPageSseTrace(sseLogPath, 'request_failed', {
+                client_request_id: readFormDataString(formData, 'clientRequestId'),
+                endpoint: PAGE_SSE_ENDPOINT,
+                elapsed_ms: Date.now() - startedAtMs,
+                status: response.status
+            });
+            throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
+        }
+        const result = parseJsonResponse(text, true, url, errorMessage);
+        appendPageSseTrace(sseLogPath, 'request_completed', {
+            client_request_id: readFormDataString(formData, 'clientRequestId'),
+            endpoint: PAGE_SSE_ENDPOINT,
+            elapsed_ms: Date.now() - startedAtMs
         });
-        throw error;
-      }
-    }
-
-    const text = await response.text();
-    if (!response.ok) {
-      appendPageSseTrace(sseLogPath, 'request_failed', {
-        client_request_id: readFormDataString(formData, 'clientRequestId'),
-        endpoint: PAGE_SSE_ENDPOINT,
-        elapsed_ms: Date.now() - startedAtMs,
-        status: response.status
-      });
-      throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
+        return result;
+    } finally {
+        clearTimeout(timeout);
     }
-    const result = parseJsonResponse(text, true, url, errorMessage);
-    appendPageSseTrace(sseLogPath, 'request_completed', {
-      client_request_id: readFormDataString(formData, 'clientRequestId'),
-      endpoint: PAGE_SSE_ENDPOINT,
-      elapsed_ms: Date.now() - startedAtMs
-    });
-    return result;
-  } 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)) {
+export function formatPageSseOutput({
+    result,
+    baseUrl,
+    responseMode = 'path',
+    defaultOutputFormat = 'png',
+    preserveBase64 = false
+}) {
+    if (!result || !Array.isArray(result.images)) return result;
     return {
-      ok: false,
-      billable: false,
-      error: {
-        code: error.scriptCode,
-        message: errorMessage(error),
-        ...(diagnostics ? { diagnostics } : {})
-      },
-      routing: buildPageSseRouting(fallbackEndpoint, fallbackMode),
-      next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到 Agent JSON。'
+        ...result,
+        images: result.images.map((image) =>
+            formatPageSseImage({ image, baseUrl, responseMode, defaultOutputFormat, preserveBase64 })
+        )
     };
-  }
-  if (isPageSseRequestRejected(error)) {
+}
+
+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: 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 不应按上游计费失败处理。'
+        ok: false,
+        billable: true,
+        error: {
+            code: 'page_sse_failed',
+            ...buildPageSseFailureStatus(error),
+            message: errorMessage(error),
+            ...(diagnostics ? { diagnostics } : {})
+        },
+        routing: buildPageSseRouting(fallbackEndpoint, fallbackMode),
+        next_step:
+            '先用 diagnose-request 诊断页面流式失败原因，再用新的 Idempotency-Key 显式选择备用路径；若改用 Agent JSON/edit 对照，必须重新校验输出尺寸和格式。'
     };
-  }
-  return {
-    ok: false,
-    billable: true,
-    error: {
-      code: 'page_sse_failed',
-      ...buildPageSseFailureStatus(error),
-      message: errorMessage(error),
-      ...(diagnostics ? { diagnostics } : {})
-    },
-    routing: buildPageSseRouting(fallbackEndpoint, fallbackMode),
-    next_step:
-      '先用 diagnose-request 诊断页面流式失败原因，再用新的 Idempotency-Key 显式选择备用路径；若改用 Agent JSON/edit 对照，必须重新校验输出尺寸和格式。'
-  };
 }
 
 export 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;
 }
 
 export function isPageSseDisabledByStreamingOptions(value) {
-  return value?.streamMode === 'non_stream' || value?.streamingStrategy === 'off';
+    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。');
-  }
+    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
-  };
+    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;
+    const error = new Error(message);
+    error.scriptCode = code;
+    return error;
 }
 
 function isPageSseScriptError(error) {
-  return Boolean(error && typeof error === 'object' && typeof error.scriptCode === 'string');
+    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);
+    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;
+    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 返回错误。';
+    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 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;
-  }
+    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)}`);
-  }
+    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, trace = {}) {
-  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);
+    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);
-  }
-  appendPageSseTrace(sseLogPath, 'request_completed', {
-    client_request_id: trace.clientRequestId,
-    endpoint: PAGE_SSE_ENDPOINT,
-    elapsed_ms: Date.now() - trace.startedAtMs,
-    final_image_count: state.completedImages.length
-  });
-  return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost, sse_diagnostics: buildPageSseDiagnostics(state) };
+    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);
+    }
+    appendPageSseTrace(sseLogPath, 'request_completed', {
+        client_request_id: trace.clientRequestId,
+        endpoint: PAGE_SSE_ENDPOINT,
+        elapsed_ms: Date.now() - trace.startedAtMs,
+        final_image_count: state.completedImages.length
+    });
+    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)}`);
-  }
+    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 appendPageSseTrace(filePath, event, details) {
-  if (!filePath) return;
-  try {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.appendFileSync(filePath, `${JSON.stringify({ at: new Date().toISOString(), event, ...details })}\n`);
-  } catch (error) {
-    console.warn(`SSE log write failed: ${error instanceof Error ? error.message : String(error)}`);
-  }
+    if (!filePath) return;
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, `${JSON.stringify({ at: new Date().toISOString(), event, ...details })}\n`);
+    } catch (error) {
+        console.warn(`SSE log write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 
 function readFormDataString(formData, name) {
-  const value = formData?.get?.(name);
-  return typeof value === 'string' ? value : undefined;
+    const value = formData?.get?.(name);
+    return typeof value === 'string' ? value : undefined;
 }
 
 function createPageSseState() {
-  return {
-    completedImages: [],
-    usage: undefined,
-    actualCost: undefined,
-    doneReceived: false,
-    completedEventCount: 0,
-    partialImageCount: 0,
-    lastEventType: undefined
-  };
+    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);
-      });
-  });
+    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;
-  }
+    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;
+    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);
+    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)}`);
-  }
+    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);
+    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;
+    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;
+    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 } : {})
-  };
+    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;
+    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, preserveBase64 }) {
+    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 (!preserveBase64 && 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 {};
+    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;
+    error.pageSseDiagnostics = buildPageSseDiagnostics(state);
+    return error;
 }
 
 function readPageSseDiagnostics(error) {
-  if (!error || typeof error !== 'object' || !error.pageSseDiagnostics) return undefined;
-  return error.pageSseDiagnostics;
+    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 } : {})
-  };
+    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-summary.mjs

@@ -1,244 +1,261 @@
 export function startScriptTiming(now = Date.now()) {
-  return {
-    startedAtMs: now,
-    startedAt: new Date(now).toISOString()
-  };
+    return {
+        startedAtMs: now,
+        startedAt: new Date(now).toISOString()
+    };
 }
 
 export function completeScriptTiming(started, now = Date.now()) {
-  return {
-    started_at: started.startedAt,
-    completed_at: new Date(now).toISOString(),
-    elapsed_ms: Math.max(0, now - started.startedAtMs)
-  };
+    return {
+        started_at: started.startedAt,
+        completed_at: new Date(now).toISOString(),
+        elapsed_ms: Math.max(0, now - started.startedAtMs)
+    };
 }
 
 export function buildSuccessSummary({ result, routing, timing, idempotencyKey, billable = true, nextAction }) {
-  const serverTiming = readObject(result?.timing);
-  const execution = readObject(result?.execution);
-  const images = Array.isArray(result?.images) ? result.images : [];
-  const imageDimensions = readResponseImageDimensions(images);
-  const timingSummary = buildTimingSummary({ clientTiming: timing, serverTiming });
-  return stableSummary({
-    ok: true,
-    billable,
-    request_id: readString(result?.request_id) || null,
-    idempotency_key: readString(result?.idempotency_key) || idempotencyKey,
-    artifact_ids: images.map((image) => image?.id).filter((value) => typeof value === 'string' && value),
-    content_urls: readImageUrls(images, ['content_url', 'path']),
-    absolute_content_urls: readImageUrls(images, ['absolute_content_url', 'absolute_path']),
-    image_dimensions: imageDimensions,
-    actual_dimensions: imageDimensions.length === 1 ? imageDimensions[0] : null,
-    cached: typeof result?.cached === 'boolean' ? result.cached : undefined,
-    started_at: timingSummary.started_at,
-    completed_at: timingSummary.completed_at,
-    elapsed_ms: timingSummary.elapsed_ms,
-    server_elapsed_ms: timingSummary.server_elapsed_ms,
-    elapsed_source: timingSummary.elapsed_source,
-    elapsed_breakdown: timingSummary.elapsed_breakdown,
-    transport: readString(execution?.transport) || readString(routing?.transport),
-    endpoint: readString(execution?.endpoint) || readString(routing?.endpoint),
-    route_mode: readString(execution?.route_mode) || readRouteMode(routing),
-    image_backend: readString(execution?.image_backend) || readString(routing?.image_backend) || null,
-    stream_mode: readString(execution?.stream_mode) || readString(routing?.stream_mode) || null,
-    streaming_strategy: readString(execution?.streaming_strategy) || readString(routing?.streaming_strategy) || null,
-    channel_request_mode: readString(execution?.channel_request_mode) || null,
-    channel_request_mode_fallback_applied:
-      typeof execution?.channel_request_mode_fallback_applied === 'boolean'
-        ? execution.channel_request_mode_fallback_applied
-        : null,
-    route_decision: readObject(execution?.route_decision) || null,
-    selected_channel_id: readString(execution?.selected_channel_id) || null,
-    upstream_host: readString(execution?.upstream_host) || null,
-    request_headers: readObject(execution?.request_headers),
-    retryable: false,
-    next_action: nextAction || 'done'
-  });
+    const serverTiming = readObject(result?.timing);
+    const execution = readObject(result?.execution);
+    const images = Array.isArray(result?.images) ? result.images : [];
+    const imageDimensions = readResponseImageDimensions(images);
+    const timingSummary = buildTimingSummary({ clientTiming: timing, serverTiming });
+    return stableSummary({
+        ok: true,
+        billable,
+        request_id: readString(result?.request_id) || null,
+        idempotency_key: readString(result?.idempotency_key) || idempotencyKey,
+        artifact_ids: images.map((image) => image?.id).filter((value) => typeof value === 'string' && value),
+        content_urls: readImageUrls(images, ['content_url', 'path']),
+        absolute_content_urls: readImageUrls(images, ['absolute_content_url', 'absolute_path']),
+        image_dimensions: imageDimensions,
+        actual_dimensions: imageDimensions.length === 1 ? imageDimensions[0] : null,
+        cached: typeof result?.cached === 'boolean' ? result.cached : undefined,
+        started_at: timingSummary.started_at,
+        completed_at: timingSummary.completed_at,
+        elapsed_ms: timingSummary.elapsed_ms,
+        server_elapsed_ms: timingSummary.server_elapsed_ms,
+        elapsed_source: timingSummary.elapsed_source,
+        elapsed_breakdown: timingSummary.elapsed_breakdown,
+        transport: readString(execution?.transport) || readString(routing?.transport),
+        endpoint: readString(execution?.endpoint) || readString(routing?.endpoint),
+        route_mode: readString(execution?.route_mode) || readRouteMode(routing),
+        image_backend: readString(execution?.image_backend) || readString(routing?.image_backend) || null,
+        stream_mode: readString(execution?.stream_mode) || readString(routing?.stream_mode) || null,
+        streaming_strategy:
+            readString(execution?.streaming_strategy) || readString(routing?.streaming_strategy) || null,
+        channel_request_mode: readString(execution?.channel_request_mode) || null,
+        channel_request_mode_fallback_applied:
+            typeof execution?.channel_request_mode_fallback_applied === 'boolean'
+                ? execution.channel_request_mode_fallback_applied
+                : null,
+        route_decision: readObject(execution?.route_decision) || null,
+        selected_channel_id: readString(execution?.selected_channel_id) || null,
+        upstream_host: readString(execution?.upstream_host) || null,
+        request_headers: readObject(execution?.request_headers),
+        retryable: false,
+        next_action: nextAction || 'done'
+    });
 }
 
 export function buildFailureSummary({ errorBody, routing, timing, idempotencyKey, billable, nextAction }) {
-  const error = readObject(errorBody?.error) || readObject(errorBody);
-  const errorMessage = readString(error?.message) || readString(errorBody?.error);
-  const diagnostics = readObject(error?.diagnostics);
-  const response = readObject(errorBody?.response);
-  const images = Array.isArray(response?.images) ? response.images : [];
-  const imageDimensions = readResponseImageDimensions(images);
-  const timingSummary = buildTimingSummary({ clientTiming: timing, diagnostics });
-  return stableSummary({
-    ok: false,
-    billable,
-    request_id: readString(error?.request_id) || null,
-    idempotency_key: idempotencyKey,
-    artifact_ids: images.map((image) => image?.id).filter((value) => typeof value === 'string' && value),
-    content_urls: readImageUrls(images, ['content_url', 'path']),
-    absolute_content_urls: readImageUrls(images, ['absolute_content_url', 'absolute_path']),
-    image_dimensions: imageDimensions,
-    expected_dimensions: readDimensionObject(error?.expected_dimensions),
-    actual_dimensions: readDimensionObject(error?.actual_dimensions),
-    dimension_check_failed: error?.code === 'dimension_check_failed' ? true : undefined,
-    started_at: timingSummary.started_at,
-    completed_at: timingSummary.completed_at,
-    elapsed_ms: timingSummary.elapsed_ms,
-    server_elapsed_ms: timingSummary.server_elapsed_ms,
-    elapsed_source: timingSummary.elapsed_source,
-    elapsed_breakdown: timingSummary.elapsed_breakdown,
-    transport: readString(routing?.transport),
-    endpoint: readString(routing?.endpoint),
-    route_mode: readRouteMode(routing),
-    image_backend: readString(routing?.image_backend) || null,
-    stream_mode: readString(routing?.stream_mode) || null,
-    streaming_strategy: readString(routing?.streaming_strategy) || null,
-    channel_request_mode: readString(diagnostics?.channel_request_mode) || null,
-    channel_request_mode_fallback_applied:
-      typeof diagnostics?.channel_request_mode_fallback_applied === 'boolean'
-        ? diagnostics.channel_request_mode_fallback_applied
-        : null,
-    route_decision: readObject(diagnostics?.route_decision) || null,
-    selected_channel_id: readString(diagnostics?.selected_channel_id) || null,
-    upstream_host: readString(diagnostics?.upstream_host) || null,
-    transport_error_kind: readString(diagnostics?.transport_error_kind),
-    retryable: typeof error?.retryable === 'boolean' ? error.retryable : undefined,
-    retry_after_seconds: readNonNegativeNumber(errorBody?.retry_after ?? diagnostics?.retry_after_seconds),
-    retry_after_ms: readNonNegativeNumber(diagnostics?.retry_after_ms),
-    cooldown_until: readString(diagnostics?.cooldown_until),
-    cooldown_target: readObject(diagnostics?.cooldown_target),
-    next_action: nextAction || buildFailureNextAction(error),
-    error_code: readString(error?.code),
-    error_message: errorMessage
-  });
+    const error = readObject(errorBody?.error) || readObject(errorBody);
+    const errorMessage = readString(error?.message) || readString(errorBody?.error);
+    const diagnostics = readObject(error?.diagnostics);
+    const response = readObject(errorBody?.response);
+    const execution = readObject(response?.execution);
+    const images = Array.isArray(response?.images) ? response.images : [];
+    const imageDimensions = readResponseImageDimensions(images);
+    const timingSummary = buildTimingSummary({ clientTiming: timing, diagnostics });
+    // Failure bodies may put final routing diagnostics on error.diagnostics even when response.execution is absent.
+    return stableSummary({
+        ok: false,
+        billable,
+        request_id: readString(error?.request_id) || null,
+        idempotency_key: idempotencyKey,
+        artifact_ids: images.map((image) => image?.id).filter((value) => typeof value === 'string' && value),
+        content_urls: readImageUrls(images, ['content_url', 'path']),
+        absolute_content_urls: readImageUrls(images, ['absolute_content_url', 'absolute_path']),
+        image_dimensions: imageDimensions,
+        expected_dimensions: readDimensionObject(error?.expected_dimensions),
+        actual_dimensions: readDimensionObject(error?.actual_dimensions),
+        dimension_check_failed: error?.code === 'dimension_check_failed' ? true : undefined,
+        started_at: timingSummary.started_at,
+        completed_at: timingSummary.completed_at,
+        elapsed_ms: timingSummary.elapsed_ms,
+        server_elapsed_ms: timingSummary.server_elapsed_ms,
+        elapsed_source: timingSummary.elapsed_source,
+        elapsed_breakdown: timingSummary.elapsed_breakdown,
+        transport: readString(execution?.transport) || readString(routing?.transport),
+        endpoint: readString(execution?.endpoint) || readString(routing?.endpoint),
+        route_mode: readString(execution?.route_mode) || readRouteMode(routing),
+        image_backend: readString(execution?.image_backend) || readString(routing?.image_backend) || null,
+        stream_mode: readString(execution?.stream_mode) || readString(routing?.stream_mode) || null,
+        streaming_strategy:
+            readString(execution?.streaming_strategy) || readString(routing?.streaming_strategy) || null,
+        channel_request_mode:
+            readString(diagnostics?.channel_request_mode) || readString(execution?.channel_request_mode) || null,
+        channel_request_mode_fallback_applied:
+            typeof diagnostics?.channel_request_mode_fallback_applied === 'boolean'
+                ? diagnostics.channel_request_mode_fallback_applied
+                : typeof execution?.channel_request_mode_fallback_applied === 'boolean'
+                  ? execution.channel_request_mode_fallback_applied
+                  : null,
+        route_decision: readObject(diagnostics?.route_decision) || readObject(execution?.route_decision) || null,
+        selected_channel_id:
+            readString(diagnostics?.selected_channel_id) || readString(execution?.selected_channel_id) || null,
+        upstream_host: readString(diagnostics?.upstream_host) || readString(execution?.upstream_host) || null,
+        transport_error_kind: readString(diagnostics?.transport_error_kind),
+        retryable: typeof error?.retryable === 'boolean' ? error.retryable : undefined,
+        retry_after_seconds: readNonNegativeNumber(errorBody?.retry_after ?? diagnostics?.retry_after_seconds),
+        retry_after_ms: readNonNegativeNumber(diagnostics?.retry_after_ms),
+        cooldown_until: readString(diagnostics?.cooldown_until),
+        cooldown_target: readObject(diagnostics?.cooldown_target),
+        next_action: nextAction || buildFailureNextAction(error),
+        error_code: readString(error?.code),
+        error_message: errorMessage
+    });
 }
 
 export function attachSummary(output, summary) {
-  return summary ? { ...output, summary } : output;
+    return summary ? { ...output, summary } : output;
 }
 
 function buildFailureNextAction(error) {
-  if (!error) return 'diagnose';
-  if (error.retryable === true) return 'retry_after_wait';
-  return 'diagnose_then_new_idempotency_key';
+    if (!error) return 'diagnose';
+    if (error.retryable === true) return 'retry_after_wait';
+    return 'diagnose_then_new_idempotency_key';
 }
 
 function stableSummary(value) {
-  return {
-    ...value,
-    request_id: value.request_id ?? null,
-    idempotency_key: value.idempotency_key ?? null,
-    artifact_ids: Array.isArray(value.artifact_ids) ? value.artifact_ids : [],
-    content_urls: Array.isArray(value.content_urls) ? value.content_urls : [],
-    absolute_content_urls: Array.isArray(value.absolute_content_urls) ? value.absolute_content_urls : [],
-    image_dimensions: Array.isArray(value.image_dimensions) ? value.image_dimensions : [],
-    expected_dimensions: value.expected_dimensions ?? null,
-    actual_dimensions: value.actual_dimensions ?? null,
-    dimension_check_failed: value.dimension_check_failed ?? false,
-    route_mode: value.route_mode ?? null,
-    image_backend: value.image_backend ?? null,
-    stream_mode: value.stream_mode ?? null,
-    streaming_strategy: value.streaming_strategy ?? null,
-    channel_request_mode: value.channel_request_mode ?? null,
-    channel_request_mode_fallback_applied: value.channel_request_mode_fallback_applied ?? null,
-    route_decision: value.route_decision ?? null,
-    selected_channel_id: value.selected_channel_id ?? null,
-    upstream_host: value.upstream_host ?? null,
-    transport_error_kind: value.transport_error_kind ?? null,
-    retry_after_ms: value.retry_after_ms ?? null,
-    retry_after_seconds: value.retry_after_seconds ?? null,
-    cooldown_until: value.cooldown_until ?? null,
-    cooldown_target: value.cooldown_target ?? null,
-    agent_diagnostics_checked: value.agent_diagnostics_checked ?? false,
-    agent_diagnostics_found: value.agent_diagnostics_found ?? false,
-    agent_diagnostics_unavailable_reason: value.agent_diagnostics_unavailable_reason ?? null,
-    agent_diagnostics_http_status: value.agent_diagnostics_http_status ?? null
-  };
+    return {
+        ...value,
+        request_id: value.request_id ?? null,
+        idempotency_key: value.idempotency_key ?? null,
+        artifact_ids: Array.isArray(value.artifact_ids) ? value.artifact_ids : [],
+        content_urls: Array.isArray(value.content_urls) ? value.content_urls : [],
+        absolute_content_urls: Array.isArray(value.absolute_content_urls) ? value.absolute_content_urls : [],
+        image_dimensions: Array.isArray(value.image_dimensions) ? value.image_dimensions : [],
+        expected_dimensions: value.expected_dimensions ?? null,
+        actual_dimensions: value.actual_dimensions ?? null,
+        dimension_check_failed: value.dimension_check_failed ?? false,
+        route_mode: value.route_mode ?? null,
+        image_backend: value.image_backend ?? null,
+        stream_mode: value.stream_mode ?? null,
+        streaming_strategy: value.streaming_strategy ?? null,
+        channel_request_mode: value.channel_request_mode ?? null,
+        channel_request_mode_fallback_applied: value.channel_request_mode_fallback_applied ?? null,
+        route_decision: value.route_decision ?? null,
+        selected_channel_id: value.selected_channel_id ?? null,
+        upstream_host: value.upstream_host ?? null,
+        transport_error_kind: value.transport_error_kind ?? null,
+        retry_after_ms: value.retry_after_ms ?? null,
+        retry_after_seconds: value.retry_after_seconds ?? null,
+        cooldown_until: value.cooldown_until ?? null,
+        cooldown_target: value.cooldown_target ?? null,
+        agent_diagnostics_checked: value.agent_diagnostics_checked ?? false,
+        agent_diagnostics_found: value.agent_diagnostics_found ?? false,
+        agent_diagnostics_unavailable_reason: value.agent_diagnostics_unavailable_reason ?? null,
+        agent_diagnostics_http_status: value.agent_diagnostics_http_status ?? null
+    };
 }
 
 function compactObject(value) {
-  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
 
 function readObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
 
 function readString(value) {
-  return typeof value === 'string' && value ? value : undefined;
+    return typeof value === 'string' && value ? value : undefined;
 }
 
 function readNonNegativeNumber(value) {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
-  return Math.round(value);
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
+    return Math.round(value);
 }
 
 function readRouteMode(routing) {
-  if (typeof routing?.route_mode === 'string' && routing.route_mode) return routing.route_mode;
-  if (routing?.transport === 'page_sse') return 'page_sse';
-  if (routing?.transport === 'server_orchestrated') return 'orchestrated';
-  if (routing?.transport === 'agent_job_polling') return 'job';
-  if (routing?.transport === 'agent_json') return 'agent';
-  return undefined;
+    if (typeof routing?.route_mode === 'string' && routing.route_mode) return routing.route_mode;
+    if (routing?.transport === 'page_sse') return 'page_sse';
+    if (routing?.transport === 'server_orchestrated') return 'orchestrated';
+    if (routing?.transport === 'agent_job_polling') return 'job';
+    if (routing?.transport === 'agent_json') return 'agent';
+    return undefined;
 }
 
 function readImageUrls(images, fields) {
-  return images
-    .map((image) => {
-      for (const field of fields) {
-        if (typeof image?.[field] === 'string' && image[field]) return image[field];
-      }
-      return undefined;
-    })
-    .filter((value) => typeof value === 'string' && value);
+    return images
+        .map((image) => {
+            for (const field of fields) {
+                if (typeof image?.[field] === 'string' && image[field]) return image[field];
+            }
+            return undefined;
+        })
+        .filter((value) => typeof value === 'string' && value);
 }
 
 function readResponseImageDimensions(images) {
-  return images
-    .map((image) => readDimensionObject(image?.dimensions) || readDimensionObject(image?.metadata?.dimensions) || readImageTopLevelDimensions(image))
-    .filter((value) => value !== undefined);
+    return images
+        .map(
+            (image) =>
+                readDimensionObject(image?.dimensions) ||
+                readDimensionObject(image?.metadata?.dimensions) ||
+                readImageTopLevelDimensions(image)
+        )
+        .filter((value) => value !== undefined);
 }
 
 function readImageTopLevelDimensions(image) {
-  if (!readObject(image)) return undefined;
-  if (!Object.prototype.hasOwnProperty.call(image, 'width')) return undefined;
-  if (!Object.prototype.hasOwnProperty.call(image, 'height')) return undefined;
-  return readDimensionObject(image);
+    if (!readObject(image)) return undefined;
+    if (!Object.prototype.hasOwnProperty.call(image, 'width')) return undefined;
+    if (!Object.prototype.hasOwnProperty.call(image, 'height')) return undefined;
+    return readDimensionObject(image);
 }
 
 function readDimensionObject(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
-  const width = readPositiveInteger(value.width);
-  const height = readPositiveInteger(value.height);
-  if (width === undefined || height === undefined) return undefined;
-  return { width, height };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const width = readPositiveInteger(value.width);
+    const height = readPositiveInteger(value.height);
+    if (width === undefined || height === undefined) return undefined;
+    return { width, height };
 }
 
 function readPositiveInteger(value) {
-  if (!Number.isInteger(value) || value <= 0) return undefined;
-  return value;
+    if (!Number.isInteger(value) || value <= 0) return undefined;
+    return value;
 }
 
 function buildTimingSummary({ clientTiming, serverTiming, diagnostics }) {
-  const serverTimingElapsedMs = readNonNegativeNumber(serverTiming?.elapsed_ms);
-  const diagnosticsElapsedMs = readNonNegativeNumber(diagnostics?.elapsed_ms);
-  const serverElapsedMs = readNonNegativeNumber(serverTiming?.server_elapsed_ms ?? serverTimingElapsedMs ?? diagnosticsElapsedMs);
-  const clientElapsedMs = readNonNegativeNumber(clientTiming?.elapsed_ms);
-  const elapsedMs = serverTimingElapsedMs ?? diagnosticsElapsedMs ?? clientElapsedMs;
-  const elapsedSource =
-    serverTimingElapsedMs !== undefined || diagnosticsElapsedMs !== undefined ? 'server_timing' : 'client_script';
-  const summary = compactObject({
-    started_at: readString(serverTiming?.started_at) || clientTiming?.started_at,
-    completed_at: readString(serverTiming?.completed_at) || clientTiming?.completed_at,
-    elapsed_ms: elapsedMs,
-    server_elapsed_ms: serverElapsedMs,
-    elapsed_source: elapsedSource,
-    elapsed_breakdown: buildElapsedBreakdown(clientElapsedMs, serverElapsedMs)
-  });
-  return summary;
+    const serverTimingElapsedMs = readNonNegativeNumber(serverTiming?.elapsed_ms);
+    const diagnosticsElapsedMs = readNonNegativeNumber(diagnostics?.elapsed_ms);
+    const serverElapsedMs = readNonNegativeNumber(
+        serverTiming?.server_elapsed_ms ?? serverTimingElapsedMs ?? diagnosticsElapsedMs
+    );
+    const clientElapsedMs = readNonNegativeNumber(clientTiming?.elapsed_ms);
+    const elapsedMs = serverTimingElapsedMs ?? diagnosticsElapsedMs ?? clientElapsedMs;
+    const elapsedSource =
+        serverTimingElapsedMs !== undefined || diagnosticsElapsedMs !== undefined ? 'server_timing' : 'client_script';
+    const summary = compactObject({
+        started_at: readString(serverTiming?.started_at) || clientTiming?.started_at,
+        completed_at: readString(serverTiming?.completed_at) || clientTiming?.completed_at,
+        elapsed_ms: elapsedMs,
+        server_elapsed_ms: serverElapsedMs,
+        elapsed_source: elapsedSource,
+        elapsed_breakdown: buildElapsedBreakdown(clientElapsedMs, serverElapsedMs)
+    });
+    return summary;
 }
 
 function buildElapsedBreakdown(clientElapsedMs, serverElapsedMs) {
-  if (clientElapsedMs === undefined && serverElapsedMs === undefined) return undefined;
-  return compactObject({
-    client_script_ms: clientElapsedMs,
-    upstream_or_server_ms: serverElapsedMs,
-    client_overhead_ms:
-      clientElapsedMs !== undefined && serverElapsedMs !== undefined ? Math.max(0, clientElapsedMs - serverElapsedMs) : undefined
-  });
+    if (clientElapsedMs === undefined && serverElapsedMs === undefined) return undefined;
+    return compactObject({
+        client_script_ms: clientElapsedMs,
+        upstream_or_server_ms: serverElapsedMs,
+        client_overhead_ms:
+            clientElapsedMs !== undefined && serverElapsedMs !== undefined
+                ? Math.max(0, clientElapsedMs - serverElapsedMs)
+                : undefined
+    });
 }

src/app/api/deploy-marker/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"b908b02b1ca43bf88871a9ffb18a6bc9421263ad","created_at":"2026-07-03T18:03:10.848Z","deploy_id":"3662dde9-7453-4db4-872d-b86510c45633"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"e9050df6c33f04cecaad6d1fcd2c7714a262bb12","created_at":"2026-07-06T10:09:57.902Z","deploy_id":"572b33fc-af8f-417f-bc6f-70cf33b54c06"} as const;
 
 export const dynamic = 'force-dynamic';