评审收口：提权类失败不再重试、重命名路径复用重试、退避预算绑定失败集合
- useRecentProjects：区分可重试失败与提权/权限类失败，后者不再就地重试、也不驱动整表重查，避免自己驱动 UAC 反复弹窗 - useRecentProjects：提权类失败的项目在用户主动打开/新建项目或重命名刷新前跳过检查 - useRecentProjects：退避重查预算绑定到失败集合，集合变化或整轮无失败即重置，长期坏目录不再吃满额度 - useRecentProjects：重命名后的单条刷新复用同一套就地重试与有界重查 - app/tauri：删除重复的 TauriInvoke 类型，统一引用 app/types 的既有定义 - tests/recentProjectsHook：失败不跨轮保留改为断言在途「检查中」，新增提权类失败不重试用例 - docs：decision-log、pitfalls、生命周期方案与异步闭环方案同步失败自愈口径与提权边界
This commit is contained in:
@@ -1,5 +1,12 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-09-23 最近项目检查失败不进终态
|
||||
|
||||
- 背景：最近项目列表把一次性的目录检查失败当成终态——5s 超时被吞成 `null`，增量投影又把上一轮的 `null` 原样搬进下一轮，且没有重试或重查入口。AGC 一次 IPC 停顿之后，整张列表会永久停在「检查失败 + 待识别」，首页「最近项目」同时因 `canOpen` 过滤变空，只能重启客户端恢复（issue #490）。
|
||||
- 决策：单次检查失败先就地重试一次（300ms）；失败结果不进新投影（失败项回到「检查中」并重新检查）；一轮结束仍有**可重试**失败时按 15s / 45s / 120s 重跑整张列表，重跑上限 3 次，失败集合变化或整轮无失败即重置预算；重命名后的单条刷新复用同一套重试与有界重查。
|
||||
- 提权边界：Windows ACL 自动提权类失败（`DACL`、`权限`、`error 5`、`安全对象不属于当前用户`、`特权`、`1300`、`AGC ACL 提权修复未成功`）判定为不可重试——重试等于在用户刚点「否」后再弹一次 UAC（提权闸门只存在于单次 invoke 内，进程级没有冷却记忆）。这类项目在用户再次主动打开/新建项目或重命名刷新之前不再自动重试，也不驱动整表重查。
|
||||
- 验证：`apps/ai-game-creator-shell/tests/recentProjectsHook.test.tsx` 覆盖「单次失败就地重试」「失败不跨轮保留」「提权类失败不重试」（前两者在改前代码上必挂）；`tests/appSurface/home.suite.ts` 的失败态改为等待最终状态；退避重查用一次性脚本验证持续失败后 15s 自动恢复（脚本未入库）。
|
||||
|
||||
## 2026-09-23 AGC 发布前先守可运行原型门禁
|
||||
|
||||
- 背景：客户端已经显示“首个可运行原型尚未完成，运行视图暂不可用”，但发布入口仍会先执行用户项目的 `build`，导致未完成原型也进入构建并在后续失败。
|
||||
@@ -289,7 +296,7 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
|
||||
## 2026-09-20 最近项目检查保持项目级隔离
|
||||
|
||||
- 背景：最近项目刷新会重新检查所有路径。若其中一个目录损坏、超时或不可读，清空整张状态表会让已确认正常的项目暂时全部显示“检查中”，用户只能移除坏项目后看到列表恢复。
|
||||
- 决策：最近项目状态按路径独立投影；刷新时保留仍在列表中的最后一次结果，只有新增或尚未检查的项目进入“检查中”。检查代次或列表成员变化后，迟到结果不得写回，单个项目的失败不能改变其它项目的可打开状态。
|
||||
- 决策：最近项目状态按路径独立投影；刷新时保留仍在列表中的最后一次**成功**结果，失败结果不进新投影并在本轮重新检查（见 2026-09-23 条目），只有新增或尚未检查的项目进入“检查中”。检查代次或列表成员变化后，迟到结果不得写回，单个项目的失败不能改变其它项目的可打开状态。
|
||||
- 验证：`recentProjectsHook.test.tsx` 覆盖“新增慢/坏项目刷新时保留正常项目”；`recentProjectsModel.test.ts`、`unityProjectOpen.test.tsx` 与前端类型检查一并执行。
|
||||
|
||||
## 2026-09-17 GameCreationApp 资源 kind 只保留一份词汇表：严格解析 + `app_log!` 留痕
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# 踩坑与排障记录
|
||||
|
||||
## 最近项目一次失败会被钉成终态
|
||||
|
||||
- **现象**：AGC 卡住一次后，项目列表每一行都显示「检查失败 + 待识别」，首页「最近项目」变成「暂无最近项目」；现场在后端恢复后逐条复跑 `inspect_local_project_directory`（8 个项目）全部 0ms 成功，界面仍然全红（issue #490）。
|
||||
- **原因**：单次检查的 5s 超时被吞成 `null` 写入状态表，而刷新用的增量投影是 `next[path] = current[path] ?? null`，把失败结果原样搬进下一轮；effect 只依赖列表与刷新计数器，既没有重试也没有 focus/visibility 重查。于是一次抖动会让整张列表永久停在失败态，首页同时被 `canOpen` 过滤清空。
|
||||
- **处理**：失败就地重试一次（300ms）；失败结果不进新投影；一轮仍有可重试失败时按 15s / 45s / 120s 重跑整表（上限 3 次，失败集合变化即重置预算）。提权/权限类失败（`DACL`、`权限`、`error 5`、`安全对象不属于当前用户`、`特权`、`1300`、`AGC ACL 提权修复未成功`）按不可重试处理，在用户主动打开/新建项目或重命名刷新之前跳过——否则「提权被拒 → 300ms 后重试」会自己驱动 UAC 反复弹窗。
|
||||
- **验证**：`apps/ai-game-creator-shell/tests/recentProjectsHook.test.tsx` 的三条用例（「单次失败就地重试」「失败不跨轮保留」「提权类失败不重试」），改前代码上前两条必挂；`tests/appSurface/home.suite.ts` 的失败态断言改为等待最终状态。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/useRecentProjects.ts`、`src-tauri/src/config.rs`。
|
||||
|
||||
## 策划 Agent 提示词中的相对路径不要当作内部实现删去
|
||||
|
||||
`project/...` 是 Agent 读写策划工作区的目标路径，`resources/...` 是查找内置分册、模板和例子的资源定位；即使阶段上下文也注入了同一产物路径，提示词里的路径仍是 Agent 需要的契约。清理宿主实现细节时不要误删这些相对路径，具体用法见[策划 Agent 路径说明](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
### RecentProjectInspection
|
||||
|
||||
每个最近项目拥有独立 operation 和结果。检查中、可打开、失败、超时、不存在、非目录、未初始化和可导入不能通过一个全局刷新 gate 互相覆盖。刷新采用增量投影：已确认的项目结果继续保留，只有新增或尚未完成检查的项目显示“检查中”；项目被移除或检查代次变化后，迟到结果不得写回列表。
|
||||
每个最近项目拥有独立 operation 和结果。检查中、可打开、失败、超时、不存在、非目录、未初始化和可导入不能通过一个全局刷新 gate 互相覆盖。刷新采用增量投影：已确认的项目结果继续保留，只有新增或尚未完成检查的项目显示“检查中”；失败结果不进新投影，失败项在本轮重新检查，并在仍有可重试失败时按有界退避重跑整张列表。提权/权限类失败不重试（重试会再次弹 UAC），在用户主动打开/新建项目或重命名刷新前跳过。项目被移除或检查代次变化后，迟到结果不得写回列表。
|
||||
|
||||
### DevStackIdentity
|
||||
|
||||
@@ -88,7 +88,7 @@
|
||||
| --- | --- |
|
||||
| operation identity 与 stale-result | `clientOperation.test.ts`、认证/home 定向测试 |
|
||||
| HTTP/auth/Runner | client HTTP/API 测试、Rust cargo check、认证 appSurface |
|
||||
| 最近项目逐行刷新 | `recentProjectsModel.test.ts`、home appSurface |
|
||||
| 最近项目逐行刷新 | `recentProjectsModel.test.ts`、`recentProjectsHook.test.tsx`、home appSurface |
|
||||
| dev-stack 身份 | `scripts/dev.test.ts`、`start-dev-stack.test.ts`、端口 marker 检查 |
|
||||
| 本地恢复边界 | 现有 manifest/runtime/resource recovery tests；未确认外部副作用不自动重放 |
|
||||
| 超时隔离与迟到结果 | `auth.suite.ts`（stalled native install 不阻塞后续登录、floor 瞬时失败可重试、围栏超时后迟到安装落地）、`home.suite.ts`（建项看门狗解围并保留迟到成功、设计运行时初始化失败后保留工作区并可打开） |
|
||||
|
||||
@@ -24,6 +24,7 @@
|
||||
2. 最近项目逐项独立检查；单项超时/失败只影响该行，已完成且可打开的项目立即可操作。
|
||||
3. 首页自动创建状态由 `WorkspaceLauncher` 生命周期持有；切页期间仍防重，迟到结果不能覆盖用户已打开的其它项目。
|
||||
4. 认证恢复和 Runner 连接继续有明确超时、错误和重试入口；本地 Runner 会话安装/清除的阻塞工作不得占用 Tauri 窗口线程。
|
||||
5. 最近项目检查失败不进终态：单次失败就地重试一次，失败结果不进增量投影并在本轮重新检查；一轮仍有可重试失败时按 15s / 45s / 120s 有界退避重跑整张列表（失败集合变化即重置预算）。提权/权限类失败不重试——重试等同于再次触发 UAC 提权，这类项目在用户主动打开/新建项目或重命名刷新前跳过。
|
||||
|
||||
## 契约与迁移
|
||||
|
||||
@@ -35,6 +36,7 @@
|
||||
| --- | --- | --- |
|
||||
| 响应体超时 | client auth/http 定向测试 | body 卡住抛出稳定超时，第二次 refresh 请求计数为 2 |
|
||||
| 最近项目独立完成 | model/controller 定向测试或 appSurface 场景 | A 完成时可打开，B 继续检查 |
|
||||
| 最近项目失败自愈 | `recentProjectsHook.test.tsx`（单次失败就地重试、失败不跨轮保留、提权类失败不重试） | 一次抖动后整行恢复为可打开；提权被拒时不产生第二次检查（不重复弹 UAC） |
|
||||
| 首页创建跨页防重 | appSurface 场景 | 切页返回后按钮仍禁用，迟到创建不覆盖已有项目 |
|
||||
| Runner 会话不阻塞窗口 | Rust 编译检查与登录/退出 UI fence | command 使用 blocking worker，前端使用 45 秒可恢复超时 |
|
||||
| 现有行为不回归 | typecheck、AGC 定向测试、编码和 diff 检查 | 命令输出 |
|
||||
|
||||
Reference in New Issue
Block a user