优化首页建项流程：AI 项目命名改为创建后异步执行 #599

New Issue

2026-10-03T17:50:19+08:00

suzmii commented

2026-10-03 17:50:19 +08:00

问题

首页自动创建游戏工作区时，当前会先同步调用 AI 生成项目名称，等命名请求返回后才真正创建工作区。

用户点击「开启创作」后页面长时间停留在「正在创建工作区」，创建耗时被无关的项目命名请求放大。截图中已出现该现象。

代码证据

当前链路位于：

apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
- suggestAutomaticProjectName() 在创建前被 await
- 随后才调用 create_automatic_local_game_project
apps/ai-game-creator-shell/src-tauri/src/commands/desktop.rs
- 自动命名请求虽然设置了 15 秒超时，但仍会阻塞前端创建流程
apps/ai-game-creator-shell/src-tauri/src/commands.rs
- create_automatic_local_game_project_at() 已支持未传名称时使用兜底名称
- rename_local_game_project() 已提供项目改名基础能力

当前命名失败会回退默认名称，但回退发生在等待请求结束之后，不能解决正常请求或超时请求造成的创建延迟。

原因

项目创建与项目命名被绑定成串行流程：

Web 环境预检；
等待 AI 生成项目名；
创建本地工作区；
进入工作台并开始首轮创作。

项目名称不是创建工作区、导入附件或发起首轮创作的前置条件，因此不应阻塞建项主链路。

实施方案

预检通过后立即创建工作区，传入空名称或不传名称，使用 Rust 现有兜底名称。
AI 项目命名改为后台异步任务，与工作区创建并行。
工作区创建成功后立即进入项目，不等待命名结果。
AI 返回合法名称后异步更新 manifest、当前项目上下文和最近项目列表。
增加条件改名保护：
- 校验项目 ID；
- 仅当当前名称仍是本次创建的兜底名称时才自动改名；
- 用户已手动改名时跳过 AI 名称，不能覆盖用户输入。
AI 命名失败、超时或返回非法内容时保持兜底名称，不影响项目创建、附件导入和首轮创作。
「做方案」流程和手动选择目录建项流程保持现有行为。

验收标准

create_automatic_local_game_project 不再等待 suggest_automatic_project_name 返回。
AI 命名请求慢、超时或失败时，用户仍可进入工作区并开始首轮创作。
AI 返回合法名称后，工作台标题和项目列表最终同步更新。
用户手动改名后，后台 AI 结果不能覆盖用户名称。
空、非法或异常 AI 响应保留兜底名称。
「做方案」不发起自动项目命名请求。
补充前端时序测试、Rust 条件改名测试和真实客户端创建 smoke。

