Merge remote-tracking branch 'origin/master' into feat/jenkins-mac-build

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

docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md

@@ -71,7 +71,7 @@ plugins/agc-cocos-editor/
 
 宿主按 `AGC_PLUGIN_WORKSPACE`、随包 `<resource_dir>/plugins`、开发构建仓库 `plugins/` 的顺序解析工作区；插件包内的 `native/payload` 由构建脚本随包映射，生成的 DLL 不入库。插件协议、权限和面板挂载全部复用通用宿主，Cocos 专属逻辑只存在于本插件包：进程名与 `--project` 解析、Creator 版本校验、named pipe 协议和 Windows 注入。
 
-该插件是**内置插件**：随客户端分发、不能卸载，只能通过 `set_agc_plugin_enabled` 控制是否可用。除开关和 feature 外，还必须满足“当前受控项目已识别为 Cocos Creator 项目”这一门禁；没有当前项目或项目类型不是 Cocos 时，插件不出现在插件列表、面板、Agent 工具目录或 MCP tools/list 中，启动、面板读取、RPC 和编辑器执行也会失败关闭。项目切换离开 Cocos 后，已运行实例立即停止。Cocos 编辑器操作统一优先通过该内置插件的 `cocos.editor.execute` / `cocos.editor.operation`（DirectProject 对应 `agc_cocos_execute`）；不得改走项目目录 `extensions/`、`package.json` 插件或第三方 MCP。开关状态保存在 AppData `extensions/builtin-plugins.json`，隔离 MCP 每次 tools/list 都向绑定宿主询问当前状态与项目门禁。
+该插件是**内置插件**：随客户端分发、不能卸载，只能通过 `set_agc_plugin_enabled` 控制是否可用。插件列表、启动、面板读取、插件 RPC、Agent 工具目录和 MCP tools/list 不按当前工程类型过滤；无当前项目或非 Cocos 项目仍沿用相同的开关、原生适配器、平台和 feature 规则。项目切换不因工程类型不同而停止插件，仍更新受控项目上下文并失效旧连接。实际编辑器操作必须取得当前受控项目对应的真实 Creator 目标并通过原有目录、PID、版本与握手校验；无项目或非引擎目录不能仅凭工具可见就通过执行校验。Cocos 编辑器操作统一优先通过该内置插件的 `cocos.editor.execute` / `cocos.editor.operation`（DirectProject 对应 `agc_cocos_execute`）；不得改走项目目录 `extensions/`、`package.json` 插件或第三方 MCP。开关状态保存在 AppData `extensions/builtin-plugins.json`，隔离 MCP 每次 tools/list 都向绑定宿主询问当前可用状态，不自行按工程类型过滤。
 
 ## AGC 项目打开入口
 

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

@@ -3,7 +3,7 @@
 > 文档状态：`current`
 > 规范关系：承接 AGC 通用插件宿主与编辑器适配主规范
 
-更新时间：`2026-09-18`
+更新时间：`2026-09-20`
 
 ## 目标与非目标
 
@@ -18,7 +18,7 @@
 ## 入口与行为合同
 
 - Unity 项目以当前受控根目录中的普通 `ProjectSettings/ProjectVersion.txt`、`Assets/` 和 `Packages/` 识别；复用现有打开项目入口，不创建平行工作台。
-- 只有当前项目为 Unity、内置插件启用且平台适配器可用时才显示插件并向 Agent 暴露 Unity 工具。禁用或离开 Unity 项目后停止插件实例，执行入口再次检查开关和项目身份。
+- 插件列表、启动、面板、插件 RPC 和 Agent 工具暴露不按当前工程类型过滤；无项目或非 Unity 项目也沿用相同的内置开关及平台适配器规则。禁用会停止插件实例，跨工程类型切换保留插件管理能力并失效旧连接。前端按宿主列表中各插件自身状态投影自动启动，不因项目类型在 Cocos/Unity 之间二选一，也不自动展开面板。执行入口继续检查开关、权限和真实项目身份；工具可见不代表任意目录可作为 Unity 执行目标。
 - 探测只读取进程和项目身份。连接必须匹配规范化项目路径、PID、进程启动身份与实际握手；多个候选时失败，不选择任意实例。助手只接受受控项目、操作和代码，不接受任意可执行文件或 payload 路径。
 - 执行接收 UTF-8 C# 代码，最多 128 KiB，拒绝空值和 NUL。连接及执行有总期限，消息最多 2 MiB，并发执行直接拒绝，不积压写请求。
 - 成功仅由 Unity 真实执行回执决定；编译或运行错误返回结构化失败与脱敏诊断。主线程同步代码不承诺可硬中止。
@@ -51,7 +51,7 @@ helper 使用一行一条 JSON 请求/响应，请求包含 `id`、`method`、`p
 | 条款 | 必须取得的证据 |
 | --- | --- |
 | 来源与构建 | 固定源码版本、许可、helper 构建和自包含发布检查 |
-| 插件接入 | manifest/协议测试，发现、启停、开关和项目级工具过滤测试 |
+| 插件接入 | manifest/协议测试，发现、启停、开关、无项目/跨工程类型的工具暴露和前端启动投影测试 |
 | 执行闭环 | helper 与原生适配器定向测试，Agent 参数及结果映射测试 |
 | 失败边界 | 跨项目、并发、超时、损坏回执、不确定阻断、重启插件不解除阻断测试 |
 | 分发 | Windows 构建脚本准备 helper，staging 仅包含目标平台运行文件及许可 |

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

@@ -1,13 +1,21 @@
 # AGC 客户端更新检查与下载
 
-更新时间：`2026-09-19`
+更新时间：`2026-09-20`
 
 本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。
 
 ## 目标
 
 - 客户端自动更新改用 Tauri 官方 `tauri-plugin-updater`：清单请求、版本比较、更新包下载、签名校验、安装与退出全部在原生侧完成；前端只负责触发、展示和渠道选择。
-- 更新按渠道分发。当前渠道集合为 `dev-win`（Windows x64）与 `dev-mac`（macOS）；构建管线按渠道产出并上传清单，客户端只读取自己渠道的清单。
+- 更新按渠道分发。渠道为 `dev`、`release` 或自定义名称；Windows/macOS 是独立的系统维度，每个渠道分别维护各系统已发布的版本、清单和安装包。客户端只读取构建时确定的渠道及系统对应的清单。
+
+## 渠道与网站配置合同
+
+- 构建参数 `AGC_UPDATE_CHANNEL` 默认 `dev`，支持 `release` 和自定义小写名称；名称符合 `[a-z][a-z0-9-]{0,31}`，不能以连字符结尾，不能为 `win/mac/windows/macos/darwin/linux` 或以 `-win/-mac` 结尾。构建目标独立决定系统和架构。
+- 为延续已发布客户端地址，OSS 继续使用 `agc/<channel>-win/` 和 `agc/<channel>-mac/` 作为物理分区；`dev-win/dev-mac` 是分区键，不是可填写的渠道。每个分区独立维护 `latest.json` 与版本目录，发布 release 不覆盖 dev。旧 `agc/latest.json` 迁移桥与其版本高水位仅属于 dev 的 Windows 分区。
+- 网站由服务端配置 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL` 选择检测渠道，默认 `dev`；更改后重启 API 服务生效。`GET /api/client-downloads` 返回该渠道 Windows/macOS 的真实已发布版本。请求参数不能覆盖配置或指定 URL；配置非法时失败关闭，不悄悄改读 dev。
+- 同一渠道中不同系统仍可具有不同 release 版本；未发布的系统隐藏，单系统失败不影响另一系统。不会从其他渠道补齐缺失版本。
+- 验收必须覆盖 dev/release/自定义渠道各自端点和对象地址、独立版本、非法名称、旧 dev 地址延续、release 不写旧迁移桥、网站配置贯通、跨渠道链接拒绝和部分失败。
 - 更新链路的信任来源从「清单里的 sha256 + 受信域名」升级为「发布签名 + 受信域名」：清单里的 `signature` 由构建期私钥生成，客户端用内置公钥校验，校验不过就拒绝安装。
 
 ## 非目标
