Squashed 'astrbot-sdk/' changes from 56943300b..0a9c86345

0a9c86345 chore: refresh vendor snapshot [skip ci]
b5d9b934b Merge pull request #105 from united-pooh:dev
c07f04e63 feat: 更新多个客户端和模块，增强类型注解和文档说明
REVERT: 56943300b chore: refresh vendor snapshot [skip ci]

git-subtree-dir: astrbot-sdk
git-subtree-split: 0a9c86345ea2192154580d0ef054b72b99892b9e

Author: whatevertogo

src/astrbot_sdk/clients/_proxy.py

@@ -80,7 +80,7 @@ def __init__(
         self._caller_plugin_id = caller_plugin_id
         self._request_scope_id = request_scope_id
 
-    def _get_descriptor(self, name: str):
+    def _get_descriptor(self, name: str) -> _CapabilityDescriptorLike | None:
         """获取能力描述符。
 
         Args:

src/astrbot_sdk/clients/files.py

@@ -1,3 +1,8 @@
+"""文件服务客户端。
+
+提供文件令牌注册和令牌反查能力，封装 `system.file.*` capabilities。
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -8,6 +13,8 @@
 
 @dataclass(slots=True)
 class FileRegistration:
+    """文件注册结果。"""
+
     token: str
     url: str
 
@@ -20,32 +27,44 @@ def from_payload(cls, payload: dict[str, Any]) -> FileRegistration:
 
 
 class FileServiceClient:
+    """文件服务能力客户端。"""
+
     def __init__(self, proxy: CapabilityProxy) -> None:
         self._proxy = proxy
 
-    async def register_file(
+    async def _register(
         self,
         path: str,
-        timeout: float | None = None,
-    ) -> str:
+        *,
+        timeout: float | None,
+    ) -> FileRegistration:
         output = await self._proxy.call(
             "system.file.register",
             {"path": str(path), "timeout": timeout},
         )
-        return FileRegistration.from_payload(output).token
+        return FileRegistration.from_payload(output)
+
+    async def register_file(
+        self,
+        path: str,
+        timeout: float | None = None,
+    ) -> str:
+        """注册本地文件并返回文件令牌。"""
+
+        return (await self._register(path, timeout=timeout)).token
 
     async def register_file_url(
         self,
         path: str,
         timeout: float | None = None,
     ) -> str:
-        output = await self._proxy.call(
-            "system.file.register",
-            {"path": str(path), "timeout": timeout},
-        )
-        return FileRegistration.from_payload(output).url
+        """注册本地文件并返回公开访问 URL。"""
+
+        return (await self._register(path, timeout=timeout)).url
 
     async def handle_file(self, token: str) -> str:
+        """将文件令牌解析回本地文件路径。"""
+
         output = await self._proxy.call(
             "system.file.handle",
             {"token": str(token)},

src/astrbot_sdk/clients/managers.py

@@ -649,7 +649,7 @@ async def append(
         session: MessageSession,
         *,
         parts: list[BaseMessageComponent],
-        sender: MessageHistorySender,
+        sender: MessageHistorySender | dict[str, Any],
         metadata: dict[str, Any] | None = None,
         idempotency_key: str | None = None,
     ) -> MessageHistoryRecord:

src/astrbot_sdk/clients/mcp.py

@@ -1,8 +1,14 @@
+"""MCP 管理客户端。
+
+提供本地 MCP 服务、全局 MCP 服务和临时 MCP session 的 SDK 封装。
+"""
+
 from __future__ import annotations
 
 from contextlib import AbstractAsyncContextManager
 from dataclasses import dataclass, field
 from enum import Enum
+from types import TracebackType
 from typing import Any
 
 from ..errors import AstrBotError
@@ -16,6 +22,8 @@ class MCPServerScope(str, Enum):
 
 @dataclass(slots=True)
 class MCPServerRecord:
+    """MCP 服务快照。"""
+
     name: str
     scope: MCPServerScope
     active: bool
@@ -69,7 +77,33 @@ def from_payload(
         )
 
 
+def _server_records_from_payload(items: Any) -> list[MCPServerRecord]:
+    if not isinstance(items, list):
+        return []
+    return [
+        record
+        for record in (
+            MCPServerRecord.from_payload(item) if isinstance(item, dict) else None
+            for item in items
+        )
+        if record is not None
+    ]
+
+
+def _require_server_record(
+    payload: dict[str, Any],
+    *,
+    action: str,
+) -> MCPServerRecord:
+    record = MCPServerRecord.from_payload(payload.get("server"))
+    if record is None:
+        raise ValueError(f"{action} returned no server")
+    return record
+
+
 class MCPSession(AbstractAsyncContextManager["MCPSession"]):
+    """临时 MCP session 的异步上下文封装。"""
+
     def __init__(
         self,
         proxy: CapabilityProxy,
@@ -106,7 +140,12 @@ async def __aenter__(self) -> MCPSession:
         )
         return self
 
-    async def __aexit__(self, exc_type, exc, tb) -> None:
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
         session_id = self._session_id
         self._session_id = None
         self._tools = []
@@ -162,6 +201,8 @@ def _require_session_id(self) -> str:
 
 
 class MCPManagerClient:
+    """MCP 服务管理客户端。"""
+
     def __init__(self, proxy: CapabilityProxy) -> None:
         self._proxy = proxy
 
@@ -171,31 +212,15 @@ async def get_server(self, name: str) -> MCPServerRecord | None:
 
     async def list_servers(self) -> list[MCPServerRecord]:
         output = await self._proxy.call("mcp.local.list", {})
-        items = output.get("servers")
-        if not isinstance(items, list):
-            return []
-        return [
-            record
-            for record in (
-                MCPServerRecord.from_payload(item) if isinstance(item, dict) else None
-                for item in items
-            )
-            if record is not None
-        ]
+        return _server_records_from_payload(output.get("servers"))
 
     async def enable_server(self, name: str) -> MCPServerRecord:
         output = await self._proxy.call("mcp.local.enable", {"name": str(name)})
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.local.enable returned no server")
-        return record
+        return _require_server_record(output, action="mcp.local.enable")
 
     async def disable_server(self, name: str) -> MCPServerRecord:
         output = await self._proxy.call("mcp.local.disable", {"name": str(name)})
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.local.disable returned no server")
-        return record
+        return _require_server_record(output, action="mcp.local.disable")
 
     async def wait_until_ready(
         self,
@@ -207,10 +232,7 @@ async def wait_until_ready(
             "mcp.local.wait_until_ready",
             {"name": str(name), "timeout": float(timeout)},
         )
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.local.wait_until_ready returned no server")
-        return record
+        return _require_server_record(output, action="mcp.local.wait_until_ready")
 
     def session(
         self,
@@ -241,28 +263,15 @@ async def register_global_server(
                 "timeout": float(timeout),
             },
         )
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.global.register returned no server")
-        return record
+        return _require_server_record(output, action="mcp.global.register")
 
     async def get_global_server(self, name: str) -> MCPServerRecord | None:
         output = await self._proxy.call("mcp.global.get", {"name": str(name)})
         return MCPServerRecord.from_payload(output.get("server"))
 
     async def list_global_servers(self) -> list[MCPServerRecord]:
         output = await self._proxy.call("mcp.global.list", {})
-        items = output.get("servers")
-        if not isinstance(items, list):
-            return []
-        return [
-            record
-            for record in (
-                MCPServerRecord.from_payload(item) if isinstance(item, dict) else None
-                for item in items
-            )
-            if record is not None
-        ]
+        return _server_records_from_payload(output.get("servers"))
 
     async def enable_global_server(
         self,
@@ -274,24 +283,15 @@ async def enable_global_server(
             "mcp.global.enable",
             {"name": str(name), "timeout": float(timeout)},
         )
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.global.enable returned no server")
-        return record
+        return _require_server_record(output, action="mcp.global.enable")
 
     async def disable_global_server(self, name: str) -> MCPServerRecord:
         output = await self._proxy.call("mcp.global.disable", {"name": str(name)})
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.global.disable returned no server")
-        return record
+        return _require_server_record(output, action="mcp.global.disable")
 
     async def unregister_global_server(self, name: str) -> MCPServerRecord:
         output = await self._proxy.call("mcp.global.unregister", {"name": str(name)})
-        record = MCPServerRecord.from_payload(output.get("server"))
-        if record is None:
-            raise ValueError("mcp.global.unregister returned no server")
-        return record
+        return _require_server_record(output, action="mcp.global.unregister")
 
 
 __all__ = [

src/astrbot_sdk/clients/memory.py

@@ -56,7 +56,7 @@ def __init__(
         self._namespace = join_memory_namespace(namespace)
 
     def namespace(self, *parts: Any) -> MemoryClient:
-        """Create a derived client that operates inside a child namespace."""
+        """创建一个工作在子命名空间中的派生客户端。"""
 
         return MemoryClient(
             self._proxy,
@@ -203,7 +203,7 @@ async def list_keys(
         *,
         namespace: str | None = None,
     ) -> list[str]:
-        """List keys in the exact namespace using case-insensitive ordering."""
+        """列出指定精确命名空间下的全部键。"""
 
         payload: dict[str, Any] = {
             "namespace": self._resolve_exact_namespace(namespace)
@@ -220,7 +220,7 @@ async def exists(
         *,
         namespace: str | None = None,
     ) -> bool:
-        """Check whether a key exists in the exact namespace."""
+        """检查指定精确命名空间中是否存在某个键。"""
 
         payload: dict[str, Any] = {"key": key}
         payload["namespace"] = self._resolve_exact_namespace(namespace)
@@ -251,7 +251,7 @@ async def clear_namespace(
         namespace: str | None = None,
         include_descendants: bool = False,
     ) -> int:
-        """Delete memories in a namespace and optionally its descendants."""
+        """清空命名空间中的记忆项，可选递归清空子命名空间。"""
 
         payload: dict[str, Any] = {
             "namespace": self._resolve_exact_namespace(namespace),
@@ -364,7 +364,7 @@ async def count(
         namespace: str | None = None,
         include_descendants: bool = False,
     ) -> int:
-        """Count memories in a namespace and optionally its descendants."""
+        """统计命名空间中的记忆项数量，可选包含子命名空间。"""
 
         payload: dict[str, Any] = {
             "namespace": self._resolve_exact_namespace(namespace),
@@ -409,24 +409,18 @@ async def stats(
             "total_items": output.get("total_items", 0),
             "total_bytes": output.get("total_bytes"),
         }
-        if "namespace" in output:
-            stats["namespace"] = output.get("namespace")
-        if "namespace_count" in output:
-            stats["namespace_count"] = output.get("namespace_count")
-        if "fts_enabled" in output:
-            stats["fts_enabled"] = output.get("fts_enabled")
-        if "vector_backend" in output:
-            stats["vector_backend"] = output.get("vector_backend")
-        if "vector_indexes" in output:
-            stats["vector_indexes"] = output.get("vector_indexes")
-        if "plugin_id" in output:
-            stats["plugin_id"] = output.get("plugin_id")
-        if "ttl_entries" in output:
-            stats["ttl_entries"] = output.get("ttl_entries")
-        if "indexed_items" in output:
-            stats["indexed_items"] = output.get("indexed_items")
-        if "embedded_items" in output:
-            stats["embedded_items"] = output.get("embedded_items")
-        if "dirty_items" in output:
-            stats["dirty_items"] = output.get("dirty_items")
+        for key in (
+            "namespace",
+            "namespace_count",
+            "fts_enabled",
+            "vector_backend",
+            "vector_indexes",
+            "plugin_id",
+            "ttl_entries",
+            "indexed_items",
+            "embedded_items",
+            "dirty_items",
+        ):
+            if key in output:
+                stats[key] = output.get(key)
         return stats

src/astrbot_sdk/clients/permission.py

@@ -1,4 +1,4 @@
-"""Permission capability clients."""
+"""权限能力客户端。"""
 
 from __future__ import annotations
 
@@ -10,6 +10,8 @@
 
 
 class PermissionCheckResult(BaseModel):
+    """权限检查结果。"""
+
     model_config = ConfigDict(extra="forbid")
 
     is_admin: bool
@@ -26,6 +28,8 @@ def from_payload(
 
 
 class PermissionClient:
+    """权限查询客户端。"""
+
     def __init__(self, proxy: CapabilityProxy) -> None:
         self._proxy = proxy
 
@@ -52,6 +56,8 @@ async def get_admins(self) -> list[str]:
 
 
 class PermissionManagerClient:
+    """权限管理客户端。"""
+
     def __init__(
         self,
         proxy: CapabilityProxy,