utils 方法解释还原

src/plugins/PFC/pfc_utils.py

@@ -202,6 +202,13 @@ async def retrieve_contextual_info(
 ) -> Tuple[str, str, str]:                 # 返回: 全局记忆, 知识, 私聊历史回忆
     """
     检索三种类型的上下文信息：全局压缩记忆、知识库知识、当前私聊的特定历史对话。
+
+    Args:
+        text: 用于检索的上下文文本 (例如聊天记录)。
+        private_name: 私聊对象的名称，用于日志记录。
+
+    Returns:
+        Tuple[str, str]: (检索到的记忆字符串, 检索到的知识字符串)
     """
     # 初始化返回值
     retrieved_global_memory_str = "无相关全局记忆。"
@@ -377,7 +384,17 @@ def get_items_from_json(
     allow_array: bool = True,
 ) -> Tuple[bool, Union[Dict[str, Any], List[Dict[str, Any]]]]:
     """从文本中提取JSON内容并获取指定字段
-    (保持你原始 pfc_utils.py 中的此函数代码不变)
+
+    Args:
+        content: 包含JSON的文本
+        private_name: 私聊名称
+        *items: 要提取的字段名
+        default_values: 字段的默认值，格式为 {字段名: 默认值}
+        required_types: 字段的必需类型，格式为 {字段名: 类型}
+        allow_array: 是否允许解析JSON数组
+
+    Returns:
+        Tuple[bool, Union[Dict[str, Any], List[Dict[str, Any]]]]: (是否成功, 提取的字段字典或字典列表)
     """
     cleaned_content = content.strip()
     result: Union[Dict[str, Any], List[Dict[str, Any]]] = {}
@@ -540,7 +557,7 @@ async def adjust_relationship_value_nonlinear(old_value: float, raw_adjustment:
 
 
 async def build_chat_history_text(observation_info: ObservationInfo, private_name: str) -> str:
-    """ (保持你原始 pfc_utils.py 中的此函数代码不变) """
+    """构建聊天历史记录文本 (包含未处理消息)"""
     chat_history_text = ""
     try:
         if hasattr(observation_info, "chat_history_str") and observation_info.chat_history_str: