provider-sdk 0.1.0__py3-none-any.whl

provider_sdk/__init__.py

@@ -0,0 +1,39 @@
+"""Provider-V2 平台插件 SDK。
+
+插件作者的唯一依赖入口。插件不得导入 ``src.*``，只能通过本 SDK 与 Host 交互。
+
+核心导出：
+
+- :class:`ProviderPlugin` — 插件基类（生命周期 + 配置）
+- :class:`PlatformAdapter` — 平台适配器抽象接口
+- :class:`PluginContext` — 运行时上下文（日志 / 配置 / HTTP）
+- :class:`PluginConfigBase` — 插件配置模型基类
+- :class:`Candidate` — 网关候选项
+"""
+
+from provider_sdk.config import Field, PluginConfigBase
+from provider_sdk.context import PluginContext
+from provider_sdk.platform import PlatformAdapter
+from provider_sdk.plugin import ProviderPlugin
+from provider_sdk.types import (
+    CONFIG_RELOAD_SCOPE_GLOBAL,
+    CONFIG_RELOAD_SCOPE_SELF,
+    ALL_CAPABILITIES,
+)
+from provider_sdk.types.candidate import Candidate, make_id
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ProviderPlugin",
+    "PlatformAdapter",
+    "PluginContext",
+    "PluginConfigBase",
+    "Field",
+    "Candidate",
+    "make_id",
+    "CONFIG_RELOAD_SCOPE_SELF",
+    "CONFIG_RELOAD_SCOPE_GLOBAL",
+    "ALL_CAPABILITIES",
+    "__version__",
+]

provider_sdk/capabilities/__init__.py

@@ -0,0 +1,73 @@
+"""能力代理：配置、HTTP、日志。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, Optional
+
+import aiohttp
+
+__all__ = ["ConfigCapability", "HttpCapability", "LoggingCapability"]
+
+GetConfigFn = Callable[[str, str], Any]
+GetGlobalConfigFn = Callable[[], Mapping[str, Any]]
+
+
+class LoggingCapability:
+    """插件日志能力。"""
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    @property
+    def logger(self) -> logging.Logger:
+        return self._logger
+
+
+class ConfigCapability:
+    """插件配置读取能力。"""
+
+    def __init__(
+        self,
+        *,
+        get_plugin_config: Callable[[], Mapping[str, Any]],
+        get_global_config: Optional[GetGlobalConfigFn] = None,
+    ) -> None:
+        self._get_plugin_config = get_plugin_config
+        self._get_global_config = get_global_config
+
+    def get_plugin(self) -> dict[str, Any]:
+        """返回当前插件配置字典副本。"""
+        raw = self._get_plugin_config()
+        return dict(raw) if isinstance(raw, Mapping) else {}
+
+    def get_global(self) -> dict[str, Any]:
+        """返回 Host 全局配置字典副本。"""
+        if self._get_global_config is None:
+            return {}
+        raw = self._get_global_config()
+        return dict(raw) if isinstance(raw, Mapping) else {}
+
+    def get(self, section: str, key: str, default: Any = None) -> Any:
+        """读取全局配置中的嵌套键。"""
+        data = self.get_global()
+        node = data.get(section)
+        if isinstance(node, Mapping):
+            return node.get(key, default)
+        return default
+
+
+class HttpCapability:
+    """共享 HTTP 会话能力。"""
+
+    def __init__(self, session: aiohttp.ClientSession) -> None:
+        self._session = session
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        return self._session
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        """对共享会话发起请求。"""
+        return await self._session.request(method, url, **kwargs)

provider_sdk/config.py

@@ -0,0 +1,78 @@
+"""插件配置模型与校验工具。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping
+from typing import Any, ClassVar, TypeVar, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "Field",
+    "PluginConfigBase",
+    "build_plugin_default_config",
+    "is_plugin_config_class",
+    "merge_plugin_config_data",
+    "validate_plugin_config",
+]
+
+PluginConfigT = TypeVar("PluginConfigT", bound="PluginConfigBase")
+
+
+class PluginConfigBase(BaseModel):
+    """插件配置模型基类。
+
+    插件作者继承此类声明配置结构；Host 据此生成默认配置与 WebUI Schema。
+    """
+
+    model_config = ConfigDict(validate_assignment=True, extra="ignore")
+
+    __ui_label__: ClassVar[str] = ""
+    __ui_icon__: ClassVar[str] = ""
+    __ui_order__: ClassVar[int] = 0
+
+
+def is_plugin_config_class(candidate: Any) -> bool:
+    """判断对象是否为插件配置模型类。"""
+    return bool(inspect.isclass(candidate) and issubclass(candidate, PluginConfigBase))
+
+
+def build_plugin_default_config(config_class: type[PluginConfigT]) -> dict[str, Any]:
+    """根据配置模型构造默认配置字典。"""
+    try:
+        instance = config_class()
+    except Exception as exc:
+        raise ValueError(
+            f"插件配置模型 {config_class.__name__} 需要为所有字段提供默认值"
+        ) from exc
+    return instance.model_dump(mode="python")
+
+
+def validate_plugin_config(
+    config_class: type[PluginConfigT],
+    config_data: Mapping[str, Any],
+) -> PluginConfigT:
+    """校验并构造强类型配置实例。"""
+    return config_class.model_validate(dict(config_data))
+
+
+def merge_plugin_config_data(
+    default_config: Mapping[str, Any],
+    raw_config: Mapping[str, Any],
+) -> tuple[dict[str, Any], bool]:
+    """将用户配置递归合并到默认配置之上。"""
+    changed = False
+    merged: dict[str, Any] = dict(default_config)
+
+    for key, value in raw_config.items():
+        base_value = merged.get(key)
+        if isinstance(base_value, Mapping) and isinstance(value, Mapping):
+            nested, nested_changed = merge_plugin_config_data(base_value, value)
+            merged[key] = nested
+            changed = changed or nested_changed or nested != dict(base_value)
+        elif base_value != value:
+            merged[key] = value
+            changed = True
+
+    return merged, changed

