Deploy 96f3dcf to Docker Space

Source: MisonL/gpt-image-playground-customer@96f3dcf3b00cdc76478bfb8c3de537c0af3b636a

.env.agent.local.example

@@ -0,0 +1,9 @@
+# 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
+
+GPT_IMAGE_PLAYGROUND_URL=http://localhost:4783
+GPT_IMAGE_AGENT_TOKEN=
+GPT_IMAGE_APP_PASSWORD_HASH=

.gitignore

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

README.md

@@ -17,6 +17,26 @@ app_port: 4783
 
 ## 快速开始
 
+第一次配置或换机器后，先跑只读就绪检查。它不会写配置、不会输出密钥、不会触发真实生图：
+
+```bash
+npm run first-run
+```
+
+该命令默认输出中文摘要；给 Agent 或脚本消费时加 `--json`。它会检查 Node、依赖、`.env.local` / `.env.agent.local` 摘要、默认本地服务 `http://localhost:4783`、Agent capabilities 和下一步动作。检查公网或 Space 服务时显式传地址：
+
+```bash
+npm run first-run -- --base-url https://your-space.hf.space
+npm run first-run -- --json --base-url https://your-space.hf.space
+```
+
+首次配置最短路径：
+
+1. 运行 `npm install`。
+2. 启动服务：本地开发用 `npm run dev`，Docker 用 `docker compose up -d --build --remove-orphans`。
+3. 运行 `npm run first-run` 看中文摘要；如果要检查 Space 或内网服务，使用 `npm run first-run -- --base-url <url>`。
+4. 如果 Agent API 需要鉴权，复制 `.env.agent.local.example` 为 `.env.agent.local`，填入本机私有 token 后加载到 shell，再运行 `npm run first-run` 或 skill 脚本。
+
 推荐 Docker：
 
 ```bash
@@ -172,12 +192,20 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 AI Agent 集成时优先调用 skill 内置脚本，而不是临时手写 fetch、curl 或表单提交逻辑。脚本会先读取 capabilities，自动处理鉴权、幂等键、路由选择、超时、产物 URL 和结构化失败摘要。
 
+交互式任务中，Agent 应先定位服务地址：用户明确提供 URL 时直接使用该 URL；否则先检查 `GPT_IMAGE_PLAYGROUND_URL`，再探测默认本地地址 `http://localhost:4783`。如果只发现环境变量或本地服务，先向用户确认是否使用；用户提供其他地址时，以用户提供的地址为准。非交互式任务无法确认时，按同一顺序自动选择，并在输出里说明地址来源。
+
+新环境或不确定服务地址时先运行 `npm run first-run`。它会只读报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程是否拿到 Agent 鉴权，以及 `.env.agent.local` 是否存在私有鉴权配置；如果 token 只在私有 env 文件中，先把它加载到 shell，再运行 skill 脚本。
+
+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` 提交或粘到任务日志。
+
 1. 只读检查当前服务能力，不触发计费：
 
 ```bash
-GPT_IMAGE_PLAYGROUND_URL=http://localhost:4783 \
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
   --contract-check \
+  --base-url http://localhost:4783 \
   "capability check"
 ```
 
@@ -185,6 +213,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
+  --base-url http://localhost:4783 \
   --size 1024x1024 \
   --quality high \
   --response-mode path \
@@ -196,6 +225,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
+  --base-url http://localhost:4783 \
   --allow-billable \
   --timeout-ms 420000 \
   --size 1024x1024 \
@@ -209,6 +239,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/edit-image.mjs \
+  --base-url http://localhost:4783 \
   --image ./source.png \
   --format webp \
   --output-compression 100 \
@@ -226,6 +257,7 @@ node skills/gpt-image-playground-agent/scripts/edit-image.mjs \
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/batch-images.mjs \
+  --base-url http://localhost:4783 \
   --input tasks.jsonl \
   --manifest runs/product-set.manifest.jsonl \
   --resume \
@@ -247,6 +279,7 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
+  --base-url http://localhost:4783 \
   --idempotency-key agent-demo-generate-001
 ```
 
@@ -254,18 +287,41 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 
 ```bash
 node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
+  --base-url http://localhost:4783 \
   --client-request-id agent-demo-edit-001
 ```
 
+远��� Space、云服务或内网服务必须显式固定目标地址，避免误查本机默认服务：
+
+```bash
+node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
+  --base-url https://your-space.hf.space \
+  --idempotency-key agent-demo-generate-001
+```
+
+首次配置和诊断输出字段速查：
+
+| 字段 | 出现位置 | 判断口径 |
+| --- | --- | --- |
+| `service_base_url` / `verification_scope.service_base_url` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 当前脚本准备访问的 Playground 服务地址。 |
+| `service_base_url_source` / `verification_scope.service_base_url_source` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | `user_provided` 表示用户或命令行明确指定；`GPT_IMAGE_PLAYGROUND_URL` 表示来自环境变量；`default_local_probe` 表示默认本地探测。 |
+| `interactive_confirmation_required` / `verification_scope.interactive_confirmation_required` | `first-run`、`agent:doctor`、诊断脚本为顶层；skill 脚本 dry-run 在 `verification_scope` 下 | 交互式任务中为 `true` 时，应先向用户确认是否使用该地址再发起真实请求。 |
+| `agent_auth_process.has_token` | `first-run --json` | 当前 shell 是否已经拿到 `GPT_IMAGE_AGENT_TOKEN`。 |
+| `private_agent_env.exists` | `first-run --json` | 本机是否存在 `.env.agent.local` 私有配置；存在不代表当前 shell 已加载。 |
+| `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
+| `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
+
 常用环境变量：
 
 | 变量 | 用途 |
 | --- | --- |
-| `GPT_IMAGE_PLAYGROUND_URL` | 指向本机、内网或公网部署地址；默认尝试 `http://localhost:4783`。 |
+| `GPT_IMAGE_PLAYGROUND_URL` | 指向本机、内网或公网部署地址；未设置时脚本默认尝试 `http://localhost:4783`。交互式任务中，自动发现到本地服务后应先向用户确认。 |
 | `GPT_IMAGE_AGENT_TOKEN` | Agent Bearer token，对应服务端 `AGENT_API_TOKEN`。 |
 | `GPT_IMAGE_APP_PASSWORD_HASH` | 使用页面访问码部署时的访问码哈希；页面 SSE 会作为 `passwordHash` 表单字段发送。 |
 | `GPT_IMAGE_AGENT_IDEMPOTENCY_KEY` | 跨脚本进程复用同一业务操作的幂等键。 |
 
+Hugging Face Space Secrets 只能写入和列出名称，不能从 CLI 读回 secret 值。远端 Space 配置了 `AGENT_API_TOKEN` 后，本机 Agent 仍需要通过不入库的 shell 环境、keychain 或本地私有 env 文件注入 `GPT_IMAGE_AGENT_TOKEN`；不要把 token 写进 README、任务 JSONL、manifest 或命令日志。仓库提供 `.env.agent.local.example` 作为私有本机配置模板。
+
 接口边界：
 
 - `/api/agent/*` 是自动化机器契约，返回最终 JSON，不向客户端返回 SSE。
@@ -303,6 +359,18 @@ docker compose up -d --build --remove-orphans
 npm run deploy:local
 ```
 
+本仓库的 Compose 服务只挂载 `generated-images/`。不要用 `docker run -v "$PWD:/workspace"` 启动本地图片上游 fixture；这会把 `.git/`、`node_modules/` 和 `.next/` 暴露给 Docker Desktop 文件共享层，可能触发文件事件风暴。本地 fixture gate 使用进程内服务：
+
+```bash
+npm run smoke:image-upstream-local
+```
+
+如本机遗留了整仓挂载的 fixture 容器，可执行：
+
+```bash
+npm run docker:cleanup-fixtures
+```
+
 常见部署模式：
 
 | 模式 | 命令或配置 | 适用场景 |
@@ -332,9 +400,11 @@ Hugging Face Space 免费层部署见 [docs/deployment/huggingface-space-free.md
 | `npm run lint:scripts` | 检查仓库脚本和 skill 脚本语法。 |
 | `npm run version:check` | 检查版本、README badge 和 CHANGELOG 口径。 |
 | `npm run verify` | 运行提交前基线。 |
+| `npm run docker:cleanup-fixtures` | 清理遗留的整仓挂载 Docker fixture 容器。 |
+| `npm run first-run` | 首次配置就绪检查，默认中文摘要；加 `-- --json` 输出机器可读 JSON。 |
 | `npm run status` | 只读查看 git、Node、部署目标和 Agent 摘要。 |
 | `npm run doctor` | 运行本机和部署诊断。 |
-| `npm run agent:doctor` | 非计费 Agent 分层诊断。 |
+| `npm run agent:doctor` | 非计费 Agent 分层诊断；支持 `-- --base-url <url>`。 |
 | `npm run deploy:space` | 上传干净 git HEAD 到固定 HF Space。 |
 
 真实上游 smoke 默认不会触发计费；需要真实生图时必须显式传入 `--allow-billable`。

package.json

@@ -12,12 +12,14 @@
     "test:scripts": "node --test \"scripts/**/*.test.mjs\"",
     "test:postgres": "node scripts/test-postgres-live.mjs",
     "version:check": "node scripts/check-version-metadata.mjs",
+    "first-run": "node scripts/first-run.mjs",
     "doctor": "node scripts/doctor.mjs",
     "status": "node scripts/status.mjs",
     "env:summary": "node scripts/env-summary.mjs",
     "verify": "node scripts/verify.mjs",
     "deploy:local": "node scripts/deploy-local.mjs",
     "deploy:space": "npm run deploy:hf-space",
+    "docker:cleanup-fixtures": "node scripts/cleanup-docker-fixtures.mjs",
     "agent:doctor": "node scripts/agent-doctor.mjs",
     "deploy:hf-space": "node scripts/deploy-hf-space.mjs",
     "doctor:hf-space": "node scripts/doctor-hf-space.mjs",

scripts/agent-doctor.mjs

@@ -2,22 +2,30 @@
 
 import { fileURLToPath } from 'node:url';
 
-import { isMainModule, parseJsonPayload, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
+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';
 
 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 DEFAULT_BASE_URL = 'http://localhost:4783';
 
 export function buildAgentDoctorArgs() {
     return [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000', 'contract check'];
 }
 
+export function buildAgentDoctorContractArgs(baseUrl) {
+    const args = [GENERATE_SCRIPT, '--contract-check', '--timeout-ms', '60000'];
+    if (baseUrl) args.push('--base-url', baseUrl);
+    args.push('contract check');
+    return args;
+}
+
 function parseArgs(argv) {
     const parsed = {
         help: false,
         allowBillable: false,
         timeoutMs: 60_000,
+        baseUrl: undefined,
         editImage: undefined
     };
     for (let index = 0; index < argv.length; index += 1) {
@@ -25,23 +33,30 @@ function parseArgs(argv) {
         if (arg === '--help' || arg === '-h') parsed.help = true;
         else if (arg === '--allow-billable') parsed.allowBillable = true;
         else if (arg === '--timeout-ms') parsed.timeoutMs = readPositiveInteger(readOptionValue(argv, (index += 1), arg), '--timeout-ms');
+        else if (arg === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
         else if (arg === '--edit-image') parsed.editImage = readOptionValue(argv, (index += 1), arg);
-        else throw new Error(`Unknown option: ${arg}`);
+        else throw new Error(`未知参数：${arg}`);
     }
     return parsed;
 }
 
 function printHelp() {
-    console.log(`Usage:
+    console.log(`用法：
   npm run agent:doctor
-  npm run agent:doctor -- --allow-billable --edit-image /path/to/reference.png
+  npm run agent:doctor -- --base-url https://your-space.hf.space --allow-billable --edit-image /path/to/reference.png
+
+环境变量：
+  GPT_IMAGE_PLAYGROUND_URL       服务基础地址，默认 http://localhost:4783。
+  GPT_IMAGE_AGENT_TOKEN          capabilities 需要 bearer 鉴权时使用。
+  GPT_IMAGE_APP_PASSWORD_HASH    capabilities 需要页面密码鉴权时使用。
 
-Environment:
-  GPT_IMAGE_PLAYGROUND_URL       Service base URL, defaults to http://localhost:4783.
-  GPT_IMAGE_AGENT_TOKEN          Bearer token when capabilities require bearer auth.
-  GPT_IMAGE_APP_PASSWORD_HASH    Password hash when capabilities require page password auth.
+选项：
+  --base-url      显式服务地址，优先于 GPT_IMAGE_PLAYGROUND_URL 和本地探测。
+  --timeout-ms    HTTP 探测和 smoke 超时，默认 60000。
+  --edit-image    真实 edit smoke 使用的参考图。
+  --allow-billable 显式允许真实 1K/2K smoke 请求。
 
-By default agent:doctor is read-only and non-billable. Billable generate/edit smoke checks require --allow-billable.`);
+agent:doctor 默认只读、非计费。真实 generate/edit smoke 必须显式添加 --allow-billable。`);
 }
 
 async function main() {
@@ -51,11 +66,12 @@ async function main() {
         return;
     }
 
-    const baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || DEFAULT_BASE_URL);
-    const contract = runContractCheck();
+    const baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+    const baseUrl = baseUrlInfo.baseUrl;
+    const contract = runContractCheck(baseUrl);
     const capabilities = await readJsonLayer('capabilities', `${baseUrl}/api/agent/capabilities`, options.timeoutMs);
     const runtime = await readJsonLayer('runtime', `${baseUrl}/api/runtime-capabilities`, options.timeoutMs);
-    const smoke = options.allowBillable ? runBillableSmoke(options) : buildSkippedSmoke(options);
+    const smoke = options.allowBillable ? runBillableSmoke(options, baseUrl) : buildSkippedSmoke(options);
     const layers = buildLayers({ capabilities, runtime, contract, smoke });
 
     printJson({
@@ -63,14 +79,17 @@ async function main() {
         command: 'agent:doctor',
         billable: options.allowBillable,
         base_url: redactBaseUrl(baseUrl),
+        service_base_url: redactBaseUrl(baseUrl),
+        service_base_url_source: baseUrlInfo.source,
+        interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
         layers,
         summary: buildSummary({ capabilities, runtime, contract, smoke })
     });
     if (layers.some((layer) => !layer.ok && !layer.skipped)) process.exit(1);
 }
 
-function runContractCheck() {
-    const result = runCommand(process.execPath, buildAgentDoctorArgs(), {
+function runContractCheck(baseUrl) {
+    const result = runCommand(process.execPath, buildAgentDoctorContractArgs(baseUrl), {
         env: { ...process.env, GPT_IMAGE_AGENT_CONTRACT_CHECK: '1' },
         timeoutMs: AGENT_DOCTOR_TIMEOUT_MS
     });
@@ -120,10 +139,12 @@ function buildSkippedSmoke(options) {
     };
 }
 
-function runBillableSmoke(options) {
+function runBillableSmoke(options, baseUrl) {
     const checks = [
         runSmokeCommand('generate_1k', [
             GENERATE_SCRIPT,
+            '--base-url',
+            baseUrl,
             '--allow-billable',
             '--agent',
             '--timeout-ms',
@@ -141,6 +162,8 @@ function runBillableSmoke(options) {
         checks.push(
             runSmokeCommand('edit_1k', [
                 EDIT_SCRIPT,
+                '--base-url',
+                baseUrl,
                 '--allow-billable',
                 '--agent',
                 '--timeout-ms',
@@ -158,6 +181,8 @@ function runBillableSmoke(options) {
         checks.push(
             runSmokeCommand('page_sse_edit_2k', [
                 EDIT_SCRIPT,
+                '--base-url',
+                baseUrl,
                 '--allow-billable',
                 '--page-sse',
                 '--timeout-ms',
@@ -296,14 +321,14 @@ function authHeaders() {
 
 function readOptionValue(argv, index, name) {
     const value = argv[index];
-    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value.`);
+    if (!value || value.startsWith('--')) throw new Error(`${name} 需要参数值。`);
     return value;
 }
 
 function readPositiveInteger(value, name) {
-    if (!/^\d+$/.test(String(value))) throw new Error(`${name} must be a positive integer.`);
+    if (!/^\d+$/.test(String(value))) throw new Error(`${name} 必须是正整数。`);
     const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${name} must be a positive integer.`);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${name} 必须是正整数。`);
     return parsed;
 }
 
