完成 SFX V2 T5 正式生成链路

接通 Luna 英文化、ElevenLabs 单次生成、MP3 校验、OSS 与权威元数据写回
演进站内和 External v1 契约、幂等参数、详情重绘与 Agent 音效模型
新增 ElevenLabs 动态定价键及历史定价快照兼容
同步 OpenAPI、外部 Agent Skill、共享计划与决策记录

docs/openapi/genarrative-external-v1.openapi.json

@@ -4449,25 +4449,41 @@
       "EditorSoundEffectGenerationRequest": {
         "type": "object",
         "required": [
-          "prompt",
-          "duration"
+          "prompt"
         ],
         "properties": {
           "prompt": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "maxLength": 2048,
+            "description": "用户原始语言音效描述。服务端只删除首尾 Unicode White_Space，并按 Unicode code point 校验 1-2048。"
           },
           "model": {
             "type": [
               "string",
               "null"
             ],
-            "default": "audio1.0"
+            "default": "eleven_text_to_sound_v2",
+            "description": "省略、null、空串、纯 Unicode White_Space 或首尾空白包围的 eleven_text_to_sound_v2 均 canonicalize 为 eleven_text_to_sound_v2；audio1.0 和其它非空值返回 400。"
           },
           "duration": {
-            "type": "integer",
-            "minimum": 2,
-            "maximum": 10
+            "anyOf": [
+              {
+                "type": "number",
+                "minimum": 0.5,
+                "maximum": 30
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "null 或省略表示自动时长；有限数值表示手动时长。服务端不按 UI 0.1 秒步进取整。"
+          },
+          "loop": {
+            "type": "boolean",
+            "default": false,
+            "description": "独立 Loop 参数；服务端不从 Prompt 推断、同步或校验。"
           },
           "projectId": {
             "type": [
@@ -4629,6 +4645,22 @@
               "background-music"
             ]
           },
+          "durationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 600,
+            "description": "SFX V2 为 MP3 探测所得实际时长；不是请求时长。BGM 或历史结果可省略。"
+          },
+          "loop": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "SFX V2 返回冻结并发送给 provider 的 Loop；BGM 或历史结果可省略。"
+          },
           "project": {
             "anyOf": [
               {

docs/project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md

@@ -2,7 +2,7 @@
 
 日期：`2026-08-06`
 
-状态：`T1、T2、T3、T4 已完成，可以继续进入 T5；T2 翻译 service、T3 ElevenLabs adapter 与 T4 前端冻结参数均待 T5 正式接线，当前仍不是可发布切点`
+状态：`T1–T5 已完成，可以继续进入 T6；T6 测试、灰度与发布门禁完成前仍不可发布`
 
 开发分支：`feat/sound_opt`
 
@@ -177,6 +177,12 @@ T4 没有修改 Worker、provider 调用、正式请求的 nullable duration / L
 - 实现新模型定价键、历史 Vidu 只读 / 重绘兼容、中英 Prompt + Loop 详情和真实时长。
 - 同批更新 External v1 Rust DTO / handler / OpenAPI / Idempotency-Key 重放 / compact result；任一字段不一致时 T5 不完成。
 
+实施记录（`2026-08-07`）：T5 已完成。站内与 External SFX 请求在定价、预扣和 enqueue 前统一 canonicalize 为固定模型、canonical userPrompt、nullable 小数时长与 Loop；正式浏览器 POST 不再配置 unsafe retry，queue payload 不包含提前翻译的 actualPrompt。Worker 在既有冻结计费上下文内执行 Luna 英文化、单次 ElevenLabs POST、MP3 校验与实际时长探测、OSS、项目资源 / 账号素材 / 画布完成态写回，并使用 queue job ID 或 inline 预生成的平台 ID 作为 Task ID。服务端重建 `generation_inputs_json`，客户端自报的实际英文 Prompt、实际时长、模型与 Loop 不进入权威 metadata。
+
+新定价键 `eleven_text_to_sound_v2` 已加入默认 JSON、api-server 与 SpacetimeDB 值校验，旧 `audio1.0` 键继续保留；历史 SpacetimeDB 定价快照仅缺新键时由受控本地定价补齐读取，下一次后台保存写回完整矩阵，不修改 schema。详情展示中英 Prompt、实际时长、Loop、生成模型与完整平台 Task ID；SFX V2 重绘恢复 userPrompt、duration mode / requested duration 和 Loop，自动时长不会把实际输出时长误作下一次手动值。
+
+External v1 Rust handler、共享 DTO、OpenAPI、compact result 与 Agent Skill 已同步 nullable `0.5-30` 时长、Loop、固定模型和实际 `durationSeconds`；接受的 model 形态生成同一 canonical queue payload，旧 / 未知模型在 enqueue 前返回 `400`。External compact 继续隐藏 provider 与 Prompt，只保留稳定资源引用、实际时长和 Loop。T5 定向 Rust、TypeScript、External/OpenAPI、Agent、定价与 SpacetimeDB WASM build 已通过，未执行真实 LLM、ElevenLabs 或其它付费请求；完整失败矩阵、端到端与发布 smoke 继续归属 T6。
+
 ### T6：测试、文档、灰度和发布门禁
 
 - 汇总 T1–T5 分层测试，增加 mock LLM + mock ElevenLabs + mock OSS 失败矩阵、端到端等值、刷新 / 重绘、计费退款、无重试、External 幂等和 BGM 回归。

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

@@ -127,6 +127,7 @@
 - 影响范围：AI 游戏创作 `runtime_driver/task_start.rs`、`task_queue.rs`、自主构建 continuation 合同、Supervisor 进度卡与相应 Rust/AppSurface 回归；不改变 manifest DAG、Agent catalog、Provider 路由或项目产物合同。
 - 验证方式：不预占 child locks，真实一次调度三项首波任务，并在有界时间内证明每个逻辑 Run 至少写入 running/`turn.started`；重复调度不得新增逻辑 Run。前端固定时钟覆盖正常运行、子 Agent 新活动、疑似停滞、各类合法等待与 terminal 冻结。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
 ## 2026-07-31 图集切片按需编码并批量确认持久化
 
 - 背景：`2026-07-29 图集切片必须受前置容量和有界 CPU 保护` 收口了连通域数量与 CPU 并发，但切片仍在一次循环里全部裁剪并编码，最多 64 份 PNG 字节连同整张 RGBA 同时驻留内存；持久化又按切片逐个调用 procedure，N 片至少 2N 次写入外加一次 cohort 完成，任一片失败都会留下已确认的部分记录。手动拆分入口另有一处重复鉴权：`get_editor_project` 已经取回并定位了来源资源，随后仍走 `parse_editor_reference_image` 按注册 ID 再解析一次，触发全账号项目与素材库扫描。
@@ -139,6 +140,7 @@
 - 验证方式：`platform-image` 覆盖 prepare 不编码且 `Send + Sync`、并发编码多个 index 结果不变、累计裁剪像素在编码前拒绝；`api-server` 覆盖切片记录 ID 稳定且按 owner / index 分区、自动路径保留处理超时告警码、上传超时释放内存许可；`spacetime-module` 覆盖批次校验的完整 cohort、重复 objectKey、来源资源同 owner 同 project、部分 cohort 拒绝与重放只在内容一致时复用。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、本文件 `2026-07-29 图集切片必须受前置容量和有界 CPU 保护`。
 - 补记说明：本条为事后补写，记录提交 `cf1a02312` 已落地的行为，不改变其任何决策。
+
 ## 2026-07-31 AI 游戏创作资源依赖图采用 Rust 只读拓扑与前端派生 SVG
 
 > 状态：其中资源卡 Pointer Move 拖动预览与局部更新验收已由 2026-08-03 mentor 最新决定暂缓；只读拓扑、SVG 派生展示、搜索与选择高亮合同继续生效。
@@ -6047,6 +6049,7 @@
 - 占位删除与重试：completion 必须读取当前权威 dialog；若删除已先持久化，只跳过画布 layer / dialog 写回，不得使用请求中的旧 placeholder 复活图层，已经成功持久化的 project resource / 账号素材允许保留。若回包时本地占位已删除，前端不得应用完成快照或写历史；现有布局 CAS 没有 deletion tombstone，因此 completion 先提交、删除保存后冲突的极端竞态仍按权威快照收口，绝对“删除意图胜出”留待 targeted delete / tombstone 方案。该路由是 unsafe POST，客户端不得配置 `EDITOR_REQUEST_RETRY_OPTIONS`；请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放，Bearer 中间件在 handler 前拒绝请求后的既有认证恢复继续保留。结果未知时先 GET 权威项目 / 素材快照，由用户显式决定是否再次执行。
 - 历史边界：成功加入画布时写一条 `perfect-pixel` 历史，中文标签为“完美像素”，并纳入新增结果保护；撤销不得让派生 PNG 消失。像素处理失败或 completion 因占位删除未落画布时不写该历史。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`。
+
 ## 2026-07-31 game-chat 每条输出入聊天、试玩后收束与平台图集引用
 
 - 背景：game-chat 的 ready response 之前只作为 transient stream 展示，专业 Agent 的 `final-reply` 只进入各自私有 conversation，刷新或事件 / 轮询重放时项目聊天可能丢失这些输出；自主构建完成后仍可能继续进入发布任务；配置 External Editor API 时，原型 HTML 也可能不实际使用平台生成的 Canvas 美术资源。
@@ -6295,6 +6298,7 @@
 - 影响范围：`/editor/canvas` 的 `audio-background-music` 面板撤销按钮与其定向测试；不改变单层交换快照语义、canonicalization、提交锁、Suno 契约或后端 Prompt 助手，也不修改状态模型字段，`temporaryPromptSnapshot` 已在公开 dialog 状态中且只在 `completing` / `simplifying` 期间非空。本条不适用于 SFX，V1.0 不改动 SFX 的一键优化与撤销行为。
 - 验证方式：按矩阵逐行覆盖初始隐藏、首次与再次 AI 处理期间显示并禁用、成功启用、失败隐藏、手动编辑后仍启用、点击预设隐藏、`submitting` 有无快照的两种表现、解除锁定后恢复，以及连续撤销互换保持启用；并断言处理期间按钮仍在可访问树中且为真实禁用态。
 - 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
 ## 2026-08-03 完美像素对账判据改看 dialog 收口状态，网关合成响应归入未知结果
 
 - 缺陷一（对账把真成功判成失败）：对账用「同 ID 的 generation-dialog 是否还在权威快照里」判定成败，而服务端成功回填时**保留**该 dialog 并就地改写——`apply_editor_canvas_generation_items` 置 `status: "idle"`、`composerOpen: false`、写入 `generatedLayerId`、清掉 `errorMessage`，该行为另有服务端测试断言 `dialog["generatedLayerId"]` 钉住。所以响应丢失但服务端其实已完成时，判据反向：用户被告知「画布未收到完美像素结果，请确认素材库」，而结果早已在画布上，重做一遍就造出第二份；这条分支还刻意不套用快照，本地也看不到那个新图层。
@@ -6468,6 +6472,7 @@
 - 权威性与剩余风险：preflight 不创建锁、reservation 或新表记录；最终 `persist_editor_pixel_art_result_and_return` 仍在同一事务内重复目录、布局、幂等 identity 和 revision 校验。preflight 通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下无引用 OSS object；彻底消除该 TOCTOU 需要 durable reservation / journal 或事务协调，不在本 PR 的最小修复边界内。
 - 契约影响：只新增 SpacetimeDB procedure ABI 与生成 bindings；没有表字段、index、migration、HTTP DTO、路由、状态码、OpenAPI 或 shared-contracts 变化。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 2026-08-04 AI 游戏项目 manifest 存储与工作台实时投影
 
 - 存储决策：`.agent/manifest.json` 的版本追加不可变约束由同目录持久专用锁保护，读取旧状态、校验版本前缀、安装临时文件和安装后回读必须处于同一临界区；进程内 Mutex 不能替代跨进程文件锁。
@@ -6527,6 +6532,7 @@
 - classic script 分析单元把 inline 与无 `defer / async` 的本地 external 正文按 `game/index.html` 标签顺序交错组成 parser-blocking 段，再把 classic external `defer` 按文档顺序放到解析完成后的 deferred 段；不得把 defer-before-inline 误投影为外链先执行。classic external `async` 的下载完成顺序不可静态证明，当前静态门直接失败关闭。带 `src` 标签的 inline body 继续忽略；外部文件仍执行可信普通文件、`game/` 边界、文件数与累计体积门禁，重复标签按浏览器出现次数保留求值位置。
 - Canvas 尺寸、可见性、元素绑定和 stylesheet 选择器扫描只消费浏览器可渲染标记；`template / textarea / noscript / title / style / xmp / iframe / noembed / plaintext` 内的 Canvas、标签和样式诱饵全部跳过。活动顶层 stylesheet 与可见标记分开提取，既允许真实 CSS 参与隐藏/尺寸判断，也不把 CSS raw-text 中的伪标签当作 DOM。
 - ESM 组合单元按 dependency 初始化先于 importer 顶层求值排列。import reference 的 span replacement 仍基于原 importer 完成，随后把已闭包的 dependency projection 放在 importer 前并对最终单元重跑 parser、semantic、单元 `2 MiB` 与累计投影 `32 MiB` 门禁；循环模块继续按 `(origin module, original root binding)` canonical identity 去重并要求有界固定点收敛。
+
 ## 2026-08-04 JavaScript 延迟状态与复合调用边
 
 - 受控异步 callback 的 alias 读取按完整 enclosing invocation 链延迟到各层函数同步收尾，最外层再延迟到当前 job 末尾；callback 写入仍不在注册点同步提交。conditional / assignment expression callee 分别在 test / RHS 求值后建立调用边，`new` 同时执行普通 function constructor 及 alias。
@@ -6727,6 +6733,7 @@
 - 业务隔离：共享组件不等于共享规则。SFX 继续使用 Vidu `audio1.0`、2–10 秒、默认 5 秒、现有 Prompt 回退、1500 字限制、价格和提交链路；BGM 继续使用 canonical Prompt、200 字生成限制、30 个预设、AI 补全 / 简化、单层撤销、提交锁和 Suno。BGM 按 dialog ID 写回，SFX 继续走现有 `setGenerateDialog`，两条路径不得互换。
 - 非目标：本次只规划视图归并，不实现 SFX V2 的 ElevenLabs、中译英、自动时长、30 秒、Loop、一键优化或预设，不修改任何后端、External v1、Schema、计费或需求原文，也不新建配置驱动的 composer 框架。
 - 实施状态：已恢复共享音频 composer，独立完整 BGM composer 及其测试文件已删除，原覆盖完整迁入总 composer。Prompt / 预设 / controller / 总 composer `121/121`、surface 与 submission workflow `72/72` 通过，typecheck、变更文件 ESLint、Prettier、编码检查和差异检查通过；没有修改后端、契约或需求原文，也没有实现 SFX V2 独有功能。
+
 ## 2026-08-06 SFX 生成优化 V2.0 T0 设计与迁移口径
 
 - 权威入口：SFX V2 的可编码规则已完整融合到 `docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。实现、审查、测试和发布只以该 tracked 权威设计、本条决策和共享实施计划为依据，不依赖团队通过 Git 无法取得的本地资料。
@@ -6759,3 +6766,11 @@
 - 预设视图：BGM 预设跑马灯抽出无业务语义的音频内核，保留单一可访问控件队列、无缝滚动、hover、触摸、页面可见性和 reduced-motion 行为；BGM / SFX 各自保留 wrapper、预设模型和业务 class。SFX wrapper 展示固定 `40 + 12` 预设，不保存展开、滚动或 hover 状态。
 - 参数与布局：SFX 首次打开为手动 `5s`、Loop false；手动 slider 为 `0.5-30s`、步进 `0.1s`，自动模式禁用 slider 但保留最近手动值。layout 恢复 `soundDurationMode / soundDurationSeconds / soundLoop`，历史 Vidu dialog 与改造入口统一打开固定 `eleven_text_to_sound_v2` / `ElevenLabs` 面板。前端显示新模型 `5` 泥点兜底，正式价格仍以后端 T5 入队冻结值为真相。
 - 锁与阶段边界：优化、提交或既有生成态只锁当前 SFX dialog 的输入、预设、滚动、参数、撤销和生成。提交 claim 同步冻结 canonical Prompt、时长模式、最近手动值与 Loop；T4 不改变正式请求的 nullable duration / Loop 映射，不接 Worker 翻译或 ElevenLabs，不修改服务端动态定价、计费、OSS、持久化详情、External v1、OpenAPI 或 SpacetimeDB schema。T4 必须与 T5 同一发布列车，不能单独发布。
+
+## 2026-08-07 SFX 生成优化 V2.0 T5 正式生成与 External v1
+
+- 正式执行链：站内与 External 请求在定价、预扣和 enqueue 前统一收敛为 canonical userPrompt、`model = eleven_text_to_sound_v2`、nullable 小数 duration 与 Loop；队列载荷不包含 actualPrompt。Worker 在既有冻结计费上下文内顺序执行 Luna 英文化、单次 ElevenLabs POST、MP3 校验 / 实际时长探测、OSS 和项目资源 / 账号素材 / 画布完成态写回，任一失败进入既有退款边界。queue 使用 job ID，inline 在 provider 前生成平台 Task ID，不伪造 provider task ID。
+- 权威结果：服务端只保留 Agent 身份关联字段并重建 SFX V2 `generation_inputs_json`，统一写入 userPrompt、actualPrompt、固定模型、duration mode、请求 / 实际时长和 Loop；客户端自报的实际英文 Prompt、实际时长、模型和 Loop 均被覆盖。信息弹窗展示中英 Prompt、实际时长、Loop、模型和完整平台 Task ID；重绘优先恢复 V2 metadata，自动模式恢复默认最近手动值 `5s`，不把实际输出时长当作手动请求值。历史 Vidu 素材仍按旧字段只读，并以新模型重绘。
+- 定价兼容：默认配置、api-server 与 SpacetimeDB 值校验同时要求保留 `audio1.0` 和新增 `eleven_text_to_sound_v2`。已存在的 SpacetimeDB 定价快照仅缺新键时，api-server 从当前受控默认 / override 补入该键后读取；其它缺失模型仍失败。该兼容不修改 schema、不在读取时写库，下一次后台保存自然持久化完整矩阵；队列计费、响应和资产成本继续使用入队冻结价格。
+- External v1：Rust DTO / handler、OpenAPI、幂等 canonical payload、compact result 与仓库 Agent Skill 同批演进。model 的省略 / null / 空串 / 纯 Unicode White_Space / 包围空白新模型 / 显式新模型统一入队；旧模型和未知非空值在 enqueue 前返回 `400`。完成结果增加实际 `durationSeconds` 与 Loop，继续隐藏 provider、userPrompt 和 actualPrompt，只暴露稳定结果引用。
+- 阶段状态：T1–T5 已完成，可以进入 T6；T6 仍需汇总 mock LLM / ElevenLabs / OSS 失败矩阵、计费退款、端到端等值、BGM 回归、API smoke、旧 Vidu 队列 drain 和发布 / 回滚门禁。T5 未执行真实 LLM、ElevenLabs 或其它付费请求，且没有 SpacetimeDB schema、migration 或 bindings 变更。

docs/【编辑器】模型定价配置管理方案-2026-06-22.md

@@ -35,6 +35,7 @@
       "prices": { "480p": 10, "720p": 20, "1080p": 40 }
     },
     "audio1.0": { "unit": "perGeneration", "price": 5 },
+    "eleven_text_to_sound_v2": { "unit": "perGeneration", "price": 5 },
     "chirp-v5": { "unit": "perGeneration", "price": 12 }
   }
 }
@@ -46,6 +47,7 @@
 - `price`：单一价格，适合音效、背景音乐等单次生成模型。
 - `prices`：档位价格，图片模型按尺寸档位配置，视频模型按分辨率配置。
 - 生图模型必须补齐支持尺寸：`gemini-3.1-flash-image-preview` 配 `0.5K / 1K / 2K`，`gpt-image-2` 配 `1K / 2K`。
+- 新编辑器 SFX 只读取 `eleven_text_to_sound_v2`；`audio1.0` 继续保留为历史 Vidu 配置兼容键，两者均按次独立配置。
 
 后端保存前校验当前正式模型、必要尺寸和必要分辨率都存在且大于 0。
 
@@ -61,6 +63,8 @@ SpacetimeDB 模块会在事务内重复执行同等强度的校验，并拒绝
 
 所有会调用外部生成 provider 的编辑器生成请求都必须由后端计算价格，前端请求不提交价格字段；同步执行按当前运行时配置进入 `execute_billable_asset_operation_with_cost` 预扣泥点，预扣失败不得继续调用上游。外部生成队列在入队时把价格写入 `external_generation_job.price_mud_points`，worker 必须用该冻结价格完成扣费、退款、响应和资产成本持久化，配置更新不得改变已入队任务金额。普通图片、规范、角色、UI 设计、宣发素材、快速编辑 / 图片修改、图标 spritesheet、UI 设计图提取素材、视频、角色动作、音效和背景音乐均遵循该规则。背景色决策（gpt-5-mini）本身也是一次上游调用，同样必须在预扣泥点之后发起：预扣前只做颜色无关的算价 / 校验（动画用默认色占位算价），决策放进 billable 闭包，余额不足则决策不跑、决策失败走失败退款。需要向前端展示实际扣费时，由后端在响应中返回 `priceMudPoints`。
 
+SFX V2 上线前已经存在的 SpacetimeDB 定价快照可能只有 `audio1.0`。读取这类历史快照时，`api-server` 只允许从当前受控默认配置或本地 override 补入缺失的 `eleven_text_to_sound_v2` 条目，使旧快照可继续读取；其它必需模型缺失仍失败。该兼容不修改 schema，也不在读取时写数据库；下一次后台保存完整定价矩阵时自然持久化新键。发布前仍应确认运行时配置中的新键和价格已经批准。
+
 ## 运行时身份首次授权
 
 模型定价 writer、外部生成队列和钱包调用都以真实 SpacetimeDB `ctx.sender()` 校验运行时服务 identity。原始 bootstrap secret 固定为 64 位十六进制；首次授权使用与当前 `spacetime_module.wasm` 构建时注入 SHA-256 摘要对应的原始值，模块收到原始值后重新计算 SHA-256 并做常量时间比较，WASM 只嵌入摘要、不嵌入原文。bootstrap secret 只能在配置表为空时建立首个受信身份，表存在后不能重复使用。queue 和钱包 runtime guard 只接受精确 `writer_identity`，迁移操作员身份不自动获得在线生成或钱包权限；因此当前生产 API、worker 和 controller 必须继承同一份 runtime token。非 HTTP 角色只做 queue procedure 鉴权预检，不具备 seed 或轮换身份的职责。migration operator 与 runtime writer 必须互斥：任何已登记 operator 都不能成为 writer，当前 writer 也不能被授权为 operator；一旦已有 operator，bootstrap secret 不得再新增或接管 operator。

docs/【编辑器】画布Agent对话面板-2026-07-03.md

@@ -96,7 +96,7 @@
 - `EditorAgentToolCall.args` 的正式持久化契约是**校验后的规范参数 JSON**，不是 LLM 返回的原始 JSON。api-server 收到工具调用后，必须先按已注册的 ToolArgs 反序列化、补齐字段默认值、删除未进入 ToolArgs 的未知 / 退役字段、执行工具参数校验，再重新序列化并写入 `args`；校验失败的调用不得持久化为待确认消息。所有有明确默认值的工具标量参数在强类型 ToolArgs 中必须使用非 `Option` 字段：调用方省略字段或把顶层字段显式传为 `null` 时，统一在 ToolArgs 反序列化前视为未提供，由 Serde 补齐默认值，并把具体默认值写入规范 `args`；没有默认值的必填字段显式传为 `null` 时同样按缺失处理.(for compatibility) 后续计价、确认展示和 job payload 不得再次使用 `unwrap_or` 补同一默认值。LLM 原始参数只作为本次规范化的瞬时输入，不作为执行或审计真相；确认、取消、任务回填与后续上下文统一读取同一条消息中的规范 `args`。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId`；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey`、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
 - api-server 内画布 Agent 工具统一实现 object-safe `EditorAgentTool: ToolDyn`。`validate_args`、计价、确认展示、worker job 构建、`format_execute_message` 和结果媒体投影都使用统一 JSON 边界；每个具体工具实现负责把 JSON 反序列化为自己的强类型 Args / 结果，并把校验与完成消息格式化转发到 `platform-editor-agent` 中既有的 typed `validate_args` / `format_execute_message`，不得在调用方复制工具规则。`editor_agent_tool(toolName, context)` 是唯一按工具名分派的位置，规划、确认和任务回填只调用返回的 dyn tool；新增工具必须补齐同一个 trait 实现和该工厂分支。LLM builder 的 `.tool(...)` 注册列表仍是独立显式清单，不属于本次动态分派。framework runner 必须在 `ToolCallOutput` 中保留工具返回的结构化 output；runner 写入 LLM memory 与 api-server 使用规范参数持久化 system text 时统一调用公开的 `format_tool_call_message`，不得丢弃 `TOOL_CALL_PENDING_MESSAGE` 后自行拼另一套“等待确认”输出。
 - `EditorAgentToolCall.displayArgs` 是必填、只读的用户确认展示投影，与 `args` 分离：
-  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；前端渲染模型字段时复用图片编辑器公共展示名映射，`gemini-3.1-flash-image-preview` 显示为 `nanobanana2`、`audio1.0` 显示为 `Vidu`、`chirp-v5` 显示为 `Suno`，视频模型显示现有产品标签，不得改写后端参数真相；
+  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；前端渲染模型字段时复用图片编辑器公共展示名映射，`gemini-3.1-flash-image-preview` 显示为 `nanobanana2`、`eleven_text_to_sound_v2` 显示为 `ElevenLabs`、历史 `audio1.0` 显示为 `Vidu`、`chirp-v5` 显示为 `Suno`，视频模型显示现有产品标签，不得改写后端参数真相；
   - `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与规范参数对应的 `imageId`，以及后端从已校验会话上下文解析出的 `objectKey`、`imageSrc`、可选 `thumbnailSrc` / `label` / `width` / `height`。
   - `extras.priceMudPoints` 保存创建待确认消息时按后端运行时模型定价快照计算的预计泥点消耗；前端统一展示为“预计消耗 N泥点”，不自行计算价格。
 - `displayArgs` 只能由 api-server 按已注册 tool 白名单，基于已经通过 ToolArgs 校验的 `args` 和当前请求开始时从 OSS 会话文档一次性构建的 `EditorToolContext` 生成；该 context 必须按 opaque `ImageId` 同时保存执行所需的 `dataKey` 与展示所需的图片地址、Object Key、缩略图、label、宽高，参数校验、确认展示和 job payload 统一查同一份 context。不能信任 LLM 自报的展示地址、标题或素材元数据。展示投影不参与确认执行，确认接口仍只读取同一条持久化 tool call 的 `args`，避免“看到的素材”和“实际执行的素材”分叉。

docs/【编辑器】画板音乐生成入口设计-2026-06-18.md

@@ -12,7 +12,7 @@
 
 音效与背景音乐继续使用同一个音频 composer，并由组件内的 `isSoundEffect = dialog.mode === 'audio-sound-effect'` 隔离行为。共享视图不等于共享业务规则：BGM 继续使用 Suno、200 字 canonical Prompt、30 个预设、AI 补全 / 简化、单层撤销和方案 A 提交锁；SFX V2 固定使用 ElevenLabs `eleven_text_to_sound_v2`、52 个预设、一键优化、自动中译英、自动 / 手动时长和 Loop。两条路径的 Prompt 模型、controller、预设 wrapper、锁和提交契约必须分别维护，不得交叉复用业务状态。
 
-SFX V2 已完成产品与技术口径冻结，T0 已通过，T1、T2、T3、T4 已完成，可以继续进入 T5；这不表示功能已上线。T2 已落地登录态一键优化 BFF 和仅生成流水线内部可见的 Worker 翻译 service，T3 已落地 ElevenLabs 直接二进制 adapter，T4 已落地 dialog-scoped 前端 controller、52 预设、优化 / 撤销、自动 / 手动时长与 Loop UI。翻译到正式 Worker、ElevenLabs、计费、持久化和 External v1 的接线仍属于 T5。在正式切换完成前，当前正式生成代码仍是 Vidu SFX V1 行为，T4 前端也不得单独发布。历史 Vidu 素材继续只读展示；重绘时使用历史用户 Prompt 打开 SFX V2 面板，新任务统一走 ElevenLabs，不回退 Vidu。
+SFX V2 已完成产品与技术口径冻结，T0 已通过，T1–T5 已完成，可以继续进入 T6 测试、灰度与发布门禁；这不表示功能已上线。登录态一键优化、Worker 翻译、ElevenLabs 直接二进制 adapter、dialog-scoped 前端交互以及正式提交 / Worker / 计费 / OSS / 权威 metadata / External v1 已完成接线。历史 Vidu 素材继续只读展示；重绘时使用历史用户 Prompt 打开 SFX V2 面板，新任务统一走 ElevenLabs，不回退 Vidu。T6 完成前仍不得发布。
 
 ## 入口与交互