Merge remote-tracking branch 'origin/master' into fix/typecheck-test

apps/ai-game-creator-shell/src-tauri/prompts/runtime/texts/direct.json

@@ -17,8 +17,14 @@
   "browser.status": "整体 passed={}",
   "browser.notStarted": "本次未启动 Chromium",
   "browser.evidence": "[AGC 浏览器事实证据]\nattempt={attempt}; completionError={completion_status}; browser={browser_status}; codeFingerprintChanged={output_changed}\n{}\n诊断与平台素材运行时观察：{}\n交互探针：{}\n客户端已保存结构化证据；它是事实输入，不代表 Codex 已阅读截图或已经完成修复。当前 cwd 是项目根目录；按需读取实际文件，并自行决定是否修改、再次试玩或直接回复。AGC 只负责启动浏览器、采集证据和执行项目边界，Codex 负责解释结果。",
-  "browser.noFailureDetails": "无额外硬失败详情",
-  "browser.noVisibleControls": "未找到可执行的可见控件",
+  "browser.noFailureDetails": "无额外视觉检查失败详情",
+  "browser.noVisibleControls": "无建议性交互探针记录",
+  "browser.gameplayNotRun": "玩法检查：未执行（visual 仅提供视觉证据）。",
+  "browser.gameplayMissing": "固定场景玩法结果缺失，不能确认通过。",
+  "browser.gameplayNoDiagnostic": "无诊断记录",
+  "browser.gameplayNoUnmetAssertion": "无",
+  "browser.gameplayViewport": "{viewport}: gameplayPassed={passed}；首条玩法诊断：{diagnostic}；首个未通过断言：{assertion}",
+  "browser.gameplayEvidence": "[固定场景玩法证据]\n{}\n断言 passed=false 表示未通过，也可能因前序阻断而未执行；修复以具体诊断为准，不把所有未通过项视为独立故障。固定场景通过不代表完整关卡已验证；reportPath 仅为宿主证据引用，无需读取私有报告。",
   "system.role": "你是陶泥儿，是 Genarrative 面向用户的游戏创作助手，负责当前任务的执行。先理解用户意图：普通对话直接回答，项目请求按需要检查、修改、运行和验证，并用简洁中文报告真实结果。",
   "system.workspaceBoundary": "工作区边界：只在当前项目目录内工作；不要读取或输出凭据、Token、Cookie、auth.json、.env 或宿主私密路径。遇到阻断必须说明具体原因、文件和下一步，不要声称未验证的成功。",
   "system.toolAuthorization": "AGC 工具授权：agc_tools 使用当前登录会话。工具返回 401/403 时，报告登录或权限状态异常并停止，交由用户处理登录和权限。",

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-browser-playtest/references/browser-evidence-contract.md

@@ -10,6 +10,8 @@ Canvas/WebGL probes can show whether registered image sources entered a core ren
 
 `mode=visual` captures desktop/mobile screenshots, loading, layout and diagnostics without clicking gameplay controls. It does not prove that the game loop works. `mode=gameplay` uses the fixed approved scenario (`generic-v1` by default, or the existing `tetris-v1` / `lane-defense-v1` contract), not an agent-written autopilot. It exercises the scenario independently in desktop and mobile viewports and requires both results. The receipt declares `gameplayViewports` separately from `visualViewports`. Older reports with only a desktop `playtest` result do not prove mobile gameplay. These bounded scenarios do not establish completion of an arbitrary long level.
 
+Use each viewport's `gameplayResults` to diagnose failures: start with its first `diagnostics` entry, then inspect `assertions` and the recorded initial/final phase, sequence and level. An assertion with `passed=false` may not have run because an earlier step blocked; do not treat every unmet assertion as an independent defect. Missing viewport evidence is not a pass. In visual mode, `gameplayResults` is empty because gameplay was not run. `reportPath` is a private host evidence reference; use the returned diagnostics instead of trying to read that report.
+
 For `generic-v1`, expose exactly one `script#playable-web-game-state[type="application/json"]` whose JSON is a projection of actual game state:
 
 ```json

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.35",
+  "version": "2026-08-26.37",
   "skills": [
     {
       "name": "agc-unity-editor",
@@ -140,7 +140,7 @@
         "references/browser-evidence-contract.md",
         "references/runner-physics.mjs"
       ],
-      "sha256": "e0e7bdca529e068ce2974a5e312a267108ab5acb20e8f9d7c0c22d049d90b796"
+      "sha256": "6800059c4e7bae70b0b42ec47175fc85e38d789e1759dca5df2067f715dc0657"
     },
     {
       "name": "agc-client-projection",

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

@@ -30,6 +30,8 @@ mod direct_runtime;
 mod direct_tool_bridge;
 mod direct_tools_mcp;
 mod direct_validation;
+#[cfg(test)]
+pub(crate) use direct_validation::browser_tool_result;
 mod generation;
 pub(crate) mod json_sidecar;
 pub(crate) mod redaction;

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

@@ -94,11 +94,14 @@ impl Drop for ActiveClaudeCodeTurnGuard {
     }
 }
 
-struct ExternalMcpStopGuard;
+struct ExternalMcpStopGuard {
+    root: PathBuf,
+    token: String,
+}
 
 impl Drop for ExternalMcpStopGuard {
     fn drop(&mut self) {
-        stop_external_mcp_loopback();
+        stop_external_mcp_loopback_for_root(&self.root, &self.token);
     }
 }
 
@@ -960,9 +963,13 @@ pub(crate) async fn direct_game_creator_claude_code_chat_at(
     observer: Option<&mut (dyn FnMut(TurnObservation) + Send)>,
 ) -> Result<String, String> {
     direct_turn_trace("claude-executor-enter");
-    let (mcp_url, mcp_token) = start_external_mcp_loopback(root, llm.web_search_enabled).await?;
+    let (mcp_url, mcp_token) =
+        start_external_mcp_loopback_for_direct_turn(root, llm.web_search_enabled).await?;
     direct_turn_trace("claude-mcp-loopback-ready");
-    let _mcp_guard = ExternalMcpStopGuard;
+    let _mcp_guard = ExternalMcpStopGuard {
+        root: root.to_path_buf(),
+        token: mcp_token.clone(),
+    };
     let home = crate::project::resolve_local_project_path(root, ".agent/runtime/claude-code/home")?;
     std::fs::create_dir_all(&home)
         .map_err(|error| format!("创建 cc Direct 隔离目录失败：{error}"))?;

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

@@ -4236,8 +4236,9 @@ pub(crate) async fn start_direct_tool_bridge(
 pub(crate) async fn start_external_client_tool_bridge(
     root: &Path,
     controlled_web_search: bool,
+    direct_turn_execution: bool,
 ) -> Result<DirectToolBridge, String> {
-    start_tool_bridge_for_source(root, controlled_web_search, false).await
+    start_tool_bridge_for_source(root, controlled_web_search, direct_turn_execution).await
 }
 
 async fn start_tool_bridge_for_source(
@@ -4421,6 +4422,115 @@ pub(super) fn drain_analytics_test_writer(
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn browser_gameplay_results_reach_model_with_matching_viewports_and_screenshots() {
+        for passed in [false, true] {
+            let temp = tempfile::tempdir().unwrap();
+            let evidence = if passed {
+                super::super::direct_validation::tests::browser_evidence_fixture(temp.path())
+            } else {
+                super::super::direct_validation::tests::failed_browser_evidence_fixture(temp.path())
+            };
+            for viewport in &evidence.viewport_results {
+                image::RgbaImage::new(2, 2)
+                    .save(&viewport.screenshot_path)
+                    .unwrap();
+            }
+            let receipt = super::super::direct_validation::browser_tool_result(
+                temp.path(),
+                &evidence,
+                Some(crate::browser::BrowserPlaytestScenario::GenericV1),
+                1,
+            );
+            assert!(evidence.viewport_results.iter().all(|result| result.passed));
+            assert_eq!(receipt["passed"], passed);
+            let outcome = bridge_validation_result(
+                temp.path(),
+                Ok(receipt.clone()),
+                |report, screenshots| BrowserPlaytestError::PlaytestNotPassed {
+                    report,
+                    screenshots,
+                },
+            )
+            .map_err(|failure| {
+                let error = ToolCallError::from(&failure);
+                assert_eq!(error.error["PlaytestNotPassed"]["report"], receipt);
+                assert!(error.error["PlaytestNotPassed"]
+                    .get("screenshots")
+                    .is_none());
+                error
+            });
+            let state = direct_tool_bridge_state(temp.path().to_path_buf());
+            let response =
+                compose_direct_tool_outcome(&state, "agc_browser_playtest", "{}", false, outcome);
+            assert_eq!(response["isError"], !passed);
+            let text = response["content"][0]["text"].as_str().unwrap();
+            let model_receipt: Value =
+                serde_json::from_str(&text[text.find('{').unwrap()..]).unwrap();
+            assert_eq!(model_receipt, receipt);
+            assert_eq!(
+                response["content"]
+                    .as_array()
+                    .unwrap()
+                    .iter()
+                    .filter(|block| block["type"] == "image")
+                    .count(),
+                2
+            );
+            let summary = model_receipt["summary"].as_str().unwrap();
+            for (index, entry) in evidence.viewport_playtests.iter().enumerate() {
+                let report = &model_receipt["gameplayResults"][index];
+                assert_eq!(
+                    report["viewport"],
+                    serde_json::to_value(entry.viewport).unwrap()
+                );
+                assert_eq!(report["passed"], entry.result.passed);
+                assert_eq!(
+                    report["assertions"],
+                    serde_json::to_value(&entry.result.assertions).unwrap()
+                );
+                assert_eq!(report["finalPhase"], "ready");
+                assert_eq!(
+                    report["finalSequence"],
+                    entry.result.final_sequence.unwrap()
+                );
+                let viewport = report["viewport"].as_str().unwrap();
+                let line = summary
+                    .lines()
+                    .find(|line| line.starts_with(&format!("{viewport}: gameplayPassed=")))
+                    .unwrap();
+                assert!(line.starts_with(&format!(
+                    "{viewport}: gameplayPassed={}",
+                    entry.result.passed
+                )));
+                if let Some(reason) = entry.result.diagnostics.first() {
+                    assert_eq!(report["diagnostics"][0], reason.as_str());
+                    assert!(line.contains(reason));
+                }
+                if let Some(assertion) = entry
+                    .result
+                    .assertions
+                    .iter()
+                    .find(|assertion| !assertion.passed)
+                {
+                    assert!(line.contains(&assertion.name));
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn external_client_bridge_can_be_enabled_for_a_direct_turn() {
+        let temporary = tempfile::tempdir().unwrap();
+        init_local_game_project_at(temporary.path(), "external-direct-turn", "外部直连回合")
+            .unwrap();
+        let bridge = start_external_client_tool_bridge(temporary.path(), false, true)
+            .await
+            .expect("direct Claude bridge");
+        assert!(bridge.state.direct_turn_execution);
+        drop(bridge);
+    }
+
     #[tokio::test]
     async fn host_cancellation_releases_queued_image_without_a_new_post() {
         use std::sync::atomic::{AtomicBool, Ordering};

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

@@ -35,12 +35,16 @@ const EXTERNAL_MCP_RESPONSE_SUMMARY_MAX_CHARS: usize = 240;
 const EXTERNAL_MCP_JOURNAL_MAX_BYTES: u64 = 8 * 1024 * 1024;
 const EXTERNAL_MCP_JOURNAL_RELATIVE_PATH: &str = ".agent/conversations/codex-responses.jsonl";
 static EXTERNAL_MCP_JOURNAL_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-static EXTERNAL_MCP_SERVER: OnceLock<Mutex<Option<ExternalMcpServer>>> = OnceLock::new();
+static EXTERNAL_MCP_SERVER: OnceLock<
+    Mutex<std::collections::BTreeMap<PathBuf, ExternalMcpServer>>,
+> = OnceLock::new();
 tokio::task_local! {
     static EXTERNAL_MCP_BRIDGE_URL: String;
 }
 
 pub(crate) struct ExternalMcpServer {
+    token: String,
+    _direct_turn_guard: Option<super::direct_tool_bridge::DirectToolBridgeTurnGuard>,
     _bridge: super::direct_tool_bridge::DirectToolBridge,
     task: tokio::task::JoinHandle<()>,
 }
@@ -1759,6 +1763,21 @@ async fn handle_external_mcp_http_request(
 pub(crate) async fn start_external_mcp_loopback(
     root: &Path,
     controlled_web_search: bool,
+) -> Result<(String, String), String> {
+    start_external_mcp_loopback_with_mode(root, controlled_web_search, false).await
+}
+
+pub(crate) async fn start_external_mcp_loopback_for_direct_turn(
+    root: &Path,
+    controlled_web_search: bool,
+) -> Result<(String, String), String> {
+    start_external_mcp_loopback_with_mode(root, controlled_web_search, true).await
+}
+
+async fn start_external_mcp_loopback_with_mode(
+    root: &Path,
+    controlled_web_search: bool,
+    direct_turn_execution: bool,
 ) -> Result<(String, String), String> {
     let root = validate_direct_tools_project_root(root)?;
     let session = current_platform_session()
@@ -1771,12 +1790,20 @@ pub(crate) async fn start_external_mcp_loopback(
     let address = listener
         .local_addr()
         .map_err(|error| format!("读取客户端 MCP 地址失败：{error}"))?;
-    let bridge =
-        super::direct_tool_bridge::start_external_client_tool_bridge(&root, controlled_web_search)
-            .await?;
+    let bridge = super::direct_tool_bridge::start_external_client_tool_bridge(
+        &root,
+        controlled_web_search,
+        direct_turn_execution,
+    )
+    .await?;
+    let direct_turn_guard = if direct_turn_execution {
+        Some(bridge.begin_user_turn()?)
+    } else {
+        None
+    };
     let state = ExternalMcpHttpState {
         bridge_url: bridge.url().to_string(),
-        root,
+        root: root.clone(),
         token: token.clone(),
         session_user_id: session.user_id,
         session_identity_generation: session.identity_generation,
@@ -1790,24 +1817,40 @@ pub(crate) async fn start_external_mcp_loopback(
         let _ = axum::serve(listener, app).await;
     });
     let url = format!("http://127.0.0.1:{}{route}", address.port());
-    let registry = EXTERNAL_MCP_SERVER.get_or_init(|| Mutex::new(None));
+    let registry =
+        EXTERNAL_MCP_SERVER.get_or_init(|| Mutex::new(std::collections::BTreeMap::new()));
     let mut guard = registry
         .lock()
         .map_err(|_| "客户端 MCP 服务注册表不可用".to_string())?;
-    if let Some(previous) = guard.take() {
-        drop(previous);
-    }
-    *guard = Some(ExternalMcpServer {
-        _bridge: bridge,
-        task,
-    });
+    guard.insert(
+        root,
+        ExternalMcpServer {
+            token: token.clone(),
+            _direct_turn_guard: direct_turn_guard,
+            _bridge: bridge,
+            task,
+        },
+    );
     Ok((url, token))
 }
 
 pub(crate) fn stop_external_mcp_loopback() {
     if let Some(registry) = EXTERNAL_MCP_SERVER.get() {
         if let Ok(mut guard) = registry.lock() {
-            guard.take();
+            guard.clear();
+        }
+    }
+}
+
+pub(crate) fn stop_external_mcp_loopback_for_root(root: &Path, token: &str) {
+    let Ok(root) = root.canonicalize() else {
+        return;
+    };
+    if let Some(registry) = EXTERNAL_MCP_SERVER.get() {
+        if let Ok(mut guard) = registry.lock() {
+            if guard.get(&root).is_some_and(|server| server.token == token) {
+                guard.remove(&root);
+            }
         }
     }
 }
@@ -2180,10 +2223,13 @@ mod tests {
         .unwrap();
         std::fs::create_dir(project.path().join(".agent")).unwrap();
         std::fs::write(project.path().join(".agent/manifest.json"), "{}").unwrap();
-        let bridge =
-            super::super::direct_tool_bridge::start_direct_tool_bridge(project.path(), false)
-                .await
-                .unwrap();
+        let bridge = super::super::direct_tool_bridge::start_external_client_tool_bridge(
+            project.path(),
+            false,
+            false,
+        )
+        .await
+        .unwrap();
         for enabled in [false, true, false, true] {
             crate::builtin_plugins::set_enabled(
                 crate::builtin_plugins::AGC_GODOT_EDITOR_PLUGIN_ID,
@@ -2281,10 +2327,13 @@ mod tests {
         let project = crate::tests::canonical_test_tempdir("builtin-editor-mcp-");
         std::fs::create_dir_all(project.path().join(".agent")).unwrap();
         std::fs::write(project.path().join(".agent/manifest.json"), "{}").unwrap();
-        let bridge =
-            super::super::direct_tool_bridge::start_direct_tool_bridge(project.path(), false)
-                .await
-                .unwrap();
+        let bridge = super::super::direct_tool_bridge::start_external_client_tool_bridge(
+            project.path(),
+            false,
+            false,
+        )
+        .await
+        .unwrap();
         for (cocos_enabled, unity_enabled) in
             [(false, false), (true, false), (false, true), (true, true)]
         {
@@ -2419,10 +2468,13 @@ mod tests {
         let project = crate::tests::canonical_test_tempdir("builtin-mcp-project-");
         std::fs::create_dir_all(project.path().join(".agent")).unwrap();
         std::fs::write(project.path().join(".agent/manifest.json"), "{}").unwrap();
-        let bridge =
-            super::super::direct_tool_bridge::start_direct_tool_bridge(project.path(), false)
-                .await
-                .unwrap();
+        let bridge = super::super::direct_tool_bridge::start_external_client_tool_bridge(
+            project.path(),
+            false,
+            false,
+        )
+        .await
+        .unwrap();
         for enabled in [false, true, false, true] {
             crate::builtin_plugins::set_enabled(
                 crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID,

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

@@ -395,6 +395,137 @@ async fn finish_async(
         .map_err(|_| "验证回执任务退出".to_string())?
 }
 
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct GameplayViewportEvidence {
+    viewport: crate::browser::BrowserValidationViewport,
+    passed: bool,
+    diagnostics: Vec<String>,
+    assertions: Vec<crate::browser::BrowserPlaytestAssertion>,
+    initial_phase: Option<crate::browser::BrowserPlaytestPhase>,
+    initial_sequence: Option<u64>,
+    initial_level: Option<u64>,
+    final_phase: Option<crate::browser::BrowserPlaytestPhase>,
+    final_sequence: Option<u64>,
+    final_level: Option<u64>,
+}
+
+/// 只投影模型修复所需的玩法事实；完整报告继续留在宿主私有目录。
+pub(crate) fn browser_tool_result(
+    root: &Path,
+    evidence: &crate::browser::BrowserValidationResult,
+    scenario: Option<crate::browser::BrowserPlaytestScenario>,
+    sequence: usize,
+) -> Value {
+    use crate::browser::BrowserValidationViewport::{Desktop, Mobile};
+
+    let gameplay_results = if scenario.is_some() {
+        [Desktop, Mobile]
+            .into_iter()
+            .map(|viewport| {
+                let result = evidence
+                    .viewport_playtests
+                    .iter()
+                    .find(|entry| entry.viewport == viewport)
+                    .map(|entry| &entry.result);
+                GameplayViewportEvidence {
+                    viewport,
+                    passed: result.is_some_and(|result| result.passed),
+                    diagnostics: result
+                        .map(|result| {
+                            result
+                                .diagnostics
+                                .iter()
+                                .take(4)
+                                .map(|message| truncate_agent_runtime_text(message, 511))
+                                .collect()
+                        })
+                        .unwrap_or_else(|| {
+                            vec![prompt_text!("direct.browser.gameplayMissing").into()]
+                        }),
+                    assertions: result
+                        .map(|result| result.assertions.clone())
+                        .unwrap_or_default(),
+                    initial_phase: result.and_then(|result| result.initial_phase),
+                    initial_sequence: result.and_then(|result| result.initial_sequence),
+                    initial_level: result.and_then(|result| result.initial_level),
+                    final_phase: result.and_then(|result| result.final_phase),
+                    final_sequence: result.and_then(|result| result.final_sequence),
+                    final_level: result.and_then(|result| result.final_level),
+                }
+            })
+            .collect::<Vec<_>>()
+    } else {
+        Vec::new()
+    };
+    let gameplay_summary = if scenario.is_none() {
+        prompt_text!("direct.browser.gameplayNotRun").to_string()
+    } else {
+        let lines = gameplay_results
+            .iter()
+            .map(|result| {
+                format!(
+                    prompt_text!("direct.browser.gameplayViewport"),
+                    viewport = match result.viewport {
+                        Desktop => "desktop",
+                        Mobile => "mobile",
+                    },
+                    passed = result.passed,
+                    diagnostic = result
+                        .diagnostics
+                        .first()
+                        .map(String::as_str)
+                        .unwrap_or(prompt_text!("direct.browser.gameplayNoDiagnostic")),
+                    assertion = result
+                        .assertions
+                        .iter()
+                        .find(|assertion| !assertion.passed)
+                        .map(|assertion| assertion.name.as_str())
+                        .unwrap_or(prompt_text!("direct.browser.gameplayNoUnmetAssertion")),
+                )
+            })
+            .collect::<Vec<_>>();
+        format!(
+            prompt_text!("direct.browser.gameplayEvidence"),
+            lines.join("\n")
+        )
+    };
+    let summary = format!(
+        "{}\n{}",
+        render_direct_browser_tool_evidence(root, evidence, sequence),
+        gameplay_summary
+    );
+    let screenshots: Vec<_> = evidence
+        .viewport_results
+        .iter()
+        .filter_map(|viewport| {
+            viewport
+                .screenshot_path
+                .strip_prefix(root)
+                .ok()
+                .map(|path| path.to_string_lossy().replace('\\', "/"))
+        })
+        .collect();
+    let passed = evidence.passed
+        && scenario.is_none_or(|scenario| {
+            crate::browser::required_viewport_playtests_passed(
+                scenario,
+                &evidence.viewport_playtests,
+            )
+        });
+    json!({
+        "kind":"browser", "mode":if scenario.is_some() {"gameplay"} else {"visual"},
+        "scenario":scenario, "passed":passed,
+        "scenarioFingerprint":scenario.map(crate::browser::browser_playtest_scenario_fingerprint),
+        "summary":summary, "screenshots":screenshots,
+        "reportPath":evidence.evidence.report_path.strip_prefix(root).ok().map(|path|path.to_string_lossy().replace('\\', "/")),
+        "visualViewports":["desktop","mobile"],
+        "gameplayViewports":evidence.viewport_playtests.iter().map(|entry|entry.viewport).collect::<Vec<_>>(),
+        "gameplayResults":gameplay_results,
+        "coverage":if scenario.is_some() {"dual-viewport-fixed-scenario"} else {"visual-only"}
+    })
+}
+
 pub(super) async fn run_browser(root: &Path, arguments: &Value) -> Result<Value, String> {
     run_browser_with_budget(root, arguments, true).await
 }
@@ -466,33 +597,9 @@ async fn run_browser_with_budget(
     .await;
     let (result, passed) = match evidence {
         Ok(evidence) => {
-            let screenshots: Vec<_> = evidence
-                .viewport_results
-                .iter()
-                .filter_map(|v| {
-                    v.screenshot_path
-                        .strip_prefix(root)
-                        .ok()
-                        .map(|p| p.to_string_lossy().replace('\\', "/"))
-                })
-                .collect();
-            let gameplay_passed = scenario.is_none_or(|scenario| {
-                crate::browser::required_viewport_playtests_passed(
-                    scenario,
-                    &evidence.viewport_playtests,
-                )
-            });
-            let passed = evidence.passed && gameplay_passed;
-            let summary = render_direct_browser_tool_evidence(root, &evidence, sequence);
-            (
-                json!({"kind":"browser", "mode":input.mode, "scenario":scenario,
-                "scenarioFingerprint":scenario.map(crate::browser::browser_playtest_scenario_fingerprint), "summary":summary, "screenshots":screenshots,
-                "reportPath":evidence.evidence.report_path.strip_prefix(root).ok().map(|p|p.to_string_lossy().replace('\\', "/")),
-                "visualViewports":["desktop","mobile"],
-                "gameplayViewports":evidence.viewport_playtests.iter().map(|v|v.viewport).collect::<Vec<_>>(),
-                "coverage":if scenario.is_some() {"dual-viewport-fixed-scenario"} else {"visual-only"}}),
-                passed,
-            )
+            let result = browser_tool_result(root, &evidence, scenario, sequence);
+            let passed = result["passed"] == true;
+            (result, passed)
         }
         Err(error) => (
             json!({"mode":input.mode,"needsReconciliation":error.starts_with("browser-cleanup-unconfirmed:"),"error":truncate_agent_runtime_text(&error, 1800)}),
@@ -599,9 +706,147 @@ pub(super) async fn run_command(root: &Path, arguments: &Value) -> Result<Value,
 }
 
 #[cfg(test)]
-mod tests {
+pub(super) mod tests {
     use super::*;
 
+    pub(crate) fn browser_evidence_fixture(root: &Path) -> crate::browser::BrowserValidationResult {
+        let mut viewports = Vec::new();
+        let mut playtests = Vec::new();
+        for viewport in ["desktop", "mobile"] {
+            viewports.push(json!({
+                "viewport":viewport, "width":1280, "height":720,
+                "finalUrl":"http://127.0.0.1/", "title":"fixture", "readyState":"complete",
+                "visibleTextSummary":"", "visibleTextCharacterCount":0, "domCharacterCount":0,
+                "expectedText":[], "consoleErrors":[], "consoleWarnings":[], "exceptions":[],
+                "failedRequests":[], "canvases":[], "diagnostics":[], "passed":true,
+                "blockedPopupCount":0, "blockedDialogCount":0, "blockedDownloadCount":0,
+                "blockedPermissionCount":0, "blockedServiceWorkerCount":0,
+                "screenshotPath":root.join(format!("{viewport}.png"))
+            }));
+            playtests.push(json!({"viewport":viewport, "result":{
+                "scenario":"generic-v1", "scenarioFingerprint":"fixture", "passed":true,
+                "initialSequence":0, "initialPhase":"ready", "initialLevel":1,
+                "finalSequence":3, "finalPhase":"ready", "finalLevel":1,
+                "assertions":[
+                    {"name":"start-control-clicked", "passed":true},
+                    {"name":"start-phase-playing", "passed":true},
+                    {"name":"restart-control-clicked", "passed":true}
+                ], "diagnostics":[]
+            }}));
+        }
+        serde_json::from_value(json!({
+            "schemaVersion":"browser-validation.v1", "url":"http://127.0.0.1/",
+            "browser":{"kind":"chrome", "product":"fixture", "protocolVersion":"1.3"},
+            "passed":true, "viewportResults":viewports, "viewportPlaytests":playtests,
+            "diagnostics":[], "completedAtUnixMs":1,
+            "evidence":{"root":root, "reportPath":root.join("validation.json")}
+        }))
+        .unwrap()
+    }
+
+    pub(crate) fn failed_browser_evidence_fixture(
+        root: &Path,
+    ) -> crate::browser::BrowserValidationResult {
+        let mut evidence = browser_evidence_fixture(root);
+        evidence.passed = false;
+        for (index, entry) in evidence.viewport_playtests.iter_mut().enumerate() {
+            entry.result.passed = false;
+            entry.result.final_phase = Some(crate::browser::BrowserPlaytestPhase::Ready);
+            entry.result.final_sequence = Some(index as u64);
+            entry.result.diagnostics = vec![if index == 0 {
+                "固定试玩控件 start 处于 disabled 状态".into()
+            } else {
+                "generic-v1 start 后必须进入 playing".into()
+            }];
+            for (assertion_index, assertion) in entry.result.assertions.iter_mut().enumerate() {
+                assertion.passed = index == 1 && assertion_index == 0;
+            }
+        }
+        evidence
+    }
+
+    #[test]
+    fn browser_tool_projection_distinguishes_gameplay_success_visual_only_and_missing_viewport() {
+        use crate::browser::BrowserPlaytestScenario::GenericV1;
+        let root = tempfile::tempdir().unwrap();
+        for mode in ["gameplay", "visual", "missing-mobile"] {
+            let mut evidence = browser_evidence_fixture(root.path());
+            let scenario = if mode == "visual" {
+                evidence.viewport_playtests.clear();
+                None
+            } else {
+                Some(GenericV1)
+            };
+            if mode == "missing-mobile" {
+                evidence.viewport_playtests.pop();
+                evidence.passed = false;
+            }
+            let receipt = browser_tool_result(root.path(), &evidence, scenario, 1);
+            let summary = receipt["summary"].as_str().unwrap();
+            assert_eq!(receipt["passed"], mode != "missing-mobile");
+            if mode == "visual" {
+                assert_eq!(receipt["gameplayResults"], json!([]));
+                assert!(summary
+                    .lines()
+                    .any(|line| line.starts_with("玩法检查：未执行")));
+                assert_eq!(receipt["coverage"], "visual-only");
+                continue;
+            }
+            for (index, viewport) in ["desktop", "mobile"].iter().enumerate() {
+                let result = &receipt["gameplayResults"][index];
+                assert_eq!(result["viewport"], *viewport);
+                if mode == "missing-mobile" && index == 1 {
+                    assert_eq!(result["passed"], false);
+                    assert!(result["diagnostics"][0].as_str().unwrap().contains("缺失"));
+                    assert!(summary.contains("mobile: gameplayPassed=false"));
+                    assert_eq!(result["assertions"], json!([]));
+                    assert_eq!(result["finalPhase"], Value::Null);
+                } else {
+                    assert_eq!(result["passed"], true);
+                    assert_eq!(result["diagnostics"], json!([]));
+                    assert!(result["assertions"]
+                        .as_array()
+                        .unwrap()
+                        .iter()
+                        .all(|a| a["passed"] == true));
+                    assert!(summary.contains(&format!("{viewport}: gameplayPassed=true")));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn browser_tool_projection_bounds_diagnostics_without_losing_either_blocker() {
+        let root = tempfile::tempdir().unwrap();
+        let mut evidence = failed_browser_evidence_fixture(root.path());
+        for viewport in &mut evidence.viewport_playtests {
+            viewport
+                .result
+                .diagnostics
+                .extend((0..8).map(|_| "额外诊断".repeat(200)));
+        }
+        let receipt = browser_tool_result(
+            root.path(),
+            &evidence,
+            Some(crate::browser::BrowserPlaytestScenario::GenericV1),
+            1,
+        );
+        for (index, entry) in evidence.viewport_playtests.iter().enumerate() {
+            let diagnostics = receipt["gameplayResults"][index]["diagnostics"]
+                .as_array()
+                .unwrap();
+            assert_eq!(diagnostics.len(), 4);
+            assert_eq!(diagnostics[0], entry.result.diagnostics[0]);
+            assert!(diagnostics
+                .iter()
+                .all(|d| d.as_str().unwrap().chars().count() <= 512));
+            assert!(receipt["summary"]
+                .as_str()
+                .unwrap()
+                .contains(&entry.result.diagnostics[0]));
+        }
+    }
+
     fn project() -> (tempfile::TempDir, std::path::PathBuf) {
         let temp = tempfile::tempdir().unwrap();
         let root = temp.path().join("project");

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

@@ -1514,6 +1514,41 @@ async fn real_chrome_generic_playtest_pointer_events_keeps_unavailable_controls_
     }
 }
 
+#[tokio::test]
+#[ignore = "requires an installed Chrome/Chromium/Edge and explicit local browser execution"]
+async fn real_chrome_generic_playtest_reports_start_click_without_playing_phase() {
+    let result = run_stable_generic_viewport_fixture(false, Some(
+        r#"<button type="button" data-playtest-id="start" data-start-phase="ready">Start</button>"#,
+    )).await;
+    assert!(!result.passed);
+    assert!(result
+        .viewport_results
+        .iter()
+        .all(|viewport| viewport.passed));
+    for entry in &result.viewport_playtests {
+        let playtest = &entry.result;
+        assert!(!playtest.passed);
+        assert_eq!(playtest.final_phase, Some(BrowserPlaytestPhase::Ready));
+        assert_eq!(playtest.final_sequence, Some(1));
+        for (name, expected) in [
+            ("start-control-clicked", true),
+            ("start-phase-playing", false),
+        ] {
+            assert_eq!(
+                playtest
+                    .assertions
+                    .iter()
+                    .find(|assertion| assertion.name == name)
+                    .unwrap()
+                    .passed,
+                expected
+            );
+        }
+        let reason = &playtest.diagnostics[0];
+        assert!(reason.contains("必须进入 playing"), "{reason}");
+    }
+}
+
 async fn run_stable_generic_viewport_fixture(
     mobile_action_broken: bool,
     start_markup: Option<&str>,
@@ -1556,7 +1591,7 @@ async fn run_stable_generic_viewport_fixture(
   };
   document.querySelector('[data-playtest-id="start"]').addEventListener('click', (event) => {
     if (event.isTrusted && state.phase === 'ready') {
-      advance(() => { state.phase = 'playing'; });
+      advance(() => { state.phase = event.currentTarget.dataset.startPhase || 'playing'; });
     }
   });
   const primary = document.querySelector('[data-playtest-id="primary-action"]');
@@ -1641,6 +1676,57 @@ async fn run_stable_generic_viewport_fixture(
     let persisted: serde_json::Value =
         serde_json::from_slice(&fs::read(&result.evidence.report_path).unwrap()).unwrap();
     assert_eq!(persisted["viewportPlaytests"].as_array().unwrap().len(), 2);
+    let receipt = crate::agent::browser_tool_result(
+        evidence.path(),
+        &result,
+        Some(BrowserPlaytestScenario::GenericV1),
+        1,
+    );
+    assert_eq!(receipt["passed"], persisted["passed"]);
+    for (index, entry) in persisted["viewportPlaytests"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .enumerate()
+    {
+        let projected = &receipt["gameplayResults"][index];
+        assert_eq!(projected["viewport"], entry["viewport"]);
+        let viewport = entry["viewport"].as_str().unwrap();
+        let line = receipt["summary"]
+            .as_str()
+            .unwrap()
+            .lines()
+            .find(|line| line.starts_with(&format!("{viewport}: gameplayPassed=")))
+            .unwrap();
+        assert!(line.starts_with(&format!(
+            "{viewport}: gameplayPassed={}",
+            entry["result"]["passed"]
+        )));
+        for field in [
+            "passed",
+            "assertions",
+            "initialPhase",
+            "initialSequence",
+            "initialLevel",
+            "finalPhase",
+            "finalSequence",
+            "finalLevel",
+        ] {
+            assert_eq!(projected[field], entry["result"][field], "{field}");
+        }
+        if let Some(reason) = entry["result"]["diagnostics"][0].as_str() {
+            assert_eq!(projected["diagnostics"][0], reason);
+            assert!(line.contains(reason));
+        }
+        if let Some(assertion) = entry["result"]["assertions"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|assertion| assertion["passed"] == false)
+        {
+            assert!(line.contains(assertion["name"].as_str().unwrap()));
+        }
+    }
     result
 }
 

apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnFailure.ts

@@ -96,9 +96,7 @@ function directModelCallText(kind: ModelCallKind | null | undefined): string {
     case 'upstreamFailed':
       return (
         (kind.native ? directNativeKindText(kind.native) : null) ??
-        (kind.statusCode >= 500
-          ? '智能服务暂时不可用，请稍后重试'
-          : '智能创作请求无效，请稍后重试')
+        directUpstreamStatusText(kind.statusCode)
       );
     case 'paidCreditsInsufficient':
       return '泥点余额不足，本轮游戏生成已中断。请充值后发送“继续”，系统会从当前项目进度接着完成。';
@@ -113,6 +111,23 @@ function directModelCallText(kind: ModelCallKind | null | undefined): string {
   }
 }
 
+function directUpstreamStatusText(statusCode: number): string {
+  switch (statusCode) {
+    case 401:
+      return '上游服务拒绝认证（HTTP 401），请重新登录后重试';
+    case 403:
+      return '上游服务拒绝访问（HTTP 403），请检查账号权限后重试';
+    case 408:
+      return '上游请求超时（HTTP 408），请稍后重试';
+    case 429:
+      return '上游服务繁忙（HTTP 429），请稍后重试';
+    default:
+      return statusCode >= 500
+        ? `智能服务暂时不可用（HTTP ${statusCode}），请稍后重试`
+        : `智能创作请求被上游拒绝（HTTP ${statusCode}），请检查请求后重试`;
+  }
+}
+
 function directTurnDeadlineText(deadline: Deadline): string {
   switch (deadline) {
     case 'response-idle':

apps/ai-game-creator-shell/tests/directTurnFailure.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { directTurnFailureNoticeText } from '../src/view/project-development/chat/conversation/directTurnFailure';
+
+describe('DirectProject 上游失败文案', () => {
+  it.each([401, 403, 408, 429, 500, 502, 503, 504])(
+    '保留 HTTP %s 的具体原因',
+    (statusCode) => {
+      const text = directTurnFailureNoticeText({
+        type: 'modelCallFailed',
+        kind: { type: 'upstreamFailed', statusCode, native: null },
+        detail: `上游 HTTP ${statusCode}`,
+      });
+
+      expect(text).toContain(`HTTP ${statusCode}`);
+      expect(text).not.toContain('智能创作请求无效');
+    },
+  );
+
+  it('原生分类优先于 HTTP 状态文案', () => {
+    const text = directTurnFailureNoticeText({
+      type: 'modelCallFailed',
+      kind: {
+        type: 'upstreamFailed',
+        statusCode: 429,
+        native: { type: 'context-window-exceeded' },
+      },
+      detail: 'upstream',
+    });
+
+    expect(text).toContain('模型上下文已超限');
+    expect(text).not.toContain('HTTP 429');
+  });
+});

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

@@ -6289,7 +6289,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **根因 4（界面看不到回复）**：聊天区是按 `item.completed` 事件流投影的（codex 路径在 `rawResponseItem/completed` 时下发 `ThreadItem::Message`），只把回复落进 `project.jsonl` 不会让本轮出现在界面上——用户看到"用户气泡 + 本轮结束于 … · 耗时"，回复只在重进项目时从历史读出来。
 - **根因 5（验收反馈复用 assistant ID）**：同一 client turn 进入 `ReviewRequired` 后会再次调用 cc。首次回复已经占用 `direct-codex:<clientTurnId>:assistant`，第二次不同正文沿用该 ID 会被历史层正确拒绝为冲突，随后却被错误投影成 `runtime-unclassified`。真实诊断中可见「写入本项目对话历史失败：…assistant」且历史已经有该条回复。
 - **根因 6（cc 字符串错误覆盖了上游分类）**：DirectProject 的 Claude Code 路由原本把 sidecar 返回的所有字符串都包装成 `LlmError::Transport`，因此 HTTP 429、401、408、5xx、sidecar 超时、空回执和无效 JSON 都显示成「执行通道未能建立或已断开」。
-- **现行口径**：cc 成功出口由放行侧补写 `DirectTurnTerminal::completed()`（`finish_if_unfinished` 幂等，codex 已写过终态时是空操作）；cc 每次解析成功后都把实际落盘的回复 item id 同步下发 `ThreadEvent::item_completed(ThreadItem::Message{role:"assistant"})`。首个回复沿用 `direct-codex:<clientTurnId>:assistant`，同一回合的反馈回复遇到内容冲突时追加 `:assistant:<uuid>`，相同内容仍按原 ID 幂等；落盘失败按回合失败收口。Claude Code 的失败文本先投影到与 Codex 相同的 `LlmError` 分类：HTTP 状态、sidecar 超时、空回执和无效 JSON 分别复用上游、超时、空响应和反序列化语义；上游状态摘要与重试建议按状态码给出。sidecar 按 `mcp__<server>` 前缀整体放行请求里声明的 MCP 服务器（权限策略在宿主侧执行）。
+- **根因 7（内部 Claude MCP 桥误用外部只读模式）**：Claude Code sidecar 使用的 loopback MCP 原本调用 `start_external_client_tool_bridge(..., false)`，桥状态 `direct_turn_execution=false` 且没有 `begin_user_turn()` 授权；`agc_register_delivery_contract`、`agc_delivery_status`、`agc_update_plan` 每次都会返回 `ToolRequiresDirectTurn`，模型收到错误后又重复注册计划，最终陷入反馈死循环直到超时。
+- **根因 8（MCP 全局单槽位）**：外部 MCP 注册表原本只有一个 `Option<ExternalMcpServer>`，不同项目的 Claude 回合会互相 abort；一个回合结束时的全局 stop 还可能误停另一个项目的桥。
+- **现行口径**：cc 成功出口由放行侧补写 `DirectTurnTerminal::completed()`（`finish_if_unfinished` 幂等，codex 已写过终态时是空操作）；cc 每次解析成功后都把实际落盘的回复 item id 同步下发 `ThreadEvent::item_completed(ThreadItem::Message{role:"assistant"})`。首个回复沿用 `direct-codex:<clientTurnId>:assistant`，同一回合的反馈回复遇到内容冲突时追加 `:assistant:<uuid>`，相同内容仍按原 ID 幂等；落盘失败按回合失败收口。Claude Code 的失败文本先投影到与 Codex 相同的 `LlmError` 分类：HTTP 状态、sidecar 超时、空回执和无效 JSON 分别复用上游、超时、空响应和反序列化语义；上游状态摘要与重试建议按状态码给出。内部 Claude Direct MCP 必须使用 `direct_turn_execution=true` 的工具桥并持有 `begin_user_turn()` guard；用户手动启动的外部 MCP 仍保持非 Direct 模式。MCP 注册表按 canonical project root 分桶，停止操作再核对 server token，迟到的旧回合不能误停同项目的新桥。sidecar 按 `mcp__<server>` 前缀整体放行请求里声明的 MCP 服务器（权限策略在宿主侧执行）。
 - **诊断口径**：`agent.direct_turn.host_dropped` / `agent.direct_turn.panic` 里的令牌字段必须写 `tt=`，写 `turnToken=` 会命中脱敏标记，整行变成 `<sensitive diagnostic details redacted>`，离线只剩"说不出原因"的 HostDropped。
 - **验证**：dev 栈里用 CDP 注入真实回合（`node %TEMP%\agc-cdp.mjs <expr>`）：①读文件轮 `claude-parse-done chars=108`，`.agent/conversations/project.jsonl` 出现 `direct-codex:cdp-…:assistant` 条目，回复内容与 `game/index.html` 前两行（`<!doctype html>` / `<html lang="zh-CN">`）逐字一致（证明宿主工具真的执行了）；②聊天视图打开时注入 `只回三个字：收到了`，DOM 断言（`document.body.innerText`）同时出现用户气泡 `11:40:05`、助手回复 `收到了` 与 `本轮结束于 11:40:16 · 耗时 10.7秒`（证明 `item.completed` 实时投影生效，不必重进项目）；同一日志不再出现新的 `host_dropped`。另有 `agent::claude_code_cli::tests::direct_claude_feedback_reply_does_not_fail_on_a_reused_client_turn_id` 回归覆盖同一回合两次不同回复。`cargo test … -- claude_code_cli::tests direct_turn_failure::tests` 19 passed。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_turn_failure.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`、`apps/ai-game-creator-shell/agent-sidecar/src/index.mjs`。

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

