Deploy 863ecb4 to Docker Space

Source: MisonL/gpt-image-playground-customer@863ecb4beb440a5c59e5a0034a32c0176a0853ba

.env.agent.local.example

@@ -1,9 +1,18 @@
 # Copy to .env.agent.local and keep the real file private.
-# Load it into your shell before running protected Agent scripts.
-#
-# Example:
-# set -a; source .env.agent.local; set +a
+# Agent CLI scripts automatically read this file from the current repo root.
+# Shell environment variables still take precedence.
+# Set GPT_IMAGE_AGENT_LOAD_ENV_FILE=0 to disable automatic loading.
 
+# Use the deployment you intend to test. For Space or other public services,
+# set the remote URL explicitly so subagents do not fall back to localhost.
 GPT_IMAGE_PLAYGROUND_URL=http://localhost:4783
+
+# Agent JSON, Agent edit, job, artifact and diagnostics endpoints use this
+# when the service is configured with AGENT_API_TOKEN.
 GPT_IMAGE_AGENT_TOKEN=
+
+# Page SSE uses the page access-code hash as a form field named passwordHash.
+# This is required for --page-sse, large generate defaults, Responses backend
+# edit, and page-SSE batch tasks when the deployment has APP_PASSWORD enabled.
+# GPT_IMAGE_AGENT_TOKEN alone does not satisfy page SSE form auth.
 GPT_IMAGE_APP_PASSWORD_HASH=

README.md

@@ -35,7 +35,7 @@ npm run first-run -- --json --base-url https://your-space.hf.space
 1. 运行 `npm install`。
 2. 启动服务：本地开发用 `npm run dev`，Docker 用 `docker compose up -d --build --remove-orphans`。
 3. 运行 `npm run first-run` 看中文摘要；如果要检查 Space 或内网服务，使用 `npm run first-run -- --base-url <url>`。
-4. 如果 Agent API 需要鉴权，复制 `.env.agent.local.example` 为 `.env.agent.local`，填入本机私有 token 后加载到 shell，再运行 `npm run first-run` 或 skill 脚本。
+4. 如果 Agent API 需要鉴权，复制 `.env.agent.local.example` 为 `.env.agent.local` 并填入本机私有 token。Agent CLI 会从当前仓库根目录自动读取该文件；shell 环境变量仍然优先。
 
 推荐 Docker：
 
@@ -194,11 +194,13 @@ AI Agent 集成时优先调用 skill 内置脚本，而不是临时手写 fetch
 
 交互式任务中，Agent 应先定位服务地址：用户明确提供 URL 时直接使用该 URL；否则先检查 `GPT_IMAGE_PLAYGROUND_URL`，再探测默认本地地址 `http://localhost:4783`。如果只发现环境变量或本地服务，先向用户确认是否使用；用户提供其他地址时，以用户提供的地址为准。非交互式任务无法确认时，按同一顺序自动选择，并在输出里说明地址来源。
 
-新环境或不确定服务地址时先运行 `npm run first-run`。它会只读报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权，以及 `.env.agent.local` 是否存在私有鉴权配置；如果 token 只在私有 env 文件中，先把它加载到 shell，再运行 skill 脚本。
+新环境或不确定服务地址时先运行 `npm run first-run`。它会只读报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权，以及 `.env.agent.local` 是否存在私有鉴权配置。Agent CLI 会从当前仓库根目录自动读取 `.env.agent.local`，shell 环境变量仍然优先；如需禁用自动读取，设置 `GPT_IMAGE_AGENT_LOAD_ENV_FILE=0`。
 
 dry-run 只做本地请求构造和静态路由规划，不读取远端 capabilities，也不验证远端鉴权、渠道容量或 manifest 写入。脚本输出里的 `verification_scope.mode=local_planning_only` 表示还没有证明远端服务可执行；需要远端合同检查时使用 `--contract-check`，真实执行必须显式添加 `--allow-billable`。
 
-subagent 或自动化任务要固定服务地址时，优先给脚本传 `--base-url`，不要只依赖默认 localhost。`generate-image.mjs`、`edit-image.mjs`、`batch-images.mjs`、`diagnose-request.mjs` 和 `npm run agent:doctor -- --base-url <url>` 都支持显式服务地址。首次配置 Agent 鉴权时复制 `.env.agent.local.example` 为 `.env.agent.local`，填入本机私有 token 后加载到 shell；不要把 `.env.agent.local` 提交或粘到任务日志。
+subagent 或自动化任务要固定服务地址时，优先给脚本传 `--base-url`，不要只依赖默认 localhost。`generate-image.mjs`、`edit-image.mjs`、`batch-images.mjs`、`diagnose-request.mjs` 和 `npm run agent:doctor -- --base-url <url>` 都支持显式服务地址。首次配置 Agent 鉴权时复制 `.env.agent.local.example` 为 `.env.agent.local` 并填入本机私有 token；不要把 `.env.agent.local` 提交或粘到任务日志。
+
+公网部署常见有两层鉴权：`GPT_IMAGE_AGENT_TOKEN` 只用于 `/api/agent/*` Bearer 鉴权；页面 SSE `/api/images` 仍可能要求 `GPT_IMAGE_APP_PASSWORD_HASH` 作为 `passwordHash` 表单字段。使用 `--page-sse`、Responses backend edit、大图默认页面 SSE 或批量页面 SSE 前，先用 `npm run first-run -- --base-url <url> --json` 或 `npm run agent:doctor -- --base-url <url>` 检查 `page_sse_auth_available_to_process` / `page_sse_auth_ready`。
 
 1. 只读检查当前服务能力，不触发计费：
 
@@ -306,8 +308,10 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 | `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
 | `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
 | `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
-| `agent_auth_process.has_token` | `first-run --json` | 当前 shell 是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
-| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；存在不代表当前 shell 已加载。 |
+| `agent_auth_process.has_token` | `first-run --json` | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
+| `page_sse_auth_available_to_process` | `first-run --json` | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。 |
+| `summary.page_sse_auth_ready` | `agent:doctor` | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。 |
+| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
 | `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
 | `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
 
@@ -320,7 +324,7 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 | `GPT_IMAGE_APP_PASSWORD_HASH` | 使用页面访问码部署时的访问码哈希；页面 SSE 会作为 `passwordHash` 表单字段发送。 |
 | `GPT_IMAGE_AGENT_IDEMPOTENCY_KEY` | 跨脚本进程复用同一业务操作的幂等键。 |
 
-Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端 Space 配置了 `AGENT_API_TOKEN` 后，本机 Agent 仍需要通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；不要把 token 写进 README、任务 JSONL、manifest 或命令日志。仓库提供 `.env.agent.local.example` 作为私有本机配置模板。
+Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端 Space 配置了 `AGENT_API_TOKEN` 后，本机 Agent 仍需要通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；如果 Space 同时配置了 `APP_PASSWORD`，页面 SSE 还需要 `GPT_IMAGE_APP_PASSWORD_HASH`。Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`，shell 环境变量优先。不要把 token、访问码或哈希写进 README、任务 JSONL、manifest 或命令日志。仓库提供 `.env.agent.local.example` 作为私有本机配置模板。
 
 接口边界：
 

scripts/agent-doctor.mjs

@@ -3,7 +3,10 @@
 import { fileURLToPath } from 'node:url';
 
 import { isMainModule, parseJsonPayload, pickFailureOutput, printJson, redactBaseUrl, runCommand } from './command-center-utils.mjs';
