feat(recorder): add offline voice clip pipeline

[变更性质]
- 本提交新增本机离线的语音片段录音能力，不涉及网络服务或语音识别。

[新增功能]
- 通过 Pulse 默认输入持续采集音频，以本地 Silero VAD 触发片段。
- 以私有目录和权限写入 24 kbps Ogg/Opus 录音，并提供 systemd 用户服务安装器。

[实现方案]
- 使用有限前置缓冲、静音封段和最长段滚动状态机，避免静音落盘及内存无限增长。
- 增加真实 Opus 编解码、服务 dry-run 和纯逻辑状态转换测试；记录模型归属和部署前置条件。

[影响范围]
- 新增 Python CLI、运行时模块、中文运维文档和自动测试。
- 未安装、启用或启动任何用户 systemd 服务；不删除或修改录音数据。

1 files changed, 92 insertions, 0 deletions

diff --git a/src/mic_clipper/runner.py b/src/mic_clipper/runner.py
new file mode 100644
index 0000000..787bf58
--- /dev/null
+++ b/src/mic_clipper/runner.py
@@ -0,0 +1,92 @@
+"""Runtime wiring for capture, VAD, segmentation, and durable clips."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable, Iterable
+from datetime import datetime
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+
+from mic_clipper.audio_input import PulseAudioInput
+from mic_clipper.segmenter import Audio, End, Segmenter, Start
+from mic_clipper.storage import ClipWriter, OpenClip
+from mic_clipper.vad import SileroVad
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Vad(Protocol):
+    def probability(self, samples: np.ndarray) -> float: ...
+
+
+class Writer(Protocol):
+    def open(self, started_at: datetime) -> OpenClip: ...
+
+
+def record_frames(
+    frames: Iterable[np.ndarray],
+    *,
+    vad: Vad,
+    writer: Writer,
+    segmenter: Segmenter,
+    now: Callable[[], datetime],
+    threshold: float = 0.5,
+) -> None:
+    """Record one finite or failing frame stream, closing an active encoder on exit."""
+    clip: OpenClip | None = None
+    try:
+        for samples in frames:
+            events = segmenter.push(samples, vad.probability(samples) >= threshold, now())
+            for event in events:
+                if isinstance(event, Start):
+                    clip = writer.open(event.started_at)
+                    try:
+                        clip.write(event.samples)
+                    except BaseException:
+                        clip.abort()
+                        clip = None
+                        raise
+                elif isinstance(event, Audio):
+                    if clip is None:
+                        raise RuntimeError("segment audio arrived without an active encoder")
+                    clip.write(event.samples)
+                elif isinstance(event, End):
+                    if clip is None:
+                        raise RuntimeError("segment end arrived without an active encoder")
+                    clip.close()
+                    clip = None
+    finally:
+        if clip is not None:
+            clip.close()
+
+
+def run_forever(root: Path, *, threshold: float = 0.5) -> None:
+    """Recreate all live components after a transient audio-service failure."""
+    retry_seconds = 1
+    while True:
+        try:
+            record_frames(
+                PulseAudioInput().frames(),
+                vad=SileroVad(),
+                writer=ClipWriter(root),
+                segmenter=Segmenter(pre_roll_seconds=0.5, silence_seconds=1.5),
+                now=lambda: datetime.now().astimezone(),
+                threshold=threshold,
+            )
+            raise RuntimeError("Pulse input ended unexpectedly")
+        except KeyboardInterrupt:
+            LOGGER.info("microphone clip recorder stopped")
+            return
+        except Exception as error:
+            LOGGER.warning(
+                "audio recorder unavailable (%s); retrying in %s seconds",
+                error,
+                retry_seconds,
+            )
+            time.sleep(retry_seconds)
+            retry_seconds = min(retry_seconds * 2, 60)