arona-agent 1.0.2 → 1.0.3

package/README.md

@@ -15,7 +15,7 @@
 ## 安装
 
 ```bash
-npm install -g git+https://github.com/SRC114514/arona-agent.git
+npm install -g arona-agent
 
 # 初始化配置文件
 arona setup
@@ -23,6 +23,9 @@ arona setup
 # 初始化后可直接启动
 arona
 
+# 更新
+npm update -g arona-agent
+
 # 禁用TTS+STT并启动
 arona --no-voice
 
@@ -146,4 +149,4 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 - 本项目不得用于影响版权方权益之分发，否则自行承担相关侵权责任。
 
 此类内容的知识产权归Nexon Games Co., Ltd.及YOSTAR LIMITED所有，其使用、复制及分发规则应严格遵循上述权利方的官方条款及适用法律法规。
-若相关权利人认为本声明或项目使用方式存在不当，可与我联系，将在核实后第一时间调整或移除相关内容。
+若相关权利人认为本声明或项目使用方式存在不当，可与我联系，将在核实后第一时间调整或移除相关内容。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arona-agent",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Terminal AI Agent with desktop pet Arona — eye-tracking pupils, voice cloning, Computer Use, TTS/STT, MCP.",
   "license": "MIT",
   "type": "module",

package/pet/renderer/style.css

@@ -34,11 +34,12 @@ body:active {
 
 
 /* 桌宠文字气泡：定位到角色头部右侧，贴近角色（不遮脸、不高高飘在右上）；
-   top 取头部高度（头 CSS y 40~195），left 紧邻渲染区右缘（320 + 10px 间距）；
+   top 取头部高度（头 CSS y 40~195），left 270px 贴近头部右缘（≈250）留 ~20px 缝隙，
+   由 ::after 小尾巴向左伸进缝隙指向角色（视觉上"连到"角色，不显远）；
    高于 Spine、鼠标穿透；只显示 mid/final 短消息 */
 #pet-bubble {
   position: absolute;
-  left: 310px;
+  left: 270px;
   top: 90px;
   transform: none;
   max-width: 220px;
@@ -58,6 +59,19 @@ body:active {
   transition: opacity 0.25s ease;
 }
 
+/* 左指小三角尾巴：从气泡左缘向左伸进气泡与角色头部的缝隙里，指向角色。
+   随父级 hidden / opacity 过渡一起隐藏。top 取气泡中部即可，位置可按需微调 */
+#pet-bubble::after {
+  content: "";
+  position: absolute;
+  left: -12px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-top: 8px solid transparent;
+  border-bottom: 8px solid transparent;
+  border-right: 12px solid rgba(20, 22, 34, 0.82);
+}
+
 #pet-bubble.hidden {
   opacity: 0;
 }

package/python/tts_say.py

@@ -145,6 +145,65 @@ def play_wav(data):
         _play_fallback(data)
 
 
+def _write_temp_wav(data):
+    """写入临时 wav，返回路径（供 synth_only 模式：合成后暂存，由 play 模式进程读取并删除）。"""
+    tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+    tmp.write(data)
+    tmp.close()
+    return tmp.name
+
+
+def _synth_and_play(cmd):
+    """默认模式：合成 + 播放（向后兼容，预合成流水线回退路径）。"""
+    text = (cmd.get("text") or "").strip()
+    voice = cmd.get("voice") or ""
+    if not text:
+        emit("error", message=t("TTS: 空文本", "TTS: empty text"))
+        sys.stdout.flush()
+        return
+    audio = synthesize(text, voice)
+    emit("play_start")
+    play_wav(audio)
+    emit("play_end")
+
+
+def _synth_only(cmd):
+    """预合成模式：只合成，写临时 wav 后发 synth_done（带路径）退出，不播放。
+    Node 侧在上一句播放期间调用本模式预合成下一句，消除句间 HTTP 合成停顿。"""
+    text = (cmd.get("text") or "").strip()
+    voice = cmd.get("voice") or ""
+    if not text:
+        emit("error", message=t("TTS: 空文本", "TTS: empty text"))
+        sys.stdout.flush()
+        return
+    audio = synthesize(text, voice)
+    path = _write_temp_wav(audio)
+    emit("synth_done", path=path)
+
+
+def _play_path(cmd):
+    """播放模式：读已合成的临时 wav 播放（无 HTTP），播完删除临时文件。"""
+    path = cmd.get("path") or ""
+    if not path or not os.path.exists(path):
+        emit("error", message=t("TTS: 无效的音频路径", "TTS: invalid audio path"))
+        sys.stdout.flush()
+        return
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+    except Exception as e:
+        emit("error", message=str(e))
+        sys.stdout.flush()
+        return
+    try:
+        os.unlink(path)
+    except Exception:
+        pass
+    emit("play_start")
+    play_wav(data)
+    emit("play_end")
+
+
 def main():
     emit("ready")
     line = sys.stdin.readline()
@@ -156,17 +215,14 @@ def main():
         emit("error", message=t("TTS: 无效的 stdin JSON", "TTS: invalid stdin JSON"))
         sys.stdout.flush()
         return
-    text = (cmd.get("text") or "").strip()
-    voice = cmd.get("voice") or ""
-    if not text:
-        emit("error", message=t("TTS: 空文本", "TTS: empty text"))
-        sys.stdout.flush()
-        return
+    mode = cmd.get("mode") or "synth_play"
     try:
-        audio = synthesize(text, voice)
-        emit("play_start")
-        play_wav(audio)
-        emit("play_end")
+        if mode == "synth_only":
+            _synth_only(cmd)
+        elif mode == "play":
+            _play_path(cmd)
+        else:
+            _synth_and_play(cmd)
         sys.stdout.flush()
     except Exception as e:
         emit("error", message=str(e))

package/src/agent.ts

@@ -21,6 +21,7 @@ import { connectMcpServers } from "./mcp.ts";
 import { InMemoryCredentialStore } from "./in_memory_credentials.ts";
 import { getMainAgent, type SubAgentId, type AgentId } from "./agent_registry.ts";
 import { speakerContextExtension } from "./speaker_context.ts";
+import { gestureContextExtension } from "./gesture_context.ts";
 import { t, getLang } from "./locale.ts";
 
 // Asia/Shanghai 当前时间，注入到 system prompt 供情境台词使用；语言随界面
@@ -571,7 +572,7 @@ export async function initAgent(): Promise<{
     appendSystemPromptOverride: () => [],
     // 群聊发言者标注：发送边界给带 speaker 的历史 assistant 消息加「角色名：」前缀，
     // 让模型区分谁说的（speaker 字段不会发给模型，必须编码进文本）
-    extensionFactories: [speakerContextExtension],
+    extensionFactories: [speakerContextExtension, gestureContextExtension],
   });
   await loader.reload();
 

package/src/gesture_context.ts

@@ -0,0 +1,48 @@
+// 桌宠手势上下文注入扩展：摸头/dizzy 触发后，在**主 Agent** 的发送边界（context 事件）
+// 追加一条 user 消息，描述"刚才发生了什么"，引导主 Agent 在回复中自然流露出确实感受到了。
+//
+// 为什么用发送边界而不是拼进用户输入：repl.ts 的 processInput 会把文本写进主 session 的
+// state.messages，而子 Agent 每轮复制主 session 全量历史（repl.ts runOneAgent）——那样手势
+// 提示词会下放给子 Agent、还会污染会话命名/存储。发送边界注入只改本次请求的消息数组、
+// 不进 state.messages → 仅主 Agent 看到、零存储污染、会话命名天然干净。
+//
+// 只注册在**主 Agent** 的 loader 扩展列表（agent.ts initAgent），子 Agent（initSubAgent）
+// 的 loader 不含本扩展 → 不会收到。消费经 pet.takeGesture()（消费即清空，只注入最近一次）。
+
+import type { ContextEvent, ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { pet } from "./pet.ts";
+import { t } from "./locale.ts";
+
+/** 桌宠手势 → user 消息的上下文场景文本（双语）。 */
+function petGestureScene(type: "pat" | "dizzy"): string {
+  if (type === "dizzy") {
+    return t(
+      "（Sensei刚才拖着你到处晃来晃去，你感觉有些头晕。请在回复里自然地体现出这份晕眩感。）",
+      "(Sensei just swung you around, and you feel a bit dizzy. Let that dizziness show naturally in your reply.)",
+    );
+  }
+  return t(
+    "（Sensei刚才摸了摸你的头。请在回复里自然地体现出被摸头的感受。）",
+    "(Sensei just petted your head. Let that show naturally in your reply.)",
+  );
+}
+
+export const gestureContextExtension: InlineExtension = {
+  name: "arona-gesture-context",
+  hidden: true, // 不显示在启动扩展列表
+  factory: (pi: ExtensionAPI) => {
+    pi.on("context", (event: ContextEvent) => {
+      // 有手势时才注入；takeGesture 消费即清空 → 一次 LLM 调用只注入一次、无手势时原样返回
+      const gesture = pet.takeGesture();
+      if (!gesture) return;
+      const scene = petGestureScene(gesture);
+      if (!scene) return;
+      return {
+        messages: [
+          ...event.messages,
+          { role: "user", content: [{ type: "text", text: scene }] },
+        ],
+      };
+    });
+  },
+};

package/src/memory.ts

@@ -171,12 +171,7 @@ interface SessionHeader {
   preview: string;
 }
 
-/**
- * 从首条 user 消息提取会话预览。
- * 剥离 repl.ts 注入的桌宠手势场景块（全角括号 `（…）` 包裹、后随空行），
- * 避免"摸头/dizzy 提示词"污染会话命名（用户首条消息常是手势触发）。
- * 仅影响预览命名，不改动存储内容。
- */
+/** 从首条 user 消息提取会话预览。 */
 function firstUserPreview(messages: any[]): string {
   const firstUserMsg = messages.find((m) => m.role === "user");
   if (!firstUserMsg) return "(empty)";
@@ -189,10 +184,8 @@ function firstUserPreview(messages: any[]): string {
             .map((c: any) => c.text)
             .join(" ")
         : "";
-  // 剥离开头的注入块：`（…）\n\n<用户真实输入>`
-  const cleaned = content.replace(/^（[^）]*）[ \t]*\n*/u, "");
-  let preview = cleaned.slice(0, 50).replace(/\n/g, " ");
-  if (cleaned.length > 50) preview += "...";
+  let preview = content.slice(0, 50).replace(/\n/g, " ");
+  if (content.length > 50) preview += "...";
   return preview;
 }
 

package/src/renderer.ts

@@ -161,6 +161,17 @@ export function createRenderer(
     setSpeakerLabel(label: string | undefined) {
       speakerLabel = label;
     },
+    // 切 session（setActiveAgent）时显式复位回合状态：消除跨会话 curMsgText/lastText 残留，
+    // 防止被新 session 的 agent_end 误读上一角色文本。
+    resetTurn() {
+      curMsgText = "";
+      lastText = "";
+      thinkingBuffer = "";
+      drawnThinkingLines = 0;
+      inThinking = false;
+      inText = false;
+      textPrefixWritten = false;
+    },
     subscribe: (session: any) => {
       return session.subscribe((event: any) => {
         switch (event.type) {

package/src/repl.ts

@@ -12,7 +12,7 @@ import * as voice from "./voice.ts";
 import { TtsStream } from "./tts_stream.ts";
 import { stopComputerUse } from "./tools/computer_use.ts";
 import { disconnectAllMcp } from "./mcp.ts";
-import { pet, stopPet, type PetGestureType } from "./pet.ts";
+import { pet, stopPet } from "./pet.ts";
 import { SlashMenu } from "./slash_menu.ts";
 import { printLogo } from "./logo.ts";
 import { PYTHON_DIR } from "./config.ts";
@@ -25,20 +25,6 @@ import { getMainAgent, getSubAgents, getAgentLabel, type AgentId, type SubAgentI
 // STT 长按阈值：按下录音热键持续 ≥ 该毫秒数并在释放时才触发录音；提前松开视为误触
 const STT_HOLD_MS = 2000;
 
-/** 桌宠手势 → 注入用户消息头部的上下文场景行（双语）。引导 Agent 在回复中自然流露出被摸头/被摇晃的感受。 */
-function petGestureScene(type: PetGestureType): string {
-  if (type === "dizzy") {
-    return t(
-      "（Sensei刚才拖着你到处晃来晃去，你感觉有些头晕。请在回复里自然地体现出这份晕眩感。）",
-      "(Sensei just swung you around, and you feel a bit dizzy. Let that dizziness show naturally in your reply.)",
-    );
-  }
-  return t(
-    "（Sensei刚才摸了摸你的头。请在回复里自然地体现出被摸头的感受。）",
-    "(Sensei just petted your head. Let that show naturally in your reply.)",
-  );
-}
-
 export class Repl {
   private rl: readline.Interface;
   private session: AgentSession;
@@ -630,18 +616,11 @@ export class Repl {
   }
 
   private async processInput(input: string) {
-    // 桌宠手势（摸头/dizzy）注入：若用户摸过头/拖住晃过，把"刚才发生了什么"作为
-    // 上下文行写在用户消息头部，引导 Agent 在回复中自然流露出确实感受到了。
-    // takeGesture 消费即清空 → 只注入最近一次、不重复注入；若用户发的是纯命令消息，
-    // processInput 不会被调用（见 line handler 的 / 分支），手势保留到下一条真实消息。
-    const gesture = pet.takeGesture();
-    let effective = input;
-    if (gesture) {
-      const scene = petGestureScene(gesture);
-      if (scene) effective = `${scene}\n\n${input}`;
-    }
+    // 桌宠手势（摸头/dizzy）不再拼进用户消息：落到主 Agent 发送边界注入（gesture_context.ts），
+    // 不进 state.messages → 子 Agent 复制主 session 历史时看不到、会话命名/存储零污染。
+    // takeGesture 消费即清空由发送边界扩展完成，只注入最近一次。
     // 展开 @文件 / !命令 后走完整回合生命周期
-    await this.runRawTurn(this.parseInput(effective));
+    await this.runRawTurn(this.parseInput(input));
   }
 
   /** 把 renderer 订阅切到指定角色 session，并记录当前发言者。 */
@@ -649,6 +628,8 @@ export class Repl {
     this.activeAgentId = agentId;
     this.activeSession = session;
     this.renderer.setSpeakerLabel(getAgentLabel(agentId));
+    // 显式复位回合状态，杜绝跨 session 残留 curMsgText/lastText 被误读
+    this.renderer.resetTurn();
     this.rendererUnsub?.();
     this.rendererUnsub = this.renderer.subscribe(session);
   }

package/src/tts_stream.ts

@@ -21,13 +21,27 @@ import { splitStreamedText, countTextUnits } from "./text_split.ts";
  *     过程性发言不朗读）——避免被 change_emotion 等工具调用切成多段的句子被拆读
  *   - 整段字数判断：countTextUnits(整段) >= MAX_TURN_LEN 则整段跳过不朗读（长回复静音）
  *   - 围栏代码块（```...```）整块剔除；句内 markdown 成句后剔除
- *   - 句子进入严格串行队列：合成（HTTP+下载）→ 播放 → 下一句
- *   - 音色每句动态取 getVoiceId(currentAgent)，setVoice 仅切换当前角色、无需重启进程
- *   - 覆盖主 + 子 Agent：同一实例通过 setVoice 切角色
+ *   - 句子进入串行播放队列 + 单槽预合成流水线：上一句播放期间预合成下一句（synth_only 写临时
+ *     wav），句间只付一次无 HTTP 的 play 进程启动，消除句间合成停顿；预合成失败回退合成+播放
+ *   - 音色按句入队时固化发音人 {text, agent}，spawn 用该角色 voice_id（不受后续 setVoice 影响）
+ *   - 每句带 TTS_SENTENCE_TIMEOUT_MS 保险丝：卡死的句子被跳过，busy 必然复位，整体不静音
+ *   - 覆盖主 + 子 Agent：同一实例通过 setVoice 切当前角色判断开关，队列句音色已各自绑定
  */
 // 整段字数阈值（countTextUnits 口径）：>= 50 的回复不朗读
 const MAX_SENTENCE_LEN = 50;
 const TTS_FORCE_SPLIT_LEN = 9999; // 仅标点切句、不强切
+// 每句合成+播放的时长保险丝：到点仍未 play_end/close 则主动杀进程、按"正常结束"推进下一句。
+// 防止 busy 被卡死的句子永久钉死整条队列（多 Agent 紧邻回合会把单句故障放大成整体静音）。
+const TTS_SENTENCE_TIMEOUT_MS = 30_000;
+
+/** 队列项：入队即固化发音人，之后任何 setVoice/cancel 都不影响本句音色选择。
+    audioPath：undefined=未尝试预合成；null=预合成失败（回退合成+播放）；string=预合成好的 wav 路径 */
+interface PendingSentence {
+  text: string;
+  agent: AgentId;
+  audioPath?: string | null;
+  prefetchPromise?: Promise<void>;
+}
 
 /** 剔除整段文本中的 ``` 代码围栏（文本已完整，无需跨 delta 状态机）。 */
 function stripCodeBlocks(s: string): string {
@@ -38,10 +52,12 @@ function stripCodeBlocks(s: string): string {
 export class TtsStream {
   private proc: ChildProcessWithoutNullStreams | null = null;
   private pendingCount = 0; // 活跃播放段数（play_start +1 / play_end -1）
-  private queue: string[] = []; // 待合成句子队列
+  private queue: PendingSentence[] = []; // 待合成句子队列（按句绑定发音人）
   private busy = false; // 当前是否有句子在合成/播放
   private shuttingDown = false;
   private _killRequested = false; // 本次是否因 cancel 主动杀进程（区分正常结束与打断）
+  private generation = 0; // 打断纪元：cancel 自增以作废在途 drain，杜绝双 drain 竞态
+  private prefetchProc: ChildProcessWithoutNullStreams | null = null; // 在途预合成进程（cancel 时一并杀）
   private currentAgent: AgentId = getMainAgent();
 
   constructor(
@@ -87,18 +103,22 @@ export class TtsStream {
       return;
     }
     const { sentences, rest } = splitStreamedText(full, TTS_FORCE_SPLIT_LEN);
-    for (const s of sentences) this.emitSentence(s);
+    for (const s of sentences) this.emitSentence(s, this.currentAgent);
     const tail = rest.trim();
-    if (tail) this.emitSentence(tail);
+    if (tail) this.emitSentence(tail, this.currentAgent);
     void this.drain();
   }
 
   /** 打断当前合成与队列（新输入 / Esc / Ctrl+C / STT 触发时调用）。 */
   cancel(): void {
+    // 自增纪元作废任何在途 drain，并复位 busy：即使被杀进程不 close，下一回合也不会被残余 busy 吞掉
+    this.generation++;
+    this.busy = false;
+    if (verbose) console.error("[tts] cancel (generation++ queue cleared busy=0)");
     this.queue = [];
     this.pendingCount = 0;
     this.killProc();
-    if (verbose) console.error("[tts] cancel (queue cleared)");
+    this.killPrefetchProc();
   }
 
   /** 切换角色后清空残余（非流式音色动态取，无需杀进程重拉）。 */
@@ -121,7 +141,7 @@ export class TtsStream {
    * 符号不计（countTextUnits）；字数为 0（纯符号）的句子不朗读。
    * （整段已 < MAX_SENTENCE_LEN，单句必然 < 阈值，此处过滤为纯防御）
    */
-  private emitSentence(sentence: string): void {
+  private emitSentence(sentence: string, agent: AgentId): void {
     const clean = stripMarkdown(sentence).trim();
     if (!clean) return;
     const units = countTextUnits(clean);
@@ -129,49 +149,185 @@ export class TtsStream {
       if (verbose) console.error(`[tts] skip sentence units=${units} "${clean.slice(0, 40)}"`);
       return;
     }
-    if (verbose) console.error(`[tts] queue push units=${units} "${clean.slice(0, 40)}"`);
-    this.queue.push(clean);
+    if (verbose) console.error(`[tts] queue push agent=${agent} units=${units} "${clean.slice(0, 40)}"`);
+    // 入队即固化发音人：之后任何 setVoice/cancel 都不影响本句音色选择
+    this.queue.push({ text: clean, agent });
     void this.drain();
   }
 
-  /** 串行排空队列：合成 + 播放一句再下一句。全部播完且未被打断时触发 onIdle。 */
+  /** 串行排空队列：合成 + 播放一句再下一句；下一句在上一句播放期间预合成（单槽流水线）。
+      全部播完且未被打断时触发 onIdle。 */
   private async drain(): Promise<void> {
     if (this.busy || this.shuttingDown) return;
     if (this.queue.length === 0) return;
+    const gen = this.generation;
     this.busy = true;
     let aborted = false;
     try {
       while (this.queue.length > 0 && !this.shuttingDown) {
-        const sentence = this.queue.shift()!;
-        if (verbose) console.error(`[tts] speakOne start "${sentence.slice(0, 40)}"`);
-        const ok = await this.speakOne(sentence);
-        if (verbose) console.error(`[tts] speakOne end ok=${ok} remaining=${this.queue.length}`);
+        if (this.generation !== gen) return; // 已被 cancel 作废，停止处理
+        const item = this.queue.shift()!;
+        // 单槽预合成：当前句播放期间预合成下一句（queue[0]），消除句间 HTTP 合成停顿
+        const next = this.queue[0];
+        if (next && next.audioPath === undefined && !next.prefetchPromise) {
+          next.prefetchPromise = this.prefetch(next).finally(() => {
+            next.prefetchPromise = undefined;
+          });
+        }
+        // 短句兜底：上一句太短时预合成可能未完成，等其收尾（已从"从头合成"缩短为"等尾巴"）
+        if (item.prefetchPromise) {
+          if (verbose) console.error(`[tts] await prefetch "${item.text.slice(0, 40)}"`);
+          await item.prefetchPromise;
+          if (this.generation !== gen) return; // 等待期间被 cancel 作废
+        }
+        if (verbose) console.error(`[tts] speakOne start agent=${item.agent} "${item.text.slice(0, 40)}"`);
+        const ok = await this.speakOne(item);
+        if (verbose) console.error(`[tts] speakOne end agent=${item.agent} ok=${ok} remaining=${this.queue.length}`);
         if (!ok) {
           aborted = true;
           break;
         }
       }
     } finally {
-      this.busy = false;
+      // 仅最年轻的 drain 复位 busy；被 cancel 作废的旧 drain 不再动它，避免清掉新一轮 drain 的 busy
+      if (this.generation === gen && this.busy) this.busy = false;
     }
-    if (!aborted && !this.shuttingDown && this.pendingCount === 0) {
+    if (this.generation === gen && !aborted && !this.shuttingDown && this.pendingCount === 0) {
       this.onIdle?.();
     }
   }
 
+  /**
+   * 预合成下一句：spawn 一次性 synth_only 进程，把 wav 写到临时文件，供播放时直接读（无 HTTP）。
+   * 成功（synth_done）→ item.audioPath = 路径（仅当 generation 未变）；失败/超时/被杀 → null（回退合成+播放）。
+   * 在上一句播放期间调用，消除句间 HTTP 合成停顿。带 TTS_SENTENCE_TIMEOUT_MS 保险丝。
+   */
+  private prefetch(item: PendingSentence): Promise<void> {
+    return new Promise((resolve) => {
+      if (verbose) console.error(`[tts] prefetch start agent=${item.agent} "${item.text.slice(0, 40)}"`);
+      let settled = false;
+      let timer: NodeJS.Timeout | undefined;
+      const gen = this.generation;
+      const doResolve = () => {
+        if (settled) return;
+        if (timer) clearTimeout(timer);
+        settled = true;
+        resolve();
+      };
+      const voiceId = getVoiceId(item.agent);
+      let stdoutBuffer = "";
+      const proc = spawnCompat(config.pythonPath, ["-u", join(PYTHON_DIR, "tts_say.py")], {
+        env: stripProxyEnv({
+          ...process.env,
+          PYTHONUTF8: "1",
+          QWEN_WORKSPACE_ID: config.workspaceId,
+          QWEN_TTS_API_KEY: config.ttsApiKey,
+          QWEN_TTS_MODEL: config.ttsModel,
+          QWEN_TTS_VOICE: voiceId,
+        }),
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      this.prefetchProc = proc;
+
+      // 保险丝：预合成最多等 TTS_SENTENCE_TIMEOUT_MS，超时杀进程 + null 回退（busy 必然复位、整体不静音）
+      timer = setTimeout(() => {
+        if (settled) return;
+        if (verbose) console.error(`[tts] prefetch TIMEOUT (${TTS_SENTENCE_TIMEOUT_MS}ms) agent=${item.agent} "${item.text.slice(0, 40)}"`);
+        if (this.prefetchProc === proc) this.prefetchProc = null;
+        if (!proc.killed) {
+          try {
+            proc.kill("SIGTERM");
+          } catch {
+            // 忽略
+          }
+        }
+        if (this.generation === gen) item.audioPath = null;
+        doResolve();
+      }, TTS_SENTENCE_TIMEOUT_MS);
+
+      proc.stdout.on("data", (data) => {
+        stdoutBuffer += data.toString();
+        const lines = stdoutBuffer.split("\n");
+        stdoutBuffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          let evt: { event?: string; message?: string; path?: string };
+          try {
+            evt = JSON.parse(trimmed);
+          } catch {
+            continue;
+          }
+          if (evt.event === "synth_done" && evt.path) {
+            if (verbose) console.error(`[tts] prefetch synth_done agent=${item.agent} "${item.text.slice(0, 40)}"`);
+            if (this.generation === gen) item.audioPath = evt.path;
+            doResolve();
+          } else if (evt.event === "error") {
+            console.warn(t(`TTS: ${evt.message ?? "unknown error"}`, `TTS: ${evt.message ?? "unknown error"}`));
+            if (verbose) console.error(`[tts] prefetch error: ${evt.message}`);
+            if (this.generation === gen) item.audioPath = null;
+            doResolve();
+          }
+        }
+      });
+
+      proc.stderr.on("data", (data) => {
+        if (!verbose) return;
+        const msg = data.toString().trim();
+        if (msg) console.error(`[python:tts_say]`, msg);
+      });
+
+      proc.on("close", () => {
+        if (this.prefetchProc === proc) this.prefetchProc = null;
+        if (!settled) {
+          // 进程退出但没等到 synth_done（被杀 / 异常）：按失败回退
+          if (this.generation === gen) item.audioPath = null;
+          doResolve();
+        }
+      });
+      proc.on("error", () => {
+        if (this.prefetchProc === proc) this.prefetchProc = null;
+        if (!settled) {
+          if (this.generation === gen) item.audioPath = null;
+          doResolve();
+        }
+      });
+
+      try {
+        proc.stdin.write(JSON.stringify({ mode: "synth_only", text: item.text, voice: voiceId }) + "\n");
+        proc.stdin.end();
+      } catch {
+        // 忽略
+      }
+    });
+  }
+
   /**
    * 合成并播放一句话：spawn 一次性 python 进程，等待其播完（play_end）或退出。
-   * @returns true = 正常结束（含合成失败，继续下一句）；false = 被 cancel 打断
+   * 已预合成（item.audioPath 为 string）走 play 模式（无 HTTP，直接播临时 wav）；
+   * 未预合成（含预合成失败回退）走默认合成+播放模式。
+   * 音色按句固定：环境变量与 stdin 都用该句所属角色的 voice_id，不受后续 setVoice 影响。
+   * 带 TTS_SENTENCE_TIMEOUT_MS 保险丝：到点仍未 play_end/close → 杀进程 + 按正常结束继续下一句，
+   * 保证 drain 必然推进、busy 必然复位，杜绝"卡死一句 → 整条 TTS 永久静音"。
+   * @returns true = 正常结束（含合成失败/超时，继续下一句）；false = 被 cancel 打断
    */
-  private speakOne(text: string): Promise<boolean> {
+  private speakOne(item: PendingSentence): Promise<boolean> {
     return new Promise((resolve) => {
       this._killRequested = false;
       let settled = false;
+      let timer: NodeJS.Timeout | undefined; // 时长保险丝句柄（TDZ 安全：先声明，后赋值）
       const doResolve = (val: boolean) => {
         if (settled) return;
+        if (timer) clearTimeout(timer);
         settled = true;
         resolve(val);
       };
+      const { text, agent } = item;
+      const voiceId = getVoiceId(agent);
+      const payload =
+        typeof item.audioPath === "string"
+          ? { mode: "play", path: item.audioPath }
+          : { text, voice: voiceId };
       let stdoutBuffer = "";
       const proc = spawnCompat(config.pythonPath, ["-u", join(PYTHON_DIR, "tts_say.py")], {
         env: stripProxyEnv({
@@ -180,12 +336,20 @@ export class TtsStream {
           QWEN_WORKSPACE_ID: config.workspaceId,
           QWEN_TTS_API_KEY: config.ttsApiKey,
           QWEN_TTS_MODEL: config.ttsModel,
-          QWEN_TTS_VOICE: getVoiceId(this.currentAgent),
+          QWEN_TTS_VOICE: voiceId,
         }),
         stdio: ["pipe", "pipe", "pipe"],
       });
       this.proc = proc;
 
+      // 时长保险丝：一句合成+播放最多等 TTS_SENTENCE_TIMEOUT_MS，超时主动杀进程并推进一步
+      timer = setTimeout(() => {
+        if (settled) return;
+        if (verbose) console.error(`[tts] speakOne TIMEOUT (${TTS_SENTENCE_TIMEOUT_MS}ms) agent=${agent} "${text.slice(0, 40)}"`);
+        if (this.proc === proc) this.killProc();
+        doResolve(true);
+      }, TTS_SENTENCE_TIMEOUT_MS);
+
       proc.stdout.on("data", (data) => {
         stdoutBuffer += data.toString();
         const lines = stdoutBuffer.split("\n");
@@ -237,7 +401,7 @@ export class TtsStream {
       });
 
       try {
-        proc.stdin.write(JSON.stringify({ text, voice: getVoiceId(this.currentAgent) }) + "\n");
+        proc.stdin.write(JSON.stringify(payload) + "\n");
         proc.stdin.end();
       } catch {
         // 忽略
@@ -245,6 +409,18 @@ export class TtsStream {
     });
   }
 
+  private killPrefetchProc(): void {
+    const proc = this.prefetchProc;
+    this.prefetchProc = null;
+    if (proc && !proc.killed) {
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        // 忽略
+      }
+    }
+  }
+
   private killProc(): void {
     this._killRequested = true;
     const proc = this.proc;