合并主分支并解决图标生成模块冲突

保留图标规范与图集生成独立模块边界

融合主分支角色动画与图片序列字段

docs/project-memory/shared-memory/decision-log.md

@@ -67,19 +67,46 @@
 
 ---
 
+## 2026-08-06 game-chat 固定规则只提供上下文，Supervisor 决定条件 Graph
+
+- 背景：用户要求把已有美术接入当前俄罗斯方块时，Runtime 在 Supervisor 首次 Provider turn 之前按关键词重置 Graph、选择是否复用美术并自动调度 child；Supervisor 没有固定快车道计划时又直接 `fixed-task-graph-stalled`。结果是模型没有理解和决策机会，`art-asset-plan` 在已有资产与 baseline 门互相冲突时重复空规划直至耗尽预算。
+- 决策：关键词、否定/重做信号、占位状态和当前资产探测统一降级为 `advisoryOnly=true` 上下文。game-chat 根 Run 在持久 `GameChatWorkflowDecision` 前禁止启动任何 manifest child，并允许 Supervisor 正常请求 Provider；Supervisor 通过 auto-safe `agent.route_manifest` 选择 `audit-existing-first` 或 `regenerate-art`。审计路线首波只启动 `design-director + code-director`；已登记但无效的旧派生视觉不得在这两项审计启动前截断 scheduler。code-director 必须先成功 `asset.list`，并在 Provider 请求中读取 Supervisor 已持久化且经校验的 `authoritative=true` 决策，再提交绑定当前 root/completion contract/revision 的覆盖合同与 `use-existing-art / generate-missing-art / regenerate-art` 路由。Runtime 只校验身份、正式资产、Canvas、私有合同、切片、manifest、缺口和 fingerprint，并执行条件分支，不从关键词替 Supervisor 作决定。
+- 资产边界：首版缺口槽位固定为 `art-spec` 与原子 `core-spritesheet`。art spec 缺失若使图集的引用/Canvas 合同同时失效，则两个槽位都是真实缺口；仅图集缺失时复用 art spec，只运行 `art-asset-plan`。完整覆盖零生成；显式重做只授权当前 root 下两个正式 owner 原位替换。已登记但校验失败的固定资产按真实缺口交回其 canonical owner，并只在持久路由绑定当前 root 时授权原位替换。art manifest baseline 豁免只读取持久路由，不重新运行关键词分类。
+- 连续性边界：正式 failed continuation 继续继承原完成合同；普通美术措辞不再按关键词跨历史根 Run 借用具体试玩类型，避免新项目误继承旧 `tetris-v1`。code-prototype 仍须先读取并最小 patch 非占位入口、可见使用四类切片，再经过静态检查和试玩门禁。
+- 恢复与权限：`agent.route_manifest` 在共享 Rust/TypeScript 命令目录中为 `auto`，否则 autonomous profile 会因不能等待人工确认而拒绝唯一决策动作；仅根 Supervisor 和其 code-director 审计 child 可执行，隔离 Agent 与其它角色拒绝。执行中断只允许按 durable pending identity 幂等恢复，同 Run 已持久决策/路由禁止改写。
+- 验证方式：覆盖决策前零 child、用户原句只产生 hint、旧无效派生视觉不阻断首波、首波只有设计/程序审计、code-director 收到真实持久策略、完整复用、仅缺图集、无效已登记资产由 owner 原位替换、重做两个 owner、baseline 豁免只认持久 route、code-director 的 asset.list/coverage/route 完成门、自动权限，以及旧 root/错误 binding/fingerprint/缺口/重复 route 失败关闭。
+- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
+---
+
+## 2026-08-06 AGC 根长任务启动与终态失败采用 Runtime 公开消息硬门
+
+- 背景：AGC 已有模型 final-reply、Runtime `eventId/publicText` 和进度卡，但根任务“已入队”没有后端持久公开回执；失败消息又散落在 main loop 多个 `let _ = append conversation` 分支。Provider 或 Runtime 在首条公开事件前失败时可能零消息，同一次失败也可能被 `turn.failed` 和 conversation 重复播报。
+- 决策：Supervisor / 专业 Agent 继续负责业务语义，Runtime 只增加两项不依赖模型的最低可观测性。用户直接投递的 Project Supervisor 根后台任务先落为不可执行的 `preparing / public-status-pending`，再以 run 绑定的 `runtime-public-status-*` message ID 幂等写入启动确认，成功后才转为 `pending / queued`；恢复预检只验证业务状态且不改写 task/conversation，仅真实 resume 持有 Agent 锁后才能把已验证的 accepted 任务持久提升为 `pending / queued`，写入失败则把 task 落为 `failed / public-status-write-failed`。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，在其它终态投影前先写一条脱敏失败消息；专业 Agent 命中同一全局硬期限时，必须通过权威 Run Profile 与根 task 在项目 conversation 幂等写根终态，同时只在精确匹配 agent/run/session、两个 parent 和 binding 的专业 Agent Session 保留 child 终态。自称根 agent/run 但 session 或两个 parent 不符的 Runtime 必须失败关闭，不得生成第二条项目终态。该前缀的 Runtime 公开状态只供 UI 展示，不合入任何 Agent prompt。前端把它视为 Runtime-owned，同秒时排在触发它的 Supervisor 用户消息之后，并仅过滤重复的根 `turn.started / turn.failed / turn.budget_exhausted`，专业 Agent 启动事件仍可见。
+- 恢复补充（以本条为准）：`preparing` 只要同 run 的用户消息或 accepted 任一已完整持久即属可恢复；preflight 不改写业务文件，resume 才在 Agent 锁内补写 accepted 并入队。用户消息或 accepted conversation 已存在而审计补写失败不得把任务改判为启动失败。根终态首次公开写入遇到瞬时失败时，完成终态投影后必须用同 message ID 再幂等写一次。带 parent 的 Supervisor receipt / isolated-join 续跑只保留一份 Runtime 公开终态，不再追加 Session 重复消息；`runtime-task-*` 与 `runtime-public-status-*` 共享同 run 的不透明关联摘要，多个同秒任务在 UI 中按实际 run 关联的 `user -> accepted -> terminal` 交错排序。
+- 边界：不改变 Supervisor 条件 Graph、`agent.route_manifest`、美术路由、Provider tool-plan / final-reply 协议、response stream 或最终 assistant 唯一性；不把 tool 参数、原始错误、路径、fingerprint、凭据和专业 Agent 私有失败诊断公开。Runtime 也不根据工具事件推断业务进展，后续若引入模型 `commentary/final` phase 应沿独立消息协议扩展。
+- 验证方式：覆盖 `preparing -> accepted -> pending` 顺序与崩溃恢复、启动确认幂等、启动确认无法持久化时任务零执行、公开状态不进入实际 Agent prompt、状态文件写入本身失败时仍先产生公开失败、根终态事件不重复进聊天、专业 Agent 启动事件仍可见、普通项目消息不被误标 Runtime-owned，并运行 Runtime 定向 Rust、AppSurface、模型测试、typecheck、编码和 diff 门禁。
+- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
+---
+
 ## 2026-08-05 game-chat 当前 ready child 对 manifest Pending 漂移保持活性
 
