Deploy 4566102 to Docker Space

Source: MisonL/gpt-image-playground-customer@45661020d068d46d33ab0321805725abdd88da69

.env.example

@@ -43,12 +43,32 @@ OPENAI_API_BASE_URL=
 # OPENAI_MAX_STREAMS_PER_CREDENTIAL=1
 # OPENAI_CHANNEL_FAILURE_COOLDOWN_MS=60000
 
+# 可选：多上游图片兼容层默认策略。默认保持 Images API JSON 基线。
+# IMAGE_GENERATION_BACKEND=images-api
+# IMAGE_STREAMING_STRATEGY=auto
+
 # 可选：实验 Responses API 图片后端。默认关闭。
-# 开启后仍需请求显式传入 imageBackend=responses，并单独配置 /responses 顶层模型。
+# 开启后仍需请求显式传入 image_backend=responses-image-generation
+# 或兼容别名 imageBackend=responses，并单独配置 /responses 顶层模型。
 # 表单 model 只作为 image_generation 工具模型，不会复用为 /responses 顶层模型。
 # ENABLE_RESPONSES_IMAGE_BACKEND=true
 # OPENAI_RESPONSES_API_MODEL=
 
+# 可选：独立真实上游 smoke 目标。默认不触发计费请求，必须显式运行 --allow-billable。
+# 每组至少提供 BASE_URL 和 API_KEY；MODEL、SIZE、QUALITY、RESPONSES_MODEL 可按上游覆盖。
+# IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=https://original-new-api.example.com/v1
+# IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=
+# IMAGE_REAL_SMOKE_GAOREN_BASE_URL=https://gaoren-new-api.example.com/v1
+# IMAGE_REAL_SMOKE_GAOREN_API_KEY=
+# IMAGE_REAL_SMOKE_SUB2API_BASE_URL=https://sub2api.example.com/v1
+# IMAGE_REAL_SMOKE_SUB2API_API_KEY=
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL=https://sub2api.example.com/v1
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY=
+# IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://gpt2image.example.com/v1
+# IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=
+# IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4
+# IMAGE_REAL_SMOKE_TIMEOUT_MS=240000
+
 # 可选：给网页加一个访问码。公网部署时建议一定要设置。
 APP_PASSWORD=
 

.env.real-smoke.example

@@ -0,0 +1,45 @@
+# Independent real upstream smoke targets.
+# Copy this file to .env.real-smoke.local and fill only the targets you can run.
+# Do not commit .env.real-smoke.local.
+# Final gate:
+# npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable
+
+# Original QuantumNous/new-api compatible Images API JSON.
+IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=
+IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=
+# IMAGE_REAL_SMOKE_ORIGINAL_MODEL=gpt-image-2
+# IMAGE_REAL_SMOKE_ORIGINAL_SIZE=1024x1024
+# IMAGE_REAL_SMOKE_ORIGINAL_QUALITY=low
+
+# gaoren002/new-api Images API SSE and keepalive branch.
+IMAGE_REAL_SMOKE_GAOREN_BASE_URL=
+IMAGE_REAL_SMOKE_GAOREN_API_KEY=
+# IMAGE_REAL_SMOKE_GAOREN_MODEL=gpt-image-2
+# IMAGE_REAL_SMOKE_GAOREN_SIZE=1024x1024
+# IMAGE_REAL_SMOKE_GAOREN_QUALITY=low
+
+# Wei-Shaw/sub2api Images API SSE.
+IMAGE_REAL_SMOKE_SUB2API_BASE_URL=
+IMAGE_REAL_SMOKE_SUB2API_API_KEY=
+# IMAGE_REAL_SMOKE_SUB2API_MODEL=gpt-image-2
+# IMAGE_REAL_SMOKE_SUB2API_SIZE=1024x1024
+# IMAGE_REAL_SMOKE_SUB2API_QUALITY=low
+
+# sub2api Responses image_generation bridge. If omitted, the smoke script can reuse IMAGE_REAL_SMOKE_SUB2API_*.
+IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL=
+IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY=
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL=gpt-image-2
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL=gpt-5.4
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_SIZE=1024x1024
+# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_QUALITY=low
+
+# GPT2Image style Responses image_generation SSE.
+IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=
+IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=
+# IMAGE_REAL_SMOKE_GPT2IMAGE_MODEL=gpt-image-2
+IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4
+# IMAGE_REAL_SMOKE_GPT2IMAGE_SIZE=1024x1024
+# IMAGE_REAL_SMOKE_GPT2IMAGE_QUALITY=low
+
+# Shared timeout for each real upstream smoke case.
+IMAGE_REAL_SMOKE_TIMEOUT_MS=240000

.gitignore

@@ -36,6 +36,7 @@ dev-server*.log
 .env*
 !.env.example
 !.env.agent.example
+!.env.real-smoke.example
 
 # vercel
 .vercel

README.md

@@ -127,7 +127,7 @@ http://localhost:4783
 - 内置遮罩工具：直接在图片上绘制遮罩，也可以上传 PNG 遮罩。
 - 完整参数控制：模型、尺寸、质量、输出格式、压缩、背景、审核级别、生成数量。
 - 4K 与自定义尺寸：支持 2K/4K 预设和手动输入宽高，并在前端校验尺寸约束。
-- 流式输出：默认开启，支持生成和编辑过程中的局部图片预览。
+- 流式输出：用户显式开启后支持生成和编辑过程中的局部图片预览。
 - 历史记录：保留提示词、参数、图片、耗时、token 使用量和估算费用。
 - 发送到编辑：从生成结果或历史记录直接进入编辑模式。
 - 下载与分享：单图结果可直接下载，分享链接支持访问码和有效期。
@@ -139,17 +139,20 @@ http://localhost:4783
 ## 默认行为
 
 - 图片生成默认使用 `quality=high`。如需降低成本或让上游自行选择质量，可在页面或 Agent 请求中显式改为 `auto`、`medium` 或 `low`。
-- 页面默认开启流式预览；并发流式批处理仍默认关闭，只有设置 `ENABLE_STREAMING_BATCH=true` 后才会把 `n>1` 拆成多个流式任务。
-- 服务端会把官方 OpenAI Images 流式事件和 OtokAPI `image.generation.*` 事件统一映射为前端稳定的 `partial_image`、`completed`、`done`、`error` 事件。
+- 页面默认不发送流式请求；用户显式开启流式预览后，才会走 SSE 路径。并发流式批处理仍默认关闭，只有设置 `ENABLE_STREAMING_BATCH=true` 后才会把 `n>1` 拆成多个流式任务。
+- 服务端会把官方 OpenAI Images 流式事件、gaoren002/new-api 与 sub2api 图片 SSE、OtokAPI `image.generation.*`、Responses `image_generation_call` 事件统一映射为前端稳定的 `partial_image`、`completed`、`done`、`error` 事件。
 - 流式请求失败时会显示原始错误状态和排查建议，不会自动改用非流式请求，以避免隐藏网关、限流或上游故障。
 
 ## 图片后端路径
 
-- 默认路径是服务端中继 OpenAI Images API：`/api/images` 调用上游 `/images/generations` 或 `/images/edits`，再返回本项目稳定的 JSON 或 SSE 协议。
-- OtokAPI 兼容仅发生在流式事件适配层：`image.generation.chunk` 和 `image.generation.result` 会被归一化，不改变页面表单、Agent API 或批量逻辑。
-- Responses API image generation 是实验路径，默认关闭。只有同时设置 `ENABLE_RESPONSES_IMAGE_BACKEND=true`、配置 `OPENAI_RESPONSES_API_MODEL`，并在请求中显式传入 `imageBackend=responses` 时，服务端才会调用 `/responses` 并读取 `image_generation_call.result`。
+- 默认路径是服务端中继 OpenAI Images API：`/api/images` 调用上游 `/images/generations` 或 `/images/edits`，再返回本项目稳定的 JSON 或 SSE 协议。原版 new-api 和 sub2api 普通 JSON 能力保持这个基线。
+- 流式能力由请求字段或环境变量显式控制：`off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。`auto` 不会凭仓库名假设上游能力；Agent 辅助脚本对 `max_edge>2048` 的单次文生图默认优先使用页面端 `/api/images` SSE，失败后先诊断，再显式选择 Agent JSON 或 job 路径。
+- 流式请求在没有 partial image 前只显示连接保持状态，不会把 keepalive 当成图片预览或成功结果。
+- gaoren002/new-api、sub2api、OtokAPI 与 GPT2Image 风格 Responses 兼容仅发生在事件适配层：partial image 只作为预览，只有最终 completed base64 才会保存为 artifact；缺最终 base64 或仅返回远程 URL 会显式失败。
+- Responses API image generation 是实验路径，默认关闭。只有同时设置 `ENABLE_RESPONSES_IMAGE_BACKEND=true`、配置 `OPENAI_RESPONSES_API_MODEL`，并在请求中显式传入 `image_backend=responses-image-generation` 或兼容别名 `imageBackend=responses` 时，服务端才会调用 `/responses` 并读取 `image_generation_call.result`。
+- Agent capabilities 会同时暴露 `supported.image_backends` 枚举和 `supported.enabled_image_backends` 当前启用后端；自动化脚本应以后者和 `image_backend_requirements` 判断 runtime 是否已准备好。
 - Responses API 的顶层模型由 `OPENAI_RESPONSES_API_MODEL` 或请求字段 `responsesModel` 指定；页面表单里的图片模型只传给 `image_generation` 工具。
-- Responses API 实验路径当前只支持非流式单张 `generate`，不替换默认 Images API，不接入现有 Agent API、流式批处理或编辑表单。
+- Responses API 实验路径支持单张 `generate` 的非流式和上游 SSE 消费，不替换默认 Images API，不接入编辑表单。Agent generate 对外仍返回最终 JSON，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用服务端内部上游 SSE 消费。
 
 ## 编辑与遮罩
 
@@ -199,7 +202,7 @@ Agent API 面向自动化调用，不要求 Agent 模拟网页表单。接口统
 | `GET /api/agent/openapi.json` | 获取机器可读 OpenAPI 描述。 |
 | `POST /api/agent/images/generate` | JSON 文生图，默认只返回文件路径和元数据。 |
 | `POST /api/agent/images/edit` | multipart 图片编辑，支持源图和 PNG mask。 |
-| `POST /api/agent/jobs/images/generate` | 创建文生图 job，适合 4K/high 或长耗时请求。 |
+| `POST /api/agent/jobs/images/generate` | 创建文生图 job，适合显式选择 job polling 的长耗时请求；大图单次文生图默认优先按 capabilities 使用页面端 `/api/images` SSE。 |
 | `GET /api/agent/jobs/{id}` | 轮询 job 状态。 |
 | `GET /api/agent/jobs/{id}/result` | 读取完成后的标准图片响应，运行中返回可重试错误。 |
 | `GET /api/agent/artifacts/{id}` | 查询产物元数据。 |
@@ -300,8 +303,10 @@ Web 流式 `/api/images` 事件会同时提供 camelCase 字段和旧 snake_case
 | `OPENAI_CHANNEL_N_API_KEYS` | 否 | 无 | 第 N 个渠道的一个或多个 API Key，多个 key 用英文逗号分隔。 |
 | `OPENAI_CHANNEL_N_FAILURE_COOLDOWN_MS` | 否 | 继承全局值 | 第 N 个渠道的失败冷却时间。 |
 | `ENABLE_STREAMING_BATCH` | 否 | `false` | 显式设为 `true` 后，流式模式下 `n>1` 会拆成多个 `n=1` 任务并发执行。 |
-| `ENABLE_RESPONSES_IMAGE_BACKEND` | 否 | `false` | 实验开关。显式设为 `true` 后，`imageBackend=responses` 请求才可调用 Responses API image generation。 |
-| `OPENAI_RESPONSES_API_MODEL` | 否 | 无 | Responses API 实验后端的 `/responses` 顶层模型。启用 `imageBackend=responses` 时必须设置，或在请求中传 `responsesModel`。 |
+| `IMAGE_GENERATION_BACKEND` | 否 | `images-api` | 服务端默认图片后端，可选 `images-api` 或 `responses-image-generation`。请求字段可覆盖。 |
+| `IMAGE_STREAMING_STRATEGY` | 否 | `auto` | 服务端默认流式兼容策略，可选 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。请求字段可覆盖。 |
+| `ENABLE_RESPONSES_IMAGE_BACKEND` | 否 | `false` | 实验开关。显式设为 `true` 后，`image_backend=responses-image-generation` 或兼容别名 `imageBackend=responses` 请求才可调用 Responses API image generation。 |
+| `OPENAI_RESPONSES_API_MODEL` | 否 | 无 | Responses API 实验后端的 `/responses` 顶层模型。启用 Responses 图片后端时必须设置，或在请求中传 `responsesModel`。 |
 | `OPENAI_MAX_STREAMS_PER_CREDENTIAL` | 否 | `1` | 每个服务端 credential 允许同时执行的流式任务数。 |
 | `OPENAI_CHANNEL_FAILURE_COOLDOWN_MS` | 否 | `60000` | 服务端 credential 或 channel 失败后的默认冷却时间。 |
 | `APP_PASSWORD` | 否 | 无 | 设置后，页面会要求输入访问码。 |
@@ -465,33 +470,44 @@ npm install
 
 要求 Node.js 20 或更高版本。Hugging Face CLI 安装方式以官方文档为准；当前官方入口是 `hf` 命令，登录使用 Hugging Face Access Token。
 
-不同用户首次接手自己的 Space 时，先生成本机访问记录文件：
+本仓库只保留一种推荐的管理员交互方式：先用顶层命令判断状态，再进入具体部署命令。Hugging Face Space 操作使用官方 `hf` CLI；不要再维护本机 access 文件，也不要把 Space Secret 写入仓库。
+
+常用入口：
 
 ```bash
-npm run init-access:hf-space -- \
-  --space-id <namespace>/<space-name> \
-  --space-url https://<user>-<space>.hf.space
+npm run status
+npm run doctor
+npm run verify
+npm run deploy:local
+npm run deploy:space
+npm run agent:doctor
 ```
 
-脚本会写入 `~/.cache/gpt-image-playground-customer/hf-space-access.txt`，生成访问码 `APP_PASSWORD` 和 `AGENT_API_TOKEN`，并记录 `HF_SPACE_ID`、`HF_SPACE_URL` 和默认同步 key。脚本不会打印 Secret 值，且默认不覆盖已有文件。
-`HF_SPACE_URL` 必须是 Hugging Face 的 `https://*.hf.space` 纯 origin 地址，不能包含凭据、路径、查询参数或片段，也不能填写反向代理、自定义域名或普通示例域名。
+`status` 只读输出 git、Node、固定 Space 目标、Agent capabilities 路径、仓库 Skill 入口和独立真实图片上游 smoke 配置摘要。它会按 shell 环境变量、`.env.real-smoke.local`、`.env.local` 的优先级判断真实 smoke 配置是否齐全，但不会输出 URL 或 API Key；`doctor` 汇总本机与 HF Space 诊断；`verify` 执行提交前基线，需要真实 PostgreSQL gate 时加 `--postgres`；`deploy:local` 重建本地 Docker 并探测真实端点；`deploy:space` 是 HF Space 发布的稳定别名；`agent:doctor` 对当前 Agent API 做只读契约检查。
 
-创建本机访问记录文件不需要 Hugging Face 账号密码。同步 Secret 到远端 Space 时，需要本机 `hf` CLI 已登录有目标 Space 管理权限的 Hugging Face Access Token：
+如果只想诊断 HF Space 前置条件，可运行：
 
 ```bash
-hf auth whoami
-hf auth login
+npm run doctor:hf-space
 ```
 
-如果不确定当前机器缺什么，先运行只读诊断：
+该命令会检查 Node、npm、`hf` CLI、HF 登录状态、`node_modules`、git、Docker、固定 Space 目标、���端 Variables 和远端 Secrets；不会写远端 Secret、不会重启 Space、不会打印 Secret 值。
+
+部署当前干净的 git HEAD 到固定 Space：
 
 ```bash
-npm run doctor:hf-space
+npm run deploy:space
 ```
 
-该命令会检查 Node、npm、`hf` CLI、HF 登录状态、`node_modules`、git、Docker、本机 access 文件和可选远端 Space 配置；不会写远端 Secret、不会重启 Space、不会打印 Secret 值。
+该脚本会使用 `git archive HEAD` 生成临时源码目录，通过 `hf upload` 上传到 `misonL/gpt-image-playground-customer`，等待新 Space commit 进入 `RUNNING`，并执行只读公网端点检查。若工作区有未提交改动，脚本会直接失败，避免把本地临时状态误当成可复现发布。
+
+配置或轮换 Space Secret 时，直接使用官方 `hf` CLI：
 
-如果修改了本机访问记录文件里的 `APP_PASSWORD`，可执行 `npm run sync-secret:hf-space` 同步到 Hugging Face Space Secret、重启并验证新访问码。脚本默认读取 `~/.cache/gpt-image-playground-customer/hf-space-access.txt`，并要求目标 Space 写在 access 文件或环境变量里，避免不同用户误写到示例 Space；输出不会回显 Secret 值。
+```bash
+hf spaces variables add misonL/gpt-image-playground-customer -e AGENT_STATE_BACKEND=memory
+hf spaces secrets add misonL/gpt-image-playground-customer -s APP_PASSWORD=<page-access-code>
+hf spaces secrets add misonL/gpt-image-playground-customer -s AGENT_API_TOKEN=<long-random-agent-token>
+```
 
 `memory` 模式不创建 SQLite 文件，也不连接 PostgreSQL。它只适合无持久化演示、短会话调试或可接受重启丢失 Agent 幂等状态的环境；容器重启后请求记录、artifact 元数据和 replay 状态都会清空。Web 图片二进制按 `NEXT_PUBLIC_IMAGE_STORAGE_MODE` 保存；HF 免费层推荐 `indexeddb`，让网页结果保存在浏览器侧。Agent API 产物仍写入容器临时文件系统，以便提供 `content_url` 下载。
 
@@ -542,15 +558,43 @@ docker logs -f gpt-image-playground-customer
 | `npm run dev` | 启动本地开发服务。 |
 | `npm run build` | 执行生产构建。 |
 | `npm run start` | 启动生产模式服务。 |
-| `npm run doctor:hf-space` | 只读诊断 HF Space 部署前置条件、本机 access 文件和远端配置。 |
-| `npm run init-access:hf-space` | 为当前用户生成本机 HF Space 访问记录、随机访问码和 Agent token。 |
+| `npm run status` | 只读输出 git、Node、Space 目标、Agent API、Skill 入口和独立真实图片上游 smoke 配置摘要；会自动读取 `.env.real-smoke.local`，不输出 URL 或 API Key。 |
+| `npm run doctor` | 运行统一诊断入口，默认包含 HF Space 只读远端检查。 |
+| `npm run verify` | 执行提交前基线：测试、lint、脚本语法、构建和 `git diff --check`；加 `-- --postgres` 会包含 live PostgreSQL gate。 |
+| `npm run deploy:local` | 重建本地 Docker 服务并探测 `/api/auth-status`、`/api/runtime-capabilities`、`/api/agent/capabilities`；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。 |
+| `npm run deploy:space` | 上传当前干净 git HEAD 到固定 HF Space，并做只读公网验证。 |
+| `npm run agent:doctor` | 通过仓库 Skill 脚本执行只读 Agent API 契约检查，不触发真实生图。 |
+| `npm run deploy:hf-space` | 使用官方 `hf` CLI 上传当前干净 git HEAD 到固定 Space 并做只读公网验证。 |
+| `npm run doctor:hf-space` | 只读诊断 HF Space 部署前置条件、固定 Space 目标和远端配置。 |
 | `npm run keepalive:hf-space` | 访问 HF Space 只读状态端点，用于 keepalive 验证。 |
-| `npm run sync-secret:hf-space` | 从本机访问记录文件同步 HF Space Secret，并验证页面访问码。 |
-| `npm run smoke:hf-space` | 构建并启动 HF 免费层近似容器，验证 memory 状态后端和 Agent API 契约。 |
+| `npm run smoke:hf-space` | 构建并启动 HF 免费层近似容器，验证 memory 状态后端和 Agent API 契约；慢机器可设置 `HF_SPACE_SMOKE_READY_TIMEOUT_MS`。 |
+| `npm run smoke:image-upstream-compat` | 启动本地 mock 上游，验证 Images API、new-api/sub2api SSE 和 Responses image_generation 兼容契约。 |
+| `npm run smoke:image-upstream-local` | 启动本地 fixture，并通过真实 smoke final gate 跑满 `original-images-json`、`gaoren-images-sse`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse` 五个独立场景。 |
+| `npm run smoke:image-upstream-real` | 检查真实上游 smoke 配置；加 `-- --allow-billable` 后才会触发真实生图。 |
 | `npm run lint` | 检查 `src/` 代码。 |
 | `npm run lint:scripts` | 跨平台检查仓库脚本和 skill 脚本语法。 |
 | `npm run format` | 格式化 `src/` 下的 TypeScript 和 React 文件。 |
 
+真实上游 smoke 使用以下环境变量前缀逐类配置：`IMAGE_REAL_SMOKE_ORIGINAL_*`、`IMAGE_REAL_SMOKE_GAOREN_*`、`IMAGE_REAL_SMOKE_SUB2API_*`、`IMAGE_REAL_SMOKE_SUB2API_RESPONSES_*`、`IMAGE_REAL_SMOKE_GPT2IMAGE_*`。每类至少提供 `BASE_URL` 和 `API_KEY`；Responses 场景还必须提供 `/responses` 顶层模型。可选覆盖图片 `MODEL`、`SIZE`、`QUALITY`。`BASE_URL` 必须是无凭据、无查询参数、无片段的 `http`/`https` 绝对 URL。默认不触发计费请求，必须显式加 `-- --allow-billable`。可复制 `.env.real-smoke.example` 为未跟踪的 `.env.real-smoke.local`，再通过 `-- --env-file .env.real-smoke.local` 加载；shell 环境变量优先级高于 `--env-file`，`--env-file` 优先级高于 `.env.local`。
+
+`npm run smoke:image-upstream-local` 会临时启动仓库内置 fixture，把 5 个独立场景全部指向本机 `/v1` 兼容服务，并调用同一个 `smoke:image-upstream-real -- --require-independent-targets --allow-billable` 门禁路径。该命令用于验证本项目的 final-gate 脚本、事件归一化和本地可复现环境；输出会标记 `local_fixture=true`。它不证明原版 new-api、gaoren/new-api、sub2api 或 GPT2Image 第三方部署当前可访问，真实验收仍需配置 `.env.real-smoke.local` 后运行真实上游门禁。
+
+若只需要验证当前 `.env.local` 中的 `OPENAI_API_KEY` 或 `OPENAI_CHANNEL_N_*` 服务端渠道，可追加 `-- --include-server-channel`。该模式不会把服务端 API Key 写入表单或输出，真实执行仍需同时追加 `--allow-billable`；可覆盖 Images JSON、Images SSE、Responses JSON、Responses SSE、Agent 内部 Images SSE 和 Agent 内部 Responses SSE 场景。可用 `IMAGE_REAL_SMOKE_SERVER_MODEL`、`IMAGE_REAL_SMOKE_SERVER_SIZE`、`IMAGE_REAL_SMOKE_SERVER_QUALITY`、`IMAGE_REAL_SMOKE_SERVER_RESPONSES_MODEL` 覆盖模型、尺寸、质量和 Responses 顶层模型。单场景默认超时 `240000ms`，可用 `--timeout-ms` 或 `IMAGE_REAL_SMOKE_TIMEOUT_MS` 调整。
+
+dry-run 输出中的 `independent_targets` 会汇总必跑、已选、未选、已配置和缺失的独立真实上游场景，并给出最终门禁命令；`required_count` 和 `unselected_required_count` 用于区分必跑总数和未选择数量，`configuration_complete=true` 只表示 5 个必跑场景都已选中且配置齐全，不代表已经执行计费生图。顶层 `final_gate_satisfied=true` 才表示最终独立真实上游门禁已实际执行并通过。`missing_env_any` 表示每组任选一个环境变量即可补齐该缺失项。例如 `sub2api-responses-json` 的 `BASE_URL` 和 `API_KEY` 可单独配置 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_*`，也可以复用 `IMAGE_REAL_SMOKE_SUB2API_*`；它的 `/responses` 顶层模型必须使用 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL`，避免和图片模型 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL` 混淆。
+
+最终验收独立真实上游时追加 `-- --require-independent-targets --allow-billable`。此时任一独立真实上游场景未被选中或被跳过都会让脚本以非零退出，并在 `unselected_required_cases`、`skipped_required_cases`、`missing_required_count` 和 `missing_required_cases` 中列出未完成的场景。若最终门禁预检发现必跑场景未选全、缺少配置或配置非法，脚本会阻断可运行目标并先失败，不触发任何真实上游计费调用。
+
+`--include-server-channel` 只能验证当前 `.env.local` 服务端渠道，不能替代独立真实上游门禁。最终验收必须让以下 5 个独立场景都实际执行，且结果中 `skipped=false`：
+
+| 场景 ID | 验证对象 | 必需配置 |
+| --- | --- | --- |
+| `original-images-json` | 原版 QuantumNous/new-api 兼容 Images API JSON | `IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL`、`IMAGE_REAL_SMOKE_ORIGINAL_API_KEY` |
+| `gaoren-images-sse` | gaoren002/new-api Images API SSE/keepalive 分支 | `IMAGE_REAL_SMOKE_GAOREN_BASE_URL`、`IMAGE_REAL_SMOKE_GAOREN_API_KEY` |
+| `sub2api-images-sse` | Wei-Shaw/sub2api Images API SSE | `IMAGE_REAL_SMOKE_SUB2API_BASE_URL`、`IMAGE_REAL_SMOKE_SUB2API_API_KEY` |
+| `sub2api-responses-json` | sub2api Responses image_generation bridge | `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL`、`IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY` 或复用 `IMAGE_REAL_SMOKE_SUB2API_BASE_URL`、`IMAGE_REAL_SMOKE_SUB2API_API_KEY`；另需 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL` |
+| `gpt2image-responses-sse` | GPT2Image 风格 Responses image_generation SSE | `IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL`、`IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY`；另需 `IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL` |
+
 ## 常见问题
 
 ### 提示未检测到 Node.js

docker-compose.memory.yml

@@ -1,8 +1,12 @@
 services:
   gpt-image-playground:
+    build:
+      args:
+        NEXT_PUBLIC_IMAGE_STORAGE_MODE: indexeddb
     environment:
       AGENT_STATE_BACKEND: memory
       AGENT_SQLITE_PATH: ""
       AGENT_DATABASE_URL: ""
       AGENT_DB_PASSWORD: ""
       AGENT_DB_PASSWORD_FILE: ""
+      NEXT_PUBLIC_IMAGE_STORAGE_MODE: indexeddb

docs/deployment/huggingface-space-free.md

@@ -45,7 +45,7 @@ hf auth whoami
 - npm 随 Node.js 一起可用。
 - Hugging Face CLI 使用当前官方 `hf` 命令。
 - `hf auth login` 使用 Hugging Face Access Token，不是账号密码。
-- Docker 只对 `npm run smoke:hf-space` 和本地容器验证必需；只创建 txt 文件和同步 Secret 不需要 Docker。
+- Docker 只对 `npm run smoke:hf-space` 和本地容器验证必需；部署到远端 Space 使用 `hf` CLI。
 
 安装 Hugging Face CLI 时，以官方文档为准。不要把远程安装脚本直接管道到 shell；如需使用官方脚本，先下载、核对来源和内容后再执行。
 
@@ -58,10 +58,58 @@ npm install
 如果不确定当前机器缺什么，运行只读诊断：
 
 ```bash
-npm run doctor:hf-space
+npm run doctor
 ```
 
-`doctor:hf-space` 会检查 Node、npm、`hf` CLI、HF 登录状态、`node_modules`、git、Docker、本机 access 文件和可选远端 Space 配置。该命令不会写远端 Secret、不会重启 Space、不会打印 Secret 值。
+`doctor` 会检查 Node、npm、`hf` CLI、HF 登录状态、`node_modules`、git、Docker、固定 Space 目标、远端 Variables 和远端 Secrets。该命令不会写远端 Secret、不会重启 Space、不会打印 Secret 值。
+
+## 管理员命令中心
+
+本仓库只保留一组稳定管理员入口：
+
+```bash
+npm run status
+npm run doctor
+npm run verify
+npm run deploy:local
+npm run deploy:space
+npm run agent:doctor
+```
+
+- `status`：只读输出 git、Node、固定 Space 目标、Agent capabilities 路径和 Skill 入口。
+- `doctor`：统一诊断入口，默认包含 HF Space 只读远端检查。
+- `verify`：提交前基线，执行测试、lint、脚本语法、构建和 `git diff --check`；需要真实 PostgreSQL gate 时加 `--postgres`。
+- `deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `--memory` 会断言 memory/indexeddb overlay 生效。
+- `deploy:space`：上传当前干净 git HEAD 到固定 HF Space，并做只读公网验证。
+- `agent:doctor`：通过仓库 Skill 脚本执行只读 Agent API 契约检查，不触发真实生图。
+
+HF Space 交互使用官方 `hf` CLI。不要维护本机 access 文件，不要把 `APP_PASSWORD`、`AGENT_API_TOKEN`、OpenAI Key 或 Hugging Face token 写入仓库文件。
+
+部署当前干净的 git HEAD 到固定 Space：
+
+```bash
+npm run deploy:space
+```
+
+该脚本会：
+
+- 使用 `git status --porcelain` 拒绝脏工作区。
+- 使用 `git archive HEAD` 生成临时源码目录，只上传已跟踪源码。
+- 使用 `hf upload` 上传到 `misonL/gpt-image-playground-customer`。
+- 等待新 Space commit 进入 `RUNNING`。
+- 检查 `/api/auth-status`、`/api/agent/capabilities` 和 `/api/runtime-capabilities`，不触发真实生图。
+
+配置或轮换 Variables/Secrets 时，直接使用官方 `hf` CLI：
+
+```bash
+hf spaces variables add misonL/gpt-image-playground-customer -e AGENT_STATE_BACKEND=memory
+hf spaces variables add misonL/gpt-image-playground-customer -e NEXT_PUBLIC_IMAGE_STORAGE_MODE=indexeddb
+hf spaces variables add misonL/gpt-image-playground-customer -e APP_LOG_LEVEL=warn
+hf spaces secrets add misonL/gpt-image-playground-customer -s APP_PASSWORD=<page-access-code>
+hf spaces secrets add misonL/gpt-image-playground-customer -s AGENT_API_TOKEN=<long-random-agent-token>
+```
+
+源码部署、远端诊断、Variables 和 Secrets 都围绕 `hf` CLI 完成；仓库内不再提供第二套 access-file 同步流程。
 
 ## Space Variables
 
@@ -160,6 +208,7 @@ npm run smoke:hf-space
 - 以 `AGENT_STATE_BACKEND=memory` 启动临时容器。
 - 用手机 User-Agent 检查首页可访问。
 - 检查 `/api/agent/capabilities` 返回 `state_backend=memory` 和 `image_storage_mode=indexeddb`。
+- 默认等待容器 HTTP ready 最多 45 秒；慢机器可设置 `HF_SPACE_SMOKE_READY_TIMEOUT_MS=90000`。
 - 执行 Agent 生成和编辑脚本的契约检查，不触发真实上游生图。
 
 ## 免费层限制
@@ -195,110 +244,6 @@ npm run keepalive:hf-space
 
 注意：keepalive 是免费层的 best-effort 机制，不能保证绕过 Hugging Face 平台维护、重启或政策限制。若需要平台级保证，应升级到付费硬件并设置永不休眠。
 
-## 初始化本机访问记录
-
-不同用户首次接手自己的 Space 时，先在本机生成访问记录文件。该文件保存在用户 home 目录下，不应提交到仓库：
-
-```bash
-npm run init-access:hf-space -- \
-  --space-id <namespace>/<space-name> \
-  --space-url https://<user>-<space>.hf.space
-```
-
-默认写入：
-
-```text
-~/.cache/gpt-image-playground-customer/hf-space-access.txt
-```
-
-文件会包含：
-
-```dotenv
-HF_SPACE_ID=<namespace>/<space-name>
-HF_SPACE_URL=https://<user>-<space>.hf.space
-HF_SPACE_SECRET_KEYS=APP_PASSWORD,AGENT_API_TOKEN
-APP_PASSWORD=<generated-page-access-code>
-AGENT_API_TOKEN=<generated-agent-token>
-```
-
-`HF_SPACE_URL` 必须是 Hugging Face 的 `https://*.hf.space` 纯 origin 地址，不能包含凭据、路径、查询参数或片段，也不能填写反向���理、自定义域名或普通示例域名。
-
-脚本不会在输出中回显 `APP_PASSWORD` 或 `AGENT_API_TOKEN`。如果文件已存在，默认拒绝覆盖；确认要重置时使用：
-
-```bash
-npm run init-access:hf-space -- \
-  --space-id <namespace>/<space-name> \
-  --space-url https://<user>-<space>.hf.space \
-  --force
-```
-
-创建这个 txt 文件不需要 Hugging Face 账号密码。它只保存本项目的访问码、Agent token 和 Space 目标信息。
-
-同步 Secret 到远端 Space 时，需要本机 `hf` CLI 已登录有目标 Space 管理权限的 Hugging Face Access Token。先检查登录状态：
-
-```bash
-hf auth whoami
-```
-
-如果未登录，执行：
-
-```bash
-hf auth login
-```
-
-`hf auth login` 使用的是 Hugging Face Access Token，不是账号密码。不要把 HF 账号密码或 HF Access Token 写入 `hf-space-access.txt`。
-
-生成后可先做本机只读诊断，不写远端：
-
-```bash
-npm run doctor:hf-space -- --skip-remote
-```
-
-如果诊断提示 access 文件缺少 `HF_SPACE_ID`、`HF_SPACE_URL` 或 `HF_SPACE_SECRET_KEYS`，说明本机可能已有旧格式文件。可手工补齐这些字段，或确认重置后重新生成：
-
-```bash
-npm run init-access:hf-space -- \
-  --space-id <namespace>/<space-name> \
-  --space-url https://<user>-<space>.hf.space \
-  --force
-```
-
-## 同步本机访问码到 Space
-
-如果本机访问记录文件里的 `APP_PASSWORD` 已更新，可以用脚本同步到 HF Space Secret、重启服务并验证新访问码：
-
-```bash
-npm run sync-secret:hf-space
-```
-
-默认读取：
-
-```text
-~/.cache/gpt-image-playground-customer/hf-space-access.txt
-```
-
-由 `init-access:hf-space` 生成的文件会让同步脚本同时同步 `APP_PASSWORD` 和 `AGENT_API_TOKEN`。旧格式文件默认只同步 `APP_PASSWORD`，不会在输出中回显访问码值。可通过环境变量覆盖目标或同步多个 key：
-
-```bash
-HF_SPACE_ID=misonL/gpt-image-playground-customer \
-HF_SPACE_URL=https://misonl-gpt-image-playground-customer.hf.space \
-HF_SPACE_ACCESS_FILE=~/.cache/gpt-image-playground-customer/hf-space-access.txt \
-HF_SPACE_SECRET_KEYS=APP_PASSWORD,AGENT_API_TOKEN \
-npm run sync-secret:hf-space
-```
-
-同步脚本默认要求 `HF_SPACE_ID` 和 `HF_SPACE_URL` 来自 access 文件或环境变量，避免不同用户误写到仓库示例 Space。只有维护默认示例 Space 时才使用：
-
-```bash
-npm run sync-secret:hf-space -- --use-default-target
-```
-
-可选参数：
-
-- `npm run sync-secret:hf-space -- --no-restart`：只写 Secret，不重启 Space。
-- `npm run sync-secret:hf-space -- --skip-verify`：跳过 `/api/auth-verify` 访问码验证。
-- `npm run sync-secret:hf-space -- --use-default-target`：允许使用脚本内置默认 Space 目标。
-
 ## 验证门禁
 
 最小验证：
@@ -315,7 +260,7 @@ git diff --check
 
 真实 Hugging Face gate：
 
-1. 推送到 Space 仓库后等待构建完成。
+1. 提交代码后执行 `npm run deploy:space`，等待 Space 新 commit 进入 `RUNNING`。
 2. 手机打开 Space 页面，确认能进入页面并发起一次真实生成。
 3. 电脑执行 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 契约检查。
 4. 如有可用测试额度，再执行一次真实 Agent 生成。

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

@@ -0,0 +1,34 @@
+# CR-AGENT-ROUTING-LOCAL-FINAL-GATE-2026-05-22
+
+## 范围
+
+- Agent 图片端点路由契约、错误诊断与终态失败语义。
+- 本地图片上游 fixture 与 `smoke:image-upstream-real` final gate 复用路径。
+- 本记录只证明本地 fixture、脚本门禁与当前代码契约；不证明第三方真实部署当前可访问。
+
+## 审计结论
+
+- `/api/agent/capabilities` 现在暴露机器可读 `routing_rules`，`schema_version=2026-05-22`。
+- 高分辨率 Agent edit 请求在 route 层 `snapshotAgentEditFormData` 前被拒绝，服务层也在读取服务端 API 凭据前保留二道校验。
+- partial-only 上游 SSE 失败会保留 `upstream_event_type` 与 `partial_image_count`，但不会泄漏 partial base64。
+- 已进入终态 `failed` 的 Agent/job 回放会移除 `retry_after_seconds` 并返回 `retryable=false`。
+- 本地 final gate 启动仓库 fixture 后复用真实 smoke 脚本，跑满 5 个独立场景并要求 `final_gate_satisfied=true`。
+- 本地 final gate 会跳过 `.env.local` 加载，并清理 `IMAGE_REAL_SMOKE_*`、`OPENAI_*`、`APP_PASSWORD`、`AGENT_API_TOKEN` 等外层输入，避免 shell 凭据污染本地 fixture 验证。
+
+## 验证记录
+
+| 命令 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `npm test` | 0 | 462 个测试通过；PostgreSQL live 子套件因 `AGENT_POSTGRES_TEST_DATABASE_URL` 未配置跳过。 |
+| `npm run lint` | 0 | `eslint src` 通过。 |
+| `npm run lint:scripts` | 0 | 脚本语法检查通过。 |
+| `npm run build` | 0 | Next.js production build 通过，standalone runtime patch 完成。 |
+| `node scripts/smoke-image-upstream-local-final-gate.mjs --timeout-ms 30000` | 0 | 5 个独立本地 fixture 场景全部通过，`final_gate_satisfied=true`。 |
+| `git diff --check` | 0 | 当前 diff 无 whitespace error。 |
+| 装饰符扫描 | 0 | 代码与 Markdown 改动中未发现 AGENTS.md 禁止的装饰性 Unicode 符号。 |
+| `coderabbit review --prompt-only -t uncommitted` | 0 | CodeRabbit 返回 `findings=0`。 |
+
+## 剩余边界
+
+- 本轮未运行真实第三方上游 `--allow-billable` 门禁；独立真实上游仍需要 `.env.real-smoke.local` 提供 5 类真实目标后再跑 `npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable`。
+- 本轮未运行 live PostgreSQL gate；数据库真实行为仍以 `npm run test:postgres` 或 `npm run verify -- --postgres` 为准。

docs/reviews/CR-IMAGE-UPSTREAM-COMPAT-2026-05-21.md

@@ -0,0 +1,189 @@
+# CR-IMAGE-UPSTREAM-COMPAT-2026-05-21
+
+## 范围
+
+- 多上游图片生成兼容层阶段验证。
+- 区分本地 mock 覆盖、当前真实上游 smoke、以及本机未配置的上游类型。
+- 记录 2026-05-21 在 `codex/image-upstream-compat` 分支上的验证口径。
+
+## 当前真实上游范围
+
+`.env.local` 当前只配置了 `superapi.buzz` 这一类真实上游，共 7 个服务端渠道。没有可直接区分的原版 QuantumNous/new-api、gaoren002/new-api、Wei-Shaw/sub2api 或独立 GPT2Image 部署地址。因此“原版 new-api / gaoren / sub2api / GPT2Image”差异主要由本地契约测试覆盖，真实 smoke 只能证明当前 `superapi.buzz` 上游在对应协议路径下的表现。
+
+当前独立真实上游配置检查：`.env.local` 没有 `IMAGE_REAL_SMOKE_*` 键，`.env.real-smoke.local` 不存在。仓库提供 `.env.real-smoke.example` 作为可提交模板，真实凭据仍应写入未跟踪的 `.env.real-smoke.local`。`npm run smoke:image-upstream-real` 当前返回 `independent_targets.configured_count=0`、`missing_count=5`。`npm run smoke:image-upstream-real -- --require-independent-targets` 当前以退出码 `1` 按预期失败，`skipped_required_cases` 为 `original-images-json`、`gaoren-images-sse`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`。
+
+## 真实 smoke 结果
+
+运行方式：在当前 worktree 启动 `npx next dev --turbopack -p 4784`；Responses 路径使用 `ENABLE_RESPONSES_IMAGE_BACKEND=true OPENAI_RESPONSES_API_MODEL=gpt-5.4` 重启同端口服务。所有输出均只记录状态、事件类型、图片数量和 base64 长度，不记录 API key 或完整图片数据。
+
+| 场景 | 结果 | 证据摘要 |
+| --- | --- | --- |
+| Images API 普通 JSON | 通过 | `/api/images` 返回 `200 application/json`，`image_count=1`，`first_b64_length=1045668`，耗时 `19921ms`。 |
+| Images API SSE / keepalive 策略 | 通过 | `/api/images` 返回 `200 text/event-stream`，事件为 `partial_image, partial_image, completed, done`，`done_image_count=1`，耗时 `29615ms`。 |
+| Responses image_generation 非流式 | 当前真实上游未通过 | `/api/images` 返回 `500 application/json`，错误为 `Responses API 未返回已完成的 image_generation_call.result。`。该结果说明当前真实上游的非流式 `/responses` 返回结构不满足本项目 final image 契约。 |
+| Responses image_generation SSE 初测 | 暴露缺口后已修复 | 初测事件为 `partial_image, completed, error`，错误为 `response.output_item.done` 缺少图片 payload。修复后无图的 Responses output item done 会被忽略，仍要求整条流最终有 final image。 |
+| Responses image_generation SSE 去重复测 | 通过 | `/api/images` 返回 `200 text/event-stream`，事件为 `partial_image, completed, done`，`done_image_count=1`，耗时 `46624ms`。 |
+| Agent 内部 Images SSE | 通过 | `/api/agent/images/generate` 返回 `200 application/json`，`image_count=1`，产物 URL 为 `/api/agent/artifacts/.../content`，未返回客户端 SSE，耗时 `96081ms`。 |
+
+## 2026-05-22 脚本化真实复验
+
+运行方式：`npm run smoke:image-upstream-real -- --include-server-channel` 先做 dry-run，确认 5 个独立真实目标因缺少专用 `IMAGE_REAL_SMOKE_*_BASE_URL` 跳过，当前 `.env.local` 服务端渠道只在追加 `--allow-billable` 后执行。随后使用 `--timeout-ms 180000` 对当前服务端渠道逐项真实调用。输出只记录 host、状态、事件类型、数量和 base64 长度。
+
+| 场景 | 结果 | 证据摘要 |
+| --- | --- | --- |
+| 当前服务端渠道 Images JSON 首次 | 显式失败 | `server-channel-images-json` 返回 `500 application/json`，`error=Connection error.`，耗时 `186537ms`，无图片。 |
+| 当前服务端渠道 Images JSON 复测 | 通过 | `server-channel-images-json` 返回 `200 application/json`，`image_count=1`，`first_b64_length=1332092`，耗时 `164893ms`。 |
+| 当前服务端渠道 Images SSE | 通过 | `server-channel-images-sse` 返回 `200 text/event-stream`，事件为 `partial_image, partial_image, partial_image, completed, done`，`done_image_count=1`，`first_b64_length=1573772`，耗时 `10843ms`。 |
+| 当前服务端渠道 Responses SSE | 通过 | `server-channel-responses-sse` 返回 `200 text/event-stream`，事件为 `partial_image, partial_image, completed, done`，`done_image_count=1`，`first_b64_length=1157276`，耗时 `3232ms`。 |
+| 当前服务端渠道 Agent 内部 Images SSE | 通过 | `server-channel-agent-images-sse` 通过 `npm run smoke:image-upstream-real -- --include-server-channel --allow-billable --timeout-ms 180000 --case server-channel-agent-images-sse` 验证，返回 `200 application/json`，`image_count=1`，产物 URL 为 `/api/agent/artifacts/.../content`，未内联 base64，耗时 `59243ms`。 |
+| 当前服务端渠道 Agent 内部 Responses SSE | 通过 | `server-channel-agent-responses-sse` 通过 `npm run smoke:image-upstream-real -- --include-server-channel --allow-billable --timeout-ms 180000 --case server-channel-agent-responses-sse` 验证，返回 `200 application/json`，`image_count=1`，产物 URL 为 `/api/agent/artifacts/.../content`，未内联 base64，耗时 `19270ms`。 |
+
+## 本地契约覆盖
+
+- `npm run smoke:image-upstream-compat` 启动临时本地 mock 上游并直接调用当前 `/api/images` route，覆盖原版 new-api Images API JSON、sub2api Images API JSON、gaoren new-api Images SSE keepalive、gaoren JSON-as-SSE completed、sub2api Images SSE、sub2api Responses image_generation bridge JSON、GPT2Image Responses image_generation SSE。
+- `npm run smoke:image-upstream-real` 提供真实上游 smoke 入口，默认只检查 `IMAGE_REAL_SMOKE_*` 配置，不加 `-- --allow-billable` 不会触发生图。当前运行结果为 5 个独立真实目标均跳过，原因是未配置独立真实上游 `BASE_URL` 环境变量。脚本已支持 `--include-server-channel`，可复用当前 `.env.local` 的服务端渠道跑 Images JSON、Images SSE、Responses JSON、Responses SSE、Agent 内部 Images SSE 和 Agent 内部 Responses SSE smoke，且不把服务端 API Key 写入表单或输出；单场景默认超时 `240000ms`。dry-run 会返回 `independent_targets` 和 `missing_env_any`，汇总必跑、已选、未选、已配置与缺失的独立目标，并用 `required_count`、`unselected_required_count`、`configuration_complete` 和顶层 `final_gate_satisfied` 明确 5 个必跑场景是否全部已实际执行并通过；非计费阶段会拒绝带凭据、查询参数或片段的 `BASE_URL`；最终验收可加 `--require-independent-targets --allow-billable`，让任何独立真实上游未被选中或被跳过都以非零退出，并写入 `unselected_required_cases`、`skipped_required_cases`、`missing_required_count` 和 `missing_required_cases`。脚本支持 `--env-file <path>` 加载独立真实 smoke 凭据文件，shell 环境变量优先级高于 `--env-file`，`--env-file` 优先级高于 `.env.local`，便于把原版 new-api、gaoren、sub2api、GPT2Image 的真实目标与主服务渠道配置隔离。`.env.real-smoke.example` 是可提交模板，`.env.real-smoke.local` 继续被 `.gitignore` 排除。`scripts/smoke-image-upstream-real.test.mjs` 覆盖默认非计费、配置后仍需显式授权、当前服务端渠道 dry-run 不泄漏 API key、独立上游准备度摘要、独立上游必跑门禁、缺失 env 诊断、unsafe `BASE_URL` 预检、超时参数校验、未知场景显式失败、显式 env 文件加载优先级、测试隔离 `.env.local` 私有渠道配置，以及本地 billable Agent smoke 后清理 `generated-images/.real-smoke` 新增图片产物。
+- `src/lib/image-stream-events.test.ts` 覆盖 OpenAI Images、OtokAPI、Responses partial、Responses partial `b64_json` 兼容字段、Responses image_generation_call completed marker、顶层 completed result、Responses output item done、Responses completed、远程 URL-only 显式失败、`response.failed` 显式失败、`response.completed` 内 `image_generation_call.status=failed` 显式失败、`image_generation_call.status=failed` 显式失败、keepalive/非对象忽略。
+- `src/lib/responses-image-backend.test.ts` 覆盖 Responses image_generation 非流式后端：读取 `image_generation_call.result`、接受省略 `status` 但提供 `result` 的兼容响应、拒绝远程 URL-only 结果、显式暴露 failed `image_generation_call` 错误、提取 data URL base64、以及流式请求参数。
+- `src/app/api/images/route.test.ts` 覆盖 Images API 非流式 JSON、Images API SSE、Images API 与 Responses image_generation 下 `force-sse` 在请求省略旧 `stream` 字段时仍进入上游 SSE、gaoren JSON-as-SSE completed 包装、SDK/relay 包装 SSE、stream 断开错误、Images API 非流式远程 URL-only 显式 502 失败、Responses 后端非流式、Responses 后端 SSE、以及 Responses failed `image_generation_call` 在 JSON/SSE 两条页面路径上都返回稳定 502 错误契约。
+- `src/app/api/agent/agent-routes.test.ts` 覆盖 Agent 默认最终 JSON、`streaming_strategy=off` 不发送上游流式参数、Images API 与 Responses image_generation 下 `streaming_strategy=force-sse` 发送上游 stream 但对外仍返回最终 JSON、直接 generate 内部 Images SSE 消费、直接 generate 内部 Responses image_generation SSE 消费、Responses failed `image_generation_call` 归一化为 `upstream_unavailable`、job polling 内部 Images SSE 消费并保存最终 artifact、job polling 内部 Responses image_generation SSE 消费并保存最终 artifact、直接 generate 与 job polling 的 Images API / Responses image_generation partial-only 无 final image 失败。
+- `src/lib/agent-api-contracts.test.ts` 覆盖 capabilities/OpenAPI 中页面 SSE、Agent 内部 upstream SSE、最终响应契约、后端枚举、流式策略枚举、真正启用上游 SSE 的 activation 策略和默认非流式 Agent 策略。
+- `src/lib/image-stream-service.test.ts` 和 `src/lib/image-stream-collector.test.ts` 覆盖 Responses 流中同一 final image 跨事件重复到达、以及单个完成事件同时经 SDK/Responses 包装层重复抽取时只保存一份最终产物；同一事件内合法多图结果仍保留多张图片。
+- 浏览器 UI smoke：`npm run dev -- --port 4785` 启动页面后确认默认未勾选流式预览；高级参数展示 Images API / Responses image_generation 后端与 6 个流式策略；4K/high + auto 显示流式建议；Responses 后端显示“Responses 顶层模型”；注入本地 fetch SSE keepalive stub 后，持续 keepalive 流只显示“连接保持中...”，不生成预览或成功结果。快速关闭且无 final image 的 keepalive 流会显式失败为“API 响应中没有有效图片数据或文件名。”，不伪造成功。2026-05-22 复验中，浏览器实际提交字段包含 `stream=true`、`partial_images=1`、`size=3072x2048`、`quality=high`、`image_backend=responses-image-generation`、`image_streaming_strategy=auto`；页面 DOM 中 `document.images` 为空，最终显示上述显式错误。
+- 运行态 Agent contract smoke：`npm run dev -- --port 4785` 启动后，`GET /api/agent/capabilities` 返回 `defaults.streaming_strategy=off`、`agent_streaming.generate.mode=non_streaming_only`、`agent_streaming.upstream_sse.mode=internal_upstream_sse`、`final_response_contract=AgentImageResponse`，并列出 `image_backend`、`streaming_strategy`、`partial_images` 三个内部上游 SSE 请求字段；`GET /api/agent/openapi.json` 的 `GenerateRequest` schema 同样包含这三个字段，`AgentStreamingCapabilities.upstream_sse.request_fields` 与 capabilities 一致；`GET /api/runtime-capabilities` 当前显示 `responsesImageBackend.enabled=false`、`mode=experimental`。
+
+## 2026-05-22 当前 worktree 基线复验
+
+本轮补充复核：`npm test`、`npm run lint`、`npm run lint:scripts`、`npm run build`、`npm run smoke:image-upstream-compat`、`git diff --check` 均重新通过。`npm run smoke:image-upstream-real -- --include-server-channel` 以非计费 dry-run 通过；`npm run smoke:image-upstream-real -- --require-independent-targets` 继续按预期以退出码 `1` 失败，原因是 `.env.real-smoke.local` 不存在且 5 个独立真实上游目标均缺少专用 `IMAGE_REAL_SMOKE_*_BASE_URL`。本轮收尾未追加新的 `--allow-billable` 请求；表中带 `--allow-billable` 的服务端渠道记录为同日此前已记录的真实服务端渠道证据，不等同于独立真实上游最终门禁。`generated-images/.real-smoke` 目录无产物残留。
+
+| 命令 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `npm test` | 0 | `425` 个测试通过，`0` 个失败。PostgreSQL live 测试因 `AGENT_POSTGRES_TEST_DATABASE_URL` 未配置跳过。 |
+| `npm run lint` | 0 | `eslint src` 通过。 |
+| `npm run lint:scripts` | 0 | `scripts/check-node-syntax.mjs` 通过。 |
+| `npm run build` | 0 | Next.js 16.2.6 production build 通过，standalone runtime patch 完成。 |
+| `npm run test:postgres` | 0 | 临时 `postgres:16-alpine` 容器内 55 个测试通过，覆盖 Agent route PostgreSQL 集成、Postgres schema/live concurrency、迁移、清理和 share metadata 契约。 |
+| `npx tsc --noEmit` | 0 | 测试和源码 TypeScript 静态检查通过。 |
+| `npm audit --audit-level=high` | 0 | `found 0 vulnerabilities`。 |
+| `npm run smoke:image-upstream-compat` | 0 | 7 个本地 mock 上游兼容场景全部通过。 |
+| `node --import tsx --test scripts/smoke-image-upstream-real.test.mjs` | 0 | 20 个脚本测试通过，覆盖 help 输出列出所有独立真实上游 env 前缀、`--env-file`、当前服务端 Responses JSON 和 Agent Responses SSE dry-run、非计费阶段拒绝 unsafe `BASE_URL`、独立上游准备度摘要、显式 env 文件加载优先级、测试隔离 `.env.local` 私有渠道配置、本地 billable Agent smoke 后清理 `generated-images/.real-smoke` 新增图片产物、独立上游必跑/已选/未选场景报告、`--require-independent-targets --case ...` 子集运行不能误报通过、只选择 server-channel 场景时最终门禁不能误报通过、5 个独立目标全部实际跑通后 `final_gate_satisfied=true`，以及本地 mock billable Responses JSON 走 `/v1/responses` 并返回图片。 |
+| `npm run smoke:image-upstream-real -- --help` | 0 | help 输出列出 `--env-file <path>`、`IMAGE_REAL_SMOKE_ORIGINAL_*`、`IMAGE_REAL_SMOKE_GAOREN_*`、`IMAGE_REAL_SMOKE_SUB2API_*`、`IMAGE_REAL_SMOKE_SUB2API_RESPONSES_*`、`IMAGE_REAL_SMOKE_GPT2IMAGE_*`。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel` | 0 | 非计费 dry-run 通过；`independent_targets.configured_count=0`、`missing_count=5`；5 个独立真实上游目标因缺少 `IMAGE_REAL_SMOKE_*_BASE_URL` 跳过；当前服务端渠道因缺少 `--allow-billable` 跳过，未触发真实生图。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel --case server-channel-responses-json` | 0 | 非计费 dry-run 通过；当前服务端 Responses JSON smoke 识别 `superapi.buzz` 渠道，因缺少 `--allow-billable` 跳过，未触发真实��图。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel --case server-channel-agent-responses-sse` | 0 | 非计费 dry-run 通过；当前服务端 Agent Responses SSE smoke 识别 `superapi.buzz` 渠道，因缺少 `--allow-billable` 跳过，未触发真实生图。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel --allow-billable --timeout-ms 180000 --case server-channel-agent-responses-sse` | 0 | 同日此前记录的真实服务端渠道通过；返回 `200 application/json`，`image_count=1`，`first_content_url=/api/agent/artifacts/.../content`，`has_inline_base64=false`。 |
+| `npm run smoke:image-upstream-real -- --require-independent-targets` | 1 | 预期失败；`independent_targets.configured_count=0`、`missing_count=5`；`skipped_required_cases` 为 `original-images-json`、`gaoren-images-sse`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`。 |
+| `npm run smoke:image-upstream-real -- --env-file .env.real-smoke.example --require-independent-targets` | 1 | 预期失败；可提交模板中的空值不会被误判为已配置真实上游，5 个独立真实目标仍全部列入 `skipped_required_cases`。 |
+| `git diff --check` | 0 | 当前 diff 无 whitespace error。 |
+| `find generated-images/.real-smoke ...` | 0 | 当前 `generated-images/.real-smoke` 目录无新增 `png`、`jpg`、`jpeg`、`webp` 产物残留。 |
+
+## 2026-05-22 运行态契约复验
+
+运行方式：`npx next dev --turbopack -p 4785` 启动本地服务后，只读请求 `GET /api/agent/capabilities`、`GET /api/agent/openapi.json`、`GET /api/runtime-capabilities`。
+
+| 端点 | 结果 | 摘要 |
+| --- | --- | --- |
+| `/api/agent/capabilities` | 通过 | `defaults.image_backend=images-api`，`defaults.streaming_strategy=off`，`defaults.partial_images=2`；`agent_streaming.generate.mode=non_streaming_only`，`agent_streaming.edit.mode=non_streaming_only`，`agent_streaming.upstream_sse.mode=internal_upstream_sse`，`request_fields=image_backend,streaming_strategy,partial_images`，`activation_strategies=openai-sse,newapi-keepalive-sse,responses-sse,force-sse`，`final_response_contract=AgentImageResponse`；`agent_streaming.page_sse.endpoint=/api/images`，`contract=page_ui_only`；`agent_jobs.mode=job_polling`。 |
+| `/api/agent/openapi.json` | 通过 | `GenerateRequest` 暴露 `image_backend`、`streaming_strategy`、`partial_images`；`image_backend.enum=images-api,responses-image-generation`；`streaming_strategy.enum=off,auto,openai-sse,newapi-keepalive-sse,responses-sse,force-sse`；`partial_images` 范围为 `1..3`；`AgentStreamingCapabilities.upstream_sse.final_response_contract` 只允许 `AgentImageResponse`。 |
+| `/api/runtime-capabilities` | 通过 | `responsesImageBackend.enabled=false`，`mode=experimental`；运行态流式批量能力未默认开启，当前服务端渠道健康容量为 `healthyCredentialCount=7`、`healthyChannelCount=7`。 |
+
+## 2026-05-22 推送后补充复验
+
+当前 HEAD 为 `6fa48f1 Fix agent route test error code typing`，已推送到 `origin/codex/image-upstream-compat`。PR #7 仍为 Draft/Open，`mergeStateStatus=CLEAN`。本轮只修改 `src/app/api/agent/agent-routes.test.ts` 的测试桩类型，把持久化失败用例中的错误码收敛为 `AgentErrorCode`，不改变业务运行代码。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `npm run verify -- --postgres` | 0 | `npm test`、`npm run lint`、`npm run lint:scripts`、`npm run build`、`npm run test:postgres`、`git diff --check`、`git diff --cached --check` 全部通过。 |
+| `NODE_ENV=test node --test --import tsx src/app/api/agent/agent-routes.test.ts` | 0 | 37 个 Agent route 测试通过；PostgreSQL 子套件因该定向命令未配置 `AGENT_POSTGRES_TEST_DATABASE_URL` 跳过，完整 Postgres gate 已由 `npm run verify -- --postgres` 覆盖。 |
+| `npx tsc --noEmit` | 0 | 修复后源码和测试 TypeScript 静态检查通过。 |
+| `npm run smoke:image-upstream-compat` | 0 | 原版 new-api Images JSON、sub2api Images JSON、gaoren keepalive SSE、gaoren JSON-as-SSE、sub2api Images SSE、sub2api Responses bridge、GPT2Image Responses SSE 七个本地 mock 兼容场景通过。 |
+| `npm audit --audit-level=high` | 0 | `found 0 vulnerabilities`。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel` | 0 | 非计费 dry-run 通过；5 个独立真实上游目标仍未配置，当前 `.env.local` 服务端渠道因缺少 `--allow-billable` 未触发生图。 |
+| `npm run smoke:image-upstream-real -- --require-independent-targets` | 1 | 按最终门禁预期失败；`final_gate_satisfied=false`、`missing_required_count=5`，缺少 `original-images-json`、`gaoren-images-sse`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`。 |
+| `npx next dev --turbopack -p 4786` + 浏览器复验 | 0 | `/api/agent/capabilities` 显示 Agent generate/edit 仍是 `non_streaming_only`，`upstream_sse.final_response_contract=AgentImageResponse`；高级参数显示 Images API / Responses image_generation 和 6 个流式策略；4K/high + auto 显示流式建议；keepalive-only SSE 期间 `document.images.length=0` 且只显示“连接保持中...”，关闭后显式报“API 响应中没有有效图片数据或文件名。”。 |
+| `.env.real-smoke.local` / `.env.real-smoke.example` | 不适用 | `.env.real-smoke.local` 当前不存在；模板 `.env.real-smoke.example` 只包含空占位符和默认 `IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4`，不能满足最终真实门禁。 |
+
+## 2026-05-22 status readiness 补充
+
+在 `be9e7cb Read real smoke env files in status` 基础上继续补充 `npm run status` 的 env 文件读取与 URL 安全校验。`status` 现在按 shell 环境变量、`.env.real-smoke.local`、`.env.local` 的优先级只读判断独立真实上游 smoke 配置是否齐全；输出只包含场景 ID、配置数量、缺失 env 键、非法 env 键与原因、最终门禁命令，不输出 URL 或 API Key。`scripts/command-center.test.mjs` 已覆盖 `.env.local` 与 `.env.real-smoke.local` 合并、shell env 优先、sub2api Responses 复用 sub2api 配置、unsafe `BASE_URL` 不泄露值，以及输出不包含 URL/key。
+
+在 `40d87f9 Harden image upstream status readiness` 基础上继续补充 `npm run smoke:image-upstream-real` 的结构化 readiness 失败报告。真实 smoke 脚本现在遇到 unsafe 独立上游 `BASE_URL` 时不再只把错误写到 stderr，而是在 JSON 报告中输出 `invalid_env`、`invalid_cases`、`invalid_required_cases`，同样只包含 env 键与 reason，不输出 URL 或 API Key。若已显式开启 `--allow-billable` 但任一选中目标存在 unsafe `BASE_URL`，脚本会在 readiness 阶段用顶层 `blocked_cases` 阻断其它已配置目标；最终门禁模式额外输出 `blocked_required_cases`，避免配置非法时产生部分真实上游调用。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `node --test scripts/command-center.test.mjs` | 0 | 22 个脚本测试通过。 |
+| `node --import tsx --test scripts/smoke-image-upstream-real.test.mjs` | 0 | 22 个真实 smoke 脚本测试通过，新增覆盖 unsafe 独立上游 `BASE_URL` 的结构化 JSON 报告、非法配置时阻断其它 billable 上游调用，以及普通 billable smoke 顶层 `blocked_cases` 汇总。 |
+| `npm run status` | 0 | `image_upstream_real_smoke.configuration_complete=false`、`configured_count=0`、`missing_count=5`，并列出 5 个独立真实上游目标缺失的 `BASE_URL` env。 |
+| unsafe `BASE_URL` status 探针 | 0 | 临时注入含凭据、查询参数和片段的 `IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL` 后，`status` 只输出 `IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL` 与 `must_not_include_credentials`，不输出 URL、查询 token 或 API Key。 |
+| unsafe `BASE_URL` real-smoke 探针 | 1 | 临时注入含凭据、查询参数和片段的 `IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL` 后，`smoke:image-upstream-real` 返回 JSON；`invalid_required_cases=original-images-json`。同时配置一个可 billable 的 gaoren 目标时，输出 `blocked_required_cases=gaoren-images-sse` 并在 1 秒内退出，证明未进入上游调用；不输出 URL、查询 token 或 API Key。 |
+| `npm run verify -- --postgres` | 0 | `npm test`、lint、script lint、build、live PostgreSQL gate、diff checks 全部通过。 |
+| `npm run smoke:image-upstream-compat` | 0 | 7 个本地 mock 兼容场景通过。 |
+| `npx tsc --noEmit` | 0 | TypeScript 静态检查通过。 |
+| `npm run smoke:image-upstream-real -- --require-independent-targets` | 1 | 按最终门禁预期失败；仍缺 5 个独立真实上游目标，`final_gate_satisfied=false`。 |
+
+## 2026-05-22 final gate preflight 补充
+
+本轮基线基于 `fc55a26 Block incomplete real smoke final gate`，该提交已推送到 `origin/codex/image-upstream-compat`。本轮补齐 `--require-independent-targets --allow-billable` 的 readiness 安全边界：若最终独立真实上游门禁发现必跑场景未选全、缺少配置或配置非法，脚本会在加载 `/api/images` / `/api/agent/images/generate` route 之前阻断已配置的可运行目标，先输出结构化失败，不发任何真实上游计费请求。该边界避免“最终门禁必然失败但已产生部分真实计费请求”的状态。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `npm run smoke:image-upstream-compat` | 0 | 原版 new-api Images JSON、sub2api Images JSON、gaoren keepalive SSE、gaoren JSON-as-SSE、sub2api Images SSE、sub2api Responses bridge、GPT2Image Responses SSE 七个本地 mock 兼容场景通过。 |
+| `node --import tsx --test scripts/smoke-image-upstream-real.test.mjs` | 0 | 23 个真实 smoke 脚本测试通过。新增覆盖最终独立门禁只配置一个目标但缺少其它必跑目标时，已配置目标被列入 `blocked_required_cases`，本地 mock 上游 `calls.length=0`。 |
+| `IMAGE_REAL_SMOKE_SKIP_DOTENV=1 npm run smoke:image-upstream-real -- --require-independent-targets --allow-billable` | 1 | 预期失败；`configuration_complete=false`、`configured_count=0`、`missing_count=5`、`missing_required_count=5`。命令虽然带 `--allow-billable`，但由于独立目标配置不完整，仅输出缺失项报告，不进入上游调用路径。 |
+
+## 2026-05-22 Responses readiness 模型口径补充
+
+本轮继续修正真实 smoke readiness 对 Responses 顶层模型的判断：`IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL` 是 sub2api Responses 场景的图片模型覆盖项，不能被当成 `/responses` 顶层模型。`npm run status` 与 `npm run smoke:image-upstream-real` 现在只接受 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL` 作为 sub2api Responses 顶层模型；GPT2Image 场景仍接受 `IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL` 或 `OPENAI_RESPONSES_API_MODEL`。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `node --test scripts/command-center.test.mjs` | 0 | 新增覆盖 `IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL=gpt-image-2` 不会让 status readiness 误判 sub2api Responses 场景配置完成。 |
+| `node --import tsx --test scripts/smoke-image-upstream-real.test.mjs` | 0 | 新增覆盖真实 smoke dry-run 同样不会把 sub2api Responses 图片模型变量当成 `/responses` 顶层模型。 |
+| `npm run status` | 0 | 当前本轮工作树有未提交改动，`head=5c6e21b`；独立真实上游仍为 `configured_count=0`、`missing_count=5`，最终门禁命令仍指向 `--env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable`。 |
+
+## 2026-05-22 GPT2Image Responses SSE 去重补充
+
+本轮兼容 mock smoke 暴露 GPT2Image 风格 Responses SSE 会先返回 `response.output_item.done`，再在 `response.completed.response.output[]` 中重复同一个无 id 的 `image_generation_call.result`。事件归一化现在在 Responses image call 缺少 `id` / `item_id` / `call_id` 时，使用最终 base64 payload 作为内部 dedupe key；如果上游提供不同 id，即使 payload 相同仍会保留为不同最终图片。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `node --test --import tsx src/lib/image-stream-collector.test.ts` | 0 | 新增覆盖 Responses 上游缺少 image call id 时，`response.output_item.done` 与 `response.completed` 的同 payload final image 只落一张。 |
+| `npm run smoke:image-upstream-compat` | 0 | GPT2Image Responses SSE 场景恢复为 `partial_image, completed, done`，不再出现重复 `completed`。 |
+
+## 2026-05-22 fcdd698 基线复验
+
+复验基线为 `fcdd698 Fix Responses upstream smoke readiness`，分支 `codex/image-upstream-compat` 已同步到 `origin/codex/image-upstream-compat`。本小节为后续追加的文档记录，不改变业务代码。PR #7 仍为 Draft/Open，`mergeStateStatus=CLEAN`，当前 GitGuardian Security Checks 通过。
+
+| 命令或检查 | 退出码 | 摘要 |
+| --- | --- | --- |
+| `npm run status` | 0 | 当前仅有本审计文档改动；独立真实上游 readiness 为 `configured_count=0`、`missing_count=5`，缺少 `original-images-json`、`gaoren-images-sse`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`。 |
+| `npm run smoke:image-upstream-compat` | 0 | 7 个本地 mock 兼容场景通过：original Images JSON、sub2api Images JSON、gaoren keepalive SSE、gaoren JSON-as-SSE、sub2api Images SSE、sub2api Responses bridge、GPT2Image Responses SSE。 |
+| `npm run smoke:image-upstream-real -- --include-server-channel` | 0 | 非计费 dry-run 通过；5 个独立真实上游目标仍因缺少专用 `IMAGE_REAL_SMOKE_*_BASE_URL` 跳过，当前服务端渠道未触发真实生图。 |
+| `IMAGE_REAL_SMOKE_SKIP_DOTENV=1 npm run smoke:image-upstream-real -- --require-independent-targets --allow-billable` | 1 | 预期失败；`configuration_complete=false`、`configured_count=0`、`missing_required_count=5`。配置不完整时先输出缺失报告，不进入上游调用路径。 |
+| `npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable` | 1 | 最终独立真实上游门禁仍失败；`.env.real-smoke.local` 当前不存在，5 个必跑目标全部列入 `skipped_required_cases`。 |
+| `npm run verify` | 0 | `npm test`、`npm run lint`、`npm run lint:scripts`、`npm run build`、`git diff --check`、`git diff --cached --check` 全部通过。 |
+| `find generated-images/.real-smoke ...` | 0 | 当前没有 `png`、`jpg`、`jpeg`、`webp` 真实 smoke 产物残留。 |
+
+本轮没有追加 `--allow-billable` 的真实生图请求。最终完成判定仍缺独立真实上游凭据和地址，需要配置 `.env.real-smoke.local` 后跑通最终门禁命令。
+
+## 完成度审计矩阵
+
+| 要求 | 当前证据 | 状态 |
+| --- | --- | --- |
+| 默认配置不破坏 OpenAI Images API、原版 new-api 和 sub2api 普通 JSON 基线 | `src/app/api/images/route.test.ts`、`npm run smoke:image-upstream-compat` 的 original new-api Images API JSON 与 sub2api Images API JSON 场景、`server-channel-images-json` 真实复测 | 已覆盖 |
+| 流式能力只通过配置、UI 开关、Agent 显式策略或探测确认启用 | `src/lib/image-upstream-strategy.ts`、`src/lib/image-upstream-strategy.test.ts`、浏览器 UI smoke 默认未勾选流式、Agent defaults 为 `streaming_strategy=off` | 已覆盖 |
+| gaoren/new-api keepalive SSE 和 JSON-as-SSE 能归一化，keepalive 不产生假预览 | `npm run smoke:image-upstream-compat` 的 gaoren keepalive 与 JSON-as-SSE 场景、`src/lib/image-stream-events.test.ts` keepalive/非对象忽略、浏览器 keepalive stub | 已覆盖，真实独立 gaoren 地址缺失 |
+| sub2api Images SSE 与 Responses bridge 能归一化 | `npm run smoke:image-upstream-compat` 的 sub2api Images SSE 和 sub2api Responses bridge JSON 场景、`src/lib/image-stream-events.test.ts` Responses partial/output/completed 覆盖 | 已覆盖，真实独立 sub2api 地址缺失 |
+| GPT2Image 风格 `/v1/responses` + `image_generation` 工具流式结果可兼容 | `src/lib/responses-image-backend.test.ts`、`npm run smoke:image-upstream-compat` 的 GPT2Image Responses SSE 场景、`server-channel-responses-sse` 真实复验 | 已覆盖，真实独立 GPT2Image 地址缺失 |
+| partial image 只能作为进度预览，最终必须等待 completed base64 | `src/lib/image-stream-service.ts`、`src/lib/image-stream-collector.ts`、`src/app/api/agent/agent-routes.test.ts` partial-only 失败用例 | 已覆盖 |
+| 缺 final base64、远程 URL-only、上游断流、Responses failed image call 必须显式失败 | `src/lib/image-stream-events.test.ts`、`src/lib/responses-image-backend.test.ts`、`src/app/api/images/route.test.ts` 的非流式 Images URL-only 502、Responses JSON/SSE failed image call 用例、`src/app/api/agent/agent-routes.test.ts` 的 Agent upstream SSE failed image call 用例、`server-channel-images-json` 首次真实 `Connection error` 显式失败记录 | 已覆盖 |
+| Agent API 对外保持最终 JSON，内部可消费上游 SSE 并保存 artifact | `src/app/api/agent/agent-routes.test.ts` 的直接 generate Images SSE、直接 generate Responses SSE、job polling Images SSE + artifact content、job polling Responses SSE + artifact content 用例，以及 `server-channel-agent-images-sse` 与 `server-channel-agent-responses-sse` 脚本化真实 smoke | 已覆盖 |
+| capabilities/OpenAPI/skill 文档清楚区分页面 SSE、Agent 内部 upstream SSE 和最终响应契约 | `src/lib/agent-api-contracts.test.ts`、`src/lib/agent-openapi.ts`、`skills/gpt-image-playground-agent/SKILL.md`、`skills/gpt-image-playground-agent/references/api.md`、运行态 `GET /api/agent/capabilities` 和 `GET /api/agent/openapi.json` smoke | 已覆盖 |
+| 三类独立上游真实 smoke：原版 new-api、gaoren/new-api、sub2api/GPT2Image | `scripts/smoke-image-upstream-real.mjs` 已支持独立 `IMAGE_REAL_SMOKE_*` 目标和 `--env-file <path>`；当前 dry-run 证明本机未配置专用 `BASE_URL`，`independent_targets` 汇总缺失目标并给出最终门禁命令，`missing_env_any` 指出缺失 env；`--require-independent-targets --allow-billable` 在配置不完整时会先失败并阻断部分真实调用；配置齐全后才允许最终门禁实际计费执行 | 未完成，缺少独立真实上游地址和 key |
+
+## 结论
+
+- 当前实现保持默认 Images API JSON 基线，不会自动按仓库名启用流式能力。
+- 页面默认不发送 `stream=true`；用户显式开启流式后，在没有 partial image 前只显示连接保持状态，不把 keepalive 当成预览或成功。
+- 当前真实上游证明 Images JSON、Images SSE、Responses SSE、Agent 内部上游 SSE 可通过本项目稳定契约落到最终产物。
+- 当前真实上游的 Responses 非流式路径未返回符合契约的 `image_generation_call.result`，本项目按设计显式失败。
+- 因本机没有独立原版 new-api、gaoren new-api、sub2api 和 GPT2Image 地址，无法把这四类实现分别做真实 smoke；对应兼容行为以本地 mock 契约测试作为当前证据。

package.json

@@ -10,11 +10,19 @@
     "test": "node --test --import tsx \"src/**/*.test.ts\" \"scripts/**/*.test.mjs\"",
     "test:scripts": "node --test \"scripts/**/*.test.mjs\"",
     "test:postgres": "node scripts/test-postgres-live.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "status": "node scripts/status.mjs",
+    "verify": "node scripts/verify.mjs",
+    "deploy:local": "node scripts/deploy-local.mjs",
+    "deploy:space": "npm run deploy:hf-space",
+    "agent:doctor": "node scripts/agent-doctor.mjs",
+    "deploy:hf-space": "node scripts/deploy-hf-space.mjs",
     "doctor:hf-space": "node scripts/doctor-hf-space.mjs",
-    "init-access:hf-space": "node scripts/init-hf-space-access.mjs",
     "keepalive:hf-space": "node scripts/keepalive-hf-space.mjs",
-    "sync-secret:hf-space": "node scripts/sync-hf-space-secret.mjs",
     "smoke:hf-space": "node scripts/smoke-hf-space-memory.mjs",
+    "smoke:image-upstream-compat": "node --import tsx scripts/smoke-image-upstream-compat.mjs",
+    "smoke:image-upstream-local": "node scripts/smoke-image-upstream-local-final-gate.mjs",
+    "smoke:image-upstream-real": "node --import tsx -- scripts/smoke-image-upstream-real.mjs",
     "start": "node scripts/start-standalone.mjs",
     "lint": "eslint src",
     "lint:scripts": "node scripts/check-node-syntax.mjs",

scripts/agent-doctor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule, parseJsonPayload, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
+
+const GENERATE_SCRIPT = fileURLToPath(new URL('../skills/gpt-image-playground-agent/scripts/generate-image.mjs', import.meta.url));
+const AGENT_DOCTOR_TIMEOUT_MS = 75_000;
+
+export function buildAgentDoctorArgs() {
+    return [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000', 'contract check'];
+}
+
+function parseArgs(argv) {
+    const unknown = argv.find((arg) => !['--help', '-h'].includes(arg));
+    if (unknown) throw new Error(`Unknown option: ${unknown}`);
+    return {
+        help: argv.includes('--help') || argv.includes('-h')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run agent:doctor
+
+Environment:
+  GPT_IMAGE_PLAYGROUND_URL       Service base URL, defaults to http://localhost:4783.
+  GPT_IMAGE_AGENT_TOKEN          Bearer token when capabilities require bearer auth.
+  GPT_IMAGE_APP_PASSWORD_HASH    Password hash when capabilities require page password auth.`);
+}
+
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+
+    const result = runCommand(process.execPath, buildAgentDoctorArgs(), {
+        env: { ...process.env, GPT_IMAGE_AGENT_CONTRACT_CHECK: '1' },
+        timeoutMs: AGENT_DOCTOR_TIMEOUT_MS
+    });
+    if (!result.ok) {
+        printJson({ ok: false, command: 'agent:doctor', output: pickFailureOutput(result) });
+        process.exit(1);
+    }
+
+    const body = result.stdout ? parseJsonPayload(result.stdout, 'agent contract check') : {};
+    printJson({ ok: true, command: 'agent:doctor', contract: body });
+}
+
+try {
+    if (isMainModule(import.meta.url, process.argv[1])) main();
+} catch (error) {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+}

scripts/agent-skill-scripts.test.mjs

@@ -76,6 +76,1026 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stderr.trim(), '');
     });
 
+    it('includes explicit upstream streaming options in generate dry-run requests', () => {
+        const result = runSkillScript('generate-image.mjs', [
+            '--image-backend',
+            'responses',
+            '--streaming-strategy',
+            'responses-sse',
+            '--partial-images',
+            '3',
+            'prompt'
+        ]);
+
+        assert.equal(result.status, 0);
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.request.image_backend, 'responses');
+        assert.equal(body.request.streaming_strategy, 'responses-sse');
+        assert.equal(body.request.partial_images, 3);
+        assert.equal(result.stderr.trim(), '');
+    });
+
+    it('prints page SSE routing guidance for high-resolution generate dry-runs', () => {
+        const result = runSkillScript('generate-image.mjs', ['--size', '3072x2048', '--quality', 'high', 'prompt']);
+
+        assert.equal(result.status, 0);
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.endpoint, 'http://localhost:4783/api/images');
+        assert.equal(body.routing_guidance.recommended_endpoint, '/api/images');
+        assert.equal(body.routing_guidance.transport, 'page_sse');
+        assert.equal(body.routing_guidance.fallback_endpoint, '/api/agent/images/generate');
+        assert.equal(body.routing_guidance.fallback_mode, 'manual_after_diagnosis');
+        assert.equal(body.routing_guidance.reason.includes('max_edge>2048'), true);
+        assert.equal(result.stderr.trim(), '');
+    });
+
+    it('does not automatically fall back after a billable page SSE generate failure', 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({
+                            agent_streaming: {
+                                page_sse: { supported: true, endpoint: '/api/images' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end('data: {"type":"error","error":"stream failed","status":502}\n\n');
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected fallback' }));
+                    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', '--size', '3072x2048', '--quality', 'high', '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.error.code, 'page_sse_failed');
+                assert.match(body.error.message, /stream failed/);
+                assert.equal(body.routing.fallback_endpoint, '/api/agent/images/generate');
+                assert.equal(body.routing.fallback_mode, 'manual_after_diagnosis');
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    ['GET /api/agent/capabilities', 'POST /api/images']
+                );
+            }
+        );
+    });
+
+    it('reports non-SSE page validation failures as non-billable', 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({
+                            agent_streaming: {
+                                page_sse: { supported: true, endpoint: '/api/images' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(400, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'size 对 gpt-image-2 无效：宽高必须是 16 的倍数。' }));
+                    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', '--size', '2049x2048', '--quality', 'high', '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.billable, false);
+                assert.equal(body.error.code, 'page_sse_request_rejected');
+                assert.equal(body.error.status, 400);
+                assert.match(body.error.message, /16 的倍数/);
+                assert.equal(body.routing.fallback_mode, 'fix_request_before_retry');
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    ['GET /api/agent/capabilities', 'POST /api/images']
+                );
+            }
+        );
+    });
+
+    it('reports non-JSON page 4xx failures as non-billable request rejections', async () => {
+        await withServer(
+            (request, response) => {
+                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' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(401, { 'content-type': 'text/plain' });
+                    response.end('missing passwordHash');
+                    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', '--size', '3072x2048', '--quality', 'high', '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.billable, false);
+                assert.equal(body.error.code, 'page_sse_request_rejected');
+                assert.equal(body.error.status, 401);
+                assert.match(body.error.message, /missing passwordHash/);
+                assert.equal(body.routing.fallback_mode, 'fix_request_before_retry');
+            }
+        );
+    });
+
+    it('reports non-SSE page server failures as billable page SSE failures', async () => {
+        await withServer(
+            (request, response) => {
+                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' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: { message: 'upstream page 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', '--size', '3072x2048', '--quality', 'high', '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.billable, true);
+                assert.equal(body.error.code, 'page_sse_failed');
+                assert.equal(body.error.status, 500);
+                assert.match(body.error.message, /upstream page failed/);
+                assert.equal(body.routing.fallback_mode, 'manual_after_diagnosis');
+            }
+        );
+    });
+
+    it('preserves object page SSE error messages', async () => {
+        await withServer(
+            (request, response) => {
+                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' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"error","error":{"message":"bad request from page","code":"validation_error","status":400}}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', '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.error.code, 'page_sse_failed');
+                assert.equal(body.billable, true);
+                assert.equal(body.error.status, 400);
+                assert.match(body.error.message, /bad request from page/);
+                assert.doesNotMatch(body.error.message, /\[object Object\]/);
+            }
+        );
+    });
+
+    it('fails large generate auto routing when page SSE capability is unavailable', 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({ agent_streaming: {}, agent_jobs: { supported: true, mode: 'job_polling' } }));
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected fallback' }));
+                    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', '--size', '3072x2048', '--quality', 'high', '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.error.code, 'page_sse_unavailable');
+                assert.equal(body.routing.fallback_mode, 'manual_after_diagnosis');
+                assert.deepEqual(requests.map((item) => `${item.method} ${item.url}`), ['GET /api/agent/capabilities']);
+            }
+        );
+    });
+
+    it('fails page SSE output when the stream ends before the done event', async () => {
+        await withServer(
+            (request, response) => {
+                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' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"final-base64","path":"/api/image/image.png","output_format":"png"}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', '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.error.code, 'page_sse_failed');
+                assert.match(body.error.message, /缺少最终 done 事件/);
+            }
+        );
+    });
+
+    it('requires page access hash before calling page SSE when capabilities declare page auth', 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({
+                            agent_streaming: {
+                                page_sse: {
+                                    supported: true,
+                                    endpoint: '/api/images',
+                                    auth: { required: true, schemes: ['form-password-hash'], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected page call' }));
+                    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', '--size', '3072x2048', '--quality', 'high', '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.error.code, 'page_sse_auth_required');
+                assert.match(body.error.message, /GPT_IMAGE_APP_PASSWORD_HASH/);
+                assert.deepEqual(requests.map((item) => `${item.method} ${item.url}`), ['GET /api/agent/capabilities']);
+            }
+        );
+    });
+
+    it('rejects overlong page SSE client request ids before sending the stream request', 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({
+                            agent_streaming: {
+                                page_sse: {
+                                    supported: true,
+                                    endpoint: '/api/images',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected page call' }));
+                    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',
+                        '--page-sse',
+                        '--size',
+                        '3072x2048',
+                        '--quality',
+                        'high',
+                        'prompt'
+                    ],
+                    {
+                        GPT_IMAGE_PLAYGROUND_URL: baseUrl,
+                        GPT_IMAGE_AGENT_IDEMPOTENCY_KEY: 'x'.repeat(129)
+                    }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.error.code, 'page_sse_client_request_id_too_long');
+                assert.match(body.error.message, /不能超过 128 个字符/);
+                assert.deepEqual(requests.map((item) => `${item.method} ${item.url}`), ['GET /api/agent/capabilities']);
+            }
+        );
+    });
+
+    it('strips page SSE base64 from default path-mode output', async () => {
+        await withServer(
+            (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"final-base64","path":"/api/image/image.png","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-1","images":[{"filename":"image.png"}]}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.images[0].filename, 'image.png');
+                assert.equal('b64_json' in body.images[0], false);
+                assert.equal(body.images[0].path, '/api/image/image.png');
+                assert.equal(body.images[0].absolute_path, `${baseUrl}/api/image/image.png`);
+                assert.equal(body.images[0].output_format, 'png');
+                assert.equal(body.images[0].clientRequestId, 'page-request-1');
+            }
+        );
+    });
+
+    it('passes response mode through to page SSE form-data requests', async () => {
+        let pageRequestBody = '';
+        await withServer(
+            async (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    pageRequestBody = await readRequestText(request);
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"final-base64","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-response-mode"}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', '--response-mode', 'base64', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                assert.match(pageRequestBody, /name="response_mode"\r?\n\r?\nbase64/);
+            }
+        );
+    });
+
+    it('omits page SSE streaming strategy unless explicitly requested', async () => {
+        let pageRequestBody = '';
+        await withServer(
+            async (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    pageRequestBody = await readRequestText(request);
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"final-base64","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-default-streaming"}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--page-sse', '--size', '1024x1024', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                assert.match(pageRequestBody, /name="stream"\r?\n\r?\ntrue/);
+                assert.doesNotMatch(pageRequestBody, /name="image_streaming_strategy"/);
+            }
+        );
+    });
+
+    it('enforces timeout while waiting for page SSE body events', async () => {
+        await withServer(
+            (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.write(': keepalive\n\n');
+                    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', '--page-sse', '--timeout-ms', '250', '--size', '1024x1024', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl },
+                    { timeoutMs: 1_200 }
+                );
+
+                assert.equal(result.timedOut, false);
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const body = JSON.parse(result.stderr);
+                assert.equal(body.error.code, 'page_sse_failed');
+                assert.match(body.error.message, /\/api\/images/);
+            }
+        );
+    });
+
+    it('passes page access hash through to page SSE form-data requests when configured', async () => {
+        let pageRequestBody = '';
+        await withServer(
+            async (request, response) => {
+                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',
+                                    auth: { required: true, schemes: ['form-password-hash'], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    pageRequestBody = await readRequestText(request);
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"final-base64","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-password"}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', 'prompt'],
+                    {
+                        GPT_IMAGE_PLAYGROUND_URL: baseUrl,
+                        GPT_IMAGE_APP_PASSWORD_HASH: 'hash-for-page-sse'
+                    }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                assert.match(pageRequestBody, /name="passwordHash"\r?\n\r?\nhash-for-page-sse/);
+            }
+        );
+    });
+
+    it('keeps page SSE base64 in default path-mode output when no path is returned', async () => {
+        await withServer(
+            (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image.png","b64_json":"indexeddb-base64","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-indexeddb"}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.images[0].filename, 'image.png');
+                assert.equal(body.images[0].b64_json, 'indexeddb-base64');
+                assert.equal('absolute_path' in body.images[0], false);
+                assert.equal(body.images[0].clientRequestId, 'page-request-indexeddb');
+            }
+        );
+    });
+
+    it('preserves completed page SSE images when the done event lists fewer images', async () => {
+        await withServer(
+            (request, response) => {
+                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',
+                                    auth: { required: false, schemes: [], form_field: 'passwordHash' }
+                                }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"image-a.png","b64_json":"base64-a","path":"/api/image/image-a.png","output_format":"png"}',
+                            '',
+                            'data: {"type":"completed","filename":"image-b.png","b64_json":"base64-b","path":"/api/image/image-b.png","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"page-request-2","images":[{"filename":"image-a.png"}]}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    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', '--size', '3072x2048', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.images.length, 2);
+                assert.equal(body.images[0].filename, 'image-a.png');
+                assert.equal(body.images[1].filename, 'image-b.png');
+                assert.equal(body.images[1].path, '/api/image/image-b.png');
+                assert.equal(body.images[1].absolute_path, `${baseUrl}/api/image/image-b.png`);
+                assert.equal(body.images[1].clientRequestId, 'page-request-2');
+            }
+        );
+    });
+
+    it('uses Agent JSON for billable large generate requests when --agent is explicit', 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({
+                            agent_streaming: {
+                                page_sse: { supported: true, endpoint: '/api/images' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            images: [
+                                {
+                                    filename: 'agent.png',
+                                    content_url: '/api/agent/artifacts/artifact-1/content',
+                                    metadata_url: '/api/agent/artifacts/artifact-1'
+                                }
+                            ]
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected page SSE call' }));
+                    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', '--agent', '--size', '3072x2048', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.images[0].filename, 'agent.png');
+                assert.equal(body.images[0].absolute_content_url, `${baseUrl}/api/agent/artifacts/artifact-1/content`);
+                assert.deepEqual(body.routing, { transport: 'agent_json', endpoint: '/api/agent/images/generate' });
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    ['GET /api/agent/capabilities', 'POST /api/agent/images/generate']
+                );
+            }
+        );
+    });
+
+    it('uses page SSE for billable small generate requests when --page-sse is explicit', 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({
+                            agent_streaming: {
+                                page_sse: { supported: true, endpoint: '/api/images' }
+                            },
+                            agent_jobs: { supported: true, mode: 'job_polling' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/images') {
+                    response.writeHead(200, { 'content-type': 'text/event-stream' });
+                    response.end(
+                        [
+                            'data: {"type":"completed","filename":"small-page.png","path":"/api/image/small-page.png","output_format":"png"}',
+                            '',
+                            'data: {"type":"done","client_request_id":"small-page-request","images":[{"filename":"small-page.png"}]}',
+                            '',
+                            ''
+                        ].join('\n')
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    response.writeHead(500, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unexpected Agent JSON call' }));
+                    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', '--page-sse', '--size', '1024x1024', '--quality', 'high', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.images[0].filename, 'small-page.png');
+                assert.equal(body.images[0].absolute_path, `${baseUrl}/api/image/small-page.png`);
+                assert.deepEqual(body.routing, { transport: 'page_sse', endpoint: '/api/images' });
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    ['GET /api/agent/capabilities', 'POST /api/images']
+                );
+            }
+        );
+    });
+
+    it('prints page SSE guidance for high-resolution edit dry-runs', () => {
+        const result = runSkillScript('edit-image.mjs', [
+            '--size',
+            '3072x2048',
+            '--quality',
+            'high',
+            '/tmp/source.png',
+            'prompt'
+        ]);
+
+        assert.equal(result.status, 0);
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.routing_guidance.recommended_endpoint, '/api/images');
+        assert.equal(body.routing_guidance.transport, 'page_sse');
+        assert.equal(body.routing_guidance.strength, 'must_use');
+        assert.equal(result.stderr.trim(), '');
+    });
+
+    it('blocks billable high-resolution Agent edit requests before reading image files', () => {
+        const result = runSkillScript('edit-image.mjs', [
+            '--allow-billable',
+            '--size',
+            '3072x2048',
+            '/tmp/missing-source.png',
+            'prompt'
+        ]);
+
+        assert.equal(result.status, 2);
+        const body = JSON.parse(result.stderr);
+        assert.equal(body.billable, false);
+        assert.equal(body.routing_guidance.recommended_endpoint, '/api/images');
+        assert.equal(body.routing_guidance.strength, 'must_use');
+        assert.equal(result.stdout.trim(), '');
+    });
+
+    it('rejects invalid generate upstream streaming options before dry-run output', () => {
+        const invalidPartialImages = runSkillScript('generate-image.mjs', ['--partial-images', '4', 'prompt']);
+        assert.equal(invalidPartialImages.status, 2);
+        assert.match(invalidPartialImages.stderr, /--partial-images 必须是 1 到 3 的整数/);
+        assert.equal(invalidPartialImages.stdout.trim(), '');
+
+        const invalidBackend = runSkillScript('generate-image.mjs', ['--image-backend', 'unknown-backend', 'prompt']);
+        assert.equal(invalidBackend.status, 2);
+        assert.match(invalidBackend.stderr, /--image-backend 必须是/);
+        assert.equal(invalidBackend.stdout.trim(), '');
+
+        const invalidStrategy = runSkillScript('generate-image.mjs', [
+            '--streaming-strategy',
+            'unknown-strategy',
+            'prompt'
+        ]);
+        assert.equal(invalidStrategy.status, 2);
+        assert.match(invalidStrategy.stderr, /--streaming-strategy 必须是/);
+        assert.equal(invalidStrategy.stdout.trim(), '');
+
+        const invalidResponseMode = runSkillScript('generate-image.mjs', ['--response-mode', 'url', 'prompt']);
+        assert.equal(invalidResponseMode.status, 2);
+        assert.match(invalidResponseMode.stderr, /--response-mode 必须是 path、base64 或 both/);
+        assert.equal(invalidResponseMode.stdout.trim(), '');
+
+        const disabledAutoPageSse = runSkillScript('generate-image.mjs', [
+            '--size',
+            '3072x2048',
+            '--streaming-strategy',
+            'off',
+            'prompt'
+        ]);
+        assert.equal(disabledAutoPageSse.status, 0);
+        const disabledAutoPageSseBody = JSON.parse(disabledAutoPageSse.stdout);
+        assert.equal(disabledAutoPageSseBody.endpoint, 'http://localhost:4783/api/agent/images/generate');
+        assert.equal(disabledAutoPageSseBody.routing_guidance.recommended_endpoint, '/api/agent/images/generate');
+        assert.equal(disabledAutoPageSse.stderr.trim(), '');
+
+        const disabledPageSse = runSkillScript('generate-image.mjs', [
+            '--page-sse',
+            '--streaming-strategy',
+            'off',
+            'prompt'
+        ]);
+        assert.equal(disabledPageSse.status, 2);
+        assert.match(disabledPageSse.stderr, /streaming_strategy=off/);
+        assert.doesNotMatch(disabledPageSse.stderr, /ModuleJob|at buildGenerateRoutingGuidance/);
+        assert.equal(disabledPageSse.stdout.trim(), '');
+    });
+
     it('shows edit help without validating unrelated env values', () => {
         const result = runSkillScript('edit-image.mjs', ['--help'], {
             GPT_IMAGE_AGENT_MAX_ATTEMPTS: 'abc'
@@ -138,6 +1158,31 @@ describe('Agent skill script argument validation', () => {
             }
         );
     });
+
+    it('does not duplicate network failure prefixes in generate capability errors', async () => {
+        await withServer(
+            (request, response) => {
+                if (request.url === '/api/agent/capabilities') {
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'text/plain' });
+                response.end('missing');
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--allow-billable', '--timeout-ms', '50', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 1);
+                assert.equal(result.stdout.trim(), '');
+                const prefixes = result.stderr.match(/请求失败：/g) || [];
+                assert.equal(prefixes.length, 1);
+                assert.match(result.stderr, /\/api\/agent\/capabilities/);
+            }
+        );
+    });
 });
 
 function runSkillScript(filename, args, env = {}) {
@@ -148,7 +1193,7 @@ function runSkillScript(filename, args, env = {}) {
     });
 }
 
-function runSkillScriptAsync(filename, args, env = {}) {
+function runSkillScriptAsync(filename, args, env = {}, options = {}) {
     return new Promise((resolve) => {
         const child = spawn(process.execPath, [join(skillScriptsRoot, filename), ...args], {
             cwd: repoRoot,
@@ -157,6 +1202,13 @@ function runSkillScriptAsync(filename, args, env = {}) {
         });
         let stdout = '';
         let stderr = '';
+        let timedOut = false;
+        const timeout = options.timeoutMs
+            ? setTimeout(() => {
+                  timedOut = true;
+                  child.kill('SIGTERM');
+              }, options.timeoutMs)
+            : undefined;
         child.stdout.setEncoding('utf8');
         child.stderr.setEncoding('utf8');
         child.stdout.on('data', (chunk) => {
@@ -165,8 +1217,9 @@ function runSkillScriptAsync(filename, args, env = {}) {
         child.stderr.on('data', (chunk) => {
             stderr += chunk;
         });
-        child.on('close', (status) => {
-            resolve({ status, stdout, stderr });
+        child.on('close', (status, signal) => {
+            if (timeout) clearTimeout(timeout);
+            resolve({ status, signal, stdout, stderr, timedOut });
         });
     });
 }
@@ -183,3 +1236,17 @@ async function withServer(handler, run) {
         await new Promise((resolve) => server.close(resolve));
     }
 }
+
+function readRequestText(request) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        request.setEncoding('utf8');
+        request.on('data', (chunk) => {
+            body += chunk;
+        });
+        request.on('end', () => {
+            resolve(body);
+        });
+        request.on('error', reject);
+    });
+}

scripts/command-center-utils.mjs

@@ -0,0 +1,132 @@
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_MAX_BUFFER = 20 * 1024 * 1024;
+const DEFAULT_FETCH_TIMEOUT_MS = 5000;
+
+export function isMainModule(moduleUrl, argvPath) {
+    return Boolean(argvPath) && moduleUrl === pathToFileURL(resolve(argvPath)).href;
+}
+
+export function runCommand(command, args = [], options = {}) {
+    const startedAt = Date.now();
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: options.encoding || 'utf8',
+        env: options.env,
+        input: options.input,
+        maxBuffer: options.maxBuffer || DEFAULT_MAX_BUFFER,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: options.timeoutMs
+    });
+    const elapsedMs = Date.now() - startedAt;
+    if (result.error) {
+        return {
+            ok: false,
+            command,
+            args,
+            status: result.status,
+            stdout: String(result.stdout || ''),
+            stderr: String(result.stderr || ''),
+            elapsed_ms: elapsedMs,
+            error: result.error.message,
+            signal: result.signal
+        };
+    }
+    return {
+        ok: result.status === 0,
+        command,
+        args,
+        status: result.status,
+        stdout: String(result.stdout || ''),
+        stderr: String(result.stderr || ''),
+        elapsed_ms: elapsedMs,
+        signal: result.signal
+    };
+}
+
+export function runCommandStrict(command, args = [], options = {}) {
+    const result = runCommand(command, args, options);
+    if (!result.ok) throw new Error(commandFailureMessage(result));
+    return result.stdout;
+}
+
+export function commandFailureMessage(result) {
+    return pickFailureOutput(result) || `${result.command} ${result.args.join(' ')} failed`;
+}
+
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+
+export function parseJsonPayload(output, label = 'command') {
+    const lines = output.split(/\r?\n/);
+    let lastError;
+    let sawCandidate = false;
+    for (let start = 0; start < lines.length; start += 1) {
+        const trimmed = lines[start].trimStart();
+        if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) continue;
+        sawCandidate = true;
+        for (let end = lines.length; end > start; end -= 1) {
+            try {
+                return JSON.parse(lines.slice(start, end).join('\n'));
+            } catch (error) {
+                lastError = error;
+            }
+        }
+    }
+    if (!sawCandidate) throw new Error(`${label} did not return JSON output.`);
+    throw new Error(`${label} returned invalid JSON: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+
+export async function fetchJsonWithTimeout(url, options = {}) {
+    const timeoutMs = options.timeoutMs || DEFAULT_FETCH_TIMEOUT_MS;
+    const pathname = safeUrlPathname(url);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        const text = await response.text();
+        const bodySnippet = formatResponseBodySnippet(text);
+        if (!response.ok) throw new Error(`${pathname} failed with HTTP ${response.status}${bodySnippet}`);
+        try {
+            return JSON.parse(text);
+        } catch (error) {
+            if (error instanceof SyntaxError) throw new Error(`${pathname} did not return JSON${bodySnippet}`);
+            throw error;
+        }
+    } catch (error) {
+        if (error?.name === 'AbortError') throw new Error(`${pathname} timed out after ${timeoutMs}ms.`);
+        throw error;
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+function formatResponseBodySnippet(text) {
+    if (!text || process.env.NODE_ENV === 'production') return '';
+    return `: ${text.slice(0, 100)}`;
+}
+
+function safeUrlPathname(url) {
+    try {
+        return new URL(url).pathname;
+    } catch {
+        return String(url);
+    }
+}
+
+export function pickFailureOutput(result, maxLength = 4000) {
+    const output = [
+        result.stdout,
+        result.stderr,
+        result.status !== undefined && result.status !== null ? `status: ${result.status}` : '',
+        result.error ? `error: ${result.error}` : '',
+        result.signal ? `signal: ${result.signal}` : ''
+    ]
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+    return output.length > maxLength ? `${output.slice(0, maxLength)}...` : output;
+}

scripts/command-center.test.mjs

@@ -0,0 +1,429 @@
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { buildAgentDoctorArgs } from './agent-doctor.mjs';
+import { fetchJsonWithTimeout, parseJsonPayload, pickFailureOutput, runCommand } from './command-center-utils.mjs';
+import {
+    buildAdminCommands,
+    buildImageUpstreamRealSmokeStatus,
+    parseGitStatusEntries,
+    readStatusEnvFromFiles,
+    readRemoteStatusFromResult
+} from './status.mjs';
+import { assertLocalProbeMatchesMode, buildDockerComposeArgs, buildDockerComposeEnv } from './deploy-local.mjs';
+import { buildVerifyPlan } from './verify.mjs';
+
+describe('Command center scripts', () => {
+    it('exposes a small stable administrator command set', () => {
+        assert.deepEqual(buildAdminCommands(), {
+            doctor: 'npm run doctor',
+            status: 'npm run status',
+            verify: 'npm run verify',
+            deploy_local: 'npm run deploy:local',
+            deploy_space: 'npm run deploy:space',
+            agent_doctor: 'npm run agent:doctor',
+            hf_space_doctor: 'npm run doctor:hf-space',
+            hf_space_smoke: 'npm run smoke:hf-space'
+        });
+    });
+
+    it('keeps the full verification gate aligned with repository policy', () => {
+        assert.deepEqual(
+            buildVerifyPlan().map((step) => step.name),
+            ['test', 'lint', 'lint:scripts', 'build', 'diff-check', 'diff-cached-check']
+        );
+    });
+
+    it('supports a quick verification loop without hiding the full gate', () => {
+        assert.deepEqual(
+            buildVerifyPlan({ quick: true }).map((step) => step.name),
+            ['test:scripts', 'lint:scripts', 'diff-check', 'diff-cached-check']
+        );
+        assert.deepEqual(
+            buildVerifyPlan({ skipBuild: true }).map((step) => step.name),
+            ['test', 'lint', 'lint:scripts', 'diff-check', 'diff-cached-check']
+        );
+    });
+
+    it('can include the live PostgreSQL gate before the final diff check', () => {
+        assert.deepEqual(
+            buildVerifyPlan({ postgres: true }).map((step) => step.name),
+            ['test', 'lint', 'lint:scripts', 'build', 'test:postgres', 'diff-check', 'diff-cached-check']
+        );
+        assert.deepEqual(
+            buildVerifyPlan({ quick: true, postgres: true }).map((step) => step.name),
+            ['test:scripts', 'lint:scripts', 'test:postgres', 'diff-check', 'diff-cached-check']
+        );
+    });
+
+    it('parses NUL-delimited git porcelain paths without rewriting filenames', () => {
+        const output = [
+            ' M README.md',
+            '?? path with spaces.md',
+            'R  new name.md',
+            'old name.md',
+            ' M path -> not rename.md',
+            ' M line\nbreak.md',
+            ''
+        ].join('\0');
+
+        assert.deepEqual(parseGitStatusEntries(output), [
+            'README.md',
+            'path with spaces.md',
+            'new name.md',
+            'path -> not rename.md',
+            'line\nbreak.md'
+        ]);
+    });
+
+    it('summarizes independent image upstream smoke readiness without exposing credentials', () => {
+        const missing = buildImageUpstreamRealSmokeStatus({});
+        assert.equal(missing.configuration_complete, false);
+        assert.equal(missing.configured_count, 0);
+        assert.deepEqual(missing.missing_cases, [
+            'original-images-json',
+            'gaoren-images-sse',
+            'sub2api-images-sse',
+            'sub2api-responses-json',
+            'gpt2image-responses-sse'
+        ]);
+        assert.deepEqual(missing.missing_env_any['sub2api-responses-json'][0], [
+            'IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL',
+            'IMAGE_REAL_SMOKE_SUB2API_BASE_URL'
+        ]);
+        assert.equal(
+            missing.final_gate_command,
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable'
+        );
+
+        const configured = buildImageUpstreamRealSmokeStatus({
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://original.example/v1',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'original-secret',
+            IMAGE_REAL_SMOKE_GAOREN_BASE_URL: 'https://gaoren.example/v1',
+            IMAGE_REAL_SMOKE_GAOREN_API_KEY: 'gaoren-secret',
+            IMAGE_REAL_SMOKE_SUB2API_BASE_URL: 'https://sub2api.example/v1',
+            IMAGE_REAL_SMOKE_SUB2API_API_KEY: 'sub2api-secret',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL: 'gpt-4.1',
+            IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL: 'https://gpt2image.example/v1',
+            IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY: 'gpt2image-secret',
+            IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL: 'gpt-5.4'
+        });
+        assert.equal(configured.configuration_complete, true);
+        assert.equal(configured.configured_count, 5);
+        assert.equal(configured.missing_count, 0);
+        assert.doesNotMatch(JSON.stringify(configured), /secret|example\/v1/);
+    });
+
+    it('requires Responses top-level models in image upstream status readiness', () => {
+        const status = buildImageUpstreamRealSmokeStatus({
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://original.example/v1',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'original-secret',
+            IMAGE_REAL_SMOKE_GAOREN_BASE_URL: 'https://gaoren.example/v1',
+            IMAGE_REAL_SMOKE_GAOREN_API_KEY: 'gaoren-secret',
+            IMAGE_REAL_SMOKE_SUB2API_BASE_URL: 'https://sub2api.example/v1',
+            IMAGE_REAL_SMOKE_SUB2API_API_KEY: 'sub2api-secret',
+            IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL: 'https://gpt2image.example/v1',
+            IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY: 'gpt2image-secret'
+        });
+
+        assert.equal(status.configuration_complete, false);
+        assert.equal(status.configured_count, 3);
+        assert.deepEqual(status.configured_cases, [
+            'original-images-json',
+            'gaoren-images-sse',
+            'sub2api-images-sse'
+        ]);
+        assert.deepEqual(status.missing_cases, ['sub2api-responses-json', 'gpt2image-responses-sse']);
+        assert.deepEqual(status.missing_env_any['sub2api-responses-json'][0], [
+            'IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL',
+            'OPENAI_RESPONSES_API_MODEL'
+        ]);
+        assert.deepEqual(status.missing_env_any['gpt2image-responses-sse'][0], [
+            'IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL',
+            'OPENAI_RESPONSES_API_MODEL'
+        ]);
+        assert.doesNotMatch(JSON.stringify(status), /secret|example\/v1/);
+    });
+
+    it('does not treat the sub2api Responses image model as the Responses top-level model', () => {
+        const status = buildImageUpstreamRealSmokeStatus({
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL: 'https://sub2api-responses.example/v1',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY: 'sub2api-responses-secret',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL: 'gpt-image-2'
+        });
+
+        assert.equal(status.configuration_complete, false);
+        assert.equal(status.configured_count, 0);
+        assert.deepEqual(status.missing_cases, [
+            'original-images-json',
+            'gaoren-images-sse',
+            'sub2api-images-sse',
+            'sub2api-responses-json',
+            'gpt2image-responses-sse'
+        ]);
+        assert.deepEqual(status.missing_env_any['sub2api-responses-json'][0], [
+            'IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL',
+            'OPENAI_RESPONSES_API_MODEL'
+        ]);
+        assert.doesNotMatch(JSON.stringify(status), /sub2api-responses-secret|sub2api-responses\.example/);
+    });
+
+    it('reports unsafe independent image upstream base URLs without exposing values', () => {
+        const status = buildImageUpstreamRealSmokeStatus({
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://user:pass@original.example/v1?token=secret#frag',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'original-secret'
+        });
+
+        assert.equal(status.configuration_complete, false);
+        assert.equal(status.configured_count, 0);
+        assert.equal(status.missing_count, 4);
+        assert.equal(status.invalid_count, 1);
+        assert.deepEqual(status.invalid_cases, ['original-images-json']);
+        assert.deepEqual(status.invalid_env['original-images-json'], [
+            {
+                key: 'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL',
+                reason: 'must_not_include_credentials'
+            }
+        ]);
+        assert.equal(status.missing_env_any['original-images-json'], undefined);
+        assert.doesNotMatch(JSON.stringify(status), /user:pass|original\.example|token=secret|original-secret/);
+    });
+
+    it('loads independent image upstream smoke readiness from env files without overriding shell env', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'image-upstream-status-'));
+        const localEnvPath = path.join(tempDir, '.env.local');
+        const realSmokeEnvPath = path.join(tempDir, '.env.real-smoke.local');
+        await writeFile(
+            localEnvPath,
+            [
+                'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=https://local-original.example/v1',
+                'IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=local-original-secret',
+                'IMAGE_REAL_SMOKE_GAOREN_BASE_URL=https://local-gaoren.example/v1',
+                'IMAGE_REAL_SMOKE_GAOREN_API_KEY=local-gaoren-secret'
+            ].join('\n')
+        );
+        await writeFile(
+            realSmokeEnvPath,
+            [
+                'IMAGE_REAL_SMOKE_GAOREN_BASE_URL=https://real-gaoren.example/v1',
+                'IMAGE_REAL_SMOKE_GAOREN_API_KEY=real-gaoren-secret',
+                'IMAGE_REAL_SMOKE_SUB2API_BASE_URL=https://real-sub2api.example/v1',
+                'IMAGE_REAL_SMOKE_SUB2API_API_KEY=real-sub2api-secret',
+                'IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL=gpt-4.1',
+                'IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://real-gpt2image.example/v1',
+                'IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=real-gpt2image-secret',
+                'IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4'
+            ].join('\n')
+        );
+
+        try {
+            const statusEnv = readStatusEnvFromFiles(
+                {
+                    IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'shell-original-secret'
+                },
+                [
+                    { path: localEnvPath, override: false },
+                    { path: realSmokeEnvPath, override: true }
+                ]
+            );
+            const status = buildImageUpstreamRealSmokeStatus(statusEnv);
+
+            assert.equal(statusEnv.IMAGE_REAL_SMOKE_ORIGINAL_API_KEY, 'shell-original-secret');
+            assert.equal(status.configuration_complete, true);
+            assert.deepEqual(status.configured_cases, [
+                'original-images-json',
+                'gaoren-images-sse',
+                'sub2api-images-sse',
+                'sub2api-responses-json',
+                'gpt2image-responses-sse'
+            ]);
+            assert.doesNotMatch(JSON.stringify(status), /secret|example\/v1/);
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it('preserves mismatched env quotes in status env files', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'image-upstream-status-'));
+        const envPath = path.join(tempDir, '.env.local');
+        await writeFile(
+            envPath,
+            [
+                'MATCHED_DOUBLE="https://quoted.example/v1"',
+                "MATCHED_SINGLE='single-secret'",
+                'MATCHED_DOUBLE_SPACES="  kept value  "',
+                'MISMATCHED_LEADING="kept-value',
+                'MISMATCHED_TRAILING=kept-value"',
+                'MISMATCHED_PAIR="kept-value\'',
+                'SINGLE_DOUBLE_QUOTE="',
+                "SINGLE_SINGLE_QUOTE='"
+            ].join('\n')
+        );
+
+        try {
+            const statusEnv = readStatusEnvFromFiles({}, [{ path: envPath, override: false }]);
+
+            assert.equal(statusEnv.MATCHED_DOUBLE, 'https://quoted.example/v1');
+            assert.equal(statusEnv.MATCHED_SINGLE, 'single-secret');
+            assert.equal(statusEnv.MATCHED_DOUBLE_SPACES, '  kept value  ');
+            assert.equal(statusEnv.MISMATCHED_LEADING, '"kept-value');
+            assert.equal(statusEnv.MISMATCHED_TRAILING, 'kept-value"');
+            assert.equal(statusEnv.MISMATCHED_PAIR, '"kept-value\'');
+            assert.equal(statusEnv.SINGLE_DOUBLE_QUOTE, '"');
+            assert.equal(statusEnv.SINGLE_SINGLE_QUOTE, "'");
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it('builds deterministic local deploy compose arguments', () => {
+        assert.deepEqual(buildDockerComposeArgs(), ['compose', '-f', 'docker-compose.yml', 'up', '-d', '--build']);
+        assert.deepEqual(buildDockerComposeArgs({ memory: true }), [
+            'compose',
+            '-f',
+            'docker-compose.yml',
+            '-f',
+            'docker-compose.memory.yml',
+            'up',
+            '-d',
+            '--build'
+        ]);
+    });
+
+    it('uses plain compose progress for diagnosable local deploy output', () => {
+        assert.deepEqual(buildDockerComposeEnv({ PATH: '/bin', COMPOSE_PROGRESS: 'auto' }), {
+            PATH: '/bin',
+            COMPOSE_PROGRESS: 'plain'
+        });
+    });
+
+    it('fails local memory deploy probes when the overlay did not take effect', () => {
+        assert.doesNotThrow(() => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }));
+        assert.doesNotThrow(() =>
+            assertLocalProbeMatchesMode({ stateBackend: 'memory', imageStorageMode: 'indexeddb' }, { memory: true })
+        );
+        assert.throws(
+            () => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }, { memory: true }),
+            /Memory overlay did not take effect/
+        );
+    });
+
+    it('routes agent:doctor through the non-billable contract check', () => {
+        const args = buildAgentDoctorArgs();
+        assert.match(args[0], /generate-image\.mjs$/);
+        assert.deepEqual(args.slice(1), ['--contract-check', '--timeout-ms', '60000', 'contract check']);
+    });
+
+    it('preserves raw child output for command consumers', () => {
+        const result = runCommand(process.execPath, ['-e', 'process.stdout.write(" M README.md\\n")']);
+
+        assert.equal(result.ok, true);
+        assert.equal(result.stdout, ' M README.md\n');
+    });
+
+    it('parses JSON output after command preamble lines', () => {
+        assert.deepEqual(parseJsonPayload('hint\n{"ok":true}', 'example'), { ok: true });
+        assert.deepEqual(parseJsonPayload('hint\n{"ok":true}\ntrailing log', 'example'), { ok: true });
+        assert.deepEqual(parseJsonPayload('[WARN] not json\n{"ok":true}', 'example'), { ok: true });
+        assert.throws(() => parseJsonPayload('hint only', 'example'), /example did not return JSON output/);
+        assert.throws(() => parseJsonPayload('hint\n{"ok":', 'example'), /example returned invalid JSON/);
+    });
+
+    it('times out local HTTP probes instead of hanging', async () => {
+        const server = createServer(() => {});
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        try {
+            assert.equal(typeof address, 'object');
+            await assert.rejects(
+                fetchJsonWithTimeout(`http://127.0.0.1:${address.port}/api/agent/capabilities`, { timeoutMs: 20 }),
+                /timed out after 20ms/
+            );
+        } finally {
+            await new Promise((resolve) => server.close(resolve));
+        }
+    });
+
+    it('preserves invalid URL fetch errors while building timeout diagnostics', async () => {
+        await assert.rejects(() => fetchJsonWithTimeout('not a url', { timeoutMs: 20 }), /Failed to parse URL|Invalid URL/i);
+    });
+
+    it('includes a response snippet when HTTP probes return non-JSON bodies', async () => {
+        const server = createServer((request, response) => {
+            response.writeHead(200, { 'content-type': 'text/html' });
+            response.end('<html>login page</html>');
+        });
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        try {
+            assert.equal(typeof address, 'object');
+            await assert.rejects(
+                fetchJsonWithTimeout(`http://127.0.0.1:${address.port}/api/agent/capabilities`, { timeoutMs: 1000 }),
+                /did not return JSON: <html>login page<\/html>/
+            );
+        } finally {
+            await new Promise((resolve) => server.close(resolve));
+        }
+    });
+
+    it('redacts response snippets from production HTTP probe errors', async () => {
+        const originalNodeEnv = process.env.NODE_ENV;
+        process.env.NODE_ENV = 'production';
+        const server = createServer((request, response) => {
+            response.writeHead(502, { 'content-type': 'text/plain' });
+            response.end('secret upstream body');
+        });
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        try {
+            assert.equal(typeof address, 'object');
+            await assert.rejects(
+                fetchJsonWithTimeout(`http://127.0.0.1:${address.port}/api/agent/capabilities`, { timeoutMs: 1000 }),
+                (error) => {
+                    assert.match(error.message, /failed with HTTP 502/);
+                    assert.doesNotMatch(error.message, /secret upstream body/);
+                    return true;
+                }
+            );
+        } finally {
+            if (originalNodeEnv === undefined) {
+                delete process.env.NODE_ENV;
+            } else {
+                process.env.NODE_ENV = originalNodeEnv;
+            }
+            await new Promise((resolve) => server.close(resolve));
+        }
+    });
+
+    it('supports command timeouts for long-running child processes', () => {
+        const result = runCommand(process.execPath, ['-e', 'setTimeout(() => {}, 1000)'], { timeoutMs: 20 });
+
+        assert.equal(result.ok, false);
+        assert.equal(result.status, null);
+        assert.match(result.error, /timed out|ETIMEDOUT|SIGTERM/i);
+        assert.match(pickFailureOutput(result), /error:|signal:/);
+    });
+
+    it('includes spawn errors in failure summaries without stdout or stderr', () => {
+        const summary = pickFailureOutput({ stdout: '', stderr: '', error: 'spawn missing ENOENT', signal: null });
+
+        assert.equal(summary, 'error: spawn missing ENOENT');
+    });
+
+    it('includes non-zero exit status in failure summaries', () => {
+        const summary = pickFailureOutput({ stdout: '', stderr: 'bad option', status: 129, signal: null });
+
+        assert.equal(summary, 'bad option\nstatus: 129');
+    });
+
+    it('keeps local status usable when remote status JSON is malformed', () => {
+        assert.deepEqual(readRemoteStatusFromResult({ ok: true, stdout: 'not json' }), {
+            ok: false,
+            error: 'hf spaces info did not return JSON output.'
+        });
+    });
+});

scripts/deploy-hf-space.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { fetchJsonWithTimeout, parseJsonPayload, runCommandStrict } from './command-center-utils.mjs';
+import { assertKnownOptions, HF_SPACE_ID, HF_SPACE_URL, isMainModule } from './hf-space-doctor-utils.mjs';
+
+const STATUS_POLL_ATTEMPTS = 40;
+const STATUS_POLL_INTERVAL_MS = 10_000;
+const PUBLIC_ENDPOINT_TIMEOUT_MS = 10_000;
+const HF_CLI_TIMEOUT_MS = 120_000;
+export const GIT_ARCHIVE_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
+
+function parseArgs(argv) {
+    assertKnownOptions(argv, ['--help', '-h']);
+    return {
+        help: argv.includes('--help') || argv.includes('-h')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run deploy:hf-space
+
+Deploys the current clean git HEAD to ${HF_SPACE_ID} with the official hf CLI.
+
+The script uploads a temporary git archive, waits for the Space to run the new
+Space commit, and performs read-only public endpoint checks.`);
+}
+
+function runText(command, args, options = {}) {
+    return runCommandStrict(command, args, {
+        input: options.input,
+        timeoutMs: options.timeoutMs || HF_CLI_TIMEOUT_MS
+    }).trim();
+}
+
+function readRepositorySlug() {
+    const envSlug = process.env.REPO_SLUG?.trim();
+    if (envSlug) return envSlug;
+    try {
+        return parseRepositorySlug(runText('git', ['remote', 'get-url', 'origin']));
+    } catch (error) {
+        throw new Error(
+            `Unable to detect repository slug from git origin. Set REPO_SLUG=owner/repo. ${error instanceof Error ? error.message : String(error)}`
+        );
+    }
+}
+
+export function parseRepositorySlug(remoteUrl) {
+    const text = String(remoteUrl || '').trim();
+    const httpsMatch = text.match(/^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+    if (httpsMatch) return `${httpsMatch[1]}/${httpsMatch[2]}`;
+    const sshMatch = text.match(/^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+    if (sshMatch) return `${sshMatch[1]}/${sshMatch[2]}`;
+    throw new Error('Unable to detect repository slug from git origin URL. Set REPO_SLUG=owner/repo.');
+}
+
+function runBinary(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: 'buffer',
+        maxBuffer: GIT_ARCHIVE_MAX_BUFFER_BYTES,
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    if (result.error) throw new Error(`${command} ${args.join(' ')} failed: ${result.error.message}`);
+    if (result.status !== 0) {
+        const output = result.stderr.toString('utf8').trim();
+        throw new Error(output || `${command} ${args.join(' ')} failed`);
+    }
+    return result.stdout;
+}
+
+function assertCleanGitWorktree() {
+    const status = runText('git', ['status', '--porcelain']);
+    if (status) {
+        throw new Error('Refusing to deploy a dirty worktree. Commit or revert local changes first.');
+    }
+}
+
+function prepareSourceTree() {
+    const sourceDir = mkdtempSync(join(tmpdir(), 'gpt-image-hf-space-'));
+    const archive = runBinary('git', ['archive', '--format=tar', 'HEAD']);
+    runText('tar', ['-x', '-C', sourceDir], { input: archive });
+    return sourceDir;
+}
+
+export function extractUploadCommitSha(output) {
+    const payload = parseJsonPayload(output, 'hf upload');
+    const directSha = [payload.sha, payload.commit, payload.commitSha, payload.commit_sha].find((value) =>
+        /^[0-9a-f]{40}$/.test(String(value || ''))
+    );
+    if (directSha) return directSha;
+
+    const match = String(payload.url || '').match(/\/commit\/([0-9a-f]{40})$/);
+    if (!match) throw new Error('hf upload output did not include a Space commit SHA or commit URL.');
+    return match[1];
+}
+
+export function buildUploadArgs({ sourceDir, localSha, repoSlug }) {
+    if (!repoSlug?.trim()) throw new Error('REPO_SLUG is required for deploy metadata.');
+    return [
+        'upload',
+        HF_SPACE_ID,
+        sourceDir,
+        '.',
+        '--repo-type',
+        'space',
+        '--commit-message',
+        `Deploy ${localSha.slice(0, 7)} to Docker Space`,
+        '--commit-description',
+        `Source: ${repoSlug}@${localSha}`,
+        '--json'
+    ];
+}
+
+function uploadSourceTree(sourceDir, localSha) {
+    const output = runText('hf', buildUploadArgs({ sourceDir, localSha, repoSlug: readRepositorySlug() }));
+    return extractUploadCommitSha(output);
+}
+
+function readSpaceInfo() {
+    const output = runText('hf', ['spaces', 'info', HF_SPACE_ID, '--format', 'json']);
+    return parseJsonPayload(output, 'hf spaces info');
+}
+
+async function waitForRunning(spaceCommitSha) {
+    let lastStage = 'unknown';
+    let lastSha = 'unknown';
+    for (let attempt = 1; attempt <= STATUS_POLL_ATTEMPTS; attempt += 1) {
+        const info = readSpaceInfo();
+        lastStage = info.runtime?.stage || 'unknown';
+        lastSha = info.sha || info.runtime?.raw?.sha || 'unknown';
+        console.log(`attempt=${attempt} stage=${lastStage} sha=${lastSha}`);
+        if (lastStage === 'RUNNING' && lastSha === spaceCommitSha) {
+            return { stage: lastStage, sha: lastSha };
+        }
+        await delay(STATUS_POLL_INTERVAL_MS);
+    }
+    throw new Error(`Space did not reach RUNNING for ${spaceCommitSha}; last stage=${lastStage} sha=${lastSha}`);
+}
+
+async function fetchJson(path) {
+    return fetchJsonWithTimeout(new URL(path, HF_SPACE_URL), { timeoutMs: PUBLIC_ENDPOINT_TIMEOUT_MS });
+}
+
+async function verifyPublicEndpoints() {
+    const authStatus = await fetchJson('/api/auth-status');
+    const capabilities = await fetchJson('/api/agent/capabilities');
+    const runtime = await fetchJson('/api/runtime-capabilities');
+
+    if (authStatus.passwordRequired !== true) {
+        throw new Error('/api/auth-status did not report passwordRequired=true.');
+    }
+    if (capabilities.defaults?.state_backend !== 'memory') {
+        throw new Error('/api/agent/capabilities did not report state_backend=memory.');
+    }
+    if (capabilities.storage?.image_storage_mode !== 'indexeddb') {
+        throw new Error('/api/agent/capabilities did not report image_storage_mode=indexeddb.');
+    }
+    return {
+        passwordRequired: authStatus.passwordRequired,
+        agentAuth: capabilities.auth,
+        stateBackend: capabilities.defaults.state_backend,
+        imageStorageMode: capabilities.storage.image_storage_mode,
+        streamingBatch: runtime.streamingBatch
+    };
+}
+
+async function deploy() {
+    assertCleanGitWorktree();
+    runText('hf', ['auth', 'whoami']);
+    const localSha = runText('git', ['rev-parse', 'HEAD']);
+    const sourceDir = prepareSourceTree();
+    try {
+        const spaceCommitSha = uploadSourceTree(sourceDir, localSha);
+        const runtime = await waitForRunning(spaceCommitSha);
+        const verification = await verifyPublicEndpoints();
+        console.log(
+            JSON.stringify(
+                {
+                    ok: true,
+                    spaceId: HF_SPACE_ID,
+                    spaceUrl: HF_SPACE_URL,
+                    localSha,
+                    spaceCommitSha,
+                    runtime,
+                    verification
+                },
+                null,
+                2
+            )
+        );
+    } finally {
+        rmSync(sourceDir, { force: true, recursive: true });
+    }
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    await deploy();
+}
+
+if (isMainModule(import.meta.url, process.argv[1])) {
+    main().catch((error) => {
+        console.error(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2));
+        process.exit(1);
+    });
+}

scripts/deploy-hf-space.test.mjs

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { GIT_ARCHIVE_MAX_BUFFER_BYTES, buildUploadArgs, extractUploadCommitSha, parseRepositorySlug } from './deploy-hf-space.mjs';
+
+describe('HF Space deploy script', () => {
+    it('extracts the Space commit SHA from hf upload JSON output', () => {
+        const sha = extractUploadCommitSha(
+            [
+                'Start hashing 189 files.',
+                '{"url":"https://huggingface.co/spaces/misonL/gpt-image-playground-customer/commit/32151b6aeaec0e59f14d1aaa87fba160ca8410df"}'
+            ].join('\n')
+        );
+
+        assert.equal(sha, '32151b6aeaec0e59f14d1aaa87fba160ca8410df');
+    });
+
+    it('rejects upload output without a Space commit URL', () => {
+        assert.throws(() => extractUploadCommitSha('{"url":"https://huggingface.co/spaces/misonL/demo"}'), /commit SHA or commit URL/);
+    });
+
+    it('extracts the Space commit SHA from direct hf upload JSON fields', () => {
+        assert.equal(
+            extractUploadCommitSha('{"sha":"cccccccccccccccccccccccccccccccccccccccc"}'),
+            'cccccccccccccccccccccccccccccccccccccccc'
+        );
+        assert.equal(
+            extractUploadCommitSha('{"commit_sha":"dddddddddddddddddddddddddddddddddddddddd"}'),
+            'dddddddddddddddddddddddddddddddddddddddd'
+        );
+    });
+
+    it('extracts the Space commit SHA when hf prints warning lines before JSON', () => {
+        const sha = extractUploadCommitSha(
+            [
+                '[WARN] retrying upload metadata',
+                '{"url":"https://huggingface.co/spaces/misonL/gpt-image-playground-customer/commit/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}',
+                'done'
+            ].join('\n')
+        );
+
+        assert.equal(sha, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    });
+
+    it('builds upload args without embedding newline characters in commit metadata', () => {
+        const args = buildUploadArgs({
+            sourceDir: '/tmp/source',
+            localSha: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+            repoSlug: 'MisonL/gpt-image-playground-customer'
+        });
+
+        assert.equal(args.includes('--json'), true);
+        assert.equal(args[args.indexOf('--commit-message') + 1], 'Deploy bbbbbbb to Docker Space');
+        assert.equal(
+            args[args.indexOf('--commit-description') + 1],
+            'Source: MisonL/gpt-image-playground-customer@bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
+        );
+        assert.equal(args.some((arg) => arg.includes('\n')), false);
+    });
+
+    it('uses a provided repository slug in upload commit metadata', () => {
+        const args = buildUploadArgs({
+            sourceDir: '/tmp/source',
+            localSha: 'eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+            repoSlug: 'owner/repo'
+        });
+
+        assert.equal(args[args.indexOf('--commit-description') + 1], 'Source: owner/repo@eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee');
+    });
+
+    it('parses GitHub repository slugs from common origin URL formats', () => {
+        assert.equal(parseRepositorySlug('https://github.com/MisonL/gpt-image-playground-customer.git'), 'MisonL/gpt-image-playground-customer');
+        assert.equal(parseRepositorySlug('git@github.com:MisonL/gpt-image-playground-customer.git'), 'MisonL/gpt-image-playground-customer');
+        assert.throws(() => parseRepositorySlug('not-a-github-url'), /Set REPO_SLUG=owner\/repo/);
+    });
+
+    it('requires an explicit repository slug for upload metadata', () => {
+        assert.throws(
+            () =>
+                buildUploadArgs({
+                    sourceDir: '/tmp/source',
+                    localSha: 'ffffffffffffffffffffffffffffffffffffffff'
+                }),
+            /REPO_SLUG is required/
+        );
+    });
+
+    it('keeps enough buffer for repository archives used by Space uploads', () => {
+        assert.ok(GIT_ARCHIVE_MAX_BUFFER_BYTES >= 128 * 1024 * 1024);
+    });
+});

scripts/deploy-local.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { fetchJsonWithTimeout, isMainModule, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
+
+const LOCAL_BASE_URL = 'http://localhost:4783';
+const PROBE_PATHS = ['/api/auth-status', '/api/runtime-capabilities', '/api/agent/capabilities'];
+const PROBE_ATTEMPTS = 30;
+const PROBE_INTERVAL_MS = 2000;
+const PROBE_TIMEOUT_MS = 5000;
+const DOCKER_COMPOSE_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function buildDockerComposeArgs(options = {}) {
+    const files = ['-f', 'docker-compose.yml'];
+    if (options.memory) files.push('-f', 'docker-compose.memory.yml');
+    return ['compose', ...files, 'up', '-d', '--build'];
+}
+
+export function buildDockerComposeEnv(env = process.env) {
+    return { ...env, COMPOSE_PROGRESS: 'plain' };
+}
+
+function parseArgs(argv) {
+    const unknown = argv.find((arg) => !['--help', '-h', '--memory', '--skip-probe'].includes(arg));
+    if (unknown) throw new Error(`Unknown option: ${unknown}`);
+    return {
+        help: argv.includes('--help') || argv.includes('-h'),
+        memory: argv.includes('--memory'),
+        skipProbe: argv.includes('--skip-probe')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run deploy:local
+  npm run deploy:local -- --memory
+
+Options:
+  --memory       Use docker-compose.memory.yml overlay for HF Space-like memory mode.
+  --skip-probe   Rebuild and start the container without HTTP endpoint probes.
+  --help         Show this help.`);
+}
+
+async function fetchJson(path) {
+    return fetchJsonWithTimeout(new URL(path, LOCAL_BASE_URL), { timeoutMs: PROBE_TIMEOUT_MS });
+}
+
+async function waitForLocalEndpoints() {
+    let lastError = '';
+    for (let attempt = 1; attempt <= PROBE_ATTEMPTS; attempt += 1) {
+        try {
+            const responses = {};
+            for (const path of PROBE_PATHS) responses[path] = await fetchJson(path);
+            return {
+                attempts: attempt,
+                baseUrl: LOCAL_BASE_URL,
+                authRequired: responses['/api/auth-status'].passwordRequired,
+                stateBackend: responses['/api/agent/capabilities'].defaults?.state_backend,
+                imageStorageMode: responses['/api/agent/capabilities'].storage?.image_storage_mode,
+                streamingBatch: responses['/api/runtime-capabilities'].streamingBatch
+            };
+        } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            await delay(PROBE_INTERVAL_MS);
+        }
+    }
+    throw new Error(`Local container did not pass HTTP probes: ${lastError}`);
+}
+
+export function assertLocalProbeMatchesMode(probe, options = {}) {
+    if (!options.memory) return;
+    const mismatches = [];
+    if (probe.stateBackend !== 'memory') mismatches.push(`stateBackend=${probe.stateBackend ?? '<missing>'} expected memory`);
+    if (probe.imageStorageMode !== 'indexeddb') {
+        mismatches.push(`imageStorageMode=${probe.imageStorageMode ?? '<missing>'} expected indexeddb`);
+    }
+    if (mismatches.length) throw new Error(`Memory overlay did not take effect: ${mismatches.join(', ')}.`);
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+
+    const docker = runCommand('docker', buildDockerComposeArgs(options), {
+        env: buildDockerComposeEnv(),
+        timeoutMs: DOCKER_COMPOSE_TIMEOUT_MS
+    });
+    if (!docker.ok) {
+        printJson({ ok: false, phase: 'docker-compose', output: pickFailureOutput(docker) });
+        process.exit(1);
+    }
+
+    if (options.skipProbe) {
+        printJson({ ok: true, phase: 'docker-compose', probe: 'skipped' });
+        return;
+    }
+
+    const probe = await waitForLocalEndpoints();
+    assertLocalProbeMatchesMode(probe, options);
+    printJson({ ok: true, phase: 'ready', probe });
+}
+
+if (isMainModule(import.meta.url, process.argv[1])) {
+    main().catch((error) => {
+        printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+        process.exit(1);
+    });
+}

scripts/doctor-hf-space.mjs

@@ -1,34 +1,32 @@
 #!/usr/bin/env node
 
-import { existsSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import {
     assertKnownOptions,
     buildNextActions,
     classifyRequiredAndRecommendedNames,
-    DEFAULT_ACCESS_FILE,
+    HF_SPACE_ID,
+    HF_SPACE_URL,
+    getJsonKeyValues,
     getJsonNames,
     isMainModule,
-    missingKeys,
-    parseAccessFile,
-    readEnvValue,
-    readOptionValue,
-    runCommand,
-    validateSpaceId,
+    runDoctorCommand,
     validateSpaceUrl
 } from './hf-space-doctor-utils.mjs';
 
 const MIN_NODE_MAJOR = 20;
-const REQUIRED_ACCESS_KEYS = ['HF_SPACE_ID', 'HF_SPACE_URL', 'HF_SPACE_SECRET_KEYS', 'APP_PASSWORD', 'AGENT_API_TOKEN'];
-const FORBIDDEN_ACCESS_KEYS = ['HF_TOKEN', 'HUGGINGFACE_TOKEN', 'HF_PASSWORD', 'HUGGINGFACE_PASSWORD'];
 const REQUIRED_SPACE_VARIABLES = ['AGENT_STATE_BACKEND', 'NEXT_PUBLIC_IMAGE_STORAGE_MODE'];
 const RECOMMENDED_SPACE_VARIABLES = ['APP_LOG_LEVEL'];
+const REQUIRED_SPACE_VARIABLE_VALUES = new Map([
+    ['AGENT_STATE_BACKEND', 'memory'],
+    ['NEXT_PUBLIC_IMAGE_STORAGE_MODE', 'indexeddb']
+]);
 const REQUIRED_SPACE_SECRETS = ['APP_PASSWORD', 'AGENT_API_TOKEN'];
 const OPTIONAL_GENERATION_SECRETS = ['OPENAI_API_KEY', 'OPENAI_CHANNEL_1_API_KEYS'];
 
 function parseArgs(argv) {
-    assertKnownOptions(argv, ['--access-file', '--help', '-h', '--skip-remote']);
+    assertKnownOptions(argv, ['--help', '-h', '--skip-remote']);
     return {
-        accessFile: readOptionValue(argv, '--access-file') || readEnvValue('HF_SPACE_ACCESS_FILE') || DEFAULT_ACCESS_FILE,
         help: argv.includes('--help') || argv.includes('-h'),
         skipRemote: argv.includes('--skip-remote')
     };
@@ -39,12 +37,8 @@ function printHelp() {
   npm run doctor:hf-space
 
 Options:
-  --access-file <path>  Override the access file path.
   --skip-remote         Skip read-only Hugging Face remote checks.
-  --help                Show this help.
-
-Environment overrides:
-  HF_SPACE_ACCESS_FILE`);
+  --help                Show this help.`);
 }
 
 function addCheck(checks, status, name, message, details = {}) {
@@ -61,7 +55,7 @@ function checkNode(checks) {
 }
 
 function checkCommand(checks, name, command, args, failureAction) {
-    const result = runCommand(command, args);
+    const result = runDoctorCommand(command, args);
     if (result.ok) {
         addCheck(checks, 'pass', name, `${command} is available.`, { version: result.stdout.split(/\r?\n/)[0] });
         return true;
@@ -70,127 +64,44 @@ function checkCommand(checks, name, command, args, failureAction) {
     return false;
 }
 
-function checkAccessFile(checks, accessFile) {
-    if (!existsSync(accessFile)) {
-        addCheck(checks, 'fail', 'access-file', `Access file is missing: ${accessFile}`, {
-            action: 'Run npm run init-access:hf-space -- --space-id <namespace>/<space-name> --space-url https://<user>-<space>.hf.space'
-        });
-        return undefined;
-    }
-
-    let values;
-    try {
-        values = parseAccessFile(accessFile);
-    } catch (error) {
-        addCheck(checks, 'fail', 'access-file', 'Access file cannot be read.', {
-            error: error instanceof Error ? error.message : String(error)
-        });
-        return undefined;
-    }
-
-    addCheck(checks, 'pass', 'access-file', `Access file exists: ${accessFile}`);
-
-    if (process.platform !== 'win32') {
-        const mode = statSync(accessFile).mode & 0o777;
-        if ((mode & 0o077) === 0) {
-            addCheck(checks, 'pass', 'access-file-permissions', `Access file permissions are ${mode.toString(8)}.`);
-        } else {
-            addCheck(checks, 'fail', 'access-file-permissions', `Access file permissions are ${mode.toString(8)}; expected 600.`, {
-                action: `chmod 600 ${accessFile}`
-            });
-        }
-    }
-
-    const missing = missingKeys(REQUIRED_ACCESS_KEYS, values);
-    if (missing.length) {
-        addCheck(checks, 'fail', 'access-file-keys', `Access file is missing required keys: ${missing.join(', ')}.`);
-    } else {
-        addCheck(checks, 'pass', 'access-file-keys', 'Access file contains all required non-empty keys.');
-    }
-
-    const forbidden = FORBIDDEN_ACCESS_KEYS.filter((key) => values.has(key));
-    if (forbidden.length) {
-        addCheck(checks, 'fail', 'access-file-forbidden-keys', `Access file must not contain Hugging Face credentials: ${forbidden.join(', ')}.`);
-    } else {
-        addCheck(checks, 'pass', 'access-file-forbidden-keys', 'Access file does not contain Hugging Face account credentials.');
-    }
-
-    validateAccessValues(checks, values);
-    return values;
-}
-
-function validateAccessValues(checks, values) {
-    const spaceId = values.get('HF_SPACE_ID')?.trim();
-    const spaceIdError = validateSpaceId(spaceId);
-    if (!spaceIdError) {
-        addCheck(checks, 'pass', 'space-id', 'HF_SPACE_ID has namespace/space format.');
-    } else if (spaceId) {
-        addCheck(checks, 'fail', 'space-id', spaceIdError);
-    }
-
-    const spaceUrl = values.get('HF_SPACE_URL')?.trim();
-    if (spaceUrl) {
-        const spaceUrlError = validateSpaceUrl(spaceUrl);
-        if (spaceUrlError) {
-            addCheck(checks, 'fail', 'space-url', spaceUrlError);
-        } else {
-            addCheck(checks, 'pass', 'space-url', 'HF_SPACE_URL looks like a Hugging Face Space URL.');
-        }
-    }
-
-    const appPassword = values.get('APP_PASSWORD') || '';
-    const agentToken = values.get('AGENT_API_TOKEN') || '';
-    if (appPassword.length >= 16 && agentToken.length >= 24) {
-        addCheck(
-            checks,
-            'pass',
-            'generated-secrets',
-            'APP_PASSWORD access code and AGENT_API_TOKEN meet the minimum length checks.'
-        );
-    } else {
-        addCheck(
-            checks,
-            'fail',
-            'generated-secrets',
-            'APP_PASSWORD access code must be at least 16 chars and AGENT_API_TOKEN at least 24 chars.'
-        );
+function checkConfiguredTarget(checks) {
+    const spaceUrlError = validateSpaceUrl(HF_SPACE_URL);
+    if (spaceUrlError) {
+        addCheck(checks, 'fail', 'space-target', spaceUrlError);
+        return;
     }
+    addCheck(checks, 'pass', 'space-target', `Using fixed Space target ${HF_SPACE_ID}.`, { spaceUrl: HF_SPACE_URL });
 }
 
-function checkRemote(checks, values, skipRemote, hfAvailable, hfAuthenticated) {
+function checkRemote(checks, skipRemote, hfAvailable, hfAuthenticated) {
     if (skipRemote) {
         addCheck(checks, 'skip', 'remote-space', 'Remote checks were skipped by --skip-remote.');
         return;
     }
-    if (!hfAvailable || !hfAuthenticated || !values) {
-        addCheck(checks, 'skip', 'remote-space', 'Remote checks require hf CLI, hf auth login, and a valid access file.');
+    if (!hfAvailable || !hfAuthenticated) {
+        addCheck(checks, 'skip', 'remote-space', 'Remote checks require hf CLI and hf auth login.');
         return;
     }
 
-    const spaceId = values.get('HF_SPACE_ID')?.trim();
-    if (!spaceId) {
-        addCheck(checks, 'skip', 'remote-space', 'Remote checks require HF_SPACE_ID in the access file.');
-        return;
-    }
-    const info = runCommand('hf', ['spaces', 'info', spaceId, '--format', 'json']);
+    const info = runDoctorCommand('hf', ['spaces', 'info', HF_SPACE_ID, '--format', 'json']);
     if (!info.ok) {
-        addCheck(checks, 'fail', 'remote-space', `Cannot read Space info for ${spaceId}.`, { error: info.error });
+        addCheck(checks, 'fail', 'remote-space', `Cannot read Space info for ${HF_SPACE_ID}.`, { error: info.error });
         return;
     }
-    addCheck(checks, 'pass', 'remote-space', `Space ${spaceId} is accessible.`);
+    addCheck(checks, 'pass', 'remote-space', `Space ${HF_SPACE_ID} is accessible.`);
     checkRemoteNames(
         checks,
-        spaceId,
+        HF_SPACE_ID,
         'remote-variables',
-        ['spaces', 'variables', 'list', spaceId, '--json'],
+        ['spaces', 'variables', 'list', HF_SPACE_ID, '--json'],
         REQUIRED_SPACE_VARIABLES,
         RECOMMENDED_SPACE_VARIABLES
     );
-    checkRemoteSecrets(checks, spaceId);
+    checkRemoteSecrets(checks, HF_SPACE_ID);
 }
 
 function checkRemoteNames(checks, spaceId, name, args, requiredNames, recommendedNames = []) {
-    const result = runCommand('hf', args);
+    const result = runDoctorCommand('hf', args);
     if (!result.ok) {
         addCheck(checks, 'warn', name, `Cannot list ${name} for ${spaceId}.`, { error: result.error });
         return;
@@ -210,6 +121,7 @@ function checkRemoteNames(checks, spaceId, name, args, requiredNames, recommende
         if (missingRecommended.length) {
             addCheck(checks, 'warn', name, `${name} missing recommended names: ${missingRecommended.join(', ')}.`);
         }
+        checkRemoteVariableValues(checks, result.stdout);
     } catch (error) {
         addCheck(checks, 'warn', name, `Cannot parse ${name} JSON output.`, {
             error: error instanceof Error ? error.message : String(error)
@@ -217,8 +129,22 @@ function checkRemoteNames(checks, spaceId, name, args, requiredNames, recommende
     }
 }
 
+function checkRemoteVariableValues(checks, jsonText) {
+    const values = getJsonKeyValues(jsonText);
+    const mismatches = [];
+    for (const [key, expected] of REQUIRED_SPACE_VARIABLE_VALUES) {
+        const actual = values.get(key);
+        if (actual !== expected) mismatches.push(`${key}=${actual ?? '<missing>'} expected ${expected}`);
+    }
+    if (mismatches.length) {
+        addCheck(checks, 'fail', 'remote-variable-values', `Remote variable values are not Space-free compatible: ${mismatches.join(', ')}.`);
+        return;
+    }
+    addCheck(checks, 'pass', 'remote-variable-values', 'Remote variable values match the Space-free runtime contract.');
+}
+
 function checkRemoteSecrets(checks, spaceId) {
-    const result = runCommand('hf', ['spaces', 'secrets', 'list', spaceId, '--json']);
+    const result = runDoctorCommand('hf', ['spaces', 'secrets', 'list', spaceId, '--json']);
     if (!result.ok) {
         addCheck(checks, 'warn', 'remote-secrets', `Cannot list remote secrets for ${spaceId}.`, { error: result.error });
         return;
@@ -255,7 +181,7 @@ function main() {
     checkNode(checks);
     checkCommand(checks, 'npm', 'npm', ['--version'], 'npm is missing. Install Node.js 20 or newer with npm.');
     const hfAvailable = checkCommand(checks, 'hf-cli', 'hf', ['version'], 'hf CLI is missing. Install the Hugging Face CLI.');
-    const hfAuth = hfAvailable ? runCommand('hf', ['auth', 'whoami']) : { ok: false };
+    const hfAuth = hfAvailable ? runDoctorCommand('hf', ['auth', 'whoami']) : { ok: false };
     if (hfAvailable && hfAuth.ok) {
         addCheck(checks, 'pass', 'hf-auth', 'hf CLI is authenticated.');
     } else if (hfAvailable) {
@@ -270,19 +196,19 @@ function main() {
         addCheck(checks, 'warn', 'node-modules', 'node_modules is missing; build, lint, test, and smoke commands require npm install.');
     }
     checkCommand(checks, 'git', 'git', ['--version'], 'git is missing; install git before cloning or pushing Space repos.');
-    const docker = runCommand('docker', ['version', '--format', '{{.Server.Version}}']);
+    const docker = runDoctorCommand('docker', ['version', '--format', '{{.Server.Version}}']);
     if (docker.ok) {
         addCheck(checks, 'pass', 'docker', 'docker is available.', { version: docker.stdout.split(/\r?\n/)[0] });
     } else {
         addCheck(checks, 'warn', 'docker', 'Docker is unavailable; npm run smoke:hf-space will not work.', {
             error: docker.error
         });
-        const dockerCli = runCommand('docker', ['--version']);
+        const dockerCli = runDoctorCommand('docker', ['--version']);
         if (dockerCli.ok) addCheck(checks, 'warn', 'docker-daemon', 'Docker CLI exists but the daemon is not reachable.');
     }
 
-    const values = checkAccessFile(checks, options.accessFile);
-    checkRemote(checks, values, options.skipRemote, hfAvailable, Boolean(hfAuth.ok));
+    checkConfiguredTarget(checks);
+    checkRemote(checks, options.skipRemote, hfAvailable, Boolean(hfAuth.ok));
 
     const failed = checks.some((check) => check.status === 'fail');
     console.log(JSON.stringify({ ok: !failed, checks, nextActions: buildNextActions(checks) }, null, 2));

scripts/doctor.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule, parseJsonPayload, printJson, runCommand } from './command-center-utils.mjs';
+
+const HF_DOCTOR_SCRIPT = fileURLToPath(new URL('./doctor-hf-space.mjs', import.meta.url));
+const DOCTOR_TIMEOUT_MS = 120_000;
+
+function parseArgs(argv) {
+    const unknown = argv.find((arg) => !['--help', '-h', '--skip-remote'].includes(arg));
+    if (unknown) throw new Error(`Unknown option: ${unknown}`);
+    return {
+        help: argv.includes('--help') || argv.includes('-h'),
+        skipRemote: argv.includes('--skip-remote')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run doctor
+  npm run doctor -- --skip-remote
+
+Options:
+  --skip-remote  Skip read-only Hugging Face remote checks.
+  --help         Show this help.`);
+}
+
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+
+    const args = [HF_DOCTOR_SCRIPT, ...(options.skipRemote ? ['--skip-remote'] : [])];
+    const result = runCommand(process.execPath, args, { timeoutMs: DOCTOR_TIMEOUT_MS });
+    const child = result.stdout ? parseJsonPayload(result.stdout, 'doctor:hf-space') : {};
+    const ok = result.ok && child.ok !== false;
+    printJson({
+        ok,
+        profile: 'local-and-hf-space',
+        checks: child.checks || [],
+        nextActions: child.nextActions || [],
+        ...(ok ? {} : { error: child.error || result.stderr || result.error || 'doctor failed' })
+    });
+    if (!ok) process.exit(1);
+}
+
+try {
+    if (isMainModule(import.meta.url, process.argv[1])) main();
+} catch (error) {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+}

scripts/env-utils.mjs

@@ -0,0 +1,15 @@
+export function readPositiveIntegerEnv(name, defaultValue, minValue = 1) {
+    const rawValue = process.env[name]?.trim();
+    if (!rawValue) return defaultValue;
+    if (!/^\d+$/.test(rawValue)) {
+        throw new Error(`${name} must be a positive integer formatted as digits`);
+    }
+    const value = Number.parseInt(rawValue, 10);
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`${name} must be a safe integer <= ${Number.MAX_SAFE_INTEGER}`);
+    }
+    if (value < minValue) {
+        throw new Error(`${name} must be a positive integer greater than or equal to ${minValue}`);
+    }
+    return value;
+}

scripts/env-utils.test.mjs

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { afterEach, describe, it } from 'node:test';
+
+import { readPositiveIntegerEnv } from './env-utils.mjs';
+
+const TEST_ENV_NAME = 'GPT_IMAGE_PLAYGROUND_TEST_INTEGER';
+
+afterEach(() => {
+    delete process.env[TEST_ENV_NAME];
+});
+
+describe('Environment utilities', () => {
+    it('returns the default value when the env var is unset', () => {
+        assert.equal(readPositiveIntegerEnv(TEST_ENV_NAME, 30), 30);
+    });
+
+    it('returns valid integer env values', () => {
+        process.env[TEST_ENV_NAME] = '42';
+
+        assert.equal(readPositiveIntegerEnv(TEST_ENV_NAME, 30), 42);
+    });
+
+    it('accepts values exactly equal to the configured minimum', () => {
+        process.env[TEST_ENV_NAME] = '1000';
+
+        assert.equal(readPositiveIntegerEnv(TEST_ENV_NAME, 30, 1000), 1000);
+    });
+
+    it('accepts zero when the configured minimum is zero', () => {
+        process.env[TEST_ENV_NAME] = '0';
+
+        assert.equal(readPositiveIntegerEnv(TEST_ENV_NAME, 30, 0), 0);
+    });
+
+    it('rejects non-digit values before parsing', () => {
+        process.env[TEST_ENV_NAME] = '12ms';
+
+        assert.throws(() => readPositiveIntegerEnv(TEST_ENV_NAME, 30), /formatted as digits/);
+    });
+
+    it('rejects values below the configured minimum', () => {
+        process.env[TEST_ENV_NAME] = '999';
+
+        assert.throws(() => readPositiveIntegerEnv(TEST_ENV_NAME, 30, 1000), /greater than or equal to 1000/);
+    });
+
+    it('rejects integers that exceed JavaScript safe integer range', () => {
+        process.env[TEST_ENV_NAME] = String(Number.MAX_SAFE_INTEGER + 1);
+
+        assert.throws(() => readPositiveIntegerEnv(TEST_ENV_NAME, 30), /safe integer/);
+    });
+});

scripts/hf-space-doctor-utils.mjs

@@ -1,9 +1,10 @@
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-export const DEFAULT_ACCESS_FILE = join(process.env.HOME || '', '.cache/gpt-image-playground-customer/hf-space-access.txt');
+export const HF_SPACE_ID = 'misonL/gpt-image-playground-customer';
+export const HF_SPACE_URL = 'https://misonl-gpt-image-playground-customer.hf.space';
+const DOCTOR_COMMAND_TIMEOUT_MS = 30_000;
 
 export function readEnvValue(name) {
     return process.env[name]?.trim() || undefined;
@@ -34,12 +35,16 @@ export function assertKnownOptions(argv, knownOptions) {
     }
 }
 
-export function runCommand(command, args = []) {
+export function runDoctorCommand(command, args = [], options = {}) {
     const result = spawnSync(command, args, {
         encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe']
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: options.timeoutMs || DOCTOR_COMMAND_TIMEOUT_MS
     });
-    if (result.error) return { ok: false, error: result.error.message };
+    if (result.error) {
+        const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+        return { ok: false, error: output ? `${result.error.message}\n${output}` : result.error.message };
+    }
     if (result.status !== 0) {
         const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
         return { ok: false, error: output || `${command} ${args.join(' ')} failed` };
@@ -47,20 +52,6 @@ export function runCommand(command, args = []) {
     return { ok: true, stdout: result.stdout.trim() };
 }
 
-export function parseAccessFile(accessFile) {
-    const values = new Map();
-    const text = readFileSync(accessFile, 'utf8');
-    for (const rawLine of text.split(/\r?\n/)) {
-        if (!rawLine || rawLine.startsWith('#')) continue;
-        const separatorIndex = rawLine.indexOf('=');
-        if (separatorIndex <= 0) continue;
-        const key = rawLine.slice(0, separatorIndex).trim();
-        const value = rawLine.slice(separatorIndex + 1);
-        if (key) values.set(key, value);
-    }
-    return values;
-}
-
 export function getJsonNames(text) {
     const parsed = JSON.parse(extractJsonPayload(text));
     const names = new Set();
@@ -78,6 +69,23 @@ export function getJsonNames(text) {
     return names;
 }
 
+export function getJsonKeyValues(text) {
+    const parsed = JSON.parse(extractJsonPayload(text));
+    const values = new Map();
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value) visit(item);
+            return;
+        }
+        if (!value || typeof value !== 'object') return;
+        if (typeof value.key === 'string' && typeof value.value === 'string') {
+            values.set(value.key, value.value);
+        }
+    };
+    visit(parsed);
+    return values;
+}
+
 function extractJsonPayload(text) {
     const trimmedText = text.trim();
     if (!trimmedText) return '[]';
@@ -108,16 +116,9 @@ const NEXT_ACTIONS = new Map([
     ['hf-cli', 'Install the Hugging Face CLI from the official documentation; avoid piping remote install scripts directly to a shell.'],
     ['hf-auth', 'Check network/proxy access to Hugging Face, then run hf auth login if the token is missing or expired.'],
     ['node-modules', 'Run npm install.'],
-    [
-        'access-file-keys',
-        'Regenerate or update the access file with npm run init-access:hf-space -- --space-id <namespace>/<space-name> --space-url https://<user>-<space>.hf.space'
-    ],
-    [
-        'generated-secrets',
-        'Regenerate weak or blank project secrets with npm run init-access:hf-space -- --space-id <namespace>/<space-name> --space-url https://<user>-<space>.hf.space --force'
-    ],
-    ['remote-variables', 'Configure the required and recommended Space Variables in Hugging Face Settings before syncing secrets.'],
-    ['remote-secrets', 'Run npm run sync-secret:hf-space after hf auth login succeeds.'],
+    ['remote-variables', 'Configure the required and recommended Space Variables with hf spaces variables add.'],
+    ['remote-variable-values', 'Set required Space Variable values with hf spaces variables add.'],
+    ['remote-secrets', 'Configure required Space Secrets with hf spaces secrets add.'],
     ['remote-generation-secret', 'Configure OPENAI_API_KEY or OPENAI_CHANNEL_1_API_KEYS in Space Secrets before real image generation.']
 ]);
 
@@ -133,8 +134,20 @@ export function buildNextActions(checks) {
 }
 
 export function validateSpaceId(spaceId) {
-    if (!spaceId?.trim()) return 'HF Space id is required.';
-    if (!/^[^/\s]+\/[^/\s]+$/.test(spaceId)) return 'HF Space id must use namespace/space format.';
+    const text = spaceId?.trim();
+    if (!text) return 'HF Space id is required.';
+    const parts = text.split('/');
+    if (parts.length < 1 || parts.length > 2 || parts.some((part) => part.length === 0)) {
+        return 'HF Space id must use space_name or namespace/space_name format with 1-96 characters per part.';
+    }
+    for (const part of parts) {
+        if (part.length > 96 || !/^[A-Za-z0-9._-]+$/.test(part)) {
+            return 'HF Space id must use space_name or namespace/space_name format with 1-96 characters per part.';
+        }
+        if (part.startsWith('.') || part.includes('..') || part.includes('--') || part.endsWith('.git')) {
+            return 'HF Space id parts cannot start with ".", contain ".." or "--", or end with ".git".';
+        }
+    }
     return undefined;
 }
 

scripts/hf-space-doctor-utils.test.mjs

@@ -8,9 +8,11 @@ import {
     assertSpaceTargetConfig,
     buildNextActions,
     classifyRequiredAndRecommendedNames,
+    getJsonKeyValues,
     getJsonNames,
     isMainModule,
     readOptionValue,
+    runDoctorCommand,
     validateSpaceId,
     validateSpaceUrl
 } from './hf-space-doctor-utils.mjs';
@@ -38,6 +40,20 @@ describe('HF Space doctor utilities', () => {
         assert.deepEqual([...names], ['OPENAI_API_KEY']);
     });
 
+    it('parses hf CLI variable values after hint lines', () => {
+        const values = getJsonKeyValues(
+            [
+                'Hint: Use `hf spaces variables add user/space -e KEY=VALUE` to add variables.',
+                '[{"key":"AGENT_STATE_BACKEND","value":"memory"},{"key":"NEXT_PUBLIC_IMAGE_STORAGE_MODE","value":"indexeddb"}]'
+            ].join('\n')
+        );
+
+        assert.deepEqual([...values], [
+            ['AGENT_STATE_BACKEND', 'memory'],
+            ['NEXT_PUBLIC_IMAGE_STORAGE_MODE', 'indexeddb']
+        ]);
+    });
+
     it('keeps auth remediation broad enough for network and token failures', () => {
         const actions = buildNextActions([
             {
@@ -76,8 +92,13 @@ describe('HF Space doctor utilities', () => {
 
     it('validates Hugging Face Space target config consistently', () => {
         assert.equal(validateSpaceId('example/demo'), undefined);
+        assert.equal(validateSpaceId('demo'), undefined);
         assert.equal(validateSpaceUrl('https://example-demo.hf.space'), undefined);
-        assert.match(validateSpaceId('bad'), /namespace\/space/);
+        assert.match(validateSpaceId('a/b/c'), /space_name or namespace\/space_name/);
+        assert.match(validateSpaceId('.bad/demo'), /cannot start/);
+        assert.match(validateSpaceId('bad--name/demo'), /cannot start/);
+        assert.match(validateSpaceId('bad.git/demo'), /cannot start/);
+        assert.match(validateSpaceId(`${'a'.repeat(97)}/demo`), /1-96 characters/);
         assert.match(validateSpaceUrl('https://example.com'), /\.hf\.space/);
         assert.match(validateSpaceUrl('https://user:pass@example-demo.hf.space'), /plain Space origin/);
         assert.match(validateSpaceUrl('https://example-demo.hf.space/share/abc'), /plain Space origin/);
@@ -93,9 +114,15 @@ describe('HF Space doctor utilities', () => {
     });
 
     it('rejects unknown CLI options and blank inline option values', () => {
-        assert.doesNotThrow(() => assertKnownOptions(['--access-file', 'tmp.txt'], ['--access-file']));
-        assert.doesNotThrow(() => assertKnownOptions(['--access-file=tmp.txt'], ['--access-file']));
-        assert.throws(() => assertKnownOptions(['--unknown'], ['--access-file']), /Unknown option/);
+        assert.doesNotThrow(() => assertKnownOptions(['--skip-remote'], ['--skip-remote']));
+        assert.throws(() => assertKnownOptions(['--unknown'], ['--skip-remote']), /Unknown option/);
         assert.throws(() => readOptionValue(['--space-id='], '--space-id'), /requires a value/);
     });
+
+    it('times out direct doctor commands instead of hanging', () => {
+        const result = runDoctorCommand(process.execPath, ['-e', 'setTimeout(() => {}, 1000)'], { timeoutMs: 100 });
+
+        assert.equal(result.ok, false);
+        assert.match(result.error, /timed out|ETIMEDOUT|SIGTERM/i);
+    });
 });

scripts/keepalive-hf-space.mjs

@@ -1,25 +1,11 @@
 #!/usr/bin/env node
 
+import { readPositiveIntegerEnv } from './env-utils.mjs';
 import { validateSpaceUrl } from './hf-space-doctor-utils.mjs';
 
 const DEFAULT_SPACE_URL = 'https://misonl-gpt-image-playground-customer.hf.space';
 const DEFAULT_KEEPALIVE_PATH = '/api/auth-status';
 const DEFAULT_TIMEOUT_MS = 30_000;
-const MIN_TIMEOUT_MS = 1_000;
-
-function readPositiveIntegerEnv(name, fallback) {
-    const rawValue = process.env[name]?.trim();
-    if (!rawValue) return fallback;
-    if (!/^\d+$/.test(rawValue)) {
-        throw new Error(`${name} must be an integer greater than or equal to ${MIN_TIMEOUT_MS}`);
-    }
-    const value = Number(rawValue);
-    if (!Number.isSafeInteger(value) || value < MIN_TIMEOUT_MS) {
-        throw new Error(`${name} must be an integer greater than or equal to ${MIN_TIMEOUT_MS}`);
-    }
-    return value;
-}
-
 function normalizeUrl(rawUrl, path) {
     const urlError = validateSpaceUrl(rawUrl);
     if (urlError) {
@@ -51,7 +37,7 @@ async function readJsonResponse(response) {
 async function pingKeepaliveEndpoint() {
     const spaceUrl = process.env.HF_SPACE_KEEPALIVE_URL?.trim() || DEFAULT_SPACE_URL;
     const path = process.env.HF_SPACE_KEEPALIVE_PATH?.trim() || DEFAULT_KEEPALIVE_PATH;
-    const timeoutMs = readPositiveIntegerEnv('HF_SPACE_KEEPALIVE_TIMEOUT_MS', DEFAULT_TIMEOUT_MS);
+    const timeoutMs = readPositiveIntegerEnv('HF_SPACE_KEEPALIVE_TIMEOUT_MS', DEFAULT_TIMEOUT_MS, 1_000);
     const expectedPasswordRequired = readExpectedPasswordRequired();
     const url = normalizeUrl(spaceUrl, path);
     const controller = new AbortController();

scripts/local-image-upstream-fixture.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+import http from 'node:http';
+import { pathToFileURL } from 'node:url';
+
+export const FIXTURE_IMAGE_BASE64 =
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
+export const MAX_JSON_BODY_BYTES = 1024 * 1024;
+
+class PayloadTooLargeError extends Error {
+    constructor() {
+        super('Request body too large');
+        this.name = 'PayloadTooLargeError';
+        this.status = 413;
+    }
+}
+
+function readJsonBody(request) {
+    return new Promise((resolve, reject) => {
+        let raw = '';
+        let byteLength = 0;
+        let tooLarge = false;
+        let settled = false;
+        const cleanup = () => {
+            request.off('data', onData);
+            request.off('end', onEnd);
+            request.off('error', onError);
+        };
+        const fail = (error) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            byteLength += Buffer.byteLength(chunk, 'utf8');
+            if (byteLength > MAX_JSON_BODY_BYTES) {
+                tooLarge = true;
+                return;
+            }
+            if (tooLarge) return;
+            raw += chunk;
+        };
+        const onEnd = () => {
+            if (tooLarge) {
+                fail(new PayloadTooLargeError());
+                return;
+            }
+            if (!raw.trim()) {
+                finish({});
+                return;
+            }
+            try {
+                finish(JSON.parse(raw));
+            } catch (error) {
+                fail(error);
+            }
+        };
+        const onError = (error) => fail(error);
+        request.setEncoding('utf8');
+        request.on('data', onData);
+        request.on('end', onEnd);
+        request.on('error', onError);
+    });
+}
+
+function sendJson(response, status, body) {
+    response.writeHead(status, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify(body));
+}
+
+function writeSse(response, event, payload) {
+    if (event) response.write(`event: ${event}\n`);
+    response.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+
+function sendImagesStream(response) {
+    response.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive'
+    });
+    response.write(': keepalive\n\n');
+    writeSse(response, 'image_generation.partial_image', {
+        type: 'image_generation.partial_image',
+        partial_image_index: 0,
+        b64_json: FIXTURE_IMAGE_BASE64
+    });
+    writeSse(response, 'image_generation.completed', {
+        type: 'image_generation.completed',
+        b64_json: FIXTURE_IMAGE_BASE64,
+        output_format: 'png',
+        size: '1024x1024',
+        quality: 'low'
+    });
+    response.end('data: [DONE]\n\n');
+}
+
+function sendResponsesStream(response) {
+    response.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive'
+    });
+    writeSse(response, 'response.image_generation_call.partial_image', {
+        type: 'response.image_generation_call.partial_image',
+        partial_image_b64: FIXTURE_IMAGE_BASE64,
+        partial_image_index: 0
+    });
+    writeSse(response, 'response.output_item.done', {
+        type: 'response.output_item.done',
+        item: {
+            id: 'ig_fixture',
+            type: 'image_generation_call',
+            status: 'completed',
+            result: FIXTURE_IMAGE_BASE64
+        }
+    });
+    writeSse(response, 'response.completed', {
+        type: 'response.completed',
+        response: {
+            output: [{ id: 'ig_fixture', type: 'image_generation_call', status: 'completed', result: FIXTURE_IMAGE_BASE64 }]
+        }
+    });
+    response.end('data: [DONE]\n\n');
+}
+
+function imagesResponse(body) {
+    const created = Math.floor(Date.now() / 1000);
+    return {
+        created,
+        data: [{ b64_json: FIXTURE_IMAGE_BASE64 }],
+        usage: {
+            input_tokens: 1,
+            output_tokens: 1,
+            total_tokens: 2
+        },
+        fixture_request: {
+            model: typeof body.model === 'string' ? body.model : undefined,
+            stream: body.stream === true
+        }
+    };
+}
+
+function responsesJsonResponse(body) {
+    return {
+        id: 'resp_fixture',
+        object: 'response',
+        model: typeof body.model === 'string' ? body.model : 'gpt-5.4',
+        output: [{ id: 'ig_fixture', type: 'image_generation_call', status: 'completed', result: FIXTURE_IMAGE_BASE64 }],
+        usage: {
+            input_tokens: 1,
+            output_tokens: 1,
+            total_tokens: 2
+        }
+    };
+}
+
+function modelsResponse() {
+    return {
+        object: 'list',
+        data: [
+            { id: 'gpt-image-2', object: 'model', owned_by: 'fixture' },
+            { id: 'gpt-5.4', object: 'model', owned_by: 'fixture' }
+        ]
+    };
+}
+
+async function handleRequest(request, response) {
+    const url = new URL(request.url || '/', 'http://fixture.local');
+    if (request.method === 'GET' && url.pathname === '/health') {
+        sendJson(response, 200, { ok: true });
+        return;
+    }
+    if (request.method === 'GET' && url.pathname === '/v1/models') {
+        sendJson(response, 200, modelsResponse());
+        return;
+    }
+    if (request.method === 'POST' && url.pathname === '/v1/images/generations') {
+        const body = await readJsonBody(request);
+        if (body.stream === true) {
+            sendImagesStream(response);
+            return;
+        }
+        sendJson(response, 200, imagesResponse(body));
+        return;
+    }
+    if (request.method === 'POST' && url.pathname === '/v1/responses') {
+        const body = await readJsonBody(request);
+        if (body.stream === true) {
+            sendResponsesStream(response);
+            return;
+        }
+        sendJson(response, 200, responsesJsonResponse(body));
+        return;
+    }
+    sendJson(response, 404, { error: { message: `No fixture route for ${request.method} ${url.pathname}` } });
+}
+
+export function createFixtureServer() {
+    return http.createServer((request, response) => {
+        handleRequest(request, response).catch((error) => {
+            const status = error instanceof PayloadTooLargeError ? error.status : 500;
+            sendJson(response, status, { error: { message: error instanceof Error ? error.message : String(error) } });
+        });
+    });
+}
+
+export function startFixtureServer(port = Number(process.env.PORT || 19080), host = process.env.HOST || '127.0.0.1') {
+    const server = createFixtureServer();
+    server.listen(port, host, () => {
+        const address = server.address();
+        const resolvedPort = typeof address === 'object' && address ? address.port : port;
+        console.log(`local image upstream fixture listening on http://${host}:${resolvedPort}`);
+    });
+    return server;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+    startFixtureServer();
+}

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

@@ -0,0 +1,199 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { FIXTURE_IMAGE_BASE64, MAX_JSON_BODY_BYTES, createFixtureServer } from './local-image-upstream-fixture.mjs';
+
+describe('local image upstream fixture', () => {
+    it('serves Images API JSON responses', async () => {
+        const fixture = await startFixture();
+        try {
+            const response = await fetch(`${fixture.baseUrl}/v1/images/generations`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: 'gpt-image-2', prompt: 'fixture json smoke', stream: false })
+            });
+
+            assert.equal(response.status, 200);
+            assert.match(response.headers.get('content-type') || '', /^application\/json\b/);
+            const body = await response.json();
+            assert.equal(body.data[0].b64_json, FIXTURE_IMAGE_BASE64);
+            assert.equal(body.fixture_request.model, 'gpt-image-2');
+            assert.equal(body.fixture_request.stream, false);
+        } finally {
+            await fixture.close();
+        }
+    });
+
+    it('serves Images API SSE responses', async () => {
+        const fixture = await startFixture();
+        try {
+            const response = await fetch(`${fixture.baseUrl}/v1/images/generations`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: 'gpt-image-2', prompt: 'fixture sse smoke', stream: true })
+            });
+
+            assert.equal(response.status, 200);
+            assert.match(response.headers.get('content-type') || '', /^text\/event-stream\b/);
+            const events = readSseEvents(await response.text());
+            assert.equal(events[0].comment, 'keepalive');
+            assert.deepEqual(
+                events.filter((event) => event.event).map((event) => event.event),
+                ['image_generation.partial_image', 'image_generation.completed']
+            );
+            assert.equal(events[1].data.type, 'image_generation.partial_image');
+            assert.equal(events[1].data.b64_json, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[2].data.type, 'image_generation.completed');
+            assert.equal(events[2].data.b64_json, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[3].done, true);
+        } finally {
+            await fixture.close();
+        }
+    });
+
+    it('serves Responses API JSON image outputs', async () => {
+        const fixture = await startFixture();
+        try {
+            const response = await fetch(`${fixture.baseUrl}/v1/responses`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: 'gpt-5.4',
+                    input: 'fixture responses json smoke',
+                    stream: false,
+                    tools: [{ type: 'image_generation' }],
+                    tool_choice: { type: 'image_generation' }
+                })
+            });
+
+            assert.equal(response.status, 200);
+            assert.match(response.headers.get('content-type') || '', /^application\/json\b/);
+            const body = await response.json();
+            assert.equal(body.id, 'resp_fixture');
+            assert.equal(body.output[0].type, 'image_generation_call');
+            assert.equal(body.output[0].result, FIXTURE_IMAGE_BASE64);
+        } finally {
+            await fixture.close();
+        }
+    });
+
+    it('serves Responses API SSE image events', async () => {
+        const fixture = await startFixture();
+        try {
+            const response = await fetch(`${fixture.baseUrl}/v1/responses`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: 'gpt-5.4',
+                    input: 'fixture responses sse smoke',
+                    stream: true,
+                    tools: [{ type: 'image_generation' }],
+                    tool_choice: { type: 'image_generation' }
+                })
+            });
+
+            assert.equal(response.status, 200);
+            assert.match(response.headers.get('content-type') || '', /^text\/event-stream\b/);
+            const events = readSseEvents(await response.text());
+            assert.deepEqual(
+                events.filter((event) => event.event).map((event) => event.event),
+                [
+                    'response.image_generation_call.partial_image',
+                    'response.output_item.done',
+                    'response.completed'
+                ]
+            );
+            assert.equal(events[0].data.partial_image_b64, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[1].data.item.type, 'image_generation_call');
+            assert.equal(events[1].data.item.result, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[2].data.response.output[0].result, FIXTURE_IMAGE_BASE64);
+            assert.equal(events[3].done, true);
+        } finally {
+            await fixture.close();
+        }
+    });
+
+    it('serves model discovery and health checks', async () => {
+        const fixture = await startFixture();
+        try {
+            const healthResponse = await fetch(`${fixture.baseUrl}/health`);
+            const modelsResponse = await fetch(`${fixture.baseUrl}/v1/models`);
+
+            assert.equal(healthResponse.status, 200);
+            assert.deepEqual(await healthResponse.json(), { ok: true });
+            assert.equal(modelsResponse.status, 200);
+            const models = await modelsResponse.json();
+            assert.deepEqual(
+                models.data.map((model) => model.id),
+                ['gpt-image-2', 'gpt-5.4']
+            );
+        } finally {
+            await fixture.close();
+        }
+    });
+
+    it('rejects oversized JSON request bodies', async () => {
+        const fixture = await startFixture();
+        try {
+            const response = await fetch(`${fixture.baseUrl}/v1/images/generations`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: 'gpt-image-2',
+                    prompt: 'x'.repeat(MAX_JSON_BODY_BYTES)
+                })
+            });
+
+            assert.equal(response.status, 413);
+            const body = await response.json();
+            assert.match(body.error.message, /too large/);
+        } finally {
+            await fixture.close();
+        }
+    });
+});
+
+async function startFixture() {
+    const server = createFixtureServer();
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}`,
+        close: () => closeServer(server)
+    };
+}
+
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) reject(error);
+            else resolve();
+        });
+    });
+}
+
+function readSseEvents(raw) {
+    return raw
+        .trim()
+        .split(/\n\n+/)
+        .map((chunk) => readSseEvent(chunk))
+        .filter(Boolean);
+}
+
+function readSseEvent(chunk) {
+    const lines = chunk.split(/\n/);
+    const comment = lines.find((line) => line.startsWith(': '));
+    const event = lines.find((line) => line.startsWith('event: '));
+    const data = lines.find((line) => line.startsWith('data: '));
+    if (comment) return { comment: comment.slice(2) };
+    if (!data) return undefined;
+    if (data === 'data: [DONE]') return { done: true };
+    return {
+        event: event ? event.slice('event: '.length) : undefined,
+        data: JSON.parse(data.slice('data: '.length))
+    };
+}

scripts/smoke-hf-space-memory.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 
+import { readPositiveIntegerEnv } from './env-utils.mjs';
+
 const imageName = process.env.HF_SPACE_SMOKE_IMAGE || 'gpt-image-playground:hf-space-memory-smoke';
 const containerName = process.env.HF_SPACE_SMOKE_CONTAINER || 'gpt-image-playground-hf-space-smoke';
 const hostPort = process.env.HF_SPACE_SMOKE_PORT || '4785';
 const token = process.env.HF_SPACE_SMOKE_AGENT_TOKEN || 'hf-space-smoke-token';
 const baseUrl = `http://127.0.0.1:${hostPort}`;
+const readyTimeoutMs = readPositiveIntegerEnv('HF_SPACE_SMOKE_READY_TIMEOUT_MS', 45_000);
 
 function run(command, args, options = {}) {
   const result = spawnSync(command, args, {
@@ -36,7 +39,7 @@ async function fetchJson(path, options = {}) {
 }
 
 async function waitForReady() {
-  const deadline = Date.now() + 45_000;
+  const deadline = Date.now() + readyTimeoutMs;
   let lastError;
   while (Date.now() < deadline) {
     try {

scripts/smoke-hf-space-memory.test.mjs

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const scriptPath = join(repoRoot, 'scripts/smoke-hf-space-memory.mjs');
+
+describe('HF Space memory smoke script validation', () => {
+  it('rejects invalid ready timeout values before Docker access', () => {
+    const result = spawnSync(process.execPath, [scriptPath], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      env: { ...process.env, HF_SPACE_SMOKE_READY_TIMEOUT_MS: '45s' }
+    });
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /HF_SPACE_SMOKE_READY_TIMEOUT_MS/);
+    assert.match(result.stderr, /positive integer/);
+    assert.equal(result.stdout.trim(), '');
+  });
+});

scripts/smoke-image-upstream-compat.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import http from 'node:http';
+const PNG_BASE64 =
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
+const originalEnv = { ...process.env };
+function restoreProcessEnv() {
+    for (const key of Object.keys(process.env)) {
+        if (!(key in originalEnv)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(originalEnv)) process.env[key] = value;
+}
+function configureRouteEnv() {
+    for (const key of [
+        'APP_PASSWORD',
+        'OPENAI_API_KEY',
+        'OPENAI_API_BASE_URL',
+        'OPENAI_CHANNEL_1_API_KEYS',
+        'OPENAI_CHANNEL_1_BASE_URL',
+        'IMAGE_GENERATION_BACKEND',
+        'IMAGE_STREAMING_STRATEGY'
+    ]) {
+        delete process.env[key];
+    }
+    process.env.APP_LOG_LEVEL = 'warn';
+    process.env.NEXT_PUBLIC_IMAGE_STORAGE_MODE = 'indexeddb';
+    process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+    process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+}
+function imageRequest(input) {
+    const formData = new FormData();
+    for (const [key, value] of Object.entries({
+        mode: 'generate',
+        prompt: input.prompt || 'local image upstream compatibility smoke',
+        model: 'gpt-image-2',
+        n: '1',
+        size: '1024x1024',
+        quality: 'high',
+        output_format: 'png',
+        apiBaseUrl: input.apiBaseUrl,
+        apiKey: 'local-smoke-key',
+        clientRequestId: input.clientRequestId || 'image-upstream-compat-smoke'
+    })) {
+        formData.append(key, value);
+    }
+    if (input.imageBackend) formData.append('imageBackend', input.imageBackend);
+    if (input.imageStreamingStrategy) formData.append('imageStreamingStrategy', input.imageStreamingStrategy);
+    if (input.responsesModel) formData.append('responsesModel', input.responsesModel);
+    if (input.stream) {
+        formData.append('stream', 'true');
+        formData.append('partial_images', '2');
+    }
+    return new Request('http://localhost/api/images', { method: 'POST', body: formData });
+}
+async function readBody(request) {
+    const chunks = [];
+    for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function sendJson(response, status, payload) {
+    response.writeHead(status, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify(payload));
+}
+function sendSse(response, events) {
+    response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    for (const event of events) {
+        if (event.comment) response.write(`: ${event.comment}\n\n`);
+        if (event.event) response.write(`event: ${event.event}\n`);
+        if ('data' in event) response.write(`data: ${JSON.stringify(event.data)}\n\n`);
+    }
+    response.write('data: [DONE]\n\n');
+    response.end();
+}
+function costLogResponse() {
+    const now = Math.floor(Date.now() / 1000);
+    return {
+        success: true,
+        data: [{ id: now, type: 2, model_name: 'gpt-image-2', quota: 3750, created_at: now, request_id: 'local-smoke' }]
+    };
+}
+async function startMockUpstream(handler) {
+    const calls = [];
+    const server = http.createServer(async (request, response) => {
+        try {
+            if (request.method === 'GET' && request.url === '/api/log/token') {
+                sendJson(response, 200, costLogResponse());
+                return;
+            }
+            const body = await readBody(request);
+            calls.push({ method: request.method, url: request.url, body });
+            await handler({ body, request, response });
+        } catch (error) {
+            sendJson(response, 500, { error: { message: error instanceof Error ? error.message : String(error) } });
+        }
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        calls,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+function assertPath(request, expectedPath) {
+    assert.equal(request.method, 'POST');
+    assert.equal(request.url?.endsWith(expectedPath), true);
+}
+async function readJsonImage(response) {
+    assert.equal(response.status, 200);
+    assert.match(response.headers.get('content-type') || '', /application\/json/);
+    const body = await response.json();
+    assert.equal(Array.isArray(body.images), true);
+    assert.equal(body.images.length, 1);
+    assert.equal(body.images[0].b64_json, PNG_BASE64);
+    return body;
+}
+async function readSseImages(response, expectedTypes) {
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get('content-type'), 'text/event-stream');
+    const events = (await response.text())
+        .split('\n\n')
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith('data: ') && part !== 'data: [DONE]')
+        .map((part) => JSON.parse(part.slice('data: '.length)));
+    assert.deepEqual(
+        events.map((event) => event.type),
+        expectedTypes
+    );
+    const done = events.at(-1);
+    assert.equal(done?.type, 'done');
+    assert.equal(done.images.length, 1);
+    assert.equal(done.images[0].b64_json, PNG_BASE64);
+    return events;
+}
+function completedImageEvent(type, data) {
+    return { event: type, data: { type, ...data } };
+}
+function responsesOutputItemDone(result) {
+    return {
+        event: 'response.output_item.done',
+        data: { type: 'response.output_item.done', item: { type: 'image_generation_call', status: 'completed', result } }
+    };
+}
+const cases = [
+    {
+        name: 'original new-api Images API JSON',
+        form: { stream: false, clientRequestId: 'smoke-images-json' },
+        handle: ({ body, request, response }) => {
+            assertPath(request, '/v1/images/generations');
+            assert.equal(JSON.parse(body).stream, false);
+            sendJson(response, 200, {
+                created: Math.floor(Date.now() / 1000),
+                data: [{ b64_json: PNG_BASE64 }],
+                usage: { input_tokens: 1, output_tokens: 2, total_tokens: 3 }
+            });
+        },
+        verify: async (response) => {
+            await readJsonImage(response);
+        }
+    },
+    {
+        name: 'sub2api Images API JSON',
+        form: { stream: false, clientRequestId: 'smoke-sub2api-images-json' },
+        handle: ({ body, request, response }) => {
+            assertPath(request, '/v1/images/generations');
+            const requestJson = JSON.parse(body);
+            assert.equal(requestJson.stream, false);
+            assert.equal(Object.hasOwn(requestJson, 'partial_images'), false);
+            sendJson(response, 200, {
+                created: Math.floor(Date.now() / 1000),
+                data: [{ b64_json: PNG_BASE64 }],
+                usage: { input_tokens: 1, output_tokens: 2, total_tokens: 3 }
+            });
+        },
+        verify: async (response) => {
+            await readJsonImage(response);
+        }
+    },
+    {
+        name: 'gaoren new-api Images SSE keepalive',
+        form: { stream: true, imageStreamingStrategy: 'newapi-keepalive-sse', clientRequestId: 'smoke-gaoren-keepalive' },
+        handle: ({ body, request, response }) => {
+            assertPath(request, '/v1/images/generations');
+            const requestJson = JSON.parse(body);
+            assert.equal(requestJson.stream, true);
+            assert.equal(requestJson.partial_images, 2);
+            sendSse(response, [
+                { comment: 'keepalive' },
+                completedImageEvent('image_generation.partial_image', {
+                    b64_json: 'gaoren-partial-base64',
+                    partial_image_index: 0
+                }),
+                completedImageEvent('image_generation.completed', { b64_json: PNG_BASE64 })
+            ]);
+        },
+        verify: async (response) => {
+            const events = await readSseImages(response, ['partial_image', 'completed', 'done']);
+            assert.equal(events[0].b64_json, 'gaoren-partial-base64');
+        }
+    },
+    {
+        name: 'gaoren new-api JSON-as-SSE completed event',
+        form: { stream: true, imageStreamingStrategy: 'newapi-keepalive-sse', clientRequestId: 'smoke-gaoren-json-as-sse' },
+        handle: ({ request, response }) => {
+            assertPath(request, '/v1/images/generations');
+            sendSse(response, [completedImageEvent('image_generation.completed', { data: [{ b64_json: PNG_BASE64 }] })]);
+        },
+        verify: async (response) => {
+            await readSseImages(response, ['completed', 'done']);
+        }
+    },
+    {
+        name: 'sub2api Images SSE',
+        form: { stream: true, imageStreamingStrategy: 'openai-sse', clientRequestId: 'smoke-sub2api-images-sse' },
+        handle: ({ request, response }) => {
+            assertPath(request, '/v1/images/generations');
+            sendSse(response, [
+                { event: 'image.generation.chunk', data: { b64_json: 'sub2api-partial-base64' } },
+                { event: 'image.generation.result', data: { data: [{ b64_json: PNG_BASE64 }] } }
+            ]);
+        },
+        verify: async (response) => {
+            const events = await readSseImages(response, ['partial_image', 'completed', 'done']);
+            assert.equal(events[0].b64_json, 'sub2api-partial-base64');
+        }
+    },
+    {
+        name: 'sub2api Responses image_generation bridge JSON',
+        form: {
+            stream: false,
+            imageBackend: 'responses-image-generation',
+            responsesModel: 'gpt-5.4',
+            clientRequestId: 'smoke-responses-bridge-json'
+        },
+        handle: ({ body, request, response }) => {
+            assertPath(request, '/v1/responses');
+            const requestJson = JSON.parse(body);
+            assert.equal(requestJson.model, 'gpt-5.4');
+            assert.equal(requestJson.stream, false);
+            assert.equal(requestJson.tool_choice.type, 'image_generation');
+            sendJson(response, 200, {
+                output: [{ type: 'image_generation_call', status: 'completed', result: PNG_BASE64 }],
+                usage: { input_tokens: 4, output_tokens: 5, total_tokens: 9 }
+            });
+        },
+        verify: async (response) => {
+            await readJsonImage(response);
+        }
+    },
+    {
+        name: 'GPT2Image Responses image_generation SSE',
+        form: {
+            stream: true,
+            imageBackend: 'responses',
+            imageStreamingStrategy: 'responses-sse',
+            responsesModel: 'gpt-5.4',
+            clientRequestId: 'smoke-gpt2image-responses-sse'
+        },
+        handle: ({ body, request, response }) => {
+            assertPath(request, '/v1/responses');
+            const requestJson = JSON.parse(body);
+            assert.equal(requestJson.stream, true);
+            assert.equal(requestJson.tools[0].partial_images, 2);
+            sendSse(response, [
+                completedImageEvent('response.image_generation_call.partial_image', {
+                    partial_image_b64: 'gpt2image-partial-base64',
+                    partial_image_index: 0
+                }),
+                completedImageEvent('response.image_generation_call.completed', { item_id: 'ig_smoke' }),
+                responsesOutputItemDone(`data:image/png;base64,${PNG_BASE64}`),
+                completedImageEvent('response.completed', {
+                    response: { output: [{ type: 'image_generation_call', status: 'completed', result: PNG_BASE64 }] }
+                })
+            ]);
+        },
+        verify: async (response) => {
+            const events = await readSseImages(response, ['partial_image', 'completed', 'done']);
+            assert.equal(events[0].b64_json, 'gpt2image-partial-base64');
+        }
+    }
+];
+
+async function runCase(POST, testCase) {
+    const upstream = await startMockUpstream(testCase.handle);
+    try {
+        const response = await POST(imageRequest({ ...testCase.form, apiBaseUrl: upstream.baseUrl }));
+        await testCase.verify(response, upstream.calls);
+        console.log(`[pass] ${testCase.name}`);
+    } finally {
+        await upstream.close();
+    }
+}
+
+async function main() {
+    configureRouteEnv();
+    const { POST } = await import('../src/app/api/images/route.ts');
+    try {
+        for (const testCase of cases) await runCase(POST, testCase);
+        console.log('image upstream compatibility mock smoke passed');
+    } finally {
+        restoreProcessEnv();
+    }
+}
+
+main().catch((error) => {
+    restoreProcessEnv();
+    console.error(error instanceof Error ? error.stack || error.message : String(error));
+    process.exit(1);
+});

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

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { commandFailureMessage, parseJsonPayload, printJson } from './command-center-utils.mjs';
+import { createFixtureServer } from './local-image-upstream-fixture.mjs';
+
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const REAL_SMOKE_SCRIPT = fileURLToPath(new URL('./smoke-image-upstream-real.mjs', import.meta.url));
+const DEFAULT_TIMEOUT_MS = 30_000;
+const LOCAL_FINAL_GATE_CASE_COUNT = 5;
+const LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS = 15_000;
+
+function parseArgs(argv) {
+    const parsed = { help: false, timeoutMs: DEFAULT_TIMEOUT_MS };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') parsed.help = true;
+        else if (arg === '--timeout-ms') parsed.timeoutMs = readTimeoutMs(readArgValue(argv, (index += 1), arg), arg);
+        else throw new Error(`未知参数：${arg}`);
+    }
+    return parsed;
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run smoke:image-upstream-local
+  npm run smoke:image-upstream-local -- --timeout-ms 30000
+
+Starts the local image upstream fixture and runs all five independent image upstream smoke cases through the real-smoke final gate. This is a local fixture gate, not proof that third-party upstream deployments are reachable.`);
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    const fixture = await startFixture();
+    try {
+        const result = await runLocalFinalGate(fixture.baseUrl, options.timeoutMs);
+        const report = parseJsonPayload(result.stdout, 'local image upstream final gate');
+        if (!result.ok) {
+            printJson({
+                ok: false,
+                local_fixture: true,
+                upstream_host: readHost(fixture.baseUrl),
+                report,
+                output: commandFailureMessage(result)
+            });
+            process.exit(1);
+        }
+        assertFinalGateReport(report);
+        printJson({
+            ok: true,
+            local_fixture: true,
+            upstream_host: readHost(fixture.baseUrl),
+            final_gate_satisfied: report.final_gate_satisfied,
+            independent_targets: report.independent_targets,
+            results: report.results.map(summarizeResult)
+        });
+    } finally {
+        await fixture.close();
+    }
+}
+
+function runLocalFinalGate(baseUrl, timeoutMs) {
+    return runCommandAsync(
+        process.execPath,
+        ['--import', 'tsx', REAL_SMOKE_SCRIPT, '--allow-billable', '--require-independent-targets', '--timeout-ms', String(timeoutMs)],
+        {
+            cwd: REPO_ROOT,
+            env: buildLocalFinalGateEnv(baseUrl, timeoutMs),
+            timeoutMs: timeoutMs * LOCAL_FINAL_GATE_CASE_COUNT + LOCAL_FINAL_GATE_PARENT_TIMEOUT_BUFFER_MS
+        }
+    );
+}
+
+function runCommandAsync(command, args, options = {}) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, options.timeoutMs);
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', (error) => {
+            clearTimeout(timeout);
+            resolve({
+                ok: false,
+                command,
+                args,
+                stdout,
+                stderr,
+                elapsed_ms: Date.now() - startedAt,
+                error: error.message
+            });
+        });
+        child.on('close', (status, signal) => {
+            clearTimeout(timeout);
+            resolve({
+                ok: status === 0,
+                command,
+                args,
+                status,
+                stdout,
+                stderr,
+                elapsed_ms: Date.now() - startedAt,
+                ...(signal ? { signal } : {}),
+                ...(timedOut ? { error: `timed out after ${options.timeoutMs}ms` } : {})
+            });
+        });
+    });
+}
+
+function buildLocalFinalGateEnv(baseUrl, timeoutMs) {
+    const env = stripSmokeEnv(process.env);
+    return {
+        ...env,
+        IMAGE_REAL_SMOKE_SKIP_DOTENV: '1',
+        IMAGE_REAL_SMOKE_TIMEOUT_MS: String(timeoutMs),
+        IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'local-fixture-key-original',
+        IMAGE_REAL_SMOKE_GAOREN_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_GAOREN_API_KEY: 'local-fixture-key-gaoren',
+        IMAGE_REAL_SMOKE_SUB2API_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_SUB2API_API_KEY: 'local-fixture-key-sub2api',
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY: 'local-fixture-key-sub2api-responses',
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL: 'gpt-5.4',
+        IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY: 'local-fixture-key-gpt2image',
+        IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL: 'gpt-5.4'
+    };
+}
+
+function stripSmokeEnv(source) {
+    const env = { ...source };
+    for (const key of Object.keys(env)) {
+        if (isSmokeEnvKey(key)) delete env[key];
+    }
+    return env;
+}
+
+function isSmokeEnvKey(key) {
+    return (
+        key.startsWith('IMAGE_REAL_SMOKE_') ||
+        key.startsWith('OPENAI_CHANNEL_') ||
+        key === 'OPENAI_API_BASE_URL' ||
+        key === 'OPENAI_API_KEY' ||
+        key === 'OPENAI_RESPONSES_API_MODEL' ||
+        key === 'OPENAI_ROUTING_STRATEGY' ||
+        key === 'OPENAI_CHANNELS_JSON' ||
+        key === 'IMAGE_OUTPUT_DIR' ||
+        key === 'APP_PASSWORD' ||
+        key === 'AGENT_API_TOKEN'
+    );
+}
+
+async function startFixture() {
+    const server = createFixtureServer();
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address !== 'object') throw new Error('local fixture did not expose a TCP address');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => closeServer(server)
+    };
+}
+
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) reject(error);
+            else resolve();
+        });
+    });
+}
+
+function assertFinalGateReport(report) {
+    if (report?.final_gate_satisfied !== true) throw new Error('local final gate did not satisfy final_gate_satisfied=true');
+    if (!Array.isArray(report.results) || report.results.length !== 5) {
+        throw new Error('local final gate did not run all five independent upstream cases');
+    }
+    const failed = report.results.find((item) => item.ok !== true || item.skipped === true);
+    if (failed) throw new Error(`local final gate case failed: ${failed.id || 'unknown'}`);
+}
+
+function summarizeResult(result) {
+    return {
+        id: result.id,
+        status: result.status,
+        content_type: result.content_type,
+        event_types: result.event_types,
+        image_count: result.image_count,
+        done_image_count: result.done_image_count,
+        first_b64_length: result.first_b64_length,
+        elapsed_ms: result.elapsed_ms
+    };
+}
+
+function readArgValue(argv, index, flag) {
+    const value = argv[index];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} 缺少参数值。`);
+    return value;
+}
+
+function readTimeoutMs(value, source) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1000) throw new Error(`${source} 必须是不小于 1000 的整数毫秒。`);
+    return parsed;
+}
+
+function readHost(value) {
+    try {
+        return new URL(value).host;
+    } catch {
+        return 'invalid-url';
+    }
+}
+
+main().catch((error) => {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+});

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

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const scriptPath = fileURLToPath(new URL('./smoke-image-upstream-local-final-gate.mjs', import.meta.url));
+
+describe('local image upstream final gate smoke launcher', () => {
+    it('runs all independent upstream cases against the local fixture', () => {
+        const result = spawnSync(process.execPath, [scriptPath, '--timeout-ms', '30000'], {
+            cwd: repoRoot,
+            encoding: 'utf8'
+        });
+
+        assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /local-fixture-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.local_fixture, true);
+        assert.equal(report.final_gate_satisfied, true);
+        assert.equal(report.independent_targets.configuration_complete, true);
+        assert.equal(report.results.length, 5);
+        assert.deepEqual(
+            report.results.map((item) => item.id),
+            [
+                'original-images-json',
+                'gaoren-images-sse',
+                'sub2api-images-sse',
+                'sub2api-responses-json',
+                'gpt2image-responses-sse'
+            ]
+        );
+        assert.equal(report.results.every((item) => item.status === 200), true);
+        assert.equal(report.results.every((item) => item.first_b64_length === 92), true);
+    });
+
+    it('prints help without starting the fixture', () => {
+        const result = spawnSync(process.execPath, [scriptPath, '--help'], {
+            cwd: repoRoot,
+            encoding: 'utf8'
+        });
+
+        assert.equal(result.status, 0);
+        assert.match(result.stdout, /smoke:image-upstream-local/);
+        assert.match(result.stdout, /local fixture gate/);
+    });
+});

scripts/smoke-image-upstream-real.mjs

@@ -0,0 +1,791 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+const originalEnv = { ...process.env };
+const CASES = [
+    { id: 'original-images-json', prefix: 'IMAGE_REAL_SMOKE_ORIGINAL', stream: false },
+    { id: 'gaoren-images-sse', prefix: 'IMAGE_REAL_SMOKE_GAOREN', stream: true, strategy: 'newapi-keepalive-sse' },
+    { id: 'sub2api-images-sse', prefix: 'IMAGE_REAL_SMOKE_SUB2API', stream: true, strategy: 'newapi-keepalive-sse' },
+    {
+        id: 'sub2api-responses-json',
+        prefix: 'IMAGE_REAL_SMOKE_SUB2API_RESPONSES',
+        fallbackPrefix: 'IMAGE_REAL_SMOKE_SUB2API',
+        stream: false,
+        backend: 'responses-image-generation'
+    },
+    {
+        id: 'gpt2image-responses-sse',
+        prefix: 'IMAGE_REAL_SMOKE_GPT2IMAGE',
+        stream: true,
+        strategy: 'responses-sse',
+        backend: 'responses-image-generation'
+    }
+];
+const SERVER_CHANNEL_CASES = [
+    { id: 'server-channel-images-json', prefix: 'IMAGE_REAL_SMOKE_SERVER', stream: false, serverChannel: true },
+    {
+        id: 'server-channel-images-sse',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: true,
+        strategy: 'newapi-keepalive-sse',
+        serverChannel: true
+    },
+    {
+        id: 'server-channel-responses-sse',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: true,
+        strategy: 'responses-sse',
+        backend: 'responses-image-generation',
+        serverChannel: true
+    },
+    {
+        id: 'server-channel-responses-json',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: false,
+        backend: 'responses-image-generation',
+        serverChannel: true
+    },
+    {
+        id: 'server-channel-agent-images-sse',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: true,
+        strategy: 'newapi-keepalive-sse',
+        serverChannel: true,
+        endpoint: 'agent-generate'
+    },
+    {
+        id: 'server-channel-agent-responses-sse',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: true,
+        strategy: 'responses-sse',
+        backend: 'responses-image-generation',
+        serverChannel: true,
+        endpoint: 'agent-generate'
+    }
+];
+
+const argv = process.argv.slice(2);
+let options;
+let exitCode = 0;
+let forceExitAfterReport = false;
+try {
+    if (!isHelpRequested(argv)) loadDotEnvFiles(argv);
+    options = parseArgs(argv);
+    if (options.help) {
+        printUsage();
+    } else {
+        configureRouteEnv();
+        const availableCases = options.includeServerChannel ? [...CASES, ...SERVER_CHANNEL_CASES] : CASES;
+        const selectedCases = availableCases.filter(
+            (testCase) => options.caseId === 'all' || testCase.id === options.caseId
+        );
+        if (selectedCases.length === 0) throw new Error(`未知真实 smoke 场景：${options.caseId}`);
+        const billablePreflight = buildBillablePreflight(selectedCases);
+        const results = [];
+        let routeHandlers;
+        for (const testCase of selectedCases) {
+            const loadHandlers = async () => {
+                routeHandlers ||= await loadRouteHandlers();
+                return routeHandlers;
+            };
+            const result = await runCase(loadHandlers, testCase, billablePreflight);
+            results.push(result);
+            if (result.timed_out) break;
+        }
+        const independentTargetSummary = buildIndependentTargetSummary(results, options.requireIndependentTargets);
+        const unselectedRequiredCases = options.requireIndependentTargets
+            ? independentTargetSummary?.unselected_required_cases || []
+            : [];
+        const invalidRequiredCases = options.requireIndependentTargets
+            ? independentTargetSummary?.invalid_cases || []
+            : [];
+        const blockedCases = results.filter((item) => item.blocked).map((item) => item.id);
+        const blockedRequiredCases = options.requireIndependentTargets
+            ? blockedCases.filter((id) => CASES.some((testCase) => testCase.id === id))
+            : [];
+        const skippedRequiredCases = options.requireIndependentTargets
+            ? results.filter((item) => item.skipped && !item.blocked && !item.server_channel).map((item) => item.id)
+            : [];
+        const missingRequiredCaseSet = new Set([...unselectedRequiredCases, ...skippedRequiredCases]);
+        const missingRequiredCases = CASES.map((testCase) => testCase.id).filter((id) =>
+            missingRequiredCaseSet.has(id)
+        );
+        const finalGateSatisfied = isFinalGateSatisfied(results, missingRequiredCases);
+        const report = {
+            ok:
+                results.every((item) => item.ok || item.skipped) &&
+                missingRequiredCases.length === 0 &&
+                invalidRequiredCases.length === 0,
+            billable: options.allowBillable,
+            final_gate_satisfied: finalGateSatisfied,
+            ...(independentTargetSummary ? { independent_targets: independentTargetSummary } : {}),
+            ...(unselectedRequiredCases.length > 0 ? { unselected_required_cases: unselectedRequiredCases } : {}),
+            ...(invalidRequiredCases.length > 0 ? { invalid_required_count: invalidRequiredCases.length } : {}),
+            ...(invalidRequiredCases.length > 0 ? { invalid_required_cases: invalidRequiredCases } : {}),
+            ...(blockedCases.length > 0 ? { blocked_count: blockedCases.length } : {}),
+            ...(blockedCases.length > 0 ? { blocked_cases: blockedCases } : {}),
+            ...(blockedRequiredCases.length > 0 ? { blocked_required_count: blockedRequiredCases.length } : {}),
+            ...(blockedRequiredCases.length > 0 ? { blocked_required_cases: blockedRequiredCases } : {}),
+            ...(skippedRequiredCases.length > 0 ? { skipped_required_cases: skippedRequiredCases } : {}),
+            ...(missingRequiredCases.length > 0 ? { missing_required_count: missingRequiredCases.length } : {}),
+            ...(missingRequiredCases.length > 0 ? { missing_required_cases: missingRequiredCases } : {}),
+            results
+        };
+        forceExitAfterReport = results.some((item) => item.timed_out);
+        await writeStdout(`${JSON.stringify(report, null, 2)}\n`);
+        exitCode = report.ok ? 0 : 1;
+    }
+} catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    exitCode = 1;
+} finally {
+    restoreProcessEnv();
+}
+if (forceExitAfterReport) {
+    process.exit(exitCode);
+}
+process.exitCode = exitCode;
+
+function writeStdout(text) {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(text, (error) => {
+            if (error) reject(error);
+            else resolve();
+        });
+    });
+}
+
+function isFinalGateSatisfied(results, missingRequiredCases) {
+    if (!options.requireIndependentTargets || !options.allowBillable || missingRequiredCases.length > 0) return false;
+    const passedIndependentCases = new Set(
+        results.filter((item) => !item.server_channel && !item.skipped && item.ok).map((item) => item.id)
+    );
+    return CASES.every((testCase) => passedIndependentCases.has(testCase.id));
+}
+
+function buildBillablePreflight(selectedCases) {
+    if (!options.allowBillable) return {};
+    if (selectedCases.some((testCase) => readInvalidEnv(readTarget(testCase)).length > 0)) {
+        return { blockBillable: true, blockReason: 'blocked by invalid base url env' };
+    }
+    if (options.requireIndependentTargets && !isRequiredIndependentGateConfigured(selectedCases)) {
+        return { blockBillable: true, blockReason: 'blocked by incomplete independent target configuration' };
+    }
+    return {};
+}
+
+function isRequiredIndependentGateConfigured(selectedCases) {
+    const selectedIndependentCaseIds = new Set(
+        selectedCases.filter((testCase) => !testCase.serverChannel).map((testCase) => testCase.id)
+    );
+    return CASES.every((testCase) => {
+        if (!selectedIndependentCaseIds.has(testCase.id)) return false;
+        const target = readTarget(testCase);
+        return readInvalidEnv(target).length === 0 && isRunnableTarget(target);
+    });
+}
+
+function parseArgs(argv) {
+    const parsed = {
+        allowBillable: false,
+        caseId: 'all',
+        envFilePath: undefined,
+        help: false,
+        includeServerChannel: false,
+        requireIndependentTargets: false,
+        timeoutMs: readTimeoutMs(env('IMAGE_REAL_SMOKE_TIMEOUT_MS') || '240000', 'IMAGE_REAL_SMOKE_TIMEOUT_MS')
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--allow-billable') parsed.allowBillable = true;
+        else if (arg === '--env-file') parsed.envFilePath = readArgValue(argv, (index += 1), arg);
+        else if (arg === '--env-file-if-exists') parsed.envFileIfExistsPath = readArgValue(argv, (index += 1), arg);
+        else if (arg === '--include-server-channel') parsed.includeServerChannel = true;
+        else if (arg === '--require-independent-targets') parsed.requireIndependentTargets = true;
+        else if (arg === '--timeout-ms') parsed.timeoutMs = readTimeoutMs(readArgValue(argv, (index += 1), arg), arg);
+        else if (arg === '--case') parsed.caseId = readArgValue(argv, (index += 1), arg);
+        else if (arg === '--help' || arg === '-h') parsed.help = true;
+        else throw new Error(`未知参数：${arg}`);
+    }
+    return parsed;
+}
+
+function isHelpRequested(argv) {
+    return argv.includes('--help') || argv.includes('-h');
+}
+
+function readTimeoutMs(value, source) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1000) {
+        throw new Error(`${source} 必须是不小于 1000 的整数毫秒。`);
+    }
+    return parsed;
+}
+
+function readArgValue(argv, index, flag) {
+    const value = argv[index];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} 缺少参数值。`);
+    return value;
+}
+
+function loadDotEnvFiles(argv) {
+    if (env('IMAGE_REAL_SMOKE_SKIP_DOTENV') !== '1') {
+        loadEnvFileIfPresent('.env.local', { overrideLoadedValues: false });
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] !== '--env-file') continue;
+        loadEnvFile(readArgValue(argv, (index += 1), '--env-file'), { overrideLoadedValues: true });
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] !== '--env-file-if-exists') continue;
+        loadEnvFileIfPresent(readArgValue(argv, (index += 1), '--env-file-if-exists'), { overrideLoadedValues: true });
+    }
+}
+
+function loadEnvFileIfPresent(filepath, options) {
+    if (!fs.existsSync(filepath)) return;
+    loadEnvFile(filepath, options);
+}
+
+function loadEnvFile(filepath, options) {
+    if (!fs.existsSync(filepath)) throw new Error(`--env-file 指定的文件不存在：${filepath}`);
+    for (const line of fs.readFileSync(filepath, 'utf8').split(/\r?\n/)) {
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!match || !shouldSetLoadedEnv(match[1], options)) continue;
+        process.env[match[1]] = match[2].replace(/^['"]|['"]$/g, '').trim();
+    }
+}
+
+function shouldSetLoadedEnv(key, options) {
+    if (originalEnv[key] !== undefined) return false;
+    return options.overrideLoadedValues || process.env[key] === undefined;
+}
+
+function restoreProcessEnv() {
+    for (const key of Object.keys(process.env)) {
+        if (!(key in originalEnv)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(originalEnv)) process.env[key] = value;
+}
+
+function configureRouteEnv() {
+    process.env.APP_LOG_LEVEL = 'warn';
+    process.env.NEXT_PUBLIC_IMAGE_STORAGE_MODE = 'indexeddb';
+    process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+    process.env.AGENT_STATE_BACKEND = 'memory';
+    process.env.IMAGE_OUTPUT_DIR = process.env.IMAGE_OUTPUT_DIR || 'generated-images/.real-smoke';
+}
+
+async function loadRouteHandlers() {
+    const imageRoute = await import('../src/app/api/images/route.ts');
+    const agentGenerateRoute = await import('../src/app/api/agent/images/generate/route.ts');
+    return {
+        images: readPostHandler(imageRoute, '/api/images'),
+        agentGenerate: readPostHandler(agentGenerateRoute, '/api/agent/images/generate')
+    };
+}
+
+function readPostHandler(routeModule, label) {
+    const handler = routeModule.POST || routeModule.default?.POST || routeModule['module.exports']?.POST;
+    if (typeof handler !== 'function') {
+        throw new Error(`${label} route 缺少 POST handler。`);
+    }
+    return handler;
+}
+
+async function runCase(loadRouteHandlersForBillable, testCase, preflight = {}) {
+    const target = readTarget(testCase);
+    const invalidEnv = readInvalidEnv(target);
+    if (invalidEnv.length > 0) return invalid(testCase, target, invalidEnv);
+    if (!isRunnableTarget(target)) return skipped(testCase, target);
+    if (preflight.blockBillable && options.allowBillable) return blocked(testCase, target, preflight.blockReason);
+    if (!options.allowBillable) {
+        return {
+            id: testCase.id,
+            skipped: true,
+            ok: true,
+            reason: 'requires --allow-billable',
+            upstream_host: readHost(target.baseUrl),
+            ...(target.serverChannel ? { server_channel: true } : {})
+        };
+    }
+    const startedAt = Date.now();
+    const routeHandlers = await loadRouteHandlersForBillable();
+    const abortController = new AbortController();
+    return withCaseTimeout(
+        runBillableCase(routeHandlers, testCase, target, startedAt, abortController.signal),
+        testCase,
+        target,
+        startedAt,
+        abortController
+    );
+}
+
+async function runBillableCase(routeHandlers, testCase, target, startedAt, signal) {
+    const outputFilesBefore = snapshotRealSmokeOutputFiles();
+    if (testCase.endpoint === 'agent-generate' && testCase.backend === 'responses-image-generation') {
+        process.env.OPENAI_RESPONSES_API_MODEL = target.responsesModel;
+    }
+    try {
+        const response =
+            testCase.endpoint === 'agent-generate'
+                ? await routeHandlers.agentGenerate(agentGenerateRequest(testCase, target, signal))
+                : await routeHandlers.images(imageRequest(testCase, target, signal));
+        const summary =
+            testCase.endpoint === 'agent-generate'
+                ? await summarizeAgentResponse(response)
+                : await summarizeResponse(response);
+        return {
+            id: testCase.id,
+            ok: isSuccessfulBillableSmokeResponse(response, summary),
+            status: response.status,
+            elapsed_ms: Date.now() - startedAt,
+            upstream_host: readHost(target.baseUrl),
+            ...(target.serverChannel ? { server_channel: true } : {}),
+            ...summary
+        };
+    } finally {
+        removeNewRealSmokeOutputFiles(outputFilesBefore);
+    }
+}
+
+function withCaseTimeout(promise, testCase, target, startedAt, abortController) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            settled = true;
+            abortController.abort();
+            resolve({
+                id: testCase.id,
+                ok: false,
+                timed_out: true,
+                elapsed_ms: Date.now() - startedAt,
+                upstream_host: readHost(target.baseUrl),
+                ...(target.serverChannel ? { server_channel: true } : {}),
+                error: `real upstream smoke timed out after ${options.timeoutMs}ms`
+            });
+        }, options.timeoutMs);
+        promise.then(
+            (value) => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeout);
+                resolve(value);
+            },
+            (error) => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeout);
+                reject(error);
+            }
+        );
+    });
+}
+
+function readTarget(testCase) {
+    const basePrefix = testCase.prefix;
+    const fallbackPrefix = testCase.fallbackPrefix || basePrefix;
+    const requiresResponsesModel = testCase.backend === 'responses-image-generation';
+    if (testCase.serverChannel) {
+        const serverBaseUrl = readEnvEntry(`${basePrefix}_BASE_URL`) || readFirstConfiguredServerBaseUrl();
+        return {
+            serverChannel: true,
+            requiresResponsesModel,
+            baseUrl: serverBaseUrl?.value,
+            baseUrlKey: serverBaseUrl?.key,
+            hasServerCredential: Boolean(env('OPENAI_API_KEY') || readFirstConfiguredServerApiKeys()),
+            model: env(`${basePrefix}_MODEL`) || 'gpt-image-2',
+            responsesModel: env(`${basePrefix}_RESPONSES_MODEL`) || env('OPENAI_RESPONSES_API_MODEL'),
+            size: env(`${basePrefix}_SIZE`) || '1024x1024',
+            quality: env(`${basePrefix}_QUALITY`) || 'low'
+        };
+    }
+    const baseUrl = readFirstEnvEntry(readSmokeEnvAlternatives(testCase, 'BASE_URL'));
+    const apiKey = readFirstEnvEntry(readSmokeEnvAlternatives(testCase, 'API_KEY'));
+    return {
+        requiresResponsesModel,
+        baseUrl: baseUrl?.value,
+        baseUrlKey: baseUrl?.key,
+        apiKey: apiKey?.value,
+        model: env(`${basePrefix}_MODEL`) || env(`${fallbackPrefix}_MODEL`) || 'gpt-image-2',
+        responsesModel: env(`${basePrefix}_RESPONSES_MODEL`) || env('OPENAI_RESPONSES_API_MODEL'),
+        size: env(`${basePrefix}_SIZE`) || env(`${fallbackPrefix}_SIZE`) || '1024x1024',
+        quality: env(`${basePrefix}_QUALITY`) || env(`${fallbackPrefix}_QUALITY`) || 'low'
+    };
+}
+
+function isRunnableTarget(target) {
+    if (!target.baseUrl) return false;
+    if (target.requiresResponsesModel && !target.responsesModel) return false;
+    if (target.serverChannel) return target.hasServerCredential;
+    if (!target.apiKey) return false;
+    return true;
+}
+
+function readInvalidEnv(target) {
+    if (!target.baseUrl || !target.baseUrlKey) return [];
+    const reason = readBaseUrlValidationReason(target.baseUrl);
+    return reason ? [{ key: target.baseUrlKey, reason }] : [];
+}
+
+function readBaseUrlValidationReason(value) {
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        return 'must_be_http_or_https_absolute_url';
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return 'must_use_http_or_https';
+    if (url.username || url.password) return 'must_not_include_credentials';
+    if (url.search || url.hash) return 'must_not_include_query_or_fragment';
+    return undefined;
+}
+
+function skipped(testCase, target) {
+    const missingEnvAny = readMissingEnvAny(testCase, target);
+    return {
+        id: testCase.id,
+        skipped: true,
+        ok: true,
+        reason: readSkippedReason(target),
+        ...(missingEnvAny.length > 0 ? { missing_env_any: missingEnvAny } : {}),
+        ...(target.serverChannel ? { server_channel: true } : {})
+    };
+}
+
+function invalid(testCase, target, invalidEnv) {
+    return {
+        id: testCase.id,
+        ok: false,
+        invalid: true,
+        reason: 'invalid base url env',
+        invalid_env: invalidEnv,
+        ...(target.serverChannel ? { server_channel: true } : {})
+    };
+}
+
+function blocked(testCase, target, reason = 'blocked by invalid base url env') {
+    return {
+        id: testCase.id,
+        skipped: true,
+        blocked: true,
+        ok: true,
+        reason,
+        upstream_host: readHost(target.baseUrl),
+        ...(target.serverChannel ? { server_channel: true } : {})
+    };
+}
+
+function buildIndependentTargetSummary(results, requireIndependentTargets = false) {
+    const independentResults = results.filter((item) => !item.server_channel);
+    const requiredCases = CASES.map((testCase) => testCase.id);
+    if (independentResults.length === 0 && !requireIndependentTargets) return undefined;
+    const selectedCases = independentResults.map((item) => item.id);
+    const unselectedRequiredCases = requiredCases.filter((id) => !selectedCases.includes(id));
+    const configuredCases = independentResults
+        .filter(
+            (item) =>
+                (!Array.isArray(item.missing_env_any) || item.missing_env_any.length === 0) &&
+                (!Array.isArray(item.invalid_env) || item.invalid_env.length === 0)
+        )
+        .map((item) => item.id);
+    const missingCases = independentResults
+        .filter((item) => Array.isArray(item.missing_env_any) && item.missing_env_any.length > 0)
+        .map((item) => item.id);
+    const invalidCases = independentResults
+        .filter((item) => Array.isArray(item.invalid_env) && item.invalid_env.length > 0)
+        .map((item) => item.id);
+    return {
+        required_count: requiredCases.length,
+        required_cases: requiredCases,
+        selected_cases: selectedCases,
+        unselected_required_count: unselectedRequiredCases.length,
+        unselected_required_cases: unselectedRequiredCases,
+        configuration_complete:
+            unselectedRequiredCases.length === 0 && missingCases.length === 0 && invalidCases.length === 0,
+        selected_count: independentResults.length,
+        configured_count: configuredCases.length,
+        missing_count: missingCases.length,
+        configured_cases: configuredCases,
+        missing_cases: missingCases,
+        invalid_count: invalidCases.length,
+        invalid_cases: invalidCases,
+        invalid_env: Object.fromEntries(
+            independentResults
+                .filter((item) => Array.isArray(item.invalid_env) && item.invalid_env.length > 0)
+                .map((item) => [item.id, item.invalid_env])
+        ),
+        final_gate_command:
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable'
+    };
+}
+
+function readSkippedReason(target) {
+    if (!target.baseUrl) return target.serverChannel ? 'missing server channel base url env' : 'missing base url env';
+    if (target.serverChannel && !target.hasServerCredential) return 'missing server channel api key env';
+    if (!target.serverChannel && !target.apiKey) return 'missing api key env';
+    if (target.requiresResponsesModel && !target.responsesModel) return 'missing responses model env';
+    return target.serverChannel ? 'missing server channel api key env' : 'missing api key env';
+}
+
+function readMissingEnvAny(testCase, target) {
+    const groups = [];
+    if (!target.baseUrl) {
+        groups.push(readSmokeEnvAlternatives(testCase, 'BASE_URL'));
+    }
+    if (target.serverChannel && target.baseUrl && !target.hasServerCredential) {
+        groups.push(['OPENAI_API_KEY', 'OPENAI_CHANNEL_1_API_KEYS']);
+    }
+    if (!target.serverChannel && target.baseUrl && !target.apiKey) {
+        groups.push(readSmokeEnvAlternatives(testCase, 'API_KEY'));
+    }
+    if (target.requiresResponsesModel && target.baseUrl && !target.responsesModel) {
+        groups.push(readResponsesModelEnvAlternatives(testCase));
+    }
+    return groups;
+}
+
+function readSmokeEnvAlternatives(testCase, suffix) {
+    const keys = [`${testCase.prefix}_${suffix}`];
+    if (testCase.fallbackPrefix && testCase.fallbackPrefix !== testCase.prefix) {
+        keys.push(`${testCase.fallbackPrefix}_${suffix}`);
+    }
+    return keys;
+}
+
+function readResponsesModelEnvAlternatives(testCase) {
+    return [`${testCase.prefix}_RESPONSES_MODEL`, 'OPENAI_RESPONSES_API_MODEL'];
+}
+
+function env(key) {
+    const value = process.env[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readEnvEntry(key) {
+    const value = env(key);
+    return value ? { key, value } : undefined;
+}
+
+function readFirstEnvEntry(keys) {
+    for (const key of keys) {
+        const value = readEnvEntry(key);
+        if (value) return value;
+    }
+    return undefined;
+}
+
+function readFirstConfiguredServerBaseUrl() {
+    return readEnvEntry('OPENAI_API_BASE_URL') || readFirstNumberedEnvEntry('OPENAI_CHANNEL_', '_BASE_URL');
+}
+
+function readFirstConfiguredServerApiKeys() {
+    return env('OPENAI_API_KEY') || readFirstNumberedEnv('OPENAI_CHANNEL_', '_API_KEYS');
+}
+
+function readFirstNumberedEnv(prefix, suffix) {
+    for (let index = 1; index <= 20; index += 1) {
+        const value = env(`${prefix}${index}${suffix}`);
+        if (value) return value;
+    }
+    return undefined;
+}
+
+function readFirstNumberedEnvEntry(prefix, suffix) {
+    for (let index = 1; index <= 20; index += 1) {
+        const value = readEnvEntry(`${prefix}${index}${suffix}`);
+        if (value) return value;
+    }
+    return undefined;
+}
+
+function imageRequest(testCase, target, signal) {
+    const formData = new FormData();
+    const fields = {
+        mode: 'generate',
+        prompt: 'real upstream compatibility smoke',
+        model: target.model,
+        n: '1',
+        size: target.size,
+        quality: target.quality,
+        output_format: 'png',
+        clientRequestId: `real-smoke-${testCase.id}`
+    };
+    for (const [key, value] of Object.entries(fields)) formData.append(key, value);
+    if (!target.serverChannel) {
+        formData.append('apiBaseUrl', target.baseUrl);
+        formData.append('apiKey', target.apiKey);
+    }
+    const pagePasswordHash = readAppPasswordHash();
+    if (pagePasswordHash) formData.append('passwordHash', pagePasswordHash);
+    formData.append('imageBackend', testCase.backend || 'images-api');
+    formData.append('imageStreamingStrategy', testCase.strategy || 'off');
+    if (testCase.backend === 'responses-image-generation') formData.append('responsesModel', target.responsesModel);
+    if (testCase.stream) {
+        formData.append('stream', 'true');
+        formData.append('partial_images', '2');
+    }
+    return new Request('http://localhost/api/images', { method: 'POST', body: formData, signal });
+}
+
+function agentGenerateRequest(testCase, target, signal) {
+    return new Request('http://localhost/api/agent/images/generate', {
+        method: 'POST',
+        headers: buildAgentRequestHeaders(testCase),
+        body: JSON.stringify({
+            prompt: 'real agent upstream sse compatibility smoke',
+            model: target.model,
+            n: 1,
+            size: target.size,
+            quality: target.quality,
+            output_format: 'png',
+            response_mode: 'path',
+            image_backend: testCase.backend || 'images-api',
+            streaming_strategy: testCase.strategy || 'off',
+            partial_images: 2
+        }),
+        signal
+    });
+}
+
+function buildAgentRequestHeaders(testCase) {
+    return {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `real-smoke-${testCase.id}-${Date.now()}`,
+        ...readAgentAuthHeaders()
+    };
+}
+
+function readAgentAuthHeaders() {
+    const token = env('AGENT_API_TOKEN');
+    if (token) return { Authorization: `Bearer ${token}` };
+    const passwordHash = readAppPasswordHash();
+    return passwordHash ? { 'X-App-Password-Hash': passwordHash } : {};
+}
+
+function readAppPasswordHash() {
+    const password = env('APP_PASSWORD');
+    if (!password) return undefined;
+    return crypto.createHash('sha256').update(password).digest('hex');
+}
+
+async function summarizeResponse(response) {
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('text/event-stream')) return summarizeSse(await response.text());
+    return summarizeJson(await response.text(), contentType);
+}
+
+function summarizeSse(text) {
+    const events = text
+        .split('\n\n')
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith('data: ') && part !== 'data: [DONE]')
+        .map((part) => safeJson(part.slice('data: '.length)))
+        .filter(Boolean);
+    const done = events.findLast((event) => event.type === 'done');
+    const error = events.findLast((event) => event.type === 'error');
+    return {
+        content_type: 'text/event-stream',
+        event_types: events.map((event) => event.type || 'unknown'),
+        done_image_count: Array.isArray(done?.images) ? done.images.length : 0,
+        first_b64_length: readFirstB64Length(done?.images),
+        ...(error ? { error: String(error.error || 'stream error') } : {})
+    };
+}
+
+function isSuccessfulBillableSmokeResponse(response, summary) {
+    if (!response.ok || summary?.error) return false;
+    if (summary?.content_type === 'text/event-stream') {
+        return summary.done_image_count > 0;
+    }
+    if (typeof summary?.image_count === 'number') {
+        return summary.image_count > 0;
+    }
+    return false;
+}
+
+function summarizeJson(text, contentType) {
+    const body = safeJson(text);
+    return {
+        content_type: contentType || undefined,
+        image_count: Array.isArray(body?.images) ? body.images.length : 0,
+        first_b64_length: readFirstB64Length(body?.images),
+        ...(body?.error ? { error: String(body.error) } : {})
+    };
+}
+
+async function summarizeAgentResponse(response) {
+    const contentType = response.headers.get('content-type') || '';
+    const body = safeJson(await response.text());
+    return {
+        content_type: contentType || undefined,
+        image_count: Array.isArray(body?.images) ? body.images.length : 0,
+        first_content_url: typeof body?.images?.[0]?.content_url === 'string' ? body.images[0].content_url : undefined,
+        has_inline_base64: Boolean(body?.images?.[0]?.b64_json),
+        ...(body?.error ? { error: String(body.error.message || body.error) } : {})
+    };
+}
+
+function readFirstB64Length(images) {
+    if (!Array.isArray(images) || typeof images[0]?.b64_json !== 'string') return 0;
+    return images[0].b64_json.length;
+}
+
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    } catch {
+        return undefined;
+    }
+}
+
+function readHost(value) {
+    try {
+        return new URL(value).host;
+    } catch {
+        return 'invalid-url';
+    }
+}
+
+function snapshotRealSmokeOutputFiles() {
+    const outputDir = readRealSmokeOutputDir();
+    if (!outputDir || !fs.existsSync(outputDir)) return new Set();
+    return new Set(fs.readdirSync(outputDir).filter(isGeneratedImageFile));
+}
+
+function removeNewRealSmokeOutputFiles(filesBefore) {
+    const outputDir = readRealSmokeOutputDir();
+    if (!outputDir || !fs.existsSync(outputDir)) return;
+    for (const filename of fs.readdirSync(outputDir).filter(isGeneratedImageFile)) {
+        if (filesBefore.has(filename)) continue;
+        fs.rmSync(`${outputDir}/${filename}`, { force: true });
+    }
+}
+
+function readRealSmokeOutputDir() {
+    return process.env.IMAGE_OUTPUT_DIR === 'generated-images/.real-smoke' ? process.env.IMAGE_OUTPUT_DIR : undefined;
+}
+
+function isGeneratedImageFile(filename) {
+    return /\.(png|jpe?g|webp)$/i.test(filename);
+}
+
+function printUsage() {
+    console.log(`用法：npm run smoke:image-upstream-real -- [--env-file <path>] [--env-file-if-exists <path>] [--allow-billable] [--include-server-channel] [--require-independent-targets] [--timeout-ms <ms>] [--case <id>]
+
+环境变量前缀：
+  IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL / IMAGE_REAL_SMOKE_ORIGINAL_API_KEY
+  IMAGE_REAL_SMOKE_GAOREN_BASE_URL / IMAGE_REAL_SMOKE_GAOREN_API_KEY
+  IMAGE_REAL_SMOKE_SUB2API_BASE_URL / IMAGE_REAL_SMOKE_SUB2API_API_KEY
+  IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL / IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY
+  IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL / IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY
+  IMAGE_REAL_SMOKE_SERVER_* 可覆盖当前服务端渠道的 MODEL / SIZE / QUALITY / RESPONSES_MODEL
+
+可选 --case：all、original-images-json、gaoren-images-sse、sub2api-images-sse、sub2api-responses-json、gpt2image-responses-sse。
+添加 --include-server-channel 后还可运行：server-channel-images-json、server-channel-images-sse、server-channel-responses-sse、server-channel-responses-json、server-channel-agent-images-sse、server-channel-agent-responses-sse。
+默认只检查配置并跳过真实生图；必须加 --allow-billable 才会调用 /api/images 或 /api/agent/images/generate。
+可用 --env-file 指向独立真实上游凭据文件；shell 环境变量优先级高于 --env-file，--env-file 优先级高于 .env.local。
+可用 --env-file-if-exists 在凭据文件存在时加载，不存在时继续输出结构化 readiness 报告。
+添加 --require-independent-targets 后，任何独立真实上游场景未被选中或被跳过都会使脚本退出非零。默认单场景超时为 240000ms。`);
+}

scripts/smoke-image-upstream-real.test.mjs

@@ -0,0 +1,1070 @@
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join } from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const scriptPath = join(repoRoot, 'scripts/smoke-image-upstream-real.mjs');
+const realSmokeOutputDir = join(repoRoot, 'generated-images/.real-smoke');
+const pngBase64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
+
+describe('image upstream real smoke script', () => {
+    it('skips every real upstream target without billable calls when no target env is configured', () => {
+        const result = runScript();
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.billable, false);
+        assert.equal(report.results.length, 5);
+        assert.equal(
+            report.results.every((item) => item.skipped === true),
+            true
+        );
+        assert.equal(
+            report.results.every((item) => item.reason === 'missing base url env'),
+            true
+        );
+        assert.deepEqual(report.results[0].missing_env_any, [['IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL']]);
+        assert.deepEqual(report.results[3].missing_env_any, [
+            ['IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL', 'IMAGE_REAL_SMOKE_SUB2API_BASE_URL']
+        ]);
+        assert.deepEqual(report.independent_targets, {
+            required_count: 5,
+            required_cases: independentSmokeCaseIds(),
+            selected_cases: independentSmokeCaseIds(),
+            unselected_required_count: 0,
+            unselected_required_cases: [],
+            configuration_complete: false,
+            selected_count: 5,
+            configured_count: 0,
+            missing_count: 5,
+            configured_cases: [],
+            missing_cases: independentSmokeCaseIds(),
+            invalid_count: 0,
+            invalid_cases: [],
+            invalid_env: {},
+            final_gate_command:
+                'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable'
+        });
+    });
+
+    it('does not run configured real upstreams without explicit billable consent or leak API keys', () => {
+        const result = runScript(['--case', 'original-images-json'], {
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://example.test/v1',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key'
+        });
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /secret-real-smoke-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.results.length, 1);
+        assert.equal(report.results[0].reason, 'requires --allow-billable');
+        assert.equal(report.results[0].upstream_host, 'example.test');
+        assert.equal('missing_env_any' in report.results[0], false);
+        assert.deepEqual(report.independent_targets.required_cases, independentSmokeCaseIds());
+        assert.deepEqual(report.independent_targets.selected_cases, ['original-images-json']);
+        assert.deepEqual(report.independent_targets.unselected_required_cases, [
+            'gaoren-images-sse',
+            'sub2api-images-sse',
+            'sub2api-responses-json',
+            'gpt2image-responses-sse'
+        ]);
+        assert.equal(report.independent_targets.configuration_complete, false);
+        assert.deepEqual(report.independent_targets.configured_cases, ['original-images-json']);
+        assert.deepEqual(report.independent_targets.missing_cases, []);
+    });
+
+    it('loads independent real upstream targets from an explicit env file without leaking API keys', () => {
+        const envFilePath = join(repoRoot, 'generated-images/.real-smoke-test.env');
+        try {
+            writeEnvFile(
+                envFilePath,
+                [
+                    'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=https://env-file.example/v1',
+                    'IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=secret-env-file-key'
+                ].join('\n')
+            );
+            const result = runScript(['--env-file', envFilePath, '--case', 'original-images-json']);
+
+            assert.equal(result.status, 0);
+            assert.equal(result.stderr.trim(), '');
+            assert.doesNotMatch(result.stdout, /secret-env-file-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].reason, 'requires --allow-billable');
+            assert.equal(report.results[0].upstream_host, 'env-file.example');
+        } finally {
+            rmSync(envFilePath, { force: true });
+        }
+    });
+
+    it('keeps shell environment values ahead of explicit env file values', () => {
+        const envFilePath = join(repoRoot, 'generated-images/.real-smoke-test.env');
+        try {
+            writeEnvFile(
+                envFilePath,
+                [
+                    'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=https://env-file.example/v1',
+                    'IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=secret-env-file-key'
+                ].join('\n')
+            );
+            const result = runScript(['--env-file', envFilePath, '--case', 'original-images-json'], {
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://shell.example/v1',
+                IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-shell-key'
+            });
+
+            assert.equal(result.status, 0);
+            assert.doesNotMatch(result.stdout, /secret-env-file-key|secret-shell-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].upstream_host, 'shell.example');
+        } finally {
+            rmSync(envFilePath, { force: true });
+        }
+    });
+
+    it('reports the missing API key env when a real upstream base URL is configured alone', () => {
+        const result = runScript(['--case', 'gaoren-images-sse'], {
+            IMAGE_REAL_SMOKE_GAOREN_BASE_URL: 'https://gaoren.example/v1'
+        });
+
+        assert.equal(result.status, 0);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.results[0].reason, 'missing api key env');
+        assert.deepEqual(report.results[0].missing_env_any, [['IMAGE_REAL_SMOKE_GAOREN_API_KEY']]);
+    });
+
+    it('reports unsafe real upstream base URLs in the structured readiness summary', () => {
+        const result = runScript(['--case', 'original-images-json'], {
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://user:pass@example.test/v1?token=secret#frag',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key'
+        });
+
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /user:pass|example\.test|secret-real-smoke-key|token=secret/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, false);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.independent_targets.configuration_complete, false);
+        assert.equal(report.independent_targets.configured_count, 0);
+        assert.equal(report.independent_targets.invalid_count, 1);
+        assert.deepEqual(report.independent_targets.invalid_cases, ['original-images-json']);
+        assert.deepEqual(report.independent_targets.invalid_env['original-images-json'], [
+            {
+                key: 'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL',
+                reason: 'must_not_include_credentials'
+            }
+        ]);
+        assert.deepEqual(report.results[0].invalid_env, [
+            {
+                key: 'IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL',
+                reason: 'must_not_include_credentials'
+            }
+        ]);
+    });
+
+    it('does not make billable upstream calls when any selected target has unsafe configuration', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--require-independent-targets'], {
+                ...buildAllIndependentTargetEnv(upstream.baseUrl),
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://user:pass@example.test/v1?token=secret#frag'
+            });
+
+            assert.equal(result.status, 1);
+            assert.doesNotMatch(result.stdout, /user:pass|example\.test|secret-independent-key|token=secret/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, false);
+            assert.deepEqual(report.invalid_required_cases, ['original-images-json']);
+            assert.deepEqual(report.blocked_required_cases, [
+                'gaoren-images-sse',
+                'sub2api-images-sse',
+                'sub2api-responses-json',
+                'gpt2image-responses-sse'
+            ]);
+            assert.equal(upstream.calls.length, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('reports blocked cases at the top level for non-final-gate billable smoke runs', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable'], {
+                ...buildAllIndependentTargetEnv(upstream.baseUrl),
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://user:pass@example.test/v1?token=secret#frag'
+            });
+
+            assert.equal(result.status, 1);
+            const report = JSON.parse(result.stdout);
+            assert.deepEqual(report.blocked_cases, [
+                'gaoren-images-sse',
+                'sub2api-images-sse',
+                'sub2api-responses-json',
+                'gpt2image-responses-sse'
+            ]);
+            assert.equal(upstream.calls.length, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('does not make billable upstream calls when the required independent gate is missing target config', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--require-independent-targets'], {
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: upstream.baseUrl,
+                IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key'
+            });
+
+            assert.equal(result.status, 1);
+            assert.doesNotMatch(result.stdout, /secret-real-smoke-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, false);
+            assert.deepEqual(report.blocked_required_cases, ['original-images-json']);
+            assert.deepEqual(report.skipped_required_cases, [
+                'gaoren-images-sse',
+                'sub2api-images-sse',
+                'sub2api-responses-json',
+                'gpt2image-responses-sse'
+            ]);
+            assert.equal(upstream.calls.length, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails the run when independent upstream targets are required but skipped', () => {
+        const result = runScript(['--require-independent-targets']);
+
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, false);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.deepEqual(report.skipped_required_cases, [
+            'original-images-json',
+            'gaoren-images-sse',
+            'sub2api-images-sse',
+            'sub2api-responses-json',
+            'gpt2image-responses-sse'
+        ]);
+        assert.equal('unselected_required_cases' in report, false);
+        assert.equal(report.missing_required_count, 5);
+        assert.deepEqual(report.missing_required_cases, independentSmokeCaseIds());
+    });
+
+    it('fails the required independent upstream gate when billable consent is missing', () => {
+        const result = runScript(['--require-independent-targets', '--case', 'original-images-json'], {
+            IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: 'https://example.test/v1',
+            IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key'
+        });
+
+        assert.equal(result.status, 1);
+        assert.doesNotMatch(result.stdout, /secret-real-smoke-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, false);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.deepEqual(report.skipped_required_cases, ['original-images-json']);
+        assert.deepEqual(report.unselected_required_cases, [
+            'gaoren-images-sse',
+            'sub2api-images-sse',
+            'sub2api-responses-json',
+            'gpt2image-responses-sse'
+        ]);
+        assert.equal(report.missing_required_count, 5);
+        assert.deepEqual(report.missing_required_cases, independentSmokeCaseIds());
+        assert.equal(report.results[0].reason, 'requires --allow-billable');
+    });
+
+    it('can include current server channel smoke cases without explicit billable consent or leaking keys', () => {
+        const result = runScript(['--include-server-channel', '--case', 'server-channel-agent-images-sse'], {
+            OPENAI_CHANNEL_1_BASE_URL: 'https://server-channel.example/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key'
+        });
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.results.length, 1);
+        assert.equal(report.results[0].reason, 'requires --allow-billable');
+        assert.equal(report.results[0].server_channel, true);
+        assert.equal(report.results[0].upstream_host, 'server-channel.example');
+        assert.equal('independent_targets' in report, false);
+    });
+
+    it('fails the required independent upstream gate when only server channel cases are selected', () => {
+        const result = runScript(
+            ['--include-server-channel', '--require-independent-targets', '--case', 'server-channel-agent-images-sse'],
+            {
+                OPENAI_CHANNEL_1_BASE_URL: 'https://server-channel.example/v1',
+                OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key'
+            }
+        );
+
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, false);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.independent_targets.required_count, 5);
+        assert.deepEqual(report.independent_targets.selected_cases, []);
+        assert.equal(report.independent_targets.unselected_required_count, 5);
+        assert.deepEqual(report.independent_targets.unselected_required_cases, independentSmokeCaseIds());
+        assert.deepEqual(report.unselected_required_cases, independentSmokeCaseIds());
+        assert.equal(report.missing_required_count, 5);
+        assert.deepEqual(report.missing_required_cases, independentSmokeCaseIds());
+        assert.equal('skipped_required_cases' in report, false);
+    });
+
+    it('can dry-run the current server channel Agent Responses SSE smoke case without leaking keys', () => {
+        const result = runScript(['--include-server-channel', '--case', 'server-channel-agent-responses-sse'], {
+            OPENAI_CHANNEL_1_BASE_URL: 'https://server-channel.example/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key',
+            IMAGE_REAL_SMOKE_SERVER_RESPONSES_MODEL: 'gpt-4.1'
+        });
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.results.length, 1);
+        assert.equal(report.results[0].reason, 'requires --allow-billable');
+        assert.equal(report.results[0].server_channel, true);
+        assert.equal(report.results[0].upstream_host, 'server-channel.example');
+    });
+
+    it('can dry-run the current server channel Responses JSON smoke case without leaking keys', () => {
+        const result = runScript(['--include-server-channel', '--case', 'server-channel-responses-json'], {
+            OPENAI_CHANNEL_1_BASE_URL: 'https://server-channel.example/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key',
+            IMAGE_REAL_SMOKE_SERVER_RESPONSES_MODEL: 'gpt-4.1'
+        });
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.final_gate_satisfied, false);
+        assert.equal(report.results.length, 1);
+        assert.equal(report.results[0].reason, 'requires --allow-billable');
+        assert.equal(report.results[0].server_channel, true);
+        assert.equal(report.results[0].upstream_host, 'server-channel.example');
+    });
+
+    it('requires an explicit Responses top-level model for Responses smoke readiness', () => {
+        const result = runScript(['--case', 'sub2api-responses-json'], {
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL: 'https://responses.example/v1',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY: 'secret-responses-key'
+        });
+
+        assert.equal(result.status, 0);
+        assert.doesNotMatch(result.stdout, /secret-responses-key|responses\.example/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.results[0].reason, 'missing responses model env');
+        assert.deepEqual(report.results[0].missing_env_any, [
+            ['IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL', 'OPENAI_RESPONSES_API_MODEL']
+        ]);
+        assert.equal(report.independent_targets.configuration_complete, false);
+        assert.deepEqual(report.independent_targets.missing_cases, ['sub2api-responses-json']);
+    });
+
+    it('does not treat the sub2api Responses image model env as readiness for the Responses top-level model', () => {
+        const result = runScript(['--case', 'sub2api-responses-json'], {
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL: 'https://responses.example/v1',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY: 'secret-responses-key',
+            IMAGE_REAL_SMOKE_SUB2API_RESPONSES_MODEL: 'gpt-image-2'
+        });
+
+        assert.equal(result.status, 0);
+        assert.doesNotMatch(result.stdout, /secret-responses-key|responses\.example/);
+        const report = JSON.parse(result.stdout);
+        assert.equal(report.ok, true);
+        assert.equal(report.results[0].reason, 'missing responses model env');
+        assert.deepEqual(report.results[0].missing_env_any, [
+            ['IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL', 'OPENAI_RESPONSES_API_MODEL']
+        ]);
+        assert.equal(report.independent_targets.configuration_complete, false);
+        assert.deepEqual(report.independent_targets.missing_cases, ['sub2api-responses-json']);
+    });
+
+    it('passes APP_PASSWORD auth to in-process page route billable smoke runs', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--case', 'original-images-json'], {
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: upstream.baseUrl,
+                IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key',
+                APP_PASSWORD: 'page-access-code'
+            });
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-real-smoke-key|page-access-code/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].image_count, 1);
+            assert.deepEqual(upstream.calls, ['/v1/images/generations']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('pins page route smoke backend and strategy against global route defaults', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--case', 'original-images-json'], {
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: upstream.baseUrl,
+                IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key',
+                IMAGE_GENERATION_BACKEND: 'responses-image-generation',
+                IMAGE_STREAMING_STRATEGY: 'force-sse',
+                ENABLE_RESPONSES_IMAGE_BACKEND: 'true',
+                OPENAI_RESPONSES_API_MODEL: 'gpt-4.1-env'
+            });
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-real-smoke-key|gpt-4\.1-env/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].content_type, 'application/json');
+            assert.equal(report.results[0].image_count, 1);
+            assert.deepEqual(upstream.calls, ['/v1/images/generations']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('trims APP_PASSWORD before hashing page route billable smoke auth', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--case', 'original-images-json'], {
+                IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: upstream.baseUrl,
+                IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key',
+                APP_PASSWORD: '  page-access-code  '
+            });
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-real-smoke-key|page-access-code/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].image_count, 1);
+            assert.deepEqual(upstream.calls, ['/v1/images/generations']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('passes AGENT_API_TOKEN auth to in-process Agent route billable smoke runs', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(
+                ['--include-server-channel', '--allow-billable', '--case', 'server-channel-agent-images-sse'],
+                {
+                    OPENAI_CHANNEL_1_BASE_URL: upstream.baseUrl,
+                    OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key',
+                    AGENT_API_TOKEN: 'secret-agent-token'
+                }
+            );
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-server-channel-key|secret-agent-token/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].image_count, 1);
+            assert.deepEqual(upstream.calls, ['/v1/images/generations']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('passes APP_PASSWORD auth to in-process Agent route billable smoke runs when no Agent token is configured', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(
+                ['--include-server-channel', '--allow-billable', '--case', 'server-channel-agent-images-sse'],
+                {
+                    OPENAI_CHANNEL_1_BASE_URL: upstream.baseUrl,
+                    OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key',
+                    APP_PASSWORD: 'page-access-code'
+                }
+            );
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-server-channel-key|page-access-code/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].image_count, 1);
+            assert.deepEqual(upstream.calls, ['/v1/images/generations']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('removes generated .real-smoke artifact files after billable local Agent smoke runs', async () => {
+        const upstream = await startLocalImagesSseUpstream();
+        const before = listRealSmokeFiles();
+        let after = before;
+        try {
+            const result = await runScriptAsync(
+                ['--include-server-channel', '--allow-billable', '--case', 'server-channel-agent-images-sse'],
+                {
+                    OPENAI_CHANNEL_1_BASE_URL: upstream.baseUrl,
+                    OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key'
+                }
+            );
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, true);
+            assert.equal(report.final_gate_satisfied, false);
+            assert.equal(report.results[0].image_count, 1);
+            after = listRealSmokeFiles();
+            assert.deepEqual(diffFiles(before, after), []);
+        } finally {
+            for (const file of diffFiles(before, after)) {
+                rmSync(join(realSmokeOutputDir, file), { force: true });
+            }
+            await upstream.close();
+        }
+    });
+
+    it('runs the current server channel Responses JSON smoke case against a local upstream', async () => {
+        const upstream = await startLocalResponsesJsonUpstream();
+        try {
+            const result = await runScriptAsync(
+                ['--include-server-channel', '--allow-billable', '--case', 'server-channel-responses-json'],
+                {
+                    OPENAI_CHANNEL_1_BASE_URL: upstream.baseUrl,
+                    OPENAI_CHANNEL_1_API_KEYS: 'secret-server-channel-key',
+                    IMAGE_REAL_SMOKE_SERVER_RESPONSES_MODEL: 'gpt-5.4'
+                }
+            );
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-server-channel-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, true);
+            assert.equal(report.final_gate_satisfied, false);
+            assert.equal(report.results[0].status, 200);
+            assert.equal(report.results[0].image_count, 1);
+            assert.equal(report.results[0].first_b64_length, pngBase64.length);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('marks the final gate satisfied only after every independent target runs successfully', async () => {
+        const upstream = await startLocalImageAndResponsesUpstream();
+        try {
+            const result = await runScriptAsync(
+                ['--allow-billable', '--require-independent-targets'],
+                buildAllIndependentTargetEnv(upstream.baseUrl)
+            );
+
+            assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-independent-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, true);
+            assert.equal(report.final_gate_satisfied, true);
+            assert.equal(report.independent_targets.configuration_complete, true);
+            assert.equal(report.independent_targets.configured_count, 5);
+            assert.equal(report.results.length, 5);
+            assert.equal(
+                report.results.every((item) => item.ok === true && item.skipped !== true),
+                true
+            );
+            assert.equal('missing_required_cases' in report, false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails the final gate when a page SSE smoke case returns a stream error event', async () => {
+        const successUpstream = await startLocalImageAndResponsesUpstream();
+        const failingSseUpstream = await startLocalFailingImagesSseUpstream();
+        try {
+            const result = await runScriptAsync(['--allow-billable', '--require-independent-targets'], {
+                ...buildAllIndependentTargetEnv(successUpstream.baseUrl),
+                IMAGE_REAL_SMOKE_GAOREN_BASE_URL: failingSseUpstream.baseUrl,
+                IMAGE_REAL_SMOKE_GAOREN_API_KEY: 'secret-independent-key-gaoren'
+            });
+
+            assert.equal(result.status, 1, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-independent-key/);
+            const report = JSON.parse(result.stdout);
+            const failedCase = report.results.find((item) => item.id === 'gaoren-images-sse');
+
+            assert.equal(report.ok, false);
+            assert.equal(report.final_gate_satisfied, false);
+            assert.equal(failedCase?.ok, false);
+            assert.equal(failedCase?.status, 200);
+            assert.equal(failedCase?.done_image_count, 0);
+            assert.match(failedCase?.error || '', /b64_json|最终图片/);
+            assert.equal(successUpstream.calls.length, 4);
+        } finally {
+            await successUpstream.close();
+            await failingSseUpstream.close();
+        }
+    });
+
+    it('exits after its own timeout when a billable upstream never responds', async () => {
+        const upstream = await startLocalHangingImageUpstream();
+        try {
+            const result = await runScriptAsync(
+                ['--allow-billable', '--case', 'original-images-json', '--timeout-ms', '1000'],
+                {
+                    IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: upstream.baseUrl,
+                    IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-real-smoke-key'
+                },
+                { killAfterMs: 4500 }
+            );
+
+            assert.equal(result.signal, null, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.equal(result.killedByTest, false, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.equal(result.status, 1, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.doesNotMatch(result.stdout, /secret-real-smoke-key/);
+            const report = JSON.parse(result.stdout);
+            assert.equal(report.ok, false);
+            assert.equal(report.final_gate_satisfied, false);
+            assert.equal(report.results[0].timed_out, true);
+            assert.equal(report.results[0].ok, false);
+            assert.match(report.results[0].error, /timed out after 1000ms/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('rejects invalid timeout values before running smoke cases', () => {
+        const result = runScript(['--timeout-ms', '999']);
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /--timeout-ms 必须是不小于 1000 的整数毫秒/);
+    });
+
+    it('rejects missing env file values before running smoke cases', () => {
+        const result = runScript(['--env-file']);
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /--env-file 缺少参数值/);
+    });
+
+    it('lets the npm smoke script pass --env-file through to the smoke script', () => {
+        const missingEnvFilePath = join(repoRoot, 'generated-images/.missing-real-smoke.env');
+        rmSync(missingEnvFilePath, { force: true });
+
+        const result = spawnSync('npm', ['run', 'smoke:image-upstream-real', '--', '--env-file', missingEnvFilePath], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            env: buildScriptEnv()
+        });
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /--env-file 指定的文件不存在/);
+        assert.doesNotMatch(result.stderr, /node: .*not found/);
+        assert.doesNotMatch(result.stderr, /ModuleJob\.run|Node\.js v|at loadEnvFile/);
+    });
+
+    it('lets the npm final gate report readiness when the optional env file is absent', () => {
+        const missingEnvFilePath = join(repoRoot, 'generated-images/.missing-real-smoke.env');
+        rmSync(missingEnvFilePath, { force: true });
+
+        const result = spawnSync(
+            'npm',
+            [
+                'run',
+                'smoke:image-upstream-real',
+                '--',
+                '--env-file-if-exists',
+                missingEnvFilePath,
+                '--require-independent-targets',
+                '--allow-billable'
+            ],
+            {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: buildScriptEnv()
+            }
+        );
+
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+        const report = JSON.parse(result.stdout.slice(result.stdout.indexOf('{')));
+        assert.equal(report.independent_targets.configuration_complete, false);
+        assert.equal(report.missing_required_count, 5);
+        assert.deepEqual(report.missing_required_cases, independentSmokeCaseIds());
+    });
+
+    it('fails explicitly for unknown real upstream smoke cases', () => {
+        const result = runScript(['--case', 'missing-case']);
+
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /未知真实 smoke 场景：missing-case/);
+    });
+
+    it('lists every independent real upstream smoke target in help output', () => {
+        const result = runScript(['--help']);
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        assert.match(result.stdout, /--env-file <path>/);
+        assert.match(result.stdout, /--env-file-if-exists <path>/);
+        for (const prefix of independentSmokePrefixes()) {
+            assert.match(result.stdout, new RegExp(`${prefix}_BASE_URL / ${prefix}_API_KEY`));
+        }
+    });
+
+    it('documents every independent real upstream smoke target in env templates without secrets', () => {
+        const envExample = readFileSync(join(repoRoot, '.env.example'), 'utf8');
+        const realSmokeEnvExample = readFileSync(join(repoRoot, '.env.real-smoke.example'), 'utf8');
+        const gitignore = readFileSync(join(repoRoot, '.gitignore'), 'utf8');
+
+        for (const prefix of independentSmokePrefixes()) {
+            assert.match(envExample, new RegExp(`# ${prefix}_BASE_URL=`));
+            assert.match(envExample, new RegExp(`# ${prefix}_API_KEY=$`, 'm'));
+            assert.match(realSmokeEnvExample, new RegExp(`${prefix}_BASE_URL=`));
+            assert.match(realSmokeEnvExample, new RegExp(`${prefix}_API_KEY=$`, 'm'));
+        }
+        assert.match(envExample, /# IMAGE_REAL_SMOKE_TIMEOUT_MS=240000/);
+        assert.match(realSmokeEnvExample, /^IMAGE_REAL_SMOKE_TIMEOUT_MS=240000$/m);
+        assert.match(gitignore, /^!.env\.real-smoke\.example$/m);
+    });
+});
+
+function independentSmokePrefixes() {
+    return [
+        'IMAGE_REAL_SMOKE_ORIGINAL',
+        'IMAGE_REAL_SMOKE_GAOREN',
+        'IMAGE_REAL_SMOKE_SUB2API',
+        'IMAGE_REAL_SMOKE_SUB2API_RESPONSES',
+        'IMAGE_REAL_SMOKE_GPT2IMAGE'
+    ];
+}
+
+function independentSmokeCaseIds() {
+    return [
+        'original-images-json',
+        'gaoren-images-sse',
+        'sub2api-images-sse',
+        'sub2api-responses-json',
+        'gpt2image-responses-sse'
+    ];
+}
+
+function buildAllIndependentTargetEnv(baseUrl) {
+    return {
+        IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_ORIGINAL_API_KEY: 'secret-independent-key-original',
+        IMAGE_REAL_SMOKE_GAOREN_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_GAOREN_API_KEY: 'secret-independent-key-gaoren',
+        IMAGE_REAL_SMOKE_SUB2API_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_SUB2API_API_KEY: 'secret-independent-key-sub2api',
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY: 'secret-independent-key-sub2api-responses',
+        IMAGE_REAL_SMOKE_SUB2API_RESPONSES_RESPONSES_MODEL: 'gpt-4.1',
+        IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL: baseUrl,
+        IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY: 'secret-independent-key-gpt2image',
+        IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL: 'gpt-5.4'
+    };
+}
+
+function runScript(args = [], env = {}) {
+    return spawnSync(process.execPath, ['--import', 'tsx', scriptPath, ...args], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        env: buildScriptEnv(env)
+    });
+}
+
+function runScriptAsync(args = [], env = {}, options = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, ['--import', 'tsx', scriptPath, ...args], {
+            cwd: repoRoot,
+            env: buildScriptEnv(env),
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const startedAt = Date.now();
+        let stdout = '';
+        let stderr = '';
+        let killedByTest = false;
+        const killTimer = options.killAfterMs
+            ? setTimeout(() => {
+                  killedByTest = true;
+                  child.kill('SIGTERM');
+              }, options.killAfterMs)
+            : undefined;
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('close', (status, signal) => {
+            if (killTimer) clearTimeout(killTimer);
+            resolve({ status, signal, stdout, stderr, killedByTest, elapsedMs: Date.now() - startedAt });
+        });
+    });
+}
+
+function listRealSmokeFiles() {
+    try {
+        return readdirSync(realSmokeOutputDir)
+            .filter((item) => item.endsWith('.png') || item.endsWith('.jpeg'))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+function diffFiles(before, after) {
+    const beforeSet = new Set(before);
+    return after.filter((file) => !beforeSet.has(file));
+}
+
+function writeEnvFile(filepath, content) {
+    rmSync(filepath, { force: true });
+    mkdirSync(dirname(filepath), { recursive: true });
+    writeFileSync(filepath, `${content}\n`, 'utf8');
+}
+
+function buildScriptEnv(env = {}) {
+    const scriptEnv = { ...process.env };
+    for (const key of Object.keys(scriptEnv)) {
+        if (isSmokeEnvKey(key)) delete scriptEnv[key];
+    }
+    return {
+        ...scriptEnv,
+        ...env,
+        NODE_ENV: 'test',
+        IMAGE_REAL_SMOKE_SKIP_DOTENV: '1'
+    };
+}
+
+function isSmokeEnvKey(key) {
+    return (
+        key.startsWith('IMAGE_REAL_SMOKE_') ||
+        key.startsWith('OPENAI_CHANNEL_') ||
+        key === 'OPENAI_API_BASE_URL' ||
+        key === 'OPENAI_API_KEY' ||
+        key === 'OPENAI_RESPONSES_API_MODEL' ||
+        key === 'OPENAI_ROUTING_STRATEGY' ||
+        key === 'OPENAI_CHANNELS_JSON' ||
+        key === 'IMAGE_GENERATION_BACKEND' ||
+        key === 'IMAGE_STREAMING_STRATEGY' ||
+        key === 'ENABLE_RESPONSES_IMAGE_BACKEND' ||
+        key === 'IMAGE_OUTPUT_DIR' ||
+        key === 'APP_PASSWORD' ||
+        key === 'AGENT_API_TOKEN'
+    );
+}
+
+async function startLocalImagesSseUpstream() {
+    const server = createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        request.resume();
+        await new Promise((resolve) => request.on('end', resolve));
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        response.write(
+            `event: image_generation.completed\ndata: ${JSON.stringify({ type: 'image_generation.completed', b64_json: pngBase64 })}\n\n`
+        );
+        response.write('data: [DONE]\n\n');
+        response.end();
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+
+async function startLocalFailingImagesSseUpstream() {
+    const server = createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        request.resume();
+        await new Promise((resolve) => request.on('end', resolve));
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        response.write(
+            `event: image_generation.completed\ndata: ${JSON.stringify({ type: 'image_generation.completed' })}\n\n`
+        );
+        response.write('data: [DONE]\n\n');
+        response.end();
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+
+async function startLocalHangingImageUpstream() {
+    const sockets = new Set();
+    const server = createServer(async (request) => {
+        if (request.method === 'POST' && request.url?.endsWith('/images/generations')) {
+            request.resume();
+            return;
+        }
+        request.resume();
+    });
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () =>
+            new Promise((resolve, reject) => {
+                for (const socket of sockets) socket.destroy();
+                server.close((error) => (error ? reject(error) : resolve()));
+            })
+    };
+}
+
+async function startLocalImageAndResponsesUpstream() {
+    const calls = [];
+    const server = createServer(async (request, response) => {
+        if (request.method !== 'POST') {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        calls.push(request.url);
+        const body = await readRequestBody(request);
+        if (request.url?.endsWith('/images/generations')) {
+            respondToImageGenerationRequest(response, body);
+            return;
+        }
+        if (request.url?.endsWith('/responses')) {
+            respondToResponsesImageRequest(response, body);
+            return;
+        }
+        response.writeHead(404, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: { message: 'not found' } }));
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        calls,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+
+async function readRequestBody(request) {
+    let body = '';
+    request.setEncoding('utf8');
+    request.on('data', (chunk) => {
+        body += chunk;
+    });
+    await new Promise((resolve) => request.on('end', resolve));
+    return body ? JSON.parse(body) : {};
+}
+
+function respondToImageGenerationRequest(response, body) {
+    if (body.stream === true) {
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        response.write(
+            `event: image_generation.completed\ndata: ${JSON.stringify({ type: 'image_generation.completed', b64_json: pngBase64 })}\n\n`
+        );
+        response.write('data: [DONE]\n\n');
+        response.end();
+        return;
+    }
+    response.writeHead(200, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify({ data: [{ b64_json: pngBase64 }] }));
+}
+
+function respondToResponsesImageRequest(response, body) {
+    if (body.tool_choice?.type !== 'image_generation' || body.tools?.[0]?.type !== 'image_generation') {
+        response.writeHead(400, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: { message: 'invalid responses image request' } }));
+        return;
+    }
+    if (body.stream === true) {
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        response.write(
+            `event: response.output_item.done\ndata: ${JSON.stringify({
+                type: 'response.output_item.done',
+                item: { type: 'image_generation_call', status: 'completed', result: pngBase64 }
+            })}\n\n`
+        );
+        response.write('data: [DONE]\n\n');
+        response.end();
+        return;
+    }
+    response.writeHead(200, { 'Content-Type': 'application/json' });
+    response.end(
+        JSON.stringify({ output: [{ type: 'image_generation_call', status: 'completed', result: pngBase64 }] })
+    );
+}
+
+async function startLocalResponsesJsonUpstream() {
+    const server = createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/responses')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        let body = '';
+        request.setEncoding('utf8');
+        request.on('data', (chunk) => {
+            body += chunk;
+        });
+        await new Promise((resolve) => request.on('end', resolve));
+        const parsed = JSON.parse(body);
+        if (
+            parsed.stream !== false ||
+            parsed.tool_choice?.type !== 'image_generation' ||
+            parsed.tools?.[0]?.type !== 'image_generation'
+        ) {
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'invalid responses image request' } }));
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(
+            JSON.stringify({
+                output: [{ type: 'image_generation_call', status: 'completed', result: pngBase64 }]
+            })
+        );
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}

scripts/status.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { HF_SPACE_ID, HF_SPACE_URL } from './hf-space-doctor-utils.mjs';
+import { isMainModule, parseJsonPayload, printJson, runCommand, runCommandStrict } from './command-center-utils.mjs';
+
+const REMOTE_STATUS_TIMEOUT_MS = 30_000;
+const IMAGE_UPSTREAM_REAL_SMOKE_CASES = [
+    { id: 'original-images-json', prefix: 'IMAGE_REAL_SMOKE_ORIGINAL' },
+    { id: 'gaoren-images-sse', prefix: 'IMAGE_REAL_SMOKE_GAOREN' },
+    { id: 'sub2api-images-sse', prefix: 'IMAGE_REAL_SMOKE_SUB2API' },
+    {
+        id: 'sub2api-responses-json',
+        prefix: 'IMAGE_REAL_SMOKE_SUB2API_RESPONSES',
+        fallbackPrefix: 'IMAGE_REAL_SMOKE_SUB2API',
+        requiresResponsesModel: true
+    },
+    { id: 'gpt2image-responses-sse', prefix: 'IMAGE_REAL_SMOKE_GPT2IMAGE', requiresResponsesModel: true }
+];
+const IMAGE_UPSTREAM_FINAL_GATE_COMMAND =
+    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable';
+const STATUS_ENV_FILES = [
+    { path: '.env.local', override: false },
+    { path: '.env.real-smoke.local', override: true }
+];
+
+export function buildAdminCommands() {
+    return {
+        doctor: 'npm run doctor',
+        status: 'npm run status',
+        verify: 'npm run verify',
+        deploy_local: 'npm run deploy:local',
+        deploy_space: 'npm run deploy:space',
+        agent_doctor: 'npm run agent:doctor',
+        hf_space_doctor: 'npm run doctor:hf-space',
+        hf_space_smoke: 'npm run smoke:hf-space'
+    };
+}
+
+export function parseGitStatusEntries(output) {
+    const entries = output.split('\0').filter(Boolean);
+    const paths = [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const status = entry.slice(0, 2);
+        paths.push(entry.slice(3));
+        if (status.includes('R') || status.includes('C')) index += 1;
+    }
+    return paths;
+}
+
+function readEnv(env, key) {
+    const value = env[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function shouldSetStatusEnv(key, baseEnv, statusEnv, options) {
+    if (baseEnv[key] !== undefined) return false;
+    return options.override || statusEnv[key] === undefined;
+}
+
+function loadStatusEnvFile(statusEnv, baseEnv, options) {
+    if (!existsSync(options.path)) return;
+    for (const line of readFileSync(options.path, 'utf8').split(/\r?\n/)) {
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!match || !shouldSetStatusEnv(match[1], baseEnv, statusEnv, options)) continue;
+        const value = match[2].trim();
+        const quoted =
+            value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")));
+        statusEnv[match[1]] = quoted ? value.slice(1, -1) : value;
+    }
+}
+
+export function readStatusEnvFromFiles(baseEnv = process.env, envFiles = STATUS_ENV_FILES) {
+    const statusEnv = { ...baseEnv };
+    for (const envFile of envFiles) {
+        loadStatusEnvFile(statusEnv, baseEnv, envFile);
+    }
+    return statusEnv;
+}
+
+function readSmokeEnvAlternatives(testCase, suffix) {
+    const keys = [`${testCase.prefix}_${suffix}`];
+    if (testCase.fallbackPrefix && testCase.fallbackPrefix !== testCase.prefix) {
+        keys.push(`${testCase.fallbackPrefix}_${suffix}`);
+    }
+    return keys;
+}
+
+function readResponsesModelEnvAlternatives(testCase) {
+    return [`${testCase.prefix}_RESPONSES_MODEL`, 'OPENAI_RESPONSES_API_MODEL'];
+}
+
+function readFirstStatusEnv(env, keys) {
+    for (const key of keys) {
+        const value = readEnv(env, key);
+        if (value) return { key, value };
+    }
+    return undefined;
+}
+
+function readBaseUrlValidationError(value) {
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        return 'must_be_http_or_https_absolute_url';
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return 'must_use_http_or_https';
+    if (url.username || url.password) return 'must_not_include_credentials';
+    if (url.search || url.hash) return 'must_not_include_query_or_fragment';
+    return undefined;
+}
+
+function readTargetConfigured(testCase, env) {
+    const baseUrl = readFirstStatusEnv(env, readSmokeEnvAlternatives(testCase, 'BASE_URL'));
+    const apiKey = readFirstStatusEnv(env, readSmokeEnvAlternatives(testCase, 'API_KEY'));
+    const responsesModel = testCase.requiresResponsesModel
+        ? readFirstStatusEnv(env, readResponsesModelEnvAlternatives(testCase))
+        : undefined;
+    const baseUrlError = baseUrl ? readBaseUrlValidationError(baseUrl.value) : undefined;
+    return {
+        baseUrl: Boolean(baseUrl),
+        apiKey: Boolean(apiKey),
+        responsesModel: Boolean(responsesModel),
+        invalidEnv: baseUrlError ? [{ key: baseUrl.key, reason: baseUrlError }] : []
+    };
+}
+
+function readMissingEnvAny(testCase, target) {
+    const groups = [];
+    if (!target.baseUrl) groups.push(readSmokeEnvAlternatives(testCase, 'BASE_URL'));
+    if (target.baseUrl && !target.apiKey) groups.push(readSmokeEnvAlternatives(testCase, 'API_KEY'));
+    if (target.baseUrl && testCase.requiresResponsesModel && !target.responsesModel) {
+        groups.push(readResponsesModelEnvAlternatives(testCase));
+    }
+    return groups;
+}
+
+export function buildImageUpstreamRealSmokeStatus(env = process.env) {
+    const caseSummaries = IMAGE_UPSTREAM_REAL_SMOKE_CASES.map((testCase) => {
+        const target = readTargetConfigured(testCase, env);
+        const missingEnvAny = readMissingEnvAny(testCase, target);
+        return {
+            id: testCase.id,
+            configured: missingEnvAny.length === 0 && target.invalidEnv.length === 0,
+            ...(missingEnvAny.length > 0 ? { missing_env_any: missingEnvAny } : {}),
+            ...(target.invalidEnv.length > 0 ? { invalid_env: target.invalidEnv } : {})
+        };
+    });
+    const configuredCases = caseSummaries.filter((item) => item.configured).map((item) => item.id);
+    const missingCases = caseSummaries.filter(
+        (item) => Array.isArray(item.missing_env_any) && item.missing_env_any.length > 0
+    );
+    const invalidCases = caseSummaries.filter((item) => Array.isArray(item.invalid_env) && item.invalid_env.length > 0);
+    return {
+        required_count: IMAGE_UPSTREAM_REAL_SMOKE_CASES.length,
+        required_cases: IMAGE_UPSTREAM_REAL_SMOKE_CASES.map((testCase) => testCase.id),
+        configuration_complete: missingCases.length === 0 && invalidCases.length === 0,
+        configured_count: configuredCases.length,
+        configured_cases: configuredCases,
+        missing_count: missingCases.length,
+        missing_cases: missingCases.map((item) => item.id),
+        missing_env_any: Object.fromEntries(missingCases.map((item) => [item.id, item.missing_env_any])),
+        invalid_count: invalidCases.length,
+        invalid_cases: invalidCases.map((item) => item.id),
+        invalid_env: Object.fromEntries(invalidCases.map((item) => [item.id, item.invalid_env])),
+        final_gate_command: IMAGE_UPSTREAM_FINAL_GATE_COMMAND
+    };
+}
+
+function parseArgs(argv) {
+    const unknown = argv.find((arg) => !['--help', '-h', '--remote'].includes(arg));
+    if (unknown) throw new Error(`Unknown option: ${unknown}`);
+    return {
+        help: argv.includes('--help') || argv.includes('-h'),
+        remote: argv.includes('--remote')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run status
+  npm run status -- --remote
+
+Options:
+  --remote       Include read-only Hugging Face Space runtime info.
+  --help         Show this help.`);
+}
+
+function buildLocalStatus() {
+    const packageJson = JSON.parse(readFileSync('package.json', 'utf8'));
+    const branch = runCommandStrict('git', ['branch', '--show-current']).trim();
+    const head = runCommandStrict('git', ['rev-parse', '--short', 'HEAD']).trim();
+    const changed = parseGitStatusEntries(runCommandStrict('git', ['status', '--porcelain=v1', '-z']));
+    return {
+        product: packageJson.name,
+        version: packageJson.version,
+        branch,
+        head,
+        dirty: changed.length > 0,
+        changed_files: changed,
+        node: process.version,
+        commands: buildAdminCommands(),
+        space: {
+            id: HF_SPACE_ID,
+            url: HF_SPACE_URL
+        },
+        agent: {
+            capabilities: '/api/agent/capabilities',
+            skill: 'skills/gpt-image-playground-agent/SKILL.md'
+        },
+        image_upstream_real_smoke: buildImageUpstreamRealSmokeStatus(readStatusEnvFromFiles(process.env))
+    };
+}
+
+export function readRemoteStatusFromResult(result) {
+    if (!result.ok) {
+        return { ok: false, error: result.error || result.stderr || result.stdout || 'Cannot read Hugging Face Space info.' };
+    }
+    let info;
+    try {
+        info = parseJsonPayload(result.stdout, 'hf spaces info');
+    } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    return {
+        ok: true,
+        stage: info.runtime?.stage || 'unknown',
+        sha: info.sha || info.runtime?.raw?.sha || 'unknown',
+        hardware: info.runtime?.hardware || info.hardware || 'unknown'
+    };
+}
+
+function readRemoteStatus() {
+    return readRemoteStatusFromResult(
+        runCommand('hf', ['spaces', 'info', HF_SPACE_ID, '--format', 'json'], { timeoutMs: REMOTE_STATUS_TIMEOUT_MS })
+    );
+}
+
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+
+    const status = buildLocalStatus();
+    printJson({
+        ok: true,
+        ...status,
+        ...(options.remote ? { remote: readRemoteStatus() } : {})
+    });
+}
+
+try {
+    if (isMainModule(import.meta.url, process.argv[1])) main();
+} catch (error) {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+}

scripts/test-postgres-live.mjs

@@ -6,9 +6,17 @@ const testFiles = ['src/lib/agent-state-postgres.test.ts', 'src/app/api/agent/ag
 const POSTGRES_READY_ATTEMPTS = 30;
 const POSTGRES_READY_INTERVAL_MS = 1000;
 
+class CommandFailedError extends Error {
+  constructor(command, args, status, stderr = '') {
+    super(`${command} ${args.join(' ')} failed with exit code ${status}`);
+    this.status = status;
+    this.stderr = stderr;
+  }
+}
+
 function run(command, args, options = {}) {
   const result = spawnSync(command, args, {
-    stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : options.silent ? 'ignore' : 'inherit',
+    stdio: options.capture || options.silent ? ['ignore', 'pipe', 'pipe'] : 'inherit',
     encoding: 'utf8',
     env: options.env || process.env
   });
@@ -16,7 +24,7 @@ function run(command, args, options = {}) {
     return result;
   }
   if (result.status !== 0) {
-    process.exit(result.status || 1);
+    throw new CommandFailedError(command, args, result.status || 1, result.stderr || '');
   }
   return result;
 }
@@ -31,6 +39,10 @@ function runTests(databaseUrl) {
   });
 }
 
+function statusFromError(error) {
+  return error instanceof CommandFailedError ? error.status : 1;
+}
+
 async function waitForPostgres(containerName) {
   for (let attempt = 0; attempt < POSTGRES_READY_ATTEMPTS; attempt += 1) {
     const result = spawnSync('docker', ['exec', containerName, 'pg_isready', '-U', 'agent_test', '-d', 'agent_test'], {
@@ -56,7 +68,11 @@ function readMappedPort(containerName) {
 }
 
 if (process.env.AGENT_POSTGRES_TEST_DATABASE_URL) {
-  runTests(process.env.AGENT_POSTGRES_TEST_DATABASE_URL);
+  try {
+    runTests(process.env.AGENT_POSTGRES_TEST_DATABASE_URL);
+  } catch (error) {
+    process.exit(statusFromError(error));
+  }
   process.exit(0);
 }
 
@@ -81,6 +97,15 @@ try {
   await waitForPostgres(containerName);
   const port = readMappedPort(containerName);
   runTests(`postgres://agent_test:agent_test@127.0.0.1:${port}/agent_test`);
+} catch (error) {
+  process.exitCode = statusFromError(error);
+  if (error instanceof CommandFailedError) {
+    if (error.stderr.trim()) {
+      console.error(error.stderr.trim());
+    }
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
 } finally {
   spawnSync('docker', ['rm', '-f', containerName], { stdio: 'ignore' });
 }

scripts/test-postgres-live.test.mjs

@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const scriptPath = fileURLToPath(new URL('./test-postgres-live.mjs', import.meta.url));
+
+describe('live PostgreSQL test launcher cleanup', () => {
+    it('removes the temporary PostgreSQL container when the test command fails', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'pg-live-launcher-'));
+        const logPath = path.join(tempDir, 'docker.log');
+        const binDir = path.join(tempDir, 'bin');
+        await mkdir(binDir);
+        await writeFile(path.join(binDir, 'node'), buildFailingNodeShim(), { mode: 0o755 });
+        await writeFile(path.join(binDir, 'docker'), buildDockerShim(logPath), { mode: 0o755 });
+
+        try {
+            const result = spawnSync(process.execPath, [scriptPath], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: {
+                    ...process.env,
+                    PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`
+                }
+            });
+
+            assert.equal(result.status, 37, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            const dockerLog = await readFile(logPath, 'utf8');
+            assert.match(dockerLog, /^run /m);
+            assert.match(dockerLog, /^exec /m);
+            assert.match(dockerLog, /^port /m);
+            assert.match(dockerLog, /^rm -f gpt-image-agent-test-pg-/m);
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it('preserves the test exit code when a PostgreSQL URL is provided', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'pg-live-launcher-'));
+        const logPath = path.join(tempDir, 'docker.log');
+        const binDir = path.join(tempDir, 'bin');
+        await mkdir(binDir);
+        await writeFile(path.join(binDir, 'node'), buildFailingNodeShim(), { mode: 0o755 });
+        await writeFile(path.join(binDir, 'docker'), buildDockerShim(logPath), { mode: 0o755 });
+
+        try {
+            const result = spawnSync(process.execPath, [scriptPath], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: {
+                    ...process.env,
+                    AGENT_POSTGRES_TEST_DATABASE_URL: 'postgres://agent_test:agent_test@127.0.0.1:55432/agent_test',
+                    PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`
+                }
+            });
+
+            assert.equal(result.status, 37, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            await assert.rejects(readFile(logPath, 'utf8'), { code: 'ENOENT' });
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it('surfaces Docker startup stderr when the temporary container cannot start', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'pg-live-launcher-'));
+        const logPath = path.join(tempDir, 'docker.log');
+        const binDir = path.join(tempDir, 'bin');
+        await mkdir(binDir);
+        await writeFile(path.join(binDir, 'node'), buildFailingNodeShim(), { mode: 0o755 });
+        await writeFile(path.join(binDir, 'docker'), buildFailingDockerRunShim(logPath), { mode: 0o755 });
+
+        try {
+            const result = spawnSync(process.execPath, [scriptPath], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: {
+                    ...process.env,
+                    PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`
+                }
+            });
+
+            assert.equal(result.status, 42, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+            assert.match(result.stderr, /docker daemon unavailable/);
+            const dockerLog = await readFile(logPath, 'utf8');
+            assert.match(dockerLog, /^run /m);
+            assert.match(dockerLog, /^rm -f gpt-image-agent-test-pg-/m);
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+});
+
+function buildFailingNodeShim() {
+    return `#!/bin/sh
+exit 37
+`;
+}
+
+function buildDockerShim(logPath) {
+    return `#!/bin/sh
+printf '%s\\n' "$*" >> ${JSON.stringify(logPath)}
+case "$1" in
+  run)
+    exit 0
+    ;;
+  exec)
+    exit 0
+    ;;
+  port)
+    printf '127.0.0.1:55432\\n'
+    exit 0
+    ;;
+  rm)
+    exit 0
+    ;;
+  *)
+    exit 2
+    ;;
+esac
+`;
+}
+
+function buildFailingDockerRunShim(logPath) {
+    return `#!/bin/sh
+printf '%s\\n' "$*" >> ${JSON.stringify(logPath)}
+case "$1" in
+  run)
+    printf 'docker daemon unavailable\\n' >&2
+    exit 42
+    ;;
+  rm)
+    exit 0
+    ;;
+  *)
+    exit 2
+    ;;
+esac
+`;
+}

scripts/verify.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { isMainModule, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
+
+const FULL_VERIFY_PLAN = [
+    { name: 'test', command: 'npm', args: ['test'] },
+    { name: 'lint', command: 'npm', args: ['run', 'lint'] },
+    { name: 'lint:scripts', command: 'npm', args: ['run', 'lint:scripts'] },
+    { name: 'build', command: 'npm', args: ['run', 'build'] },
+    { name: 'diff-check', command: 'git', args: ['diff', '--check'] },
+    { name: 'diff-cached-check', command: 'git', args: ['diff', '--cached', '--check'] }
+];
+
+const QUICK_VERIFY_PLAN = [
+    { name: 'test:scripts', command: 'npm', args: ['run', 'test:scripts'] },
+    { name: 'lint:scripts', command: 'npm', args: ['run', 'lint:scripts'] },
+    { name: 'diff-check', command: 'git', args: ['diff', '--check'] },
+    { name: 'diff-cached-check', command: 'git', args: ['diff', '--cached', '--check'] }
+];
+
+const POSTGRES_VERIFY_STEP = { name: 'test:postgres', command: 'npm', args: ['run', 'test:postgres'] };
+
+export function buildVerifyPlan(options = {}) {
+    const source = options.quick ? QUICK_VERIFY_PLAN : FULL_VERIFY_PLAN;
+    const plan = source.filter((step) => !(options.skipBuild && step.name === 'build'));
+    if (!options.postgres) return plan;
+    const firstDiffCheckIndex = plan.findIndex((step) => step.name.startsWith('diff-'));
+    if (firstDiffCheckIndex === -1) return [...plan, POSTGRES_VERIFY_STEP];
+    return [...plan.slice(0, firstDiffCheckIndex), POSTGRES_VERIFY_STEP, ...plan.slice(firstDiffCheckIndex)];
+}
+
+function parseArgs(argv) {
+    const unknown = argv.find((arg) => !['--help', '-h', '--quick', '--skip-build', '--postgres'].includes(arg));
+    if (unknown) throw new Error(`Unknown option: ${unknown}`);
+    return {
+        help: argv.includes('--help') || argv.includes('-h'),
+        postgres: argv.includes('--postgres'),
+        quick: argv.includes('--quick'),
+        skipBuild: argv.includes('--skip-build')
+    };
+}
+
+function printHelp() {
+    console.log(`Usage:
+  npm run verify
+  npm run verify -- --quick
+
+Options:
+  --quick        Run script tests, script syntax checks, and git diff whitespace checks.
+  --postgres     Include the live PostgreSQL gate with npm run test:postgres.
+  --skip-build   Run the full plan without npm run build.
+  --help         Show this help.`);
+}
+
+function runVerify(options) {
+    const checks = [];
+    for (const step of buildVerifyPlan(options)) {
+        const result = runCommand(step.command, step.args);
+        checks.push({
+            name: step.name,
+            command: [step.command, ...step.args].join(' '),
+            status: result.ok ? 'pass' : 'fail',
+            elapsed_ms: result.elapsed_ms,
+            ...(result.ok ? {} : { output: pickFailureOutput(result) })
+        });
+        if (!result.ok) break;
+    }
+
+    const ok = checks.every((check) => check.status === 'pass');
+    printJson({ ok, profile: options.quick ? 'quick' : 'full', postgres: Boolean(options.postgres), checks });
+    if (!ok) process.exit(1);
+}
+
+try {
+    if (isMainModule(import.meta.url, process.argv[1])) {
+        const options = parseArgs(process.argv.slice(2));
+        if (options.help) {
+            printHelp();
+        } else {
+            runVerify(options);
+        }
+    }
+} catch (error) {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+}

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

@@ -7,29 +7,40 @@ description: 当用户需要通过 API 调用已部署的 GPT Image Playground
 
 通过用户已部署的 GPT Image Playground `/api/agent/*` 接口生成或编辑图片。不要假设服务一定在本机；不要模拟网页表单；直接使用 Agent API 契约、幂等键和产物 URL。
 
+## 路由硬规则
+
+- 先读取 `GET /api/agent/capabilities` 的 `routing_rules`，按机器可读规则选择端点。
+- `edit` 且 `max(width,height)>2048` 时，必须使用页面端 `POST /api/images` form-data SSE 路径，不要走非流式 `/api/agent/images/edit`。
+- 复杂 UI 批量出图优先使用页面端 `POST /api/images` SSE，并记录切换原因、失败清单和续跑锚点。
+- 长图恢复或需要续跑锚点的生产请求优先使用页面端 `POST /api/images` SSE，保留局部进度和缺最终图诊断。
+- 普通小图单次文生图使用 `/api/agent/images/generate`；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE，流式失败后先诊断，再显式选择 Agent JSON 或 job 路径，不自动回退。
+- 同一个已进入终态 `failed` 的 `Idempotency-Key` 只会回放失败；重新尝试必须先诊断原因，再创建新的业务操作和新的 key。
+
 ## 执行流程
 
 1. 先定位服务基础地址。优先使用用户明确提供的 URL；其次使用 `GPT_IMAGE_PLAYGROUND_URL`；都没有时尝试默认地址 `http://localhost:4783`。
 2. 用候选基础地址请求 `GET /api/agent/capabilities`。如果默认地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，向用户询问实际部署地址、端口、域名和是否需要鉴权。
-3. 读取 capabilities 中的认证方式、模型、模型级限制、Agent 流式边界、状态后端和端点路径；不要硬编码假设部署方式。
-4. 为每个业务操作生成稳定的 `Idempotency-Key`。同一操作重试时复用原 key；不同操作不要复用。
-5. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点是非流式端点，当前固定以 `stream: false` 调上游。
+3. 读取 capabilities 中的认证方式、模型、模型级限制、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
+4. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
+5. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点对外始终返回最终 `AgentImageResponse` JSON；如 capabilities 声明 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用内部上游 SSE 消费。
 6. 图片编辑使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段使用 `image_0..image_9`。该 Agent 端点同样是非流式端点。
 7. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
-8. 不要把页面端 `POST /api/images` 当成 Agent 默认路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明。
-9. 读取 `agent_jobs`。若 `supported=true` 且 `mode=job_polling`，4K/high 或长耗时任务优先走 job/polling。
+8. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复或明确诊断后切换。
+9. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
 10. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
 11. 返回结果时优先给出 `content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。
 
 ## 鉴权
 
-如果服务端配置了 `AGENT_API_TOKEN`，发送：
+Agent JSON、Agent edit、job 和 artifact 端点的鉴权以 `auth.schemes` 为准。如果服务端配置了 `AGENT_API_TOKEN`，发送：
 
 ```text
 Authorization: Bearer <token>
 ```
 
-此时服务端只接受 Bearer token，不会回退到访问码哈希。如果未配置 `AGENT_API_TOKEN` 但配置了页面访问码 `APP_PASSWORD`，发送 `X-App-Password-Hash`。下载或删除产物时必须复用 capabilities 声明的同一鉴权方式。
+此时 Agent 端点只接受 Bearer token，不会回退到访问码哈希。如果未配置 `AGENT_API_TOKEN` 但配置了页面访问码 `APP_PASSWORD`，Agent 端点发送 `X-App-Password-Hash`。下载或删除产物时必须复用 capabilities 声明的同一 Agent 鉴权方式。
+
+页面端 `/api/images` SSE 是独立页面契约，读取 `agent_streaming.page_sse.auth`。当该字段声明 `required=true` 时，必须在 form-data 中发送 `passwordHash`；脚本侧对应环境变量是 `GPT_IMAGE_APP_PASSWORD_HASH`。即使 `auth.schemes` 只返回 `bearer`，混合配置下 page SSE 仍可能需要这个表单访问码哈希。页面 SSE 还会把同一业务 key 写入 form-data `clientRequestId`，长度不得超过 `agent_streaming.page_sse.client_request_id.max_length`。
 
 ## 调用约束
 
@@ -39,13 +50,14 @@ Authorization: Bearer <token>
 - 不要把 `error.message` 当成唯一判断依据；稳定分支以 `error.code` 和 HTTP 状态为准。
 - 不要在没有 `Idempotency-Key` 的情况下调用生成或编辑接口。
 - 不要对同一个已进入终态 `failed` 的 `Idempotency-Key` 继续重试。终态失败回放会返回 `retryable=false`；需要重新尝试时，先确认失败原因，再创建新的业务操作和新的 `Idempotency-Key`。
-- 不要把 `agent_streaming.page_sse.supported=true` 解读为 `/api/agent/images/generate` 支持流式；Agent generate/edit 当前以 `non_streaming_only` 声明。
+- 不要把 `agent_streaming.page_sse.supported=true` 解读为 `/api/agent/images/generate` 会对客户端返回 SSE；Agent generate/edit 对外仍是最终 JSON。`agent_streaming.upstream_sse` 仅表示服务端内部可消费上游 SSE 并保存最终 artifact。
 - 不要调用 job endpoints，除非 capabilities 明确返回 `agent_jobs.supported=true` 且 `mode=job_polling`。
-- 不要把一次高分辨率、高质量长耗时失败归纳为全局不可用。优先查看 `error.diagnostics.upstream_status`、`transport_error`、`selected_channel_id`、`channel_cooldown_scope` 和 `retry_after_seconds`。
+- 不要把一次高分辨率、高质量长耗时失败归纳为全局不可用。优先查看 `error.diagnostics.upstream_status`、`upstream_event_type`、`partial_image_count`、`transport_error`、`selected_channel_id`、`channel_cooldown_scope` 和 `retry_after_seconds`。
+- 不要在 `error.retryable=false` 时依据历史 `retry_after_seconds` 继续重试同一个 key；终态失败需要新业务操作和新 key。
 
 ## Job Polling
 
-当 `agent_jobs.supported=true` 时，长耗时文生图可使用：
+当 `agent_jobs.supported=true` 时，显式 job 路径可使用：
 
 1. `POST /api/agent/jobs/images/generate` 创建 job，仍必须提供 `Idempotency-Key`。
 2. `GET /api/agent/jobs/{id}` 轮询状态。
@@ -53,7 +65,7 @@ Authorization: Bearer <token>
 
 `GET /result` 在 job 运行中会返回 `request_in_progress` 和 `Retry-After`；不存在返回 `job_not_found`；过期返回 `job_expired`。同一业务操作重试创建 job 时复用原 `Idempotency-Key`，服务会返回同一个 job。
 
-当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。若服务进程在 job 结束前重启，客户端应按状态和错误码继续轮询或重新创建同一 `Idempotency-Key` 的 job。若 job 已进入 `failed` 终态，`GET /result` 和状态摘要都会返回 `retryable=false`，并保留 `code`、`message`、`upstream_status` 和 `diagnostics` 用于定位原因，但同一个 key 不会触发新执行。需要重新尝试时，先确认失败原因，再以新的业务操作和新的 `Idempotency-Key` 创建 job。
+当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。若服务进程在 job 结束前重启，客户端应按状态和错误码继续轮询或重新创建同一 `Idempotency-Key` 的 job。若 job 已进入 `failed` 终态，`GET /result` 和状态摘要都会返回 `retryable=false`，并保留 `code`、`message`、`upstream_status` 和 `diagnostics` 用于定位原因，但同一个 key 不会触发新执行。需要重新尝试时，先确认失败原因，再以新的业务操作和新的 `Idempotency-Key` 创建 job。默认大图单次文生图已经切到页面端 `/api/images` SSE，job 不是默认路径。
 
 ## 可用脚本
 
@@ -61,6 +73,17 @@ Authorization: Bearer <token>
 - `skills/gpt-image-playground-agent/scripts/edit-image.mjs`：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。
 - `skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
 
+生成和编辑脚本的 dry-run 输出会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。
+
+如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
+
+- `npm run status`：只读查看 git、Space 目标、Agent API、Skill 入口和独立真实图片上游 smoke 配置摘要；会自动读取 `.env.real-smoke.local`，不��出 URL 或 API Key。
+- `npm run doctor`：统一诊断本机与 HF Space 配置，不写 Secret。
+- `npm run verify`：运行提交前基线；需要真实 PostgreSQL gate 时加 `-- --postgres`。
+- `npm run deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。
+- `npm run deploy:space`：部署干净 git HEAD 到固定 Space，并做只读公网验证。
+- `npm run agent:doctor`：执行只读 Agent API 契约检查，不触发真实生图。
+
 生成脚本常用参数：
 
 ```bash
@@ -72,6 +95,19 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   "a product photo of a ceramic mug"
 ```
 
+启用 Agent 内部上游 SSE 时，必须显式传策略字段；脚本仍只输出最终 JSON：
+
+```bash
+node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
+  --allow-billable \
+  --image-backend images-api \
+  --streaming-strategy newapi-keepalive-sse \
+  --partial-images 2 \
+  --size 4096x4096 \
+  --quality high \
+  "a product photo of a ceramic mug"
+```
+
 真实生图必须显式开启：
 
 ```bash
@@ -82,7 +118,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   "a product photo of a ceramic mug"
 ```
 
-生成脚本会在 capabilities 声明 `agent_jobs.supported=true` 后，对 `quality=high` 且最大边不小于 3072 的请求自动使用 job polling。也可以用 `--job` 强制 job polling，或用 `--no-job` 强制同步 Agent generate。
+生成脚本会对 `max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE；如果 capabilities 未声明 `agent_streaming.page_sse.supported=true`，脚本会显式失败，不会静默降级到 Agent JSON。如果页面流式失败，脚本会返回结构化失败结果，先诊断再决定是否用 `--agent` 或 `--job` 重新执行，不会自动发起第二次请求。也可以用 `--page-sse` 强制页面流式，或用 `--agent` 强制非流式 Agent generate，`--job` 仍可显式选择 job 路径。上游流式字段支持 `--image-backend`、`--streaming-strategy`、`--partial-images`；默认不发送这些字段，保持服务端默认非流式基线。
 
 编辑脚本支持 `--model`、`--size`、`--quality`、`--response-mode`、`--timeout-ms`、`--idempotency-key`、`--dry-run` 和 `--allow-billable`。
 
@@ -101,14 +137,14 @@ OPENAI_API_KEY=... node skills/gpt-image-playground-agent/scripts/probe-upstream
 
 - `GPT_IMAGE_PLAYGROUND_URL`：服务基础地址，可指向本机、局域网、云服务器或域名；脚本未设置时默认尝试 `http://localhost:4783`。
 - `GPT_IMAGE_AGENT_TOKEN`：Bearer token。
-- `GPT_IMAGE_APP_PASSWORD_HASH`：使用 `APP_PASSWORD` 访问码部署时发送的 `X-App-Password-Hash`。
+- `GPT_IMAGE_APP_PASSWORD_HASH`：使用 `APP_PASSWORD` 访问码部署时，Agent 端点发送为 `X-App-Password-Hash`，页面 SSE 发送为 form-data `passwordHash`。
 - `GPT_IMAGE_AGENT_IDEMPOTENCY_KEY`：跨脚本进程恢复同一操作时复用的幂等键。
 - `GPT_IMAGE_AGENT_MAX_ATTEMPTS`：最大尝试次数，默认 `3`。
 - `GPT_IMAGE_AGENT_CONTRACT_CHECK=1`：只检查 capabilities 和错误契约，不触发真实生图或编辑。
 
 `GPT_IMAGE_PLAYGROUND_URL` 必须是无凭据、无查询参数、无片段的 `http`/`https` 绝对 base URL。不要把 token、访问码或其他 Secret 放进 URL。生成脚本轮询 job result 时只会携带鉴权头访问同 origin URL，避免异常服务返回外部 `result_url` 后泄露 Bearer token 或访问码哈希。
 
-脚本会把服务返回的相对产物路径补充为绝对 URL，适合调用 Hugging Face Space、云服务器或自定义域名上的公网实例。
+脚本会把服务返回的相对产物路径补充为绝对 URL，页面 SSE 的相对 `path` 会补充 `absolute_path`，适合调用 Hugging Face Space、云服务器或自定义域名上的公网实例。
 
 ## 参考
 

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

@@ -1,5 +1,15 @@
 # GPT Image Playground Agent API 参考
 
+## 目录
+
+- [辅助脚本](#辅助脚本)
+- [能力查询](#能力查询)
+- [Job Polling](#job-polling)
+- [生成图片](#生成图片)
+- [编辑图片](#编辑图片)
+- [产物元数据](#产物元数据)
+- [错误](#错误)
+
 ## 辅助脚本
 
 - `skills/gpt-image-playground-agent/scripts/generate-image.mjs`：JSON 文生图调用。
@@ -9,9 +19,10 @@
 生成和编辑脚本默认只做 dry-run，不触发真实生图或编辑。必须显式添加 `--allow-billable` 才会调用 `/api/agent/images/generate` 或 `/api/agent/images/edit`。
 上游探针默认只检查 DNS、TLS 和 `/models`，必须显式添加 `--allow-billable` 才会调用上游 `/images/generations`。
 脚本支持 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 或 `--contract-check` 做只读契约检查，不触发真实生图或编辑。
-鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。
-当服务返回相对 `content_url` 或 `metadata_url` 时，辅助脚本会额外输出 `absolute_content_url` 和 `absolute_metadata_url`。
+Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，Agent 端点才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。页面端 `/api/images` SSE 另看 `agent_streaming.page_sse.auth`；当其声明 `required=true` 时，form-data 必须包含 `passwordHash`。
+当服务返回相对 `content_url`、`metadata_url` 或页面 SSE `path` 时，辅助脚本会额外输出 `absolute_content_url`、`absolute_metadata_url` 或 `absolute_path`。
 同一个 `Idempotency-Key` 如果已经进入终态 `failed`，再次调用 generate/edit 或 job result/status 只会回放该失败，且 `retryable=false`。需要重新尝试时应创建新的业务操作和新的 `Idempotency-Key`。
+页面端 `/api/images` SSE 会把同一个业务 key 复用到 `clientRequestId`，因此脚本使用的 `Idempotency-Key` 不能超过 capabilities 中 `agent_streaming.page_sse.client_request_id.max_length` 声明的字符数；超长时会直接报错，不会静默截断。
 
 生成脚本参数：
 
@@ -61,24 +72,44 @@ GET /api/agent/capabilities
 
 关键字段：
 
-- `auth.required`：是否需要鉴权。
-- `auth.schemes`：当前部署实际接受的鉴权方案。`AGENT_API_TOKEN` 优先于 `APP_PASSWORD`，两者同时配置时只返回 `bearer`。
+- `auth.required`：Agent 端点是否需要鉴权。
+- `auth.schemes`：Agent 端点当前实际接受的鉴权方案。`AGENT_API_TOKEN` 优先于 `APP_PASSWORD`，两者同时配置时只返回 `bearer`。
 - `model_limits.gpt-image-2.max_edge`：最大单边像素，当前为 `3840`。
 - `model_limits.gpt-image-2.max_pixels`：最大总像素，当前为 `8294400`。
 - `model_limits.gpt-image-2.edge_multiple`：宽高必须是该值的倍数，当前为 `16`。
 - `model_limits.gpt-image-2.max_aspect`：最大长短边比例，当前为 `3`。
 - `model_limits.gpt-image-2.min_pixels`：最小总像素，当前为 `655360`。
 - `model_limits.gpt-image-2.recommended_presets`：推荐尺寸预设。
-- `model_limits.gpt-image-2.high_4k_risk`：高质量 4K 级请求的长耗时风险说明。
+- `model_limits.gpt-image-2.large_image_risk`：大尺寸请求的长耗时风险说明，当前适用于 `max_edge>2048`。
 - `agent_streaming.generate.mode`：当前为 `non_streaming_only`。
 - `agent_streaming.edit.mode`：当前为 `non_streaming_only`。
+- `agent_streaming.upstream_sse`：Agent generate 内部消费上游 SSE 的能力，客户端响应仍是最终 `AgentImageResponse` JSON。
+- `agent_streaming.upstream_sse.image_backends`：支持 `images-api`、`responses-image-generation`。
+- `agent_streaming.upstream_sse.enabled_image_backends`：当前运行时可直接使用的 Agent 上游 SSE 后端；`responses-image-generation` 只有在所需环境变量齐备时才出现。
+- `agent_streaming.upstream_sse.streaming_strategies`：支持 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
+- `agent_streaming.upstream_sse.activation_strategies`：会真正向上游发送 `stream=true` 的策略，当前为 `openai-sse`、`newapi-keepalive-sse`、`responses-sse`、`force-sse`。
 - `agent_streaming.page_sse`：页面端 `/api/images` 的 form-data SSE 能力，不代表 Agent generate/edit 支持流式。
+- `agent_streaming.page_sse.auth`：页面 SSE 的独立表单鉴权。`APP_PASSWORD` 已配置时为 `required=true`、`schemes=["form-password-hash"]`、`form_field="passwordHash"`。
+- `agent_streaming.page_sse.client_request_id`：页面 SSE 的请求 ID 契约。脚本会把 `Idempotency-Key` 写入 form-data `clientRequestId`，最大长度以 `max_length` 为准，当前为 `128`。
+- `routing_rules.high_resolution_edit`：`edit` 且最大边大于 `2048` 时必须使用页面端 `/api/images` SSE。
+- `routing_rules.complex_ui_batch`：复杂 UI 批量出图推荐使用页面端 `/api/images` SSE。
+- `routing_rules.long_image_recovery`：长图恢复或续跑锚点场景推荐使用页面端 `/api/images` SSE。
+- `routing_rules.agent_generate_small_smoke`：普通小图单次文生图默认使用 `/api/agent/images/generate`。
+- `routing_rules.page_sse_large_generate`：`max_edge>2048` 的单次文生图推荐优先使用 `/api/images` SSE，失败后先诊断，再显式选择 `/api/agent/images/generate` 或 job 路径。
+- `routing_rules.retry_recovery`：终态失败不会用同一 `Idempotency-Key` 重新执行，必须诊断后创建新的业务操作和新的 key。
+- `defaults.image_backend`：Agent generate 默认 `images-api`。
+- `defaults.streaming_strategy`：Agent generate 默认 `off`，不会默认向上游发送 `stream=true`。
+- `defaults.partial_images`：Agent generate 默认 `2`，仅在显式启用上游 SSE 时使用。
+- `supported.image_backends`：机器可读的图片后端枚举。
+- `supported.enabled_image_backends`：当前运行时可直接使用的图片后端。
+- `supported.image_backend_requirements`：每个图片后端的 required env、missing env 和 enabled 状态；Responses 后端需要 `ENABLE_RESPONSES_IMAGE_BACKEND` 与 `OPENAI_RESPONSES_API_MODEL`。
+- `supported.streaming_strategies`：机器可读的流式兼容策略枚举。
 - `agent_jobs.supported`：当前为 `true`，表示可使用 job polling。
 - `agent_jobs.mode`：当前为 `job_polling`。
 - `agent_jobs.endpoints`：路径为 `POST /api/agent/jobs/images/generate`、`GET /api/agent/jobs/{id}`、`GET /api/agent/jobs/{id}/result`。
 - `agent_jobs.states`：状态机为 `queued`、`running`、`succeeded`、`failed`、`expired`。
 
-当 `agent_jobs.supported=true` 且 `mode=job_polling` 时，4K/high 长耗时请求优先创建 job 并轮询结果；同步 Agent generate 仍适用于普通非流式请求。当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。
+当 `agent_jobs.supported=true` 且 `mode=job_polling` 时，job 路径仍然可用，但普通大图单次文生图的默认路径已经切到页面端 `/api/images` SSE。高分辨率 edit 和复杂 UI 批量生产不应走 Agent 非流式 edit，优先按 `routing_rules` 使用页面端 `/api/images` SSE。当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。大图页面流式失败后不自动回退，先诊断再显式选新路径。
 
 ## Job Polling
 
@@ -147,11 +178,14 @@ Content-Type: application/json
   "output_format": "png",
   "background": "auto",
   "moderation": "auto",
-  "response_mode": "path"
+  "response_mode": "path",
+  "image_backend": "images-api",
+  "streaming_strategy": "off",
+  "partial_images": 2
 }
 ```
 
-Agent 生成端点当前只支持非流式 JSON 响应。不要向该端点发送 `stream: true`；页面 SSE 使用独立的 `POST /api/images` form-data 路径。
+Agent 生成端点对外始终返回最终 JSON，不会对客户端返回 SSE。不要向该端点发送 `stream: true`；页面 SSE 使用独立的 `POST /api/images` form-data 路径。若 capabilities 中 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`streaming_strategy`、`partial_images` 显式启用服务端内部上游 SSE 消费，最终响应仍是 `AgentImageResponse`。
 
 响应：
 
@@ -198,6 +232,8 @@ Content-Type: multipart/form-data
 - `image_0..image_9`：源图片。
 - `mask`：可选 PNG 遮罩。
 
+当 `size` 的最大边大于 `2048` 时，Agent edit 端点会返回 `validation_error`，不会联系上游；该场景必须按 `routing_rules.high_resolution_edit` 使用页面端 `/api/images` form-data SSE 路径。
+
 ## 产物元数据
 
 ```http
@@ -228,6 +264,8 @@ DELETE /api/agent/artifacts/{id}
       "selected_channel_id": "default",
       "upstream_host": "api.example.test",
       "upstream_status": 524,
+      "upstream_event_type": "image_generation.partial_image",
+      "partial_image_count": 1,
       "transport_error": false,
       "retry_after_seconds": 15,
       "channel_cooldown_scope": "channel",

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

@@ -55,6 +55,7 @@ try {
 }
 
 if (options.dryRun || (!contractCheck && !options.allowBillable)) {
+  const routingGuidance = buildEditRoutingGuidance(options);
   console.log(
     JSON.stringify(
       {
@@ -62,6 +63,7 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
         billable: false,
         dry_run: true,
         endpoint: `${baseUrl}/api/agent/images/edit`,
+        routing_guidance: routingGuidance,
         idempotency_key: idempotencyKey,
         request: {
           image_path: imagePath,
@@ -80,6 +82,23 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
   process.exit(0);
 }
 
+const routingGuidance = buildEditRoutingGuidance(options);
+if (routingGuidance.strength === 'must_use') {
+  console.error(
+    JSON.stringify(
+      {
+        ok: false,
+        billable: false,
+        error: '当前请求命中高分辨率 edit 路由硬规则；请使用页面端 /api/images form-data SSE 路径。',
+        routing_guidance: routingGuidance
+      },
+      null,
+      2
+    )
+  );
+  process.exit(2);
+}
+
 function parseArgs(argv) {
   const parsed = {
     model: 'gpt-image-2',
@@ -124,6 +143,30 @@ function absoluteUrl(value) {
   return new URL(value, `${baseUrl}/`).toString();
 }
 
+function buildEditRoutingGuidance(parsed) {
+  if (readMaxImageEdge(parsed.size) > 2048) {
+    return {
+      recommended_endpoint: '/api/images',
+      transport: 'page_sse',
+      strength: 'must_use',
+      reason: 'Agent edit is non-streaming; high-resolution edit should use the page form-data SSE endpoint.'
+    };
+  }
+  return {
+    recommended_endpoint: '/api/agent/images/edit',
+    transport: 'agent_json',
+    strength: 'default',
+    reason: 'Normal edit requests can use the Agent JSON response contract.'
+  };
+}
+
+function readMaxImageEdge(size) {
+  if (typeof size !== 'string') return 0;
+  const match = size.match(/^(\d+)x(\d+)$/);
+  if (!match) return 0;
+  return Math.max(Number(match[1]), Number(match[2]));
+}
+
 function enrichImageUrls(result) {
   if (!result || !Array.isArray(result.images)) return result;
   return {

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import { AGENT_ENDPOINTS, buildAgentJobResultPath } from '../../../src/lib/agent-api-paths.mjs';
 import {
   errorMessage,
   normalizeBaseUrl,
@@ -12,6 +13,20 @@ import {
   sleep
 } from './lib/script-utils.mjs';
 
+const IMAGE_BACKENDS = new Set(['images-api', 'images', 'responses', 'responses-image-generation']);
+const RESPONSE_MODES = new Set(['path', 'base64', 'both']);
+const STREAMING_STRATEGIES = new Set([
+  'off',
+  'auto',
+  'openai-sse',
+  'newapi-keepalive-sse',
+  'responses-sse',
+  'force-sse'
+]);
+const MIN_PARTIAL_IMAGES = 1;
+const MAX_PARTIAL_IMAGES = 3;
+const MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH = 128;
+const PAGE_SSE_ENDPOINT = '/api/images';
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 const contractCheck = process.env.GPT_IMAGE_AGENT_CONTRACT_CHECK === '1' || process.argv.includes('--contract-check');
@@ -73,8 +88,9 @@ if (isNonBillableDryRun(options, contractCheck)) {
         ok: true,
         billable: false,
         dry_run: true,
-        endpoint: dryRunEndpoint(options.jobMode),
-        job_mode: options.jobMode,
+        endpoint: dryRunEndpoint(requestBody, options.routeMode),
+        route_mode: options.routeMode,
+        routing_guidance: buildGenerateRoutingGuidance(requestBody, options.routeMode),
         idempotency_key: idempotencyKey,
         request: requestBody,
         next_step: '重新执行并添加 --allow-billable 才会发起真实生图请求。'
@@ -89,6 +105,10 @@ if (isNonBillableDryRun(options, contractCheck)) {
 try {
   var capabilities = await readCapabilities();
 } catch (error) {
+  if (isScriptError(error)) {
+    console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+    process.exit(1);
+  }
   console.error(errorMessage(error));
   process.exit(1);
 }
@@ -99,12 +119,31 @@ if (contractCheck) {
 }
 
 try {
-  if (shouldUseJobPolling(capabilities, requestBody, options.jobMode)) {
+  if (shouldUseJobPolling(capabilities, options.routeMode)) {
     await runGenerateJob();
+  } else if (shouldUsePageSse(capabilities, requestBody, options.routeMode)) {
+    try {
+      const result = await runPageSseRequest();
+      console.log(
+        JSON.stringify(
+          buildSuccessOutput(formatPageSseOutput(result), { transport: 'page_sse', endpoint: PAGE_SSE_ENDPOINT }),
+          null,
+          2
+        )
+      );
+      process.exit(0);
+    } catch (error) {
+      console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+      process.exit(1);
+    }
   } else {
-    await runGenerateRequest();
+    await runGenerateRequest({ routing: { transport: 'agent_json', endpoint: AGENT_ENDPOINTS.generate } });
   }
 } catch (error) {
+  if (isScriptError(error)) {
+    console.error(JSON.stringify(buildPageSseFailureOutput(error), null, 2));
+    process.exit(1);
+  }
   console.error(errorMessage(error));
   process.exit(1);
 }
@@ -117,10 +156,13 @@ function parseArgs(argv) {
     n: '1',
     format: 'png',
     responseMode: 'path',
+    imageBackend: undefined,
+    streamingStrategy: undefined,
+    partialImages: undefined,
     timeoutMs: undefined,
     promptFile: undefined,
     idempotencyKey: undefined,
-    jobMode: 'auto',
+    routeMode: 'auto',
     dryRun: false,
     allowBillable: false,
     help: false,
@@ -130,8 +172,9 @@ function parseArgs(argv) {
     const arg = argv[index];
     if (arg === '--dry-run') parsed.dryRun = true;
     else if (arg === '--allow-billable') parsed.allowBillable = true;
-    else if (arg === '--job') parsed.jobMode = 'always';
-    else if (arg === '--no-job') parsed.jobMode = 'never';
+    else if (arg === '--job') parsed.routeMode = 'job';
+    else if (arg === '--no-job' || arg === '--agent') parsed.routeMode = 'agent';
+    else if (arg === '--page-sse') parsed.routeMode = 'page_sse';
     else if (arg === '--help' || arg === '-h') parsed.help = true;
     else if (arg === '--contract-check') continue;
     else if (arg === '--model') parsed.model = readOptionValue(argv, (index += 1), arg);
@@ -140,6 +183,9 @@ function parseArgs(argv) {
     else if (arg === '--n') parsed.n = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--format') parsed.format = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--response-mode') parsed.responseMode = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--image-backend') parsed.imageBackend = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--streaming-strategy') parsed.streamingStrategy = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--partial-images') parsed.partialImages = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--prompt-file') parsed.promptFile = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
@@ -160,32 +206,71 @@ function readPrompt(parsed, { readPromptFile }) {
 }
 
 function buildRequestBody(promptValue, parsed) {
-  return {
-    prompt: promptValue || 'contract check',
-    model: parsed.model,
-    n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
-    size: parsed.size,
-    quality: parsed.quality,
-    output_format: normalizeOutputFormat(parsed.format),
-    response_mode: parsed.responseMode
-  };
+  return addUpstreamStrategyFields(
+    {
+      prompt: promptValue || 'contract check',
+      model: parsed.model,
+      n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
+      size: parsed.size,
+      quality: parsed.quality,
+      output_format: normalizeOutputFormat(parsed.format),
+      response_mode: parsed.responseMode
+    },
+    parsed
+  );
 }
 
 function buildDryRunRequestBody(parsed) {
-  const body = {
-    model: parsed.model,
-    n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
-    size: parsed.size,
-    quality: parsed.quality,
-    output_format: normalizeOutputFormat(parsed.format),
-    response_mode: parsed.responseMode
-  };
+  const body = addUpstreamStrategyFields(
+    {
+      model: parsed.model,
+      n: readConfiguredPositiveInteger(parsed.n, '--n', 1),
+      size: parsed.size,
+      quality: parsed.quality,
+      output_format: normalizeOutputFormat(parsed.format),
+      response_mode: parsed.responseMode
+    },
+    parsed
+  );
   if (parsed.promptFile) {
     return { ...body, prompt_file: parsed.promptFile };
   }
   return { ...body, prompt: parsed.promptParts.join(' ') };
 }
 
+function addUpstreamStrategyFields(body, parsed) {
+  validateUpstreamStrategyOptions(parsed);
+  return {
+    ...body,
+    ...(parsed.imageBackend ? { image_backend: parsed.imageBackend } : {}),
+    ...(parsed.streamingStrategy ? { streaming_strategy: parsed.streamingStrategy } : {}),
+    ...(parsed.partialImages ? { partial_images: readPartialImages(parsed.partialImages) } : {})
+  };
+}
+
+function validateUpstreamStrategyOptions(parsed) {
+  if (!RESPONSE_MODES.has(parsed.responseMode)) {
+    throw new Error('--response-mode 必须是 path、base64 或 both。');
+  }
+  if (parsed.imageBackend && !IMAGE_BACKENDS.has(parsed.imageBackend)) {
+    throw new Error('--image-backend 必须是 images-api、images、responses 或 responses-image-generation。');
+  }
+  if (parsed.streamingStrategy && !STREAMING_STRATEGIES.has(parsed.streamingStrategy)) {
+    throw new Error('--streaming-strategy 必须是 off、auto、openai-sse、newapi-keepalive-sse、responses-sse 或 force-sse。');
+  }
+  if (parsed.routeMode === 'page_sse' && parsed.streamingStrategy === 'off') {
+    throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
+  }
+}
+
+function readPartialImages(value) {
+  const parsed = readConfiguredPositiveInteger(value, '--partial-images', 2);
+  if (parsed < MIN_PARTIAL_IMAGES || parsed > MAX_PARTIAL_IMAGES) {
+    throw new Error('--partial-images 必须是 1 到 3 的整数。');
+  }
+  return parsed;
+}
+
 function hasPromptSource(parsed) {
   return Boolean(parsed.promptFile || parsed.promptParts.length > 0);
 }
@@ -217,14 +302,47 @@ function enrichImageUrls(result) {
   };
 }
 
-function dryRunEndpoint(jobMode) {
-  if (jobMode === 'always') return `${baseUrl}/api/agent/jobs/images/generate`;
-  if (jobMode === 'never') return `${baseUrl}/api/agent/images/generate`;
-  return `${baseUrl}/api/agent/images/generate 或 ${baseUrl}/api/agent/jobs/images/generate`;
+function dryRunEndpoint(body, routeMode) {
+  if (routeMode === 'job') return `${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`;
+  if (routeMode === 'agent') return `${baseUrl}${AGENT_ENDPOINTS.generate}`;
+  if (routeMode === 'page_sse') return `${baseUrl}${PAGE_SSE_ENDPOINT}`;
+  return isLargeGenerate(body) && isPageSseAllowed(body)
+    ? `${baseUrl}${PAGE_SSE_ENDPOINT}`
+    : `${baseUrl}${AGENT_ENDPOINTS.generate}`;
+}
+
+function buildGenerateRoutingGuidance(body, routeMode) {
+  if (routeMode === 'job') {
+    return {
+      recommended_endpoint: AGENT_ENDPOINTS.create_generate_job,
+      transport: 'agent_job_polling',
+      strength: 'recommended',
+      reason: 'Explicit --job requests use Agent job polling.'
+    };
+  }
+  if (routeMode === 'page_sse' && !isPageSseAllowed(body)) {
+    throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
+  }
+  if ((routeMode === 'page_sse' || (routeMode !== 'agent' && isLargeGenerate(body))) && isPageSseAllowed(body)) {
+    return {
+      recommended_endpoint: PAGE_SSE_ENDPOINT,
+      transport: 'page_sse',
+      strength: 'recommended',
+      fallback_endpoint: AGENT_ENDPOINTS.generate,
+      fallback_mode: 'manual_after_diagnosis',
+      reason: 'Generate requests with max_edge>2048 should use page form-data SSE first; if the stream fails, diagnose first and rerun manually with Agent JSON.'
+    };
+  }
+  return {
+    recommended_endpoint: AGENT_ENDPOINTS.generate,
+    transport: 'agent_json',
+    strength: 'default',
+    reason: 'Normal single-image generate requests use the Agent JSON response contract.'
+  };
 }
 
 async function readCapabilities() {
-  const { response, result, text } = await fetchJson(`${baseUrl}/api/agent/capabilities`, {
+  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.capabilities}`, {
     headers: authHeaders(),
     timeoutMs
   });
@@ -234,12 +352,12 @@ async function readCapabilities() {
   return result;
 }
 
-async function runGenerateRequest() {
+async function runGenerateRequest(options = {}) {
   let lastResult;
   let lastRetryAfter = null;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const { response, result } = await fetchJson(`${baseUrl}/api/agent/images/generate`, {
+    const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -251,7 +369,7 @@ async function runGenerateRequest() {
     });
 
     if (response.ok) {
-      console.log(JSON.stringify(enrichImageUrls(result), null, 2));
+      console.log(JSON.stringify(buildSuccessOutput(enrichImageUrls(result), options.routing), null, 2));
       process.exit(0);
     }
 
@@ -266,12 +384,340 @@ async function runGenerateRequest() {
   process.exit(1);
 }
 
+async function runPageSseRequest() {
+  const url = `${baseUrl}${PAGE_SSE_ENDPOINT}`;
+  const formData = buildPageSseFormData();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        body: formData,
+        signal: controller.signal
+      });
+    } catch (error) {
+      throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+    }
+    try {
+      const contentType = response.headers.get('content-type') || '';
+      if (contentType.includes('text/event-stream')) {
+        return await collectPageSseResult(response, controller.signal);
+      }
+      const text = await response.text();
+      if (!response.ok) {
+        throw createPageSseHttpError(response.status, readErrorFromJsonText(text) || text);
+      }
+      return parseJsonResponse(text, true, url);
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`请求失败：${url}。${errorMessage(error)}`);
+      }
+      throw error;
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function assertPageSseReady(capabilitiesValue) {
+  const pageSse = capabilitiesValue?.agent_streaming?.page_sse;
+  if (!supportsPageSse(capabilitiesValue)) {
+    throw createScriptError(
+      'page_sse_unavailable',
+      '大图默认路由需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级到 Agent JSON。'
+    );
+  }
+  if (pageSse?.auth?.required === true && !passwordHash) {
+    throw createScriptError(
+      'page_sse_auth_required',
+      '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
+    );
+  }
+}
+
+function buildPageSseFormData() {
+  const formData = new FormData();
+  assertPageSseClientRequestIdLength(idempotencyKey);
+  formData.append('mode', 'generate');
+  formData.append('prompt', requestBody.prompt);
+  formData.append('model', requestBody.model);
+  formData.append('n', String(requestBody.n));
+  formData.append('size', requestBody.size);
+  formData.append('quality', requestBody.quality);
+  formData.append('output_format', requestBody.output_format);
+  formData.append('response_mode', requestBody.response_mode);
+  formData.append('clientRequestId', idempotencyKey);
+  formData.append('stream', 'true');
+  formData.append('partial_images', String(requestBody.partial_images || 2));
+  if (requestBody.image_backend) formData.append('image_backend', normalizeImageBackendForPage(requestBody.image_backend));
+  if (requestBody.streaming_strategy) {
+    formData.append('image_streaming_strategy', requestBody.streaming_strategy);
+  }
+  if (requestBody.background) formData.append('background', requestBody.background);
+  if (requestBody.moderation) formData.append('moderation', requestBody.moderation);
+  if (requestBody.output_compression !== undefined) {
+    formData.append('output_compression', String(requestBody.output_compression));
+  }
+  if (passwordHash) formData.append('passwordHash', passwordHash);
+  return formData;
+}
+
+function assertPageSseClientRequestIdLength(clientRequestId) {
+  if (clientRequestId.length > MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH) {
+    throw createScriptError(
+      'page_sse_client_request_id_too_long',
+      `页面 SSE 的 clientRequestId 不能超过 ${MAX_PAGE_SSE_CLIENT_REQUEST_ID_LENGTH} 个字符；请缩短 Idempotency-Key。`
+    );
+  }
+}
+
+function formatPageSseOutput(result) {
+  if (!result || !Array.isArray(result.images)) return result;
+  return {
+    ...result,
+    images: result.images.map((image) => formatPageSseImage(image))
+  };
+}
+
+function formatPageSseImage(image) {
+  const output = { ...image };
+  if (output.path) {
+    output.absolute_path = absoluteUrl(output.path);
+    if (requestBody.response_mode === 'path') {
+      delete output.b64_json;
+    }
+  }
+  return output;
+}
+
+function normalizeImageBackendForPage(value) {
+  if (value === 'images') return 'images-api';
+  if (value === 'responses') return 'responses-image-generation';
+  return value;
+}
+
+function readPageSseClientRequestId(event) {
+  if (typeof event.clientRequestId === 'string') return event.clientRequestId;
+  if (typeof event.client_request_id === 'string') return event.client_request_id;
+  return undefined;
+}
+
+function normalizePageSseImage(image, fallbackClientRequestId) {
+  const clientRequestId = image.clientRequestId || image.client_request_id || fallbackClientRequestId;
+  return {
+    ...image,
+    output_format: image.outputFormat || image.output_format || requestBody.output_format,
+    ...(clientRequestId ? { clientRequestId } : {})
+  };
+}
+
+function mergePageSseDoneImages(doneImages, completedImages, fallbackClientRequestId) {
+  if (!Array.isArray(doneImages) || doneImages.length === 0) {
+    return completedImages.map((image) => normalizePageSseImage(image, fallbackClientRequestId));
+  }
+  const imageCount = Math.max(doneImages.length, completedImages.length);
+  return Array.from({ length: imageCount }, (_, index) =>
+    normalizePageSseImage({ ...(completedImages[index] || {}), ...(doneImages[index] || {}) }, fallbackClientRequestId)
+  );
+}
+
+async function collectPageSseResult(response, signal) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('页面 SSE 响应缺少 body。');
+  const decoder = new TextDecoder();
+  const state = { completedImages: [], usage: undefined, actualCost: undefined, doneReceived: false };
+  let buffer = '';
+  while (true) {
+    const { done, value } = await readPageSseChunk(reader, signal);
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const events = buffer.split(/\r?\n\r?\n/);
+    buffer = events.pop() || '';
+    for (const rawEvent of events) {
+      applyPageSseEvent(state, rawEvent);
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) applyPageSseEvent(state, buffer);
+  if (state.completedImages.length === 0) {
+    throw new Error('页面 SSE 未返回最终图片。');
+  }
+  if (!state.doneReceived) {
+    throw new Error('页面 SSE 缺少最终 done 事件，流式响应可能已提前中断。');
+  }
+  return { images: state.completedImages, usage: state.usage, actualCost: state.actualCost };
+}
+
+function readPageSseChunk(reader, signal) {
+  if (!signal) return reader.read();
+  if (signal.aborted) {
+    return Promise.reject(new Error('请求超时。'));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(new Error('请求超时。'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    reader.read().then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+function applyPageSseEvent(state, rawEvent) {
+  const event = parsePageSseEvent(rawEvent);
+  if (!event) return;
+  if (event.type === 'error') {
+    throw createPageSseStreamError(event);
+  }
+  if (event.type === 'completed' && event.filename) {
+    state.completedImages.push(
+      normalizePageSseImage(
+        {
+          filename: event.filename,
+          b64_json: event.b64_json,
+          path: event.path,
+          output_format: event.outputFormat || event.output_format || requestBody.output_format
+        },
+        readPageSseClientRequestId(event)
+      )
+    );
+    return;
+  }
+  if (event.type === 'done') {
+    state.doneReceived = true;
+    const clientRequestId = readPageSseClientRequestId(event);
+    state.completedImages = mergePageSseDoneImages(event.images, state.completedImages, clientRequestId);
+    state.usage = event.usage;
+    state.actualCost = event.actualCost !== undefined ? event.actualCost : event.actual_cost;
+  }
+}
+
+function formatPageSseError(value) {
+  if (typeof value === 'string' && value.trim()) return value;
+  if (value && typeof value === 'object') {
+    if (typeof value.message === 'string' && value.message.trim()) return value.message;
+    if (typeof value.code === 'string' && value.code.trim()) return value.code;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '页面 SSE 返回错误事件。';
+    }
+  }
+  return '页面 SSE 返回错误事件。';
+}
+
+function createPageSseStreamError(event) {
+  const error = new Error(formatPageSseError(event.error));
+  const status = readPageSseStreamStatus(event);
+  if (Number.isInteger(status)) {
+    error.streamStatus = status;
+  }
+  return error;
+}
+
+function readPageSseStreamStatus(event) {
+  if (Number.isInteger(event.status)) return event.status;
+  if (event.error && typeof event.error === 'object' && Number.isInteger(event.error.status)) {
+    return event.error.status;
+  }
+  return undefined;
+}
+
+function parsePageSseEvent(rawEvent) {
+  const lines = rawEvent.split(/\r?\n/);
+  const data = lines
+    .filter((line) => line.startsWith('data: '))
+    .map((line) => line.slice(6))
+    .join('\n')
+    .trim();
+  if (!data || data === '[DONE]') return undefined;
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    throw new Error(`页面 SSE 事件不是有效 JSON：${errorMessage(error)}`);
+  }
+}
+
+function buildSuccessOutput(result, routing) {
+  return routing ? { ...result, routing } : result;
+}
+
+function buildPageSseFailureOutput(error) {
+  if (isScriptError(error)) {
+    return buildPageSseScriptFailure(error);
+  }
+  if (isPageSseRequestRejected(error)) {
+    return buildPageSseRequestRejectedFailure(error);
+  }
+  return buildBillablePageSseFailure(error);
+}
+
+function buildPageSseRouting(fallbackMode) {
+  return {
+    transport: 'page_sse',
+    endpoint: PAGE_SSE_ENDPOINT,
+    fallback_endpoint: AGENT_ENDPOINTS.generate,
+    fallback_mode: fallbackMode
+  };
+}
+
+function buildPageSseScriptFailure(error) {
+  return {
+    ok: false,
+    billable: false,
+    error: {
+      code: error.scriptCode,
+      message: errorMessage(error)
+    },
+    routing: buildPageSseRouting('manual_after_diagnosis'),
+    next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到 Agent JSON。'
+  };
+}
+
+function buildPageSseRequestRejectedFailure(error) {
+  return {
+    ok: false,
+    billable: false,
+    error: {
+      code: 'page_sse_request_rejected',
+      status: error.status,
+      message: errorMessage(error)
+    },
+    routing: buildPageSseRouting('fix_request_before_retry'),
+    next_step: '先修正页面端拒绝的请求参数或鉴权，再重新执行；这类本地 4xx 不应按上游计费失败处理。'
+  };
+}
+
+function buildBillablePageSseFailure(error) {
+  return {
+    ok: false,
+    billable: true,
+    error: {
+      code: 'page_sse_failed',
+      ...buildPageSseFailureStatus(error),
+      message: errorMessage(error)
+    },
+    routing: buildPageSseRouting('manual_after_diagnosis'),
+    next_step:
+      '先诊断页面流式失败原因，再决定是否用 --agent 重新执行同一业务请求；不要自动重试同一个请求。'
+  };
+}
+
+function buildPageSseFailureStatus(error) {
+  if (error && typeof error === 'object') {
+    if (Number.isInteger(error.streamStatus)) return { status: error.streamStatus };
+    if (Number.isInteger(error.status)) return { status: error.status };
+  }
+  return {};
+}
+
 async function runGenerateJob() {
   let lastResult;
   let lastRetryAfter = null;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const { response, result } = await fetchJson(`${baseUrl}/api/agent/jobs/images/generate`, {
+    const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -303,7 +749,7 @@ async function pollJobResult(job) {
   if (!job || typeof job.id !== 'string') {
     throw new Error('创建 job 的响应缺少 job.id。');
   }
-  const resultUrl = resolveSameOriginUrl(baseUrl, job.result_url || `/api/agent/jobs/${job.id}/result`, 'job.result_url');
+  const resultUrl = resolveSameOriginUrl(baseUrl, job.result_url || buildAgentJobResultPath(job.id), 'job.result_url');
   const deadlineMs = Date.now() + timeoutMs;
   let lastResult;
   let lastRetryAfter = job.retry_after_seconds || 1;
@@ -328,7 +774,7 @@ async function pollJobResult(job) {
 
 async function runContractCheck(capabilitiesValue) {
   const checks = [];
-  const { response, result } = await fetchJson(`${baseUrl}/api/agent/images/generate`, {
+  const { response, result } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
@@ -338,14 +784,14 @@ async function runContractCheck(capabilitiesValue) {
     timeoutMs
   });
   if (response.status === 400 && result?.error?.code === 'idempotency_key_required') {
-    checks.push({ endpoint: '/api/agent/images/generate', status: response.status, error_code: result.error.code });
+    checks.push({ endpoint: AGENT_ENDPOINTS.generate, status: response.status, error_code: result.error.code });
   } else {
     console.error(JSON.stringify({ ok: false, billable: false, status: response.status, result }, null, 2));
     process.exit(1);
   }
 
   if (supportsJobPolling(capabilitiesValue)) {
-    const jobCheck = await fetchJson(`${baseUrl}/api/agent/jobs/images/generate`, {
+    const jobCheck = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -361,7 +807,7 @@ async function runContractCheck(capabilitiesValue) {
       process.exit(1);
     }
     checks.push({
-      endpoint: '/api/agent/jobs/images/generate',
+      endpoint: AGENT_ENDPOINTS.create_generate_job,
       status: jobCheck.response.status,
       error_code: jobCheck.result.error.code
     });
@@ -371,15 +817,27 @@ async function runContractCheck(capabilitiesValue) {
 }
 
 async function fetchJson(url, init) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), init.timeoutMs);
   try {
-    const fetchInit = { ...init };
-    delete fetchInit.timeoutMs;
-    const response = await fetch(url, { ...fetchInit, signal: controller.signal });
+    const response = await fetchWithTimeout(url, init);
     const text = await response.text();
     const result = parseJsonResponse(text, response.ok, url);
     return { response, result, text };
+  } catch (error) {
+    const message = errorMessage(error);
+    if (message.startsWith(`请求失败：${url}。`)) {
+      throw error;
+    }
+    throw new Error(`请求失败：${url}。${message}`);
+  }
+}
+
+async function fetchWithTimeout(url, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? timeoutMs);
+  try {
+    const fetchInit = { ...init };
+    delete fetchInit.timeoutMs;
+    return await fetch(url, { ...fetchInit, signal: controller.signal });
   } catch (error) {
     const message = errorMessage(error);
     throw new Error(`请求失败：${url}。${message}`);
@@ -388,6 +846,18 @@ async function fetchJson(url, init) {
   }
 }
 
+function readErrorFromJsonText(text) {
+  let result;
+  try {
+    result = parseJsonResponse(text, false, '');
+  } catch {
+    return undefined;
+  }
+  if (typeof result?.error === 'string') return result.error;
+  if (typeof result?.error?.message === 'string') return result.error.message;
+  return undefined;
+}
+
 function parseJsonResponse(text, isOk, url) {
   if (!text) return null;
   try {
@@ -407,16 +877,39 @@ function supportsJobPolling(capabilitiesValue) {
   return Boolean(capabilitiesValue?.agent_jobs?.supported === true && capabilitiesValue.agent_jobs.mode === 'job_polling');
 }
 
-function shouldUseJobPolling(capabilitiesValue, request, jobMode) {
-  if (jobMode === 'never') return false;
+function supportsPageSse(capabilitiesValue) {
+  return Boolean(capabilitiesValue?.agent_streaming?.page_sse?.supported === true);
+}
+
+function shouldUseJobPolling(capabilitiesValue, routeMode) {
+  if (routeMode !== 'job') return false;
   if (!supportsJobPolling(capabilitiesValue)) {
-    if (jobMode === 'always') {
-      throw new Error('服务 capabilities 未声明 agent_jobs.supported=true，不能调用 job endpoint。');
+    throw new Error('服务 capabilities 未声明 agent_jobs.supported=true，不能调用 job endpoint。');
+  }
+  return true;
+}
+
+function shouldUsePageSse(capabilitiesValue, request, routeMode) {
+  if (routeMode === 'agent' || routeMode === 'job') return false;
+  if (!isPageSseAllowed(request)) {
+    if (routeMode === 'page_sse') {
+      throw new Error('streaming_strategy=off 时不能强制使用页面 SSE。');
     }
     return false;
   }
-  if (jobMode === 'always') return true;
-  return request.quality === 'high' && readMaxImageEdge(request.size) >= 3072;
+  if (routeMode === 'page_sse' || isLargeGenerate(request)) {
+    assertPageSseReady(capabilitiesValue);
+    return true;
+  }
+  return false;
+}
+
+function isLargeGenerate(request) {
+  return readMaxImageEdge(request.size) > 2048;
+}
+
+function isPageSseAllowed(request) {
+  return request.streaming_strategy !== 'off';
 }
 
 function readMaxImageEdge(size) {
@@ -426,9 +919,38 @@ function readMaxImageEdge(size) {
   return Math.max(Number(match[1]), Number(match[2]));
 }
 
+function createScriptError(code, message) {
+  const error = new Error(message);
+  error.scriptCode = code;
+  return error;
+}
+
+function isScriptError(error) {
+  return Boolean(error && typeof error === 'object' && typeof error.scriptCode === 'string');
+}
+
+function createPageSseHttpError(status, detail) {
+  const message = detail ? `页面 SSE 请求失败，状态码 ${status}：${detail}` : `页面 SSE 请求失败，状态码 ${status}。`;
+  const error = new Error(message);
+  error.status = status;
+  return error;
+}
+
+function isPageSseRequestRejected(error) {
+  return Boolean(
+    error &&
+      typeof error === 'object' &&
+      Number.isInteger(error.status) &&
+      error.status >= 400 &&
+      error.status < 500
+  );
+}
+
 function printUsage() {
   console.error('用法：generate-image.mjs [options] <prompt>');
   console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
-  console.error('常用参数：--model --size --quality --n --format --response-mode --timeout-ms --prompt-file --idempotency-key --job --no-job');
+  console.error(
+    '常用参数：--model --size --quality --n --format --response-mode --image-backend --streaming-strategy --partial-images --timeout-ms --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
+  );
   console.error('契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 generate-image.mjs 或 generate-image.mjs --contract-check');
 }

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

@@ -1,3 +1,8 @@
+import {
+  CHINESE_POSITIVE_INTEGER_MESSAGES,
+  parsePositiveIntegerConfig
+} from '../../../../src/lib/positive-integer-config.mjs';
+
 const MAX_RETRY_AFTER_SECONDS = 60;
 
 export function readOptionValue(argv, index, name) {
@@ -9,15 +14,9 @@ export function readOptionValue(argv, index, name) {
 }
 
 export function readConfiguredPositiveInteger(value, name, fallback) {
-  if (value === undefined || value === null || value === '') return fallback;
-  if (!/^\d+$/.test(String(value))) {
-    throw new Error(`${name} 必须是正整数。`);
-  }
-  const parsed = Number(value);
-  if (!Number.isSafeInteger(parsed) || parsed < 1) {
-    throw new Error(`${name} 必须是正整数。`);
-  }
-  return parsed;
+  return parsePositiveIntegerConfig(value, name, fallback, {
+    messages: CHINESE_POSITIVE_INTEGER_MESSAGES
+  });
 }
 
 export function normalizeBaseUrl(value) {

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

@@ -1,14 +1,16 @@
+import type { AgentErrorCode } from '@/lib/api-error-response';
+import Database from 'better-sqlite3';
+import type { NextRequest } from 'next/server';
 import assert from 'node:assert/strict';
 import { mkdtemp, readdir, rm } from 'node:fs/promises';
 import http from 'node:http';
+import type { Socket } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, it } from 'node:test';
-import Database from 'better-sqlite3';
 import { Pool } from 'pg';
 
-const PNG_BASE64 =
-    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
+const PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
 
 let originalEnv: NodeJS.ProcessEnv;
 let originalCwd = '';
@@ -41,7 +43,9 @@ beforeEach(async () => {
 });
 
 afterEach(async () => {
-    const { resetAgentStateStoreForTests, setAgentStateStoreFactoryForTests } = await import('@/lib/agent-state-runtime');
+    const { resetAgentStateStoreForTests, setAgentStateStoreFactoryForTests } = await import(
+        '@/lib/agent-state-runtime'
+    );
     const { resetServerChannelStateForTests } = await import('@/lib/server-channel-router');
     restoreProcessEnv(originalEnv);
     process.chdir(originalCwd);
@@ -80,6 +84,23 @@ describe('Agent route integration', () => {
         assert.deepEqual(body.auth.schemes, []);
     });
 
+    it('reports enabled Responses image backend from the deployed runtime environment', async () => {
+        const { getCapabilities } = await loadAgentRoutes();
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+
+        const response = await getCapabilities();
+        assert.equal(response.status, 200);
+        const body = await response.json();
+        assert.deepEqual(body.supported.enabled_image_backends, ['images-api', 'responses-image-generation']);
+        assert.equal(body.supported.image_backend_requirements['responses-image-generation'].enabled, true);
+        assert.deepEqual(body.supported.image_backend_requirements['responses-image-generation'].missing_env, []);
+        assert.deepEqual(body.agent_streaming.upstream_sse.enabled_image_backends, [
+            'images-api',
+            'responses-image-generation'
+        ]);
+    });
+
     it('generates through a compatible upstream once and replays the cached response for the same idempotency key', async () => {
         const { generateImage } = await loadAgentRoutes();
         let upstreamCalls = 0;
@@ -113,6 +134,371 @@ describe('Agent route integration', () => {
         await upstream.close();
     });
 
+    it('does not send upstream stream parameters when Agent streaming_strategy is off', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startImageUpstream((body) => {
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-upstream-stream-off-key', {
+                    prompt: 'agent upstream stream off',
+                    streaming_strategy: 'off'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, false);
+            assert.equal(Object.hasOwn(upstreamJson, 'partial_images'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('consumes upstream image SSE internally while keeping the Agent generate response non-streaming', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'image_generation.partial_image',
+                    data: { type: 'image_generation.partial_image', b64_json: 'agent-partial-base64' }
+                },
+                {
+                    event: 'image_generation.completed',
+                    data: { type: 'image_generation.completed', b64_json: PNG_BASE64 }
+                }
+            ];
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-upstream-sse-key', {
+                    prompt: 'agent upstream sse',
+                    response_mode: 'base64',
+                    streaming_strategy: 'newapi-keepalive-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.cached, false);
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+
+            const upstreamJson = JSON.parse(upstreamBody);
+            assert.equal(upstreamJson.stream, true);
+            assert.equal(upstreamJson.partial_images, 2);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('consumes JSON Images responses returned to Agent stream requests as final results', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startImageUpstream((body) => {
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-stream-json-fallback-key', {
+                    prompt: 'agent stream json fallback',
+                    response_mode: 'base64',
+                    streaming_strategy: 'newapi-keepalive-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, true);
+            assert.equal(upstreamJson.partial_images, 2);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('uses force-sse for Agent upstream image SSE while keeping the final JSON contract', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'image_generation.completed',
+                    data: { type: 'image_generation.completed', b64_json: PNG_BASE64 }
+                }
+            ];
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-force-sse-key', {
+                    prompt: 'agent force sse',
+                    response_mode: 'base64',
+                    streaming_strategy: 'force-sse',
+                    partial_images: 3
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, true);
+            assert.equal(upstreamJson.partial_images, 3);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('consumes Responses image_generation SSE internally while keeping the Agent generate response non-streaming', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingResponsesImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'response.image_generation_call.partial_image',
+                    data: {
+                        type: 'response.image_generation_call.partial_image',
+                        partial_image_b64: 'agent-responses-partial-base64',
+                        partial_image_index: 0
+                    }
+                },
+                {
+                    event: 'response.output_item.done',
+                    data: {
+                        type: 'response.output_item.done',
+                        item: {
+                            type: 'image_generation_call',
+                            status: 'completed',
+                            result: PNG_BASE64
+                        }
+                    }
+                }
+            ];
+        });
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-responses-upstream-sse-key', {
+                    prompt: 'agent responses upstream sse',
+                    response_mode: 'base64',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'responses-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.cached, false);
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.model, 'gpt-5.4');
+            assert.equal(upstreamJson.stream, true);
+            const tools = upstreamJson.tools as Array<Record<string, unknown>>;
+            assert.equal(tools[0].type, 'image_generation');
+            assert.equal(tools[0].partial_images, 2);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('uses force-sse for Agent Responses image_generation SSE while keeping the final JSON contract', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingResponsesImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'response.output_item.done',
+                    data: {
+                        type: 'response.output_item.done',
+                        item: {
+                            type: 'image_generation_call',
+                            status: 'completed',
+                            result: PNG_BASE64
+                        }
+                    }
+                }
+            ];
+        });
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-responses-force-sse-key', {
+                    prompt: 'agent responses force sse',
+                    response_mode: 'base64',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'force-sse',
+                    partial_images: 3
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            const body = await response.json();
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.model, 'gpt-5.4');
+            assert.equal(upstreamJson.stream, true);
+            const tools = upstreamJson.tools as Array<Record<string, unknown>>;
+            assert.equal(tools[0].type, 'image_generation');
+            assert.equal(tools[0].partial_images, 3);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails Agent Responses upstream SSE requests when partial images arrive without a final image', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        const upstream = await startStreamingResponsesImageUpstream(() => [
+            {
+                event: 'response.image_generation_call.partial_image',
+                data: {
+                    type: 'response.image_generation_call.partial_image',
+                    partial_image_b64: 'agent-responses-partial-only',
+                    partial_image_index: 0
+                }
+            }
+        ]);
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-responses-upstream-sse-partial-only-key', {
+                    prompt: 'agent responses upstream sse partial only',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'responses-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 502);
+            const body = await response.json();
+            assert.equal(body.error.code, 'upstream_unavailable');
+            assert.match(body.error.message, /最终图片 b64_json/);
+            assert.equal(body.error.diagnostics.upstream_event_type, 'response.image_generation_call.partial_image');
+            assert.equal(body.error.diagnostics.partial_image_count, 1);
+            assert.equal(body.error.diagnostics.retry_after_seconds, 15);
+            assert.equal(JSON.stringify(body).includes('agent-responses-partial-only'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails Agent Responses upstream SSE requests when the image_generation_call fails', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        const upstream = await startStreamingResponsesImageUpstream(() => [
+            {
+                event: 'response.output_item.done',
+                data: {
+                    type: 'response.output_item.done',
+                    item: {
+                        type: 'image_generation_call',
+                        status: 'failed',
+                        error: {
+                            code: 'content_policy_violation',
+                            message: 'blocked by upstream policy'
+                        }
+                    }
+                }
+            }
+        ]);
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-responses-upstream-sse-failed-call-key', {
+                    prompt: 'agent responses upstream sse failed call',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'responses-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 502);
+            const body = await response.json();
+            assert.equal(body.error.code, 'upstream_unavailable');
+            assert.match(body.error.message, /blocked by upstream policy/);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails Agent upstream SSE requests when partial images arrive without a final image', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        const upstream = await startStreamingImageUpstream(() => [
+            {
+                event: 'image_generation.partial_image',
+                data: { type: 'image_generation.partial_image', b64_json: 'agent-partial-only' }
+            }
+        ]);
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-upstream-sse-partial-only-key', {
+                    prompt: 'agent upstream sse partial only',
+                    streaming_strategy: 'newapi-keepalive-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 502);
+            const body = await response.json();
+            assert.equal(body.error.code, 'upstream_unavailable');
+            assert.match(body.error.message, /最终图片 b64_json/);
+            assert.equal(body.error.diagnostics.upstream_event_type, 'image_generation.partial_image');
+            assert.equal(body.error.diagnostics.partial_image_count, 1);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('generates and replays through the memory state backend without creating SQLite state', async () => {
         process.env.AGENT_STATE_BACKEND = 'memory';
         delete process.env.AGENT_SQLITE_PATH;
@@ -126,12 +512,16 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const first = await generateImage(agentJsonRequest('route-memory-cache-key', { prompt: 'agent memory route success' }));
+            const first = await generateImage(
+                agentJsonRequest('route-memory-cache-key', { prompt: 'agent memory route success' })
+            );
             assert.equal(first.status, 200);
             const firstBody = await first.json();
             assert.equal(firstBody.cached, false);
 
-            const second = await generateImage(agentJsonRequest('route-memory-cache-key', { prompt: 'agent memory route success' }));
+            const second = await generateImage(
+                agentJsonRequest('route-memory-cache-key', { prompt: 'agent memory route success' })
+            );
             assert.equal(second.status, 200);
             const secondBody = await second.json();
             assert.equal(secondBody.cached, true);
@@ -251,6 +641,7 @@ describe('Agent route integration', () => {
             const replay = await generateImage(agentJsonRequest(idempotencyKey, { prompt: 'diagnostics' }));
             assert.equal(replay.status, 502);
             assert.equal(replay.headers.get('x-idempotent-replay'), 'true');
+            assert.equal(replay.headers.get('x-request-id'), body.error.request_id);
             const replayBody = await replay.json();
             assert.equal(replayBody.error.code, 'upstream_unavailable');
             assert.equal(replayBody.error.retryable, false);
@@ -276,7 +667,9 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const created = await createGenerateJob(agentJobJsonRequest('route-job-key', { prompt: 'agent route job' }));
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-key', { prompt: 'agent route job' })
+            );
             assert.equal(created.status, 202);
             const createdBody = await created.json();
             assert.equal(createdBody.job.state, 'running');
@@ -304,6 +697,259 @@ describe('Agent route integration', () => {
         }
     });
 
+    it('creates a generate job that consumes upstream image SSE and saves the final artifact', async () => {
+        const { createGenerateJob, getJobResult, getArtifactContent } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'image_generation.partial_image',
+                    data: { type: 'image_generation.partial_image', b64_json: 'job-partial-base64' }
+                },
+                {
+                    event: 'image_generation.completed',
+                    data: { type: 'image_generation.completed', b64_json: PNG_BASE64 }
+                }
+            ];
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-upstream-sse-key', {
+                    prompt: 'agent job upstream sse',
+                    streaming_strategy: 'newapi-keepalive-sse',
+                    partial_images: 2
+                })
+            );
+            assert.equal(created.status, 202);
+            const createdBody = await created.json();
+
+            const result = await waitForJobResult(getJobResult, createdBody.job.id);
+            assert.equal(result.status, 200);
+            assert.notEqual(result.headers.get('content-type'), 'text/event-stream');
+            const resultBody = await result.json();
+            assert.equal(resultBody.request_id, createdBody.job.id);
+            assert.equal(resultBody.cached, false);
+            assert.equal(resultBody.images.length, 1);
+            assert.equal('b64_json' in resultBody.images[0], false);
+            assert.match(resultBody.images[0].content_url, /^\/api\/agent\/artifacts\/[^/]+\/content$/);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, true);
+            assert.equal(upstreamJson.partial_images, 2);
+
+            const artifactId = resultBody.images[0].content_url.split('/').at(-2);
+            assert.equal(typeof artifactId, 'string');
+            const content = await getArtifactContent(
+                new Request(`http://localhost/api/agent/artifacts/${artifactId}/content`),
+                { params: Promise.resolve({ id: artifactId }) }
+            );
+            assert.equal(content.status, 200);
+            assert.equal(
+                Buffer.compare(Buffer.from(await content.arrayBuffer()), Buffer.from(PNG_BASE64, 'base64')),
+                0
+            );
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails image upstream SSE generate jobs when partial images arrive without a final image', async () => {
+        const { createGenerateJob, getJob, getJobResult } = await loadAgentRoutes();
+        const upstream = await startStreamingImageUpstream(() => [
+            {
+                event: 'image_generation.partial_image',
+                data: { type: 'image_generation.partial_image', b64_json: 'job-images-partial-only' }
+            }
+        ]);
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-images-missing-final-key', {
+                    prompt: 'agent job images partial only',
+                    streaming_strategy: 'newapi-keepalive-sse',
+                    partial_images: 2
+                })
+            );
+            assert.equal(created.status, 202);
+            const createdBody = await created.json();
+
+            const result = await waitForJobResult(getJobResult, createdBody.job.id);
+            assert.equal(result.status, 502);
+            const resultBody = await result.json();
+            assert.equal(resultBody.error.code, 'upstream_unavailable');
+            assert.match(resultBody.error.message, /最终图片 b64_json/);
+            assert.equal(resultBody.error.retryable, false);
+            assert.equal(resultBody.error.diagnostics.upstream_event_type, 'image_generation.partial_image');
+            assert.equal(resultBody.error.diagnostics.partial_image_count, 1);
+            assert.equal(resultBody.error.diagnostics.retry_after_seconds, undefined);
+            assert.equal(JSON.stringify(resultBody).includes('job-images-partial-only'), false);
+
+            const status = await getJob(new Request(`http://localhost/api/agent/jobs/${createdBody.job.id}`), {
+                params: Promise.resolve({ id: createdBody.job.id })
+            });
+            assert.equal(status.status, 200);
+            const statusBody = await status.json();
+            assert.equal(statusBody.job.state, 'failed');
+            assert.equal(statusBody.job.error.code, 'upstream_unavailable');
+            assert.match(statusBody.job.error.message, /最终图片 b64_json/);
+            assert.equal(statusBody.job.error.retryable, false);
+            assert.equal(statusBody.job.error.diagnostics.upstream_event_type, 'image_generation.partial_image');
+            assert.equal(statusBody.job.error.diagnostics.partial_image_count, 1);
+            assert.equal(statusBody.job.error.diagnostics.retry_after_seconds, undefined);
+            assert.equal(JSON.stringify(statusBody).includes('job-images-partial-only'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('creates a generate job that consumes Responses image_generation SSE and saves the final artifact', async () => {
+        const { createGenerateJob, getJobResult, getArtifactContent } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startStreamingResponsesImageUpstream((body) => {
+            upstreamBody = body;
+            return [
+                {
+                    event: 'response.image_generation_call.partial_image',
+                    data: {
+                        type: 'response.image_generation_call.partial_image',
+                        partial_image_b64: 'job-responses-partial-base64',
+                        partial_image_index: 0
+                    }
+                },
+                {
+                    event: 'response.output_item.done',
+                    data: {
+                        type: 'response.output_item.done',
+                        item: {
+                            type: 'image_generation_call',
+                            status: 'completed',
+                            result: PNG_BASE64
+                        }
+                    }
+                }
+            ];
+        });
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-responses-upstream-sse-key', {
+                    prompt: 'agent job responses upstream sse',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'responses-sse',
+                    partial_images: 2
+                })
+            );
+            assert.equal(created.status, 202);
+            const createdBody = await created.json();
+
+            const result = await waitForJobResult(getJobResult, createdBody.job.id);
+            assert.equal(result.status, 200);
+            assert.notEqual(result.headers.get('content-type'), 'text/event-stream');
+            const resultBody = await result.json();
+            assert.equal(resultBody.request_id, createdBody.job.id);
+            assert.equal(resultBody.cached, false);
+            assert.equal(resultBody.images.length, 1);
+            assert.equal('b64_json' in resultBody.images[0], false);
+            assert.match(resultBody.images[0].content_url, /^\/api\/agent\/artifacts\/[^/]+\/content$/);
+
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.model, 'gpt-5.4');
+            assert.equal(upstreamJson.stream, true);
+            assert.equal((upstreamJson.tool_choice as Record<string, unknown>).type, 'image_generation');
+            const tools = upstreamJson.tools as Array<Record<string, unknown>>;
+            assert.equal(tools[0].type, 'image_generation');
+            assert.equal(tools[0].partial_images, 2);
+
+            const artifactId = resultBody.images[0].content_url.split('/').at(-2);
+            assert.equal(typeof artifactId, 'string');
+            const content = await getArtifactContent(
+                new Request(`http://localhost/api/agent/artifacts/${artifactId}/content`),
+                { params: Promise.resolve({ id: artifactId }) }
+            );
+            assert.equal(content.status, 200);
+            assert.equal(
+                Buffer.compare(Buffer.from(await content.arrayBuffer()), Buffer.from(PNG_BASE64, 'base64')),
+                0
+            );
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails Responses upstream SSE generate jobs when partial images arrive without a final image', async () => {
+        const { createGenerateJob, getJob, getJobResult } = await loadAgentRoutes();
+        const upstream = await startStreamingResponsesImageUpstream(() => [
+            {
+                event: 'response.image_generation_call.partial_image',
+                data: {
+                    type: 'response.image_generation_call.partial_image',
+                    partial_image_b64: 'job-responses-partial-only',
+                    partial_image_index: 0
+                }
+            }
+        ]);
+        process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
+        process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-5.4';
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-responses-missing-final-key', {
+                    prompt: 'agent job responses partial only',
+                    image_backend: 'responses-image-generation',
+                    streaming_strategy: 'responses-sse',
+                    partial_images: 2
+                })
+            );
+            assert.equal(created.status, 202);
+            const createdBody = await created.json();
+
+            const result = await waitForJobResult(getJobResult, createdBody.job.id);
+            assert.equal(result.status, 502);
+            const resultBody = await result.json();
+            assert.equal(resultBody.error.code, 'upstream_unavailable');
+            assert.match(resultBody.error.message, /最终图片 b64_json/);
+            assert.equal(resultBody.error.retryable, false);
+            assert.equal(
+                resultBody.error.diagnostics.upstream_event_type,
+                'response.image_generation_call.partial_image'
+            );
+            assert.equal(resultBody.error.diagnostics.partial_image_count, 1);
+            assert.equal(resultBody.error.diagnostics.retry_after_seconds, undefined);
+            assert.equal(JSON.stringify(resultBody).includes('job-responses-partial-only'), false);
+
+            const status = await getJob(new Request(`http://localhost/api/agent/jobs/${createdBody.job.id}`), {
+                params: Promise.resolve({ id: createdBody.job.id })
+            });
+            assert.equal(status.status, 200);
+            const statusBody = await status.json();
+            assert.equal(statusBody.job.state, 'failed');
+            assert.equal(statusBody.job.error.code, 'upstream_unavailable');
+            assert.match(statusBody.job.error.message, /最终图片 b64_json/);
+            assert.equal(statusBody.job.error.retryable, false);
+            assert.equal(
+                statusBody.job.error.diagnostics.upstream_event_type,
+                'response.image_generation_call.partial_image'
+            );
+            assert.equal(statusBody.job.error.diagnostics.partial_image_count, 1);
+            assert.equal(statusBody.job.error.diagnostics.retry_after_seconds, undefined);
+            assert.equal(JSON.stringify(statusBody).includes('job-responses-partial-only'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('reuses the running generate job for the same idempotency key', async () => {
         const { createGenerateJob, getJobResult } = await loadAgentRoutes();
         let releaseUpstream: (() => void) | undefined;
@@ -356,12 +1002,16 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const first = await createGenerateJob(agentJobJsonRequest('route-job-conflict-key', { prompt: 'first job body' }));
+            const first = await createGenerateJob(
+                agentJobJsonRequest('route-job-conflict-key', { prompt: 'first job body' })
+            );
             assert.equal(first.status, 202);
             const firstBody = await first.json();
             await waitFor(() => upstreamCalls === 1);
 
-            const conflict = await createGenerateJob(agentJobJsonRequest('route-job-conflict-key', { prompt: 'different job body' }));
+            const conflict = await createGenerateJob(
+                agentJobJsonRequest('route-job-conflict-key', { prompt: 'different job body' })
+            );
             assert.equal(conflict.status, 409);
             assert.equal((await conflict.json()).error.code, 'idempotency_conflict');
             assert.equal(upstreamCalls, 1);
@@ -386,7 +1036,9 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const created = await createGenerateJob(agentJobJsonRequest('route-job-failure-key', { prompt: 'job failure' }));
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-failure-key', { prompt: 'job failure' })
+            );
             assert.equal(created.status, 202);
             const createdBody = await created.json();
 
@@ -411,11 +1063,123 @@ describe('Agent route integration', () => {
             assert.equal(statusBody.job.error.upstream_status, 500);
             assert.equal(statusBody.job.error.diagnostics.upstream_status, 500);
             assert.equal(upstreamCalls > 0, true);
+
+            const replay = await createGenerateJob(
+                agentJobJsonRequest('route-job-failure-key', { prompt: 'job failure' })
+            );
+            assert.equal(replay.status, 202);
+            assert.equal(replay.headers.get('x-idempotent-replay'), 'true');
+            const replayBody = await replay.json();
+            assert.equal(replayBody.job.id, createdBody.job.id);
+            assert.equal(replayBody.job.state, 'failed');
         } finally {
             await upstream.close();
         }
     });
 
+    it('marks generate jobs as failed when completion state persistence fails', async () => {
+        const { createGenerateJob, getJob } = await loadAgentRoutes();
+        const { setAgentStateStoreFactoryForTests } = await import('@/lib/agent-state-runtime');
+        const requestId = 'job-completion-failure-request';
+        let failErrorCode: AgentErrorCode | undefined;
+        let saveCalls = 0;
+        const upstream = await startImageUpstream(() => ({ data: [{ b64_json: PNG_BASE64 }] }));
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+        setAgentStateStoreFactoryForTests(() => ({
+            async init() {},
+            async recoverExpiredRequests() {
+                return 0;
+            },
+            async purgeExpiredRequests() {
+                return 0;
+            },
+            async beginRequest() {
+                return {
+                    type: 'acquired',
+                    record: {
+                        requestId,
+                        idempotencyKey: 'job-completion-failure-key',
+                        requestHash: 'hash',
+                        mode: 'generate',
+                        status: 'running',
+                        requestJson: { prompt: 'job completion persistence failure' },
+                        createdAt: '2026-05-12T00:00:00.000Z',
+                        updatedAt: '2026-05-12T00:00:00.000Z',
+                        expiresAt: '2099-05-13T00:00:00.000Z'
+                    }
+                };
+            },
+            async refreshRequestLease() {
+                return true;
+            },
+            async saveArtifacts() {
+                saveCalls += 1;
+            },
+            async completeRequest() {
+                throw new Error('job completion persistence failed');
+            },
+            async failRequest(input: { requestId: string; error: { error: { code: AgentErrorCode } } }) {
+                assert.equal(input.requestId, requestId);
+                failErrorCode = input.error.error.code;
+            },
+            async getRequest(id: string) {
+                if (id !== requestId || !failErrorCode) return undefined;
+                return {
+                    requestId,
+                    idempotencyKey: 'job-completion-failure-key',
+                    requestHash: 'hash',
+                    mode: 'generate',
+                    status: 'failed',
+                    requestJson: { prompt: 'job completion persistence failure' },
+                    errorJson: {
+                        error: {
+                            code: failErrorCode,
+                            message: '保存请求完成状态失败。',
+                            retryable: true,
+                            request_id: requestId
+                        }
+                    },
+                    createdAt: '2026-05-12T00:00:00.000Z',
+                    updatedAt: '2026-05-12T00:00:01.000Z',
+                    expiresAt: '2099-05-13T00:00:00.000Z'
+                };
+            },
+            async getArtifact() {
+                return undefined;
+            },
+            async listArtifactsForRequest() {
+                return [];
+            },
+            async deleteArtifact() {
+                return false;
+            }
+        }));
+
+        const originalConsoleError = console.error;
+        console.error = () => {};
+        try {
+            const created = await createGenerateJob(
+                agentJobJsonRequest('job-completion-failure-key', { prompt: 'job completion persistence failure' })
+            );
+            assert.equal(created.status, 202);
+            await waitFor(() => failErrorCode === 'unexpected_error');
+            assert.equal(saveCalls, 1);
+
+            const status = await getJob(new Request(`http://localhost/api/agent/jobs/${requestId}`), {
+                params: Promise.resolve({ id: requestId })
+            });
+            assert.equal(status.status, 200);
+            const statusBody = await status.json();
+            assert.equal(statusBody.job.state, 'failed');
+            assert.equal(statusBody.job.error.code, 'unexpected_error');
+            assert.equal(statusBody.job.error.retryable, false);
+        } finally {
+            console.error = originalConsoleError;
+            await upstream.close();
+        }
+    });
+
     it('keeps a long-running generate job leased while the upstream call is still active', async () => {
         process.env.AGENT_REQUEST_LEASE_MS = '200';
         process.env.AGENT_RECOVERY_INTERVAL_MS = '50';
@@ -433,7 +1197,9 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const created = await createGenerateJob(agentJobJsonRequest('route-job-lease-key', { prompt: 'job lease' }));
+            const created = await createGenerateJob(
+                agentJobJsonRequest('route-job-lease-key', { prompt: 'job lease' })
+            );
             assert.equal(created.status, 202);
             const createdBody = await created.json();
             await waitFor(() => upstreamCalls === 1);
@@ -457,7 +1223,9 @@ describe('Agent route integration', () => {
 
     it('returns structured errors for missing and expired jobs', async () => {
         const { getJob, getJobResult } = await loadAgentRoutes();
-        const { resetAgentStateStoreForTests, setAgentStateStoreFactoryForTests } = await import('@/lib/agent-state-runtime');
+        const { resetAgentStateStoreForTests, setAgentStateStoreFactoryForTests } = await import(
+            '@/lib/agent-state-runtime'
+        );
 
         const missing = await getJob(new Request('http://localhost/api/agent/jobs/missing-job'), {
             params: Promise.resolve({ id: 'missing-job' })
@@ -543,13 +1311,45 @@ describe('Agent route integration', () => {
         await upstream.close();
     });
 
+    it('aborts Agent edit upstream calls when the client request signal aborts', async () => {
+        const { editImage } = await loadAgentRoutes();
+        const upstream = await startHangingImageEditUpstream();
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+        const abortController = new AbortController();
+
+        try {
+            const responsePromise = editImage(
+                agentEditRequest('route-edit-abort-key', 'agent edit abort', {}, 'path', {
+                    signal: abortController.signal
+                })
+            );
+            await waitFor(() => upstream.requests === 1);
+            abortController.abort();
+
+            const response = await Promise.race([
+                responsePromise,
+                new Promise<Response>((_, reject) =>
+                    setTimeout(() => reject(new Error('Agent edit upstream call did not abort')), 1500)
+                )
+            ]);
+
+            assert.notEqual(response.status, 200);
+        } finally {
+            abortController.abort();
+            await upstream.close();
+        }
+    });
+
     it('returns field-level errors for invalid edit multipart requests', async () => {
         const { editImage } = await loadAgentRoutes();
         const upstream = await startImageUpstream(() => ({ data: [{ b64_json: PNG_BASE64 }] }));
         process.env.OPENAI_API_KEY = 'test-key';
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
-        const response = await editImage(agentEditRequest('route-edit-validation-key', 'agent edit invalid', {}, 'url'));
+        const response = await editImage(
+            agentEditRequest('route-edit-validation-key', 'agent edit invalid', {}, 'url')
+        );
 
         assert.equal(response.status, 422);
         const body = await response.json();
@@ -559,6 +1359,93 @@ describe('Agent route integration', () => {
         await upstream.close();
     });
 
+    it('rejects high-resolution Agent edit requests before contacting upstream', async () => {
+        const { editImage } = await loadAgentRoutes();
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream(() => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await editImage(
+                agentEditRequest('route-edit-high-resolution-key', 'high resolution edit', {}, { size: '3072x2048' })
+            );
+
+            assert.equal(response.status, 422);
+            const body = await response.json();
+            assert.equal(body.error.code, 'validation_error');
+            assert.match(body.error.message, /\/api\/images/);
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('rejects high-resolution Agent edit requests before reading files or API credentials', async () => {
+        const { editImage } = await loadAgentRoutes();
+        delete process.env.OPENAI_API_KEY;
+        delete process.env.OPENAI_API_BASE_URL;
+
+        const formData = new FormData();
+        formData.append('prompt', 'high resolution edit without file');
+        formData.append('model', 'gpt-image-2');
+        formData.append('size', '3072x2048');
+        formData.append('response_mode', 'path');
+
+        const response = await editImage(
+            new Request('http://localhost/api/agent/images/edit', {
+                method: 'POST',
+                headers: {
+                    'Idempotency-Key': 'route-edit-high-resolution-no-file-key'
+                },
+                body: formData
+            })
+        );
+
+        assert.equal(response.status, 422);
+        const body = await response.json();
+        assert.equal(body.error.code, 'validation_error');
+        assert.match(body.error.message, /\/api\/images/);
+        assert.equal(body.error.details?.fields?.image_0, undefined);
+        assert.doesNotMatch(body.error.message, /API Key|图片文件/);
+    });
+
+    it('rejects auto-size Agent edit when the uploaded source image is high resolution', async () => {
+        const { editImage } = await loadAgentRoutes();
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream(() => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await editImage(
+                agentEditRequest(
+                    'route-edit-auto-high-resolution-source-key',
+                    'auto high resolution source',
+                    {},
+                    {
+                        size: 'auto',
+                        image_0: createPngWithDimensions(3072, 2048)
+                    }
+                )
+            );
+
+            assert.equal(response.status, 422);
+            const body = await response.json();
+            assert.equal(body.error.code, 'validation_error');
+            assert.match(body.error.message, /\/api\/images/);
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('returns validation errors for non-multipart edit requests', async () => {
         const { editImage } = await loadAgentRoutes();
 
@@ -627,6 +1514,7 @@ describe('Agent route integration', () => {
             const replay = await editImage(agentEditRequest(idempotencyKey, 'edit diagnostics'));
             assert.equal(replay.status, 502);
             assert.equal(replay.headers.get('x-idempotent-replay'), 'true');
+            assert.equal(replay.headers.get('x-request-id'), body.error.request_id);
             const replayBody = await replay.json();
             assert.equal(replayBody.error.code, 'upstream_unavailable');
             assert.equal(replayBody.error.retryable, false);
@@ -703,7 +1591,9 @@ describe('Agent route integration', () => {
         const originalConsoleError = console.error;
         console.error = () => {};
         try {
-            const response = await editImage(agentEditRequest('edit-completion-failure-key', 'state completion failure'));
+            const response = await editImage(
+                agentEditRequest('edit-completion-failure-key', 'state completion failure')
+            );
 
             assert.equal(response.status, 500);
             const body = await response.json();
@@ -727,14 +1617,21 @@ describe('Agent route integration', () => {
         process.env.AGENT_API_TOKEN = 'artifact-token';
 
         const generated = await generateImage(
-            agentJsonRequest('artifact-auth-key', { prompt: 'artifact auth' }, { Authorization: 'Bearer artifact-token' })
+            agentJsonRequest(
+                'artifact-auth-key',
+                { prompt: 'artifact auth' },
+                { Authorization: 'Bearer artifact-token' }
+            )
         );
         const body = await generated.json();
         const artifactId = body.images[0].id;
 
-        const denied = await getArtifactContent(new Request(`http://localhost/api/agent/artifacts/${artifactId}/content`), {
-            params: Promise.resolve({ id: artifactId })
-        });
+        const denied = await getArtifactContent(
+            new Request(`http://localhost/api/agent/artifacts/${artifactId}/content`),
+            {
+                params: Promise.resolve({ id: artifactId })
+            }
+        );
         assert.equal(denied.status, 401);
         assert.equal((await denied.json()).error.code, 'unauthorized');
 
@@ -770,7 +1667,11 @@ describe('Agent route integration', () => {
         assert.equal((await deleted.json()).deleted, true);
 
         const replayAfterDelete = await generateImage(
-            agentJsonRequest('artifact-auth-key', { prompt: 'artifact auth' }, { Authorization: 'Bearer artifact-token' })
+            agentJsonRequest(
+                'artifact-auth-key',
+                { prompt: 'artifact auth' },
+                { Authorization: 'Bearer artifact-token' }
+            )
         );
         assert.equal(replayAfterDelete.status, 404);
         assert.equal((await replayAfterDelete.json()).error.code, 'artifact_not_found');
@@ -785,7 +1686,9 @@ describe('Agent route integration', () => {
         process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
 
         try {
-            const generated = await generateImage(agentJsonRequest('artifact-missing-content-key', { prompt: 'missing content' }));
+            const generated = await generateImage(
+                agentJsonRequest('artifact-missing-content-key', { prompt: 'missing content' })
+            );
             const body = await generated.json();
             const image = body.images[0];
             await rm(readStoredArtifactFilepath(image.id), { force: true });
@@ -868,7 +1771,9 @@ describe('Agent route integration', () => {
         const originalConsoleError = console.error;
         console.error = () => {};
         try {
-            const response = await generateImage(agentJsonRequest('completion-failure-key', { prompt: 'state completion failure' }));
+            const response = await generateImage(
+                agentJsonRequest('completion-failure-key', { prompt: 'state completion failure' })
+            );
 
             assert.equal(response.status, 500);
             const body = await response.json();
@@ -944,7 +1849,9 @@ describe('Agent route integration', () => {
         const originalConsoleError = console.error;
         console.error = () => {};
         try {
-            const response = await generateImage(agentJsonRequest('artifact-save-failure-key', { prompt: 'artifact save failure' }));
+            const response = await generateImage(
+                agentJsonRequest('artifact-save-failure-key', { prompt: 'artifact save failure' })
+            );
 
             assert.equal(response.status, 500);
             const body = await response.json();
@@ -961,57 +1868,67 @@ describe('Agent route integration', () => {
 
 const livePostgresUrl = process.env.AGENT_POSTGRES_TEST_DATABASE_URL;
 
-describe('Agent route PostgreSQL integration', { skip: livePostgresUrl ? false : 'AGENT_POSTGRES_TEST_DATABASE_URL is not set' }, () => {
-    it('allows only one upstream winner for concurrent identical idempotency requests', async () => {
-        assert.ok(livePostgresUrl);
-        const { generateImage } = await loadAgentRoutes();
-        const schemaName = `agent_route_${Date.now().toString(36)}`;
-        const pool = new Pool({ connectionString: livePostgresUrl });
-        process.env.AGENT_STATE_BACKEND = 'postgres';
-        process.env.AGENT_DATABASE_URL = `${livePostgresUrl}${livePostgresUrl.includes('?') ? '&' : '?'}options=-c%20search_path%3D${schemaName}`;
-        process.env.AGENT_REQUEST_LEASE_MS = '60000';
-        const admin = await pool.connect();
-        let releaseUpstream: (() => void) | undefined;
-        let upstreamCalls = 0;
-        const upstream = await startImageUpstream(async () => {
-            upstreamCalls += 1;
-            await new Promise<void>((resolve) => {
-                releaseUpstream = resolve;
+describe(
+    'Agent route PostgreSQL integration',
+    { skip: livePostgresUrl ? false : 'AGENT_POSTGRES_TEST_DATABASE_URL is not set' },
+    () => {
+        it('allows only one upstream winner for concurrent identical idempotency requests', async () => {
+            assert.ok(livePostgresUrl);
+            const { generateImage } = await loadAgentRoutes();
+            const schemaName = `agent_route_${Date.now().toString(36)}`;
+            const pool = new Pool({ connectionString: livePostgresUrl });
+            process.env.AGENT_STATE_BACKEND = 'postgres';
+            process.env.AGENT_DATABASE_URL = `${livePostgresUrl}${livePostgresUrl.includes('?') ? '&' : '?'}options=-c%20search_path%3D${schemaName}`;
+            process.env.AGENT_REQUEST_LEASE_MS = '60000';
+            const admin = await pool.connect();
+            let releaseUpstream: (() => void) | undefined;
+            let upstreamCalls = 0;
+            const upstream = await startImageUpstream(async () => {
+                upstreamCalls += 1;
+                await new Promise<void>((resolve) => {
+                    releaseUpstream = resolve;
+                });
+                return { data: [{ b64_json: PNG_BASE64 }] };
             });
-            return { data: [{ b64_json: PNG_BASE64 }] };
+            process.env.OPENAI_API_KEY = 'test-key';
+            process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+            try {
+                await admin.query(`CREATE SCHEMA "${schemaName}"`);
+                const firstRequest = generateImage(
+                    agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' })
+                );
+                await waitFor(() => upstreamCalls === 1);
+
+                const second = await generateImage(
+                    agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' })
+                );
+                assert.equal(second.status, 409);
+                const secondBody = await second.json();
+                assert.equal(secondBody.error.code, 'request_in_progress');
+                assert.equal(secondBody.error.retryable, true);
+                assert.equal(second.headers.has('retry-after'), true);
+
+                releaseUpstream?.();
+                const first = await firstRequest;
+                assert.equal(first.status, 200);
+
+                const replay = await generateImage(
+                    agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' })
+                );
+                assert.equal(replay.status, 200);
+                assert.equal((await replay.json()).cached, true);
+                assert.equal(upstreamCalls, 1);
+            } finally {
+                releaseUpstream?.();
+                await upstream.close();
+                await admin.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`);
+                admin.release();
+                await pool.end();
+            }
         });
-        process.env.OPENAI_API_KEY = 'test-key';
-        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
-
-        try {
-            await admin.query(`CREATE SCHEMA "${schemaName}"`);
-            const firstRequest = generateImage(agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' }));
-            await waitFor(() => upstreamCalls === 1);
-
-            const second = await generateImage(agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' }));
-            assert.equal(second.status, 409);
-            const secondBody = await second.json();
-            assert.equal(secondBody.error.code, 'request_in_progress');
-            assert.equal(secondBody.error.retryable, true);
-            assert.equal(second.headers.has('retry-after'), true);
-
-            releaseUpstream?.();
-            const first = await firstRequest;
-            assert.equal(first.status, 200);
-
-            const replay = await generateImage(agentJsonRequest('pg-route-concurrent-key', { prompt: 'pg concurrent' }));
-            assert.equal(replay.status, 200);
-            assert.equal((await replay.json()).cached, true);
-            assert.equal(upstreamCalls, 1);
-        } finally {
-            releaseUpstream?.();
-            await upstream.close();
-            await admin.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`);
-            admin.release();
-            await pool.end();
-        }
-    });
-});
+    }
+);
 
 async function loadAgentRoutes() {
     const { resetAgentStateStoreForTests } = await import('@/lib/agent-state-runtime');
@@ -1027,18 +1944,28 @@ async function loadAgentRoutes() {
     const jobRoute = await import('./jobs/[id]/route');
     const jobResultRoute = await import('./jobs/[id]/result/route');
     return {
-        getCapabilities: capabilitiesRoute.GET,
-        generateImage: generateRoute.POST,
-        editImage: editRoute.POST,
-        createGenerateJob: createGenerateJobRoute.POST,
-        getJob: jobRoute.GET,
-        getJobResult: jobResultRoute.GET,
-        getArtifact: artifactRoute.GET,
-        deleteArtifact: artifactRoute.DELETE,
-        getArtifactContent: artifactContentRoute.GET
+        getCapabilities: () => capabilitiesRoute.GET(),
+        generateImage: (request: Request) => generateRoute.POST(asNextRequest(request)),
+        editImage: (request: Request) => editRoute.POST(asNextRequest(request)),
+        createGenerateJob: (request: Request) => createGenerateJobRoute.POST(asNextRequest(request)),
+        getJob: (request: Request, context: AgentRouteContext) => jobRoute.GET(asNextRequest(request), context),
+        getJobResult: (request: Request, context: AgentRouteContext) =>
+            jobResultRoute.GET(asNextRequest(request), context),
+        getArtifact: (request: Request, context: AgentRouteContext) =>
+            artifactRoute.GET(asNextRequest(request), context),
+        deleteArtifact: (request: Request, context: AgentRouteContext) =>
+            artifactRoute.DELETE(asNextRequest(request), context),
+        getArtifactContent: (request: Request, context: AgentRouteContext) =>
+            artifactContentRoute.GET(asNextRequest(request), context)
     };
 }
 
+type AgentRouteContext = { params: Promise<{ id: string }> };
+
+function asNextRequest(request: Request): NextRequest {
+    return request as unknown as NextRequest;
+}
+
 function agentJsonRequest(idempotencyKey: string, body: Record<string, unknown>, headers: Record<string, string> = {}) {
     return new Request('http://localhost/api/agent/images/generate', {
         method: 'POST',
@@ -1051,7 +1978,11 @@ function agentJsonRequest(idempotencyKey: string, body: Record<string, unknown>,
     });
 }
 
-function agentJobJsonRequest(idempotencyKey: string, body: Record<string, unknown>, headers: Record<string, string> = {}) {
+function agentJobJsonRequest(
+    idempotencyKey: string,
+    body: Record<string, unknown>,
+    headers: Record<string, string> = {}
+) {
     return new Request('http://localhost/api/agent/jobs/images/generate', {
         method: 'POST',
         headers: {
@@ -1063,28 +1994,55 @@ function agentJobJsonRequest(idempotencyKey: string, body: Record<string, unknow
     });
 }
 
+type AgentEditRequestFields = {
+    image_0?: Buffer;
+    [field: string]: string | Buffer | undefined;
+};
+
 function agentEditRequest(
     idempotencyKey: string,
     prompt: string,
     headers: Record<string, string> = {},
-    responseMode = 'path'
+    responseModeOrFields: string | AgentEditRequestFields = 'path',
+    options: { signal?: AbortSignal } = {}
 ) {
+    const fields: AgentEditRequestFields =
+        typeof responseModeOrFields === 'string'
+            ? { response_mode: responseModeOrFields }
+            : { response_mode: 'path', ...responseModeOrFields };
+    const imageBuffer = fields.image_0 ?? Buffer.from(PNG_BASE64, 'base64');
     const formData = new FormData();
     formData.append('prompt', prompt);
     formData.append('model', 'gpt-image-2');
-    formData.append('response_mode', responseMode);
-    formData.append('image_0', new File([Buffer.from(PNG_BASE64, 'base64')], 'input.png', { type: 'image/png' }));
+    for (const [key, value] of Object.entries(fields)) {
+        if (key === 'image_0') continue;
+        if (typeof value !== 'string') {
+            throw new TypeError(`Agent edit test field ${key} must be a string.`);
+        }
+        formData.append(key, value);
+    }
+    formData.append('image_0', new File([imageBuffer], 'input.png', { type: 'image/png' }));
     return new Request('http://localhost/api/agent/images/edit', {
         method: 'POST',
         headers: {
             'Idempotency-Key': idempotencyKey,
             ...headers
         },
-        body: formData
+        body: formData,
+        signal: options.signal
     });
 }
 
-async function startImageUpstream(handler: () => unknown | Promise<unknown>): Promise<{ baseUrl: string; close: () => Promise<void> }> {
+function createPngWithDimensions(width: number, height: number): Buffer {
+    const buffer = Buffer.from(PNG_BASE64, 'base64');
+    buffer.writeUInt32BE(width, 16);
+    buffer.writeUInt32BE(height, 20);
+    return buffer;
+}
+
+async function startImageUpstream(
+    handler: (body: string, url: string) => unknown | Promise<unknown>
+): Promise<{ baseUrl: string; close: () => Promise<void> }> {
     const server = http.createServer(async (request, response) => {
         if (
             request.method !== 'POST' ||
@@ -1094,9 +2052,11 @@ async function startImageUpstream(handler: () => unknown | Promise<unknown>): Pr
             response.end(JSON.stringify({ error: { message: 'not found' } }));
             return;
         }
-        request.resume();
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
         try {
-            const body = await handler();
+            const body = await handler(Buffer.concat(chunks).toString('utf8'), request.url || '');
             response.writeHead(200, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify(body));
         } catch (error) {
@@ -1114,6 +2074,111 @@ async function startImageUpstream(handler: () => unknown | Promise<unknown>): Pr
     };
 }
 
+async function startHangingImageEditUpstream(): Promise<{
+    baseUrl: string;
+    readonly requests: number;
+    close: () => Promise<void>;
+}> {
+    let requests = 0;
+    const sockets = new Set<Socket>();
+    const server = http.createServer(async (request, response) => {
+        if (request.method === 'POST' && request.url?.endsWith('/images/edits')) {
+            requests += 1;
+            request.resume();
+            return;
+        }
+        request.resume();
+        response.writeHead(404, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: { message: 'not found' } }));
+    });
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        get requests() {
+            return requests;
+        },
+        close: () =>
+            new Promise((resolve, reject) => {
+                for (const socket of sockets) socket.destroy();
+                server.close((error) => (error ? reject(error) : resolve()));
+            })
+    };
+}
+
+async function startStreamingImageUpstream(
+    handler: (
+        body: string
+    ) => Array<{ event?: string; data: unknown }> | Promise<Array<{ event?: string; data: unknown }>>
+): Promise<{ baseUrl: string; close: () => Promise<void> }> {
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const events = await handler(Buffer.concat(chunks).toString('utf8'));
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        for (const event of events) {
+            if (event.event) {
+                response.write(`event: ${event.event}\n`);
+            }
+            response.write(`data: ${JSON.stringify(event.data)}\n\n`);
+        }
+        response.write('data: [DONE]\n\n');
+        response.end();
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+
+async function startStreamingResponsesImageUpstream(
+    handler: (
+        body: string
+    ) => Array<{ event?: string; data: unknown }> | Promise<Array<{ event?: string; data: unknown }>>
+): Promise<{ baseUrl: string; close: () => Promise<void> }> {
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/responses')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const events = await handler(Buffer.concat(chunks).toString('utf8'));
+        response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+        for (const event of events) {
+            if (event.event) {
+                response.write(`event: ${event.event}\n`);
+            }
+            response.write(`data: ${JSON.stringify(event.data)}\n\n`);
+        }
+        response.write('data: [DONE]\n\n');
+        response.end();
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return {
+        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
+    };
+}
+
 function readStoredResponseJson(idempotencyKey: string): string {
     const db = new Database(path.join(tempDir, 'agent.sqlite'), { readonly: true });
     try {
@@ -1130,7 +2195,9 @@ function readStoredResponseJson(idempotencyKey: string): string {
 function readStoredArtifactFilepath(id: string): string {
     const db = new Database(path.join(tempDir, 'agent.sqlite'), { readonly: true });
     try {
-        const row = db.prepare('SELECT filepath FROM agent_artifacts WHERE id = ?').get(id) as { filepath: string } | undefined;
+        const row = db.prepare('SELECT filepath FROM agent_artifacts WHERE id = ?').get(id) as
+            | { filepath: string }
+            | undefined;
         assert.ok(row);
         return row.filepath;
     } finally {
@@ -1140,7 +2207,9 @@ function readStoredArtifactFilepath(id: string): string {
 
 async function listGeneratedImageFiles(): Promise<string[]> {
     try {
-        return (await readdir(path.join(tempDir, 'generated-images'))).filter((entry) => /\.(png|jpe?g|webp)$/i.test(entry));
+        return (await readdir(path.join(tempDir, 'generated-images'))).filter((entry) =>
+            /\.(png|jpe?g|webp)$/i.test(entry)
+        );
     } catch {
         return [];
     }
@@ -1163,10 +2232,7 @@ async function waitFor(predicate: () => boolean): Promise<void> {
 }
 
 async function waitForJobResult(
-    getJobResult: (
-        request: Request,
-        context: { params: Promise<{ id: string }> }
-    ) => Promise<Response>,
+    getJobResult: (request: Request, context: { params: Promise<{ id: string }> }) => Promise<Response>,
     id: string
 ): Promise<Response> {
     for (let attempt = 0; attempt < 200; attempt += 1) {

src/app/api/agent/capabilities/route.ts

@@ -16,6 +16,8 @@ function readPublicCapabilitiesEnv(): Record<string, string | undefined> {
         AGENT_DB_PASSWORD_FILE: process.env.AGENT_DB_PASSWORD_FILE ? 'configured' : undefined,
         AGENT_REQUEST_TTL_SECONDS: process.env.AGENT_REQUEST_TTL_SECONDS,
         AGENT_PUBLIC_BASE_URL: process.env.AGENT_PUBLIC_BASE_URL,
+        ENABLE_RESPONSES_IMAGE_BACKEND: process.env.ENABLE_RESPONSES_IMAGE_BACKEND,
+        OPENAI_RESPONSES_API_MODEL: process.env.OPENAI_RESPONSES_API_MODEL?.trim() ? 'configured' : undefined,
         NEXT_PUBLIC_IMAGE_STORAGE_MODE: process.env.NEXT_PUBLIC_IMAGE_STORAGE_MODE,
         VERCEL: process.env.VERCEL
     };

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

@@ -1,4 +1,7 @@
+import { readAgentLeaseMs, readAgentRequestTtlSeconds } from '@/lib/agent-api-contracts';
+import { assertAgentAuthorized } from '@/lib/agent-auth';
 import {
+    assertAgentEditRouteAllowedFromFormData,
     buildEditRequestHashFromSnapshot,
     completeAgentExecutionState,
     createArtifactPersistenceError,
@@ -12,11 +15,14 @@ import {
     saveAgentExecutionArtifacts,
     snapshotAgentEditFormData
 } from '@/lib/agent-image-service';
-import { readAgentLeaseMs, readAgentRequestTtlSeconds } from '@/lib/agent-api-contracts';
-import { AgentApiError, agentErrorResponse, normalizeAgentError, storedAgentErrorResponse } from '@/lib/api-error-response';
-import { assertAgentAuthorized } from '@/lib/agent-auth';
 import { ensureAgentStateStoreReady } from '@/lib/agent-state-runtime';
 import { createRequestId } from '@/lib/agent-state-store';
+import {
+    AgentApiError,
+    agentErrorResponse,
+    normalizeAgentError,
+    storedAgentErrorResponse
+} from '@/lib/api-error-response';
 import { appLogger } from '@/lib/app-logger';
 import { NextRequest, NextResponse } from 'next/server';
 
@@ -25,6 +31,7 @@ export async function POST(request: NextRequest) {
     try {
         assertAgentAuthorized(request.headers);
         const formData = await parseAgentEditFormData(request);
+        await assertAgentEditRouteAllowedFromFormData(formData);
         const idempotencyKey = readIdempotencyKey(request.headers);
         const requestSnapshot = await snapshotAgentEditFormData(formData);
         const store = await ensureAgentStateStoreReady();
@@ -45,7 +52,10 @@ export async function POST(request: NextRequest) {
         }
         if (beginResult.type === 'failed') {
             requestId = beginResult.record.requestId;
-            return storedAgentErrorResponse(beginResult.error, { 'X-Idempotent-Replay': 'true' });
+            return storedAgentErrorResponse(beginResult.error, {
+                'X-Idempotent-Replay': 'true',
+                'X-Request-Id': requestId
+            });
         }
         if (beginResult.type === 'conflict') {
             throw new AgentApiError({
@@ -71,7 +81,8 @@ export async function POST(request: NextRequest) {
             headers: request.headers,
             requestId,
             idempotencyKey,
-            cached: false
+            cached: false,
+            abortSignal: request.signal
         }).catch(async (error) => {
             const errorBody = errorToAgentErrorBody(error, requestId);
             await store.failRequest({ requestId, error: errorBody });

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

@@ -1,3 +1,5 @@
+import { readAgentLeaseMs, readAgentRequestTtlSeconds } from '@/lib/agent-api-contracts';
+import { assertAgentAuthorized } from '@/lib/agent-auth';
 import {
     buildGenerateRequestHash,
     completeAgentExecutionState,
@@ -11,11 +13,14 @@ import {
     readIdempotencyKey,
     saveAgentExecutionArtifacts
 } from '@/lib/agent-image-service';
-import { readAgentLeaseMs, readAgentRequestTtlSeconds } from '@/lib/agent-api-contracts';
-import { AgentApiError, agentErrorResponse, normalizeAgentError, storedAgentErrorResponse } from '@/lib/api-error-response';
-import { assertAgentAuthorized } from '@/lib/agent-auth';
 import { ensureAgentStateStoreReady } from '@/lib/agent-state-runtime';
 import { createRequestId } from '@/lib/agent-state-store';
+import {
+    AgentApiError,
+    agentErrorResponse,
+    normalizeAgentError,
+    storedAgentErrorResponse
+} from '@/lib/api-error-response';
 import { appLogger } from '@/lib/app-logger';
 import { NextRequest, NextResponse } from 'next/server';
 
@@ -43,7 +48,10 @@ export async function POST(request: NextRequest) {
         }
         if (beginResult.type === 'failed') {
             requestId = beginResult.record.requestId;
-            return storedAgentErrorResponse(beginResult.error, { 'X-Idempotent-Replay': 'true' });
+            return storedAgentErrorResponse(beginResult.error, {
+                'X-Idempotent-Replay': 'true',
+                'X-Request-Id': requestId
+            });
         }
         if (beginResult.type === 'conflict') {
             throw new AgentApiError({
@@ -69,7 +77,8 @@ export async function POST(request: NextRequest) {
             headers: request.headers,
             requestId,
             idempotencyKey,
-            cached: false
+            cached: false,
+            abortSignal: request.signal
         }).catch(async (error) => {
             const errorBody = errorToAgentErrorBody(error, requestId);
             await store.failRequest({ requestId, error: errorBody });

src/app/api/agent/jobs/[id]/result/route.ts

@@ -1,7 +1,7 @@
 import {
     assertReadableJobRecord,
     readAgentJobState,
-    readCompletedJobResult
+    readJobResult
 } from '@/lib/agent-job-service';
 import {
     AgentApiError,
@@ -26,7 +26,7 @@ export async function GET(request: NextRequest, context: RouteContext) {
         const store = await ensureAgentStateStoreReady();
         const record = assertReadableJobRecord(await store.getRequest(id), id);
         requestId = record.requestId;
-        const result = await readCompletedJobResult(store, record);
+        const result = await readJobResult(store, record);
         if (result.type === 'response') {
             return NextResponse.json(result.response, { headers: { 'X-Request-Id': requestId } });
         }

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

@@ -34,6 +34,7 @@ export async function POST(request: NextRequest) {
         if (beginResult.type === 'replay' || beginResult.type === 'failed') {
             requestId = beginResult.record.requestId;
             return NextResponse.json(buildAgentJobStatusResponse(beginResult.record), {
+                status: 202,
                 headers: { 'X-Idempotent-Replay': 'true', 'X-Request-Id': requestId }
             });
         }

src/app/api/auth-status/route.test.ts

@@ -0,0 +1,24 @@
+import { GET } from './route';
+import assert from 'node:assert/strict';
+import { afterEach, describe, it } from 'node:test';
+
+const originalAppPassword = process.env.APP_PASSWORD;
+
+afterEach(() => {
+    if (originalAppPassword === undefined) {
+        delete process.env.APP_PASSWORD;
+    } else {
+        process.env.APP_PASSWORD = originalAppPassword;
+    }
+});
+
+describe('GET /api/auth-status', () => {
+    it('treats blank APP_PASSWORD as disabled', async () => {
+        process.env.APP_PASSWORD = '   ';
+
+        const response = await GET();
+        const body = (await response.json()) as { passwordRequired?: boolean };
+
+        assert.equal(body.passwordRequired, false);
+    });
+});

src/app/api/auth-status/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
 export async function GET() {
-    const appPasswordSet = !!process.env.APP_PASSWORD;
+    const appPasswordSet = Boolean(process.env.APP_PASSWORD?.trim());
     return NextResponse.json({ passwordRequired: appPasswordSet });
 }

src/app/api/auth-verify/route.test.ts

@@ -16,6 +16,21 @@ afterEach(() => {
 });
 
 describe('POST /api/auth-verify', () => {
+    it('treats blank APP_PASSWORD as disabled', async () => {
+        process.env.APP_PASSWORD = '   ';
+        const request = new NextRequest('http://localhost/api/auth-verify', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({})
+        });
+
+        const response = await POST(request);
+        const result = (await response.json()) as { authenticated?: boolean; passwordRequired?: boolean };
+
+        assert.equal(response.status, 200);
+        assert.deepEqual(result, { authenticated: true, passwordRequired: false });
+    });
+
     it('returns a page access code error code for invalid access-code hashes', async () => {
         process.env.APP_PASSWORD = PAGE_PASSWORD_FIXTURE;
         const request = new NextRequest('http://localhost/api/auth-verify', {