RuoYi-Vue3-FastAPI/ruoyi-fastapi-backend/plugins/core/runtime/startup.py

import asyncio
import sys
from collections.abc import Callable
from dataclasses import replace
from pathlib import Path
from typing import Any

from fastapi import FastAPI

from common.router import auto_register_controller_files
from config.database import AsyncSessionLocal
from config.env import AppConfig
from config.get_db import get_db
from plugins.core.discovery.registry import PluginRegistry, RegisteredPlugin
from plugins.core.lifecycle.migration import (
    PluginMigrationHistoryRecord,
    PluginMigrationHistoryStore,
    PluginMigrationRunner,
)
from plugins.core.lifecycle.seed import PluginSeedRunner
from plugins.core.runtime.bootstrap import PluginRuntimeBuilder
from plugins.core.runtime.hooks import PluginHookRunner
from plugins.core.runtime.route_guard import (
    PluginEnabledDependency,
    PluginRouteStateGateway,
    UnavailablePluginRouteStateGateway,
)
from plugins.core.runtime.service.gateway import DefaultPluginCommandRunnerGateway, PluginCommandRunnerGateway
from plugins.core.runtime.startup_gateway import (
    PluginStartupManagementGateway,
    UnavailablePluginStartupManagementGateway,
)
from plugins.core.validation.dependencies import (
    PLUGIN_STARTUP_DEPENDENCY_ERROR_PREFIX,
    DependencyCheckResult,
    PluginDependencyInstallPlanner,
    PythonDependencyInspector,
)
from plugins.core.validation.structure import PluginStructureChecker
from utils.log_util import logger


class PluginStartupMigrationHistoryStore(PluginMigrationHistoryStore):
    """
    启动期插件 migration 历史存储适配器。
    """

    def __init__(self, management_gateway: PluginStartupManagementGateway, async_session_local: Any = None) -> None:
        """
        初始化启动期 migration 历史存储。

        :param management_gateway: 插件启动期管理端口
        :param async_session_local: 独立数据库会话工厂
        :return: None
        """
        self.management_gateway = management_gateway
        self.async_session_local = async_session_local

    async def get_record(
        self,
        query_db: Any,
        plugin_id: str,
        migration_path: str,
    ) -> PluginMigrationHistoryRecord | None:
        """
        获取 migration 执行历史。

        :param query_db: orm对象
        :param plugin_id: 插件ID
        :param migration_path: migration 相对路径
        :return: migration 执行历史
        """
        plugin_migration = await self.management_gateway.get_plugin_migration(query_db, plugin_id, migration_path)
        if not plugin_migration:
            return None
        return PluginMigrationHistoryRecord(
            checksum=plugin_migration.migration_checksum,
            status=getattr(plugin_migration, 'status', 'success'),
            error_message=getattr(plugin_migration, 'error_message', None),
        )

    async def record_running(
        self,
        query_db: Any,
        plugin_id: str,
        migration_path: str,
        checksum: str,
        version: str,
        statement_count: int,
    ) -> None:
        """
        记录 migration 开始执行。

        :param query_db: orm对象
        :param plugin_id: 插件ID
        :param migration_path: migration 相对路径
        :param checksum: 内容校验值
        :param version: 执行时插件版本
        :param statement_count: SQL 语句数量
        :return: None
        """
        await self._add_plugin_migration(
            query_db,
            self.management_gateway.build_migration_record(
                plugin_id,
                migration_path,
                checksum,
                version,
                statement_count,
                'running',
            ),
        )

    async def record_success(
        self,
        query_db: Any,
        plugin_id: str,
        migration_path: str,
        checksum: str,
        version: str,
        statement_count: int,
    ) -> None:
        """
        记录 migration 成功执行历史。

        :param query_db: orm对象
        :param plugin_id: 插件ID
        :param migration_path: migration 相对路径
        :param checksum: 内容校验值
        :param version: 执行时插件版本
        :param statement_count: SQL 语句数量
        :return: None
        """
        await self._add_plugin_migration(
            query_db,
            self.management_gateway.build_migration_record(
                plugin_id,
                migration_path,
                checksum,
                version,
                statement_count,
            ),
        )

    async def record_failure(
        self,
        query_db: Any,
        plugin_id: str,
        migration_path: str,
        checksum: str,
        version: str,
        statement_count: int,
        error_message: str,
    ) -> None:
        """
        记录 migration 执行失败历史。

        :param query_db: orm对象
        :param plugin_id: 插件ID
        :param migration_path: migration 相对路径
        :param checksum: 内容校验值
        :param version: 执行时插件版本
        :param statement_count: SQL 语句数量
        :param error_message: 失败错误信息
        :return: None
        """
        await self._add_plugin_migration(
            query_db,
            self.management_gateway.build_migration_record(
                plugin_id,
                migration_path,
                checksum,
                version,
                statement_count,
                'failed',
                error_message,
            ),
        )

    async def _add_plugin_migration(self, query_db: Any, plugin_migration: Any) -> None:
        """
        写入 migration 历史，优先使用独立会话提交。

        :param query_db: 当前启动期 orm对象
        :param plugin_migration: migration 历史模型
        :return: None
        """
        if self.async_session_local is None:
            await self.management_gateway.add_plugin_migration(query_db, plugin_migration)
            return

        async with self.async_session_local() as session:
            await self.management_gateway.add_plugin_migration(session, plugin_migration)
            await session.commit()


