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

app/exercises/dead_bug/detector.py

@@ -32,8 +32,9 @@ from app.vision.pose_types import (
     RIGHT_WRIST,
 )
 
-
 class DeadBugDetector:
+    """死虫式（Dead Bug）运动检测器"""
+
     def __init__(
         self,
         *,
@@ -43,6 +44,7 @@ class DeadBugDetector:
         reset_confirm_frames: int = 3,
         prefer_gpu: bool = True,
     ) -> None:
+        """初始化姿态检测器、状态机和可视化渲染组件"""
         self.visibility_threshold = visibility_threshold
 
         self._latest_result = None
@@ -72,9 +74,11 @@ class DeadBugDetector:
         self._last_timestamp_ms = -1
 
     def close(self) -> None:
+        """释放MediaPipe模型资源"""
         self._landmarker.close()
 
     def process_frame(self, bgr_frame: np.ndarray, timestamp_ms: int) -> tuple[np.ndarray, DeadBugResult]:
+        """处理单帧：姿态检测、指标计算、状态机更新、可视化叠加"""
         timestamp_ms = self._normalize_timestamp(timestamp_ms)
 
         with self._result_lock:
@@ -166,6 +170,7 @@ class DeadBugDetector:
         return annotated, result
 
     def _normalize_timestamp(self, timestamp_ms: int) -> int:
+        """确保时间戳严格递增（MediaPipe要求）"""
         if timestamp_ms <= self._last_timestamp_ms:
             timestamp_ms = self._last_timestamp_ms + 1
         self._last_timestamp_ms = timestamp_ms