+> 本条只保留 ready child 的 Pending 漂移处理；历史试玩类型继承与旧三 Director 首波验收已由 `2026-08-06 game-chat 固定规则只提供上下文，Supervisor 决定条件 Graph` 取代。
+
 - 背景：ready scheduler 已为当前根 Run 持久化并启动 `code-prototype`，但并发 hydration 持有的旧 manifest 快照随后把该节点从 running 覆盖回 pending。父 Run 只读取 manifest 时会在 child 仍运行的情况下误判固定 Graph 已停滞并先行失败；child 完成门又因 pending 连续拒绝真实交付，最终耗尽 loop。
 - 决策：父 Supervisor 的“是否调度新节点”和“是否等待已存在 child”必须分开。派生视觉需要父规划修复时可以暂停新调度，但只要当前最新且仍活跃的根 Run 下存在确定性 runId、正确父绑定且 durable journal 非终态的 ready child，父 Run 必须保持 `waiting-for-manifest-tasks`。game-chat child 仅在同一当前根 Run、确定性 runId、可信 scheduler source、正确父绑定、journal 仍为 queued/running 且不处于确认、用户输入或 reconciliation 时，容忍 manifest 的 pending 漂移并继续走全部产物、静态检查和试玩门禁。
 - 失败关闭：GUI/CLI、旧父 Run child、终态 child、错误/伪造绑定、非确定性 runId、WaitingForConfirmation、WaitingForUserInput 和 needs-reconciliation 都不得借用该容忍；创建更新的根 Run 后，旧 child 立即失去父 DAG 活性与 pending 完成资格。
-- 玩法连续性：既有美术增量任务可跨可信 Supervisor 入口回溯同 Session 的最近具体试玩场景；只跳过纯继续和既有美术接入语义，遇到更新的详细 Generic 新目标立即停止，避免从更老项目错误借用 `tetris-v1`。
-- 验证方式：覆盖当前 game-chat child 的 running -> manifest pending 漂移仍保持 DAG 活跃并可完成投影；更新根 Run 后旧 child 被拒绝；派生视觉需要修复但已有 child 活跃时父 Run仍持久化等待；GUI child 继续拒绝 pending；GUI 创建俄罗斯方块后从 game-chat 接入既有美术仍使用 `tetris-v1`。
+- 玩法连续性：普通美术措辞不再触发历史玩法类型回溯；只有正式 failed continuation 继承原完成合同，纯“继续”沿用现有 continuation 识别边界。
+- 验证方式：覆盖当前 game-chat child 的 running -> manifest pending 漂移仍保持 DAG 活跃并可完成投影；更新根 Run 后旧 child 被拒绝；派生视觉需要修复但已有 child 活跃时父 Run仍持久化等待；GUI child 继续拒绝 pending；普通美术措辞使用当前任务分类，不借用旧 `tetris-v1`。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
 
 ---
 
 ## 2026-08-05 增量接入既有美术时复用已验收 Graph 节点
 
+> 已由 `2026-08-06 game-chat 固定规则只提供上下文，Supervisor 决定条件 Graph` 取代。下述内容保留为问题演进记录，不再作为当前实现依据。
+
 - 背景：game-chat 增量指令“把 UI 和方块替换成美术资源”会重置七项首版 Graph，把已有且已验收的 `art-director / art-asset-plan` 重新打开。`art-asset-plan` 确定性快车道同时因图集已存在而返回零 action，child 完成门又要求 `assets/manifest.art.json` 相对本轮 baseline 发生变化，最终连续六轮得到同一 `unchanged-from-run-baseline` blocker 并耗尽 loop；这不是 Provider 故障。
 - 决策：只有 game-chat 用户明确表达替换、接入、使用或复用美术资源，项目已有非占位游戏，且 art spec、透明图集、Canvas 登记、私有图集合同、四类切片与 art manifest 全部通过现有严格验收时，Graph reset 才保留 `art-director / art-asset-plan=completed`，只重新打开设计、代码和试玩节点。根 Supervisor 完成门仅对该合法复用场景豁免 `assets/manifest.art.json(unchanged-from-run-baseline)`；文件存在、JSON、Canvas、私有合同、切片和代码可见使用门禁继续执行，任一证据失效即撤销豁免。普通新游戏、全新/重做美术、否定使用或占位项目一律把美术节点恢复为 pending。
 - 玩法连续性：合法增量美术接入从同 Session 的可信 Supervisor 历史根 Run 继承最近一个非 Generic 试玩场景；只跨过纯继续与既有美术接入语义，遇到更新的详细 Generic 新目标立即停止。例如 GUI 创建的俄罗斯方块转入 game-chat 继续使用 `tetris-v1`，不能因为本轮文字只描述 UI/美术而降级成 Generic，也不能跨过后来的新游戏目标借用旧场景。
@@ -5917,6 +5944,21 @@
 - 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。
 - 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。
 