class PluginRuntimeStartupManager:
    """
    插件运行时启动协调器。

    将插件发现、实体导入、资源安装、路由注册和生命周期钩子从应用入口中隔离出来，
    让 server.py 只保留高层启动顺序。
    """

    def __init__(
        self,
        builder: PluginRuntimeBuilder | None = None,
        management_gateway: PluginStartupManagementGateway | None = None,
        route_state_gateway: PluginRouteStateGateway | None = None,
        python_dependency_inspector: PythonDependencyInspector | None = None,
        python_dependency_inspector_factory: Callable[[], PythonDependencyInspector] | None = None,
        command_runner_gateway: PluginCommandRunnerGateway | None = None,
        default_enabled_builtin_plugin_ids: set[str] | None = None,
    ) -> None:
        """
        初始化插件运行时启动协调器。

        :param builder: 插件运行时构建器
        :param management_gateway: 插件启动期管理端口
        :param route_state_gateway: 插件路由状态读取端口
        :param python_dependency_inspector: Python 依赖检查器
        :param python_dependency_inspector_factory: Python 依赖检查器工厂
        :param command_runner_gateway: 插件命令执行网关
        :param default_enabled_builtin_plugin_ids: 首次启动默认安装启用的内置插件 ID 集合
        :return: None
        """
        self.builder = builder or PluginRuntimeBuilder()
        self.management_gateway = management_gateway or UnavailablePluginStartupManagementGateway()
        self.route_state_gateway = route_state_gateway or UnavailablePluginRouteStateGateway()
        self.python_dependency_inspector_factory = python_dependency_inspector_factory or PythonDependencyInspector
        self.python_dependency_inspector = python_dependency_inspector or self.python_dependency_inspector_factory()
        self.command_runner_gateway = command_runner_gateway or DefaultPluginCommandRunnerGateway()
        self.default_enabled_builtin_plugin_ids = (
            self.parse_default_enabled_builtin_plugin_ids(AppConfig.app_default_enabled_plugins)
            if default_enabled_builtin_plugin_ids is None
            else set(default_enabled_builtin_plugin_ids)
        )

    def bind_app(self, app: FastAPI) -> None:
        """
        绑定插件运行时对象到 FastAPI state。

        :param app: FastAPI对象
        :return: None
        """
        app.state.plugin_runtime_startup = self
        app.state.plugin_runtime_builder = self.builder
        if not hasattr(app.state, 'plugin_registry'):
            app.state.plugin_registry = self.builder.build_registry()
        if not hasattr(app.state, 'plugin_routes_registered'):
            app.state.plugin_routes_registered = False

    def import_builtin_entities(self) -> None:
        """
        导入内置业务模块实体。

        :return: None
        """
        self.builder.import_builtin_entities()

    @staticmethod
    def parse_default_enabled_builtin_plugin_ids(plugin_ids: str) -> set[str]:
        """
        解析默认启用内置插件配置。

        :param plugin_ids: 逗号分隔的插件 ID 配置
        :return: 插件 ID 集合
        """
        return {plugin_id.strip() for plugin_id in plugin_ids.split(',') if plugin_id.strip()}

    async def prepare_enabled_plugins(self, app: FastAPI, *, startup_write_enabled: bool = True) -> None:
        """
        准备启用插件运行时实体。

        :param app: FastAPI对象
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: None
        """
        default_dependency_failed_plugin_ids: set[str] = set()
        if startup_write_enabled:
            default_dependency_failed_plugin_ids = await self.sync_default_enabled_builtin_plugin_install_states()
        await self.load_registry_from_database(app)
        dependency_failed_plugin_ids = await self.check_enabled_plugin_python_dependencies(
            app,
            startup_write_enabled=startup_write_enabled,
        )
        app.state.plugin_dependency_failed_plugin_ids = (
            default_dependency_failed_plugin_ids | dependency_failed_plugin_ids
        )
        self.disable_runtime_plugins(app, dependency_failed_plugin_ids)
        import_failed_plugin_ids = await self.import_enabled_plugin_entities(
            app,
            startup_write_enabled=startup_write_enabled,
        )
        self.disable_runtime_plugins(app, import_failed_plugin_ids)

    async def requires_startup_write(self) -> bool:
        """
        判断当前数据库状态是否要求重新执行启动期全局写入。

        Redis ready 标记用于协调同一代际的并发 worker，但它的生命周期可能长于
        数据库本身。数据库被重建、清空或恢复旧快照后，默认启用插件可能重新缺少
        安装状态，此时不能复用旧 ready 标记。

        :return: 是否需要重新执行启动期写入
        """
        if not self.default_enabled_builtin_plugin_ids:
            return False

        discovered_plugin_ids = {
            plugin.manifest.id
            for plugin in self.builder.discover_plugins()
            if plugin.manifest.id in self.default_enabled_builtin_plugin_ids
        }
        if not discovered_plugin_ids:
            return False

        async for query_db in get_db():
            plugin_list = await self.management_gateway.list_plugins(query_db)
            database_plugin_map = {plugin.plugin_id: plugin for plugin in plugin_list}
            return any(
                self._should_sync_default_enabled_builtin_plugin(database_plugin_map.get(plugin_id))
                for plugin_id in discovered_plugin_ids
            )

        return True

    async def check_enabled_plugin_python_dependencies(
        self,
        app: FastAPI,
        *,
        startup_write_enabled: bool = True,
    ) -> set[str]:
        """
        检查启用插件的 Python 依赖，缺失时标记插件运行时异常。

        :param app: FastAPI对象
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: 依赖检查失败的插件 ID 集合
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return set()

        self.python_dependency_inspector.refresh()
        failed_plugin_ids: set[str] = set()
        recovered_plugins: list[RegisteredPlugin] = []
        for plugin in self._list_dependency_check_plugins(plugin_registry):
            python_requirements = plugin.discovered_plugin.manifest.dependencies.python
            failed_messages = []
            if python_requirements:
                dependency_result = self._check_plugin_python_dependencies(plugin.plugin_id, python_requirements)
                failed_messages = self._build_dependency_failed_messages(dependency_result)
            if not failed_messages:
                if startup_write_enabled and self._has_startup_dependency_error(plugin):
                    recovered_plugins.append(plugin)
                continue
            failed_plugin_ids.add(plugin.plugin_id)
            error_message = self._build_dependency_startup_error_message(plugin.plugin_id, failed_messages)
            logger.bind(
                plugin_id=plugin.plugin_id,
                startup_generation=getattr(app.state, 'plugin_startup_generation', None),
                plugin_startup_role_at_creation='writer' if startup_write_enabled else 'reader',
                startup_write_enabled=startup_write_enabled,
            ).error(f'❌ {error_message}')
            if startup_write_enabled:
                await self.mark_plugin_runtime_error(app, plugin.plugin_id, error_message)

        if recovered_plugins:
            await self.recover_plugin_dependency_errors(app, recovered_plugins)
        return failed_plugin_ids

    @classmethod
    def _list_dependency_check_plugins(cls, plugin_registry: PluginRegistry) -> list[RegisteredPlugin]:
        """
        获取本次启动需要检查 Python 依赖的插件。

        除当前启用插件外，还要重新检查上次因启动依赖失败而被隔离的插件，
        避免其进入 error 状态后在后续启动中被启用态过滤器永久跳过。

        :param plugin_registry: 插件运行时注册表
        :return: 需要检查依赖的插件列表
        """
        plugins = list(plugin_registry.list_enabled_plugins())
        checked_plugin_ids = {plugin.plugin_id for plugin in plugins}
        for plugin in plugin_registry.list_plugins():
            if plugin.plugin_id in checked_plugin_ids:
                continue
            if cls._has_startup_dependency_error(plugin):
                plugins.append(plugin)
                checked_plugin_ids.add(plugin.plugin_id)
        return plugins

    @staticmethod
    def _has_startup_dependency_error(plugin: RegisteredPlugin) -> bool:
        """
        判断插件是否仅因启动依赖检查失败而处于异常状态。

        :param plugin: 插件运行时快照
        :return: 是否为启动依赖异常
        """
        database_plugin = plugin.database_plugin
        last_error = getattr(database_plugin, 'last_error', None) if database_plugin else None
        return (
            getattr(database_plugin, 'status', None) == 'error'
            and isinstance(last_error, str)
            and last_error.startswith(PLUGIN_STARTUP_DEPENDENCY_ERROR_PREFIX)
        )

    async def recover_plugin_dependency_errors(
        self,
        app: FastAPI,
        plugins: list[RegisteredPlugin],
    ) -> None:
        """
        恢复启动依赖重新满足的插件状态，并刷新运行时注册表。

        仅处理带启动依赖错误前缀的插件，其他 migration、实体导入或 hook
        异常仍保持 error，避免启动时误清除真实故障。

        :param app: FastAPI对象
        :param plugins: 依赖已恢复的插件列表
        :return: None
        """
        recovered = False
        async for query_db in get_db():
            for plugin in plugins:
                result = await self.management_gateway.recover_plugin_dependency_error(
                    query_db,
                    plugin.discovered_plugin,
                )
                if result.is_success:
                    recovered = True
                    logger.info(f'✅ 插件启动依赖已恢复：{plugin.plugin_id}')
                    continue
                logger.warning(f'⚠️ 插件启动依赖恢复状态写入失败：{plugin.plugin_id}，原因：{result.message}')
            if recovered:
                await query_db.commit()
            else:
                await query_db.rollback()
        if recovered:
            await self.load_registry_from_database(app)

    def _check_plugin_python_dependencies(
        self,
        plugin_id: str,
        python_requirements: list[str],
    ) -> DependencyCheckResult:
        """
        检查单个插件 Python 依赖。

        :param plugin_id: 插件ID
        :param python_requirements: Python 依赖声明列表
        :return: 依赖检查结果
        """
        return DependencyCheckResult(
            plugin_id=plugin_id, items=self.python_dependency_inspector.check(python_requirements)
        )

    @staticmethod
    def _build_dependency_failed_messages(dependency_result: DependencyCheckResult) -> list[str]:
        """
        构建依赖检查失败消息。

        :param dependency_result: 依赖检查结果
        :return: 失败消息列表
        """
        return [item.message for item in dependency_result.items if not item.ok]

    @staticmethod
    def _build_dependency_startup_error_message(plugin_id: str, failed_messages: list[str]) -> str:
        """
        构建包含修复命令的启动依赖检查失败消息。

        :param plugin_id: 插件ID
        :param failed_messages: 依赖检查失败消息
        :return: 启动依赖检查失败消息
        """
        install_command = f'ruoyi plugin install-deps {plugin_id} --env={AppConfig.app_env} --yes'
        return (
            f'{PLUGIN_STARTUP_DEPENDENCY_ERROR_PREFIX}{"；".join(failed_messages)}；安装依赖请执行：{install_command}'
        )

    async def _prompt_and_install_plugin_python_dependencies(
        self,
        plugin_id: str,
        dependency_result: DependencyCheckResult,
    ) -> bool:
        """
        在 TTY 环境中询问是否安装插件 Python 依赖。

        :param plugin_id: 插件ID
        :param dependency_result: 依赖检查结果
        :return: 是否已尝试安装依赖
        """
        if not self._can_prompt_dependency_install():
            return False
        failed_messages = self._build_dependency_failed_messages(dependency_result)
        print(f'插件 {plugin_id} 缺少启动所需 Python 依赖：', file=sys.stderr)
        for message in failed_messages:
            print(f'- {message}', file=sys.stderr)
        answer = (await asyncio.to_thread(input, '是否立即安装缺失依赖？[y/N] ')).strip().lower()
        if answer not in {'y', 'yes'}:
            return False
        await self._install_plugin_python_dependencies(dependency_result)
        self.python_dependency_inspector = self.python_dependency_inspector_factory()
        return True

    @staticmethod
    def _can_prompt_dependency_install() -> bool:
        """
        判断当前启动环境是否支持交互确认。

        :return: 是否支持交互确认
        """
        _ = AppConfig.app_workers
        _ = sys.stdin.isatty()
        return False

    async def _install_plugin_python_dependencies(self, dependency_result: DependencyCheckResult) -> None:
        """
        安装插件 Python 依赖。

        :param dependency_result: 依赖检查结果
        :return: None
        """
        install_plan = PluginDependencyInstallPlanner().build_plan(dependency_result)
        for item in install_plan.items:
            if item.kind != 'python':
                continue
            completed = await asyncio.to_thread(
                self.command_runner_gateway.run_command,
                item.command,
                item.workdir,
            )
            if completed.returncode == 0:
                logger.info(f'✅ 插件 {dependency_result.plugin_id} Python 依赖安装完成：{item.requirement}')
                continue
            logger.error(
                f'❌ 插件 {dependency_result.plugin_id} Python 依赖安装失败：{item.requirement}，'
                f'returncode={completed.returncode}，stderr={completed.stderr[-500:]}'
            )

    async def activate_enabled_plugins(self, app: FastAPI, *, startup_write_enabled: bool = True) -> None:
        """
        激活启用插件运行时资源。

        :param app: FastAPI对象
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: None
        """
        if startup_write_enabled:
            await self.sync_enabled_plugin_install_states(app)
            await self.install_enabled_plugin_resources(app)
        await self.run_enabled_plugin_hooks(app, 'on_startup', startup_write_enabled=startup_write_enabled)
        self.register_enabled_plugin_routers(app, startup_write_enabled=startup_write_enabled)

    async def shutdown(self, app: FastAPI, *, startup_write_enabled: bool = True) -> None:
        """
        执行插件运行时关闭接入流程。

        :param app: FastAPI对象
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: None
        """
        await self.run_enabled_plugin_hooks(app, 'on_shutdown', startup_write_enabled=startup_write_enabled)

    async def load_registry_from_database(self, app: FastAPI) -> None:
        """
        从数据库插件状态构建运行时插件注册表。

        :param app: FastAPI对象
        :return: None
        """
        async for query_db in get_db():
            plugin_list = await self.management_gateway.list_plugins(query_db)
            app.state.plugin_registry = self.builder.build_registry(plugin_list)

    async def import_enabled_plugin_entities(
        self,
        app: FastAPI,
        *,
        startup_write_enabled: bool = True,
    ) -> set[str]:
        """
        导入启用插件实体并标记导入失败插件。

        :param app: FastAPI对象
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: 实体导入失败的插件 ID 集合
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return set()

        import_result = self.builder.import_plugin_entities(plugin_registry)
        failed_plugin_ids: set[str] = set()
        for failure in import_result.failures:
            failed_plugin_ids.add(failure.plugin_id)
            logger.bind(
                plugin_id=failure.plugin_id,
                startup_generation=getattr(app.state, 'plugin_startup_generation', None),
                plugin_startup_role_at_creation='writer' if startup_write_enabled else 'reader',
                startup_write_enabled=startup_write_enabled,
            ).error(f'❌ 插件实体导入失败：{failure.error_message}')
            if startup_write_enabled:
                await self.mark_plugin_runtime_error(app, failure.plugin_id, failure.error_message)

        return failed_plugin_ids

    async def install_enabled_plugin_resources(self, app: FastAPI) -> None:
        """
        逐插件同步启用插件的启动期资源。

        每个插件使用独立事务，单个插件资源声明或数据库写入失败时仅隔离该插件，
        不再回滚其他插件或阻断宿主应用启动。

        :param app: FastAPI对象
        :return: None
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return

        plugins = list(plugin_registry.list_enabled_plugins())
        for plugin in plugins:
            await self.install_plugin_resources_with_isolation(app, plugin)

    async def install_plugin_resources_with_isolation(
        self,
        app: FastAPI,
        plugin: RegisteredPlugin,
    ) -> None:
        """
        在独立事务中同步单个插件资源，失败时隔离该插件。

        :param app: FastAPI对象
        :param plugin: 插件运行时快照
        :return: None
        """
        with logger.contextualize(
            plugin_id=plugin.plugin_id,
            plugin_startup_role_at_creation='writer',
            startup_write_enabled=True,
        ):
            logger.info('🔄 开始同步单插件启动资源')
            try:
                async for query_db in get_db():
                    try:
                        await self.management_gateway.install_plugin_resources(
                            query_db,
                            plugin.discovered_plugin,
                            enabled=True,
                        )
                        await query_db.commit()
                    except Exception:
                        await query_db.rollback()
                        raise
            except Exception as exc:
                error_message = f'插件启动资源同步失败：{exc}'
                logger.exception(f'❌ {error_message}')
                await self.mark_plugin_runtime_error(app, plugin.plugin_id, error_message)
                return
            logger.info('✅ 单插件启动资源同步完成')

    async def sync_enabled_plugin_install_states(self, app: FastAPI) -> None:
        """
        将默认启用且尚未持久化安装状态的插件标记为已安装。

        :param app: FastAPI对象
        :return: None
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return

        plugins_to_sync = [
            plugin
            for plugin in plugin_registry.list_enabled_plugins()
            if self._should_sync_plugin_install_state(plugin)
        ]
        if not plugins_to_sync:
            return

        for plugin in plugins_to_sync:
            await self.sync_plugin_install_with_isolation(app, plugin)

        await self.load_registry_from_database(app)

    async def sync_plugin_install_with_isolation(
        self,
        app: FastAPI,
        plugin: RegisteredPlugin,
    ) -> None:
        """
        执行单插件启动安装，失败时记录错误并继续其他插件。

        :param app: FastAPI对象
        :param plugin: 插件运行时快照
        :return: None
        """
        try:
            await self.sync_plugin_install(plugin.discovered_plugin, enabled=True)
        except Exception as exc:
            error_message = f'插件启动安装失败：{exc}'
            logger.exception(f'❌ {plugin.plugin_id} {error_message}')
            await self.mark_plugin_runtime_error(app, plugin.plugin_id, error_message)

    async def sync_plugin_install(self, discovered_plugin: Any, *, enabled: bool) -> None:
        """
        使用独立事务执行单个插件的启动期安装生命周期。

        启动期首次安装与管理端安装保持相同的关键步骤：结构校验、发现状态写入、
        资源同步、migration、seed、on_install 钩子和最终安装状态写入。

        :param discovered_plugin: 已发现插件对象
        :param enabled: 插件资源是否启用
        :return: None
        """
        plugin_id = discovered_plugin.manifest.id
        with logger.contextualize(
            plugin_id=plugin_id,
            plugin_startup_role_at_creation='writer',
            startup_write_enabled=True,
        ):
            logger.info('🔄 开始执行插件启动安装生命周期')
            self.validate_plugin_structure(discovered_plugin)
            async for query_db in get_db():
                try:
                    await self.management_gateway.upsert_discovered_plugin(
                        query_db,
                        discovered_plugin,
                        self.builder.plugins_root,
                        self.builder.frontend_plugins_root,
                    )
                    await self.management_gateway.install_plugin_resources(
                        query_db,
                        discovered_plugin,
                        enabled=enabled,
                    )
                    await self.run_plugin_install_scripts(query_db, discovered_plugin)
                    await self.run_plugin_install_hook(query_db, discovered_plugin)
                    await self.management_gateway.mark_plugin_installed(query_db, discovered_plugin)
                    await query_db.commit()
                except Exception:
                    await query_db.rollback()
                    raise
            logger.info('✅ 插件启动安装生命周期执行完成')

    @staticmethod
    async def run_plugin_install_hook(query_db: Any, discovered_plugin: Any) -> None:
        """
        执行插件首次安装钩子。

        :param query_db: orm对象
        :param discovered_plugin: 已发现插件对象
        :return: None
        """
        await PluginHookRunner(discovered_plugin).run('on_install', query_db=query_db)

    def validate_plugin_structure(self, discovered_plugin: Any) -> None:
        """
        校验启动期首次安装插件的目录和声明引用。

        :param discovered_plugin: 已发现插件对象
        :return: None
        :raises ValueError: 插件结构校验失败
        """
        result = PluginStructureChecker(
            self.builder.backend_root,
            self.builder.frontend_plugins_root,
        ).check(discovered_plugin)
        if result.ok:
            return
        messages = '；'.join(item.message for item in result.failed_items)
        raise ValueError(f'插件结构校验失败：{messages}')

    @staticmethod
    def _should_sync_plugin_install_state(plugin: RegisteredPlugin) -> bool:
        """
        判断启用插件是否需要在启动期同步安装状态。

        :param plugin: 插件运行时快照
        :return: 是否需要同步
        """
        database_plugin = plugin.database_plugin
        if database_plugin is None:
            return True
        return (
            not getattr(database_plugin, 'installed_version', None)
            and getattr(database_plugin, 'status', None) == 'discovered'
        )

    async def run_plugin_install_scripts(self, query_db: Any, discovered_plugin: Any) -> None:
        """
        执行插件安装期数据库脚本。

        :param query_db: orm对象
        :param discovered_plugin: 已发现插件对象
        :return: None
        """
        async with AsyncSessionLocal() as migration_session:
            await PluginMigrationRunner(
                discovered_plugin,
                PluginStartupMigrationHistoryStore(self.management_gateway, AsyncSessionLocal),
                manage_execution_transaction=True,
            ).run(migration_session)
        await self.run_plugin_seed_scripts(query_db, discovered_plugin)

    @staticmethod
    async def run_plugin_seed_scripts(query_db: Any, discovered_plugin: Any) -> None:
        """
        执行插件 seed 脚本。

        :param query_db: orm对象
        :param discovered_plugin: 已发现插件对象
        :return: None
        """
        await PluginSeedRunner(discovered_plugin).run(query_db)

    def register_enabled_plugin_routers(
        self,
        app: FastAPI,
        *,
        startup_write_enabled: bool = True,
    ) -> None:
        """
        注册启用插件 controller 路由。

        :param app: FastAPI对象
        :param startup_write_enabled: 当前worker是否为插件启动writer
        :return: None
        """
        if getattr(app.state, 'plugin_routes_registered', False):
            return
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        plugin_ids = []
        if plugin_registry:
            plugin_ids = [
                plugin.plugin_id
                for plugin in plugin_registry.list_enabled_plugins()
                if plugin.discovered_plugin.manifest.backend.routers.auto_scan
            ]
        for plugin_id in plugin_ids:
            with logger.contextualize(
                plugin_id=plugin_id,
                startup_generation=getattr(app.state, 'plugin_startup_generation', None),
                plugin_startup_role_at_creation='writer' if startup_write_enabled else 'reader',
                startup_write_enabled=startup_write_enabled,
            ):
                controller_files = self._find_plugin_controller_files([plugin_id])
                controller_files = self._filter_plugin_controller_files_by_route_prefix(plugin_id, controller_files)
                if controller_files:
                    auto_register_controller_files(
                        app,
                        controller_files,
                        dependencies=[PluginEnabledDependency(plugin_id, self.route_state_gateway)],
                    )
        app.state.plugin_routes_registered = True

    def _filter_plugin_controller_files_by_route_prefix(self, plugin_id: str, controller_files: list[str]) -> list[str]:
        """
        启动期再次校验插件 controller 路由前缀，避免绕过预检注册宿主命名空间路由。

        :param plugin_id: 插件ID
        :param controller_files: controller 文件路径列表
        :return: 通过命名空间校验的 controller 文件路径列表
        """
        checker = PluginStructureChecker(self.builder.backend_root)
        valid_controller_files = []
        for controller_file in controller_files:
            check_items = checker.check_controller_file_route_prefixes(plugin_id, Path(controller_file))
            if not check_items:
                logger.error(f'❌ 插件 {plugin_id} controller 路由前缀无法静态确认，启动期跳过注册：{controller_file}')
                continue
            failed_items = [item for item in check_items if not item.ok]
            if failed_items:
                logger.error(
                    f'❌ 插件 {plugin_id} controller 路由前缀非法，启动期跳过注册：'
                    f'{"、".join(item.message for item in failed_items)}'
                )
                continue
            valid_controller_files.append(controller_file)

        return valid_controller_files

    def _find_plugin_controller_files(self, plugin_ids: list[str]) -> list[str]:
        """
        查找启用插件 controller 目录下的路由文件。

        :param plugin_ids: 插件ID列表
        :return: 插件controller文件路径列表
        """
        backend_root = self.builder.backend_root
        plugins_root = backend_root / 'plugins'
        controller_files = []
        for plugin_id in plugin_ids:
            controller_dir = plugins_root / plugin_id / 'controller'
            if not controller_dir.is_dir():
                continue
            controller_files.extend(str(path) for path in controller_dir.glob('[!_]*.py'))

        return sorted(controller_files)

    async def run_enabled_plugin_hooks(
        self,
        app: FastAPI,
        hook_name: str,
        *,
        startup_write_enabled: bool = True,
    ) -> None:
        """
        执行启用插件生命周期钩子。

        :param app: FastAPI对象
        :param hook_name: 钩子名称
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: None
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return

        for plugin in plugin_registry.list_enabled_plugins():
            await self.run_single_plugin_hook(
                app,
                plugin,
                hook_name,
                startup_write_enabled=startup_write_enabled,
            )

    async def run_single_plugin_hook(
        self,
        app: FastAPI,
        plugin: RegisteredPlugin,
        hook_name: str,
        *,
        startup_write_enabled: bool = True,
    ) -> None:
        """
        执行单个插件生命周期钩子并处理运行时异常。

        :param app: FastAPI对象
        :param plugin: 插件运行时快照
        :param hook_name: 钩子名称
        :param startup_write_enabled: 是否允许执行启动期写库操作
        :return: None
        """
        try:
            await PluginHookRunner(plugin.discovered_plugin).run(
                hook_name,
                app=app,
                startup_write_enabled=startup_write_enabled,
            )
        except Exception as exc:
            logger.bind(
                plugin_id=plugin.plugin_id,
                plugin_hook=hook_name,
                startup_generation=getattr(app.state, 'plugin_startup_generation', None),
                plugin_startup_role_at_creation='writer' if startup_write_enabled else 'reader',
                startup_write_enabled=startup_write_enabled,
                origin_hook=hook_name,
            ).exception(f'❌ 插件生命周期钩子执行失败：{exc}')
            if startup_write_enabled:
                await self.mark_plugin_runtime_error(app, plugin.plugin_id, str(exc))
            elif hook_name == 'on_startup':
                self.disable_runtime_plugins(app, {plugin.plugin_id})

    async def mark_plugin_runtime_error(self, app: FastAPI, plugin_id: str, error_message: str) -> None:
        """
        标记插件运行时异常并刷新运行时注册表。

        :param app: FastAPI对象
        :param plugin_id: 插件ID
        :param error_message: 错误信息
        :return: None
        """
        async for query_db in get_db():
            result = await self.management_gateway.mark_plugin_error(query_db, plugin_id, error_message)
            if not result.is_success:
                await query_db.rollback()
                registered_plugin = self.get_registered_plugin(app, plugin_id)
                if registered_plugin:
                    await self.management_gateway.upsert_discovered_plugin(
                        query_db,
                        registered_plugin.discovered_plugin,
                        self.builder.plugins_root,
                        self.builder.frontend_plugins_root,
                    )
                    result = await self.management_gateway.mark_plugin_error(query_db, plugin_id, error_message)
            if result.is_success:
                await query_db.commit()
            else:
                await query_db.rollback()
                logger.warning(f'⚠️ 插件运行时异常状态写入失败：{plugin_id}，原因：{result.message}')
        await self.load_registry_from_database(app)

    async def sync_default_enabled_builtin_plugin_install_states(self) -> set[str]:
        """
        首次启动时将内置默认启用插件写入数据库安装状态。

        安装脚本执行前先校验 Python 依赖，避免 migration/seed 导入缺失依赖导致启动
        提前失败。缺失依赖的插件被标记为 error 并隔离，不影响其他插件继续启动。

        :return: 依赖检查失败的默认启用插件 ID 集合
        """
        if not self.default_enabled_builtin_plugin_ids:
            return set()

        discovered_plugins = [
            plugin
            for plugin in self.builder.discover_plugins()
            if plugin.manifest.id in self.default_enabled_builtin_plugin_ids
        ]
        if not discovered_plugins:
            return set()

        failed_plugin_ids: set[str] = set()
        async for query_db in get_db():
            plugin_list = await self.management_gateway.list_plugins(query_db)
        database_plugin_map = {plugin.plugin_id: plugin for plugin in plugin_list}
        plugins_to_sync = [
            plugin
            for plugin in discovered_plugins
            if self._should_sync_default_enabled_builtin_plugin(database_plugin_map.get(plugin.manifest.id))
        ]
        if not plugins_to_sync:
            return failed_plugin_ids

        self.python_dependency_inspector.refresh()
        for plugin in plugins_to_sync:
            plugin_id = plugin.manifest.id
            dependency_failed_messages = self._check_default_plugin_python_dependencies(plugin)
            if dependency_failed_messages:
                failed_plugin_ids.add(plugin_id)
                error_message = self._build_dependency_startup_error_message(
                    plugin_id,
                    dependency_failed_messages,
                )
                logger.error(f'❌ {plugin_id} {error_message}')
                await self.mark_discovered_plugin_startup_error(plugin, error_message)
                continue
            try:
                await self.sync_plugin_install(plugin, enabled=True)
            except Exception as exc:
                failed_plugin_ids.add(plugin_id)
                error_message = f'插件启动安装失败：{exc}'
                logger.exception(f'❌ {plugin_id} {error_message}')
                await self.mark_discovered_plugin_startup_error(plugin, error_message)
        return failed_plugin_ids

    async def mark_discovered_plugin_startup_error(
        self,
        discovered_plugin: Any,
        error_message: str,
    ) -> None:
        """
        以独立事务持久化启动期插件错误，确保安装事务回滚后仍可观测。

        :param discovered_plugin: 已发现插件对象
        :param error_message: 错误信息
        :return: None
        """
        plugin_id = discovered_plugin.manifest.id
        async for query_db in get_db():
            try:
                await self.management_gateway.upsert_discovered_plugin(
                    query_db,
                    discovered_plugin,
                    self.builder.plugins_root,
                    self.builder.frontend_plugins_root,
                )
                result = await self.management_gateway.mark_plugin_error(query_db, plugin_id, error_message)
                if not result.is_success:
                    raise RuntimeError(result.message)
                await query_db.commit()
            except Exception:
                await query_db.rollback()
                logger.exception(f'❌ 插件启动异常状态写入失败：{plugin_id}')

    def _check_default_plugin_python_dependencies(self, discovered_plugin: Any) -> list[str]:
        """
        校验内置默认启用插件的 Python 依赖。

        :param discovered_plugin: 已发现插件
        :return: 依赖检查失败消息列表
        """
        python_requirements = discovered_plugin.manifest.dependencies.python
        if not python_requirements:
            return []
        dependency_result = self._check_plugin_python_dependencies(
            discovered_plugin.manifest.id,
            python_requirements,
        )
        return self._build_dependency_failed_messages(dependency_result)

    @staticmethod
    def _should_sync_default_enabled_builtin_plugin(database_plugin: Any | None) -> bool:
        """
        判断内置默认启用插件是否需要启动期初始化安装状态。

        :param database_plugin: 数据库插件状态
        :return: 是否需要初始化
        """
        if database_plugin is None:
            return True
        return (
            not getattr(database_plugin, 'installed_version', None)
            and getattr(database_plugin, 'status', None) == 'discovered'
            and getattr(database_plugin, 'enabled', None) == '0'
        )

    @staticmethod
    def disable_runtime_plugins(app: FastAPI, plugin_ids: set[str]) -> None:
        """
        在当前 worker 的运行时注册表中停用指定插件，避免非写入 worker 继续导入或注册失败插件。

        :param app: FastAPI对象
        :param plugin_ids: 需要在当前 worker 跳过的插件 ID 集合
        :return: None
        """
        if not plugin_ids:
            return
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return
        app.state.plugin_registry = PluginRegistry(
            [
                replace(plugin, enabled=False, status='error') if plugin.plugin_id in plugin_ids else plugin
                for plugin in plugin_registry.list_plugins()
            ]
        )

    @staticmethod
    def get_registered_plugin(app: FastAPI, plugin_id: str) -> RegisteredPlugin | None:
        """
        从应用运行时注册表获取插件快照。

        :param app: FastAPI对象
        :param plugin_id: 插件ID
        :return: 插件运行时快照
        """
        plugin_registry = getattr(app.state, 'plugin_registry', None)
        if plugin_registry is None:
            return None

        return plugin_registry.get_plugin(plugin_id)