修复AI游戏创作壳跨平台启动

修复 macOS 下 Unix 文件身份比较和临时目录测试兼容
隔离 AI 游戏创作本地数据库与发布身份并阻止旧 schema 降级启动
完善 Tauri 开发栈错误传播和 POSIX 子进程树清理
跳过 macOS 不支持的进程指标回调以消除周期告警
补充开发调度测试、技术方案和团队排障记忆

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

@@ -13,6 +13,7 @@ const viteUrl = `http://${viteHost}:${vitePort}/`;
 const viteMarkerUrl = `${viteUrl}__agc_dev_server.json`;
 const defaultApiTarget = process.env.RUST_SERVER_TARGET || 'http://127.0.0.1:8082';
 const backendDatabase = 'genarrative-game-creator-dev';
+const backendSpacetimeDataDir = 'server-rs/.spacetimedb/ai-game-creator/data';
 const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 
 function readJson(path) {
@@ -146,9 +147,13 @@ async function isExistingVitePairedWithBackend(apiTarget) {
 }
 
 function spawnChild(command, args, options) {
+  const useShell = process.platform === 'win32';
   return spawn(command, args, {
     ...options,
-    shell: true,
+    shell: useShell,
+    // POSIX 下让每个长驻服务拥有独立进程组，退出时可以连同 npm、
+    // Node、Cargo 及其子进程一起清理，避免残留订阅任务持续刷日志。
+    detached: !useShell,
     stdio: 'inherit',
   });
 }
@@ -158,9 +163,17 @@ function stopChild(child, signal = 'SIGTERM') {
     return;
   }
   try {
-    child.kill(signal);
+    if (process.platform !== 'win32' && Number.isInteger(child.pid)) {
+      process.kill(-child.pid, signal);
+    } else {
+      child.kill(signal);
+    }
   } catch {
-    // ignore cleanup races
+    try {
+      child.kill(signal);
+    } catch {
+      // ignore cleanup races
+    }
   }
 }
 
@@ -200,6 +213,8 @@ async function ensureBackend() {
       '--',
       '--database',
       backendDatabase,
+      '--spacetime-data-dir',
+      backendSpacetimeDataDir,
       '--no-interactive',
     ],
     { cwd: appRoot },

apps/ai-game-creator-shell/src-tauri/src/project.rs

