Deploy 3a8b0c7 to Docker Space

Source: MisonL/gpt-image-playground-customer@3a8b0c75f35f7fb9ad0e6b81cae55bd49ca2572a

.env.example

@@ -96,9 +96,13 @@ OPENAI_API_BASE_URL=
 # 要使用 Responses 后端，需要请求显式传入 image_backend=responses-image-generation，
 # 或把 IMAGE_GENERATION_BACKEND 设为 responses-image-generation / responses；
 # 两种方式都需要单独配置 /responses 顶层模型。
+# OPENAI_RESPONSES_API_MODEL 是服务端默认顶层模型，页面请求可用 responsesModel、
+# responses_model、gptModel 或 gpt_model 覆盖单次请求。
+# 该配置只影响本项目的 responses-image-generation 路径，不改变兼容上游自身
+# /v1/images/generations 桥接层内部选择的模型。
 # 表单 model 只作为 image_generation 工具模型，不会复用为 /responses 顶层模型。
 # ENABLE_RESPONSES_IMAGE_BACKEND=true
-# OPENAI_RESPONSES_API_MODEL=
+# OPENAI_RESPONSES_API_MODEL=gpt-5.4
 
 # 可选：独立真实上游 smoke 目标。默认不触发计费请求，必须显式运行 --allow-billable。
 # 每组至少提供 BASE_URL 和 API_KEY；MODEL、SIZE、QUALITY、RESPONSES_MODEL 可按上游覆盖。

README.md

@@ -17,27 +17,20 @@ app_port: 4783
 
 ## 快速开始
 
-第一次配置或换机器后，先跑只读就绪检查。它不会写配置、不会输出密钥、不会触发真实生图：
+第一次配置或换机器后，先跑只读就绪检查。它不会写配置、输出密钥或触发真实生图：
 
 ```bash
 npm run first-run
 ```
 
-该命令默认输出中文摘要；给 Agent 或脚本消费时加 `--json`。它会检查 Node、依赖、`.env.local` / `.env.agent.local` 摘要、默认本地服务 `http://localhost:4783`、Agent capabilities 和下一步动作。检查公网或 Space 服务时显式传地址：
+检查公网或 Space 服务时显式传地址；给脚本消费时加 `--json`：
 
 ```bash
 npm run first-run -- --base-url https://your-space.hf.space
 npm run first-run -- --json --base-url https://your-space.hf.space
 ```
 
-首次配置最短路径：
-
-1. 运行 `npm install`。
-2. 启动服务：本地开发用 `npm run dev`，Docker 用 `docker compose up -d --build --remove-orphans`。
-3. 运行 `npm run first-run` 看中文摘要；如果要检查 Space 或内网服务，使用 `npm run first-run -- --base-url <url>`。
-4. 如果 Agent API 需要鉴权，复制 `.env.agent.local.example` 为 `.env.agent.local` 并填入本机私有 token。Agent CLI 会从当前仓库根目录自动读取该文件；shell 环境变量仍然优先。
-
-推荐 Docker：
+本地服务推荐用 Docker：
 
 ```bash
 docker compose up -d --build --remove-orphans
@@ -56,7 +49,7 @@ OPENAI_API_KEY=your_openai_api_key_here
 OPENAI_API_BASE_URL=https://api.openai.com/v1
 ```
 
-本地开发：
+开发模式：
 
 ```bash
 npm install
@@ -106,6 +99,7 @@ start-windows.bat
 | 图片存储 | `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_MAX_STREAMS_PER_CREDENTIAL` | 单个渠道凭证允许同时执行的图片请求数，默认 `1`。 |
 | 渠道队列 | `OPENAI_CHANNEL_QUEUE_ENABLED`、`OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS`、`OPENAI_CHANNEL_QUEUE_MAX_SIZE` | 控制超出凭证容量时等待还是立即失败。 |
@@ -142,18 +136,20 @@ OPENAI_CHANNEL_3_UPSTREAM_PROFILE=matsca
 
 - 自定义 API URL 必须同时填写自定义 API Key，避免服务端密钥被发送到未知地址。
 - Docker compose 本身不把默认图片后端改成 Responses；未在 `.env.local` 显式配置时仍是 `images-api` 和 `auto`。
-- Responses image backend 需要 `ENABLE_RESPONSES_IMAGE_BACKEND=true` 和 `OPENAI_RESPONSES_API_MODEL`。
+- Responses image backend 需要 `ENABLE_RESPONSES_IMAGE_BACKEND=true` 和 `OPENAI_RESPONSES_API_MODEL`。页面请求也可以用 `responsesModel`、`responses_model`、`gptModel` 或 `gpt_model` 覆盖单次 `/responses` 顶层模型；这些字段只影响本项目的 `responses-image-generation` 路径，不会改变兼容上游自身 `/v1/images/generations` 桥接层内部选择的模型。
 - Matsca、extra headers、provider manifest、真实上游 smoke 等高级配置以 [.env.example](./.env.example) 为准。
 
 ## Agent API
 
-Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先读取 capabilities，再按返回的认证方式、路由规则、状态后端和端点能力选择路径。
+Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先读取 capabilities，再按返回的认证、路由和端点能力选择路径。
+
+新增 probe、diagnostics 或路由可观测能力时，先落 API / capabilities / OpenAPI 契约，再让 Skill 脚本做薄封装；不要让脚本自己复制页面与 Agent 的边界判断。
 
 常用入口：
 
 | 接口 | 用途 |
 | --- | --- |
-| `GET /api/agent/capabilities` | 查询模型、限制、认证方式、状态后端和路由规则。 |
+| `GET /api/agent/capabilities` | 查询模型、限制、认证方式和路由规则。 |
 | `GET /api/agent/openapi.json` | 获取 OpenAPI 描述。 |
 | `POST /api/agent/images/generate` | JSON 文生图。 |
 | `POST /api/agent/images/edit` | multipart 图片编辑，支持源图和 mask。 |
@@ -162,7 +158,7 @@ Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先
 | `GET /api/agent/jobs/{id}/result` | 读取成功 job 的标准图片响应。 |
 | `GET /api/agent/artifacts/{id}/content` | 下载产物图片。 |
 | `POST /api/agent/diagnostics/page-requests` | 批量读取页面请求的脱敏日志诊断摘要。 |
-| `GET /api/agent/diagnostics/requests` | 按 Agent request id 或幂等键查询 Agent state 请求诊断。 |
+| `GET /api/agent/diagnostics/requests` | 按 request id 或幂等键查询诊断。 |
 
 生成示例：
 
@@ -179,7 +175,7 @@ curl -s http://localhost:4783/api/agent/images/generate \
 - [skills/gpt-image-playground-agent/SKILL.md](./skills/gpt-image-playground-agent/SKILL.md)
 - [Agent API 参考](./skills/gpt-image-playground-agent/references/api.md)
 
-脚本默认 dry-run，不触发真实计费请求；真实生成必须显式添加 `--allow-billable`。
+脚本默认 dry-run，不触发真实计费请求；真实生成必须显式添加 `--allow-billable`：
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
@@ -190,17 +186,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 ### AI Agent 典型使用方式
 
-AI Agent 集成时优先调用 skill 内置脚本，而不是临时手写 fetch、curl 或表单提交逻辑。脚本会先读取 capabilities，自动处理鉴权、幂等键、路由选择、超时、产物 URL 和结构化失败摘要。
-
-交互式任务中，Agent 应先定位服务地址：用户明确提供 URL 时直接使用该 URL；否则先检查 `GPT_IMAGE_PLAYGROUND_URL`，再探测默认本地地址 `http://localhost:4783`。如果只发现环境变量或本地服务，先向用户确认是否使用；用户提供其他地址时，以用户提供的地址为准。非交互式任务无法确认时，按同一顺序自动选择，并在输出里说明地址来源。
-
-新环境或不确定服务地址时先运行 `npm run first-run`。它会只读报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权，以及 `.env.agent.local` 是否存在私有鉴权配置。Agent CLI 会从当前仓库根目录自动读取 `.env.agent.local`，shell 环境变量仍然优先；如需禁用自动读取，设置 `GPT_IMAGE_AGENT_LOAD_ENV_FILE=0`。
-
-dry-run 只做本地请求构造和静态路由规划，不读取远端 capabilities，也不验证远端鉴权、渠道容量或 manifest 写入。脚本输出里的 `verification_scope.mode=local_planning_only` 表示还没有证明远端服务可执行；需要远端合同检查时使用 `--contract-check`，真实执行必须显式添加 `--allow-billable`。
-
-subagent 或自动化任务要固定服务地址时，优先给脚本传 `--base-url`，不要只依赖默认 localhost。`generate-image.mjs`、`edit-image.mjs`、`batch-images.mjs`、`diagnose-request.mjs` 和 `npm run agent:doctor -- --base-url <url>` 都支持显式服务地址。首次配置 Agent 鉴权时复制 `.env.agent.local.example` 为 `.env.agent.local` 并填入本机私有 token；不要把 `.env.agent.local` 提交或粘到任务日志。
-
-公网部署常见有两层鉴权：`GPT_IMAGE_AGENT_TOKEN` 只用于 `/api/agent/*` Bearer 鉴权；页面 SSE `/api/images` 仍可能要求 `GPT_IMAGE_APP_PASSWORD_HASH` 作为 `passwordHash` 表单字段。使用 `--page-sse`、Responses backend edit、大图默认页面 SSE 或批量页面 SSE 前，先用 `npm run first-run -- --base-url <url> --json` 或 `npm run agent:doctor -- --base-url <url>` 检查 `page_sse_auth_available_to_process` / `page_sse_auth_ready`。
+AI Agent 集成时优先调用 skill 脚本，不要临时手写 fetch、curl 或表单提交逻辑。脚本会处理 capabilities、鉴权、幂等键、路由、超时、产物 URL 和结构化失败摘要。
 
 1. 只读检查当前服务能力，不触发计费：
 
@@ -211,7 +197,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   "capability check"
 ```
 
-2. 先 dry-run 单张文生图，确认请求字段和路由：
+2. dry-run 单张文生图，确认请求字段和路由：
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
@@ -223,7 +209,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   "a clean product photo of a ceramic mug"
 ```
 
-3. 用户明确允许后，再执行真实计费请求：
+3. 用户明确允许后执行真实请求：
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
@@ -237,7 +223,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   "a clean product photo of a ceramic mug"
 ```
 
-4. 图生图默认 WebP 输出，走页面 SSE 路径：
+4. 图生图：
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/edit-image.mjs \
@@ -266,17 +252,6 @@ node skills/gpt-image-playground-agent/scripts/batch-images.mjs \
   --ordered-prefix product-set
 ```
 
-真实批量执行时再添加 `--allow-billable`。多张真实任务优先使用 `batch-images.mjs`、`--manifest`、`--resume` 和 `--dimension-check`；不要手动并行启动多个单张脚本，否则会绕过续跑记录、容量反馈和尺寸门禁。需要并发时添加 `--concurrency N`，并确认 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 允许；建议并发为 `1` 时保持串行。
-
-页面 SSE 返回 503 或断流时，先用诊断脚本读取结构化摘要，再用新的幂等键���式选择备用路径。`edit-image.mjs --agent --stream-mode non_stream --streaming-strategy off` 只适合作为对照诊断；Agent edit 输出格式和尺寸可能与页面 SSE 不完全一致，尺寸敏感任务必须重新校验或用 `--dimension-check`。
-
-排查环境配置时不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。Codex 会话日志会持久保存命令输出；优先运行 `npm run env:summary`，或在命令中先把 `API_KEY`、`TOKEN`、`PASSWORD`、`SECRET` 值替换为 `<redacted>`。
-
-```bash
-npm run env:summary
-npm run env:summary -- --file .env.local --container gpt-image-playground-customer
-```
-
 6. 失败或结果需要追踪时，用诊断脚本读摘要：
 
 ```bash
@@ -285,7 +260,7 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
   --idempotency-key agent-demo-generate-001
 ```
 
