Deploy 34af419 to Docker Space

Source: MisonL/gpt-image-playground-customer@34af419d1e35b93f1874ba494453e0fab7ea54fe

README.md

@@ -141,7 +141,7 @@ OPENAI_CHANNEL_3_UPSTREAM_PROFILE=matsca
 - `OPENAI_CHANNEL_N_REQUEST_MODES` 是管理员基于真实上游 smoke 设置的服务端白名单；全局默认可用 `OPENAI_UPSTREAM_REQUEST_MODES`。`/api/runtime-capabilities` 的 `channelRouting.requestModeControls`、`channelRouting.requestModeHealth` 和 Agent capabilities 的 `request_mode_controls` 会暴露配置入口、健康覆盖和对应真实 smoke gate。Agent 客户端只提交业务意图，不应自行选择 Images、Responses、SSE 或非流式路径。`stream_mode=auto` 可由服务端在 SSE 不可用时显式退到非流式并标记 fallback；`stream_mode=stream` 或显式页面 SSE 诊断必须失败可见，不会静默降级。真实执行后可从 `execution.channel_request_mode`、`execution.channel_request_mode_fallback_applied` 和 `execution.route_decision` 读取服务端实际选路结果；失败冷却若能关联到本次服务端 request mode，会只冷却该渠道或凭证的对应 request mode，并在 `error.diagnostics.cooldown_target.request_mode` 暴露。
 - 渠道恢复探测使用非计费 `GET /models` 只确认 host、鉴权和 models 端点恢复；它不能替代 request mode 的真实 Images/Responses/SSE smoke。管理员应以真实 smoke 结果决定 `OPENAI_CHANNEL_N_REQUEST_MODES`。
 - Docker compose 本身不把默认图片后端改成 Responses；未在 `.env.local` 显式配置时仍是 `images-api` 和 `auto`。
-- Responses image backend 需要 `ENABLE_RESPONSES_IMAGE_BACKEND=true` 和 `OPENAI_RESPONSES_API_MODEL`。页面请求也可以用 `responsesModel`、`responses_model`、`gptModel` 或 `gpt_model` 覆盖单次 `/responses` 顶层模型；这些字段只影响本项目的 `responses-image-generation` 路径，不会改变兼容上游自身 `/v1/images/generations` 桥接层内部选择的模型。
+- Responses image backend 需要 `ENABLE_RESPONSES_IMAGE_BACKEND=true` 和 `OPENAI_RESPONSES_API_MODEL`。生成意图也可以用 `responsesModel`、`responses_model`、`gptModel` 或 `gpt_model` 覆盖单次 `/responses` 顶层模型；这些字段只影响本项目的 `responses-image-generation` 路径，不会改变兼容上游自身 `/v1/images/generations` 桥接层内部选择的模型。
 - Matsca、extra headers、provider manifest、真实上游 smoke 等高级配置以 [.env.example](./.env.example) 为准。
 
 ## Agent API
@@ -156,7 +156,7 @@ Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先
 | --- | --- |
 | `GET /api/agent/capabilities` | 查询模型、限制、认证方式和路由规则。 |
 | `GET /api/agent/openapi.json` | 获取 OpenAPI 描述。 |
-| `POST /api/agent/images/generate` | JSON 文生图。 |
+| `POST /api/agent/images/generate` | JSON 文生图（显式 Agent / 诊断）。 |
 | `POST /api/agent/images/edit` | multipart 图片编辑，支持源图和 mask。 |
 | `POST /api/agent/jobs/images/generate` | 创建文生图 job。 |
 | `GET /api/agent/jobs/{id}` | 查询 job 状态。 |