@@ -336,8 +336,8 @@ fn verify_unix_agent_db_root(root: &Path, opened: &File) -> Result<(), String> {
     let metadata = opened
         .metadata()
         .map_err(|error| format!("复核 Agent DB 项目目录句柄失败：{error}"))?;
-    if stat.st_dev != metadata.dev()
-        || stat.st_ino != metadata.ino()
+    if stat.st_dev as u64 != metadata.dev()
+        || stat.st_ino as u64 != metadata.ino()
         || stat.st_mode & libc::S_IFMT != libc::S_IFDIR
     {
         return Err("Agent DB 项目目录在安全打开期间发生替换或不是普通目录".to_string());
@@ -380,8 +380,8 @@ fn verify_unix_agent_db_entry(
     } else {
         libc::S_IFREG
     };
-    if stat.st_dev != metadata.dev()
-        || stat.st_ino != metadata.ino()
+    if stat.st_dev as u64 != metadata.dev()
+        || stat.st_ino as u64 != metadata.ino()
         || stat.st_mode & libc::S_IFMT != expected_type
     {
         return Err(format!("{label}在安全打开期间发生替换"));

apps/ai-game-creator-shell/src-tauri/src/runner.rs

@@ -1200,8 +1200,8 @@ fn verify_unix_project_owner_entry(
     } else {
         libc::S_IFREG
     };
-    if stat.st_dev != opened_metadata.dev()
-        || stat.st_ino != opened_metadata.ino()
+    if stat.st_dev as u64 != opened_metadata.dev()
+        || stat.st_ino as u64 != opened_metadata.ino()
         || stat.st_mode & libc::S_IFMT != expected_type
     {
         return Err(format!("{label} 在安全打开期间发生替换"));

apps/ai-game-creator-shell/src-tauri/src/tests.rs

@@ -1286,7 +1286,10 @@ fn unique_project_path() -> PathBuf {
         .expect("system clock should be after epoch")
         .as_millis();
     let counter = TEST_PROJECT_COUNTER.fetch_add(1, Ordering::Relaxed);
-    std::env::temp_dir().join(format!(
+    let temp_root = std::env::temp_dir()
+        .canonicalize()
+        .unwrap_or_else(|_| std::env::temp_dir());
+    temp_root.join(format!(
         "genarrative-ai-game-creator-test-{}-{millis}-{counter}",
         std::process::id()
     ))

apps/ai-game-creator-shell/src-tauri/src/tool_plan_handoff.rs

@@ -1673,8 +1673,8 @@ fn verify_unix_tool_plan_entry(
     } else {
         libc::S_IFREG
     };
-    if stat.st_dev != opened_metadata.dev()
-        || stat.st_ino != opened_metadata.ino()
+    if stat.st_dev as u64 != opened_metadata.dev()
+        || stat.st_ino as u64 != opened_metadata.ino()
         || stat.st_mode & libc::S_IFMT != expected_type
     {
         return Err(format!("{label} 在安全扫描期间发生替换"));

docs/project-memory/shared-memory/pitfalls.md

@@ -3500,3 +3500,21 @@
 - 运维陷阱：从容器内运行 Compose 时，宿主 `/opt/gitea-stack` 必须挂到容器同名绝对路径；挂成 `/stack` 会让相对 bind source 被 daemon解析为宿主 `/stack/...`，表现为 Gitea进入空安装页、gateway 脚本“缺失”。发现后不要迁移空库，立即用同路径 mount 重建并核对原数据大小、installed 日志、仓库数和 API。切换前保留冷数据 tar、pg_dumpall 和原 compose/env/runner 配置，备份与 token 不提交 Git。
 - 验证：同时检查 Gitea 版本、runner declare、外层 `Privileged=false`/无 CapAdd/无宿主 socket、inner job `Binds=[]`、`MaskedPaths=[]`、`ReadonlyPaths=[]`、固定 image digest、`/var/run/docker.sock` 不存在、公共 proxy 可用、直连公网/Postgres/metadata 失败，以及完整 bwrap canary。AI 原生壳的共享 Agent Runtime 后台锁 suite 固定单线程执行；并行全量出现锁或异步终态失败、逐项单线程全部通过时，修正 suite 调度口径，不放宽断言。最后重跑四个 CI job；checkout 成功但 apt/rustup/npm 同时失败时，先排 proxy/env，而不是改测试。
 - 关联：`.gitea/workflows/project-ci.yml`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/development-workflow.md`。
+
+## Unix 文件身份复核不能假定 Linux 的 `dev_t` 类型
+
+- 现象：AI 游戏创作 Tauri 壳在 Linux CI 编译通过，但 macOS 上会在 Agent DB、External Runner owner 和 tool-plan handoff 的 `fstatat` 身份复核中报 `i32 == u64` 类型错误；Tauri 失败后配套后端收束，终端还可能短暂出现 SpacetimeDB 订阅连接失败的连锁日志。
+- 原因：`libc::stat.st_dev` 跟随平台 `dev_t`，macOS 为有符号整数，而 `std::os::unix::fs::MetadataExt::dev()` 统一返回 `u64`；直接比较会把 Linux 的类型偶合误当成 Unix 通用契约。
+- 处理：与 Rust 标准库的 Unix `MetadataExt` 实现保持一致，先把 `st_dev / st_ino` 规范为 `u64`，再与 `metadata.dev() / metadata.ino()` 比较；设备号、inode 和文件类型三重检查均必须保留。
+- macOS 测试夹具：`std::env::temp_dir()` 可能返回 `/var/folders/...`，而 `/var` 是系统兼容符号链接。需要真实项目根的 Runtime 测试应先 canonicalize 已存在的临时根目录，再创建唯一子目录；不得为了让夹具通过而放宽生产 Runtime 的项目根及祖先符号链接拒绝规则。
+- 验证：macOS 本机运行 `cargo check --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`，并复跑 Agent DB、project owner 和 tool-plan handoff 的 Unix 相对句柄替换检测；Linux CI 继续覆盖原有安全回归。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/project.rs`、`runner.rs`、`tool_plan_handoff.rs`。
+
+## AI 游戏创作壳不能用全局或匿名身份发布本地模块
+
+- 现象：`npm run agc` 在发布模块时先访问 `auth.spacetimedb.com` 并以 401 失败；改成 `--anonymous` 后首次可能成功，但再次启动会因匿名 identity 变化而 403。若把 403 当成可忽略警告继续启动，api-server 会连接旧 schema，随后持续输出 `external_generation_job`、`profile_recharge_order_expiration_timer` 等缺表订阅失败，Tauri 也可能在后端就绪前退出或迟迟不弹窗。
+- 原因：本地 publish 默认继承开发者全局 SpacetimeDB 云端登录，离线时 standalone 无法校验 issuer；`--anonymous` 不是可跨进程持久复用的 owner identity；AI 游戏创作壳若再复用主站历史数据目录，还会继承旧数据库归属和旧 schema。
+- 处理：AI 游戏创作壳固定使用 gitignored 的独立数据目录；standalone 就绪后先从 `/v1/identity` 获取并持久化同一 API identity，再用数据目录内权限为 `0600` 的独立 `cli.toml` 执行 `spacetime login --token` 和 publish。远程 server 继续使用正常登录配置；本地 publish 403 必须阻断 API/Vite，不得带旧 schema 降级启动。POSIX 启动器用独立进程组收束 npm、Node、Cargo 和子进程，退出后确认 3080、8082、3101 均释放。
+- macOS 日志：api-server 进程指标当前只实现 Windows API 和 Linux `/proc`，macOS 必须跳过 observable callback 注册；不能每轮采集为每个指标重复打印“不支持平台”。Rust/Tauri 既有 `dead_code` warning 与一次性配置缺失提示不属于长驻重试日志。
+- 验证：连续运行两次 `npm run agc`，两次都必须真实完成 module publish、`/v1/ping`、`/healthz`、Vite 3080 和 Tauri `Running`；稳定观察期间不得出现缺表订阅失败或进程指标平台告警，Ctrl-C 后三个端口和主 Tauri 进程均应释放。
+- 关联：`scripts/dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`server-rs/crates/api-server/src/process_metrics.rs`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -474,6 +474,9 @@ game-project/
 - 终端可用 `npm run ai-game-creator-shell:agent-run -- /绝对项目路径 "游戏创作需求"` 跑一次真实 LLM 生成、落盘、`game.static_smoke` 和本地 HTTP 预览；发布 App 读取 Tauri 应用配置目录中的 `game-creator.config.json`，开发 CLI 无 AppHandle 时才读取仓库旁边的配置模板和 gitignored 本机覆盖文件，不把 API Key 写入仓库或项目文件。自动验证可加 `--no-wait`，例如 `npm run ai-game-creator-shell:agent-run -- --no-wait /tmp/genarrative-ai-game-test "像素风反弹弹幕厨房"`，生成预览 trace 后立即停止本地预览，避免终端卡在回车等待。默认 API kind 为 `openai_responses`；旧 Chat Completions 兼容网关设置 `llm.apiKind` 为 `openai_chat`，Anthropic Messages 网关设置 `llm.apiKind` 为 `anthropic`。真实 OpenAI-compatible 网关建议设置 `llm.stream` 为 `true` 跑 Planner 和 Generator，避免长请求非流式空闲断连。
 - 终端可用 `npm run ai-game-creator-shell:agent-run:smoke` 跑一次无密钥本地端到端 smoke：脚本启动本机 OpenAI-compatible SSE 流式测试 provider，预置一个本地上传图片和一个本地上传音频，复用真实 `--agent-run`、Planner / Orchestrator / 角色 agent / Generator / Evaluator loop、本地落盘、`game.static_smoke` 和本地 HTTP 预览，并断言每次 provider 请求都使用 `stream: true`、Planner 与 Generator 分别命中自己的 `agentLlm` provider 配置、provider prompt 收到图片与音频资产上下文以及最近对话上下文、生成 HTML 引用这些资产、预览服务能用 `GET` 读取 `/assets/...`、用 `HEAD` 返回真实资源长度和对应 MIME、headless Chrome 打开预览后至少执行一帧游戏 JS，且通过确定性亮色探针采样证明 canvas 不是空白画布、`.agent/run.latest.json` 的 step group 覆盖 design / balance / art / audio / code / publishing 六组、第二轮会重跑 Evaluator 命中任务及其下游影响任务，未受影响角色 carry-over；随后脚本自动给 CLI 发送回车停止预览。该脚本只用于开发验证，不进入产品生成路径。
 - `npm run ai-game-creator-shell:dev` 的 Tauri `devUrl` 固定为 `http://127.0.0.1:3080/`，Vite 必须 `strictPort` 对齐；`beforeDevCommand` 先复用已经跑在 3080 且页面标题为 `AI 游戏创作` 的本 app Vite server，否则才启动新的 Vite，若端口被其它服务占用则直接失败并提示释放端口。
+- AI 游戏创作 App 的本地后端使用 gitignored 的 `server-rs/.spacetimedb/ai-game-creator/data`，不复用主站旧 standalone 数据目录。启动器从本地 `/v1/identity` 获取并持久化 API identity，再通过数据目录内 `0600` 的独立 `dev-cli/cli.toml` 发布模块；不得读取或覆盖开发者全局 SpacetimeDB 登录，也不得回退到每次变化的 `--anonymous` 身份。发布失败时 API 和 Vite 不得继续启动旧 schema，避免 `external_generation_job` 等缺表订阅进入持续重试。
+- `start-dev-stack.mjs` 在 POSIX 下以独立进程组托管后端和 Vite，关闭 Tauri 或任一子进程失败时必须收束整组；macOS 不注册仅支持 Windows/Linux 的 api-server 进程指标 observable callback，避免每轮指标采集重复输出平台不支持告警。
+- Unix 下 Agent DB、External Runner owner 和 tool-plan handoff 的相对句柄复核必须同时比较设备号、inode 和文件类型；`libc::stat` 的 `st_dev / st_ino` 先按 Rust `MetadataExt` 的 Unix 口径规范为 `u64` 再比较，保持 Linux 和 macOS 的同一安全语义，不得为了通过 macOS 编译而删除路径替换检测。
 - AI 游戏创作 App 的 Vite root 保持在 `apps/ai-game-creator-shell`，但开发服务器必须通过 `server.fs.allow: [repoRoot]` 允许加载 `packages/shared/src` 共享契约；配置自检同时守住该规则，避免 typecheck 通过后真实 Tauri WebView 因共享源码 403 变成白屏。Tauri 事件 capability 只向 `client`、`developer`、`main`、`launcher` 窗口开放 `core:event:allow-listen` 和 `core:event:allow-unlisten`；Runtime 事件仍由 Rust 发出，前端不获得 `emit` 权限。
 - `.agent/manifest.json` 会保存 6 个专业组下 16 个组内角色任务状态，当前覆盖 `Director`、`Gameplay`、`Difficulty`、`Asset`、`Polish`、`SFX`、`Code`、`Review`、`Preview`、`Playtest`、`Publish`；程序组内显式包含 `quality-review` 质量评审 gate，由 Evaluator trace 标记完成；开发窗口的专业组面板读取 manifest，而不是前端硬编码。
 - 主窗口的 agent 状态列表以 manifest 角色任务为底表，再合并最近 run trace 中 `taskGraph.tasks` 的任务状态、同 taskId / group / role 的最新 step 状态、输入输出路径、错误摘要、lifecycleStatus 和 `activeTaskIds` / `carriedTaskIds` / `readyTaskIds` 编排标记；如果 trace 缺失或过期，只展示 manifest 的静态任务状态和“暂无最近运行证据”。

scripts/dev.mjs

@@ -1513,12 +1513,11 @@ class DevRunner {
         await this.publishSpacetimeModule();
       } catch (error) {
         if (isSpacetimePublishPermissionError(error)) {
-          console.warn(
-            `[dev:spacetime] 本地发布被当前 identity 拒绝，保留已启动的 standalone: ${error.message}`,
+          throw new Error(
+            `本地数据库不属于当前隔离 identity，已停止启动以避免 API 使用旧 schema 后持续重试订阅。请改用独立本地数据目录，或在确认无需保留旧开发数据后重建该目录。详情: ${error.message}`,
           );
-        } else {
-          throw error;
         }
+        throw error;
       }
     }
   }
@@ -1645,8 +1644,10 @@ class DevRunner {
   async publishSpacetimeModule() {
     const env = buildLocalRustProcessEnv(this.baseEnv);
     this.prepareMigrationBootstrapSecret(env);
+    const cliConfigPath = await this.prepareLocalSpacetimeCliIdentity(env);
 
     const args = buildSpacetimePublishArgs({
+      cliConfigPath,
       database: this.options.database,
       preserveDatabase: this.options.preserveDatabase,
       server: this.state.spacetimeServer,
@@ -1660,6 +1661,48 @@ class DevRunner {
     });
   }
 
+  async prepareLocalSpacetimeCliIdentity(env) {
+    if (!isLoopbackSpacetimeServer(this.state.spacetimeServer)) {
+      return '';
+    }
+
+    await this.ensureApiServerSpacetimeToken();
+    const cliConfigPath = resolve(
+      this.options.spacetimeDataDir,
+      'dev-cli',
+      'cli.toml',
+    );
+    ensureParentDir(cliConfigPath);
+    if (
+      existsSync(cliConfigPath) &&
+      resolveCurrentSpacetimeCliToken(cliConfigPath) === this.spacetimeApiToken
+    ) {
+      chmodSync(cliConfigPath, 0o600);
+      console.log('[dev:spacetime] 已复用隔离的本地发布 identity');
+      return cliConfigPath;
+    }
+    await runForeground(
+      'spacetime',
+      [
+        '--config-path',
+        cliConfigPath,
+        'login',
+        '--token',
+        this.spacetimeApiToken,
+      ],
+      {
+        cwd: serverRsDir,
+        env,
+        label: 'spacetime-login',
+      },
+    );
+    if (existsSync(cliConfigPath)) {
+      chmodSync(cliConfigPath, 0o600);
+    }
+    console.log('[dev:spacetime] 已配置隔离的本地发布 identity');
+    return cliConfigPath;
+  }
+
   prepareMigrationBootstrapSecret(env) {
     let runtimeServiceBootstrapSecret = '';
     switch (this.options.migrationBootstrapSecretMode) {
@@ -2814,8 +2857,14 @@ function isLoopbackSpacetimeServer(serverUrl) {
   }
 }
 
-function resolveCurrentSpacetimeCliToken() {
-  const result = spawnSync('spacetime', ['login', 'show', '--token'], {
+function resolveCurrentSpacetimeCliToken(cliConfigPath = '') {
+  const args = [
+    ...(cliConfigPath ? ['--config-path', cliConfigPath] : []),
+    'login',
+    'show',
+    '--token',
+  ];
+  const result = spawnSync('spacetime', args, {
     cwd: repoRoot,
     encoding: 'utf8',
     shell: process.platform === 'win32',
@@ -2839,13 +2888,21 @@ function trimPreview(text, maxLength = 300) {
 
 function runForeground(command, args, { cwd, env, label }) {
   return new Promise((resolveRun, rejectRun) => {
+    let capturedOutput = '';
+    const capture = (chunk, target) => {
+      target.write(chunk);
+      capturedOutput = `${capturedOutput}${String(chunk)}`.slice(-32_768);
+    };
     const child = spawn(command, args, {
       cwd,
       env,
-      stdio: 'inherit',
+      stdio: ['inherit', 'pipe', 'pipe'],
       shell: process.platform === 'win32',
     });
 
+    child.stdout?.on('data', (chunk) => capture(chunk, process.stdout));
+    child.stderr?.on('data', (chunk) => capture(chunk, process.stderr));
+
     child.on('error', rejectRun);
     child.on('exit', (code, signal) => {
       if (signal) {
@@ -2854,7 +2911,12 @@ function runForeground(command, args, { cwd, env, label }) {
       }
 
       if (code !== 0) {
-        rejectRun(new Error(`[dev:${label}] 退出码: ${code}`));
+        const detail = trimPreview(capturedOutput, 2_000);
+        rejectRun(
+          new Error(
+            `[dev:${label}] 退出码: ${code}${detail ? `: ${detail}` : ''}`,
+          ),
+        );
         return;
       }
 
@@ -2914,8 +2976,14 @@ function isDirectModuleExecution(argv1, moduleUrl, resolvePath = safeRealpath) {
   }
 }
 
-function buildSpacetimePublishArgs({ database, server, preserveDatabase }) {
+function buildSpacetimePublishArgs({
+  cliConfigPath = '',
+  database,
+  server,
+  preserveDatabase,
+}) {
   const args = [
+    ...(cliConfigPath ? ['--config-path', cliConfigPath] : []),
     'publish',
     database,
     '--server',

scripts/dev.test.ts

@@ -761,16 +761,20 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
     ).toBe(false);
   });
 
-  test('发布 spacetime-module 时忽略 spacetime.json 以免覆盖显式数据库', () => {
+  test('发布 spacetime-module 时使用隔离身份配置并忽略 spacetime.json', () => {
     const args = buildSpacetimePublishArgs({
+      cliConfigPath: '/tmp/genarrative-cli.toml',
       database: 'xushi-p4wfr',
       preserveDatabase: false,
       server: 'http://127.0.0.1:3101',
     });
 
     expect(args).toContain('--no-config');
+    expect(args).not.toContain('--anonymous');
     expect(args).toEqual(
       expect.arrayContaining([
+        '--config-path',
+        '/tmp/genarrative-cli.toml',
         'publish',
         'xushi-p4wfr',
         '--server',
@@ -780,6 +784,17 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
     );
   });
 
+  test('远程 SpacetimeDB 发布继续使用默认登录身份', () => {
+    const args = buildSpacetimePublishArgs({
+      database: 'xushi-p4wfr',
+      preserveDatabase: true,
+      server: 'https://spacetime.example.com',
+    });
+
+    expect(args).not.toContain('--anonymous');
+    expect(args).not.toContain('--config-path');
+  });
+
   test('手动刷新 spacetime 只重新发布模块，不重启 standalone 进程', async () => {
     const { explicitOptions, options } = parseArgs([], {});
     const runner = new DevRunner(options, {}, explicitOptions);

server-rs/crates/api-server/src/process_metrics.rs

@@ -8,6 +8,12 @@ use tracing::warn;
 
 // 进程指标只描述 api-server 自身，不携带请求、用户或作品维度，避免 OTLP 指标高基数膨胀。
 pub(crate) fn register_process_metrics() {
+    // 当前采集实现依赖 Windows API 或 Linux /proc。macOS 等平台不注册
+    // observable callbacks，避免每次 OTLP reader 采集时为每个指标重复告警。
+    if !cfg!(any(windows, target_os = "linux")) {
+        return;
+    }
+
     static REGISTERED: OnceLock<()> = OnceLock::new();
     REGISTERED.get_or_init(register_process_metrics_once);
 }