Merge remote-tracking branch 'refs/remotes/origin/master' into feat/log-the-dianosis

# Conflicts:
#	docs/project-memory/shared-memory/decision-log.md
#	docs/project-memory/shared-memory/pitfalls.md

docs/technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md

@@ -3,7 +3,9 @@
 > 文档状态：`current`
 > 规范关系：承接 AGC 通用插件宿主与编辑器适配主规范
 
-更新时间：`2026-09-20`
+更新时间：`2026-09-21`
+
+2026-09-21 更新：解除工作区发现上的两条限制——一层子目录多命中时按目录名排序取第一个（不再整体失败关闭），`project.godot` 允许是符号链接 / Windows reparse point / 硬链接（按链接目标判定）；同时设置→扩展 的内置插件行去掉手动「启动 / 停止」，启动统一由前端自动完成、停止改走该行启用开关。
 
 ## 目标与边界
 
@@ -15,7 +17,7 @@
 
 将 Godot 编辑器操控接入现有 AGC PluginHost、EditorAdapter、Runner、内置插件开关、权限审计和 Agent 工具链。Windows x64 的 Godot 4.7 及以上标准编辑器是首个实现目标，实机验收使用 4.7.2；其他平台和 .NET 编辑器不得从该结果推断支持。
 
-初版工程路径支持 Windows 本地盘符目录；UNC/网络共享路径在准备描述文件前明确拒绝。链接/reparse point 继续按同一文件边界失败关闭。
+初版工程路径支持 Windows 本地盘符目录；UNC/网络共享路径在准备描述文件前明确拒绝。受管描述文件、缓存与运行缓存继续按同一文件边界对链接/reparse point 失败关闭；唯一例外是工作区发现读取的 `project.godot`，它允许是链接并按目标判定。
 
 DLL 原件随 AGC 安装包放在插件资源目录中；Godot Windows 加载器会在被加载文件旁生成 `~DLL`，因此宿主在 AGC 私有配置目录的运行缓存中按编辑器实例和构建身份准备临时加载副本。AGC 向项目新增一个可扫描的受管 `.gdextension` 描述文件，通过绝对路径引用该实例的加载副本；Godot 可自动生成其同名 `.uid` 伴生文件。DLL 不复制进工程。重新聚焦 Godot 后，由官方文件扫描完成首次加载；不需要用户打开或运行脚本，不创建 EditorPlugin addon，不修改 project.godot 或业务场景文件。编译工具链只属于开发与打包环境，不要求终端用户安装编译器。
 
@@ -24,9 +26,9 @@ DLL 原件随 AGC 安装包放在插件资源目录中；Godot Windows 加载器
 ## 入口与归属
 
 - 插件 id 为 `agc-godot-editor`，适配器为 `godot-editor`；命令 `godot.editor.execute`、连接能力 `godot.editor.connection`，DirectProject 工具为 `agc_godot_execute`。复用已有扩展列表和启用开关，不建立平行插件管理页面。
-- 项目发现沿用现有 Godot 工作区合同：工作区根保持用户选定目录；实际 Godot 根由普通 project.godot 在根或唯一一层子目录中确定。准备描述文件和读取 Godot 缓存只作用于实际 Godot 根，通用文件工具/Runtime 的工作区根不改变。
+- 项目发现沿用现有 Godot 工作区合同：工作区根保持用户选定目录；实际 Godot 根由根目录或一层直接子目录中的 project.godot 确定，一层命中多个时按目录名排序取第一个（确定性，不再报歧义），`project.godot` 本身是链接时按链接目标判定。准备描述文件和读取 Godot 缓存只作用于实际 Godot 根，通用文件工具/Runtime 的工作区根不改变。
 - 平台、内置开关、项目及目标身份必须在执行入口重新检查。插件只能处理宿主传入的当前受控项目，模型不能覆盖项目路径、DLL 路径、端口、令牌或目标实例。
-- Godot 的插件列表、启动和 Agent 工具目录继续按当前 Godot 项目过滤；Cocos/Unity 沿用各自不按工程类型过滤的合同。前端统一消费宿主列表自动启动三种编辑器插件，不在界面重复推断项目类型。Godot 的项目切换仍撤销旧插件上下文并停止旧实例。
+- Godot 的插件列表、启动和 Agent 工具目录继续按当前 Godot 项目过滤；Cocos/Unity 沿用各自不按工程类型过滤的合同。前端统一消费宿主列表自动启动三种编辑器插件，不在界面重复推断项目类型；设置→扩展 的内置插件行只保留启用/禁用与重载，不再提供手动启动/停止入口。Godot 的项目切换仍撤销旧插件上下文并停止旧实例。
 - 插件启动先完成项目事件订阅并接收当前受控项目快照，再注册命令和连接能力；命令可见时必须已经具备执行上下文。订阅期间收到的新项目事件优先于迟到的初始快照。
 - 只连接已打开且唯一匹配真实工程路径的 Godot Editor；校验 PID、进程启动身份、Godot 版本、握手中的工程路径与会话代次。多个候选、非编辑器、路径不符或已退出的进程均拒绝，不启动或关闭用户编辑器。
 - GUI、DirectProject 和 Agent Runtime 的原生操作统一由长寿命 Runner 持有。项目切换使连接失效，迟到回执不能改变新项目状态。

docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md

@@ -1,6 +1,6 @@
 # AGC 客户端更新检查与下载
 
-更新时间：`2026-09-20`
+更新时间：`2026-09-21`
 
 本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。
 
@@ -18,6 +18,17 @@
 - 验收必须覆盖 dev/release/自定义渠道各自端点和对象地址、独立版本、非法名称、旧 dev 地址延续、release 不写旧迁移桥、网站配置贯通、跨渠道链接拒绝和部分失败。
 - 更新链路的信任来源从「清单里的 sha256 + 受信域名」升级为「发布签名 + 受信域名」：清单里的 `signature` 由构建期私钥生成，客户端用内置公钥校验，校验不过就拒绝安装。
 
+### 渠道与安装身份合同
+
+- 渠道同时决定**更新端点**与**安装身份**，两者都由构建期写入产物。默认渠道 `dev` 保持基线身份 `productName = 陶泥儿`、`identifier = world.genarrative.ai-game-creator`；其它渠道（`release` 与自定义渠道）派生 `productName = 陶泥儿 <渠道显示名>`（`release` → `陶泥儿 Release`、`beta-2` → `陶泥儿 Beta-2`）与 `identifier = world.genarrative.ai-game-creator.<渠道>`。渠道显示名按连字符分段首字母大写，不改动渠道本身。
+- 默认渠道身份**不可变更**：既有安装目录、卸载项、快捷方式与已发布客户端的升级链都建立在基线身份上。渠道身份由 `apps/ai-game-creator-shell/scripts/channel-identity.mjs` 单点定义，构建入口、macOS 发布入口与配置门禁共同消费；基线 `tauri.conf.json` 必须逐字等于默认渠道身份。
+- 安装身份决定的持久与可见事实：Windows 安装目录 `%LOCALAPPDATA%\<产品名>`、卸载项与 `HKCU\Software\genarrative\<产品名>`、WebView2 数据目录 `%LOCALAPPDATA%\<identifier>`、客户端数据目录 `%APPDATA%\<identifier>`；macOS `.app` 名、bundle id、DMG 卷名与菜单栏应用名。
+- 同机并存：不同渠道的包体可以在同一台设备上同时安装并同时运行，互不覆盖、互不顶掉；同一渠道的新版本仍是原地升级，因为更新端点与安装身份同属一个渠道。
+- 数据不跨渠道共享：本地项目、工程快照、模板、登录态、诊断日志与 Runner/项目锁按渠道身份分目录。切渠道等于换一个客户端，不迁移、不合并本地数据；渠道内的 origin 隔离规则不变。
+- 主窗口与工作区/启动器窗口标题取构建期产品名，让同机并存的渠道客户端在任务栏与 Alt-Tab 中可区分；默认渠道标题仍是「陶泥儿」。
+- 首装包与更新包的对象名包含产品名（如 `陶泥儿 Release_0.1.96_x64-setup.exe`、`陶泥儿 Release_0.1.96_aarch64.dmg`）。清单 `downloads` 地址由发布脚本按本次真实产物派生，禁止写死产品名；首装包选择按 `<版本>_<架构>.dmg` 唯一匹配，不依赖产品名字面量。
+- Windows 提权 ACL 修复助手按目录名识别安装身份：`<基线>` 与 `<基线>.<渠道>` 都在 AGC 自有的 managed 范围内；相似前缀（例如 `world.genarrative.ai-game-creator-backup`）不在范围内，落回 user-selected 范围或直接拒绝。
+
 ## 非目标
 
 - 不做灰度放量、分批更新、强制更新和自动回滚；渠道只决定「取哪份清单」。
@@ -110,11 +121,21 @@
   - 迁移起点：已发布客户端（含当前线上版本）内置自研清单地址 `agc/latest.json`（sha256 格式），下载与安装由自研 Rust 命令完成。
   - 迁移策略见「未决问题与决策」。迁移完成后，自研清单解析、下载命令、下载进度事件以及为此放行的 CSP / HTTP 白名单条目按「四不写」整条删除，不留兼容分支与墓碑说明。
 
+- 渠道安装身份映射（`<channel>` 为 `dev`、`release` 或自定义名称；`<Channel>` 为渠道显示名）：
+
+| 渠道                 | productName        | identifier                                     | Windows 安装目录                    | 客户端数据目录                                  |
+| -------------------- | ------------------ | ---------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
+| `dev`（默认）        | `陶泥儿`           | `world.genarrative.ai-game-creator`            | `%LOCALAPPDATA%\陶泥儿`             | `%APPDATA%\world.genarrative.ai-game-creator`     |
+| `release` / 自定义   | `陶泥儿 <Channel>` | `world.genarrative.ai-game-creator.<channel>`  | `%LOCALAPPDATA%\陶泥儿 <Channel>`   | `%APPDATA%\world.genarrative.ai-game-creator.<channel>` |
+
+- 安装身份迁移：`dev` 客户端保持原身份，升级链路连续；`release` 与自定义渠道首次以新身份安装，**不接管也不迁移**任何既有 `dev` 安装、本地项目或登录态，设备上因此可以同时存在两个渠道的客户端，由用户自行决定是否卸载其一。
+
 ## 构建与发布
 
 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
+- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
 - 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
@@ -157,6 +178,25 @@
 | 真实更新闭环（含升级后重启） | 0.1.47 客户端按提示下载安装并重启                                       | 通过（2026-09-17 用户实测：提示 → 下载 → 安装 → 关于页显示新版本，再次检查为已是最新）                                               |
 | 更新摘要端到端展示           | 公网读取渠道清单 `notes` 与客户端更新提示                               | 通过（2026-09-17 用户实测：0.1.62 清单带 8 条自动摘要，客户端提示正常显示多行内容）                                                  |
 
+渠道安装身份隔离已于 `2026-09-21` 完成源码验收：
+
+| 条款 | 验收方式 | 结果 |
+| --- | --- | --- |
+| 渠道身份派生与默认渠道不变 | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过；`dev` 逐字等于基线 `陶泥儿` / `world.genarrative.ai-game-creator`，`release` / `beta-2` 派生独立产品名与 identifier，非法渠道失败关闭 |
+| 身份与端点同批注入 | 同上的渠道 `--config` 用例 | 通过；`productName` / `identifier` 与 `/<channel>-win|mac/latest.json` 来自同一次解析 |
+| 渠道产物首装包选择 | 同上的渠道 DMG 夹具用例 | 通过；`陶泥儿 Release_<版本>_aarch64.dmg` 仍按 `<版本>_<架构>.dmg` 唯一匹配 |
+| 基线配置等于默认渠道身份 | `node apps/ai-game-creator-shell/scripts/check-config.mjs` | 通过；基线漂移与非默认渠道身份不隔离都会失败关闭 |
+| 全量发布脚本回归 | `node --test build-release.test.mjs release-oss.test.mjs prepare-macos-codex.test.mjs cargo-features.test.mjs` | 通过（64/64，含 macOS 入口按渠道解析产品名的守卫） |
+| AGC 自有 AppData 提权 ACL 范围 | `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- config::private_path_elevation_policy_tests` | 通过（12/12；含基线、`<基线>.release`、`<基线>.beta-2` 与相似前缀 `-backup` 的反向断言） |
+| 渠道身份进入真实构建产物 | `AGC_UPDATE_CHANNEL=release npm --prefix apps/ai-game-creator-shell run build -- --no-bundle --debug` | 通过；Tauri 接受派生的 `productName` / `identifier` 并完成构建；产物字符串实测 `陶泥儿 Release` × 1、`agc/release-win/latest.json` × 1、`world.genarrative.ai-game-creator.release` × 1、`agc/dev-win/latest.json` × 0 |
+
+未验证项（不得按已通过处理）：
+
+- 真实 Windows 双渠道安装与并存：尚未在同一台设备安装 `dev` 与 `release` 两个渠道的安装包，安装目录/卸载项/数据目录的分离与两个客户端同时运行属于发布验收，本次只到源码与脚本层级。
+- 未生成安装包：本轮构建烟测止于 `--no-bundle`，NSIS 安装目录 / 卸载项 / 快捷方式按渠道分开、以及「装完 release 后 dev 仍在」的现场证据需要一次真实渠道打包与安装。
+- macOS 侧只验证到入口派生逻辑：`.app` 名、bundle id 与 DMG 卷名的渠道派生没有在 macOS 节点实跑。
+- 客户端数据隔离的运行期事实（`%APPDATA%\<identifier>` 分目录、登录态不跨渠道）未做真机对照。
+
 待执行证据（首次渠道发布后回填）：
 
 | 条款                 | 验收方式                                            | 证据   |
@@ -174,6 +214,7 @@
 - macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 arm64 单架构构建、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为关（与 Windows 渠道对称，即直接发布），只有勾选后才退化为「只打印上传计划、不写 OSS」的演练。
 - macOS 代码签名与公证暂缺：产物为未签名 + 未公证，构建入口剥离 `APPLE_*` 凭据跳过 Apple 签名，不传 `--no-sign`（它还会跳过 updater 的 minisign 签名，产物将没有 `.sig`）；构建清单实测记录 `appleSigned` 与签名类型，`latest.json` 侧固定记录 `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
 - 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。
+- 渠道安装身份（2026-09-21）：渠道此前只决定更新端点，`productName` / `identifier` 与渠道无关，导致不同渠道的包体共用 `%LOCALAPPDATA%\陶泥儿`、同一个卸载项与同一份 `%APPDATA%\world.genarrative.ai-game-creator` 数据目录，后装的渠道静默顶掉先装的渠道并接管更新端点与本地登录态。现决策为「渠道进安装身份」：默认渠道保持基线身份不动，其它渠道派生 `<产品名> <渠道显示名>` 与 `<基线>.<渠道>`，渠道内仍原地升级，同机并存与数据隔离成立。窗口标题、macOS 产物名与 Windows 提权 ACL 的 managed 识别范围同批跟随该身份。
 
 待办：
 

docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md

@@ -22,7 +22,7 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 ## 后台模板管理
 
 - 后台新增 `#agc-templates`「模板管理」页签，复用现有后台布局、列表、公共表单/独立弹窗及写入确认。提供名称/ID/标签搜索、运行时和上下架筛选，展示封面、名称、简介、标签、引擎/版本、包大小与上架状态。
-- 本轮只允许编辑名称、简介、标签、封面和上架状态；不新增模板、不上传 ZIP、不修改 ID、运行时、引擎或模板版本，不删除包、历史对象或已建项目。
+- 编辑接口只允许改名称、简介、标签、封面和上架状态，不修改 ID、运行时、引擎或模板版本；**模板新增与 ZIP 上传见「后台模板上传」章节**。两条路径都不删除包、历史对象或已建项目。
 - 唯一数据真相仍是 OSS `templates/index.json`：`templates` 保存上架条目，新增可选 `inactiveTemplates` 保存下架条目，两个数组之间 ID 唯一。后台合并展示两组；AGC 客户端仍只读取 `templates`，刷新后不展示下架项。下架不是资源访问撤销，旧清单缓存和已下载项目不受影响。下架条目元数据位于公开清单，不承载私密草稿。
 - 后台读取/写入分别为 `GET /admin/api/agc-templates`、`PUT /admin/api/agc-templates/{id}`，均经过现有后台认证及 `agc-templates` 页签权限。owner 默认可用，member 需显式分配该权限；不新增数据库表或 schema。部署时后台、API 与引用权限白名单的 SpacetimeDB 模块需同步更新，成员账号才可保存新页签权限。
 - GET 返回 `{ revision, writable, templates }`：revision 是完整原始清单字节的 SHA-256；每条包含 `id/title/summary/tags/runtime/engine/engineVersion/templateVersion/enabled/coverUrl/zipSizeBytes`。不可用或格式错误返回可诊断错误，不能当作空模板库。
@@ -33,6 +33,18 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 - CLI 与后台共享锁和清单合同。CLI 合并保留未选条目与 `inactiveTemplates`，更新下架模板仍保持下架；新增模板默认上架，CLI 不承担删除或上下架。显式发布选中 ID 时，展示字段按该模板源更新，后台编辑结果持续有效直到下一次显式发布该 ID。两端都必须保留另一组条目，不能因本地模板源较旧而抹掉后台记录。
 - 验收包含权限、入口挂载、过滤、编辑与图片校验、上下架往返、未知字段保留、过期 revision/锁争用、上传失败与未知提交、CLI 对下架项的更新/保留，以及桌面/窄屏真实浏览器验证。真实 OSS 写入和生产部署不在本轮验证范围，使用隔离存储替身。
 
+## 后台模板上传
+
+- 后台「模板管理」页提供「上传模板」入口：一次可多选 `.zip`，再按模板 ID 同名多选封面，逐行确认 ID / 名称 / 版本 / 运行时 / entry 后整批提交。简介、标签与引擎可在上传后用编辑接口补齐。
+- 接口 `POST /admin/api/agc-templates/import`（`multipart/form-data`）：`manifest` 文本字段 + `zip_<index>` / `cover_<index>` 文件字段，下标与 manifest 条目顺序一一对应。manifest 为 `{ expectedRevision, templates: [{ id, title, summary, tags, runtime, engine, engineVersion, entry, templateVersion, zipField, coverField }] }`，禁止未知字段。
+- 限制：单批最多 20 个模板；单个 ZIP ≤ 64 MiB；单张封面 ≤ 5 MiB；请求体 ≤ 200 MiB；`runtime` 仅接受 `html / unity / godot / cocos`，`id` / `templateVersion` / `entry` 走既有标识符与相对路径白名单。存储层为 `application/zip` 单独放宽单对象上限到 64 MiB，图片与元数据仍是 5 MiB。
+- 语义：一批**全有或全无**。任一模板的 manifest 字段、归档或封面不合法，都在任何写入之前整批拒绝，并逐项给出模板 ID 与原因。
+- 归档校验不落盘：合法 zip、无符号链接、无绝对路径 / `..` / 盘符 / 反斜杠条目、必须包含 manifest 声明的 `entry`、条目数 ≤ 4096 且解压后总大小 ≤ 512 MiB；并拒绝含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）与根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的包（与 CLI 打包同一门禁，见 [`【模板规范】AGC 模板包组织指南`](../【模板规范】AGC模板包组织指南-2026-09-21.md)）。
+- 封面每个模板必填，按字节嗅探格式（只接受真实 PNG / JPEG / WebP），不信任 multipart 声明的 content-type；上限与编辑路径相同（5 MiB、单边 4096、1600 万像素）。SVG 仍只可能来自 CLI 历史发布。
+- 发布复用既有协议：ZIP 按上传字节原样发布（不重新打包、不删除历史对象），对象键为 `templates/v1/<id>/sha256/<摘要>/{template.zip,cover.*,template.json}`；在发布锁内先 CAS 校验 `expectedRevision`（过期返回 409），写入后逐个回读校验，最后提交一次清单；清单写入结果不明时保留锁并返回 503。断连由独立任务持有，不会在清单 PUT 在途时提前解锁。
+- 版本与保留语义：新 ID 默认上架；已存在 ID 就地更新并保留 `enabled` 分组、其它条目与未知扩展字段（含下架条目）；同一 ID 同一 `templateVersion` 的 ZIP 字节不同时拒绝并要求递增版本（与 CLI 同一句文案），字节完全一致时按内容复用，响应里以 `reusedObjects` 标出。
+- 后台页面沿用既有写入确认、防重复提交与刷新语义：409 提示刷新后重试；上传失败只在弹窗内交代，401 仍交由会话处理。
+
 ## OSS 契约
 
 ```text
@@ -66,15 +78,19 @@ templates/
 - 所有对象键必须落在 `templates/` 前缀内；客户端只用「受信任 OSS 主机 + 对象键」自行拼 URL，**不直接信任清单里的地址**。
 - 任何一项校验失败（schema、标识符、sha256、尺寸、键前缀）都让整次清单读取失败，前端拿到的是全有或全无的清单。
 - 模板源在仓库 `apps/ai-game-creator-shell/template-library/`：`v1/<id>/{meta.json, project/**, cover.(png|jpg|webp|svg)}`，`template.zip` **不落仓库**，由脚本按 `project/` 现场打包（条目排序、固定时间戳，同内容重复打包摘要一致）。
-- 上传与校验由 [`scripts/agc-template-library-publish.mjs`](../../scripts/agc-template-library-publish.mjs) 完成：`--source apps/ai-game-creator-shell/template-library [--dry-run] [--only <id,id,...>]`。ZIP、封面和元数据分别以自身字节的 SHA-256 定位，只创建新对象或复用逐字节校验一致的已有对象；全部对象回读一致后才更新 `index.json`。失败不回收已上传对象，旧清单及其引用始终可读。
+- 模板包内容怎么组织（根目录结构、Cocos 工程保留项、不要放的东西、封面与体积上限、发布前自检）见 [`docs/【模板规范】AGC模板包组织指南-2026-09-21.md`](../【模板规范】AGC模板包组织指南-2026-09-21.md)。
+- 上传与校验由 [`scripts/agc-template-library-publish.mjs`](../../scripts/agc-template-library-publish.mjs) 完成：`--source apps/ai-game-creator-shell/template-library [--dry-run] [--only <id,id,...>]`。ZIP、封面和元数据分别以自身字节的 SHA-256 定位，只创建新对象或复用逐字节校验一致的已有对象；全部对象回读一致后才更新 `index.json`。失败不回收已上传对象，旧清单及其引用始终可读。打包阶段执行与后台上传相同的正文门禁（`readProjectFiles`）：正文含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）或根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的模板直接报错，不产生任何上传对象。
 - 只更新指定模板时使用 `--only <id,id,...>`，在发布锁内读取最新清单，只替换指定 ID，其余条目和未知扩展字段保留。首次清单 404 可由本次选择初始化；读取异常或清单非法时停止。全量发布也遵守相同锁与版本门禁。
+- `templates/README.md` 与上述正文不同：它不是内容寻址对象，而是**覆盖写的说明文档**，源在仓库 `apps/ai-game-creator-shell/template-library/README.md`（上限 64 KiB），由同一次发布在清单之前写入并回读校验。客户端从不读它，改契约只改仓库源即可，不要再手工维护线上副本。
 - 正式发布先通过 `GetBucketVersioning` 确认 Bucket 从未开启版本控制，再用 `x-oss-forbid-overwrite: true` 原子创建 `.publish-lock.json`；版本控制 Enabled、Suspended、检查无权限或无法判定时均在写入前停止。所有写同一清单的发布进程必须使用此锁，发布期间不得改变 Bucket 版本控制配置。锁没有自动过期或抢占机制，已被占用时直接失败，重新执行须重新获取锁并读取最新清单。
 - 只释放本任务已明确获取且 owner 标识仍一致的锁。获取结果不明时不猜测删除。正文对象不可变，其写入失败可安全释放本任务的锁；清单 PUT 已发起后若遇到断连、超时或服务端 5xx 等不确定结果，必须保留锁并报错，防止旧在途请求晚于下一发布者写入。清单收到确定成功或确定拒绝响应后才进入正常解锁路径；不自动重发清单写入，也不凭一次 GET 猜测在途 PUT 已结束。遗留锁须在确认原请求及进程已终止或完成后由运维处理；释放失败必须报告，不伪装为发布成功。
 - `--dry-run` 仅构造和读取合并计划，不读取凭据、不获取锁、不 PUT/DELETE。发布不删除历史对象，也不提供随发布清理的选项；旧客户端缓存和未完成下载可能仍引用旧键。
 - 同一 ID、同一 `templateVersion` 的 ZIP 大小或摘要改变时，在上传正文前拒绝，要求更新模板版本；只把相同 ZIP 迁移到新键可保留版本。客户端现有 `<id>/<templateVersion>` 缓存行为不变。
-- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程），以及 Cocos Creator 3.8.8 的 `cocos-empty-2d`、`cocos-empty-3d`、`cocos-empty-3d-hq`、`cocos-hello-world`。
+- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程）、Cocos Creator 3.8.8 的 `cocos-empty-2d`、`cocos-empty-3d`、`cocos-empty-3d-hq`、`cocos-hello-world`，以及 Godot 4.7 的 `godot-empty-2d`、`godot-empty-3d`、`godot-hello-world`、`godot-platformer-2d`。
 - Cocos 内容来自 Creator 3.8.8 随附的 `resources/templates/{empty-2d,empty,empty-quality,hello-3d-world}`，保留官方资源、`.meta`、设置和模板预设；补齐 `package.json.creator.version`，空模板以 `assets/.gitkeep` 保证资源目录进入 Git 和 ZIP。`entry` 为 `package.json`，不打包编辑器生成的缓存或用户项目数据。
 - Cocos 建项在复制后按实际 `package.json.creator.version + assets/` 识别，复用既有 Cocos 导入流程，写入 `cocosProjectRoot: "."`；每个新项目重建 `package.json.uuid` 并写入所选项目名。只创建 `.agent` 管理目录，不生成 Web 占位入口；模板源与本机安装缓存不被改写。
+- Godot 内容为仓库内手写的 Godot 4.7 工程（`project.godot` + `scenes/` + `scripts/`，GL Compatibility 渲染，只用内置 `ui_*` 输入动作，不依赖外部贴图），`entry` 为 `project.godot`，不打包 `.godot/` 编辑器缓存与导出产物。
+- Godot 建项在复制后按 `project.godot` 识别，复用既有 Godot 导入流程，写入 `godotProjectRoot: "."`，并把工程显示名改写成用户选择的项目名（只改 `[application]` 段的 `config/name` 一行，其余字节逐字保留）；不生成 `game/` 占位入口与 `assets/`、`memory/`、`exports/` 并行目录，也不改写模板源与本机安装缓存。
 - 客户端可用 `AGC_TEMPLATE_LIBRARY_BASE_URL` 覆盖库地址；只接受 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`（拒绝其他主机、路径、http）。
 
 ## 客户端实现
@@ -83,9 +99,9 @@ templates/
 
 | 命令                                                | 行为                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fetch_game_template_library`                       | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache`                                                                                                                                                                                                                                                                                         |
+| `fetch_game_template_library`                       | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache`。远端已经答话但正文不是合法 UTF-8 或不符合 schema、以及缓存自己损坏时，一律失败关闭，不用缓存掩盖远端错误                                                                                                                                                                                  |
 | `download_game_template`                            | 取清单里对应条目，流式下载 zip（≤512 MiB），校验字节数与 SHA-256，解压到 `<app_data>/templates/installed/<id>/<version>/`，最后写 `installed.json` 作为安装完成的唯一标记                                                                                                                                                                                                                                                   |
-| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在自动工作区根目录下按既有自动工作区规则建目录：先复制模板文件；Cocos 项目更新自身身份后走既有 Cocos 导入，其余沿现有 `init_local_game_project_at` 初始化。根目录默认是 `<app_data>/projects/`，用户可选 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |
+| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在自动工作区根目录下按既有自动工作区规则建目录：先复制模板文件；Cocos 项目更新自身身份后走既有 Cocos 导入，Godot 项目改写工程显示名后走既有 Godot 导入，其余沿现有 `init_local_game_project_at` 初始化。根目录默认是 `<app_data>/projects/`，用户可选 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |
 
 安全与健壮性：
 
@@ -93,6 +109,7 @@ templates/
 - 安装目录名由标识符白名单拼出，不拼接远端字符串；重装时只清理该模板自己的安装目录。
 - 模板文件与安装记录统一走 `write_game_creator_private_file` / `ensure_game_creator_private_directory_tree`，保持项目目录的私有 DACL 口径。
 - 建项目失败时删除刚创建的项目目录，不留半成品。
+- 大小 / 摘要校验在落盘之前完成，被拒绝的模板包不产生任何安装目录；`installed.json` 是「已下载」的唯一判据，目录残留（例如解压中途失败）不构成已安装，下次安装会先清理该模板自己的安装目录。
 
 ### 前端
 
@@ -114,6 +131,14 @@ Cocos 回归分别覆盖仓库模板和线上真实 ZIP 的安装、连续建项
 
 `2026-09-19` 发布一致性验收：Node 发布回归 22 项通过，覆盖两个发布者竞争、正文/清单写入失败、迟到清单 PUT、锁归属、版本控制拒绝、V1 签名及真实 CLI 的无写入 dry-run。Rust 定向回归 15 项通过，新增内容地址的清单解析与 URL 保留校验；3 项线上用例本轮未重复执行，此前同日线上下载及原生建项已通过。只读 dry-run 保留线上九个模板并仅计划更新四个 Cocos 条目。格式、编码、文档索引、定向 ESLint 与 diff 检查通过。全部并发/故障写入证据来自离线替身，未执行真实 OSS 锁写入或发布，也未验证 Creator 内场景运行。
 
+`2026-09-21` 客户端接入复核：Rust 定向 24 项通过（新增清单来源判定 5 项：合法远端正文优先并标 `network`、远端失败回退缓存并标 `cache`、无缓存时暴露远端错误、远端正文非法时不用缓存掩盖、缓存损坏时失败关闭；新增建项目失败清理 1 项；并在大小/摘要不一致、越界归档两条用例上补「拒绝后不留安装目录、不产生已下载判据」断言）。3 项线上用例（读线上清单、下载安装线上模板、下载并原生建项 Cocos 模板）本轮全部真实执行通过；匿名 `GET https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json` 返回 200、`schemaVersion=agc-template-library.v1`、9 个模板。前端 38 项通过（模型 9、网格 6、页面 12、控制器 11），`appSurface` 首页模板用例 2 项通过（灰度外隐藏入口与推荐位、点击进入模板库不建项），AGC `typecheck` 通过。仍未验证：Creator 内场景运行，以及真机 iOS / Android 观感。
+
+`2026-09-21` 模板库重发布：把线上库从 09-17 的旧产物对齐到仓库当前源。线上 9 个模板里 7 个（`blank-3d-scene`、`cocos-empty-2d/3d/3d-hq/hello-world`、`phaser-2d-starter`、`threejs-3d-starter`）的 ZIP 与仓库不一致（旧产物来自 PR 定稿前的源，例如模板内嵌 `package-lock.json` 已由 `5e4ff54a9` 删除、`game.js` / `main.js` 后来改过），其中 2 个原本一致（`blank-2d-canvas`、`blank-web`）。按「同版本 ZIP 不得变」门禁，为这 7 个模板递增 `templateVersion` 到 `0.1.1` 后重发：28 个内容寻址对象逐个回读校验通过，`index.json` 与 `templates/README.md` 在锁内提交；线上清单现在全部指向 `v1/<id>/sha256/<摘要>/` 键，`libraryVersion=1`、9 个模板、无下架条目。发布脚本本次同时补齐说明文档受管写入（源文件即 `apps/ai-game-creator-shell/template-library/README.md`）并修掉「守卫拒绝后直接 `process.exit(1)` 触发 libuv 断言崩溃、看不到原因」的问题；线上 README 与仓库源已逐字节一致。
+
+`2026-09-21` 模板正文目录门禁：CLI 打包（`readProjectFiles`）与后台上传（`validate_import_archive`）统一拒绝正文含 `.agent` / `.git` / `.svn` / `node_modules` 段（任意层级）与根目录 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode` 的模板，两处用同一份段名单与同一句文案。同名目录段只在根目录受限：正文内 `game/dist/**` 与 `.gitignore` 仍合法（`.gitignore` 不等于 `.git`），Cocos 模板的 `.creator` / `.gitignore` 不受影响。证据：Node 发布回归 28 项通过（新增 1 项，13 条拒绝用例 + 2 条放行断言）；Rust `admin_templates` 8 项回归通过（新增 `template_import_archive_rejects_identity_and_build_directories`）；仓库现有 9 个模板源无一条命中门禁，本地重打包的 9 个 ZIP 摘要与线上 `index.json` 的 `zipSha256` 逐条一致（匿名读清单 200、9 个模板、0 个下架条目），即门禁未改变任何已发布字节。未执行真实 OSS 写入。
+
+`2026-09-21` Godot 模板入库：新增 `godot-empty-2d` / `godot-empty-3d` / `godot-hello-world` / `godot-platformer-2d` 四个仓库内手写模板，并给建项补 Godot 分流。模板内容用本机 Godot `4.7.2.stable` 逐项验证：四个模板的主场景都能实例化并跑满 3 帧、全部 GDScript 过 `--check-only`（同一条命令对故意写错的脚本报告 Parse Error，证明检查有效）；平台跳跃模板另做真机物理试玩——角色落地 y=627.99（地面顶 656 − 半高 28）、按住右 1 秒位移 320px、连按跳跃后落在平台上 y=515.93（平台顶 544 − 28）、三枚金币全部收集后 HUD 变为「已收集 3 / 3 —— 全部完成！Esc 重来」。Rust 侧 4 项定向回归通过：`template_library::tests::godot_template_creates_native_project_with_relative_root_and_display_name`（Godot 模板建项得到 `godotProjectRoot: "."`、无 `game/` 占位入口、`config/name` 改写成所选名称且其余行逐字保留）、`import_tests::rewrites_only_the_godot_display_name_line`、`import_tests::keeps_a_godot_project_without_a_display_name_line_untouched`，以及既有 Cocos/Web 建项回归未受影响。发布保持 `--only` 定向：只新增四个 Godot 模板对象并重写清单，其余 9 个模板的键与版本不变；未在客户端「模板库」里实际建一次项目。
+
 ## 本地压测假数据注入（feature 控制）
 
 模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。

docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md

@@ -254,6 +254,7 @@ npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> -
 - `cwd` 必须是项目内规范相对目录，拒绝符号链接、绝对路径、`..`、Windows 盘符 / UNC / ADS 和整个 `.agent` 控制面；超时固定在 1-300 秒，stdin 关闭，stdout / stderr 采用有界头尾保留并先做凭据清洗。
 - 默认权限为 `confirm`。确认摘要包含程序、argv 摘要、cwd 和超时；精确动作继续绑定 actionId、repository fingerprint、project revision 和 execution owner。Runner 在 `executing` 阶段退出时保持 `needs-reconciliation`，不得自动重放命令。
 - 子进程继承环境清空；可执行文件必须从项目外安全绝对目录解析为绝对路径，子进程 PATH 只保留这些已规范化目录，并注入隔离 HOME / TMP / cache、离线包管理配置和不可达代理。超时或读流失败时 Runtime 请求终止受控进程组并检查终止调用结果，但这不等同于完整 detached-process / 容器隔离。首版安全等级与现有 `project.verify` 相同：固定程序和参数策略加用户确认，不宣称已经具备 Codex CLI 的完整 OS sandbox；在完成平台沙箱前不得把 `command.exec` 默认改为 `auto`。
+- Linux 一次性命令确认 target 终态并回收主进程后，按 `/proc/<pid>/stat` 核对同 PGID 成员；空组或只剩 `Z / X` 成员无需再发送信号，不因容器 PID 1 未回收孤儿僵尸而误报 reconciliation。存在存活成员时仍必须核对原 leader 启动身份，身份缺失或不匹配时拒绝发送信号；读取或解析进程状态失败同样进入 reconciliation。此判断不扩展为 detached-process 隔离证明，也不改变诊断命令与验证 gate 的区分。
 - Cargo / npm 缓存固定写入项目私有 `.agent/runtime/command-env/cache`，不复用或改写用户宿主缓存，也不允许联网补依赖。依赖未进入项目 vendor、现有 `node_modules` 或隔离缓存时，命令应以真实失败输出回到 Agent；首版不为“跑通命令”复制宿主的 Cargo registry、凭据或用户级配置。
 - `command.exec` 的执行前后源码指纹各自最多遍历 20,000 个目录项、10,000 个受保护文件和 512 MiB 正文；执行前超预算直接拒绝启动，执行后无法完成指纹则进入 `needs-reconciliation`，不得把截断扫描当成完整验证凭证。
 - 命令结束后重建安全项目文件指纹。若命令改写了受保护项目文件，则保持 verification gate 未通过并要求 Agent 重新检查；每次真正启动命令前已经保守推进一次 revision。可签发验证凭证的命令仅限 `cargo check/test/clippy/fmt/build`、`npm test`、命名为 `check/typecheck/test/lint/build/verify/validate` 的 npm 验证脚本及精确 `node --test`；`git`、`rg`、`cargo metadata` 和普通 `npm run` 即使退出码为 0 也只作为诊断结果。只有验证型命令退出码为 0、未超时、未改写受保护文件，且命令日志、manifest 投影和 Agent DB 审计全部成功后，才允许绑定当前 revision 的 passed gate；任一审计失败必须先保持 failed gate，再进入 `needs-reconciliation`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -1,5 +1,16 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-09-21 Godot 工作区发现放宽与内置插件行去掉手动启动
+
+本节覆盖下文“打开项目自动识别 Godot”中的旧口径：判定从「唯一命中」放宽为「确定性命中」，`project.godot` 从「必须是普通文件」放宽为「按链接目标判定」。
+
+| 要求 | 必须成立的行为 | 完成证据 |
+| --- | --- | --- |
+| 确定性多命中 | 根目录未命中时，一层直接子目录中多个 `project.godot` 命中按目录名排序取第一个；不再报「多个 Godot 项目」，也不再要求用户改选具体工程 | `cargo test --locked -p genarrative-ai-game-creator-shell --bin genarrative-ai-game-creator-shell -- project::manifest::import_tests::` 与 `-- tests::project::` |
+| 链接标记 | `project.godot` 是符号链接 / Windows reparse point / 硬链接时按链接目标判定，目标解析为普通文件即命中；目录与悬空链接仍不算命中 | `import_tests::accepts_symbolic_link_project_marker`（unix）、`import_tests::accepts_windows_hard_link_project_marker`、`import_tests::accepts_windows_reparse_project_marker` |
+| 保持不变的边界 | 工作区根本身是链接、候选子目录是链接、二层及更深目录不递归，这三条既有边界不动 | `import_tests::ignores_symbolic_link_child_candidate_without_writing_agent_metadata`、`import_tests::ignores_windows_reparse_child_candidate_without_writing_agent_metadata`、`import_tests::ignores_godot_projects_below_the_first_child_level` |
+| 内置插件行 | 设置→扩展 的内置插件行不再渲染手动「启动 / 停止」按钮；启动由项目切换时的前端自动启动承担，停止走该行启用开关（禁用即停止并断开编辑器连接）；导入扩展行的启动按钮保留 | `apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`tests/pluginHost.test.ts` |
+
 ## 2026-09-20 DirectProject 七项效率闭环（补齐合同）
 
 本节补齐并覆盖下节中仅靠 Skill 要求预检、收尾、批读和原生命令预算的部分。完整目标仍为：自动预检、宿主验收与收尾、分层验证、统一执行/返修预算、稳定测试基线、请求耗时与批量读取、所有工具并行。已有代码及测试不等于全部目标已完成；按下表逐项验收。
@@ -48,6 +59,8 @@
 ### 宿主验收与执行许可合同
 
 - 正式 GUI 和 CLI 的共同 Direct 回合入口建立宿主控制状态，绑定 canonical 项目路径、稳定 clientTurnId 和原始用户输入摘要；宿主私有目录保存权威账本并独占该回合，项目 `.agent` 仅允许保存展示副本。配置或项目侧文件被改写、工具切换、Provider 重试和进程重启不得刷新同一回合的预算。
+- Direct 回合集成测试也按生产入口计算原始用户输入的 SHA-256 十六进制摘要（64 字符），不能用请求名称替代。用户回显过滤回归继续覆盖实时消息去重、回合起止身份关联及历史落盘过滤。
+- 直接启动 Direct 工具桥的图片生成通知测试，须复用真实宿主执行会话与已登记交付合同夹具，再发起工具请求；继续验证资源提交后发出 manifest 失效通知，以及空提示词被参数校验拒绝且不发通知，不绕过执行许可门禁。
 - 普通聊天与读取不要求交付合同。首次修改、代码执行或付费扩项之前，模型通过结构化工具登记本轮必需范围与验收项；合同非空、有界且只冻结一次。模型只能声明要求，不能提交“通过”作为证据。后续扩项留到新的用户回合。
 - 明确新 Web 创建由宿主可信脚手架凭证及尚未交付的宿主记录判定，CLI 同样据此判定，不从提示文本猜测；这种回合即使模型没有调用工具或没有登记合同，也不得按普通聊天宣布交付。已有项目只有未激活合同且从未产生副作用时才允许直接聊天结束。
 - 验收项为明确类型的产物、构建/测试命令、双端视觉或指定固定场景的双端玩法。可信新 Web 游戏由宿主补充构建、双端视觉和玩法底线，不能由模型声明“已有项目”降低。已有项目按冻结的变更范围选择层级；平台美术只在用户目标要求时成为必需项。
@@ -199,6 +212,7 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
 
 ## 资源画布生成、展示与布局合同
 
+- 客户端「生成图标素材」只将用户描述去除首尾空白后，保留内部换行并作为唯一 `iconDescriptions` 元素提交；不添加小游戏首版原型、核心美术或默认美术 brief，不截断、不按段落或字数拆条。面板与原生入口均要求描述非空且最多 `200` 个 Unicode 字符（按码点计数），超限在提交前明确拒绝；其余图片生成提示词维持 `32000` 字符上限。规范图、纯色背景、素材排布等生图约束由网站与客户端共用的 API Server 流程统一添加。完整请求合同见 [画板图标素材生成入口设计](../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
 - 生成工具点击后先在当前栏目创建临时占位卡，并以卡片为锚点展示独立生成浮层；占位不登记为正式素材、不进入 Agent 可引用资源集。上传仍沿用文件选择，不创建虚假生成任务。关闭编辑浮层不应丢失正在执行的任务；切换项目不得将旧项目结果或草稿写入新项目。
 - 图片生成支持从现有素材选择器添加真实参考；引用携带稳定资源身份并经既有原生权限、归属与类型校验传至生成链路，不能仅拼接名称。缺少规范图不阻止打开面板；确有规范前置的操作必须在提交前满足要求，不能绕过后端校验。用户可通过现有工具栏先生成规范图。
 - 占位可移动。提交复用正式生成任务、幂等与结果登记链路；成功结果使用占位最新位置，失败保留输入与引用供重试。已受理但响应不确定时先对账，不能无条件再次发起付费生成。关闭、删除占位和后台任务的行为需保持既有任务所有权，不把隐藏展示当作取消任务。
@@ -271,7 +285,7 @@ Rust 分片日志在失败时输出有界 stdout 尾部中的失败段，保留
 
 ## DirectProject 用户消息契约验证
 
-`chat_with_game_creator_direct_codex` 必须携带 `projectPath`、`prompt`、稳定的 `clientTurnId` 和完整 `userItem`；`creationType` 与 `attachments` 按实际输入传递。Rust 通过 `projectPath` 解析项目身份，不接收额外 `projectId`。界面测试必须核对 `userItem` 的消息身份、角色、正文及附件内容，拒绝回合用例仍验证实际返回的错误原因。重开项目的历史恢复测试使用 `read_direct_project_history_slice` 的 canonical raw items 与 `hasMore`，首屏 `limit: 20`。资源图和生成任务的读取继续遵守原有工作台恢复逻辑，不因聊天断言失败延迟、关闭或改变它们。
+`chat_with_game_creator_direct_codex` 必须携带 `projectPath`、稳定的 `clientTurnId` 和完整 `userItem`（文本、`@` 素材引用与附件引用都在同一份 content 里）；`creationType` 按实际输入传递。Rust 只从 canonical `userItem` 派生回合输入，不接收前端渲染的 `@显示名` 文本投影。Rust 通过 `projectPath` 解析项目身份，不接收额外 `projectId`。界面测试必须核对 `userItem` 的消息身份、角色、正文及附件内容，拒绝回合用例仍验证实际返回的错误原因。重开项目的历史恢复测试使用 `read_direct_project_history_slice` 的 canonical raw items 与 `hasMore`，首屏 `limit: 20`。资源图和生成任务的读取继续遵守原有工作台恢复逻辑，不因聊天断言失败延迟、关闭或改变它们。
 
 ## 2026-09-16 DirectProject 回合展示唯一归属
 
@@ -523,8 +537,8 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 
 ## 技术选择
 
-- 桌面壳：新建 `apps/ai-game-creator-shell`，与现有 `apps/desktop-shell` 分离，避免把游戏创作本地能力塞进主站宿主壳；启动时先检查平台登录态，未登录只展示登录页，登录后进入单窗口客户端首页；正式用户窗口常驻左侧栏和顶部栏，并在首页、项目组、指南 / 反馈和项目开发页之间切换。发布和 debug 启动都只登记并打开 `client` 用户窗口；`index.html?agent-chat` 仅保留为显式前端调试路由，不是 Tauri 自动启动入口。
-- 窗口外壳：`client`、动态 `main` / `launcher` / `supervisor-chat` 窗口统一关闭原生 decorations，由前端 `WindowChrome` 绘制陶泥儿品牌 Logo、当前页面 / 项目标题和最小化 / 最大化 / 关闭控制。标题栏不重复展示项目列表或本地工作区入口：首页及非项目页面的居中标题固定为“创作工作台”，打开项目后切换为当前项目名；泥点账户入口通过标题栏右侧插槽渲染，标题文本使用独立的窗口几何居中层，不参与左右入口宽度分配，项目名过长时仅在可用宽度内省略。标题栏只复用 `packages/shared/src/theme.css` 的暖陶土变量与现有产品 IP，不引入另一套主题；浏览器预览或非 Tauri 宿主中窗口控制安全降级，不能阻断页面渲染。
+- 桌面壳：新建 `apps/ai-game-creator-shell`，与现有 `apps/desktop-shell` 分离，避免把游戏创作本地能力塞进主站宿主壳；启动时先检查平台登录态，未登录只展示登录页，登录后进入单窗口客户端首页；正式用户窗口常驻左侧栏和顶部栏，并在首页、项目组、指南 / 反馈和项目开发页之间切换。发布和 debug 启动都只登记并打开 `client` 用户窗口。
+- 窗口外壳：`client`、动态 `main` / `launcher` 窗口统一关闭原生 decorations，由前端 `WindowChrome` 绘制陶泥儿品牌 Logo、当前页面 / 项目标题和最小化 / 最大化 / 关闭控制。标题栏不重复展示项目列表或本地工作区入口：首页及非项目页面的居中标题固定为“创作工作台”，打开项目后切换为当前项目名；泥点账户入口通过标题栏右侧插槽渲染，标题文本使用独立的窗口几何居中层，不参与左右入口宽度分配，项目名过长时仅在可用宽度内省略。标题栏只复用 `packages/shared/src/theme.css` 的暖陶土变量与现有产品 IP，不引入另一套主题；浏览器预览或非 Tauri 宿主中窗口控制安全降级，不能阻断页面渲染。
 - 平台后端：继续使用 `server-rs + Axum + SpacetimeDB`；本地开发启动独立客户端时，`agc` / Tauri dev 会先启动或复用配套 SpacetimeDB 与 `api-server`，再启动固定端口 Vite，并通过 `/api` 代理访问实际后端端口。
 - 本地能力：使用 Tauri Rust command；正式用户 App 在项目运行工作台内承载 `127.0.0.1` 本地 HTTP preview，不再调用系统外部浏览器。运行容器只接受当前授权项目由 `PreviewRegistry` 返回的 loopback URL，release / dev CSP 都只为 `http://127.0.0.1:*` 开放 `frame-src`，并使用受限 iframe sandbox 隔离游戏脚本；远程 URL、`file://` 和任意手填地址均不得进入该容器。
 - Agent Runtime：扩展 `server-rs/crates/platform-agent`，不引入 LangChain、AutoGen、Microsoft Agent Framework 或 OpenAI Agents SDK sidecar 作为核心。
@@ -534,13 +548,6 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 代码组织：桌面客户端入口保持为薄组合层。前端把认证、Tauri 桥接、Runtime 配置、Agent Runtime 展示和项目摘要分别放入 `src/app`、`src/services` 与 `src/features`；Rust 项目能力和测试按功能域使用目录模块；界面测试与真实 Runtime E2E 使用薄 suite registry / entry 保留原执行顺序。后续拆分必须保持公开导出、命令契约、测试名称和行为不变，不能用 `include!`、整文件文本拼接或只移动到另一个超大文件代替真实模块边界。
 - 源码门禁：`check:native-shells` 等源码扫描必须跟随真实模块归属；入口组合层只验证受控组件的挂载关系，具体实现由所属模块单独验证。模块拆分后不得为了满足旧字符串扫描把实现搬回 `App.tsx`，也不得用跨文件文本拼接代替组件归属检查。
 
-## 开发态 Project Supervisor 纯聊天独立窗口
-
-- 入口边界：当前仅 Tauri dev 提供独立窗口，路由为 `index.html?supervisor-chat&projectPath=...`，其中 `projectPath` 传入 URL 编码后的项目绝对路径。该窗口仅通过显式开发调试动作打开，不增加正式用户入口，也不随 `npm run agc` 自动弹出；重复打开同一项目只恢复并聚焦原窗口，切换项目时在同一窗口导航。
-- Runtime 边界：窗口固定对话 Agent 为 `project-supervisor`，新 Run 使用 `standard` profile，复用现有 active Session、External Runner、Agent Runtime、AppData 配置和持久 conversation；不新建平行会话库、Runner 或配置存储，也不把该测试入口隐式切成自动修改项目的自主构建模式。
-- 界面边界：只显示持久消息区、输入框、必要的等待 / 错误状态、工具确认 / 用户追问卡片和设置入口；不显示 Agent picker、Session 面板、Goal 面板、完整 Runtime 面板或专业 Agent 协作栏。会话历史仍绑定 `project-supervisor` 的 active Session 持久化，不因隐藏 Session 控制面而变为临时聊天；`supervisor-chat` 窗口必须具备只读 Tauri event listen / unlisten capability，以实时接收 Runtime 更新。
-- 产品边界：正式用户 `client` 窗口、登录后首页和项目开发流程保持不变，不暴露该开发验证面。
-
 ## 2026-07-29 “游戏运行 + 聊天”独立构建入口
 
 - Windows AppData 安全迁移：首次创建客户端 AppData 时必须以进程 `TokenUser` SID 显式设置 owner，并写入当前用户私有 DACL，不能把可能为 Administrators 的 `TokenOwner` 当作用户身份。发现历史目录 owner 不属于当前 `TokenUser` 时，不在原目录上放宽权限，而是拒绝 reparse point / junction / symlink 后，将旧目录原子重命名到同级唯一 `.owner-mismatch-backup-*` 备份，再新建并验证当前用户 owner 与私有 DACL；迁移或备份失败必须失败关闭，不覆盖旧配置。
@@ -558,7 +565,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 固定试玩契约：`generic-v1` 初始状态必须为 `ready` 且 `level > 0`；点击 start 后 sequence 必须推进、phase 必须进入 `playing`，并先持续观察 2 秒、取得至少 8 个实际样本，期间保持 `playing`，以确认玩家获得正常操作机会。随后必须点击唯一可见、启用且真实可交互的 `data-playtest-id="primary-action"` 控件；该控件必须映射游戏的真实主要玩法操作，并以 sequence 相对点击前严格推进证明操作已被接受。玩家获得这次正常操作机会之前进入 `won | lost` 属于过早结束并失败；操作被接受后的单次 `lost` 是合法游戏结局，但不能成为所有受控尝试的唯一结果；若主要操作后仍为 `playing`，则继续观察 3 秒并取得至少 12 个实际样本，`won` 可提前证明非失败推进。点击 restart 后 sequence 必须再次推进并恢复到 `ready | playing`，随后持续观察 3 秒且取得至少 12 个实际样本。若首轮结果为 `lost`，重开稳定后必须再执行一次必要的 start、2 秒 / 8 样本操作机会和真实 primary-action；第二次必须进入或保持 `playing`（再观察 3 秒 / 12 样本且不得转为 `lost`）或进入 `won`，两次都固定 `lost` 代表无法正常推进的恶性 bug，必须失败。各观察窗口内 sequence 不得回退，restart 窗口只能保持 `ready | playing`；样本数门槛不能替代时长门槛，窗口末端必须强制再读取一次有效状态，不能只在前段快速取得足够样本后提前通过。控件 selector、观察时长、最少样本数、终态边界、非失败推进、末端覆盖、sequence 单调 / 严格推进规则及完整 required assertions 都进入 scenario fingerprint。读取旧 fingerprint 回执和检查 plan liveness 时，把合同升级造成的 fingerprint 不匹配视为 stale missing，允许同一 run 重新执行 `preview.validate` 自愈；身份、路径、digest 或内容完整性篡改仍失败关闭。最终完成门每次按当前合同重算 fingerprint，并严格拒绝旧 fingerprint、旧 assertion 集或仅保存历史 `passed=true` 的证据。
 - 一次性自动预览授权：用户在该入口成功提交本轮自主生成需求，即视为对“当前项目 + 当前 Supervisor 父 run”的一次 `preview.start` 授权。授权以仅含项目路径与 accepted parent runId 的客户端本地记录持久化，App / WebView 重启后仍可恢复，但项目或 run 身份不匹配时不得使用。只有当前 accepted parent run 成功完成 `preview.validate` 且给出有效 revision 后，客户端才可消费授权，由 Tauri 首次启动并自动展示该 revision 的用户可见预览；一次授权最多成功启动一个 Tauri preview server，并必须继续走现有权限、项目写锁、审计和客户端 `PreviewRegistry` 链路。项目或 Agent 策略的显式 deny 始终优先，不得被此授权绕过。启动成功、显式 deny、非瞬时失败、父 run 在首版验证前终止或切换项目后授权失效；`preview.start` 恰逢项目写锁竞争属于瞬时失败，不消费授权，释放写锁后由同一轮询链路重试。
 - 增量预览刷新：Tauri 客户端记录当前 iframe 已展示的 validated revision；同一当前 run 后续成功 `preview.validate` 的 revision 严格高于已展示 revision 时，只在原 Tauri preview server 和原 loopback origin 上刷新 iframe，不得再次调用 `preview.start`、新增 server 或切换到 Runner registry。相同或更低 revision 不触发刷新。preview HTTP server 对 HTML、脚本、样式、资源和错误响应统一发送 `Cache-Control: no-store`，iframe 刷新必须读取新 revision，不能继续命中 WebView 缓存中的旧版本。自动预览轮询回归的等待上限必须严格大于生产 `1000ms` 轮询间隔，不得使用同为 `1000ms` 的默认上限制造 CI 边界竞争。
-- 系统边界：该页面是既有 AI 游戏创作工作台的独立构建例外，不新增平台玩法入口、后端 API、会话库、Runner 或预览服务，也不把入口并回普通正式客户端。原 `supervisor-chat` 继续固定使用 `standard` profile 并保持纯聊天行为，不继承本例外的自主构建、事件聚合或自动预览授权。
+- 系统边界：该页面是既有 AI 游戏创作工作台的独立构建例外，不新增平台玩法入口、后端 API、会话库、Runner 或预览服务，也不把入口并回普通正式客户端，也不继承本例外的自主构建、事件聚合或自动预览授权。
 
 - 对话输出中的 `eventId + publicText` 只指需要独立进入聊天的进度事件；`turn.started` 和根 Run 终态失败事件由上一条 `runtime-public-status-*` 硬门覆盖，不得同时转成事件消息。专业 Agent child 的失败消息继续留在其 Agent Session，根项目聊天只接收 Supervisor 终态失败、明确公开进度和安全 final-reply，避免一项失败被 Runtime event 与 conversation 各播报一次。
 - 验证：前端运行时模型定向测试、Rust completion/source/asset 合同测试、`cargo fmt --check`、`npm run check:encoding` 与 `git diff --check` 必须全部执行；Windows 文件锁竞态只可作为既有测试失败单独记录，不得将其改写为本次改动的通过证据。
@@ -578,7 +585,8 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 模式合同：客户端 AppData 配置新增全局 `agentMode`，只接受 `codex_cli / provider`。缺省和新安装默认使用 `codex_cli`，原有 HTTP LLM Provider 路径完整保留并可显式切回 `provider`；切换只影响下一次节点请求，不新增 Runner、任务图、会话库、配置库或业务事实源。
 - 调度边界：正式 DAG、manifest、Agent task/session/run 身份、队列、锁、委派、all-join、完成门、Provider lifecycle、持久 retry/handoff 与 `needs-reconciliation` 继续由现有 AGC Runtime 掌控。每个被调度节点在 `codex_cli` 模式下直接启动一次非交互 `codex exec` 充当该节点的推理 Agent；Codex 返回当前 Runtime 广告函数的结构化调用，Runtime 仍是唯一 ToolHost，不允许 CLI 自己写项目、执行命令、调用 MCP 或形成第二套 revision / verification 真相。
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.155.1` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。固定版本只在 `build_support/codex_bundle.rs` 声明一次，构建脚本、宿主补丁执行器身份、逐次审批协议允许列表和模型目录捕获共同引用它，避免多处字面量漂移。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
-- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述统一由 `tauri.conf.json` 的 `productName: "陶泥儿"` 生成；应用 identifier 与内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
+- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述由 `tauri.conf.json` 的 `productName` 生成：基线是 `陶泥儿`，发布构建按渠道由 `--config` 覆盖为 `陶泥儿 <渠道显示名>`，identifier 同批派生 `<基线>.<渠道>`（默认渠道保持基线值），因此不同渠道的包体可在同一台设备并存；内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
+- Windows 渠道 AppData 目录归属判断及其调用分支统一保留 Windows 条件编译；通用项目路径策略测试仍可在 Linux 运行，实际 ACL 修复保持原平台门禁与授权范围。
 - macOS 安装包必须携带锁定版本的原生 Codex、`codex-code-mode-host`、`rg`、上游 zsh、`codex-package.json` 和第三方声明，保留上游相对布局；构建时按 Cargo 目标选择 npm 原生依赖，缺文件、版本或目标不匹配立即失败，不借用开发机 PATH 里的 Codex。资源只在 `tauri.macos.conf.json` 映射到 `Contents/Resources/coding-agent/mac-native/darwin-arm64/` 与 `darwin-x64/`。构建与运行共享平台文件白名单，运行时由当前 `.app/Contents/MacOS` 定位相邻 `Resources`，完整性与版本验证通过后优先使用内置组件；失败沿既有外部安装回退，不能运行未校验的内置文件。macOS 当前只构建 arm64 单架构，但资源映射仍并列携带两套锁定原生 Codex 依赖（运行切片按 Cargo 目标只选择对应目录），恢复 Intel 时无需改动资源布局；随包 Node 只有宿主架构那一份，所以不得构建 universal 包。不读取全局 Codex。
 - 内置插件的清单、运行入口与面板同时在 Windows/macOS 随包分发，继续由既有 PluginHost 的应用资源目录扫描入口发现；不携带开发依赖、缓存、测试或私有配置。插件文件随包不等于原生适配器跨平台：Cocos 进程桥接仍受现有 Windows 实现和 feature 门禁约束，macOS 原生桥接另行设计与验收，不复制 Windows DLL 冒充支持。系统 Node、用户 Cocos Creator、账号登录、网络和生成工程的 npm 工具链仍是现有外部前提，不在此次 Codex 侧车补齐中隐式变更。
 - macOS 安装包验收必须包括：脱离仓库位置的 `.app` 资源与架构检查、受限 PATH/隔离 HOME 下内置 Codex 启动和 app-server 握手、必需文件缺失/篡改/平台错误的拒绝测试，以及 DMG 完整性检查。真实登录、Provider 对话、GUI 和 Cocos 操作必须独立列出证据，不能用压缩包生成或 `--version` 成功替代。未配置正式签名、公证的本地测试包不得作为公开发行包。
@@ -748,7 +756,7 @@ Agent Runtime 负责：
 ## Agent 能力清单
 
 - 用户能力：项目开发工作台、陶泥儿聊天、上传文件、manifest 资源视图、客户端内运行表现层和专业 Agent 紧凑状态；正式用户窗口仍不展示原始任务 / 文件 / 日志、开发预览调试面板、能力清单或开发专用单 Agent 聊天入口。
-- 开发调试能力：`index.html?agent-chat` 可作为显式前端调试路由；开发者可选择 Agent、授权本地项目路径，并通过 `read_local_conversation` / `append_local_conversation_message` 读写 `.agent/conversations/agents/<agentId>.jsonl`，通过 `agentLlm.<agentId>` 调用该 Agent 的独立 LLM 路由做真实对话，用于单独调试某个 Agent 的长期对话上下文。这里的 `<agentId>` 以 manifest taskId 为规范值，旧 `group-role` 别名只作为兼容输入映射到 taskId。
+- 开发调试能力：无 GUI 调试使用 `npm run agc:chat` / `npm run agc:swarm` 终端入口，复用 External Runner、active Session、conversation 与各 Agent 私有记忆；`<agentId>` 以 manifest taskId 为规范值，旧 `group-role` 别名只作为兼容输入映射到 taskId。
 - 命令能力：内置命令调用、权限 gate、执行日志；v1 只允许白名单受限命令，不执行任意 shell。
 - 编排能力：任务拆分、任务图依赖、专业组调度、多智能体协作；Runtime V1 会为单 Agent 对话和生成 loop 中的角色 brief 写入独立 runtime state / event，先解决“每个 Agent 正在做什么、跑到哪一步、最近一次 task/run 是什么”的可观测性。
 - 历史边界说明：下一条“后台任务能力”保留 V1.1 前的进程内演进记录，其中 App 内 tokio task、进程内 drain、旧工具箱和“不是独立 OS 进程”的描述均已失效；当前执行边界以上文独立 Runner 说明为准。
@@ -1325,7 +1333,7 @@ game-project/
 - 开发模式可执行 `canvas.asset_import`，将项目内已有文件按画板来源导入 manifest；也可执行 `canvas.export_import`，把现有画板素材导出 ZIP 回流为本地项目资产。`game.generate_draft` 在普通模式登录态有效或高级模式凭据有效时复用同一平台图片生成能力，不新增平行资产模型。
 - 普通模式已在登录后的单窗口项目开发页渲染 GameAgent 工作台、`project-supervisor` 主聊天和专业 Agent 协作只读状态，不提供专业 Agent / child 单 Agent 对话；首页首条需求直接投递 active Supervisor Session，全新项目没有该 Session 时先通过既有 Session 命令创建并设为 active，已有项目恢复该 Session 与历史后继续交互。Tauri 主窗口承载当前授权项目的 loopback 游戏画面，但不承载开发 Agent picker、调度工具台或任意地址预览调试面板。
 - 聊天生成草案后会尝试启动只读 `127.0.0.1:<port>` 静态 HTTP server，把预览地址回写客户端项目运行工作台并切换到运行视图；不再调用系统外部浏览器。
-- 开发模式仅在 Vite dev 环境响应 `?dev` 或 `#dev`；`npm run agc` 与 release 都只打开 `client` 用户窗口，显式 `?agent-chat` 与 `supervisor-chat` 调试入口不随启动自动弹出。正式构建忽略 dev 参数，release 配置只登记一个用户窗口，登录后同窗口进入首页并在项目组 / 项目开发页之间切换。
+- `npm run agc` 与 release 都只打开 `client` 用户窗口。正式构建与 release 配置只登记一个用户窗口，登录后同窗口进入首页并在项目组 / 项目开发页之间切换。
 - `check:native-shells` 会运行 `ai-game-creator-shell:check` 和 `ai-game-creator-shell:build -- --no-bundle`，并静态检查 release 与 debug 启动都只登记 `client / index.html` 这一个默认窗口、禁止 Tauri setup 自动打开 developer 窗口、开发面板必须挂在 `devMode` 分支内，正式用户 App 的运行容器只接受 `http://127.0.0.1:*`，release / dev CSP 都只为该 loopback origin 开放 `frame-src`，Tauri 预览激活命令不得调用 opener，用户主流程不得调用旧工作区窗口切换 command。
 - 共享契约提供 `GAME_CREATION_AGENT_CAPABILITIES` 和内置命令权限枚举；开发模式会展示能力列表。
 - 共享契约提供 manifest task schema 和 ready-task 选择器，用于记录任务拆分、专业组、角色模板、依赖、产物、验收条件和当前可执行任务。
@@ -1783,7 +1791,7 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
 - 可观测性按产品口径收敛到本机日志：同步结果、失败分类、延后与跳过计数只写入 AppData 诊断日志（`project_snapshot.sync.*` 前缀），客户端界面不暴露上传状态、时间线或入口按钮。`read_local_project_snapshot_state` 与 `sync_local_project_snapshot` 两条命令仅作为 native-only 的排障与联调入口登记，不在渲染层调用。
 - 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
-- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
+- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/manifest.json`；`channel` 是本部署渠道（`GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL`，缺省沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`），同一 bucket 因此天然按渠道分区，开发与正式部署互不可见对方项目。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀（含历史无渠道的 `agc/project-snapshots/v1/`）继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。后台“项目工程”按渠道查询与下载，渠道名非法时失败关闭，历史 v1 对象不再列出。
 - 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`。只允许凭据回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`；bucket 与 endpoint 不跟随资源存储的 `ALIYUN_OSS_BUCKET` / `_ENDPOINT`，避免默认写入其它 bucket。显式快照目标配置继续优先；不自动搬迁其它 bucket 的现存数据。
 
 ### 正常、失败、重试与幂等行为

docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md

@@ -106,7 +106,7 @@ readHistory(threadId, { beforeItemId?, limit }) -> {
 
 Thread 内所有公开事件共用一个单调递增 seq，但 **seq 只是 Thread Manager 的内部游标事实，不下发**：同一个 subscriber 的 `consume` 按队列顺序返回事件数组，数组顺序就是前端要处理的顺序，前端因此不需要 item 级 cursor 或第二套 reducer。
 
-线上模型是 ts-rs 导出的 tagged enum（`agent/direct_thread_wire.rs`），前端消费 `src/features/project-workspace/generated/` 里的生成绑定，改 Rust 模型后跑 `cargo test export_bindings` 重新生成；毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
+线上模型是 ts-rs 导出的 tagged enum（`agent/direct_thread_wire.rs`），前端消费 `src/view/project-development/chat/generated/` 里的生成绑定，改 Rust 模型后跑 `cargo test export_bindings` 重新生成；毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
 
 事件按 `type` 区分，条目按 `itemType` 区分：
 

docs/technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md

@@ -227,7 +227,7 @@ initialAttachments={currentProjectContext.attachments}
 1. [`home.suite.ts`](../../apps/ai-game-creator-shell/tests/appSurface/home.suite.ts)「imports home attachments…」：Direct invoke 必须带 `attachments`，其中 `name` 为 `角色参考.png`、`localPath` 为 upload 返回路径、`status: 'imported'`。用 png 证明不是 md 特例。
 2. 无附件的 Direct invoke 仍不得出现 `attachments` 键（或等价：不传该字段）。
 3. `planningStartMode` 首轮仍走 Supervisor，`chat_with_game_creator_agent` 的 payload 不含附件 sidecar。
-4. 工作台后发的普通消息：`chat_with_game_creator_direct_codex` 只有 `projectPath/prompt/clientTurnId`（及既有 creationType 规则），不带 attachments。
+4. 工作台后发的普通消息：`chat_with_game_creator_direct_codex` 只有 `projectPath/clientTurnId`（及既有 creationType 规则），不带 attachments。
 5. 若本分支已能跑 PR #210 的 home.suite / plan-gdd 做成游戏用例：只断言它仍调用 `createHomeDraftAutomatically` / 仍使用原固定 prompt；**不要**给做成游戏加第二条附件协议。sidecar 由通用 Direct 断言覆盖。
 
 ### 不测

docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md

@@ -1,6 +1,6 @@
 # 策划 Agent 生产迁移与工作区浏览方案
 
-更新时间：2026-09-20
+更新时间：2026-09-21
 状态：已完成（2026-09-18）
 
 > 现状说明（2026-09-18）：本文记录的迁移已完成，当前策划入口统一使用 Design Agent。旧 Planning V1/V2 会话、专用命令、审批卡和展示适配已删除；文中提到的 V2 文件仅代表迁移时的参考来源，不得作为现行实现、回退路径或测试迁移目标。
@@ -174,6 +174,18 @@ Runtime 不维护文档版本号，不解析文档版本，不提供版本回退
 
 验收至少覆盖：保存后重新进入策划显示一致；旧会话切换模型后实际请求改变；当前执行不被中途改档；下一次发送/澄清/审批继续/主动重试生效；自动恢复不重复工具副作用；GameAgent 原有选择、发送和运行行为不回归。真实 Provider 或桌面环境缺失时明确记为未验证，不用 fixture 冒充实机结果。
 
+### 4.2 策划参考附件导入
+
+- 首页策划入口与策划聊天框将用户附件按原始字节导入 `design_artifacts/references/`，Agent 通过现有工作区文件工具自行发现。有用户文字时，导入完成后才开始首页首轮策划；只有附件时只进入工作区，不合成消息或自动启动策划。聊天框导入中暂缓发送、阶段批准、澄清与重试，并提示等待导入完成再切换游戏制作，避免新回合读取未完成文件或模式切换丢失导入结果。
+- 文件名保留安全的原始名称；同名自动追加序号，禁止覆盖已有文件。沿用项目权限与工作区路径边界，禁止通过文件名、符号链接或目录链接写出工作区。空文件也可导入。
+- 导入只写策划工作区，不登记游戏资产、不更新项目资源清单或游戏 revision，不触发上传后的清单刷新。不组装回合附件、不把文件路径或清单注入 Agent 消息。
+- 每个文件独立返回结果；部分失败不丢弃成功文件，界面显示成功数量及失败文件和原因。用户可重新选择失败文件重试；成功导入不自动重放，再次手动导入同名文件视为新副本。
+- 游戏入口继续使用现有资产上传链路。已有 `assets/uploads/` 文件不自动搬迁；转入游戏制作时沿用现有策划工作区登记行为。
+- 本次不修改 Agent 提示词、工具或消息协议，不增加 PDF、Word 等二进制文档解析；保存成功不代表格式可由现有 UTF-8 文件读取工具解析。
+- 验收覆盖：首页与聊天框导入、多文件部分失败、同名与空文件、工作区工具可列出并读取文本、路径与链接边界、资源清单和 revision 保持不变、游戏上传兼容。证据由定向前端测试、本地 Rust 文件往返测试、类型检查和编码检查提供；真实桌面交互另行记录。
+
+验证证据（2026-09-21）：`appSurface.test.ts` 中策划导入、导入中审批、首页游戏附件与模型控件定向用例通过；`designWorkspaceDebug.test.tsx`、`designProjectRestore.test.tsx` 与 `workspaceLauncherManifestMerge.test.tsx` 通过，覆盖文件事件刷新、项目恢复和导入中模式切换。Rust `agent::design_tools::tests::` 8 项通过，覆盖文件往返及写入边界。AGC typecheck（含命令注册检查）、定向 ESLint、Rust 格式、编码、文档索引与差异检查通过。未运行安装包桌面点击验证或真实 Provider；Windows 链接用例在宿主不支持建链接时跳过。
+
 ## 5. Agent Runtime
 
 新的 Runtime 应提供自由工具循环：

docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md

@@ -586,13 +586,13 @@ hydrate_planning_session_v2
 
 ### 7.3 UI 复用边界
 
-第一版可复用现有：
+策划会话的入口容器、审批卡与工作台布局已经落地在当前模块结构里：
 
-- `ProjectSupervisorView` 的聊天区域和工作台布局；
-- `GddApprovalCard` 的产物展示与审批交互；
-- 现有耗时展示和会话历史加载。
+- `view/project-development/planning/PlanningChatView.tsx`：策划会话容器，只消费 V2 状态；
+- `view/project-development/planning/GddApprovalCard.tsx` 与 `PlanningLaneRuntimeStrip.tsx`：产物展示、审批交互与窄条运行态；
+- 现有耗时展示和会话历史加载继续复用。
 
-但数据来源必须改为 V2 状态，不再把“页面组件叫 Supervisor”当作运行时身份。后续再把组件重命名为 `PlanningSessionView`，不作为本次切换前置。
+数据来源只有 V2 状态；旧 `project-supervisor-plan` 运行时不参与页面渲染，也不再作为组件身份。
 
 ## 8. 最小安全与业务校验