Merge pull request '修复 #599：首页建项不再等待 AI 项目命名，改为后台条件改名' (#606) from fix/home-project-naming-async into master

Reviewed-on: http://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/606

docs/project-memory/shared-memory/decision-log.md

@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-10-03 首页自动建项与 AI 项目命名解耦（Issue 599）
+
+- 背景：首页「开启创作」原先串行执行「Web 预检 → `await suggest_automatic_project_name` → `create_automatic_local_game_project`」。项目名称不是创建工作区、导入附件或发起首轮创作的前置条件，命名请求（`AUTOMATIC_PROJECT_NAME_TIMEOUT_MS = 15s`，正常请求同样占时）却把用户按在「正在创建工作区」上。
+- 决策（建项与命名解耦）：建项固定传 `name: null`，由宿主既有兜底名（`GameAgent 项目 <8 位短 id>` / `策划项目 <8 位短 id>`）落盘并立即进入项目；命名请求在建项前并行打出、结果交给后台任务。后台拿到合法名称后调用新增的 `rename_local_game_project_if_unchanged(projectPath, expectedProjectId, expectedName, name)`：只有「项目 ID 相同」且「当前名称仍是本次创建的兜底名」才改名，返回 `renamed: true/false`（跳过时不写盘、不是错误）。用户已手动改名、项目 ID 不符、名称与现状相同一律跳过；空 `expectedProjectId` / `expectedName`、空名 / 控制字符 / 超长一律失败关闭。
+- 决策（纳入「生成任务」体系）：自动命名做成**项目工作台那条既有「生成任务」列表里的一条后台任务**，而不只是页面里的一个 promise。账本记录加 `taskType`（`asset-generation` / `project-naming`，缺省 `asset-generation`）、`kind` 变可选，schema 升 `agc-asset-generation-task.v2`（读取同时接受 v1/v2，v1 记录按素材任务读回）；新增 `enqueue_local_project_naming_task`（排队中）/ `update_local_project_naming_task`（命名中 → 已完成/失败），展示名固定「AI 项目命名」，与素材生成共用同一份账本、同一个变更事件与同一个侧栏。状态流转：排队中 → 命名中 → 已完成（已应用 AI 名称 / 建议名与现状一致 / 用户已手动改名而跳过）或失败（无可用名称 / 自动改名失败，均保留兜底名）。命名任务由命名链路推进、**不进 live 集合就会被中断收口误判**，所以 enqueue 写账本前登记 live、update 终态写盘后摘除（中断残留仍按命名口径收口为失败）。前端按 `taskType` 把命名记录从素材任务分支里剔除，命名行不渲染缩略图/提示词/派发与定位动作，结论只在终态显示。
+- 边界：改名是簿记写入，与既有 `rename_local_game_project` 同口径**不推进项目 revision**（推 revision 会让运行时验证凭证无故漂移）；返回的 `revision` 是当时盘上的值。后台改名结果写「当前项目上下文」与「最近项目行重检」必须等建项主体收尾（`entrySettled`）：AI 比进项目更快时直接写上下文会被随后的 `enterProjectDevelopment` 用兜底名覆盖，最近项目行也要等进项目登记过才会被重检；写入前再过壳的生命周期守卫（`mounted` + 代次），关窗/卸载后只保留已落盘的改名，不写 UI 投影。账本是**展示旁路**：`enqueue` / `update` 失败只写诊断日志，绝不影响建项、命名与首轮创作；「做方案」与手动选目录建项不发起自动命名。本次未改共享契约（`packages/shared/**`）、server-rs 与任何 SpacetimeDB schema/HTTP 路由。条件改名的 `expectedProjectId` / `expectedName` 为空时按仓库同类入口口径失败关闭；`update_local_project_naming_task` 与 enqueue 共用 `project.rename` 权限位、校验记录归属，且终态只接受同状态幂等重放。**兼容性写成显式边界：兼容是单向的**——新构建读 v1 账本 OK；旧构建读到含命名记录（`kind: null`）的账本会整份解析失败（面板报读失败、同批在途素材任务被按中断收口）。前端刷新必须先订阅事件再读快照，并在面板打开时补读一次兜底（**门控**：仅当列表里确实存在在途命名行时才补读，避免给没有命名任务的项目多打一次账本 IPC）。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/{commands.rs,desktop.rs,asset_generation_tasks.rs,asset_generation_tasks/runtime.rs}`、`apps/ai-game-creator-shell/src/{app/types.ts,features/app-shell/{useHomeProjectCreation.ts,WorkspaceLauncher.tsx},features/resource-canvas/{resourceCanvasAssetGenerationTaskModel.ts,ResourceCanvasAssetGenerationTasksPanelView.tsx},view/project-development/index.tsx}`、`apps/ai-game-creator-shell/tests/{homeProjectNamingAsync.test.tsx,projectNamingGenerationTaskRow.test.tsx,appSurface/home.suite.ts}`。
+- 验证：`npx vitest run apps/ai-game-creator-shell/tests/homeProjectNamingAsync.test.tsx`（12 passed，含「命名请求永不返回仍进工作区」「AI 结果先于进项目落定仍不被兜底名覆盖」「手动改名不被覆盖且任务按已完成+已跳过收口」「非法/空响应 → 任务 failed 且保留兜底名」「做方案不发起命名」「切到别的工作区不被劫持」「卸载/pagehide 后不写上下文」，并断言入队→命名中→终态的账本推进序列）；`projectNamingGenerationTaskRow.test.tsx`（3 passed：固定展示名/不渲染缩略图提示词定位、终态才显示结论、失败徽章与原因 + 在途计数）；AGC 全量 `npm run test -- apps/ai-game-creator-shell/tests`（1964 passed / 17 skipped）；`cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute asset_generation_task`（27 passed，含 `naming_task_stays_in_flight_across_ledger_reads_until_terminal`、`naming_task_update_requires_the_project_rename_permission`、`naming_task_update_rejects_a_record_from_another_project`、`naming_task_terminal_state_rejects_a_different_status_but_allows_the_same_one`、`ledger_with_an_unsupported_schema_version_fails_closed`、`ledger_without_a_schema_version_is_accepted_as_v1`）与 `conditional_project_rename_tests`（7 passed，含超长名失败关闭）；`npm run agc:typecheck`（含 `check:tests:types`）、`cargo fmt --check`、`npm run check:encoding`、`git diff --check`。
 ## 2026-10-03 AGC 发布版本标签改为由工程内部版本派生，取代「用户可编辑标签」口径
 
 - 背景：用户实机验收指出发布面板「项目版本」显示 v6，而 AGC 工程内部只有 4 条正式版本记录（资源总览「项目版本」栏目 4 张卡，顶栏「智能体修订」下拉同样只有这 4 条）。核实：面板值来自本地清单 `manifest.projectVersion` 这个可编辑标量，它被三条链路反复钉到**平台** `game_distribution_version.version_number` 上——发布成功回写（`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:1531-1535`）、打开面板回读绑定回填（`:536-541`）、用户手改（`:944-965`）；而 `manifest.versions` 从头到尾不参与该值。`publicationRevision` 只做 CAS，与任何版本号都无推导关系（`module-game-distribution/src/domain.rs:27-40` 的版本号解析只比 `max_existing` 与 `requested`）。

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

@@ -2,6 +2,26 @@
 
 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
 
+## 2026-10-04 把非素材任务塞进「生成任务」账本：taskType 维度、v1 兼容与 live 集合
+
+- **现象**：首页「AI 项目命名」改成进「生成任务」列表后，第一次读账本（工作台打开项目就会读）就把那条还在跑的命名任务标成**失败**；随后前端的终态推进被拒（记录已终态）。
+- **根因**：账本的中断收口判据是「非终态 + 不在本进程 live 集合」= 上次运行的残留。素材生成任务由 Rust 后台任务在 `start` 里先登记 live 再落账本；项目命名任务由前端驱动（`enqueue` / `update` 两条 IPC），没有登记 live，于是任何一次 `list_local_project_asset_generations` 都把它当成残留收口。
+- **处理（现行口径）**：账本记录加 `taskType`（`asset-generation` / `project-naming`，缺省 `asset-generation`）、`kind` 变可选；schema 升 `agc-asset-generation-task.v2`，读取同时接受 v1 与 v2（v1 记录按素材任务读回）。`enqueue_local_project_naming_task` 写账本前登记 live（写盘失败只回滚本轮插入的那条），`update_local_project_naming_task` 在非终态时幂等登记、终态写盘成功后摘除。命名没有素材可交叉核对，中断收口一律 failed 且文案与素材口径区分（不含「目标素材」）。
+- **边界**：命名任务的结论文案（已应用 / 用户已改名跳过 / 失败保留兜底名）由命名链路给出；账本只是展示旁路——`enqueue` / `update` 失败只写诊断日志，绝不影响建项、命名与首轮创作。前端按 `taskType` 把命名记录从素材任务列表里剔除（素材分支会按 `kind` 解析），命名行固定展示名「AI 项目命名」，只在终态显示结论。
+- **边界（兼容是单向的，必须写清）**：**新构建读旧账本 OK，旧构建读新账本会失败**——命名记录写 `"kind": null`，而旧构建（`AssetGenerationTaskRecord.kind` 必填且 `read_ledger` 不校验 schema）解析含命名记录的账本会**整份失败** → 面板报「生成任务列表读取失败」，且同一次读里在途的素材任务会被按「上次运行中断」收口为失败。触发条件只有「同一项目先被新构建写过命名任务、之后又被旧构建打开（降级或新旧混跑）」。潜在的低成本正向兼容方向（**未实施，需先确认**）：命名记录也写一个合法 `kind`（例如 `unknown`）只靠 `taskType` 区分——旧构建会把它渲染成一张名为「AI 项目命名」的素材任务卡，但账本能解析、不会误伤在途素材任务。
+- **边界（前端读快照的时序）**：命名行的推进发生在本组件之外，刷新只能靠「变更事件 + 一次受控快照读取」。**必须先订阅再读**（与素材队列「先订阅后派发」同口径）：先读后订阅时，落在这一次 IPC 往返里的终态事件没有消费者、直接丢掉，行会永久停在「命名中」；订阅失败时退化为「进项目读一次 + 面板打开时补读」。补读兜底必须有，但**有门控**：仅当列表里确实存在一条在途命名行时才读——没有命名任务的项目不该因为打开面板就多打一次账本 IPC，那会改变「轮询计数」这类外部可观测行为（既有生成任务用例正是按轮询次数推进 mock 的）。
+- **边界（update 的门禁与终态语义）**：`update_local_project_naming_task` 与 `enqueue` 共用 `project.rename` 权限位，并校验记录 `project_id` 与项目一致；记录一旦终态只接受**同状态幂等重放**，改写成另一种状态（含 `completed → failed`）一律 Err 且不写盘——否则一次迟到的排队/失败事件会覆盖已落定的命名结论。
+- **判据/取证**：Rust `cargo test … asset_generation_task` 27 条（含 `naming_task_stays_in_flight_across_ledger_reads_until_terminal`、`naming_task_update_requires_the_project_rename_permission`、`naming_task_update_rejects_a_record_from_another_project`、`naming_task_terminal_state_rejects_a_different_status_but_allows_the_same_one`、`ledger_with_an_unsupported_schema_version_fails_closed`、`ledger_without_a_schema_version_is_accepted_as_v1`）与 `conditional_project_rename_tests` 7 条（含超长名失败关闭）；前端 `homeProjectNamingAsync.test.tsx`（入队→running→终态的推进序列）、`projectNamingGenerationTaskRow.test.tsx`（行渲染）、appSurface 的「syncs the workbench title and recent project list with the AI name after creation」「recovers the naming row when the terminal event lands before the subscription is ready」「re-reads the naming ledger when the generation tasks panel opens」（后两条已做「改前红」验证：退回「先读后订阅 / 面板打开不补读」两条即红）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`。
+
+## 2026-10-03 后台异步回填被「进项目」覆盖：AI 项目名只在兜底名仍成立时改
+
+- **现象**（Issue 599）：首页建项把 AI 命名改成「与建项并行、结果后台回填」后，偶尔工作台标题停在兜底名（`GameAgent 项目 <短 id>`），而磁盘 manifest 已经是 AI 名字。
+- **原因**：改名落盘很快，但写「当前项目上下文」的那次 `setCurrentProjectContext` 被 `enterProjectDevelopment` 随后的兜底上下文覆盖——AI 比进项目更快时，回填写入时上下文里还没有这个项目（`current` 为 null 或仍是上一个项目）。同一原因下 `refreshRecentWorkspace` 也会被丢弃：最近项目行只在 `recentWorkspacesRef` 已包含该路径时才更新状态，而路径是进项目时才登记的。
+- **处理（现行口径）**：后台改名任务里，「写项目上下文 + 重检最近项目行」这两步必须等「建项主体收尾」（进项目成功、失败或让位于别的项目）的信号再执行；改名本身照旧立即落盘。回归用 promise 闸门卡住 `get_local_game_preview_status` 复现顺序，不用 sleep。
+- **判据/取证**：`npx vitest run apps/ai-game-creator-shell/tests/homeProjectNamingAsync.test.tsx` 的「keeps the AI name when the naming result lands before the project is entered」（去掉等待即复现兜底名覆盖）；appSurface 的「syncs the workbench title and recent project list with the AI name after creation」。
+- **边界**：条件改名的判据必须由宿主校验（项目 ID + 当前名称仍是兜底名），前端只转述 `expectedProjectId` / `expectedName`；用户已手动改名时宿主返回 `renamed: false`，回填整体跳过、绝不覆盖用户输入。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`。
 ## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
 
 - **现象**：Windows 本机 `npm run check:generated-bindings`（`npm run lint` 链内，`scripts/check-repository-ci.sh` 的 Repository checks 也走它）在 `build.rs:167:29` panic：`插件随包资源校验失败：随包插件存在未声明文件：.../src-tauri/resources/plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`；树上换成 `agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe` 时报同一类错。反向还有更隐蔽的形态：门禁 2 秒就 exit 0 说「通过」，但 tree 上其实带着编辑器产物。

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

@@ -1,5 +1,17 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-10-03 首页建项不等 AI 命名（Issue 599）
+
+本节覆盖下文「2026-08-20 Direct Codex 审核 Skill Pack 与受控工具内核」里「自动项目命名仍是首页建项前置」的隐含口径。
+
+- 首页「开启创作 / 进入立项策划」的提交链路是「Web 环境预检 → 立即用宿主兜底名创建工作区 → 进入项目 → 首轮创作」。`create_automatic_local_game_project` 不再接收前端命名结果（固定 `name: null`，由宿主生成 `GameAgent 项目 <8 位短 id>` / `策划项目 <8 位短 id>`）：AI 命名请求在建项前并行打出，命名慢、超时、失败或返回非法内容都不影响建项、附件导入与首轮创作。
+- AI 返回合法名称后走新增的条件改名命令 `rename_local_game_project_if_unchanged(projectPath, expectedProjectId, expectedName, name)`：`expectedProjectId` 取自建项返回的 `manifest.projectId`，`expectedName` 是本次创建的兜底名。只有「项目身份一致」且「当前名称仍是兜底名」才落盘改名；用户已手动改名、项目 ID 不符、名称与现状相同都返回 `renamed: false` 并保持现状，空名 / 控制字符 / 超长失败关闭。改名与既有 `rename_local_game_project` 同口径：簿记写入，不推进项目 revision。
+- 改名成功后，当前项目上下文（窗口标题与工作台项目名）与最近项目行的目录重检在「进项目落定」之后写入；AI 结果比进项目更快返回时同样以 AI 名称为准，不被 `enterProjectDevelopment` 的兜底上下文覆盖。
+- 「做方案」不发起自动项目命名请求；手动选择目录建项保持原有行为（沿用目录名，不做 AI 命名）。
+- 自动命名是**项目工作台「生成任务」列表里的一条后台任务**：账本记录用 `taskType`（`asset-generation` / `project-naming`）区分，schema `agc-asset-generation-task.v2`（读取兼容 v1，v1 记录按素材任务读回），`kind` 对命名任务为 null；入队/推进走 `enqueue_local_project_naming_task` / `update_local_project_naming_task`，展示名固定「AI 项目命名」，状态流转「排队中 → 命名中 → 已完成（已应用 AI 名称 / 建议名一致 / 用户已改名跳过）或失败（无可用名称 / 自动改名失败，均保留兜底名）」。命名行的结论只在终态显示，没有缩略图、提示词与「定位到素材」。命名任务由命名链路推进，因此入队要登记 live、终态写盘后摘除，否则任何一次账本读取都会把它按「上次运行中断」误收口为失败；账本只作展示旁路，入队/推进失败只写诊断日志，不影响建项、命名与首轮创作。
+- 回归入口：`npx vitest run apps/ai-game-creator-shell/tests/homeProjectNamingAsync.test.tsx`（时序用 promise 闸门，不用 sleep）、`npx vitest run apps/ai-game-creator-shell/tests/projectNamingGenerationTaskRow.test.tsx`、`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`、`cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute asset_generation_task`、`cargo test --features=… conditional_project_rename_tests`。
+
+
 ## 2026-10-02 退役自建 Agent Runtime 与 CLI 执行面
 
 自建 Agent Runtime（`agent/runtime_driver`、`runtime_protocol`、`runtime_tools`、`runtime_actions`、`runtime_state`、`runtime_adapter`、`agent/prompt.rs`、`agent_native_tools.rs`、`collaboration.rs`、`delegation.rs`、`goal.rs`、`context_compaction.rs`、`isolated_agent.rs`、`tool_plan_handoff/`、`user_input.rs`）与它的 Tauri 命令、`--agent-*` CLI、真实 e2e harness、CI job 一并退役，历史由 Git 保存，见 `docs/adr/【ADR】退役AGC独立Agent Runtime与CLI执行面-2026-10-02.md`。本文正文里所有关于 `--agent-run` / `--agent-task` / `--agent-runner-status` / `agent-run:smoke` / `agent-runtime-real-e2e.mjs`、后台单 Agent 队列、`read_game_creator_agent_runtime(s)`、Supervisor 自主协作与 Goal 生命周期的描述均已失效，不再作为实现依据。外部 Runner（`--agent-runner`）仅保留编辑器桥 RPC 与 `runner.attach_gui_owner` + GUI owner 参与锁 / watchdog。AGC 现役链路以 DirectProject（`agent/direct_*` + codex app-server）、资源工作台与本文其后的 DirectProject 相关条目为准。