From a3d0588e7efe37a5ebbd97a56dcfc385853f64b4 Mon Sep 17 00:00:00 2001 From: minecraft1024a Date: Sat, 6 Sep 2025 15:52:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(core):=20=E4=B8=BA=E6=A0=B8=E5=BF=83?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=B7=BB=E5=8A=A0=E6=97=A5=E5=BF=97=E8=AE=B0?= =?UTF-8?q?=E5=BD=95=E5=92=8C=E6=96=87=E6=A1=A3=E5=AD=97=E7=AC=A6=E4=B8=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为 `cycle_processor`, `response_handler`, `generator_api`, 和 `send_api` 等核心代码文件补充了日志记录器和详细的文档字符串（docstrings）。 本次更新旨在提高代码的可读性和可维护性，通过清晰的文档注释和日志输出，使其他开发者能更容易地理解代码逻辑和功能，并为未来的调试和功能扩展提供便利。 --- src/chat/chat_loop/cycle_processor.py | 48 +++++++++++++++++++++++-- src/chat/chat_loop/response_handler.py | 20 +++++++++++ src/plugin_system/apis/generator_api.py | 17 +++++++++ src/plugin_system/apis/send_api.py | 2 ++ 4 files changed, 84 insertions(+), 3 deletions(-) diff --git a/src/chat/chat_loop/cycle_processor.py b/src/chat/chat_loop/cycle_processor.py index 4a39ddd0e..a1862f515 100644 --- a/src/chat/chat_loop/cycle_processor.py +++ b/src/chat/chat_loop/cycle_processor.py @@ -19,10 +19,14 @@ from .hfc_context import HfcContext from .response_handler import ResponseHandler from .cycle_tracker import CycleTracker +# 日志记录器 logger = get_logger("hfc.processor") class CycleProcessor: + """ + 循环处理器类，负责处理单次思考循环的逻辑。 + """ def __init__(self, context: HfcContext, response_handler: ResponseHandler, cycle_tracker: CycleTracker): """ 初始化循环处理器 @@ -51,14 +55,30 @@ class CycleProcessor: thinking_id, actions, ) -> Tuple[Dict[str, Any], str, Dict[str, float]]: + """ + 发送并存储回复信息 + + Args: + response_set: 回复内容集合 + loop_start_time: 循环开始时间 + action_message: 动作消息 + cycle_timers: 循环计时器 + thinking_id: 思考ID + actions: 动作列表 + + Returns: + Tuple[Dict[str, Any], str, Dict[str, float]]: 循环信息, 回复文本, 循环计时器 + """ + # 发送回复 with Timer("回复发送", cycle_timers): reply_text, sent_messages = await self.response_handler.send_response( response_set, loop_start_time, action_message ) if sent_messages: + # 异步处理错别字修正 asyncio.create_task(self.response_handler.handle_typo_correction(sent_messages)) - # 存储reply action信息 + # 存储reply action信息 person_info_manager = get_person_info_manager() # 获取 platform，如果不存在则从 chat_stream 获取，如果还是 None 则使用默认值 @@ -66,6 +86,7 @@ class CycleProcessor: if platform is None: platform = getattr(self.context.chat_stream, "platform", "unknown") + # 获取用户信息并生成回复提示 person_id = person_info_manager.get_person_id( platform, action_message.get("user_id", ""), @@ -73,6 +94,7 @@ class CycleProcessor: person_name = await person_info_manager.get_value(person_id, "person_name") action_prompt_display = f"你对{person_name}进行了回复：{reply_text}" + # 存储动作信息到数据库 await database_api.store_action_info( chat_stream=self.context.chat_stream, action_build_into_prompt=False, @@ -106,7 +128,7 @@ class CycleProcessor: interest_value: 兴趣值 Returns: - bool: 处理是否成功 + str: 动作类型 功能说明: - 开始新的思考循环并记录计时 @@ -122,6 +144,15 @@ class CycleProcessor: # 当interest_value为0时，概率接近0（使用Focus模式） # 当interest_value很高时，概率接近1（使用Normal模式） def calculate_normal_mode_probability(interest_val: float) -> float: + """ + 计算普通模式的概率 + + Args: + interest_val: 兴趣值 + + Returns: + float: 概率 + """ # 使用sigmoid函数，调整参数使概率分布更合理 # 当interest_value = 0时，概率约为0.1 # 当interest_value = 1时，概率约为0.5 @@ -131,6 +162,7 @@ class CycleProcessor: x0 = 1.0 # 控制曲线中心点 return 1.0 / (1.0 + math.exp(-k * (interest_val - x0))) + # 计算普通模式概率 normal_mode_probability = ( calculate_normal_mode_probability(interest_value) * 0.5 @@ -149,9 +181,11 @@ class CycleProcessor: f"{self.log_prefix} 基于兴趣值 {interest_value:.2f}，概率 {normal_mode_probability:.2f}，选择Focus planner模式" ) + # 开始新的思考循环 cycle_timers, thinking_id = self.cycle_tracker.start_cycle() logger.info(f"{self.log_prefix} 开始第{self.context.cycle_counter}次思考") + # 发送正在输入状态 if ENABLE_S4U and self.context.chat_stream and self.context.chat_stream.user_info: await send_typing(self.context.chat_stream.user_info.user_id) @@ -176,12 +210,14 @@ class CycleProcessor: from src.plugin_system.core.event_manager import event_manager from src.plugin_system import EventType + # 触发规划前事件 result = await event_manager.trigger_event( EventType.ON_PLAN, plugin_name="SYSTEM", stream_id=self.context.chat_stream ) if result and not result.all_continue_process(): raise UserWarning(f"插件{result.get_summary().get('stopped_handlers', '')}于规划前中断了内容生成") + # 规划动作 with Timer("规划器", cycle_timers): actions, _ = await self.action_planner.plan( mode=mode, @@ -227,6 +263,7 @@ class CycleProcessor: "command": command, } else: + # 生成回复 try: success, response_set, _ = await generator_api.generate_reply( chat_stream=self.context.chat_stream, @@ -245,6 +282,7 @@ class CycleProcessor: logger.debug(f"{self.log_prefix} 并行执行：回复生成任务已被取消") return {"action_type": "reply", "success": False, "reply_text": "", "loop_info": None} + # 发送并存储回复 loop_info, reply_text, cycle_timers_reply = await self._send_and_store_reply( response_set, loop_start_time, @@ -323,13 +361,15 @@ class CycleProcessor: } reply_text = action_reply_text + # 停止正在输入状态 if ENABLE_S4U: await stop_typing() + # 结束循环 self.context.chat_instance.cycle_tracker.end_cycle(loop_info, cycle_timers) self.context.chat_instance.cycle_tracker.print_cycle_info(cycle_timers) - action_type = actions[0]["action_type"] if actions else "no_action" + action_type = actions["action_type"] if actions else "no_action" return action_type async def _handle_action( @@ -357,6 +397,7 @@ class CycleProcessor: if not self.context.chat_stream: return False, "", "" try: + # 创建动作处理器 action_handler = self.context.action_manager.create_action( action_name=action, action_data=action_data, @@ -398,6 +439,7 @@ class CycleProcessor: logger.error(f"{self.context.log_prefix} 回退方案也失败，无法创建任何动作处理器") return False, "", "" + # 执行动作 success, reply_text = await action_handler.handle_action() return success, reply_text, "" except Exception as e: diff --git a/src/chat/chat_loop/response_handler.py b/src/chat/chat_loop/response_handler.py index 982b7d54d..8b56127e0 100644 --- a/src/chat/chat_loop/response_handler.py +++ b/src/chat/chat_loop/response_handler.py @@ -10,11 +10,15 @@ from .hfc_context import HfcContext # 导入反注入系统 +# 日志记录器 logger = get_logger("hfc") anti_injector_logger = get_logger("anti_injector") class ResponseHandler: + """ + 响应处理器类，负责生成和发送机器人的回复。 + """ def __init__(self, context: HfcContext): """ 初始化响应处理器 @@ -60,12 +64,15 @@ class ResponseHandler: - 构建并返回完整的循环信息 - 用于上级方法的状态跟踪 """ + # 发送回复 reply_text, sent_messages = await self.send_response(response_set, loop_start_time, action_message) if sent_messages: + # 异步处理错别字修正 asyncio.create_task(self.handle_typo_correction(sent_messages)) person_info_manager = get_person_info_manager() + # 获取平台信息 platform = "default" if self.context.chat_stream: platform = ( @@ -74,11 +81,13 @@ class ResponseHandler: or self.context.chat_stream.platform ) + # 获取用户信息并生成回复提示 user_id = action_message.get("user_id", "") person_id = person_info_manager.get_person_id(platform, user_id) person_name = await person_info_manager.get_value(person_id, "person_name") action_prompt_display = f"你对{person_name}进行了回复：{reply_text}" + # 存储动作信息到数据库 await database_api.store_action_info( chat_stream=self.context.chat_stream, action_build_into_prompt=False, @@ -89,6 +98,7 @@ class ResponseHandler: action_name="reply", ) + # 构建循环信息 loop_info: Dict[str, Any] = { "loop_plan_info": { "action_result": plan_result.get("action_result", {}), @@ -123,10 +133,12 @@ class ResponseHandler: - 正确处理元组格式的回复段 """ current_time = time.time() + # 计算新消息数量 new_message_count = message_api.count_new_messages( chat_id=self.context.stream_id, start_time=thinking_start_time, end_time=current_time ) + # 根据新消息数量决定是否需要引用回复 need_reply = new_message_count >= random.randint(2, 4) reply_text = "" @@ -137,6 +149,7 @@ class ResponseHandler: for reply_seg in reply_set: logger.debug(f"Processing reply_seg type: {type(reply_seg)}, content: {reply_seg}") + # 提取回复内容 if reply_seg["type"] == "typo": data = reply_seg["typo"] else: @@ -144,10 +157,12 @@ class ResponseHandler: reply_text += data + # 如果是主动思考且内容为“沉默”，则不发送 if is_proactive_thinking and data.strip() == "沉默": logger.info(f"{self.context.log_prefix} 主动思考决定保持沉默，不发送消息") continue + # 发送第一段回复 if not first_replied: sent_message = await send_api.text_to_stream( text=data, @@ -158,6 +173,7 @@ class ResponseHandler: ) first_replied = True else: + # 发送后续回复 sent_message = await send_api.text_to_stream( text=data, stream_id=self.context.stream_id, @@ -165,6 +181,7 @@ class ResponseHandler: set_reply=False, typing=True, ) + # 记录已发送的错别字消息 if sent_message and reply_seg["type"] == "typo": sent_messages.append( { @@ -181,9 +198,12 @@ class ResponseHandler: """处理错别字修正""" for msg in sent_messages: if msg["type"] == "typo": + # 随机等待一段时间 await asyncio.sleep(random.uniform(2, 4)) + # 撤回消息 recalled = await send_api.recall_message(str(msg["message_id"]), self.context.stream_id) if recalled: + # 发送修正后的消息 await send_api.text_to_stream( str(msg["correction"]), self.context.stream_id, reply_to_message=msg["original_message"] ) diff --git a/src/plugin_system/apis/generator_api.py b/src/plugin_system/apis/generator_api.py index 3ea507cc0..7f3074a81 100644 --- a/src/plugin_system/apis/generator_api.py +++ b/src/plugin_system/apis/generator_api.py @@ -20,6 +20,7 @@ from src.plugin_system.base.component_types import ActionInfo install(extra_lines=3) +# 日志记录器 logger = get_logger("generator_api") @@ -113,6 +114,7 @@ async def generate_reply( logger.debug("[GeneratorAPI] 开始生成回复") + # 向下兼容，从action_data中获取reply_to和extra_info if not reply_to and action_data: reply_to = action_data.get("reply_to", "") if not extra_info and action_data: @@ -133,6 +135,7 @@ async def generate_reply( return False, [], None assert llm_response_dict is not None, "llm_response_dict不应为None" # 虽然说不会出现llm_response为空的情况 if content := llm_response_dict.get("content", ""): + # 处理为拟人化文本 reply_set = process_human_text(content, enable_splitter, enable_chinese_typo) else: reply_set = [] @@ -208,6 +211,7 @@ async def rewrite_reply( ) reply_set = [] if content: + # 处理为拟人化文本 reply_set = process_human_text(content, enable_splitter, enable_chinese_typo) if success: @@ -238,6 +242,7 @@ def process_human_text( if not isinstance(content, str): raise ValueError("content 必须是字符串类型") try: + # 处理LLM响应 processed_response = process_llm_response(content, enable_splitter, enable_chinese_typo) reply_set = [] @@ -260,6 +265,18 @@ async def generate_response_custom( request_type: str = "generator_api", prompt: str = "", ) -> Optional[str]: + """ + 使用自定义提示生成回复 + + Args: + chat_stream: 聊天流对象 + chat_id: 聊天ID + request_type: 请求类型 + prompt: 自定义提示 + + Returns: + Optional[str]: 生成的回复内容 + """ replyer = get_replyer(chat_stream, chat_id, request_type=request_type) if not replyer: logger.error("[GeneratorAPI] 无法获取回复器") diff --git a/src/plugin_system/apis/send_api.py b/src/plugin_system/apis/send_api.py index 9c629fc3b..3aea3cde4 100644 --- a/src/plugin_system/apis/send_api.py +++ b/src/plugin_system/apis/send_api.py @@ -43,6 +43,7 @@ from src.chat.message_receive.message import MessageSending, MessageRecv from maim_message import Seg from src.config.config import global_config +# 日志记录器 logger = get_logger("send_api") # 适配器命令响应等待池 @@ -186,6 +187,7 @@ async def _send_to_target( # 创建消息段 message_segment = Seg(type=message_type, data=content) # type: ignore + # 处理回复消息 if reply_to_message: anchor_message = message_dict_to_message_recv(message_dict=reply_to_message) if anchor_message and anchor_message.message_info and anchor_message.message_info.user_info: