feat(tts): StepFun voice selection via CharacterDesigner + provider-aware beat-audio

Make homepage cards and live sessions produce sound when the server is
configured for StepFun TTS, instead of silently failing (the prebaked
Xiaomi voice was useless on a StepFun server, and wasted ~220KB/beat in
Fast Origin Transfer).

Three coordinated changes:

1. CharacterDesigner now picks a StepFun preset voice id directly from the
   32-entry catalog in the SAME LLM call that designs the character — zero
   extra latency, LLM-grade match quality. The Xiaomi prompt path is
   byte-identical to history (verified programmatically) so cache hit rate
   and voice quality are preserved. pickStepfunVoiceId (keyword scorer)
   remains the fallback for orphan speakers / invalid LLM picks.

2. The 32-preset catalog moves to lib/tts-client/stepfun-voices.json as the
   single source of truth, shared by the scorer, the CharacterDesigner
   prompt, /api/tts-provider, and the offline enrich script.

3. A new GET /api/tts-provider endpoint lets the client probe the server's
   TTS provider at /play mount. fetchBeatAudio then shapes its request body:
   on a StepFun server it sends the lightweight stepfunVoiceId /
   voiceDescription and omits the ~220KB Xiaomi reference audio (FOT saving
   ~13MB per protagonist per session on prebaked cards). requestBeatAudio
   re-provisions on a provider mismatch before synth, so audio never goes
   silent on a cross-provider replay or mid-session provider flip.

New type fields are all optional and backward-compatible: Character.stepfunVoiceId,
BeatAudioRequest.voiceDescription/characterName/stepfunVoiceId, voice made
optional. AGENTS.md updated for the new route, type fields, dependency map,
and StepFun voice-selection flow.

lib/engine/agents/characterDesigner.ts

@@ -1,5 +1,10 @@
 import { chat, generateImage } from "@infiplot/ai-client";
