Squashed 'astrbot-sdk/' changes from 44b67256b..3cf8142fb

3cf8142fb chore: refresh vendor snapshot [skip ci]
ffe5fd101 Merge pull request #110 from united-pooh:dev
15f7adf4b refactor: update documentation and code references from v4 to astrbot-sdk
a75fe8903 feat: 增强 wrap_client_exception 函数的异常处理逻辑，确保重建异常时的正确返回
7553253ed Merge pull request #109 from united-pooh/dev
7167f6ccf feat: 添加错误处理包装函数，增强客户端异常处理能力
REVERT: 44b67256b chore: refresh vendor snapshot [skip ci]

git-subtree-dir: astrbot-sdk
git-subtree-split: 3cf8142fb3dde637755495d62e1a0525887e87cf

Author: whatevertogo

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "astrbot-sdk"
 version = "0.1.0"
-description = "AstrBot SDK with v4 runtime, worker protocol, and plugin tooling"
+description = "AstrBot SDK with s5r runtime, worker protocol, and plugin tooling"
 readme = "README.md"
 requires-python = ">=3.12"
 classifiers = [

src/astrbot_sdk/__init__.py

@@ -1,12 +1,12 @@
 """AstrBot SDK 的顶层公共 API。
 
-这里仅重新导出 v4 推荐直接导入的稳定入口。
+这里仅重新导出 astrbot-sdk 推荐直接导入的稳定入口。
 
 新插件应直接使用此模块的导出：
     from astrbot_sdk import Star, Context, MessageEvent
     from astrbot_sdk.decorators import on_command, on_message
 
-迁移期适配入口位于独立模块；此处只暴露 v4 原生主入口。
+迁移期适配入口位于独立模块；此处只暴露 astrbot-sdk 原生主入口。
 """
 
 from .clients.managers import (

src/astrbot_sdk/cli.py

@@ -719,7 +719,7 @@ def _render_init_readme(*, plugin_name: str) -> str:
         f"""\
         # {plugin_name}
 
-        一个最小可运行的 AstrBot SDK v4 插件。
+        一个最小可运行的 AstrBot SDK 插件。
 
         ## 目录结构
 

src/astrbot_sdk/clients/__init__.py

@@ -1,4 +1,4 @@
-"""原生v4能力客户端
+"""原生 astrbot-sdk 能力客户端
 
 这些客户端为 Context 提供了用于调用远程能力的狭窄且具类型化 (typed) 的接口。
 它们负责处理能力名称、载荷格式化（payload shaping）以及结果解码，且不会暴露协议或传输层的具体细节。

src/astrbot_sdk/clients/_errors.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from ..errors import AstrBotError
+
+
+def client_call_label(
+    client_name: str,
+    method_name: str,
+    details: str | None = None,
+) -> str:
+    label = f"{client_name}.{method_name}"
+    if details:
+        return f"{label} ({details})"
+    return label
+
+
+def wrap_client_exception(
+    *,
+    client_name: str,
+    method_name: str,
+    exc: Exception,
+    details: str | None = None,
+) -> Exception:
+    message = f"{client_call_label(client_name, method_name, details)} failed: {exc}"
+    if isinstance(exc, AstrBotError):
+        return AstrBotError(
+            code=exc.code,
+            message=message,
+            hint=exc.hint,
+            retryable=exc.retryable,
+            docs_url=exc.docs_url,
+            details=exc.details,
+        )
+    try:
+        rebuilt = exc.__class__(message)
+    except Exception:
+        return RuntimeError(message)
+    if isinstance(rebuilt, Exception):
+        return rebuilt
+    return RuntimeError(message)
+
+
+__all__ = ["client_call_label", "wrap_client_exception"]

src/astrbot_sdk/clients/http.py

@@ -41,6 +41,7 @@ async def handle_http_request(request_id: str, payload: dict, cancel_token):
 
 from ..decorators import get_capability_meta
 from ..errors import AstrBotError
+from ._errors import wrap_client_exception
 from ._proxy import CapabilityProxy
 
 
@@ -116,16 +117,23 @@ async def register_api(
         if methods is None:
             methods = ["GET"]
         resolved_handler = _resolve_handler_capability(handler_capability, handler)
-
-        await self._proxy.call(
-            "http.register_api",
-            {
-                "route": route,
-                "methods": methods,
-                "handler_capability": resolved_handler,
-                "description": description,
-            },
-        )
+        try:
+            await self._proxy.call(
+                "http.register_api",
+                {
+                    "route": route,
+                    "methods": methods,
+                    "handler_capability": resolved_handler,
+                    "description": description,
+                },
+            )
+        except Exception as exc:
+            raise wrap_client_exception(
+                client_name="HTTPClient",
+                method_name="register_api",
+                details=f"route={route!r}, methods={list(methods)!r}",
+                exc=exc,
+            ) from exc
 
     async def unregister_api(
         self, route: str, methods: list[str] | None = None
@@ -141,11 +149,18 @@ async def unregister_api(
         """
         if methods is None:
             methods = []
-
-        await self._proxy.call(
-            "http.unregister_api",
-            {"route": route, "methods": methods},
-        )
+        try:
+            await self._proxy.call(
+                "http.unregister_api",
+                {"route": route, "methods": methods},
+            )
+        except Exception as exc:
+            raise wrap_client_exception(
+                client_name="HTTPClient",
+                method_name="unregister_api",
+                details=f"route={route!r}, methods={list(methods)!r}",
+                exc=exc,
+            ) from exc
 
     async def list_apis(self) -> list[dict[str, Any]]:
         """列出当前插件注册的所有 API。
@@ -158,8 +173,15 @@ async def list_apis(self) -> list[dict[str, Any]]:
             for api in apis:
                 print(f"{api['route']}: {api['methods']}")
         """
-        output = await self._proxy.call(
-            "http.list_apis",
-            {},
-        )
+        try:
+            output = await self._proxy.call(
+                "http.list_apis",
+                {},
+            )
+        except Exception as exc:
+            raise wrap_client_exception(
+                client_name="HTTPClient",
+                method_name="list_apis",
+                exc=exc,
+            ) from exc
         return output.get("apis", [])

src/astrbot_sdk/clients/llm.py

@@ -1,6 +1,6 @@
 """大语言模型客户端模块。
 
-提供 v4 原生的 LLM 能力调用接口。
+提供 astrbot-sdk 原生的 LLM 能力调用接口。
 
 设计边界：
     - `chat()` 是便捷文本接口，返回最终文本