@@ -33,11 +41,11 @@
 ### 官网下载与客户端服务地址
 
 - 官网首页提供无需登录的「下载客户端」入口，桌面和移动视口均可访问；入口打开独立下载面板，复用平台按钮、弹窗和状态组件。
-- 每次打开下载面板请求同源公开 `GET /api/client-downloads`，后端并行读取固定 `dev-win/latest.json` 与 `dev-mac/latest.json` 并汇总已发布平台，网页和接口均禁用缓存。平台列表与每项版本完全来自清单；不在网页写死版本或猜测文件名。
+- 每次打开下载面板请求同源公开 `GET /api/client-downloads`，后端并行读取配置渠道的 `<channel>-win/latest.json` 与 `<channel>-mac/latest.json` 并汇总已发布平台，网页和接口均禁用缓存。平台列表与每项版本完全来自清单；不在网页写死版本或猜测文件名。
 - 接口返回 `{ downloads: [{ platform, architecture, version, downloadUrl }], unavailablePlatforms: [] }`，平台为 `windows` / `macos`，架构为 `x86_64` / `aarch64`；Windows 仅支持 x86_64，Mac 按清单实际提供的架构展示 Apple Silicon / Intel 下载项。DTO 由 `shared-contracts` 与 `packages/shared` 对齐，不接受请求参数指定上游 URL，不触及 SpacetimeDB。
 - 渠道清单新增可选 `downloads` 字典，键与 updater 平台键一致，值为 `{ url }`，只登记首装包。Windows `.exe` 可同时用于首装和更新；macOS 首装必须为 `.dmg`，不得将 `.app.tar.gz` 当首装包。已发布且没有 `downloads` 字段的 Windows 清单可读取既有 `platforms.windows-x86_64.url`；Mac 没有首装元数据时隐藏，不推导 DMG 地址。
 - 渠道 404 视为尚未发布并隐藏该平台；两端均未发布时显示空状态。单渠道请求失败、超时或格式非法时保留另一端有效下载项，同时提示部分平台暂不可用并允许重试；没有任何有效项且存在失败时返回可读 502。关闭面板取消请求，迟到响应不能覆盖下一次打开的状态。
-- 每个上游请求总超时 10 秒、响应体上限 128 KiB、不跟随重定向、不附加用户凭据；返回的链接仅接受固定 OSS 来源、对应 `/agc/<channel>/<version>/` 下的 HTTPS `.exe` / `.dmg` 对象，架构键必须属于该渠道。不提供陈旧、未知来源或版本不匹配的下载地址，不泄露上游正文。
+- 每个上游请求总超时 10 秒、响应体上限 128 KiB、不跟随重定向、不附加用户凭据；返回的链接仅接受固定 OSS 来源、对应 `/agc/<channel>-win|mac/<version>/` 分区下的 HTTPS `.exe` / `.dmg` 对象，架构键必须属于对应系统。不提供陈旧、未知来源或版本不匹配的下载地址，不泄露上游正文。
 - AGC 开发态和正式包的平台服务地址统一固定为 `https://dev.genarrative.world`；登录页不提供服务器选择或自定义地址。旧的服务器偏好不能覆盖固定地址；已有会话仍按 origin 隔离，不能将其他服务的凭据迁往 dev。自定义 LLM 配置不属于平台服务器选择。
 - access token 与 origin 一起保存；已有 dev origin 的 token 保留。没有 origin 的旧 token 一律清除，因为旧版可以单独修改服务器偏好，偏好不能证明 token 来源。随后仅使用 dev 自己的 refresh cookie 恢复或重新登录；原生会话回写同样绑定 dev origin。
 - 验收覆盖固定 dev 的登录/会话与请求行为、旧服务器偏好、首页入口挂载、动态最新版本链接、清单失败与重试、关闭取消、桌面和移动布局，以及公开清单和安装包的真实可读性。
@@ -47,7 +55,7 @@
 - 正式包启动时检查一次渠道清单；仅当清单版本高于当前版本时显示更新提示，提示包含目标版本与发布说明。
 - 用户确认后下载更新包：下载期间显示进度与已下载字节数；下载完成后按平台安装。
 - Windows 使用静默安装模式（NSIS `quiet`），安装启动成功后客户端退出并由安装程序重启新版本；macOS 由客户端在安装完成后重启进程接管新版本。
-- 渠道在构建期确定并烘焙进产物：`dev-win` 产物只读 `dev-win` 清单，`dev-mac` 产物只读 `dev-mac` 清单，同一份二进制不会在运行期跨渠道切换。
+- 渠道与系统在构建期确定并烘焙进产物：如 dev 的 Windows 产物只读 `dev-win` 分区，release 的 Mac 产物只读 `release-mac` 分区，同一份二进制不会在运行期跨渠道切换。
 - 开发态（`npm run agc` / `agc:serve` 由 Vite dev server 提供前端）不检查更新、不显示更新入口，也不下载任何更新包。
 
 ### 失败、重试与幂等
