ErisPulse 1.2.2__tar.gz → 1.2.3__tar.gz

{erispulse-1.2.2 → erispulse-1.2.3}/.github/tools/update-api-docs.py

@@ -60,7 +60,7 @@ def main():
     module_dir = Path('src/ErisPulse')
     reference_path = Path('docs/REFERENCE.md')
     
-    modules = ['__init__', '__main__', 'adapter', 'db', 'logger', 'mods', 'raiserr', 'util']
+    modules = ['__init__', '__main__', 'adapter', 'db', 'logger', 'raiserr', 'util']
     
     for module in modules:
         py_file = module_dir / f'{module}.py'

{erispulse-1.2.2 → erispulse-1.2.3}/LICENSE

@@ -2,6 +2,9 @@ MIT License
 
 Copyright (c) 2025 ErisPulse
 
+Portions of this software are based on https://github.com/FramerOrg/Framer 
+(Copyright (c) 2025 runoneall).
+
 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
@@ -19,3 +22,7 @@ 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.
+
+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).

{erispulse-1.2.2 → erispulse-1.2.3}/PKG-INFO

@@ -1,12 +1,15 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 1.2.2
+Version: 1.2.3
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>, runoneall <runoobsteve@gmail.com>
 License: MIT License
         
         Copyright (c) 2025 ErisPulse
         
+        Portions of this software are based on https://github.com/FramerOrg/Framer 
+        (Copyright (c) 2025 runoneall).
+        
         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
@@ -24,6 +27,10 @@ License: MIT License
         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).
 License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -38,6 +45,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: aiohttp
 Requires-Dist: importlib>=1.0.4
+Requires-Dist: pip
 Requires-Dist: watchdog
 Description-Content-Type: text/markdown
 

{erispulse-1.2.2 → erispulse-1.2.3}/docs/ADAPTERS.md

