AGC产物迁移npm与Phaser4

新增 npm + Vite + Phaser 4.2.1 游戏工程脚手架

允许 DirectProject 在项目边界内安装依赖并执行构建

让预览、静态检查、投影和试玩导出统一使用 dist 产物

补充 Phaser Skill、技术方案、项目记忆和定向测试

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

@@ -53,6 +53,7 @@
     "focus-trap-react": "^12.0.3",
     "lexical": "^0.47.0",
     "lucide-react": "^0.546.0",
+    "phaser": "^4.2.1",
     "react": "^19.0.0",
     "react-arborist": "^3.16.0",
     "react-colorful": "^5.8.0",

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: agc-web-game-development
-description: Build or modify a playable web game in the current AGC project. Use for gameplay creation, bug fixes, UI or layout changes, responsive behavior, asset integration, controls, scoring, reset flows, and other HTML, CSS, JavaScript, DOM, Canvas, or WebGL work.
+description: Build or modify a playable npm-managed Phaser 4 web game in the current AGC project. Use for gameplay creation, bug fixes, UI or layout changes, responsive behavior, asset integration, controls, scoring, reset flows, and other HTML, CSS, JavaScript, DOM, Canvas, or WebGL work.
 ---
 
 # AGC Web Game Development
 
-Implement the user's actual game request in the current project. Choose DOM, Canvas, WebGL, or a combination based on the game rather than a fixed code template.
+Implement the user's actual game request in the current project as an npm-managed Phaser 4.2.1 game. Use Phaser scenes for gameplay and DOM only for deliberately external UI.
 
 ## Workflow
 
-1. Read the existing `index.html`, `style.css`, and `game.js` before modifying an existing game.
+1. Read the existing package and source files before editing. New projects place `package.json`, `index.html`, `style.css`, and `game.js` under `game/`; existing root packages retain their layout. Run npm in that package directory (for example `npm --prefix game ci` and `npm --prefix game run build`).
-2. Keep the entry self-contained and runnable from the AGC loopback preview. Avoid CDN-only dependencies and network-required runtime assets.
+2. Keep `package.json` and `package-lock.json` authoritative. Import Phaser with `import Phaser from 'phaser'`; do not copy a bundle, add an import map, or use a CDN. Other npm dependencies are allowed when the game needs them.
-3. Build a complete playable loop: visible objective, responsive input, meaningful state changes, success or failure feedback, and a reliable restart path where the game needs one.
+3. Build with the project's npm script before previewing. The playable entry is the package directory's `dist/index.html`; never report an unbuilt bare-module page as playable. Import assets or configure public assets so all runtime media is included in dist; preview and exports cannot read outside it.
-4. Fit the active game scene to desktop and mobile viewports without accidental page scrollbars. Reserve deliberate safe space for HUD elements instead of covering interactive content.
+4. Build a complete playable loop: visible objective, responsive input, meaningful state changes, success or failure feedback, and a reliable restart path where the game needs one.
-5. Reuse registered Taonier art when available through `agc_tools`. Load media defensively and keep gameplay usable when an optional derivative is absent; never relabel a local placeholder as platform art.
+5. Fit the active game scene to desktop and mobile viewports without accidental page scrollbars. Reserve deliberate safe space for HUD elements instead of covering interactive content.
-6. Avoid undefined animation callbacks, duplicate loops, stale event listeners, and state that survives restart unintentionally.
+6. Reuse registered Taonier art when available through `agc_tools`. Load media defensively and keep gameplay usable when an optional derivative is absent; never relabel a local placeholder as platform art.
-7. After a meaningful game change, use the browser playtest Skill and fix issues shown by real evidence before reporting completion.
+7. Let Phaser own the render loop and input dispatch. Avoid duplicate scenes, stale event listeners, and state that survives restart unintentionally.
+8. After a meaningful game change, use the browser playtest Skill and fix issues shown by real evidence before reporting completion.
 
 When implementing a new game loop or a broad gameplay revision, read `references/game-quality-checklist.md`.
 

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Web 游戏实现"
-  short_description: "在当前项目内设计、实现并验证可玩的 HTML、CSS 与 JavaScript 游戏"
+  short_description: "在当前项目内设计、实现并验证 npm 管理的 Phaser 4 游戏"
   default_prompt: "Use $agc-web-game-development to build or modify the current playable web game."

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.10",
+  "version": "2026-08-26.12",
   "skills": [
     {
       "name": "agc-project-structure",
@@ -57,7 +57,7 @@
         "agents/openai.yaml",
         "references/game-quality-checklist.md"
       ],
-      "sha256": "d7748d9ebf4324add0541daf16a2bbec09c4862b85af55bfb369c7f3b99aedff"
+      "sha256": "0649c72dd53e05ad7c87b28def1397c2badf61b0c308091196c40f7c48a8b36a"
     },
     {
       "name": "agc-browser-playtest",

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

@@ -1330,12 +1330,13 @@ fn codex_app_server_turn_start_params(
         "approvalPolicy": approval_policy,
     });
     if workspace_mode.allows_workspace_writes() {
-        // Native project commands stay offline and remain bounded to the
+        // npm install/build must resolve project dependencies. Network access
-        // real game workspace.
+        // is enabled only for DirectProject; writableRoots keeps the file-write
+        // boundary at the real game workspace.
         params["sandboxPolicy"] = serde_json::json!({
             "type": "workspaceWrite",
             "writableRoots": [workspace_path],
-            "networkAccess": false
+            "networkAccess": true
         });
     }
     params
@@ -2119,6 +2120,9 @@ impl CodexAppServerConnection {
         if workspace_mode == CodexAppServerWorkspaceMode::DirectProject && llm.web_search_enabled {
             command.env(DIRECT_TOOLS_MCP_CONTROLLED_WEB_SEARCH_ENV, "1");
         }
+        if workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
+            command.env("npm_config_cache", workspace_path.join(".npm-cache"));
+        }
         command
             .env("CODEX_HOME", &isolated_codex_home)
             .env("HOME", &isolated_os_home)
@@ -4522,7 +4526,7 @@ mod tests {
         );
         assert_eq!(
             turn.pointer("/sandboxPolicy/networkAccess"),
-            Some(&serde_json::json!(false))
+            Some(&serde_json::json!(true))
         );
         let authority_paths = [
             turn.get("cwd"),

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

@@ -10,7 +10,7 @@ const MAX_DIRECT_SYSTEM_PROMPT_CHARS: usize = 16 * 1024;
 const MIN_DIRECT_CLIENT_TURN_ID_CHARS: usize = 6;
 const MAX_DIRECT_CLIENT_TURN_ID_CHARS: usize = 160;
 const DIRECT_TAONIER_IDENTITY_GUIDANCE: &str = "对外身份合同：你是“陶泥儿”，是 Genarrative 的游戏创作助手。用户询问你是谁、你的名称或能力时，以陶泥儿的身份回答；不要把 Codex、ChatGPT、OpenAI、模型、通用 AI 助手或内部执行智能体当作自己的名称或对外身份。Codex app-server 仅是客户端内部执行技术；只有用户明确询问底层实现时才可如实说明，同时仍以陶泥儿自称。";
-const DIRECT_AGC_ENGINEERING_GUIDANCE: &str = "AGC 工程合同（仅说明项目边界，不是流程门槛）：当前 Codex cwd 是用户选择的项目目录（工作区根），源码、素材、音效和其它资源按项目现有结构放置；先按需读取当前 cwd 下适用的 `AGENTS.md`、README 或项目说明，把它们当作项目规范参考。原生文件工具、patch 和命令参数使用 cwd 相对路径，例如 `index.html`、`style.css`、`game.js`、`assets/hero.png`；如果 Codex 原生文件修改不可用，可以按需用客户端 `agc_write_file` 把文本写入项目相对路径。调用 `agc_write_file` 时，content 必须是目标文件的完整原始 UTF-8 正文；不得把 command.exec 的 Exit code、Wall time、Output 包装、终端日志或解释文字一起复制进 content，命令结果只能用于判断，不能当作文件正文。`../`、绝对路径、`.agent/`、`.git/`、密钥文件和 Runtime 控制面属于客户端边界，不能请求扩权或直接改写。DirectProject 提供 Codex 原生文件、搜索、命令、图片查看、Skill、经客户端注入的 `agc_tools` MCP，以及客户端扩展列表中用户已启用的第三方 MCP。用户明确指定第三方 MCP Server 或工具时，先在当前可用工具中查找并直接调用；找不到时如实说明，不得伪造。你可以按需选择这些能力：`agc_write_file` 写入代码、配置、资源依赖清单或说明文件；`agc_generate_image` 生成普通图片、角色图、视觉规范图（icon-spec）、UI 设计图或发布宣传图；`agc_edit_image` 修改已登记图片；`taonier_prepare_game_art` 准备完整游戏美术包及可用的 canonical 切片；`agc_list_registered_assets`、`agc_list_project_files`、`agc_list_account_assets`、`agc_import_account_assets` 用于发现和接入资源依赖；`agc_create_or_derive_resource` 用于视频、角色动画、音效或背景音乐；`agc_browser_playtest` 用于需要时的本地试玩观察；Skill references 按需使用相对路径直接读取。切图、资源依赖、规范图和试玩都只是可选工具提示，不要求调用、固定顺序或特定产物，AGC 不会据此替你拆任务、编排 DAG、做强验收或阻止继续执行；不要等待 Supervisor、harness 或宿主规划器。不要读取或输出凭据、Token、Cookie、auth.json、.env 或宿主私密路径；项目锁、付费提交、幂等键、下载校验和客户端投影由客户端处理。游戏文件真实变化后客户端可登记资源和版本，Codex 不直接保存或伪造项目版本。";
+const DIRECT_AGC_ENGINEERING_GUIDANCE: &str = "AGC 工程合同：当前 cwd 是用户选择的项目目录。新 Web 游戏使用 npm + Vite，Phaser 固定为 4.2.1，在 `game.js` 或模块中使用 `import Phaser from 'phaser'`；可以按需使用其它 npm 依赖，不得复制 Phaser bundle、使用 import map 或 CDN。先读取当前 cwd 下适用的 AGENTS.md、README 或项目说明。源码使用 cwd 相对路径，例如 `index.html`、`style.css`、`game.js`、`package.json`、`package-lock.json`、`assets/hero.png`；依赖安装与构建使用项目自己的 npm scripts，完成后必须从 `dist/index.html` 试玩。 原生文件工具、patch 和命令参数使用 cwd 相对路径，例如 `index.html`、`style.css`、`game.js`、`assets/hero.png`；如果 Codex 原生文件修改不可用，可以按需用客户端 `agc_write_file` 把文本写入项目相对路径。调用 `agc_write_file` 时，content 必须是目标文件的完整原始 UTF-8 正文；不得把 command.exec 的 Exit code、Wall time、Output 包装、终端日志或解释文字一起复制进 content，命令结果只能用于判断，不能当作文件正文。`../`、绝对路径、`.agent/`、`.git/`、密钥文件和 Runtime 控制面属于客户端边界，不能请求扩权或直接改写。DirectProject 提供 Codex 原生文件、搜索、命令、图片查看、Skill、经客户端注入的 `agc_tools` MCP，以及客户端扩展列表中用户已启用的第三方 MCP。用户明确指定第三方 MCP Server 或工具时，先在当前可用工具中查找并直接调用；找不到时如实说明，不得伪造。你可以按需选择这些能力：`agc_write_file` 写入代码、配置、资源依赖清单或说明文件；`agc_generate_image` 生成普通图片、角色图、视觉规范图（icon-spec）、UI 设计图或发布宣传图；`agc_edit_image` 修改已登记图片；`taonier_prepare_game_art` 准备完整游戏美术包及可用的 canonical 切片；`agc_list_registered_assets`、`agc_list_project_files`、`agc_list_account_assets`、`agc_import_account_assets` 用于发现和接入资源依赖；`agc_create_or_derive_resource` 用于视频、角色动画、音效或背景音乐；`agc_browser_playtest` 用于需要时的本地试玩观察；Skill references 按需使用相对路径直接读取。切图、资源依赖、规范图和试玩都只是可选工具提示，不要求调用、固定顺序或特定产物，AGC 不会据此替你拆任务、编排 DAG、做强验收或阻止继续执行；不要等待 Supervisor、harness 或宿主规划器。不要读取或输出凭据、Token、Cookie、auth.json、.env 或宿主私密路径；项目锁、付费提交、幂等键、下载校验和客户端投影由客户端处理。游戏文件真实变化后客户端可登记资源和版本，Codex 不直接保存或伪造项目版本。";
 const DIRECT_CODEX_ART_SPEC_ASSET_PATH: &str = "assets/art-spec.png";
 const DIRECT_CODEX_BACKGROUND_ASSET_PATH: &str = "assets/direct-game-background.png";
 const DIRECT_CODEX_SPRITESHEET_ASSET_PATH: &str = "assets/art-spritesheet.png";
@@ -72,6 +72,21 @@ fn direct_codex_game_outputs(root: &Path) -> Vec<(String, &'static str, &'static
         (entry.to_string(), "game-entry", "text/html"),
         (format!("{prefix}style.css"), "game-style", "text/css"),
         (format!("{prefix}game.js"), "game-script", "text/javascript"),
+        (
+            format!("{prefix}package.json"),
+            "game-package",
+            "application/json",
+        ),
+        (
+            format!("{prefix}package-lock.json"),
+            "game-lockfile",
+            "application/json",
+        ),
+        (
+            format!("{prefix}vite.config.js"),
+            "game-build-config",
+            "text/javascript",
+        ),
     ]
 }
 
