@kmchai/cortico-world-voice 0.1.0 → 0.2.0

package/src/world.ts

@@ -2,8 +2,8 @@
  * 语音 World:把回复念出来。
  *
  * 触发层从主 session 输出流与事件库认出要念的话;文本层过滤与切句;
- * 合成层按配置的协议适配器取音频;出口层本机播放、发事件或只返回附件。
- * 这一层不 import 任何具体 TTS 包,也不 import 唱歌插件。
+ * 合成层经 HTTP 调 Kmch AI · 服务;出口层本机播放、发事件或只返回附件。
+ * 这一层不解析任何 TTS 方言,也不监听端口。
  */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -14,24 +14,26 @@ import type {
   Logger, ToolDef, ToolOutcome, World, WorldHost, WorldLamp, WorldWebUiDecl,
 } from 'cortico/core/types.ts';
 import { nullLogger, nowIso } from 'cortico/core/util.ts';
-import { backendOf } from './backends/index.ts';
-import { VOICE_DEFAULTS, VOICE_ID, VOICE_OPTIONS_KIND, voiceConfigGroups, voiceText } from './config.ts';
+import { VOICE_DEFAULTS, VOICE_ID, VOICE_MODELS_KIND, VOICE_OPTIONS_KIND, voiceConfigGroups, voiceText } from './config.ts';
 import type { AudioPlayer } from './audio/player.ts';
 import { createPlayer } from './audio/player.ts';
 import { SpeechQueue, type SpeechJob } from './audio/queue.ts';
-import { startVoiceHttp, type VoiceHttpHandle } from './http.ts';
-import { registerVoiceOptions } from './options.ts';
-import { singHealth, singRemote, singRequestOf } from './sing.ts';
+import { registerOptions, unregisterOptions } from './options.ts';
+import { ServiceClient, type SpeechService } from './service.ts';
 import { splitSpeech, truncateSpeech } from './speech/chunk.ts';
+import { buildInstruct, resolveStyle } from './speech/style.ts';
 import { filterSpeech } from './speech/text.ts';
 import { EventPoller, eventTypes, hasKeyword, latestUserText, splitList, VoiceTap } from './triggers.ts';
 import { VOICE_TOOL_DECLS } from './tools.ts';
-import type { BackendHealth, TtsAudio, TtsBackend, TtsRequest, VoiceConfigSection, VoiceOption } from './types.ts';
+import type {
+  ModelOption, ServiceHealth, TtsAudio, TtsRequest, VoiceConfigSection, VoiceOption,
+} from './types.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
 const DEDUPE_WINDOW_MS = 5000;
+const HEALTH_INTERVAL_MS = 15_000;
 const HEALTH_TTL_MS = 15_000;