@@ -319,11 +344,6 @@ function normalizeBaseUrl(value) {
     return normalized;
 }
 
-function redactBaseUrl(value) {
-    const parsed = new URL(value);
-    return `${parsed.protocol}//${parsed.host}`;
-}
-
 function safePathname(url) {
     try {
         return new URL(url).pathname;

scripts/agent-skill-scripts.test.mjs

@@ -155,6 +155,46 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stdout.trim(), '');
     });
 
+    it('lets explicit base-url override the environment service URL in dry-run output', () => {
+        const generateResult = runSkillScript(
+            'generate-image.mjs',
+            ['--base-url', 'https://space.example.test/', '--size', '1024x1024', 'prompt'],
+            { GPT_IMAGE_PLAYGROUND_URL: 'http://localhost:4783' }
+        );
+        assert.equal(generateResult.status, 0);
+        const generateBody = JSON.parse(generateResult.stdout);
+        assert.equal(generateBody.verification_scope.service_base_url, 'https://space.example.test');
+        assert.equal(generateBody.verification_scope.service_base_url_source, 'user_provided');
+        assert.equal(generateBody.verification_scope.interactive_confirmation_required, false);
+
+        const editResult = runSkillScript(
+            'edit-image.mjs',
+            ['--base-url', 'https://space.example.test/', '--image', '/tmp/source.png', 'prompt'],
+            { GPT_IMAGE_PLAYGROUND_URL: 'http://localhost:4783' }
+        );
+        assert.equal(editResult.status, 0);
+        const editBody = JSON.parse(editResult.stdout);
+        assert.equal(editBody.verification_scope.service_base_url, 'https://space.example.test');
+        assert.equal(editBody.verification_scope.service_base_url_source, 'user_provided');
+
+        const tempRoot = mkdtempSync(join(tmpdir(), 'batch-base-url-'));
+        try {
+            const inputPath = join(tempRoot, 'tasks.jsonl');
+            writeFileSync(inputPath, JSON.stringify({ id: 'first', prompt: 'prompt' }));
+            const batchResult = runSkillScript(
+                'batch-images.mjs',
+                ['--base-url', 'https://space.example.test/', '--input', inputPath],
+                { GPT_IMAGE_PLAYGROUND_URL: 'http://localhost:4783' }
+            );
+            assert.equal(batchResult.status, 0);
+            const batchBody = JSON.parse(batchResult.stdout);
+            assert.equal(batchBody.verification_scope.service_base_url, 'https://space.example.test');
+            assert.equal(batchBody.verification_scope.service_base_url_source, 'user_provided');
+        } finally {
+            rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+
     it('rejects upstream probe base URLs with embedded credentials before network checks', () => {
         const result = runSkillScript('probe-upstream-image.mjs', [
             '--base-url',
@@ -240,6 +280,10 @@ describe('Agent skill script argument validation', () => {
         const body = JSON.parse(result.stdout);
         assert.equal(body.dry_run, true);
         assert.equal(body.billable, false);
+        assert.equal(body.verification_scope.mode, 'local_planning_only');
+        assert.equal(body.verification_scope.remote_capabilities_verified, false);
+        assert.equal(body.verification_scope.runtime_capacity_verified, false);
+        assert.equal(body.verification_scope.auth_verified, false);
         assert.equal(body.request.output_format, 'webp');
         assert.equal(body.request.output_compression, 100);
         assert.equal(result.stderr.trim(), '');
@@ -310,6 +354,10 @@ describe('Agent skill script argument validation', () => {
         assert.equal(body.request.stream_mode, 'auto');
         assert.equal(body.request.streaming_strategy, 'force-sse');
         assert.equal(body.request.partial_images, 2);
+        assert.equal(body.verification_scope.mode, 'local_planning_only');
+        assert.equal(body.verification_scope.remote_capabilities_verified, false);
+        assert.equal(body.verification_scope.runtime_capacity_verified, false);
+        assert.equal(body.verification_scope.auth_verified, false);
         assert.equal(result.stderr.trim(), '');
     });
 
@@ -2500,6 +2548,29 @@ describe('Agent skill script argument validation', () => {
         assert.deepEqual(matches, []);
     });
 
+    it('keeps skill frontmatter valid without requiring Python YAML tooling', () => {
+        const skillText = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8');
+        const match = skillText.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        assert.ok(match, 'SKILL.md must start with YAML frontmatter');
+
+        const frontmatter = Object.fromEntries(
+            match[1]
+                .split(/\r?\n/)
+                .filter(Boolean)
+                .map((line) => {
+                    const separator = line.indexOf(':');
+                    assert.ok(separator > 0, `invalid frontmatter line: ${line}`);
+                    return [line.slice(0, separator).trim(), line.slice(separator + 1).trim()];
+                })
+        );
+
+        assert.deepEqual(Object.keys(frontmatter).sort(), ['description', 'name']);
+        assert.match(frontmatter.name, /^[a-z0-9-]+$/);
+        assert.ok(frontmatter.description.length > 0);
+        assert.ok(frontmatter.description.length <= 1024);
+        assert.doesNotMatch(frontmatter.description, /[<>]/);
+    });
+
     it('tells agents to use bundled scripts instead of ad hoc API callers', () => {
         const skillText = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8');
         const openAiYaml = readFileSync(join(skillRoot, 'agents/openai.yaml'), 'utf8');
@@ -2550,12 +2621,26 @@ describe('Agent skill script argument validation', () => {
         const skillText = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8');
         const apiReference = readFileSync(join(skillRoot, 'references/api.md'), 'utf8');
 
+        assert.match(readmeText, /npm run first-run/);
+        assert.match(readmeText, /npm run first-run -- --json/);
+        assert.match(readmeText, /\.env\.agent\.local\.example/);
+        assert.match(readmeText, /--base-url http:\/\/localhost:4783/);
+        assert.match(skillText, /npm run first-run/);
+        assert.match(skillText, /-- --json/);
+        assert.match(skillText, /--base-url <url>/);
+        assert.match(skillText, /\.env\.agent\.local\.example/);
+        assert.match(apiReference, /npm run first-run/);
+        assert.match(apiReference, /npm run first-run -- --json/);
+        assert.match(apiReference, /--base-url <url>/);
+        assert.match(apiReference, /\.env\.agent\.local\.example/);
         assert.match(readmeText, /不要手动并行启动多个单张脚本/);
         assert.match(readmeText, /streamingBatch\.recommendedConcurrency/);
         assert.match(readmeText, /channelQueue\.capacityPerCredential/);
         assert.match(readmeText, /Agent edit 输出格式和尺寸可能与页面 SSE 不完全一致/);
         assert.match(readmeText, /不要直接输出 `\.env\.local`、`\.env\*\.local`、secret 文件或原始 `docker inspect \.Config\.Env`/);
         assert.match(readmeText, /npm run env:summary/);
+        assert.match(readmeText, /verification_scope\.mode=local_planning_only/);
+        assert.match(readmeText, /Hugging Face Space Secrets 只能写入和列出名称/);
 
         assert.match(skillText, /不要手动并行启动多个单张脚本/);
         assert.match(skillText, /capacity_feedback/);
@@ -2564,6 +2649,9 @@ describe('Agent skill script argument validation', () => {
         assert.match(skillText, /复杂 UI、长 prompt、高质量图生图遇到 5 分钟级超时/);
         assert.match(skillText, /Codex 会话日志会持久保存命令输出/);
         assert.match(skillText, /npm run env:summary/);
+        assert.match(skillText, /verification_scope\.mode=local_planning_only/);
+        assert.match(skillText, /manifest_written=false/);
+        assert.match(skillText, /Hugging Face Space Secrets 只能写入和列出名称/);
 
         assert.match(apiReference, /不要手动并行启动多个单张脚本来绕过 `capacity_feedback`/);
         assert.match(apiReference, /streamingBatch\.recommendedConcurrency/);
@@ -2571,6 +2659,9 @@ describe('Agent skill script argument validation', () => {
         assert.match(apiReference, /尺寸敏感任务必须使用批量 `--dimension-check` 或下载后校验/);
         assert.match(apiReference, /channel_capacity_queue_aborted/);
         assert.match(apiReference, /npm run env:summary/);
+        assert.match(apiReference, /verification_scope\.mode=local_planning_only/);
+        assert.match(apiReference, /manifest_written=false/);
+        assert.match(apiReference, /Hugging Face Space Secrets 只能写入和列出名称/);
     });
 
     it('keeps WebUI page APIs out of the Agent OpenAPI contract', () => {
@@ -2647,6 +2738,24 @@ describe('Agent skill script argument validation', () => {
             assert.match(result.stderr, /用法：generate-image\.mjs/);
             assert.equal(result.stdout.trim(), '');
             assert.doesNotMatch(`${result.stdout}\n${result.stderr}`, /ERR_MODULE_NOT_FOUND|src\/lib/);
+
+            const convertHelp = spawnSync(
+                process.execPath,
+                [join(copiedSkillRoot, 'scripts/convert-image-format.mjs'), '--help'],
+                {
+                    cwd: tmpdir(),
+                    encoding: 'utf8',
+                    env: {
+                        ...process.env,
+                        NODE_PATH: ''
+                    }
+                }
+            );
+
+            assert.equal(convertHelp.status, 0);
+            assert.match(convertHelp.stderr, /用法：convert-image-format\.mjs/);
+            assert.equal(convertHelp.stdout.trim(), '');
+            assert.doesNotMatch(`${convertHelp.stdout}\n${convertHelp.stderr}`, /ERR_MODULE_NOT_FOUND|sharp/);
         } finally {
             rmSync(tempRoot, { recursive: true, force: true });
         }
@@ -2683,6 +2792,11 @@ describe('Agent skill script argument validation', () => {
             const body = JSON.parse(result.stdout);
             assert.equal(body.dry_run, true);
             assert.equal(body.billable, false);
+            assert.equal(body.verification_scope.mode, 'local_planning_only');
+            assert.equal(body.verification_scope.remote_capabilities_verified, false);
+            assert.equal(body.verification_scope.runtime_capacity_verified, false);
+            assert.equal(body.manifest_written, false);
+            assert.equal(body.manifest_write_reason, 'dry_run');
             assert.equal(body.total, 2);
             assert.equal(body.concurrency, 1);
             assert.equal(body.tasks[0].endpoint, '/api/agent/images/generate');
@@ -5022,6 +5136,40 @@ describe('Agent skill script argument validation', () => {
         );
     });
 
+    it('lets diagnose-request explicit base-url override the environment service URL', async () => {
+        await withServer(
+            async (request, response) => {
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ endpoints: {} }));
+                    return;
+                }
+                if (request.url === '/api/agent/diagnostics/requests/req_base_url') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ found: false }));
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'diagnose-request.mjs',
+                    ['--base-url', baseUrl, '--agent-request-id', 'req_base_url'],
+                    { GPT_IMAGE_PLAYGROUND_URL: 'http://127.0.0.1:9' }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.service_base_url, baseUrl);
+                assert.equal(body.service_base_url_source, 'user_provided');
+                assert.equal(body.interactive_confirmation_required, false);
+                assert.equal(body.agent_found, false);
+            }
+        );
+    });
+
     it('reports missing Agent state diagnostics as found false without failing the script', async () => {
         await withServer(
             async (request, response) => {

scripts/cleanup-docker-fixtures.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule, pickFailureOutput, printJson, runCommand } from './command-center-utils.mjs';
+
+const LEGACY_FIXTURE_CONTAINER = 'gipc-local-image-fixture';
+const LEGACY_FIXTURE_DESTINATION = '/workspace';
+const DOCKER_TIMEOUT_MS = 30_000;
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export function hasLegacyFixtureRepoMount(mounts, repoRoot = REPO_ROOT) {
+    const resolvedRepoRoot = resolve(repoRoot);
+    return mounts.some(
+        (mount) =>
+            mount?.Type === 'bind' &&
+            typeof mount.Source === 'string' &&
+            resolve(mount.Source) === resolvedRepoRoot &&
+            mount.Destination === LEGACY_FIXTURE_DESTINATION
+    );
+}
+
+export function parseDockerInspectContainer(output) {
+    const parsed = JSON.parse(output);
+    if (!Array.isArray(parsed) || !parsed[0] || typeof parsed[0] !== 'object') {
+        throw new Error('docker inspect did not return a container object');
+    }
+    return parsed[0];
+}
+
+export function summarizeDockerMounts(mounts) {
+    return mounts.map((mount) => ({
+        type: mount.Type,
+        source: mount.Source,
+        destination: mount.Destination,
+        mode: mount.Mode,
+        writable: mount.RW
+    }));
+}
+
+function parseArgs(argv) {
+    const options = {
+        dryRun: false,
+        help: false,
+        containerName: LEGACY_FIXTURE_CONTAINER
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--dry-run') {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (arg === '--container') {
+            const value = argv[index + 1];
+            if (!value) throw new Error('--container requires a value');
+            options.containerName = value;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown option: ${arg}`);
+    }
+    return options;
+}
+
+function printHelp() {
+    console.log(`用法：npm run docker:cleanup-fixtures -- [--dry-run] [--container <name>]
+
+清理遗留的本地图片上游 Docker fixture 容器。该脚本只会删除同时满足以下条件的容器：
+
+- 容器名匹配，默认 ${LEGACY_FIXTURE_CONTAINER}
+- 存在 ${REPO_ROOT} -> ${LEGACY_FIXTURE_DESTINATION} 的整仓 bind mount
+
+推荐使用 npm run smoke:image-upstream-local 启动本地 fixture。不要用 docker run -v "$PWD:${LEGACY_FIXTURE_DESTINATION}" 启动 fixture。`);
+}
+
+function isMissingContainer(result) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    return /No such object|No such container/i.test(output);
+}
+
+export function buildAbsentReport(containerName) {
+    return {
+        ok: true,
+        command: 'docker:cleanup-fixtures',
+        container: containerName,
+        present: false,
+        unsafe_repo_mount: false,
+        removed: false
+    };
+}
+
+export function buildSkippedReport(containerName, mounts) {
+    return {
+        ok: true,
+        command: 'docker:cleanup-fixtures',
+        container: containerName,
+        present: true,
+        unsafe_repo_mount: false,
+        removed: false,
+        mounts: summarizeDockerMounts(mounts)
+    };
+}
+
+function cleanupLegacyFixtureContainer(options) {
+    const inspect = runCommand('docker', ['inspect', options.containerName], { timeoutMs: DOCKER_TIMEOUT_MS });
+    if (!inspect.ok) {
+        if (isMissingContainer(inspect)) return buildAbsentReport(options.containerName);
+        return {
+            ok: false,
+            command: 'docker:cleanup-fixtures',
+            phase: 'inspect',
+            container: options.containerName,
+            error: pickFailureOutput(inspect)
+        };
+    }
+
+    let container;
+    try {
+        container = parseDockerInspectContainer(inspect.stdout);
+    } catch (error) {
+        return {
+            ok: false,
+            command: 'docker:cleanup-fixtures',
+            phase: 'parse-inspect',
+            container: options.containerName,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+
+    const mounts = Array.isArray(container.Mounts) ? container.Mounts : [];
+    if (!hasLegacyFixtureRepoMount(mounts, REPO_ROOT)) return buildSkippedReport(options.containerName, mounts);
+    if (options.dryRun) {
+        return {
+            ok: true,
+            command: 'docker:cleanup-fixtures',
+            container: options.containerName,
+            present: true,
+            unsafe_repo_mount: true,
+            removed: false,
+            dry_run: true,
+            mounts: summarizeDockerMounts(mounts)
+        };
+    }
+
+    const remove = runCommand('docker', ['rm', '-f', options.containerName], { timeoutMs: DOCKER_TIMEOUT_MS });
+    return {
+        ok: remove.ok,
+        command: 'docker:cleanup-fixtures',
+        container: options.containerName,
+        present: true,
+        unsafe_repo_mount: true,
+        removed: remove.ok,
+        mounts: summarizeDockerMounts(mounts),
+        ...(remove.ok ? {} : { phase: 'remove', error: pickFailureOutput(remove) })
+    };
+}
+
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    const report = cleanupLegacyFixtureContainer(options);
+    printJson(report);
+    if (!report.ok) process.exitCode = 1;
+}
+
+if (isMainModule(import.meta.url, process.argv[1])) main();

scripts/command-center-utils.mjs

@@ -80,6 +80,12 @@ export function parseJsonPayload(output, label = 'command') {
     throw new Error(`${label} returned invalid JSON: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
 }
 
+export function redactBaseUrl(value) {
+    const parsed = new URL(value);
+    const path = parsed.pathname === '/' ? '' : parsed.pathname.replace(/\/+$/, '');
+    return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
 export async function fetchJsonWithTimeout(url, options = {}) {
     const timeoutMs = options.timeoutMs || DEFAULT_FETCH_TIMEOUT_MS;
     const pathname = safeUrlPathname(url);

scripts/command-center.test.mjs

@@ -6,8 +6,16 @@ import os from 'node:os';
 import path from 'node:path';
 import { describe, it } from 'node:test';
 
-import { buildAgentDoctorArgs } from './agent-doctor.mjs';
+import { buildAgentDoctorArgs, buildAgentDoctorContractArgs } from './agent-doctor.mjs';
 import { fetchJsonWithTimeout, parseJsonPayload, pickFailureOutput, runCommand } from './command-center-utils.mjs';
+import {
+    buildAbsentReport,
+    buildSkippedReport,
+    hasLegacyFixtureRepoMount,
+    parseDockerInspectContainer,
+    summarizeDockerMounts
+} from './cleanup-docker-fixtures.mjs';
+import { buildFirstRunReport, formatFirstRunText } from './first-run.mjs';
 import {
     buildAdminCommands,
     buildImageUpstreamRealSmokeStatus,
@@ -21,12 +29,14 @@ import { buildVerifyPlan } from './verify.mjs';
 describe('Command center scripts', () => {
     it('exposes a small stable administrator command set', () => {
         assert.deepEqual(buildAdminCommands(), {
+            first_run: 'npm run first-run',
             doctor: 'npm run doctor',
             status: 'npm run status',
             env_summary: 'npm run env:summary',
             verify: 'npm run verify',
             deploy_local: 'npm run deploy:local',
             deploy_space: 'npm run deploy:space',
+            docker_cleanup_fixtures: 'npm run docker:cleanup-fixtures',
             agent_doctor: 'npm run agent:doctor',
             hf_space_doctor: 'npm run doctor:hf-space',
             hf_space_smoke: 'npm run smoke:hf-space'
@@ -322,6 +332,77 @@ describe('Command center scripts', () => {
         });
     });
 
+    it('detects only the legacy fixture whole-repository Docker mount', () => {
+        const repoRoot = '/Volumes/Work/code/gpt-image-playground-customer';
+        assert.equal(
+            hasLegacyFixtureRepoMount(
+                [
+                    {
+                        Type: 'bind',
+                        Source: repoRoot,
+                        Destination: '/workspace',
+                        Mode: 'ro',
+                        RW: false
+                    }
+                ],
+                repoRoot
+            ),
+            true
+        );
+        assert.equal(
+            hasLegacyFixtureRepoMount(
+                [
+                    {
+                        Type: 'bind',
+                        Source: `${repoRoot}/generated-images`,
+                        Destination: '/app/generated-images',
+                        Mode: '',
+                        RW: true
+                    }
+                ],
+                repoRoot
+            ),
+            false
+        );
+    });
+
+    it('parses and summarizes Docker fixture cleanup inspection data', () => {
+        const container = parseDockerInspectContainer(
+            JSON.stringify([
+                {
+                    Mounts: [
+                        {
+                            Type: 'bind',
+                            Source: '/repo',
+                            Destination: '/workspace',
+                            Mode: 'ro',
+                            RW: false
+                        }
+                    ]
+                }
+            ])
+        );
+
+        assert.deepEqual(summarizeDockerMounts(container.Mounts), [
+            {
+                type: 'bind',
+                source: '/repo',
+                destination: '/workspace',
+                mode: 'ro',
+                writable: false
+            }
+        ]);
+        assert.deepEqual(buildAbsentReport('gipc-local-image-fixture'), {
+            ok: true,
+            command: 'docker:cleanup-fixtures',
+            container: 'gipc-local-image-fixture',
+            present: false,
+            unsafe_repo_mount: false,
+            removed: false
+        });
+        assert.equal(buildSkippedReport('custom', container.Mounts).removed, false);
+    });
+
     it('fails local memory deploy probes when the overlay did not take effect', () => {
         assert.doesNotThrow(() => assertLocalProbeMatchesMode({ stateBackend: 'sqlite', imageStorageMode: 'fs' }));
         assert.doesNotThrow(() =>
@@ -339,10 +420,188 @@ describe('Command center scripts', () => {
         assert.deepEqual(args.slice(1), ['--contract-check', '--timeout-ms', '60000', 'contract check']);
     });
 
-    it('reports layered agent:doctor diagnostics without billable smoke by default', async () => {
+    it('routes agent:doctor contract check through an explicit base URL', () => {
+        const args = buildAgentDoctorContractArgs('https://space.example.test/');
+        assert.match(args[0], /generate-image\.mjs$/);
+        assert.deepEqual(args.slice(1), [
+            '--contract-check',
+            '--timeout-ms',
+            '60000',
+            '--base-url',
+            'https://space.example.test/',
+            'contract check'
+        ]);
+    });
+
+    it('reports first-run readiness without exposing secrets', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'first-run-'));
+        await writeFile(path.join(tempDir, 'package.json'), JSON.stringify({ name: 'demo', version: '1.0.0' }));
+        await writeFile(path.join(tempDir, 'package-lock.json'), '{}');
+        await writeFile(path.join(tempDir, '.env.agent.local'), 'GPT_IMAGE_AGENT_TOKEN=file-secret\n');
         await withServer(
             (request, response) => {
                 if (request.url === '/api/agent/capabilities') {
+                    assert.equal(request.headers.authorization, 'Bearer shell-secret');
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            auth: { schemes: ['bearer'] },
+                            defaults: { state_backend: 'memory' },
+                            supported: { image_backend_requirements: {} }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/runtime-capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ streaming: { defaultMode: 'auto' } }));
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                try {
+                    const report = await buildFirstRunReport(
+                        {
+                            cwd: tempDir,
+                            baseUrl,
+                            envFiles: ['.env.agent.local'],
+                            timeoutMs: 1000
+                        },
+                        { GPT_IMAGE_AGENT_TOKEN: 'shell-secret' }
+                    );
+
+                    assert.equal(report.command, 'first-run');
+                    assert.equal(report.billable, false);
+                    assert.equal(report.service_base_url, baseUrl);
+                    assert.equal(report.service_base_url_source, 'user_provided');
+                    assert.equal(report.interactive_confirmation_required, false);
+                    assert.deepEqual(report.agent_auth_process, {
+                        has_token: true,
+                        has_password_hash: false,
+                        has_any_auth: true
+                    });
+                    assert.deepEqual(report.private_agent_env, {
+                        exists: true,
+                        has_token: true,
+                        has_password_hash: false
+                    });
+                    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 === 'agent_auth_available_to_process')
+                            .auth_in_private_env_file,
+                        true
+                    );
+                    assert.doesNotMatch(JSON.stringify(report), /shell-secret|file-secret/);
+                    assert.match(JSON.stringify(report.next_actions), /agent:doctor/);
+                } finally {
+                    await rm(tempDir, { recursive: true, force: true });
+                }
+            }
+        );
+    });
+
+    it('formats first-run as human-readable text by default', async () => {
+        const report = await buildFirstRunReport({ cwd: process.cwd(), baseUrl: 'not a url', envFiles: [] }, {});
+        const text = formatFirstRunText(report);
+
+        assert.match(text, /^首次配置检查：需要处理/m);
+        assert.match(text, /服务地址：无效/);
+        assert.match(text, /当前进程鉴权：未加载/);
+        assert.match(text, /私有 Agent env：不存在/);
+        assert.match(text, /下一步：/);
+        assert.doesNotMatch(text, /^\{/);
+    });
+
+    it('preserves path-prefixed service URLs in first-run reports', async () => {
+        // This test only checks local URL normalization in the report; .test is reserved and should not resolve.
+        const report = await buildFirstRunReport(
+            {
+                cwd: process.cwd(),
+                baseUrl: 'https://space.example.test/proxy/',
+                envFiles: [],
+                timeoutMs: 5
+            },
+            {}
+        );
+
+        assert.equal(report.service_base_url, 'https://space.example.test/proxy');
+    });
+
+    it('prints localized first-run help and option errors', async () => {
+        const help = await runNodeCommandAsync(['scripts/first-run.mjs', '--help'], {
+            env: process.env,
+            timeoutMs: 5_000
+        });
+        assert.equal(help.ok, true);
+        assert.match(help.stdout, /用法：/);
+        assert.match(help.stdout, /输出机器可读 JSON/);
+        assert.doesNotMatch(help.stdout, /Usage:/);
+
+        const invalid = await runNodeCommandAsync(['scripts/first-run.mjs', '--missing-option'], {
+            env: process.env,
+            timeoutMs: 5_000
+        });
+        assert.equal(invalid.ok, false);
+        assert.match(invalid.stdout, /"ok": false/);
+        assert.match(invalid.stdout, /未知参数：--missing-option/);
+    });
+
+    it('keeps first-run local discovery explicit when no URL is provided', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'first-run-default-'));
+        try {
+            await writeFile(path.join(tempDir, 'package.json'), JSON.stringify({ name: 'demo', version: '1.0.0' }));
+
+            const report = await buildFirstRunReport({ cwd: tempDir, envFiles: [], timeoutMs: 20 }, {});
+
+            assert.equal(report.service_base_url_source, 'default_local_probe');
+            assert.equal(report.interactive_confirmation_required, true);
+            assert.equal(report.ok, false);
+            assert.match(JSON.stringify(report.next_actions), /确认探测到的服务地址/);
+        } finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it('points first-run at auth setup when the service rejects capabilities with 401', async () => {
+        const tempDir = await mkdtemp(path.join(os.tmpdir(), 'first-run-auth-'));
+        await writeFile(path.join(tempDir, 'package.json'), JSON.stringify({ name: 'demo', version: '1.0.0' }));
+        await withServer(
+            (_request, response) => {
+                response.writeHead(401, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'unauthorized' }));
+            },
+            async (baseUrl) => {
+                try {
+                    const report = await buildFirstRunReport(
+                        {
+                            cwd: tempDir,
+                            baseUrl: `${baseUrl}/`,
+                            envFiles: [],
+                            timeoutMs: 1000
+                        },
+                        {}
+                    );
+
+                    assert.equal(report.service_base_url, baseUrl);
+                    assert.equal(report.checks.find((check) => check.name === 'agent_auth_available_to_process').skipped, false);
+                    assert.equal(report.checks.find((check) => check.name === 'service_reachable').status, 401);
+                    assert.equal('runtime' in report.service, false);
+                    assert.match(JSON.stringify(report.next_actions), /GPT_IMAGE_AGENT_TOKEN/);
+                    assert.doesNotMatch(JSON.stringify(report.next_actions), /Start the service/);
+                } finally {
+                    await rm(tempDir, { recursive: true, force: true });
+                }
+            }
+        );
+    });
+
+    it('reports layered agent:doctor diagnostics without billable smoke by default', async () => {
+        await withServer(
+            (request, response) => {
+                if (request.url === '/proxy/api/agent/capabilities') {
                     response.writeHead(200, { 'content-type': 'application/json' });
                     response.end(
                         JSON.stringify({
@@ -370,7 +629,7 @@ describe('Command center scripts', () => {
                     );
                     return;
                 }
-                if (request.url === '/api/runtime-capabilities') {
+                if (request.url === '/proxy/api/runtime-capabilities') {
                     response.writeHead(200, { 'content-type': 'application/json' });
                     response.end(
                         JSON.stringify({
@@ -384,7 +643,12 @@ describe('Command center scripts', () => {
                     );
                     return;
                 }
-                if (request.url === '/api/agent/images/generate') {
+                if (request.url === '/proxy/api/agent/images/generate') {
+                    if (request.headers['idempotency-key']) {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ images: [{ id: 'doctor-generate', filename: 'doctor.png' }] }));
+                        return;
+                    }
                     response.writeHead(400, { 'content-type': 'application/json' });
                     response.end(
                         JSON.stringify({
@@ -397,7 +661,7 @@ describe('Command center scripts', () => {
                     );
                     return;
                 }
-                if (request.url === '/api/agent/jobs/images/generate') {
+                if (request.url === '/proxy/api/agent/jobs/images/generate') {
                     response.writeHead(400, { 'content-type': 'application/json' });
                     response.end(
                         JSON.stringify({
@@ -414,8 +678,9 @@ describe('Command center scripts', () => {
                 response.end(JSON.stringify({ error: 'missing' }));
             },
             async (baseUrl) => {
+                const prefixedBaseUrl = `${baseUrl}/proxy`;
                 const result = await runNodeCommandAsync(['scripts/agent-doctor.mjs'], {
-                    env: { ...process.env, GPT_IMAGE_PLAYGROUND_URL: baseUrl },
+                    env: { ...process.env, GPT_IMAGE_PLAYGROUND_URL: `${prefixedBaseUrl}/` },
                     timeoutMs: 15_000
                 });
 
@@ -430,10 +695,126 @@ describe('Command center scripts', () => {
                 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.service_base_url, prefixedBaseUrl);
+                assert.equal(body.service_base_url_source, 'GPT_IMAGE_PLAYGROUND_URL');
+                assert.equal(body.interactive_confirmation_required, true);
             }
         );
     });
 
+    it('uses an explicit base URL for agent:doctor billable smoke checks', async () => {
+        const hits = [];
+        await withServer(
+            (request, response) => {
+                hits.push(request.url);
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            defaults: { state_backend: 'memory' },
+                            storage: { image_storage_mode: 'indexeddb', postgres_configured: false },
+                            agent_streaming: { page_sse: { supported: true } },
+                            agent_jobs: { supported: true },
+                            routing_rules: {
+                                high_resolution_edit: {
+                                    conditions: { operation: 'edit', max_edge: { operator: 'gt', value: 2048 } }
+                                }
+                            },
+                            supported: {
+                                image_backend_requirements: {
+                                    'responses-image-generation': {
+                                        supported: true,
+                                        enabled: true,
+                                        missing_env: []
+                                    }
+                                }
+                            }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/runtime-capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            streaming: {
+                                defaultMode: 'auto',
+                                unavailableMarkScope: 'channel+backend+strategy+operation'
+                            },
+                            streamingBatch: { enabled: true },
+                            responsesImageBackend: { enabled: true, mode: 'experimental' }
+                        })
+                    );
+                    return;
+                }
+                if (request.url === '/api/agent/images/generate') {
+                    if (request.headers['idempotency-key']) {
+                        response.writeHead(200, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ images: [{ id: 'doctor-generate', filename: 'doctor.png' }] }));
+                    } else {
+                        response.writeHead(400, { 'content-type': 'application/json' });
+                        response.end(
+                            JSON.stringify({
+                                error: {
+                                    code: 'idempotency_key_required',
+                                    message: 'missing key',
+                                    retryable: false
+                                }
+                            })
+                        );
+                    }
+                    return;
+                }
+                if (request.url === '/api/agent/jobs/images/generate') {
+                    response.writeHead(400, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            error: {
+                                code: 'idempotency_key_required',
+                                message: 'missing key',
+                                retryable: false
+                            }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runNodeCommandAsync(
+                    ['scripts/agent-doctor.mjs', '--base-url', baseUrl, '--allow-billable'],
+                    { timeoutMs: 15_000 }
+                );
+
+                assert.equal(result.ok, true);
+                const body = parseJsonPayload(result.stdout, 'agent doctor');
+                assert.equal(body.service_base_url_source, 'user_provided');
+                assert.equal(body.interactive_confirmation_required, false);
+                assert.ok(hits.includes('/api/agent/images/generate'));
+            }
+        );
+    });
+
+    it('prints localized agent:doctor help and option errors', async () => {
+        const help = await runNodeCommandAsync(['scripts/agent-doctor.mjs', '--help'], {
+            env: process.env,
+            timeoutMs: 5_000
+        });
+        assert.equal(help.ok, true);
+        assert.match(help.stdout, /用法：/);
+        assert.match(help.stdout, /真实 generate\/edit smoke/);
+        assert.doesNotMatch(help.stdout, /Usage:/);
+
+        const invalid = await runNodeCommandAsync(['scripts/agent-doctor.mjs', '--bad-option'], {
+            env: process.env,
+            timeoutMs: 5_000
+        });
+        assert.equal(invalid.ok, false);
+        assert.match(invalid.stdout, /"ok": false/);
+        assert.match(invalid.stdout, /未知参数：--bad-option/);
+    });
+
     it('preserves raw child output for command consumers', () => {
         const result = runCommand(process.execPath, ['-e', 'process.stdout.write(" M README.md\\n")']);
 

scripts/first-run.mjs

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+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';
+
+const DEFAULT_TIMEOUT_MS = 3000;
+const DEFAULT_ENV_FILES = ['.env.local', '.env.agent.local'];
+
+function parseArgs(argv) {
+    const parsed = {
+        help: false,
+        json: false,
+        baseUrl: undefined,
+        timeoutMs: DEFAULT_TIMEOUT_MS
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') parsed.help = true;
+        else if (arg === '--json') parsed.json = true;
+        else if (arg === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
+        else if (arg === '--timeout-ms') parsed.timeoutMs = readPositiveInteger(readOptionValue(argv, (index += 1), arg), arg);
+        else throw new Error(`未知参数：${arg}`);
+    }
+    return parsed;
+}
+
+function printHelp() {
+    console.log(`用法：
+  npm run first-run
+  npm run first-run -- --json
+  npm run first-run -- --base-url https://your-space.hf.space
+
+选项：
+  --json         输出机器可读 JSON。
+  --base-url     显式服务地址，优先于 GPT_IMAGE_PLAYGROUND_URL 和本地探测。
+  --timeout-ms   HTTP 探测超时，默认 3000。
+
+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;
+    const base = resolveFirstRunBaseUrl(options.baseUrl, env);
+    const envSummary = envFiles.map((filePath) => summarizeEnvFile(join(cwd, filePath)));
+    const validationError = readBaseUrlValidationError(base);
+    const service = validationError
+        ? { ok: false, skipped: true, error: validationError }
+        : await probeService(base.baseUrl, {
+              timeoutMs: options.timeoutMs || DEFAULT_TIMEOUT_MS,
+              headers: authHeaders(env)
+          });
+    const agentAuth = readAgentAuthState(env, envSummary);
+    const checks = buildChecks({
+        cwd,
+        env,
+        envSummary,
+        service,
+        base,
+        validationError
+    });
+    const nextActions = buildNextActions({ checks, base, service, env, envSummary, validationError });
+    return {
+        ok: checks.every((check) => check.ok || check.skipped),
+        command: 'first-run',
+        billable: false,
+        service_base_url: validationError ? undefined : redactBaseUrl(base.baseUrl),
+        service_base_url_source: base.source,
+        interactive_confirmation_required: base.interactive_confirmation_required,
+        agent_auth_process: agentAuth.process,
+        private_agent_env: agentAuth.privateEnv,
+        checks,
+        env_sources: envSummary.map((source) => summarizeEnvSource(source, cwd)),
+        service: summarizeService(service),
+        next_actions: nextActions
+    };
+}
+
+async function probeService(baseUrl, options) {
+    const capabilities = await readJsonEndpoint(`${baseUrl}/api/agent/capabilities`, options);
+    const runtime = capabilities.ok ? await readJsonEndpoint(`${baseUrl}/api/runtime-capabilities`, options) : undefined;
+    return {
+        ok: capabilities.ok && (!runtime || runtime.ok),
+        capabilities,
+        ...(runtime ? { runtime } : {})
+    };
+}
+
+async function readJsonEndpoint(url, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetch(url, { headers: options.headers, signal: controller.signal });
+        const text = await response.text();
+        if (!response.ok) {
+            return {
+                ok: false,
+                status: response.status,
+                endpoint: safeEndpoint(url),
+                error: `HTTP ${response.status}`
+            };
+        }
+        try {
+            return {
+                ok: true,
+                status: response.status,
+                endpoint: safeEndpoint(url),
+                body: JSON.parse(text)
+            };
+        } catch {
+            return {
+                ok: false,
+                status: response.status,
+                endpoint: safeEndpoint(url),
+                error: 'response_not_json'
+            };
+        }
+    } catch (error) {
+        return {
+            ok: false,
+            endpoint: safeEndpoint(url),
+            error: error?.name === 'AbortError' ? `timeout_after_${options.timeoutMs}ms` : 'request_failed'
+        };
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+function buildChecks({ cwd, env, envSummary, service, base, validationError }) {
+    const node = readNodeCheck();
+    const packageJson = readPackageJson(cwd);
+    const packageLock = existsSync(join(cwd, 'package-lock.json'));
+    const nodeModules = existsSync(join(cwd, 'node_modules'));
+    const currentToken = Boolean(env.GPT_IMAGE_AGENT_TOKEN || env.GPT_IMAGE_APP_PASSWORD_HASH);
+    const fileToken = envSummary.some((source) =>
+        ['GPT_IMAGE_AGENT_TOKEN', 'GPT_IMAGE_APP_PASSWORD_HASH'].some((name) => sourceHasSetVariable(source, name))
+    );
+    return [
+        { name: 'node_version', ok: node.ok, current: node.current, required: '>=20.0.0' },
+        { name: 'package_lock', ok: packageLock },
+        {
+            name: 'dependencies_installed',
+            ok: nodeModules,
+            skipped: false,
+            hint: nodeModules ? undefined : 'run npm install'
+        },
+        {
+            name: 'env_files',
+            ok: envSummary.some((source) => source.exists),
+            files: envSummary.map((source) => ({ path: source.path.replace(`${cwd}/`, ''), exists: source.exists }))
+        },
+        {
+            name: 'agent_auth_available_to_process',
+            ok: currentToken,
+            skipped: !requiresAgentAuth(service),
+            auth_in_private_env_file: fileToken
+        },
+        {
+            name: 'service_base_url_valid',
+            ok: !validationError,
+            source: base.source,
+            ...(validationError ? { error: validationError } : {})
+        },
+        {
+            name: 'service_reachable',
+            ok: service.ok,
+            endpoint: '/api/agent/capabilities',
+            ...(service.capabilities?.status ? { status: service.capabilities.status } : {}),
+            ...(service.capabilities?.error ? { error: service.capabilities.error } : {})
+        },
+        {
+            name: 'agent_capabilities_contract',
+            ok: isCapabilitiesBody(service.capabilities?.body),
+            skipped: !service.capabilities?.ok
+        },
+        {
+            name: 'runtime_capabilities_contract',
+            ok: Boolean(service.runtime?.ok),
+            skipped: !service.capabilities?.ok
+        },
+        {
+            name: 'package_metadata',
+            ok: Boolean(packageJson.name && packageJson.version),
+            package: packageJson.name,
+            version: packageJson.version
+        }
+    ];
+}
+
+function readAgentAuthState(env, envSummary) {
+    const hasToken = Boolean(env.GPT_IMAGE_AGENT_TOKEN);
+    const hasPasswordHash = Boolean(env.GPT_IMAGE_APP_PASSWORD_HASH);
+    const privateSource = envSummary.find((source) => source.path.endsWith('.env.agent.local'));
+    return {
+        process: {
+            has_token: hasToken,
+            has_password_hash: hasPasswordHash,
+            has_any_auth: hasToken || hasPasswordHash
+        },
+        privateEnv: {
+            exists: privateSource?.exists === true,
+            has_token: privateSource ? sourceHasSetVariable(privateSource, 'GPT_IMAGE_AGENT_TOKEN') : false,
+            has_password_hash: privateSource ? sourceHasSetVariable(privateSource, 'GPT_IMAGE_APP_PASSWORD_HASH') : false
+        }
+    };
+}
+
+function buildNextActions({ checks, base, service, env, envSummary, validationError }) {
+    const actions = [];
+    const hasCurrentAuth = Boolean(env.GPT_IMAGE_AGENT_TOKEN || env.GPT_IMAGE_APP_PASSWORD_HASH);
+    const hasFileAuth = envSummary.some((source) =>
+        ['GPT_IMAGE_AGENT_TOKEN', 'GPT_IMAGE_APP_PASSWORD_HASH'].some((name) => sourceHasSetVariable(source, name))
+    );
+    if (!findCheck(checks, 'node_version').ok) actions.push('安装 Node.js 20 或更新版本。');
+    if (!findCheck(checks, 'dependencies_installed').ok) actions.push('运行 npm install。');
+    if (!findCheck(checks, 'env_files').ok) {
+        actions.push('复制 .env.example 为 .env.local，或在页面设置里配置默认上游。');
+    }
+    if (validationError) {
+        actions.push('把 GPT_IMAGE_PLAYGROUND_URL 或 --base-url 设为不含凭据、查询参数或片段的 http/https 地址。');
+        return actions;
+    }
+    if (!hasCurrentAuth && requiresAgentAuth(service) && !hasFileAuth) {
+        actions.push(
+            '在仓库外导出 GPT_IMAGE_AGENT_TOKEN 或 GPT_IMAGE_APP_PASSWORD_HASH，再运行受保护的 Agent 脚本。'
+        );
+    }
+    if (!service.ok && !requiresAgentAuth(service)) {
+        actions.push('先用 npm run dev 或 docker compose up -d --build --remove-orphans 启动服务，再重新运行 npm run first-run。');
+    }
+    if (base.interactive_confirmation_required) {
+        actions.push('在交互式 Agent 任务里，先和用户确认探测到的服务地址，再发真实请求。');
+    }
+    if (!hasCurrentAuth && hasFileAuth) {
+        actions.push('先把私有 Agent env 文件加载到 shell，再运行 Agent 脚本。');
+    }
+    if (service.ok && hasCurrentAuth) {
+        actions.push('运行 npm run agent:doctor 做完整的非计费 Agent 合同检查。');
+    }
+    return actions;
+}
+
+function requiresAgentAuth(service) {
+    if (service.capabilities?.status === 401 || service.capabilities?.status === 403) return true;
+    const schemes = service.capabilities?.body?.auth?.schemes;
+    return Array.isArray(schemes) && schemes.length > 0;
+}
+
+function sourceHasSetVariable(source, name) {
+    return source.exists && source.variables.some((item) => item.name === name && item.set === true);
+}
+
+function summarizeEnvSource(source, cwd) {
+    return {
+        path: source.path.startsWith(`${cwd}/`) ? source.path.slice(cwd.length + 1) : source.path,
+        exists: source.exists,
+        variable_count: source.variable_count || 0,
+        configured: source.variables
+            .filter((item) => item.set)
+            .map((item) => ({
+                name: item.name,
+                sensitive: item.sensitive,
+                value_kind: item.value_kind
+            }))
+    };
+}
+
+function summarizeService(service) {
+    const capabilities = service.capabilities || {};
+    const runtime = service.runtime;
+    return {
+        ok: service.ok,
+        capabilities: {
+            ok: capabilities.ok === true,
+            endpoint: capabilities.endpoint,
+            ...(capabilities.status ? { status: capabilities.status } : {}),
+            ...(capabilities.error ? { error: capabilities.error } : {}),
+            ...(capabilities.ok ? summarizeCapabilitiesBody(capabilities.body) : {})
+        },
+        ...(runtime
+            ? {
+                  runtime: {
+                      ok: runtime.ok === true,
+                      endpoint: runtime.endpoint,
+                      ...(runtime.status ? { status: runtime.status } : {}),
+                      ...(runtime.error ? { error: runtime.error } : {}),
+                      ...(runtime.ok ? summarizeRuntimeBody(runtime.body) : {})
+                  }
+              }
+            : {})
+    };
+}
+
+function summarizeCapabilitiesBody(body) {
+    return {
+        auth_required: body?.auth?.required === true,
+        auth_schemes: Array.isArray(body?.auth?.schemes) ? body.auth.schemes : [],
+        state_backend: body?.defaults?.state_backend,
+        image_storage_mode: body?.storage?.image_storage_mode,
+        agent_jobs_supported: body?.agent_jobs?.supported === true,
+        page_sse_supported: body?.agent_streaming?.page_sse?.supported === true,
+        responses_image_backend_enabled:
+            body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true
+    };
+}
+
+function summarizeRuntimeBody(body) {
+    return {
+        default_streaming_strategy: body?.streaming?.defaultStrategy,
+        streaming_batch_enabled: body?.streamingBatch?.enabled === true,
+        recommended_concurrency: body?.streamingBatch?.recommendedConcurrency,
+        channel_capacity_per_credential: body?.channelQueue?.capacityPerCredential,
+        responses_image_backend_enabled: body?.responsesImageBackend?.enabled === true
+    };
+}
+
+function findCheck(checks, name) {
+    return checks.find((check) => check.name === name) || { ok: false };
+}
+
+function readNodeCheck() {
+    const match = process.version.match(/^v(\d+)\./);
+    const major = match ? Number(match[1]) : 0;
+    return { ok: major >= 20, current: process.version };
+}
+
+function readPackageJson(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    } catch {
+        return {};
+    }
+}
+
+function isCapabilitiesBody(body) {
+    return Boolean(body && typeof body === 'object' && body.supported && body.defaults);
+}
+
+function authHeaders(env) {
+    if (env.GPT_IMAGE_AGENT_TOKEN) return { Authorization: `Bearer ${env.GPT_IMAGE_AGENT_TOKEN}` };
+    if (env.GPT_IMAGE_APP_PASSWORD_HASH) return { 'X-App-Password-Hash': env.GPT_IMAGE_APP_PASSWORD_HASH };
+    return {};
+}
+
+function readBaseUrlValidationError(base) {
+    return base.error;
+}
+
+function resolveFirstRunBaseUrl(explicitBaseUrl, env) {
+    try {
+        return resolvePlaygroundBaseUrl(explicitBaseUrl, env);
+    } catch (error) {
+        return {
+            baseUrl: '',
+            source: explicitBaseUrl ? 'user_provided' : env.GPT_IMAGE_PLAYGROUND_URL ? 'GPT_IMAGE_PLAYGROUND_URL' : 'default_local_probe',
+            interactive_confirmation_required: explicitBaseUrl ? false : true,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+
+export function formatFirstRunText(report) {
+    const lines = [];
+    lines.push(`首次配置检查：${report.ok ? '通过' : '需要处理'}`);
+    if (report.service_base_url) {
+        lines.push(`服务地址：${report.service_base_url}（${formatServiceSource(report.service_base_url_source)}）`);
+    } else {
+        lines.push(`服务地址：无效（${readCheckError(report, 'service_base_url_valid') || 'unknown'}）`);
+    }
+    lines.push(`交互式确认：${report.interactive_confirmation_required ? '需要' : '不需要'}`);
+    lines.push(`当前进程鉴权：${formatAuthState(report.agent_auth_process)}`);
+    lines.push(`私有 Agent env：${formatPrivateEnvState(report.private_agent_env)}`);
+    lines.push('');
+    lines.push('检查项：');
+    for (const check of report.checks) {
+        lines.push(`- ${formatCheckLabel(check.name)}：${formatCheckStatus(check)}`);
+    }
+    lines.push('');
+    lines.push('服务摘要：');
+    lines.push(`- 能力：${formatEndpoint(report.service?.capabilities)}`);
+    lines.push(`- 运行时：${formatEndpoint(report.service?.runtime)}`);
+    const capability = report.service?.capabilities || {};
+    if (capability.ok) {
+        lines.push(`- 鉴权：${capability.auth_required ? capability.auth_schemes.join(',') || '需要' : '不需要'}`);
+        lines.push(`- 状态后端：${capability.state_backend || '未知'}，图片存储：${capability.image_storage_mode || '未知'}`);
+    }
+    const runtime = report.service?.runtime || {};
+    if (runtime.ok) {
+        lines.push(
+            `- 并发建议：推荐=${runtime.recommended_concurrency ?? '未知'}，每凭证容量=${runtime.channel_capacity_per_credential ?? '未知'}`
+        );
+    }
+    lines.push('');
+    lines.push('下一步：');
+    if (report.next_actions.length === 0) {
+        lines.push('- 无');
+    } else {
+        for (const action of report.next_actions) lines.push(`- ${action}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+
+function formatCheckStatus(check) {
+    if (check.skipped) return '已跳过';
+    if (check.ok) return '通过';
+    if (check.status) return `失败（${check.status}）`;
+    if (check.error) return `失败（${check.error}）`;
+    return '失败';
+}
+
+function formatEndpoint(endpoint) {
+    if (!endpoint) return '已跳过';
+    if (endpoint.ok) return `通过 ${endpoint.status || ''}`.trim();
+    return `失败${endpoint.status ? ` ${endpoint.status}` : ''}${endpoint.error ? ` ${endpoint.error}` : ''}`;
+}
+
+function formatAuthState(auth) {
+    if (!auth) return '未知';
+    if (auth.has_token) return '已加载 token';
+    if (auth.has_password_hash) return '已加载访问码哈希';
+    return '未加载';
+}
+
+function formatPrivateEnvState(privateEnv) {
+    if (!privateEnv?.exists) return '不存在';
+    if (privateEnv.has_token) return '存在，含 token';
+    if (privateEnv.has_password_hash) return '存在，含访问码哈希';
+    return '存在，未发现 Agent 鉴权变量';
+}
+
+function readCheckError(report, name) {
+    const check = report.checks.find((item) => item.name === name);
+    return check?.error;
+}
+
+function formatServiceSource(source) {
+    if (source === 'user_provided') return '用户提供';
+    if (source === 'GPT_IMAGE_PLAYGROUND_URL') return '环境变量 GPT_IMAGE_PLAYGROUND_URL';
+    if (source === 'default_local_probe') return '默认本地探测';
+    return source || '未知来源';
+}
+
+function formatCheckLabel(name) {
+    const labels = {
+        node_version: 'Node.js 版本',
+        package_lock: 'package-lock.json',
+        dependencies_installed: '依赖是否已安装',
+        env_files: '环境文件',
+        agent_auth_available_to_process: 'Agent 鉴权可用',
+        service_base_url_valid: '服务地址合法',
+        service_reachable: '服务可达',
+        agent_capabilities_contract: 'Agent capabilities 合同',
+        runtime_capabilities_contract: 'runtime capabilities 合同',
+        package_metadata: '包信息'
+    };
+    return labels[name] || name;
+}
+
+function safeEndpoint(url) {
+    try {
+        return new URL(url).pathname;
+    } catch {
+        return String(url);
+    }
+}
+
+function readOptionValue(argv, index, name) {
+    const value = argv[index];
+    if (!value || value.startsWith('--')) throw new Error(`${name} 需要参数值。`);
+    return value;
+}
+
+function readPositiveInteger(value, name) {
+    if (!/^\d+$/.test(String(value))) throw new Error(`${name} 必须是正整数。`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${name} 必须是正整数。`);
+    return parsed;
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    const report = await buildFirstRunReport(options);
+    if (options.json) {
+        printJson(report);
+    } else {
+        process.stdout.write(formatFirstRunText(report));
+    }
+    if (!report.ok) process.exit(1);
+}
+
+try {
+    if (isMainModule(import.meta.url, process.argv[1])) await main();
+} catch (error) {
+    printJson({ ok: false, command: 'first-run', billable: false, error: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+}

scripts/status.mjs

@@ -28,12 +28,14 @@ const STATUS_ENV_FILES = [
 
 export function buildAdminCommands() {
     return {
+        first_run: 'npm run first-run',
         doctor: 'npm run doctor',
         status: 'npm run status',
         env_summary: 'npm run env:summary',
         verify: 'npm run verify',
         deploy_local: 'npm run deploy:local',
         deploy_space: 'npm run deploy:space',
+        docker_cleanup_fixtures: 'npm run docker:cleanup-fixtures',
         agent_doctor: 'npm run agent:doctor',
         hf_space_doctor: 'npm run doctor:hf-space',
         hf_space_smoke: 'npm run smoke:hf-space'

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

@@ -43,18 +43,21 @@ Agent API 只作为自动化客户端接口，不作为首战场景或用户验
 ## 执行流程
 
 1. 先按任务类型选择内置脚本，不要从零写 API 调用代码。
-2. 定位服务基础地址。优先使用用户明确提供的 URL；其次使用 `GPT_IMAGE_PLAYGROUND_URL`；都没有时尝试默认地址 `http://localhost:4783`。
-3. 让脚本请求 `GET /api/agent/capabilities`。如果默认地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，向用户询问实际部署地址、端口、域名和是否需要鉴权。
-4. 读取 capabilities 中的认证方式、模型、模型级限制、`image_transport`、`routing_rules`、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
-5. 为每个业务操作生成稳定的 `Idempotency-Key`。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 `failed` 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
-6. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点对外始终返回最终 `AgentImageResponse` JSON；如 capabilities 声明 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images` 控制内部上游 SSE 消费。不要把 `responsesModel`、`thinking`、`promptOptimization` 或 `force_web` 发送到 Agent JSON；这些字段需要页面端 `/api/images` form-data 路径。
-7. 图片编辑若走 Agent edit，使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段必须使用从 `image_0` 开始的连续字段，最大数量以 capabilities 的 `limits.upload_images.max` 为准；跳号、超过当前 profile 上限、`image_01` 或 `image_foo` 会被显式拒绝。该 Agent 端点同样是非流式端点；上游 SSE 字段按 `agent_streaming.upstream_sse.request_fields_by_mode.edit` 发送，不要给 Agent edit 传 `image_backend`。需要 `image_backend=responses-image-generation` 或页面表单字段 `image_streaming_strategy=responses-sse` 的 edit，一律走页面端 `/api/images` form-data SSE；脚本参数仍写作 `--streaming-strategy responses-sse`。
-8. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
-9. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复、显式页面参数或明确诊断后切换。
-10. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
-11. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
-12. 返回结果时优先给出 `summary`、`content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。回答“4K 非流式花了多久”时优先读 `summary.elapsed_ms`，服务端返回 timing 时也读 `summary.server_elapsed_ms`。
-13. 需要查询页面请求后的人工反馈或日志摘要时，使用页面 SSE 的 `clientRequestId` 或脚本复用的 `Idempotency-Key` 调用 `scripts/diagnose-request.mjs --client-request-id ...`；不要直接调用 `/api/logs`。需要查询 Agent state 请求状态时，使用 `scripts/diagnose-request.mjs --agent-request-id ...` 或 `--idempotency-key ...`。
+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 脚本。
+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。
+9. 文生图使用 `POST /api/agent/images/generate`，请求体为 JSON。该 Agent 端点对外始终返回最终 `AgentImageResponse` JSON；如 capabilities 声明 `agent_streaming.upstream_sse.supported=true`，可通过 `image_backend`、`stream_mode`、`streaming_strategy`、`partial_images` 控制内部上游 SSE 消费。不要把 `responsesModel`、`thinking`、`promptOptimization` 或 `force_web` 发送到 Agent JSON；这些字段需要页面端 `/api/images` form-data 路径。
+10. 图片编辑若走 Agent edit，使用 `POST /api/agent/images/edit`，请求体为 `multipart/form-data`，源图字段必须使用从 `image_0` 开始的连续字段，最大数量以 capabilities 的 `limits.upload_images.max` 为准；跳号、超过当前 profile 上限、`image_01` 或 `image_foo` 会被显式拒绝。该 Agent 端点同样是非流式端点；上游 SSE 字段按 `agent_streaming.upstream_sse.request_fields_by_mode.edit` 发送，不要给 Agent edit 传 `image_backend`。需要 `image_backend=responses-image-generation` 或页面表单字段 `image_streaming_strategy=responses-sse` 的 edit，一律走页面端 `/api/images` form-data SSE；脚本参数仍写作 `--streaming-strategy responses-sse`。
+11. 默认使用 `response_mode: "path"`，只在用户明确需要图片内联数据时使用 `base64` 或 `both`。
+12. 不要把页面端 `POST /api/images` 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 `agent_streaming.page_sse` 单独声明；仅在 `routing_rules` 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复、显式页面参数或明确诊断后切换。
+13. 读取 `agent_jobs`。job 路径只在显式选择时使用；`max_edge>2048` 的单次文生图默认优先走页面端 `/api/images` SSE。
+14. 处理失败时读取结构化 `error.code`、`error.retryable`、`error.diagnostics` 和 `Retry-After`。仅当 `retryable=true` 时等待后重试。
+15. 返回结果时优先给出 `summary`、`content_url`、`metadata_url`、`absolute_content_url`、`absolute_metadata_url`、产物 ID、尺寸、格式和是否命中幂等缓存。回答“4K 非流式花了多久”时优先读 `summary.elapsed_ms`，服务端返回 timing 时也读 `summary.server_elapsed_ms`。
+16. 需要查询页面请求后的人工反馈或日志摘要时，使用页面 SSE 的 `clientRequestId` 或脚本复用的 `Idempotency-Key` 调用 `scripts/diagnose-request.mjs --client-request-id ...`；不要直接调用 `/api/logs`。需要查询 Agent state 请求状态时，使用 `scripts/diagnose-request.mjs --agent-request-id ...` 或 `--idempotency-key ...`。
 
 ## 鉴权
 
@@ -74,7 +77,8 @@ Authorization: Bearer <token>
 - 排查环境配置时不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。Codex 会话日志会持久保存命令输出；优先运行仓库脚本 `npm run env:summary`，或在命令中先把 `API_KEY`、`TOKEN`、`PASSWORD`、`SECRET` 值替换为 `<redacted>`。
 - Skill 必须保持自包含和可迁移：脚本、示例和说明不得写入本机绝对路径或仓库绝对路径；运行脚本时以当前已安装 Skill 目录为根解析 `scripts/`，不要依赖某台机器上的 checkout 位置。
 - Skill 必须兼容 Windows、Linux 和 macOS：脚本只用 Node.js 20+、跨平台 `node:` 标准库和 `package.json` 声明依赖；文档示例用 `node "<skill-root>/scripts/..."`，不依赖 bash、sh、chmod、可执行位、POSIX inline env 或反斜杠续行。
-- 不要把 `localhost:4783` 当作唯一部署位置；它只是无明确地址时的探测默认值。
+- 不要把 `localhost:4783` 当作唯一部署位置；它只是无明确地址时的探测默认值。交互式任务中，探测到本地服务后先请用户确认是否使用；用户提供其他地址时，以用户地址为准。
+- subagent 或自动化任务如果用户指定 Space、云服务或内网服务，调用 `generate-image.mjs`、`edit-image.mjs`、`batch-images.mjs`、`diagnose-request.mjs` 或 `npm run agent:doctor -- --base-url <url>` 时显式传服务地址；不要依赖默认 localhost。
 - 不要在模型上下文中展开大体积 base64，除非用户明确要求。
 - 不要把 `error.message` 当成唯一判断依据；稳定分支以 `error.code` 和 HTTP 状态为准。
 - 不要在没有 `Idempotency-Key` 的情况下调用生成或编辑接口。
@@ -105,46 +109,59 @@ Authorization: Bearer <token>
 - `scripts/edit-image.mjs`：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实编辑。
 - `scripts/batch-images.mjs`：JSONL 批量 generate/edit 调用。默认 dry-run，不消耗额度；必须添加 `--allow-billable` 才会真实执行，支持 append-only manifest、`--resume`、`--ordered-prefix`、`--dimension-check`、`--max-attempts`、`--concurrency` 和顺序执行下的 `--max-consecutive-failures`。`--concurrency` 默认 `1`，大于 `1` 时并发执行并按输入顺序输出结果。
 - `scripts/convert-image-format.mjs`：本地 PNG/JPEG/WebP 互转。默认输出 WebP，质量 `100`；JPEG 会把透明背景铺成白色，PNG/WebP 保留透明。
-- `scripts/diagnose-request.mjs`：按一个或多个页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断；支持读取批量 manifest，不触发生图计费。
+- `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 输出会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。
+生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成和编辑 dry-run 还会包含 `routing_guidance`，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable` 和 `next_action`。
 所有生成、编辑、批量和探针脚本在 dry-run 或真实请求前都会校验尺寸参数。`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 契约。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：
 
+- `npm run first-run`：首次配置就绪检查，只读、非计费、不写 env 文件；默认输出中文摘要，加 `-- --json` 输出机器可读 JSON；用于确认 Node、依赖、服务地址、Agent capabilities、当前进程鉴权和下一步动作。
 - `npm run status`：只读查看 git、Space 目标、Agent API、Skill 入口和独立真实图片上游 smoke 配置摘要；会自动读取 `.env.real-smoke.local`，不输出 URL 或 API Key。
 - `npm run doctor`：统一诊断本机与 HF Space 配置，不写 Secret。
 - `npm run verify`：运行提交前基线；需要真实 PostgreSQL gate 时加 `-- --postgres`。
 - `npm run deploy:local`：重建本地 Docker 服务并探测真实 HTTP 端点；加 `-- --memory` 会断言 memory/indexeddb overlay 生效。
 - `npm run deploy:space`：部署干净 git HEAD 到固定 Space，并做只读公网验证。
-- `npm run agent:doctor`：执行非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend 和 Responses/GPT2Image readiness；真实 1K/2K smoke 必须显式加 `-- --allow-billable`。
+- `npm run agent:doctor`：执行非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend 和 Responses/GPT2Image readiness；支持 `-- --base-url <url>`；真实 1K/2K smoke 必须显式加 `-- --allow-billable`。
+
+首次配置和诊断输出字段速查：
+
+| 字段 | 出现位置 | 判断口径 |
+| --- | --- | --- |
+| `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 已加载。 |
+| `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
+| `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
 
 生成脚本常用参数：
 
 ```text
-node "<skill-root>/scripts/generate-image.mjs" --size 2048x2048 --quality high --response-mode path --idempotency-key stable-operation-key "a product photo of a ceramic mug"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --size 2048x2048 --quality high --response-mode path --idempotency-key stable-operation-key "a product photo of a ceramic mug"
 ```
 
 常用 preset 可先 dry-run 展开真实参数，不触发计费：
 
 ```text
-node "<skill-root>/scripts/generate-image.mjs" --preset 1k-smoke-agent "a product photo of a ceramic mug"
-node "<skill-root>/scripts/generate-image.mjs" --preset 4k-agent-nonstream "a cinematic landscape"
-node "<skill-root>/scripts/generate-image.mjs" --preset 4k-page-sse "a cinematic landscape"
-node "<skill-root>/scripts/generate-image.mjs" --preset 4k-upstream-sse-newapi "a cinematic landscape"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --preset 1k-smoke-agent "a product photo of a ceramic mug"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --preset 4k-agent-nonstream "a cinematic landscape"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --preset 4k-page-sse "a cinematic landscape"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --preset 4k-upstream-sse-newapi "a cinematic landscape"
 ```
 
 启用 Agent 内部上游 SSE 时，必须显式传策略字段；脚本仍只输出最终 JSON：
 
 ```text
-node "<skill-root>/scripts/generate-image.mjs" --allow-billable --image-backend images-api --stream-mode auto --streaming-strategy newapi-keepalive-sse --partial-images 2 --size 3840x2160 --quality high "a product photo of a ceramic mug"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --allow-billable --image-backend images-api --stream-mode auto --streaming-strategy newapi-keepalive-sse --partial-images 2 --size 3840x2160 --quality high "a product photo of a ceramic mug"
 ```
 
 真实生图必须显式开启：
 
 ```text
-node "<skill-root>/scripts/generate-image.mjs" --allow-billable --timeout-ms 420000 --size 2048x2048 "a product photo of a ceramic mug"
+node "<skill-root>/scripts/generate-image.mjs" --base-url https://your-space.hf.space --allow-billable --timeout-ms 420000 --size 2048x2048 "a product photo of a ceramic mug"
 ```
 
 本地格式转换不触发生图计费：
@@ -168,17 +185,17 @@ generate 或页面 SSE 请求包含 `image_backend` 时，`partial_images` 必
 默认 dry-run 只解析 JSONL、生成稳定幂等键并输出计划，不请求服务：
 
 ```text
-node "<skill-root>/scripts/batch-images.mjs" --input tasks.jsonl --ordered-prefix product-set
+node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.space --input tasks.jsonl --ordered-prefix product-set
 ```
 
 真实批量执行必须显式允许计费。需要并发时添加 `--concurrency N`；需要严格连续失败熔断时保持 `--concurrency 1`：
 
 ```text
-node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --max-consecutive-failures 3
-node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --concurrency 3
+node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.space --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --max-consecutive-failures 3
+node "<skill-root>/scripts/batch-images.mjs" --base-url https://your-space.hf.space --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --concurrency 3
 ```
 
-`--manifest` 使用 JSONL append-only 记录每条任务的 `index`、`id`、`idempotency_key`、`attempt`、`status`、响应或错误以及机器可读 `summary`；`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存；即使 fetch 或 SSE 收集阶段失败，也会记录 `request_started`、`request_failed`、`elapsed_ms`、`client_request_id` 和 `endpoint`，便于区分上游未给终图和解析/断流问题。
+`--manifest` 使用 JSONL append-only 记录每条任务的 `index`、`id`、`idempotency_key`、`attempt`、`status`、响应或错误以及机器可读 `summary`；`--resume` 会读取已成功记录并跳过同一 `id` 或 `idempotency_key`。dry-run 不写 manifest，输出会声明 `manifest_written=false` 和 `manifest_write_reason=dry_run`。`--dimension-check` 会读取响应里的 `b64_json` 或同 origin `content_url`，校验 PNG/JPEG/WebP 尺寸是否等于任务 `size`。`--max-attempts` 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；`--concurrency` 大于 `1` 时会先读取运行态并发建议，并发执行任务并按输入顺序输出结果。服务端 `recommendedConcurrency` 或 `channelQueue.capacityPerCredential` 小于请求值时，脚本会把有效并发降到建议值并在输出中写入 `capacity_feedback`；不要再另开多个单张脚本绕过这个限制。`--max-consecutive-failures` 会在连续失败达到阈值后跳过后续任务并输出 `failure_summary` 与 `resume_fix_list`，且只能与顺序执行的 `--concurrency 1` 同用。任务级 `sse_log_path` 会把页面 SSE 原始事件按 JSONL 追加保存；即使 fetch 或 SSE 收集阶段失败，也会记录 `request_started`、`request_failed`、`elapsed_ms`、`client_request_id` 和 `endpoint`，便于区分上游未给终图和解析/断流问题。
 
 批量 JSONL 字段按模式区分：`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚本在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。
 
@@ -193,11 +210,11 @@ node "<skill-root>/scripts/probe-upstream-image.mjs" --base-url https://api.open
 页面请求反馈和日志诊断：
 
 ```text
-node "<skill-root>/scripts/diagnose-request.mjs" --client-request-id stable-operation-key --filename output.png
-node "<skill-root>/scripts/diagnose-request.mjs" --manifest runs/product-set.manifest.jsonl --filename output.png
-node "<skill-root>/scripts/diagnose-request.mjs" --manifest runs/product-set.manifest.jsonl --output runs/diagnosis.json
-node "<skill-root>/scripts/diagnose-request.mjs" --agent-request-id req_abc
-node "<skill-root>/scripts/diagnose-request.mjs" --idempotency-key stable-operation-key
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --client-request-id stable-operation-key --filename output.png
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --manifest runs/product-set.manifest.jsonl --filename output.png
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --manifest runs/product-set.manifest.jsonl --output runs/diagnosis.json
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --agent-request-id req_abc
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --idempotency-key stable-operation-key
 ```
 
 调用前按当前系统和 shell 设置 `OPENAI_API_KEY` 或 `GPT_IMAGE_UPSTREAM_API_KEY`，不要把 key 写进命令历史或文档。
@@ -208,7 +225,7 @@ node "<skill-root>/scripts/diagnose-request.mjs" --idempotency-key stable-operat
 
 脚本读取以下环境变量：
 
-- `GPT_IMAGE_PLAYGROUND_URL`：服务基础地址，可指向本机、局域网、云服务器或域名；脚本未设置时默认尝试 `http://localhost:4783`。
+- `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_AGENT_IDEMPOTENCY_KEY`：跨脚本进程恢复同一操作时复用的幂等键；也供 `diagnose-request.mjs` 按 Agent 幂等键查询 state。脚本不会自动重试已终态失败的 key。
@@ -217,6 +234,8 @@ node "<skill-root>/scripts/diagnose-request.mjs" --idempotency-key stable-operat
 - `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` 不入库。
+
 上游请求头由服务端统一生成。默认 `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 值。
 
 `GPT_IMAGE_PLAYGROUND_URL` 必须是无凭据、无查询参数、无片段的 `http`/`https` 绝对 base URL。不要把 token、访问码或其他 Secret 放进 URL。生成脚本轮询 job result 时只会携带鉴权头访问同 origin URL，避免异常服务返回外部 `result_url` 后泄露 Bearer token 或访问码哈希。

skills/gpt-image-playground-agent/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "GPT Image Agent API"
-  short_description: "使用内置脚本调用图片 Agent API"
-  default_prompt: "使用 $gpt-image-playground-agent 先选择并运行内置脚本，不要临时编写 API 调用脚本。"
+  short_description: "使用内置脚本调用图片 Agent API，并确认目标服务地址"
+  default_prompt: "使用 $gpt-image-playground-agent 先选择并运行内置脚本；运行前先定位服务地址，用户提供 URL 时显式传 --base-url，自动发现本地或环境变量地址时先确认，不要临时编写 API 调用脚本。"

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

@@ -26,13 +26,17 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - `scripts/edit-image.mjs`：multipart 编辑调用。
 - `scripts/batch-images.mjs`：JSONL 批量 generate/edit 调用。
 - `scripts/convert-image-format.mjs`：本地 PNG/JPEG/WebP 互转。
-- `scripts/diagnose-request.mjs`：按页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断。
+- `scripts/diagnose-request.mjs`：按页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断，支持 `--base-url` 固定目标服务。
 - `scripts/probe-upstream-image.mjs`：上游图片接口连通性探针。
 
-生成、编辑和批量脚本默认只做 dry-run，不触发真实生图或编辑。必须显式添加 `--allow-billable` 才会按 capabilities 路由规则调用 `/api/agent/images/generate`、`/api/agent/images/edit`、`/api/agent/jobs/images/generate` 或页面端 `/api/images` SSE。
+生成、编辑和批量脚本默认只做 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`、服务可达性、当前进程鉴权和下一步动作。
+自动化消费时使用 `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`。
+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` 不入库。
 排查环境配置时不要直接输出 `.env.local`、`.env*.local`、secret 文件或原始 `docker inspect .Config.Env`。Codex 会话日志会持久保存命令输出；优先运行仓库脚本 `npm run env:summary`，或在命令中先把 `API_KEY`、`TOKEN`、`PASSWORD`、`SECRET` 值替换为 `<redacted>`。
 
 ```text
@@ -119,6 +123,8 @@ npm run env:summary -- --file .env.local --container gpt-image-playground-custom
 - `--dry-run`
 - `--allow-billable`
 
+批量 dry-run 不写 manifest，输出会声明 `manifest_written=false` 和 `manifest_write_reason=dry_run`。只有真实执行时 manifest 才作为 append-only 续跑记录写入。
+
 批量 JSONL 每行字段按 `mode` 区分。`background` 只适用于 `generate`；`image_path`、`image_paths`、`mask_path` 只适用于 `edit`。默认 WebP edit 任务走页面 SSE；如需 Agent edit 固定输出，请拆成单张 `edit-image.mjs --agent`。`output_format`、`format`、`output_compression`、`moderation`、`image_backend`、`streaming_strategy`、`partial_images`、`responsesModel`/`gptModel`/`gpt_model`、`thinking`、`promptOptimization`/`prompt_optimization`、`force_web`/`forceWeb` 可用于页面 SSE 路径。edit 任务设置 `image_backend=responses-image-generation` 时会走页面 SSE；不要把它改成 Agent edit。`responsesModel` 会选择页面 SSE 路径，且必须同时设置 `image_backend=responses-image-generation` 或兼容值 `responses`，因为 Agent JSON 不接收请求级 Responses 顶层模型。JSONL 字段名必须使用 `streaming_strategy`；`image_streaming_strategy` 是页面 form-data 字段名，不是 batch JSONL 字段，会被脚��在真实请求前拒绝。PNG 搭配 `output_compression` 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。`page_sse`、`complex_ui`、`long_image`、`resume_or_recover` 必须是 JSON 布尔值，`transport` 目前只接受 `page_sse`。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段，避免参数被真实接口忽略。
 
 Responses edit JSONL 正例：
@@ -523,8 +529,28 @@ node "<skill-root>/scripts/diagnose-request.mjs" --agent-request-id req_abc
 node "<skill-root>/scripts/diagnose-request.mjs" --idempotency-key stable-operation-key
 ```
 
+固定服务地址时加 `--base-url`：
+
+```text
+node "<skill-root>/scripts/diagnose-request.mjs" --base-url https://your-space.hf.space --idempotency-key stable-operation-key
+```
+
+远程 Space、云服务或内网服务必须显式传 `--base-url`，不要让诊断脚本误查默认本地服务。
+
 脚本输出会包含 `diagnostics_retention`。当某个请求的 `matched_log_count=0` 时，该请求会额外包含 `diagnostics_note`，说明无匹配日志的保留窗口边界。
 
+首次配置和诊断输出字段速查：
+
+| 字段 | 出现位置 | 判断口径 |
+| --- | --- | --- |
+| `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 已加载。 |
+| `capabilities.ok` | `first-run --json`、`agent:doctor` | 目标地址是否返回 Agent capabilities；失败时先看 HTTP 状态、鉴权提示和服务地址。 |
+| `diagnostics_retention` | `diagnose-request.mjs` | 页面日志诊断的保留窗口；无匹配日志不等于请求一定没发生。 |
+
 单条 Agent state 诊断响应示例：
 
 ```json

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

@@ -3,7 +3,6 @@ import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
 import {
   errorMessage,
   assertValidImageSizeForModel,
-  normalizeBaseUrl,
   normalizeOutputFormat,
   parseImageSizeValue,
   readCapabilitiesImageTransportTimeoutMs,
@@ -11,6 +10,7 @@ import {
   readMaxImageEdge,
   readOptionValue,
   readPartialImages,
+  resolvePlaygroundBaseUrl,
   resolveSameOriginUrl,
   validateAgentEditRequestAgainstCapabilities,
   validateAgentGenerateRequestAgainstCapabilities
@@ -118,6 +118,7 @@ if (options.help) {
 }
 
 let baseUrl;
+let baseUrlInfo;
 let tasks;
 let timeoutMs;
 let capabilities;
@@ -126,7 +127,8 @@ let runtimeCapabilities;
 let runtimeCapabilitiesPromise;
 try {
   if (!options.input) throw new Error('--input 需要 JSONL 文件路径。');
-  baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+  baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+  baseUrl = baseUrlInfo.baseUrl;
   timeoutMs = readConfiguredPositiveInteger(options.timeoutMs, '--timeout-ms', 420000);
   options.maxAttempts = readConfiguredPositiveInteger(
     options.maxAttempts ?? DEFAULT_BATCH_MAX_ATTEMPTS,
@@ -167,8 +169,11 @@ if (!options.allowBillable || options.dryRun) {
         ok: true,
         billable: false,
         dry_run: true,
+        verification_scope: buildDryRunVerificationScope(),
         input: options.input,
         manifest: manifestPath,
+        manifest_written: false,
+        manifest_write_reason: 'dry_run',
         total: planned.length,
         max_attempts: options.maxAttempts,
         max_consecutive_failures: options.maxConsecutiveFailures,
@@ -235,6 +240,7 @@ function parseArgs(argv) {
     maxAttempts: undefined,
     maxConsecutiveFailures: undefined,
     concurrency: undefined,
+    baseUrl: undefined,
     allowBillable: false,
     dryRun: false,
     resume: false,
@@ -252,6 +258,7 @@ function parseArgs(argv) {
     else if (arg === '--manifest') parsed.manifest = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--ordered-prefix') parsed.orderedPrefix = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--max-attempts') parsed.maxAttempts = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--max-consecutive-failures') {
       parsed.maxConsecutiveFailures = readOptionValue(argv, (index += 1), arg);
@@ -264,6 +271,20 @@ function parseArgs(argv) {
   return parsed;
 }
 
+function buildDryRunVerificationScope() {
+  return {
+    mode: 'local_planning_only',
+    service_base_url: baseUrl,
+    service_base_url_source: baseUrlInfo.source,
+    interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+    remote_capabilities_verified: false,
+    runtime_capacity_verified: false,
+    auth_verified: false,
+    billable_request_sent: false,
+    note: 'Dry-run validates JSONL parsing, idempotency keys, request previews and static routing only; run with --allow-billable to verify remote capabilities, capacity and auth.'
+  };
+}
+
 function readJsonlTasks(filePath) {
   return fs
     .readFileSync(filePath, 'utf8')
@@ -1402,5 +1423,5 @@ function mimeTypeForPath(filePath) {
 function printUsage() {
   console.error('用法：batch-images.mjs --input tasks.jsonl [options]');
   console.error('默认只输出 dry-run；添加 --allow-billable 才会按 routing rules 逐行真实请求 Agent API 或页面 SSE。');
-  console.error('常用参数：--manifest --resume --ordered-prefix --dimension-check --max-attempts --max-consecutive-failures --concurrency --timeout-ms --dry-run --allow-billable');
+  console.error('常用参数：--manifest --resume --ordered-prefix --dimension-check --max-attempts --max-consecutive-failures --concurrency --timeout-ms --base-url --dry-run --allow-billable');
 }

skills/gpt-image-playground-agent/scripts/convert-image-format.mjs

@@ -2,7 +2,6 @@
 import { errorMessage, normalizeOutputFormat, readConfiguredPositiveInteger, readOptionValue } from './lib/script-utils.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import sharp from 'sharp';
 
 const OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp']);
 const DEFAULT_OUTPUT_FORMAT = 'webp';
@@ -100,6 +99,7 @@ async function buildConversionPlan(parsed) {
 
 async function convertImage(plan) {
   await fs.mkdir(path.dirname(plan.output.path), { recursive: true });
+  const sharp = await loadSharp();
   let pipeline = sharp(plan.input.path, { animated: false });
   if (plan.output.format === 'jpeg') {
     pipeline = pipeline.flatten({ background: '#ffffff' }).jpeg({ quality: plan.output.quality });
@@ -122,6 +122,18 @@ async function convertImage(plan) {
   };
 }
 
+async function loadSharp() {
+  try {
+    const module = await import('sharp');
+    return module.default;
+  } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+      throw new Error('缺少 sharp 依赖，无法执行图片格式转换；请在包含本 skill 的项目中安装依赖后重试。');
+    }
+    throw error;
+  }
+}
+
 async function readInputFileStat(inputPath) {
   let stat;
   try {

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

@@ -2,7 +2,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { AGENT_ENDPOINTS } from './lib/agent-api-paths.mjs';
-import { errorMessage, normalizeBaseUrl, readOptionValue } from './lib/script-utils.mjs';
+import { errorMessage, readOptionValue, resolvePlaygroundBaseUrl } from './lib/script-utils.mjs';
 
 const MAX_CLIENT_REQUEST_IDS = 50;
 const token = process.env.GPT_IMAGE_AGENT_TOKEN || '';
@@ -24,8 +24,10 @@ if (options.help) {
 let baseUrl;
 let clientRequestIds;
 let agentLookups;
+let baseUrlInfo;
 try {
-  baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+  baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+  baseUrl = baseUrlInfo.baseUrl;
   clientRequestIds = readClientRequestIds(options);
   agentLookups = readAgentLookups(options);
   if (!clientRequestIds.length && !agentLookups.length) {
@@ -46,6 +48,9 @@ try {
   const body = {
     ok: true,
     billable: false,
+    service_base_url: baseUrl,
+    service_base_url_source: baseUrlInfo.source,
+    interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
     page_request_count: requests.length,
     agent_request_count: agentRequests.length,
     request_count: requests.length,
@@ -84,6 +89,7 @@ function parseArgs(argv) {
     filenames: [],
     manifests: [],
     output: '',
+    baseUrl: undefined,
     help: false
   };
   const envClientRequestId = process.env.GPT_IMAGE_AGENT_CLIENT_REQUEST_ID?.trim();
@@ -95,7 +101,9 @@ function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === '--client-request-id' || arg === '--request-id') {
+    if (arg === '--base-url') {
+      parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
+    } else if (arg === '--client-request-id' || arg === '--request-id') {
       parsed.clientRequestIds.push(readOptionValue(argv, (index += 1), arg));
     } else if (arg === '--agent-request-id') {
       parsed.agentRequestIds.push(readOptionValue(argv, (index += 1), arg));
@@ -487,6 +495,6 @@ function writeOutputFile(filepath, text) {
 }
 
 function printUsage() {
-  console.error('用法：diagnose-request.mjs [--client-request-id <id>] [--agent-request-id <id>] [--idempotency-key <key>] [--manifest <jsonl>] [--filename <name>] [--output <json>]');
+  console.error('用法：diagnose-request.mjs [--base-url <url>] [--client-request-id <id>] [--agent-request-id <id>] [--idempotency-key <key>] [--manifest <jsonl>] [--filename <name>] [--output <json>]');
   console.error('只读查询页面反馈/日志诊断或 Agent state 请求诊断，不触发生图计费。');
 }

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

@@ -5,7 +5,6 @@ import path from 'node:path';
 import {
   errorMessage,
   assertValidImageSizeForModel,
-  normalizeBaseUrl,
   normalizeOutputFormat,
   parseRetryAfterValue,
   readCapabilitiesImageTransportTimeoutMs,
@@ -13,6 +12,7 @@ import {
   readMaxImageEdge,
   readOptionValue,
   readPartialImages,
+  resolvePlaygroundBaseUrl,
   sleep,
   validateAgentEditRequestAgainstCapabilities
 } from './lib/script-utils.mjs';
@@ -95,8 +95,10 @@ if ((!imagePath || !prompt) && !contractCheck) {
 }
 
 let baseUrl;
+let baseUrlInfo;
 try {
-  baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+  baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+  baseUrl = baseUrlInfo.baseUrl;
 } catch (error) {
   console.error(errorMessage(error));
   process.exit(2);
@@ -110,6 +112,7 @@ if (options.dryRun || (!contractCheck && !options.allowBillable)) {
         ok: true,
         billable: false,
         dry_run: true,
+        verification_scope: buildDryRunVerificationScope(),
         endpoint: `${baseUrl}${routingGuidance.recommended_endpoint}`,
         routing_guidance: routingGuidance,
         idempotency_key: idempotencyKey,
@@ -179,6 +182,7 @@ function parseArgs(argv) {
     forceWeb: undefined,
     sseLogPath: undefined,
     timeoutMs: undefined,
+    baseUrl: undefined,
     idempotencyKey: undefined,
     imagePath: undefined,
     imagePathSource: undefined,
@@ -215,6 +219,7 @@ function parseArgs(argv) {
     else if (arg === '--force-web') parsed.forceWeb = true;
     else if (arg === '--sse-log') parsed.sseLogPath = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--base-url') parsed.baseUrl = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--image') {
       if (parsed.imagePathSource === 'option') throw new Error('--image 只能设置一次。');
@@ -243,6 +248,20 @@ function absoluteUrl(value) {
   return new URL(value, `${baseUrl}/`).toString();
 }
 
+function buildDryRunVerificationScope() {
+  return {
+    mode: 'local_planning_only',
+    service_base_url: baseUrl,
+    service_base_url_source: baseUrlInfo.source,
+    interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+    remote_capabilities_verified: false,
+    runtime_capacity_verified: false,
+    auth_verified: false,
+    billable_request_sent: false,
+    note: 'Dry-run validates local request construction and routing guidance only; run --contract-check or --allow-billable to verify the remote service.'
+  };
+}
+
 function buildEditRoutingGuidance(parsed) {
   if (parsed.routeMode === 'agent') {
     assertNoPageOnlyEditOptions(parsed, 'Agent edit');
@@ -448,7 +467,7 @@ async function fetchWithTimeout(url, init) {
 function printUsage() {
   console.error('用法：edit-image.mjs [options] <image-path> <prompt> 或 edit-image.mjs --image <path> [options] <prompt>');
   console.error('默认只输出 dry-run；添加 --allow-billable 才会真实编辑图片。');
-  console.error('常用参数：--image --model --size --quality --response-mode --format --output-compression --moderation --image-backend --responses-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --idempotency-key --page-sse --agent --dry-run --allow-billable');
+  console.error('常用参数：--image --model --size --quality --response-mode --format --output-compression --moderation --image-backend --responses-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --base-url --idempotency-key --page-sse --agent --dry-run --allow-billable');
   console.error('契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 edit-image.mjs 或 edit-image.mjs --contract-check');
 }
 

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

@@ -3,7 +3,6 @@ import { AGENT_ENDPOINTS, buildAgentJobResultPath } from './lib/agent-api-paths.
 import {
     errorMessage,
     assertValidImageSizeForModel,
-    normalizeBaseUrl,
     normalizeOutputFormat,
     parseRetryAfterValue,
     readCapabilitiesImageTransportTimeoutMs,
@@ -11,6 +10,7 @@ import {
     readMaxImageEdge,
     readOptionValue,
     readPartialImages,
+    resolvePlaygroundBaseUrl,
     resolveSameOriginUrl,
     sleep,
     validateAgentGenerateRequestAgainstCapabilities
@@ -120,8 +120,10 @@ if (!isNonBillableDryRun(options, contractCheck) && !prompt && !contractCheck) {
 }
 
 let baseUrl;
+let baseUrlInfo;
 try {
-    baseUrl = normalizeBaseUrl(process.env.GPT_IMAGE_PLAYGROUND_URL || 'http://localhost:4783');
+    baseUrlInfo = resolvePlaygroundBaseUrl(options.baseUrl, process.env);
+    baseUrl = baseUrlInfo.baseUrl;
 } catch (error) {
     console.error(errorMessage(error));
     process.exit(2);
@@ -134,6 +136,7 @@ if (isNonBillableDryRun(options, contractCheck)) {
                 ok: true,
                 billable: false,
                 dry_run: true,
+                verification_scope: buildDryRunVerificationScope(),
                 endpoint: dryRunEndpoint(requestBody, options.routeMode),
                 route_mode: options.routeMode,
                 routing_guidance: buildGenerateRoutingGuidance(requestBody, options.routeMode),
@@ -228,6 +231,7 @@ function parseArgs(argv) {
         partialImages: undefined,
         sseLogPath: undefined,
         timeoutMs: undefined,
+        baseUrl: undefined,
         promptFile: undefined,
         idempotencyKey: undefined,
         routeMode: 'auto',
@@ -263,6 +267,7 @@ function parseArgs(argv) {
         else if (arg === '--partial-images') parsed.partialImages = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--sse-log') parsed.sseLogPath = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--base-url') parsed.baseUrl = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--prompt-file') parsed.promptFile = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
@@ -473,6 +478,20 @@ function enrichImageUrls(result) {
     };
 }
 
+function buildDryRunVerificationScope() {
+    return {
+        mode: 'local_planning_only',
+        service_base_url: baseUrl,
+        service_base_url_source: baseUrlInfo.source,
+        interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+        remote_capabilities_verified: false,
+        runtime_capacity_verified: false,
+        auth_verified: false,
+        billable_request_sent: false,
+        note: 'Dry-run validates local request construction and routing guidance only; run --contract-check or --allow-billable to verify the remote service.'
+    };
+}
+
 function dryRunEndpoint(body, routeMode) {
     if (routeMode === 'job') return `${baseUrl}${AGENT_ENDPOINTS.create_generate_job}`;
     if (routeMode === 'agent') return `${baseUrl}${AGENT_ENDPOINTS.generate}`;
@@ -1368,7 +1387,7 @@ function printUsage() {
     console.error('用法：generate-image.mjs [options] <prompt>');
     console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
     console.error(
-        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
+        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --base-url --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
     );
     console.error(
         '契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 generate-image.mjs 或 generate-image.mjs --contract-check'

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

@@ -2,6 +2,7 @@ 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';
 
 export function readOptionValue(argv, index, name) {
   const value = argv[index];
@@ -110,6 +111,28 @@ export function normalizeBaseUrl(value) {
   return normalized;
 }
 
+export function resolvePlaygroundBaseUrl(explicitBaseUrl, env = process.env) {
+  if (explicitBaseUrl) {
+    return {
+      baseUrl: normalizeBaseUrl(explicitBaseUrl),
+      source: 'user_provided',
+      interactive_confirmation_required: false
+    };
+  }
+  if (env.GPT_IMAGE_PLAYGROUND_URL) {
+    return {
+      baseUrl: normalizeBaseUrl(env.GPT_IMAGE_PLAYGROUND_URL),
+      source: 'GPT_IMAGE_PLAYGROUND_URL',
+      interactive_confirmation_required: true
+    };
+  }
+  return {
+    baseUrl: DEFAULT_PLAYGROUND_BASE_URL,
+    source: 'default_local_probe',
+    interactive_confirmation_required: true
+  };
+}
+
 export function normalizeOutputFormat(value) {
   return value.toLowerCase() === 'jpg' ? 'jpeg' : value.toLowerCase();
 }