neobot-modloader 1.0.0__py3-none-any.whl

neobot_modloader/__init__.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from neobot_modloader.agent import AgentRequest
+from neobot_modloader.bot import Bot
+from neobot_modloader.database import (
+    Migration,
+    PluginDatabase,
+    PluginDatabaseClosedError,
+    PluginDatabaseError,
+    PluginDatabaseNotReadyError,
+    PluginMigrationConflictError,
+    PluginMigrationError,
+)
+from neobot_modloader.config_store import (
+    CONFIG_FILENAME as PLUGIN_CONFIG_FILENAME,
+    PluginConfigStore,
+    merge_plugin_config,
+)
+from neobot_modloader.dependency import (
+    PluginDependency,
+    PluginDependencyError,
+    format_dependency,
+    parse_dependencies,
+    parse_dependency,
+    version_satisfies,
+)
+from neobot_modloader.dependencies import PythonDependencyInstaller
+from neobot_modloader.generation import RuntimeGeneration
+from neobot_modloader.hooks import PluginHookBus
+from neobot_modloader.host import DefaultServiceRegistry, PluginHostFacade
+from neobot_modloader.installer import (
+    PROXY_MODES,
+    PluginInstallError,
+    PluginInstallResult,
+    PluginInstaller,
+    PluginUpdateCheck,
+    ProxySettings,
+    RepoSpec,
+    compare_versions,
+)
+from neobot_modloader.loader import DiscoveredPlugin, FilesystemPluginLoader
+from neobot_modloader.loading.models import OFFICIAL_SOURCE, THIRD_PARTY_SOURCE
+from neobot_modloader.management import PluginControlFacade, PluginOperationResult, PluginSnapshot
+from neobot_modloader.state import PluginStateEntry, PluginStateStore
+from neobot_modloader.manager import DefaultPluginManager
+from neobot_modloader.message import AtSegment, ImageSegment, Message, MessageChain, MessageSegment, at, image, text
+from neobot_modloader.plugin import Plugin
+from neobot_modloader.reply import Reply
+from neobot_modloader.runtime import PluginRuntime
+from neobot_modloader.context import RuntimePluginContext
+from neobot_modloader.users import UserDirectory, UserProfile
+from neobot_contracts.ports.screenshot import (
+    FontFace,
+    FontFormat,
+    FontLoadError,
+    ImageFormat,
+    InvalidScreenshotOptions,
+    RenderOptions,
+    ScreenshotError,
+    ScreenshotMode,
+    ScreenshotOptions,
+    ScreenshotPort,
+    ScreenshotResult,
+    ScreenshotTargetNotFound,
+    ScreenshotTimeout,
+    ScreenshotUnavailable,
+)
+
+__all__ = [
+    "AgentRequest",
+    "AtSegment",
+    "Bot",
+    "DefaultPluginManager",
+    "DefaultServiceRegistry",
+    "DiscoveredPlugin",
+    "FilesystemPluginLoader",
+    "OFFICIAL_SOURCE",
+    "PLUGIN_CONFIG_FILENAME",
+    "PROXY_MODES",
+    "PluginInstallError",
+    "PluginInstallResult",
+    "PluginInstaller",
+    "PluginStateEntry",
+    "PluginStateStore",
+    "PluginUpdateCheck",
+    "ProxySettings",
+    "RepoSpec",
+    "THIRD_PARTY_SOURCE",
+    "compare_versions",
+    "ImageSegment",
+    "Message",
+    "MessageChain",
+    "MessageSegment",
+    "PluginDependency",
+    "PluginDependencyError",
+    "format_dependency",
+    "parse_dependencies",
+    "parse_dependency",
+    "version_satisfies",
+    "Migration",
+    "Plugin",
+    "PluginConfigStore",
+    "PluginControlFacade",
+    "PluginDatabase",
+    "PluginDatabaseClosedError",
+    "PluginDatabaseError",
+    "PluginDatabaseNotReadyError",
+    "PluginHookBus",
+    "PluginHostFacade",
+    "PluginMigrationConflictError",
+    "PluginMigrationError",
+    "PluginOperationResult",
+    "PluginRuntime",
+    "PluginSnapshot",
+    "PythonDependencyInstaller",
+    "Reply",
+    "RuntimeGeneration",
+    "RuntimePluginContext",
+    "UserDirectory",
+    "UserProfile",
+    "at",
+    "image",
+    "merge_plugin_config",
+    "text",
+    "FontFace",
+    "FontFormat",
+    "FontLoadError",
+    "ImageFormat",
+    "InvalidScreenshotOptions",
+    "RenderOptions",
+    "ScreenshotError",
+    "ScreenshotMode",
+    "ScreenshotOptions",
+    "ScreenshotPort",
+    "ScreenshotResult",
+    "ScreenshotTargetNotFound",
+    "ScreenshotTimeout",
+    "ScreenshotUnavailable",
+]

