Deploy 34544cc to Docker Space

Source: MisonL/gpt-image-playground-customer@34544ccd35f4321f92ab73ef5ac36603ee9f7720

.env.example

@@ -18,6 +18,7 @@ OPENAI_API_BASE_URL=
 # - round_robin：按请求顺序轮询所有渠道 key，适合简单均摊流量。
 # - random：每次随机选择一个渠道 key，适合轻量分散请求。
 # OPENAI_ROUTING_STRATEGY=sticky
+# OPENAI_UPSTREAM_REQUEST_MODES=images-non-stream,images-sse,responses-non-stream,responses-sse
 #
 # 渠道配置规则：
 # - N 从 1 开始递增，例如 OPENAI_CHANNEL_1_*、OPENAI_CHANNEL_2_*。
@@ -26,6 +27,13 @@ OPENAI_API_BASE_URL=
 # - BASE_URL 默认要求 https；本机 loopback HTTP 可直接用于本地 fixture。
 # - 远程 HTTP 必须加入 OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS。
 # - API_KEYS 支持一个或多个 key，多个 key 用英文逗号分隔。
+# - REQUEST_MODES 可选，用于声明该渠道经真实 smoke 验证可用的服务端请求方式。
+#   单 key 旧配置可用 OPENAI_UPSTREAM_REQUEST_MODES 声明全局可用方式。
+#   该白名单只供服务端路由和诊断使用；Agent 客户端仍只提交业务意图。
+#   stream_mode=auto 可由服务端显式 fallback；stream_mode=stream 或显式页面 SSE 不会静默降级。
+#   可选值：images-non-stream、images-sse、responses-non-stream、responses-sse。
+#   旧后端名别名仅用于兼容输入，建议新配置始终使用上面四个规范值。
+#   未配置时默认认为四种方式都可尝试；配置后服务端只会把匹配方式的请求路由到该渠道。
 # - FAILURE_COOLDOWN_MS 可选，覆盖该渠道失败后的冷却时间。
 # - API Key 本身不要包含逗号。
 #
@@ -33,6 +41,7 @@ OPENAI_API_BASE_URL=
 # OPENAI_CHANNEL_1_ID=official
 # OPENAI_CHANNEL_1_BASE_URL=https://api.openai.com/v1
 # OPENAI_CHANNEL_1_API_KEYS=sk-key-1,sk-key-2
+# OPENAI_CHANNEL_1_REQUEST_MODES=images-non-stream,images-sse
 # OPENAI_CHANNEL_1_FAILURE_COOLDOWN_MS=30000
 # OPENAI_CHANNEL_1_USER_AGENT=gpt-image-playground/customer
 # OPENAI_CHANNEL_1_UPSTREAM_HEADERS_JSON={"X-Custom-Client":"customer"}
@@ -64,6 +73,7 @@ OPENAI_API_BASE_URL=
 # 页面提供显式“并发批量”开关；开启后，流式模式下 n>1 会拆成多个 n=1 的独立流式任务，并按服务端 key 容量并发执行。
 # 默认 sticky 路由按单个 credential 容量推荐并发；round_robin/random 才会使用完整 credential 池。
 # key 出现鉴权、额度或限流类错误后会短暂冷却；渠道出现 5xx、CDN 超时或连接错误后会冷却整个渠道。
+# 如果失败能关联到本次服务端 request mode，只冷却对应 request mode，不误伤同渠道其他可用方式。
 # OPENAI_MAX_STREAMS_PER_CREDENTIAL=1
 # OPENAI_CHANNEL_QUEUE_ENABLED=true
 # OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS=420000
@@ -73,8 +83,9 @@ OPENAI_API_BASE_URL=
 # OPENAI_CHANNEL_FAILURE_COOLDOWN_MS=30000
 #
 # 可选：服务端渠道恢复探测。存在服务端凭证时默认开启，并要求冷却到期的
-# credential/channel 先通过后台 GET /models 探测，成功后才重新进入用户生图流量。
-# 探测不调用 /images/generations，不触发生图费用；MAX_PER_TICK 用于限制探测流量。
+# credential/channel/request mode 先通过后台 GET /models 探测，成功后才重新进入用户生图流量。
+# 探测不调用 /images/generations，不触发生图费用；它只确认 host、鉴权和 models 端点恢复，
+# 不能替代 Images/Responses/SSE 的真实 smoke；MAX_PER_TICK 用于限制探测流量。
 # OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED=true
 # 如果设为 true，OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED 也必须启用。
 # OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY=true

README.md

@@ -101,9 +101,10 @@ start-windows.bat
 | 默认后端 | `IMAGE_GENERATION_BACKEND` | 默认 `images-api`；可设为 `responses-image-generation`。 |
 | Responses 顶层模型 | `OPENAI_RESPONSES_API_MODEL` | 仅在 `responses-image-generation` 后端生效；作为 `/responses` 的顶层 `model`，例如 `gpt-5.4`。 |
 | 流式策略 | `IMAGE_STREAMING_STRATEGY` | 默认 `auto`；可设为 `off`、`openai-sse`、`responses-sse` 等。 |
