Merge remote-tracking branch 'origin/master' into feat/fail-as-event

# Conflicts: # docs/project-memory/shared-memory/decision-log.md
2026-09-24 19:17:48 +08:00
parent 7cb7bd9581 96b0fada3a
commit 2fa89006c4
30 changed files with 1745 additions and 117 deletions
@@ -1,5 +1,15 @@
 # 踩坑与排障记录

+## 同一祖先下的多个项目会各自弹一次 UAC
+
+- **现象**：AGC 启动页一次挂载出现多个叠在一起的 UAC 提权弹窗；用户点「否」后仍会被再问一次。
+- **原因**：`windows_acl_repair_target`（`src-tauri/src/config.rs`）对 Managed 作用域返回「第一个读取被拒的祖先」——同一祖先下的多个项目解析到**同一个** repair target；而唯一的去重是单次调用内的局部 `attempted_targets`，跨调用、跨线程都没有记忆。启动页一次并发检查 ≤8 个最近项目，就会并发启动同样多次 `powershell -Verb RunAs`。
+- **处理**：进程级 single-flight（key = `(规范化 repair target, scope)`）+ 结果冷却（成功 30s / 失败 15s / 用户取消 120s）+ 等待窗口 60s 超时按失败关闭；leader 异常退出由 RAII 兜底唤醒等待者。用户取消带稳定标记 `AGC_ACL_ELEVATION_DENIED`，前端据此不自动重试；用户主动操作会清除拒绝记忆。
+- **不要踩的坑**：① 闸门 key 必须归一化 `\\?\` / `\\?\UNC\` 前缀——最近项目列表里同一项目实测同时存在 `\\?\C:\...` 与 `C:\...` 两种写法，按原始字符串做 key 会让同一个目录弹两次 UAC（`windows_acl_repair_gate_key`）；② 冷却必须从**结果落库**时刻算起，用 leader 起跑时刻会让 120s 拒绝冷却在 UAC 被挂着两分钟时提前过期，紧接着的自动重查立刻再弹一次；③ 复现「多个项目共用同一 target」时，DENY 要写在祖先的**父目录**上靠继承落入祖先——`icacls` 直接加在容器自身实测只影响子项（容器自身 `GetFileAttributes` 仍成功），target 会退化成每个项目自己，repro 不出并发弹窗；④ 夹具路径必须落在 `game_creator_private_path_allows_auto_elevation` 放行范围内（runtime config dir / `.config/genarrative` / 打包 AppData / 带 `.agent/manifest.json` 的项目根），因为提权子进程会按 **repair target** 再校验一次 `scope.allows_path`，否则失败关闭。
+- **验证**：`src-tauri/src/tests/acl_repair_gate.rs`（并发只执行一次、冷却复用、拒绝冷却、清除后可重试、follower 超时、leader panic 唤醒等待者、冷却基准、路径写法归一、leader 卡死接管与迟到结果丢弃）。真机复现（无需提权交互即可计数）：在 Managed 放行范围内建 8 个带 `.agent/manifest.json` 的假项目 → 对共同祖先的**父目录** `icacls <父目录> /deny *<sid>:(OI)(CI)(RX)` → 挂载启动页，同时数 `powershell.exe` 里命令行带 `RunAs` 的进程数（`Start-Process -Wait` 会让它一直存活到用户应答）与 `consent.exe` 峰值：修复前 8 个并发请求，修复后 1 个；把同一目录的 `\\?\C:\...` 与 `C:\...` 两种写法一起塞进最近项目，还能验证 key 归一化是否生效（修复前 2 个、修复后 1 个）。
+- **leader 卡死的兜底**：闸门只有 follower 的有界等待（60s），若提权子进程真的挂死（`Start-Process -Wait` 无超时），`leader_deadline`（5 分钟）之前该 key 一直被占住，之后新调用会接管并按新 leader 执行；被接管后旧 leader 迟到的结果按令牌丢弃，不会覆盖接管者。`clear_game_creator_acl_elevation_denials` 只清「被拒绝」记忆，不清理 running。
+- **关联**：`src-tauri/src/acl_repair_gate.rs`、`src-tauri/src/config.rs`、issue #498。
+
 > 策划历史条目边界：旧策划 V1/V2 已全部退役，当前入口仅使用 Design Agent。下文带日期的旧 Planning V2、Fast GDD、`plan.submit_gdd`、旧 IPC/模块记录仅用于追溯，不能作为恢复旧代码、身份门禁或专属测试的依据；共享问题需在现役调用上核查。现行合同见[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。

 ## 2026-09-24 模型输出的围栏会粘在正文行里：聊天 Markdown 必须先归一化再解析