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

.gitea/workflows/project-ci.yml

@@ -27,9 +27,28 @@ env:
   RUSTC_WRAPPER: ''
   CARGO_BUILD_RUSTC_WRAPPER: ''
 
+# job 声明顺序就是 runner 领取顺序，因此把最长尾的客户端 Rust 门禁排在前面，
+# 让它在最少的等待下占用并发槽位；其余 job 按时长递减排列。
+#
+# 客户端（微信壳 / Expo 移动壳 / Tauri 桌面壳 / AI 游戏创作壳）门禁原先全部串在
+# `Native shell tests` 一个 job 里，实测 18 分 37 秒。现在按门禁组拆成一个分组一个 job：
+# `Native shell tests`（契约 + H5 / 微信 / 移动 / 桌面壳门禁 + 发布构建 smoke）、
+# `AI game creator shell web tests`（typecheck + 壳内测试）、`AI game creator shell
+# Rust shard 1/4` 到 `4/4`（AGC 壳 bin 单测按名单分 4 片）、`AI game creator shell
+# Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的
+# 共享 / 平台 crate 测试）。各自的命令与拆分前逐一对应，本地
+# `npm run check:native-shells` 仍是同一条串行序列。
+#
+# AGC 壳的 bin 单测（2466 条）按名单分 4 片、一片一个 job：片内保持 `--test-threads=1`
+# （当年线程并行会互相干扰的是进程内后台锁与异步终态），片与片之间靠 job 级并发摊开。
+# 不要改回「一个 job 里多进程并行这几片」：同一容器内它们会争抢共享 HOME、target 与固定
+# 临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」。
 jobs:
-  repository-checks:
-    name: Repository checks
+  # AGC 壳自身的 Rust bin 单测分片，4 片各自独立 job 并发执行、片内仍保持
+  # `--test-threads=1`。这里不装 npm 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，
+  # 也只需要 AGC 壳自己那份锁定依赖。
+  ai-game-creator-shell-rust-shard-1:
+    name: AI game creator shell Rust shard 1/4
     runs-on: genarrative-ci
     steps:
       - name: Checkout full history from Gitea
@@ -41,76 +60,228 @@ jobs:
       - name: Validate preinstalled CI job image and sandbox
         run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
 
-      - name: Resolve comparison base
+      - name: Prepare AI game creator shell Rust dependencies
         shell: bash
         run: |
           set -euo pipefail
-          base_ref="$(node -e '
-            const fs = require("node:fs");
-            const event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
-            process.stdout.write(event.pull_request?.base?.sha ?? event.before ?? "");
-          ')"
-          if [[ -n "${base_ref}" && ! "${base_ref}" =~ ^0+$ ]]; then
-            git cat-file -e "${base_ref}^{commit}" 2>/dev/null || {
-              echo "comparison base commit is unavailable: ${base_ref}" >&2
+          # AGC 壳有独立 Cargo.lock，其 path 依赖已含 platform-llm、platform-agent、
+          # agent-runtime-core 与 shared-contracts，因此只锁这一份 manifest 就能覆盖壳测试
+          # 与 smoke 的全部第三方依赖；server-rs 那次预热归 crate 级 job，不在这里重复。
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
               exit 1
-            }
-          else
-            base_ref="$(git merge-base HEAD origin/master 2>/dev/null || git rev-parse HEAD)"
-          fi
-          resolved_base_ref="$(git rev-parse --verify "${base_ref}^{commit}" 2>/dev/null || true)"
-          head_ref="$(git rev-parse HEAD)"
-          if [[ "${resolved_base_ref}" == "${head_ref}" ]]; then
-            resolved_base_ref="$(git rev-parse --verify HEAD^ 2>/dev/null || true)"
-          fi
-          if [[ -z "${resolved_base_ref}" ]]; then
-            echo 'comparison base must resolve to a commit distinct from HEAD.' >&2
-            exit 1
-          fi
-          base_ref="${resolved_base_ref}"
-          if [[ "${GITHUB_EVENT_NAME:-}" == 'pull_request' ]] \
-            && ! git merge-base --is-ancestor "${base_ref}" HEAD; then
-            echo 'pull request head does not contain the latest base commit; update the branch and rerun CI.' >&2
-            exit 1
-          fi
-          echo "SPACETIME_SCHEMA_BASE_REF=${base_ref}" >> "${GITHUB_ENV}"
+            fi
+            sleep $((attempt * 2))
+          done
 
-      - name: Install npm dependencies
-        run: bash scripts/ci-npm-ci-with-retry.sh
+      - name: Run AI game creator shell Rust shard 1/4
+        run: npm run check:native-shells:agc-rust-shard-1
 
-      - name: Run repository checks
-        run: npm run check:repository-ci
-
-  frontend-tests:
-    name: Frontend tests
+  ai-game-creator-shell-rust-shard-2:
+    name: AI game creator shell Rust shard 2/4
     runs-on: genarrative-ci
     steps:
-      - name: Checkout source from Gitea
+      - name: Checkout full history from Gitea
         env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '1'
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
           GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
         run: genarrative-gitea-checkout
 
       - name: Validate preinstalled CI job image and sandbox
         run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
 
-      - name: Install npm dependencies
-        run: bash scripts/ci-npm-ci-with-retry.sh
+      - name: Prepare AI game creator shell Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
 
-      - name: Run frontend and script tests
-        run: npm run test
+      - name: Run AI game creator shell Rust shard 2/4
+        run: npm run check:native-shells:agc-rust-shard-2
 
-      - name: Run BgFilter worker smoke harness tests
-        run: npm run bgfilter-worker:smoke-test
+  ai-game-creator-shell-rust-shard-3:
+    name: AI game creator shell Rust shard 3/4
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
 
-      - name: Validate production health patrol behavior
-        run: npm run check:production-health-patrol
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
 
-      - name: Validate production API release behavior
-        run: npm run check:production-api-release
+      - name: Prepare AI game creator shell Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
 
-      - name: Validate production API deploy behavior
-        run: npm run check:production-api-deploy
+      - name: Run AI game creator shell Rust shard 3/4
+        run: npm run check:native-shells:agc-rust-shard-3
+
+  ai-game-creator-shell-rust-shard-4:
+    name: AI game creator shell Rust shard 4/4
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Prepare AI game creator shell Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
+
+      - name: Run AI game creator shell Rust shard 4/4
+        run: npm run check:native-shells:agc-rust-shard-4
+
+  # agent-run smoke 会 spawn `cargo run`（走壳自己的 manifest），同样不装 npm 依赖，
+  # 单独一个 job，免得把已经压到 4 分钟级的片 job 拖长。
+  ai-game-creator-shell-rust-smoke:
+    name: AI game creator shell Rust smoke
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Prepare AI game creator shell Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
+
+      - name: Run AI game creator shell agent-run smoke
+        run: npm run check:native-shells:agc-rust-smoke
+
+  # AGC 壳依赖的共享 / 平台 crate 测试用的是 server-rs workspace 与两个无锁独立 crate
+  # 的 manifest，属另一套依赖图，因此单独一个 job 预热、单独跑。
+  ai-game-creator-shell-rust-crates:
+    name: AI game creator shell Rust crates
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Prepare server-rs Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path server-rs/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'server-rs Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
+
+      - name: Prepare standalone Rust crate dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          # agent-runtime-core / agent-runtime-orchestration 被 server-rs/Cargo.toml 的
+          # exclude 排除，不参与上面的 workspace 锁文件，因此上面那次锁定 fetch 覆盖不到它们；
+          # 而 `npm run ai-game-creator-shell:check:rust:crates` 会用
+          # `cargo test --manifest-path` 单独跑这两个 crate。不在这里预热的话，这两条测试
+          # 会在测试阶段自己 `Updating crates.io index`，crates.io 一抖动整条 job 就红
+          # （见 #327 / PR #316 run 1950）。
+          # 两个 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
+          # 加锁标志会因为缺少锁文件直接失败。生成的 Cargo.lock 落在两个 crate 目录内，
+          # 已被各自的 .gitignore 忽略，只留在容器里；随后的测试阶段因此能用锁定版本
+          # 解析，不再触碰 registry index。
+          for manifest_path in \
+            server-rs/crates/agent-runtime-core/Cargo.toml \
+            server-rs/crates/agent-runtime-orchestration/Cargo.toml; do
+            for attempt in $(seq 1 5); do
+              if cargo fetch \
+                --target x86_64-unknown-linux-gnu \
+                --manifest-path "${manifest_path}"; then
+                break
+              fi
+              if [[ "${attempt}" -eq 5 ]]; then
+                echo "standalone crate dependency fetch failed after 5 attempts: ${manifest_path}" >&2
+                exit 1
+              fi
+              sleep $((attempt * 2))
+            done
+          done
+
+      - name: Run AI game creator shell shared crate gates
+        run: npm run check:native-shells:agc-rust-crates
 
   backend-tests:
     name: Backend tests
@@ -194,6 +365,8 @@ jobs:
       - name: Check SpacetimeDB module
         run: cargo check --locked -p spacetime-module --manifest-path server-rs/Cargo.toml
 
+  # 客户端的壳级与契约门禁：静态契约断言、H5 / 微信 / 移动 / 桌面壳运行时门禁，
+  # 以及依赖发布产物的构建 smoke。
   native-shell-tests:
     name: Native shell tests
     runs-on: genarrative-ci
@@ -215,7 +388,6 @@ jobs:
         run: |
           set -euo pipefail
           for manifest_path in \
-            server-rs/Cargo.toml \
             apps/desktop-shell/src-tauri/Cargo.toml \
             apps/ai-game-creator-shell/src-tauri/Cargo.toml; do
             for attempt in $(seq 1 5); do
@@ -232,39 +404,118 @@ jobs:
             done
           done
 
-      - name: Prepare standalone Rust crate dependencies
-        shell: bash
-        run: |
-          set -euo pipefail
-          # agent-runtime-core / agent-runtime-orchestration 被 server-rs/Cargo.toml 的
-          # exclude 排除，不参与上面的 workspace 锁文件，因此上面那次锁定 fetch 覆盖不到它们；
-          # 而 check:native-shells 会经 agent-runtime-*:check 用 `cargo test --manifest-path`
-          # 单独跑这两个 crate。不在这里预热的话，这两条测试会在测试阶段自己
-          # `Updating crates.io index`，crates.io 一抖动整条 native shell 作业就红
-          # （见 #327 / PR #316 run 1950）。
-          # 两个 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
-          # 加锁标志会因为缺少锁文件直接失败。生成的 Cargo.lock 落在两个 crate 目录内，
-          # 已被各自的 .gitignore 忽略，只留在容器里；随后的测试阶段因此能用锁定版本
-          # 解析，不再触碰 registry index。
-          for manifest_path in \
-            server-rs/crates/agent-runtime-core/Cargo.toml \
-            server-rs/crates/agent-runtime-orchestration/Cargo.toml; do
-            for attempt in $(seq 1 5); do
-              if cargo fetch \
-                --target x86_64-unknown-linux-gnu \
-                --manifest-path "${manifest_path}"; then
-                break
-              fi
-              if [[ "${attempt}" -eq 5 ]]; then
-                echo "standalone crate dependency fetch failed after 5 attempts: ${manifest_path}" >&2
-                exit 1
-              fi
-              sleep $((attempt * 2))
-            done
-          done
+      - name: Run native shell contract gates
+        run: npm run check:native-shells:contract
 
       - name: Run native shell gates
-        run: npm run check:native-shells
+        run: npm run check:native-shells:shells
+
+      - name: Run native shell release build smoke
+        run: npm run check:native-shells:release
 
       - name: Ensure native lockfiles are unchanged
         run: git diff --exit-code -- apps/desktop-shell/src-tauri/Cargo.lock apps/ai-game-creator-shell/src-tauri/Cargo.lock