+| 渠道请求方式 | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES` | 可选。声明全局或单渠道可用方式：`images-non-stream`、`images-sse`、`responses-non-stream`、`responses-sse`；旧后端名别名仅为兼容输入，建议使用这四个规范值。 |
 | 并发容量 | `OPENAI_MAX_STREAMS_PER_CREDENTIAL` | 单个渠道凭证允许同时执行的图片请求数，默认 `1`。 |
 | 渠道队列 | `OPENAI_CHANNEL_QUEUE_ENABLED`、`OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS`、`OPENAI_CHANNEL_QUEUE_MAX_SIZE` | 控制超出凭证容量时等待还是立即失败。 |
-| 失败冷却 | `OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED`、`OPENAI_CHANNEL_FAILURE_COOLDOWN_MS` | 控制失败渠道或凭证是否临时移出路由池。 |
+| 失败冷却 | `OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED`、`OPENAI_CHANNEL_FAILURE_COOLDOWN_MS` | 控制失败渠道、凭证或已识别请求方式是否临时移出路由池。 |
 | 上游超时 | `IMAGE_UPSTREAM_TIMEOUT_MS`、`IMAGE_STREAM_DATA_INTERVAL_TIMEOUT_MS`、`IMAGE_UPSTREAM_MAX_RETRIES` | 默认按长耗时图片请求处理，SDK 自动重试默认关闭。 |
 | 日志窗口 | `APP_LOG_LEVEL`、`APP_LOG_MAX_ENTRIES` | 控制服务端日志等级和 Agent 诊断可回溯窗口。 |
 
@@ -115,10 +116,12 @@ OPENAI_ROUTING_STRATEGY=round_robin
 OPENAI_CHANNEL_1_ID=official
 OPENAI_CHANNEL_1_BASE_URL=https://api.openai.com/v1
 OPENAI_CHANNEL_1_API_KEYS=your-primary-key
+OPENAI_CHANNEL_1_REQUEST_MODES=images-non-stream,images-sse
 
 OPENAI_CHANNEL_2_ID=backup
 OPENAI_CHANNEL_2_BASE_URL=https://your-compatible-api.example.com/v1
 OPENAI_CHANNEL_2_API_KEYS=your-backup-key-a,your-backup-key-b
+OPENAI_CHANNEL_2_REQUEST_MODES=images-non-stream
 
 OPENAI_CHANNEL_3_ID=matsca
 OPENAI_CHANNEL_3_BASE_URL=https://img.matsca.com/v1
@@ -135,6 +138,8 @@ OPENAI_CHANNEL_3_UPSTREAM_PROFILE=matsca
 注意：
 
 - 自定义 API URL 必须同时填写自定义 API Key，避免服务端密钥被发送到未知地址。
+- `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` 桥接层内部选择的模型。
 - Matsca、extra headers、provider manifest、真实上游 smoke 等高级配置以 [.env.example](./.env.example) 为准。
@@ -340,12 +345,12 @@ Hugging Face Space 免费层部署见 [docs/deployment/huggingface-space-free.md
 | `npm run verify` | 运行提交前基线。 |
 | `npm run docker:cleanup-fixtures` | 清理遗留的整仓挂载 Docker fixture 容器。 |
 | `npm run first-run` | 首次配置就绪检查，默认中文摘要；加 `-- --json` 输出机器可读 JSON。 |
-| `npm run status` | 只读查看 git、Node、部署目标和 Agent 摘要。 |
+| `npm run status` | 只读查看 git、Node、部署目标、Agent 摘要和真实 smoke 配置状态；不执行计费图片请求。 |
 | `npm run doctor` | 运行本机和部署诊断。 |
 | `npm run agent:doctor` | 非计费 Agent 分层诊断；支持 `-- --base-url <url>`。 |
 | `npm run deploy:space` | 上传干净 git HEAD 到固定 HF Space。 |
 
-真实上游 smoke 默认不会触发计费；需要真实生图时必须显式传入 `--allow-billable`。
+真实上游 smoke 默认不会触发计费；`npm run status` 只报告 `configuration_complete` 和 `smoke_state=not_run_by_status` 等配置口径。需要真实生图验证时必须显式传入 `--allow-billable`。
 
 ## 常见问题
 

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "3203c24f5434c569bbfec2fb425430d3e45fcbc3",
-  "created_at": "2026-06-23T13:55:49.360Z",
-  "deploy_id": "dea5a9f7-24bf-4297-a091-f730901c220a"
+  "local_sha": "34544ccd35f4321f92ab73ef5ac36603ee9f7720",
+  "created_at": "2026-06-24T14:38:59.964Z",
+  "deploy_id": "dee10b1a-4b9c-47bb-a7f3-89875a64183f"
 }

scripts/agent-doctor.mjs

@@ -7,11 +7,13 @@ import {
     loadPrivateAgentEnvFile,
     resolvePlaygroundBaseUrl
 } from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
+import { CHANNEL_REQUEST_MODES, CHANNEL_REQUEST_MODE_SMOKE_CASES } from '../src/lib/channel-request-mode-values.mjs';
 
 const GENERATE_SCRIPT = fileURLToPath(new URL('../skills/gpt-image-playground-agent/scripts/generate-image.mjs', import.meta.url));
 const EDIT_SCRIPT = fileURLToPath(new URL('../skills/gpt-image-playground-agent/scripts/edit-image.mjs', import.meta.url));
 const AGENT_DOCTOR_TIMEOUT_MS = 75_000;
 const PAGE_SSE_GENERATE_SMOKE_NAME = 'responses_page_sse_generate_1k';
+const RESPONSES_AGENT_GENERATE_SMOKE_NAME = 'responses_agent_generate_1k';
 
 export function buildAgentDoctorArgs() {
     return [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000', 'contract check'];
@@ -131,6 +133,7 @@ function buildSkippedSmoke(options) {
         checks: [
             { name: 'generate_1k', skipped: true, reason: 'requires --allow-billable' },
             { name: PAGE_SSE_GENERATE_SMOKE_NAME, skipped: true, reason: 'requires --allow-billable' },
+            { name: RESPONSES_AGENT_GENERATE_SMOKE_NAME, skipped: true, reason: 'requires --allow-billable' },
             {
                 name: 'edit_1k',
                 skipped: true,
@@ -184,6 +187,26 @@ function runBillableSmoke(options, baseUrl) {
             '--idempotency-key',
             `agent-doctor-responses-page-sse-generate-${Date.now()}`,
             'agent doctor responses page SSE generate smoke'
+        ]),
+        runSmokeCommand(RESPONSES_AGENT_GENERATE_SMOKE_NAME, [
+            GENERATE_SCRIPT,
+            '--base-url',
+            baseUrl,
+            '--allow-billable',
+            '--agent',
+            '--timeout-ms',
+            String(options.timeoutMs),
+            '--size',
+            '1024x1024',
+            '--quality',
+            'low',
+            '--image-backend',
+            'responses-image-generation',
+            '--stream-mode',
+            'non_stream',
+            '--idempotency-key',
+            `agent-doctor-responses-agent-generate-${Date.now()}`,
+            'agent doctor responses non-stream generate smoke'
         ])
     ];
     if (options.editImage) {
@@ -302,7 +325,9 @@ function summarizeCapabilities(body) {
                 : undefined,
         agent_jobs: body?.agent_jobs?.supported === true,
         routing_rules: Boolean(body?.routing_rules),
-        executable_routing_rules: Boolean(body?.routing_rules?.high_resolution_edit?.conditions)
+        executable_routing_rules: Boolean(body?.routing_rules?.high_resolution_edit?.conditions),
+        request_modes_supported: readRequestModeList(body?.supported?.request_modes),
+        request_modes_by_channel: readCapabilitiesRequestModesByChannel(body)
     };
 }
 
@@ -311,7 +336,10 @@ function summarizeRuntime(body) {
         default_stream_mode: body?.streaming?.defaultMode,
         streaming_unavailable_scope: body?.streaming?.unavailableMarkScope,
         responses_image_backend: body?.responsesImageBackend?.enabled === true,
-        streaming_batch_enabled: body?.streamingBatch?.enabled === true
+        streaming_batch_enabled: body?.streamingBatch?.enabled === true,
+        configured_request_modes: readRequestModeList(body?.channelRouting?.configuredRequestModes),
+        effective_request_modes: readRequestModeList(body?.channelRouting?.effectiveRequestModes),
+        effective_request_modes_by_channel: readRuntimeRequestModesByChannel(body)
     };
 }
 
@@ -333,7 +361,11 @@ function summarizeResponsesReadiness(capabilities, runtime) {
         missing_env: requirements?.missing_env || [],
         gpt2image_real_smoke_case: 'gpt2image-responses-sse',
         real_smoke_gate:
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable',
+        real_smoke_gates: [
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-responses-json --allow-billable',
             'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+        ]
     };
 }
 
@@ -352,7 +384,13 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
                 : capabilities.ok,
         page_sse_real_smoke: summarizePageSseSmoke(smoke),
         responses_page_sse_generate_smoke: summarizeSmokeCheck(smoke, PAGE_SSE_GENERATE_SMOKE_NAME),
+        responses_agent_generate_smoke: summarizeSmokeCheck(smoke, RESPONSES_AGENT_GENERATE_SMOKE_NAME),
         real_smoke_checks: summarizeSmokeChecks(smoke),
+        request_modes: buildRequestModeSummary({
+            capabilities: capabilities.ok ? capabilities.body : undefined,
+            runtime: runtime.ok ? runtime.body : undefined,
+            smoke
+        }),
         responses_gpt2image_ready:
             capabilities.ok && runtime.ok
                 ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true &&
@@ -382,11 +420,70 @@ function summarizeSmokeChecks(smoke) {
     return {
         agent_generate_1k: summarizeSmokeCheck(smoke, 'generate_1k'),
         responses_page_sse_generate_1k: summarizeSmokeCheck(smoke, PAGE_SSE_GENERATE_SMOKE_NAME),
+        responses_agent_generate_1k: summarizeSmokeCheck(smoke, RESPONSES_AGENT_GENERATE_SMOKE_NAME),
         agent_edit_1k: summarizeSmokeCheck(smoke, 'edit_1k'),
         page_sse_edit_2k: summarizeSmokeCheck(smoke, 'page_sse_edit_2k')
     };
 }
 
+function buildRequestModeSummary({ capabilities, runtime, smoke }) {
+    const supported = readRequestModeList(capabilities?.supported?.request_modes);
+    const configured = readRequestModeList(runtime?.channelRouting?.configuredRequestModes);
+    const effective = readRequestModeList(runtime?.channelRouting?.effectiveRequestModes);
+    return {
+        supported,
+        configured,
+        effective,
+        admin_whitelist_by_channel: readCapabilitiesRequestModesByChannel(capabilities),
+        effective_by_channel: readRuntimeRequestModesByChannel(runtime),
+        smoke: Object.fromEntries(
+            CHANNEL_REQUEST_MODES.map((mode) => [mode, summarizeRequestModeSmoke(smoke, mode)])
+        )
+    };
+}
+
+function summarizeRequestModeSmoke(smoke, mode) {
+    const checks = CHANNEL_REQUEST_MODE_SMOKE_CASES[mode] || [];
+    if (checks.length === 0) {
+        return {
+            state: 'skipped',
+            checks: [],
+            billable: false
+        };
+    }
+    const states = checks.map((name) => summarizeSmokeCheck(smoke, name));
+    return {
+        state: states.includes('failed') ? 'failed' : states.includes('passed') ? 'passed' : 'skipped',
+        checks,
+        billable: smoke.skipped !== true
+    };
+}
+
+function readCapabilitiesRequestModesByChannel(body) {
+    const channels = Array.isArray(body?.upstream_request_headers?.channels)
+        ? body.upstream_request_headers.channels
+        : [];
+    return channels.map((channel) => ({
+        channel_id: String(channel?.id || ''),
+        request_modes: readRequestModeList(channel?.request_modes)
+    })).filter((channel) => channel.channel_id);
+}
+
+function readRuntimeRequestModesByChannel(body) {
+    const channels = Array.isArray(body?.channelRouting?.effectiveRequestModesByChannel)
+        ? body.channelRouting.effectiveRequestModesByChannel
+        : [];
+    return channels.map((channel) => ({
+        channel_id: String(channel?.channelId || ''),
+        request_modes: readRequestModeList(channel?.requestModes)
+    })).filter((channel) => channel.channel_id);
+}
+
+function readRequestModeList(value) {
+    if (!Array.isArray(value)) return [];
+    return CHANNEL_REQUEST_MODES.filter((mode) => value.includes(mode));
+}
+
 function authHeaders() {
     if (process.env.GPT_IMAGE_AGENT_TOKEN) return { Authorization: `Bearer ${process.env.GPT_IMAGE_AGENT_TOKEN}` };
     if (process.env.GPT_IMAGE_APP_PASSWORD_HASH) return { 'X-App-Password-Hash': process.env.GPT_IMAGE_APP_PASSWORD_HASH };

scripts/agent-skill-scripts.test.mjs

@@ -631,7 +631,7 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stderr.trim(), '');
     });
 
-    it('uses the server orchestration endpoint for default billable generate requests', async () => {
+    it('keeps default generate on server orchestration when request modes are declared', async () => {
         const requests = [];
         let imageRequestBody = '';
         await withServer(
@@ -639,7 +639,32 @@ 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(agentGenerateCapabilities()));
+                    response.end(
+                        JSON.stringify(
+                            agentGenerateCapabilities({
+                                supported: {
+                                    request_modes: [
+                                        'images-non-stream',
+                                        'images-sse',
+                                        'responses-non-stream',
+                                        'responses-sse'
+                                    ]
+                                },
+                                upstream_request_headers: {
+                                    channels: [
+                                        {
+                                            id: 'images',
+                                            request_modes: ['images-non-stream', 'images-sse']
+                                        },
+                                        {
+                                            id: 'responses',
+                                            request_modes: ['responses-sse']
+                                        }
+                                    ]
+                                }
+                            })
+                        )
+                    );
                     return;
                 }
                 if (request.url === '/api/agent/image-requests') {
@@ -679,7 +704,17 @@ describe('Agent skill script argument validation', () => {
                                 route_mode: 'job',
                                 image_backend: 'images-api',
                                 stream_mode: 'non_stream',
-                                streaming_strategy: 'off'
+                                streaming_strategy: 'off',
+                                channel_request_mode: 'images-non-stream',
+                                channel_request_mode_fallback_applied: false,
+                                route_decision: {
+                                    requested_backend: 'images-api',
+                                    preferred_channel_request_mode: 'images-non-stream',
+                                    selected_channel_request_mode: 'images-non-stream',
+                                    fallback_applied: false,
+                                    selected_channel_id: 'channel-orchestrated',
+                                    upstream_host: 'upstream.example.test'
+                                }
                             },
                             timing: { server_elapsed_ms: 1234 }
                         })
@@ -720,6 +755,16 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(body.summary.transport, 'agent_job_polling');
                 assert.equal(body.summary.endpoint, '/api/agent/image-requests');
                 assert.equal(body.summary.route_mode, 'job');
+                assert.equal(body.summary.channel_request_mode, 'images-non-stream');
+                assert.equal(body.summary.channel_request_mode_fallback_applied, false);
+                assert.deepEqual(body.summary.route_decision, {
+                    requested_backend: 'images-api',
+                    preferred_channel_request_mode: 'images-non-stream',
+                    selected_channel_request_mode: 'images-non-stream',
+                    fallback_applied: false,
+                    selected_channel_id: 'channel-orchestrated',
+                    upstream_host: 'upstream.example.test'
+                });
                 assert.deepEqual(body.summary.content_urls, ['/api/agent/artifacts/artifact-orchestrated-1/content']);
                 assert.deepEqual(body.summary.actual_dimensions, { width: 1254, height: 1254 });
                 assert.deepEqual(
@@ -1503,9 +1548,26 @@ describe('Agent skill script argument validation', () => {
                                     code: 'unexpected_error',
                                     retryable: false,
                                     diagnostics: {
+                                        channel_request_mode: 'images-non-stream',
+                                        channel_request_mode_fallback_applied: true,
+                                        route_decision: {
+                                            requested_backend: 'images-api',
+                                            preferred_channel_request_mode: 'images-sse',
+                                            fallback_channel_request_mode: 'images-non-stream',
+                                            selected_channel_request_mode: 'images-non-stream',
+                                            fallback_applied: true,
+                                            selected_channel_id: 'channel-a',
+                                            upstream_host: 'upstream.example.test'
+                                        },
                                         selected_channel_id: 'channel-a',
                                         upstream_host: 'upstream.example.test',
-                                        transport_error_kind: 'aborted'
+                                        transport_error_kind: 'aborted',
+                                        retry_after_ms: 30000,
+                                        cooldown_until: '2026-06-11T12:00:00.000Z',
+                                        cooldown_target: {
+                                            channel_id: 'channel-a',
+                                            request_mode: 'images-non-stream'
+                                        }
                                     }
                                 }
                             }
@@ -1527,13 +1589,43 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(result.stdout.trim(), '');
                 const body = JSON.parse(result.stderr);
                 assert.equal(body.summary.request_id, 'req_generate_diag');
+                assert.equal(body.summary.channel_request_mode, 'images-non-stream');
+                assert.equal(body.summary.channel_request_mode_fallback_applied, true);
+                assert.deepEqual(body.summary.route_decision, {
+                    requested_backend: 'images-api',
+                    preferred_channel_request_mode: 'images-sse',
+                    fallback_channel_request_mode: 'images-non-stream',
+                    selected_channel_request_mode: 'images-non-stream',
+                    fallback_applied: true,
+                    selected_channel_id: 'channel-a',
+                    upstream_host: 'upstream.example.test'
+                });
                 assert.equal(body.summary.selected_channel_id, 'channel-a');
                 assert.equal(body.summary.upstream_host, 'upstream.example.test');
                 assert.equal(body.summary.transport_error_kind, 'aborted');
+                assert.equal(body.summary.retry_after_ms, 30000);
+                assert.equal(body.summary.cooldown_until, '2026-06-11T12:00:00.000Z');
+                assert.deepEqual(body.summary.cooldown_target, {
+                    channel_id: 'channel-a',
+                    request_mode: 'images-non-stream'
+                });
                 assert.equal(body.summary.agent_diagnostics_checked, true);
                 assert.equal(body.summary.agent_diagnostics_found, true);
                 assert.equal(body.agent_failure_diagnostics.request_id, 'req_generate_diag');
                 assert.equal(body.agent_failure_diagnostics.status, 'failed');
+                assert.deepEqual(body.agent_failure_diagnostics.cooldown_target, {
+                    channel_id: 'channel-a',
+                    request_mode: 'images-non-stream'
+                });
+                assert.deepEqual(body.agent_failure_diagnostics.route_decision, {
+                    requested_backend: 'images-api',
+                    preferred_channel_request_mode: 'images-sse',
+                    fallback_channel_request_mode: 'images-non-stream',
+                    selected_channel_request_mode: 'images-non-stream',
+                    fallback_applied: true,
+                    selected_channel_id: 'channel-a',
+                    upstream_host: 'upstream.example.test'
+                });
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
                     [
@@ -3491,6 +3583,9 @@ describe('Agent skill script argument validation', () => {
         assert.match(skillText, /summary\.page_sse_real_smoke/);
         assert.match(skillText, /兼容聚合状态/);
         assert.match(skillText, /summary\.responses_page_sse_generate_smoke/);
+        assert.match(skillText, /summary\.responses_agent_generate_smoke/);
+        assert.match(skillText, /responses_agent_generate_1k/);
+        assert.match(skillText, /request_mode_controls/);
         assert.match(skillText, /summary\.real_smoke_checks/);
         assert.match(apiReference, /npm run first-run/);
         assert.match(apiReference, /npm run first-run -- --json/);
@@ -3501,6 +3596,9 @@ describe('Agent skill script argument validation', () => {
         assert.match(apiReference, /summary\.page_sse_real_smoke/);
         assert.match(apiReference, /兼容聚合状态/);
         assert.match(apiReference, /summary\.responses_page_sse_generate_smoke/);
+        assert.match(apiReference, /summary\.responses_agent_generate_smoke/);
+        assert.match(apiReference, /responses_agent_generate_1k/);
+        assert.match(apiReference, /request_mode_controls/);
         assert.match(apiReference, /summary\.real_smoke_checks/);
         assert.match(readmeText, /不要手动并行启动多个单张脚本/);
         assert.match(readmeText, /streamingBatch\.recommendedConcurrency/);
@@ -6104,7 +6202,10 @@ describe('Agent skill script argument validation', () => {
                                     diagnostics: {
                                         transport_error_kind: 'dns',
                                         cooldown_until: '2026-06-11T12:00:00.000Z',
-                                        cooldown_target: { channel_id: 'channel-a' }
+                                        cooldown_target: {
+                                            channel_id: 'channel-a',
+                                            request_mode: 'images-non-stream'
+                                        }
                                     }
                                 }
                             }
@@ -6138,6 +6239,10 @@ describe('Agent skill script argument validation', () => {
                 );
                 assert.equal(body.agent_requests[1].lookup.type, 'idempotency_key');
                 assert.equal(body.agent_requests[1].diagnostics.error.diagnostics.transport_error_kind, 'dns');
+                assert.equal(
+                    body.agent_requests[1].diagnostics.error.diagnostics.cooldown_target.request_mode,
+                    'images-non-stream'
+                );
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
                     [

scripts/command-center.test.mjs

@@ -114,6 +114,19 @@ describe('Command center scripts', () => {
             'gpt2image-responses-sse',
             'matsca-images-sse'
         ]);
+        assert.deepEqual(missing.request_modes['images-non-stream'], {
+            required_count: 1,
+            required_cases: ['original-images-json'],
+            configuration_complete: false,
+            configured_count: 0,
+            configured_cases: [],
+            missing_count: 1,
+            missing_cases: ['original-images-json'],
+            invalid_count: 0,
+            invalid_cases: [],
+            smoke_state: 'not_run_by_status'
+        });
+        assert.deepEqual(missing.request_modes['responses-sse'].required_cases, ['gpt2image-responses-sse']);
         assert.deepEqual(missing.missing_env_any['sub2api-responses-json'][0], [
             'IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL',
             'IMAGE_REAL_SMOKE_SUB2API_BASE_URL'
@@ -140,6 +153,9 @@ describe('Command center scripts', () => {
         assert.equal(configured.configuration_complete, true);
         assert.equal(configured.configured_count, 6);
         assert.equal(configured.missing_count, 0);
+        assert.equal(configured.request_modes['images-sse'].configured_count, 3);
+        assert.deepEqual(configured.request_modes['responses-non-stream'].configured_cases, ['sub2api-responses-json']);
+        assert.deepEqual(configured.request_modes['responses-sse'].configured_cases, ['gpt2image-responses-sse']);
         assert.doesNotMatch(JSON.stringify(configured), /secret|example\/v1/);
     });
 
@@ -742,6 +758,12 @@ describe('Command center scripts', () => {
                                 }
                             },
                             supported: {
+                                request_modes: [
+                                    'images-non-stream',
+                                    'images-sse',
+                                    'responses-non-stream',
+                                    'responses-sse'
+                                ],
                                 image_backend_requirements: {
                                     'responses-image-generation': {
                                         supported: true,
@@ -749,6 +771,18 @@ describe('Command center scripts', () => {
                                         missing_env: []
                                     }
                                 }
+                            },
+                            upstream_request_headers: {
+                                channels: [
+                                    {
+                                        id: 'images',
+                                        request_modes: ['images-non-stream', 'images-sse']
+                                    },
+                                    {
+                                        id: 'responses',
+                                        request_modes: ['responses-sse']
+                                    }
+                                ]
                             }
                         })
                     );
@@ -763,7 +797,17 @@ describe('Command center scripts', () => {
                                 unavailableMarkScope: 'channel+backend+strategy+operation'
                             },
                             streamingBatch: { enabled: true },
-                            responsesImageBackend: { enabled: true, mode: 'experimental' }
+                            responsesImageBackend: { enabled: true, mode: 'experimental' },
+                            channelRouting: {
+                                configuredRequestModes: ['images-non-stream', 'images-sse', 'responses-sse'],
+                                effectiveRequestModes: ['images-non-stream', 'images-sse'],
+                                effectiveRequestModesByChannel: [
+                                    {
+                                        channelId: 'images',
+                                        requestModes: ['images-non-stream', 'images-sse']
+                                    }
+                                ]
+                            }
                         })
                     );
                     return;
@@ -836,9 +880,24 @@ describe('Command center scripts', () => {
                 assert.deepEqual(body.summary.real_smoke_checks, {
                     agent_generate_1k: 'skipped',
                     responses_page_sse_generate_1k: 'skipped',
+                    responses_agent_generate_1k: 'skipped',
                     agent_edit_1k: 'skipped',
                     page_sse_edit_2k: 'skipped'
                 });
+                assert.deepEqual(body.summary.request_modes.supported, [
+                    'images-non-stream',
+                    'images-sse',
+                    'responses-non-stream',
+                    'responses-sse'
+                ]);
+                assert.deepEqual(body.summary.request_modes.configured, ['images-non-stream', 'images-sse', 'responses-sse']);
+                assert.deepEqual(body.summary.request_modes.effective, ['images-non-stream', 'images-sse']);
+                assert.deepEqual(body.summary.request_modes.smoke['responses-non-stream'].checks, [
+                    'responses_agent_generate_1k'
+                ]);
+                assert.equal(body.summary.request_modes.smoke['responses-non-stream'].state, 'skipped');
+                assert.equal(body.summary.request_modes.smoke['responses-sse'].state, 'skipped');
+                assert.equal(body.summary.request_modes.smoke['responses-sse'].billable, false);
                 assert.equal(body.summary.responses_gpt2image_ready, true);
                 assert.equal(body.summary.responses_image_backend_declared_supported, true);
                 assert.equal(body.summary.billable_smoke, 'skipped');
@@ -846,13 +905,34 @@ describe('Command center scripts', () => {
                 assert.ok(
                     body.layers
                         .find((layer) => layer.name === 'billable_smoke')
-                        .checks.some((check) => check.name === 'responses_page_sse_generate_1k' && check.skipped === true)
+                        .checks.some((check) => check.name === 'responses_agent_generate_1k' && check.skipped === true)
                 );
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').executable_routing_rules, true);
+                assert.deepEqual(body.layers.find((layer) => layer.name === 'capabilities').request_modes_supported, [
+                    'images-non-stream',
+                    'images-sse',
+                    'responses-non-stream',
+                    'responses-sse'
+                ]);
+                assert.deepEqual(body.layers.find((layer) => layer.name === 'runtime_backend').effective_request_modes, [
+                    'images-non-stream',
+                    'images-sse'
+                ]);
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_declared_supported, true);
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_required, true);
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_ready, false);
                 assert.equal(body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').declared_supported, true);
+                assert.match(
+                    body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').real_smoke_gate,
+                    /gpt2image-responses-sse/
+                );
+                assert.deepEqual(
+                    body.layers.find((layer) => layer.name === 'responses_gpt2image_readiness').real_smoke_gates,
+                    [
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-responses-json --allow-billable',
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+                    ]
+                );
                 assert.match(
                     body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_next_action,
                     /GPT_IMAGE_APP_PASSWORD_HASH/
@@ -986,8 +1066,13 @@ describe('Command center scripts', () => {
                 assert.equal(body.interactive_confirmation_required, false);
                 assert.equal(body.summary.page_sse_real_smoke, 'passed');
                 assert.equal(body.summary.responses_page_sse_generate_smoke, 'passed');
+                assert.equal(body.summary.responses_agent_generate_smoke, 'passed');
                 assert.equal(body.summary.real_smoke_checks.agent_generate_1k, 'passed');
                 assert.equal(body.summary.real_smoke_checks.responses_page_sse_generate_1k, 'passed');
+                assert.equal(body.summary.real_smoke_checks.responses_agent_generate_1k, 'passed');
+                assert.equal(body.summary.request_modes.smoke['images-non-stream'].state, 'passed');
+                assert.equal(body.summary.request_modes.smoke['responses-non-stream'].state, 'passed');
+                assert.equal(body.summary.request_modes.smoke['responses-sse'].state, 'passed');
                 assert.equal(body.summary.real_smoke_checks.agent_edit_1k, 'skipped');
                 assert.equal(body.summary.real_smoke_checks.page_sse_edit_2k, 'skipped');
                 assert.ok(hits.includes('/api/agent/images/generate'));
@@ -1074,8 +1159,13 @@ describe('Command center scripts', () => {
                 assert.equal(body.summary.billable_smoke, 'failed');
                 assert.equal(body.summary.page_sse_real_smoke, 'failed');
                 assert.equal(body.summary.responses_page_sse_generate_smoke, 'failed');
+                assert.equal(body.summary.responses_agent_generate_smoke, 'passed');
                 assert.equal(body.summary.real_smoke_checks.agent_generate_1k, 'passed');
                 assert.equal(body.summary.real_smoke_checks.responses_page_sse_generate_1k, 'failed');
+                assert.equal(body.summary.real_smoke_checks.responses_agent_generate_1k, 'passed');
+                assert.equal(body.summary.request_modes.smoke['images-non-stream'].state, 'passed');
+                assert.equal(body.summary.request_modes.smoke['responses-non-stream'].state, 'passed');
+                assert.equal(body.summary.request_modes.smoke['responses-sse'].state, 'failed');
                 assert.equal(body.summary.real_smoke_checks.page_sse_edit_2k, 'skipped');
                 const pageSseOutput = body.layers
                     .find((layer) => layer.name === 'billable_smoke')

scripts/smoke-image-upstream-compat.mjs

@@ -297,7 +297,7 @@ async function main() {
     const { POST } = await import('../src/app/api/images/route.ts');
     try {
         for (const testCase of cases) await runCase(POST, testCase);
-        console.log('image upstream compatibility mock smoke passed');
+        console.log('image upstream compatibility local fixture smoke passed');
     } finally {
         restoreProcessEnv();
     }

scripts/smoke-image-upstream-real.mjs

@@ -68,6 +68,14 @@ const SERVER_CHANNEL_CASES = [
         backend: 'responses-image-generation',
         serverChannel: true,
         endpoint: 'agent-generate'
+    },
+    {
+        id: 'server-channel-agent-responses-json',
+        prefix: 'IMAGE_REAL_SMOKE_SERVER',
+        stream: false,
+        backend: 'responses-image-generation',
+        serverChannel: true,
+        endpoint: 'agent-generate'
     }
 ];
 

scripts/status.mjs

@@ -5,24 +5,31 @@ import net from 'node:net';
 
 import { HF_SPACE_ID, HF_SPACE_URL } from './hf-space-doctor-utils.mjs';
 import { isMainModule, parseJsonPayload, printJson, runCommand, runCommandStrict } from './command-center-utils.mjs';
+import { CHANNEL_REQUEST_MODES, CHANNEL_REQUEST_MODE_ADMIN_CONTROL } from '../src/lib/channel-request-mode-values.mjs';
 
 const REMOTE_STATUS_TIMEOUT_MS = 30_000;
 const LOCAL_ENDPOINT_TIMEOUT_MS = 500;
 const IMAGE_UPSTREAM_REAL_SMOKE_CASES = [
-    { id: 'original-images-json', prefix: 'IMAGE_REAL_SMOKE_ORIGINAL' },
-    { id: 'gaoren-images-sse', prefix: 'IMAGE_REAL_SMOKE_GAOREN' },
-    { id: 'sub2api-images-sse', prefix: 'IMAGE_REAL_SMOKE_SUB2API' },
+    { id: 'original-images-json', prefix: 'IMAGE_REAL_SMOKE_ORIGINAL', requestMode: 'images-non-stream' },
+    { id: 'gaoren-images-sse', prefix: 'IMAGE_REAL_SMOKE_GAOREN', requestMode: 'images-sse' },
+    { id: 'sub2api-images-sse', prefix: 'IMAGE_REAL_SMOKE_SUB2API', requestMode: 'images-sse' },
     {
         id: 'sub2api-responses-json',
         prefix: 'IMAGE_REAL_SMOKE_SUB2API_RESPONSES',
         fallbackPrefix: 'IMAGE_REAL_SMOKE_SUB2API',
-        requiresResponsesModel: true
+        requiresResponsesModel: true,
+        requestMode: 'responses-non-stream'
     },
-    { id: 'gpt2image-responses-sse', prefix: 'IMAGE_REAL_SMOKE_GPT2IMAGE', requiresResponsesModel: true },
-    { id: 'matsca-images-sse', prefix: 'IMAGE_REAL_SMOKE_MATSCA' }
+    {
+        id: 'gpt2image-responses-sse',
+        prefix: 'IMAGE_REAL_SMOKE_GPT2IMAGE',
+        requiresResponsesModel: true,
+        requestMode: 'responses-sse'
+    },
+    { id: 'matsca-images-sse', prefix: 'IMAGE_REAL_SMOKE_MATSCA', requestMode: 'images-sse' }
 ];
 const IMAGE_UPSTREAM_FINAL_GATE_COMMAND =
-    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable';
+    CHANNEL_REQUEST_MODE_ADMIN_CONTROL.finalGateCommand;
 const STATUS_ENV_FILES = [
     { path: '.env.local', override: false },
     { path: '.env.real-smoke.local', override: true }
@@ -152,6 +159,7 @@ export function buildImageUpstreamRealSmokeStatus(env = process.env) {
         const missingEnvAny = readMissingEnvAny(testCase, target);
         return {
             id: testCase.id,
+            request_mode: testCase.requestMode,
             configured: missingEnvAny.length === 0 && target.invalidEnv.length === 0,
             ...(missingEnvAny.length > 0 ? { missing_env_any: missingEnvAny } : {}),
             ...(target.invalidEnv.length > 0 ? { invalid_env: target.invalidEnv } : {})
@@ -174,10 +182,37 @@ export function buildImageUpstreamRealSmokeStatus(env = process.env) {
         invalid_count: invalidCases.length,
         invalid_cases: invalidCases.map((item) => item.id),
         invalid_env: Object.fromEntries(invalidCases.map((item) => [item.id, item.invalid_env])),
+        request_modes: summarizeRealSmokeRequestModes(caseSummaries),
         final_gate_command: IMAGE_UPSTREAM_FINAL_GATE_COMMAND
     };
 }
 
+function summarizeRealSmokeRequestModes(caseSummaries) {
+    return Object.fromEntries(
+        CHANNEL_REQUEST_MODES.map((mode) => {
+            const items = caseSummaries.filter((item) => item.request_mode === mode);
+            const configured = items.filter((item) => item.configured);
+            const missing = items.filter((item) => Array.isArray(item.missing_env_any) && item.missing_env_any.length > 0);
+            const invalid = items.filter((item) => Array.isArray(item.invalid_env) && item.invalid_env.length > 0);
+            return [
+                mode,
+                {
+                    required_count: items.length,
+                    required_cases: items.map((item) => item.id),
+                    configuration_complete: missing.length === 0 && invalid.length === 0,
+                    configured_count: configured.length,
+                    configured_cases: configured.map((item) => item.id),
+                    missing_count: missing.length,
+                    missing_cases: missing.map((item) => item.id),
+                    invalid_count: invalid.length,
+                    invalid_cases: invalid.map((item) => item.id),
+                    smoke_state: 'not_run_by_status'
+                }
+            ];
+        })
+    );
+}
+
 function normalizeLocalHostname(hostname) {
     return hostname.toLowerCase().replace(/^\[|\]$/g, '');
 }

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

@@ -32,6 +32,17 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 ## 路由规则
 
 - 先读取 `GET /api/agent/capabilities` 的 `orchestration` 与 `routing_rules`。普通文生图默认提交业务意图到 `orchestration.endpoint`，当前为 `POST /api/agent/image-requests`；服务端负责选择内部执行路径、上游策略和 job polling。Agent 客户端不要按尺寸、远端 HTTPS 或流式策略自行选择 `/api/images`、`/api/agent/images/generate` 或 job endpoint。
+- `capabilities.supported.request_modes`、`capabilities.upstream_request_headers.channels[].request_modes` 和 `capabilities.request_mode_controls` 是服务端管理员配置的渠道请求方式白名单与诊断控制面；Agent 客户端不要据此绕过 `orchestration.endpoint` 自行挑选 Images、Responses、SSE 或非流式路径。
+
+执行决策表：
+
+| 场景 | Agent 输入 | 服务端职责 | 结果字段 |
+| --- | --- | --- | --- |
+| 普通文生图 | prompt、尺寸、质量等业务意图 | 通过 `orchestration.endpoint` 选择 Agent/job、渠道、Images/Responses、SSE/非流式 | `summary.transport`、`summary.route_mode`、`summary.channel_request_mode`、`summary.route_decision` |
+| 自动上游流式 | `stream_mode=auto` 或默认值 | 若 SSE 渠道不可用，可在服务端显式退到非流式并标记 fallback | `summary.channel_request_mode_fallback_applied=true` |
+| 显式流式诊断 | `stream_mode=stream` 或显式 `--page-sse` | 失败必须显式返回错误，不静默改成非流式 | `summary.route_decision.no_channel_reason` 或结构化错误 |
+| 管理员渠道白名单 | `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES` | 只约束服务端可选渠道，不授权 Agent 客户端自选 endpoint | `capabilities.request_mode_controls`、`agent:doctor.summary.request_modes` |
+
 - 默认 WebP edit 使用页面端 `POST /api/images` form-data SSE 路径，因为 Agent edit 不接收输出格式字段。需要 Responses image_generation edit 时也必须使用页面 SSE，不要用 `--agent`。显式 `--agent` 才使用 `/api/agent/images/edit` Agent multipart 最终 JSON，输出格式固定为 Agent 契约；如果页面流式不可用或失败，先诊断结构化错误，再用新的 `Idempotency-Key` 显式决定是否用 Agent edit 对照。Agent edit 只是对照路径，不保证与页面 SSE 的输出格式和像素尺寸完全一致；尺寸敏感任务必须用 `--dimension-check` 或下载后校验。
 - `capabilities` 里声明的 `page_sse_supported=true`、`agent_streaming.upstream_sse.supported=true` 只表示路径被声明支持，不表示当前渠道每次实测都能成功；如果页面 SSE、Responses 路径或服务端编排入口返回 `503`、断流，或 `summary` 里 `selected_channel_id`、`upstream_host` 为空，先诊断结构化错误，再用新的 `Idempotency-Key` 显式选择诊断路径，不自动回退。
 - 复杂 UI 批量出图优先使用页面端 `POST /api/images` SSE 和 `scripts/batch-images.mjs`；不要手动并行启动多个单张脚本，因为这会绕过 manifest、`--resume`、`capacity_feedback` 和尺寸门禁。需要并发时显式设置 `--concurrency N` 或页面“并发批量”开关，并记录切换原因、失败清单和续跑锚点。
@@ -87,7 +98,7 @@ Authorization: Bearer <token>
 - 不要对同一个已进入终态 `failed` 的 `Idempotency-Key` 继续重试。终态失败回放会返回 `retryable=false`；需要重新尝试时，先确认失败原因，再创建新的业务操作和新的 `Idempotency-Key`。
 - 不要把 `agent_streaming.page_sse.supported=true` 解读为 `/api/agent/images/generate` 会对客户端返回 SSE；Agent generate/edit 对外仍是最终 JSON。`agent_streaming.upstream_sse` 仅表示服务端内部可消费上游 SSE 并保存最终 artifact。
 - 不要直接调用 job endpoints，除非 capabilities 明确返回 `agent_jobs.supported=true` 且 `mode=job_polling`，并且本次是显式 `--job` 诊断或兼容场景。默认 generate 使用 `orchestration.endpoint`。
-- 不要把一次高分辨率、高质量长耗时失败归纳为全局不可用。优先查看 `error.diagnostics.upstream_status`、`upstream_event_type`、`partial_image_count`、`transport_error`、`selected_channel_id`、`channel_cooldown_scope` 和 `retry_after_seconds`。
+- 不要把一次高分辨率、高质量长耗时失败归纳为全局不可用。优先查看 `error.diagnostics.upstream_status`、`upstream_event_type`、`partial_image_count`、`transport_error`、`selected_channel_id`、`channel_cooldown_scope`、`error.diagnostics.cooldown_target.request_mode` 和 `retry_after_seconds`。
 - 不要在 `error.retryable=false` 时依据历史 `retry_after_seconds` 继续重试同一个 key；终态失败需要新业务操作和新 key。
 - 不要把 `/api/runtime-capabilities`、`/api/feedback`、`/api/shares`、`/api/logs` 或 `/api/image-delete` 当成 Agent API。它们是页面运行态或页面工作流端点，鉴权和字段契约与 `/api/agent/*` ��同；反馈和诊断的 Agent 只读入口是 `/api/agent/page-requests/{id}/feedback`、`/api/agent/page-requests/feedback`、`/api/agent/diagnostics/page-requests/{id}` 和 `/api/agent/diagnostics/page-requests`。
 
@@ -114,7 +125,7 @@ Authorization: Bearer <token>
 - `scripts/diagnose-request.mjs`：按一个或多个页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断；支持读取批量 manifest 和 `--base-url`，不触发生图计费。
 - `scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
 
-生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`，便于人工审查。
+生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`，便于人工审查。
 所有生成、编辑、批量和探针脚本在 dry-run 或真实请求前都会校验尺寸参数。`gpt-image-2` 支持 `auto` 或任意正整数 `WIDTHxHEIGHT`；默认 OpenAI-compatible 上游的更严格尺寸边界由服务端 profile 或真实上游显式报错。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。生成、页面编辑、批量页面 SSE 和上游探针默认请求 `output_format=webp`、`output_compression=100`；普通 Agent edit 不发送输出格式字段，输出格式固定为 Agent 契约。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
@@ -141,7 +152,10 @@ Authorization: Bearer <token>
 | `responses_image_backend_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。 |
 | `summary.page_sse_real_smoke` | `agent:doctor` | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。 |
 | `summary.responses_page_sse_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `agent_generate_1k`、`responses_page_sse_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
+| `summary.responses_agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
+| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
+| `summary.request_modes` | `agent:doctor` | 管理员 request mode 的配置和真实 smoke 摘要；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
+| `request_mode_controls` | `capabilities` | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`。 |
 | `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
 | `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
 | `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |

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

@@ -47,7 +47,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 同一个 `Idempotency-Key` 如果已经进入终态 `failed`，再次调用 generate/edit 或 job result/status 只会回放该失败，且 `retryable=false`。需要重新尝试时应创建新的业务操作和新的 `Idempotency-Key`。
 页面端 `/api/images` SSE 会把同一个业务 key 复用到 `clientRequestId`，因此脚本使用的 `Idempotency-Key` 不能超过 capabilities 中 `agent_streaming.page_sse.client_request_id.max_length` 声明的字符数；超长时会直接报错，不会静默截断。
 脚本会在 dry-run 和真实请求前前置校验 `--size` 或 JSONL `size`。`gpt-image-2` 支持 `auto` 或任意正整数 `WIDTHxHEIGHT`；默认 OpenAI-compatible 上游的更严格尺寸边界由服务端 profile 或真实上游显式报错。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。生成、页面编辑、批量和上游探针默认请求 `output_format=webp`、`output_compression=100`。
-真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。失败摘要也稳定包含空数组或 `null` 形式的产物、路由、渠道和尺寸字段，便于 subagent 按同一模板汇报；尺寸门禁失败属于“上游已生成但本地验收失败”，失败摘要会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`。失败摘要还包含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`。Agent JSON 失败时脚本会按幂等键只读查询 Agent state；若命中，会把 `request_id`、`selected_channel_id`、`upstream_host`、`transport_error_kind` 合并进首次失败摘要，并输出 `agent_failure_diagnostics`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
+真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。`transport` 表示 Agent 对外访问的服务端端点形态，`route_mode` 表示 Agent/job/page SSE 路径，`channel_request_mode` 表示服务端实际调用上游的 Images/Responses 与 SSE/非流式组合，`route_decision` 记录 requested backend、preferred/fallback/selected request mode、fallback 是否发生、选中渠道、上游 host 或 no-channel 原因。失败摘要也稳定包含空数组或 `null` 形式的产物、路由、渠道和尺寸字段，便于 subagent 按同一模板汇报；尺寸门禁失败属于“上游已生成但本地验收失败”，失败摘要会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`。失败摘要还包含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`。Agent JSON 失败时脚本会按幂等键只读查询 Agent state；若命中，会把 `request_id`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host`、`transport_error_kind` 合并进首次失败摘要，并输出 `agent_failure_diagnostics`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
 
 生成脚本参数：
 
@@ -204,8 +204,10 @@ GET /api/agent/capabilities
 - `agent_streaming.page_sse.auth`：页面 SSE 的独立表单鉴权。`APP_PASSWORD` 已配置时为 `required=true`、`schemes=["form-password-hash"]`、`form_field="passwordHash"`。
 - `agent_streaming.page_sse.client_request_id`：页面 SSE 的请求 ID 契约。脚本会把 `Idempotency-Key` 写入 form-data `clientRequestId`，最大长度以 `max_length` 为准，当前为 `128`。
 - 页面 SSE 或 Responses 路径失败时，如果 `selected_channel_id`、`upstream_host` 为空，通常表示请求没有真正落到可执行渠道；先诊断结构化错误，再用新的 `Idempotency-Key` 显式改路由。
+- `supported.request_modes`：服务端支持的上游请求方式枚举，当前为 `images-non-stream`、`images-sse`、`responses-non-stream`、`responses-sse`。该字段描述服务端能力全集，不代表每个管理员渠道都已真实 smoke 通过。
 - `upstream_request_headers.default`：默认上游请求头摘要，包含 `user_agent_effective`、`has_extra_headers`、`allowed_header_names` 和 `configured_header_names`。
 - `upstream_request_headers.channels`：每个服务端渠道的脱敏请求头摘要。该字段不包含 API key、Authorization 值、Matsca app secret 值或任意 header value。
+- `request_mode_controls`：管理员 request mode 白名单控制面，声明 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`；Agent 客户端只能用于解释执行结果，不应据此自行选择上游请求方式。
 - `routing_rules.high_resolution_edit`：`edit` 且最大边大于 `2048` 时默认优先使用页面端 `/api/images` SSE，页面流式有问题时显式回退。
 - `routing_rules.complex_ui_batch`：复杂 UI 批量出图推荐使用页面端 `/api/images` SSE。
 - `routing_rules.long_image_recovery`：长图恢复或续跑锚点场景推荐使用页面端 `/api/images` SSE。
@@ -571,7 +573,10 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 | `responses_image_backend_real_smoke_status` | `first-run --json` | 结构化说明 `first-run` 未执行真实 Responses image_generation smoke；不要把声明支持当作实测通过。 |
 | `summary.page_sse_real_smoke` | `agent:doctor` | Page SSE 真实 smoke 的兼容聚合状态；任一 Page SSE smoke 失败为 `failed`，任一通过且无失败为 `passed`，全部跳过为 `skipped`；精确判断优先看 `summary.real_smoke_checks`。 |
 | `summary.responses_page_sse_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + page SSE + `responses-sse` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
-| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `agent_generate_1k`、`responses_page_sse_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
+| `summary.responses_agent_generate_smoke` | `agent:doctor` | `--allow-billable` 时对 `responses-image-generation` + Agent JSON + `responses-non-stream` 这条文生图路径的真实 smoke 状态；非计费时为 `skipped`。 |
+| `summary.real_smoke_checks` | `agent:doctor` | 各真实 smoke 的状态汇总，包含 `agent_generate_1k`、`responses_page_sse_generate_1k`、`responses_agent_generate_1k`、`agent_edit_1k` 和 `page_sse_edit_2k`。 |
+| `summary.request_modes` | `agent:doctor` | 管理员 request mode 的配置和真实 smoke 摘要；`billable=false` 时只能证明配置可见，不能当作真实上游通过。 |
+| `request_mode_controls` | `capabilities` | 管理员 request mode 白名单控制面；包含 `OPENAI_UPSTREAM_REQUEST_MODES`、`OPENAI_CHANNEL_N_REQUEST_MODES`、真实 smoke gate 和 `agent_client_policy=diagnostics_only`。 |
 | `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
 | `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
 | `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
@@ -683,7 +688,8 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
       "retry_after_ms": 15000,
       "cooldown_until": "2026-05-20T00:00:15.000Z",
       "cooldown_target": {
-        "channel_id": "default"
+        "channel_id": "default",
+        "request_mode": "images-sse"
       },
       "channel_cooldown_scope": "channel",
       "response_headers": {
@@ -696,7 +702,7 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 }
 ```
 
-`diagnostics` 只包含脱敏诊断字段和白名单响应头，不包含 API key、token、完整上游响应体或图片 base64。SDK/网络层只有 `Connection error.` 时，`transport_error` 会是 `true`，但不会伪造 `upstream_status`。如果页面 SSE 请求返回 `page_sse_failed`、`503`、断流，且 `summary.selected_channel_id` 与 `summary.upstream_host` 为空，按页面流式路径未跑通处理；先用 `diagnose-request.mjs` 读取结构化摘要，再用新的 `Idempotency-Key` 显式选择 Agent JSON 或 job，不自动回退。
+`diagnostics` 只包含脱敏诊断字段和白名单响应头，不包含 API key、token、完整上游响应体或图片 base64。SDK/网络层只有 `Connection error.` 时，`transport_error` 会是 `true`，但不会伪造 `upstream_status`。`diagnostics.route_decision` 与成功响应的 `execution.route_decision` 同口径，用于解释服务端为何选择或未能选择某个上游请求方式。如果页面 SSE 请求返回 `page_sse_failed`、`503`、断流，且 `summary.selected_channel_id` 与 `summary.upstream_host` 为空，按页面流式路径未跑通处理；先用 `diagnose-request.mjs` 读取结构化摘要，再用新的 `Idempotency-Key` 显式选择 Agent JSON 或 job，不自动回退。
 
 常见错误码：
 

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

@@ -130,9 +130,18 @@ function buildAgentFailureDiagnostics(result, diagnostics) {
     status: readString(request?.status),
     error_code: readString(error?.code),
     retryable: typeof error?.retryable === 'boolean' ? error.retryable : undefined,
+    channel_request_mode:
+      readString(errorDiagnostics?.channel_request_mode) || readString(execution?.channel_request_mode),
+    channel_request_mode_fallback_applied:
+      readBoolean(errorDiagnostics?.channel_request_mode_fallback_applied) ??
+      readBoolean(execution?.channel_request_mode_fallback_applied),
+    route_decision: readObject(errorDiagnostics?.route_decision) || readObject(execution?.route_decision),
     selected_channel_id: readString(errorDiagnostics?.selected_channel_id) || readString(execution?.selected_channel_id),
     upstream_host: readString(errorDiagnostics?.upstream_host) || readString(execution?.upstream_host),
-    transport_error_kind: readString(errorDiagnostics?.transport_error_kind)
+    transport_error_kind: readString(errorDiagnostics?.transport_error_kind),
+    retry_after_ms: readNonNegativeNumber(errorDiagnostics?.retry_after_ms),
+    cooldown_until: readString(errorDiagnostics?.cooldown_until),
+    cooldown_target: readObject(errorDiagnostics?.cooldown_target)
   };
 }
 
@@ -147,11 +156,27 @@ function mergeDiagnosticsIntoSummary(summary, diagnosticsResult, diagnostics) {
   return {
     ...summary,
     request_id: preferExistingString(summary.request_id, request?.request_id) || null,
+    channel_request_mode:
+      preferExistingString(summary.channel_request_mode, errorDiagnostics?.channel_request_mode, execution?.channel_request_mode) ||
+      null,
+    channel_request_mode_fallback_applied:
+      readBoolean(summary.channel_request_mode_fallback_applied) ??
+      readBoolean(errorDiagnostics?.channel_request_mode_fallback_applied) ??
+      readBoolean(execution?.channel_request_mode_fallback_applied) ??
+      null,
+    route_decision:
+      readObject(summary.route_decision) ||
+      readObject(errorDiagnostics?.route_decision) ||
+      readObject(execution?.route_decision) ||
+      null,
     selected_channel_id:
       preferExistingString(summary.selected_channel_id, errorDiagnostics?.selected_channel_id, execution?.selected_channel_id) ||
       null,
     upstream_host: preferExistingString(summary.upstream_host, errorDiagnostics?.upstream_host, execution?.upstream_host) || null,
     transport_error_kind: preferExistingString(summary.transport_error_kind, errorDiagnostics?.transport_error_kind) || null,
+    retry_after_ms: readNonNegativeNumber(summary.retry_after_ms) ?? readNonNegativeNumber(errorDiagnostics?.retry_after_ms),
+    cooldown_until: preferExistingString(summary.cooldown_until, errorDiagnostics?.cooldown_until),
+    cooldown_target: readObject(summary.cooldown_target) || readObject(errorDiagnostics?.cooldown_target) || null,
     retryable: diagnosticsRetryable ?? summary.retryable,
     agent_diagnostics_checked: true,
     agent_diagnostics_found: diagnosticsResult.found === true,
@@ -195,10 +220,22 @@ function isObject(value) {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 
+function readObject(value) {
+  return isObject(value) ? value : undefined;
+}
+
 function readString(value) {
   return typeof value === 'string' && value ? value : undefined;
 }
 
+function readBoolean(value) {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readNonNegativeNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 function readPositiveInteger(value) {
   return Number.isSafeInteger(value) && value > 0 ? value : undefined;
 }

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

@@ -42,6 +42,12 @@ export function buildSuccessSummary({ result, routing, timing, idempotencyKey, b
     image_backend: readString(execution?.image_backend) || readString(routing?.image_backend) || null,
     stream_mode: readString(execution?.stream_mode) || readString(routing?.stream_mode) || null,
     streaming_strategy: readString(execution?.streaming_strategy) || readString(routing?.streaming_strategy) || null,
+    channel_request_mode: readString(execution?.channel_request_mode) || null,
+    channel_request_mode_fallback_applied:
+      typeof execution?.channel_request_mode_fallback_applied === 'boolean'
+        ? execution.channel_request_mode_fallback_applied
+        : null,
+    route_decision: readObject(execution?.route_decision) || null,
     selected_channel_id: readString(execution?.selected_channel_id) || null,
     upstream_host: readString(execution?.upstream_host) || null,
     request_headers: readObject(execution?.request_headers),
@@ -82,6 +88,12 @@ export function buildFailureSummary({ errorBody, routing, timing, idempotencyKey
     image_backend: readString(routing?.image_backend) || null,
     stream_mode: readString(routing?.stream_mode) || null,
     streaming_strategy: readString(routing?.streaming_strategy) || null,
+    channel_request_mode: readString(diagnostics?.channel_request_mode) || null,
+    channel_request_mode_fallback_applied:
+      typeof diagnostics?.channel_request_mode_fallback_applied === 'boolean'
+        ? diagnostics.channel_request_mode_fallback_applied
+        : null,
+    route_decision: readObject(diagnostics?.route_decision) || null,
     selected_channel_id: readString(diagnostics?.selected_channel_id) || null,
     upstream_host: readString(diagnostics?.upstream_host) || null,
     transport_error_kind: readString(diagnostics?.transport_error_kind),
@@ -122,6 +134,9 @@ function stableSummary(value) {
     image_backend: value.image_backend ?? null,
     stream_mode: value.stream_mode ?? null,
     streaming_strategy: value.streaming_strategy ?? null,
+    channel_request_mode: value.channel_request_mode ?? null,
+    channel_request_mode_fallback_applied: value.channel_request_mode_fallback_applied ?? null,
+    route_decision: value.route_decision ?? null,
     selected_channel_id: value.selected_channel_id ?? null,
     upstream_host: value.upstream_host ?? null,
     transport_error_kind: value.transport_error_kind ?? null,

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

@@ -37,6 +37,11 @@ beforeEach(async () => {
     process.env.AGENT_STATE_BACKEND = 'sqlite';
     process.env.AGENT_SQLITE_PATH = path.join(tempDir, 'agent.sqlite');
     process.env.NEXT_PUBLIC_IMAGE_STORAGE_MODE = 'fs';
+    for (const key of Object.keys(process.env)) {
+        if (/^OPENAI_CHANNEL_\d+_/.test(key)) {
+            delete process.env[key];
+        }
+    }
     delete process.env.APP_PASSWORD;
     delete process.env.AGENT_API_TOKEN;
     delete process.env.OPENAI_API_KEY;
@@ -47,6 +52,7 @@ beforeEach(async () => {
     delete process.env.OPENAI_CHANNEL_1_API_KEYS;
     delete process.env.OPENAI_CHANNEL_1_BASE_URL;
     delete process.env.OPENAI_CHANNEL_1_UPSTREAM_PROFILE;
+    delete process.env.OPENAI_CHANNEL_1_REQUEST_MODES;
     delete process.env.OPENAI_CHANNEL_1_MATSCA_APP_ID;
     delete process.env.OPENAI_CHANNEL_1_MATSCA_APP_SECRET;
     delete process.env.OPENAI_CHANNEL_1_USER_AGENT;
@@ -55,6 +61,7 @@ beforeEach(async () => {
     delete process.env.OPENAI_CHANNEL_2_API_KEYS;
     delete process.env.OPENAI_CHANNEL_2_BASE_URL;
     delete process.env.OPENAI_CHANNEL_2_UPSTREAM_PROFILE;
+    delete process.env.OPENAI_CHANNEL_2_REQUEST_MODES;
     delete process.env.OPENAI_CHANNEL_2_MATSCA_APP_ID;
     delete process.env.OPENAI_CHANNEL_2_MATSCA_APP_SECRET;
     delete process.env.OPENAI_CHANNEL_2_USER_AGENT;
@@ -135,6 +142,12 @@ describe('Agent route integration', () => {
         assert.deepEqual(body.upstream_request_headers.channels, [
             {
                 id: 'matsca',
+                request_modes: [
+                    'images-non-stream',
+                    'images-sse',
+                    'responses-non-stream',
+                    'responses-sse'
+                ],
                 request_headers: {
                     user_agent_effective: 'configured',
                     has_extra_headers: true,
@@ -203,6 +216,12 @@ describe('Agent route integration', () => {
         assert.deepEqual(body.upstream_request_headers.channels, [
             {
                 id: 'matsca',
+                request_modes: [
+                    'images-non-stream',
+                    'images-sse',
+                    'responses-non-stream',
+                    'responses-sse'
+                ],
                 request_headers: {
                     user_agent_effective: 'configured',
                     has_extra_headers: true,
@@ -249,6 +268,16 @@ describe('Agent route integration', () => {
             assert.equal(firstBody.execution.image_backend, 'images-api');
             assert.equal(firstBody.execution.stream_mode, 'non_stream');
             assert.equal(firstBody.execution.streaming_strategy, 'auto');
+            assert.equal(firstBody.execution.channel_request_mode, 'images-non-stream');
+            assert.equal(firstBody.execution.channel_request_mode_fallback_applied, false);
+            assert.deepEqual(firstBody.execution.route_decision, {
+                requested_backend: 'images-api',
+                preferred_channel_request_mode: 'images-non-stream',
+                selected_channel_request_mode: 'images-non-stream',
+                fallback_applied: false,
+                selected_channel_id: 'default',
+                upstream_host: new URL(upstream.baseUrl).host
+            });
             assert.equal(firstBody.execution.upstream_host, new URL(upstream.baseUrl).host);
             assert.equal(firstBody.execution.request_headers.user_agent_effective, 'gpt-image-playground/2.1.0');
             assert.equal(firstBody.execution.request_headers.has_extra_headers, false);
@@ -390,6 +419,9 @@ describe('Agent route integration', () => {
             );
 
             assert.equal(response.status, 200);
+            const body = await response.json();
+            assert.equal(body.execution.channel_request_mode, 'images-non-stream');
+            assert.equal(body.execution.channel_request_mode_fallback_applied, false);
             const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
             assert.equal(upstreamJson.stream, false);
             assert.equal(Object.hasOwn(upstreamJson, 'partial_images'), false);
@@ -430,6 +462,87 @@ describe('Agent route integration', () => {
         }
     });
 
+    it('uses a non-streaming channel request mode when Agent auto streaming has no SSE channel', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamBody = '';
+        const upstream = await startImageUpstream((body) => {
+            upstreamBody = body;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-only';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-auto-json-channel-key', {
+                    prompt: 'agent auto json channel',
+                    stream_mode: 'auto'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const body = await response.json();
+            assert.equal(body.execution.channel_request_mode, 'images-non-stream');
+            assert.equal(body.execution.channel_request_mode_fallback_applied, true);
+            assert.deepEqual(body.execution.route_decision, {
+                requested_backend: 'images-api',
+                preferred_channel_request_mode: 'images-sse',
+                fallback_channel_request_mode: 'images-non-stream',
+                selected_channel_request_mode: 'images-non-stream',
+                fallback_applied: true,
+                selected_channel_id: 'json-only',
+                upstream_host: new URL(upstream.baseUrl).host
+            });
+            const upstreamJson = JSON.parse(upstreamBody) as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, false);
+            assert.equal(Object.hasOwn(upstreamJson, 'partial_images'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails explicit Agent stream requests instead of falling back to non-streaming request modes', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream(() => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-only';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-explicit-stream-no-sse-key', {
+                    prompt: 'agent explicit stream no sse',
+                    stream_mode: 'stream',
+                    streaming_strategy: 'openai-sse',
+                    partial_images: 2
+                })
+            );
+
+            assert.equal(response.status, 503);
+            const body = await response.json();
+            assert.equal(body.error.code, 'configuration_error');
+            assert.equal(body.error.diagnostics.channel_request_mode, 'images-sse');
+            assert.equal(body.error.diagnostics.channel_request_mode_fallback_applied, false);
+            assert.deepEqual(body.error.diagnostics.route_decision, {
+                requested_backend: 'images-api',
+                preferred_channel_request_mode: 'images-sse',
+                selected_channel_request_mode: 'images-sse',
+                fallback_applied: false,
+                no_channel_reason: '当前没有支持 images-sse 的健康渠道凭证。请调整请求策略或 OPENAI_CHANNEL_N_REQUEST_MODES。'
+            });
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('rejects OpenAI-compatible Agent generate profile violations before calling upstream', async () => {
         const { generateImage } = await loadAgentRoutes();
         let upstreamCalls = 0;
@@ -1027,6 +1140,7 @@ describe('Agent route integration', () => {
             assert.match(body.error.diagnostics.upstream_host, /^127\.0\.0\.1:\d+$/);
             assert.equal(body.error.diagnostics.channel_cooldown_scope, 'channel');
             assert.equal(body.error.diagnostics.cooldown_target.channel_id, 'default');
+            assert.equal(body.error.diagnostics.cooldown_target.request_mode, 'images-non-stream');
             assert.equal(typeof body.error.diagnostics.retry_after_ms, 'number');
             assert.equal(typeof body.error.diagnostics.cooldown_until, 'string');
             assert.equal(typeof body.error.diagnostics.elapsed_ms, 'number');
@@ -1056,6 +1170,10 @@ describe('Agent route integration', () => {
             assert.equal(diagnosticsBody.diagnostics.error.diagnostics.selected_channel_id, 'default');
             assert.match(diagnosticsBody.diagnostics.error.diagnostics.upstream_host, /^127\.0\.0\.1:\d+$/);
             assert.equal(diagnosticsBody.diagnostics.error.diagnostics.cooldown_target.channel_id, 'default');
+            assert.equal(
+                diagnosticsBody.diagnostics.error.diagnostics.cooldown_target.request_mode,
+                'images-non-stream'
+            );
             assert.equal(typeof diagnosticsBody.diagnostics.error.diagnostics.retry_after_ms, 'number');
             assert.equal(JSON.stringify(diagnosticsBody).includes('test-key'), false);
         } finally {
@@ -1105,6 +1223,8 @@ describe('Agent route integration', () => {
             assert.equal(resultBody.execution.transport, 'agent_job_polling');
             assert.equal(resultBody.execution.endpoint, '/api/agent/jobs/images/generate');
             assert.equal(resultBody.execution.route_mode, 'job');
+            assert.equal(resultBody.execution.channel_request_mode, 'images-non-stream');
+            assert.equal(resultBody.execution.channel_request_mode_fallback_applied, false);
             assert.equal(typeof resultBody.timing.elapsed_ms, 'number');
             assert.equal(resultBody.timing.elapsed_ms >= 0, true);
         } finally {
@@ -1141,6 +1261,8 @@ describe('Agent route integration', () => {
             assert.equal(resultBody.execution.transport, 'agent_job_polling');
             assert.equal(resultBody.execution.endpoint, '/api/agent/image-requests');
             assert.equal(resultBody.execution.route_mode, 'job');
+            assert.equal(resultBody.execution.channel_request_mode, 'images-non-stream');
+            assert.equal(resultBody.execution.channel_request_mode_fallback_applied, false);
             assert.equal(upstreamCalls, 1);
         } finally {
             await upstream.close();

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

@@ -44,7 +44,7 @@ function readPublicChannelEnv(env: NodeJS.ProcessEnv): Record<string, string | u
     const publicEnv: Record<string, string | undefined> = {};
     for (const key of Object.keys(env)) {
         const match =
-            /^OPENAI_CHANNEL_(\d+)_(ID|BASE_URL|UPSTREAM_PROFILE|PROVIDER_MANIFEST|API_KEYS|MATSCA_APP_ID|MATSCA_APP_SECRET|USER_AGENT|UPSTREAM_HEADERS_JSON)$/.exec(key);
+            /^OPENAI_CHANNEL_(\d+)_(ID|BASE_URL|UPSTREAM_PROFILE|PROVIDER_MANIFEST|REQUEST_MODES|API_KEYS|MATSCA_APP_ID|MATSCA_APP_SECRET|USER_AGENT|UPSTREAM_HEADERS_JSON)$/.exec(key);
         if (!match) continue;
         const [, , fieldName] = match;
         publicEnv[key] = readPublicChannelEnvValue(key, fieldName, env[key]);

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

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"3203c24f5434c569bbfec2fb425430d3e45fcbc3","created_at":"2026-06-23T13:55:49.360Z","deploy_id":"dea5a9f7-24bf-4297-a091-f730901c220a"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"34544ccd35f4321f92ab73ef5ac36603ee9f7720","created_at":"2026-06-24T14:38:59.964Z","deploy_id":"dee10b1a-4b9c-47bb-a7f3-89875a64183f"} as const;
 
 export const dynamic = 'force-dynamic';
 

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

@@ -32,6 +32,11 @@ function restoreProcessEnv(snapshot: NodeJS.ProcessEnv) {
 beforeEach(() => {
     originalEnv = { ...process.env };
     console.error = () => {};
+    for (const key of Object.keys(process.env)) {
+        if (/^OPENAI_CHANNEL_\d+_/.test(key)) {
+            delete process.env[key];
+        }
+    }
     delete process.env.APP_PASSWORD;
     delete process.env.OPENAI_API_KEY;
     delete process.env.OPENAI_API_BASE_URL;
@@ -39,6 +44,7 @@ beforeEach(() => {
     delete process.env.OPENAI_CHANNEL_1_API_KEYS;
     delete process.env.OPENAI_CHANNEL_1_BASE_URL;
     delete process.env.OPENAI_CHANNEL_1_UPSTREAM_PROFILE;
+    delete process.env.OPENAI_CHANNEL_1_REQUEST_MODES;
     delete process.env.OPENAI_CHANNEL_1_MATSCA_APP_ID;
     delete process.env.OPENAI_CHANNEL_1_MATSCA_APP_SECRET;
     delete process.env.OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED;
@@ -118,6 +124,69 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('uses a non-streaming channel request mode when page auto streaming has no SSE channel', async () => {
+        const { POST } = await import('./route');
+        const upstreamBodies: string[] = [];
+        const upstream = await startImagesJsonUpstream(async (body, _url, request) => {
+            if (request.method === 'POST') {
+                upstreamBodies.push(body);
+            }
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-only';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    streamMode: 'auto'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            assert.equal(upstreamBodies.length, 1);
+            const upstreamJson = JSON.parse(upstreamBodies[0] || '{}') as Record<string, unknown>;
+            assert.equal(upstreamJson.stream, false);
+            assert.equal(Object.hasOwn(upstreamJson, 'partial_images'), false);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('fails explicit page stream requests instead of falling back to non-streaming request modes', async () => {
+        const { POST } = await import('./route');
+        const upstreamBodies: string[] = [];
+        const upstream = await startImagesJsonUpstream(async (body, _url, request) => {
+            if (request.method === 'POST') {
+                upstreamBodies.push(body);
+            }
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-only';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    streamMode: 'stream',
+                    imageStreamingStrategy: 'openai-sse'
+                })
+            );
+
+            assert.equal(response.status, 503);
+            const body = (await response.json()) as { error?: string };
+            assert.match(body.error || '', /images-sse/);
+            assert.equal(upstreamBodies.length, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('keeps the stable SSE contract for SDK-parsed multi-image results without partial events', async () => {
         const { POST } = await import('./route');
         const upstream = await startStreamingImageUpstream(async () => [
@@ -743,13 +812,13 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
     it('rejects the experimental Responses API backend when the feature flag is disabled', async () => {
         const { POST } = await import('./route');
         const response = await POST(
-                imageFormRequest({
-                    apiBaseUrl: 'http://127.0.0.1:1/v1',
-                    apiKey: 'test-key',
-                    stream: false,
-                    streamMode: 'non_stream',
-                    imageBackend: 'responses'
-                })
+            imageFormRequest({
+                apiBaseUrl: 'http://127.0.0.1:1/v1',
+                apiKey: 'test-key',
+                stream: false,
+                streamMode: 'non_stream',
+                imageBackend: 'responses'
+            })
         );
 
         assert.equal(response.status, 400);
@@ -761,13 +830,13 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         process.env.ENABLE_RESPONSES_IMAGE_BACKEND = 'true';
         const { POST } = await import('./route');
         const response = await POST(
-                imageFormRequest({
-                    apiBaseUrl: 'http://127.0.0.1:1/v1',
-                    apiKey: 'test-key',
-                    stream: false,
-                    streamMode: 'non_stream',
-                    imageBackend: 'responses'
-                })
+            imageFormRequest({
+                apiBaseUrl: 'http://127.0.0.1:1/v1',
+                apiKey: 'test-key',
+                stream: false,
+                streamMode: 'non_stream',
+                imageBackend: 'responses'
+            })
         );
 
         assert.equal(response.status, 400);
@@ -781,14 +850,14 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         const { POST } = await import('./route');
 
         const multiImage = await POST(
-                imageFormRequest({
-                    apiBaseUrl: 'http://127.0.0.1:1/v1',
-                    apiKey: 'test-key',
-                    stream: false,
-                    streamMode: 'non_stream',
-                    imageBackend: 'responses',
-                    n: '2'
-                })
+            imageFormRequest({
+                apiBaseUrl: 'http://127.0.0.1:1/v1',
+                apiKey: 'test-key',
+                stream: false,
+                streamMode: 'non_stream',
+                imageBackend: 'responses',
+                n: '2'
+            })
         );
         assert.equal(multiImage.status, 400);
         assert.match(String(((await multiImage.json()) as Record<string, unknown>).error), /单张生成/);
@@ -799,15 +868,15 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         process.env.OPENAI_RESPONSES_API_MODEL = 'gpt-4.1';
         const { POST } = await import('./route');
         const edit = await POST(
-                imageFormRequest({
-                    apiBaseUrl: 'http://127.0.0.1:1/v1',
-                    apiKey: 'test-key',
-                    stream: false,
-                    streamMode: 'non_stream',
-                    imageBackend: 'responses',
-                    n: '2',
-                    mode: 'edit'
-                })
+            imageFormRequest({
+                apiBaseUrl: 'http://127.0.0.1:1/v1',
+                apiKey: 'test-key',
+                stream: false,
+                streamMode: 'non_stream',
+                imageBackend: 'responses',
+                n: '2',
+                mode: 'edit'
+            })
         );
         assert.equal(edit.status, 400);
         assert.match(String(((await edit.json()) as Record<string, unknown>).error), /单张编辑/);
@@ -1293,7 +1362,10 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
             };
             assert.equal(upstreamJson.tools?.[0]?.type, 'image_generation');
             assert.equal(upstreamJson.tools?.[0]?.action, 'edit');
-            assert.equal(upstreamJson.input?.[0]?.content?.some((item) => item.type === 'input_image'), true);
+            assert.equal(
+                upstreamJson.input?.[0]?.content?.some((item) => item.type === 'input_image'),
+                true
+            );
         } finally {
             await upstream.close();
         }

src/app/api/images/route.ts

@@ -43,6 +43,11 @@ import {
     type ImageStreamMode,
     type ImageStreamingStrategy
 } from '@/lib/image-upstream-strategy';
+import {
+    isStreamingChannelRequestMode,
+    resolveChannelRequestMode,
+    type ChannelRequestMode
+} from '@/lib/channel-request-mode';
 import { PAGE_PASSWORD_AUTH_ERROR_CODES } from '@/lib/page-password-auth';
 import { getServerChannelState } from '@/lib/server-channel-router';
 import { createOpenAIImageClientOptions } from '@/lib/openai-image-transport';
@@ -60,6 +65,7 @@ type StreamResolutionInput = {
     operation: StreamingOperation;
     selectedCredential?: ChannelCredential;
     sourceId?: string;
+    forceNonStream?: boolean;
 };
 
 type StreamResolution = {
@@ -69,6 +75,17 @@ type StreamResolution = {
     streamingMarkedUnavailable: boolean;
 };
 
+type ChannelRequestModePlan = {
+    preferred: ChannelRequestMode;
+    fallback?: ChannelRequestMode;
+};
+
+type PageChannelSelection = {
+    selectedCredential?: ChannelCredential;
+    requestMode: ChannelRequestMode;
+    forcedNonStream: boolean;
+};
+
 function readErrorStatus(error: unknown): number | undefined {
     if (typeof error !== 'object' || error === null) return undefined;
     if ('status' in error && typeof error.status === 'number') return error.status;
@@ -122,6 +139,14 @@ function normalizeAvailabilityBaseUrl(baseUrl: string | undefined): string {
 function resolvePageStream(input: StreamResolutionInput): StreamResolution {
     const availabilityKey = createAvailabilityKey(input);
     const streamingAvailability = getServerChannelState().streamingAvailability;
+    if (input.forceNonStream) {
+        return {
+            availabilityKey,
+            streamEnabled: false,
+            streamFallbackEnabled: false,
+            streamingMarkedUnavailable: streamingAvailability.isUnavailable(availabilityKey)
+        };
+    }
     if (input.streamMode === 'non_stream') {
         return {
             availabilityKey,
@@ -161,6 +186,67 @@ function resolvePageStream(input: StreamResolutionInput): StreamResolution {
     };
 }
 
+function resolvePageChannelRequestModePlan(input: {
+    streamMode: ImageStreamMode;
+    imageBackend: ImageGenerationBackend;
+    streamingStrategy: ImageStreamingStrategy;
+}): ChannelRequestModePlan {
+    if (input.streamMode === 'non_stream') {
+        return {
+            preferred: resolveChannelRequestMode({ imageBackend: input.imageBackend, streamEnabled: false })
+        };
+    }
+    if (input.streamMode === 'auto' && input.streamingStrategy === 'off') {
+        return {
+            preferred: resolveChannelRequestMode({ imageBackend: input.imageBackend, streamEnabled: false })
+        };
+    }
+    const preferred = resolveChannelRequestMode({
+        imageBackend: input.imageBackend,
+        streamEnabled: resolveImageStreamEnabled({
+            imageBackend: input.imageBackend,
+            requestedStream: true,
+            streamingStrategy: input.streamingStrategy
+        })
+    });
+    if (input.streamMode !== 'auto' || !isStreamingChannelRequestMode(preferred)) {
+        return { preferred };
+    }
+    return {
+        preferred,
+        fallback: resolveChannelRequestMode({ imageBackend: input.imageBackend, streamEnabled: false })
+    };
+}
+
+function selectPageServerCredential(input: {
+    router: NonNullable<ReturnType<typeof getServerChannelState>['router']>;
+    affinityKey: string;
+    plan: ChannelRequestModePlan;
+}): PageChannelSelection {
+    try {
+        return {
+            selectedCredential: input.router.select({
+                affinityKey: input.affinityKey,
+                requestMode: input.plan.preferred
+            }),
+            requestMode: input.plan.preferred,
+            forcedNonStream: false
+        };
+    } catch (error) {
+        if (!input.plan.fallback || !(error instanceof RequestValidationError)) {
+            throw error;
+        }
+        return {
+            selectedCredential: input.router.select({
+                affinityKey: input.affinityKey,
+                requestMode: input.plan.fallback
+            }),
+            requestMode: input.plan.fallback,
+            forcedNonStream: true
+        };
+    }
+}
+
 function markStreamingUnavailable(input: {
     key: StreamingAvailabilityKey;
     error?: unknown;
@@ -228,6 +314,7 @@ function releaseChannelLeaseAfterResponse(response: Response, lease: ChannelCapa
 
 export async function POST(request: NextRequest) {
     let selectedServerCredential: ChannelCredential | undefined;
+    let selectedServerRequestMode: ChannelRequestMode | undefined;
     let channelLease: ChannelCapacityLease | undefined;
     let clientRequestId: string | undefined;
     let requestLogContext: RequestLogContext | undefined;
@@ -252,9 +339,24 @@ export async function POST(request: NextRequest) {
         );
         assertSafeApiOverride(requestApiKey, requestApiBaseUrl);
         validateApiBaseUrl(requestApiBaseUrl, { allowedPlainHttpBaseUrls });
-        selectedServerCredential = requestApiKey
-            ? undefined
-            : serverChannelRouter?.select({ affinityKey: readAffinityKey(request.headers) });
+        const streamMode = readImageStreamMode(formData, process.env);
+        const imageBackend = readImageGenerationBackend(formData, process.env);
+        const streamingStrategy = readImageStreamingStrategy(formData, process.env);
+        const requestModePlan = resolvePageChannelRequestModePlan({ streamMode, imageBackend, streamingStrategy });
+        const channelSelection =
+            requestApiKey || !serverChannelRouter
+                ? {
+                      selectedCredential: undefined,
+                      requestMode: requestModePlan.preferred,
+                      forcedNonStream: false
+                  }
+                : selectPageServerCredential({
+                      router: serverChannelRouter,
+                      affinityKey: readAffinityKey(request.headers),
+                      plan: requestModePlan
+                  });
+        selectedServerCredential = channelSelection.selectedCredential;
+        selectedServerRequestMode = channelSelection.requestMode;
         const {
             apiKey: effectiveApiKey,
             baseUrl: effectiveApiBaseUrl,
@@ -280,7 +382,11 @@ export async function POST(request: NextRequest) {
         if (selectedCredential) {
             appLogger.info(
                 `已选择 API 渠道：${selectedCredential.channelId}，凭证：${selectedCredential.id}，策略：server`,
-                requestLogContext
+                {
+                    ...requestLogContext,
+                    channelRequestMode: channelSelection.requestMode,
+                    channelRequestModeFallbackApplied: channelSelection.forcedNonStream
+                }
             );
         }
 
@@ -337,12 +443,9 @@ export async function POST(request: NextRequest) {
             requestLogContext
         );
 
-        const streamMode = readImageStreamMode(formData, process.env);
         const partialImagesCount = toPartialImagesCount(
             readCount(formData, 'partial_images', 2, upstreamProfile.partialImages.min, upstreamProfile.partialImages.max)
         );
-        const imageBackend = readImageGenerationBackend(formData, process.env);
-        const streamingStrategy = readImageStreamingStrategy(formData, process.env);
         const streamResolution = resolvePageStream({
             streamMode,
             imageBackend,
@@ -352,7 +455,8 @@ export async function POST(request: NextRequest) {
             sourceId: createAvailabilitySourceId({
                 selectedCredential,
                 baseUrl: effectiveApiBaseUrl
-            })
+            }),
+            forceNonStream: channelSelection.forcedNonStream
         });
         assertResponsesImageBackendAllowed({ imageBackend, mode });
         appLogger.info('图片上游兼容策略。', {
@@ -363,6 +467,8 @@ export async function POST(request: NextRequest) {
             streamEnabled: streamResolution.streamEnabled,
             streamFallbackEnabled: streamResolution.streamFallbackEnabled,
             streamingMarkedUnavailable: streamResolution.streamingMarkedUnavailable,
+            channelRequestMode: channelSelection.requestMode,
+            channelRequestModeFallbackApplied: channelSelection.forcedNonStream,
             upstreamProfile: upstreamProfile.id,
             upstreamExtraHeaders: Boolean(upstreamHeaders)
         });
@@ -503,7 +609,7 @@ export async function POST(request: NextRequest) {
                 preview: typeof invalidResult === 'string' ? invalidResult.slice(0, 300) : invalidResult,
                 ...requestLogContext
             });
-            reportServerCredentialFailure(selectedCredential, { status: 502 });
+            reportServerCredentialFailure(selectedCredential, { status: 502 }, selectedServerRequestMode);
             const response = NextResponse.json({ error: describeInvalidImagesResponse(invalidResult) }, { status: 502 });
             const responseWithHeaders = appendChannelQueueHeaders(response, channelLease);
             channelLease?.release();
@@ -513,7 +619,7 @@ export async function POST(request: NextRequest) {
     } catch (error: unknown) {
         channelLease?.release();
         channelLease = undefined;
-        reportServerCredentialFailure(selectedServerCredential, error);
+        reportServerCredentialFailure(selectedServerCredential, error, selectedServerRequestMode);
         appLogger.error('/api/images 处理失败：', {
             ...requestLogContext,
             error: error instanceof Error ? error.message : String(error)

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

@@ -26,16 +26,19 @@ beforeEach(() => {
     delete process.env.IMAGE_UPSTREAM_MAX_RETRIES;
     delete process.env.OPENAI_API_KEY;
     delete process.env.OPENAI_API_BASE_URL;
+    delete process.env.OPENAI_ROUTING_STRATEGY;
     delete process.env.OPENAI_CHANNEL_1_ID;
     delete process.env.OPENAI_CHANNEL_1_API_KEYS;
     delete process.env.OPENAI_CHANNEL_1_BASE_URL;
     delete process.env.OPENAI_CHANNEL_1_UPSTREAM_PROFILE;
     delete process.env.OPENAI_CHANNEL_1_PROVIDER_MANIFEST;
+    delete process.env.OPENAI_CHANNEL_1_REQUEST_MODES;
     delete process.env.OPENAI_CHANNEL_2_ID;
     delete process.env.OPENAI_CHANNEL_2_API_KEYS;
     delete process.env.OPENAI_CHANNEL_2_BASE_URL;
     delete process.env.OPENAI_CHANNEL_2_UPSTREAM_PROFILE;
     delete process.env.OPENAI_CHANNEL_2_PROVIDER_MANIFEST;
+    delete process.env.OPENAI_CHANNEL_2_REQUEST_MODES;
     delete process.env.OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED;
     delete process.env.OPENAI_CHANNEL_QUEUE_ENABLED;
     delete process.env.OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS;
@@ -59,7 +62,10 @@ describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
     it('exposes streaming batch capability by default without the removed env gate', async () => {
         const { GET } = await import('./route');
 
-        const body = (await (await GET()).json()) as Record<string, { enabled: boolean; recommendedConcurrency?: number }>;
+        const body = (await (await GET()).json()) as Record<
+            string,
+            { enabled: boolean; recommendedConcurrency?: number }
+        >;
 
         assert.equal(body.streamingBatch.enabled, true);
         assert.equal(typeof body.streamingBatch.recommendedConcurrency, 'number');
@@ -204,7 +210,10 @@ describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
         assert.equal(defaultBody.upstreamProfile.serverProfile, 'openai-compatible');
         assert.equal(defaultBody.upstreamProfile.serverProfileMixed, false);
         assert.equal(defaultBody.upstreamProfile.requestProfile, 'openai-compatible');
-        assert.equal((defaultBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages, 10);
+        assert.equal(
+            (defaultBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages,
+            10
+        );
 
         process.env.OPENAI_CHANNEL_1_ID = 'matsca';
         process.env.OPENAI_CHANNEL_1_API_KEYS = 'sk-matsca';
@@ -223,7 +232,10 @@ describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
             (matscaBody.upstreamProfile.activeConstraints as { generateCount: { max: number } }).generateCount.max,
             4
         );
-        assert.equal((matscaBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages, 8);
+        assert.equal(
+            (matscaBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages,
+            8
+        );
         assert.equal(JSON.stringify(matscaBody).includes('sk-matsca'), false);
 
         process.env.OPENAI_CHANNEL_2_ID = 'official';
@@ -240,7 +252,10 @@ describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
             (mixedBody.upstreamProfile.activeConstraints as { generateCount: { max: number } }).generateCount.max,
             4
         );
-        assert.equal((mixedBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages, 8);
+        assert.equal(
+            (mixedBody.upstreamProfile.activeConstraints as { upload: { maxImages: number } }).upload.maxImages,
+            8
+        );
         assert.deepEqual(
             (mixedBody.upstreamProfile.activeConstraints as { partialImages: { min: number; max: number } })
                 .partialImages,
@@ -371,4 +386,119 @@ describe('GET /api/runtime-capabilities', { concurrency: false }, () => {
         assert.equal(enabled.responsesImageBackend.hasDefaultModel, true);
         assert.deepEqual(enabled.responsesImageBackend.missingEnv, []);
     });
+
+    it('exposes sanitized channel request modes for routing diagnostics', async () => {
+        process.env.OPENAI_ROUTING_STRATEGY = 'round_robin';
+        process.env.OPENAI_CHANNEL_1_ID = 'images';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = 'https://images.example.com/v1';
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'sk-secret';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream,images-sse';
+        const { GET } = await import('./route');
+
+        const body = (await (await GET()).json()) as {
+            channelRouting: {
+                strategy: string;
+                credentialCount: number;
+                channelCount: number;
+                supportedRequestModes: string[];
+                configuredRequestModes: string[];
+                effectiveRequestModes: string[];
+                requestModeControls: {
+                    globalEnv: string;
+                    channelEnvPattern: string;
+                    mutableAtRuntime: boolean;
+                    smokeGateCommands: Record<string, string[]>;
+                };
+                requestModeHealth: Array<{
+                    mode: string;
+                    configuredCredentialCount: number;
+                    healthyCredentialCount: number;
+                    configuredChannelCount: number;
+                    healthyChannelCount: number;
+                }>;
+                requestModesByChannel: Array<{
+                    channelId: string;
+                    requestModes: string[];
+                }>;
+                effectiveRequestModesByChannel: Array<{
+                    channelId: string;
+                    requestModes: string[];
+                }>;
+            };
+        };
+
+        assert.deepEqual(body.channelRouting, {
+            strategy: 'round_robin',
+            credentialCount: 1,
+            channelCount: 1,
+            supportedRequestModes: ['images-non-stream', 'images-sse', 'responses-non-stream', 'responses-sse'],
+            configuredRequestModes: ['images-non-stream', 'images-sse'],
+            effectiveRequestModes: ['images-non-stream', 'images-sse'],
+            requestModeControls: {
+                source: 'admin_env_whitelist',
+                globalEnv: 'OPENAI_UPSTREAM_REQUEST_MODES',
+                channelEnvPattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+                mutableAtRuntime: false,
+                finalGateCommand:
+                    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable',
+                smokeGateCommands: {
+                    'images-non-stream': [
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case original-images-json --allow-billable'
+                    ],
+                    'images-sse': [
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-images-sse --allow-billable'
+                    ],
+                    'responses-non-stream': [
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-responses-json --allow-billable'
+                    ],
+                    'responses-sse': [
+                        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+                    ]
+                }
+            },
+            requestModeHealth: [
+                {
+                    mode: 'images-non-stream',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'images-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'responses-non-stream',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                },
+                {
+                    mode: 'responses-sse',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                }
+            ],
+            requestModesByChannel: [
+                {
+                    channelId: 'images',
+                    requestModes: ['images-non-stream', 'images-sse']
+                }
+            ],
+            effectiveRequestModesByChannel: [
+                {
+                    channelId: 'images',
+                    requestModes: ['images-non-stream', 'images-sse']
+                }
+            ]
+        });
+        assert.equal(JSON.stringify(body.channelRouting).includes('sk-secret'), false);
+    });
 });

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

@@ -1,4 +1,5 @@
 import { getChannelPoolSummary, toPublicChannelFailure } from '@/lib/channel-router';
+import { CHANNEL_REQUEST_MODES, CHANNEL_REQUEST_MODE_ADMIN_CONTROL } from '@/lib/channel-request-mode';
 import { summarizeImageUpstreamProfile } from '@/lib/image-upstream-profile';
 import { readImageStreamMode, readImageStreamingStrategy } from '@/lib/image-upstream-strategy';
 import { summarizeOpenAIImageTransport } from '@/lib/openai-image-transport';
@@ -15,6 +16,7 @@ export async function GET() {
         const serverChannelState = getServerChannelState();
         const summary = getChannelPoolSummary(serverChannelState.config);
         const healthSummary = serverChannelState.router?.getHealthSummary();
+        const requestModeHealthSummary = serverChannelState.router?.getRequestModeHealthSummary();
         const maxStreamsPerCredential = readPositiveIntegerEnv(process.env, 'OPENAI_MAX_STREAMS_PER_CREDENTIAL', 1);
         const channelQueueSummary = serverChannelState.channelCapacityQueue.summary();
         const responsesImageBackendEnabled = readBooleanEnv(process.env, 'ENABLE_RESPONSES_IMAGE_BACKEND');
@@ -74,6 +76,28 @@ export async function GET() {
                 pendingProbeChannelCount: healthSummary?.pendingRecoveryProbeChannelCount ?? 0,
                 probe: serverChannelState.channelRecoveryProber?.summary()
             },
+            channelRouting: {
+                strategy: summary.strategy,
+                credentialCount: summary.credentialCount,
+                channelCount: summary.channelCount,
+                supportedRequestModes: CHANNEL_REQUEST_MODES,
+                configuredRequestModes:
+                    requestModeHealthSummary?.configuredRequestModes ?? (summary.credentialCount > 0 ? CHANNEL_REQUEST_MODES : []),
+                effectiveRequestModes:
+                    requestModeHealthSummary?.effectiveRequestModes ?? (summary.credentialCount > 0 ? CHANNEL_REQUEST_MODES : []),
+                requestModeControls: CHANNEL_REQUEST_MODE_ADMIN_CONTROL,
+                requestModeHealth: requestModeHealthSummary?.modes ?? [],
+                requestModesByChannel: summary.channels.map((channel) => ({
+                    channelId: channel.id,
+                    requestModes: channel.requestModes
+                })),
+                effectiveRequestModesByChannel:
+                    requestModeHealthSummary?.effectiveRequestModesByChannel ??
+                    summary.channels.map((channel) => ({
+                        channelId: channel.id,
+                        requestModes: channel.requestModes
+                    }))
+            },
             upstreamProfile,
             imageTransport: summarizeOpenAIImageTransport(process.env),
             providerManifests,

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

@@ -524,6 +524,35 @@ describe('buildAgentCapabilities', () => {
             required_env: ['ENABLE_RESPONSES_IMAGE_BACKEND', 'OPENAI_RESPONSES_API_MODEL'],
             missing_env: ['ENABLE_RESPONSES_IMAGE_BACKEND', 'OPENAI_RESPONSES_API_MODEL']
         });
+        assert.deepEqual(capabilities.supported.request_modes, [
+            'images-non-stream',
+            'images-sse',
+            'responses-non-stream',
+            'responses-sse'
+        ]);
+        assert.deepEqual(capabilities.request_mode_controls, {
+            source: 'admin_env_whitelist',
+            global_env: 'OPENAI_UPSTREAM_REQUEST_MODES',
+            channel_env_pattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+            mutable_at_runtime: false,
+            agent_client_policy: 'diagnostics_only',
+            final_gate_command:
+                'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable',
+            smoke_gate_commands: {
+                'images-non-stream': [
+                    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case original-images-json --allow-billable'
+                ],
+                'images-sse': [
+                    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-images-sse --allow-billable'
+                ],
+                'responses-non-stream': [
+                    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-responses-json --allow-billable'
+                ],
+                'responses-sse': [
+                    'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+                ]
+            }
+        });
         assert.deepEqual(capabilities.supported.streaming_strategies, [
             'off',
             'auto',
@@ -560,6 +589,28 @@ describe('buildAgentCapabilities', () => {
         assert.match(capabilities.agent_jobs.current_guidance, /job/);
     });
 
+    it('reports configured server-channel request modes in Agent capabilities', () => {
+        const capabilities = buildAgentCapabilities({
+            OPENAI_CHANNEL_1_ID: 'images',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://images.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'configured',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-json,images-sse'
+        });
+
+        assert.deepEqual(capabilities.upstream_request_headers.channels, [
+            {
+                id: 'images',
+                request_modes: ['images-non-stream', 'images-sse'],
+                request_headers: {
+                    user_agent_effective: 'gpt-image-playground/2.1.0',
+                    has_extra_headers: false,
+                    allowed_header_names: ['user-agent', 'x-app-id', 'x-app-secret'],
+                    configured_header_names: []
+                }
+            }
+        ]);
+    });
+
     it('reports Matsca server-channel upload and image-count limits in Agent capabilities', () => {
         const capabilities = buildAgentCapabilities({
             OPENAI_CHANNEL_1_ID: 'matsca',
@@ -820,6 +871,25 @@ describe('buildAgentCapabilities', () => {
         assert.ok('AgentErrorDiagnostics' in document.components.schemas);
         assert.ok('AgentImageResponseTiming' in document.components.schemas);
         assert.ok('AgentImageResponseExecution' in document.components.schemas);
+        assert.ok('ChannelRequestModeDecision' in document.components.schemas);
+        assert.deepEqual(document.components.schemas.AgentImageResponseExecution.properties.channel_request_mode.enum, [
+            'images-non-stream',
+            'images-sse',
+            'responses-non-stream',
+            'responses-sse'
+        ]);
+        assert.equal(
+            document.components.schemas.AgentImageResponseExecution.properties.channel_request_mode_fallback_applied.type,
+            'boolean'
+        );
+        assert.equal(
+            document.components.schemas.AgentImageResponseExecution.properties.route_decision.$ref,
+            '#/components/schemas/ChannelRequestModeDecision'
+        );
+        assert.equal(
+            document.components.schemas.ChannelRequestModeDecision.properties.requested_backend.enum.includes('images-api'),
+            true
+        );
         assert.ok('UpstreamRequestHeaderSummary' in document.components.schemas);
         assert.ok('AgentRequestDiagnosticsCapabilities' in document.components.schemas);
         assert.ok('AgentRequestDiagnosticsRetention' in document.components.schemas);
@@ -998,6 +1068,20 @@ describe('buildAgentCapabilities', () => {
             'responses-image-generation'
         ]);
         assert.ok(capabilityProperties.supported.properties.image_backend_requirements);
+        assert.deepEqual(capabilityProperties.supported.properties.request_modes.items.enum, [
+            'images-non-stream',
+            'images-sse',
+            'responses-non-stream',
+            'responses-sse'
+        ]);
+        assert.equal(
+            document.components.schemas.AgentRequestModeControls.properties.agent_client_policy.const,
+            'diagnostics_only'
+        );
+        assert.equal(
+            document.components.schemas.AgentRequestModeControls.properties.channel_env_pattern.type,
+            'string'
+        );
         assert.deepEqual(
             document.components.schemas.AgentStreamingCapabilities.properties.upstream_sse.properties.request_fields
                 .const,
@@ -1061,11 +1145,29 @@ describe('buildAgentCapabilities', () => {
         assert.equal(document.components.schemas.AgentRoutingRules.required.includes('long_image_recovery'), true);
         assert.match(document.components.schemas.EditRequest.description, /\/api\/images/);
         assert.ok('upstream_event_type' in document.components.schemas.AgentErrorDiagnostics.properties);
+        assert.deepEqual(document.components.schemas.AgentErrorDiagnostics.properties.channel_request_mode.enum, [
+            'images-non-stream',
+            'images-sse',
+            'responses-non-stream',
+            'responses-sse'
+        ]);
+        assert.equal(
+            document.components.schemas.AgentErrorDiagnostics.properties.channel_request_mode_fallback_applied.type,
+            'boolean'
+        );
+        assert.equal(
+            document.components.schemas.AgentErrorDiagnostics.properties.route_decision.$ref,
+            '#/components/schemas/ChannelRequestModeDecision'
+        );
         assert.ok('partial_image_count' in document.components.schemas.AgentErrorDiagnostics.properties);
         assert.ok('transport_error_kind' in document.components.schemas.AgentErrorDiagnostics.properties);
         assert.ok('retry_after_ms' in document.components.schemas.AgentErrorDiagnostics.properties);
         assert.ok('cooldown_until' in document.components.schemas.AgentErrorDiagnostics.properties);
         assert.ok('cooldown_target' in document.components.schemas.AgentErrorDiagnostics.properties);
+        assert.deepEqual(
+            document.components.schemas.AgentErrorDiagnostics.properties.cooldown_target.properties.request_mode.enum,
+            ['images-non-stream', 'images-sse', 'responses-non-stream', 'responses-sse']
+        );
         assert.equal(document.components.schemas.ResultFeedback.properties.note.maxLength, 500);
     });
 

src/lib/agent-api-contracts.ts

@@ -2,6 +2,12 @@ import { AGENT_ENDPOINTS, AGENT_JOB_ENDPOINTS } from './agent-api-paths.mjs';
 import type { AgentErrorDiagnostics } from './api-error-response';
 import { readAppLogRetentionMetadata, type AppLogRetentionMetadata } from './app-log-retention';
 import { getChannelPoolSummary, parseChannelPoolConfig } from './channel-router';
+import {
+    CHANNEL_REQUEST_MODES,
+    CHANNEL_REQUEST_MODE_ADMIN_CONTROL,
+    type ChannelRequestMode,
+    type ChannelRequestModeDecision
+} from './channel-request-mode';
 import {
     MAX_IMAGE_COUNT,
     MAX_PROMPT_LENGTH,
@@ -174,6 +180,9 @@ export type AgentImageResponseExecution = {
     image_backend: ImageGenerationBackend;
     stream_mode: ImageStreamMode;
     streaming_strategy: ImageStreamingStrategy;
+    channel_request_mode?: ChannelRequestMode;
+    channel_request_mode_fallback_applied?: boolean;
+    route_decision?: ChannelRequestModeDecision;
     selected_channel_id?: string;
     upstream_host?: string;
     request_headers: UpstreamRequestHeaderSummary;
@@ -231,9 +240,19 @@ export type AgentCapabilities = {
         default: UpstreamRequestHeaderSummary;
         channels: Array<{
             id: string;
+            request_modes: readonly ChannelRequestMode[];
             request_headers: UpstreamRequestHeaderSummary;
         }>;
     };
+    request_mode_controls: {
+        source: 'admin_env_whitelist';
+        global_env: string;
+        channel_env_pattern: string;
+        mutable_at_runtime: false;
+        agent_client_policy: 'diagnostics_only';
+        final_gate_command: string;
+        smoke_gate_commands: Record<ChannelRequestMode, readonly string[]>;
+    };
     defaults: {
         model: GptImageModel;
         response_mode: AgentResponseMode;
@@ -366,6 +385,7 @@ export type AgentCapabilities = {
         image_backends: readonly ImageGenerationBackend[];
         enabled_image_backends: readonly ImageGenerationBackend[];
         image_backend_requirements: Record<ImageGenerationBackend, ImageBackendRuntimeRequirement>;
+        request_modes: readonly ChannelRequestMode[];
         streaming_strategies: readonly ImageStreamingStrategy[];
         stream_modes: readonly ImageStreamMode[];
     };
@@ -909,6 +929,7 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
         image_transport: summarizeOpenAIImageTransport(env),
         upstream_profile: upstreamLimits.summary,
         upstream_request_headers: buildAgentUpstreamRequestHeadersCapabilities(env),
+        request_mode_controls: buildAgentRequestModeControlsCapabilities(),
         defaults: {
             model: 'gpt-image-2',
             response_mode: 'path',
@@ -1141,6 +1162,7 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
             image_backends: AGENT_IMAGE_BACKENDS,
             enabled_image_backends: enabledImageBackends,
             image_backend_requirements: imageBackendRequirements,
+            request_modes: CHANNEL_REQUEST_MODES,
             streaming_strategies: AGENT_STREAMING_STRATEGIES,
             stream_modes: AGENT_STREAM_MODES
         },
@@ -1158,12 +1180,25 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
     };
 }
 
+function buildAgentRequestModeControlsCapabilities(): AgentCapabilities['request_mode_controls'] {
+    return {
+        source: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.source,
+        global_env: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.globalEnv,
+        channel_env_pattern: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.channelEnvPattern,
+        mutable_at_runtime: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.mutableAtRuntime,
+        agent_client_policy: 'diagnostics_only',
+        final_gate_command: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.finalGateCommand,
+        smoke_gate_commands: CHANNEL_REQUEST_MODE_ADMIN_CONTROL.smokeGateCommands
+    };
+}
+
 function buildAgentUpstreamRequestHeadersCapabilities(env: Record<string, string | undefined>): AgentCapabilities['upstream_request_headers'] {
     const channelSummary = getChannelPoolSummary(parseChannelPoolConfig(env));
     return {
         default: summarizeUpstreamRequestHeaders(undefined, env),
         channels: channelSummary.channels.map((channel) => ({
             id: channel.id,
+            request_modes: channel.requestModes,
             request_headers: channel.requestHeaders
         }))
     };

src/lib/agent-channel-request-mode.ts

@@ -0,0 +1,151 @@
+import { AgentApiError } from './api-error-response';
+import {
+    isStreamingChannelRequestMode,
+    resolveChannelRequestMode,
+    type ChannelRequestMode,
+    type ChannelRequestModeBackend,
+    type ChannelRequestModeDecision
+} from './channel-request-mode';
+import type { ChannelCredential } from './channel-router';
+import { RequestValidationError } from './image-request-utils';
+import {
+    resolveImageStreamEnabled,
+    type ImageStreamMode,
+    type ImageStreamingStrategy
+} from './image-upstream-strategy';
+import type { getServerChannelState } from './server-channel-router';
+import { readAffinityKey } from './server-runtime';
+
+export type AgentChannelRequestModePlan = {
+    imageBackend: ChannelRequestModeBackend;
+    preferred: ChannelRequestMode;
+    fallback?: ChannelRequestMode;
+};
+
+export type AgentChannelSelection = {
+    selectedCredential?: ChannelCredential;
+    requestMode: ChannelRequestMode;
+    fallbackApplied: boolean;
+    noChannelReason?: string;
+};
+
+export function createAgentChannelRequestModePlan(input: {
+    imageBackend: ChannelRequestModeBackend;
+    streamMode: ImageStreamMode;
+    streamingStrategy: ImageStreamingStrategy;
+}): AgentChannelRequestModePlan {
+    const preferred = resolveChannelRequestMode({
+        imageBackend: input.imageBackend,
+        streamEnabled: resolveStaticAgentStreamEnabled(input)
+    });
+    if (input.streamMode !== 'auto' || !isStreamingChannelRequestMode(preferred)) {
+        return { imageBackend: input.imageBackend, preferred };
+    }
+    return {
+        imageBackend: input.imageBackend,
+        preferred,
+        fallback: resolveChannelRequestMode({ imageBackend: input.imageBackend, streamEnabled: false })
+    };
+}
+
+export function selectAgentChannelCredential(input: {
+    router: ReturnType<typeof getServerChannelState>['router'];
+    headers: Headers;
+    requestModePlan: AgentChannelRequestModePlan;
+}): AgentChannelSelection {
+    try {
+        return selectAgentChannelForMode(input, input.requestModePlan.preferred, false);
+    } catch (error) {
+        if (!input.requestModePlan.fallback || !(error instanceof RequestValidationError)) {
+            throw normalizeChannelSelectionError(error, input.requestModePlan, false);
+        }
+        try {
+            return selectAgentChannelForMode(input, input.requestModePlan.fallback, true);
+        } catch (fallbackError) {
+            throw normalizeChannelSelectionError(fallbackError, input.requestModePlan, true);
+        }
+    }
+}
+
+export function buildAgentChannelRequestModeDecision(input: {
+    requestModePlan: AgentChannelRequestModePlan;
+    selection: AgentChannelSelection;
+    selectedCredential?: ChannelCredential;
+    upstreamHost?: string;
+}): ChannelRequestModeDecision {
+    const selectedChannelId = input.selectedCredential?.channelId ?? input.selection.selectedCredential?.channelId;
+    return {
+        requested_backend: input.requestModePlan.imageBackend,
+        preferred_channel_request_mode: input.requestModePlan.preferred,
+        ...(input.requestModePlan.fallback ? { fallback_channel_request_mode: input.requestModePlan.fallback } : {}),
+        selected_channel_request_mode: input.selection.requestMode,
+        fallback_applied: input.selection.fallbackApplied,
+        ...(selectedChannelId ? { selected_channel_id: selectedChannelId } : {}),
+        ...(input.upstreamHost ? { upstream_host: input.upstreamHost } : {}),
+        ...(input.selection.noChannelReason ? { no_channel_reason: input.selection.noChannelReason } : {})
+    };
+}
+
+function resolveStaticAgentStreamEnabled(input: {
+    imageBackend: ChannelRequestModeBackend;
+    streamMode: ImageStreamMode;
+    streamingStrategy: ImageStreamingStrategy;
+}): boolean {
+    if (input.streamMode === 'non_stream') return false;
+    if (input.streamMode === 'auto' && input.streamingStrategy === 'off') return false;
+    return resolveImageStreamEnabled({
+        imageBackend: input.imageBackend,
+        requestedStream: true,
+        streamingStrategy: input.streamingStrategy
+    });
+}
+
+function selectAgentChannelForMode(
+    input: {
+        router: ReturnType<typeof getServerChannelState>['router'];
+        headers: Headers;
+    },
+    requestMode: ChannelRequestMode,
+    fallbackApplied: boolean
+): AgentChannelSelection {
+    return {
+        selectedCredential: input.router?.select({
+            affinityKey: readAffinityKey(input.headers),
+            requestMode
+        }),
+        requestMode,
+        fallbackApplied
+    };
+}
+
+function normalizeChannelSelectionError(
+    error: unknown,
+    requestModePlan: AgentChannelRequestModePlan,
+    fallbackApplied: boolean
+): unknown {
+    if (!(error instanceof RequestValidationError)) {
+        return error;
+    }
+    const requestMode = fallbackApplied
+        ? (requestModePlan.fallback ?? requestModePlan.preferred)
+        : requestModePlan.preferred;
+    return new AgentApiError({
+        code: error.status >= 500 ? 'configuration_error' : 'validation_error',
+        message: error.message,
+        status: error.status,
+        retryable: false,
+        details: error.details,
+        diagnostics: {
+            channel_request_mode: requestMode,
+            channel_request_mode_fallback_applied: fallbackApplied,
+            route_decision: buildAgentChannelRequestModeDecision({
+                requestModePlan,
+                selection: {
+                    requestMode,
+                    fallbackApplied,
+                    noChannelReason: error.message
+                }
+            })
+        }
+    });
+}

src/lib/agent-image-service.ts

@@ -7,6 +7,12 @@ import {
     validateAgentGenerateRequest
 } from './agent-api-contracts';
 import { AGENT_ENDPOINTS } from './agent-api-paths.mjs';
+import {
+    buildAgentChannelRequestModeDecision,
+    createAgentChannelRequestModePlan,
+    selectAgentChannelCredential,
+    type AgentChannelRequestModePlan
+} from './agent-channel-request-mode';
 import { assertArtifactFilepathAllowed, deleteArtifactFileIfAllowed } from './agent-file-utils';
 import {
     artifactRecordToResponseItem,
@@ -20,10 +26,20 @@ import {
     type BeginAgentRequestResult,
     type AgentStateStore
 } from './agent-state-store';
-import { AgentApiError, normalizeAgentError, storedAgentErrorResponse, type AgentErrorBody } from './api-error-response';
+import {
+    AgentApiError,
+    normalizeAgentError,
+    storedAgentErrorResponse,
+    type AgentErrorBody
+} from './api-error-response';
 import type { AgentErrorDiagnostics } from './api-error-response';
 import { appLogger } from './app-logger';
 import type { ChannelCapacityLease } from './channel-capacity-queue';
+import {
+    isStreamingChannelRequestMode,
+    type ChannelRequestMode,
+    type ChannelRequestModeDecision
+} from './channel-request-mode';
 import {
     type ChannelCredential,
     type ChannelFailureReport,
@@ -53,13 +69,7 @@ import {
     MissingOpenAiImageDataError,
     persistOpenAiImages as persistSharedOpenAiImages
 } from './image-service';
-import {
-    parseImageStreamModeValue,
-    parseImageStreamingStrategyValue,
-    resolveImageStreamEnabled,
-    type ImageStreamMode,
-    type ImageStreamingStrategy
-} from './image-upstream-strategy';
+import { collectOpenAiImagesFromStream } from './image-stream-collector';
 import {
     readImageUpstreamProfile,
     mergeUpstreamHeadersWithFixed,
@@ -68,21 +78,27 @@ import {
     type PartialImagesCount,
     type UpstreamRequestHeaders
 } from './image-upstream-profile';
-import { collectOpenAiImagesFromStream } from './image-stream-collector';
+import {
+    parseImageStreamModeValue,
+    parseImageStreamingStrategyValue,
+    resolveImageStreamEnabled,
+    type ImageStreamMode,
+    type ImageStreamingStrategy
+} from './image-upstream-strategy';
 import { createImagesApiGenerateStream } from './images-api-stream';
+import { buildOpenAIImageRequestOptions, createOpenAIImageClientOptions } from './openai-image-transport';
 import {
     createResponsesImageStream,
     generateImageWithResponsesBackend,
     type ResponsesImageGenerateInput
 } from './responses-image-backend';
-import { buildOpenAIImageRequestOptions, createOpenAIImageClientOptions } from './openai-image-transport';
 import { getServerChannelState } from './server-channel-router';
+import { readBooleanEnv } from './server-runtime';
 import type { StreamingAvailabilityKey } from './streaming-availability';
-import { readAffinityKey, readBooleanEnv } from './server-runtime';
 import crypto from 'crypto';
 import fs from 'fs/promises';
-import OpenAI from 'openai';
 import { NextResponse } from 'next/server';
+import OpenAI from 'openai';
 
 export type AgentRequestExecutionResult = {
     response: AgentImageResponse;
@@ -93,6 +109,9 @@ export type AgentRequestExecutionResult = {
 type CredentialContext = {
     openai: OpenAI;
     selectedCredential?: ChannelCredential;
+    channelRequestMode?: ChannelRequestMode;
+    channelRequestModeFallbackApplied: boolean;
+    channelRequestModeDecision: ChannelRequestModeDecision;
     baseUrl?: string;
     apiKey: string;
     upstreamProfile: ImageUpstreamProfile;
@@ -123,6 +142,7 @@ type AgentStreamOptions = {
     streamingStrategy: ImageStreamingStrategy;
     partialImages: PartialImagesCount;
     selectedCredential?: ChannelCredential;
+    channelRequestMode?: ChannelRequestMode;
 };
 
 type AgentEditStreamRequest = {
@@ -141,6 +161,9 @@ type AgentExecutionMetadata = {
     imageBackend: AgentImageResponseExecution['image_backend'];
     streamMode: ImageStreamMode;
     streamingStrategy: ImageStreamingStrategy;
+    channelRequestMode?: ChannelRequestMode;
+    channelRequestModeFallbackApplied: boolean;
+    channelRequestModeDecision: ChannelRequestModeDecision;
     selectedCredential?: ChannelCredential;
 };
 
@@ -242,16 +265,32 @@ export async function agentBeginResultResponse(
 }
 
 export function prepareAgentGenerate(request: AgentGenerateRequest, headers: Headers): AgentGeneratePreparation {
-    const credentialContext = createOpenAiClient(headers);
+    const credentialContext = createOpenAiClient(headers, resolveAgentGenerateChannelRequestModePlan(request));
     validateAgentGenerateAgainstUpstreamProfile(request, credentialContext.upstreamProfile);
     return { credentialContext };
 }
 
+function resolveAgentGenerateChannelRequestModePlan(request: AgentGenerateRequest): AgentChannelRequestModePlan {
+    return createAgentChannelRequestModePlan({
+        imageBackend: request.image_backend,
+        streamMode: request.stream_mode,
+        streamingStrategy: request.streaming_strategy
+    });
+}
+
+function resolveAgentEditChannelRequestModePlan(formData: FormData): AgentChannelRequestModePlan {
+    return createAgentChannelRequestModePlan({
+        imageBackend: 'images-api',
+        streamMode: readAgentEditStreamMode(formData),
+        streamingStrategy: readAgentEditStreamingStrategy(formData)
+    });
+}
+
 export async function prepareAgentEdit(formData: FormData, headers: Headers): Promise<AgentEditPreparation> {
     const prompt = readRequiredText(formData, 'prompt');
     const model = readModel(formData);
     assertImageFilesPresent(formData);
-    const credentialContext = createOpenAiClient(headers);
+    const credentialContext = createOpenAiClient(headers, resolveAgentEditChannelRequestModePlan(formData));
     const n = readCount(
         formData,
         'n',
@@ -275,10 +314,7 @@ export async function prepareAgentEdit(formData: FormData, headers: Headers): Pr
     return { credentialContext, prompt, model, n, size, quality, responseMode, streamRequest, imageFiles, maskFile };
 }
 
-function buildOpenAiRequestOptions(
-    context: CredentialContext,
-    abortSignal?: AbortSignal
-): OpenAI.RequestOptions {
+function buildOpenAiRequestOptions(context: CredentialContext, abortSignal?: AbortSignal): OpenAI.RequestOptions {
     return buildOpenAIImageRequestOptions({
         abortSignal,
         headers: mergeUpstreamHeadersWithFixed(context.upstreamHeaders, {})
@@ -350,17 +386,15 @@ export async function executeAgentGenerate(options: {
     transport?: AgentExecutionTransportContext;
     abortSignal?: AbortSignal;
 }): Promise<AgentRequestExecutionResult> {
-    const credentialContext = options.preparation?.credentialContext ?? prepareAgentGenerate(options.request, options.headers).credentialContext;
+    const credentialContext =
+        options.preparation?.credentialContext ??
+        prepareAgentGenerate(options.request, options.headers).credentialContext;
     const startedAtMs = Date.now();
     const startedAt = isoDate(new Date(startedAtMs));
     let channelLease: ChannelCapacityLease | undefined;
     try {
         channelLease = await acquireAgentChannelCapacity(credentialContext, options.abortSignal);
-        const result = await executeAgentGenerateUpstream(
-            options.request,
-            credentialContext,
-            options.abortSignal
-        );
+        const result = await executeAgentGenerateUpstream(options.request, credentialContext, options.abortSignal);
         channelLease?.release();
         channelLease = undefined;
         return await persistOpenAiImages({
@@ -388,12 +422,19 @@ export async function executeAgentGenerate(options: {
                 imageBackend: options.request.image_backend,
                 streamMode: options.request.stream_mode,
                 streamingStrategy: options.request.streaming_strategy,
+                channelRequestMode: credentialContext.channelRequestMode,
+                channelRequestModeFallbackApplied: credentialContext.channelRequestModeFallbackApplied,
+                channelRequestModeDecision: credentialContext.channelRequestModeDecision,
                 selectedCredential: credentialContext.selectedCredential
             },
             abortSignal: options.abortSignal
         });
     } catch (error) {
-        const failureReport = reportServerCredentialFailure(credentialContext.selectedCredential, error);
+        const failureReport = reportServerCredentialFailure(
+            credentialContext.selectedCredential,
+            error,
+            credentialContext.channelRequestMode
+        );
         throw normalizeAgentError(error, buildAgentExecutionDiagnostics(credentialContext, startedAtMs, failureReport));
     } finally {
         channelLease?.release();
@@ -412,7 +453,8 @@ async function executeAgentGenerateUpstream(
         streamMode: request.stream_mode,
         streamingStrategy: request.streaming_strategy,
         partialImages: request.partial_images,
-        selectedCredential: credentialContext.selectedCredential
+        selectedCredential: credentialContext.selectedCredential,
+        channelRequestMode: credentialContext.channelRequestMode
     };
     if (request.image_backend === 'responses-image-generation') {
         return executeAgentResponsesGenerate(request, credentialContext, abortSignal);
@@ -475,7 +517,10 @@ function validateAgentGenerateAgainstUpstreamProfile(
             422
         );
     }
-    if (request.partial_images < upstreamProfile.partialImages.min || request.partial_images > upstreamProfile.partialImages.max) {
+    if (
+        request.partial_images < upstreamProfile.partialImages.min ||
+        request.partial_images > upstreamProfile.partialImages.max
+    ) {
         throw new RequestValidationError(
             `partial_images 必须在 ${upstreamProfile.partialImages.min} 到 ${upstreamProfile.partialImages.max} 之间。`,
             422
@@ -528,7 +573,8 @@ async function executeAgentResponsesGenerate(
         streamMode: request.stream_mode,
         streamingStrategy: request.streaming_strategy,
         partialImages: request.partial_images,
-        selectedCredential: credentialContext.selectedCredential
+        selectedCredential: credentialContext.selectedCredential,
+        channelRequestMode: credentialContext.channelRequestMode
     };
     if (!shouldUseAgentUpstreamStream(streamOptions)) {
         return generateImageWithResponsesBackend(input);
@@ -561,6 +607,7 @@ function shouldUseAgentUpstreamStream(input: AgentStreamOptions): boolean {
     const key = createAgentStreamingAvailabilityKey(input);
     const availability = getServerChannelState().streamingAvailability;
     if (input.streamMode === 'non_stream') return false;
+    if (input.channelRequestMode && !isStreamingChannelRequestMode(input.channelRequestMode)) return false;
     if (input.streamMode === 'auto' && availability.isUnavailable(key)) return false;
     return resolveImageStreamEnabled({
         imageBackend: input.imageBackend,
@@ -643,7 +690,7 @@ export async function executeAgentEdit(options: {
     const startedAt = isoDate(new Date(startedAtMs));
     let channelLease: ChannelCapacityLease | undefined;
     try {
-        const preparation = options.preparation ?? await prepareAgentEdit(options.formData, options.headers);
+        const preparation = options.preparation ?? (await prepareAgentEdit(options.formData, options.headers));
         credentialContext = preparation.credentialContext;
         const editParams: OpenAI.Images.ImageEditParamsNonStreaming = {
             model: preparation.model,
@@ -660,7 +707,8 @@ export async function executeAgentEdit(options: {
             streamMode: preparation.streamRequest.streamMode,
             streamingStrategy: preparation.streamRequest.streamingStrategy,
             partialImages: preparation.streamRequest.partialImages,
-            selectedCredential: credentialContext.selectedCredential
+            selectedCredential: credentialContext.selectedCredential,
+            channelRequestMode: credentialContext.channelRequestMode
         };
         channelLease = await acquireAgentChannelCapacity(credentialContext, options.abortSignal);
         const result = shouldUseAgentUpstreamStream(streamOptions)
@@ -702,12 +750,19 @@ export async function executeAgentEdit(options: {
                 imageBackend: 'images-api',
                 streamMode: preparation.streamRequest.streamMode,
                 streamingStrategy: preparation.streamRequest.streamingStrategy,
+                channelRequestMode: credentialContext.channelRequestMode,
+                channelRequestModeFallbackApplied: credentialContext.channelRequestModeFallbackApplied,
+                channelRequestModeDecision: credentialContext.channelRequestModeDecision,
                 selectedCredential: credentialContext.selectedCredential
             },
             abortSignal: options.abortSignal
         });
     } catch (error) {
-        const failureReport = reportServerCredentialFailure(credentialContext?.selectedCredential, error);
+        const failureReport = reportServerCredentialFailure(
+            credentialContext?.selectedCredential,
+            error,
+            credentialContext?.channelRequestMode
+        );
         throw normalizeAgentError(error, buildAgentExecutionDiagnostics(credentialContext, startedAtMs, failureReport));
     } finally {
         channelLease?.release();
@@ -895,9 +950,14 @@ export async function hydrateAgentReplayResponse(
     };
 }
 
-function createOpenAiClient(headers: Headers): CredentialContext {
+function createOpenAiClient(headers: Headers, requestModePlan: AgentChannelRequestModePlan): CredentialContext {
     const serverChannelRouter = getServerChannelState().router;
-    const selectedCredential = serverChannelRouter?.select({ affinityKey: readAffinityKey(headers) });
+    const selection = selectAgentChannelCredential({
+        router: serverChannelRouter,
+        headers,
+        requestModePlan
+    });
+    const selectedCredential = selection.selectedCredential;
     const {
         apiKey,
         baseUrl,
@@ -912,12 +972,21 @@ function createOpenAiClient(headers: Headers): CredentialContext {
     validateApiBaseUrl(baseUrl || '', {
         allowedPlainHttpBaseUrls: readPlainHttpApiBaseUrlAllowlist(process.env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS)
     });
+    const channelRequestModeDecision = buildAgentChannelRequestModeDecision({
+        requestModePlan,
+        selection,
+        selectedCredential: effectiveSelectedCredential,
+        upstreamHost: baseUrl ? readUrlHost(baseUrl) : undefined
+    });
     if (!apiKey) {
         throw new AgentApiError({
             code: 'configuration_error',
             message: '未配置服务端 API Key。请设置 OPENAI_API_KEY 或 OPENAI_CHANNEL_N_API_KEYS。',
             status: 500,
-            retryable: false
+            retryable: false,
+            diagnostics: {
+                route_decision: channelRequestModeDecision
+            }
         });
     }
     return {
@@ -929,6 +998,9 @@ function createOpenAiClient(headers: Headers): CredentialContext {
             })
         ),
         selectedCredential: effectiveSelectedCredential,
+        channelRequestMode: selection.requestMode,
+        channelRequestModeFallbackApplied: selection.fallbackApplied,
+        channelRequestModeDecision,
         baseUrl,
         apiKey,
         upstreamProfile:
@@ -950,19 +1022,27 @@ function buildAgentExecutionDiagnostics(
     const upstreamHost = context?.baseUrl ? readUrlHost(context.baseUrl) : undefined;
     return {
         elapsed_ms: Date.now() - startedAtMs,
+        ...(context?.channelRequestMode ? { channel_request_mode: context.channelRequestMode } : {}),
+        ...(context ? { channel_request_mode_fallback_applied: context.channelRequestModeFallbackApplied } : {}),
+        ...(context?.channelRequestModeDecision ? { route_decision: context.channelRequestModeDecision } : {}),
         ...(context?.selectedCredential?.channelId
             ? { selected_channel_id: context.selectedCredential.channelId }
             : {}),
         ...(upstreamHost ? { upstream_host: upstreamHost } : {}),
-        ...(failureReport?.cooldownApplied ? {
-            retry_after_ms: failureReport.retryAfterMs,
-            cooldown_until: isoDate(new Date(failureReport.cooldownUntil)),
-            cooldown_target: {
-                channel_id: failureReport.target.channelId,
-                ...(failureReport.target.credentialId ? { credential_id: failureReport.target.credentialId } : {})
-            },
-            channel_cooldown_scope: failureReport.scope
-        } : {})
+        ...(failureReport?.cooldownApplied
+            ? {
+                  retry_after_ms: failureReport.retryAfterMs,
+                  cooldown_until: isoDate(new Date(failureReport.cooldownUntil)),
+                  cooldown_target: {
+                      channel_id: failureReport.target.channelId,
+                      ...(failureReport.target.credentialId
+                          ? { credential_id: failureReport.target.credentialId }
+                          : {}),
+                      ...(failureReport.target.requestMode ? { request_mode: failureReport.target.requestMode } : {})
+                  },
+                  channel_cooldown_scope: failureReport.scope
+              }
+            : {})
     };
 }
 
@@ -976,13 +1056,17 @@ function readUrlHost(value: string): string | undefined {
 
 function reportServerCredentialFailure(
     credential: ChannelCredential | undefined,
-    error: unknown
+    error: unknown,
+    requestMode?: ChannelRequestMode
 ): ChannelFailureReport | undefined {
     const serverChannelRouter = getServerChannelState().router;
     if (!credential || !serverChannelRouter) return undefined;
     if (isChannelFailure(error)) {
-        const reason = describeChannelFailure(error, 'channel');
-        const report = serverChannelRouter.reportFailure(credential, { scope: 'channel', reason });
+        const reason = {
+            ...describeChannelFailure(error, 'channel'),
+            ...(requestMode ? { requestMode } : {})
+        };
+        const report = serverChannelRouter.reportFailure(credential, { scope: 'channel', requestMode, reason });
         appLogger.warn(
             report.cooldownApplied
                 ? `Temporarily cooling down API channel: ${credential.channelId}`
@@ -992,8 +1076,11 @@ function reportServerCredentialFailure(
         return report;
     }
     if (isCredentialFailure(error)) {
-        const reason = describeChannelFailure(error, 'credential');
-        const report = serverChannelRouter.reportFailure(credential, { reason });
+        const reason = {
+            ...describeChannelFailure(error, 'credential'),
+            ...(requestMode ? { requestMode } : {})
+        };
+        const report = serverChannelRouter.reportFailure(credential, { requestMode, reason });
         appLogger.warn(
             report.cooldownApplied
                 ? `Temporarily cooling down API channel credential: ${credential.channelId}/${credential.id}`
@@ -1126,6 +1213,12 @@ function buildAgentImageExecution(
         image_backend: metadata.imageBackend,
         stream_mode: metadata.streamMode,
         streaming_strategy: metadata.streamingStrategy,
+        ...(metadata.channelRequestMode ? { channel_request_mode: metadata.channelRequestMode } : {}),
+        channel_request_mode_fallback_applied: metadata.channelRequestModeFallbackApplied,
+        route_decision: {
+            ...metadata.channelRequestModeDecision,
+            ...(upstreamHost ? { upstream_host: upstreamHost } : {})
+        },
         ...(metadata.selectedCredential?.channelId
             ? { selected_channel_id: metadata.selectedCredential.channelId }
             : {}),

src/lib/agent-openapi.ts

@@ -19,6 +19,7 @@ import {
     readAgentPublicBaseUrl
 } from './agent-api-contracts';
 import { AGENT_ENDPOINTS } from './agent-api-paths.mjs';
+import { CHANNEL_REQUEST_MODES } from './channel-request-mode';
 import { MAX_PROMPT_LENGTH } from './image-request-utils';
 
 type AgentOpenApiSecurityRequirement = { BearerAuth: [] } | { AppPasswordHash: [] };
@@ -429,6 +430,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         'image_transport',
                         'upstream_profile',
                         'upstream_request_headers',
+                        'request_mode_controls',
                         'defaults',
                         'limits',
                         'model_limits',
@@ -468,9 +470,13 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                                     type: 'array',
                                     items: {
                                         type: 'object',
-                                        required: ['id', 'request_headers'],
+                                        required: ['id', 'request_modes', 'request_headers'],
                                         properties: {
                                             id: { type: 'string' },
+                                            request_modes: {
+                                                type: 'array',
+                                                items: { type: 'string', enum: CHANNEL_REQUEST_MODES }
+                                            },
                                             request_headers: { $ref: '#/components/schemas/UpstreamRequestHeaderSummary' }
                                         },
                                         additionalProperties: false
@@ -479,6 +485,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                             },
                             additionalProperties: false
                         },
+                        request_mode_controls: { $ref: '#/components/schemas/AgentRequestModeControls' },
                         upstream_profile: {
                             type: 'object',
                             required: [
@@ -666,6 +673,7 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                                 'image_backends',
                                 'enabled_image_backends',
                                 'image_backend_requirements',
+                                'request_modes',
                                 'streaming_strategies',
                                 'stream_modes'
                             ],
@@ -695,6 +703,10 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                                     type: 'object',
                                     additionalProperties: { $ref: '#/components/schemas/ImageBackendRequirement' }
                                 },
+                                request_modes: {
+                                    type: 'array',
+                                    items: { type: 'string', enum: CHANNEL_REQUEST_MODES }
+                                },
                                 streaming_strategies: {
                                     type: 'array',
                                     items: { type: 'string', enum: AGENT_STREAMING_STRATEGIES }
@@ -1404,6 +1416,21 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                     },
                     additionalProperties: false
                 },
+                ChannelRequestModeDecision: {
+                    type: 'object',
+                    required: ['requested_backend', 'fallback_applied'],
+                    properties: {
+                        requested_backend: { type: 'string', enum: AGENT_IMAGE_BACKENDS },
+                        preferred_channel_request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES },
+                        fallback_channel_request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES },
+                        selected_channel_request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES },
+                        fallback_applied: { type: 'boolean' },
+                        selected_channel_id: { type: 'string' },
+                        upstream_host: { type: 'string' },
+                        no_channel_reason: { type: 'string' }
+                    },
+                    additionalProperties: false
+                },
                 AgentImageResponseExecution: {
                     type: 'object',
                     required: [
@@ -1414,6 +1441,8 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         'image_backend',
                         'stream_mode',
                         'streaming_strategy',
+                        'channel_request_mode_fallback_applied',
+                        'route_decision',
                         'request_headers'
                     ],
                     properties: {
@@ -1424,6 +1453,9 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                         image_backend: { type: 'string', enum: AGENT_IMAGE_BACKENDS },
                         stream_mode: { type: 'string', enum: AGENT_STREAM_MODES },
                         streaming_strategy: { type: 'string', enum: AGENT_STREAMING_STRATEGIES },
+                        channel_request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES },
+                        channel_request_mode_fallback_applied: { type: 'boolean' },
+                        route_decision: { $ref: '#/components/schemas/ChannelRequestModeDecision' },
                         selected_channel_id: { type: 'string' },
                         upstream_host: { type: 'string' },
                         request_headers: { $ref: '#/components/schemas/UpstreamRequestHeaderSummary' }
@@ -1784,6 +1816,9 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                     type: 'object',
                     properties: {
                         elapsed_ms: { type: 'integer', minimum: 0 },
+                        channel_request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES },
+                        channel_request_mode_fallback_applied: { type: 'boolean' },
+                        route_decision: { $ref: '#/components/schemas/ChannelRequestModeDecision' },
                         selected_channel_id: { type: 'string' },
                         upstream_host: { type: 'string' },
                         upstream_status: { type: 'integer' },
@@ -1812,7 +1847,8 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                             required: ['channel_id'],
                             properties: {
                                 channel_id: { type: 'string' },
-                                credential_id: { type: 'string' }
+                                credential_id: { type: 'string' },
+                                request_mode: { type: 'string', enum: CHANNEL_REQUEST_MODES }
                             },
                             additionalProperties: false
                         },
@@ -1846,6 +1882,34 @@ export function buildAgentOpenApiDocument(env: Record<string, string | undefined
                     },
                     additionalProperties: false
                 },
+                AgentRequestModeControls: {
+                    type: 'object',
+                    required: [
+                        'source',
+                        'global_env',
+                        'channel_env_pattern',
+                        'mutable_at_runtime',
+                        'agent_client_policy',
+                        'final_gate_command',
+                        'smoke_gate_commands'
+                    ],
+                    properties: {
+                        source: { type: 'string', const: 'admin_env_whitelist' },
+                        global_env: { type: 'string' },
+                        channel_env_pattern: { type: 'string' },
+                        mutable_at_runtime: { type: 'boolean', const: false },
+                        agent_client_policy: { type: 'string', const: 'diagnostics_only' },
+                        final_gate_command: { type: 'string' },
+                        smoke_gate_commands: {
+                            type: 'object',
+                            additionalProperties: {
+                                type: 'array',
+                                items: { type: 'string' }
+                            }
+                        }
+                    },
+                    additionalProperties: false
+                },
                 ImageTransportCapabilities: {
                     type: 'object',
                     required: [

src/lib/api-error-response.test.ts

@@ -1,5 +1,6 @@
 import {
     AgentApiError,
+    type AgentErrorDiagnostics,
     agentErrorResponse,
     createAgentErrorBody,
     normalizeAgentError,
@@ -96,6 +97,12 @@ describe('normalizeAgentError', () => {
     });
 
     it('adds sanitized upstream diagnostics without inventing an HTTP status', () => {
+        const unsafeCooldownTarget = {
+            channel_id: ' channel-a ',
+            credential_id: ' credential-a ',
+            request_mode: 'images-non-stream',
+            api_key: 'secret'
+        } as unknown as NonNullable<AgentErrorDiagnostics['cooldown_target']>;
         const error = normalizeAgentError(
             Object.assign(new Error('Connection error.'), {
                 name: 'APIConnectionError',
@@ -110,9 +117,7 @@ describe('normalizeAgentError', () => {
                 upstream_host: 'api.example.test',
                 retry_after_ms: 15000,
                 cooldown_until: '2026-06-11T00:00:15.000Z',
-                cooldown_target: {
-                    channel_id: 'channel-a'
-                }
+                cooldown_target: unsafeCooldownTarget
             }
         );
         const body = createAgentErrorBody(error, 'request-2');
@@ -124,11 +129,54 @@ describe('normalizeAgentError', () => {
         assert.equal(body.error.diagnostics?.transport_error, true);
         assert.equal(body.error.diagnostics?.retry_after_ms, 15000);
         assert.equal(body.error.diagnostics?.cooldown_until, '2026-06-11T00:00:15.000Z');
-        assert.deepEqual(body.error.diagnostics?.cooldown_target, { channel_id: 'channel-a' });
+        assert.deepEqual(body.error.diagnostics?.cooldown_target, {
+            channel_id: 'channel-a',
+            credential_id: 'credential-a',
+            request_mode: 'images-non-stream'
+        });
         assert.deepEqual(body.error.diagnostics?.response_headers, { 'cf-ray': 'abc-SJC' });
         assert.equal(JSON.stringify(body).includes('secret'), false);
     });
 
+    it('drops invalid cooldown target diagnostics', () => {
+        const error = normalizeAgentError(new Error('diagnostics'), {
+            retry_after_ms: 15000,
+            cooldown_target: {
+                channel_id: 'channel-a',
+                request_mode: 'invalid-mode'
+            } as unknown as NonNullable<AgentErrorDiagnostics['cooldown_target']>
+        });
+        const body = createAgentErrorBody(error, 'request-invalid-cooldown-target');
+
+        assert.equal(body.error.diagnostics?.retry_after_ms, 15000);
+        assert.deepEqual(body.error.diagnostics?.cooldown_target, { channel_id: 'channel-a' });
+    });
+
+    it('drops cooldown targets without a valid channel id', () => {
+        const error = normalizeAgentError(new Error('diagnostics'), {
+            retry_after_ms: 15000,
+            cooldown_target: {
+                channel_id: ' ',
+                request_mode: 'images-non-stream'
+            } as unknown as NonNullable<AgentErrorDiagnostics['cooldown_target']>
+        });
+        const body = createAgentErrorBody(error, 'request-blank-cooldown-target');
+
+        assert.equal(body.error.diagnostics?.retry_after_ms, 15000);
+        assert.equal(body.error.diagnostics?.cooldown_target, undefined);
+    });
+
+    it('drops cooldown target diagnostics that are not objects', () => {
+        const error = normalizeAgentError(new Error('diagnostics'), {
+            retry_after_ms: 15000,
+            cooldown_target: 'channel-a' as unknown as NonNullable<AgentErrorDiagnostics['cooldown_target']>
+        });
+        const body = createAgentErrorBody(error, 'request-string-cooldown-target');
+
+        assert.equal(body.error.diagnostics?.retry_after_ms, 15000);
+        assert.equal(body.error.diagnostics?.cooldown_target, undefined);
+    });
+
     it('filters caller-provided diagnostic response headers through the allowlist', () => {
         const error = normalizeAgentError(new Error('diagnostics'), {
             response_headers: {

src/lib/api-error-response.ts

@@ -1,6 +1,11 @@
 import { RequestValidationError } from './image-request-utils';
 import { isChannelFailure } from './channel-router';
 import { ChannelCapacityQueueError } from './channel-capacity-queue';
+import {
+    CHANNEL_REQUEST_MODES,
+    type ChannelRequestMode,
+    type ChannelRequestModeDecision
+} from './channel-request-mode';
 import { NextResponse } from 'next/server';
 
 export type AgentErrorCode =
@@ -20,6 +25,9 @@ export type AgentErrorCode =
 
 export type AgentErrorDiagnostics = {
     elapsed_ms?: number;
+    channel_request_mode?: ChannelRequestMode;
+    channel_request_mode_fallback_applied?: boolean;
+    route_decision?: ChannelRequestModeDecision;
     selected_channel_id?: string;
     upstream_host?: string;
     upstream_status?: number;
@@ -33,6 +41,7 @@ export type AgentErrorDiagnostics = {
     cooldown_target?: {
         channel_id: string;
         credential_id?: string;
+        request_mode?: ChannelRequestMode;
     };
     channel_cooldown_scope?: 'credential' | 'channel';
     response_headers?: Record<string, string>;
@@ -159,8 +168,14 @@ function cleanDiagnostics(diagnostics: AgentErrorDiagnostics | undefined): Agent
         diagnostics.retry_after_ms !== undefined
             ? normalizeNonNegativeInteger(diagnostics.retry_after_ms)
             : undefined;
+    const cooldownTarget = cleanCooldownTarget(diagnostics.cooldown_target);
     const cleaned: AgentErrorDiagnostics = {
         ...(diagnostics.elapsed_ms !== undefined ? { elapsed_ms: Math.max(0, Math.round(diagnostics.elapsed_ms)) } : {}),
+        ...(diagnostics.channel_request_mode ? { channel_request_mode: diagnostics.channel_request_mode } : {}),
+        ...(diagnostics.channel_request_mode_fallback_applied !== undefined
+            ? { channel_request_mode_fallback_applied: diagnostics.channel_request_mode_fallback_applied }
+            : {}),
+        ...(diagnostics.route_decision ? { route_decision: diagnostics.route_decision } : {}),
         ...(diagnostics.selected_channel_id ? { selected_channel_id: diagnostics.selected_channel_id } : {}),
         ...(diagnostics.upstream_host ? { upstream_host: diagnostics.upstream_host } : {}),
         ...(diagnostics.upstream_status !== undefined ? { upstream_status: diagnostics.upstream_status } : {}),
@@ -171,13 +186,36 @@ function cleanDiagnostics(diagnostics: AgentErrorDiagnostics | undefined): Agent
         ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
         ...(retryAfterMs !== undefined ? { retry_after_ms: retryAfterMs } : {}),
         ...(diagnostics.cooldown_until ? { cooldown_until: diagnostics.cooldown_until } : {}),
-        ...(diagnostics.cooldown_target ? { cooldown_target: diagnostics.cooldown_target } : {}),
+        ...(cooldownTarget ? { cooldown_target: cooldownTarget } : {}),
         ...(diagnostics.channel_cooldown_scope ? { channel_cooldown_scope: diagnostics.channel_cooldown_scope } : {}),
         ...(responseHeaders ? { response_headers: responseHeaders } : {})
     };
     return Object.keys(cleaned).length > 0 ? cleaned : undefined;
 }
 
+function cleanCooldownTarget(target: unknown): AgentErrorDiagnostics['cooldown_target'] | undefined {
+    if (typeof target !== 'object' || target === null) return undefined;
+    const source = target as Record<string, unknown>;
+    const channelId = normalizeNonEmptyString(source.channel_id);
+    if (!channelId) return undefined;
+    const credentialId = normalizeNonEmptyString(source.credential_id);
+    const requestMode = normalizeDiagnosticRequestMode(source.request_mode);
+    return {
+        channel_id: channelId,
+        ...(credentialId ? { credential_id: credentialId } : {}),
+        ...(requestMode ? { request_mode: requestMode } : {})
+    };
+}
+
+function normalizeDiagnosticRequestMode(value: unknown): ChannelRequestMode | undefined {
+    if (typeof value !== 'string') return undefined;
+    return CHANNEL_REQUEST_MODES.includes(value as ChannelRequestMode) ? (value as ChannelRequestMode) : undefined;
+}
+
+function normalizeNonEmptyString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
 function readNumberField(error: unknown, field: string): number | undefined {
     if (typeof error !== 'object' || error === null || !(field in error)) return undefined;
     const value = (error as Record<string, unknown>)[field];

src/lib/channel-health-prober.ts

@@ -36,6 +36,7 @@ export type ChannelHealthProbeRecord = {
     scope: 'credential' | 'channel';
     channelId: string;
     credentialId: string;
+    requestMode?: ChannelRecoveryProbeCandidate['requestMode'];
     ok: boolean;
     status?: number;
     code?: string;
@@ -186,7 +187,7 @@ export function createChannelHealthProber(options: ChannelHealthProberOptions):
 }
 
 function toCandidateKey(candidate: ChannelRecoveryProbeCandidate): string {
-    return `${candidate.scope}:${candidate.credential.id}:${candidate.unhealthyUntil}`;
+    return `${candidate.scope}:${candidate.credential.id}:${candidate.requestMode ?? ''}:${candidate.unhealthyUntil}`;
 }
 
 function toFailureCandidate(
@@ -234,6 +235,7 @@ function toProbeRecord(candidate: ChannelRecoveryProbeCandidate, result: ProbeRe
         scope: candidate.scope,
         channelId: candidate.credential.channelId,
         credentialId: candidate.credential.id,
+        ...(candidate.requestMode ? { requestMode: candidate.requestMode } : {}),
         ok: result.ok,
         ...(result.status === undefined ? {} : { status: result.status }),
         ...(result.code === undefined ? {} : { code: result.code })
@@ -248,6 +250,7 @@ function toFailureReason(
     return {
         at,
         scope: candidate.scope,
+        ...(candidate.requestMode ? { requestMode: candidate.requestMode } : {}),
         ...(result.status === undefined ? {} : { status: result.status }),
         ...(result.code === undefined ? {} : { code: result.code })
     };

src/lib/channel-request-mode-values.mjs

@@ -0,0 +1,36 @@
+export const CHANNEL_REQUEST_MODES = Object.freeze([
+    'images-non-stream',
+    'images-sse',
+    'responses-non-stream',
+    'responses-sse'
+]);
+
+export const CHANNEL_REQUEST_MODE_SMOKE_CASES = Object.freeze({
+    'images-non-stream': Object.freeze(['generate_1k', 'edit_1k']),
+    'images-sse': Object.freeze(['page_sse_edit_2k']),
+    'responses-non-stream': Object.freeze(['responses_agent_generate_1k']),
+    'responses-sse': Object.freeze(['responses_page_sse_generate_1k'])
+});
+
+export const CHANNEL_REQUEST_MODE_ADMIN_CONTROL = Object.freeze({
+    source: 'admin_env_whitelist',
+    globalEnv: 'OPENAI_UPSTREAM_REQUEST_MODES',
+    channelEnvPattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+    mutableAtRuntime: false,
+    finalGateCommand:
+        'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --require-independent-targets --allow-billable',
+    smokeGateCommands: Object.freeze({
+        'images-non-stream': Object.freeze([
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case original-images-json --allow-billable'
+        ]),
+        'images-sse': Object.freeze([
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-images-sse --allow-billable'
+        ]),
+        'responses-non-stream': Object.freeze([
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case sub2api-responses-json --allow-billable'
+        ]),
+        'responses-sse': Object.freeze([
+            'npm run smoke:image-upstream-real -- --env-file-if-exists .env.real-smoke.local --case gpt2image-responses-sse --allow-billable'
+        ])
+    })
+});

src/lib/channel-request-mode.ts

@@ -0,0 +1,130 @@
+import { RequestValidationError } from './image-request-utils';
+import {
+    CHANNEL_REQUEST_MODES as SHARED_CHANNEL_REQUEST_MODES,
+    CHANNEL_REQUEST_MODE_ADMIN_CONTROL as SHARED_CHANNEL_REQUEST_MODE_ADMIN_CONTROL
+} from './channel-request-mode-values.mjs';
+
+export const CHANNEL_REQUEST_MODES = SHARED_CHANNEL_REQUEST_MODES as readonly [
+    'images-non-stream',
+    'images-sse',
+    'responses-non-stream',
+    'responses-sse'
+];
+
+export type ChannelRequestMode = (typeof CHANNEL_REQUEST_MODES)[number];
+
+export type ChannelRequestModeBackend = 'images-api' | 'responses-image-generation';
+
+export type ChannelRequestModeDecision = {
+    requested_backend: ChannelRequestModeBackend;
+    preferred_channel_request_mode?: ChannelRequestMode;
+    fallback_channel_request_mode?: ChannelRequestMode;
+    selected_channel_request_mode?: ChannelRequestMode;
+    fallback_applied: boolean;
+    selected_channel_id?: string;
+    upstream_host?: string;
+    no_channel_reason?: string;
+};
+
+export type ChannelRequestModeHealthSummary = {
+    configuredRequestModes: readonly ChannelRequestMode[];
+    effectiveRequestModes: readonly ChannelRequestMode[];
+    modes: Array<{
+        mode: ChannelRequestMode;
+        configuredCredentialCount: number;
+        healthyCredentialCount: number;
+        configuredChannelCount: number;
+        healthyChannelCount: number;
+    }>;
+    effectiveRequestModesByChannel: Array<{
+        channelId: string;
+        requestModes: readonly ChannelRequestMode[];
+    }>;
+};
+
+export const DEFAULT_CHANNEL_REQUEST_MODES: readonly ChannelRequestMode[] = CHANNEL_REQUEST_MODES;
+export const CHANNEL_REQUEST_MODE_ADMIN_CONTROL = SHARED_CHANNEL_REQUEST_MODE_ADMIN_CONTROL as {
+    readonly source: 'admin_env_whitelist';
+    readonly globalEnv: 'OPENAI_UPSTREAM_REQUEST_MODES';
+    readonly channelEnvPattern: 'OPENAI_CHANNEL_N_REQUEST_MODES';
+    readonly mutableAtRuntime: false;
+    readonly finalGateCommand: string;
+    readonly smokeGateCommands: Record<ChannelRequestMode, readonly string[]>;
+};
+
+const CHANNEL_REQUEST_MODE_SET = new Set<string>(CHANNEL_REQUEST_MODES);
+const CHANNEL_REQUEST_MODE_ALIASES: Record<string, ChannelRequestMode> = {
+    'images-api': 'images-non-stream',
+    'images-api-non-stream': 'images-non-stream',
+    'images-api-json': 'images-non-stream',
+    'images-json': 'images-non-stream',
+    'images-nonstream': 'images-non-stream',
+    'images-api-sse': 'images-sse',
+    'images-stream': 'images-sse',
+    'images-api-stream': 'images-sse',
+    responses: 'responses-non-stream',
+    'responses-json': 'responses-non-stream',
+    'responses-nonstream': 'responses-non-stream',
+    'responses-image-generation': 'responses-non-stream',
+    'responses-image-generation-non-stream': 'responses-non-stream',
+    'responses-image-generation-sse': 'responses-sse',
+    'responses-stream': 'responses-sse'
+};
+
+export function parseChannelRequestModes(
+    value: string | undefined,
+    fieldName: string
+): ChannelRequestMode[] | undefined {
+    if (!value?.trim()) return undefined;
+    const modes: ChannelRequestMode[] = [];
+    for (const rawPart of value.split(/[,\s]+/)) {
+        const normalized = normalizeChannelRequestMode(rawPart);
+        if (!normalized) continue;
+        if (!modes.includes(normalized)) {
+            modes.push(normalized);
+        }
+    }
+    if (modes.length === 0) {
+        throw new RequestValidationError(`${fieldName} 至少需要包含一个请求方式。`, 500);
+    }
+    return modes;
+}
+
+export function getEffectiveChannelRequestModes(input: {
+    requestModes?: readonly ChannelRequestMode[];
+}): readonly ChannelRequestMode[] {
+    return input.requestModes?.length ? input.requestModes : DEFAULT_CHANNEL_REQUEST_MODES;
+}
+
+export function channelSupportsRequestMode(
+    input: { requestModes?: readonly ChannelRequestMode[] },
+    mode: ChannelRequestMode
+): boolean {
+    return getEffectiveChannelRequestModes(input).includes(mode);
+}
+
+export function resolveChannelRequestMode(input: {
+    imageBackend: ChannelRequestModeBackend;
+    streamEnabled: boolean;
+}): ChannelRequestMode {
+    if (input.imageBackend === 'responses-image-generation') {
+        return input.streamEnabled ? 'responses-sse' : 'responses-non-stream';
+    }
+    return input.streamEnabled ? 'images-sse' : 'images-non-stream';
+}
+
+export function isStreamingChannelRequestMode(mode: ChannelRequestMode): boolean {
+    return mode.endsWith('-sse');
+}
+
+function normalizeChannelRequestMode(value: string): ChannelRequestMode | undefined {
+    const normalized = value.trim().toLowerCase().replace(/_/g, '-');
+    if (!normalized) return undefined;
+    if (CHANNEL_REQUEST_MODE_SET.has(normalized)) return normalized as ChannelRequestMode;
+    const aliased = CHANNEL_REQUEST_MODE_ALIASES[normalized];
+    if (aliased) return aliased;
+    throw new RequestValidationError(
+        `请求方式 ${value} 无效，必须是 ${CHANNEL_REQUEST_MODES.join(', ')} 之一。`,
+        500
+    );
+}

src/lib/channel-router.test.ts

@@ -9,6 +9,7 @@ import {
     toPublicChannelFailure
 } from './channel-router';
 import { ChannelCapacityQueueError } from './channel-capacity-queue';
+import { CHANNEL_REQUEST_MODES } from './channel-request-mode';
 import { IMAGE_UPSTREAM_PROFILES } from './image-upstream-profile';
 import { RequestValidationError } from './image-request-utils';
 import assert from 'node:assert/strict';
@@ -154,6 +155,30 @@ describe('parseChannelPoolConfig', () => {
             /OPENAI_CHANNEL_N/
         );
     });
+
+    it('parses explicit per-channel request modes', () => {
+        const config = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'images-only',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://images.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'sk-one',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-json, images-sse'
+        });
+
+        assert.deepEqual(config.credentials[0]?.requestModes, ['images-non-stream', 'images-sse']);
+    });
+
+    it('rejects invalid per-channel request modes', () => {
+        assert.throws(
+            () =>
+                parseChannelPoolConfig({
+                    OPENAI_CHANNEL_1_ID: 'bad',
+                    OPENAI_CHANNEL_1_BASE_URL: 'https://bad.example.com/v1',
+                    OPENAI_CHANNEL_1_API_KEYS: 'sk-one',
+                    OPENAI_CHANNEL_1_REQUEST_MODES: 'responses-websocket'
+                }),
+            /请求方式/
+        );
+    });
 });
 
 describe('getChannelPoolSummary', () => {
@@ -180,6 +205,7 @@ describe('getChannelPoolSummary', () => {
                     effectiveProfile: IMAGE_UPSTREAM_PROFILES['openai-compatible'],
                     hasExtraHeaders: false,
                     requestHeaders: DEFAULT_HEADER_SUMMARY,
+                    requestModes: CHANNEL_REQUEST_MODES,
                     credentialCount: 2
                 },
                 {
@@ -189,6 +215,7 @@ describe('getChannelPoolSummary', () => {
                     effectiveProfile: IMAGE_UPSTREAM_PROFILES['openai-compatible'],
                     hasExtraHeaders: false,
                     requestHeaders: DEFAULT_HEADER_SUMMARY,
+                    requestModes: CHANNEL_REQUEST_MODES,
                     credentialCount: 1
                 }
             ]
@@ -221,6 +248,7 @@ describe('getChannelPoolSummary', () => {
                         has_extra_headers: true,
                         configured_header_names: ['x-app-id', 'x-app-secret']
                     },
+                    requestModes: CHANNEL_REQUEST_MODES,
                     credentialCount: 1
                 }
             ]
@@ -328,6 +356,7 @@ describe('getChannelPoolSummary', () => {
                     effectiveProfile: config.credentials[0]?.providerProfile,
                     hasExtraHeaders: false,
                     requestHeaders: DEFAULT_HEADER_SUMMARY,
+                    requestModes: CHANNEL_REQUEST_MODES,
                     providerManifest: {
                         id: 'custom_provider',
                         name: 'Custom Provider',
@@ -414,6 +443,25 @@ describe('createChannelRouter', () => {
         assert.equal(router.select().id, 'b#0');
     });
 
+    it('selects only channels that support the requested mode', () => {
+        const modeConfig = parseChannelPoolConfig({
+            OPENAI_ROUTING_STRATEGY: 'round_robin',
+            OPENAI_CHANNEL_1_ID: 'images',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://images.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'sk-images',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream',
+            OPENAI_CHANNEL_2_ID: 'responses',
+            OPENAI_CHANNEL_2_BASE_URL: 'https://responses.example.com/v1',
+            OPENAI_CHANNEL_2_API_KEYS: 'sk-responses',
+            OPENAI_CHANNEL_2_REQUEST_MODES: 'responses-sse'
+        });
+        const router = createChannelRouter(modeConfig);
+
+        assert.equal(router.select({ requestMode: 'responses-sse' }).channelId, 'responses');
+        assert.equal(router.select({ requestMode: 'images-non-stream' }).channelId, 'images');
+        assert.throws(() => router.select({ requestMode: 'images-sse' }), /支持 images-sse/);
+    });
+
     it('skips a failed credential until the cooldown expires', () => {
         let now = 1000;
         const router = createChannelRouter({
@@ -602,6 +650,221 @@ describe('createChannelRouter', () => {
         });
     });
 
+    it('reports configured and effective request modes separately', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'images',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://images.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'images-key',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse',
+            OPENAI_CHANNEL_2_ID: 'responses',
+            OPENAI_CHANNEL_2_BASE_URL: 'https://responses.example.com/v1',
+            OPENAI_CHANNEL_2_API_KEYS: 'responses-key',
+            OPENAI_CHANNEL_2_REQUEST_MODES: 'responses-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now
+        });
+
+        assert.deepEqual(router.getRequestModeHealthSummary(), {
+            configuredRequestModes: ['images-non-stream', 'images-sse', 'responses-sse'],
+            effectiveRequestModes: ['images-non-stream', 'images-sse', 'responses-sse'],
+            modes: [
+                {
+                    mode: 'images-non-stream',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'images-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'responses-non-stream',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                },
+                {
+                    mode: 'responses-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                }
+            ],
+            effectiveRequestModesByChannel: [
+                {
+                    channelId: 'images',
+                    requestModes: ['images-non-stream', 'images-sse']
+                },
+                {
+                    channelId: 'responses',
+                    requestModes: ['responses-sse']
+                }
+            ]
+        });
+
+        router.reportFailure(requestModeConfig.credentials[1], { scope: 'channel' });
+        assert.deepEqual(router.getRequestModeHealthSummary(), {
+            configuredRequestModes: ['images-non-stream', 'images-sse', 'responses-sse'],
+            effectiveRequestModes: ['images-non-stream', 'images-sse'],
+            modes: [
+                {
+                    mode: 'images-non-stream',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'images-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'responses-non-stream',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                },
+                {
+                    mode: 'responses-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 0
+                }
+            ],
+            effectiveRequestModesByChannel: [
+                {
+                    channelId: 'images',
+                    requestModes: ['images-non-stream', 'images-sse']
+                }
+            ]
+        });
+
+        now = 1100;
+        assert.deepEqual(router.getRequestModeHealthSummary().effectiveRequestModes, [
+            'images-non-stream',
+            'images-sse',
+            'responses-sse'
+        ]);
+    });
+
+    it('cools only the failed request mode when failure reports include a request mode', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-key',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now
+        });
+        const credential = requestModeConfig.credentials[0];
+
+        const report = router.reportFailure(credential, {
+            scope: 'channel',
+            requestMode: 'images-sse',
+            reason: {
+                at: now,
+                scope: 'channel',
+                status: 524
+            }
+        });
+
+        assert.deepEqual(report.target, {
+            channelId: 'mixed',
+            requestMode: 'images-sse'
+        });
+        assert.deepEqual(report.reason, {
+            at: 1000,
+            scope: 'channel',
+            status: 524,
+            requestMode: 'images-sse'
+        });
+        assert.throws(() => router.select({ requestMode: 'images-sse' }), /支持 images-sse/);
+        assert.equal(router.select({ requestMode: 'images-non-stream' }).id, credential.id);
+        assert.deepEqual(router.getHealthSummary(), {
+            credentialCount: 1,
+            healthyCredentialCount: 1,
+            unhealthyCredentialCount: 0,
+            channelCount: 1,
+            healthyChannelCount: 1,
+            unhealthyChannelCount: 0,
+            pendingRecoveryProbeCredentialCount: 0,
+            pendingRecoveryProbeChannelCount: 0,
+            lastFailure: {
+                at: 1000,
+                scope: 'channel',
+                status: 524,
+                requestMode: 'images-sse'
+            }
+        });
+        assert.deepEqual(router.getRequestModeHealthSummary(), {
+            configuredRequestModes: ['images-non-stream', 'images-sse'],
+            effectiveRequestModes: ['images-non-stream'],
+            modes: [
+                {
+                    mode: 'images-non-stream',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 1,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 1
+                },
+                {
+                    mode: 'images-sse',
+                    configuredCredentialCount: 1,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 1,
+                    healthyChannelCount: 0
+                },
+                {
+                    mode: 'responses-non-stream',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                },
+                {
+                    mode: 'responses-sse',
+                    configuredCredentialCount: 0,
+                    healthyCredentialCount: 0,
+                    configuredChannelCount: 0,
+                    healthyChannelCount: 0
+                }
+            ],
+            effectiveRequestModesByChannel: [
+                {
+                    channelId: 'mixed',
+                    requestModes: ['images-non-stream']
+                }
+            ]
+        });
+
+        now = 1100;
+        assert.equal(router.select({ requestMode: 'images-sse' }).id, credential.id);
+        assert.deepEqual(router.getRequestModeHealthSummary().effectiveRequestModes, [
+            'images-non-stream',
+            'images-sse'
+        ]);
+    });
+
     it('uses per-channel cooldown when a channel defines a longer window', () => {
         let now = 1000;
         const channelConfig = parseChannelPoolConfig({
@@ -830,6 +1093,177 @@ describe('createChannelRouter', () => {
         });
     });
 
+    it('requires recovery probes for request-mode cooldowns', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-key',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now,
+            requireProbeForRecovery: true
+        });
+        const failed = requestModeConfig.credentials[0];
+
+        router.reportFailure(failed, { scope: 'channel', requestMode: 'images-sse' });
+
+        now = 1100;
+        assert.equal(router.select({ requestMode: 'images-non-stream' }).id, failed.id);
+        assert.throws(() => router.select({ requestMode: 'images-sse' }), /支持 images-sse/);
+        assert.deepEqual(
+            router.getRecoveryProbeCandidates().map((candidate) => ({
+                scope: candidate.scope,
+                credentialId: candidate.credential.id,
+                requestMode: candidate.requestMode
+            })),
+            [{ scope: 'channel', credentialId: 'mixed#0', requestMode: 'images-sse' }]
+        );
+        assert.deepEqual(router.getHealthSummary(), {
+            credentialCount: 1,
+            healthyCredentialCount: 1,
+            unhealthyCredentialCount: 0,
+            channelCount: 1,
+            healthyChannelCount: 1,
+            unhealthyChannelCount: 0,
+            pendingRecoveryProbeCredentialCount: 0,
+            pendingRecoveryProbeChannelCount: 1,
+            lastFailure: {
+                at: 1000,
+                scope: 'channel',
+                requestMode: 'images-sse'
+            }
+        });
+
+        const candidate = router.getRecoveryProbeCandidates()[0];
+        assert.equal(router.reportRecoveryProbeSuccess(candidate), true);
+        assert.equal(router.select({ requestMode: 'images-sse' }).id, failed.id);
+    });
+
+    it('uses a request-mode-capable sibling credential for channel request-mode recovery probes', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-a,mixed-b',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now,
+            requireProbeForRecovery: true
+        });
+        const [first, second] = requestModeConfig.credentials;
+
+        router.reportFailure(first, { scope: 'channel', requestMode: 'images-sse' });
+        now = 1010;
+        router.reportFailure(first, { requestMode: 'images-sse' });
+
+        now = 1100;
+        assert.deepEqual(
+            router.getRecoveryProbeCandidates().map((candidate) => ({
+                scope: candidate.scope,
+                credentialId: candidate.credential.id,
+                requestMode: candidate.requestMode
+            })),
+            [{ scope: 'channel', credentialId: second.id, requestMode: 'images-sse' }]
+        );
+        assert.equal(router.reportRecoveryProbeSuccess(router.getRecoveryProbeCandidates()[0]), true);
+        assert.equal(router.getHealthSummary().pendingRecoveryProbeCredentialCount, 1);
+    });
+
+    it('queues the channel recovery probe before request-mode probes for the same channel', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-key',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now,
+            requireProbeForRecovery: true
+        });
+        const failed = requestModeConfig.credentials[0];
+
+        router.reportFailure(failed, { scope: 'channel' });
+        router.reportFailure(failed, { scope: 'channel', requestMode: 'images-sse' });
+
+        now = 1100;
+        assert.deepEqual(
+            router.getRecoveryProbeCandidates().map((candidate) => ({
+                scope: candidate.scope,
+                credentialId: candidate.credential.id,
+                requestMode: candidate.requestMode
+            })),
+            [{ scope: 'channel', credentialId: failed.id, requestMode: undefined }]
+        );
+    });
+
+    it('queues the credential recovery probe before request-mode probes for the same credential', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-key',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now,
+            requireProbeForRecovery: true
+        });
+        const failed = requestModeConfig.credentials[0];
+
+        router.reportFailure(failed);
+        router.reportFailure(failed, { requestMode: 'images-sse' });
+
+        now = 1100;
+        assert.deepEqual(
+            router.getRecoveryProbeCandidates().map((candidate) => ({
+                scope: candidate.scope,
+                credentialId: candidate.credential.id,
+                requestMode: candidate.requestMode
+            })),
+            [{ scope: 'credential', credentialId: failed.id, requestMode: undefined }]
+        );
+    });
+
+    it('clears older credential request-mode probes when a channel request-mode probe recovers', () => {
+        let now = 1000;
+        const requestModeConfig = parseChannelPoolConfig({
+            OPENAI_CHANNEL_1_ID: 'mixed',
+            OPENAI_CHANNEL_1_BASE_URL: 'https://mixed.example.com/v1',
+            OPENAI_CHANNEL_1_API_KEYS: 'mixed-a,mixed-b',
+            OPENAI_CHANNEL_1_REQUEST_MODES: 'images-non-stream,images-sse'
+        });
+        const router = createChannelRouter({
+            ...requestModeConfig,
+            failureCooldownMs: 100,
+            now: () => now,
+            requireProbeForRecovery: true
+        });
+        const [first, second] = requestModeConfig.credentials;
+
+        router.reportFailure(first, { requestMode: 'images-sse' });
+        router.reportFailure(second, { requestMode: 'images-sse' });
+        now = 1010;
+        router.reportFailure(first, { scope: 'channel', requestMode: 'images-sse' });
+
+        now = 1110;
+        const candidate = router.getRecoveryProbeCandidates()[0];
+        assert.equal(router.reportRecoveryProbeSuccess(candidate), true);
+        assert.equal(router.getHealthSummary().pendingRecoveryProbeCredentialCount, 0);
+        assert.equal(router.select({ requestMode: 'images-sse' }).channelId, 'mixed');
+    });
+
     it('ignores stale recovery probe success after the credential fails again', () => {
         let now = 1000;
         const router = createChannelRouter({

src/lib/channel-router.ts

@@ -17,6 +17,14 @@ import {
     type ImageProviderManifest,
     type ImageProviderManifestSummary
 } from './image-upstream-provider-manifest';
+import {
+    CHANNEL_REQUEST_MODES,
+    channelSupportsRequestMode,
+    getEffectiveChannelRequestModes,
+    parseChannelRequestModes,
+    type ChannelRequestMode,
+    type ChannelRequestModeHealthSummary
+} from './channel-request-mode';
 import { ChannelCapacityQueueError } from './channel-capacity-queue';
 import { RequestValidationError, readPlainHttpApiBaseUrlAllowlist, validateApiBaseUrl } from './image-request-utils';
 
@@ -32,6 +40,7 @@ export type ChannelCredential = {
     providerManifest?: ImageProviderManifestSummary;
     providerProfile?: ImageUpstreamProfile;
     failureCooldownMs?: number;
+    requestModes?: ChannelRequestMode[];
 };
 
 export type ChannelPoolConfig = {
@@ -51,21 +60,24 @@ export type ChannelPoolSummary = {
         hasExtraHeaders: boolean;
         requestHeaders: ReturnType<typeof summarizeUpstreamRequestHeaders>;
         providerManifest?: ImageProviderManifestSummary;
+        requestModes: readonly ChannelRequestMode[];
         credentialCount: number;
     }>;
 };
 
 export type ChannelRouter = {
-    select(options?: { affinityKey?: string }): ChannelCredential;
+    select(options?: { affinityKey?: string; requestMode?: ChannelRequestMode }): ChannelCredential;
     reportFailure(credential: ChannelCredential, options?: ChannelFailureReportOptions): ChannelFailureReport;
     getRecoveryProbeCandidates(): ChannelRecoveryProbeCandidate[];
     reportRecoveryProbeSuccess(candidate: ChannelRecoveryProbeCandidate): boolean;
     reportRecoveryProbeFailure(candidate: ChannelRecoveryProbeCandidate, reason?: ChannelFailureReason): void;
     getHealthSummary(): ChannelPoolHealthSummary;
+    getRequestModeHealthSummary(): ChannelRequestModeHealthSummary;
 };
 
 export type ChannelFailureReportOptions = {
     scope?: 'credential' | 'channel';
+    requestMode?: ChannelRequestMode;
     reason?: ChannelFailureReason;
 };
 
@@ -77,6 +89,7 @@ export type ChannelFailureReport = {
     target: {
         channelId: string;
         credentialId?: string;
+        requestMode?: ChannelRequestMode;
     };
     reason: ChannelFailureReason;
 };
@@ -87,6 +100,7 @@ export type ChannelFailureReason = {
     status?: number;
     code?: string;
     requestId?: string;
+    requestMode?: ChannelRequestMode;
     message?: string;
 };
 
@@ -108,6 +122,7 @@ export type ChannelRecoveryProbeCandidate = {
     scope: 'credential' | 'channel';
     credential: ChannelCredential;
     unhealthyUntil: number;
+    requestMode?: ChannelRequestMode;
 };
 
 export type EffectiveCredential = {
@@ -131,7 +146,7 @@ const DEFAULT_STRATEGY: RoutingStrategy = 'sticky';
 const DEFAULT_FAILURE_COOLDOWN_MS = 30_000;
 const VALID_STRATEGIES = new Set<RoutingStrategy>(['sticky', 'round_robin', 'random']);
 const CHANNEL_KEY_PATTERN =
-    /^OPENAI_CHANNEL_(\d+)_(ID|BASE_URL|API_KEYS|UPSTREAM_PROFILE|PROVIDER_MANIFEST|MATSCA_APP_ID|MATSCA_APP_SECRET|USER_AGENT|UPSTREAM_HEADERS_JSON|FAILURE_COOLDOWN_MS)$/;
+    /^OPENAI_CHANNEL_(\d+)_(ID|BASE_URL|API_KEYS|UPSTREAM_PROFILE|PROVIDER_MANIFEST|REQUEST_MODES|MATSCA_APP_ID|MATSCA_APP_SECRET|USER_AGENT|UPSTREAM_HEADERS_JSON|FAILURE_COOLDOWN_MS)$/;
 
 export function parseChannelPoolConfig(env: Record<string, string | undefined>): ChannelPoolConfig {
     if (env.OPENAI_CHANNELS_JSON?.trim()) {
@@ -168,22 +183,41 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
     const failureCooldownMs = Math.max(1, Math.floor(options.failureCooldownMs ?? DEFAULT_FAILURE_COOLDOWN_MS));
     const unhealthyUntilByCredentialId = new Map<string, number>();
     const unhealthyUntilByChannelId = new Map<string, number>();
+    const unhealthyUntilByCredentialRequestMode = new Map<string, number>();
+    const unhealthyUntilByChannelRequestMode = new Map<string, number>();
     const probeRequiredCredentialIds = new Set<string>();
     const probeRequiredChannelIds = new Set<string>();
+    const probeRequiredCredentialRequestModes = new Set<string>();
+    const probeRequiredChannelRequestModes = new Set<string>();
     const channelIds = Array.from(new Set(options.credentials.map((credential) => credential.channelId)));
     let lastFailure: ChannelFailureReason | undefined;
 
-    const isCoolingDown = (credential: ChannelCredential) => {
+    const isCoolingDown = (credential: ChannelCredential, requestMode?: ChannelRequestMode) => {
         const currentTime = now();
         return (
             (unhealthyUntilByCredentialId.get(credential.id) ?? 0) > currentTime ||
-            (unhealthyUntilByChannelId.get(credential.channelId) ?? 0) > currentTime
+            (unhealthyUntilByChannelId.get(credential.channelId) ?? 0) > currentTime ||
+            Boolean(
+                requestMode &&
+                    ((unhealthyUntilByCredentialRequestMode.get(credentialRequestModeKey(credential, requestMode)) ?? 0) >
+                        currentTime ||
+                        (unhealthyUntilByChannelRequestMode.get(channelRequestModeKey(credential, requestMode)) ?? 0) >
+                            currentTime)
+            )
         );
     };
 
-    const isWaitingForProbe = (credential: ChannelCredential) => {
+    const isWaitingForProbe = (credential: ChannelCredential, requestMode?: ChannelRequestMode) => {
         if (!options.requireProbeForRecovery) return false;
-        return probeRequiredCredentialIds.has(credential.id) || probeRequiredChannelIds.has(credential.channelId);
+        return (
+            probeRequiredCredentialIds.has(credential.id) ||
+            probeRequiredChannelIds.has(credential.channelId) ||
+            Boolean(
+                requestMode &&
+                    (probeRequiredCredentialRequestModes.has(credentialRequestModeKey(credential, requestMode)) ||
+                        probeRequiredChannelRequestModes.has(channelRequestModeKey(credential, requestMode)))
+            )
+        );
     };
 
     const isHealthy = (credential: ChannelCredential) => {
@@ -191,9 +225,16 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
     };
 
     const healthyCredentials = () => options.credentials.filter(isHealthy);
+    const supportsRequestedMode = (credential: ChannelCredential, mode: ChannelRequestMode | undefined) => {
+        return !mode || channelSupportsRequestMode(credential, mode);
+    };
+    const isHealthyForRequestMode = (credential: ChannelCredential, mode: ChannelRequestMode | undefined) => {
+        return supportsRequestedMode(credential, mode) && !isCoolingDown(credential, mode) && !isWaitingForProbe(credential, mode);
+    };
     const setCooldown = (
         credential: ChannelCredential,
-        scope: 'credential' | 'channel'
+        scope: 'credential' | 'channel',
+        requestMode?: ChannelRequestMode
     ): { cooldownApplied: boolean; cooldownUntil: number; retryAfterMs: number } => {
         if (!failureCooldownEnabled) {
             return { cooldownApplied: false, cooldownUntil: now(), retryAfterMs: 0 };
@@ -201,24 +242,66 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
         const cooldownMs = credential.failureCooldownMs ?? failureCooldownMs;
         const unhealthyUntil = now() + cooldownMs;
         if (scope === 'channel') {
+            if (requestMode) {
+                unhealthyUntilByChannelRequestMode.set(channelRequestModeKey(credential, requestMode), unhealthyUntil);
+                if (options.requireProbeForRecovery) {
+                    probeRequiredChannelRequestModes.add(channelRequestModeKey(credential, requestMode));
+                }
+                return { cooldownApplied: true, cooldownUntil: unhealthyUntil, retryAfterMs: cooldownMs };
+            }
             unhealthyUntilByChannelId.set(credential.channelId, unhealthyUntil);
             if (options.requireProbeForRecovery) probeRequiredChannelIds.add(credential.channelId);
             return { cooldownApplied: true, cooldownUntil: unhealthyUntil, retryAfterMs: cooldownMs };
         }
+        if (requestMode) {
+            unhealthyUntilByCredentialRequestMode.set(credentialRequestModeKey(credential, requestMode), unhealthyUntil);
+            if (options.requireProbeForRecovery) {
+                probeRequiredCredentialRequestModes.add(credentialRequestModeKey(credential, requestMode));
+            }
+            return { cooldownApplied: true, cooldownUntil: unhealthyUntil, retryAfterMs: cooldownMs };
+        }
         unhealthyUntilByCredentialId.set(credential.id, unhealthyUntil);
         if (options.requireProbeForRecovery) probeRequiredCredentialIds.add(credential.id);
         return { cooldownApplied: true, cooldownUntil: unhealthyUntil, retryAfterMs: cooldownMs };
     };
 
+    const clearCredentialRequestModeCooldownsForChannel = (
+        channelId: string,
+        requestMode: ChannelRequestMode,
+        unhealthyUntil: number
+    ) => {
+        for (const credential of options.credentials) {
+            if (credential.channelId !== channelId) continue;
+            const key = credentialRequestModeKey(credential, requestMode);
+            if ((unhealthyUntilByCredentialRequestMode.get(key) ?? 0) <= unhealthyUntil) {
+                unhealthyUntilByCredentialRequestMode.delete(key);
+                probeRequiredCredentialRequestModes.delete(key);
+            }
+        }
+    };
+
     return {
         select(selectOptions = {}) {
-            const candidates = healthyCredentials();
+            const requestMode = selectOptions.requestMode;
+            const candidates = options.credentials.filter((credential) =>
+                isHealthyForRequestMode(credential, requestMode)
+            );
             if (candidates.length === 0) {
-                throw new RequestValidationError('当前没有可用的健康渠道凭证。', 503);
+                throw new RequestValidationError(
+                    requestMode
+                        ? `当前没有支持 ${requestMode} 的健康渠道凭证。请调整请求策略或 OPENAI_CHANNEL_N_REQUEST_MODES。`
+                        : '当前没有可用的健康渠道凭证。',
+                    503
+                );
             }
 
             if (options.strategy === 'round_robin') {
-                const credential = selectRoundRobinHealthy(options.credentials, nextIndex, isHealthy);
+                const credential = selectRoundRobinHealthy(
+                    options.credentials,
+                    nextIndex,
+                    (candidate) => isHealthyForRequestMode(candidate, requestMode),
+                    requestMode
+                );
                 nextIndex = credential.nextIndex;
                 return credential.value;
             }
@@ -232,18 +315,27 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
             const startIndex = stableHash(affinityKey) % options.credentials.length;
             for (let offset = 0; offset < options.credentials.length; offset += 1) {
                 const credential = options.credentials[(startIndex + offset) % options.credentials.length];
-                if (isHealthy(credential)) {
+                if (isHealthyForRequestMode(credential, requestMode)) {
                     return credential;
                 }
             }
 
-            throw new RequestValidationError('当前没有可用的健康渠道凭证。', 503);
+            throw new RequestValidationError(
+                requestMode
+                    ? `当前没有支持 ${requestMode} 的健康渠道凭证。请调整请求策略或 OPENAI_CHANNEL_N_REQUEST_MODES。`
+                    : '当前没有可用的健康渠道凭证。',
+                503
+            );
         },
         reportFailure(credential: ChannelCredential, reportOptions = {}) {
             const currentTime = now();
             const scope = reportOptions.scope === 'channel' ? 'channel' : 'credential';
-            lastFailure = reportOptions.reason ?? { at: currentTime, scope };
-            const cooldown = setCooldown(credential, scope);
+            const requestMode = reportOptions.requestMode;
+            lastFailure = {
+                ...(reportOptions.reason ?? { at: currentTime, scope }),
+                ...(requestMode ? { requestMode } : {})
+            };
+            const cooldown = setCooldown(credential, scope, requestMode);
             return {
                 scope,
                 cooldownApplied: cooldown.cooldownApplied,
@@ -251,7 +343,8 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
                 retryAfterMs: cooldown.retryAfterMs,
                 target: {
                     channelId: credential.channelId,
-                    ...(scope === 'credential' ? { credentialId: credential.id } : {})
+                    ...(scope === 'credential' ? { credentialId: credential.id } : {}),
+                    ...(requestMode ? { requestMode } : {})
                 },
                 reason: lastFailure
             };
@@ -261,7 +354,9 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
             const currentTime = now();
             const candidates: ChannelRecoveryProbeCandidate[] = [];
             const queuedChannelIds = new Set<string>();
+            const queuedCredentialIds = new Set<string>();
             const dueChannelIds = new Set<string>();
+            const dueChannelRequestModeKeys = new Set<string>();
             for (const credential of options.credentials) {
                 const channelUnhealthyUntil = unhealthyUntilByChannelId.get(credential.channelId) ?? 0;
                 const credentialUnhealthyUntil = unhealthyUntilByCredentialId.get(credential.id) ?? 0;
@@ -287,6 +382,71 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
                 }
             }
 
+            for (const [key, channelUnhealthyUntil] of unhealthyUntilByChannelRequestMode.entries()) {
+                const parsed = readChannelRequestModeKey(key);
+                if (!parsed || channelUnhealthyUntil > currentTime) continue;
+                if (!probeRequiredChannelRequestModes.has(key)) continue;
+                dueChannelRequestModeKeys.add(key);
+                if (
+                    probeRequiredChannelIds.has(parsed.channelId) ||
+                    (unhealthyUntilByChannelId.get(parsed.channelId) ?? 0) > currentTime ||
+                    queuedChannelIds.has(parsed.channelId) ||
+                    queuedChannelIds.has(key)
+                ) {
+                    continue;
+                }
+                const credential = findChannelRequestModeProbeCredential(
+                    options.credentials,
+                    parsed.channelId,
+                    parsed.requestMode,
+                    unhealthyUntilByCredentialRequestMode,
+                    unhealthyUntilByCredentialId,
+                    probeRequiredCredentialIds,
+                    currentTime
+                );
+                if (!credential) continue;
+                candidates.push({
+                    scope: 'channel',
+                    credential,
+                    unhealthyUntil: channelUnhealthyUntil,
+                    requestMode: parsed.requestMode
+                });
+                queuedChannelIds.add(key);
+                queuedCredentialIds.add(credential.id);
+            }
+
+            for (const [key, credentialUnhealthyUntil] of unhealthyUntilByCredentialRequestMode.entries()) {
+                const parsed = readCredentialRequestModeKey(key);
+                if (!parsed || credentialUnhealthyUntil > currentTime) continue;
+                if (!probeRequiredCredentialRequestModes.has(key)) continue;
+                const channelKey = `${parsed.channelId}${REQUEST_MODE_KEY_SEPARATOR}${parsed.requestMode}`;
+                if (
+                    probeRequiredChannelIds.has(parsed.channelId) ||
+                    (unhealthyUntilByChannelId.get(parsed.channelId) ?? 0) > currentTime ||
+                    probeRequiredCredentialIds.has(parsed.credentialId) ||
+                    (unhealthyUntilByCredentialId.get(parsed.credentialId) ?? 0) > currentTime ||
+                    queuedChannelIds.has(parsed.channelId) ||
+                    queuedCredentialIds.has(parsed.credentialId)
+                ) {
+                    continue;
+                }
+                if (
+                    probeRequiredChannelRequestModes.has(channelKey) &&
+                    (!dueChannelRequestModeKeys.has(channelKey) || queuedChannelIds.has(channelKey))
+                ) {
+                    continue;
+                }
+                const credential = options.credentials.find((candidate) => candidate.id === parsed.credentialId);
+                if (!credential) continue;
+                candidates.push({
+                    scope: 'credential',
+                    credential,
+                    unhealthyUntil: credentialUnhealthyUntil,
+                    requestMode: parsed.requestMode
+                });
+                queuedCredentialIds.add(credential.id);
+            }
+
             for (const credential of options.credentials) {
                 const credentialUnhealthyUntil = unhealthyUntilByCredentialId.get(credential.id) ?? 0;
                 const credentialReady =
@@ -294,7 +454,7 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
                     credentialUnhealthyUntil <= currentTime &&
                     (!probeRequiredChannelIds.has(credential.channelId) ||
                         (dueChannelIds.has(credential.channelId) && !queuedChannelIds.has(credential.channelId)));
-                if (credentialReady) {
+                if (credentialReady && !queuedCredentialIds.has(credential.id)) {
                     candidates.push({
                         scope: 'credential',
                         credential,
@@ -305,6 +465,29 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
             return candidates;
         },
         reportRecoveryProbeSuccess(candidate: ChannelRecoveryProbeCandidate) {
+            if (candidate.requestMode) {
+                if (candidate.scope === 'channel') {
+                    const key = channelRequestModeKey(candidate.credential, candidate.requestMode);
+                    if ((unhealthyUntilByChannelRequestMode.get(key) ?? 0) !== candidate.unhealthyUntil) {
+                        return false;
+                    }
+                    unhealthyUntilByChannelRequestMode.delete(key);
+                    probeRequiredChannelRequestModes.delete(key);
+                    clearCredentialRequestModeCooldownsForChannel(
+                        candidate.credential.channelId,
+                        candidate.requestMode,
+                        candidate.unhealthyUntil
+                    );
+                    return true;
+                }
+                const key = credentialRequestModeKey(candidate.credential, candidate.requestMode);
+                if ((unhealthyUntilByCredentialRequestMode.get(key) ?? 0) !== candidate.unhealthyUntil) {
+                    return false;
+                }
+                unhealthyUntilByCredentialRequestMode.delete(key);
+                probeRequiredCredentialRequestModes.delete(key);
+                return true;
+            }
             if (candidate.scope === 'channel') {
                 if ((unhealthyUntilByChannelId.get(candidate.credential.channelId) ?? 0) !== candidate.unhealthyUntil) {
                     return false;
@@ -325,11 +508,14 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
             return true;
         },
         reportRecoveryProbeFailure(candidate: ChannelRecoveryProbeCandidate, reason) {
-            lastFailure = reason ?? {
-                at: now(),
-                scope: candidate.scope
+            lastFailure = {
+                ...(reason ?? {
+                    at: now(),
+                    scope: candidate.scope
+                }),
+                ...(candidate.requestMode ? { requestMode: candidate.requestMode } : {})
             };
-            setCooldown(candidate.credential, candidate.scope);
+            setCooldown(candidate.credential, candidate.scope, candidate.requestMode);
         },
         getHealthSummary() {
             const healthyCredentialCount = healthyCredentials().length;
@@ -343,18 +529,79 @@ export function createChannelRouter(options: ChannelRouterOptions): ChannelRoute
                 channelCount: channelIds.length,
                 healthyChannelCount,
                 unhealthyChannelCount: channelIds.length - healthyChannelCount,
-                pendingRecoveryProbeCredentialCount: probeRequiredCredentialIds.size,
-                pendingRecoveryProbeChannelCount: probeRequiredChannelIds.size,
+                pendingRecoveryProbeCredentialCount:
+                    probeRequiredCredentialIds.size + probeRequiredCredentialRequestModes.size,
+                pendingRecoveryProbeChannelCount:
+                    probeRequiredChannelIds.size + probeRequiredChannelRequestModes.size,
                 ...(lastFailure ? { lastFailure } : {})
             };
+        },
+        getRequestModeHealthSummary() {
+            return {
+                configuredRequestModes: summarizeCredentialRequestModes(options.credentials),
+                effectiveRequestModes: summarizeHealthyRequestModes(options.credentials, isHealthyForRequestMode),
+                modes: summarizeRequestModeCoverage(options.credentials, isHealthyForRequestMode),
+                effectiveRequestModesByChannel: summarizeHealthyRequestModesByChannel(options.credentials, isHealthyForRequestMode)
+            };
         }
     };
 }
 
+const REQUEST_MODE_KEY_SEPARATOR = '\u0000';
+
+function channelRequestModeKey(credential: ChannelCredential, requestMode: ChannelRequestMode): string {
+    return `${credential.channelId}${REQUEST_MODE_KEY_SEPARATOR}${requestMode}`;
+}
+
+function credentialRequestModeKey(credential: ChannelCredential, requestMode: ChannelRequestMode): string {
+    return `${credential.channelId}${REQUEST_MODE_KEY_SEPARATOR}${credential.id}${REQUEST_MODE_KEY_SEPARATOR}${requestMode}`;
+}
+
+function readChannelRequestModeKey(value: string): { channelId: string; requestMode: ChannelRequestMode } | undefined {
+    const [channelId, requestMode] = value.split(REQUEST_MODE_KEY_SEPARATOR);
+    if (!channelId || !isChannelRequestMode(requestMode)) return undefined;
+    return { channelId, requestMode };
+}
+
+function readCredentialRequestModeKey(value: string): {
+    channelId: string;
+    credentialId: string;
+    requestMode: ChannelRequestMode;
+} | undefined {
+    const [channelId, credentialId, requestMode] = value.split(REQUEST_MODE_KEY_SEPARATOR);
+    if (!channelId || !credentialId || !isChannelRequestMode(requestMode)) return undefined;
+    return { channelId, credentialId, requestMode };
+}
+
+function isChannelRequestMode(value: string | undefined): value is ChannelRequestMode {
+    return Boolean(value && (CHANNEL_REQUEST_MODES as readonly string[]).includes(value));
+}
+
+function findChannelRequestModeProbeCredential(
+    credentials: ChannelCredential[],
+    channelId: string,
+    requestMode: ChannelRequestMode,
+    unhealthyUntilByCredentialRequestMode: Map<string, number>,
+    unhealthyUntilByCredentialId: Map<string, number>,
+    probeRequiredCredentialIds: Set<string>,
+    currentTime: number
+): ChannelCredential | undefined {
+    return credentials.find(
+        (credential) =>
+            credential.channelId === channelId &&
+            channelSupportsRequestMode(credential, requestMode) &&
+            !probeRequiredCredentialIds.has(credential.id) &&
+            (unhealthyUntilByCredentialId.get(credential.id) ?? 0) <= currentTime &&
+            (unhealthyUntilByCredentialRequestMode.get(credentialRequestModeKey(credential, requestMode)) ?? 0) <=
+                currentTime
+    );
+}
+
 function selectRoundRobinHealthy(
     credentials: ChannelCredential[],
     startIndex: number,
-    isHealthy: (credential: ChannelCredential) => boolean
+    isHealthy: (credential: ChannelCredential) => boolean,
+    requestMode?: ChannelRequestMode
 ): { value: ChannelCredential; nextIndex: number } {
     for (let offset = 0; offset < credentials.length; offset += 1) {
         const index = (startIndex + offset) % credentials.length;
@@ -367,7 +614,12 @@ function selectRoundRobinHealthy(
         }
     }
 
-    throw new RequestValidationError('当前没有可用的健康渠道凭证。', 503);
+    throw new RequestValidationError(
+        requestMode
+            ? `当前没有支持 ${requestMode} 的健康渠道凭证。请调整请求策略或 OPENAI_CHANNEL_N_REQUEST_MODES。`
+            : '当前没有可用的健康渠道凭证。',
+        503
+    );
 }
 
 export function getChannelPoolSummary(config: ChannelPoolConfig): ChannelPoolSummary {
@@ -381,6 +633,7 @@ export function getChannelPoolSummary(config: ChannelPoolConfig): ChannelPoolSum
             hasExtraHeaders: boolean;
             requestHeaders: ReturnType<typeof summarizeUpstreamRequestHeaders>;
             providerManifest?: ImageProviderManifestSummary;
+            requestModes: readonly ChannelRequestMode[];
             credentialCount: number;
         }
     >();
@@ -399,6 +652,7 @@ export function getChannelPoolSummary(config: ChannelPoolConfig): ChannelPoolSum
             hasExtraHeaders: Boolean(credential.upstreamHeaders),
             requestHeaders: summarizeUpstreamRequestHeaders(credential.upstreamHeaders),
             ...(credential.providerManifest ? { providerManifest: credential.providerManifest } : {}),
+            requestModes: getEffectiveChannelRequestModes(credential),
             credentialCount: 1
         });
     });
@@ -411,6 +665,51 @@ export function getChannelPoolSummary(config: ChannelPoolConfig): ChannelPoolSum
     };
 }
 
+function summarizeCredentialRequestModes(credentials: ChannelCredential[]): readonly ChannelRequestMode[] {
+    return CHANNEL_REQUEST_MODES.filter((mode) =>
+        credentials.some((credential) => getEffectiveChannelRequestModes(credential).includes(mode))
+    );
+}
+
+function summarizeHealthyRequestModes(
+    credentials: ChannelCredential[],
+    isHealthyForRequestMode: (credential: ChannelCredential, mode: ChannelRequestMode) => boolean
+): readonly ChannelRequestMode[] {
+    return CHANNEL_REQUEST_MODES.filter((mode) =>
+        credentials.some((credential) => isHealthyForRequestMode(credential, mode))
+    );
+}
+
+function summarizeHealthyRequestModesByChannel(
+    credentials: ChannelCredential[],
+    isHealthyForRequestMode: (credential: ChannelCredential, mode: ChannelRequestMode) => boolean
+): Array<{ channelId: string; requestModes: readonly ChannelRequestMode[] }> {
+    return Array.from(new Set(credentials.map((credential) => credential.channelId))).flatMap((channelId) => {
+        const channelCredentials = credentials.filter((credential) => credential.channelId === channelId);
+        const requestModes = summarizeHealthyRequestModes(channelCredentials, isHealthyForRequestMode);
+        return requestModes.length ? [{ channelId, requestModes }] : [];
+    });
+}
+
+function summarizeRequestModeCoverage(
+    credentials: ChannelCredential[],
+    isHealthyForRequestMode: (credential: ChannelCredential, mode: ChannelRequestMode) => boolean
+): ChannelRequestModeHealthSummary['modes'] {
+    return CHANNEL_REQUEST_MODES.map((mode) => {
+        const configuredCredentials = credentials.filter((credential) =>
+            getEffectiveChannelRequestModes(credential).includes(mode)
+        );
+        const healthyModeCredentials = credentials.filter((credential) => isHealthyForRequestMode(credential, mode));
+        return {
+            mode,
+            configuredCredentialCount: configuredCredentials.length,
+            healthyCredentialCount: healthyModeCredentials.length,
+            configuredChannelCount: new Set(configuredCredentials.map((credential) => credential.channelId)).size,
+            healthyChannelCount: new Set(healthyModeCredentials.map((credential) => credential.channelId)).size
+        };
+    });
+}
+
 export function resolveEffectiveCredential(options: {
     requestApiKey: string;
     requestApiBaseUrl: string;
@@ -512,6 +811,7 @@ function parseLegacyConfig(env: Record<string, string | undefined>): ChannelPool
     if (rawProfile && !isValidImageUpstreamProfileId(rawProfile)) {
         throw new RequestValidationError('OPENAI_UPSTREAM_PROFILE 必须是 openai-compatible 或 matsca。', 500);
     }
+    const requestModes = parseChannelRequestModes(env.OPENAI_UPSTREAM_REQUEST_MODES, 'OPENAI_UPSTREAM_REQUEST_MODES');
 
     return {
         strategy: DEFAULT_STRATEGY,
@@ -525,7 +825,8 @@ function parseLegacyConfig(env: Record<string, string | undefined>): ChannelPool
                     explicitProfile: rawProfile,
                     channelId: 'default',
                     baseUrl
-                }).id
+                }).id,
+                ...(requestModes ? { requestModes } : {})
             }
         ]
     };
@@ -540,6 +841,10 @@ function parseNumberedChannel(env: Record<string, string | undefined>, channelIn
     const providerManifest = readChannelProviderManifest(env, channelIndex, upstreamProfile);
     const providerProfile = providerManifest ? createProviderManifestProfile(providerManifest) : undefined;
     const failureCooldownMs = readOptionalPositiveIntegerEnv(env, `OPENAI_CHANNEL_${channelIndex}_FAILURE_COOLDOWN_MS`);
+    const requestModes = parseChannelRequestModes(
+        env[`OPENAI_CHANNEL_${channelIndex}_REQUEST_MODES`],
+        `OPENAI_CHANNEL_${channelIndex}_REQUEST_MODES`
+    );
     if (baseUrl) {
         validateApiBaseUrl(baseUrl, {
             allowedPlainHttpBaseUrls: readPlainHttpApiBaseUrlAllowlist(env.OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS)
@@ -563,7 +868,8 @@ function parseNumberedChannel(env: Record<string, string | undefined>, channelIn
         ...(upstreamHeaders ? { upstreamHeaders } : {}),
         ...(providerManifest ? { providerManifest: createProviderManifestSummary(providerManifest) } : {}),
         ...(providerProfile ? { providerProfile } : {}),
-        ...(failureCooldownMs ? { failureCooldownMs } : {})
+        ...(failureCooldownMs ? { failureCooldownMs } : {}),
+        ...(requestModes ? { requestModes } : {})
     }));
 }
 

src/lib/image-route-support.ts

@@ -6,6 +6,7 @@ import {
     isChannelFailure,
     isCredentialFailure
 } from './channel-router';
+import type { ChannelRequestMode } from './channel-request-mode';
 import { RequestValidationError } from './image-request-utils';
 import type { ImageGenerationBackend } from './image-upstream-strategy';
 import { getServerChannelState } from './server-channel-router';
@@ -44,12 +45,19 @@ export function assertResponsesImageBackendAllowed(input: { imageBackend: ImageB
     }
 }
 
-export function reportServerCredentialFailure(credential: ChannelCredential | undefined, error: unknown) {
+export function reportServerCredentialFailure(
+    credential: ChannelCredential | undefined,
+    error: unknown,
+    requestMode?: ChannelRequestMode
+) {
     const serverChannelRouter = getServerChannelState().router;
     if (!credential || !serverChannelRouter) return;
     if (isChannelFailure(error)) {
-        const reason = describeChannelFailure(error, 'channel');
-        const report = serverChannelRouter.reportFailure(credential, { scope: 'channel', reason });
+        const reason = {
+            ...describeChannelFailure(error, 'channel'),
+            ...(requestMode ? { requestMode } : {})
+        };
+        const report = serverChannelRouter.reportFailure(credential, { scope: 'channel', requestMode, reason });
         appLogger.warn(
             report.cooldownApplied
                 ? `暂时冷却 API 渠道：${credential.channelId}`
@@ -59,8 +67,11 @@ export function reportServerCredentialFailure(credential: ChannelCredential | un
         return;
     }
     if (isCredentialFailure(error)) {
-        const reason = describeChannelFailure(error, 'credential');
-        const report = serverChannelRouter.reportFailure(credential, { reason });
+        const reason = {
+            ...describeChannelFailure(error, 'credential'),
+            ...(requestMode ? { requestMode } : {})
+        };
+        const report = serverChannelRouter.reportFailure(credential, { requestMode, reason });
         appLogger.warn(
             report.cooldownApplied
                 ? `暂时冷却 API 渠道凭证：${credential.channelId}/${credential.id}`