From f65481674bbbe84bb379b8e8113c111f0a258f56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A2=A8=E7=B6=A0BG?= <s5460703@gmail.com>
Date: Mon, 22 Jun 2026 15:46:19 +0800
Subject: [PATCH] feat(stt): pass local initial_prompt to faster-whisper

---
 cli-config.yaml.example           |  1 +
 tests/tools/test_transcription.py | 44 +++++++++++++++++++++++++++++++
 tools/transcription_tools.py      |  6 ++++-
 3 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index c5097e9fbee6..43eb3c2dcff1 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -1127,6 +1127,7 @@ stt:
   local:
     model: "base"              # tiny | base | small | medium | large-v3 | turbo
     # language: ""             # auto-detect; set to "en", "es", "fr", etc. to force
+    # initial_prompt: ""       # Optional faster-whisper prompt, e.g. bias Chinese output to simplified Chinese
   # groq:
   #   language: ""             # blank = use HERMES_LOCAL_STT_LANGUAGE if set, else auto-detect
   openai:
diff --git a/tests/tools/test_transcription.py b/tests/tools/test_transcription.py
index 669b28e302bb..c1bba550eca0 100644
--- a/tests/tools/test_transcription.py
+++ b/tests/tools/test_transcription.py
@@ -152,6 +152,50 @@ class TestTranscribeLocal:
         assert result["success"] is True
         assert result["transcript"] == "Hello world"
 
+    def test_passes_initial_prompt_when_configured(self, tmp_path):
+        audio_file = tmp_path / "test.ogg"
+        audio_file.write_bytes(b"fake audio")
+
+        mock_info = MagicMock(language="zh", duration=2.5)
+        mock_model = MagicMock()
+        mock_model.transcribe.return_value = ([], mock_info)
+
+        fake_fw = _fake_faster_whisper_module(mock_model)
+        with patch("tools.transcription_tools._HAS_FASTER_WHISPER", True), \
+             patch("tools.transcription_tools._load_stt_config", return_value={
+                 "local": {"initial_prompt": "以下是普通话的句子，使用简体中文。"},
+             }), \
+             patch.dict("sys.modules", {"faster_whisper": fake_fw}), \
+             patch("tools.transcription_tools._local_model", None):
+            from tools.transcription_tools import _transcribe_local
+            result = _transcribe_local(str(audio_file), "base")
+
+        assert result["success"] is True
+        assert mock_model.transcribe.call_args.kwargs["initial_prompt"] == (
+            "以下是普通话的句子，使用简体中文。"
+        )
+
+    def test_omits_blank_initial_prompt(self, tmp_path):
+        audio_file = tmp_path / "test.ogg"
+        audio_file.write_bytes(b"fake audio")
+
+        mock_info = MagicMock(language="en", duration=2.5)
+        mock_model = MagicMock()
+        mock_model.transcribe.return_value = ([], mock_info)
+
+        fake_fw = _fake_faster_whisper_module(mock_model)
+        with patch("tools.transcription_tools._HAS_FASTER_WHISPER", True), \
+             patch("tools.transcription_tools._load_stt_config", return_value={
+                 "local": {"initial_prompt": "   "},
+             }), \
+             patch.dict("sys.modules", {"faster_whisper": fake_fw}), \
+             patch("tools.transcription_tools._local_model", None):
+            from tools.transcription_tools import _transcribe_local
+            result = _transcribe_local(str(audio_file), "base")
+
+        assert result["success"] is True
+        assert "initial_prompt" not in mock_model.transcribe.call_args.kwargs
+
     def test_not_installed(self):
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False):
             from tools.transcription_tools import _transcribe_local
diff --git a/tools/transcription_tools.py b/tools/transcription_tools.py
index 25bb458fde85..19015f6c8dc7 100644
--- a/tools/transcription_tools.py
+++ b/tools/transcription_tools.py
@@ -1155,14 +1155,18 @@ def _transcribe_local(file_path: str, model_name: str) -> Dict[str, Any]:
             _local_model_name = model_name
 
         # Language: config.yaml (stt.local.language) > env var > auto-detect.
+        local_config = _load_stt_config().get("local") or {}
         _forced_lang = (
-            (_load_stt_config().get("local") or {}).get("language")
+            local_config.get("language")
             or os.getenv(LOCAL_STT_LANGUAGE_ENV)
             or None
         )
         transcribe_kwargs = {"beam_size": 5}
         if _forced_lang:
             transcribe_kwargs["language"] = _forced_lang
+        initial_prompt = local_config.get("initial_prompt")
+        if isinstance(initial_prompt, str) and initial_prompt.strip():
+            transcribe_kwargs["initial_prompt"] = initial_prompt
 
         try:
             segments, info = _local_model.transcribe(file_path, **transcribe_kwargs)