AstrBot 4.3.3__py3-none-any.whl → 4.5.0__py3-none-any.whl

astrbot/core/agent/mcp_client.py

@@ -40,8 +40,15 @@ async def _quick_test_mcp_connection(config: dict) -> tuple[bool, str]:
     timeout = cfg.get("timeout", 10)
 
     try:
+        if "transport" in cfg:
+            transport_type = cfg["transport"]
+        elif "type" in cfg:
+            transport_type = cfg["type"]
+        else:
+            raise Exception("MCP 连接配置缺少 transport 或 type 字段")
+
         async with aiohttp.ClientSession() as session:
-            if cfg.get("transport") == "streamable_http":
+            if transport_type == "streamable_http":
                 test_payload = {
                     "jsonrpc": "2.0",
                     "method": "initialize",
@@ -121,7 +128,14 @@ class MCPClient:
             if not success:
                 raise Exception(error_msg)
 
-            if cfg.get("transport") != "streamable_http":
+            if "transport" in cfg:
+                transport_type = cfg["transport"]
+            elif "type" in cfg:
+                transport_type = cfg["type"]
+            else:
+                raise Exception("MCP 连接配置缺少 transport 或 type 字段")
+
+            if transport_type != "streamable_http":
                 # SSE transport method
                 self._streams_context = sse_client(
                     url=cfg["url"],
@@ -134,7 +148,7 @@ class MCPClient:
                 )
 
                 # Create a new client session
-                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 20))
+                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 60))
                 self.session = await self.exit_stack.enter_async_context(
                     mcp.ClientSession(
                         *streams,
@@ -159,7 +173,7 @@ class MCPClient:
                 )
 
                 # Create a new client session
-                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 20))
+                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 60))
                 self.session = await self.exit_stack.enter_async_context(
                     mcp.ClientSession(
                         read_stream=read_s,

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -209,9 +209,38 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                     )
                     continue
 
+                valid_params = {}  # 参数过滤：只传递函数实际需要的参数
+
+                # 获取实际的 handler 函数
+                if func_tool.handler:
+                    logger.debug(
+                        f"工具 {func_tool_name} 期望的参数: {func_tool.parameters}"
+                    )
+                    if func_tool.parameters and func_tool.parameters.get("properties"):
+                        expected_params = set(func_tool.parameters["properties"].keys())
+
+                        valid_params = {
+                            k: v
+                            for k, v in func_tool_args.items()
+                            if k in expected_params
+                        }
+
+                    # 记录被忽略的参数
+                    ignored_params = set(func_tool_args.keys()) - set(
+                        valid_params.keys()
+                    )
+                    if ignored_params:
+                        logger.warning(
+                            f"工具 {func_tool_name} 忽略非期望参数: {ignored_params}"
+                        )
+                else:
+                    # 如果没有 handler（如 MCP 工具），使用所有参数
+                    valid_params = func_tool_args
+                    logger.warning(f"工具 {func_tool_name} 没有 handler，使用所有参数")
+
                 try:
                     await self.agent_hooks.on_tool_start(
-                        self.run_context, func_tool, func_tool_args
+                        self.run_context, func_tool, valid_params
                     )
                 except Exception as e:
                     logger.error(f"Error in on_tool_start hook: {e}", exc_info=True)
@@ -219,7 +248,7 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 executor = self.tool_executor.execute(
                     tool=func_tool,
                     run_context=self.run_context,
-                    **func_tool_args,
+                    **valid_params,  # 只传递有效的参数
                 )
 
                 _final_resp: CallToolResult | None = None

astrbot/core/astr_agent_context.py

@@ -9,3 +9,4 @@ class AstrAgentContext:
     first_provider_request: ProviderRequest
     curr_provider_request: ProviderRequest
     streaming: bool
+    tool_call_timeout: int = 60  # Default tool call timeout in seconds

astrbot/core/astrbot_config_mgr.py

@@ -5,6 +5,7 @@ from astrbot.core.utils.shared_preferences import SharedPreferences
 from astrbot.core.config.astrbot_config import ASTRBOT_CONFIG_PATH
 from astrbot.core.config.default import DEFAULT_CONFIG
 from astrbot.core.platform.message_session import MessageSession
+from astrbot.core.umop_config_router import UmopConfigRouter
 from astrbot.core.utils.astrbot_path import get_astrbot_config_path
 from typing import TypeVar, TypedDict
 
@@ -15,14 +16,12 @@ class ConfInfo(TypedDict):
     """Configuration information for a specific session or platform."""
 
     id: str  # UUID of the configuration or "default"
-    umop: list[str]  # Unified Message Origin Pattern
     name: str
     path: str  # File name to the configuration file
 
 
 DEFAULT_CONFIG_CONF_INFO = ConfInfo(
     id="default",
-    umop=["::"],
     name="default",
     path=ASTRBOT_CONFIG_PATH,
 )
@@ -31,8 +30,14 @@ DEFAULT_CONFIG_CONF_INFO = ConfInfo(
 class AstrBotConfigManager:
     """A class to manage the system configuration of AstrBot, aka ACM"""
 
-    def __init__(self, default_config: AstrBotConfig, sp: SharedPreferences):
+    def __init__(
+        self,
+        default_config: AstrBotConfig,
+        ucr: UmopConfigRouter,
+        sp: SharedPreferences,
+    ):
         self.sp = sp
+        self.ucr = ucr
         self.confs: dict[str, AstrBotConfig] = {}
         """uuid / "default" -> AstrBotConfig"""
         self.confs["default"] = default_config
@@ -63,24 +68,15 @@ class AstrBotConfigManager:
                 )
                 continue
 
-    def _is_umo_match(self, p1: str, p2: str) -> bool:
-        """判断 p2 umo 是否逻辑包含于 p1 umo"""
-        p1_ls = p1.split(":")
-        p2_ls = p2.split(":")
-
-        if len(p1_ls) != 3 or len(p2_ls) != 3:
-            return False  # 非法格式
-
-        return all(p == "" or p == "*" or p == t for p, t in zip(p1_ls, p2_ls))
-
     def _load_conf_mapping(self, umo: str | MessageSession) -> ConfInfo:
         """获取指定 umo 的配置文件 uuid, 如果不存在则返回默认配置(返回 "default")
 
         Returns:
             ConfInfo: 包含配置文件的 uuid, 路径和名称等信息, 是一个 dict 类型
         """
-        # uuid -> { "umop": list, "path": str, "name": str }
+        # uuid -> { "path": str, "name": str }
         abconf_data = self._get_abconf_data()
+
         if isinstance(umo, MessageSession):
             umo = str(umo)
         else:
@@ -89,10 +85,13 @@ class AstrBotConfigManager:
             except Exception:
                 return DEFAULT_CONFIG_CONF_INFO
 
-        for uuid_, meta in abconf_data.items():
-            for pattern in meta["umop"]:
-                if self._is_umo_match(pattern, umo):
-                    return ConfInfo(**meta, id=uuid_)
+        conf_id = self.ucr.get_conf_id_for_umop(umo)
+        if conf_id:
+            meta = abconf_data.get(conf_id)
+            if meta and isinstance(meta, dict):
+                # the bind relation between umo and conf is defined in ucr now, so we remove "umop" here
+                meta.pop("umop", None)
+                return ConfInfo(**meta, id=conf_id)
 
         return DEFAULT_CONFIG_CONF_INFO
 
@@ -100,23 +99,14 @@ class AstrBotConfigManager:
         self,
         abconf_path: str,
         abconf_id: str,
-        umo_parts: list[str] | list[MessageSession],
         abconf_name: str | None = None,
     ) -> None:
         """保存配置文件的映射关系"""
