neobot-modloader 1.0.0a7__tar.gz

neobot_modloader-1.0.0a7/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.3
+Name: neobot-modloader
+Version: 1.0.0a7
+Summary: Add your description here
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Dist: neobot-adapter
+Requires-Dist: neobot-contracts
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

neobot_modloader-1.0.0a7/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "neobot-modloader"
+version = "1.0.0-alpha.7"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "neobot-adapter",
+    "neobot-contracts",
+]
+
+[tool.uv.sources]
+neobot-adapter = { workspace = true }
+neobot-contracts = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_modloader-1.0.0a7/src/neobot_modloader/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from neobot_modloader.context import PluginContext
+from neobot_modloader.events import PluginEventBus
+from neobot_modloader.hooks import PluginHookBus
+from neobot_modloader.loader import FilesystemPluginLoader
+from neobot_modloader.manager import DefaultPluginManager
+from neobot_modloader.plugin import BasePlugin
+from neobot_modloader.runtime import PluginRuntime
+
+__all__ = [
+    "BasePlugin",
+    "DefaultPluginManager",
+    "FilesystemPluginLoader",
+    "PluginContext",
+    "PluginEventBus",
+    "PluginHookBus",
+    "PluginRuntime",
+]

neobot_modloader-1.0.0a7/src/neobot_modloader/context.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from pydantic import BaseModel
+
+from neobot_adapter.model.response import SendMsgResponse
+from neobot_contracts.models import ConversationRef
+from neobot_contracts.ports.logging import Logger, NullLogger
+
+from neobot_modloader.events import PluginEventBus
+
+MessagePayload = str | list[dict[str, Any]]
+
+
+class PluginAgentRegistrar:
+    def __init__(
+        self,
+        *,
+        plugin_name: str,
+        registry: Any | None,
+        record_registration: Any | None,
+    ) -> None:
+        self._plugin_name = plugin_name
+        self._registry = registry
+        self._record_registration = record_registration
+        self._registered: dict[str, Any] = {}
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._registered)
+
+    def register(self, name: str, agent: Any) -> str:
+        if self._registry is None:
+            raise RuntimeError("Agent registry is not available")
+        local_name = self._validate_name(name)
+        self._validate_agent(agent)
+        registered_name = self._registered_name(local_name)
+        if registered_name in self._registered:
+            raise ValueError(f"插件 Agent 已注册: {registered_name}")
+        registry_names = getattr(self._registry, "names", [])
+        if registered_name in registry_names:
+            raise ValueError(f"Agent 已注册: {registered_name}")
+        self._registry.register(registered_name, agent)
+        self._registered[registered_name] = agent
+        if self._record_registration is not None:
+            self._record_registration(registered_name, agent)
+        return registered_name
+
+    def unregister(self, registered_name: str) -> Any | None:
+        agent = self._registered.pop(registered_name, None)
+        if self._registry is None:
+            return agent
+        unregister = getattr(self._registry, "unregister", None)
+        if callable(unregister):
+            removed = unregister(registered_name)
+            return removed if removed is not None else agent
+        return agent
+
+    def snapshot(self) -> list[dict[str, str]]:
+        return [
+            {"name": name, "description": str(getattr(agent, "description", ""))}
+            for name, agent in self._registered.items()
+        ]
+
+    def list_agents(self, name: str | None = None) -> str:
+        if name is not None:
+            local_name = self._validate_name(name)
+            registered_name = self._registered_name(local_name)
+            agent = self._registered.get(registered_name)
+            if agent is None:
+                return f"Agent '{registered_name}' not found"
+            return f"Agent {registered_name}: {getattr(agent, 'description', '')}"
+        if not self._registered:
+            return "No agents available"
+        lines = [
+            f"- {registered_name}: {getattr(agent, 'description', '')}"
+            for registered_name, agent in self._registered.items()
+        ]
+        return "Available agents:\n" + "\n".join(lines)
+
+    def _registered_name(self, local_name: str) -> str:
+        return f"plugin:{self._plugin_name}:{local_name}"
+
+    @staticmethod
+    def _validate_name(name: str) -> str:
+        if not isinstance(name, str):
+            raise TypeError("Agent name must be a string")
+        if not name:
+            raise ValueError("Agent name cannot be empty")
+        if name != name.strip():
+            raise ValueError("Agent name cannot contain leading or trailing whitespace")
+        if ":" in name:
+            raise ValueError("Agent name cannot contain ':'")
+        return name
+
+    @staticmethod
+    def _validate_agent(agent: Any) -> None:
+        missing: list[str] = []
+        for attr in ("description", "tool_definitions"):
+            if not hasattr(agent, attr):
+                missing.append(attr)
+        for method in ("invoke", "stream_invoke", "close"):
+            if not callable(getattr(agent, method, None)):
+                missing.append(method)
+        if missing:
+            raise TypeError(f"Plugin agent is missing required attributes: {', '.join(missing)}")
+
+
+class PluginContext:
+    def __init__(
+        self,
+        *,
+        plugin_name: str,
+        plugin_dir: Path,
+        data_dir: Path,
+        config: Mapping[str, Any] | None,
+        logger: Logger | None,
+        adapter: Any,
+        hook_bus: Any | None = None,
+        record_subscription: Any | None = None,
+        agent_registry: Any | None = None,
+        record_agent_registration: Any | None = None,
+    ) -> None:
+        self._plugin_name = plugin_name
+        self._plugin_dir = plugin_dir
+        self._data_dir = data_dir
+        self._config = dict(config or {})
+        self._logger = logger or NullLogger()
+        self._adapter = adapter
+        self._data_dir.mkdir(parents=True, exist_ok=True)
+        self.agents = PluginAgentRegistrar(
+            plugin_name=plugin_name,
+            registry=agent_registry,
+            record_registration=record_agent_registration,
+        )
+        from neobot_modloader.hooks import PluginHookBus
+
+        self.on = PluginEventBus(
+            hook_bus=hook_bus or PluginHookBus(logger=self._logger),
+            logger=self._logger,
+            record_subscription=record_subscription or (lambda _subscription: None),
+        )
+
+    @property
+    def plugin_name(self) -> str:
+        return self._plugin_name
+
+    @property
+    def plugin_dir(self) -> Path:
+        return self._plugin_dir
+
+    @property
+    def data_dir(self) -> Path:
+        return self._data_dir
+
+    @property
+    def config(self) -> Mapping[str, Any]:
+        return self._config
+
+    @property
+    def logger(self) -> Logger:
+        return self._logger
+
+    async def send_private(self, user_id: int, message: MessagePayload) -> SendMsgResponse:
+        return await self._adapter.send_private_msg(user_id, message)
+
+    async def send_group(self, group_id: int, message: MessagePayload) -> SendMsgResponse:
+        return await self._adapter.send_group_msg(group_id, message)
+
+    async def send(
+        self,
+        conversation: ConversationRef,
+        message: MessagePayload,
+    ) -> SendMsgResponse:
+        return await self._adapter.send(conversation, message)
+
+    async def reply(self, event: dict[str, Any] | BaseModel, message: MessagePayload) -> SendMsgResponse:
+        return await self.send(self.conversation_from_event(event), message)
+
+    def message_text(self, event: dict[str, Any] | BaseModel) -> str:
+        data = self._event_to_dict(event)
+        raw_message = data.get("raw_message")
+        if raw_message is not None:
+            return str(raw_message)
+
+        message = data.get("message")
+        if isinstance(message, str):
+            return message
+        if isinstance(message, list):
+            return "".join(self._segment_text(segment) for segment in message)
+        if message is None:
+            return ""
+        return str(message)
+
+    def conversation_from_event(self, event: dict[str, Any] | BaseModel) -> ConversationRef:
+        data = self._event_to_dict(event)
+        message_type = data.get("message_type")
+        if message_type == "private" and data.get("user_id") is not None:
+            return ConversationRef(kind="private", id=str(data["user_id"]))
+        if message_type == "group" and data.get("group_id") is not None:
+            return ConversationRef(kind="group", id=str(data["group_id"]))
+        if data.get("group_id") is not None:
+            return ConversationRef(kind="group", id=str(data["group_id"]))
+        if data.get("user_id") is not None:
+            return ConversationRef(kind="private", id=str(data["user_id"]))
+        raise ValueError(f"无法从事件推断会话: plugin={self.plugin_name}")
+
+    def require_config(self, key: str) -> Any:
+        if key not in self._config:
+            raise KeyError(f"插件 {self.plugin_name!r} 缺少配置项 {key!r}")
+        return self._config[key]
+
+    def _event_to_dict(self, event: dict[str, Any] | BaseModel) -> dict[str, Any]:
+        if isinstance(event, BaseModel):
+            return event.model_dump(mode="python")
+        return dict(event)
+
+    def _segment_text(self, segment: Any) -> str:
+        if isinstance(segment, BaseModel):
+            segment = segment.model_dump(mode="python")
+        if not isinstance(segment, Mapping):
+            return str(segment)
+        if segment.get("type") != "text":
+            return ""
+        data = segment.get("data")
+        if isinstance(data, Mapping):
+            return str(data.get("text", ""))
+        return ""