-import { provisionVoice } from "@infiplot/tts-client";
+import {
+  isStepfun,
+  isValidStepfunVoiceId,
+  provisionVoice,
+  type ProvisionVoiceOptions,
+} from "@infiplot/tts-client";
 import type {
   Character,
   CharacterVoice,
@@ -9,7 +14,7 @@ import type {
 import { parseJsonLoose } from "../jsonParser";
 import { mockImageDataUri } from "../mockImage";
 import {
-  CHARACTER_DESIGNER_SYSTEM,
+  buildCharacterDesignerSystem,
   buildCharacterDesignerUserMessage,
   buildCharacterPortraitPrompt,
 } from "../prompts";
@@ -34,6 +39,10 @@ import {
 type CharacterDesignOutput = {
   visualDescription?: string;
   voiceDescription?: string;
+  /** Only present on the StepFun path (the system prompt asks for it when
+   *  stepfun:true). Hallucinated / out-of-catalog ids are dropped before
+   *  they reach provisioning, falling back to pickStepfunVoiceId. */
+  stepfunVoiceId?: string;
 };
 
 // TEMP: per-phase timing for latency diagnosis. Same convention as the
@@ -50,7 +59,7 @@ async function runDesignLLM(
   const raw = await chat(
     config.text,
     [
-      { role: "system", content: CHARACTER_DESIGNER_SYSTEM },
+      { role: "system", content: buildCharacterDesignerSystem({ stepfun: stepfunEnabled(config) }) },
       {
         role: "user",
         content: buildCharacterDesignerUserMessage(charName, session),
@@ -61,6 +70,13 @@ async function runDesignLLM(
   return parseJsonLoose<CharacterDesignOutput>(raw);
 }
 
+/** True when the server's TTS config points at StepFun (so the CharacterDesigner
+ *  should also pick a preset voice id). Returns false when TTS is off or on the
+ *  Xiaomi path — keeping the Xiaomi prompt byte-identical to history. */
+function stepfunEnabled(config: EngineConfig): boolean {
+  return !!config.tts && isStepfun(config.tts);
+}
+
 // Generate the per-character base portrait. The portrait is a "concept
 // sheet" — single character, neutral pose, plain background — so it works
 // well as a Runware referenceImages anchor for later scenes.
@@ -105,10 +121,11 @@ export async function provisionCharacterVoice(
   config: EngineConfig,
   voiceDescription: string,
   charName: string,
+  opts?: ProvisionVoiceOptions,
 ): Promise<CharacterVoice | undefined> {
   if (!config.tts) return undefined;
   try {
-    return await provisionVoice(config.tts, voiceDescription, charName);
+    return await provisionVoice(config.tts, voiceDescription, charName, opts);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`[characterDesigner] voice provision failed for ${charName}: ${msg}`);
@@ -120,10 +137,18 @@ export async function provisionCharacterVoice(
 // call. The director then schedules renderCharacterPortrait /
 // provisionCharacterVoice around the Painter. Multiple new characters in the
 // same scene run this stage in parallel at the director level.
+//
+// On the StepFun path the same call ALSO yields stepfunVoiceId (the model
+// picks from the 32-preset catalog it sees in the system prompt). An invalid
+// pick is dropped here so the downstream provision falls back to the keyword
+// scorer — never trust an LLM-hallucinated id at the synth boundary.
 export type CharacterCard = {
   name: string;
   visualDescription?: string;
   voiceDescription: string;
+  /** Only set on the StepFun path AND only when the LLM picked a valid catalog
+   *  id. Threads through provisionCharacterVoice → stepfunProvision. */
+  stepfunVoiceId?: string;
 };
 
 export async function designCharacterCard(
@@ -135,12 +160,19 @@ export async function designCharacterCard(
   const design = await runDesignLLM(config, session, charName);
   tlog(`[charDesigner ${charName}] design LLM`, tDesign);
 
+  // Drop invalid catalog picks before they reach provision/synth. A hallucinated
+  // id would 4xx at synth time; better to fall back to pickStepfunVoiceId now.
+  const stepfunVoiceId = isValidStepfunVoiceId(design.stepfunVoiceId)
+    ? design.stepfunVoiceId
+    : undefined;
+
   return {
     name: charName,
     visualDescription: design.visualDescription?.trim() || undefined,
     voiceDescription:
       design.voiceDescription?.trim() ||
       `请根据角色名「${charName}」推断其性别、年龄与气质，生成最贴合的音色。所属世界观：${session.worldSetting}`,
+    stepfunVoiceId,
   };
 }
 

lib/engine/director.ts

@@ -305,8 +305,13 @@ export async function directScene(
   }
 
   // Kick off voice provisioning for every NEW char (never on the paint path).
+  // On the StepFun path, thread the LLM-selected stepfunVoiceId from the card
+  // into provision — it lets stepfunProvision honor the catalog pick instead
+  // of falling back to the keyword scorer (same network cost: still zero).
   const voicePromises = cards.map((card) =>
-    provisionCharacterVoice(config, card.voiceDescription, card.name).then(
+    provisionCharacterVoice(config, card.voiceDescription, card.name, {
+      stepfunVoiceId: card.stepfunVoiceId,
+    }).then(
       (voice): Character => ({
         name: card.name,
         voiceDescription: card.voiceDescription,

lib/engine/orchestrator.ts

@@ -1,6 +1,7 @@
 import type {
   BeatAudioRequest,
   BeatAudioResponse,
+  CharacterVoice,
   EngineConfig,
   FreeformClassify,
   FreeformClassifyRequest,
@@ -17,6 +18,7 @@ import type {
 } from "@infiplot/types";
 import { coerceOrientation } from "@infiplot/types";
 import { chat } from "@infiplot/ai-client";
+import { isStepfun, isValidStepfunVoiceId, provisionVoice } from "@infiplot/tts-client";
 import { runArchitect } from "./agents/architect";
 import { selectStyle } from "./agents/styleSelector";
 import { directInsertBeat, directScene } from "./director";
@@ -241,11 +243,70 @@ export async function requestInsertBeat(
 //  timeout / failure / TTS disabled, so the client just plays silent.
 // ──────────────────────────────────────────────────────────────────────
 
+// Resolve a synth-ready voice for the request, normalizing provider
+// mismatches. The client usually sends a voice whose provider matches the
+// server's TTS (the common case). The mismatch case is mainly prebaked
+// homepage cards: they ship a Xiaomi voice baked at build time, but the
+// server may now run StepFun — so the client skips the ~220KB reference
+// audio (saving FOT) and sends stepfunVoiceId / voiceDescription instead.
+// We re-provision against the SERVER's provider so the right voice synth runs.
+// Returns undefined when there's nothing to synthesize from (caller plays
+// silent).
+async function resolveVoice(
+  config: EngineConfig,
+  req: BeatAudioRequest,
+): Promise<CharacterVoice | undefined> {
+  const serverStepfun = !!config.tts && isStepfun(config.tts);
+  const voiceProvider = req.voice?.provider;
+
+  // Fast path: the client sent a matching voice. (Also covers the legacy
+  // xiaomi card + xiaomi server case where the 220KB was unavoidable anyway.)
+  if (req.voice && (voiceProvider === "stepfun") === serverStepfun) {
+    return req.voice;
+  }
+
+  // Mismatch (or voice omitted). Re-provision against the server's provider.
+  if (!config.tts) return undefined;
+
+  // StepFun server: prefer an LLM-picked / prebaked id (zero-cost), else
+  // fall back to the keyword scorer over the voiceDescription.
+  if (serverStepfun) {
+    if (isValidStepfunVoiceId(req.stepfunVoiceId)) {
+      return provisionVoice(config.tts, req.voiceDescription ?? "", req.characterName, {
+        stepfunVoiceId: req.stepfunVoiceId,
+      });
+    }
+    if (req.voiceDescription) {
+      return provisionVoice(config.tts, req.voiceDescription, req.characterName);
+    }
+    return undefined;
+  }
+
+  // Xiaomi server but client sent a StepFun voice (or nothing). Re-design via
+  // voicedesign using the description; no description → can't synthesize.
+  //
+  // NOTE: this re-provision runs OUTSIDE synthesizeBeat's 15s withTimeout — a
+  // hung MiMo voicedesign tail (~30-70s) could hang /api/beat-audio until the
+  // platform timeout. Accepted because: (1) this path only fires on a rare
+  // cross-provider replay (.infiplot carrying a stepfun voice, opened on a
+  // Xiaomi-server deploy) or a mid-session provider flip — NOT the common
+  // prebaked-card + stepfun-server case, which is a pure-function provision
+  // with no network; (2) it degrades to silence rather than crashing. If it
+  // ever bites in practice, wrap resolve+synth in one withTimeout in voice.ts
+  // (requires threading an AbortSignal through provisionVoice → xiaomiProvision).
+  if (req.voiceDescription) {
+    return provisionVoice(config.tts, req.voiceDescription, req.characterName);
+  }
+  return undefined;
+}
+
 export async function requestBeatAudio(
   config: EngineConfig,
   req: BeatAudioRequest,
 ): Promise<BeatAudioResponse> {
   if (!config.tts) return { audio: null };
-  const audio = await synthesizeBeat(config.tts, req.voice, req.beat);
+  const voice = await resolveVoice(config, req);
+  if (!voice) return { audio: null };
+  const audio = await synthesizeBeat(config.tts, voice, req.beat);
   return { audio };
 }

lib/engine/prompts.ts

@@ -7,6 +7,7 @@ import type {
   StoryState,
   WriterPlan,
 } from "@infiplot/types";
+import { formatStepfunCatalogForPrompt } from "@infiplot/tts-client";
 
 // ══════════════════════════════════════════════════════════════════════
 //  Multi-agent scene generation pipeline:
@@ -599,7 +600,14 @@ function collectPriorSceneKeys(session: Session): string[] {
 //  (e.g., gentle-looking character with energetic voice).
 // ──────────────────────────────────────────────────────────────────────
 
-export const CHARACTER_DESIGNER_SYSTEM = `你是视觉小说的「角色设定师」。给你一个**新登场角色的名字**，你要为这个角色同时设计两份卡片：
+// CHARACTER_DESIGNER_SYSTEM is split into a provider-agnostic CORE (visual +
+// voice-text rules) and a provider-specific TAIL (the JSON contract). When the
+// server runs StepFun, the tail additionally asks the model to pick a preset
+// voice id from the 32-entry catalog — so the SAME LLM call that designs the
+// character also selects its voice, at zero extra latency. When StepFun is
+// off (Xiaomi / no TTS), the tail is byte-identical to the historical prompt
+// (Xiaomi path is cache- and behavior-preserving).
+const CHARACTER_DESIGNER_SYSTEM_CORE = `你是视觉小说的「角色设定师」。给你一个**新登场角色的名字**，你要为这个角色同时设计两份卡片：
 1. **视觉设定卡（英文）**——给生图模型 FLUX 用，遵循 prompt engineering 风格
 2. **音色设定卡（中文）**——给小米 MiMo 配音设计用
 
@@ -652,7 +660,12 @@ export const CHARACTER_DESIGNER_SYSTEM = `你是视觉小说的「角色设定
 - 随后描述：年龄段（如「约17岁少女」「30 出头男性」）、音色质感、性格情绪基调、语速节奏、人设腔调、口音方言
 - 用中文，整段连续描述，不分段
 - 长度：50–80 个中文字为宜
-- 例："女性，约17岁少女，音色清亮带点稚嫩甜美，性格开朗外向但容易害羞，语速偏快，标准普通话"
+- 例："女性，约17岁少女，音色清亮带点稚嫩甜美，性格开朗外向但容易害羞，语速偏快，标准普通话"`;
+
+// JSON-contract tail for the NON-stepfun path (Xiaomi voicedesign / no TTS).
+// Byte-identical to the historical prompt so the Xiaomi path keeps its cache
+// hit rate and voice quality unchanged.
+const CHARACTER_DESIGNER_TAIL_DEFAULT = `
 
 必须输出严格 JSON：
 {
@@ -662,6 +675,43 @@ export const CHARACTER_DESIGNER_SYSTEM = `你是视觉小说的「角色设定
 
 不要输出 JSON 以外的任何文本。`;
 
+// JSON-contract tail for the StepFun path. Same core output, plus the model
+// picks a preset voice id from the catalog. The id must match the SAME person
+// the voiceDescription describes (gender / age / vibe) — designed together so
+// appearance and voice stay coherent (the same invariant the CORE enforces).
+const CHARACTER_DESIGNER_TAIL_STEPFUN = `
+
+**StepFun 预设音色选择（必做）：**
+除 voiceDescription 外，你还必须从下列 StepFun 预设音色清单中，为本角色挑选一个与 voiceDescription 描绘的「同一个人」（性别 / 年龄段 / 气质都要一致）最贴合的预设，并把它的 id 填入 stepfunVoiceId。清单：
+${formatStepfunCatalogForPrompt()}
+
+挑选原则：
+- stepfunVoiceId 必须是上表里某个 id，原样复制（拼写、大小写、连字符都不能变）。
+- 必须与 voiceDescription 的性别一致（男声选 male 行，女声选 female 行）。
+- 年龄段尽量一致；拿不准时优先气质匹配（例如“冷艳御姐”选 lengyanyujie、“软萌萝莉”选 ruanmengnvsheng）。
+- 不允许编造清单外的 id，也不允许留空。
+
+必须输出严格 JSON：
+{
+  "visualDescription": "English visual card, comma-separated tags...",
+  "voiceDescription": "中文音色卡，以性别开头...",
+  "stepfunVoiceId": "清单内某个 id"
+}
+
+不要输出 JSON 以外的任何文本。`;
+
+/** Build the CharacterDesigner system prompt, provider-aware.
+ *  - stepfun:false → identical to the historical Xiaomi/no-TTS prompt.
+ *  - stepfun:true  → additionally asks the model to pick a StepFun preset
+ *    voice id from the 32-entry catalog (see formatStepfunCatalogForPrompt). */
+export function buildCharacterDesignerSystem(opts: {
+  stepfun: boolean;
+}): string {
+  return opts.stepfun
+    ? CHARACTER_DESIGNER_SYSTEM_CORE + CHARACTER_DESIGNER_TAIL_STEPFUN
+    : CHARACTER_DESIGNER_SYSTEM_CORE + CHARACTER_DESIGNER_TAIL_DEFAULT;
+}
+
 export function buildCharacterDesignerUserMessage(
   charName: string,
   session: Session,