@@ -168,7 +168,7 @@ Agent API 是机器接口，不是自治 Agent 平台。自动化客户端应先
 生成示例：
 
 ```bash
-curl -s http://localhost:4783/api/agent/images/generate \
+curl -s http://localhost:4783/api/agent/image-requests \
   -H "Authorization: Bearer your-agent-token" \
   -H "Idempotency-Key: demo-$(date +%s)" \
   -H "Content-Type: application/json" \

docs/deployment/huggingface-space-free.md

@@ -199,7 +199,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 脚本会先读取 `GET /api/agent/capabilities`，再调用 Agent API。成功响应会保留相对 `content_url`，同时补充 `absolute_content_url` 和 `absolute_metadata_url`，便于在桌面环境直接下载产物。
 
-远端 Agent 调用不要硬编码路径。普通文生图默认提交业务意图到 capabilities 声明的 `orchestration.endpoint`，由服务端选择内部执行路径、上游 request mode 和轮询方式；Agent 客户端不按尺寸、远端 HTTPS 或流式参数自行选择 Images、Responses、SSE 或非流式路径。页面高级字段、默认 WebP edit、高分辨率 edit 和复杂批量仍按 Skill 规则使用页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再用新的 `Idempotency-Key` 显式选择 Agent JSON、Agent edit 或 job 路径对照。job polling 只在显式选择时使用。需要诊断对照时可用 `--agent` 或 `--streaming-strategy off` 强制 Agent JSON，也可用 `--page-sse` 或 `--job` 显式选择路径。
+远端 Agent 调用不要硬编码路径。普通文生图默认提交业务意图到 capabilities 声明的 `orchestration.endpoint`，由服务端选择内部执行路径、上游 request mode 和轮询方式；Agent 客户端不按尺寸、远端 HTTPS 或流式参数自行选择 Images、Responses、SSE 或非流式路径。显式 page_sse 诊断、默认 WebP edit、高分辨率 edit 和复杂批量仍按 Skill 规则使用页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再用新的 `Idempotency-Key` 显式选择 Agent JSON、Agent edit 或 job 路径对照。job polling 只在显式选择时使用。需要诊断对照时可用 `--agent` 或 `--streaming-strategy off` 强制 Agent JSON，也可用 `--page-sse` 或 `--job` 显式选择路径。
 
 如果 Space 同时配置了 `APP_PASSWORD` 和 `AGENT_API_TOKEN`，Agent JSON 端点用 `GPT_IMAGE_AGENT_TOKEN` 发送 Bearer token；页面端 `/api/images` SSE 仍按 capabilities 的 `agent_streaming.page_sse.auth` 判断，可能需要额外设置 `GPT_IMAGE_APP_PASSWORD_HASH`，并通过 form-data `passwordHash` 发送页面访问码哈希。页面 SSE 会把业务 key 写入 `clientRequestId`，长度上限以 capabilities 中的 `agent_streaming.page_sse.client_request_id.max_length` 为准。
 

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "07209608cdbddc4207aa853b7eb6ea60db1f1827",
-  "created_at": "2026-06-26T01:51:20.764Z",
-  "deploy_id": "fce636f2-7a61-4ff6-8f38-d69ac5edeb35"
+  "local_sha": "34af419d1e35b93f1874ba494453e0fab7ea54fe",
+  "created_at": "2026-06-26T04:13:04.694Z",
+  "deploy_id": "cff00c2a-9ee2-45f8-bca2-6a8465a84274"
 }

scripts/agent-skill-scripts.test.mjs

@@ -555,7 +555,7 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stderr.trim(), '');
     });
 
-    it('routes GPT2Image-compatible generate options through page SSE dry-runs', () => {
+    it('keeps GPT2Image-compatible generate options on server orchestration dry-runs', () => {
         const result = runSkillScript('generate-image.mjs', [
             '--image-backend',
             'responses',
@@ -571,8 +571,8 @@ describe('Agent skill script argument validation', () => {
 
         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.transport, 'page_sse');
+        assert.equal(body.endpoint, 'http://localhost:4783/api/agent/image-requests');
+        assert.equal(body.routing_guidance.transport, 'server_orchestrated');
         assert.equal(body.request.image_backend, 'responses');
         assert.equal(body.request.responsesModel, 'gpt-5.4-mini');
         assert.equal(body.request.thinking, 'medium');
@@ -816,6 +816,15 @@ describe('Agent skill script argument validation', () => {
                         '3072x2048',
                         '--streaming-strategy',
                         'off',
+                        '--image-backend',
+                        'responses',
+                        '--responses-model',
+                        'gpt-5.4-mini',
+                        '--thinking',
+                        'medium',
+                        '--prompt-optimization',
+                        'false',
+                        '--force-web',
                         'prompt'
                     ],
                     { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
@@ -854,6 +863,11 @@ describe('Agent skill script argument validation', () => {
                 const requestBody = JSON.parse(imageRequestBody);
                 assert.equal(requestBody.size, '3072x2048');
                 assert.equal(requestBody.streaming_strategy, 'off');
+                assert.equal(requestBody.image_backend, 'responses');
+                assert.equal(requestBody.responsesModel, 'gpt-5.4-mini');
+                assert.equal(requestBody.thinking, 'medium');
+                assert.equal(requestBody.promptOptimization, false);
+                assert.equal(requestBody.force_web, true);
             }
         );
     });
@@ -1050,8 +1064,8 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(body.error.code, 'page_sse_failed');
                 assert.match(body.error.message, /stream failed/);
                 assert.match(body.next_step, /新的 Idempotency-Key/);
-                assert.match(body.next_step, /重新校验输出尺寸和格式/);
-                assert.equal(body.routing.fallback_endpoint, '/api/agent/images/generate');
+                assert.match(body.next_step, /服务端编排入口/);
+                assert.equal(body.routing.fallback_endpoint, '/api/agent/image-requests');
                 assert.equal(body.routing.fallback_mode, 'manual_after_diagnosis');
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
@@ -2556,7 +2570,7 @@ describe('Agent skill script argument validation', () => {
                     transport: 'page_sse',
                     endpoint: '/api/images',
                     route_mode: 'page_sse',
-                    fallback_endpoint: '/api/agent/images/generate',
+                    fallback_endpoint: '/api/agent/image-requests',
                     fallback_mode: 'manual_after_diagnosis',
                     stream_mode: null,
                     streaming_strategy: null
@@ -2577,7 +2591,7 @@ describe('Agent skill script argument validation', () => {
         );
     });
 
-    it('passes GPT2Image-compatible generate options to page SSE form-data', async () => {
+    it('passes GPT2Image-compatible generate options to page SSE only when explicitly requested', async () => {
         const requests = [];
         let pageSseRequestBody = '';
         await withServer(
@@ -2615,6 +2629,7 @@ describe('Agent skill script argument validation', () => {
                     'generate-image.mjs',
                     [
                         '--allow-billable',
+                        '--page-sse',
                         '--image-backend',
                         'responses',
                         '--responses-model',
@@ -2726,13 +2741,77 @@ describe('Agent skill script argument validation', () => {
         );
     });
 
-    it('rejects generate page-only options for explicit Agent routes before network requests', async () => {
+    it('passes generate response controls through explicit Agent and job diagnostic routes', async () => {
         const requests = [];
+        let agentRequestBody = '';
+        let jobRequestBody = '';
         await withServer(
-            (request, response) => {
+            async (request, response) => {
                 requests.push({ method: request.method, url: request.url });
-                response.writeHead(500, { 'content-type': 'application/json' });
-                response.end(JSON.stringify({ error: 'unexpected request' }));
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify(agentGenerateCapabilities()));
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    agentRequestBody = await readRequestText(request);
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            images: [
+                                {
+                                    id: 'agent-artifact',
+                                    filename: 'agent.webp',
+                                    content_url: '/api/agent/artifacts/agent-artifact/content'
+                                }
+                            ]
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/jobs/images/generate') {
+                    jobRequestBody = await readRequestText(request);
+                    response.writeHead(202, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            job: {
+                                id: 'job-diagnostic-1',
+                                state: 'running',
+                                result_url: '/api/agent/jobs/job-diagnostic-1/result',
+                                retry_after_seconds: 1
+                            }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/jobs/job-diagnostic-1/result') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            request_id: 'job-diagnostic-1',
+                            idempotency_key: 'job-diagnostic-key',
+                            cached: false,
+                            images: [
+                                {
+                                    id: 'job-artifact',
+                                    filename: 'job.webp',
+                                    content_url: '/api/agent/artifacts/job-artifact/content'
+                                }
+                            ],
+                            execution: {
+                                transport: 'agent_job_polling',
+                                endpoint: '/api/agent/jobs/images/generate',
+                                route_mode: 'job',
+                                image_backend: 'responses-image-generation',
+                                stream_mode: 'auto',
+                                streaming_strategy: 'auto'
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
             },
             async (baseUrl) => {
                 const result = await runSkillScriptAsync(
@@ -2749,39 +2828,108 @@ describe('Agent skill script argument validation', () => {
                     { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
                 );
 
-                assert.equal(result.status, 2);
-                assert.equal(result.stdout.trim(), '');
-                assert.match(result.stderr, /Agent generate 不接受文生图高级页面字段/);
-                assert.deepEqual(requests, []);
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const agentBody = JSON.parse(agentRequestBody);
+                assert.equal(agentBody.image_backend, 'responses');
+                assert.equal(agentBody.responsesModel, 'gpt-5.4-mini');
 
-                const jobResult = runSkillScript('generate-image.mjs', [
-                    '--job',
-                    '--image-backend',
-                    'responses',
-                    '--responses-model',
-                    'gpt-5.4-mini',
-                    'prompt'
-                ]);
-                assert.equal(jobResult.status, 2);
-                assert.match(jobResult.stderr, /Agent generate job 不接受文生图高级页面字段/);
-                assert.equal(jobResult.stdout.trim(), '');
+                const jobResult = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    [
+                        '--allow-billable',
+                        '--job',
+                        '--idempotency-key',
+                        'job-diagnostic-key',
+                        '--image-backend',
+                        'responses',
+                        '--responses-model',
+                        'gpt-5.4-mini',
+                        'prompt'
+                    ],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+                assert.equal(jobResult.status, 0);
+                assert.equal(jobResult.stderr.trim(), '');
+                const jobBody = JSON.parse(jobRequestBody);
+                assert.equal(jobBody.image_backend, 'responses');
+                assert.equal(jobBody.responsesModel, 'gpt-5.4-mini');
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    [
+                        'GET /api/agent/capabilities',
+                        'POST /api/agent/images/generate',
+                        'GET /api/agent/capabilities',
+                        'POST /api/agent/jobs/images/generate',
+                        'GET /api/agent/jobs/job-diagnostic-1/result'
+                    ]
+                );
             }
         );
     });
 
-    it('rejects generate page-only options when streaming is disabled before network requests', async () => {
+    it('keeps generate response controls on server orchestration when streaming is disabled', async () => {
         const requests = [];
+        let imageRequestBody = '';
         await withServer(
-            (request, response) => {
+            async (request, response) => {
                 requests.push({ method: request.method, url: request.url });
-                response.writeHead(500, { 'content-type': 'application/json' });
-                response.end(JSON.stringify({ error: 'unexpected request' }));
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify(agentGenerateCapabilities()));
+                    return;
+                }
+                if (request.url === '/api/agent/image-requests') {
+                    imageRequestBody = await readRequestText(request);
+                    response.writeHead(202, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            job: {
+                                id: 'job-nonstream-controls',
+                                state: 'running',
+                                result_url: '/api/agent/jobs/job-nonstream-controls/result',
+                                retry_after_seconds: 1
+                            }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/jobs/job-nonstream-controls/result') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            request_id: 'job-nonstream-controls',
+                            idempotency_key: 'nonstream-controls-key',
+                            cached: false,
+                            images: [
+                                {
+                                    id: 'artifact-nonstream-controls',
+                                    filename: 'nonstream.webp',
+                                    content_url: '/api/agent/artifacts/artifact-nonstream-controls/content'
+                                }
+                            ],
+                            execution: {
+                                transport: 'agent_job_polling',
+                                endpoint: '/api/agent/image-requests',
+                                route_mode: 'job',
+                                image_backend: 'responses-image-generation',
+                                stream_mode: 'non_stream',
+                                streaming_strategy: 'auto'
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
             },
             async (baseUrl) => {
                 const result = await runSkillScriptAsync(
                     'generate-image.mjs',
                     [
                         '--allow-billable',
+                        '--idempotency-key',
+                        'nonstream-controls-key',
                         '--image-backend',
                         'responses',
                         '--responses-model',
@@ -2793,10 +2941,20 @@ describe('Agent skill script argument validation', () => {
                     { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
                 );
 
-                assert.equal(result.status, 2);
-                assert.equal(result.stdout.trim(), '');
-                assert.match(result.stderr, /文生图高级页面参数需要页面 SSE/);
-                assert.deepEqual(requests, []);
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const requestBody = JSON.parse(imageRequestBody);
+                assert.equal(requestBody.image_backend, 'responses');
+                assert.equal(requestBody.responsesModel, 'gpt-5.4-mini');
+                assert.equal(requestBody.stream_mode, 'non_stream');
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    [
+                        'GET /api/agent/capabilities',
+                        'POST /api/agent/image-requests',
+                        'GET /api/agent/jobs/job-nonstream-controls/result'
+                    ]
+                );
             }
         );
     });
@@ -3910,7 +4068,7 @@ describe('Agent skill script argument validation', () => {
             assert.equal(body.guardrails.repeat_ordered_prefix_on_real_run, true);
             assert.equal(body.guardrails.dimension_check_recommended, true);
             assert.match(body.guardrails.dimension_check_reason, /--dimension-check/);
-            assert.equal(body.tasks[0].endpoint, '/api/agent/images/generate');
+            assert.equal(body.tasks[0].endpoint, '/api/agent/image-requests');
             assert.equal(body.tasks[0].idempotency_key, 'demo-0001-first-item');
             assert.equal(body.tasks[0].request.model, 'gpt-image-2');
             assert.equal(body.tasks[0].request.output_format, 'jpeg');
@@ -3963,7 +4121,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: { code: 'unexpected_error', message: 'fetch failed', retryable: false } }));
                         return;
@@ -4116,7 +4274,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         agentRequestBody = await readRequestText(request);
                         response.writeHead(200, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ images: [{ id: 'compressed-image', filename: 'compressed.jpg' }] }));
@@ -4170,7 +4328,7 @@ describe('Agent skill script argument validation', () => {
                         );
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: 'generate should not be called' }));
                         return;
@@ -4297,7 +4455,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(200, { 'content-type': 'application/json' });
                         response.end(
                             JSON.stringify({
@@ -4329,7 +4487,7 @@ describe('Agent skill script argument validation', () => {
                     assert.equal(body.results[1].status, 'succeeded');
                     assert.deepEqual(
                         requests.map((item) => `${item.method} ${item.url}`),
-                        ['GET /api/agent/capabilities', 'POST /api/agent/images/generate']
+                        ['GET /api/agent/capabilities', 'POST /api/agent/image-requests']
                     );
                     const manifestLines = readFileSync(manifestPath, 'utf8').trim().split(/\r?\n/).map(JSON.parse);
                     assert.equal(manifestLines.length, 3);
@@ -4368,7 +4526,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         activeGenerateRequests += 1;
                         enteredGenerateRequests += 1;
                         maxActiveGenerateRequests = Math.max(maxActiveGenerateRequests, activeGenerateRequests);
@@ -4478,7 +4636,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         activeGenerateRequests += 1;
                         maxActiveGenerateRequests = Math.max(maxActiveGenerateRequests, activeGenerateRequests);
                         await new Promise((resolve) => setTimeout(resolve, 20));
@@ -4521,8 +4679,8 @@ describe('Agent skill script argument validation', () => {
                         [
                             'GET /api/runtime-capabilities',
                             'GET /api/agent/capabilities',
-                            'POST /api/agent/images/generate',
-                            'POST /api/agent/images/generate'
+                            'POST /api/agent/image-requests',
+                            'POST /api/agent/image-requests'
                         ]
                     );
                 }
@@ -4576,7 +4734,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: 'unexpected resumed request' }));
                         return;
@@ -4747,7 +4905,7 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
-    it('routes batch generate requests with responsesModel through page SSE', async () => {
+    it('routes batch generate requests with responsesModel through server orchestration', async () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-responses-model-'));
         try {
             const inputPath = join(tempRoot, 'tasks.jsonl');
@@ -4772,6 +4930,12 @@ describe('Agent skill script argument validation', () => {
                         response.writeHead(200, { 'content-type': 'application/json' });
                         response.end(
                             JSON.stringify({
+                                orchestration: {
+                                    supported: true,
+                                    transport_selection: 'server_owned',
+                                    endpoint: '/api/agent/image-requests'
+                                },
+                                agent_jobs: { supported: true, mode: 'job_polling' },
                                 agent_streaming: {
                                     page_sse: { supported: true, endpoint: '/api/images' }
                                 }
@@ -4779,23 +4943,56 @@ describe('Agent skill script argument validation', () => {
                         );
                         return;
                     }
-                    if (request.url === '/api/images') {
+                    if (request.url === '/api/agent/image-requests') {
                         pageSseRequestBody = await readRequestText(request);
-                        response.writeHead(200, { 'content-type': 'text/event-stream' });
+                        response.writeHead(202, { 'content-type': 'application/json' });
                         response.end(
-                            [
-                                'data: {"type":"completed","filename":"responses.png","path":"/generated/responses.png"}',
-                                '',
-                                'data: {"type":"done","images":[{"filename":"responses.png","path":"/generated/responses.png"}]}',
-                                '',
-                                ''
-                            ].join('\n')
+                            JSON.stringify({
+                                job: {
+                                    id: 'batch-job-responses',
+                                    state: 'running',
+                                    result_url: '/api/agent/jobs/batch-job-responses/result',
+                                    retry_after_seconds: 1
+                                }
+                            })
                         );
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
-                        response.writeHead(500, { 'content-type': 'application/json' });
-                        response.end(JSON.stringify({ error: 'unexpected Agent generate call' }));
+                    if (request.url === '/api/agent/jobs/batch-job-responses/result') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                request_id: 'batch-job-responses',
+                                idempotency_key: 'batch-responses-model-key',
+                                cached: false,
+                                images: [
+                                    {
+                                        id: 'responses-artifact',
+                                        filename: 'responses.png',
+                                        content_url: '/generated/responses.png'
+                                    }
+                                ],
+                                execution: {
+                                    transport: 'agent_job_polling',
+                                    endpoint: '/api/agent/image-requests',
+                                    route_mode: 'job',
+                                    image_backend: 'responses-image-generation',
+                                    stream_mode: 'auto',
+                                    streaming_strategy: 'auto',
+                                    channel_request_mode: 'responses-sse',
+                                    channel_request_mode_fallback_applied: false,
+                                    route_decision: {
+                                        requested_backend: 'responses-image-generation',
+                                        preferred_channel_request_mode: 'responses-sse',
+                                        selected_channel_request_mode: 'responses-sse',
+                                        fallback_applied: false,
+                                        selected_channel_id: 'responses-channel',
+                                        upstream_host: 'upstream.example.test'
+                                    }
+                                },
+                                timing: { server_elapsed_ms: 1234 }
+                            })
+                        );
                         return;
                     }
                     response.writeHead(404, { 'content-type': 'application/json' });
@@ -4809,14 +5006,26 @@ describe('Agent skill script argument validation', () => {
                     assert.equal(result.status, 0);
                     assert.equal(result.stderr.trim(), '');
                     const body = JSON.parse(result.stdout);
-                    assert.equal(body.results[0].routing.transport, 'page_sse');
+                    assert.deepEqual(body.results[0].routing, {
+                        strength: 'default',
+                        transport: 'server_orchestrated',
+                        endpoint: '/api/agent/image-requests',
+                        route_mode: 'job',
+                        result_mode: 'job_polling',
+                        reason: 'Batch generate tasks submit intent to the server orchestration endpoint; the service owns internal route selection.'
+                    });
+                    assert.equal(body.results[0].summary.transport, 'agent_job_polling');
+                    assert.equal(body.results[0].summary.endpoint, '/api/agent/image-requests');
+                    assert.equal(body.results[0].summary.route_mode, 'job');
+                    assert.equal(body.results[0].summary.channel_request_mode, 'responses-sse');
                     assert.deepEqual(
                         requests.map((item) => `${item.method} ${item.url}`),
-                        ['GET /api/agent/capabilities', 'POST /api/images']
+                        ['GET /api/agent/capabilities', 'POST /api/agent/image-requests', 'GET /api/agent/jobs/batch-job-responses/result']
                     );
-                    assert.match(pageSseRequestBody, /name="image_backend"\r?\n\r?\nresponses/);
-                    assert.match(pageSseRequestBody, /name="responsesModel"\r?\n\r?\ngpt-4\.1-responses/);
-                    assert.match(pageSseRequestBody, /name="image_streaming_strategy"\r?\n\r?\nresponses-sse/);
+                    const requestBody = JSON.parse(pageSseRequestBody);
+                    assert.equal(requestBody.image_backend, 'responses-image-generation');
+                    assert.equal(requestBody.responsesModel, 'gpt-4.1-responses');
+                    assert.equal(requestBody.streaming_strategy, 'responses-sse');
                 }
             );
         } finally {
@@ -4918,7 +5127,7 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
-    it('fails batch responsesModel routing when page SSE capability is unavailable', async () => {
+    it('keeps batch responsesModel routing on server orchestration when page SSE capability is unavailable', async () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-responses-model-no-sse-'));
         try {
             const inputPath = join(tempRoot, 'tasks.jsonl');
@@ -4938,12 +5147,67 @@ describe('Agent skill script argument validation', () => {
                     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: {} }));
+                        response.end(
+                            JSON.stringify({
+                                orchestration: {
+                                    supported: true,
+                                    transport_selection: 'server_owned',
+                                    endpoint: '/api/agent/image-requests'
+                                },
+                                agent_jobs: { supported: true, mode: 'job_polling' }
+                            })
+                        );
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
-                        response.writeHead(500, { 'content-type': 'application/json' });
-                        response.end(JSON.stringify({ error: 'unexpected Agent generate call' }));
+                    if (request.url === '/api/agent/image-requests') {
+                        response.writeHead(202, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                job: {
+                                    id: 'batch-no-page-sse-job',
+                                    state: 'running',
+                                    result_url: '/api/agent/jobs/batch-no-page-sse-job/result',
+                                    retry_after_seconds: 1
+                                }
+                            })
+                        );
+                        return;
+                    }
+                    if (request.url === '/api/agent/jobs/batch-no-page-sse-job/result') {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                request_id: 'batch-no-page-sse-job',
+                                idempotency_key: 'responses-no-page-sse',
+                                cached: false,
+                                images: [
+                                    {
+                                        id: 'batch-no-page-sse-artifact',
+                                        filename: 'responses.png',
+                                        content_url: '/generated/responses.png'
+                                    }
+                                ],
+                                execution: {
+                                    transport: 'agent_job_polling',
+                                    endpoint: '/api/agent/image-requests',
+                                    route_mode: 'job',
+                                    image_backend: 'responses-image-generation',
+                                    stream_mode: 'auto',
+                                    streaming_strategy: 'auto',
+                                    channel_request_mode: 'images-non-stream',
+                                    channel_request_mode_fallback_applied: false,
+                                    route_decision: {
+                                        requested_backend: 'responses-image-generation',
+                                        preferred_channel_request_mode: 'images-non-stream',
+                                        selected_channel_request_mode: 'images-non-stream',
+                                        fallback_applied: false,
+                                        selected_channel_id: 'images-channel',
+                                        upstream_host: 'upstream.example.test'
+                                    }
+                                },
+                                timing: { server_elapsed_ms: 987 }
+                            })
+                        );
                         return;
                     }
                     response.writeHead(404, { 'content-type': 'application/json' });
@@ -4954,15 +5218,23 @@ describe('Agent skill script argument validation', () => {
                         GPT_IMAGE_PLAYGROUND_URL: baseUrl
                     });
 
-                    assert.equal(result.status, 1);
+                    assert.equal(result.status, 0);
                     assert.equal(result.stderr.trim(), '');
                     const body = JSON.parse(result.stdout);
-                    assert.equal(body.results[0].ok, false);
-                    assert.equal(body.results[0].error.code, 'page_sse_unavailable');
-                    assert.equal(body.results[0].routing.transport, 'page_sse');
+                    assert.equal(body.results[0].ok, true);
+                    assert.deepEqual(body.results[0].routing, {
+                        strength: 'default',
+                        transport: 'server_orchestrated',
+                        endpoint: '/api/agent/image-requests',
+                        route_mode: 'job',
+                        result_mode: 'job_polling',
+                        reason: 'Batch generate tasks submit intent to the server orchestration endpoint; the service owns internal route selection.'
+                    });
+                    assert.equal(body.results[0].summary.transport, 'agent_job_polling');
+                    assert.equal(body.results[0].summary.channel_request_mode, 'images-non-stream');
                     assert.deepEqual(
                         requests.map((item) => `${item.method} ${item.url}`),
-                        ['GET /api/agent/capabilities']
+                        ['GET /api/agent/capabilities', 'POST /api/agent/image-requests', 'GET /api/agent/jobs/batch-no-page-sse-job/result']
                     );
                 }
             );
@@ -4971,7 +5243,7 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
-    it('does not route batch tasks through page SSE when streaming is explicitly disabled', () => {
+    it('does not route batch generate tasks through page SSE when streaming is explicitly disabled', () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-disabled-page-sse-'));
         try {
             const inputPath = join(tempRoot, 'tasks.jsonl');
@@ -4989,8 +5261,9 @@ describe('Agent skill script argument validation', () => {
 
             assert.equal(result.status, 0);
             const body = JSON.parse(result.stdout);
-            assert.equal(body.tasks[0].routing.transport, 'agent_json');
-            assert.equal(body.tasks[0].endpoint, '/api/agent/images/generate');
+            assert.equal(body.tasks[0].routing.transport, 'server_orchestrated');
+            assert.equal(body.tasks[0].routing.endpoint, '/api/agent/image-requests');
+            assert.equal(body.tasks[0].routing.result_mode, 'job_polling');
         } finally {
             rmSync(tempRoot, { recursive: true, force: true });
         }
@@ -5221,7 +5494,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         idempotencyKeys.push(request.headers['idempotency-key']);
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: { message: 'upstream failed', code: 'upstream_failed' } }));
@@ -5285,7 +5558,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         idempotencyKeys.push(request.headers['idempotency-key']);
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: { message: 'upstream failed', code: 'upstream_failed' } }));
@@ -5341,7 +5614,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         idempotencyKeys.push(request.headers['idempotency-key']);
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: { message: 'upstream failed', code: 'upstream_failed' } }));
@@ -5392,7 +5665,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         idempotencyKeys.push(request.headers['idempotency-key']);
                         response.writeHead(500, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ error: 'upstream failed' }));
@@ -5452,7 +5725,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(200, { 'content-type': 'application/json' });
                         response.end(JSON.stringify({ images: [{ id: 'dim-image', filename: 'dim.png', content_url: '/artifact/dim.png' }] }));
                         return;
@@ -5861,9 +6134,13 @@ describe('Agent skill script argument validation', () => {
                 '--input',
                 responsesModelNonStreamInputPath
             ]);
-            assert.equal(responsesModelNonStreamResult.status, 2);
-            assert.match(responsesModelNonStreamResult.stderr, /responses-model-non-stream\.responsesModel 需要页面 SSE 路径/);
-            assert.equal(responsesModelNonStreamResult.stdout.trim(), '');
+            assert.equal(responsesModelNonStreamResult.status, 0);
+            assert.equal(responsesModelNonStreamResult.stderr.trim(), '');
+            const responsesModelNonStreamBody = JSON.parse(responsesModelNonStreamResult.stdout);
+            assert.equal(responsesModelNonStreamBody.tasks[0].routing.transport, 'server_orchestrated');
+            assert.equal(responsesModelNonStreamBody.tasks[0].routing.endpoint, '/api/agent/image-requests');
+            assert.equal(responsesModelNonStreamBody.tasks[0].request.responsesModel, 'gpt-4.1');
+            assert.equal(responsesModelNonStreamBody.tasks[0].request.stream_mode, 'non_stream');
 
             const responsesModelWithoutBackendInputPath = join(tempRoot, 'responses-model-without-backend.jsonl');
             writeFileSync(
@@ -5915,7 +6192,7 @@ describe('Agent skill script argument validation', () => {
                         response.end(JSON.stringify({ ok: true }));
                         return;
                     }
-                    if (request.url === '/api/agent/images/generate') {
+                    if (request.url === '/api/agent/image-requests') {
                         response.writeHead(200, { 'content-type': 'application/json' });
                         response.end(
                             JSON.stringify({

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

@@ -50,7 +50,7 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 - 复杂 UI、长 prompt、高质量图生图遇到 5 分钟级超时、连接中断或上游 503 时，不要把失败归因到提示词质量；先读 `summary` 和诊断，再用新 key 显式尝试压缩 prompt 或改为 `quality=medium` 的对照请求，并记录这是稳定性取舍。
 - 长图恢复或需要续跑锚点的生产请求优先使用页面端 `POST /api/images` SSE，保留局部进度和缺最终图诊断。
 - 普通单次文生图默认使用 `POST /api/agent/image-requests`。`--agent`、`--job`、`--page-sse` 是显式诊断或兼容开关：`--agent` 直连 `/api/agent/images/generate`，`--job` 直连 `/api/agent/jobs/images/generate`，`--page-sse` 直连页面端 `/api/images` SSE。不要把这些显式开关当成默认自动路由。
-- 单张文生图使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时走页面端 `/api/images` SSE，因为这些是页面高级字段，不属于 Agent JSON schema。`--responses-model` 覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。该字段只影响本项目 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。`--responses-model` 必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`；显式 `--agent`、`--job`、`stream_mode=non_stream` 或 `streaming_strategy=off` 会被脚本前置拒绝。
+- 单张文生图使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时仍提交到服务端编排入口，由服务端选择 Responses image_generation、Images API、SSE 或非流式执行方式。`--responses-model` 覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。该字段只影响本项目 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。`--responses-model` 必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`；显式 `--page-sse` 才直连页面端 `/api/images` SSE 做诊断。
 - 同一个已进入终态 `failed` 的 `Idempotency-Key` 只会回放失败；重新尝试必须先诊断原因，再创建新的业务操作和新的 key。
 
 ## 执行流程
@@ -63,10 +63,10 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 6. 让脚本请求 `GET /api/agent/capabilities`。如果所选地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，交互式任务中向用户询问实际部署地址、端口、域名和是否需要鉴权；非交互式任务中显式失败并输出下一步动作。
 7. 读取 capabilities 中的认证方式、模型、模型级限制、`image_transport`、`orchestration`、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
 8. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
-9. 文生图默认使用 `POST /api/agent/image-requests`，请求体为 JSON 业务意图，服务端返回 job 状态并由脚本轮询 `job.result_url`。服务端内部仍会返回标准 `AgentImageResponse`，并在 `execution` 中暴露真实执行路径。显式 `--agent` 才使用 `POST /api/agent/images/generate`；不要把 `responsesModel`、`thinking`、`promptOptimization` 或 `force_web` 发送到 Agent JSON，这些字段需要页面端 `/api/images` form-data 路径。
+9. 文生图默认使用 `POST /api/agent/image-requests`，请求体为 JSON 业务意图，服务端返回 job 状态并由脚本轮询 `job.result_url`。服务端内部仍会返回标准 `AgentImageResponse`，并在 `execution` 中暴露真实执行路径。`responsesModel`、`thinking`、`promptOptimization` 和 `force_web` 是 generate 意图字段；脚本默认把它们交给服务端编排入口处理，不因此自行改用页面端 `/api/images`。
 10. 图片编辑若走 Agent edit，使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段必须使用从 `image_0` 开始的连续字段，最大数量以 capabilities 的 `limits.upload_images.max` 为准；跳号、超过当前 profile 上限、`image_01` 或 `image_foo` 会被显式拒绝。该 Agent 端点同样是非流式端点；上游 SSE 字段按 `agent_streaming.upstream_sse.request_fields_by_mode.edit` 发送，不要给 Agent edit 传 `image_backend`。需要 `image_backend=responses-image-generation` 或页面表单字段 `image_streaming_strategy=responses-sse` 的 edit，一律走页面端 `/api/images` form-data SSE；脚本参数仍写作 `--streaming-strategy responses-sse`。
 11. 默认使用 `response_mode: "path"`，只���用户明确需要图片内联数据时使用 `base64` 或 `both`。
-12. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在默认 WebP edit、复杂 UI 批量、长图恢复、页面高级字段、显式 `--page-sse` 或明确诊断后使用。
+12. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；generate 只在显式 `--page-sse` 或页面工作台诊断时使用它，默认 WebP edit、Responses edit、长图恢复或需要原始 SSE 日志的 edit 仍可使用页面 SSE。
 13. 读取 `agent_jobs` 只用于理解服务端编排结果和显式 `--job` 诊断路径。普通 generate 不再由 Agent 客户端根据本地/远端或尺寸选择 Agent JSON、page SSE 或 job。
 14. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。页面 SSE 返回 `503`、断流，或 `summary` 里的 `selected_channel_id`、`upstream_host` 为空时，先按结构化失败诊断，再用新 key 显式换路径，不要把它当成已自动回退成功。
 15. 返回结果时优先给出 `summary`、`content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。回答“4K 非流式花了多久”时优先读 `summary.elapsed_ms`，服务端返回 timing 时也读 `summary.server_elapsed_ms`。