+## 2026-07-28 编辑器媒体类型统一由 assetKind 判定
+
+- 决策：`assetKind` 是编辑器资源和素材唯一权威媒体类别；不新增或返回 `mediaType`。`character-animation` 渲染为序列帧，`video` 渲染为视频，`audio/sound-effect/background-music` 渲染为音频，其余类别渲染为图片。前端内部可保留派生的 `CanvasMediaType` 选择渲染器，但不能把它作为后端事实。
+- 持久化边界：`editor_project_resource` 与 `editor_asset` 表尾只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，默认均为 `None`；`editor_showcase_asset` 作为提交时冻结的审核与公开快照，同样在表尾保存这两个字段并从账号素材逐字段复制，旧行默认均为 `None`。正式帧对象和角色动作生成响应都不保存或返回 `frameIndex`，数组位置是唯一播放顺序；帧数取数组长度，FPS 由帧数和毫秒时长即时推导，不持久化 `frame_count`、`fps` 或通用 `duration_seconds`。后端处理抽帧和逐帧去背时仍保留内部 `frame_index`，仅用于乱序并发收口、OSS 命名、日志和错误定位；仓库内旧 helper 同步升级，不为它保留外部兼容字段。
+- 时长口径：`image_sequence_duration_ms` 只表示角色图片序列完整播放一次的毫秒时长，与音频 / 视频生成请求中的 `durationSeconds` 完全分离。角色动作与视频生成响应仍可携带各自既有的请求 / 结果级 `frameCount/fps/durationSeconds`；通用音视频秒数不进入资源 / 素材正式列、`EditorAsset`、`CanvasLayer` 或画布 layout，只允许把上传探测值或生成请求值格式化为用户可见字符串后写入 `generation_inputs_json.fields[]` 供素材详情展示。素材详情和画布 ZIP 用户可见元数据只透传实际存在的 `fields[]` 时长项；缺少时直接省略，不生成 `--:--` 占位。素材放置与工程恢复不做媒体探测，也不从 layout / resource 回退；音频播放只使用媒体 `loadedmetadata.duration`。不得为音频生成响应新增 `durationSeconds`，也不得把音视频秒数写入图片序列字段。前端角色动作播放器使用 `imageSequenceDurationMs / imageSequenceFrames.length`，Spine 导出时才换算秒数并推导 FPS。
+- 写入与复用边界：`assetKind=character-animation` 必须在 SpacetimeDB storage/procedure 边界同时提供至少两帧有效数组与大于 0 的图片序列毫秒时长；其他类别不得携带图片序列字段。同项目同源同媒体资源只允许 `None → Some` 单调回填，非空冲突失败关闭，延迟重试的 `updated_at` 取请求时间与既有时间的较大值。
+- 生成关联边界：角色动作生成响应同时返回已经持久化的最终 `resource` / `asset`；带项目上下文时前端结果图层必须直接使用 `resource.resourceId` 及其预览视频来源血缘，缺少 resource 直接失败。无项目放置也必须绑定响应中的正式账号素材，不能从响应 `frames` 构造无资产真相的本地动作结果。“动作（原始视频）”只是 `asset_kind = video` 的 provider 中间产物，其 `editor_project_resource` 与 `editor_asset` 两行都固定 `generation_inputs_json = NULL`，不得携带引用或开放参数复用；完整用户生成配方只保存在最终 `asset_kind = character-animation` 的序列资源 / 素材。角色动作规范化迁移对权威证明的 preview video 同样清空整份生成输入，但不改写其 `source_resource_id`。
+- repair 幂等边界：legacy 音频 repair 不再派生或回填任何资源级通用时长，因此新列上线前已完成 repair 的重放继续按原字段精确匹配；图片序列字段在音频行上均为 `None`。
+- 布局边界：`editor_project_resource` 的正式字段是角色动作唯一媒体真相；动作 layout 只保存资源引用和 placement，不保存帧、时长、预览、生成输入、资源元数据或顶层 `mediaType`。前端仍可从 `assetKind` 派生内部 `CanvasMediaType`，但后端响应清洗不得把普通 layer 的旧 `mediaType` 传回前端，也不得递归删除 `generationInputs.references[*].mediaType`。
+- 迁移边界（2026-08-04 收口）：存量 `generation_inputs_json.characterAnimation`、已证明动作行的 helper 顶层 `frames/previewVideoPath/frameCount/fps/durationSeconds`、`screenColorHex`、正式帧 `frameIndex`、误标预览 MP4 和动作 layout 副本，由 `normalize_editor_character_animation_metadata_and_return` 按 `asset → project-resource → showcase → canvas` 一次性规范化。顶层字段只有先证明动作身份后才解释；普通图片 / 视频任意 JSON 中的同名字段不动。canvas dry-run 可消费前置 scope 的计划态结果，但 apply 仍要求前置 scope 已物理完成；同 task 候选先按权威对象规划分类并排除预览视频，只有唯一最终图片序列可补建资源。正式序列每帧必须按首帧 bucket 的稳定路径精确匹配同 owner / task 的图片 `editor_character_animation` 对象并补齐 `objectKey/assetObjectId`。迁移永不验证 layout 复制的 `sourceResourceId`，补建资源采用最终素材的 DB 血缘；新生成直接来源链仍严格校验。正式/旧版冲突、最终候选为零或多个、对象不匹配形成 blocker；apply 必须绑定同批 dry-run SHA-256，结束后全量复核零匹配、零 blocker。迁移完成后删除 api-server、admin、Web 与 helper 的 action fallback。
+- 新写入边界：`assetKind=character-animation` 的 `generationInputs` 若含旧运行字段或 `screenColorHex`，正式帧若含 `frameIndex`，api-server 和 SpacetimeDB storage 均失败关闭；门禁只对角色动作生效，不误伤其它素材的任意 generation input JSON。
+- 交互边界：角色动作素材下载导出完整序列 ZIP；点击、HTML5 拖放和指针拖放创建可移动、循环播放且可保存恢复的序列图层。`assetKind=character-animation` 但缺少有效帧时按损坏素材失败关闭，不回退首帧 PNG。
+- 精选展示边界：`/creation` 精选卡片和预览弹窗继续扩展各自现有媒体 renderer，不复用或重构画布图层组件；卡片静止时只读取首帧，hover / focus 后才加载并播放完整序列，预览弹窗提供播放暂停。后台素材查询与精选审核继续共用 `AdminEditorAssetMedia`，列表只读首帧，预览弹窗才逐帧使用管理员换签。两端均按 `imageSequenceDurationMs / imageSequenceFrames.length` 切帧，下一帧未就绪时保留上一帧且禁止淡入；损坏动作不退回普通图片。
+- 精选帧授权边界：公开换签只对当前已通过、已展示、返还完成且未删除的精选动作，按同 owner 的冻结帧 `assetObjectId` / `objectKey` 形成 exact grant；不从 `imageSrc` 或前缀推导。隐藏、拒绝、删除或快照损坏后逐帧授权随当前事务真相撤销，`read-url` 与 `read-bytes` 继续共用该判断。
+
 ## 2026-07-24 后台用户详情展示历史花费泥点
 
 - 口径：`historicalConsumedPoints` 表示用户历史总消费，只累计 `profile_wallet_ledger.source_type = asset_operation_consume` 且 `amount_delta < 0` 的绝对值；`asset_operation_refund` 不冲减，充值退款追回、余额重置、赠送和退款 hold 均不计入。
@@ -6108,6 +6150,8 @@
 
 ## 2026-08-03 game-chat 开发态前后端同源与快车道恢复
 
+> game-chat 的旧三 Director 首波、无条件美术生成和对应 Pending 容忍范围已由 `2026-08-06 game-chat 固定规则只提供上下文，Supervisor 决定条件 Graph` 取代；本条其余 GUI / CLI、启动、source 与输出决策继续有效。
+
 - 启动决策：`npm run agc` 与 `npm run agc:game-chat` 统一先经外层 Node 启动器预检 `3080`。在 marker 尚不能证明 worktree 归属时，任何已占用的 3080 都不得复用，并必须在原生窗口创建前失败关闭；Tauri CLI 退出后必须收束已启动的客户端进程树，不允许终端已退出但窗口与 Runner 仍假在线。
 - 首波决策：普通 GUI / CLI 的正式 16 节点 DAG 与 game-chat 首版 lane 都只把 `design-director / art-director / code-director` 作为首波 ready Agent。正式 DAG 的 `design-foundation` 等待策划与美术 Director，`code-prototype` 等待程序 Director 及数值、美术、音频三条底层产物链；game-chat 在策划与美术 Director 完成后启动 `art-asset-plan` 生成透明图集，`code-prototype` 必须同时等待三个 Director 与该图集任务，再串行执行静态检查和试玩。首波以外的非 repair 底层 Agent 只能由依赖就绪调度或上层明确返工合同按需激活。
 - Runtime 决策：game-chat 七任务 lane、平台美术、单轮收束和自动预览只由持久 `project-supervisor-game-chat` root source 启用。hydration 对 `Pending` 的容忍只适用于当前 source-aware lane 的三个零依赖首波任务。页面进度、阶段记录和 final-reply 白名单统一使用七项任务与 `x/7`。
