MaiBot 1.3.8__py3-none-any.whl

src/main.py

@@ -0,0 +1,300 @@
+from typing import TYPE_CHECKING, Any, Optional
+
+from rich.traceback import install
+
+import asyncio
+import sys
+import time
+
+from src.common.i18n import t
+from src.common.logger import get_logger
+from src.common.runtime_loop import set_main_loop
+from src.config.config import config_manager, global_config
+from src.manager.async_task_manager import async_task_manager
+from src.prompt.prompt_manager import prompt_manager
+
+# from src.api.main import start_api_server
+
+# 导入插件运行时
+# 导入消息API和traceback模块
+# from src.chat.utils.token_statistics import TokenStatisticsTask
+
+install(extra_lines=3)
+
+logger = get_logger("main")
+
+
+if TYPE_CHECKING:
+    from maim_message import MessageServer
+    from src.common.message_server.server import Server
+    from src.webui.webui_server import ThreadedWebUIServer
+
+
+async def _wait_for_plugin_runners_spawned(
+    plugin_runtime_manager: Any,
+    plugin_runtime_task: asyncio.Task[None],
+    timeout: float = 1.0,
+) -> None:
+    """让插件 Runner 子进程先拉起，以便和后续重初始化并行。"""
+
+    deadline = asyncio.get_running_loop().time() + timeout
+    while not plugin_runtime_task.done():
+        supervisors = list(getattr(plugin_runtime_manager, "supervisors", []))
+        if supervisors and all(getattr(supervisor, "_runner_process", None) is not None for supervisor in supervisors):
+            return
+        if asyncio.get_running_loop().time() >= deadline:
+            return
+        await asyncio.sleep(0.02)
+
+
+class MainSystem:
+    def __init__(self) -> None:
+        # 使用消息API替代直接的FastAPI实例
+        self.app: MessageServer | None = None
+        self.server: Server | None = None
+        self.webui_server: ThreadedWebUIServer | None = None  # 独立线程中的 WebUI 服务器
+        self._message_handlers_registered = False
+        self.watchdog_task: Optional[asyncio.Task[None]] = None
+
+    def _ensure_message_server(self) -> None:
+        """按需初始化消息 API，避免阻塞主启动链路的早期阶段。"""
+
+        if self.app is not None and self.server is not None:
+            return
+
+        from src.common.message_server import get_global_api
+        from src.common.message_server.server import get_global_server
+
+        self.app = get_global_api()
+        self.server = get_global_server()
+
+    def _register_message_handlers(self) -> None:
+        """注册主消息处理器；消息服务实际调度前完成即可。"""
+
+        if self._message_handlers_registered:
+            return
+
+        self._ensure_message_server()
+        if self.app is None:
+            raise RuntimeError("消息 API 初始化失败")
+
+        from src.chat.message_receive.bot import chat_bot
+
+        self.app.register_message_handler(chat_bot.message_process)
+        self.app.register_custom_message_handler("message_id_echo", chat_bot.echo_message_process)
+        self._message_handlers_registered = True
+
+    def _start_webui_server(self) -> None:
+        """启动独立线程中的 WebUI 服务器。"""
+        from src.config.config import global_config
+
+        if not global_config.webui.enabled:
+            logger.info(t("startup.webui_disabled"))
+            return
+
+        try:
+            from src.webui.webui_server import get_threaded_webui_server
+
+            self.webui_server = get_threaded_webui_server()
+            self.webui_server.start()
+
+        except Exception as e:
+            logger.error(t("startup.webui_server_init_failed", error=e))
+
+    async def initialize(self) -> None:
+        """初始化系统组件"""
+        logger.info(t("startup.waking_up", nickname=global_config.bot.nickname))
+
+        try:
+            from src.services.tool_record_cleanup_service import run_startup_tool_record_vacuum_if_needed
+
+            await asyncio.to_thread(run_startup_tool_record_vacuum_if_needed)
+            await self._init_components()
+        except Exception:
+            if self.webui_server:
+                await self.webui_server.shutdown()
+            raise
+
+        logger.info(t("startup.initialization_completed_banner", nickname=global_config.bot.nickname))
+
+    async def _init_components(self) -> None:
+        """初始化其他组件"""
+        init_start_time = time.time()
+
+        await config_manager.start_file_watcher()
+
+        # 插件 Runner 启动最重，尽早发起以便和后续初始化并行。
+        from src.plugin_runtime.integration import get_plugin_runtime_manager
+
+        plugin_runtime_manager = get_plugin_runtime_manager()
+        plugin_runtime_task = asyncio.create_task(plugin_runtime_manager.start(), name="plugin_runtime_start")
+        await _wait_for_plugin_runners_spawned(plugin_runtime_manager, plugin_runtime_task)
+
+        # 数据库启动维护已完成；让 WebUI 在线程中加载，与后续组件初始化并行，
+        # 无需等待全部插件就绪后才开放管理页面。
+        self._start_webui_server()
+
+        from src.A_memorix.host_service import a_memorix_host_service
+        from src.mcp_module.service import get_mcp_service
+        from src.services.expression_vector_service import expression_vector_service
+
+        a_memorix_host_service.register_config_reload_callback()
+        get_mcp_service().register_config_reload_callback()
+        expression_vector_service.start()
+        a_memorix_task = asyncio.create_task(a_memorix_host_service.start(), name="a_memorix_start")
+
+        await asyncio.sleep(0)
+        prompt_manager.load_prompts()
+
+        from src.emoji_system.emoji_manager import emoji_manager
+
+        emoji_load_task = asyncio.create_task(asyncio.to_thread(emoji_manager.load_emojis_from_db), name="emoji_load_from_db")
+
+        # 启动API服务器
+        # start_api_server()
+        # logger.info("API服务器启动成功")
+
+        try:
+            await asyncio.gather(plugin_runtime_task, a_memorix_task)
+            await emoji_load_task
+        except Exception:
+            for task in (plugin_runtime_task, a_memorix_task, emoji_load_task):
+                if not task.done():
+                    task.cancel()
+            await asyncio.gather(
+                plugin_runtime_task,
+                a_memorix_task,
+                emoji_load_task,
+                return_exceptions=True,
+            )
+            raise
+
+        # 初始化表情管理器
+        logger.info(t("startup.emoji_manager_initialized"))
+
+        # 初始化聊天管理器
+        from src.chat.message_receive.chat_manager import chat_manager
+        from src.services.memory_flow_service import memory_automation_service
+
+        await chat_manager.initialize()
+        asyncio.create_task(chat_manager.regularly_save_sessions())
+
+        logger.info(t("startup.chat_manager_initialized"))
+        await memory_automation_service.start()
+
+        # await asyncio.sleep(0.5) #防止logger输出飞了
+
+        # 触发 ON_START 事件，事件总线会统一桥接到 IPC 插件运行时。
+        from src.core.event_bus import event_bus
+        from src.core.types import EventType
+
+        await event_bus.emit(event_type=EventType.ON_START)
+        # logger.info("已触发 ON_START 事件")
+
+        from src.chat.utils.statistic import OnlineTimeRecordTask, StatisticOutputTask
+
+        # 添加在线时间统计任务
+        await async_task_manager.add_task(OnlineTimeRecordTask())
+
+        # 添加统计信息输出任务
+        await async_task_manager.add_task(StatisticOutputTask())
+
+        # 添加遥测心跳与统计上传任务
+        from src.common.remote import TelemetryHeartBeatTask, TelemetryStatsUploadTask
+
+        await async_task_manager.add_task(TelemetryHeartBeatTask())
+        await async_task_manager.add_task(TelemetryStatsUploadTask())
+
+        # 主循环卡顿看门狗；WebUI 循环另有一份，挂在 WebUI 服务器启动处。
+        from src.common.event_loop_watchdog import start_watchdog
+
+        self.watchdog_task = start_watchdog("main")
+
+        try:
+            init_time = int(1000 * (time.time() - init_start_time))
+            logger.info(t("startup.initialization_completed_cycles", init_time=init_time))
+        except Exception as e:
+            logger.error(t("startup.brain_external_world_failed", error=e))
+            raise
+
+    async def schedule_tasks(self) -> None:
+        """调度定时任务"""
+        try:
+            from src.chat.image_system.image_cache_cleanup import periodic_image_cache_cleanup
+            from src.emoji_system.emoji_cache_cleanup import periodic_emoji_cache_cleanup
+            from src.emoji_system.emoji_manager import emoji_manager
+            from src.maisaka.display.prompt_preview_logger import PromptPreviewLogger
+            from src.services.image_path_maintenance_service import (
+                run_image_path_maintenance_background,
+                should_schedule_image_path_maintenance_background,
+            )
+            from src.webui.routers.data_transfer import periodic_transfer_temp_cleanup
+
+            # 在独立线程中巡检推理图片，空闲时也能清理旧版本遗留的孤立缓存。
+            PromptPreviewLogger.start()
+            self._register_message_handlers()
+            if self.app is None or self.server is None:
+                raise RuntimeError("消息服务未初始化")
+
+            tasks = [
+                emoji_manager.periodic_emoji_maintenance(),
+                periodic_emoji_cache_cleanup(),
+                periodic_image_cache_cleanup(),
+                periodic_transfer_temp_cleanup(),
+                self.app.run(),
+                self.server.run(),
+            ]
+            if global_config.debug.enable_console_input:
+                if sys.stdin.isatty():
+                    from src.cli.bot_console import BotConsole
+
+                    logger.info("已启用终端输入，可输入普通消息或 /clear、/pm 等指令；输入 exit() 关闭终端输入")
+                    tasks.append(BotConsole().run())
+                else:
+                    logger.warning("终端输入已配置为启用，但当前 stdin 不是交互式终端，已跳过")
+            image_path_maintenance_needed = await asyncio.to_thread(should_schedule_image_path_maintenance_background)
+            if image_path_maintenance_needed:
+                tasks.append(run_image_path_maintenance_background())
+
+            await asyncio.gather(*tasks)
+        except asyncio.CancelledError:
+            logger.info(t("startup.schedule_cancelled"))
+            raise
+
+
+async def main() -> None:
+    """主函数"""
+    set_main_loop(asyncio.get_running_loop())
+    system = MainSystem()
+    try:
+        await system.initialize()
+        await system.schedule_tasks()
+    finally:
+        if system.webui_server:
+            await system.webui_server.shutdown()
+        if system.watchdog_task is not None:
+            system.watchdog_task.cancel()
+            system.watchdog_task = None
+        from src.A_memorix.host_service import a_memorix_host_service
+        from src.chat.image_system.image_manager import image_manager
+        from src.emoji_system.emoji_manager import emoji_manager
+        from src.mcp_module.service import get_mcp_service
+        from src.plugin_runtime.integration import get_plugin_runtime_manager
+        from src.services.expression_vector_service import expression_vector_service
+        from src.services.memory_flow_service import memory_automation_service
+
+        emoji_manager.shutdown()
+        await image_manager.shutdown()
+        await expression_vector_service.stop()
+        await memory_automation_service.shutdown()
+        await a_memorix_host_service.stop()
+        await get_plugin_runtime_manager().bridge_event("on_stop")
+        await get_plugin_runtime_manager().stop()
+        await async_task_manager.stop_and_wait_all_tasks()
+        await get_mcp_service().close()
+        await config_manager.stop_file_watcher()
+        set_main_loop(None)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/maisaka/attention_drift.py

