合并远端主分支更新

同步主分支音效生成与External v1契约更新
保留图标规范与图集生成链路
适配VectorEngine LLM客户端命名并解决前端提交语义冲突

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

@@ -6785,6 +6785,60 @@
 - 非目标：本次只规划视图归并，不实现 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 无法取得的本地资料。
+- 共享视图边界不变：`audio-sound-effect` 与 `audio-background-music` 继续共用 `ImageCanvasAudioGenerationComposerView`，通过 `isSoundEffect` 分流；SFX 和 BGM 的 Prompt 模型、controller、预设 wrapper、锁和提交契约分别维护，不新建独立页面或第二套音频系统。
+- 后端入口边界：正式生成原地演进 `server-rs/crates/shared-contracts/src/assets.rs` 的现有音频 DTO 与 `server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs` 的现有 handler，保留既有 `/api/editor/audios/*/generations` 路由、queue / inline 分流、计费和队列边界；不得新建平行 DTO、正式生成 BFF、handler 或第二套路由。只有 SFX Prompt 优化内部路由、Worker 翻译 service 和 ElevenLabs adapter 是新增能力。
+- provider 迁移：新编辑器 SFX 任务固定使用 ElevenLabs `eleven_text_to_sound_v2`，不提供模型选择、Vidu fallback 或 `audio1.0` alias。Vidu builder / 轮询仅保留给历史素材和其它未迁移调用方；历史素材可读，重绘新任务使用 ElevenLabs。
+- Prompt 真相：`prompt` 表示用户可见且确认的 canonical `userPrompt`，`actual_prompt` 表示 Worker 严格验收后实际提交给 ElevenLabs 的英文 `actualPrompt`。两者均以 2048 Unicode code points 为上限，只删除首尾 Unicode `White_Space`，不做其它规范化、默认 Prompt 回退或静默截断。
+- 可见交互：SFX 固定 40 个事件预设 + 12 个补充要求。空 Prompt 直接写入；非空 Prompt 末尾已是 Unicode 标点时直接追加，否则使用中文逗号 `，` 分隔。允许重复，不保留选中态，不去重或截断；点击预设清除旧快照。
+- Prompt 助手：一键优化使用 `gpt-5.6-luna`、`reasoning_effort = medium`；Worker 正式英文化使用同模型、`reasoning_effort = low`。两类候选上限均为 2048 Unicode code points，因此分别固定 completion tokens 总预算 `2048 × 4 = 8192`；该预算由隐藏 reasoning tokens 与可见输出 tokens 共享，不包含输入 Prompt tokens，也不是可见正文保证。当前 VectorEngine OpenAI Chat wire 固定发送 `max_completion_tokens = 8192`，内部历史字段名 `max_output_tokens` 不是业务语义。预算不按实际输入长度动态缩小；两者均不发送 temperature 或 function tools，只接受完整 `response.text` 中唯一 JSON object 的严格 envelope。翻译除要求 `isEnglish = true` 外，程序侧还要求候选至少含一个 Latin alphabetic code point，且所有 alphabetic code point 都属于 Latin Script；日文假名、韩文、西里尔、希腊和阿拉伯等非 Latin 字母均失败。优化只有一个业务语义轮，`finish_reason = length` 直接失败；翻译首轮成功响应但候选不合格或 `length` 时使用同一 `userPrompt`、同一 `8192` 上限唯一重试，第二轮 `length` 最终失败，`content_filter` 和 transport 最终失败不开启第二业务语义轮。翻译最终失败时 ElevenLabs 请求数必须为 0。
+- 撤销与锁：一键优化成功产生一层 canonical Prompt 交换快照；优化失败清除本次临时快照，不恢复更早快照。AI 操作和正式提交使用 dialog ID、账号 + 项目 scope、同步 operation ID 与 `AbortController`；只锁当前 SFX dialog。正式提交在第一个 `await` 前冻结 Prompt / duration / Loop；API 接受后结束 `submitting`、进入现有 `queued/generating` 占位，不把接受任务写成生成已完成。
+- 时长与 Loop：首次打开默认自动时长模式，预置最近手动值 `5s`、Loop false；手动范围 `0.5-30s`，UI 步进 `0.1s`。自动模式发送 `duration_seconds = null`，禁用 slider 但保留最近手动值。Loop 是独立 API 布尔参数；系统不根据 Prompt 推断、同步或校验 Loop，Prompt 文本与 Loop 开关不建立业务一致性门禁。
+- ElevenLabs 契约：`POST /v1/sound-generation`，body 固定 `text / model_id / duration_seconds / loop / prompt_influence=0.3`，query 固定 `output_format=mp3_44100_128`，`xi-api-key` 只在服务端 header 注入。provider POST 不自动重试，浏览器正式 POST 不 unsafe retry，队列 `max_attempts = 1`，一个平台 job 最多一次 ElevenLabs POST。成功响应复用现有 `MAX_GENERATED_AUDIO_BYTES = 40 MiB` 做 Content-Length 预检和 `limit + 1` 流式读取，验证 MIME 与真实 MP3，并探测有限正实际时长；实际时长仅受独立技术异常上限 `600s` 约束，不与请求最大 `30s` 比较，`30.5s-600s` 的合法结果可接受。平台使用 operation / queue job ID 作为 `taskId`，不伪造 provider task ID。
+- 结果真相：服务端重建 SFX V2 `generation_inputs_json`，写入 `userPrompt / actualPrompt / model / durationMode / requestedDurationSeconds / actualDurationSeconds / loop`；实际英文 Prompt、实际时长、model 和 Loop 不信任客户端自报。SFX V2 完成响应的 `durationSeconds` 使用同一 MP3 探测值；本条作为后出的 SFX 专项决策，仅在该完成响应上覆盖 2026-07-28“音频生成响应不得新增 `durationSeconds`”的通用口径，不新增资源 / 素材正式时长列，也不把该值写入 `EditorAsset`、`CanvasLayer`、layout 或图片序列字段。信息弹窗展示用户 Prompt、实际英文 Prompt、模型、实际时长、Loop 和平台 Task ID；历史 Vidu 数据不误标英文 Prompt。
+- 计费、External v1 与 schema：新模型键 `eleven_text_to_sound_v2` 保持 5 泥点 / 次，后端入队时冻结价格为真相。External v1 的 duration 演进为可选 / nullable `0.5-30 number`，Loop 缺省 false；`model` 的 omitted / null / 空串 / 纯空白 / 首尾空白包围的新模型 / 显式新模型统一 canonicalize 为 `eleven_text_to_sound_v2`，并产生相同幂等 payload。显式旧 `audio1.0` 和未知非空值返回 `400 BAD_REQUEST`，且必须为零入队、零预扣、零 LLM、零 provider；Rust、OpenAPI、幂等重放与最终响应必须在 T5 同批变更。本次不修改 SpacetimeDB schema，复用现有 `prompt`、`actual_prompt`、`generation_inputs_json` 和画布 layout。
+- 共享计划：脱敏 T1–T6 任务、当前基线、测试矩阵、旧 Vidu 队列 drain、发布与回滚门禁记录在 `docs/project-memory/plans/【实施计划】SFX生成优化V2.0任务拆解-2026-08-06.md`。T0 只验收设计、决策、共享计划、差距归属和安全记录，不要求当前 Vidu V1 代码、OpenAPI 或实际 API 已与 SFX V2 设计一致；实现差距归入 T1–T5，T6 统一验收。
+- 安全与状态：机器本地未跟踪资料不得进入提交，也不得被仓库文档链接、引用或作为团队证据源；ElevenLabs Key 只允许从服务端私密环境配置读取，不进入浏览器、日志、fixture、共享文档或 Git。T0 已通过，可以进入 T1–T5 实现；后续仍不得把秘密值、个人本地资料或不可审计记录写入仓库。
+
+## 2026-08-06 SFX 生成优化 V2.0 T2 助手与 Worker 翻译 service
+
+- 一键优化：新增登录态内部路由 `POST /api/editor/audios/sound-effects/prompts/optimizations`，复用 T1 的最小请求 / 响应 DTO、现有编辑器 `LlmClient`、标准成功 / 错误 envelope 和 route tracking。请求固定 Luna、OpenAI Chat、Medium、completion tokens 总预算 `8192`，当前 VectorEngine Chat wire 只发送 `max_completion_tokens=8192`，不发送 temperature 或 function tools；路由独立使用 `32 KiB` body limit，不增加功能级限流器，也不进入 External v1。
+- 优化验收：内部五字段 envelope 必须从完整 `response.text` 直接反序列化，允许外围 JSON whitespace，拒绝代码块、前后解释、多个 JSON、额外 / 重复字段、错误类型、tool call 和未完成 finish reason。候选只删除首尾 Unicode `White_Space`，要求 `1-2048` code points、至少一个 Han code point，并严格执行 `true / true / false / false`；失败 HTTP 响应不携带候选、内部 envelope 或上游回显正文。
+- 翻译 service：在现有 `vector_engine_audio_generation` 内新增仅 crate 内部生成流水线可见、没有同步 HTTP 路由的翻译 service。每个业务语义轮固定 Luna、OpenAI Chat、Low、completion tokens 总预算 `8192`，当前 VectorEngine Chat wire 只发送 `max_completion_tokens=8192`，不发送 temperature 或 tools；候选严格执行五字段结构、`true / true / true / false`、`1-2048` code points、至少一个 Latin alphabetic code point，且所有 alphabetic code point 都属于 Latin Script。Han、假名、韩文、西里尔、希腊和阿拉伯字母均失败，Common / Inherited 数字、标点、空白和符号允许。
+- 轮次与错误：首轮成功返回但结构、判断、Script、长度或 `finish_reason=length` 不合格时，只以同一 canonical `userPrompt` 开启唯一第二业务语义轮；不得读取或传递首轮候选。首轮 `content_filter` 和 transport / timeout / 上游最终失败直接结束；`LlmClient` 内部 transport retry 仍属于当前业务轮。第二轮任何失败均最终失败。service 错误展示只提供 `translation_invalid / translation_upstream_failed` 分类和安全中文消息，不保存或输出未通过候选。
+- 阶段边界：T2 没有调用 ElevenLabs、创建额外任务、扣费、修改队列 payload、持久化 `actual_prompt` 或变更 External v1 / OpenAPI / SpacetimeDB schema。T5 接入正式 Worker 时必须移除 T2 的 staged dead-code 豁免，并把翻译结果作为唯一 `actualPrompt` 进入 provider；T2 单独合入仍不是可发布切点。
+
+## 2026-08-07 SFX 生成优化 V2.0 T4 前端 controller 与参数 UI
+
+- 状态模型：SFX 使用独立于 BGM 的纯状态模型和 dialog-scoped controller。优化与提交均在第一个 `await` 前同步 claim operation；账号、项目、dialog、mode 与 `AbortController` 共同判定响应归属。关闭、删除、mode / scope 切换后的旧响应不能写回新面板；同一按钮双击只有第一个 operation 生效。
+- Prompt 与撤销：计数、优化、预设、撤销和提交统一复用 T1 的 Unicode `White_Space` canonicalizer 与 `1-2048` code point 规则。优化开始时以当前 canonical Prompt 替换旧快照，成功转为单层交换快照，失败清除本次临时快照且不恢复更早快照；预设写入清快照，手动编辑优化结果后仍可在两个 canonical 版本间反复交换。
+- 预设视图：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 变更。
+
+## 2026-08-07 SFX Prompt 边界 canonicalization 改为 ECMAScript trim
+
+- 决策：SFX 的 `userPrompt` 与 `actualPrompt` 从首尾 Unicode `White_Space` 规则改为 ECMAScript `String.trim()` 语义。TypeScript 直接使用 `String.trim()`；Rust 以等值边界字符集合实现，不能使用语义不同的 Rust `str::trim()`。因此首尾 `U+FEFF` 删除、首尾 `U+0085` 保留，内部空白、内部 `U+FEFF`、`U+200B`、组合字符和 ZWJ emoji 继续保持原样。
+- 范围：只影响 SFX Prompt 的输入、优化候选、Worker 翻译候选、正式请求、metadata 校验与 ElevenLabs body；BGM Prompt 以及 External v1 `model` 的 Unicode `White_Space` canonicalization 不变。
+- 验证：共享 fixture 锁定 ECMAScript 全部首尾删除字符、`U+FEFF` 边界删除与内部保留、`U+0085` 边界保留、内部空白和 `1 / 2048 / 2049` code point；前后端必须共同消费该 fixture。
+
+## 2026-08-07 SFX 生成优化 V2.0 T6 Worker 组合门禁
+
+- 正式编排：SFX Worker 以同一个内部编排函数串联现有计费、翻译、ElevenLabs、OSS、asset object / bind 候选准备和原子项目资源 / 账号素材 / 画布 / job 提交。生产 adapter 继续调用正式实现，测试 adapter 只替换外部边界；禁止另写与生产分叉的“测试专用业务流程”。
+- 失败与退款：余额不足时 Worker future 不得被 poll，LLM / ElevenLabs / OSS / 写回均为零；预扣后的翻译、provider、MP3、OSS 或写回失败全部一次退款。组合矩阵必须证明每个 job 的 ElevenLabs POST 最多一次、翻译最终失败 provider 为零、成功只扣费一次。
+- 分类：内部稳定 reason code 固定为 `translation_invalid / translation_upstream_failed / translation_budget_exhausted / elevenlabs_http_failed / invalid_audio / duration_probe_failed / oss_failed / writeback_failed`。MIME、空 body 和大小归 `invalid_audio`；MP3 识别、帧读取和时长门禁归 `duration_probe_failed`。普通用户继续只读稳定短文案，不暴露 endpoint、上游正文或凭据。
+- 跨入口：画布 Agent `generate-sound-effect` 与站内 / External v1 共用 canonical Prompt、固定模型、nullable `0.5-30` 小数时长和 Loop；省略 duration 为手动 `5s`，显式 null 为自动。SFX 参数解析必须保留该 null，不能被通用 null-default 兼容层改写。最终仍进入相同 `editor_sound_effect_generation` queue payload，不新增 Agent 专属链路。
+- 发布边界：T6 工程实施和 mock / loopback 门禁不等于真实 provider 或生产验收。发布前关闭 SFX 入队，使用显式 `--server` / `--server-url` 只读查询 `external_generation_job` 中 pending / running 的 `editor_sound_effect_generation`，清零后按 api-server / Worker → Web 顺序部署并灰度；禁止 `--root-dir`、删除任务伪造 drain 或自动回退 Vidu。本次没有 SpacetimeDB schema、migration 或 bindings 变更。
 ## 2026-08-06 编辑器生成结果使用 durable receipt 与统一原子提交
 
 - 背景：图片、改图、去背景、图集 / UI 多产物、角色动作、视频、音效和背景音乐在 OSS 结果可用后，仍分段 confirm object、创建 project resource / account asset、保存 canvas 和 complete job。任一中间失败都会留下部分业务事实；只把 `external_generation_job` 当 operation journal 又无法覆盖无 job 的 inline，也无法独立证明某批 resource/asset/canvas 已作为一笔提交完成。

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