-页面 SSE 请求通常用同一个业务 key 作为 `clientRequestId`，也可以这样查：
+页面 SSE 请求通常用同一个业务 key 作为 `clientRequestId`：
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
@@ -293,61 +268,20 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
   --client-request-id agent-demo-edit-001
 ```
 
-远程 Space、云服务或内网服务必须显式固定目标地址，避免误查本机默认服务：
-
-```bash
-node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
-  --base-url https://your-space.hf.space \
-  --idempotency-key agent-demo-generate-001
-```
-
-首次配置和诊断输出字段速查：
-
-| 字段 | 出现位置 | 判断口径 |
-| --- | --- | --- |
-| `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` 真实计费请求。 |
-| `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` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
-
-常用环境变量：
-
-| 变量 | 用途 |
-| --- | --- |
-| `GPT_IMAGE_PLAYGROUND_URL` | 指向本机、内网或公网部署地址；未设置时脚本默认尝试 `http://localhost:4783`。交互式任务中，自动发现到本地服务后应先向用户确认。 |
-| `GPT_IMAGE_AGENT_TOKEN` | Agent Bearer token，对应服务端 `AGENT_API_TOKEN`。 |
-| `GPT_IMAGE_APP_PASSWORD_HASH` | 使用页面访问码部署时的访问码哈希；页面 SSE 会作为 `passwordHash` 表单字段发送。 |
-| `GPT_IMAGE_AGENT_IDEMPOTENCY_KEY` | 跨脚本进程复用同一业务操作的幂等键。 |
-
-Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端 Space 配置了 `AGENT_API_TOKEN` 后，本机 Agent 仍需要通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；如果 Space 同时配置了 `APP_PASSWORD`，页面 SSE 还需要 `GPT_IMAGE_APP_PASSWORD_HASH`。Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`，shell 环境变量优先。不要把 token、访问码或哈希写进 README、任务 JSONL、manifest 或命令日志。仓库提供 `.env.agent.local.example` 作为私有本机配置模板。
-
-接口边界：
+关键规则：
 
-- `/api/agent/*` 是自动化机器契约，返回最终 JSON，不向客户端返回 SSE。
-- `POST /api/images` 是 WebUI form-data 路径，支持页面 SSE、页面访问码表单鉴权和高级图片字段。
-- `GET /api/runtime-capabilities` 是页面运行态能力 API，不进入 Agent OpenAPI。
-- 页面反馈、分享、��志和文件删除 API 使用页面鉴权或页面文件名契约，不复用 Agent Bearer token。
+- 交互式任务中，如果只发现本地服务或 `GPT_IMAGE_PLAYGROUND_URL`，先向用户确认；用户给了 URL 时以用户 URL 为准。
+- 远程 Space、云服务或内网服务必须显式传 `--base-url`，避免误用本机默认服务。
+- Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`；shell 环境变量优先。首次配置可复制 `.env.agent.local.example`。不要提交 token、访问码或哈希。
+- `GPT_IMAGE_AGENT_TOKEN` 只用于 `/api/agent/*`；页面 SSE `/api/images` 可能还需要 `GPT_IMAGE_APP_PASSWORD_HASH`。
+- dry-run 只验证本地请求构造；`verification_scope.mode=local_planning_only` 不是远端已可执行。远端合同检查用 `--contract-check`，真实执行必须加 `--allow-billable`。
+- 多张真实任务优先用 `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 的范围。
-- 灵感相册和历史复用是浏览器工作台体验，不作为机器 API 契约承诺。
-
-边界矩阵：
-
-| 能力或端点 | 归属契约 | 进入 Agent OpenAPI | 自动化口径 |
-| --- | --- | --- | --- |
-| `POST /api/agent/images/generate`、`POST /api/agent/images/edit`、Agent jobs、Agent artifacts | Agent API | 是 | 通过 skill 脚本和 Agent 鉴权调用。 |
-| `POST /api/images` | 页面 form-data SSE API | 否 | 默认 WebP edit、页面高级字段、大图或复杂批量需要时由 skill 显式选择。 |
-| `GET /api/runtime-capabilities` | 页面运行态能力 API | 否 | 只读查看流式默认值、图片上游传输、渠道健康和队列状态。 |
-| `PUT/DELETE /api/feedback` | 页面结果反馈 API | 否 | 页面写入和清理反馈；Agent 只读查询用 `/api/agent/page-requests/feedback` 或 `/api/agent/page-requests/{id}/feedback`。 |
-| `POST /api/agent/page-requests/feedback`、`GET /api/agent/page-requests/{id}/feedback` | Agent 结果反馈只读 API | 是 | Agent 按页面 `clientRequestId` 查询反馈。 |
-| `POST /api/agent/diagnostics/page-requests`、`GET /api/agent/diagnostics/page-requests/{id}` | Agent 页面请求诊断 API | 是 | Agent 按页面 `clientRequestId` 查询脱敏日志摘要，不直接读 `/api/logs`。 |
-| `GET /api/logs` | 页面日志 SSE API | 否 | 页面使用访问码哈希读取；不接受 Agent token。 |
-| `POST /api/shares`、`GET /api/shares/{token}`、`POST /api/shares/{token}/content` | 页面分享 API | 否 | 使用页面 cookie、访问码和分享 token。 |
-| `POST /api/image-delete` | 页面图片文件删除 API | 否 | 按页面文件名删除 `generated-images/` 文件，不删除 Agent artifact 状态。 |
+- 页面 SSE 返回 503 或断流时，先用诊断脚本读取结构化摘要，再用新的幂等键显式选择备用路径。`page_sse_supported=true` 只是声明支持，不代表实测一定成功。Agent edit 输出格式和尺寸可能与页面 SSE 不完全一致，尺寸敏感任务必须重新校验或用 `--dimension-check`。
+- 排查环境配置时优先运行 `npm run env:summary`，不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。
+- Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。
+- 边界矩阵精简版：
+- `/api/agent/*` 返回最终 JSON；`POST /api/images`、`GET /api/runtime-capabilities`、`/api/feedback`、`/api/shares`、`/api/logs` 和 `POST /api/image-delete` 属于页面或运行态 API，不进入 Agent OpenAPI。Agent 只读反馈和诊断入口是 `/api/agent/page-requests/feedback`、`/api/agent/page-requests/{id}/feedback`、`/api/agent/diagnostics/page-requests` 和 `/api/agent/diagnostics/page-requests/{id}`。灵感相册和历史复用是浏览器工作台体验，不作为机器 API 契约承诺。
 
 ## Docker 与部署
 

scripts/agent-doctor.mjs

@@ -11,6 +11,7 @@ import {
 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 PAGE_SSE_GENERATE_SMOKE_NAME = 'responses_page_sse_generate_1k';
 
 export function buildAgentDoctorArgs() {
     return [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000', 'contract check'];
@@ -129,6 +130,7 @@ function buildSkippedSmoke(options) {
         reason: 'requires --allow-billable',
         checks: [
             { name: 'generate_1k', skipped: true, reason: 'requires --allow-billable' },
+            { name: PAGE_SSE_GENERATE_SMOKE_NAME, skipped: true, reason: 'requires --allow-billable' },
             {
                 name: 'edit_1k',
                 skipped: true,
@@ -160,6 +162,28 @@ function runBillableSmoke(options, baseUrl) {
             '--idempotency-key',
             `agent-doctor-generate-${Date.now()}`,
             'agent doctor 1k generate smoke'
+        ]),
+        runSmokeCommand(PAGE_SSE_GENERATE_SMOKE_NAME, [
+            GENERATE_SCRIPT,
+            '--base-url',
+            baseUrl,
+            '--allow-billable',
+            '--page-sse',
+            '--timeout-ms',
+            String(options.timeoutMs),
+            '--size',
+            '1024x1024',
+            '--quality',
+            'low',
+            '--image-backend',
+            'responses-image-generation',
+            '--stream-mode',
+            'stream',
+            '--streaming-strategy',
+            'responses-sse',
+            '--idempotency-key',
+            `agent-doctor-responses-page-sse-generate-${Date.now()}`,
+            'agent doctor responses page SSE generate smoke'
         ])
     ];
     if (options.editImage) {
@@ -266,6 +290,7 @@ function buildLayers({ capabilities, runtime, contract, smoke }) {
 function summarizeCapabilities(body) {
     return {
         page_sse: body?.agent_streaming?.page_sse?.supported === true,
+        page_sse_declared_supported: body?.agent_streaming?.page_sse?.supported === true,
         page_sse_auth_required: body?.agent_streaming?.page_sse?.auth?.required === true,
         page_sse_auth_ready:
             body?.agent_streaming?.page_sse?.auth?.required === true
@@ -301,6 +326,7 @@ function summarizeStateBackend(body) {
 function summarizeResponsesReadiness(capabilities, runtime) {
     const requirements = capabilities?.supported?.image_backend_requirements?.['responses-image-generation'];
     return {
+        declared_supported: requirements?.supported === true,
         backend_supported: requirements?.supported === true,
         backend_enabled: requirements?.enabled === true,
         runtime_enabled: runtime?.responsesImageBackend?.enabled === true,
@@ -317,19 +343,32 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
         contract_check: contract.ok ? 'ok' : 'failed',
         runtime: runtime.ok ? 'ok' : 'failed',
         state_backend: capabilities.ok ? capabilities.body?.defaults?.state_backend : 'unknown',
+        page_sse_declared_supported: capabilities.ok
+            ? capabilities.body?.agent_streaming?.page_sse?.supported === true
+            : false,
         page_sse_auth_ready:
             capabilities.ok && capabilities.body?.agent_streaming?.page_sse?.auth?.required === true
                 ? Boolean(process.env.GPT_IMAGE_APP_PASSWORD_HASH)
                 : capabilities.ok,
+        page_sse_real_smoke: summarizeSmokeCheck(smoke, PAGE_SSE_GENERATE_SMOKE_NAME),
         responses_gpt2image_ready:
             capabilities.ok && runtime.ok
                 ? 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
+            : false,
         billable_smoke: smoke.skipped ? 'skipped' : smoke.ok ? 'ok' : 'failed'
     };
 }
 
+function summarizeSmokeCheck(smoke, name) {
+    const check = smoke.checks?.find((item) => item.name === name);
+    if (!check || check.skipped) return 'skipped';
+    return check.ok ? 'passed' : 'failed';
+}
+
 function authHeaders() {
     if (process.env.GPT_IMAGE_AGENT_TOKEN) return { Authorization: `Bearer ${process.env.GPT_IMAGE_AGENT_TOKEN}` };
     if (process.env.GPT_IMAGE_APP_PASSWORD_HASH) return { 'X-App-Password-Hash': process.env.GPT_IMAGE_APP_PASSWORD_HASH };

scripts/agent-skill-scripts.test.mjs

@@ -3,7 +3,8 @@ import {
     readCapabilitiesImageTransportTimeoutMs,
     resolveSameOriginUrl
 } from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
-import { AGENT_ENDPOINTS } from '../src/lib/agent-api-paths.mjs';
+import { enrichFailureWithAgentDiagnostics } from '../skills/gpt-image-playground-agent/scripts/lib/agent-diagnostics-summary.mjs';
+import { AGENT_ENDPOINTS } from '../skills/gpt-image-playground-agent/scripts/lib/agent-api-paths.mjs';
 import assert from 'node:assert/strict';
 import { spawn, spawnSync } from 'node:child_process';
 import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -85,6 +86,89 @@ describe('Agent skill script argument validation', () => {
         assert.equal(probeResult.stdout.trim(), '');
     });
 
+    it('caps Agent diagnostics enrichment timeout independently of image request timeouts', async () => {
+        const startedAt = Date.now();
+        const result = await enrichFailureWithAgentDiagnostics({
+            baseUrl: 'http://example.test/playground',
+            authHeaders: () => ({}),
+            idempotencyKey: 'slow-diagnostics-key',
+            failureOutput: { ok: false, error: { code: 'network_error' } },
+            summary: {
+                ok: false,
+                retryable: true,
+                next_action: 'retry_after_wait'
+            },
+            timeoutMs: 420000,
+            diagnosticsTimeoutMs: 25,
+            fetchFn: (_url, init) =>
+                new Promise((_resolve, reject) => {
+                    init.signal.addEventListener('abort', () => {
+                        const error = new Error('aborted');
+                        error.name = 'AbortError';
+                        reject(error);
+                    });
+                })
+        });
+
+        assert.equal(result.summary.agent_diagnostics_checked, true);
+        assert.equal(result.summary.agent_diagnostics_found, false);
+        assert.equal(result.summary.agent_diagnostics_unavailable_reason, 'diagnostics_timeout');
+        assert.equal(result.failureOutput.agent_failure_diagnostics.unavailable_reason, 'diagnostics_timeout');
+        assert.equal(result.summary.retryable, true);
+        assert.equal(result.summary.next_action, 'retry_after_wait');
+        assert.ok(Date.now() - startedAt < 1000);
+    });
+
+    it('reports non-json Agent diagnostics responses distinctly', async () => {
+        const result = await enrichFailureWithAgentDiagnostics({
+            baseUrl: 'http://example.test/playground',
+            authHeaders: () => ({}),
+            idempotencyKey: 'html-diagnostics-key',
+            failureOutput: { ok: false, error: { code: 'network_error' } },
+            summary: { ok: false },
+            timeoutMs: 420000,
+            fetchFn: async () => ({
+                ok: false,
+                status: 502,
+                headers: new Headers({ 'content-type': 'text/html' }),
+                text: async () => '<html>bad gateway</html>'
+            })
+        });
+
+        assert.equal(result.summary.agent_diagnostics_checked, true);
+        assert.equal(result.summary.agent_diagnostics_found, false);
+        assert.equal(result.summary.agent_diagnostics_unavailable_reason, 'non_json_response');
+        assert.equal(result.summary.agent_diagnostics_http_status, 502);
+        assert.equal(result.failureOutput.agent_failure_diagnostics.unavailable_reason, 'non_json_response');
+        assert.equal(result.failureOutput.agent_failure_diagnostics.http_status, 502);
+    });
+
+    it('treats found Agent diagnostics without payload as invalid', async () => {
+        const result = await enrichFailureWithAgentDiagnostics({
+            baseUrl: 'http://example.test/playground',
+            authHeaders: () => ({}),
+            idempotencyKey: 'missing-diagnostics-key',
+            failureOutput: { ok: false, error: { code: 'network_error' } },
+            summary: { ok: false },
+            timeoutMs: 420000,
+            fetchFn: async () => ({
+                ok: true,
+                status: 200,
+                headers: new Headers({ 'content-type': 'application/json' }),
+                text: async () => JSON.stringify({ found: true })
+            })
+        });
+
+        assert.equal(result.summary.agent_diagnostics_checked, true);
+        assert.equal(result.summary.agent_diagnostics_found, false);
+        assert.equal(result.summary.agent_diagnostics_unavailable_reason, 'invalid_response');
+        assert.equal(result.summary.agent_diagnostics_http_status, 200);
+        assert.equal(result.failureOutput.agent_failure_diagnostics.found, false);
+        assert.equal(result.failureOutput.agent_failure_diagnostics.unavailable_reason, 'invalid_response');
+        assert.equal(result.failureOutput.agent_failure_diagnostics.http_status, 200);
+        assert.equal(result.failureOutput.agent_failure_diagnostics.request_id, undefined);
+    });
+
     it('converts local images to webp by default', () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-convert-'));
         try {
@@ -1138,6 +1222,243 @@ describe('Agent skill script argument validation', () => {
         );
     });
 
+    it('enriches failed Agent generate summaries with Agent state diagnostics', async () => {
+        const requests = [];
+        await withServer(
+            (request, response) => {
+                requests.push({ method: request.method, url: request.url });
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: { code: 'unexpected_error', message: 'fetch failed', retryable: false } }));
+                    return;
+                }
+                if (request.url === '/api/agent/diagnostics/requests?idempotency_key=diag-generate-key') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            found: true,
+                            diagnostics: {
+                                request: {
+                                    request_id: 'req_generate_diag',
+                                    idempotency_key: 'diag-generate-key',
+                                    status: 'failed'
+                                },
+                                error: {
+                                    code: 'unexpected_error',
+                                    retryable: false,
+                                    diagnostics: {
+                                        selected_channel_id: 'channel-a',
+                                        upstream_host: 'upstream.example.test',
+                                        transport_error_kind: 'aborted'
+                                    }
+                                }
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--allow-billable', '--idempotency-key', 'diag-generate-key', '--size', '1024x1024', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.summary.request_id, 'req_generate_diag');
+                assert.equal(body.summary.selected_channel_id, 'channel-a');
+                assert.equal(body.summary.upstream_host, 'upstream.example.test');
+                assert.equal(body.summary.transport_error_kind, 'aborted');
+                assert.equal(body.summary.agent_diagnostics_checked, true);
+                assert.equal(body.summary.agent_diagnostics_found, true);
+                assert.equal(body.agent_failure_diagnostics.request_id, 'req_generate_diag');
+                assert.equal(body.agent_failure_diagnostics.status, 'failed');
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    [
+                        'GET /api/agent/capabilities',
+                        'POST /api/agent/images/generate',
+                        'GET /api/agent/diagnostics/requests?idempotency_key=diag-generate-key'
+                    ]
+                );
+            }
+        );
+    });
+
+    it('preserves path prefixes when fetching Agent state diagnostics', async () => {
+        const requests = [];
+        await withServer(
+            (request, response) => {
+                requests.push({ method: request.method, url: request.url });
+                if (request.url === '/playground/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (request.url === '/playground/api/agent/images/generate') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            error: { code: 'unexpected_error', message: 'fetch failed', retryable: false }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/playground/api/agent/diagnostics/requests?idempotency_key=path-diag-key') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            found: true,
+                            diagnostics: {
+                                request: {
+                                    request_id: 'req_path_diag',
+                                    idempotency_key: 'path-diag-key',
+                                    status: 'failed'
+                                }
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--allow-billable', '--idempotency-key', 'path-diag-key', '--size', '1024x1024', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: `${baseUrl}/playground` }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.summary.request_id, 'req_path_diag');
+                assert.equal(body.summary.agent_diagnostics_checked, true);
+                assert.equal(body.summary.agent_diagnostics_found, true);
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    [
+                        'GET /playground/api/agent/capabilities',
+                        'POST /playground/api/agent/images/generate',
+                        'GET /playground/api/agent/diagnostics/requests?idempotency_key=path-diag-key'
+                    ]
+                );
+            }
+        );
+    });
+
+    it('replaces stale retry guidance when Agent diagnostics report a terminal failure', async () => {
+        await withServer(
+            (request, response) => {
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(503, { 'content-type': 'application/json', 'retry-after': '1' });
+                    response.end(
+                        JSON.stringify({
+                            error: { code: 'network_error', message: 'temporary failure', retryable: true }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/diagnostics/requests?idempotency_key=terminal-diag-key') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            found: true,
+                            diagnostics: {
+                                request: {
+                                    request_id: 'req_terminal_diag',
+                                    idempotency_key: 'terminal-diag-key',
+                                    status: 'failed'
+                                },
+                                error: {
+                                    code: 'upstream_failed',
+                                    retryable: false
+                                }
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--allow-billable', '--idempotency-key', 'terminal-diag-key', '--size', '1024x1024', 'prompt'],
+                    {
+                        GPT_IMAGE_AGENT_MAX_ATTEMPTS: '1',
+                        GPT_IMAGE_PLAYGROUND_URL: baseUrl
+                    }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.summary.request_id, 'req_terminal_diag');
+                assert.equal(body.summary.retryable, false);
+                assert.equal(body.summary.next_action, 'diagnose_then_new_idempotency_key');
+                assert.equal(body.agent_failure_diagnostics.retryable, false);
+            }
+        );
+    });
+
+    it('does not report diagnostics lookup failures as upstream transport errors', async () => {
+        await withServer(
+            (request, response) => {
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: { code: 'unexpected_error', message: 'fetch failed', retryable: false } }));
+                    return;
+                }
+                if (request.url === '/api/agent/diagnostics/requests?idempotency_key=diag-unavailable-key') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'diagnostics unavailable' }));
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--allow-billable', '--idempotency-key', 'diag-unavailable-key', '--size', '1024x1024', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.summary.transport_error_kind, null);
+                assert.equal(body.summary.agent_diagnostics_checked, true);
+                assert.equal(body.summary.agent_diagnostics_found, false);
+                assert.equal(body.summary.agent_diagnostics_unavailable_reason, 'status_500');
+                assert.equal(body.agent_failure_diagnostics.unavailable_reason, 'status_500');
+            }
+        );
+    });
+
     it('uses page SSE client request id max length declared by capabilities', async () => {
         const requests = [];
         await withServer(
@@ -1615,7 +1936,9 @@ describe('Agent skill script argument validation', () => {
                                 {
                                     filename: 'agent-off.png',
                                     content_url: '/api/agent/artifacts/artifact-off/content',
-                                    metadata_url: '/api/agent/artifacts/artifact-off'
+                                    metadata_url: '/api/agent/artifacts/artifact-off',
+                                    width: 1254,
+                                    height: 1254
                                 }
                             ],
                             timing: { server_elapsed_ms: 4321 }
@@ -1660,6 +1983,8 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(body.summary.route_mode, 'agent');
                 assert.deepEqual(body.summary.content_urls, ['/api/agent/artifacts/artifact-off/content']);
                 assert.deepEqual(body.summary.absolute_content_urls, [`${baseUrl}/api/agent/artifacts/artifact-off/content`]);
+                assert.deepEqual(body.summary.actual_dimensions, { width: 1254, height: 1254 });
+                assert.deepEqual(body.summary.image_dimensions, [{ width: 1254, height: 1254 }]);
                 assert.equal(typeof body.summary.elapsed_ms, 'number');
                 assert.equal(body.summary.elapsed_source, 'client_script');
                 assert.equal(body.summary.server_elapsed_ms, 4321);
@@ -2352,6 +2677,102 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
+    it('enriches failed Agent edit summaries with Agent state diagnostics', async () => {
+        const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-edit-diagnostics-'));
+        try {
+            const imagePath = join(tempRoot, 'source.png');
+            writeFileSync(imagePath, fakePngBuffer(2, 1));
+            const requests = [];
+
+            await withServer(
+                async (request, response) => {
+                    requests.push({ method: request.method, url: request.url });
+                    if (request.url === '/api/agent/capabilities') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                agent_streaming: {
+                                    page_sse: { supported: true, endpoint: '/api/images' }
+                                }
+                            })
+                        );
+                        return;
+                    }
+                    if (request.url === '/api/agent/images/edit') {
+                        await readRequestText(request);
+                        response.writeHead(500, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ error: { code: 'unexpected_error', message: 'edit failed', retryable: false } }));
+                        return;
+                    }
+                    if (request.url === '/api/agent/diagnostics/requests?idempotency_key=diag-edit-key') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                found: true,
+                                diagnostics: {
+                                    request: {
+                                        request_id: 'req_edit_diag',
+                                        idempotency_key: 'diag-edit-key',
+                                        status: 'failed'
+                                    },
+                                    error: {
+                                        code: 'unexpected_error',
+                                        retryable: false,
+                                        diagnostics: {
+                                            selected_channel_id: 'channel-edit',
+                                            upstream_host: 'edit-upstream.example.test',
+                                            transport_error_kind: 'socket_closed'
+                                        }
+                                    }
+                                }
+                            })
+                        );
+                        return;
+                    }
+                    response.writeHead(404, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'missing' }));
+                },
+                async (baseUrl) => {
+                    const result = await runSkillScriptAsync(
+                        'edit-image.mjs',
+                        [
+                            '--allow-billable',
+                            '--agent',
+                            '--idempotency-key',
+                            'diag-edit-key',
+                            '--size',
+                            '3072x2048',
+                            imagePath,
+                            'prompt'
+                        ],
+                        { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                    );
+
+                    assert.equal(result.status, 1);
+                    assert.equal(result.stdout.trim(), '');
+                    const body = JSON.parse(result.stderr);
+                    assert.equal(body.summary.request_id, 'req_edit_diag');
+                    assert.equal(body.summary.selected_channel_id, 'channel-edit');
+                    assert.equal(body.summary.upstream_host, 'edit-upstream.example.test');
+                    assert.equal(body.summary.transport_error_kind, 'socket_closed');
+                    assert.equal(body.summary.agent_diagnostics_checked, true);
+                    assert.equal(body.summary.agent_diagnostics_found, true);
+                    assert.equal(body.agent_failure_diagnostics.request_id, 'req_edit_diag');
+                    assert.deepEqual(
+                        requests.map((item) => `${item.method} ${item.url}`),
+                        [
+                            'GET /api/agent/capabilities',
+                            'POST /api/agent/images/edit',
+                            'GET /api/agent/diagnostics/requests?idempotency_key=diag-edit-key'
+                        ]
+                    );
+                }
+            );
+        } finally {
+            rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+
     it('rejects default WebP edit dry-runs when streaming is explicitly disabled', () => {
         const result = runSkillScript('edit-image.mjs', [
             '--size',
@@ -2778,10 +3199,14 @@ describe('Agent skill script argument validation', () => {
         assert.match(skillText, /脚本参数仍写作 `--streaming-strategy responses-sse`/);
         assert.match(skillText, /batch JSONL 字段是 `streaming_strategy`/);
         assert.match(skillText, /`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段/);
+        assert.match(skillText, /`capabilities` 里声明的 `page_sse_supported=true`/);
+        assert.match(skillText, /`selected_channel_id`、`upstream_host` 为空/);
         assert.match(skillText, /支持位置参数 `<image-path> <prompt>`，也支持 `--image <path> <prompt>` 别名/);
         assert.match(skillText, /`--image-backend responses-image-generation` 只用于页面 SSE edit/);
         assert.match(skillText, /不要把 Matsca `limits\.partial_images=0\.\.4` 误套到 `responses-image-generation`/);
         assert.match(apiReference, /limits\.partial_images_by_backend\[image_backend\]/);
+        assert.match(apiReference, /只代表“声明支持”，不代表当前渠道每次实测都能成功/);
+        assert.match(apiReference, /如果 `selected_channel_id`、`upstream_host` 为空/);
         assert.match(apiReference, /Agent edit 不接收 `image_backend`、`output_format` 或 `output_compression`/);
         assert.match(apiReference, /强制 Agent edit 时输出格式固定为 PNG，`partial_images` 按默认 Images API\/profile 范围校验/);
         assert.match(apiReference, /图片路径可以用位置参数 `<image-path> <prompt>`，也可以用 `--image <path> <prompt>`/);
@@ -2819,6 +3244,7 @@ describe('Agent skill script argument validation', () => {
         assert.match(readmeText, /npm run env:summary/);
         assert.match(readmeText, /verification_scope\.mode=local_planning_only/);
         assert.match(readmeText, /Hugging Face Space Secrets 只能写入和列出名称/);
+        assert.match(readmeText, /`page_sse_supported=true` 只是声明支持，不代表实测一定成功/);
 
         assert.match(skillText, /不要手动并行启动多个单张脚本/);
         assert.match(skillText, /capacity_feedback/);
@@ -2840,6 +3266,8 @@ describe('Agent skill script argument validation', () => {
         assert.match(apiReference, /verification_scope\.mode=local_planning_only/);
         assert.match(apiReference, /manifest_written=false/);
         assert.match(apiReference, /Hugging Face Space Secrets 只能写入和列出名称/);
+        assert.match(apiReference, /这个失败表示上游已生成但本地验收未通过/);
+        assert.match(apiReference, /`validation_failure_count>0` 而 `request_failure_count=0`/);
     });
 
     it('keeps WebUI page APIs out of the Agent OpenAPI contract', () => {
@@ -2894,6 +3322,24 @@ describe('Agent skill script argument validation', () => {
         assert.match(openApiSource, /高分辨率 edit 默认优先使用页面端 \/api\/images form-data SSE/);
     });
 
+    it('requires new probe and diagnostics work to keep API contracts ahead of Skill wrappers', () => {
+        const readmeText = readFileSync(join(repoRoot, 'README.md'), 'utf8');
+        const skillText = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8');
+        const apiReference = readFileSync(join(skillRoot, 'references/api.md'), 'utf8');
+
+        assert.match(readmeText, /新增 probe、diagnostics 或路由可观测能力时，先落 API \/ capabilities \/ OpenAPI 契约/);
+        assert.match(readmeText, /Skill 脚本做薄封装/);
+        assert.match(skillText, /新增 probe、diagnostics、路由健康或请求旅程能力时/);
+        assert.match(skillText, /GET \/api\/agent\/capabilities/);
+        assert.match(skillText, /GET \/api\/agent\/openapi\.json/);
+        assert.match(skillText, /\/api\/agent\/diagnostics\/\*/);
+        assert.match(skillText, /Skill 脚本只做薄封装/);
+        assert.match(skillText, /不能复制页面 API、运行态 API 和 Agent API 的边界判断/);
+        assert.match(apiReference, /新增 probe、diagnostics 或健康摘要时/);
+        assert.match(apiReference, /capabilities、OpenAPI 或明确的 Agent 只读端点/);
+        assert.match(apiReference, /不要让脚本自己拼 page API、runtime API 和 Agent API 的边界逻辑/);
+    });
+
     it('runs from a copied standalone skill directory outside the repository', () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-playground-agent-'));
         const copiedSkillRoot = join(tempRoot, 'gpt-image-playground-agent');
@@ -2997,6 +3443,10 @@ describe('Agent skill script argument validation', () => {
             assert.equal(body.manifest_write_reason, 'dry_run');
             assert.equal(body.total, 2);
             assert.equal(body.concurrency, 1);
+            assert.equal(body.guardrails.ordered_prefix, 'demo');
+            assert.equal(body.guardrails.repeat_ordered_prefix_on_real_run, true);
+            assert.equal(body.guardrails.dimension_check_recommended, true);
+            assert.match(body.guardrails.dimension_check_reason, /--dimension-check/);
             assert.equal(body.tasks[0].endpoint, '/api/agent/images/generate');
             assert.equal(body.tasks[0].idempotency_key, 'demo-0001-first-item');
             assert.equal(body.tasks[0].request.model, 'gpt-image-2');
@@ -3017,6 +3467,77 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
+    it('records enriched Agent diagnostics for failed batch tasks and manifests', async () => {
+        const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-diagnostics-'));
+        try {
+            const inputPath = join(tempRoot, 'tasks.jsonl');
+            const manifestPath = join(tempRoot, 'manifest.jsonl');
+            writeFileSync(inputPath, JSON.stringify({ id: 'diag-task', prompt: 'prompt', idempotency_key: 'batch-diag-key' }));
+
+            await withServer(
+                (request, response) => {
+                    if (request.url === '/api/agent/capabilities') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ ok: true }));
+                        return;
+                    }
+                    if (request.url === '/api/agent/images/generate') {
+                        response.writeHead(500, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ error: { code: 'unexpected_error', message: 'fetch failed', retryable: false } }));
+                        return;
+                    }
+                    if (request.url === '/api/agent/diagnostics/requests?idempotency_key=batch-diag-key') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                found: true,
+                                diagnostics: {
+                                    request: {
+                                        request_id: 'req_batch_diag',
+                                        idempotency_key: 'batch-diag-key',
+                                        status: 'failed'
+                                    },
+                                    error: {
+                                        code: 'unexpected_error',
+                                        retryable: false,
+                                        diagnostics: {
+                                            selected_channel_id: 'channel-b',
+                                            upstream_host: 'batch-upstream.example.test'
+                                        }
+                                    }
+                                }
+                            })
+                        );
+                        return;
+                    }
+                    response.writeHead(404, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'missing' }));
+                },
+                async (baseUrl) => {
+                    const result = await runSkillScriptAsync(
+                        'batch-images.mjs',
+                        ['--allow-billable', '--input', inputPath, '--manifest', manifestPath, '--max-attempts', '1'],
+                        { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                    );
+
+                    assert.equal(result.status, 1);
+                    assert.equal(result.stderr.trim(), '');
+                    const body = JSON.parse(result.stdout);
+                    assert.equal(body.results[0].summary.request_id, 'req_batch_diag');
+                    assert.equal(body.results[0].summary.selected_channel_id, 'channel-b');
+                    assert.equal(body.results[0].summary.upstream_host, 'batch-upstream.example.test');
+                    assert.equal(body.results[0].summary.agent_diagnostics_checked, true);
+                    assert.equal(body.results[0].agent_failure_diagnostics.request_id, 'req_batch_diag');
+                    const manifestLines = readFileSync(manifestPath, 'utf8').trim().split(/\r?\n/).map(JSON.parse);
+                    assert.equal(manifestLines[0].summary.request_id, 'req_batch_diag');
+                    assert.equal(manifestLines[0].agent_failure_diagnostics.request_id, 'req_batch_diag');
+                }
+            );
+        } finally {
+            rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+
     it('rejects invalid batch concurrency before dry-run output', () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-concurrency-'));
         try {
@@ -4473,6 +4994,8 @@ describe('Agent skill script argument validation', () => {
                     assert.equal(result.stderr.trim(), '');
                     const body = JSON.parse(result.stdout);
                     assert.equal(body.results[0].status, 'succeeded');
+                    assert.deepEqual(body.results[0].summary.actual_dimensions, { width: 1024, height: 1024 });
+                    assert.deepEqual(body.results[0].summary.image_dimensions, [{ width: 1024, height: 1024 }]);
                 }
             );
         } finally {
@@ -4912,7 +5435,14 @@ describe('Agent skill script argument validation', () => {
                     }
                     if (request.url === '/api/agent/images/generate') {
                         response.writeHead(200, { 'content-type': 'application/json' });
-                        response.end(JSON.stringify({ images: [{ id: 'dim-image', filename: 'dim.png', b64_json: fakePngBase64(512, 512) }] }));
+                        response.end(
+                            JSON.stringify({
+                                images: [
+                                    { id: 'dim-image-bad', filename: 'dim-bad.png', b64_json: fakePngBase64(512, 512) },
+                                    { id: 'dim-image-ok', filename: 'dim-ok.png', b64_json: fakePngBase64(1024, 1024) }
+                                ]
+                            })
+                        );
                         return;
                     }
                     response.writeHead(404, { 'content-type': 'application/json' });
@@ -4929,7 +5459,29 @@ describe('Agent skill script argument validation', () => {
                     assert.equal(result.stderr.trim(), '');
                     const body = JSON.parse(result.stdout);
                     assert.equal(body.ok, false);
-                    assert.match(body.results[0].error, /尺寸校验失败/);
+                    assert.equal(body.results[0].error.code, 'dimension_check_failed');
+                    assert.match(body.results[0].error.message, /尺寸校验失败/);
+                    assert.deepEqual(body.results[0].error.expected_dimensions, { width: 1024, height: 1024 });
+                    assert.deepEqual(body.results[0].error.actual_dimensions, { width: 512, height: 512 });
+                    assert.equal(body.results[0].validation_failure_kind, 'generated_artifact_failed_dimension_check');
+                    assert.equal(body.results[0].response.images[0].b64_json, undefined);
+                    assert.equal(body.results[0].response.images[0].b64_json_length, fakePngBase64(512, 512).length);
+                    assert.deepEqual(body.results[0].response.images[0].dimensions, { width: 512, height: 512 });
+                    assert.equal(body.results[0].response.images[1].b64_json, undefined);
+                    assert.equal(body.results[0].response.images[1].b64_json_length, fakePngBase64(1024, 1024).length);
+                    assert.deepEqual(body.results[0].response.images[1].dimensions, { width: 1024, height: 1024 });
+                    assert.deepEqual(body.results[0].summary.artifact_ids, ['dim-image-bad', 'dim-image-ok']);
+                    assert.deepEqual(body.results[0].summary.image_dimensions, [
+                        { width: 512, height: 512 },
+                        { width: 1024, height: 1024 }
+                    ]);
+                    assert.deepEqual(body.results[0].summary.expected_dimensions, { width: 1024, height: 1024 });
+                    assert.deepEqual(body.results[0].summary.actual_dimensions, { width: 512, height: 512 });
+                    assert.equal(body.results[0].summary.dimension_check_failed, true);
+                    assert.equal(body.failure_summary.validation_failure_count, 1);
+                    assert.equal(body.failure_summary.request_failure_count, 0);
+                    assert.equal(body.failure_summary.tasks[0].failure_kind, 'generated_artifact_failed_dimension_check');
+                    assert.deepEqual(body.failure_summary.tasks[0].artifact_ids, ['dim-image-bad', 'dim-image-ok']);
                 }
             );
         } finally {
@@ -5685,9 +6237,10 @@ function listTextFiles(root) {
 
 function runSkillScriptAsync(filename, args, env = {}, options = {}) {
     return new Promise((resolve) => {
+        const baseEnv = buildIsolatedSkillScriptEnv({ loadPrivateAgentEnv: options.loadPrivateAgentEnv });
         const child = spawn(process.execPath, [join(skillScriptsRoot, filename), ...args], {
             cwd: repoRoot,
-            env: { ...process.env, ...env },
+            env: { ...baseEnv, ...env },
             stdio: ['ignore', 'pipe', 'pipe']
         });
         let stdout = '';

scripts/command-center.test.mjs

@@ -507,6 +507,11 @@ describe('Command center scripts', () => {
                     );
                     assert.equal(report.service.capabilities.page_sse_auth_required, true);
                     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.match(formatFirstRunText(report), /页面 SSE：声明支持，实测=未执行真实 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,
@@ -535,6 +540,7 @@ describe('Command center scripts', () => {
         assert.match(text, /当前进程鉴权：未加载/);
         assert.match(text, /私有 Agent env：不存在/);
         assert.match(text, /下一步：/);
+        assert.doesNotMatch(text, /实测=passed/);
         assert.doesNotMatch(text, /^\{/);
     });
 
@@ -718,12 +724,22 @@ describe('Command center scripts', () => {
                 assert.equal(body.summary.runtime, 'ok');
                 assert.equal(body.summary.state_backend, 'memory');
                 assert.equal(body.summary.page_sse_auth_ready, false);
+                assert.equal(body.summary.page_sse_declared_supported, true);
+                assert.equal(body.summary.page_sse_real_smoke, 'skipped');
                 assert.equal(body.summary.responses_gpt2image_ready, true);
+                assert.equal(body.summary.responses_image_backend_declared_supported, true);
                 assert.equal(body.summary.billable_smoke, 'skipped');
                 assert.equal(body.layers.find((layer) => layer.name === 'billable_smoke').skipped, true);
+                assert.ok(
+                    body.layers
+                        .find((layer) => layer.name === 'billable_smoke')
+                        .checks.some((check) => check.name === 'responses_page_sse_generate_1k' && check.skipped === true)
+                );
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').executable_routing_rules, true);
+                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.match(
                     body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_next_action,
                     /GPT_IMAGE_APP_PASSWORD_HASH/
@@ -798,6 +814,19 @@ describe('Command center scripts', () => {
                     }
                     return;
                 }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"doctor-page-sse.png","path":"/api/image/doctor-page-sse.png","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"doctor-page-sse-request","images":[{"filename":"doctor-page-sse.png"}]}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    return;
+                }
                 if (request.url === '/api/agent/jobs/images/generate') {
                     response.writeHead(400, { 'content-type': 'application/json' });
                     response.end(
@@ -824,7 +853,9 @@ describe('Command center scripts', () => {
                 const body = parseJsonPayload(result.stdout, 'agent doctor');
                 assert.equal(body.service_base_url_source, 'user_provided');
                 assert.equal(body.interactive_confirmation_required, false);
+                assert.equal(body.summary.page_sse_real_smoke, 'passed');
                 assert.ok(hits.includes('/api/agent/images/generate'));
+                assert.ok(hits.includes('/api/images'));
             }
         );
     });

scripts/first-run.mjs

@@ -317,6 +317,7 @@ function summarizeService(service) {
 }
 
 function summarizeCapabilitiesBody(body) {
+    const responsesRequirement = body?.supported?.image_backend_requirements?.['responses-image-generation'];
     return {
         auth_required: body?.auth?.required === true,
         auth_schemes: Array.isArray(body?.auth?.schemes) ? body.auth.schemes : [],
@@ -326,8 +327,12 @@ function summarizeCapabilitiesBody(body) {
         image_storage_mode: body?.storage?.image_storage_mode,
         agent_jobs_supported: body?.agent_jobs?.supported === true,
         page_sse_supported: body?.agent_streaming?.page_sse?.supported === true,
-        responses_image_backend_enabled:
-            body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true
+        page_sse_declared_supported: body?.agent_streaming?.page_sse?.supported === true,
+        page_sse_real_smoke: 'not_run_by_first_run',
+        upstream_sse_declared_supported: body?.agent_streaming?.upstream_sse?.supported === true,
+        responses_image_backend_declared_supported: responsesRequirement?.supported === true,
+        responses_image_backend_enabled: responsesRequirement?.enabled === true,
+        responses_image_backend_real_smoke: 'not_run_by_first_run'
     };
 }
 
@@ -412,6 +417,12 @@ export function formatFirstRunText(report) {
         lines.push(
             `- 页面 SSE 鉴权：${capability.page_sse_auth_required ? `需要 ${capability.page_sse_auth_form_field || 'passwordHash'}` : '不需要'}`
         );
+        lines.push(
+            `- 页面 SSE：声明${capability.page_sse_declared_supported ? '支持' : '未支持'}，实测=${formatSmokeState(capability.page_sse_real_smoke)}`
+        );
+        lines.push(
+            `- Responses 后端：声明${capability.responses_image_backend_declared_supported ? '支持' : '未支持'}，启用=${capability.responses_image_backend_enabled ? '是' : '否'}，实测=${formatSmokeState(capability.responses_image_backend_real_smoke)}`
+        );
         lines.push(`- 状态后端：${capability.state_backend || '未知'}，图片存储：${capability.image_storage_mode || '未知'}`);
     }
     const runtime = report.service?.runtime || {};
@@ -444,6 +455,16 @@ function formatEndpoint(endpoint) {
     return `失败${endpoint.status ? ` ${endpoint.status}` : ''}${endpoint.error ? ` ${endpoint.error}` : ''}`;
 }
 
+function formatSmokeState(value) {
+    const states = {
+        not_run_by_first_run: '未执行真实 smoke',
+        skipped: '已跳过',
+        passed: '通过',
+        failed: '失败'
+    };
+    return states[value] || value || '未知';
+}
+
 function formatAuthState(auth) {
     if (!auth) return '未知';
     if (auth.has_token) return '已加载 token';

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

@@ -20,7 +20,8 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
 - 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 `scripts/` 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
 - 先用 dry-run 或 `--contract-check` 检查请求、路由和鉴权；只有用户明确允许真实计费时才加 `--allow-billable`。
-- 真实调用成功或失败后，优先读取脚本输出的 `summary`。它是面向 Agent 的机器摘要，包含 `billable`、请求 ID、幂等键、产物 URL、耗时、耗时拆分、路由、渠道、上游 host、脱敏请求头、重试和下一步动作；不要再先手查 SQLite、Docker logs 或上游后台。
+- 真实调用成功或失败后，优先读取脚本输出的 `summary`。它是面向 Agent 的机器摘要，包含 `billable`、请求 ID、幂等键、产物 URL、耗时、耗时拆分、路由、渠道、上游 host、脱敏请求头、重试和下一步动作；Agent JSON 失败时脚本会按幂等键做一次只读 Agent state 诊断补采样，补充 `agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status`、`request_id`、渠道和上游 host。不要再先手查 SQLite、Docker logs 或上游后台。
+- 新增 probe、diagnostics、路由健康或请求旅程能力时，先在服务端定义机器 API 契约，并通过 `GET /api/agent/capabilities`、`GET /api/agent/openapi.json` 或明确的 `/api/agent/diagnostics/*` 端点声明；Skill 脚本只做薄封装，不能复制页面 API、运行态 API 和 Agent API 的边界判断。
 
 ## 产品边界
 
@@ -32,12 +33,13 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 
 - 先读取 `GET /api/agent/capabilities` 的 `routing_rules`，按机器可读规则选择端点。
 - 默认 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` 显式切换到 Agent JSON 或 job，不自动回退。
 - 复杂 UI 批量出图优先使用页面端 `POST /api/images` SSE 和 `scripts/batch-images.mjs`；不要手动并行启动多个单张脚本，因为这会绕过 manifest、`--resume`、`capacity_feedback` 和尺寸门禁。需要并发时显式设置 `--concurrency N` 或页面“并发批量”开关，并记录切换原因、失败清单和续跑锚点。
 - 真实批量并发前先看 `GET /api/runtime-capabilities` 的 `channelQueue.capacityPerCredential` 和 `streamingBatch.recommendedConcurrency`。如果服务端建议并发为 `1`，或返回 `channel_capacity_queue_aborted` / `retry_after_seconds`，同一渠道任务保持 `--concurrency 1`，不要用多个 shell 进程绕过限流。
 - 复杂 UI、长 prompt、高质量图生图遇到 5 分钟级超时、连接中断或上游 503 时，不要把失败归因到提示词质量；先读 `summary` 和诊断，再用新 key 显式尝试压缩 prompt 或改为 `quality=medium` 的对照请求，并记录这是稳定性取舍。
 - 长图恢复或需要续跑锚点的生产请求优先使用页面端 `POST /api/images` SSE，保留局部进度和缺最终图诊断。
 - 普通小图单次文生图使用 `/api/agent/images/generate`；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE，流式失败后先诊断，再显式选择 Agent JSON 或 job 路径，不自动回退。
-- 单张文生图使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时走页面端 `/api/images` SSE，因为这些是页面高级字段，不属于 Agent JSON schema。`--responses-model` 必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`；显式 `--agent`、`--job`、`stream_mode=non_stream` 或 `streaming_strategy=off` 会被脚本前置拒绝。
+- 单张文生图使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时走页面端 `/api/images` SSE，因为这些是页面高级字段，不属于 Agent JSON schema。`--responses-model` 覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。该字段只影响本项目 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。`--responses-model` 必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`；显式 `--agent`、`--job`、`stream_mode=non_stream` 或 `streaming_strategy=off` 会被脚本前置拒绝。
 - 同一个已进入终态 `failed` 的 `Idempotency-Key` 只会回放失败；重新尝试必须先诊断原因，再创建新的业务操作和新的 key。
 
 ## 执行流程
@@ -55,7 +57,7 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 11. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
 12. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复、显式页面参数或明确诊断后切换。
 13. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
-14. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
+14. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。页面 SSE 返回 `503`、断流，或 `summary` 里的 `selected_channel_id`、`upstream_host` 为空时，先按结构化失败诊断，再用新 key 显式换路径，不要把它当成已自动回退成功。
 15. 返回结果时优先给出 `summary`、`content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。回答“4K 非流式花了多久”时优先读 `summary.elapsed_ms`，服务端返回 timing 时也读 `summary.server_elapsed_ms`。
 16. 需要查询页面请求后的人工反馈或日志摘要时，使用页面 SSE 的 `clientRequestId` 或脚本复用的 `Idempotency-Key` 调用 `scripts/diagnose-request.mjs --client-request-id ...`；不要直接调用 `/api/logs`。需要查询 Agent state 请求状态时，使用 `scripts/diagnose-request.mjs --agent-request-id ...` 或 `--idempotency-key ...`。
 
@@ -112,7 +114,7 @@ Authorization: Bearer <token>
 - `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 还会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。
+生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成和编辑 dry-run 还会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_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`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `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 或真实请求前都会校验尺寸参数。`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 契约。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
@@ -197,7 +199,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`；`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。dry-run 不写 manifest，输出会声明 `manifest_written=false` 和 `manifest_write_reason=dry_run`。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`--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 `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`，便于区分上游未给终图和解析/断流问题。
 
 批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。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

@@ -47,7 +47,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 同一个 `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`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。失败摘要也稳定包含空数组或 `null` 形式的产物、路由和渠道字段，便于 subagent 按同一模板汇报。失败摘要还包含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
+真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_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`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。失败摘要也稳定包含空数组或 `null` 形式的产物、路由、渠道和尺寸字段，便于 subagent 按同一模板汇报；尺寸门禁失败属于“上游已生成但本地验收失败”，失败摘要会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`。失败摘要还包含 `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`、`selected_channel_id`、`upstream_host`、`transport_error_kind` 合并进首次失败摘要，并输出 `agent_failure_diagnostics`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
 
 生成脚本参数：
 
@@ -59,7 +59,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--output-compression`：默认 `100`，仅适用于 `jpeg` 或 `webp`。
 - `--response-mode`：默认 `path`。
 - `--image-backend`：可选，显式选择 `images-api`、`images`、`responses` 或 `responses-image-generation`。
-- `--responses-model` / `--gpt-model`：页面 SSE 专属字段，设置 Responses 顶层模型；必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`。
+- `--responses-model` / `--gpt-model`：页面 SSE 专属字段，覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`。该字段只影响本项目的 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。
 - `--thinking`：页面 SSE 专属字段，可选值为 `minimal`、`none`、`low`、`medium`、`high` 或 `xhigh`。
 - `--prompt-optimization`：页面 SSE 专属字段，必须是 `true` 或 `false`。
 - `--force-web`：页面 SSE 专属字段，会发送为 form-data `force_web=true`。
@@ -115,7 +115,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`。
+- `--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`。这个失败表示上游已生成但本地验收未通过，不等于上游请求失败。
 - `--max-attempts`：失败任务最大尝试次数。第二次及后续尝试会追加新的 attempt 级 `Idempotency-Key`，避免复用终态失败 key。
 - `--concurrency`：并发执行窗口，默认 `1`。大于 `1` 时会先读取 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 和 `channelQueue.capacityPerCredential`，把有效并发限制到服务端建议值后按输入顺序输出结果；适合已确认渠道容量的批量生产。
 - `--max-consecutive-failures`：顺序执行下的连续失败熔断阈值，默认 `0` 表示不熔断。只能与 `--concurrency 1` 同用。
@@ -123,7 +123,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--dry-run`
 - `--allow-billable`
 
-批量 dry-run 不写 manifest，输出会声明 `manifest_written=false` 和 `manifest_write_reason=dry_run`。只有真实执行时 manifest 才作为 append-only 续跑记录写入。
+批量 dry-run 不写 manifest，输出会声明 `manifest_written=false`、`manifest_write_reason=dry_run` 和 `guardrails`。`guardrails.ordered_prefix` 是本次 dry-run 用于自动生成幂等键的前缀，真实执行应复用同一个 `--ordered-prefix`；`guardrails.dimension_check_recommended=true` 表示输入包含固定尺寸但未启用 `--dimension-check`。只有真实执行时 manifest 才作为 append-only 续跑记录写入；Agent JSON 失败时 manifest 会同时保存增强后的 `summary` 和 `agent_failure_diagnostics`。尺寸门禁失败同样写入结构化 summary 和可审查产物 URL，避免只能从中文错误文本解析期望和实际尺寸。批量总摘要会输出 `failure_summary.validation_failure_count` 和 `failure_summary.request_failure_count`，用于区分“上游已生成但本地验收失败”和“请求未成功完成”。当 `validation_failure_count>0` 而 `request_failure_count=0` 时，要按验收失败处理，不能当成上游不可用。
 
 批量 JSONL 每行字段按 `mode` 区分。`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 会选择页面 SSE 路径，且必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`，因为 Agent JSON 不接收请求级 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 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
 
@@ -191,7 +191,7 @@ GET /api/agent/capabilities
 - `agent_streaming.generate.mode`：当前为 `non_streaming_only`。
 - `agent_streaming.edit.mode`：当前为 `non_streaming_only`。
 - `agent_streaming.upstream_sse`：Agent generate/edit 内部消费上游 SSE 的能力，客户端响应仍是最终 `AgentImageResponse` JSON。
-- `agent_streaming.upstream_sse.supported`：布尔值；当服务端支持 Agent 内部上游 SSE 消费时为 `true`，否则为 `false`。客户端只在为 `true` 时发送上游流式控制字段。
+- `agent_streaming.upstream_sse.supported`：布尔值；当服务端支持 Agent 内部上游 SSE 消费时为 `true`，否则为 `false`。客户端只在为 `true` 时发送上游流式控制字段。这个字段只代表“声明支持”，不代表当前渠道每次实测都能成功。
 - `agent_streaming.upstream_sse.request_fields`：兼容旧客户端的字段合集，当前为 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images`。
 - `agent_streaming.upstream_sse.request_fields_by_mode.generate`：generate 可发送的上游 SSE 控制字段，当前为 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images`。
 - `agent_streaming.upstream_sse.request_fields_by_mode.edit`：edit 可发送的上游 SSE 控制字段，当前为 `stream_mode`、`streaming_strategy`、`partial_images`。
@@ -200,19 +200,22 @@ GET /api/agent/capabilities
 - `agent_streaming.upstream_sse.streaming_strategies`：支持 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
 - `agent_streaming.upstream_sse.stream_modes`：支持 `auto`、`stream`、`non_stream`。
 - `agent_streaming.upstream_sse.activation_strategies`：会真正向上游发送 `stream=true` 的策略，当前包含 `auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
-- `agent_streaming.page_sse`：页面端 `/api/images` 的 form-data SSE 能力，不代表 Agent generate/edit 支持流式。
+- `agent_streaming.page_sse`：页面端 `/api/images` 的 form-data SSE 能力，不代表 Agent generate/edit 支持流式。即使该字段为 `supported=true`，页面 SSE 仍可能在当前渠道返回 `503`、断流或没有选中渠道；这时应先诊断，再显式切换到 Agent JSON 或 job，不自动回退。
 - `agent_streaming.page_sse.auth`：页面 SSE 的独立表单鉴权。`APP_PASSWORD` 已配置时为 `required=true`、`schemes=["form-password-hash"]`、`form_field="passwordHash"`。
 - `agent_streaming.page_sse.client_request_id`：页面 SSE 的请求 ID 契约。脚本会把 `Idempotency-Key` 写入 form-data `clientRequestId`，最大长度以 `max_length` 为准，当前为 `128`。
+- 页面 SSE 或 Responses 路径失败时，如果 `selected_channel_id`、`upstream_host` 为空，通常表示请求没有真正落到可执行渠道；先诊断结构化错误，再用新的 `Idempotency-Key` 显式改路由。
 - `upstream_request_headers.default`：默认上游请求头摘要，包含 `user_agent_effective`、`has_extra_headers`、`allowed_header_names` 和 `configured_header_names`。
 - `upstream_request_headers.channels`：每个服务端渠道的脱敏请求头摘要。该字段不包含 API key、Authorization 值、Matsca app secret 值或任意 header value。
 - `routing_rules.high_resolution_edit`：`edit` 且最大边大于 `2048` 时默认优先使用页面端 `/api/images` SSE，页面流式有问题时显式回退。
 - `routing_rules.complex_ui_batch`：复杂 UI 批量出图推荐使用页面端 `/api/images` SSE。
 - `routing_rules.long_image_recovery`：长图恢复或续跑锚点场景推荐使用页面端 `/api/images` SSE。
 - `routing_rules.agent_generate_small_smoke`：普通小图单次文生图默认使用 `/api/agent/images/generate`。
-- `routing_rules.page_sse_large_generate`：`max_edge>2048` 的单次文生图推荐优先使用 `/api/images` SSE，失败后先诊断，再显式选择 `/api/agent/images/generate` 或 job 路径。
+- `routing_rules.page_sse_large_generate`：`max_edge>2048` 的单次文生图推荐优先使用 `/api/images` SSE，失败后先诊断，再显式选择 `/api/agent/images/generate` 或 job 路径；不要把页面 SSE 的失败解释成自动回退到 Agent JSON 成功。
 - `routing_rules.retry_recovery`：终态失败不会用同一 `Idempotency-Key` 重新执行，必须诊断后创建新的业务操作和新的 key。
 - 批量 JSONL 路由控制字段：`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`；脚本会在 dry-run 阶段拒绝字符串布尔值和未知 transport。
 - `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`。
@@ -673,7 +676,7 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 }
 ```
 
-`diagnostics` 只包含脱敏诊断字段和白名单响应头，不包含 API key、token、完整上游响应体或图片 base64。SDK/网络层只有 `Connection error.` 时，`transport_error` 会是 `true`，但不会伪造 `upstream_status`。
+`diagnostics` 只包含脱敏诊断字段和白名单响应头，不包含 API key、token、完整上游响应体或图片 base64。SDK/网络层只有 `Connection error.` 时，`transport_error` 会是 `true`，但不会伪造 `upstream_status`。如果页面 SSE 请求返回 `page_sse_failed`、`503`、断流，且 `summary.selected_channel_id` 与 `summary.upstream_host` 为空，按页面流式路径未跑通处理；先用 `diagnose-request.mjs` 读取结构化摘要，再用新的 `Idempotency-Key` 显式选择 Agent JSON 或 job，不自动回退。
 
 常见错误码：
 

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
+import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
 import {
   errorMessage,
   assertValidImageSizeForModel,
@@ -25,6 +26,7 @@ import {
   postPageSse
 } from './lib/page-sse-client.mjs';
 import {
+  attachSummary,
   buildFailureSummary as buildScriptFailureSummary,
   buildSuccessSummary,
   completeScriptTiming,
@@ -57,6 +59,7 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
 const DEFAULT_BATCH_MAX_ATTEMPTS = 1;
 const DEFAULT_MAX_CONSECUTIVE_FAILURES = 0;
 const DEFAULT_BATCH_CONCURRENCY = 1;
+const FAILURE_KIND_DIMENSION_CHECK = 'generated_artifact_failed_dimension_check';
 const GENERATE_ONLY_FIELDS = [
   'background'
 ];
@@ -79,6 +82,21 @@ const PAGE_ADVANCED_FIELDS = [
 const EDIT_ONLY_FIELDS = ['image_path', 'image_paths', 'mask_path'];
 const BOOLEAN_ROUTING_FIELDS = ['page_sse', 'complex_ui', 'long_image', 'resume_or_recover'];
 const THINKING_VALUES = new Set(['minimal', 'none', 'low', 'medium', 'high', 'xhigh']);
+
+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 = '确认当前渠道是否支持请求尺寸，或调整任务接受实际返回尺寸；重新执行必须使用新的 Idempotency-Key。';
+    this.expectedDimensions = details.expected;
+    this.actualDimensions = details.actual;
+    this.response = sanitizeResponse(details.response);
+  }
+}
+
 const TASK_FIELDS = new Set([
   'id',
   'mode',
@@ -180,6 +198,7 @@ if (!options.allowBillable || options.dryRun) {
         max_attempts: options.maxAttempts,
         max_consecutive_failures: options.maxConsecutiveFailures,
         concurrency: options.concurrency,
+        guardrails: buildDryRunGuardrails(planned, options),
         tasks: planned.map((task) => {
           const routing = buildTaskRouting(task);
           return {
@@ -672,13 +691,13 @@ async function runTask(task) {
   const routing = buildTaskRouting(task);
   const taskTiming = startScriptTiming();
   try {
-    const response =
+    let response =
       routing.transport === 'page_sse'
         ? await postPageSseTask(task, routing)
         : task.mode === 'edit'
           ? await postEditTask(task)
           : await postGenerateTask(task);
-    if (options.dimensionCheck) await assertDimensions(task, response);
+    if (options.dimensionCheck) response = await assertDimensions(task, response);
     const summary = buildSuccessSummary({
       result: response,
       routing,
@@ -698,8 +717,27 @@ async function runTask(task) {
       billable: failure.billable !== false,
       nextAction: failure.next_step
     });
-    const output = { ok: false, status: 'failed', id: task.id, idempotency_key: task.idempotencyKey, ...failure, summary };
-    appendManifest(manifestPath, { ...baseManifestEntry(task), status: 'failed', ...failure, summary });
+    const failureOutput = { ok: false, status: 'failed', id: task.id, idempotency_key: task.idempotencyKey, ...failure, summary };
+    const enriched = shouldEnrichAgentFailure(failure)
+      ? await enrichFailureWithAgentDiagnostics({
+          baseUrl,
+          authHeaders,
+          idempotencyKey: task.idempotencyKey,
+          failureOutput,
+          summary,
+          timeoutMs
+        })
+      : { failureOutput, summary };
+    const output = attachSummary(enriched.failureOutput, enriched.summary);
+    appendManifest(manifestPath, {
+      ...baseManifestEntry(task),
+      status: 'failed',
+      ...failure,
+      ...(enriched.failureOutput.agent_failure_diagnostics
+        ? { agent_failure_diagnostics: enriched.failureOutput.agent_failure_diagnostics }
+        : {}),
+      summary: enriched.summary
+    });
     return output;
   }
 }
@@ -816,6 +854,22 @@ function buildTaskFailureOutput(error, routing) {
       next_step: error.pageSseFailure.next_step
     };
   }
+  if (error?.code === 'dimension_check_failed') {
+    return {
+      billable: error.billable !== false,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        expected_dimensions: error.expectedDimensions,
+        actual_dimensions: error.actualDimensions
+      },
+      validation_failure_kind: FAILURE_KIND_DIMENSION_CHECK,
+      response: error.response,
+      routing,
+      ...(typeof error?.nextStep === 'string' ? { next_step: error.nextStep } : {})
+    };
+  }
   return {
     ...(error?.billable === false ? { billable: false } : {}),
     error: errorMessage(error),
@@ -824,6 +878,10 @@ function buildTaskFailureOutput(error, routing) {
   };
 }
 
+function shouldEnrichAgentFailure(failure) {
+  return failure.billable !== false && failure.routing?.transport === 'agent_json';
+}
+
 function buildCircuitBreakerSkippedTask(task, consecutiveFailures) {
   return {
     status: 'skipped',
@@ -834,6 +892,22 @@ function buildCircuitBreakerSkippedTask(task, consecutiveFailures) {
   };
 }
 
+function buildDryRunGuardrails(plannedTasks, parsedOptions) {
+  const hasExplicitFixedSize = plannedTasks.some((task) => {
+    const size = task.raw?.size;
+    return typeof size === 'string' && size !== 'auto';
+  });
+  return {
+    ordered_prefix: parsedOptions.orderedPrefix,
+    repeat_ordered_prefix_on_real_run: true,
+    dimension_check_recommended: hasExplicitFixedSize && !parsedOptions.dimensionCheck,
+    dimension_check_reason:
+      hasExplicitFixedSize && !parsedOptions.dimensionCheck
+        ? '输入包含固定尺寸；真实上游可能返回非请求尺寸，尺寸敏感任务应添加 --dimension-check。'
+        : null
+  };
+}
+
 function buildFailedTaskSummary(result, task) {
   const error = normalizeFailureError(result.error);
   return {
@@ -844,12 +918,21 @@ function buildFailedTaskSummary(result, task) {
     route: result.routing?.transport,
     endpoint: result.routing?.endpoint,
     billable: result.billable !== false,
+    failure_kind: readFailureKind(result),
     code: error.code,
     message: error.message,
+    artifact_ids: Array.isArray(result.summary?.artifact_ids) ? result.summary.artifact_ids : [],
+    content_urls: Array.isArray(result.summary?.content_urls) ? result.summary.content_urls : [],
+    absolute_content_urls: Array.isArray(result.summary?.absolute_content_urls) ? result.summary.absolute_content_urls : [],
     next_step: result.next_step || buildFailureNextStep(error)
   };
 }
 
+function readFailureKind(result) {
+  if (typeof result?.validation_failure_kind === 'string') return result.validation_failure_kind;
+  return 'request_failed';
+}
+
 function normalizeFailureError(error) {
   if (error && typeof error === 'object') {
     return {
@@ -871,6 +954,8 @@ function buildFailureSummary(failedTasks) {
     count: failedTasks.length,
     billable_count: failedTasks.filter((task) => task.billable).length,
     non_billable_count: failedTasks.filter((task) => !task.billable).length,
+    validation_failure_count: failedTasks.filter((task) => task.failure_kind === FAILURE_KIND_DIMENSION_CHECK).length,
+    request_failure_count: failedTasks.filter((task) => task.failure_kind !== FAILURE_KIND_DIMENSION_CHECK).length,
     tasks: failedTasks
   };
 }
@@ -1293,15 +1378,25 @@ function enrichImageUrls(result) {
 
 async function assertDimensions(task, response) {
   const expected = parseExpectedSize(task.raw.size || (task.mode === 'generate' ? '1024x1024' : undefined));
-  if (!expected) throw new Error(`${task.id} --dimension-check 需要 size 为 WIDTHxHEIGHT。`);
-  if (!Array.isArray(response.images)) return;
+  if (!expected) throw new DimensionCheckError(`${task.id} --dimension-check 需要 size 为 WIDTHxHEIGHT。`);
+  if (!Array.isArray(response.images)) return response;
+  const images = [];
+  let mismatch;
   for (const image of response.images) {
     const bytes = await readImageBytes(image);
     const actual = readImageDimensions(bytes);
+    images.push({ ...image, dimensions: actual });
     if (actual.width !== expected.width || actual.height !== expected.height) {
-      throw new Error(`${task.id} 尺寸校验失败：期望 ${expected.width}x${expected.height}，实际 ${actual.width}x${actual.height}。`);
+      mismatch ??= actual;
     }
   }
+  if (mismatch) {
+    throw new DimensionCheckError(
+      `${task.id} 尺寸校验失败：期望 ${expected.width}x${expected.height}，实际 ${mismatch.width}x${mismatch.height}。`,
+      { expected, actual: mismatch, response: { ...response, images } }
+    );
+  }
+  return { ...response, images };
 }
 
 async function readImageBytes(image) {

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

@@ -33,6 +33,7 @@ import {
   normalizeImageBackendForPage,
   postPageSse
 } from './lib/page-sse-client.mjs';
+import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
 
 const STREAM_MODES = new Set(['auto', 'stream', 'non_stream']);
 const STREAMING_STRATEGIES = new Set([
@@ -668,6 +669,25 @@ if (routingGuidance.transport === 'page_sse') {
   }
 }
 
+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);
+}
+
 for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
   let response;
   let result;
@@ -720,16 +740,7 @@ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
 const failureOutput = { ...lastResult, retry_after: lastRetryAfter };
 console.error(
   JSON.stringify(
-    attachSummary(
-      failureOutput,
-      buildFailureSummary({
-        errorBody: failureOutput,
-        routing: { transport: 'agent_json', endpoint: '/api/agent/images/edit' },
-        timing: completeScriptTiming(scriptTiming),
-        idempotencyKey,
-        billable: failureOutput?.billable !== false
-      })
-    ),
+    await buildAgentFailureOutput(failureOutput, { transport: 'agent_json', endpoint: '/api/agent/images/edit' }),
     null,
     2
   )

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { AGENT_ENDPOINTS, buildAgentJobResultPath } from './lib/agent-api-paths.mjs';
+import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
 import {
     errorMessage,
     assertValidImageSizeForModel,
@@ -615,7 +616,10 @@ async function runGenerateRequest(options = {}) {
 
     console.error(
         JSON.stringify(
-            buildFailureOutput({ ...lastResult, retry_after: lastRetryAfter }, { transport: 'agent_json', endpoint: AGENT_ENDPOINTS.generate }),
+            await buildAgentFailureOutput(
+                { ...lastResult, retry_after: lastRetryAfter },
+                { transport: 'agent_json', endpoint: AGENT_ENDPOINTS.generate }
+            ),
             null,
             2
         )
@@ -1102,6 +1106,19 @@ function buildFailureOutput(output, routing) {
     );
 }
 
+async function buildAgentFailureOutput(output, routing) {
+    const failure = buildFailureOutput(output, routing);
+    const enriched = await enrichFailureWithAgentDiagnostics({
+        baseUrl,
+        authHeaders,
+        idempotencyKey,
+        failureOutput: failure,
+        summary: failure.summary,
+        timeoutMs
+    });
+    return attachSummary(enriched.failureOutput, enriched.summary);
+}
+
 function buildPageSseFailureStatus(error) {
     if (error && typeof error === 'object') {
         if (Number.isInteger(error.streamStatus)) return { status: error.streamStatus };

skills/gpt-image-playground-agent/scripts/lib/agent-diagnostics-summary.mjs

@@ -0,0 +1,204 @@
+import { AGENT_ENDPOINTS } from './agent-api-paths.mjs';
+
+const DEFAULT_AGENT_DIAGNOSTICS_TIMEOUT_MS = 5000;
+
+export async function enrichFailureWithAgentDiagnostics({
+  baseUrl,
+  authHeaders,
+  idempotencyKey,
+  failureOutput,
+  summary,
+  timeoutMs,
+  diagnosticsTimeoutMs,
+  fetchFn = fetch
+}) {
+  const diagnosticsResult = await fetchAgentDiagnosticsByIdempotencyKey({
+    baseUrl,
+    authHeaders,
+    idempotencyKey,
+    timeoutMs,
+    diagnosticsTimeoutMs,
+    fetchFn
+  });
+
+  const diagnostics = diagnosticsResult.diagnostics;
+  const agentFailureDiagnostics = buildAgentFailureDiagnostics(diagnosticsResult, diagnostics);
+
+  return {
+    failureOutput: {
+      ...failureOutput,
+      ...(agentFailureDiagnostics ? { agent_failure_diagnostics: agentFailureDiagnostics } : {})
+    },
+    summary: mergeDiagnosticsIntoSummary(summary, diagnosticsResult, diagnostics)
+  };
+}
+
+async function fetchAgentDiagnosticsByIdempotencyKey({
+  baseUrl,
+  authHeaders,
+  idempotencyKey,
+  timeoutMs,
+  diagnosticsTimeoutMs,
+  fetchFn
+}) {
+  const url = buildAgentEndpointUrl(baseUrl, AGENT_ENDPOINTS.agent_request_diagnostics_lookup);
+  url.searchParams.set('idempotency_key', idempotencyKey);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), resolveDiagnosticsTimeoutMs(timeoutMs, diagnosticsTimeoutMs));
+  try {
+    const response = await fetchFn(url, {
+      headers: authHeaders(),
+      signal: controller.signal
+    });
+    const text = await response.text();
+    if (!isJsonResponse(response) && text) {
+      return buildUnavailableDiagnosticsResult('non_json_response', response.status);
+    }
+    const result = parseJson(text);
+    if (response.status === 404 && result?.found === false) {
+      return { checked: true, found: false };
+    }
+    if (!response.ok) {
+      return buildUnavailableDiagnosticsResult(`status_${response.status}`, response.status);
+    }
+    if (!result || typeof result !== 'object' || typeof result.found !== 'boolean') {
+      return buildUnavailableDiagnosticsResult('invalid_response', response.status);
+    }
+    if (result.found === true && !isObject(result.diagnostics)) {
+      return buildUnavailableDiagnosticsResult('invalid_response', response.status);
+    }
+    return {
+      checked: true,
+      found: result.found,
+      diagnostics: result.found ? result.diagnostics : null
+    };
+  } catch (error) {
+    return {
+      checked: true,
+      found: false,
+      unavailable_reason: readFetchErrorKind(error)
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function buildAgentEndpointUrl(baseUrl, endpoint) {
+  return new URL(`${String(baseUrl).replace(/\/+$/, '')}${endpoint}`);
+}
+
+function buildUnavailableDiagnosticsResult(unavailableReason, status) {
+  return {
+    checked: true,
+    found: false,
+    unavailable_reason: unavailableReason,
+    ...(Number.isInteger(status) ? { http_status: status } : {})
+  };
+}
+
+function resolveDiagnosticsTimeoutMs(timeoutMs, diagnosticsTimeoutMs) {
+  return Math.min(
+    readPositiveInteger(timeoutMs) || DEFAULT_AGENT_DIAGNOSTICS_TIMEOUT_MS,
+    readPositiveInteger(diagnosticsTimeoutMs) || DEFAULT_AGENT_DIAGNOSTICS_TIMEOUT_MS
+  );
+}
+
+function isJsonResponse(response) {
+  const contentType = typeof response?.headers?.get === 'function' ? response.headers.get('content-type') : '';
+  return String(contentType || '').toLowerCase().includes('application/json');
+}
+
+function buildAgentFailureDiagnostics(result, diagnostics) {
+  if (!result?.checked) return undefined;
+  if (!result.found) {
+    return {
+      checked: true,
+      found: false,
+      unavailable_reason: result.unavailable_reason || null,
+      http_status: result.http_status ?? null
+    };
+  }
+  const request = isObject(diagnostics?.request) ? diagnostics.request : undefined;
+  const error = isObject(diagnostics?.error) ? diagnostics.error : undefined;
+  const errorDiagnostics = isObject(error?.diagnostics) ? error.diagnostics : undefined;
+  const response = isObject(diagnostics?.response) ? diagnostics.response : undefined;
+  const execution = isObject(response?.execution) ? response.execution : undefined;
+  return {
+    checked: true,
+    found: true,
+    request_id: readString(request?.request_id),
+    status: readString(request?.status),
+    error_code: readString(error?.code),
+    retryable: typeof error?.retryable === 'boolean' ? error.retryable : undefined,
+    selected_channel_id: readString(errorDiagnostics?.selected_channel_id) || readString(execution?.selected_channel_id),
+    upstream_host: readString(errorDiagnostics?.upstream_host) || readString(execution?.upstream_host),
+    transport_error_kind: readString(errorDiagnostics?.transport_error_kind)
+  };
+}
+
+function mergeDiagnosticsIntoSummary(summary, diagnosticsResult, diagnostics) {
+  if (!diagnosticsResult?.checked) return summary;
+  const request = isObject(diagnostics?.request) ? diagnostics.request : undefined;
+  const error = isObject(diagnostics?.error) ? diagnostics.error : undefined;
+  const errorDiagnostics = isObject(error?.diagnostics) ? error.diagnostics : undefined;
+  const response = isObject(diagnostics?.response) ? diagnostics.response : undefined;
+  const execution = isObject(response?.execution) ? response.execution : undefined;
+  const diagnosticsRetryable = typeof error?.retryable === 'boolean' ? error.retryable : undefined;
+  return {
+    ...summary,
+    request_id: preferExistingString(summary.request_id, request?.request_id) || null,
+    selected_channel_id:
+      preferExistingString(summary.selected_channel_id, errorDiagnostics?.selected_channel_id, execution?.selected_channel_id) ||
+      null,
+    upstream_host: preferExistingString(summary.upstream_host, errorDiagnostics?.upstream_host, execution?.upstream_host) || null,
+    transport_error_kind: preferExistingString(summary.transport_error_kind, errorDiagnostics?.transport_error_kind) || null,
+    retryable: diagnosticsRetryable ?? summary.retryable,
+    agent_diagnostics_checked: true,
+    agent_diagnostics_found: diagnosticsResult.found === true,
+    agent_diagnostics_unavailable_reason: diagnosticsResult.found ? null : diagnosticsResult.unavailable_reason || null,
+    agent_diagnostics_http_status: diagnosticsResult.found ? null : diagnosticsResult.http_status ?? null,
+    next_action: readDiagnosticsNextAction(summary.next_action, diagnosticsRetryable)
+  };
+}
+
+function readDiagnosticsNextAction(currentNextAction, diagnosticsRetryable) {
+  if (diagnosticsRetryable === true) return 'retry_after_wait';
+  if (diagnosticsRetryable === false) return 'diagnose_then_new_idempotency_key';
+  return currentNextAction || 'diagnose_then_new_idempotency_key';
+}
+
+function preferExistingString(...values) {
+  for (const value of values) {
+    const stringValue = readString(value);
+    if (stringValue) return stringValue;
+  }
+  return undefined;
+}
+
+function parseJson(text) {
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}
+
+function readFetchErrorKind(error) {
+  const name = typeof error?.name === 'string' ? error.name : '';
+  if (name === 'AbortError') return 'diagnostics_timeout';
+  const causeCode = typeof error?.cause?.code === 'string' ? error.cause.code : '';
+  if (causeCode) return causeCode;
+  return 'diagnostics_fetch_failed';
+}
+
+function isObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function readString(value) {
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function readPositiveInteger(value) {
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}

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

@@ -17,6 +17,7 @@ export function buildSuccessSummary({ result, routing, timing, idempotencyKey, b
   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,
@@ -26,6 +27,8 @@ export function buildSuccessSummary({ result, routing, timing, idempotencyKey, b
     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,
@@ -51,15 +54,22 @@ export function buildFailureSummary({ errorBody, routing, timing, idempotencyKey
   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: [],
-    content_urls: [],
-    absolute_content_urls: [],
+    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,
@@ -104,6 +114,10 @@ function stableSummary(value) {
     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,
@@ -114,7 +128,11 @@ function stableSummary(value) {
     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
+    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
   };
 }
 
@@ -154,6 +172,32 @@ function readImageUrls(images, fields) {
     .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);
+}
+
+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);
+}
+
+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 };
+}
+
+function readPositiveInteger(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);

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

@@ -36,7 +36,7 @@ export async function POST(request: NextRequest) {
             requestHash
         );
         if (existingResult) {
-            return agentBeginResultResponse(existingResult, store);
+            return await agentBeginResultResponse(existingResult, store);
         }
         const preparation = await prepareAgentEdit(formData, request.headers);
         const beginResult = await store.beginRequest({

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

@@ -34,7 +34,7 @@ export async function POST(request: NextRequest) {
             requestHash
         );
         if (existingResult) {
-            return agentBeginResultResponse(existingResult, store);
+            return await agentBeginResultResponse(existingResult, store);
         }
         const preparation = prepareAgentGenerate(imageRequest, request.headers);
         const beginResult = await store.beginRequest({