@@ -89,40 +89,253 @@ sdk.env.set("YunhuAdapter", {
 > - 云湖需要在控制台指向我们开启的 `server` 地址，否则无法正常接收消息。
 
 #### 数据格式示例
+云湖目前有9种事件会推送给机器人：
+
+|事件字段名称|事件用途|
+|:---:|:---:|
+|message.receive.normal|普通消息|
+|message.receive.instruction|指令消息|
+|group.join|用户加群|
+|group.leave|用户退群|
+|bot.followed|机器人关注|
+|bot.unfollowed|机器人取关|
+|bot.shortcut.menu|快捷菜单|
+|button.report.inline|按钮汇报|
+|bot.setting|机器人设置|
+
+每个事件的触发条件以及数据结构如下：
+
+##### 普通消息事件
+当用户向机器人或机器人所在的群聊发送消息，且没有选择指令时，将会触发该事件。
+```json
+{
+  "version": "1.0",
+  "header": 
+    "eventId": "c192ccc83d5147f2859ca77bcfafc9f9",
+    "eventType": "message.receive.normal",
+    "eventTime": 1748613099002
+  }
+  "event": {
+    "sender": 
+      "senderId": "6300451",
+      "senderType": "user",
+      "senderUserLevel": "owner",
+      "senderNickname": "ShanFish"
+    },
+    "chat": {
+      "chatId": "49871624",
+      "chatType": "bot"
+    },
+    "message": {
+      "msgId": "5c887bc0a82244c7969c08000f5b3ae8",
+      "parentId": "",
+      "sendTime": 1748613098989,
+      "chatId": "49871624",
+      "chatType": "bot",
+      "contentType": "text",
+      "content": {
+        "text": "你好"
+      },
+      "instructionId": 0,
+      "instructionName": "",
+      "commandId": 0,
+      "comandName": ""
+    }
+  }
+}
+```
+##### 指令消息事件
+当用户点击聊天栏的"/"图标时，将列出该机器人/群聊可用的所有指令。用户发送带有指令的消息后，将会触发该事件。
 ```json
 {
     "version": "1.0",
     "header": {
-        "eventId": "xxxxx",
-        "eventTime": 1647735644000,
-        "eventType": "message.receive.instruction"
+        "eventId": "ee74aded326b4578959073fe88f0076a",
+        "eventType": "message.receive.instruction",
+        "eventTime": 1749442433069
     },
     "event": {
         "sender": {
-            "senderId": "xxxxx",
+            "senderId": "6300451",
             "senderType": "user",
-            "senderUserLevel": "member",
-            "senderNickname": "昵称"
+            "senderUserLevel": "owner",
+            "senderNickname": "ShanFish"
         },
         "chat": {
-            "chatId": "xxxxx",
-            "chatType": "group"
+            "chatId": "49871624",
+            "chatType": "bot"
         },
         "message": {
-            "msgId": "xxxxxx",
-            "parentId": "xxxx",
-            "sendTime": 1647735644000,
-            "chatId": "xxxxxxxx",
-            "chatType": "group",
+            "msgId": "1d879c6ec68c4c52b78f87d83084955e",
+            "parentId": "",
+            "sendTime": 1749442433057,
+            "chatId": "49871624",
+            "chatType": "bot",
             "contentType": "text",
             "content": {
-                "text": "早上好"
+                "text": "/抽奖信息",
+                "menu": {}
             },
-            "commandId": 98,
-            "commandName": "计算器"
+            "instructionId": 1505,
+            "instructionName": "抽奖信息",
+            "commandId": 1505,
+            "commandName": "抽奖信息"
+        }
+    }
+}
+```
+##### 用户加群事件
+当用户加入机器人所在的群聊后，将会触发该事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "d5429cb5e4654fbcaeee9e4adb244741",
+        "eventType": "group.join",
+        "eventTime": 1749442891943
+    },
+    "event": {
+        "time": 1749442891843,
+        "chatId": "985140593",
+        "chatType": "group",
+        "userId": "3707697",
+        "nickname": "ShanFishApp",
+        "avatarUrl": "https://chat-storage1.jwznb.com/defalut-avatars/Ma%20Rainey.png?sign=b19c8978f4e0d9e43a8aec4f1e3c82ef&t=68466f5b"
+    }
+}
+```
+##### 用户退群事件
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "06959e95aaf547078367104ba754c554",
+        "eventType": "group.leave",
+        "eventTime": 1749442644367
+    },
+    "event": {
+        "time": 1749442644343,
+        "chatId": "985140593",
+        "chatType": "group",
+        "userId": "3707697",
+        "nickname": "ShanFishApp",
+        "avatarUrl": "https://chat-storage1.jwznb.com/defalut-avatars/Ma%20Rainey.png?sign=92fdef22a240a05de78b13afdab5ac51&t=68466e64"
+    }
+}
+```
+##### 用户关注机器人事件
+当用户在机器人ID或机器人推荐处添加机器人后，将会触发该事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "3fe280a400f9460daa03a642d1fad39b",
+        "eventType": "bot.followed",
+        "eventTime": 1749443049592
+    },
+    "event": {
+        "time": 1749443049580,
+        "chatId": "49871624",
+        "chatType": "bot",
+        "userId": "3707697",
+        "nickname": "ShanFishApp",
+        "avatarUrl": "https://chat-storage1.jwznb.com/defalut-avatars/Ma%20Rainey.png?sign=33bb173f1b22ed0e44da048b175767c6&t=68466ff9"
+    }
+}
+```
+##### 用户取关机器人事件
+当用户点击删除机器人按钮后，将会触发该事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "b4f51386d916464b99782052c030c5b7",
+        "eventType": "bot.unfollowed",
+        "eventTime": 1749443036382
+    },
+    "event": {
+        "time": 1749443036373,
+        "chatId": "49871624",
+        "chatType": "bot",
+        "userId": "3707697",
+        "nickname": "ShanFishApp",
+        "avatarUrl": "https://chat-storage1.jwznb.com/defalut-avatars/Ma%20Rainey.png?sign=07cf8e9d6ca0875835f9a4a6811b6b4c&t=68466fec"
+    }
+}
+```
+##### 按钮汇报事件
+机器人可以发送带按钮的消息。当用户按下按钮actionType为3(汇报类按钮)的按钮时，将会触发该事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "0d6d269ff7f046828c8562f905f9ee08",
+        "eventType": "button.report.inline",
+        "eventTime": 1749446185273
+    },
+    "event": {
+        "time": 1749446185268,
+        "msgId": "1838c3dd84474e9e9e1e00ca64e72065",
+        "recvId": "6300451",
+        "recvType": "user",
+        "userId": "6300451",
+        "value": "xxxx"
+    }
+}
+```
+
+##### 快捷菜单事件
+当用户点击了开发者自行配置的快捷菜单时，且该快捷菜单类型为普通菜单，将会触发本事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "93d0e36ce0334da58448409fd0527590",
+        "eventType": "bot.shortcut.menu",
+        "eventTime": 1749445822197
+    },
+    "event": {
+        "botId": "49871624",
+        "menuId": "HNH1LDHF",
+        "menuType": 1,
+        "menuAction": 1,
+        "chatId": "985140593",
+        "chatType": "group",
+        "senderType": "user",
+        "senderId": "6300451",
+        "sendTime": 1749445822
+    }
+}
+
+```
+##### 机器人设置事件
+当开发者配置了机器人设置项时，在机器人列表处将会出现"设置"按钮。用户设置完成后，将会触发本事件。
+```json
+{
+    "version": "1.0",
+    "header": {
+        "eventId": "5ad7e23399ef46a685cead1abe2efa19",
+        "eventType": "bot.setting",
+        "eventTime": 1749446299131
+    },
+    "event": {
+        "time": 1749446299128,
+        "chatId": "49871624",
+        "chatType": "bot",
+        "groupId": "985140593",
+        "groupName": "云湖测试群",
+        "avatarUrl": "https://chat-img.jwznb.com/77db590d9cee77de13e7c8cf0887b5ba.jpg",
+        "settingJson": {
+            "wezzrm": {
+                "id": "wezzrm",
+                "type": "switch",
+                "label": "测试",
+                "value": true
+            }
         }
     }
 }
+
 ```
 
 #### 注意：`chat` 与 `sender` 的误区