## 问题首页自动创建游戏工作区时，当前会先同步调用 AI 生成项目名称，等命名请求返回后才真正创建工作区。用户点击「开启创作」后页面长时间停留在「正在创建工作区」，创建耗时被无关的项目命名请求放大。截图中已出现该现象。 ## 代码证据当前链路位于： - `apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts` - `suggestAutomaticProjectName()` 在创建前被 `await` - 随后才调用 `create_automatic_local_game_project` - `apps/ai-game-creator-shell/src-tauri/src/commands/desktop.rs` - 自动命名请求虽然设置了 15 秒超时，但仍会阻塞前端创建流程 - `apps/ai-game-creator-shell/src-tauri/src/commands.rs` - `create_automatic_local_game_project_at()` 已支持未传名称时使用兜底名称 - `rename_local_game_project()` 已提供项目改名基础能力当前命名失败会回退默认名称，但回退发生在等待请求结束之后，不能解决正常请求或超时请求造成的创建延迟。 ## 原因项目创建与项目命名被绑定成串行流程： 1. Web 环境预检； 2. 等待 AI 生成项目名； 3. 创建本地工作区； 4. 进入工作台并开始首轮创作。项目名称不是创建工作区、导入附件或发起首轮创作的前置条件，因此不应阻塞建项主链路。 ## 实施方案 1. 预检通过后立即创建工作区，传入空名称或不传名称，使用 Rust 现有兜底名称。 2. AI 项目命名改为后台异步任务，与工作区创建并行。 3. 工作区创建成功后立即进入项目，不等待命名结果。 4. AI 返回合法名称后异步更新 manifest、当前项目上下文和最近项目列表。 5. 增加条件改名保护： - 校验项目 ID； - 仅当当前名称仍是本次创建的兜底名称时才自动改名； - 用户已手动改名时跳过 AI 名称，不能覆盖用户输入。 6. AI 命名失败、超时或返回非法内容时保持兜底名称，不影响项目创建、附件导入和首轮创作。 7. 「做方案」流程和手动选择目录建项流程保持现有行为。 ## 验收标准 - `create_automatic_local_game_project` 不再等待 `suggest_automatic_project_name` 返回。 - AI 命名请求慢、超时或失败时，用户仍可进入工作区并开始首轮创作。 - AI 返回合法名称后，工作台标题和项目列表最终同步更新。 - 用户手动改名后，后台 AI 结果不能覆盖用户名称。 - 空、非法或异常 AI 响应保留兜底名称。 - 「做方案」不发起自动项目命名请求。 - 补充前端时序测试、Rust 条件改名测试和真实客户端创建 smoke。

suzmii added the Kind/Enhancement

Priority

Low

4

labels 2026-10-03 17:50:56 +08:00

suzmii self-assigned this 2026-10-03 19:47:59 +08:00

suzmii commented

2026-10-04 00:01:26 +08:00

问题原因

首页「开启创作」的建项链路把 AI 项目命名 await 在创建工作区之前：

Web 环境预检；
await suggest_automatic_project_name（宿主侧最长 15s 超时，正常请求同样占时）；
才调用 create_automatic_local_game_project。

项目名称并不是创建工作区、导入附件或发起首轮创作的前置条件，这一步串行让用户停在「正在创建工作区」上，创建耗时被一个无关的命名请求放大。

打算进行的更改 / 实现思路

预检通过后立即创建工作区：create_automatic_local_game_project 固定传 name: null，走宿主现有兜底名（GameAgent 项目 <8 位短 id> / 策划项目 <8 位短 id>）。
命名请求改为与建项并行发起，结果交给后台任务消费，建项一刻不等它。
工作区创建成功立即进入项目；后台命名结果在「进项目落定」（entrySettled）之后再回填当前项目上下文与最近项目行的目录重检，避免被进项目的兜底上下文覆盖。
宿主新增条件改名命令 rename_local_game_project_if_unchanged(projectPath, expectedProjectId, expectedName, name)：只有「项目 ID 相符」且「当前名称仍是本次创建的兜底名」才落盘改名；用户已手动改名、项目 ID 不符、名称未变一律跳过（renamed: false，不写盘）。与既有 rename_local_game_project 同口径，改名是簿记写入、不推进项目 revision。
AI 命名失败 / 超时 / 返回空或非法内容 → 保留兜底名，不影响创建、附件导入与首轮创作。
「做方案」不发起自动项目命名；手动选择目录建项流程保持原行为。

落地情况

commit e3c91c4e2（分支 fix/home-project-naming-async），PR #606。
改动文件：src-tauri/src/commands.rs（新增条件改名命令 + 5 例单测）、src-tauri/src/desktop.rs（注册新命令 1 行）、src/features/app-shell/useHomeProjectCreation.ts（并行建项 + 后台回填）、WorkspaceLauncher.tsx（注入最近项目重检）、src/app/types.ts（结果类型）、tests/homeProjectNamingAsync.test.tsx（新增 9 例时序测试）、tests/appSurface/home.suite.ts（客户端级用例 + 既有附件用例改为 name: null），另更新实施计划专题 / decision-log / pitfalls。
验证（实跑）：Rust 条件改名 conditional_project_rename_tests 5 passed；前端闸门时序用例 9 passed；AGC 全量套件 1910 passed / 17 skipped；cargo check、cargo fmt --check、npm run agc:typecheck、npm run check:encoding、git diff --check 全过。
未覆盖：真机（真实 Tauri 客户端）建项 smoke 需要重启在跑的客户端（CDP 9222 只在 WebView2 创建前生效），尚未执行。