@@ -3184,7 +3199,14 @@ fn direct_codex_generated_source() -> GameCreationAppAssetSource {
 
 fn direct_codex_output_fingerprint(root: &Path) -> String {
     let mut hasher = Sha256::new();
-    for (local_path, _, _) in direct_codex_game_outputs(root) {
+    let mut paths: Vec<String> = direct_codex_game_outputs(root)
+        .into_iter()
+        .map(|(p, _, _)| p)
+        .collect();
+    paths.extend(direct_npm_source_paths(root));
+    paths.sort();
+    paths.dedup();
+    for local_path in paths {
         hasher.update(local_path.as_bytes());
         hasher.update([0]);
         let path = root.join(local_path);
@@ -3200,6 +3222,70 @@ fn direct_codex_output_fingerprint(root: &Path) -> String {
     format!("{:x}", hasher.finalize())
 }
 
+fn direct_npm_source_paths(root: &Path) -> Vec<String> {
+    let base = if root.join("package.json").is_file() {
+        root.to_path_buf()
+    } else if root.join("game/package.json").is_file() {
+        root.join("game")
+    } else {
+        return Vec::new();
+    };
+    let mut output = Vec::new();
+    let mut pending = vec![(base, 0usize)];
+    let mut inspected = 0usize;
+    while let Some((directory, depth)) = pending.pop() {
+        if depth > 16 || inspected >= 4096 {
+            break;
+        }
+        let Ok(entries) = fs::read_dir(directory) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            inspected += 1;
+            if inspected > 4096 {
+                break;
+            }
+            let name = entry.file_name().to_string_lossy().to_ascii_lowercase();
+            if name.starts_with('.')
+                || matches!(
+                    name.as_str(),
+                    "node_modules"
+                        | "dist"
+                        | "target"
+                        | "memory"
+                        | "exports"
+                        | "auth.json"
+                        | "credentials.json"
+                        | "game-creator.config.json"
+                        | "game-creator.config.local.json"
+                )
+            {
+                continue;
+            }
+            let Ok(kind) = entry.file_type() else {
+                continue;
+            };
+            let path = entry.path();
+            if kind.is_dir() {
+                pending.push((path, depth + 1));
+            } else if kind.is_file()
+                && matches!(
+                    path.extension().and_then(|e| e.to_str()),
+                    Some("js" | "mjs" | "cjs" | "ts" | "tsx" | "jsx" | "css" | "html" | "json")
+                )
+            {
+                if let Ok(relative) = path.strip_prefix(root) {
+                    if let Some(value) = relative.to_str() {
+                        output.push(value.replace('\\', "/"));
+                    }
+                }
+            }
+        }
+    }
+    output.sort();
+    output
+}
+
 fn direct_browser_evidence_root(root: &Path, attempt: usize) -> Result<std::path::PathBuf, String> {
     let revision = read_game_creator_agent_runtime_project_revision(root)
         .map(|value| value.revision)
@@ -3631,6 +3717,34 @@ fn sync_direct_codex_project_file_projection_at(
         )?;
         registered += 1;
     }
+    for local_path in direct_npm_source_paths(root) {
+        if direct_codex_game_outputs(root)
+            .iter()
+            .any(|(p, _, _)| p == &local_path)
+        {
+            continue;
+        }
+        if root.join(&local_path).is_file() {
+            let media_type = if local_path.ends_with(".css") {
+                "text/css"
+            } else if local_path.ends_with(".json") {
+                "application/json"
+            } else if local_path.ends_with(".html") {
+                "text/html"
+            } else {
+                "text/javascript"
+            };
+            register_local_asset_at(
+                root,
+                &local_path,
+                "game-source",
+                media_type,
+                "direct-codex",
+                direct_codex_generated_source(),
+            )?;
+            registered += 1;
+        }
+    }
     if registered == 0 {
         return Err("Codex 返回后没有可登记的游戏文件".to_string());
     }
@@ -7343,7 +7457,7 @@ mod tests {
         assert_eq!(manifest.versions.len(), 1);
         assert_eq!(manifest.versions[0].version_id, "initial-1");
         assert_eq!(manifest.versions[0].project_revision, 1);
-        assert_eq!(manifest.versions[0].resource_bindings.len(), 10);
+        assert_eq!(manifest.versions[0].resource_bindings.len(), 13);
         for expected_path in DIRECT_CODEX_ART_ASSET_PATHS.into_iter().chain(
             DIRECT_CODEX_SPRITESHEET_SLICE_PATHS
                 .iter()
@@ -7380,7 +7494,7 @@ mod tests {
             .expect("project revision");
         assert_eq!(revision.revision, 2);
         let manifest = read_manifest(&root.path().join(".agent/manifest.json")).expect("manifest");
-        assert_eq!(manifest.assets.len(), 10);
+        assert_eq!(manifest.assets.len(), 13);
         assert_eq!(
             manifest
                 .assets
@@ -7400,7 +7514,7 @@ mod tests {
             manifest.versions[1].created_reason,
             GameIterationVersionCreatedReason::AgentRevision
         );
-        assert_eq!(manifest.versions[1].resource_bindings.len(), 10);
+        assert_eq!(manifest.versions[1].resource_bindings.len(), 13);
 
         let unchanged_fingerprint = direct_codex_output_fingerprint(root.path());
         sync_direct_codex_project_outputs_at(root.path(), Some(&unchanged_fingerprint))
@@ -8284,3 +8398,36 @@ mod tests {
         );
     }
 }
+
+#[cfg(test)]
+mod npm_source_projection_tests {
+    use super::*;
+
+    #[test]
+    fn npm_sources_track_nested_modules_but_ignore_dependencies_and_private_files() {
+        for nested in [false, true] {
+            let root = tempfile::tempdir_in(std::env::temp_dir().canonicalize().unwrap()).unwrap();
+            let source = if nested {
+                root.path().join("game")
+            } else {
+                root.path().to_path_buf()
+            };
+            fs::create_dir_all(source.join("src/scenes")).unwrap();
+            fs::create_dir_all(source.join("node_modules/demo")).unwrap();
+            fs::create_dir_all(source.join(".npm-cache")).unwrap();
+            fs::write(source.join("package.json"), "{}").unwrap();
+            fs::write(source.join("src/scenes/play.ts"), "export const value = 1;").unwrap();
+            fs::write(source.join("node_modules/demo/index.js"), "private dep").unwrap();
+            fs::write(source.join(".npm-cache/auth.json"), "private cache").unwrap();
+            let paths = direct_npm_source_paths(root.path());
+            let prefix = if nested { "game/" } else { "" };
+            assert!(paths.contains(&format!("{prefix}src/scenes/play.ts")));
+            assert!(!paths
+                .iter()
+                .any(|path| path.contains("node_modules") || path.contains(".npm-cache")));
+            let before = direct_codex_output_fingerprint(root.path());
+            fs::write(source.join("src/scenes/play.ts"), "export const value = 2;").unwrap();
+            assert_ne!(direct_codex_output_fingerprint(root.path()), before);
+        }
+    }
+}

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

@@ -78,7 +78,7 @@ pub(crate) use draft_validation::{
     validate_llm_agent_handoffs, validate_llm_game_draft, validate_non_placeholder_game_html,
     validate_playable_game_html, validate_safe_game_html_runtime,
 };
-pub(crate) use draft_writer::write_local_game_draft_at;
+pub(crate) use draft_writer::{ensure_legacy_json_generator_project, write_local_game_draft_at};
 #[allow(unused_imports)]
 pub(crate) use loop_orchestration::{
     emit_agent_progress, game_creator_agent_llm_error_is_mud_points_insufficient,

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

@@ -9,8 +9,8 @@ pub(crate) fn write_local_game_draft_at(
     if prompt.is_empty() {
         return Err("创作想法不能为空".to_string());
     }
+    ensure_legacy_json_generator_project(root)?;
     validate_llm_game_draft(prompt, draft)?;
-    init_local_game_project_at(root, "local-project-draft", "未命名游戏原型")?;
     let checkpoint = create_local_project_checkpoint_at(root)?;
     let timestamp = unix_timestamp();
     let title = draft.title.trim();
@@ -134,3 +134,38 @@ pub(crate) fn write_local_game_draft_at(
         manifest,
     })
 }
+
+pub(crate) fn ensure_legacy_json_generator_project(root: &Path) -> Result<(), String> {
+    if root.join("game/package.json").exists()
+        || root.join("package.json").exists()
+        || !root.join("game/index.html").is_file()
+        || !root.join(".agent/manifest.json").is_file()
+    {
+        return Err("JSON Generator 仅支持已有的单文件 HTML 项目；新建游戏与 npm / Phaser 4 项目请使用 DirectProject 完成依赖安装、构建和试玩".to_string());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod legacy_generator_tests {
+    use super::*;
+
+    #[test]
+    fn legacy_generator_rejects_npm_before_writing() {
+        let root = tempfile::tempdir_in(std::env::temp_dir().canonicalize().unwrap()).unwrap();
+        fs::create_dir_all(root.path().join("game")).unwrap();
+        fs::create_dir_all(root.path().join(".agent")).unwrap();
+        fs::write(root.path().join("game/index.html"), "legacy source").unwrap();
+        fs::write(root.path().join(".agent/manifest.json"), "{}").unwrap();
+        assert!(ensure_legacy_json_generator_project(root.path()).is_ok());
+        fs::write(root.path().join("game/package.json"), "{}").unwrap();
+        assert!(ensure_legacy_json_generator_project(root.path())
+            .unwrap_err()
+            .contains("DirectProject"));
+        assert_eq!(
+            fs::read_to_string(root.path().join("game/index.html")).unwrap(),
+            "legacy source"
+        );
+        assert!(!root.path().join(".agent/spec.md").exists());
+    }
+}

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

@@ -44,6 +44,7 @@ pub(crate) async fn run_game_creator_agent_loop_at(
     project_blackboard: &str,
     progress: Option<&AgentProgressEmitter<'_>>,
 ) -> Result<GameCreatorAgentLoopResult, String> {
+    ensure_legacy_json_generator_project(root)?;
     let spec_path = root.join(".agent/spec.md");
     let findings_path = root.join(".agent/findings.md");
     let run_id = format!("game-generate-draft-{}", unix_millis());

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

@@ -24,6 +24,7 @@ JSON schema:
 }
 
 gameHtml 规则：
+- 此 JSON 协议仅用于已有的单文件 HTML 项目；npm / Phaser 项目必须使用 DirectProject，不能通过 gameHtml 交付 package.json 或模块源码。
 - 必须是单文件 HTML，不能加载远程脚本、远程图片、远程 CSS 或 CDN。
 - 必须包含 canvas、canvas getContext、实际绘制调用、键盘或鼠标输入、requestAnimationFrame 主循环、目标、失败或胜利状态、R 或按钮重开。
 - JavaScript 不要 eval、Function、localStorage、fetch、WebSocket、ServiceWorker。

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

@@ -294,6 +294,7 @@ pub(crate) async fn generate_local_game_draft_at(
     if prompt.is_empty() {
         return Err("创作想法不能为空".to_string());
     }
+    ensure_legacy_json_generator_project(root)?;
 
     init_local_game_project_at(root, "local-project-draft", "未命名游戏原型")?;
     let short_memory = read_optional_text(&root.join("memory/session.md"))?;

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

@@ -1489,14 +1489,12 @@ const DEFAULT_GAME_INDEX_HTML: &str = r#"<!doctype html>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Genarrative Game Draft</title>
-    <style>
-      body { margin: 0; display: grid; min-height: 100vh; place-items: center; background: #101827; color: #d9e7ff; font: 16px system-ui, sans-serif; }
-      main { width: min(720px, calc(100vw - 32px)); }
-    </style>
   </head>
-  <body><main>还没有生成游戏。回到聊天输入创意并确认生成后，这里会写入可试玩原型。</main></body>
+  <body><main id="game"></main><script type="module" src="/game.js"></script></body>
 </html>
 "#;
+const DEFAULT_GAME_STYLE_CSS: &str = "body { margin: 0; display: grid; min-height: 100vh; place-items: center; background: #101827; color: #d9e7ff; font: 16px system-ui, sans-serif; }\nmain { width: min(720px, calc(100vw - 32px)); }\n";
+const DEFAULT_GAME_SCRIPT_JS: &str = "import Phaser from 'phaser';\nimport './style.css';\n\nclass PlaceholderScene extends Phaser.Scene {\n  create() { this.add.text(24, 24, '还没有生成游戏。回到聊天输入创意并确认生成后，这里会写入可试玩原型。'); }\n}\n\nnew Phaser.Game({ type: Phaser.AUTO, width: 720, height: 420, parent: 'game', scene: PlaceholderScene });\n";
 
 const DEFAULT_EDITOR_BASE_URL: &str = "http://127.0.0.1:3000";
 const GAME_CREATOR_CONFIG_FILE_NAME: &str = "game-creator.config.json";

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

@@ -1405,9 +1405,14 @@ fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option<usize> {
         .position(|candidate| candidate == needle)
 }
 
-/// 解析项目游戏根：项目根存在 `index.html` 时使用项目根（新布局），
+/// npm 工程只预览构建结果；单 HTML 工程保留现有入口布局。
-/// 否则回退到旧布局的 `game/` 子目录。
 pub(crate) fn project_game_root(root: &Path) -> PathBuf {
+    if root.join("package.json").is_file() || root.join("dist/index.html").is_file() {
+        return root.join("dist");
+    }
+    if root.join("game/package.json").is_file() || root.join("game/dist/index.html").is_file() {
+        return root.join("game/dist");
+    }
     if root.join("index.html").is_file() {
         root.to_path_buf()
     } else {
@@ -1419,9 +1424,24 @@ pub(crate) fn resolve_preview_path(root: &Path, url_path: &str) -> Result<PathBu
     let path = url_path.split('?').next().unwrap_or("/");
     let decoded = percent_decode_path(path).ok_or_else(|| "预览路径非法".to_string())?;
     let relative = decoded.trim_start_matches('/');
+    if !relative.is_empty()
+        && relative.split('/').any(|part| {
+            part.is_empty()
+                || part == "."
+                || part == ".."
+                || part.contains('\\')
+                || part.chars().any(char::is_control)
+        })
+    {
+        return Err("预览路径非法".to_string());
+    }
     if relative.is_empty() {
         return canonical_preview_path(root, &project_game_root(root).join("index.html"));
     }
+    let game_root = project_game_root(root);
+    if game_root == root.join("dist") || game_root == root.join("game/dist") {
+        return canonical_preview_path(root, &game_root.join(relative));
+    }
 
     let mut file_path = root.to_path_buf();
     let mut parts = relative.split('/');
@@ -1456,6 +1476,43 @@ fn canonical_preview_path(root: &Path, file_path: &Path) -> Result<PathBuf, Stri
         .canonicalize()
         .map_err(|error| format!("预览文件不可用：{}: {error}", file_path.display()))?;
 
+    let relative_requested = file_path
+        .strip_prefix(root)
+        .map_err(|_| "预览路径越过项目目录".to_string())?;
+    let mut checked = root.to_path_buf();
+    for component in relative_requested.components() {
+        if !matches!(component, std::path::Component::Normal(_)) {
+            return Err("预览路径非法".to_string());
+        }
+        if component.as_os_str().to_str().is_some_and(|name| {
+            [
+                ".agent",
+                ".git",
+                ".codex",
+                ".hermes",
+                "node_modules",
+                "memory",
+                "exports",
+                "target",
+            ]
+            .iter()
+            .any(|protected| name.eq_ignore_ascii_case(protected))
+        }) {
+            return Err("预览路径不能访问控制或依赖目录".to_string());
+        }
+        checked.push(component);
+        if fs::symlink_metadata(&checked)
+            .map_err(|error| error.to_string())?
+            .file_type()
+            .is_symlink()
+        {
+            return Err("预览路径不能包含符号链接".to_string());
+        }
+    }
+    if !canonical_file.is_file() {
+        return Err("预览路径必须是文件".to_string());
+    }
+
     // New DirectProject layouts may use the project root itself as the web
     // root.  The old allow-list below only considered `game/` and `assets/`,
     // which made a valid root `index.html` resolve to a 404 even though
@@ -1492,7 +1549,7 @@ fn canonical_preview_path(root: &Path, file_path: &Path) -> Result<PathBuf, Stri
         }
     }
 
-    for segment in ["game", "assets", "ui"] {
+    for segment in ["game", "assets", "ui", "dist"] {
         let allowed_dir = root.join(segment);
         let metadata = match fs::symlink_metadata(&allowed_dir) {
             Ok(metadata) => metadata,
@@ -1586,6 +1643,43 @@ mod tests {
     use super::*;
     use std::fs;
 
+    #[test]
+    fn npm_preview_requires_build_and_prefers_bundled_assets() {
+        let base = PathBuf::from(std::env::var("HOME").unwrap()).join("data/tmp");
+        fs::create_dir_all(&base).unwrap();
+        let root = tempfile::tempdir_in(base).unwrap();
+        fs::write(root.path().join("package.json"), "{}").unwrap();
+        fs::write(root.path().join("index.html"), "source").unwrap();
+        assert!(resolve_preview_path(root.path(), "/").is_err());
+        fs::create_dir_all(root.path().join("dist/assets")).unwrap();
+        fs::create_dir_all(root.path().join("assets")).unwrap();
+        fs::write(root.path().join("dist/index.html"), "<!doctype html>").unwrap();
+        fs::write(root.path().join("dist/assets/main.js"), "bundled").unwrap();
+        fs::write(root.path().join("assets/main.js"), "source").unwrap();
+        fs::write(root.path().join("assets/hero.png"), "image").unwrap();
+        assert_eq!(
+            resolve_preview_path(root.path(), "/assets/main.js").unwrap(),
+            root.path()
+                .join("dist/assets/main.js")
+                .canonicalize()
+                .unwrap()
+        );
+        assert!(resolve_preview_path(root.path(), "/assets/hero.png").is_err());
+        fs::create_dir_all(root.path().join("game")).unwrap();
+        fs::write(root.path().join("game/index.html"), "source").unwrap();
+        assert!(resolve_preview_path(root.path(), "/game/index.html").is_err());
+        assert!(resolve_preview_path(root.path(), "/assets/%2e%2e/index.html").is_err());
+        #[cfg(unix)]
+        {
+            std::os::unix::fs::symlink(
+                root.path().join("index.html"),
+                root.path().join("dist/assets/leak.html"),
+            )
+            .unwrap();
+            assert!(resolve_preview_path(root.path(), "/assets/leak.html").is_err());
+        }
+    }
+
     #[test]
     fn root_layout_serves_root_entry_and_keeps_legacy_paths_available() {
         let root = tempfile::tempdir().expect("create preview root");

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

@@ -4,26 +4,7 @@ pub(crate) fn export_local_project_package_at(
     root: &Path,
 ) -> Result<LocalProjectExportPackageResult, String> {
     validate_project_root(root)?;
-    ensure_project_export_package_dir(root, "game")?;
+    super::verification::validate_project_game_entry(root)?;
-    let game_index_path = resolve_local_project_path(root, "game/index.html")?;
-    if !game_index_path.is_file() {
-        return Err("导出试玩包前需要先生成 game/index.html".to_string());
-    }
-    let game_index_metadata = checked_export_package_metadata(&game_index_path, "game/index.html")?;
-    if !game_index_metadata.is_file() {
-        return Err("导出试玩包前需要先生成 game/index.html".to_string());
-    }
-    prepare_game_creator_private_path_for_read(&game_index_path, false, "游戏入口")?;
-    let game_index = fs::read_to_string(&game_index_path)
-        .map_err(|error| format!("读取游戏入口失败：{}: {error}", game_index_path.display()))?;
-    if game_index.trim().is_empty() {
-        return Err("导出试玩包前 game/index.html 不能为空".to_string());
-    }
-    let lower_game_index = game_index.to_ascii_lowercase();
-    if !lower_game_index.contains("<html") && !lower_game_index.contains("<!doctype html") {
-        return Err("导出试玩包前 game/index.html 必须是 HTML 文档".to_string());
-    }
-    validate_game_html_smoke(&game_index)?;
     ensure_project_export_package_dir(root, "exports")?;
     let readme_path = resolve_local_project_path(root, "exports/README.md")?;
     if !readme_path.is_file() {
@@ -217,8 +198,22 @@ pub(crate) fn collect_project_export_package_files(
     root: &Path,
 ) -> Result<Vec<(String, PathBuf, u64)>, String> {
     let mut files = Vec::new();
-    collect_project_export_package_dir_files(root, "game", &mut files)?;
+    let game_root = crate::preview::project_game_root(root);
-    if resolve_local_project_path(root, "assets")?.exists() {
+    let built = game_root == root.join("dist") || game_root == root.join("game/dist");
+    if built {
+        let relative = relative_project_path(root, &game_root)?;
+        collect_project_export_package_dir_files(root, &relative, &mut files)?;
+        for (name, _, _) in &mut files {
+            *name = format!(
+                "game/{}",
+                name.strip_prefix(&format!("{relative}/"))
+                    .ok_or("构建产物路径非法")?
+            );
+        }
+    } else {
+        collect_project_export_package_dir_files(root, "game", &mut files)?;
+    }
+    if !built && resolve_local_project_path(root, "assets")?.exists() {
         collect_project_export_package_dir_files(root, "assets", &mut files)?;
     }
     let readme_path = resolve_local_project_path(root, "exports/README.md")?;
@@ -312,3 +307,42 @@ pub(crate) fn normalize_export_package_entry_path(relative_path: &str) -> Result
     }
     normalize_relative_path(relative_path)
 }
+
+#[cfg(test)]
+mod npm_export_tests {
+    use super::*;
+
+    #[test]
+    fn npm_package_contains_only_dist_and_publish_readme() {
+        let base = PathBuf::from(std::env::var("HOME").unwrap()).join("data/tmp");
+        fs::create_dir_all(&base).unwrap();
+        let root = tempfile::tempdir_in(base).unwrap();
+        for directory in ["dist/assets", "assets", "exports", "node_modules", "game"] {
+            fs::create_dir_all(root.path().join(directory)).unwrap();
+        }
+        for file in [
+            "package.json",
+            "dist/index.html",
+            "dist/assets/main.js",
+            "assets/hero.png",
+            "exports/README.md",
+            "node_modules/private.js",
+            "game/source.js",
+        ] {
+            fs::write(root.path().join(file), "test").unwrap();
+        }
+        let files = collect_project_export_package_files(root.path()).unwrap();
+        let names = files
+            .iter()
+            .map(|(name, _, _)| name.as_str())
+            .collect::<Vec<_>>();
+        assert_eq!(
+            names,
+            vec![
+                "exports/README.md",
+                "game/assets/main.js",
+                "game/index.html"
+            ]
+        );
+    }
+}

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

@@ -9,6 +9,32 @@ static MANIFEST_LOCK_OPEN_GUARD: OnceLock<Mutex<()>> = OnceLock::new();
 
 pub(crate) const GAME_CREATION_PROJECT_NAME_MAX_CHARS: usize = 80;
 
+const DEFAULT_GAME_PACKAGE_JSON: &str = r#"{
+  "name": "agc-game",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite"
+  },
+  "dependencies": {
+    "phaser": "4.2.1"
+  },
+  "devDependencies": {
+    "vite": "^6.2.0"
+  }
+}
+"#;
+
+const DEFAULT_GAME_VITE_CONFIG: &str = r#"import { defineConfig } from 'vite';
+
+export default defineConfig({
+  root: '.',
+  base: './',
+  build: { outDir: 'dist', emptyOutDir: true },
+});
+"#;
+
 pub(crate) fn normalize_game_creation_project_name(value: &str) -> Result<String, String> {
     let name = value.trim();
     if name.is_empty() {
@@ -445,6 +471,11 @@ pub(crate) fn init_local_game_project_at(
     let name = normalize_game_creation_project_name(name)?;
 
     prepare_game_creator_project_root_for_read(root, true, "本地项目目录")?;
+    let create_npm_scaffold = !manifest_storage_exists(&root.join(".agent/manifest.json"))?
+        && !root.join("index.html").exists()
+        && !root.join("game/index.html").exists()
+        && !root.join("package.json").exists()
+        && !root.join("game/package.json").exists();
     for relative in ["game", "assets", "memory", "memory/agents", "exports"] {
         let path = root.join(relative);
         ensure_game_creator_private_directory_tree(&path, "本地项目目录")?;
@@ -459,6 +490,32 @@ pub(crate) fn init_local_game_project_at(
             "默认游戏入口",
         )?;
     }
+    if create_npm_scaffold {
+        for (relative, content, label) in [
+            (
+                "game/package.json",
+                DEFAULT_GAME_PACKAGE_JSON,
+                "游戏 npm 配置",
+            ),
+            (
+                "game/package-lock.json",
+                include_str!("../../resources/agc-game-package-lock.json"),
+                "游戏 npm 锁文件",
+            ),
+            (
+                "game/vite.config.js",
+                DEFAULT_GAME_VITE_CONFIG,
+                "游戏 Vite 配置",
+            ),
+            ("game/style.css", DEFAULT_GAME_STYLE_CSS, "游戏样式"),
+            ("game/game.js", DEFAULT_GAME_SCRIPT_JS, "游戏入口脚本"),
+        ] {
+            let path = root.join(relative);
+            if !prepare_game_creator_private_path_for_read(&path, false, label)? {
+                crate::write_game_creator_private_file(&path, content.as_bytes(), label)?;
+            }
+        }
+    }
 
     let agent_db_path = root.join(".agent/agent.db");
     if !agent_db_path.exists() {
@@ -1514,3 +1571,41 @@ pub(crate) fn trim_optional_string(value: Option<String>) -> Option<String> {
 mod import_tests;
 #[cfg(test)]
 mod recovery_tests;
+
+#[cfg(test)]
+mod npm_scaffold_tests {
+    use super::*;
+
+    #[test]
+    fn npm_scaffold_uses_package_import_and_preserves_user_changes() {
+        let root = tempfile::tempdir_in(std::env::temp_dir().canonicalize().unwrap()).unwrap();
+        init_local_game_project_at(root.path(), "npm-scaffold", "游戏").unwrap();
+        let package: serde_json::Value =
+            serde_json::from_slice(&fs::read(root.path().join("game/package.json")).unwrap())
+                .unwrap();
+        assert_eq!(package["dependencies"]["phaser"], "4.2.1");
+        assert!(fs::read_to_string(root.path().join("game/game.js"))
+            .unwrap()
+            .contains("import Phaser from 'phaser'"));
+        assert!(root.path().join("game/package-lock.json").is_file());
+        fs::write(root.path().join("game/game.js"), "user source").unwrap();
+        init_local_game_project_at(root.path(), "npm-scaffold", "游戏").unwrap();
+        assert_eq!(
+            fs::read_to_string(root.path().join("game/game.js")).unwrap(),
+            "user source"
+        );
+    }
+
+    #[test]
+    fn npm_scaffold_does_not_migrate_an_existing_html_project() {
+        let root = tempfile::tempdir_in(std::env::temp_dir().canonicalize().unwrap()).unwrap();
+        fs::create_dir(root.path().join("game")).unwrap();
+        fs::write(root.path().join("game/index.html"), "existing html").unwrap();
+        init_local_game_project_at(root.path(), "existing-html", "已有游戏").unwrap();
+        assert!(!root.path().join("game/package.json").exists());
+        assert_eq!(
+            fs::read_to_string(root.path().join("game/index.html")).unwrap(),
+            "existing html"
+        );
+    }
+}

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

@@ -14,16 +14,12 @@ pub(crate) fn run_limited_local_command_at(
         return Err("项目目录必须是绝对路径".to_string());
     }
 
-    let game_index_path = root.join("game/index.html");
+    let (game_index_path, html) = validate_project_game_entry(root)?;
-    prepare_game_creator_private_path_for_read(&game_index_path, false, "游戏入口")?;
+    let output = format!(
-    let html = fs::read_to_string(&game_index_path)
+        "通过：{}，{} 字节",
-        .map_err(|error| format!("读取游戏入口失败：{}: {error}", game_index_path.display()))?;
+        relative_project_path(root, &game_index_path)?,
-    if !html.contains("<html") && !html.contains("<!doctype html") {
+        html.len()
-        return Err("游戏入口不是 HTML 文档".to_string());
+    );
-    }
-    validate_game_html_smoke(&html)?;
-
-    let output = format!("通过：game/index.html，{} 字节", html.len());
     let log_path = root.join(".agent/logs/command.log");
     let updated_at = unix_timestamp();
     let line = format!("{updated_at} command.run_limited {command_id}: {output}\n");
@@ -49,6 +45,59 @@ pub(crate) fn run_limited_local_command_at(
     })
 }
 
+pub(crate) fn validate_project_game_entry(root: &Path) -> Result<(PathBuf, String), String> {
+    let game_root = crate::preview::project_game_root(root);
+    let index = crate::preview::resolve_preview_path(root, "/")?;
+    prepare_game_creator_private_path_for_read(&index, false, "游戏入口")?;
+    let html = fs::read_to_string(&index).map_err(|error| format!("读取游戏入口失败：{error}"))?;
+    let lower = html.to_ascii_lowercase();
+    if !lower.contains("<html") && !lower.contains("<!doctype html") {
+        return Err("游戏入口不是 HTML 文档".to_string());
+    }
+    if game_root == root.join("dist") || game_root == root.join("game/dist") {
+        validate_built_game_references(root, &html)?;
+    } else {
+        validate_game_html_smoke(&html)?;
+    }
+    Ok((index, html))
+}
+
+fn validate_built_game_references(root: &Path, html: &str) -> Result<(), String> {
+    let tags = regex::Regex::new(r"(?is)<(?:script|link|img|audio|video|source)\b[^>]*>").unwrap();
+    let attributes =
+        regex::Regex::new(r#"(?is)\s+([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))"#)
+            .unwrap();
+    for tag in tags.find_iter(html) {
+        for attribute in attributes.captures_iter(tag.as_str()) {
+            let name = attribute.get(1).unwrap().as_str();
+            if !name.eq_ignore_ascii_case("src") && !name.eq_ignore_ascii_case("href") {
+                continue;
+            }
+            let value = attribute
+                .get(2)
+                .or_else(|| attribute.get(3))
+                .or_else(|| attribute.get(4))
+                .unwrap()
+                .as_str();
+            if value.is_empty()
+                || value.starts_with('#')
+                || value.starts_with("//")
+                || value.contains(':')
+            {
+                continue;
+            }
+            let path = value.split(['?', '#']).next().unwrap_or(value);
+            let path = path.strip_prefix("./").unwrap_or(path);
+            crate::preview::resolve_preview_path(
+                root,
+                &format!("/{}", path.trim_start_matches('/')),
+            )
+            .map_err(|error| format!("构建入口引用不可用：{value}: {error}"))?;
+        }
+    }
+    Ok(())
+}
+
 pub(crate) const PROJECT_VERIFICATION_OUTPUT_MAX_BYTES: usize = 24 * 1024;
 const PROJECT_VERIFICATION_PACKAGE_MAX_BYTES: u64 = 512 * 1024;
 const PROJECT_VERIFICATION_MIN_TIMEOUT_SECONDS: u64 = 1;
@@ -840,3 +889,25 @@ pub(crate) fn enforce_project_auto_permission_policy(
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod npm_build_tests {
+    use super::*;
+
+    #[test]
+    fn built_smoke_checks_module_files_without_inline_canvas() {
+        let base = PathBuf::from(std::env::var("HOME").unwrap()).join("data/tmp");
+        fs::create_dir_all(&base).unwrap();
+        let root = tempfile::tempdir_in(base).unwrap();
+        fs::create_dir_all(root.path().join("dist/assets")).unwrap();
+        fs::write(root.path().join("package.json"), "{}").unwrap();
+        let html = r#"<!doctype html><html><script type="module" src="./assets/main.js"></script><link href="./assets/main.css" rel="stylesheet"></html>"#;
+        fs::write(root.path().join("dist/index.html"), html).unwrap();
+        assert!(validate_built_game_references(root.path(), html).is_err());
+        fs::write(root.path().join("dist/assets/main.js"), "export {};").unwrap();
+        fs::write(root.path().join("dist/assets/main.css"), "body{}").unwrap();
+        assert!(validate_built_game_references(root.path(), html).is_ok());
+        let lazy_html = r#"<!doctype html><html><img data-src="later.png" data-href="missing.png" alt="src='not-a-reference.png'" src="./assets/main.js"></html>"#;
+        assert!(validate_built_game_references(root.path(), lazy_html).is_ok());
+    }
+}

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

@@ -51,9 +51,11 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 
 ## AGC DirectProject 与 UI workflow
 
+- 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建，已有单 HTML/Godot 不自动迁移。
+
 - 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。
 - DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP，并在启动时额外读取客户端扩展仓库中已启用的第三方 MCP 独立项。第三方 STDIO/HTTP 配置只写入本次隔离 `CODEX_HOME`，单项非 required，启停、重命名和内容指纹进入 app-server pool identity；完整 Plugin Runtime、hooks/apps 和单文件脚本手动指定入口仍关闭。Skill 正文与 references 由 Codex 原生按需读取；`agc_tools` 负责标准美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`；付费资源调用仍由客户端绑定回合、幂等账本、请求上限和投影权威。
-- DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在真实 `game/` cwd 与 `workspaceWrite(writableRoots=[game])` 内可用；原生命令网络保持关闭。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。
+- DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在用户项目 cwd 与 `workspaceWrite(writableRoots=[project])` 内可用；原生命令允许联网以支持 npm 安装，npm 缓存位于项目内 `.npm-cache/`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。
 - `ui-prototype`（设计图片）与 UI 编辑器 `UI` JSON 是不同资源。白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`，由 provider-backed 识别、合并和组件绑定持久化 State/revision，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 投影到 manifest。Provider 缺失、请求失败、工具缺失、结果不匹配或仍有待审节点时保留真实阶段并返回 blocker，不得用 deterministic seed 伪造完成。
 - UI workflow 的资源桥接与 Runtime 边界以 `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 和 AGC 实施计划的 2026-08-24 覆盖段为准；只生成图片、登记空 JSON 或进入普通图片画布都不构成 workflow 完成。
 

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

@@ -1,5 +1,13 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-09-08 Web 游戏 npm 与 Phaser 4 产物合同
+
+新建 Web 游戏使用 npm 工程：默认 `game/package.json` 声明 Phaser 4.2.1 和 Vite 构建工具，源码使用 `import Phaser from 'phaser'`，`package-lock.json` 由 npm 维护。默认脚手架文件位于 `game/`，包含 `index.html`、`game.js`、`style.css`、`vite.config.js` 和 npm 配置/锁文件；已有根目录 npm 工程沿用原根，可按需求拆分模块并添加任意其它 npm 依赖，不设置包名白名单。客户端不手工分发 Phaser bundle，不用 import map 模拟 package 导入。
+
+Agent 在包含 `package.json` 的目录执行 `npm ci`（依赖变更使用 `npm install`）和 `npm run build`；默认可从工作区根执行 `npm --prefix game ci` 与 `npm --prefix game run build`。DirectProject 保持 workspace-write 目录边界并开放网络，以支持 npm 依赖解析和安装；凭据仍由客户端代理持有，不进入项目或原生命令环境。其它执行模式维持现有权限。新游戏完成后执行 `npm run build` 并用真实浏览器试玩；依赖安装与构建失败必须反馈真实错误，不能回退成未解析裸模块导入的静态页面。
+
+npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.html`，静态 smoke 校验构建入口及本地文件引用，实际可玩性由浏览器验证。预览服务与导出读取该构建目录，所有运行素材必须由构建纳入 dist；npm 预览不回退读取源码或项目素材目录，保证试玩与导出一致。源码投影包含 package、锁文件、配置和真实游戏源码，排除 `node_modules/`、`dist/`、控制文件与凭据；npm 试玩包将 dist 文件映射到 `game/` 并附带发布说明，不包含源码依赖安装目录。现有单 HTML 项目不自动迁移，Godot 项目保持原合同。旧 JSON Generator 仅接受已初始化的单 HTML 项目，npm 项目或新建请求在调用 LLM 前明确拒绝并引导使用 DirectProject，避免静态草案伪装为 npm 构建产物。本节覆盖下文仅适用于旧单 HTML 产物的 Canvas API、手写动画循环和禁止外部本地脚本要求。
+
 ## 2026-09-02 项目名称显示与自动提炼
 
 - `.agent/manifest.json` 的 `name` 仍是本地项目显示名唯一事实源；项目组页行尾更多菜单提供行内重命名，保存必须走 Tauri 受控命令、项目写锁、manifest 写锁与既有 ACL/权限校验。重命名只更新 manifest，不改变项目目录、`projectId`、项目类型、任务、资源、版本或远端同步状态；保存成功后当前项目上下文、窗口标题和最近项目检查结果必须回读新 manifest 并保持一致。

package-lock.json

@@ -110,6 +110,7 @@
         "focus-trap-react": "^12.0.3",
         "lexical": "^0.47.0",
         "lucide-react": "^0.546.0",
+        "phaser": "^4.2.1",
         "react": "^19.0.0",
         "react-arborist": "^3.16.0",
         "react-colorful": "^5.8.0",
@@ -11570,7 +11571,6 @@
       "version": "5.0.4",
       "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
       "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/events-universal": {
@@ -17706,6 +17706,15 @@
         "node": "*"
       }
     },
+    "node_modules/phaser": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/phaser/-/phaser-4.2.1.tgz",
+      "integrity": "sha512-WUNwCPJpdjvZiuT6SgCfYVW8Qw/3j0jJ4ws7P2QkhFLFu74sbGuyHJcbFueGkY/AYO4Pi47bNQXn1OCJeLX//w==",
+      "license": "MIT",
+      "dependencies": {
+        "eventemitter3": "^5.0.4"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -26309,6 +26318,7 @@
         "focus-trap-react": "^12.0.3",
         "lexical": "^0.47.0",
         "lucide-react": "^0.546.0",
+        "phaser": "^4.2.1",
         "react": "^19.0.0",
         "react-arborist": "^3.16.0",
         "react-colorful": "^5.8.0",
@@ -30478,8 +30488,7 @@
     "eventemitter3": {
       "version": "5.0.4",
       "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
-      "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
+      "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="
-      "dev": true
     },
     "events-universal": {
       "version": "1.0.1",
@@ -34500,6 +34509,14 @@
       "integrity": "sha512-Dp6zGqpTdETdR63lehJYPeIOqpiNBNtc7BpWSLrOje7UaIsE5aY92r/AunQA7rsXvet3lrJ3JnZX29UPTKXyKQ==",
       "dev": true
     },
+    "phaser": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/phaser/-/phaser-4.2.1.tgz",
+      "integrity": "sha512-WUNwCPJpdjvZiuT6SgCfYVW8Qw/3j0jJ4ws7P2QkhFLFu74sbGuyHJcbFueGkY/AYO4Pi47bNQXn1OCJeLX//w==",
+      "requires": {
+        "eventemitter3": "^5.0.4"
+      }
+    },
     "picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",