@@ -85,19 +93,19 @@
 }
 ```
 
-- 渠道与平台映射：
+- 渠道与平台分区映射（`<channel>` 为 dev、release 或自定义名称）：
 
-| 渠道      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
+| 系统      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
 | --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
-| `dev-win` | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/dev-win/latest.json` |
-| `dev-mac` | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/dev-mac/latest.json` |
+| Windows | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/<channel>-win/latest.json` |
+| macOS | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/<channel>-mac/latest.json` |
 
-- 对象布局：清单固定写成 `agc/<channel>/latest.json`；安装包与签名写成 `agc/<channel>/<version>/<file>` 与 `<file>.sig`。
-- macOS 正式交付使用 universal 主程序，同时携带分目录的 arm64/x64 原生 Codex 组件；每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录。不得把两套原生包的元数据或辅助程序混装。
-- universal 更新包的两个平台键指向同一个 `.app.tar.gz` 和签名。单架构构建仅登记本架构供诊断，不轮流覆盖 dev-mac 正式清单；正式双架构发布必须构建 universal。
+- 对象布局：清单固定写成 `agc/<channel>-win|mac/latest.json`；安装包与签名写成同一分区的 `<version>/<file>` 与 `<file>.sig`。
+- macOS 正式交付使用 universal 主程序：两个平台键指向同一个 `.app.tar.gz` 与签名，一份产物同时服务 Apple Silicon 与 Intel。单架构目标（`aarch64-apple-darwin` / `x86_64-apple-darwin`）只用于本机诊断，不登记正式分区清单——单架构构建不可轮流覆盖同一个 `latest.json` 并宣称双架构均可更新。
+- universal 主程序同时携带分目录的 arm64/x64 原生 Codex 组件：每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录，不得把两套原生包的元数据或辅助程序混装。
 - 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
-- 版本递增按渠道独立进行：发布脚本读取该渠道远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；两个渠道的版本号互不影响。
-- 版本高水位：发布脚本取「渠道清单版本」与「旧协议迁移指针版本」（迁移窗口内）中的较大值再递增。只看渠道清单会在渠道启用初期把版本链改小 —— 2026-09-17 首次渠道发布即把旧指针的 0.1.57 退回 0.1.48，随后以显式 0.1.60 纠偏；迁移窗口结束（旧指针 404）后自动只剩渠道清单，`dev-mac` 不参与旧指针比较。
+- 版本递增按渠道及系统分区独立进行：发布脚本读取该分区远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；不同分区的远端版本互不影响。
+- 版本高水位：仅 dev 的 Windows 分区在迁移窗口内取「分区清单版本」与「旧协议迁移指针版本」较大值再递增，避免已发布旧客户端版本倒退。迁移窗口结束（旧指针 404）后只读分区清单；release、自定义渠道与所有 Mac 分区均不参与旧指针比较。
 - 迁移（旧协议 → 渠道清单）：
   - 迁移起点：已发布客户端（含当前线上版本）内置自研清单地址 `agc/latest.json`（sha256 格式），下载与安装由自研 Rust 命令完成。
   - 迁移策略见「未决问题与决策」。迁移完成后，自研清单解析、下载命令、下载进度事件以及为此放行的 CSP / HTTP 白名单条目按「四不写」整条删除，不留兼容分支与墓碑说明。
@@ -106,17 +114,19 @@
 
 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
-- 渠道由构建参数显式指定，并按目标平台校验：Windows 目标只允许 `dev-win`，macOS 目标只允许 `dev-mac`；未显式指定时按目标平台取默认渠道。
+- 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
 - 定时调度只在本轮到达的提交包含 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` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
-- 上传：安装包与 `.sig` 上传到 `agc/<channel>/<version>/`，清单以 `--force` 覆盖上传到 `agc/<channel>/latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
+- 上传：安装包与 `.sig` 上传到 `agc/<channel>-win|mac/<version>/`，清单以 `--force` 覆盖上传到对应分区的 `latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
 - 首装发布：发布脚本生成 `downloads`，Windows 复用已选 NSIS `.exe`，Mac 选择本次版本和目标架构匹配的非空 `.dmg`；缺失、歧义或版本/架构不匹配时失败，不发布带悬空地址的清单。上传顺序为更新包、签名及首装包全部成功后再更新渠道清单，Windows 相同对象只上传一次。`dry-run` 不写 OSS。各渠道独立写自己的清单，由 BFF 汇总，Windows 与 Mac 发布不会覆盖彼此的下载项；Mac 跨架构合并仍遵循现有单架构发布约束。
 - Jenkins 流水线需要新增渠道参数与签名凭据；签名私钥与密码只以受保护凭据注入当前进程，不写入 workspace、日志或归档产物。
 - 归档证据：安装包、`.sig`、渠道清单与源码 commit。
 
 ## 验收标准与证据
 
+渠道与系统分离的定向验证覆盖发布脚本、上传计划、网站配置贯通及跨渠道链接拒绝：`build-release.test.mjs`、`release-oss.test.mjs`、`platform-oss client_downloads` 和 `api-server client_download`。本地隔离数据库的 API smoke 验证 `/healthz` 成功、配置 release 时仅读取 release 分区、查询参数不能覆盖渠道、未发布版本返回空列表且 `no-store`；这不代表已构建或上传 release 安装包。真实 Windows/macOS 安装、签名和更新仍由发布验收单独执行。
+
 官网下载与固定服务地址已于 `2026-09-19` 完成源码验收：
 
 | 条款 | 验收方式 | 结果 |
@@ -161,11 +171,11 @@
 - macOS 采用 universal 包，两个平台键对应同一更新产物；主程序用 lipo 检查两种架构，Codex 资源分别做原生身份/摘要与启动验证。Rosetta 结果不代替 Intel 真机验收。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
-- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、渠道清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为开，只有显式关闭才会写入 OSS。
+- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为开，只有显式关闭才会写入 OSS。
 - macOS 代码签名与公证暂缺：产物为未签名 + 未公证，`--no-sign` 保留，构建清单与 `latest.json` 显式记录 `appleSigned=false` / `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
 - 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。
 
 待办：
 
-- macOS `dev-mac` 渠道已落地构建与发布能力：Mac Jenkins 节点、release 入口（更新包 + 签名 + 首装包 + 渠道清单）、验签门禁与 dry-run 默认开启均已就绪。
+- macOS 分区（`<channel>-mac`）已落地构建与发布能力：Mac Jenkins 节点、release 入口（更新包 + 签名 + 首装包 + 分区清单）、验签门禁与 dry-run 默认开启均已就绪。
 - 剩余待办：Apple 代码签名与公证凭据（未就绪期间以未验证项记录）、macOS 安装后重启接管新版本的实机验证、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）。

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

@@ -8,6 +8,17 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 - 客户端侧：Rust `template_library` 模块（读清单、下载、安装、建项目）+ 模板库全屏页 + 首页模板推荐 + 左侧导航入口。
 - 不在本次范围：模板制作工具、模板审核、模板计费、增量更新、已建项目的模板回填。
 
+## 模板库灰度访问
+
+- 后台现有灰度发布页登记 `agc:template-library`，控制整个模板库；复用用户 ID 白名单、用户标签、拒绝名单和稳定用户分桶比例，不新增数据库表或字段。未配置此 Gate 时默认关闭；已配置且停用灰度时遵循现有语义全量开放，启用灰度时拒绝名单优先于白名单及比例。
+- `/api/runtime/frontend-config` 增加 `agcTemplateLibraryEnabled`，按认证主体返回服务端权威结论。客户端尚未得到结果、匿名或请求失败时关闭入口；权限结果不作为离线缓存。
+- 登录、主体变化、窗口重新获得焦点和每次模板操作时刷新权限，不承诺后台修改的实时推送。未获准时首页模板推荐和左侧模板库导航隐藏，不读取 OSS 清单；已在模板页检测到失去权限时回到首页。原生命令明确拒绝或权限检查失败后同样清空并关闭入口。账号切换或退出后立即清空前一主体的清单、操作状态和可见性，旧异步响应不能恢复权限或导航。
+- 原生清单读取、下载和模板建项命令均独立核对当前平台会话及服务端权限，不能依靠前端隐藏；远端等待后的会话变化必须拒绝，安装和建项写入使用当前会话身份保护。已缓存清单和已安装模板不能绕过权限。
+- 此灰度控制当前客户端的产品功能，不承诺公开 OSS 模板内容的保密性，也不限制已创建项目的正常打开和编辑。旧客户端升级后才接入此控制。
+- 验收覆盖缺省关闭、明确全量、允许/拒绝名单、标签和比例、请求失败、缓存绕过、原生命令阻断、首页/导航/模板页以及账号切换竞态。
+- 验证入口：后台灰度页面测试、`useTemplateLibrary.test.tsx`、AppSurface 实际挂载的 template 用例、原生 `template_library` 测试和后端 `frontend_runtime_config` 测试。退出开始使用既有平台会话代次立即撤销，建项返回、revision 读取和预览核验后的旧回调均不得导航或登记最近项目；同主体 token 轮换不误撤销原生身份。
+- 本地隔离数据库已验证 Gate 经后台 API 保存后可重新读回，匿名运行时配置为 false；后台受控浏览器 smoke 验证桌面和 320px 布局及保存确认交互。线上 OSS 下载和正式安装包登录后的端到端操作不由这些测试替代。
+
 ## OSS 契约
 
 ```text

docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md

@@ -4,7 +4,7 @@
 > 规范关系：AGC 插件与编辑器适配主规范
 > 验收范围：插件 manifest、宿主生命周期、RPC、Capability/权限审计、UI 挂载和编辑器适配器边界
 
-更新时间：`2026-09-18`
+更新时间：`2026-09-20`
 
 ## 目标与边界
 
@@ -72,7 +72,16 @@ OpenAI 的标准模型是“Plugin 作为可安装包，组合 Skills、可选 M
 
 Windows 与 macOS 构建都将内置插件的清单、JS 入口与面板复制到应用资源目录；staging 每次重建，避免已删除插件或跨目标原生 payload 残留。macOS 不携带 Windows native payload。Cocos 进程桥接仍仅按既有 Windows 平台实现提供，插件文件可被发现不代表 macOS 已支持编辑器控制；JS 入口的系统 Node 前提不变。
 
-Cocos 插件对用户可见与可启动必须同时满足当前为 Cocos 项目、宿主已注册 `cocos-editor` 原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器仅在 Windows 且编译 `cocos-editor-execute` 时注册；Agent 工具使用相同平台与 feature 门禁。前端只按后端列表投影判断是否自动启动，不自行推断平台能力。
+Cocos 与 Unity 插件的可见性、启动、面板、插件 RPC 和 Agent 工具暴露不按当前工程类型过滤；无当前项目以及普通 AGC、Godot、Cocos、Unity 项目使用同一套插件可用性规则。宿主必须已注册插件声明的原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器与 Agent 工具继续受各自平台和编译 feature 约束，禁用开关继续阻止启动与工具执行。前端只按后端列表投影判断是否自动启动，不自行推断平台能力或再次按工程类型过滤。
+
+### 工程上下文与真实编辑器目标
+
+- 工程类型只用于工程识别及对应工程工作流，不作为 `agc-cocos-editor` / `agc-unity-editor` 的管理、面板或工具目录门禁。Runtime、DirectProject MCP、工具策略快照和模型上下文使用一致规则；工具已暴露不代表真实编辑器已连接或操作已成功。
+- 前端对宿主列表中的 Cocos 与 Unity 插件分别根据适配器支持、启用、Runtime 入口和运行状态投影自动启动，不按项目类型二选一；自动启动不自动展开编辑器面板。
+- 项目切换不因新工程类型不同而停止插件或隐藏工具；当前受控项目上下文仍须按既有顺序更新，旧编辑器连接失效。旧请求与回执保留原项目归属，不能更新新项目连接状态。
+- 实际编辑器操作仍须取得有效的当前受控项目和与之匹配的真实编辑器目标。宿主注入项目路径，显式路径必须与当前受控项目一致；适配器继续校验真实工程结构、目标 PID、进程身份、版本与握手。无项目、不匹配的工程目录、无编辑器或不支持的平台均应在发送编辑器操作前明确失败，不回退到其它项目或任意编辑器进程。
+- 插件启用状态、manifest 适配器绑定、`editor.rpc` 权限、超时与并发拒绝、执行结果不确定阻断均保持原合同。取消工程类型过滤不增加自动重试，不清除项目切换或重启插件前已经产生的不确定状态。
+- 不新增或迁移项目类型、内置插件开关、API/DTO、SpacetimeDB schema 或持久项目数据；不扩大 Cocos/Unity 原生适配器的平台支持，也不把任意非引擎目录解释为可执行的编辑器工程。
 
 ### 内置插件与可用开关
 
@@ -141,6 +150,7 @@ OpenAI 官方 Plugins 文档将 Skills、MCP Server 和可选 UI 定义为同一
 - Rust：manifest 路径/权限校验、目录扫描、权限拒绝和通用适配器 registry 边界单测；`cargo check --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`。
 - 前端：`agc-plugin-sdk` TypeScript 编译、宿主服务类型检查，以及 `PluginPanelHost` 的挂载/卸载测试。
 - 内置插件开关：`builtin_plugins` 单测覆盖默认值、持久化往返、坏文件失败关闭，以及“禁用后工具目录里不再出现该工具”；`plugin_host` 单测覆盖禁用后不能启动、启用后回到 stopped。
+- 工程类型独立性：覆盖无当前项目、普通 AGC、Godot、Cocos、Unity 上下文中的插件列表、启动、面板、RPC 与 Runtime/DirectProject 工具目录一致性；项目切换不因类型变化停止插件。保留禁用开关、缺失原生适配器、平台/feature、显式跨项目路径拒绝与真实编辑器目标校验的独立反例；非引擎目录不能仅因工具可见就通过实际操作校验。
 - 插件工作区：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 覆盖工作区扫描与 manifest 启用状态；`cargo test --manifest-path plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml` 覆盖 Cocos 适配器；`node --test plugins/agc-cocos-editor/src/entry.test.mjs` 覆盖插件入口协议与 manifest 一致性。
 - 通用仓库门禁：`npm run check:encoding`、`git diff --check`；发布前仍需单独执行 AGC package smoke 和安装包 smoke。
 

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