neobot_modloader-1.0.0a7/src/neobot_modloader/events.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+
+from neobot_modloader.hooks import PluginHookBus, Rule
+
+EventHandler = Callable[..., Any]
+SubscriptionRecorder = Callable[[Any], None]
+
+
+class PluginEventBus:
+    def __init__(
+        self,
+        *,
+        hook_bus: PluginHookBus,
+        logger: Logger | None = None,
+        record_subscription: SubscriptionRecorder | None = None,
+    ) -> None:
+        self._hook_bus = hook_bus
+        self._logger = logger or NullLogger()
+        self._record_subscription = record_subscription or (lambda _subscription: None)
+
+    def message(
+        self,
+        *,
+        group: bool = False,
+        private: bool = False,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+        regex: str | re.Pattern[str] | None = None,
+        keywords: str | Sequence[str] | None = None,
+        contains: str | Sequence[str] | None = None,
+        not_contains: str | Sequence[str] | None = None,
+    ) -> Callable[[EventHandler], EventHandler]:
+        if group and private:
+            raise ValueError("group 和 private 不能同时为 True")
+        message_type = "group" if group else "private" if private else None
+        rule = _build_message_rule(
+            rule=rule,
+            regex=regex,
+            keywords=keywords,
+            contains=contains,
+            not_contains=not_contains,
+        )
+        return self._decorator(
+            post_type="message",
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            message_type=message_type,
+            notice_type=None,
+            request_type=None,
+            meta_event_type=None,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+        )
+
+    def notice(
+        self,
+        notice_type: str | None = None,
+        *,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+    ) -> Callable[[EventHandler], EventHandler]:
+        return self._decorator(
+            post_type="notice",
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            message_type=None,
+            notice_type=notice_type,
+            request_type=None,
+            meta_event_type=None,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+        )
+
+    def request(
+        self,
+        request_type: str | None = None,
+        *,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+    ) -> Callable[[EventHandler], EventHandler]:
+        return self._decorator(
+            post_type="request",
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            message_type=None,
+            notice_type=None,
+            request_type=request_type,
+            meta_event_type=None,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+        )
+
+    def meta_event(
+        self,
+        meta_event_type: str | None = None,
+        *,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+    ) -> Callable[[EventHandler], EventHandler]:
+        return self._decorator(
+            post_type="meta_event",
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            message_type=None,
+            notice_type=None,
+            request_type=None,
+            meta_event_type=meta_event_type,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+        )
+
+    def event(
+        self,
+        *,
+        post_type: str | None = None,
+        message_type: str | None = None,
+        notice_type: str | None = None,
+        request_type: str | None = None,
+        meta_event_type: str | None = None,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+    ) -> Callable[[EventHandler], EventHandler]:
+        return self._decorator(
+            post_type=post_type,
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            message_type=message_type,
+            notice_type=notice_type,
+            request_type=request_type,
+            meta_event_type=meta_event_type,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+        )
+
+    def _decorator(
+        self,
+        *,
+        post_type: str | None,
+        timeout: float | None,
+        block: bool,
+        block_ai_reply: bool,
+        message_type: str | None,
+        notice_type: str | None,
+        request_type: str | None,
+        meta_event_type: str | None,
+        sub_type: str | None,
+        rule: Rule | None,
+        priority: int,
+    ) -> Callable[[EventHandler], EventHandler]:
+        def register(handler: EventHandler) -> EventHandler:
+            subscription = self._hook_bus.subscribe(
+                handler,
+                post_type=post_type,
+                message_type=message_type,
+                notice_type=notice_type,
+                request_type=request_type,
+                meta_event_type=meta_event_type,
+                sub_type=sub_type,
+                rule=rule,
+                priority=priority,
+                timeout=timeout,
+                block=block,
+                block_ai_reply=block_ai_reply,
+                logger=self._logger,
+            )
+            self._record_subscription(subscription)
+            return handler
+
+        return register
+
+
+def _build_message_rule(
+    *,
+    rule: Rule | None,
+    regex: str | re.Pattern[str] | None,
+    keywords: str | Sequence[str] | None,
+    contains: str | Sequence[str] | None,
+    not_contains: str | Sequence[str] | None,
+) -> Rule | None:
+    if regex is None and keywords is None and contains is None and not_contains is None:
+        return rule
+
+    keyword_values = _to_text_list(keywords)
+    contains_values = _to_text_list(contains)
+    not_contains_values = _to_text_list(not_contains)
+    compiled_regex = re.compile(regex) if isinstance(regex, str) else regex
+
+    async def combined(event: dict[str, Any]) -> bool:
+        text = _message_text(event)
+        if compiled_regex is not None and compiled_regex.search(text) is None:
+            return False
+        if keyword_values and not any(keyword in text for keyword in keyword_values):
+            return False
+        if contains_values and not all(value in text for value in contains_values):
+            return False
+        if not_contains_values and any(value in text for value in not_contains_values):
+            return False
+        if rule is None:
+            return True
+        result = rule(event)
+        if inspect.isawaitable(result):
+            result = await result
+        return bool(result)
+
+    return combined
+
+
+def _to_text_list(value: str | Sequence[str] | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(item) for item in value]
+
+
+def _message_text(event: Any) -> str:
+    data = _event_to_dict(event)
+    raw_message = data.get("raw_message")
+    if raw_message is not None:
+        return str(raw_message)
+
+    message = data.get("message")
+    if isinstance(message, str):
+        return message
+    if isinstance(message, list):
+        return "".join(_segment_text(segment) for segment in message)
+    if message is None:
+        return ""
+    return str(message)
+
+
+def _event_to_dict(event: Any) -> dict[str, Any]:
+    if isinstance(event, dict):
+        return event
+    if hasattr(event, "model_dump"):
+        dumped = event.model_dump(mode="python")
+        return dumped if isinstance(dumped, dict) else {}
+    return {}
+
+
+def _segment_text(segment: Any) -> str:
+    if hasattr(segment, "model_dump"):
+        segment = segment.model_dump(mode="python")
+    if not isinstance(segment, dict):
+        return str(segment)
+    if segment.get("type") != "text":
+        return ""
+    data = segment.get("data")
+    if isinstance(data, dict):
+        return str(data.get("text", ""))
+    return ""