@@ -6116,6 +6160,8 @@
 
 ## 2026-08-03 game-chat 失败续跑与首版产物保护
 
+> game-chat 的无条件美术生成部分已由 2026-08-06 的 Supervisor 条件路由取代；失败 continuation、非占位入口保护和美术产物验收边界继续有效。
+
 - 事故事实：`game01` 的首个根 run 已交付并验证水晶下落方块原型，但父 run 在上下文压缩后因 token 上限失败；用户随后输入“继续”时，客户端创建了 task 仅为“继续”的新 game-chat root，完成合同重置 seed manifest，五分钟 fallback 再把该短语当主题整文件覆盖 `game/index.html`。这不是模型随机换题，而是 root 目标未继承、每新 run 无条件 reset 和 fallback 无条件 `file.write` 叠加形成的确定性缺陷。
 - 续跑决策：同一 Supervisor Session、同一持久 source 的最近失败根 run 后，严格继续短语创建 successor root，并继承前序原始任务、baseline revision / artifact 身份；纯继续识别统一由一个精确函数负责，覆盖“继续 / 接着 / continue / go on”等无新约束短语。真正新需求、跨 Session、跨 GUI / CLI / game-chat source、前序正常完成或含具体新约束的输入继续创建独立新任务并重置本轮 manifest。successor 不复用旧网络请求、pending、action、Provider lifecycle 或 sidecar，只继承业务目标和已提交项目事实。
 - 覆盖决策：game-chat fallback 只允许初始化缺失/占位入口的首次落盘。非占位 `game/index.html` 必须保留，并由当前 `code-prototype` 先读取和实际 patch，取得本人 `mutationRevision` 后才能运行 `game.static_smoke` 与交付；只读 smoke 不得冒充续作。确定性 fallback 只允许已实现真实语义的显式玩法模板：俄罗斯方块模板必须具备 10×20 棋盘、下落、移动、旋转、锁定、消行和触顶失败，收集模板只用于明确收集类目标，未知玩法失败关闭。纯继续目标未恢复时同样失败关闭。完成门新增 baseline 玩法连续性和 action-driven state 检查，generic Canvas 非空、三个按钮存在或静态 smoke 通过都不能单独证明任务没有换题。
