后端：增加BGM提示词补全与简化接口

新增登录态补全与简化内部BFF及共享请求约束
实现OpenAI Chat四字段严格响应解析与180到170两轮简化
隔离上游错误与未通过候选并补齐重试和协议测试
同步权威设计与项目决策记录

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

@@ -123,21 +123,25 @@
 - 默认模型使用现有编辑器 Agent LLM 配置中的 `gpt-5.4-mini`；Prompt 助手复用现有 `LlmClient`，不建立新的平台 LLM 能力。
 - 服务端模板必须要求：保留用户明确的主题、场景、风格、情绪、乐器、能量、韵律、时长、循环和避免项；按场景选择性补足场景、氛围、能量、韵律、乐器、旋律、声音设计、循环和避免项，不为凑全方向堆砌形容词。
 - 用户描述已足够完整时，只补充一至两个与主题匹配的具体声音细节。发现冲突时，优先级为“明确避免项和限制 > 明确玩法用途与场景 > 风格、情绪、能量与韵律 > AI 补充细节”。
-- 输出只允许一条可直接写回输入框的中文 BGM Prompt；不得包含解释、标题、Markdown、JSON、代码块、具体艺人或歌曲模仿要求。
-- AI 输出先执行同一套首尾 Unicode 空白规范化，再由程序计算字符数。结果必须包含有效字符且不超过 200 个 Unicode code point；校验通过后整段写回输入框并成为唯一最终 Prompt。调用失败、结果为空、格式非法或超限时保留请求前已经写回的规范化 Prompt，不写回部分结果。
+- 内部 envelope 的 `prompt` 字段只允许包含一条可直接写回输入框的中文 BGM Prompt；候选文本本身不得包含解释、标题、Markdown、JSON、代码块、具体艺人或歌曲模仿要求。
+- 补全与简化共用同一份内部结构化 envelope：`prompt: string`、`isDirectWritebackFormat: boolean`、`isContentComplete: boolean`、`hasObviousFragment: boolean`。助手显式使用现有 OpenAI Chat 协议，envelope 由完整 `response.text` 中唯一一个 JSON object 承载；服务端只允许 `serde_json` 对完整文本做全量解析，允许 JSON object 外围存在 JSON whitespace，但不接受代码块、前后解释、多个 JSON 值或从字符串中截取 object，也不执行自动修复。助手请求不发送 function tools，不做运行时双协议 fallback；响应出现 tool call 时同样视为结构非法。envelope 只用于服务端解析和判断，不属于候选文本，不写回输入框，也不通过 BFF 暴露给客户端。
+- 补全候选先执行同一套首尾 Unicode 空白规范化，再由程序计算字符数。候选只有在四字段结构有效、canonical `prompt` 包含有效字符且不超过 200 个 Unicode code point，并且三个布尔字段依次为 `true / true / false` 时才通过；程序不使用关键词或未定义正则猜测候选格式、完整性或残句。通过后整段写回输入框并成为唯一最终 Prompt。
+- 补全只执行一个业务语义轮。`LlmClient` 在该轮内部按现有配置执行的 transport retry 不计为新增业务语义轮；该轮最终发生 transport、超时或上游失败时直接返回失败，不再发起内容修复轮。
+- 调用失败、结果为空、结构或判断不合格、格式非法或超限时保留请求前已经写回的规范化 Prompt，不写回部分结果；错误响应不得包含未通过候选或内部 envelope。
 - 补全过程不调用 Suno、不创建正式生成任务、不触发正式音乐生成扣费。
 
 ### 一键简化
 
 - 点击一键简化时先按统一规则规范化输入框首尾空白并同步写回；只在规范化后的当前 Prompt 总字符数超过 200 时允许调用。点击前保存这份规范化后的完整 Prompt，AI 处理中保持输入框不变。