neobot_modloader-1.0.0a7/src/neobot_modloader/hooks.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+
+Rule = Callable[[dict[str, Any]], bool | Awaitable[bool]]
+EventHandler = Callable[..., Any]
+ReplyBlockRecorder = Callable[[Any], None]
+
+
+@dataclass
+class HookSubscription:
+    _unsubscribe: Callable[[], None]
+    _active: bool = True
+
+    def unsubscribe(self) -> None:
+        if not self._active:
+            return
+        self._unsubscribe()
+        self._active = False
+
+
+@dataclass(slots=True)
+class HookRegistration:
+    handler: EventHandler
+    post_type: str | None = None
+    message_type: str | None = None
+    notice_type: str | None = None
+    request_type: str | None = None
+    meta_event_type: str | None = None
+    sub_type: str | None = None
+    rule: Rule | None = None
+    priority: int = 0
+    timeout: float | None = None
+    block: bool = False
+    block_ai_reply: bool = False
+    logger: Logger = field(default_factory=NullLogger)
+    event_model: type[BaseModel] | None = None
+
+    def matches(self, event: dict[str, Any]) -> bool:
+        if self.post_type and event.get("post_type") != self.post_type:
+            return False
+        if self.message_type and event.get("message_type") != self.message_type:
+            return False
+        if self.notice_type and event.get("notice_type") != self.notice_type:
+            return False
+        if self.request_type and event.get("request_type") != self.request_type:
+            return False
+        if self.meta_event_type and event.get("meta_event_type") != self.meta_event_type:
+            return False
+        if self.sub_type and event.get("sub_type") != self.sub_type:
+            return False
+        return True
+
+    def coerce(self, event: dict[str, Any]) -> Any:
+        if self.event_model is not None:
+            return self.event_model.model_validate(event)
+        return event
+
+
+class PluginHookBus:
+    def __init__(
+        self,
+        *,
+        logger: Logger | None = None,
+        record_ai_reply_block: ReplyBlockRecorder | None = None,
+    ) -> None:
+        self._logger = logger or NullLogger()
+        self._record_ai_reply_block = record_ai_reply_block
+        self._hooks: list[HookRegistration] = []
+        self._lock = threading.RLock()
+
+    def subscribe(
+        self,
+        handler: EventHandler,
+        *,
+        post_type: str | None = None,
+        message_type: str | None = None,
+        notice_type: str | None = None,
+        request_type: str | None = None,
+        meta_event_type: str | None = None,
+        sub_type: str | None = None,
+        rule: Rule | None = None,
+        priority: int = 0,
+        timeout: float | None = None,
+        block: bool = False,
+        block_ai_reply: bool = False,
+        logger: Logger | None = None,
+    ) -> HookSubscription:
+        registration = HookRegistration(
+            handler=handler,
+            post_type=post_type,
+            message_type=message_type,
+            notice_type=notice_type,
+            request_type=request_type,
+            meta_event_type=meta_event_type,
+            sub_type=sub_type,
+            rule=rule,
+            priority=priority,
+            timeout=timeout,
+            block=block,
+            block_ai_reply=block_ai_reply,
+            logger=logger or self._logger,
+            event_model=_extract_event_model(handler),
+        )
+        with self._lock:
+            self._hooks.append(registration)
+            self._hooks.sort(key=lambda item: item.priority, reverse=True)
+
+        def _unsubscribe() -> None:
+            with self._lock:
+                self._hooks = [item for item in self._hooks if item is not registration]
+
+        return HookSubscription(_unsubscribe)
+
+    async def dispatch(self, ctx: Any) -> None:
+        event = getattr(ctx, "raw_event", None)
+        if not isinstance(event, dict):
+            return
+        with self._lock:
+            hooks = [hook for hook in self._hooks if hook.matches(event)]
+
+        for hook in hooks:
+            if getattr(ctx, "consumed", False):
+                break
+            if hook.rule is not None:
+                try:
+                    rule_result = hook.rule(event)
+                    if inspect.isawaitable(rule_result):
+                        rule_result = await rule_result
+                    if not rule_result:
+                        continue
+                except Exception as exc:
+                    hook.logger.exception(f"插件事件规则执行失败 ({hook.handler.__module__}.{hook.handler.__qualname__}): {exc}")
+                    continue
+
+            try:
+                payload = hook.coerce(event)
+            except Exception as exc:
+                hook.logger.exception(f"插件事件模型转换失败 ({hook.handler.__module__}.{hook.handler.__qualname__}): {exc}")
+                payload = event
+
+            handled = await self._call_hook(hook, payload)
+            if not handled:
+                continue
+
+            if hook.block_ai_reply:
+                block_ai_reply = getattr(ctx, "block_ai_reply", None)
+                if callable(block_ai_reply):
+                    block_ai_reply()
+                if self._record_ai_reply_block is not None:
+                    self._record_ai_reply_block(event)
+            if hook.block:
+                consume = getattr(ctx, "consume", None)
+                if callable(consume):
+                    consume()
+                break
+
+    async def _call_hook(self, hook: HookRegistration, event: Any) -> bool:
+        try:
+            call = _call_handler(hook.handler, event)
+            if hook.timeout is None:
+                await call
+            else:
+                await asyncio.wait_for(call, timeout=hook.timeout)
+            return True
+        except TimeoutError:
+            hook.logger.warning(f"插件事件处理超时: {hook.handler.__module__}.{hook.handler.__qualname__}")
+            return False
+        except Exception as exc:
+            hook.logger.exception(f"插件事件处理失败 ({hook.handler.__module__}.{hook.handler.__qualname__}): {exc}")
+            return False
+
+
+def _extract_event_model(handler: EventHandler) -> type[BaseModel] | None:
+    try:
+        hints = get_type_hints(handler)
+    except Exception:
+        return None
+    params = list(inspect.signature(handler).parameters.values())
+    if not params:
+        return None
+    annotation = hints.get(params[0].name)
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    return None
+
+
+async def _call_handler(handler: EventHandler, event: Any) -> Any:
+    if inspect.iscoroutinefunction(handler):
+        return await handler(event)
+    return await asyncio.to_thread(handler, event)