@@ -194,7 +194,7 @@ node "<skill-root>/scripts/convert-image-format.mjs" --format webp --quality 100
 node "<skill-root>/scripts/convert-image-format.mjs" --format png --output ./source.png ./source.webp --overwrite
 ```
 
-生成脚本默认把文生图业务意图提交到服务端编排入口 `/api/agent/image-requests`；服务端内部决定使用 Agent JSON、内部上游 SSE、job polling 或其他可观测路径。脚本不再根据 `max_edge>2048`、公网 HTTPS 或 `streaming_strategy=off` 自行切换默认端点。单张 generate 仍支持 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 和 `--force-web`；这些字段属于页面 SSE form-data，dry-run 会显示 page SSE 路由，真实请求会发送 `responsesModel`、`thinking`、`promptOptimization` 和 `force_web`。`--agent`、`--job`、`--page-sse` 是显式诊断或兼容开关，使用时必须记录原因，并用新的 `Idempotency-Key` 避免混淆业务操作。默认 WebP edit 走页面 SSE；显式 `--agent` 才走 Agent multipart 最终 JSON，输出格式固定为 Agent 契约。Responses image_generation edit 属于页面 SSE 路径：可显式传 `--page-sse --image-backend responses-image-generation --streaming-strategy responses-sse`；如果运行时已显式配置 `IMAGE_GENERATION_BACKEND=responses-image-generation` 或兼容别名 `responses`，且 `IMAGE_STREAMING_STRATEGY=responses-sse`，也可以依赖服务端默认值。Docker compose 本身不设置这两个默认值，未配置 `.env.local` 时仍是 `images-api` 和 `auto`。不要为 Responses edit 加 `--agent`。默认 WebP edit 与非流式策略冲突时脚本前置拒绝，除非显式添加 `--agent` 做 Agent JSON 对照。页面高级 edit 字段与非流式策略冲突时脚本同样前置拒绝。上游流式字段优先读取 `agent_streaming.upstream_sse.request_fields_by_mode`：generate 支持 `--image-backend`、`--stream-mode`、`--streaming-strategy`、`--partial-images`；Agent edit 只支持 `--stream-mode`、`--streaming-strategy`、`--partial-images`。页面 SSE edit 可发送 `image_backend` 和表单字段 `image_streaming_strategy`；CLI 参数是 `--streaming-strategy`，batch JSONL 字段是 `streaming_strategy`。
+生成脚本默认把文生图业务意图提交到服务端编排入口 `/api/agent/image-requests`；服务端内部决定使用 Agent JSON、内部上游 SSE、job polling 或其他可观测路径。脚本不再根据 `max_edge>2048`、公网 HTTPS、页面高级字段或 `streaming_strategy=off` 自行切换默认端点。单张 generate 支持 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 和 `--force-web`；这些字段会作为生成意图提交到服务端编排入口，由服务端选择 Responses image_generation、Images API、SSE 或非流式执行方式。`--agent`、`--job`、`--page-sse` 是显式诊断或兼容开关，使用时必须记录原因，并用新的 `Idempotency-Key` 避免混淆业务操作。默认 WebP edit 走页面 SSE；显式 `--agent` 才走 Agent multipart 最终 JSON，输出格式固定为 Agent 契约。Responses image_generation edit 属于页面 SSE 路径：可显式传 `--page-sse --image-backend responses-image-generation --streaming-strategy responses-sse`；如果运行时已显式配置 `IMAGE_GENERATION_BACKEND=responses-image-generation` 或兼容别名 `responses`，且 `IMAGE_STREAMING_STRATEGY=responses-sse`，也可以依赖服务端默认���。Docker compose 本身不设置这两个默认值，未配置 `.env.local` 时仍是 `images-api` 和 `auto`。不要为 Responses edit 加 `--agent`。默认 WebP edit 与非流式策略冲突时脚本前置拒绝，除非显式添加 `--agent` 做 Agent JSON 对照。页面高级 edit 字段与非流式策略冲突时脚本同样前置拒绝。上游流式字段优先读取 `agent_streaming.upstream_sse.request_fields_by_mode`：generate 支持 `--image-backend`、`--stream-mode`、`--streaming-strategy`、`--partial-images`；Agent edit 只支持 `--stream-mode`、`--streaming-strategy`、`--partial-images`。页面 SSE edit 可发送 `image_backend` 和表单字段 `image_streaming_strategy`；CLI 参数是 `--streaming-strategy`，batch JSONL 字段是 `streaming_strategy`。
 
 generate 或页面 SSE 请求包含 `image_backend` 时，`partial_images` 必须先按 `limits.partial_images_by_backend[image_backend]` 校验；capabilities 没有该字段时才退回 `limits.partial_images`。Agent edit 不接受 `image_backend`，其内部上游流式字段按默认 Images API/profile 范围校验；Responses backend edit 需要页面 SSE。不要把 Matsca `limits.partial_images=0..4` 误套到 `responses-image-generation`，Responses backend 当前使用自己的 `1..3` 范围。
 
@@ -220,7 +220,7 @@ node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.sp
 
 `--manifest` 使用 JSONL append-only 记录每条任务的 `index`、`id`、`idempotency_key`、`attempt`、`status`、响应或错误以及机器可读 `summary`；Agent JSON 失败时 manifest 也会记录只读诊断补采样得到的 `agent_failure_diagnostics`。`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。dry-run 不写 manifest，输出会声明 `manifest_written=false`、`manifest_write_reason=dry_run` 和 `guardrails`；真实执行应复用 dry-run 中的同一个 `--ordered-prefix`，否则未显式写 `idempotency_key` 的任务会生成不同 key。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`；通过时成功摘要写入 `image_dimensions` 和单图 `actual_dimensions`，失败时 `error.code=dimension_check_failed`、`validation_failure_kind=generated_artifact_failed_dimension_check`、产物 URL、`summary.expected_dimensions`、`summary.actual_dimensions`、`summary.dimension_check_failed=true` 会同时写入 manifest。固定尺寸任务没有开启时，dry-run 会在 `guardrails.dimension_check_recommended` 中提示。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`failure_summary` 会区分 `validation_failure_count` 和 `request_failure_count`，避免把已生成但验收失败误判为上游调用失败。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存；即使 fetch 或 SSE 收集阶段失败，也会记录 `request_started`、`request_failed`、`elapsed_ms`、`client_request_id` 和 `endpoint`，便于区分上游未给终图和解析/断流问题。
 
-批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。
+批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。批量 generate 默认提交到 `/api/agent/image-requests`，`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 会作为 generate 意图字段随 JSON 发送给服务端编排入口。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images` 和上述 Responses 控制字段仍可用于页面 SSE edit 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。
 
 编辑脚本支持位置参数 `<image-path> <prompt>`，也支持 `--image <path> <prompt>` 别名；不要同时传两种图片路径。常用选项包括 `--model`、`--size`、`--quality`、`--response-mode`、`--format`、`--output-compression`、`--moderation`、`--image-backend`、`--responses-model`、`--thinking`、`--prompt-optimization`、`--force-web`、`--stream-mode`、`--streaming-strategy`、`--partial-images`、`--timeout-ms`、`--idempotency-key`、`--page-sse`、`--agent`、`--dry-run` 和 `--allow-billable`。其中 `--image-backend responses-image-generation` 只用于页面 SSE edit。
 

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

@@ -59,10 +59,10 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--output-compression`：默认 `100`，仅适用于 `jpeg` 或 `webp`。
 - `--response-mode`：默认 `path`。
 - `--image-backend`：可选，显式选择 `images-api`、`images`、`responses` 或 `responses-image-generation`。