@@ -6403,6 +6449,8 @@
 - local 状态：`local-*` 只是 ID 形状，不能直接解释为“素材仍在保存”。新上传 / 新生成素材是否 pending 取资源登记在途状态；严格满足兼容谓词的历史自包含本地角色动作序列是持久化终态，不得误报等待。若当前版本尚不能复制这类序列，以准确原因失败关闭；既非 pending 又不满足历史谓词的 unresolved local 图层也失败关闭，但不得承诺稍后一定自动恢复。layout PATCH pending 不参与资源登记判断，系统剪贴板图片导入不受影响。
 - schema 与迁移：在现有 `EditorCanvasLayer` 结构体末尾追加 `#[default(None::<String>)] asset_kind_override: Option<String>`，不删除、改名、重排或改类型。legacy 图层类型与资源默认相同则迁移为 `None`，不同则迁移为 override；资源无默认值时只有全部引用图层显式同值才补资源默认，否则保留各自 override；自包含历史序列的显式类型迁入 override，不伪造资源。同步 `migration.rs`、表目录 / 数据契约、生成 bindings、HTTP DTO 与结构化 canonical hash，并运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`。
 - 并发边界：未登记图层被禁止复制后，不再按临时资源 ID 合并项目资源创建请求，也不再用一次响应批量改写共享临时 ID。每个合法新增图层保留自己的响应快照与回调；layout PATCH 的串行 latest-wins 队列、共享资源的多布局引用和 session 资源快照按 `resourceId` 去重继续保留，它们与资源创建 single-flight 是不同机制。
+- 媒体兼容边界：override 只允许在资源默认类型的同一媒体族内变化。动作、视频各自独立成族，`audio/sound-effect/background-music` 同属音频族，其余类型与空默认值同属图片族。前端菜单禁用跨族标签且更新入口重复校验；后端对每个结构化图层按资源完整校验，跨族值清空后回退资源默认类型，不因该兼容错误拒绝整个保存。
+- 历史恢复：客户端读取到已持久化的跨族 override 时必须保留图层、回退资源默认类型、显示明确提示并自动提交清理后的布局；不得再用 `hydrateLayer() -> null -> filter(Boolean)` 静默隐藏持久层仍存在的图层。修复保存只替换命中图层的规范化布局项，其他尚不能 hydrate 的历史项原样保留，避免修复一个标签时顺带删除无关数据。
 
 ## 2026-08-03 Agent Runtime 原生工具合同本地失败关闭
 

docs/project-memory/shared-memory/development-workflow.md

@@ -81,9 +81,19 @@ cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml real_
 
 修改 game-chat release flavor 后，至少执行壳配置门禁、AppSurface game-chat 定向测试、前端类型检查、AppData / 诊断日志 / release flavor 相关 Rust 定向测试、`npm run check:encoding` 和 `git diff --check`。打包 smoke 必须确认：安装信息和产物版本为 `0.1.1`；无参数启动直接进入且只能停留在 game-chat 页面；停止或断开 `api-server` 后本地工作台仍能打开；普通 dev / release 与 debug game-chat 仍走原认证入口；独立 AppData 生效。预览 smoke 应先让当前 run 成功验证 revision N，确认 Tauri registry 启动一个 server 且 iframe 自动出现；在 validate 后、start 取得锁前推进项目 revision，必须确认原子 `expectedRevision` 门禁拒绝启动且授权保留等待新证据；再验证 revision N+1，确认 server 进程和 loopback origin 不变、iframe 显示新版本且响应为 `no-store`。same-run steer 还要覆盖旧验证不消费新授权、旧异步 attempt 不清新 generation；Runner registry 单独 running、失败 / 相同 / 更低 revision 均不能触发用户预览或重复刷新，停止后顶部显示“预览未启动”。独立包退出时必须通过 `runner.shutdown_for_client_exit` 先进入 draining 再结束本 boot，保留 durable sidecar 供下次 reconciliation，不把中断任务写成 completed；Windows Runner 必须 `CREATE_SUSPENDED -> AssignProcessToJobObject -> ResumeThread`，分配或恢复失败时 kill + wait，客户端持有 kill-on-close Job 兜底，关闭主窗口后 Runner、MCP、command、ConPTY 及其后代都应消失。普通 dev / release 和 CLI 继续使用 `runner.shutdown_if_idle`。
 
-game-chat 迭代还必须确认以下行为：Supervisor ready 输出、`design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 七个专业 Agent 的 durable `final-reply`，以及 Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/7`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口均不得暴露或启动 `publish-strategy` / `publish-package`。game-chat 必须配置可用的 External Editor API，按 `art-spec.png -> icon-spritesheet -> art-spritesheet.png + iconImageSrcs 本地切片 -> code-prototype Canvas 使用四类切片` 推进；缺少任一环节都必须失败关闭。
+game-chat 迭代还必须确认以下行为：Supervisor ready 输出、本轮实际启动的 `design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 专业 Agent 各自产生 durable `final-reply`，条件路由跳过的节点只要求 manifest 正确投影为 completed，不伪造 Agent 回复；Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/7`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口均不得暴露或启动 `publish-strategy` / `publish-package`。固定关键词与资产探测只进入 Supervisor 的 advisory context；没有持久 Supervisor 路由时不得启动任何 child。只有程序侧审计判定存在真实缺口或 Supervisor 明确选择整体重做时才要求可用 External Editor API，并按 `art-spec.png -> icon-spritesheet -> art-spritesheet.png + iconImageSrcs 本地切片 -> code-prototype Canvas 使用四类切片` 补齐；`use-existing-art` 不得重复生成或扣费，但仍须通过相同正式资产和代码可见使用门禁。
 
-game-chat 素材完整快车道采用七任务口径。父 Run 与全部 child Run 共用 4200 秒软预算和 4500 秒累计硬上限；先确定性生成并登记 `art-spec.png`，再由 `art-asset-plan` 通过专用 icon-spritesheet 路由生成透明 `art-spritesheet.png`，下载并持久化响应中的独立切片，最后才允许 code-prototype 写入或局部修复入口。软预算后只允许使用已登记图集、当前 resourceId 对应切片清单的确定性本地 fallback、`game.static_smoke` 和 `preview.validate`；不得退回普通生图、猜测 atlas 网格或纯代码核心画面。完成门要求活动 Canvas 分别绘制 player、blocks-and-targets、obstacles-and-scene、feedback-effects 四类不同切片；整图 `<img>`、CSS background、完整图集直绘、单个猜测裁切和路径诱饵均失败。对应定向测试至少包括：
+Project Supervisor 根后台任务还必须验证公开消息硬门：任务先落为不可执行的 `preparing / public-status-pending`，项目 conversation 中存在且仅存在一条同 run 的 `runtime-public-status-* / accepted` 后才能转为 `pending / queued`；恢复 preflight 只验证并临时分类可恢复状态，不改写 task/conversation，真实 resume 持有 Agent 锁后才可把 accepted preparing 持久提升为 `pending / queued`；否则不得执行。若该消息无法持久化，task 必须进入 `failed / public-status-write-failed` 且 Provider、工具与 child 调度均为零。这类 Runtime 公开状态不得合入 Agent prompt。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，即使后续 task/event/state 写入失败，也必须已经存在一条脱敏终态失败消息；专业 Agent 命中全局硬期限时，项目 conversation 仍必须幂等保留根终态，但 child 终态只能写入与权威 task 的 agent/run/session、两个 parent 和 binding 全部一致的私有 Session；自称根 agent/run 却 session 或 parent 不符时失败关闭。只有根 Supervisor 的 `turn.started / turn.failed / turn.budget_exhausted` 不得再形成第二条聊天消息，专业 Agent 的公开启动事件仍应显示。非 Supervisor 专业 Agent 的失败状态留在对应 Agent Session，不得把私有诊断送进项目 conversation。定向复验至少运行：
+
+提交前还要覆盖启动崩溃窗口：仅 `preparing` 时 preflight/resume 均不执行；用户消息已持久但 accepted 缺失时，preflight 只报可恢复且 task/conversation 不变，resume 才补写 accepted 并转为 `pending / queued`。还要验证用户消息或 accepted 已落盘但审计失败均继续入队、根终态首次公开写入瞬时失败会用同 ID 重试、receipt / isolated-join 失败只有一条公开结果，以及同秒连续任务通过共享的 run 关联摘要按 `user -> accepted -> terminal` 逐任务展示。
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml public_start_status -- --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml structured_plan_state_write_failure_stops_before_context_and_audit -- --test-threads=1
+npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts apps/ai-game-creator-shell/tests/appSurface.test.ts
+```
+
+game-chat 条件快车道仍采用七任务口径，但执行顺序由持久合同控制。父 Run 与全部 child Run 共用 4200 秒软预算和 4500 秒累计硬上限；Supervisor 首轮先调用 `agent.route_manifest`，决策前零 child。`audit-existing-first` 的首波仅为 `design-director + code-director`，已登记但无效的旧派生视觉不得阻断这两项审计启动；code-director 必须先 `asset.list`，读取 Supervisor 已持久化的 authoritative 决策，再提交正式资产覆盖合同。覆盖完整时跳过图片生成，存在缺口时只开放缺口对应 owner，`regenerate-art` 才强制重新开放两个美术 owner；已登记但校验失败的固定资产只允许当前路由绑定的 canonical owner 原位替换。新生成仍按 `art-spec.png -> art-spritesheet.png + 独立切片` 推进，最后才允许 code-prototype 写入或局部修复入口。软预算后只允许使用已登记图集、当前 resourceId 对应切片清单的确定性本地 fallback、`game.static_smoke` 和 `preview.validate`；不得退回普通生图、猜测 atlas 网格或纯代码核心画面。完成门要求活动 Canvas 分别绘制 player、blocks-and-targets、obstacles-and-scene、feedback-effects 四类不同切片；整图 `<img>`、CSS background、完整图集直绘、单个猜测裁切和路径诱饵均失败。对应定向测试至少包括：决策前零 child、旧无效视觉不阻断首波、首波无美术 child、code-director 收到真实持久策略、完整覆盖零生成、仅缺图集只运行 `art-asset-plan`、无效已登记资产由 owner 原位替换、art spec 缺失导致引用合同失效时同时补齐两个槽位、显式重做原位替换两个正式资产、旧 root/fingerprint/缺口或重复路由失败关闭，以及补齐后恢复 code-prototype。
 
 失败续跑还必须覆盖同 Session 同 source 继承、跨 Session / 跨 source 不继承、首次与连续 successor 的 effective task / contract / scheduler 一致性，以及中英文纯继续短语使用同一识别函数。非占位入口的新 `code-prototype` 必须先产生本人 mutation 再 smoke；连续只读 smoke 不得收束。占位 fallback 只允许显式支持的真实玩法模板，俄罗斯方块必须验证棋盘、下落、旋转、锁定和消行语义，未知玩法必须失败关闭。
 