@@ -4437,6 +4437,12 @@
 - 处理：先确定权威组件边界，再按完整调用链解决冲突。图片画布音频入口当前决策是恢复一个共享 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM/SFX 的 validator、写回、锁和提交契约仍分别保持。不要只补一个常量后继续维持已经废弃的双 composer 边界。
 - 验证：同时渲染 `audio-sound-effect` 与 `audio-background-music`，覆盖两个 mode 的正向控件和互斥负向断言、dialog / mode 切换、BGM 稳定 ID 与 controller 缺失的失败关闭，并运行 `ImageCanvasGenerationComposerView.test.tsx` 与 typecheck。
 
+## SFX Worker 不能只靠分层单测证明退款和零副作用（2026-08-07）
+
+- 现象：LLM、ElevenLabs adapter、OSS 和 metadata 各自测试都通过，但无法直接证明余额不足时外部调用为零、翻译失败不会调用 provider、OSS / DB 失败只退款一次，或项目资源 / 素材 / 画布使用同一份权威 metadata。
+- 原因：正式 SFX handler 把计费、翻译、provider、持久化和写回内联在一个 future 中；分层测试只能证明单个 helper，不能证明组合顺序和“失败后不继续”。同时若把 mock 流程另写一遍，它本身又可能与生产逻辑漂移。
+- 处理：抽出单一 Worker 编排函数和计费 / stage adapter。生产 adapter 代理现有正式实现：OSS 后只准备 asset object / binding 候选，项目资源、账号素材、画布和 job 终态通过同一原子提交落库；测试 adapter 逐段记录调用与注入失败。组合矩阵同时断言 charge / refund、LLM / provider / OSS / writeback 计数、稳定 reason code 和权威值等值。ElevenLabs 二进制、MIME、大小、timeout 和 MP3 仍由 loopback adapter 测试负责，组合 mock 不替代协议测试。
+- 验证：自动 / 手动时长 × Loop 四组合成功；余额不足；翻译、HTTP、无效音频、时长探测、OSS PUT / HEAD、asset confirm / bind、项目资源、账号素材和画布写回逐点失败；所有 job provider POST `<= 1`，预扣后失败 refund `= 1`。
 ## 生成结果的稳定 ID 和 job 终态都不能代替 durable receipt（2026-08-06）
 
 - 现象：Provider / OSS 已成功，但项目资源、账号素材、binding、画布和 job 只完成一部分；不确定结果重放时，有时又复制一批素材或重复推进 canvas revision。inline 路径在进程重启后尤其无法判断前一次提交是否整笔完成。