ErisPulse 2.1.1__tar.gz → 2.1.3__tar.gz

{erispulse-2.1.1 → erispulse-2.1.3}/LICENSE

@@ -22,8 +22,10 @@ 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.
 
-The documentation portion of this project references content from https://codeberg.org/ybr/yhwiki,
-licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 
-International License (CC BY-NC-ND 4.0).
+This SDK's core adapter standardization layer strictly follows OneBot12 specifications (https://12.onebot.dev/) for:
+- Event data normalization
+- API request/response formats
+- Message segment definitions
+- Metadata definitions
 
-Note: This license file has been updated to correct the upstream project reference.
+This ensures consistent behavior and interoperability across all adapter implementations.

{erispulse-2.1.1 → erispulse-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.1.1
+Version: 2.1.3
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>, runoneall <runoobsteve@gmail.com>
 License: MIT License
@@ -27,11 +27,13 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-        The documentation portion of this project references content from https://codeberg.org/ybr/yhwiki,
-        licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 
-        International License (CC BY-NC-ND 4.0).
+        This SDK's core adapter standardization layer strictly follows OneBot12 specifications (https://12.onebot.dev/) for:
+        - Event data normalization
+        - API request/response formats
+        - Message segment definitions
+        - Metadata definitions
         
-        Note: This license file has been updated to correct the upstream project reference.
+        This ensures consistent behavior and interoperability across all adapter implementations.
 License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers

{erispulse-2.1.1 → erispulse-2.1.3}/docs/AIDocs/ErisPulse-AdapterDev.md

@@ -170,7 +170,8 @@ MyAdapter/
 ├── LICENSE
 └── MyAdapter/
     ├── __init__.py
-    └── Core.py
+    ├── Core.py
+    └── Converter.py
 ```
 
 ### 2. `pyproject.toml` 文件
@@ -212,15 +213,26 @@ from .Core import MyAdapter
 ```python
 from ErisPulse import sdk
 from ErisPulse.Core import BaseAdapter
+from ErisPulse.Core import adapter_server
+
+# 这里仅你使用 websocket 作为通信协议时需要 | 第一个作为参数的类型是 WebSocket, 第二个是 WebSocketDisconnect，当 ws 连接断开时触发你的捕捉
+# 一般来说你不用在依赖中添加 fastapi, 因为它已经内置在 ErisPulse 中了
+from fastapi import WebSocket, WebSocketDisconnect
 
 class MyAdapter(BaseAdapter):
-    def __init__(self):    # 适配器有显式的导入sdk对象, 所以不需导入sdk对象
+    def __init__(self, sdk):    # 这里是不强制传入sdk的，你可以选择不传入 
         self.sdk = sdk
         self.env = self.sdk.env
         self.logger = self.sdk.logger
         
         self.logger.info("MyModule 初始化完成")
         self.config = self._get_config()
+        self.converter = self._setup_converter()  # 获取转换器实例
+        self.convert = self.converter.convert
+
+    def _setup_converter(self):
+        from .Converter import MyPlatformConverter
+        return MyPlatformConverter()
 
     def _get_config(self):
         # 加载配置方法，你需要在这里进行必要的配置加载逻辑
@@ -232,29 +244,38 @@ class MyAdapter(BaseAdapter):
             self.env.setConfig("MyAdapter", default_config)
             return default_config
         return config
+
     class Send(BaseAdapter.Send):  # 继承BaseAdapter内置的Send类
-        # 底层SendDSL中提供了To方法，用户调用的时候类会被定义 `self._target_type` 和 `self._target_id`/`self._target_to` 三个属性
-        # 当你只需要一个接受的To时，例如 mail 的To只是一个邮箱，那么你可以使用 `self.To(email)`，这时只会有 `self._target_id`/`self._target_to` 两个属性被定义
-        # 或者说你不需要用户的To，那么用户也可以直接使用 Send.Func(text) 的方式直接调用这里的方法
+        """
+        Send消息发送DSL，支持四种调用方式(继承的Send类包含了To和Using方法):
+        1. 指定类型和ID: To(type,id).Func() -> 设置_target_type和_target_id/_target_to
+           示例: Send.To("group",123).Text("hi")
+        2. 指定发送账号: Using(account_id).Func() -> 设置_account_id
+           示例: Send.Using("bot1").Text("hi")
+        3. 组合使用: Using(account_id).To(type,id).Func()
+           示例: Send.Using("bot1").To("user","123").Text("hi")
+        4. 直接调用: Func() -> 不设置目标属性
+           示例: Send.Text("broadcast")
+        """
         
-        # 可以重写Text方法提供平台特定实现
         def Text(self, text: str):
+            """发送文本消息（可重写实现）"""
             return asyncio.create_task(
                 self._adapter.call_api(
                     endpoint="/send",
                     content=text,
-                    recvId=self._target_id,
-                    recvType=self._target_type
+                    recvId=self._target_id,    # 来自To()设置的属性
+                    recvType=self._target_type # 来自To(type,id)设置的属性
                 )
             )
             
-        # 添加新的消息类型
         def Image(self, file: bytes):
+            """发送图片消息"""
             return asyncio.create_task(
                 self._adapter.call_api(
                     endpoint="/send_image",
                     file=file,
-                    recvId=self._target_id,
+                    recvId=self._target_id,    # 自动使用To()设置的属性
                     recvType=self._target_type
                 )
             )
@@ -318,12 +339,233 @@ class Send((BaseAdapter.Send):
         )
 ```
 
-调用方式如下：
+调用方式支持以下组合：
+
+1. 指定发送账号和接收目标：
+```python
+sdk.adapter.MyPlatform.Send.Using("bot1").To("user", "U1001").Text("你好")
+```
 
+2. 仅指定接收目标：
 ```python
 sdk.adapter.MyPlatform.Send.To("user", "U1001").Text("你好")
 ```
 
+3. 仅指定发送账号：
+```python
+sdk.adapter.MyPlatform.Send.Using("bot1").Text("广播消息")
+```
+
+4. 直接调用：
+```python
+sdk.adapter.MyPlatform.Send.Text("广播消息")
+```
+
+`Using`方法用于指定发送账号，会设置`self._account_id`属性，可以在后续API调用中使用。
+
+---
+
+## 5. 事件转换与路由注册
+
+适配器需要处理平台原生事件并转换为OneBot12标准格式，同时需要向底层框架注册路由。以下是两种典型实现方式：
+
+### 5.1 WebSocket 方式实现
+
+```python
+async def _ws_handler(self, websocket: WebSocket):
+    """WebSocket连接处理器"""
+    self.connection = websocket
+    self.logger.info("客户端已连接")
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+            try:
+                event = json.loads(data)
+                # 提交原生事件到适配器
+                # 原生事件需要通过指定平台来获取 比如 sdk.adapter.MyPlatform.on("事件类型")
+                self.emit(data.get("event_type"), data)
+
+                # 转换为OneBot12标准事件
+                onebot_event = self.convert(event)
+                if onebot_event:
+                    # 提交标准事件到框架 | 这里直接通过 sdk.adaoter.on("事件类型") 便可以获取到事件，但是需要判断字段里面的platform字段来区分适配器
+                    await self.sdk.adapter.emit(onebot_event)
+            except json.JSONDecodeError:
+                self.logger.error(f"JSON解析失败: {data}")
+    except WebSocketDisconnect:
+        self.logger.info("客户端断开连接")
+    finally:
+        self.connection = None
+
+async def start(self):
+    """注册WebSocket路由"""
+    adapter_server.register_websocket(
+        adapter_name="myplatform",  # 适配器名称
+        path="/ws",  # 路由路径
+        handler=self._ws_handler,  # 处理器
+        auth_handler=self._auth_handler  # 认证处理器(可选)
+    )
+```
+
+### 5.2 WebHook 方式实现
+
+```python
+async def _webhook_handler(self, request: Request):
+    """WebHook请求处理器"""
+    try:
+        data = await request.json()
+
+        # 提交原生事件到适配器
+        # 原生事件需要通过指定平台来获取 比如 sdk.adapter.MyPlatform.on("事件类型")
+        self.emit(data.get("event_type"), data)
+
+        # 转换为OneBot12标准事件
+        onebot_event = self.convert(data)=
+        if onebot_event:
+            # 提交标准事件到框架 | 这里直接通过 sdk.adaoter.on("事件类型") 便可以获取到事件，但是需要判断字段里面的platform字段来区分适配器
+            await self.sdk.adapter.emit(onebot_event)
+        return JSONResponse({"status": "ok"})
+    except Exception as e:
+        self.logger.error(f"处理WebHook失败: {str(e)}")
+        return JSONResponse({"status": "failed"}, status_code=400)
+
+async def start(self):
+    """注册WebHook路由"""
+    adapter_server.register_webhook(
+        adapter_name="myplatform",  # 适配器名称
+        path="/webhook",  # 路由路径
+        handler=self._webhook_handler,  # 处理器
+        methods=["POST"]  # 支持的HTTP方法
+    )
+```
+
+### 5.3 事件转换器实现
+
+适配器应提供标准的事件转换器，将平台原生事件转换为OneBot12格式(具体实现请参考[事件转换标准文档](docs/AdapterStandards/EventConversion.md)：
+
+```python
+class MyPlatformConverter:
+    def convert(self, raw_event: Dict) -> Optional[Dict]:
+        """将平台原生事件转换为OneBot12标准格式"""
+        if not isinstance(raw_event, dict):
+            return None
+
+        # 基础事件结构
+        onebot_event = {
+            "id": str(raw_event.get("event_id", uuid.uuid4())),
+            "time": int(time.time()),
+            "type": "",  # message/notice/request/meta_event
+            "detail_type": "",
+            "platform": "myplatform",
+            "self": {
+                "platform": "myplatform",
+                "user_id": str(raw_event.get("bot_id", ""))
+            },
+            "myplatform_raw": raw_event  # 保留原始数据
+        }
+
+        # 根据事件类型分发处理
+        event_type = raw_event.get("type")
+        if event_type == "message":
+            return self._handle_message(raw_event, onebot_event)
+        elif event_type == "notice":
+            return self._handle_notice(raw_event, onebot_event)
+        
+        return None
+```
+
+## 6. API响应标准
+
+适配器的`call_api`方法必须返回符合以下标准的响应结构：
+
+### 6.1 成功响应格式
+
+```python
+{
+    "status": "ok",  # 必须
+    "retcode": 0,  # 必须，0表示成功
+    "data": {  # 必须，成功时返回的数据
+        "message_id": "123456",  # 消息ID(如果有)
+        "time": 1632847927.599013  # 时间戳(如果有)
+    },
+    "message": "",  # 必须，成功时为空字符串
+    "message_id": "123456",  # 可选，消息ID
+    "echo": "1234",  # 可选，当请求中包含echo时返回
+    "myplatform_raw": {...}  # 可选，原始响应数据
+}
+```
+
+### 6.2 失败响应格式
+
+```python
+{
+    "status": "failed",  # 必须
+    "retcode": 10003,  # 必须，非0错误码
+    "data": None,  # 必须，失败时为null
+    "message": "缺少必要参数",  # 必须，错误描述
+    "message_id": "",  # 可选，失败时为空字符串
+    "echo": "1234",  # 可选，当请求中包含echo时返回
+    "myplatform_raw": {...}  # 可选，原始响应数据
+}
+```
+
+### 6.3 实现示例
+
+```python
+async def call_api(self, endpoint: str, **params):
+    try:
+        # 调用平台API
+        raw_response = await self._platform_api_call(endpoint, **params)
+        
+        # 标准化响应
+        standardized = {
+            "status": "ok" if raw_response["success"] else "failed",
+            "retcode": 0 if raw_response["success"] else raw_response.get("code", 10001),
+            "data": raw_response.get("data"),
+            "message": raw_response.get("message", ""),
+            "message_id": raw_response.get("data", {}).get("message_id", ""),
+            "myplatform_raw": raw_response
+        }
+        
+        if "echo" in params:
+            standardized["echo"] = params["echo"]
+            
+        return standardized
+        
+    except Exception as e:
+        return {
+            "status": "failed",
+            "retcode": 34000,  # 平台错误代码段
+            "data": None,
+            "message": str(e),
+            "message_id": ""
+        }
+```
+
+## 7. 错误代码规范
+
+适配器应遵循以下错误代码范围：
+
+| 代码范围 | 类型 | 说明 |
+|---------|------|------|
+| 0 | 成功 | 必须为0 |
+| 1xxxx | 请求错误 | 无效参数、不支持的操作等 |
+| 2xxxx | 处理器错误 | 适配器内部处理错误 |
+| 3xxxx | 执行错误 | 平台API调用错误 |
+| 34xxx | 平台错误 | 平台返回的错误 |
+
+建议在适配器中定义常量：
+
+```python
+class ErrorCode:
+    SUCCESS = 0
+    INVALID_PARAMS = 10003
+    UNSUPPORTED_ACTION = 10002
+    INTERNAL_ERROR = 20001
+    PLATFORM_ERROR = 34000
+```
+
 ---
 
 ## 开发建议
@@ -350,7 +592,7 @@ sdk.adapter.MyPlatform.Send.To("user", "U1001").Text("你好")
 
 ---
 
-*文档最后更新于 2025-07-17 08:10:26*
+*文档最后更新于 2025-07-17 12:44:51*
 
 <!--- End of Adapter.md -->
 
@@ -690,7 +932,7 @@ def generate_message_id(platform: str, raw_id: str) -> str:
 
 # 📦 `ErisPulse.__init__` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -835,6 +1077,31 @@ SDK初始化入口
 
 ---
 
+##### `__str__`
+
+转换为字符串时触发初始化
+
+:return: str 模块字符串表示
+
+---
+
+##### `__copy__`
+
+浅拷贝时返回自身，保持懒加载特性
+
+:return: self
+
+---
+
+##### `__deepcopy__`
+
+深拷贝时返回自身，保持懒加载特性
+
+:param memo: memo
+:return: self
+
+---
+
 ### `AdapterLoader`
 
 适配器加载器
@@ -969,13 +1236,17 @@ SDK初始化入口
 
 ---
 
-##### `_pre_register_modules`
+##### `_initialize_modules`
+
+⚠️ **内部方法**：
 
-预记录所有模块信息到SDK属性中
+初始化模块
 
 :param modules: List[str] 模块名称列表
 :param module_objs: Dict[str, Any] 模块对象字典
 
+:return: bool 模块初始化是否成功
+
 ---
 
 ##### `_register_adapters`
@@ -991,27 +1262,14 @@ SDK初始化入口
 
 ---
 
-##### `_initialize_modules`
-
-⚠️ **内部方法**：
 
-初始化模块
-
-:param modules: List[str] 模块名称列表
-:param module_objs: Dict[str, Any] 模块对象字典
-
-:return: bool 模块初始化是否成功
-
----
-
-
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\__main__.md
 
 # 📦 `ErisPulse.__main__` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -1200,13 +1458,13 @@ PyPI包管理器
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\adapter.md
 
 # 📦 `ErisPulse.Core.adapter` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -1248,6 +1506,7 @@ ErisPulse 适配器系统
 :param adapter: 所属适配器实例
 :param target_type: 目标类型(可选)
 :param target_id: 目标ID(可选)
+:param _account_id: 发送账号(可选)
 
 ---
 
@@ -1265,6 +1524,19 @@ ErisPulse 适配器系统
 
 ---
 
+##### `Using`
+
+设置发送账号
+
+:param _account_id: 发送账号
+:return: SendDSL实例
+
+:example:
+>>> adapter.Send.Using("bot1").To("123").Text("Hello")
+>>> adapter.Send.To("123").Using("bot1").Text("Hello")  # 支持乱序
+
+---
+
 ### `BaseAdapter`
 
 适配器基类
@@ -1537,13 +1809,13 @@ OneBot12协议事件监听装饰器
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\env.md
 
 # 📦 `ErisPulse.Core.env` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -1829,13 +2101,13 @@ ErisPulse 环境配置模块
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\logger.md
 
 # 📦 `ErisPulse.Core.logger` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -1917,13 +2189,13 @@ ErisPulse 日志系统
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\mods.md
 
 # 📦 `ErisPulse.Core.mods` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -2106,13 +2378,13 @@ ErisPulse 模块管理器
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\raiserr.md
 
 # 📦 `ErisPulse.Core.raiserr` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -2216,13 +2488,13 @@ ErisPulse 错误管理系统
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\server.md
 
 # 📦 `ErisPulse.Core.server` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -2343,13 +2615,13 @@ ErisPulse Adapter Server
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 ## ErisPulse\Core\util.md
 
 # 📦 `ErisPulse.Core.util` 模块
 
-*自动生成于 2025-07-16 15:34:26*
+*自动生成于 2025-07-17 16:57:03*
 
 ---
 
@@ -2443,6 +2715,6 @@ ErisPulse 工具函数集合
 ---
 
 
-*文档最后更新于 2025-07-16 15:34:26*
+*文档最后更新于 2025-07-17 16:57:03*
 
 <!--- End of API文档 -->