@@ -654,7 +664,7 @@ npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-tool-plan-handoff-r
 
 ## AI 游戏创作长耗时与退出恢复验证
 
-- 修改 autonomous 调度时，必须证明缺省 policy 不产生 manifest 之外的首波专业委派，Editor Key、已有/损坏视觉资产均不能改变该事实；显式项目 policy 只验证“原样尊重”，不能由 Runtime 隐式扩充。
+- 修改 autonomous 调度时，必须证明缺省 policy 不产生 manifest 之外的首波专业委派，Editor Key、已有/损坏视觉资产均不能改变该事实；game-chat 还必须证明持久 Supervisor 决策前零 child，决策后的首波只有 `design-director + code-director`，固定关键词不能直接改 Graph。显式项目 policy 只验证“原样尊重”，不能由 Runtime 隐式扩充。
 - 修改预览完成门时，分别覆盖 child `preview-readiness` 当前 revision smoke、child `preview-playtest` 到根 Supervisor 合同的 browser receipt，以及 WebSocket 启动前退出的稳定基础设施分类。基础设施错误必须在一次浏览器调用后让 run 失败，不能只做到后续调用快速失败而继续消耗 Provider 轮次。
 - 修改 game-chat Runner 生命周期时，至少覆盖 busy durable sidecar 拒绝 client-exit、拒绝后 `draining=false` 可继续执行、清空后 idle shutdown、重复 shutdown 幂等；Windows target check 继续保留，不能以删除 Job Object 或放任后台继续来规避 reconciliation。
 - LLM 配置回归必须穷举全部规范 Agent，校验无遗漏/重复、显式 patch 覆盖默认，并锁定 GUI 展示映射和 Rust resolver 一致；模板与 GUI 初始草稿不得把规范默认持久化成 `agentLlm` 显式覆盖。`--llm-status` 要输出逐 Agent 实际 reasoning/timing/retry 值。运行日志与当前配置冲突时，先区分 durable run snapshot 和后来修改的文件，不能按当前文件反推历史请求。

docs/project-memory/shared-memory/pitfalls.md