@@ -195,6 +195,8 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema
 ### 分层验证与预算
 
 - 复用客户端浏览器与现有固定玩法场景。视觉检查采集双端画面/布局/资源/诊断；玩法检查分别在 desktop/mobile 执行明确的固定场景和真实输入，按视口保存结果。旧报告缺少移动端玩法结果时保持未知，不补通过。报告必须声明检查层级；视觉通过不能宣称玩法通过，固定场景通过也不能宣称覆盖未执行的完整关卡。
+- 浏览器工具回执在 `mode=gameplay` 时新增 `gameplayResults` 双端有界投影，每个视口包含 `viewport`、`passed`、`diagnostics`、`assertions` 及 `initialPhase` / `initialSequence` / `initialLevel`、`finalPhase` / `finalSequence` / `finalLevel`。`assertions` 仅列当前固定场景的断言名称和通过状态；每端最多公开 4 条诊断，每条最多 512 字符。缺少某端结果时仍返回该视口 `passed=false`，诊断说明证据缺失，断言为空且六个状态字段为 `null`；断言的 `passed=false` 可包含未执行，不能据此断言该断言已独立执行且失败。`mode=visual` 的 `gameplayResults` 为空，并在摘要中明确玩法未执行。摘要从同一投影给出每端首条诊断和首个未通过断言，不能与结构化结果相矛盾。工具回执不得展开完整宿主报告；`reportPath` 只作宿主证据引用。宿主报告结构、验收门禁、持久化预算和私有路径保护保持原合同，旧回执不回填新字段。
+- 回执验收覆盖 start 禁用、点击后 phase 不符合和玩法成功；逐视口核对持久报告与摘要中的状态、首条诊断和首个未通过断言，并检查成功、失败两条最终 MCP 回包路径。
 - 输入或碰撞改变先做定点玩法检查；纯图像/颜色变化做视觉检查；首次交付和影响闭环的修改做所需玩法验证。新增失败或相关代码变化才重跑对应层，不因改说明文字重复完整验证。
 - 内置试玩和客户端托管的外部 Node/npm 验证共用当前 clientTurnId 的持久化预算。客户端分配递增执行序号，模型提供的旧 attempt 仅作兼容输入，不能减少计数或重置预算；同一轮错误反馈、工具切换和进程重启均不能刷新已消费次数。
 - 新增本地 validation.maxRuns（默认 3，正整数）独立于 llm.maxRetries；显式配置原样使用，不按角色或运行模式改写。超限直接返回已用/上限和最近证据，停止新的验证。预检与正常构建不计作重复试玩。