-- `--responses-model` / `--gpt-model`：页面 SSE 专属字段，覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`。该字段只影响本项目的 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。
-- `--thinking`：页面 SSE 专属字段，可选值为 `minimal`、`none`、`low`、`medium`、`high` 或 `xhigh`。
-- `--prompt-optimization`：页面 SSE 专属字段，必须是 `true` 或 `false`。
-- `--force-web`：页面 SSE 专属字段，会发送为 form-data `force_web=true`。
+- `--responses-model` / `--gpt-model`：生成意图字段，覆盖本次请求的 Responses 顶层模型；未传时使用服务端 `OPENAI_RESPONSES_API_MODEL`。必须同时设置 `--image-backend responses-image-generation` 或兼容别名 `responses`。该字段只影响本项目的 `responses-image-generation` 路径，不改变兼容上游自身 Images API 桥接层内部选择的模型。
+- `--thinking`：生成意图字段，可选值为 `minimal`、`none`、`low`、`medium`、`high` 或 `xhigh`。
+- `--prompt-optimization`：生成意图字段，必须是 `true` 或 `false`。
+- `--force-web`：生成意图字段，服务端在 Images API 路径发送为 `force_web=true`。
 - `--stream-mode`：可选，显式选择 `auto`、`stream` 或 `non_stream`。
 - `--streaming-strategy`：可选，显式选择 `off`、`auto`、`openai-sse`、`newapi-keepalive-sse`、`responses-sse` 或 `force-sse`。
 - `--partial-images`：可选，显式设置上游 SSE partial image 数量。generate 或页面 SSE 请求包含 `image_backend` 时优先按 capabilities 的 `limits.partial_images_by_backend[image_backend]` 校验；缺少 backend 专属范围时才使用 `limits.partial_images`。
@@ -77,7 +77,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--preset`：常用 dry-run/真实调用参数集，当前包括 `1k-smoke-agent`、`4k-agent-nonstream`、`4k-page-sse` 和 `4k-upstream-sse-newapi`。dry-run 会展开真实请求字段，不触发计费。
 
 普通单次文生图默认提交到 `/api/agent/image-requests` 服务端编排入口；脚本不再按 `max_edge>2048`、公网 HTTPS 或 `--streaming-strategy off` 自行选择 page SSE、Agent JSON 或 job endpoint。需要对照时显式使用 `--page-sse`、`--agent` 或 `--job`。
-单张 generate 脚本使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时会选择页面端 `/api/images` SSE。显式 `--agent`、`--job`、`stream_mode=non_stream` 或 `streaming_strategy=off` 与这些页面高级字段同时出现时会在网络请求前失败，避免字段被 Agent JSON 忽略。
+单张 generate 脚本使用 `--responses-model`/`--gpt-model`、`--thinking`、`--prompt-optimization` 或 `--force-web` 时仍默认提交到 `/api/agent/image-requests`。服务端会在内部决定使用 Responses image_generation、Images API、SSE 或非流式路径；Agent 客户端不应因为这些字段自行选择 `/api/images`。
 当服务端默认 `IMAGE_STREAMING_STRATEGY=off` 且请求未覆盖 `streaming_strategy` 时，运行时默认策略为 `off`；WebUI 会把 server-default 流式请求切到 `non_stream`，并发批量开关不可用。generate 脚本显式传 `--streaming-strategy off` 时仍提交给服务端编排入口，除非同时显式使用 `--agent`。
 
 编辑脚本参数：
@@ -125,7 +125,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 
 批量 dry-run 不写 manifest，输出会声明 `manifest_written=false`、`manifest_write_reason=dry_run` 和 `guardrails`。`guardrails.ordered_prefix` 是本次 dry-run 用于自动生成幂等键的前缀，真实执行应复用同一个 `--ordered-prefix`；`guardrails.dimension_check_recommended=true` 表示输入包含固定尺寸但未启用 `--dimension-check`。只有真实执行时 manifest 才作为 append-only 续跑记录写入；Agent JSON 失败时 manifest 会同时保存增强后的 `summary` 和 `agent_failure_diagnostics`。尺寸门禁失败同样写入结构化 summary 和可审查产物 URL，避免只能从中文错误文本解析期望和实际尺寸。批量总摘要会输出 `failure_summary.validation_failure_count` 和 `failure_summary.request_failure_count`，用于区分“上游已生成但本地验收失败”和“请求未成功完成”。当 `validation_failure_count>0` 而 `request_failure_count=0` 时，要按验收失败处理，不能当成上游不可用。
 