@@ -1,5 +1,23 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 项目主模型使用记录
+
+- 项目在 `.agent/model-usage.jsonl` 保存主模型记录，供复制或压缩完整项目后查询，不新增界面展示。每条只保存版本、记录时间、来源、请求模型标识、可确认的模型名称，以及可用的客户端回合和线程身份；不保存提示词、响应正文、连接地址或凭据。
+- DirectProject 每次提交回合前保存本次请求的模型快照，来源为 `turn-request`。官方目录标识与真实型号分开：官方标识只写 `requestedModel`，不能把 `platform-default`、目录 ID、`Direct Codex` 或 `codex-app-server` 当成模型名；自定义路由保存明确提交的型号。响应返回的模型名以 `provider-response` 追加，使用请求发出时冻结的项目/回合归属，后续切模型不会覆盖历史。
+- 模型名从成功 Responses JSON 的顶层 `model` 或 SSE `response.created` / `response.in_progress` / `response.completed` 中的 `response.model` 提取；只读取白名单字段，有界处理分块和异常数据，响应内容仍原样转发。上游没有返回型号时保留请求证据，不推测实际模型。
+- 旧项目通过 `project.status` 读取 manifest 成功后补录一次：在有界范围内优先恢复项目内可明确识别的主模型运行记录，超出历史扫描预算时跳过对应候选；没有找到可信历史型号时写入当前配置快照并标注 `current-config-backfill`，不声称其为历史事实。官方配置只有目录标识时保留标识，模型名为空；以后真实回合仍继续追加。补录幂等，不覆盖或改写原项目历史。
+- 记录复用项目受控路径与追加锁；无写权限、损坏或超限时保留已有文件并写安全诊断，不因此中断项目打开、模型响应或触发额外付费重试。响应记录在阻塞工作线程中追加，文件锁等待不阻塞响应原始块转发。补录仅发生在项目 `project.status` 命令和本次回合入口，不扫描机器上的其它项目或私人会话。
+- 验收覆盖：请求与响应的模型差异、跨回合/项目隔离、切模型保留历史、旧项目补录及幂等、分块 SSE/JSON、不含模型/失败响应不伪造型号，以及凭据/正文不落盘。使用本地 HTTP fixture 验证代理透传和落盘，真实供应商调用另行报告。
+
+| 合同 | 自动化证据入口 |
+| --- | --- |
+| 来源区分、切模型保留历史、补录幂等、损坏/超限保护 | `project::model_usage::tests` |
+| JSON/SSE 字节透传、模型落盘与跨回合归属 | `agent::codex_provider_proxy::tests::model_usage_proxy_*` |
+| 分块 UTF-8、换行、多行事件和有界解析 | `agent::codex_provider_proxy::model_usage::tests` |
+| 文件锁争用不阻塞响应、流中断仍保留已确认型号 | Provider 代理的锁争用与流错误 fixture |
+
+记录格式版本为 `schemaVersion: 1`。`recordedAtMs` 是记录时间，`historicalModelConfirmed` 仅在响应观测或可信历史恢复时为 `true`；它在请求快照和当前配置补录时为 `false`。上述本地 fixture 不替代真实供应商或安装包验收。
+
 ## 2026-09-17 GameCreationApp 资源 kind：唯一词汇表、严格解析与 `app_log!` 留痕
 
 本节覆盖 2026-09-15 节里关于「canonical 字符串列表 / legacy 别名表 / `tracing` 留痕 / ts-rs 生成路径」的表述；枚举成员集合、「不迁移、不静默转换」的总体口径不变。
@@ -468,6 +486,8 @@ V1.11 的受保护仓库控制目录同时包含 `.git / .agent / .agents / .cod
 
 Prompt 静态门禁必须断言上述 Bundle section 当前定义的权威语义与组合关系；身份文案调整后应同步更新旧断言，不得继续依赖已经退出 Bundle 的历史连续措辞，也不得在测试或 Provider builder 中复制一份平行 Prompt。
 
+Agent 可见的系统指令、工具与参数说明、恢复指引和上下文模板统一由外置提示词文件维护。AGC 沿用 `prompts/runtime/manifest.json`：已有 composition/section 保持原有组合关系，独立调用的文本按职责登记在 `textCatalogs`，目录为 `prompts/runtime/texts/`，每份 JSON 是稳定文本键到正文的映射。构建期校验目录、文件、重复键和空正文，并生成可供 `format!` 使用的编译期文本宏；变量填充沿用 Rust 格式语法。Runtime 状态、用户内容、schema 类型与枚举、权限和校验继续由代码生成。服务端 Agent 的独立 crate 使用各自 `prompts/` 中的编译期文本文件。迁移以当前组装结果和工具 schema 等价为验收依据，源码门禁检查各提示词入口的内联正文与外置引用。
+
 2026-07-12 起，通用开发能力的 Runtime V1.1 增量以 [`【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`](<./【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md>) 为编码级事实源。它补充仓库启动上下文、同一发布二进制独立 Runner、受限本地预览浏览器验证、动态隔离子 Agent 和真实 Provider 全链路验收；本文件中“进程内 tokio task”“首轮不预加载项目内容”和“不创建动态执行实例”的旧口径由 V1.1 明确替代，未涉及能力继续沿用本文件。
 
 同一文档的“V1.2 对标 Codex CLI 增量”继续作为受控命令与推理档位的事实源。对一次性 `command.exec` 而言，只接受 Runtime 白名单内的固定 `program` 和逐项 `args` argv，默认 `confirm`，可执行文件解析为项目外绝对路径且子进程只使用安全 PATH；不解析 shell 字符串，不提供管道、重定向、PTY 或后台进程。这里对 PTY 和后台进程的排除仅适用于 `command.exec`，不能用来否定 V1.10 的独立持久进程工具，也不能把 `command.exec` 自身改成长驻入口。`command.exec` 的 action、stdout / stderr、退出码、超时与源码指纹结果统一进入现有 `action / observation`、project revision、verification gate 和 `needs-reconciliation` 链路；只有明确验证型命令且退出码、源码指纹、命令日志、manifest 与 Agent DB 审计全通过才签发 passed gate，Git / rg / cargo metadata / 普通 npm run 只作诊断。首版只请求终止受控进程组，安全等级与 `project.verify` 相同，不宣称已具备完整 OS sandbox 或 detached-process 隔离。
@@ -1371,12 +1391,12 @@ game-project/
 
 ## 2026-08-20 Direct Codex 审核 Skill Pack 与受控工具内核
 
-- 普通项目对话只由一个 project-bound Codex app-server thread 执行。客户端系统提示词只放最小工程合同、当前游戏源码有界快照、项目 prompts 和审核 Skill 索引；不再批量读取项目 `.codex/.agents` Skill 正文，也不恢复 Supervisor、专业 Agent 或 harness。
-- 首页恢复“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。该选择与设置页的 Agent Runtime 模式无关；每次首页提交仍只自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 仅作为受限结构化首轮上下文传给同一 Codex thread，不拼接“初始意图”文案、不产生首页对话、不切换 Provider 或恢复旧 Runtime 编排。
+- 普通项目对话由一个 project-bound Codex app-server thread 执行。客户端系统提示词包含最小工程合同、项目 prompts 和审核 Skill 索引；源码与 Skill 正文按任务需要读取。提示词、工具描述与 Skill 直接描述当前任务、输入和成功条件，细节按调用需要提供。
+- 首页提供“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。每次首页提交自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 作为受限结构化首轮上下文传给同一 Codex thread。
 - `agc-skill-pack.v1` 只包含项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影五项 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync`，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文由 Codex 原生 Skill 机制按意图加载，一层引用只能经 `agc_read_skill_resource` 读取清单内 Markdown。引用路径按平台无关规则拒绝反斜杠、盘符、UNC、绝对路径和 `..`，不能依赖当前宿主的 `std::path` 语义判断其它平台路径。
-- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP；2026-08-31 起还会在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置，但不读取用户全局 Codex MCP、不开启完整 Plugin Runtime。内置工具固定为审核引用读取、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`。内置 MCP 进程只做协议；真实浏览器、付费 External v1 调用与受控搜索通过随机 loopback 地址回到客户端主进程，因此不复制 GUI 登录态、开发者 Key、项目路径、revision、operation 或幂等键到模型上下文。内置与用户启用的第三方 MCP 工具都沿用 DirectProject 自动批准方式，但付费资源工具仍由客户端绑定稳定回合身份、限制单回合请求数、串行执行并优先恢复匹配账本；通用 shell、Codex 原生 webSearch、任意原生命令网络、多 Agent 和完整插件能力继续关闭。`llm.webSearchEnabled` 只控制 DirectProject 的 AGC 受控搜索工具暴露与执行，Codex 原生 `web_search` 始终保持 disabled；Provider、ToolHost、DirectHome 不纳入本次联网主链路。
-- 陶泥儿生成继续复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端优先使用当前 AGC 登录会话及账号路由，只有受控的 ExternalDeveloper 发布模式才在客户端内部使用按服务器 origin 隔离的私有 Key。用户和模型都不需要提供或配置 API Key；凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
-- 自定义 LLM API Key 路由只在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理不注入 Key，只要求请求自带 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，防止隔离 app-server 把 API Provider 误判为余额 0；旧 ToolHost 保持原 Provider 行为。
+- DirectProject 连接客户端内置的 `agc_tools` STDIO MCP，并在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置。内置工具包括审核引用读取、图片生成、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`。内置 MCP 进程负责协议；真实浏览器、付费平台调用与受控搜索通过随机 loopback 地址回到客户端主进程，GUI 登录态、开发者 Key、项目路径、revision、operation 与幂等键由客户端持有并隔离于模型上下文。内置与用户启用的第三方 MCP 工具沿用 DirectProject 自动批准方式；付费资源工具由客户端绑定稳定回合身份、串行执行并优先恢复匹配账本。`llm.webSearchEnabled` 控制 DirectProject 的 AGC 受控搜索工具暴露与执行。原生工具与审批权限以下方“DirectProject Codex 完整访问覆盖”为准。
+- 陶泥儿生成复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端使用当前 AGC 登录会话及账号路由，受控的 ExternalDeveloper 发布模式在客户端内部使用按服务器 origin 隔离的私有 Key。凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
+- 自定义 LLM API Key 路由在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理使用请求自带的 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，按实际 API Provider 响应判断请求结果。
 
 - 2026-08-12 计划拒绝恢复：结构化 `runtime.plan_update` 被 Runtime 拒绝后，下一轮 Provider 请求按请求级目录收窄到实际项目 mutation 与 `respond_to_user`（已进入协作编排的 Supervisor 保留 `agent.delegate / agent.run_status`），并明确禁止再次规划、读取、搜索或验证；后续已有真实 mutation observation 后解除临时目录，不改变持久 executable policy。
 
@@ -1437,13 +1457,13 @@ game-project/
 
 ## DirectProject 工具权限现行覆盖（2026-08-24）
 
-本文早期关于“DirectProject 关闭通用 shell、原生网络和主动工具”的描述属于迁移前基线；2026-09-14 起，DirectProject 的 Codex sandbox 与审批规则由下方“完整访问覆盖”取代。其余 ToolHost/DirectHome 合同不变。客户端审核的 `agc_tools` MCP 继续承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并保留项目锁、幂等账本、下载校验、恢复与投影权威。
+DirectProject 的 Codex sandbox 与审批规则以下方“完整访问覆盖”为准。客户端审核的 `agc_tools` MCP 承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并持有项目锁、幂等账本、下载校验、恢复与投影权威。
 
 ## DirectProject Codex 完整访问覆盖（2026-09-14）
 
-DirectProject 现明确采用 Codex app-server 的 `danger-full-access` sandbox：thread 使用 `sandbox="danger-full-access"`，turn 使用 `sandboxPolicy.type="dangerFullAccess"`，不再发送 `workspaceWrite`、`writableRoots` 或项目根文件批准白名单。DirectProject 收到 app-server 的文件变更、命令执行和权限请求时直接接受，Codex 原生能力不再按项目路径做二次白名单裁剪；用户选择的项目目录仍作为 cwd 和 AGC 业务身份根，用于连接池、审计与客户端受控 MCP 的项目绑定。
+DirectProject 采用 Codex app-server 的 `danger-full-access` sandbox：thread 使用 `sandbox="danger-full-access"`，turn 使用 `sandboxPolicy.type="dangerFullAccess"`。DirectProject 收到 app-server 的文件变更、命令执行和权限请求时直接接受；用户选择的项目目录作为 cwd 和 AGC 业务身份根，用于连接池、审计与客户端受控 MCP 的项目绑定。
 
-这项覆盖只改变 Codex 原生 app-server 的 sandbox 与审批边界：首页只读对话、AGC `agc_tools` MCP 的业务授权、Provider 凭据隔离、Runtime 审计与客户端 `agc_write_file` 的产品契约继续有效。系统提示词不再把 `.agent/`、`.git/`、项目外路径等描述为 Codex 原生能力禁区，但仍要求不要把 Token、Cookie、auth.json、`.env` 或 Runtime 私有控制面主动输出到对话、工具参数和日志。
+首页按只读对话执行；AGC `agc_tools` MCP 按业务授权执行，Provider 凭据保持隔离，Runtime 审计与客户端 `agc_write_file` 遵守各自产品契约。Token、Cookie、auth.json、`.env` 或 Runtime 私有控制面禁止主动输出到对话、工具参数和日志。
 
 DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过泛化 ToolHost 包装；原生命令网络随完整 sandbox 开放；联网资料仍可走受控 `agc_web_search`。多 Agent、Apps、完整插件 Runtime、hooks、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制仍关闭，避免绕过 AGC durable delegation、浏览器证据和副作用审计；图片生成通过客户端审核的 `agc_tools.agc_generate_image` 暴露普通单图、角色图、视觉规范图和 UI 设计图，完整游戏美术包继续使用 `agc_tools.taonier_prepare_game_art`，两者都复用同一客户端登录态、幂等账本、下载校验和 manifest/revision 投影，不开放 Codex 原生 image tool。app-server 使用隔离 `CODEX_HOME`：内置 `agc_tools` 由客户端启动参数注入，用户在客户端扩展列表启用的独立第三方 MCP 以原生配置写入该次隔离 home；全局 Codex MCP、禁用项、Plugin hooks/apps 和其它插件能力不进入 DirectProject。第三方项固定非 required，配置或启动失败只记录该项，不替换 `agc_tools`；provider session token、工具桥地址和受控搜索标记不得通过第三方 MCP 的环境转发字段泄露。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅使用连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。`agc_tools` 的平台授权由 AGC 客户端当前登录会话和受控后端完成，普通客户端不得把 DirectProject 请求改成外部 API Key 请求；401/403 只投影为客户端登录或权限异常，不向用户索要凭据或暴露内部 URL。shell 子进程采用 `shell_environment_policy` core 继承及 secret/proxy/bridge 排除，provider key 和桥接凭据不得进入命令环境。系统提示词不再预注入项目源码快照或 Skill 正文，Codex 按需读取当前 cwd 文件。
 ## 2026-08-24 AGC UI 原型桥接与自主 UI workflow