-- 服务端在本次简化中冻结 `originalPrompt` 为入站 canonical Prompt，最多两次调用期间始终不变，作为内容保真参照。第一次调用使用 `currentPrompt = originalPrompt`，目标为 180 字。这里的 `originalPrompt` / `currentPrompt` 是服务端组装 LLM 简化模板时的内部变量；客户端简化 BFF DTO 仍只提交一个 `currentPrompt`，该入站值经 canonicalization 后同时成为内部 `originalPrompt` 和第一次内部 `currentPrompt`。
-- 180 不是硬门槛。每次调用要求返回内部结构化 envelope：`prompt: string`、`isDirectWritebackFormat: boolean`、`isContentComplete: boolean`、`hasObviousFragment: boolean`。envelope 不属于候选文本，也不得写回输入框；响应不能解析为包含上述正确字段类型的对象时，本次候选不通过。
+- 服务端在本次简化中冻结 `originalPrompt` 为入站 canonical Prompt，最多两个业务语义轮期间始终不变，作为内容保真参照。第一次业务语义轮使用 `currentPrompt = originalPrompt`，目标为 180 字。这里的 `originalPrompt` / `currentPrompt` 是服务端组装 LLM 简化模板时的内部变量；客户端简化 BFF DTO 仍只提交一个 `currentPrompt`，该入站值经 canonicalization 后同时成为内部 `originalPrompt` 和第一次内部 `currentPrompt`。每个业务语义轮内部由 `LlmClient` 按现有配置执行的 transport retry 不增加业务语义轮数。
+- 180 不是硬门槛。简化使用与补全相同的四字段内部结构化 envelope；envelope 不属于候选文本，也不得写回输入框或通过 BFF 暴露。响应不能解析为包含上述正确字段类型的对象时，本次候选不通过。
 - 候选“格式合法”专指 `isDirectWritebackFormat = true`：模型确认 canonical 候选只包含一条可直接写回输入框的中文 BGM Prompt，不包含解释、标题、Markdown、JSON、代码块、字数报告、处理过程或删改说明。它与“内部结构可解析”是两个独立校验项；程序不得另用关键词或未定义的正则推断标题、解释等语义格式。
-- 第一次候选未通过任一通过条件时，自动进行唯一一次重试，目标为 170 字。若第一次响应至少能解析为对象并提取字符串 `prompt`，且该字符串 canonicalize 后包含有效字符，第二次使用 `currentPrompt = canonicalize(第一次候选)`，即使第一次因其它字段缺失、超限、格式、完整性或残句判断而不通过；若第一次响应连对象或字符串 `prompt` 都无法提取，或候选 canonicalize 后不含有效字符，第二次回退使用 `currentPrompt = originalPrompt`。第二次调用中的 `originalPrompt` 始终仍是最初入站 canonical Prompt。
-- 每次候选都先执行同一套首尾 Unicode 空白规范化，再计算实际字符数。第二次仍不合格时返回失败并保留请求前已经写回的规范化 Prompt，提示用户手动精简；最多两次 LLM 调用，任何情况下都不得由程序截断到 200 字。
+- 第一次业务语义轮成功取得上游响应、但候选未通过任一通过条件时，自动进行唯一一个第二业务语义轮，目标为 170 字。只有当完整 `response.text` 已按上述规则全量解析为单个 JSON object 时，才允许从该 object 读取字符串 `prompt`；禁止从未完整解析的文本、代码块、解释或畸形 JSON 中做子串提取。若可提取的字符串 `prompt` canonicalize 后包含有效字符，第二次使用 `currentPrompt = canonicalize(第一次候选)`，即使第一次因其它字段缺失、超限、格式、完整性或残句判断而不通过；若完整响应无法解析为单个 object、object 中没有字符串 `prompt`，或候选 canonicalize 后不含有效字符，第二次回退使用 `currentPrompt = originalPrompt`。第二次业务语义轮中的 `originalPrompt` 始终仍是最初入站 canonical Prompt。
+- 第一次业务语义轮最终发生 transport、超时或上游失败时直接返回失败，不进入 170 字内容修复轮；这类失败只应用该轮内部既有的 `LlmClient` transport retry。
+- 每次候选都先执行同一套首尾 Unicode 空白规范化，再计算实际字符数。第二次仍不合格时返回失败并保留请求前已经写回的规范化 Prompt，提示用户手动精简；错误响应不得包含第一次或第二次未通过候选、可提取的 `prompt` 或内部 envelope。最多两个业务语义轮，任何情况下都不得由程序截断到 200 字。
 - 简化模板必须优先保留明确限制、场景与用途、情绪与风格、核心乐器与速度、能量/韵律/旋律、循环结构、区分度较高的声音设计，再删除次要修饰细节；不得改变专有名词、BPM、调性、时长、数值、乐器和明确限制。
 - 程序不抽取关键词，不对规范化后的输入与候选执行内容硬编码逐项比对。是否为直接写回格式、是否保留重要信息且内容完整、是否形成明显残句由 LLM 在同一次调用的三个布尔字段中分别判断。
