tg-bot-plugin-sdk 0.2.0__py3-none-any.whl

tg_bot_plugin_sdk/__init__.py

@@ -0,0 +1,88 @@
+"""TG-BOT 插件作者侧 SDK。"""
+
+from .capability import (
+    CAPABILITY_CONCURRENCY_ASYNC_SIDECAR,
+    CAPABILITY_CONCURRENCY_ASYNC_TERMINAL,
+    CAPABILITY_CONCURRENCY_SYNC_SESSION,
+    CAPABILITY_KIND_EVENT,
+    CAPABILITY_KIND_INVOKE,
+    PluginCapabilitySpec,
+    event_capability,
+    invoke_capability,
+    project_plugin_capability_contract,
+    resolve_plugin_capability_specs,
+)
+from .content import PluginContent
+from .context import (
+    BackgroundTaskHandle,
+    BackgroundTaskObserver,
+    EventCapabilityContext,
+    PluginContext,
+    PluginAdminOpsSink,
+    PluginDurableTaskHandler,
+    PluginScheduler,
+    PluginTaskQueueProtocol,
+    ScheduledTaskHandle,
+)
+from .exceptions import CapabilityDeclarationError, PluginError, SdkContractError
+from .externalize import (
+    DEFAULT_EXTERNALIZE_RELATIVE_PATH,
+    externalize_manifest_capability_contract,
+    project_manifest_capability_contract,
+)
+from .admin_ops import PluginAdminOps
+from .plugin import BasePlugin
+from .governance import GovernanceActionResult, PluginGovernance
+from .providers import PluginProviderHandler, PluginProviders, ProviderCallError
+from .runtime import (
+    CapabilityResult,
+    ManagedResourceAccessError,
+    ManagedDataDomainRoute,
+    ManagedResourceContext,
+    ManagedResourceHandle,
+    ManagedStorageProfileSummary,
+    RuntimeCapabilityInvocation,
+)
+
+__all__ = [
+    "BasePlugin",
+    "BackgroundTaskHandle",
+    "BackgroundTaskObserver",
+    "CAPABILITY_CONCURRENCY_ASYNC_SIDECAR",
+    "CAPABILITY_CONCURRENCY_ASYNC_TERMINAL",
+    "CAPABILITY_CONCURRENCY_SYNC_SESSION",
+    "CAPABILITY_KIND_EVENT",
+    "CAPABILITY_KIND_INVOKE",
+    "CapabilityDeclarationError",
+    "CapabilityResult",
+    "DEFAULT_EXTERNALIZE_RELATIVE_PATH",
+    "EventCapabilityContext",
+    "GovernanceActionResult",
+    "ManagedDataDomainRoute",
+    "ManagedResourceAccessError",
+    "ManagedResourceContext",
+    "ManagedResourceHandle",
+    "ManagedStorageProfileSummary",
+    "PluginAdminOps",
+    "PluginAdminOpsSink",
+    "PluginCapabilitySpec",
+    "PluginContent",
+    "PluginContext",
+    "PluginDurableTaskHandler",
+    "PluginError",
+    "PluginGovernance",
+    "PluginProviderHandler",
+    "PluginProviders",
+    "PluginScheduler",
+    "PluginTaskQueueProtocol",
+    "ProviderCallError",
+    "RuntimeCapabilityInvocation",
+    "ScheduledTaskHandle",
+    "SdkContractError",
+    "event_capability",
+    "externalize_manifest_capability_contract",
+    "invoke_capability",
+    "project_manifest_capability_contract",
+    "project_plugin_capability_contract",
+    "resolve_plugin_capability_specs",
+]

tg_bot_plugin_sdk/admin_ops.py

