feat: 完善敲木鱼玩法模板链路

2026-05-24 02:49:13 +08:00
parent 2ba4691bc0
commit 8638397faa
402 changed files with 2329 additions and 1781 deletions
--- a/scripts/dev.mjs
+++ b/scripts/dev.mjs
@@ -257,6 +257,96 @@ function requireCommand(command) {
  }
 }

+function readWorkspaceSpacetimeVersion() {
+  const manifestText = readFileSync(manifestPath, 'utf8');
+  const match = /^spacetimedb\s*=\s*(?:"([^"]+)"|\{[^}]*version\s*=\s*"([^"]+)")/mu.exec(
+    manifestText,
+  );
+  const version = match?.[1] ?? match?.[2] ?? '';
+  if (!version) {
+    throw new Error('无法从 server-rs/Cargo.toml 读取 spacetimedb 版本');
+  }
+  return version;
+}
+
+function parseSpacetimeToolVersion(output) {
+  const match = /spacetimedb tool version\s+([0-9]+\.[0-9]+\.[0-9]+)/u.exec(output);
+  return match?.[1] ?? '';
+}
+
+function readSpacetimeToolVersion() {
+  const result = spawnSync('spacetime', ['--version'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+
+  if (result.error) {
+    throw new Error(`读取 spacetime 版本失败: ${result.error.message}`);
+  }
+
+  const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+  const version = parseSpacetimeToolVersion(output);
+  if (!version) {
+    throw new Error(`无法解析 spacetime 版本输出: ${trimPreview(output)}`);
+  }
+  return version;
+}
+
+function assertSpacetimeToolVersionMatchesWorkspace({
+  toolVersion,
+  workspaceVersion,
+}) {
+  if (toolVersion === workspaceVersion) {
+    return;
+  }
+
+  throw new Error(
+    [
+      `本机 spacetime CLI/standalone 版本 ${toolVersion} 与 server-rs 锁定的 SpacetimeDB ${workspaceVersion} 不一致。`,
+      '版本错位会导致 procedure 返回值 BSATN 反序列化失败，前端表现为 SpacetimeDB procedure 调用超时。',
+      `请执行 spacetime version install ${workspaceVersion} && spacetime version use ${workspaceVersion} 后重新运行本命令。`,
+    ].join(''),
+  );
+}
+
+function assertReusableSpacetimeProcessVersionMatchesWorkspace({
+  dataDir,
+  serverUrl,
+}) {
+  const recordedVersion = readRecordedSpacetimeToolVersion(dataDir);
+  const workspaceVersion = readWorkspaceSpacetimeVersion();
+  if (!recordedVersion) {
+    throw new Error(
+      [
+        `检测到正在运行的本地 SpacetimeDB: ${serverUrl}，但缺少 SpacetimeDB 版本记录。`,
+        '为避免复用旧 standalone 导致 procedure 返回值 BSATN 反序列化失败和前端调用超时，请先停止该进程，再重新运行 npm run dev:spacetime。',
+      ].join(''),
+    );
+  }
+
+  if (recordedVersion === workspaceVersion) {
+    return;
+  }
+
+  throw new Error(
+    [
+      `正在运行的本地 SpacetimeDB standalone 版本 ${recordedVersion} 与 server-rs 锁定的 SpacetimeDB ${workspaceVersion} 不一致。`,
+      '版本错位会导致 procedure 返回值 BSATN 反序列化失败，前端表现为 SpacetimeDB procedure 调用超时。',
+      '请停止当前 SpacetimeDB 进程，执行 spacetime version use ',
+      workspaceVersion,
+      ' 后重新运行 npm run dev:spacetime。',
+    ].join(''),
+  );
+}
+
+function ensureSpacetimeToolVersionMatchesWorkspace() {
+  assertSpacetimeToolVersionMatchesWorkspace({
+    toolVersion: readSpacetimeToolVersion(),
+    workspaceVersion: readWorkspaceSpacetimeVersion(),
+  });
+}
+
 function ensureRequiredFiles(command) {
  const requiredFiles = [];

@@ -478,6 +568,9 @@ class DevRunner {
    ) {
      requireCommand('spacetime');
    }
+    if (this.shouldValidateSpacetimeToolVersion(command)) {
+      ensureSpacetimeToolVersionMatchesWorkspace();
+    }

    await this.tryReuseExistingSpacetime(command);
    await this.resolvePorts(command);
@@ -485,6 +578,19 @@ class DevRunner {
    this.printSummary(command);
  }

+  shouldValidateSpacetimeToolVersion(command) {
+    if (command === 'spacetime') {
+      return true;
+    }
+    if (command === 'all') {
+      return !this.options.skipSpacetime || !this.options.skipPublish;
+    }
+    if (command === 'api-server') {
+      return isLoopbackSpacetimeServer(this.state.spacetimeServer);
+    }
+    return false;
+  }
+
  async tryReuseExistingSpacetime(command) {
    if (this.options.skipSpacetime) {
      return;
@@ -525,6 +631,11 @@ class DevRunner {
        continue;
      }

+      assertReusableSpacetimeProcessVersionMatchesWorkspace({
+        dataDir: this.options.spacetimeDataDir,
+        serverUrl: candidate,
+      });
+
      const port = safeUrlPort(candidate);
      if (Number.isInteger(port) && port > 0) {
        this.options.spacetimePort = port;
@@ -705,6 +816,15 @@ class DevRunner {
    const logFile = resolve(options.spacetimeDataDir, 'logs/dev-spacetime-start.log');
    const logStream = createWriteStream(logFile, {flags: 'a', encoding: 'utf8'});
    service.logStream = logStream;
+    const spacetimeToolVersion = readSpacetimeToolVersion();
+    assertSpacetimeToolVersionMatchesWorkspace({
+      toolVersion: spacetimeToolVersion,
+      workspaceVersion: readWorkspaceSpacetimeVersion(),
+    });
+    recordSpacetimeToolVersion(
+      options.spacetimeDataDir,
+      spacetimeToolVersion,
+    );

    console.log(`[dev:spacetime] log: ${logFile}`);
    const env = {
@@ -1357,6 +1477,15 @@ function readRecordedSpacetimeUrl(dataDir) {
  return '';
 }

+function readRecordedSpacetimeToolVersion(dataDir) {
+  const versionPath = resolve(dataDir, 'dev-spacetime-tool-version');
+  if (!existsSync(versionPath)) {
+    return '';
+  }
+
+  return readFileSync(versionPath, 'utf8').split(/\r?\n/u)[0]?.trim() ?? '';
+}
+
 function readRecordedSpacetimePidState(dataDir) {
  const pidPath = resolve(dataDir, 'spacetime.pid');
  if (!existsSync(pidPath)) {
@@ -1389,6 +1518,16 @@ function readRecordedSpacetimePidState(dataDir) {
  }
 }

+function recordSpacetimeToolVersion(dataDir, version) {
+  const versionPath = resolve(dataDir, 'dev-spacetime-tool-version');
+  ensureParentDir(versionPath);
+  try {
+    writeFileSync(versionPath, `${version}\n`, 'utf8');
+  } catch (error) {
+    console.warn(`[dev:spacetime] 写入版本记录失败 ${versionPath}: ${error.message}`);
+  }
+}
+
 function recordSpacetimeUrl(dataDir, serverUrl) {
  const targets = [
    resolve(dataDir, 'dev-spacetime-url'),
@@ -1580,10 +1719,13 @@ function isSpacetimePublishPermissionError(error) {

 export {
  DevRunner,
+  assertReusableSpacetimeProcessVersionMatchesWorkspace,
+  assertSpacetimeToolVersionMatchesWorkspace,
  buildSpacetimePublishArgs,
  createDevServerSpawnOptions,
  createWatchConfigs,
  isSpacetimePublishPermissionError,
+  parseSpacetimeToolVersion,
  parseArgs,
  shouldAcceptWatchEvent,
 };
--- a/scripts/dev.test.ts
+++ b/scripts/dev.test.ts
@@ -1,4 +1,4 @@
-import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';

@@ -6,10 +6,13 @@ import {afterEach, describe, expect, test, vi} from 'vitest';

 import {
  DevRunner,
+  assertReusableSpacetimeProcessVersionMatchesWorkspace,
+  assertSpacetimeToolVersionMatchesWorkspace,
  buildSpacetimePublishArgs,
  createDevServerSpawnOptions,
  createWatchConfigs,
  isSpacetimePublishPermissionError,
+  parseSpacetimeToolVersion,
  parseArgs,
  shouldAcceptWatchEvent,
 } from './dev.mjs';
@@ -21,6 +24,15 @@ afterEach(() => {
  vi.restoreAllMocks();
 });

+function workspaceSpacetimeVersionForTest() {
+  const manifestText = readFileSync('server-rs/Cargo.toml', 'utf8');
+  const match = /^spacetimedb\s*=\s*"([^"]+)"/mu.exec(manifestText);
+  if (!match) {
+    throw new Error('无法读取测试用 SpacetimeDB 版本');
+  }
+  return match[1];
+}
+
 describe('dev scheduler argument routing', () => {
  test('完整 dev 栈覆盖前端代理到本次解析出的 api-server 地址', () => {
    const {command, explicitOptions, options} = parseArgs([], {
@@ -104,6 +116,11 @@ describe('dev scheduler spacetime reuse guard', () => {
    try {
      writeFileSync(join(tempDir, 'dev-spacetime-url'), 'http://127.0.0.1:3199\n', 'utf8');
      writeFileSync(join(tempDir, 'spacetime.pid'), `${process.pid}\n`, 'utf8');
+      writeFileSync(
+        join(tempDir, 'dev-spacetime-tool-version'),
+        `${workspaceSpacetimeVersionForTest()}\n`,
+        'utf8',
+      );
      globalThis.fetch = vi.fn(async () => ({status: 200})) as unknown as typeof fetch;

      const {command, explicitOptions, options} = parseArgs(
@@ -126,6 +143,11 @@ describe('dev scheduler spacetime reuse guard', () => {
    const tempDir = mkdtempSync(join(tmpdir(), 'genarrative-spacetime-reuse-'));
    try {
      writeFileSync(join(tempDir, 'spacetime.pid'), `${process.pid}\n`, 'utf8');
+      writeFileSync(
+        join(tempDir, 'dev-spacetime-tool-version'),
+        `${workspaceSpacetimeVersionForTest()}\n`,
+        'utf8',
+      );
      globalThis.fetch = vi.fn(async () => ({status: 200})) as unknown as typeof fetch;

      const {command, explicitOptions, options} = parseArgs(
@@ -212,6 +234,40 @@ describe('dev scheduler watch routing', () => {
 });

 describe('dev scheduler spacetime refresh', () => {
+  test('解析 spacetime --version 输出里的 tool version', () => {
+    const version = parseSpacetimeToolVersion(`
+A new version of SpacetimeDB is available: v2.2.0 (current: v2.1.0)
+spacetimedb tool version 2.2.0; spacetimedb-lib version 2.2.0;
+`);
+
+    expect(version).toBe('2.2.0');
+  });
+
+  test('本机 spacetime 版本和 workspace 锁定版本不一致时直接报清楚', () => {
+    expect(() =>
+      assertSpacetimeToolVersionMatchesWorkspace({
+        toolVersion: '2.1.0',
+        workspaceVersion: '2.2.0',
+      }),
+    ).toThrow('procedure 返回值 BSATN 反序列化失败');
+  });
+
+  test('复用本地 SpacetimeDB standalone 前校验启动时版本记录', () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'genarrative-spacetime-version-'));
+    try {
+      writeFileSync(join(tempDir, 'dev-spacetime-tool-version'), '2.1.0\n', 'utf8');
+
+      expect(() =>
+        assertReusableSpacetimeProcessVersionMatchesWorkspace({
+          dataDir: tempDir,
+          serverUrl: 'http://127.0.0.1:3101',
+        }),
+      ).toThrow('SpacetimeDB procedure 调用超时');
+    } finally {
+      rmSync(tempDir, {recursive: true, force: true});
+    }
+  });
+
  test('本地发布 403 时识别为身份权限问题，避免误杀 standalone', () => {
    const error = new Error(
      'Pre-publish check failed with status 403 Forbidden: c200... is not authorized to perform action on database c200...: update database',
--- a/scripts/generate-edutainment-road-town-map-concepts.mjs
+++ b/scripts/generate-edutainment-road-town-map-concepts.mjs
@@ -0,0 +1,443 @@
+import { Buffer } from 'node:buffer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const repoRoot = process.cwd();
+const outDir = path.join(
+  repoRoot,
+  'output',
+  'imagegen',
+  'edutainment-road-town-map-concepts-20260523',
+);
+const styleReferencePath = path.join(
+  repoRoot,
+  'public',
+  'child-motion-demo',
+  'picture-book-grass-stage.png',
+);
+const layoutReferencePaths = [
+  path.join(repoRoot, 'tmp', 'edutainment_video_frames', 'video1_t2_11950ms.png'),
+  path.join(repoRoot, 'tmp', 'edutainment_video_frames', 'video1_t3_23400ms.png'),
+];
+const defaultTimeoutMs = 1000000;
+
+const commonPrompt = [
+  '横屏 16:9 电视端寓教于乐板块玩法入口概念图。',
+  '新的结构要求：抛弃原本乐园地图、环形乐园、岛屿乐园和主题公园分区结构，改为参考 Toca Life World 地图的“马路串联小建筑群”结构。',
+  '每一屏都是一个完整的主题小建筑群街区：画面中心必须有一条灰蓝色可通车马路横向贯穿，马路有双车道、白色虚线、斑马线、路口、转弯支路和小汽车。',
+  '马路必须从画面左侧边缘进入、从画面右侧边缘离开，左右边缘都要明确暗示可以接到上一屏和下一屏，像横向滑动世界地图的一段。',
+  '建筑群沿马路两侧聚集，不要平均散成乐园点位；每屏像一个小镇街区、一组主题建筑、一段可探索街道。',
+  '采用轻微俯视的卡通等距地图视角，能看清建筑立面、屋顶、路网和车辆路径。',
+  '整体保持 Genarrative 寓教于乐现有明亮卡通绘本插画风：柔和水彩笔触、纸张纹理、温暖草地、浅蓝天空、圆润儿童友好、干净低噪声。',
+  '入口模块只用建筑外形和道具暗示，不写任何文字：识物可用水果店、动物卡片屋、观察橱窗；绘画可用彩笔工坊、画纸屋；动作可用小操场、跳圈馆；拼图可用积木拼图屋；声音节奏可用小剧场、音乐屋；自然探索可用树屋、温室、观测台。',
+  '参考图只用于学习“中央马路 + 两侧主题小建筑群 + 横向连续世界”的结构，不要复制 Toca Life World 的 logo、角色、建筑外形、UI、按钮、文字、字幕、水印或品牌元素。',
+  '不要出现中文、英文、数字、字母、按钮文案、UI 面板、教程说明、logo、水印、商业 IP、真实品牌、城堡、环球影城/迪士尼式乐园、环形乐园岛、漂浮岛、地球球体、过度奇幻设施、真实照片感、暗黑科技风。',
+].join('');
+
+const concepts = [
+  {
+    id: 'edutainment-road-town-01-cognition-main-street',
+    title: '识物认知主街',
+    prompt: [
+      commonPrompt,
+      '本屏主题：识物认知主街。',
+      '马路从左到右横穿中轴，路两侧是一组水果小店、动物观察窗、图形积木屋、透明展示橱窗和小型公交站，像儿童认知街区。',
+      '建筑数量 6 到 8 个，分成前景近路建筑和后景山坡建筑，街区整体紧凑，不能变成分散乐园点。',
+      '左边缘的道路要露出半个弯道和继续驶入的小汽车，右边缘道路继续出画，暗示下一屏可以接到绘画工坊街。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-road-town-02-creative-workshop-street',
+    title: '绘画创作工坊街',
+    prompt: [
+      commonPrompt,
+      '本屏主题：绘画创作工坊街。',
+      '中央马路横贯画面，马路两侧聚成彩笔工坊、画纸屋、颜料罐屋、绘本小剧场、手工材料店和圆顶小展馆。',
+      '建筑轮廓要像一组主题小建筑群，屋顶可有画笔、颜料、纸张、拼贴形状等图形化暗示，但不要出现任何文字。',
+      '左边道路接识物主街，右边道路接运动音乐街；用连续路面、车道线、小汽车和路灯强调可横向滑动探索。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-road-town-03-motion-music-block',
+    title: '运动音乐街区',
+    prompt: [
+      commonPrompt,
+      '本屏主题：运动音乐街区。',
+      '中央马路是主要路径，两侧是一组动作热身馆、小操场、跳圈屋、音乐小剧场、鼓点屋、铃铛塔和户外小舞台。',
+      '建筑群要围绕道路形成一个活泼街区，前景可以有迷你停车位、斑马线、小汽车、路牌形状图标，但不要文字。',
+      '道路左侧出画连接绘画创作工坊街，右侧出画连接自然探索街；画面边缘不能封死。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-road-town-04-nature-lab-avenue',
+    title: '自然探索实验大道',
+    prompt: [
+      commonPrompt,
+      '本屏主题：自然探索实验大道。',
+      '中央马路横向穿过一组自然探索小建筑群：温室、树屋、昆虫观察屋、云朵气象站、小望远镜塔、湖边小码头和拼图桥。',
+      '建筑沿道路成街区分布，后景是柔和山坡和树林，前景保留路边草地、停车位和小汽车路径。',
+      '左边道路接运动音乐街，右边道路继续进入森林或新的学习街区，明确体现一屏接一屏的世界地图结构。',
+    ].join(''),
+  },
+];
+
+function readDotenv(fileName) {
+  const filePath = path.join(repoRoot, fileName);
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+    let value = match[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[match[1]] = value;
+  }
+  return values;
+}
+
+function resolveEnv() {
+  const loaded = {
+    ...readDotenv('.env.example'),
+    ...readDotenv('.env.local'),
+    ...readDotenv('.env.secrets.local'),
+    ...process.env,
+  };
+  return {
+    baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '')
+      .trim()
+      .replace(/\/+$/u, ''),
+    apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(),
+    timeoutMs: Number.parseInt(
+      String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
+      10,
+    ),
+  };
+}
+
+function generationUrl(baseUrl) {
+  return baseUrl.endsWith('/v1')
+    ? `${baseUrl}/images/generations`
+    : `${baseUrl}/v1/images/generations`;
+}
+
+function collectStringsByKey(value, targetKey, output) {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectStringsByKey(entry, targetKey, output));
+    return;
+  }
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === targetKey) {
+      if (typeof nested === 'string' && nested.trim()) {
+        output.push(nested.trim());
+      }
+      if (Array.isArray(nested)) {
+        nested.forEach((entry) => {
+          if (typeof entry === 'string' && entry.trim()) {
+            output.push(entry.trim());
+          }
+        });
+      }
+    }
+    collectStringsByKey(nested, targetKey, output);
+  }
+}
+
+function inferExtensionFromBytes(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from('\x89PNG\r\n\x1A\n', 'binary'))) {
+    return 'png';
+  }
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff]))) {
+    return 'jpg';
+  }
+  if (
+    bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'webp';
+  }
+  return 'png';
+}
+
+function inferExtensionFromContentType(contentType) {
+  const normalized = contentType.split(';')[0]?.trim().toLowerCase();
+  if (normalized === 'image/png') {
+    return 'png';
+  }
+  if (normalized === 'image/webp') {
+    return 'webp';
+  }
+  if (normalized === 'image/jpeg') {
+    return 'jpg';
+  }
+  return 'png';
+}
+
+function toDataUrl(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  const bytes = readFileSync(filePath);
+  const extension = inferExtensionFromBytes(bytes);
+  const mime = extension === 'jpg' ? 'image/jpeg' : `image/${extension}`;
+  return `data:${mime};base64,${bytes.toString('base64')}`;
+}
+
+function referenceDataUrls() {
+  return [styleReferencePath, ...layoutReferencePaths]
+    .map((filePath) => toDataUrl(filePath))
+    .filter(Boolean);
+}
+
+function buildRequestBody(concept, size, references) {
+  const body = {
+    model: 'gpt-image-2-all',
+    prompt: concept.prompt,
+    n: 1,
+    size,
+  };
+  if (references.length > 0) {
+    body.image = references;
+  }
+  return body;
+}
+
+function buildDryRunRequestBody(concept, size, references) {
+  return {
+    model: 'gpt-image-2-all',
+    prompt: concept.prompt,
+    n: 1,
+    size,
+    imageReferenceCount: references.length,
+  };
+}
+
+async function fetchJson(url, options, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: abortController.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`);
+    }
+    return JSON.parse(text);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function downloadUrl(url, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: abortController.signal });
+    if (!response.ok) {
+      throw new Error(`download ${response.status}`);
+    }
+    return {
+      bytes: Buffer.from(await response.arrayBuffer()),
+      extension: inferExtensionFromContentType(
+        response.headers.get('content-type') || '',
+      ),
+    };
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`Generated image download timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function outputPathFor(concept, extension = 'png') {
+  return path.join(outDir, `${concept.id}.${extension}`);
+}
+
+function findExistingOutputPath(concept) {
+  for (const extension of ['png', 'jpg', 'jpeg', 'webp']) {
+    const candidate = outputPathFor(concept, extension);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function generateOne(env, concept, size, references) {
+  const payload = await fetchJson(
+    generationUrl(env.baseUrl),
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(buildRequestBody(concept, size, references)),
+    },
+    env.timeoutMs,
+  );
+
+  const urls = [];
+  const b64Images = [];
+  collectStringsByKey(payload, 'url', urls);
+  collectStringsByKey(payload, 'image', urls);
+  collectStringsByKey(payload, 'image_url', urls);
+  collectStringsByKey(payload, 'b64_json', b64Images);
+
+  let image;
+  const imageUrl = [...new Set(urls)].find((url) => /^https?:\/\//u.test(url));
+  if (imageUrl) {
+    image = await downloadUrl(imageUrl, env.timeoutMs);
+  } else if (b64Images[0]) {
+    const bytes = Buffer.from(b64Images[0], 'base64');
+    image = {
+      bytes,
+      extension: inferExtensionFromBytes(bytes),
+    };
+  } else {
+    throw new Error(`VectorEngine returned no image for ${concept.id}`);
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const outputPath = outputPathFor(concept, image.extension);
+  writeFileSync(outputPath, image.bytes);
+  return outputPath;
+}
+
+const args = new Map();
+for (let index = 2; index < process.argv.length; index += 1) {
+  const raw = process.argv[index];
+  if (raw.startsWith('--')) {
+    const next = process.argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      args.set(raw, next);
+      index += 1;
+    } else {
+      args.set(raw, true);
+    }
+  }
+}
+
+const size = String(args.get('--size') || '3840x2160');
+const dryRun = args.has('--dry-run') || !args.has('--live');
+const selectedIds = String(args.get('--only') || '')
+  .split(',')
+  .map((value) => value.trim())
+  .filter(Boolean);
+const selectedConcepts = concepts.filter(
+  (concept) => selectedIds.length === 0 || selectedIds.includes(concept.id),
+);
+const references = referenceDataUrls();
+
+if (dryRun) {
+  console.log(
+    JSON.stringify(
+      {
+        mode: 'dry-run',
+        outDir,
+        size,
+        styleReference: existsSync(styleReferencePath)
+          ? styleReferencePath
+          : null,
+        layoutReferences: layoutReferencePaths.filter((filePath) =>
+          existsSync(filePath),
+        ),
+        count: selectedConcepts.length,
+        requests: selectedConcepts.map((concept) => ({
+          id: concept.id,
+          title: concept.title,
+          body: buildDryRunRequestBody(concept, size, references),
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+
+const env = resolveEnv();
+if (!env.baseUrl || !env.apiKey) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY',
+      hasBaseUrl: Boolean(env.baseUrl),
+      hasApiKey: Boolean(env.apiKey),
+    }),
+  );
+  process.exit(1);
+}
+
+const files = [];
+const generatedFileById = new Map();
+for (const concept of selectedConcepts) {
+  console.log(`Generating ${concept.id}...`);
+  const file = await generateOne(env, concept, size, references);
+  files.push(file);
+  generatedFileById.set(concept.id, file);
+}
+
+const metadataFiles = concepts
+  .map((concept) => {
+    const file = generatedFileById.get(concept.id) ?? findExistingOutputPath(concept);
+    if (!file) {
+      return null;
+    }
+    return {
+      id: concept.id,
+      title: concept.title,
+      file,
+      prompt: concept.prompt,
+    };
+  })
+  .filter(Boolean);
+
+writeFileSync(
+  path.join(outDir, 'generation-metadata.json'),
+  JSON.stringify(
+    {
+      model: 'gpt-image-2-all',
+      size,
+      generatedAt: new Date().toISOString(),
+      styleReference: existsSync(styleReferencePath) ? styleReferencePath : null,
+      layoutReferences: layoutReferencePaths.filter((filePath) =>
+        existsSync(filePath),
+      ),
+      generatedIds: selectedConcepts.map((concept) => concept.id),
+      files: metadataFiles,
+    },
+    null,
+    2,
+  ),
+);
+
+console.log(JSON.stringify({ ok: true, count: files.length, files }, null, 2));
--- a/scripts/generate-edutainment-toca-world-map-concepts.mjs
+++ b/scripts/generate-edutainment-toca-world-map-concepts.mjs
@@ -0,0 +1,422 @@
+import { Buffer } from 'node:buffer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const repoRoot = process.cwd();
+const outDir = path.join(
+  repoRoot,
+  'output',
+  'imagegen',
+  'edutainment-toca-world-map-concepts-20260523',
+);
+const styleReferencePath = path.join(
+  repoRoot,
+  'public',
+  'child-motion-demo',
+  'picture-book-grass-stage.png',
+);
+const defaultTimeoutMs = 1000000;
+
+const commonPrompt = [
+  '横屏 16:9 寓教于乐板块玩法入口概念图。',
+  '参考 Toca Life World 的地图组织方式：一个横向展开的大世界，允许向左和向右以“一屏一屏”的单位继续延伸和探索。',
+  '画面必须像儿童绘本插画，明亮、干净、温暖、圆润、手绘感强，保留 Genarrative 寓教于乐现有的草地、水彩、纸张纹理和童趣气质。',
+  '地图里要有清晰的道路、步道、河流、桥、分区节点和地标，但不要复制 Toca 的 logo、角色、字体、UI、建筑外形或配色。',
+  '每个玩法入口都要像一个可单独进入的区域，区域之间既连贯又能独立辨认，适合后续做横向滑动或分屏探索。',
+  '左右两侧都要有明显的延展感，边缘不能封死，重要场景不要都挤在画面中心。',
+  '中心只保留一个轻量主枢纽，左右各留出半屏到一屏的可继续探索空间。',
+  '不要出现文字、数字、字母、按钮文案、UI 面板、logo、水印、真实照片感、暗黑科技风、过度复杂的人物表情、现成商业 IP 角色。',
+].join('');
+
+const concepts = [
+  {
+    id: 'edutainment-toca-world-01-river-town',
+    title: '河道城镇带',
+    prompt: [
+      commonPrompt,
+      '版式方向：一条横向城镇带沿着河道和主路展开，左边是果园与识物区，中间是创作和主枢纽区，右边是音乐广场、自然观察和运动区。',
+      '每个区域像独立小镇街区，房屋和设施分布在道路两侧，远处山坡和天空继续延伸，整体感觉像可以一直向左右滑动。',
+      '左侧入口更偏自然与认知，右侧入口更偏探索与表演，中间保留一个安静广场作为聚合点。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-toca-world-02-mountain-arc',
+    title: '山脊长廊',
+    prompt: [
+      commonPrompt,
+      '版式方向：一条山脊和环山公路贯穿左右，地图像被拉长的山地长廊，城市、树林、草坡和小店沿山脊展开。',
+      '左屏是水果农场和画画工坊，中屏是社区广场和拼图桥，右屏是音乐小剧场、动物观察和冒险步道。',
+      '地形要有明显起伏，但道路必须连续、可走、可向两侧继续延伸，像同一世界的不同屏幕段落。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-toca-world-03-island-chain',
+    title: '岛链世界',
+    prompt: [
+      commonPrompt,
+      '版式方向：多个小岛通过桥梁、栈道和缆车相连，像一条横向的岛链，每个岛都像一屏可探索区域。',
+      '左侧岛是识物果园岛，中间岛是绘本创作岛和主广场，右侧岛是运动草地岛、音乐舞台岛和自然探索岛。',
+      '每个岛的边缘都要暗示下一岛的延伸，水面和道路自然把画面向左向右打开，不要封闭成一个圆形世界。',
+    ].join(''),
+  },
+  {
+    id: 'edutainment-toca-world-04-city-park-spine',
+    title: '城市公园脊',
+    prompt: [
+      commonPrompt,
+      '版式方向：一条城市公园主脊从左到右穿过整个画面，主脊两侧是不同功能街区，像儿童版的世界地图主干道。',
+      '左边是安静学习区和果园，中央是综合广场、画画棚和拼图桥，右边是音乐广场、运动场、动物观测点和森林边界。',
+      '整体更接近 Toca 式“世界菜单”感，但美术要更像绘本插画，不要扁平矢量 UI，也不要把地图画成球体。',
+    ].join(''),
+  },
+];
+
+function readDotenv(fileName) {
+  const filePath = path.join(repoRoot, fileName);
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+    let value = match[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[match[1]] = value;
+  }
+  return values;
+}
+
+function resolveEnv() {
+  const loaded = {
+    ...readDotenv('.env.example'),
+    ...readDotenv('.env.local'),
+    ...readDotenv('.env.secrets.local'),
+    ...process.env,
+  };
+  return {
+    baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '')
+      .trim()
+      .replace(/\/+$/u, ''),
+    apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(),
+    timeoutMs: Number.parseInt(
+      String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
+      10,
+    ),
+  };
+}
+
+function generationUrl(baseUrl) {
+  return baseUrl.endsWith('/v1')
+    ? `${baseUrl}/images/generations`
+    : `${baseUrl}/v1/images/generations`;
+}
+
+function collectStringsByKey(value, targetKey, output) {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectStringsByKey(entry, targetKey, output));
+    return;
+  }
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === targetKey) {
+      if (typeof nested === 'string' && nested.trim()) {
+        output.push(nested.trim());
+      }
+      if (Array.isArray(nested)) {
+        nested.forEach((entry) => {
+          if (typeof entry === 'string' && entry.trim()) {
+            output.push(entry.trim());
+          }
+        });
+      }
+    }
+    collectStringsByKey(nested, targetKey, output);
+  }
+}
+
+function inferExtensionFromBytes(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from('\x89PNG\r\n\x1A\n', 'binary'))) {
+    return 'png';
+  }
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff]))) {
+    return 'jpg';
+  }
+  if (
+    bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'webp';
+  }
+  return 'png';
+}
+
+function inferExtensionFromContentType(contentType) {
+  const normalized = contentType.split(';')[0]?.trim().toLowerCase();
+  if (normalized === 'image/png') {
+    return 'png';
+  }
+  if (normalized === 'image/webp') {
+    return 'webp';
+  }
+  if (normalized === 'image/jpeg') {
+    return 'jpg';
+  }
+  return 'png';
+}
+
+function toDataUrl(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  const bytes = readFileSync(filePath);
+  const extension = inferExtensionFromBytes(bytes);
+  const mime = extension === 'jpg' ? 'image/jpeg' : `image/${extension}`;
+  return `data:${mime};base64,${bytes.toString('base64')}`;
+}
+
+function buildRequestBody(concept, size, hasStyleReference) {
+  const body = {
+    model: 'gpt-image-2-all',
+    prompt: concept.prompt,
+    n: 1,
+    size,
+  };
+  if (hasStyleReference) {
+    const ref = toDataUrl(styleReferencePath);
+    if (ref) {
+      body.image = [ref];
+    }
+  }
+  return body;
+}
+
+function buildDryRunRequestBody(concept, size, hasStyleReference) {
+  return {
+    model: 'gpt-image-2-all',
+    prompt: concept.prompt,
+    n: 1,
+    size,
+    imageReferenceCount: hasStyleReference ? 1 : 0,
+  };
+}
+
+async function fetchJson(url, options, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: abortController.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`);
+    }
+    return JSON.parse(text);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function downloadUrl(url, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: abortController.signal });
+    if (!response.ok) {
+      throw new Error(`download ${response.status}`);
+    }
+    return {
+      bytes: Buffer.from(await response.arrayBuffer()),
+      extension: inferExtensionFromContentType(
+        response.headers.get('content-type') || '',
+      ),
+    };
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`Generated image download timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function outputPathFor(concept, extension = 'png') {
+  return path.join(outDir, `${concept.id}.${extension}`);
+}
+
+function findExistingOutputPath(concept) {
+  for (const extension of ['png', 'jpg', 'jpeg', 'webp']) {
+    const candidate = outputPathFor(concept, extension);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function generateOne(env, concept, size) {
+  const payload = await fetchJson(
+    generationUrl(env.baseUrl),
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(buildRequestBody(concept, size, existsSync(styleReferencePath))),
+    },
+    env.timeoutMs,
+  );
+
+  const urls = [];
+  const b64Images = [];
+  collectStringsByKey(payload, 'url', urls);
+  collectStringsByKey(payload, 'image', urls);
+  collectStringsByKey(payload, 'image_url', urls);
+  collectStringsByKey(payload, 'b64_json', b64Images);
+
+  let image;
+  const imageUrl = [...new Set(urls)].find((url) => /^https?:\/\//u.test(url));
+  if (imageUrl) {
+    image = await downloadUrl(imageUrl, env.timeoutMs);
+  } else if (b64Images[0]) {
+    const bytes = Buffer.from(b64Images[0], 'base64');
+    image = {
+      bytes,
+      extension: inferExtensionFromBytes(bytes),
+    };
+  } else {
+    throw new Error(`VectorEngine returned no image for ${concept.id}`);
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const outputPath = outputPathFor(concept, image.extension);
+  writeFileSync(outputPath, image.bytes);
+  return outputPath;
+}
+
+const args = new Map();
+for (let index = 2; index < process.argv.length; index += 1) {
+  const raw = process.argv[index];
+  if (raw.startsWith('--')) {
+    const next = process.argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      args.set(raw, next);
+      index += 1;
+    } else {
+      args.set(raw, true);
+    }
+  }
+}
+
+const size = String(args.get('--size') || '2048x1152');
+const dryRun = args.has('--dry-run') || !args.has('--live');
+const selectedIds = String(args.get('--only') || '')
+  .split(',')
+  .map((value) => value.trim())
+  .filter(Boolean);
+const selectedConcepts = concepts.filter(
+  (concept) => selectedIds.length === 0 || selectedIds.includes(concept.id),
+);
+const hasStyleReference = existsSync(styleReferencePath);
+
+if (dryRun) {
+  console.log(
+    JSON.stringify(
+      {
+        mode: 'dry-run',
+        outDir,
+        size,
+        hasStyleReference,
+        count: selectedConcepts.length,
+        requests: selectedConcepts.map((concept) => ({
+          id: concept.id,
+          title: concept.title,
+          body: buildDryRunRequestBody(concept, size, hasStyleReference),
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+
+const env = resolveEnv();
+if (!env.baseUrl || !env.apiKey) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY',
+      hasBaseUrl: Boolean(env.baseUrl),
+      hasApiKey: Boolean(env.apiKey),
+    }),
+  );
+  process.exit(1);
+}
+
+const files = [];
+const generatedFileById = new Map();
+for (const concept of selectedConcepts) {
+  console.log(`Generating ${concept.id}...`);
+  const file = await generateOne(env, concept, size);
+  files.push(file);
+  generatedFileById.set(concept.id, file);
+}
+
+const metadataFiles = concepts
+  .map((concept) => {
+    const file = generatedFileById.get(concept.id) ?? findExistingOutputPath(concept);
+    if (!file) {
+      return null;
+    }
+    return {
+      id: concept.id,
+      title: concept.title,
+      file,
+      prompt: concept.prompt,
+    };
+  })
+  .filter(Boolean);
+
+writeFileSync(
+  path.join(outDir, 'generation-metadata.json'),
+  JSON.stringify(
+    {
+      model: 'gpt-image-2-all',
+      size,
+      generatedAt: new Date().toISOString(),
+      styleReference: hasStyleReference ? styleReferencePath : null,
+      generatedIds: selectedConcepts.map((concept) => concept.id),
+      files: metadataFiles,
+    },
+    null,
+    2,
+  ),
+);
+
+console.log(JSON.stringify({ ok: true, count: files.length, files }, null, 2));