provider_sdk/context.py

@@ -0,0 +1,78 @@
+"""插件运行时上下文。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import aiohttp
+
+from provider_sdk.capabilities import ConfigCapability, HttpCapability, LoggingCapability
+
+__all__ = ["HostServices", "PluginContext", "create_plugin_context"]
+
+
+@dataclass
+class HostServices:
+    """Host 注入给 SDK 的运行时服务集合。"""
+
+    session: aiohttp.ClientSession
+    plugin_id: str
+    plugin_dir: str = ""
+    get_plugin_config: Any = None
+    get_global_config: Any = None
+    logger: Optional[logging.Logger] = None
+
+
+class PluginContext:
+    """插件运行时上下文。
+
+    插件通过 ``self.ctx`` 访问日志、配置与 HTTP 会话。
+    """
+
+    def __init__(
+        self,
+        *,
+        plugin_id: str,
+        plugin_dir: str,
+        logger: logging.Logger,
+        config: ConfigCapability,
+        http: HttpCapability,
+    ) -> None:
+        self.plugin_id = plugin_id
+        self.plugin_dir = plugin_dir
+        self.logger = logger
+        self.config = config
+        self.http = http
+
+    @property
+    def paths(self) -> Mapping[str, str]:
+        """插件相关路径。"""
+        return {"plugin_dir": self.plugin_dir}
+
+
+def create_plugin_context(services: HostServices) -> PluginContext:
+    """根据 Host 服务构造插件上下文。"""
+    plugin_id = services.plugin_id
+    logger = services.logger or logging.getLogger(f"provider_sdk.plugin.{plugin_id}")
+
+    def _plugin_config() -> Mapping[str, Any]:
+        if callable(services.get_plugin_config):
+            raw = services.get_plugin_config()
+            return dict(raw) if isinstance(raw, Mapping) else {}
+        return {}
+
+    config_cap = ConfigCapability(
+        get_plugin_config=_plugin_config,
+        get_global_config=services.get_global_config if callable(services.get_global_config) else None,
+    )
+    http_cap = HttpCapability(services.session)
+    return PluginContext(
+        plugin_id=plugin_id,
+        plugin_dir=services.plugin_dir,
+        logger=logger,
+        config=config_cap,
+        http=http_cap,
+    )

provider_sdk/integrate.py

@@ -0,0 +1,51 @@
+"""与 Provider Host 注册表集成的辅助函数。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+import aiohttp
+
+from provider_sdk.runtime.loader import LoadedPlugin, PluginLoader
+
+__all__ = ["load_platform_plugins", "register_loaded_plugins"]
+
+
+async def load_platform_plugins(
+    plugins_root: Path,
+    session: aiohttp.ClientSession,
+    *,
+    host_version: str = "",
+    get_plugin_config: Optional[Callable[[str], Mapping[str, Any]]] = None,
+    get_global_config: Optional[Callable[[], Mapping[str, Any]]] = None,
+    whitelist: Optional[Sequence[str]] = None,
+    blacklist: Optional[Sequence[str]] = None,
+) -> list[LoadedPlugin]:
+    """发现并加载 ``plugins/`` 目录下的平台插件。"""
+    loader = PluginLoader(host_version=host_version, plugin_type_filter="platform")
+    return await loader.discover_and_load(
+        plugins_root,
+        session,
+        get_plugin_config=get_plugin_config,
+        get_global_config=get_global_config,
+        whitelist=whitelist,
+        blacklist=blacklist,
+    )
+
+
+def register_loaded_plugins(registry: Any, loaded: Sequence[LoadedPlugin]) -> None:
+    """将已加载插件的适配器注册到 echotools 风格注册表。
+
+    ``registry`` 需实现 ``register(adapter)`` 或内部 ``_registry.register``。
+    """
+    for record in loaded:
+        adapter = record.adapter
+        if hasattr(registry, "register") and callable(registry.register):
+            registry.register(adapter)
+            continue
+        inner = getattr(registry, "_registry", None)
+        if inner is not None and hasattr(inner, "register"):
+            inner.register(adapter)
+            continue
+        raise TypeError("registry 不支持 register(adapter)")

provider_sdk/platform.py

