@openav/cli 0.0.0-stage → 1.0.41

package/bin/dscode.exe

@@ -0,0 +1,12 @@
+#!/bin/sh
+echo "Error: dscode native binary not installed." >&2
+echo "" >&2
+echo "Either postinstall did not run (--ignore-scripts, some pnpm configs)" >&2
+echo "or the platform-native optional dependency was not downloaded" >&2
+echo "(--omit=optional)." >&2
+echo "" >&2
+echo "Run the postinstall manually (adjust path for local vs global install):" >&2
+echo "  node node_modules/@deepseekcode/cli/install.cjs" >&2
+echo "" >&2
+echo "Or reinstall without --ignore-scripts / --omit=optional." >&2
+exit 1

package/bin/stt/requirements.txt

@@ -0,0 +1,20 @@
+# DeepSeekCode 语音转文字（STT）依赖 — faster-whisper（唯一引擎）
+#
+# 安装（任选其一）：
+#   pip install -r packages/stt/requirements.txt
+#   或：pip install faster-whisper
+#
+# 说明：
+#   - 不需要 torch / funasr / modelscope：识别引擎只有 faster-whisper
+#     （ctranslate2 后端，CPU int8 即可用），中文与英语走同一套依赖，
+#     区别只在模型档位（en → base.en，其余 → 多语言 base）。
+#   - Python 3.10+（stt_server.py 用了 PEP 604 的 `X | None` 注解），推荐 3.10~3.12。
+
+# 音频容器解码：PyAV —— OGG/Opus、MP3、M4A 等平台原生格式
+# 给 stt_server.decode_with_av 用；WAV / 裸 f32 走标准库，不需要它。
+# **不需要系统 ffmpeg**：PyAV 的 wheel 自带 FFmpeg 库（av.library_versions 可验），
+# 这正是选 PyAV 而不是 subprocess 调 ffmpeg 的全部理由。
+av>=11
+
+# 识别引擎：faster-whisper（whisper.cpp 的 Python 绑定，CPU 上快且省内存）
+faster-whisper>=1.0.0

package/bin/stt/stt_server.py

@@ -0,0 +1,544 @@
+#!/usr/bin/env python3
+"""DeepSeekCode 本地语音转文字（STT）服务。
+
+参考 OpenWorker 的 stt/ 侧车设计（Rust + whisper.cpp），改为 Python 实现。
+**唯一的识别引擎是 faster-whisper**，按语言选两个模型档位：
+
+  - 英语（en）→ faster-whisper 英语专用模型（base.en，CPU 上快且省内存）
+  - 其他语言（zh/ja/ko/fr/de/es/ru/pt/it…）→ faster-whisper 多语言模型
+    （默认 base，可用 DSC_STT_WHISPER_MULTI_MODEL 调整，如 small）
+
+多语言档的语言码「未命中」时改由模型自动识别（详见 transcribe_whisper 的说明）：
+语言码不在多语言模型的语言表里、或带提示这一趟识别结果为空，都会退回 language=None
+让 whisper 自己判定，避免「选错语言 → 静默出垃圾/空结果」。
+
+WAV / 裸 f32 用标准库自己解（http.server / json / base64 / wave / struct），
+其余平台原生容器（OGG/Opus、MP3、M4A…）交给 **PyAV**（`av`，按需 import）。
+选 PyAV 而不是调 `ffmpeg` 可执行文件：PyAV 的 wheel 里自带 FFmpeg 库，
+所以「本机有没有 ffmpeg」不再是这条链路的先决条件（Windows 上尤其关键）。
+后端包同样按需懒加载：`/status` 不触发任何模型下载；`/transcribe` 首次调用时会
+自动下载模型（faster-whisper 走 HuggingFace），耗时取决于网络。
+
+接口（仅监听 127.0.0.1）：
+  GET  /health      → {"status": "ok"}
+  POST /transcribe  → {"language": "<ISO-639-1 小写两位码>",
+                       "format": "wav"|"f32"|"auto"|"ogg"|"mp3"|…,
+                       "audio": "<base64>"} → {"text": "..."}
+
+`format` 语义：
+  - "wav"/"f32"    —— 老两条路，向后兼容（浏览器录音直传）；
+  - "auto"         —— 按魔数嗅探：RIFF/WAVE 走内置解析器，其余交通用解码器。
+                      频道入站（IM 语音）用这个，调用方不必认容器；
+  - 具体容器名      —— 已知容器（见 `_AV_FORMATS`）直接走通用解码器。
+
+
+环境变量：
+  DSC_STT_PORT           监听端口（默认 0 = 系统分配；父进程通常指定 --port）
+  DSC_STT_WHISPER_MODEL  faster-whisper 英语模型名（默认 base.en）
+  DSC_STT_WHISPER_MULTI_MODEL  faster-whisper 多语言模型名（默认 base）
+  DSC_STT_DEVICE         auto|cuda|cpu（默认 auto）
+
+模型下载源（由 Node 侧按 config.yaml settings.stt.* 注入；本文件不读它们，
+而是 huggingface_hub 在 **import 期**自行读取 —— 因此改端点
+必须重启本进程才生效，Node 侧 restartService() 负责这件事）：
+  HF_ENDPOINT            HuggingFace 端点（默认 https://huggingface.co，国内可设
+                         https://hf-mirror.com）—— faster-whisper 的模型权重走这里
+"""
+
+import base64
+import importlib
+import io
+import json
+import os
+import struct
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+DEFAULT_MODELS_DIR = str(Path.home() / ".agent" / "stt-models")
+TARGET_RATE = 16_000  # whisper 要求 16k 采样率
+
+_backends_lock = threading.Lock()
+_loaded = {"en": None, "multi": None}  # 缓存已加载的模型对象
+
+
+def log(msg: str) -> None:
+    print(f"[stt] {msg}", file=sys.stderr, flush=True)
+
+
+# ─────────────────────────── 音频解码 ───────────────────────────
+
+
+def _resample_mono(input_samples: list[float], source_rate: int) -> list[float]:
+    """线性插值重采样到 16k（与 OpenWorker stt 的 Rust 实现同思路）。"""
+    if source_rate == TARGET_RATE:
+        return list(input_samples)
+    output_len = int(len(input_samples) * TARGET_RATE / source_rate)
+    ratio = source_rate / TARGET_RATE
+    out = []
+    for i in range(output_len):
+        pos = i * ratio
+        left = int(pos)
+        right = min(left + 1, len(input_samples) - 1)
+        frac = pos - left
+        out.append(input_samples[left] * (1.0 - frac) + input_samples[right] * frac)
+    return out
+
+
+def decode_wav(data: bytes) -> tuple[list[float], int]:
+    """解析 WAV（RIFF）→ 单声道 float32 样本 + 采样率。支持 PCM16 / IEEE float32。"""
+    if data[0:4] != b"RIFF" or data[8:12] != b"WAVE":
+        raise ValueError("Not a WAV file (RIFF/WAVE header missing)")
+    pos = 12
+    channels = 1
+    rate = TARGET_RATE
+    bits = 16
+    fmt_code = 1
+    while pos + 8 <= len(data):
+        chunk_id = data[pos:pos + 4]
+        chunk_size = struct.unpack("<I", data[pos + 4:pos + 8])[0]
+        if chunk_id == b"fmt ":
+            fmt_code, channels, rate = struct.unpack("<HHI", data[pos + 8:pos + 16])
+            bits = struct.unpack("<H", data[pos + 22:pos + 24])[0] if pos + 24 <= len(data) else 16
+        elif chunk_id == b"data":
+            audio = data[pos + 8:pos + 8 + chunk_size]
+            samples: list[float] = []
+            if fmt_code == 3 and bits == 32:  # IEEE float32
+                n = len(audio) // 4
+                for i in range(0, n * 4, 4):
+                    samples.append(struct.unpack("<f", audio[i:i + 4])[0])
+            elif bits == 16:  # PCM16
+                n = len(audio) // 2
+                for i in range(0, n * 2, 2):
+                    samples.append(struct.unpack("<h", audio[i:i + 2])[0] / 32768.0)
+            elif bits == 8:  # PCM8 unsigned
+                samples = [(b - 128) / 128.0 for b in audio]
+            else:
+                raise ValueError(f"Unsupported WAV bit depth: {bits}")
+            if channels > 1:
+                mono = []
+                for i in range(0, len(samples) - channels + 1, channels):
+                    mono.append(sum(samples[i:i + channels]) / channels)
+                samples = mono
+            return samples, rate
+        pos += 8 + chunk_size + (chunk_size % 2)
+    raise ValueError("WAV data chunk not found")
+
+
+# ────────────────────── 通用解码（平台容器：OGG/Opus、MP3…） ──────────────────────
+
+# 能直接交给通用解码器的容器名（`format` 字段的取值）。键即调用方可传的字符串。
+_AV_FORMATS = frozenset({
+    "ogg", "opus", "oga", "mp3", "m4a", "mp4", "aac", "webm", "flac", "wma", "amr", "silk",
+})
+
+
+def _sniff_needs_av(raw: bytes) -> bool:
+    """魔数嗅探：只有明确的 WAV / 裸 f32 才走内置解析器，其余一律交给 PyAV。
+
+    刻意**默认偏严**（白名单而非黑名单）：认不出的字节流宁可交给 PyAV 报错，
+    也不要拿内置 WAV 解析器去猜 —— 后者对非 RIFF 输入只会抛一句难懂的
+    "WAV data chunk not found"，掩盖真正的「容器不受支持」。
+    """
+    if len(raw) < 12:
+        return False  # 交给 decode_wav 报它自己的错
+    return raw[0:4] != b"RIFF" or raw[8:12] != b"WAVE"
+
+
+def decode_with_av(raw: bytes) -> tuple[list[float], int]:
+    """用 PyAV 解任意容器 → 单声道 float32 + 采样率。
+
+    PyAV 的 wheel 自带 FFmpeg 库，所以不需要系统 `ffmpeg`（这是选它而不是
+    subprocess 调 ffmpeg 的全部理由）。解码到 16k **单声道**由 av 的
+    AudioResampler 完成，避免自己再写一遍重采样。
+    """
+    try:
+        import av  # 懒加载：没装 av 时只有这条路径失败，wav/f32 老路径不受影响
+    except ImportError as exc:  # pragma: no cover - 依赖缺失路径
+        raise ValueError(
+            "Audio container decoding requires PyAV. "
+            "Install it into the STT venv: pip install av"
+        ) from exc
+
+    try:
+        with av.open(io.BytesIO(raw), mode="r") as container:
+            stream = next((s for s in container.streams if s.type == "audio"), None)
+            if stream is None:
+                raise ValueError("No audio stream found in payload")
+
+            resampler = av.AudioResampler(format="s16", layout="mono", rate=TARGET_RATE)
+            chunks: list[bytes] = []
+            for frame in container.decode(stream):
+                # resample() 可能返回 0..N 个帧（含缓冲中的尾巴）
+                for out in resampler.resample(frame):
+                    chunks.append(out.to_ndarray().tobytes())
+            # flush：重采样器内部可能还压着尾巴，不冲会静默丢最后几十毫秒
+            for out in resampler.resample(None):
+                chunks.append(out.to_ndarray().tobytes())
+    except ValueError:
+        raise
+    except Exception as exc:
+        raise ValueError(f"Could not decode audio container: {exc}") from exc
+
+    if not chunks:
+        raise ValueError("Decoded audio is empty (no samples produced)")
+    return _pcm16_to_f32(b"".join(chunks)), TARGET_RATE
+
+
+def _pcm16_to_f32(pcm: bytes) -> list[float]:
+    """PCM16 little-endian → [-1, 1) float32 列表。用 array 而非逐样本 struct，快一个量级。"""
+    import array
+
+    arr = array.array("h")
+    arr.frombytes(pcm[: len(pcm) - (len(pcm) % 2)])
+    return [v / 32768.0 for v in arr]
+
+
+def decode_audio(body: dict) -> tuple[list[float], int]:
+    """按 format 解码请求里的音频 → 单声道 float32 + 采样率。"""
+    raw = base64.b64decode(body.get("audio") or "", validate=False)
+    fmt = (body.get("format") or "wav").lower()
+    if fmt == "f32":
+        n = len(raw) // 4
+        samples = [struct.unpack("<f", raw[i:i + 4])[0] for i in range(0, n * 4)]
+        return samples, TARGET_RATE
+    if fmt == "wav":
+        return decode_wav(raw)
+    if fmt == "auto":
+        # 调用方（IM 适配器）拿到什么就传什么，由这里决定用哪个解码器
+        return decode_wav(raw) if not _sniff_needs_av(raw) else decode_with_av(raw)
+    if fmt in _AV_FORMATS:
+        return decode_with_av(raw)
+    raise ValueError(
+        f"Unsupported audio format: {fmt} "
+        f"(supported: wav, f32, auto, {', '.join(sorted(_AV_FORMATS))})"
+    )
+
+
+# ─────────────────────────── 后端：whisper（英语 + 多语言） ───────────────────────────
+
+# whisper 两种模型档位：en=英语专用（更快更准），multi=多语言（覆盖其余语言）
+_WHISPER_MODEL_ENV = {"en": "DSC_STT_WHISPER_MODEL", "multi": "DSC_STT_WHISPER_MULTI_MODEL"}
+_WHISPER_MODEL_DEFAULT = {"en": "base.en", "multi": "base"}
+
+# 多语言模型语言表的探测结果缓存：set = 已知语言码集合；空 set = 探测过但取不到，
+# 调用方据此跳过预检（不做「未知即未命中」的误判）。
+_MULTI_LANGUAGE_CODES: set[str] = set()
+_MULTI_LANGUAGE_CODES_PROBED = False
+
+# 「带语言提示这一趟白跑了」的判定阈值（秒）：VAD 之后剩下的语音短于它，
+# 空结果更可能是静音而不是语言选错，此时不重试、不浪费第二次推理。
+_EMPTY_RETRY_MIN_VAD_SEC = 1.0
+
+
+def _multi_language_codes() -> set[str] | None:
+    """多语言模型支持的语言码集合；取不到返回 None（= 未知，调用方跳过预检）。
+
+    取自 faster-whisper 自带的语言表（模块/属性名随版本有差异，逐一尝试）；
+    取不到时宁可放弃预检交给模型自身判定，也不要因版本差异把正常语言误判成未命中。
+    """
+    global _MULTI_LANGUAGE_CODES, _MULTI_LANGUAGE_CODES_PROBED
+    if _MULTI_LANGUAGE_CODES_PROBED:
+        return _MULTI_LANGUAGE_CODES or None
+    table = None
+    for module_name, attr in (("faster_whisper.tokenizer", "_LANGUAGES"), ("whisper.tokenizer", "LANGUAGES")):
+        try:
+            module = importlib.import_module(module_name)
+        except Exception:  # noqa: BLE001 — 探测失败即放弃预检
+            continue
+        candidate = getattr(module, attr, None)
+        if isinstance(candidate, dict) and candidate:
+            table = candidate
+            break
+    _MULTI_LANGUAGE_CODES_PROBED = True
+    _MULTI_LANGUAGE_CODES = {str(code).lower() for code in table} if table else set()
+    if not _MULTI_LANGUAGE_CODES:
+        log("multilingual language table unavailable — the model decides the language itself")
+    return _MULTI_LANGUAGE_CODES or None
+
+
+def _whisper_loaded(kind: str) -> object | None:
+    with _backends_lock:
+        return _loaded[kind]
+
+
+def _whisper_load(kind: str) -> object:
+    with _backends_lock:
+        if _loaded[kind] is not None:
+            return _loaded[kind]
+        try:
+            from faster_whisper import WhisperModel  # noqa: PLC0415
+        except ImportError as exc:
+            raise RuntimeError(
+                "Whisper STT backend (faster-whisper) is not installed. Run:\n"
+                "  pip install faster-whisper\n"
+                "The DeepSeekCode server needs it for voice input."
+            ) from exc
+        model_name = os.environ.get(_WHISPER_MODEL_ENV[kind], _WHISPER_MODEL_DEFAULT[kind])
+        device = detect_device()
+        compute = "float16" if device == "cuda" else "int8"
+        log(f"loading faster-whisper[{kind}] model '{model_name}' (device={device}, compute={compute})…")
+        model = WhisperModel(model_name, device=device, compute_type=compute)
+        _loaded[kind] = model
+        log(f"faster-whisper[{kind}] model ready")
+        return model
+
+
+def transcribe_whisper(samples_f32: list[float], language: str, kind: str) -> tuple[str, str | None]:
+    """whisper 转写。kind 决定用英语专用还是多语言模型；language 为 ISO-639-1 码。
+
+    返回 `(文本, 自动识别出的语言码)`：第二个元素仅在「语言提示未命中、改由模型自动
+    识别」时非空，供调用方回报实际使用的语言。
+
+    语言提示策略：默认把 language 交给模型（跳过自动识别 —— 短音频的自动语言判定
+    很不可靠）。**只有多语言档**会在「未命中」时退回 language=None 自动识别，三种触发：
+
+      1. 语言码不在多语言模型的语言表里 —— 硬传下去 faster-whisper 会直接抛错，
+         用户拿到 500 而不是结果（Node 侧有白名单，此路径主要保护直接调本服务/
+         未来扩充语言清单的场景）；
+      2. 带提示这一趟识别结果为空，且 VAD 之后确实还剩 ≥1s 语音（选错语言的典型
+         表现就是这种「有声音但没结果」）—— 让模型自己判定一次；
+      3. 模型拒收该语言码（版本差异兜底），重试时改用自动识别。
+
+    ⚠️ 不为「有结果但不对」而重试：whisper 在显式 language 下不给语言概率，
+    拿不到「对不对」的信号，重试只会把耗时翻倍。第二条的「空结果」是唯一可靠的
+    可用信号，且已用 VAD 时长把「纯静音」排除在外（静音不重试）。
+    """
+    model = _whisper_load(kind)
+    import numpy as np  # noqa: PLC0415
+
+    audio = np.asarray(samples_f32, dtype=np.float32)
+
+    def run(hint: str | None):
+        segments, info = model.transcribe(audio, language=hint, beam_size=5, vad_filter=True)
+        # segments 可能是惰性生成器：解码异常会在迭代期抛出，故连消费一起包在调用方
+        text = " ".join(s.text.strip() for s in segments).strip()
+        return text, info
+
+    hint: str | None = language
+    if kind == "multi":
+        codes = _multi_language_codes()
+        if codes is not None and language not in codes:
+            log(f"language {language!r} not in the multilingual model's language table — using auto-detect")
+            hint = None
+    try:
+        text, info = run(hint)
+    except Exception as exc:  # noqa: BLE001 — 语言码把整趟转写打死不值得，退回自动识别
+        if hint is None:
+            raise
+        log(f"model rejected language {hint!r} ({exc}) — retrying with auto-detect")
+        text, info = run(None)
+        hint = None
+
+    if hint is not None and kind == "multi" and not text:
+        vad_sec = getattr(info, "duration_after_vad", None)
+        if vad_sec is None:
+            vad_sec = getattr(info, "duration", 0.0) or 0.0
+        if float(vad_sec) >= _EMPTY_RETRY_MIN_VAD_SEC:
+            log(f"empty result for language {hint!r} ({float(vad_sec):.1f}s after VAD) — retrying with auto-detect")
+            text, info = run(None)
+            hint = None
+
+    if hint is not None:
+        return text, None
+    detected = getattr(info, "language", None)
+    return text, (str(detected) if detected else None)
+
+
+# ─────────────────────────── 设备检测 / 状态 ───────────────────────────
+
+def detect_device() -> str:
+    env = os.environ.get("DSC_STT_DEVICE", "auto").lower()
+    if env in ("cuda", "gpu"):
+        return "cuda"
+    if env == "cpu":
+        return "cpu"
+    # torch 不是本服务的依赖（faster-whisper 走 ctranslate2）；装了就用它探 CUDA，
+    # 没装一律 cpu。想显式用 GPU 请设 DSC_STT_DEVICE=cuda。
+    try:
+        import torch  # noqa: PLC0415
+
+        return "cuda" if torch.cuda.is_available() else "cpu"
+    except ImportError:
+        return "cpu"
+
+
+def _backend_status() -> dict:
+    def probe(name: str) -> dict:
+        loaded = _loaded.get(name) is not None
+        # 捕获所有异常而非仅 ImportError：Windows 上 ctranslate2 DLL 加载失败等
+        # 场景需要把具体原因带给前端，否则"pip 装完了却仍显示未安装"无从排查。
+        error = None
+        try:
+            import faster_whisper  # noqa: PLC0415, F401
+
+            installed = True
+        except Exception as exc:  # noqa: BLE001 — 探测需吞掉一切导入期异常
+            installed = False
+            error = f"{type(exc).__name__}: {exc}"
+        model = os.environ.get(_WHISPER_MODEL_ENV[name], _WHISPER_MODEL_DEFAULT[name])
+        return {
+            "installed": installed,
+            "loaded": loaded,
+            "error": error,
+            "model": model,
+        }
+
+    return {"en": probe("en"), "multi": probe("multi")}
+
+
+# ─────────────────────────── HTTP 服务 ───────────────────────────
+
+class SttHandler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, fmt: str, *args):  # 走自己的 stderr 日志，避免重复刷屏
+        log(f"{self.command} {self.path} — {fmt % args}")
+
+    def _send(self, status: int, payload: dict) -> None:
+        data = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path.split("?")[0] == "/health":
+            return self._send(200, {"status": "ok"})
+        if self.path.split("?")[0] == "/status":
+            return self._send(200, {
+                "service": "ok",
+                "python": sys.version.split()[0],
+                "models_dir": os.environ.get("DSC_STT_MODELS_DIR", DEFAULT_MODELS_DIR),
+                "device": detect_device(),
+                "backends": _backend_status(),
+            })
+        self._send(404, {"error": "Not found"})
+
+    def do_POST(self) -> None:  # noqa: N802
+        if self.path.split("?")[0] != "/transcribe":
+            return self._send(404, {"error": "Not found"})
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+            raw = self.rfile.read(length) if length else b"{}"
+            body = json.loads(raw.decode("utf-8") or "{}")
+        except Exception as exc:  # noqa: BLE001
+            return self._send(400, {"error": f"Bad request body: {exc}"})
+        lang = str(body.get("language") or "en").lower()
+        # 接受任意 ISO-639-1 两位小写码：en→英语专用 whisper，
+        # 其余（含 zh）→多语言 whisper（模型支持约 99 种语言）。非两位字母码才拒绝。
+        if not (len(lang) == 2 and lang.isalpha() and lang.isascii()):
+            return self._send(400, {"error": f"Unsupported language: {lang} (use an ISO-639-1 code like 'en' / 'zh' / 'ja')"})
+        if not body.get("audio"):
+            return self._send(400, {"error": "Missing 'audio' (base64-encoded audio)"})
+
+        try:
+            samples, rate = decode_audio(body)
+            samples = _resample_mono(samples, rate)
+        except Exception as exc:  # noqa: BLE001
+            return self._send(400, {"error": f"Could not decode audio: {exc}"})
+
+        # 少于 0.25 秒视为空白录音（对齐 OpenWorker 行为），直接返回空串
+        if len(samples) < TARGET_RATE // 4:
+            return self._send(200, {"text": "", "language": lang})
+
+        effective_lang = lang
+        try:
+            if lang == "en":
+                text, auto_lang = transcribe_whisper(samples, "en", "en")
+                backend = "faster-whisper"
+                effective_lang = auto_lang or lang
+            else:
+                text, auto_lang = transcribe_whisper(samples, lang, "multi")
+                backend = "faster-whisper-multi"
+                # 未命中 → 自动识别：回报实际使用的语言，便于调用方对齐/排查
+                effective_lang = auto_lang or lang
+        except Exception as exc:  # noqa: BLE001
+            log(f"transcribe failed: {exc}")
+            return self._send(500, {"error": f"Transcription failed: {exc}"})
+
+        if effective_lang != lang:
+            log(f"transcribed {lang} (auto-detected as {effective_lang}): {text[:60]!r}")
+        else:
+            log(f"transcribed {lang}: {text[:60]!r}")
+        return self._send(200, {"text": text, "language": effective_lang, "backend": backend})
+
+
+def _arg_value(name: str) -> str | None:
+    if name in sys.argv:
+        return sys.argv[sys.argv.index(name) + 1]
+    return None
+
+
+def parent_alive(pid: int) -> bool:
+    """父进程是否还在。
+
+    **不要**用 `os.kill(pid, 0)` 探活：Windows 上它并非「发 0 号信号」，CPython 会走
+    `OpenProcess(PROCESS_ALL_ACCESS)` + `TerminateProcess`（文档：除 CTRL_C_EVENT /
+    CTRL_BREAK_EVENT 外的 sig 会「unconditionally killed by the TerminateProcess API」），
+    而且 `PROCESS_ALL_ACCESS` 在子进程带 `CREATE_NO_WINDOW`（Node 侧 `windowsHide: true`，
+    见 `stt.ts:249`）时**会失败并抛 OSError** → 看门狗误判「父进程已死」→ 服务约 5 秒后
+    自杀，表现为第一个请求连接被重置、之后一律 ConnectionRefused。
+    实测见 `.agent/tts-probe/shape_probe.py`（S1 产品 stdio 形态）。
+    `packages/tts/tts_server.py` 有同一份修复，两处改动请保持同步。
+    """
+    if os.name == "nt":
+        import ctypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        # 只申请「查询」权限，不做任何写/终止操作
+        handle = kernel32.OpenProcess(0x1000, False, pid)
+        if not handle:
+            return False
+        try:
+            code = ctypes.c_ulong()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return False
+            return code.value == 259  # STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def main() -> None:
+    models_dir = os.environ.get("DSC_STT_MODELS_DIR", DEFAULT_MODELS_DIR)
+    # 模型缓存集中到 models_dir（与 Node 侧 spawn 时注入的 HF_HOME 一致）
+    os.environ.setdefault("HF_HOME", str(Path(models_dir) / "huggingface"))
+    Path(models_dir).mkdir(parents=True, exist_ok=True)
+
+    port = int(_arg_value("--port") or os.environ.get("DSC_STT_PORT") or "0")
+    raw_parent = _arg_value("--parent-pid")
+    parent_pid = int(raw_parent) if raw_parent and raw_parent.isdigit() else None
+
+    server = ThreadingHTTPServer(("127.0.0.1", port), SttHandler)
+    server.daemon_threads = True
+    log(f"listening on 127.0.0.1:{server.server_address[1]} (models_dir={models_dir})")
+
+    def watchdog() -> None:
+        """父进程（Node server）退出后自动退出，避免残留孤儿进程（Windows 上尤为必要）。"""
+        while True:
+            time.sleep(5)
+            if not parent_alive(parent_pid):
+                log(f"parent pid {parent_pid} gone, exiting")
+                server.shutdown()
+                return
+
+    if parent_pid is not None:
+        threading.Thread(target=watchdog, daemon=True).start()
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