@@ -0,0 +1,116 @@
+from typing import Mapping
+
+from src.common.i18n import get_locale
+from src.config.config import global_config
+
+
+DRIFT_LEVEL_RULES = {
+    "subtle": {
+        "zh-CN": "漂移档位：轻微漂移。只在最近消息里出现非常自然的触发点时，轻轻联想一句；大多数时候继续当前话题。",
+        "en-US": "Drift level: subtle. Add a small aside only when recent messages provide a very natural hook; usually stay on the current topic.",
+        "ja-JP": "ドリフト段階：軽め。直近メッセージにとても自然なきっかけがある時だけ軽く一言連想し、基本は現在の話題に沿ってください。",
+    },
+    "active": {
+        "zh-CN": "漂移档位：活跃联想。可以主动抓住新鲜、好笑、反差强或熟悉的细节接话，但回复仍要清楚、短促、能被最近消息解释。",
+        "en-US": "Drift level: active. You may actively pick up fresh, funny, contrasting, or familiar details, but the reply must stay clear, short, and explainable from recent messages.",
+        "ja-JP": "ドリフト段階：活発な連想。新鮮、面白い、ギャップの強い、見知った細部を拾ってもよいですが、返信は明確で短く、直近文脈から説明できるものにしてください。",
+    },
+    "scattered": {
+        "zh-CN": "漂移档位：明显发散。你可以明显地被支线、关键词、熟人语气或反差点勾走，先接住那个点再回到正题；回复里允许出现一次可理解的突然拐弯。",
+        "en-US": "Drift level: scattered. You may noticeably get pulled by side topics, keywords, familiar voices, or contrasts; catch that detail first, then return to the point. One understandable sudden turn is allowed in a reply.",
+        "ja-JP": "ドリフト段階：はっきり発散。支線、キーワード、見知った口調、ギャップに明確に引かれてよく、その点を先に拾ってから本題へ戻ってください。返信内で一度なら理解できる急な曲がり方をしてかまいません。",
+    },
+    "wild": {
+        "zh-CN": "漂移档位：强烈跳跃。你可以先被最有趣的细节劫走一下，出现短促插话、突然联想或半路拐弯；但每轮最多一次明显跳跃，不能无视明确提问，最后要让人看得出你在接哪条消息。",
+        "en-US": "Drift level: wild. You may first get hijacked by the most interesting detail, with a short interjection, sudden association, or mid-reply turn. Allow at most one obvious jump per turn, do not ignore direct questions, and leave the reply traceable to a recent message.",
+        "ja-JP": "ドリフト段階：強めのジャンプ。いちばん面白い細部に一瞬さらわれ、短い差し込み、突然の連想、途中の方向転換をしてもかまいません。ただし一回の返信で明確なジャンプは最大一度、明確な質問は無視せず、どの直近メッセージを受けたのか分かるようにしてください。",
+    },
+}
+
+ANCHOR_POLICY_RULES = {
+    "strict": {
+        "zh-CN": "回钩策略：严格回钩。联想或短反应之后，要立刻回到当前正在聊的主题或被回复对象。",
+        "en-US": "Anchor policy: strict. After an aside or short reaction, immediately return to the current topic or reply target.",
+        "ja-JP": "アンカー方針：厳格。連想や短い反応の後は、すぐ現在の話題または返信対象へ戻ってください。",
+    },
+    "balanced": {
+        "zh-CN": "回钩策略：自然回钩。可以短暂沿着支线说一句，但通常要让结尾或主要意思回到当前聊天。",
+        "en-US": "Anchor policy: balanced. You may briefly follow a side association, but usually bring the ending or main point back to the current chat.",
+        "ja-JP": "アンカー方針：自然。短く寄り道してもよいですが、基本的には結末や主旨を現在の会話へ戻してください。",
+    },
+    "loose": {
+        "zh-CN": "回钩策略：宽松关联。可以保留更自由的相关联想，但不能凭空换话题，也不能无视明确提问。",
+        "en-US": "Anchor policy: loose. You may keep a freer related association, but do not switch topics out of nowhere or ignore direct questions.",
+        "ja-JP": "アンカー方針：ゆるめ。より自由な関連連想を残してもよいですが、唐突に話題を変えたり、明確な質問を無視したりしないでください。",
+    },
+}
+
+REACTION_STYLE_RULES = {
+    "reserved": {
+        "zh-CN": "短反应风格：少量短反应。只有特别适合接话时，才用一句很短的反应开头。",
+        "en-US": "Short reaction style: reserved. Start with a very short reaction only when it fits especially well.",
+        "ja-JP": "短い反応スタイル：控えめ。特に合う時だけ、とても短い反応から始めてください。",
+    },
+    "natural": {
+        "zh-CN": "短反应风格：自然短反应。可以偶尔先用短句、吐槽或语气词接住话题，再继续正常回复。",
+        "en-US": "Short reaction style: natural. You may occasionally start with a short phrase, quip, or interjection before continuing normally.",
+        "ja-JP": "短い反応スタイル：自然。たまに短い一言、ツッコミ、間投詞で受けてから普通に返信してもかまいません。",
+    },
+    "lively": {
+        "zh-CN": "短反应风格：活泼短反应。更容易先用短促反应开头，但不要把回复拆得太碎，也不要每次都这样。",
+        "en-US": "Short reaction style: lively. You are more likely to open with a short reaction, but do not fragment the reply too much or do it every time.",
+        "ja-JP": "短い反応スタイル：活発。短い反応から入りやすくしてよいですが、返信を細かく分けすぎず、毎回そうしないでください。",
+    },
+}
+
+
+def _localized_text(texts: Mapping[str, str]) -> str:
+    locale = get_locale()
+    return texts.get(locale, texts["zh-CN"])
+
+
+def build_attention_drift_prompt_block() -> str:
+    """构建注意力漂移模式的 prompt 注入块。"""
+
+    config = global_config.experimental.attention_drift
+    if not config.enabled:
+        return ""
+
+    drift_rule = _localized_text(DRIFT_LEVEL_RULES[config.drift_level])
+    anchor_rule = _localized_text(ANCHOR_POLICY_RULES[config.anchor_policy])
+    reaction_rule = _localized_text(REACTION_STYLE_RULES[config.reaction_style])
+
+    return _localized_text(
+        {
+            "en-US": (
+                "Attention drift style:\n"
+                "- You may be briefly attracted by fresh, funny, contrasting, or personally familiar details in the chat, but every drift must have a clear hook in recent messages.\n"
+                "- Drift is not just changing the topic: grab a standout hook first, then make a brief turn that feels like a sudden spark of thought.\n"
+                "- Prefer lively association over real inefficiency: do not deliberately delay, ignore tasks, or scatter tool use just to act distracted.\n"
+                "- Do not medicalize this style, do not call yourself ADHD, and do not announce that you are distracted.\n"
+                f"- {drift_rule}\n"
+                f"- {anchor_rule}\n"
+                f"- {reaction_rule}\n"
+            ),
+            "ja-JP": (
+                "注意ドリフトスタイル：\n"
+                "- チャット内の新鮮、面白い、ギャップの強い、または見知った要素に一時的に引かれてもよいですが、ドリフトには必ず直近メッセージ内の明確なきっかけが必要です。\n"
+                "- ドリフトは単なる話題変更ではありません。目立つきっかけを先に拾い、思考が急に光ったような短い曲がり方にしてください。\n"
+                "- 本当に非効率にするのではなく、活発な連想として表現してください。気が散ったふりのために遅延、タスク無視、ツール使用の散乱をしないでください。\n"
+                "- このスタイルを医学化せず、自分を ADHD と呼ばず、気が散っていると宣言しないでください。\n"
+                f"- {drift_rule}\n"
+                f"- {anchor_rule}\n"
+                f"- {reaction_rule}\n"
+            ),
+            "zh-CN": (
+                "注意力漂移风格：\n"
+                "- 你可以短暂被聊天里新鲜、好笑、反差强或熟悉的人和梗吸引，但每次漂移都必须能从最近消息里找到明确触发点。\n"
+                "- 漂移不是单纯换话题，而是先抓一个突出的触发点，再用很短的拐弯制造“脑子突然亮了一下”的感觉。\n"
+                "- 表现活跃联想，不要真的降效；不要为了显得分心而故意拖延、忽略任务或打散工具调用。\n"
+                "- 不要医学化描述这种风格，不要自称 ADHD，也不要主动声明自己分心。\n"
+                f"- {drift_rule}\n"
+                f"- {anchor_rule}\n"
+                f"- {reaction_rule}\n"
+            ),
+        }
+    )

