Initial TrueGrowth source import

openspec/changes/add-suno-lyrics-task-and-canvas-flow/proposal.md

@@ -0,0 +1,81 @@
+# Change: 增加 Suno 歌词任务与画布落地适配
+
+## Why
+
+当前仓库已经具备 Suno 音乐生成的基础闭环：
+
+- `audio` 已经是一等生成模态
+- Suno 音乐提交与轮询已经有专门的 adapter / service
+- 任务队列、自动插入和画布音频节点都已经围绕“音频资产”建立了展示和落地路径
+
+但 `suno lyrics` 会打破当前实现里的一个默认前提：
+
+- 它沿用 Suno 的提交与查询链路
+- 但最终产物不是音频 URL，而是 `title / tags / text` 形式的文本结果
+
+如果继续沿用当前“`audio` 任务必然产出可播放 URL”的假设，就会出现三类问题：
+
+- 提交层无法选择 `/suno/submit/lyrics`
+- 结果提取层会因缺少 `audio_url` 而把任务判定为无结果
+- 任务队列、自动插入和画布会把歌词结果错误地当成音频卡片处理
+
+因此需要把 Suno 的“提交动作”和“最终结果类型”显式拆开，并把歌词任务融入现有队列与画布能力中。
+
+## What Changes
+
+- 在现有 `audio / suno` 路由体系内新增 `lyrics` 动作
+- 让 Suno 请求显式区分：
+  - 提交动作：`music` / `lyrics`
+  - 结果类型：`audio` / `lyrics`
+- 新增 `POST /suno/submit/lyrics` 提交适配，并继续复用 `/suno/fetch/{task_id}` 轮询
+- 为歌词查询结果增加标准化提取，保留 `text / title / tags / providerTaskId`
+- 调整任务结果模型与持久化结构，使文本歌词结果不再依赖媒体 URL
+- 在任务队列中为歌词任务提供独立展示与操作，而不是复用音频卡片假设
+- 在画布中将歌词结果插入为文本或 markdown 卡片，而不是音频节点
+- 在音频输入模式中增加动作切换，并让音乐专属参数只在 `music` 动作下展示
+
+## Scope
+
+### In Scope
+
+- `lyrics` 动作的 submit / fetch / normalize 闭环
+- 继续复用现有 `audio` 默认路由，不新增独立的 `lyrics` 默认路由
+- 新增 `sunoAction` 和歌词结果字段
+- 任务队列中的歌词任务展示、重试、恢复和插入能力
+- 画布文本插入路径对歌词结果的适配
+- 自动插入路径根据结果类型在音频卡片与文本内容之间分流
+
+### Out Of Scope
+
+- 独立的歌词编辑器或画布内富文本歌词组件
+- 一键把歌词任务自动串联成音乐生成任务
+- `suno-tags`、`suno_act_tags`、`suno-midi` 等其他 Suno 辅助动作
+- 为歌词结果新增独立的默认模型类型或独立的产品入口页
+
+## Impact
+
+- Affected specs:
+  - `audio-generation`
+  - `generation-task-queue`
+  - `canvas-generated-text`
+- Affected code:
+  - `packages/drawnix/src/services/audio-api-service.ts`
+  - `packages/drawnix/src/services/model-adapters/*`
+  - `packages/drawnix/src/services/provider-routing/*`
+  - `packages/drawnix/src/types/shared/core.types.ts`
+  - `packages/drawnix/src/services/task-queue-service.ts`
+  - `packages/drawnix/src/services/task-storage-reader.ts`
+  - `packages/drawnix/src/services/media-executor/task-storage-writer.ts`
+  - `packages/drawnix/src/components/ai-input-bar/*`
+  - `packages/drawnix/src/components/task-queue/*`
+  - `packages/drawnix/src/hooks/useAutoInsertToCanvas.ts`
+  - `packages/drawnix/src/services/media-result-handler.ts`
+  - `packages/drawnix/src/services/sw-capabilities/handler.ts`
+
+## Relationship To Existing Changes
+
+- 建立在 `add-audio-generation-suno-routing` 已定义的 `audio` 模态与 Suno 路由方案之上
+- 与 `add-canvas-audio-playback` 互补：
+  - 音乐结果继续进入音频节点
+  - 歌词结果进入文本插入链路
+- 本变更不会把歌词能力建成新的模态，而是在现有 `audio` 能力族中补齐新的动作和结果类型