为所有函数和类添加中文注释文档字符串

app/audio/rep_announcer.py

@@ -8,9 +8,11 @@ from typing import Any
 
 from loguru import logger
 
-
 class RepAnnouncer:
+    """运动次数语音播报器"""
+
     def __init__(self, *, enabled: bool = True, rate: int = 185, volume: float = 1.0) -> None:
+        """初始化TTS引擎（macOS用say，其他系统用pyttsx3）"""
         self.enabled = enabled
         self.rate = rate
         self.volume = volume
@@ -24,6 +26,7 @@ class RepAnnouncer:
             self._start()
 
     def announce_count(self, count: int) -> None:
+        """将次数放入队列进行异步语音播报"""
         if not self.enabled or count <= 0:
             return
         while True:
@@ -34,6 +37,7 @@ class RepAnnouncer:
         self._queue.put(str(count))
 
     def close(self) -> None:
+        """停止播报线程并释放资源"""
         if not self.enabled:
             return
         self._queue.put(None)
@@ -43,6 +47,7 @@ class RepAnnouncer:
             self._current_process.terminate()
 
     def _start(self) -> None:
+        """根据平台初始化TTS引擎并启动后台播报线程"""
         if sys.platform == "darwin":
             self._use_macos_say = True
             logger.info("Rep announcer initialized with macOS say")
@@ -63,6 +68,7 @@ class RepAnnouncer:
         self._thread.start()
 
     def _run(self) -> None:
+        """后台线程：从队列读取文本并调用TTS播放"""
         while True:
             text = self._queue.get()
             if text is None: