perf: 修改部分注释

astrbot/core/conversation_mgr.py

@@ -39,7 +39,13 @@ class ConversationManager:
         sp.put("session_conversation", self.session_conversations)
 
     async def new_conversation(self, unified_msg_origin: str) -> str:
-        """新建对话，并将当前会话的对话转移到新对话"""
+        """新建对话，并将当前会话的对话转移到新对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         conversation_id = str(uuid.uuid4())
         self.db.new_conversation(user_id=unified_msg_origin, cid=conversation_id)
         self.session_conversations[unified_msg_origin] = conversation_id
@@ -47,14 +53,24 @@ class ConversationManager:
         return conversation_id
 
     async def switch_conversation(self, unified_msg_origin: str, conversation_id: str):
-        """切换会话的对话"""
+        """切换会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         self.session_conversations[unified_msg_origin] = conversation_id
         sp.put("session_conversation", self.session_conversations)
 
     async def delete_conversation(
         self, unified_msg_origin: str, conversation_id: str = None
     ):
-        """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话"""
+        """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.delete_conversation(user_id=unified_msg_origin, cid=conversation_id)
@@ -62,23 +78,48 @@ class ConversationManager:
             sp.put("session_conversation", self.session_conversations)
 
     async def get_curr_conversation_id(self, unified_msg_origin: str) -> str:
-        """获取会话当前的对话 ID"""
+        """获取会话当前的对话 ID
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         return self.session_conversations.get(unified_msg_origin, None)
 
     async def get_conversation(
         self, unified_msg_origin: str, conversation_id: str
     ) -> Conversation:
-        """获取会话的对话"""
+        """获取会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        Returns:
+            conversation (Conversation): 对话对象
+        """
         return self.db.get_conversation_by_user_id(unified_msg_origin, conversation_id)
 
     async def get_conversations(self, unified_msg_origin: str) -> List[Conversation]:
-        """获取会话的所有对话"""
+        """获取会话的所有对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversations (List[Conversation]): 对话对象列表
+        """
         return self.db.get_conversations(unified_msg_origin)
 
     async def update_conversation(
         self, unified_msg_origin: str, conversation_id: str, history: List[Dict]
     ):
-        """更新会话的对话"""
+        """更新会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+            history (List[Dict]): 对话历史记录, 是一个字典列表, 每个字典包含 role 和 content 字段
+        """
         if conversation_id:
             self.db.update_conversation(
                 user_id=unified_msg_origin,
@@ -87,7 +128,12 @@ class ConversationManager:
             )
 
     async def update_conversation_title(self, unified_msg_origin: str, title: str):
-        """更新会话的对话标题"""
+        """更新会话的对话标题
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            title (str): 对话标题
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.update_conversation_title(
@@ -97,7 +143,12 @@ class ConversationManager:
     async def update_conversation_persona_id(
         self, unified_msg_origin: str, persona_id: str
     ):
-        """更新会话的对话 Persona ID"""
+        """更新会话的对话 Persona ID
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            persona_id (str): 对话 Persona ID
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.update_conversation_persona_id(
@@ -107,7 +158,14 @@ class ConversationManager:
     async def get_human_readable_context(
         self, unified_msg_origin, conversation_id, page=1, page_size=10
     ):
-        """获取人类可读的上下文"""
+        """获取人类可读的上下文
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+            page (int): 页码
+            page_size (int): 每页大小
+        """
         conversation = await self.get_conversation(unified_msg_origin, conversation_id)
         history = json.loads(conversation.history)
 

astrbot/core/log.py

@@ -46,7 +46,7 @@ log_color_config = {
 def is_plugin_path(pathname):
     """检查文件路径是否来自插件目录
 
-    Parameters:
+    Args:
         pathname (str): 文件路径
 
     Returns:
@@ -62,7 +62,7 @@ def is_plugin_path(pathname):
 def get_short_level_name(level_name):
     """将日志级别名称转换为四个字母的缩写
 
-    Parameters:
+    Args:
         level_name (str): 日志级别名称, 如 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
 
     Returns:
@@ -103,7 +103,7 @@ class LogBroker:
     def unregister(self, q: Queue):
         """取消订阅
 
-        Parameters:
+        Args:
             q (Queue): 需要取消订阅的队列
         """
         self.subscribers.remove(q)
@@ -111,7 +111,7 @@ class LogBroker:
     def publish(self, log_entry: str):
         """发布新日志到所有订阅者, 使用非阻塞方式投递, 避免一个订阅者阻塞整个系统
 
-        Parameters:
+        Args:
             log_entry (str): 日志消息, 可以是字符串或字典
         """
         self.log_cache.append(log_entry)
@@ -136,7 +136,7 @@ class LogQueueHandler(logging.Handler):
         """日志处理的入口方法, 接受一个日志记录, 转换为字符串后由 LogBroker 发布
         这个方法会在每次日志记录时被调用
 
-        Parameters:
+        Args:
             record (logging.LogRecord): 日志记录对象, 包含日志信息
         """
         log_entry = self.format(record)
@@ -151,7 +151,14 @@ class LogManager:
 
     @classmethod
     def GetLogger(cls, log_name: str = "default"):
-        """获取指定名称的日志记录器logger"""
+        """获取指定名称的日志记录器logger
+
+        Args:
+            log_name (str): 日志记录器的名称, 默认为 "default"
+
+        Returns:
+            logging.Logger: 返回配置好的日志记录器
+        """
         logger = logging.getLogger(log_name)
         # 检查该logger或父级logger是否已经有处理器, 如果已经有处理器, 直接返回该logger, 避免重复配置
         if logger.hasHandlers():
@@ -211,7 +218,12 @@ class LogManager:
 
     @classmethod
     def set_queue_handler(cls, logger: logging.Logger, log_broker: LogBroker):
-        """设置队列处理器, 用于将日志消息发送到 LogBroker"""
+        """设置队列处理器, 用于将日志消息发送到 LogBroker
+
+        Args:
+            logger (logging.Logger): 日志记录器
+            log_broker (LogBroker): 日志代理类, 用于缓存和分发日志消息
+        """
         handler = LogQueueHandler(log_broker)
         handler.setLevel(logging.DEBUG)
         if logger.handlers:

astrbot/core/pipeline/stage.py

@@ -8,8 +8,7 @@ from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from .context import PipelineContext
 from astrbot.core.message.message_event_result import MessageEventResult, CommandResult
 
-registered_stages: List[Stage] = []
-"""维护了所有已注册的 Stage 实现类"""
+registered_stages: List[Stage] = []  # 维护了所有已注册的 Stage 实现类
 
 
 def register_stage(cls):

astrbot/core/pipeline/waking_check/stage.py

@@ -21,6 +21,11 @@ class WakingCheckStage(Stage):
     """
 
     async def initialize(self, ctx: PipelineContext) -> None:
+        """初始化唤醒检查阶段
+
+        Args:
+            ctx (PipelineContext): 消息管道上下文对象, 包括配置和插件管理器
+        """
         self.ctx = ctx
         self.no_permission_reply = self.ctx.astrbot_config["platform_settings"].get(
             "no_permission_reply", True