From 71b70421fc55f927c828c92cd34829fb317ff7b1 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Tue, 17 Mar 2026 06:22:14 -0700
Subject: [PATCH 1/3] feat(voice-button): add autoReplace support for
 continuous speech replacement

---
 docs/src/components/sender.md                 | 19 ++++++--
 .../src/sender-actions/voice-button/index.vue | 47 +++++++++++++++----
 .../voice-button/speech.types.ts              |  2 +-
 3 files changed, 56 insertions(+), 12 deletions(-)

diff --git a/docs/src/components/sender.md b/docs/src/components/sender.md
index e78fb9d9c..c72ae693f 100644
--- a/docs/src/components/sender.md
+++ b/docs/src/components/sender.md
@@ -155,10 +155,23 @@ TrSender.Suggestion.configure({ items: suggestions, filterFn: customFilter })
 
 #### 基础语音识别
 
-使用浏览器内置的语音识别功能，支持混合输入和连续识别两种模式。
+使用浏览器内置的语音识别功能，支持混合输入和连续识别两种模式。可通过 `speechConfig.lang` 显式指定识别语言。
 
 <demo vue="../../demos/sender/voice-input.vue" title="基础语音输入" description="使用浏览器内置语音识别，支持混合输入和连续识别。" />
 
+:::tip lang 语言说明
+`lang` 用于指定语音识别语言，建议显式传入，并与页面的 `html lang` 保持一致，避免页面语言和浏览器环境语言不一致时出现识别偏差。
+
+常见取值示例：
+
+| 值 | 说明 |
+| --- | --- |
+| `en` | 英语 |
+| `zh` | 中文 |
+| `zh-CN` | 简体中文 |
+| `en-US` | 美式英语 |
+:::
+
 #### 自定义语音服务
 
 支持集成第三方语音识别服务（如阿里云、百度、Azure 等）。
@@ -597,7 +610,7 @@ type TooltipPlacement =
 // SpeechConfig 语音配置
 interface SpeechConfig {
   customHandler?: SpeechHandler // 自定义语音处理器
-  lang?: string // 识别语言，默认浏览器语言
+  lang?: string // 识别语言，建议显式配置并与 html lang 保持一致；未传入时由浏览器环境决定
   continuous?: boolean // 是否持续识别
   interimResults?: boolean // 是否返回中间结果
   autoReplace?: boolean // 是否自动替换内容
@@ -789,4 +802,4 @@ Sender 组件提供了丰富的 CSS 变量用于自定义样式。
 |-------|----------|
 | startSpeech | 使用 `VoiceButton.start()` |
 | stopSpeech | 使用 `VoiceButton.stop()` |
-| activateTemplateFirstField | 自动处理，无需调用 |
\ No newline at end of file
+| activateTemplateFirstField | 自动处理，无需调用 |
diff --git a/packages/components/src/sender-actions/voice-button/index.vue b/packages/components/src/sender-actions/voice-button/index.vue
index 700bb5200..1cd7d5f84 100644
--- a/packages/components/src/sender-actions/voice-button/index.vue
+++ b/packages/components/src/sender-actions/voice-button/index.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, ref } from 'vue'
 import { useSenderContext } from '../../sender/context'
 import { useSpeechHandler } from './useSpeechHandler'
 import ActionButton from '../action-button/index.vue'
@@ -16,24 +16,53 @@ const emit = defineEmits<VoiceButtonEmits>()
 // 从 Context 获取最小依赖：只需要 editor 和 disabled
 const { editor, disabled: contextDisabled } = useSenderContext()
 const isDisabled = computed(() => props.disabled || contextDisabled.value)
+const speechRange = ref<{ from: number; to: number } | null>(null)
+
+const resetSpeechRange = () => {
+  speechRange.value = null
+}
+
+const insertTranscript = (transcript: string) => {
+  if (!props.autoInsert || !editor.value || !transcript) return
+
+  const editorInstance = editor.value
+  const autoReplace = props.speechConfig?.autoReplace ?? false
+
+  if (!autoReplace) {
+    editorInstance.commands.insertContent(transcript + ' ')
+    editorInstance.commands.focus('end')
+    return
+  }
+
+  // 在单次录音会话期间，持续替换当前的语音插入范围
+  const range = speechRange.value ?? {
+    from: editorInstance.state.selection.from,
+    to: editorInstance.state.selection.to,
+  }
+  const tr = editorInstance.state.tr.insertText(transcript, range.from, range.to)
+  editorInstance.view.dispatch(tr)
+  speechRange.value = {
+    from: range.from,
+    to: range.from + transcript.length,
+  }
+  editorInstance.commands.focus('end')
+}
 
 // 语音配置 - 使用普通对象而不是 computed，避免每次都创建新对象
 const speechOptions = {
   ...props.speechConfig,
   onStart: () => {
+    resetSpeechRange()
     emit('speech-start')
   },
   onInterim: (transcript: string) => {
+    if (props.speechConfig?.autoReplace) {
+      insertTranscript(transcript)
+    }
     emit('speech-interim', transcript)
   },
   onFinal: (transcript: string) => {
-    // 自动插入到编辑器(可配置)
-    if (props.autoInsert && editor.value) {
-      // 插入内容
-      editor.value.commands.insertContent(transcript + ' ')
-      // 确保光标在内容末尾
-      editor.value.commands.focus('end')
-    }
+    insertTranscript(transcript)
     emit('speech-final', transcript)
   },
   onEnd: (transcript?: string) => {
@@ -41,9 +70,11 @@ const speechOptions = {
     if (editor.value) {
       editor.value.commands.focus('end')
     }
+    resetSpeechRange()
     emit('speech-end', transcript)
   },
   onError: (error: Error) => {
+    resetSpeechRange()
     emit('speech-error', error)
   },
 }
diff --git a/packages/components/src/sender-actions/voice-button/speech.types.ts b/packages/components/src/sender-actions/voice-button/speech.types.ts
index f745f1e66..7c51d70a5 100644
--- a/packages/components/src/sender-actions/voice-button/speech.types.ts
+++ b/packages/components/src/sender-actions/voice-button/speech.types.ts
@@ -27,7 +27,7 @@ export interface SpeechConfig {
   lang?: string // 识别语言，默认浏览器语言
   continuous?: boolean // 是否持续识别
   interimResults?: boolean // 是否返回中间结果
-  autoReplace?: boolean // 是否自动替换当前输入内容
+  autoReplace?: boolean // 是否在本次录音期间自动替换语音插入内容
   onVoiceButtonClick?: (isRecording: boolean, preventDefault: () => void) => void | Promise<void> // 录音按钮点击拦截器
 }
 

From 39ca9cbfeb29c5090956df67c6cc197f3a239c6c Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Tue, 17 Mar 2026 21:05:49 -0700
Subject: [PATCH 2/3] docs(sender): update voice button documentation and type
 definitions

---
 docs/src/components/sender.md                     | 15 +++++++--------
 .../sender-actions/voice-button/speech.types.ts   |  3 +--
 2 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/docs/src/components/sender.md b/docs/src/components/sender.md
index c72ae693f..a7bcfc7f7 100644
--- a/docs/src/components/sender.md
+++ b/docs/src/components/sender.md
@@ -1,4 +1,4 @@
----
+---
 outline: [1, 3]
 ---
 
@@ -442,7 +442,7 @@ onSelect: (item) => {
 | tooltipPlacement | Tooltip 位置                 | `TooltipPlacement`    | `'top'`     |
 | speechConfig     | 语音配置                     | `SpeechConfig`        | -           |
 | autoInsert       | 是否自动插入识别结果到编辑器 | `boolean`             | `true`      |
-| onButtonClick    | 按钮点击拦截器               | `Function`            | -           |
+| onButtonClick    | 按钮点击拦截器               | `(isRecording: boolean, preventDefault: () => void) => void \| Promise<void>` | - |
 
 ## Slots
 
@@ -610,11 +610,10 @@ type TooltipPlacement =
 // SpeechConfig 语音配置
 interface SpeechConfig {
   customHandler?: SpeechHandler // 自定义语音处理器
-  lang?: string // 识别语言，建议显式配置并与 html lang 保持一致；未传入时由浏览器环境决定
-  continuous?: boolean // 是否持续识别
-  interimResults?: boolean // 是否返回中间结果
-  autoReplace?: boolean // 是否自动替换内容
-  onVoiceButtonClick?: (isRecording, preventDefault) => void // 按钮点击拦截器
+  lang?: string // 内置 Web Speech 的识别语言；未传入时使用 navigator.language
+  continuous?: boolean // 内置 Web Speech 是否持续识别
+  interimResults?: boolean // 内置 Web Speech 是否返回中间结果
+  autoReplace?: boolean // 是否在本次录音期间用最新识别结果替换当前语音插入内容
 }
 
 // 模板项（联合类型）
@@ -802,4 +801,4 @@ Sender 组件提供了丰富的 CSS 变量用于自定义样式。
 |-------|----------|
 | startSpeech | 使用 `VoiceButton.start()` |
 | stopSpeech | 使用 `VoiceButton.stop()` |
-| activateTemplateFirstField | 自动处理，无需调用 |
+| activateTemplateFirstField | 自动处理，无需调用 |
\ No newline at end of file
diff --git a/packages/components/src/sender-actions/voice-button/speech.types.ts b/packages/components/src/sender-actions/voice-button/speech.types.ts
index 7c51d70a5..a182d1aae 100644
--- a/packages/components/src/sender-actions/voice-button/speech.types.ts
+++ b/packages/components/src/sender-actions/voice-button/speech.types.ts
@@ -1,4 +1,4 @@
-/**
+/**
  * 语音识别相关类型定义
  */
 // 语音回调函数集合
@@ -28,7 +28,6 @@ export interface SpeechConfig {
   continuous?: boolean // 是否持续识别
   interimResults?: boolean // 是否返回中间结果
   autoReplace?: boolean // 是否在本次录音期间自动替换语音插入内容
-  onVoiceButtonClick?: (isRecording: boolean, preventDefault: () => void) => void | Promise<void> // 录音按钮点击拦截器
 }
 
 // 语音识别状态

From 855ae9eac6733ddc6f6c10bfc0264c404776877a Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 18 Mar 2026 02:24:51 -0700
Subject: [PATCH 3/3] feat(voice-button): refactor speech input modes from
 mixed/continuous to append/replace

---
 docs/demos/sender/voice-input.vue             | 26 ++++++++++++-------
 .../src/sender-actions/voice-button/index.vue | 26 +++++++++++++------
 2 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/docs/demos/sender/voice-input.vue b/docs/demos/sender/voice-input.vue
index 39bfff2bc..d3e617d50 100644
--- a/docs/demos/sender/voice-input.vue
+++ b/docs/demos/sender/voice-input.vue
@@ -2,7 +2,7 @@
 import { ref } from 'vue'
 import { TrSender, VoiceButton } from '@opentiny/tiny-robot'
 
-const voiceMode = ref<'mixed' | 'continuous'>('mixed')
+const voiceMode = ref<'append' | 'replace'>('append')
 </script>
 
 <template>
@@ -10,28 +10,36 @@ const voiceMode = ref<'mixed' | 'continuous'>('mixed')
     <div style="display: flex; align-items: center; gap: 12px">
       <span style="font-weight: 500">模式：</span>
       <label style="display: flex; align-items: center; gap: 4px; cursor: pointer">
-        <input type="radio" value="mixed" v-model="voiceMode" style="cursor: pointer" />
-        <span>混合输入</span>
+        <input type="radio" value="append" v-model="voiceMode" style="cursor: pointer" />
+        <span>追加模式</span>
       </label>
       <label style="display: flex; align-items: center; gap: 4px; cursor: pointer">
-        <input type="radio" value="continuous" v-model="voiceMode" style="cursor: pointer" />
-        <span>连续识别</span>
+        <input type="radio" value="replace" v-model="voiceMode" style="cursor: pointer" />
+        <span>替换模式</span>
       </label>
     </div>
     <div style="padding: 8px 12px; background: #f5f7fa; border-radius: 4px; font-size: 13px; color: #666">
-      {{ voiceMode === 'mixed' ? '语音识别结果追加到输入框，可继续编辑' : '持续识别语音并自动替换内容' }}
+      {{
+        voiceMode === 'append'
+          ? '追加模式：每次语音识别结果会追加到输入框末尾，适合混合输入'
+          : '替换模式：每次语音识别会替换输入框全部内容，适合纯语音输入'
+      }}
     </div>
     <tr-sender
       :key="voiceMode"
       mode="multiple"
-      :placeholder="voiceMode === 'mixed' ? '点击麦克风说话，识别结果会追加到此处...' : '点击麦克风开始连续识别...'"
+      :placeholder="
+        voiceMode === 'append'
+          ? '可以打字或点击麦克风说话，语音内容会追加...'
+          : '点击麦克风说话，每次识别会替换全部内容...'
+      "
     >
       <template #footer-right>
         <VoiceButton
           :speech-config="
-            voiceMode === 'mixed'
+            voiceMode === 'append'
               ? { autoReplace: false, interimResults: true }
-              : { autoReplace: true, continuous: true }
+              : { autoReplace: true, interimResults: true }
           "
         />
       </template>
diff --git a/packages/components/src/sender-actions/voice-button/index.vue b/packages/components/src/sender-actions/voice-button/index.vue
index 1cd7d5f84..e2a7a6683 100644
--- a/packages/components/src/sender-actions/voice-button/index.vue
+++ b/packages/components/src/sender-actions/voice-button/index.vue
@@ -34,16 +34,24 @@ const insertTranscript = (transcript: string) => {
     return
   }
 
-  // 在单次录音会话期间，持续替换当前的语音插入范围
-  const range = speechRange.value ?? {
-    from: editorInstance.state.selection.from,
-    to: editorInstance.state.selection.to,
+  // autoReplace 模式：替换整个输入框内容
+  if (speechRange.value === null) {
+    // 首次插入，记录起始位置为 0
+    speechRange.value = {
+      from: 0,
+      to: 0,
+    }
   }
-  const tr = editorInstance.state.tr.insertText(transcript, range.from, range.to)
+
+  // 替换从起始位置到当前内容末尾的所有文本
+  const docSize = editorInstance.state.doc.content.size
+  const tr = editorInstance.state.tr.insertText(transcript, speechRange.value.from, docSize)
   editorInstance.view.dispatch(tr)
+
+  // 更新范围，保持起始位置不变，更新结束位置
   speechRange.value = {
-    from: range.from,
-    to: range.from + transcript.length,
+    from: speechRange.value.from,
+    to: speechRange.value.from + transcript.length,
   }
   editorInstance.commands.focus('end')
 }
@@ -62,7 +70,9 @@ const speechOptions = {
     emit('speech-interim', transcript)
   },
   onFinal: (transcript: string) => {
-    insertTranscript(transcript)
+    if (!props.speechConfig?.autoReplace) {
+      insertTranscript(transcript)
+    }
     emit('speech-final', transcript)
   },
   onEnd: (transcript?: string) => {