{erispulse-1.2.2 → erispulse-1.2.3}/docs/CHANGELOG.md

@@ -8,10 +8,20 @@
 > **贡献日志**
 > 如需为新版本添加日志，请在对应版本号下补充内容，并注明日期和主要贡献者。
 
+## [1.2.3]
+### 新增
+- 安装本地模块时自动安装依赖
+
+### 修复
+- 修复使用UV管理器安装SDK后安装模块时提示 "pip" 不存在的错误
+
+---
+
 ## [1.2.2]
 
 ### 修复
 - 初始化项目时自动初始化环境配置的时候两个环境变量被错误覆盖的问题
+
 ---
 
 ## [1.2.0]
@@ -64,6 +74,10 @@
 
 ---
 
+
+<details>
+<summary>历史版本（1.1.13 及更早）</summary>
+
 ## [1.1.12 - 1.1.13]
 ### 新增
 -  默认模块源,现在直接执行 epsdk update 命令即可添加并更新官方模块源
@@ -288,9 +302,6 @@
 
 ---
 
-<details>
-<summary>历史版本（1.0.11 及更早）</summary>
-
 ## [1.0.11]
 
 ### 改进

{erispulse-1.2.2 → erispulse-1.2.3}/docs/CLI.md

@@ -14,6 +14,8 @@
 | `upgrade`  | `[--force] [--init]`      | 升级模块（`--force` 强制覆盖）        | `epsdk upgrade --force --init`      |
 | `install`  | `<module...> [--init]`    | 安装一个或多个模块（空格分隔），支持本地目录路径 | `epsdk install YunhuAdapter OpenAI`<br>`epsdk install .`<br>`epsdk install /path/to/module` |
 | `uninstall`| `<module> [--init]`       | 移除指定模块                          | `epsdk uninstall old-module --init` |