-import { resolvePlaygroundBaseUrl } from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
+import {
+    loadPrivateAgentEnvFile,
+    resolvePlaygroundBaseUrl
+} from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.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));
@@ -60,6 +63,7 @@ agent:doctor 默认只读、非计费。真实 generate/edit smoke 必须显式
 }
 
 async function main() {
+    loadPrivateAgentEnvFile();
     const options = parseArgs(process.argv.slice(2));
     if (options.help) {
         printHelp();
@@ -262,6 +266,15 @@ function buildLayers({ capabilities, runtime, contract, smoke }) {
 function summarizeCapabilities(body) {
     return {
         page_sse: body?.agent_streaming?.page_sse?.supported === true,
+        page_sse_auth_required: body?.agent_streaming?.page_sse?.auth?.required === true,
+        page_sse_auth_ready:
+            body?.agent_streaming?.page_sse?.auth?.required === true
+                ? Boolean(process.env.GPT_IMAGE_APP_PASSWORD_HASH)
+                : true,
+        page_sse_auth_next_action:
+            body?.agent_streaming?.page_sse?.auth?.required === true && !process.env.GPT_IMAGE_APP_PASSWORD_HASH
+                ? 'Set GPT_IMAGE_APP_PASSWORD_HASH in private local env before using --page-sse.'
+                : 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)
@@ -304,6 +317,10 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
         contract_check: contract.ok ? 'ok' : 'failed',
         runtime: runtime.ok ? 'ok' : 'failed',
         state_backend: capabilities.ok ? capabilities.body?.defaults?.state_backend : 'unknown',
+        page_sse_auth_ready:
+            capabilities.ok && capabilities.body?.agent_streaming?.page_sse?.auth?.required === true
+                ? Boolean(process.env.GPT_IMAGE_APP_PASSWORD_HASH)
+                : capabilities.ok,
         responses_gpt2image_ready:
             capabilities.ok && runtime.ok
                 ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true &&

scripts/agent-skill-scripts.test.mjs

@@ -6,7 +6,7 @@ import {
 import { AGENT_ENDPOINTS } from '../src/lib/agent-api-paths.mjs';
 import assert from 'node:assert/strict';
 import { spawn, spawnSync } from 'node:child_process';
-import { cpSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -126,6 +126,144 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stdout.trim(), '');
     });
 
+    it('loads private agent env files for CLI scripts without overriding shell env', () => {
+        const tempRoot = mkdtempSync(join(tmpdir(), 'agent-env-load-'));
+        try {
+            mkdirSync(join(tempRoot, '.git'));
+            writeFileSync(
+                join(tempRoot, '.env.agent.local'),
+                [
+                    'GPT_IMAGE_PLAYGROUND_URL=https://file-space.example.test',
+                    'GPT_IMAGE_AGENT_MAX_ATTEMPTS=2',
+                    'GPT_IMAGE_AGENT_TOKEN=file-token',
+                    'GPT_IMAGE_APP_PASSWORD_HASH=file-hash',
+                    'GPT_IMAGE_UPSTREAM_BASE_URL=https://upstream.example.test/v1',
+                    'GPT_IMAGE_UPSTREAM_API_KEY=upstream-secret'
+                ].join('\n')
+            );
+
+            const loaded = runSkillScript('generate-image.mjs', ['prompt'], {}, { cwd: tempRoot, loadPrivateAgentEnv: true });
+            assert.equal(loaded.status, 0);
+            const loadedBody = JSON.parse(loaded.stdout);
+            assert.equal(loadedBody.verification_scope.service_base_url, 'https://file-space.example.test');
+            assert.equal(loadedBody.verification_scope.service_base_url_source, 'GPT_IMAGE_PLAYGROUND_URL');
+            assert.equal(loadedBody.verification_scope.interactive_confirmation_required, true);
+            assert.doesNotMatch(loaded.stdout, /file-token|file-hash|upstream-secret/);
+            assert.equal(loaded.stderr.trim(), '');
+
+            const fromNestedCwd = runSkillScript(
+                'generate-image.mjs',
+                ['prompt'],
+                {},
+                { cwd: join(tempRoot, 'nested', 'scripts'), loadPrivateAgentEnv: true, createCwd: true }
+            );
+            assert.equal(fromNestedCwd.status, 0);
+            const nestedBody = JSON.parse(fromNestedCwd.stdout);
+            assert.equal(nestedBody.verification_scope.service_base_url, 'https://file-space.example.test');
+
+            const parentRoot = mkdtempSync(join(tmpdir(), 'agent-env-parent-'));
+            try {
+                writeFileSync(
+                    join(parentRoot, '.env.agent.local'),
+                    'GPT_IMAGE_PLAYGROUND_URL=https://parent-space.example.test'
+                );
+                const childRoot = join(parentRoot, 'child-repo');
+                mkdirSync(join(childRoot, '.git'), { recursive: true });
+                const bounded = runSkillScript(
+                    'generate-image.mjs',
+                    ['prompt'],
+                    {},
+                    { cwd: join(childRoot, 'nested'), loadPrivateAgentEnv: true, createCwd: true }
+                );
+                assert.equal(bounded.status, 0);
+                const boundedBody = JSON.parse(bounded.stdout);
+                assert.equal(boundedBody.verification_scope.service_base_url, 'http://localhost:4783');
+
+                const projectCopyRoot = join(parentRoot, 'project-copy');
+                mkdirSync(join(projectCopyRoot, 'skills/gpt-image-playground-agent'), { recursive: true });
+                mkdirSync(join(projectCopyRoot, 'nested'), { recursive: true });
+                writeFileSync(join(projectCopyRoot, 'package.json'), JSON.stringify({ name: 'gpt-image-playground' }));
+                writeFileSync(join(projectCopyRoot, 'skills/gpt-image-playground-agent/SKILL.md'), '# skill\n');
+                const projectBounded = runSkillScript(
+                    'generate-image.mjs',
+                    ['prompt'],
+                    {},
+                    { cwd: join(projectCopyRoot, 'nested'), loadPrivateAgentEnv: true }
+                );
+                assert.equal(projectBounded.status, 0);
+                const projectBoundedBody = JSON.parse(projectBounded.stdout);
+                assert.equal(projectBoundedBody.verification_scope.service_base_url, 'http://localhost:4783');
+
+                writeFileSync(
+                    join(projectCopyRoot, '.env.agent.local'),
+                    'GPT_IMAGE_PLAYGROUND_URL=https://project-copy.example.test'
+                );
+                const projectLoaded = runSkillScript(
+                    'generate-image.mjs',
+                    ['prompt'],
+                    {},
+                    { cwd: join(projectCopyRoot, 'nested'), loadPrivateAgentEnv: true }
+                );
+                assert.equal(projectLoaded.status, 0);
+                const projectLoadedBody = JSON.parse(projectLoaded.stdout);
+                assert.equal(projectLoadedBody.verification_scope.service_base_url, 'https://project-copy.example.test');
+
+                const projectSkillScriptsLoaded = runSkillScript(
+                    'generate-image.mjs',
+                    ['prompt'],
+                    {},
+                    {
+                        cwd: join(projectCopyRoot, 'skills/gpt-image-playground-agent/scripts'),
+                        loadPrivateAgentEnv: true,
+                        createCwd: true
+                    }
+                );
+                assert.equal(projectSkillScriptsLoaded.status, 0);
+                const projectSkillScriptsLoadedBody = JSON.parse(projectSkillScriptsLoaded.stdout);
+                assert.equal(
+                    projectSkillScriptsLoadedBody.verification_scope.service_base_url,
+                    'https://project-copy.example.test'
+                );
+            } finally {
+                rmSync(parentRoot, { recursive: true, force: true });
+            }
+
+            const shellWins = runSkillScript(
+                'generate-image.mjs',
+                ['prompt'],
+                { GPT_IMAGE_PLAYGROUND_URL: 'https://shell-space.example.test' },
+                { cwd: tempRoot, loadPrivateAgentEnv: true }
+            );
+            assert.equal(shellWins.status, 0);
+            const shellBody = JSON.parse(shellWins.stdout);
+            assert.equal(shellBody.verification_scope.service_base_url, 'https://shell-space.example.test');
+
+            const disabled = runSkillScript(
+                'generate-image.mjs',
+                ['prompt'],
+                { GPT_IMAGE_AGENT_LOAD_ENV_FILE: '0' },
+                { cwd: tempRoot }
+            );
+            assert.equal(disabled.status, 0);
+            const disabledBody = JSON.parse(disabled.stdout);
+            assert.equal(disabledBody.verification_scope.service_base_url, 'http://localhost:4783');
+
+            const probe = runSkillScript(
+                'probe-upstream-image.mjs',
+                ['--timeout-ms', '1'],
+                {},
+                { cwd: tempRoot, loadPrivateAgentEnv: true }
+            );
+            assert.notEqual(probe.status, 2);
+            const probeBody = JSON.parse(probe.stdout);
+            assert.equal(probeBody.base_url, 'https://upstream.example.test/v1');
+            assert.equal(probeBody.api_key_configured, true);
+            assert.doesNotMatch(probe.stdout, /upstream-secret/);
+        } finally {
+            rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+
     it('inherits longer image transport timeout from capabilities by default', () => {
         assert.equal(
             readCapabilitiesImageTransportTimeoutMs(
@@ -918,6 +1056,28 @@ describe('Agent skill script argument validation', () => {
                 const body = JSON.parse(result.stderr);
                 assert.equal(body.error.code, 'page_sse_auth_required');
                 assert.match(body.error.message, /GPT_IMAGE_APP_PASSWORD_HASH/);
+                assert.match(body.error.message, /\.env\.agent\.local/);
+                assert.match(body.error.message, /GPT_IMAGE_AGENT_TOKEN/);
+                assert.equal(body.summary.ok, false);
+                assert.equal(body.summary.billable, false);
+                assert.equal(body.summary.request_id, null);
+                assert.equal(body.summary.idempotency_key.startsWith('agent-generate-'), true);
+                assert.deepEqual(body.summary.artifact_ids, []);
+                assert.deepEqual(body.summary.content_urls, []);
+                assert.deepEqual(body.summary.absolute_content_urls, []);
+                assert.equal(body.summary.route_mode, 'page_sse');
+                assert.equal(body.summary.image_backend, null);
+                assert.equal(body.summary.stream_mode, null);
+                assert.equal(body.summary.streaming_strategy, null);
+                assert.equal(body.summary.selected_channel_id, null);
+                assert.equal(body.summary.upstream_host, null);
+                assert.equal(body.summary.transport_error_kind, null);
+                assert.equal(body.summary.retry_after_ms, null);
+                assert.equal(body.summary.retry_after_seconds, null);
+                assert.equal(body.summary.cooldown_until, null);
+                assert.equal(body.summary.cooldown_target, null);
+                assert.equal(body.summary.elapsed_source, 'client_script');
+                assert.equal(typeof body.summary.elapsed_breakdown.client_script_ms, 'number');
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
                     ['GET /api/agent/capabilities']
@@ -1457,7 +1617,8 @@ describe('Agent skill script argument validation', () => {
                                     content_url: '/api/agent/artifacts/artifact-off/content',
                                     metadata_url: '/api/agent/artifacts/artifact-off'
                                 }
-                            ]
+                            ],
+                            timing: { server_elapsed_ms: 4321 }
                         })
                     );
                     return;
@@ -1496,7 +1657,13 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(body.summary.idempotency_key.startsWith('agent-generate-'), true);
                 assert.equal(body.summary.transport, 'agent_json');
                 assert.equal(body.summary.endpoint, '/api/agent/images/generate');
+                assert.equal(body.summary.route_mode, 'agent');
+                assert.deepEqual(body.summary.content_urls, ['/api/agent/artifacts/artifact-off/content']);
+                assert.deepEqual(body.summary.absolute_content_urls, [`${baseUrl}/api/agent/artifacts/artifact-off/content`]);
                 assert.equal(typeof body.summary.elapsed_ms, 'number');
+                assert.equal(body.summary.elapsed_source, 'client_script');
+                assert.equal(body.summary.server_elapsed_ms, 4321);
+                assert.equal(body.summary.elapsed_breakdown.upstream_or_server_ms, 4321);
                 assert.equal(body.summary.next_action, 'done');
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
@@ -1620,11 +1787,22 @@ describe('Agent skill script argument validation', () => {
                 const body = JSON.parse(result.stdout);
                 assert.equal(body.images[0].filename, 'small-page.png');
                 assert.equal(body.images[0].absolute_path, `${baseUrl}/api/image/small-page.png`);
-                assert.deepEqual(body.routing, { transport: 'page_sse', endpoint: '/api/images' });
+                assert.deepEqual(body.routing, {
+                    transport: 'page_sse',
+                    endpoint: '/api/images',
+                    route_mode: 'page_sse',
+                    fallback_endpoint: '/api/agent/images/generate',
+                    fallback_mode: 'manual_after_diagnosis',
+                    stream_mode: null,
+                    streaming_strategy: null
+                });
                 assert.equal(body.summary.ok, true);
                 assert.equal(body.summary.billable, true);
                 assert.equal(body.summary.transport, 'page_sse');
                 assert.equal(body.summary.endpoint, '/api/images');
+                assert.equal(body.summary.route_mode, 'page_sse');
+                assert.deepEqual(body.summary.content_urls, ['/api/image/small-page.png']);
+                assert.deepEqual(body.summary.absolute_content_urls, [`${baseUrl}/api/image/small-page.png`]);
                 assert.equal(typeof body.summary.elapsed_ms, 'number');
                 assert.deepEqual(
                     requests.map((item) => `${item.method} ${item.url}`),
@@ -2721,6 +2899,26 @@ describe('Agent skill script argument validation', () => {
         const copiedSkillRoot = join(tempRoot, 'gpt-image-playground-agent');
         try {
             cpSync(skillRoot, copiedSkillRoot, { recursive: true });
+            writeFileSync(
+                join(tempRoot, '.env.agent.local'),
+                'GPT_IMAGE_PLAYGROUND_URL=https://parent-space.example.test'
+            );
+            const standaloneRun = spawnSync(
+                process.execPath,
+                [join(copiedSkillRoot, 'scripts/generate-image.mjs'), 'prompt'],
+                {
+                    cwd: join(copiedSkillRoot, 'scripts'),
+                    encoding: 'utf8',
+                    env: {
+                        ...buildIsolatedSkillScriptEnv({ loadPrivateAgentEnv: true }),
+                        GPT_IMAGE_AGENT_LOAD_ENV_FILE: '1'
+                    }
+                }
+            );
+            assert.equal(standaloneRun.status, 0);
+            const standaloneBody = JSON.parse(standaloneRun.stdout);
+            assert.equal(standaloneBody.verification_scope.service_base_url, 'http://localhost:4783');
+
             const result = spawnSync(
                 process.execPath,
                 [join(copiedSkillRoot, 'scripts/generate-image.mjs'), '--help'],
@@ -5443,14 +5641,34 @@ describe('Agent skill script argument validation', () => {
     });
 });
 
-function runSkillScript(filename, args, env = {}) {
+function runSkillScript(filename, args, env = {}, options = {}) {
+    const baseEnv = buildIsolatedSkillScriptEnv({ loadPrivateAgentEnv: options.loadPrivateAgentEnv });
+    if (options.createCwd) mkdirSync(options.cwd, { recursive: true });
     return spawnSync(process.execPath, [join(skillScriptsRoot, filename), ...args], {
-        cwd: repoRoot,
+        cwd: options.cwd || repoRoot,
         encoding: 'utf8',
-        env: { ...process.env, ...env }
+        env: { ...baseEnv, ...env }
     });
 }
 
+function buildIsolatedSkillScriptEnv(options = {}) {
+    const keepNames = [
+        'HOME',
+        'PATH',
+        'SystemRoot',
+        'TEMP',
+        'TMP',
+        'TMPDIR',
+        'USERPROFILE'
+    ];
+    const isolated = {};
+    for (const name of keepNames) {
+        if (process.env[name] !== undefined) isolated[name] = process.env[name];
+    }
+    if (!options.loadPrivateAgentEnv) isolated.GPT_IMAGE_AGENT_LOAD_ENV_FILE = '0';
+    return isolated;
+}
+
 function listTextFiles(root) {
     const result = [];
     for (const name of readdirSync(root)) {

scripts/command-center.test.mjs

@@ -447,6 +447,15 @@ describe('Command center scripts', () => {
                         JSON.stringify({
                             auth: { schemes: ['bearer'] },
                             defaults: { state_backend: 'memory' },
+                            agent_streaming: {
+                                page_sse: {
+                                    supported: true,
+                                    auth: {
+                                        required: true,
+                                        form_field: 'passwordHash'
+                                    }
+                                }
+                            },
                             supported: { image_backend_requirements: {} }
                         })
                     );
@@ -489,6 +498,15 @@ describe('Command center scripts', () => {
                     });
                     assert.equal(report.service.ok, true);
                     assert.equal(report.checks.find((check) => check.name === 'agent_auth_available_to_process').ok, true);
+                    assert.equal(report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').ok, false);
+                    assert.equal(report.checks.find((check) => check.name === 'page_sse_auth_available_to_process').skipped, false);
+                    assert.equal(
+                        report.checks.find((check) => check.name === 'page_sse_auth_available_to_process')
+                            .auth_in_private_env_file,
+                        false
+                    );
+                    assert.equal(report.service.capabilities.page_sse_auth_required, true);
+                    assert.equal(report.service.capabilities.page_sse_auth_form_field, 'passwordHash');
                     assert.equal(
                         report.checks.find((check) => check.name === 'agent_auth_available_to_process')
                             .auth_in_private_env_file,
@@ -496,6 +514,8 @@ describe('Command center scripts', () => {
                     );
                     assert.doesNotMatch(JSON.stringify(report), /shell-secret|file-secret/);
                     assert.match(JSON.stringify(report.next_actions), /agent:doctor/);
+                    assert.match(JSON.stringify(report.next_actions), /GPT_IMAGE_APP_PASSWORD_HASH/);
+                    assert.match(JSON.stringify(report.next_actions), /GPT_IMAGE_AGENT_TOKEN/);
                 } finally {
                     await rm(tempDir, { recursive: true, force: true });
                 }
@@ -504,7 +524,10 @@ describe('Command center scripts', () => {
     });
 
     it('formats first-run as human-readable text by default', async () => {
-        const report = await buildFirstRunReport({ cwd: process.cwd(), baseUrl: 'not a url', envFiles: [] }, {});
+        const report = await buildFirstRunReport(
+            { cwd: process.cwd(), baseUrl: 'not a url', envFiles: [] },
+            { GPT_IMAGE_AGENT_LOAD_ENV_FILE: '0' }
+        );
         const text = formatFirstRunText(report);
 
         assert.match(text, /^首次配置检查：需要处理/m);
@@ -608,7 +631,10 @@ describe('Command center scripts', () => {
                             defaults: { state_backend: 'memory' },
                             storage: { image_storage_mode: 'indexeddb', postgres_configured: false },
                             agent_streaming: {
-                                page_sse: { supported: true }
+                                page_sse: {
+                                    supported: true,
+                                    auth: { required: true, form_field: 'passwordHash' }
+                                }
                             },
                             agent_jobs: { supported: true },
                             routing_rules: {
@@ -691,10 +717,17 @@ describe('Command center scripts', () => {
                 assert.equal(body.summary.capabilities, 'ok');
                 assert.equal(body.summary.runtime, 'ok');
                 assert.equal(body.summary.state_backend, 'memory');
+                assert.equal(body.summary.page_sse_auth_ready, false);
                 assert.equal(body.summary.responses_gpt2image_ready, true);
                 assert.equal(body.summary.billable_smoke, 'skipped');
                 assert.equal(body.layers.find((layer) => layer.name === 'billable_smoke').skipped, true);
                 assert.equal(body.layers.find((layer) => layer.name === 'capabilities').executable_routing_rules, true);
+                assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_required, true);
+                assert.equal(body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_ready, false);
+                assert.match(
+                    body.layers.find((layer) => layer.name === 'capabilities').page_sse_auth_next_action,
+                    /GPT_IMAGE_APP_PASSWORD_HASH/
+                );
                 assert.equal(body.service_base_url, prefixedBaseUrl);
                 assert.equal(body.service_base_url_source, 'GPT_IMAGE_PLAYGROUND_URL');
                 assert.equal(body.interactive_confirmation_required, true);
@@ -942,7 +975,7 @@ function runNodeCommandAsync(args, options = {}) {
     return new Promise((resolve) => {
         const child = spawn(process.execPath, args, {
             cwd: process.cwd(),
-            env: options.env,
+            env: { GPT_IMAGE_AGENT_LOAD_ENV_FILE: '0', ...options.env },
             stdio: ['ignore', 'pipe', 'pipe']
         });
         let stdout = '';

scripts/first-run.mjs

@@ -5,7 +5,10 @@ import { join } from 'node:path';
 
 import { isMainModule, printJson, redactBaseUrl } from './command-center-utils.mjs';
 import { summarizeEnvFile } from './env-summary.mjs';
-import { resolvePlaygroundBaseUrl } from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
+import {
+    loadPrivateAgentEnvFile,
+    resolvePlaygroundBaseUrl
+} from '../skills/gpt-image-playground-agent/scripts/lib/script-utils.mjs';
 
 const DEFAULT_TIMEOUT_MS = 3000;
 const DEFAULT_ENV_FILES = ['.env.local', '.env.agent.local'];
@@ -45,6 +48,7 @@ first-run 只读、非计费，不写 env 文件或 secret。`);
 export async function buildFirstRunReport(options = {}, env = process.env) {
     const cwd = options.cwd || process.cwd();
     const envFiles = options.envFiles || DEFAULT_ENV_FILES;
+    loadPrivateAgentEnvFile({ cwd, env });
     const base = resolveFirstRunBaseUrl(options.baseUrl, env);
     const envSummary = envFiles.map((filePath) => summarizeEnvFile(join(cwd, filePath)));
     const validationError = readBaseUrlValidationError(base);
@@ -159,6 +163,14 @@ function buildChecks({ cwd, env, envSummary, service, base, validationError }) {
             skipped: !requiresAgentAuth(service),
             auth_in_private_env_file: fileToken
         },
+        {
+            name: 'page_sse_auth_available_to_process',
+            ok: Boolean(env.GPT_IMAGE_APP_PASSWORD_HASH),
+            skipped: !requiresPageSsePasswordHash(service),
+            auth_in_private_env_file: envSummary.some((source) =>
+                sourceHasSetVariable(source, 'GPT_IMAGE_APP_PASSWORD_HASH')
+            )
+        },
         {
             name: 'service_base_url_valid',
             ok: !validationError,
@@ -229,6 +241,11 @@ function buildNextActions({ checks, base, service, env, envSummary, validationEr
             '在仓库外导出 GPT_IMAGE_AGENT_TOKEN 或 GPT_IMAGE_APP_PASSWORD_HASH，再运行受保护的 Agent 脚本。'
         );
     }
+    if (requiresPageSsePasswordHash(service) && !env.GPT_IMAGE_APP_PASSWORD_HASH) {
+        actions.push(
+            '如果要使用页面 SSE、Responses backend edit 或 --page-sse，请在本机私有 .env.agent.local 中设置 GPT_IMAGE_APP_PASSWORD_HASH；Agent 脚本会自动读取该文件，GPT_IMAGE_AGENT_TOKEN 只覆盖 Agent JSON 鉴权。'
+        );
+    }
     if (!service.ok && !requiresAgentAuth(service)) {
         actions.push('先用 npm run dev 或 docker compose up -d --build --remove-orphans 启动服务，再重新运行 npm run first-run。');
     }
@@ -236,7 +253,7 @@ function buildNextActions({ checks, base, service, env, envSummary, validationEr
         actions.push('在交互式 Agent 任务里，先和用户确认探测到的服务地址，再发真实请求。');
     }
     if (!hasCurrentAuth && hasFileAuth) {
-        actions.push('先把私有 Agent env 文件加载到 shell，再运行 Agent 脚本。');
+        actions.push('Agent 脚本会自动读取 .env.agent.local；如果仍提示缺少鉴权，请确认文件位于当前仓库根目录且变量名正确。');
     }
     if (service.ok && hasCurrentAuth) {
         actions.push('运行 npm run agent:doctor 做完整的非计费 Agent 合同检查。');
@@ -250,6 +267,10 @@ function requiresAgentAuth(service) {
     return Array.isArray(schemes) && schemes.length > 0;
 }
 
+function requiresPageSsePasswordHash(service) {
+    return service.capabilities?.body?.agent_streaming?.page_sse?.auth?.required === true;
+}
+
 function sourceHasSetVariable(source, name) {
     return source.exists && source.variables.some((item) => item.name === name && item.set === true);
 }
@@ -299,6 +320,8 @@ function summarizeCapabilitiesBody(body) {
     return {
         auth_required: body?.auth?.required === true,
         auth_schemes: Array.isArray(body?.auth?.schemes) ? body.auth.schemes : [],
+        page_sse_auth_required: body?.agent_streaming?.page_sse?.auth?.required === true,
+        page_sse_auth_form_field: body?.agent_streaming?.page_sse?.auth?.form_field,
         state_backend: body?.defaults?.state_backend,
         image_storage_mode: body?.storage?.image_storage_mode,
         agent_jobs_supported: body?.agent_jobs?.supported === true,
@@ -386,6 +409,9 @@ export function formatFirstRunText(report) {
     const capability = report.service?.capabilities || {};
     if (capability.ok) {
         lines.push(`- 鉴权：${capability.auth_required ? capability.auth_schemes.join(',') || '需要' : '不需要'}`);
+        lines.push(
+            `- 页面 SSE 鉴权：${capability.page_sse_auth_required ? `需要 ${capability.page_sse_auth_form_field || 'passwordHash'}` : '不需要'}`
+        );
         lines.push(`- 状态后端：${capability.state_backend || '未知'}，图片存储：${capability.image_storage_mode || '未知'}`);
     }
     const runtime = report.service?.runtime || {};
@@ -451,6 +477,7 @@ function formatCheckLabel(name) {
         dependencies_installed: '依赖是否已安装',
         env_files: '环境文件',
         agent_auth_available_to_process: 'Agent 鉴权可用',
+        page_sse_auth_available_to_process: '页面 SSE 鉴权可用',
         service_base_url_valid: '服务地址合法',
         service_reachable: '服务可达',
         agent_capabilities_contract: 'Agent capabilities 合同',

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

@@ -20,7 +20,7 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
 - 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 `scripts/` 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
 - 先用 dry-run 或 `--contract-check` 检查请求、路由和鉴权；只有用户明确允许真实计费时才加 `--allow-billable`。
-- 真实调用成功或失败后，优先读取脚本输出的 `summary`。它是面向 Agent 的机器摘要，包含 `billable`、请求 ID、幂等键、产物 URL、耗时、路由、渠道、上游 host、脱敏请求头、重试和下一步动作；不要再先手查 SQLite、Docker logs 或上游后台。
+- 真实调用成功或失败后，优先读取脚本输出的 `summary`。它是面向 Agent 的机器摘要，包含 `billable`、请求 ID、幂等键、产物 URL、耗时、耗时拆分、路由、渠道、上游 host、脱敏请求头、重试和下一步动作；不要再先手查 SQLite、Docker logs 或上游后台。
 
 ## 产品边界
 
@@ -46,7 +46,7 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 2. 定位服务基础地址。用户明确提供 URL 时直接使用该 URL；否则先检查 `GPT_IMAGE_PLAYGROUND_URL`，再探测默认本地地址 `http://localhost:4783`。
 3. 交互式任务中，如果只发现环境变量或本地默认地址，先把发现到的地址、服务可达性和鉴权需求告诉用户，并确认是否使用它；不要把自动发现到的本地服务直接当成用户意图。如果用户随后提供其他服务地址，以用户提供的地址为准。
 4. 非交互式任务无法向用户确认时，按“用户提供 URL > `GPT_IMAGE_PLAYGROUND_URL` > 默认本地探测地址”的顺序执行，并在输出里标明服务地址来源和是否只是自动发现。
-5. 位于仓库根目录且用户是首次配置、换机器、服务地址不确定或 token 不确定时，先运行 `npm run first-run`。该命令只读、非计费、不写 env 文件，默认输出中文摘要；`-- --json` 输出机器可读 JSON。它会报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权，以及 `.env.agent.local` 是否存在私有鉴权配置；如果 token 只在私有 env 文件中，先加载到 shell，再运行 skill 脚本。
+5. 位于仓库根目录且用户是首次配置、换机器、服务地址不确定或 token 不确定时，先运行 `npm run first-run`。该命令只读、非计费、不写 env 文件，默认输出中文摘要；`-- --json` 输出机器可读 JSON。它会报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权、页面 SSE 鉴权是否可用，以及 `.env.agent.local` 是否存在私有鉴权配置。Agent CLI 默认从当前仓库根目录自动读取 `.env.agent.local`，shell 环境变量优先；如需禁用自动读取，设置 `GPT_IMAGE_AGENT_LOAD_ENV_FILE=0`。
 6. 让脚本请求 `GET /api/agent/capabilities`。如果所选地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，交互式任务中向用户询问实际部署地址、端口、域名和是否需要鉴权；非交互式任务中显式失败并输出下一步动作。
 7. 读取 capabilities 中的认证方式、模型、模型级限制、`image_transport`、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
 8. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
@@ -69,7 +69,7 @@ Authorization: Bearer <token>
 
 此时 Agent 端点只接受 Bearer token，不会回退到访问码哈希。如果未配置 `AGENT_API_TOKEN` 但配置了页面访问码 `APP_PASSWORD`，Agent 端点发送 `X-App-Password-Hash`。下载或删除产物时必须复用 capabilities 声明的同一 Agent 鉴权方式。
 
-页面端 `/api/images` SSE 是独立页面契约，读取 `agent_streaming.page_sse.auth`。当该字段声明 `required=true` 时，必须在 form-data 中发送 `passwordHash`；脚本侧对应环境变量是 `GPT_IMAGE_APP_PASSWORD_HASH`。即使 `auth.schemes` 只返回 `bearer`，混合配置下 page SSE 仍可能需要这个表单访问码哈希。页面 SSE 还会把同一业务 key 写入 form-data `clientRequestId`，长度不得超过 `agent_streaming.page_sse.client_request_id.max_length`。
+页面端 `/api/images` SSE 是独立页面契约，读取 `agent_streaming.page_sse.auth`。当该字段声明 `required=true` 时，必须在 form-data 中发送 `passwordHash`；脚本侧对应环境变量是 `GPT_IMAGE_APP_PASSWORD_HASH`。即使 `auth.schemes` 只返回 `bearer`，混合配置下 page SSE 仍可能需要这个表单访问码哈希；`GPT_IMAGE_AGENT_TOKEN` 不能替代页面 SSE 表单鉴权。页面 SSE 还会把同一业务 key 写入 form-data `clientRequestId`，长度不得超过 `agent_streaming.page_sse.client_request_id.max_length`。
 
 ## 调用约束
 
@@ -132,8 +132,10 @@ Authorization: Bearer <token>
 | `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
 | `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
 | `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
-| `agent_auth_process.has_token` | `first-run --json` | 当前 shell 是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
-| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；存在不代表当前 shell 已加载。 |
+| `agent_auth_process.has_token` | `first-run --json` | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
+| `page_sse_auth_available_to_process` | `first-run --json` | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。 |
+| `summary.page_sse_auth_ready` | `agent:doctor` | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。 |
+| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
 | `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
 | `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
 
@@ -227,14 +229,14 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 
 - `GPT_IMAGE_PLAYGROUND_URL`：服务基础地址，可指向本机、局域网、云服务器或域名；脚本未设置时默认尝试 `http://localhost:4783`。脚本参数 `--base-url` 优先级高于该环境变量。
 - `GPT_IMAGE_AGENT_TOKEN`：Bearer token。
-- `GPT_IMAGE_APP_PASSWORD_HASH`：使用 `APP_PASSWORD` 访问码部署时，Agent 端点发送为 `X-App-Password-Hash`，页面 SSE 发送为 form-data `passwordHash`。
+- `GPT_IMAGE_APP_PASSWORD_HASH`：使用 `APP_PASSWORD` 访问码部署时，Agent 端点发送为 `X-App-Password-Hash`，页面 SSE 发送为 form-data `passwordHash`。公网 Space 同时配置 `AGENT_API_TOKEN` 和 `APP_PASSWORD` 时，Agent JSON 需要 `GPT_IMAGE_AGENT_TOKEN`，页面 SSE 仍需要这个哈希。
 - `GPT_IMAGE_AGENT_IDEMPOTENCY_KEY`：跨脚本进程恢复同一操作时复用的幂等键；也供 `diagnose-request.mjs` 按 Agent 幂等键查询 state。脚本不会自动重试已终态失败的 key。
 - `GPT_IMAGE_AGENT_CLIENT_REQUEST_ID`：供 `diagnose-request.mjs` 读取的页面请求 ID；页面 SSE 路径通常等于脚本使用的 `Idempotency-Key`，多个 ID 可重复传 `--client-request-id`。
 - `GPT_IMAGE_AGENT_REQUEST_ID`：供 `diagnose-request.mjs` 读取 Agent state 请求诊断的 Agent `request_id`。
 - `GPT_IMAGE_AGENT_MAX_ATTEMPTS`：最大尝试次数，默认 `3`。
 - `GPT_IMAGE_AGENT_CONTRACT_CHECK=1`：只检查 capabilities 和错误契约，不触发真实生图或编辑。
 
-Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端配置 `AGENT_API_TOKEN` 后，本机 Agent 仍必须通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；不要把 token 写进仓库、README、任务 JSONL、manifest、命令参数或日志。仓库根目录的 `.env.agent.local.example` 只作私有本机配置模板，真实 `.env.agent.local` 不入库。
+Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端配置 `AGENT_API_TOKEN` 后，本机 Agent 仍必须通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`，shell 环境变量优先。不要把 token 写进仓库、README、任务 JSONL、manifest、命令参数或日志。仓库根目录的 `.env.agent.local.example` 只作私有本机配置模板，真实 `.env.agent.local` 不入库。
 
 上游请求���由服务端统一生成。默认 `User-Agent` 是 `gpt-image-playground/<package-version>`；可用 `OPENAI_UPSTREAM_USER_AGENT` 或 `UPSTREAM_USER_AGENT` 覆盖全局 UA，也可用 `OPENAI_CHANNEL_N_USER_AGENT` 和 `OPENAI_CHANNEL_N_UPSTREAM_HEADERS_JSON` 覆盖单渠道安全 header。`Authorization`、`Accept`、`Content-Type`、`Content-Length` 和 `Host` 等协议头不可由 extra headers 覆盖；capabilities、status 和 diagnostics 只暴露 `user_agent_effective`、`has_extra_headers`、`allowed_header_names` 和 `configured_header_names`，不暴露 secret 值。
 

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

@@ -32,11 +32,11 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 生成、编辑和批量脚本默认只做 dry-run，不触发真实生图或编辑。dry-run 输出的 `verification_scope.mode=local_planning_only` 表示只完成本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。必须显式添加 `--allow-billable` 才会按 capabilities 路由规则调用 `/api/agent/images/generate`、`/api/agent/images/edit`、`/api/agent/jobs/images/generate` 或页面端 `/api/images` SSE。
 上游探针默认只检查 DNS、TLS 和 `/models`，必须显式添加 `--allow-billable` 才会调用上游 `/images/generations`。
 脚本支持 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 或 `--contract-check` 做只读契约检查，不触发真实生图或编辑。
-位于仓库根目录且是首次配置、换机器、服务地址不确定或 token 不确定时，先运行 `npm run first-run`。它只读、非计费、不写 env 文件，默认输出中文摘要，并报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程鉴权和下一步动作。
+位于仓库根目录且是首次配置、换机器、服务地址不确定或 token 不确定时，先运行 `npm run first-run`。它只读、非计费、不写 env 文件，默认输出中文摘要，并报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程鉴权、页面 SSE 鉴权和下一步动作。
 自动化消费时使用 `npm run first-run -- --json`。
-Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，Agent 端点才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。页面端 `/api/images` SSE 另看 `agent_streaming.page_sse.auth`；当其声明 `required=true` 时，form-data 必须包含 `passwordHash`。
+Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，Agent 端点才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。页面端 `/api/images` SSE 另看 `agent_streaming.page_sse.auth`；当其声明 `required=true` 时，form-data 必须包含 `passwordHash`。`GPT_IMAGE_AGENT_TOKEN` 不能替代页面 SSE 表单鉴权。
 subagent 或自动化任务如果用户指定 Space、云服务或内网服务，调用 `generate-image.mjs`、`edit-image.mjs`、`batch-images.mjs`、`diagnose-request.mjs` 或 `npm run agent:doctor -- --base-url <url>` 时显式传服务地址；不要依赖默认 localhost。
-Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端配置 `AGENT_API_TOKEN` 后，本机 Agent 仍必须通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；不要把 token 写进仓库、README、任务 JSONL、manifest、命令参数或日志。仓库根目录的 `.env.agent.local.example` 只作私有本机配置模板，真实 `.env.agent.local` 不入库。
+Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端配置 `AGENT_API_TOKEN` 后，本机 Agent 仍必须通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`，shell 环境变量优先。不要把 token 写进仓库、README、任务 JSONL、manifest、命令参数或日志。仓库根目录的 `.env.agent.local.example` 只作私有本机配置模板，真实 `.env.agent.local` 不入库。
 排查环境配置时不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。Codex 会话日志会持久保存命令输出；优先运行仓库脚本 `npm run env:summary`，或在命令中先把 `API_KEY`、`TOKEN`、`PASSWORD`、`SECRET` 值替换为 `<redacted>`。
 
 ```text
@@ -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`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。失败摘要包含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。回答耗时问题时优先读取 `summary.elapsed_ms`；服务端返回 timing 时同时读取 `summary.server_elapsed_ms`。
+真实执行输出会包含机器可读 `summary`。成功摘要包含 `ok`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`cached`、`started_at`、`completed_at`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host`、脱敏 `request_headers` 和 `next_action`。失败摘要也稳定包含空数组或 `null` 形式的产物、路由和渠道字段，便于 subagent 按同一模板汇报。失败摘要还包含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。回答耗时问题时优先读取 `summary.elapsed_ms`；需要区分脚本等待和上游耗时时读取 `summary.elapsed_breakdown`。
 
 生成脚本参数：
 
@@ -546,8 +546,10 @@ node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.h
 | `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
 | `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
 | `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
-| `agent_auth_process.has_token` | `first-run --json` | 当前 shell 是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
-| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；存在不代表当前 shell 已加载。 |
+| `agent_auth_process.has_token` | `first-run --json` | 当前进程是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
+| `page_sse_auth_available_to_process` | `first-run --json` | 目标服务要求页面 SSE `passwordHash` 时，当前进程是否已加载 `GPT_IMAGE_APP_PASSWORD_HASH`。 |
+| `summary.page_sse_auth_ready` | `agent:doctor` | 页面 SSE 鉴权是否已满足；为 `false` 时不要运行 `--page-sse` 真实计费请求。 |
+| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；Agent CLI 默认从当前仓库根目录读取该文件。 |
 | `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
 | `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
 

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

@@ -10,6 +10,7 @@ import {
   readMaxImageEdge,
   readOptionValue,
   readPartialImages,
+  loadPrivateAgentEnvFile,
   resolvePlaygroundBaseUrl,
   resolveSameOriginUrl,
   validateAgentEditRequestAgainstCapabilities,
@@ -101,6 +102,7 @@ const TASK_FIELDS = new Set([
   ...EDIT_ONLY_FIELDS
 ]);
 
+loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 

skills/gpt-image-playground-agent/scripts/diagnose-request.mjs

@@ -2,9 +2,10 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
-import { errorMessage, readOptionValue, resolvePlaygroundBaseUrl } from './lib/script-utils.mjs';
+import { errorMessage, loadPrivateAgentEnvFile, readOptionValue, resolvePlaygroundBaseUrl } from './lib/script-utils.mjs';
 
 const MAX_CLIENT_REQUEST_IDS = 50;
+loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 

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

@@ -12,6 +12,7 @@ import {
   readMaxImageEdge,
   readOptionValue,
   readPartialImages,
+  loadPrivateAgentEnvFile,
   resolvePlaygroundBaseUrl,
   sleep,
   validateAgentEditRequestAgainstCapabilities
@@ -49,6 +50,7 @@ const THINKING_VALUES = new Set(['minimal', 'none', 'low', 'medium', 'high', 'xh
 const DEFAULT_PAGE_OUTPUT_FORMAT = 'webp';
 const DEFAULT_PAGE_OUTPUT_COMPRESSION = 100;
 
+loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 const contractCheck = process.env.GPT_IMAGE_AGENT_CONTRACT_CHECK === '1' || process.argv.includes('--contract-check');

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

@@ -10,6 +10,7 @@ import {
     readMaxImageEdge,
     readOptionValue,
     readPartialImages,
+    loadPrivateAgentEnvFile,
     resolvePlaygroundBaseUrl,
     resolveSameOriginUrl,
     sleep,
@@ -63,6 +64,7 @@ const GENERATE_PRESETS = {
         '2'
     ]
 };
+loadPrivateAgentEnvFile();
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
 const passwordHash = process.env.GPT_IMAGE_APP_PASSWORD_HASH || '';
 const contractCheck = process.env.GPT_IMAGE_AGENT_CONTRACT_CHECK === '1' || process.argv.includes('--contract-check');
@@ -187,8 +189,9 @@ try {
             console.log(
                 JSON.stringify(
                     buildSuccessOutput(formatPageSseOutput(result), {
-                        transport: 'page_sse',
-                        endpoint: PAGE_SSE_ENDPOINT
+                        ...buildPageSseSummaryRouting(),
+                        fallback_endpoint: AGENT_ENDPOINTS.generate,
+                        fallback_mode: 'manual_after_diagnosis'
                     }, completeScriptTiming(scriptTiming)),
                     null,
                     2
@@ -696,7 +699,7 @@ function assertPageSseReady(capabilitiesValue) {
     if (pageSse?.auth?.required === true && !passwordHash) {
         throw createScriptError(
             'page_sse_auth_required',
-            '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
+            '页面 SSE 路径需要表单字段 passwordHash；请在本机私有 .env.agent.local 中设置 GPT_IMAGE_APP_PASSWORD_HASH，或导出该环境变量后重试。只有 GPT_IMAGE_AGENT_TOKEN 不能用于页面 SSE 表单鉴权。'
         );
     }
 }
@@ -1000,13 +1003,23 @@ function buildPageSseFailureOutput(error, timing = completeScriptTiming(scriptTi
 
 function buildPageSseRouting(fallbackMode) {
     return {
-        transport: 'page_sse',
-        endpoint: PAGE_SSE_ENDPOINT,
+        ...buildPageSseSummaryRouting(),
         fallback_endpoint: AGENT_ENDPOINTS.generate,
         fallback_mode: fallbackMode
     };
 }
 
+function buildPageSseSummaryRouting() {
+    return {
+        transport: 'page_sse',
+        endpoint: PAGE_SSE_ENDPOINT,
+        route_mode: 'page_sse',
+        image_backend: normalizeImageBackendForPage(requestBody?.image_backend),
+        stream_mode: requestBody?.stream_mode || null,
+        streaming_strategy: requestBody?.streaming_strategy || null
+    };
+}
+
 function buildPageSseScriptFailure(error, diagnostics, timing) {
     const output = {
         ok: false,

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

@@ -21,7 +21,7 @@ export function assertPageSseReady({ capabilities, passwordHash, idempotencyKey
   if (pageSse?.auth?.required === true && !passwordHash) {
     throw createPageSseScriptError(
       'page_sse_auth_required',
-      '页面 SSE 路径需要表单字段 passwordHash；请设置 GPT_IMAGE_APP_PASSWORD_HASH 后重试。'
+      '页面 SSE 路径需要表单字段 passwordHash；请在本机私有 .env.agent.local 中设置 GPT_IMAGE_APP_PASSWORD_HASH，或导出该环境变量后重试。只有 GPT_IMAGE_AGENT_TOKEN 不能用于页面 SSE 表单鉴权。'
     );
   }
   const maxLength = readPageSseClientRequestIdMaxLength(capabilities);

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

@@ -17,29 +17,30 @@ export function buildSuccessSummary({ result, routing, timing, idempotencyKey, b
   const serverTiming = readObject(result?.timing);
   const execution = readObject(result?.execution);
   const images = Array.isArray(result?.images) ? result.images : [];
-  const contentUrls = images
-    .map((image) => image?.absolute_content_url || image?.content_url || image?.absolute_path || image?.path)
-    .filter((value) => typeof value === 'string' && value);
-  return compactObject({
+  const timingSummary = buildTimingSummary({ clientTiming: timing, serverTiming });
+  return stableSummary({
     ok: true,
     billable,
-    request_id: readString(result?.request_id),
+    request_id: readString(result?.request_id) || null,
     idempotency_key: readString(result?.idempotency_key) || idempotencyKey,
     artifact_ids: images.map((image) => image?.id).filter((value) => typeof value === 'string' && value),
-    content_urls: contentUrls,
+    content_urls: readImageUrls(images, ['content_url', 'path']),
+    absolute_content_urls: readImageUrls(images, ['absolute_content_url', 'absolute_path']),
     cached: typeof result?.cached === 'boolean' ? result.cached : undefined,
-    started_at: readString(serverTiming?.started_at) || timing?.started_at,
-    completed_at: readString(serverTiming?.completed_at) || timing?.completed_at,
-    elapsed_ms: readNonNegativeNumber(serverTiming?.elapsed_ms) ?? timing?.elapsed_ms,
-    server_elapsed_ms: readNonNegativeNumber(serverTiming?.server_elapsed_ms),
+    started_at: timingSummary.started_at,
+    completed_at: timingSummary.completed_at,
+    elapsed_ms: timingSummary.elapsed_ms,
+    server_elapsed_ms: timingSummary.server_elapsed_ms,
+    elapsed_source: timingSummary.elapsed_source,
+    elapsed_breakdown: timingSummary.elapsed_breakdown,
     transport: readString(execution?.transport) || readString(routing?.transport),
     endpoint: readString(execution?.endpoint) || readString(routing?.endpoint),
-    route_mode: readString(execution?.route_mode),
-    image_backend: readString(execution?.image_backend),
-    stream_mode: readString(execution?.stream_mode),
-    streaming_strategy: readString(execution?.streaming_strategy),
-    selected_channel_id: readString(execution?.selected_channel_id),
-    upstream_host: readString(execution?.upstream_host),
+    route_mode: readString(execution?.route_mode) || readRouteMode(routing),
+    image_backend: readString(execution?.image_backend) || readString(routing?.image_backend) || null,
+    stream_mode: readString(execution?.stream_mode) || readString(routing?.stream_mode) || null,
+    streaming_strategy: readString(execution?.streaming_strategy) || readString(routing?.streaming_strategy) || null,
+    selected_channel_id: readString(execution?.selected_channel_id) || null,
+    upstream_host: readString(execution?.upstream_host) || null,
     request_headers: readObject(execution?.request_headers),
     retryable: false,
     next_action: nextAction || 'done'
@@ -50,18 +51,29 @@ export function buildFailureSummary({ errorBody, routing, timing, idempotencyKey
   const error = readObject(errorBody?.error) || readObject(errorBody);
   const errorMessage = readString(error?.message) || readString(errorBody?.error);
   const diagnostics = readObject(error?.diagnostics);
-  return compactObject({
+  const timingSummary = buildTimingSummary({ clientTiming: timing, diagnostics });
+  return stableSummary({
     ok: false,
     billable,
-    request_id: readString(error?.request_id),
+    request_id: readString(error?.request_id) || null,
     idempotency_key: idempotencyKey,
-    started_at: timing?.started_at,
-    completed_at: timing?.completed_at,
-    elapsed_ms: timing?.elapsed_ms,
+    artifact_ids: [],
+    content_urls: [],
+    absolute_content_urls: [],
+    started_at: timingSummary.started_at,
+    completed_at: timingSummary.completed_at,
+    elapsed_ms: timingSummary.elapsed_ms,
+    server_elapsed_ms: timingSummary.server_elapsed_ms,
+    elapsed_source: timingSummary.elapsed_source,
+    elapsed_breakdown: timingSummary.elapsed_breakdown,
     transport: readString(routing?.transport),
     endpoint: readString(routing?.endpoint),
-    selected_channel_id: readString(diagnostics?.selected_channel_id),
-    upstream_host: readString(diagnostics?.upstream_host),
+    route_mode: readRouteMode(routing),
+    image_backend: readString(routing?.image_backend) || null,
+    stream_mode: readString(routing?.stream_mode) || null,
+    streaming_strategy: readString(routing?.streaming_strategy) || null,
+    selected_channel_id: readString(diagnostics?.selected_channel_id) || null,
+    upstream_host: readString(diagnostics?.upstream_host) || null,
     transport_error_kind: readString(diagnostics?.transport_error_kind),
     retryable: typeof error?.retryable === 'boolean' ? error.retryable : undefined,
     retry_after_seconds: readNonNegativeNumber(errorBody?.retry_after ?? diagnostics?.retry_after_seconds),
@@ -84,6 +96,28 @@ function buildFailureNextAction(error) {
   return 'diagnose_then_new_idempotency_key';
 }
 
+function stableSummary(value) {
+  return {
+    ...value,
+    request_id: value.request_id ?? null,
+    idempotency_key: value.idempotency_key ?? null,
+    artifact_ids: Array.isArray(value.artifact_ids) ? value.artifact_ids : [],
+    content_urls: Array.isArray(value.content_urls) ? value.content_urls : [],
+    absolute_content_urls: Array.isArray(value.absolute_content_urls) ? value.absolute_content_urls : [],
+    route_mode: value.route_mode ?? null,
+    image_backend: value.image_backend ?? null,
+    stream_mode: value.stream_mode ?? null,
+    streaming_strategy: value.streaming_strategy ?? null,
+    selected_channel_id: value.selected_channel_id ?? null,
+    upstream_host: value.upstream_host ?? null,
+    transport_error_kind: value.transport_error_kind ?? null,
+    retry_after_ms: value.retry_after_ms ?? null,
+    retry_after_seconds: value.retry_after_seconds ?? null,
+    cooldown_until: value.cooldown_until ?? null,
+    cooldown_target: value.cooldown_target ?? null
+  };
+}
+
 function compactObject(value) {
   return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
@@ -100,3 +134,51 @@ function readNonNegativeNumber(value) {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
   return Math.round(value);
 }
+
+function readRouteMode(routing) {
+  if (typeof routing?.route_mode === 'string' && routing.route_mode) return routing.route_mode;
+  if (routing?.transport === 'page_sse') return 'page_sse';
+  if (routing?.transport === 'agent_job_polling') return 'job';
+  if (routing?.transport === 'agent_json') return 'agent';
+  return undefined;
+}
+
+function readImageUrls(images, fields) {
+  return images
+    .map((image) => {
+      for (const field of fields) {
+        if (typeof image?.[field] === 'string' && image[field]) return image[field];
+      }
+      return undefined;
+    })
+    .filter((value) => typeof value === 'string' && value);
+}
+
+function buildTimingSummary({ clientTiming, serverTiming, diagnostics }) {
+  const serverTimingElapsedMs = readNonNegativeNumber(serverTiming?.elapsed_ms);
+  const diagnosticsElapsedMs = readNonNegativeNumber(diagnostics?.elapsed_ms);
+  const serverElapsedMs = readNonNegativeNumber(serverTiming?.server_elapsed_ms ?? serverTimingElapsedMs ?? diagnosticsElapsedMs);
+  const clientElapsedMs = readNonNegativeNumber(clientTiming?.elapsed_ms);
+  const elapsedMs = serverTimingElapsedMs ?? diagnosticsElapsedMs ?? clientElapsedMs;
+  const elapsedSource =
+    serverTimingElapsedMs !== undefined || diagnosticsElapsedMs !== undefined ? 'server_timing' : 'client_script';
+  const summary = compactObject({
+    started_at: readString(serverTiming?.started_at) || clientTiming?.started_at,
+    completed_at: readString(serverTiming?.completed_at) || clientTiming?.completed_at,
+    elapsed_ms: elapsedMs,
+    server_elapsed_ms: serverElapsedMs,
+    elapsed_source: elapsedSource,
+    elapsed_breakdown: buildElapsedBreakdown(clientElapsedMs, serverElapsedMs)
+  });
+  return summary;
+}
+
+function buildElapsedBreakdown(clientElapsedMs, serverElapsedMs) {
+  if (clientElapsedMs === undefined && serverElapsedMs === undefined) return undefined;
+  return compactObject({
+    client_script_ms: clientElapsedMs,
+    upstream_or_server_ms: serverElapsedMs,
+    client_overhead_ms:
+      clientElapsedMs !== undefined && serverElapsedMs !== undefined ? Math.max(0, clientElapsedMs - serverElapsedMs) : undefined
+  });
+}

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

@@ -1,8 +1,39 @@
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+
 const MAX_RETRY_AFTER_SECONDS = 60;
 const DIGITS_PATTERN = /^\d+$/;
 const IMAGE_SIZE_PATTERN = /^(\d+)x(\d+)$/;
 const LEGACY_IMAGE_SIZES = new Set(['auto', '1024x1024', '1536x1024', '1024x1536']);
 export const DEFAULT_PLAYGROUND_BASE_URL = 'http://localhost:4783';
+const DEFAULT_PRIVATE_AGENT_ENV_FILE = '.env.agent.local';
+const PRIVATE_AGENT_ENV_PREFIX = 'GPT_IMAGE_';
+const DISABLE_PRIVATE_AGENT_ENV_VALUES = new Set(['0', 'false', 'no']);
+
+export function loadPrivateAgentEnvFile(options = {}) {
+  const env = options.env || process.env;
+  if (isPrivateAgentEnvLoadingDisabled(env)) {
+    return { loaded: false, skipped: true, reason: 'disabled_by_env' };
+  }
+  const cwd = options.cwd || process.cwd();
+  const filePath = options.filePath || findPrivateAgentEnvFile(cwd);
+  if (!existsSync(filePath)) {
+    return { loaded: false, skipped: true, reason: 'file_not_found', path: filePath };
+  }
+  const entries = parsePrivateAgentEnvContent(readFileSync(filePath, 'utf8'));
+  const appliedNames = [];
+  for (const { name, value } of entries) {
+    if (!name.startsWith(PRIVATE_AGENT_ENV_PREFIX)) continue;
+    if (env[name] !== undefined) continue;
+    env[name] = value;
+    appliedNames.push(name);
+  }
+  return {
+    loaded: true,
+    path: filePath,
+    applied_names: appliedNames
+  };
+}
 
 export function readOptionValue(argv, index, name) {
   const value = argv[index];
@@ -194,6 +225,75 @@ export function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function isPrivateAgentEnvLoadingDisabled(env) {
+  return DISABLE_PRIVATE_AGENT_ENV_VALUES.has(String(env.GPT_IMAGE_AGENT_LOAD_ENV_FILE || '').trim().toLowerCase());
+}
+
+function findPrivateAgentEnvFile(cwd) {
+  const start = resolve(cwd);
+  let current = start;
+  while (true) {
+    const candidate = join(current, DEFAULT_PRIVATE_AGENT_ENV_FILE);
+    if (existsSync(candidate)) return candidate;
+    if (isPrivateAgentEnvSearchBoundary(current) || dirname(current) === current) {
+      return join(start, DEFAULT_PRIVATE_AGENT_ENV_FILE);
+    }
+    current = dirname(current);
+  }
+}
+
+function isPrivateAgentEnvSearchBoundary(directory) {
+  return existsSync(join(directory, '.git')) || isPlaygroundProjectRoot(directory) || isStandaloneSkillRoot(directory);
+}
+
+function isPlaygroundProjectRoot(directory) {
+  return existsSync(join(directory, 'package.json')) && existsSync(join(directory, 'skills/gpt-image-playground-agent/SKILL.md'));
+}
+
+function isStandaloneSkillRoot(directory) {
+  return (
+    existsSync(join(directory, 'SKILL.md')) &&
+    existsSync(join(directory, 'scripts')) &&
+    !isPlaygroundProjectRoot(dirname(dirname(directory)))
+  );
+}
+
+function parsePrivateAgentEnvContent(content) {
+  const entries = [];
+  for (const line of content.split(/\r?\n/)) {
+    const parsed = parsePrivateAgentEnvLine(line);
+    if (parsed) entries.push(parsed);
+  }
+  return entries;
+}
+
+function parsePrivateAgentEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return undefined;
+  const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+  if (!match) return undefined;
+  return { name: match[1], value: parsePrivateAgentEnvValue(match[2].trim()) };
+}
+
+function parsePrivateAgentEnvValue(value) {
+  if (value.length < 2) return value;
+  if (value.startsWith('"') || value.startsWith("'")) return parseQuotedPrivateAgentEnvValue(value);
+  return stripPrivateAgentEnvComment(value).trim();
+}
+
+function parseQuotedPrivateAgentEnvValue(value) {
+  const quote = value[0];
+  const closeIndex = value.indexOf(quote, 1);
+  if (closeIndex < 0) return value.slice(1);
+  return value.slice(1, closeIndex);
+}
+
+function stripPrivateAgentEnvComment(value) {
+  const index = value.search(/\s#/);
+  if (index < 0) return value;
+  return value.slice(0, index);
+}
+
 function assertPositiveIntegerDimensions(width, height, label) {
   if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
     throw new Error(`${label} 的宽度和高度必须是正数。`);

skills/gpt-image-playground-agent/scripts/probe-upstream-image.mjs

@@ -4,6 +4,7 @@ import tls from 'node:tls';
 import {
   errorMessage,
   assertValidImageSizeForModel,
+  loadPrivateAgentEnvFile,
   normalizeBaseUrl,
   normalizeOutputFormat,
   readConfiguredPositiveInteger,
@@ -16,6 +17,7 @@ const DEFAULT_USER_AGENT = 'gpt-image-playground/probe';
 const OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp']);
 const DEFAULT_OUTPUT_FORMAT = 'webp';
 const DEFAULT_OUTPUT_COMPRESSION = 100;
+loadPrivateAgentEnvFile();
 const scriptTiming = startScriptTiming();
 let options;
 try {