@kmchai/cortico-world-voice 0.1.0 → 0.2.0

package/src/config.ts

@@ -6,17 +6,18 @@ import type { VoiceConfigSection } from './types.ts';
 export const VOICE_ID = 'voice';
 /** 配置里 `x-options` 用的动态音色表。 */
 export const VOICE_OPTIONS_KIND = 'voice.voices';
+/** 配置里 `x-options` 用的动态模型表。 */
+export const VOICE_MODELS_KIND = 'voice.models';
 
 export const VOICE_DEFAULTS: VoiceConfigSection = {
   enabled: false,
 
-  backend: 'audiocpp',
-  baseUrl: 'http://127.0.0.1:8000',
-  model: 'ming3-tts',
-  voice: '4016',
-  apiKeySecret: '',
+  serviceUrl: 'http://127.0.0.1:9883',
+  serviceTokenSecret: '',
+  model: '',
+  voice: '',
   format: 'wav',
-  timeoutMs: 120_000,
+  timeoutMs: 180_000,
 
   emotionMode: 'instruct',
   defaultEmotion: '',
@@ -47,51 +48,35 @@ export const VOICE_DEFAULTS: VoiceConfigSection = {
   chunkMax: 120,
   gapMs: 120,
   shareAudio: false,
-
-  httpApi: false,
-  httpPort: 9883,
-  httpToken: '',
-  httpPlay: false,
-
-  singUrl: '',
-  singToken: '',
-
-  customUrl: '',
-  customMethod: 'POST',
-  customHeaders: '',
-  customBody: '',
-  customResponse: 'audio',
-  customAudioPath: 'audio',
 };
 
 const TEXT = {
   zh: {
     label: '语音',
     envTitle: '语音 · 环境提示词',
-    lampBackend: '语音服务',
+    lampService: '语音服务',
     lampQueue: '朗读队列',
-    lampApi: '本地接口',
-    lampSinger: '唱歌',
+    servicePage: '服务设置',
     connection: '连接',
-    connectionDesc: '语音服务地址与协议。',
-    backend: '协议',
-    baseUrl: '服务地址',
+    connectionDesc: '语音服务的 HTTP 地址与令牌。',
+    serviceUrl: '服务地址',
+    serviceUrlDesc: 'Kmch AI · 服务 的网关地址。',
+    serviceTokenSecret: '服务令牌变量名',
+    serviceTokenSecretDesc: '部署 .env 里的变量名,留空表示服务不校验。',
     model: '模型',
     voice: '音色',
-    apiKeySecret: '密钥变量名',
-    apiKeySecretDesc: '部署 .env 里的变量名,留空表示不需要。',
     format: '音频格式',
     timeoutMs: '超时(毫秒)',
     style: '音色与情绪',
     styleDesc: '',
     emotionMode: '情绪控制',
-    emotionModeDesc: 'instruct 折成自然语言;categorical 只发情绪标签;basic 只发语速/音调/音量;tags 只用正文标签;none 不发。',
+    emotionModeDesc: 'instruct 折成自然语言指令;categorical 只发情绪标签;basic 只发语速;tags 只用正文标签;none 不发。',
     defaultEmotion: '默认情绪',
     defaultInstruct: '默认表演指令',
     speed: '语速',
     paralinguistic: '副语言标签',
-    paralinguisticDesc: 'auto 只在支持标签的后端保留;strip 一律从朗读文本里删掉。',
-    triggers: '触发与过滤',
+    paralinguisticDesc: 'auto 保留,由服务与模型决定;strip 一律从朗读文本里删掉。',
+    triggers: '触发',
     triggersDesc: '',
     autoSpeak: '自动朗读',
     autoProbability: '自动朗读概率',
@@ -106,6 +91,8 @@ const TEXT = {
     explicitWindowSec: '回看秒数',
     minChars: '最短字数',
     maxChars: '最长字数',
+    filter: '文本过滤',
+    filterDesc: '',
     filterCode: '过滤代码块',
     filterUrls: '过滤网址',
     filterMarkdown: '过滤 Markdown',
@@ -114,7 +101,7 @@ const TEXT = {
     filterEmoji: '过滤表情与符号',
     filterSymbols: '额外过滤字符',
     filterSymbolsDesc: '按字面删除,可用逗号/分号/换行分隔。',
-    output: '输出与接口',
+    output: '输出',
     outputDesc: '',
     playback: '播放方式',
     playbackDesc: 'local 用本机播放器;event 发 tts.voice 事件交给别的插件;none 只合成。',
@@ -122,52 +109,33 @@ const TEXT = {
     chunkMax: '单块字数',
     gapMs: '块间停顿(毫秒)',
     shareAudio: '回执带音频附件',
-    httpApi: '开放本地语音接口',
-    httpPort: '接口端口',
-    httpToken: '接口令牌',
-    httpTokenDesc: '留空不校验;只监听 127.0.0.1。',
-    httpPlay: '接口合成也本机播放',
-    sing: '唱歌',
-    singDesc: '接到唱歌插件的 HTTP 接口;留空则 voice_sing 回失败。',
-    singUrl: '唱歌服务地址',
-    singToken: '唱歌令牌',
-    custom: 'custom 协议',
-    customDesc: '自定义 JSON 请求;占位符 {{text}} {{voice}} {{emotion}} {{instruct}} {{model}} {{speed}} {{format}}。',
-    customUrl: '完整地址',
-    customMethod: '方法',
-    customHeaders: '请求头(JSON)',
-    customHeadersDesc: '值里的 ${KEY} 换成 apiKeySecret 读到的密钥。',
-    customBody: '请求体模板(JSON)',
-    customResponse: '音频位置',
-    customAudioPath: '音频字段路径',
   },
   en: {
     label: 'Voice',
     envTitle: 'Voice · environment prompt',
-    lampBackend: 'Speech service',
+    lampService: 'Speech service',
     lampQueue: 'Speech queue',
-    lampApi: 'Local API',
-    lampSinger: 'Singing',
+    servicePage: 'Service settings',
     connection: 'Connection',
-    connectionDesc: 'Where the speech service is and which protocol it speaks.',
-    backend: 'Protocol',
-    baseUrl: 'Base URL',
+    connectionDesc: 'Where the speech service is and which token it expects.',
+    serviceUrl: 'Service URL',
+    serviceUrlDesc: 'Gateway address of Kmch AI · Service.',
+    serviceTokenSecret: 'Service token variable',
+    serviceTokenSecretDesc: 'Name in the deployment .env; empty means the service does not check.',
     model: 'Model',
     voice: 'Voice',
-    apiKeySecret: 'Secret variable',
-    apiKeySecretDesc: 'Name in the deployment .env; empty means none.',
     format: 'Audio format',
     timeoutMs: 'Timeout (ms)',
     style: 'Voice and emotion',
     styleDesc: '',
     emotionMode: 'Emotion control',
-    emotionModeDesc: 'instruct turns it into natural language; categorical sends a label; basic sends speed/pitch/volume; tags uses inline tags only; none sends nothing.',
+    emotionModeDesc: 'instruct turns it into natural language; categorical sends a label; basic sends speed; tags uses inline tags only; none sends nothing.',
     defaultEmotion: 'Default emotion',
     defaultInstruct: 'Default direction',
     speed: 'Speed',
     paralinguistic: 'Paralinguistic tags',
-    paralinguisticDesc: 'auto keeps them only on backends that support them; strip removes them from the spoken text.',
-    triggers: 'Triggers and filters',
+    paralinguisticDesc: 'auto keeps them and lets the service and model decide; strip removes them from the spoken text.',
+    triggers: 'Triggers',
     triggersDesc: '',
     autoSpeak: 'Automatic speech',
     autoProbability: 'Automatic probability',
@@ -182,6 +150,8 @@ const TEXT = {
     explicitWindowSec: 'Look-back seconds',
     minChars: 'Minimum characters',
     maxChars: 'Maximum characters',
+    filter: 'Text filter',
+    filterDesc: '',
     filterCode: 'Filter code blocks',
     filterUrls: 'Filter URLs',
     filterMarkdown: 'Filter Markdown',
@@ -190,7 +160,7 @@ const TEXT = {
     filterEmoji: 'Filter emoji and symbols',
     filterSymbols: 'Extra filtered characters',
     filterSymbolsDesc: 'Removed literally; comma/semicolon/newline separated.',
-    output: 'Output and API',
+    output: 'Output',
     outputDesc: '',
     playback: 'Playback',
     playbackDesc: 'local uses the built-in player; event emits tts.voice for another plugin; none only synthesizes.',
@@ -198,24 +168,6 @@ const TEXT = {
     chunkMax: 'Characters per chunk',
     gapMs: 'Gap between chunks (ms)',
     shareAudio: 'Attach audio to tool results',
-    httpApi: 'Serve the local speech API',
-    httpPort: 'API port',
-    httpToken: 'API token',
-    httpTokenDesc: 'Empty means no check; loopback only.',
-    httpPlay: 'Play API requests locally too',
-    sing: 'Singing',
-    singDesc: 'HTTP endpoint of a singing plugin; empty makes voice_sing fail.',
-    singUrl: 'Singing service URL',
-    singToken: 'Singing token',
-    custom: 'custom protocol',
-    customDesc: 'Custom JSON request; placeholders {{text}} {{voice}} {{emotion}} {{instruct}} {{model}} {{speed}} {{format}}.',
-    customUrl: 'Full URL',
-    customMethod: 'Method',
-    customHeaders: 'Headers (JSON)',
-    customHeadersDesc: '${KEY} in a value is replaced with the secret named by apiKeySecret.',
-    customBody: 'Body template (JSON)',
-    customResponse: 'Audio location',
-    customAudioPath: 'Audio field path',
   },
 } as const;
 
@@ -238,11 +190,10 @@ export function voiceConfigGroups(language: Language): ConfigGroup[] {
         title: t.connection,
         description: t.connectionDesc,
         properties: {
-          [`${p}backend`]: { type: 'string', title: t.backend, enum: ['audiocpp', 'openai', 'custom'], 'x-hot': true },
-          [`${p}baseUrl`]: { type: 'string', title: t.baseUrl, 'x-hot': true },
-          [`${p}model`]: { type: 'string', title: t.model, 'x-hot': true },
+          [`${p}serviceUrl`]: { type: 'string', title: t.serviceUrl, description: t.serviceUrlDesc, 'x-hot': true },
+          [`${p}serviceTokenSecret`]: { type: 'string', title: t.serviceTokenSecret, description: t.serviceTokenSecretDesc, 'x-hot': true },
+          [`${p}model`]: { type: 'string', title: t.model, 'x-options': VOICE_MODELS_KIND, 'x-hot': true },
           [`${p}voice`]: { type: 'string', title: t.voice, 'x-options': VOICE_OPTIONS_KIND, 'x-hot': true },
-          [`${p}apiKeySecret`]: { type: 'string', title: t.apiKeySecret, description: t.apiKeySecretDesc, 'x-hot': false },
           [`${p}format`]: { type: 'string', title: t.format, enum: ['wav', 'mp3'], 'x-hot': true },
           [`${p}timeoutMs`]: { type: 'integer', title: t.timeoutMs, minimum: 1000, maximum: 600_000, 'x-hot': true },
         },
@@ -280,6 +231,16 @@ export function voiceConfigGroups(language: Language): ConfigGroup[] {
           [`${p}explicitWindowSec`]: { type: 'integer', title: t.explicitWindowSec, minimum: 0, maximum: 3600, 'x-hot': true },
           [`${p}minChars`]: { type: 'integer', title: t.minChars, minimum: 1, maximum: 100, 'x-hot': true },
           [`${p}maxChars`]: { type: 'integer', title: t.maxChars, minimum: 20, maximum: 8000, 'x-hot': true },
+        },
+      },
+    },
+    {
+      id: 'world:voice-filter',
+      owner: 'world:voice',
+      schema: {
+        type: 'object',
+        title: t.filter,
+        properties: {
           [`${p}filterCode`]: { type: 'boolean', title: t.filterCode, 'x-hot': true },
           [`${p}filterUrls`]: { type: 'boolean', title: t.filterUrls, 'x-hot': true },
           [`${p}filterMarkdown`]: { type: 'boolean', title: t.filterMarkdown, 'x-hot': true },
@@ -301,29 +262,6 @@ export function voiceConfigGroups(language: Language): ConfigGroup[] {
           [`${p}chunkMax`]: { type: 'integer', title: t.chunkMax, minimum: 20, maximum: 500, 'x-hot': true },
           [`${p}gapMs`]: { type: 'integer', title: t.gapMs, minimum: 0, maximum: 5000, 'x-hot': true },
           [`${p}shareAudio`]: { type: 'boolean', title: t.shareAudio, 'x-hot': true },
-          [`${p}httpApi`]: { type: 'boolean', title: t.httpApi, 'x-hot': false },
-          [`${p}httpPort`]: { type: 'integer', title: t.httpPort, minimum: 1, maximum: 65535, 'x-hot': false },
-          [`${p}httpToken`]: { type: 'string', title: t.httpToken, description: t.httpTokenDesc, 'x-hot': false },
-          [`${p}httpPlay`]: { type: 'boolean', title: t.httpPlay, 'x-hot': true },
-          [`${p}singUrl`]: { type: 'string', title: t.singUrl, description: t.singDesc, 'x-hot': true },
-          [`${p}singToken`]: { type: 'string', title: t.singToken, 'x-hot': true },
-        },
-      },
-    },
-    {
-      id: 'world:voice-custom',
-      owner: 'world:voice',
-      schema: {
-        type: 'object',
-        title: t.custom,
-        description: t.customDesc,
-        properties: {
-          [`${p}customUrl`]: { type: 'string', title: t.customUrl, 'x-hot': true },
-          [`${p}customMethod`]: { type: 'string', title: t.customMethod, enum: ['POST', 'GET'], 'x-hot': true },
-          [`${p}customHeaders`]: { type: 'string', title: t.customHeaders, description: t.customHeadersDesc, 'x-hot': true },
-          [`${p}customBody`]: { type: 'string', title: t.customBody, 'x-hot': true },
-          [`${p}customResponse`]: { type: 'string', title: t.customResponse, enum: ['audio', 'base64', 'url'], 'x-hot': true },
-          [`${p}customAudioPath`]: { type: 'string', title: t.customAudioPath, 'x-hot': true },
         },
       },
     },

package/src/definition.ts

@@ -1,6 +1,6 @@
 import { describeTools, type WorldDefinition } from 'cortico/world.ts';
-import { VOICE_DEFAULTS, VOICE_ID, VOICE_OPTIONS_KIND } from './config.ts';
-import { currentVoiceOptions } from './options.ts';
+import { VOICE_DEFAULTS, VOICE_ID } from './config.ts';
+import { currentOptions } from './options.ts';
 import { VOICE_TOOL_DECLS } from './tools.ts';
 import type { VoiceConfigSection } from './types.ts';
 import { VoiceWorld } from './world.ts';
@@ -9,7 +9,7 @@ export const VOICE: WorldDefinition<VoiceConfigSection> = {
   id: VOICE_ID,
   label: 'Voice',
   defaults: () => ({ ...VOICE_DEFAULTS }),
-  configOptions: (kind) => (kind === VOICE_OPTIONS_KIND ? currentVoiceOptions() : []),
+  configOptions: (kind) => currentOptions(kind),
   create: (ctx) => new VoiceWorld({
     cfg: ctx.cfg,
     timezone: ctx.timezone,
@@ -20,7 +20,6 @@ export const VOICE: WorldDefinition<VoiceConfigSection> = {
   describe: {
     tools: describeTools(VOICE_TOOL_DECLS, {
       voice_speak: { zh: '现在念一句;可指定情绪、表演指令、音色与语速,也可以只合成不出声。', en: 'Say one line now, optionally with an emotion, direction, voice and speed, or synthesize it silently.' },
-      voice_sing: { zh: '把一句歌词交给唱歌插件唱出来。', en: 'Sing one lyric line through the configured singing service.' },
       voice_hush: { zh: '立刻停声并清空排队。', en: 'Stop the voice and drop queued lines.' },
       voice_style: { zh: '读或改自动朗读使用的长期音色与情绪。', en: 'Read or change the standing voice style used by automatic reading.' },
     }),

package/src/options.ts

@@ -1,15 +1,36 @@
 /**
- * 配置页的音色下拉要读运行中实例探到的音色,但 `WorldDefinition.configOptions` 是静态签名。
- * 实例启动时把「读当前音色表」的函数注册进来。
+ * 配置页的模型与音色下拉要读运行中实例从服务探到的目录,但
+ * `WorldDefinition.configOptions` 是静态签名。实例启动或探活时把读取函数注册进来;
+ * 只支持 `voice.models` 与 `voice.voices` 两种 kind,未知 kind 返回空。
+ * 读的是已经缓存的表,不在配置页里发请求;服务不可达时保留上次的表,没有就是空表。
+ * 当前值不在表里时由框架补入,这里不重复做。
  */
-import type { VoiceOption } from './types.ts';
+import { VOICE_MODELS_KIND, VOICE_OPTIONS_KIND } from './config.ts';
+import type { SelectOption } from './types.ts';
 
-let provider: (() => VoiceOption[]) | null = null;
+export const OPTION_KINDS = [VOICE_MODELS_KIND, VOICE_OPTIONS_KIND] as const;
+export type OptionKind = (typeof OPTION_KINDS)[number];
 
-export function registerVoiceOptions(fn: () => VoiceOption[]): void {
-  provider = fn;
+type Provider = () => readonly SelectOption[];
+
+const providers = new Map<OptionKind, Provider>();
+
+function isOptionKind(kind: string): kind is OptionKind {
+  return kind === VOICE_MODELS_KIND || kind === VOICE_OPTIONS_KIND;
+}
+
+/** 实例启动或探活时登记;同一 kind 后登记的覆盖先前的。 */
+export function registerOptions(kind: OptionKind, provider: Provider): void {
+  providers.set(kind, provider);
+}
+
+/** 实例停止时撤销自己登记的那一项;已有更新实例登记时不动它。 */
+export function unregisterOptions(kind: OptionKind, provider: Provider): void {
+  if (providers.get(kind) === provider) providers.delete(kind);
 }
 
-export function currentVoiceOptions(): VoiceOption[] {
-  return provider?.() ?? [];
+/** 未知 kind 返回空数组,框架继续查询其他 World。 */
+export function currentOptions(kind: string): SelectOption[] {
+  if (!isOptionKind(kind)) return [];
+  return [...(providers.get(kind)?.() ?? [])];
 }

package/src/service.ts

@@ -0,0 +1,290 @@
+/**
+ * Kmch AI · 服务 的 HTTP 客户端。语音只认这一条协议:
+ * `POST /v1/audio/speech` 取音频,`GET /health` 探活,
+ * `GET /v1/models` 与 `GET /v1/audio/voices` 取目录。
+ * 令牌只从 secret() 现读,不写日志、不留副本。
+ */
+import type {
+  AudioFormat, ModelOption, ServiceHealth, TtsAudio, TtsRequest, VoiceConfigSection, VoiceOption,
+} from './types.ts';
+
+const PROBE_TIMEOUT_MS = 8000;
+const LIST_TIMEOUT_MS = 8000;
+
+export interface ServiceClientDeps {
+  fetch: typeof fetch;
+  /** 从部署 .env 读密钥;名字为空时返回空串。 */
+  secret(name: string): string;
+  /** `worlds.voice` 的活引用。 */
+  cfg(): VoiceConfigSection;
+}
+
+/** World 只需要这些方法;测试用假客户端也实现它们。 */
+export type SpeechService = Pick<ServiceClient, 'synthesize' | 'health' | 'models' | 'voices'>;
+
+export class ServiceClient implements SpeechService {
+  constructor(private readonly deps: ServiceClientDeps) {}
+
+  private get cfg(): VoiceConfigSection {
+    return this.deps.cfg();
+  }
+
+  async synthesize(req: TtsRequest, signal?: AbortSignal): Promise<TtsAudio> {
+    const cfg = this.cfg;
+    const body: Record<string, unknown> = {
+      input: req.text,
+      response_format: req.format,
+    };
+    const model = cfg.model.trim();
+    if (model) body.model = model;
+    const voice = (req.voice ?? '').trim() || cfg.voice.trim();
+    if (voice) body.voice = voice;
+    const instruct = (req.instruct ?? '').trim();
+    if (instruct) body.instructions = instruct;
+    const emotion = (req.emotion ?? '').trim();
+    if (emotion) body.emotion = emotion;
+    if (req.speed !== undefined && Number.isFinite(req.speed)) body.speed = req.speed;
+
+    return this.request(this.endpoint('/v1/audio/speech'), {
+      method: 'POST',
+      headers: this.headers(true),
+      body: JSON.stringify(body),
+    }, cfg.timeoutMs, signal ?? req.signal, async (res) => {
+      if (!res.ok) throw new Error(await errorText(res));
+      const declared = res.headers.get('content-type');
+      const mime = normalizeMime(declared, req.format);
+      if (!mime) {
+        throw new Error(`voice service returned ${declared?.split(';')[0]?.trim() || 'no content-type'} instead of audio`);
+      }
+      const bytes = new Uint8Array(await res.arrayBuffer());
+      if (bytes.length === 0) throw new Error('voice service returned an empty audio body');
+      return { bytes, mime, seconds: mime === 'audio/wav' ? wavSeconds(bytes) : undefined };
+    });
+  }
+
+  /** 探活;连不上或回应不合法时返回 `ok: false`,不抛错。 */
+  async health(): Promise<ServiceHealth> {
+    try {
+      return await this.request(
+        this.endpoint('/health'),
+        { method: 'GET', headers: this.headers() },
+        Math.min(this.cfg.timeoutMs || PROBE_TIMEOUT_MS, PROBE_TIMEOUT_MS),
+        undefined,
+        async (res): Promise<ServiceHealth> => {
+          if (!res.ok) {
+            return { ok: false, ready: false, status: `HTTP ${res.status}`, detail: await errorText(res) };
+          }
+          const data = await res.json().catch(() => null) as {
+            status?: unknown; ready?: unknown; models?: unknown; services?: unknown;
+          } | null;
+          const status = typeof data?.status === 'string' && data.status.trim() ? data.status.trim() : 'ok';
+          const ready = data?.ready === true;
+          const models = typeof data?.models === 'number'
+            ? data.models
+            : Array.isArray(data?.services) ? data.services.length : undefined;
+          return {
+            ok: true,
+            ready,
+            status,
+            ...(models !== undefined ? { models } : {}),
+            detail: `${status}${models !== undefined ? ` · ${models} models` : ''}`,
+          };
+        },
+      );
+    } catch (error) {
+      return { ok: false, ready: false, status: 'unreachable', detail: messageOf(error) };
+    }
+  }
+
+  async models(): Promise<ModelOption[]> {
+    const payload = await this.request(
+      this.endpoint('/v1/models'),
+      { method: 'GET', headers: this.headers() },
+      this.listTimeout(),
+      undefined,
+      (res) => this.readJson(res),
+    ) as { data?: unknown } | unknown[] | null;
+    const raw = Array.isArray(payload) ? payload : Array.isArray(payload?.data) ? payload.data : [];
+    return raw.flatMap((item): ModelOption[] => {
+      const option = optionOf(item);
+      return option ? [option] : [];
+    });
+  }
+
+  async voices(model?: string): Promise<VoiceOption[]> {
+    const url = new URL(this.endpoint('/v1/audio/voices'));
+    const wanted = (model ?? this.cfg.model).trim();
+    if (wanted) url.searchParams.set('model', wanted);
+    const payload = await this.request(
+      url.toString(),
+      { method: 'GET', headers: this.headers() },
+      this.listTimeout(),
+      undefined,
+      (res) => this.readJson(res),
+    ) as { data?: unknown; voices?: unknown } | unknown[] | null;
+    const raw = Array.isArray(payload)
+      ? payload
+      : Array.isArray(payload?.data) ? payload.data
+        : Array.isArray(payload?.voices) ? payload.voices
+          : [];
+    return raw.flatMap((item): VoiceOption[] => {
+      const option = optionOf(item);
+      return option ? [option] : [];
+    });
+  }
+
+  // ———————— 内部 ————————
+
+  /** 地址可以带 `/v1`,也可以不带;路径统一从网关根算起。 */
+  private endpoint(path: string): string {
+    const raw = this.cfg.serviceUrl.trim();
+    if (!raw) throw new Error('serviceUrl is empty');
+    let url: URL;
+    try {
+      url = new URL(raw);
+    } catch {
+      throw new Error(`serviceUrl is not a valid URL: ${raw}`);
+    }
+    url.search = '';
+    url.hash = '';
+    if (!url.pathname.endsWith('/')) url.pathname += '/';
+    const base = url.pathname.replace(/\/+$/, '').replace(/\/v1$/, '');
+    url.pathname = `${base}${path}`;
+    return url.toString();
+  }
+
+  private headers(json = false): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (json) out['Content-Type'] = 'application/json';
+    const name = this.cfg.serviceTokenSecret.trim();
+    const token = name ? this.deps.secret(name).trim() : '';
+    if (token) out.Authorization = `Bearer ${token}`;
+    return out;
+  }
+
+  private listTimeout(): number {
+    return Math.min(this.cfg.timeoutMs || LIST_TIMEOUT_MS, LIST_TIMEOUT_MS);
+  }
+
+  private async readJson(res: Response): Promise<unknown> {
+    if (!res.ok) throw new Error(await errorText(res));
+    return res.json().catch(() => null);
+  }
+
+  /**
+   * 超时覆盖到回应体读完,不只是等到响应头;外部 signal 的取消也持续到读完。
+   * `read` 自己抛的错原样保留,超时统一报同一个句子。
+   */
+  private async request<T>(
+    url: string,
+    init: RequestInit,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+    read: (res: Response) => Promise<T>,
+  ): Promise<T> {
+    const ctrl = new AbortController();
+    const ms = Math.max(1, timeoutMs);
+    let timedOut = false;
+    const timeoutError = (): Error => new Error(`voice service timed out after ${ms} ms`);
+    let rejectDeadline: (error: Error) => void = () => {};
+    const deadline = new Promise<never>((_resolve, reject) => { rejectDeadline = reject; });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      const error = timeoutError();
+      ctrl.abort(error);
+      rejectDeadline(error);
+    }, ms);
+    const forward = (): void => ctrl.abort(signal?.reason);
+    if (signal) {
+      if (signal.aborted) forward();
+      else signal.addEventListener('abort', forward, { once: true });
+    }
+    try {
+      const res = await Promise.race([
+        this.deps.fetch(url, { ...init, signal: ctrl.signal }),
+        deadline,
+      ]);
+      return await Promise.race([read(res), deadline]);
+    } catch (error) {
+      if (timedOut) throw timeoutError();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', forward);
+    }
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function optionOf(item: unknown): { value: string; label: string } | null {
+  if (typeof item === 'string') {
+    const value = item.trim();
+    return value ? { value, label: value } : null;
+  }
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const o = item as Record<string, unknown>;
+  const value = [o.value, o.id, o.name]
+    .find((v): v is string => typeof v === 'string' && v.trim() !== '')?.trim();
+  if (!value) return null;
+  const label = [o.label, o.display_name, o.displayName, o.name]
+    .find((v): v is string => typeof v === 'string' && v.trim() !== '')?.trim() ?? value;
+  return { value, label };
+}
+
+/** 音频回应只接受 wav / mpeg;octet-stream 按请求的格式归一。 */
+function normalizeMime(raw: string | null, format: AudioFormat): string | null {
+  const type = (raw ?? '').split(';')[0]!.trim().toLowerCase();
+  if (!type || type === 'application/octet-stream') return format === 'mp3' ? 'audio/mpeg' : 'audio/wav';
+  if (type === 'audio/wav' || type === 'audio/wave' || type === 'audio/x-wav') return 'audio/wav';
+  if (type === 'audio/mpeg' || type === 'audio/mp3' || type === 'audio/mpeg3' || type === 'audio/x-mpeg') return 'audio/mpeg';
+  return null;
+}
+
+/** 压成一行:状态行加服务返回的错误正文(JSON 只取 message/code/param)。 */
+async function errorText(res: Response): Promise<string> {
+  let raw = '';
+  try { raw = await res.text(); } catch { /* 读不到就只用状态 */ }
+  let detail = raw.replace(/\s+/g, ' ').trim();
+  if (detail) {
+    try {
+      const parsed = JSON.parse(raw) as { error?: unknown };
+      const error = parsed?.error;
+      if (typeof error === 'string') {
+        detail = error.trim() || detail;
+      } else if (error && typeof error === 'object' && !Array.isArray(error)) {
+        const e = error as Record<string, unknown>;
+        const parts: string[] = [];
+        if (typeof e.message === 'string' && e.message.trim()) parts.push(e.message.trim());
+        if (typeof e.code === 'string' && e.code.trim()) parts.push(e.code.trim());
+        if (typeof e.param === 'string' && e.param.trim()) parts.push(`param ${e.param.trim()}`);
+        if (parts.length) detail = parts.join(' · ');
+      }
+    } catch { /* 非 JSON,保留原文 */ }
+  }
+  const status = `voice service ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`;
+  return `${status}${detail ? `: ${detail.slice(0, 500)}` : ''}`;
+}
+
+/** PCM16 WAV 的时长;不是 RIFF/WAVE 时返回 undefined。 */
+export function wavSeconds(bytes: Uint8Array): number | undefined {
+  if (bytes.length < 44) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, false) !== 0x52494646 || view.getUint32(8, false) !== 0x57415645) return undefined;
+  let offset = 12;
+  let byteRate = 0;
+  while (offset + 8 <= bytes.length) {
+    const id = view.getUint32(offset, false);
+    const size = view.getUint32(offset + 4, true);
+    const body = offset + 8;
+    if (id === 0x666d7420 && body + 16 <= bytes.length) byteRate = view.getUint32(body + 8, true);
+    if (id === 0x64617461) {
+      if (byteRate > 0 && size > 0) return size / byteRate;
+      return undefined;
+    }
+    offset = body + size + (size % 2);
+  }
+  return undefined;
+}

package/src/speech/style.ts

@@ -1,5 +1,5 @@
 /** 情绪、语速与表演指令的归一。 */
-import type { EmotionMode, VoiceConfigSection } from '../types.ts';
+import type { VoiceConfigSection } from '../types.ts';
 
 export interface StyleOverride {
   emotion?: string;
@@ -20,13 +20,6 @@ export function classifySpeed(speed: number): '慢速' | '中速' | '快速' {
   return '中速';
 }
 
-export function classifyLevel(value: number): '低' | '中' | '高' {
-  if (!Number.isFinite(value)) return '中';
-  if (value <= 0.34) return '低';
-  if (value >= 0.67) return '高';
-  return '中';
-}
-
 /** 参数 > 配置默认值。空串表示没给。 */
 export function resolveStyle(cfg: VoiceConfigSection, override: StyleOverride = {}): ResolvedStyle {
   return {
@@ -37,7 +30,7 @@ export function resolveStyle(cfg: VoiceConfigSection, override: StyleOverride =
 }
 
 /**
- * 自然语言表演指令。audiocpp 的 freeform 模板与 OpenAI 的 instructions 都用它。
+ * 自然语言表演指令,作为 `instructions` 发给服务。
  * 有 instruct 时以它为主,情绪与语速续在后面。
  */
 export function buildInstruct(style: ResolvedStyle): string {
@@ -52,8 +45,3 @@ export function buildInstruct(style: ResolvedStyle): string {
   }
   return parts.length ? `用${parts.join('，')}的语气朗读。` : '';
 }
-
-/** 某种情绪模式需不需要单独的情绪字段。 */
-export function sendsEmotion(mode: EmotionMode): boolean {
-  return mode === 'categorical';
-}