@@ -0,0 +1,140 @@
+"""平台适配器抽象接口 — 与 Provider Host 内置适配器契约一致。"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, AsyncGenerator, Dict, List, Optional, Union
+
+import aiohttp
+
+from provider_sdk.types.candidate import Candidate
+
+__all__ = ["PlatformAdapter", "DEFAULT_CONTEXT_LENGTH"]
+
+DEFAULT_CONTEXT_LENGTH = 131072
+
+
+class PlatformAdapter(ABC):
+    """所有平台适配器的抽象基类。
+
+  设计原则（与 Host 一致）：
+
+  - ``init()`` 必须立即返回，耗时操作放后台 Task
+  - ``candidates()`` 随时反映真实状态
+  - 可选能力方法有安全默认实现
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """平台标识名（小写，建议与目录名一致）。"""
+        ...
+
+    @property
+    def supported_models(self) -> List[str]:
+        """支持的模型列表。"""
+        return []
+
+    @property
+    def default_capabilities(self) -> Dict[str, bool]:
+        """默认能力字典，用于 ``/v1/models`` 输出。"""
+        return {"chat": True}
+
+    @property
+    def context_length(self) -> Optional[int]:
+        """默认上下文长度。"""
+        return DEFAULT_CONTEXT_LENGTH
+
+    @abstractmethod
+    async def init(self, session: aiohttp.ClientSession) -> None:
+        """初始化适配器，必须立即返回。"""
+        ...
+
+    @abstractmethod
+    async def candidates(self) -> List[Candidate]:
+        """返回当前可用候选项列表。"""
+        ...
+
+    @abstractmethod
+    async def ensure_candidates(self, count: int) -> int:
+        """确保至少有 ``count`` 个候选项可用。"""
+        ...
+
+    @abstractmethod
+    async def complete(
+        self,
+        candidate: Candidate,
+        messages: List[Dict[str, Any]],
+        model: str,
+        stream: bool,
+        *,
+        thinking: bool = False,
+        search: bool = False,
+        **kw: Any,
+    ) -> AsyncGenerator[Union[str, Dict[str, Any]], None]:
+        """聊天补全，yield 文本增量或结构化事件。"""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """关闭适配器并释放资源。"""
+        ...
+
+    async def fetch_remote_models(self) -> List[str]:
+        """拉取远程模型列表。"""
+        return []
+
+    async def create_embedding(
+        self,
+        candidate: Candidate,
+        input_data: Union[str, List[str]],
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        inputs = [input_data] if isinstance(input_data, str) else list(input_data)
+        return {
+            "object": "list",
+            "data": [
+                {"object": "embedding", "index": i, "embedding": []}
+                for i, _ in enumerate(inputs)
+            ],
+            "model": model,
+            "usage": {"prompt_tokens": 0, "total_tokens": 0},
+        }
+
+    async def create_image(
+        self,
+        candidate: Candidate,
+        prompt: str,
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        return {"created": int(time.time()), "data": []}
+
+    async def create_moderation(
+        self,
+        candidate: Candidate,
+        input_data: Union[str, List[str]],
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        inputs = [input_data] if isinstance(input_data, str) else list(input_data)
+        return {
+            "id": f"modr-{uuid.uuid4().hex[:24]}",
+            "model": model,
+            "results": [{"flagged": False, "categories": {}, "category_scores": {}} for _ in inputs],
+        }
+
+    def set_proxy_enabled(self, enabled: bool) -> None:
+        """设置代理覆盖开关（可选）。"""
+        del enabled
+
+    def is_proxy_allowed(self) -> bool:
+        """是否允许代理切换。"""
+        return False
+
+    def is_proxy_enabled(self) -> bool:
+        """当前是否启用代理。"""
+        return False

provider_sdk/plugin.py

@@ -0,0 +1,172 @@
+"""Provider 平台插件基类。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any, ClassVar, Iterable
+
+from provider_sdk.config import (
+    PluginConfigBase,
+    build_plugin_default_config,
+    is_plugin_config_class,
+    merge_plugin_config_data,
+    validate_plugin_config,
+)
+from provider_sdk.context import PluginContext
+from provider_sdk.platform import PlatformAdapter
+from provider_sdk.types import CONFIG_RELOAD_SCOPE_SELF
+
+__all__ = ["ProviderPlugin", "get_platform_adapter", "is_platform_plugin"]
+
+
+class ProviderPlugin:
+    """SDK 平台插件基类。
+
+    用法示例::
+
+        class EchoPlugin(ProviderPlugin, PlatformAdapter):
+            @property
+            def name(self) -> str:
+                return "echo"
+
+            async def on_load(self) -> None:
+                self.ctx.logger.info("echo 插件已加载")
+
+            async def init(self, session):
+                ...
+
+        def create_plugin() -> EchoPlugin:
+            return EchoPlugin()
+    """
+
+    config_reload_subscriptions: ClassVar[Iterable[str]] = ()
+    config_model: ClassVar[type[PluginConfigBase] | None] = None
+
+    def __init__(self) -> None:
+        self._ctx: PluginContext | None = None
+        self._plugin_config_data: dict[str, Any] = {}
+        self._plugin_config_instance: PluginConfigBase | None = None
+
+    @classmethod
+    def get_config_model(cls) -> type[PluginConfigBase] | None:
+        candidate = cls.config_model
+        return candidate if is_plugin_config_class(candidate) else None
+
+    @classmethod
+    def has_config_model(cls) -> bool:
+        return cls.get_config_model() is not None
+
+    @classmethod
+    def build_default_config(cls) -> dict[str, Any]:
+        config_class = cls.get_config_model()
+        if config_class is None:
+            return {}
+        return build_plugin_default_config(config_class)
+
+    def normalize_plugin_config(
+        self,
+        config_data: Mapping[str, Any] | None,
+    ) -> tuple[dict[str, Any], bool]:
+        raw_config: dict[str, Any] = dict(config_data) if isinstance(config_data, Mapping) else {}
+        config_class = type(self).get_config_model()
+        if config_class is None:
+            return raw_config, False
+
+        default_config = type(self).build_default_config()
+        if not raw_config:
+            validated = validate_plugin_config(config_class, default_config)
+            return validated.model_dump(mode="python"), bool(default_config)
+
+        merged, changed = merge_plugin_config_data(default_config, raw_config)
+        validated = validate_plugin_config(config_class, merged)
+        normalized = validated.model_dump(mode="python")
+        return normalized, changed or normalized != merged
+
+    def set_plugin_config(self, config: dict[str, Any]) -> None:
+        normalized, _ = self.normalize_plugin_config(config)
+        self._plugin_config_data = normalized
+
+        config_class = type(self).get_config_model()
+        if config_class is None:
+            self._plugin_config_instance = None
+            return
+
+        try:
+            self._plugin_config_instance = validate_plugin_config(config_class, normalized)
+        except Exception as exc:
+            self._plugin_config_instance = None
+            self._get_logger().warning("插件配置校验失败: %s", exc)
+
+    @property
+    def config(self) -> PluginConfigBase:
+        if not type(self).has_config_model():
+            raise RuntimeError("当前插件未声明 config_model")
+        if self._plugin_config_instance is None:
+            raise RuntimeError("当前插件配置尚未注入")
+        return self._plugin_config_instance
+
+    def get_plugin_config_data(self) -> dict[str, Any]:
+        return dict(self._plugin_config_data)
+
+    @property
+    def ctx(self) -> PluginContext:
+        if self._ctx is None:
+            raise RuntimeError("插件上下文尚未初始化")
+        return self._ctx
+
+    def _set_context(self, ctx: PluginContext) -> None:
+        self._ctx = ctx
+
+    def _get_logger(self) -> logging.Logger:
+        if self._ctx is not None:
+            return self._ctx.logger
+        return logging.getLogger("provider_sdk.plugin")
+
+    async def on_load(self) -> None:
+        """插件加载完成后的生命周期钩子。"""
+
+    async def on_unload(self) -> None:
+        """插件卸载前的生命周期钩子。"""
+
+    async def on_config_update(
+        self,
+        scope: str,
+        config_data: dict[str, object],
+        version: str,
+    ) -> None:
+        """配置热重载回调。
+
+        ``scope`` 为 ``self`` 时表示插件自身 ``config.toml`` 变更。
+        """
+        if scope == CONFIG_RELOAD_SCOPE_SELF:
+            self.set_plugin_config(dict(config_data))
+        del version
+
+
+def is_platform_plugin(instance: Any) -> bool:
+    """判断对象是否为合法的 Provider 平台插件。"""
+    return isinstance(instance, ProviderPlugin)
+
+
+def get_platform_adapter(plugin: ProviderPlugin) -> PlatformAdapter:
+    """从插件实例提取平台适配器。
+
+    插件类可同时继承 :class:`PlatformAdapter`；否则必须实现
+    ``get_adapter()`` 并返回适配器实例。
+
+    Raises:
+        TypeError: 插件未提供平台适配器。
+    """
+    if isinstance(plugin, PlatformAdapter):
+        return plugin
+
+    getter = getattr(plugin, "get_adapter", None)
+    if callable(getter):
+        adapter = getter()
+        if isinstance(adapter, PlatformAdapter):
+            return adapter
+
+    raise TypeError(
+        f"插件 {type(plugin).__name__} 必须继承 PlatformAdapter 或实现 get_adapter()"
+    )

provider_sdk/runtime/__init__.py

@@ -0,0 +1,15 @@
+"""Host 侧插件运行时。"""
+
+from provider_sdk.runtime.loader import (
+    LoadedPlugin,
+    PluginLoadError,
+    PluginLoader,
+    discover_plugin_dirs,
+)
+
+__all__ = [
+    "LoadedPlugin",
+    "PluginLoadError",
+    "PluginLoader",
+    "discover_plugin_dirs",
+]

provider_sdk/runtime/loader.py

@@ -0,0 +1,264 @@
+"""Host 侧插件发现与加载。"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence
+
+import aiohttp
+
+from provider_sdk.context import HostServices, create_plugin_context
+from provider_sdk.plugin import ProviderPlugin, get_platform_adapter, is_platform_plugin
+from provider_sdk.platform import PlatformAdapter
+from provider_sdk.types.manifest import PluginManifest, load_manifest_file
+
+__all__ = [
+    "LoadedPlugin",
+    "PluginLoadError",
+    "PluginLoader",
+    "discover_plugin_dirs",
+]
+
+logger = logging.getLogger("provider_sdk.runtime.loader")
+
+_MANIFEST_NAME = "_manifest.json"
+_ENTRY_MODULE = "plugin.py"
+_FACTORY_NAME = "create_plugin"
+
+
+class PluginLoadError(RuntimeError):
+    """插件加载失败。"""
+
+
+@dataclass
+class LoadedPlugin:
+    """加载成功的插件记录。"""
+
+    manifest: PluginManifest
+    plugin: ProviderPlugin
+    adapter: PlatformAdapter
+    plugin_dir: Path
+    module_name: str
+
+
+def discover_plugin_dirs(plugins_root: Path) -> List[Path]:
+    """扫描插件根目录，返回包含 manifest 的子目录列表。"""
+    root = plugins_root.resolve()
+    if not root.is_dir():
+        return []
+
+    candidates: List[Path] = []
+    for child in sorted(root.iterdir()):
+        if not child.is_dir():
+            continue
+        if child.name.startswith(".") or child.name.startswith("_"):
+            continue
+        if (child / _MANIFEST_NAME).is_file() and (child / _ENTRY_MODULE).is_file():
+            candidates.append(child)
+    return candidates
+
+
+def _topological_sort(manifests: Mapping[str, PluginManifest]) -> List[str]:
+    indegree: Dict[str, int] = {pid: 0 for pid in manifests}
+    graph: Dict[str, List[str]] = {pid: [] for pid in manifests}
+
+    for pid, manifest in manifests.items():
+        for dep in manifest.dependencies:
+            if dep not in manifests:
+                raise PluginLoadError(f"插件 {pid} 依赖未找到的插件: {dep}")
+            graph[dep].append(pid)
+            indegree[pid] += 1
+
+    queue = deque(sorted(pid for pid, deg in indegree.items() if deg == 0))
+    ordered: List[str] = []
+    while queue:
+        current = queue.popleft()
+        ordered.append(current)
+        for nxt in graph[current]:
+            indegree[nxt] -= 1
+            if indegree[nxt] == 0:
+                queue.append(nxt)
+
+    if len(ordered) != len(manifests):
+        raise PluginLoadError("插件依赖存在环")
+    return ordered
+
+
+def _load_entry_module(plugin_dir: Path, plugin_id: str) -> Any:
+    module_name = f"provider_plugin_{plugin_id.replace('.', '_').replace('-', '_')}"
+    entry = plugin_dir / _ENTRY_MODULE
+    spec = importlib.util.spec_from_file_location(module_name, entry)
+    if spec is None or spec.loader is None:
+        raise PluginLoadError(f"无法加载入口模块: {entry}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _validate_lifecycle(plugin: ProviderPlugin) -> None:
+    cls = type(plugin)
+    if cls.on_load is ProviderPlugin.on_load:
+        pass
+    if cls.on_unload is ProviderPlugin.on_unload:
+        pass
+    if cls.on_config_update is ProviderPlugin.on_config_update:
+        pass
+
+
+class PluginLoader:
+    """扫描 ``plugins/`` 目录并加载 SDK 平台插件。"""
+
+    def __init__(
+        self,
+        *,
+        host_version: str = "",
+        plugin_type_filter: str = "platform",
+    ) -> None:
+        self._host_version = host_version
+        self._plugin_type_filter = plugin_type_filter.strip().lower()
+        self._loaded: Dict[str, LoadedPlugin] = {}
+        self._failed: Dict[str, str] = {}
+
+    @property
+    def loaded_plugins(self) -> Dict[str, LoadedPlugin]:
+        return dict(self._loaded)
+
+    @property
+    def failed_plugins(self) -> Dict[str, str]:
+        return dict(self._failed)
+
+    async def discover_and_load(
+        self,
+        plugins_root: Path,
+        session: aiohttp.ClientSession,
+        *,
+        get_plugin_config: Optional[Callable[[str], Mapping[str, Any]]] = None,
+        get_global_config: Optional[Callable[[], Mapping[str, Any]]] = None,
+        whitelist: Optional[Sequence[str]] = None,
+        blacklist: Optional[Sequence[str]] = None,
+    ) -> List[LoadedPlugin]:
+        """发现并加载全部合法插件。"""
+        plugin_dirs = discover_plugin_dirs(plugins_root)
+        manifests: Dict[str, PluginManifest] = {}
+        dir_by_id: Dict[str, Path] = {}
+
+        for plugin_dir in plugin_dirs:
+            try:
+                manifest = load_manifest_file(plugin_dir)
+            except Exception as exc:
+                self._failed[plugin_dir.name] = str(exc)
+                logger.error("manifest 解析失败 [%s]: %s", plugin_dir.name, exc)
+                continue
+
+            if self._plugin_type_filter and manifest.plugin_type != self._plugin_type_filter:
+                continue
+
+            manifests[manifest.id] = manifest
+            dir_by_id[manifest.id] = plugin_dir
+
+        wl = set(whitelist) if whitelist else None
+        bl = set(blacklist or [])
+        ordered_ids = _topological_sort(manifests)
+
+        loaded: List[LoadedPlugin] = []
+        for plugin_id in ordered_ids:
+            manifest = manifests[plugin_id]
+            adapter_name = plugin_id.rsplit(".", 1)[-1]
+
+            if wl is not None and adapter_name not in wl and plugin_id not in wl:
+                continue
+            if adapter_name in bl or plugin_id in bl:
+                continue
+
+            plugin_dir = dir_by_id[plugin_id]
+            try:
+                record = await self._load_one(
+                    plugin_dir,
+                    manifest,
+                    session,
+                    get_plugin_config=get_plugin_config,
+                    get_global_config=get_global_config,
+                )
+            except Exception as exc:
+                self._failed[plugin_id] = str(exc)
+                logger.error("插件加载失败 [%s]: %s", plugin_id, exc)
+                continue
+
+            self._loaded[plugin_id] = record
+            loaded.append(record)
+
+        return loaded
+
+    async def _load_one(
+        self,
+        plugin_dir: Path,
+        manifest: PluginManifest,
+        session: aiohttp.ClientSession,
+        *,
+        get_plugin_config: Optional[Callable[[str], Mapping[str, Any]]] = None,
+        get_global_config: Optional[Callable[[], Mapping[str, Any]]] = None,
+    ) -> LoadedPlugin:
+        module = _load_entry_module(plugin_dir, manifest.id)
+        factory = getattr(module, _FACTORY_NAME, None)
+        if not callable(factory):
+            raise PluginLoadError(f"插件 {manifest.id} 缺少 {_FACTORY_NAME}() 工厂函数")
+
+        instance = factory()
+        if not is_platform_plugin(instance):
+            raise PluginLoadError(f"插件 {manifest.id} 必须返回 ProviderPlugin 实例")
+
+        _validate_lifecycle(instance)
+        adapter = get_platform_adapter(instance)
+
+        if adapter.name != manifest.id.split(".")[-1] and adapter.name != manifest.id:
+            logger.warning(
+                "插件 %s 的 adapter.name=%s 与 manifest id 不完全一致",
+                manifest.id,
+                adapter.name,
+            )
+
+        config_lookup = get_plugin_config or (lambda _pid: {})
+        services = HostServices(
+            session=session,
+            plugin_id=manifest.id,
+            plugin_dir=str(plugin_dir.resolve()),
+            get_plugin_config=lambda: config_lookup(manifest.id),
+            get_global_config=get_global_config,
+        )
+        ctx = create_plugin_context(services)
+        instance._set_context(ctx)
+
+        initial_config = config_lookup(manifest.id)
+        if isinstance(initial_config, Mapping):
+            instance.set_plugin_config(dict(initial_config))
+
+        await instance.on_load()
+        await adapter.init(session)
+
+        return LoadedPlugin(
+            manifest=manifest,
+            plugin=instance,
+            adapter=adapter,
+            plugin_dir=plugin_dir,
+            module_name=module.__name__,
+        )
+
+    async def unload_all(self) -> None:
+        """卸载全部已加载插件。"""
+        for plugin_id, record in list(self._loaded.items()):
+            try:
+                await record.adapter.close()
+            except Exception as exc:
+                logger.warning("关闭适配器失败 [%s]: %s", plugin_id, exc)
+            try:
+                await record.plugin.on_unload()
+            except Exception as exc:
+                logger.warning("on_unload 失败 [%s]: %s", plugin_id, exc)
+        self._loaded.clear()

provider_sdk/types/__init__.py

@@ -0,0 +1,14 @@
+"""类型常量与重载范围定义。"""
+
+from __future__ import annotations
+
+from provider_sdk.types.candidate import ALL_CAPABILITIES
+
+CONFIG_RELOAD_SCOPE_SELF = "self"
+CONFIG_RELOAD_SCOPE_GLOBAL = "global"
+
+__all__ = [
+    "CONFIG_RELOAD_SCOPE_SELF",
+    "CONFIG_RELOAD_SCOPE_GLOBAL",
+    "ALL_CAPABILITIES",
+]

provider_sdk/types/candidate.py

@@ -0,0 +1,138 @@
+"""网关候选项类型 — 与 Provider Host ``Candidate`` 字段对齐。"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+__all__ = ["ALL_CAPABILITIES", "Candidate", "make_id"]
+
+ALL_CAPABILITIES: tuple[str, ...] = (
+    "chat",
+    "vision",
+    "image_gen",
+    "image_edit",
+    "image_variation",
+    "video_gen",
+    "audio_gen",
+    "audio_in",
+    "audio_transcription",
+    "audio_translation",
+    "embedding",
+    "research",
+    "thinking",
+    "search",
+    "code_exec",
+    "artifacts",
+    "tools",
+    "native_tools",
+    "upload",
+    "continuation",
+    "moderation",
+    "rerank",
+    "batch",
+    "fine_tuning",
+    "files",
+    "assistants",
+    "threads",
+    "runs",
+    "vector_stores",
+    "realtime",
+    "responses",
+)
+
+
+def make_id(platform: str, resource_id: str = "") -> str:
+    """生成候选项 ID。
+
+    Args:
+        platform: 平台标识名。
+        resource_id: 平台资源标识；提供时生成确定性 ID。
+
+    Returns:
+        格式为 ``{platform}_{hash12}`` 的 ID。
+    """
+    if resource_id:
+        digest = hashlib.sha256(f"{platform}:{resource_id}".encode()).hexdigest()[:12]
+        return f"{platform}_{digest}"
+    return f"{platform}_{uuid.uuid4().hex[:12]}"
+
+
+@dataclass
+class Candidate:
+    """候选项，包含能力布尔字段与元数据。"""
+
+    id: str
+    platform: str
+    resource_id: str
+
+    chat: bool = False
+    vision: bool = False
+    tools: bool = False
+    native_tools: bool = False
+    thinking: bool = False
+    search: bool = False
+    continuation: bool = False
+
+    image_gen: bool = False
+    image_edit: bool = False
+    image_variation: bool = False
+    video_gen: bool = False
+    audio_gen: bool = False
+
+    audio_in: bool = False
+    audio_transcription: bool = False
+    audio_translation: bool = False
+
+    embedding: bool = False
+    rerank: bool = False
+
+    research: bool = False
+    code_exec: bool = False
+    artifacts: bool = False
+    moderation: bool = False
+    responses: bool = False
+
+    upload: bool = False
+    files: bool = False
+    vector_stores: bool = False
+
+    batch: bool = False
+    fine_tuning: bool = False
+
+    assistants: bool = False
+    threads: bool = False
+    runs: bool = False
+
+    realtime: bool = False
+
+    context_length: Optional[int] = None
+
+    models: List[str] = field(default_factory=list)
+    available: bool = True
+    busy: bool = False
+    cooldown: float = 0.0
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    def has_capability(self, cap: str) -> bool:
+        """检查是否具备指定能力。"""
+        return bool(getattr(self, cap, False))
+
+    def to_model_dict(self, owned_by: str = "") -> Dict[str, Any]:
+        """转换为 ``/v1/models`` 条目格式。"""
+        caps: Dict[str, bool] = {}
+        for cap in ALL_CAPABILITIES:
+            if getattr(self, cap, False):
+                caps[cap] = True
+        result: Dict[str, Any] = {
+            "object": "model",
+            "created": int(time.time()),
+            "owned_by": owned_by or self.platform,
+            "capabilities": caps,
+        }
+        if self.context_length is not None:
+            result["context_length"] = self.context_length
+        return result

provider_sdk/types/manifest.py

@@ -0,0 +1,108 @@
+"""插件 manifest 解析与校验。"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional
+
+__all__ = ["PluginManifest", "parse_manifest", "load_manifest_file"]
+
+_MANIFEST_FILENAME = "_manifest.json"
+_PLUGIN_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{1,126}[a-z0-9]$")
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """``_manifest.json`` 强类型视图。"""
+
+    id: str
+    name: str
+    version: str
+    description: str = ""
+    plugin_type: str = "platform"
+    author: str = ""
+    dependencies: List[str] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+    host_min_version: str = ""
+    host_max_version: str = ""
+    sdk_min_version: str = "0.1.0"
+    sdk_max_version: str = "0.99.99"
+    manifest_version: int = 1
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def plugin_dependency_ids(self) -> List[str]:
+        """依赖插件 ID 列表（``dependencies`` 字段别名）。"""
+        return list(self.dependencies)
+
+
+def _read_author(value: Any) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, Mapping):
+        return str(value.get("name") or "").strip()
+    return ""
+
+
+def _read_dependencies(value: Any) -> List[str]:
+    if not isinstance(value, list):
+        return []
+    out: List[str] = []
+    for item in value:
+        if isinstance(item, str) and item.strip():
+            out.append(item.strip())
+        elif isinstance(item, Mapping):
+            dep_id = str(item.get("id") or item.get("plugin_id") or "").strip()
+            if dep_id:
+                out.append(dep_id)
+    return out
+
+
+def parse_manifest(data: Mapping[str, Any]) -> PluginManifest:
+    """将原始 JSON 映射解析为 :class:`PluginManifest`。
+
+    Raises:
+        ValueError: manifest 缺少必填字段或格式非法。
+    """
+    plugin_id = str(data.get("id") or "").strip()
+    if not plugin_id:
+        raise ValueError("manifest 缺少 id")
+    if not _PLUGIN_ID_RE.match(plugin_id):
+        raise ValueError(f"manifest id 格式非法: {plugin_id}")
+
+    name = str(data.get("name") or plugin_id).strip()
+    version = str(data.get("version") or "0.0.0").strip()
+    host_app = data.get("host_application") if isinstance(data.get("host_application"), Mapping) else {}
+    sdk_info = data.get("sdk") if isinstance(data.get("sdk"), Mapping) else {}
+
+    return PluginManifest(
+        id=plugin_id,
+        name=name,
+        version=version,
+        description=str(data.get("description") or "").strip(),
+        plugin_type=str(data.get("plugin_type") or "platform").strip().lower(),
+        author=_read_author(data.get("author")),
+        dependencies=_read_dependencies(data.get("dependencies")),
+        capabilities=[str(x).strip() for x in (data.get("capabilities") or []) if str(x).strip()],
+        host_min_version=str(host_app.get("min_version") or "").strip(),
+        host_max_version=str(host_app.get("max_version") or "").strip(),
+        sdk_min_version=str(sdk_info.get("min_version") or "0.1.0").strip(),
+        sdk_max_version=str(sdk_info.get("max_version") or "0.99.99").strip(),
+        manifest_version=int(data.get("manifest_version") or 1),
+        raw=dict(data),
+    )
+
+
+def load_manifest_file(plugin_dir: Path) -> PluginManifest:
+    """从插件目录读取 ``_manifest.json``。"""
+    path = plugin_dir / _MANIFEST_FILENAME
+    if not path.is_file():
+        raise FileNotFoundError(f"缺少 {_MANIFEST_FILENAME}: {plugin_dir}")
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, Mapping):
+        raise ValueError(f"manifest 根节点必须是对象: {path}")
+    return parse_manifest(data)

provider_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: provider-sdk
+Version: 0.1.0
+Summary: Provider-V2 平台插件 SDK — 第三方平台适配器开发与加载
+Author: provider-sdk
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nichengfuben/provider-sdk
+Project-URL: Documentation, https://github.com/nichengfuben/provider-sdk/blob/main/docs/guide.md
+Project-URL: Repository, https://github.com/nichengfuben/provider-sdk
+Project-URL: Issues, https://github.com/nichengfuben/provider-sdk/issues
+Keywords: provider,llm,gateway,plugin,sdk,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# provider-sdk
+
+Provider-V2 平台插件 SDK。对标 [maibot-plugin-sdk](https://github.com/Mai-with-u/maibot-plugin-sdk) 的插件契约，为第三方**平台适配器**提供独立开发与加载能力。
+
+## 安装
+
+```bash
+pip install -e X:\Project\provider-sdk
+```
+
+## 快速开始
+
+在 Provider Host 的 `plugins/` 目录下创建插件文件夹：
+
+```
+plugins/
+  my_platform/
+    _manifest.json
+    plugin.py
+    config.toml          # 可选，由 Host 管理
+```
+
+`plugin.py` 最小示例见 [`examples/echo_platform/plugin.py`](examples/echo_platform/plugin.py)。
+
+```python
+from provider_sdk import ProviderPlugin, PlatformAdapter, Candidate, make_id
+
+class MyPlugin(ProviderPlugin, PlatformAdapter):
+    @property
+    def name(self) -> str:
+        return "my_platform"
+
+    async def on_load(self) -> None:
+        self.ctx.logger.info("loaded")
+
+    async def init(self, session): ...
+    async def candidates(self) -> list[Candidate]: ...
+    async def ensure_candidates(self, count: int) -> int: ...
+    async def complete(self, candidate, messages, model, stream, **kw): ...
+    async def close(self) -> None: ...
+
+def create_plugin() -> MyPlugin:
+    return MyPlugin()
+```
+
+## 与 MaiBot SDK 的对应关系
+
+| MaiBot | provider-sdk |
+|--------|----------------|
+| `MaiBotPlugin` | `ProviderPlugin` |
+| `create_plugin()` | `create_plugin()` |
+| `_manifest.json` | `_manifest.json` |
+| `on_load` / `on_unload` / `on_config_update` | 相同 |
+| `self.ctx.send` / `gateway` 等 | `self.ctx.config` / `http` / `logger` |
+| `@Tool` / `@Command` | 平台插件以 `PlatformAdapter` 能力为主 |
+
+## Host 集成
+
+```python
+from pathlib import Path
+from provider_sdk.integrate import load_platform_plugins, register_loaded_plugins
+
+loaded = await load_platform_plugins(Path("plugins"), session)
+register_loaded_plugins(registry, loaded)
+```
+
+完整说明见 [`docs/guide.md`](docs/guide.md)。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```

provider_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+provider_sdk/__init__.py,sha256=_tfZdsO_EM_-poHePu_o_91h0DGOqdZuy8fLlS7rG28,1168
+provider_sdk/config.py,sha256=pgi9DeDtjX0iv6MR1eEK5tNUwyv9arTy2n_10acDab4,2490
+provider_sdk/context.py,sha256=BF4uT6qQbnmMMnMC-0RSD7AWlKzC6L9Pyc1CNY9LpUc,2250
+provider_sdk/integrate.py,sha256=-dySX5DnEPfrGUxEW3CCvM58j4cxm3WULekwcoCEZpA,1850
+provider_sdk/platform.py,sha256=rXPbRPorYYLlmOnQ9o3rMzAD-l0CPkQXszuvwZNCriM,4072
+provider_sdk/plugin.py,sha256=tEMum5CN-xHGsnsc6Tx8CvXGssCxauYTmSyWcXLf8IM,5821
+provider_sdk/capabilities/__init__.py,sha256=WCQqMcNOFGnU9eQsPC4rj0QYpy7rUU4uyNz9IkMrgPs,2235
+provider_sdk/runtime/__init__.py,sha256=dWU2zbaNJOIqrEwAjR-KYDr6B3u4UrVWXHF2siG94lA,282
+provider_sdk/runtime/loader.py,sha256=-87KaYYRu2ly8btOJK9uCC6sqhbkB1FO1YZd1AjgzdQ,9088
+provider_sdk/types/__init__.py,sha256=QpX4KxNbqHL54qgqeGdCmFUWLcIWdBl_edAsxcyUcWk,330
+provider_sdk/types/candidate.py,sha256=MWPK4L9gdGEdxkI4Yzk4TZ5-EBn_7okQ5kHuAJd7y0o,3468
+provider_sdk/types/manifest.py,sha256=WEv3ep_YKyxBo7tV1SaWeJgT8Oq56AKLSCP26VVoqYE,3948
+provider_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=hUIaOfCtc8HRKim1ozd7uE6nPGr4fmfOlY-4rK6lwPs,1103
+provider_sdk-0.1.0.dist-info/METADATA,sha256=6viMG9fsnmHgr308bLg8HGbGjpxel3VSCiYmZMuvJrE,3295
+provider_sdk-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+provider_sdk-0.1.0.dist-info/top_level.txt,sha256=gp3jTnkwS1ISaTgWZLrHyxpiNDiTdcuq-Ze1QXu9ebI,13
+provider_sdk-0.1.0.dist-info/RECORD,,

provider_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

provider_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 provider-sdk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provider_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+provider_sdk