Merge remote-tracking branch 'origin/master' into codex/game-agent-resource-workbench
# Conflicts: # docs/project-memory/shared-memory/decision-log.md
This commit is contained in:
@@ -8,7 +8,7 @@
|
||||
|
||||
## 背景
|
||||
|
||||
VectorEngine `gpt-image-2`、音频、LLM 等外部生成不能由面向外部调用方的 HTTP 请求长期等待上游、OSS 持久化和 SpacetimeDB 回写。站内保留受控 `inline` 排障模式；External v1 的八类生成则固定使用持久队列和统一查询接口，避免调用方超时后重复提交、重复扣费或丢失已完成结果。
|
||||
VectorEngine `gpt-image-2`、音频、LLM 等外部生成不能由面向外部调用方的 HTTP 请求长期等待上游、OSS 持久化和 SpacetimeDB 回写。站内保留受控 `inline` 排障模式；External v1 的九类生成则固定使用持久队列和统一查询接口，避免调用方超时后重复提交、重复扣费或丢失已完成结果。
|
||||
|
||||
## 目标
|
||||
|
||||
@@ -117,7 +117,7 @@ pending/running -> cancelled (预留)
|
||||
- `queue`：默认值，HTTP handler 入队 `external_generation_job`，由 `external-generation-worker` 角色 claim lease 后执行；生产、预发和压测默认使用该模式。
|
||||
- `inline`：HTTP handler 直接调用同一个 worker executor，同步等待 provider、OSS 和 SpacetimeDB 写回完成后返回 `operation.status = completed`；只用于本地或低并发排查，不提供队列持久化、lease 重领和 worker 横向扩容。
|
||||
|
||||
External v1 八类生成不读取上述模式分支：即使进程配置为 `inline`，External handler 仍只做校验、幂等入队并返回 HTTP `202`。调用方按 `/api/external/v1/generations/{operationId}` 查询；这条外部契约不能因部署环境不同而从异步退化为同步响应。
|
||||
External v1 九类生成不读取上述模式分支：即使进程配置为 `inline`，External handler 仍只做校验、幂等入队并返回 HTTP `202`。调用方按 `/api/external/v1/generations/{operationId}` 查询；这条外部契约不能因部署环境不同而从异步退化为同步响应。
|
||||
|
||||
同一个 Rust binary 通过 `GENARRATIVE_PROCESS_ROLE` 切换：
|
||||
|
||||
@@ -220,7 +220,7 @@ inline 完成结果与 External v1 completed compact result 继续使用结构
|
||||
|
||||
### External v1 异步提交与查询
|
||||
|
||||
External v1 复用上述九类 editor job kind 中除手动去背景外的八类生成 kind。外部 POST handler 只负责 API Key scope、owner、请求校验和入队，不调用 `*_for_owner` 同步执行函数：
|
||||
External v1 复用上述全部九类 editor job kind，包括手动去背景。外部 POST handler 只负责 API Key scope、owner、请求校验和入队，不调用 `*_for_owner` 同步执行函数；去背景在入队前还会解析当前 owner 的稳定来源，并预检、规范化项目与素材目录目标。提供 `targetLayerId` 时必须同时提供 `projectId`；没有 `canvasCompletion` 时还要确认目标图层存在并关联当前项目资源，存在 `canvasCompletion` 时继续按生成完成链路写入而不执行原位替换：
|
||||
|
||||
1. 每个生成 POST 必须携带 `Idempotency-Key`。服务端把 owner、job kind、稳定键和规范请求纳入 dedupe；未知结果重试必须复用原键。
|
||||
2. 成功入队返回 HTTP `202`、`operationId`、`statusUrl`、`pollAfterMs`，并设置 `Location` / `Retry-After`；不返回 project、asset 或媒体结果。
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
- 项目路径、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 调用权。
|
||||
|
||||
## 2026-08-23 AGC 资源生成补齐（视频 / 动画 / 音效 / 背景音乐）
|
||||
|
||||
@@ -16,7 +17,7 @@
|
||||
- 新建视频 / 音效 / 背景音乐时，先复用 `prepare_external_canvas_generation_context` 创建或匹配同名画板项目与素材库目录，并在生成请求中携带 `projectId / assetFolderId / canvasCompletion`，结果同时进入平台画布 / 素材库与本地 manifest。
|
||||
- durable 账本新增 `remoteLegacyPublicPath` 字段（旧账本默认缺省），用于角色动画预览视频的换签下载与恢复；资源提交、轮询、下载、manifest 提交和恢复队列继续复用既有资源编辑事务链。
|
||||
- 资源编辑请求指纹纳入 `generationMode`，同一 `operationId` 换生成模式重试时不再按旧账本模式恢复；旧账本继续通过 legacy 指纹兼容。
|
||||
- 去背景（`/api/editor/images/background-removals`）仍缺 External v1 契约，不在本次补齐范围；本次只补视频 / 角色动画 / 音效 / 背景音乐。
|
||||
- 去背景通过 External v1 语义工具开放；原始服务端 worker 和账号态内部路由仍不直接暴露给 Codex。
|
||||
|
||||
## 2026-08-19 UI Editor 节点右键菜单
|
||||
|
||||
@@ -780,6 +781,7 @@ game-project/
|
||||
|
||||
- `apps/ai-game-creator-shell` 是独立 Tauri App，不复用 `apps/desktop-shell`。
|
||||
- 独立客户端启动时先进入平台登录检查；未登录页默认展示手机号验证码登录，并保留密码登录切换。验证码登录调用平台后端 `/api/auth/phone/send-code` 与 `/api/auth/phone/login`，密码登录继续调用 `/api/auth/entry`；Tauri dev 下 `/api` 走本轮动态 AGC Vite 代理，普通发布版静态窗口下通过 Tauri 原生 HTTP transport 固定访问开发服务器 `https://dev.genarrative.world/api/*`，避开 WebView CORS 预检并持久化刷新 Cookie。原生 HTTP capability 只允许该 HTTPS origin 的 `/api/*`，客户端解析层也拒绝其它 release origin；game-chat release 继续不依赖平台登录和 `api-server`。网络层失败时展示登录服务不可达提示，不裸露 WebView 的 `Load failed`。
|
||||
- 登录检查、未登录和客户端页面加载失败三种认证外壳统一使用共享陶泥儿产品形象与平台浅色主题 token；登录卡片、输入框、方式切换和主按钮沿用平台暖色视觉，并在不超过 `480px` 的窄视口收紧留白。视觉优化不改变服务器选择、验证码、密码、登录态安装或错误恢复语义。
|
||||
- `npm run agc` 的本地 SpacetimeDB owner identity 以独立 `spacetimeDataDir` 为作用域，不绑定可能漂移的监听端口；旧端口作用域记录仅在同一 data dir 下身份唯一时自动迁移，出现多个不同旧身份时失败关闭。`.app/dev-stack.json` 必须记录规范化 `spacetimeDataDir`，独立壳只复用数据库名和该目录同时匹配且健康的后端，旧 schema 状态或共享目录状态缺少此字段时不得复用。POSIX 子进程在 `spawn` 返回时立即登记 `error / exit` 生命周期、保存 detached leader 的 PGID 并把句柄交给外层；即使 direct leader 已先退出，也必须继续向负 PGID 发信号清理同组后代。后端 ready 前的 SIGINT、SIGTERM、超时或 ENOENT 都必须走同一进程组清理链路，不能遗留 npm、Cargo 或 SpacetimeDB。非 Linux Runtime 执行 `project.verify` 时，`npm run` 参数校验必须允许受控的 `--silent`、`--ignore-scripts` 位于脚本名前，并继续拒绝缺少真实脚本名的调用。
|
||||
- Tauri Rust 入口保持薄壳：`src-tauri/src/main.rs` 只保留共享类型 / 常量、模块声明、CLI preflight、`tauri::Builder`、运行时配置初始化和 `invoke_handler` 清单；命令行入口放在 `cli.rs`，Tauri command 包装放在 `commands.rs`，运行时配置与 LLM 配置检查放在 `config.rs`，Agent loop 与生成编排放在 `agent.rs`，上传 / 画板 / 平台美术生成接入放在 `assets.rs`，本地项目文件、记忆、对话、权限、checkpoint、manifest 和通用路径工具放在 `project.rs`，本地 HTTP 预览与 preview 命令放在 `preview.rs`，旧窗口兼容命令放在 `windows.rs`，Rust 单测放在 `tests.rs`。后续继续拆分时保持 Tauri command 名、JSON 字段、`.agent/*` 路径和错误语义不变。
|
||||
- 本地项目初始化会创建 `game/`、`assets/`、`memory/`、`memory/agents/`、`exports/`、`.agent/logs/`，写入 `.agent/manifest.json`，生成 append-only JSONL 本地项目索引 `.agent/agent.db`，并生成默认 `game/index.html`。
|
||||
|
||||
Reference in New Issue
Block a user