合并：把 master 的告警清理与首页对话退役并进接单化分支

- 冲突 codex_app_server/mod.rs：保留类型化回合失败 DirectTurnRunFailure 与 EnvironmentNotReady 分类，接受删除 audit/metrics 参数
- 冲突 direct_runtime/mod.rs：保留类型化错误反馈循环与"交付报告只读一次"，保留 check_direct_turn_preconditions，接受 master 的 turn_kind 贯穿与首页无项目对话退役
- 冲突 direct_runtime/user_input.rs：保留接单后发射器与 canonical 用户条目的新调用签名
- 删除：随 master 移除 direct_codex_audit、direct_turn_metrics 两个账本模块及其全部引用
- 删除：direct_codex_error_should_feedback 字符串判据与首页对话函数及其测试
- 调整：direct_codex_error_feedback_prompt 收成单参数，与已落地的提示词模板一致
- 修复：master 新插入的用户条目冻结块改用 DirectTurnError::turn_failed

docs/project-memory/shared-memory/development-workflow.md

@@ -53,6 +53,8 @@
 
 ## 验证路由
 
+Windows 下的移动壳 smoke 通过 Node 启动从当前 workspace 包解析出的 Expo/EAS CLI，不直接 `spawnSync('npm.cmd')`；保留原配置与导出断言。具体入口和警告清理边界见本地开发运维文档。
+
 提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。
 
 提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。

docs/project-memory/shared-memory/document-map.md

@@ -1,6 +1,6 @@
 # 文档地图与阅读索引
 
-更新时间：`2026-08-31`
+更新时间：`2026-09-23`
 
 ## 阅读顺序
 
@@ -24,16 +24,16 @@
 AI 游戏创作 / DirectProject / UI workflow：
 
 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