@@ -14,6 +14,15 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## Runtime 状态写失败不能发生在公开失败消息之前
+
+- 现象：用户提交长任务后只看到运行失败或任务直接消失，聊天里一条有用消息都没有；另一些失败又同时出现 Runtime event 和 conversation 两条近似提示。
+- 原因：启动确认依赖实际 `turn.started`，任务只入队或 Runner 在 start transition 前失败时没有公开回执；终态失败先写 task/event/state，最后才由各 main-loop 分支尽力追加 assistant。坏掉的若正是状态文件，流程会在公开消息前返回；散落的 `let _` 又无法提供幂等身份。
+- 处理：用户直接投递的 Project Supervisor 根任务先落为不可执行的 `preparing / public-status-pending`，持久化同 run 的 `runtime-public-status-* / accepted` 后才转为 `pending / queued`；恢复 preflight 只验证业务状态，不改写 task/conversation，仅 resume 持有 Agent 锁后才可持久提升。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，先写相同协议的终态消息，再处理 Runtime 其它投影。专业 Agent 命中全局硬期限时，应由权威根 task 在项目 conversation 中幂等写根终态，child 仅在身份完整匹配时写私有 Session；根 agent/run 的 session 或两个 parent 冲突时必须失败关闭。消息正文只能来自封闭脱敏映射，prompt 构建必须按稳定前缀排除；前端按前缀标记 Runtime-owned，只过滤根 Supervisor 的 `turn.started / turn.failed / turn.budget_exhausted`，不吞掉专业 Agent 启动进度。模型仍负责业务 commentary/final，Runtime 的两条硬门不扩展成业务判断器。
+- 恢复补充：不能把“accepted 还没写完”等同于“用户从未投递”。用户消息已持久时，真实 resume 必须补写 accepted 后才入队；用户消息或 accepted conversation 已存在时，后续审计失败不得留下“正在启动”但永不执行的假状态，但同 message ID 的 role/content 冲突必须把 task 明确收束为 `conversation-write-failed`。根终态首次公开写入的瞬时失败必须在终态投影后用相同 message ID 重试。带 parent 的 Supervisor continuation 不得同时产生 Session 终态和 Runtime 事件两条公开消息；秒级时间戳下必须以 task/status message ID 共享的 run 关联摘要排序，不能用不同消息类别的计数猜测顺序。
+- 验证：任务 journal 必须显示 `preparing -> pending`，仅有 accepted 时恢复才可提升；破坏项目 conversation 时断言任务为 `public-status-write-failed` 且无可运行 pending；破坏 Runtime state 路径时断言公开失败已经存在；重复写同一 run/status 只有一条 message ID；渲染实际 prompt 断言不包含 Runtime 公开状态；AppSurface 证明根启动/失败事件不重复，专业 Agent 启动仍可见。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs`、`agent/runtime_driver/task_start.rs`、`src/features/agent-runtime/model.ts`、`src/features/project-workspace/SupervisorChatOnlyView.tsx`。
+
 ## manifest 被旧快照写回 Pending 时不能让父 Run 抛下真实运行中的 child
 
 - 现象：`code-prototype` 已有确定性 child run、running journal 和工具事件，父 Supervisor 却在几秒后以 fixed graph stalled 失败；child 随后完成代码与静态检查，但 completion gate 持续报告 `task=code-prototype status=pending`，最后 `loop-budget-exhausted`。
@@ -22,12 +31,20 @@
 - 验证：人工把当前 child 的 manifest 状态回写 pending，断言父 DAG 仍 in progress、父上下文可持久化为 `waiting-for-manifest-tasks`、child 可投影 completed；随后创建更新根 Run，断言旧 child 不再保持 DAG 活性且 completion blocker 恢复 `status=pending`。不要靠增加 loop 次数或伪造 completed 掩盖竞态。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
 
+## 固定关键词提示不能代替 Supervisor 选择条件任务图
+
+- 现象：用户只说“现在没有用到任何美术资源”，Graph 就在 Supervisor 输出任何计划前自动打开美术节点；或者用户想复用现有素材，Runtime 直接按关键词预完成节点。Supervisor 无固定计划时随即 `fixed-task-graph-stalled`，看起来像模型不理解意图，实际上模型根本没有获得决策机会。
+- 原因：同一套关键词函数同时承担 prompt hint、Graph reset、baseline 豁免和历史试玩类型继承，启发式信号越过 Supervisor 成为了控制面真相；main loop 又在 Provider 请求前优先调度 ready task。
+- 处理：启发式结果只序列化成 `advisoryOnly=true` 的 Supervisor context。Scheduler 以持久 `GameChatWorkflowDecision` 为首轮前置门；Supervisor 先选审计或整体重做，code-director 再用成功 `asset.list` 和 Runtime 复核的覆盖合同选择复用或精确补缺。Runtime 可以拒绝过期、伪造、遗漏或重复 route，但不得替 Supervisor 补写决定。
+- 验证：直接使用用户原句，断言 hint 命中但 manifest 全部保持 pending、决策前零 child、Provider request 包含路由工具；决策后首波只有 design/code，code-director 未完成 asset.list/route 时不能完成；再分别覆盖完整复用、真实缺口和显式重做。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`runtime_driver/main_loop.rs`、`runtime_driver/task_start.rs`、`runtime_protocol/autonomous_completion.rs`。
+
 ## 既有正式产物不能同时被快车道视为已完成、被本轮 baseline 门视为未变化
 
 - 现象：增量任务已有完整美术图集，`art-asset-plan` 每轮都返回零 action 和“已验证交付”，但 completion gate 每轮都报告 `assets/manifest.art.json(unchanged-from-run-baseline)`；最终 child `loop-budget-exhausted`，随后 Graph 和父 Run 失败。日志中没有本轮 Provider request、tool plan 或 action receipt。
 - 原因：Graph reset 无差别重新打开稳定的美术 owner 节点；快车道按“当前产物有效”判断完成，owner 完成合同则按“本轮必须修改 baseline 产物”判断完成，两套语义互相冲突。增加 loop 预算、伪造版本号或机械改写 manifest 都不能消除冲突，还会引入 verification loop、字段丢失或错误复用旧主题。
-- 处理：先在 Graph 层区分“复用已验收产物”和“需要重新生成”。仅对明确的既有美术接入意图、非占位游戏和整套严格有效的视觉合同保留美术节点 completed；根完成门只忽略这一路径的 art manifest baseline 相同，所有结构、Canvas、私有回执、切片和可见使用验收继续失败关闭。普通新游戏、全新美术或证据损坏必须重新打开 owner 节点。
-- 验证：不要只断言 child 未被调度；还要直接经过父完成门，证明合法复用不再出现 art baseline gap，并证明删除切片后 baseline gap 与视觉合同 gap 重新出现。另覆盖普通新目标和全新美术请求不复用旧美术。
+- 处理：关键词和资产探测只作为 Supervisor 的 advisory context，不能直接修改 Graph。根 Run 先持久化 `audit-existing-first / regenerate-art` 决策；前者只启动 `design-director + code-director`，由 code-director 在成功 `asset.list` 后提交权威覆盖合同和精确缺口。Runtime 验证合同后才把已有 owner 投影为 completed，或只打开缺口 owner；根完成门只对持久路由明确复用的 art manifest 忽略 baseline 相同，所有结构、Canvas、私有回执、切片和可见使用验收继续失败关闭。
+- 验证：先断言 Supervisor 决策前零 child、固定关键词不会预完成节点，再覆盖完整复用、仅缺图集和明确重做。还要直接经过父完成门，证明合法持久路由不再出现 art baseline gap，并证明删除切片后覆盖合同拒绝复用；旧 root、错误 fingerprint、虚构或遗漏缺口和重复改写路由都应失败关闭。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
 
 ## 执行锁移交给未确认启动的异步 future 会制造永久 queued
@@ -395,10 +412,18 @@
 
 - 现象：产品要求画板 `生成角色动作` 返回后按透明序列帧播放和下载，但旧实现或旧测试可能继续把结果当作预览视频处理。
 - 原因：后端仍需要先生成 `previewVideoPath` 再抽帧、绿幕去背和落 OSS；如果前端把预览视频当主媒体，就会绕过已经扣绿幕的 PNG 帧，也无法按序列帧打包下载。
-- 处理：角色动作结果图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`，`previewVideoPath` 只作为来源信息保留。单图层下载必须生成序列帧 ZIP；画布素材 ZIP 中角色动作写入 `sequences/<编号-标题>/frames/`。不得移除后端原有视频生成、抽帧、绿幕去背和帧落盘流程。
-- 验证：`ImageCanvasGenerationLayerModel` 应断言动作结果 `src` 为首帧且 `mediaType="image-sequence"`；画布集成测试应出现 `画布序列帧：角色动作` 图片播放器，不应出现角色动作 `<video>`；导出测试应断言角色动作下载和画布素材导出都包含序列帧 ZIP / frames 目录。
+- 处理：角色动作结果图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`，`previewVideoPath` 只作为来源信息保留。生成端确认每帧对象后必须把该帧 `objectKey` 与 `assetObjectId` 一起写入正式 payload 和 `generation_inputs_json.characterAnimation.frames`。单图层下载必须生成序列帧 ZIP；画布素材 ZIP 中角色动作写入 `sequences/<编号-标题>/frames/`。不得移除后端原有视频生成、抽帧、绿幕去背和帧落盘流程。
+- 验证：`ImageCanvasGenerationLayerModel` 应断言动作结果 `src` 为首帧且 `mediaType="image-sequence"`；画布集成测试应出现 `画布序列帧：角色动作` 图片播放器，不应出现角色动作 `<video>`；导出测试应断言角色动作下载和画布素材导出都包含序列帧 ZIP / frames 目录；生成测试还应断言首帧与非首帧的稳定引用都被保留。
 - 关联：`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 
+## OSS 导出兜底必须覆盖响应体读取阶段
+
+- 现象：浏览器控制台显示 OSS `206 Partial Content` 后紧跟 `net::ERR_FAILED`，画布预览或素材导出失败，但没有出现预期的 `/api/assets/read-bytes` 兜底请求。
+- 原因：`fetch(signedUrl)` 可能先返回一个 `ok` 的 `Response`，网络、浏览器 Range 缓存或传输错误随后才在 `arrayBuffer()` / `blob()` 消费响应体时暴露；如果直连保护边界只包住 `fetch` 和状态码，响应体失败会绕过 fallback。
+- 处理：私有素材字节读取必须在直连 OSS 分支内完整消费响应体并重新构造可重复读取的 `Response`；换签、请求、非成功状态或响应体读取任一阶段失败时统一回退同源 `/api/assets/read-bytes`。Abort 仍应直接上抛，不能转化为额外服务器读取。
+- 验证：前端服务测试模拟 OSS 返回 `206/ok`、但 `blob()` reject，断言随后请求 `/api/assets/read-bytes` 并返回 fallback 完整字节；同时保留直连成功、局部分片、直连非成功、请求 reject 和 Abort 边界。
+- 关联：`src/services/assetReadUrlService.ts`、`src/services/assetReadUrlService.test.ts`、`src/components/image-editor/ImageCanvasExportModel.ts`。
+
 ## 图片画布序列帧播放不要复用普通图片淡入样式
 
 - 现象：角色动作序列帧播放时看起来像每帧之间在渐变或闪烁。
@@ -4005,6 +4030,35 @@
 - 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。
 - 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
 - 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
