Merge remote-tracking branch 'origin/master' into feat/ui-editor-v3

# Conflicts:
#	docs/project-memory/shared-memory/pitfalls.md

apps/ai-game-creator-shell/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genarrative/ai-game-creator-shell",
   "private": true,
-  "version": "0.1.29",
+  "version": "0.1.45",
   "type": "module",
   "scripts": {
     "dev": "node scripts/start-tauri-dev.mjs",
@@ -57,6 +57,7 @@
     "react-colorful": "^5.8.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
     "vite": "^6.2.0",
     "zustand": "^5.0.14"

apps/ai-game-creator-shell/scripts/check-config.mjs

@@ -113,6 +113,11 @@ const allowedUncalledTauriCommands = [
   'chat_with_game_creator_agent',
   'check_ui_editor_font_glyph_coverage',
   'create_ui_design_resource',
+  // 图片类生成的同步变体：GUI 已改为 `start_local_project_asset_generation` + 项目内任务账本
+  // （提交即返回、后台生成）。这条命令**没有生产调用方**，只有 Rust 集成测试
+  // （`src/tests/project.rs`）与 `commands.rs` 单测在调；待后续批次删除，或改为转调
+  // `start_local_project_asset_generation`。
+  'generate_local_project_asset',
   'open_game_creator_launcher_window',
   'open_game_creator_workspace_window',
   'read_direct_project_conversation',
@@ -1290,7 +1295,7 @@ for (const requiredSource of [
   }
 }
 
-if (tauriConfig.productName !== 'Genarrative AI Game Creator') {
+if (tauriConfig.productName !== '陶泥儿') {
   throw new Error('AI game creator shell productName drifted');
 }
 
@@ -1302,19 +1307,19 @@ const expectedBundledDesignAgentResources = {
   'design-agent': 'design-agent',
 };
 const expectedBundledWindowsResources = {
-  'resources/codex/win-x64/bin/codex.exe': 'codex/win-x64/bin/codex.exe',
+  'resources/codex/win-x64/bin/codex.exe': 'coding-agent/win-x64/bin/codex.exe',
   'resources/codex/win-x64/bin/codex-code-mode-host.exe':
-    'codex/win-x64/bin/codex-code-mode-host.exe',
+    'coding-agent/win-x64/bin/codex-code-mode-host.exe',
   'resources/codex/win-x64/codex-path/rg.exe':
-    'codex/win-x64/codex-path/rg.exe',
+    'coding-agent/win-x64/codex-path/rg.exe',
   'resources/codex/win-x64/codex-resources/codex-command-runner.exe':
-    'codex/win-x64/codex-resources/codex-command-runner.exe',
+    'coding-agent/win-x64/codex-resources/codex-command-runner.exe',
   'resources/codex/win-x64/codex-resources/codex-windows-sandbox-setup.exe':
-    'codex/win-x64/codex-resources/codex-windows-sandbox-setup.exe',
+    'coding-agent/win-x64/codex-resources/codex-windows-sandbox-setup.exe',
   'resources/codex/win-x64/codex-package.json':
-    'codex/win-x64/codex-package.json',
-  'resources/codex/win-x64/NOTICE.md': 'codex/win-x64/NOTICE.md',
-  'resources/codex/win-x64/manifest.json': 'codex/win-x64/manifest.json',
+    'coding-agent/win-x64/codex-package.json',
+  'resources/codex/win-x64/NOTICE.md': 'coding-agent/win-x64/NOTICE.md',
+  'resources/codex/win-x64/manifest.json': 'coding-agent/win-x64/manifest.json',
   'resources/plugins': 'plugins',
 };
 assert.deepEqual(

apps/ai-game-creator-shell/scripts/dev-port.mjs

@@ -9,6 +9,10 @@ import {
 const agcDevHost = '127.0.0.1';
 const legacyAgcDevPort = 3080;
 const agcVitePortEnvKey = 'GENARRATIVE_AGC_VITE_PORT';
+const agcAdminWebHost = '127.0.0.1';
+const legacyAgcAdminWebPort = 3102;
+// 与 scripts/dev.mjs 的后台 Web 端口配置保持同一环境变量名。
+const agcAdminWebPortEnvKey = 'ADMIN_WEB_PORT';
 
 function readConfiguredAgcDevPort(env = process.env) {
   const rawPort = String(env[agcVitePortEnvKey] ?? '').trim();
@@ -99,13 +103,100 @@ function withAgcDevEndpointEnv(endpoint, env = process.env) {
   };
 }
 
+function readConfiguredAgcAdminWebPort(env = process.env) {
+  const rawPort = String(env[agcAdminWebPortEnvKey] ?? '').trim();
+  if (!rawPort) {
+    return null;
+  }
+
+  const port = normalizePort(rawPort, -1);
+  if (port < 1024) {
+    throw new Error(`${agcAdminWebPortEnvKey} 必须是 1024-65535 的有效端口`);
+  }
+  return port;
+}
+
+function createAgcAdminWebEndpoint(port, portRange = null) {
+  const origin = `http://${agcAdminWebHost}:${port}`;
+  return {
+    host: agcAdminWebHost,
+    port,
+    origin,
+    basePath: '/admin/',
+    url: `${origin}/admin/`,
+    portRange,
+  };
+}
+
+// AGC 开发态的后台 Web 与 `npm run dev` 的后台 Vite 共用同一套优先端口约定：
+// Linux 取当前用户端口段的 `start + 3` 槽位，非 Linux 保留 `3102` 兼容首选并允许统一漂移。
+async function resolveAgcAdminWebEndpoint({
+  env = process.env,
+  platform = process.platform,
+  strictConfigured = false,
+  reservedPorts = [],
+  reservePortRange = reserveLinuxDevPortRange,
+  findPort = findAvailablePort,
+} = {}) {
+  const configuredPort = readConfiguredAgcAdminWebPort(env);
+  let portRange = null;
+  let preferredPort = configuredPort ?? legacyAgcAdminWebPort;
+
+  if (platform === 'linux') {
+    const allocation = await reservePortRange({ env });
+    if (!allocation?.range) {
+      throw new Error('无法取得当前 Linux 用户的 dev 端口段');
+    }
+    portRange = allocation.range;
+    const mappedAdminWebPort = mapDevPortsToPortRange(portRange)?.adminWebPort;
+    if (!Number.isInteger(mappedAdminWebPort)) {
+      throw new Error(
+        `当前 Linux dev 端口段 ${portRange.label} 缺少后台 Web 槽位；请先迁移为至少 6 个端口且不与其它用户重叠的端口段`,
+      );
+    }
+    preferredPort = configuredPort ?? mappedAdminWebPort;
+  }
+
+  const reservedPortSet = new Set(
+    reservedPorts.filter((value) => Number.isInteger(value) && value > 0),
+  );
+  const port = await findPort({
+    host: agcAdminWebHost,
+    preferredPort,
+    portRange,
+    reservedPorts: reservedPortSet,
+    strict: strictConfigured && configuredPort != null,
+  });
+  console.log(
+    formatPortDecision({
+      name: 'ai-game-creator-shell-admin-web',
+      host: agcAdminWebHost,
+      preferredPort,
+      resolvedPort: port,
+    }),
+  );
+  if (portRange) {
+    console.log(
+      `[ai-game-creator-shell] admin-web port-range: ${portRange.label}`,
+    );
+  }
+
+  return createAgcAdminWebEndpoint(port, portRange);
+}
+
 export {
+  agcAdminWebHost,
+  agcAdminWebPortEnvKey,
   agcDevHost,
   agcVitePortEnvKey,
+  createAgcAdminWebEndpoint,
   createAgcDevEndpoint,
+  legacyAgcAdminWebPort,
   legacyAgcDevPort,
   readAgcDevEndpoint,
+  readConfiguredAgcAdminWebPort,
   readConfiguredAgcDevPort,
+  resolveAgcAdminWebEndpoint,
   resolveAgcDevEndpoint,
   withAgcDevEndpointEnv,
 };

apps/ai-game-creator-shell/scripts/start-dev-stack.mjs

@@ -14,12 +14,14 @@ import {
 import {
   agcVitePortEnvKey,
   readAgcDevEndpoint,
+  resolveAgcAdminWebEndpoint,
   resolveAgcDevEndpoint,
   withAgcDevEndpointEnv,
 } from './dev-port.mjs';
 
 const appRoot = fileURLToPath(new URL('..', import.meta.url));
 const repoRoot = resolve(appRoot, '../..');
+const adminWebDir = resolve(repoRoot, 'apps/admin-web');
 const devStackStatePath = resolve(repoRoot, '.app/dev-stack.json');
 const apiServerExePath = resolve(
   repoRoot,
@@ -32,6 +34,8 @@ const backendSpacetimeDataDir = resolve(
   repoRoot,
   'server-rs/.spacetimedb/ai-game-creator/data',
 );
+// 后台 Web 默认跟随 AGC 一起起来，便于联调后台页面；`AGC_DEV_ADMIN_WEB=0` 可关闭。
+const agcDevAdminWebEnvKey = 'AGC_DEV_ADMIN_WEB';
 const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const childLifecycles = new WeakMap();
 
@@ -200,36 +204,122 @@ function urlPort(url) {
   }
 }
 
-// 读取端口当前真正的监听进程身份。返回 null 表示探测本身不可用（例如缺少
-// Get-NetTCPConnection），此时调用方必须退化为旧行为，不能让本地启动直接失败。
+// 端口归属探测脚本。历史实现用 `Get-NetTCPConnection` 取监听进程，而它底层走
+// WMI：实测单端口单次 11.2 秒、再叠加每个 PID 的 `Get-CimInstance` 3.3 秒，
+// 一轮探测约 43 秒，直接把"配套后端就绪"等待拖到分钟级。改用原生
+// `netstat -ano`（约 30 毫秒）取端口 -> PID，再用 .NET `Process` 读进程名和
+// 可执行文件路径（毫秒级）；只有核对 SpacetimeDB `--data-dir` 归属时才按 PID
+// 取命令行，并允许调用方把已知命令行传进来复用。
+const windowsPortOwnerProbeCommand = [
+  '$ErrorActionPreference = "SilentlyContinue"',
+  '$queriedPorts = @()',
+  'foreach ($raw in ($env:GENARRATIVE_QUERY_PORTS -split ",")) {',
+  '  if ($raw -match "^\\d+$") { $queriedPorts += [int]$raw }',
+  '}',
+  '$knownCommandLines = @{}',
+  'if ($env:GENARRATIVE_KNOWN_COMMAND_LINES) {',
+  '  try {',
+  '    foreach ($property in (ConvertFrom-Json $env:GENARRATIVE_KNOWN_COMMAND_LINES).PSObject.Properties) {',
+  '      $knownCommandLines[[int]$property.Name] = [string]$property.Value',
+  '    }',
+  '  } catch { }',
+  '}',
+  '$listenerPidByPort = @{}',
+  'foreach ($line in (netstat -ano -p tcp)) {',
+  '  $fields = @($line -split "\\s+" | Where-Object { $_ })',
+  '  if ($fields.Count -lt 4) { continue }',
+  '  if ($fields[0] -ne "TCP") { continue }',
+  '  # A listening socket always has foreign address 0.0.0.0:0 / [::]:0, which',
+  '  # is locale-independent unlike the localized netstat State column.',
+  '  if ($fields[2] -notmatch ":0$") { continue }',
+  '  $localPort = [int]($fields[1].Split(":")[-1])',
+  '  if ($queriedPorts -notcontains $localPort) { continue }',
+  '  # The PID is the last column; do not hardcode its index.',
+  '  if ($fields[-1] -notmatch "^\\d+$") { continue }',
+  '  $listenerPidByPort[$localPort] = [int]$fields[-1]',
+  '}',
+  '$result = @()',
+  'foreach ($port in ($listenerPidByPort.Keys | Sort-Object)) {',
+  '  $processId = $listenerPidByPort[$port]',
+  '  $name = $null',
+  '  $executablePath = $null',
+  '  $commandLine = $null',
+  '  try {',
+  '    $process = [System.Diagnostics.Process]::GetProcessById($processId)',
+  '    $name = $process.ProcessName + ".exe"',
+  '    try { $executablePath = $process.MainModule.FileName } catch { }',
+  '  } catch { }',
+  '  if ($knownCommandLines.ContainsKey($processId)) {',
+  '    $commandLine = $knownCommandLines[$processId]',
+  '  } elseif (($name -like "spacetime*") -or (-not $executablePath)) {',
+  '    try { $commandLine = (Get-CimInstance Win32_Process -Filter ("ProcessId=" + $processId)).CommandLine } catch { }',
+  '  }',
+  '  $result += [pscustomobject]@{ port = [int]$port; processId = $processId; name = $name; executablePath = $executablePath; commandLine = $commandLine }',
+  '}',
+  'ConvertTo-Json -InputObject @($result) -Compress',
+].join('\n');
+
+// 进程命令行在进程生命周期内不变，但 PID 会被系统复用；按 PID 记 TTL 缓存，
+// 让"等配套后端就绪"的轮询只在首个周期付出 WMI 成本。TTL 取 5 分钟：本轮实测
+// 这台机器上首次 WMI 调用约 18 秒（热调用 3.3 秒），而 PID 在 5 分钟内被复用
+// 成另一个运行本工作树 data dir 的 SpacetimeDB 才能造成误判，概率可忽略。
+// 默认实现才缓存，注入实现（测试）与显式 env 始终重新读取。
+const WINDOWS_COMMAND_LINE_CACHE_TTL_MS = 300_000;
+const windowsPortOwnerCommandLineCache = new Map();
+
+function resolveCommandLineCache({ spawnImpl, env }) {
+  return spawnImpl === spawnSync && env === process.env
+    ? windowsPortOwnerCommandLineCache
+    : new Map();
+}
+
+// 读取端口当前真正的监听进程身份。返回 null 表示探测本身不可用（例如系统缺少
+// netstat），此时调用方必须退化为旧行为，不能让本地启动直接失败。
 function readWindowsPortOwnerIdentities(
   ports,
-  { spawnImpl = spawnSync, env = process.env } = {},
+  {
+    spawnImpl = spawnSync,
+    env = process.env,
+    now = Date.now,
+    commandLineTtlMs = WINDOWS_COMMAND_LINE_CACHE_TTL_MS,
+    commandLineCache = resolveCommandLineCache({ spawnImpl, env }),
+  } = {},
 ) {
   const uniquePorts = [...new Set(ports.filter((port) => port > 0))];
   if (uniquePorts.length === 0) {
     return null;
   }
 
-  const command = [
-    '$ErrorActionPreference = "SilentlyContinue"',
-    '$ports = ($env:GENARRATIVE_QUERY_PORTS -split ",") | Where-Object { $_ }',
-    '$result = @()',
-    'foreach ($port in $ports) {',
-    '  $connection = Get-NetTCPConnection -State Listen -LocalPort ([int]$port) -ErrorAction SilentlyContinue | Select-Object -First 1',
-    '  if (-not $connection) { continue }',
-    '  $owner = Get-CimInstance Win32_Process -Filter ("ProcessId=" + $connection.OwningProcess) -ErrorAction SilentlyContinue',
-    '  $result += [pscustomobject]@{ port = [int]$port; processId = [int]$connection.OwningProcess; name = $owner.Name; executablePath = $owner.ExecutablePath; commandLine = $owner.CommandLine }',
-    '}',
-    'ConvertTo-Json -InputObject @($result) -Compress',
-  ].join('\n');
+  const knownCommandLines = {};
+  for (const [processId, record] of [...commandLineCache]) {
+    if (record && now() - record.at < commandLineTtlMs) {
+      knownCommandLines[processId] = record.commandLine;
+    } else {
+      commandLineCache.delete(processId);
+    }
+  }
+
+  const childEnv = {
+    ...env,
+    GENARRATIVE_QUERY_PORTS: uniquePorts.join(','),
+  };
+  if (Object.keys(knownCommandLines).length > 0) {
+    childEnv.GENARRATIVE_KNOWN_COMMAND_LINES =
+      JSON.stringify(knownCommandLines);
+  }
 
   const result = spawnImpl(
     'powershell.exe',
-    ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', command],
+    [
+      '-NoProfile',
+      '-ExecutionPolicy',
+      'Bypass',
+      '-Command',
+      windowsPortOwnerProbeCommand,
+    ],
     {
       encoding: 'utf8',
-      env: { ...env, GENARRATIVE_QUERY_PORTS: uniquePorts.join(',') },
+      env: childEnv,
       maxBuffer: 8 * 1024 * 1024,
     },
   );
@@ -240,9 +330,22 @@ function readWindowsPortOwnerIdentities(
   const owners = new Map();
   for (const entry of parseWindowsProcessSnapshot(result.stdout)) {
     const port = Number(entry?.port);
-    if (Number.isInteger(port) && port > 0) {
-      owners.set(port, entry);
+    if (!Number.isInteger(port) || port <= 0) {
+      continue;
     }
+    const processId = Number(entry?.processId);
+    if (
+      Number.isInteger(processId) &&
+      processId > 0 &&
+      typeof entry?.commandLine === 'string' &&
+      entry.commandLine
+    ) {
+      commandLineCache.set(processId, {
+        commandLine: entry.commandLine,
+        at: now(),
+      });
+    }
+    owners.set(port, entry);
   }
   return owners;
 }
@@ -879,10 +982,102 @@ async function startVite(apiTarget, endpoint = readAgcDevEndpoint()) {
   );
 }
 
+function readAdminWebEnabled(env = process.env) {
+  return String(env[agcDevAdminWebEnvKey] ?? '').trim() !== '0';
+}
+
+// 后台 Web 与 AGC Vite 一样直接由本启动器持有，不经过 `dev.mjs admin-web`：
+// 后者会整体重写 `.app/dev-stack.json`，把本次配套后端的状态覆盖掉。
+function startAdminWeb(
+  apiUrl,
+  endpoint,
+  { env = process.env, spawnImpl = spawnChild } = {},
+) {
+  return spawnImpl(
+    npm,
+    [
+      '--prefix',
+      '../..',
+      'exec',
+      'vite',
+      '--',
+      '--host',
+      endpoint.host,
+      '--port',
+      String(endpoint.port),
+      '--strictPort',
+    ],
+    {
+      cwd: adminWebDir,
+      env: {
+        ...env,
+        ADMIN_API_TARGET: apiUrl,
+        GENARRATIVE_API_TARGET: apiUrl,
+        GENARRATIVE_API_PORT: String(urlPort(apiUrl) || 8082),
+        ADMIN_WEB_BASE: endpoint.basePath,
+      },
+    },
+  );
+}
+
+function formatStartupSummary({
+  frontendUrl = '',
+  apiUrl = '',
+  adminWebUrl = '',
+  spacetimeUrl = '',
+  bgfilterWorkerUrl = '',
+} = {}) {
+  const segments = [
+    ['前端', frontendUrl],
+    ['后端', apiUrl],
+    ['后台', adminWebUrl],
+    ['数据库', spacetimeUrl],
+    ['bgfilter-worker', bgfilterWorkerUrl],
+  ]
+    .filter(([, value]) => Boolean(value))
+    .map(([label, value]) => `${label} ${value}`);
+  return `[ai-game-creator-shell] 启动汇总: ${segments.join(' | ')}`;
+}
+
+// 后台 Web 是可选联调服务：端口解析或启动失败只告警，不能阻断 AGC 客户端与配套后端。
+async function ensureAdminWeb({
+  apiUrl,
+  reservedPorts = [],
+  env = process.env,
+  enabled = readAdminWebEnabled(env),
+  resolveEndpoint = resolveAgcAdminWebEndpoint,
+  spawnAdminWeb = startAdminWeb,
+  waitForExit = waitForChildTermination,
+  warn = (message) => console.warn(message),
+} = {}) {
+  if (!enabled) {
+    return { endpoint: null, child: null };
+  }
+
+  try {
+    const endpoint = await resolveEndpoint({ env, reservedPorts });
+    const child = spawnAdminWeb(apiUrl, endpoint, { env });
+    waitForExit(child).then((failure) => {
+      warn(
+        `[ai-game-creator-shell] 后台 Web 已退出（${formatChildFailure(failure)}），AGC 继续运行。`,
+      );
+    });
+    return { endpoint, child };
+  } catch (error) {
+    warn(
+      `[ai-game-creator-shell] 后台 Web 未能启动（${
+        error instanceof Error ? error.message : String(error)
+      }），AGC 继续运行。`,
+    );
+    return { endpoint: null, child: null };
+  }
+}
+
 async function main() {
   let backendChild = null;
   let startedBackend = false;
   let viteChild = null;
+  let adminWebChild = null;
   let shutdownSignal = '';
   const signalHandlers = new Map();
 
@@ -905,6 +1100,7 @@ async function main() {
     const handler = () => {
       shutdownSignal = signal;
       stopChild(viteChild, signal);
+      stopChild(adminWebChild, signal);
       stopChild(backendChild, signal);
       // 立刻清扫，避免外层 taskkill /F 抢在 finally 之前把本进程杀掉。
       sweepStartedBackend();
@@ -937,6 +1133,25 @@ async function main() {
       throw new Error(`启动期收到 ${shutdownSignal}，已停止前端服务`);
     }
 
+    const adminWeb = await ensureAdminWeb({
+      apiUrl: backend.targets.apiUrl,
+      // AGC Vite 端口尚未监听，必须显式保留，避免被后台 Web 抢先占用。
+      reservedPorts: [endpoint.port],
+    });
+    adminWebChild = adminWeb.child;
+    if (shutdownSignal) {
+      throw new Error(`启动期收到 ${shutdownSignal}，已停止后台 Web`);
+    }
+    console.log(
+      formatStartupSummary({
+        frontendUrl: endpoint.url,
+        apiUrl: backend.targets.apiUrl,
+        adminWebUrl: adminWeb.endpoint?.url ?? '',
+        spacetimeUrl: backend.targets.spacetimeUrl,
+        bgfilterWorkerUrl: backend.targets.bgfilterWorkerUrl,
+      }),
+    );
+
     const children = [backendChild, viteChild].filter(Boolean);
     if (children.length === 0) {
       return 0;
@@ -946,10 +1161,12 @@ async function main() {
       children.map((child) => waitForChildTermination(child)),
     );
     stopChild(viteChild);
+    stopChild(adminWebChild);
     stopChild(backendChild);
     return failure.type === 'error' || failure.signal ? 1 : (failure.code ?? 0);
   } catch (error) {
     stopChild(viteChild);
+    stopChild(adminWebChild);
     stopChild(backendChild);
     console.error(
       `[ai-game-creator-shell] ${error instanceof Error ? error.message : String(error)}`,
@@ -958,6 +1175,7 @@ async function main() {
   } finally {
     await Promise.all([
       terminateChildTree(viteChild),
+      terminateChildTree(adminWebChild),
       terminateChildTree(backendChild),
     ]);
     sweepStartedBackend();
@@ -975,9 +1193,12 @@ function isDirectModuleExecution() {
 }
 
 export {
+  agcDevAdminWebEnvKey,
+  ensureAdminWeb,
   ensureBackend,
   formatChildFailure,
   formatOwnerLabel,
+  formatStartupSummary,
   isAiGameCreatorServer,
   isBackendReady,
   isDirectModuleExecution,
@@ -985,6 +1206,7 @@ export {
   isWorktreeApiServerOwner,
   isWorktreeSpacetimeOwner,
   preflightExistingVite,
+  readAdminWebEnabled,
   readBackendServiceFailure,
   readChildFailure,
   readExistingViteServer,
@@ -993,6 +1215,7 @@ export {
   resolveBackendTargetsFromState,
   runWindowsTaskkill,
   spawnChild,
+  startAdminWeb,
   stopChild,
   terminateChildTree,
   verifyAgcBackendOwnership,

apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs

@@ -22,7 +22,6 @@ const appRoot = fileURLToPath(new URL('..', import.meta.url));
 const repoRoot = resolve(appRoot, '../..');
 const tauriCliPath = resolve(repoRoot, 'node_modules/@tauri-apps/cli/tauri.js');
 const AGC_DESIGN_DEBUG_ENV = 'GENARRATIVE_AGC_DESIGN_DEBUG';
-const AGC_DESIGN_DEBUG_VITE_ENV = 'VITE_GENARRATIVE_AGC_DESIGN_DEBUG';
 const designDebugEnabled =
   process.env[AGC_DESIGN_DEBUG_ENV]?.trim() === '0' ? '0' : '1';
 
@@ -137,7 +136,6 @@ async function runTauriDev(
       env: {
         ...withAgcDevEndpointEnv(endpoint),
         [AGC_DESIGN_DEBUG_ENV]: designDebugEnabled,
-        [AGC_DESIGN_DEBUG_VITE_ENV]: designDebugEnabled,
       },
     });
     const childResult = waitForCli(child);
@@ -191,7 +189,6 @@ async function prepareFrontendDev(endpoint, { onChild, signal }) {
       cwd: repoRoot,
       env: {
         ...withAgcDevEndpointEnv(endpoint),
-        [AGC_DESIGN_DEBUG_VITE_ENV]: designDebugEnabled,
       },
     },
   );

apps/ai-game-creator-shell/src-tauri/Cargo.lock

@@ -1725,7 +1725,7 @@ dependencies = [
 
 [[package]]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.29"
+version = "0.1.45"
 dependencies = [
  "agent-runtime-core",
  "axum",

apps/ai-game-creator-shell/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.29"
+version = "0.1.45"
 edition = "2021"
 publish = false
 

apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/overview-card.md

@@ -1,4 +1,4 @@
-概念阶段定稿时，还必须创建或更新 `project/速览卡.md`。Runtime 只检查该文件是否存在，不检查内容。请使用下面的固定结构，不要加入审批操作说明或独立的决定状态段落：
+概念阶段定稿时，创建或更新 `project/速览卡.md`。下面是速览卡的参考结构；根据游戏类型、项目规模和用户要求选择字段，同类内容可以合并，项目不需要的字段可以省略，复杂项目可以增加必要字段。表格和列表中的示例行可按实际对象逐行扩展，不代表数量上限：
 
 # 速览卡：《游戏名》
 
@@ -20,7 +20,7 @@
 
 ## 6. 核心循环
 
-## 7. 目标用户
+## 7. 目标用户与情境
 - 核心用户：
 - 游戏偏好：
 - 单次游玩时长：

apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-art-bible-SKILL.md

@@ -33,7 +33,7 @@ description: 写"美术圣经"（美术侧）分册时使用。与总纲（技
    对象（资产总清单的范围）、物品表（item_id 绑定依据，数据侧已定）、
    画风 skill（全局画风库可引用）。
 2. 本件在数据侧表结构定稿后开写（素材清单引用 item_id）。
-3. 读金样 exemplars/stardew-tdd-art-bible.md——契约表与资产状态表的登记密度以它为准（同层只读一次）。
+3. 读取金样 exemplars/stardew-tdd-art-bible.md 了解契约表与资产状态表包含的信息类型（同层只读一次）。
 
 ## 三、怎么写（模板即流程，按节）
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-data-SKILL.md

@@ -34,7 +34,7 @@ description: 写"数据与配表"（数据侧）分册时使用。与总纲（
    （架构层的定性基准，在本件落成前 N 日验算）。
 2. 先读两份提取件：字段字典全套规则与验收模板已在那里成文，本件是
    项目实例化，不是重新发明。
-3. 读金样 exemplars/stardew-tdd-data.md——总清单规模、验算表与验收结论的写法以它为准（同层只读一次）。
+3. 读取金样 exemplars/stardew-tdd-data.md 了解数据清单、验算表与验收结论包含的信息类型（同层只读一次）。
 
 ## 三、怎么写（模板即流程，按节）
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-tech-SKILL.md

@@ -28,7 +28,7 @@ description: 写"技术实现"（程序侧）分册时使用。与总纲（技
 1. 输入齐了吗：架构层系统范围表+P0 清单（拆模块依据）、数据侧表结构契约
    （加载与校验要引用）、skill 选型卡（实现类需求先查卡，不自造轮子）。
 2. 读总纲判断立场；本件在数据侧表结构定稿后开写。
-3. 读金样 exemplars/stardew-tdd-tech.md——各节的填充密度与"实证参照"写法以它为准（同层只读一次）。
+3. 读取金样 exemplars/stardew-tdd-tech.md 了解技术实现文档包含的信息类型（同层只读一次）。
 
 ## 三、怎么写（模板即流程，按节）
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md

@@ -13,10 +13,13 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计
 > 本文件是系统架构层唯一承载写作流程的教学件。
 > 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。
 
+## 〇、结构适配原则
+
+本分册的章节、字段和数量是参考结构，不是固定清单。先根据游戏类型、项目规模、用户要求和顶层设计判断适用项：适用项写入，同类项可合并，若某项对本项目没意义则省略；复杂项目可以拆分补充，简单项目可以压缩为最小可用架构。
+
 ## 一、这一层的判断立场
 你是架构师，切系统的刀在你手里。在这个层里你相信：
-- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量——每个系统必须能
-  一句话答出"删了它，什么塌"（P0 原因）。
+- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量。只有确实需要独立职责、状态或数据边界的部分才拆成系统；每个实际拆出的系统应能说明删除后的影响。
 - **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID，
   不复制主数据。两个系统管同一件事 = 架构事故。
 - **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。
@@ -28,11 +31,11 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计
 ## 二、动笔前
 1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束**
    摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。
-2. 读 exemplars/stardew-architecture.md 做质量锚（模仿密度，不抄内容），
+2. 读取 exemplars/stardew-architecture.md 了解内容组织方式，
    然后往 templates/architecture.md 里填。
 3. 记住顶层的核心循环图——切完必须跑覆盖检查。
 
-## 三、十二节总览：写什么、为什么、怎么咬合
+## 三、架构设计的组织维度：写什么、为什么、怎么咬合
 
 架构文档回答四个问题：
 **这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→
@@ -74,7 +77,7 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计
 三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖
 三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档站。
 
-## 四、怎么写（模板即流程，十二节按序）
+## 四、怎么写（模板参考结构，建议按此组织）
 （本节是带写法要领的教学版；实际填写的纯净模板在 templates/architecture.md）
 
 ### 1. 架构定位与目标
@@ -85,10 +88,10 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计
 → 没有变更记录的架构文档，第二轮迭代就会变成黑箱。
 
 ### 2. 系统地图
-Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。
+Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。
 P0 段五列表：
 | 系统 | 目的 | 输入 | 输出 | P0 原因 |
-→ 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。
+→ 对实际拆出的系统说明删除后的影响；无法形成独立职责的部分合并，不为满足数量新增系统。
 
 ### 3. 系统职责
 | 系统 | 主要职责 | 不负责 → 移交谁 |

apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md

@@ -13,6 +13,10 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 > 本文件是概念层唯一承载写作流程的教学件。
 > 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。
 
+## 〇、结构适配原则
+
+本分册的章节、字段和数量是参考结构，不是固定清单。先根据游戏类型、项目规模、用户要求和上层已定范围判断适用项：适用项写入，同类项可合并，若某项对本项目没意义则省略；复杂项目可以拆分补充，简单项目可以压缩为最小可用规格。
+
 ## 一、这一层的判断立场
 你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。
 在这个层里你相信：
@@ -27,11 +31,11 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 ## 二、动笔前
 1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。
    没有 → 先问一个定调问题，禁止自问自答充当用户。
-2. 读 exemplars/stardew-concept.md 做质量锚（模仿密度，不抄内容），
+2. 读取 exemplars/stardew-concept.md 了解内容组织方式，
    然后往 templates/concept-design.md 里填。
 3. 零参照时在文档头注明"零参照"。
 
-## 三、九节总览：写什么、为什么、怎么咬合
+## 三、概念设计的组织维度：写什么、为什么、怎么咬合
 
 概念文档回答四个问题：
 **这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→
@@ -50,7 +54,7 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 | 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 |
 | 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 |
 | 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" |
-| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 给顶层的硬约束 | 收口重锤：写完九节重述一遍，检验整份文档有没有写散；把承诺变成对下的契约 | 回环呼应 1；把 8 的交接具体化成 2~4 条硬约束 |
+| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 按需记录给顶层的约束 | 收口并检查概念是否写散；把承诺转成对下的契约 | 回环呼应 1；把边界和交接约束传给下一层 |
 
 咬合一图：
 
@@ -69,7 +73,7 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束；
 **对上**边界画线防止越层。九节不是清单，是一台咬合的机器。
 
-## 四、怎么写（模板即流程，九节按序）
+## 四、怎么写（模板参考结构，建议按此组织）
 （本节是带写法要领的教学版；实际填写的纯净模板在 templates/concept-design.md）
 
 ### 1. 一句话概念
@@ -80,7 +84,7 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 **定调记录**（全项目调性真源，此节定死）：
 - 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。
 - 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。
-- 调性锚 T 原则：3~7 条逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。
+- 调性锚 T 原则：按项目需要提炼并逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。
   检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。
   → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。
 **设计锚点（六项，争议时的仲裁原则，全部具名）**
@@ -112,8 +116,7 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 ### 7. 核心张力
 - __ 有限，但 __。
 - __ vs __（两端的代价各是什么）。
-→ 每条两端都必须有代价，只有一端的"假张力"删掉。这些是顶层取舍表的
-  种子，后面要逐条对应。
+→ 如果项目存在核心张力，保留的每条张力都应说明双方代价；没有形成有效张力时，不为了满足结构新增张力。这些是顶层取舍表的种子，后面按需对应。
 
 ### 8. 边界与约束
 - 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、
@@ -124,9 +127,9 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 ### 9. 概念定稿（收口重锤）
 这个游戏的核心不是 __，而是：
 > （一句话重述核心承诺）
-交给下一层的约束：__ 必须 __（2~4 条，顶层必须围绕它们展开）。
+交给下一层的约束：按项目需要记录，顶层据此展开。
 
-某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。
+若某节对本项目没意义，直接省略。
 
 ## 五、分析文档（全局一份，按层分节）
 
@@ -158,4 +161,4 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏
 ## 七、红线（只有三条）
 1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。
 2. 不越层：出现具体数值、按键、界面即删。
-3. 不凑数：写不满就说明缺什么，禁止万金油句填充。
+3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。

apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md

@@ -2,7 +2,7 @@
 
 ---
 name: game-gdd-system-doc
-description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、
+description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、
   红线与分析文档格式。每类系统的专属写法与模板在 modules/system-types/ 下对应目录的 SKILL.md
   与对应模块的模板.md 里，按需取用。
 ---
@@ -12,6 +12,10 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪
 > 本文件是系统文档层的总纲；各系统的专属写法在 `modules/system-types/` 下对应目录的 `SKILL.md`，
   专属模板在 `modules/system-types/` 对应目录的 `模板.md`。通用纪律不在各系统 skill 里重复。
 
+## 〇、结构适配原则
+
+本分册的章节、字段和数量是参考结构，不是固定清单。先根据系统类型、实际复杂度、用户要求和架构职责判断适用项：适用项写入，同类项可合并，若某项对本系统没意义则省略；复杂系统可以拆分补充，简单系统可以压缩为最小可执行规格。
+
 ## 一、这一层的判断立场
 你是写单个系统的策划。在这个层里你相信：
 - 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表
@@ -20,15 +24,15 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪
   防返工价值最高的几行。
 - 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。
 - 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。
-- 所有系统同构：读者读熟一份就能读所有份。
+- 系统文档保持基本可读的一致性，但不要求所有系统使用相同章节；结构应服从系统类型和实际行为。
 
 ## 二、动笔前
 1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。
 2. 在 01~12 文件夹里选最接近的系统类型（可组合，如"钓鱼"=05 采集+06 战斗
    的判定部分），读取对应的 `SKILL.md` 与 `模板.md`。
-3. 该文件夹标注"必读例子"的，先读例子全文做密度锚。
+3. 该文件夹标注"参考例子"的，可先读例子了解写法。
 
-## 三、十二节总览：写什么、为什么、怎么咬合
+## 三、常见内容总览：写什么、为什么、怎么咬合
 
 系统文档回答四个问题：
 **这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→
@@ -43,7 +47,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪
 | 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 |
 | 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 |
 | 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 |
-| 8 | 反馈 | 何时/何强度/何通道 | 无反馈=没发生 | 顶层反馈四层 |
+| 8 | 反馈 | 关键结果何时、以何种方式反馈 | 让实际结果可理解 | 与本系统实际结果对应 |
 | 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 |
 | 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 |
 | 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 |
@@ -52,20 +56,20 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪
 咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越
 职责边界；**对下**第 7 节交接喂 TDD。
 
-## 四、十二节通用写法
+## 四、常见内容的参考写法
 （各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md）
 
 1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。
 2 支撑体验：对应顶层目标第__条、调性原则第__条。
-3 进入与退出：常规进入/读档恢复/特殊事件后返回，三入口必写。
-4 玩家行动：≥4 个具名动词组；编排类写"安排"动词，活动类写"操作"动词。
+3 进入与退出：按本系统实际存在的入口、退出和恢复路径记录。
+4 玩家行动：记录本系统实际存在的具名动词组；编排类写"安排"动词，活动类写"操作"动词。
 5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。
 6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。
 7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。
-8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。
+8 反馈：记录本系统关键结果的可理解反馈；存在失败时说明原因和恢复路径。
 9 内部循环：动词链；可拆单次/区域/长期三层。
 10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。
-11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。
+11 边界与非目标：参考该类型 skill 的“三不”说明边界；建议说明字段与数值的交接边界。
 12 开放问题：结构级才留；手感数值类标"待原型验证"。
 
 ## 五、分析文档（全局一份，按层分节）
@@ -100,4 +104,4 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪
 1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。
 2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD），
   不替别的系统定规则。
-3. 不凑数：写不出"删了塌什么"、填不满的节，说明缺料——停笔说明，不硬凑。
+3. 不凑数：写不出"删了塌什么"的系统直接删除；章节对项目有意义但信息不足时，记录已确定内容与待补问题。

apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md

@@ -13,6 +13,10 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定
 > 本文件是顶层设计唯一承载写作流程的教学件。
 > 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。
 
+## 〇、结构适配原则
+
+本分册的章节、字段和数量是参考结构，不是固定清单。先根据游戏类型、项目规模、用户要求和概念层定稿判断适用项：适用项写入，同类项可合并，若某项对本项目没意义则省略；复杂项目可以拆分补充，简单项目可以压缩为最小可用规格。
+
 ## 一、这一层的判断立场
 你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"，
 顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信：
@@ -26,11 +30,11 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定
 
 ## 二、动笔前
 1. 概念层 design.md 已定稿可用——顶层定位与取舍表直接从它长出来。
-2. 读 exemplars/stardew-top-design.md 做质量锚（模仿密度，不抄内容），
+2. 读取 exemplars/stardew-top-design.md 了解内容组织方式，
    然后往 templates/top-design.md 里填。
-3. 把概念层的核心张力清单摊开放在手边——取舍表必须逐条挂上编号。
+3. 把概念层已确认的核心张力作为输入；存在对应取舍时再挂上编号。
 
-## 三、十六节总览：写什么、为什么、怎么咬合
+## 三、顶层设计的组织维度：写什么、为什么、怎么咬合
 
 顶层文档回答四个问题：
 **玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→
@@ -43,14 +47,14 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定
 |---|---|---|---|---|
 | 1 | 顶层定位与规模锚点 | 承概念定稿 + "让玩家每天都在想"念头句 + 不是X不是Y + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 |
 | 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 |
-| 3 | 核心推动力 | 动机主次 + 即时/日程/季节/长期四层推动 | 玩家"什么时候被什么推着走"的完整图谱 | 时间四层对应 10 节奏结构的四层 |
+| 3 | 核心推动力 | 按项目实际存在的即时、阶段或长期推动力组织 | 玩家"什么时候被什么推着走"的推动结构 | 与实际节奏结构对应 |
 | 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 |
-| 5 | 小循环 | 几十秒到几分钟的具名动词链 ×3+ | 真正被玩到的那层；动词链可直接复制进实现 | 检验：删掉某条，游戏是否少了一块可命名的乐趣 |
-| 6 | 资源流与输入输出 | 资源流图（来源→储存→消耗）+ 输入输出清单 + 反馈四层 | 资源是循环的血液；防白给、防废物、防套利 | 供血给 4~5 的每个循环环节 |
+| 5 | 小循环 | 按项目实际存在的局内或短周期动词链组织 | 记录真正被玩到的循环 | 按实际循环层级互检 |
+| 6 | 资源流与输入输出 | 按项目实际存在的资源流、输入输出和反馈组织 | 说明循环中的实际供给与结果 | 与实际循环环节对应 |
 | 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 |
 | 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 |
 | 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） |
-| 10 | 节奏结构 | 日内/周内/季节/长期四层 + 情绪摆动 | 防止"一直紧张"或"一直平"；摆动才有呼吸 | 四层对应 3 的推动力四层 |
+| 10 | 节奏结构 | 按项目实际存在的时间层级和情绪变化组织 | 说明玩法节奏如何变化 | 与实际推动力层级对应 |
 | 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 |
 | 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 |
 | 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 |
@@ -80,7 +84,7 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定
 （大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、
 顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。
 
-## 四、怎么写（模板即流程，十六节按序）
+## 四、怎么写（模板参考结构，建议按此组织）
 （本节是带写法要领的教学版；实际填写的纯净模板在 templates/top-design.md）
 
 ### 1. 顶层定位与规模锚点
@@ -96,24 +100,24 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定
 ### 3. 核心推动力
 - 动机主次：__。
 - 即时推动 __；日程推动 __；季节推动 __；长期推动 __。
-→ 四层都要有实指；空着的那层就是将来留存崩塌的地方。
+→ 只展开项目实际存在的时间层级；不存在的层级不设字段。
 
 ### 4. 大循环
 **__ → __ → __ → __ → 回到 __。**（附核心循环图）
 → 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。
 
-### 5. 小循环（具名动词链 ×3+）
+### 5. 小循环（按项目实际数量）
 **__循环**：__ → __ → __ → __ → __。
 → 必须具名（"农务循环"不是"资源循环"）；动词链完整到可以直接照做。
 
 ### 6. 资源流与输入输出
 （资源流图：每种核心资源 来源 → 储存 → 消耗 三段全）
-主要输入 __；主要输出 __；反馈四层：立即 __ / 短期 __ / 中期 __ / 长期 __。
+主要输入 __；主要输出 __；按项目需要记录反馈层级。
 → 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。
 
 ### 7. 最小体验单位
 __（多短一段玩法体现独有乐趣——原型只做这一个单位）。
-单个行动必须至少提供一种清晰反馈：资源/进度/能力/关系/信息/视觉状态之一。
+保留的玩家行动应有与玩法相称的可理解反馈；反馈形式和数量按项目决定。
 
 ### 8. 核心活动流程（段落表）
 | 阶段 | 玩家行为 | 设计目的 |
@@ -153,7 +157,7 @@ __（多短一段玩法体现独有乐趣——原型只做这一个单位）。
 顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。
 后续架构必须围绕 __ 拆系统；不得 __。
 
-某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。
+若某节对本项目没意义，直接省略。
 
 ## 五、分析文档（全局一份，按层分节）
 
@@ -187,4 +191,4 @@ __（多短一段玩法体现独有乐趣——原型只做这一个单位）。
 ## 七、红线（只有三条）
 1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。
 2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。
-3. 不凑数：写不满就说明缺什么，禁止万金油句填充。
+3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/architecture.md

@@ -1,5 +1,7 @@
 ### C1 模板_系统架构.md（→ templates/architecture.md）
 
+本模板是参考结构，不是固定清单。只有需要独立职责、状态或数据边界的部分才拆成系统；简单项目可以合并系统和章节，复杂项目可以增加必要的系统与校验。表格中的示例行可按实际系统、风险和问题扩展，不代表数量上限。
+
 # 系统架构：《游戏名》
 
 ## 架构定位与目标
@@ -18,6 +20,7 @@
 |---|---|---|---|
 | S01 | __ | __ | P0 |
 | S02 | __ | __ | |
+（以上为示例，可按实际系统删减或扩充。）
 
 支撑层（不拥有核心规则）：__。
 
@@ -105,6 +108,8 @@ flowchart LR
 | 风险 | 校验方式 |
 |---|---|
 | __ | __ |
+（按实际风险逐行补充。）
 
 ## 开放的结构问题
 - __
+（按实际问题逐条补充。）

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/concept-design.md

@@ -1,5 +1,7 @@
 ### C1 模板_概念设计.md（→ templates/concept-design.md）
 
+本模板是参考结构，不是固定清单。填写前按项目类型、规模和用户要求筛选章节与字段；同类内容可合并，若某节对项目没有实际意义则删除，复杂项目可增加必要内容。表格和列表中的示例项可按实际内容扩展，不代表数量上限。
+
 # 概念设计：《游戏名》
 
 ## 一句话概念
@@ -10,14 +12,14 @@
 ### 定调记录（全项目调性真源，级联决策的依据库）
 - 参照选择：以《__》为主（__, 学 __）；不参考 __。
 - 调性滑杆：压力感 __ / 战斗比重 __ / 管理深度 __ / 叙事比重 __ / 节奏 __。
-- 调性锚（T 原则，逐条具名，下游每个开放问题先来这里级联）：
-  T1 __；T2 __；T3 __；T4 __；T5 __。
+- 调性锚（按项目需要逐条具名，下游开放问题按需从这里级联）：
+  T__ __。
 
 ### 设计锚点（六仲裁位）
 - 核心幻想：__。
   玩家念头："__"
 - 目标体验：__。
-- 玩家动机：短期 __；长期 __。
+- 玩家动机（按项目实际存在的时间尺度填写）：__。
 - 核心循环：__ → __ → __ → __ → 回到 __。
 - 跑偏风险：__。
 - 非目标：__（详见《不是什么》）。

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-art-bible.md

@@ -1,5 +1,7 @@
 ### C3 02_美术圣经/模板.md（→ templates/tdd-art-bible.md）
 
+本模板是美术实施的参考结构。按项目实际需要选择角色、场景、UI、动画和素材契约；没有对应资产类型时删除相应章节，复杂项目可增加必要的视觉规则。表格和资产条目可按实际内容扩展，不代表数量上限。
+
 # 美术圣经：《游戏名》
 
 > 状态：{drafting / reviewed / frozen}　|　定调锚：概念层@v{N} 第 2 节　|　style_id：`__`
@@ -10,7 +12,7 @@ __（一段话：从定调记录翻译的视觉气质；参考图位 __ 张）
 
 ## 视觉锚
 
-- 关键词：__（3~5 个）。
+- 关键词：__（按项目需要）。
 - 禁用关键词：__。
 - 色板：主色 __ / 辅色 __ / 点缀 __（配比 __）；昼夜·天气·季节表现 __。
 - 形状语言：__。
@@ -40,6 +42,7 @@ __（承 UI 系统文档的界面清单；视觉语言与信息分层对齐）
 | 素材 | 规格（尺寸/帧数/方向数） | 命名规则 | atlas 格式 | 验收 | 绑定 |
 |---|---|---|---|---|---|
 | __ | __ | __ | __ | __ | `item_ __` / 豁免：__ |
+（以上为示例，可按实际素材删减或扩充。）
 
 - 绘制工艺：__（用陶泥儿 MCP 的路径与参数；封装流程）。
 - 豁免类型仅限：程序化生成 / UI 文本 / 本期不需要。
@@ -49,17 +52,19 @@ __（承 UI 系统文档的界面清单；视觉语言与信息分层对齐）
 | asset_id | 规格 | 绑定 | 状态 | 验收记录 | contract_version |
 |---|---|---|---|---|---|
 | __ | __ | `item_ __` / 豁免 | 缺失/草稿/已交付/已验收/已接入 | 技术过/视觉过 @__ | __ |
+（以上为示例，可按实际资产删减或扩充。）
 
 - 状态单向流转：缺失 → 草稿 → 已交付 → 已验收 → 已接入；驳回退回草稿并记原因。
 - 验收两维：技术（尺寸/透明/帧数/命名）+ 视觉（对照视觉锚）；两维都过才进"已验收"。
-- 每个 gameplay 可见对象必有一行，或显式豁免——没有第三种状态。
+- 需要登记的 gameplay 可见对象有一行；不需要资产登记的对象不建立空记录。
 - 程序接入后填消费点（哪个模块加载、事件映射），`contract_version` 变更须重验收。
 
 ## 量产流程与验证
 
 1. 概念候选 __ 张 → 2. 人选方向 → 3. 锚点图 __ 张 → 4. 锁圣经 →
 5. 写契约 → 6. 小批 __ 张 → 7. 技术检查（__）→ 8. 接入程序 →
-9. 运行时截图验收（桌面/移动双视口下 __ 可辨）→ 10. 扩产。
+9. 运行时验收（按项目支持的平台）→ 10. 扩产。
+（以上为示例，可按实际流程删减或扩充。）
 
 ## 开放问题回执
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-data.md

@@ -1,5 +1,7 @@
 ### C3 03_数据与配表/模板.md（→ templates/tdd-data.md）
 
+本模板是数据与配表的参考结构。只有项目实际存在配置、枚举、关系或条件数据时才建立对应表和校验；简单项目可以直接写配置约定，复杂项目再拆分表结构与验算流程。表格中的示例行可按实际数据、字段和验算项扩展，不代表数量上限。
+
 # 数据与配表：《游戏名》
 
 > 状态：{structuring / filling / accepted}　|　基于：各系统交接节汇总　|　验收：check@{id} 最新结论 __
@@ -9,6 +11,7 @@
 | 表格组 | 建议表名 | 主要维护系统 |
 |---|---|---|
 | __ | __ | __ |
+（以上为示例，可按实际数据表删减或扩充。）
 
 （表格拆分是生产组织方式，不改变主数据归属。）
 
@@ -26,7 +29,7 @@
 |---|---|---|---|---|---|---|
 | __ | date_day / progress_flag / skill_level / schedule_open / quest_completed / __ | __ | __ | __ | active | __ |
 
-（复杂条件拆条件组+条件行；全项目只此一个条件入口，程序实现一次 `check(condition_id)`。）
+（存在复杂条件时再拆条件组与条件行；没有条件系统时删除本节。）
 
 ## 工作簿组织与建表顺序
 
@@ -36,6 +39,7 @@
 
 建表顺序：①物品表（公共 item_id）→ ②__ → ③__ → ④__ → ⑤__ → ⑥__ → ⑦__ → ⑧__。
 每完成一组查三件事：引用 ID 存在 / 条件有负责系统 / 同一数值只有一个系统维护。
+（以上为示例，可按实际表结构删减或扩充。）
 
 ## 表格-程序契约
 
@@ -54,12 +58,14 @@
 | 表 | 字段 | 默认值 | 依据 | 推翻条件 |
 |---|---|---|---|---|
 | __ | __ | __ | T__ / 台账 id | __ |
+（以上为示例，可按实际验算字段删减或扩充。）
 
 - 前五日闭环验算：
 
 | 日期 | 主目标 | 关键行动 | 主要成本 | 主要获得 | 结果 |
 |---|---|---|---|---|---|
 | 第 1 日 | __ | __ | __ | __ | __ |
+（以上为示例，可按实际循环或阶段删减或扩充。）
 
 - 收益链校验：`__ → __ → __ → __ → __`（逐环引 ID）。
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-master.md

@@ -1,5 +1,7 @@
 ### C3 模板_TDD总册.md（→ templates/tdd-master.md）
 
+本模板是 TDD 总册的参考结构。只建立当前项目实际需要的技术、美术、数据和索引内容；没有对应方向时不创建空分册，复杂项目可以增加施工所需的分册。表格中的示例行可按实际分册、问题和验收项扩展，不代表数量上限。
+
 # TDD 总册：《游戏名》
 
 > 本册是 TDD 层的封面与索引：正文在三件分册（01 技术实现 / 02 美术圣经 / 03 数据与配表），
@@ -7,19 +9,19 @@
 
 ## 自足性检查（TDD 的完成判据）
 
-> 标准：一个施工 agent 只看 TDD，能做完完整游戏。逐项模拟它必问的问题，
+> 标准：施工方只看当前 TDD，能完成项目实际范围内的实现。逐项检查当前项目真正需要的问题，
 > 答得出=过；答不出=缺口（列 GDD 来源与同步动作）。
 
 | # | 施工 agent 的问题 | 答案在哪 | 状态 |
 |---|---|---|---|
-| 1 | 每个系统怎么行为（规则/行动/反馈）？ | 01 收编章（@v{N}） | __ |
-| 2 | 每张表有多少行内容、文本全填了吗？ | 03 全量填充+完成度验收 | __ |
-| 3 | 每个界面长什么样、怎么走？ | 01 UI 交互规格 | __ |
-| 4 | 每份素材什么规格、谁验收过？ | 02 资产状态表（全行非缺失） | __ |
+| 1 | 实际存在的系统怎么行为？ | 01 收编章（@v{N}） | __ |
+| 2 | 实际使用的表和配置是否可施工？ | 03 数据与配表 | __ |
+| 3 | 实际存在的界面怎么走？ | 01 UI 交互规格 | __ |
+| 4 | 实际需要的素材什么规格？ | 02 资产状态表 | __ |
 | 5 | 代码怎么组织、跑在哪？ | 01 代码组织+能力边界 | __ |
 | 6 | 怎么算做完了（判据）？ | 01 里程碑+各件验收 | __ |
 
-全部为"过"时，TDD 进入 frozen——构建可以完全脱离 GDD 进行。
+当前项目所需检查全部为"过"时，TDD 进入 frozen——构建可以在本版本范围内脱离 GDD 进行。
 
 ## 三件状态
 
@@ -54,7 +56,7 @@
 
 | 件 | 最近验收 | blocker | 结论 |
 |---|---|---|---|
-| 01 | __（构建+双视口验证 @__） | __ | __ |
+| 01 | __（按项目平台验证 @__） | __ | __ |
 | 02 | __（技术+视觉两维 @__） | __ | __ |
 | 03 | __（七查 @check_id） | __ | __ |
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-tech.md

@@ -1,9 +1,11 @@
 ### C3 01_技术实现/模板.md（→ templates/tdd-tech.md）
 
+本模板是技术实现的参考结构。按当前运行时、系统复杂度和用户要求选择章节；没有对应系统、界面、输入、音频或存档需求时，删除相应内容，复杂项目可增加施工所需章节。表格和系统条目可按实际实现范围扩展，不代表数量上限。
+
 # 技术实现：《游戏名》
 
 > 状态：{drafting / reviewed / frozen}　|　基于 GDD：架构层@v{N}　|　数据侧契约：data/contracts@v{M}
-> **目标运行时：{HTML / Unity / Godot / Cocos}（由 GDD 平台事实锁定）**　|　预览：{HTML=双视口浏览器 / 引擎=陶泥儿驱动弹窗}　|　导出：{HTML=自包含 / 引擎=陶泥儿驱动 CLI}
+> **目标运行时：{HTML / Unity / Godot / Cocos}（由 GDD 平台事实锁定）**　|　预览：{按项目平台验证 / 引擎=陶泥儿驱动弹窗}　|　导出：{HTML=自包含 / 引擎=陶泥儿驱动 CLI}
 
 ## 系统行为规格（收编章）
 
@@ -28,7 +30,7 @@
 
 ## 技术目标与平台事实
 
-- 平台事实（注入，禁改）：自包含 Web · 双视口（桌面/移动）· 键鼠/触屏双输入 · 本地 HTTP 预览。
+- 平台事实（由 GDD 平台事实锁定）：__。
 - 技术目标：__（可测量，如"首屏可玩 ≤ __ 秒"）。
 
 ## 技术风险
@@ -39,7 +41,7 @@
 
 ## 运行时能力边界
 
-| 能力（P0 七件） | 落位（按所选运行时） | 状态（原生/自封装/受限） | 说明 |
+| 能力（按项目实际使用的能力填写） | 落位（按所选运行时） | 状态（原生/自封装/受限） | 说明 |
 |---|---|---|---|
 | 瓦片地图渲染 | __ | __ | __ |
 | 寻路 | __ | __ | __ |
@@ -85,7 +87,7 @@
 ## 构建与验证
 
 - 构建：__（命令/流程）。
-- 验证分级：自动__（跑什么、看什么输出为过）；半自动__（双视口浏览器验证步骤）；手测__（谁试玩、观察什么）。
+- 验证分级：自动__（跑什么、看什么输出为过）；半自动__（按项目平台验证步骤）；手测__（谁试玩、观察什么）。
 
 ## 版本里程碑
 

apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/top-design.md

@@ -1,5 +1,7 @@
 ### C1 模板_顶层设计.md（→ templates/top-design.md）
 
+本模板是参考结构，不是固定清单。填写前按项目实际存在的循环、资源、时间层级和用户要求筛选章节；同类内容可合并，若某项不存在则删除，复杂项目可增加必要内容。表格、列表和循环示例可按实际内容扩展，不代表数量上限。
+
 # 顶层设计：《游戏名》
 
 ## 顶层定位与规模锚点
@@ -43,6 +45,7 @@ __ → __ → __ → __ → __。
 
 ### __循环
 __ → __ → __ → __。
+（以上为示例，可按实际循环删减或扩充。）
 
 ## 资源流与输入输出
 
@@ -58,13 +61,14 @@ flowchart LR
 
 ## 最小体验单位
 __。
-单个行动必须至少提供一种清晰反馈：__。
+保留的玩家行动应有与玩法相称的可理解反馈：__。
 
 ## 核心活动流程
 
 | 阶段 | 玩家行为 | 设计目的 |
 |---|---|---|
 | __ | __ | __ |
+（按实际阶段逐行补充。）
 
 ## 取舍表
 
@@ -77,6 +81,7 @@ __。
 - 周内节奏：__。
 - 季节/章节节奏：__。
 - 长期节奏：__。
+（以上为示例，可按实际节奏层级删减或扩充。）
 
 整体情绪在"__"与"__"之间摆动（恢复来源：__；变化来源：__）。
 
@@ -103,9 +108,11 @@ __。
 | 验证点 | 成功标准 |
 |---|---|
 | __ | __ |
+（按实际验证点逐行补充。）
 
 ## 开放问题
 - __
+（按实际问题逐条补充。）
 
 ## 顶层定稿
 顶层当前定稿为：__。

apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md

@@ -1,12 +1,16 @@
 
 你是游戏策划协作 Agent，与用户持续协作完成游戏设计。像普通策划同事一样交流，使用工作区文件工具读写资料；所有文件路径使用相对路径。根据当前对话、阶段上下文和已有文档决定下一步行动。修改文件后，简要说明修改内容和相对路径。对不确定内容区分用户确认、Agent 建议和待原型验证事项；不要把建议写成用户已确认的决定。
 
-优先完成能够依据已有信息推进的工作，不要为每个设计空白都询问用户。局部、可逆的问题可以先提出合理方案并标为暂定。会影响当前阶段范围、关键规则、下游实现或其他重要方向，且必须由用户决定的问题，应先通过纯文本或问询工具询问，等待用户回答，并据此更新相关产物；不要带着这类未决问题提交阶段审批。
+优先完成能够依据已有信息推进的工作，不要为每个设计空白都询问用户。局部、可逆的问题可以先提出合理方案并标为暂定。会影响当前阶段范围、关键规则、下游实现或其他重要方向，且必须由用户决定的问题，应先通过纯文本或问询工具询问，等待用户回答。决定稳定后，再更新受影响的正式产物和必要的过程记录；不要带着这类未决问题提交阶段审批。
+
+分析阶段优先记录当前目标、上层约束、候选方案、取舍、用户已确认或 Agent 暂定的边界，以及必须检查的验收项。除非用户明确要求展开讨论，不要先在回复中逐节起草与正式文档重复的长篇正文；形成结论后直接写入正式产物，再进行一次必要的一致性检查。文件操作前只需说明简短计划、目标文件和主要变化。
 
 正式策划文档在文档头部写明版本标记，例如“版本：v1”。由你自行维护版本号：只有整体修订、阶段性定稿或用户意见造成实质内容变化时才递增；错别字、措辞润色、单个局部修改和小范围补充不单独递增。
 
 阶段审批是每个阶段的最终检查，表示本阶段产物已经完成，无未决内容，交给用户做最终检阅，不承担问询功能。提交前，解决所有影响本阶段完成的关键问题，或明确说明它们不阻塞本阶段交付，并更新相关产物。可以保留不阻塞当前阶段的后续事项和待原型验证项。
 
+过程文档用于记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档。阶段内优先完成主要设计内容；只有稳定且影响后续工作的决定才需要同步到多个过程文档。阶段提交前，补齐影响验收的关键记录。
+
 阶段获批后，产物中已经采用的方案作为后续工作的依据，并保留原有决策来源。除非用户主动质疑或出现新的约束冲突，不要反复要求确认历史暂定决定。
 
 用户说“继续”时，继续推进当前阶段最有价值的工作。判断本阶段已完成并准备交用户检阅时，应调用 `submit_phase_for_approval`；只有该工具调用成功，才算正式提交审批。