aichat-sdk 0.1.0__tar.gz

aichat_sdk-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+build
+dist
+*.egg
+*.egg-info
+.DS_Store
+__pycache__/
+.idea/
+
+# uv
+.venv/
+
+# pytest and coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+
+.env
+*.log
+*.pt
+
+aichat_sdk/asr/audio_*
+
+examples/web/config.json
+examples/web/sessions/

aichat_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: aichat_sdk
+Version: 0.1.0
+Summary: Chat SDK: LLM streaming, MCP tools, and ByteDance bidirectional TTS.
+Project-URL: Homepage, https://gitee.com/fa0/aichat_sdk
+Project-URL: Repository, https://gitee.com/fa0/aichat_sdk
+Author: dairoot
+Keywords: chat,openai,sdk,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: av>=12.0
+Requires-Dist: edge-tts>=7.0
+Requires-Dist: fastmcp>=3.4.7
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: lunardate==0.2.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: openai>=1.40.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-socks>=3.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sounddevice>=0.5.6
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aichat_sdk
+
+一个语音对话 SDK。用户对着麦克风说话，SDK 负责听懂（语音识别）、想清楚（大模型 + 工具）、说出来（语音合成），宿主程序只需要把声音收进来、把声音放出去。
+
+## 它能做什么
+
+- **像人一样聊天**：回复是口语、短句，不念标题、不念符号，适合直接朗读；用户随时插话就能打断
+- **会查东西**：天气、笑话、联网搜索（微博、搜狗，不用配 key），还能按需接入外部 MCP 工具
+- **会用技能**：读取本机 `~/.agents/skills` 下的技能说明，按里面的指引一步步执行命令，比如查飞书群聊、发消息、看日程
+- **会放音乐**：本地曲库点歌，边放边推歌词
+- **知道时间和地点**：公历、农历、临近节日、用户所在城市，都会告诉模型
+- **自己结束对话**：聊完了或者空闲太久，会说句再见然后关会话
+
+## 它是怎么工作的
+
+整条链路是一根事件驱动的流水线：
+
+1. **听**：麦克风的声音通过 WebSocket 送到独立的 ASR 服务（单独的 `asr_server` 仓库，识别、断句、声纹都在那边），识别结果回到 SDK
+2. **想**：识别出的文字交给大模型。模型可以直接回答，也可以先调工具、读技能、执行命令，拿到结果再回答；整个过程流式进行，第一个字出来就开始往下传
+3. **说**：模型每吐出一点文字就喂给语音合成，合成出的音频编成 Opus 包排进队列
+4. **播**：宿主从队列里按顺序取消息——识别结果、工具调用、每句话的开始和结束、音频包、歌词、结束信号——自己解码播放
+
+有一条必须遵守的约定：**收到音频就把麦克风静音，收到「音频播完」再恢复拾音**，否则机器会听见自己说话。
+
+## 大模型这一层
+
+- 支持任何 OpenAI 兼容的接口，实际用过 DeepSeek 和通义千问
+- 系统提示词是模板生成的，把角色人设、当前日期、用户位置、可用技能清单一起注入；提示词专门为语音场景写，要求模型说人话、说短话
+- **思考模式按需开关**：用户刚说完话的第一次调用不开思考，保证回得快；一旦调过工具，后面的调用就打开思考，让推理过程走单独的通道、不会被念出来（`AgentInfo.tool_thinking` 可关掉，网页控制台上也有对应勾选框）。这么做是因为某些模型关掉思考后会把「让我先看看」这类内心独白直接写进回复，提示词管不住
+- 推理内容会保存在对话记录里，web 页面上折叠显示，方便排查模型为什么这么答
+
+## 语音合成
+
+- **字节跳动**（默认）：服务端双向流式，逐字喂进去就出声，延迟最低
+- **微软 Edge**：免 key，按标点切成小段并发请求，段短所以首包也快
+
+两种引擎输出格式一致，切换只需要改一个参数。
+
+## 怎么试
+
+- 配好 `.env`：大模型的地址、模型名和 key；用字节 TTS 的话再加它的 App ID 和 Key；ASR 服务地址不改就用默认的本机端口
+- 先把 `asr_server` 跑起来
+- 有麦克风和扬声器就运行 `tests/test_run_v2.py` 直接对话；没有麦克风就运行 `tests/test_run.py`，它在代码里塞了两句话进去
+- 想边聊边改配置，运行 `examples/web/main.py`，浏览器打开本机 8080 端口：可以换模型、换音色、改人设、开关工具、配外部 MCP，保存后立即生效；页面上还能实时看到每一轮对话、工具调用和模型的思考内容，每轮聊完会自动存一份完整记录
+
+## 给开发者
+
+要改代码，先看 `AGENTS.md`：队列和事件的实现细节、MCP 工具怎么注册注销、TTS 会话的生命周期限制、各种踩过的坑都记在那里。

