Merge remote-tracking branch 'origin/master' into feat/ui-editor-v3

# Conflicts:
#	apps/ai-game-creator-shell/tests/uiEditorPage.test.ts
#	docs/project-memory/shared-memory/decision-log.md

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

@@ -2,6 +2,111 @@
 
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+
+## 2026-09-18 Provider 瞬态重试次数严格按设置执行（游戏开发 Agent 与策划 Agent 不再被档位收进区间）
+
+- 背景：AGC 客户端此前把 `agentLlm.<agent>.maxRetries` 按运行档位重新收进固定区间——`autonomous-game-build` 档位（自主构建的游戏开发 Agent 及其继承档位的专业子 Agent）被抬到 12~16，`standard` 档位（含立项策划入口的策划 Agent 与普通 Agent 对话）被压到最多 3；瞬态分类里的上游 400 还在同一预算上再收窄到 2 次。现场把 `maxRetries` 设成 5 时，游戏开发与策划两条链路都不按设置执行。
+- 决策：删除这三处区间限制，`maxRetries` 严格等于允许的物理重试次数（显式 `0` 仍表示不重试）。运行档位只保留「上游 400 是否算瞬态错误」的判定（autonomous 档位才重试 400），不再改写次数：`AGENT_RUNTIME_PROVIDER_TRANSIENT_RETRY_LIMIT`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_TRANSIENT_RETRY_FLOOR`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_TRANSIENT_RETRY_LIMIT`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_UPSTREAM_400_RETRY_LIMIT` 四个常量与 `game_creator_agent_runtime_provider_transient_max_retries_at` 一并删除，换成返回 `{max_retries, retry_upstream_400}` 的 `game_creator_agent_runtime_provider_transient_retry_policy_at`。
+- 边界：只改重试次数的来源。瞬态错误分类（`timeout / connectivity / transport / 408 / 429 / 5xx / empty-response / deserialize / stream-unavailable`，以及 autonomous 档位下的 400）、`retryBackoffMs` 指数退避（仍封顶 30s）、durable retry sidecar / lifecycle / `-transient-N` slot 身份、cancel / steer / goal 门禁、耗尽后的 reconciliation 口径与「泥点不足不重试」都不变；前端设置面板与 `agentLlm.<agent>.maxRetries` 契约不变。
+- 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
+- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-17 AGC 抠图提交使用远端画布项目身份
+
+- 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
+- 决策：抠图请求及工具回执统一使用 `prepare_external_canvas_generation_context` 返回的远端 `context.project_id`；本地 manifest 项目 ID 只用于绑定键和本地状态，不得作为主站业务请求的 `projectId`。
+- 验证：客户端定向 Rust 测试、格式、编码和 diff 检查通过；未修改主站路由或 BgFilter。
+## 2026-09-17 图集切分模式改为显式声明
+
+## 2026-09-17 DirectProject 首屏历史锚点只认订阅回执的 lastCompletedItemId
+
+- 背景：ADR「首屏历史由 `subscribe` 返回的 `lastCompletedItemId` 锚定，再取最近切片」只落了一半。`DirectThreadManager` 是搬运层，内存里没有「已完成条目」的锚点，`subscribe` 一律返回 `last_completed_item_id: None`；`commands.rs` 的 `subscribe_direct_project_thread` 在为空时用 `read_direct_project_last_item_id_at` 从磁盘回填，所以线上回执里的值是真的（订阅那一刻文件里最后一条可显示条目的原始 item id）。前端侧：首屏一直在 `loadProjectConversation` 里用 `beforeItemId: null` 直接取文件尾一屏，`lastCompletedItemId` 自 `1b40f030e` 起不再被任何代码读取。
+- 决策（锚点语义）：首屏切片的新端（较新一侧）边界就是这个锚点，**含锚点条目本身**；切片命令新增 `throughItemId` 参数表达「取到这条为止」。比锚点更新的条目只从运行态事件来，历史切片与实时流因此不重叠（原来的文件尾读取会把订阅回执之后才完成的条目也拉进历史，与运行态事件同 id 重叠，只靠前端合并兜住）。
+- 决策（读取时机）：订阅回执到达之前不读首屏，也不退化成「取文件尾」；锚点缺失（订阅不可用 / 失败 / 历史为空）时才按文件尾取尾屏。`/history` 手动重读保持「按当前文件尾取尾屏」的恢复语义，不锚定。
+- 决策（翻页不变）：向后翻页仍用切片返回的 `firstItemId` 作 `beforeItemId`（不含锚点），`hasMore` 与连拉口径不变。
+- 影响范围：`agent/direct_project_history.rs`（切片锚点 + `through_item_id` 参数）、`commands.rs`（`read_direct_project_history_slice` 命令参数）、AGC 前端首屏读取接线与测试骨架。**未改**：DirectRuntime 的 `turn-stream.jsonl` / `tool-calls.jsonl` 写入与进度事件、`list_game_creator_direct_active_turns`、SpacetimeDB 与 HTTP 契约。
+- 验证方式（已跑）：Rust 侧 `cargo test agent::direct_project_history`（22 passed，含「窗口取到锚点那条、排除比锚点更新的条目、`beforeItemId` 与 `throughItemId` 互斥报错」三类用例）；前端 `npx vitest run .../directHistoryAnchorGate.test.ts`（10 passed）与 appSurface 的 `anchors the first history page at the subscribe receipt instead of the file tail`（全量 475 tests / 457 passed / 17 skipped；唯一失败 `edits the published runtime config without leaking API keys into chat` 与本次改动无关，stash 掉本次前端改动后同样变红）；`tsc` / ESLint / prettier / `check:encoding` / `check:doc-index` / `git diff --check` 全绿。变异验证：闸门忽略「已消费」、首屏不等闸门两处改动各自让对应用例变红。
+- 关联文档：[ADR](../../adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)、[里程碑](../plans/【里程碑】DirectProject聊天真相源收敛-2026-09-16.md)、[实施计划](../plans/【实施计划】DirectProject聊天真相源收敛-2026-09-16.md)。
+
+- 决策：`sliceMode` 在图标图集生成入口成为必填字段且不保留任何默认值。省略、`null` 或空字符串必须在引用解析、定价、入队和 provider / OSS 副作用之前返回 `400`（`field=sliceMode`）；`grid` 必须同时提供 `gridX`/`gridY`，`connected-components` 不得携带网格尺寸，二者矛盾同样在副作用前失败关闭。
+- 决策要求：只有用户或需求明确要求等分网格、固定槽位或指定行列数时才使用 `grid`，且行列数必须来自该需求；自由排布、数量不定或只要求一张图集时显式传 `connected-components`，需要约束素材张数时用 `sliceCount`，不得用网格参数表达张数，也不得用固定 `2×2` 表达“四类素材”。
+- 影响面：平台两个图集生成入口（`/api/editor/...` 与 `/api/external/v1/editor/...`）、OpenAPI、画板 Agent 工具、画板前端提交计划、AGC 客户端 MCP 工具说明与桥接校验、AGC 原生工具 schema 与观察器、AGC Skill 与外部编辑器 Skill。
+- 迁移影响：省略 `sliceMode` 的旧调用方（含已发布但未更新的 AGC 客户端和第三方外部 API 调用方）会在图集生成上收到 `400`；本次同时把仓库内自有调用方改为显式声明，不为旧客户端保留兜底分支。
+- 错误可执行性：缺失、空白、未知取值都以 `400` + `field=sliceMode` 返回允许取值和决策分支，`grid` 缺维度提示 `sliceCount` 才是张数约束；`sliceCount` 的公开契约上限与切片上限统一为 `256`（识别数量与目标不一致返回 `422` 并回报实际数量）。
+- 反馈闭环：图集生成结果回显生效的 `sliceMode`/`gridX`/`gridY` 与 `slicePaths`；严格图集提交前必须证明平台回显的模式（`grid` 时含行列数）与请求显式声明一致，缺失或不一致一律失败关闭。
+- 标准美术包：客户端显式声明 `sliceMode=connected-components` + `sliceCount=4`，本地按用途位置写四张 canonical 切片前再次校验数量正好为四，数量不符时失败关闭，禁止截断或补位。
+- 测试环境：在提权 shell 的 Windows 主机上，`%TEMP%` 下新建目录的默认所有者是 `BUILTIN\Administrators` 而不是当前 TokenUser，AGC 的所有者校验会拒绝测试自己创建的项目根；测试构建对该情形（仅限 `%TEMP%` 内、且失败原因为所有者不匹配）先按“本调用创建的对象”初始化所有者后重试，临时目录之外的越权所有者继续失败关闭。
+- 权威合同：[画板图标素材生成入口设计](../../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
+## 2026-09-17 `agc_tools` 媒体资源提示词上限收敛为单一口径，并按 kind 暴露给模型
+
+- 背景：有人反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。核查后工具本身都在（`agc_edit_image` / `agc_create_or_derive_resource`），图片快速编辑在 2026-09-14 的真实项目日志里也有成功记录；但存在三类真实缺陷：① `agc_create_or_derive_resource` 的 `prompt` 在 schema 里只声明 4000，真实上限却是按 kind 分的（背景音乐 140、音效 1900、视频/角色动画 4000、图片 32000），MCP 层还额外写死了一条 140 判断，模型从 schema 与 skill 都看不出 140/1900，写一句正常长度的背景音乐描述就当场被拒；② 客户端 UI 用同一口径但会截断并提示，agent 侧却只有硬拒，形成「UI 能做、agent 调不动」的观感；③ `sourceLocalAssetId` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
+- 决策一（单一口径）：提示词上限只由 `resource_edit_prompt_max_chars` 给出，MCP 工具层、客户端受控工具桥与提交校验全部从它取数；超限文案复用 `resource_edit_prompt_limit_error`，保证模型看到的数字就是真实生效的数字。传输层边界只在信封级生效，不再用一个更小的通用常量先于按 kind 上限误报。
+- 决策二（按 kind 暴露）：`agc_create_or_derive_resource` 的 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength`（background-music / sound-effect / video+character-animation），顶层 `maxLength` 等于各 kind 上限的最大值，`prompt` 描述里写明每个数字；`agc_edit_image` 继续用图片口径 32000。skill 包 `agc-client-projection`（SKILL.md 与 `references/projection-contract.md`）同步写明四个数字，并说明超限要在本地收敛而不是原样重发。
+- 决策三（可执行的前置提示）：源资源未登记时统一返回「先用 `agc_list_registered_assets` 选已有 localAssetId；文件只在项目里时先用 `agc_list_project_files` 确认 `assetImportable=true`，再用 `agc_import_account_assets.localPaths` 登记后重试」。本轮不放开「已完成任务产物」在 agent 侧的隐式正规化：登记是带副作用与 revision 推进的事务，必须由模型显式发起。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`（上限与文案的唯一口径）、`agent/direct_tool_bridge.rs`（按 kind 判定与未登记源资源提示）、`agent/direct_tools_mcp.rs`（schema 与校验）、`resources/agc-skills/agc-client-projection/**` 与清单指纹（version `2026-08-26.18`）。**未改** `/api/external/v1` 契约与 OpenAPI、SpacetimeDB schema、前端 TS 侧 `resourceEditPromptMaxLength` 数字、客户端 UI 行为。
+- 验证方式：新增 `tool_prompt_limits_agree_with_the_client_authority`（四个 kind 的 schema 上限、MCP 校验与客户端权威口径同数字，超限文案带真实上限）、`bridge_resource_prompt_limits_follow_the_client_authority`（工具桥侧同类门禁，含图片编辑的 32000 边界）、`edit_image_tool_reaches_the_platform_image_edit_route` 与 `background_music_tool_reaches_the_platform_audio_route`（MCP 工具层 → 真实工具桥 → 假平台，断言 `/api/editor/images/edits` 与 `/api/editor/audios/background-music/generations` 的路径、Bearer、Idempotency-Key、正文与派生资源落盘，图片编辑正文不得回填 assetKind）、`background_music_prompt_over_the_limit_is_rejected_before_any_bridge_call`（超限在桥请求之前失败）、`unregistered_source_reports_the_registration_follow_up_tools`；`agent::direct_tools_mcp` 22 passed、`agent::skill_pack` 4 passed、`agent::direct_tool_bridge` 17 passed（7 条本机既有失败见下）、`npm run agc:skill-pack:check` 与 `skill-pack:test` 通过。本机 `tempfile::tempdir()` 归属校验失败导致的既有用例（`project::resource_editor` 45 条、`agent::direct_tool_bridge` 7 条）在本轮改动前后**同为失败**（stash 基线复跑确认），与本次无关。
+- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-17 资源画布支持引擎资源只读预览
+
+- 背景：Cocos Creator 工程里已有的引擎资源（模型、动画、预制体、材质、图集、压缩纹理…）此前在发现层就止步：`.glb` / `.prefab` / `.anim` / `.texture` 等扩展名既不可登记，也不进资源画布，工程导入后画布上只看得到位图、音频与脚本。
+- 决策（范围）：本轮只做**只读预览**。引擎资源可以被发现、登记进 manifest、进入资源画布并按类型出预览；不承接编辑、派生、生成与回写，也不解码引擎私有容器（`.texture` / `.cubemap` / `.rt` / `.skel` / `.dbbin` / `.psd` / `.exr` / `.pcm` 只出类型卡）。
+- 决策（契约）：**不新增 manifest 契约字段、不新增 canonical kind、不新增画布分类轴**。引擎资源复用既有 kind（模型/场景/预制体/地形 → `scene`，动画 → `character-animation`，材质/特效 → `code`，图集与容器 → `document`，图像容器 → `image`，裸 PCM → `audio`），避免 `deny_unknown_fields` 让旧客户端读不出整份 manifest；引擎语义由**类型角标**（模型 / 动画 / 材质 / 图集 / 纹理…）表达，不复用「图片 / 文档」。
+- 决策（卡面与读取）：新增三个卡面分支 —— `model`（`.glb` / `.gltf` / `.fbx`，由单例 WebGL 渲染器出缩略图，整页只保留一个 WebGL 上下文）、`structured`（Cocos 序列化资源的结构摘要，非 UTF-8 变体降级成类型卡而不是报错）、`binary`（不发起任何读取，不占预览读取槽）。图像容器（`.tga` / `.tif` / `.tiff` / `.hdr`）先在原生侧转码成 PNG，再走既有图片预览链路。
+- 边界：`.meta` 等引擎导入侧车文件仍然只可发现、不可登记；发现层新增 `model` / `binary` 两个**发现类别**（不是 manifest kind）。多文件 glTF（外部 `.bin` / 贴图）与超限模型降级成类型卡；预览管线既有语义（可见性门禁、3 槽并发、LRU 预算、取消与重试口径）不变。
+- 决策（发现过滤）：引擎工程的 `library/` / `temp/` / `profiles/` / `local/` 不再进发现结果，判定收窄为「工程根直接子目录 + 当前目录确实是 Cocos Creator 工程（`package.json.creator.version` + `assets/`）」。**不放进全局跳过表**：这些名字在别的工程里可能是真实源码目录。过滤落在唯一一份目录遍历（`list_local_project_files_at`）上，因此 Agent 发现、前端资源树与提示词里的未登记清单同步生效；项目快照 / 版本指纹 / 检查点的语义本轮不动。
+- 决策（模型上限与缓存键）：模型预览字节上限从 16 MiB 放宽到 32 MiB，与通用媒体预览取同一上限（base64 载荷约 43 MiB）；超过上限仍是类型卡，不做半渲染。缩略图缓存键改用**稳定身份**（资源身份 + 路径 + 字节数）而不是 blob URL：预览缓存淘汰后重读同一模型不会重新解析 + 重新渲染。要再往上放宽，必须先把预览载荷换成 Tauri 原始字节通道。
+- 决策（模型放大预览）：模型卡可以在工具条打开「3D 预览」独立浮层，浮层内是**交互式视角**（OrbitControls：左键旋转 / 右键或中键平移 / 滚轮缩放 / 复位视角），与三维建模软件同一套操作习惯。加载 / 取景 / 释放三条口径抽到共用模块 `resourceModelScene`，缩略图与浮层不许各写一套；画布上的卡片仍然是静态缩略图并继续共用**唯一**一个 WebGL 上下文，只有打开浮层时才新建交互式上下文，关闭即 dispose。浮层仍是只读预览：不写 manifest、不参与编辑与派生。
+- 验证：`cargo check`、`cargo fmt --check` 通过；`cargo test … cocos` 9 条通过（发现分类 / 登记 / 提示词投影 / 插件门禁）；`cargo test … resource_inspect::tests` 7 条通过（含结构化预览与二进制降级、TGA→PNG 转码、模型签名判定）；`cargo test … agent_asset_import_tests` 9 条通过；生成目录过滤用例通过（引擎工程过滤、非引擎工程不过滤）；`tests/resourceCocosPreviewContract.test.tsx` 7 条通过（含模型卡渲染不可用时的降级、稳定缓存键）；`npx vitest run apps/ai-game-creator-shell/tests/resource apps/ai-game-creator-shell/tests/project` 52 文件 / 543 用例通过；`appSurface.test.ts` 450 通过 / 20 跳过；app `tsc --noEmit`、`npm run check:encoding`、`git diff --check`、`npm run check:doc-index` 通过。
+- 真机验收（2026-09-17 补）：在真实客户端内打开一个含模型 / 动画 / 序列化资源 / TGA / 引擎容器的 Cocos 夹具工程，模型卡出三维缩略图、序列化资源出结构摘要、TGA 出转码后的真实图片、引擎容器出类型卡；同现场 `list_local_project_files` 对根级 `library/` / `temp/` / `profiles/` 返回 0 条、`assets/library/` 正常列出。证据见里程碑文档「证据要求」。
+- 未验证：本机其余仍用 `tempfile::tempdir()` 的既有 Rust 用例继续被 `Windows 安全对象不属于当前用户` 阻断（与本决策无关；根因与手工夹具相同，已记入 `pitfalls.md`）。
+- 关联文档：`docs/project-memory/plans/【里程碑】资源画布支持引擎资源预览-2026-09-17.md`。
+
+## 2026-09-16 抠图模式与背景色契约
+
+- External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
+- flat 的颜色允许 `auto`、`#RRGGBB` 或省略，自动识别完全由 BgFilter 负责。主站只校验、透传，不调用视觉模型选色；complex 携带颜色、非法值和空字符串在入队前拒绝。
+- 来源、名称、模式与颜色共同区分客户端请求意图；旧参数调用及旧 External 请求的幂等指纹须保持稳定。
+- 权威合同：[AGC 抠图模式与背景色透传](../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)。
+
+## 2026-09-16 策划 Agent 工具执行退出项目级写锁并自动接续中断批次
+
+- 背景：策划 Agent 每个 `read_file` / `write_file` / `patch_file` 工具都在执行前竞争全局项目写锁，但同一会话已由 `.agent/design-agent/active.lock` 串行化，工具目标又限定在 `design_artifacts`；项目锁既不覆盖「工具 + 会话 checkpoint」事务，还把进程中断时的 `executing=true` 不确定窗口扩大到等锁与工具执行全程。真机项目出现 `pendingBatch.executing=true`、`function_call` 无配对 output、UI 只显示工作中且无错误的状态。
+- 决策：单次策划工具不再竞争项目级写锁，只保留策划命令锁与既有原子写入；GameAgent / DirectProject 的公共项目锁实现与调用不变。重开项目 hydrate 时，若命令锁可获取且当前批次处于 `executing=true`、当前 call 无 output，则自动续跑原回合：为该 call 补写「执行结果未保存」的工具错误、跳过剩余调用并交回 Provider 自愈；不得重放文件副作用，也不要求用户手动重试。
+- 验证：新增定向用例证明中断批次自动补齐工具 output、收到后续 assistant 回复、清空 pendingBatch 并结束原 turn，同时目标文件保持未修改（未重放 `patch_file`）；策划 Runtime 定向 14 条、策划工具 3 条通过，`cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
+- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
+
+## 2026-09-16 AGC 同 AppData 多窗口共享 Agent Runner
+
+- 背景：双击或再次启动 AGC 客户端时报「应用启动失败」，启动日志为 `startup.runner.owner-lock.failed details=AI 游戏创作界面已由同一 AppData 目录中的其他进程运行`。原设计（2026-07-27 / 2026-08-23）要求同一 AppData 只有一个 GUI owner，第二个界面进程在 setup 阶段就失败退出。
+- 决策（锁语义）：`agent-runner.gui-owner.lock` 改为**界面参与锁** `agent-runner.gui-participant.lock`，以共享句柄打开，同一 AppData 的任意数量窗口可同时持有；Runner 的启动检查、attach 门禁与 watchdog 只用“能否独占取得该文件”判断是否仍有窗口存活。全部窗口退出后才关停 Runner 并清理 endpoint。
+- 决策（claim 采纳与发布）：窗口启动先**采纳**durable claim（同一 epoch/revision），只有 claim 缺失或不可读才发布新 claim；登录、refresh、退出或换号才发布新 claim（新 epoch + 本窗口 revision），成为新的登录态权威。同一 claim 的重复 attach 是幂等空操作，不再清空 Runner 登录态；只有 epoch 变化或携带明确登出参数才允许替换 / 清空。并发发布以最后一次成功写入的 claim 为准，落败窗口按最新 claim 有界重试。
+- 决策（事件与退出）：manifest 失效与 Runtime update relay 的接收端从单槽改为按 `event_sink_token` 去重的注册表并广播，发送失败只淘汰该接收端；GUI 退出先释放本窗口参与锁，仍有其它窗口时保留 Runner（`agent.runner.gui_exit.retained_for_other_windows`），最后一个窗口才请求关闭。Runner 启动失败时先按最新 endpoint 复用一次，避免两个窗口同时冷启动时的实例锁竞争被误报成启动失败。
+- 边界：本机 GUI ↔ Runner 协议方法与参数不变，不引入多 Runner、不做跨 AppData 会话共享；项目级 `.agent/project.lock` 不变，多窗口仍不能并行写同一项目；平台登录态 generation 单调与 claim 失配失败关闭语义保持不变；混用新旧版本二进制访问同一 AppData 不属于支持场景。
+- 验证：定向 Rust `runner::tests::gui_owner_*` 11 条与新增的参与锁多窗口 / 存活判定 / claim 采纳与轮换 / 同 claim 第二个窗口不清空登录态用例全部通过；真实 debug 二进制 Windows smoke 证明同一 AppData 两个 GUI 都完成 `startup.setup.complete`、只存在一个 `--agent-runner` 进程、关闭一个窗口后另一个窗口与 Runner 继续存活、最后一个窗口退出后 Runner 退出并删除 endpoint；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
+- 未验证 / 已知环境问题：真实安装包双开需要重新构建发布后才能验证；`durable_provider_handoff_prevents_shutdown_even_when_corrupt`、`durable_provider_retry_prevents_shutdown_and_reopens_writes`、`runtime_interrupt_for_true_steer_decision_only_interrupts_older_provider_cursor` 三条用例在本机改动前的基线上即失败（Windows 安全对象 owner 校验与 Provider 请求重复），与本决策无关。
+- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`（2026-09-16 节）、`docs/project-memory/plans/【里程碑】AGC同AppData多窗口共享Runner-2026-09-16.md`。
+
+## 2026-09-16 DirectProject 三维请求解除 Phaser 固定约束，由 Codex 自选技术栈
+
+- 背景：三维需求（"做个 3D 城市游戏"）在只有 Phaser 4 二维通道的工程里没有落点，而完成判定以"源码引用已登记平台图片 + 浏览器渲染到该图"为硬门禁，模型可推进的唯一动作退化成生成图集；真机侧表现为长时间生图与反复接线，等轴伪 3D 成了默认交付。产品决定不再用"先澄清引擎"卡住三维请求，改为放开选型。
+- 决策：用户消息表达三维（3D / 三维）且没有点名引擎时，本回合注入**自选技术栈合同**：不受"新 Web 游戏固定 Phaser 4.2.1"约束，由 Codex 自行选择三维技术栈（Three.js、Babylon.js 等 npm 运行时，或当前工程自带的引擎），可以按需新增 npm 依赖、调整工程结构，并在回复里说明选型；客户端不要求先澄清、不阻断任何工具、不拒绝登记产出。
+- 决策（常驻口径）：`DIRECT_AGC_ENGINEERING_GUIDANCE` 的 Phaser 固定约束按二维/三维分层——二维游戏仍是 Phaser 4.2.1，三维请求不受该约束。首页回合只加一行三维提示，仍允许按既有规则创建项目。
+- 边界：用户点名引擎时沿用既有工程合同（Cocos / Unity / Godot 等与当前目录不匹配时先说明不匹配）；用户主动选择"等轴 / 伪 3D / 2.5D"或话题是代码里的三维概念时不注入合同。唯一保留的红线是不得用等轴伪 3D 或二维图集冒充三维交付而不说明。识别只读用户原文，不改写消息、不触发额外工作流，也不做工具阻断或注册门禁。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs`。**未改** `/api/external/v1` 契约 / OpenAPI / DTO、SpacetimeDB schema、AGC 工具桥行为、前端投影与资源工作台。
+- 验证方式：`three_dimensional_game_request_frees_the_engine_choice`、`explicit_flat_presentation_requests_do_not_trigger_three_dimensional_selection`、`named_engine_requests_keep_the_existing_engineering_rule`、`three_dimensional_contract_reports_the_current_project_engine`、`home_three_dimensional_note_keeps_project_creation_available`、`system_prompt_is_bounded_and_declares_direct_runtime`，以及 `agent::direct_tools_mcp` 17 passed；`cargo fmt --check` 通过。本机临时目录 owner ACL 与进程用户不一致，涉及 `init_local_game_project_at` 的既有用例（含未改动模块）在本机无法执行，全量分片与真机 smoke 未在本轮取得。
+- 关联文档：[里程碑](../plans/【里程碑】Direct三维请求自选技术栈-2026-09-16.md)、[实施计划](../plans/【实施计划】Direct三维请求自选技术栈-2026-09-16.md)。
+
+## 2026-09-17 DirectProject 历史分页的「可显示」口径定为前端回合反馈，一次翻页连拉上限 5 页
+
+- 背景：ADR 与里程碑要求「一次翻页操作在前端自动连拉，直到出现可显示条目或 `hasMore=false`，上限 5 页」，但实现只落地了后端锚点与文件尾回扫，前端仍是单发一页。历史切片的 `limit` 按原始条目计，一整页全是工具卡片 / 思考文本且落进同一个已渲染回合的折叠「执行过程」时，用户点「显示更早的对话」看不到任何变化。
+- 决策（可显示 = 出现新回合）：一次翻页操作连续取页，停止判据是**合并后聊天投影的回合数增加**（出现新的用户气泡）。工具卡片与思考文本虽然能通过 `projectDirectThreadItem`，但它们可能整页落进已渲染回合的折叠过程区，不构成用户可见反馈。
+- 决策（粒度和上限）：每个用户操作最多 5 次请求，首屏那次算第 1 页、之后每次点击重新计数；每页仍是 `limit = CONVERSATION_VISIBLE_STEP`，上限只约束请求次数，不改页大小契约。
+- 决策（硬性终止）：`items` 为空、`firstItemId` 为 null 或与请求锚点相同 → 立即停止，不靠 5 页上限兜底。
+- 决策（落点）：口径与循环只在 `features/project-workspace/directHistoryPaging.ts` 一份实现里，首屏与「显示更早」共用；`DIRECT_HISTORY_MAX_PAGES_PER_ACTION` 放 `app/constants.ts`。
+- 边界：循环内只累积、结束后一次性并入聊天 state；某页失败时保留已成功页并沿用现有报错文案；切换项目时丢弃整批；不新增 loading / 禁用态与新文案，不做滚动锚定补偿；运行中回合允许连拉历史。
+- 验证：`directHistoryPaging` 单测 8 条覆盖口径、上限、`hasMore=false` 早停、锚点不前进、单页失败；`project-development.suite.ts` 新增「跨页同回合」集成用例作为真实回归网（变异验证：把判据退化成「有可渲染条目就停」后该用例变红）；`tsc` 与 `appSurface.test.ts`（470 tests / 17 skipped）全绿。
+
 ## 2026-09-16 图标图集自动拆图上限提高到 256
 
 - 背景：AGC 图标图集自动连通域识别在一次生成中识别出 86 个区域，原有 64 片上限在后处理阶段阻断了请求；该上限同时影响 api-server 自动 / 手动切片、SpacetimeDB 批量落库和统一生成结果 item 数量。
@@ -8141,8 +8246,8 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 
 ## 2026-08-24 AGC Direct 抠图语义工具
 
-- 决策：将 External v1 `/api/external/v1/editor/images/background-removals` 通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
-- 约束：异步结果只投影有界队列状态，不允许模型自行构造源 URL 或在不确定提交后更换请求身份；External v1 负责 API Key、幂等接收与统一 operation 查询，客户端不得绕过该契约。
+- 决策：将抠图能力通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；普通登录态使用账号鉴权的 `/api/editor/images/background-removals`，ExternalDeveloper 模式使用 External v1 `/api/external/v1/editor/images/background-removals`。客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
+- 约束：异步结果与恢复语义以本文「2026-09-17 AGC 抠图接入本地资源编辑恢复闭环」决策为准。不允许模型自行构造源 URL 或在不确定提交后更换请求身份；两种路由都接收客户端稳定幂等身份，External v1 继续负责 API Key、幂等接收与统一 operation 查询，客户端不得绕过该契约。
 
 ## 2026-08-24 资源详情动作、空态滚动与最终图多步恢复
 
@@ -8251,6 +8356,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 
 - `.agent/conversations/project.jsonl` 中的 DirectProject 用户消息由 AGC 在 `turn/start` 前以 `direct-codex:{clientTurnId}:user` 幂等追加；写入失败时禁止发起 Codex turn，失败或中断也保留该 user item。
 - Codex app-server 回显的 `userMessage` / `role=user` item 不是第二个历史来源。AGC 只处理其观察和关联，不再把该 echo 追加到项目历史；Codex 的 assistant、tool 和其它有效 response item 仍按现有 append-only 规则落盘。
+- 2026-09-17 追加：回显过滤必须同时覆盖**运行态事件侧**（`direct_thread_visible_item`，`item/started` 与 `rawResponseItem/completed` 两条路径），不能只过滤落盘。只过滤落盘时实时聊天会多出两条没有历史对应的孤儿用户气泡，各自开出一个「耗时 0 秒」的假回合，重进页面读同一份已过滤的 `project.jsonl` 又恢复正常；判据是 `direct_project_turn_does_not_forward_codex_user_echo_as_chat_items`（回合事件里只能有一条 `direct-codex:{clientTurnId}:user` 用户条目）。
 - 本地 AGC user-item 写入必须使用允许 user item 的内部入口，Codex raw item 写入使用过滤入口，避免“过滤回显”反过来阻断预写。相同 `clientTurnId` 只能复用相同规范化 prompt，内容冲突必须失败关闭。
 
 ## 2026-08-31 AGC 错误报告与诊断上传
@@ -8765,11 +8871,81 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：新增 `agent/runtime_error.rs` 作为统一错误事件与有界诊断 sidecar 边界。DirectProject 失败、Agent Runtime terminal failure 均持久化 `.agent/runtime/errors/<eventId>.json`，并将脱敏 assistant 终态写回 `project.jsonl`；前端只通过 `read_agent_runtime_error_detail` 读取脱敏详情。旧 `failure.json` 保留兼容，不把原始 stderr、凭据、URL/query、宿主绝对路径写入用户文本。
 - 决策：错误使用稳定 `source / stage / code / retryable / publicText / recoveryHint / detailRef` 字段；试玩 attempt 越界返回终态错误并停止继续等待。素材完成门扫描实际 npm 源码模块，并把 manifest 中合法的自定义 art-spritesheet 路径纳入候选，构建和浏览器观察仍需通过既有完成门。
 - 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-15 AGC 统一错误事件、诊断落库与验收反馈”；开发期计划见 `docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md` 与对应实施计划。
+
+## 2026-09-16 平台会话身份与凭据分离
+
+- 背景：长回合保活和 401 续期每次签发新 access token，并推进 native generation 重新安装原生会话；冻结平台会话同时比对身份与 token 字节，于是同账号的正常续期被等价成换号，并发在途的生成 / 编辑 / 上传 / 确认 / 下载 operation 全部被判为“旧账号请求”失败。更彻底的一层是原生会话、Runner attach 与 renderer 代次都把“写入顺序”和“身份归属”压在同一个计数器上。
+- 决策：平台会话拆成身份（`userId + api origin + identity generation`）与凭据（当前 access token）。identity generation 只在登录、切号、登出或新的 GUI authority epoch 推进；同账号续期只更新凭据并推进只用于拒绝迟到写入的 revision。冻结会话校验、MCP 会话身份与 Runner attach 统一按身份判定，换号 / 退出仍然失败关闭。刷新失败只在服务端明确 401/403 且一次收敛重试后仍失败时清会话；`/api/auth/refresh` 的轮换失败不再下发清空 refresh cookie 的响应。
+- 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-16 平台会话身份与凭据分离”；开发期计划见 `docs/project-memory/plans/【里程碑】平台会话身份与凭据分离-2026-09-16.md` 与对应实施计划。
+- 验证：AGC `platform_session::tests`、`runner::tests`、`assets::tests` 定向通过；AGC `appSurface` 前端套件 468 项通过；网站 `src/services/apiClient.test.ts` 33 项通过；`cargo test -p api-server refresh_session` 通过。项目夹具类 Rust 用例受本机临时目录属主为 `BUILTIN\Administrators` 的环境限制，未计入本次证据。
 ## 2026-09-15 Direct 回合跨页面继续运行与活动项目面板
 
 - 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
 - 边界：快照不写项目文件、不进入公共 API、不跨应用重启恢复；读取失败保留上一份结果并单独提示，不改写成权限或审批失败。身份锁排他性、付费身份和项目写锁不变。
 
+## 2026-09-17 AGC 模板库落在 oss://agc-dev/templates/
+
+- 背景：AGC 需要「真·游戏模板」库，让用户能浏览、筛选、下载模板并直接由模板创建项目，且模板内容更新不依赖客户端发版。
+- 决策：模板库固定在 bucket `agc-dev`（endpoint `oss-rg-china-mainland.aliyuncs.com`）的 `templates/` 前缀，公共读；**不再嵌套 `agc/` 这一层**（`agc/` 继续只放客户端安装包与 `latest.json` 更新通道）。目录为 `templates/index.json` + `templates/v1/<templateId>/{template.json,template.zip,cover.png}`，zip 根等于 AGC 项目根。
+- 决策：清单 schema 为 `agc-template-library.v1`，每条模板带 `tags`、`coverKey/coverWidth/coverHeight/coverSha256`、`zipKey/zipSizeBytes/zipSha256` 与 `templateVersion`；客户端只信「受信任 OSS 主机 + 对象键」自行拼 URL，清单里的地址字段不参与请求。
+- 决策：客户端缓存与安装根为 `<app_data>/templates/`（`index.json` 缓存 + `installed/<id>/<version>/`，安装完成才写 `installed.json`）；建项目在 `<app_data>/projects/` 下走既有自动工作区规则，先铺模板文件再补 `.agent` 清单。
+- 决策：模板库首页推荐位替换原「灵感推荐」本机图片目录（已删除 `InspirationGallery.tsx` 与 `assets/inspiration/`）；左侧导航新增模板库入口，打开独立全屏页。`tauri.conf.json` 的 `img-src` 放行受信任 OSS 主机用于封面图。
+- 关联规范：`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`；开发期计划见 `docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md` 与对应实施计划。
+- 验证：Rust 模板库 8 项定向单测、前端模型 9 项单测、AGC `tsc` 类型检查通过；`templates/index.json` 匿名可读且每个 `zipKey` 回读 SHA-256 与清单一致；发布脚本 `scripts/agc-template-library-publish.mjs` 支持 `--dry-run` 与上传后回读校验。
+
+## 2026-09-16 CI 宿主 CPU 上限：Jenkins 16 核 / Gitea Actions runner 12 核
+
+- 背景：`genarrative-station`（32 逻辑核）上 Jenkins Built-In Node 与 Gitea Actions runner 共用同一宿主。Jenkins `jenkins.service` 原先没有任何 CPU 限制（`cpu.max=max`），构建期 Web / Api / Stdb 三分支并行（Vitest 8 线程 + 两次默认 32 job 的 cargo）把整机顶到 80%~95%；`gitea-runner` 容器 `--cpus=24`（75%）在 push 触发的 CI 波峰里实测峰值 24.8~25.3 核，是同一时间窗里更大的单一消耗方。
+- 决策：两路 CI 都设硬上限。Jenkins 侧 `systemctl set-property jenkins.service CPUQuota=1600%`（16 核 / 50%，覆盖 Built-In Node 上所有子构建，立即生效、无需重启，drop-in 落 `/etc/systemd/system.control/jenkins.service.d/50-CPUQuota.conf`）。runner 侧把 `/opt/gitea-stack/compose.yml` 的 `cpus` 由 `"24.0"` 改为 `"12.0"`（12 核 / 37.5%），并用 `docker update --cpus=12 gitea-runner` 让运行中的容器立即生效，不重建容器、不中断在跑 job。
+- 边界：Deploy 阶段在远端 dev / release agent 执行，不受该上限约束。调整只动这两处：`systemctl set-property / revert jenkins.service`、`docker update --cpus=<n> gitea-runner` 加同步 compose（备份 `/opt/gitea-stack/compose.yml.bak-<时间戳>`）。
+- 验证：限速后 `Genarrative-Full-Build-And-Deploy` #289 / #290 SUCCESS；采样期 Jenkins 峰值 10.2~10.5 核、限流不足 2s（可忽略），runner 峰值 12.07 核且持续出现 throttling，整机回落到 2.6%~19.8%。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
+
+## 2026-09-17 AGC 抠图接入本地资源编辑恢复闭环
+
+- 背景：`agc_remove_background` 原先只提交 `/api/editor/images/background-removals` 并返回 `queued`，没有轮询远端任务、下载完成媒体或写入本地 manifest；BgFilter 已成功处理但 Agent 因此永远只能看到受理回执。
+- 决策：抠图作为 `LocalProjectResourceEditKind::BackgroundRemoval` 接入现有资源编辑账本，模式和背景色写入 operation 身份；提交后复用同一套轮询、结果下载、staging、manifest 提交和恢复逻辑。已有账本优先恢复，禁止在未知结果时换 operation/idempotency 重发。
+- 边界：主站异步队列、BgFilter 和 SpacetimeDB schema 不变；Agent 只获得本地完成资源和安全身份投影，不接触内部 worker 或凭据。
+- 恢复：已受理任务中断后按原 operation 续查；提交结果不确定时保留账本并人工对账。升级前无账本的 queued 回执不自动迁移或重发，已有远端成果通过正式素材导入恢复。
+- 展示：恢复面板按账本显示抠图模式，平面背景模式同时显示已记录的自动背景色或颜色值，缺失字段不推断默认值，帮助区分同名待处理任务。
+
+## 2026-09-17 Jenkins 公网入口 jenkins.genarrative.world 复用 router 反向隧道口径
+
+- 背景：Jenkins controller 实际与 Gitea 同机运行在 `genarrative-station`（`jenkins.service`，`--httpPort=8080 --prefix=/jenkins`，`JENKINS_HOME=/var/lib/jenkins`），此前只有内网入口 `http://192.168.35.82:8080/jenkins/`；`router.genarrative.world` 已有「dev Nginx → dev loopback → station 反向隧道」的成熟口径。
+- 决策：沿用 router 口径，不新增网关组件。`genarrative-station` 的 `gitea-reverse-tunnel.service` 增加 `-R 127.0.0.1:18085:127.0.0.1:8080`（dev loopback `18085` → station Jenkins `127.0.0.1:8080`）；dev 新增 `/etc/nginx/conf.d/jenkins.genarrative.world.conf`：`80` 只做 ACME webroot 与 `301`，`443` 用 Certbot 证书反代 `http://127.0.0.1:18085` 并保留 `Upgrade` / `X-Forwarded-*`；证书按 router 口径用 `certbot certonly --webroot -w /var/www/html -d jenkins.genarrative.world --renew-hook 'systemctl reload nginx'` 申请。
+- 路径口径：Jenkins 固定 `--prefix=/jenkins`，域名根路径 `302` 到 `https://jenkins.genarrative.world/jenkins/login`，`/jenkins` 补斜杠，其余未带前缀路径 `302` 到 `/jenkins$request_uri`；证书不复制到 Pingora 私有目录，公网 `80/443` 仍由 dev Nginx 监听。
+- 边界：本次只暴露 HTTP/HTTPS UI，`slaveAgentPort` 保持 `-1`（agent 继续由 Jenkins 用 SSH launcher 连 dev / release），不改 Jenkins `jenkinsUrl` 与鉴权策略；Jenkins 登录页因此进入公网可达面，访问控制继续依赖 Jenkins 自身账号体系。
+- 验证：dev `nginx -t` 与 `systemctl reload nginx` 通过；`curl -sI https://jenkins.genarrative.world/` 返回 `302 /jenkins/login`、`/jenkins/login` 返回 `200`、登录页静态资源 `200`、`http://` 入口 `301`；Let's Encrypt 证书 `CN=jenkins.genarrative.world` 到期 `2026-12-16`；公网探测 `82.157.175.59` 仍只开放 `80/443/22`。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
+
+## 2026-09-17 预览部署控制面公网入口 build.genarrative.world
+
+- 背景：多人内网预览控制面（`preview-deployer-server` + `shared/Genarrative-Preview-Deployer` Job）此前只在内网 `http://192.168.35.82/build/` 提供，2026-08-15 决策明确「不配置公网域名」；本次要求给它加公网入口。
+- 决策：沿用 router / Jenkins 同一口径新增 `build.genarrative.world` 作为控制面公网入口，并把 `preview.genarrative.world` 作为 `*.preview.genarrative.world` 规划的父域名先落一张落地页（实例本身仍只在内网）。station `gitea-reverse-tunnel.service` 增加 `-R 127.0.0.1:18086:127.0.0.1:8410`；dev 新增 `/etc/nginx/conf.d/build.genarrative.world.conf`（`80` ACME+`301`，`443` 把 `/build/`、`/api/preview-deployer/` 反代到 `127.0.0.1:18086`，`/` 跳 `/build/`，公网侧 `proxy_cookie_flags ~ secure`）与 `/etc/nginx/conf.d/preview.genarrative.world.conf`（单域名证书 + 落地页）。
+- 白名单：控制面按 `Host` 精确匹配、对非 GET 的 `/api/*` 精确匹配 `Origin`，因此同步改为 `GENARRATIVE_PREVIEW_DEPLOYER_ALLOWED_HOSTS=192.168.35.82,build.genarrative.world`、`GENARRATIVE_PREVIEW_DEPLOYER_ALLOWED_ORIGINS=http://192.168.35.82,https://build.genarrative.world`；`GENARRATIVE_PREVIEW_DEPLOYER_SECURE_COOKIE` 保持 `false`（内网 HTTP 入口继续可用），公网 cookie 的 `Secure` 由 dev nginx 强制。重启 `genarrative-preview-deployer.service` 会清空内存会话，内网用户需重新输入口令。
+- 边界：本次只暴露控制面（触发/查看构建、卸载），预览实例不暴露；`preview.genarrative.world` 没有通配记录，实例地址仍是内网 `http://192.168.35.82:84xx`，控制面页面展示的 `webUrl` 也仍是内网地址。要变成公网实例地址，需要 `*.preview.genarrative.world` 通配证书（只能 DNS-01）、station 侧按 Host 分发和页面 URL 口径改造。
+- 验证：`nginx -t` 与 reload 通过；`https://build.genarrative.world/` `302 → /build/`、`/build/` `200`、SPA 资源 `200`、`/api/preview-deployer/session` 返回 `{"authenticated":false}`；错误或缺失 `Origin` 的 POST `403`、错误口令 `401`、字段名不符 `422`；两个新域名证书到期 `2026-12-16`；内网 `Host: 192.168.35.82` 仍 `200`、未知 Host `403`；jenkins / dev / git 入口回归正常。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[Jenkins容器预览部署控制面技术方案](../../technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md)。
+
+## 2026-09-17 预览控制面增加公网预览地址口径（代码已实现，待随控制面发布）
+
+- 背景：控制面页面此前只展示内网地址 `http://192.168.35.82:<webPort>`；公网通配域名 `*.preview.genarrative.world` 已解析到 dev，需要页面能显示对应的公网入口。
+- 决策：公网地址由控制面自己派生，不接受 Jenkins 产物或状态文件提供的任意地址。`preview-deployer-server` 新增可选配置 `GENARRATIVE_PREVIEW_DEPLOYER_WEB_DOMAIN`（如 `preview.genarrative.world`，只接受小写字母、数字、短横线和点号，不带协议与端口），并在公开 DTO 新增 `webPublicUrl`：仅当记录已有内网 `webUrl` 时取 `https://<instanceId>.<WEB_DOMAIN>`（实例 ID 仍由分支派生，形如 `preview-<16位hex>`），卸载时与 `webUrl` / `webPort` 一起清空；状态文件里的旧值在加载时被重新派生覆盖。
+- 前端：`apps/preview-deployer-web` 在存在公网地址时把「打开公网预览」作为主入口，内网地址降级为次级链接；未配置时行为与之前一致。
+- 上线依赖（本次未完成）：`*.preview.genarrative.world` 通配证书（Let's Encrypt 通配只能走 DNS-01，域名在 DNSPod，certbot 无官方插件，需要 DNSPod API Token 配合 acme.sh）、station 侧按 Host 分发到 `84xx` 端口、dev 通配 vhost 与隧道；控制面本体需在 station 用 `scripts/deploy/preview-deployer-install.sh` 重建发布。
+- 验证：`cargo test -p preview-deployer-server`（13 项）、`apps/preview-deployer-web` vitest（13 项，含新增公网地址用例）、`npx tsc --noEmit`、`npm run preview-deployer:web:build`（`PREVIEW_DEPLOYER_WEB_BASE=/build/`）、`npm run check:preview-deployer`、`npm run check:encoding`、`git diff --check` 全部通过。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[Jenkins容器预览部署控制面技术方案](../../technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md)。
+
+## 2026-09-17 AGC 自动建项支持用户自选项目创建目录（入口设在设置「工作区」）
+
+- 背景：首页「做游戏 / 做方案」与模板库「使用模板」的自动建项固定落在 `<app_data>/projects`，用户无法把游戏放到自己的工作盘或工程目录；同时该路径不能随意放开（受管私有目录门禁与 Documents 继承 ACL 的既有约束见 `pitfalls.md`）。
+- 决策：新增可选参数 `projectsRoot`（`create_automatic_local_game_project`、`create_automatic_local_game_project_from_template`），为空时由 Rust 回落到 `<app_data>/projects`。可选值只接受本机原生目录选择器返回的目录：`validate_requested_game_project_creation_root` 要求非空绝对路径、无控制字符、已存在的普通目录（拒绝链接/reparse point），并通过 `prepare_game_creator_project_root_for_read` 的 user-selected 范围校验与一次性修复；目录不存在不代为创建。
+- 决策：客户端偏好「项目创建目录」存 `localStorage` 键 `genarrative-ai-game-creator.project-creation-directory.v1`；入口只在设置里（侧边栏「配置」→ 分类「工作区」），首页输入行与模板库页头不再各挂一个入口。「恢复默认位置」即清空偏好。偏好只表达用户意图，不是授权凭据：每次建项都重新过 Rust 门禁，存储被改坏最坏是回退默认位置或一次可见失败。既有项目不迁移。
+- 决策：该偏好属于客户端本地设置，不并入 `read_game_creator_app_config` 那份运行时配置：在「工作区」里选择目录当场生效，不受「保存设置」按钮影响；首页与模板库建项时各自读取同一份偏好。
+- 决策：`pick_local_project_directory` 增加可选 `title`（限 24 字符、无控制字符，其余回退默认标题），使「选择项目创建目录」不再冒用「选择游戏项目目录」文案。
+- 关联规范：`docs/project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`。
+- 验证：`cargo test --bin genarrative-ai-game-creator-shell creation_root`（2 项）、模板库定向单测 14 项、偏好模型 3 项、`appSurface` 472 项（含设置页「工作区」选择/恢复目录与「设置里选目录后建项带 `projectsRoot`」两条场景）、`tsc`、`check:encoding` 与 `check-doc-index` 通过。
+
 ## 2026-09-18 UI 编辑器深模块 seam 收敛
 
 - 决策：UI 编辑器的语义状态写入通过 React-free `stateTransition` seam；页面 hook 继续负责 React/history/lock adapter。保存前增加 `stateInvariants` projection，Rust 持久化规则仍是最终权威。

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

@@ -4,6 +4,10 @@
 
 ## 标准流程
 
+前端测试稳定性验证使用根目录 `npm test`（与 Frontend tests job 相同），保留 Vitest 的 8 worker 上限。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
+
+用例隔离必须包括浏览器状态与 mock 实现：修改 `window.history` 后恢复基线路由；`spyOn(window, 'getSelection')` 等 spy 在用例结束后 restore；`clearAllMocks` 仅清调用记录，不能恢复被上一个用例替换的返回值。顺序打乱暴露的失败应修复泄漏来源，保留原有业务断言。
+
 ```text
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```
@@ -20,6 +24,8 @@
 
 ## 开始前
 
+- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码，不能经依赖软链接读取另一工作树的共享包。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，不用给组件补全局变量来掩盖错误来源。
+
 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
 - 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
 - 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
@@ -47,6 +53,8 @@
 
 ## 验证路由
 
+AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
+
 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
 
 SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。

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

@@ -1,5 +1,76 @@
 # 踩坑与排障记录
 
+## 生成草稿与异步展示边界必须按身份隔离
+
+非模态生成浮层切换占位时按 draftId 分实例，卸载保留未提交/失败草稿，成功提交不再复活草稿；旧项目占位不存在时丢弃其保存回调。失败重试保留原请求输入和引用身份，引用失效不能静默过滤；修改已绑定输入须明确另起请求，不伪装成原请求重试。
+
+聊天真实发送时间按相同用户 itemId 与正式条目合并，不能被启动应答后的观测时间覆盖。Thread Manager 生命周期事件透传已有 userItemId，使仅历史回读、live 为空的回合仍可精确补终态时间；不得按历史尾项或时间近似猜归属。布局整理仅可合并队尾同范围意图，不能越过中间手动写入；拖动预览和保存均冻结按下时的相应坐标基准。
+
+## Phaser 与 CSS 双重居中导致游戏画面偏移
+
+Phaser `Scale.FIT` 与 `autoCenter: CENTER_BOTH` 会给 canvas 计算定位外边距。若 canvas 的直接父容器同时使用 `display: grid; place-items: center` 或另一套 CSS 居中，浏览器再次定位带 margin 的元素，竖屏游戏会相对预览区域偏右。应只保留一个居中责任方：Phaser 居中时直接父容器使用尺寸明确的普通块布局；CSS 居中时设置 `autoCenter: NO_CENTER`。不禁止外围页面的 Grid/Flex 布局，不通过修改 AGC iframe 的固定偏移掩盖项目 CSS 问题。
+
+开发 Agent 的实际系统工程提示和 `agc-web-game-development` Skill 均包含此规则。布局修改后重新构建 dist，分别在桌面、移动与 resize 后测量 canvas 相对游戏父容器的中心误差（预期居中时不超过 1 CSS px），同时检查无溢出和意外滚动条；构建成功不等于视觉验收通过。
+
+## 发布目标与原生能力必须贯穿完整入口
+
+显式 `--target` 不能只改变 Tauri 命令参数；AGC 发布入口必须把同一解析结果传给版本高水位、更新端点、产物目录/后缀和清单平台键，否则 macOS 构建可能错误使用 Windows 渠道。插件文件存在也不代表 native 能力可用：Cocos 在宿主注册表缺少适配器时应隐藏并拒绝启动，前端自动启动消费后端列表投影，不能仅凭项目类型推断能力。发布策略以客户端更新权威文档为准，单架构资源不能登记成双架构产物。
+
+## macOS 安装包小不代表运行依赖齐全
+
+AGC 的 DMG 生成成功只证明应用可以被打包。平台专属 Codex staging、Tauri resource 映射、运行时资源目录定位和辅助组件 SHA-256 清单必须同时闭合；只配置 Windows 资源会让 Mac 开发机因全局 Codex 而掩盖缺包。macOS 使用锁定原生依赖中的 Codex、code-mode host、rg 和 zsh，不能复制 Windows EXE/DLL。用 `scripts/check-macos-bundle.mjs`（AGC 应用目录下）对复制到临时目录的 `.app` 做限制 PATH、隔离 HOME 的正式查找、app-server 握手和缺组件拒绝检查；GUI、账号、Provider 与 Cocos 原生桥接另行验收。插件 JS 入口仍依赖系统 Node，不得将“插件文件随包”表述为“无需任何外部工具链”。
+
+## AGC 空快照测试必须等待请求完成
+
+`waitFor(() => expect(activeTurns).toEqual([]))` 在 Hook 初始状态就能成功，不能证明首次异步读取已经完成。引用稳定性回归应显式控制 Promise 完成，并同时检查首次空响应与禁用后的引用；快照签名初值必须与初始空数组一致。窗口同步测试应验证未变化状态不重复发布，不能依赖一次多余的空态更新。
+
+## AGC Windows 开发态首次页面加载缓慢
+
+Vite 默认监听应用根下的 Rust `src-tauri/target`，构建产物较多时会创建大量 Windows 文件监听器。AGC 配置通过 `server.watch.ignored: ['**/src-tauri/target/**']` 排除此目录，不关闭业务源码、CSS、共享组件监听或 HMR。排查时区分后端就绪、Vite 扫描和原生窗口首绘；监听目录回归不能代替实机首绘测量，验证入口见本地开发运维文档。
+
+## 2026-09-17 AGC 输入盒的「推理档」弹层被祖先裁切：要放开裁切而不是挪弹层
+
+- **现象**：窄窗口下（视口 ≤1000px 时右侧对话面板只有 280px 宽）点开输入盒右下角的「推理档」，弹层是个**空盒子**：档位文字（默认 / 低 / 中 / 高 / 最高）整片看不见，只剩一个方框。
+- **成因**：推理档是控制排里最靠左的弹层锚点，`.conversation-model-menu` 默认 `right: 0` 贴触发钮右缘**向左**展开；触发钮右边还压着模型选择、语音、发送三颗钮，所以 150px 宽的弹层在 280px 面板里会伸到面板左侧 42px 之外。`.game-workbench-chat`、`.project-supervisor-surface.is-direct-codex`、`.project-supervisor-conversation` 三层各自的 `overflow: hidden` 沿自己的溢出边界裁掉它，而档位文字起点才 14px（面板左内边距 5px + 按钮左内边距 9px），正好落在被裁掉的那半边。
+- **处理（用户指定口径）**：不挪弹层位置——只让 direct-codex 那三层不再裁切：`.game-workbench-chat:has(.project-supervisor-composer.is-direct-codex)`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex .project-supervisor-conversation` 三条 `overflow: visible`。弹层的 `right: 0`、尺寸和触发钮锚点全不变，只是允许它盖到左侧资源面板上完整显示。消息列表自带 `overflow-y: auto`（另一轴按规范计算为 auto），消息内容仍由列表自身裁剪。
+- **易错点**：① 把弹层改成 `left: 0` 或往右挪也能让它可见，但那是改变展开方向，弹层会跑到触发钮右边（用户明确否决）；② 只放开最外层聊天列不够——surface 与 conversation 各自都会裁，三层必须同时放开；③ 只按宽度比大小会误判：280px 面板里控制排本身也超出（发送钮右侧溢出 22px，被窗口右缘吃掉），那不是本条的原因，别顺手去改控制排布局。
+- **验证**：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts` 的 `keeps the landscape workbench edge-to-edge with internal chat scrolling` 钉住三条 override 声明在场（删掉任一条即红）。真机几何用 playwright-cli 打开一份只含真实 `styles.css` 与真实 composer DOM 的最小复现页实测（视口 1000×700、面板 280px）：弹层 rect 修复前后都是 `[-42, 108]`（位置未动），`elementFromPoint` 的命中区间从修复前的 `[2, 108]` 变成整块；档位文字在截图中完整可见。
+- **关联**：`apps/ai-game-creator-shell/src/styles.css`（`面板纵向布局（2026-07 Codex 风格改造）` 区块之后）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+## 2026-09-17 资源卡「内容跟着边框动」与「模型缩略图被拉伸」是两条不同的几何陷阱
+
+- **内容跟着状态边框位移**：卡片底态是 `border: 0`，悬停 / 选中才加 1px 边框；卡片是 `box-sizing: border-box`，而卡面（`.game-resource-card-visual`）与角标都是 `position: absolute; inset: 0`（包含块 = **padding box**）⇒ 状态一切换，内容盒四边各被吃掉 1px，卡面与角标整体位移并缩小 2px。修法：底态写成 `border: 1px solid transparent;`，状态只点亮 `border-color`；契约用例改成断言「资源卡规则里不得出现非 1px 的 `border` / `border-width`」。
+- **模型缩略图看起来被拉伸 / 被裁**：三个原因叠在一起 —— ① 缩略图渲染器的 `PerspectiveCamera` 是单例复用件，`aspect` 默认 `1` 且从没更新，方形投影被塞进宽扁缓冲；② 卡面里 `width/height: 100%` 的图片挂在 `place-items: center` 的网格里，网格项高度会退化成"按内容定高"（百分比高度解析成 `auto`），图片按自然比例长过卡片、被 `overflow: hidden` 裁掉，看起来就像被拉伸；③ 栏目画布用 `transform: scale(var(--resource-section-zoom))` 放大（真机 1.5 倍），而 `ResizeObserver` / `offsetWidth` 只看**布局盒**，缩放变化既不触发 observer，按布局尺寸 1:1 渲染的图也会被放大到发虚。修法：渲染前设 `camera.aspect`；图片改 `position: absolute; inset: 0` + `object-fit: contain`；渲染尺寸取 `offsetWidth/offsetHeight × 2` 超采样（上限 1024），并把实际渲染尺寸暴露到 `data-model-render-size` 方便排障。
+
+## 2026-09-17 从提权会话创建的目录会被 AGC 的 Windows owner 校验直接拒绝
+
+- **现象**：在 Codex 会话里手工创建的工程目录（例如 `C:\Users\<user>\Documents\Codex\...\cocos-preview-fixture`），用客户端打开时报 `Windows 安全对象不属于当前用户：<path>`；Rust 侧同样用 `tempfile::tempdir()` 建夹具的用例也成片失败在同一句上。
+- **原因**：这个 shell 以管理员身份运行，`New-Item` / `tempfile` 新建目录的 owner 是 `BUILTIN\Administrators`，而 AGC 的校验要求 owner 等于当前用户 SID（`KDLETTERS\<user>`）。`Get-Acl <path> | Select Owner` 与 `whoami` 一比就能定性；同一台机器上由客户端自己创建的目录 owner 正确，所以「客户端自己建的项目能用、手建的不能用」。
+- **处理**：手工夹具先 `icacls <path> /setowner "<DOMAIN>\<user>" /T`；Rust 用例改用工程自带的 `crate::tests::canonical_test_tempdir(prefix)`（它会 canonicalize 并重置目录 owner），不要直接用 `tempfile::tempdir()`。判「用例失败与本改动无关」时，先确认失败信息是不是这一条。
+
+## JSON 卡片显示与 UI 编辑能力必须同源
+
+JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡片、缩略图及编辑器入口共同消费受控文本预览的 `uiDesignAssetId`；只有原生复用 UI 持久化合同校验 schema、完整 State 和项目/资产身份后才设置它。普通 JSON 保留 JSON 代码预览，不按 `kind: UI/ui` 或 schema 字符串片段猜测编辑能力。已有合法 UI State 的加载/保存不依赖 kind 精确大小写，但新建初始化仍保留正式 UI 资产门禁；缓存与项目切换须保留现有身份隔离。
+
+## 窗口 Context 发布不得依赖每次渲染新建的业务回调
+
+工作台向窗口标题栏发布运行项目时，若 effect 依赖普通函数派生的回调，发布 Context 会重新渲染工作台，进而再次发布并清理，形成更新深度循环。转发入口须稳定，并在提交阶段更新实际处理器引用；发布数据变化与卸载清理分开。回归测试必须组合真实窗口 Provider 和工作台消费者，只有独立画布测试无法覆盖这条反馈链；回归时用有界发布次数阻止测试失控。画布快速操作时暴露的更新深度错误，也须检查外层状态同步，不能直接归因于滚轮频率。
+
+活动回合快照的初始签名须与初始空数组一致，首次异步返回空数组不能额外换引用。停用、重新启用或切换读取器时应使旧请求失效，避免晚到结果覆盖新快照；测试需控制 Promise 完成时机，不能用“初始数组已为空”当作请求已结束。无原生读取器时窗口只发布一次空状态。
+
+## 2026-09-17 工具 schema 声明的上限与真实校验不一致，会表现成「agent 调不动这个功能」
+
+- **现象**：用户反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。查工具目录时两个工具都在（`agc_edit_image`、`agc_create_or_derive_resource`），图片快速编辑在真实项目日志里还有成功记录；但 agent 侧写一句正常长度的背景音乐描述就失败，而客户端 UI 用同一个提示词却只是被截断加提示。
+- **原因**：`agc_create_or_derive_resource.prompt` 在 MCP schema 里只声明 `maxLength: 4000`，真实上限按 kind 分（背景音乐 140 / 音效 1900 / 视频、角色动画 4000 / 图片 32000），MCP 层还额外写死一条 `kind == background-music && > 140` 的判断；skill 包没有任何一处写这两个数字。模型从 schema 与 skill 都无法得知 140，于是必然踩一次硬拒。同类隐患还有两处：客户端工具桥用通用 4000 校验 prompt，会把 4000 以上的图片编辑提示词误报成「超出安全边界」；按 kind 校验散落在 MCP 与桥两处，新增类型容易只改一处。
+- **处理**：上限收敛到 `resource_edit_prompt_max_chars` 单一权威（工具层、桥、提交校验共用），超限文案复用 `resource_edit_prompt_limit_error`；工具 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength` 并在描述里写明数字；prompt 的传输层边界退到信封级，避免通用常量先于按 kind 上限报错；两端 skill 文档同步写明四个数字。新增 `tool_prompt_limits_agree_with_the_client_authority` 作为门禁：四类 kind 的 schema 上限、桥上限与权威口径必须同数字，且超限文案必须带真实上限。
+- **验证**：`cargo test --bin genarrative-ai-game-creator-shell -- --test-threads=1 agent::direct_tools_mcp::tests`（22 passed，含两条走 MCP 工具层 → 真实工具桥 → 假平台的媒体工具契约用例与一条超限零请求用例）、`agent::direct_tool_bridge::tests`（17 passed，含新增的按 kind 上限门禁；另有 7 条本机既有失败）、`agent::skill_pack`（4 passed）、`npm run agc:skill-pack:check`。本机 `tempfile::tempdir()` 归属校验失败会让 `project::resource_editor` 45 条与 `agent::direct_tool_bridge` 7 条既有用例失败，改动前后同为失败，不要据此误判回归。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`、`src-tauri/src/agent/direct_tool_bridge.rs`、`src-tauri/src/agent/direct_tools_mcp.rs`、`src-tauri/resources/agc-skills/agc-client-projection/`。
+
+## 2026-09-16 从 Codex 里启动 AGC 客户端会看到被重定向的 `%APPDATA%`
+
+- **现象**：在 Codex 会话里用 `Start-Process` 启动 `genarrative-ai-game-creator-shell.exe` 做排障时，子进程写 `C:\Users\<user>\AppData\Roaming\world.genarrative.ai-game-creator\...` 的内容会落到 `C:\Users\<user>\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\...`；同一个 `Test-Path` / `Get-ChildItem` 命中的是重定向视图，只有 `\\?\C:\Users\...` 形式能区分真实路径。
+- **影响**：用 agent 拉起的客户端复现「多开 / 登录态冲突 / 锁文件被占用」类问题时，可能与用户双击开始菜单快捷方式的真实进程不是同一份 AppData，从而得出「两个实例没有互相冲突」或「日志里没有那条失败」的错误结论。
+- **处理**：把用户双击快捷方式（或从 Codex 之外启动）的进程作为唯一用户侧证据；核对待查文件时同时比对真实 `AppData\Roaming` 路径与 `Packages\...\LocalCache\Roaming` 路径；排障结论里写明客户端是「谁启动的」。
+
 ## Windows 已登记生图资产未刷新
 
 Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` / `\\?\UNC\`，而前端项目路径仍是普通盘符或 UNC。失效监听不能直接比较原始字符串；识别为同一项目后，用当前项目路径重读 manifest，保留项目切换与 revision 门禁。普通 `agc_generate_image` 成功提交也必须发出失效通知，不能依赖整轮 Agent 结束。回归需覆盖两种 Windows 前缀、其它项目事件拒收，以及 Agent 尚未结束和后续失败时已登记图片卡片仍可见。
@@ -195,6 +266,15 @@ AGC 的 Cocos 能力来自随客户端分发的 `agc-cocos-editor` 内置插件
 首页命名回合成功后创建命令失败且不会留下项目目录。用户通过目录选择器创建的
 项目仍走 user-selected 权限范围。
 
+- 2026-09-17 补充：首页与模板建项支持用户自选 `projectsRoot`（见
+  `docs/project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md`）。
+  自选目录只有一条合法来源——本机原生目录选择器返回的目录，并且必须在 Rust 侧
+  通过 `validate_requested_game_project_creation_root`
+  （绝对路径 / 无控制字符 / 已存在普通目录 / 非链接与 reparse point /
+  `prepare_game_creator_project_root_for_read`）。默认值仍必须是
+  `app_data_dir()/projects`：不要因为"用户能自选"就把默认值改成 Documents 或
+  其它用户目录，也不要在目录不存在时替用户创建。
+
 ## 2026-09-12 Cocos 项目识别不等于编辑器桥就绪
 
 - 现象：能发现正确 Creator PID、Agent 也有 `agc_cocos_execute`，但首次执行报 pipe 不存在；仅登记目标的 `connect` 会误报成功。
@@ -5625,3 +5705,42 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 验证：`git config --show-origin --get user.name` 出现 `file:.git/config  Git Hooks Test`、`git rev-parse --show-toplevel` 指向 `%TEMP%\genarrative-pre-push-*\repo` 都是被污染的确定性证据；被 `core.worktree` 劫持期间执行的 `git pull` 会把检出写进临时目录，真实工作树整体落后（本次 93 个文件），配置修好后用 `git checkout HEAD -- .` 回填。
 - Vitest 的 `toHaveBeenCalledWith` 匹配任意一次调用，失败输出会列出其它命令；应先定位相同命令的真实参数差异，不能由其它调用的序号推断时序故障。
 - 存在后台轮询的 IPC mock 不应要求目标命令占据全局最后一次调用。验证刷新时先记录调用边界，再筛选该边界之后的目标命令，严格核对其最后一次参数，避免后台查询影响断言，也避免旧调用掩盖刷新未执行。
+
+## 2026-09-16 并发生图遇到“登录态冲突”：身份代次与凭据轮换混用
+
+- **现象**：DirectProject 长回合里并发派发的生图 / 素材生成请求中途报 `authentication-required: 陶泥儿登录态已变化，旧账号请求已停止，请使用当前账号重试`，或平台工具返回 `HTTP 401 invalid-token`；账号并没有切换，重新登录后短时间内可复现。
+- **原因**：客户端把两件事压成了一个判据。原生冻结会话（`PlatformSessionSnapshot`）同时承担“身份归属”和“access token 字节比对”，而长回合保活与 401 续期每次都会签发新 token 并推进 native generation 重新安装会话；于是同账号的正常续期被等价成换号，续期窗口内所有在途生成、编辑、上传、确认和下载 operation 全部失配。保活定时器（回合 busy 时每 5 分钟一次）会稳定落在生图窗口内，所以并发越多越必现。另一层在服务端：`/api/auth/refresh` 是严格一次性轮换，且失败时下发清空 refresh cookie 的响应；两个窗口 / 实例并发续期时，输的一方会把赢家刚写入的有效 cookie 删掉。
+- **处理（现行口径）**：平台会话统一拆成**身份**（`userId + api origin + identity generation`）与**凭据**（当前 access token）。identity generation 只在登录、切号、登出和新的 GUI authority epoch 推进；同账号续期只更新凭据并推进写入 revision（revision 只用于拒绝迟到写入）。冻结会话校验只比身份，比 token 字节的判据已被取代。刷新失败语义收紧为：只有服务端明确返回 401/403 且经一次收敛重试后仍失败，才清本地会话；网络错误、5xx、网关错误和响应契约异常必须保留会话与 access token。`/api/auth/refresh` 的轮换失败不再下发清 cookie 响应。
+- **验证**：AGC `platform_session::tests` 覆盖“同身份 token 轮换后冻结会话仍有效”“换号 / 退出后失效”“迟到 install 被 revision 拒绝”；`appSurface` 前端用例覆盖“续期不推进身份代次且 native 写入 revision 递增”“瞬时刷新失败不清会话”；网站 `src/services/apiClient.test.ts` 覆盖“刷新 401 后收敛重试成功”与“两次都被拒绝才判权威失效”；`api-server` `refresh_session_*` 覆盖“轮换失败不下发清 cookie”。定位同类问题先看冻结会话判据里有没有 token 字节，再看服务端失败响应有没有 `Max-Age=0`。
+
+## 2026-09-16 同步 Tauri 命令里 `tokio::spawn`：点「终止」整个客户端 abort 闪退
+
+- **现象**：AGC 客户端（陶泥儿 0.1.46 安装包，`C:\Users\<用户>\AppData\Local\陶泥儿\genarrative-ai-game-creator-shell.exe`）在对话回合运行中点输入盒的「终止」后整个 App 直接消失。Windows 事件日志 `Application Error` 1000：异常代码 `0xc0000409`、出错模块就是该 exe、偏移 `0x3395066`；`%LOCALAPPDATA%\CrashDumps` 留下同名 minidump，其 ExceptionStream 为 `NumberParameters=1`、`Param[0]=7`（`FAST_FAIL_FATAL_APP_EXIT`）⇒ Rust `abort()`，既不是栈溢出（`0xC00000FD`）也不是访问违例（`0xC0000005`）。
+- **原因**：`cancel_direct_codex_turn` 是**同步** Tauri 命令，Tauri 把非 `async` 命令直接跑在 IPC 回调线程（Windows 上是 WebView2 的 UI 线程）；该线程没有进入任何 tokio runtime 上下文（`main` 只 `tauri::async_runtime::set(handle)` 加泄漏 Runtime，从未在调用线程 `enter()`）。终止链路 `cancel_direct_codex_turn_at → CodexTurnStartCancellation::cancel → maybe_interrupt` 却用 `tokio::spawn` 派发 `turn/interrupt`：在没有上下文的线程上 `tokio::spawn` 经 `Handle::current()` panic（"there is no reactor running"），panic 又跨不过 Tauri 的 IPC 回调边界，Rust 只能 abort 整个进程。同一模块的 `CodexThreadLease::drop`、`CodexTurnGuard::drop` 是同一形态。引入点是 2026-09-15 23:37 的 `76bbeb684 重构 DirectProject Agent 深模块`；既有覆盖只有 `#[cfg(unix)]` 的 `#[tokio::test]` 走 Drop 守卫路径，碰不到同步命令线程，所以 CI 全绿。
+- **处理**：`codex_app_server/mod.rs` 新增 `spawn_codex_app_server_task`，统一经 `tauri::async_runtime::spawn` 派发（生产环境就是 `main` 装的深栈 runtime）；终止、租约 Drop、回合 Drop 三处一起改走它。判据是「调用点可能位于没有 tokio 上下文的线程」，不是「这个函数看起来像异步」。
+- **验证**：新增 `codex_app_server_task_dispatch_needs_no_tokio_runtime_context`——在 `std::thread::spawn` 出来的无上下文线程里调用派发入口，若回退成 `tokio::spawn` 即失败（实测回退后报 `there is no reactor running, must be called from the context of a Tokio 1.x runtime`）。
+- **排障注意**：Release GUI 没有 panic hook、也没有 stderr，panic 文案不会落盘；`diagnostics/application.log` 只会停在崩溃前最后一行（本次停在 `agent.codex_app_server.remote_control disabled` 之后），所以「应用日志没有异常」不能当作「没有 Rust panic」，要结合 WER 事件、minidump 的 fail-fast 参数与调用线程上下文判断。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs`、`apps/ai-game-creator-shell/src-tauri/src/main.rs`（`install_agent_runtime_async_runtime_with_deep_stack`）、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`（`cancel_direct_codex_turn`）。
+
+## 2026-09-16 AGC 壳跑过 `cargo test` 后前端 typecheck 必红：ts-rs 导出把 `generated/*.ts` 重写成另一种形状
+
+- **现象**：在 `apps/ai-game-creator-shell/src-tauri` 跑过 `cargo test` 之后，`npm run ai-game-creator-shell:typecheck` 报 10 条类型错（`src/features/project-workspace/resourceReferences.ts:106-112` 的 `string | undefined` 不能赋给 `string | null`；同文件 134 行的对象字面量带 `type: 'message'`，而 `DirectCodexUserMessageItem` 里没有该字段），`npm run ai-game-creator-shell:build` 也死在 `beforeBuildCommand` 的同一条 typecheck 上。
+- **原因**：crate 里的 ts-rs 导出会按**本机依赖版本**重写 `src/features/project-workspace/generated/DirectCodexUser*.ts`：注释头变成 "This file was generated…"、字符串改双引号、`DirectCodexUserMessageItem` 丢掉 `type: 'message'` 判别字段、并多出一个 `DirectCodexUserMessageEnvelope.ts`。仓库里提交的那份是前端真正依赖的形状（前端按带 `type` 的判别联合写），重写后两边就对不上——错在生成器版本漂移，不在前端。
+- **处理（现行口径）**：不要把重写结果当改动提交。跑过 `cargo test` 或构建后只恢复 `apps/ai-game-creator-shell/src/features/project-workspace/generated/DirectCodexUser*.ts` 的仓库版本，再删掉多出来的 `DirectCodexUserMessageEnvelope.ts`；不要恢复整个 `generated/` 目录，以免误删 DirectThread 的现役绑定。绑定与前端形状冲突时以**已提交的 DirectCodexUser 绑定 + 前端**为基准排查。
+- **验证**：恢复仓库版本后 `npm run ai-game-creator-shell:typecheck` exit 0（`[skill-pack] OK`）；保留重写结果时同一条命令 exit 2。release 构建本身还会在 `src/features/ui-editor/types/` 落下 `BindingChange.ts` / `BindingDTO.ts` 两个无人引用的生成产物；它们不属于前端契约，发现后直接删除，不提交。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/`（ts-rs 导出源）、`apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts`、`apps/ai-game-creator-shell/scripts/build-release.mjs`（`beforeBuildCommand`）。
+
+## 2026-09-16 Node 26 下 vitest 的 jsdom 用例拿不到 window.localStorage
+
+- **现象**：只声明 `@vitest-environment jsdom` 的用例里 `window.localStorage` 是 `undefined`（典型报错 `Cannot read properties of undefined (reading 'clear')`）；而 `appSurface.test.ts` 里同样访问 `window.localStorage` 却一切正常。
+- **原因（已核对，不是推断）**：Node 26 在 `globalThis` 上定义了实验性 `localStorage` 访问器，不传 `--localstorage-file` 时它返回 `undefined`。vitest 0.34 的 jsdom 环境把 jsdom window 的描述符复制到全局时，不会覆盖 `globalThis` 上已存在的键，于是 jsdom 真正的 `Storage` 被 Node 的 `undefined` 顶掉。`appSurface` 之所以不受影响，是因为 `apps/ai-game-creator-shell/tests/appSurface/harness.ts` 自己用 `Object.defineProperty(window, 'localStorage', …)` 挂了内存实现。
+- **处理**：跑这类用例时给 Node 加 `--localstorage-file`，例如 `NODE_OPTIONS="--localstorage-file=/tmp/vitest-node-localstorage" npx vitest run <files>`；`apps/ai-game-creator-shell/tests/clientApi.test.ts` 与 `chatPromptPolish.test.tsx` 加这个开关后 26 项全绿。不要改业务代码或往测试里塞假 storage 来绕过。
+- **关联**：`vitest.config.ts`（`environment: 'node'` + 用例内 docblock 切 jsdom）、`apps/ai-game-creator-shell/tests/appSurface/harness.ts` 的内存 localStorage 垫片。
+
+## 2026-09-17 AGC 壳首页无限 setState：effect 依赖了每次渲染都换身份的普通函数
+
+- **现象**：dev 客户端停在首页、不点任何东西也会持续刷 `WEBVIEW error webview: Maximum update depth exceeded …`（5 秒涨 ~8.5 KB 日志），对应 WebView2 renderer 工作集涨到 **4.2 GB**、CPU 持续累计（约 0.7–1.5 核）；表现上很像"模板库卡片太多/滚动卡"，实际与页面内容无关。
+- **原因**：`WorkspaceLauncher` 里发布"活动项目面板"数据的 effect，依赖数组里带了 `openActiveProject`；它由 `useCallback([openProject, setProjectPath])` 生成，而 `openProject` 来自 `useHomeProjectCreation` 的**普通函数声明**（每次渲染都是新身份）→ `openActiveProject` 每渲染都变 → effect 每渲染重跑 → cleanup/主体调 `setActiveProjectRuns` 改 `WindowChrome` 的 state → 标题栏重渲染 → 又一轮。`WindowChrome` 的 context value 当时还是内联对象，进一步放大了连带重渲染。日志里没有组件栈，是靠在 `console.error` 包装里抓 `new Error().stack`（该日志与 setState 同栈）才定位到 `WorkspaceLauncher.tsx` 的 `commitHookEffectListUnmount → dispatchSetState`。
+- **处理（现行口径）**：① 依赖里只放数据，回调走 ref（`openActiveProjectRef`）——effect 不再因回调换身份而重跑；② `useDirectActiveTurns` 轮询只在快照内容变化时才 `setActiveTurns`（并给空态做引用稳定），避免每 5 秒换一次数组身份去带动下游 effect；③ `WindowChrome` 的 context value 用 `useMemo` 收口。判断类问题的通行判据：**凡是把"每次渲染新生成的函数/对象"写进 effect 依赖的，一律视为 bug**。
+- **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。

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

@@ -51,6 +51,8 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 
 ## AGC DirectProject 与 UI workflow
 
+- AGC 的本地 `llm.customEnabled` 默认关闭，只能手动修改配置文件；开启后设置支持自定义 Responses 端点、读取 `/models`、勾选和预览 `visibleModels`。对话下拉只显示勾选项，LLM 请求经客户端凭据代理直连自定义上游；不会回退官方中转，平台资源服务仍使用账号权限。详见 AGC 后台模型别名与对话选择规范。
+
 - DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。
 - 回合生命周期只由活动 client 回合快照和 Direct 事件恢复；Provider 的历史终态通知不能创建活动 client 回合。消息发送时间保存在历史信封，原始 item 不混入宿主字段；完成后的中间文本和工具默认收进“执行过程”，最终回复及失败提示保持可见。
 

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

@@ -16,6 +16,13 @@
 
 ## 开发中
 
+- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 只在展开正文走既有安全渲染，折叠预览只取纯文本，不在 summary 嵌套链接或按钮。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色，不由自然语言输出猜测。
+
+- Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。
+
+- AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
+
+- 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
 - 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
 - UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
 - AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。