-批量 JSONL 每行字段按 `mode` 区分。`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 会选择页面 SSE 路径，且必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`，因为 Agent JSON 不接收请求级 Responses 顶层模型。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
+批量 JSONL 每行字段按 `mode` 区分。`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。批量 generate 默认提交到 `/api/agent/image-requests`，`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 会随 JSON 业务意图提交给服务端编排入口。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images` 以及上述 Responses 控制字段可用于页面 SSE edit 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
 
 Responses edit JSONL 正例：
 
@@ -216,7 +216,7 @@ GET /api/agent/capabilities
 - `orchestration.transport_selection`：当前为 `server_owned`，表示 Agent 客户端不应按尺寸、远端 HTTPS 或流式参数自行选择 page SSE、Agent JSON 或 job endpoint。
 - `orchestration.result_mode`：当前为 `job_polling`，脚本会轮询 `job.result_url` 并输出标准 `AgentImageResponse`。
 - `routing_rules.agent_generate_small_smoke`：`strength=explicit`，兼容旧客户端和显式 `--agent` 诊断路径；不是普通 generate 默认入口。
-- `routing_rules.page_sse_large_generate`：`strength=explicit`，显式 page SSE 诊断和页面工作台路径的参考规则；普通 generate 默认仍走 `orchestration.endpoint`。
+- `routing_rules.page_sse_generate_diagnostics`：`strength=explicit`，显式 page SSE 诊断和页面工作台路径的参考规则；普通 generate 默认仍走 `orchestration.endpoint`。
 - `routing_rules.retry_recovery`：终态失败不会用同一 `Idempotency-Key` 重新执行，必须诊断后创建新的业务操作和新的 key。
 - 批量 JSONL 路由控制字段：`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`；脚本会在 dry-run 阶段拒绝字符串布尔值和未知 transport。
 - `GET /api/runtime-capabilities` 不属于 Agent capabilities。它是页面工作台读取的运行态能力摘要，用于展示流式默认值、图片上游传输配置、渠道健康、渠道队列、并发建议、Responses 后端 enablement 和缺失环境变量，不进入 Agent OpenAPI。
@@ -336,7 +336,7 @@ Agent JSON 生成端点对外始终返回最终 JSON，不会对客户端返回
 
 - 页面 SSE 使用独立的 `POST /api/images` form-data 路径。
 - 若 capabilities 中 `agent_streaming.upstream_sse.supported=true`，generate 可通过 `request_fields_by_mode.generate` 声明的字段控制服务端内部上游 SSE 消费。Agent JSON 的 `image_backend=responses-image-generation` 当前只支持 generate；Responses backend edit 使用页面端 `/api/images` form-data SSE。
-- 不要向 Agent 生成端点发送 `responsesModel`、`gptModel`、`gpt_model`、`thinking`、`promptOptimization`、`prompt_optimization`、`force_web` 或 `forceWeb`。这些是页面 form-data 高级字段；单张 generate 脚本会在需要时走 `/api/images` SSE。
+- 不要向 Agent 生成端点发送 `responsesModel`、`gptModel`、`gpt_model`、`thinking`、`promptOptimization`、`prompt_optimization`、`force_web` 或 `forceWeb`。这些是 generate 意图字段；脚本默认把它们交给服务端编排入口处理，只有显式 `--page-sse` 才会进入 `/api/images` SSE。
 - `/api/agent/image-requests` 的最终轮询结果和 Agent JSON 生成端点最终响应都使用 `AgentImageResponse`。
 - `stream_mode=stream` 强制流式并直接暴露失败。
 - `stream_mode=non_stream` 直接非流式。

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
+import { AGENT_ENDPOINTS, buildAgentJobResultPath } from './lib/agent-api-paths.mjs';
 import { enrichFailureWithAgentDiagnostics } from './lib/agent-diagnostics-summary.mjs';
 import {
   errorMessage,
@@ -547,9 +547,6 @@ function validateTaskRoutingFields(raw, id, mode) {
   if ((raw.page_sse === true || raw.transport === 'page_sse') && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
     throw new Error(`${id} stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。`);
   }
-  if (readResponsesModel(raw, id) && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
-    throw new Error(`${id}.responsesModel 需要页面 SSE 路径，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。`);
-  }
   if (hasOwn(raw, 'sse_log_path') && (raw.stream_mode === 'non_stream' || raw.streaming_strategy === 'off')) {
     throw new Error(`${id}.sse_log_path 需要页面 SSE 路径，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。`);
   }
@@ -894,7 +891,11 @@ function buildTaskFailureOutput(error, routing) {
 }
 
 function shouldEnrichAgentFailure(failure) {
-  return failure.billable !== false && failure.routing?.transport === 'agent_json';
+  return (
+    failure.billable !== false &&
+    failure.routing?.transport !== 'page_sse' &&
+    failure.validation_failure_kind !== FAILURE_KIND_DIMENSION_CHECK
+  );
 }
 
 function buildCircuitBreakerSkippedTask(task, consecutiveFailures) {
@@ -960,7 +961,7 @@ function normalizeFailureError(error) {
 
 function buildFailureNextStep(error) {
   if (error.code === 'page_sse_request_rejected') return '修正请求参数或鉴权后，使用新的 Idempotency-Key 重试失败任务。';
-  if (error.code === 'page_sse_unavailable') return '补齐 page_sse capability 或显式改用 Agent JSON，再重试失败任务。';
+  if (error.code === 'page_sse_unavailable') return '补齐 page_sse capability，或用新的 Idempotency-Key 改走服务端编排或显式诊断路径。';
   return '诊断失败原因后，用新的 Idempotency-Key 重试失败任务；不要复用终态失败 key。';
 }
 
@@ -992,16 +993,26 @@ function buildTaskRouting(task) {
       endpoint: PAGE_SSE_ENDPOINT,
       transport: 'page_sse',
       strength: task.mode === 'edit' && readTaskMaxEdge(task) > 2048 ? 'default' : 'recommended',
-      fallback_endpoint: task.mode === 'edit' ? AGENT_ENDPOINTS.edit : AGENT_ENDPOINTS.generate,
+      fallback_endpoint: task.mode === 'edit' ? AGENT_ENDPOINTS.edit : AGENT_ENDPOINTS.create_image_request,
       fallback_mode: 'manual_after_diagnosis',
       reason
     };
   }
+  if (task.mode === 'generate') {
+    return {
+      endpoint: AGENT_ENDPOINTS.create_image_request,
+      transport: 'server_orchestrated',
+      strength: 'default',
+      route_mode: 'job',
+      result_mode: 'job_polling',
+      reason: 'Batch generate tasks submit intent to the server orchestration endpoint; the service owns internal route selection.'
+    };
+  }
   return {
-    endpoint: task.mode === 'edit' ? AGENT_ENDPOINTS.edit : AGENT_ENDPOINTS.generate,
+    endpoint: AGENT_ENDPOINTS.edit,
     transport: 'agent_json',
     strength: 'default',
-    reason: 'Agent JSON-compatible batch tasks use the Agent response contract.'
+    reason: 'Agent JSON-compatible batch edit tasks use the Agent response contract.'
   };
 }
 
@@ -1085,14 +1096,10 @@ function shouldUsePageSseForTask(task) {
   }
   if (!pageSseAllowed) return false;
   if (task.raw.complex_ui === true || task.raw.long_image === true || task.raw.resume_or_recover === true) return true;
-  if (readResponsesModel(task.raw, task.id)) return true;
   if (task.raw.sse_log_path) return true;
   if (task.mode === 'edit' && hasPageAdvancedFields(task.raw)) return true;
   if (task.mode === 'edit') return true;
   if (task.mode === 'edit' && readTaskMaxEdge(task) > 2048) return true;
-  if (task.mode === 'generate' && readTaskMaxEdge(task) > 2048) {
-    return true;
-  }
   return false;
 }
 
@@ -1114,13 +1121,52 @@ async function postGenerateTask(task) {
         taskCapabilities
       )
   );
-  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.generate}`, {
+  const { response, result, text } = await fetchJson(`${baseUrl}${AGENT_ENDPOINTS.create_image_request}`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'Idempotency-Key': task.idempotencyKey, ...authHeaders() },
     body: JSON.stringify(body)
   });
   if (!response.ok) throw new Error(readErrorMessage(result) || `generate 请求失败，状态码 ${response.status}：${text}`);