-        for part in umo_parts:
-            if isinstance(part, MessageSession):
-                part = str(part)
-            elif not isinstance(part, str):
-                raise ValueError(
-                    "umo_parts must be a list of strings or MessageSession instances"
-                )
         abconf_data = self.sp.get(
             "abconf_mapping", {}, scope="global", scope_id="global"
         )
         random_word = abconf_name or uuid.uuid4().hex[:8]
         abconf_data[abconf_id] = {
-            "umop": umo_parts,
             "path": abconf_path,
             "name": random_word,
         }
@@ -153,29 +143,26 @@ class AstrBotConfigManager:
     def get_conf_list(self) -> list[ConfInfo]:
         """获取所有配置文件的元数据列表"""
         conf_list = []
-        conf_list.append(DEFAULT_CONFIG_CONF_INFO)
         abconf_mapping = self._get_abconf_data()
         for uuid_, meta in abconf_mapping.items():
+            if not isinstance(meta, dict):
+                continue
+            meta.pop("umop", None)
             conf_list.append(ConfInfo(**meta, id=uuid_))
+        conf_list.append(DEFAULT_CONFIG_CONF_INFO)
         return conf_list
 
     def create_conf(
         self,
-        umo_parts: list[str] | list[MessageSession],
         config: dict = DEFAULT_CONFIG,
         name: str | None = None,
     ) -> str:
