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

configs/load.py

@@ -29,6 +29,7 @@ _SECTION_CLASS = {
 
 
 def _dict_to_dataclass(cls: type, data: dict[str, Any] | None) -> dict[str, Any]:
+    """将字典过滤为仅包含指定dataclass字段的键值对"""
     if data is None:
         return {}
     field_names = {f.name for f in dataclasses.fields(cls)}
@@ -36,6 +37,7 @@ def _dict_to_dataclass(cls: type, data: dict[str, Any] | None) -> dict[str, Any]
 
 
 def _read_yaml(path: Path) -> dict[str, Any]:
+    """读取YAML配置文件并返回字典"""
     if not path.exists():
         return {}
     with open(path, encoding="utf-8") as f:
@@ -43,6 +45,7 @@ def _read_yaml(path: Path) -> dict[str, Any]:
 
 
 def load_config(config_path: str | Path | None = None) -> AppConfig:
+    """加载并解析应用配置，返回AppConfig实例"""
     if config_path is None:
         config_path = _PROJECT_ROOT / "config.yaml"
 

configs/models.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 @dataclass
 class ServerConfig:
+    """WebSocket服务器配置"""
     host: str = "0.0.0.0"
     port: int = 8765
     max_ws_size: int = 10_485_760
@@ -13,16 +14,19 @@ class ServerConfig:
 
 @dataclass
 class VideoConfig:
+    """视频帧处理配置"""
     process_every_n_frames: int = 1
 
 
 @dataclass
 class ModelConfig:
+    """姿态检测模型配置"""
     path: str = ""
     prefer_gpu: bool = True
 
     @property
     def resolved_path(self) -> str:
+        """返回模型文件的绝对路径"""
         if self.path:
             return self.path
         return str(Path(__file__).resolve().parent.parent / "pose_models" / "pose_landmarker_full.task")
@@ -30,6 +34,7 @@ class ModelConfig:
 
 @dataclass
 class DeadBugConfig:
+    """死虫式（Dead Bug）运动检测配置"""
     visibility_threshold: float = 0.45
     extension_confirm_frames: int = 4
     reset_confirm_frames: int = 3
@@ -37,6 +42,7 @@ class DeadBugConfig:
 
 @dataclass
 class AudioConfig:
+    """语音播报配置"""
     rep_announcer_enabled: bool = True
     rep_announcer_rate: int = 185
     rep_announcer_volume: float = 1.0
@@ -44,17 +50,20 @@ class AudioConfig:
 
 @dataclass
 class LoggingConfig:
+    """日志配置"""
     dir: str = "logs"
     rotation: str = "20 MB"
     retention: str = "14 days"
 
     @property
     def dir_path(self) -> Path:
+        """返回日志目录的绝对路径"""
         return Path(__file__).resolve().parent.parent / self.dir
 
 
 @dataclass
 class AppConfig:
+    """应用总配置，聚合所有子配置"""
     server: ServerConfig = field(default_factory=ServerConfig)
     video: VideoConfig = field(default_factory=VideoConfig)
     model: ModelConfig = field(default_factory=ModelConfig)