@@ -1616,23 +1636,23 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 ### 目标与非目标
 
 - 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；重复内容不重复上传，远端占用跟随当前清单收敛。
-- 非目标：不做云端下载/恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
+- 非目标：不做客户端云端恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
 - 非目标：不把 OSS AccessKey 放进客户端；客户端不直连 OSS。
 
 ### 参与入口、状态与跨模块边界
 
-- 触发入口有两个：工作区窗口 `main` 存活期间的周期定时器、工作区窗口关闭事件（`CloseRequested`）。两者共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
-- 应用退出（`RunEvent::Exit`）不重复发起同步：该时刻窗口已销毁，按窗口重新枚举项目只会得到空集；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步能写完索引再退出。
+- 触发入口为项目生命周期登记、已登记项目的周期定时器及窗口关闭事件（`CloseRequested`）。它们共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
+- 应用退出（`RunEvent::Exit`）不重复发起同步；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步有机会写完索引再退出。超过预算不能声明最后状态已经上传。
 - 客户端扫描、差异对比、索引持久化与上传编排都在 Tauri Rust 进程（`src-tauri/src/project_snapshot/`）；WebView 只读状态，不参与差异计算。
 - 本地索引是增量对比的唯一依据：`<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` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
-- 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`，未配置时回退 `ALIYUN_OSS_*`；与"资源 bucket 与备份 bucket 分离"的既有口径一致。
+- 目标 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 的现存数据。
 
 ### 正常、失败、重试与幂等行为
 
-- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `sha256`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件。
+- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `fnv1a64`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件；清单元数据变化单独提交。
 - 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。清单描述的是项目当前全量内容，因此清单体积就是该项目在 OSS 上的常驻占用。
 - 远端回收：清单写入成功后，服务端读取上一版清单，按 `(路径, 字节数, 摘要)` 反推出不再被当前清单引用的对象键并删除。只处理上一版清单登记过的键，不做 LIST，因此不可能误删其它项目或其它功能的对象；单次最多回收 2000 个对象，剩余部分留到下一次清单写入继续；上一版清单读不到或解析失败时整轮跳过回收（fail-closed）。单个删除失败只记日志，不影响本次同步语义。
 - 因此本功能是"当前状态镜像 + 清单"，不保留历史版本：同一路径的内容变化会覆盖式替换远端对象，回滚能力不在本轮范围内。
@@ -1656,6 +1676,18 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 运行时 smoke：AGC 开发态打开项目、观察索引写入与同步日志、关闭工作区窗口后确认关闭触发的那次同步执行；报告为"客户端 diff 已验证 / 服务端已配置环境联调"两层，不合并成一句"已通"。
 - 边界：新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。
 
+### 后台工程列表与下载
+
+- 正式客户端在单窗口内切换启动器和项目，不以窗口 URL 判断活动项目。前端把当前窗口的已打开项目登记给原生同步器；打开后发起首轮同步，离开/切换项目和物理关窗为旧项目补同步，周期扫描只读这份窗口登记。重复登记同一路径不重复发起；注册失败写诊断，不能假装已登记。
+- 清单补充可选 `projectName` 与 `pendingFiles`：名称来自本地 manifest；`pendingFiles` 是本轮失败、延后、并发变动与非策略排除的跳过文件数量。`0` 表示扫描范围已同步；大文件等被跳过不能标成完整。旧清单字段缺失表示完整性未知，维持可读取兼容，不反写旧清单。
+- 项目名称或完整性发生变化时，即使文件内容没有差异也要提交新清单；本机索引记录上次已提交的这两个字段。实际客户端下一次正常同步可补齐历史清单元数据；后台只读访问不迁移旧清单。缺失 `pendingFiles` 不能默认成 0，临时跳过原因消失后允许无文件上传的 `partial → ready` 转换。
+- 后台增加“项目工程”入口，仅 owner 及拥有 `project-snapshots` 页签权限的管理员可访问。`GET /admin/api/project-snapshots?cursor=&limit=20` 读取私有 OSS 清单并返回 `{items,nextCursor}`；单页最多 100 个，游标由服务端校验，目录与清单读取有界。条目为 `{userId,projectId,projectName,syncRevision,syncedAtMs,fileCount,totalBytes,status}`，状态为 `ready / partial / unverified`，名称缺失时显示 projectId。
+- `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 只读取该用户/项目的固定清单与其引用对象，返回 `application/zip` 附件。ZIP 中路径直接使用原始相对路径，不包含 userId、摘要目录或 OSS 前缀；名称使用经过安全处理的项目名和 revision。下载固定本次读到的清单，远端并发回收导致对象缺失则整体失败，不能静默遗漏。
+- `partial` 快照下载返回 409；`unverified` 历史快照可导出已同步文件，列表明确显示“完整性未知”，动作称“下载已存文件”。`ready` 才显示“下载完整工程”。ZIP 构建核验每一文件的长度与 fnv1a64 摘要，拒绝穿越、绝对路径、重复/大小写冲突路径、非法项目身份；缺失或损坏整体失败，不返回成功的残缺 ZIP。
+- ZIP 使用服务端临时文件并限制并发，不将 2 GiB 工程整体驻留内存；成功、失败、客户端取消均清理临时文件。单文件、总量、文件数沿用上传上限，超限明确拒绝。零字节工程文件可以上传和导出。OSS 凭据与签名不下发浏览器，列表失败保留错误而非伪造空列表。
+- 工程归档范围与上传策略一致：源码、素材及引擎配置按原路径保存，依赖/构建缓存、凭据、`.agent` 会话与运行日志排除；此 ZIP 不声明能恢复 AGC 对话历史。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
+- 验收覆盖真实单窗口生命周期登记、首次/增量/零字节上传、后台列表分页和权限、ZIP 解压目录及摘要、部分/历史清单、缺失对象、路径拒绝、下载取消清理，并分别报告定向测试和真实环境证据。
+
 ### 未决问题
 
 - 用户侧看不到同步状态与失败原因（界面按产品口径不暴露），排障只能读 AppData 诊断日志或调用 native-only 命令；如果后续要支持用户自助排查，需要先确认是否允许在客户端出现上传相关 UI。

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

@@ -1,7 +1,9 @@
 # 策划 Agent 生产迁移与工作区浏览方案
 
 更新时间：2026-09-10
-状态：实施中
+状态：已完成（2026-09-18）
+
+> 现状说明（2026-09-18）：本文记录的迁移已完成，当前策划入口统一使用 Design Agent。旧 Planning V1/V2 会话、专用命令、审批卡和展示适配已删除；文中提到的 V2 文件仅代表迁移时的参考来源，不得作为现行实现、回退路径或测试迁移目标。
 
 ## 1. 目标
 
@@ -23,11 +25,11 @@
 
 生产侧复用 Provider、会话恢复、文件读写、审计和 UI 通信等基建，不复用现有立项策划 Agent 的行为协议。
 