-        """
-        umo 由三个部分组成 [platform_id]:[message_type]:[session_id]。
-
-        umo_parts 可以是 "::" (代表所有), 可以是 "[platform_id]::" (代表指定平台下的所有类型消息和会话)。
-        """
         conf_uuid = str(uuid.uuid4())
         conf_file_name = f"abconf_{conf_uuid}.json"
         conf_path = os.path.join(get_astrbot_config_path(), conf_file_name)
         conf = AstrBotConfig(config_path=conf_path, default_config=config)
         conf.save_config()
-        self._save_conf_mapping(conf_file_name, conf_uuid, umo_parts, abconf_name=name)
+        self._save_conf_mapping(conf_file_name, conf_uuid, abconf_name=name)
         self.confs[conf_uuid] = conf
         return conf_uuid
 
@@ -228,15 +215,12 @@ class AstrBotConfigManager:
         logger.info(f"成功删除配置文件 {conf_id}")
         return True
 
-    def update_conf_info(
-        self, conf_id: str, name: str | None = None, umo_parts: list[str] | None = None
-    ) -> bool:
+    def update_conf_info(self, conf_id: str, name: str | None = None) -> bool:
         """更新配置文件信息
 
         Args:
             conf_id: 配置文件的 UUID
             name: 新的配置文件名称 (可选)
-            umo_parts: 新的 UMO 部分列表 (可选)
 
         Returns:
             bool: 更新是否成功
@@ -255,18 +239,6 @@ class AstrBotConfigManager:
         if name is not None:
             abconf_data[conf_id]["name"] = name
 
-        # 更新 UMO 部分
-        if umo_parts is not None:
-            # 验证 UMO 部分格式
-            for part in umo_parts:
-                if isinstance(part, MessageSession):
-                    part = str(part)
-                elif not isinstance(part, str):
-                    raise ValueError(
-                        "umo_parts must be a list of strings or MessageSession instances"
-                    )
-            abconf_data[conf_id]["umop"] = umo_parts
-
         # 保存更新
         self.sp.put("abconf_mapping", abconf_data, scope="global", scope_id="global")
         self.abconf_data = abconf_data

astrbot/core/config/default.py

@@ -6,7 +6,7 @@ import os
 
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
-VERSION = "4.3.3"
+VERSION = "4.5.0"
 DB_PATH = os.path.join(get_astrbot_data_path(), "data_v4.db")
 
 # 默认配置
@@ -57,6 +57,7 @@ DEFAULT_CONFIG = {
         "web_search": False,
         "websearch_provider": "default",
         "websearch_tavily_key": [],
+        "websearch_baidu_app_builder_key": "",
         "web_search_link": False,
         "display_reasoning_text": False,
         "identifier": False,
@@ -71,6 +72,7 @@ DEFAULT_CONFIG = {
         "show_tool_use_status": False,
         "streaming_segmented": False,
         "max_agent_step": 30,
+        "tool_call_timeout": 60,
     },
     "provider_stt_settings": {
         "enable": False,
@@ -132,8 +134,11 @@ DEFAULT_CONFIG = {
     "persona": [],  # deprecated
     "timezone": "Asia/Shanghai",
     "callback_api_base": "",
-    "default_kb_collection": "",  # 默认知识库名称
+    "default_kb_collection": "",  # 默认知识库名称, 已经过时
     "plugin_set": ["*"],  # "*" 表示使用所有可用的插件, 空列表表示不使用任何插件
+    "kb_names": [],  # 默认知识库名称列表
+    "kb_fusion_top_k": 20,  # 知识库检索融合阶段返回结果数量
+    "kb_final_top_k": 5,  # 知识库检索最终返回结果数量
 }
 
 
@@ -160,10 +165,11 @@ CONFIG_METADATA_2 = {
                         "enable": False,
                         "appid": "",
                         "secret": "",
+                        "is_sandbox": False,
                         "callback_server_host": "0.0.0.0",
                         "port": 6196,
                     },
-                    "QQ 个人号(aiocqhttp)": {
+                    "QQ 个人号(OneBot v11)": {
                         "id": "default",
                         "type": "aiocqhttp",
                         "enable": False,
@@ -171,7 +177,7 @@ CONFIG_METADATA_2 = {
                         "ws_reverse_port": 6199,
                         "ws_reverse_token": "",
                     },
-                    "微信个人号(WeChatPadPro)": {
+                    "WeChatPadPro": {
                         "id": "wechatpadpro",
                         "type": "wechatpadpro",
                         "enable": False,
@@ -207,6 +213,18 @@ CONFIG_METADATA_2 = {
                         "callback_server_host": "0.0.0.0",
                         "port": 6195,
                     },
+                    "企业微信智能机器人": {
+                        "id": "wecom_ai_bot",
+                        "type": "wecom_ai_bot",
+                        "enable": True,
+                        "wecomaibot_init_respond_text": "💭 思考中...",
+                        "wecomaibot_friend_message_welcome_text": "",
+                        "wecom_ai_bot_name": "",
+                        "token": "",
+                        "encoding_aes_key": "",
+                        "callback_server_host": "0.0.0.0",
+                        "port": 6198,
+                    },
                     "飞书(Lark)": {
                         "id": "lark",
                         "type": "lark",
@@ -254,6 +272,14 @@ CONFIG_METADATA_2 = {
                         "misskey_default_visibility": "public",
                         "misskey_local_only": False,
                         "misskey_enable_chat": True,
+                        # download / security options
+                        "misskey_allow_insecure_downloads": False,
+                        "misskey_download_timeout": 15,
+                        "misskey_download_chunk_size": 65536,
+                        "misskey_max_download_bytes": None,
+                        "misskey_enable_file_upload": True,
+                        "misskey_upload_concurrency": 3,
+                        "misskey_upload_folder": "",
                     },
                     "Slack": {
                         "id": "slack",
@@ -278,8 +304,26 @@ CONFIG_METADATA_2 = {
                         "satori_heartbeat_interval": 10,
                         "satori_reconnect_delay": 5,
                     },
+                    # "WebChat": {
+                    #     "id": "webchat",
+                    #     "type": "webchat",
+                    #     "enable": False,
+                    #     "webchat_link_path": "",
+                    #     "webchat_present_type": "fullscreen",
+                    # },
                 },
                 "items": {
+                    # "webchat_link_path": {
+                    #     "description": "链接路径",
+                    #     "_special": "webchat_link_path",
+                    #     "type": "string",
+                    # },
+                    # "webchat_present_type": {
+                    #     "_special": "webchat_present_type",
+                    #     "description": "展现形式",
+                    #     "type": "string",
+                    #     "options": ["fullscreen", "embedded"],
+                    # },
                     "satori_api_base_url": {
                         "description": "Satori API 终结点",
                         "type": "string",
@@ -382,6 +426,41 @@ CONFIG_METADATA_2 = {
                         "type": "bool",
                         "hint": "启用后，机器人将会监听和响应私信聊天消息",
                     },
+                    "misskey_enable_file_upload": {
+                        "description": "启用文件上传到 Misskey",
+                        "type": "bool",
+                        "hint": "启用后，适配器会尝试将消息链中的文件上传到 Misskey。URL 文件会先尝试服务器端上传，异步上传失败时会回退到下载后本地上传。",
+                    },
+                    "misskey_allow_insecure_downloads": {
+                        "description": "允许不安全下载（禁用 SSL 验证）",
+                        "type": "bool",
+                        "hint": "当远端服务器存在证书问题导致无法正常下载时，自动禁用 SSL 验证作为回退方案。适用于某些图床的证书配置问题。启用有安全风险，仅在必要时使用。",
+                    },
+                    "misskey_download_timeout": {
+                        "description": "远端下载超时时间（秒）",
+                        "type": "int",
+                        "hint": "下载远程文件时的超时时间（秒），用于异步上传回退到本地上传的场景。",
+                    },
+                    "misskey_download_chunk_size": {
+                        "description": "流式下载分块大小（字节）",
+                        "type": "int",
+                        "hint": "流式下载和计算 MD5 时使用的每次读取字节数，过小会增加开销，过大会占用内存。",
+                    },
+                    "misskey_max_download_bytes": {
+                        "description": "最大允许下载字节数（超出则中止）",
+                        "type": "int",
+                        "hint": "如果希望限制下载文件的最大大小以防止 OOM，请填写最大字节数；留空或 null 表示不限制。",
+                    },
+                    "misskey_upload_concurrency": {
+                        "description": "并发上传限制",
+                        "type": "int",
+                        "hint": "同时进行的文件上传任务上限（整数，默认 3）。",
+                    },
+                    "misskey_upload_folder": {
+                        "description": "上传到网盘的目标文件夹 ID",
+                        "type": "string",
+                        "hint": "可选：填写 Misskey 网盘中目标文件夹的 ID，上传的文件将放置到该文件夹内。留空则使用账号网盘根目录。",
+                    },
                     "telegram_command_register": {
                         "description": "Telegram 命令注册",
                         "type": "bool",
@@ -433,24 +512,38 @@ CONFIG_METADATA_2 = {
                         "hint": "启用后，机器人可以接收到频道的私聊消息。",
                     },
                     "ws_reverse_host": {
-                        "description": "反向 Websocket 主机地址(AstrBot 为服务器端)",
+                        "description": "反向 Websocket 主机",
                         "type": "string",
-                        "hint": "aiocqhttp 适配器的反向 Websocket 服务器 IP 地址，不包含端口号。",
+                        "hint": "AstrBot 将作为服务器端。",
                     },
                     "ws_reverse_port": {
                         "description": "反向 Websocket 端口",
                         "type": "int",
-                        "hint": "aiocqhttp 适配器的反向 Websocket 端口。",
                     },
                     "ws_reverse_token": {
                         "description": "反向 Websocket Token",
                         "type": "string",
-                        "hint": "aiocqhttp 适配器的反向 Websocket Token。未设置则不启用 Token 验证。",
+                        "hint": "反向 Websocket Token。未设置则不启用 Token 验证。",
+                    },
+                    "wecom_ai_bot_name": {
+                        "description": "企业微信智能机器人的名字",
+                        "type": "string",
+                        "hint": "请务必填写正确，否则无法使用一些指令。",
+                    },
+                    "wecomaibot_init_respond_text": {
+                        "description": "企业微信智能机器人初始响应文本",
+                        "type": "string",
+                        "hint": "当机器人收到消息时，首先回复的文本内容。留空则使用默认值。",
+                    },
+                    "wecomaibot_friend_message_welcome_text": {
+                        "description": "企业微信智能机器人私聊欢迎语",
+                        "type": "string",
+                        "hint": "当用户当天进入智能机器人单聊会话，回复欢迎语，留空则不回复。",
                     },
                     "lark_bot_name": {
                         "description": "飞书机器人的名字",
                         "type": "string",
-                        "hint": "请务必填对，否则 @ 机器人将无法唤醒，只能通过前缀唤醒。",
+                        "hint": "请务必填写正确，否则 @ 机器人将无法唤醒，只能通过前缀唤醒。",
                     },
                     "discord_token": {
                         "description": "Discord Bot Token",
@@ -1324,6 +1417,7 @@ CONFIG_METADATA_2 = {
                         "description": "嵌入维度",
                         "type": "int",
                         "hint": "嵌入向量的维度。根据模型不同，可能需要调整，请参考具体模型的文档。此配置项请务必填写正确，否则将导致向量数据库无法正常工作。",
+                        "_special": "get_embedding_dim",
                     },
                     "embedding_model": {
                         "description": "嵌入模型",
@@ -1845,6 +1939,10 @@ CONFIG_METADATA_2 = {
                         "description": "工具调用轮数上限",
                         "type": "int",
                     },
+                    "tool_call_timeout": {
+                        "description": "工具调用超时时间（秒）",
+                        "type": "int",
+                    },
                 },
             },
             "provider_stt_settings": {
@@ -1967,6 +2065,9 @@ CONFIG_METADATA_2 = {
             "default_kb_collection": {
                 "type": "string",
             },
+            "kb_names": {"type": "list", "items": {"type": "string"}},
+            "kb_fusion_top_k": {"type": "int", "default": 20},
+            "kb_final_top_k": {"type": "int", "default": 5},
         },
     },
 }
@@ -2045,10 +2146,22 @@ CONFIG_METADATA_3 = {
                 "description": "知识库",
                 "type": "object",
                 "items": {
-                    "default_kb_collection": {
-                        "description": "默认使用的知识库",
-                        "type": "string",
+                    "kb_names": {
+                        "description": "知识库列表",
+                        "type": "list",
+                        "items": {"type": "string"},
                         "_special": "select_knowledgebase",
+                        "hint": "支持多选",
+                    },
+                    "kb_fusion_top_k": {
+                        "description": "融合检索结果数",
+                        "type": "int",
+                        "hint": "多个知识库检索结果融合后的返回结果数量",
+                    },
+                    "kb_final_top_k": {
+                        "description": "最终返回结果数",
+                        "type": "int",
+                        "hint": "从知识库中检索到的结果数量，越大可能获得越多相关信息，但也可能引入噪音。建议根据实际需求调整",
                     },
                 },
             },
@@ -2063,7 +2176,7 @@ CONFIG_METADATA_3 = {
                     "provider_settings.websearch_provider": {
                         "description": "网页搜索提供商",
                         "type": "string",
-                        "options": ["default", "tavily"],
+                        "options": ["default", "tavily", "baidu_ai_search"],
                     },
                     "provider_settings.websearch_tavily_key": {
                         "description": "Tavily API Key",
@@ -2074,6 +2187,14 @@ CONFIG_METADATA_3 = {
                             "provider_settings.websearch_provider": "tavily",
                         },
                     },
+                    "provider_settings.websearch_baidu_app_builder_key": {
+                        "description": "百度千帆智能云 APP Builder API Key",
+                        "type": "string",
+                        "hint": "参考：https://console.bce.baidu.com/iam/#/iam/apikey/list",
+                        "condition": {
+                            "provider_settings.websearch_provider": "baidu_ai_search",
+                        },
+                    },
                     "provider_settings.web_search_link": {
                         "description": "显示来源引用",
                         "type": "bool",
@@ -2109,6 +2230,10 @@ CONFIG_METADATA_3 = {
                         "description": "工具调用轮数上限",
                         "type": "int",
                     },
+                    "provider_settings.tool_call_timeout": {
+                        "description": "工具调用超时时间（秒）",
+                        "type": "int",
+                    },
                     "provider_settings.streaming_response": {
                         "description": "流式回复",
                         "type": "bool",
@@ -2130,7 +2255,7 @@ CONFIG_METADATA_3 = {
                     "provider_settings.wake_prefix": {
                         "description": "LLM 聊天额外唤醒前缀 ",
                         "type": "string",
-                        "hint": "例子: 如果唤醒前缀为 `/`, 额外聊天唤醒前缀为 `chat`，则需要 `/chat` 才会触发 LLM 请求。默认为空。",
+                        "hint": "如果唤醒前缀为 `/`, 额外聊天唤醒前缀为 `chat`，则需要 `/chat` 才会触发 LLM 请求。默认为空。",
                     },
                     "provider_settings.prompt_prefix": {
                         "description": "用户提示词",

astrbot/core/conversation_mgr.py

@@ -7,7 +7,7 @@ AstrBot 会话-对话管理器, 维护两个本地存储, 其中一个是 json
 
 import json
 from astrbot.core import sp
-from typing import Dict, List
+from typing import Dict, List, Callable, Awaitable
 from astrbot.core.db import BaseDatabase
 from astrbot.core.db.po import Conversation, ConversationV2
 
@@ -20,6 +20,38 @@ class ConversationManager:
         self.db = db_helper
         self.save_interval = 60  # 每 60 秒保存一次
 
+        # 会话删除回调函数列表（用于级联清理，如知识库配置）
+        self._on_session_deleted_callbacks: List[Callable[[str], Awaitable[None]]] = []
+
+    def register_on_session_deleted(
+        self, callback: Callable[[str], Awaitable[None]]
+    ) -> None:
+        """注册会话删除回调函数
+
+        其他模块可以注册回调来响应会话删除事件，实现级联清理。
+        例如：知识库模块可以注册回调来清理会话的知识库配置。
+
+        Args:
+            callback: 回调函数，接收会话ID (unified_msg_origin) 作为参数
+        """
+        self._on_session_deleted_callbacks.append(callback)
+
+    async def _trigger_session_deleted(self, unified_msg_origin: str) -> None:
+        """触发会话删除回调
+
+        Args:
+            unified_msg_origin: 会话ID
+        """
+        for callback in self._on_session_deleted_callbacks:
+            try:
+                await callback(unified_msg_origin)
+            except Exception as e:
+                from astrbot.core import logger
+
+                logger.error(
+                    f"会话删除回调执行失败 (session: {unified_msg_origin}): {e}"
+                )
+
     def _convert_conv_from_v2_to_v1(self, conv_v2: ConversationV2) -> Conversation:
         """将 ConversationV2 对象转换为 Conversation 对象"""
         created_at = int(conv_v2.created_at.timestamp())
@@ -106,6 +138,9 @@ class ConversationManager:
         self.session_conversations.pop(unified_msg_origin, None)
         await sp.session_remove(unified_msg_origin, "sel_conv_id")
 
+        # 触发会话删除回调（级联清理）
+        await self._trigger_session_deleted(unified_msg_origin)
+
     async def get_curr_conversation_id(self, unified_msg_origin: str) -> str | None:
         """获取会话当前的对话 ID