统一 AGC 失败兜底口径：兜底只用专用错误码与专用文案

新增 homeCreationFailure 统一创建失败出口：宿主机器码 / IPC 失联 / 专用未分类兜底三种文案，宿主原始文本改为 appendWebviewLog 落 application.log 而不上屏
首页创建失败不再无条件覆盖成「创建未完成，请重试」，也不再写死「首条需求投递失败」指认某一步；工作区已建好时保留该事实并提供「已创建的工作区」恢复说法
宿主预检按真实原因分流浏览器验证错误码（browser-missing / launch-timeout / launch-failed / cancelled / browser-cleanup-failed / browser-environment-failed / evidence-failed / input-invalid / page-check-failed），未识别落回专用 web-preflight-unclassified
依赖准备收据保留宿主返回的真实失败码，不再一律写成 web-scaffold-preparation-failed
直连回合失败分类器 else 改为专用 runtime-unclassified，并补 sidecar-turn-timeout / sidecar-launch-failed / app-server-launch-failed / claude-code-failed 四个有证据的具体码
Codex CLI 与 Claude sidecar 的进程启动失败保留真实 OS 错误，不再报成「不支持 app-server 子命令」或「Node runtime 不可用」
更新检查新增结果型入口 checkForAppUpdateResult，「关于」页检查失败显示真实原因而不是「当前已是最新版本」
首页无码预检兜底文案不再写「请检查 Node/npm 或浏览器」这类未证实的候选原因
同步 pitfalls 六条与团队约定：兜底码/兜底文案规则、五项修复的现象根因处理验证、测试夹具编译修复记录
验证：vitest homeCreationFailure/homeWebPreflight/appUpdate/appSurface 共 215 passed；cargo test environment_check:: 19 passed、agent::runtime_error:: 5 passed、direct_failure_diagnostic 4 passed、tests::configuration:: 45 passed；cargo fmt --check、tsc --noEmit、npm run typecheck、check:encoding、git diff --check 通过

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

@@ -6253,3 +6253,51 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理**：保留预检失败关闭语义，但提取 Rust 返回的安全错误码；对无错误码的 Tauri 调用故障显示独立 IPC 提示，并仅对这类瞬态调用失败重试一次。首页调用方必须透传该安全提示，不能重新覆盖为通用文案。
 - **验证**：`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx` 覆盖 ready、具体宿主错误码、IPC 失败、无错误码 blocked 和 planning 绕过；同一 Windows 安装包 CLI 实测 Node `v22.22.2`、npm `10.9.7`、Edge desktop/mobile PNG 均通过。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx`、`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`。
+
+## 2026-10-02 AGC 首页把创建失败覆盖成通用文案，「项目已建好」被说成「创建未完成」
+
+- **现象**：首页自动创建在项目目录已经建好之后失败（策划运行时切换、附件导入、进入工作台抛错）时，浮层显示「创建未完成，请重试」，而同一页面同时列着「已创建的工作区：…」；用户会以为没建成功，再建一遍。
+- **根因**：`useHomeProjectCreation.ts` 把底层文本拼进「工作区已创建；未能进入项目开发：<原因>」再抛出，`src/view/home/index.tsx` 的 `catch` 又无条件覆盖成写死的通用文案。注释声称“详细错误已由工作区创建控制器记录”，实际只有一次 `setStatus`，紧接着就被覆盖，没有任何落盘；同一处的包装文案还写死成「首条需求投递失败」，把运行时切换、附件导入等失败都指认成“投递”这一步。
+- **处理**：新增 `homeCreationFailure.ts` 作为唯一出口：由宿主机器码（`project-revision-conflict` / `web-build-timeout` 这类连字符标识）、Tauri/WebView 传输形状（`Failed to fetch`、IPC 自定义协议失败）与专用兜底共同决定用户文案，并按“工作区是否已建好”分成两条；宿主原始文本不再上屏，改为 `appendWebviewLog` 写进 `application.log` 作为证据（脱敏沿用 `normalizeDiagnosticText`）。控制器抛出 `HomeCreationFailure`（带 `userMessage` 与 `diagnostic`），首页只透传它的 `userMessage`，对未知值一律落回专用兜底；包装文案改为中性的「未能进入项目开发」，不再指认某一步。
+- **验证**：`apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts` 5 条覆盖机器码、传输故障、无码兜底、原始文本只进诊断、首页出口；`npx vitest run tests/appSurface.test.ts tests/homeCreationFailure.test.ts tests/homeWebPreflight.test.tsx tests/appUpdate.test.ts` 215 passed / 9 skipped；`npx tsc --noEmit -p tsconfig.json` 与 `npm run typecheck` 通过。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src/view/home/index.tsx`、`apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts`、`apps/ai-game-creator-shell/tests/appSurface/home.suite.ts`。
+
+## 2026-10-02 AGC 宿主预检把浏览器验证的多种原因压成一个 browser-failed
+
+- **现象**：预检失败一律提示浏览器相关问题，但同一安装包 `--environment-check` 可能返回 `status=ready`；宿主侧真实原因可能是证据目录不可写、报告写盘失败、宿主取消或浏览器收束未确认。
+- **根因**：`environment_check/web_creation.rs` 把 `validate_local_preview_in_browser` 的所有 `Err` 统一映射成 `web-preflight-browser-failed`（验证层实际会返回“未发现可用浏览器”“启动浏览器超时”“启动浏览器失败：<OS 码>”“宿主已停止本轮浏览器验证”“browser-cleanup-unconfirmed”“evidenceRoot …”“页面导航失败”等）。同一文件的依赖准备收据又把任何失败都写成 `web-scaffold-preparation-failed`，而宿主返回的真实机器码就在手上，等于把唯一的诊断线索作废。
+- **处理**：按真实原因分流成 `web-preflight-browser-missing` / `-launch-timeout` / `-launch-failed` / `web-preflight-cancelled` / `-browser-cleanup-failed` / `-browser-environment-failed` / `-evidence-failed` / `-input-invalid` / `-page-check-failed`，未识别原因落回专用兜底 `web-preflight-unclassified`；收据改为保留宿主返回的真实机器码，只有确实拿不到码时才用专用兜底；首页无码兜底文案不再写「请检查 Node/npm 或浏览器」这种未证实的候选原因。
+- **验证**：`cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute --bin genarrative-ai-game-creator-shell environment_check::` 19 passed（含 `browser_validation_failures_keep_their_own_reason_codes`、`scaffold_receipt_keeps_the_real_failure_code`）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`、`apps/ai-game-creator-shell/src-tauri/src/browser/process.rs`、`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`。
+
+## 2026-10-02 AGC 直连回合失败分类器拿具体码当兜底
+
+- **现象**：同一条 `code=runtime-failure` 同时承载「Claude Code 返回失败终态」与「Claude Agent SDK sidecar 回合超时」两种完全不同的原因；任何新失败形态都会静默并入该桶，从标签上看不出分类覆盖率。
+- **根因**：`agent/runtime_error.rs` 的 `classify_direct_codex_error` 用具体码 `runtime-failure` 做 `else` 兜底，并且整条分类依赖中文子串嗅探，未识别原因既没有专用兜底槽，也不进入统计口径。
+- **处理**：`else` 改为专用兜底码 `runtime-unclassified`；把已有真实证据的原因提升为具体码 `sidecar-turn-timeout` / `sidecar-launch-failed` / `app-server-launch-failed` / `claude-code-failed`。前端 `direct-codex-failure:v1|v2` 解析本就接受任意 `[a-z0-9-]+`，不需要兼容层。
+- **验证**：`cargo test … agent::runtime_error::` 5 passed（含新增的 `known_sidecar_and_app_server_failures_keep_their_own_codes`、`unclassified_failures_get_a_dedicated_code`）；`cargo test … direct_failure_diagnostic` 4 passed（断言已改为按实际原因分类）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs`、`apps/ai-game-creator-shell/src/features/agent-runtime/model.ts`。
+
+## 2026-10-02 AGC 子进程启动失败被报成「不支持子命令」/「Node runtime 不可用」
+
+- **现象**：Codex CLI 可执行文件缺失、路径错误、权限不足或被安全软件拦截时，用户被提示「当前 Codex CLI 不支持 app-server 子命令，请升级 Codex CLI」，升级后仍是同一个错；Claude sidecar 的 Node 进程完全起不来时被笼统说成「Node runtime 不可用」，且丢掉 OS 错误码。
+- **根因**：`config.rs::check_game_creator_codex_app_server_available` 与 `agent/claude_code_cli.rs::game_creator_claude_code_cli_version_identity` 都把 `Command::output()` 的 `map_err(|_| …)` 归因到“子命令不支持”或“运行时不可用”。`output()` 失败只可能是 spawn/exec 失败，与“不支持子命令”是两码事。
+- **处理**：两处改为保留真实 OS 错误的「启动失败」文案；`output()` 成功但输出不符时仍保留原来的“不支持 app-server 子命令，请升级”判据，失败关闭语义不变。
+- **验证**：`cargo test … tests::configuration::` 45 passed（覆盖 LLM 配置状态链路）；同一 `--bin` 编译通过。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/config.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`。
+
+## 2026-10-02 AGC 更新检查失败被显示成「当前已是最新版本」
+
+- **现象**：「关于」页手动检查更新，在清单 404、渠道缺少当前平台条目、网络失败或签名校验失败时仍显示「当前已是最新版本」。
+- **根因**：`services/appUpdate.ts` 把更新插件的所有异常统一 `return null`（按“无更新”收口），而这个 `null` 同时表示“没有更新”和“检查失败”；`RuntimeConfigDialog` 里对应的 `catch` 分支因此永远不可达，失败被兜成成功。
+- **处理**：新增结果型入口 `checkForAppUpdateResult()`（`available` / `current` / `failed` / `disabled`），失败保留插件返回的原始原因；`checkForAppUpdate()` 退化为启动期投影（失败仍静默、不阻塞启动、不动更新提示）；「关于」页按结果分别显示，失败显示具体原因，渠道未启用不再冒充“已是最新”。
+- **验证**：`apps/ai-game-creator-shell/tests/appUpdate.test.ts` 9 passed（新增失败/已是最新/有更新/未启用四组用例，并保留启动期静默断言）；`npx tsc --noEmit` 通过。
+- **关联**：`apps/ai-game-creator-shell/src/services/appUpdate.ts`、`apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`apps/ai-game-creator-shell/tests/appUpdate.test.ts`。
+
+## 2026-10-02 AGC 测试夹具未跟随“执行器与协议正交”拆分，HEAD 上 Rust 测试无法编译
+
+- **现象**：`cargo test --bin genarrative-ai-game-creator-shell` 在 HEAD 上直接编译失败，9 个错误全部集中在 `src/tests/configuration.rs`：`select_game_creator_model` 少了第 4 个协议参数、`GameCreatorAppConfig` 少了 `selected_model_protocol` 字段。
+- **根因**：`6bf57c1e5` 把执行器与线协议拆成正交维度时只更新了生产代码，测试夹具没有同步，于是所有 Rust 定向验证（包括随包预检与运行时分类）都被挡住。
+- **处理**：夹具补 `None` 协议参数与 `selected_model_protocol: None`，不改任何断言口径。
+- **验证**：`cargo test --features=… --bin … tests::configuration::` 45 passed。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs`、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`、`apps/ai-game-creator-shell/src-tauri/src/main.rs`。

docs/project-memory/shared-memory/team-conventions.md

@@ -18,6 +18,8 @@
 
 - DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。完整回合条目统一保存在 `project.jsonl`；旧平行审计和附属请求分段计时已退出生产入口，不能因残留实现或测试而恢复旧契约。界面生命周期耗时与独立模型使用记录继续有效，未知边界不补零。详见 AGC 主专题的“Direct 历史、审计与耗时的现行边界”。
 
+- 用户可见失败必须与真实原因对齐：兜底只允许使用**专门的兜底码/兜底文案**（`*-unclassified` / `*-unknown` / `Other` / IPC 与未分类专用提示），任何一层都不得借用某个具体子系统的错误去兜住无关原因（把 Tauri IPC 断连说成「环境预检未通过」、把进程启动失败说成「不支持 app-server 子命令」、把更新检查失败说成「已是最新」都属此类）。下层已经算好的**用户文案**（宿主错误码、控制器整理过的提示）只能透传，不得被上层覆盖成通用文案；宿主原始文本（Provider 文本、IPC 报错、完整路径）不直接上屏，只作为证据写进 `application.log`、运行时错误事件或 analytics。分类器的 `else` 必须是专用未分类码，不能用已有具体码兼任。详见 pitfalls 的 2026-10-02 批次条目。
+
 - DirectProject 源码修改走 `agc_apply_patch`、进度走 `agc_update_plan`：SDK 原生的 `apply_patch` / `update_plan` 注册会被按回合移除（全局串行单例），不要恢复它们或用伪造工具注解换取并发。补丁只在当前项目内、受当前回合 Write 许可和受控进程约束，失败可能已部分写入，未知结果不自动重放；计划完成不构成验收证据。
 
 - 捆绑 Codex 版本只在 `build_support/codex_bundle.rs` 固定一次，不要在测试或脚本里另写字面量；升级 SDK 后必须重跑模型目录真实用例、宿主补丁往返、并发夹具与发行载荷 smoke。原生命令工具名随 SDK 版本变化（0.155 起为 `exec_command` / `write_stdin`），脚本与夹具应按真实目录取用，不要按旧名字硬编码。

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

