Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(voice): lock speech protocols for official endpoints

JiangJiahao2eef1517dbd8
diff --git a/apps/desktop/src/main/voice-conversation/__tests__/models.test.ts b/apps/desktop/src/main/voice-conversation/__tests__/models.test.ts
index 04790ed3a5..cb2acb71f4 100644
--- a/apps/desktop/src/main/voice-conversation/__tests__/models.test.ts
+++ b/apps/desktop/src/main/voice-conversation/__tests__/models.test.ts
@@ -123,11 +123,12 @@ it('supports documented native endpoints without guessing protocols from model I
});
it('requires an explicit choice for null protocols and excludes unusable credentials/routes', () => {
- const provider = custom('p', 'https://api.elevenlabs.io/v1', [
+ const provider = custom('p', 'https://proxy.test/v1', [
{ id: 'voice', name: 'Voice', mode: 'audio_speech', nativeApi: null },
]);
const d = deps([provider]);
expect(speechModels(d)[0].protocol).toBeUndefined();
+ expect(speechModels(d)[0].protocolLocked).toBe(false);
const selected = { providerId: 'p', agent: 'codex' as const, modelId: 'voice', voice: 'v' };
expect(() => resolveSpeechConnection(d, selected)).toThrow('model_unavailable');
expect(resolveSpeechConnection(d, { ...selected, protocol: 'elevenlabs' }).protocol).toBe(
@@ -144,6 +145,73 @@ it('requires an explicit choice for null protocols and excludes unusable credent
expect(speechModels(d)).toEqual([]);
});
+it.each([
+ ['https://api.elevenlabs.io/v1', 'elevenlabs', 'openai'],
+ ['https://api.minimax.io/anthropic', 'minimax', 'elevenlabs'],
+ ['https://api.minimax.cn/v1', 'minimax', 'openai'],
+ ['https://api.minimaxi.com/v1', 'minimax', 'openai'],
+ ['https://api.minimax.chat/v1', 'minimax', 'openai'],
+ ['https://api-uw.minimax.io/v1', 'minimax', 'openai'],
+ ['https://api.openai.com/v1', 'openai', 'minimax'],
+] as const)(
+ 'keeps %s on its official %s contract even with a saved %s override',
+ (baseUrl, protocol, savedProtocol) => {
+ // The host contract also wins over absent, unverified or incompatible catalog metadata.
+ for (const nativeApi of [undefined, null, 'openai-audio-speech'] as const) {
+ const d = deps([
+ custom('official', baseUrl, [
+ { id: 'speech', name: 'Speech', mode: 'audio_speech', nativeApi },
+ ]),
+ ]);
+ expect(speechModels(d)[0]).toMatchObject({ protocol, protocolLocked: true });
+ expect(
+ resolveSpeechConnection(d, {
+ providerId: 'official',
+ agent: 'codex',
+ modelId: 'speech',
+ protocol: savedProtocol,
+ }),
+ ).toEqual({
+ baseUrl: `${new URL(baseUrl).origin}/v1`,
+ protocol,
+ headers:
+ protocol === 'elevenlabs'
+ ? { 'xi-api-key': 'official-codex-key' }
+ : { authorization: 'Bearer official-codex-key' },
+ });
+ }
+ },
+);
+
+it.each([
+ 'https://speech-proxy.test/api.elevenlabs.io/v1',
+ 'https://api.elevenlabs.io.proxy.test/prefix/v1',
+ 'https://api.elevenlabs.io:8443/prefix/v1',
+ 'http://127.0.0.1:8000/prefix/v1',
+])(
+ 'preserves manual overrides for a compatible proxy at %s regardless of model brand',
+ (baseUrl) => {
+ const d = deps([
+ custom('proxy', baseUrl, [
+ { id: 'eleven_flash_v2_5', name: 'ElevenLabs', mode: 'audio_speech' },
+ ]),
+ ]);
+ expect(speechModels(d)[0].protocolLocked).toBe(false);
+ expect(
+ resolveSpeechConnection(d, {
+ providerId: 'proxy',
+ agent: 'codex',
+ modelId: 'eleven_flash_v2_5',
+ protocol: 'openai',
+ }),
+ ).toEqual({
+ baseUrl,
+ protocol: 'openai',
+ headers: { authorization: 'Bearer proxy-codex-key' },
+ });
+ },
+);
+
it('rejects cross-origin model overrides and stale credentials in headers; permits explicit local no-auth', () => {
const p = custom('p', 'https://api.elevenlabs.io/v1', [
{ id: 'v', name: 'V', mode: 'audio_speech' },
diff --git a/apps/desktop/src/main/voice-conversation/models.ts b/apps/desktop/src/main/voice-conversation/models.ts
index ddaec1591f..3da9aa0732 100644
--- a/apps/desktop/src/main/voice-conversation/models.ts
+++ b/apps/desktop/src/main/voice-conversation/models.ts
@@ -60,18 +60,9 @@ function nativeProtocol(catalog: Catalog, providerId: string, model: ProviderMed
: resolveModelNativeApi(BUNDLED_CATALOG.modelRegistry, providerId, model.id);
}
-/** Endpoint adapters are explicit contracts, not guesses based on a model name or chat wire. */
-function customProtocol(
- base: URL,
- declared: ReturnType<typeof nativeProtocol>,
-): SpeechProtocol | null {
- if (declared === 'openai-audio-speech') return 'openai';
- if (declared !== undefined) return null; // Includes an explicit unverified/null declaration.
- return endpointProtocol(base);
-}
-
+/** Official endpoints fix the adapter, independently of model names or catalog metadata. */
function endpointProtocol(base: URL): SpeechProtocol | null {
- if (base.protocol !== 'https:') return null;
+ if (base.protocol !== 'https:' || base.port) return null;
if (base.hostname === 'api.elevenlabs.io') return 'elevenlabs';
if (
[
@@ -141,11 +132,15 @@ function bindings(deps: SpeechCatalogDeps, selection?: SpeechModelSelection): Bi
const base = apiBase(model.route?.baseUrl ?? route.upstream);
const ownerBase = apiBase(route.upstream);
if (!base || !ownerBase || base.origin !== ownerBase.origin) continue;
- const detectedProtocol = customProtocol(base, declared);
- const protocol = selection?.protocol ?? detectedProtocol;
+ const fixedProtocol = endpointProtocol(base);
+ const detectedProtocol =
+ fixedProtocol ?? (declared === 'openai-audio-speech' ? 'openai' : null);
+ // A saved override cannot turn an official endpoint into another provider's API.
+ // Custom proxies retain explicit choices, including for null/unverified metadata.
+ const protocol = fixedProtocol ?? selection?.protocol ?? detectedProtocol;
// Official native adapters use their documented origin endpoint. Compatible
// OpenAI proxies keep the configured prefix (including a non-/v1 API base).
- if (protocol !== 'openai' && endpointProtocol(base) === protocol) base.pathname = '/v1';
+ if (fixedProtocol && fixedProtocol !== 'openai') base.pathname = '/v1';
else if (!base.pathname || base.pathname === '/') base.pathname = '/v1';
const headers: Record<string, string> = {};
for (const [name, value] of Object.entries(route.headerOverride ?? {})) {
@@ -189,6 +184,7 @@ function bindings(deps: SpeechCatalogDeps, selection?: SpeechModelSelection): Bi
providerName: provider.name,
agent,
protocol: detectedProtocol ?? undefined,
+ protocolLocked: !!fixedProtocol,
defaultVoice: referenceSpeechVoices(media.id, protocol ?? undefined)[0] ?? '',
},
connection: protocol
diff --git a/apps/desktop/src/renderer/features/bots/voice/CompanionVoicePanel.tsx b/apps/desktop/src/renderer/features/bots/voice/CompanionVoicePanel.tsx
index 9fb9b8bb34..8799a225ca 100644
--- a/apps/desktop/src/renderer/features/bots/voice/CompanionVoicePanel.tsx
+++ b/apps/desktop/src/renderer/features/bots/voice/CompanionVoicePanel.tsx
@@ -65,16 +65,25 @@ export function CompanionVoicePanel(props: Props) {
? models.find((model) => voiceModelKey(model) === voiceModelKey(preference))
: models[0];
const validModel = !!selectedModel;
- const selectedVoice = voice ?? preference?.voice ?? selectedModel?.defaultVoice ?? '';
+ const protocolOverride = selectedModel?.protocolLocked ? undefined : preference?.protocol;
+ const incompatibleSavedProtocol =
+ selectedModel?.protocolLocked &&
+ preference?.protocol !== undefined &&
+ preference.protocol !== selectedModel.protocol;
+ // A voice saved for another adapter is not portable. Keep the stored preference
+ // intact until the user chooses a voice; never persist a derived default on load.
+ const selectedVoice =
+ voice ??
+ (incompatibleSavedProtocol ? '' : (preference?.voice ?? selectedModel?.defaultVoice ?? ''));
const selection = normalizeVoiceConversationSelection({
providerId: selectedModel?.providerId,
agent: selectedModel?.agent,
modelId: selectedModel?.id,
- protocol: preference?.protocol,
+ protocol: protocolOverride,
voice: selectedVoice,
});
const protocol =
- preference?.protocol ??
+ protocolOverride ??
selectedModel?.protocol ??
((selectedModel?.providerId ?? 'xd') === 'xd' ? 'openai' : undefined);
const controller = useMemo(
@@ -393,7 +402,13 @@ export function CompanionVoicePanel(props: Props) {
{selectedModel && selectedModel.providerId !== 'xd' && selectedModel.agent ? (
<FormField
label={t('bots.voiceMode.protocol')}
- hint={t('bots.voiceMode.protocolHint')}
+ hint={t(
+ incompatibleSavedProtocol && voice === undefined
+ ? 'bots.voiceMode.protocolCorrectedHint'
+ : selectedModel.protocolLocked
+ ? 'bots.voiceMode.protocolAutomaticHint'
+ : 'bots.voiceMode.protocolHint',
+ )}
className="min-w-52 flex-1"
>
{(control) => (
@@ -405,9 +420,12 @@ export function CompanionVoicePanel(props: Props) {
{ value: 'openai', label: t('bots.voiceMode.protocolOpenai') },
{ value: 'elevenlabs', label: 'ElevenLabs' },
{ value: 'minimax', label: 'MiniMax' },
- ]}
- disabled={!ready || saving || starting}
+ ].filter(
+ (option) => !selectedModel.protocolLocked || option.value === protocol,
+ )}
+ disabled={selectedModel.protocolLocked || !ready || saving || starting}
onValueChange={(value) => {
+ if (selectedModel.protocolLocked) return;
const next = {
providerId: selectedModel.providerId,
agent: selectedModel.agent,
@@ -436,7 +454,7 @@ export function CompanionVoicePanel(props: Props) {
providerId: selectedModel.providerId,
agent: selectedModel.agent,
modelId: selectedModel.id,
- protocol: preference?.protocol,
+ protocol: protocolOverride,
}}
protocol={protocol}
voice={selectedVoice}
@@ -450,7 +468,7 @@ export function CompanionVoicePanel(props: Props) {
providerId: selectedModel.providerId,
agent: selectedModel.agent,
modelId: selectedModel.id,
- protocol: preference?.protocol,
+ protocol: protocolOverride,
voice: value,
});
if (save && next && validModel) void persist(next);
diff --git a/apps/desktop/src/renderer/features/bots/voice/__tests__/CompanionVoicePanel.test.tsx b/apps/desktop/src/renderer/features/bots/voice/__tests__/CompanionVoicePanel.test.tsx
index 7a0d7aa4d5..041ec73a55 100644
--- a/apps/desktop/src/renderer/features/bots/voice/__tests__/CompanionVoicePanel.test.tsx
+++ b/apps/desktop/src/renderer/features/bots/voice/__tests__/CompanionVoicePanel.test.tsx
@@ -1,5 +1,5 @@
// @vitest-environment jsdom
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
import { voiceModelKey, type VoiceConversationModel } from '@/../shared/voiceConversation';
import { afterEach, beforeEach, expect, it, vi } from 'vitest';
@@ -215,6 +215,180 @@ it('requires an explicit API choice for an unknown endpoint before requesting a
);
});
+it.each(['elevenlabs', 'minimax', 'openai'] as const)(
+ 'shows only the fixed %s API for an official endpoint and keeps its saved voice',
+ async (protocol) => {
+ models = [
+ {
+ id: 'speech',
+ name: 'Speech',
+ providerId: 'official',
+ agent: 'codex',
+ protocol,
+ protocolLocked: true,
+ },
+ ];
+ vi.mocked(window.electronAPI.voiceConversation.preference).mockResolvedValue({
+ selection: {
+ providerId: 'official',
+ agent: 'codex',
+ modelId: 'speech',
+ protocol,
+ voice: 'saved-voice',
+ },
+ customized: true,
+ });
+ renderPanel();
+ await screen.findByText('bots.voiceMode.protocolAutomaticHint');
+ const field = screen.getByLabelText('bots.voiceMode.protocol') as HTMLSelectElement;
+ expect(field.disabled).toBe(true);
+ expect(field.value).toBe(protocol);
+ expect(
+ Array.from(field.options)
+ .map((option) => option.value)
+ .filter(Boolean),
+ ).toEqual([protocol]);
+ await waitFor(() =>
+ expect((screen.getByLabelText('bots.voiceMode.voiceId') as HTMLInputElement).value).toBe(
+ 'saved-voice',
+ ),
+ );
+ expect(window.electronAPI.voiceConversation.setPreference).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByRole('button', { name: 'bots.voiceMode.start' }));
+ await waitFor(() =>
+ expect(start).toHaveBeenCalledWith(
+ expect.objectContaining({ modelId: 'speech', voice: 'saved-voice' }),
+ ),
+ );
+ expect(
+ vi.mocked(window.electronAPI.voiceConversation.start).mock.calls[0][0],
+ ).not.toHaveProperty('protocol');
+ },
+);
+
+it('repairs a saved API mismatch without reusing its voice or rewriting preferences on load', async () => {
+ models = [
+ {
+ id: 'eleven_flash_v2_5',
+ name: 'ElevenLabs',
+ providerId: 'official',
+ agent: 'codex',
+ protocol: 'elevenlabs',
+ protocolLocked: true,
+ },
+ ];
+ vi.mocked(window.electronAPI.voiceConversation.preference).mockResolvedValue({
+ selection: {
+ providerId: 'official',
+ agent: 'codex',
+ modelId: 'eleven_flash_v2_5',
+ protocol: 'openai',
+ voice: 'alloy',
+ },
+ customized: true,
+ });
+ renderPanel();
+ await screen.findByText('bots.voiceMode.protocolCorrectedHint');
+ expect((screen.getByLabelText('bots.voiceMode.protocol') as HTMLSelectElement).value).toBe(
+ 'elevenlabs',
+ );
+ const voice = screen.getByLabelText('bots.voiceMode.voiceId') as HTMLInputElement;
+ expect(voice.value).toBe('');
+ expect(
+ screen.getByRole('button', { name: 'bots.voiceMode.preview' }).hasAttribute('disabled'),
+ ).toBe(true);
+ expect(
+ screen.getByRole('button', { name: 'bots.voiceMode.start' }).hasAttribute('disabled'),
+ ).toBe(true);
+ await waitFor(() =>
+ expect(window.electronAPI.voiceConversation.voices).toHaveBeenCalledWith({
+ providerId: 'official',
+ agent: 'codex',
+ modelId: 'eleven_flash_v2_5',
+ protocol: undefined,
+ }),
+ );
+ expect(window.electronAPI.voiceConversation.setPreference).not.toHaveBeenCalled();
+ fireEvent.change(voice, { target: { value: 'eleven-voice-id' } });
+ fireEvent.blur(voice);
+ await waitFor(() =>
+ expect(window.electronAPI.voiceConversation.setPreference).toHaveBeenCalledWith('bot', {
+ providerId: 'official',
+ agent: 'codex',
+ modelId: 'eleven_flash_v2_5',
+ voice: 'eleven-voice-id',
+ }),
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'bots.voiceMode.preview' }));
+ await waitFor(() =>
+ expect(window.electronAPI.voiceConversation.preview).toHaveBeenCalledWith(
+ expect.objectContaining({ voice: 'eleven-voice-id' }),
+ ),
+ );
+ expect(
+ vi.mocked(window.electronAPI.voiceConversation.preview).mock.calls[0][0],
+ ).not.toHaveProperty('protocol');
+ expect(start).not.toHaveBeenCalled();
+ expect(audio.start).not.toHaveBeenCalled();
+});
+
+it('keeps a proxy API override and unlocks the selector after switching away from an official model', async () => {
+ models = [
+ {
+ id: 'eleven_flash_v2_5',
+ name: 'Official',
+ providerId: 'official',
+ agent: 'codex',
+ protocol: 'elevenlabs',
+ protocolLocked: true,
+ },
+ { id: 'eleven_flash_v2_5', name: 'Proxy', providerId: 'proxy', agent: 'codex' },
+ ];
+ vi.mocked(window.electronAPI.voiceConversation.preference).mockResolvedValue({
+ selection: {
+ providerId: 'proxy',
+ agent: 'codex',
+ modelId: 'eleven_flash_v2_5',
+ protocol: 'openai',
+ voice: 'proxy-voice',
+ },
+ customized: true,
+ });
+ renderPanel();
+ await waitFor(() =>
+ expect((screen.getByLabelText('bots.voiceMode.protocol') as HTMLSelectElement).value).toBe(
+ 'openai',
+ ),
+ );
+ expect((screen.getByLabelText('bots.voiceMode.voiceId') as HTMLInputElement).value).toBe(
+ 'proxy-voice',
+ );
+ await act(async () => {
+ fireEvent.change(screen.getByLabelText('bots.voiceMode.model'), {
+ target: { value: voiceModelKey(models[0]) },
+ });
+ });
+ expect((screen.getByLabelText('bots.voiceMode.protocol') as HTMLSelectElement).disabled).toBe(
+ true,
+ );
+ await act(async () => {
+ fireEvent.change(screen.getByLabelText('bots.voiceMode.model'), {
+ target: { value: voiceModelKey(models[1]) },
+ });
+ });
+ const field = screen.getByLabelText('bots.voiceMode.protocol') as HTMLSelectElement;
+ expect(field.disabled).toBe(false);
+ expect(
+ Array.from(field.options)
+ .map((option) => option.value)
+ .filter(Boolean),
+ ).toEqual(['openai', 'elevenlabs', 'minimax']);
+ await act(async () => {
+ fireEvent.change(field, { target: { value: 'minimax' } });
+ });
+ expect(field.value).toBe('minimax');
+});
+
it('preserves an unavailable saved connection until the user restores defaults', async () => {
models = [
{
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 09eebb2b1a..1b1bea1d79 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -9437,7 +9437,9 @@
"preferenceError": "Could not load or save voice settings. Please try again.",
"protocol": "Speech API",
"protocolOpenai": "OpenAI compatible",
- "protocolHint": "Choose the speech API used by this connection. The chat API is unchanged."
+ "protocolHint": "Choose the speech API this address supports. This does not switch providers.",
+ "protocolAutomaticHint": "Matched automatically to the provider’s official address.",
+ "protocolCorrectedHint": "The API now matches the official address. Choose a voice again."
}
},
"common": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index a357e438aa..6ade93e77c 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -9400,7 +9400,9 @@
"preferenceError": "音声設定を読み込むか保存できませんでした。もう一度お試しください。",
"protocol": "音声 API",
"protocolOpenai": "OpenAI 互換",
- "protocolHint": "この接続が使用する音声 API を選択します。チャット API は変更されません。"
+ "protocolHint": "このアドレスが対応する音声 API を選択してください。プロバイダーは切り替わりません。",
+ "protocolAutomaticHint": "プロバイダーの公式アドレスに合わせて自動選択されています。",
+ "protocolCorrectedHint": "公式アドレスに合わせて API を修正しました。音声を選び直してください。"
}
},
"common": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 12cf2da089..c9ccb26f27 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -9400,7 +9400,9 @@
"preferenceError": "음성 설정을 불러오거나 저장하지 못했습니다. 다시 시도해 주세요.",
"protocol": "음성 API",
"protocolOpenai": "OpenAI 호환",
- "protocolHint": "이 연결에서 사용하는 음성 API를 선택하세요. 채팅 API는 변경되지 않습니다."
+ "protocolHint": "이 주소가 지원하는 음성 API를 선택하세요. 제공자는 변경되지 않습니다.",
+ "protocolAutomaticHint": "제공자의 공식 주소에 맞춰 자동으로 선택되었습니다.",
+ "protocolCorrectedHint": "공식 주소에 맞게 API를 수정했습니다. 음성을 다시 선택하세요."
}
},
"common": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index dc85b0f786..625b3a8f9b 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -9400,7 +9400,9 @@
"preferenceError": "未能读取或保存语音设置,请重试。",
"protocol": "语音接口",
"protocolOpenai": "OpenAI 兼容",
- "protocolHint": "选择该连接使用的语音接口,不影响对话接口。"
+ "protocolHint": "选择此地址实际支持的语音接口;切换接口不会更换供应商。",
+ "protocolAutomaticHint": "已根据供应商的官方地址自动匹配。",
+ "protocolCorrectedHint": "已按官方地址修正接口,请重新选择音色。"
}
},
"common": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index bd43972764..62af549b4b 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -9400,7 +9400,9 @@
"preferenceError": "無法讀取或儲存語音設定,請重試。",
"protocol": "語音介面",
"protocolOpenai": "OpenAI 相容",
- "protocolHint": "選擇此連接使用的語音介面,不影響對話介面。"
+ "protocolHint": "選擇此位址實際支援的語音介面;切換介面不會更換供應商。",
+ "protocolAutomaticHint": "已根據供應商的官方位址自動配對。",
+ "protocolCorrectedHint": "已依官方位址修正介面,請重新選擇音色。"
}
},
"common": {
diff --git a/apps/desktop/src/shared/voiceConversation.ts b/apps/desktop/src/shared/voiceConversation.ts
index 20c765aa57..a439d7c3a2 100644
--- a/apps/desktop/src/shared/voiceConversation.ts
+++ b/apps/desktop/src/shared/voiceConversation.ts
@@ -8,7 +8,7 @@ export type SpeechModelSelection = {
providerId?: string;
agent?: AgentKind;
modelId: string;
- /** Explicit user choice for a custom speech endpoint; absent follows a known adapter. */
+ /** Custom endpoints allow overrides; official endpoints always use their own adapter. */
protocol?: SpeechProtocol;
};
export type VoiceConversationSelection = SpeechModelSelection & { voice: string };
@@ -32,6 +32,8 @@ export type VoiceConversationModel = {
providerName?: string;
agent?: AgentKind;
protocol?: SpeechProtocol;
+ /** The official endpoint fixes protocol; saved overrides cannot select another adapter. */
+ protocolLocked?: boolean;
defaultVoice?: string;
};
export type VoiceConversationPreference = {
diff --git a/docs/product-rules/companion-voice-mode.md b/docs/product-rules/companion-voice-mode.md
index 439e5bd83f..ad5670731a 100644
--- a/docs/product-rules/companion-voice-mode.md
+++ b/docs/product-rules/companion-voice-mode.md
@@ -8,9 +8,10 @@
- 原任务空闲时正常发送,仍在运行时沿既有插话路径投递。语音是本机用户本人输入,不盖自动化或远程设备来源标签,不增加系统提示词。识别结果按普通文字发送,不执行桌面斜杠命令。
- 最终回复经过持久化完成标记确认后才朗读。按本次语音发送的 clientId 关联,不朗读历史、过程文字、工具、子代理、内部协调或群来源私信。文本消息始终是对话记录的正本。
- 独立选择朗读模型和音色,按当前账号下的伙伴保存,不改变聊天模型。来源包括有权限的 Cindy AI,以及已连接的本地 BYOK 供应商;候选必须是 `audio_speech`、未停用且具备可用的 API key 或明确的本机免鉴权连接。同名模型按连接 ID、runtime 和上游模型 ID 区分,不能借另一连接的密钥。无候选时显示空状态,不采集麦克风。
-- BYOK 支持 OpenAI 兼容、ElevenLabs、MiniMax 三种语音接口。已声明的 OpenAI speech 协议或已知官方端点可确定默认接口;其余候选(包括显式未验证协议)必须由用户在语音面板明确选择接口,不能只凭模型名、`mode` 或聊天协议推断。这个覆盖仅作用于当前伙伴的朗读,不重写公共 Registry 或供应商的聊天协议。音色支持列表选择、手动输入和试听;本次不提供创建或删除克隆音色的能力。
+- BYOK 支持 OpenAI 兼容、ElevenLabs、MiniMax 三种语音接口。已知官方 HTTPS 地址自动匹配并固定接口,面板显示匹配说明、禁用接口选择,Main 同样采用该官方接口,不接受旧偏好或调用参数切换到其他厂商协议。自定义/中转地址保留手动选择;已声明的 OpenAI speech 协议可作为默认,其余候选(包括显式未验证协议)须用户明确选择。不能只凭模型名、`mode` 或聊天协议推断,切换接口不会更换连接地址或凭证。这个覆盖仅作用于当前伙伴的朗读,不重写公共 Registry 或供应商的聊天协议。音色支持列表选择、手动输入和试听;本次不提供创建或删除克隆音色的能力。
- 模型、语音接口和音色为伙伴级显式偏好,打开面板、重启后保留。恢复默认删除该伙伴的选择,继续跟随可用目录;已有旧版全局偏好仍可继承,单独重置一个伙伴时以 `null` 清除该伙伴的旧偏好继承,不复制默认模型、不影响其他伙伴。保存失败明确提示。保存的连接消失或停用时保留选择并禁止开始,不静默改用同名模型。
- 更换连接、runtime、型号或接口时,不沿用旧音色;目标型号有明确参考默认值才填入,否则等待用户选择或输入。同一连接下的不同型号也不视为音色兼容。已有保存音色不因刷新失败、列表未收录而被覆盖,仍显示在手动输入中。
+- 旧偏好中的接口与官方地址冲突时,面板采用官方接口并提示重新选择音色,重新选择前不试听或开始;正确接口下的已有音色继续保留。读取偏好时不写回推导默认值,用户选择音色后通过既有保存流程移除不适用的接口覆盖。自定义/中转地址的显式接口与音色偏好不受影响。
- 刷新重新读取当前有效目录,并尝试刷新 Cindy AI;Gateway 刷新失败不阻止本机 BYOK 目录显示。新增第三方型号仍沿设置页已有的获取列表、手动添加和启用流程。
- 朗读结束继续监听。用户开口时立即取消待生成及正在播放的声音;新的文字仍投递到原任务。停止朗读不会取消 Agent 工具、清空任务队列或代答权限确认。
- 需要确认权限、问题或计划,或任务队列暂停时,关闭麦克风并暂停语音模式;用户完成确认后显式继续。静音、锁屏、休眠、切走任务、关面板、账号切换同样释放采集和播放资源,不在后台重新开始。
@@ -39,7 +40,7 @@
| ElevenLabs | `<base>/text-to-speech/<voiceId>/stream?output_format=pcm_24000`,`xi-api-key`,`model_id / text` | 原始 PCM |
| MiniMax | `<base>/t2a_v2`,Bearer,`stream: true`、`exclude_aggregated_audio: true`、`output_format: hex`、`voice_setting.voice_id`、24kHz 单声道 PCM | SSE JSON 的 hex 音频;检查业务错误及格式,结束包的聚合音频不重复播放 |
-官方域名使用文档规定的 `/v1` 语音端点,MiniMax 的 `/anthropic` 聊天路径不会被沿用。用户指定的兼容代理保留配置的 API base 路径前缀;如果代理提供不同的语音根路径,应在设置中新增独立连接。接口选择不证明供应商的型号、付费方案或音色可用,执行失败仍回到文字。
+已知官方 HTTPS origin(默认端口)固定使用该服务的接口;具体列表由 `main/voice-conversation/models.ts` 维护,不按型号品牌锁定。此规则确定执行适配器,不修改 Registry 的 `nativeApi` 声明,也不证明目录里的型号可执行。ElevenLabs / MiniMax 使用文档规定的 `/v1` 语音端点,MiniMax 的 `/anthropic` 聊天路径不会被沿用。用户指定的兼容代理保留配置的 API base 路径前缀;如果代理提供不同的语音根路径,应在设置中新增独立连接。接口选择不证明供应商的型号、付费方案或音色可用,执行失败仍回到文字。
原生接口依据:[ElevenLabs stream](https://elevenlabs.io/docs/api-reference/text-to-speech/stream)、[MiniMax HTTP TTS](https://platform.minimax.io/docs/api-reference/speech-t2a-http)。响应有类型、大小、超时和完整性检查,重定向被拒绝,上游原始错误不穿过 IPC。流式传输与插话取消共用原有代次检查和播放背压,不增加音频落盘。