-- BFF 对外只返回已通过校验的 Prompt 和程序计算的字符数，不暴露三个内部判断字段。
+- BFF 成功时只返回已通过校验的 Prompt 和程序计算的字符数，不暴露三个内部判断字段；失败时使用现有 API 错误 envelope，且不返回任何候选或内部判断字段。
 - 候选只有同时满足以下条件才通过：内部结构可解析且四个字段类型正确；canonical 候选包含有效字符；canonical 候选实际字符数不超过 200；`isDirectWritebackFormat = true`；`isContentComplete = true`；`hasObviousFragment = false`。程序负责解析和检查字段类型、canonicalization、有效字符与实际字符数，并执行三个布尔判断结果；字符数由程序计算且不采信模型报告，程序不自行推断三个语义判断。
 - 一键简化不维护或恢复“已选预设”元数据；预设已写入输入框的文本只是当前最终 Prompt 的一部分。
 
@@ -242,6 +246,7 @@ POST /api/editor/audios/background-music/prompts/simplifications
 - 客户端不得提交 `maxChars`、`targetChars`、模型名、预设 ID、分组、颜色、内部模板或格式 / 完整性 / 残句判断；这些由服务端固定或由内部 LLM 结果产生。
 - 两个助手 BFF 不调用 Suno、钱包扣费、正式 generation queue、OSS、素材库或 SpacetimeDB。
 - 两个助手请求中的 `currentPrompt` 必须是前端已经写回输入框的 canonical Prompt；响应 `prompt` 也必须先执行同一 canonicalization，`charCount` 是响应 canonical Prompt 的 Unicode code point 数。
+- 补全与简化成功响应都只包含上面的 `prompt` / `charCount` 业务字段；内部四字段 envelope、`originalPrompt`、目标字数、业务语义轮信息和未通过候选均不得出现在成功或失败响应中。失败继续使用现有 API 错误 envelope。
 - BGM 正式提交必须使用输入框已经写回的 canonical Prompt，不得额外拼接用户不可见内容，也不得把空 Prompt 回退为“游戏背景音乐”。
 
 统一响应：
@@ -287,7 +292,7 @@ POST /api/editor/audios/background-music/prompts/simplifications
 - 在 `api-server` 增加登录态内部 BGM Prompt 助手 BFF：
   - `POST /api/editor/audios/background-music/prompts/completions`
   - `POST /api/editor/audios/background-music/prompts/simplifications`
-- Prompt 助手 BFF 在入站和 LLM 候选出站边界执行 BGM canonicalization；服务端字符数、0 / 1 / 2 个有效字符规则和 200 字限制都基于 canonical Prompt。助手使用现有编辑器专用 LLM client 和 `gpt-5.4-mini` 默认配置；补全固定执行一次，简化按 `180 -> 170` 最多两次，并按“一键简化”章节冻结 `originalPrompt`、派生每次 `currentPrompt`。服务端负责模板组装、canonical 字符校验、内部 envelope 解析、执行格式 / 完整性 / 残句三个布尔判断和现有 API 错误 envelope；不自行猜测三个语义判断。
+- Prompt 助手 BFF 在入站和 LLM 候选出站边界执行 BGM canonicalization；服务端字符数、0 / 1 / 2 个有效字符规则和 200 字限制都基于 canonical Prompt。助手使用现有编辑器专用 LLM client、`gpt-5.4-mini` 默认配置和显式 OpenAI Chat 协议；补全固定执行一个业务语义轮，简化按 `180 -> 170` 最多两个业务语义轮，并按“一键简化”章节冻结 `originalPrompt`、派生每轮 `currentPrompt`。`LlmClient` 在单轮内部执行的 transport retry 不计入业务语义轮数，简化第一轮 transport、超时或上游失败不进入 170 字轮。服务端负责模板组装、canonical 字符校验、对完整 `response.text` 中单个 JSON object 的 `serde_json` 全量解析、补全与简化共用的内部 envelope 校验、执行格式 / 完整性 / 残句三个布尔判断和现有 API 错误 envelope；不自行猜测三个语义判断，也不向客户端返回未通过候选。助手不发送 function tools，不接受 tool call，不从代码块或解释中截取 JSON，不自动修复，也不做运行时双协议 fallback。
 - Prompt 助手继续复用 `LlmClient` 现有失败原文日志行为。本需求不增加请求级日志开关、脱敏、metadata-only 模式或相关上线门禁。
 - BGM generation BFF 在入站时防御性执行同一幂等 canonicalization，规范化后校验有效字符和 200 字限制，并把 canonical Prompt 写入正式 generation queue 请求载荷、持久化记录和响应；删除空 Prompt 默认回退。助手模板只用于生成输入框可见候选，不得进入正式队列或 Suno 请求。SFX 继续使用现有规范化、回退、Vidu body 和 1500 字限制。
 - BFF 复用现有 `vector_engine_audio_generation` 的任务轮询、下载、OSS 持久化和计费包装；音效 10 泥点，背景音乐 5 泥点。
@@ -316,8 +321,10 @@ POST /api/editor/audios/background-music/prompts/simplifications
 - BGM 输入框按 canonical Prompt 的 Unicode code point 显示 `0 / 200` 计数和动作状态，但编辑期间不因计数而改写输入框；canonical Prompt 为空时三个动作全部禁止，1 个有效字符且不超限时可以生成但不能 AI 补全，至少 2 个有效字符且不超限时可以 AI 补全，非空且达到 201 个 code point 时只能一键简化。200 / 201 个纯 Unicode `White_Space` 原始输入均先归一为空，不能简化。
 - 三组 30 个 BGM 预设按本文固定文案写入或追加；点击前先删除首尾 Unicode `White_Space` 并写回，再基于规范化结果判断空值和末尾标点。重复点击和追加后超限不得丢失 canonical Prompt，内部空格和内部换行保持原位。
 - 预设展开后默认无缝慢速循环，桌面端左 / 中 / 右区域分别加速向左、暂停、加速向右，左右箭头同步加速；组件在触摸环境被渲染时可横向滚动并选择词条，本需求不恢复移动端图片画布入口。
-- AI 补全的输入和候选都先 canonicalize；成功后只写回一条不超过 200 字的中文 canonical Prompt，失败、空值、格式错误或超限结果保留请求前已经写回的 canonical Prompt，也不调用 Suno 或扣除正式音乐生成泥点。
-- 一键简化资格、180 / 170 目标后的实际字符数和候选校验都基于 canonical Prompt；第一次使用冻结的 `originalPrompt`，第二次优先处理第一次可提取的非空 canonical 候选，否则回退处理 `originalPrompt`，且两次都以同一 `originalPrompt` 作保真参照。候选必须同时通过结构、有效字符、200 字、格式、完整性和残句校验；第二次仍失败时保留请求前已经写回的 canonical Prompt，程序不得截断。
+- AI 补全的输入和候选都先 canonicalize；补全只执行一个业务语义轮，候选必须通过共用四字段 envelope、有效字符、200 字和 `true / true / false` 三个判断后，才写回一条中文 canonical Prompt。失败、空值、结构或判断错误、格式错误或超限结果保留请求前已经写回的 canonical Prompt，错误响应不暴露候选，也不调用 Suno 或扣除正式音乐生成泥点。
+- 一键简化资格、180 / 170 目标后的实际字符数和候选校验都基于 canonical Prompt；第一次使用冻结的 `originalPrompt`，第二次优先处理第一次成功响应中可提取的非空 canonical 候选，否则回退处理 `originalPrompt`，且两个业务语义轮都以同一 `originalPrompt` 作保真参照。第一轮 transport、超时或上游失败直接失败，不进入第二轮；每轮内部的 `LlmClient` transport retry 不增加业务语义轮数。候选必须同时通过结构、有效字符、200 字、格式、完整性和残句校验；第二次仍失败时保留请求前已经写回的 canonical Prompt，不暴露任一未通过候选，程序不得截断。
+- Prompt 助手协议测试必须证明请求显式使用 OpenAI Chat 且不发送 function tools；只接受完整 `response.text` 全量解析所得的单个 JSON object。外围 JSON whitespace 可以通过，代码块、前后解释、多个 JSON 值、畸形 JSON、仅能子串提取的 object 和任意 tool call 均失败，不触发自动修复或运行时协议 fallback。
+- Prompt 助手轮次测试必须区分业务语义轮和单轮内部 transport retry：补全始终只有一个业务语义轮；简化只有第一轮成功返回但候选不合格时才进入 170 字轮，第一轮 transport、超时或上游失败不进入第二轮。
 - AI 补全和简化成功均产生一层 canonical Prompt 交换式撤销快照；手动编辑后仍可撤销，点击预设清除快照，点击撤销前先规范化当前输入并可在两个 canonical 版本间反复互换。
 - AI 操作的旧响应、关闭 dialog 后的响应或其它 dialog 的响应不得覆盖当前 Prompt；同一按钮双击只产生一个有效助手请求。
 - BGM 点击生成后在首个 `await` 前同步锁定当前 dialog；同一 dialog 快速重复点击只产生一次正式请求、一个生成任务和一次扣费，不锁整个画布或其它 dialog。