合并资源编辑与当前主线改动
Project CI / Backend tests (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 1/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 2/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 3/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 4/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust smoke (pull_request) Has been cancelled
Project CI / AI game creator shell Rust crates (pull_request) Has been cancelled
Project CI / Native shell tests (pull_request) Has been cancelled
Project CI / Frontend tests (pull_request) Has been cancelled
Project CI / Repository checks (pull_request) Has been cancelled
Project CI / AI game creator shell web tests (pull_request) Has been cancelled
Project CI / Backend tests (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 1/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 2/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 3/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust shard 4/4 (pull_request) Has been cancelled
Project CI / AI game creator shell Rust smoke (pull_request) Has been cancelled
Project CI / AI game creator shell Rust crates (pull_request) Has been cancelled
Project CI / Native shell tests (pull_request) Has been cancelled
Project CI / Frontend tests (pull_request) Has been cancelled
Project CI / Repository checks (pull_request) Has been cancelled
Project CI / AI game creator shell web tests (pull_request) Has been cancelled
保留资源 kind 强类型与栅格 subtype 严格校验 合并抠图模式、幂等账本、恢复轮询和 PNG 透明通道校验 修正共享资源枚举在 Cocos 登记与抠图桥接中的类型传递 保留双方模板库、项目快照、发布和 Provider 重试改动
This commit is contained in:
@@ -41,6 +41,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)：当前工作台页面和验收边界。
|
||||
|
||||
@@ -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": {
|
||||
|
||||
@@ -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` 在发布管线渠道化前不删除。
|
||||
@@ -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` 写入。
|
||||
- 签名缺失即失败关闭：构建机未注入签名私钥时发布中止，不产生半成品清单。
|
||||
- 渠道端点写进产物：渠道名一旦发布不可改名（改名等于已发布客户端再也找不到更新）。
|
||||
- 回滚点：发布脚本与流水线都在本里程碑内，回滚后客户端仍可用原先的自研清单协议；迁移桥可独立停用。
|
||||
@@ -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/` 前缀即回到空模板库；客户端保留错误与空态展示，不阻断其它功能。
|
||||
@@ -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 与文档修改；无数据迁移。首个检查点为组件用例通过，第二个为工作台集成与类型检查。真实客户端未测则明确保留待验收状态。
|
||||
@@ -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 前缀与错误报告链路。
|
||||
@@ -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 或后续单独开放画板入口。
|
||||
@@ -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 平台条目、跨架构不匹配时的表现。
|
||||
@@ -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、渠道缺少当前平台条目、非主窗口调用。
|
||||
@@ -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 覆盖。
|
||||
@@ -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`。
|
||||
@@ -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，未更新飞书。
|
||||
@@ -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 私有文件写入与目录解析工具。
|
||||
@@ -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 副作用之前；确认响应字段与请求一致。
|
||||
@@ -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`，它们已能真实跑通）。
|
||||
@@ -23,6 +23,30 @@
|
||||
- 验证：`agent::direct_codex_user_item` 定向 16 条通过，覆盖成功注入、生成失败保留引用摘要、非 UI 文档不触发与历史回读不产生 `ui/generated-*.js`。
|
||||
|
||||
|
||||
## 2026-09-18 Provider 瞬态重试次数严格按设置执行（游戏开发 Agent 与策划 Agent 不再被档位收进区间）
|
||||
|
||||
- 背景：AGC 客户端此前把 `agentLlm.<agent>.maxRetries` 按运行档位重新收进固定区间——`autonomous-game-build` 档位（自主构建的游戏开发 Agent 及其继承档位的专业子 Agent）被抬到 12~16，`standard` 档位（含立项策划入口的策划 Agent 与普通 Agent 对话）被压到最多 3；瞬态分类里的上游 400 还在同一预算上再收窄到 2 次。现场把 `maxRetries` 设成 5 时，游戏开发与策划两条链路都不按设置执行。
|
||||
- 决策：删除这三处区间限制，`maxRetries` 严格等于允许的物理重试次数（显式 `0` 仍表示不重试）。运行档位只保留「上游 400 是否算瞬态错误」的判定（autonomous 档位才重试 400），不再改写次数：`AGENT_RUNTIME_PROVIDER_TRANSIENT_RETRY_LIMIT`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_TRANSIENT_RETRY_FLOOR`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_TRANSIENT_RETRY_LIMIT`、`AGENT_RUNTIME_AUTONOMOUS_PROVIDER_UPSTREAM_400_RETRY_LIMIT` 四个常量与 `game_creator_agent_runtime_provider_transient_max_retries_at` 一并删除，换成返回 `{max_retries, retry_upstream_400}` 的 `game_creator_agent_runtime_provider_transient_retry_policy_at`。
|
||||
- 边界：只改重试次数的来源。瞬态错误分类（`timeout / connectivity / transport / 408 / 429 / 5xx / empty-response / deserialize / stream-unavailable`，以及 autonomous 档位下的 400）、`retryBackoffMs` 指数退避（仍封顶 30s）、durable retry sidecar / lifecycle / `-transient-N` slot 身份、cancel / steer / goal 门禁、耗尽后的 reconciliation 口径与「泥点不足不重试」都不变；前端设置面板与 `agentLlm.<agent>.maxRetries` 契约不变。
|
||||
- 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
|
||||
- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
|
||||
|
||||
## 2026-09-17 AGC 抠图提交使用远端画布项目身份
|
||||
|
||||
- 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
|
||||
- 决策：抠图请求及工具回执统一使用 `prepare_external_canvas_generation_context` 返回的远端 `context.project_id`；本地 manifest 项目 ID 只用于绑定键和本地状态，不得作为主站业务请求的 `projectId`。
|
||||
- 验证：客户端定向 Rust 测试、格式、编码和 diff 检查通过；未修改主站路由或 BgFilter。
|
||||
## 2026-09-17 图集切分模式改为显式声明
|
||||
|
||||
- 决策：`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` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
|
||||
@@ -33,6 +57,21 @@
|
||||
- 验证方式：新增 `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，主站前端保持现有行为。
|
||||
@@ -8207,8 +8246,8 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
|
||||
## 2026-08-24 AGC Direct 抠图语义工具
|
||||
|
||||
- 决策：将 External v1 `/api/external/v1/editor/images/background-removals` 通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
|
||||
- 约束：异步结果只投影有界队列状态，不允许模型自行构造源 URL 或在不确定提交后更换请求身份；External v1 负责 API Key、幂等接收与统一 operation 查询，客户端不得绕过该契约。
|
||||
- 决策：将抠图能力通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；普通登录态使用账号鉴权的 `/api/editor/images/background-removals`，ExternalDeveloper 模式使用 External v1 `/api/external/v1/editor/images/background-removals`。客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
|
||||
- 约束：异步结果与恢复语义以本文「2026-09-17 AGC 抠图接入本地资源编辑恢复闭环」决策为准。不允许模型自行构造源 URL 或在不确定提交后更换请求身份；两种路由都接收客户端稳定幂等身份，External v1 继续负责 API Key、幂等接收与统一 operation 查询，客户端不得绕过该契约。
|
||||
|
||||
## 2026-08-24 资源详情动作、空态滚动与最终图多步恢复
|
||||
|
||||
@@ -8849,6 +8888,16 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 决策：Direct Codex 结构化资源引用命中该 kind 时，顺序调用 UI Editor persistence 的 `generate_ui_design_code_at`，生成 `ui/generated-*.js`，并把 `请先阅读生成的带有文档的代码片段: {relative_path}` 追加到当前 prompt。生成失败不阻断本轮引用，追加原始 `生成代码遇到错误{error}`，其它引用继续处理。
|
||||
- 原因：复用 `html_renderer/mod.rs` 统一产物，确保 LLM 读取的代码包含 UI 节点元数据和文档注释；严格 kind + mediaType 判定避免图片资产误走代码生成。
|
||||
|
||||
## 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 核，是同一时间窗里更大的单一消耗方。
|
||||
@@ -8856,3 +8905,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)。
|
||||
|
||||
@@ -51,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 架构边界和验证门禁。
|
||||
|
||||
@@ -6,6 +6,14 @@
|
||||
- **处理（现行口径）**：生成目录一律成对登记 `.prettierignore` + eslint `ignorePatterns`；改 `export_to` 时同步改这两处，并用 `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml` 后 `git diff` 为空来验证幂等。
|
||||
- **易错点**：旧的 `apps/ai-game-creator-shell/src/contracts/generated/` 目录下的同名文件不会自动删除，换目录后必须显式删除旧文件，否则会出现「两个同名 union，改动只落在一个目录」的假绿。
|
||||
|
||||
## 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 宽）点开输入盒右下角的「推理档」，弹层是个**空盒子**：档位文字（默认 / 低 / 中 / 高 / 最高）整片看不见，只剩一个方框。
|
||||
@@ -14,6 +22,16 @@
|
||||
- **易错点**：① 把弹层改成 `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 历史不能按工具条目切页再按消息推进游标
|
||||
|
||||
@@ -27,6 +45,8 @@ JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡
|
||||
|
||||
工作台向窗口标题栏发布运行项目时，若 effect 依赖普通函数派生的回调，发布 Context 会重新渲染工作台，进而再次发布并清理，形成更新深度循环。转发入口须稳定，并在提交阶段更新实际处理器引用；发布数据变化与卸载清理分开。回归测试必须组合真实窗口 Provider 和工作台消费者，只有独立画布测试无法覆盖这条反馈链；回归时用有界发布次数阻止测试失控。画布快速操作时暴露的更新深度错误，也须检查外层状态同步，不能直接归因于滚轮频率。
|
||||
|
||||
活动回合快照的初始签名须与初始空数组一致，首次异步返回空数组不能额外换引用。停用、重新启用或切换读取器时应使旧请求失效，避免晚到结果覆盖新快照；测试需控制 Promise 完成时机，不能用“初始数组已为空”当作请求已结束。无原生读取器时窗口只发布一次空状态。
|
||||
|
||||
## 2026-09-17 工具 schema 声明的上限与真实校验不一致，会表现成「agent 调不动这个功能」
|
||||
|
||||
- **现象**：用户反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。查工具目录时两个工具都在（`agc_edit_image`、`agc_create_or_derive_resource`），图片快速编辑在真实项目日志里还有成功记录；但 agent 侧写一句正常长度的背景音乐描述就失败，而客户端 UI 用同一个提示词却只是被截断加提示。
|
||||
@@ -5685,3 +5705,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`。
|
||||
|
||||
@@ -16,6 +16,7 @@
|
||||
|
||||
## 开发中
|
||||
|
||||
- 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
|
||||
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
|
||||
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
|
||||
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。
|
||||
|
||||
@@ -1,68 +1,137 @@
|
||||
# AGC 客户端更新检查与下载
|
||||
|
||||
## 交付范围
|
||||
更新时间：`2026-09-17`
|
||||
|
||||
AGC 每次启动时由根窗口检查一次公开 OSS 更新清单。清单默认位于
|
||||
`https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/latest.json`，构建时可用
|
||||
`VITE_AGC_UPDATE_MANIFEST_URL` 覆盖为同一受信任 OSS 域名下的 HTTPS 地址。客户端版本取
|
||||
`apps/ai-game-creator-shell/package.json`，通过 `version` 与清单版本比较；只有远端版本更高时显示更新提示。
|
||||
本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。
|
||||
|
||||
清单格式：
|
||||
## 目标
|
||||
|
||||
- 客户端自动更新改用 Tauri 官方 `tauri-plugin-updater`：清单请求、版本比较、更新包下载、签名校验、安装与退出全部在原生侧完成；前端只负责触发、展示和渠道选择。
|
||||
- 更新按渠道分发。当前渠道集合为 `dev-win`（Windows x64）与 `dev-mac`（macOS）；构建管线按渠道产出并上传清单，客户端只读取自己渠道的清单。
|
||||
- 更新链路的信任来源从「清单里的 sha256 + 受信域名」升级为「发布签名 + 受信域名」：清单里的 `signature` 由构建期私钥生成，客户端用内置公钥校验，校验不过就拒绝安装。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不做灰度放量、分批更新、强制更新和自动回滚；渠道只决定「取哪份清单」。
|
||||
- 不做后台静默自动安装：是否下载安装始终由用户在更新提示里确认（仅「是否显示提示」受渠道与开发态开关影响）。
|
||||
- 不支持应用商店分发（Microsoft Store / App Store）、移动端更新和企业内网自建更新服务。
|
||||
- 不为自研 sha256 清单协议保留长期实现；迁移桥（见「契约与迁移」）只用于把已发布客户端带到新协议，随后整条删除。
|
||||
|
||||
## 入口与边界
|
||||
|
||||
- 用户入口：
|
||||
- 客户端启动时在根窗口检查一次渠道清单，发现新版本时显示更新提示，用户可下载并安装。
|
||||
- 运行时设置「关于」页提供手动检查更新（强制刷新）。
|
||||
- 涉及模块：AGC 客户端（Rust `src-tauri`、前端 `src/`）、AGC 构建与发布脚本（`apps/ai-game-creator-shell/scripts/`）、Jenkins 发布流水线、OSS 对象布局。
|
||||
- 正式状态来源：
|
||||
- 客户端当前版本以 Tauri app version 为唯一权威来源（`tauri.conf.json`，由发布脚本与 `package.json`、`Cargo.toml`、`Cargo.lock` 同步递增）。
|
||||
- 远端最新版本取自当前渠道的 `latest.json`。
|
||||
- 信任边界：清单地址在构建期确定并烘焙进产物；客户端不接受用户输入、后端响应或项目文件提供的更新地址，也不回退到其它渠道或旧协议地址。
|
||||
|
||||
## 必须成立的行为
|
||||
|
||||
### 正常路径
|
||||
|
||||
- 正式包启动时检查一次渠道清单；仅当清单版本高于当前版本时显示更新提示，提示包含目标版本与发布说明。
|
||||
- 用户确认后下载更新包：下载期间显示进度与已下载字节数；下载完成后按平台安装。
|
||||
- Windows 使用静默安装模式（NSIS `quiet`），安装启动成功后客户端退出并由安装程序重启新版本；macOS 由客户端在安装完成后重启进程接管新版本。
|
||||
- 渠道在构建期确定并烘焙进产物：`dev-win` 产物只读 `dev-win` 清单，`dev-mac` 产物只读 `dev-mac` 清单，同一份二进制不会在运行期跨渠道切换。
|
||||
- 开发态（`npm run agc` / `agc:serve` 由 Vite dev server 提供前端）不检查更新、不显示更新入口，也不下载任何更新包。
|
||||
|
||||
### 失败、重试与幂等
|
||||
|
||||
- 清单请求失败均静默忽略，不阻塞客户端启动：网络错误、TLS 错误、404（渠道尚未发布版本）、格式非法、渠道没有当前平台条目、远端版本不高于当前版本。
|
||||
- 同一客户端生命周期内只自动检查一次；手动检查可强制刷新。
|
||||
- 签名校验失败、下载中断或写入失败必须失败关闭：删除临时文件、不启动安装程序，并给出可读错误文案；不接受「校验失败但继续安装」。
|
||||
- 重复点击下载或安装不产生并发安装；安装开始后客户端不再接受新的更新操作。
|
||||
|
||||
### 权限、归属与数据边界
|
||||
|
||||
- 更新能力通过 Tauri capability 显式授予客户端主窗口，其它窗口（调试窗口等）不得授予。
|
||||
- 客户端只允许访问渠道清单声明的地址，只允许安装清单声明且签名校验通过的对象。
|
||||
- 清单与安装包在 OSS 上保持公开可读；签名私钥与 OSS 凭据只存在于构建环境（Jenkins 凭据、本机发布配置），不写入仓库、日志、构建产物或客户端包。
|
||||
- 客户端不记录更新地址以外的敏感信息；失败文案不回显凭据、绝对路径或响应正文。
|
||||
|
||||
## 契约与迁移
|
||||
|
||||
- 清单格式（Tauri updater v2）：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.1.13",
|
||||
"downloadUrl": "https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/0.1.13/Genarrative-AI-Game-Creator.exe",
|
||||
"sha256": "<64位十六进制摘要>",
|
||||
"size": 123456789,
|
||||
"releaseNotes": "修复与改进"
|
||||
"version": "0.1.48",
|
||||
"notes": "发布说明，可为空",
|
||||
"pub_date": "2026-09-17T00:00:00Z",
|
||||
"platforms": {
|
||||
"windows-x86_64": {
|
||||
"signature": "<.sig 文件内容>",
|
||||
"url": "https://<oss>/agc/dev-win/0.1.48/<安装包文件名>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`downloadUrl` 必须是 HTTPS；如提供 `sha256` / `size`，Tauri 下载时会校验摘要和字节数。点击“下载更新”后，客户端将安装包流式写入系统临时目录并显示进度，校验成功后通过 Windows UAC 提权启动 NSIS 静默安装并退出旧客户端。
|
||||
- 渠道与平台映射：
|
||||
|
||||
## 启动与失败策略
|
||||
| 渠道 | 构建目标 | 清单平台键 | 更新包 | 清单地址 |
|
||||
| --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
|
||||
| `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` |
|
||||
|
||||
- 检查挂在 `WindowChrome` 根组件，覆盖首页、工作台和调试窗口；网络错误、格式错误或版本不高于当前版本均静默忽略，不阻塞客户端启动。
|
||||
- 更新请求使用单例 Promise，React StrictMode 或同一窗口重复挂载不会重复请求。
|
||||
- Tauri HTTP capability 与 CSP 仅放行默认 OSS 域名；若更换域名，需同步更新 `capabilities/main.json`、`tauri.conf.json` 和发布环境配置。
|
||||
- 对象布局：清单固定写成 `agc/<channel>/latest.json`；安装包与签名写成 `agc/<channel>/<version>/<file>` 与 `<file>.sig`。
|
||||
- macOS 使用 universal 包：`dev-mac` 按 universal 目标构建（Intel 与 Apple Silicon 共用一个包），清单把同一个 `.app.tar.gz` 与同一个签名分别写入 `darwin-aarch64` 与 `darwin-x86_64`，升级后仍是 universal 包。这是 Tauri 官方发布工具对 universal 产物的既有写法。
|
||||
- 上一条的两个键不能合成单一 `darwin-universal` 键：更新插件按运行时实际架构解析清单键（Apple Silicon 命中 `darwin-aarch64`，Intel 命中 `darwin-x86_64`），不存在自动命中 `darwin-universal` 的情形。将来真要单独发该键，必须在客户端同时设置自定义 target，否则清单里这一项永远不会被读取。
|
||||
- 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
|
||||
- 版本递增按渠道独立进行：发布脚本读取该渠道远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；两个渠道的版本号互不影响。
|
||||
- 版本高水位：发布脚本取「渠道清单版本」与「旧协议迁移指针版本」（迁移窗口内）中的较大值再递增。只看渠道清单会在渠道启用初期把版本链改小 —— 2026-09-17 首次渠道发布即把旧指针的 0.1.57 退回 0.1.48，随后以显式 0.1.60 纠偏；迁移窗口结束（旧指针 404）后自动只剩渠道清单，`dev-mac` 不参与旧指针比较。
|
||||
- 迁移（旧协议 → 渠道清单）：
|
||||
- 迁移起点：已发布客户端（含当前线上版本）内置自研清单地址 `agc/latest.json`（sha256 格式），下载与安装由自研 Rust 命令完成。
|
||||
- 迁移策略见「未决问题与决策」。迁移完成后，自研清单解析、下载命令、下载进度事件以及为此放行的 CSP / HTTP 白名单条目按「四不写」整条删除，不留兼容分支与墓碑说明。
|
||||
|
||||
## 发布约定
|
||||
## 构建与发布
|
||||
|
||||
当前发布目标固定为 Windows x64 NSIS。执行 `npm run ai-game-creator-shell:build` 会先读取
|
||||
`VITE_AGC_UPDATE_MANIFEST_URL`（默认 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/latest.json`）的
|
||||
`latest.json`，取本地与 OSS 的较高版本并递增一个 patch，然后同步更新 package、Tauri 和 Cargo
|
||||
版本后再向 Tauri 传入 `--target x86_64-pc-windows-msvc` 构建。OSS 清单首次不存在时按本地版本递增；
|
||||
OSS 请求失败、清单格式错误或版本无效会终止发布，避免覆盖线上版本。构建完成后自动扫描 `.exe`
|
||||
安装包，并在 `apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/latest.json`
|
||||
生成包含版本、下载地址、大小和 SHA-256 的清单。可通过 `AGC_BUILD_TARGET` 显式覆盖目标（发布仍应使用
|
||||
Windows x64），通过 `AGC_UPDATE_ARTIFACT` 指定要发布的安装包，通过 `AGC_UPDATE_OSS_BASE_URL` 指定
|
||||
OSS 前缀，通过 `AGC_RELEASE_VERSION` 指定三段版本号（仅在明确需要复现指定版本时使用），通过
|
||||
`AGC_UPDATE_RELEASE_NOTES` 写入发布说明，支持多行文本且保留内部换行；`--no-bundle` smoke 构建不会读取 OSS、修改版本或生成清单。
|
||||
- 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
|
||||
- 渠道由构建参数显式指定，并按目标平台校验：Windows 目标只允许 `dev-win`，macOS 目标只允许 `dev-mac`；未显式指定时按目标平台取默认渠道。
|
||||
- 定时调度只在本轮到达的提交包含 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 指向已存在的对象。
|
||||
- Jenkins 流水线需要新增渠道参数与签名凭据；签名私钥与密码只以受保护凭据注入当前进程，不写入 workspace、日志或归档产物。
|
||||
- 归档证据：安装包、`.sig`、渠道清单与源码 commit。
|
||||
|
||||
每次发布安装包上传完成后，再使用 ossutil 的 `--force` 覆盖上传同一目录生成的 `latest.json`，确保固定的 latest 指针和 `downloadUrl` 指向已存在的 OSS 对象；未显式强制覆盖时，ossutil 在目标已存在时会交互询问并按默认值跳过，不能作为 Jenkins 非交互发布方式。清单和安装包均使用公开可读对象，不在清单中保存凭据、签名或本地路径。构建脚本本身不负责上传 OSS，发布流水线通过 `release:upload` 完成上传。
|
||||
## 验收标准与证据
|
||||
|
||||
如需一键构建并上传，可执行 `npm run ai-game-creator-shell:release:upload`。该命令要求本机已安装并配置 `ossutil`，
|
||||
先按上述规则比较 OSS 版本、递增 patch、构建 Windows x64 NSIS，再上传安装包和 `latest.json`。默认上传到
|
||||
`agc-dev` / `oss-rg-china-mainland.aliyuncs.com`，也可用 `AGC_OSS_BUCKET`、`AGC_OSS_ENDPOINT` 和 `OSSUTIL_BIN`
|
||||
覆盖；本机执行时凭据由 ossutil 本机配置读取，不能写入仓库或命令行参数。
|
||||
已获得的证据：
|
||||
|
||||
## Jenkins Windows 构建节点
|
||||
| 条款 | 验收方式 | 证据 |
|
||||
| ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 渠道与端点映射、渠道校验 | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过（默认渠道、错配失败关闭、未知渠道失败关闭） |
|
||||
| universal 包挂两个平台键 | 同上 + 本地发布烟测（伪造 bundle） | 通过（两键同 URL 同签名，不生成迁移清单） |
|
||||
| 缺签名时失败关闭 | 同上 | 通过 |
|
||||
| 开发态不检查更新 | `vitest run apps/ai-game-creator-shell/tests/appUpdate.test.ts` | 通过（开关关闭时不请求清单） |
|
||||
| 旧自研链路整条删除 | 代码检索无残留命令、事件与白名单条目 | 通过（`download_agc_update` / 下载事件 / 清单常量均无残留） |
|
||||
| 清单与对象布局符合渠道约定 | `Genarrative-Agc-Windows-Build` #68（2026-09-17，SUCCESS） | 通过：`agc/dev-win/latest.json` = 0.1.48 + `windows-x86_64`；`agc/dev-win/0.1.48/陶泥儿_0.1.48_x64-setup.exe` 与同名 `.sig` 公网可读 |
|
||||
| 清单签名与签名对象一致 | 取回 `.sig` 对象与渠道清单 `signature` 比对 | 通过（逐字相同，420 字节） |
|
||||
| 安装包与清单登记一致 | 下载安装包实算 SHA-256 与尺寸后与迁移桥清单比对 | 通过（size `104678031`、sha256 `1f67…4fd0` 一致） |
|
||||
| 旧协议迁移桥 | 公网读取 `agc/latest.json` | 通过（0.1.48，`downloadUrl` 指向同一对象，含 `sha256` / `size`） |
|
||||
| 真实更新闭环（含升级后重启） | 0.1.47 客户端按提示下载安装并重启 | 通过（2026-09-17 用户实测：提示 → 下载 → 安装 → 关于页显示新版本，再次检查为已是最新） |
|
||||
| 更新摘要端到端展示 | 公网读取渠道清单 `notes` 与客户端更新提示 | 通过（2026-09-17 用户实测：0.1.62 清单带 8 条自动摘要，客户端提示正常显示多行内容） |
|
||||
|
||||
AGC 发布流水线使用 `jenkins/Jenkinsfile.ai-game-creator-shell-build`，当前节点标签为
|
||||
`windows && win2022`。节点应为 Windows Server 2022 x64 虚拟机，预装 Node.js 22、npm
|
||||
10.9.7、Rust 1.96.0、Visual Studio Build Tools（MSVC 与 Windows SDK）、Git 和 ossutil；
|
||||
Jenkins Agent 服务必须能在同一用户环境中找到这些命令。Tauri Windows bundler 使用
|
||||
`tauri.windows.conf.json` 中的 `bundle.useLocalToolsDir: true`，把固定版本的 NSIS 工具缓存到
|
||||
`src-tauri/target/.tauri/NSIS`，不依赖 Jenkins 服务账户的 `%LOCALAPPDATA%\tauri` 或 PATH 中的系统 NSIS。
|
||||
Jenkins Checkout 的 `git clean -fdx` 会清理该构建目录，因此每次全新工作区可能重新下载 NSIS；这只影响构建耗时，不改变工具来源或执行权限要求。
|
||||
流水线参数 `AGC_UPDATE_RELEASE_NOTES` 使用 Jenkins `text` 类型，可直接输入多行发布说明；执行根 workspace 的 `npm ci`，然后调用
|
||||
`npm run ai-game-creator-shell:release:upload`，并归档 Windows 安装包、`latest.json` 与源码 commit。
|
||||
流水线会将未导出的空参数按空字符串处理：`COMMIT_HASH` 留空时沿用 Jenkins SCM 当前提交，`OSSUTIL_BIN` 留空时使用节点 PATH 中的 `ossutil`，不会因 PowerShell 对空环境变量调用 `.Trim()` 而提前失败。
|
||||
待执行证据（首次渠道发布后回填）：
|
||||
|
||||
Jenkins Job 在“Build and upload”阶段通过受保护凭据 ID `AliyunAccessKeyId` 和
|
||||
`AliyunaccessKeySecret` 注入 AccessKey，仅在当前进程运行时传给 ossutil，不写入仓库、workspace 或构建日志；
|
||||
本机运行仍使用 ossutil 配置。凭据必须具备 `PutObject` 权限；OSS 对客户端保持公共读即可，公共读本身不授予
|
||||
Jenkins 上传权限。由于版本号取决于 OSS 当前清单，Job 已关闭并发构建；若 Jenkins
|
||||
上存在多个 AGC 发布 Job，还应使用同一个 Lockable Resource 串行化发布。Job 参数
|
||||
`AGC_RELEASE_VERSION` 留空时自动递增，填写后会使用指定版本并更新对应的 `latest.json`，因此回滚或测试旧版本前应确认不会覆盖线上更新入口。
|
||||
| 条款 | 验收方式 | 证据 |
|
||||
| -------------------- | --------------------------------------------------- | ------ |
|
||||
| 签名校验失败拒绝安装 | 篡改渠道清单 `signature` 后观察客户端拒绝安装的表现 | 待执行 |
|
||||
| 签名校验失败拒绝安装 | 篡改渠道清单 `signature` 后观察客户端拒绝安装的表现 | 待执行 |
|
||||
|
||||
## 未决问题与决策
|
||||
|
||||
已决策：
|
||||
|
||||
- macOS 采用 universal 包，同一产物同时挂 `darwin-aarch64` 与 `darwin-x86_64` 两个清单键（见「契约与迁移」）。
|
||||
- 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `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 发布方式：`dev-mac` 产物在本机 mac 上执行发布入口上传，Jenkins 暂不新增 macOS 节点；macOS 代码签名与公证凭据未确认前，相关闭环记为未验证项，不静默通过。
|
||||
|
||||
待办：
|
||||
|
||||
- macOS `dev-mac` 渠道落地（macOS 构建机、签名与公证、安装后重启验证、是否接入 Jenkins macOS 节点）暂缓，由后续独立变更单独完成；在此之前 `dev-mac` 渠道只有构建与清单能力，不发布。
|
||||
|
||||
@@ -61,10 +61,25 @@ OpenAPI 与客户端工具的对外说明只描述模式用途、参数约束和
|
||||
}
|
||||
```
|
||||
|
||||
客户端保留旧参数调用；新字段不填时不改变旧调用语义。客户端不读取图片、不自动选色、不把 `auto` 改写为具体颜色，使用原有 Bearer 认证、幂等键和队列返回模型。
|
||||
客户端保留旧参数调用；新字段不填时不改变模式语义。客户端不自动选色、不把 `auto` 改写为具体颜色；源资源校验、认证、异步任务查询、结果下载和本地登记由客户端负责。
|
||||
|
||||
工具 schema、桥接参数校验和随包 `agc-client-projection` Skill/契约说明必须保持一致。模式与颜色属于请求意图，必须参与客户端幂等指纹；同一图片与名称的不同模式不能复用同一次请求。缺省 complex 且没有颜色时保留既有指纹。主站在默认值归一化之前计算 External 请求指纹，缺失的新字段不序列化，避免旧请求重放发生冲突。
|
||||
|
||||
客户端提交前建立的本地项目绑定会返回主站远端 `projectId` 与 `assetFolderId`，抠图请求必须使用这两个远端身份；本地 manifest `projectId` 仅用于绑定和本地状态，不能直接提交给主站。
|
||||
|
||||
### 本地结果与恢复合同
|
||||
|
||||
`agc_remove_background` 复用本地资源编辑账本，类型为 `background-removal`。源图片保持不变，抠图结果作为新资源写入项目。模式和背景色随账本持久化并参与请求指纹，其它编辑类型的历史指纹保持不变。
|
||||
|
||||
1. 客户端建立源图片的正式资源绑定，在提交前保存 operation、幂等键和请求意图。普通登录态提交 `/api/editor/images/background-removals`，从 `data.queueState.operationId` 读取受理身份；开发者模式提交 External v1 对应路由，从 `data.operationId` 读取身份。
|
||||
2. 受理后持续查询账号路由 `/api/runtime/external-generation/jobs/{operationId}` 或 External v1 对应状态路由。`queued`、`running` 只描述远端返回状态；固定进度值、本地文件缺失或 pending 清单为空均不能证明 BgFilter 排队。
|
||||
3. 远端 completed 后按稳定资源身份换取有效下载 URL，校验结果为带 alpha 通道的有效 PNG，随后复用 staging、manifest 和 revision 提交。只在本地登记完成后向 Agent 返回 `completed`、`operationId`、`resource.localAssetId`、相对路径和安全告警，不暴露临时 URL 或凭据。
|
||||
4. 轮询中断、超时或下载失败保留已受理 operation；`agc_list_registered_assets.pendingOperations` 与客户端恢复面板可见。相同源资源、结果名称、模式和颜色的后续调用优先恢复同一任务，不再次提交。不同账号不能恢复原账号任务；切回原账号后按既有恢复规则续接。
|
||||
5. 远端 failed 明确失败；提交响应不确定且无法确认 operation 时进入人工对账状态，不自动换键重发。失败/未知均不得伪造透明图或自动切换本地抠图方式。
|
||||
6. 升级前仅返回 queued、没有本地账本的任务不自动迁移；已有远端结果须通过正式资源查询和导入恢复，不据旧回执重新发起付费请求。
|
||||
|
||||
本修复只扩展 AGC 客户端现有工作流，不修改主站队列、BgFilter 或 SpacetimeDB schema。验收覆盖账号与开发者两种响应封装、queued/running/completed、已受理中断恢复不重复 POST、远端失败不登记结果，以及既有资源编辑回归。
|
||||
|
||||
## 实施任务
|
||||
|
||||
### 任务一：冻结 BgFilter 契约
|
||||
@@ -93,6 +108,13 @@ OpenAPI 与客户端工具的对外说明只描述模式用途、参数约束和
|
||||
|
||||
## 验收证据
|
||||
|
||||
2026-09-17 客户端闭环验证：
|
||||
|
||||
- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell project::resource_editor:: -- --test-threads=1` 通过。新增 HTTP fixture 覆盖开发者 queued/running/completed、账号 HTTP 200 queueState 与 `data.job`、换签下载、PNG alpha 校验、原图保留和新资源提交。
|
||||
- 已受理任务的首次轮询失败后，pending 保留模式与颜色；恢复只查询原 operation，整个流程只 POST 一次，成功后清除 pending。远端 failed 不新增结果资源。既有账号隔离、提交原子性和崩溃恢复用例通过。
|
||||
- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell agent::direct_tool_bridge::tests -- --test-threads=1`、AGC 类型检查、技能包校验、Rust 格式、编码、文档索引与 diff 检查通过。
|
||||
- 本轮未运行真实登录客户端 → 本地主站 → BgFilter 的端到端 smoke；当前本地后端已停止，自动化证据使用模拟 HTTP 服务。此前 BgFilter 成功日志只证明上游处理完成，不证明主站结果持久化或客户端导入成功。
|
||||
|
||||
2026-09-16 实测：
|
||||
|
||||
- 主站 `cargo test -p api-server background_removal`：36 项通过，覆盖非法请求入队前拒绝、缺省 complex、队列参数保留、旧请求指纹、父侧内部 RPC 和 provider multipart。
|
||||
|
||||
@@ -0,0 +1,136 @@
|
||||
# 【技术方案】AGC 模板库与模板建项
|
||||
|
||||
## 交付范围
|
||||
|
||||
AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，正文是 zip），并让用户能浏览、搜索、筛选、下载模板，直接由模板创建项目。模板更新不再依赖客户端发版。
|
||||
|
||||
- OSS 侧：bucket `agc-dev`（endpoint `oss-rg-china-mainland.aliyuncs.com`）下的 `templates/` 前缀，公共读。
|
||||
- 客户端侧：Rust `template_library` 模块（读清单、下载、安装、建项目）+ 模板库全屏页 + 首页模板推荐 + 左侧导航入口。
|
||||
- 不在本次范围：模板制作工具、模板审核、模板计费、增量更新、已建项目的模板回填。
|
||||
|
||||
## OSS 契约
|
||||
|
||||
```text
|
||||
templates/
|
||||
index.json # 模板库清单，客户端唯一读取入口
|
||||
v1/<templateId>/
|
||||
template.json # 单模板元数据（含文件级摘要）
|
||||
template.zip # 模板正文，zip 根 == AGC 项目根（如 game/index.html）
|
||||
cover.(png|jpg|webp|svg) # 封面图（卡片展示，客户端 <img> 直接取）
|
||||
```
|
||||
|
||||
`index.json`（schema `agc-template-library.v1`）：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `schemaVersion` | 固定 `agc-template-library.v1`；破坏性变更换 schema，不原地改语义 |
|
||||
| `library` / `libraryVersion` / `updatedAt` | 库标识、库格式版本、本次更新时间 |
|
||||
| `templates[].id` | 稳定标识，`[a-z0-9][a-z0-9._-]{0,63}`，同时是目录名 |
|
||||
| `templates[].title/summary/tags[]` | 展示与搜索/筛选用文案；`tags` 参与标签筛选与关键词命中 |
|
||||
| `templates[].runtime` | `html` / `unity` / `godot` / `cocos` |
|
||||
| `templates[].engine` / `engineVersion` | 引擎标识与版本（如 `phaser` 4.2.1、`three.js` 0.180.0） |
|
||||
| `templates[].templateVersion` / `updatedAt` | 模板内容版本；客户端按它判断是否需要重新下载 |
|
||||
| `templates[].entry` | 解压后的项目入口相对路径，如 `game/index.html` |
|
||||
| `templates[].zipKey` / `zipSizeBytes` / `zipSha256` | 模板包对象键、字节数、SHA-256（下载后强校验） |
|
||||
| `templates[].coverKey` / `coverWidth` / `coverHeight` / `coverSha256` | 封面对象键与尺寸/摘要 |
|
||||
| `templates[].metadataKey` | 单模板元数据对象键（`template.json`） |
|
||||
|
||||
约束：
|
||||
|
||||
- 所有对象键必须落在 `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] [--prune]`，脚本生成 `template.json` 与 `index.json`、上传后回读 zip 摘要；`--prune` 清理该模板前缀下本次没有产出的旧对象（例如换封面扩展名后的残留）。
|
||||
- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程）。
|
||||
- 客户端可用 `AGC_TEMPLATE_LIBRARY_BASE_URL` 覆盖库地址；只接受 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`（拒绝其他主机、路径、http）。
|
||||
|
||||
## 客户端实现
|
||||
|
||||
### Rust：`apps/ai-game-creator-shell/src-tauri/src/template_library.rs`
|
||||
|
||||
| 命令 | 行为 |
|
||||
| --- | --- |
|
||||
| `fetch_game_template_library` | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache` |
|
||||
| `download_game_template` | 取清单里对应条目，流式下载 zip（≤512 MiB），校验字节数与 SHA-256，解压到 `<app_data>/templates/installed/<id>/<version>/`，最后写 `installed.json` 作为安装完成的唯一标记 |
|
||||
| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在 `<app_data>/projects/` 下按既有自动工作区规则建目录：先复制模板文件，再走 `init_local_game_project_at` 补 `.agent` 清单与标准目录 |
|
||||
|
||||
安全与健壮性：
|
||||
|
||||
- 解压只接受普通文件与目录：拒绝绝对路径、`..`、盘符、反斜杠、符号链接，并有文件数（4096）与单文件大小（256 MiB）上限。
|
||||
- 安装目录名由标识符白名单拼出，不拼接远端字符串；重装时只清理该模板自己的安装目录。
|
||||
- 模板文件与安装记录统一走 `write_game_creator_private_file` / `ensure_game_creator_private_directory_tree`，保持项目目录的私有 DACL 口径。
|
||||
- 建项目失败时删除刚创建的项目目录，不留半成品。
|
||||
|
||||
### 前端
|
||||
|
||||
- `src/features/template-library/templateLibraryModel.ts`：清单类型、搜索（空白分隔多关键词「与」）、标签/运行时/已下载筛选、标签选项聚合、体积格式化等纯函数。
|
||||
- `src/features/template-library/useTemplateLibrary.ts`：一次拉清单，暴露筛选状态、下载与「用模板建项目」；下载成功后只就地更新该条目的已下载状态。
|
||||
- `src/view/template-library/index.tsx`：模板库全屏页（返回、刷新、搜索、运行时/标签筛选、仅看已下载、卡片显示封面与已下载徽标、下载/使用模板）。
|
||||
- 卡片动作按安装状态收口：已下载且版本一致时**不再显示下载入口**，只留「使用模板」；版本落后才显示「更新」；缺包显示「下载」。
|
||||
- 过程提示（下载完成、开始建项目）走浮层 toast（复用 `packages/shared` 的 `PlatformRuntimeStatusToast`，`document.body` 浮层 + 2.6 秒自动消失），不再占用页面内位置；页面内只保留可操作的错误与空态。
|
||||
- 首页「灵感推荐」替换为「模板库」推荐位（`src/view/home/TemplateRecommendations.tsx`）：只展示封面、标题、运行时与已下载徽标，点击进入模板库页面；首页不再直接触发建项目。
|
||||
- 左侧导航新增模板库入口（`LauncherView = 'template-library'`）。
|
||||
- `src-tauri/tauri.conf.json` 的 `csp` / `devCsp` 在 `img-src` 放行 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`，用于封面图；`connect-src` 原本已放行同一域名。
|
||||
- 旧的本机灵感图目录 `src/view/home/assets/inspiration/` 与 `InspirationGallery.tsx` 一并删除，不再保留退役实现。
|
||||
|
||||
## 验收与验证
|
||||
|
||||
## 本地压测假数据注入（feature 控制）
|
||||
|
||||
模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。
|
||||
|
||||
- 开关：Cargo feature `template-library-fixtures`（**默认关闭**）。关闭时 `apply_template_library_fixtures` 是恒等透传，正式产物里不存在注入分支，并有单测保证这一点。
|
||||
- 条数：环境变量 `AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT`（默认 1000；`0` 表示不注入；上限 20000）。
|
||||
- 假数据特征：真实条目保留在最前，其余按真实条目循环复制；`id`/标题唯一，封面地址追加 `?synthetic=N`（强制逐张请求，模拟“每个模板各自封面”）；标签追加 `批次-00..19`；安装态按 1/3 混合。
|
||||
- 运行方式：
|
||||
|
||||
```bash
|
||||
# 本机 dev 客户端（保留 Windows 默认 feature）
|
||||
AGC_DEV_CARGO_FEATURES=cocos-editor-execute,template-library-fixtures npm run dev
|
||||
# 直接跑二进制
|
||||
cargo run --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features template-library-fixtures
|
||||
# 覆盖条数
|
||||
AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT=300 AGC_DEV_CARGO_FEATURES=template-library-fixtures npm run dev
|
||||
```
|
||||
|
||||
两种编译模式都要过模板库单测：默认构建跑「恒等透传」用例，`--features template-library-fixtures` 跑「补齐到配置条数」用例。
|
||||
|
||||
### 1000 条实测结论
|
||||
|
||||
### 卡片列表虚拟滚动（react-window）
|
||||
|
||||
- 列表改用 workspace 里已有的 `react-window@1.8.11` 的 `FixedSizeGrid`（`react-arborist` 已在用同一版本，不引入新包；类型来自 devDependency `@types/react-window`）。
|
||||
- 布局契约收在纯函数 `templateLibraryGrid.ts`（单测覆盖）：列数 = `floor((容器宽 + gap) / (最小卡宽 + gap))`、列宽 = 容器宽 / 列数、行高 = `卡片宽 × 9/16 + 文字区 150 + gap`；`buildTemplateRows` 按行切分并在行尾补 `null` 占位。
|
||||
- 卡片抽成 `TemplateCard`（`memo`），网格只渲染可视行 + 2 行 overscan；筛选条件（关键词/标签/运行时/仅看已下载）变化时把滚动位置复位到顶部，避免"从筛选切回全量后停在空白处"。
|
||||
- **页面高度契约**：页面根节点的高度按**父级 `.launcher-main` 的实测高度**内联设置，既不用百分比也不用 `100vh`。原因：外壳样式 `.launcher-main > .platform-theme { height: 100% }` 特异性高于 Tailwind 工具类，而这条百分比在 `.launcher-shell { min-height: 100vh }` 链路上是不定高，页面会退化成内容高度（虚拟网格视口高度 0、卡片区整片空白）；`100vh` 又比真实舞台高一个标题栏高度（窗口 100vh=800 / 舞台 750），底部会被裁掉。
|
||||
- 筛选区（运行时/标签）改成可独立滚动的区块（`max-h-[24vh]`），标签数量随库量增长时不再把卡片区挤出窗口。
|
||||
- 回归：`templateLibraryGrid.test.ts` 覆盖列数/行高/行数/切行；页面测试用固定视口断言「1000 条只渲染 ≤ 40 张卡片，滚动高度仍按 250 行计算」。
|
||||
|
||||
- 页面能正常渲染 1000 张卡片（头部显示「共 1000 个模板 · 已下载 335 个」），并且滚动容器生效（窗口高度压到 430px 时右侧出现滚动条，页面内容被裁切而不是溢出到窗口外）。
|
||||
- 需要后续收口的两点（本次未改）：① 标签筛选条随库量膨胀——1000 条时聚合出 35 个标签、占三行；② 一次性渲染 1000 个卡片节点并触发 1000 次封面请求。建议标签只展示 Top N + 「更多」，卡片列表加分页或虚拟滚动。
|
||||
- 前端回归：1000 条渲染 + 已安装过滤（334）/标签过滤（50）/关键词过滤数量自洽，见 `apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
|
||||
|
||||
```bash
|
||||
# 模板库单测（清单校验、键安全、解压路径逃逸、安装与建项目）
|
||||
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
|
||||
# 前端模型与页面单测（AGC 测试统一在 apps/ai-game-creator-shell/tests/）
|
||||
npx vitest run apps/ai-game-creator-shell/tests/templateLibraryModel.test.ts apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx
|
||||
# 类型检查 / 编码 / 空白
|
||||
cd apps/ai-game-creator-shell && npm run typecheck
|
||||
npm run check:encoding
|
||||
git diff --check
|
||||
# OSS 侧匿名可读
|
||||
curl -s https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json
|
||||
```
|
||||
|
||||
手工验收：打开模板库 → 搜索与筛选 → 下载（出现「已下载」徽标）→ 「使用模板」→ 进入项目工作台且项目里已有模板文件。
|
||||
|
||||
运行态核验（客户端真的拉过清单时）：本机缓存 `<app_data>/templates/index.json` 与线上 `templates/index.json` 逐字节一致；`<app_data>/templates/installed/<id>/<version>/installed.json` 出现即表示该模板已下载完成。
|
||||
|
||||
## 失败与回退
|
||||
|
||||
- 清单读不到且没有本机缓存：模板库页显示错误与重试，首页推荐位显示「模板库暂时没有可用的模板」。
|
||||
- 版本落后：`installedVersion != templateVersion` 视为需要重新下载，点「使用模板」会先重下再建项目。
|
||||
- 需要回退整条链路时，删除 `templates/` 前缀即可让客户端回到"空模板库"；客户端代码路径不受影响。
|
||||
@@ -34,8 +34,18 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
|
||||
|
||||
`patch_file` 的所有 edits 均匹配同一份原文件，参数顺序不影响结果。完成唯一匹配与不重叠校验后，按原文起点升序拼接未修改片段与替换文本，最后一次性写入；任一校验失败时不写文件。回归用例覆盖乱序 edits、中文内容与替换长度增减，并核对完整落盘内容。此行为仅属于策划 Agent 文件工具。
|
||||
|
||||
## 策划 Agent 运行 panic 边界
|
||||
|
||||
`finish_design_command` 的运行段包在 `catch_unwind` 边界内：任何运行期 panic 被转成一次普通失败，由既有错误分支从最后一个持久检查点恢复，向会话写入固定公开文案"策划运行发生内部错误，本轮已中断，可直接重试；若反复出现请反馈。"，并以 `running=false、可重试、lastError 有值` 的视图正常返回。panic 负载只写入私有 design_debug，不进入用户可见消息；continue、recover_uncertain 与 decide 三个入口共享同一边界。边界不改变工具错误、Provider 瞬态重试和批次不确定恢复的既有语义。
|
||||
|
||||
运行段通过 task-local 携带项目根；首次运行时安装的 panic hook 在 panic 瞬间把代码位置（file:line:column）和负载追加写入私有 design_debug，随后交给原 hook 维持既有 stderr 输出。hook 只在策划运行段内生效（其它任务无 task-local 上下文时直接透传），多线程 runtime 下 future 跨 worker 迁移也能正确归因。
|
||||
|
||||
## 资源画布交互与工作台状态同步
|
||||
|
||||
- 未完成抠图的恢复项在现有类型行显示账本中的复杂/平面背景模式；平面模式显示已记录的自动背景色或颜色值，缺失模式/颜色不补默认值，恢复仍按原 operation 身份执行。
|
||||
- 活动回合初始空快照、首次成功读取的空结果及禁用后的空态保持同一数组引用；快照签名初值与空态重置值均为 `[]`。无原生 invoke 的窗口测试只期待首次状态发布，异步空结果测试显式控制请求完成，不以初始空数组作为请求已完成的证据。
|
||||
|
||||
- 活动回合轮询的初始空快照与后续空结果保持同一引用；停用或切换读取器使旧请求失效，晚到快照不得恢复已停用的活动回合或覆盖新轮询结果。无原生读取器时窗口只发布一次空状态，不通过额外空数组触发重复发布。
|
||||
- 工作台向窗口标题栏发布正在运行的项目时，输入未变化不得形成重复发布与清理的渲染循环；打开项目动作始终使用当前工作台处理逻辑，退出工作台后清除其标题栏状态。
|
||||
- 资源子画布（含「所有资源」）保留空白处左键框选、资源卡左键选中/拖动、触摸板双指平移及捏合缩放；右键按住空白处或资源卡拖动时平移画布，不改变资源选择与布局。中键和空格抓手继续可用。总览保留既有左键平移，并支持右键平移。
|
||||
- 画布接管的右键手势不弹出原生菜单；输入框、媒体操作、工具条和独立浮层不被画布抢占。指针取消、捕获丢失或窗口失焦后终止平移，不能继续跟随指针。
|
||||
@@ -45,6 +55,8 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
|
||||
|
||||
## 资源卡选中工具栏与导出
|
||||
|
||||
- AGC 选中工具栏按既有动作顺序最多直接显示前 5 项（不计分隔线），剩余动作进入「更多」。悬停、点击及键盘均可展开独立纵向浮层，优先向上展开，窗口顶边空间不足时向下避让；浮层限制在窗口内，超高时自行滚动，不带动画布。动作执行、点击外部、Escape 或换选资源后关闭；禁用状态和原处理链路保持不变。Web 美术画布默认不折叠。
|
||||
- 「素材类型」与「信息」不占工具栏名额，改为资源卡右上角的类型标签和信息圆钮，与 Web 美术画布共用卡片控件。未选中卡片可直接打开信息；类型入口仅对 manifest 资产可用。控件不触发卡片拖拽或多选，信息面板仍复用运行页签的字段。
|
||||
- 共享选中工具栏按实际显示的快速编辑、编辑动作、改造、导出与宿主动作组生成分隔线；空组不产生分隔线，不依赖宿主 CSS 隐藏重复线。
|
||||
- AGC 所有具有本地文件路径的素材都显示带文字的「导出」按钮，位于工具栏末组的「删除素材」之前，两者之间不插入分隔线；「重命名」继续保留在前面的常规动作组。工具栏宽度上限为 `min(92vw, 800px)`，窄屏仍可横向滚动。图片、视频、音频、动画、UI、文档及其它文件共用 `isResourceCanvasExportable`，不按媒体类型限制导出；无文件路径及虚拟项目版本不提供文件导出入口。
|
||||
- 导出继续复用 `saveProjectResourcesToDisk`：原生保存对话框选择路径，`save_local_project_asset_file` 复制原始文件字节，不转图片、不重编码、不另建 IPC。后端继续校验源文件、敏感路径和目标路径；取消不写文件，失败通过工作台提示。
|
||||
@@ -176,7 +188,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
|
||||
|
||||
- 素材读取区分三类来源：`asset.list` / `agc_list_registered_assets` 是当前项目本地 manifest，`agc_list_project_files` / `file.list` 只发现项目目录中实际存在但可能未登记的文件，`asset.library.list` 是当前登录账号素材库，项目画布资源读取是当前网页项目/画布的完整图片清单；账户素材库不能替代项目画布清单。
|
||||
- Agent 只接收稳定素材 ID、类型、尺寸和项目相对路径等安全投影。客户端负责重新校验账号/项目归属、换签下载、媒体校验，以及 manifest/画布原子登记；不得向 Agent 暴露绝对路径、签名 URL、objectKey、token 或 Cookie。
|
||||
- `canvas.asset_import` 支持账户/画布资源 ID 和项目内本地相对路径。项目文件发现结果以 `assetImportable` 明确区分当前可登记的已识别图片、字体、音频、视频、文档和代码文件与其它文件；Agent 只能提交前者。导入拒绝路径穿越、`.agent`、符号链接/reparse point 及敏感配置文件；外部宿主文件须由 UI 原生文件选择器授权后导入，不开放任意绝对路径。
|
||||
- `canvas.asset_import` 支持账户/画布资源 ID 和项目内本地相对路径。项目文件发现结果以 `assetImportable` 明确区分当前可登记的已识别图片、字体、音频、视频、文档、代码与**引擎资源**（Cocos Creator 的模型、动画、场景/预制体、材质/特效、图集与压缩纹理容器）与其它文件；Agent 只能提交前者。引擎资源在资源画布上是**只读预览**：模型出缩略图、序列化资源出结构摘要、客户端解不了的容器出类型卡，不承接编辑与派生；`.meta`、`library/`、`temp/` 等引擎生成物仍然只可发现、不可登记。导入拒绝路径穿越、`.agent`、符号链接/reparse point 及敏感配置文件；外部宿主文件须由 UI 原生文件选择器授权后导入，不开放任意绝对路径。
|
||||
- Runtime `asset.list` 与 `file.list` 的详情使用文件上下文上限，而不是普通工具短摘要上限，确保有界候选/目录清单不会因前部内容较长而整体丢失；`asset.list` 超出 48 项或 `file.list` 超出 40 项时仍显式返回剩余数量，Agent 再按候选父目录（例如 `assets`、`game/assets`）缩小范围查询。
|
||||
- 结果仅返回成功/跳过/失败数量、安全 ID、相对路径、来源、脱敏失败摘要和实际 `revisionAdvanceCount`；幂等跳过不得虚增 revision，部分失败仍须准确记录已发生的 revision 变化。
|
||||
- 普通 Prompt 上下文与错误诊断必须使用分离的脱敏边界：Prompt 继续对疑似凭据行整体隐藏；错误诊断保留 HTTP 状态以及 `code / field / message / reason / detail` 等安全字段，仅替换 Token、Cookie、私钥、配置名、URL 和宿主路径等敏感值。`agc_create_or_derive_resource.assetName` 是必填的人类可读资源显示名称，不接受项目路径、URL、objectKey、Token 或其它凭据。
|
||||
@@ -188,7 +200,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
|
||||
- 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
|
||||
- 资源查询同时投影未完成 operation 的安全状态。媒体工具成功只返回 operation、本地相对路径、资源类型、Canvas/resource/asset/task 身份、正式序列帧以及脱敏后的 `warnings / sliceWarnings`；错误继续使用统一脱敏边界。客户端资源账本持久化 completed 结果的两类告警，committed replay 不能把历史告警伪装成空集合。
|
||||
- 角色动画、视频、音效和背景音乐在构造新的远端请求前统一准备当前项目同名画布与素材目录上下文，并在端点支持时携带 `projectId / assetFolderId / canvasCompletion`。角色动画 placeholder 使用源图片真实宽高，避免非方形角色进入画布时失真；正式 resource/asset 与序列帧继续直接复用 External 返回身份，不从首帧伪造重复资源。已有冻结 request body 或已受理 operation 保持不变，不因本次升级重建请求或重复扣费。
|
||||
- 抠图通过新增 `agc_remove_background` 语义工具开放：模型只提交当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端解析稳定 `resourceId`，准备同名画布/素材目录并生成稳定 operation/idempotency 身份，调用 External v1 `/api/external/v1/editor/images/background-removals` 后只返回有界队列状态。抠图服务仍由客户端和服务端负责源校验、BgFilter、素材登记与画布事务，Codex 不获得内部 worker、凭据或任意 API 调用权。
|
||||
- 抠图通过新增 `agc_remove_background` 语义工具开放：模型只提交当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端解析稳定 `resourceId`，准备同名画布/素材目录并生成稳定 operation/idempotency 身份。普通登录态使用账号鉴权的 `/api/editor/images/background-removals`，ExternalDeveloper 模式使用 External v1 `/api/external/v1/editor/images/background-removals`；客户端接收异步受理后轮询任务状态，下载完成媒体并登记到本地 manifest，未知结果保留同一 operation 供恢复。抠图服务仍由客户端和服务端负责源校验、BgFilter、素材登记与画布事务，Codex 不获得内部 worker、凭据或任意 API 调用权。
|
||||
|
||||
## 2026-08-23 AGC 资源生成补齐（视频 / 动画 / 音效 / 背景音乐）
|
||||
|
||||
@@ -1554,3 +1566,56 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
|
||||
|
||||
- 两个窗口同时对同一项目发起 Runtime 写请求时，用户体验仍由项目级写锁串行决定；本次不引入跨窗口排队提示。
|
||||
- 平台会话在窗口间传播依赖共享 localStorage 与 Runner 权威；渲染层不做跨窗口事件推送，另一个窗口在下一次会话校验或刷新时收敛。
|
||||
|
||||
## 2026-09-17 AGC 项目定时快照上传（agc-dev）
|
||||
|
||||
### 目标与非目标
|
||||
|
||||
- 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；重复内容不重复上传，远端占用跟随当前清单收敛。
|
||||
- 非目标：不做云端下载/恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
|
||||
- 非目标：不把 OSS AccessKey 放进客户端；客户端不直连 OSS。
|
||||
|
||||
### 参与入口、状态与跨模块边界
|
||||
|
||||
- 触发入口有两个：工作区窗口 `main` 存活期间的周期定时器、工作区窗口关闭事件（`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 分离"的既有口径一致。
|
||||
|
||||
### 正常、失败、重试与幂等行为
|
||||
|
||||
- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `sha256`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件。
|
||||
- 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。清单描述的是项目当前全量内容，因此清单体积就是该项目在 OSS 上的常驻占用。
|
||||
- 远端回收：清单写入成功后，服务端读取上一版清单，按 `(路径, 字节数, 摘要)` 反推出不再被当前清单引用的对象键并删除。只处理上一版清单登记过的键，不做 LIST，因此不可能误删其它项目或其它功能的对象；单次最多回收 2000 个对象，剩余部分留到下一次清单写入继续；上一版清单读不到或解析失败时整轮跳过回收（fail-closed）。单个删除失败只记日志，不影响本次同步语义。
|
||||
- 因此本功能是"当前状态镜像 + 清单"，不保留历史版本：同一路径的内容变化会覆盖式替换远端对象，回滚能力不在本轮范围内。
|
||||
- 幂等：同一摘要与字节数的对象重复提交由服务端 HEAD 校验后跳过；探测失败按"未存在"处理并照常 PUT，宁可多传一次也不漏传。索引只在清单写入成功后推进，失败时保留旧索引以便下次重算。
|
||||
- 与项目写锁解耦：同步不持有项目写锁，也不阻塞 Agent 写入。读取摘要后与上传前各按 `(字节数, 修改时间)` 复核一次，任一处不一致就判定该文件"同步期间发生变化"：本轮不上传、不写入索引；若该路径上一轮已同步过则沿用旧记录，避免被误判成删除而触发远端回收。这类文件在下一个周期或下次关窗时重算重试。
|
||||
- 失败关闭：单个文件失败不推进该文件的索引项，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（401/403）与格式类拒绝（400/413）是确定性失败，停止本轮剩余请求并等待用户处理后重试；服务端配额或频率拒绝（429）与传输类失败按可重试处理。
|
||||
- 配额与限流：单文件 64 MiB、单次同步上传预算 512 MiB（超出部分延后到下一次）、单项目常驻上限 2 GiB（客户端在扫描后先判，超限直接给出明确失败；服务端按清单累计体积复核并返回 413）；服务端按用户做进程内小时配额（文件 3000 次、清单 120 次）并对同一项目强制 5 秒最小清单间隔，超限返回 429 且带 `Retry-After`。进程内配额只用于抑制异常客户端与失控重试，跨节点配额由"单项目上限 + 清单引用回收"保证。
|
||||
- 生命周期：同步有界超时（单文件与整次同步分别设上限），项目关闭与应用退出路径不因同步失败而阻塞或延迟退出超过超时上限。
|
||||
- 上传内容边界：复用项目索引与 checkpoint 同一份 `should_skip_project_snapshot_path` 口径——整个 `.agent`（含 runtime、logs、checkpoint、manifest、project.lock）、版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录与 `.pem`/`.key` 等敏感后缀都不参与同步；符号链接与重解析点同样跳过。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
|
||||
|
||||
### 契约与兼容
|
||||
|
||||
- 新增登录态内部路由 `POST /api/agc/project-snapshots/files`，请求 DTO 放在 `shared-contracts`；不属于 `/api/external/v1`，因此不更新 External OpenAPI，与 `/api/error-reports` 同类。
|
||||
- 服务端校验 `projectId` 形态（拒绝路径分隔符、`..`、控制字符与超长值）、相对路径规范（正斜杠、拒绝绝对路径与穿越）、摘要形态（`fnv1a64:` + 16 位十六进制）和字节数上限，任何越界返回 4xx 而不是写入 OSS。
|
||||
- 不改变客户端与 Runner 的本机协议、平台会话语义、项目写锁与 manifest 结构；新增索引文件位于 AppData，不进入用户项目目录。
|
||||
|
||||
### 验收标准与证据来源
|
||||
|
||||
- 定向 Rust 测试：首次同步全量、仅改一个文件时只产生一个修改项、删除文件只体现在清单、`(size,mtime)` 未变时复用旧摘要、排除规则与上限跳过、同步失败不推进索引、同一项目并发触发串行化。
|
||||
- 服务端测试：越界 `projectId`/相对路径/摘要被拒；相同摘要重复提交走跳过分支；超过单项目上限返回 413；超过用户小时配额返回 429；鉴权缺失返回 401；OSS 未配置返回明确的 5xx 而不是写入空对象。
|
||||
- 运行时 smoke：AGC 开发态打开项目、观察索引写入与同步日志、关闭工作区窗口后确认关闭触发的那次同步执行；报告为"客户端 diff 已验证 / 服务端已配置环境联调"两层，不合并成一句"已通"。
|
||||
- 边界：新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。
|
||||
|
||||
### 未决问题
|
||||
|
||||
- 用户侧看不到同步状态与失败原因（界面按产品口径不暴露），排障只能读 AppData 诊断日志或调用 native-only 命令；如果后续要支持用户自助排查，需要先确认是否允许在客户端出现上传相关 UI。
|
||||
- 历史版本：本轮只保留"当前状态镜像 + 清单"，旧内容对象在清单写入成功后即被回收，没有回滚能力；要保留历史版本需要先定"保留几个 revision + 由谁回收"的策略。
|
||||
- 用户级配额：跨节点的用户总量配额与计费口径未定；当前用单项目 2 GiB 上限 + 清单引用回收保证常驻占用有界，用户级总量只能靠项目数间接约束。
|
||||
- 目标 bucket 的生命周期规则（例如转低频/过期删除）需要在部署环境确认后单独收口；功能本身已不再依赖它来控制增长。
|
||||
- 大项目（素材数量多、单文件大）的首轮全量上传耗时与带宽占用未实测；单次预算 512 MiB 会把超出部分留到下一次同步，但并发上限与断点续传仍未引入。
|
||||
|
||||
@@ -20,6 +20,8 @@ Stdb 发布以 root 准备文件、再切换 `spacetimedb` 用户执行时，WAS
|
||||
|
||||
## 本地启动
|
||||
|
||||
AGC Vite 的 `server.watch.ignored` 排除 `**/src-tauri/target/**`，避免递归监听 Rust 构建产物、在 Windows 上创建大量文件监听器并拖慢首次页面加载。保留业务源码、CSS 与仓库共享组件的监听及热更新；不通过关闭 watcher 或 HMR 规避问题。监听回归使用 `node --test apps/ai-game-creator-shell/scripts/vite-watch.test.mjs`，验证构建目录被排除、应用源码及根目录外的共享源码仍能触发变更；原生窗口首绘耗时另行实测，不把监听测试耗时当作启动性能指标。
|
||||
|
||||
AGC `backend` 模式与 `all` / `api-server` 一样，必须同时探测 API 和 BgFilter worker 端口，漂移后的 worker 地址同时传给 API、worker 和 readiness 检查。不能因为旧 worker 的 `/readyz` 可访问，就把新启动失败的同端口 worker 视为就绪；AGC 前端会等待完整配套后端，worker 失败可能最终表现为 Tauri 等待前端 180 秒超时。
|
||||
|
||||
`npm run agc` 外层启动器先执行 `agc:serve` 并等待前端与配套后端就绪，再启动 Tauri，同时清空本次 CLI 的 `beforeDevCommand`，避免重复拉起服务和把数据库发布时间计入 Tauri 的 180 秒前端等待。准备阶段最多等待 660 秒（后端门禁仍为 600 秒），退出时清理本次启动的服务树，不停止复用的服务。AGC 自动发布显式使用 `--preserve-database`，schema 冲突须人工确认迁移，不自动清空数据。
|
||||
@@ -70,7 +72,7 @@ Linux 本机多用户并发开发时，`npm run dev`、`npm run dev:*` 单模块
|
||||
|
||||
后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
|
||||
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；AGC Vite marker 同时提供 `repoRoot + processId + port`，与 `.app/dev-stack.json` 的 `instanceId` 和 API target 交叉核对；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；AGC Vite marker 同时提供 `repoRoot + processId + port`，与 `.app/dev-stack.json` 的 `instanceId` 和 API target 交叉核对；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。开发态客户端不检查更新：启动器给 AGC Vite 注入 `VITE_AGC_ENABLE_APP_UPDATE_CHECK=0`，客户端不请求 OSS 更新清单、也不显示更新入口；需要联调更新流程时显式传 `VITE_AGC_ENABLE_APP_UPDATE_CHECK=1`。
|
||||
|
||||
AGC 开发态还会按后台 Web 的端口约定额外拉起 `apps/admin-web`：Linux 用当前用户端口段的 `start + 3` 槽位，非 Linux 以 `3102` 为兼容首选并允许统一漂移，`ADMIN_WEB_PORT` 可显式指定且必须避开已解析的 AGC Vite 端口；设置 `AGC_DEV_ADMIN_WEB=0` 可关闭。后台 Vite 与 AGC Vite 一样由 `start-dev-stack.mjs` 直接持有并随启动器退出收束，不走 `npm run dev:admin-web`——后者会整体重写 `.app/dev-stack.json`，覆盖本次配套后端的归属状态；后台 Web 的端口解析、启动失败或运行中意外退出都只打印告警，不阻断也不连带停止 AGC 客户端与配套后端。前端与配套后端就绪后，启动器会打印一行 `[ai-game-creator-shell] 启动汇总:`，依次给出前端、后端、后台、数据库与 `bgfilter-worker` 的实际地址；端口漂移或默认端口被其它工作树占用时，以这一行为准。
|
||||
|
||||
@@ -137,7 +139,7 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去
|
||||
|
||||
`Genarrative-Scheduled-Revision-Trigger` 是唯一的定时入口，每小时检查一次（`H * * * *`，分钟由 Jenkins 按 Job 名散列，不等同于整点）。它只用 `git ls-remote` 解析 `SOURCE_BRANCH`（默认 `master`）的远端 HEAD，不 checkout 工作区；解析出的完整 commit 与上一次触发过的 revision 相同则标记 `NOT_BUILT` 并结束，不触发任何下游。
|
||||
|
||||
revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，两条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。两条下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。
|
||||
revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，两条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。两条下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Windows 客户端发布额外按路径过滤：调度管线比较「上一轮已触发的 revision」与本次 revision 之间的变更路径，只有出现 `apps/ai-game-creator-shell/`、`packages/`、`server-rs/crates/`、`plugins/agc-cocos-editor/`、`apps/desktop-shell/src-tauri/icons/`、`package.json` 或 `package-lock.json` 时才触发 `Genarrative-Agc-Windows-Build`，纯文档或流水线自身的提交只触发 Full Build、不推高客户端版本号；判定取消或失败一律按「需要发布」处理，勾选 `FORCE_TRIGGER` 可强制两条都触发。两条下游各自判定：AGC Windows Build 采用「客户端相关路径白名单」，Full Build 采用「与线上站点 / 后端无关的路径黑名单」（`docs/`、`.codex/`、`jenkins/`、`apps/ai-game-creator-shell/`、`apps/mobile-shell/`、`apps/desktop-shell/`、`apps/preview-deployer-web/`、`tools/`、根级 `*.md`），改动只要落在黑名单之外就会照常部署，避免漏发线上站点或后端；两条同时被判为跳过时调度管线只推进 revision 状态、不触发任何发布。客户端渠道清单的更新摘要同样自动生成：发布脚本读取上一份渠道清单的 `commit` 字段，把该提交到本次提交之间触及客户端相关路径的提交标题逐条写进 `notes`（旧协议清单写入 `releaseNotes`，并落盘归档文件 `release-notes.txt`）；`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准，缺少上一份 `commit` 时不写摘要。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。
|
||||
|
||||
调度状态是调度 Job 工作区里的 `.jenkins-last-triggered-revision`，构建描述同时回显本次 revision 与结果。工作区被清理（例如 `Wipe Out Workspace`）或状态文件缺失时，下一次运行按“版本变化”处理并触发一次，之后恢复稳定；需要重建同一版本时勾选 `FORCE_TRIGGER`。Job 按仓库内 `jenkins/scheduled-revision-trigger-job-config.xml` 创建：`scriptPath=jenkins/Jenkinsfile.scheduled-revision-trigger`、Git 入口 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git`、凭据 `genarrative-local-gitea-ssh`、`<triggers/>` 留空（定时器写在 Jenkinsfile 里）。推送后必须让三个 live Job 各自加载一次新 Jenkinsfile，并只读核对 `config.xml`：Full 与 AGC 不再有 cron，定时只来自新调度 Job；只改 Jenkinsfile 而不确认 live 配置时，旧 cron 仍会继续触发。
|
||||
|
||||
@@ -540,6 +542,50 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
|
||||
|
||||
角色动画源帧 PUT、透明帧 PUT 和最终帧 HEAD 使用 `AppState` 内同一个 OSS HTTP Client/连接池，并受进程级 8 路 OSS permit 保护；BgFilter、阿里云抠图和本地处理不占用该 permit。每个 OSS attempt 最多 3 次（首次 + 2 次重试），退避为 250ms、500ms；只重试 timeout、无 HTTP 响应传输错误、OSS PutObject 的 `400 + RequestTimeout`、PUT 400 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 500–599。动作帧 PUT 收到 400 时只读取最多 16 KiB OSS 错误 XML，提取 `Code` 和 `RequestId`；`oss_request_id` 优先使用响应头 `x-oss-request-id`，XML 字段只作回退。错误体读取超时/断流不再按确定性 400 处理：已解析出的 `Code` 优先生效；未解析出 `Code` 时按读取失败原因置 `timeout`/`transport` 并重试，message 追加「错误响应体读取失败」。日志字段包括 `frame_index`、`object_key`、`operation=source_put|final_put|final_head`、`attempt`、`max_attempts`、`retryable`、`will_retry`、`retry_delay_ms`、`permit_wait_ms`、`timeout`、`connect`、`transport`、`oss_code`、`oss_request_id`、`status` 和 `elapsed_ms`。`请求 OSS 失败` 时，`timeout/connect/transport=true` 表示传输类失败；`status=400, oss_code=RequestTimeout, timeout=true`、`status=429` 或 `500–599` 表示暂时性失败，PUT 的 `status=400`、`oss_code` 为空且 `timeout=true` 或 `transport=true`（message 含「错误响应体读取失败」）同样是暂时性失败。除 `RequestTimeout` 和该错误体读取失败两类例外外，其他 400、401/403/404、配置、URL 和签名错误是确定性失败，不会重试。最终帧 HEAD 失败只会重试 HEAD，不会重复 PUT；如果任一帧最终失败，确认整段动作已排空已启动 Future，并检查任务按现有契约退款且没有发布缺帧动画。
|
||||
|
||||
### AGC 项目快照上传目标
|
||||
|
||||
AGC 客户端按周期与项目关闭时机把用户项目增量上传到 `agc-dev`。客户端只持有平台登录态 Access
|
||||
Token，经 `POST /api/agc/project-snapshots/files`（单文件原始字节）与
|
||||
`POST /api/agc/project-snapshots/manifest`（本次同步清单）交给 `api-server`，由服务端写入私有前缀
|
||||
`agc/project-snapshots/v1/{user}/{project}/`；客户端不直连 OSS，也不持有 OSS 凭据。
|
||||
|
||||
```env
|
||||
GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET=agc-dev
|
||||
GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ENDPOINT=oss-rg-china-mainland.aliyuncs.com
|
||||
GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_ID=
|
||||
GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_SECRET=
|
||||
```
|
||||
|
||||
专用凭据为空时回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，bucket 与 endpoint
|
||||
仍默认指向 AGC 发行 bucket，因此回退凭据必须具备目标 bucket 该前缀的 `PutObject` / `GetObject` /
|
||||
`DeleteObject` 权限；`api-server` 启动时会打印一行 `AGC 项目快照 OSS 客户端已启用`（含 bucket、
|
||||
endpoint 与凭据来源，不含密钥），凭据缺失或只配一半则跳过该客户端、接口返回 `503`，客户端按失败关闭
|
||||
处理：不写空对象，也不推进本地增量索引，下一次触发重算重试。
|
||||
|
||||
远端占用按当前清单收敛：每次清单写入成功后，服务端用上一版清单反推不再被引用的对象键并删除，单次最多
|
||||
回收 2000 个，上一版清单不可读时整轮跳过（不会误删）。因此不需要额外配置 bucket 生命周期来防止无界
|
||||
增长；`agc/project-snapshots/v1/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
|
||||
单次同步上传预算 512 MiB、单项目常驻 2 GiB；超限分别表现为跳过/延后/413。服务端另有进程内小时配额
|
||||
（文件 3000 次、清单 120 次）与同一项目 5 秒最小清单间隔，超限返回 `429` 并带 `Retry-After`。
|
||||
|
||||
两层可重复的现场验证：
|
||||
|
||||
```bash
|
||||
# 1. 存储层：直接对真实 bucket 做内部前缀写入、读回与清理，并在结束时删除探针对象。
|
||||
cargo run -p platform-oss --example agc_project_snapshot_live_smoke --manifest-path server-rs/Cargo.toml
|
||||
|
||||
# 2. 客户端链路：真实差异引擎 → 本地 api-server → 真实 OSS。第一次必须 synced 且上传 > 0，
|
||||
# 紧接着的第二次必须 no-op 且上传 0 个文件；需要先取得登录态并指定项目与索引目录。
|
||||
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml \
|
||||
project_snapshot_live_sync -- --ignored --nocapture
|
||||
```
|
||||
|
||||
客户端冒烟读取 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_LIVE_PROJECT`（项目绝对路径，建议用可丢弃的副本）、
|
||||
`..._LIVE_TOKEN`、`..._LIVE_API_BASE_URL`、`..._LIVE_USER_ID` 与 `..._LIVE_CONFIG_DIR`（索引目录，
|
||||
`cargo test` 进程没有窗口 setup 初始化 AppData 配置目录，必须显式指定）；未设置时用例自我跳过。
|
||||
本地联调可用 `npm run dev:api-server` 起 api-server，并用密码登录（开发态默认允许未知手机号自动注册）
|
||||
取得 Access Token。
|
||||
|
||||
## 生产运维
|
||||
|
||||
生产部署当前口径：
|
||||
@@ -739,6 +785,8 @@ npm run container:down
|
||||
`npm run container:config` 默认只做 quiet 校验，避免把本地 env 中的 token 展开到终端；确需排查完整 compose 时再传 `-- --print`。
|
||||
|
||||
多人内网预览入口固定为 `http://192.168.35.82/build/`，不配置公网域名。该独立 Jenkins 容器预览部署控制面不让浏览器直接操作 Docker 或持有 Jenkins Token；SPA 通过同源代理触发固定 `shared/Genarrative-Preview-Deployer` Job。分支和 commit 输入框通过受认证的控制服务搜索固定内网 Git 仓库并展示下拉结果；提交构建前控制服务重新确认分支存在、可选 commit 存在且属于目标分支，失败时不触发 Jenkins，Jenkins checkout 仍保留最终复核。每个分支使用稳定的内部 `deploymentId` 和独立 Compose project，Web 端口从 `8400..8499` 在文件锁内分配，同一分支换 commit 优先复用端口，卸载后释放；页面记录 ID 使用 Jenkins 构建编号。Jenkins 用 `preview-result.json` 向页面提供 resolved commit、发布结果和内网 Web URL，页面刷新时由控制服务实时复核 Web 健康；构建详情链接固定使用局域网 Jenkins 地址，不暴露 loopback 地址。失败/取消且不可卸载的记录保留 7 天，停止记录保留 30 天，仍可卸载的失败记录不会自动清理。安装资产为 `deploy/systemd/genarrative-preview-deployer.service`、`deploy/env/preview-deployer.env.example` 和 `deploy/nginx/genarrative-preview-deployer-lan.conf`；完整合同见 `docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md`。
|
||||
Jenkins controller 与 Gitea 同机运行在 `genarrative-station`，除内网入口 `http://192.168.35.82:8080/jenkins/` 外，公网入口为 `https://jenkins.genarrative.world/jenkins/`：dev 的 `/etc/nginx/conf.d/jenkins.genarrative.world.conf` 把 `443` 反代到 `http://127.0.0.1:18085`，该 loopback 端口由同机 `gitea-reverse-tunnel.service` 新增的 `-R 127.0.0.1:18085:127.0.0.1:8080` 落到 station 的 `jenkins.service`（`--prefix=/jenkins`，因此域名根路径 `302` 到 `/jenkins/login`）。排障顺序：dev `ss -tlnp | grep 18085` 必须有 `sshd` 监听，`curl -sI https://jenkins.genarrative.world/jenkins/login` 必须 `200`，`systemctl status gitea-reverse-tunnel.service` 必须 `active`，且公网 `80/443` 仍由 Nginx 监听；`slaveAgentPort=-1` 保持关闭，agent 仍走 SSH launcher，不新增入库端口。证书按 router 口径用 Certbot webroot（`/var/www/html`）维护，续期 hook 为 `systemctl reload nginx`。
|
||||
预览部署控制面的公网入口为 `https://build.genarrative.world/build/`（`/` 与 `/build` 分别 `302`/`301` 到 `/build/`，API 走同源 `/api/preview-deployer/`）：dev 的 `/etc/nginx/conf.d/build.genarrative.world.conf` 反代到 `127.0.0.1:18086`，该 loopback 端口由 station `gitea-reverse-tunnel.service` 的 `-R 127.0.0.1:18086:127.0.0.1:8410` 落到控制面 `preview-deployer-server`。控制面按 `Host` 精确匹配白名单、对非 GET 的 `/api/*` 精确匹配 `Origin`，公网域名必须同时出现在 `GENARRATIVE_PREVIEW_DEPLOYER_ALLOWED_HOSTS` 和 `GENARRATIVE_PREVIEW_DEPLOYER_ALLOWED_ORIGINS` 中；公网 cookie 的 `Secure` 由 dev nginx 的 `proxy_cookie_flags ~ secure` 强制，因此 `GENARRATIVE_PREVIEW_DEPLOYER_SECURE_COOKIE` 保持 `false`，内网 `http://192.168.35.82/build/` 的登录态不受影响。排障顺序：dev `ss -tlnp | grep 18086` 有 `sshd` 监听；`curl -s https://build.genarrative.world/api/preview-deployer/session` 返回 `{"authenticated":false}`；缺失或错误 `Origin` 的 POST 必须 `403`，错误口令必须 `401`。`preview.genarrative.world` 当前只是通配规划下的落地页，预览实例仍只在内网 `http://192.168.35.82:84xx`；要暴露实例需要 `*.preview.genarrative.world` 通配证书（只能 DNS-01）、station 侧按 Host 分发和页面 `webUrl` 口径改造。
|
||||
隔离验证 worker 队列和 API-only 更新时使用 `npm run container:worker-smoke -- smoke`。该命令不复用 `deploy/container/api-server.env`，会在 `deploy/container/worker-smoke/` 生成本机专用 env 与端口 state，并且只使用 unsupported job 验证 worker claim / fail 回写，不覆盖 BgFilter 成功、失败或 fallback 链路，也不需要真实外部生成密钥；本机 crates.io 网络不稳时使用 `--local-binary`，由容器内 Cargo 复用本机 Cargo 缓存构建，并把产物放进 Debian bookworm smoke runtime。
|
||||
|
||||
独立 BgFilter worker 的本机全进程验证先运行 `cargo build -p api-server --manifest-path server-rs/Cargo.toml`，再依次运行 `npm run bgfilter-worker:smoke-test`、`npm run bgfilter-worker:load-smoke` 和 `npm run bgfilter-worker:fault-smoke`。三条命令只使用动态 loopback 端口、假 OSS 签名配置和本地 mock provider；不会读取仓库 `.env*` 或请求真实 BgFilter / OSS。自定义或 WSL binary 通过 `GENARRATIVE_BGFILTER_SMOKE_BINARY` 指定。当前 fault 范围包含 overload、queue deadline、两类 HTTP 状态顺序重试结果，以及 provider 成功响应 body 中途 reset 后第二次 attempt 串行成功；慢读、大响应、父侧客户端断连与 SIGTERM 排空另行验证。
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user