From 5113eaf245c60ea86ce7b1a484ed3bbdd8ebacfa Mon Sep 17 00:00:00 2001
From: Chris233 <h-chris233@outlook.com>
Date: Wed, 9 Sep 2026 14:57:35 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat(providers):=20=E7=BB=9F=E4=B8=80?=
 =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E5=AD=97=E6=AE=B5=E3=80=81=E6=90=9C=E7=B4=A2?=
 =?UTF-8?q?=E4=B8=8E=E5=BC=82=E6=AD=A5=E4=BF=9D=E5=AD=98=E9=9A=94=E7=A6=BB?=
 =?UTF-8?q?=20(#1044)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(providers): unify model fields and isolate asynchronous updates

* fix(providers): preserve pending credential drafts
---
 .../openless-core/src/provider_rules.rs       |  13 +
 .../app/src/components/SettingsModal.tsx      |  15 +-
 .../app/src/components/ui/SelectLite.tsx      |   8 +-
 .../app/src/lib/ipc/asr-credentials.ts        |   8 +-
 .../lib/ipc/mock-provider-descriptors.json    |  48 ++
 openless-all/app/src/lib/ipc/providers.ts     |  23 +-
 .../app/src/pages/settings/ChannelList.tsx    |  16 +-
 .../pages/settings/LlmProtocolFields.test.ts  |   6 +-
 .../src/pages/settings/LlmProtocolFields.tsx  |  21 +-
 .../app/src/pages/settings/ProviderForm.tsx   |  46 ++
 .../pages/settings/ProvidersSection.test.ts   |  18 +-
 .../src/pages/settings/ProvidersSection.tsx   | 745 +++++-------------
 .../pages/settings/credentialDraft.test.ts    |  91 +++
 .../app/src/pages/settings/credentialDraft.ts |  64 ++
 .../src/pages/settings/modelCatalog.test.ts   |  47 ++
 .../app/src/pages/settings/modelCatalog.ts    |  23 +
 16 files changed, 590 insertions(+), 602 deletions(-)
 create mode 100644 openless-all/app/src/lib/ipc/mock-provider-descriptors.json
 create mode 100644 openless-all/app/src/pages/settings/ProviderForm.tsx
 create mode 100644 openless-all/app/src/pages/settings/credentialDraft.test.ts
 create mode 100644 openless-all/app/src/pages/settings/credentialDraft.ts
 create mode 100644 openless-all/app/src/pages/settings/modelCatalog.test.ts
 create mode 100644 openless-all/app/src/pages/settings/modelCatalog.ts

diff --git a/openless-all/app/crates/openless-core/src/provider_rules.rs b/openless-all/app/crates/openless-core/src/provider_rules.rs
index 50aad94a..a2efeb6a 100644
--- a/openless-all/app/crates/openless-core/src/provider_rules.rs
+++ b/openless-all/app/crates/openless-core/src/provider_rules.rs
@@ -1084,6 +1084,19 @@ mod tests {
         }
     }
 
+    #[test]
+    fn browser_provider_descriptor_fixture_matches_core() {
+        let fixture: Vec<ProviderDescriptor> = serde_json::from_str(include_str!(
+            "../../../src/lib/ipc/mock-provider-descriptors.json"
+        ))
+        .unwrap();
+        let actual = [ProviderKind::Llm, ProviderKind::Asr, ProviderKind::Omni]
+            .into_iter()
+            .flat_map(provider_descriptors)
+            .collect::<Vec<_>>();
+        assert_eq!(fixture, actual);
+    }
+
     #[test]
     fn secret_like_volc_resource_ids_are_not_attributed() {
         assert_eq!(
diff --git a/openless-all/app/src/components/SettingsModal.tsx b/openless-all/app/src/components/SettingsModal.tsx
index e8cf8b8c..e36e08e4 100644
--- a/openless-all/app/src/components/SettingsModal.tsx
+++ b/openless-all/app/src/components/SettingsModal.tsx
@@ -8,6 +8,7 @@
 //
 // 设计原则：每个可见控件都必须可用。
 
+import { ProviderLeaveContext, useProviderForm } from '../pages/settings/ProviderForm';
 import { useLayoutEffect, useRef, useState, type CSSProperties } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Icon } from './Icon';
@@ -57,6 +58,8 @@ const LINK_ITEMS: ModalNavItem[] = [
 ];
 
 export function SettingsModal({ os: _os, onClose, initialSettingsSection }: SettingsModalProps) {
+  const providerForm = useProviderForm();
+  const close = () => { void providerForm.finish(onClose); };
   const { t } = useTranslation();
   const mobile = useMobileLayout();
   const conservative = useConservativeLayout();
@@ -78,8 +81,9 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
   }, [section, mobile]);
 
   return (
+    <ProviderLeaveContext.Provider value={providerForm.register}>
     <div
-      onClick={mobile ? undefined : onClose}
+      onClick={mobile ? undefined : close}
       style={{
         position: mobile ? 'fixed' : 'absolute',
         inset: 0,
@@ -124,7 +128,7 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
           }}>
             <button
               type="button"
-              onClick={onClose}
+              onClick={close}
               aria-label={t('common.close')}
               style={mobileHeaderBtnStyle}
             >
@@ -140,7 +144,7 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
                   <button
                     key={it.id}
                     type="button"
-                    onClick={() => setSection(it.id as SettingsSectionId)}
+                    onClick={() => void providerForm.finish(() => setSection(it.id as SettingsSectionId))}
                     className={active ? 'ol-nav-btn ol-nav-btn-active' : 'ol-nav-btn'}
                     style={mobileTabChipStyle(active)}
                   >
@@ -186,7 +190,7 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
                 <button
                   key={it.id}
                   ref={el => { tabRefs.current[idx] = el; }}
-                  onClick={() => setSection(it.id as SettingsSectionId)}
+                  onClick={() => void providerForm.finish(() => setSection(it.id as SettingsSectionId))}
                   className={active ? 'ol-nav-btn ol-nav-btn-active' : 'ol-nav-btn'}
                   style={navBtnStyle}>
                   <Icon name={it.icon} size={14} />
@@ -223,7 +227,7 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
           />
           {!mobile && (
           <button
-            onClick={onClose}
+            onClick={close}
             style={{
               position: 'absolute', top: 14, right: 14, zIndex: 2,
               width: 28, height: 28, border: 0, borderRadius: 999,
@@ -288,6 +292,7 @@ export function SettingsModal({ os: _os, onClose, initialSettingsSection }: Sett
         </div>
       </div>
     </div>
+    </ProviderLeaveContext.Provider>
   );
 }
 
diff --git a/openless-all/app/src/components/ui/SelectLite.tsx b/openless-all/app/src/components/ui/SelectLite.tsx
index 01bb432c..a502c96f 100644
--- a/openless-all/app/src/components/ui/SelectLite.tsx
+++ b/openless-all/app/src/components/ui/SelectLite.tsx
@@ -35,6 +35,8 @@ export interface SelectOption {
   value: string;
   label: string;
   disabled?: boolean;
+  /** 搜索期间仍保留操作项，例如自定义输入入口。 */
+  alwaysVisible?: boolean;
   /** 可选：渲染在选项标签右侧、勾选标记左侧（如麦克风音量条）。 */
   trailing?: ReactNode;
 }
@@ -111,7 +113,7 @@ export function SelectLite({
     const needle = query.trim().toLocaleLowerCase();
     if (!needle) return options;
     return options.filter(option => (
-      option.label.toLocaleLowerCase().includes(needle)
+      option.alwaysVisible || option.label.toLocaleLowerCase().includes(needle)
       || option.value.toLocaleLowerCase().includes(needle)
     ));
   }, [options, query]);
@@ -263,6 +265,7 @@ export function SelectLite({
   };
 
   const selectIndex = (index: number) => {
+    if (disabled) return;
     const option = filteredOptions[index];
     if (!option || option.disabled) return;
     onChange(option.value);
@@ -319,6 +322,7 @@ export function SelectLite({
   };
 
   const handleSearchKeyDown = (event: ReactKeyboardEvent<HTMLInputElement>) => {
+    if (event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229) return;
     if (event.key === 'Escape') {
       event.preventDefault();
       closeMenu();
@@ -459,7 +463,7 @@ export function SelectLite({
             role="listbox"
             style={{ maxHeight: searchable ? 274 : 272, overflowY: 'auto' }}
           >
-            {filteredOptions.length === 0 && (
+            {!filteredOptions.some(option => !option.alwaysVisible) && (
               <div
                 style={{
                   padding: '18px 10px',
diff --git a/openless-all/app/src/lib/ipc/asr-credentials.ts b/openless-all/app/src/lib/ipc/asr-credentials.ts
index 183426de..51c1d14b 100644
--- a/openless-all/app/src/lib/ipc/asr-credentials.ts
+++ b/openless-all/app/src/lib/ipc/asr-credentials.ts
@@ -2,7 +2,7 @@ import type { CredentialsStatus } from "../types"
 import { invokeOrMock, isTauri } from "./shared"
 import { mockCredentialsStatus, mockCredentialValues } from "./mock-data"
 import { invalidateMockChannelTest } from "./channels"
-import type { LlmRequestFormat } from "./providers"
+import { listProviderDescriptors, type LlmRequestFormat } from "./providers"
 
 export interface ProviderCheckResult {
     ok: boolean
@@ -104,6 +104,10 @@ export async function listProviderModels(
     channelId?: string,
     providerType?: string,
 ): Promise<ProviderModelsResult> {
+    if (!isTauri) {
+        const descriptor = (await listProviderDescriptors(kind)).find(item => item.providerType === providerType)
+        if (descriptor?.staticModels.length) return { models: descriptor.staticModels }
+    }
     if (!isTauri && providerType === "orcarouter" && (kind === "llm" || kind === "asr")) {
         const endpointAccount = kind === "llm" ? "ark.endpoint" : "asr.endpoint"
         const endpoint = mockCredentialValues.get(`${channelId ?? ''}:${endpointAccount}`)
@@ -124,6 +128,6 @@ export async function listProviderModels(
         models:
             kind === "llm"
                 ? ["gpt-4o", "deepseek-v4-flash", "deepseek-v4-pro"]
-                : ["whisper-1"],
+                : kind === "omni" ? ["gpt-4o-audio-preview", "qwen3-omni-flash"] : ["whisper-1"],
     }))
 }
diff --git a/openless-all/app/src/lib/ipc/mock-provider-descriptors.json b/openless-all/app/src/lib/ipc/mock-provider-descriptors.json
new file mode 100644
index 00000000..f991e8fb
--- /dev/null
+++ b/openless-all/app/src/lib/ipc/mock-provider-descriptors.json
@@ -0,0 +1,48 @@
+[
+  {"kind":"llm","providerType":"ark","labelKey":"ark","defaultEndpoint":"https://ark.cn-beijing.volces.com/api/v3","defaultModel":"deepseek-v3-2","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"deepseek","labelKey":"deepseek","defaultEndpoint":"https://api.deepseek.com/v1","defaultModel":"deepseek-v4-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"siliconflow","labelKey":"siliconflow","defaultEndpoint":"https://api.siliconflow.cn/v1","defaultModel":"Qwen/Qwen2.5-7B-Instruct","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"atlascloud","labelKey":"atlascloud","defaultEndpoint":"https://api.atlascloud.ai/v1","defaultModel":"qwen/qwen3.5-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"openai","labelKey":"openai","defaultEndpoint":"https://api.openai.com/v1","defaultModel":"gpt-4o","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"gemini","labelKey":"gemini","defaultEndpoint":"https://generativelanguage.googleapis.com/v1beta","defaultModel":"gemini-2.5-flash","authRequirement":"api_key","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"llm","providerType":"codex_oauth","labelKey":"codexOAuth","defaultEndpoint":null,"defaultModel":"gpt-5.5","authRequirement":"o_auth","validationProbe":"llm_text","staticModels":["gpt-5.5","gpt-5.3-codex","gpt-5.4","gpt-5.5"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"llm","providerType":"mimo","labelKey":"mimo","defaultEndpoint":"https://api.xiaomimimo.com/v1","defaultModel":"xiaomi/mimo-v2-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"cometapi","labelKey":"cometapi","defaultEndpoint":"https://api.cometapi.com/v1","defaultModel":"gpt-4o","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"openrouterFree","labelKey":"openrouterFree","defaultEndpoint":"https://openrouter.ai/api/v1","defaultModel":"qwen/qwen3-coder:free","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"orcarouter","labelKey":"orcarouter","defaultEndpoint":"https://api.orcarouter.ai/v1","defaultModel":"orcarouter/fusion-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"alibabaCoding","labelKey":"alibabaCoding","defaultEndpoint":"https://coding-intl.dashscope.aliyuncs.com/v1","defaultModel":"qwen3-coder-plus","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"codingPlanX","labelKey":"codingPlanX","defaultEndpoint":"https://api.codingplanx.ai/v1","defaultModel":"gpt-5-mini","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"minimax","labelKey":"minimax","defaultEndpoint":"https://api.minimaxi.com/v1","defaultModel":"MiniMax-M3","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"stepfun","labelKey":"stepfun","defaultEndpoint":"https://api.stepfun.com/v1","defaultModel":"step-1o-turbo-vision","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"opencode","labelKey":"opencode","defaultEndpoint":"https://opencode.ai/zen/v1","defaultModel":"deepseek-v4-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"custom","labelKey":"customChatCompletions","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"custom_responses","labelKey":"customResponses","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"responses","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"custom_messages","labelKey":"customMessages","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"messages","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"asr","providerType":"volcengine","labelKey":"asrVolcengine","defaultEndpoint":null,"defaultModel":null,"authRequirement":"volcengine","validationProbe":"asr_silence_allows_no_final","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"elevenlabs","labelKey":"asrElevenLabs","defaultEndpoint":"https://api.elevenlabs.io/v1","defaultModel":"scribe_v2","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":["scribe_v2"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"bailian","labelKey":"asrBailian","defaultEndpoint":"wss://dashscope.aliyuncs.com/api-ws/v1/inference/","defaultModel":"fun-asr-realtime","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":["fun-asr-realtime","fun-asr-flash-8k-realtime","qwen3-asr-flash-realtime","qwen3-asr-flash-realtime-2026-02-10","qwen3-asr-flash-realtime-2025-10-27","qwen-audio-3.0-asr-flash","fun-asr-flash-2026-06-15","qwen3-asr-flash","fun-asr","fun-asr-2025-11-07","fun-asr-2025-08-25","fun-asr-mtl","fun-asr-mtl-2025-08-25","paraformer-v2"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"bailian-qwen3-realtime","labelKey":"asrBailianQwen3","defaultEndpoint":"wss://dashscope.aliyuncs.com/api-ws/v1/realtime","defaultModel":"qwen3-asr-flash-realtime","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":["qwen3-asr-flash-realtime","qwen3-asr-flash-realtime-2026-02-10","qwen3-asr-flash-realtime-2025-10-27"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"bailian-fun-asr-flash","labelKey":"asrBailianFunAsrFlash","defaultEndpoint":"https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation","defaultModel":"fun-asr-flash-2026-06-15","authRequirement":"api_key","validationProbe":"asr_non_silent","staticModels":["qwen-audio-3.0-asr-flash","fun-asr-flash-2026-06-15"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"siliconflow","labelKey":"asrSiliconflow","defaultEndpoint":"https://api.siliconflow.cn/v1","defaultModel":"FunAudioLLM/SenseVoiceSmall","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"stepfun","labelKey":"asrStepfun","defaultEndpoint":"https://api.stepfun.com/v1","defaultModel":"stepaudio-2.5-asr","authRequirement":"api_key","validationProbe":"stepfun_no_speech","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"zhipu","labelKey":"asrZhipu","defaultEndpoint":"https://open.bigmodel.cn/api/paas/v4","defaultModel":"glm-asr-2512","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"groq","labelKey":"asrGroq","defaultEndpoint":"https://api.groq.com/openai/v1","defaultModel":"whisper-large-v3-turbo","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"whisper","labelKey":"asrWhisper","defaultEndpoint":"https://api.openai.com/v1","defaultModel":"whisper-1","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"openrouter","labelKey":"asrOpenrouter","defaultEndpoint":"https://openrouter.ai/api/v1","defaultModel":"openai/whisper-large-v3-turbo","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"orcarouter","labelKey":"orcarouter","defaultEndpoint":"https://api.orcarouter.ai/v1","defaultModel":"google/gemini-2.5-flash","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"zenmux","labelKey":"asrZenmux","defaultEndpoint":"https://zenmux.ai/api/v1","defaultModel":"qwen/qwen3-asr-flash","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"openai-compatible","labelKey":"asrOpenAiCompatible","defaultEndpoint":null,"defaultModel":null,"authRequirement":"endpoint_model_optional_api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"xiaomi-mimo-asr","labelKey":"asrXiaomiMimo","defaultEndpoint":"https://api.xiaomimimo.com/v1","defaultModel":"mimo-v2.5-asr","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":["mimo-v2.5-asr"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"iflytek","labelKey":"asrIflytek","defaultEndpoint":null,"defaultModel":null,"authRequirement":"xfyun","validationProbe":"asr_silence_allows_no_final","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"foundry-local-whisper","labelKey":"asrFoundryLocalWhisper","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"local-whisper","labelKey":"asrLocalWhisper","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"sherpa-onnx-local","labelKey":"asrSherpaOnnxLocal","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"local-qwen3-mlx","labelKey":"asrLocalQwen3Mlx","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"local-qwen3-c","labelKey":"asrLocalQwen3C","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"local-qwen3","labelKey":"asrLocalQwen3","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"apple-speech","labelKey":"asrAppleSpeech","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"omni","providerType":"openai","labelKey":"omniOpenai","defaultEndpoint":"https://api.openai.com/v1","defaultModel":"gpt-4o-audio-preview","authRequirement":"api_key","validationProbe":"omni_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"omni","providerType":"gemini","labelKey":"omniGemini","defaultEndpoint":"https://generativelanguage.googleapis.com/v1beta","defaultModel":"gemini-2.5-flash","authRequirement":"api_key","validationProbe":"omni_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"omni","providerType":"dashscope-omni","labelKey":"omniDashscope","defaultEndpoint":"https://dashscope.aliyuncs.com/compatible-mode/v1","defaultModel":"qwen3-omni-flash","authRequirement":"api_key","validationProbe":"omni_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"omni","providerType":"custom","labelKey":"custom","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key","validationProbe":"omni_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]}
+]
diff --git a/openless-all/app/src/lib/ipc/providers.ts b/openless-all/app/src/lib/ipc/providers.ts
index 8387f284..f536d8ce 100644
--- a/openless-all/app/src/lib/ipc/providers.ts
+++ b/openless-all/app/src/lib/ipc/providers.ts
@@ -1,3 +1,4 @@
+import mockDescriptors from './mock-provider-descriptors.json'
 import { invokeOrMock } from './shared'
 
 export type ProviderKind = 'asr' | 'llm' | 'omni'
@@ -27,23 +28,7 @@ export interface ProviderDescriptor {
 
 /** Core owns protocol, defaults, and credential requirements. */
 export function listProviderDescriptors(kind: ProviderKind): Promise<ProviderDescriptor[]> {
-  return invokeOrMock('list_provider_descriptors', { kind }, () => kind === 'llm' ? [
-    ['opencode', 'opencode', 'chat_completions'],
-    ['orcarouter', 'orcarouter', 'chat_completions'],
-    ['custom', 'customChatCompletions', 'chat_completions'],
-    ['custom_responses', 'customResponses', 'responses'],
-    ['custom_messages', 'customMessages', 'messages'],
-  ].map(([providerType, labelKey, format]) => ({
-    kind, providerType, labelKey,
-    defaultEndpoint: providerType === 'orcarouter' ? 'https://api.orcarouter.ai/v1' : providerType === 'opencode' ? 'https://opencode.ai/zen/v1' : null,
-    defaultModel: providerType === 'orcarouter' ? 'orcarouter/fusion-flash' : providerType === 'opencode' ? 'deepseek-v4-flash' : null,
-    authRequirement: 'api_key_unless_custom_endpoint', validationProbe: 'llm_text', staticModels: [],
-    defaultRequestFormat: format as LlmRequestFormat,
-    supportedRequestFormats: ['chat_completions', 'responses', 'messages'],
-  })) : kind === 'asr' ? [{
-    kind, providerType: 'orcarouter', labelKey: 'orcarouter',
-    defaultEndpoint: 'https://api.orcarouter.ai/v1', defaultModel: 'google/gemini-2.5-flash',
-    authRequirement: 'api_key', validationProbe: 'asr_silence', staticModels: [],
-    defaultRequestFormat: null, supportedRequestFormats: [],
-  }] : [])
+  // Snapshot of Core provider_rules::provider_descriptors (all three kinds).
+  return invokeOrMock('list_provider_descriptors', { kind },
+    () => (mockDescriptors as ProviderDescriptor[]).filter(descriptor => descriptor.kind === kind))
 }
diff --git a/openless-all/app/src/pages/settings/ChannelList.tsx b/openless-all/app/src/pages/settings/ChannelList.tsx
index b13b97d3..7f5e23e6 100644
--- a/openless-all/app/src/pages/settings/ChannelList.tsx
+++ b/openless-all/app/src/pages/settings/ChannelList.tsx
@@ -30,6 +30,7 @@ import {
   type Channel,
   type ProviderDescriptor,
 } from '../../lib/ipc';
+import { ProviderFormContext, useProviderForm } from './ProviderForm';
 import { emitSaved } from '../../lib/savedEvent';
 import { useMobileLayout, useReadableLayout, useConservativeLayout } from '../../lib/useMobileLayout';
 import { useHotkeySettings } from '../../state/HotkeySettingsContext';
@@ -733,6 +734,7 @@ function ChannelModal({
   onUserMutation: () => void;
 }) {
   const { t } = useTranslation();
+  const form = useProviderForm();
   const [name, setName] = useState(channel.name);
   const [providerType, setProviderType] = useState(channel.providerType);
   const [changingProvider, setChangingProvider] = useState(false);
@@ -810,7 +812,8 @@ function ChannelModal({
   const isLocalEngine = descriptor?.authRequirement === 'none';
 
   return (
-    <Modal onClose={onClose} width={mobile ? 'min(560px, 100%)' : 'min(600px, 100%)'}>
+    <ProviderFormContext.Provider value={form}>
+    <Modal onClose={() => void form.finish(onClose)} width={mobile ? 'min(560px, 100%)' : 'min(600px, 100%)'}>
       <div style={{ fontSize: 15, fontWeight: 600, color: 'var(--ol-ink)', marginBottom: 14 }}>
         {t(isDraft ? 'settings.channels.createTitle' : 'settings.channels.editTitle')}
       </div>
@@ -818,8 +821,8 @@ function ChannelModal({
       <label style={fieldLabel}>{t('settings.channels.providerLabel')}</label>
       <SelectLite
         value={providerType}
-        disabled={changingProvider}
-        onChange={next => void changeProvider(next)}
+        disabled={changingProvider || form.leaving}
+        onChange={next => void form.finish(() => changeProvider(next))}
         options={presets.map(p => ({
           value: p.id,
           label: t(`settings.providers.presets.${p.nameKey}`),
@@ -841,6 +844,7 @@ function ChannelModal({
       />
 
       {/* key 决定：换供应商时整组凭据字段重挂载，读的是新厂商对应的槽位。 */}
+      <fieldset disabled={changingProvider || form.leaving} style={{ border: 0, padding: 0, margin: 0, minWidth: 0 }}>
       {!changingProvider && <ChannelCredentialFields
         key={`${channel.id}:${providerType}`}
         kind={kind}
@@ -850,6 +854,7 @@ function ChannelModal({
         onTested={() => void onChanged()}
         onUserMutation={onUserMutation}
       />}
+      </fieldset>
 
       {isLocalEngine && (
         <div style={{ fontSize: 11.5, color: 'var(--ol-ink-4)', lineHeight: 1.6, marginTop: 6 }}>
@@ -863,7 +868,7 @@ function ChannelModal({
             <span style={{ fontSize: 12, color: 'var(--ol-warn)' }}>
               {t('settings.channels.deleteConfirm')}
             </span>
-            <button onClick={() => void remove()} style={dangerBtn}>
+            <button onClick={() => void form.finish(remove)} disabled={form.leaving} style={dangerBtn}>
               {t('settings.channels.confirmDelete')}
             </button>
             <button onClick={() => setConfirmDelete(false)} style={ghostBtn}>{t('common.cancel')}</button>
@@ -873,9 +878,10 @@ function ChannelModal({
             {t('settings.channels.delete')}
           </button>
         )}
-        <button onClick={onClose} style={primaryBtn}>{t('common.close')}</button>
+        <button onClick={() => void form.finish(onClose)} disabled={form.leaving} style={primaryBtn}>{t('common.close')}</button>
       </div>
     </Modal>
+    </ProviderFormContext.Provider>
   );
 }
 
diff --git a/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts b/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
index f6192f9e..f36e915c 100644
--- a/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
+++ b/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
@@ -24,7 +24,11 @@ assert(opencode?.defaultRequestFormat === 'chat_completions'
   && opencode.defaultEndpoint === 'https://opencode.ai/zen/v1'
   && opencode.defaultModel === 'deepseek-v4-flash', 'OpenCode browser preset must retain Core defaults');
 assert(presets.find(p => p.id === 'custom_messages')?.defaultRequestFormat === 'messages', 'Picker must retain Core protocol defaults');
-for (const preset of presets) assert(preset.supportedRequestFormats?.length === 3, 'All compatibility presets allow switching');
+for (const preset of presets) {
+  assert(preset.supportedRequestFormats?.length === (preset.defaultRequestFormat ? 3 : 0), 'Picker must retain Core protocol capabilities');
+}
+assert(presets.find(p => p.id === 'gemini')?.defaultRequestFormat == null, 'Native Gemini must not gain compatibility formats');
+assert(presets.find(p => p.id === 'codex_oauth')?.staticModels?.length, 'OAuth static models must be available without an API key');
 
 const first = await createChannel('llm', 'opencode', 'first');
 const second = await createChannel('llm', 'custom', 'second');
diff --git a/openless-all/app/src/pages/settings/LlmProtocolFields.tsx b/openless-all/app/src/pages/settings/LlmProtocolFields.tsx
index ed3b99dd..f238fe6a 100644
--- a/openless-all/app/src/pages/settings/LlmProtocolFields.tsx
+++ b/openless-all/app/src/pages/settings/LlmProtocolFields.tsx
@@ -1,10 +1,11 @@
-import { useEffect, useRef, useState } from 'react';
+import { useContext, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { SelectLite } from '../../components/ui/SelectLite';
 import { readCredential, setCredential } from '../../lib/ipc';
 import type { LlmRequestFormat } from '../../lib/ipc/providers';
 import { emitSaved } from '../../lib/savedEvent';
 import { SettingRow, inputStyle } from './shared';
+import { ProviderFormContext } from './ProviderForm';
 
 const accounts = ['ark.request_format', 'ark.messages_thinking', 'ark.max_tokens', 'ark.thinking_budget'] as const;
 type Account = typeof accounts[number];
@@ -35,6 +36,7 @@ export function LlmProtocolFields({ channelId, defaultFormat, formats, onUserMut
   onSaved?: (changedAccounts: readonly Account[]) => void;
 }) {
   const { t } = useTranslation();
+  const form = useContext(ProviderFormContext);
   const [values, setValues] = useState<ProtocolValues>(emptyValues);
   const [saved, setSaved] = useState<ProtocolValues>(emptyValues);
   const [loaded, setLoaded] = useState(false);
@@ -42,6 +44,8 @@ export function LlmProtocolFields({ channelId, defaultFormat, formats, onUserMut
   const [error, setError] = useState<'read' | 'save' | null>(null);
   const mounted = useRef(true);
   const writing = useRef(false);
+  const pendingWrite = useRef<Promise<boolean>>(Promise.resolve(true));
+  const flushRef = useRef<() => Promise<boolean>>(() => Promise.resolve(true));
   const dirty = accounts.some(account => values[account] !== saved[account]);
   const validation = protocolValidationError(values, defaultFormat);
 
@@ -60,11 +64,14 @@ export function LlmProtocolFields({ channelId, defaultFormat, formats, onUserMut
   useEffect(() => {
     onBlockedChange('protocol', !loaded || saving || dirty || error !== null || validation !== null);
   }, [loaded, saving, dirty, error, validation, onBlockedChange]);
+  useEffect(() => form?.register('protocol', () => flushRef.current()), [form?.register]);
 
-  const save = async (next: ProtocolValues) => {
-    if (!loaded || writing.current || protocolValidationError(next, defaultFormat)) return;
+  const save = (next: ProtocolValues): Promise<boolean> => {
+    if (writing.current) return pendingWrite.current;
+    if (!loaded || protocolValidationError(next, defaultFormat)) return Promise.resolve(false);
     writing.current = true;
     setSaving(true); setError(null);
+    pendingWrite.current = (async () => {
     try {
       const changedAccounts = accounts.filter(account => next[account] !== saved[account]);
       for (const account of changedAccounts) {
@@ -75,15 +82,21 @@ export function LlmProtocolFields({ channelId, defaultFormat, formats, onUserMut
         emitSaved('saved', t('common.saved'));
         onSaved?.(changedAccounts);
       }
+      return true;
     } catch {
       if (mounted.current) { setError('save'); emitSaved('failed', t('common.operationFailed')); }
+      return false;
     } finally {
       writing.current = false;
       if (mounted.current) setSaving(false);
     }
+    })();
+    return pendingWrite.current;
   };
+  flushRef.current = () => writing.current ? pendingWrite.current : dirty ? save(values) : Promise.resolve(true);
 
   const change = (account: Account, value: string, immediate = false) => {
+    if (!loaded || writing.current || form?.leaving) return;
     onUserMutation();
     const next = { ...values, [account]: value };
     setValues(next);
@@ -91,7 +104,7 @@ export function LlmProtocolFields({ channelId, defaultFormat, formats, onUserMut
   };
   const format = values['ark.request_format'] || defaultFormat;
   const mode = values['ark.messages_thinking'] || 'adaptive';
-  const disabled = !loaded || saving;
+  const disabled = !loaded || saving || form?.leaving;
   const numberField = (account: Account, label: string, placeholder: string) => (
     <SettingRow label={label}>
       <input type="number" min={account === 'ark.thinking_budget' ? 1024 : 1} step={1}
diff --git a/openless-all/app/src/pages/settings/ProviderForm.tsx b/openless-all/app/src/pages/settings/ProviderForm.tsx
new file mode 100644
index 00000000..80a2a899
--- /dev/null
+++ b/openless-all/app/src/pages/settings/ProviderForm.tsx
@@ -0,0 +1,46 @@
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from 'react';
+
+export const ProviderLeaveContext = createContext<((id: string, flush: () => Promise<boolean>) => () => void) | null>(null);
+
+/** 同一表单的写入在关闭/切换前收敛；版本只含计数，不携带凭据内容。 */
+export function useProviderForm() {
+  const parent = useContext(ProviderLeaveContext);
+  const id = useId();
+  const version = useRef(0);
+  const [revision, setRevision] = useState(0);
+  const [blocked, setBlocked] = useState<Record<string, boolean>>({});
+  const blockers = useRef<Record<string, boolean>>({});
+  const flushers = useRef(new Map<string, () => Promise<boolean>>());
+  const busy = useRef(false);
+  const [leaving, setLeaving] = useState(false);
+  const invalidate = useCallback((account = '') => {
+    if (!['ark.model_id', 'asr.model', 'omni.model'].includes(account)) version.current += 1;
+    setRevision(value => value + 1);
+  }, []);
+  const track = useCallback((account: string, next: boolean) => {
+    blockers.current[account] = next;
+    setBlocked(previous => previous[account] === next ? previous : { ...previous, [account]: next });
+  }, []);
+  const register = useCallback((account: string, flush: () => Promise<boolean>) => {
+    flushers.current.set(account, flush);
+    return () => { flushers.current.delete(account); delete blockers.current[account];
+      setBlocked(previous => { const next = { ...previous }; delete next[account]; return next; }); };
+  }, []);
+  const finish = useCallback(async (action: () => void | Promise<void>) => {
+    if (busy.current) return false;
+    busy.current = true;
+    setLeaving(true);
+    invalidate();
+    try {
+      const results = await Promise.all([...flushers.current.values()].map(flush => flush()));
+      if (!results.every(Boolean) || Object.entries(blockers.current).some(([account, blocked]) => blocked && !flushers.current.has(account))) return false;
+      await action();
+      return true;
+    } finally { busy.current = false; setLeaving(false); }
+  }, [invalidate]);
+  useEffect(() => parent?.(id, () => finish(() => undefined)), [parent, id, finish]);
+  return useMemo(() => ({ version, revision, blocked, leaving, invalidate, track, register, finish }),
+    [revision, blocked, leaving, invalidate, track, register, finish]);
+}
+
+export const ProviderFormContext = createContext<ReturnType<typeof useProviderForm> | null>(null);
diff --git a/openless-all/app/src/pages/settings/ProvidersSection.test.ts b/openless-all/app/src/pages/settings/ProvidersSection.test.ts
index 88b964f1..a89e8a41 100644
--- a/openless-all/app/src/pages/settings/ProvidersSection.test.ts
+++ b/openless-all/app/src/pages/settings/ProvidersSection.test.ts
@@ -1,4 +1,4 @@
-import { LLM_LABELS, prioritizeOrcaRouterModels } from './ProvidersSection';
+import { LLM_LABELS } from './ProvidersSection';
 import { ASR_LABELS } from './shared';
 import { presetsFor } from './ChannelList';
 import { filterOrcaRouterModels } from '../../lib/ipc/asr-credentials';
@@ -41,22 +41,6 @@ if (coreAsr.length !== 1 || coreAsr[0].authRequirement !== 'endpoint_model_optio
   throw new Error('Core provider descriptor must replace the browser fallback in the channel picker');
 }
 
-const prioritizedOrcaRouterModels = prioritizeOrcaRouterModels([
-  'openai/gpt-5-mini',
-  'orcarouter/fusion-mini',
-  'anthropic/claude-haiku-4.5',
-  'orcarouter/fusion-flash',
-]);
-
-if (prioritizedOrcaRouterModels.join(',') !== [
-  'orcarouter/fusion-flash',
-  'orcarouter/fusion-mini',
-  'anthropic/claude-haiku-4.5',
-  'openai/gpt-5-mini',
-].join(',')) {
-  throw new Error(`unexpected OrcaRouter model ordering: ${prioritizedOrcaRouterModels.join(',')}`);
-}
-
 const protocolCatalog = [
   { id: 'model/chat', supported_endpoint_types: ['openai'] },
   { id: 'model/responses', supported_endpoint_types: ['openai-response'] },
diff --git a/openless-all/app/src/pages/settings/ProvidersSection.tsx b/openless-all/app/src/pages/settings/ProvidersSection.tsx
index a599b73e..514081a5 100644
--- a/openless-all/app/src/pages/settings/ProvidersSection.tsx
+++ b/openless-all/app/src/pages/settings/ProvidersSection.tsx
@@ -1,7 +1,7 @@
 // 服务 → AI 提供商：LLM 润色模型 + ASR 语音转写两张卡片。
 // 自 Settings.tsx 整体迁出，逻辑零改动；i18n key 全部保持 `settings.providers.*`。
 
-import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Icon } from '../../components/Icon';
 import { detectOS } from '../../components/WindowChrome';
@@ -15,6 +15,9 @@ import {
   validateProviderCredentials,
   type ProviderDescriptor,
 } from '../../lib/ipc';
+import { ModelCatalog } from './modelCatalog';
+import { CredentialDraft } from './credentialDraft';
+import { ProviderFormContext, useProviderForm } from './ProviderForm';
 import { LlmProtocolFields } from './LlmProtocolFields';
 import { emitSaved } from '../../lib/savedEvent';
 import { useLayoutStack, useConservativeLayout } from '../../lib/useMobileLayout';
@@ -106,6 +109,53 @@ const ASR_DEFAULT_RESOURCE_ID = 'volc.seedasr.sauc.duration';
 /** 模型预设下拉里的「自定义模型…」哨兵值：选中即切回输入框手输。 */
 const CUSTOM_MODEL_OPTION_VALUE = '__custom_model__';
 
+function useRegisteredCredentialDraft(
+  account: string,
+  provider?: string,
+  onUserMutation?: () => void,
+  onBlockedChange?: (account: string, blocked: boolean) => void,
+  enabled = true,
+) {
+  const { t } = useTranslation();
+  const form = useContext(ProviderFormContext);
+  const draft = useMemo(() => new CredentialDraft(
+    () => readCredential(account, provider), value => setCredential(account, value, provider),
+  ), [account, provider]);
+  const state = useSyncExternalStore(draft.subscribe, draft.snapshot, draft.snapshot);
+  const blocked = !state.loaded || state.dirty || state.status === 'saving'
+    || state.status === 'readError' || state.status === 'saveError';
+
+  useEffect(() => {
+    if (!enabled) return;
+    void draft.load();
+    return () => draft.dispose();
+  }, [draft, enabled]);
+  useEffect(() => {
+    if (!enabled) return;
+    form?.track(account, blocked);
+    onBlockedChange?.(account, blocked);
+  }, [account, blocked, enabled, form?.track, onBlockedChange]);
+  useEffect(() => enabled ? form?.register(account, draft.flush) : undefined,
+    [account, draft, enabled, form?.register]);
+  useEffect(() => {
+    if (!enabled) return;
+    if (state.status === 'saving') emitSaved('saving', t('common.saving'));
+    if (state.status === 'saved') emitSaved('saved', t('common.saved'));
+    if (state.status === 'saveError') emitSaved('failed', t('common.operationFailed'));
+  }, [enabled, state.status, t]);
+
+  const edit = (value: string) => {
+    if (!enabled || !state.loaded) return false;
+    form?.track(account, true);
+    form?.invalidate(account);
+    onUserMutation?.();
+    draft.edit(value);
+    return true;
+  };
+
+  return { ...state, draft, edit, disabled: !enabled || !state.loaded || form?.leaving };
+}
+
 /**
  * 一张渠道卡片的凭据字段区（编辑弹窗的主体）。
  *
@@ -135,30 +185,24 @@ export function ChannelCredentialFields({
   const baseLayoutStack = useLayoutStack();
   const conservative = useConservativeLayout();
   const layoutStack = conservative || baseLayoutStack;
-  const [llmModelRevision, setLlmModelRevision] = useState(0);
+  const form = useContext(ProviderFormContext);
   const [configRevision, setConfigRevision] = useState(0);
-  const [orcarouterCatalogRevision, setOrcarouterCatalogRevision] = useState(0);
+
   const [blockedFields, setBlockedFields] = useState<Record<string, boolean>>({});
   const trackField = useCallback((account: string, blocked: boolean) => {
+    form?.track(account, blocked);
     setBlockedFields(previous => previous[account] === blocked ? previous : { ...previous, [account]: blocked });
-  }, []);
+  }, [form?.track]);
   const onLlmMutation = () => { onUserMutation?.(); setConfigRevision(value => value + 1); };
 
-  const [asrModelRevision, setAsrModelRevision] = useState(0);
+
   const unifiedBailian = providerType === 'bailian';
   const [bailianModel, setBailianModel] = useState('');
-  const [volcengineAuthMode, setVolcengineAuthMode] = useState<'app_id_token' | 'api_key'>('app_id_token');
-
-  useEffect(() => {
-    if (providerType === 'volcengine') {
-      readCredential('volcengine.auth_mode', channelId)
-        .then(v => {
-          if (v === 'api_key') setVolcengineAuthMode('api_key');
-          else setVolcengineAuthMode('app_id_token');
-        })
-        .catch(() => setVolcengineAuthMode('app_id_token'));
-    }
-  }, [providerType, channelId]);
+  const volcengineAuth = useRegisteredCredentialDraft(
+    'volcengine.auth_mode', channelId, onUserMutation, undefined,
+    descriptor?.authRequirement === 'volcengine',
+  );
+  const volcengineAuthMode = volcengineAuth.value === 'api_key' ? 'api_key' : 'app_id_token';
 
   useEffect(() => {
     if (!unifiedBailian) setBailianModel('');
@@ -191,13 +235,8 @@ export function ChannelCredentialFields({
       <>
         {!!descriptor.supportedRequestFormats?.length && descriptor.defaultRequestFormat && (
           <LlmProtocolFields channelId={channelId} defaultFormat={descriptor.defaultRequestFormat}
-            formats={descriptor.supportedRequestFormats} onUserMutation={onLlmMutation}
-            onBlockedChange={trackField} onSaved={changedAccounts => {
-              if (providerType === 'orcarouter' && changedAccounts.includes('ark.request_format')) {
-                setOrcarouterCatalogRevision(value => value + 1);
-              }
-              onTested?.();
-            }} />
+            formats={descriptor.supportedRequestFormats} onUserMutation={() => { form?.invalidate(); onLlmMutation(); }}
+            onBlockedChange={trackField} onSaved={() => onTested?.()} />
         )}
         {codexOAuthSelected ? (
           <div style={{ fontSize: 11.5, color: 'var(--ol-ink-4)', lineHeight: 1.6, margin: '2px 0 10px' }}>
@@ -234,28 +273,13 @@ export function ChannelCredentialFields({
             )}
           </>
         )}
-        {providerType === 'orcarouter' ? (
-          <CatalogModelField key={`${channelId}:catalog:${orcarouterCatalogRevision}`} kind="llm" provider={channelId}
-            baseUrl={defaultEndpoint ?? ''} defaultModel={defaultModel ?? ''}
-            onUserMutation={onLlmMutation} onBlockedChange={trackField}
-            trailing={<LlmThinkingToggle enabled={prefs?.llmThinkingEnabled ?? false} onToggle={onLlmThinkingToggle} />} />
-        ) : (
-        <CredentialField key={`${channelId}:model:${llmModelRevision}`} label={t('settings.providers.modelLabel')}
-          account="ark.model_id" provider={channelId}
-          placeholder={defaultModel || 'model-name'} mono
-          defaultValue={defaultModel || undefined}
+        <ModelField kind="llm" providerType={providerType} provider={channelId}
+          staticModels={descriptor.staticModels} defaultValue={defaultModel || undefined}
           onUserMutation={onLlmMutation} onBlockedChange={trackField}
-          trailing={(
-            <LlmThinkingToggle
-              enabled={prefs?.llmThinkingEnabled ?? false}
-              onToggle={onLlmThinkingToggle}
-            />
-          )}
-        />
-        )}
-        <ProviderTools key={configRevision} disabled={Object.values(blockedFields).some(Boolean) || (!!descriptor.supportedRequestFormats?.length && blockedFields.protocol === undefined)} kind="llm" modelAccount="ark.model_id" provider={channelId}
-          onModelSelected={() => setLlmModelRevision(v => v + 1)} onTested={onTested}
-          onUserMutation={onUserMutation} showFetchModels={providerType !== 'orcarouter'} />
+          trailing={<LlmThinkingToggle enabled={prefs?.llmThinkingEnabled ?? false} onToggle={onLlmThinkingToggle} />} />
+        <ProviderTools key={`${configRevision}:${form?.revision}`} disabled={Object.values(blockedFields).some(Boolean) || (!!descriptor.supportedRequestFormats?.length && blockedFields.protocol === undefined)} kind="llm" provider={channelId}
+          onTested={onTested}
+          onUserMutation={onUserMutation} />
       </>
     );
   }
@@ -269,20 +293,13 @@ export function ChannelCredentialFields({
         <SettingRow label={t('settings.providers.volcengineAuthModeLabel')}>
           <SelectLite
             value={volcengineAuthMode}
-            onChange={async (v) => {
-              onUserMutation?.();
-              const mode = v as 'app_id_token' | 'api_key';
-              const prev = volcengineAuthMode;
-              setVolcengineAuthMode(mode);
-              try {
-                await setCredential('volcengine.auth_mode', mode, channelId);
-              } catch (error) {
-                // 写入失败必须回滚 UI 并提示：否则模式看着已切换、重启后却静默回退，
-                // 配合独立 API Key 槽会造成「Key 存在但模式不对」的混乱。
-                console.error('[settings] failed to save volcengine auth mode', error);
-                setVolcengineAuthMode(prev);
-                emitSaved('failed', t('common.operationFailed'));
-              }
+            disabled={volcengineAuth.disabled}
+            onChange={v => {
+              const save = async () => {
+                if (volcengineAuth.edit(v)) await volcengineAuth.draft.flush();
+              };
+              if (form) void form.finish(save);
+              else void save();
             }}
             options={[
               { value: 'app_id_token', label: t('settings.providers.volcengineAuthModeAppIdToken') },
@@ -291,6 +308,12 @@ export function ChannelCredentialFields({
             ariaLabel={t('settings.providers.volcengineAuthModeLabel')}
             style={{ ...inputStyle, width: '100%', maxWidth: layoutStack ? '100%' : 260 }}
           />
+          {volcengineAuth.status === 'readError' && (
+            <span style={{ fontSize: 11, color: 'var(--ol-warn)' }}>{t('settings.providers.readFailed')}</span>
+          )}
+          {volcengineAuth.status === 'saveError' && (
+            <button onClick={() => void volcengineAuth.draft.flush()} style={miniBtnStyle}>{t('common.retry')}</button>
+          )}
         </SettingRow>
         {/* 两种模式使用各自独立的凭据槽位：旧版 Access Token（volcengine.access_key）
             与方舟 API Key（volcengine.api_key）互不预填，切换模式不会残留混淆。 */}
@@ -318,8 +341,8 @@ export function ChannelCredentialFields({
             ? t('settings.providers.volcengineApiKeyNote')
             : t('settings.providers.volcengineMappingNote')}
         </div>
-        <ProviderTools kind="asr" modelAccount="asr.model" provider={channelId}
-          showFetchModels={false} onModelSelected={() => setAsrModelRevision(v => v + 1)} onTested={onTested}
+        <ProviderTools key={form?.revision} disabled={Object.values(form?.blocked ?? {}).some(Boolean)} kind="asr" provider={channelId}
+          onTested={onTested}
           onUserMutation={onUserMutation} />
       </>
     );
@@ -335,8 +358,8 @@ export function ChannelCredentialFields({
         <div style={{ marginTop: 2, fontSize: 11.5, color: 'var(--ol-ink-4)', lineHeight: 1.6 }}>
           {t('settings.providers.xfyunNote')}
         </div>
-        <ProviderTools kind="asr" modelAccount="asr.model" provider={channelId}
-          showFetchModels={false} onModelSelected={() => setAsrModelRevision(v => v + 1)} onTested={onTested}
+        <ProviderTools key={form?.revision} disabled={Object.values(form?.blocked ?? {}).some(Boolean)} kind="asr" provider={channelId}
+          onTested={onTested}
           onUserMutation={onUserMutation} />
       </>
     );
@@ -352,29 +375,6 @@ export function ChannelCredentialFields({
     );
   }
 
-  if (providerType === 'orcarouter') {
-    return (
-      <>
-        <CredentialField key={`${channelId}:api_key`} label={t('settings.providers.apiKeyLabel')}
-          account="asr.api_key" provider={channelId} mono mask onUserMutation={onUserMutation} />
-        <CredentialField key={`${channelId}:endpoint`} label={t('settings.providers.baseUrlLabel')}
-          account="asr.endpoint" provider={channelId}
-          placeholder={defaultEndpoint ?? undefined} defaultValue={defaultEndpoint ?? undefined}
-          onUserMutation={onUserMutation} />
-        <CatalogModelField
-          kind="asr"
-          provider={channelId}
-          baseUrl={defaultEndpoint ?? ''}
-          defaultModel={defaultModel ?? ''}
-          onUserMutation={onUserMutation}
-        />
-        <ProviderTools kind="asr" modelAccount="asr.model" provider={channelId}
-          onModelSelected={() => setAsrModelRevision(v => v + 1)} onTested={onTested}
-          onUserMutation={onUserMutation} showFetchModels={false} />
-      </>
-    );
-  }
-
   return (
     <>
       <CredentialField key={`${channelId}:api_key`} label={t('settings.providers.apiKeyLabel')}
@@ -384,17 +384,12 @@ export function ChannelCredentialFields({
         account="asr.endpoint" provider={channelId}
         placeholder={defaultEndpoint || 'https://your-endpoint/v1'}
         defaultValue={defaultEndpoint || undefined} onUserMutation={onUserMutation} />
-      <CredentialField key={`${channelId}:model:${asrModelRevision}`} label={t('settings.providers.modelLabel')}
-        account="asr.model" provider={channelId}
-        placeholder={defaultModel || 'model-name'}
-        defaultValue={defaultModel || undefined}
+      <ModelField kind="asr" providerType={providerType} provider={channelId}
+        staticModels={descriptor.staticModels} defaultValue={defaultModel || undefined}
         onUserMutation={onUserMutation}
-        onValueChange={unifiedBailian ? setBailianModel : undefined}
-        options={descriptor?.staticModels?.length
-          ? descriptor.staticModels.map(model => ({ value: model, label: model }))
-          : undefined} />
+        onValueChange={unifiedBailian ? setBailianModel : undefined} />
       {unifiedBailian && (
-        <BailianProtocolHint key={`${channelId}:proto:${asrModelRevision}`} currentModel={bailianModel} />
+        <BailianProtocolHint currentModel={bailianModel} />
       )}
       {unifiedBailian && bailianModelSupportsVocabulary(bailianModel) && (
         <>
@@ -422,12 +417,12 @@ export function ChannelCredentialFields({
           {t('settings.providers.zenmuxVocabularyNote')}
         </div>
       )}
-      {/* 统一百炼「拉取模型」只写 model，不覆盖用户选择的区域或工作空间 endpoint。 */}
-      <ProviderTools kind="asr" modelAccount="asr.model" provider={channelId}
-        onModelSelected={() => setAsrModelRevision(v => v + 1)} onTested={onTested}
+      {/* 连通性测试与目录拉取分开，不回填模型或 endpoint。 */}
+      <ProviderTools key={form?.revision} disabled={Object.values(form?.blocked ?? {}).some(Boolean)} kind="asr" provider={channelId}
+        onTested={onTested}
         onUserMutation={onUserMutation} />
       {(providerType === 'openai-compatible' || providerType === 'zenmux') && (
-        <AsrAdvancedOptions provider={channelId} onUserMutation={onUserMutation} />
+        <AsrAdvancedOptions provider={channelId} providerType={providerType} onUserMutation={onUserMutation} />
       )}
     </>
   );
@@ -438,41 +433,25 @@ export function ChannelCredentialFields({
 // zenmux 暴露 enable_itn（数字归一化）开关，verbose_json / 分片对其无意义。
 function AsrAdvancedOptions({
   provider,
+  providerType,
   onUserMutation,
 }: {
   provider: string;
+  providerType: 'openai-compatible' | 'zenmux';
   onUserMutation?: () => void;
 }) {
   const { t } = useTranslation();
-  const [verboseJson, setVerboseJson] = useState(false);
+  const advanced = useRegisteredCredentialDraft('asr.advanced_config', provider, onUserMutation);
+  const config = useMemo(() => parseAdvancedAsrConfig(advanced.loaded ? advanced.value : null),
+    [advanced.loaded, advanced.value]);
   const [chunkDraft, setChunkDraft] = useState('');
-  const [enableItn, setEnableItn] = useState(true);
-  const [status, setStatus] = useState<'idle' | 'saving' | 'error'>('idle');
-  const [error, setError] = useState('');
+  const chunkInitialized = useRef(false);
 
   useEffect(() => {
-    let cancelled = false;
-    setStatus('idle');
-    setError('');
-    void (async () => {
-      try {
-        const raw = await readCredential('asr.advanced_config', provider);
-        if (cancelled) return;
-        const config = parseAdvancedAsrConfig(raw);
-        setVerboseJson(config.verboseJson);
-        setChunkDraft(config.chunkDurationMs ? String(config.chunkDurationMs) : '');
-        setEnableItn(config.enableItn);
-      } catch (err) {
-        if (!cancelled) {
-          setStatus('error');
-          setError(err instanceof Error ? err.message : String(err));
-        }
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [provider]);
+    if (!advanced.loaded || (chunkInitialized.current && advanced.status !== 'saved')) return;
+    chunkInitialized.current = true;
+    setChunkDraft(config.chunkDurationMs ? String(config.chunkDurationMs) : '');
+  }, [advanced.loaded, advanced.status, config.chunkDurationMs]);
 
   const parseChunkDraft = (draft: string): number | null => {
     const value = Number(draft);
@@ -480,32 +459,20 @@ function AsrAdvancedOptions({
     return Math.floor(value);
   };
 
-  const save = async (partial: {
+  const edit = (partial: {
     verboseJson?: boolean
     chunkDurationMs?: number | null
     enableItn?: boolean
   }) => {
-    onUserMutation?.();
-    setStatus('saving');
-    setError('');
     const next: AdvancedAsrConfig = {
-      verboseJson: partial.verboseJson ?? verboseJson,
+      verboseJson: partial.verboseJson ?? config.verboseJson,
       chunkDurationMs:
         partial.chunkDurationMs !== undefined
           ? partial.chunkDurationMs
           : parseChunkDraft(chunkDraft),
-      enableItn: partial.enableItn ?? enableItn,
+      enableItn: partial.enableItn ?? config.enableItn,
     };
-    try {
-      await setCredential('asr.advanced_config', serializeAdvancedAsrConfig(next), provider);
-      setVerboseJson(next.verboseJson);
-      setChunkDraft(next.chunkDurationMs ? String(next.chunkDurationMs) : '');
-      setEnableItn(next.enableItn);
-      setStatus('idle');
-    } catch (err) {
-      setStatus('error');
-      setError(err instanceof Error ? err.message : String(err));
-    }
+    return advanced.edit(serializeAdvancedAsrConfig(next));
   };
 
   return (
@@ -521,12 +488,15 @@ function AsrAdvancedOptions({
       >
         {t('settings.providers.asrAdvancedNote')}
       </div>
-      {provider === 'zenmux' ? (
+      <fieldset disabled={advanced.disabled} style={{ border: 0, padding: 0, margin: 0, minWidth: 0 }}>
+      {providerType === 'zenmux' ? (
         <SettingRow
           label={t('settings.providers.asrAdvancedEnableItnLabel')}
           desc={t('settings.providers.asrAdvancedEnableItnHint')}
         >
-          <Toggle on={enableItn} onToggle={(next) => void save({ enableItn: next })} />
+          <Toggle on={config.enableItn} onToggle={(next) => {
+            if (edit({ enableItn: next })) void advanced.draft.flush();
+          }} />
         </SettingRow>
       ) : (
         <>
@@ -534,7 +504,9 @@ function AsrAdvancedOptions({
             label={t('settings.providers.asrAdvancedVerboseJsonLabel')}
             desc={t('settings.providers.asrAdvancedVerboseJsonHint')}
           >
-            <Toggle on={verboseJson} onToggle={(next) => void save({ verboseJson: next })} />
+            <Toggle on={config.verboseJson} onToggle={(next) => {
+              if (edit({ verboseJson: next })) void advanced.draft.flush();
+            }} />
           </SettingRow>
           <SettingRow
             label={t('settings.providers.asrAdvancedChunkLabel')}
@@ -546,9 +518,13 @@ function AsrAdvancedOptions({
               step={1000}
               value={chunkDraft}
               placeholder="0"
-              disabled={status === 'saving'}
-              onChange={(e) => setChunkDraft(e.target.value)}
-              onBlur={() => void save({ chunkDurationMs: parseChunkDraft(chunkDraft) })}
+              disabled={advanced.disabled}
+              onChange={(event) => {
+                const value = event.target.value;
+                setChunkDraft(value);
+                if (edit({ chunkDurationMs: parseChunkDraft(value) })) advanced.draft.schedule();
+              }}
+              onBlur={() => void advanced.draft.flush()}
               onKeyDown={(e) => {
                 if (e.key === 'Enter') (e.target as HTMLInputElement).blur();
               }}
@@ -557,11 +533,15 @@ function AsrAdvancedOptions({
           </SettingRow>
         </>
       )}
-      {status === 'error' && (
+      </fieldset>
+      {advanced.status === 'readError' && (
         <div style={{ fontSize: 11, color: 'var(--ol-warn)', lineHeight: 1.4 }}>
-          {t('common.operationFailed')}: {error}
+          {t('settings.providers.readFailed')}
         </div>
       )}
+      {advanced.status === 'saveError' && (
+        <button onClick={() => void advanced.draft.flush()} style={miniBtnStyle}>{t('common.retry')}</button>
+      )}
     </>
   );
 }
@@ -593,22 +573,10 @@ function bailianModelSupportsVocabulary(model: string): boolean {
 }
 
 // 模型框下的一行协议提示,解决「三种模型看不出区别」——告诉用户当前模型是实时还是
-// 录音文件、行为差异如何。随 asrModelRevision(拉取/选择模型时)与挂载时重读 asr.model。
+// 录音文件、行为差异如何。只使用当前渠道模型字段的值。
 function BailianProtocolHint({ currentModel }: { currentModel: string }) {
   const { t } = useTranslation();
-  const [model, setModel] = useState('');
-
-  useEffect(() => {
-    let cancelled = false;
-    readCredential('asr.model')
-      .then(v => { if (!cancelled) setModel(v || 'fun-asr-realtime'); })
-      .catch(() => { /* 读失败按默认实时提示 */ });
-    return () => { cancelled = true; };
-  }, []);
-
-  useEffect(() => {
-    setModel(currentModel || 'fun-asr-realtime');
-  }, [currentModel]);
+  const model = currentModel || 'fun-asr-realtime';
 
   const protocol = bailianModelProtocol(model);
   const hint = protocol === 'realtime'
@@ -626,187 +594,43 @@ function BailianProtocolHint({ currentModel }: { currentModel: string }) {
 
 type ProviderToolStatus = 'idle' | 'loading' | 'success' | 'empty' | 'error';
 
-/**
- * OrcaRouter exposes a large, changing catalog. Keep its own router models at
- * the top, then sort the remaining vendor/model ids for predictable scanning.
- */
-export function prioritizeOrcaRouterModels(models: string[]): string[] {
-  return [...models].sort((left, right) => {
-    const leftOwn = left.startsWith('orcarouter/');
-    const rightOwn = right.startsWith('orcarouter/');
-    if (leftOwn !== rightOwn) return leftOwn ? -1 : 1;
-    return left.localeCompare(right);
-  });
-}
-
-function CatalogModelField({
-  kind,
-  provider,
-  baseUrl,
-  defaultModel,
-  trailing,
-  onUserMutation,
-  onBlockedChange,
-}: {
-  kind: 'llm' | 'asr';
-  provider: string;
-  baseUrl: string;
-  defaultModel: string;
-  trailing?: ReactNode;
-  onUserMutation?: () => void;
-  onBlockedChange?: (account: string, blocked: boolean) => void;
+/** 目录只提供候选；CredentialField 是选择与手填唯一的写入入口。 */
+function ModelField({ kind, providerType, staticModels = [], ...field }: Omit<CredentialFieldProps, 'account' | 'label' | 'options'> & {
+  kind: 'llm' | 'asr' | 'omni'; providerType: string; staticModels?: string[];
 }) {
   const { t } = useTranslation();
-  const baseLayoutStack = useLayoutStack();
-  const conservative = useConservativeLayout();
-  const layoutStack = conservative || baseLayoutStack;
-  const [models, setModels] = useState<string[]>([]);
-  const [selectedModel, setSelectedModel] = useState('');
-  const [status, setStatus] = useState<ProviderToolStatus>('loading');
-  const [message, setMessage] = useState(t('settings.providers.loadingModels'));
-  const requestRef = useRef(0);
-  const endpointAccount = kind === 'llm' ? 'ark.endpoint' : 'asr.endpoint';
-  const modelAccount = kind === 'llm' ? 'ark.model_id' : 'asr.model';
-
-  useEffect(() => {
-    onBlockedChange?.(modelAccount, status !== 'success');
-  }, [modelAccount, status, onBlockedChange]);
-
-  const loadModels = async (initialize: boolean) => {
-    const requestId = ++requestRef.current;
-    setStatus('loading');
-    setMessage(t('settings.providers.loadingModels'));
-    try {
-      // A newly created/migrated channel may not have received its preset yet.
-      // Fill only an empty endpoint here; an explicit endpoint edit remains
-      // respected, matching the behavior of the other named providers.
-      if (initialize) {
-        const endpoint = await readCredential(endpointAccount, provider);
-        if (!endpoint?.trim()) {
-          await setCredential(endpointAccount, baseUrl, provider);
-        }
-      }
-      const [savedModel, result] = await Promise.all([
-        readCredential(modelAccount, provider),
-        listProviderModels(kind, provider, 'orcarouter'),
-      ]);
-      if (requestId !== requestRef.current) return;
-      const nextModels = prioritizeOrcaRouterModels(result.models);
-      setModels(nextModels);
-      if (nextModels.length === 0) {
-        setSelectedModel('');
-        setStatus('empty');
-        setMessage(t('settings.providers.modelsEmpty'));
-        return;
-      }
-
-      const current = savedModel?.trim() ?? '';
-      const nextModel = nextModels.includes(current)
-        ? current
-        : nextModels.includes(defaultModel)
-          ? defaultModel
-          : nextModels[0];
-      if (nextModel !== current) {
-        await setCredential(modelAccount, nextModel, provider);
-      }
-      if (requestId !== requestRef.current) return;
-      setSelectedModel(nextModel);
-      setStatus('success');
-      setMessage(t('settings.providers.modelsLoaded', { count: nextModels.length }));
-    } catch (error) {
-      if (requestId !== requestRef.current) return;
-      setModels([]);
-      setStatus('error');
-      setMessage(providerErrorMessage(error, t));
-    }
+  const form = useContext(ProviderFormContext);
+  const loader = useMemo(() => new ModelCatalog(), [kind, field.provider, providerType]);
+  const catalog = useSyncExternalStore(loader.subscribe, loader.snapshot, loader.snapshot);
+  const version = form?.version.current ?? 0;
+  useEffect(() => () => loader.invalidate(), [loader]);
+  const loadModels = async () => {
+    if (form?.leaving || Object.values(form?.blocked ?? {}).some(Boolean)) return;
+    await loader.load(version, () => listProviderModels(kind, field.provider, providerType),
+      () => form?.version.current ?? 0);
   };
-
-  useEffect(() => {
-    void loadModels(true);
-    return () => {
-      requestRef.current += 1;
-    };
-    // The channel id defines the credential scope; changing it must reload the catalog.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [provider]);
-
-  const applyModel = async (model: string) => {
-    onUserMutation?.();
-    setStatus('loading');
-    setMessage(t('common.saving'));
-    try {
-      await setCredential(modelAccount, model, provider);
-      setSelectedModel(model);
-      setStatus('success');
-      setMessage(t('settings.providers.modelSaved', { model }));
-      emitSaved('saved', t('common.saved'));
-    } catch (error) {
-      setStatus('error');
-      setMessage(providerErrorMessage(error, t));
-      emitSaved('failed', t('common.operationFailed'));
-    }
-  };
-
-  return (
-    <SettingRow label={t('settings.providers.modelLabel')}>
-      <div style={{ display: 'flex', flexDirection: 'column', gap: 6, width: '100%', maxWidth: layoutStack ? '100%' : 420 }}>
-        <div style={{ display: 'flex', gap: 6, alignItems: 'center', width: '100%', flexWrap: layoutStack ? 'wrap' : 'nowrap' }}>
-          <SelectLite
-            value={selectedModel}
-            onChange={model => void applyModel(model)}
-            options={models.map(model => ({ value: model, label: model }))}
-            placeholder={status === 'loading'
-              ? t('settings.providers.loadingModels')
-              : t('settings.providers.selectModel')}
-            disabled={status === 'loading' || models.length === 0}
-            searchable
-            searchPlaceholder={t('settings.providers.searchModels')}
-            emptyMessage={t('settings.providers.noMatchingModels')}
-            ariaLabel={t('settings.providers.selectModel')}
-            style={{
-              flex: layoutStack ? '1 1 100%' : 1,
-              width: '100%',
-              minWidth: 0,
-              maxWidth: '100%',
-              fontFamily: 'var(--ol-font-mono)',
-            }}
-          />
-          <button
-            onClick={() => {
-              onUserMutation?.();
-              void loadModels(false);
-            }}
-            title={t('common.refresh')}
-            aria-label={t('common.refresh')}
-            style={iconBtnStyle}
-            disabled={status === 'loading'}
-          >
-            <Icon name="refresh" size={13} />
-          </button>
-          {trailing}
-        </div>
-        <span style={{ fontSize: 11, color: status === 'error' ? 'var(--ol-warn)' : status === 'success' ? 'var(--ol-ok)' : 'var(--ol-ink-4)', lineHeight: 1.4 }}>
-          {message}
-        </span>
-        <span style={{ fontSize: 11, color: 'var(--ol-ink-4)', lineHeight: 1.4 }}>
-          {t(kind === 'asr'
-            ? 'settings.providers.orcarouterAsrCatalogHint'
-            : 'settings.providers.orcarouterCatalogHint')}
-        </span>
-      </div>
-    </SettingRow>
-  );
+  const active = catalog?.version === version ? catalog : null;
+  const models = [...new Set([...staticModels, ...(active?.models ?? [])])].sort((a, b) => a.localeCompare(b));
+  const message = !active ? '' : active.status === 'loading' ? t('settings.providers.loadingModels')
+    : active.status === 'error' ? providerErrorMessage(active.error, t)
+    : active.models.length ? t('settings.providers.modelsLoaded', { count: active.models.length }) : t('settings.providers.modelsEmpty');
+  return <CredentialField {...field} label={t('settings.providers.modelLabel')}
+    account={kind === 'llm' ? 'ark.model_id' : `${kind}.model`} mono
+    placeholder={field.defaultValue || 'model-name'} options={models.map(value => ({ value, label: value }))}
+    below={<>
+      <button onClick={() => void loadModels()} style={miniBtnStyle}
+        disabled={form?.leaving || Object.values(form?.blocked ?? {}).some(Boolean)}>{t('settings.providers.fetchModels')}</button>
+      {message && <span role="status" style={{ fontSize: 11, overflowWrap: 'anywhere', color: active?.status === 'error' ? 'var(--ol-warn)' : 'var(--ol-ink-4)' }}>{message}</span>}
+    </>} />;
 }
 
-function ProviderTools({ kind, modelAccount, provider, onModelSelected, onTested, onUserMutation, showFetchModels = true, disabled = false }: { disabled?: boolean; kind: 'llm' | 'asr' | 'omni'; modelAccount: string; provider?: string; onModelSelected: () => void; onTested?: () => void; onUserMutation?: () => void; showFetchModels?: boolean }) {
+function ProviderTools({ kind, provider, onTested, onUserMutation, disabled = false }: { disabled?: boolean; kind: 'llm' | 'asr' | 'omni'; provider?: string; onTested?: () => void; onUserMutation?: () => void }) {
   const { t } = useTranslation();
   const baseLayoutStack = useLayoutStack();
   const conservative = useConservativeLayout();
   const layoutStack = conservative || baseLayoutStack;
   const mounted = useRef(true);
   useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
-  const [models, setModels] = useState<string[]>([]);
-  const [selectedModel, setSelectedModel] = useState('');
   const [status, setStatus] = useState<ProviderToolStatus>('idle');
   const [message, setMessage] = useState('');
 
@@ -832,8 +656,6 @@ function ProviderTools({ kind, modelAccount, provider, onModelSelected, onTested
   const validate = async () => {
     if (disabled) return;
     onUserMutation?.();
-    setModels([]);
-    setSelectedModel('');
     setResult('loading', t('settings.providers.validating'));
     const started = performance.now();
     try {
@@ -861,57 +683,11 @@ function ProviderTools({ kind, modelAccount, provider, onModelSelected, onTested
     }
   };
 
-  const loadModels = async () => {
-    if (disabled) return;
-    onUserMutation?.();
-    setResult('loading', t('settings.providers.loadingModels'));
-    try {
-      const result = await listProviderModels(kind, provider);
-      setModels(result.models);
-      if (result.models.length === 0) {
-        setResult('empty', t('settings.providers.modelsEmpty'));
-      } else {
-        setSelectedModel('');
-        setResult('success', t('settings.providers.modelsLoaded', { count: result.models.length }));
-      }
-    } catch (error) {
-      setModels([]);
-      setResult('error', providerErrorMessage(error, t));
-    }
-  };
-
-  const applyModel = async (model: string) => {
-    onUserMutation?.();
-    setResult('loading', t('common.saving'));
-    try {
-      await setCredential(modelAccount, model, provider);
-      setSelectedModel(model);
-      onModelSelected();
-      setResult('success', t('settings.providers.modelSaved', { model }));
-    } catch (error) {
-      setResult('error', providerErrorMessage(error, t));
-    }
-  };
-
   return (
     <SettingRow label={t('settings.providers.toolsLabel')}>
       <div style={{ display: 'flex', flexDirection: 'column', gap: 8, width: '100%', maxWidth: layoutStack ? '100%' : 420 }}>
         <div style={{ display: 'flex', gap: 6, alignItems: 'center', flexWrap: 'wrap', width: '100%' }}>
           <button onClick={validate} style={miniBtnStyle} disabled={disabled || status === 'loading'}>{t('settings.providers.validate')}</button>
-          {showFetchModels && (
-            <button onClick={loadModels} style={miniBtnStyle} disabled={disabled || status === 'loading'}>{t('settings.providers.fetchModels')}</button>
-          )}
-          {showFetchModels && models.length > 0 && (
-            <SelectLite
-              value={selectedModel}
-              onChange={applyModel}
-              disabled={disabled || status === 'loading'}
-              options={models.map(model => ({ value: model, label: model }))}
-              placeholder={t('settings.providers.selectModel')}
-              ariaLabel={t('settings.providers.selectModel')}
-              style={{ flex: layoutStack ? '1 1 100%' : '1 1 180px', maxWidth: layoutStack ? '100%' : 220, minWidth: 0 }}
-            />
-          )}
         </div>
         {message && (
           <span style={{ fontSize: 11, color: status === 'error' ? 'var(--ol-warn)' : status === 'empty' ? 'var(--ol-ink-4)' : 'var(--ol-ok)', lineHeight: 1.4 }}>
@@ -955,8 +731,6 @@ function providerErrorMessage(error: unknown, t: ReturnType<typeof useTranslatio
   return t('common.operationFailed');
 }
 
-type CredentialFieldStatus = 'idle' | 'saving' | 'saved' | 'readError' | 'saveError' | 'copied' | 'copyError';
-
 interface CredentialFieldProps {
   onBlockedChange?: (account: string, blocked: boolean) => void;
   label: string;
@@ -972,156 +746,36 @@ interface CredentialFieldProps {
   onUserMutation?: () => void;
   /** 提供则渲染为下拉（预设选择）代替输入框；当前值不在预设里时附加为自定义项。 */
   options?: SelectOption[];
+  below?: ReactNode;
 }
 
-function CredentialField({ label, account, provider, placeholder, mono, mask, defaultValue, trailing, onValueChange, onUserMutation, options, onBlockedChange }: CredentialFieldProps) {
+function CredentialField({ label, account, provider, placeholder, mono, mask, defaultValue, trailing, onValueChange, onUserMutation, options, onBlockedChange, below }: CredentialFieldProps) {
   const { t } = useTranslation();
   const baseLayoutStack = useLayoutStack();
   const conservative = useConservativeLayout();
   const layoutStack = conservative || baseLayoutStack;
-  const [value, setValue] = useState('');
+  const credential = useRegisteredCredentialDraft(account, provider, onUserMutation, onBlockedChange);
+  const { draft, value, loaded, status, disabled } = credential;
   const [revealed, setRevealed] = useState(false);
-  const [loaded, setLoaded] = useState(false);
-  const [dirty, setDirty] = useState(false);
-  const [status, setStatus] = useState<CredentialFieldStatus>('idle');
-  // 预设下拉的「自定义模型…」逃生口：选中后切回输入框，保证后端支持的任意模型名都能手输。
   const [customModelMode, setCustomModelMode] = useState(false);
-  useEffect(() => {
-    onBlockedChange?.(account, !loaded || dirty || status === 'saving' || status === 'readError' || status === 'saveError');
-  }, [account, loaded, dirty, status, onBlockedChange]);
+  const composing = useRef(false);
+  useEffect(() => { if (loaded) onValueChange?.(value); }, [loaded, value, onValueChange]);
 
-  const debounceRef = useRef<number | null>(null);
-  const statusRef = useRef<number | null>(null);
-  const mountedRef = useRef(true);
-  const editRevision = useRef(0);
-  const saveQueue = useRef<Promise<void>>(Promise.resolve());
-  const markMutation = () => { editRevision.current += 1; onUserMutation?.(); };
-
-  useEffect(() => {
-    let cancelled = false;
-    setLoaded(false);
-    setDirty(false);
-    setStatus('idle');
-    setValue('');
-    onValueChange?.('');
-    if (debounceRef.current) {
-      clearTimeout(debounceRef.current);
-      debounceRef.current = null;
-    }
-    readCredential(account, provider)
-      .then(v => {
-        if (cancelled) return;
-        setValue(v ?? '');
-        onValueChange?.(v ?? '');
-        setLoaded(true);
-      })
-      .catch(error => {
-        if (cancelled) return;
-        console.error('[settings] failed to read credential', account, error);
-        onValueChange?.('');
-        setLoaded(true);
-        setStatus('readError');
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [account, provider, onValueChange]);
-
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => {
-      mountedRef.current = false;
-      if (debounceRef.current) clearTimeout(debounceRef.current);
-      if (statusRef.current) clearTimeout(statusRef.current);
-    };
-  }, []);
-
-  // 改造：除 readError（持续错误，留在输入旁标识字段不可用）外，所有 saving / saved /
-  //   saveError / copied / copyError 一律发到右上角 SavedToast。原内联文案太挤、跟其它
-  //   页面 toast 风格不统一。
-  const showTemporaryStatus = (next: CredentialFieldStatus) => {
-    if (next === 'saving') {
-      emitSaved('saving', t('common.saving'));
-    } else if (next === 'saved') {
-      emitSaved('saved', t('common.saved'));
-    } else if (next === 'saveError') {
-      emitSaved('failed', t('common.operationFailed'));
-    } else if (next === 'copied') {
-      emitSaved('saved', t('common.copied'));
-    } else if (next === 'copyError') {
-      emitSaved('failed', t('common.operationFailed'));
-    }
-    setStatus(next);
-    if (statusRef.current) clearTimeout(statusRef.current);
-    statusRef.current = window.setTimeout(() => setStatus('idle'), 1600);
+  const change = (next: string, immediate = false) => {
+    if (!credential.edit(next)) return;
+    if (immediate) void draft.flush();
+    else if (!composing.current) draft.schedule();
   };
-
-  const save = async (v: string, force = false) => {
-    if (!loaded || (!dirty && !force)) return;
-    if (!mountedRef.current) return;
-    const revision = editRevision.current;
-    setStatus('saving');
-    emitSaved('saving', t('common.saving'));
-    try {
-      // 按编辑顺序写入，旧请求完成不能把新值标记为已保存。
-      const write = saveQueue.current.catch(() => undefined).then(() => setCredential(account, v, provider));
-      saveQueue.current = write;
-      await write;
-      if (!mountedRef.current || revision !== editRevision.current) return;
-      setDirty(false);
-      showTemporaryStatus('saved');
-    } catch (error) {
-      if (!mountedRef.current || revision !== editRevision.current) return;
-      console.error('[settings] failed to save credential', account, error);
-      showTemporaryStatus('saveError');
-    }
-  };
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    markMutation();
-    const v = e.target.value;
-    setValue(v);
-    onValueChange?.(v);
-    if (!loaded) return;
-    setDirty(true);
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-    debounceRef.current = window.setTimeout(() => save(v, true), 300);
-  };
-
-  const onBlur = () => {
-    if (!loaded || !dirty) return;
-    if (debounceRef.current) {
-      clearTimeout(debounceRef.current);
-      debounceRef.current = null;
-    }
-    void save(value, true);
-  };
-
-  const fillDefault = async () => {
-    if (!loaded || !defaultValue) return;
-    markMutation();
-    setValue(defaultValue);
-    onValueChange?.(defaultValue);
-    setDirty(true);
-    await save(defaultValue, true);
-  };
-
+  const onBlur = () => { if (!composing.current) void draft.flush(); };
   const onCopy = async () => {
     if (!value || !loaded) return;
     try {
-      if (!navigator.clipboard?.writeText) {
-        throw new Error('Clipboard API unavailable');
-      }
       await navigator.clipboard.writeText(value);
-      showTemporaryStatus('copied');
-    } catch (error) {
-      console.error('[settings] failed to copy credential', account, error);
-      showTemporaryStatus('copyError');
-    }
+      emitSaved('saved', t('common.copied'));
+    } catch { emitSaved('failed', t('common.operationFailed')); }
   };
 
   const inputType = mask && !revealed ? 'password' : 'text';
-  const disabled = !loaded;
   const showInsecureEndpointWarning = (account === 'ark.endpoint' || account === 'asr.endpoint' || account === 'omni.endpoint')
     && value.trim().toLowerCase().startsWith('http://');
 
@@ -1129,7 +783,7 @@ function CredentialField({ label, account, provider, placeholder, mono, mask, de
     <SettingRow label={label}>
       <div style={{ display: 'flex', flexDirection: 'column', gap: 5, width: '100%', maxWidth: layoutStack ? '100%' : 420 }}>
         <div style={{ display: 'flex', gap: 6, alignItems: 'center', width: '100%', flexWrap: layoutStack ? 'wrap' : 'nowrap' }}>
-          {options && !customModelMode ? (
+          {!!options?.length && !customModelMode ? (
             <SelectLite
               value={value}
               onChange={(v) => {
@@ -1138,18 +792,16 @@ function CredentialField({ label, account, provider, placeholder, mono, mask, de
                   setCustomModelMode(true);
                   return;
                 }
-                markMutation();
-                setValue(v);
-                onValueChange?.(v);
-                if (!loaded) return;
-                setDirty(true);
-                void save(v, true);
+                change(v, true);
               }}
               options={[
                 ...(value && !options.some(o => o.value === value) ? [{ value, label: value }] : []),
                 ...options,
-                { value: CUSTOM_MODEL_OPTION_VALUE, label: t('settings.providers.customModelLabel', 'Custom model…') },
+                { value: CUSTOM_MODEL_OPTION_VALUE, label: t('settings.providers.customModelLabel'), alwaysVisible: true },
               ]}
+              searchable
+              searchPlaceholder={t('settings.providers.searchModels')}
+              emptyMessage={t('settings.providers.noMatchingModels')}
               placeholder={loaded ? placeholder : t('common.loading')}
               disabled={disabled}
               ariaLabel={label}
@@ -1160,13 +812,16 @@ function CredentialField({ label, account, provider, placeholder, mono, mask, de
               type={inputType}
               value={value}
               placeholder={loaded ? placeholder : t('common.loading')}
-              onChange={handleChange}
+              aria-label={label}
+              onChange={event => { if (options) setCustomModelMode(true); change(event.target.value); }}
+              onCompositionStart={() => { composing.current = true; draft.pause(); }}
+              onCompositionEnd={() => { composing.current = false; draft.schedule(); }}
               onBlur={onBlur}
               disabled={disabled}
               style={{ ...inputStyle, flex: layoutStack ? '1 1 180px' : 1, minWidth: 0, maxWidth: '100%', fontFamily: mono ? 'var(--ol-font-mono)' : 'inherit' }}
             />
           )}
-          {options && customModelMode && (
+          {!!options?.length && customModelMode && (
             <button
               onClick={() => setCustomModelMode(false)}
               title={t('settings.providers.presetListLabel', 'Back to presets')}
@@ -1177,7 +832,7 @@ function CredentialField({ label, account, provider, placeholder, mono, mask, de
             </button>
           )}
           {defaultValue && !value && loaded && (
-            <button onClick={fillDefault} title={t('settings.providers.fillDefault')} style={iconBtnStyle} disabled={!loaded}>
+            <button onClick={() => change(defaultValue, true)} title={t('settings.providers.fillDefault')} style={iconBtnStyle} disabled={!loaded}>
               <Icon name="check" size={13} />
             </button>
           )}
@@ -1215,6 +870,8 @@ function CredentialField({ label, account, provider, placeholder, mono, mask, de
             </span>
           )}
         </div>
+        {below && <div style={{ display: 'flex', gap: 6, alignItems: 'center', flexWrap: 'wrap' }}>{below}</div>}
+        {status === 'saveError' && <button onClick={() => void draft.flush()} style={miniBtnStyle}>{t('common.retry')}</button>}
         {showInsecureEndpointWarning && (
           <span style={{ fontSize: 11, color: 'var(--ol-warn)', lineHeight: 1.45 }}>
             {t('settings.providers.endpointHttpWarning')}
@@ -1262,7 +919,7 @@ export function OmniChannelSection() {
   const [omniProvider, setOmniProvider] = useState('custom');
   const [committedOmniProvider, setCommittedOmniProvider] = useState('custom');
   const omniSwitchSeqRef = useRef(0);
-  const [omniModelRevision, setOmniModelRevision] = useState(0);
+  const form = useProviderForm();
 
   useEffect(() => {
     void listProviderDescriptors('omni')
@@ -1275,15 +932,16 @@ export function OmniChannelSection() {
       nameKey: descriptor.labelKey,
       baseUrl: descriptor.defaultEndpoint ?? '',
       modelPlaceholder: descriptor.defaultModel ?? '',
+      staticModels: descriptor.staticModels,
     })), [descriptors]);
 
   useEffect(() => {
-    if (!prefs) return;
+    if (!prefs || form.leaving) return;
     const knownOmni = omniPresets.find(x => x.id === prefs.activeOmniProvider);
     const omniId = knownOmni ? knownOmni.id : 'custom';
     setOmniProvider(omniId);
     setCommittedOmniProvider(omniId);
-  }, [prefs, omniPresets]);
+  }, [prefs?.activeOmniProvider, omniPresets, form.leaving]);
 
   // 与 LLM 卡同语义：受控下拉立即反馈 + committed 控制 CredentialField remount
   // + seq 守卫防 stale 覆盖，只是凭据落到 omni.* 槽。
@@ -1341,7 +999,7 @@ export function OmniChannelSection() {
   const omniPreset = omniPresets.find(p => p.id === committedOmniProvider);
 
   return (
-    <>
+    <ProviderFormContext.Provider value={form}>
       <div style={{ marginBottom: 12 }}>
         <SettingRow
           label={t('settings.providers.pipelineModeLabel')}
@@ -1352,7 +1010,7 @@ export function OmniChannelSection() {
               {(['traditional', 'multimodal'] as const).map(mode => (
                 <button
                   key={mode}
-                  onClick={() => onPipelineModeChange(mode)}
+                  disabled={form.leaving} onClick={() => void form.finish(() => onPipelineModeChange(mode))}
                   style={{
                     padding: '5px 12px', fontSize: 12, fontWeight: 500, border: 0, borderRadius: 6,
                     fontFamily: 'inherit',
@@ -1382,7 +1040,7 @@ export function OmniChannelSection() {
           <SettingRow label={t('settings.providers.providerLabel')}>
             <SelectLite
               value={omniProvider}
-              onChange={next => onOmniProviderChange(next)}
+              disabled={form.leaving} onChange={next => void form.finish(() => onOmniProviderChange(next))}
               options={omniPresets.map(p => ({
                 value: p.id,
                 label: t(`settings.providers.presets.${p.nameKey}`),
@@ -1391,6 +1049,7 @@ export function OmniChannelSection() {
               style={{ ...inputStyle, width: '100%', maxWidth: layoutStack ? '100%' : 200 }}
             />
           </SettingRow>
+          <fieldset disabled={form.leaving} style={{ border: 0, padding: 0, margin: 0, minWidth: 0 }}>
           <CredentialField
             key={`${committedOmniProvider}:api_key`}
             label={t('settings.providers.apiKeyLabel')}
@@ -1423,21 +1082,13 @@ export function OmniChannelSection() {
               />
             </>
           )}
-          <CredentialField
-            key={`${committedOmniProvider}:model:${omniModelRevision}`}
-            label={t('settings.providers.modelLabel')}
-            account="omni.model"
-            placeholder={omniPreset?.modelPlaceholder || 'model-name'}
-            mono
-          />
-          <ProviderTools
-            key={`omni:${committedOmniProvider}`}
-            kind="omni"
-            modelAccount="omni.model"
-            onModelSelected={() => setOmniModelRevision(v => v + 1)}
-          />
+          <ModelField key={committedOmniProvider} kind="omni" providerType={committedOmniProvider}
+            staticModels={omniPreset?.staticModels} defaultValue={omniPreset?.modelPlaceholder || undefined} />
+          <ProviderTools key={`omni:${committedOmniProvider}:${form.revision}`} kind="omni"
+            disabled={Object.values(form.blocked).some(Boolean) || form.leaving} />
+          </fieldset>
         </Card>
       )}
-    </>
+    </ProviderFormContext.Provider>
   );
 }
diff --git a/openless-all/app/src/pages/settings/credentialDraft.test.ts b/openless-all/app/src/pages/settings/credentialDraft.test.ts
new file mode 100644
index 00000000..4a2c663c
--- /dev/null
+++ b/openless-all/app/src/pages/settings/credentialDraft.test.ts
@@ -0,0 +1,91 @@
+import { CredentialDraft } from './credentialDraft';
+
+function assert(condition: unknown, message: string) { if (!condition) throw new Error(message); }
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+const tick = () => new Promise(resolve => setTimeout(resolve, 0));
+
+async function main() {
+  const writes: string[] = [];
+  const first = deferred<void>();
+  const second = deferred<void>();
+  const draft = new CredentialDraft(async () => 'saved', value => {
+    writes.push(`channel-A:ark.model_id:${value}`);
+    return writes.length === 1 ? first.promise : second.promise;
+  });
+  await draft.load();
+  assert(draft.snapshot().value === 'saved' && writes.length === 0, 'reading must not write');
+  draft.edit('m1');
+  const save1 = draft.flush();
+  assert(draft.flush() === save1, 'blur and close must share the pending save');
+  await tick();
+  draft.edit('m2');
+  const save2 = draft.flush();
+  assert(writes.length === 1, 'm2 must wait for m1');
+  first.reject(new Error('old failure'));
+  await save1;
+  await tick();
+  assert(draft.snapshot().value === 'm2' && draft.snapshot().status === 'saving', 'old failure must not replace new status');
+  assert(writes.join(',') === 'channel-A:ark.model_id:m1,channel-A:ark.model_id:m2', 'writes must capture account and order');
+  second.resolve();
+  assert(await save2, 'new value must save after old failure');
+  assert(!draft.snapshot().dirty && draft.snapshot().value === 'm2', 'only latest save clears dirty');
+
+  const sequence: string[] = [];
+  const closeDraft = new CredentialDraft(async () => '', async value => { sequence.push(value); });
+  await closeDraft.load();
+  closeDraft.edit('debounced'); closeDraft.schedule();
+  closeDraft.edit('selected'); await closeDraft.flush();
+  await new Promise(resolve => setTimeout(resolve, 350));
+  assert(sequence.join(',') === 'selected', 'selection cancels an older debounce');
+  closeDraft.edit('before-switch'); closeDraft.schedule();
+  if (await closeDraft.flush()) sequence.push('new-provider-default');
+  closeDraft.dispose();
+  assert(sequence.slice(-2).join(',') === 'before-switch,new-provider-default', 'switch must follow the pending draft');
+
+  let failed = true;
+  const retry = new CredentialDraft(async () => 'original', async () => { if (failed) throw new Error('save'); });
+  await retry.load(); retry.edit('custom');
+  assert(!await retry.flush() && retry.snapshot().dirty, 'failed write must block close and retain the draft');
+  failed = false;
+  assert(await retry.flush() && !retry.snapshot().dirty, 'same edit must be retryable');
+
+  const authWrite = deferred<void>();
+  const advancedWrite = deferred<void>();
+  let advancedAttempts = 0;
+  const authMode = new CredentialDraft(async () => '', () => authWrite.promise);
+  const advanced = new CredentialDraft(async () => '{}', () => (
+    ++advancedAttempts === 1 ? advancedWrite.promise : Promise.resolve()
+  ));
+  await Promise.all([authMode.load(), advanced.load()]);
+  authMode.edit('api_key');
+  advanced.edit('{"verboseJson":true,"chunkDurationMs":30000,"enableItn":false}');
+  let leaveFinished = false;
+  const leave = Promise.all([authMode.flush(), advanced.flush()])
+    .then(results => results.every(Boolean))
+    .finally(() => { leaveFinished = true; });
+  await tick();
+  assert(!leaveFinished, 'leaving must wait for every registered credential write');
+  authWrite.resolve();
+  advancedWrite.reject(new Error('save'));
+  assert(!await leave, 'one failed credential write must block leaving');
+  assert(authMode.snapshot().value === 'api_key' && !authMode.snapshot().dirty, 'successful auth mode must remain saved');
+  assert(advanced.snapshot().value.includes('30000') && advanced.snapshot().dirty, 'failed advanced config must retain its draft');
+  assert(await advanced.flush() && !advanced.snapshot().dirty, 'advanced config must retry the retained value');
+
+  const oldRead = deferred<string | null>();
+  let reads = 0;
+  const reading = new CredentialDraft(() => ++reads === 1 ? oldRead.promise : Promise.resolve('new'), async () => undefined);
+  const initial = reading.load();
+  reading.edit('too-early');
+  assert(reading.snapshot().value === '', 'reading must disable editing');
+  reading.dispose(); await reading.load(); reading.edit('typed');
+  oldRead.resolve('stale'); await initial;
+  assert(reading.snapshot().value === 'typed', 'old read must not replace a new scope or edit');
+  draft.dispose(); retry.dispose(); authMode.dispose(); advanced.dispose(); reading.dispose();
+}
+void main();
diff --git a/openless-all/app/src/pages/settings/credentialDraft.ts b/openless-all/app/src/pages/settings/credentialDraft.ts
new file mode 100644
index 00000000..65cc21ea
--- /dev/null
+++ b/openless-all/app/src/pages/settings/credentialDraft.ts
@@ -0,0 +1,64 @@
+type Status = 'idle' | 'saving' | 'saved' | 'readError' | 'saveError';
+
+/** 一个凭据槽的草稿和串行写入；调用方在更换作用域前等待 flush。 */
+export class CredentialDraft {
+  private state = { value: '', loaded: false, dirty: false, status: 'idle' as Status };
+  private listeners = new Set<() => void>();
+  private revision = 0;
+  private generation = 0;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private queue: Promise<unknown> = Promise.resolve();
+  private pending: { revision: number; promise: Promise<boolean> } | undefined;
+  constructor(private read: () => Promise<string | null>, private write: (value: string) => Promise<void>) {}
+  snapshot = () => this.state;
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  private update(next: Partial<typeof this.state>) {
+    this.state = { ...this.state, ...next };
+    this.listeners.forEach(listener => listener());
+  }
+  async load() {
+    const generation = ++this.generation;
+    const revision = this.revision;
+    try {
+      const value = await this.read();
+      if (generation === this.generation && revision === this.revision) this.update({ value: value ?? '', loaded: true });
+    } catch {
+      if (generation === this.generation) this.update({ status: 'readError' });
+    }
+  }
+  edit(value: string) {
+    if (!this.state.loaded) return;
+    clearTimeout(this.timer);
+    this.revision += 1;
+    this.update({ value, dirty: true, status: 'idle' });
+  }
+  schedule() {
+    clearTimeout(this.timer);
+    const revision = this.revision;
+    this.timer = setTimeout(() => { if (revision === this.revision) void this.flush(); }, 300);
+  }
+  pause() { clearTimeout(this.timer); }
+  flush = (): Promise<boolean> => {
+    clearTimeout(this.timer);
+    if (!this.state.dirty) return Promise.resolve(true);
+    if (!this.state.loaded) return Promise.resolve(false);
+    const revision = this.revision;
+    if (this.pending?.revision === revision) return this.pending.promise;
+    const generation = this.generation;
+    const value = this.state.value;
+    this.update({ status: 'saving' });
+    const write = this.queue.catch(() => undefined).then(() => this.write(value));
+    this.queue = write;
+    const promise = write.then(() => {
+      if (revision !== this.revision || generation !== this.generation) return false;
+      this.update({ dirty: false, status: 'saved' });
+      return true;
+    }, () => {
+      if (revision === this.revision && generation === this.generation) this.update({ status: 'saveError' });
+      return false;
+    }).finally(() => { if (this.pending?.revision === revision) this.pending = undefined; });
+    this.pending = { revision, promise };
+    return promise;
+  };
+  dispose() { this.generation += 1; clearTimeout(this.timer); }
+}
diff --git a/openless-all/app/src/pages/settings/modelCatalog.test.ts b/openless-all/app/src/pages/settings/modelCatalog.test.ts
new file mode 100644
index 00000000..1df109ae
--- /dev/null
+++ b/openless-all/app/src/pages/settings/modelCatalog.test.ts
@@ -0,0 +1,47 @@
+import { ModelCatalog } from './modelCatalog';
+import { CredentialDraft } from './credentialDraft';
+
+function assert(condition: unknown, message: string) { if (!condition) throw new Error(message); }
+function deferred() {
+  let resolve!: (value: { models: string[] }) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<{ models: string[] }>((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+async function main() {
+  const catalog = new ModelCatalog();
+  let version = 0;
+  const current = () => version;
+  for (const failOld of [false, true]) {
+    const a = deferred(); const b = deferred();
+    const first = catalog.load(version, () => a.promise, current);
+    const second = catalog.load(version, () => b.promise, current);
+    b.resolve({ models: ['new'] }); await second;
+    if (failOld) a.reject(new Error('old authentication error')); else a.resolve({ models: ['old'] });
+    await first;
+    assert(catalog.snapshot()?.models.join() === 'new' && catalog.snapshot()?.status === 'success', 'old response or error must be ignored');
+  }
+  const editing = deferred();
+  const pending = catalog.load(version, () => editing.promise, current);
+  version += 1; // endpoint/key/protocol edit invalidates immediately, before saving.
+  editing.resolve({ models: ['stale-config'] }); await pending;
+  assert(catalog.snapshot()?.version !== version, 'old candidates must not belong to the edited configuration');
+  const unmounted = deferred();
+  const closed = catalog.load(version, () => unmounted.promise, current);
+  catalog.invalidate(); unmounted.reject(new Error('after close')); await closed;
+  assert(catalog.snapshot()?.status === 'loading', 'unmounted error must not publish');
+
+  const writes: string[] = [];
+  const draft = new CredentialDraft(async () => 'missing-from-catalog', async value => { writes.push(value); });
+  await draft.load();
+  const directory = deferred();
+  const fetching = catalog.load(version, () => directory.promise, current);
+  draft.edit('typed-during-request'); await draft.flush();
+  directory.resolve({ models: ['different-model'] }); await fetching;
+  await catalog.load(version, async () => ({ models: [] }), current);
+  await catalog.load(version, async () => { throw new Error('401'); }, current);
+  assert(draft.snapshot().value === 'typed-during-request' && writes.join() === 'typed-during-request', 'success, empty and failure cannot write or clear the model');
+  assert(!draft.snapshot().dirty, 'catalog failure cannot block a saved manual model');
+  draft.dispose();
+}
+void main();
diff --git a/openless-all/app/src/pages/settings/modelCatalog.ts b/openless-all/app/src/pages/settings/modelCatalog.ts
new file mode 100644
index 00000000..3f13e949
--- /dev/null
+++ b/openless-all/app/src/pages/settings/modelCatalog.ts
@@ -0,0 +1,23 @@
+type CatalogState = { version: number; models: string[]; status: 'loading' | 'success' | 'empty' | 'error'; error?: unknown };
+
+/** 目录响应只改变候选；配置版本与请求序号共同决定响应是否有效。 */
+export class ModelCatalog {
+  private state: CatalogState | null = null;
+  private request = 0;
+  private listeners = new Set<() => void>();
+  snapshot = () => this.state;
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  private update(state: CatalogState) { this.state = state; this.listeners.forEach(listener => listener()); }
+  invalidate() { this.request += 1; }
+  async load(version: number, read: () => Promise<{ models: string[] }>, currentVersion: () => number) {
+    const request = ++this.request;
+    const current = () => request === this.request && version === currentVersion();
+    this.update({ version, models: [], status: 'loading' });
+    try {
+      const result = await read();
+      if (current()) this.update({ version, models: result.models, status: result.models.length ? 'success' : 'empty' });
+    } catch (error) {
+      if (current()) this.update({ version, models: [], status: 'error', error });
+    }
+  }
+}

From bf1237c6b1978354bb31d3637fd7ccb85e5a377e Mon Sep 17 00:00:00 2001
From: kevinlin <linjiang1205@qq.com>
Date: Wed, 9 Sep 2026 23:39:11 +0800
Subject: [PATCH 2/4] =?UTF-8?q?feat(provider):=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E8=85=BE=E8=AE=AF=E4=BA=91=E5=AE=9E=E6=97=B6=E8=AF=AD=E9=9F=B3?=
 =?UTF-8?q?=E5=A4=84=E7=90=86=E9=93=BE=E8=B7=AF=20(#1020)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: add Tencent TokenHub and realtime ASR

Rebase onto Core 2.0: Hunyuan realtime ASR and TokenHub polish now live
in openless-core with the shared provider registry, credentials, and
cloud transcription session lifecycle.

* fix: harden Tencent ASR and TokenHub

---------

Co-authored-by: Chris233 <h-chris233@outlook.com>
---
 README.md                                     |    4 +-
 README.zh.md                                  |    4 +-
 .../app/crates/openless-core/src/asr/mod.rs   |    2 +
 .../openless-core/src/asr/tencent_cloud.rs    | 1000 +++++++++++++++++
 .../openless-core/src/cloud_providers.rs      |  127 ++-
 .../crates/openless-core/src/credentials.rs   |    3 +
 .../openless-core/src/credentials_legacy.rs   |   21 +
 .../crates/openless-core/src/llm_protocol.rs  |   28 +-
 .../app/crates/openless-core/src/polish.rs    |  163 ++-
 .../openless-core/src/provider_rules.rs       |  159 ++-
 .../openless-core/src/provider_service.rs     |  109 +-
 .../app/linux-egui/src/credentials.rs         |   18 +-
 openless-all/app/linux-egui/src/main.rs       |   67 ++
 .../app/src-tauri/src/commands/credentials.rs |   11 +-
 .../src-tauri/src/persistence/credentials.rs  |   55 +
 openless-all/app/src/i18n/en.ts               |    7 +
 openless-all/app/src/i18n/ja.ts               |    7 +
 openless-all/app/src/i18n/ko.ts               |    7 +
 openless-all/app/src/i18n/zh-CN.ts            |    7 +
 openless-all/app/src/i18n/zh-TW.ts            |    7 +
 .../lib/ipc/mock-provider-descriptors.json    |    2 +
 openless-all/app/src/lib/ipc/providers.ts     |    1 +
 openless-all/app/src/pages/Overview.tsx       |    1 +
 .../pages/settings/LlmProtocolFields.test.ts  |    4 +
 .../pages/settings/ProvidersSection.test.ts   |    6 +
 .../src/pages/settings/ProvidersSection.tsx   |   30 +-
 .../app/src/pages/settings/shared.tsx         |    1 +
 27 files changed, 1816 insertions(+), 35 deletions(-)
 create mode 100644 openless-all/app/crates/openless-core/src/asr/tencent_cloud.rs

diff --git a/README.md b/README.md
index e9e0bb4c..4011362e 100644
--- a/README.md
+++ b/README.md
@@ -198,9 +198,9 @@ Every item below is one more layer sedimented into a default — a capability yo
 - 🎨 **Style Pack Marketplace** — browse, install, and like community **style packs** from the in-app Marketplace, and publish your own (custom system prompt per pack, switchable by hotkey). Backed by a moderated marketplace backend; uploads are reviewed before they go public.
 - ⚡ **Streaming insertion** — polished text is written to the cursor character by character to reduce perceived latency, with an automatic one-shot-paste fallback. Toggle in Settings → Recording.
 - **Toggle and push-to-talk** recording modes, plus a **MediaPlayPause trigger** so wired-earbud inline controls can start and stop recording. `Esc` cancels at any phase, including polish and insertion.
-- **Cloud ASR**: Volcengine streaming ASR (bigasr), iFlytek realtime ASR (RTASR), Alibaba Cloud Bailian (classic realtime / Qwen3 realtime / Fun-ASR-Flash file transcription), StepFun StepAudio (batch + realtime), Zhipu GLM-ASR, Xiaomi MiMo ASR, OrcaRouter audio-input Gemini, ElevenLabs Scribe, OpenAI-compatible batch transcription (OpenAI Whisper / Groq / SiliconFlow SenseVoice / OpenRouter / ZenMux), and Apple Speech (macOS).
+- **Cloud ASR**: Volcengine streaming ASR (bigasr), Tencent Cloud Hunyuan realtime ASR (Hy-ASR), iFlytek realtime ASR (RTASR), Alibaba Cloud Bailian (classic realtime / Qwen3 realtime / Fun-ASR-Flash file transcription), StepFun StepAudio (batch + realtime), Zhipu GLM-ASR, Xiaomi MiMo ASR, OrcaRouter audio-input Gemini, ElevenLabs Scribe, OpenAI-compatible batch transcription (OpenAI Whisper / Groq / SiliconFlow SenseVoice / OpenRouter / ZenMux), and Apple Speech (macOS).
 - **Local ASR**: bundled Qwen3-ASR (0.6B / 1.7B) via vendored `Open-Less/qwen-asr` (macOS); Windows Foundry Local Whisper and sherpa-onnx (experimental) variants.
-- **Polish providers**: Ark (Volcengine), DeepSeek, OpenAI, Google Gemini, Codex OAuth, SiliconFlow, Atlas Cloud, Xiaomi MiMo, CometAPI, OpenRouter, OrcaRouter, Alibaba Cloud Coding Plan, CodingPlanX, MiniMax, StepFun, and OpenCode Zen — plus any OpenAI-compatible endpoint you bring.
+- **Polish providers**: Ark (Volcengine), DeepSeek, OpenAI, Google Gemini, Codex OAuth, SiliconFlow, Atlas Cloud, Xiaomi MiMo, Tencent Cloud TokenHub, CometAPI, OpenRouter, OrcaRouter, Alibaba Cloud Coding Plan, CodingPlanX, MiniMax, StepFun, and OpenCode Zen — plus any OpenAI-compatible endpoint you bring.
 - **Four output modes**: raw, light polish, structured (**AI-prompt mode**), and formal. Plus a **translation hotkey** that converts speech directly into the configured target language ([#43](../../issues/43)).
 - **Selection-ask QA panel** — a separate hotkey opens a floating panel that runs voice Q&A against the highlighted text in any app ([#118](../../issues/118)).
 - **Main window**: Overview / History / Vocab / Style / Marketplace / Settings. Persistent tray icon, plus a mini status capsule that floats on screen and follows the display you are typing on (multi-monitor).
diff --git a/README.zh.md b/README.zh.md
index 4dde3063..88759401 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -203,9 +203,9 @@ OpenLess 只做一件事:**把语音变成可用的书面文字(尤其是 AI 提
 - 🎨 **风格包市场**——在应用内的 Marketplace 浏览、安装、点赞社区**风格包**,并发布自己的(每个包一套自定义系统提示词,可用快捷键切换)。由经过审核的市场后端支撑;上传内容公开前会经过审核。
 - ⚡ **流式插入**——润色后的文本逐字符写入光标以降低感知延迟,并带有自动的一次性粘贴回退。可在 设置 → 录音 中切换。
 - **切换式与按住说话(push-to-talk)** 两种录音模式,外加 **MediaPlayPause 触发**,让有线耳机的线控也能开始 / 停止录音。`Esc` 可在任意阶段取消,包括润色与插入。
-- **云端 ASR**:Volcengine 流式 ASR(bigasr)、讯飞实时语音转写(RTASR)、阿里云百炼(经典实时 / Qwen3 实时 / Fun-ASR-Flash 录音文件)、阶跃星辰 StepAudio(批式 + 实时)、智谱 GLM-ASR、小米 MiMo ASR、OrcaRouter 音频输入 Gemini、ElevenLabs Scribe、OpenAI 兼容批量转写(OpenAI Whisper / Groq / 硅基流动 SenseVoice / OpenRouter / ZenMux),以及 Apple Speech(macOS)。
+- **云端 ASR**:Volcengine 流式 ASR(bigasr)、腾讯云混元实时 ASR(Hy-ASR)、讯飞实时语音转写(RTASR)、阿里云百炼(经典实时 / Qwen3 实时 / Fun-ASR-Flash 录音文件)、阶跃星辰 StepAudio(批式 + 实时)、智谱 GLM-ASR、小米 MiMo ASR、OrcaRouter 音频输入 Gemini、ElevenLabs Scribe、OpenAI 兼容批量转写(OpenAI Whisper / Groq / 硅基流动 SenseVoice / OpenRouter / ZenMux),以及 Apple Speech(macOS)。
 - **本地 ASR**:通过 vendored 的 `Open-Less/qwen-asr` 内置 Qwen3-ASR(0.6B / 1.7B)(macOS);Windows 上的 Foundry Local Whisper 与 sherpa-onnx(实验性)变体。
-- **润色提供方**:Ark(火山方舟)、DeepSeek、OpenAI、Google Gemini、Codex OAuth、硅基流动、Atlas Cloud、小米 MiMo、CometAPI、OpenRouter、OrcaRouter、阿里云 Coding Plan、CodingPlanX、MiniMax、StepFun、OpenCode Zen,以及你自带的任意 OpenAI 兼容端点。
+- **润色提供方**:Ark(火山方舟)、DeepSeek、OpenAI、Google Gemini、Codex OAuth、硅基流动、Atlas Cloud、小米 MiMo、腾讯云 TokenHub、CometAPI、OpenRouter、OrcaRouter、阿里云 Coding Plan、CodingPlanX、MiniMax、StepFun、OpenCode Zen,以及你自带的任意 OpenAI 兼容端点。
 - **四种输出模式**:原文、轻度润色、结构化(**AI 提示词模式**)、正式。另有一个**翻译快捷键**,将语音直接转换为所配置的目标语言([#43](../../issues/43))。
 - **选区问答面板**——一个独立快捷键打开浮动面板,针对任意应用中被高亮选中的文本进行语音问答([#118](../../issues/118))。
 - **主窗口**:概览 / 历史 / 词典 / 风格 / 市场 / 设置。常驻托盘图标,以及一个浮于屏幕、并跟随你正在输入的显示器的迷你状态胶囊(多显示器)。
diff --git a/openless-all/app/crates/openless-core/src/asr/mod.rs b/openless-all/app/crates/openless-core/src/asr/mod.rs
index b016e1b1..a8177bfe 100644
--- a/openless-all/app/crates/openless-core/src/asr/mod.rs
+++ b/openless-all/app/crates/openless-core/src/asr/mod.rs
@@ -8,6 +8,7 @@ pub mod mimo;
 pub mod pcm;
 pub mod qwen_realtime;
 pub mod stepfun_realtime;
+pub mod tencent_cloud;
 pub mod volcengine;
 pub mod wav;
 pub mod whisper;
@@ -20,6 +21,7 @@ pub use elevenlabs::ElevenLabsBatchASR;
 pub use mimo::MimoBatchASR;
 pub use qwen_realtime::{Qwen3RealtimeASR, Qwen3RealtimeCredentials};
 pub use stepfun_realtime::{StepfunRealtimeASR, StepfunRealtimeCredentials};
+pub use tencent_cloud::{TencentCloudCredentials, TencentCloudStreamingASR};
 pub use volcengine::{VolcengineCredentials, VolcengineStreamingASR};
 pub use whisper::WhisperBatchASR;
 pub use xfyun::{XfyunCredentials, XfyunStreamingASR};
diff --git a/openless-all/app/crates/openless-core/src/asr/tencent_cloud.rs b/openless-all/app/crates/openless-core/src/asr/tencent_cloud.rs
new file mode 100644
index 00000000..4832843d
--- /dev/null
+++ b/openless-all/app/crates/openless-core/src/asr/tencent_cloud.rs
@@ -0,0 +1,1000 @@
+//! 腾讯云实时语音识别 WebSocket 客户端。
+//!
+//! 官方文档：https://cloud.tencent.com/document/api/1093/48982
+//!
+//! 协议要点：
+//! - 端点：`wss://asr.cloud.tencent.com/asr/v2/<appid>`；
+//! - 鉴权：查询参数按字典序拼接后，以 SecretKey 做 HMAC-SHA1，再 Base64；
+//! - 音频：16 kHz / 16-bit / 单声道 PCM，每 200ms 发送 6400 bytes；
+//! - 收尾：发送文本消息 `{"type":"end"}`，等待 `final=1`；
+//! - 默认模型：`Hy-ASR-3.0-preview`（腾讯云当前最新混元 ASR Preview）。
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use base64::Engine;
+use futures_util::{SinkExt, StreamExt};
+use hmac::{Hmac, Mac};
+use parking_lot::Mutex as ParkingMutex;
+use serde_json::Value;
+use sha1::Sha1;
+use tokio::net::TcpStream;
+use tokio::sync::{mpsc, oneshot, Mutex as AsyncMutex};
+use tokio_tungstenite::tungstenite::client::IntoClientRequest;
+use tokio_tungstenite::tungstenite::Message;
+use tokio_tungstenite::{connect_async, MaybeTlsStream, WebSocketStream};
+use uuid::Uuid;
+
+use crate::config::{TaskSpawner, TokioTaskSpawner};
+use crate::ports::{TextStreamChunk, TextStreamSink};
+
+use super::{AudioConsumer, RawTranscript};
+
+pub const PROVIDER_ID: &str = "tencent-cloud";
+pub const DEFAULT_ENDPOINT: &str = "wss://asr.cloud.tencent.com/asr/v2";
+pub const DEFAULT_MODEL: &str = "Hy-ASR-3.0-preview";
+pub const TARGET_AUDIO_CHUNK_BYTES: usize = 6_400;
+
+const BYTES_PER_MS: u64 = 32;
+const MAX_AUDIO_SEND_RATE: u64 = 2;
+const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
+const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(5);
+const FRAME_SEND_TIMEOUT: Duration = Duration::from_secs(5);
+const FINAL_RESULT_TIMEOUT: Duration = Duration::from_secs(15);
+
+type WsStream = WebSocketStream<MaybeTlsStream<TcpStream>>;
+type WsSink = futures_util::stream::SplitSink<WsStream, Message>;
+type SharedWriter = Arc<AsyncMutex<Option<WsSink>>>;
+
+enum SendItem {
+    Audio(Vec<u8>),
+    End(oneshot::Sender<Result<(), TencentCloudASRError>>),
+}
+
+#[derive(Clone, Debug)]
+pub struct TencentCloudCredentials {
+    pub app_id: String,
+    pub secret_id: String,
+    pub secret_key: String,
+    pub model: String,
+}
+
+impl TencentCloudCredentials {
+    pub fn auth_ok(&self) -> bool {
+        !self.app_id.trim().is_empty()
+            && !self.secret_id.trim().is_empty()
+            && !self.secret_key.trim().is_empty()
+    }
+
+    fn resolved_model(&self) -> &str {
+        let model = self.model.trim();
+        if model.is_empty() {
+            DEFAULT_MODEL
+        } else {
+            model
+        }
+    }
+}
+
+#[derive(Debug, Clone, thiserror::Error)]
+pub enum TencentCloudASRError {
+    #[error("credentials missing")]
+    CredentialsMissing,
+    #[error("connection failed")]
+    ConnectionFailed,
+    #[error("credentials rejected or service unavailable ({0})")]
+    AuthRejected(i64),
+    #[error("account unavailable ({0})")]
+    AccountUnavailable(i64),
+    #[error("rate limited")]
+    RateLimited,
+    #[error("service unavailable ({0})")]
+    ServiceUnavailable(i64),
+    #[error("request failed ({0})")]
+    TaskFailed(i64),
+    #[error("no final result")]
+    NoFinalResult,
+    #[error("final result timed out")]
+    FinalResultTimeout,
+}
+
+#[derive(Default)]
+struct SyncState {
+    pending_audio: Vec<u8>,
+    bytes_sent: u64,
+    started: bool,
+    finished: bool,
+    final_tx: Option<oneshot::Sender<Result<RawTranscript, TencentCloudASRError>>>,
+    final_segments: BTreeMap<i64, String>,
+    partial_segments: BTreeMap<i64, String>,
+    last_result_text: String,
+}
+
+pub struct TencentCloudStreamingASR {
+    credentials: TencentCloudCredentials,
+    endpoint: String,
+    task_spawner: Arc<dyn TaskSpawner>,
+    state: ParkingMutex<SyncState>,
+    writer: SharedWriter,
+    final_rx: ParkingMutex<Option<oneshot::Receiver<Result<RawTranscript, TencentCloudASRError>>>>,
+    handshake_tx: ParkingMutex<Option<oneshot::Sender<Result<(), TencentCloudASRError>>>>,
+    send_tx: ParkingMutex<Option<mpsc::UnboundedSender<SendItem>>>,
+    partial_sink: ParkingMutex<Option<Arc<dyn TextStreamSink>>>,
+}
+
+impl TencentCloudStreamingASR {
+    pub fn new(credentials: TencentCloudCredentials) -> Self {
+        Self::with_task_spawner(credentials, Arc::new(TokioTaskSpawner))
+    }
+
+    pub fn with_task_spawner(
+        credentials: TencentCloudCredentials,
+        task_spawner: Arc<dyn TaskSpawner>,
+    ) -> Self {
+        Self::with_endpoint(credentials, task_spawner, DEFAULT_ENDPOINT.to_string())
+    }
+
+    fn with_endpoint(
+        credentials: TencentCloudCredentials,
+        task_spawner: Arc<dyn TaskSpawner>,
+        endpoint: String,
+    ) -> Self {
+        Self {
+            credentials,
+            endpoint,
+            task_spawner,
+            state: ParkingMutex::new(SyncState::default()),
+            writer: Arc::new(AsyncMutex::new(None)),
+            final_rx: ParkingMutex::new(None),
+            handshake_tx: ParkingMutex::new(None),
+            send_tx: ParkingMutex::new(None),
+            partial_sink: ParkingMutex::new(None),
+        }
+    }
+
+    pub fn set_partial_sink(&self, sink: Arc<dyn TextStreamSink>) {
+        *self.partial_sink.lock() = Some(sink);
+    }
+
+    pub fn connect_url(&self) -> String {
+        connect_url_at(
+            &self.endpoint,
+            &self.credentials,
+            chrono::Utc::now().timestamp(),
+            random_nonce(),
+            Uuid::new_v4().to_string(),
+        )
+    }
+
+    pub async fn open_session(self: &Arc<Self>) -> Result<(), TencentCloudASRError> {
+        if !self.credentials.auth_ok() {
+            return Err(TencentCloudASRError::CredentialsMissing);
+        }
+
+        let request = self
+            .connect_url()
+            .into_client_request()
+            .map_err(|_| TencentCloudASRError::ConnectionFailed)?;
+        let (ws, _) = tokio::time::timeout(CONNECT_TIMEOUT, connect_async(request))
+            .await
+            .map_err(|_| TencentCloudASRError::ConnectionFailed)?
+            .map_err(|_| TencentCloudASRError::ConnectionFailed)?;
+        let (write, read) = ws.split();
+        *self.writer.lock().await = Some(write);
+
+        let (final_tx, final_rx) = oneshot::channel();
+        let (send_tx, mut send_rx) = mpsc::unbounded_channel::<SendItem>();
+        let (handshake_tx, handshake_rx) = oneshot::channel();
+        {
+            let mut state = self.state.lock();
+            *state = SyncState::default();
+            state.final_tx = Some(final_tx);
+        }
+        *self.final_rx.lock() = Some(final_rx);
+        *self.send_tx.lock() = Some(send_tx);
+        *self.handshake_tx.lock() = Some(handshake_tx);
+
+        let writer = Arc::clone(&self.writer);
+        let weak_self = Arc::downgrade(self);
+        let task_spawner = Arc::clone(&self.task_spawner);
+        task_spawner.spawn(Box::pin(async move {
+            let mut next_audio_send_at = None;
+            while let Some(item) = send_rx.recv().await {
+                let (result, done) = match item {
+                    SendItem::Audio(chunk) => {
+                        if let Some(send_at) = next_audio_send_at {
+                            tokio::time::sleep_until(send_at).await;
+                        }
+                        let interval_ms =
+                            (chunk.len() as u64 / BYTES_PER_MS / MAX_AUDIO_SEND_RATE).max(1);
+                        let result = send_binary(&writer, chunk).await;
+                        next_audio_send_at =
+                            Some(tokio::time::Instant::now() + Duration::from_millis(interval_ms));
+                        (result, None)
+                    }
+                    SendItem::End(done) => {
+                        (send_text(&writer, r#"{"type":"end"}"#).await, Some(done))
+                    }
+                };
+                if let Err(error) = &result {
+                    log::error!("[tencent-cloud-asr] websocket send failed");
+                    if let Some(this) = weak_self.upgrade() {
+                        this.finish_error(error.clone());
+                    }
+                }
+                if let Some(done) = done {
+                    let _ = done.send(result.clone());
+                }
+                if result.is_err() {
+                    break;
+                }
+            }
+        }));
+
+        let weak_self = Arc::downgrade(self);
+        let task_spawner = Arc::clone(&self.task_spawner);
+        task_spawner.spawn(Box::pin(async move {
+            let mut read = read;
+            while let Some(message) = read.next().await {
+                let Some(this) = weak_self.upgrade() else {
+                    break;
+                };
+                match message {
+                    Ok(Message::Text(text)) => {
+                        if !this.handle_text_message(&text) {
+                            break;
+                        }
+                    }
+                    Ok(Message::Close(_)) => {
+                        this.finish_on_close();
+                        break;
+                    }
+                    Ok(_) => {}
+                    Err(_) => {
+                        log::error!("[tencent-cloud-asr] receive loop failed");
+                        this.finish_with_partial_or_error(TencentCloudASRError::ConnectionFailed);
+                        break;
+                    }
+                }
+            }
+        }));
+
+        match tokio::time::timeout(HANDSHAKE_TIMEOUT, handshake_rx).await {
+            Ok(Ok(Ok(()))) => Ok(()),
+            Ok(Ok(Err(error))) => {
+                self.cancel();
+                Err(error)
+            }
+            Ok(Err(_)) => {
+                self.cancel();
+                Err(TencentCloudASRError::ConnectionFailed)
+            }
+            Err(_) => {
+                self.cancel();
+                Err(TencentCloudASRError::ConnectionFailed)
+            }
+        }
+    }
+
+    pub async fn send_last_frame(&self) -> Result<(), TencentCloudASRError> {
+        self.flush_pending_audio();
+        let (done_tx, done_rx) = oneshot::channel();
+        let sender = self
+            .send_tx
+            .lock()
+            .as_ref()
+            .cloned()
+            .ok_or(TencentCloudASRError::ConnectionFailed)?;
+        sender
+            .send(SendItem::End(done_tx))
+            .map_err(|_| TencentCloudASRError::ConnectionFailed)?;
+        done_rx
+            .await
+            .map_err(|_| TencentCloudASRError::ConnectionFailed)?
+    }
+
+    pub async fn await_final_result(&self) -> Result<RawTranscript, TencentCloudASRError> {
+        self.await_final_result_with_timeout(FINAL_RESULT_TIMEOUT)
+            .await
+    }
+
+    pub async fn await_final_result_with_timeout(
+        &self,
+        timeout: Duration,
+    ) -> Result<RawTranscript, TencentCloudASRError> {
+        let Some(receiver) = self.final_rx.lock().take() else {
+            return Err(TencentCloudASRError::NoFinalResult);
+        };
+        match tokio::time::timeout(timeout, receiver).await {
+            Ok(Ok(result)) => result,
+            Ok(Err(_)) => Err(TencentCloudASRError::NoFinalResult),
+            Err(_) => {
+                log::error!(
+                    "[tencent-cloud-asr] final result timed out after {} ms",
+                    timeout.as_millis()
+                );
+                self.cancel();
+                Err(TencentCloudASRError::FinalResultTimeout)
+            }
+        }
+    }
+
+    pub fn cancel(&self) {
+        self.state.lock().pending_audio.clear();
+        *self.handshake_tx.lock() = None;
+        *self.send_tx.lock() = None;
+        let writer = Arc::clone(&self.writer);
+        self.task_spawner.spawn(Box::pin(async move {
+            let mut guard = writer.lock().await;
+            if let Some(mut ws) = guard.take() {
+                let _ = ws.close().await;
+            }
+        }));
+        self.signal_error(TencentCloudASRError::NoFinalResult);
+    }
+
+    fn flush_pending_audio(&self) {
+        let leftover = {
+            let mut state = self.state.lock();
+            if state.pending_audio.is_empty() {
+                return;
+            }
+            let leftover = std::mem::take(&mut state.pending_audio);
+            state.bytes_sent += leftover.len() as u64;
+            leftover
+        };
+        self.enqueue_audio(leftover);
+    }
+
+    fn enqueue_audio(&self, chunk: Vec<u8>) {
+        let Some(sender) = self.send_tx.lock().as_ref().cloned() else {
+            return;
+        };
+        if sender.send(SendItem::Audio(chunk)).is_err() {
+            self.signal_error(TencentCloudASRError::ConnectionFailed);
+        }
+    }
+
+    fn handle_text_message(&self, text: &str) -> bool {
+        let value: Value = match serde_json::from_str(text) {
+            Ok(value) => value,
+            Err(error) => {
+                log::warn!("[tencent-cloud-asr] invalid json event: {error}");
+                return true;
+            }
+        };
+        let code = value.get("code").and_then(Value::as_i64).unwrap_or(-1);
+        if code != 0 {
+            let error = classify_server_error(code);
+            if let Some(sender) = self.handshake_tx.lock().take() {
+                let _ = sender.send(Err(error.clone()));
+            }
+            self.finish_error(error);
+            return false;
+        }
+
+        self.mark_started();
+        if let Some(result) = value.get("result") {
+            self.record_result(result);
+        }
+        if value.get("final").and_then(Value::as_i64) == Some(1) {
+            self.finish_success();
+            return false;
+        }
+        true
+    }
+
+    fn mark_started(&self) {
+        let mut state = self.state.lock();
+        if !state.started {
+            state.started = true;
+        }
+        drop(state);
+        if let Some(sender) = self.handshake_tx.lock().take() {
+            let _ = sender.send(Ok(()));
+        }
+    }
+
+    fn record_result(&self, result: &Value) {
+        let Some(text) = result.get("voice_text_str").and_then(Value::as_str) else {
+            return;
+        };
+        let text = text.trim();
+        if text.is_empty() {
+            return;
+        }
+        let index = result.get("index").and_then(Value::as_i64).unwrap_or(0);
+        let slice_type = result
+            .get("slice_type")
+            .and_then(Value::as_i64)
+            .unwrap_or(1);
+        let mut state = self.state.lock();
+        state.last_result_text = text.to_string();
+        let mut delta = None;
+        if slice_type == 2 {
+            state.final_segments.insert(index, text.to_string());
+            state.partial_segments.remove(&index);
+        } else {
+            let previous = state
+                .partial_segments
+                .get(&index)
+                .map(String::as_str)
+                .unwrap_or("");
+            delta = text
+                .strip_prefix(previous)
+                .filter(|suffix| !suffix.is_empty())
+                .map(str::to_string);
+            state.partial_segments.insert(index, text.to_string());
+        }
+        drop(state);
+        if let Some(delta) = delta {
+            if let Some(sink) = self.partial_sink.lock().clone() {
+                let _ = sink.publish(TextStreamChunk {
+                    text: delta,
+                    offset: 0,
+                });
+            }
+        }
+    }
+
+    fn finish_on_close(&self) {
+        if let Some(sender) = self.handshake_tx.lock().take() {
+            let _ = sender.send(Err(TencentCloudASRError::ConnectionFailed));
+            return;
+        }
+        self.finish_with_partial_or_error(TencentCloudASRError::NoFinalResult);
+    }
+
+    fn finish_with_partial_or_error(&self, error: TencentCloudASRError) {
+        let has_text = {
+            let state = self.state.lock();
+            !state.last_result_text.trim().is_empty()
+                || !state.final_segments.is_empty()
+                || !state.partial_segments.is_empty()
+        };
+        if has_text {
+            self.finish_success();
+        } else {
+            self.finish_error(error);
+        }
+    }
+
+    fn finish_success(&self) {
+        let (sender, text, duration_ms) = {
+            let mut state = self.state.lock();
+            if state.finished {
+                return;
+            }
+            state.finished = true;
+            state.pending_audio.clear();
+            let mut segments = state.final_segments.clone();
+            for (index, text) in &state.partial_segments {
+                segments.entry(*index).or_insert_with(|| text.clone());
+            }
+            let text = if segments.is_empty() {
+                state.last_result_text.clone()
+            } else {
+                super::mimo::join_transcript_chunks(
+                    &segments.into_values().collect::<Vec<String>>(),
+                )
+            };
+            (state.final_tx.take(), text, state.bytes_sent / BYTES_PER_MS)
+        };
+        *self.send_tx.lock() = None;
+        if let Some(sender) = sender {
+            let _ = sender.send(Ok(RawTranscript { text, duration_ms }));
+        }
+        self.close_writer();
+    }
+
+    fn signal_error(&self, error: TencentCloudASRError) {
+        let sender = {
+            let mut state = self.state.lock();
+            if state.finished {
+                return;
+            }
+            state.finished = true;
+            state.final_tx.take()
+        };
+        *self.send_tx.lock() = None;
+        if let Some(sender) = sender {
+            let _ = sender.send(Err(error));
+        }
+    }
+
+    fn finish_error(&self, error: TencentCloudASRError) {
+        if let Some(sender) = self.handshake_tx.lock().take() {
+            let _ = sender.send(Err(error.clone()));
+        }
+        self.signal_error(error);
+        self.close_writer();
+    }
+
+    fn close_writer(&self) {
+        let writer = Arc::clone(&self.writer);
+        self.task_spawner.spawn(Box::pin(async move {
+            let mut guard = writer.lock().await;
+            if let Some(mut ws) = guard.take() {
+                let _ = ws.close().await;
+            }
+        }));
+    }
+}
+
+impl AudioConsumer for TencentCloudStreamingASR {
+    fn consume_pcm_chunk(&self, pcm: &[u8]) {
+        let chunks = {
+            let mut state = self.state.lock();
+            if !state.started || state.finished {
+                return;
+            }
+            state.pending_audio.extend_from_slice(pcm);
+            let mut chunks = Vec::new();
+            while state.pending_audio.len() >= TARGET_AUDIO_CHUNK_BYTES {
+                let chunk = state
+                    .pending_audio
+                    .drain(..TARGET_AUDIO_CHUNK_BYTES)
+                    .collect::<Vec<u8>>();
+                state.bytes_sent += chunk.len() as u64;
+                chunks.push(chunk);
+            }
+            chunks
+        };
+        for chunk in chunks {
+            self.enqueue_audio(chunk);
+        }
+    }
+}
+
+async fn send_binary(writer: &SharedWriter, data: Vec<u8>) -> Result<(), TencentCloudASRError> {
+    let mut guard = writer.lock().await;
+    let Some(ws) = guard.as_mut() else {
+        return Err(TencentCloudASRError::ConnectionFailed);
+    };
+    tokio::time::timeout(FRAME_SEND_TIMEOUT, ws.send(Message::Binary(data)))
+        .await
+        .map_err(|_| TencentCloudASRError::ConnectionFailed)?
+        .map_err(|_| TencentCloudASRError::ConnectionFailed)
+}
+
+async fn send_text(writer: &SharedWriter, data: &str) -> Result<(), TencentCloudASRError> {
+    let mut guard = writer.lock().await;
+    let Some(ws) = guard.as_mut() else {
+        return Err(TencentCloudASRError::ConnectionFailed);
+    };
+    tokio::time::timeout(FRAME_SEND_TIMEOUT, ws.send(Message::Text(data.to_string())))
+        .await
+        .map_err(|_| TencentCloudASRError::ConnectionFailed)?
+        .map_err(|_| TencentCloudASRError::ConnectionFailed)
+}
+
+fn connect_url_at(
+    base_endpoint: &str,
+    credentials: &TencentCloudCredentials,
+    timestamp: i64,
+    nonce: u32,
+    voice_id: String,
+) -> String {
+    let endpoint = format!(
+        "{}/{}",
+        base_endpoint.trim_end_matches('/'),
+        credentials.app_id.trim()
+    );
+    let parsed = url::Url::parse(&endpoint).expect("static Tencent Cloud endpoint parses");
+    let host_and_path = format!(
+        "{}{}",
+        parsed.host_str().expect("Tencent Cloud endpoint has host"),
+        parsed.path()
+    );
+    let params = BTreeMap::from([
+        (
+            "engine_model_type".to_string(),
+            credentials.resolved_model().to_string(),
+        ),
+        ("expired".to_string(), (timestamp + 86_400).to_string()),
+        ("filter_dirty".to_string(), "0".to_string()),
+        ("filter_empty_result".to_string(), "1".to_string()),
+        ("filter_modal".to_string(), "1".to_string()),
+        ("filter_punc".to_string(), "0".to_string()),
+        ("needvad".to_string(), "1".to_string()),
+        ("nonce".to_string(), nonce.to_string()),
+        (
+            "secretid".to_string(),
+            credentials.secret_id.trim().to_string(),
+        ),
+        ("timestamp".to_string(), timestamp.to_string()),
+        ("voice_format".to_string(), "1".to_string()),
+        ("voice_id".to_string(), voice_id),
+    ]);
+    let query = query_string(&params);
+    let signing_text = format!("{host_and_path}?{query}");
+    let signature = compute_signature(&signing_text, &credentials.secret_key);
+    format!("{endpoint}?{query}&signature={}", url_encode(&signature))
+}
+
+fn query_string(params: &BTreeMap<String, String>) -> String {
+    params
+        .iter()
+        .map(|(key, value)| format!("{key}={value}"))
+        .collect::<Vec<String>>()
+        .join("&")
+}
+
+fn url_encode(value: &str) -> String {
+    url::form_urlencoded::byte_serialize(value.as_bytes()).collect()
+}
+
+pub fn compute_signature(signing_text: &str, secret_key: &str) -> String {
+    let mut mac = Hmac::<Sha1>::new_from_slice(secret_key.trim().as_bytes())
+        .expect("HMAC accepts any key length");
+    mac.update(signing_text.as_bytes());
+    base64::engine::general_purpose::STANDARD.encode(mac.finalize().into_bytes())
+}
+
+fn random_nonce() -> u32 {
+    let bytes = Uuid::new_v4().into_bytes();
+    u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) % 1_000_000_000 + 1
+}
+
+fn classify_server_error(code: i64) -> TencentCloudASRError {
+    match code {
+        4002 | 4003 => TencentCloudASRError::AuthRejected(code),
+        4004 | 4005 => TencentCloudASRError::AccountUnavailable(code),
+        4006 => TencentCloudASRError::RateLimited,
+        4009 => TencentCloudASRError::ConnectionFailed,
+        5000..=5002 => TencentCloudASRError::ServiceUnavailable(code),
+        _ => TencentCloudASRError::TaskFailed(code),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    struct DelayedFirstSpawner {
+        spawned: AtomicUsize,
+        release: Arc<tokio::sync::Semaphore>,
+    }
+
+    impl TaskSpawner for DelayedFirstSpawner {
+        fn spawn(&self, task: futures_util::future::BoxFuture<'static, ()>) {
+            if self.spawned.fetch_add(1, Ordering::SeqCst) == 0 {
+                let release = Arc::clone(&self.release);
+                tokio::spawn(async move {
+                    release.acquire_owned().await.unwrap().forget();
+                    task.await;
+                });
+            } else {
+                tokio::spawn(task);
+            }
+        }
+    }
+
+    fn credentials() -> TencentCloudCredentials {
+        TencentCloudCredentials {
+            app_id: "1259220000".into(),
+            secret_id: "test-secret-id".into(),
+            secret_key: "key".into(),
+            model: DEFAULT_MODEL.into(),
+        }
+    }
+
+    #[test]
+    fn hmac_sha1_signature_matches_known_vector() {
+        assert_eq!(
+            compute_signature("The quick brown fox jumps over the lazy dog", "key"),
+            "3nybhbi3iqa8ino29wqQcBydtNk="
+        );
+    }
+
+    #[test]
+    fn connect_url_uses_sorted_signed_query_and_encodes_signature() {
+        let url = connect_url_at(
+            DEFAULT_ENDPOINT,
+            &credentials(),
+            1_700_000_000,
+            42,
+            "voice-id".into(),
+        );
+        assert!(url.starts_with(
+            "wss://asr.cloud.tencent.com/asr/v2/1259220000?engine_model_type=Hy-ASR-3.0-preview&expired=1700086400"
+        ));
+        assert!(url.contains("&nonce=42&secretid=test-secret-id&timestamp=1700000000"));
+        assert!(url.contains("&voice_format=1&voice_id=voice-id&signature="));
+        assert!(!url.ends_with('='));
+    }
+
+    #[test]
+    fn stable_segments_replace_partials_and_keep_order() {
+        let asr = TencentCloudStreamingASR::new(credentials());
+        asr.record_result(&serde_json::json!({
+            "slice_type": 1,
+            "index": 1,
+            "voice_text_str": "世界"
+        }));
+        asr.record_result(&serde_json::json!({
+            "slice_type": 2,
+            "index": 0,
+            "voice_text_str": "你好"
+        }));
+        let state = asr.state.lock();
+        assert_eq!(
+            state.final_segments.get(&0).map(String::as_str),
+            Some("你好")
+        );
+        assert_eq!(
+            state.partial_segments.get(&1).map(String::as_str),
+            Some("世界")
+        );
+    }
+
+    #[test]
+    fn server_errors_are_classified_for_actions() {
+        assert!(matches!(
+            classify_server_error(4002),
+            TencentCloudASRError::AuthRejected(_)
+        ));
+        assert!(matches!(
+            classify_server_error(4006),
+            TencentCloudASRError::RateLimited
+        ));
+        assert!(matches!(
+            classify_server_error(5000),
+            TencentCloudASRError::ServiceUnavailable(5000)
+        ));
+    }
+
+    #[test]
+    fn auth_ok_requires_all_three_keys() {
+        assert!(credentials().auth_ok());
+        assert!(!TencentCloudCredentials {
+            app_id: "app".into(),
+            secret_id: "id".into(),
+            secret_key: String::new(),
+            model: DEFAULT_MODEL.into(),
+        }
+        .auth_ok());
+    }
+
+    #[tokio::test]
+    async fn websocket_session_sends_all_audio_before_end_and_returns_final_text() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let endpoint = format!("ws://{}/asr/v2", listener.local_addr().unwrap());
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success" }).to_string(),
+            ))
+            .await
+            .unwrap();
+
+            let first = ws.next().await.unwrap().unwrap();
+            let second = ws.next().await.unwrap().unwrap();
+            let end = ws.next().await.unwrap().unwrap();
+            assert!(matches!(first, Message::Binary(bytes) if bytes.len() == 6_400));
+            assert!(matches!(second, Message::Binary(bytes) if bytes.len() == 100));
+            assert_eq!(end, Message::Text(r#"{"type":"end"}"#.to_string()));
+
+            ws.send(Message::Text(
+                serde_json::json!({
+                    "code": 0,
+                    "message": "success",
+                    "result": { "slice_type": 2, "index": 0, "voice_text_str": "你好" }
+                })
+                .to_string(),
+            ))
+            .await
+            .unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success", "final": 1 }).to_string(),
+            ))
+            .await
+            .unwrap();
+        });
+        let asr = Arc::new(TencentCloudStreamingASR::with_endpoint(
+            credentials(),
+            Arc::new(TokioTaskSpawner),
+            endpoint,
+        ));
+
+        asr.open_session().await.unwrap();
+        asr.consume_pcm_chunk(&vec![1; 6_500]);
+        asr.send_last_frame().await.unwrap();
+        let transcript = asr.await_final_result().await.unwrap();
+
+        assert_eq!(transcript.text, "你好");
+        assert_eq!(transcript.duration_ms, 203);
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn end_waits_for_queued_audio_even_when_writer_start_is_delayed() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let endpoint = format!("ws://{}/asr/v2", listener.local_addr().unwrap());
+        let (first_tx, mut first_rx) = oneshot::channel();
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success" }).to_string(),
+            ))
+            .await
+            .unwrap();
+            first_tx.send(ws.next().await.unwrap().unwrap()).unwrap();
+            assert!(matches!(
+                ws.next().await.unwrap().unwrap(),
+                Message::Binary(bytes) if bytes.len() == 100
+            ));
+            assert_eq!(
+                ws.next().await.unwrap().unwrap(),
+                Message::Text(r#"{"type":"end"}"#.to_string())
+            );
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success", "final": 1 }).to_string(),
+            ))
+            .await
+            .unwrap();
+        });
+        let release = Arc::new(tokio::sync::Semaphore::new(0));
+        let asr = Arc::new(TencentCloudStreamingASR::with_endpoint(
+            credentials(),
+            Arc::new(DelayedFirstSpawner {
+                spawned: AtomicUsize::new(0),
+                release: Arc::clone(&release),
+            }),
+            endpoint,
+        ));
+        asr.open_session().await.unwrap();
+        asr.consume_pcm_chunk(&vec![1; 6_500]);
+        let finishing = {
+            let asr = Arc::clone(&asr);
+            tokio::spawn(async move { asr.send_last_frame().await })
+        };
+
+        assert!(
+            tokio::time::timeout(Duration::from_millis(1_800), &mut first_rx)
+                .await
+                .is_err(),
+            "end must not bypass audio queued on a delayed writer"
+        );
+        release.add_permits(1);
+        assert!(matches!(
+            tokio::time::timeout(Duration::from_secs(2), &mut first_rx)
+                .await
+                .unwrap()
+                .unwrap(),
+            Message::Binary(bytes) if bytes.len() == 6_400
+        ));
+        finishing.await.unwrap().unwrap();
+        assert!(asr.await_final_result().await.unwrap().text.is_empty());
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn buffered_audio_replay_stays_within_tencent_rate_limit() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let endpoint = format!("ws://{}/asr/v2", listener.local_addr().unwrap());
+        let (elapsed_tx, elapsed_rx) = oneshot::channel();
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success" }).to_string(),
+            ))
+            .await
+            .unwrap();
+            let mut received_at = Vec::new();
+            for _ in 0..3 {
+                assert!(matches!(
+                    ws.next().await.unwrap().unwrap(),
+                    Message::Binary(bytes) if bytes.len() == TARGET_AUDIO_CHUNK_BYTES
+                ));
+                received_at.push(tokio::time::Instant::now());
+            }
+            assert_eq!(
+                ws.next().await.unwrap().unwrap(),
+                Message::Text(r#"{"type":"end"}"#.to_string())
+            );
+            elapsed_tx
+                .send(received_at[2].duration_since(received_at[0]))
+                .unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success", "final": 1 }).to_string(),
+            ))
+            .await
+            .unwrap();
+        });
+        let asr = Arc::new(TencentCloudStreamingASR::with_endpoint(
+            credentials(),
+            Arc::new(TokioTaskSpawner),
+            endpoint,
+        ));
+
+        asr.open_session().await.unwrap();
+        asr.consume_pcm_chunk(&vec![1; TARGET_AUDIO_CHUNK_BYTES * 3]);
+        asr.send_last_frame().await.unwrap();
+        asr.await_final_result().await.unwrap();
+
+        assert!(
+            elapsed_rx.await.unwrap() >= Duration::from_millis(180),
+            "buffered audio must be paced instead of sent as one burst"
+        );
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn websocket_rejection_does_not_expose_server_message() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let endpoint = format!("ws://{}/asr/v2", listener.local_addr().unwrap());
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({
+                    "code": 4002,
+                    "message": "SENSITIVE_SERVER_RESPONSE"
+                })
+                .to_string(),
+            ))
+            .await
+            .unwrap();
+        });
+        let asr = Arc::new(TencentCloudStreamingASR::with_endpoint(
+            credentials(),
+            Arc::new(TokioTaskSpawner),
+            endpoint,
+        ));
+
+        let error = asr.open_session().await.unwrap_err();
+
+        assert!(matches!(error, TencentCloudASRError::AuthRejected(4002)));
+        assert!(!error.to_string().contains("SENSITIVE_SERVER_RESPONSE"));
+        server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn cancel_closes_the_socket_and_unblocks_waiters() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let endpoint = format!("ws://{}/asr/v2", listener.local_addr().unwrap());
+        let (closed_tx, closed_rx) = oneshot::channel();
+        let server = tokio::spawn(async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
+            ws.send(Message::Text(
+                serde_json::json!({ "code": 0, "message": "success" }).to_string(),
+            ))
+            .await
+            .unwrap();
+            let closed = matches!(
+                ws.next().await,
+                Some(Ok(Message::Close(_))) | None | Some(Err(_))
+            );
+            closed_tx.send(closed).unwrap();
+        });
+        let asr = Arc::new(TencentCloudStreamingASR::with_endpoint(
+            credentials(),
+            Arc::new(TokioTaskSpawner),
+            endpoint,
+        ));
+        asr.open_session().await.unwrap();
+
+        asr.cancel();
+
+        assert!(tokio::time::timeout(Duration::from_secs(2), closed_rx)
+            .await
+            .unwrap()
+            .unwrap());
+        assert!(matches!(
+            asr.send_last_frame().await,
+            Err(TencentCloudASRError::ConnectionFailed)
+        ));
+        assert!(matches!(
+            asr.await_final_result().await,
+            Err(TencentCloudASRError::NoFinalResult)
+        ));
+        server.await.unwrap();
+    }
+}
diff --git a/openless-all/app/crates/openless-core/src/cloud_providers.rs b/openless-all/app/crates/openless-core/src/cloud_providers.rs
index 0793bbe4..159c69b8 100644
--- a/openless-all/app/crates/openless-core/src/cloud_providers.rs
+++ b/openless-all/app/crates/openless-core/src/cloud_providers.rs
@@ -12,11 +12,13 @@ use std::time::{Duration, Instant};
 use futures_util::future::BoxFuture;
 use parking_lot::{Mutex, RwLock};
 
+use crate::asr::tencent_cloud::TencentCloudASRError;
 use crate::asr::{
     BailianCredentials, BailianRealtimeASR, DashScopeMultimodalASR, DictionaryHotword,
     ElevenLabsBatchASR, MimoBatchASR, Qwen3RealtimeASR, Qwen3RealtimeCredentials,
-    StepfunRealtimeASR, StepfunRealtimeCredentials, VolcengineCredentials, VolcengineStreamingASR,
-    WhisperBatchASR, XfyunCredentials, XfyunStreamingASR,
+    StepfunRealtimeASR, StepfunRealtimeCredentials, TencentCloudCredentials,
+    TencentCloudStreamingASR, VolcengineCredentials, VolcengineStreamingASR, WhisperBatchASR,
+    XfyunCredentials, XfyunStreamingASR,
 };
 use crate::config::{TaskSpawner, TokioTaskSpawner};
 use crate::credentials::{
@@ -24,7 +26,8 @@ use crate::credentials::{
     ASR_API_KEY_ACCOUNT, ASR_ENDPOINT_ACCOUNT, ASR_MODEL_ACCOUNT, ASR_VOCABULARY_ID_ACCOUNT,
     LLM_API_KEY_ACCOUNT, LLM_ENDPOINT_ACCOUNT, LLM_EXTRA_HEADERS_ACCOUNT, LLM_TEMPERATURE_ACCOUNT,
     OMNI_API_KEY_ACCOUNT, OMNI_ENDPOINT_ACCOUNT, OMNI_EXTRA_HEADERS_ACCOUNT, OMNI_MODEL_ACCOUNT,
-    OMNI_TEMPERATURE_ACCOUNT, VOLCENGINE_ACCESS_KEY_ACCOUNT, VOLCENGINE_API_KEY_ACCOUNT,
+    OMNI_TEMPERATURE_ACCOUNT, TENCENT_CLOUD_APP_ID_ACCOUNT, TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+    TENCENT_CLOUD_SECRET_KEY_ACCOUNT, VOLCENGINE_ACCESS_KEY_ACCOUNT, VOLCENGINE_API_KEY_ACCOUNT,
     VOLCENGINE_APP_KEY_ACCOUNT, VOLCENGINE_AUTH_MODE_ACCOUNT, VOLCENGINE_RESOURCE_ID_ACCOUNT,
     XFYUN_API_KEY_ACCOUNT, XFYUN_APP_ID_ACCOUNT,
 };
@@ -60,6 +63,7 @@ pub const SHARED_CLOUD_ASR_PROVIDER_TYPES: &[&str] = &[
     "openai-compatible",
     "xiaomi-mimo-asr",
     "iflytek",
+    "tencent-cloud",
 ];
 
 pub const SHARED_CLOUD_LLM_PROVIDER_TYPES: &[&str] = &[
@@ -79,6 +83,7 @@ pub const SHARED_CLOUD_LLM_PROVIDER_TYPES: &[&str] = &[
     "minimax",
     "stepfun",
     "opencode",
+    "tencentTokenHub",
     "custom",
     "custom_responses",
     "custom_messages",
@@ -119,6 +124,7 @@ enum CloudTranscriptionSessionKind {
     QwenRealtime(Arc<Qwen3RealtimeASR>),
     StepfunRealtime(Arc<StepfunRealtimeASR>),
     Xfyun(Arc<XfyunStreamingASR>),
+    TencentCloud(Arc<TencentCloudStreamingASR>),
 }
 
 struct CloudTranscriptionSession {
@@ -169,6 +175,9 @@ impl AudioConsumer for CloudTranscriptionSession {
                 provider.consume_pcm_chunk(pcm)
             }
             CloudTranscriptionSessionKind::Xfyun(provider) => provider.consume_pcm_chunk(pcm),
+            CloudTranscriptionSessionKind::TencentCloud(provider) => {
+                provider.consume_pcm_chunk(pcm)
+            }
         }
     }
 }
@@ -235,6 +244,16 @@ impl TranscriptionSession for CloudTranscriptionSession {
                     timeout_transcription(Duration::from_secs(120), provider.await_final_result())
                         .await?
                 }
+                CloudTranscriptionSessionKind::TencentCloud(provider) => {
+                    provider
+                        .send_last_frame()
+                        .await
+                        .map_err(map_tencent_asr_error)?;
+                    provider
+                        .await_final_result()
+                        .await
+                        .map_err(map_tencent_asr_error)?
+                }
             };
             Ok(TranscriptOutput {
                 text: transcript.text,
@@ -254,6 +273,7 @@ impl TranscriptionSession for CloudTranscriptionSession {
             CloudTranscriptionSessionKind::QwenRealtime(provider) => provider.cancel(),
             CloudTranscriptionSessionKind::StepfunRealtime(provider) => provider.cancel(),
             CloudTranscriptionSessionKind::Xfyun(provider) => provider.cancel(),
+            CloudTranscriptionSessionKind::TencentCloud(provider) => provider.cancel(),
         }
         Box::pin(async { Ok(()) })
     }
@@ -632,6 +652,62 @@ async fn build_cloud_transcription_session(
             provider.open_session().await.map_err(map_asr_error)?;
             (CloudTranscriptionSessionKind::Xfyun(provider), None)
         }
+        ActiveAsrProviderKind::TencentCloud => {
+            let app_id = read_channel_credential(
+                credentials,
+                CredentialNamespace::Asr,
+                channel_id,
+                TENCENT_CLOUD_APP_ID_ACCOUNT,
+            )
+            .await?
+            .unwrap_or_default();
+            let secret_id = read_channel_credential(
+                credentials,
+                CredentialNamespace::Asr,
+                channel_id,
+                TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+            )
+            .await?
+            .unwrap_or_default();
+            let secret_key = read_channel_credential(
+                credentials,
+                CredentialNamespace::Asr,
+                channel_id,
+                TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
+            )
+            .await?
+            .unwrap_or_default();
+            require_configured(&app_id, "Tencent Cloud AppID")?;
+            require_configured(&secret_id, "Tencent Cloud SecretID")?;
+            require_configured(&secret_key, "Tencent Cloud SecretKey")?;
+            let model = read_channel_credential(
+                credentials,
+                CredentialNamespace::Asr,
+                channel_id,
+                ASR_MODEL_ACCOUNT,
+            )
+            .await?
+            .filter(|value| !value.trim().is_empty())
+            .unwrap_or_else(|| crate::asr::tencent_cloud::DEFAULT_MODEL.to_string());
+            let provider = Arc::new(TencentCloudStreamingASR::with_task_spawner(
+                TencentCloudCredentials {
+                    app_id,
+                    secret_id,
+                    secret_key,
+                    model: model.clone(),
+                },
+                Arc::clone(&task_spawner),
+            ));
+            provider.set_partial_sink(Arc::clone(&partials));
+            provider
+                .open_session()
+                .await
+                .map_err(map_tencent_asr_error)?;
+            (
+                CloudTranscriptionSessionKind::TencentCloud(provider),
+                Some(model),
+            )
+        }
     };
     Ok((kind, crate::AsrCallLabel::new(effective, label_model)))
 }
@@ -676,6 +752,22 @@ fn map_asr_error(error: impl std::fmt::Display) -> BackendError {
     )
 }
 
+fn map_tencent_asr_error(error: TencentCloudASRError) -> BackendError {
+    let retryable = matches!(
+        &error,
+        TencentCloudASRError::ConnectionFailed
+            | TencentCloudASRError::RateLimited
+            | TencentCloudASRError::ServiceUnavailable(_)
+            | TencentCloudASRError::NoFinalResult
+            | TencentCloudASRError::FinalResultTimeout
+    );
+    BackendError::new(
+        BackendErrorCode::Provider,
+        format!("Tencent Cloud ASR failed: {error}"),
+    )
+    .retryable(retryable)
+}
+
 pub struct SharedCloudTextPolisher {
     credentials: Arc<dyn CredentialStore>,
     active: Arc<Mutex<HashMap<SessionId, Arc<ProviderCancellation>>>>,
@@ -1868,6 +1960,35 @@ mod tests {
     use super::*;
     use crate::{InMemoryCredentialStore, ProviderInvocation, SecretValue};
 
+    #[test]
+    fn tencent_cloud_errors_keep_retryability_and_stable_public_messages() {
+        use crate::asr::tencent_cloud::TencentCloudASRError;
+
+        for error in [
+            TencentCloudASRError::ConnectionFailed,
+            TencentCloudASRError::RateLimited,
+            TencentCloudASRError::NoFinalResult,
+            TencentCloudASRError::FinalResultTimeout,
+            TencentCloudASRError::ServiceUnavailable(5000),
+        ] {
+            let error = map_tencent_asr_error(error);
+            assert_eq!(error.code, BackendErrorCode::Provider);
+            assert!(error.retryable, "{error:?}");
+            assert!(error.details.is_none());
+        }
+        for error in [
+            TencentCloudASRError::CredentialsMissing,
+            TencentCloudASRError::AuthRejected(4002),
+            TencentCloudASRError::AccountUnavailable(4004),
+            TencentCloudASRError::TaskFailed(4001),
+        ] {
+            let error = map_tencent_asr_error(error);
+            assert_eq!(error.code, BackendErrorCode::Provider);
+            assert!(!error.retryable, "{error:?}");
+            assert!(error.details.is_none());
+        }
+    }
+
     struct IgnoreTextStreamSink;
 
     impl TextStreamSink for IgnoreTextStreamSink {
diff --git a/openless-all/app/crates/openless-core/src/credentials.rs b/openless-all/app/crates/openless-core/src/credentials.rs
index db651678..dc627063 100644
--- a/openless-all/app/crates/openless-core/src/credentials.rs
+++ b/openless-all/app/crates/openless-core/src/credentials.rs
@@ -68,6 +68,9 @@ pub const VOLCENGINE_AUTH_MODE_ACCOUNT: &str = "volcengine.auth_mode";
 pub const VOLCENGINE_API_KEY_ACCOUNT: &str = "volcengine.api_key";
 pub const XFYUN_APP_ID_ACCOUNT: &str = "xfyun.app_id";
 pub const XFYUN_API_KEY_ACCOUNT: &str = "xfyun.api_key";
+pub const TENCENT_CLOUD_APP_ID_ACCOUNT: &str = "tencent_cloud.app_id";
+pub const TENCENT_CLOUD_SECRET_ID_ACCOUNT: &str = "tencent_cloud.secret_id";
+pub const TENCENT_CLOUD_SECRET_KEY_ACCOUNT: &str = "tencent_cloud.secret_key";
 pub const LLM_API_KEY_ACCOUNT: &str = "ark.api_key";
 pub const LLM_MODEL_ACCOUNT: &str = "ark.model_id";
 pub const LLM_ENDPOINT_ACCOUNT: &str = "ark.endpoint";
diff --git a/openless-all/app/crates/openless-core/src/credentials_legacy.rs b/openless-all/app/crates/openless-core/src/credentials_legacy.rs
index 6b5bc878..74b3f190 100644
--- a/openless-all/app/crates/openless-core/src/credentials_legacy.rs
+++ b/openless-all/app/crates/openless-core/src/credentials_legacy.rs
@@ -99,6 +99,9 @@ struct LegacyEntry {
     advanced_config: Option<String>,
     xfyun_app_id: Option<String>,
     xfyun_api_key: Option<String>,
+    tencent_cloud_app_id: Option<String>,
+    tencent_cloud_secret_id: Option<String>,
+    tencent_cloud_secret_key: Option<String>,
     temperature: Option<f64>,
     extra_headers: Option<BTreeMap<String, String>>,
     request_format: Option<String>,
@@ -127,6 +130,9 @@ impl Default for LegacyEntry {
             advanced_config: None,
             xfyun_app_id: None,
             xfyun_api_key: None,
+            tencent_cloud_app_id: None,
+            tencent_cloud_secret_id: None,
+            tencent_cloud_secret_key: None,
             temperature: None,
             extra_headers: None,
             request_format: None,
@@ -153,6 +159,9 @@ impl LegacyEntry {
             &self.advanced_config,
             &self.xfyun_app_id,
             &self.xfyun_api_key,
+            &self.tencent_cloud_app_id,
+            &self.tencent_cloud_secret_id,
+            &self.tencent_cloud_secret_key,
             &self.request_format,
             &self.messages_thinking,
             &self.max_tokens,
@@ -379,6 +388,15 @@ fn decode_entry(
             (ASR_ADVANCED_CONFIG_ACCOUNT, entry.advanced_config),
             (XFYUN_APP_ID_ACCOUNT, entry.xfyun_app_id),
             (XFYUN_API_KEY_ACCOUNT, entry.xfyun_api_key),
+            (TENCENT_CLOUD_APP_ID_ACCOUNT, entry.tencent_cloud_app_id),
+            (
+                TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+                entry.tencent_cloud_secret_id,
+            ),
+            (
+                TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
+                entry.tencent_cloud_secret_key,
+            ),
         ]);
     }
     if let Some(account) = extra_headers {
@@ -432,6 +450,9 @@ pub fn read_legacy_accounts(
                 ASR_ADVANCED_CONFIG_ACCOUNT,
                 XFYUN_APP_ID_ACCOUNT,
                 XFYUN_API_KEY_ACCOUNT,
+                TENCENT_CLOUD_APP_ID_ACCOUNT,
+                TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+                TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
             ][..],
         ),
         (
diff --git a/openless-all/app/crates/openless-core/src/llm_protocol.rs b/openless-all/app/crates/openless-core/src/llm_protocol.rs
index ee0e01e7..0c4314ba 100644
--- a/openless-all/app/crates/openless-core/src/llm_protocol.rs
+++ b/openless-all/app/crates/openless-core/src/llm_protocol.rs
@@ -39,7 +39,7 @@ impl LlmRequestFormat {
     }
 
     pub fn selectable(provider: &str) -> bool {
-        !matches!(provider, "gemini" | "codex_oauth")
+        !matches!(provider, "gemini" | "codex_oauth" | "tencentTokenHub")
     }
 
     pub fn parse(value: &str) -> Result<Self, BackendError> {
@@ -531,6 +531,32 @@ mod tests {
             .is_err());
     }
 
+    #[tokio::test]
+    async fn tokenhub_is_fixed_to_chat_completions() {
+        let store = InMemoryCredentialStore::default();
+        store
+            .write(
+                CredentialKey::new(
+                    CredentialNamespace::Llm,
+                    Some("tokenhub".into()),
+                    REQUEST_FORMAT_ACCOUNT,
+                )
+                .unwrap(),
+                SecretValue::new("messages"),
+            )
+            .await
+            .unwrap();
+
+        assert!(!LlmRequestFormat::selectable("tencentTokenHub"));
+        assert_eq!(
+            LlmProtocolConfig::load(&store, "tokenhub", "tencentTokenHub")
+                .await
+                .unwrap()
+                .format,
+            LlmRequestFormat::ChatCompletions
+        );
+    }
+
     #[test]
     fn urls_and_auth_follow_format_without_losing_gateway_paths() {
         for descriptor in crate::provider_rules::provider_descriptors(crate::ProviderKind::Llm) {
diff --git a/openless-all/app/crates/openless-core/src/polish.rs b/openless-all/app/crates/openless-core/src/polish.rs
index 9bd15dc1..13d4e5d1 100644
--- a/openless-all/app/crates/openless-core/src/polish.rs
+++ b/openless-all/app/crates/openless-core/src/polish.rs
@@ -189,6 +189,7 @@ fn is_builtin_llm_provider(provider_id: &str) -> bool {
             | "minimax"
             | "stepfun"
             | "opencode"
+            | "tencentTokenHub"
     )
 }
 
@@ -1649,14 +1650,20 @@ pub(crate) fn apply_openai_compatible_thinking_control(
     model: &str,
     thinking_enabled: bool,
 ) {
+    if provider_id.trim() == "tencentTokenHub" {
+        apply_tokenhub_chat_thinking_control(body, model, thinking_enabled);
+        return;
+    }
     // 优先按 provider_id 预设分派；custom / 未声明 provider 时回退到 base_url 兜底,
     // 让用户用"自定义"preset 接入 MiniMax 也能正确下发 thinking 控制参数。
     // Zen 是多模型网关，仅 DeepSeek 模型使用 DeepSeek 的思考参数。
     let is_opencode = provider_id.trim() == "opencode"
-        || (matches!(provider_id.trim(), "custom" | "custom_responses" | "custom_messages")
-            && url::Url::parse(base_url.trim())
-                .ok()
-                .is_some_and(|url| url.host_str() == Some("opencode.ai")));
+        || (matches!(
+            provider_id.trim(),
+            "custom" | "custom_responses" | "custom_messages"
+        ) && url::Url::parse(base_url.trim())
+            .ok()
+            .is_some_and(|url| url.host_str() == Some("opencode.ai")));
     let control = if is_opencode {
         model
             .trim()
@@ -1709,6 +1716,31 @@ pub(crate) fn apply_openai_compatible_thinking_control(
     }
 }
 
+fn apply_tokenhub_chat_thinking_control(body: &mut Value, model: &str, enabled: bool) {
+    use crate::provider_rules::TokenHubChatModelPolicy::*;
+
+    match crate::provider_rules::tokenhub_chat_model_policy(model) {
+        Some(Hy3) => {
+            body["thinking"] = json!({ "type": if enabled { "enabled" } else { "disabled" } });
+            if enabled {
+                body["reasoning_effort"] = json!("medium");
+            }
+        }
+        Some(ToggleThinking) => {
+            body["thinking"] = json!({ "type": if enabled { "enabled" } else { "disabled" } });
+        }
+        Some(QwenThinking) => body["enable_thinking"] = json!(enabled),
+        Some(AdaptiveThinking) => {
+            body["thinking"] = json!({ "type": if enabled { "adaptive" } else { "disabled" } });
+        }
+        Some(AlwaysThinking) if enabled => {
+            body["thinking"] = json!({ "type": "enabled" });
+        }
+        Some(KimiK3) if enabled => body["reasoning_effort"] = json!("max"),
+        Some(AlwaysThinking | KimiK3 | Plain) | None => {}
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum ThinkingControl {
     ReasoningEffort,
@@ -2143,8 +2175,12 @@ mod tests {
     #[tokio::test]
     async fn all_text_entrypoints_use_the_selected_protocol_over_http() {
         for (format, (preset, prefix)) in LlmRequestFormat::ALL.into_iter().flat_map(|format| {
-            [("custom", "/gateway/v1"), ("opencode", "/zen/v1"), ("opencode", "/zen/go/v1")]
-                .map(|entry| (format, entry))
+            [
+                ("custom", "/gateway/v1"),
+                ("opencode", "/zen/v1"),
+                ("opencode", "/zen/go/v1"),
+            ]
+            .map(|entry| (format, entry))
         }) {
             let listener = TcpListener::bind("127.0.0.1:0").unwrap();
             let address = listener.local_addr().unwrap();
@@ -2311,7 +2347,11 @@ mod tests {
             ("custom", "https://opencode.ai/zen/v1", true),
             ("custom_responses", "https://opencode.ai/zen/v1", true),
             ("custom_messages", "https://opencode.ai/zen/v1", true),
-            ("custom", "https://OPENCODE.AI:443/zen/go/v1/chat/completions", true),
+            (
+                "custom",
+                "https://OPENCODE.AI:443/zen/go/v1/chat/completions",
+                true,
+            ),
             ("custom", "https://opencode.ai.example/zen/v1", false),
             ("custom", "https://fakeopencode.ai/zen/v1", false),
             ("custom", "https://opencode.ai@example.com/zen/v1", false),
@@ -2323,22 +2363,37 @@ mod tests {
                         let provider = OpenAICompatibleLLMProvider::new(
                             OpenAICompatibleConfig::new(preset, "test", endpoint, "key", model)
                                 .with_thinking_enabled(enabled)
-                                .with_protocol(LlmProtocolConfig { format, ..Default::default() }),
+                                .with_protocol(LlmProtocolConfig {
+                                    format,
+                                    ..Default::default()
+                                }),
                         );
-                        let body = provider.chat_body(false, vec![json!({"role":"user","content":"hi"})]);
+                        let body =
+                            provider.chat_body(false, vec![json!({"role":"user","content":"hi"})]);
                         match format {
-                            LlmRequestFormat::ChatCompletions if zen && model.starts_with("deepseek-") => {
-                                assert_eq!(body["thinking"]["type"], if enabled { "enabled" } else { "disabled" });
+                            LlmRequestFormat::ChatCompletions
+                                if zen && model.starts_with("deepseek-") =>
+                            {
+                                assert_eq!(
+                                    body["thinking"]["type"],
+                                    if enabled { "enabled" } else { "disabled" }
+                                );
                             }
                             LlmRequestFormat::Messages if enabled => {
                                 assert_eq!(body["thinking"]["type"], "adaptive");
                             }
-                            _ => assert!(body.get("thinking").is_none(), "{preset} {endpoint} {model} {format:?}"),
+                            _ => assert!(
+                                body.get("thinking").is_none(),
+                                "{preset} {endpoint} {model} {format:?}"
+                            ),
                         }
                         assert!(body.get("reasoning_effort").is_none());
                         assert!(body.get("enable_thinking").is_none());
                         if format == LlmRequestFormat::Responses {
-                            assert_eq!(body["reasoning"]["effort"], if enabled { "medium" } else { "low" });
+                            assert_eq!(
+                                body["reasoning"]["effort"],
+                                if enabled { "medium" } else { "low" }
+                            );
                             assert!(body.get("messages").is_none());
                         } else {
                             assert!(body.get("reasoning").is_none());
@@ -3224,6 +3279,88 @@ mod tests {
         assert_eq!(body["thinking"]["type"], "adaptive");
     }
 
+    #[test]
+    fn tokenhub_chat_thinking_matches_model_capabilities() {
+        let body = |model: &str, enabled: bool| {
+            OpenAICompatibleLLMProvider::new(
+                OpenAICompatibleConfig::new(
+                    "tencentTokenHub",
+                    "Tencent TokenHub",
+                    "https://tokenhub.tencentmaas.com/v1",
+                    "k",
+                    model,
+                )
+                .with_thinking_enabled(enabled),
+            )
+            .chat_body(false, vec![json!({ "role": "user", "content": "hi" })])
+        };
+
+        for model in [
+            "hy3",
+            "hy4-preview",
+            "deepseek-v4-pro",
+            "deepseek/deepseek-v4-flash",
+            "glm-5.2",
+            "glm-5v-turbo",
+            "kimi-k2.6",
+            "kimi-k2.5",
+        ] {
+            assert_eq!(body(model, true)["thinking"]["type"], "enabled", "{model}");
+            assert_eq!(
+                body(model, false)["thinking"]["type"],
+                "disabled",
+                "{model}"
+            );
+        }
+        assert_eq!(body("hy3", true)["reasoning_effort"], "medium");
+
+        assert_eq!(body("qwen3.5-plus", true)["enable_thinking"], true);
+        assert_eq!(body("qwen3.5-plus", false)["enable_thinking"], false);
+
+        assert_eq!(body("minimax-m3", true)["thinking"]["type"], "adaptive");
+        assert_eq!(body("minimax-m3", false)["thinking"]["type"], "disabled");
+
+        for model in ["glm-5.3", "kimi-k2.7-code", "minimax-m2.7"] {
+            assert!(body(model, false).get("thinking").is_none(), "{model}");
+            assert_eq!(body(model, true)["thinking"]["type"], "enabled");
+        }
+        let kimi_k3 = body("kimi-k3", true);
+        assert_eq!(kimi_k3["reasoning_effort"], "max");
+        assert!(kimi_k3.get("thinking").is_none());
+        assert!(body("kimi-k3", false).get("reasoning_effort").is_none());
+
+        for model in [
+            "hy-mt2-pro",
+            "hy-role",
+            "hunyuan-role-latest",
+            "mimo-v2.5-pro",
+            "future-model",
+        ] {
+            let body = body(model, true);
+            assert!(body.get("thinking").is_none(), "{model}");
+            assert!(body.get("enable_thinking").is_none(), "{model}");
+            assert!(body.get("reasoning_effort").is_none(), "{model}");
+        }
+    }
+
+    #[test]
+    fn custom_tokenhub_endpoint_does_not_invent_model_policy() {
+        for base_url in [
+            "https://tokenhub.tencentmaas.com/v1/",
+            "https://api.lkeap.cloud.tencent.com/plan/v3",
+        ] {
+            let provider = OpenAICompatibleLLMProvider::new(
+                OpenAICompatibleConfig::new("custom", "Custom", base_url, "k", "hy3")
+                    .with_thinking_enabled(false),
+            );
+
+            let body = provider.chat_body(false, vec![json!({ "role": "user", "content": "hi" })]);
+
+            assert!(body.get("thinking").is_none());
+            assert!(body.get("reasoning_effort").is_none());
+        }
+    }
+
     #[test]
     fn openai_chat_body_falls_back_to_base_url_for_custom_minimax_endpoint() {
         // 用 "custom" preset + 自定义 MiniMax base_url 接入时,base_url 兜底
diff --git a/openless-all/app/crates/openless-core/src/provider_rules.rs b/openless-all/app/crates/openless-core/src/provider_rules.rs
index a2efeb6a..d48ca28d 100644
--- a/openless-all/app/crates/openless-core/src/provider_rules.rs
+++ b/openless-all/app/crates/openless-core/src/provider_rules.rs
@@ -21,6 +21,7 @@ const MIMO_PROVIDER_ID: &str = "xiaomi-mimo-asr";
 const DASHSCOPE_MULTIMODAL_PROVIDER_ID: &str = "bailian-fun-asr-flash";
 const ELEVENLABS_PROVIDER_ID: &str = "elevenlabs";
 const XFYUN_PROVIDER_ID: &str = "iflytek";
+const TENCENT_CLOUD_PROVIDER_ID: &str = "tencent-cloud";
 
 const ASR_PROVIDER_TYPES: &[(&str, &str)] = &[
     ("volcengine", "asrVolcengine"),
@@ -39,6 +40,7 @@ const ASR_PROVIDER_TYPES: &[(&str, &str)] = &[
     (OPENAI_COMPATIBLE_ASR_PROVIDER_ID, "asrOpenAiCompatible"),
     ("xiaomi-mimo-asr", "asrXiaomiMimo"),
     (XFYUN_PROVIDER_ID, "asrIflytek"),
+    (TENCENT_CLOUD_PROVIDER_ID, "asrTencentCloud"),
     ("foundry-local-whisper", "asrFoundryLocalWhisper"),
     ("local-whisper", "asrLocalWhisper"),
     ("sherpa-onnx-local", "asrSherpaOnnxLocal"),
@@ -65,6 +67,7 @@ const LLM_PROVIDER_TYPES: &[(&str, &str)] = &[
     ("minimax", "minimax"),
     ("stepfun", "stepfun"),
     ("opencode", "opencode"),
+    ("tencentTokenHub", "tencentTokenHub"),
     ("custom", "customChatCompletions"),
     ("custom_responses", "customResponses"),
     ("custom_messages", "customMessages"),
@@ -112,6 +115,7 @@ pub enum AuthRequirement {
     ApiKeyUnlessCustomEndpoint,
     Volcengine,
     Xfyun,
+    TencentCloud,
     OAuth,
 }
 
@@ -189,11 +193,14 @@ fn provider_descriptor_with_label(
             match id.as_str() {
                 "volcengine" => AuthRequirement::Volcengine,
                 XFYUN_PROVIDER_ID => AuthRequirement::Xfyun,
+                TENCENT_CLOUD_PROVIDER_ID => AuthRequirement::TencentCloud,
                 OPENAI_COMPATIBLE_ASR_PROVIDER_ID => AuthRequirement::EndpointModelOptionalApiKey,
                 _ => AuthRequirement::ApiKey,
             },
             match id.as_str() {
-                "volcengine" | XFYUN_PROVIDER_ID => ValidationProbe::AsrSilenceAllowsNoFinal,
+                "volcengine" | XFYUN_PROVIDER_ID | TENCENT_CLOUD_PROVIDER_ID => {
+                    ValidationProbe::AsrSilenceAllowsNoFinal
+                }
                 "stepfun" => ValidationProbe::StepfunNoSpeech,
                 DASHSCOPE_MULTIMODAL_PROVIDER_ID => ValidationProbe::AsrNonSilent,
                 _ => ValidationProbe::AsrSilence,
@@ -305,6 +312,7 @@ pub enum ActiveAsrProviderKind {
     WhisperCompatible,
     Volcengine,
     Xfyun,
+    TencentCloud,
 }
 
 /// Non-secret facts read by a platform credential adapter. Core evaluates
@@ -321,6 +329,9 @@ pub struct CredentialConfiguration {
     pub volcengine_resource_id: bool,
     pub xfyun_app_id: bool,
     pub xfyun_api_key: bool,
+    pub tencent_cloud_app_id: bool,
+    pub tencent_cloud_secret_id: bool,
+    pub tencent_cloud_secret_key: bool,
     pub llm_api_key: bool,
     pub llm_endpoint: bool,
     pub llm_endpoint_matches_default: bool,
@@ -403,6 +414,11 @@ pub fn auth_requirement_satisfied(
         }
         AuthRequirement::Volcengine => volcengine_configured(configuration),
         AuthRequirement::Xfyun => configuration.xfyun_app_id && configuration.xfyun_api_key,
+        AuthRequirement::TencentCloud => {
+            configuration.tencent_cloud_app_id
+                && configuration.tencent_cloud_secret_id
+                && configuration.tencent_cloud_secret_key
+        }
         AuthRequirement::OAuth => configuration.codex_oauth && model,
     }
 }
@@ -418,7 +434,8 @@ pub fn api_key_required(
     match descriptor.auth_requirement {
         AuthRequirement::None
         | AuthRequirement::EndpointModelOptionalApiKey
-        | AuthRequirement::OAuth => false,
+        | AuthRequirement::OAuth
+        | AuthRequirement::TencentCloud => false,
         AuthRequirement::ApiKeyUnlessCustomEndpoint => {
             let Some(endpoint) = configured_endpoint.filter(|value| !value.trim().is_empty())
             else {
@@ -480,6 +497,7 @@ pub fn default_asr_model(provider_type: &str) -> Option<&'static str> {
         "orcarouter" => Some(crate::asr::mimo::ORCAROUTER_DEFAULT_MODEL),
         "zenmux" => Some(crate::asr::whisper::ZENMUX_DEFAULT_MODEL),
         "xiaomi-mimo-asr" => Some(crate::asr::mimo::DEFAULT_MODEL),
+        TENCENT_CLOUD_PROVIDER_ID => Some(crate::asr::tencent_cloud::DEFAULT_MODEL),
         _ => None,
     }
 }
@@ -501,6 +519,7 @@ pub fn default_llm_endpoint(provider_type: &str) -> Option<&'static str> {
         "codingPlanX" => Some("https://api.codingplanx.ai/v1"),
         "minimax" => Some("https://api.minimaxi.com/v1"),
         "stepfun" => Some("https://api.stepfun.com/v1"),
+        "tencentTokenHub" => Some("https://tokenhub.tencentmaas.com/v1"),
         _ => None,
     }
 }
@@ -521,10 +540,77 @@ pub fn default_llm_model(provider_type: &str) -> Option<&'static str> {
         "codingPlanX" => Some("gpt-5-mini"),
         "minimax" => Some("MiniMax-M3"),
         "stepfun" => Some("step-1o-turbo-vision"),
+        "tencentTokenHub" => Some("hy3"),
         _ => None,
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum TokenHubChatModelPolicy {
+    Hy3,
+    ToggleThinking,
+    QwenThinking,
+    AdaptiveThinking,
+    AlwaysThinking,
+    KimiK3,
+    Plain,
+}
+
+pub(crate) fn tokenhub_chat_model_policy(model: &str) -> Option<TokenHubChatModelPolicy> {
+    use TokenHubChatModelPolicy::*;
+
+    // ponytail: /models lacks capability metadata; keep this one family classifier until it does.
+    let model = model.trim().to_ascii_lowercase();
+    let policy = if matches!(model.as_str(), "hy3" | "hy3-preview") {
+        Hy3
+    } else if model.starts_with("qwen3.5-") {
+        QwenThinking
+    } else if model == "minimax-m3" {
+        AdaptiveThinking
+    } else if model == "kimi-k3" {
+        KimiK3
+    } else if matches!(
+        model.as_str(),
+        "glm-5.3" | "glm-5.3-flash" | "minimax-m2.7" | "minimax-m2.5"
+    ) || model.starts_with("kimi-k2.7-code")
+    {
+        AlwaysThinking
+    } else if model.starts_with("hy4-")
+        || model.starts_with("deepseek-")
+        || model.starts_with("deepseek/")
+        || matches!(
+            model.as_str(),
+            "glm-5.2"
+                | "glm-5.1"
+                | "glm-5"
+                | "glm-5-turbo"
+                | "glm-5v-turbo"
+                | "kimi-k2.6"
+                | "kimi-k2.5"
+        )
+    {
+        ToggleThinking
+    } else {
+        let minimax_language = model
+            .strip_prefix("minimax-m")
+            .and_then(|suffix| suffix.chars().next())
+            .is_some_and(|character| character.is_ascii_digit());
+        if model.starts_with("hy-mt2-")
+            || model.starts_with("hy-role")
+            || model.starts_with("hunyuan-role")
+            || model.starts_with("glm-")
+            || model.starts_with("kimi-")
+            || minimax_language
+            || model.starts_with("mimo-v")
+        {
+            Plain
+        } else {
+            return None;
+        }
+    };
+    Some(policy)
+}
+
 pub fn default_omni_endpoint(provider_type: &str) -> Option<&'static str> {
     match provider_type {
         "openai" => Some("https://api.openai.com/v1"),
@@ -576,6 +662,7 @@ pub fn active_asr_provider_kind(id: &str) -> ActiveAsrProviderKind {
         DASHSCOPE_MULTIMODAL_PROVIDER_ID => ActiveAsrProviderKind::DashScopeMultimodal,
         ELEVENLABS_PROVIDER_ID => ActiveAsrProviderKind::ElevenLabs,
         XFYUN_PROVIDER_ID => ActiveAsrProviderKind::Xfyun,
+        TENCENT_CLOUD_PROVIDER_ID => ActiveAsrProviderKind::TencentCloud,
         value if is_whisper_compatible_provider(value) => ActiveAsrProviderKind::WhisperCompatible,
         _ => ActiveAsrProviderKind::Volcengine,
     }
@@ -609,6 +696,10 @@ pub fn is_xfyun_provider(id: &str) -> bool {
     id == XFYUN_PROVIDER_ID
 }
 
+pub fn is_tencent_cloud_provider(id: &str) -> bool {
+    id == TENCENT_CLOUD_PROVIDER_ID
+}
+
 pub fn is_whisper_compatible_provider(id: &str) -> bool {
     matches!(
         id,
@@ -1003,12 +1094,25 @@ mod tests {
         assert!(crate::cloud_providers::SHARED_CLOUD_LLM_PROVIDER_TYPES.contains(&"opencode"));
         let descriptor = provider_descriptor(ProviderKind::Llm, "opencode").unwrap();
         assert_eq!(descriptor.label_key, "opencode");
-        assert_eq!(descriptor.default_endpoint.as_deref(), Some("https://opencode.ai/zen/v1"));
-        assert_eq!(descriptor.default_model.as_deref(), Some("deepseek-v4-flash"));
-        assert_eq!(descriptor.default_request_format, Some(LlmRequestFormat::ChatCompletions));
+        assert_eq!(
+            descriptor.default_endpoint.as_deref(),
+            Some("https://opencode.ai/zen/v1")
+        );
+        assert_eq!(
+            descriptor.default_model.as_deref(),
+            Some("deepseek-v4-flash")
+        );
+        assert_eq!(
+            descriptor.default_request_format,
+            Some(LlmRequestFormat::ChatCompletions)
+        );
         assert_eq!(descriptor.supported_request_formats, LlmRequestFormat::ALL);
         assert_eq!(descriptor.validation_probe, ValidationProbe::LlmText);
-        assert!(api_key_required(ProviderKind::Llm, "opencode", Some("https://opencode.ai/zen/v1/chat/completions/")));
+        assert!(api_key_required(
+            ProviderKind::Llm,
+            "opencode",
+            Some("https://opencode.ai/zen/v1/chat/completions/")
+        ));
         let mut configuration = CredentialConfiguration {
             llm_endpoint: true,
             llm_endpoint_matches_default: true,
@@ -1020,6 +1124,49 @@ mod tests {
         assert!(llm_configured("opencode", &configuration));
     }
 
+    #[test]
+    fn tencent_cloud_asr_and_tokenhub_supply_defaults_and_credentials() {
+        assert!(crate::cloud_providers::SHARED_CLOUD_ASR_PROVIDER_TYPES.contains(&"tencent-cloud"));
+        assert!(
+            crate::cloud_providers::SHARED_CLOUD_LLM_PROVIDER_TYPES.contains(&"tencentTokenHub")
+        );
+        let asr = provider_descriptor(ProviderKind::Asr, "tencent-cloud").unwrap();
+        assert_eq!(asr.label_key, "asrTencentCloud");
+        assert_eq!(
+            asr.default_model.as_deref(),
+            Some(crate::asr::tencent_cloud::DEFAULT_MODEL)
+        );
+        assert_eq!(asr.auth_requirement, AuthRequirement::TencentCloud);
+        assert_eq!(
+            asr.validation_probe,
+            ValidationProbe::AsrSilenceAllowsNoFinal
+        );
+        let mut configuration = CredentialConfiguration::default();
+        assert!(!auth_requirement_satisfied(&asr, &configuration));
+        configuration.tencent_cloud_app_id = true;
+        configuration.tencent_cloud_secret_id = true;
+        configuration.tencent_cloud_secret_key = true;
+        assert!(auth_requirement_satisfied(&asr, &configuration));
+        assert_eq!(
+            active_asr_provider_kind("tencent-cloud"),
+            ActiveAsrProviderKind::TencentCloud
+        );
+
+        let llm = provider_descriptor(ProviderKind::Llm, "tencentTokenHub").unwrap();
+        assert_eq!(llm.label_key, "tencentTokenHub");
+        assert_eq!(
+            llm.default_endpoint.as_deref(),
+            Some("https://tokenhub.tencentmaas.com/v1")
+        );
+        assert_eq!(llm.default_model.as_deref(), Some("hy3"));
+        assert_eq!(
+            llm.auth_requirement,
+            AuthRequirement::ApiKeyUnlessCustomEndpoint
+        );
+        assert_eq!(llm.default_request_format, None);
+        assert!(llm.supported_request_formats.is_empty());
+    }
+
     #[test]
     fn descriptors_are_the_single_source_for_defaults_auth_and_probes() {
         let compatible = provider_descriptor(ProviderKind::Asr, "openai-compatible").unwrap();
diff --git a/openless-all/app/crates/openless-core/src/provider_service.rs b/openless-all/app/crates/openless-core/src/provider_service.rs
index a3bbd298..d4a89c3f 100644
--- a/openless-all/app/crates/openless-core/src/provider_service.rs
+++ b/openless-all/app/crates/openless-core/src/provider_service.rs
@@ -418,7 +418,7 @@ fn validate_configuration(resolved: &ResolvedProvider) -> Result<(), BackendErro
     ) && api_key.trim().is_empty()
         && !matches!(
             descriptor.auth_requirement,
-            AuthRequirement::Volcengine | AuthRequirement::Xfyun
+            AuthRequirement::Volcengine | AuthRequirement::Xfyun | AuthRequirement::TencentCloud
         )
     {
         let label = match resolved.kind {
@@ -436,7 +436,10 @@ fn validate_configuration(resolved: &ResolvedProvider) -> Result<(), BackendErro
     if model.is_none()
         && !matches!(
             descriptor.auth_requirement,
-            AuthRequirement::None | AuthRequirement::Volcengine | AuthRequirement::Xfyun
+            AuthRequirement::None
+                | AuthRequirement::Volcengine
+                | AuthRequirement::Xfyun
+                | AuthRequirement::TencentCloud
         )
     {
         return Err(invalid_request("provider model is not configured"));
@@ -450,7 +453,10 @@ fn validate_configuration(resolved: &ResolvedProvider) -> Result<(), BackendErro
         if endpoint.is_none()
             && !matches!(
                 descriptor.auth_requirement,
-                AuthRequirement::None | AuthRequirement::Volcengine | AuthRequirement::Xfyun
+                AuthRequirement::None
+                    | AuthRequirement::Volcengine
+                    | AuthRequirement::Xfyun
+                    | AuthRequirement::TencentCloud
             )
         {
             return Err(provider_error("provider endpoint is not configured"));
@@ -650,6 +656,7 @@ async fn fetch_models(
         .ok_or_else(|| provider_error("provider endpoint is not configured"))?;
     let url = models_url(endpoint)?;
     let is_gemini = resolved.provider_type == "gemini";
+    let tokenhub_chat_only = resolved.provider_type == "tencentTokenHub";
     let orcarouter_filter = (resolved.provider_type == "orcarouter").then(|| {
         let endpoint_type = match (resolved.kind, resolved.protocol.format) {
             (ProviderKind::Llm, LlmRequestFormat::Responses) => "openai-response",
@@ -709,7 +716,12 @@ async fn fetch_models(
     if response.body.len() > MODEL_LIST_MAX_BYTES {
         return Err(provider_error("provider model response is too large"));
     }
-    parse_model_list(&response.body, is_gemini, orcarouter_filter)
+    parse_model_list(
+        &response.body,
+        is_gemini,
+        orcarouter_filter,
+        tokenhub_chat_only,
+    )
 }
 
 #[derive(Clone, Copy)]
@@ -722,6 +734,7 @@ fn parse_model_list(
     body: &[u8],
     is_gemini: bool,
     orcarouter_filter: Option<OrcaRouterCatalogFilter>,
+    tokenhub_chat_only: bool,
 ) -> Result<Vec<String>, BackendError> {
     let value: serde_json::Value = serde_json::from_slice(body)
         .map_err(|_| provider_error("provider model response is invalid JSON"))?;
@@ -756,6 +769,10 @@ fn parse_model_list(
             .and_then(serde_json::Value::as_array)
             .ok_or_else(|| provider_error("provider model response is missing data"))?
             .iter()
+            .filter(|item| {
+                !tokenhub_chat_only
+                    || item.get("status").and_then(serde_json::Value::as_str) == Some("online")
+            })
             .filter(|item| {
                 orcarouter_filter.is_none_or(|filter| {
                     let supports_endpoint = item
@@ -781,6 +798,10 @@ fn parse_model_list(
             .filter_map(|item| item.get("id").and_then(serde_json::Value::as_str))
             .map(str::trim)
             .filter(|name| !name.is_empty())
+            .filter(|name| {
+                !tokenhub_chat_only
+                    || crate::provider_rules::tokenhub_chat_model_policy(name).is_some()
+            })
             .filter(|name| {
                 if !orcarouter_filter.is_some_and(|filter| filter.kind == ProviderKind::Asr) {
                     return true;
@@ -1338,6 +1359,7 @@ mod tests {
             br#"{"data":[{"id":"gpt-z"},{"id":""},{"id":"gpt-a"},{"id":"gpt-z"}]}"#,
             false,
             None,
+            false,
         )
         .unwrap();
         assert_eq!(models, vec!["gpt-a", "gpt-z"]);
@@ -1349,6 +1371,7 @@ mod tests {
             br#"{"models":[{"name":"models/gemini-z","supportedGenerationMethods":["generateContent"]},{"name":"models/embedding","supportedGenerationMethods":["embedContent"]},{"name":"gemini-a"}]}"#,
             true,
             None,
+            false,
         )
         .unwrap();
         assert_eq!(models, vec!["gemini-a", "gemini-z"]);
@@ -1356,11 +1379,87 @@ mod tests {
 
     #[test]
     fn invalid_model_response_is_a_provider_error_without_body() {
-        let error = parse_model_list(br#"{"error":"secret-key"}"#, false, None).unwrap_err();
+        let error = parse_model_list(br#"{"error":"secret-key"}"#, false, None, false).unwrap_err();
         assert_eq!(error.code, BackendErrorCode::Provider);
         assert!(!format!("{error:?}").contains("secret-key"));
     }
 
+    #[tokio::test]
+    async fn tokenhub_catalog_lists_only_online_language_models() {
+        let credentials = Arc::new(InMemoryCredentialStore::default());
+        let channel = create_channel_with_values(
+            &credentials,
+            ChannelKind::Llm,
+            "tencentTokenHub",
+            &[(LLM_API_KEY_ACCOUNT, "fixture-key")],
+        )
+        .await;
+        let transport = Arc::new(FakeProviderTransport::default());
+        transport.push_response(
+            200,
+            br#"{"object":"list","data":[
+                {"id":"hy3","status":"online"},
+                {"id":"hy4-preview","status":"online"},
+                {"id":"hy-mt2-pro","status":"online"},
+                {"id":"hy-role","status":"online"},
+                {"id":"hunyuan-role-latest","status":"online"},
+                {"id":"deepseek/deepseek-v4-flash","status":"online"},
+                {"id":"glm-5.3","status":"online"},
+                {"id":"kimi-k3","status":"online"},
+                {"id":"minimax-m3","status":"online"},
+                {"id":"qwen3.5-flash","status":"online"},
+                {"id":"mimo-v2.5-pro","status":"online"},
+                {"id":"deepseek-v4-pro","status":"pre-offline"},
+                {"id":"glm-future"},
+                {"id":"hy-image-v3","status":"online"},
+                {"id":"hy-video-v1.5","status":"online"},
+                {"id":"HY-3D-3.1","status":"online"},
+                {"id":"hy-asr-3.0-preview","status":"online"},
+                {"id":"minimax-speech-2.8-hd","status":"online"},
+                {"id":"kinfra-text-embedding-4b","status":"online"}
+            ]}"#
+            .to_vec(),
+        );
+        let service = ProviderService::new_with_transport(
+            credentials,
+            Arc::new(crate::TokioTaskSpawner),
+            transport.clone(),
+        );
+
+        let result = service
+            .list_models(ProviderRequest {
+                kind: ProviderKind::Llm,
+                channel_id: Some(channel),
+                thinking_enabled: false,
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(
+            result.models,
+            vec![
+                "deepseek/deepseek-v4-flash",
+                "glm-5.3",
+                "hunyuan-role-latest",
+                "hy-mt2-pro",
+                "hy-role",
+                "hy3",
+                "hy4-preview",
+                "kimi-k3",
+                "mimo-v2.5-pro",
+                "minimax-m3",
+                "qwen3.5-flash",
+            ]
+        );
+        assert_eq!(
+            transport.requests()[0].headers,
+            vec![(
+                "Authorization".to_string(),
+                "Bearer fixture-key".to_string()
+            )]
+        );
+    }
+
     #[tokio::test]
     async fn orcarouter_catalog_uses_core_channel_defaults_and_filters_capabilities() {
         let catalog = r#"{"data":[
diff --git a/openless-all/app/linux-egui/src/credentials.rs b/openless-all/app/linux-egui/src/credentials.rs
index 123e285b..0f506728 100644
--- a/openless-all/app/linux-egui/src/credentials.rs
+++ b/openless-all/app/linux-egui/src/credentials.rs
@@ -5,7 +5,8 @@ use futures_util::future::BoxFuture;
 use openless_core::credentials::{
     ASR_API_KEY_ACCOUNT, ASR_ENDPOINT_ACCOUNT, ASR_MODEL_ACCOUNT, LLM_API_KEY_ACCOUNT,
     LLM_ENDPOINT_ACCOUNT, LLM_MODEL_ACCOUNT, OMNI_API_KEY_ACCOUNT, OMNI_ENDPOINT_ACCOUNT,
-    OMNI_MODEL_ACCOUNT, VOLCENGINE_ACCESS_KEY_ACCOUNT, VOLCENGINE_API_KEY_ACCOUNT,
+    OMNI_MODEL_ACCOUNT, TENCENT_CLOUD_APP_ID_ACCOUNT, TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+    TENCENT_CLOUD_SECRET_KEY_ACCOUNT, VOLCENGINE_ACCESS_KEY_ACCOUNT, VOLCENGINE_API_KEY_ACCOUNT,
     VOLCENGINE_APP_KEY_ACCOUNT, VOLCENGINE_AUTH_MODE_ACCOUNT, VOLCENGINE_RESOURCE_ID_ACCOUNT,
     XFYUN_API_KEY_ACCOUNT, XFYUN_APP_ID_ACCOUNT,
 };
@@ -395,6 +396,21 @@ impl CredentialStore for LinuxCredentialStore {
                     &active_asr_provider,
                     XFYUN_API_KEY_ACCOUNT,
                 ),
+                tencent_cloud_app_id: has(
+                    CredentialNamespace::Asr,
+                    &active_asr_provider,
+                    TENCENT_CLOUD_APP_ID_ACCOUNT,
+                ),
+                tencent_cloud_secret_id: has(
+                    CredentialNamespace::Asr,
+                    &active_asr_provider,
+                    TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+                ),
+                tencent_cloud_secret_key: has(
+                    CredentialNamespace::Asr,
+                    &active_asr_provider,
+                    TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
+                ),
                 llm_api_key: has(
                     CredentialNamespace::Llm,
                     &active_llm_provider,
diff --git a/openless-all/app/linux-egui/src/main.rs b/openless-all/app/linux-egui/src/main.rs
index bb2e9717..19942ce7 100644
--- a/openless-all/app/linux-egui/src/main.rs
+++ b/openless-all/app/linux-egui/src/main.rs
@@ -74,6 +74,7 @@ mod linux_app {
         model: String,
         auth_mode: String,
         resource_id: String,
+        app_id: String,
         // Secret inputs are intentionally write-only. Loading an editor never
         // exposes an existing key into egui state, logs or screenshots.
         primary_secret: String,
@@ -1632,6 +1633,7 @@ mod linux_app {
             }
             openless_core::AuthRequirement::Volcengine => "火山引擎凭据",
             openless_core::AuthRequirement::Xfyun => "讯飞 AppID + API Key",
+            openless_core::AuthRequirement::TencentCloud => "腾讯云 AppID + SecretID + SecretKey",
             openless_core::AuthRequirement::OAuth => "OAuth",
         }
     }
@@ -1711,6 +1713,19 @@ mod linux_app {
             } else {
                 (String::new(), String::new())
             };
+        let app_id = if descriptor.auth_requirement == openless_core::AuthRequirement::TencentCloud
+        {
+            read_provider_value(
+                &backend,
+                kind,
+                &channel.id,
+                openless_core::credentials::TENCENT_CLOUD_APP_ID_ACCOUNT,
+            )
+            .await?
+            .unwrap_or_default()
+        } else {
+            String::new()
+        };
         Ok(ProviderEditor {
             kind,
             name: channel.name.clone(),
@@ -1720,6 +1735,7 @@ mod linux_app {
             model,
             auth_mode,
             resource_id,
+            app_id,
             primary_secret: String::new(),
             secondary_secret: String::new(),
         })
@@ -1777,6 +1793,18 @@ mod linux_app {
                 secret_edit(ui, "AppID", &mut editor.primary_secret);
                 secret_edit(ui, "API Key", &mut editor.secondary_secret);
             }
+            openless_core::AuthRequirement::TencentCloud => {
+                ui.horizontal(|ui| {
+                    ui.label("腾讯云 AppID");
+                    ui.text_edit_singleline(&mut editor.app_id);
+                });
+                secret_edit(ui, "SecretID", &mut editor.primary_secret);
+                secret_edit(ui, "SecretKey", &mut editor.secondary_secret);
+                ui.horizontal(|ui| {
+                    ui.label("Model");
+                    ui.text_edit_singleline(&mut editor.model);
+                });
+            }
             _ => {
                 secret_edit(ui, "API Key（留空表示不修改）", &mut editor.primary_secret);
                 ui.horizontal(|ui| {
@@ -1913,6 +1941,40 @@ mod linux_app {
                 )
                 .await?;
             }
+            openless_core::AuthRequirement::TencentCloud => {
+                write_or_remove_provider_value(
+                    &backend,
+                    editor.kind,
+                    channel_id,
+                    openless_core::credentials::TENCENT_CLOUD_APP_ID_ACCOUNT,
+                    &editor.app_id,
+                )
+                .await?;
+                write_secret_if_entered(
+                    &backend,
+                    editor.kind,
+                    channel_id,
+                    openless_core::credentials::TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+                    &editor.primary_secret,
+                )
+                .await?;
+                write_secret_if_entered(
+                    &backend,
+                    editor.kind,
+                    channel_id,
+                    openless_core::credentials::TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
+                    &editor.secondary_secret,
+                )
+                .await?;
+                write_or_remove_provider_value(
+                    &backend,
+                    editor.kind,
+                    channel_id,
+                    model_account(editor.kind),
+                    &editor.model,
+                )
+                .await?;
+            }
             _ => {
                 write_or_remove_provider_value(
                     &backend,
@@ -1958,6 +2020,11 @@ mod linux_app {
                 openless_core::credentials::XFYUN_APP_ID_ACCOUNT,
                 openless_core::credentials::XFYUN_API_KEY_ACCOUNT,
             ],
+            openless_core::AuthRequirement::TencentCloud => &[
+                openless_core::credentials::TENCENT_CLOUD_APP_ID_ACCOUNT,
+                openless_core::credentials::TENCENT_CLOUD_SECRET_ID_ACCOUNT,
+                openless_core::credentials::TENCENT_CLOUD_SECRET_KEY_ACCOUNT,
+            ],
             _ => &[api_key_account(editor.kind)],
         };
         for account in accounts {
diff --git a/openless-all/app/src-tauri/src/commands/credentials.rs b/openless-all/app/src-tauri/src/commands/credentials.rs
index f9fac199..b75d68fb 100644
--- a/openless-all/app/src-tauri/src/commands/credentials.rs
+++ b/openless-all/app/src-tauri/src/commands/credentials.rs
@@ -535,6 +535,9 @@ fn credential_configuration(
         volcengine_resource_id: configured(&snap.volcengine_resource_id),
         xfyun_app_id: configured(&snap.xfyun_app_id),
         xfyun_api_key: configured(&snap.xfyun_api_key),
+        tencent_cloud_app_id: configured(&snap.tencent_cloud_app_id),
+        tencent_cloud_secret_id: configured(&snap.tencent_cloud_secret_id),
+        tencent_cloud_secret_key: configured(&snap.tencent_cloud_secret_key),
         llm_api_key: configured(&snap.ark_api_key),
         llm_endpoint: llm_endpoint.is_some(),
         llm_endpoint_matches_default: llm_endpoint.is_some_and(|endpoint| {
@@ -799,7 +802,10 @@ fn account_provider_kind(account: CredentialAccount) -> CredentialProviderKind {
         | CredentialAccount::AsrVocabularyId
         | CredentialAccount::AsrAdvancedConfig
         | CredentialAccount::XfyunAppId
-        | CredentialAccount::XfyunApiKey => CredentialProviderKind::Asr,
+        | CredentialAccount::XfyunApiKey
+        | CredentialAccount::TencentCloudAppId
+        | CredentialAccount::TencentCloudSecretId
+        | CredentialAccount::TencentCloudSecretKey => CredentialProviderKind::Asr,
         CredentialAccount::OmniApiKey
         | CredentialAccount::OmniEndpoint
         | CredentialAccount::OmniModel => CredentialProviderKind::Omni,
@@ -831,6 +837,9 @@ fn parse_account(s: &str) -> Result<CredentialAccount, String> {
         "asr.advanced_config" => Ok(CredentialAccount::AsrAdvancedConfig),
         "xfyun.app_id" => Ok(CredentialAccount::XfyunAppId),
         "xfyun.api_key" => Ok(CredentialAccount::XfyunApiKey),
+        "tencent_cloud.app_id" => Ok(CredentialAccount::TencentCloudAppId),
+        "tencent_cloud.secret_id" => Ok(CredentialAccount::TencentCloudSecretId),
+        "tencent_cloud.secret_key" => Ok(CredentialAccount::TencentCloudSecretKey),
         "omni.api_key" => Ok(CredentialAccount::OmniApiKey),
         "omni.endpoint" => Ok(CredentialAccount::OmniEndpoint),
         "omni.model" => Ok(CredentialAccount::OmniModel),
diff --git a/openless-all/app/src-tauri/src/persistence/credentials.rs b/openless-all/app/src-tauri/src/persistence/credentials.rs
index eaa643a4..03d25386 100644
--- a/openless-all/app/src-tauri/src/persistence/credentials.rs
+++ b/openless-all/app/src-tauri/src/persistence/credentials.rs
@@ -349,6 +349,15 @@ struct CredsAsrEntry {
     /// 讯飞实时语音转写 APIKey（接口密钥）。
     #[serde(skip_serializing_if = "Option::is_none")]
     xfyunApiKey: Option<String>,
+    /// 腾讯云账号 AppID（实时语音识别 WebSocket 路径参数）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tencentCloudAppId: Option<String>,
+    /// 腾讯云 API 密钥 SecretID。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tencentCloudSecretId: Option<String>,
+    /// 腾讯云 API 密钥 SecretKey。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tencentCloudSecretKey: Option<String>,
 }
 
 impl CredsAsrEntry {
@@ -378,6 +387,17 @@ impl CredsAsrEntry {
             && self.advancedConfig.as_deref().unwrap_or("").is_empty()
             && self.xfyunAppId.as_deref().unwrap_or("").is_empty()
             && self.xfyunApiKey.as_deref().unwrap_or("").is_empty()
+            && self.tencentCloudAppId.as_deref().unwrap_or("").is_empty()
+            && self
+                .tencentCloudSecretId
+                .as_deref()
+                .unwrap_or("")
+                .is_empty()
+            && self
+                .tencentCloudSecretKey
+                .as_deref()
+                .unwrap_or("")
+                .is_empty()
     }
 }
 
@@ -1611,6 +1631,11 @@ fn lookup_account(root: &CredsRoot, account: CredentialAccount) -> Option<String
         CredentialAccount::AsrAdvancedConfig => asr.and_then(|e| pick(&e.advancedConfig)),
         CredentialAccount::XfyunAppId => asr.and_then(|e| pick(&e.xfyunAppId)),
         CredentialAccount::XfyunApiKey => asr.and_then(|e| pick(&e.xfyunApiKey)),
+        CredentialAccount::TencentCloudAppId => asr.and_then(|e| pick(&e.tencentCloudAppId)),
+        CredentialAccount::TencentCloudSecretId => asr.and_then(|e| pick(&e.tencentCloudSecretId)),
+        CredentialAccount::TencentCloudSecretKey => {
+            asr.and_then(|e| pick(&e.tencentCloudSecretKey))
+        }
         CredentialAccount::OmniApiKey => omni.and_then(|e| pick(&e.apiKey)),
         CredentialAccount::OmniEndpoint => omni.and_then(|e| pick(&e.baseURL)),
         CredentialAccount::OmniModel => omni.and_then(|e| pick(&e.model)),
@@ -1720,6 +1745,18 @@ fn write_account(root: &mut CredsRoot, account: CredentialAccount, value: Option
             let entry = root.providers.asr.entry(asr_id).or_default();
             entry.xfyunApiKey = normalized;
         }
+        CredentialAccount::TencentCloudAppId => {
+            let entry = root.providers.asr.entry(asr_id).or_default();
+            entry.tencentCloudAppId = normalized;
+        }
+        CredentialAccount::TencentCloudSecretId => {
+            let entry = root.providers.asr.entry(asr_id).or_default();
+            entry.tencentCloudSecretId = normalized;
+        }
+        CredentialAccount::TencentCloudSecretKey => {
+            let entry = root.providers.asr.entry(asr_id).or_default();
+            entry.tencentCloudSecretKey = normalized;
+        }
         CredentialAccount::OmniApiKey => {
             let entry = root.omni.providers.entry(omni_id).or_default();
             entry.apiKey = normalized;
@@ -1760,6 +1797,12 @@ pub enum CredentialAccount {
     XfyunAppId,
     /// 讯飞实时语音转写 APIKey。
     XfyunApiKey,
+    /// 腾讯云账号 AppID。
+    TencentCloudAppId,
+    /// 腾讯云 API 密钥 SecretID。
+    TencentCloudSecretId,
+    /// 腾讯云 API 密钥 SecretKey。
+    TencentCloudSecretKey,
     /// 多模态（Omni）模型的 API Key。仅多模态管线读取。
     OmniApiKey,
     /// 多模态（Omni）模型的 Base URL。
@@ -1789,6 +1832,9 @@ impl CredentialAccount {
             CredentialAccount::AsrAdvancedConfig => "asr.advanced_config",
             CredentialAccount::XfyunAppId => "xfyun.app_id",
             CredentialAccount::XfyunApiKey => "xfyun.api_key",
+            CredentialAccount::TencentCloudAppId => "tencent_cloud.app_id",
+            CredentialAccount::TencentCloudSecretId => "tencent_cloud.secret_id",
+            CredentialAccount::TencentCloudSecretKey => "tencent_cloud.secret_key",
             CredentialAccount::OmniApiKey => "omni.api_key",
             CredentialAccount::OmniEndpoint => "omni.endpoint",
             CredentialAccount::OmniModel => "omni.model",
@@ -1812,6 +1858,9 @@ impl CredentialAccount {
             CredentialAccount::AsrAdvancedConfig,
             CredentialAccount::XfyunAppId,
             CredentialAccount::XfyunApiKey,
+            CredentialAccount::TencentCloudAppId,
+            CredentialAccount::TencentCloudSecretId,
+            CredentialAccount::TencentCloudSecretKey,
             CredentialAccount::OmniApiKey,
             CredentialAccount::OmniEndpoint,
             CredentialAccount::OmniModel,
@@ -1832,6 +1881,9 @@ pub struct CredentialsSnapshot {
     pub asr_model: Option<String>,
     pub xfyun_app_id: Option<String>,
     pub xfyun_api_key: Option<String>,
+    pub tencent_cloud_app_id: Option<String>,
+    pub tencent_cloud_secret_id: Option<String>,
+    pub tencent_cloud_secret_key: Option<String>,
     pub ark_api_key: Option<String>,
     pub ark_model_id: Option<String>,
     pub ark_endpoint: Option<String>,
@@ -1853,6 +1905,9 @@ fn credentials_snapshot(root: &CredsRoot, include_omni: bool) -> CredentialsSnap
         asr_model: lookup_account(root, CredentialAccount::AsrModel),
         xfyun_app_id: lookup_account(root, CredentialAccount::XfyunAppId),
         xfyun_api_key: lookup_account(root, CredentialAccount::XfyunApiKey),
+        tencent_cloud_app_id: lookup_account(root, CredentialAccount::TencentCloudAppId),
+        tencent_cloud_secret_id: lookup_account(root, CredentialAccount::TencentCloudSecretId),
+        tencent_cloud_secret_key: lookup_account(root, CredentialAccount::TencentCloudSecretKey),
         ark_api_key: lookup_account(root, CredentialAccount::ArkApiKey),
         ark_model_id: lookup_account(root, CredentialAccount::ArkModelId),
         ark_endpoint: lookup_account(root, CredentialAccount::ArkEndpoint),
diff --git a/openless-all/app/src/i18n/en.ts b/openless-all/app/src/i18n/en.ts
index 43e30e48..6d25f7c8 100644
--- a/openless-all/app/src/i18n/en.ts
+++ b/openless-all/app/src/i18n/en.ts
@@ -1012,6 +1012,7 @@ export const en: typeof zhCN = {
         minimax: 'MiniMax (M3)',
         stepfun: 'StepFun',
         opencode: 'OpenCode Zen',
+        tencentTokenHub: 'Tencent Cloud TokenHub',
         customChatCompletions: "Custom · Chat Completions",
         customResponses: "Custom · Responses",
         customMessages: "Custom · Messages",
@@ -1030,6 +1031,7 @@ export const en: typeof zhCN = {
         asrOpenAiCompatible: 'Custom OpenAI-compatible',
         asrXiaomiMimo: 'Xiaomi MiMo ASR',
         asrIflytek: 'iFlytek Realtime ASR',
+        asrTencentCloud: 'Tencent Cloud Hunyuan Realtime ASR',
         asrElevenLabs: 'ElevenLabs Scribe',
         asrSherpaOnnxLocal: 'Local sherpa-onnx (experimental)',
         asrFoundryLocalWhisper: 'Local Whisper (Foundry Local)',
@@ -1063,6 +1065,11 @@ export const en: typeof zhCN = {
       xfyunAppIdLabel: 'AppID',
       xfyunApiKeyLabel: 'API Key',
       xfyunNote: 'Get AppID and API Key from the iFlytek Open Platform "Realtime ASR" service page. Audio is 16 kHz / 16-bit / mono PCM; the standard API has no hotword parameter (configure personalized hotwords in the iFlytek console), and the language defaults to Mandarin Chinese.',
+      tencentCloudAppIdLabel: 'Tencent Cloud AppID',
+      tencentCloudSecretIdLabel: 'SecretID',
+      tencentCloudSecretKeyLabel: 'SecretKey',
+      tencentCloudNote: 'Uses Tencent Cloud Speech Recognition API credentials. The default Hy-ASR-3.0-preview supports Chinese, English, and 20 dialects; Preview accepts only mono 16 kHz PCM up to 60 seconds and does not yet support context or hotword boosting.',
+      tencentTokenHubNote: 'Only online language models are listed. Some models always use reasoning; turning reasoning off keeps that model\'s fixed behavior.',
       localAsrActiveNotice: 'Local ASR ({{name}}) is currently active. Switch or disable it from the Advanced tab.',
       localAsrTakeoverHint: 'Once "{{name}}" is enabled, the ASR provider will be taken over.',
       asrProviderTakenOver: 'A local engine is active. Pick another provider in the dropdown above to switch (the local engine stops automatically); manage local models under Services → Local models.',
diff --git a/openless-all/app/src/i18n/ja.ts b/openless-all/app/src/i18n/ja.ts
index 68dd9431..36a57b13 100644
--- a/openless-all/app/src/i18n/ja.ts
+++ b/openless-all/app/src/i18n/ja.ts
@@ -1014,6 +1014,7 @@ export const ja: typeof zhCN = {
         minimax: 'MiniMax（M3）',
         stepfun: 'StepFun（階躍星辰）',
         opencode: 'OpenCode Zen',
+        tencentTokenHub: 'Tencent Cloud TokenHub',
         customChatCompletions: "カスタム · Chat Completions",
         customResponses: "カスタム · Responses",
         customMessages: "カスタム · Messages",
@@ -1032,6 +1033,7 @@ export const ja: typeof zhCN = {
         asrOpenAiCompatible: 'カスタム OpenAI 互換',
         asrXiaomiMimo: 'Xiaomi MiMo ASR',
         asrIflytek: 'iFlytek リアルタイム音声認識',
+        asrTencentCloud: 'Tencent Cloud Hunyuan リアルタイム ASR',
         asrElevenLabs: 'ElevenLabs Scribe',
         asrSherpaOnnxLocal: 'ローカル sherpa-onnx（実験的）',
         asrFoundryLocalWhisper: 'ローカル Whisper（Foundry Local）',
@@ -1065,6 +1067,11 @@ export const ja: typeof zhCN = {
       xfyunAppIdLabel: 'AppID',
       xfyunApiKeyLabel: 'API Key',
       xfyunNote: 'iFlytek オープンプラットフォームの「リアルタイム音声認識」サービスページで AppID と API Key を取得します。音声は 16kHz / 16bit / モノラル PCM。標準版 API にホットワード引数はありません（iFlytek コンソールで個別ホットワードを設定）。言語はデフォルトで中国語（普通話）です。',
+      tencentCloudAppIdLabel: 'Tencent Cloud AppID',
+      tencentCloudSecretIdLabel: 'SecretID',
+      tencentCloudSecretKeyLabel: 'SecretKey',
+      tencentCloudNote: 'Tencent Cloud 音声認識 API の認証情報を使用します。既定の Hy-ASR-3.0-preview は中国語・英語・20 方言に対応します。Preview は 60 秒以内の 16kHz モノラル PCM のみ対応し、コンテキストとホットワード強化は未対応です。',
+      tencentTokenHubNote: '現在オンラインの言語モデルのみを表示します。一部のモデルは常に思考を使用し、思考をオフにしてもモデル固有の動作を維持します。',
       localAsrActiveNotice: '現在「{{name}}」を使用中。「詳細設定」タブから切り替えまたは無効化できます。',
       localAsrTakeoverHint: '「{{name}}」を有効化すると ASR プロバイダーが引き継がれます。',
       asrProviderTakenOver: 'ローカルエンジンを使用中です。上のドロップダウンで別のプロバイダーを選ぶと切り替えられます（ローカルエンジンは自動的に停止します）。ローカルモデルは「サービス → ローカルモデル」で管理します。',
diff --git a/openless-all/app/src/i18n/ko.ts b/openless-all/app/src/i18n/ko.ts
index 8ffe7000..09fd69a9 100644
--- a/openless-all/app/src/i18n/ko.ts
+++ b/openless-all/app/src/i18n/ko.ts
@@ -1014,6 +1014,7 @@ export const ko: typeof zhCN = {
         minimax: 'MiniMax (M3)',
         stepfun: 'StepFun',
         opencode: 'OpenCode Zen',
+        tencentTokenHub: 'Tencent Cloud TokenHub',
         customChatCompletions: "사용자 지정 · Chat Completions",
         customResponses: "사용자 지정 · Responses",
         customMessages: "사용자 지정 · Messages",
@@ -1032,6 +1033,7 @@ export const ko: typeof zhCN = {
         asrOpenAiCompatible: '커스텀 OpenAI 호환',
         asrXiaomiMimo: 'Xiaomi MiMo ASR',
         asrIflytek: 'iFlytek 실시간 음성 인식',
+        asrTencentCloud: 'Tencent Cloud Hunyuan 실시간 ASR',
         asrElevenLabs: 'ElevenLabs Scribe',
         asrSherpaOnnxLocal: '로컬 sherpa-onnx(실험적)',
         asrFoundryLocalWhisper: '로컬 Whisper(Foundry Local)',
@@ -1065,6 +1067,11 @@ export const ko: typeof zhCN = {
       xfyunAppIdLabel: 'AppID',
       xfyunApiKeyLabel: 'API Key',
       xfyunNote: 'iFlytek 오픈 플랫폼 "실시간 음성 인식" 서비스 페이지에서 AppID와 API Key를 가져옵니다. 오디오는 16kHz/16bit/모노 PCM입니다. 표준 API에는 핫워드 매개변수가 없으며(iFlytek 콘솔에서 개별 핫워드 설정), 언어는 기본적으로 중국어(보통화)입니다.',
+      tencentCloudAppIdLabel: 'Tencent Cloud AppID',
+      tencentCloudSecretIdLabel: 'SecretID',
+      tencentCloudSecretKeyLabel: 'SecretKey',
+      tencentCloudNote: 'Tencent Cloud 음성 인식 API 자격 증명을 사용합니다. 기본 Hy-ASR-3.0-preview는 중국어·영어·20개 방언을 지원합니다. Preview는 60초 이내의 16kHz 모노 PCM만 지원하며, 컨텍스트와 핫워드 강화는 아직 지원하지 않습니다.',
+      tencentTokenHubNote: '현재 온라인인 언어 모델만 표시합니다. 일부 모델은 항상 추론을 사용하며, 추론을 꺼도 해당 모델의 고정 동작을 유지합니다.',
       localAsrActiveNotice: '현재 "{{name}}" 사용 중. "고급" 탭에서 전환 또는 비활성화할 수 있습니다.',
       localAsrTakeoverHint: '"{{name}}" 활성화 시 ASR 프로바이더가 인수됩니다.',
       asrProviderTakenOver: '현재 로컬 엔진을 사용 중입니다. 위의 드롭다운에서 다른 공급자를 선택하면 전환됩니다(로컬 엔진은 자동으로 중지됨). 로컬 모델은 「서비스 → 로컬 모델」에서 관리합니다.',
diff --git a/openless-all/app/src/i18n/zh-CN.ts b/openless-all/app/src/i18n/zh-CN.ts
index 22496dcc..b49e8e2b 100644
--- a/openless-all/app/src/i18n/zh-CN.ts
+++ b/openless-all/app/src/i18n/zh-CN.ts
@@ -1010,6 +1010,7 @@ export const zhCN = {
         minimax: 'MiniMax（M3）',
         stepfun: 'StepFun（阶跃星辰）',
         opencode: 'OpenCode Zen',
+        tencentTokenHub: '腾讯云 TokenHub',
         customChatCompletions: "自定义 · Chat Completions",
         customResponses: "自定义 · Responses",
         customMessages: "自定义 · Messages",
@@ -1028,6 +1029,7 @@ export const zhCN = {
         asrOpenAiCompatible: '自定义 OpenAI 兼容',
         asrXiaomiMimo: '小米 MiMo ASR',
         asrIflytek: '讯飞实时语音转写',
+        asrTencentCloud: '腾讯云混元实时 ASR',
         asrElevenLabs: 'ElevenLabs Scribe',
         asrSherpaOnnxLocal: '本地 sherpa-onnx（实验性）',
         asrFoundryLocalWhisper: '本地 Whisper（Foundry Local）',
@@ -1061,6 +1063,11 @@ export const zhCN = {
       xfyunAppIdLabel: 'AppID',
       xfyunApiKeyLabel: 'API Key',
       xfyunNote: '在讯飞开放平台「实时语音转写」服务页获取 AppID 与 API Key。音频为 16kHz/16bit/单声道 PCM；标准版接口暂不支持热词参数（可在讯飞控制台配置个性化热词），语种默认中文普通话。',
+      tencentCloudAppIdLabel: '腾讯云 AppID',
+      tencentCloudSecretIdLabel: 'SecretID',
+      tencentCloudSecretKeyLabel: 'SecretKey',
+      tencentCloudNote: '使用腾讯云「语音识别」服务的 API 密钥。默认 Hy-ASR-3.0-preview 支持中英与 20 种方言；Preview 仅支持 60 秒以内的 16kHz 单声道 PCM，暂不支持上下文或热词增强。',
+      tencentTokenHubNote: '仅显示当前在线的语言模型。部分模型始终启用思考；关闭思考开关时将沿用该模型的固定行为。',
       localAsrActiveNotice: '当前已启用「{{name}}」，可在「高级」中切换或禁用。',
       localAsrTakeoverHint: '启动「{{name}}」后，ASR 提供商将被接管。',
       asrProviderTakenOver: '当前用的是本地引擎，在上方下拉直接选其它供应商即可切换（本地引擎会自动停用）；本地模型在「服务 → 本地模型」里管理。',
diff --git a/openless-all/app/src/i18n/zh-TW.ts b/openless-all/app/src/i18n/zh-TW.ts
index 71b4cacd..3d60d311 100644
--- a/openless-all/app/src/i18n/zh-TW.ts
+++ b/openless-all/app/src/i18n/zh-TW.ts
@@ -1012,6 +1012,7 @@ export const zhTW: typeof zhCN = {
         minimax: 'MiniMax（M3）',
         stepfun: 'StepFun（階躍星辰）',
         opencode: 'OpenCode Zen',
+        tencentTokenHub: '騰訊雲 TokenHub',
         customChatCompletions: "自訂 · Chat Completions",
         customResponses: "自訂 · Responses",
         customMessages: "自訂 · Messages",
@@ -1030,6 +1031,7 @@ export const zhTW: typeof zhCN = {
         asrOpenAiCompatible: '自訂 OpenAI 相容',
         asrXiaomiMimo: '小米 MiMo ASR',
         asrIflytek: '訊飛即時語音轉寫',
+        asrTencentCloud: '騰訊雲混元即時 ASR',
         asrElevenLabs: 'ElevenLabs Scribe',
         asrSherpaOnnxLocal: '本地 sherpa-onnx（實驗性）',
         asrFoundryLocalWhisper: '本地 Whisper（Foundry Local）',
@@ -1063,6 +1065,11 @@ export const zhTW: typeof zhCN = {
       xfyunAppIdLabel: 'AppID',
       xfyunApiKeyLabel: 'API Key',
       xfyunNote: '在訊飛開放平台「即時語音轉寫」服務頁取得 AppID 與 API Key。音訊為 16kHz/16bit/單聲道 PCM；標準版介面暫不支援熱詞參數（可在訊飛控制台設定個人化熱詞），語種預設中文普通話。',
+      tencentCloudAppIdLabel: '騰訊雲 AppID',
+      tencentCloudSecretIdLabel: 'SecretID',
+      tencentCloudSecretKeyLabel: 'SecretKey',
+      tencentCloudNote: '使用騰訊雲「語音辨識」服務的 API 金鑰。預設 Hy-ASR-3.0-preview 支援中英與 20 種方言；Preview 僅支援 60 秒內的 16kHz 單聲道 PCM，暫不支援上下文或熱詞增強。',
+      tencentTokenHubNote: '僅顯示目前在線的語言模型。部分模型始終啟用思考；關閉思考開關時將沿用該模型的固定行為。',
       localAsrActiveNotice: '當前已啓用「{{name}}」，可在「高級」中切換或停用。',
       localAsrTakeoverHint: '啓動「{{name}}」後，ASR 提供商將被接管。',
       asrProviderTakenOver: '目前使用的是本地引擎，在上方下拉直接選其他供應商即可切換（本地引擎會自動停用）；本地模型在「服務 → 本地模型」裡管理。',
diff --git a/openless-all/app/src/lib/ipc/mock-provider-descriptors.json b/openless-all/app/src/lib/ipc/mock-provider-descriptors.json
index f991e8fb..e5c15e31 100644
--- a/openless-all/app/src/lib/ipc/mock-provider-descriptors.json
+++ b/openless-all/app/src/lib/ipc/mock-provider-descriptors.json
@@ -15,6 +15,7 @@
   {"kind":"llm","providerType":"minimax","labelKey":"minimax","defaultEndpoint":"https://api.minimaxi.com/v1","defaultModel":"MiniMax-M3","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
   {"kind":"llm","providerType":"stepfun","labelKey":"stepfun","defaultEndpoint":"https://api.stepfun.com/v1","defaultModel":"step-1o-turbo-vision","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
   {"kind":"llm","providerType":"opencode","labelKey":"opencode","defaultEndpoint":"https://opencode.ai/zen/v1","defaultModel":"deepseek-v4-flash","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
+  {"kind":"llm","providerType":"tencentTokenHub","labelKey":"tencentTokenHub","defaultEndpoint":"https://tokenhub.tencentmaas.com/v1","defaultModel":"hy3","authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"llm","providerType":"custom","labelKey":"customChatCompletions","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"chat_completions","supportedRequestFormats":["chat_completions","responses","messages"]},
   {"kind":"llm","providerType":"custom_responses","labelKey":"customResponses","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"responses","supportedRequestFormats":["chat_completions","responses","messages"]},
   {"kind":"llm","providerType":"custom_messages","labelKey":"customMessages","defaultEndpoint":null,"defaultModel":null,"authRequirement":"api_key_unless_custom_endpoint","validationProbe":"llm_text","staticModels":[],"defaultRequestFormat":"messages","supportedRequestFormats":["chat_completions","responses","messages"]},
@@ -34,6 +35,7 @@
   {"kind":"asr","providerType":"openai-compatible","labelKey":"asrOpenAiCompatible","defaultEndpoint":null,"defaultModel":null,"authRequirement":"endpoint_model_optional_api_key","validationProbe":"asr_silence","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"asr","providerType":"xiaomi-mimo-asr","labelKey":"asrXiaomiMimo","defaultEndpoint":"https://api.xiaomimimo.com/v1","defaultModel":"mimo-v2.5-asr","authRequirement":"api_key","validationProbe":"asr_silence","staticModels":["mimo-v2.5-asr"],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"asr","providerType":"iflytek","labelKey":"asrIflytek","defaultEndpoint":null,"defaultModel":null,"authRequirement":"xfyun","validationProbe":"asr_silence_allows_no_final","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
+  {"kind":"asr","providerType":"tencent-cloud","labelKey":"asrTencentCloud","defaultEndpoint":null,"defaultModel":"Hy-ASR-3.0-preview","authRequirement":"tencent_cloud","validationProbe":"asr_silence_allows_no_final","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"asr","providerType":"foundry-local-whisper","labelKey":"asrFoundryLocalWhisper","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"asr","providerType":"local-whisper","labelKey":"asrLocalWhisper","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
   {"kind":"asr","providerType":"sherpa-onnx-local","labelKey":"asrSherpaOnnxLocal","defaultEndpoint":null,"defaultModel":null,"authRequirement":"none","validationProbe":"unsupported","staticModels":[],"defaultRequestFormat":null,"supportedRequestFormats":[]},
diff --git a/openless-all/app/src/lib/ipc/providers.ts b/openless-all/app/src/lib/ipc/providers.ts
index f536d8ce..2011e04e 100644
--- a/openless-all/app/src/lib/ipc/providers.ts
+++ b/openless-all/app/src/lib/ipc/providers.ts
@@ -11,6 +11,7 @@ export type AuthRequirement =
   | 'api_key_unless_custom_endpoint'
   | 'volcengine'
   | 'xfyun'
+  | 'tencent_cloud'
   | 'o_auth'
 
 export interface ProviderDescriptor {
diff --git a/openless-all/app/src/pages/Overview.tsx b/openless-all/app/src/pages/Overview.tsx
index 4c499e52..c0370edd 100644
--- a/openless-all/app/src/pages/Overview.tsx
+++ b/openless-all/app/src/pages/Overview.tsx
@@ -54,6 +54,7 @@ const LLM_NAME_KEY_BY_ID: Record<string, string> = {
   alibabaCoding: 'alibabaCoding',
   codingPlanX: 'codingPlanX',
   opencode: 'opencode',
+  tencentTokenHub: 'tencentTokenHub',
   custom: 'custom',
 };
 
diff --git a/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts b/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
index f36e915c..b2aad90a 100644
--- a/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
+++ b/openless-all/app/src/pages/settings/LlmProtocolFields.test.ts
@@ -23,6 +23,10 @@ const opencode = presets.find(p => p.id === 'opencode');
 assert(opencode?.defaultRequestFormat === 'chat_completions'
   && opencode.defaultEndpoint === 'https://opencode.ai/zen/v1'
   && opencode.defaultModel === 'deepseek-v4-flash', 'OpenCode browser preset must retain Core defaults');
+const tokenhub = presets.find(p => p.id === 'tencentTokenHub');
+assert(tokenhub?.defaultRequestFormat === null
+  && tokenhub.supportedRequestFormats?.length === 0,
+  'TokenHub browser preset must stay fixed to Chat Completions');
 assert(presets.find(p => p.id === 'custom_messages')?.defaultRequestFormat === 'messages', 'Picker must retain Core protocol defaults');
 for (const preset of presets) {
   assert(preset.supportedRequestFormats?.length === (preset.defaultRequestFormat ? 3 : 0), 'Picker must retain Core protocol capabilities');
diff --git a/openless-all/app/src/pages/settings/ProvidersSection.test.ts b/openless-all/app/src/pages/settings/ProvidersSection.test.ts
index a89e8a41..a2bd1c47 100644
--- a/openless-all/app/src/pages/settings/ProvidersSection.test.ts
+++ b/openless-all/app/src/pages/settings/ProvidersSection.test.ts
@@ -7,6 +7,12 @@ const atlascloudPreset = LLM_LABELS.find(p => p.id === 'atlascloud');
 if (LLM_LABELS.find(p => p.id === 'opencode')?.nameKey !== 'opencode') {
   throw new Error('OpenCode LLM label is missing');
 }
+if (LLM_LABELS.find(p => p.id === 'tencentTokenHub')?.nameKey !== 'tencentTokenHub') {
+  throw new Error('Tencent Cloud TokenHub LLM label is missing');
+}
+if (ASR_LABELS.find(p => p.id === 'tencent-cloud')?.nameKey !== 'asrTencentCloud') {
+  throw new Error('Tencent Cloud ASR label is missing');
+}
 
 if (!atlascloudPreset) {
   throw new Error('Atlas Cloud LLM preset is missing');
diff --git a/openless-all/app/src/pages/settings/ProvidersSection.tsx b/openless-all/app/src/pages/settings/ProvidersSection.tsx
index 514081a5..598013ac 100644
--- a/openless-all/app/src/pages/settings/ProvidersSection.tsx
+++ b/openless-all/app/src/pages/settings/ProvidersSection.tsx
@@ -94,7 +94,7 @@ export const LLM_LABELS = [
   ['codex_oauth', 'codexOAuth'], ['mimo', 'mimo'], ['cometapi', 'cometapi'],
   ['openrouterFree', 'openrouterFree'], ['orcarouter', 'orcarouter'], ['alibabaCoding', 'alibabaCoding'],
   ['codingPlanX', 'codingPlanX'], ['minimax', 'minimax'], ['stepfun', 'stepfun'],
-  ['opencode', 'opencode'],
+  ['opencode', 'opencode'], ['tencentTokenHub', 'tencentTokenHub'],
   ['custom', 'customChatCompletions'], ['custom_responses', 'customResponses'], ['custom_messages', 'customMessages'],
 ].map(([id, nameKey]) => ({ id, nameKey })) as readonly { id: string; nameKey: string }[];
 
@@ -280,6 +280,11 @@ export function ChannelCredentialFields({
         <ProviderTools key={`${configRevision}:${form?.revision}`} disabled={Object.values(blockedFields).some(Boolean) || (!!descriptor.supportedRequestFormats?.length && blockedFields.protocol === undefined)} kind="llm" provider={channelId}
           onTested={onTested}
           onUserMutation={onUserMutation} />
+        {providerType === 'tencentTokenHub' && (
+          <div style={{ marginTop: 2, fontSize: 11.5, color: 'var(--ol-ink-4)', lineHeight: 1.6 }}>
+            {t('settings.providers.tencentTokenHubNote')}
+          </div>
+        )}
       </>
     );
   }
@@ -365,6 +370,29 @@ export function ChannelCredentialFields({
     );
   }
 
+  if (descriptor?.authRequirement === 'tencent_cloud') {
+    return (
+      <>
+        <CredentialField key={`${channelId}:app_id`} label={t('settings.providers.tencentCloudAppIdLabel')}
+          account="tencent_cloud.app_id" provider={channelId} mono onUserMutation={onUserMutation} />
+        <CredentialField key={`${channelId}:secret_id`} label={t('settings.providers.tencentCloudSecretIdLabel')}
+          account="tencent_cloud.secret_id" provider={channelId} mono mask onUserMutation={onUserMutation} />
+        <CredentialField key={`${channelId}:secret_key`} label={t('settings.providers.tencentCloudSecretKeyLabel')}
+          account="tencent_cloud.secret_key" provider={channelId} mono mask onUserMutation={onUserMutation} />
+        <CredentialField key={`${channelId}:model`} label={t('settings.providers.modelLabel')}
+          account="asr.model" provider={channelId} mono
+          placeholder={descriptor?.defaultModel || 'Hy-ASR-3.0-preview'}
+          defaultValue={descriptor?.defaultModel || 'Hy-ASR-3.0-preview'} onUserMutation={onUserMutation} />
+        <div style={{ marginTop: 2, fontSize: 11.5, color: 'var(--ol-ink-4)', lineHeight: 1.6 }}>
+          {t('settings.providers.tencentCloudNote')}
+        </div>
+        <ProviderTools key={form?.revision} disabled={Object.values(form?.blocked ?? {}).some(Boolean)} kind="asr" provider={channelId}
+          onTested={onTested}
+          onUserMutation={onUserMutation} />
+      </>
+    );
+  }
+
   // 本地引擎（qwen3 / sherpa / foundry / Apple 语音）没有 key 与地址；模型的下载与
   // 切换仍由「高级 → 本地模型」里的 <LocalAsr embedded /> 负责，这里只说明一句。
   if (descriptor?.authRequirement === 'none') {
diff --git a/openless-all/app/src/pages/settings/shared.tsx b/openless-all/app/src/pages/settings/shared.tsx
index 7a191f8a..55b79094 100644
--- a/openless-all/app/src/pages/settings/shared.tsx
+++ b/openless-all/app/src/pages/settings/shared.tsx
@@ -228,6 +228,7 @@ export const ASR_LABELS = [
   { id: 'openai-compatible', nameKey: 'asrOpenAiCompatible' },
   { id: 'xiaomi-mimo-asr', nameKey: 'asrXiaomiMimo' },
   { id: 'iflytek', nameKey: 'asrIflytek' },
+  { id: 'tencent-cloud', nameKey: 'asrTencentCloud' },
   { id: 'foundry-local-whisper', nameKey: 'asrFoundryLocalWhisper' },
   { id: 'local-whisper', nameKey: 'asrLocalWhisper' },
   { id: 'sherpa-onnx-local', nameKey: 'asrSherpaOnnxLocal' },

From 758409146428c922c042673b511bbc188cbda54d Mon Sep 17 00:00:00 2001
From: Eclock2000 <127169032+Eclock2000@users.noreply.github.com>
Date: Wed, 9 Sep 2026 14:00:30 -0400
Subject: [PATCH 3/4] =?UTF-8?q?fix(hotkeys):=20support=20F13=E2=80=93F20?=
 =?UTF-8?q?=20and=20the=20native=20Mac=20Dictation=20key=20(#1040)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(hotkeys): 支持专用 F20 与 Mac 原生听写键

* fix(hotkeys): make the Mac Dictation key a single trigger option

* refactor(hotkeys): remove optional Dictation key status UI

* fix(hotkeys): re-enable disabled Mac Dictation event tap

---------

Co-authored-by: Chris233 <h-chris233@outlook.com>
---
 .../openless-core/src/shortcut_types.rs       |  21 +-
 .../app/src-tauri/src/combo_hotkey.rs         |  49 +++
 .../app/src-tauri/src/commands/hotkeys.rs     |  39 +--
 .../app/src-tauri/src/commands/settings.rs    |  36 +++
 openless-all/app/src-tauri/src/coordinator.rs |  29 +-
 .../src/coordinator/native_dictation_key.rs   | 108 +++++++
 openless-all/app/src-tauri/src/lib.rs         |   2 +
 .../app/src-tauri/src/macos_dictation_key.rs  | 288 ++++++++++++++++++
 .../app/src-tauri/src/shortcut_binding.rs     |  55 ++++
 .../app/src-tauri/src/side_aware_combo.rs     | 154 ++++++++--
 .../app/src/components/ShortcutRecorder.tsx   |  41 ++-
 openless-all/app/src/i18n/en.ts               |   8 +
 openless-all/app/src/i18n/zh-CN.ts            |   8 +
 openless-all/app/src/i18n/zh-TW.ts            |   8 +
 openless-all/app/src/lib/hotkey.ts            |   1 +
 .../app/src/lib/hotkeyRecorder.test.ts        |   9 +
 openless-all/app/src/lib/hotkeyRecorder.ts    |   8 +
 .../pages/settings/RecordingInputSection.tsx  |   5 +-
 .../src/pages/settings/ShortcutsSection.tsx   |   5 +-
 19 files changed, 821 insertions(+), 53 deletions(-)
 create mode 100644 openless-all/app/src-tauri/src/coordinator/native_dictation_key.rs
 create mode 100644 openless-all/app/src-tauri/src/macos_dictation_key.rs

diff --git a/openless-all/app/crates/openless-core/src/shortcut_types.rs b/openless-all/app/crates/openless-core/src/shortcut_types.rs
index c870db84..f56c66d6 100644
--- a/openless-all/app/crates/openless-core/src/shortcut_types.rs
+++ b/openless-all/app/crates/openless-core/src/shortcut_types.rs
@@ -51,6 +51,9 @@ pub const SIDE_SPECIFIC_NON_DICTATION_MSG: &str =
     "Side-specific modifier shortcuts are only supported for dictation start/stop.";
 
 pub fn reject_side_specific_non_dictation(binding: &ShortcutBinding) -> Result<(), String> {
+    if binding.primary == "MacDictationKey" {
+        return Err("The Mac Dictation key is only supported for dictation start/stop.".into());
+    }
     if binding_requires_side_aware_hook(binding) {
         return Err(SIDE_SPECIFIC_NON_DICTATION_MSG.to_string());
     }
@@ -193,6 +196,10 @@ pub fn binding_from_legacy_trigger(trigger: HotkeyTrigger) -> ShortcutBinding {
 }
 
 pub fn validate_shortcut_binding(binding: &ShortcutBinding) -> Result<(), ShortcutBindingError> {
+    #[cfg(target_os = "macos")]
+    if binding.primary == "MacDictationKey" && binding.modifiers.is_empty() {
+        return Ok(());
+    }
     if legacy_modifier_trigger(binding).is_some() {
         return Ok(());
     }
@@ -278,6 +285,14 @@ fn validate_primary(raw: &str) -> Result<(), ShortcutBindingError> {
             | "F10"
             | "F11"
             | "F12"
+            | "F13"
+            | "F14"
+            | "F15"
+            | "F16"
+            | "F17"
+            | "F18"
+            | "F19"
+            | "F20"
     ) {
         return Ok(());
     }
@@ -785,7 +800,11 @@ mod tests {
     fn validates_shared_shortcut_grammar_without_a_native_hotkey_crate() {
         assert!(validate_shortcut_binding(&combo("D", &["cmd", "shift"])).is_ok());
         assert!(validate_shortcut_binding(&combo("?", &["shift"])).is_ok());
-        assert!(validate_shortcut_binding(&combo("F12", &[])).is_ok());
+        for number in 1..=20 {
+            assert!(validate_shortcut_binding(&combo(&format!("F{number}"), &[])).is_ok());
+        }
+        assert!(validate_shortcut_binding(&combo(" f20 ", &[])).is_ok());
+        assert!(validate_shortcut_binding(&combo("F21", &[])).is_err());
         assert_eq!(
             validate_shortcut_binding(&combo("D", &["hyper"])),
             Err(ShortcutBindingError::UnsupportedModifier("hyper".into()))
diff --git a/openless-all/app/src-tauri/src/combo_hotkey.rs b/openless-all/app/src-tauri/src/combo_hotkey.rs
index 6792160e..e2daaba0 100644
--- a/openless-all/app/src-tauri/src/combo_hotkey.rs
+++ b/openless-all/app/src-tauri/src/combo_hotkey.rs
@@ -50,6 +50,8 @@ pub struct ComboHotkeyMonitor {
 
 struct Inner {
     registered: Mutex<Option<RegisteredHotkey>>,
+    #[cfg(target_os = "macos")]
+    native_dictation: Mutex<Option<crate::macos_dictation_key::Monitor>>,
     tx: Sender<ComboHotkeyEvent>,
 }
 
@@ -67,6 +69,18 @@ impl ComboHotkeyMonitor {
         binding: ShortcutBinding,
         tx: Sender<ComboHotkeyEvent>,
     ) -> Result<Self, ComboHotkeyError> {
+        #[cfg(target_os = "macos")]
+        if is_native_dictation(&binding) {
+            let native = crate::macos_dictation_key::Monitor::start(tx.clone())
+                .map_err(ComboHotkeyError::RegisterFailed)?;
+            return Ok(Self {
+                inner: Arc::new(Inner {
+                    registered: Mutex::new(None),
+                    native_dictation: Mutex::new(Some(native)),
+                    tx,
+                }),
+            });
+        }
         let runtime = GlobalHotkeyRuntime::shared()
             .map_err(|e| ComboHotkeyError::ManagerInitFailed(e.to_string()))?;
 
@@ -87,6 +101,8 @@ impl ComboHotkeyMonitor {
         Ok(Self {
             inner: Arc::new(Inner {
                 registered: Mutex::new(Some(registered)),
+                #[cfg(target_os = "macos")]
+                native_dictation: Mutex::new(None),
                 tx,
             }),
         })
@@ -94,6 +110,17 @@ impl ComboHotkeyMonitor {
 
     /// 替换当前注册的组合键（用户在设置里改了组合键时）。
     pub fn update_binding(&self, binding: ShortcutBinding) -> Result<(), ComboHotkeyError> {
+        #[cfg(target_os = "macos")]
+        if is_native_dictation(&binding) {
+            if self.native_dictation_active() {
+                return Ok(());
+            }
+            let native = crate::macos_dictation_key::Monitor::start(self.inner.tx.clone())
+                .map_err(ComboHotkeyError::RegisterFailed)?;
+            *self.inner.native_dictation.lock() = Some(native);
+            self.inner.registered.lock().take();
+            return Ok(());
+        }
         let next = parse_binding(&binding)?;
         let mut current = self.inner.registered.lock();
         if let Some(prev) = current.as_ref() {
@@ -115,13 +142,31 @@ impl ComboHotkeyMonitor {
             })
             .map_err(|e| ComboHotkeyError::RegisterFailed(format!("spawn forward thread: {e}")))?;
         *current = Some(registered);
+        #[cfg(target_os = "macos")]
+        self.inner.native_dictation.lock().take();
         Ok(())
     }
 }
 
+#[cfg(target_os = "macos")]
+fn is_native_dictation(binding: &ShortcutBinding) -> bool {
+    binding.primary == crate::macos_dictation_key::PRIMARY && binding.modifiers.is_empty()
+}
+#[cfg(target_os = "macos")]
+impl ComboHotkeyMonitor {
+    pub fn native_dictation_active(&self) -> bool {
+        self.inner
+            .native_dictation
+            .lock()
+            .as_ref()
+            .is_some_and(|m| m.active())
+    }
+}
 impl Drop for ComboHotkeyMonitor {
     fn drop(&mut self) {
         self.inner.registered.lock().take();
+        #[cfg(target_os = "macos")]
+        self.inner.native_dictation.lock().take();
     }
 }
 
@@ -145,6 +190,10 @@ fn forward_loop(hotkey_id: u32, rx: Receiver<GlobalHotKeyEvent>, tx: Sender<Comb
 
 /// 测试一个组合键是否可以注册（不实际注册，仅验证格式）。
 pub fn validate_binding(binding: &ShortcutBinding) -> Result<(), ComboHotkeyError> {
+    #[cfg(target_os = "macos")]
+    if is_native_dictation(binding) {
+        return Ok(());
+    }
     parse_binding(binding)?;
     Ok(())
 }
diff --git a/openless-all/app/src-tauri/src/commands/hotkeys.rs b/openless-all/app/src-tauri/src/commands/hotkeys.rs
index f22dbefe..aff77481 100644
--- a/openless-all/app/src-tauri/src/commands/hotkeys.rs
+++ b/openless-all/app/src-tauri/src/commands/hotkeys.rs
@@ -14,17 +14,16 @@ pub fn validate_shortcut_binding(binding: ShortcutBinding) -> Result<(), String>
 }
 
 #[tauri::command]
-pub fn set_dictation_hotkey(
+pub async fn set_dictation_hotkey(
     coord: CoordinatorState<'_>,
     binding: ShortcutBinding,
 ) -> Result<(), String> {
-    crate::shortcut_binding::validate_binding(&binding).map_err(|e| e.to_string())?;
-    reject_bare_shift_dictation_shortcut(&binding)?;
-    let mut prefs = coord.backend().get_preferences();
-    prefs.dictation_hotkey = binding;
-    sync_dictation_hotkey_legacy_fields(&mut prefs);
-    reject_hotkey_collisions(&prefs)?;
-    super::settings::persist_strict_settings(&coord, prefs)
+    let coord = Arc::clone(coord.inner());
+    tauri::async_runtime::spawn_blocking(move || {
+        super::settings::replace_dictation_hotkey(&coord, binding)
+    })
+    .await
+    .map_err(|error| error.to_string())?
 }
 
 #[tauri::command]
@@ -120,19 +119,21 @@ pub fn validate_combo_hotkey(binding: ComboBinding) -> Result<(), String> {
 
 /// 设置自定义录音组合键并热更新 monitor。
 #[tauri::command]
-pub fn set_combo_hotkey(coord: CoordinatorState<'_>, binding: ComboBinding) -> Result<(), String> {
-    let mut prefs = coord.backend().get_preferences();
+pub async fn set_combo_hotkey(
+    coord: CoordinatorState<'_>,
+    binding: ComboBinding,
+) -> Result<(), String> {
     let shortcut = ShortcutBinding {
-        primary: binding.primary.clone(),
-        modifiers: binding.modifiers.clone(),
+        primary: binding.primary,
+        modifiers: binding.modifiers,
     };
-    reject_bare_shift_dictation_shortcut(&shortcut)?;
-    crate::combo_hotkey::validate_binding(&shortcut).map_err(|e| e.to_string())?;
-    prefs.custom_combo_hotkey = Some(binding);
-    prefs.dictation_hotkey = shortcut;
-    sync_dictation_hotkey_legacy_fields(&mut prefs);
-    reject_hotkey_collisions(&prefs)?;
-    super::settings::persist_strict_settings(&coord, prefs)
+    crate::combo_hotkey::validate_binding(&shortcut).map_err(|error| error.to_string())?;
+    let coord = Arc::clone(coord.inner());
+    tauri::async_runtime::spawn_blocking(move || {
+        super::settings::replace_dictation_hotkey(&coord, shortcut)
+    })
+    .await
+    .map_err(|error| error.to_string())?
 }
 
 #[cfg(test)]
diff --git a/openless-all/app/src-tauri/src/commands/settings.rs b/openless-all/app/src-tauri/src/commands/settings.rs
index 8a0c5604..9f10dcdb 100644
--- a/openless-all/app/src-tauri/src/commands/settings.rs
+++ b/openless-all/app/src-tauri/src/commands/settings.rs
@@ -700,3 +700,39 @@ pub async fn app_download_and_install_android_update(
         Err("应用内更新仅支持 Android".to_string())
     }
 }
+
+/// Replace the single dictation binding under the existing settings transaction.
+pub(crate) fn replace_dictation_hotkey(
+    coord: &Coordinator,
+    binding: ShortcutBinding,
+) -> Result<(), String> {
+    let _host_guard = coord.lock_settings_host();
+    let mut prefs = coord.backend().get_preferences();
+    crate::shortcut_binding::validate_binding(&binding).map_err(|error| error.to_string())?;
+    reject_bare_shift_dictation_shortcut(&binding)?;
+    #[cfg(target_os = "macos")]
+    {
+        let native = crate::macos_dictation_key::PRIMARY;
+        if prefs.dictation_hotkey.primary == native || binding.primary == native {
+            if coord.dictation_shortcut_is_busy() {
+                return Err("macDictationKeyBusy".into());
+            }
+            if binding == prefs.dictation_hotkey {
+                // No settings effect is generated for an unchanged binding.
+                return coord.try_update_native_dictation_binding();
+            }
+        }
+    }
+    prefs.dictation_hotkey = binding;
+    sync_dictation_hotkey_legacy_fields(&mut prefs);
+    reject_hotkey_collisions(&prefs)?;
+    coord
+        .backend()
+        .update_settings(
+            prefs,
+            openless_core::SettingsUpdateOptions::STRICT,
+            &TauriSettingsRuntime::new(coord),
+        )
+        .map(|_| ())
+        .map_err(|error| error.to_string())
+}
diff --git a/openless-all/app/src-tauri/src/coordinator.rs b/openless-all/app/src-tauri/src/coordinator.rs
index 6727f108..410cbae4 100644
--- a/openless-all/app/src-tauri/src/coordinator.rs
+++ b/openless-all/app/src-tauri/src/coordinator.rs
@@ -34,6 +34,8 @@ mod capsule_focus;
 #[path = "coordinator/dictation_core.rs"]
 mod dictation;
 mod hotkey_loops;
+#[cfg(target_os = "macos")]
+mod native_dictation_key;
 mod qa;
 #[cfg(all(not(mobile), target_os = "windows"))]
 pub(crate) mod selection_voice_session;
@@ -1464,11 +1466,28 @@ impl Coordinator {
         if previous.style_packs != next.style_packs {
             self.try_update_style_pack_hotkey_bindings()?;
         }
-        if previous.dictation != next.dictation || previous.dictation_mode != next.dictation_mode {
-            self.update_hotkey_binding();
-        }
-        if previous.dictation != next.dictation {
-            self.update_combo_hotkey_binding();
+        #[cfg(target_os = "macos")]
+        let native_transition = previous.dictation.primary == crate::macos_dictation_key::PRIMARY
+            || next.dictation.primary == crate::macos_dictation_key::PRIMARY;
+        #[cfg(not(target_os = "macos"))]
+        let native_transition = false;
+        if native_transition {
+            #[cfg(target_os = "macos")]
+            if previous.dictation != next.dictation
+                || previous.dictation_mode != next.dictation_mode
+            {
+                self.try_update_native_dictation_binding()?;
+                self.update_modifier_shortcut_bindings();
+            }
+        } else {
+            if previous.dictation != next.dictation
+                || previous.dictation_mode != next.dictation_mode
+            {
+                self.update_hotkey_binding();
+            }
+            if previous.dictation != next.dictation {
+                self.update_combo_hotkey_binding();
+            }
         }
         if previous.qa != next.qa {
             self.update_qa_hotkey_binding();
diff --git a/openless-all/app/src-tauri/src/coordinator/native_dictation_key.rs b/openless-all/app/src-tauri/src/coordinator/native_dictation_key.rs
new file mode 100644
index 00000000..f9176f21
--- /dev/null
+++ b/openless-all/app/src-tauri/src/coordinator/native_dictation_key.rs
@@ -0,0 +1,108 @@
+//! Synchronous native-key registration participates in the Core settings transaction.
+use super::*;
+
+impl Coordinator {
+    pub(crate) fn dictation_shortcut_is_busy(&self) -> bool {
+        !matches!(
+            self.backend().snapshot().dictation.phase,
+            openless_core::DictationPhase::Idle
+                | openless_core::DictationPhase::Completed
+                | openless_core::DictationPhase::Cancelled
+                | openless_core::DictationPhase::Failed
+        )
+    }
+
+    /// Keep the previous listener until replacement registration succeeds. The
+    /// caller is a worker thread; Carbon ownership changes run on the UI thread.
+    pub(crate) fn try_update_native_dictation_binding(&self) -> Result<(), String> {
+        let target = hotkey_runtime_target(&self.inner);
+        let inner = Arc::clone(&self.inner);
+        let (done_tx, done_rx) = mpsc::sync_channel(1);
+        // Cancel queued work on timeout. Once a callback has started, wait for
+        // its acknowledgement before Core can roll back the runtime target.
+        // This gate never nests with the target mutex on the calling thread.
+        let cancelled = Arc::new(Mutex::new(false));
+        let callback_cancelled = Arc::clone(&cancelled);
+        self.inner.host.run_on_main_thread(move || {
+            let cancelled = callback_cancelled.lock();
+            let result = (|| {
+                if *cancelled || hotkey_runtime_target(&inner) != target {
+                    return Err("macDictationKeyChanged".into());
+                }
+                let binding = target.dictation.clone();
+                let trigger = crate::shortcut_binding::legacy_modifier_trigger(&binding);
+                if trigger.is_some() || is_unconfigured_shortcut(&binding) {
+                    if trigger.is_some() && inner.hotkey.lock().is_none() {
+                        return Err("macDictationKeyUnavailable".into());
+                    }
+                    inner.combo_hotkey.lock().take();
+                    inner.side_aware_combo.lock().take();
+                } else if crate::shortcut_binding::binding_requires_side_aware_hook(&binding) {
+                    let mut slot = inner.side_aware_combo.lock();
+                    if let Some(monitor) = slot.as_ref() {
+                        // A failed native registration leaves this route alive.
+                        // Reuse its sender: dropping an old side-aware handle
+                        // after creating another would clear the singleton route.
+                        monitor
+                            .update_binding(binding)
+                            .map_err(|error| error.to_string())?;
+                    } else {
+                        let (tx, rx) = mpsc::channel();
+                        let monitor =
+                            crate::side_aware_combo::SideAwareComboMonitor::start(binding, tx)
+                                .map_err(|error| error.to_string())?;
+                        let bridge_inner = Arc::clone(&inner);
+                        std::thread::Builder::new()
+                            .name("openless-side-combo-bridge".into())
+                            .spawn(move || combo_hotkey_bridge_loop(bridge_inner, rx))
+                            .map_err(|error| error.to_string())?;
+                        *slot = Some(monitor);
+                    }
+                    inner.combo_hotkey.lock().take();
+                } else {
+                    let mut slot = inner.combo_hotkey.lock();
+                    if let Some(monitor) = slot.as_ref() {
+                        monitor
+                            .update_binding(binding)
+                            .map_err(|error| error.to_string())?;
+                    } else {
+                        let (tx, rx) = mpsc::channel();
+                        let monitor = ComboHotkeyMonitor::start(binding, tx)
+                            .map_err(|error| error.to_string())?;
+                        let bridge_inner = Arc::clone(&inner);
+                        std::thread::Builder::new()
+                            .name("openless-combo-hotkey-bridge".into())
+                            .spawn(move || combo_hotkey_bridge_loop(bridge_inner, rx))
+                            .map_err(|error| error.to_string())?;
+                        *slot = Some(monitor);
+                    }
+                    inner.side_aware_combo.lock().take();
+                }
+                if let Some(monitor) = inner.hotkey.lock().as_ref() {
+                    monitor.update_binding(crate::types::HotkeyBinding {
+                        trigger: trigger.unwrap_or(crate::types::HotkeyTrigger::Custom),
+                        mode: target.dictation_mode,
+                        keys: None,
+                    });
+                }
+                Ok(())
+            })();
+            let _ = done_tx.send(result);
+        })?;
+        match done_rx.recv_timeout(std::time::Duration::from_secs(5)) {
+            Ok(result) => result,
+            Err(_) => {
+                let mut cancelled = cancelled.lock();
+                // A running callback may have finished while we acquired the
+                // gate. Its real result takes precedence over the timeout.
+                match done_rx.try_recv() {
+                    Ok(result) => result,
+                    Err(_) => {
+                        *cancelled = true;
+                        Err("macDictationKeyUnavailable".into())
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/openless-all/app/src-tauri/src/lib.rs b/openless-all/app/src-tauri/src/lib.rs
index 8b450cc7..f6a243d1 100644
--- a/openless-all/app/src-tauri/src/lib.rs
+++ b/openless-all/app/src-tauri/src/lib.rs
@@ -31,6 +31,8 @@ mod coordinator;
 mod coordinator_state;
 mod core_adapters;
 mod correction;
+#[cfg(target_os = "macos")]
+mod macos_dictation_key;
 mod qa_adapter;
 mod tauri_coordinator_host;
 // 托盘麦克风设备变更监听：macOS CoreAudio / Windows MMDevice 原生通知（空闲零唤醒），
diff --git a/openless-all/app/src-tauri/src/macos_dictation_key.rs b/openless-all/app/src-tauri/src/macos_dictation_key.rs
new file mode 100644
index 00000000..8acdea5c
--- /dev/null
+++ b/openless-all/app/src-tauri/src/macos_dictation_key.rs
@@ -0,0 +1,288 @@
+//! Process-owned capture of the Mac Dictation key. Ordinary F5 is never captured.
+use crate::combo_hotkey::ComboHotkeyEvent;
+use std::{
+    ffi::c_void,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        mpsc::{self, Sender},
+        Arc,
+    },
+    thread,
+    time::{Duration, Instant},
+};
+
+pub const PRIMARY: &str = "MacDictationKey";
+const MODIFIERS: u64 = (1 << 17) | (1 << 18) | (1 << 19) | (1 << 20) | (1 << 23);
+fn effective_flags(flags: u64, fn_down: bool) -> u64 {
+    if fn_down {
+        flags
+    } else {
+        flags & !(1 << 23)
+    }
+}
+#[derive(Default)]
+struct KeyState {
+    held: bool,
+}
+#[derive(Debug, PartialEq)]
+enum Edge {
+    Pass,
+    Repeat,
+    Press,
+    Release,
+}
+impl KeyState {
+    fn event(&mut self, key: i64, down: bool, repeat: bool, flags: u64) -> Edge {
+        if key != 176 {
+            return Edge::Pass;
+        }
+        if self.held {
+            if down {
+                return Edge::Repeat;
+            }
+            self.held = false;
+            return Edge::Release;
+        }
+        if down && !repeat && flags & MODIFIERS == 0 {
+            self.held = true;
+            return Edge::Press;
+        }
+        Edge::Pass
+    }
+}
+
+#[link(name = "CoreGraphics", kind = "framework")]
+extern "C" {
+    fn CGEventTapCreate(
+        location: u32,
+        placement: u32,
+        options: u32,
+        mask: u64,
+        callback: extern "C" fn(*mut c_void, u32, *mut c_void, *mut c_void) -> *mut c_void,
+        context: *mut c_void,
+    ) -> *mut c_void;
+    fn CGEventTapEnable(tap: *mut c_void, enabled: bool);
+    fn CGEventGetIntegerValueField(event: *mut c_void, field: u32) -> i64;
+    fn CGEventGetFlags(event: *mut c_void) -> u64;
+    fn CGEventSourceKeyState(state: i32, key: u16) -> bool;
+}
+#[link(name = "CoreFoundation", kind = "framework")]
+extern "C" {
+    fn CFMachPortCreateRunLoopSource(
+        allocator: *const c_void,
+        port: *mut c_void,
+        order: isize,
+    ) -> *mut c_void;
+    fn CFMachPortInvalidate(port: *mut c_void);
+    fn CFRunLoopGetCurrent() -> *mut c_void;
+    fn CFRunLoopAddSource(runloop: *mut c_void, source: *mut c_void, mode: *const c_void);
+    fn CFRunLoopRemoveSource(runloop: *mut c_void, source: *mut c_void, mode: *const c_void);
+    fn CFRunLoopRunInMode(mode: *const c_void, seconds: f64, return_after_source: bool) -> i32;
+    fn CFRelease(value: *const c_void);
+    static kCFRunLoopDefaultMode: *const c_void;
+}
+struct Context {
+    state: KeyState,
+    tx: Sender<ComboHotkeyEvent>,
+    stop: Arc<AtomicBool>,
+    tap: *mut c_void,
+}
+
+fn recover_disabled_tap(ctx: &mut Context, enable: impl FnOnce(*mut c_void)) {
+    if ctx.state.held {
+        let _ = ctx
+            .tx
+            .send(ComboHotkeyEvent::Released { at: Instant::now() });
+    }
+    ctx.state.held = false;
+    enable(ctx.tap);
+}
+
+extern "C" fn callback(
+    _: *mut c_void,
+    kind: u32,
+    event: *mut c_void,
+    data: *mut c_void,
+) -> *mut c_void {
+    if data.is_null() {
+        return event;
+    }
+    let ctx = unsafe { &mut *(data as *mut Context) };
+    if kind == 0xffff_fffe || kind == 0xffff_ffff {
+        // Fail open for a held key, then restore the selected trigger in place.
+        recover_disabled_tap(ctx, |tap| unsafe { CGEventTapEnable(tap, true) });
+        log::warn!("[dictation-key] native interception was disabled and has been re-enabled");
+        return event;
+    }
+    if event.is_null() || !matches!(kind, 10 | 11) {
+        return event;
+    }
+    let key = unsafe { CGEventGetIntegerValueField(event, 9) };
+    if key != 176 {
+        return event;
+    }
+    // Never start a new capture in a password field / Secure Event Input session.
+    if !ctx.state.held && crate::unicode_keystroke::is_secure_input_enabled() {
+        return event;
+    }
+    let (flags, repeat) = unsafe {
+        (
+            CGEventGetFlags(event),
+            CGEventGetIntegerValueField(event, 8) != 0,
+        )
+    };
+    let fn_down = unsafe { CGEventSourceKeyState(0, 63) };
+    let edge = ctx
+        .state
+        .event(key, kind == 10, repeat, effective_flags(flags, fn_down));
+    let message = match edge {
+        Edge::Press => Some(ComboHotkeyEvent::Pressed { at: Instant::now() }),
+        Edge::Release => Some(ComboHotkeyEvent::Released { at: Instant::now() }),
+        _ => None,
+    };
+    if let Some(message) = message {
+        if ctx.tx.send(message).is_err() {
+            ctx.stop.store(true, Ordering::SeqCst);
+            return event;
+        }
+    }
+    if edge == Edge::Pass {
+        event
+    } else {
+        std::ptr::null_mut()
+    }
+}
+
+pub struct Monitor {
+    stop: Arc<AtomicBool>,
+    thread: Option<thread::JoinHandle<()>>,
+}
+impl Monitor {
+    pub fn start(tx: Sender<ComboHotkeyEvent>) -> Result<Self, String> {
+        let stop = Arc::new(AtomicBool::new(false));
+        let thread_stop = stop.clone();
+        let (ready_tx, ready_rx) = mpsc::sync_channel(1);
+        let thread = thread::Builder::new()
+            .name("openless-dictation-key".into())
+            .spawn(move || unsafe {
+                let mut context = Context {
+                    state: KeyState::default(),
+                    tx,
+                    stop: thread_stop.clone(),
+                    tap: std::ptr::null_mut(),
+                };
+                let tap = CGEventTapCreate(
+                    0,
+                    0,
+                    0,
+                    (1 << 10) | (1 << 11),
+                    callback,
+                    &mut context as *mut _ as *mut c_void,
+                );
+                if tap.is_null() {
+                    let _ = ready_tx.send(Err("macDictationKeyPermission".to_string()));
+                    return;
+                }
+                context.tap = tap;
+                let source = CFMachPortCreateRunLoopSource(std::ptr::null(), tap, 0);
+                if source.is_null() {
+                    CFMachPortInvalidate(tap);
+                    CFRelease(tap);
+                    let _ = ready_tx.send(Err("macDictationKeyUnavailable".to_string()));
+                    return;
+                }
+                let runloop = CFRunLoopGetCurrent();
+                CFRunLoopAddSource(runloop, source, kCFRunLoopDefaultMode);
+                CGEventTapEnable(tap, true);
+                if ready_tx.send(Ok(())).is_ok() {
+                    while !thread_stop.load(Ordering::SeqCst) {
+                        CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.5, false);
+                    }
+                }
+                CGEventTapEnable(tap, false);
+                CFRunLoopRemoveSource(runloop, source, kCFRunLoopDefaultMode);
+                CFMachPortInvalidate(tap);
+                CFRelease(source);
+                CFRelease(tap);
+            })
+            .map_err(|e| e.to_string())?;
+        match ready_rx.recv_timeout(Duration::from_secs(3)) {
+            Ok(Ok(())) => Ok(Self {
+                stop,
+                thread: Some(thread),
+            }),
+            result => {
+                stop.store(true, Ordering::SeqCst);
+                let _ = thread.join();
+                Err(match result {
+                    Ok(Err(e)) => e,
+                    _ => "macDictationKeyUnavailable".into(),
+                })
+            }
+        }
+    }
+    pub fn active(&self) -> bool {
+        !self.stop.load(Ordering::SeqCst)
+    }
+}
+impl Drop for Monitor {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::SeqCst);
+        if let Some(thread) = self.thread.take() {
+            let _ = thread.join();
+        }
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn function_layer_flag_is_distinct_from_physical_fn() {
+        assert_eq!(effective_flags(1 << 23, false), 0);
+        assert_eq!(effective_flags(1 << 23, true), 1 << 23);
+        assert_eq!(effective_flags((1 << 19) | (1 << 23), false), 1 << 19);
+    }
+    #[test]
+    fn ordinary_and_modified_keys_pass_through() {
+        let mut s = KeyState::default();
+        for key in [96, 90, 59, 58, 63] {
+            assert_eq!(s.event(key, true, false, 0), Edge::Pass);
+        }
+        for bit in [17, 18, 19, 20, 23] {
+            assert_eq!(s.event(176, true, false, 1 << bit), Edge::Pass);
+        }
+        assert_eq!(s.event(176, false, false, 0), Edge::Pass);
+    }
+    #[test]
+    fn repeat_and_release_pairing() {
+        let mut s = KeyState::default();
+        assert_eq!(s.event(176, true, true, 0), Edge::Pass);
+        assert_eq!(s.event(176, true, false, 0), Edge::Press);
+        assert_eq!(s.event(176, true, true, 0), Edge::Repeat);
+        assert_eq!(s.event(176, false, false, MODIFIERS), Edge::Release);
+        assert_eq!(s.event(176, false, false, 0), Edge::Pass);
+        assert_eq!(s.event(176, true, false, 0), Edge::Press);
+    }
+    #[test]
+    fn disabled_tap_releases_held_key_and_is_reenabled() {
+        let (tx, rx) = mpsc::channel();
+        let stop = Arc::new(AtomicBool::new(false));
+        let mut context = Context {
+            state: KeyState { held: true },
+            tx,
+            stop: stop.clone(),
+            tap: std::ptr::null_mut(),
+        };
+        let mut reenabled = false;
+
+        recover_disabled_tap(&mut context, |_| reenabled = true);
+
+        assert!(reenabled);
+        assert!(!context.state.held);
+        assert!(!stop.load(Ordering::SeqCst));
+        assert!(matches!(
+            rx.try_recv(),
+            Ok(ComboHotkeyEvent::Released { .. })
+        ));
+    }
+}
diff --git a/openless-all/app/src-tauri/src/shortcut_binding.rs b/openless-all/app/src-tauri/src/shortcut_binding.rs
index 00c7a49d..a635762c 100644
--- a/openless-all/app/src-tauri/src/shortcut_binding.rs
+++ b/openless-all/app/src-tauri/src/shortcut_binding.rs
@@ -14,6 +14,10 @@ pub use openless_core::{
 
 pub fn validate_binding(binding: &ShortcutBinding) -> Result<(), ShortcutBindingError> {
     openless_core::validate_shortcut_binding(binding)?;
+    #[cfg(target_os = "macos")]
+    if binding.primary == crate::macos_dictation_key::PRIMARY {
+        return Ok(());
+    }
     if legacy_modifier_trigger(binding).is_some()
         || (binding.modifiers.is_empty() && binding.primary.eq_ignore_ascii_case("shift"))
         || binding_requires_side_aware_hook(binding)
@@ -95,6 +99,14 @@ pub fn parse_primary(raw: &str) -> Result<Code, ShortcutBindingError> {
         "F10" => Code::F10,
         "F11" => Code::F11,
         "F12" => Code::F12,
+        "F13" => Code::F13,
+        "F14" => Code::F14,
+        "F15" => Code::F15,
+        "F16" => Code::F16,
+        "F17" => Code::F17,
+        "F18" => Code::F18,
+        "F19" => Code::F19,
+        "F20" => Code::F20,
         _ => return Err(ShortcutBindingError::UnsupportedKey(trimmed.to_string())),
     };
     Ok(named)
@@ -160,6 +172,49 @@ fn char_to_code(ch: char) -> Option<Code> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn extended_function_keys_parse_without_modifiers() {
+        for (name, code) in [
+            ("F13", Code::F13),
+            ("F14", Code::F14),
+            ("F15", Code::F15),
+            ("F16", Code::F16),
+            ("F17", Code::F17),
+            ("F18", Code::F18),
+            ("F19", Code::F19),
+            ("F20", Code::F20),
+        ] {
+            let binding = ShortcutBinding {
+                primary: name.into(),
+                modifiers: vec![],
+            };
+            assert!(validate_binding(&binding).is_ok());
+            let parsed = parse_global_hotkey(&binding).unwrap();
+            assert_eq!(parsed.key, code);
+            assert!(parsed.mods.is_empty());
+            assert!(legacy_modifier_trigger(&binding).is_none());
+        }
+        assert_eq!(parse_primary(" f20 ").unwrap(), Code::F20);
+        assert!(parse_primary("F21").is_err());
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn native_dictation_key_is_bare_and_dictation_only() {
+        let native = ShortcutBinding {
+            primary: crate::macos_dictation_key::PRIMARY.into(),
+            modifiers: vec![],
+        };
+        assert!(validate_binding(&native).is_ok());
+        assert!(parse_global_hotkey(&native).is_err());
+        assert!(reject_side_specific_non_dictation(&native).is_err());
+        let modified = ShortcutBinding {
+            modifiers: vec!["shift".into()],
+            ..native
+        };
+        assert!(validate_binding(&modified).is_err());
+    }
+
     #[test]
     fn parses_combo_and_single_key() {
         let combo = ShortcutBinding {
diff --git a/openless-all/app/src-tauri/src/side_aware_combo.rs b/openless-all/app/src-tauri/src/side_aware_combo.rs
index e042a85e..ab335b45 100644
--- a/openless-all/app/src-tauri/src/side_aware_combo.rs
+++ b/openless-all/app/src-tauri/src/side_aware_combo.rs
@@ -186,19 +186,7 @@ impl SideAwareComboMonitor {
 
         #[cfg(not(target_os = "linux"))]
         {
-            if binding.modifiers.is_empty()
-                || binding
-                    .modifiers
-                    .iter()
-                    .any(|tag| !is_side_specific_modifier_tag(tag))
-            {
-                return Err(crate::combo_hotkey::ComboHotkeyError::UnsupportedModifier(
-                    "binding is not side-specific".into(),
-                ));
-            }
-            crate::shortcut_binding::parse_primary(&binding.primary).map_err(|e| {
-                crate::combo_hotkey::ComboHotkeyError::UnsupportedKey(e.to_string())
-            })?;
+            validate_side_binding(&binding)?;
 
             let slot = ACTIVE_MONITOR.get_or_init(|| RwLock::new(None));
             let mut guard = slot.write().expect("side combo monitor lock poisoned");
@@ -211,6 +199,51 @@ impl SideAwareComboMonitor {
     }
 }
 
+#[cfg(not(target_os = "linux"))]
+fn validate_side_binding(
+    binding: &ShortcutBinding,
+) -> Result<(), crate::combo_hotkey::ComboHotkeyError> {
+    if binding.modifiers.is_empty()
+        || binding
+            .modifiers
+            .iter()
+            .any(|tag| !is_side_specific_modifier_tag(tag))
+    {
+        return Err(crate::combo_hotkey::ComboHotkeyError::UnsupportedModifier(
+            "binding is not side-specific".into(),
+        ));
+    }
+    crate::shortcut_binding::parse_primary(&binding.primary)
+        .map_err(|e| crate::combo_hotkey::ComboHotkeyError::UnsupportedKey(e.to_string()))?;
+
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+impl SideAwareComboMonitor {
+    /// Update the existing route without replacing its handle or event sender.
+    /// Used when a failed native-key switch restores an already-live shortcut.
+    pub(crate) fn update_binding(
+        &self,
+        binding: ShortcutBinding,
+    ) -> Result<(), crate::combo_hotkey::ComboHotkeyError> {
+        validate_side_binding(&binding)?;
+        let slot = ACTIVE_MONITOR.get().ok_or_else(|| {
+            crate::combo_hotkey::ComboHotkeyError::RegisterFailed(
+                "side-aware listener is unavailable".into(),
+            )
+        })?;
+        let active = slot.read().expect("side combo monitor lock poisoned");
+        let active = active.as_ref().ok_or_else(|| {
+            crate::combo_hotkey::ComboHotkeyError::RegisterFailed(
+                "side-aware listener is unavailable".into(),
+            )
+        })?;
+        *active.state.lock() = SideAwareComboState::new(binding);
+        Ok(())
+    }
+}
+
 impl Drop for SideAwareComboMonitor {
     fn drop(&mut self) {
         if let Some(slot) = ACTIVE_MONITOR.get() {
@@ -270,11 +303,12 @@ pub mod platform {
     use super::*;
 
     use windows::Win32::UI::Input::KeyboardAndMouse::{
-        VK_BACK, VK_DELETE, VK_DOWN, VK_END, VK_ESCAPE, VK_F1, VK_F10, VK_F11, VK_F12, VK_F2,
-        VK_F3, VK_F4, VK_F5, VK_F6, VK_F7, VK_F8, VK_F9, VK_HOME, VK_INSERT, VK_LCONTROL, VK_LEFT,
-        VK_LMENU, VK_LSHIFT, VK_LWIN, VK_OEM_1, VK_OEM_2, VK_OEM_3, VK_OEM_4, VK_OEM_5, VK_OEM_6,
-        VK_OEM_7, VK_OEM_COMMA, VK_OEM_MINUS, VK_OEM_PERIOD, VK_OEM_PLUS, VK_RCONTROL, VK_RETURN,
-        VK_RIGHT, VK_RMENU, VK_RSHIFT, VK_RWIN, VK_SPACE, VK_TAB, VK_UP,
+        VK_BACK, VK_DELETE, VK_DOWN, VK_END, VK_ESCAPE, VK_F1, VK_F10, VK_F11, VK_F12, VK_F13,
+        VK_F14, VK_F15, VK_F16, VK_F17, VK_F18, VK_F19, VK_F2, VK_F20, VK_F3, VK_F4, VK_F5, VK_F6,
+        VK_F7, VK_F8, VK_F9, VK_HOME, VK_INSERT, VK_LCONTROL, VK_LEFT, VK_LMENU, VK_LSHIFT,
+        VK_LWIN, VK_OEM_1, VK_OEM_2, VK_OEM_3, VK_OEM_4, VK_OEM_5, VK_OEM_6, VK_OEM_7,
+        VK_OEM_COMMA, VK_OEM_MINUS, VK_OEM_PERIOD, VK_OEM_PLUS, VK_RCONTROL, VK_RETURN, VK_RIGHT,
+        VK_RMENU, VK_RSHIFT, VK_RWIN, VK_SPACE, VK_TAB, VK_UP,
     };
 
     pub fn dispatch_vk(vk_code: u32, pressed: bool) {
@@ -334,6 +368,14 @@ pub mod platform {
             x if x == VK_F10.0 as u32 => "F10",
             x if x == VK_F11.0 as u32 => "F11",
             x if x == VK_F12.0 as u32 => "F12",
+            x if x == VK_F13.0 as u32 => "F13",
+            x if x == VK_F14.0 as u32 => "F14",
+            x if x == VK_F15.0 as u32 => "F15",
+            x if x == VK_F16.0 as u32 => "F16",
+            x if x == VK_F17.0 as u32 => "F17",
+            x if x == VK_F18.0 as u32 => "F18",
+            x if x == VK_F19.0 as u32 => "F19",
+            x if x == VK_F20.0 as u32 => "F20",
             x if x == VK_OEM_1.0 as u32 => ";",
             x if x == VK_OEM_PLUS.0 as u32 => "=",
             x if x == VK_OEM_COMMA.0 as u32 => ",",
@@ -428,6 +470,14 @@ fn macos_keycode_to_primary(keycode: i64) -> Option<&'static str> {
         109 => Some("F10"),
         103 => Some("F11"),
         111 => Some("F12"),
+        105 => Some("F13"),
+        107 => Some("F14"),
+        113 => Some("F15"),
+        106 => Some("F16"),
+        64 => Some("F17"),
+        79 => Some("F18"),
+        80 => Some("F19"),
+        90 => Some("F20"),
         _ => None,
     }
 }
@@ -535,6 +585,74 @@ pub mod platform {
 mod tests {
     use super::*;
 
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn restoring_live_side_binding_preserves_its_event_route() {
+        use std::sync::mpsc;
+        let binding = ShortcutBinding {
+            primary: "D".into(),
+            modifiers: vec!["ctrl-right".into()],
+        };
+        let (tx, rx) = mpsc::channel();
+        let monitor = SideAwareComboMonitor::start(binding.clone(), tx).unwrap();
+        let press_and_release = |primary: &str| {
+            handle_side_modifier(SideModifier::CtrlRight, true);
+            handle_primary_key(primary, true);
+            handle_primary_key(primary, false);
+            handle_side_modifier(SideModifier::CtrlRight, false);
+            assert!(matches!(
+                rx.try_recv(),
+                Ok(ComboHotkeyEvent::Pressed { .. })
+            ));
+            assert!(matches!(
+                rx.try_recv(),
+                Ok(ComboHotkeyEvent::Released { .. })
+            ));
+            assert!(rx.try_recv().is_err());
+        };
+        press_and_release("D");
+        // Native registration failed before removing this monitor. The reverse
+        // transaction must reuse the live route, even on repeated restoration.
+        monitor.update_binding(binding.clone()).unwrap();
+        monitor.update_binding(binding).unwrap();
+        press_and_release("D");
+        assert!(monitor
+            .update_binding(ShortcutBinding {
+                primary: "F21".into(),
+                modifiers: vec!["ctrl-right".into()]
+            })
+            .is_err());
+        press_and_release("D");
+        monitor
+            .update_binding(ShortcutBinding {
+                primary: "F20".into(),
+                modifiers: vec!["ctrl-right".into()],
+            })
+            .unwrap();
+        press_and_release("F20");
+        drop(monitor);
+        assert!(matches!(
+            rx.try_recv(),
+            Err(mpsc::TryRecvError::Disconnected)
+        ));
+    }
+
+    #[test]
+    fn extended_macos_function_keys_use_carbon_keycodes() {
+        for (keycode, primary) in [
+            (105, "F13"),
+            (107, "F14"),
+            (113, "F15"),
+            (106, "F16"),
+            (64, "F17"),
+            (79, "F18"),
+            (80, "F19"),
+            (90, "F20"),
+        ] {
+            assert_eq!(macos_keycode_to_primary(keycode), Some(primary));
+        }
+    }
+
     #[test]
     fn macos_keycode_2_is_d() {
         assert_eq!(macos_keycode_to_primary(2), Some("D"));
diff --git a/openless-all/app/src/components/ShortcutRecorder.tsx b/openless-all/app/src/components/ShortcutRecorder.tsx
index 49794925..a946a6a5 100644
--- a/openless-all/app/src/components/ShortcutRecorder.tsx
+++ b/openless-all/app/src/components/ShortcutRecorder.tsx
@@ -3,6 +3,7 @@ import { AnimatePresence, motion } from 'framer-motion';
 import { ChevronDown } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { formatComboParts, modifiersFromPressedCodes } from '../lib/hotkey';
+import { functionKeyPrimaryFromEvent } from '../lib/hotkeyRecorder';
 import { KbdGroup } from './Kbd';
 import { setShortcutRecordingActive, validateShortcutBinding } from '../lib/ipc';
 import type { ShortcutBinding } from '../lib/types';
@@ -28,6 +29,7 @@ export function ShortcutRecorder({
   resetLabel,
   comboOnly = false,
   sideSpecificModifiers = false,
+  allowMacDictationKey = false,
 }: {
   value: ShortcutBinding | null;
   onSave: (binding: ShortcutBinding) => Promise<void>;
@@ -45,11 +47,15 @@ export function ShortcutRecorder({
   comboOnly?: boolean;
   /** 听写 start/stop 专用：录制 cmd-left / ctrl-right 等侧向修饰键。 */
   sideSpecificModifiers?: boolean;
+  /** macOS dictation only: choose the dedicated key as the single trigger. */
+  allowMacDictationKey?: boolean;
 }) {
   const { t } = useTranslation();
   const [recording, setRecording] = useState(false);
   const [menuOpen, setMenuOpen] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const nativeSelected = allowMacDictationKey && value?.primary === 'MacDictationKey';
+  const nativeError = error && ['Permission', 'Busy', 'Unavailable', 'Changed'].find(kind => error.includes(`macDictationKey${kind}`));
   const pendingModifier = useRef<ShortcutBinding | null>(null);
   const pendingTimer = useRef<number | null>(null);
   const pressedCodes = useRef<Set<string>>(new Set());
@@ -106,8 +112,9 @@ export function ShortcutRecorder({
       resetRecordingState();
       setRecording(false);
       setError(null);
-    } catch {
-      setError(t('settings.recording.comboConflict'));
+    } catch (reason) {
+      const message = String(reason);
+      setError(message.includes('macDictationKey') ? message : t('settings.recording.comboConflict'));
     }
   };
 
@@ -205,10 +212,15 @@ export function ShortcutRecorder({
     }
   };
 
-  const doReset = () => {
+  const doReset = async () => {
     setMenuOpen(false);
     setError(null);
-    if (onReset) void onReset();
+    try {
+      await onReset?.();
+    } catch (reason) {
+      const message = String(reason);
+      setError(message.includes('macDictationKey') ? message : t('settings.recording.comboConflict'));
+    }
   };
 
   const doDisable = () => {
@@ -354,11 +366,26 @@ export function ShortcutRecorder({
                 <motion.div
                   key="menu"
                   initial={{ height: 0, opacity: 0 }}
-                  animate={{ height: MENU_HEIGHT, opacity: 1 }}
+                  animate={{ height: allowMacDictationKey ? MENU_HEIGHT * 2 : MENU_HEIGHT, opacity: 1 }}
                   exit={{ height: 0, opacity: 0 }}
                   transition={{ duration: 0.16, ease: menuEase }}
                   style={{ overflow: 'hidden' }}
                 >
+                  {allowMacDictationKey && <div style={menuRowStyle}>
+                    <button
+                      type="button"
+                      aria-pressed={nativeSelected}
+                      disabled={disabled}
+                      title={t('macDictationKey.description')}
+                      onClick={() => {
+                        setMenuOpen(false);
+                        void finish({ primary: 'MacDictationKey', modifiers: [] });
+                      }}
+                      style={disabled ? disabledMenuButtonStyle : nativeSelected ? menuPrimaryStyle : menuButtonStyle}
+                    >
+                      {t('macDictationKey.label')}
+                    </button>
+                  </div>}
                   <div style={menuRowStyle}>
                     <motion.button
                       initial={{ y: 4, opacity: 0 }}
@@ -403,7 +430,7 @@ export function ShortcutRecorder({
           </motion.div>
         )}
       </AnimatePresence>
-      {error && <div style={{ fontSize: 11, color: 'var(--ol-red, #ef4444)' }}>{error}</div>}
+      {error && <div role="alert" style={{ fontSize: 11, color: 'var(--ol-red, #ef4444)' }}>{nativeError ? t(`macDictationKey.${nativeError}`) : error}</div>}
     </div>
   );
 }
@@ -426,6 +453,8 @@ function modifierPrimaryFromCode(code: string, key: string): string {
 }
 
 function primaryFromKeyboardEvent(e: KeyboardEvent): string {
+  const functionKey = functionKeyPrimaryFromEvent(e);
+  if (functionKey) return functionKey;
   const printable = primaryFromPrintableCode(e.code);
   if (printable) return printable;
   if (e.key.length === 1) return e.key;
diff --git a/openless-all/app/src/i18n/en.ts b/openless-all/app/src/i18n/en.ts
index 6d25f7c8..0b073f21 100644
--- a/openless-all/app/src/i18n/en.ts
+++ b/openless-all/app/src/i18n/en.ts
@@ -4,6 +4,14 @@ import type { zhCN } from './zh-CN';
 
 // Type-level guarantee that en mirrors the zh-CN shape.
 export const en: typeof zhCN = {
+  macDictationKey: {
+    Changed: 'The shortcut changed while saving. Please try again.',
+    label: "Mac Dictation key",
+    description: "Replaces the current dictation shortcut with the microphone key. Quitting OpenLess releases it to macOS.",
+    Permission: "Allow OpenLess in macOS Privacy & Security → Accessibility, then retry.",
+    Busy: "Finish the current dictation before changing its shortcut.",
+    Unavailable: "Could not activate this shortcut. The saved binding is unchanged; retry or choose another key.",
+  },
   app: {
     name: 'OpenLess',
     tagline: 'Speak naturally, write perfectly',
diff --git a/openless-all/app/src/i18n/zh-CN.ts b/openless-all/app/src/i18n/zh-CN.ts
index b49e8e2b..c8d176de 100644
--- a/openless-all/app/src/i18n/zh-CN.ts
+++ b/openless-all/app/src/i18n/zh-CN.ts
@@ -2,6 +2,14 @@
 // 添加新 key 时，必须同步更新 en.ts，否则首次切换到 English 会回落到中文残留。
 
 export const zhCN = {
+  macDictationKey: {
+    Changed: '保存期间快捷键已改变，请重试。',
+    label: "Mac 听写键",
+    description: "用麦克风图标键替换当前听写快捷键。退出 OpenLess 后，此键交回 macOS。",
+    Permission: "请在 macOS「隐私与安全性 → 辅助功能」中允许 OpenLess 后重试。",
+    Busy: "请先结束当前听写，再更改快捷键。",
+    Unavailable: "无法启用此快捷键，已保存的绑定未改变。请重试或选择其他键。",
+  },
   app: {
     name: 'OpenLess',
     tagline: '自然说话，完美书写',
diff --git a/openless-all/app/src/i18n/zh-TW.ts b/openless-all/app/src/i18n/zh-TW.ts
index 3d60d311..9ce75771 100644
--- a/openless-all/app/src/i18n/zh-TW.ts
+++ b/openless-all/app/src/i18n/zh-TW.ts
@@ -4,6 +4,14 @@ import type { zhCN } from './zh-CN';
 // 新增 key 時，必須同步更新 en.ts，避免切換到 English 後出現中文殘留。
 
 export const zhTW: typeof zhCN = {
+  macDictationKey: {
+    Changed: '儲存期間快捷鍵已變更，請重試。',
+    label: "Mac 聽寫鍵",
+    description: "用麥克風圖示鍵替換目前的聽寫快捷鍵。結束 OpenLess 後，此鍵交回 macOS。",
+    Permission: "請在 macOS「隱私權與安全性 → 輔助使用」中允許 OpenLess 後重試。",
+    Busy: "請先結束目前的聽寫，再變更快捷鍵。",
+    Unavailable: "無法啟用此快捷鍵，已儲存的綁定未變更。請重試或選擇其他鍵。",
+  },
   app: {
     name: 'OpenLess',
     tagline: '自然說話，完美書寫',
diff --git a/openless-all/app/src/lib/hotkey.ts b/openless-all/app/src/lib/hotkey.ts
index 1196e018..bf09a0b5 100644
--- a/openless-all/app/src/lib/hotkey.ts
+++ b/openless-all/app/src/lib/hotkey.ts
@@ -368,6 +368,7 @@ function formatPrimary(primary: string): string {
   const isMac = currentPlatform().isMac;
   if (isMac) {
     switch (trimmed.toLowerCase()) {
+      case 'macdictationkey': return i18n.t('macDictationKey.label');
       case 'space': return '\u2423';
       case 'enter':
       case 'return': return '\u21A9';
diff --git a/openless-all/app/src/lib/hotkeyRecorder.test.ts b/openless-all/app/src/lib/hotkeyRecorder.test.ts
index a1a5841a..d9d8b333 100644
--- a/openless-all/app/src/lib/hotkeyRecorder.test.ts
+++ b/openless-all/app/src/lib/hotkeyRecorder.test.ts
@@ -1,5 +1,6 @@
 import {
   createHotkeyRecorderState,
+  functionKeyPrimaryFromEvent,
   orderHotkeyCodes,
   updateHotkeyRecorderState,
 } from './hotkeyRecorder';
@@ -83,3 +84,11 @@ function apply(
 }
 
 assertDeepEqual(orderHotkeyCodes(['Mouse4', 'ControlLeft']), ['ControlLeft', 'Mouse4'], 'orders mouse after modifiers');
+
+for (let i = 1; i <= 20; i++) {
+  assertEqual(functionKeyPrimaryFromEvent({ code: `F${i}`, key: `F${i}` }), `F${i}`, 'function key');
+}
+assertEqual(functionKeyPrimaryFromEvent({ code: 'F20', key: '\uF717' }), 'F20', 'WebKit private-use key');
+assertEqual(functionKeyPrimaryFromEvent({ code: 'F20', key: 'Unidentified' }), 'F20', 'physical F20');
+assertEqual(functionKeyPrimaryFromEvent({ code: '', key: 'F20' }), 'F20', 'named F20 fallback');
+assertEqual(functionKeyPrimaryFromEvent({ code: 'KeyA', key: 'a' }), null, 'printable key preserved');
diff --git a/openless-all/app/src/lib/hotkeyRecorder.ts b/openless-all/app/src/lib/hotkeyRecorder.ts
index 8ab692f5..8473eedc 100644
--- a/openless-all/app/src/lib/hotkeyRecorder.ts
+++ b/openless-all/app/src/lib/hotkeyRecorder.ts
@@ -68,3 +68,11 @@ const HOTKEY_CODE_ORDER = [
   'NumpadSubtract', 'NumpadMultiply', 'NumpadDivide', 'NumpadDecimal', 'NumpadEnter',
   'Mouse4', 'Mouse5',
 ];
+
+/** Prefer physical function-key codes; WebKit can expose a private-use key value. */
+export function functionKeyPrimaryFromEvent(event: { code: string; key: string }): string | null {
+  const supported = /^F([1-9]|1[0-9]|20)$/;
+  if (supported.test(event.code)) return event.code;
+  if (supported.test(event.key)) return event.key;
+  return null;
+}
diff --git a/openless-all/app/src/pages/settings/RecordingInputSection.tsx b/openless-all/app/src/pages/settings/RecordingInputSection.tsx
index 8fc63cc7..12639d28 100644
--- a/openless-all/app/src/pages/settings/RecordingInputSection.tsx
+++ b/openless-all/app/src/pages/settings/RecordingInputSection.tsx
@@ -265,17 +265,18 @@ export function RecordingInputSection() {
           <ShortcutRecorder
             value={prefs.dictationHotkey}
             sideSpecificModifiers
+            allowMacDictationKey={os === 'mac'}
             // 录音快捷键是核心热键，Rust 端不接受 null，不可停用——置灰并提示。
             disableDisabled
             disableHint={t('settings.recording.comboDisableHint')}
             onSave={async binding => {
               await setDictationHotkey(binding);
-              await savePrefs({ ...prefs, dictationHotkey: binding });
+              await refresh();
             }}
             onReset={async () => {
               const binding = defaultDictationHotkey();
               await setDictationHotkey(binding);
-              await savePrefs({ ...prefs, dictationHotkey: binding });
+              await refresh();
             }}
           />
         </SettingRow>
diff --git a/openless-all/app/src/pages/settings/ShortcutsSection.tsx b/openless-all/app/src/pages/settings/ShortcutsSection.tsx
index 84daa1bb..a11f4da1 100644
--- a/openless-all/app/src/pages/settings/ShortcutsSection.tsx
+++ b/openless-all/app/src/pages/settings/ShortcutsSection.tsx
@@ -30,7 +30,7 @@ import { detectOS } from '../../components/WindowChrome';
 export function ShortcutsSection() {
   const { t } = useTranslation();
   const os = detectOS();
-  const { prefs, hotkey, updatePrefs: savePrefs } = useHotkeySettings();
+  const { prefs, hotkey, refresh, updatePrefs: savePrefs } = useHotkeySettings();
   const [platformCaps, setPlatformCaps] = useState<PlatformCapabilities | null>(null);
   const [stylePacks, setStylePacks] = useState<StylePack[]>([]);
   // 新增行的草稿状态：先选风格包、再录快捷键，两者齐了才真正落库。
@@ -101,12 +101,13 @@ export function ShortcutsSection() {
           <ShortcutRecorder
             value={prefs.dictationHotkey}
             sideSpecificModifiers
+            allowMacDictationKey={os === 'mac'}
             // 与「录音与输入」页一致：核心热键不可停用，置灰并提示。
             disableDisabled
             disableHint={t('settings.recording.comboDisableHint')}
             onSave={async binding => {
               await setDictationHotkey(binding);
-              await savePrefs({ ...prefs, dictationHotkey: binding });
+              await refresh();
             }}
           />
           <div style={{ fontSize: 11, color: 'var(--ol-ink-4)' }}>

From 882fac63f083886f33443e1c29aca34e4f200be4 Mon Sep 17 00:00:00 2001
From: zhou zhichao <69954637+zhou-zhichao@users.noreply.github.com>
Date: Thu, 10 Sep 2026 00:36:12 +0200
Subject: [PATCH 4/4] fix(remote-input): preserve phone trust across restarts
 and IP changes (#1037)

* fix(remote-input): preserve phone trust with a persistent local CA

* fix(remote-input): disclose LAN certificate MITM risk

---------

Co-authored-by: Chris233 <h-chris233@outlook.com>
---
 .github/workflows/ci.yml                      |   3 +
 docs/remote-input-certificates.md             |  92 ++++
 openless-all/app/Cargo.lock                   | 112 ++++
 openless-all/app/linux-egui/Cargo.toml        |   7 +-
 .../app/linux-egui/src/remote_input.rs        |  99 +---
 openless-all/app/src-tauri/Cargo.lock         |  95 +++-
 openless-all/app/src-tauri/Cargo.toml         |   5 +-
 .../app/src-tauri/backend-tests/Cargo.lock    | 184 +++++++
 .../app/src-tauri/backend-tests/Cargo.toml    |  11 +
 .../backend-tests/tests/remote_tls.rs         |   3 +
 .../src-tauri/src/remote_server/assets/app.js |  62 ++-
 .../src/remote_server/assets/index.html       |  16 +-
 .../src/remote_server/assets/style.css        |   2 +
 .../app/src-tauri/src/remote_server/mod.rs    | 183 ++-----
 .../src/remote_server/tls_identity.rs         | 506 ++++++++++++++++++
 openless-all/app/src/i18n/en.ts               |   6 +-
 openless-all/app/src/i18n/ja.ts               |   6 +-
 openless-all/app/src/i18n/ko.ts               |   6 +-
 openless-all/app/src/i18n/zh-CN.ts            |   6 +-
 openless-all/app/src/i18n/zh-TW.ts            |   6 +-
 .../src/pages/settings/RemoteInputSection.tsx |  13 +-
 21 files changed, 1148 insertions(+), 275 deletions(-)
 create mode 100644 docs/remote-input-certificates.md
 create mode 100644 openless-all/app/src-tauri/backend-tests/tests/remote_tls.rs
 create mode 100644 openless-all/app/src-tauri/src/remote_server/tls_identity.rs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 591589e5..b6515e72 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -185,6 +185,9 @@ jobs:
       - name: Test Core
         run: cargo test --locked -p openless-core
 
+      - name: Test remote input TLS identity and Unix key permissions
+        run: cargo test --locked --manifest-path src-tauri/backend-tests/Cargo.toml --test remote_tls
+
   cross-platform:
     name: ${{ matrix.label }} checks
     strategy:
diff --git a/docs/remote-input-certificates.md b/docs/remote-input-certificates.md
new file mode 100644
index 00000000..229019bf
--- /dev/null
+++ b/docs/remote-input-certificates.md
@@ -0,0 +1,92 @@
+# Remote input: one-time phone certificate setup
+
+Remote input needs HTTPS for browser microphone access. OpenLess generates a
+private certificate authority (CA) on each computer and a separate server
+certificate covering that computer's LAN addresses. The phone installs the
+public CA certificate. The CA private key stays in the computer's user data.
+
+## iPhone and iPad
+
+1. Enable remote input on the computer. Use the address shown in settings, on
+   the same network as the computer. Settings also has a **Copy iPhone
+   certificate link** button for each address.
+2. Open the address in Safari. On the initial certificate warning, check the
+   address against the computer, then use **Show Details → Visit This Website**
+   to reach your own computer's setup page. This exception is only a bootstrap
+   step, not the persistent trust setup.
+3. Expand **First-time setup: trust this computer** and choose **iPhone:
+   download profile**. Alternatively, open the copied `/cert.mobileconfig` link
+   directly in Safari.
+4. Install the downloaded profile in **Settings → General → VPN & Device
+   Management**.
+5. In **Settings → General → About → Certificate Trust Settings**, enable full
+   trust for **OpenLess Remote Input CA**. Return to Safari and reload the page.
+6. Enter the pairing code and allow microphone access when Safari asks.
+
+Installing a profile and enabling full SSL trust are separate steps. Apple
+requires the latter for profiles downloaded from a website; a desktop app
+cannot silently approve it on a personal iPhone. See
+[Apple's certificate trust instructions](https://support.apple.com/en-gb/102390).
+This setup removes certificate warnings after trust is established; browser
+microphone permissions and the pairing code remain separate controls.
+
+Only install a CA from your own computer. A CA can issue certificates, so its
+private key is sensitive. Remove the OpenLess profile from the phone when you
+no longer use it. The certificate fingerprint in each profile identifier keeps
+profiles for different computers from replacing one another.
+
+## Android
+
+Download `/cert.cer` using the **Android: download CA** link. Install it through
+the system's **Install a certificate → CA certificate** settings, then return
+to the browser. Menu names and browser support for user-installed CAs vary by
+device. The download contains only the public root certificate.
+
+## What OpenLess automates
+
+- Creates and atomically persists a unique CA and server identity on first use.
+- Reuses the same CA and server certificate after restarts and upgrades that
+  preserve application data.
+- Reissues the server certificate when required LAN or virtual-adapter IPs
+  change, keeping the same CA and therefore the phone's trust.
+- Renews the server certificate on service startup when less than 30 days
+  remain. Leaves are valid for at most 366 days including clock-skew allowance;
+  a continuously running service must restart before its leaf expires.
+- Serves the public CA as a `.cer` file or iOS configuration profile on both
+  Tauri desktop and Linux egui hosts. The private keys are never downloaded.
+- Refuses to start with a damaged, unreadable, mismatched, or expiring CA rather
+  than silently replacing the phone's trust anchor.
+
+## Upgrades, reinstalling, and recovery
+
+Older releases used a directly self-signed leaf (`remote-cert-v4.der`) and
+regenerated it whenever a newly observed IP was absent from a sidecar SAN list.
+Even a virtual-adapter change could invalidate the certificate trusted by the
+phone. Some releases also hid certificate setup and packaged the non-CA leaf
+as a root profile. Upgrading from this format requires the one-time setup above.
+Old files are left intact for rollback; they are not promoted to a CA.
+
+Keep `remote-tls-identity-v1.json` with the application's user configuration
+when backing up or reinstalling. On Windows it is in
+`%APPDATA%\com.openless.app`; on Tauri macOS it is in the application's config
+directory; on Linux egui it is in the host data directory's `remote-input`
+subdirectory. This file contains private keys: do not publish it, send it to a
+phone, or copy it to another computer. Unix files are owner-readable/writable
+only; Windows files inherit the user's application-data ACL.
+
+If this file is damaged, restore the computer's own backup. If it is lost, or
+the CA expires (ten years), explicitly back up/remove the old identity while
+OpenLess is stopped, restart, and install/trust the newly generated CA on each
+phone. Deleting all application data necessarily loses the old trust identity.
+
+## Regression checks
+
+```sh
+cargo test --manifest-path openless-all/app/src-tauri/backend-tests/Cargo.toml --test remote_tls
+node openless-all/app/scripts/remote-input-audio-queue.test.mjs
+```
+
+The TLS tests exercise real rustls handshakes with only the downloaded CA as a
+trust anchor, IP changes, restart reuse, renewal, corrupted keys, persistence
+failure, migration, and separation between two computers. iOS installation and
+microphone recording still require a physical-device smoke test.
diff --git a/openless-all/app/Cargo.lock b/openless-all/app/Cargo.lock
index 646d0d38..a4b807be 100644
--- a/openless-all/app/Cargo.lock
+++ b/openless-all/app/Cargo.lock
@@ -170,6 +170,45 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "asn1-rs"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+dependencies = [
+ "asn1-rs-derive",
+ "asn1-rs-impl",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-traits",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
+[[package]]
+name = "asn1-rs-derive"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "asn1-rs-impl"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "async-broadcast"
 version = "0.7.2"
@@ -978,6 +1017,20 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac6b926516df9c60bfa16e107b21086399f8285a44ca9711344b9e553c5146e2"
 
+[[package]]
+name = "der-parser"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+dependencies = [
+ "asn1-rs",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-bigint",
+ "num-traits",
+ "rusticata-macros",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -2254,6 +2307,12 @@ version = "3.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
 
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
 [[package]]
 name = "libc"
 version = "0.2.189"
@@ -3080,6 +3139,15 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "oid-registry"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
+dependencies = [
+ "asn1-rs",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -3122,6 +3190,7 @@ version = "0.1.0"
 dependencies = [
  "arboard",
  "axum",
+ "base64",
  "cpal",
  "dbus",
  "eframe",
@@ -3137,9 +3206,13 @@ dependencies = [
  "rustls",
  "serde",
  "serde_json",
+ "sha2",
+ "tempfile",
+ "time",
  "tokio",
  "tokio-rustls",
  "uuid",
+ "x509-parser",
 ]
 
 [[package]]
@@ -3638,6 +3711,7 @@ dependencies = [
  "ring",
  "rustls-pki-types",
  "time",
+ "x509-parser",
  "yasna",
 ]
 
@@ -3819,6 +3893,15 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "rusticata-macros"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
+dependencies = [
+ "nom 7.1.3",
+]
+
 [[package]]
 name = "rustix"
 version = "0.38.44"
@@ -4396,6 +4479,7 @@ dependencies = [
  "powerfmt",
  "serde_core",
  "time-core",
+ "time-macros",
 ]
 
 [[package]]
@@ -4404,6 +4488,16 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 
+[[package]]
+name = "time-macros"
+version = "0.2.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.4"
@@ -5698,6 +5792,24 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "x509-parser"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+dependencies = [
+ "asn1-rs",
+ "data-encoding",
+ "der-parser",
+ "lazy_static",
+ "nom 7.1.3",
+ "oid-registry",
+ "ring",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
diff --git a/openless-all/app/linux-egui/Cargo.toml b/openless-all/app/linux-egui/Cargo.toml
index 2cb80cf7..1e35030d 100644
--- a/openless-all/app/linux-egui/Cargo.toml
+++ b/openless-all/app/linux-egui/Cargo.toml
@@ -27,6 +27,11 @@ libc = "0.2"
 axum = { version = "0.7", default-features = false, features = ["ws", "http1", "tokio"] }
 hyper-util = { version = "0.1", features = ["tokio", "server-auto", "server", "http1"] }
 local-ip-address = "0.6"
-rcgen = "0.13"
+base64 = "0.22"
+sha2 = "0.10"
+rcgen = { version = "0.13", features = ["x509-parser"] }
+x509-parser = { version = "0.16", features = ["verify"] }
+time = "0.3"
+tempfile = "3"
 rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12", "logging"] }
 tokio-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12", "logging"] }
diff --git a/openless-all/app/linux-egui/src/remote_input.rs b/openless-all/app/linux-egui/src/remote_input.rs
index c2be6247..070579d9 100644
--- a/openless-all/app/linux-egui/src/remote_input.rs
+++ b/openless-all/app/linux-egui/src/remote_input.rs
@@ -289,71 +289,8 @@ fn access_urls(port: u16) -> Vec<String> {
 }
 
 #[cfg(target_os = "linux")]
-fn load_or_generate_certificate(
-    directory: &std::path::Path,
-    sans: &[String],
-) -> Result<(Vec<u8>, rustls::pki_types::PrivateKeyDer<'static>), BackendError> {
-    use rustls::pki_types::{PrivateKeyDer, PrivatePkcs8KeyDer};
-
-    let cert_path = directory.join("remote-cert-v4.der");
-    let key_path = directory.join("remote-key-v4.der");
-    let sans_path = directory.join("remote-cert-sans-v4.txt");
-    if let (Ok(cert), Ok(key), Ok(saved)) = (
-        std::fs::read(&cert_path),
-        std::fs::read(&key_path),
-        std::fs::read_to_string(&sans_path),
-    ) {
-        let saved = saved.lines().collect::<std::collections::HashSet<_>>();
-        if sans.iter().all(|value| saved.contains(value.as_str())) {
-            return Ok((cert, PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key))));
-        }
-    }
-    let mut params = rcgen::CertificateParams::new(sans.to_vec())
-        .map_err(|error| remote_platform_error(format!("invalid TLS names: {error}")))?;
-    let mut name = rcgen::DistinguishedName::new();
-    name.push(rcgen::DnType::CommonName, "OpenLess Remote Input");
-    params.distinguished_name = name;
-    params
-        .extended_key_usages
-        .push(rcgen::ExtendedKeyUsagePurpose::ServerAuth);
-    let key = rcgen::KeyPair::generate()
-        .map_err(|error| remote_platform_error(format!("TLS key generation failed: {error}")))?;
-    let cert = params
-        .self_signed(&key)
-        .map_err(|error| remote_platform_error(format!("TLS certificate failed: {error}")))?;
-    let cert_der = cert.der().as_ref().to_vec();
-    let key_der = key.serialize_der();
-    std::fs::create_dir_all(directory)
-        .map_err(|error| remote_platform_error(format!("TLS directory failed: {error}")))?;
-    std::fs::write(&cert_path, &cert_der)
-        .map_err(|error| remote_platform_error(format!("TLS certificate save failed: {error}")))?;
-    std::fs::write(&key_path, &key_der)
-        .map_err(|error| remote_platform_error(format!("TLS key save failed: {error}")))?;
-    std::fs::write(&sans_path, sans.join("\n"))
-        .map_err(|error| remote_platform_error(format!("TLS names save failed: {error}")))?;
-    use std::os::unix::fs::PermissionsExt;
-    std::fs::set_permissions(&key_path, std::fs::Permissions::from_mode(0o600))
-        .map_err(|error| remote_platform_error(format!("TLS key permissions failed: {error}")))?;
-    Ok((
-        cert_der,
-        PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key_der)),
-    ))
-}
-
-#[cfg(target_os = "linux")]
-fn tls_config(
-    cert: Vec<u8>,
-    key: rustls::pki_types::PrivateKeyDer<'static>,
-) -> Result<Arc<rustls::ServerConfig>, BackendError> {
-    let provider = Arc::new(rustls::crypto::ring::default_provider());
-    rustls::ServerConfig::builder_with_provider(provider)
-        .with_safe_default_protocol_versions()
-        .map_err(|error| remote_platform_error(format!("TLS protocol failed: {error}")))?
-        .with_no_client_auth()
-        .with_single_cert(vec![rustls::pki_types::CertificateDer::from(cert)], key)
-        .map(Arc::new)
-        .map_err(|error| remote_platform_error(format!("TLS certificate failed: {error}")))
-}
+#[path = "../../src-tauri/src/remote_server/tls_identity.rs"]
+mod tls_identity;
 
 #[cfg(target_os = "linux")]
 fn router(state: Arc<WebState>) -> Router {
@@ -387,14 +324,32 @@ fn router(state: Arc<WebState>) -> Router {
             "/cert.cer",
             get(|State(state): State<Arc<WebState>>| async move {
                 (
-                    [(
-                        axum::http::header::CONTENT_TYPE,
-                        "application/x-x509-ca-cert",
-                    )],
+                    [
+                        (
+                            axum::http::header::CONTENT_TYPE,
+                            "application/x-x509-ca-cert",
+                        ),
+                        (axum::http::header::CACHE_CONTROL, "no-store"),
+                    ],
                     state.cert_der.clone(),
                 )
             }),
         )
+        .route(
+            "/cert.mobileconfig",
+            get(|State(state): State<Arc<WebState>>| async move {
+                (
+                    [
+                        (
+                            axum::http::header::CONTENT_TYPE,
+                            "application/x-apple-aspen-config",
+                        ),
+                        (axum::http::header::CACHE_CONTROL, "no-store"),
+                    ],
+                    tls_identity::mobileconfig(&state.cert_der),
+                )
+            }),
+        )
         .route("/ws", get(websocket_upgrade))
         .with_state(state)
 }
@@ -444,8 +399,10 @@ async fn start_server(
 ) -> Result<LinuxRemoteServerHandle, BackendError> {
     let mut sans = vec!["localhost".to_string(), "127.0.0.1".to_string()];
     sans.extend(local_lan_ipv4s());
-    let (cert_der, key) = load_or_generate_certificate(&data_dir.join("remote-input"), &sans)?;
-    let acceptor = TlsAcceptor::from(tls_config(cert_der.clone(), key)?);
+    let identity = tls_identity::load_or_create(&data_dir.join("remote-input"), &sans)
+        .map_err(remote_platform_error)?;
+    let cert_der = identity.trust_cert;
+    let acceptor = TlsAcceptor::from(identity.server_config);
     let listener = TcpListener::bind(SocketAddr::from(([0, 0, 0, 0], port)))
         .await
         .map_err(|error| remote_platform_error(format!("remote input bind failed: {error}")))?;
diff --git a/openless-all/app/src-tauri/Cargo.lock b/openless-all/app/src-tauri/Cargo.lock
index 46e9fe79..6cacfb09 100644
--- a/openless-all/app/src-tauri/Cargo.lock
+++ b/openless-all/app/src-tauri/Cargo.lock
@@ -180,6 +180,45 @@ version = "0.7.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
 
+[[package]]
+name = "asn1-rs"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+dependencies = [
+ "asn1-rs-derive",
+ "asn1-rs-impl",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-traits",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
+[[package]]
+name = "asn1-rs-derive"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "synstructure",
+]
+
+[[package]]
+name = "asn1-rs-impl"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "async-broadcast"
 version = "0.7.2"
@@ -1394,6 +1433,20 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac6b926516df9c60bfa16e107b21086399f8285a44ca9711344b9e553c5146e2"
 
+[[package]]
+name = "der-parser"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+dependencies = [
+ "asn1-rs",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-bigint",
+ "num-traits",
+ "rusticata-macros",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -4147,6 +4200,15 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "oid-registry"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
+dependencies = [
+ "asn1-rs",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -4260,7 +4322,9 @@ dependencies = [
  "tauri-plugin-shell",
  "tauri-plugin-single-instance",
  "tauri-plugin-updater",
+ "tempfile",
  "thiserror 1.0.69",
+ "time",
  "tokenizers",
  "tokio",
  "tokio-rustls",
@@ -4272,6 +4336,7 @@ dependencies = [
  "window-vibrancy 0.7.1",
  "windows 0.58.0",
  "winreg 0.52.0",
+ "x509-parser",
  "zip 2.4.2",
 ]
 
@@ -5034,6 +5099,7 @@ dependencies = [
  "ring",
  "rustls-pki-types",
  "time",
+ "x509-parser",
  "yasna",
 ]
 
@@ -5331,6 +5397,15 @@ dependencies = [
  "transpose",
 ]
 
+[[package]]
+name = "rusticata-macros"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
+dependencies = [
+ "nom 7.1.3",
+]
+
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -6769,7 +6844,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.3.4",
+ "getrandom 0.4.2",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",
@@ -8886,6 +8961,24 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "x509-parser"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+dependencies = [
+ "asn1-rs",
+ "data-encoding",
+ "der-parser",
+ "lazy_static",
+ "nom 7.1.3",
+ "oid-registry",
+ "ring",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
diff --git a/openless-all/app/src-tauri/Cargo.toml b/openless-all/app/src-tauri/Cargo.toml
index 81385425..8a73e8b6 100644
--- a/openless-all/app/src-tauri/Cargo.toml
+++ b/openless-all/app/src-tauri/Cargo.toml
@@ -81,7 +81,10 @@ tauri-plugin-autostart = "2"
 global-hotkey = "0.6"
 enigo = "0.3"
 arboard = { version = "3", features = ["wayland-data-control"] }
-rcgen = "^0.13"
+rcgen = { version = "0.13", features = ["x509-parser"] }
+x509-parser = { version = "0.16", features = ["verify"] }
+time = "0.3"
+tempfile = "3"
 local-ip-address = "^0.6"
 rustls = { version = "^0.23", default-features = false, features = ["ring", "std", "tls12", "logging"] }
 tokio-rustls = { version = "^0.26", default-features = false, features = ["ring", "tls12", "logging"] }
diff --git a/openless-all/app/src-tauri/backend-tests/Cargo.lock b/openless-all/app/src-tauri/backend-tests/Cargo.lock
index e95ee7d3..a4041cda 100644
--- a/openless-all/app/src-tauri/backend-tests/Cargo.lock
+++ b/openless-all/app/src-tauri/backend-tests/Cargo.lock
@@ -52,6 +52,45 @@ dependencies = [
  "derive_arbitrary",
 ]
 
+[[package]]
+name = "asn1-rs"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+dependencies = [
+ "asn1-rs-derive",
+ "asn1-rs-impl",
+ "displaydoc",
+ "nom",
+ "num-traits",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
+[[package]]
+name = "asn1-rs-derive"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "asn1-rs-impl"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -303,6 +342,20 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac6b926516df9c60bfa16e107b21086399f8285a44ca9711344b9e553c5146e2"
 
+[[package]]
+name = "der-parser"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+dependencies = [
+ "asn1-rs",
+ "displaydoc",
+ "nom",
+ "num-bigint",
+ "num-traits",
+ "rusticata-macros",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -840,6 +893,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
 [[package]]
 name = "libc"
 version = "0.2.189"
@@ -932,6 +991,12 @@ dependencies = [
  "unicase",
 ]
 
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -973,12 +1038,41 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-conv"
 version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -988,6 +1082,15 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "oid-registry"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
+dependencies = [
+ "asn1-rs",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -998,8 +1101,18 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 name = "openless-backend-tests"
 version = "0.1.0"
 dependencies = [
+ "base64",
  "openless-core",
+ "rcgen",
+ "rustls",
+ "serde",
+ "serde_json",
+ "sha2",
+ "tempfile",
+ "time",
  "tokio",
+ "uuid",
+ "x509-parser",
 ]
 
 [[package]]
@@ -1065,6 +1178,16 @@ dependencies = [
  "hmac",
 ]
 
+[[package]]
+name = "pem"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
+dependencies = [
+ "base64",
+ "serde_core",
+]
+
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
@@ -1331,6 +1454,20 @@ dependencies = [
  "rand_core 0.10.1",
 ]
 
+[[package]]
+name = "rcgen"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75e669e5202259b5314d1ea5397316ad400819437857b90861765f24c4cf80a2"
+dependencies = [
+ "pem",
+ "ring",
+ "rustls-pki-types",
+ "time",
+ "x509-parser",
+ "yasna",
+]
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -1470,6 +1607,15 @@ version = "2.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
 
+[[package]]
+name = "rusticata-macros"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
+dependencies = [
+ "nom",
+]
+
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -1809,6 +1955,7 @@ dependencies = [
  "powerfmt",
  "serde_core",
  "time-core",
+ "time-macros",
 ]
 
 [[package]]
@@ -1817,6 +1964,16 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 
+[[package]]
+name = "time-macros"
+version = "0.2.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.4"
@@ -2358,6 +2515,24 @@ version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
+[[package]]
+name = "x509-parser"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+dependencies = [
+ "asn1-rs",
+ "data-encoding",
+ "der-parser",
+ "lazy_static",
+ "nom",
+ "oid-registry",
+ "ring",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
@@ -2377,6 +2552,15 @@ dependencies = [
  "lzma-sys",
 ]
 
+[[package]]
+name = "yasna"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17bb3549cc1321ae1296b9cdc2698e2b6cb1992adfa19a8c72e5b7a738f44cd"
+dependencies = [
+ "time",
+]
+
 [[package]]
 name = "yoke"
 version = "0.8.3"
diff --git a/openless-all/app/src-tauri/backend-tests/Cargo.toml b/openless-all/app/src-tauri/backend-tests/Cargo.toml
index 9a307a76..4588a126 100644
--- a/openless-all/app/src-tauri/backend-tests/Cargo.toml
+++ b/openless-all/app/src-tauri/backend-tests/Cargo.toml
@@ -8,3 +8,14 @@ publish = false
 [dependencies]
 openless-core = { path = "../../crates/openless-core" }
 tokio = { version = "1", features = ["rt-multi-thread"] }
+
+rcgen = { version = "0.13", features = ["x509-parser"] }
+x509-parser = { version = "0.16", features = ["verify"] }
+rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+time = "0.3"
+tempfile = "3"
+base64 = "0.22"
+sha2 = "0.10"
+uuid = { version = "1", features = ["v4"] }
diff --git a/openless-all/app/src-tauri/backend-tests/tests/remote_tls.rs b/openless-all/app/src-tauri/backend-tests/tests/remote_tls.rs
new file mode 100644
index 00000000..a2c4ea46
--- /dev/null
+++ b/openless-all/app/src-tauri/backend-tests/tests/remote_tls.rs
@@ -0,0 +1,3 @@
+// Exercise the production TLS implementation without linking the desktop UI.
+#[path = "../../src/remote_server/tls_identity.rs"]
+mod tls_identity;
diff --git a/openless-all/app/src-tauri/src/remote_server/assets/app.js b/openless-all/app/src-tauri/src/remote_server/assets/app.js
index 66554286..e515a58c 100644
--- a/openless-all/app/src-tauri/src/remote_server/assets/app.js
+++ b/openless-all/app/src-tauri/src/remote_server/assets/app.js
@@ -26,7 +26,7 @@
       offlineTitle: '连接已断开',
       offlineSub: '与电脑的连接已中断。',
       btnReconnect: '重新连接',
-      certTip: '首次访问浏览器会提示“连接不安全”（本地自签名证书）。Android Chrome：点“高级”→“继续前往”；iOS Safari：点“显示详情”→“访问此网站”。',
+      certTip: "如遇证书提示，请核对地址与电脑显示一致，再按“首次设置：信任此电脑”完成安装和完全信任。",
       tipToggle: '点击大按钮开始录音，再次点击结束并识别。',
       tipHold: '按住大按钮说话，松开结束并识别。',
       labelToggleIdle: '点击开始',
@@ -57,10 +57,12 @@
       pcmQueueOverflow: '❌ 音频缓存已满，请重试。',
       micUnknown: '❌ 无法启动录音{name}。',
       errGeneric: '发生错误',
-      helpTitle: '连不上？多半是手机没信任证书',
-      helpAndroid: '① 安卓 / 一般情况：用浏览器无痕模式打开本页，出现“不安全”警告时选“继续前往”，再输入配对码连接。',
-      helpIos: '② iOS Safari：用无痕模式打开本页，出现“不安全”提示时点“显示详情 → 访问此网站”，再输入配对码连接（无需安装证书）。',
-      helpDownloadCert: '⬇ 下载并安装证书',
+      helpTitle: "首次设置：信任此电脑",
+      helpAndroid: "安卓：下载 CA 证书，在系统设置的“安装证书 → CA 证书”中安装，再回到本页。菜单名称因设备而异。",
+      helpIos: "iPhone / iPad：下载描述文件，打开“设置 → 通用 → VPN 与设备管理”安装；再到“通用 → 关于本机 → 证书信任设置”，为 OpenLess Remote Input CA 打开“完全信任”，返回 Safari 刷新。每台电脑只需设置一次；旧版证书需要重新安装。",
+      helpDownloadCert: "↓ iPhone：下载描述文件",
+      helpDownloadAndroid: "↓ 安卓：下载 CA 证书",
+      helpTrustWarning: "首次证书下载无法验证电脑身份，恶意局域网设备可能通过中间人攻击替换根证书。仅在可信的家庭或私人网络中安装，勿在公共或共享网络操作。根证书具备签发能力，私钥保存在这台电脑；不再使用时请从手机移除。",
       helpCopyLink: '⧉ 复制链接',
       helpCopied: '已复制 ✓',
       copy: '复制',
@@ -79,7 +81,7 @@
       offlineTitle: '連線已中斷',
       offlineSub: '與電腦的連線已中斷。',
       btnReconnect: '重新連線',
-      certTip: '首次造訪瀏覽器會提示「連線不安全」（本機自簽憑證）。Android Chrome：點「進階」→「繼續前往」；iOS Safari：點「顯示詳細資訊」→「瀏覽此網站」。',
+      certTip: "如遇憑證提示，請核對位址與電腦顯示一致，再依「首次設定：信任這台電腦」完成安裝與完全信任。",
       tipToggle: '點擊大按鈕開始錄音，再次點擊結束並辨識。',
       tipHold: '按住大按鈕說話，放開結束並辨識。',
       labelToggleIdle: '點擊開始',
@@ -110,10 +112,12 @@
       pcmQueueOverflow: '❌ 音訊暫存已滿，請重試。',
       micUnknown: '❌ 無法啟動錄音{name}。',
       errGeneric: '發生錯誤',
-      helpTitle: '連不上？多半是手機沒信任憑證',
-      helpAndroid: '① 安卓 / 一般情況：用瀏覽器無痕模式開啟本頁，出現“不安全”警告時選“繼續前往”，再輸入配對碼連線。',
-      helpIos: '② iOS Safari：用無痕模式開啟本頁，出現“不安全”提示時點“顯示詳細資訊 → 瀏覽此網站”，再輸入配對碼連線（無需安裝憑證）。',
-      helpDownloadCert: '⬇ 下載並安裝憑證',
+      helpTitle: "首次設定：信任這台電腦",
+      helpAndroid: "Android：下載 CA 憑證，在系統設定的「安裝憑證 → CA 憑證」中安裝，再返回本頁。選單名稱依裝置而異。",
+      helpIos: "iPhone / iPad：下載描述檔，開啟「設定 → 一般 → VPN 與裝置管理」安裝；再到「一般 → 關於本機 → 憑證信任設定」，為 OpenLess Remote Input CA 開啟「完全信任」，返回 Safari 重新整理。每台電腦只需設定一次；舊版憑證需要重新安裝。",
+      helpDownloadCert: "↓ iPhone：下載描述檔",
+      helpDownloadAndroid: "↓ Android：下載 CA 憑證",
+      helpTrustWarning: "首次憑證下載無法驗證電腦身分，惡意區域網路裝置可能透過中間人攻擊替換根憑證。僅在可信任的家庭或私人網路中安裝，請勿在公共或共享網路操作。根憑證能簽發憑證，私密金鑰保存在這台電腦；不再使用時請從手機移除。",
       helpCopyLink: '⧉ 複製連結',
       helpCopied: '已複製 ✓',
       copy: '複製',
@@ -132,7 +136,7 @@
       offlineTitle: 'Disconnected',
       offlineSub: 'The connection to your computer was lost.',
       btnReconnect: 'Reconnect',
-      certTip: 'On first visit the browser will warn "Not secure" (local self-signed certificate). Android Chrome: tap "Advanced" → "Proceed"; iOS Safari: tap "Show Details" → "visit this website".',
+      certTip: "If a certificate warning appears, check that the address matches your computer, then follow “First-time setup: trust this computer” to install and fully trust the certificate.",
       tipToggle: 'Tap the big button to start recording, tap again to finish and transcribe.',
       tipHold: 'Hold the big button to talk, release to finish and transcribe.',
       labelToggleIdle: 'Tap to start',
@@ -163,10 +167,12 @@
       pcmQueueOverflow: '❌ Audio buffer is full. Please try again.',
       micUnknown: '❌ Could not start recording{name}.',
       errGeneric: 'An error occurred',
-      helpTitle: "Can't connect? The phone probably doesn't trust the certificate",
-      helpAndroid: '① Android / general: open this page in an incognito tab, choose "Proceed" on the "Not secure" warning, then enter the pairing code.',
-      helpIos: '② iOS Safari: open this page in an incognito tab; on the "Not Private" warning tap "Show Details → visit this website", then enter the code (no certificate install needed).',
-      helpDownloadCert: '⬇ Download & install cert',
+      helpTitle: "First-time setup: trust this computer",
+      helpAndroid: "Android: download the CA certificate, install it under system Settings → Install a certificate → CA certificate, then return here. Menu names vary by device.",
+      helpIos: "iPhone / iPad: download the profile and install it in Settings → General → VPN & Device Management. Then enable full trust for OpenLess Remote Input CA in General → About → Certificate Trust Settings and reload Safari. Set up once per computer; certificates from older versions need this one-time replacement.",
+      helpDownloadCert: "↓ iPhone: download profile",
+      helpDownloadAndroid: "↓ Android: download CA",
+      helpTrustWarning: "The initial certificate download cannot verify the computer's identity; a malicious device on the LAN could replace the root certificate in a man-in-the-middle attack. Install it only on a trusted home or private network, never on a public or shared network. The root CA can issue certificates and its private key stays on this computer; remove it from your phone when no longer needed.",
       helpCopyLink: '⧉ Copy link',
       helpCopied: 'Copied ✓',
       copy: 'Copy',
@@ -185,7 +191,7 @@
       offlineTitle: '接続が切断されました',
       offlineSub: 'パソコンとの接続が切断されました。',
       btnReconnect: '再接続',
-      certTip: '初回アクセス時、ブラウザに「保護されていません」と表示されます（ローカル自己署名証明書）。Android Chrome：「詳細設定」→「アクセスする」、iOS Safari：「詳細を表示」→「このWebサイトを閲覧」をタップしてください。',
+      certTip: "証明書の警告が表示されたら、アドレスがコンピュータの表示と一致することを確認し、「初回設定：このコンピュータを信頼」の手順でインストールと完全な信頼を行ってください。",
       tipToggle: '大きいボタンをタップして録音開始、もう一度タップで終了して認識します。',
       tipHold: '大きいボタンを長押しして話し、離すと終了して認識します。',
       labelToggleIdle: 'タップで開始',
@@ -216,10 +222,12 @@
       pcmQueueOverflow: '❌ 音声バッファがいっぱいです。もう一度お試しください。',
       micUnknown: '❌ 録音を開始できませんでした{name}。',
       errGeneric: 'エラーが発生しました',
-      helpTitle: '接続できない？多くは証明書が信頼されていません',
-      helpAndroid: '① Android / 一般：ブラウザのシークレットモードで本ページを開き、「保護されていません」で「アクセスする」を選び、ペアリングコードを入力。',
-      helpIos: '② iOS Safari：シークレットモードで本ページを開き、「安全ではありません」で「詳細を表示 → このWebサイトにアクセス」をタップしてコードを入力（証明書のインストール不要）。',
-      helpDownloadCert: '⬇ 証明書をインストール',
+      helpTitle: "初回設定：このコンピュータを信頼",
+      helpAndroid: "Android：CA 証明書をダウンロードし、システム設定の「証明書のインストール → CA 証明書」でインストールしてから戻ってください。項目名は端末により異なります。",
+      helpIos: "iPhone / iPad：プロファイルをダウンロードし、「設定 → 一般 → VPN とデバイス管理」でインストールします。次に「一般 → 情報 → 証明書信頼設定」で OpenLess Remote Input CA を完全に信頼し、Safari を再読み込みしてください。各コンピュータで一度だけ必要です。旧バージョンの証明書は一度入れ替えてください。",
+      helpDownloadCert: "↓ iPhone：プロファイルをダウンロード",
+      helpDownloadAndroid: "↓ Android：CA をダウンロード",
+      helpTrustWarning: "初回の証明書ダウンロードではコンピューターの身元を確認できず、LAN 上の悪意あるデバイスが中間者攻撃でルート証明書を置き換える可能性があります。信頼できる家庭内またはプライベートネットワークでのみインストールし、公共または共有ネットワークでは操作しないでください。ルート CA は証明書を発行でき、秘密鍵はこのコンピューターに保存されます。不要になったらスマートフォンから削除してください。",
       helpCopyLink: '⧉ リンクをコピー',
       helpCopied: 'コピーしました ✓',
       copy: 'コピー',
@@ -238,7 +246,7 @@
       offlineTitle: '연결이 끊겼습니다',
       offlineSub: '컴퓨터와의 연결이 끊겼습니다.',
       btnReconnect: '다시 연결',
-      certTip: '처음 접속하면 브라우저에 "안전하지 않음" 경고가 표시됩니다(로컬 자체 서명 인증서). Android Chrome: "고급" → "계속 진행"; iOS Safari: "세부정보 표시" → "이 웹사이트 방문"을 탭하세요.',
+      certTip: "인증서 경고가 나타나면 주소가 컴퓨터에 표시된 주소와 일치하는지 확인한 뒤 “최초 설정: 이 컴퓨터 신뢰”에 따라 인증서를 설치하고 완전히 신뢰하세요.",
       tipToggle: '큰 버튼을 탭하여 녹음을 시작하고, 다시 탭하면 종료 후 인식합니다.',
       tipHold: '큰 버튼을 길게 눌러 말하고, 떼면 종료 후 인식합니다.',
       labelToggleIdle: '탭하여 시작',
@@ -269,10 +277,12 @@
       pcmQueueOverflow: '❌ 오디오 버퍼가 가득 찼습니다. 다시 시도하세요.',
       micUnknown: '❌ 녹음을 시작할 수 없습니다{name}.',
       errGeneric: '오류가 발생했습니다',
-      helpTitle: '연결이 안 되나요? 대개 인증서를 신뢰하지 않아서입니다',
-      helpAndroid: '① Android / 일반: 시크릿 모드로 이 페이지를 열고 "안전하지 않음" 경고에서 "계속"을 선택한 뒤 페어링 코드를 입력하세요.',
-      helpIos: '② iOS Safari: 시크릿 모드로 이 페이지를 열고 "안전하지 않음" 경고에서 "세부사항 표시 → 이 웹사이트 방문"을 누른 뒤 코드를 입력하세요(인증서 설치 불필요).',
-      helpDownloadCert: '⬇ 인증서 설치',
+      helpTitle: "최초 설정: 이 컴퓨터 신뢰",
+      helpAndroid: "Android: CA 인증서를 다운로드하고 시스템 설정 → 인증서 설치 → CA 인증서에서 설치한 뒤 돌아오세요. 메뉴 이름은 기기마다 다릅니다.",
+      helpIos: "iPhone / iPad: 프로파일을 다운로드하고 설정 → 일반 → VPN 및 기기 관리에서 설치하세요. 일반 → 정보 → 인증서 신뢰 설정에서 OpenLess Remote Input CA를 완전히 신뢰한 뒤 Safari를 새로고침하세요. 컴퓨터마다 한 번만 설정하면 됩니다. 이전 버전의 인증서는 한 번 교체해야 합니다.",
+      helpDownloadCert: "↓ iPhone: 프로파일 다운로드",
+      helpDownloadAndroid: "↓ Android: CA 다운로드",
+      helpTrustWarning: "최초 인증서 다운로드에서는 컴퓨터의 신원을 확인할 수 없으며, LAN의 악성 기기가 중간자 공격으로 루트 인증서를 바꿀 수 있습니다. 신뢰할 수 있는 가정용 또는 사설 네트워크에서만 설치하고 공용 또는 공유 네트워크에서는 진행하지 마세요. 루트 CA는 인증서를 발급할 수 있고 개인 키는 이 컴퓨터에 저장됩니다. 더 이상 사용하지 않으면 휴대폰에서 제거하세요.",
       helpCopyLink: '⧉ 링크 복사',
       helpCopied: '복사됨 ✓',
       copy: '복사',
@@ -838,7 +848,7 @@
   }
   if (copyCertBtn) {
     copyCertBtn.addEventListener('click', function () {
-      var url = location.origin + '/cert.cer';
+      var url = location.origin + '/cert.mobileconfig';
       var ok = function () {
         copyCertBtn.textContent = L.helpCopied;
         setTimeout(function () { copyCertBtn.textContent = L.helpCopyLink; }, 1500);
diff --git a/openless-all/app/src-tauri/src/remote_server/assets/index.html b/openless-all/app/src-tauri/src/remote_server/assets/index.html
index 05c26cbb..14f6a12f 100644
--- a/openless-all/app/src-tauri/src/remote_server/assets/index.html
+++ b/openless-all/app/src-tauri/src/remote_server/assets/index.html
@@ -35,16 +35,18 @@
         <button id="btn-connect" class="btn btn-primary" data-i18n="btnConnect">连接</button>
       </div>
 
-      <!-- 连接帮助：证书信任引导（手机上直接照做）。暂时隐藏（用户要求），需要时去掉 hidden 即可恢复。 -->
-      <div class="help" hidden>
-        <div class="help-title" data-i18n="helpTitle">连不上？多半是手机没信任证书</div>
-        <p class="help-step" data-i18n="helpAndroid">① 安卓 / 一般情况：用浏览器无痕模式打开本页，出现“不安全”警告时选“继续前往”，再输入配对码连接。</p>
-        <p class="help-step" data-i18n="helpIos">② iOS Safari 必须装证书：点下方按钮下载并安装描述文件，然后到「设置 → 通用 → 关于本机 → 证书信任设置」里打开它的“完全信任”，再回来连接。</p>
+      <!-- Keep setup discoverable without obscuring the pairing form. -->
+      <details class="help">
+        <summary class="help-title" data-i18n="helpTitle">首次设置：信任此电脑</summary>
+        <p class="help-step" data-i18n="helpIos">iPhone / iPad：下载描述文件，打开“设置 → 通用 → VPN 与设备管理”安装；再到“通用 → 关于本机 → 证书信任设置”，为 OpenLess Remote Input CA 打开“完全信任”，返回 Safari 刷新。每台电脑只需设置一次；旧版证书需要重新安装。</p>
+        <p class="help-step" data-i18n="helpAndroid">安卓：下载 CA 证书，在系统设置的“安装证书 → CA 证书”中安装，再回到本页。菜单名称因设备而异。</p>
+        <p class="help-step" data-i18n="helpTrustWarning">只安装你自己电脑提供的 OpenLess 根证书。它具备签发证书的能力，私钥保存在这台电脑；不再使用时请从手机移除。</p>
         <div class="help-actions">
-          <a class="help-link" href="/cert.cer" data-i18n="helpDownloadCert">⬇ 下载并安装证书</a>
+          <a class="help-link" href="/cert.mobileconfig" data-i18n="helpDownloadCert">↓ iPhone：下载描述文件</a>
+          <a class="help-link help-link-ghost" href="/cert.cer" data-i18n="helpDownloadAndroid">↓ 安卓：下载 CA 证书</a>
           <button type="button" class="help-link help-link-ghost" id="copy-cert-link" data-i18n="helpCopyLink">⧉ 复制链接</button>
         </div>
-      </div>
+      </details>
     </section>
 
     <!-- ===== 录音屏 ===== -->
diff --git a/openless-all/app/src-tauri/src/remote_server/assets/style.css b/openless-all/app/src-tauri/src/remote_server/assets/style.css
index 3b3ab4fd..36a45958 100644
--- a/openless-all/app/src-tauri/src/remote_server/assets/style.css
+++ b/openless-all/app/src-tauri/src/remote_server/assets/style.css
@@ -243,7 +243,9 @@ body {
   font-weight: 600;
   color: var(--ink-2);
   margin-bottom: 10px;
+  cursor: pointer;
 }
+.help:not([open]) .help-title { margin-bottom: 0; }
 .help-step {
   font-size: 12.5px;
   color: var(--ink-3);
diff --git a/openless-all/app/src-tauri/src/remote_server/mod.rs b/openless-all/app/src-tauri/src/remote_server/mod.rs
index 6c2352fe..e78df6e9 100644
--- a/openless-all/app/src-tauri/src/remote_server/mod.rs
+++ b/openless-all/app/src-tauri/src/remote_server/mod.rs
@@ -5,9 +5,10 @@
 //! 手机录音以 16k/单声道/16-bit LE PCM 经 WebSocket 实时推回 PC，并通过共享
 //! [`openless_core::OpenLessBackend`] 的 external-audio seam 进入同一听写管线。
 //!
-//! 关键约束：浏览器 `getUserMedia` 仅在安全上下文可用，所以必须 HTTPS。证书用
-//! rcgen 自签名（SAN 含本机局域网 IP），手机首次访问需手动信任。TLS 走 ring
-//! 后端（与项目 reqwest/tungstenite 一致，避免 aws-lc-sys 的 C 编译依赖）。
+//! Browser microphone access requires a secure context, so this server uses HTTPS.
+//! A persistent per-installation CA signs a separate LAN server certificate.
+//! Phones install and trust the CA once. TLS uses ring
+//! (matching reqwest/tungstenite and avoiding an additional aws-lc-sys dependency).
 
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::sync::Arc;
@@ -172,106 +173,13 @@ pub fn access_urls(port: u16) -> Vec<String> {
 
 // ───────────────────────── TLS ─────────────────────────
 
-/// 自签名证书：持久化到磁盘并跨重启复用。否则每次启动证书都变 —— 手机（尤其 iOS
-/// Safari）上一次信任过的证书立刻失效，wss 握手静默挂起，表现为"连接中"卡死。仅当
-/// 磁盘无证书 / 解析失败 / 当前局域网 IP 不在已存 SAN 列表里（换了网络）时才重新生成。
-/// 返回 (证书 DER 原始字节, 私钥)。
-fn load_or_generate_cert(
-    dir: Option<&std::path::Path>,
-    sans: &[String],
-) -> Result<(Vec<u8>, rustls::pki_types::PrivateKeyDer<'static>), String> {
-    use rustls::pki_types::{PrivateKeyDer, PrivatePkcs8KeyDer};
-    // 文件名带 schema 版本：证书结构变更（v4 改回非 CA 服务器证书）时旧文件自动失效、重新生成。
-    const CERT_FILE: &str = "remote-cert-v4.der";
-    const KEY_FILE: &str = "remote-key-v4.der";
-    const SANS_FILE: &str = "remote-cert-sans-v4.txt";
-    if let Some(dir) = dir {
-        if let (Ok(cert), Ok(key), Ok(saved)) = (
-            std::fs::read(dir.join(CERT_FILE)),
-            std::fs::read(dir.join(KEY_FILE)),
-            std::fs::read_to_string(dir.join(SANS_FILE)),
-        ) {
-            let saved_set: std::collections::HashSet<&str> = saved.lines().collect();
-            // 当前需要的 SAN 都在已存证书里 → 复用，证书保持稳定（手机信任一次长期有效）。
-            if sans.iter().all(|s| saved_set.contains(s.as_str())) {
-                log::info!("[remote-input] reusing persisted self-signed server cert");
-                return Ok((cert, PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key))));
-            }
-        }
-    }
-    // 生成自签名服务器证书（SAN 含本机各局域网 IP）。主路径是浏览器页面级
-    // “继续访问/访问此网站”例外；/cert.cer 与 /cert.mobileconfig 是手机系统级
-    // 安装信任的兜底（部分浏览器的 wss 不复用页面级例外时使用）。
-    let (cert_der, key_der) = {
-        use rcgen::{
-            CertificateParams, DistinguishedName, DnType, ExtendedKeyUsagePurpose, KeyPair,
-            KeyUsagePurpose,
-        };
-        let mut params =
-            CertificateParams::new(sans.to_vec()).map_err(|e| format!("rcgen params: {e}"))?;
-        // 关键：做成普通服务器证书（非 CA，rcgen 默认即 NoCa）。iOS Safari 用页面级
-        // “访问此网站”即可信任、无需安装证书 —— 这正是之前一直能用的方式。把证书做成 CA
-        // 反而会让 iOS 拒绝页面级例外（CA 不能直接当服务器证书），导致一直超时。
-        let mut dn = DistinguishedName::new();
-        dn.push(DnType::CommonName, "OpenLess Remote Input");
-        dn.push(DnType::OrganizationName, "OpenLess");
-        params.distinguished_name = dn;
-        params.key_usages.push(KeyUsagePurpose::DigitalSignature);
-        params
-            .extended_key_usages
-            .push(ExtendedKeyUsagePurpose::ServerAuth);
-        let key_pair = KeyPair::generate().map_err(|e| format!("rcgen keypair: {e}"))?;
-        let cert = params
-            .self_signed(&key_pair)
-            .map_err(|e| format!("rcgen self_signed: {e}"))?;
-        (cert.der().as_ref().to_vec(), key_pair.serialize_der())
-    };
-    if let Some(dir) = dir {
-        let _ = std::fs::create_dir_all(dir);
-        let _ = std::fs::write(dir.join(CERT_FILE), &cert_der);
-        let _ = std::fs::write(dir.join(KEY_FILE), &key_der);
-        // 私钥收紧为 0600：app 配置目录通常已是用户私有，但多用户/共享主机上
-        // 默认 umask 可能给到组/其他用户可读。Windows 下 %APPDATA% 的 ACL
-        // 本身仅限本用户，无对应权限位可设。
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            let _ = std::fs::set_permissions(
-                dir.join(KEY_FILE),
-                std::fs::Permissions::from_mode(0o600),
-            );
-        }
-        let _ = std::fs::write(dir.join(SANS_FILE), sans.join("\n"));
-        log::info!("[remote-input] generated new self-signed server cert (SAN={sans:?})");
-    }
-    Ok((
-        cert_der,
-        PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key_der)),
-    ))
-}
-
-fn build_server_config(
-    cert_der: Vec<u8>,
-    key_der: rustls::pki_types::PrivateKeyDer<'static>,
-) -> Result<Arc<rustls::ServerConfig>, String> {
-    let provider = Arc::new(rustls::crypto::ring::default_provider());
-    let config = rustls::ServerConfig::builder_with_provider(provider)
-        .with_safe_default_protocol_versions()
-        .map_err(|e| format!("tls protocol: {e}"))?
-        .with_no_client_auth()
-        .with_single_cert(
-            vec![rustls::pki_types::CertificateDer::from(cert_der)],
-            key_der,
-        )
-        .map_err(|e| format!("tls cert: {e}"))?;
-    Ok(Arc::new(config))
-}
+mod tls_identity;
 
 // ───────────────────────── 启动 ─────────────────────────
 
 struct WsState {
     backend: Arc<openless_core::OpenLessBackend>,
-    /// 自签名证书的 DER 原始字节，供 /cert.cer 下载给手机安装信任。
+    /// Public CA certificate offered for phone installation; never the server leaf or key.
     cert_der: Vec<u8>,
     /// 服务关停广播的接收端，每条 WS 连接 clone 一份并在主循环 select 监听。
     conn_shutdown_rx: tokio::sync::watch::Receiver<bool>,
@@ -336,10 +244,13 @@ fn build_router(state: Arc<WsState>) -> Router {
             "/cert.cer",
             get(|State(state): State<Arc<WsState>>| async move {
                 (
-                    [(
-                        axum::http::header::CONTENT_TYPE,
-                        "application/x-x509-ca-cert",
-                    )],
+                    [
+                        (
+                            axum::http::header::CONTENT_TYPE,
+                            "application/x-x509-ca-cert",
+                        ),
+                        (axum::http::header::CACHE_CONTROL, "no-store"),
+                    ],
                     state.cert_der.clone(),
                 )
             }),
@@ -372,53 +283,17 @@ async fn index_handler(State(state): State<Arc<WsState>>) -> impl IntoResponse {
     )
 }
 
-/// 极简标准 base64：构造 .mobileconfig 时把证书 DER 编码进 XML，避免引入额外依赖。
-fn base64_encode(data: &[u8]) -> String {
-    const T: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-    let mut out = String::with_capacity((data.len() + 2) / 3 * 4);
-    for chunk in data.chunks(3) {
-        let b0 = chunk[0];
-        let b1 = *chunk.get(1).unwrap_or(&0);
-        let b2 = *chunk.get(2).unwrap_or(&0);
-        out.push(T[(b0 >> 2) as usize] as char);
-        out.push(T[(((b0 & 0x03) << 4) | (b1 >> 4)) as usize] as char);
-        out.push(if chunk.len() > 1 {
-            T[(((b1 & 0x0f) << 2) | (b2 >> 6)) as usize] as char
-        } else {
-            '='
-        });
-        out.push(if chunk.len() > 2 {
-            T[(b2 & 0x3f) as usize] as char
-        } else {
-            '='
-        });
-    }
-    out
-}
-
-/// iOS 配置描述文件：把证书包成 .mobileconfig。Safari 点击后凭 content-type
-/// (application/x-apple-aspen-config) 直接进入“安装描述文件”流程，比裸 .cer 顺滑、
-/// 也不会把当前页面导航走。安装后仍需到「设置→通用→关于本机→证书信任设置」打开完全信任。
-///
-/// 安全边界：PayloadType `com.apple.security.root` 只是 iOS 安装证书的固定入口，
-/// 证书本身是非 CA 的纯服务器证书（rcgen NoCa + EKU=ServerAuth，见
-/// load_or_generate_cert）——不含签发能力，无法用来给其他域名签证书做 MITM。
-/// 信任它的影响范围仅限「持有本机私钥者可冒充 SAN 里列出的本机局域网 IP」，
-/// 私钥只存在用户 PC 的应用配置目录。设置页 certTrustWarning 同步向用户说明。
+// iOS still requires the user to install the profile and enable full trust.
 async fn mobileconfig_handler(State(state): State<Arc<WsState>>) -> impl IntoResponse {
-    let b64 = base64_encode(&state.cert_der);
-    let xml = format!(
-        r#"<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0"><dict><key>PayloadContent</key><array><dict><key>PayloadCertificateFileName</key><string>openless.cer</string><key>PayloadContent</key><data>{b64}</data><key>PayloadType</key><string>com.apple.security.root</string><key>PayloadIdentifier</key><string>com.openless.remote-input.cert</string><key>PayloadUUID</key><string>A1B2C3D4-0001-4000-8000-000000000001</string><key>PayloadVersion</key><integer>1</integer><key>PayloadDisplayName</key><string>OpenLess Remote Input Certificate</string></dict></array><key>PayloadDisplayName</key><string>OpenLess Remote Input</string><key>PayloadIdentifier</key><string>com.openless.remote-input</string><key>PayloadType</key><string>Configuration</string><key>PayloadUUID</key><string>A1B2C3D4-0002-4000-8000-000000000002</string><key>PayloadVersion</key><integer>1</integer></dict></plist>"#,
-        b64 = b64
-    );
     (
-        [(
-            axum::http::header::CONTENT_TYPE,
-            "application/x-apple-aspen-config",
-        )],
-        xml,
+        [
+            (
+                axum::http::header::CONTENT_TYPE,
+                "application/x-apple-aspen-config",
+            ),
+            (axum::http::header::CACHE_CONTROL, "no-store"),
+        ],
+        tls_identity::mobileconfig(&state.cert_der),
     )
 }
 
@@ -428,11 +303,15 @@ pub async fn start(cfg: RemoteServerConfig) -> Result<RemoteServerHandle, String
     for ip in local_lan_ipv4s() {
         sans.push(ip.to_string());
     }
-    // 证书目录用 app 配置目录（跨重启稳定）；拿不到则退回内存生成（不持久化）。
-    let cert_dir = cfg.app.path().app_config_dir().ok();
-    let (cert_der, key_der) = load_or_generate_cert(cert_dir.as_deref(), &sans)?;
-    let rustls_config = build_server_config(cert_der.clone(), key_der)?;
-    let acceptor = TlsAcceptor::from(rustls_config);
+    // Trust must survive restarts and upgrades; refuse ephemeral identities.
+    let cert_dir = cfg
+        .app
+        .path()
+        .app_config_dir()
+        .map_err(|error| format!("remote TLS config directory: {error}"))?;
+    let identity = tls_identity::load_or_create(&cert_dir, &sans)?;
+    let cert_der = identity.trust_cert;
+    let acceptor = TlsAcceptor::from(identity.server_config);
 
     let addr = SocketAddr::from(([0, 0, 0, 0], cfg.port));
     let listener = TcpListener::bind(addr).await.map_err(|e| {
diff --git a/openless-all/app/src-tauri/src/remote_server/tls_identity.rs b/openless-all/app/src-tauri/src/remote_server/tls_identity.rs
new file mode 100644
index 00000000..42752f9e
--- /dev/null
+++ b/openless-all/app/src-tauri/src/remote_server/tls_identity.rs
@@ -0,0 +1,506 @@
+//! A persistent, per-installation CA and a separate short-lived TLS leaf.
+//! Phones trust the CA once; changes to LAN or virtual-adapter IPs only reissue
+//! the leaf. Never silently replace an unreadable CA: that revokes phone trust.
+
+use std::io::{Read, Write};
+use std::path::Path;
+use std::sync::Arc;
+
+use rcgen::{
+    BasicConstraints, CertificateParams, DistinguishedName, DnType, ExtendedKeyUsagePurpose, IsCa,
+    KeyPair, KeyUsagePurpose,
+};
+use rustls::pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer};
+use serde::{Deserialize, Serialize};
+use time::{Duration, OffsetDateTime};
+
+const IDENTITY_FILE: &str = "remote-tls-identity-v1.json";
+const MAX_IDENTITY_BYTES: u64 = 64 * 1024;
+
+#[derive(Serialize, Deserialize)]
+struct StoredIdentity {
+    ca_cert: Vec<u8>,
+    ca_key: Vec<u8>,
+    leaf_cert: Vec<u8>,
+    leaf_key: Vec<u8>,
+}
+
+pub(super) struct TlsIdentity {
+    /// Only this public CA certificate is offered for phone installation.
+    pub trust_cert: Vec<u8>,
+    pub server_config: Arc<rustls::ServerConfig>,
+}
+
+fn key_der(bytes: Vec<u8>) -> PrivateKeyDer<'static> {
+    PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(bytes))
+}
+
+fn matching_key(cert: &[u8], key: &[u8]) -> Result<(), String> {
+    rustls::sign::CertifiedKey::from_der(
+        vec![CertificateDer::from(cert.to_vec())],
+        key_der(key.to_vec()),
+        &rustls::crypto::ring::default_provider(),
+    )
+    .map(|_| ())
+    .map_err(|error| format!("remote TLS certificate/key mismatch: {error}"))
+}
+
+fn parse_cert(cert: &[u8]) -> Result<CertificateParams, String> {
+    CertificateParams::from_ca_cert_der(&CertificateDer::from(cert))
+        .map_err(|error| format!("invalid remote TLS certificate: {error}"))
+}
+
+fn read_identity(path: &Path) -> Result<Option<StoredIdentity>, String> {
+    let metadata = match std::fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => return Err(format!("cannot inspect remote TLS identity: {error}")),
+    };
+    if !metadata.is_file() || metadata.len() > MAX_IDENTITY_BYTES {
+        return Err("remote TLS identity must be a regular file under 64 KiB".into());
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))
+            .map_err(|error| format!("cannot protect remote TLS identity: {error}"))?;
+    }
+    let mut bytes = Vec::new();
+    std::fs::File::open(path)
+        .and_then(|file| file.take(MAX_IDENTITY_BYTES + 1).read_to_end(&mut bytes))
+        .map_err(|error| format!("cannot read remote TLS identity: {error}"))?;
+    if bytes.len() as u64 > MAX_IDENTITY_BYTES {
+        return Err("remote TLS identity exceeds 64 KiB".into());
+    }
+    serde_json::from_slice(&bytes)
+        .map(Some)
+        .map_err(|_| "remote TLS identity is damaged; restore it from backup instead of replacing phone trust".into())
+}
+
+fn save_identity(
+    path: &Path,
+    identity: &StoredIdentity,
+    first_install: bool,
+) -> Result<(), String> {
+    let directory = path.parent().ok_or("remote TLS directory is unavailable")?;
+    let bytes = serde_json::to_vec(identity).map_err(|error| error.to_string())?;
+    // tempfile creates private files (0600 on Unix). Windows inherits the user's
+    // application-data ACL. Keep the key and certificates in one atomic bundle.
+    let mut file = tempfile::NamedTempFile::new_in(directory)
+        .map_err(|error| format!("cannot create remote TLS identity: {error}"))?;
+    file.write_all(&bytes)
+        .and_then(|_| file.as_file().sync_all())
+        .map_err(|error| format!("cannot write remote TLS identity: {error}"))?;
+    if first_install {
+        file.persist_noclobber(path)
+    } else {
+        file.persist(path)
+    }
+    .map_err(|error| format!("cannot persist remote TLS identity: {error}"))?;
+    Ok(())
+}
+
+fn create_ca(now: OffsetDateTime) -> Result<StoredIdentity, String> {
+    let mut params = CertificateParams::default();
+    let mut name = DistinguishedName::new();
+    name.push(DnType::CommonName, "OpenLess Remote Input CA");
+    name.push(DnType::OrganizationName, "OpenLess");
+    params.distinguished_name = name;
+    params.is_ca = IsCa::Ca(BasicConstraints::Constrained(0));
+    params.key_usages = vec![KeyUsagePurpose::KeyCertSign, KeyUsagePurpose::CrlSign];
+    params.not_before = now - Duration::days(1);
+    params.not_after = now + Duration::days(3650);
+    let key = KeyPair::generate().map_err(|error| error.to_string())?;
+    let cert = params
+        .self_signed(&key)
+        .map_err(|error| error.to_string())?;
+    Ok(StoredIdentity {
+        ca_cert: cert.der().to_vec(),
+        ca_key: key.serialize_der(),
+        leaf_cert: Vec::new(),
+        leaf_key: Vec::new(),
+    })
+}
+
+fn valid_leaf(identity: &StoredIdentity, sans: &[String], now: OffsetDateTime) -> bool {
+    let Ok(params) = parse_cert(&identity.leaf_cert) else {
+        return false;
+    };
+    let Ok(required) = CertificateParams::new(sans.to_vec()) else {
+        return false;
+    };
+    if !matches!(params.is_ca, IsCa::NoCa | IsCa::ExplicitNoCa)
+        || params.not_before > now
+        || params.not_after < now + Duration::days(30)
+        || !required
+            .subject_alt_names
+            .iter()
+            .all(|san| params.subject_alt_names.contains(san))
+        || matching_key(&identity.leaf_cert, &identity.leaf_key).is_err()
+    {
+        return false;
+    }
+    // Validate the cached leaf against the stored trust anchor, not a sidecar
+    // list of SANs. A stale or mismatched leaf must never reach the listener.
+    use rustls::client::danger::ServerCertVerifier;
+    let mut roots = rustls::RootCertStore::empty();
+    if roots
+        .add(CertificateDer::from(identity.ca_cert.clone()))
+        .is_err()
+    {
+        return false;
+    }
+    let Ok(verifier) = rustls::client::WebPkiServerVerifier::builder_with_provider(
+        Arc::new(roots),
+        Arc::new(rustls::crypto::ring::default_provider()),
+    )
+    .build() else {
+        return false;
+    };
+    let Some(name) = sans
+        .first()
+        .and_then(|name| rustls::pki_types::ServerName::try_from(name.clone()).ok())
+    else {
+        return false;
+    };
+    let Ok(timestamp) = u64::try_from(now.unix_timestamp()) else {
+        return false;
+    };
+    verifier
+        .verify_server_cert(
+            &CertificateDer::from(identity.leaf_cert.as_slice()),
+            &[],
+            &name,
+            &[],
+            rustls::pki_types::UnixTime::since_unix_epoch(std::time::Duration::from_secs(
+                timestamp,
+            )),
+        )
+        .is_ok()
+}
+
+pub(super) fn load_or_create(directory: &Path, sans: &[String]) -> Result<TlsIdentity, String> {
+    load_at(directory, sans, OffsetDateTime::now_utc())
+}
+
+fn load_at(directory: &Path, sans: &[String], now: OffsetDateTime) -> Result<TlsIdentity, String> {
+    if sans.is_empty() {
+        return Err("remote TLS requires at least one server name".into());
+    }
+    std::fs::create_dir_all(directory)
+        .map_err(|error| format!("cannot create remote TLS directory: {error}"))?;
+    let path = directory.join(IDENTITY_FILE);
+    let saved = read_identity(&path)?;
+    let first_install = saved.is_none();
+    let mut identity = match saved {
+        Some(identity) => identity,
+        None => create_ca(now)?,
+    };
+    matching_key(&identity.ca_cert, &identity.ca_key)?;
+    let (remainder, ca_x509) = x509_parser::parse_x509_certificate(&identity.ca_cert)
+        .map_err(|_| "invalid remote TLS CA encoding")?;
+    if !remainder.is_empty()
+        || ca_x509.issuer() != ca_x509.subject()
+        || ca_x509.verify_signature(None).is_err()
+    {
+        return Err("remote TLS CA signature is invalid; restore the identity from backup".into());
+    }
+    let ca_params = parse_cert(&identity.ca_cert)?;
+    if !matches!(ca_params.is_ca, IsCa::Ca(_))
+        || !ca_params.key_usages.contains(&KeyUsagePurpose::KeyCertSign)
+        || ca_params.not_before > now
+        || ca_params.not_after <= now + Duration::days(30)
+    {
+        return Err("remote TLS CA is invalid or expires soon; restore a valid identity or explicitly reset it and trust the new certificate on each phone".into());
+    }
+    if !valid_leaf(&identity, sans, now) {
+        let ca_key = KeyPair::try_from(&key_der(identity.ca_key.clone()))
+            .map_err(|error| error.to_string())?;
+        let ca_expiry = ca_params.not_after;
+        let ca = ca_params
+            .self_signed(&ca_key)
+            .map_err(|error| error.to_string())?;
+        let key = KeyPair::generate().map_err(|error| error.to_string())?;
+        let mut params =
+            CertificateParams::new(sans.to_vec()).map_err(|error| error.to_string())?;
+        let mut name = DistinguishedName::new();
+        name.push(DnType::CommonName, "OpenLess Remote Input");
+        name.push(DnType::OrganizationName, "OpenLess");
+        params.distinguished_name = name;
+        params.key_usages = vec![KeyUsagePurpose::DigitalSignature];
+        params.extended_key_usages = vec![ExtendedKeyUsagePurpose::ServerAuth];
+        params.not_before = now - Duration::days(1);
+        params.not_after = (now + Duration::days(365)).min(ca_expiry);
+        params.use_authority_key_identifier_extension = true;
+        let cert = params
+            .signed_by(&key, &ca, &ca_key)
+            .map_err(|error| error.to_string())?;
+        identity.leaf_cert = cert.der().to_vec();
+        identity.leaf_key = key.serialize_der();
+        if !valid_leaf(&identity, sans, now) {
+            return Err("generated remote TLS certificate failed validation".into());
+        }
+        save_identity(&path, &identity, first_install)?;
+    }
+    let config = rustls::ServerConfig::builder_with_provider(Arc::new(
+        rustls::crypto::ring::default_provider(),
+    ))
+    .with_safe_default_protocol_versions()
+    .map_err(|error| error.to_string())?
+    .with_no_client_auth()
+    .with_single_cert(
+        vec![CertificateDer::from(identity.leaf_cert)],
+        key_der(identity.leaf_key),
+    )
+    .map_err(|error| format!("remote TLS config: {error}"))?;
+    Ok(TlsIdentity {
+        trust_cert: identity.ca_cert,
+        server_config: Arc::new(config),
+    })
+}
+
+/// The profile contains a public CA only. IDs include its fingerprint so two
+/// computers can be trusted without replacing each other's iOS profiles.
+pub(super) fn mobileconfig(cert: &[u8]) -> String {
+    use base64::Engine;
+    use sha2::{Digest, Sha256};
+    let fingerprint = format!("{:x}", Sha256::digest(cert));
+    let b64 = base64::engine::general_purpose::STANDARD.encode(cert);
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>PayloadContent</key><array><dict>
+<key>PayloadCertificateFileName</key><string>openless-ca.cer</string>
+<key>PayloadContent</key><data>{b64}</data>
+<key>PayloadType</key><string>com.apple.security.root</string>
+<key>PayloadIdentifier</key><string>com.openless.remote-input.{fingerprint}.cert</string>
+<key>PayloadUUID</key><string>{cert_uuid}</string>
+<key>PayloadVersion</key><integer>1</integer>
+<key>PayloadDisplayName</key><string>OpenLess Remote Input CA ({short})</string>
+</dict></array>
+<key>PayloadDisplayName</key><string>OpenLess Remote Input ({short})</string>
+<key>PayloadDescription</key><string>Trust only a profile downloaded from your own computer. After installation, enable full trust in Settings &gt; General &gt; About &gt; Certificate Trust Settings. This CA can issue certificates; remove this profile when you stop using remote input.</string>
+<key>PayloadIdentifier</key><string>com.openless.remote-input.{fingerprint}</string>
+<key>PayloadType</key><string>Configuration</string>
+<key>PayloadUUID</key><string>{profile_uuid}</string>
+<key>PayloadVersion</key><integer>1</integer>
+</dict></plist>"#,
+        short = &fingerprint[..8],
+        cert_uuid = uuid::Uuid::new_v4(),
+        profile_uuid = uuid::Uuid::new_v4(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn names() -> Vec<String> {
+        vec!["localhost".into(), "127.0.0.1".into(), "192.168.1.2".into()]
+    }
+
+    fn stored(directory: &Path) -> StoredIdentity {
+        read_identity(&directory.join(IDENTITY_FILE))
+            .unwrap()
+            .unwrap()
+    }
+
+    fn verify_server(identity: &TlsIdentity, trusted_ca: &[u8], name: &str) -> bool {
+        let mut roots = rustls::RootCertStore::empty();
+        roots
+            .add(CertificateDer::from(trusted_ca.to_vec()))
+            .unwrap();
+        let client_config = rustls::ClientConfig::builder_with_provider(Arc::new(
+            rustls::crypto::ring::default_provider(),
+        ))
+        .with_safe_default_protocol_versions()
+        .unwrap()
+        .with_root_certificates(roots)
+        .with_no_client_auth();
+        let mut client = rustls::ClientConnection::new(
+            Arc::new(client_config),
+            name.to_owned().try_into().unwrap(),
+        )
+        .unwrap();
+        let mut server =
+            rustls::ServerConnection::new(Arc::clone(&identity.server_config)).unwrap();
+        for _ in 0..10 {
+            let mut bytes = Vec::new();
+            client.write_tls(&mut bytes).unwrap();
+            server.read_tls(&mut bytes.as_slice()).unwrap();
+            if server.process_new_packets().is_err() {
+                return false;
+            }
+            bytes.clear();
+            server.write_tls(&mut bytes).unwrap();
+            client.read_tls(&mut bytes.as_slice()).unwrap();
+            if client.process_new_packets().is_err() {
+                return false;
+            }
+            if !client.is_handshaking() && !server.is_handshaking() {
+                return true;
+            }
+        }
+        false
+    }
+
+    #[test]
+    fn restart_reuses_identity_and_tls_works_with_only_the_downloaded_ca() {
+        let dir = tempfile::tempdir().unwrap();
+        let first = load_or_create(dir.path(), &names()).unwrap();
+        let before = std::fs::read(dir.path().join(IDENTITY_FILE)).unwrap();
+        let second = load_or_create(dir.path(), &names()).unwrap();
+        assert_eq!(
+            before,
+            std::fs::read(dir.path().join(IDENTITY_FILE)).unwrap()
+        );
+        assert_eq!(first.trust_cert, second.trust_cert);
+        for name in names() {
+            assert!(verify_server(&second, &first.trust_cert, &name));
+        }
+        assert!(!verify_server(&second, &first.trust_cert, "192.168.1.99"));
+        let saved = stored(dir.path());
+        let ca = parse_cert(&saved.ca_cert).unwrap();
+        let leaf = parse_cert(&saved.leaf_cert).unwrap();
+        assert!(matches!(
+            ca.is_ca,
+            IsCa::Ca(BasicConstraints::Constrained(0))
+        ));
+        assert!(matches!(leaf.is_ca, IsCa::NoCa | IsCa::ExplicitNoCa));
+        assert!(leaf
+            .extended_key_usages
+            .contains(&ExtendedKeyUsagePurpose::ServerAuth));
+        assert!(leaf.not_after - leaf.not_before <= Duration::days(366));
+    }
+
+    #[test]
+    fn virtual_adapter_and_lan_changes_preserve_phone_trust() {
+        let dir = tempfile::tempdir().unwrap();
+        let first = load_or_create(dir.path(), &names()).unwrap();
+        let before = stored(dir.path());
+        let mut changed = names();
+        changed.push("172.26.112.1".into());
+        changed.push("192.168.2.3".into());
+        let second = load_or_create(dir.path(), &changed).unwrap();
+        let after = stored(dir.path());
+        assert_eq!(before.ca_cert, after.ca_cert);
+        assert_eq!(before.ca_key, after.ca_key);
+        assert_ne!(before.leaf_cert, after.leaf_cert);
+        assert!(verify_server(&second, &first.trust_cert, "192.168.2.3"));
+        // Removing an adapter does not require another leaf or CA.
+        load_or_create(dir.path(), &names()).unwrap();
+        assert_eq!(after.leaf_cert, stored(dir.path()).leaf_cert);
+    }
+
+    #[test]
+    fn renews_expiring_leaf_without_rotating_ca() {
+        let dir = tempfile::tempdir().unwrap();
+        let now = OffsetDateTime::now_utc();
+        load_at(dir.path(), &names(), now).unwrap();
+        let before = stored(dir.path());
+        load_at(dir.path(), &names(), now + Duration::days(340)).unwrap();
+        let after = stored(dir.path());
+        assert_eq!(before.ca_cert, after.ca_cert);
+        assert_ne!(before.leaf_cert, after.leaf_cert);
+        assert!(parse_cert(&after.leaf_cert).unwrap().not_after > now + Duration::days(700));
+    }
+
+    #[test]
+    fn repairs_bad_leaf_but_never_replaces_damaged_or_mismatched_ca() {
+        let dir = tempfile::tempdir().unwrap();
+        let first = load_or_create(dir.path(), &names()).unwrap();
+        let path = dir.path().join(IDENTITY_FILE);
+        let mut saved = stored(dir.path());
+        saved.leaf_cert = vec![0];
+        save_identity(&path, &saved, false).unwrap();
+        let repaired = load_or_create(dir.path(), &names()).unwrap();
+        assert!(verify_server(&repaired, &first.trust_cert, "localhost"));
+        saved = stored(dir.path());
+        let mut damaged = stored(dir.path());
+        *damaged.ca_cert.last_mut().unwrap() ^= 1;
+        save_identity(&path, &damaged, false).unwrap();
+        assert!(load_or_create(dir.path(), &names()).is_err());
+        assert_eq!(damaged.ca_cert, stored(dir.path()).ca_cert);
+        saved.ca_key = KeyPair::generate().unwrap().serialize_der();
+        save_identity(&path, &saved, false).unwrap();
+        let before = std::fs::read(&path).unwrap();
+        assert!(load_or_create(dir.path(), &names()).is_err());
+        assert_eq!(before, std::fs::read(&path).unwrap());
+        std::fs::write(&path, b"interrupted write").unwrap();
+        assert!(load_or_create(dir.path(), &names()).is_err());
+        assert_eq!(
+            b"interrupted write",
+            std::fs::read(&path).unwrap().as_slice()
+        );
+    }
+
+    #[test]
+    fn refuses_expired_ca_instead_of_silently_revoking_trust() {
+        let dir = tempfile::tempdir().unwrap();
+        let now = OffsetDateTime::now_utc();
+        load_at(dir.path(), &names(), now).unwrap();
+        let before = std::fs::read(dir.path().join(IDENTITY_FILE)).unwrap();
+        assert!(load_at(dir.path(), &names(), now + Duration::days(3651)).is_err());
+        assert_eq!(
+            before,
+            std::fs::read(dir.path().join(IDENTITY_FILE)).unwrap()
+        );
+    }
+
+    #[test]
+    fn migration_keeps_legacy_files_and_profiles_only_contain_public_ca() {
+        use base64::Engine;
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("remote-cert-v4.der"), b"legacy cert").unwrap();
+        std::fs::write(dir.path().join("remote-key-v4.der"), b"legacy key").unwrap();
+        let first = load_or_create(dir.path(), &names()).unwrap();
+        let profile = mobileconfig(&first.trust_cert);
+        let saved = stored(dir.path());
+        let encoded = |bytes: &[u8]| base64::engine::general_purpose::STANDARD.encode(bytes);
+        assert!(profile.contains(&format!("<data>{}</data>", encoded(&first.trust_cert))));
+        assert!(!profile.contains(&encoded(&saved.ca_key)));
+        assert!(!profile.contains(&encoded(&saved.leaf_key)));
+        assert!(!profile.contains(&encoded(&saved.leaf_cert)));
+        assert_eq!(
+            std::fs::read(dir.path().join("remote-cert-v4.der")).unwrap(),
+            b"legacy cert"
+        );
+        assert_eq!(
+            std::fs::read(dir.path().join("remote-key-v4.der")).unwrap(),
+            b"legacy key"
+        );
+        let other = tempfile::tempdir().unwrap();
+        let second = load_or_create(other.path(), &names()).unwrap();
+        assert_ne!(first.trust_cert, second.trust_cert);
+        assert!(!verify_server(&second, &first.trust_cert, "localhost"));
+        assert_ne!(profile, mobileconfig(&second.trust_cert));
+    }
+
+    #[test]
+    fn persistence_errors_never_fall_back_to_an_ephemeral_identity() {
+        let dir = tempfile::tempdir().unwrap();
+        let blocked = dir.path().join("blocked");
+        std::fs::write(&blocked, b"not a directory").unwrap();
+        assert!(load_or_create(&blocked, &names()).is_err());
+        std::fs::create_dir(dir.path().join(IDENTITY_FILE)).unwrap();
+        assert!(load_or_create(dir.path(), &names()).is_err());
+        assert!(load_or_create(dir.path(), &[]).is_err());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn stored_private_keys_are_owner_only() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        load_or_create(dir.path(), &names()).unwrap();
+        assert_eq!(
+            std::fs::metadata(dir.path().join(IDENTITY_FILE))
+                .unwrap()
+                .permissions()
+                .mode()
+                & 0o777,
+            0o600
+        );
+    }
+}
diff --git a/openless-all/app/src/i18n/en.ts b/openless-all/app/src/i18n/en.ts
index 0b073f21..60fad289 100644
--- a/openless-all/app/src/i18n/en.ts
+++ b/openless-all/app/src/i18n/en.ts
@@ -1435,9 +1435,9 @@ export const en: typeof zhCN = {
       portInUse: 'Port {{port}} is in use, please change it',
       startError: 'Failed to start the remote input service: {{reason}}',
       securityHint: 'Reachable only on the same LAN and requires the pairing code; turn it off when not in use.',
-      certHint: 'On first visit the browser warns the certificate is untrusted — choose "Proceed".',
-      certTrustWarning:
-        'The certificate is only used by this PC’s remote input service (it cannot issue other certificates). Never trust certificates from unknown sources; remove it from your phone’s settings when no longer needed.',
+      certHint: "Open “First-time setup: trust this computer” on the phone to install and trust the certificate. Older versions require one-time setup; subsequent restarts and IP changes preserve trust.",
+      certTrustWarning: "The initial certificate download cannot verify the computer's identity; a malicious device on the LAN could replace the root certificate in a man-in-the-middle attack. Install it only on a trusted home or private network, never on a public or shared network. The root CA can issue certificates and its private key stays on this computer; remove it from your phone when no longer needed.",
+      certSetupLink: "Copy iPhone certificate link",
       waitingStart: 'The service is not running yet. Turn the switch off, then on again. Do not restart the app.',
       starting: 'Starting the remote input service…',
       urlsStale: 'These addresses come from the previous run and may be out of date.',
diff --git a/openless-all/app/src/i18n/ja.ts b/openless-all/app/src/i18n/ja.ts
index 36a57b13..2467d088 100644
--- a/openless-all/app/src/i18n/ja.ts
+++ b/openless-all/app/src/i18n/ja.ts
@@ -1395,9 +1395,9 @@ export const ja: typeof zhCN = {
       portInUse: 'ポート {{port}} は使用中です。変更してください',
       startError: 'リモート入力サービスの起動に失敗しました：{{reason}}',
       securityHint: '同一 LAN からのみアクセス可能で、ペアリングコードの入力が必要です。使わないときはオフにすることを推奨します。',
-      certHint: '初回アクセス時、ブラウザが証明書は信頼されていないと警告します。案内に従って「続行」を選択してください。',
-      certTrustWarning:
-        'この証明書は本機のリモート入力サービス専用です（他の証明書を発行できません）。出所不明の証明書は信頼しないでください。不要になったらスマートフォンの設定から削除できます。',
+      certHint: "スマートフォンの「初回設定：このコンピュータを信頼」で証明書をインストールし信頼してください。旧バージョンからは一度設定が必要ですが、その後は再起動や IP 変更でも信頼が保持されます。",
+      certTrustWarning: "初回の証明書ダウンロードではコンピューターの身元を確認できず、LAN 上の悪意あるデバイスが中間者攻撃でルート証明書を置き換える可能性があります。信頼できる家庭内またはプライベートネットワークでのみインストールし、公共または共有ネットワークでは操作しないでください。ルート CA は証明書を発行でき、秘密鍵はこのコンピューターに保存されます。不要になったらスマートフォンから削除してください。",
+      certSetupLink: "iPhone 証明書リンクをコピー",
       waitingStart: 'サービスはまだ起動していません。スイッチを一度オフにしてからオンにしてください。アプリを再起動しないでください。',
       starting: 'リモート入力サービスを起動しています…',
       urlsStale: 'これらのアドレスは前回の起動時のもので、古くなっている可能性があります。',
diff --git a/openless-all/app/src/i18n/ko.ts b/openless-all/app/src/i18n/ko.ts
index 09fd69a9..21423d9e 100644
--- a/openless-all/app/src/i18n/ko.ts
+++ b/openless-all/app/src/i18n/ko.ts
@@ -1395,9 +1395,9 @@ export const ko: typeof zhCN = {
       portInUse: '포트 {{port}}이(가) 사용 중입니다. 변경하세요',
       startError: '원격 입력 서비스 시작에 실패했습니다: {{reason}}',
       securityHint: '같은 LAN에서만 접속 가능하며 페어링 코드 입력이 필요합니다. 사용하지 않을 때는 끄는 것을 권장합니다.',
-      certHint: '첫 접속 시 브라우저가 인증서를 신뢰할 수 없다고 경고합니다. 안내에 따라 "계속 진행"을 선택하세요.',
-      certTrustWarning:
-        '이 인증서는 이 PC의 원격 입력 서비스 전용입니다(다른 인증서를 발급할 수 없음). 출처를 알 수 없는 인증서는 신뢰하지 마세요. 더 이상 사용하지 않으면 휴대폰 설정에서 제거할 수 있습니다.',
+      certHint: "휴대폰에서 “최초 설정: 이 컴퓨터 신뢰”를 열고 인증서를 설치하고 신뢰하세요. 이전 버전에서는 한 번 설정해야 하며, 이후 재시작과 IP 변경 시 신뢰가 유지됩니다.",
+      certTrustWarning: "최초 인증서 다운로드에서는 컴퓨터의 신원을 확인할 수 없으며, LAN의 악성 기기가 중간자 공격으로 루트 인증서를 바꿀 수 있습니다. 신뢰할 수 있는 가정용 또는 사설 네트워크에서만 설치하고 공용 또는 공유 네트워크에서는 진행하지 마세요. 루트 CA는 인증서를 발급할 수 있고 개인 키는 이 컴퓨터에 저장됩니다. 더 이상 사용하지 않으면 휴대폰에서 제거하세요.",
+      certSetupLink: "iPhone 인증서 링크 복사",
       waitingStart: '서비스가 아직 시작되지 않았습니다. 스위치를 끈 다음 다시 켜세요. 앱을 다시 시작하지 마세요.',
       starting: '원격 입력 서비스를 시작하는 중입니다…',
       urlsStale: '이 주소는 이전 실행에서 가져온 것으로 최신이 아닐 수 있습니다.',
diff --git a/openless-all/app/src/i18n/zh-CN.ts b/openless-all/app/src/i18n/zh-CN.ts
index c8d176de..70e9bd6b 100644
--- a/openless-all/app/src/i18n/zh-CN.ts
+++ b/openless-all/app/src/i18n/zh-CN.ts
@@ -1433,9 +1433,9 @@ export const zhCN = {
       portInUse: '端口 {{port}} 被占用，请更换',
       startError: '远程输入服务启动失败：{{reason}}',
       securityHint: '仅同一局域网可访问，需输入配对码；不用时建议关闭。',
-      certHint: '首次访问浏览器会提示证书不受信任，按提示选择"继续访问"。',
-      certTrustWarning:
-        '该证书仅用于本机远程输入服务（不能签发其他证书），请勿信任来源不明的证书；不再使用时可在手机系统设置中移除。',
+      certHint: "首次连接请在手机页面展开“首次设置：信任此电脑”，安装并信任证书。升级旧版需设置一次；以后重启和换 IP 会保留信任。",
+      certTrustWarning: "首次证书下载无法验证电脑身份，恶意局域网设备可能通过中间人攻击替换根证书。仅在可信的家庭或私人网络中安装，勿在公共或共享网络操作。根证书具备签发能力，私钥保存在这台电脑；不再使用时请从手机移除。",
+      certSetupLink: "复制 iPhone 证书链接",
       waitingStart: '服务尚未启动。请关闭开关再打开一次，不要重启软件。',
       starting: '正在启动远程输入服务…',
       urlsStale: '这些地址来自上次运行，可能已经过期。',
diff --git a/openless-all/app/src/i18n/zh-TW.ts b/openless-all/app/src/i18n/zh-TW.ts
index 9ce75771..f34c8781 100644
--- a/openless-all/app/src/i18n/zh-TW.ts
+++ b/openless-all/app/src/i18n/zh-TW.ts
@@ -1401,9 +1401,9 @@ export const zhTW: typeof zhCN = {
       portInUse: '連接埠 {{port}} 被佔用，請更換',
       startError: '遠端輸入服務啟動失敗：{{reason}}',
       securityHint: '僅同一區域網路可存取，需輸入配對碼；不用時建議關閉。',
-      certHint: '首次存取瀏覽器會提示憑證不受信任，按提示選擇「繼續存取」。',
-      certTrustWarning:
-        '該憑證僅用於本機遠端輸入服務（無法簽發其他憑證），請勿信任來源不明的憑證；不再使用時可在手機系統設定中移除。',
+      certHint: "首次連線請在手機頁面展開「首次設定：信任這台電腦」，安裝並信任憑證。升級舊版需設定一次；之後重新啟動和更換 IP 會保留信任。",
+      certTrustWarning: "首次憑證下載無法驗證電腦身分，惡意區域網路裝置可能透過中間人攻擊替換根憑證。僅在可信任的家庭或私人網路中安裝，請勿在公共或共享網路操作。根憑證能簽發憑證，私密金鑰保存在這台電腦；不再使用時請從手機移除。",
+      certSetupLink: "複製 iPhone 憑證連結",
       waitingStart: '服務尚未啟動。請關閉開關再打開一次，不要重啟軟體。',
       starting: '正在啟動遠端輸入服務…',
       urlsStale: '這些地址來自上次執行，可能已經過期。',
diff --git a/openless-all/app/src/pages/settings/RemoteInputSection.tsx b/openless-all/app/src/pages/settings/RemoteInputSection.tsx
index e4336915..d3c38cab 100644
--- a/openless-all/app/src/pages/settings/RemoteInputSection.tsx
+++ b/openless-all/app/src/pages/settings/RemoteInputSection.tsx
@@ -205,7 +205,7 @@ export function RemoteInputSection() {
                 {status.urls.map((u) => (
                   <div
                     key={u}
-                    style={{ display: 'flex', alignItems: 'center', gap: 8 }}
+                    style={{ display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 8 }}
                   >
                     <span
                       style={{
@@ -224,6 +224,17 @@ export function RemoteInputSection() {
                     >
                       {copied === u ? '✓' : '⧉'}
                     </button>
+                    <button
+                      onClick={async () => {
+                        const link = `${u}/cert.mobileconfig`;
+                        await copyText(link);
+                        setCopied(link);
+                        window.setTimeout(() => setCopied((c) => c === link ? null : c), 1500);
+                      }}
+                      style={smallBtn}
+                    >
+                      {copied === `${u}/cert.mobileconfig` ? '✓' : t('settings.remoteInput.certSetupLink')}
+                    </button>
                   </div>
                 ))}
               </div>