src/maisaka/builtin_tool/__init__.py

@@ -0,0 +1,236 @@
+"""Maisaka 内置工具聚合入口。"""
+
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional
+
+from src.config.config import global_config
+from src.core.tooling import ToolAvailabilityContext, ToolExecutionContext, ToolExecutionResult, ToolInvocation, ToolSpec
+from src.llm_models.payload_content.tool_option import ToolDefinitionInput
+from src.maisaka.focus import focus_mode_manager
+
+from .context import BuiltinToolRuntimeContext
+from .fetch_history import get_tool_spec as get_fetch_history_tool_spec
+from .fetch_history import handle_tool as handle_fetch_history_tool
+from .query_memory import get_tool_spec as get_query_memory_tool_spec
+from .query_memory import handle_tool as handle_query_memory_tool
+from .query_image_memory import get_tool_spec as get_query_image_memory_tool_spec
+from .query_image_memory import handle_tool as handle_query_image_memory_tool
+from .query_person_profile import get_tool_spec as get_query_person_profile_tool_spec
+from .query_person_profile import handle_tool as handle_query_person_profile_tool
+from .read_tool_result import get_tool_spec as get_read_tool_result_tool_spec
+from .read_tool_result import handle_tool as handle_read_tool_result_tool
+from .reply import get_tool_spec as get_reply_tool_spec
+from .reply import handle_tool as handle_reply_tool
+from .send_emoji import get_tool_spec as get_send_emoji_tool_spec
+from .send_emoji import handle_tool as handle_send_emoji_tool
+from .show_emoji_list import get_tool_spec as get_show_emoji_list_tool_spec
+from .show_emoji_list import handle_tool as handle_show_emoji_list_tool
+from .subagent import get_status_tool_spec as get_subagent_status_tool_spec
+from .subagent import get_stop_tool_spec as get_subagent_stop_tool_spec
+from .subagent import get_tool_spec as get_subagent_tool_spec
+from .subagent import handle_status_tool as handle_subagent_status_tool
+from .subagent import handle_stop_tool as handle_subagent_stop_tool
+from .subagent import handle_tool as handle_subagent_tool
+from .switch_chat import get_tool_spec as get_switch_chat_tool_spec
+from .switch_chat import handle_tool as handle_switch_chat_tool
+from .tool_search import get_tool_spec as get_tool_search_tool_spec
+from .tool_search import handle_tool as handle_tool_search_tool
+from .view_forward_message import get_tool_spec as get_view_forward_message_tool_spec
+from .view_forward_message import handle_tool as handle_view_forward_message_tool
+from .wait import get_tool_spec as get_wait_tool_spec
+from .wait import handle_tool as handle_wait_tool
+
+BuiltinToolHandler = Callable[[ToolInvocation, Optional[ToolExecutionContext]], Awaitable[ToolExecutionResult]]
+BuiltinToolRawHandler = Callable[
+    [BuiltinToolRuntimeContext, ToolInvocation, Optional[ToolExecutionContext]],
+    Awaitable[ToolExecutionResult],
+]
+BuiltinToolStage = Literal["action", "both"]
+BuiltinToolVisibility = Literal["visible", "deferred", "hidden"]
+BuiltinToolChatScope = Literal["all", "group", "private"]
+
+
+@dataclass(frozen=True)
+class BuiltinToolEntry:
+    """内置工具目录项，集中声明工具所属阶段与默认可见性。"""
+
+    name: str
+    get_spec: Callable[[], ToolSpec]
+    handle_tool: BuiltinToolRawHandler
+    stage: BuiltinToolStage
+    visibility: BuiltinToolVisibility = "visible"
+    chat_scope: BuiltinToolChatScope = "all"
+
+    def build_spec(self, context: Optional[ToolAvailabilityContext] = None) -> ToolSpec:
+        """生成带统一可见性元数据的工具声明。"""
+
+        tool_spec = deepcopy(get_reply_tool_spec(context) if self.name == "reply" else self.get_spec())
+        tool_spec.metadata["builtin_stage"] = self.stage
+        tool_spec.metadata["visibility"] = self.visibility
+        return tool_spec
+
+
+def _get_query_memory_tool_spec() -> ToolSpec:
+    """根据配置生成 query_memory 工具声明。"""
+
+    return get_query_memory_tool_spec(enabled=bool(global_config.a_memorix.integration.enable_memory_query_tool))
+
+
+def _get_query_person_profile_tool_spec() -> ToolSpec:
+    """根据配置生成 query_person_profile 工具声明。"""
+
+    return get_query_person_profile_tool_spec(
+        enabled=bool(global_config.a_memorix.integration.enable_person_profile_query_tool)
+    )
+
+
+def _get_query_image_memory_tool_spec() -> ToolSpec:
+    return get_query_image_memory_tool_spec(enabled=bool(global_config.a_memorix.image_memory.enabled))
+
+
+BUILTIN_TOOL_ENTRIES: List[BuiltinToolEntry] = [
+    BuiltinToolEntry("wait", get_wait_tool_spec, handle_wait_tool, stage="both"),
+    BuiltinToolEntry("reply", get_reply_tool_spec, handle_reply_tool, stage="action"),
+    BuiltinToolEntry(
+        "view_forward_message",
+        get_view_forward_message_tool_spec,
+        handle_view_forward_message_tool,
+        stage="action",
+        visibility="deferred",
+    ),
+    BuiltinToolEntry("query_memory", _get_query_memory_tool_spec, handle_query_memory_tool, stage="action"),
+    BuiltinToolEntry(
+        "query_image_memory",
+        _get_query_image_memory_tool_spec,
+        handle_query_image_memory_tool,
+        stage="action",
+    ),
+    BuiltinToolEntry(
+        "query_person_profile",
+        _get_query_person_profile_tool_spec,
+        handle_query_person_profile_tool,
+        stage="action",
+    ),
+    BuiltinToolEntry("send_emoji", get_send_emoji_tool_spec, handle_send_emoji_tool, stage="action"),
+    BuiltinToolEntry("show_emoji_list", get_show_emoji_list_tool_spec, handle_show_emoji_list_tool, stage="action"),
+    BuiltinToolEntry("tool_search", get_tool_search_tool_spec, handle_tool_search_tool, stage="action"),
+    BuiltinToolEntry("subagent", get_subagent_tool_spec, handle_subagent_tool, stage="action"),
+    BuiltinToolEntry("subagent_status", get_subagent_status_tool_spec, handle_subagent_status_tool, stage="action"),
+    BuiltinToolEntry("subagent_stop", get_subagent_stop_tool_spec, handle_subagent_stop_tool, stage="action"),
+    BuiltinToolEntry(
+        "read_tool_result",
+        get_read_tool_result_tool_spec,
+        handle_read_tool_result_tool,
+        stage="action",
+    ),
+    BuiltinToolEntry(
+        "fetch_history",
+        get_fetch_history_tool_spec,
+        handle_fetch_history_tool,
+        stage="action",
+    ),
+    BuiltinToolEntry("switch_chat", get_switch_chat_tool_spec, handle_switch_chat_tool, stage="action"),
+]
+
+
+def _get_builtin_tool_entries(
+    *,
+    stage: Optional[BuiltinToolStage] = None,
+    visibility: Optional[BuiltinToolVisibility] = None,
+    context: Optional[ToolAvailabilityContext] = None,
+) -> List[BuiltinToolEntry]:
+    """按阶段与可见性筛选内置工具目录项。"""
+
+    entries = BUILTIN_TOOL_ENTRIES
+    entries = [entry for entry in entries if _is_builtin_tool_enabled_by_config(entry)]
+    if stage is not None:
+        entries = [entry for entry in entries if entry.stage in {stage, "both"}]
+    if visibility is not None:
+        entries = [entry for entry in entries if entry.visibility == visibility]
+    if context is not None:
+        entries = [entry for entry in entries if _is_builtin_tool_available(entry, context)]
+    return entries
+
+
+def _is_builtin_tool_enabled_by_config(entry: BuiltinToolEntry) -> bool:
+    """根据全局配置判断内置工具是否应暴露。"""
+
+    if entry.name == "show_emoji_list":
+        return global_config.emoji.use_new_send_logic
+    if entry.name == "send_emoji":
+        return not global_config.emoji.use_new_send_logic
+    if entry.name in {"fetch_history", "switch_chat"}:
+        return bool(global_config.experimental.focus_mode)
+    if entry.name == "subagent":
+        return global_config.experimental.planner_subagent
+    if entry.name in {"subagent_status", "subagent_stop"}:
+        # 只有后台子代理才有需要查看和终止的任务
+        return global_config.experimental.planner_subagent and global_config.experimental.advanced_sub_agent
+    if entry.name == "read_tool_result":
+        # 只有开启超长结果整理时才会有被暂存的原文可读
+        return global_config.experimental.tool_result_condense
+    return True
+
+
+def _is_builtin_tool_available(entry: BuiltinToolEntry, context: ToolAvailabilityContext) -> bool:
+    """判断内置工具是否适用于当前聊天。"""
+
+    if entry.name in {"fetch_history", "switch_chat"}:
+        if context.session_id:
+            return focus_mode_manager.is_enabled_for_session(
+                context.session_id,
+                is_group_chat=context.is_group_chat,
+            )
+        if not focus_mode_manager.is_enabled_for_chat(is_group_chat=context.is_group_chat):
+            return False
+    if entry.chat_scope == "all":
+        return True
+    if entry.chat_scope == "group":
+        return context.is_group_chat is True
+    if entry.chat_scope == "private":
+        return context.is_group_chat is False
+    return True
+
+
+def get_builtin_tool_visibility(tool_spec: ToolSpec) -> BuiltinToolVisibility:
+    """读取工具声明里的可见性。"""
+
+    raw_visibility = str(tool_spec.metadata.get("visibility") or "").strip()
+    if raw_visibility == "deferred":
+        return "deferred"
+    if raw_visibility == "hidden":
+        return "hidden"
+    return "visible"
+
+
+def is_builtin_tool_in_action_stage(tool_spec: ToolSpec) -> bool:
+    """判断内置工具是否属于 Action Loop 阶段。"""
+
+    return str(tool_spec.metadata.get("builtin_stage") or "").strip() in {"action", "both"}
+
+
+def get_all_builtin_tool_specs(context: Optional[ToolAvailabilityContext] = None) -> List[ToolSpec]:
+    """获取全部内置工具声明。"""
+
+    return [entry.build_spec(context) for entry in _get_builtin_tool_entries(context=context)]
+
+
+def get_builtin_tools(context: Optional[ToolAvailabilityContext] = None) -> List[ToolDefinitionInput]:
+    """获取默认暴露给模型层的内置工具定义。"""
+
+    tool_specs = [
+        entry.build_spec(context)
+        for entry in _get_builtin_tool_entries(stage="action", visibility="visible", context=context)
+    ]
+    return [tool_spec.to_llm_definition() for tool_spec in tool_specs if tool_spec.enabled]
+
+
+def build_builtin_tool_handlers(tool_ctx: BuiltinToolRuntimeContext) -> Dict[str, BuiltinToolHandler]:
+    """构建内置工具处理器映射。"""
+
+    return {
+        entry.name: lambda invocation, context=None, entry=entry: entry.handle_tool(tool_ctx, invocation, context)
+        for entry in BUILTIN_TOOL_ENTRIES
+    }