docs(planner): 为规划器相关模块添加详细的文档字符串

为 `plan_executor`、`planner` 和 `planner_prompts` 模块中的类和函数补充了详细的文档字符串（docstrings）。

这提高了代码的可读性和可维护性，阐明了每个组件的职责、参数和返回值，使得其他开发者能更容易地理解和使用这些模块。

src/chat/planner_actions/plan_executor.py

@@ -10,15 +10,32 @@ logger = get_logger("plan_executor")
 
 class PlanExecutor:
     """
-    执行 Plan 中最终确定的动作。
+    负责接收一个 Plan 对象，并执行其中最终确定的所有动作。
+
+    这个类是规划流程的最后一步，将规划结果转化为实际的动作执行。
+
+    Attributes:
+        action_manager (ActionManager): 用于实际执行各种动作的管理器实例。
     """
 
     def __init__(self, action_manager: ActionManager):
+        """
+        初始化 PlanExecutor。
+
+        Args:
+            action_manager (ActionManager): 一个 ActionManager 实例，用于执行动作。
+        """
         self.action_manager = action_manager
 
     async def execute(self, plan: Plan):
         """
-        读取 Plan 对象的 decided_actions 字段并执行。
+        遍历并执行 Plan 对象中 `decided_actions` 列表里的所有动作。
+
+        如果动作类型为 "no_action"，则会记录原因并跳过。
+        否则，它将调用 ActionManager 来执行相应的动作。
+
+        Args:
+            plan (Plan): 包含待执行动作列表的 Plan 对象。
         """
         if not plan.decided_actions:
             logger.info("没有需要执行的动作。")

src/chat/planner_actions/plan_generator.py

@@ -15,10 +15,25 @@ from src.plugin_system.core.component_registry import component_registry
 
 class PlanGenerator:
     """
-    搜集信息并生成初始 Plan 对象。
+    PlanGenerator 负责在规划流程的初始阶段收集所有必要信息。
+
+    它会汇总以下信息来构建一个“原始”的 Plan 对象，该对象后续会由 PlanFilter 进行筛选：
+    -   当前聊天信息 (ID, 目标用户)
+    -   当前可用的动作列表
+    -   最近的聊天历史记录
+
+    Attributes:
+        chat_id (str): 当前聊天的唯一标识符。
+        action_manager (ActionManager): 用于获取可用动作列表的管理器。
     """
 
     def __init__(self, chat_id: str):
+        """
+        初始化 PlanGenerator。
+
+        Args:
+            chat_id (str): 当前聊天的 ID。
+        """
         from src.chat.planner_actions.action_manager import ActionManager
         self.chat_id = chat_id
         # 注意：ActionManager 可能需要根据实际情况初始化
@@ -26,7 +41,15 @@ class PlanGenerator:
 
     async def generate(self, mode: ChatMode) -> Plan:
         """
-        生成并填充初始的 Plan 对象。
+        收集所有信息，生成并返回一个初始的 Plan 对象。
+
+        这个 Plan 对象包含了决策所需的所有上下文信息。
+
+        Args:
+            mode (ChatMode): 当前的聊天模式。
+
+        Returns:
+            Plan: 一个填充了初始上下文信息的 Plan 对象。
         """
         _is_group_chat, chat_target_info_dict = get_chat_type_and_target_info(self.chat_id)
         