## 问题原因首页「开启创作」的建项链路把 AI 项目命名 **`await` 在创建工作区之前**： 1. Web 环境预检； 2. `await suggest_automatic_project_name`（宿主侧最长 15s 超时，正常请求同样占时）； 3. 才调用 `create_automatic_local_game_project`。项目名称并不是创建工作区、导入附件或发起首轮创作的前置条件，这一步串行让用户停在「正在创建工作区」上，创建耗时被一个无关的命名请求放大。 ## 打算进行的更改 / 实现思路 1. 预检通过后**立即**创建工作区：`create_automatic_local_game_project` 固定传 `name: null`，走宿主现有兜底名（`GameAgent 项目 <8 位短 id>` / `策划项目 <8 位短 id>`）。 2. 命名请求改为与建项**并行**发起，结果交给后台任务消费，建项一刻不等它。 3. 工作区创建成功立即进入项目；后台命名结果在「进项目落定」（`entrySettled`）之后再回填当前项目上下文与最近项目行的目录重检，避免被进项目的兜底上下文覆盖。 4. 宿主新增条件改名命令 `rename_local_game_project_if_unchanged(projectPath, expectedProjectId, expectedName, name)`：只有「项目 ID 相符」且「当前名称仍是本次创建的兜底名」才落盘改名；用户已手动改名、项目 ID 不符、名称未变一律跳过（`renamed: false`，不写盘）。与既有 `rename_local_game_project` 同口径，改名是簿记写入、不推进项目 revision。 5. AI 命名失败 / 超时 / 返回空或非法内容 → 保留兜底名，不影响创建、附件导入与首轮创作。 6. 「做方案」不发起自动项目命名；手动选择目录建项流程保持原行为。 ## 落地情况 - commit `e3c91c4e2`（分支 `fix/home-project-naming-async`），PR #606。 - 改动文件：`src-tauri/src/commands.rs`（新增条件改名命令 + 5 例单测）、`src-tauri/src/desktop.rs`（注册新命令 1 行）、`src/features/app-shell/useHomeProjectCreation.ts`（并行建项 + 后台回填）、`WorkspaceLauncher.tsx`（注入最近项目重检）、`src/app/types.ts`（结果类型）、`tests/homeProjectNamingAsync.test.tsx`（新增 9 例时序测试）、`tests/appSurface/home.suite.ts`（客户端级用例 + 既有附件用例改为 `name: null`），另更新实施计划专题 / decision-log / pitfalls。 - 验证（实跑）：Rust 条件改名 `conditional_project_rename_tests` **5 passed**；前端闸门时序用例 **9 passed**；AGC 全量套件 **1910 passed / 17 skipped**；`cargo check`、`cargo fmt --check`、`npm run agc:typecheck`、`npm run check:encoding`、`git diff --check` 全过。 - 未覆盖：真机（真实 Tauri 客户端）建项 smoke 需要重启在跑的客户端（CDP 9222 只在 WebView2 创建前生效），尚未执行。

suzmii referenced this issue from a commit

2026-10-04 00:12:18 +08:00

补充 #599 自审回归用例：用户已切到别的工作区时后台改名不劫持上下文

suzmii referenced this issue from a commit

2026-10-05 15:51:50 +08:00

收口 #599 评审：文档补面板补读的门控条件、PR 正文用例数字与真实计数对齐

suzmii referenced a pull request that will close this issue

2026-10-05 16:06:36 +08:00

修复 #599：首页建项不再等待 AI 项目命名，改为后台条件改名 #606

suzmii closed this issue

2026-10-05 16:06:48 +08:00

Sign in to join this conversation.