@@ -76,7 +76,6 @@
- 处理：本阶段不加机制，manifest 明确降级为 lineage 判定通过后的补充信号（见 decision-log 2026-08-12 条）。将来要做，必须同时覆盖两条写入路径，并统一走毫秒换算 helper。
- 验证：`apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts` 的「keeps an unbound manifest out of the verdict until the current main is terminal」钉住了现有边界与残余风险；该用例最后一条断言即为已记录的残余风险，改动它就意味着重新裁决，必须同步更新决策记录。
- 现象：前端 Runtime map 以 Agent ID 保存当前记录。新一轮仍会复用 `code-prototype` 、`art-director` 、`art-asset-plan` 这些 Agent ID；若旧 root 已终态但 main/美术 child 或 manifest 仍在收口，直接从 live map 归档会在新 root 接管后丢失旧后代，或把新轮证据误接到旧阶段记录。
- 修复：根进入终态时按完整 `agent/session/run` 身份保存 root-scoped Runtime 快照，后续只合并同一稳定身份的更新；manifest 快照只在该 root 仍为当前 root 时捕获。归档前重新执行严格 lineage、全终态、单 main/单 active art 与 reconciliation 门禁，并用 root run 派生稳定 message ID。
@@ -109,6 +108,7 @@
- 并发恢复补充：自主根任务 journal 写入后建立或重建 completion contract 时，初始 manifest reset 与 continuation reconciliation reset 不能重新使用 fail-fast 项目锁。异步 child finalization 可以合法插入两次取锁之间，使已入 journal 的新根被误记为 `completion-contract-failed` 。这两条 reset 必须使用现有有界等待项目锁，超时仍失败关闭；只验证 scheduler 合同的测试应预占 child Runtime lane，不能真实启动后台 worker 后再手工改 manifest。确定性回归要显式持锁，分别证明初始合同与 continuation 合同等待释放后成功落盘。
- 验证：夹具必须从 `init_local_game_project_at` 开始，先断言无 `package.json` 且占位入口 smoke 失败，再证明产物不齐阻断、齐全后内部验证通过、无 smoke trace、再次 mutation 失效；另覆盖四个 owner 路径矩阵、错误身份、恢复、跨 run 凭证、`art-director` 有/无 Key、动态美术借凭证拒绝、`code-prototype` project.verify-only 阻断和试玩 executor 身份。
- 关联：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 、`docs/technical/【技术方案】立项策划Agent（ ） 。
## UI 设计 State 的 strict JSON round-trip 不能混用两种浮点序列化表示（2026-08-19）
- 现象：为节点拖拽/缩放生成非整数 Transform 后，保存报“UI 设计 State 安装后回读与待写内容不一致”；由于读取主文件失败关闭后恢复 `.previous` ，后续回读表现为刚导入的 spirit/sprite 资产丢失。
@@ -4364,7 +4364,6 @@
- 处理：历史花费只累计 `asset_operation_consume` 负向流水绝对值，退款不冲减；通过 `profile_wallet_consumption_total` 在已有投影时按主键 O(1) 累加。首次上线必须在停写维护窗口由 owner 执行全量初始化，为每个已有钱包流水的用户建立投影，不能让所有存量用户的首次正常消费各自扫描历史；维护遗漏或新用户缺行时才在首次消费或详情读取中按用户索引兜底重建一次。手动对账扫描是独立高风险操作，member 必须单独持有 `profile-wallet-consumption-reconcile` ，不能因为能打开共享用户详情就自动获得。
- 验证：构造消费、退款、充值退款追回和赠送混合流水，断言只累计消费；维护初始化后正常消费只按主键累加；重复详情读取不得重复扫描或重复累计；任意 Tab 权限不能调用手动对账，同时确认充值订单列表的通用钱包快照没有新增历史流水扫描。
- 症状：`code-prototype` 首次完成后 `.agent/logs/command.log` 已出现 `permission.confirm preview.start` ，但客户端没有 iframe， `.agent/logs/preview.log` 也没有新的 running 记录；后续即使父 run 完成也不再启动。
- 根因：旧实现调用 `start_local_game_preview` 前就把“项目 + parent run”的授权加入 attempted 集合并清空；首版完成投影与后续专业任务仍在写项目时，启动恰逢项目写锁竞争，catch 只显示错误却无法重试。
- 约束：一次性语义应按“成功或确定性终态”消费，不按“函数调用次数”消费。项目写锁竞争保留同一授权并轮询重试；成功、显式 deny 与非瞬时失败才清除。授权需持久化项目路径和 accepted runId，重启恢复时仍必须逐项匹配，切换项目不得继承。
@@ -4460,7 +4459,6 @@
- 处理：严格继续意图必须在同一 Supervisor Session、同一持久 source 内继承最近失败根 run 的原始目标和 baseline，但保持新的 run/Provider/sidecar 身份；纯继续词表只能有一个权威实现，中英文短语都走同一入口，真正新需求仍独立 reset。非占位入口禁止 fallback 整体覆盖，也不能反复运行只读 smoke；当前 `code-prototype` 必须先读取并实际 patch，取得本人 mutation 后才能验证和交付。占位 fallback 只支持具备真实语义的显式模板，俄罗斯方块必须实际实现棋盘、下落、旋转、锁定和消行，未知玩法失败关闭。`art-spec.png` 只作规范参考，核心运行时位图必须来自独立派生的透明 `art-spritesheet.png` 及其 `iconImageSrcs` 本地切片；切片清单绑定当前图集 resourceId，Canvas 分别使用玩家、目标、场景和反馈四类素材。不得猜测图集是 2×2 等分、把规范板塞进画面或以纯代码核心实体绕过派生素材。
- 验证：覆盖失败根任务“水晶俄罗斯方块”后输入“继续”、连续 successor、跨 Session、跨 source、正常完成后新输入、带具体新需求、既有非占位入口先 patch 后 smoke、初始化占位的俄罗斯方块真实语义、未知玩法失败关闭、纯继续目标缺失、规范图不在运行 DOM/Canvas、真实动作前后 `sequence` 与 RAF 空转。浏览器验收必须同时比较 baseline 玩法关键文本/控件/状态和当前 revision，不能只看 Canvas 非空与三个固定按钮。
- 现象：用户要求把已有美术资源接入游戏时，固定 `code-director -> art-director / art-asset-plan -> code-prototype` 图会在缺少主 Agent 审计的情况下启动美术生成，或把“整体重做”错误实现为无条件生图；美术完成后又换了 Run，代码接入、静态检查和试玩无法形成连续责任链。
- 原因：固定节点把“是否需要美术”的语义判断编码为 Runtime 前置流程，`code-director` 成为另一个主控，而不是让真正接入游戏的 `code-prototype` 基于权威资产事实决策；如果再把固定审计策略塞进用户意图字段，Supervisor 的理解也会被 Runtime 规则覆盖。两个素材槽都缺失时若先消耗不可重试的 `art-asset-plan` 委派，其 child 又必然因缺规范图失败，整个 Run 会进入无法补救的死路。
- 处理：Supervisor 用 `intentSummary` 持久化自己对用户意图的理解，固定 `audit-existing-first` 只作安全执行策略，随后只启动 `code-prototype` 。主 Agent 先 `asset.list` ，完整覆盖就直接使用；仅在事实证明缺少规范图或核心图集时，才建立一个写入范围受限为 `assets/**` 的美术 durable delivery。两槽都缺失时必须先完成并认领 `art-director` 的 `EvidenceReady` delivery，再委派 `art-asset-plan` ；回执返回同一主 Run 后再接入素材、原玩法语义检查、静态检查和双视口试玩。读取旧 v1 决策时必须复核其旧 fingerprint，并从完成合同绑定的有效任务迁移 intent；旧 `code-director` coverage/route 只能触发当前主 Agent 重新审计和原位替换，不能直接成为新完成证据。整体视觉重做意图同样必须经过这次审计，不能成为绕过资产复用或强制重生成的固定规则。完整 GUI / CLI DAG 不使用该例外。
@@ -4489,7 +4487,6 @@
- 验证：DOM 与截图不得出现外部品牌或 unsupported 列；AppSurface 覆盖 populated / invalid / empty、搜索与菜单；Playwright 在 `1280× 测量无页面级溢出。视频控制在有用时长内，清楚展示搜索、清除、菜单、状态反馈和项目打开结果，每一段都有可观察变化。
- 关联：`apps/ai-game-creator-shell/src/features/app-shell/ProjectCreation.tsx` 、`apps/ai-game-creator-shell/src/features/app-shell/model.ts` 、`apps/ai-game-creator-shell/src/features/app-shell/useRecentProjects.ts` 、`apps/ai-game-creator-shell/tests/appSurface/home.suite.ts` 。
- 现象：首波从单个美术任务扩展为三个 Director 后，hydration 若仍只容忍 seed lane 的第一个任务在 manifest 短暂恢复 `Pending` 时收束，另外两个已启动 Director 会被卡住。另外默认 `llm.stream=false` 下的专业 final reply 虽已由 finalization 提交，但后续阶段推进项目 revision 后，早期回复会从 Runtime 查询中消失。
- 原因：hydration 例外把“首波”错误收窄成了单个固定或数组第一项任务；`visible_game_creator_agent_runtime_response_stream_at` 又把未提交流的 revision 新鲜度门误用到了已终态提交的 durable final reply。
- 处理：从当前 root source 的 seed lane 动态解析全部零依赖首波任务，只对这些 child 容忍 hydration `Pending` ，后续 code prototype / preview 仍严格要求 Running/Completed。`streaming / ready` 仍要求当前 revision， `committed` 回复改为依据 finalization 的稳定身份查询，不随后续项目 revision 失效。
@@ -4865,7 +4862,6 @@
- 现象二：图片预览已经读取真实宽高，但大量资源触发 LRU 淘汰后，卡片又退回 `180x128` ，布局和连线随之跳动。原因是布局尺寸直接从可淘汰的 Blob/Object URL 预览缓存派生。处理时预览二进制仍按预算淘汰，但已验证的轻量 `pixelWidth/pixelHeight` 必须在当前项目、模式和资源 identity 作用域内独立保留；identity 或 scope 变化时再清理。
- 验证：分别覆盖严格 edit body、错误分类、生成占位恢复，以及超过预览缓存条目上限后首张图片仍保持真实比例、布局碰撞和依赖端点不退化。
# 2026-08-21 已有资源 ID 不等于可用于快速编辑的 canonical 来源
- manifest 中的 `source.resourceId` 可能指向历史按 `game-background` 等 Game Agent 私有 kind 登记的远端资源。只检查 ID 前缀并直接传给 `sourceReferenceId` 会在 External v1 入队前得到 `unsupported-source-kind` ；本地 kind 映射只有在真正重新登记来源时才生效。
@@ -4873,14 +4869,12 @@
- 批量导入不能在安装首个媒体后继续执行带 `?` 的 ID、路径、层序或 revision 计算；这些步骤必须先完成。原子草稿写入返回错误后，回读失败属于提交结果未知，必须保留媒体并报对账错误，不能把回读错误压成“未提交”后删除可能已被草稿引用的文件。所有回滚删除失败也必须显式上报。
- 失败 generation 同时存在私有 ledger 和 draft 投影，只在 React state 中 `filter` 会在重启后复活。删除 UI 必须调用只允许明确失败任务的后端归档操作，结果未知任务不能删除。
## 运行中 generation 与 refine 来源身份不能按 create 链路处理（2026-08-21）
- 草稿 hydrate 后同步等待远端 generation recovery，会让生命周期长期停在 recovering，连平移和选图也被 inert。关键事务恢复与任务恢复必须拆开：前者先完成，后者后台推进且失败只进入任务/notice。
- refine 提交若无条件校验 `source.resourceId == local-asset:<assetId>` ，会拒绝本来合法的 `editor-resource-*` 已登记来源，并可能把事务卡在 `revision-installed` 。创建与未登记本地资产才补 local identity；已登记 refine 必须保留并按解析后的来源身份回读。
- 画布内部 absolute overlay 只能覆盖宿主网格，嵌在左右分栏时不会遮住整个窗口。阻断性失败必须 portal 到 `document.body` ，并用 fixed inset 覆盖整个 WebView；测试应验证 portal 的直接宿主和 fullscreen modifier。
## 自由画板 viewport 与资源 extent 分离（2026-08-24）
- 非空资源栏目使用无限画布：普通平移的 `x / y` 不按资源 extent 夹取，窗口 resize、媒体测量和资源 extent 变化也不得把用户 viewport 拉回内容边界；共享 `MIN_SCALE/MAX_SCALE` 只约束缩放比例。只有首次进入组合或用户显式复位时，才用真实卡片包围盒计算 fit。