aichat_sdk-0.1.0/README.md

@@ -0,0 +1,48 @@
+# aichat_sdk
+
+一个语音对话 SDK。用户对着麦克风说话，SDK 负责听懂（语音识别）、想清楚（大模型 + 工具）、说出来（语音合成），宿主程序只需要把声音收进来、把声音放出去。
+
+## 它能做什么
+
+- **像人一样聊天**：回复是口语、短句，不念标题、不念符号，适合直接朗读；用户随时插话就能打断
+- **会查东西**：天气、笑话、联网搜索（微博、搜狗，不用配 key），还能按需接入外部 MCP 工具
+- **会用技能**：读取本机 `~/.agents/skills` 下的技能说明，按里面的指引一步步执行命令，比如查飞书群聊、发消息、看日程
+- **会放音乐**：本地曲库点歌，边放边推歌词
+- **知道时间和地点**：公历、农历、临近节日、用户所在城市，都会告诉模型
+- **自己结束对话**：聊完了或者空闲太久，会说句再见然后关会话
+
+## 它是怎么工作的
+
+整条链路是一根事件驱动的流水线：
+
+1. **听**：麦克风的声音通过 WebSocket 送到独立的 ASR 服务（单独的 `asr_server` 仓库，识别、断句、声纹都在那边），识别结果回到 SDK
+2. **想**：识别出的文字交给大模型。模型可以直接回答，也可以先调工具、读技能、执行命令，拿到结果再回答；整个过程流式进行，第一个字出来就开始往下传
+3. **说**：模型每吐出一点文字就喂给语音合成，合成出的音频编成 Opus 包排进队列
+4. **播**：宿主从队列里按顺序取消息——识别结果、工具调用、每句话的开始和结束、音频包、歌词、结束信号——自己解码播放
+
+有一条必须遵守的约定：**收到音频就把麦克风静音，收到「音频播完」再恢复拾音**，否则机器会听见自己说话。
+
+## 大模型这一层
+
+- 支持任何 OpenAI 兼容的接口，实际用过 DeepSeek 和通义千问
+- 系统提示词是模板生成的，把角色人设、当前日期、用户位置、可用技能清单一起注入；提示词专门为语音场景写，要求模型说人话、说短话
+- **思考模式按需开关**：用户刚说完话的第一次调用不开思考，保证回得快；一旦调过工具，后面的调用就打开思考，让推理过程走单独的通道、不会被念出来（`AgentInfo.tool_thinking` 可关掉，网页控制台上也有对应勾选框）。这么做是因为某些模型关掉思考后会把「让我先看看」这类内心独白直接写进回复，提示词管不住
+- 推理内容会保存在对话记录里，web 页面上折叠显示，方便排查模型为什么这么答
+
+## 语音合成
+
+- **字节跳动**（默认）：服务端双向流式，逐字喂进去就出声，延迟最低
+- **微软 Edge**：免 key，按标点切成小段并发请求，段短所以首包也快
+
+两种引擎输出格式一致，切换只需要改一个参数。
+
+## 怎么试
+
+- 配好 `.env`：大模型的地址、模型名和 key；用字节 TTS 的话再加它的 App ID 和 Key；ASR 服务地址不改就用默认的本机端口
+- 先把 `asr_server` 跑起来
+- 有麦克风和扬声器就运行 `tests/test_run_v2.py` 直接对话；没有麦克风就运行 `tests/test_run.py`，它在代码里塞了两句话进去
+- 想边聊边改配置，运行 `examples/web/main.py`，浏览器打开本机 8080 端口：可以换模型、换音色、改人设、开关工具、配外部 MCP，保存后立即生效；页面上还能实时看到每一轮对话、工具调用和模型的思考内容，每轮聊完会自动存一份完整记录
+
+## 给开发者
+
+要改代码，先看 `AGENTS.md`：队列和事件的实现细节、MCP 工具怎么注册注销、TTS 会话的生命周期限制、各种踩过的坑都记在那里。

aichat_sdk-0.1.0/aichat_sdk/__init__.py