neobot_modloader/agent.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AgentRequest:
+    task: str
+    messages: list[dict[str, Any]]
+    delegate_context: str
+    state: dict[str, Any]

neobot_modloader/agent_intent.py

@@ -0,0 +1,89 @@
+"""插件消息处理器的「交主管线」意图通道（spec(5) §1.4 R13/R14 的实现基础）。
+
+背景：`ctx.block_ai_reply()` 只能**拦住** AI 回复，插件消息处理器没有任何
+把控制权**交回**主回复管线（并携带提示词 / 声明预激活技能）的手段。本模块补上
+这条通用能力（不是给小游戏开特例，第三方插件同样可用）：
+
+- 插件在消息处理器里调用 `ctx.agent_reply(background, preactivate=[...])`；
+- 该调用经 `request_agent_reply` 落到**本次事件的 EventContext**上（一次性、
+  随事件对象传递、消费即清除），事件管线再走**既有**的「命令结果触发一次回复」
+  通路，因此不新造管线；
+- `preactivate` 里的技能名会在本轮回复构建工具表时被按需激活，使这些
+  `{plugin}__{tool}` 在该轮模型调用里即可直接调用。
+
+实现说明：处理器拿到的 `ctx` 是插件运行时上下文（每个插件一个、跨事件复用），
+它不知道当前事件，所以这里用 **ContextVar** 在 `PluginHookBus.dispatch` 期间
+绑定当前 EventContext；dispatch 结束后在 finally 里复位。ContextVar 是
+任务/上下文作用域的，不会跨请求串台，也不留进程级可变状态。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from contextvars import ContextVar
+from typing import Any
+
+#: 当前正在分发的事件上下文（由 PluginHookBus.dispatch 绑定；无事件时为 None）
+_CURRENT_EVENT_CONTEXT: ContextVar[Any | None] = ContextVar(
+    "neobot_plugin_current_event_context", default=None
+)
+
+
+def bind_event_context(ctx: Any) -> Any:
+    """绑定当前事件上下文，返回用于复位的 token。"""
+    return _CURRENT_EVENT_CONTEXT.set(ctx)
+
+
+def reset_event_context(token: Any) -> None:
+    """复位事件上下文绑定（必须在 finally 中调用）。"""
+    try:
+        _CURRENT_EVENT_CONTEXT.reset(token)
+    except (ValueError, LookupError):  # pragma: no cover - 跨上下文复位时忽略
+        pass
+
+
+def current_event_context() -> Any | None:
+    return _CURRENT_EVENT_CONTEXT.get()
+
+
+def normalize_preactivate(preactivate: Any) -> tuple[str, ...]:
+    """规范化预激活技能名（去空、去重、保序）。"""
+    if preactivate is None:
+        return ()
+    if isinstance(preactivate, str) or not isinstance(preactivate, Sequence):
+        values = [preactivate]
+    else:
+        values = list(preactivate)
+    seen: list[str] = []
+    for item in values:
+        name = str(item or "").strip()
+        if name and name not in seen:
+            seen.append(name)
+    return tuple(seen)
+
+
+def request_agent_reply(background: Any = "", *, preactivate: Any = ()) -> bool:
+    """请求「把本轮交回主回复管线」。
+
+    返回是否登记成功；**永不抛异常**（消息路径上的任何失败都只是「这次不生效」）。
+    """
+    try:
+        ctx = _CURRENT_EVENT_CONTEXT.get()
+        if ctx is None:
+            return False
+        recorder = getattr(ctx, "agent_reply", None)
+        if not callable(recorder):
+            return False
+        recorder(str(background or ""), preactivate=normalize_preactivate(preactivate))
+        return True
+    except Exception:
+        return False
+
+
+__all__ = [
+    "bind_event_context",
+    "current_event_context",
+    "normalize_preactivate",
+    "request_agent_reply",
+    "reset_event_context",
+]

neobot_modloader/bot.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from neobot_contracts.models import ConversationRef
+
+
+class Bot:
+    """适配器包装类，对外提供稳定的消息发送 API。
+
+    暴露 ``send``、``send_private`` 与 ``send_group``，对插件和依赖注入
+    解析出的处理器隐藏适配器内部实现。
+    """
+
+    def __init__(self, adapter: Any) -> None:
+        self._adapter = adapter
+
+    @property
+    def self_id(self) -> Any:
+        """从适配器获取机器人自身的 ID。"""
+        return getattr(self._adapter, "self_id", None)
+
+    async def send(self, conversation: ConversationRef, message: Any) -> Any:
+        """将 *message* 发送到 *conversation*。
+
+        委托给 ``adapter.send(conversation, message)``。
+        """
+        return await self._adapter.send(conversation, message)
+
+    async def send_private(self, user_id: int, message: Any) -> Any:
+        """将 *message* 发送到由 *user_id* 标识的私聊。
+
+        委托给 ``adapter.send_private_msg(user_id, message)``。
+        """
+        return await self._adapter.send_private_msg(user_id, message)
+
+    async def send_group(self, group_id: int, message: Any) -> Any:
+        """将 *message* 发送到由 *group_id* 标识的群聊。
+
+        委托给 ``adapter.send_group_msg(group_id, message)``。
+        """
+        return await self._adapter.send_group_msg(group_id, message)

neobot_modloader/command_dsl.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from typing import Any
+
+from neobot_modloader.message import AtSegment, ImageSegment, Message, MessageSegment
+
+
+class PatternError(ValueError):
+    pass
+
+
+class PatternMatchError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class PatternElement:
+    kind: str
+    value: str
+    name: str | None = None
+    value_type: str = "str"
+    optional: bool = False
+    list_value: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class PatternMatch:
+    matched: bool
+    values: dict[str, Any]
+    error: str | None = None
+    command_matched: bool = False
+
+
+class MessagePattern:
+    def __init__(
+        self,
+        pattern: str | None = None,
+        *,
+        command: bool = False,
+        aliases: tuple[str, ...] = (),
+        prefix: str = "/",
+    ) -> None:
+        self.pattern = (pattern or "").strip()
+        self.command = command
+        self.aliases = tuple(aliases)
+        self.elements = _parse_pattern(self.pattern)
+        self.prefix = _validate_command_prefix(prefix) if command else prefix
+        if self.command:
+            if not self.elements or self.elements[0].kind != "literal":
+                raise PatternError("command pattern must start with a command name")
+            self.command_name = self.elements[0].value.removeprefix(self.prefix)
+            self.body = self.elements[1:]
+        else:
+            self.command_name = ""
+            self.body = self.elements
+
+    @property
+    def capture_names(self) -> tuple[str, ...]:
+        return tuple(
+            element.name
+            for element in self.elements
+            if element.kind == "param" and element.name is not None
+        )
+
+    @property
+    def usage(self) -> str:
+        return (
+            f"{self.prefix}{self.pattern}"
+            if self.command and not self.pattern.startswith(self.prefix)
+            else self.pattern
+        )
+
+    def match(self, message: Message) -> PatternMatch:
+        tokens = _message_tokens(message)
+        if self.command:
+            command_index = _find_command(tokens, self.prefix)
+            if command_index is None:
+                return PatternMatch(False, {}, command_matched=False)
+            raw = tokens[command_index]
+            assert isinstance(raw, str)
+            command_name = raw.removeprefix(self.prefix)
+            allowed = {
+                self.command_name.lower(),
+                *(alias.removeprefix(self.prefix).lower() for alias in self.aliases),
+            }
+            if command_name.lower() not in allowed:
+                return PatternMatch(False, {}, command_matched=False)
+            try:
+                values = _match_elements(self.body, tokens[command_index + 1 :])
+            except PatternMatchError as exc:
+                return PatternMatch(False, {}, str(exc), command_matched=True)
+            return PatternMatch(True, values, command_matched=True)
+
+        if not self.body:
+            return PatternMatch(True, {}, command_matched=False)
+        try:
+            values = _match_elements(self.body, tokens)
+        except PatternMatchError as exc:
+            return PatternMatch(False, {}, str(exc), command_matched=False)
+        return PatternMatch(True, values, command_matched=False)
+
+
+class RegexPattern:
+    def __init__(
+        self,
+        pattern: str | re.Pattern[str],
+        *,
+        flags: int = 0,
+    ) -> None:
+        if not isinstance(flags, int):
+            raise PatternError("flags must be an integer")
+        if isinstance(pattern, str):
+            try:
+                compiled = re.compile(pattern, flags)
+            except (re.error, ValueError, OverflowError) as exc:
+                raise PatternError(f"invalid regex pattern: {exc}") from exc
+        elif isinstance(pattern, re.Pattern):
+            if flags:
+                raise PatternError(
+                    "flags cannot be applied to an already compiled pattern"
+                )
+            compiled = pattern
+        else:
+            raise PatternError(
+                "regex pattern must be a string or a compiled pattern"
+            )
+        if not isinstance(compiled.pattern, str):
+            raise PatternError("regex pattern must be a string pattern")
+        if not compiled.pattern.strip():
+            raise PatternError("regex pattern cannot be empty")
+        self.pattern = compiled
+
+    @property
+    def capture_names(self) -> tuple[str, ...]:
+        return tuple(sorted(self.pattern.groupindex))
+
+    @property
+    def usage(self) -> str:
+        return self.pattern.pattern
+
+    def match(self, message: Message) -> PatternMatch:
+        match = self.pattern.search(message.text)
+        if match is None:
+            return PatternMatch(False, {})
+        return PatternMatch(
+            True, {name: match.group(name) for name in self.capture_names}
+        )
+
+
+def _parse_pattern(pattern: str) -> list[PatternElement]:
+    if not pattern:
+        return []
+    try:
+        tokens = shlex.split(pattern, posix=True)
+    except ValueError as exc:
+        raise PatternError(str(exc)) from exc
+
+    elements: list[PatternElement] = []
+    capture_names: set[str] = set()
+    for token in tokens:
+        if token.startswith("<") and token.endswith(">"):
+            element = _parse_param(token[1:-1], optional=False)
+        elif token.startswith("[") and token.endswith("]"):
+            element = _parse_param(token[1:-1], optional=True)
+        else:
+            element = PatternElement(kind="literal", value=token)
+        if element.name is not None:
+            if element.name in capture_names:
+                raise PatternError(f"duplicate parameter name: {element.name}")
+            capture_names.add(element.name)
+        elements.append(element)
+    return elements
+
+
+def _parse_param(raw: str, *, optional: bool) -> PatternElement:
+    if ":" in raw:
+        name, value_type = raw.split(":", 1)
+    else:
+        name, value_type = raw, "str"
+    name = name.strip()
+    value_type = value_type.strip()
+    if not name:
+        raise PatternError("parameter name cannot be empty")
+    list_value = value_type.startswith("list[") and value_type.endswith("]")
+    if list_value:
+        value_type = value_type[5:-1].strip()
+    if value_type not in {"str", "int", "float", "bool", "rest", "image", "at"}:
+        raise PatternError(f"unsupported parameter type: {value_type}")
+    return PatternElement(
+        kind="param",
+        value=raw,
+        name=name,
+        value_type=value_type,
+        optional=optional,
+        list_value=list_value,
+    )
+
+
+def _message_tokens(message: Message) -> list[str | MessageSegment]:
+    tokens: list[str | MessageSegment] = []
+    for segment in message.segments:
+        if segment.type == "text":
+            tokens.extend(_split_text(segment.text))
+        else:
+            tokens.append(segment)
+    return tokens
+
+
+def _split_text(value: str) -> list[str]:
+    try:
+        return shlex.split(value, posix=True)
+    except ValueError:
+        return value.split()
+
+
+def _find_command(
+    tokens: list[str | MessageSegment], prefix: str = "/"
+) -> int | None:
+    for index, token in enumerate(tokens):
+        if isinstance(token, str) and token.startswith(prefix) and len(token) > len(prefix):
+            return index
+    return None
+
+
+def _validate_command_prefix(prefix: str) -> str:
+    if not isinstance(prefix, str):
+        raise PatternError("command prefix must be a string")
+    if any(char.isspace() for char in prefix):
+        raise PatternError("command prefix cannot contain whitespace")
+    return prefix
+
+
+def _match_elements(
+    elements: list[PatternElement], tokens: list[str | MessageSegment]
+) -> dict[str, Any]:
+    values: dict[str, Any] = {}
+    index = 0
+    for element in elements:
+        if element.kind == "literal":
+            index = _match_literal(element.value, tokens, index)
+            continue
+        assert element.name is not None
+        value, index = _capture(element, tokens, index)
+        values[element.name] = value
+    return values
+
+
+def _match_literal(literal: str, tokens: list[str | MessageSegment], start: int) -> int:
+    for index in range(start, len(tokens)):
+        token = tokens[index]
+        if isinstance(token, str) and token.lower() == literal.lower():
+            return index + 1
+        if not isinstance(token, str):
+            continue
+        break
+    raise PatternMatchError(f"expected {literal!r}")
+
+
+def _capture(
+    element: PatternElement,
+    tokens: list[str | MessageSegment],
+    start: int,
+) -> tuple[Any, int]:
+    if element.value_type == "image":
+        return _capture_image(element, tokens, start)
+    if element.value_type == "at":
+        return _capture_at(element, tokens, start)
+    if element.value_type == "rest":
+        rest = " ".join(token for token in tokens[start:] if isinstance(token, str))
+        if not rest and not element.optional:
+            raise PatternMatchError(f"missing required parameter {element.name}")
+        return (rest or None if element.optional else rest), len(tokens)
+
+    index = _next_text_token(tokens, start)
+    if index is None:
+        if element.optional:
+            return None, start
+        raise PatternMatchError(f"missing required parameter {element.name}")
+    token = tokens[index]
+    assert isinstance(token, str)
+    return _coerce_text(token, element), index + 1
+
+
+def _capture_image(
+    element: PatternElement,
+    tokens: list[str | MessageSegment],
+    start: int,
+) -> tuple[Any, int]:
+    images: list[ImageSegment] = []
+    first_index: int | None = None
+    last_index = start
+    for index in range(start, len(tokens)):
+        token = tokens[index]
+        if isinstance(token, ImageSegment):
+            if first_index is None:
+                first_index = index
+            images.append(token)
+            last_index = index + 1
+            if not element.list_value:
+                break
+    if element.list_value:
+        if not images and not element.optional:
+            raise PatternMatchError(f"missing required image parameter {element.name}")
+        return images, last_index if images else start
+    if first_index is None:
+        if element.optional:
+            return None, start
+        raise PatternMatchError(f"missing required image parameter {element.name}")
+    return images[0], last_index
+
+
+def _capture_at(
+    element: PatternElement,
+    tokens: list[str | MessageSegment],
+    start: int,
+) -> tuple[Any, int]:
+    ats: list[AtSegment] = []
+    first_index: int | None = None
+    last_index = start
+    for index in range(start, len(tokens)):
+        token = tokens[index]
+        if isinstance(token, AtSegment):
+            if first_index is None:
+                first_index = index
+            ats.append(token)
+            last_index = index + 1
+            if not element.list_value:
+                break
+        elif not isinstance(token, str):
+            break
+    if element.list_value:
+        if not ats and not element.optional:
+            raise PatternMatchError(f"missing required at parameter {element.name}")
+        return ats, last_index if ats else start
+    if first_index is None:
+        if element.optional:
+            return None, start
+        raise PatternMatchError(f"missing required at parameter {element.name}")
+    return ats[0], last_index
+
+
+def _next_text_token(tokens: list[str | MessageSegment], start: int) -> int | None:
+    for index in range(start, len(tokens)):
+        if isinstance(tokens[index], str):
+            return index
+    return None
+
+
+def _coerce_text(value: str, element: PatternElement) -> Any:
+    try:
+        if element.value_type == "str":
+            return value
+        if element.value_type == "int":
+            return int(value)
+        if element.value_type == "float":
+            return float(value)
+        if element.value_type == "bool":
+            return _coerce_bool(value)
+    except ValueError as exc:
+        raise PatternMatchError(f"invalid value for {element.name}: {value!r}") from exc
+    raise PatternMatchError(f"unsupported parameter type: {element.value_type}")
+
+
+def _coerce_bool(value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "n", "off"}:
+        return False
+    raise ValueError(value)