-const VOICES_TTL_MS = 10 * 60_000;
+const CATALOG_TTL_MS = 10 * 60_000;
 
 export interface VoiceWorldDeps {
   fetch: typeof fetch;
@@ -39,8 +41,8 @@ export interface VoiceWorldDeps {
   rng(): number;
   now(): number;
   sleep(ms: number): Promise<void>;
-  /** 测试用:替换协议适配器。 */
-  backend?: TtsBackend;
+  /** 测试用:替换服务客户端。 */
+  service?: SpeechService;
 }
 
 export interface VoiceWorldOptions {
@@ -61,8 +63,12 @@ interface EnqueueOptions {
   voice?: string;
   speed?: number;
   silent?: boolean;
-  /** 不切块:唱歌与要交出去的附件要一整段。 */
-  single?: boolean;
+}
+
+interface ServiceState {
+  ok: boolean;
+  detail?: string;
+  at: number;
 }
 
 function defaultDeps(): VoiceWorldDeps {
@@ -84,6 +90,17 @@ function asNumber(value: unknown): number | undefined {
   return Number.isFinite(n) ? n : undefined;
 }
 
+/** 徽标只显示主机与端口;地址不合法时退回原串。 */
+function serviceHost(raw: string): string {
+  const value = raw.trim();
+  if (!value) return '—';
+  try {
+    return new URL(value).host || '—';
+  } catch {
+    return value;
+  }
+}
+
 /** 等一个 promise;超时返回 'timeout',不取消原任务。 */
 async function within<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {
   let timer: NodeJS.Timeout | undefined;
@@ -104,27 +121,36 @@ export class VoiceWorld implements World {
   private readonly player: AudioPlayer | null;
   private readonly queue: SpeechQueue;
   private readonly tap: VoiceTap;
+  private readonly service: SpeechService;
   private host: WorldHost | null = null;
-  private http: VoiceHttpHandle | null = null;
-  private httpError = '';
   private poller: EventPoller | null = null;
   private healthTimer: NodeJS.Timeout | null = null;
   private started = false;
   private tempDir = '';
   private tempSeq = 0;
-  private backendState: { ok: boolean; detail?: string; at: number } | null = null;
+  private serviceState: ServiceState | null = null;
   private probing = false;
-  private singReady = false;
   private voices: VoiceOption[] = [];
   private voicesAt = 0;
   private voicesSignature = '';
   private voicesLoading = false;
+  private models: ModelOption[] = [];
+  private modelsAt = 0;
+  private modelsSignature = '';
+  private modelsLoading = false;
   private readonly lastSpoken = new Map<string, number>();
   private lastFailureAt = 0;
+  private readonly modelOptions = (): readonly ModelOption[] => this.models;
+  private readonly voiceOptions = (): readonly VoiceOption[] => this.voices;
 
   constructor(private readonly opts: VoiceWorldOptions) {
     this.log = opts.log ?? nullLogger();
     this.deps = { ...defaultDeps(), ...opts.deps };
+    this.service = this.deps.service ?? new ServiceClient({
+      fetch: this.deps.fetch,
+      secret: (name) => this.opts.secret(name),
+      cfg: () => this.cfg,
+    });
     this.player = this.deps.createPlayer(this.log);
     this.queue = new SpeechQueue({
       player: this.player,
@@ -141,7 +167,6 @@ export class VoiceWorld implements World {
       onText: (text, source) => this.consider(text, source),
       onAbort: () => this.queue.hush(),
     });
-    registerVoiceOptions(() => this.voiceOptions());
   }
 
   private get cfg(): VoiceConfigSection {
@@ -152,11 +177,9 @@ export class VoiceWorld implements World {
     const cfg = this.cfg;
     return {
       'voice.auto': cfg.autoSpeak ? `${Math.round(cfg.autoProbability * 100)}%` : 'off',
-      'voice.backend': cfg.backend,
       'voice.voice': cfg.voice || 'default',
       'voice.emotion': cfg.defaultEmotion || 'neutral',
       'voice.instruct': cfg.defaultInstruct || 'none',
-      'voice.sing': cfg.singUrl ? 'available' : 'not configured',
     };
   }
 
@@ -168,7 +191,6 @@ export class VoiceWorld implements World {
     });
     return [
       tool('voice_speak', (args) => this.handleSpeak(args)),
-      tool('voice_sing', (args) => this.handleSing(args)),
       tool('voice_hush', async () => {
         this.queue.hush();
         return 'Voice stopped; queued lines were dropped.';
@@ -182,30 +204,28 @@ export class VoiceWorld implements World {
     this.maybeRefresh();
     const cfg = this.cfg;
     const stats = this.queue.stats();
-    const backendLamp: WorldLamp = this.backendState === null
-      ? { label: t.lampBackend, state: this.started ? 'loading' : 'offline' }
-      : this.backendState.ok
-        ? { label: t.lampBackend, state: 'online', ...(this.backendState.detail ? { hint: this.backendState.detail } : {}) }
-        : { label: t.lampBackend, state: 'error', ...(this.backendState.detail ? { hint: this.backendState.detail } : {}) };
-    const apiLamp: WorldLamp = !cfg.httpApi
-      ? { label: t.lampApi, state: 'offline' }
-      : this.http
-        ? { label: t.lampApi, state: 'online', hint: `127.0.0.1:${this.http.port}` }
-        : { label: t.lampApi, state: 'error', ...(this.httpError ? { hint: this.httpError } : {}) };
+    const serviceLamp: WorldLamp = this.serviceState === null
+      ? { label: t.lampService, state: this.started ? 'loading' : 'offline' }
+      : this.serviceState.ok
+        ? { label: t.lampService, state: 'online', ...(this.serviceState.detail ? { hint: this.serviceState.detail } : {}) }
+        : { label: t.lampService, state: 'error', ...(this.serviceState.detail ? { hint: this.serviceState.detail } : {}) };
     return {
       label: t.label,
       lamps: [
-        backendLamp,
-        { label: t.lampQueue, state: stats.speaking ? 'loading' : 'online', hint: `${stats.queued}` },
-        apiLamp,
-        { label: t.lampSinger, state: cfg.singUrl ? (this.singReady ? 'online' : 'offline') : 'offline' },
+        serviceLamp,
+        {
+          label: t.lampQueue,
+          state: !this.started ? 'offline' : stats.speaking ? 'loading' : 'online',
+          hint: `${stats.queued}`,
+        },
       ],
       badges: [
+        { label: 'service', value: serviceHost(cfg.serviceUrl), tone: 'plain' },
+        { label: 'model', value: cfg.model || '—', tone: 'plain' },
         { label: 'voice', value: cfg.voice || '—', tone: 'plain' },
-        { label: 'emotion', value: cfg.defaultEmotion || '—', tone: 'plain' },
-        { label: 'queue', value: stats.queued, tone: stats.queued ? 'on' : 'plain' },
       ],
       config: voiceConfigGroups(language),
+      links: [{ label: t.servicePage, href: '#/provider/world:service' }],
       promptDocs: [{
         key: 'worlds.voice.envPrompt',
         title: t.envTitle,
@@ -214,11 +234,9 @@ export class VoiceWorld implements World {
         role: 'envPrompt',
         vars: [
           { name: 'voice.auto', description: 'Automatic reading probability, or off.' },
-          { name: 'voice.backend', description: 'Active protocol id.' },
           { name: 'voice.voice', description: 'Current voice id.' },
           { name: 'voice.emotion', description: 'Standing emotion.' },
           { name: 'voice.instruct', description: 'Standing direction.' },
-          { name: 'voice.sing', description: 'Whether a singing service is configured.' },
         ],
       }],
     };
@@ -234,8 +252,9 @@ export class VoiceWorld implements World {
   async start(host: WorldHost): Promise<void> {
     this.host = host;
     this.started = true;
+    this.registerCatalogOptions();
     this.log.info('语音 World 启动', {
-      backend: this.cfg.backend,
+      service: serviceHost(this.cfg.serviceUrl),
       playback: this.cfg.playback,
       auto: this.cfg.autoSpeak ? this.cfg.autoProbability : 'off',
     });
@@ -244,22 +263,19 @@ export class VoiceWorld implements World {
         this.log.warn('播放器预热失败', { err: error instanceof Error ? error.message : String(error) });
       });
     }
-    if (this.cfg.httpApi) await this.startHttp();
     this.syncPoller();
     void this.probe();
-    this.healthTimer = setInterval(() => { void this.probe(); }, HEALTH_TTL_MS * 2);
+    this.healthTimer = setInterval(() => { void this.probe(); }, HEALTH_INTERVAL_MS);
     this.healthTimer.unref?.();
   }
 
   async stop(): Promise<void> {
     this.started = false;
+    this.unregisterCatalogOptions();
     if (this.healthTimer) clearInterval(this.healthTimer);
     this.healthTimer = null;
     this.poller?.stop();
     this.poller = null;
-    const http = this.http;
-    this.http = null;
-    if (http) await http.close().catch(() => {});
     await this.queue.close();
     if (this.tempDir) {
       try { rmSync(this.tempDir, { recursive: true, force: true }); } catch { /* 临时目录 */ }
@@ -286,13 +302,6 @@ export class VoiceWorld implements World {
     const cfg = this.cfg;
     if (!cfg.autoSpeak) return;
 
-    // 唱歌标记是显式的,不掷概率。没配唱歌服务时按普通文本念。
-    const sing = singRequestOf(raw);
-    if (sing.marked && cfg.singUrl.trim()) {
-      if (sing.lyrics && this.fresh(sing.lyrics)) this.enqueueSing(sing.lyrics, source);
-      return;
-    }
-
     const filtered = filterSpeech(raw, cfg);
     if (!filtered.text) return;
 
@@ -310,31 +319,11 @@ export class VoiceWorld implements World {
     this.log.debug('自动朗读', { source, explicit, chars: [...filtered.text].length });
   }
 
-  private enqueueSing(lyrics: string, source: string): void {
-    const cfg = this.cfg;
-    if (!cfg.singUrl.trim()) return;
-    this.queue.enqueue({
-      text: lyrics,
-      chunks: [lyrics],
-      silent: cfg.playback === 'none',
-      source,
-      produce: (chunk, signal) => singRemote({
-        url: cfg.singUrl,
-        token: cfg.singToken,
-        lyrics: chunk,
-        timeoutMs: Math.max(cfg.timeoutMs, 180_000),
-        fetch: this.deps.fetch,
-        signal,
-      }),
-    });
-    this.log.info('自动唱歌', { source, chars: [...lyrics].length });
-  }
-
   private enqueue(text: string, opts: EnqueueOptions): ReturnType<SpeechQueue['enqueue']> | null {
     const cfg = this.cfg;
     const clipped = truncateSpeech(text, cfg.maxChars);
     if ([...clipped].length < Math.max(1, cfg.minChars)) return null;
-    const chunks = opts.single ? [clipped] : splitSpeech(clipped, cfg.chunkMax);
+    const chunks = splitSpeech(clipped, cfg.chunkMax);
     if (chunks.length === 0) return null;
     const job: SpeechJob = {
       text: clipped,
@@ -403,73 +392,6 @@ export class VoiceWorld implements World {
     return this.spokenOutcome(undefined, 0, false);
   }
 
-  private async handleSing(args: Record<string, unknown>): Promise<ToolOutcome> {
-    const { lyrics } = singRequestOf(asString(args.lyrics));
-    if (!lyrics) return { text: 'voice_sing failed: there are no lyrics to sing.', failed: true };
-    if (!this.cfg.singUrl.trim()) {
-      return { text: 'voice_sing failed: no singing service is configured (worlds.voice.singUrl).', failed: true };
-    }
-    const silent = this.cfg.playback === 'none';
-    const share = this.cfg.shareAudio;
-    const timeoutMs = Math.max(this.cfg.timeoutMs, 180_000);
-    const produce = (text: string, signal: AbortSignal) => singRemote({
-      url: this.cfg.singUrl,
-      token: this.cfg.singToken,
-      lyrics: text,
-      timeoutMs,
-      fetch: this.deps.fetch,
-      signal,
-    });
-
-    // 要交附件:合成完整一首就回执,播放交给队列,不等播完。
-    if (share) {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
-      try {
-        const audio = await produce(lyrics, controller.signal);
-        if (!silent) {
-          this.queue.enqueue({
-            text: lyrics,
-            chunks: [lyrics],
-            silent: false,
-            source: 'tool:voice_sing',
-            produce: async () => audio,
-          });
-        }
-        const outcome = this.spokenOutcome(audio, audio.seconds ?? 0, silent);
-        return { ...outcome, text: outcome.text.replace('one line', 'one sung line') };
-      } catch (error) {
-        return { text: `voice_sing failed: ${error instanceof Error ? error.message : String(error)}`, failed: true };
-      } finally {
-        clearTimeout(timer);
-      }
-    }
-
-    const job: SpeechJob = {
-      text: lyrics,
-      chunks: [lyrics],
-      silent,
-      source: 'tool:voice_sing',
-      produce,
-    };
-    const enqueued = this.queue.enqueue(job);
-    if (!silent) {
-      const first = await within(Promise.race([
-        enqueued.started.then(() => 'started' as const),
-        enqueued.done.then((r) => r),
-      ]), timeoutMs);
-      if (first === 'timeout') return { text: 'The singing service is still working; the song will play when ready.' };
-      if (first !== 'started' && !first.ok) {
-        return { text: `voice_sing failed: ${first.error ?? 'cancelled'}`, failed: true };
-      }
-      return { text: 'Singing now.' };
-    }
-    const result = await within(enqueued.done, timeoutMs + 60_000);
-    if (result === 'timeout') return { text: 'voice_sing failed: the singing service timed out.', failed: true };
-    if (!result.ok) return { text: `voice_sing failed: ${result.error ?? 'cancelled'}`, failed: true };
-    return { text: 'Sang one line without playing.' };
-  }
-
   private async handleStyle(args: Record<string, unknown>): Promise<ToolOutcome> {
     const has = (key: string): boolean => Object.prototype.hasOwnProperty.call(args, key);
     const patch: Partial<VoiceConfigSection> = {};
@@ -492,8 +414,7 @@ export class VoiceWorld implements World {
     const cfg = this.cfg;
     return `Voice: ${cfg.voice || 'default'}; emotion: ${cfg.defaultEmotion || 'neutral'}; `
       + `direction: ${cfg.defaultInstruct || 'none'}; speed: ${cfg.speed}; `
-      + `automatic: ${cfg.autoSpeak ? `${Math.round(cfg.autoProbability * 100)}%` : 'off'}; `
-      + `singing: ${cfg.singUrl ? 'configured' : 'not configured'}.`;
+      + `automatic: ${cfg.autoSpeak ? `${Math.round(cfg.autoProbability * 100)}%` : 'off'}.`;
   }
 
   private spokenOutcome(audio: TtsAudio | undefined, seconds: number, silent: boolean): ToolOutcome {
@@ -518,26 +439,45 @@ export class VoiceWorld implements World {
 
   // ———————— 合成与出口 ————————
 
-  private backendContext() {
-    return {
-      cfg: this.cfg,
-      secret: (name: string) => (name ? this.opts.secret(name) : ''),
-      fetch: this.deps.fetch,
-      log: this.log,
-    };
-  }
-
-  private async synthesize(text: string, style: { emotion?: string; instruct?: string; voice?: string; speed?: number }, signal: AbortSignal): Promise<TtsAudio> {
+  /**
+   * 语义字段按 emotionMode 只发一种:instruct 发指令,categorical 发情绪,
+   * basic 发语速,tags/none 不发;voice/model/format 每次都带。
+   */
+  private async synthesize(
+    text: string,
+    style: { emotion?: string; instruct?: string; voice?: string; speed?: number },
+    signal: AbortSignal,
+  ): Promise<TtsAudio> {
     const cfg = this.cfg;
-    const backend = this.deps.backend ?? backendOf(cfg.backend);
-    const request: TtsRequest = { text, format: cfg.format, signal, ...style };
+    const resolved = resolveStyle(cfg, style);
+    const request: TtsRequest = {
+      text,
+      format: cfg.format,
+      signal,
+      ...(style.voice ? { voice: style.voice } : {}),
+    };
+    switch (cfg.emotionMode) {
+      case 'instruct': {
+        const instruct = buildInstruct(resolved);
+        if (instruct) request.instruct = instruct;
+        break;
+      }
+      case 'categorical':
+        request.emotion = resolved.emotion || '平静';
+        break;
+      case 'basic':
+        request.speed = resolved.speed;
+        break;
+      default:
+        break;
+    }
     try {
-      const audio = await backend.synthesize(request, this.backendContext());
-      this.markBackend({ ok: true });
+      const audio = await this.service.synthesize(request, signal);
+      this.markService({ ok: true });
       return audio;
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
-      this.markBackend({ ok: false, detail });
+      this.markService({ ok: false, detail });
       void this.pushFailure(detail, { source: 'synthesize', chars: [...text].length });
       throw error;
     }
@@ -570,7 +510,7 @@ export class VoiceWorld implements World {
   private async pushFailure(detail: string, meta: Record<string, unknown>): Promise<void> {
     const host = this.host;
     if (!host) return;
-    // 后端长时间不可用时,自动朗读会每句都失败;事件留一条,日志照常。
+    // 服务长时间不可用时,自动朗读会每句都失败;事件留一条,日志照常。
     const now = this.deps.now();
     if (now - this.lastFailureAt < 30_000) return;
     this.lastFailureAt = now;
@@ -587,11 +527,11 @@ export class VoiceWorld implements World {
     } catch { /* 只归档,失败就只留日志 */ }
   }
 
-  // ———————— 状态、HTTP 与音色 ————————
+  // ———————— 状态与目录 ————————
 
-  private markBackend(state: BackendHealth): void {
-    const previous = this.backendState;
-    this.backendState = { ...state, at: this.deps.now() };
+  private markService(state: Pick<ServiceState, 'ok' | 'detail'>): void {
+    const previous = this.serviceState;
+    this.serviceState = { ...state, at: this.deps.now() };
     if (previous?.ok !== state.ok) {
       if (state.ok) this.log.info('语音服务可用');
       else this.log.warn('语音服务不可用', { detail: state.detail ?? '' });
@@ -600,44 +540,44 @@ export class VoiceWorld implements World {
 
   private async probe(): Promise<void> {
     if (this.probing) return;
+    // 探活会刷新目录;每次探活都重新登记,停用后重新启用的实例也能接上。
+    this.registerCatalogOptions();
     this.probing = true;
     try {
-      const backend = this.deps.backend ?? backendOf(this.cfg.backend);
-      const state = await backend.health(this.backendContext());
-      this.markBackend(state);
-      if (this.cfg.singUrl.trim()) this.singReady = await singHealth({
-        url: this.cfg.singUrl,
-        token: this.cfg.singToken || undefined,
-        fetch: this.deps.fetch,
+      const health: ServiceHealth = await this.service.health();
+      this.markService({
+        ok: health.ok && health.ready,
+        detail: health.detail ?? health.status,
       });
-      else this.singReady = false;
-      await this.refreshVoices();
     } catch (error) {
-      this.markBackend({ ok: false, detail: error instanceof Error ? error.message : String(error) });
+      this.markService({ ok: false, detail: error instanceof Error ? error.message : String(error) });
     } finally {
       this.probing = false;
     }
+    // 探活顺带刷新目录;读不到时 refresh 会保留上一次的表。
+    await this.refreshVoices(true);
+    await this.refreshModels(true);
   }
 
   private maybeRefresh(): void {
     if (!this.started) return;
     const now = this.deps.now();
-    if (!this.probing && (this.backendState === null || now - this.backendState.at > HEALTH_TTL_MS)) {
+    if (!this.probing && (this.serviceState === null || now - this.serviceState.at > HEALTH_TTL_MS)) {
       void this.probe();
     }
-    if (!this.voicesLoading && now - this.voicesAt > VOICES_TTL_MS) void this.refreshVoices();
+    if (now - this.voicesAt > CATALOG_TTL_MS) void this.refreshVoices();
+    if (now - this.modelsAt > CATALOG_TTL_MS) void this.refreshModels();
   }
 
   private async refreshVoices(force = false): Promise<void> {
     const cfg = this.cfg;
-    const signature = `${cfg.backend}|${cfg.baseUrl}|${cfg.model}`;
+    const signature = `${cfg.serviceUrl.trim()}|${cfg.model.trim()}`;
     if (this.voicesLoading && !force) return;
-    if (!force && signature === this.voicesSignature && this.deps.now() - this.voicesAt < VOICES_TTL_MS) return;
+    if (!force && signature === this.voicesSignature && this.deps.now() - this.voicesAt < CATALOG_TTL_MS) return;
     this.voicesLoading = true;
     try {
-      const backend = this.deps.backend ?? backendOf(cfg.backend);
-      const list = await backend.listVoices(this.backendContext());
-      if (signature !== `${this.cfg.backend}|${this.cfg.baseUrl}|${this.cfg.model}`) return;
+      const list = await this.service.voices(cfg.model);
+      if (signature !== `${this.cfg.serviceUrl.trim()}|${this.cfg.model.trim()}`) return;
       this.voices = list;
       this.voicesSignature = signature;
       this.voicesAt = this.deps.now();
@@ -648,73 +588,35 @@ export class VoiceWorld implements World {
     }
   }
 
-  private voiceOptions(): VoiceOption[] {
-    const current = this.cfg.voice.trim();
-    const out = [...this.voices];
-    if (current && !out.some((v) => v.value === current)) out.unshift({ value: current, label: current });
-    return out;
-  }
-
-  private async startHttp(): Promise<void> {
-    if (this.http) return;
+  private async refreshModels(force = false): Promise<void> {
+    const signature = this.cfg.serviceUrl.trim();
+    if (this.modelsLoading && !force) return;
+    if (!force && signature === this.modelsSignature && this.deps.now() - this.modelsAt < CATALOG_TTL_MS) return;
+    this.modelsLoading = true;
     try {
-      this.http = await startVoiceHttp({
-        port: this.cfg.httpPort,
-        deps: {
-          token: () => this.cfg.httpToken,
-          status: () => ({
-            ready: this.backendState?.ok === true,
-            state: this.backendState?.detail ?? (this.backendState?.ok ? 'ready' : 'unknown'),
-            backend: backendOf(this.cfg.backend).label,
-            model: this.cfg.model,
-            voice: this.cfg.voice,
-            queue: this.queue.stats().queued,
-            sing: !!this.cfg.singUrl.trim(),
-          }),
-          synthesize: async ({ request, play }, signal) => {
-            const audio = await this.synthesize(request.text, {
-              ...(request.emotion ? { emotion: request.emotion } : {}),
-              ...(request.instruct ? { instruct: request.instruct } : {}),
-              ...(request.voice ? { voice: request.voice } : {}),
-              ...(request.speed !== undefined ? { speed: request.speed } : {}),
-            }, signal);
-            if (play || this.cfg.httpPlay) {
-              this.queue.enqueue({
-                text: request.text,
-                chunks: [request.text],
-                silent: false,
-                source: 'http',
-                produce: async () => audio,
-              });
-            }
-            return audio;
-          },
-          sing: async (lyrics, signal) => {
-            if (!this.cfg.singUrl.trim()) throw new Error('no singing service configured');
-            return singRemote({
-              url: this.cfg.singUrl,
-              token: this.cfg.singToken,
-              lyrics,
-              timeoutMs: Math.max(this.cfg.timeoutMs, 180_000),
-              fetch: this.deps.fetch,
-              signal,
-            });
-          },
-          voices: async () => {
-            await this.refreshVoices(true);
-            return this.voiceOptions();
-          },
-          log: this.log,
-        },
-      });
-      this.httpError = '';
-      this.log.info('本地语音接口已就绪', { port: this.http.port });
+      const list = await this.service.models();
+      if (signature !== this.cfg.serviceUrl.trim()) return;
+      this.models = list;
+      this.modelsSignature = signature;
+      this.modelsAt = this.deps.now();
     } catch (error) {
-      this.httpError = error instanceof Error ? error.message : String(error);
-      this.log.error('本地语音接口启动失败', { err: this.httpError });
+      this.log.debug('模型表读取失败', { err: error instanceof Error ? error.message : String(error) });
+    } finally {
+      this.modelsLoading = false;
     }
   }
 
+  /** 下拉读的是缓存表;服务读不到时保留上一次的结果。当前值由框架补入。 */
+  private registerCatalogOptions(): void {
+    registerOptions(VOICE_MODELS_KIND, this.modelOptions);
+    registerOptions(VOICE_OPTIONS_KIND, this.voiceOptions);
+  }
+
+  private unregisterCatalogOptions(): void {
+    unregisterOptions(VOICE_MODELS_KIND, this.modelOptions);
+    unregisterOptions(VOICE_OPTIONS_KIND, this.voiceOptions);
+  }
+
   private syncPoller(): void {
     const types = eventTypes(this.cfg);
     if (types.size === 0) {
@@ -753,4 +655,4 @@ export class VoiceWorld implements World {
   }
 }
 
-export { VOICE_DEFAULTS, VOICE_ID, VOICE_OPTIONS_KIND };
+export { VOICE_DEFAULTS, VOICE_ID, VOICE_MODELS_KIND, VOICE_OPTIONS_KIND };