+
+  frontend-tests:
+    name: Frontend tests
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout source from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '1'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Install npm dependencies
+        run: bash scripts/ci-npm-ci-with-retry.sh
+
+      - name: Run frontend and script tests
+        run: npm run test
+
+      - name: Run BgFilter worker smoke harness tests
+        run: npm run bgfilter-worker:smoke-test
+
+      - name: Validate production health patrol behavior
+        run: npm run check:production-health-patrol
+
+      - name: Validate production API release behavior
+        run: npm run check:production-api-release
+
+      - name: Validate production API deploy behavior
+        run: npm run check:production-api-deploy
+
+  repository-checks:
+    name: Repository checks
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Resolve comparison base
+        shell: bash
+        run: |
+          set -euo pipefail
+          base_ref="$(node -e '
+            const fs = require("node:fs");
+            const event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
+            process.stdout.write(event.pull_request?.base?.sha ?? event.before ?? "");
+          ')"
+          if [[ -n "${base_ref}" && ! "${base_ref}" =~ ^0+$ ]]; then
+            git cat-file -e "${base_ref}^{commit}" 2>/dev/null || {
+              echo "comparison base commit is unavailable: ${base_ref}" >&2
+              exit 1
+            }
+          else
+            base_ref="$(git merge-base HEAD origin/master 2>/dev/null || git rev-parse HEAD)"
+          fi
+          resolved_base_ref="$(git rev-parse --verify "${base_ref}^{commit}" 2>/dev/null || true)"
+          head_ref="$(git rev-parse HEAD)"
+          if [[ "${resolved_base_ref}" == "${head_ref}" ]]; then
+            resolved_base_ref="$(git rev-parse --verify HEAD^ 2>/dev/null || true)"
+          fi
+          if [[ -z "${resolved_base_ref}" ]]; then
+            echo 'comparison base must resolve to a commit distinct from HEAD.' >&2
+            exit 1
+          fi
+          base_ref="${resolved_base_ref}"
+          if [[ "${GITHUB_EVENT_NAME:-}" == 'pull_request' ]] \
+            && ! git merge-base --is-ancestor "${base_ref}" HEAD; then
+            echo 'pull request head does not contain the latest base commit; update the branch and rerun CI.' >&2
+            exit 1
+          fi
+          echo "SPACETIME_SCHEMA_BASE_REF=${base_ref}" >> "${GITHUB_ENV}"
+
+      - name: Install npm dependencies
+        run: bash scripts/ci-npm-ci-with-retry.sh
+
+      - name: Run repository checks
+        run: npm run check:repository-ci
+
+  # 客户端的 AI 游戏创作壳前端门禁：typecheck 与壳内测试，不触碰 Cargo。
+  ai-game-creator-shell-web-tests:
+    name: AI game creator shell web tests
+    runs-on: genarrative-ci
+    steps:
+      - name: Checkout full history from Gitea
+        env:
+          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: genarrative-gitea-checkout
+
+      - name: Validate preinstalled CI job image and sandbox
+        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+
+      - name: Install npm dependencies
+        run: bash scripts/ci-npm-ci-with-retry.sh
+
+      - name: Run AI game creator shell web gates
+        run: npm run check:native-shells:agc-web

apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs

@@ -0,0 +1,461 @@
+#!/usr/bin/env node
+// AGC 壳 Rust 套件的分片运行器。
+//
+// 背景：AGC 壳的 Rust 单测集中在 src/main.rs 的 bin target（实测 2466 条），仓库口径用
+// `--test-threads=1` 跑，理由是并行调度会让共享 Agent Runtime 后台锁与异步终态的用例在
+// **同一进程内**互相干扰（见 development-workflow 的 Tauri suite 单线程口径）。代价是
+// 整套用例串行跑满 507 秒，占掉 CI 上 `AI game creator shell Rust tests` job 的大头。
+//
+// 这里保留「片内串行」的既有口径，只把用例集合切成 N 片：
+// - CI 用 `--shard-index=<i>` 让**每个 job 只跑一片**，靠多个 job 并发把整套用例摊开；
+// - 本地不传 `--shard-index` 时把 N 片放进 N 个**独立进程**并行（--concurrency 可调），
+//   保留一条命令跑全量的入口。
+// 片并集必须等于全集、且不得重复，数量不符即失败，防止分片规则改动后静默漏跑；该校验
+// 与「只跑一片」无关，因此在每个 job 上都会执行。
+//
+// 注意：同一容器内多进程并行这套用例（共享 HOME、target、固定临时路径）实测会互相拖慢，
+// 比串行还慢，所以 CI 走「一个 job 一片」而不是单 job 内并行。
+//
+// 用法：
+//   node scripts/run-rust-shell-test-shards.mjs --shards=4 --shard-index=2   # CI：只跑第 2 片
+//   node scripts/run-rust-shell-test-shards.mjs [--shards=4] [--concurrency=4]  # 本地：全量
+//   node scripts/run-rust-shell-test-shards.mjs --manifest=<Cargo.toml> --target-kind=lib --no-locked
+//
+// 参数：
+//   --shards=<n>        分片数，默认 4
+//   --shard-index=<i>   只跑第 i 片（1..shards）；不传则跑全部分片
+//   --concurrency=<n>   同时运行的片数，默认等于分片数；--shard-index 时恒为 1
+//   --manifest=<path>   Cargo.toml，默认 ../src-tauri/Cargo.toml（相对本脚本）
+//   --target-kind=<k>   bin | lib，默认 bin（本地自测小 crate 时用 lib）
+//   --bin=<name>        bin target 名，默认 genarrative-ai-game-creator-shell
+//   --package=<name>    target-kind=lib 时要跑的包名（配合 lib 目标使用）
+//   --no-locked         传给 cargo 时不带 --locked（只对没有提交 Cargo.lock 的 crate 需要）
+//   --shard-tmp-root=<path>  片专属 TMPDIR 的父目录，默认 <系统临时目录>/agc-rust-shards
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const shellRoot = path.resolve(scriptDirectory, '..');
+
+function fail(message) {
+  console.error(`[rust-shards] ${message}`);
+  process.exit(1);
+}
+
+function parsePositiveInteger(name, rawValue) {
+  if (!/^[1-9][0-9]*$/.test(rawValue)) {
+    fail(`${name} must be a positive integer, received: ${rawValue}`);
+  }
+
+  return Number(rawValue);
+}
+
+const options = {
+  shards: 4,
+  shardIndex: undefined,
+  concurrency: undefined,
+  manifestPath: path.join(shellRoot, 'src-tauri', 'Cargo.toml'),
+  targetKind: 'bin',
+  binName: 'genarrative-ai-game-creator-shell',
+  packageName: undefined,
+  locked: true,
+  shardTmpRoot: path.join(os.tmpdir(), 'agc-rust-shards'),
+};
+
+for (const rawArgument of process.argv.slice(2)) {
+  if (rawArgument === '--no-locked') {
+    options.locked = false;
+    continue;
+  }
+
+  const separatorIndex = rawArgument.indexOf('=');
+  if (!rawArgument.startsWith('--') || separatorIndex === -1) {
+    fail(`unexpected argument: ${rawArgument}`);
+  }
+
+  const name = rawArgument.slice(2, separatorIndex);
+  const value = rawArgument.slice(separatorIndex + 1);
+  switch (name) {
+    case 'shards':
+      options.shards = parsePositiveInteger('--shards', value);
+      break;
+    case 'shard-index':
+      options.shardIndex = parsePositiveInteger('--shard-index', value);
+      break;
+    case 'concurrency':
+      options.concurrency = parsePositiveInteger('--concurrency', value);
+      break;
+    case 'manifest':
+      options.manifestPath = path.resolve(process.cwd(), value);
+      break;
+    case 'target-kind':
+      if (value !== 'bin' && value !== 'lib') {
+        fail(`--target-kind must be bin or lib, received: ${value}`);
+      }
+      options.targetKind = value;
+      break;
+    case 'bin':
+      options.binName = value;
+      break;
+    case 'package':
+      options.packageName = value;
+      break;
+    case 'shard-tmp-root':
+      options.shardTmpRoot = path.resolve(process.cwd(), value);
+      break;
+    default:
+      fail(`unexpected argument: ${rawArgument}`);
+  }
+}
+
+if (!fs.existsSync(options.manifestPath)) {
+  fail(`manifest does not exist: ${options.manifestPath}`);
+}
+
+if (options.shardIndex !== undefined && options.shardIndex > options.shards) {
+  fail(
+    `--shard-index (${options.shardIndex}) must be within --shards (${options.shards})`,
+  );
+}
+
+const concurrency = options.concurrency ?? options.shards;
+const crateRoot = path.dirname(options.manifestPath);
+
+function buildCargoArguments(target) {
+  const cargoArguments = ['test'];
+  if (options.locked) {
+    cargoArguments.push('--locked');
+  }
+  cargoArguments.push('--manifest-path', options.manifestPath);
+  if (target.kind === 'lib') {
+    if (options.packageName !== undefined) {
+      cargoArguments.push('-p', options.packageName);
+    }
+    cargoArguments.push('--lib');
+    return cargoArguments;
+  }
+  cargoArguments.push('--bin', target.name);
+  return cargoArguments;
+}
+
+function formatDuration(milliseconds) {
+  return `${(milliseconds / 1000).toFixed(1)}s`;
+}
+
+// 编译一次，直接拿到测试可执行文件：后续每片都运行同一个二进制，不再各自调用 cargo，
+// 免得 N 个 cargo 去争 package cache 与 target 目录锁。
+function resolveTestExecutable() {
+  return new Promise((resolve, reject) => {
+    const cargoArguments = buildCargoArguments({
+      kind: options.targetKind,
+      name: options.binName,
+    });
+    cargoArguments.push('--no-run', '--message-format=json');
+    console.log(`[rust-shards] cargo ${cargoArguments.join(' ')}`);
+
+    const child = spawn('cargo', cargoArguments, {
+      cwd: crateRoot,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+
+    let buffered = '';
+    const executables = [];
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      buffered += chunk;
+      const lines = buffered.split('\n');
+      buffered = lines.pop() ?? '';
+      for (const line of lines) {
+        if (!line.startsWith('{')) {
+          continue;
+        }
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (
+          message.reason === 'compiler-artifact' &&
+          typeof message.executable === 'string'
+        ) {
+          executables.push(message.executable);
+        }
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(new Error(`unable to start cargo: ${error.message}`));
+    });
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            `cargo ${cargoArguments.join(' ')} failed with exit code ${code}`,
+          ),
+        );
+        return;
+      }
+      const uniqueExecutables = [...new Set(executables)];
+      if (uniqueExecutables.length !== 1) {
+        reject(
+          new Error(
+            `expected exactly one test executable for the ${options.targetKind} target, found ${uniqueExecutables.length}: ${uniqueExecutables.join(', ')}`,
+          ),
+        );
+        return;
+      }
+      resolve(uniqueExecutables[0]);
+    });
+  });
+}
+
+function listTestNames(executable) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, ['--list'], {
+      cwd: crateRoot,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      reject(new Error(`unable to list tests: ${error.message}`));
+    });
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            `listing tests failed with exit code ${code}: ${stderr.trim()}`,
+          ),
+        );
+        return;
+      }
+      const names = [];
+      for (const line of stdout.split('\n')) {
+        const match = /^(.*): test$/.exec(line.trim());
+        if (match !== null && match[1].length > 0) {
+          names.push(match[1]);
+        }
+      }
+      resolve(names);
+    });
+  });
+}
+
+function splitTestNames(testNames, shardCount) {
+  const sortedNames = [...testNames].sort();
+  const shards = Array.from({ length: shardCount }, () => []);
+  sortedNames.forEach((testName, index) => {
+    shards[index % shardCount].push(testName);
+  });
+  return shards;
+}
+
+function assertShardsCoverEveryTest(testNames, shards) {
+  const flattened = shards.flat();
+  if (flattened.length !== testNames.length) {
+    fail(
+      `shard split covered ${flattened.length} of ${testNames.length} tests; the split rule must be exhaustive`,
+    );
+  }
+  if (new Set(flattened).size !== flattened.length) {
+    fail(
+      'shard split selected the same test more than once; the split rule must be disjoint',
+    );
+  }
+  const missing = testNames.filter((testName) => !flattened.includes(testName));
+  if (missing.length > 0) {
+    fail(
+      `shard split is missing tests, for example: ${missing.slice(0, 5).join(', ')}`,
+    );
+  }
+}
+
+function runShard(executable, shardIndex, shardCount, shardTestNames) {
+  const label = `shard ${shardIndex + 1}/${shardCount}`;
+  const shardTmpDirectory = path.join(
+    options.shardTmpRoot,
+    `shard-${shardIndex + 1}`,
+  );
+  fs.rmSync(shardTmpDirectory, { recursive: true, force: true });
+  fs.mkdirSync(shardTmpDirectory, { recursive: true });
+  const startedAt = Date.now();
+
+  return new Promise((resolve) => {
+    const child = spawn(
+      executable,
+      ['--exact', ...shardTestNames, '--test-threads=1'],
+      {
+        cwd: crateRoot,
+        env: {
+          ...process.env,
+          TMPDIR: shardTmpDirectory,
+          TMP: shardTmpDirectory,
+          TEMP: shardTmpDirectory,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+
+    const failureLines = [];
+    let inFailureList = false;
+    let stderr = '';
+    const consumeLine = (rawLine) => {
+      const line = rawLine.replace(/\r$/, '');
+      if (line.includes('failures:')) {
+        inFailureList = true;
+        return;
+      }
+      if (inFailureList) {
+        if (line.trim().length === 0) {
+          inFailureList = false;
+          return;
+        }
+        failureLines.push(line.trim());
+      }
+    };
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    let stdoutBuffer = '';
+    child.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk;
+      const lines = stdoutBuffer.split('\n');
+      stdoutBuffer = lines.pop() ?? '';
+      for (const line of lines) {
+        consumeLine(line);
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on('error', (error) => {
+      resolve({
+        label,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        testCount: shardTestNames.length,
+        failures: [`unable to start test binary: ${error.message}`],
+        stderr,
+      });
+    });
+    child.on('close', (code) => {
+      resolve({
+        label,
+        ok: code === 0,
+        durationMs: Date.now() - startedAt,
+        testCount: shardTestNames.length,
+        failures: failureLines,
+        stderr,
+      });
+    });
+  });
+}
+
+async function runWithConcurrency(shards, runner) {
+  const results = new Array(shards.length);
+  let nextIndex = 0;
+  const workers = Array.from(
+    { length: Math.min(concurrency, shards.length) },
+    async () => {
+      while (nextIndex < shards.length) {
+        const index = nextIndex;
+        nextIndex += 1;
+        results[index] = await runner(shards[index], index);
+      }
+    },
+  );
+  await Promise.all(workers);
+  return results;
+}
+
+async function main() {
+  const executable = await resolveTestExecutable();
+  const testNames = await listTestNames(executable);
+  if (testNames.length === 0) {
+    fail(
+      `no tests discovered in ${options.manifestPath} (${options.targetKind})`,
+    );
+  }
+
+  const shards = splitTestNames(testNames, options.shards);
+  assertShardsCoverEveryTest(testNames, shards);
+
+  const selectedShards =
+    options.shardIndex === undefined
+      ? shards.map((shardTestNames, index) => ({ index, shardTestNames }))
+      : [
+          {
+            index: options.shardIndex - 1,
+            shardTestNames: shards[options.shardIndex - 1],
+          },
+        ];
+
+  if (options.shardIndex === undefined) {
+    console.log(
+      `[rust-shards] ${testNames.length} tests, ${shards.length} shard(s), concurrency ${Math.min(concurrency, shards.length)}`,
+    );
+    for (const { index, shardTestNames } of selectedShards) {
+      console.log(
+        `[rust-shards] shard ${index + 1}/${shards.length}: ${shardTestNames.length} test(s)`,
+      );
+    }
+  } else {
+    console.log(
+      `[rust-shards] ${testNames.length} tests, ${shards.length} shard(s), running shard ${options.shardIndex}/${shards.length} (${selectedShards[0].shardTestNames.length} test(s))`,
+    );
+  }
+
+  const results = await runWithConcurrency(
+    selectedShards,
+    ({ index, shardTestNames }) =>
+      runShard(executable, index, shards.length, shardTestNames),
+  );
+
+  let failed = false;
+  for (const result of results) {
+    if (result.ok) {
+      console.log(
+        `[rust-shards] ${result.label} ok: ${result.testCount} test(s) in ${formatDuration(result.durationMs)}`,
+      );
+      continue;
+    }
+    failed = true;
+    console.error(
+      `[rust-shards] ${result.label} FAILED: ${result.testCount} test(s) in ${formatDuration(result.durationMs)}`,
+    );
+    for (const failure of result.failures) {
+      console.error(`[rust-shards]   ${failure}`);
+    }
+    if (result.stderr.trim().length > 0) {
+      console.error(
+        `[rust-shards]   stderr: ${result.stderr.trim().split('\n').slice(-20).join('\n[rust-shards]   ')}`,
+      );
+    }
+  }
+
+  if (failed) {
+    process.exit(1);
+  }
+  console.log('[rust-shards] OK');
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});

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

@@ -84,6 +84,7 @@ function resolveBackendTargetsFromState(
     requireAgcBackend = false,
     expectedDatabase = backendDatabase,
     expectedSpacetimeDataDir = backendSpacetimeDataDir,
+    expectedRepoRoot = repoRoot,
     fallbackApiTarget = defaultApiTarget,
   } = {},
 ) {
@@ -101,7 +102,25 @@ function resolveBackendTargetsFromState(
   const hasMatchingDataDir =
     Boolean(spacetimeDataDir) &&
     spacetimeDataDir === resolve(expectedSpacetimeDataDir);
-  const hasMatchingBackend = hasMatchingDatabase && hasMatchingDataDir;
+  const instanceId =
+    typeof state?.instanceId === 'string' ? state.instanceId.trim() : '';
+  const hasMatchingRepoRoot =
+    typeof state?.repoRoot === 'string' &&
+    resolve(state.repoRoot) === resolve(expectedRepoRoot);
+  const hasMatchingInstance =
+    Boolean(instanceId) &&
+    [apiServer, spacetime, bgfilterWorker]
+      .filter(Boolean)
+      .every(
+        (service) =>
+          service.repoRoot &&
+          resolve(service.repoRoot) === resolve(expectedRepoRoot) &&
+          service.instanceId === instanceId,
+      );
+  const hasMatchingBackend =
+    hasMatchingDatabase &&
+    hasMatchingDataDir &&
+    (!requireAgcBackend || (hasMatchingRepoRoot && hasMatchingInstance));
   const canReuseState = !requireAgcBackend || hasMatchingBackend;
   const apiUrl =
     canReuseState && isActive(apiServer) && apiServer.url
@@ -127,6 +146,8 @@ function resolveBackendTargetsFromState(
     spacetimeDataDir,
     hasMatchingDatabase,
     hasMatchingDataDir,
+    hasMatchingRepoRoot,
+    hasMatchingInstance,
     hasMatchingBackend,
   };
 }

apps/ai-game-creator-shell/src-tauri/prompts/runtime/common.md

@@ -1,6 +1,6 @@
 处理代码任务时先用 project.search 定位，再用带行号的 file.read 获取足够上下文；单文件小改优先使用 file.patch；涉及多个文件时优先使用 project.patchset，它会自动创建 checkpoint，无需额外调用 project.checkpoint，并在成功后用返回的 checkpointId 调用 project.diff(includeContent=true) 审查整体变更；只有确认文件已废弃时才删除。
 
-每次成功执行 file.write、file.patch、file.delete、project.patchset 或 project.restore，以及每次真正启动 command.exec 或 command.start，都会产生新的项目 revision；最后一次修改后必须成功执行 project.verify、可验证 command.exec，或成功执行 command.run_limited 的 game.static_smoke，才能调用 respond_to_user 收束。文件回读不能替代可执行验证，验证后再次修改必须重新验证。需要执行 package.json 中的验证脚本时，先读取 package.json，再把真实脚本名和读到的完整命令原样提交给 project.verify；script 可以是 check、typecheck、test、lint、build，或使用 check:<name>、test:<name>（例如 test:unit）、lint:<name>、typecheck:<name>、build:<name>、verify:<name>、validate:<name> 形式的命名脚本，其中冒号后的每个非空段必须以字母或数字开头且只能包含字母、数字、连字符、下划线或点；不得猜测或改写 expectedCommand。
+每次成功执行 file.write、file.patch、file.delete、project.patchset 或 project.restore，以及每次真正启动 command.exec、command.start 或 project.bootstrap，都会产生新的项目 revision；DirectProject 的 npm/Phaser 工程先用 project.bootstrap {cwd:"game"} 执行受控无参数 npm install，再用 project.verify {cwd:"game",script:"build",expectedCommand:从 game/package.json 原样读取} 构建，并确认 game/dist/index.html 存在。最后一次修改后必须成功执行 project.verify、可验证 command.exec，或成功执行 command.run_limited 的 game.static_smoke，才能调用 respond_to_user 收束。文件回读不能替代可执行验证，验证后再次修改必须重新验证。需要执行 package.json 中的验证脚本时，先读取 package.json，再把真实脚本名和读到的完整命令原样提交给 project.verify；script 可以是 check、typecheck、test、lint、build，或使用 check:<name>、test:<name>（例如 test:unit）、lint:<name>、typecheck:<name>、build:<name>、verify:<name>、validate:<name> 形式的命名脚本，其中冒号后的每个非空段必须以字母或数字开头且只能包含字母、数字、连字符、下划线或点；不得猜测或改写 expectedCommand。
 
 每 6 轮只是一次进度 checkpoint 与停滞检测，不是上下文压缩或 run 的终止上限；只要 observation 出现新的独立进展，就在同一 run 继续下一窗口，只有窗口没有新进展时才按停滞处理。真正的上下文压缩仅由 token 阈值或显式 compact 触发。Agent 私有记忆只能由本人写入，跨 Agent 共享稳定结论用 blackboard.write，给单个 Agent 留上下文用 agent.message。
 

apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs

@@ -1378,15 +1378,19 @@ fn codex_app_server_thread_start_params(
     base_instructions: String,
     use_model_provider: bool,
 ) -> serde_json::Value {
-    // DirectProject is an autonomous Codex session.  The app-server sandbox
-    // remains the hard write boundary; approval prompts are not a second
-    // harness that can stall a turn.  DirectHome/ToolHost stay passive.
+    // DirectProject is an autonomous Codex session with explicit full OS
+    // access; approval prompts are not a second harness that can stall a turn.
+    // DirectHome/ToolHost stay passive.
     let approval_policy = "never";
     let mut params = serde_json::json!({
         "model": model,
         "cwd": workspace_path,
         "approvalPolicy": approval_policy,
-        "sandbox": if workspace_mode.allows_workspace_writes() { "workspace-write" } else { "read-only" },
+        "sandbox": if workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
+            "danger-full-access"
+        } else {
+            "read-only"
+        },
         "ephemeral": true,
         "baseInstructions": base_instructions
     });
@@ -1404,7 +1408,6 @@ fn codex_app_server_turn_start_params(
     thread_id: &str,
     input: serde_json::Value,
     model: &str,
-    workspace_path: &std::path::Path,
     workspace_mode: CodexAppServerWorkspaceMode,
     client_user_message_id: Option<&str>,
 ) -> serde_json::Value {
@@ -1415,14 +1418,12 @@ fn codex_app_server_turn_start_params(
         "model": model,
         "approvalPolicy": approval_policy,
     });
-    if workspace_mode.allows_workspace_writes() {
-        // npm install/build must resolve project dependencies. Network access
-        // is enabled only for DirectProject; writableRoots keeps the file-write
-        // boundary at the real game workspace.
+    if workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
+        // DirectProject is an explicitly user-selected local Codex session.
+        // Give the native Codex tools the full OS sandbox profile so they are
+        // not narrowed by a project-root writableRoots allowlist.
         params["sandboxPolicy"] = serde_json::json!({
-            "type": "workspaceWrite",
-            "writableRoots": [workspace_path],
-            "networkAccess": true
+            "type": "dangerFullAccess"
         });
     }
     if let Some(client_user_message_id) = client_user_message_id
@@ -1436,40 +1437,27 @@ fn codex_app_server_turn_start_params(
 }
 
 fn game_creator_codex_app_server_interaction_response(
-    workspace_path: &std::path::Path,
     workspace_mode: CodexAppServerWorkspaceMode,
     id: u64,
-    method: &str,
-    requested_grant_root: Option<&str>,
+    _method: &str,
+    _requested_grant_root: Option<&str>,
 ) -> serde_json::Value {
-    let direct_workspace = workspace_mode.allows_workspace_writes();
-    let file_change_within_workspace = game_creator_codex_file_change_request_is_allowed(
-        workspace_path,
-        method,
-        requested_grant_root,
-    );
-    if direct_workspace && file_change_within_workspace {
-        serde_json::json!({
+    if workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
+        // Full-access DirectProject sessions do not use a file-root allowlist
+        // or a second approval gate. The declared sandbox policy is the only
+        // capability boundary for native Codex operations.
+        return serde_json::json!({
             "id": id,
             "result": { "decision": "accept" }
-        })
-    } else if direct_workspace && method == "item/fileChange/requestApproval" {
-        serde_json::json!({
-            "id": id,
-            "error": {
-                "code": -32602,
-                "message": "Genarrative AGC 只允许当前项目工作区的文件变更审批"
-            }
-        })
-    } else {
-        serde_json::json!({
-            "id": id,
-            "error": {
-                "code": -32601,
-                "message": "Genarrative AGC 拒绝 app-server 的交互、审批与工具请求"
-            }
-        })
+        });
     }
+    serde_json::json!({
+        "id": id,
+        "error": {
+            "code": -32601,
+            "message": "Genarrative AGC 拒绝 app-server 的交互、审批与工具请求"
+        }
+    })
 }
 
 #[cfg(test)]
@@ -2734,7 +2722,6 @@ impl CodexAppServerConnection {
             &thread_id,
             input,
             model,
-            &self.inner.workspace_path,
             self.inner.workspace_mode,
             direct_client_turn_id,
         );
@@ -3293,7 +3280,6 @@ async fn read_game_creator_codex_app_server_stdout(
                         );
                     }
                     let response = game_creator_codex_app_server_interaction_response(
-                        &inner.workspace_path,
                         inner.workspace_mode,
                         id,
                         method,
@@ -3635,82 +3621,6 @@ async fn read_game_creator_codex_app_server_stderr(
     }
 }
 
-#[cfg(windows)]
-fn game_creator_codex_workspace_path_key(path: &std::path::Path) -> String {
-    let value = path.to_string_lossy();
-    value
-        .strip_prefix("\\\\?\\")
-        .unwrap_or(value.as_ref())
-        .replace('/', "\\")
-        .trim_end_matches('\\')
-        .to_ascii_lowercase()
-}
-
-fn game_creator_codex_grant_root_is_within_workspace(
-    workspace: &std::path::Path,
-    grant_root: &str,
-) -> bool {
-    fn canonicalize_with_missing_tail(path: &std::path::Path) -> Option<std::path::PathBuf> {
-        if !path.is_absolute()
-            || path
-                .components()
-                .any(|component| matches!(component, std::path::Component::ParentDir))
-        {
-            return None;
-        }
-        let mut existing = path.to_path_buf();
-        let mut missing_tail = Vec::new();
-        while !existing.exists() {
-            missing_tail.push(existing.file_name()?.to_os_string());
-            if !existing.pop() {
-                return None;
-            }
-        }
-        let mut normalized = existing.canonicalize().ok()?;
-        for component in missing_tail.iter().rev() {
-            normalized.push(component);
-        }
-        Some(normalized)
-    }
-
-    let workspace = workspace
-        .canonicalize()
-        .unwrap_or_else(|_| workspace.to_path_buf());
-    let Some(grant_root) = canonicalize_with_missing_tail(std::path::Path::new(grant_root)) else {
-        return false;
-    };
-    #[cfg(windows)]
-    {
-        let workspace_key = game_creator_codex_workspace_path_key(&workspace);
-        let grant_key = game_creator_codex_workspace_path_key(&grant_root);
-        grant_key == workspace_key
-            || grant_key
-                .strip_prefix(&workspace_key)
-                .is_some_and(|suffix| suffix.starts_with('\\'))
-    }
-    #[cfg(not(windows))]
-    {
-        grant_root == workspace || grant_root.starts_with(&workspace)
-    }
-}
-
-fn game_creator_codex_file_change_request_is_allowed(
-    workspace: &std::path::Path,
-    method: &str,
-    grant_root: Option<&str>,
-) -> bool {
-    if method != "item/fileChange/requestApproval" {
-        return false;
-    }
-    // `grantRoot: null` means the already-declared turn sandbox root. It is
-    // valid only for file changes; it must never authorize another capability
-    // or a broader permission request.
-    grant_root.is_none()
-        || grant_root.is_some_and(|grant_root| {
-            game_creator_codex_grant_root_is_within_workspace(workspace, grant_root)
-        })
-}
-
 async fn fail_game_creator_codex_app_server_connection(
     inner: &Weak<CodexAppServerInner>,
     error: String,
@@ -4481,7 +4391,6 @@ mod tests {
             "home-thread",
             serde_json::json!([{ "type": "text", "text": "你好" }]),
             "fixture-model",
-            workspace,
             CodexAppServerWorkspaceMode::DirectHome,
             None,
         );
@@ -4495,7 +4404,6 @@ mod tests {
             "item/permissions/requestApproval",
         ] {
             let response = game_creator_codex_app_server_interaction_response(
-                workspace,
                 CodexAppServerWorkspaceMode::DirectHome,
                 7,
                 method,
@@ -4513,14 +4421,10 @@ mod tests {
     }
 
     #[test]
-    fn direct_project_protocol_and_interactions_expose_only_the_real_game_workspace() {
+    fn direct_project_protocol_uses_full_access_without_a_root_allowlist() {
         let temp = tempfile::tempdir().expect("temp dir");
         let project_root = temp.path().join("project");
-        let assets = project_root.join("assets");
-        let agent = project_root.join(".agent");
         std::fs::create_dir_all(&project_root).expect("project root");
-        std::fs::create_dir(&assets).expect("assets directory");
-        std::fs::create_dir(&agent).expect("agent directory");
         let workspace =
             resolve_direct_codex_game_workspace(&project_root).expect("resolve project workspace");
         assert_eq!(
@@ -4536,83 +4440,40 @@ mod tests {
             true,
         );
         assert_eq!(thread["cwd"], serde_json::json!(workspace));
-        assert_eq!(thread["sandbox"], "workspace-write");
+        assert_eq!(thread["sandbox"], "danger-full-access");
 
         let turn = codex_app_server_turn_start_params(
             "project-thread",
             serde_json::json!([{ "type": "text", "text": "修复游戏" }]),
             "fixture-model",
-            &workspace,
             CodexAppServerWorkspaceMode::DirectProject,
             Some("direct-turn-0001"),
         );
         assert_eq!(turn["clientUserMessageId"], "direct-turn-0001");
         assert_eq!(
-            turn.pointer("/sandboxPolicy/writableRoots/0"),
-            Some(&serde_json::json!(workspace))
-        );
-        assert_eq!(
-            turn.pointer("/sandboxPolicy/networkAccess"),
-            Some(&serde_json::json!(true))
-        );
-        let authority_paths = [
-            turn.get("cwd"),
-            turn.pointer("/sandboxPolicy/writableRoots/0"),
-        ];
-        assert!(
-            authority_paths
-                .iter()
-                .flatten()
-                .all(|value| value.as_str() == Some(workspace.to_string_lossy().as_ref())),
-            "writable params must be exactly the project workspace"
+            turn.pointer("/sandboxPolicy/type"),
+            Some(&serde_json::json!("dangerFullAccess"))
         );
+        assert!(turn.pointer("/sandboxPolicy/writableRoots").is_none());
+        assert!(turn.pointer("/sandboxPolicy/networkAccess").is_none());
 
-        let workspace_string = workspace.to_string_lossy().into_owned();
-        for allowed_root in [None, Some(workspace_string.as_str())] {
+        for (id, method) in [
+            (9, "item/fileChange/requestApproval"),
+            (10, "item/commandExecution/requestApproval"),
+            (11, "item/permissions/requestApproval"),
+            (12, "item/tool/call"),
+        ] {
             let response = game_creator_codex_app_server_interaction_response(
-                &workspace,
                 CodexAppServerWorkspaceMode::DirectProject,
-                9,
-                "item/fileChange/requestApproval",
-                allowed_root,
+                id,
+                method,
+                Some("C:\\outside-project"),
             );
             assert_eq!(
                 response.pointer("/result/decision"),
                 Some(&serde_json::json!("accept"))
             );
         }
-        for forbidden_root in [assets, agent] {
-            let forbidden_root = forbidden_root.to_string_lossy().into_owned();
-            let response = game_creator_codex_app_server_interaction_response(
-                &workspace,
-                CodexAppServerWorkspaceMode::DirectProject,
-                10,
-                "item/fileChange/requestApproval",
-                Some(&forbidden_root),
-            );
-            assert_eq!(
-                response.pointer("/result/decision"),
-                Some(&serde_json::json!("accept")),
-                "project-root children must stay writable: {forbidden_root}"
-            );
-        }
-        for method in [
-            "item/commandExecution/requestApproval",
-            "item/permissions/requestApproval",
-            "item/tool/call",
-        ] {
-            for requested_root in [None, Some(workspace_string.as_str())] {
-                let response = game_creator_codex_app_server_interaction_response(
-                    &workspace,
-                    CodexAppServerWorkspaceMode::DirectProject,
-                    11,
-                    method,
-                    requested_root,
-                );
-                assert!(response.get("error").is_some());
-                assert!(response.get("result").is_none());
-            }
-        }
     }
 
     #[test]
@@ -4630,26 +4491,6 @@ mod tests {
         assert!(resolve_direct_codex_game_workspace(&file_root).is_err());
     }
 
-    #[cfg(all(unix, not(target_os = "macos")))]
-    #[test]
-    fn direct_project_grant_root_comparison_remains_case_sensitive() {
-        let temp = tempfile::tempdir().expect("temp dir");
-        let project_root = temp.path().join("Project");
-        let child = project_root.join("assets");
-        let different_case = temp.path().join("project").join("assets");
-        std::fs::create_dir_all(&child).expect("child directory");
-        std::fs::create_dir_all(&different_case).expect("different-case directory");
-
-        assert!(game_creator_codex_grant_root_is_within_workspace(
-            &project_root,
-            project_root.to_string_lossy().as_ref()
-        ));
-        assert!(!game_creator_codex_grant_root_is_within_workspace(
-            &project_root,
-            different_case.to_string_lossy().as_ref()
-        ));
-    }
-
     #[cfg(unix)]
     #[test]
     fn direct_project_rejects_a_non_directory_workspace() {
@@ -5246,51 +5087,25 @@ while IFS= read -r line; do :; done
     }
 
     #[test]
-    fn direct_file_change_approval_is_limited_to_workspace() {
-        let temp = tempfile::tempdir().expect("temp dir");
-        let workspace = temp.path().join("demo");
-        let child = workspace.join("assets");
-        let sibling = temp.path().join("demolition");
-        std::fs::create_dir_all(&child).expect("workspace child");
-        std::fs::create_dir(&sibling).expect("sibling");
-        assert!(game_creator_codex_file_change_request_is_allowed(
-            &workspace,
+    fn direct_project_interactions_accept_full_access_without_a_root_allowlist() {
+        for method in [
             "item/fileChange/requestApproval",
-            None
-        ));
-        assert!(game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            workspace.to_string_lossy().as_ref()
-        ));
-        assert!(game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            child.to_string_lossy().as_ref()
-        ));
-        assert!(!game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            sibling.to_string_lossy().as_ref()
-        ));
-        assert!(!game_creator_codex_file_change_request_is_allowed(
-            &workspace,
-            "item/fileChange/requestApproval",
-            Some(sibling.to_string_lossy().as_ref())
-        ));
-        assert!(!game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            sibling.join("missing").to_string_lossy().as_ref()
-        ));
-        assert!(game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            workspace.join("missing").to_string_lossy().as_ref()
-        ));
-        assert!(!game_creator_codex_grant_root_is_within_workspace(
-            &workspace,
-            workspace
-                .join("..")
-                .join("outside")
-                .to_string_lossy()
-                .as_ref()
-        ));
+            "item/commandExecution/requestApproval",
+            "item/permissions/requestApproval",
+            "item/tool/call",
+        ] {
+            let response = game_creator_codex_app_server_interaction_response(
+                CodexAppServerWorkspaceMode::DirectProject,
+                1,
+                method,
+                Some("C:\\outside-project"),
+            );
+            assert_eq!(
+                response.pointer("/result/decision"),
+                Some(&serde_json::json!("accept"))
+            );
+            assert!(response.get("error").is_none());
+        }
     }
 
     #[test]

apps/ai-game-creator-shell/src-tauri/src/agent/generation/prompt_context.rs

@@ -16,7 +16,7 @@ JSON schema:
     { "group": "balance", "role": "Difficulty", "summary": "数值交接摘要", "outputs": ["game/balance.json"], "next": "交给程序组读取" },
     { "group": "art", "role": "Asset", "summary": "美术交接摘要", "outputs": ["assets/manifest.art.json"], "next": "进入画板或本地资产登记" },
     { "group": "audio", "role": "SFX", "summary": "音乐音效交接摘要", "outputs": ["assets/manifest.audio.json"], "next": "进入画板音频链路" },
-    { "group": "code", "role": "Code", "summary": "程序交接摘要", "outputs": ["game/index.html"], "next": "交给 Playtest" },
+    { "group": "code", "role": "Code", "summary": "程序交接摘要", "outputs": ["game/index.html", "game/game.js", "game/package.json", "game/vite.config.js"], "next": "先 project.bootstrap，再 project.verify(build)，交给 Playtest" },
     { "group": "publishing", "role": "Publish", "summary": "运营交接摘要", "outputs": ["exports/README.md"], "next": "等待预览验收" }
   ],
   "handoffSummary": "六组 agent 的交接摘要，每组一行",
@@ -24,6 +24,7 @@ JSON schema:
 }
 
 gameHtml 规则：
+- 本次若目标是 Phaser/npm，workspaceMode 必须为 DirectProject；先写入完整 game/ 工程文件，再由受控项目工具安装与构建。
 - 此 JSON 协议仅用于已有的单文件 HTML 项目；npm / Phaser 项目必须使用 DirectProject，不能通过 gameHtml 交付 package.json 或模块源码。
 - 必须是单文件 HTML，不能加载远程脚本、远程图片、远程 CSS 或 CDN。
 - 必须包含 canvas、canvas getContext、实际绘制调用、键盘或鼠标输入、requestAnimationFrame 主循环、目标、失败或胜利状态、R 或按钮重开。

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_audit.rs

@@ -1192,6 +1192,7 @@ pub(in crate::agent) fn agent_runtime_public_action_input_summary(
             | "project.patchset"
             | "project.search"
             | "project.verify"
+            | "project.bootstrap"
             | "file.list"
             | "file.read"
             | "file.write"
@@ -1259,6 +1260,7 @@ pub(crate) fn agent_runtime_tool_action_fingerprint(
             | "command.stdin"
             | "command.terminate"
             | "project.verify"
+            | "project.bootstrap"
     )
     .then(|| {
         let metadata = command_sandbox_platform_metadata();
@@ -1468,11 +1470,23 @@ pub(crate) fn agent_runtime_tool_action_input_summary(
                 .and_then(|value| value.as_bool())
                 .unwrap_or(false)
         ),
+        "project.bootstrap" => {
+            format!(
+                "cwd={} · timeoutSeconds={}",
+                relative_path(&["cwd"]),
+                input
+                    .get("timeoutSeconds")
+                    .or_else(|| input.get("timeout_seconds"))
+                    .and_then(|value| value.as_u64())
+                    .unwrap_or(300)
+            )
+        }
         "project.verify" => {
             let expected_command = text(&["expectedCommand", "expected_command"]);
             let command_chars = expected_command.chars().count();
             format!(
-                "script={} · expectedCommandSha256={:x} · expectedCommandChars={} · timeoutSeconds={}",
+                "cwd={} · script={} · expectedCommandSha256={:x} · expectedCommandChars={} · timeoutSeconds={}",
+                relative_path(&["cwd"]),
                 text(&["script"]),
                 Sha256::digest(expected_command.as_bytes()),
                 command_chars,

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/action_execution.rs

@@ -184,6 +184,17 @@ pub(crate) async fn execute_game_creator_agent_runtime_tool_action_with_pending_
             )
             .await
         }
+        "project.bootstrap" => {
+            observe_agent_runtime_project_bootstrap(
+                root,
+                agent_id,
+                run_id,
+                action_id,
+                &action_fingerprint,
+                &action.input,
+            )
+            .await
+        }
         "project.checkpoint" => observe_agent_runtime_project_checkpoint(root),
         "project.restore" => {
             observe_agent_runtime_project_restore(root, agent_id, run_id, &action.input)

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs

@@ -8,10 +8,15 @@ pub(crate) struct AgentRuntimeAutonomousSourcePayloadStats {
 }
 
 pub(in crate::agent) fn agent_runtime_autonomous_project_verify_available(root: &Path) -> bool {
-    let package_path = root.join("package.json");
-    fs::symlink_metadata(package_path)
-        .map(|metadata| metadata.file_type().is_file() && !metadata.file_type().is_symlink())
-        .unwrap_or(false)
+    [root.join("package.json"), root.join("game/package.json")]
+        .into_iter()
+        .any(|package_path| {
+            fs::symlink_metadata(package_path)
+                .map(|metadata| {
+                    metadata.file_type().is_file() && !metadata.file_type().is_symlink()
+                })
+                .unwrap_or(false)
+        })
 }
 
 pub(in crate::agent) fn add_agent_runtime_autonomous_source_field(

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs

@@ -345,7 +345,7 @@ fn build_game_creator_agent_background_tool_plan_request_at(
     let project_tools_contract = if runtime_owner_artifact_validation_available {
         "project.search 使用 {\"query\":\"要查找的字面文本\",\"path\":\"\",\"maxResults\":20,\"caseSensitive\":false}，path 为空字符串时搜索整个项目，返回 path:line 和匹配行；当前固定 owner 的函数目录不广告 project.verify；project.checkpoint 使用空对象，只用于多个 file.* 写动作前或需要独立回退点时创建本地 checkpoint；project.patchset 会自动创建 checkpoint，不要为同一批变更额外调用 project.checkpoint；project.restore 使用 {\"checkpointId\":\"checkpoint id\"}；project.diff 使用 {\"checkpointId\":\"checkpoint id\",\"includeContent\":true,\"maxFiles\":20,\"maxChars\":24000}；git.inspect 使用 {\"includeDiff\":true,\"maxFiles\":20,\"maxChars\":24000}，只读项目根 Git 状态和有界 diff，不得用它提交、暂存、切分支、合并、重置、stash、worktree 或访问 remote。".to_string()
     } else {
-        "project.search 使用 {\"query\":\"要查找的字面文本\",\"path\":\"\",\"maxResults\":20,\"caseSensitive\":false}，path 为空字符串时搜索整个项目，返回 path:line 和匹配行；project.verify 使用 {\"script\":\"check|typecheck|test|lint|build\",\"expectedCommand\":\"从 package.json 读取的完整原始脚本\",\"timeoutSeconds\":120}，只执行项目根 package.json 中同名 npm 脚本，expectedCommand 不一致时拒绝执行，确认策略以当前工具策略中 project.verify 的独立权限为准；project.checkpoint 使用空对象，只用于多个 file.* 写动作前或需要独立回退点时创建本地 checkpoint；project.patchset 会自动创建 checkpoint，不要为同一批变更额外调用 project.checkpoint；project.restore 使用 {\"checkpointId\":\"checkpoint id\"}；project.diff 使用 {\"checkpointId\":\"checkpoint id\",\"includeContent\":true,\"maxFiles\":20,\"maxChars\":24000}；git.inspect 使用 {\"includeDiff\":true,\"maxFiles\":20,\"maxChars\":24000}，只读项目根 Git 状态和有界 diff，不得用它提交、暂存、切分支、合并、重置、stash、worktree 或访问 remote。".to_string()
+        "project.search 使用 {\"query\":\"要查找的字面文本\",\"path\":\"\",\"maxResults\":20,\"caseSensitive\":false}，path 为空字符串时搜索整个项目，返回 path:line 和匹配行；project.bootstrap 使用 {\"cwd\":\"game\",\"timeoutSeconds\":300}，只执行 game 目录无参数 npm install 并记录 package/lock 指纹；project.verify 使用 {\"script\":\"check|typecheck|test|lint|build\",\"expectedCommand\":\"从对应 cwd 的 package.json 读取的完整原始脚本\",\"timeoutSeconds\":120,\"cwd\":\"game\"}，只执行对应 cwd package.json 中同名 npm 脚本，build 必须确认 game/dist/index.html；expectedCommand 不一致时拒绝执行，确认策略以当前工具策略中 project.verify 的独立权限为准；project.checkpoint 使用空对象，只用于多个 file.* 写动作前或需要独立回退点时创建本地 checkpoint；project.patchset 会自动创建 checkpoint，不要为同一批变更额外调用 project.checkpoint；project.restore 使用 {\"checkpointId\":\"checkpoint id\"}；project.diff 使用 {\"checkpointId\":\"checkpoint id\",\"includeContent\":true,\"maxFiles\":20,\"maxChars\":24000}；git.inspect 使用 {\"includeDiff\":true,\"maxFiles\":20,\"maxChars\":24000}，只读项目根 Git 状态和有界 diff，不得用它提交、暂存、切分支、合并、重置、stash、worktree 或访问 remote。".to_string()
     };
     let prompt = format!(
         concat!(

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs

@@ -28,6 +28,7 @@ pub(crate) fn agent_runtime_executable_tools() -> Vec<&'static str> {
         "project.index",
         "project.search",
         "project.verify",
+        "project.bootstrap",
         "project.checkpoint",
         "project.restore",
         "project.diff",
@@ -83,6 +84,7 @@ pub(crate) fn agent_runtime_acceptance_evidence_tools() -> BTreeSet<&'static str
         "project.index",
         "project.search",
         "project.verify",
+        "project.bootstrap",
         "project.diff",
         "git.inspect",
         "project.patchset",

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver.rs

@@ -156,6 +156,7 @@ pub(super) const AGENT_RUNTIME_AUTONOMOUS_GAME_BUILD_AUTO_COMMAND_IDS: &[&str] =
     "file.delete",
     "project.patchset",
     "project.verify",
+    "project.bootstrap",
     "command.run_limited",
     "preview.validate",
     "canvas.asset_generate",

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/interaction.rs

@@ -109,6 +109,7 @@ pub(crate) fn agent_runtime_tool_requires_repository_context_fingerprint_gate(to
             | "project.index"
             | "project.search"
             | "project.verify"
+            | "project.bootstrap"
             | "project.checkpoint"
             | "project.patchset"
             | "project.restore"

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/command_ops.rs

@@ -857,6 +857,12 @@ pub(crate) async fn observe_agent_runtime_project_verify(
         .and_then(serde_json::Value::as_str)
         .unwrap_or_default()
         .to_string();
+    let cwd = input
+        .get("cwd")
+        .and_then(serde_json::Value::as_str)
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or(".")
+        .to_string();
     let timeout_seconds =
         agent_runtime_tool_input_usize(input, &["timeoutSeconds", "timeout_seconds"])
             .unwrap_or(AGENT_RUNTIME_PROJECT_VERIFY_DEFAULT_TIMEOUT_SECONDS);
@@ -896,6 +902,7 @@ pub(crate) async fn observe_agent_runtime_project_verify(
         script.as_str(),
         expected_command.as_str(),
         timeout_seconds,
+        cwd.as_str(),
         || {
             verification_state = Some(begin_agent_runtime_project_verification_locked(
                 root,
@@ -931,6 +938,7 @@ pub(crate) async fn observe_agent_runtime_project_verify(
                 "script": verification.script,
                 "expectedCommand": audit_expected_command,
                 "packageManager": verification.package_manager,
+                "cwd": verification.cwd_relative,
                 "status": verification.status,
                 "exitCode": verification.exit_code,
                 "timedOut": verification.timed_out,
@@ -1039,3 +1047,81 @@ pub(crate) async fn observe_agent_runtime_project_verify(
         }
     }
 }
+
+pub(crate) async fn observe_agent_runtime_project_bootstrap(
+    root: &Path,
+    agent_id: &str,
+    run_id: &str,
+    action_id: Option<&str>,
+    action_fingerprint: &str,
+    input: &serde_json::Value,
+) -> AgentRuntimeToolObservation {
+    let cwd = input
+        .get("cwd")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or_default();
+    let timeout = agent_runtime_tool_input_usize(input, &["timeoutSeconds", "timeout_seconds"])
+        .unwrap_or(300);
+    if cwd != "game" {
+        return AgentRuntimeToolObservation {
+            tool: "project.bootstrap".to_string(),
+            status: "failed".to_string(),
+            summary: "project.bootstrap 只允许 cwd=game".to_string(),
+            detail: None,
+        };
+    }
+    let _lock = match acquire_project_write_lock(root, "project.bootstrap") {
+        Ok(lock) => lock,
+        Err(error) => {
+            return AgentRuntimeToolObservation {
+                tool: "project.bootstrap".to_string(),
+                status: "failed".to_string(),
+                summary: "project.bootstrap 无法取得项目执行锁".to_string(),
+                detail: Some(redact_agent_runtime_project_paths(root, &error, 240)),
+            }
+        }
+    };
+    let result = crate::project::run_project_bootstrap_at(root, timeout as u64).await;
+    match result {
+        Ok(value) if value.status == "completed" => {
+            if let Err(error) = append_agent_db_record(
+                root,
+                serde_json::json!({
+                    "recordType":"agent.runtime.project.bootstrap", "agentId":agent_id, "runId":run_id,
+                    "actionId":action_id, "actionFingerprint":action_fingerprint, "cwd":"game",
+                    "packageSha256":value.package_sha256, "lockSha256":value.lock_sha256,
+                    "status":value.status, "logPath":value.log_path, "output":value.output
+                }),
+            ) {
+                return AgentRuntimeToolObservation {
+                    tool: "project.bootstrap".to_string(),
+                    status: AGENT_RUNTIME_TOOL_OBSERVATION_STATUS_NEEDS_RECONCILIATION.to_string(),
+                    summary: "project.bootstrap 已安装，但审计记录无法落盘".to_string(),
+                    detail: Some(redact_agent_runtime_project_paths(root, &error, 500)),
+                };
+            }
+            AgentRuntimeToolObservation {
+                tool: "project.bootstrap".to_string(),
+                status: "ok".to_string(),
+                summary: "game 依赖安装已完成".to_string(),
+                detail: Some(format!(
+                    "cwd=game · packageSha256={} · lockSha256={}",
+                    value.package_sha256,
+                    value.lock_sha256.as_deref().unwrap_or("none")
+                )),
+            }
+        }
+        Ok(value) => AgentRuntimeToolObservation {
+            tool: "project.bootstrap".to_string(),
+            status: "failed".to_string(),
+            summary: "game 依赖安装失败".to_string(),
+            detail: Some(value.output),
+        },
+        Err(error) => AgentRuntimeToolObservation {
+            tool: "project.bootstrap".to_string(),
+            status: "failed".to_string(),
+            summary: redact_agent_runtime_project_paths(root, &error, 240),
+            detail: None,
+        },
+    }
+}

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

@@ -1009,7 +1009,8 @@ fn runtime_tool_description(tool: &str) -> &'static str {
         }
         "project.index" => "刷新并读取有界仓库启动上下文。",
         "project.search" => "在项目文本文件中做有界字面量搜索。",
-        "project.verify" => "运行 package.json 中原样声明的验证脚本。",
+        "project.verify" => "在项目或指定相对 cwd 中运行 package.json 原样声明的验证脚本，并检查构建产物。",
+        "project.bootstrap" => "仅在项目 game 目录受控执行无参数 npm install，并记录依赖文件指纹。",
         "project.checkpoint" => "创建项目本地 checkpoint。",
         "project.restore" => "从 checkpoint 恢复当前项目。",
         "project.diff" => "读取 checkpoint 与当前项目之间的有界差异。",
@@ -1154,10 +1155,18 @@ fn runtime_tool_input_schema(tool: &str) -> Value {
             }
         }),
         "project.verify" => json!({
-            "type": "object", "required": ["script", "expectedCommand", "timeoutSeconds"], "additionalProperties": false,
+            "type": "object", "required": ["script", "expectedCommand", "timeoutSeconds", "cwd"], "additionalProperties": false,
             "properties": {
                 "script": { "type": "string", "minLength": 1 },
                 "expectedCommand": { "type": "string", "minLength": 1 },
+                "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 600 },
+                "cwd": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9._/-]+$" }
+            }
+        }),
+        "project.bootstrap" => json!({
+            "type": "object", "required": ["cwd", "timeoutSeconds"], "additionalProperties": false,
+            "properties": {
+                "cwd": { "type": "string", "const": "game" },
                 "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }
             }
         }),

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

@@ -647,9 +647,9 @@ pub(crate) fn register_design_artifacts_at(root: &Path) -> Result<usize, String>
         register_local_asset_at(
             root,
             &relative,
-            "design-document",
+            "document",
             media_type,
-            "design-document",
+            "document",
             GameCreationAppAssetSource {
                 kind: GameCreationAppAssetSourceKind::Uploaded,
                 canvas_project_id: None,

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

@@ -321,6 +321,44 @@ pub(crate) fn resolve_project_command_spec_at(
         .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Validation, error))
 }
 
+/// Resolves the one privileged npm operation used to hydrate a DirectProject.
+/// It intentionally bypasses the general command.exec npm allow-list: callers
+/// must use the dedicated `project.bootstrap` action, which only accepts the
+/// literal `npm install` in the project's `game` directory.
+pub(crate) fn resolve_project_bootstrap_spec_at(
+    root: &Path,
+    timeout_seconds: u64,
+) -> Result<ProjectCommandSpec, ProjectCommandError> {
+    validate_project_root(root)
+        .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Validation, error))?;
+    let cwd_relative = "game".to_string();
+    let cwd = resolve_local_project_path(root, &cwd_relative)
+        .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Validation, error))?;
+    validate_project_command_cwd_components(root, &cwd_relative)
+        .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Validation, error))?;
+    if !(PROJECT_COMMAND_MIN_TIMEOUT_SECONDS..=PROJECT_COMMAND_MAX_TIMEOUT_SECONDS)
+        .contains(&timeout_seconds)
+    {
+        return Err(ProjectCommandError::new(
+            ProjectCommandErrorStage::Validation,
+            format!("project.bootstrap timeoutSeconds 必须在 {PROJECT_COMMAND_MIN_TIMEOUT_SECONDS}-{PROJECT_COMMAND_MAX_TIMEOUT_SECONDS} 之间"),
+        ));
+    }
+    let program = "npm".to_string();
+    let (executable, safe_path) = resolve_project_command_executable(root, &program)
+        .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Validation, error))?;
+    Ok(ProjectCommandSpec {
+        program,
+        executable,
+        safe_path,
+        arguments: vec!["install".to_string()],
+        cwd_relative,
+        cwd,
+        timeout_seconds,
+        verification_eligible: false,
+    })
+}
+
 fn resolve_project_command_spec_inner(
     root: &Path,
     program: &str,
@@ -1202,6 +1240,19 @@ pub(crate) fn prepare_project_command_launch_spec(
         (OsString::from("NO_PROXY"), OsString::new()),
         (OsString::from("PATH"), spec.safe_path.clone()),
     ];
+    if spec
+        .arguments
+        .first()
+        .is_some_and(|argument| argument == "install")
+    {
+        for (name, value) in &mut environment {
+            match name.to_string_lossy().as_ref() {
+                "npm_config_offline" => *value = OsString::from("false"),
+                "HTTP_PROXY" | "HTTPS_PROXY" | "ALL_PROXY" => *value = OsString::new(),
+                _ => {}
+            }
+        }
+    }
     for name in ["SystemRoot", "PATHEXT", "RUSTUP_HOME"] {
         if let Some(value) = std::env::var_os(name) {
             environment.push((OsString::from(name), value));
@@ -1998,6 +2049,16 @@ pub(crate) async fn run_project_command_with_output_at(
         .await
 }
 
+pub(crate) async fn run_project_bootstrap_command_at(
+    root: &Path,
+    timeout_seconds: u64,
+) -> Result<ProjectCommandResult, ProjectCommandError> {
+    let spec = resolve_project_bootstrap_spec_at(root, timeout_seconds)?;
+    let launch = prepare_project_command_launch_spec(root, &spec)?;
+    let staged = stage_project_command_launch_spec(&spec, launch)?;
+    run_prepared_project_command_with_output_at(root, &spec, staged, None, || Ok(())).await
+}
+
 pub(crate) async fn run_prepared_project_command_with_output_at<F>(
     root: &Path,
     spec: &ProjectCommandSpec,

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

@@ -302,7 +302,19 @@ mod linux {
         cwd: &Path,
         environment: &[(OsString, OsString)],
     ) -> Result<CommandSandboxLaunch, CommandSandboxError> {
-        let metadata = CommandSandboxMetadata::enforced_linux();
+        let mut metadata = CommandSandboxMetadata::enforced_linux();
+        let network_enabled = executable
+            .file_name()
+            .and_then(OsStr::to_str)
+            .is_some_and(|name| {
+                name.eq_ignore_ascii_case("npm") || name.eq_ignore_ascii_case("npm.cmd")
+            })
+            && arguments
+                .first()
+                .is_some_and(|argument| argument == "install");
+        if network_enabled {
+            metadata.network = "enabled";
+        }
         let bwrap = find_trusted_bwrap().map_err(|error| {
             CommandSandboxError::new(
                 format!("command sandbox unavailable: {error}"),
@@ -363,7 +375,7 @@ mod linux {
             )?;
         let fixed_system_read_only = collect_fixed_system_mounts();
 
-        let launch = build_linux_bwrap_launch(LinuxSandboxPlan {
+        let mut launch = build_linux_bwrap_launch(LinuxSandboxPlan {
             bwrap,
             root,
             cwd,
@@ -375,6 +387,7 @@ mod linux {
             external_read_only,
             fixed_system_read_only,
         });
+        launch.metadata = metadata.clone();
         run_project_mount_preflight(&launch).map_err(|error| {
             CommandSandboxError::new(
                 format!("command sandbox project mount preflight 失败：{error}"),
@@ -602,7 +615,19 @@ mod linux {
 
     fn build_linux_bwrap_launch(plan: LinuxSandboxPlan) -> CommandSandboxLaunch {
         let mut args = Vec::<OsString>::new();
-        push_namespace_arguments(&mut args);
+        push_namespace_arguments(
+            &mut args,
+            plan.executable
+                .file_name()
+                .and_then(OsStr::to_str)
+                .is_some_and(|name| {
+                    name.eq_ignore_ascii_case("npm") || name.eq_ignore_ascii_case("npm.cmd")
+                })
+                && plan
+                    .arguments
+                    .first()
+                    .is_some_and(|argument| argument == "install"),
+        );
         push_ro_bind(&mut args, Path::new("/usr"), Path::new("/usr"));
         for (target, destination) in &plan.merged_usr_links {
             push_option(
@@ -673,7 +698,7 @@ mod linux {
         }
     }
 
-    fn push_namespace_arguments(args: &mut Vec<OsString>) {
+    fn push_namespace_arguments(args: &mut Vec<OsString>, share_network: bool) {
         for argument in [
             "--die-with-parent",
             "--unshare-all",
@@ -686,6 +711,9 @@ mod linux {
         ] {
             args.push(OsString::from(argument));
         }
+        if share_network {
+            args.push(OsString::from("--share-net"));
+        }
     }
 
     fn push_option<'a, I>(args: &mut Vec<OsString>, option: &str, values: I)
@@ -829,7 +857,7 @@ mod linux {
         merged_usr_links: &[(OsString, PathBuf)],
     ) -> Result<(), String> {
         let mut args = Vec::<OsString>::new();
-        push_namespace_arguments(&mut args);
+        push_namespace_arguments(&mut args, false);
         push_ro_bind(&mut args, Path::new("/usr"), Path::new("/usr"));
         for (target, destination) in merged_usr_links {
             push_option(

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

@@ -1945,28 +1945,36 @@ pub(crate) fn read_platform_account_session_generation() -> u64 {
 }
 
 #[tauri::command]
-pub(crate) fn install_platform_account_session(
+pub(crate) async fn install_platform_account_session(
     user_id: String,
     access_token: String,
     api_base_url: String,
     generation: u64,
 ) -> Result<(), String> {
-    validate_platform_session_input(&user_id, &access_token, &api_base_url, generation)?;
-    install_external_agent_runner_platform_session(
-        &user_id,
-        &access_token,
-        &api_base_url,
-        generation,
-    )?;
-    install_platform_session(&user_id, &access_token, &api_base_url, generation)
+    tokio::task::spawn_blocking(move || {
+        validate_platform_session_input(&user_id, &access_token, &api_base_url, generation)?;
+        install_external_agent_runner_platform_session(
+            &user_id,
+            &access_token,
+            &api_base_url,
+            generation,
+        )?;
+        install_platform_session(&user_id, &access_token, &api_base_url, generation)
+    })
+    .await
+    .map_err(|error| format!("安装本地运行时会话任务意外终止：{error}"))?
 }
 
 #[tauri::command]
-pub(crate) fn clear_platform_account_session(generation: u64) -> Result<(), String> {
-    shutdown_game_creator_codex_app_servers()?;
-    clear_external_agent_runner_platform_session(generation)?;
-    clear_platform_session(generation);
-    Ok(())
+pub(crate) async fn clear_platform_account_session(generation: u64) -> Result<(), String> {
+    tokio::task::spawn_blocking(move || {
+        shutdown_game_creator_codex_app_servers()?;
+        clear_external_agent_runner_platform_session(generation)?;
+        clear_platform_session(generation);
+        Ok(())
+    })
+    .await
+    .map_err(|error| format!("清除本地运行时会话任务意外终止：{error}"))?
 }
 
 #[tauri::command]

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

@@ -39,6 +39,7 @@ pub(crate) const ISOLATED_AGENT_PRIVATE_MEMORY_SCHEMA_VERSION: &str =
 
 pub(crate) const ISOLATED_AGENT_UNSCOPED_DENIED_COMMAND_IDS: &[&str] = &[
     "project.verify",
+    "project.bootstrap",
     "project.git_commit",
     "command.exec",
     "command.start",
@@ -59,6 +60,7 @@ pub(crate) const ISOLATED_AGENT_UNSCOPED_DENIED_COMMAND_IDS: &[&str] = &[
 
 pub(crate) const ISOLATED_AGENT_UNSCOPED_DENIED_TOOLS: &[&str] = &[
     "project.verify",
+    "project.bootstrap",
     "project.git_commit",
     "command.exec",
     "command.start",

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

@@ -6,6 +6,7 @@ use std::io::{Seek, SeekFrom};
 mod agent_db;
 mod asset_export;
 mod asset_rename;
+mod bootstrap;
 mod checkpoint;
 mod conversation;
 mod export;
@@ -23,6 +24,7 @@ mod write_lock;
 pub(crate) use agent_db::*;
 pub(crate) use asset_export::*;
 pub(crate) use asset_rename::*;
+pub(crate) use bootstrap::*;
 pub(crate) use checkpoint::*;
 pub(crate) use conversation::*;
 pub(crate) use export::*;

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

@@ -0,0 +1,113 @@
+use super::*;
+use sha2::{Digest, Sha256};
+
+const BOOTSTRAP_PACKAGE_MAX_BYTES: u64 = 512 * 1024;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct ProjectBootstrapResult {
+    pub(crate) status: String,
+    pub(crate) output: String,
+    pub(crate) package_sha256: String,
+    pub(crate) lock_sha256: Option<String>,
+    pub(crate) log_path: String,
+    pub(crate) updated_at: u64,
+}
+
+fn read_bootstrap_file(path: &Path, label: &str) -> Result<Vec<u8>, String> {
+    let metadata = fs::symlink_metadata(path)
+        .map_err(|error| format!("读取 {label} 失败：{}: {error}", path.display()))?;
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err(format!("project.bootstrap 要求 {label} 是普通文件"));
+    }
+    if metadata.len() > BOOTSTRAP_PACKAGE_MAX_BYTES {
+        return Err(format!(
+            "project.bootstrap {label} 超过 {} 字节上限",
+            BOOTSTRAP_PACKAGE_MAX_BYTES
+        ));
+    }
+    prepare_game_creator_private_path_for_read(path, false, label)?;
+    fs::read(path).map_err(|error| format!("读取 {label} 失败：{error}"))
+}
+
+pub(crate) async fn run_project_bootstrap_at(
+    root: &Path,
+    timeout_seconds: u64,
+) -> Result<ProjectBootstrapResult, String> {
+    validate_project_root(root)?;
+    let game = resolve_local_project_path(root, "game")?;
+    if !game.is_dir() {
+        return Err("project.bootstrap 只允许项目内 game 目录".to_string());
+    }
+    let package = read_bootstrap_file(&game.join("package.json"), "game/package.json")?;
+    let package_json: serde_json::Value = serde_json::from_slice(&package)
+        .map_err(|error| format!("解析 game/package.json 失败：{error}"))?;
+    if let Some(manager) = package_json
+        .get("packageManager")
+        .and_then(serde_json::Value::as_str)
+    {
+        if !manager.trim().starts_with("npm@") && manager.trim() != "npm" {
+            return Err("project.bootstrap 当前只支持 npm packageManager".to_string());
+        }
+    }
+    for lock_name in ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"] {
+        if game.join(lock_name).exists() {
+            return Err(format!("project.bootstrap 检测到非 npm 锁文件 {lock_name}"));
+        }
+    }
+    if !package_json
+        .get("scripts")
+        .is_some_and(serde_json::Value::is_object)
+    {
+        return Err("project.bootstrap 要求 game/package.json 包含 scripts 对象".to_string());
+    }
+    let lock = match fs::symlink_metadata(game.join("package-lock.json")) {
+        Ok(_) => Some(read_bootstrap_file(
+            &game.join("package-lock.json"),
+            "game/package-lock.json",
+        )?),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
+        Err(error) => return Err(format!("读取 game/package-lock.json 失败：{error}")),
+    };
+    let command = crate::command_exec::run_project_bootstrap_command_at(root, timeout_seconds)
+        .await
+        .map_err(|error| error.to_string())?;
+    let completed = command.exit_code == Some(0) && !command.timed_out;
+    let status = if completed { "completed" } else { "failed" };
+    let updated_at = unix_timestamp();
+    let log_path = resolve_local_project_path(root, ".agent/logs/command.log")?;
+    let package_sha256 = format!("{:x}", Sha256::digest(&package));
+    let lock_sha256 = lock
+        .as_ref()
+        .map(|bytes| format!("{:x}", Sha256::digest(bytes)));
+    let output = sanitize_project_verification_output(&command.output);
+    let line = format!(
+        "{updated_at} project.bootstrap status={} packageSha256={} lockSha256={} cwd=game\n{}\n",
+        status,
+        package_sha256,
+        lock_sha256.as_deref().unwrap_or("none"),
+        output
+    );
+    append_game_creator_private_file(&log_path, line.as_bytes(), "命令日志")?;
+    record_command_run(
+        root,
+        GameCreationAppCommandRunState {
+            command_id: "project.bootstrap".to_string(),
+            status: if completed {
+                GameCreationAppCommandRunStatus::Completed
+            } else {
+                GameCreationAppCommandRunStatus::Failed
+            },
+            output: output.clone(),
+            log_path: ".agent/logs/command.log".to_string(),
+            updated_at,
+        },
+    )?;
+    Ok(ProjectBootstrapResult {
+        status: status.to_string(),
+        output,
+        package_sha256,
+        lock_sha256,
+        log_path: ".agent/logs/command.log".to_string(),
+        updated_at,
+    })
+}

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

@@ -121,6 +121,7 @@ pub(crate) struct ProjectVerificationSpec {
     pub(crate) program: String,
     pub(crate) arguments: Vec<String>,
     pub(crate) timeout_seconds: u64,
+    pub(crate) cwd_relative: String,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -129,6 +130,7 @@ pub(crate) struct ProjectVerificationResult {
     pub(crate) script: String,
     pub(crate) expected_command: String,
     pub(crate) package_manager: String,
+    pub(crate) cwd_relative: String,
     pub(crate) status: String,
     pub(crate) exit_code: Option<i32>,
     pub(crate) timed_out: bool,
@@ -290,9 +292,38 @@ pub(crate) fn resolve_project_verification_spec_at(
     script: &str,
     expected_command: &str,
     timeout_seconds: u64,
+) -> Result<ProjectVerificationSpec, String> {
+    resolve_project_verification_spec_with_cwd_at(
+        root,
+        script,
+        expected_command,
+        timeout_seconds,
+        ".",
+    )
+}
+
+pub(crate) fn resolve_project_verification_spec_with_cwd_at(
+    root: &Path,
+    script: &str,
+    expected_command: &str,
+    timeout_seconds: u64,
+    cwd_relative: &str,
 ) -> Result<ProjectVerificationSpec, String> {
     validate_project_root(root)?;
-    ensure_project_verification_has_no_project_npmrc(root)?;
+    let cwd_relative = if cwd_relative.trim().is_empty() || cwd_relative.trim() == "." {
+        ".".to_string()
+    } else {
+        normalize_relative_path(cwd_relative)?
+    };
+    let package_root = if cwd_relative == "." {
+        root.to_path_buf()
+    } else {
+        resolve_local_project_path(root, &cwd_relative)?
+    };
+    if !package_root.is_dir() {
+        return Err("project.verify cwd 必须是项目内普通目录".to_string());
+    }
+    ensure_project_verification_has_no_project_npmrc(&package_root)?;
     let script = script.trim();
     if script.chars().count() > PROJECT_VERIFICATION_SCRIPT_MAX_CHARS {
         return Err(format!(
@@ -323,7 +354,7 @@ pub(crate) fn resolve_project_verification_spec_at(
         ));
     }
 
-    let package_path = root.join("package.json");
+    let package_path = package_root.join("package.json");
     let metadata = fs::symlink_metadata(&package_path).map_err(|error| {
         format!(
             "读取 package.json 失败：{}: {error}",
@@ -348,7 +379,7 @@ pub(crate) fn resolve_project_verification_spec_at(
     })?;
     let package: serde_json::Value = serde_json::from_str(&package_content)
         .map_err(|error| format!("解析 package.json 失败：{error}"))?;
-    let package_manager = project_verification_package_manager_at(root, &package)?;
+    let package_manager = project_verification_package_manager_at(&package_root, &package)?;
     let actual_command = package
         .get("scripts")
         .and_then(serde_json::Value::as_object)
@@ -360,6 +391,20 @@ pub(crate) fn resolve_project_verification_spec_at(
             "package.json 中的 {script} 脚本已变化，请重新读取后再确认执行"
         ));
     }
+    if script == "build" && cwd_relative == "game" {
+        let modules_path = package_root.join("node_modules");
+        let modules_metadata = fs::symlink_metadata(&modules_path).map_err(|error| {
+            if error.kind() == std::io::ErrorKind::NotFound {
+                "project.verify build 前缺少 game/node_modules；请先执行 project.bootstrap"
+                    .to_string()
+            } else {
+                format!("project.verify 检查 game/node_modules 失败：{error}")
+            }
+        })?;
+        if modules_metadata.file_type().is_symlink() || !modules_metadata.is_dir() {
+            return Err("project.verify build 前的 game/node_modules 不是普通目录；请重新执行 project.bootstrap".to_string());
+        }
+    }
 
     Ok(ProjectVerificationSpec {
         script: script.to_string(),
@@ -373,6 +418,7 @@ pub(crate) fn resolve_project_verification_spec_at(
             script.to_string(),
         ],
         timeout_seconds,
+        cwd_relative,
     })
 }
 
@@ -485,10 +531,21 @@ async fn run_project_verification_process<F>(
 where
     F: FnOnce() -> Result<(), String>,
 {
-    ensure_project_verification_has_no_project_npmrc(root)
+    let package_root = if spec.cwd_relative == "." {
+        root.to_path_buf()
+    } else {
+        resolve_local_project_path(root, &spec.cwd_relative)
+            .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Preflight, error))?
+    };
+    ensure_project_verification_has_no_project_npmrc(&package_root)
         .map_err(|error| ProjectCommandError::new(ProjectCommandErrorStage::Preflight, error))?;
-    let command_spec =
-        resolve_project_command_spec_at(root, "npm", &spec.arguments, ".", spec.timeout_seconds)?;
+    let command_spec = resolve_project_command_spec_at(
+        root,
+        "npm",
+        &spec.arguments,
+        &spec.cwd_relative,
+        spec.timeout_seconds,
+    )?;
     let launch = prepare_project_command_launch_spec(root, &command_spec)?;
     let launch_metadata = launch.clone();
     let staged = stage_project_command_launch_spec(&command_spec, launch)?;
@@ -620,9 +677,14 @@ pub(crate) async fn run_project_verification_at(
     expected_command: &str,
     timeout_seconds: u64,
 ) -> Result<ProjectVerificationResult, String> {
-    run_project_verification_with_commit_at(root, script, expected_command, timeout_seconds, || {
-        Ok(())
-    })
+    run_project_verification_with_commit_at(
+        root,
+        script,
+        expected_command,
+        timeout_seconds,
+        ".",
+        || Ok(()),
+    )
     .await
 }
 
@@ -631,15 +693,21 @@ pub(crate) async fn run_project_verification_with_commit_at<F>(
     script: &str,
     expected_command: &str,
     timeout_seconds: u64,
+    cwd_relative: &str,
     durable_commit: F,
 ) -> Result<ProjectVerificationResult, String>
 where
     F: FnOnce() -> Result<(), String>,
 {
-    let spec =
-        resolve_project_verification_spec_at(root, script, expected_command, timeout_seconds)?;
+    let spec = resolve_project_verification_spec_with_cwd_at(
+        root,
+        script,
+        expected_command,
+        timeout_seconds,
+        cwd_relative,
+    )?;
     let started_at = std::time::Instant::now();
-    let process = match run_project_verification_process(root, &spec, durable_commit).await {
+    let mut process = match run_project_verification_process(root, &spec, durable_commit).await {
         Ok(process) => process,
         Err(error) if error.needs_reconciliation() => {
             return Err(format!("project.verify 执行状态需要人工核对：{error}"));
@@ -658,7 +726,18 @@ where
         },
     };
     let duration_ms = u64::try_from(started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
-    let completed = !process.timed_out && process.exit_code == Some(0);
+    let mut completed = !process.timed_out && process.exit_code == Some(0);
+    if completed && spec.script == "build" && spec.cwd_relative == "game" {
+        let dist_entry = root.join("game").join("dist").join("index.html");
+        completed = fs::symlink_metadata(&dist_entry)
+            .is_ok_and(|metadata| metadata.is_file() && !metadata.file_type().is_symlink());
+        if !completed {
+            process.output = format!(
+                "{}\nproject.verify build 成功但缺少 game/dist/index.html",
+                process.output
+            );
+        }
+    }
     let status = if completed { "completed" } else { "failed" };
     let command_id = format!("project.verify.{}", spec.script);
     let updated_at = unix_timestamp();
@@ -703,6 +782,7 @@ where
         script: spec.script,
         expected_command: spec.expected_command,
         package_manager: spec.package_manager,
+        cwd_relative: spec.cwd_relative,
         status: status.to_string(),
         exit_code: process.exit_code,
         timed_out: process.timed_out,

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

@@ -14,16 +14,59 @@ const PROJECT_WRITE_LOCK_UNWRITTEN_GRACE_SECONDS: u64 = 30;
 const PROJECT_WRITE_LOCK_PID_REUSE_TOLERANCE_SECONDS: u64 = 5;
 const PROJECT_WRITE_LOCK_MAX_BYTES: u64 = 4 * 1024;
 
+/// 本进程内真正落盘持有项目写锁的线程登记表。
+///
+/// `.agent/project.lock` 的 `pid` 只能证明“锁由本进程的某条写通道持有”，它分不清
+/// 两种完全不同的局面：
+/// - **同一条调用链再次取锁**：持锁方就是自己，必须放行，否则每次嵌套项目写入都要
+///   白等一个等待预算再报“项目正在被其他写操作占用”；
+/// - **本进程另一条写通道正在写**：项目 revision 侧车、steer 序号、一致快照读、
+///   pending sidecar 复核和恢复安装都靠这把锁串行化，必须照旧等待。
+///
+/// 复用判据因此不能停在 `pid`：只有**当前线程**就是真实持锁线程时才返回 advisory
+/// guard，本进程其余争用继续走有界等待与终态占用。登记按路径进行、按路径注销：
+/// guard 可能被移到别的线程再 Drop（例如写入路径把锁交给阻塞线程池的持有者），
+/// 按线程注销会漏项，让后续的重入判断失真。
+static PROJECT_WRITE_LOCK_THREAD_OWNERS: std::sync::Mutex<Vec<(PathBuf, std::thread::ThreadId)>> =
+    std::sync::Mutex::new(Vec::new());
+
+fn project_write_lock_thread_owners(
+) -> std::sync::MutexGuard<'static, Vec<(PathBuf, std::thread::ThreadId)>> {
+    // 登记表只是复用判据的加速器：中毒时继续用内部值，不能让一次取锁失败升级成
+    // 整个进程再也写不了项目。
+    PROJECT_WRITE_LOCK_THREAD_OWNERS
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn register_project_write_lock_thread_owner(path: &Path) {
+    let mut owners = project_write_lock_thread_owners();
+    if owners.iter().any(|(owner, _)| owner == path) {
+        return;
+    }
+    owners.push((path.to_path_buf(), std::thread::current().id()));
+}
+
+fn unregister_project_write_lock_thread_owner(path: &Path) {
+    project_write_lock_thread_owners().retain(|(owner, _)| owner != path);
+}
+
+/// 当前线程是否就是这条锁路径上真实落盘的持有者（同线程重入）。
+fn project_write_lock_reentered_by_current_thread(path: &Path) -> bool {
+    let thread = std::thread::current().id();
+    project_write_lock_thread_owners()
+        .iter()
+        .any(|(owner, owner_thread)| owner == path && *owner_thread == thread)
+}
+
 #[derive(Debug)]
 pub(crate) struct ProjectWriteLock {
     path: PathBuf,
     content: String,
-    /// In the free-form autonomous lane a single Runtime process may have
-    /// several specialist actions in flight at once.  A file lock is still
-    /// useful across processes, but making same-process contenders fail turns
-    /// ordinary parallel work into a dead run (and can deadlock nested tool
-    /// calls).  Such a contender receives an in-process/advisory guard instead
-    /// of deleting the real holder's lock on drop.
+    /// 两种“本进程持锁但不必自等”的争用会拿到 advisory guard：同一线程重入（同一条
+    /// 调用链再次取锁）和自主游戏构建流水线（它有意让并行专家动作同时在飞）。这两种
+    /// 情况下争用是进程内重叠而不是另一个客户端在改项目，返回的 guard 不拥有
+    /// `.agent/project.lock`，Drop 时也不得删除真实持有者的锁。
     bypassed_same_process: bool,
 }
 
@@ -47,6 +90,7 @@ impl Drop for ProjectWriteLock {
         if self.bypassed_same_process {
             return;
         }
+        unregister_project_write_lock_thread_owner(&self.path);
         if fs::read_to_string(&self.path).is_ok_and(|content| content == self.content) {
             let _ = fs::remove_file(&self.path);
         }
@@ -815,6 +859,7 @@ pub(crate) fn acquire_project_write_lock_failure(
                         path.display()
                     )));
                 }
+                register_project_write_lock_thread_owner(&path);
                 return Ok(ProjectWriteLock {
                     path,
                     content: content.clone(),
@@ -860,14 +905,15 @@ pub(crate) fn acquire_project_write_lock_failure(
                         }
                     }
                 }
-                if crate::agent::autonomous_game_build_root_run_active_at(root)
-                    && project_write_lock_is_owned_by_current_process(&path)
+                if project_write_lock_is_owned_by_current_process(&path)
+                    && (crate::agent::autonomous_game_build_root_run_active_at(root)
+                        || project_write_lock_reentered_by_current_thread(&path))
                 {
-                    // The autonomous game-build lane intentionally permits
-                    // parallel specialist actions.  If the durable lock belongs
-                    // to this very process, contention is an in-process overlap,
-                    // not another application editing the project.  Return an
-                    // advisory guard and leave the real lock untouched.
+                    // 持锁方就是本进程自己时必须区分重入与并发：同一条调用链（同一
+                    // 线程）再次取锁，以及自主流水线有意并行专家动作，返回 advisory
+                    // guard、不自等、不动真实锁；本进程**其它线程**正在写则继续走
+                    // 有界等待，保住 revision 侧车、steer 序号、一致快照读与恢复安装
+                    // 的串行化。
                     return Ok(ProjectWriteLock {
                         path,
                         content: String::new(),