为拆分heartFC_chat后的几个文件 添加亿点注释

src/chat/chat_loop/cycle_tracker.py

@@ -9,9 +9,31 @@ logger = get_logger("hfc.cycle")
 
 class CycleTracker:
     def __init__(self, context: HfcContext):
+        """
+        初始化循环跟踪器
+        
+        Args:
+            context: HFC聊天上下文对象
+            
+        功能说明:
+        - 负责跟踪和记录每次思考循环的详细信息
+        - 管理循环的开始、结束和信息存储
+        """
         self.context = context
 
     def start_cycle(self) -> Tuple[Dict[str, float], str]:
+        """
+        开始新的思考循环
+        
+        Returns:
+            tuple: (循环计时器字典, 思考ID字符串)
+            
+        功能说明:
+        - 增加循环计数器
+        - 创建新的循环详情对象
+        - 生成唯一的思考ID
+        - 初始化循环计时器
+        """
         self.context.cycle_counter += 1
         self.context.current_cycle_detail = CycleDetail(self.context.cycle_counter)
         self.context.current_cycle_detail.thinking_id = f"tid{str(round(time.time(), 2))}"
@@ -19,6 +41,19 @@ class CycleTracker:
         return cycle_timers, self.context.current_cycle_detail.thinking_id
 
     def end_cycle(self, loop_info: Dict[str, Any], cycle_timers: Dict[str, float]):
+        """
+        结束当前思考循环
+        
+        Args:
+            loop_info: 循环信息，包含规划和动作信息
+            cycle_timers: 循环计时器，记录各阶段耗时
+            
+        功能说明:
+        - 设置循环详情的完整信息
+        - 将当前循环加入历史记录
+        - 记录计时器和结束时间
+        - 打印循环统计信息
+        """
         if self.context.current_cycle_detail:
             self.context.current_cycle_detail.set_loop_info(loop_info)
             self.context.history_loop.append(self.context.current_cycle_detail)
@@ -27,6 +62,18 @@ class CycleTracker:
             self.print_cycle_info(cycle_timers)
 
     def print_cycle_info(self, cycle_timers: Dict[str, float]):
+        """
+        打印循环统计信息
+        
+        Args:
+            cycle_timers: 循环计时器字典
+            
+        功能说明:
+        - 格式化各阶段的耗时信息
+        - 计算总体循环持续时间
+        - 输出详细的性能统计日志
+        - 显示选择的动作类型
+        """
         if not self.context.current_cycle_detail:
             return