feat(voice): 百炼声音复刻create_voice + TTS instruction情绪驱动(主TTS-昔涟复刻音色)

Docs/api-client.md

@@ -30,11 +30,13 @@
 | 7 | `/api/v1/sessions/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除次级会话及其消息** → `{data:{deleted:<id>}}`；主会话不可删回 `403 forbidden`；未注入 HistoryStore 回 `501` |
 | 8 | `/api/v1/personas` | GET | JWT | ✅ | `{data:[persona...]}` |
 | 9 | `/api/v1/audio/transcribe` | POST | JWT(owner) | ✅ | **语音→文本**：body `{audio:"<base64>",format?,deviceId?}` → `{data:{text}}`（走后端 STT，百炼 `qwen-audio-3.0-asr-flash`） |
-| 10 | `/api/v1/audio/speech` | POST | JWT(owner) | ✅ | **文本→音频**：body `{text,voice?,format?}` → `200` 音频字节（`Content-Type: audio/<format>`，非 JSON envelope，走后端 TTS，百炼 `cosyvoice-v3-flash`） |
+| 10 | `/api/v1/audio/speech` | POST | JWT(owner) | ✅ | **文本→音频**：body `{text,voice?,format?,instruction?}` → `200` 音频字节（`Content-Type: audio/<format>`，非 JSON envelope，走后端 TTS，百炼 `cosyvoice-v3-flash`，复刻音色可带 `instruction` 情绪指令） |
+| 11 | `/api/v1/audio/voice-clone` | POST | JWT(owner) | ✅ | **声音复刻建音色**：body `{url:"<公网参考音频URL>",prefix?}` → `{data:{voiceId}}`（走百炼 `voice-enrollment` create_voice） |
 
 > **语音 REST 源（`/api/v1/audio/*`，均 owner-only + 审计）**：原生/移动端用它上传/获取音频，**绕开 WS 4KB 帧限**。
 > - `POST /api/v1/audio/transcribe`：body `{audio:"<base64>", format?:"wav", deviceId?}` → `200 {data:{text}}`。`audio` 为 base64（或 data: URI）；`format` 为编码（`wav`/`mp3`/`ogg`，缺省 `wav`）；空 audio 回 `400`；未注入语音服务 `500 voice_unavailable`、识别失败 `500 stt_failed`。
-> - `POST /api/v1/audio/speech`：body `{text, voice?, format?}` → `200` 原始音频字节（`Content-Type: audio/<format>`），**非 JSON envelope**。`voice`/`format` 目前遵循服务端 `VOICE_TTS_VOICE_ID`/`VOICE_TTS_FORMAT` 配置（后续支持按请求覆盖）；空 text 回 `400`；未注入语音服务 `500 voice_unavailable`、合成失败 `500 tts_failed`、静默空音频 `500 tts_empty`。**声音复刻（响昔涟音色）**：先用参考音频（公网 URL）在百炼「声音复刻」建自定义音色，再把返回的 `voice_id` 配到 `VOICE_TTS_VOICE_ID`（本项目不做 create_voice）。
+> - `POST /api/v1/audio/speech`：body `{text, voice?, format?, instruction?}` → `200` 原始音频字节（`Content-Type: audio/<format>`），**非 JSON envelope**。`voice`/`format` 目前遵循服务端 `VOICE_TTS_VOICE_ID`/`VOICE_TTS_FORMAT` 配置（后续支持按请求覆盖）；`instruction` 为**可选** per-request 情绪/语气指令（如 `"语气开朗俏皮，像女朋友撒娇"`），只对**复刻/设计音色**生效——**系统音色 `longxiaochun_v3` 被服务端忽略，永不发送自由指令**（CosyVoice 系统音色需固定格式）；长度 ≤100 字符（汉字记 2）；未传时回退到服务端 `VOICE_TTS_INSTRUCTION`。空 text 回 `400`；未注入语音服务 `500 voice_unavailable`、合成失败 `500 tts_failed`、静默空音频 `500 tts_empty`。
+> - `POST /api/v1/audio/voice-clone`：body `{url:"<公网参考音频URL>", prefix?:"cyrene"}` → `200 {data:{voiceId}}`。`url` 为**公网可访问的参考音频 URL**（create_voice **只收 `input.url`，不收 base64**），音频要求 10~20s 连续清晰朗读、≤10MB、≥16kHz；`prefix` 为音色名前缀（**≤10 字母/数字**，缺省 `cyrene`）。返回的 `voiceId` 填到 `VOICE_TTS_VOICE_ID` 即可用该复刻音色合成（`target_model` 固定为 `VOICE_TTS_MODEL`，须与合成模型一致）。**URL 不写审计/日志（红线，绝不打日志）**。空 url 回 `400`；未注入语音服务 `500 voice_unavailable`；建音色失败 `500 voice_clone_failed`。**⚠️ 真建音色需主人提供公网参考音频 URL（当前无，断言待提供）；且需北京地域 API Key（CosyVoice 声音复刻仅华北2北京地域）。**
 
 ## 2. REST 端点（管理，`/api/v1/admin/*`）
 
@@ -202,6 +204,7 @@
 - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
 
 ## 5. 变更记录
+- `v0.19`（**百炼声音复刻 create_voice + TTS instruction 情绪驱动，主 TTS 用昔涟复刻音色**）：`POST /api/v1/audio/voice-clone`（**新增**，owner-only + 审计，body `{url:"<公网参考音频URL>", prefix?}` → `{data:{voiceId}}`）——走后端 `voice.DashscopeCloner`（百炼 `voice-enrollment` create_voice，`POST {base}/services/audio/tts/customization`，`input{action:create_voice, target_model:VOICE_TTS_MODEL, prefix, url}`，**只收公网 URL 不收 base64**，返回 `output.voice_id`；**URL 不打日志不写审计**）。`POST /api/v1/audio/speech` 新增**可选 `instruction`**（per-request 情绪/语气指令，如 `"语气开朗俏皮，像女朋友撒娇"`），经 ctx 透传给 TTS adapter；**只对复刻/设计音色生效**（`cosyvoice-v3-flash` 复刻音色可任意指令；系统音色 `longxiaochun_v3` 需固定格式，服务端 `canInstruct` 判定后**永不发送**）。config 新增 `VOICE_TTS_INSTRUCTION`（默认 `""`）、`VOICE_CLONE_PREFIX`（默认 `cyrene`，≤10 字母/数字）；`voice.Chain`/`voice.Service` 新增 `CloneVoice`，`VoiceCloner` 接口（cloud rung 提供；未配 cloud 回 `voice_unavailable`）。**⚠️ 真建昔涟音色仍待主人提供公网参考音频 URL（当前无）**，且 CosyVoice 声音复刻仅华北2北京地域（确认 key 地域）；TTS instruction 用现有复刻音色或先仅单测请求体，避免改系统音色行为。
 - `v0.18`（**后端语音接通阿里百炼 STT + TTS 主链路**）：`POST /api/v1/audio/transcribe`（**新增**，owner + 审计，body `{audio,format?,deviceId?}` → `{data:{text}}`，走 STT）；`POST /api/v1/audio/speech`（**新增**，owner + 审计，body `{text,voice?,format?}` → 音频字节 `audio/<format>`，走 TTS）——**REST 语音源**，原生/移动端经它绕开 WS 4KB 帧限上传/获取音频；WS `voice_input` 上行新增 **`deviceId`**（随语音轮次落库，design/16 §4.5）。后端 `internal/runtime/multimodal/voice` 的 cloud rung 由空 endpoint stub 改为**真实百炼 adapter**：STT `qwen-audio-3.0-asr-flash`（base64 原始字节→文本）、TTS `cosyvoice-v3-flash`（按 `voice_id` 合成，取非流式返回的 24h 音频 URL 下载字节）。**实测**（`DASHSCOPE_API_KEY` 实跑）：TTS「你好，我是昔涟」→ 106124 字节 wav；把该 wav 喂给 STT → 文本「你好，我是西联。」（TTS 发音把「昔涟」读得近似「西联」，STT 识别正确）；语音链 (cloud→…→silent) 返回真实字节/文本。**已实测修正**：`cosyvoice-v3.5-plus`/`longxiaochun`（v2 音色）走 HTTP `SpeechSynthesizer` 会回 `418`（引擎拒绝），改用 **`cosyvoice-v3-flash` + `longxiaochun_v3`**（v3 音色，各模型音色不可混用）。**声音复刻（响昔涟音色）仍待**：需参考音频（公网 URL）在百炼建自定义音色后把 `voice_id` 填入 `VOICE_TTS_VOICE_ID`（本项目不做 create_voice）。config 新增 `DASHSCOPE_BASE_URL`/`VOICE_STT_\*`/`VOICE_TTS_\*`（`VOICE_TTS_SAMPLE_RATE` 默认 24000）。
 - `v0.17`（系统设置安全与存储：吊销全部 API key / 轮换 JWT 密钥 / 备份 / 恢复，design/11 §4 + design/10 §3 模块14）：新增 `POST /api/v1/admin/system/{revoke-keys,rotate-jwt,backup,restore}`（均 **owner-only** + 审计）。`revoke-keys` 走 `auth.APIKey.RevokeAll()`（清空 key 表，返回 `{revoked:n}`）；`rotate-jwt` 走 `auth.JWTService.RotateSecret`（≥32 位，**新密钥不回显/不落日志**，现有 token 立即失效）；`backup` 用 SQLite `VACUUM INTO` 快照到 `<dataDir>/backup-<ts>.db`（含已提交 WAL 内容）返回 `{path,size}`；`restore` 先校验路径在 dataDir 内（**`filepath.Rel` 防路径穿越**，逃逸回 `400`）→ **先自动备份当前 DB** → 替换 DB 文件 → 返回 `{restored:true,backup,note:"需重启后生效"}`（运行进程持有 DB 句柄，热替换需重启可见）。gateway 新增 `Deps.DatabasePath`（composition root 传入实际打开的 SQLite 路径）。`编辑环境变量 / 重启服务 / 检查更新` 仍为后置，未实现、不伪造。
 - `v0.17`（KOOK 适配器面板 + 每适配器专属页，design/17 §2）：`GET /api/v1/admin/channels/{platform}/view`、`GET /api/v1/admin/channels/{platform}/friends?type=`、`POST /api/v1/admin/channels/{platform}/friend/handle`、`POST /api/v1/admin/channels/{platform}/message/test`（**新增**，均 owner-only + 审计，带可选 `?accountId=`，仅 `kook` 实现，其它平台 `501`）；`GET /api/v1/admin/channels` 每条账号附 `capabilities`（面板按平台渲染专属卡片）。KOOK 面板：好友/申请、服务器/频道/成员、私信会话、发消息测试——经适配器 REST（`Authorization: Bot <token>`）拉真实数据，token 不打印不落日志，子项失败记入 `errors` 不伪造。