neobot_modloader-1.0.0a7/src/neobot_modloader/loader.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import re
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+
+from neobot_modloader.plugin import FunctionPlugin
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedPlugin:
+    name: str
+    version: str
+    plugin: Any
+    plugin_dir: Path
+    config: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class PluginLoadError:
+    name: str
+    plugin_dir: Path
+    error: Exception
+
+
+PluginLoadResult = LoadedPlugin | PluginLoadError
+
+
+class FilesystemPluginLoader:
+    def __init__(self, logger: Logger | None = None) -> None:
+        self._logger = logger or NullLogger()
+
+    def load_all(self, plugin_dir: Path) -> list[PluginLoadResult]:
+        plugin_dir = plugin_dir.resolve()
+        if not plugin_dir.exists():
+            self._logger.info(f"插件目录不存在，已按空目录处理: {plugin_dir}")
+            return []
+        if not plugin_dir.is_dir():
+            return [
+                PluginLoadError(
+                    name=plugin_dir.name,
+                    plugin_dir=plugin_dir,
+                    error=NotADirectoryError(str(plugin_dir)),
+                )
+            ]
+
+        results: list[PluginLoadResult] = []
+        for entry in sorted(plugin_dir.iterdir(), key=lambda item: item.name):
+            if entry.name.startswith("_"):
+                continue
+            if entry.is_file() and entry.suffix == ".py":
+                results.append(self._load_file(entry))
+            elif entry.is_dir() and (entry / "__init__.py").is_file():
+                results.append(self._load_package(entry))
+        return results
+
+    def _load_file(self, path: Path) -> PluginLoadResult:
+        name = path.stem
+        try:
+            self._validate_plugin_name(name)
+            module = self._import_module(path, name)
+            plugin = self._create_plugin(module, name=name, version="0.1.0")
+            plugin_name = str(getattr(plugin, "name", name) or name)
+            self._validate_plugin_name(plugin_name)
+            version = str(getattr(plugin, "version", "0.1.0") or "0.1.0")
+            return LoadedPlugin(
+                name=plugin_name,
+                version=version,
+                plugin=plugin,
+                plugin_dir=path.parent,
+                config={},
+            )
+        except Exception as exc:
+            self._logger.exception(f"插件加载失败 ({path}): {exc}")
+            return PluginLoadError(name=name, plugin_dir=path.parent, error=exc)
+
+    def _load_package(self, path: Path) -> PluginLoadResult:
+        manifest_name = path.name
+        try:
+            metadata = self._read_manifest(path / "plugin.toml")
+            name = str(metadata.get("name") or path.name)
+            self._validate_plugin_name(name)
+            version = str(metadata.get("version") or "0.1.0")
+            config = metadata.get("config") or {}
+            if not isinstance(config, dict):
+                raise TypeError("plugin.toml 的 [config] 必须是 table")
+
+            module = self._import_module(path / "__init__.py", name)
+            plugin = self._create_plugin(module, name=name, version=version)
+            plugin_name = str(getattr(plugin, "name", name) or name)
+            self._validate_plugin_name(plugin_name)
+            plugin_version = str(getattr(plugin, "version", version) or version)
+            return LoadedPlugin(
+                name=plugin_name,
+                version=plugin_version,
+                plugin=plugin,
+                plugin_dir=path,
+                config=dict(config),
+            )
+        except Exception as exc:
+            self._logger.exception(f"插件加载失败 ({path}): {exc}")
+            return PluginLoadError(name=manifest_name, plugin_dir=path, error=exc)
+
+    def _read_manifest(self, path: Path) -> dict[str, Any]:
+        if not path.is_file():
+            return {}
+        with path.open("rb") as file:
+            return tomllib.load(file)
+
+    def _import_module(self, path: Path, plugin_name: str) -> ModuleType:
+        module_name = self._module_name(path, plugin_name)
+        sys.modules.setdefault("neobot_user_plugins", ModuleType("neobot_user_plugins"))
+        spec = importlib.util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"无法创建插件模块 spec: {path}")
+        module = importlib.util.module_from_spec(spec)
+        if path.name == "__init__.py":
+            module.__package__ = module_name
+            module.__path__ = [str(path.parent)]
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+        except Exception:
+            sys.modules.pop(module_name, None)
+            raise
+        return module
+
+    def _create_plugin(self, module: ModuleType, *, name: str, version: str) -> Any:
+        setup = getattr(module, "setup", None)
+        if callable(setup):
+            return FunctionPlugin(name=name, version=version, setup=setup)
+
+        plugin = getattr(module, "plugin", None)
+        if plugin is not None:
+            return plugin
+
+        create_plugin = getattr(module, "create_plugin", None)
+        if callable(create_plugin):
+            return create_plugin()
+
+        raise ValueError("插件模块未导出 setup(ctx)、plugin 或 create_plugin()")
+
+    def _module_name(self, path: Path, plugin_name: str) -> str:
+        digest = hashlib.sha1(str(path.resolve()).encode("utf-8")).hexdigest()[:12]
+        safe_name = re.sub(r"\W", "_", plugin_name)
+        return f"neobot_user_plugins.{safe_name}_{digest}"
+
+    def _validate_plugin_name(self, name: str) -> None:
+        if not name:
+            raise ValueError("插件名不能为空")
+        if "/" in name or "\\" in name or name in {".", ".."}:
+            raise ValueError(f"非法插件名: {name!r}")