-  return enrichImageUrls(result);
+  if (!result?.job) return enrichImageUrls(result);
+  return pollJobResult(result.job);
+}
+
+async function pollJobResult(job) {
+  if (!job || typeof job.id !== 'string') {
+    throw new Error('创建 job 的响应缺少 job.id。');
+  }
+  const resultUrl = resolveSameOriginUrl(baseUrl, job.result_url || buildAgentJobResultPath(job.id), 'job.result_url');
+  const deadlineMs = Date.now() + timeoutMs;
+  let lastResult;
+
+  while (Date.now() < deadlineMs) {
+    const { response, result, text } = await fetchJson(resultUrl, {
+      headers: authHeaders()
+    });
+    if (response.ok) return enrichImageUrls(result);
+    lastResult = result;
+    if (result?.error?.code !== 'request_in_progress' || result?.error?.retryable !== true) {
+      throw new Error(readErrorMessage(result) || `job result 请求失败，状态码 ${response.status}：${text}`);
+    }
+    await sleep(readJobRetryAfterSeconds(result, job));
+  }
+
+  throw new Error(readErrorMessage(lastResult) || '等待 job result 超时。');
+}
+
+function readJobRetryAfterSeconds(result, job) {
+  const value = result?.retry_after ?? result?.error?.retry_after_seconds ?? job?.retry_after_seconds;
+  return readRetryAfterSeconds(value);
+}
+
+function readRetryAfterSeconds(value) {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.min(value, 30);
+  if (typeof value === 'string' && /^\d+(\.\d+)?$/.test(value)) return Math.min(Number(value), 30);
+  return 1;
+}
+
+async function sleep(seconds) {
+  await new Promise((resolve) => setTimeout(resolve, Math.max(0, seconds) * 1000));
 }
 
 async function postEditTask(task) {
@@ -1238,6 +1284,10 @@ function buildGenerateBody(raw) {
     ? normalizeOutputFormat(raw.output_format ?? raw.format)
     : DEFAULT_OUTPUT_FORMAT;
   const outputCompression = readOutputCompression(raw, String(raw.id || 'generate'));
+  const responsesModel = readResponsesModel(raw, String(raw.id || 'generate'));
+  const thinking = hasOwn(raw, 'thinking') ? normalizeEnumValue(raw.thinking, THINKING_VALUES, 'thinking') : undefined;
+  const promptOptimization = readPromptOptimization(raw, String(raw.id || 'generate'));
+  const forceWeb = readForceWeb(raw, String(raw.id || 'generate'));
   const body = {
     prompt: raw.prompt,
     model: raw.model || 'gpt-image-2',
@@ -1250,6 +1300,10 @@ function buildGenerateBody(raw) {
     ...(raw.background ? { background: raw.background } : {}),
     ...(raw.moderation ? { moderation: raw.moderation } : {}),
     ...(hasOwn(raw, 'image_backend') ? { image_backend: normalizeEnumValue(raw.image_backend, IMAGE_BACKENDS, 'image_backend') } : {}),
+    ...(responsesModel ? { responsesModel } : {}),
+    ...(thinking ? { thinking } : {}),
+    ...(promptOptimization !== undefined ? { promptOptimization } : {}),
+    ...(forceWeb !== undefined ? { force_web: forceWeb } : {}),
     ...(hasOwn(raw, 'stream_mode') ? { stream_mode: normalizeEnumValue(raw.stream_mode, STREAM_MODES, 'stream_mode') } : {}),
     ...(hasOwn(raw, 'streaming_strategy')
       ? { streaming_strategy: normalizeEnumValue(raw.streaming_strategy, STREAMING_STRATEGIES, 'streaming_strategy') }

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

@@ -213,7 +213,7 @@ try {
                 JSON.stringify(
                     buildSuccessOutput(formatPageSseOutput(result), {
                         ...buildPageSseSummaryRouting(),
-                        fallback_endpoint: AGENT_ENDPOINTS.generate,
+                        fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
                         fallback_mode: 'manual_after_diagnosis'
                     }, completeScriptTiming(scriptTiming)),
                     null,
@@ -412,19 +412,10 @@ function validateUpstreamStrategyOptions(parsed) {
     if (parsed.routeMode === 'page_sse' && (parsed.streamingStrategy === 'off' || parsed.streamMode === 'non_stream')) {
         throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。');
     }
-    if (hasPageOnlyGenerateOptions(parsed) && !isPageSseAllowed(parsed)) {
-        throw new Error('文生图高级页面参数需要页面 SSE，不能同时设置 stream_mode=non_stream 或 streaming_strategy=off。');
-    }
-    if (parsed.routeMode === 'agent') {
-        assertNoPageOnlyGenerateOptions(parsed, 'Agent generate');
-    }
     if (!OUTPUT_FORMATS.has(normalizeOutputFormat(parsed.format))) {
         throw new Error('--format 必须是 png、jpeg 或 webp。');
     }
     if (parsed.outputCompression !== undefined) readOutputCompression(parsed);
-    if (parsed.routeMode === 'job') {
-        assertNoPageOnlyGenerateOptions(parsed, 'Agent generate job');
-    }
 }
 
 function validateResponsesModelBackend(parsed) {
@@ -449,21 +440,6 @@ function readOutputCompression(parsed) {
     return parsedValue;
 }
 
-function hasPageOnlyGenerateOptions(value) {
-    return Boolean(
-        value.responsesModel ||
-            value.thinking ||
-            value.promptOptimization !== undefined ||
-            value.forceWeb !== undefined ||
-            value.force_web !== undefined
-    );
-}
-
-function assertNoPageOnlyGenerateOptions(parsed, context) {
-    if (!hasPageOnlyGenerateOptions(parsed)) return;
-    throw new Error(`${context} 不接受文生图高级页面字段；请去掉这些字段或使用 --page-sse。`);
-}
-
 function readBooleanOption(value, name) {
     if (value === true || value === 'true') return true;
     if (value === false || value === 'false') return false;
@@ -582,9 +558,7 @@ 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 (hasPageOnlyGenerateOptions(body) || isLargeGenerate(body)) && isPageSseAllowed(body)
-        ? `${baseUrl}${PAGE_SSE_ENDPOINT}`
-        : `${baseUrl}${AGENT_ENDPOINTS.generate}`;
+    return `${baseUrl}${AGENT_ENDPOINTS.generate}`;
 }
 
 function buildGenerateRoutingGuidance(body, routeMode) {
@@ -608,23 +582,14 @@ function buildGenerateRoutingGuidance(body, routeMode) {
     if (routeMode === 'page_sse' && !isPageSseAllowed(body)) {
         throw new Error('stream_mode=non_stream 或 streaming_strategy=off 时不能强制使用页面 SSE。');
     }
-    if (
-        (routeMode === 'page_sse' ||
-            (routeMode !== 'agent' && (hasPageOnlyGenerateOptions(body) || isLargeGenerate(body)))) &&
-        isPageSseAllowed(body)
-    ) {
-        const reason = routeMode === 'page_sse'
-            ? 'Explicit --page-sse requests use the page form-data SSE endpoint.'
-            : hasPageOnlyGenerateOptions(body)
-            ? 'Responses/GPT2Image-compatible generate options require the page form-data SSE endpoint; Agent JSON generate does not accept those fields.'
-            : 'Generate requests with page-workbench-only requirements should use the page form-data SSE endpoint; if the stream fails, diagnose first and rerun manually with Agent JSON.';
+    if (routeMode === 'page_sse' && isPageSseAllowed(body)) {
         return {
             recommended_endpoint: PAGE_SSE_ENDPOINT,
             transport: 'page_sse',
             strength: 'recommended',
-            fallback_endpoint: AGENT_ENDPOINTS.generate,
+            fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
             fallback_mode: 'manual_after_diagnosis',
-            reason
+            reason: 'Explicit --page-sse requests use the page form-data SSE endpoint.'
         };
     }
     return {
@@ -1101,7 +1066,7 @@ function buildPageSseFailureOutput(error, timing = completeScriptTiming(scriptTi
 function buildPageSseRouting(fallbackMode) {
     return {
         ...buildPageSseSummaryRouting(),
-        fallback_endpoint: AGENT_ENDPOINTS.generate,
+        fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
         fallback_mode: fallbackMode
     };
 }
@@ -1127,7 +1092,7 @@ function buildPageSseScriptFailure(error, diagnostics, timing) {
             ...(diagnostics ? { diagnostics } : {})
         },
         routing: buildPageSseRouting('manual_after_diagnosis'),
-        next_step: '先补齐页面流式 capability 或��问码哈希，再重新执行；不要静默切换到 Agent JSON。'
+        next_step: '先补齐页面流式 capability 或访问码哈希，再重新执行；不要静默切换到其他端点。'
     };
     return attachSummary(output, buildFailureSummary({
         errorBody: output,
@@ -1174,7 +1139,7 @@ function buildBillablePageSseFailure(error, diagnostics, timing) {
         },
         routing: buildPageSseRouting('manual_after_diagnosis'),
         next_step:
-            '先用 diagnose-request 诊断页面流式失败原因，再用新的 Idempotency-Key 显式选择备用路径；若改用 Agent JSON 对照，必须重新校验输出尺寸和格式。'
+            '先用 diagnose-request 诊断页面流式失败原因，再用新的 Idempotency-Key 显式选择服务端编排入口或其他诊断路径。'
     };
     return attachSummary(output, buildFailureSummary({
         errorBody: output,
@@ -1554,19 +1519,15 @@ function shouldUsePageSse(capabilitiesValue, request, routeMode) {
         }
         return false;
     }
-    if (routeMode === 'page_sse' || hasPageOnlyGenerateOptions(request) || isLargeGenerate(request)) {
+    if (routeMode === 'page_sse') {
         assertPageSseReady(capabilitiesValue);
         return true;
     }
     return false;
 }
 
-function isLargeGenerate(request) {
-    return readMaxImageEdge(request.size) > 2048;
-}
-
 function shouldPreferServerOrchestration(request) {
-    return !hasPageOnlyGenerateOptions(request);
+    return true;
 }
 
 function isPageSseAllowed(request) {

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

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"07209608cdbddc4207aa853b7eb6ea60db1f1827","created_at":"2026-06-26T01:51:20.764Z","deploy_id":"fce636f2-7a61-4ff6-8f38-d69ac5edeb35"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"34af419d1e35b93f1874ba494453e0fab7ea54fe","created_at":"2026-06-26T04:13:04.694Z","deploy_id":"cff00c2a-9ee2-45f8-bca2-6a8465a84274"} as const;
 
 export const dynamic = 'force-dynamic';
 

src/lib/agent-api-contracts.test.ts

@@ -74,6 +74,39 @@ describe('validateAgentGenerateRequest', () => {
         );
     });
 
+    it('accepts Agent generate response controls as service-owned intent fields', () => {
+        assert.deepEqual(
+            validateAgentGenerateRequest({
+                prompt: 'draw a stable generate request',
+                image_backend: 'responses-image-generation',
+                responsesModel: 'gpt-5.4-mini',
+                thinking: 'medium',
+                promptOptimization: false,
+                force_web: true
+            }),
+            {
+                model: 'gpt-image-2',
+                prompt: 'draw a stable generate request',
+                n: 1,
+                size: '1024x1024',
+                quality: 'high',
+                output_format: 'webp',
+                output_compression: 100,
+                background: 'auto',
+                moderation: 'auto',
+                response_mode: 'path',
+                image_backend: 'responses-image-generation',
+                stream_mode: 'auto',
+                streaming_strategy: 'auto',
+                partial_images: 2,
+                responsesModel: 'gpt-5.4-mini',
+                thinking: 'medium',
+                promptOptimization: false,
+                force_web: true
+            }
+        );
+    });
+
     it('rejects Responses backend partial image counts outside the backend contract', () => {
         assert.throws(
             () =>
@@ -489,13 +522,17 @@ describe('buildAgentCapabilities', () => {
             requires_new_idempotency_key_on_retry: true,
             no_automatic_fallback: true
         });
-        assert.equal(capabilities.routing_rules.page_sse_large_generate.endpoint, '/api/images');
-        assert.equal(capabilities.routing_rules.page_sse_large_generate.transport, 'page_sse');
-        assert.equal(capabilities.routing_rules.page_sse_large_generate.strength, 'explicit');
-        assert.equal(capabilities.routing_rules.page_sse_large_generate.action.strength, 'explicit');
-        assert.deepEqual(capabilities.routing_rules.page_sse_large_generate.conditions, {
+        assert.equal(capabilities.routing_rules.page_sse_generate_diagnostics.endpoint, '/api/images');
+        assert.equal(capabilities.routing_rules.page_sse_generate_diagnostics.transport, 'page_sse');
+        assert.equal(capabilities.routing_rules.page_sse_generate_diagnostics.strength, 'explicit');
+        assert.equal(capabilities.routing_rules.page_sse_generate_diagnostics.action.strength, 'explicit');
+        assert.equal(
+            capabilities.routing_rules.page_sse_generate_diagnostics.action.fallback_endpoint,
+            AGENT_ENDPOINTS.create_image_request
+        );
+        assert.deepEqual(capabilities.routing_rules.page_sse_generate_diagnostics.conditions, {
             operation: 'generate',
-            max_edge: { operator: 'gt', value: 2048 },
+            explicit_page_sse: true,
             single_request: true
         });
         assert.equal(capabilities.routing_rules.retry_recovery.reuse_failed_idempotency_key, false);
@@ -927,6 +964,10 @@ describe('buildAgentCapabilities', () => {
             'force-sse'
         ]);
         assert.deepEqual(generateProperties.stream_mode.enum, ['auto', 'stream', 'non_stream']);
+        assert.deepEqual(generateProperties.thinking.enum, ['minimal', 'none', 'low', 'medium', 'high', 'xhigh']);
+        assert.equal(generateProperties.responsesModel.maxLength, 128);
+        assert.equal(generateProperties.promptOptimization.type, 'boolean');
+        assert.equal(generateProperties.force_web.type, 'boolean');
         assert.deepEqual(generateProperties.n, { type: 'integer', minimum: 1, maximum: 10 });
         assert.deepEqual(generateProperties.partial_images, { type: 'integer', minimum: 1, maximum: 3, default: 2 });
         assert.deepEqual(document.components.schemas.GenerateRequest.allOf[0].then.properties.partial_images, {
@@ -1051,6 +1092,7 @@ describe('buildAgentCapabilities', () => {
             'gt',
             'lte'
         ]);
+        assert.equal(document.components.schemas.AgentRoutingCondition.properties.explicit_page_sse.type, 'boolean');
         assert.equal(
             document.components.schemas.AgentRoutingAction.properties.requires_new_idempotency_key_on_retry.type,
             'boolean'

src/lib/agent-api-contracts.ts

@@ -98,7 +98,7 @@ export const AGENT_UPSTREAM_SSE_EDIT_REQUEST_FIELDS = [
     'partial_images'
 ] as const;
 export const AGENT_PAGE_SSE_AGENT_USAGE =
-    'explicit_for_generate_recommended_for_page_only_fields_default_webp_edit_high_resolution_edit_long_image_recovery_and_complex_batch' as const;
+    'explicit_diagnostics_for_generate_recommended_for_default_webp_edit_high_resolution_edit_long_image_recovery_and_complex_batch' as const;
 const AGENT_DEFAULT_PARTIAL_IMAGES = 2;
 
 export type AgentStateBackend = 'memory' | 'sqlite' | 'postgres';
@@ -152,6 +152,10 @@ export type AgentGenerateRequest = {
     stream_mode: ImageStreamMode;
     streaming_strategy: ImageStreamingStrategy;
     partial_images: 0 | 1 | 2 | 3 | 4;
+    responsesModel?: string;
+    thinking?: 'minimal' | 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+    promptOptimization?: boolean;
+    force_web?: boolean;
 };
 
 export type AgentImageResponseItem = {
@@ -358,7 +362,7 @@ export type AgentCapabilities = {
         complex_ui_batch: AgentRoutingRule;
         long_image_recovery: AgentRoutingRule;
         agent_generate_small_smoke: AgentRoutingRule;
-        page_sse_large_generate: AgentRoutingRule;
+        page_sse_generate_diagnostics: AgentRoutingRule;
         retry_recovery: {
             reuse_failed_idempotency_key: false;
             new_attempt_guidance: string;
@@ -437,6 +441,7 @@ export type AgentRoutingRule = {
 
 export type AgentRoutingCondition = {
     operation: 'generate' | 'edit' | 'generate_or_edit';
+    explicit_page_sse?: boolean;
     max_edge?: {
         operator: 'gt' | 'lte';
         value: number;
@@ -669,6 +674,60 @@ function readModeration(body: Record<string, unknown>, fields: FieldErrors): Age
     return value;
 }
 
+function readOptionalStringField(
+    body: Record<string, unknown>,
+    field: string,
+    fields: FieldErrors,
+    options: { maxLength?: number } = {}
+): string | undefined {
+    const value = body[field];
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value !== 'string') {
+        fields[field] = '必须是字符串';
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        fields[field] = '必须是非空字符串';
+        return undefined;
+    }
+    if (options.maxLength !== undefined && trimmed.length > options.maxLength) {
+        fields[field] = `长度不能超过 ${options.maxLength} 个字符`;
+        return undefined;
+    }
+    return trimmed;
+}
+
+function readOptionalBooleanField(body: Record<string, unknown>, field: string, fields: FieldErrors): boolean | undefined {
+    const value = body[field];
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value === 'boolean') return value;
+    fields[field] = '必须是布尔值';
+    return undefined;
+}
+
+function readAgentResponsesModel(
+    body: Record<string, unknown>,
+    imageBackend: ImageGenerationBackend,
+    fields: FieldErrors
+): string | undefined {
+    const value = readOptionalStringField(body, 'responsesModel', fields, { maxLength: 128 });
+    if (value && imageBackend !== 'responses-image-generation') {
+        fields.responsesModel = '仅适用于 image_backend=responses-image-generation';
+    }
+    return value;
+}
+
+function readAgentThinking(body: Record<string, unknown>, fields: FieldErrors): AgentGenerateRequest['thinking'] {
+    const value = readOptionalStringField(body, 'thinking', fields);
+    if (value === undefined) return undefined;
+    if (['minimal', 'none', 'low', 'medium', 'high', 'xhigh'].includes(value)) {
+        return value as AgentGenerateRequest['thinking'];
+    }
+    fields.thinking = '必须是 minimal、none、low、medium、high 或 xhigh';
+    return undefined;
+}
+
 function readOutputCompression(
     body: Record<string, unknown>,
     outputFormat: ValidOutputFormat,
@@ -712,6 +771,10 @@ export function validateAgentGenerateRequest(body: unknown): AgentGenerateReques
     const streamMode = readAgentStreamMode(objectBody, fields);
     const streamingStrategy = readAgentStreamingStrategy(objectBody, fields);
     const partialImages = readPartialImagesForBackend(objectBody, imageBackend, fields, upstreamLimits.profile);
+    const responsesModel = readAgentResponsesModel(objectBody, imageBackend, fields);
+    const thinking = readAgentThinking(objectBody, fields);
+    const promptOptimization = readOptionalBooleanField(objectBody, 'promptOptimization', fields);
+    const forceWeb = readOptionalBooleanField(objectBody, 'force_web', fields);
     validateAgentImageUpstreamStrategy({ imageBackend, streamMode, streamingStrategy, fields });
 
     if (Object.keys(fields).length > 0) {
@@ -732,7 +795,11 @@ export function validateAgentGenerateRequest(body: unknown): AgentGenerateReques
         image_backend: imageBackend,
         stream_mode: streamMode,
         streaming_strategy: streamingStrategy,
-        partial_images: partialImages
+        partial_images: partialImages,
+        ...(responsesModel ? { responsesModel } : {}),
+        ...(thinking ? { thinking } : {}),
+        ...(promptOptimization !== undefined ? { promptOptimization } : {}),
+        ...(forceWeb !== undefined ? { force_web: forceWeb } : {})
     };
 }
 
@@ -1113,11 +1180,11 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
                 },
                 reason: 'Agent JSON generate remains available for compatibility and explicit diagnostics; ordinary generate clients should use orchestration.endpoint.'
             },
-            page_sse_large_generate: {
-                when: ['operation=generate', 'max_edge>2048', 'single_request=true'],
+            page_sse_generate_diagnostics: {
+                when: ['operation=generate', 'explicit_page_sse=true'],
                 conditions: {
                     operation: 'generate',
-                    max_edge: { operator: 'gt', value: 2048 },
+                    explicit_page_sse: true,
                     single_request: true
                 },
                 endpoint: '/api/images',
@@ -1127,12 +1194,12 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
                     endpoint: '/api/images',
                     transport: 'page_sse',
                     strength: 'explicit',
-                    fallback_endpoint: AGENT_ENDPOINTS.generate,
+                    fallback_endpoint: AGENT_ENDPOINTS.create_image_request,
                     fallback_mode: 'manual_after_diagnosis',
                     requires_new_idempotency_key_on_retry: true,
                     no_automatic_fallback: true
                 },
-                reason: 'Page form-data SSE is available for explicit page-workbench or diagnostic large generate runs; ordinary generate clients should use orchestration.endpoint.'
+                reason: 'Page form-data SSE is available for explicit page-workbench or diagnostic generate runs; ordinary generate clients should use orchestration.endpoint.'
             },
             retry_recovery: {
                 reuse_failed_idempotency_key: false,

src/lib/agent-image-service.ts

@@ -468,7 +468,8 @@ async function executeAgentGenerateUpstream(
         output_format: request.output_format,
         background: request.background as OpenAI.Images.ImageGenerateParams['background'],
         moderation: request.moderation as OpenAI.Images.ImageGenerateParams['moderation'],
-        ...(request.output_compression !== undefined ? { output_compression: request.output_compression } : {})
+        ...(request.output_compression !== undefined ? { output_compression: request.output_compression } : {}),
+        ...(request.force_web !== undefined ? { force_web: request.force_web } : {})
     };
     if (!shouldUseAgentUpstreamStream(streamOptions)) {
         return openai.images.generate(
@@ -557,7 +558,7 @@ async function executeAgentResponsesGenerate(
     const input: ResponsesImageGenerateInput = {
         responses: openai.responses,
         prompt: request.prompt,
-        responsesModel: readAgentResponsesApiModel(),
+        responsesModel: readAgentResponsesApiModel(request.responsesModel),
         imageModel: request.model,
         size: readAgentResponsesImageSize(request.size),
         quality: request.quality,
@@ -565,7 +566,9 @@ async function executeAgentResponsesGenerate(
         background: request.background,
         moderation: request.moderation,
         abortSignal,
-        ...(request.output_compression !== undefined ? { outputCompression: request.output_compression } : {})
+        ...(request.output_compression !== undefined ? { outputCompression: request.output_compression } : {}),
+        ...(request.promptOptimization !== undefined ? { promptOptimization: request.promptOptimization } : {}),
+        ...(request.thinking ? { thinking: request.thinking } : {})
     };
     const streamOptions: AgentStreamOptions = {
         mode: 'generate',
@@ -660,14 +663,17 @@ function isAbortLikeError(error: unknown, abortSignal?: AbortSignal): boolean {
     return name === 'AbortError' || name === 'CanceledError';
 }
 
-function readAgentResponsesApiModel(): string {
-    const model = process.env.OPENAI_RESPONSES_API_MODEL?.trim();
+function readAgentResponsesApiModel(requestModel?: string): string {
+    const model = requestModel?.trim() || process.env.OPENAI_RESPONSES_API_MODEL?.trim();
     if (!model) {
         throw new RequestValidationError(
-            'Responses API 图片后端必须配置 OPENAI_RESPONSES_API_MODEL，作为 /responses 顶层模型。',
+            'Responses API 图片后端必须配置 OPENAI_RESPONSES_API_MODEL 或请求字段 responsesModel，作为 /responses 顶层模型。',
             500
         );
     }
+    if (model.length > 128) {
+        throw new RequestValidationError('Responses API 顶层模型名称不能超过 128 个字符。', 400);
+    }
     return model;
 }
 

src/lib/agent-openapi.ts

@@ -1098,7 +1098,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         'complex_ui_batch',
                         'long_image_recovery',
                         'agent_generate_small_smoke',
-                        'page_sse_large_generate',
+                        'page_sse_generate_diagnostics',
                         'retry_recovery'
                     ],
                     properties: {
@@ -1106,7 +1106,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         complex_ui_batch: { $ref: '#/components/schemas/AgentRoutingRule' },
                         long_image_recovery: { $ref: '#/components/schemas/AgentRoutingRule' },
                         agent_generate_small_smoke: { $ref: '#/components/schemas/AgentRoutingRule' },
-                        page_sse_large_generate: { $ref: '#/components/schemas/AgentRoutingRule' },
+                        page_sse_generate_diagnostics: { $ref: '#/components/schemas/AgentRoutingRule' },
                         retry_recovery: {
                             type: 'object',
                             required: ['reuse_failed_idempotency_key', 'new_attempt_guidance'],
@@ -1154,6 +1154,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         },
                         batch: { type: 'boolean' },
                         single_request: { type: 'boolean' },
+                        explicit_page_sse: { type: 'boolean' },
                         complex_ui: { type: 'boolean' },
                         long_image: { type: 'boolean' },
                         resume_or_recover: { type: 'boolean' }
@@ -1305,6 +1306,17 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                             enum: AGENT_IMAGE_BACKENDS,
                             default: 'images-api'
                         },
+                        responsesModel: {
+                            type: 'string',
+                            maxLength: 128,
+                            description: 'Responses image_generation 顶层模型；仅适用于 image_backend=responses-image-generation。'
+                        },
+                        thinking: {
+                            type: 'string',
+                            enum: ['minimal', 'none', 'low', 'medium', 'high', 'xhigh']
+                        },
+                        promptOptimization: { type: 'boolean' },
+                        force_web: { type: 'boolean' },
                         streaming_strategy: {
                             type: 'string',
                             enum: AGENT_STREAMING_STRATEGIES,