langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/plugin/loader.py

@@ -0,0 +1,386 @@
+"""
+plugin/loader.py — Plugin Discovery/Load/Register 主编排。
+
+职责：
+    协调插件发现、manifest 解析、能力注册与 hook 原子切换。
+
+链路位置：
+    由容器 on_start/on_end 调用，连接 workspace 配置、HookEngine 与各 Registry。
+
+当前裁剪范围：
+    覆盖本地+内置插件；不包含远程插件下载与 MCP 连接管理。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.loop.hook.config import HookSpec, HooksConfigSnapshot
+from langchain_agentx.loop.hook.types import HookEvent
+from langchain_agentx.workspace.config import AgentWorkspaceConfig
+
+from .builtin import BuiltinPluginRegistry
+from .config import PluginConfigLoader
+from .manifest import MinimalManifest, PluginManifestSchema, ValidationError
+from .registries import AgentRegistry, CommandRegistry, SkillRegistry
+from .types import (
+    GenericPluginError,
+    HookLoadFailedError,
+    LoadedPlugin,
+    ManifestParseError,
+    ManifestValidationError,
+    PluginError,
+    PluginLoadResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PluginLoader:
+    def __init__(
+        self,
+        workspace_config: AgentWorkspaceConfig,
+        hook_engine: Any,
+        skill_registry: SkillRegistry,
+        command_registry: CommandRegistry,
+        agent_registry: AgentRegistry,
+        mcp_manager: Any | None = None,
+        builtin_registry: BuiltinPluginRegistry | None = None,
+    ) -> None:
+        self._cfg = workspace_config
+        self._hook_engine = hook_engine
+        self._skill_registry = skill_registry
+        self._command_registry = command_registry
+        self._agent_registry = agent_registry
+        self._mcp_manager = mcp_manager
+        self._builtin_registry = builtin_registry or BuiltinPluginRegistry.global_instance()
+        self._loaded: list[LoadedPlugin] = []
+
+    async def load_all(self, container_type: str | None = None) -> PluginLoadResult:
+        errors: list[PluginError] = []
+        candidates = await self._discover(errors)
+        if container_type:
+            candidates = [
+                plugin
+                for plugin in candidates
+                if not plugin.applicable_containers
+                or container_type in plugin.applicable_containers
+            ]
+
+        candidates = [plugin for plugin in candidates if plugin.enabled]
+
+        errors.extend(await self._register_skills(candidates))
+        errors.extend(await self._register_commands(candidates))
+        errors.extend(await self._register_agents(candidates))
+        errors.extend(await self._register_hooks_atomic(candidates))
+
+        self._loaded = candidates
+        return PluginLoadResult(enabled=candidates, errors=errors)
+
+    async def unload_all(self) -> None:
+        for plugin in self._loaded:
+            try:
+                self._skill_registry.unregister_plugin(plugin.source)
+                self._command_registry.unregister_plugin(plugin.source)
+                self._agent_registry.unregister_plugin(plugin.source)
+            except Exception as exc:
+                logger.error(
+                    "plugin unload failed for %s: %s", plugin.source, exc, exc_info=True
+                )
+        snapshot = self._get_snapshot()
+        if snapshot is not None:
+            try:
+                snapshot.replace_plugin_hooks_atomic([])
+            except Exception as exc:
+                logger.error("plugin hook cleanup failed: %s", exc, exc_info=True)
+        self._loaded = []
+
+    async def reload(self, container_type: str | None = None) -> PluginLoadResult:
+        errors: list[PluginError] = []
+        candidates = await self._discover(errors)
+        if container_type:
+            candidates = [
+                plugin
+                for plugin in candidates
+                if not plugin.applicable_containers
+                or container_type in plugin.applicable_containers
+            ]
+        candidates = [plugin for plugin in candidates if plugin.enabled]
+
+        for plugin in self._loaded:
+            self._skill_registry.unregister_plugin(plugin.source)
+            self._command_registry.unregister_plugin(plugin.source)
+            self._agent_registry.unregister_plugin(plugin.source)
+
+        errors.extend(await self._register_skills(candidates))
+        errors.extend(await self._register_commands(candidates))
+        errors.extend(await self._register_agents(candidates))
+        errors.extend(await self._register_hooks_atomic(candidates))
+        self._loaded = candidates
+        return PluginLoadResult(enabled=candidates, errors=errors)
+
+    async def disable_plugin(self, plugin_source: str) -> None:
+        self._skill_registry.unregister_plugin(plugin_source)
+        self._command_registry.unregister_plugin(plugin_source)
+        self._agent_registry.unregister_plugin(plugin_source)
+        snapshot = self._get_snapshot()
+        if snapshot is not None:
+            snapshot.remove_plugin_hooks(plugin_source)
+        self._loaded = [plugin for plugin in self._loaded if plugin.source != plugin_source]
+
+    async def _discover(self, errors: list[PluginError]) -> list[LoadedPlugin]:
+        plugins: list[LoadedPlugin] = []
+        plugins.extend(self._discover_builtin())
+        local_plugins, local_errors = await self._discover_local()
+        plugins.extend(local_plugins)
+        errors.extend(local_errors)
+        return plugins
+
+    def _discover_builtin(self) -> list[LoadedPlugin]:
+        plugin_config = PluginConfigLoader.load(self._cfg)
+        loaded: list[LoadedPlugin] = []
+        for definition in self._builtin_registry.all():
+            plugin_id = f"{definition.name}@builtin"
+            enabled = plugin_config.is_enabled(plugin_id, default=definition.default_enabled)
+            if definition.is_available and not definition.is_available():
+                continue
+            loaded.append(
+                LoadedPlugin(
+                    name=definition.name,
+                    description=definition.description,
+                    version=definition.version,
+                    path="builtin",
+                    source=plugin_id,
+                    enabled=enabled,
+                    is_builtin=True,
+                    hooks_config=definition.hooks,
+                    mcp_servers=definition.mcp_servers or {},
+                    applicable_containers=definition.applicable_containers,
+                )
+            )
+        return loaded
+
+    async def _discover_local(self) -> tuple[list[LoadedPlugin], list[PluginError]]:
+        plugins_dir = self._cfg.plugins_dir
+        if not plugins_dir.exists():
+            return [], []
+
+        plugin_config = PluginConfigLoader.load(self._cfg)
+        plugins: list[LoadedPlugin] = []
+        errors: list[PluginError] = []
+        for plugin_dir in sorted(plugins_dir.iterdir()):
+            if not plugin_dir.is_dir():
+                continue
+            plugin_id = f"{plugin_dir.name}@local"
+            if not plugin_config.is_enabled(plugin_id, default=True):
+                continue
+            loaded, error = await self._load_local_plugin(plugin_dir, plugin_id)
+            if loaded is not None:
+                plugins.append(loaded)
+            if error is not None:
+                errors.append(error)
+        return plugins, errors
+
+    async def _load_local_plugin(
+        self, plugin_dir: Path, plugin_id: str
+    ) -> tuple[LoadedPlugin | None, PluginError | None]:
+        manifest_path = plugin_dir / "plugin.json"
+        if manifest_path.exists():
+            try:
+                raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+                manifest = PluginManifestSchema.validate(raw)
+            except json.JSONDecodeError as exc:
+                return (
+                    None,
+                    ManifestParseError(
+                        source=plugin_id,
+                        manifest_path=str(manifest_path),
+                        parse_error=str(exc),
+                    ),
+                )
+            except ValidationError as exc:
+                return (
+                    None,
+                    ManifestValidationError(
+                        source=plugin_id,
+                        manifest_path=str(manifest_path),
+                        validation_errors=exc.messages,
+                    ),
+                )
+            except OSError as exc:
+                return (
+                    None,
+                    GenericPluginError(
+                        source=plugin_id,
+                        plugin=plugin_dir.name,
+                        error=str(exc),
+                    ),
+                )
+        else:
+            manifest = MinimalManifest(name=plugin_dir.name)
+
+        skills_dir = plugin_dir / manifest.skills_path
+        commands_dir = plugin_dir / manifest.commands_path
+        agents_dir = plugin_dir / manifest.agents_path
+        loaded = LoadedPlugin(
+            name=manifest.name,
+            description=manifest.description,
+            version=manifest.version,
+            path=str(plugin_dir),
+            source=plugin_id,
+            enabled=True,
+            is_builtin=False,
+            skills_dir=skills_dir if skills_dir.exists() else None,
+            commands_dir=commands_dir if commands_dir.exists() else None,
+            agents_dir=agents_dir if agents_dir.exists() else None,
+            hooks_config=manifest.hooks,
+            mcp_servers=manifest.mcp_servers,
+            dependencies=manifest.dependencies,
+            applicable_containers=manifest.applicable_containers,
+        )
+        return loaded, None
+
+    async def _register_skills(self, plugins: list[LoadedPlugin]) -> list[PluginError]:
+        errors: list[PluginError] = []
+        for plugin in plugins:
+            errors.extend(self._skill_registry.register(plugin))
+        return errors
+
+    async def _register_commands(self, plugins: list[LoadedPlugin]) -> list[PluginError]:
+        errors: list[PluginError] = []
+        for plugin in plugins:
+            errors.extend(self._command_registry.register(plugin))
+        return errors
+
+    async def _register_agents(self, plugins: list[LoadedPlugin]) -> list[PluginError]:
+        errors: list[PluginError] = []
+        for plugin in plugins:
+            errors.extend(self._agent_registry.register(plugin))
+        return errors
+
+    async def _register_hooks_atomic(self, plugins: list[LoadedPlugin]) -> list[PluginError]:
+        snapshot = self._get_snapshot()
+        if snapshot is None:
+            return [
+                GenericPluginError(
+                    source="plugin-loader",
+                    plugin="hook_engine",
+                    error="hook engine snapshot is unavailable",
+                )
+            ]
+
+        errors: list[PluginError] = []
+        specs: list[HookSpec] = []
+        for plugin in plugins:
+            if plugin.is_builtin:
+                continue
+            if not plugin.hooks_config:
+                continue
+            built_specs, built_errors = self._convert_hooks_to_specs(plugin)
+            specs.extend(built_specs)
+            errors.extend(built_errors)
+
+        snapshot.replace_plugin_hooks_atomic(specs)
+        return errors
+
+    def _convert_hooks_to_specs(
+        self, plugin: LoadedPlugin
+    ) -> tuple[list[HookSpec], list[PluginError]]:
+        specs: list[HookSpec] = []
+        errors: list[PluginError] = []
+        hooks_config = plugin.hooks_config or {}
+        if not isinstance(hooks_config, dict):
+            return specs, errors
+
+        event_map = {event.name: event for event in HookEvent}
+        for event_name, matchers in hooks_config.items():
+            if event_name not in event_map:
+                logger.warning(
+                    "plugin %s has unknown hook event %r, skipping",
+                    plugin.source,
+                    event_name,
+                )
+                continue
+            event = event_map[event_name]
+            if not isinstance(matchers, list):
+                continue
+            for matcher_entry in matchers:
+                if not isinstance(matcher_entry, dict):
+                    continue
+                matcher = self._extract_matcher(matcher_entry.get("matcher", {}))
+                for hook_entry in matcher_entry.get("hooks", []):
+                    spec_or_error = self._build_spec(plugin, event, matcher, hook_entry)
+                    if isinstance(spec_or_error, HookSpec):
+                        specs.append(spec_or_error)
+                    else:
+                        errors.append(spec_or_error)
+        return specs, errors
+
+    def _build_spec(
+        self,
+        plugin: LoadedPlugin,
+        event: HookEvent,
+        matcher: str,
+        hook_entry: Any,
+    ) -> HookSpec | HookLoadFailedError:
+        if not isinstance(hook_entry, dict):
+            return HookLoadFailedError(
+                source=plugin.source,
+                plugin=plugin.name,
+                hook_path=f"plugin.json/hooks/{event.name}",
+                reason="hook entry must be object",
+            )
+        executor_type = hook_entry.get("type")
+        if executor_type not in ("command", "http", "prompt", "agent"):
+            return HookLoadFailedError(
+                source=plugin.source,
+                plugin=plugin.name,
+                hook_path=f"plugin.json/hooks/{event.name}",
+                reason=f"unsupported executor type in manifest: {executor_type!r}",
+            )
+        if executor_type == "http" and event == HookEvent.SESSION_START:
+            return HookLoadFailedError(
+                source=plugin.source,
+                plugin=plugin.name,
+                hook_path=f"plugin.json/hooks/{event.name}",
+                reason="http hooks cannot be used with SessionStart event",
+            )
+        timeout = hook_entry.get("timeout", self._default_timeout(executor_type))
+        return HookSpec(
+            event=event,
+            executor_type=executor_type,
+            config=dict(hook_entry),
+            matcher=matcher,
+            timeout=float(timeout),
+            source="plugin",
+            plugin_source=plugin.source,
+            once=bool(hook_entry.get("once", False)),
+        )
+
+    @staticmethod
+    def _extract_matcher(matcher: Any) -> str:
+        if isinstance(matcher, dict):
+            tool_name = matcher.get("tool_name")
+            if isinstance(tool_name, str) and tool_name.strip():
+                return tool_name.strip()
+        return "*"
+
+    @staticmethod
+    def _default_timeout(executor_type: str) -> float:
+        if executor_type == "http":
+            return 30.0
+        return 60.0
+
+    def _get_snapshot(self) -> HooksConfigSnapshot | None:
+        snapshot = getattr(self._hook_engine, "snapshot", None)
+        if snapshot is None:
+            snapshot = getattr(self._hook_engine, "_snapshot", None)
+        if isinstance(snapshot, HooksConfigSnapshot):
+            return snapshot
+        return None
+
+
+__all__ = ["PluginLoader"]

langchain_agentx/plugin/manifest.py

@@ -0,0 +1,154 @@
+"""
+plugin/manifest.py — plugin.json 解析与校验。
+
+职责：
+    定义 PluginManifest/MinimalManifest，并提供 PluginManifestSchema.validate()。
+
+链路位置：
+    PluginLoader._load_local_plugin() 在构建 LoadedPlugin 前调用本模块。
+
+当前裁剪范围：
+    仅覆盖 P0/P1 校验规则，不包含 mcp_servers 深度校验与依赖拓扑解析。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import re
+from typing import Any
+
+from langchain_agentx.loop.hook.types import HookEvent
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    name: str
+    description: str = ""
+    version: str = "0.1.0"
+    applicable_containers: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+    skills_path: str = "skills"
+    commands_path: str = "commands"
+    agents_path: str = "agents"
+    hooks: dict[str, Any] | None = None
+    mcp_servers: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class MinimalManifest(PluginManifest):
+    pass
+
+
+class ValidationError(Exception):
+    """manifest 校验错误。"""
+
+    def __init__(self, messages: list[str]) -> None:
+        super().__init__("; ".join(messages))
+        self.messages = messages
+
+
+class PluginManifestSchema:
+    """plugin.json 校验器。"""
+
+    _name_pattern = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+    _semver_pattern = re.compile(r"^\d+\.\d+\.\d+$")
+    _allowed_hook_types = {"command", "http", "prompt", "agent"}
+    _http_disallowed_events = {"SessionStart"}
+
+    @classmethod
+    def validate(cls, raw: dict[str, Any]) -> PluginManifest:
+        if not isinstance(raw, dict):
+            raise ValidationError(["manifest root must be object"])
+
+        errors: list[str] = []
+        name = raw.get("name")
+        if not isinstance(name, str) or not cls._name_pattern.fullmatch(name):
+            errors.append("name must match ^[a-z0-9][a-z0-9-]{0,63}$")
+
+        description = raw.get("description", "")
+        if description is not None and not isinstance(description, str):
+            errors.append("description must be string")
+        description = description if isinstance(description, str) else ""
+
+        version = raw.get("version", "0.1.0")
+        if not isinstance(version, str) or not cls._semver_pattern.fullmatch(version):
+            errors.append("version must be semver x.y.z")
+
+        applicable = raw.get("applicable_containers", [])
+        if not isinstance(applicable, list) or not all(isinstance(v, str) for v in applicable):
+            errors.append("applicable_containers must be list[str]")
+            applicable = []
+
+        dependencies = raw.get("dependencies", [])
+        if not isinstance(dependencies, list) or not all(isinstance(v, str) for v in dependencies):
+            errors.append("dependencies must be list[str]")
+            dependencies = []
+
+        skills_path = raw.get("skills_path", "skills")
+        commands_path = raw.get("commands_path", "commands")
+        agents_path = raw.get("agents_path", "agents")
+        for field_name, value in (
+            ("skills_path", skills_path),
+            ("commands_path", commands_path),
+            ("agents_path", agents_path),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                errors.append(f"{field_name} must be non-empty string")
+
+        hooks = raw.get("hooks")
+        if hooks is not None:
+            cls._validate_hooks(hooks, errors)
+
+        mcp_servers = raw.get("mcp_servers", {})
+        if not isinstance(mcp_servers, dict):
+            errors.append("mcp_servers must be object")
+            mcp_servers = {}
+
+        if errors:
+            raise ValidationError(errors)
+
+        return PluginManifest(
+            name=name,
+            description=description,
+            version=version,
+            applicable_containers=applicable,
+            dependencies=dependencies,
+            skills_path=skills_path,
+            commands_path=commands_path,
+            agents_path=agents_path,
+            hooks=hooks if isinstance(hooks, dict) else None,
+            mcp_servers=mcp_servers,
+        )
+
+    @classmethod
+    def _validate_hooks(cls, hooks: Any, errors: list[str]) -> None:
+        if not isinstance(hooks, dict):
+            errors.append("hooks must be object")
+            return
+        valid_event_names = {event.name for event in HookEvent}
+        for event_name, matchers in hooks.items():
+            if not isinstance(event_name, str):
+                errors.append("hook event key must be string")
+                continue
+            if event_name not in valid_event_names:
+                # 未知事件只告警级别，忽略该 key，不阻断整个 manifest
+                continue
+            if not isinstance(matchers, list):
+                errors.append(f"hooks.{event_name} must be list")
+                continue
+            for matcher in matchers:
+                if not isinstance(matcher, dict):
+                    errors.append(f"hooks.{event_name} matcher must be object")
+                    continue
+                hook_items = matcher.get("hooks", [])
+                if not isinstance(hook_items, list):
+                    errors.append(f"hooks.{event_name}.hooks must be list")
+                    continue
+                for hook in hook_items:
+                    if not isinstance(hook, dict):
+                        errors.append(f"hooks.{event_name}.hooks[] must be object")
+                        # hook type/http+SessionStart 语义校验由 loader._build_spec 负责，
+                        # 此处只做结构性检查，不整体拒绝 manifest。
+
+
+__all__ = ["MinimalManifest", "PluginManifest", "PluginManifestSchema", "ValidationError"]