+
+## 角色动作不能靠素材主图或通用生成输入恢复
+
+- 现象：角色动作在整画布导出时正常，但从素材库单项下载只得到第一帧 PNG，拖回画布也成为普通静态图片。
+- 原因：`editor_asset.image_src` 只指向首帧；若 worker 把完整帧集塞进 `generation_inputs_json`，素材 DTO、用户输入清洗或画布布局任一层丢字段，就会退化成 PNG。再增加一个 `mediaType` 只能掩盖结果字段没有落到正式资源的问题。
+- 处理：worker 只把完整帧集与图片序列毫秒时长写入 `editor_project_resource` / `editor_asset` 的 `image_sequence_frames_json`、`image_sequence_duration_ms`；数组位置是唯一帧序，不保存 `frameIndex`，帧数和 FPS 均按需派生。`assetKind=character-animation` 决定序列渲染。素材映射、单项下载和拖回画布只读取这两个正式字段，项目 resource 在保存 / 刷新后继续作为主真相；动作 layout 只保留资源引用和 placement，不再复制正式媒体结果。账号素材提交精选审核时，`editor_showcase_asset` 必须冻结复制相同字段，公开 read model 只返回正式字段。外部 helper 只调用一次动作生成接口并直接使用响应 `resource` / `asset`。
+- 画布回填：角色动作会形成“原角色资源 → 预览视频资源 → 最终序列资源”的血缘链。生成响应必须返回已经持久化的最终 resource，前端图层直接使用其 `resourceId`；不能继续构造 `local-resource-character-animation-*`，否则 `appendCanvasLayersWithResources` 会再次创建重复资源。新图层的 `sourceResourceId` 同时使用最终 resource 的直接来源（预览视频 resource），不能继续沿用请求中的原角色 resource；否则结构化保存会在已生成并计费后因血缘不一致而拒绝。修复时只替换资源关联与血缘字段，不要顺带把动作图层显示尺寸从生成占位尺寸改成原始帧分辨率。
+- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。同一 task 可能同时存在误标为动作的预览 MP4 和最终首帧 PNG，候选查找必须先按权威对象类型做计划态分类，排除视频并要求唯一正式图片序列，不能按原始 `assetKind` 计数。账号素材仍有旧帧、但后来拖入画布的 project-resource 只剩清洗后 `fields/references` 时，project-resource dry-run 必须按同 owner / task / 首帧对象精确消费 asset 计划态结果；apply 仍要求前置 asset scope 已物理完成。canvas 判断已有 resource 是否为动作时也必须消费 project-resource 的计划态类型：旧库误标为动作、但权威对象证明为 preview MP4 且 layout 本身是 video 的图层直接跳过动作清理；layout 明确为 `image-sequence` 却指向该视频时继续形成 blocker，资源规划本身有 blocker 时也不得静默跳过。正式序列还要逐帧用稳定对象路径匹配同 owner / task 的已登记图片对象并补齐 `objectKey/assetObjectId`。迁移不得验证 layout 复制的 `sourceResourceId`：历史 layer 可能仍指向原角色，而最终素材已指向预览资源；清理副本后采用最终素材的 DB 血缘即可，新生成链路仍保持严格校验。正式与旧版结果冲突、候选为零或多个均形成 blocker；脚本诊断应直接打印 scope、ID、原因、owner/project/task、对象身份和来源资源，不能只报 blocker ID。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。
+- 新写入与验证：动作 `generationInputs` 出现 `characterAnimation/frames/previewVideoPath/frameCount/fps/durationSeconds/screenColorHex`，或正式帧出现 `frameIndex`，HTTP 与 storage 双层拒绝；其它 asset kind 的任意 JSON 不受该动作门禁影响。测试覆盖两种历史 JSON、无关顶层同名字段、正式/旧版相等与冲突、可选帧引用合并、screen color 和 frameIndex 清理、预览 MP4 重分类、幂等、blocker/hash apply、画布 placement 清理/资源补建、正式字段缺失失败关闭和 helper 单请求。
+
+## 图片序列时长不要复用通用媒体秒数
+
+- 现象：把角色动作、视频、音频和上传媒体都写进通用 `duration_seconds`，随后又尝试用持久化 `frame_count/fps/duration_seconds` 互相校验，造成取整口径、生成参数和实际播放时长彼此污染。
+- 原因：角色动作需要的是一组图片完整播放一次的精确时长；视频 / 音频的 `durationSeconds` 是生成请求或临时运行态参数。帧数已经由数组长度唯一确定，FPS 也可按需要推导，无需维护三份可冲突真相。
+- 处理：资源 / 素材只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，精选审核快照只冻结复制这两个正式字段。角色动作要求至少两帧且毫秒时长大于 0；播放器按 `时长毫秒 / 数组长度` 计算间隔，Spine 导出时再换算秒数并推导 FPS。音频 / 视频 `durationSeconds` 不映射到这两个字段。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`。
+
+## 精选角色动作显示首帧还要检查前端 renderer 与逐帧授权
+
+- 现象：精选接口已经返回 `imageSequenceFrames` 和正确的 5 / 6 秒成本，但创作主页或后台审核仍只显示首帧；接入播放器后又可能只有第一帧成功、后续帧换签返回 404。
+- 原因：快照字段、展示 renderer 和私有对象授权是三道独立边界。公开 `imageSrc/objectKey` 只代表首帧，不能让前端自动获得完整帧集；顶层精选 exact grant 也不会自动覆盖其它帧对象。
+- 处理：公开精选模型必须把 `assetKind=character-animation` 映射到序列 renderer，并携带完整帧与毫秒时长；后台素材查询和精选审核共同透传同一字段并复用 `AdminEditorAssetMedia`。生成端不能在 `ProcessedEditorCharacterAnimationFrame → EditorCharacterAnimationFramePayload` 收口时丢弃逐帧 `assetObjectId/objectKey`，正式序列 JSON 必须保留已确认对象的稳定引用。公开授权在 SpacetimeDB 同一事务快照中只按有效精选动作的同 owner 逐帧 `assetObjectId/objectKey` 匹配，不能放宽 generated 前缀。列表未交互时只读首帧，打开或激活动作预览后也只挂载当前帧和有界预读窗口，避免再次制造换签突发；单帧换签或解码失败时跳过该帧、暂停全帧失败的序列并提供显式重试，不能长期显示空白或旧帧。卡片 hover 与 focus 分别跟踪，只要任一状态仍成立就继续播放，系统请求 `prefers-reduced-motion` 时卡片和弹窗默认暂停，用户仍可在弹窗中手动播放。
+- 验证：模型 / 组件测试覆盖 4 / 5 / 6 秒动作、损坏序列不回退 PNG、后台两页共用播放器和未激活列表不逐帧请求；SpacetimeDB 测试覆盖主对象、每帧对象、无关对象、跨 owner 与取消展示后的授权撤销。真实浏览器和端到端验收由人工单独执行，不把 unit / component 结果写成 E2E PASS。
+
+## 可复用资源回填必须保持时间戳单调
+
+- 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。
+- 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。
+
 ## 历史钱包消费不能从最近流水或通用订单快照推算
 
 - 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。