neobot_modloader-1.0.0a7/src/neobot_modloader/manager.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+from neobot_contracts.ports.plugin import PluginState
+
+
+@dataclass(slots=True)
+class PluginRecord:
+    name: str
+    plugin: Any
+    context: Any
+    state: PluginState = PluginState.UNLOADED
+    subscriptions: list[Any] = field(default_factory=list)
+    agent_registrations: list[tuple[str, Any]] = field(default_factory=list)
+    error: Exception | None = None
+
+
+class DefaultPluginManager:
+    def __init__(self, logger: Logger | None = None) -> None:
+        self._logger = logger or NullLogger()
+        self._records: dict[str, PluginRecord] = {}
+
+    def register(self, plugin: Any, context: Any) -> None:
+        name = context.plugin_name
+        if name in self._records:
+            raise ValueError(f"插件已注册: {name}")
+        self._records[name] = PluginRecord(name=name, plugin=plugin, context=context)
+
+    def get_plugin(self, name: str) -> Any | None:
+        record = self._records.get(name)
+        return record.plugin if record is not None else None
+
+    def get_state(self, name: str) -> PluginState:
+        record = self._records.get(name)
+        return record.state if record is not None else PluginState.UNLOADED
+
+    def get_subscriptions(self, name: str) -> list[Any]:
+        record = self._records.get(name)
+        if record is None:
+            return []
+        return list(record.subscriptions)
+
+    def record_subscription(self, name: str, subscription: Any) -> None:
+        record = self._records.get(name)
+        if record is None:
+            raise KeyError(f"插件未注册: {name}")
+        record.subscriptions.append(subscription)
+
+    def record_agent_registration(self, name: str, registered_name: str, agent: Any) -> None:
+        record = self._records.get(name)
+        if record is None:
+            raise KeyError(f"插件未注册: {name}")
+        record.agent_registrations.append((registered_name, agent))
+
+    async def load_plugin(self, name: str) -> None:
+        record = self._records[name]
+        if record.state not in {PluginState.UNLOADED, PluginState.STOPPED}:
+            return
+        try:
+            await self._maybe_await(record.plugin.on_load(record.context))
+        except Exception as exc:
+            record.error = exc
+            record.state = PluginState.ERROR
+            self._logger.exception(f"插件加载失败 ({name}): {exc}")
+            self._unsubscribe_all(record)
+            await self._cleanup_agents(record)
+            return
+        record.state = PluginState.LOADED
+        record.error = None
+
+    async def start_plugin(self, name: str) -> None:
+        record = self._records[name]
+        if record.state is PluginState.STOPPED:
+            await self.load_plugin(name)
+        if record.state is not PluginState.LOADED:
+            return
+        try:
+            await self._maybe_await(record.plugin.on_start())
+        except Exception as exc:
+            record.error = exc
+            record.state = PluginState.ERROR
+            self._logger.exception(f"插件启动失败 ({name}): {exc}")
+            self._unsubscribe_all(record)
+            await self._cleanup_agents(record)
+            return
+        record.state = PluginState.RUNNING
+        record.error = None
+
+    async def stop_plugin(self, name: str) -> None:
+        record = self._records[name]
+        if record.state in {PluginState.UNLOADED, PluginState.STOPPED}:
+            return
+        should_mark_stopped = record.state is not PluginState.ERROR
+        if record.state in {PluginState.LOADED, PluginState.RUNNING}:
+            try:
+                await self._maybe_await(record.plugin.on_stop())
+            except Exception as exc:
+                record.error = exc
+                self._logger.exception(f"插件停止失败 ({name}): {exc}")
+        self._unsubscribe_all(record)
+        await self._cleanup_agents(record)
+        if should_mark_stopped:
+            record.state = PluginState.STOPPED
+
+    async def load_all(self) -> None:
+        for name in list(self._records):
+            await self.load_plugin(name)
+
+    async def start_all(self) -> None:
+        for name in list(self._records):
+            await self.start_plugin(name)
+
+    async def stop_all(self) -> None:
+        for name in reversed(list(self._records)):
+            await self.stop_plugin(name)
+
+    async def _maybe_await(self, value: Any) -> Any:
+        if inspect.isawaitable(value):
+            return await value
+        return value
+
+    def _unsubscribe_all(self, record: PluginRecord) -> None:
+        subscriptions = record.subscriptions
+        record.subscriptions = []
+        for subscription in subscriptions:
+            try:
+                subscription.unsubscribe()
+            except Exception as exc:
+                self._logger.exception(f"插件订阅清理失败 ({record.name}): {exc}")
+
+    async def _cleanup_agents(self, record: PluginRecord) -> None:
+        registrations = record.agent_registrations
+        record.agent_registrations = []
+        registrar = getattr(record.context, "agents", None)
+        for registered_name, agent in registrations:
+            try:
+                unregister = getattr(registrar, "unregister", None)
+                if callable(unregister):
+                    unregister(registered_name)
+            except Exception as exc:
+                self._logger.exception(f"插件 Agent 注销失败 ({record.name}/{registered_name}): {exc}")
+            try:
+                close = getattr(agent, "close", None)
+                if callable(close):
+                    await self._maybe_await(close())
+            except Exception as exc:
+                self._logger.exception(f"插件 Agent 关闭失败 ({record.name}/{registered_name}): {exc}")