package/bin/tts/requirements.txt

@@ -0,0 +1,21 @@
+# DeepSeekCode 语音合成（TTS）依赖 — Kokoro-82M（ONNX，CPU 可跑）
+#
+# 安装：
+#   pip install -r packages/tts/requirements.txt
+#
+# 说明：
+#   - **不含 torch**：kokoro-onnx 走 onnxruntime，CPU 即可，依赖闭包约 40MB。
+#   - espeakng-loader 会连 espeak-ng 及其数据一起装上，用户**不需要**手动装 espeak-ng
+#     （这原本是 Windows 上最劝退的一步）。
+#   - misaki[zh] 是**中文可懂度的硬依赖**，不是可选优化：Kokoro 的中文音色是用 misaki 的
+#     拼音 IPA（带调号）训练的，而 kokoro-onnx 自带的 espeak `cmn` 路径丢声母、无音调，
+#     中文会听不懂且**不报错**。详见 docs/architecture-design/PERSONAL_REMOTE_AGENT_PLAN.md
+#     gotcha 11。misaki[zh] 只引入 pypinyin / jieba / cn2an / ordered-set / regex，无 torch。
+#   - Python 3.10+（用了 PEP 604 的 `X | None` 注解）。
+#   - 权重（model_uint8f16.onnx + voices-v1.0.bin）不由 pip 安装，由 Node 侧
+#     `packages/server/src/ttsDownload.ts` 下载到 ~/.agent/tts-models。
+
+kokoro-onnx>=0.4.0
+onnxruntime>=1.17.0
+numpy>=1.24.0
+misaki[zh]>=0.9.4