-2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`（历史方案，仅供追溯）
+2. `docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md`（当前 Design Agent；旧策划 V1/V2 均已退役）
 3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
 5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（历史 V1 方案，仅供追溯）
 6. `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`
 7. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 8. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
-9. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`
-10. `docs/technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md`
-11. `docs/technical/【技术方案】Direct回合行为审计账本-2026-08-31.md`
+9. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`（历史 V2 方案，仅供追溯，不是当前实现依据）
+10. DirectProject 附件按 AGC 主实施计划的 canonical `userItem` 合同；`docs/technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md` 为旧 sidecar 历史方案，不作为实现入口。
+11. Direct 历史、审计与耗时按 AGC 实施计划及原始历史专题；`docs/technical/【技术方案】Direct回合行为审计账本-2026-08-31.md` 已归历史，不作为实现入口。
 12. `docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`
 13. `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`
 14. UI 编辑器、宿主壳和当前测试专题文档

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

@@ -1,5 +1,43 @@
 # 踩坑与排障记录
 
+> 策划历史条目边界：旧策划 V1/V2 已全部退役，当前入口仅使用 Design Agent。下文带日期的旧 Planning V2、Fast GDD、`plan.submit_gdd`、旧 IPC/模块记录仅用于追溯，不能作为恢复旧代码、身份门禁或专属测试的依据；共享问题需在现役调用上核查。现行合同见[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
+
+## 2026-09-24 对话过程卡的读秒退回 1 秒一跳：刷新粒度必须与显示精度同格
+
+- **现象**：AGC DirectProject 对话区底部那条「陶泥儿正在处理 / 已耗时 12.4秒」的状态条，小数位一秒才动一格，看着像读数卡住；同一屏里工具卡片的耗时与资源生成侧栏的读秒都在正常走 0.1 秒，只有这一处不动。
+- **原因**：耗时文案不足一分钟保留一位小数（`formatElapsedDuration`），刷新就必须是 100ms。这次改动方向本身是对的——把 clock 从整个聊天视图下移到耗时那一行，但顺手在组件里另写了一份 `setInterval(..., 1000)`，绕过了对话侧唯一的 `useLiveNow`（`LIVE_TIMER_TICK_MS = 100`）；`team-conventions.md` 里「运行时用 100ms 叶子时钟刷新一位小数、终态冻结」这条约定当时已经写好，改动没有对齐它。
+- **处理（现行口径）**：耗时文案的刷新一律走 `useLiveNow`，不在视图组件里另起 interval；tick 只订在显示耗时的那一行（叶子节点），不能落在整块面板或整份回合列表上。可机检的判据是「不足一分钟的耗时必须每 100ms 递增一次小数位」。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/directProjectProcessStatus.test.tsx`（把 `LIVE_TIMER_TICK_MS` 临时改回 1000 时第一步即红）；真实浏览器里 600ms 内文案从 `18.0秒` 走到 `18.6秒`。
+- **关联**：`apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx`、`apps/ai-game-creator-shell/src/features/project-workspace/useLiveNow.ts`、`apps/ai-game-creator-shell/src/styles.css`。
+
+## 策划回复的重复终态不能重新启动伪流式
+
+策划 Runtime 会通过状态事件与命令返回交付同一份最终视图。若前端清空临时正文后再拿“最后一条非用户历史消息”回填动画，就会出现正式回复旁又播放一遍、播放后消失的假重试。正文应按 `messageId` 保存显示进度，与正式消息共用一个气泡；请求完成不清动画，不延迟正式业务状态。Provider 自动重试复用消息 ID 并发送空文本，只允许重置未持久化的该条回复。正文、工具状态和 reasoning 分开；事件与异步命令收尾均检查项目及活动回合，旧请求不能覆盖新回合。详见 [AGC 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
+
+## 2026-09-23 弹窗打开时自绘标题栏的最小化 / 最大化 / 关闭静默失效
+
+- **现象**：AGC 打开「发布到游戏广场」面板（以及其它任何弹窗）后，右上角三个窗口按钮点了没有任何反应，拖拽标题栏也不能移动窗口；关掉弹窗立刻恢复。标题栏看着完全正常，遮罩也明显只压住了下面的工作区，所以很容易误判成「按钮自己坏了」或 Tauri 窗口 API 挂了。
+- **原因**：标题栏在模态之外，但它是窗口边框。`ThemedModal` 用的 `focus-trap-react` 在 **document 捕获阶段**监听 `mousedown`/`touchstart`/`click`：模态外的点击一律 `preventDefault()`，`click` 还会 `stopImmediatePropagation()`。React 的监听挂在 document 内的根容器上，捕获阶段就被掐掉的 `click` 永远到不了 React，于是既不报错也不执行 —— 与「焦点陷阱吞掉模态外点击」是同一类问题（见 2026-09-20 发布面板焦点陷阱那条）。另有一条独立的同类缺陷：`.app-update-overlay` 用 `inset: 0`，把标题栏真的盖住了，更新弹窗期间按钮被遮罩挡住。
+- **处理（现行口径）**：① 全屏弹层一律从标题栏下方开始（`top: var(--window-chrome-height)`），不得用 `inset: 0` 盖住标题栏；② `ThemedModal` 的焦点陷阱用 `allowOutsideClick` 只放行落在 `[data-window-chrome-bar]` 内的目标，工作区内容点击继续被拦；③ 新增全屏弹层时把类名补进 `apps/ai-game-creator-shell/tests/windowChromeOverlayContract.test.ts` 的清单。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/themedModal.test.tsx apps/ai-game-creator-shell/tests/WindowChrome.test.tsx apps/ai-game-creator-shell/tests/windowChromeOverlayContract.test.ts`（标题栏点击放行、工作区点击仍被拦、7 个全屏弹层都在标题栏下方）；两个新增用例去掉修复后确实失败，确认能守住这条约定。
+- **关联**：`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/styles.css`。
+
+## Direct 宿主继续请求不能重发原始用户条目
+
+原始 `direct_user_item` 同时参与历史持久化和模型输入转换；验收或错误反馈更新了 prompt 后，如果发送层仍优先转换原始条目，模型会收到重复的用户输入，而本地历史按 itemId 去重后只显示一次。首次请求与宿主继续必须显式区分：首次保留结构化输入，继续发送当次反馈，原始条目只保留历史与事件关联职责。GUI、CLI 的两条循环都要覆盖；只改反馈文本或清空原始条目不完整。见 [Direct 宿主继续请求输入修复](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-09-23-direct-宿主继续请求输入修复)。
+
+## 最近项目一次失败会被钉成终态
+
+- **现象**：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-阶段与提示词注入)。
+
 ## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查
 
 - **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。
@@ -825,6 +863,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 并发边界：steer 入队、Runner `runtime.steer` 通知都不得直接触发 Provider interrupt。Codex app-server 的判定使用独立节点，不能等待主节点 turn 锁；判定为 true 后也只能中断 `appliedSteerCursor < steer.sequence` 的旧 Provider 请求，已经消费该 steer 后启动的新请求不可被误杀。已经开始的工具和外部动作不强杀，完成 observation 后再消费 steer。
 - 验证：真实 mock LLM 回归必须覆盖状态询问回复且 `interruptCurrentProvider=false`；持久重放只保留一条语义回复；steer 入队后旧 Provider 继续运行，判定为 true 后才中断；新规划 Provider 的 cursor 已包含该 steer 时即使旧判定为 true 也不能中断。前端同秒多条消息保持“用户补充 → 判断提示/语义回复”的关联顺序。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/interaction.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/runner/dispatch.rs`、`apps/ai-game-creator-shell/src/features/agent-runtime/model.ts`。
+- 2026-09-23 更新：`agent/interaction.rs` 与 `steer-decision` LLM 判定链已整体删除，本条中「判定 LLM / `interruptCurrentProvider` / 只中断旧 cursor」的实现细节仅作历史记录；现役语义是 steer durable 入队后由 `runtime.steer` 唤醒，并在下一安全边界应用。
 
 ## Jenkins 异步备份不能用 nohup 脱离作业
 
@@ -4431,9 +4470,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - 现象：`npm run agc:test:chat` 在进入聊天前报“Agent Runner 版本与当前客户端不一致，但旧 Runner 仍有任务，暂不能重启”；正式客户端仍能看到自己的待确认或委派任务，重复执行测试也持续失败。
 - 原因：Runner 复用身份同时绑定协议版本和当前可执行文件 SHA-256。`cargo run` 重新编译后的 debug 二进制与正在运行的 release Runner 指纹不同，而旧入口只隔离测试项目、仍把正式 AppData 直接传给 CLI，于是测试会向正式 endpoint 发升级探测。正式 Runner 有 pending action、Provider sidecar、进程会话或非终态队列时拒绝退出是正确的安全门禁，不能通过强退或放宽 idle 判定让测试通过。
-- 处理：正式 AppData 只作只读配置来源。每次人工测试在系统临时根创建 `0700` sentinel 隔离目录，只把主配置和可选 local overlay 私有复制为 `0600` 普通文件；不得复制 endpoint、lock、`.previous` 或其它状态。LLM 检查与 Swarm CLI 全部使用隔离目录。退出时通过内部 CLI 请求 `runner.shutdown_if_idle`，确认隔离 endpoint 消失后才删除配置；仍有任务或无法确认退出时同时保留测试项目和隔离配置并报告路径。正式 Runner 的 PID、bootId、端口和 executable fingerprint 必须保持不变。
+- 处理：正式 AppData 只作只读配置来源。每次人工测试在系统临时根创建 `0700` sentinel 隔离目录，只把主配置和可选 local overlay 私有复制为 `0600` 普通文件；不得复制 endpoint、lock、`.previous` 或其它状态。LLM 检查与端到端测试入口全部使用隔离目录。退出时通过内部 CLI 请求 `runner.shutdown_if_idle`，确认隔离 endpoint 消失后才删除配置；仍有任务或无法确认退出时同时保留测试项目和隔离配置并报告路径。正式 Runner 的 PID、bootId、端口和 executable fingerprint 必须保持不变。
 - 验证：单元测试覆盖私有 inode、权限、local overlay、禁止复制 endpoint/lock/备份、符号链接拒绝、sentinel 清理和 endpoint 存在时拒绝删除；真实 smoke 使用隔离 AppData 启动并收束空闲 Runner，前后比较正式 endpoint 身份且确认正式 PID 存活，再检查本轮 `/tmp` 项目和隔离配置均已清理。
-- 关联：`apps/ai-game-creator-shell/scripts/agent-swarm-test-chat.mjs`、`apps/ai-game-creator-shell/tests/agentSwarmTestEntry.test.ts`、`apps/ai-game-creator-shell/src-tauri/src/runner/client.rs`、`apps/ai-game-creator-shell/src-tauri/src/cli.rs`。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/runner/client.rs`、`apps/ai-game-creator-shell/src-tauri/src/cli.rs`。
 
 ## Swarm 队列 busy 不能直接当成 canonical run 可 steer
 
@@ -4441,7 +4480,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 原因：旧 `runtime_is_busy` 同时包含当前 state 和队列汇总，调用方看到 `task_queue.pending > 0` 后仍从 canonical state 反推 steer、失败扫描和 turn report 的 runId；取消 tombstone 还会让恢复扫描在处理 A 后无条件跳过 B。底层拒绝 terminal steer 和保留 A 的真实失败历史都是正确行为，不能通过放宽门禁或删除历史记录修复。
 - 处理：保留 queue busy 用于 Runner 存活判断，另由 Runtime 协议层提供唯一 steerable 判定。start mutation 返回实际 `acceptedRunId`，CLI 以它建立不可变 turn baseline；失败、reconciliation、用户交互、收束和报告只观察该 run。canonical 已推进到后续 run 时从 task journal 读取目标 run 的最终记录。旧 cancelled canonical 若仍有 pending 且无 running，恢复扫描跳过旧 run 的 pending action 恢复，直接启动队首 pending。若输入与已落盘 pending task 及最后一条 user 消息相同，则只观察原 run。Goal 路径也必须核对同一 Agent、Session、runId、Run Profile 和 steerable 状态。连续 run 的回复必须按确定性 finalization message ID 过滤；历史 specialist 失败必须以 `(agentId, runId)` 为键读取完整 journal，不能让滞后的非失败 state 删除 journal 已记录的失败；报告计数也不能退回 `recent_tasks` 的 12 条窗口。
 - 验证：构造 cancelled run A、保留 A cancel tombstone、pending run B 和单份已落盘用户消息，证明恢复后 B 进入 running 并完成且 conversation 不重复。另覆盖观察 B 时忽略 A 及 A 子任务失败、观察 A 时仍正常失败、B 完成后 canonical 已推进到 C 仍可从 journal 收束 B、`turn.report.parentRunId` 始终为 baseline，以及 expected Goal runId 不一致时不选中目标。
-- 关联：`apps/ai-game-creator-shell/src-tauri/src/swarm_cli/turn_dispatch.rs`、`apps/ai-game-creator-shell/src-tauri/src/swarm_cli/terminal_classification.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs`。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs`。
 
 ## 2026-07-25 autonomous-game-build 不能只检查 game/index.html 就宣称正式项目完成
 
@@ -4456,9 +4495,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 ## 终端真实测试不能混用配置参数、stdin EOF 和持续预览
 
-- 现象：开发者第一次运行 `agc:test:chat` 时必须先打开 GUI 才能配置 Provider；无 TTY 的脚本可能在 stdin 立即 EOF 后零任务成功退出，或者任务已经完成却继续等待 preview 的 `Ctrl+C`，导致自动化看似卡死。若为图省事增加 `--api-key`，密钥还会进入 shell history 和进程列表。
+- 现象：开发者第一次运行真实 E2E 聊天测试时必须先打开 GUI 才能配置 Provider；无 TTY 的脚本可能在 stdin 立即 EOF 后零任务成功退出，或者任务已经完成却继续等待 preview 的 `Ctrl+C`，导致自动化看似卡死。若为图省事增加 `--api-key`，密钥还会进入 shell history 和进程列表。
 - 原因：把首次配置、手工多轮聊天、单轮真实测试和持续试玩当成同一个交互生命周期；同时让 GUI 与 CLI 使用不同配置入口，或把 EOF 既解释为“提交当前需求”又解释为“没有输入”，会让退出语义随调用环境漂移。
-- 处理：GUI 与 `npm run agc:config` 共用系统 AppData `game-creator.config.json`，终端隐藏输入 API Key 并禁止 `--api-key`；更新时保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置，POSIX 权限维持目录 `0700` / 文件 `0600` 并原子替换。显式 `--config-dir` 必须以 `world.genarrative.ai-game-creator` 为独立叶目录，不能让向导对 `/tmp`、AppData 根或共享目录整体 chmod / 重建 DACL。隐藏输入调用 `stdin.resume()` 后必须记住原 pause 状态，在成功、取消、异常和 `SIGINT / SIGTERM / SIGHUP` 路径恢复 raw mode 并 `pause()`，信号恢复后重发；只移除 `data` listener 会让 `--configure-only`、配置检查失败或 Ctrl+C 保持活动 stdin。缺配置时仅 TTY 人工会话可询问进入向导，非 TTY 立即失败并提示配置命令。
+- 处理：GUI 与 `npm run agc:config` 共用系统 AppData `game-creator.config.json`，终端隐藏输入 API Key 并禁止 `--api-key`；更新时保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置，POSIX 权限维持目录 `0700` / 文件 `0600` 并原子替换。显式 `--config-dir` 必须以 `world.genarrative.ai-game-creator` 为独立叶目录，不能让向导对 `/tmp`、AppData 根或共享目录整体 chmod / 重建 DACL。隐藏输入调用 `stdin.resume()` 后必须记住原 pause 状态，在成功、取消、异常和 `SIGINT / SIGTERM / SIGHUP` 路径恢复 raw mode 并 `pause()`，信号恢复后重发；只移除 `data` listener 会让 配置检查失败或 Ctrl+C 保持活动 stdin。缺配置时仅 TTY 人工会话可询问进入向导，非 TTY 立即失败并提示配置命令。
 - Windows 密钥复制：`mode: 0o600` 和 POSIX `chmod` 在 Windows 上不能代替 DACL。隔离 AppData 目录必须先设置仅当前用户、禁止继承的 DACL；目标配置文件先以空文件创建并收紧 DACL，之后才允许把 API Key 字节写入。先 `copyFile` 再依赖 Rust 只读检查或事后收紧会留下密钥暴露窗口，也可能因继承 ACL 不满足 Runtime 合同而在首次 `--llm-status` 失败。
 - Windows PowerShell 参数：不要把 DACL 目标路径和目录标记直接追加在 `powershell.exe -Command <script>` 后；Windows Node `spawn` 会让 PowerShell 5.1 把这些值拼入命令文本，带空格的临时路径会被拆分并使 `GetFullPath($args[0])` 失败。当前实现只通过子进程私有环境变量传入路径和布尔值，并由真实 Windows `npm run agc:typecheck` 覆盖 DACL 回归。
 - 测试超时补充：配置向导的读路径和写路径都会加固私有目录与配置文件，`readGameCreatorWizardConfigState` 与 `writeGameCreatorConfigAtomically` 只要没拿到 `secureWindowsPath` 桩，Windows 上每次调用就各自拉起真实 `powershell.exe`（本机实测约 `0.6s` / 次）。只给写路径传桩、漏掉读路径时，单条用例会累计 `9` 次加固、耗时约 `5.5s`，稳定撞上 vitest 默认 `5000ms` 上限并报 `Test timed out in 5000ms`（不是断言失败）。凡只校验配置分层优先级、不校验 ACL 的用例，读写路径必须带上同一份 `skippedWindowsAclOptions` 桩，把用例耗时从秒级压回 `24ms` 量级；确实要覆盖私有 ACL 的用例才保留真实加固，并自行留足超时预算。隔离 Swarm 运行配置的入口 `prepareSwarmTestRuntimeConfig` 按同一范式暴露了可选第三参 `{ secureWindowsPath }`，默认 `null` 时仍走真实实现，生产调用点保持单参调用；一次调用在双配置文件场景最多加固 3 次，不传桩时同样会稳定吃掉秒级预算。
@@ -4516,7 +4555,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 ## tool-plan handoff 不能把计划叙述和源码字段当成配置载荷扫描
 
-- 现象：Provider 已返回 HTTP 200 并计费，tool-plan lifecycle 却只有 `started`，handoff 账本停在上一 loop，Runtime 进入 `needs-reconciliation`；重启 Runner 或 `/resume` 后仍原样被屏障阻断。
+- 现象：Provider 已返回 HTTP 200 并计费，tool-plan lifecycle 却只有 `started`，handoff 账本停在上一 loop，Runtime 进入 `needs-reconciliation`；重启 Runner 或运行显式恢复（`--agent-resume`）后仍原样被屏障阻断。
 - 原因：在解析 function arguments 之前，对整段 `response.text` 和序列化 arguments 统一执行 `.env`、`game-creator.config` 等字面标记扫描。安全叙述如“无需读取 `.env`”，或 `oldText / newText / content / patch` 中的普通源码字面量，会在真实路径和内容字段尚未区分时被误判。原始响应未成功交接时不会留下正文，因此现场只能结合 loop 边界和最小复现定位，不能把高概率分支冒充已恢复的原响应证据。
 - 处理：计划叙述与规范源码内容字段只检查真实密钥 token 形状、凭据头标记和不安全控制字符；结构化敏感 JSON key、非内容字段的配置痕迹和绝对路径、真实 token、容量、thinking、身份、顺序及账本完整性继续失败关闭。成功 handoff 失败时只在 Runtime event/state 和 Agent DB 保存受控 `failureKind`、脱敏错误 SHA-256、字符数与 requestId，禁止保存正文、arguments、密钥和绝对路径。
 - 验证：必须同时覆盖 narrative 和 `oldText / newText / content / html / patch` 提及 `.env` / `game-creator.config` 可 round-trip，`path=.env.local` 与 `sk-...` 真实 token 仍拒绝，全部 handoff 回归通过；诊断审计必须断言不存在 `error / response / arguments` 原文。修复后的外部 Provider 重试仍需新起独立轮次，不能与故障轮或确定性回归拼接为 PASS。
@@ -4524,10 +4563,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 ## 自然语言“继续修复”不能在无活动 Runtime 时落入空 resume
 
-- 现象：旧 run 已取消且 `/resume` 明确报告无可恢复任务，用户随后输入“继续”“继续之前干的事情”或“那就继续修复”，interaction 仍返回 `resume`，宿主反复扫描后不新建任务。
-- 原因：interaction 模型能看到会话历史，却不知道宿主已经排除了 active、pending 和可 steer Runtime；宿主又把自然语言 `resume` 与显式 `/resume` 当成相同控制动作机械执行。
-- 处理：活动 Runtime、排队任务和 Goal 仍在 interaction 前优先 steer/恢复；只有这些门禁全部为空后，自然语言 interaction 返回的 `resume` 才规范化为 `execute` 并创建新 run。显式 `/resume` 继续保持纯恢复控制，不因无任务而隐式执行。
-- 验证：保留自然语言必须进入统一 interaction loop 与显式 `/resume` 命令测试，并新增无活动 Runtime 时 `Resume -> Execute`、普通 reply 不变的回归。
+- 现象：旧 run 已取消且显式恢复入口明确报告无可恢复任务，用户随后输入“继续”“继续之前干的事情”或“那就继续修复”，interaction 仍返回 `resume`，宿主反复扫描后不新建任务。
+- 原因：interaction 模型能看到会话历史，却不知道宿主已经排除了 active、pending 和可 steer Runtime；宿主又把自然语言 `resume` 与显式恢复入口当成相同控制动作机械执行。
+- 处理：活动 Runtime、排队任务和 Goal 仍在 interaction 前优先 steer/恢复；只有这些门禁全部为空后，自然语言 interaction 返回的 `resume` 才规范化为 `execute` 并创建新 run。显式恢复入口（`--agent-resume`）继续保持纯恢复控制，不因无任务而隐式执行。
+- 验证：保留自然语言必须进入统一 interaction loop 与显式恢复入口测试，并新增无活动 Runtime 时 `Resume -> Execute`、普通 reply 不变的回归。
 
 ## tool-plan 中项目内绝对路径应在成功交接时规范化
 
@@ -5269,11 +5308,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - 现象：用户明确要求重做美术或切换游戏主题，工具仍立即返回 `assets/art-spec.png`、`assets/direct-game-background.png`、`assets/art-spritesheet.png`；新需求没有 Provider operation，游戏继续使用旧图。切片虽然已经落盘，也可能不出现在资源管理或工具结果中。
 - 原因：旧 Direct 工具只有 `brief`，完整包校验成功后无条件短路；固定阶段账本恢复又未比较本次生成 prompt。切片只写文件和切片清单，未作为顶层 manifest asset 投影；工具桥只返回三条主路径并丢失切片与 warning。
-- 处理：显式重做使用 `mode=regenerate`，普通请求使用 `reuse-or-create`。重生成必须由当前最新 User 消息明确授权并绑定客户端稳定 `clientTurnId`。授权先对完整原文做 Unicode NFKC 与撇号规范化，随后整串必须完整匹配审核过的独立立即执行指令，只允许句号/感叹号收尾；不得剥离引号、方括号或代码片段，动作前后也不得携带 brief、条件、否定、选择、确认、费用、延迟或其它文本。风格需求先单独描述，再由下一条独立“请重新生成美术”消息确认；不要靠扩充 deny 同义词推断付费同意。同一调用完成回包丢失只从 `completed` 持久结果等值重放，不能因重试再次扣费。App 必须在 Direct 调用前落盘原始 User 消息和回合 ID，Tauri 必须在成功返回前幂等落盘同 ID assistant 终态；同进程重复水合若命中“回合仍在运行”，只能显示瞬时占用提示，不得以稳定 assistant messageId 写成终态并抢占原执行的成功回复。恢复扫描与启动前置恢复必须发现 `resetting / compensating / anchored in-progress` 并在专用锁内恢复，重开项目只续跑真正未回答的原身份。整条付费链必须持有专用跨进程执行锁；换新回合时先持久化 `resetting` 再清理旧阶段账本，不得通过删除 workflow 留出无主窗口。崩溃补偿只恢复旧文件并清 replacement CAS 锚点，已 `prepared / accepted` 阶段账本、原 `Idempotency-Key / operationId` 必须保留，同冻结意图续跑复用旧请求；未知账本在文件 mutation 前失败关闭。只有没有任何阶段账本和替换锚点的孤立 workflow 空壳可原子接管；旧 schema 和其余冲突失败关闭。遇到 prompt 或当前 art-spec 身份不一致的未决账本必须保留原 operation 并返回对账错误。Direct app-server 可写边界只限真实 canonical `game/`，canonical 项目根的原生 OS 路径字节与权威 manifest `projectId` 经域标签和独立长度前缀编码后共同绑定连接池和 thread 身份，不得写项目根、`assets/`、`.agent/`，也不得获得网络、命令、MCP 或权限扩权；受控工具如果需要项目级客户端状态，只能从同一真实 `game/` cwd 经相同校验内部反查项目根，不能扩大模型可写根。标准图集首次创建和重生成都要求四张透明、可见、像素及平台身份唯一的 canonical 切片；工具只回传通过私有回执、公开清单、源图和顶层登记交叉验证的 `slicePaths` 与安全 `resources`。部分/opaque/重复/缺回执切片必须告警，不能把公开清单或顶层自述身份当作 Canvas 权威。
+- 处理：显式重做使用 `mode=regenerate`，普通请求使用 `reuse-or-create`。模式由 Codex 根据当前用户请求通过审核工具显式选择；客户端不再使用 Unicode NFKC、关键词、否定词表或独立确认句式判断业务意图。旧文本授权规则已被 2026-09-03 MCP 决策替代，相关无调用实现于 2026-09-23 删除。工具桥绑定活动客户端回合与稳定 `clientTurnId`，冻结首次 `brief` 摘要；缺少活动回合或摘要冲突仍拒绝。项目权限、账号、计费、幂等、锁与未知结果恢复合同继续有效。
+- 幂等与恢复：同一调用完成回包丢失只从 `completed` 持久结果等值重放，不能因重试再次扣费。App 必须在 Direct 调用前落盘原始 User 消息和回合 ID，Tauri 必须在成功返回前幂等落盘同 ID assistant 终态；同进程重复水合若命中“回合仍在运行”，只能显示瞬时占用提示，不得以稳定 assistant messageId 写成终态并抢占原执行的成功回复。恢复扫描与启动前置恢复必须发现 `resetting / compensating / anchored in-progress` 并在专用锁内恢复，重开项目只续跑真正未回答的原身份。整条付费链必须持有专用跨进程执行锁；换新回合时先持久化 `resetting` 再清理旧阶段账本，不得通过删除 workflow 留出无主窗口。崩溃补偿只恢复旧文件并清 replacement CAS 锚点，已 `prepared / accepted` 阶段账本、原 `Idempotency-Key / operationId` 必须保留，同冻结意图续跑复用旧请求；未知账本在文件 mutation 前失败关闭。只有没有任何阶段账本和替换锚点的孤立 workflow 空壳可原子接管；旧 schema 和其余冲突失败关闭。遇到 prompt 或当前 art-spec 身份不一致的未决账本必须保留原 operation 并返回对账错误。
+- 执行边界（2026-09-24 校准）：DirectProject 的 cwd 与 AGC 业务身份根是用户选择的 canonical 项目根；其原生 OS 路径字节与权威 manifest `projectId` 经域标签和独立长度前缀编码后绑定连接池和 thread 身份。旧的 `game/` 唯一可写根、禁止全部网络 / 命令 / MCP 的描述已失效；也不能把后来的“完整访问”描述理解为绕过当前宿主门禁。当前 thread 使用 `sandbox=read-only`、`approvalPolicy=untrusted`，turn 使用 `sandboxPolicy.type=readOnly`；原生命令按逐次审批与宿主执行许可处理，客户端 MCP 仍校验项目绑定、业务权限和副作用许可。具体边界以[主实施计划“宿主验收与执行许可合同”](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#宿主验收与执行许可合同)及当前实现为准，Provider 凭据保持隔离。
+- 资源投影：标准图集首次创建和重生成都要求四张透明、可见、像素及平台身份唯一的 canonical 切片；工具只回传通过私有回执、公开清单、源图和顶层登记交叉验证的 `slicePaths` 与安全 `resources`。部分/opaque/重复/缺回执切片必须告警，不能把公开清单或顶层自述身份当作 Canvas 权威。
 - 同进程恢复补充：命中“同一 stable turn 仍在运行”后除禁止写 assistant 终态外，还必须删除当前 App 实例的恢复 claim。这样原调用随后成功时显式刷新能读取其终态，随后失败时也能按相同 `clientTurnId` 再次续跑；不要靠重载 WebView 清理进程内 claim，也不要用无界定时轮询制造并发调用。
 - 严格图集崩溃补充：规范图和背景图的两文件 rollback 不覆盖严格图集事务已经整体修改的 `.agent/manifest.json`、私有回执、公开清单、主图集、四切片和切片清单。必须在严格调用前持久化 pending 及九项旧合同身份；重启恢复先对账底层严格事务，完整新合同直接收口完成，完整旧合同才补偿前两阶段，混合或漂移状态失败关闭。不要在严格提交成功后局部恢复前两张图。
 - 部分旧包补充：rollback 的规范图/背景图必须保存旧字节与旧 manifest entry，不能把这两项缺失隐式当成空内容；显式 `regenerate` 因此只在这两项可信可回滚时开放。历史主图集、私有回执、公开清单或 canonical 切片可以缺失，但八个严格路径与受管顶层 asset identity 必须逐项冻结其真实 `Present/Some` 或 `Missing/None` 状态，补偿也必须恢复相同存在性。不要因为旧美术包缺切片而阻断重生成，也不要把本轮新建的严格文件误记成旧文件。
-- 对话扫描与 claim 补充：历史中出现 `User A / User B / Assistant B` 时，B 已回答不代表 A 已回答，扫描必须继续寻找 A。成功 Direct 回复在 Rust 返回前已经落盘，前端冗余 append 失败不能据此重跑；普通错误回复的显式落盘失败时，恢复 claim 要保持到 React fallback writer 的同一 messageId append 明确收敛。writer 成功或明确失败后才释放；失败路径要停止该消息的自动迟到重试，再由显式 `/history` 复用原 stable turn。终态后及时删除 claim，避免 Set 无界增长。
+- 对话扫描与 claim 补充：历史中出现 `User A / User B / Assistant B` 时，B 已回答不代表 A 已回答，扫描必须继续寻找 A。成功 Direct 回复在 Rust 返回前已经落盘，前端冗余 append 失败不能据此重跑；普通错误回复的显式落盘失败时，恢复 claim 要保持到 React fallback writer 的同一 messageId append 明确收敛。writer 成功或明确失败后才释放；失败路径要停止该消息的自动迟到重试，再由显式重新加载对话复用原 stable turn。终态后及时删除 claim，避免 Set 无界增长。
 
 ## GDD 历史审批回执误触发当前恢复提示（2026-08-27）
 
@@ -5805,6 +5847,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：① 产品行为保留“导出成功后自动打开面板”（一键发布入口），但受影响的用例必须先用 `findByRole('dialog', { name: '发布到游戏广场' })` 断言面板出现、点「关闭发布面板」再继续后续会话操作；② 给这类“新增自动弹窗”改流程时，先跑一遍相关 `appSurface` 用例，避免只跑新增用例；③ 排查同类“点了没反应”时，先看当前是否有焦点陷阱模态打开，而不是先怀疑事件绑定或状态。
 - **关联**：`apps/ai-game-creator-shell/src/App.tsx`（`setPublishPanelOpen(true)`）、`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-preview/preview-shortcuts/assert-project-tools-and-preview.ts`。
 
+## 2026-09-23 AGC 发布按钮点了没反应：DirectProject 不渲染 workspaceStatus，权限确认也没有挂载点
+
+- **现象**：AGC 聊天头能看到「发布」按钮，点击后没有任何提示、面板也不出现；项目权限要求确认时同样静默，用户只能描述为「点了没反应」。
+- **原因**：普通项目固定走 `DirectProjectChatView`，它不渲染工作台状态行，也不渲染 `PlanningChatView` 里那块 `pending-command` 确认卡片；发布提示、权限确认和取消结果原先只写 `workspaceStatus` / `messages`。上游 `f502829fd` 已把发布提示同时 `announce` 回 DirectProject，但确认卡片仍未挂载到 DirectProject；权限查询抛错也没有 catch，确认时策略改为拒绝同样只写工作台消息。结果等待确认、命令被拒、确认后拒绝这几条路径仍表现为「点了没反应」。
+- **处理（现行口径）**：发布相关提示统一走 `announcePublishMessage`，同时写 `workspaceStatus` 和 `directProjectChatRef.current.announce`；`DirectProjectChatView` 增加 `pendingConfirmation` / `onConfirmConfirmation` / `onCancelConfirmation`，在对话列表与输入盒之间渲染与 `PlanningChatView` 同形的确认条；`requestGamePublish` 对权限查询整段兜底并把错误回显到聊天，点击后先回「正在检查发布权限…」，进入导出再回「正在构建并打包试玩包」。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx`（正常发布 / 导出失败 / 确认继续 / 取消 / 确认时拒绝 / 权限查询失败 6 条）与 AGC 全量前端用例通过；`npm run ai-game-creator-shell:typecheck`、`npm run check:encoding`、`git diff --check` 通过。
+- **关联**：`apps/ai-game-creator-shell/src/App.tsx`、`apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx`、`apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx`。
+
 ## 2026-09-21 受控 Lexical 输入区的回写用被动 effect：滞后渲染的 props 会把用户草稿清空
 
 - **现象**：DirectProject 输入盒里粘贴（或连续输入）长文本，提交时 `chat_with_game_creator_direct_codex` 根本没发出去，界面停在空输入盒；`chat-composer` 用例里表现为「队列/终止/语音追加」五条一起红，但手工操作只在快速输入后偶发。
@@ -5825,7 +5875,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - **现象**：`chat_with_game_creator_direct_codex` 的 Tauri 入参曾并列带一个 `prompt: String`（前端把 canonical content 渲染成 `@显示名` 文本），Rust 侧从不读取——`cargo check` 直接报 `src/agent/direct_runtime/user_input.rs` 的 `unused variable: prompt`；前端每次提交仍要算一遍，界面测试也钉着这份投影文本。
 - **成因**：DirectProject 回合真正的输入只来自 canonical `userItem`。`direct_codex_user_item_to_codex_turn_input`（`agent/direct_codex_user_item/wire.rs`）在 DirectProject 分支重建 `turn/start.input`，`LlmRunRequest` 里那份 `user_prompt` 会被覆盖；客户端投影走的是另一套口径（素材被删或改名时退化成裸 resourceId），一旦有人把它接回 Codex，就把 `@显示名` 标签污染了模型输入。
-- **现行口径**：IPC 只传 `projectPath`、`clientTurnId`、`userItem` 与可选 `creationType`；Rust 只从 `userItem` 派生回合输入（空判定与三维契约探测用的派生 prompt 仍在 Rust 内部生成）。前端那份 `@显示名` 投影只服务本地的 `/history` 识别与队列 chip 文案，不出 IPC；界面断言只能读 `userItem.content`。
+- **现行口径**：IPC 只传 `projectPath`、`clientTurnId`、`userItem` 与可选 `creationType`；Rust 只从 `userItem` 派生回合输入（空判定与三维契约探测用的派生 prompt 仍在 Rust 内部生成）。前端那份 `@显示名` 投影只服务本地的历史条目识别与队列 chip 文案，不出 IPC；界面断言只能读 `userItem.content`。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/user_input.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/wire.rs`、`apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts`、`apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts`。
 
 ## 2026-09-21 DirectProject 结构化消息不能逐个拒绝空白文本片段
@@ -5862,3 +5912,51 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - CI 产物清理：Gitea 1.26.4 的仓库 REST 仅列出 finalized/expired V4 artifact，内置到期清理不回收上传中断的 tmp-upload 分块。缓存上传块须带专属标识，宿主只清理目标仓库已结束且超过 7 天的 master run 中同样过期的自有普通文件，未知文件/符号链接保护，不改数据库或全局 prune。Artifact.workflow_run 仅含 ID/SHA，判断过期产物所属事件和状态须再读 run API，不能当作完整 run 使用。
 - 自动切换：Gitea 1.26.4 的 disabled 检查与 FetchTask 事务不原子，Runner 客户端超时不能证明服务端回滚，容器暂时为空也不能证明没有已领取任务。网关必须解析实际 Connect Protobuf/gzip，转发 FetchTask 结果前持久化任务 ID，仅在最终日志及执行清理后的最终 UpdateTask 确认后清账；取消响应不能提前释放。暂停新领取、在途为零、账本为零且内层活动容器为空才可切换，无需全局 Runner admin API。未知协议/响应或崩溃遗留标记停止切换；旧网关缺 active_tasks 不能默认零。首次接入与账本升级须空闲窗口。.runner 的 mtime 不证明地址已加载，应核验真实 FetchTask 来源及本次容器启动时间。
 - 扩展：预热所有 Rust 测试组时保留各自 cwd、profile、features 和锁策略；同一临时 target 的 Cargo fresh 不代表不同 cwd 都已生成缓存键，AGC 提示词契约、分片和 smoke 切换入口前清理预热 target。不要把 workspace 与 spacetime-module 合并成一次编译；Native shell release step 清空双 wrapper，避免将测试缓存扩展成发布缓存。当前 sccache 0.18.0 的 READ_ONLY 在 miss 后仍打包产物并产生 cache write error，不适合用来承诺“未命中无开销”。
+
+## 2026-09-22 卡片文字用 grid 的 auto 行排版，会被按「一行」裁掉
+
+- **现象**：AGC 模板库卡片标题看着被切掉、简介只剩一行、标签行缺半截；`TEMPLATE_CARD_TEXT_HEIGHT` 与真实内容相差约 24px，但卡片底部看起来仍「刚好贴住」，很容易误判成没问题。
+- **原因**：文字区原本是 `grid min-h-0 content-start gap-2 overflow-hidden`，行高由 auto 轨道决定。auto 轨道的 max-content 高度对可换行文本等于**一行**的高度：标题拿到 14px（实际需要 20）、简介 14px（两行需要 32）、标签 14px（需要 19），只有最后一个子项（按钮行）拿到完整高度。真实浏览器实测 `clientHeight`/`scrollHeight` 为 14/20、14/32、14/19。jsdom 不计算布局，单测全绿也照不出来。
+- **处理（现行口径）**：文字区改 `flex flex-col`，每行写死高度并加 `shrink-0`（标题 `h-5`、元信息 `h-4`、简介 `h-8`、标签 `h-5.5`、按钮行 `h-7`，内边距 `p-3`、行距 `gap-2`），行高契约按同一组分项常量（`TEMPLATE_CARD_*_HEIGHT`）算出文字区 174。卡片行高、`TemplateCard` 类名与这组常量必须同时改。
+- **写死高度的连带约束**：动作行一旦固定成 `h-7`，那它就**只能放两个按钮**。再往里塞第三段文本（当时的「正在下载模板」）时，最小卡宽 250px 下按钮文案会被挤成两行并顶出卡片（用户看到「使用模 板 / 更 新」叠成一团）。现行口径是忙状态写在触发它的按钮上（`下载中` / `创建中`，按钮就地换图标+文案），按钮一律 `whitespace-nowrap shrink-0`，动作行 `overflow-hidden` 兜底。
+- **验证**：真实浏览器逐行核对 `clientHeight === scrollHeight`（20/20、16/16、32/32、22/22、28/28）；单测钉住分项常量与卡片各行类名（`templateLibraryGrid.test.ts`、`templateLibraryView.test.tsx`）。
+- **关联**：`apps/ai-game-creator-shell/src/features/template-library/templateLibraryGrid.ts`、`apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`（卡片列表虚拟滚动）。
+
+## 2026-09-22 筛选 chip 的选中态只靠低透明度色相微调，用户看不出选中了什么
+
+- **现象**：模板库筛选 chip 选中与未选中的底色实测只差 **1.09:1**（选中 `rgba(238,208,183,0.26)` 合成后 ≈ `#f9eee5`，未选 ≈ `#fdf9f5`），选中文字 `#b76038` 在自己底色上只有 3.88:1（低于 AA）；运行时分段选中的白底 pill 也和米色页面几乎同色。反馈原话是「选中和没选中的颜色都看不出有差别」。
+- **原因**：选中态走的是 `--platform-cool-bg/border/text`，这三个变量在浅色皮肤里是同一个暖色调的低透明度版本（bg 26%、border 24% alpha），只够做「淡淡的染色」，不足以表达二元状态；深色皮肤里 `rgba(8,145,178,0.14)` 同样太弱，而深色皮肤里「更深的填充」反而更不可分辨。
+- **处理（现行口径）**：筛选控件的二元状态统一为**未选 = 浅底描边 + 常规文字，选中 = 实心品牌填充 + 反白文字**（`.platform-category-chip--active` 与 `PlatformSegmentedTabs` 的 `tone="accent"` 共用 `--platform-chip-*` 语义色；深色皮肤用「亮填充 + 深文字」，因为深色下只有更亮才算选中）。改色只改 `packages/shared/src/theme.css` 的语义变量，不要再往组件里写颜色。
+- **同一坑的第二种表现**：把「悬停」也刷成品牌色（暖色描边 + 暖色文字）后，未选中的 chip 一悬停就像已选中——品牌色一旦被悬停借走，「已选中」这个强状态就没有颜色可用了。现行阶梯是「静止 = 浅底中性描边 / 悬停 = 中性加描边 + 极淡暖底 + 深色文字 / 按下 = 再压一层 / 选中 = 实心填充 + 反白文字」。客户端实测：选中填充 `#b0522e` vs 悬停底 `#f9efe4` = 4.52:1，选中 vs 静止 = 4.97:1，悬停 vs 静止 = 1.10:1（只是提示，不抢选中）。
+- **验证**：`apps/ai-game-creator-shell/tests/workbenchThemeContrast.test.ts` 按 WCAG 公式断言两套皮肤都满足「选中标签文字 ≥ 4.5:1（渐变两端都要过）」且「选中填充 vs 未选底色 ≥ 3:1」；真实浏览器实测改后两态对比 5.6–6.1:1、选中文字 5.5–6.0:1（改前分别是 1.09:1 与 3.88:1）。
+- **关联**：`packages/shared/src/theme.css`、`packages/shared/src/components/styles.css`、`packages/shared/src/components/PlatformSegmentedTabs.tsx`、`apps/ai-game-creator-shell/tests/workbenchThemeContrast.test.ts`。
+
+## 2026-09-22 虚拟网格按「包裹层宽度」算列宽，经典滚动条一出现就多出横向滚动条
+
+- **现象**：AGC 模板库卡片区底部在客户端里凭空多出一条横向滚动条（外层并没有横向溢出内容）；窗口放到没有竖向滚动的尺寸时又不出现。
+- **原因**：react-window 的内层宽度 = `列数 × 列宽`，而列宽是按**包裹层**宽度算的（`floor(容器宽 / 列数)`）。经典（非 overlay）滚动条会吃掉 grid 外层的 `clientWidth`：Windows / WebView2 上竖向滚动条约 17px，于是内层 1184 比外层可用宽 1167 宽出正好一个滚动条，react-window 就按「横向也要滚」处理。**Playwright 自带的 Chromium 用的是 overlay 滚动条（占宽 0），本地量 `offsetWidth - clientWidth` 是 0，完全复现不出来** —— 这类问题只能在 WebView2 客户端里看，或者按算术推。
+- **处理（现行口径）**：`computeTemplateGridLayoutWithScrollbar`（`templateLibraryGrid.ts`）在「内容确实会竖向溢出」时先把滚动条宽度从容器宽度里扣掉再算列宽/行高，不竖向溢出时不预留（否则右侧会留一条无意义的白边）；滚动条宽度由 `measureVerticalScrollbarWidth()` 量一次（overlay 平台为 0，逻辑自动退化）。同类虚拟列表再出现「莫名其妙的横向滚动条」，先查这里的算术，不要靠 `overflow-x: hidden` 掩盖（那会把最后一列切掉）。
+- **验证**：`templateLibraryGrid.test.ts` 断言「竖向溢出时 `列数 × 列宽 ≤ 容器宽 - 滚动条`」「不溢出或 overlay 时与不预留完全一致」；真机客户端截图确认横向滚动条消失、右侧只剩竖向滚动条。
+- **关联**：`apps/ai-game-creator-shell/src/features/template-library/templateLibraryGrid.ts`、`apps/ai-game-creator-shell/src/view/template-library/index.tsx`。
+
+## 2026-09-22 「15% 透明度的焦点环」等于没有焦点提示；选中态自己的投影还会把焦点环顶掉
+
+- **现象**：键盘 Tab 走到筛选 chip、开关、卡片按钮上时，屏幕上完全看不出焦点在哪；自动化里更隐蔽——`box-shadow` 计算值非空（一串 `rgba(0,0,0,0) 0 0 0 0` 的 Tailwind ring 占位），只查「有没有 shadow」会全部判过。
+- **原因**：两个叠加的问题。① `--platform-input-focus-ring` 是 `rgba(204,117,76,0.15)`，合成到页面底色后对底色只有 **1.17:1**，远低于 WCAG 非文本对比要求的 3:1；② 焦点环用 `box-shadow` 画，而**选中态自己也有 `box-shadow`**（实心 chip 的投影），选中的 chip / 分段项聚焦时环被状态投影盖掉，等于没有提示。
+- **处理（现行口径）**：`--platform-input-focus-ring` 改成实心色（浅色 `#b6623f`，对页面 4.3:1；深色 `#9fb0ff`，对深色底 6.5:1）；筛选 chip / 分段项 / 排序按钮的焦点环改用 `outline: 2px solid var(--platform-input-focus-ring); outline-offset: 2px`——`outline` 不参与 `box-shadow` 层叠，不会被选中态投影顶掉，也不撑开布局。
+- **验证**：`tests/workbenchThemeContrast.test.ts` 断言焦点环对两套皮肤的页面底色 ≥ 3:1；真实浏览器里对页面上**全部 175 个可聚焦控件**做 blur→focus 前后比对，无一例外都能看到焦点变化（改前有 8 个控件聚焦前后完全一致）。查焦点态时必须比较「聚焦前后的计算样式差异」，不能只看属性是否非空。
+- **关联**：`packages/shared/src/theme.css`、`packages/shared/src/components/styles.css`、`apps/ai-game-creator-shell/tests/workbenchThemeContrast.test.ts`。
+
+## 2026-09-22 封面图加载失败会画出浏览器的「裂图」图标
+
+- **现象**：模板清单里的封面 URL 失效（或离线）时，卡片封面上出现浏览器的破碎图片图标，比没有封面更难看。
+- **处理**：`TemplateCard` 的 `img` 加 `onError` 直接把自身 `visibility` 设为 `hidden`（不进 state，卡片是 memo 的纯展示组件），留下封面容器本身的中性底色；单测用 `fireEvent.error(cover)` 钉住。
+- **关联**：`apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx`、`apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
+
+## 2026-09-23 渠道 `--config` 只写窗口标题，打包产物系统标题栏回来了且登录请求被 ACL 拒绝
+
+- **现象**：dev 渠道 0.1.129 安装包启动后，窗口顶部同时出现系统标题栏（浅蓝条 + 原生最小化/最大化/关闭）与前端自绘 `WindowChrome`；窗口缩到 816x639（约 800x600 客户区）；登录页常驻「无法连接登录服务，请确认配套后端或 API 代理已启动后重试」。应用日志同一秒出现 `startup.window-title.failed: 缺少 client 主窗口`，而 `https://dev.genarrative.world` 在浏览器/curl 下可正常响应。
+- **原因**：`ebb288a6a`（2026-09-23 18:49）为统一渠道产品名，在渠道配置里加了 `app: { windows: [{ title: productName }] }`。Tauri 的 `--config` 合并是 JSON Merge Patch（`tauri-utils/build.rs` 用 `json_patch::merge`）：对象递归合并、**数组整体替换**。基线窗口数组被整条换掉后，`label` 回落到默认 `main`（不是 `client`）、`decorations` 回落到 `true`、尺寸回落到 800x600。三条症状同源：① `decorations: true` → 系统标题栏；② 尺寸回落 → 816x639；③ label 不再是 `client` → `capabilities/main.json`（`windows: ["client"]`，承载 `http:default` 与平台 API scope、dialog/opener/updater/剪贴板权限）整条不命中，前端 `fetchClientHttp` 走 `@tauri-apps/plugin-http` 时被 ACL 拒绝并抛错，登录状态检查就报成"连不上服务器"。判断关键：**这类"连不上服务"是权限拒绝，不是网络故障——先看窗口 label 与 capability 的 `windows` 是否还对得上，别去查后端与代理**。
+- **处理（现行口径）**：`createChannelConfig()` 从基线 `src-tauri/tauri.conf.json` 读完整 client 窗口对象后展开、只覆盖 `title`（`readBaseClientWindow()`），渠道配置不得再出现"只写 `title`"的窗口对象。新增守卫：`build-release.test.mjs` 用同语义的 merge patch 复现 Tauri 合并并断言 `label=client` / `decorations=false` / 1280x800 / min 1280x720 且承载 `http:default` 的 capability 必须包含该 label；`check-config.mjs` 增补基线 `decorations !== false` 失败关闭。
+- **验证**：`node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs scripts/cargo-features.test.mjs scripts/release-oss.test.mjs scripts/prepare-macos-codex.test.mjs`（60/60）、`node apps/ai-game-creator-shell/scripts/check-config.mjs` 通过；`createChannelConfig('dev', …)` 实测输出含 `label: client` 与 `decorations: false`。修复后的安装包尚未重新构建与安装，真机观感与登录链未复核。
+- **关联**：`apps/ai-game-creator-shell/scripts/build-release.mjs`、`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/src-tauri/capabilities/main.json`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。

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

@@ -16,7 +16,7 @@
 
 ## 开发中
 
-- DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。模型请求计时只保存安全元数据与可观测边界，未知不补零，写盘不能阻塞响应流。详见 AGC 主专题的“DirectProject 交付效率与可观测性”。
+- DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。完整回合条目统一保存在 `project.jsonl`；旧平行审计和附属请求分段计时已退出生产入口，不能因残留实现或测试而恢复旧契约。界面生命周期耗时与独立模型使用记录继续有效，未知边界不补零。详见 AGC 主专题的“Direct 历史、审计与耗时的现行边界”。
 
 - DirectProject 源码修改走 `agc_apply_patch`、进度走 `agc_update_plan`：SDK 原生的 `apply_patch` / `update_plan` 注册会被按回合移除（全局串行单例），不要恢复它们或用伪造工具注解换取并发。补丁只在当前项目内、受当前回合 Write 许可和受控进程约束，失败可能已部分写入，未知结果不自动重放；计划完成不构成验收证据。
 
@@ -43,6 +43,8 @@
 - 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
 - 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本。
 - Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
+- AGC 外置智能体提示词只写模型必须遵守的指令与契约（工具名与参数、调用顺序、禁止项、失败处理、产物要求），不写客户端/宿主怎么实现：内部预算字段与限额、内部状态机与枚举、执行器锁与沙箱技术栈、进程/插件部署、注入与投影管线都属于宿主实现，一律改写成对应行为要求或删除。
+- 修改提示词文本时保留原有 `{...}`/`{{...}}` 占位符；确需增删占位符必须同步改对应 Rust 调用点与断言该文本的测试。
 - UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
 - AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；过程字号和颜色由共享组件统一定义，错误状态保留语义色。
 - 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。