@@ -0,0 +1,423 @@
+import asyncio
+import json
+import logging
+from typing import Any
+
+from aichat_sdk.asr.asr_client import AsrWebSocketClient
+from aichat_sdk.config import ASR_SERVER_WS_URL
+from aichat_sdk.llm import LlmAgent
+from aichat_sdk.llm.mcp import get_default_chat_tools
+from aichat_sdk.llm.type_enum import AgentInfo, DeviceInfo
+from aichat_sdk.utils.opus_codec import (
+    OpusStreamDecoder,
+    OpusStreamEncoder,
+    PcmStreamResampler,
+)
+
+__version__ = "0.1.0"
+
+
+logger = logging.getLogger(__name__)
+
+IDLE_TIMEOUT_SECONDS = 60
+IDLE_FAREWELL_PROMPT = (
+    "用户已长时间没有说话，本次会话即将自动结束。"
+    "请直接输出一两句简短自然的道别话，可以结合刚才聊到的内容。"
+    "只输出纯文本，不要调用任何工具，也不要向用户提问或期待回复。"
+)
+
+
+def get_tts_client(tts_engine: str = "bytedance"):
+    engine = tts_engine.lower()
+    if engine in {"edge", "edge-tts"}:
+        from aichat_sdk.tts.edge.bidirection import EdgeTTSClient
+
+        return EdgeTTSClient()
+    if engine in {"bytedance", "v2", "bytedancev2"}:
+        from aichat_sdk.tts.bytedancev2.bidirection import BytedanceTTSClient
+
+        return BytedanceTTSClient(voice_type="zh_female_wanwanxiaohe_moon_bigtts")
+    if engine in {"v3", "bytedancev3"}:
+        from aichat_sdk.tts.bytedancev3.bidirection import BytedanceTTSClient
+
+        return BytedanceTTSClient(voice_type="zh_female_vv_uranus_bigtts")
+    raise ValueError("未知 tts_engine，支持: bytedance, v2, v3, edge")
+
+
+class ChatBot:
+    def __init__(
+        self,
+        tts_engine: str = "bytedance",
+        input_sample_rate: int = 24000,  # Opus 编码采样率(限 8k/12k/16k/24k/48k)，TTS 源 PCM 采样率不同时会自动重采样;
+        output_sample_rate: int = 24000,  # 宿主解码后拿到的 PCM 采样率(任意),解码器用 create_opus_decoder() 创建。
+        asr_server_url: str = ASR_SERVER_WS_URL,  # ASR 服务地址
+        send_idle_farewell: bool = True,  # 空闲超时后是否先发送告别语,为 False 时直接关闭会话。
+        user_info: DeviceInfo = DeviceInfo(timezone=8, city="北京"),  # 用户信息
+        agent_info: AgentInfo = AgentInfo(),  # 角色信息
+    ) -> None:
+        """input_sample_rate:Opus 编码采样率(限 8k/12k/16k/24k/48k)，
+        TTS 源 PCM 采样率不同时会自动重采样;
+        output_sample_rate:宿主解码后拿到的 PCM 采样率(任意),解码器用 create_opus_decoder() 创建。
+        send_idle_farewell:空闲超时后是否先发送告别语,为 False 时直接关闭会话。
+        """
+        self.tts = get_tts_client(tts_engine)
+        self.asr = AsrWebSocketClient(asr_server_url)
+
+        self.output_sample_rate = output_sample_rate
+        self._send_idle_farewell = send_idle_farewell
+        self.llm = LlmAgent(user_info=user_info, agent_info=agent_info)
+        self._queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._input_sample_rate = input_sample_rate
+        self._opus_encoder = OpusStreamEncoder(input_sample_rate)
+        self._pcm_resampler: PcmStreamResampler | None = None
+        self._audio_text = ""
+        self._audio_terminal_sent = True
+        self._tts_session_started = False
+        self._chat_task: asyncio.Task | None = None
+        self._session_lock = asyncio.Lock()
+        self._asr_dispatch_tasks: set[asyncio.Task] = set()
+        self._pending_mcp_call: tuple[str, dict[str, Any]] | None = None
+        # 宿主从队列取走 audio_finish 时置位，等"真正播完"用
+        self._audio_finish_consumed = asyncio.Event()
+
+        self._is_session_closed = False
+        self._idle_task: asyncio.Task | None = None
+
+    def create_opus_decoder(self) -> OpusStreamDecoder:
+        """给宿主建配套解码器,输出 output_sample_rate 的 PCM,按同样的采样率播放。"""
+        return OpusStreamDecoder(self.output_sample_rate)
+
+    def audio_callback(self, indata, frames, time, status) -> None:
+        """把宿主采集的 16 kHz 单声道 Float32 PCM 发往 ASR 服务。"""
+        self.asr.audio_callback(indata, frames, time, status)
+
+    def _start_idle_timer(self):
+        self._cancel_idle_timer()
+        if not self._is_session_closed:
+            self._idle_task = asyncio.create_task(self._idle_farewell())
+
+    def _cancel_idle_timer(self):
+        if self._idle_task and not self._idle_task.done():
+            self._idle_task.cancel()
+        self._idle_task = None
+
+    async def _idle_farewell(self):
+        """超过 IDLE_TIMEOUT_SECONDS 用户无回复,按配置告别或直接结束会话。"""
+        await asyncio.sleep(IDLE_TIMEOUT_SECONDS)
+        # 先清引用再 send_text,否则 send_text 里的 abort 会把当前任务自己 cancel 掉
+        self._idle_task = None
+        self._is_session_closed = True
+
+        if self._send_idle_farewell:
+            logger.info(f"[idle] 用户超过 {IDLE_TIMEOUT_SECONDS}s 未回复,推送告别")
+            await self.send_text("", response_instructions=IDLE_FAREWELL_PROMPT, role="user")
+            # await self.send_text(IDLE_FAREWELL_PROMPT, role="system")
+
+        else:
+            logger.info(f"[idle] 用户超过 {IDLE_TIMEOUT_SECONDS}s 未回复,直接关闭")
+            await self._queue.put({"type": "close"})
+
+    async def receive_item(self):
+        item = await self._queue.get()
+        if item.get("type") == "lyric":
+            logger.info(f"[music] lyric: {item['data']}")
+        # 空闲计时以宿主消费(≈播放)节奏为准:取到 audio_finish 即真正播完、开始计时;
+        # 音频是瞬间推满队列的(整首歌几秒推完),按推送侧计时会在播放途中误触发。
+        elif item.get("type") == "audio_finish":
+            self._start_idle_timer()
+            self._audio_finish_consumed.set()
+        elif item.get("type") == "audio":
+            self._cancel_idle_timer()
+        return item
+
+    async def reg_llm(self):
+
+        @self.llm.on("text")
+        async def handle_chat_text(text: str):
+            # 会话开着但 10s 没收到文本，服务端就把它作废:之后送的字不再出声,
+            # FinishSession 也可能不回(实测 9s 正常、10s 起必挂)。工具调用和
+            # LLM 首字慢都能轻松撑过 10s，所以等真的有字了再开会话。
+            if not self._tts_session_started:
+                self._tts_session_started = True
+                await self.tts.start_session()
+            await self.tts.send_char(text)
+
+        @self.llm.on("tool")
+        async def handle_chat_tool(payload: dict):
+            arguments_str = payload["arguments"]
+            if len(arguments_str) > 50:
+                arguments_str = arguments_str[:50] + "..."
+            logger.info(f"[tool] tool_call: {payload['name']} ({arguments_str})")
+            await self._queue.put({"type": "tool", "data": payload})
+
+        @self.llm.on("before_tool_exec")
+        async def handle_chat_before_tool_exec(text: str):
+            await self._wait_audio_played(text)
+
+        @self.llm.on("tool_results")
+        async def handle_chat_tool_results(payload: list[dict]):
+            payload_str = json.dumps(payload, ensure_ascii=False)
+            if len(payload_str) > 100:
+                payload_str = payload_str[:100] + "..."
+            logger.info(f"[tool] tool_results: {payload_str}")
+            await self._queue.put({"type": "tool_results", "data": payload})
+
+            if any(msg.get("name") == "end_session" for msg in payload):
+                self._is_session_closed = True
+
+            for msg in payload:
+                if msg["name"] == "play_music":
+                    try:
+                        result = json.loads(msg["content"])
+                        mcp_name = result.get("mcp")
+                        song = result.get("song")
+                        if isinstance(mcp_name, str) and isinstance(song, str):
+                            self._pending_mcp_call = (mcp_name, {"song": song})
+                    except (json.JSONDecodeError, KeyError, TypeError):
+                        pass  # 结果里没有 path 说明选歌失败，无需播放
+
+        @self.llm.on("finish")
+        async def handle_chat_finish(text: str):
+            self._audio_text = text
+            await self.tts.finish_session()
+            # 正常实现会在 finish_session 内触发 audio_finish；这里作为协议
+            # 兜底，防止第三方 TTS 返回却忘记发终结事件。
+            await self._finish_audio_and_followups()
+
+    async def reg_tts(self):
+
+        @self.tts.on("audio")
+        async def handle_audio(pcm_data: bytes):
+            if self._pcm_resampler is not None:
+                pcm_data = self._pcm_resampler.resample(pcm_data)
+            for packet in self._opus_encoder.encode(pcm_data):
+                await self._queue.put({"type": "audio", "data": packet})
+
+        @self.tts.on("audio_finish")
+        async def handle_audio_finish():
+            await self._finish_audio_and_followups()
+
+        @self.tts.on("sentence_start")
+        async def handle_sentence_start(text: str):
+            logger.info(f"[tts] {text}")
+            await self._queue.put({"type": "sentence_start", "data": text})
+
+        @self.tts.on("sentence_end")
+        async def handle_sentence_end(text: str):
+            await self._queue.put({"type": "sentence_end", "data": text})
+
+    async def reg_asr(self):
+        @self.asr.on("stt")
+        async def handle_stt(payload: dict):
+            logger.info(f"[asr] {payload['content']}")
+            self.tts.set_last_context_text(payload["content"])
+            task = asyncio.create_task(self.send_text(payload["content"], audio_url=payload.get("audio_url")))
+            self._asr_dispatch_tasks.add(task)
+            task.add_done_callback(self._finish_asr_dispatch)
+
+        @self.asr.on("error")
+        async def handle_asr_error(payload: dict):
+            logger.error("[asr] server error: %s", payload)
+
+    def _finish_asr_dispatch(self, task: asyncio.Task) -> None:
+        self._asr_dispatch_tasks.discard(task)
+        if task.cancelled():
+            return
+        error = task.exception()
+        if error is not None:
+            logger.error(
+                "ASR result dispatch failed",
+                exc_info=(type(error), error, error.__traceback__),
+            )
+
+    async def initialize(self):
+        await self.reg_llm()
+        await self.reg_tts()
+        await self.reg_asr()
+        try:
+            await self.asr.connect()
+        except Exception as e:
+            logger.error(f"ASR connect failed: {e}")
+            await self.asr.close()
+            exit(1)
+        try:
+            await self.tts.connect()
+        except Exception as e:
+            logger.error(f"TTS connect failed: {e}")
+            await self.tts.close()
+            exit(1)
+        # 工具列表是懒构建的，不预热的话第一次拉起外部 MCP server（stdio 子进程）
+        # 的耗时会算进第一轮回复；构建是阻塞调用，放线程里跑不挡事件循环。
+        await asyncio.to_thread(get_default_chat_tools)
+        source_sample_rate = getattr(
+            self.tts,
+            "sample_rate",
+            self._input_sample_rate,
+        )
+        if source_sample_rate != self._input_sample_rate:
+            self._pcm_resampler = PcmStreamResampler(
+                source_sample_rate,
+                self._input_sample_rate,
+            )
+        self._start_idle_timer()
+
+    async def close(self):
+        self._cancel_idle_timer()
+        for task in self._asr_dispatch_tasks:
+            task.cancel()
+        if self._asr_dispatch_tasks:
+            await asyncio.gather(
+                *self._asr_dispatch_tasks,
+                return_exceptions=True,
+            )
+        self._asr_dispatch_tasks.clear()
+        await self.abort()
+        await self.asr.close()
+        close = getattr(self.tts, "close", None) or getattr(
+            self.tts,
+            "disconnect",
+            None,
+        )
+        if close is not None:
+            await close()
+
+    async def _run_session_task(self, coroutine_factory) -> None:
+        async with self._session_lock:
+            await self._abort_locked()
+            task = asyncio.create_task(coroutine_factory())
+            self._chat_task = task
+        try:
+            await task
+        except asyncio.CancelledError:
+            # 被下一轮会话替换时，只有子任务被 cancel，当前包装任务本身没有
+            # cancellation request；调用方主动 cancel 时则清理会话并继续传播。
+            if asyncio.current_task().cancelling():
+                async with self._session_lock:
+                    if self._chat_task is task:
+                        await self._abort_locked(notify_host=True)
+                raise
+        finally:
+            async with self._session_lock:
+                if self._chat_task is task:
+                    self._chat_task = None
+
+    async def send_text(self, user_text: str, role: str = "user", response_instructions: str = None, audio_url: str | None = None):
+        """audio_url:这句话对应的用户录音地址(ASR 服务给的),只挂在 messages 上供宿主回放,不发给 LLM。"""
+        await self._run_session_task(lambda: self._run_chat(user_text, role, response_instructions, audio_url))
+
+    async def _run_chat(self, user_text: str, role, response_instructions, audio_url: str | None = None):
+        self._prepare_audio_session()
+        try:
+            await self._queue.put({"type": "stt", "data": user_text})
+            await self.llm.chat(user_text, role, response_instructions, audio_url=audio_url)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("chat pipeline failed")
+            await self._fail_audio_session()
+            raise
+
+    async def send_tts_text(self, text: str):
+        await self._run_session_task(lambda: self._run_tts_text(text))
+
+    async def _run_tts_text(self, text: str) -> None:
+        self._prepare_audio_session()
+        try:
+            await self.tts.start_session()
+            await self.tts.send_char(text)
+            self._audio_text = text
+            await self.tts.finish_session()
+            await self._finish_audio_and_followups()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("direct TTS pipeline failed")
+            await self._fail_audio_session()
+            raise
+
+    async def _wait_audio_played(self, text: str) -> None:
+        """工具执行前等本轮已出声的文本真正播完。
+
+        先收掉 TTS 会话、推 audio_finish，再等宿主把它取走（音频是瞬间推满队列的，
+        只有宿主取到 audio_finish 才算播完）。之后按新一段音频处理:工具返回后的
+        回复重新开会话、结束时再推一条 audio_finish。一个字都没吐过就不用等，
+        也不能去收一个没开过的会话。
+        """
+        if not self._tts_session_started:
+            return
+        self._audio_text = text
+        self._audio_finish_consumed.clear()
+        await self.tts.finish_session()
+        await self._finish_audio_and_followups()
+        await self._audio_finish_consumed.wait()
+        # 取走 audio_finish 会起空闲计时，但工具还在跑，不算用户没回复
+        self._cancel_idle_timer()
+        self._prepare_audio_session()
+
+    def _prepare_audio_session(self) -> None:
+        self._audio_text = ""
+        self._audio_terminal_sent = False
+        self._tts_session_started = False
+
+    async def _enqueue_audio_finish(self) -> bool:
+        if self._audio_terminal_sent:
+            return False
+        self._audio_terminal_sent = True
+        if self._pcm_resampler is not None:
+            pcm = self._pcm_resampler.flush()
+            for packet in self._opus_encoder.encode(pcm):
+                await self._queue.put({"type": "audio", "data": packet})
+        for packet in self._opus_encoder.flush():
+            await self._queue.put({"type": "audio", "data": packet})
+        await self._queue.put({"type": "audio_finish", "data": self._audio_text})
+        return True
+
+    async def _finish_audio_and_followups(self) -> None:
+        if not await self._enqueue_audio_finish():
+            return
+        if self._is_session_closed:
+            await self._queue.put({"type": "close"})
+        elif self._pending_mcp_call:
+            # 等本轮回复的语音播完再开始放歌，避免歌声盖住回复
+            name, args = self._pending_mcp_call
+            self._pending_mcp_call = None
+            async for data in self.llm.stream_mcp_tool(name, args):
+                await self._queue.put(data)
+
+    async def _fail_audio_session(self) -> None:
+        try:
+            await self.tts.abort()
+        except Exception:
+            logger.exception("failed to abort TTS after pipeline error")
+        await self._enqueue_audio_finish()
+
+    async def abort(self):
+        async with self._session_lock:
+            await self._abort_locked(notify_host=True)
+
+    async def _abort_locked(self, *, notify_host: bool = False) -> None:
+        self._cancel_idle_timer()
+        session_was_active = not self._audio_terminal_sent
+        task = self._chat_task
+        if task and task is not asyncio.current_task() and not task.done():
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+
+        if self._chat_task is task:
+            self._chat_task = None
+        self._pending_mcp_call = None
+        try:
+            await self.tts.abort()
+        except Exception:
+            logger.exception("failed to abort TTS session")
+        if self._pcm_resampler is not None:
+            self._pcm_resampler.reset()
+        self._opus_encoder.reset()
+        removed_audio_finish = False
+        while not self._queue.empty():
+            item = self._queue.get_nowait()
+            removed_audio_finish |= item.get("type") == "audio_finish"
+        self._audio_text = ""
+        self._audio_terminal_sent = True
+        if notify_host and (session_was_active or removed_audio_finish):
+            await self._queue.put({"type": "audio_finish", "data": ""})