@@ -0,0 +1,134 @@
+"""Author-facing admin_ops facade with binding-scoped runtime helper semantics."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _clone_json(payload: Any) -> Any:
+    return json.loads(json.dumps(payload, ensure_ascii=True, default=str))
+
+
+def _clone_mapping(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, Mapping):
+        return {}
+    cloned = _clone_json(dict(payload))
+    if isinstance(cloned, dict):
+        return cloned
+    return {}
+
+
+class PluginAdminOps:
+    """Expose minimal admin_ops helper surfaces without freezing storage internals."""
+
+    def __init__(self, ctx: Any) -> None:
+        self._ctx = ctx
+
+    def is_available(self) -> bool:
+        return callable(getattr(self._ctx, "_admin_ops_sink", None))
+
+    def _sink(self) -> Any:
+        sink = getattr(self._ctx, "_admin_ops_sink", None)
+        if callable(sink):
+            return sink
+        return None
+
+    def _resource_scope(self) -> str:
+        resource_context = getattr(self._ctx, "resource_context", None)
+        return str(getattr(resource_context, "scope", "") or "").strip()
+
+    def _business_space(self) -> dict[str, Any]:
+        resource_context = getattr(self._ctx, "resource_context", None)
+        return _clone_mapping(getattr(resource_context, "business_space", {}))
+
+    def _resolve_dimension(self, payload: Mapping[str, Any], field_name: str, fallback: str = "") -> str:
+        normalized_value = str(payload.get(field_name) or fallback or "").strip()
+        if not normalized_value:
+            raise ValueError(f"{field_name} is required")
+        return normalized_value
+
+    def _resolve_bot_id(self, payload: Mapping[str, Any]) -> str:
+        return self._resolve_dimension(
+            payload,
+            "bot_id",
+            fallback=str(getattr(self._ctx, "bot_id", "") or "").strip(),
+        )
+
+    def _resolve_resource_id(self, payload: Mapping[str, Any]) -> str:
+        resource_context = getattr(self._ctx, "resource_context", None)
+        fallback = str(getattr(resource_context, "resource_id", "") or "").strip()
+        return self._resolve_dimension(payload, "resource_id", fallback=fallback)
+
+    def _resolve_binding_id(self, payload: Mapping[str, Any]) -> str:
+        resource_context = getattr(self._ctx, "resource_context", None)
+        fallback = str(getattr(resource_context, "binding_id", "") or "").strip()
+        return self._resolve_dimension(payload, "binding_id", fallback=fallback)
+
+    def _build_entry(self, event_kind: str, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        normalized_payload = _clone_mapping(payload or {})
+        entry = {
+            "event_kind": str(event_kind or "").strip(),
+            "plugin_name": str(getattr(self._ctx, "plugin_name", "") or "").strip(),
+            "plugin_id": str(getattr(self._ctx, "plugin_id", "") or "").strip(),
+            "bot_id": self._resolve_bot_id(normalized_payload),
+            "resource_id": self._resolve_resource_id(normalized_payload),
+            "binding_id": self._resolve_binding_id(normalized_payload),
+        }
+        scope = self._resource_scope()
+        if scope:
+            entry["scope"] = scope
+        business_space = self._business_space()
+        if business_space:
+            entry["business_space"] = business_space
+        normalized_payload.setdefault("bot_id", entry["bot_id"])
+        normalized_payload.setdefault("resource_id", entry["resource_id"])
+        normalized_payload.setdefault("binding_id", entry["binding_id"])
+        entry["payload"] = normalized_payload
+        return entry
+
+    async def _persist_entry(self, entry: dict[str, Any]) -> dict[str, Any]:
+        sink = self._sink()
+        if sink is None:
+            raise RuntimeError("admin_ops sink is unavailable")
+        try:
+            result = sink(_clone_mapping(entry))
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            logger.exception(
+                "Failed to persist admin_ops event=%s plugin=%s",
+                str(entry.get("event_kind") or "").strip(),
+                str(getattr(self._ctx, "plugin_name", "") or "").strip(),
+            )
+            raise
+        return entry
+
+    def build_operation_log_entry(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self._build_entry("operation_log", payload)
+
+    def build_bot_log_entry(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self._build_entry("bot_log", payload)
+
+    def build_name_change_event_entry(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self._build_entry("name_change_event", payload)
+
+    def build_permission_event_entry(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return self._build_entry("permission_event", payload)
+
+    async def write_operation_log(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return await self._persist_entry(self.build_operation_log_entry(payload))
+
+    async def write_bot_log(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return await self._persist_entry(self.build_bot_log_entry(payload))
+
+    async def write_name_change_event(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return await self._persist_entry(self.build_name_change_event_entry(payload))
+
+    async def write_permission_event(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        return await self._persist_entry(self.build_permission_event_entry(payload))

tg_bot_plugin_sdk/capability.py

@@ -0,0 +1,320 @@
+"""作者侧 capability 真源模型。"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .exceptions import CapabilityDeclarationError, SdkContractError
+
+CAPABILITY_KIND_INVOKE = "invoke"
+CAPABILITY_KIND_EVENT = "event"
+CAPABILITY_CONCURRENCY_SYNC_SESSION = "sync_session"
+CAPABILITY_CONCURRENCY_ASYNC_SIDECAR = "async_sidecar"
+CAPABILITY_CONCURRENCY_ASYNC_TERMINAL = "async_terminal"
+DEFAULT_CAPABILITY_CONCURRENCY_CLASS = CAPABILITY_CONCURRENCY_SYNC_SESSION
+DEFAULT_SUPPORTED_CHAT_TYPES = ("private", "group", "supergroup", "channel")
+DEFAULT_FOLLOW_UP_ACTOR_MODES = ("inherit_root_actor",)
+VALID_CONCURRENCY_CLASSES = frozenset(
+    {
+        CAPABILITY_CONCURRENCY_SYNC_SESSION,
+        CAPABILITY_CONCURRENCY_ASYNC_SIDECAR,
+        CAPABILITY_CONCURRENCY_ASYNC_TERMINAL,
+    }
+)
+VALID_ASYNC_IDEMPOTENCY_STRATEGIES = frozenset({"update_id", "message_revision"})
+
+
+def _clone_json_value(value: Any) -> Any:
+    if value in (None, ""):
+        return None
+    return json.loads(json.dumps(value, ensure_ascii=True, default=str))
+
+
+def _clone_json_object(value: Any) -> dict[str, Any] | None:
+    if value in (None, ""):
+        return None
+    cloned = _clone_json_value(value)
+    if isinstance(cloned, dict):
+        return cloned
+    raise SdkContractError("capability_json_invalid", "capability json object fields must be objects")
+
+
+def _normalize_json_tuple(values: Any) -> tuple[dict[str, Any], ...]:
+    if values in (None, ""):
+        return ()
+    if not isinstance(values, (list, tuple)):
+        raise SdkContractError("capability_json_invalid", "capability json tuple fields must be arrays")
+    result: list[dict[str, Any]] = []
+    for item in values:
+        cloned = _clone_json_object(item)
+        if cloned is not None:
+            result.append(cloned)
+    result.sort(key=lambda item: json.dumps(item, ensure_ascii=True, sort_keys=True))
+    return tuple(result)
+
+
+def _normalize_string_tuple(values: Any) -> tuple[str, ...]:
+    if values in (None, ""):
+        return ()
+    if isinstance(values, str):
+        values = [values]
+    result: list[str] = []
+    seen: set[str] = set()
+    for item in values:
+        normalized = str(item or "").strip()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        result.append(normalized)
+    result.sort()
+    return tuple(result)
+
+
+def _normalize_concurrency_class(value: Any) -> str:
+    normalized = str(value or "").strip().lower() or DEFAULT_CAPABILITY_CONCURRENCY_CLASS
+    if normalized not in VALID_CONCURRENCY_CLASSES:
+        raise SdkContractError(
+            "capability_concurrency_class_invalid",
+            f"unsupported concurrency_class: {normalized}",
+        )
+    return normalized
+
+
+@dataclass(frozen=True, slots=True)
+class PluginCapabilitySpec:
+    capability_id: str
+    description: str
+    title: str = ""
+    label: str = ""
+    kind: str = CAPABILITY_KIND_INVOKE
+    allowed_surfaces: tuple[str, ...] = ()
+    supported_chat_types: tuple[str, ...] = DEFAULT_SUPPORTED_CHAT_TYPES
+    input_schema: dict[str, Any] | None = None
+    output_schema: dict[str, Any] | None = None
+    result_schema: dict[str, Any] | None = None
+    filter_schema: dict[str, Any] | None = None
+    trigger_types: tuple[str, ...] = ()
+    concurrency_class: str = DEFAULT_CAPABILITY_CONCURRENCY_CLASS
+    delivery_mode: str = ""
+    idempotency_strategy: str = ""
+    presentations: tuple[dict[str, Any], ...] = ()
+    required_bot_admin_rights: tuple[str, ...] = ()
+    required_chat_traits: dict[str, Any] | None = None
+    privacy_mode_requirement: str = "any"
+    resource_override_slots: tuple[str, ...] = ()
+    follow_up_actor_modes: tuple[str, ...] = DEFAULT_FOLLOW_UP_ACTOR_MODES
+    requires_managed_webapp_auth_context: bool = False
+    allow_resource_override: bool = False
+    variables: tuple[dict[str, Any], ...] = ()
+    default_template: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "capability_id", str(self.capability_id or "").strip())
+        object.__setattr__(self, "description", str(self.description or "").strip())
+        object.__setattr__(self, "title", str(self.title or "").strip())
+        object.__setattr__(self, "label", str(self.label or "").strip())
+        if self.title and not self.label:
+            object.__setattr__(self, "label", self.title)
+        if self.label and not self.title:
+            object.__setattr__(self, "title", self.label)
+        object.__setattr__(self, "kind", CAPABILITY_KIND_EVENT if self.kind == CAPABILITY_KIND_EVENT else CAPABILITY_KIND_INVOKE)
+        object.__setattr__(self, "allowed_surfaces", _normalize_string_tuple(self.allowed_surfaces))
+        object.__setattr__(
+            self,
+            "supported_chat_types",
+            _normalize_string_tuple(self.supported_chat_types or DEFAULT_SUPPORTED_CHAT_TYPES),
+        )
+        object.__setattr__(self, "input_schema", _clone_json_object(self.input_schema))
+        object.__setattr__(self, "output_schema", _clone_json_object(self.output_schema))
+        object.__setattr__(self, "result_schema", _clone_json_object(self.result_schema))
+        object.__setattr__(self, "filter_schema", _clone_json_object(self.filter_schema))
+        object.__setattr__(self, "trigger_types", _normalize_string_tuple(self.trigger_types))
+        object.__setattr__(self, "concurrency_class", _normalize_concurrency_class(self.concurrency_class))
+        object.__setattr__(self, "delivery_mode", str(self.delivery_mode or "").strip().lower())
+        object.__setattr__(self, "idempotency_strategy", str(self.idempotency_strategy or "").strip().lower())
+        object.__setattr__(self, "presentations", _normalize_json_tuple(self.presentations))
+        object.__setattr__(self, "required_bot_admin_rights", _normalize_string_tuple(self.required_bot_admin_rights))
+        object.__setattr__(self, "required_chat_traits", _clone_json_object(self.required_chat_traits))
+        object.__setattr__(self, "privacy_mode_requirement", str(self.privacy_mode_requirement or "any").strip() or "any")
+        object.__setattr__(self, "resource_override_slots", _normalize_string_tuple(self.resource_override_slots))
+        object.__setattr__(self, "follow_up_actor_modes", _normalize_string_tuple(self.follow_up_actor_modes or DEFAULT_FOLLOW_UP_ACTOR_MODES))
+        object.__setattr__(self, "requires_managed_webapp_auth_context", bool(self.requires_managed_webapp_auth_context))
+        object.__setattr__(self, "allow_resource_override", bool(self.allow_resource_override or self.resource_override_slots))
+        object.__setattr__(self, "variables", _normalize_json_tuple(self.variables))
+        object.__setattr__(self, "default_template", _clone_json_object(self.default_template))
+
+    def to_contract_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "capability_id": self.capability_id,
+            "kind": self.kind,
+            "description": self.description,
+            "supported_chat_types": list(self.supported_chat_types),
+            "allow_resource_override": bool(self.allow_resource_override),
+            "variables": [dict(item) for item in self.variables],
+        }
+        if self.title:
+            payload["title"] = self.title
+        if self.label:
+            payload["label"] = self.label
+        if self.allowed_surfaces:
+            payload["allowed_surfaces"] = list(self.allowed_surfaces)
+        if self.input_schema:
+            payload["input_schema"] = dict(self.input_schema)
+        if self.output_schema:
+            payload["output_schema"] = dict(self.output_schema)
+        if self.result_schema:
+            payload["result_schema"] = dict(self.result_schema)
+        if self.filter_schema:
+            payload["filter_schema"] = dict(self.filter_schema)
+        if self.trigger_types:
+            payload["trigger_types"] = list(self.trigger_types)
+        payload["concurrency_class"] = self.concurrency_class
+        if self.delivery_mode:
+            payload["delivery_mode"] = self.delivery_mode
+        if self.idempotency_strategy:
+            payload["idempotency_strategy"] = self.idempotency_strategy
+        if self.presentations:
+            payload["presentations"] = [dict(item) for item in self.presentations]
+        if self.required_bot_admin_rights:
+            payload["required_bot_admin_rights"] = list(self.required_bot_admin_rights)
+        if self.required_chat_traits:
+            payload["required_chat_traits"] = dict(self.required_chat_traits)
+        if self.privacy_mode_requirement:
+            payload["privacy_mode_requirement"] = self.privacy_mode_requirement
+        if self.resource_override_slots:
+            payload["resource_override_slots"] = list(self.resource_override_slots)
+        if self.follow_up_actor_modes:
+            payload["follow_up_actor_modes"] = list(self.follow_up_actor_modes)
+        if self.requires_managed_webapp_auth_context:
+            payload["requires_managed_webapp_auth_context"] = True
+        if self.default_template:
+            payload["default_template"] = dict(self.default_template)
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class PluginCapabilityBinding:
+    spec: PluginCapabilitySpec
+    method_name: str
+    handler: Callable[..., Any]
+
+
+def _validate_plugin_capability_specs(specs: list[PluginCapabilitySpec]) -> None:
+    for spec in specs:
+        if not spec.capability_id:
+            raise SdkContractError("capability_id_required", "capability_id is required")
+        if not spec.description:
+            raise SdkContractError("capability_description_required", f"{spec.capability_id}: description is required")
+        delivery_mode = spec.delivery_mode or "inline"
+        if spec.concurrency_class == CAPABILITY_CONCURRENCY_SYNC_SESSION:
+            if delivery_mode == "durable_queue":
+                raise SdkContractError(
+                    "capability_sync_session_delivery_mode_invalid",
+                    f"{spec.capability_id}: sync_session capabilities must not declare durable_queue delivery_mode",
+                )
+        else:
+            if delivery_mode != "durable_queue":
+                raise SdkContractError(
+                    "capability_async_delivery_mode_invalid",
+                    f"{spec.capability_id}: async capabilities must declare delivery_mode=durable_queue",
+                )
+            if spec.idempotency_strategy not in VALID_ASYNC_IDEMPOTENCY_STRATEGIES:
+                raise SdkContractError(
+                    "capability_async_idempotency_strategy_invalid",
+                    f"{spec.capability_id}: async capabilities must declare idempotency_strategy=update_id|message_revision",
+                )
+        if spec.kind == CAPABILITY_KIND_EVENT:
+            if spec.allowed_surfaces:
+                raise SdkContractError(
+                    "event_capability_allowed_surfaces_forbidden",
+                    f"{spec.capability_id}: event capabilities must not declare allowed_surfaces",
+                )
+            continue
+        if spec.input_schema is None:
+            raise SdkContractError(
+                "invoke_capability_input_schema_required",
+                f"{spec.capability_id}: invoke capabilities must declare input_schema",
+            )
+        if spec.output_schema is None:
+            raise SdkContractError(
+                "invoke_capability_output_schema_required",
+                f"{spec.capability_id}: invoke capabilities must declare output_schema",
+            )
+
+
+def _record_capability_spec(
+    specs_by_id: dict[str, PluginCapabilitySpec],
+    spec: PluginCapabilitySpec,
+    *,
+    origin: str,
+) -> None:
+    if spec.capability_id in specs_by_id:
+        raise CapabilityDeclarationError(
+            "duplicate_capability_id",
+            f"duplicate capability_id detected: {spec.capability_id}",
+            details={"origin": origin},
+        )
+    specs_by_id[spec.capability_id] = spec
+
+
+def invoke_capability(**kwargs: Any):
+    spec = PluginCapabilitySpec(kind=CAPABILITY_KIND_INVOKE, **kwargs)
+
+    def _decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(func, "__tg_bot_capability_spec__", spec)
+        return func
+
+    return _decorator
+
+
+def event_capability(**kwargs: Any):
+    spec = PluginCapabilitySpec(kind=CAPABILITY_KIND_EVENT, **kwargs)
+
+    def _decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(func, "__tg_bot_capability_spec__", spec)
+        return func
+
+    return _decorator
+
+
+def _collect_decorated_capability_bindings(plugin: Any) -> list[PluginCapabilityBinding]:
+    bindings: list[PluginCapabilityBinding] = []
+    seen_methods: set[str] = set()
+    for cls in reversed(type(plugin).mro()):
+        if cls is object:
+            continue
+        for method_name, candidate in cls.__dict__.items():
+            if method_name in seen_methods:
+                continue
+            spec = getattr(candidate, "__tg_bot_capability_spec__", None)
+            if not isinstance(spec, PluginCapabilitySpec):
+                continue
+            bound_handler = getattr(plugin, method_name, None)
+            if not callable(bound_handler):
+                continue
+            bindings.append(PluginCapabilityBinding(spec=spec, method_name=method_name, handler=bound_handler))
+            seen_methods.add(method_name)
+    bindings.sort(key=lambda item: (item.spec.capability_id, item.method_name))
+    return bindings
+
+
+def resolve_plugin_capability_specs(plugin: Any) -> list[PluginCapabilitySpec]:
+    specs_by_id: dict[str, PluginCapabilitySpec] = {}
+    if "get_capability_specs" in type(plugin).__dict__:
+        for spec in plugin.get_capability_specs():
+            if not isinstance(spec, PluginCapabilitySpec):
+                raise TypeError("plugin capability specs must be PluginCapabilitySpec")
+            _record_capability_spec(specs_by_id, spec, origin="get_capability_specs")
+    for binding in _collect_decorated_capability_bindings(plugin):
+        _record_capability_spec(specs_by_id, binding.spec, origin=f"decorated:{binding.method_name}")
+    return [specs_by_id[key] for key in sorted(specs_by_id.keys())]
+
+
+def project_plugin_capability_contract(plugin: Any) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    specs = resolve_plugin_capability_specs(plugin)
+    _validate_plugin_capability_specs(specs)
+    capability_payload = [spec.to_contract_dict() for spec in specs]
+    return {"capabilities": capability_payload}, capability_payload