neobot_modloader-1.0.0a7/src/neobot_modloader/plugin.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from neobot_contracts.ports.plugin import PluginContext
+
+
+class BasePlugin:
+    name: str = ""
+    version: str = "0.1.0"
+
+    async def on_load(self, ctx: PluginContext) -> None:
+        pass
+
+    async def on_start(self) -> None:
+        pass
+
+    async def on_stop(self) -> None:
+        pass
+
+
+class FunctionPlugin(BasePlugin):
+    def __init__(
+        self,
+        *,
+        name: str,
+        setup: Callable[[PluginContext], Any],
+        version: str = "0.1.0",
+    ) -> None:
+        self.name = name
+        self.version = version
+        self._setup = setup
+
+    async def on_load(self, ctx: PluginContext) -> None:
+        result = self._setup(ctx)
+        if inspect.isawaitable(result):
+            await result

neobot_modloader-1.0.0a7/src/neobot_modloader/runtime.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from neobot_contracts.ports.logging import Logger, NullLogger
+
+from neobot_modloader.context import PluginContext
+from neobot_modloader.hooks import PluginHookBus
+from neobot_modloader.loader import FilesystemPluginLoader, LoadedPlugin, PluginLoadError
+from neobot_modloader.manager import DefaultPluginManager
+
+
+class PluginRuntime:
+    def __init__(
+        self,
+        *,
+        plugin_dir: Path,
+        data_dir: Path,
+        adapter: Any,
+        logger_factory: Any,
+        loader: FilesystemPluginLoader | None = None,
+        manager: DefaultPluginManager | None = None,
+        logger: Logger | None = None,
+        agent_registry: Any | None = None,
+        hook_bus: PluginHookBus | None = None,
+        record_ai_reply_block: Any | None = None,
+    ) -> None:
+        self.plugin_dir = plugin_dir.resolve()
+        self.data_dir = data_dir.resolve()
+        self.adapter = adapter
+        self.logger_factory = logger_factory
+        self.agent_registry = agent_registry
+        self.record_ai_reply_block = record_ai_reply_block
+        self.logger = logger or self._get_logger("modloader.runtime")
+        self.hook_bus = hook_bus or PluginHookBus(
+            logger=self._get_logger("modloader.hooks"),
+            record_ai_reply_block=record_ai_reply_block,
+        )
+        self.loader = loader or FilesystemPluginLoader(
+            logger=self._get_logger("modloader.loader")
+        )
+        self.manager = manager or DefaultPluginManager(
+            logger=self._get_logger("modloader.manager")
+        )
+
+    def load_all(self) -> None:
+        self.plugin_dir.mkdir(parents=True, exist_ok=True)
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.logger.info(f"插件目录: {self.plugin_dir}")
+
+        results = self.loader.load_all(self.plugin_dir)
+        loaded_count = 0
+        error_count = 0
+        for result in results:
+            if isinstance(result, PluginLoadError):
+                error_count += 1
+                self.logger.error(f"插件加载跳过 ({result.name}): {result.error}")
+                continue
+            self._register(result)
+            loaded_count += 1
+        self.logger.info(f"插件扫描完成: loaded={loaded_count}, errors={error_count}")
+
+    async def load_registered(self) -> None:
+        await self.manager.load_all()
+
+    async def start_all(self) -> None:
+        await self.manager.load_all()
+        await self.manager.start_all()
+
+    async def stop_all(self) -> None:
+        await self.manager.stop_all()
+
+    def _register(self, loaded: LoadedPlugin) -> None:
+        logger = self._get_logger(f"plugin.{loaded.name}")
+        context = PluginContext(
+            plugin_name=loaded.name,
+            plugin_dir=loaded.plugin_dir,
+            data_dir=self.data_dir / loaded.name,
+            config=loaded.config,
+            logger=logger,
+            adapter=self.adapter,
+            hook_bus=self.hook_bus,
+            record_subscription=lambda subscription, name=loaded.name: self.manager.record_subscription(
+                name, subscription
+            ),
+            agent_registry=self.agent_registry,
+            record_agent_registration=lambda registered_name, agent, name=loaded.name: self.manager.record_agent_registration(
+                name, registered_name, agent
+            ),
+        )
+        try:
+            self.manager.register(loaded.plugin, context)
+        except Exception as exc:
+            self.logger.exception(f"插件注册失败 ({loaded.name}): {exc}")
+
+    def _get_logger(self, name: str) -> Logger:
+        get_logger = getattr(self.logger_factory, "get_logger", None)
+        if callable(get_logger):
+            return get_logger(name)
+        return NullLogger()