Merge remote-tracking branch 'origin/master'

# Conflicts: # apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs
2026-08-24 12:21:29 +08:00
parent 46053832fd 2449e77461
commit 299b52d71b
55 changed files with 17802 additions and 1676 deletions
@@ -418,6 +418,11 @@
            "ExternalApiKey": []
          }
        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
+          }
+        ],
        "requestBody": {
          "required": false,
          "content": {
@@ -439,11 +444,17 @@
              }
            }
          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -684,6 +695,9 @@
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
          }
        ],
        "requestBody": {
@@ -718,6 +732,9 @@
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -766,6 +783,11 @@
            "ExternalApiKey": []
          }
        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
+          }
+        ],
        "requestBody": {
          "required": true,
          "content": {
@@ -795,6 +817,9 @@
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -1557,6 +1582,18 @@
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
+      },
+      "IdempotentCreateKey": {
+        "name": "Idempotency-Key",
+        "in": "header",
+        "required": false,
+        "description": "可选的稳定创建幂等键。同一账号、接口与键使用相同规范化请求体重试时返回首次结果的当前记录，即使该记录后来已被修改；同键不同请求体返回 409。首次结果已删除时，同键重放同样返回 409 且不会重新创建。网络结果不确定时必须复用原值。",
+        "schema": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[!-~]+$"
+        }
      }
    },
    "responses": {
@@ -1610,6 +1647,16 @@
          }
        }
      },
+      "IdempotentCreateConflict": {
+        "description": "稳定创建幂等冲突：同一 Idempotency-Key 携带不同规范化请求体，或首次创建结果已删除 / 缺少耐久回执；服务端不会重新创建或重复首次副作用",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
      "UpstreamError": {
        "description": "上游生成服务失败",
        "content": {
@@ -66,7 +66,10 @@
 - 原生读取必须在命令入口、权限 / 登记复核后、打开文件后、每个固定上限读取块之间、签名 / 图片结构校验前、漂移复核前和 base64 编码前检查取消。取消的排队任务不得打开文件，取消的在途任务不得生成 data URL 或 Blob URL；全局 permit 只能在对应原生任务结束后释放。重复 `requestId` 失败关闭，取消未知或已完成 scope 幂等成功；成功、失败和取消均必须清理活动 request / scope registry。为防止近期 request ID 重放和已取消 scope 复活，原生管理器继续保留有界 tombstone：seen request 最多 `8192` 项；非活动 cancelled scope 的保留预算为 `1024` 项，仍有请求的已取消 scope 必须临时钉住，最后一个请求结束后立即重新淘汰到预算内。明确取消只静默收口旧 scope，当前 scope 的真实 transient / permanent 失败语义不变。
 - 安全读取失败、图片解码失败或视频无可解码画面时，卡片展示稳定类型占位，不挂载破图，不降级为项目外 URL 或裸路径读取。滚动可见性不得自动重试已失败预取；读取漂移、文件替换和通用暂时失败标记为 transient，用户再次打开详情或点击播放时可以显式重试。超尺寸、损坏、类型不支持和不安全 SVG 等永久失败继续缓存且不得用“关闭后重试”误导用户。

-### 3.4 数值微调
+### 3.4 运行视窗与数值微调
+
+- 运行视窗必须占满中央工作区为游戏保留的可用区域。loopback 预览页通过客户端本地 preview server 注入的只读尺寸桥上报文档实际宽高；宿主只接受当前 iframe、当前 loopback origin 的固定版本消息，并将完整游戏文档等比缩放、居中放入视窗。iframe 首次适配后发生的真实内容增高或缩短仍必须被接受；仅浏览上下文宽高回灌或内容宽高未变化时保持当前状态，不触发重复渲染。
+- 窗口或中央区域尺寸变化后必须重新测量和适配；内容已经放得下时保持 `1:1`，不得无故放大。游戏文档宽高超过视窗时缩小整体画面，不显示 iframe 横向或纵向滚动条，也不得用单纯裁切替代完整展示。尺寸桥以根布局 `ResizeObserver` 为主，并在页面可见时每 `500ms` 至多探测 `512` 个元素作为绝对定位溢出的低频兜底；探测截断时不得用部分样本下调尺寸，viewport 耦合的 `100vh / 100% / bottom / right` 布局也不得形成自反馈。相同测量结果去重，不监听整页属性、文本或子节点突变；桥不读取项目正文、不修改 manifest、游戏文件或运行业务状态。桥脚本只能注入到真实 HTML 标签上下文，不能把脚本、样式、模板或注释中的 `</body>` / `</html>` 文本误判为结束标签；省略结束标签的 UTF-8 HTML 仍需安全注入。

 - 数值修改立即写入当前项目的编辑态配置。
 - 当前已拉起的体验预览和测试切片不热更新；必须重新拉起后才能消费新值。
@@ -7189,8 +7189,8 @@

 - 路由决策：普通 AGC 登录后直接调用固定官方 origin 下的网站现役 `/api/editor/*`、`/api/assets/*` 与 `/api/runtime/external-generation/jobs/*`，不再要求用户配置 External Editor Base URL 或 `tnr_sk_...`。普通 release 的官方 origin 继续服从 2026-08-10 的 dev API 固定规则，本地 dev 使用配套代理。`/api/external/v1` 的 Bearer Developer API Key 契约保持独立且不接受网站 Access Token，只供第三方 Agent/CLI、独立 standalone game-chat release 与显式高级自定义模式；服务端不为普通用户自动签发、代管或下发 Developer Key。
 - UI 与 standalone 例外：普通 Launcher、工作台、已认证 debug game-chat 和运行时配置页不展示或维护 External Editor URL/Key。独立 standalone game-chat release 仍绕过 `AuthenticatedClient`，只能在用户显式配置其隔离 AppData 的高级 External v1 URL/Key 后使用云端画板能力；凭据缺失时明确不可用，不得回退到普通登录态、内置 Key 或隐式公共账号。
- 会话 CAS：WebView 登录、refresh、退出和换号通过窄 Tauri/Runner 协议同步 `userId + 短期 Access Token + authGeneration` 到 GUI/Runner 进程内存。generation 单调递增，只有不旧于当前值的安装/清除可以生效；每个业务请求在发出前冻结 `ownerUserId + authGeneration`，在响应解析、账本推进、媒体安装和正式项目提交前都重新核对。旧 generation 的迟到安装、响应或清除不得覆盖新账号，也不得把旧账号产物安装到新账号项目。
- 凭据边界：Access Token、refresh Cookie、Authorization 和 authGeneration 不进入 AppData、项目、manifest、生成账本、Agent prompt、conversation、Agent DB、trace、日志或普通错误；durable 账本只保存非敏感 ownerUserId。Runner IPC 只允许专用 session install/clear 消息携带 Token，普通生成/恢复命令参数继续不得携带 Access Token 或 Developer Key。
+- 会话 CAS：GUI 取得 owner OS 锁时产生随机 `owner epoch`，并持久化只含 `owner epoch + session revision` 的私有 claim。WebView 登录、refresh、退出和换号先单调推进 durable session revision，再以 `runner.attach_gui_owner` 同步 `userId + 短期 Access Token + authGeneration`；Runner 只接受 epoch/revision 与 durable claim 完全一致的 attach。同一 epoch 内 generation 仍单调递增，只有不旧于当前值的安装/清除可以生效；新 GUI epoch 则可替换旧进程留下的更高 generation。每个业务请求在发出前冻结 `ownerUserId + authGeneration`，在响应解析、账本推进、媒体安装和正式项目提交前都重新核对。旧 epoch/revision/generation 的迟到 attach、响应或清除不得覆盖新账号，也不得把旧账号产物安装到新账号项目。
+- 凭据边界：Access Token、refresh Cookie、Authorization 和 authGeneration 不进入 AppData、durable claim、项目、manifest、生成账本、Agent prompt、conversation、Agent DB、trace、日志或普通错误；durable claim 只保存非敏感 epoch/revision，durable 账本只保存非敏感 ownerUserId。Token 只允许随与 durable claim 完全匹配的 `runner.attach_gui_owner` 进入 Runner 内存；旧 `platform.session.install/clear` 不再是授权入口，普通生成/恢复命令参数继续不得携带 Access Token 或 Developer Key。claim 缺失、不可读或失配时 Runner 必须立即清空平台会话并阻断 Runtime 请求；同步失败必须隔离或停止旧 Runner，不得在 GUI 已切换后继续使用旧账号权威。
 - 401/refresh：普通模式首次 `401` 进入当前 authGeneration 的全局单飞 refresh；其它请求等待同一 Promise，但各自 deadline、取消和账号归属独立。refresh 成功只在原 generation/owner 仍当前时以更高 generation CAS 发布新 Token，然后每个调用最多使用原 endpoint、原始请求字节和原 `Idempotency-Key` 重试一次。refresh 失败、账号已切换或重试仍为 `401` 时停止网络并保留原 operation；`403` 表示当前账号权限不足，不触发 refresh。高级 External v1 模式只允许用户修正自己的 Developer Key，并继续原 operation。
 - Durable 身份与换号：普通账本身份固定为 `official-platform-v1 + 官方 origin + ownerUserId`，高级账本身份固定为 External service origin，二者均不绑定可轮换 Token/Key。退出或换号会提升 generation、中止并脱离旧请求；新账号对旧 owner 的 `prepared/accepted/running` 账本必须零 POST、零 GET、零下载、零安装、零归档，只有重新登录同一 owner 后才能恢复。`401/403/404`、网关错误或轮询超时不能在 owner 不匹配时证明旧 operation 的终态。
 - 幂等与站内响应：`prepared` 只可精确重放账本冻结的原 endpoint、原始正文和原幂等键；`accepted/running` 只查询原 operationId。Access Token/Key 轮换、refresh、重启、退出或换号都不得创建替代 operation、修改正文或重新扣费。站内生成适配 `200 + queueState.operationId`、inline 完成和 `job` 状态包装；External v1 继续固定 `202 + operationId`，两者共享相同 owner、计费、稳定引用与本地事务门禁。
@@ -14363,6 +14363,31 @@
 - 素材生成确认、离开确认和旧服务身份确认沿用现有独立 modal，不在当前面板下方追加内容。modal 打开后焦点必须进入对话框，并同时隔离工具栏、画布视口、缩放/小地图、状态区和并存操作层，使背景从键盘焦点顺序与 accessibility tree 中退出。
 - `Tab` / `Shift+Tab` 必须在当前 modal 内双向循环；非异步 pending 状态允许 `Escape` 安全关闭。关闭后优先恢复到原触发器，自动弹出的 modal 则回退到可操作的工具栏入口，不能把焦点遗留在已卸载节点或被隔离背景中。

+## 2026-08-23 AGC 本地资源与 External Editor 账号绑定分离
+
+- 权威边界：本地项目 ID、manifest asset、正式本地文件和内容摘要属于设备上的本地项目；`canvasProjectId / resourceId / assetObjectId / objectKey` 属于具体 External Editor 服务 principal。manifest 中现有远端字段继续保留生成来源，不再承担“当前账号可编辑句柄”，本轮不修改共享 manifest schema。
+- 私有投影：统一在 `.agent/runtime/external-editor-bindings/` 持久化 active binding。项目 binding 按服务 origin、平台 userId 或 Developer Key 摘要以及本地 `projectId` 分区；资源 binding 再绑定远端项目、本地 asset ID、源 SHA-256、媒体类型和 canonical asset kind。sidecar 不保存 Token、Key、Cookie、Authorization、签名上传表单、媒体正文或绝对路径。
+- binding 完整性与并发：lookup key 与稳定 payload 内容指纹分开校验，远端 project/folder/resource/object ID、object key 和尺寸的任一改写都必须失败关闭。同一 `本地项目 + principal` 的首次 binding 建立串行化覆盖复读、远端创建与安装，并发生成不得各自创建画布或留下孤儿项目。
+- binding schema 迁移：当前 project/resource sidecar 显式为 v2 且 payload fingerprint 必填。旧 v1 文档仅能由独立 `deny_unknown_fields` wire 结构命中，在 key、principal、local project/source、remote 引用、object key、时间和尺寸等现役不变量通过后计算指纹并原子回写 v2；未知字段或身份 / source / 路径篡改均失败关闭且不回写。
+- 切号语义：账号 B 打开账号 A 曾生成资源的同一本地项目时，不访问、迁移或覆盖 A 的私有画布；B 从本地正式文件在自己的远端项目重新上传、confirm、登记并形成独立 binding。切回 A 时复用 A binding。项目标题只用于远端展示，不能作为同名项目的权威关联；项目改名不换 binding。
+- Runner 切号权威：Runner 协议 v7 规定 GUI owner 锁每次取得都创建新的随机 owner epoch，每次平台会话变更先推进 durable session revision claim。Runner 只能通过与该 claim 完全匹配的 `runner.attach_gui_owner` 替换会话，因此新 GUI 即使从较低 `authGeneration` 开始也能取代旧进程权威。claim 失配时立即清空 Runner 平台会话并阻断 Runtime，旧 `platform.session.install/clear` 只失败关闭而不再变更权威；GUI 与 Runner 同步失败时必须隔离或停止旧 Runner。
+- renderer / native 会话提交：renderer auth generation 只负责 UI 转换和迟到读取失效，native install / clear 使用独立只增 generation 并在同一串行队列执行。登录、refresh、当前用户查询与 native commit 共用请求前冻结的 API origin，refresh singleflight 按 origin 分区；入队前冻结 `user + token + origin`。候选账号只在 native 成功且仍属当前 auth generation 时提交；期望权威显式表示为 account 或 `null`。迟到 native 完成必须以更高 generation 对账回当前期望权威，对账失败清空 renderer committed 会话与 Token。
+- stale refresh 决策：queued commit 的 expected generation 过期时，early return 先恢复 renderer 当前 committed / desired Token。旧账号的 refresh 失败在当前 owner 已变更时只返回 `stale`，不发送会让 `AuthenticatedClient` 清空新账号的 failed 结果，也不执行新账号 native clear。
+- 在途边界：资源编辑、素材画布生成和 Agent 美术生成的 `prepared / accepted / running` 账本继续锁定发起 principal。账号切换后只能停止请求并保留原 operation 供切回或对账，不得把在途副作用迁移到新账号，也不得重建正文或重复 POST。只有尚未提交远端生成的新操作可以为当前账号建立新的项目和资源 binding。
+- 在途会话复验：提交返回 `operationId` 后先持久化 accepted 身份，再在每次 poll、download 和本地 commit 前校验冻结会话；同步本地 commit 必须持有冻结会话租约，使切号与安装线性化。Tauri 手工生成入口也必须使用稳定的 durable operation slot，不能退化成临时幂等键。切号后不得继续旧账号网络或把旧账号结果安装到本地项目。
+- 账本 owner 线性化：资源编辑与素材画布的 owner 绑定、服务身份指纹 / 挑战和确认写入，均在同一冻结 platform session 租约下完成，且账本已有 owner 必须精确匹配 `userId + api origin`。Developer Key 账本保持 `owner=null`；请求 / 确认挑战的直接命令调用也不具备跨 owner 写入权限。
+- 恢复投影：资源恢复列表持有当前 session 租约扫描，远端账本只对精确 owner `userId + api origin` 可见；未绑 owner 的 Developer / legacy 远端账本与 owner 不完整账本均失败关闭，纯本地编辑仍可见。renderer auth generation 变更同步作废恢复 read epoch，清空列表、挑战和动作状态，迟到读取不得恢复旧账号投影。
+- Direct 审计对账：图集只读恢复已完成 file + manifest 登记后，`asset.register` 追加审计一旦成功或结果未知，后续登记 / binding 失败都保留 file、manifest 和已落盘 audit，统一进入 `reconciliation-required`。禁止为了伪造原子性而回滚 manifest、删文件、重试未知审计或重新生成。
+- 账本迁移：资源 canonical 身份从历史 manifest `resourceId` 收口到本地 asset ID 时，旧账本只在 source asset、路径和 SHA-256 一致时可白名单恢复；新请求仍只信任本地 canonical 身份。
+- 集成边界：`resource_editor`、素材画布参考准备、`canvas.asset_generate` 的 art-spec 派生和直连只读恢复统一消费当前 principal binding；PR 176 rebase 后必须删除或整合其局部 canonical cache，不能保留第二套账号身份系统。External v1 的项目、素材目录和项目资源创建接口新增可选 `Idempotency-Key` 请求头并同步 OpenAPI；客户端用 binding key 派生稳定值，服务端按 `owner + 接口命名空间 + key` 生成稳定 ID，同键同正文返回原记录、同键异正文冲突。
+- 验收：至少覆盖 A 生成到本地后切 B 重登记、B 请求零 A 远端 ID、重启后复用 B、切回 A 复用 A、两个同名本地项目隔离、项目改名不漂移、源 SHA 或 kind 变化重登记、A 在途任务切 B 零网络，以及 sidecar 零凭据和身份篡改失败关闭。
+
+## 2026-08-23 AI 游戏运行视窗按预览文档实际尺寸自适应
+
+- 背景：项目开发工作台的中央运行视窗尺寸小于部分生成游戏的页面布局高度时，滚动条来自 loopback iframe 内部；宿主只隐藏 overflow 会直接裁掉标题、Canvas 或控制区，不能满足完整试玩。
+- 决策：客户端本地 preview server 为 UTF-8 HTML 注入固定同源尺寸桥；注入器按真实 HTML tokenizer 边界保守处理注释异常结束、DOCTYPE 引号、script escaped / double-escaped、raw-text、template、plaintext、foreign content 与重复 `src`，省略结束标签时只在已证明安全的文档位置注入。桥通过根节点 `ResizeObserver`、页面 load、窗口 resize 与字体就绪重新测量；页面可见时以 `500ms` 低频兜底探测至多 `512` 个元素边界，探测截断时不采用可能低估的部分样本，并排除随 viewport 同步变化的布局自反馈。它不订阅整页 DOM 突变，并只在尺寸元组真实变化时上报文档与浏览上下文宽高。宿主只接受当前 iframe source 与当前授权 loopback origin 的固定版本消息，按实际内容和可用容器计算最大为 `1` 的等比缩放并居中显示；首次缩放后仍接受内容宽高真实变化，重复内容尺寸或仅 viewport 回灌不更新状态，容器 resize 后重新以原生视口测量。运行视窗不再提供 iframe 横纵滚动条，内容适配不改游戏文件、manifest、PreviewRegistry 或运行业务状态，非 UTF-8 HTML 保持原样。
+- 验证：前端纯函数覆盖无需缩放、纵向超高缩放、首次缩放后的增高 / 缩短、重复内容尺寸去重、过期 viewport 与非法消息；Rust preview server 测试锁定尺寸去重、无全页 MutationObserver、低频有界探测、截断保护、固定 body 与 viewport 耦合布局不振荡、真实 HTML 上下文注入、注释异常结束、DOCTYPE 引号、script escaped / double-escaped、raw-text / template / plaintext / foreign content、省略结束标签、大小写结束标签、重复 `src` 和幂等注入；再以桌面最小窗口和更高窗口人工确认完整画面、动态内容变化后仍适配、无纵向滚动条且指针 / 键盘交互仍可用。
+
 ## 2026-08-23 Direct Codex 显式重生成与切片一等资源

 - 决策：`taonier_prepare_game_art` 使用 `reuse-or-create | regenerate` 两态合同；旧调用缺省复用，只有用户显式重做或换风格才允许重生成。`regenerate` 只绕过本地完整包复用，不绕过未决 External Editor operation；旧账本 prompt 与本次 prompt 不一致时必须进入结果未知/对账，零新 POST。
@@ -4840,6 +4840,24 @@
 - 处理：先查 kernel journal 的 `Memory cgroup out of memory` 和目标容器 ID，再把本地/预发完整容器 SpacetimeDB 上限统一为 `2g`；保留 page pool 限制。不要只增加 publish 重试，也不要把 `/healthz` 或首页改成数据库就绪探针。
 - 验证：用新空卷完成模块 publish、五服务启动和 Web/API smoke，并确认容器未 OOM、SpacetimeDB 与 API/Nginx 最终 healthy。

+## 同一本地项目切换账号后不能继续信任 manifest 远端 ID（2026-08-23）
+
+- 现象：本地资源文件仍存在，但账号 A 生成后切到账号 B，快速编辑、GIF/视频派生、art-spec 下游生成或直连恢复提示画布不存在、无权限或资源不属于当前项目；原请求重试仍失败。
+- 原因：本地 manifest 只有一组 `source.canvasProjectId / resourceId / assetObjectId`，旧实现把它同时当作历史来源和当前账号可编辑引用。新的 operation 虽已绑定 B，却会把 A 的 project/resource/object 身份配合 B Token 发出；另一部分链路又把 A 的画布 ID 与 B 按标题选出的项目严格比较。
+- 处理：manifest 远端字段只保留历史 provenance。所有远端编辑和派生先解析 `.agent/runtime/external-editor-bindings/` 中当前 principal 的项目/资源 binding；不存在时从本地正式文件按 asset ID、SHA-256、媒体类型和 canonical kind 在当前账号重登记。禁止按标题、manifest ID 或其他账号 committed ledger 自动采纳远端对象。A 的在途 operation 继续留在 A，B 只能开始自己的新操作。
+- 并发与升级陷阱：首次 binding 不能用无锁的“先查后建”，否则两个 generation 会各自创建远端项目/目录；进程锁只能压住当前存活客户端，远端创建还必须携带由 binding key 派生的稳定 `Idempotency-Key`，关闭“响应已返回但 sidecar 未落盘”时重启重复创建的窗口。canonical ID 变更也不能只改新请求指纹；必须用本地 asset、路径和内容摘要白名单恢复旧 accepted/committed 账本，避免升级后已付费结果永久无法恢复。
+- binding wire 升级陷阱：在仍标 v1 的 struct 上直接新增必填指纹，会让所有已有本地项目的 binding 反序列化失败，重现“画布项目丢失”。必须升为新 schema，用独立严格 legacy wire 只迁移完整通过现役不变量校验的旧文档；不能用 default 缺失字段或在身份校验前回写。
+- 在途切号陷阱：只在首次 POST 前校验 session 不足以锁定 principal。获得 `operationId` 后必须先落盘，后续每次 poll、download 和本地 commit 都要复验原 session；同步 commit 的“先校验再写入”仍有切号竞态，必须用会话租约把校验与本地安装线性化。手工 Tauri 入口若使用临时幂等键，也会在 202 后切号时丢失恢复身份。切号后继续用 A Token 轮询或安装 A 结果同样是账号边界缺失。
+- renderer / native 两阶段陷阱：只用一个 generation 同时表示 UI 转换和 native CAS，或在 Rust 确认前先替换 committed Token，会让迟到 install / clear 把新账号覆盖回旧账号。正确做法是 auth generation 与 native 只增 generation 分离，所有 native mutation 串行，入队前冻结 token + origin + user，并持续以显式 account / `null` 期望权威对账迟到完成。对账失败不能恢复未确认候选会话，而要清空 committed 会话与 Token。
+- auth origin 竞态陷阱：只在登录前持久化服务器选择不等于冻结事务 origin；请求 A 在途时若 UI 改为 B，返回的 A Token 可能被安装到 B origin。登录、hydrate 与 refresh 必须在首个请求前冻结 origin，让 HTTP 链与 native commit 共用该快照；同时按 origin 隔离 refresh singleflight，不能让 A 的 Promise 被 B 复用。
+- stale refresh 陷阱：请求在入队前写入候选 Token 后，若 queued commit 直接因 generation 过期返回却不恢复 renderer authority，本地请求会继续携带错账号 Token。另外，A refresh 失败晚于 B 登录成功时，若仍向全局发布 failed，`AuthenticatedClient` 会把 B 误登出。所有 stale early return 先恢复当前 committed / desired Token；旧 owner 的迟到 refresh failure 只返回 `stale`，不 clear、不发布 failed。
+- 账本写入租约陷阱：只在进入命令时读一次当前账号，仍可能在 owner 绑定、服务身份指纹 / 挑战或确认落盘前切到 B，从而向 A 账本写入 B 身份。这些写入必须持同一冻结 platform session 租约并精确校验 ledger owner；公开的 request / confirm 命令也必须自身完成 owner 门禁，不能依赖调用方曾经走过恢复流程。
+- 恢复列表泄漏陷阱：项目相同不代表账本对当前账号可见。如果列表只按 project / phase 扫描，切 B 后会展示 A 的 operation，迟到回包还可能把已清空的列表重新写回。扫描必须持当前 session 租约并按完整 owner `userId + api origin` 过滤；未绑 / 不完整的远端账本隐藏，纯本地编辑保留。renderer 还要用 auth generation 使恢复 read epoch 失效并清空相关操作状态。
+- 追加审计回滚陷阱：Direct 恢复中 `asset.register` 是 append-only 审计，返回错误不能证明 append 未持久。若 file / manifest 已落盘且审计成功或结果未知，删文件或回滚 manifest 会创造“审计已存在、资源却消失”的第二种不一致，重试还可能复制审计或重新扣费。应保留 file + manifest + audit 现场并标记 `reconciliation-required`；后续 binding 失败也使用同一语义。
+- Runner 跨 GUI 陷阱：WebView 的 `authGeneration` 会随 GUI 进程重启从较低值重新开始，但 busy Runner 可能仍持有旧 GUI 的高 generation。只用 generation CAS 会把新账号安装误判为过期；只把 OS owner 锁当作授权，或保留独立 `platform.session.install/clear` 入口，又会让 Runner 在单次 IPC 丢失后继续使用旧账号。Runner 协议 v7 由 owner 锁创建随机 epoch，每次会话变更先推进 durable revision claim，并且只允许与 claim 完全匹配的 `runner.attach_gui_owner` 安装会话。Runner 要持续比对 claim，失配立即清空平台会话并拒绝 Runtime 请求；GUI 同步失败还要隔离或停止旧 Runner，不能只向前端报错。
+- 验证：用真实平台会话 fixture 覆盖 A→B→重启→A，逐个断言 B 的 URL、请求体和稳定引用中没有 A 的 project/resource/object ID；另测同名 localProjectId 隔离、改名不漂移、源摘要变化、非 refine 参考、视频 committed objectKey、art-spec 派生以及在途 operation 切号零网络。Runner 回归还要覆盖高 generation 旧 epoch 被低 generation 新 epoch 正确替换、迟到旧 epoch/revision attach 失败关闭、claim 改写或同步失败后旧 Runner 零 Runtime 请求。Developer Key fixture 不能替代平台账号隔离证据。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/external_editor_bindings.rs`、`project/resource_editor.rs`、`project/asset_canvas/generation.rs`、`agent/generation/canvas_generation.rs`、`agent/direct_runtime.rs`。
+
 ## Direct 美术工具不能把“包存在”当成“本次已生成”（2026-08-23）

 - 现象：用户明确要求重做美术或切换游戏主题，工具仍立即返回 `assets/art-spec.png`、`assets/direct-game-background.png`、`assets/art-spritesheet.png`；新需求没有 Provider operation，游戏继续使用旧图。切片虽然已经落盘，也可能不出现在资源管理或工具结果中。
@@ -413,7 +413,17 @@ Agent Runtime 负责：
 - 2026-07-10 补充：后台任务工具箱已加入 `project.restore`。Agent 可在 diff 或自检发现本轮修改走偏后请求恢复到指定 checkpoint；Runtime 复用 `project.restore` 权限策略和项目写锁，observation 只返回 checkpoint id、恢复文件数和删除文件数，不返回本机绝对路径。默认确认策略下不会静默回滚用户项目。
 - 2026-07-10 补充：单 Agent 聊天和后台 planning prompt 会读取同一个 Agent 的 Runtime 连续上下文，把本 Agent 最近 status / phase / runId / 当前任务 / 下一步、最近回复、计划、观察、最近 3 条工具动作、最近事件、最近 3 条任务记录和工具策略摘要带入下一轮推理；上下文按规范 taskId 隔离，不读取其他 Agent 的 runtime 文件，并在进入 prompt 前过滤密钥和本机绝对路径。新后台 run 启动时会继承本 Agent 上次 `recentToolCalls` 和 `lastResponse`，让多轮任务不丢失结构化行动证据。
 - 2026-07-10 补充：后台任务工具箱已加入 `preview.start`。Agent 可在 loop 中自行请求启动当前项目的本地 HTTP 预览；Runtime 会复用 `preview.start` 策略、项目写锁、共享 `PreviewRegistry`、manifest 预览状态、`.agent/logs/preview.log` 和 run trace 追加逻辑，并把 `agent.runtime.preview.start` 写入 `.agent/agent.db`。该 observation 只向 LLM 返回 localhost URL 与端口，不返回用户项目绝对路径。
- 后台任务工具箱提供 `canvas.asset_generate`。Agent 在 loop 中给出素材 prompt、`outputPath`、比例、尺寸、kind 与展示名；普通已认证客户端通过固定官方 origin 的 `/api/editor/*`、`/api/assets/*` 和 `/api/runtime/external-generation/jobs/*` 调用平台，独立 standalone game-chat/显式高级模式才通过 `/api/external/v1/*` 与自备 Developer Key 调用。生成前按本地项目名称创建或复用同名画布项目和同名素材库目录，请求必须携带 `projectId + assetFolderId + canvasCompletion`，生成结果同时进入平台画布、素材库和本地项目。canonical 视觉 DAG 固定为：`art-director` 用图片生成 `kind=spec` 生成 `assets/art-spec.png`；`design-foundation` 精确引用该 resourceId，用图片生成 `kind=ui-design` 生成 `assets/ui-prototype.png`；`art-asset-plan` 使用同一 resourceId 和具体 `iconDescriptions` 调用图标 spritesheet 生成，产出真实透明的 `assets/art-spritesheet.png`。Runtime 在 POST 前把调用模式、相对 endpoint、精确请求体、SHA-256 与稳定 `Idempotency-Key` 原子写入 `.agent/runtime/canvas-generation-requests/` 私有账本并回读一致；普通模式还冻结 `official-platform-v1 + 官方 origin + ownerUserId`，高级模式冻结 External service origin，两者均不保存 Token 或 Key。`accepted` 账本只恢复 GET；`prepared` 表示首次提交结果未知，只允许使用原 endpoint、原始 JSON 字节与同一键恢复 POST，不得重建远端项目/目录、重组正文或分配新键。普通模式站内响应兼容 `200 + queueState.operationId`、inline 完成和 `job` 状态包装；高级 External v1 固定 `202 + operationId`。生成 POST 使用独立三十五分钟等待预算；game-chat 的两次串行生成纳入父 run `4200` 秒软预算与 `4500` 秒总截止。轮询超时、临时鉴权或网关错误只保留原 operation 并在恢复时继续；结果损坏、状态损坏、透明派生失败或远端完成后的本地提交失败进入对账。`postprocess-failed-source-preserved` 不得登记为透明图集或自动重试；其它 general warning 保持 completed 并与 `sliceWarning` 分别展示。UI extraction 只处理已有带标注 UI 图，不属于这条 DAG；图集不得回退到普通生图。UI 原型 prompt、`generationInputs.artSpec` 和 `ui-prototype.v2` 验收必须从当前项目玩法合同提取 HUD、可玩区域、关键实体、操作、失败/重开与移动布局。旧正式图不合格时只返回 `needs-repair`；Supervisor 认领后由原 owner 使用 `replaceExisting=true` 原位替换。凭据不进入项目文件；幂等键只进入受权限约束的私有生成账本，不进入 observation、manifest、agent.db 或日志。
+- 后台任务工具箱提供 `canvas.asset_generate`。Agent 在 loop 中给出素材 prompt、`outputPath`、比例、尺寸、kind 与展示名；普通已认证客户端通过固定官方 origin 的 `/api/editor/*`、`/api/assets/*` 和 `/api/runtime/external-generation/jobs/*` 调用平台，独立 standalone game-chat/显式高级模式才通过 `/api/external/v1/*` 与自备 Developer Key 调用。生成前按当前服务 principal 与本地 `projectId` 的私有 binding 创建或复用远端画布项目和素材库目录，请求必须携带 `projectId + assetFolderId + canvasCompletion`，生成结果同时进入平台画布、素材库和本地项目。canonical 视觉 DAG 固定为：`art-director` 用图片生成 `kind=spec` 生成 `assets/art-spec.png`；`design-foundation` 精确引用该 resourceId，用图片生成 `kind=ui-design` 生成 `assets/ui-prototype.png`；`art-asset-plan` 使用同一 resourceId 和具体 `iconDescriptions` 调用图标 spritesheet 生成，产出真实透明的 `assets/art-spritesheet.png`。Runtime 在 POST 前把调用模式、相对 endpoint、精确请求体、SHA-256 与稳定 `Idempotency-Key` 原子写入 `.agent/runtime/canvas-generation-requests/` 私有账本并回读一致；普通模式还冻结 `official-platform-v1 + 官方 origin + ownerUserId`，高级模式冻结 External service origin，两者均不保存 Token 或 Key。`accepted` 账本只恢复 GET；`prepared` 表示首次提交结果未知，只允许使用原 endpoint、原始 JSON 字节与同一键恢复 POST，不得重建远端项目/目录、重组正文或分配新键。普通模式站内响应兼容 `200 + queueState.operationId`、inline 完成和 `job` 状态包装；高级 External v1 固定 `202 + operationId`。生成 POST 使用独立三十五分钟等待预算；game-chat 的两次串行生成纳入父 run `4200` 秒软预算与 `4500` 秒总截止。轮询超时、临时鉴权或网关错误只保留原 operation 并在恢复时继续；结果损坏、状态损坏、透明派生失败或远端完成后的本地提交失败进入对账。`postprocess-failed-source-preserved` 不得登记为透明图集或自动重试；其它 general warning 保持 completed 并与 `sliceWarning` 分别展示。UI extraction 只处理已有带标注 UI 图，不属于这条 DAG；图集不得回退到普通生图。UI 原型 prompt、`generationInputs.artSpec` 和 `ui-prototype.v2` 验收必须从当前项目玩法合同提取 HUD、可玩区域、关键实体、操作、失败/重开与移动布局。旧正式图不合格时只返回 `needs-repair`；Supervisor 认领后由原 owner 使用 `replaceExisting=true` 原位替换。凭据不进入项目文件；幂等键只进入受权限约束的私有生成账本，不进入 observation、manifest、agent.db 或日志。
+- External Editor 的远端项目和资源属于服务 principal，不属于本地项目的跨账号身份。`.agent/manifest.json` 中 `source.canvasProjectId / resourceId / assetObjectId` 只记录生成来源，不得作为当前登录账号的 active editable binding。客户端在 `.agent/runtime/external-editor-bindings/` 私有保存账号级投影：项目键至少包含服务 origin、principal 和本地 `projectId`，资源键再包含远端项目、本地 asset ID、源文件 SHA-256、媒体类型与 canonical asset kind；值保存该 principal 下的远端 project/folder/resource/object 身份。Token 轮换继续复用同一 principal binding，账号、服务、源字节或 canonical kind 变化必须重新建立；同名本地项目和项目改名不得参与权威匹配。
+- binding 的 lookup key 与稳定 payload 内容指纹分开校验；远端 project/folder/resource/object ID、object key 或尺寸被单独改写时必须失败关闭。同一本地项目和 principal 的首次项目 binding 建立必须串行化覆盖“复读 binding → 必要的远端创建 → 原子安装 binding”，不得因并发任务创建孤儿画布。External v1 项目、素材目录和项目资源创建请求携带由 binding key 派生的稳定 `Idempotency-Key`；服务端在 owner 与接口命名空间内生成稳定 ID，并允许同键同正文安全重试，使远端响应后、本地 sidecar 落盘前崩溃也不会重复创建。
+- 当前 binding wire schema 为 v2，payload fingerprint 必填。已落盘的 v1 project/resource JSON 只能经独立严格 wire 结构读取，在 lookup key、principal、本地 source、远端字段、对象键、时间和尺寸等不变量全部通过后重算指纹并原子回写 v2。不得用 `serde(default)` 把未知或篡改文档混入迁移。
+- 已完成的本地正式资源以本地文件和 manifest asset 身份为权威。切换账号后，当前账号没有资源 binding 时，必须从本地字节上传、confirm 并登记到当前账号的远端项目后再编辑或派生；任何请求都不得把旧账号的 `canvasProjectId / resourceId / objectKey` 与新账号 Token 组合。新绑定不得覆盖历史来源，也不得迁移或删除旧账号远端对象。已经 `prepared / accepted / running` 的生成或编辑 operation 仍冻结原 principal、原正文和原 operation；切换账号只能停止恢复并保留对账证据，不能改绑、重放或重复扣费。
+- 远端提交返回 `operationId` 后先持久化 accepted 身份，再在每次 poll、download 和本地 commit 前复验冻结会话；同步本地 commit 持有冻结会话租约，使切号只能发生在完整安装前或安装后。Tauri 手工生成同样使用稳定的 durable operation slot，不得使用进程内临时幂等键。历史资源编辑账本从 manifest 远端 resource ID 迁移到本地 asset ID 时，只允许在本地 asset、路径和内容摘要仍一致时兼容旧指纹，新请求不得恢复信任 manifest 远端 ID。
+- renderer 中的 auth generation 只用于标记当前 UI 身份转换并使迟到读取失效；发给 Rust / Runner 的 native generation 是另一条只增不减的序列，不得用可重置的 renderer generation 直接充当 native CAS。所有 native install / clear 串行入队；登录、refresh、当前用户查询和 native commit 必须共用首个请求前冻结的同一 API origin，refresh singleflight 也按 origin 隔离。提交入队前冻结候选 `accessToken + api origin + user` 快照，并显式记录期望权威是具体账号还是 `null`。候选快照只在 native 确认成功且 auth generation 仍当前时成为 committed 会话；迟到的 install / clear 完成必须用更高 native generation 把 Rust / Runner 对账回当前期望权威，对账失败则清空 renderer 的 committed 会话与 Token 并失败关闭。
+- queued commit 发现 expected auth generation 已过期时，必须在 stale early return 前把 renderer Token 恢复到当前 committed / desired authority，不得留下入队前冻结的候选 Token。旧账号 refresh 的迟到失败若已不属于当前账号，只能投影为 `stale`；不得进入当前账号的 refresh-failed / clear 链路，也不得使 `AuthenticatedClient` 登出已成功切换的新账号。
+- 资源编辑与素材画布账本的 platform owner 绑定、服务身份指纹 / 确认挑战和确认结果写入，必须全程持有同一冻结 platform session 租约，并要求账本已有 owner 与该 `userId + api origin` 精确一致；直接调用确认命令也不得越过 owner 校验。Developer Key 路径保持 `owner=null` 且不伪造 platform session 租约。
+- 资源恢复列表是当前 principal 的私有投影：列举期间持有当前 platform session 租约，远端账本只在 owner `userId + api origin` 完整且精确匹配时可见；未绑 owner 的 Developer / legacy 远端账本和 owner 不完整账本失败关闭，纯本地编辑仍对项目可见。renderer 在 auth generation 变更时立即使恢复读取 epoch 失效、清空旧列表 / 挑战 / 在途动作并关闭面板，迟到回包不得重新投影旧账号条目。
+- Direct 只读恢复中，本地文件与 manifest 登记成功后，`asset.register` 追加审计的结果若为成功或无法判定，都必须保留当前 file + manifest + 已追加的 audit 现场；后续账号资源 binding 安装失败同样保留这些可证事实。该路径统一返回 `reconciliation-required`，禁止回滚 manifest / 删除文件，也禁止在无法证明审计未落盘时重试登记或重新生成。
 - 2026-08-03 durable 恢复补充，2026-08-04 扩展 `prepared`：`prepared / accepted / legacy-completed` 恢复必须先从私有账本读取持久化的画布 ID、素材目录 ID、画布名、生成提示词、route、kind 与引用资源；`prepared` 只原样恢复同一逻辑 POST，`accepted` 只查询既有 operation。不得在读取账本前重建请求、重新列举或创建远端项目/目录，也不得让本地输出路径漂移挡住恢复。显式“继续/恢复”复用原 action、pending、provider batch 与生成账本身份，不创建 successor 请求或新幂等键。恢复执行和后续 continuation 使用独立 Tokio task 栈边界，同时继续持有原 Agent lock。终态清理固定先删 generation / parallel 附属 sidecar，最后删 pending 身份锚点；历史孤儿只有所属任务已明确 completed/cancelled 时可自动清理，活动、未知或 `needs-reconciliation` orphan 必须保留并失败关闭。
 - 生成账本必须绑定调用模式与服务身份：普通模式为固定官方 origin + ownerUserId，高级 External v1 模式为显式 service origin；Access Token 或 Developer Key 只负责当前请求授权，轮换不得改变已有 operation 的归属。退出或换号提升单调账号 generation，中止并脱离旧请求；旧 owner 账本在新 owner 下禁止 POST、GET、下载、安装和归档，只有重新登录同一 owner 后才能恢复。绝对 signed URL、query/fragment 和未知扩展字段不得进入项目账本，只有安全相对路径或 objectKey 可作为 durable 下载引用。accepted operation 明确 failed 时也保留账本，直到 pending observation 和 Provider batch 成员终态持久化后再按统一清理链删除。首次请求结果已经未知后，鉴权或其它非成功响应不能证明原请求未入队，必须保留原账本。生成账本根目录、扫描与删除使用受控路径解析逐级拒绝符号链接，非法控制路径失败关闭。
 - 2026-07-10 补充：后台任务工具箱已加入 `task.list`。Agent 可在 loop 中读取 manifest 任务图、每个 seed task 的状态 / 依赖 / 产物交接，以及按依赖计算的 `readyTaskIds`；Runtime 复用 `task.list` 项目权限策略，策略要求确认或拒绝时只返回策略 observation，不向 LLM 暴露任务图细节。
@@ -424,6 +434,7 @@ Agent Runtime 负责：
 - 2026-07-10 补充：后台任务工具箱已加入 `agent.delegate`。Agent 可在 loop 中把明确任务投递到另一个 Agent 的独立后台队列，复用目标 Agent 原有锁和 pending drain 语义；同一目标 Agent 串行，不同目标 Agent 可并行。该工具受 `agent.delegate` 策略保护，策略要求确认或拒绝时不会写目标对话、不会启动目标后台任务，也不会写 `agent.runtime.agent.delegate` 审计记录。
 - 2026-07-10 补充：`agent.delegate` 已形成可恢复的父子任务闭环。`delegationId` 由 durable pending action 的 `actionId` 派生，子任务记录会保存 `parentAgentId / parentRunId / delegationId`，终态记录额外保存经过统一凭据清洗和安全截断的 `terminalDetail`；同一委派的提交和回执分别受 delegation 级 OS 文件锁保护，同一目标 Agent 的 runId 分配与 pending 追加还受任务账本 OS 锁保护。子任务进入 `completed / failed / cancelled / budget-exhausted` 任一终态时，Runtime 按 `delegationId` 幂等生成且至多生成一次 `agent.delegate.result` 回执，失败、排队或活跃取消、预算耗尽都必须回传，不能只覆盖成功。回执会向父 Agent 既有队列追加固定 runId、`source=agent-delegate-receipt` 的续跑任务，把完整的已清洗 `terminalDetail` 交回父 run，不再只保留 80 字符 UI 摘要；回执 prompt 明确禁止重复同一委派，排队期间不提前写入父会话，真正开始执行时才幂等落盘，用户消息或回执消息落盘失败时不会进入 LLM。回执任务保留父 run 关联，并在真正开始或恢复前再次检查父 run 状态，关联缺失或父 run 不存在时失败关闭；该续跑仍受父 Agent 原有 FIFO、per-Agent OS 锁、权限确认、取消、恢复和 `needs-reconciliation` 屏障约束，不直接重入父 run、不插队、不新增独立 worker；父 run 已取消或普通失败时只保留 suppressed receipt 审计，不自动复活，父 Session 归档与切换会被未结束委派阻止，极端归档竞态下回执回落到父 Agent 当前可写 Session。恢复先恢复 pending action / reconciliation 屏障，再扫描“子任务终态已落盘但回执未提交”的窗口并补齐缺失回执；`needs-reconciliation` 本身不回执，只有人工核对后最终取消才回传 `cancelled`。
 - 历史记录（已由 V1.1 独立 Runner 替代）：Runtime 最初通过 `resume_game_creator_agent_runtime_tasks` 把本地 JSONL 队列重接到当前 App 进程。当前恢复入口仍保留权限、任务顺序和 `agent.runtime.background_task.recovered` 审计语义，但实际由独立 Runner 接管原 run / session；已发出的上游 LLM 请求仍不能从网络中间点续传。2026-07-27 起，Runner 归 Tauri GUI 生命周期所有，同一 AppData 只允许一个 GUI owner。GUI 启动子进程会显式声明 `--gui-owner-required` 并在就绪后 attach owner；Runner 若在启动检查前已发现 owner 释放则直接失败，不得退化成 CLI-owned Runner。Runner 使用独立 watchdog 线程每 100ms 监控 owner OS 锁，不依赖服务端主循环继续推进；owner 丢失后先触发 1.5 秒共享 deadline 的 draining、Provider 中断和 process session 回收，若主循环或排空链路卡死则在 1.75 秒后由 Runner 自身进程安全硬退出并清理匹配 bootId 的 endpoint。GUI 客户端还必须把完整 `runner.attach_gui_owner` 参数作为绑定规范化 AppData 的进程内登记保存；`ensure_external_agent_runner` 无论复用既有 endpoint 还是启动新 Runner，都要在把 endpoint 交给 Runtime 写请求前按新 `bootId` 补登记。同一登记 generation 在同一 boot 上幂等，补登记失败不得记录成功 boot 且本次 `ensure` 失败关闭；未建立 GUI 登记的普通 CLI 不执行该重放。OS owner 锁与 watchdog 已成立只代表进程受 GUI 生命周期约束，不能替代事件 sink 等进程内附加能力的逐 boot 恢复。因此正常最终退出、panic、SIGKILL 和 setup 中途失败都不会再因 busy 或主循环卡死而残留后台进程。endpoint 缺失 / 读取失败必须结合 Runner 实例锁判断；GUI 客户端强制兜底在 Linux 使用 pidfd、Windows 使用稳定进程 handle。macOS 没有等价稳定句柄，客户端不得在 start identity 检查后按裸 PID 强杀，而由跨平台 Runner 自身 watchdog 提供硬退出兜底。旧 endpoint 缺 start identity 时，只有认证 ping 精确匹配 PID + bootId 才允许迁移 busy 旧 Runner。未完成任务保持 durable 状态并在下一次启动走 reconciliation / recovery，不能伪造 completed 或重放副作用。关闭单个 WebView / 子窗口和普通 CLI 退出不触发该行为，版本切换与人工命令仍可使用只关闭空闲实例的 `runner.shutdown_if_idle`。
+- 2026-08-23 Runner 协议 v7 GUI owner 会话权威补充：GUI 取得 owner OS 锁时产生随机 `owner epoch`，并在私有 AppData 持久化只含 `owner epoch + session revision` 的 claim；每次登录、refresh、退出或换号都必须先单调推进 durable session revision，再同步 Runner。`runner.attach_gui_owner` 是 Runner 接受平台会话快照的唯一授权入口；只有 attach 携带的 epoch/revision 与 durable claim 完全一致才可安装或清除会话，新 GUI epoch 可替换旧进程留下的高 `authGeneration`，不用可在新 WebView 重置的 generation 猜测进程所有权。Runner 在 claim 缺失、不可读或与当前 attach 身份失配时立即清空进程内平台会话，并阻断除重新 attach 及必要管理请求以外的 Runtime 工作；旧 `platform.session.install/clear` 协议不再是授权入口。GUI 会话同步未得到完整 attach 确认时本地变更必须失败，并隔离或停止旧 Runner；即使进程终止失败，claim 失配门禁也不允许旧账号继续发起 Runtime 请求。claim 不保存 Access Token，Token 只随当次受保护的 attach IPC 进入 Runner 内存。
 - 2026-08-05 GUI owner attachment 确认补充：登记参数必须保存 GUI manifest 事件接收端的真实 `event_sink_port` 与 `event_sink_token`，不得借用 actionId 等无关字段作为测试替身。每次 attach RPC 只有同时返回 `attached=true` 与 `eventSinkAttached=true` 才能把当前 `bootId` 标记为已登记；`eventSinkAttached` 缺失、为 false 或普通 RPC 失败都保持当前 boot 待重试。sink token 只留在私有进程内登记和 RPC 参数中，不进入日志、错误文本或公共状态。
 - 2026-07-10 补充，2026-07-16 由 V1.28 澄清：后台 planning 与预算内 final reply 使用专用最小上下文，只预置 Agent 身份、sessionId、runId、执行模式和工具策略；Agent 私有记忆、项目记忆、黑板、对话、资产、项目索引与文件正文只能经对应工具通过权限 gate 后作为 observation 进入下一轮。只有开发窗口的专业 Agent 前台直调可使用对应角色上下文；正式用户前台现已统一进入 `project-supervisor`。长黑板、记忆和对话按尾部截断，确保最新结论与最新定向消息优先保留。
 - 2026-07-10 补充，2026-07-16 由 V1.28 澄清：同一 Agent 的开发前台直调、流式调试和后台任务统一使用 `.agent/runtime/locks/<agentId>.lock` OS 文件锁。开发前台不再在整个 LLM 请求期间占用项目级写锁；同 Agent 后台任务在开发前台运行时只入队，前台成功或失败后把当前 Agent 锁直接移交给 drain，不重新抢锁，也不允许 drain 启动异常把已经完成的调试结果改判为失败。正式用户 GUI 不通过该入口直聊专业 Agent；不同 Agent 继续并行，真实项目写工具只在副作用执行期间短暂申请项目写锁。
@@ -544,7 +555,7 @@ game-project/
 - 中间主视窗提供 `resource-overview / asset-canvas / resource-editor / run` 四种状态。2026-08-10 起普通用户“新增资源”显示为禁用态且处理函数拒绝 create；所有现役资源从聚焦态“编辑资源”进入非破坏性派生。静态图片继续进入 refine 素材创作无限画布，SVG、视频、音频、文档/代码、Agent 回执和项目版本进入统一资源编辑壳并按能力分流；底层 create 合同仅保留兼容。编辑面板只替换中央区域，不覆盖右侧 Supervisor 或底部 Agent。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源总览只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执、已导入附件和已完成任务明确登记的产物派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，未完成任务或未在 `artifacts` 中登记的任意本地音频也不冒充正式资源。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源总览卡片拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供通用工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态。该资源总览边界不限制后续素材创作无限画布内的图片图层移动/缩放、生成和正式回写。
- 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
+- 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。preview server 对 UTF-8 HTML 响应注入固定同源尺寸桥脚本；注入点通过真实 HTML tokenizer 边界定位，保守处理注释异常结束、DOCTYPE 引号、script escaped / double-escaped、raw-text、template、plaintext、foreign content 与重复 `src`，并支持省略 `</body>` / `</html>`。桥以 `ResizeObserver` 观察 `documentElement / body` 根布局，结合页面 load、窗口 resize 与字体就绪重新测量；页面可见时另以 `500ms` 低频兜底探测至多 `512` 个元素的实际边界，探测截断时保留 body / scroll 上界，并按连续测量排除随 viewport 同步变化的 `100vh / 100% / bottom / right` 自反馈。相同尺寸元组去重后才以固定版本 `postMessage` 上报，不订阅整页 `MutationObserver`。宿主同时校验消息 origin 和 `event.source`，以实际内容宽高与当前容器宽高计算不超过 `1` 的等比缩放；首次适配后仍接受内容宽高的真实变化，但仅 viewport 回灌或重复内容尺寸不更新 React 状态。容器 resize 后回到原生视口重新测量；放得下时保持 `1:1`，超出时完整缩小并居中，iframe 禁止横纵滚动条，不能以 `overflow: hidden` 直接裁掉超出内容。非 UTF-8 HTML 原样返回，不因适配桥破坏已有预览。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
 - 当前 run 专业状态与项目历史成果分离：状态继续严格匹配当前 `parentRunId`；已有文本成果从专业 Agent 持久对话中合法的 `agent-finalization-<32 lower hex>` assistant 恢复，并以“历史成果”来源投影到资源管理文档区。新 run 失败、待确认、候选为空或持久对话瞬时读取失败不得清除已恢复的旧成功回执，普通失败 assistant 也不得被当作成果。
@@ -1141,7 +1152,7 @@ game-project/

 - 阶段五只接图片生成与图片精修，通过阶段二共享 `ImageCanvasGenerationPort` 调用客户端 Tauri adapter，并复用现有编辑器项目、统一生成队列、资产上传/换签、稳定引用解析和受控下载能力；不复制网站 `useImageCanvasGenerationWorkflow`，不新增角色动画、视频、音频、图集或平行生成系统。
 - 生成面板和确认摘要只操作本地状态；用户点击独立“确认生成”后才通过 `canvas.asset_generate` confirm 权限边界。本地生成意图建立时即分配稳定 `intentId/generationId/idempotencyKey`，取消确认则直接丢弃且零 External 调用；一旦提交，重复点击、重启和未知结果保持原身份，不能自动确认或换键重扣。
- 主站网页画布与普通 AI 游戏创作 Tauri 客户端统一使用当前平台登录态调用固定官方 origin 的 `/api/editor/*`、`/api/assets/*` 与 `/api/runtime/external-generation/jobs/*`。网站 Access Token 延续现有 WebView 客户端存储与刷新 Cookie 机制；登录成功或刷新后，AGC 只把 `userId + 短期 Access Token + 单调 authGeneration` 的当前快照同步到 GUI/Runner 进程内存，退出或换号以更高 generation 清除旧快照。Token 不写 Rust AppData 配置、项目、账本或日志。`/api/external/v1/*` 继续只供第三方开发者和独立 standalone game-chat/高级自定义模式使用自备 `tnr_sk_...`，不自动签发或下发 Developer API Key。
+- 主站网页画布与普通 AI 游戏创作 Tauri 客户端统一使用当前平台登录态调用固定官方 origin 的 `/api/editor/*`、`/api/assets/*` 与 `/api/runtime/external-generation/jobs/*`。网站 Access Token 延续现有 WebView 客户端存储与刷新 Cookie 机制；GUI 层的同一 `owner epoch` 内仍使用单调 `authGeneration` 约束请求与迟到回包，但每次登录、refresh、退出或换号先推进 durable session revision，再由与 claim 完全匹配的 `runner.attach_gui_owner` 把 `userId + 短期 Access Token + authGeneration` 快照安装到 Runner 进程内存。新 GUI epoch 不继承旧进程 generation；claim 失配时 Runner 清空会话并阻断 Runtime，不得保留旧账号快照。Token 不写 Rust AppData 配置、durable claim、项目、账本或日志。`/api/external/v1/*` 继续只供第三方开发者和独立 standalone game-chat/高级自定义模式使用自备 `tnr_sk_...`，不自动签发或下发 Developer API Key。
 - 每个网络动作在发出前冻结 `ownerUserId + authGeneration`，并在响应解析、账本推进、媒体安装和正式提交前复核当前账号。旧 generation 的迟到响应或清除不得覆盖新账号。普通模式首次 `401` 时，每个 generation 只允许一个共享 refresh；其它请求等待它，但保留各自 deadline/取消。refresh 成功后以更高 generation CAS 安装新 Token，并仅用原 endpoint、原始请求字节和原 `Idempotency-Key` 重试一次；refresh 失败、账号切换或再次 `401` 时停止网络并保留账本，`403` 不触发 refresh。
 - 调用模式、精确相对 endpoint、精确请求、prompt、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。本地参考图 direct-upload ticket 的 host/formFields/policy/signature/临时 Authorization 只存在内存；恢复账本只允许保存稳定 bucket/objectKey。普通账本身份固定为 `official-platform-v1 + 官方 origin + ownerUserId`，高级账本身份固定为 External service origin；均不绑定或保存 Token/Key。换号后旧 owner 账本零网络、零安装，只有重新登录同一 owner 后才能恢复。`accepted/running` 只 GET 原 operation，`prepared` 只精确重放冻结 endpoint、原始请求字节和原幂等键。草稿/manifest/event/日志只投影安全阶段与本地身份。
 - 固定状态顺序为 `generation-accepted -> generation-running -> remote-completed -> media-downloaded -> asset-durable-committed -> manifest-projected -> layout-ready -> selected`。远端 completed 后必须先验证稳定引用，再经 `/assets/read-url` 下载并写入阶段三 staging；随后用账本中的固定本地 commit 身份进入既有 journal/ledger 事务。正式提交失败只恢复本地事务，不重新生成或下载。
@@ -755,6 +755,15 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 时间：`completed_at_micros` 必须为正数并固化为 receipt 完成时间；object/resource/asset/binding/canvas 候选的原时间字段与它一起进入 commit SHA-256，重放必须复用原 prepared commit 而不得重新取时。queue job 完成时间与完成事件仍使用 SpacetimeDB `ctx.timestamp`，不信任调用方时钟。
 - 索引：主键 `operation_key`；`by_editor_generation_operation_owner(owner_user_id, operation_id)` 仅用于受控定位和诊断，不允许同 owner 跨 operation kind 复用同一 operation ID。

+### `editor_idempotent_create_receipt`
+
+- Rust 结构体：`EditorIdempotentCreateReceipt`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布工程、素材文件夹和工程资源首次创建的私有 durable receipt。主键 `receipt_key` 由认证 owner、接口 namespace 与 API 根据 `Idempotency-Key` 派生的请求记录 ID 做 domain-separated SHA-256 得到；`request_sha256` 覆盖完整规范化 create payload，但不包含每次重试都会变化的请求时间。首次业务行、副作用与 receipt 必须在同一 SpacetimeDB 事务中提交，主键唯一约束负责并发仲裁。
+- 重放：同 owner、namespace、key 与同一原始规范化正文重放时，按 receipt 的 `result_record_id` 返回当前业务行，因此工程改名、目录更新或资源元数据后仍不会把当前可变行误判为请求正文漂移；同键异正文返回 `409`。receipt 不随业务行删除，首次结果已删除时重放统一返回 `409` 并拒绝重建；receipt 缺失但请求稳定 ID 已存在同样失败关闭，不能补造 receipt 或重复首次副作用。
+- 索引：主键 `receipt_key`；`by_editor_idempotent_create_receipt_owner(owner_user_id, namespace, request_record_id)` 仅用于受控诊断。表为 private，不作为工程、目录或资源 read model。
+- 真实事务门禁：运行 `npm run check:editor-idempotency-procedures`，在隔离的 SpacetimeDB 2.7.0 hotfix3 standalone 中发布当前模块，验证工程、素材文件夹和工程资源的同正文重放、异正文冲突、并发仲裁、删除后失败关闭，以及业务行与 private receipt 一一对应且无孤儿；源码字符串断言不能替代该门禁。
+
 ### `editor_generation_runtime_identity_rotation`

 - Rust 结构体：`EditorGenerationRuntimeIdentityRotation`