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

app/webrtc/frame_source.py

@@ -9,6 +9,7 @@ TARGET_HEIGHT = 720
 
 
 def validate_frame_size(image: np.ndarray, width: int = TARGET_WIDTH, height: int = TARGET_HEIGHT) -> None:
+    """验证视频帧尺寸是否与目标尺寸一致，不一致时记录警告"""
     h, w = image.shape[:2]
     if w != width or h != height:
         logger.warning("Unexpected frame size: {}x{}", w, h)

app/webrtc/peer_session.py

@@ -10,13 +10,15 @@ from loguru import logger
 from app.signaling.ice_parser import parse_ice
 from app.webrtc.video_receiver import VideoReceiver
 
-
 class PeerSession:
+    """WebRTC对等连接会话管理"""
+
     def __init__(self) -> None:
         self._pc = RTCPeerConnection()
         self._video_task: asyncio.Task | None = None
 
     async def handle(self, websocket) -> None:
+        """处理WebSocket信令交互与WebRTC连接建立"""
         self._setup_events()
 
         try:
@@ -47,6 +49,7 @@ class PeerSession:
             await self._cleanup()
 
     def _setup_events(self) -> None:
+        """注册ICE连接状态变化和视频轨道接收事件处理器"""
         @self._pc.on("track")
         async def on_track(track):
             logger.info(f"Track received: kind={track.kind}")
@@ -61,6 +64,7 @@ class PeerSession:
                 await self._pc.close()
 
     async def _cleanup(self) -> None:
+        """清理视频任务并关闭对等连接"""
         if self._video_task:
             self._video_task.cancel()
             try:

app/webrtc/video_receiver.py

@@ -13,6 +13,7 @@ from configs.load import config
 
 
 def _format_pose_debug(pose_result) -> str:
+    """格式化姿态检测结果用于调试日志输出"""
     metrics = pose_result.metrics
     if metrics is None:
         return "metrics=None"
@@ -24,12 +25,14 @@ def _format_pose_debug(pose_result) -> str:
         f"ll={metrics.left_leg_extended}, rl={metrics.right_leg_extended})"
     )
 
-
 class VideoReceiver:
+    """视频轨道接收与运动检测流水线"""
+
     def __init__(self, track) -> None:
         self._track = track
 
     async def run(self) -> None:
+        """持续接收视频帧并进行姿态检测、渲染和语音播报"""
         logger.info("Start receiving video frames, process_every_n={}", config.video.process_every_n_frames)
 
         frame_count = 0