修复素材画布登录态生成闭环
复用客户端登录态与服务端环境配置，移除客户手填 API Key 的生成路径。 补齐外部生成幂等查询、泥点扣费结果回填与失败错误映射。 修复确认生成后返回原界面的问题，并完善生成中、成功和失败状态展示。 更新契约、测试、技术方案、PRD 与项目决策记录。
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
## 目标
|
||||
|
||||
在 Genarrative 内建设独立桌面 App：普通用户通过项目开发工作台中的陶泥儿对话、资源画布、运行状态和确认操作，让平台生成保存在本地的可运行 Web 游戏原型，并通过本地 HTTP server 预览；主窗口提供运行时配置入口，用于保存发布版 AppData / Tauri 配置目录里的 LLM 与画板 API 配置。任务明细、原始文件、命令日志和专业 Agent 调试控制仍放到开发构建的独立开发窗口。v1 只做 Web 小游戏原型闭环，不扩展 Unity、Godot、云同步或插件市场。
|
||||
在 Genarrative 内建设独立桌面 App：普通用户通过项目开发工作台中的陶泥儿对话、资源画布、运行状态和确认操作，让平台生成保存在本地的可运行 Web 游戏原型，并通过本地 HTTP server 预览；主窗口提供运行时配置入口，用于保存发布版 AppData / Tauri 配置目录里的 LLM 配置及受控开发者 External Editor 配置。普通客户素材画布使用平台登录态调用内部编辑器 API，不展示或要求填写画板 Base URL / API Key。任务明细、原始文件、命令日志和专业 Agent 调试控制仍放到开发构建的独立开发窗口。v1 只做 Web 小游戏原型闭环，不扩展 Unity、Godot、云同步或插件市场。
|
||||
|
||||
## 技术选择
|
||||
|
||||
@@ -952,9 +952,10 @@ game-project/
|
||||
|
||||
## 2026-08-05 客户端素材创作无限画布阶段五真实图片生成
|
||||
|
||||
- 阶段五只接图片生成与图片精修，通过阶段二共享 `ImageCanvasGenerationPort` 调用客户端 Tauri adapter，并复用 `canvas.asset_generate` 的 External Editor 会话准备、异步提交/查询、稳定引用解析和受控下载能力；不复制网站 `useImageCanvasGenerationWorkflow`，不新增角色动画、视频、音频、图集或平行生成系统。
|
||||
- 阶段五只接图片生成与图片精修，通过阶段二共享 `ImageCanvasGenerationPort` 调用客户端 Tauri adapter，并复用现有编辑器项目、统一生成队列、资产上传/换签、稳定引用解析和受控下载能力；不复制网站 `useImageCanvasGenerationWorkflow`，不新增角色动画、视频、音频、图集或平行生成系统。
|
||||
- 生成面板和确认摘要只操作本地状态；用户点击独立“确认生成”后才通过 `canvas.asset_generate` confirm 权限边界。本地生成意图建立时即分配稳定 `intentId/generationId/idempotencyKey`，取消确认则直接丢弃且零 External 调用；一旦提交，重复点击、重启和未知结果保持原身份，不能自动确认或换键重扣。
|
||||
- External 相对 endpoint、精确请求、prompt、配置指纹、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。本地参考图 direct-upload ticket 的 host/formFields/policy/signature/临时 Authorization 只存在内存；恢复账本只允许保存稳定 bucket/objectKey。API Key、Authorization、Provider URL、签名 URL和绝对路径不进入项目事实；草稿/manifest/event/日志只投影安全阶段与本地身份，External taskId 不写 manifest `source.taskId`。
|
||||
- 普通客户模式只使用当前平台登录态调用 `/api/editor/*`、`/api/assets/*` 与 `/api/runtime/external-generation/jobs/*`；后端从登录身份解析 owner、按现有统一生成队列预扣/退款泥点，并只在服务端读取供应商配置。客户 UI 不显示 Base URL / API Key，也不得把根目录 `.env*`、供应商 Key 或开发者 Key 打包给客户端。`/api/external/v1` 与开发者 API Key 继续保留给第三方 Agent、CLI 和内部验收，不能用开发者 Key 替代客户身份或计费归属。
|
||||
- 调用模式、精确相对 endpoint、精确请求、prompt、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。本地参考图 direct-upload ticket 的 host/formFields/policy/signature/临时 Authorization 只存在内存；恢复账本只允许保存稳定 bucket/objectKey。登录 Access Token、API Key、Authorization、Provider URL、签名 URL和绝对路径不进入账本或项目事实；登录 Token 刷新不得触发 `configuration-changed`。草稿/manifest/event/日志只投影安全阶段与本地身份，远端 taskId 不写 manifest `source.taskId`。
|
||||
- 固定状态顺序为 `generation-accepted -> generation-running -> remote-completed -> media-downloaded -> asset-durable-committed -> manifest-projected -> layout-ready -> selected`。远端 completed 后必须先验证稳定引用，再经 `/assets/read-url` 下载并写入阶段三 staging；随后用账本中的固定本地 commit 身份进入既有 journal/ledger 事务。正式提交失败只恢复本地事务，不重新生成或下载。
|
||||
- 应用重启时 `accepted/running` 只恢复 GET，`prepared` 只以私有账本原请求字节和原键恢复同一 POST。用户停止等待只失效当前 focus generation；不可取消的远端操作继续 reconcile，迟到 completed 可以更新原项目但不能抢焦点。配置缺失、结果引用不稳定、下载/提交失败和未知结果都不得显示资源创建成功。
|
||||
- 最终审计后 Tauri 撤销/重做直接使用与网站相同的共享 `useCanvasHistory`，共享 history 同时恢复 viewport、选择、图层位置和缩放边界；Tauri 自身只保留 Pointer 事件接线，平移、缩放、选择、图层变换和 renderer 算法继续来自共享 core/react。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
更新时间：`2026-08-06`
|
||||
|
||||
状态：阶段一产品与技术合同已冻结；截至 2026-08-06，阶段一、二共享画布 chrome 与主站接入已实现，客户端中央画布换肤留待后续阶段。
|
||||
状态：阶段一产品与技术合同已冻结；截至 2026-08-06，客户登录态图片生成、泥点计费链路、中央进度/失败态和 Tauri 正式资产提交已落地，后续增量仍受本文合同约束。
|
||||
|
||||
本文是网站与 AI 游戏创作 Tauri 客户端共享图片画布能力的下一阶段编码依据。若本文与资源管理阶段七的“美术编辑暂缓”口径冲突，以本文对后续素材创作切片的更新决定为准；资源总览既有布局、依赖图和只读聚焦合同继续有效。
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
3. 阶段一正式闭环只覆盖图片。PNG、JPEG、WebP 的导入、画布平移与缩放、单选与多选、图层移动与缩放、层序、显隐、锁定、翻转、分组、撤销与重做、裁剪/扩图等基础编辑、图片生成、导出和 Tauri 本地正式回写均属于目标，不得再列为非目标。
|
||||
4. 现有一键去背景能力可以通过共享 Host Port 接入；毛发级抠图、可编辑蒙版和高级边缘修复后续分期。图集、角色动画、视频编辑和音频编辑不进入本阶段正式闭环。
|
||||
5. 网站和 Tauri 必须实际 import 同一份画布 core 与 React/UI 源码。现役 `src/components/image-editor/` 是抽取来源，不得把整个目录复制到客户端，也不得形成网站版和 Tauri 版两份长期分叉的画布实现。
|
||||
6. 网站继续负责账户、钱包、服务端编辑器项目和云端素材库；Tauri 继续负责本地项目、受控文件读写、manifest、项目 mutation revision 和 External Editor API。共享画布不知道这些事实来自哪个宿主。
|
||||
6. 网站继续负责账户、钱包、服务端编辑器项目和云端素材库；Tauri 继续负责本地项目、受控文件读写、manifest、项目 mutation revision，并以当前平台登录态复用同一服务端编辑器与计费链路。第三方 Agent/CLI 使用的 External Editor API 是独立开发者通道，不是普通客户素材画布的鉴权方式。共享画布不知道这些事实来自哪个宿主。
|
||||
7. 本阶段不修改 SpacetimeDB schema，不新增前端业务真相，不把草稿 sidecar 当成正式资产。
|
||||
|
||||
## 2. 中央主视窗状态与入口
|
||||
@@ -58,7 +58,7 @@ apps/ai-game-creator-shell/src/features/asset-canvas/tauriImageCanvasHostAdapter
|
||||
- `image-canvas-core` 只含纯 TypeScript 的画布模型、几何、选择、图层命令、历史、序列化、防御校验和状态机；不得依赖 React、DOM、Tauri、HTTP、账号、钱包或浏览器存储。
|
||||
- `image-canvas-react` 只含 React 视图、hooks、交互控制器和通用 UI，依赖 core 和注入的 Host Port；不得直接 import Tauri API、站点请求客户端、账户 store 或钱包 store。
|
||||
- 网站 adapter 可以依赖账户、钱包、现有服务端 editor project、云端素材库、OSS/asset object 和生成 API。
|
||||
- Tauri adapter 可以依赖 `invoke/listen`、本地项目上下文、受控媒体命令、manifest、项目 revision、草稿 sidecar 和 External Editor API 配置。
|
||||
- Tauri adapter 可以依赖 `invoke/listen`、本地项目上下文、受控媒体命令、manifest、项目 revision、草稿 sidecar 和当前平台登录态；受控开发者模式才可依赖 External Editor API 配置。
|
||||
- 依赖方向只能是“宿主 adapter -> React/UI -> core”。core/react 不得反向 import 任一宿主。
|
||||
|
||||
### 3.2 禁止复制的验收门
|
||||
@@ -200,7 +200,7 @@ interface ImageCanvasHostPort {
|
||||
- `hostRevision` 是宿主权威提交版本的字符串表示：Tauri 使用十进制项目 mutation revision，网站使用现有服务端 editor project revision。共享 UI 只透传/展示，不比较不同宿主的 revision。
|
||||
- `commitId/idempotencyKey` 由共享流程在第一次正式保存前生成；响应未知时两宿主都复用原完整请求。`expectedHostRevision` 由 adapter 从已加载的权威宿主快照提供，Tauri 必须无损解析为本文的安全整数 `expectedRevision`。
|
||||
- Web adapter 把草稿、导入、生成、导出和提交映射到现有服务端 editor project、云端素材库及账户/钱包链路。
|
||||
- Tauri adapter 把草稿、导入、导出和提交映射到本文第 7 至 11 节的本地合同；生成通过 External Editor API，API Key 只从 Tauri 应用配置读取，不能进入项目 sidecar、manifest、事件或错误正文。
|
||||
- Tauri adapter 把草稿、导入、导出和提交映射到本文第 7 至 11 节的本地合同；普通客户生成通过平台登录态调用现有内部编辑器/资产/任务状态 API，后端按 owner 进入统一生成队列与泥点预扣/退款。客户界面不显示或要求填写 Base URL / API Key。External Editor API 只作为第三方 Agent、CLI 和受控内部验收通道；任一模式的凭据都不能进入项目 sidecar、manifest、事件或错误正文。
|
||||
|
||||
### 3.4 主站 UI 对齐与共享画布 chrome
|
||||
|
||||
@@ -911,10 +911,10 @@ cancelling
|
||||
|
||||
### 14.1 确认与身份
|
||||
|
||||
- 打开生成面板、修改 prompt / 比例 / 尺寸 / `assetKind`、选择参考资源和预览确认摘要都只能产生本地 UI 状态，确认前不得读取或创建 External Editor 项目、素材目录、上传票据或生成 operation。
|
||||
- 打开生成面板、修改 prompt / 比例 / 尺寸 / `assetKind`、选择参考资源和预览确认摘要都只能产生本地 UI 状态，确认前不得读取或创建服务端编辑器项目、素材目录、上传票据或生成 operation。
|
||||
- 只有用户点击独立确认面板中的“确认生成”才进入现有 `canvas.asset_generate` confirm 权限边界。项目 deny 继续优先；客户端不得调用 auto gate、模拟确认或在恢复时分配新逻辑请求。
|
||||
- 一次逻辑生成在本地意图建立时固定分配规范 UUID v4 `intentId`、`generationId`、External `idempotencyKey`、本地 `commitId` 和本地 commit idempotency key。用户取消确认可直接丢弃这组未使用身份且保持零 External 调用；一旦点击“确认生成”，重复点击、IPC 响应丢失、进程重启和结果未知都复用原值与原始请求字节。只有远端明确 terminal failed 后，用户再次明确确认才可建立新 intent。
|
||||
- External taskId 是远端生成事实，不是本地 manifest task 身份。阶段五本地正式资产的 `source.taskId` 固定为 `null`，不能把 External taskId 填入并参与本地 producer/task graph。
|
||||
- 一次逻辑生成在本地意图建立时固定分配规范 UUID v4 `intentId`、`generationId`、远端 `idempotencyKey`、本地 `commitId` 和本地 commit idempotency key。用户取消确认可直接丢弃这组未使用身份且保持零远端调用；一旦点击“确认生成”，重复点击、IPC 响应丢失、进程重启和结果未知都复用原值与原始请求字节。只有远端明确 terminal failed 后，用户再次明确确认才可建立新 intent。
|
||||
- 远端 taskId 是平台生成事实，不是本地 manifest task 身份。阶段五本地正式资产的 `source.taskId` 固定为 `null`，不能把远端 taskId 填入并参与本地 producer/task graph。
|
||||
|
||||
### 14.2 私有账本与公开投影
|
||||
|
||||
@@ -924,7 +924,7 @@ cancelling
|
||||
.agent/workbench/asset-canvas/generations/<generationId>.json
|
||||
```
|
||||
|
||||
账本由每个 `projectId + generationId` 的进程内 single-flight、安全相对路径和原子 sidecar 写入保护，包含精确 External 相对 endpoint / 请求 JSON / SHA-256、prompt 私有正文、配置指纹、External idempotency key、operationId、稳定 `objectKey/resourceId/assetObjectId`、本地 staging 与 commit 恢复身份。本地参考图上传恢复只允许暂存稳定 bucket/objectKey；direct-upload ticket 的 host、formFields、policy、signature 和临时 Authorization 只存在内存，任何阶段都不得序列化。阶段三正式资产事务继续由既有持久锁保护。API Key、Authorization、Provider URL、签名 URL 和绝对路径不得写入账本；API Key 只参与不可逆配置指纹。
|
||||
账本由每个 `projectId + generationId` 的进程内 single-flight、安全相对路径和原子 sidecar 写入保护，包含调用模式、精确相对 endpoint / 请求 JSON / SHA-256、prompt 私有正文、不依赖凭据的 API 身份指纹、远端 idempotency key、operationId、稳定 `objectKey/resourceId/assetObjectId`、本地 staging 与 commit 恢复身份。本地参考图上传恢复只允许暂存稳定 bucket/objectKey；direct-upload ticket 的 host、formFields、policy、signature 和临时 Authorization 只存在内存，任何阶段都不得序列化。阶段三正式资产事务继续由既有持久锁保护。登录 Access Token、API Key、Authorization、Provider URL、签名 URL 和绝对路径不得写入账本；登录 Token 刷新不得导致 `configuration-changed`。
|
||||
|
||||
草稿、manifest、Tauri 事件、Agent DB、Runtime observation、trace、普通错误和日志只允许出现 `intentId/generationId`、安全阶段、引用资源 ID、本地 asset/commit/event 身份和稳定错误码。草稿 generation record 不再保存 prompt、External idempotency key 或 operationId；阶段五读取旧空记录兼容，但下一次成功写入必须移除这些私有字段。
|
||||
|
||||
@@ -952,8 +952,8 @@ confirmation-required
|
||||
|
||||
### 14.4 首版请求范围与恢复
|
||||
|
||||
- 普通生成使用 `POST /api/external/v1/editor/images/generations`，支持 prompt、`1:1 | 2:3 | 3:2 | 9:16 | 16:9`、`0.5K | 1K | 2K`、合法 `assetKind` 和最多 9 个稳定参考资源。
|
||||
- refine 使用 `POST /api/external/v1/editor/images/edits`，`sourceImageSrc` 必须来自源资产的 objectKey、External 项目 resourceId 或素材 assetId；`assetObjectId` 本身不是该字段接受的引用。本地独有图片在用户确认后先走现有 direct-upload ticket → OSS form → object confirm，确认后的 objectKey 才可进入生成请求。`sourceResourceId` 只在源资产确有 External resourceId 时发送，不能用本地 `local-asset:*`、objectKey 或 assetObjectId 冒充。额外参考最多 8 个。
|
||||
- 普通客户生成使用 `POST /api/editor/images/generations`，refine 使用 `POST /api/editor/images/edits`；两者携带当前登录 Bearer Token 和稳定 `Idempotency-Key`，由后端将 owner 与幂等身份绑定并沿统一生成队列扣费。提交响应中的 `queueState.operationId` 是轮询身份，状态使用 `GET /api/runtime/external-generation/jobs/{operationId}`；completed 必须返回与 External 通道一致语义的 compact `result`，供客户端解析稳定引用。
|
||||
- 开发者模式才使用对应 `/api/external/v1/editor/images/*`；两种模式支持相同 prompt、`1:1 | 2:3 | 3:2 | 9:16 | 16:9`、`0.5K | 1K | 2K`、合法 `assetKind` 与参考资源约束。refine 的 `sourceImageSrc` 必须来自源资产的 objectKey、服务端项目 resourceId 或素材 assetId；`assetObjectId` 本身不是该字段接受的引用。本地独有图片在用户确认后先走现有 direct-upload ticket → OSS form → object confirm，确认后的 objectKey 才可进入生成请求。`sourceResourceId` 只在源资产确有服务端 resourceId 时发送，不能用本地 `local-asset:*`、objectKey 或 assetObjectId 冒充。额外参考最多 8 个。
|
||||
- `accepted/running` 重启只查询原 operation；`prepared` 只以账本中的原 endpoint、原始字节和原键恢复同一 POST。轮询超时、临时鉴权/网关错误或结果未知保持可恢复，不自动转 failed 或换键扣费。
|
||||
- 用户“停止等待”只撤销当前 session 的聚焦意图，不伪装远端取消。后台 command 可以继续安全 reconcile；应用退出后由项目恢复扫描继续原 operation。迟到完成可以更新原项目权威缓存和 manifest，但不能切回旧画布、清搜索或抢焦点。
|
||||
- 配置缺失、远端 terminal failed、稳定引用缺失、下载失败、staging/正式提交失败都不得返回资源创建成功。只有 terminal failed 才允许用户通过新的独立确认建立新 intent；其它未知或对账状态必须保留原身份。
|
||||
- 登录失效、余额不足、平台生成服务配置错误、远端 terminal failed、稳定引用缺失、下载失败、staging/正式提交失败都不得返回资源创建成功。客户模式不得把缺少开发者 API Key 显示为失败原因。只有 terminal failed 才允许用户通过新的独立确认建立新 intent；其它未知或对账状态必须保留原身份。
|
||||
|
||||
Reference in New Issue
Block a user