合并最新主分支并保留策划退役清理

合并 origin/master 的最新功能与测试变更

保留已删除的策划 Agent V1/V2 运行时和旧 GDD 入口

仅解决资源预览类型冲突，不恢复退役策划调用

docs/README.md

@@ -39,6 +39,7 @@
 - [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
 - [AGC Cocos Creator 编辑器桥接模块](<./technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md>)：独立 crate、feature 开关、目标校验与 Windows 注入边界。
 - [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、OSS 清单格式和下载约定。
+- [AGC 模板库与模板建项](./technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)：`templates/` 前缀的模板库契约、下载安装与「用模板建项目」链路。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
 - [Direct 回合行为审计账本](./technical/【技术方案】Direct回合行为审计账本-2026-08-31.md)：Direct GUI 回合把 native 读 / MCP / 写文件落成项目内有界时间线，用于判断有没有打开本轮附件。
 - [项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)：当前工作台页面和验收边界。

docs/openapi/genarrative-external-v1.openapi.json

@@ -3363,7 +3363,7 @@
       },
       "EditorIconSpritesheetGenerationRequest": {
         "type": "object",
-        "required": ["referenceId", "iconDescriptions"],
+        "required": ["referenceId", "iconDescriptions", "sliceMode"],
         "properties": {
           "referenceId": {
             "type": "string",
@@ -3395,26 +3395,25 @@
               "connected-components",
               "grid"
             ],
-            "default": "connected-components",
-            "description": "图集切分模式。connected-components 按透明像素 alpha 连通域识别独立素材；grid 按用户提供的 gridX/gridY 划分网格槽。省略时使用 connected-components。"
+            "description": "必填，没有默认值：必须在引用解析、定价、入队和任何 provider / OSS 副作用之前显式声明切分模式。需求明确要求等分网格、固定槽位或指定行列数时传 grid，并用 gridX/gridY 传入来自需求本身的行列数；自由排布、数量不定或只要求一张图集时传 connected-components，需要约束素材张数时用 sliceCount。connected-components 不接受 gridX/gridY，grid 必须同时提供 gridX/gridY（各 1..32）。省略、null 或空字符串返回 400（field=sliceMode），模式与网格参数互相矛盾返回 400（field=gridX/gridY），两者都不会产生计费、入队或 provider 调用。响应中的 sliceMode 回显本次实际采用的模式。"
           },
           "gridX": {
             "type": "integer",
             "minimum": 1,
             "maximum": 32,
-            "description": "grid 模式的横向网格数量。"
+            "description": "grid 模式的横向网格数量，只能与 sliceMode=grid 同时出现；与 connected-components 同时提交返回 400。"
           },
           "gridY": {
             "type": "integer",
             "minimum": 1,
             "maximum": 32,
-            "description": "grid 模式的纵向网格数量。"
+            "description": "grid 模式的纵向网格数量，只能与 sliceMode=grid 同时出现；与 connected-components 同时提交返回 400。"
           },
           "sliceCount": {
             "type": "integer",
             "minimum": 1,
-            "maximum": 100,
-            "description": "connected-components 模式下可选的目标切片数量；省略时按图像内容自动识别。grid 模式的切片数量由 gridX×gridY 决定。"
+            "maximum": 256,
+            "description": "connected-components 模式下可选的目标切片数量（1..256）；省略时按图像内容自动识别上限。识别结果与该目标数量不一致、为 0 或超过 256 时返回 422 并给出实际识别数量，不会静默截断。grid 模式的切片数量由 gridX×gridY 决定，不接受该字段。"
           },
           "screenColor": {
             "type": ["string", "null"],
@@ -3649,7 +3648,7 @@
               "connected-components",
               "grid"
             ],
-            "description": "实际采用的图集切分模式。"
+            "description": "本次实际采用的图集切分模式，与请求显式声明的 sliceMode 一致；图集生成入口不回退到任何默认模式。"
           },
           "gridX": {
             "type": "integer",
@@ -3664,7 +3663,7 @@
           "sliceCount": {
             "type": "integer",
             "minimum": 0,
-            "maximum": 100,
+            "maximum": 256,
             "description": "实际生成的切片数量。"
           },
           "sliceWarning": {

docs/project-memory/plans/【实施计划】AGC客户端更新切换到官方更新插件-2026-09-17.md

@@ -0,0 +1,37 @@
+# 【实施计划】AGC 客户端更新切换到官方更新插件
+
+| 字段      | 值                                                                                  |
+| --------- | ----------------------------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC客户端更新切换到官方更新插件-2026-09-17.md` |
+| Status    | ready                                                                               |
+| Owner     | Codex                                                                               |
+
+## 修改边界
+
+- 允许修改：AGC 客户端原生侧（依赖、插件注册、更新相关命令与其测试）、AGC 前端更新服务与更新提示、「关于」页检查入口、capability 与 Tauri 配置、AGC 客户端测试、主规范与开发运维文档。
+- 明确不修改：发布脚本与 Jenkins（渠道化属于下一个里程碑）、OSS 对象布局、SpacetimeDB、`/api/external/v1`、网站与其它 App。
+
+## 实现顺序
+
+1. 生成发布签名密钥对：私钥落在仓库外 `%USERPROFILE%\.tauri\`，公钥写入客户端配置（公钥发布后不可更换）。
+2. 原生侧：加入官方更新插件依赖并注册；删除自研更新下载命令、下载进度事件、安装器启动逻辑与其专属测试；新增供 macOS 安装后重启的应用命令。
+3. 配置与权限：打开更新产物生成，写入公钥、渠道端点（默认 Windows 渠道）与 Windows 静默安装模式；capability 增加更新权限，并移除只为自研清单放行的 OSS 白名单与 CSP 连接项。
+4. 前端：更新服务改为调用官方插件（检查、下载、进度、安装、重启收敛），删除自研清单解析、版本比较与下载实现；更新提示改用插件进度回调；保留开发态特性开关语义。
+5. 测试：改写更新服务定向用例（开关关闭不发请求、更新元数据映射、失败静默、进度与重启、无待装更新时失败关闭）。
+6. 文档：更新技术方案与开发运维说明，删除自研链路描述。
+
+## 验证命令
+
+1. `npm --prefix apps/ai-game-creator-shell run typecheck`（含 `check-config.mjs` 与 skill-pack 校验）
+2. `npx vitest run apps/ai-game-creator-shell/tests/appUpdate.test.ts apps/ai-game-creator-shell/tests/featureFlags.test.ts apps/ai-game-creator-shell/tests/dev-feature-flags.test.ts`
+3. `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
+4. `npx eslint` / `npx prettier --check`（改动文件）
+5. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+6. 运行时：`npm run agc` 启动不产生更新清单请求；检索确认自研命令、事件与白名单条目无残留。
+
+## 风险与回滚点
+
+- 公钥不可更换：密钥已生成但尚未发布任何签名版本，若需要带密码的私钥仍可在首次发布前重新生成。
+- Windows 安装模式由插件配置决定（本里程碑固定 `quiet`，与旧 PowerShell `/S` 一致）；若改为 `passive` 会多出安装进度条 UI。
+- 插件在 Windows 上安装成功后自行退出进程，前端不再有机会更新界面；提示面板的完成态只在 macOS / Linux 可见。
+- 回滚点：改动集中在客户端与配置，回滚后即可退回自研链路；旧 OSS `agc/latest.json` 在发布管线渠道化前不删除。

docs/project-memory/plans/【实施计划】AGC对话历史分页恢复-2026-09-16.md

@@ -0,0 +1,26 @@
+# AGC 对话历史分页恢复实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [AGC 对话历史分页恢复](./【里程碑】AGC对话历史分页恢复-2026-09-16.md)
+
+## 实施
+
+1. 原生历史读取复用逐行解析，增加消息模式，过滤后分页并返回已有原始消息 ID 游标；保持原始接口默认行为和路径权限。
+2. 工作台首屏与更早消息读取显式请求消息模式，消费游标；加载代次隔离、单飞与 ID 去重。
+3. 合成记录测试复现原始工具页卡住的形状，覆盖旧无 ID、坏行、时间、失败/重复/切项目；临时目录只读重放用户日志。
+4. 前端/原生定向测试、类型、Lint、编码、文档和差异检查通过后，更新问题表及 PR 草稿并本地提交。
+5. 在临时消息投影中标记历史来源，保留 Runtime 所有权语义；刷新合并时只保留非历史来源的待回读消息。补齐「先加载旧页，再 /history，再翻页」的顺序与去重回归，保持尚未落盘用户输入的保留逻辑。
+
+## 边界与停止条件
+
+不调整 Direct 消息呈现归属、不修未证明的写入丢失、不上传日志、不触碰用户项目。必要 API 变化仅为本地 IPC 可选参数和游标字段；无 OpenAPI、SpacetimeDB 或持久化迁移。远程推送/PR/WIP 操作仍待额外确认。
+
+## 验收证据
+
+- 历史消息模型、回合呈现及分页集成共 24 个前端测试通过；包含真实 App 的首屏/更早页、单飞、失败重试、重叠消息、同项目重新加载及离开再进入的迟到响应。
+- 16 个历史原生测试通过；人工日志重放用例在 CI 默认忽略，已在本地单独执行通过。
+- 使用用户提供的原始日志运行修复后的原生读取：44 条现存聊天消息（含 2 条用户消息）分 3 页取回，逐项内容与顺序一致，原文件字节未变；未在仓库保存原始日志。
+- 工作台/Direct 恢复与画布导航的 8 个定向回归通过。真实客户端重新进入与向上翻页尚待用户验收；本次涉及 Rust IPC，需重新构建并启动原生端。
+- 与前面画布/JSON 修复联合复验：119 个前端定向测试、30 个原生测试通过；AGC TypeScript、修改文件 ESLint、编码、文档索引和差异检查通过。
+- 状态只覆盖日志中已经证明的分页卡页，不据此宣称其它可能的未落盘消息也已恢复。

docs/project-memory/plans/【实施计划】AGC更新发布管线渠道化-2026-09-17.md

@@ -0,0 +1,37 @@
+# 【实施计划】AGC 更新发布管线渠道化
+
+| 字段      | 值                                                                        |
+| --------- | ------------------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md` |
+| Status    | ready                                                                     |
+| Owner     | Codex                                                                     |
+
+## 修改边界
+
+- 允许修改：AGC 发布脚本（`apps/ai-game-creator-shell/scripts/build-release.mjs`、`release-upload.mjs` 及其测试）、AGC 发布流水线 `jenkins/Jenkinsfile.ai-game-creator-shell-build`、开发运维与技术方案文档。
+- 明确不修改：客户端插件接入与前端更新服务（上一里程碑已完成）、SpacetimeDB、`/api/external/v1`、网站与其它 App、其它 Jenkins Job。
+- 不执行 OSS 上传：本里程碑只交付脚本、流水线定义与本地可验证产物；真实发布需要单独授权与凭据。
+
+## 实现顺序
+
+1. 发布脚本：解析并校验渠道（渠道与目标平台绑定，未显式指定时按平台取默认渠道），把渠道写进远端清单地址与构建期端点配置。
+2. 清单生成：按渠道产出官方更新插件清单（版本、发布说明、发布时间、平台键与签名），universal macOS 产物同时挂两个平台键；缺少签名或签名为空时失败关闭。
+3. 迁移桥：Windows 渠道额外产出旧协议 sha256 清单，指向同一渠道的最新安装包，供已发布客户端升级到新协议。
+4. 上传：按渠道写版本目录（安装包与签名）与渠道 latest 指针，旧协议指针单独覆盖写。
+5. 流水线：新增渠道参数与签名凭据注入，归档安装包、签名、渠道清单与 commit。
+6. 测试与文档：更新发布脚本单测（渠道校验、清单结构、签名缺失失败关闭、旧协议清单），同步开发运维与技术方案。
+
+## 验证命令
+
+1. `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs apps/ai-game-creator-shell/scripts/cargo-features.test.mjs`
+2. 本地清单 smoke：伪造 bundle 目录 + 真实签名私钥，断言渠道清单与旧协议清单结构、缺少签名时失败关闭
+3. `npm --prefix apps/ai-game-creator-shell run typecheck`
+4. `npm run ai-game-creator-shell:build -- --no-bundle`（渠道端点注入后的构建 smoke；不改版本、不读远端清单、不生成清单）
+5. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`、prettier 与 eslint（改动文件）
+
+## 风险与回滚点
+
+- 版本递增按渠道独立：`dev-win` 与 `dev-mac` 的清单地址不同，互不影响；旧协议指针只由 `dev-win` 写入。
+- 签名缺失即失败关闭：构建机未注入签名私钥时发布中止，不产生半成品清单。
+- 渠道端点写进产物：渠道名一旦发布不可改名（改名等于已发布客户端再也找不到更新）。
+- 回滚点：发布脚本与流水线都在本里程碑内，回滚后客户端仍可用原先的自研清单协议；迁移桥可独立停用。

docs/project-memory/plans/【实施计划】AGC模板库客户端接入-2026-09-17.md

@@ -0,0 +1,59 @@
+# AGC 模板库客户端接入实施计划
+
+Version: 1.0
+Status: active
+Date: 2026-09-17
+Milestone Spec: `docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md`
+
+## 步骤
+
+1. **OSS 库布局与契约**
+   - 在 `agc-dev` 落地 `templates/` 前缀：`index.json`、`v1/<id>/{template.json,template.zip,cover.*}`。
+   - 清单补齐 `tags`、`coverKey/coverWidth/coverHeight/coverSha256`，正文改为 zip（zip 根 == 项目根）。
+   - 模板源落在 `apps/ai-game-creator-shell/template-library/v1/<id>/{meta.json,project/**,cover.*}`；zip 由 `scripts/agc-template-library-publish.mjs` 现场打包（不落仓库）。
+   - 交付：发布脚本（校验 + 打包 + 上传 + 回读校验，支持 `--dry-run` / `--prune`）、`templates/README.md`，以及 5 个模板（3 个空白 + 2 个起步工程）。
+   - 验收：匿名 `GET templates/index.json` 可读，每个 `zipKey` 回读 SHA-256 与清单一致。
+
+2. **Rust 模板库模块**
+   - 新增 `src-tauri/src/template_library.rs`：清单解析与校验、受信任 base、缓存/安装目录、zip 安全解压、安装记录、由模板建项目。
+   - 注册命令 `fetch_game_template_library`、`download_game_template`、`create_automatic_local_game_project_from_template`。
+   - 交付：模块内 8 项单测（schema/重复模板、键前缀、base 校验、解压逃逸、摘要与大小、安装记录、建项目与失败清理）。
+   - 验收：`cargo test --bin genarrative-ai-game-creator-shell template_library` 全绿。
+
+3. **前端状态链路**
+   - `src/features/template-library/templateLibraryModel.ts`（类型与搜索/筛选纯函数）与 `useTemplateLibrary.ts`（拉取、下载、建项目、就地更新已下载状态）。
+   - `useHomeProjectCreation` 增加 `enterCreatedTemplateProject`，复用既有进项目通道。
+   - 交付：9 项模型单测。
+   - 验收：`npx vitest run src/features/template-library` 全绿。
+
+4. **界面接入**
+   - 新增 `src/view/template-library/index.tsx` 全屏页；`LauncherView` 增加 `template-library`；左侧导航加模板库入口。
+   - 首页「灵感推荐」替换为 `TemplateRecommendations`；删除 `InspirationGallery.tsx` 与 `assets/inspiration/`。
+   - `tauri.conf.json` 的 `img-src` 放行受信任 OSS 主机以加载封面。
+   - 验收：模板库页可搜索、筛选、下载、显示已下载并成功建项目；首页推荐位可跳转。
+
+5. **文档与共享记忆**
+   - 主规范 `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`，并在 `docs/README.md` 建索引。
+   - 本里程碑与实施计划；`decision-log.md` 记录库路径、清单 schema、缓存目录与 CSP 约定。
+   - 验收：`node scripts/check-doc-index.mjs` 通过。
+
+## 验证命令
+
+```bash
+cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library -- --ignored
+cd apps/ai-game-creator-shell && npx tsc -p tsconfig.json --noEmit
+npx vitest run apps/ai-game-creator-shell/tests/templateLibraryModel.test.ts apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx
+node scripts/agc-template-library-publish.mjs --source <dir> --dry-run
+npm run check:encoding
+node scripts/check-doc-index.mjs
+git diff --check
+```
+
+## 风险与回退
+
+- **封面走 WebView 直连**：仅放行受信任 OSS 主机；若日后改用后端签名，清单的 `coverKey` 不变。
+- **模板包体积**：下载上限 512 MiB、解压文件数 4096、单文件 256 MiB；超限直接拒绝，不落盘。
+- **清单漂移**：客户端只信「受信任主机 + 对象键」，清单中的地址字段不参与请求。
+- **回退**：清空 `templates/` 前缀即回到空模板库；客户端保留错误与空态展示，不阻断其它功能。

docs/project-memory/plans/【实施计划】AGC画布交互稳定性修复-2026-09-16.md

@@ -0,0 +1,44 @@
+# AGC 画布交互稳定性修复实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [画布交互稳定性修复](./【里程碑】AGC画布交互稳定性修复-2026-09-16.md)
+
+## 修改顺序与边界
+
+1. 将临时诊断收敛成正式回归测试，覆盖窗口 Context 反馈、提示条件和鼠标/触摸板事件。
+2. 稳定工作台打开项目的转发回调，保持最新处理器语义，不改项目加载逻辑。
+3. 解耦运行提示与选择；在原有画布事件链加入右键平移、菜单边界和中断清理，不另建控制器。
+4. 执行定向验证并检查首次加载、平移和原有框选/卡片拖动回归。
+
+## 验证
+
+- 定向 Vitest：窗口工作台、画布交互、布局与原有导航用例。
+- 运行提示的源码契约与交互回归同时覆盖：提示仅取决于运行能力和 UI 编辑器路由，不依赖资源选择；选中资源后提示及 `aria-describedby` 保留，点击运行仍不能进入不可用视图。
+- AGC `tsc --noEmit`；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+- 真实客户端首次进入和触摸板操作无法以 jsdom 代替；未实测时保持待验收。
+
+## 风险与停止条件
+
+窗口反馈测试必须有更新次数上限，避免未修复代码让测试失控。右键仅接管画布背景/卡片，不抢输入控件与浮层。新增问题只有影响本次验收才扩大范围；不根据猜测修改 B01/B02 的布局与动画。
+
+回滚仅限本批局部补丁；不重置工作树，不覆盖其它修改。完成自动化验证后停在真实客户端验收，不推进额外功能。
+
+## 问题状态
+
+| 编号 | 问题 | 状态与证据 |
+| --- | --- | --- |
+| B01 | 刷新后首次进入画布元素抖动 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。不宣称所有布局/动画原因均已排除。 |
+| B02 | 初次进入双指平移无效，整理后恢复 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。隔离组件连续平移通过。 |
+| B03 | 快速平移触发更新深度错误 | 已修复已确认的窗口 Context 反馈循环，回归验证收敛；真实操作继续观察。 |
+| B04 | 资源选中后运行不可用提示消失 | 已修复，提示与选择解耦，自动化验证通过。 |
+| B05 | 对话记录偶发丢失 | 已修复日志复现的历史分页卡点：消息模式过滤后分页、原生游标与读取代次隔离。原生只读重放分 3 页取回全部 44 条现存消息，原文件未变；真实客户端待验收，不扩大为其它未落盘记录已恢复。 |
+| B06 | JSON 文档未正确识别展示 | 已按用户确认完成本地修复：合法 UI State 由原生完整校验，卡片显示 UI 设计并进入现有编辑器；普通 JSON 显示 JSON 并可代码预览。自动化验证通过，待重建原生客户端验收；详见 JSON 语义识别实施计划。 |
+| C01 | 右键平移，保留左键框选 | 已实现，卡片左键拖动、框选、指针取消/失焦/捕获丢失及控件边界测试通过。 |
+
+## 已取得证据与剩余门禁
+
+- 修复前新增回归测试能检出外壳重复发布、运行提示消失和右键无效；修复后窗口/画布定向测试通过，现有导航、框选、指针点击/取消、UI 编辑器返回平移和素材定位用例通过。
+- AGC TypeScript、修改文件 ESLint、编码、文档索引及差异空白检查通过。
+- 测试仍有既有 React 列表 key、旧用例 act/IPC 桩告警，未作为本批功能修复扩大范围。
+- 用户反馈 B01/B02 本轮未再复现，记为已优化；右键手感与其它真实客户端细节继续观察。对话历史分页与 JSON 双路径均已本地修复并通过定向验证，待重建原生端后真实客户端验收。本计划保持开放。

docs/project-memory/plans/【实施计划】AGC资源JSON语义识别-2026-09-16.md

@@ -0,0 +1,27 @@
+# AGC 资源 JSON 语义识别实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [AGC 资源 JSON 语义识别](./【里程碑】AGC资源JSON语义识别-2026-09-16.md)
+
+## 实施边界
+
+1. 原生 UI 持久化模块抽取可复用的内容解析与只读识别；文本预览返回可选的已验证 UI 资产身份。
+2. 保留新设计初始化的严格 UI 资产门禁；已有 State 的加载/保存/生成按登记资源和真实文档校验，不依赖标签精确大小写。
+3. 前端预览缓存透传识别结果；工作台卡片与编辑器入口消费同一结果，普通 JSON 详情使用代码块。
+4. 单元、组件与原生测试覆盖合法/普通/损坏/跨身份/未登记和保存边界；保持先前画布修复。
+
+## 验证与停止条件
+
+- 定向 Vitest、Tauri persistence/resource preview 定向 Rust 测试、AGC TypeScript、修改文件 ESLint、编码、文档索引及 `git diff --check`。
+- 不读取或修改用户项目原文件，不将日志或真实对话作为仓库测试夹具。
+- 原生构建/真实客户端受环境限制时记录实际证据，不能以 TS 测试代替原生验证。
+- 完成上述范围后停止；B05 已有分页卡点证据，本轮不顺带修改历史合同。
+
+## 验证结果
+
+- 92 个前端定向测试通过，覆盖原生结果驱动的卡片/编辑器路由、普通 JSON 代码预览、伪 UI 文本拒绝、读取失败、缓存切项目，以及原有画布导航与指针回归。
+- 14 个 UI 持久化原生测试通过，包含有效 State 对多种登记标签的识别/加载/保存、未知 schema/字段与坏结构拒绝、项目/资产身份、普通 JSON 防覆盖及原有恢复/CAS 边界。
+- 原生测试在 macOS 默认 `/var` 临时路径触发既有拒绝符号链接门禁；改用真实 `/private/tmp` 后通过，未放宽产品路径安全校验。
+- AGC TypeScript、修改文件 ESLint 已通过。测试仍有既有 React key/act 告警及 Rust 未使用代码警告，不影响本批断言。
+- 真实客户端的图片/UI State 体验仍待验收。本次包含 Rust 预览字段，必须重新构建并启动原生端，不能仅刷新前端就认为识别结果已更新。

docs/project-memory/plans/【实施计划】AGC资源菜单收纳-2026-09-17.md

@@ -0,0 +1,16 @@
+# AGC 资源菜单收纳实施计划
+
+对应：[里程碑](./【里程碑】AGC资源菜单收纳-2026-09-17.md)，Issue #409，产品已确认方案 A。
+
+## PR #410 CI 修复
+
+以远端合并提交 959beebf 为基线：修复菜单文件 import 排序、Web 角标结构断言、活动回合空快照与晚到请求竞态；窗口发布次数断言对齐稳定快照合同。原生 HTTP scope 检查对齐官方 updater 当前权限，不恢复退役 OSS 白名单；Rust 图集测试补齐显式切片模式与 strict schema 字段，不放宽正式校验。按故障项定向测试后运行前端全套及原生契约检查；Rust 使用独立 target，实际未执行的检查必须单独列出。推送需再次确认。
+
+本地修复验证：`npm test` 342 个文件通过（4137 项通过、37 项跳过），窗口与空快照最后一次定向复验 9 项通过；`lint:eslint`、根目录/AGC 类型检查、原生 contract 检查、Rust fmt、编码、文档索引与 diff 检查通过。Rust 工具目录 schema 用例及后台平台美术生成用例均在 Windows 独立 target 下通过；生成用例同时检查真实 mock 请求中的 grid、2×2 参数与响应匹配。未执行全量 Rust 分片、Linux CI、生产服务或真实客户端手感验收。
+
+1. 在 shared 扩展通用操作收纳及卡片角标控件；共用工具栏只给 AGC 开启 5 项限制，Web 卡片迁移共用角标而不改现有回调。
+2. AGC 卡片承接类型和信息，保留当前面板与命令链；信息使用资源身份防止换选竞态。
+3. 补工具栏/工作台定向回归，检查禁用、移入、Escape、换选和卡片事件边界。
+4. 并行执行定向 Vitest、AGC 类型检查、编码与文档索引检查，再自审整体调用链。
+
+风险：portal 浮层点击外部判定、缩放角标与拖拽冲突、原测试依赖完整工具栏。回滚仅撤销本分支 UI 与文档修改；无数据迁移。首个检查点为组件用例通过，第二个为工作台集成与类型检查。真实客户端未测则明确保留待验收状态。

docs/project-memory/plans/【实施计划】AGC项目定时快照上传-2026-09-17.md

@@ -0,0 +1,43 @@
+# AGC 项目定时快照上传实施计划
+
+Version: 1.0
+Status: active
+Date: 2026-09-17
+Parent Milestone: `【里程碑】AGC项目定时快照上传-2026-09-17.md`
+
+## 修改边界
+
+1. `server-rs/crates/shared-contracts/src/`：新增 `agc_project_snapshots` DTO（单文件上传请求/响应、同步清单信封），只放共享字段，不放 OSS 细节。
+2. `apps/ai-game-creator-shell/src-tauri/src/project_snapshot/`：新增客户端模块，包含扫描与排除规则、索引读写、差异对比、上传编排、状态与日志；不修改 `project/` 下既有 manifest 与写锁语义。
+3. `apps/ai-game-creator-shell/src-tauri/src/main.rs`：注册新模块、命令与生命周期钩子；`windows.rs` 的窗口关闭与应用退出路径接入触发调用，不改变现有窗口创建/关闭顺序。
+4. `server-rs/crates/platform-oss/src/lib.rs`：新增项目快照私有前缀常量与（必要时）独立 bucket 配置入口；不改动既有前缀枚举语义与资源写路径。
+5. `server-rs/crates/api-server/src/project_snapshots.rs`：新增路由、鉴权、校验与 OSS 写入；不改动 `error_reports` 与 `assets` 既有路由。
+6. `.env.example`：补充 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_*` 说明与默认值。
+7. `docs/`：主规范已更新；完成后把持久结论合并回主规范并删除本计划。
+
+## 实现顺序
+
+1. 先写 `shared-contracts` DTO 与客户端差异引擎（扫描、排除、索引、diff）及单测，此时无网络依赖，可独立验证。
+2. 接上传编排：按差异集合逐文件提交，成功后再提交清单，最后推进索引；用本地 TCP stub server 覆盖成功、幂等跳过、鉴权失败与部分失败路径。
+3. 接触发接线：周期定时器、工作区窗口关闭与应用退出；确认关闭路径的有界超时和串行化。
+4. 最后接服务端路由与 OSS 写入，补参数校验与幂等跳过测试；服务端完成前客户端按"未配置即失败关闭、不写入索引"处理。
+
+每一步都保留既有失败关闭行为；新模块默认不改变其它同步路径（Runner、项目写锁、Resource Editor）。
+
+## 验证命令
+
+- `cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check`
+- `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot -- --nocapture`
+- `cargo test -p api-server --bin api-server project_snapshots -- --nocapture`
+- `cargo fmt -p api-server -p shared-contracts -p platform-oss -- --check`
+- `npm run --prefix apps/ai-game-creator-shell typecheck`（若触及前端）
+- `npm run check:encoding`
+- `git diff --check`
+- 运行时按需：`npm run agc` 打开项目观察索引写入与同步日志，关闭窗口确认关闭触发。
+
+## 风险与回滚
+
+- 上传体积与带宽：首轮全量可能很大，先设单文件与单次同步总量上限并把超限项记入跳过清单；不静默截断。
+- 数据出境边界：只上传项目目录内普通文件，排除 `.agent/runtime`、`.agent/logs`、`.git`、构建产物与临时文件；凭据类文件不在白名单内。
+- 服务端未配置 bucket 时客户端必须失败关闭，不能把本地索引推进成"已同步"，否则后续同步会漏传。
+- 回滚：客户端可停用触发接线（保留模块与测试）即可回到无上传行为；服务端路由与配置项可单独移除，不影响既有 OSS 前缀与错误报告链路。

docs/project-memory/plans/【实施计划】图集切片模式显式决策-2026-09-17.md

@@ -0,0 +1,39 @@
+# 【实施计划】图集切片模式显式决策
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】图集切片模式显式决策-2026-09-17.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：`server-rs/crates/api-server`（图标图集生成入口、错误体、画板 Agent 工具装配、OpenAPI 契约测试）、平台画板前端（`src/services/image-editor`、`src/components/image-editor`）、AGC 客户端（`apps/ai-game-creator-shell/src-tauri` 的 MCP 工具说明、桥接校验、原生工具 schema、图集生成选项与调用方、AGC Skill）、`.codex/skills/genarrative-external-editor-api`、`docs/openapi/genarrative-external-v1.openapi.json`、主规范与共享记忆。
+- 明确不修改 `platform-editor-agent`：画板 Agent 的工具参数不变，其链路在装配层固定显式声明 `connected-components`，画板因此不具备网格生成入口。
+- 明确不修改：拆分 / 去背 / 像素规整算法、切片上限、手动拆分入口行为、SpacetimeDB schema、旧版本客户端兼容分支。
+
+## 实现顺序
+
+1. 平台入口：`sliceMode` 由可选改必填并校验模式自洽性，失败发生在引用解析、定价、入队之前。
+2. 公开契约：OpenAPI 请求体去掉默认值、补必填与失败语义，并补契约测试。
+3. 平台自有调用方显式声明模式：画板 Agent 工具装配（固定连通域）、画板前端提交计划（固定连通域）。
+4. AGC 客户端：MCP 工具说明与桥接校验、原生工具 schema 与观察器、图集生成选项与全部调用方、AGC Skill 与外部 MCP 说明。
+5. 错误可执行性：切片模式按原始字符串接收后逐项校验，统一返回 `field`、允许取值与决策分支；`sliceCount` 契约上限与切片上限对齐。
+6. 反馈闭环：生成结果回显生效声明与切片路径，严格图集在本地提交前校验回显与请求一致。
+7. 标准美术包显式声明 `connected-components` + `sliceCount=4`，用途映射前校验切片数量正好为四。
+8. 测试环境：为提权 Windows 主机上的 `%TEMP%` 所有者偏差补测试构建专用的所有者初始化重试（仅限临时目录内、且失败原因为所有者不匹配）。
+9. 文档与共享记忆同步，最后运行定向验证与编码 / diff 检查。
+
+## 验证命令
+
+1. `cargo test -p api-server editor_icon_spritesheet`（名称按实际测试筛选）
+2. `cargo test -p platform-editor-agent`
+3. `npm run test -- src/services/image-editor/editorProjectClient.test.ts`（按仓库既有前端测试入口）
+4. `cargo test -p ai-game-creator-shell` 定向筛选 `slice_mode` / `generate_image`
+5. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+
+## 风险与回滚点
+
+- 风险 1：已发布的 AGC 客户端与第三方外部 API 调用方在未更新前会因缺失 `sliceMode` 收到 `400`。回滚点为「恢复服务端兜底读取连通域」，但该兜底与本次里程碑目标冲突，需产品确认后再引入过渡期。
+- 风险 2：AGC 原生工具 schema 从“可选”改为“显式声明”，自主运行时可能出现一轮可修复的工具参数失败。回滚点为「保留 schema 字段但收回 description 中的强制措辞」。
+- 风险 3：画板前端显式声明模式后，画板自身不再具备网格生成能力；需要网格时改用外部 API 或后续单独开放画板入口。

docs/project-memory/plans/【里程碑】AGC macOS渠道更新落地-2026-09-17.md

@@ -0,0 +1,46 @@
+# 【里程碑】AGC macOS 渠道更新落地
+
+| 字段        | 值                                                                 |
+| ----------- | ------------------------------------------------------------------ |
+| Version     | 1.0                                                                |
+| Status      | deferred                                                           |
+| Date        | 2026-09-17                                                         |
+| Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |
+
+## 目标
+
+`dev-mac` 渠道可产出并发布 macOS 更新包，客户端在 macOS 上完成检查、安装与重启接管新版本。
+
+## 范围
+
+- macOS 更新产物：按 universal 目标构建（Intel 与 Apple Silicon 共用一个包），更新包与其签名按渠道约定生成并上传，清单把同一对象挂到两个 macOS 平台键。
+- macOS 安装后的重启收敛：安装完成后由客户端重启进程运行新版本，不依赖安装程序代为重启。
+- macOS 代码签名与公证依赖的确认与记录：未签名或未公证的产物视为不可发布。
+- macOS 构建执行环境（本机 mac 或新增 macOS 节点）与渠道发布的衔接方式。
+
+## 不在范围内
+
+- Windows 渠道行为调整。
+- 微软商店或 App Store 分发。
+- 更新包体积优化与增量更新。
+
+## 依赖与前置条件
+
+- 客户端插件化与发布管线渠道化两个里程碑已验收。
+- macOS 签名证书与公证凭据可用；若不满足，本里程碑只能交付构建与清单能力，并明确标注未验证项。
+- macOS 通用包所需的双架构工具链（两个 darwin 目标）在构建机上可用。
+
+本里程碑暂缓执行：macOS 构建机与签名 / 公证凭据尚未就绪，改由后续独立变更承接；暂缓期间 dev-mac 渠道不发布。
+
+## 验收标准
+
+- [ ] `dev-mac` 渠道清单包含两个 macOS 平台条目且指向同一个 universal 安装包与签名，对象在 OSS 上一致可下载。
+- [ ] macOS 客户端能完成一次真实更新：检查、下载、安装、重启后运行新版本，且升级后产物仍是 universal 包。
+- [ ] 覆盖写渠道 latest 指针后，旧版本 macOS 客户端可升级到新版本；Windows 与 macOS 渠道互不干扰。
+- [ ] 未签名或未公证产物在发布阶段失败关闭，或在不满足条件时明确记录为未验证项而非静默通过。
+
+## 证据要求
+
+- 自动化：macOS 更新产物选择与清单生成用例、仓库门禁。
+- 运行时：macOS 上一次真实更新闭环（含重启后版本核对），OSS 对象与清单核对。
+- 边界：签名校验失败、公证缺失、渠道缺少 macOS 平台条目、跨架构不匹配时的表现。

docs/project-memory/plans/【里程碑】AGC客户端更新切换到官方更新插件-2026-09-17.md

@@ -0,0 +1,45 @@
+# 【里程碑】AGC 客户端更新切换到官方更新插件
+
+| 字段        | 值                                                                 |
+| ----------- | ------------------------------------------------------------------ |
+| Version     | 1.0                                                                |
+| Status      | approved                                                           |
+| Date        | 2026-09-17                                                         |
+| Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |
+
+## 目标
+
+客户端自动更新的检查、下载、签名校验与安装改由 Tauri 官方更新插件承担，前端只保留触发与展示，并按渠道读取清单；开发态继续不检查更新。
+
+## 范围
+
+- 官方更新插件在客户端两侧接入：原生侧注册与配置，前端调用官方 API 替代自研检查与下载。
+- 渠道作为构建期常量进入客户端：每个渠道的产物只读该渠道清单，运行期不切换渠道。
+- 保留并复核现有开发态特性开关语义：开发态不检查更新、不显示更新入口。
+- 更新能力只授予客户端主窗口。
+
+## 不在范围内
+
+- 发布管线与 OSS 对象布局的渠道化改造。
+- macOS 产物落地、签名与公证。
+- 旧客户端迁移桥（是否保留旧清单指针）。
+
+## 依赖与前置条件
+
+- 发布签名公钥可用；公钥写入客户端配置，来源见主规范未决问题。
+- 渠道清单地址与对象布局按主规范约定确定，渠道集合固定为 `dev-win` 与 `dev-mac`。
+- 官方插件版本与当前 Tauri 主版本兼容。
+
+## 验收标准
+
+- [ ] 正式包走官方更新插件的检查与安装路径；更新包校验失败时必须拒绝安装并清理临时文件。
+- [ ] 客户端只请求本渠道清单，且不因清单缺失、格式错误或网络失败阻塞启动。
+- [ ] 开发态启动不产生任何更新清单请求，也不显示更新入口。
+- [ ] 更新能力只授予客户端主窗口，其它窗口调用被拒绝。
+- [ ] 自研清单解析、下载命令、下载进度事件与相应的 CSP / HTTP 白名单放行整条删除，无残留兼容分支。
+
+## 证据要求
+
+- 自动化：前端定向用例（渠道映射、开发态开关、失败关闭）、原生侧定向用例、类型检查与仓库门禁。
+- 运行时：`agc` 开发启动无清单请求；使用测试渠道清单完成一次真实检查与安装闭环（含升级后重启）。
+- 边界：签名不匹配、下载中断、清单 404、渠道缺少当前平台条目、非主窗口调用。

docs/project-memory/plans/【里程碑】AGC对话历史分页恢复-2026-09-16.md

@@ -0,0 +1,20 @@
+# AGC 对话历史分页恢复
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：DirectProject 回合展示唯一归属](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 范围与评审
+
+用户已要求修复 B05。已用用户提供的原始日志只读复验：原始切片被工具/推理填满时，聊天投影为空，消息游标不推进。修复聊天读取与分页，不改历史写入、不删除记录、不修改模型上下文，不扩大到其它尚无证据的对话丢失原因。
+
+采用已有切片接口的显式消息模式与原生游标。原始模式缺省行为保持不变，旧无 ID 消息保留；前端以项目和加载代次隔离结果。本轮不包含远程写入。
+
+## 验收
+
+1. 工具/推理密集、末尾无消息、纯工具历史均不产生空页死循环。
+2. 消息正文、原始 ID、时间和顺序保持不变，翻页能到达早期用户提问及最终回答，不重复。
+3. 连点、请求失败重试、项目切换和同项目重新加载不会污染消息或游标。
+4. 原始切片默认模式回归通过，用户日志只读重放可以取回全部现存消息；不把真实日志或对话正文提交到仓库。
+5. 加载更早消息后重新读取历史，旧页不出现在最新回复之后；再次翻页保持顺序且不重复。未落盘的实时用户输入不因历史刷新被丢弃。

docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md

@@ -0,0 +1,47 @@
+# 【里程碑】AGC 更新发布管线渠道化
+
+| 字段        | 值                                                                 |
+| ----------- | ------------------------------------------------------------------ |
+| Version     | 1.0                                                                |
+| Status      | approved                                                           |
+| Date        | 2026-09-17                                                         |
+| Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |
+
+## 目标
+
+构建与发布管线按渠道产出官方更新插件要求的清单与签名产物并上传到渠道路径，发布入口可通过渠道参数在渠道之间切换。
+
+## 范围
+
+- 构建期按渠道生成清单：版本按渠道独立递增，清单包含该渠道平台的下载地址与签名；`dev-mac` 的 universal 包按同一地址与签名同时写入 `darwin-aarch64` 与 `darwin-x86_64`。
+- 构建期生成更新产物签名，并在缺少签名私钥或私钥不可用时失败关闭。
+- 渠道参数与目标平台绑定校验：Windows 目标只能发布 `dev-win`，macOS 目标只能发布 `dev-mac`；未显式指定时按目标平台取默认渠道。
+- 上传按渠道落位：安装包与签名进版本目录，清单覆盖写渠道路径的 latest 指针。
+- Jenkins 流水线增加渠道参数与签名凭据注入，凭据不落盘、不进日志、不进归档。
+
+## 不在范围内
+
+- 客户端侧的更新链路改造。
+- macOS 构建环境建设与 mac 产物签名、公证。
+- 旧客户端迁移桥；若决定保留，作为本里程碑的可选增量单独评审。
+
+## 依赖与前置条件
+
+- 客户端切换到官方更新插件的里程碑已验收：清单格式、公钥与客户端期望一致。
+- 签名密钥对已生成并进入构建凭据，公钥已写入客户端配置。
+- OSS 上传凭据与既有发布入口可复用。
+
+## 验收标准
+
+- [ ] 指定渠道发布时该渠道清单版本按渠道独立递增，另一个渠道清单不受影响。
+- [ ] 渠道与目标平台不匹配、缺少签名私钥或私钥密码错误时发布失败关闭，不产生半成品清单。
+- [ ] 发布后 OSS 上安装包、签名与渠道清单三者一致：清单内地址指向已存在的对象，签名与安装包匹配。
+- [ ] universal macOS 产物的两个平台键指向同一对象同一签名，不存在只挂单一架构键或指向不存在对象的情况。
+- [ ] Jenkins 归档与日志中不出现签名私钥内容，凭据只注入构建进程。
+- [ ] 未显式指定渠道时按目标平台取默认渠道，且 `--no-bundle` smoke 路径仍不读远端版本、不改版本、不生成清单。
+
+## 证据要求
+
+- 自动化：发布脚本单测（渠道解析与校验、版本递增、清单结构、签名缺失失败关闭）、仓库门禁。
+- 运行时：一次真实渠道发布加 OSS 对象核对（清单、安装包、签名），并用该清单触发一次客户端更新闭环。
+- 边界：渠道与平台不匹配、签名密钥缺失、远端清单 404、远端清单格式非法、重复发布时的 latest 覆盖。

docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md

@@ -0,0 +1,40 @@
+# AGC 模板库客户端接入
+
+Version: 1.0
+Status: active
+Date: 2026-09-17
+Parent Spec: `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`
+
+## 目标
+
+AGC 客户端能读取公共 OSS 上的游戏模板库，并把「浏览 → 筛选 → 下载 → 用模板建项目」做成一条可用链路，模板更新不再依赖客户端发版。
+
+## 范围
+
+- OSS `templates/` 前缀的库布局、清单 schema、封面与 zip 元数据契约。
+- Rust 侧读取清单、下载安装、由模板创建项目的命令与安全边界。
+- 模板库全屏页（搜索、标签/运行时筛选、仅看已下载）、首页模板推荐位、左侧导航入口。
+- 仓库内发布脚本与文档、模板库定向单测与类型检查。
+
+## 不做
+
+- 不做模板制作工具、模板审核、模板计费与推荐算法。
+- 不做模板增量更新（按 `templateVersion` 全量重下）。
+- 不把模板回填进已创建项目，也不改写用户项目内容。
+- 不放宽现有项目私有 DACL、下载摘要校验和受信任 OSS 主机边界。
+
+## 验收标准
+
+1. `fetch_game_template_library` 能读到清单并合并本机已安装状态；远端不可用时回退本机缓存并标明 `source=cache`。
+2. `download_game_template` 对字节数与 SHA-256 不一致、越界对象键、非 `templates/` 前缀的包一律拒绝，且不落半成品目录。
+3. zip 解压拒绝绝对路径、`..`、盘符、符号链接；安装完成后才写 `installed.json` 作为已下载判据。
+4. `create_automatic_local_game_project_from_template` 建出的项目同时具备模板文件、`.agent` 清单与标准目录；失败时不留项目目录。
+5. 模板库页可按关键词、标签、运行时与「仅看已下载」筛选；卡片显示封面与已下载徽标；已下载且版本一致时不再显示下载入口（落后显示「更新」）；过程提示以浮层 toast 呈现，不占页面内位置；「使用模板」在版本落后时先重下再建项。
+6. 首页推荐位展示模板库内容并可进入模板库页；左侧导航有模板库入口且为独立全屏页。
+7. 定向 Rust 单测 9 项（含线上清单 fixture）、前端模型 9 项 + 页面/推荐位 8 项、`tsc` 类型检查、`npm run check:encoding`、`git diff --check` 全部通过；可选真连检查能读线上清单、下载安装线上模板并据此建项目。
+
+## 依赖
+
+- 现有自动工作区建项链路（`create_automatic_local_game_project_at` / `init_local_game_project_at`）。
+- 现有 AGC 更新通道使用的受信任 OSS 主机与 CSP 白名单口径。
+- 仓库 OSS 凭据（本机 `.env.secrets.local` 的 `ALIYUN_OSS_*`）与 `scripts/agc-template-library-publish.mjs`。

docs/project-memory/plans/【里程碑】AGC画布交互稳定性修复-2026-09-16.md

@@ -0,0 +1,26 @@
+# AGC 画布交互稳定性修复
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：资源画布交互与工作台状态同步](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与范围
+
+完成工作台标题栏状态更新循环、运行提示随选择消失、右键平移三项本地修复，保持左键框选与卡片拖动。不修改布局算法、持久化和后端；不开远程 Issue/PR、不推送。
+
+## 评审
+
+依据已完成的源码追踪、客户端错误日志及有界复现自检：状态归属仍在窗口与工作台原有边界内；交互修改只影响画布手势；没有数据迁移、权限或 API 变化。用户已确认右键平移及保留左键框选，并授权先尝试本地修复。真实客户端首次进入抖动与触摸板平移仍需另行验收。
+
+## 验收
+
+1. 工作台发布窗口状态后收敛；重复渲染不持续更新或清理，打开项目回调使用最新处理器，卸载清理有效。
+2. 选中资源后运行不可用提示仍在，运行能力不变。
+3. 子画布空白处及卡片右键平移不改变选择或坐标；左键框选与卡片拖动保留；总览支持右键平移。
+4. 指针取消、失去捕获、窗口失焦终止平移；控件与浮层保留原有交互。
+5. 连续平移测试、定向测试、类型检查、编码与文档门禁完成并记录限制；B01/B02 仅在真实复测后决定关闭。
+
+## 依赖
+
+当前源码与已安装测试依赖；真实 AGC 客户端验收环境。没有外部写操作依赖。

docs/project-memory/plans/【里程碑】AGC资源JSON语义识别-2026-09-16.md

@@ -0,0 +1,26 @@
+# AGC 资源 JSON 语义识别
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：文档与代码素材预览](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与边界
+
+按用户确认同时支持普通 JSON 与 UI 设计 JSON：前者显示 JSON 并可代码预览，后者显示 UI 设计并进入原有编辑器。原生侧复用现有文档校验，前端不推断正式状态。不修改 manifest 分类，不迁移用户文件，不改历史分页，不做远程写入。
+
+## 评审
+
+已核对原生受控文本预览、UI State 持久化合同和工作台卡片/编辑器路由。复用完整读取结果识别，未知 schema/坏结构/身份不符均不授予编辑入口；已有 UI 资产的大小写标签不应阻断真实合法 State。新增可选预览字段只承载原生识别结果；不引入新的状态文件或平行编辑器。
+
+## 验收标准
+
+1. 普通 JSON 显示 JSON，不渲染卡面原文，不出现 UI 编辑器入口，显式预览为 JSON 代码块。
+2. 完整合法且身份匹配的 UI State 显示 UI 设计并进入现有编辑器；大小写标签或文档标签不影响内容识别。
+3. 损坏 JSON、伪 schema、未知字段、坏 State、跨项目/资产、未登记文件不能获得 UI 编辑入口；原文查看或读取错误仍可见。
+4. 识别不产生写入；普通 JSON 不能通过编辑器保存或初始化被覆盖。有效已有设计仍支持原有 CAS 保存。
+5. 预览缓存能传递原生结果并随资源身份失效；原有卡片、框选/平移和图片预览回归通过。
+
+## 依赖
+
+本地前端与 Tauri 源码、现有测试依赖；真实客户端体验单独验收。

docs/project-memory/plans/【里程碑】AGC资源菜单收纳-2026-09-17.md

@@ -0,0 +1,31 @@
+# AGC 资源菜单收纳
+
+- Version: 1
+- Status: implemented，本地自动化通过，待真实客户端验收
+- Date: 2026-09-17
+- Parent Spec: ../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+
+## 范围与评审
+
+仅调整前端入口和临时浮层状态，不修改资源命令、权限、持久化、后端或 Web 默认菜单行为。主菜单保留前 5 项，其余悬停/点击向上展开；类型与信息下沉卡片。产品已选定方案 A，边界与既有资源操作合同无冲突，按单里程碑实施。对应 Issue #409，已获得创建 Issue 与本地实施授权；推送、PR 与飞书写入仍需单独确认。
+
+## 验收
+
+- 动作顺序、禁用状态和回调保持一致，少于等于 5 项不出现更多。
+- 更多支持鼠标移入浮层、点击、键盘、外部关闭与视口约束。
+- 卡片类型、信息入口不触发拖拽；未选中卡直接看信息，换选不残留旧信息。
+- 定向组件与工作台测试、类型检查、编码/文档索引/diff 检查通过；真实客户端视觉和触摸板手感单独验收。
+
+## 产品结论与验收待办
+
+正式实现采用方案 A；方案 B 不进入工作台，A/B 演示只留在忽略目录供本地参考。
+
+完整工作台回归的 2 项失败已定位为新增信息按钮导致“版本 1”模糊匹配重复，改为精确查询资源选中按钮，完整重跑通过。
+
+## 验收证据
+
+- `appSurface.test.ts`：450 项通过、20 项跳过。
+- 收纳/卡片、Web 工具栏/卡片、资源类型实时链路、替换/重命名、浮层判据、动作可用性：178 项通过；追加真实工作台「更多滚轮不平移画布、Escape 仅收菜单、换选收起」与「跨卡片信息身份」2 项通过。
+- 根目录类型检查与 AGC 类型检查（含 skill-pack / config 检查）通过；编码、文档索引与 diff 检查通过。
+- 浏览器中真实组件预览已检查上方展开、执行回调后关闭、卡片信息入口；预览仅用演示数据，不替代真实 AGC 客户端。
+- 剩余：真实客户端、原生保存对话框、触摸板操作人工验收。未推送，未创建 PR，未更新飞书。

docs/project-memory/plans/【里程碑】AGC项目定时快照上传-2026-09-17.md

@@ -0,0 +1,49 @@
+# AGC 项目定时快照上传
+
+Version: 1.0
+Status: active
+Date: 2026-09-17
+Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-17 AGC 项目定时快照上传（agc-dev）”
+
+## 目标
+
+AGC 在项目打开期间按周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；只上传内容发生变化的文件，重复内容不重复上传，远端缺少对应对象时才新建。
+
+## 范围
+
+- 客户端 `src-tauri/src/project_snapshot/`（`scan.rs` / `diff.rs` / `index.rs` / `transport.rs`）：项目扫描、排除规则、增量索引与差异对比、上传编排、状态查询。
+- 触发接线：工作区窗口存活周期定时器、工作区窗口关闭（`CloseRequested`）；应用退出只做有界等待，不重复发起同步。
+- 服务端 `POST /api/agc/project-snapshots/files` 与 `POST /api/agc/project-snapshots/manifest`：登录态鉴权、参数校验、私有前缀 OSS 写入、HEAD 幂等跳过。
+- 目标 bucket 配置：`GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_*`，默认 `agc-dev`。
+- 契约：`shared-contracts::agc_project_snapshots` 新增请求/响应 DTO 与项目 ID、相对路径、摘要校验函数。
+- 客户端增量索引：`<AppData>/project-snapshots/<projectId>/index.json`，按用户身份判等，换号后按冷启动全量重算。
+- 排除口径：复用 `should_skip_project_snapshot_path`（整个 `.agent`、`.git`、构建与依赖目录、凭据目录、敏感后缀、符号链接与重解析点）。
+
+## 不做
+
+- 不做云端下载/恢复、跨设备合并、版本回滚。
+- 不保留多版本历史：清单写入成功后回收不再被引用的旧对象，同一路径只保留当前内容。
+- 不下发 bucket 生命周期策略；不做跨节点的用户级总量配额与计费口径。
+- 不新增 SpacetimeDB 表或 procedure，不修改 `/api/external/v1` 与 External OpenAPI。
+- 不在客户端暴露上传状态、时间线或入口按钮；状态只落本机诊断日志，排障走 native-only 命令。
+
+## 验收标准
+
+1. 首次同步上传项目内全部符合条件的普通文件；再次同步在无改动时上传 0 个文件。
+2. 只修改一个文件时，差异集合恰好包含一个修改项；删除一个文件时上传集合为空且清单中不再包含该文件。
+3. `(字节数, 修改时间)` 未变的文件复用已存摘要，不重复读取内容计算摘要。
+4. 排除规则命中项（`.agent/runtime`、`.agent/logs`、`.git`、`node_modules`、构建产物、临时文件、符号链接）与超限文件进入跳过清单，不进入上传集合。
+5. 任一次同步失败（非鉴权类）不推进本地索引，下一次触发重算并重试；鉴权/权限类失败不自动重试。
+6. 同一项目的并发触发串行执行，不产生两路重复上传。
+7. 工作区窗口关闭与应用退出都会触发一次同步，且关闭路径不因同步失败而阻塞退出超过超时上限。
+8. 服务端拒绝越界 `projectId`、相对路径与摘要；相同摘要重复提交走跳过分支且不写入新对象。
+9. 新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。
+10. 清单写入成功后，上一版清单里不再被引用的对象被回收；上一版清单不可读时整轮不删除任何对象。
+11. 单项目超过 2 GiB 时客户端明确失败、服务端按 413 拒绝；超过服务端小时配额或 5 秒最小间隔时返回 429 且带 `Retry-After`。
+12. 同步期间被改写的文件既不上传也不推进索引，沿用上一轮记录，且不会被误判成删除。
+
+## 依赖
+
+- 现有 `platform_session`（用户身份与 Access Token）、项目 manifest（稳定 `project_id`）。
+- 现有 `platform-oss`（PUT/HEAD、私有访问）、`api-server` 登录态中间件与 `shared-contracts`。
+- 现有 AppData 私有文件写入与目录解析工具。

docs/project-memory/plans/【里程碑】图集切片模式显式决策-2026-09-17.md

@@ -0,0 +1,49 @@
+# 【里程碑】图集切片模式显式决策
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-17 |
+| Parent Spec | `docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md` |
+
+## 目标
+
+图标图集生成的切分模式不再具备任何隐式默认：平台入口、AGC 客户端自有流程、画板前端和所有 Agent / 工具说明都必须在请求中显式声明 `sliceMode`，并在同一份决策要求下选择 `connected-components` 或 `grid`。
+
+## 范围
+
+- `sliceMode` 在图标图集生成入口成为必填；缺失、`null`、空字符串在副作用之前失败关闭。
+- `grid` 与 `connected-components` 的参数自洽性：`grid` 必须带行列数，连通域不得携带网格尺寸。
+- 决策要求写入主规范、公开契约、MCP / Agent 工具说明、Skill 与客户端自有路径，口径一致。
+- 依赖平台默认值的自有调用方全部改为显式声明，且不新增兜底分支。
+- 失败信息可执行：所有拒绝路径都带字段名与决策要求，`sliceCount` 的目标数量与上限语义在契约中写清。
+- 端到端可证明：生成结果回显生效的切分声明与切片路径，严格图集在本地提交前校验回显与请求一致。
+- 标准美术包显式声明四张 canonical 切片的切分声明，并在用途映射前校验切片数量正好为四。
+
+## 不在范围内
+
+- 不改动图集生成、去背、像素规整、拆分算法本身和切片上限。
+- 不新增切分模式，不恢复已退役的固定网格契约。
+- 不改动手动 `拆分图集` 入口的既有行为。
+- 不为旧版本客户端保留过渡性兜底。
+
+## 依赖与前置条件
+
+- 无外部依赖；`sliceMode`、`gridX`、`gridY` 契约字段已在现行版本存在。
+
+## 验收标准
+
+- [ ] 省略 / `null` / 空字符串 `sliceMode` 的图集生成请求在定价、入队、扣费和 provider 调用之前返回 `400`，错误体含 `field=sliceMode`。
+- [ ] `grid` 缺 `gridX` 或 `gridY`、越界、乘积超限时 `400`；`connected-components` 携带 `gridX`/`gridY` 时 `400`。
+- [ ] 公开契约、MCP / Agent 工具说明、Skill 与画板前端类型都要求显式声明，且不再声明任何默认值。
+- [ ] AGC 客户端与画板前端的所有图集生成路径都显式传入模式，不再依赖平台兜底。
+- [ ] 响应回显的 `sliceMode` 与请求声明一致；`grid` 时同时回显行列数。
+- [ ] 拒绝信息包含字段名、允许取值与决策分支；`sliceCount` 契约上限与切片上限一致。
+- [ ] 标准美术包声明 `sliceCount=4`，数量不符时在写入用途清单前失败关闭。
+
+## 证据要求
+
+- 自动化：平台定向测试（缺失、空串、连通域带网格尺寸、grid 缺维度、正常两种模式）、OpenAPI 契约测试、前端与 AGC 客户端定向测试。
+- 运行时：本地 `api-server` smoke 提交一次缺字段请求，确认返回 `400` 且无扣费 / 入队记录。
+- 边界：确认失败发生在引用解析、定价、入队与 OSS 副作用之前；确认响应字段与请求一致。

docs/project-memory/plans/【里程碑】资源画布支持引擎资源预览-2026-09-17.md

@@ -0,0 +1,57 @@
+# 【里程碑】资源画布支持引擎资源预览
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented; 真机 Cocos 工程验收待补 |
+| Date | 2026-09-17 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
+
+## 目标
+
+引擎（Cocos Creator 等）工程里已经存在的资源，可以被登记进 manifest，并作为资源画布的卡片**只读预览**：模型出缩略图、序列化资源出结构摘要、客户端解不了的容器出类型卡。
+
+## 范围
+
+- 登记与发现：模型、动画、场景/预制体/瓦片地图/地形、材质/特效、图集与字体配置、图像容器、引擎二进制容器。
+- 生成目录过滤：Cocos 工程的 `library/`、`temp/`、`profiles/`、`local/` 不进发现结果（仅当当前目录确实是引擎工程时生效）。
+- 画布准入与卡面：新增「引擎资源」三个卡面分支（模型 / 结构摘要 / 类型卡），并按扩展名给出引擎语义的类型角标。
+- 模型放大预览：选中模型卡后用工具条的「3D 预览」打开浮层，给出与三维建模软件一致的视角操作（左键旋转 / 右键或中键平移 / 滚轮缩放 / 复位视角）。
+- 只读预览通道：模型字节读取、引擎序列化文本读取（非 UTF-8 时降级）、图像容器原生转码。
+
+## 不在范围内
+
+- 引擎资源的编辑、派生、生成与回写（画布上仍是只读预览；「快速编辑」等现有工具链不承接这些类型）。
+- 引擎私有格式的解码：压缩纹理（`.texture` / `.cubemap` / `.rt`）、Spine 二进制（`.skel`）、DragonBones 二进制（`.dbbin`）、PSD、EXR、裸 PCM 只出类型卡。
+- 新增 manifest 契约字段（`cocosUuid` 等）、新增 canonical kind、新增画布分类轴：本轮复用既有 kind，避免旧客户端读不出 manifest（`deny_unknown_fields`）。
+- 多文件 glTF（`baseURI` 指向外部 `.bin` / 贴图）的渲染：卡面只渲染自包含的 `.glb` / 单文件 `.gltf` / `.fbx`，其余降级成类型卡（本轮选择放宽字节上限，不做资源路径解析）。
+- 项目快照 / 版本指纹 / 检查点对生成目录的口径：本轮只过滤**发现结果**，不改快照语义。
+
+## 依赖与前置条件
+
+- 现有四道闸门：发现（`bridge_project_file_class`）、登记（`agent_local_project_file_type`）、画布准入（`projectedResourceKind`）、卡面读取（`resourceCardPreviewModel` + 原生预览命令）。
+- 既有预览管线（可见性门禁、3 槽并发、LRU 预算、取消与失败语义）不改口径。
+- 前端新增 `three` 运行时依赖（缩略图渲染器）与 `@types/three` 类型依赖。
+
+## 验收标准
+
+- [x] 表内引擎资源都能通过发现层拿到非空 `mediaType`，并按 `model` / `binary` / `image` / `document` / `audio` 等类别被筛出。
+- [x] 表内引擎资源都能登记进 manifest，`kind` 只落在既有 canonical 词表内。
+- [x] 表内引擎资源都能进入资源画布，并落到预期的卡面分支与类型角标。
+- [x] 模型卡在渲染不可用时降级成类型卡，不冒泡成预览失败。
+- [x] 引擎序列化资源的非 UTF-8 变体降级成类型卡，不报错。
+- [x] 图像容器（`.tga` / `.tif` / `.tiff` / `.hdr`）由原生侧转码成 PNG 后按图片卡显示。
+- [x] 引擎工程的生成目录不出现在发现结果里，同名目录在非引擎工程里照常列出。
+- [x] 模型预览上限放宽到与通用媒体预览一致（32 MiB），超出后仍是类型卡而不是半渲染。
+- [x] 模型卡可以放大到独立浮层里交互查看：拖动与滚轮都真实改变画面，「复位视角」回到打开时的取景。
+- [x] 真机 Cocos 工程（含模型与动画资源）在客户端内滚动浏览的视觉验收。
+
+## 证据要求
+
+- 自动化：`cargo check`；`cargo fmt --check`；`cargo test --bin genarrative-ai-game-creator-shell cocos`（9 通过，含发现分类 / 登记 / 提示词 / 插件门禁）；`cargo test … resource_inspect::tests`（7 通过：结构化预览与二进制降级、TGA→PNG 转码、模型媒体类型签名 + 既有文本 / SVG / 尺寸用例）；`cargo test … agent_asset_import_tests`（9 通过）；`cargo test … local_project_file_listing_skips_engine_generated_directories_only_for_engine_projects`；`npx vitest run apps/ai-game-creator-shell/tests/resourceCocosPreviewContract.test.tsx`（7 通过）；`npx vitest run apps/ai-game-creator-shell/tests/resource apps/ai-game-creator-shell/tests/project`（52 文件 / 543 用例）；`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（450 通过 / 20 跳过）；`npm run typecheck`（app）；`npm run check:encoding`；`git diff --check`；`npm run check:doc-index`。
+- 运行时（2026-09-17 完成）：在真实客户端（`npm run agc` 起的 Tauri 客户端 + WebView2 CDP 驱动）里打开一个**本地临时 Cocos 夹具工程**（含模型 / 动画 / 序列化资源 / TGA / 引擎容器，不入库），经 `import_local_cocos_project` 与受控登记导入 10 个引擎资源后逐栏核对：模型卡出真实三维缩略图（`data-model-preview-status=ready`，卡面是渲染出来的 PNG data URL）；`.anim` / `.scene` / `.prefab` / `.plist` / `.effect` 出结构摘要或文本预览；`.tga` 出真实图片（原生转码生效）；`.texture` / `.bin` / `.pcm` 出「纹理 · TEXTURE」「二进制 · BIN」「音频片段 · PCM」类型卡。验收截图（本地留存，不入库）：场景与环境栏（模型 + 摘要）、文档栏（类型卡）、待归类栏（TGA 转码）、音频栏、模型放大预览。
+- 运行时（目录过滤）：同一现场调 `list_local_project_files`，根级 `library/` / `temp/` / `profiles/` **0 条**，而 `assets/library/inside.bin` 正常列出。
+- 运行时（模型交互）：同一现场选中 `cube.glb` → 工具条出现「3D 预览」→ 浮层内 `data-model-viewer-status=ready`、canvas 已挂载；真实鼠标拖拽与滚轮各产生一次不同的渲染结果（三张截图 MD5 互不相同），点「复位视角」后的截图与打开时**逐字节一致**（MD5 `A6531331206456C666909F80384B53AD`）。证据：`agc-model-viewer-initial.png` / `agc-viewer-rotated.png` / `agc-viewer-zoomed-out.png` / `agc-viewer-reset.png`。
+- 运行时（卡面几何）：同一现场量 `cube.glb` 卡的卡片盒 / 卡面 / 类型角标 / 缩略图四个矩形的 `x/y/w/h`，在**指针移开、悬停、选中**三种状态下**完全一致**（此前悬停会把卡面四边各吃 1px）；缩略图渲染尺寸为 `356x252`（布局盒 178×126 × 2 超采样），绘制比 1.4127 与卡面盒 267×189 的比例一致，缩放后不发虚、不裁切。证据：`agc-fix-hover.png` / `agc-fix-selected.png`。
+- 边界：`.meta` 仍然只可发现、不可登记；引擎工程的 `library/` / `temp/` / `profiles/` / `local/` 不进发现结果，同名目录在非引擎工程里照常列出；`.pcm` / `.texture` 等容器不发起读取。
+- 未验证：真机客户端内的视觉验收（本机没有可用的 Cocos 工程实例）。Rust 侧其余仍用 `tempfile::tempdir()` 的既有用例在本机仍被 `Windows 安全对象不属于当前用户` 阻断（本次把预览与导入这两个模块的用例改用工程自带的 `crate::tests::canonical_test_tempdir`，它们已能真实跑通）。

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

@@ -2,6 +2,49 @@
 
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.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 图集切分模式改为显式声明
+
+- 决策：`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，主站前端保持现有行为。
@@ -8176,8 +8219,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 资源详情动作、空态滚动与最终图多步恢复
 
@@ -8812,6 +8855,16 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：采用后台继续运行语义。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 核，是同一时间窗里更大的单一消耗方。
@@ -8819,3 +8872,38 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 边界：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)。

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
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```
@@ -47,6 +51,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,54 @@
 # 踩坑与排障记录
 
+## 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()`。判「用例失败与本改动无关」时，先确认失败信息是不是这一条。
+
+## DirectProject 历史不能按工具条目切页再按消息推进游标
+
+原始 `response_item` 历史同时含用户/助手消息、推理与工具输出。若原生每次取 20 个原始条目、前端过滤聊天消息后再找最旧 ID，纯工具页会让消息集合为空且游标不动，看起来历史丢失。聊天读取固定显式请求 `messagesOnly: true`，原生逐行过滤后按消息分页并返回 `oldestItemId`；默认原始模式留给原始条目消费者。无 ID 旧消息保留并扩展到可寻址边界，不能造 ID。前端保留项目与读取代次、单飞及 ID 去重，旧请求的成功、失败与 finally 都不能覆盖新读取；真实日志只在临时目录只读重放，不能提交正文夹具。
+
+## 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\...` 形式能区分真实路径。
@@ -5649,3 +5698,11 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：不要把重写结果当改动提交。跑过 `cargo test` 或构建后先 `git checkout -- apps/ai-game-creator-shell/src/features/project-workspace/generated`，再删掉多出来的 `DirectCodexUserMessageEnvelope.ts`，然后才做 typecheck / 打包；绑定与前端形状冲突时以**已提交的绑定 + 前端**为基准排查。
 - **验证**：恢复提交版本后 `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-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`。