@@ -184,7 +184,7 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema
 ### 环境与工作流
 
 - 客户端交付配套 Node/npm；发布包从本机已安装且与目标平台/架构一致的工具链制作受校验资源，保留许可并校验内容摘要。安装态不依赖系统 PATH 的 Node；开发态可使用已验证的宿主运行时。不得从项目或相对 PATH 加载伪造运行时。随包运行时是**单架构**官方发行版，因此 macOS 当前只构建 `aarch64-apple-darwin` 单架构包；要出 universal 必须先让 staging 支持按架构各带一份同版本运行时，在此之前 universal 目标失败关闭，不得只带宿主架构那一份糊过去。
-- 新建 Web 游戏在生图和大量实现前执行客户端环境预检，检查 Node/npm 的实际版本、浏览器启动和 CDP 可用性。报告只包含安全状态、版本、耗时和错误码。缺失或异常必须尽早返回阻塞，不能指示模型改宿主环境、全盘搜索或自行下载一套运行时。编辑器工程不强制 Web 工具链。
+- 新建 Web 游戏在生图和大量实现前执行客户端环境预检，检查 Node/npm 的实际版本、浏览器启动和 CDP 可用性。报告只包含安全状态、版本、耗时和错误码；错误码必须按真实原因分流，浏览器验证只允许在确有证据时使用 `web-preflight-browser-missing` / `-launch-timeout` / `-launch-failed` / `-browser-cleanup-failed`，取消、证据写入、输入与页面校验各有独立码，未识别原因落回专用 `web-preflight-unclassified`，不得用一个具体子系统码兜底。缺失或异常必须尽早返回阻塞，不能指示模型改宿主环境、全盘搜索或自行下载一套运行时。编辑器工程不强制 Web 工具链。
 - 预检不安装依赖、不修改项目 revision、不请求平台生成；构建仍执行项目自己的 npm 脚本。Codex 隔离 HOME 与平台凭据边界保持不变，客户端把已验证的运行时加入执行 PATH，不能把宿主凭据目录交给模型。
 - 第一轮先明确本次必需玩法、素材和验收项。同批独立读取尽量合并，必需图片一次规划；已有且可用的资产复用。已有目标全部通过后给出交付结果，非阻塞的新点子列为后续工作，不在收尾时主动开启新的生产链。