完成客户端素材画布阶段五真实图片生成闭环
通过共享生成端口接入 External Editor 图片生成与精修 建立稳定生成幂等身份和私有可恢复账本 复用正式资产事务及资源投影布局选择链路 补齐取消迟到、重复完成、重启恢复和隐私隔离测试 同步更新素材画布技术合同与项目共享记忆
This commit is contained in:
@@ -6145,3 +6145,13 @@
|
||||
- telemetry 只扫描可见 DOM 文本和 AST 可达的 JavaScript：hidden DOM、字符串/注释、恒假分支、未调用函数和 inert/raw-text 内容不得补齐状态字段；已链接 classic/module 单元沿同一可达扫描口径判定。玩法 identity 保留独立的现有识别口径，不能反向补齐 telemetry。
|
||||
- CSS `url(...)` 的资产路径保持原始大小写解析，stylesheet 证据必须同时命中实际可见元素；未命中 selector、元素自身或祖先 hidden、以及匹配隐藏规则的节点均不作证。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-08-05 客户端素材画布真实图片生成复用 External Editor 与正式资产事务
|
||||
|
||||
- 生成入口决策：客户端共享素材画布只实现首版图片生成与精修，通过共享 `ImageCanvasGenerationPort` 调用既有 External Editor v1 与 `canvas.asset_generate`，不复制网站 `useImageCanvasGenerationWorkflow`，不建立第二套生成、扣费或发布系统。
|
||||
- 确认决策：编辑 prompt、尺寸、比例、素材类型与参考图只改本地 UI；最终“确认生成”之前零 External 请求。一次已确认意图固定 `intentId + generationId + External idempotencyKey + commitId + commit idempotencyKey`，未知结果、重启和重复点击只能沿原身份恢复。
|
||||
- 持久化决策：prompt、精确请求快照、配置指纹、External key、operationId、上传凭证和远端稳定引用只写 `.agent/workbench/asset-canvas/generations/` 私有账本；公开草稿、manifest 与事件只投影安全阶段和本地资产身份。External taskId 不得写入本地 manifest taskId。
|
||||
- 恢复决策：`accepted/running` 只 GET 原 operation，提交未知只用原请求字节和原 key 对账；远端完成后以固定 staging token 下载，再进入阶段三 journal/ledger。应用打开严格先恢复本地正式资产事务，再恢复 generation ledger，因此下载后提交中断只恢复原本地事务，不重新生成或下载。
|
||||
- 显现决策：`generation-accepted -> generation-running -> remote-completed -> media-downloaded -> asset-durable-committed -> manifest-projected -> layout-ready -> selected` 不可压成 completed；停止 UI 等待只失效聚焦意图，迟到完成仍可安全投影 manifest，但不能抢焦点。
|
||||
- 精修身份决策：正式本地资源通过 `referenceResourceIds` 引用原资源；External `sourceImageSrc` 只使用 objectKey、项目 resourceId 或素材 assetId，不能把 assetObjectId 当成媒体引用。`sourceResourceId` 只允许真实 External resourceId，不能使用 `local-asset:*` 或 objectKey 冒充。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/asset_canvas/generation.rs`、`packages/image-canvas-core/src/ports.ts`、`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`。
|
||||
|
||||
@@ -4204,3 +4204,12 @@
|
||||
- 原因：脚本用 `Buffer.readUInt32BE(0)` 读取文件头，却只比较 `0xfeedfacf` 等正序数值；arm64 常见头字节是 `cf fa ed fe`，读取结果为 `0xcffaedfe`。
|
||||
- 处理：文件头白名单同时覆盖 32/64 位与 fat Mach-O 的正序和反字节序合法魔数，并由桌面配置门禁同时反查 staging 脚本和根级产物检查，不能改成只按扩展名或构建退出码判断。
|
||||
- 验证：在 macOS 上构建真实 desktop-shell release，运行 `npm run desktop-shell:stage-release-binary`，再由 `npm run check:native-shells` 校验 staged 产物。
|
||||
|
||||
## 远端图片 completed 不能冒充本地资源创建成功（2026-08-05）
|
||||
|
||||
- 现象：External operation 已返回 completed，但稳定引用缺失、下载失败、正式资产事务中断或 manifest 已提交而 UI 事件丢失时，界面仍可能提前显示“资源创建成功”，重复回调还可能再次下载、写文件或登记资源。
|
||||
- 原因：把远端生成、媒体传输、本地 durability、manifest 投影、布局和选择压成一个 completed 布尔值；同时把 External idempotencyKey、operationId 或 taskId 暴露到公开草稿，导致恢复逻辑从非权威状态重建请求或误绑本地 task graph。
|
||||
- 处理：使用私有 generation ledger 保存原请求、External 身份、稳定远端引用、固定 staging token 与本地 commit 身份；公开面只投影不可逆阶段。启动时先恢复阶段三事务，再恢复原 generation；重复 completed 先检查远端引用、staging 和 committed ledger，只有 `committed | already-committed` 才进入 manifest 投影。用户取消等待只推进 focus generation，不删除账本或伪装远端取消。
|
||||
- 精修补充：`sourceImageSrc` 是可下载的稳定媒体引用，`sourceResourceId` 是资源身份，二者不能因为都可表现为字符串就填同一个 objectKey。本地 `local-asset:*` 只保留在本地 manifest 血缘；没有真实 External resourceId 时省略 `sourceResourceId`。
|
||||
- 验证：覆盖确认前零调用、同 key 连点、accepted 重启 GET-only、重复 completed、取消后迟到、下载后本地事务恢复、事件丢失、切项目/改选择、旧轮询隔离、实时布局与选择、精修血缘及敏感字段零泄漏。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/asset_canvas/generation.rs`、`apps/ai-game-creator-shell/src/features/asset-canvas/AssetCanvasSurface.tsx`、`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`。
|
||||
|
||||
@@ -948,3 +948,11 @@ game-project/
|
||||
- 保存开始冻结 `saveAttemptId + sessionId + draftId + commitId + focusGeneration`。迟到提交始终可以更新当前项目的权威 manifest，但只有 flow、项目、保存尝试和 generation 仍匹配的最新意图可以继续定位。定位依次等待资源投影、dependency/type 两份布局 settled 且均有位置、当前筛选可见和 `data-resource-id` DOM 卡片存在；完成后按 commitId 只执行一次。搜索隐藏时保留条件并提供“清除搜索并定位”，该显式动作建立新的 focus generation。
|
||||
- 锁职责复核保持阶段三实现：正式提交/恢复固定为“项目 mutation write lock -> asset-canvas draft/transaction lock -> manifest store lock”；资源布局只取得独立 `.layout.lock`，不取得项目 mutation 或 asset-canvas 锁，布局协调只发生在提交释放锁并返回/发事件之后，不形成反向锁顺序。
|
||||
- 阶段四新增纯状态机与中央主视窗集成测试，覆盖响应/事件双顺序、旧 manifest、旧 graph/layout、切项目、改选择、连续保存、搜索隐藏、布局未完成、DOM 一次聚焦、refine 真实依赖以及无 reload/重开项目。最终通过项以本次任务验证记录为准。
|
||||
|
||||
## 2026-08-05 客户端素材创作无限画布阶段五真实图片生成
|
||||
|
||||
- 阶段五只接图片生成与图片精修，通过阶段二共享 `ImageCanvasGenerationPort` 调用客户端 Tauri adapter，并复用 `canvas.asset_generate` 的 External Editor 会话准备、异步提交/查询、稳定引用解析和受控下载能力；不复制网站 `useImageCanvasGenerationWorkflow`，不新增角色动画、视频、音频、图集或平行生成系统。
|
||||
- 生成面板和确认摘要只操作本地状态；用户点击独立“确认生成”后才通过 `canvas.asset_generate` confirm 权限边界。本地生成意图建立时即分配稳定 `intentId/generationId/idempotencyKey`，取消确认则直接丢弃且零 External 调用；一旦提交，重复点击、重启和未知结果保持原身份，不能自动确认或换键重扣。
|
||||
- External endpoint、精确请求、prompt、配置指纹、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。API Key、Authorization、Provider URL、签名 URL和绝对路径不进入项目事实；草稿/manifest/event/日志只投影安全阶段与本地身份，External 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 可以更新原项目但不能抢焦点。配置缺失、结果引用不稳定、下载/提交失败和未知结果都不得显示资源创建成功。
|
||||
|
||||
@@ -882,3 +882,56 @@ cancelling
|
||||
| A28 | 恢复草稿 | 主文件损坏但恢复副本可信/不可信 | 可信副本恢复到 clean history 基线；不可信进入对账，不猜测 |
|
||||
|
||||
下一阶段只有在矩阵对应的纯模型、共享 React、Web adapter、Tauri adapter、Rust 持久化与 AppSurface 测试全部通过后，才可宣称图片素材创作正式闭环完成。
|
||||
|
||||
## 14. 2026-08-05 阶段五真实图片生成补丁
|
||||
|
||||
本节是 Tauri 真实图片生成的编码级补丁；与第 3、6、12 节的早期四态生成记录冲突时，以本节为准。网站继续复用现役生成工作流，客户端只通过共享 `ImageCanvasGenerationPort` 接入，不复制 `useImageCanvasGenerationWorkflow`，也不新建第二套服务端生成系统。
|
||||
|
||||
### 14.1 确认与身份
|
||||
|
||||
- 打开生成面板、修改 prompt / 比例 / 尺寸 / `assetKind`、选择参考资源和预览确认摘要都只能产生本地 UI 状态，确认前不得读取或创建 External Editor 项目、素材目录、上传票据或生成 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。
|
||||
|
||||
### 14.2 私有账本与公开投影
|
||||
|
||||
私有账本固定放在：
|
||||
|
||||
```text
|
||||
.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 恢复身份。阶段三正式资产事务继续由既有持久锁保护。API Key、Authorization、Provider URL、签名 URL 和绝对路径不得写入账本；API Key 只参与不可逆配置指纹。
|
||||
|
||||
草稿、manifest、Tauri 事件、Agent DB、Runtime observation、trace、普通错误和日志只允许出现 `intentId/generationId`、安全阶段、引用资源 ID、本地 asset/commit/event 身份和稳定错误码。草稿 generation record 不再保存 prompt、External idempotency key 或 operationId；阶段五读取旧空记录兼容，但下一次成功写入必须移除这些私有字段。
|
||||
|
||||
### 14.3 不可压缩状态机
|
||||
|
||||
生成与显现必须按下列阶段推进，不能用单个 `completed` 布尔值代替：
|
||||
|
||||
```text
|
||||
confirmation-required
|
||||
→ generation-accepted
|
||||
→ generation-running
|
||||
→ remote-completed
|
||||
→ media-downloaded
|
||||
→ asset-durable-committed
|
||||
→ manifest-projected
|
||||
→ layout-ready
|
||||
→ selected
|
||||
```
|
||||
|
||||
- `generation-accepted` 只表示 External `202 + operationId` 已原子落账；`queued/running` 继续属于远端生成期。
|
||||
- `remote-completed` 必须已经取得自洽稳定引用；缺 `objectKey/resourceId/assetObjectId` 中可支持下载与身份核验的必要组合时进入 `reconciliation-required`，不得显示成功。
|
||||
- `media-downloaded` 表示媒体通过 `/assets/read-url` 换签、SSRF/重定向门禁、大小、签名、完整解码和尺寸检查，并已写入阶段三受控 staging；重复 completed 不再下载或重写。
|
||||
- `asset-durable-committed` 只来自阶段三 journal / ledger 的 `committed | already-committed`。下载成功但提交失败时保留 generation ledger、staging token 和原 commit 身份，恢复只继续本地事务，不重新生成或下载。
|
||||
- `manifest-projected / layout-ready / selected` 继续复用阶段四单向链路。只有当前项目、flow、session、draft、intent 和 focus generation 全匹配时才允许选择；manifest 已提交但事件丢失时以 command/recovery 的权威完整快照继续投影。
|
||||
|
||||
### 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 个。
|
||||
- `accepted/running` 重启只查询原 operation；`prepared` 只以账本中的原 endpoint、原始字节和原键恢复同一 POST。轮询超时、临时鉴权/网关错误或结果未知保持可恢复，不自动转 failed 或换键扣费。
|
||||
- 用户“停止等待”只撤销当前 session 的聚焦意图，不伪装远端取消。后台 command 可以继续安全 reconcile；应用退出后由项目恢复扫描继续原 operation。迟到完成可以更新原项目权威缓存和 manifest，但不能切回旧画布、清搜索或抢焦点。
|
||||
- 配置缺失、远端 terminal failed、稳定引用缺失、下载失败、staging/正式提交失败都不得返回资源创建成功。只有 terminal failed 才允许用户通过新的独立确认建立新 intent；其它未知或对账状态必须保留原身份。
|
||||
|
||||
Reference in New Issue
Block a user