@@ -55,7 +78,13 @@ class PlanGenerator:
 
     def _get_available_actions(self) -> Dict[str, "ActionInfo"]:
         """
-        获取当前可用的动作。
+        从 ActionManager 和组件注册表中获取当前所有可用的动作。
+
+        它会合并已注册的动作和系统级动作（如 "no_reply"），
+        并以字典形式返回。
+
+        Returns:
+            Dict[str, "ActionInfo"]: 一个字典，键是动作名称，值是 ActionInfo 对象。
         """
         current_available_actions_dict = self.action_manager.get_using_actions()
         all_registered_actions: Dict[str, ActionInfo] = component_registry.get_components_by_type( # type: ignore

src/chat/planner_actions/planner.py

@@ -20,10 +20,29 @@ logger = get_logger("planner")
 
 class ActionPlanner:
     """
-    协调器，按顺序调用 Generator -> Filter -> Executor。
+    ActionPlanner 是规划系统的核心协调器。
+
+    它负责整合规划流程的三个主要阶段：
+    1.  **生成 (Generate)**: 使用 PlanGenerator 创建一个初始的行动计划。
+    2.  **筛选 (Filter)**: 使用 PlanFilter 对生成的计划进行审查和优化。
+    3.  **执行 (Execute)**: 使用 PlanExecutor 执行最终确定的行动。
+
+    Attributes:
+        chat_id (str): 当前聊天的唯一标识符。
+        action_manager (ActionManager): 用于执行具体动作的管理器。
+        generator (PlanGenerator): 负责生成初始计划。
+        filter (PlanFilter): 负责筛选和优化计划。
+        executor (PlanExecutor): 负责执行最终计划。
     """
 
     def __init__(self, chat_id: str, action_manager: ActionManager):
+        """
+        初始化 ActionPlanner。
+
+        Args:
+            chat_id (str): 当前聊天的 ID。
+            action_manager (ActionManager): 一个 ActionManager 实例。
+        """
         self.chat_id = chat_id
         self.action_manager = action_manager
         self.generator = PlanGenerator(chat_id)
@@ -34,7 +53,18 @@ class ActionPlanner:
         self, mode: ChatMode = ChatMode.FOCUS
     ) -> Tuple[List[Dict], Optional[Dict]]:
         """
-        执行完整的规划流程。
+        执行从生成到执行的完整规划流程。
+
+        这个方法按顺序协调生成、筛选和执行三个阶段。
+
+        Args:
+            mode (ChatMode): 当前的聊天模式，默认为 FOCUS。
+
+        Returns:
+            Tuple[List[Dict], Optional[Dict]]: 一个元组，包含：
+                - final_actions_dict (List[Dict]): 最终确定的动作列表（字典格式）。
+                - final_target_message_dict (Optional[Dict]): 最终的目标消息（字典格式），如果没有则为 None。
+                这与旧版 planner 的返回值保持兼容。
         """
         # 1. 生成初始 Plan
         initial_plan = await self.generator.generate(mode)

src/chat/planner_actions/planner_prompts.py

@@ -1,12 +1,21 @@
 """
-本文件集中管理所有与规划器相关的提示词模板。
+本文件集中管理所有与规划器（Planner）相关的提示词（Prompt）模板。
+
+通过将提示词与代码逻辑分离，可以更方便地对模型的行为进行迭代和优化，
+而无需修改核心代码。
 """
 from src.chat.utils.prompt import Prompt
 
+
 def init_prompts():
     """
-    初始化并注册所有规划器相关的提示词。
+    初始化并向 Prompt 注册系统注册所有规划器相关的提示词。
+
+    这个函数会在模块加载时自动调用，确保所有提示词在系统启动时都已准备就绪。
     """
+    # 核心规划器提示词，用于在接收到新消息时决定如何回应。
+    # 它构建了一个复杂的上下文，包括历史记录、可用动作、角色设定等，
+    # 并要求模型以 JSON 格式输出一个或多个动作组合。
     Prompt(
         """
 {schedule_block}
@@ -83,6 +92,8 @@ def init_prompts():
         "planner_prompt",
     )
 
+    # 主动思考规划器提示词，用于在没有新消息时决定是否要主动发起对话。
+    # 它模拟了人类的自发性思考，允许模型根据长期记忆和最近的对话来决定是否开启新话题。
     Prompt(
         """
 # 主动思考决策
@@ -140,6 +151,8 @@ def init_prompts():
         "proactive_planner_prompt",
     )
 
+    # 单个动作的格式化提示词模板。
+    # 用于将每个可用动作的信息格式化后，插入到主提示词的 {action_options_text} 占位符中。
     Prompt(
         """
 动作：{action_name}
@@ -154,5 +167,6 @@ def init_prompts():
         "action_prompt",
     )
 
-# 在模块加载时自动初始化
+
+# 在模块加载时自动调用，完成提示词的注册。
 init_prompts()