+| `init`    | -                         | 初始化sdk | `epsdk init`                        |
+| `run` | `<script> [--reload]` | 运行指定脚本（支持热重载） | `epsdk run main.py --reload` |
 
 ## 源管理
 | 命令 | 参数 | 描述 | 示例 |
@@ -21,27 +23,6 @@
 | `origin add` | `<url>` | 添加源 | `epsdk origin add https://erisdev.com/map.json` |
 | `origin list` | - | 源列表 | `epsdk origin list` |
 | `origin del` | `<url>` | 删除源 | `epsdk origin del https://erisdev.com/map.json` |
-| `run` | `<script> [--reload]` | 运行指定脚本（支持热重载） | `epsdk run main.py --reload` |
-
----
-
-## 运行脚本命令详解
-
-`run` 命令支持以下参数：
-
-- `<script>`: 要运行的Python脚本路径
-- `--reload`: 启用热重载模式，当脚本文件发生变化时自动重启
-
-示例：
-```bash
-# 普通运行
-epsdk run main.py
-
-# 热重载模式
-epsdk run main.py --reload
-```
-
-热重载模式下，任何对脚本文件的修改都会触发自动重启，方便开发调试。
 
 ---
 

{erispulse-1.2.2 → erispulse-1.2.3}/docs/DEVELOPMENT.md

@@ -19,15 +19,9 @@
 #### 日志记录：
 
 ```python
-#  设置日志级别
-sdk.logger.set_level("DEBUG")
-
 #  设置单个模块日志级别
 sdk.logger.set_module_level("MyModule", "DEBUG")
 
-#  设置日志输出到文件
-sdk.logger.set_output_file("log.txt")
-
 #  单次保持所有模块日志历史到文件
 sdk.logger.save_logs("log.txt")
 
@@ -115,10 +109,6 @@ async def my_retry_function():
     # 此函数会在异常时自动重试 3 次，每次间隔 1 秒
     ...
 
-# 可视化模块依赖关系
-topology = sdk.util.show_topology()
-print(topology)  # 打印模块依赖拓扑图
-
 # 缓存装饰器：缓存函数调用结果（基于参数）
 @sdk.util.cache
 def get_expensive_result(param):
@@ -131,8 +121,8 @@ def sync_task():
     # 此函数将在独立线程中运行，避免阻塞事件循环
     ...
 
-# 异步调用同步函数的快捷方式
-sdk.util.ExecAsync(sync_task)  # 在事件循环中
+# 在同步函数中调用异步任务
+sdk.util.ExecAsync(sync_task)
 
 ```
 
@@ -181,7 +171,11 @@ moduleInfo = {
     },
     "dependencies": {
         "requires": [],       # 必须依赖的其他模块
-        "optional": [],       # 可选依赖模块列表（满足其中一个即可）
+        "optional": [         # 可选依赖模块列表（满足其中一个即可）
+            "可选模块",
+            ["可选模块"],
+            ["可选组依赖模块1", "可选组依赖模块2"]
+        ],
         "pip": []             # 第三方 pip 包依赖
     }
 }
@@ -189,6 +183,10 @@ moduleInfo = {
 from .Core import Main
 ```
 
+其中, 可选依赖支持组依赖：
+- 可选模块与组依赖模块（如 `["组依赖模块1", "组依赖模块2"]` 和 `["组依赖模块3", "组依赖模块4"]`）构成“或”关系，即满足其中一组即可。
+- 组依赖模块以数组形式表示，视为一个整体（例如：`组依赖模块1 + 组依赖模块2` 和 `可选模块` 中任意一组存在即符合要求）。
+
 > ⚠️ 注意：模块名必须唯一，避免与其他模块冲突。
 
 ---
@@ -279,7 +277,7 @@ class Main:
         #   在 MyPlatformAdapter 中的方法可以使用 sdk.adapter.<适配器注册名>.<方法名> 访问
 
 class MyPlatformAdapter(sdk.BaseAdapter):
-    class Send(super().Send):  # 继承BaseAdapter内置的Send类
+    class Send(sdk.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) 的方式直接调用这里的方法