-原型行为是新的策划 Agent 契约。现有 `Planning V2` 只作为 Provider 调用、持久化和恢复实现的参考来源，不作为行为、提示词、产物或审批契约。
+原型行为是新的策划 Agent 契约。已退役的 `Planning V2` 仅作为迁移历史中的 Provider 调用、持久化和恢复参考来源，不作为行为、提示词、产物、审批契约或回退路径。
 
 常驻提示词、阶段提示、速览卡结构说明、工具名称与参数、资源目录和注入映射以迁移时核对的原型文件为基线。迁移不顺便重写提示词，不增加模型输出内容门禁。旧需求文档中已明确舍弃的行为不恢复。
 
-本方案描述生产迁移目标。当前已接入独立设计会话、自由工具循环、阶段审批命令和工作区浏览命令；生产入口对无旧 Planning V2 会话的策划项目切换到新设计 Agent，已有 V2 会话仍走原链路。旧 Planning V2 专用展示尚未清理。
+本方案描述已完成的生产迁移。当前入口使用独立设计会话、自由工具循环、阶段审批命令和工作区浏览命令；旧 Planning V2 会话不再继续运行，旧专用展示和命令已删除。历史项目按当前 Design Agent 入口重新开始，不做旧会话转换或旧测试迁移。
 
 ## 3. 复用与丢弃清单
 
@@ -66,16 +68,17 @@
 
 路径穿越、绝对路径、控制目录访问和凭据泄露防护属于安全边界，可以保留；它们不能扩展成限制正常策划创作的业务门禁。
 
-现有参考入口如下。复用对象是其中的可用函数和通信机制，不是整个模块：
+当前实现入口如下：
 
-| 代码入口 | 参考内容与注意点 |
+| 代码入口 | 职责与边界 |
 | --- | --- |
-| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/planning_session_v2.rs` | Provider 配置、请求、重试、会话恢复；丢弃问询计数策略、强制工具和输出纠错协议 |
-| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/file_ops.rs` | 读写、补丁和删除实现；不可原封不动继承 owner、产物和任务门禁 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/design_runtime.rs` | Provider 请求、工具循环、重试、阶段审批与会话恢复 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/design_session.rs` | 设计会话、阶段状态与待交互请求的持久化 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs` | 固定资源包、工作区文件读写、补丁、删除、搜索与路径安全边界 |
 | `apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs` | 路径解析、文件列出和读取、基础写入；内部绝对路径字段不得传给模型 |
-| `apps/ai-game-creator-shell/src/App.tsx` | Tauri 事件订阅、文件刷新、会话恢复入口；不把旧策划状态投影当作新契约 |
-| `apps/ai-game-creator-shell/src/features/project-workspace/ProjectWorkspaceChatPane.tsx` | Game Agent 文件列表与读取入口；新的文件浏览应直接打开文件视图，不往聊天中追加文件正文 |
-| `apps/ai-game-creator-shell/src/features/project-workspace/GddApprovalCard.tsx` | 仅参考现有面板和通用交互样式；不沿用结构化 GDD 展示及三按钮决定模型 |
+| `apps/ai-game-creator-shell/src/App.tsx` | Design Agent IPC、事件订阅、文件刷新、会话恢复与输入提交 |
+| `apps/ai-game-creator-shell/src/features/project-workspace/DesignWorkspacePanel.tsx` | 策划工作区文件浏览与正文展示，直接打开文件视图 |
+| `apps/ai-game-creator-shell/src/features/project-workspace/DesignAgentSurface.tsx` | 消息、reasoning、澄清与阶段审批交互 |
 
 不为此次迁移先建设通用 Agent 框架。已有函数能够直接使用就直接使用，只有确实需要拆除业务耦合时才做局部拆分。
 
@@ -239,6 +242,8 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide
 
 澄清卡提供独立的选项回答和自由文本回答。点击选项只提交请求身份和所选选项，不携带文本框草稿；Runtime 根据已保存的问题/选项形成明确的回答内容，不只传递“3”之类的序号。用户也可不选择任何选项，直接填写文本并点击“提交回答”，发送请求身份、`optionIndex: null` 和文本正文，Runtime 将其表述为“用户回答”，不将它当作某个选项的补充。新澄清请求出现时清空上一题的文本草稿。不沿用生产旧问题数量上限和固定问答字段。澄清卡待回答状态应可在重启后恢复。
 
+用户向上滚动查看策划历史时暂停自动跟随；发送新的普通消息后恢复跟随最新消息和回复，仅编辑输入内容不改变历史阅读位置。
+
 ## 8. 用户工作区浏览
 
 `design_artifacts` 同时是 Agent 工作区和用户查看策划资料的文件区。用户不需要通过聊天请求 Agent 才能看到文件。
@@ -307,7 +312,7 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide
 
 实现落在生产 Rust 会话/工具层与现有 React 策划入口，不随应用再启动 Python 原型进程。保持单一用户入口，不为迁移建设第二套工作台。
 
-切换前盘点旧 Planning V2 活跃会话和持久化数据。旧结构化 GDD 不能直接推断为新五阶段中的某个阶段，不自动转换或覆盖已有项目。旧会话的继续运行或只读保留方式需在实际盘点后明确，再处理入口退役；这不要求新 Agent 兼容旧 GDD 行为。
+迁移时不把旧 Planning V2 会话或结构化 GDD 转换为新五阶段状态。旧命令、旧展示和旧测试已删除；当前入口不读取旧 V2 authority，也不要求新 Agent 兼容旧 GDD 行为。
 
 ## 12. 验收标准
 
@@ -340,7 +345,7 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide
 - 外部搜索；
 - 多个策划身份提示词同时存在；
 - 多 Agent 协作；
-- 旧 Fast GDD 展示和 GDD schema 兼容。
+- 不迁移旧 Fast GDD 展示、V2 schema 或旧测试；新 Design Agent 使用自己的会话和阶段产物测试。
 
 ## 14. 开发调试入口
 

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

@@ -1,10 +1,10 @@
 # 策划会话 Runtime V2 接入与旧链路退役方案
 
 - 日期：2026-09-03
-- 状态：P0 合同冻结、P1 内核、P2 产物闭环、P3 入口/UI 接入、P4 灰度回归验收与 P5 旧链路退役均已完成；本文是新生产实现的目标方案与阶段验收合同
-- 适用范围：AGC 桌面 App 的“做方案”入口、策划会话、GDD 产物与审批
+- 状态：**历史方案，已完成并退役**。Runtime V2 及其专用入口、命令、展示和测试已在 2026-09 按四不写原则删除；当前“做方案”统一使用独立 Design Agent。
+- 适用范围：历史 AGC“做方案”入口、策划会话、GDD 产物与审批设计
 
-> 本文规定新策划 Agent 的生产接入和旧链路退役方式。P3 开始修改正式 AGC 入口与工作台，但旧 `project-supervisor-plan` / `project-planning` 源码仍保留，直到 P5 完成退役；V2 切换时旧链路直接封存，所有未完成旧会话强制失败，旧 Fast GDD 文档之后只作为历史记录依据。
+> 本文只用于追溯 Runtime V2 的设计和退役过程，不是现行实现依据。不要恢复 `planning_session_v2`、`planning_policy_v2`、`hydrate_planning_session_v2` 或 V2 专用 UI；当前行为以 Design Agent 生产迁移方案和代码为准。
 
 ## 1. 决策摘要