ErisPulse 1.1.16__tar.gz → 1.2.0__tar.gz

{erispulse-1.1.16 → erispulse-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 1.1.16
+Version: 1.2.0
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>, runoneall <runoobsteve@gmail.com>
 License: MIT License

{erispulse-1.1.16 → erispulse-1.2.0}/docs/ADAPTERS.md

@@ -69,6 +69,25 @@ buttons = [
 await yunhu.Send.To("user", user_id).Text("带按钮的消息", buttons=buttons)
 ```
 
+#### env.py 配置示例
+```python
+sdk.env.set("YunhuAdapter", {
+    "token": "",       # 机器人 Token
+    "mode": "server",  # server / polling (polling使用社区脚本支持)
+    "server": {
+        "host": "0.0.0.0",
+        "port": 25888,
+        "path": "/yunhu/webhook"
+    },
+    "polling": {
+        "url": "https://example.com/",
+    }
+})
+```
+> **注意：**
+> - 云湖适配器使用 `server` 模式时，需要配置 `server` 字段；使用 `polling` 模式时，需要配置 `polling` 字段。
+> - 云湖需要在控制台指向我们开启的 `server` 地址，否则无法正常接收消息。
+
 #### 数据格式示例
 ```json
 {
@@ -175,33 +194,39 @@ await telegram.Send.To("user", user_id).Text("Hello World!")
 - `.DeleteMessage(message_id: int)`：删除指定消息。
 - `.GetChat()`：获取聊天信息。
 
-#### 数据格式示例
-```json
-{
-  "update_id": 123456789,
-  "message": {
-    "message_id": 101,
-    "from": {
-      "id": 123456789,
-      "is_bot": false,
-      "first_name": "John",
-      "last_name": "Doe",
-      "username": "johndoe",
-      "language_code": "en"
+#### env.py 配置示例
+```python
+sdk.env.set("TelegramAdapter", {
+    # 必填：Telegram Bot Token
+    "token": "YOUR_BOT_TOKEN",
+
+    # Webhook 模式下的服务配置（如使用 webhook）
+    "server": {
+        "host": "127.0.0.1",            # 推荐监听本地，防止外网直连
+        "port": 8443,                   # 监听端口
+        "path": "/telegram/webhook"     # Webhook 路径
     },
-    "chat": {
-      "id": 123456789,
-      "first_name": "John",
-      "last_name": "Doe",
-      "username": "johndoe",
-      "type": "private"
-},
-    "date": 1672531199,
-    "text": "Hello!"
-  }
-}
+    "webhook": {
+        "host": "example.com",          # Telegram API 监听地址（外部地址）
+        "port": 8443,                   # 监听端口
+        "path": "/telegram/webhook"     # Webhook 路径
+    }
+
+    # 启动模式: webhook 或 polling
+    "mode": "webhook",
+
+    # 可选：代理配置（用于连接 Telegram API）
+    "proxy": {
+        "host": "127.0.0.1",
+        "port": 1080,
+        "type": "socks5"  # 支持 socks4 / socks5
+    }
+})
 ```
 
+#### 数据格式示例
+> 略: 使用你了解的 TG 事件数据格式即可,这里不进行演示
+
 ---
 
 ### 3. OneBotAdapter
@@ -232,20 +257,26 @@ await onebot.Send.To("group", group_id).Text("Hello World!")
 - `.Edit(message_id: int, new_text: str)`：编辑消息。
 - `.Batch(target_ids: List[str], text: str)`：批量发送消息。
 
-#### 数据格式示例
-```json
-{
-  "post_type": "message",
-  "message_type": "group",
-  "group_id": 123456,
-  "user_id": 987654321,
-  "message": "Hello!",
-  "raw_message": "Hello!",
-  "time": 1672531199,
-  "self_id": 123456789
-}
+#### env.py 配置示例
+```python
+sdk.env.set("OneBotAdapter", {
+    "mode": "client", # 或者 "server"
+    "server": {
+        "host": "127.0.0.1",
+        "port": 8080,
+        "path": "/",
+        "token": ""
+    },
+    "client": {
+        "url": "ws://127.0.0.1:3001",
+        "token": ""
+    }
+})
 ```
 
+#### 数据格式示例
+> 略: 使用你了解的 OneBot v11 事件数据格式即可,这里不进行演示
+
 ---
 
 ## 生命周期管理

{erispulse-1.1.16 → erispulse-1.2.0}/docs/CHANGELOG.md

@@ -8,6 +8,16 @@
 > **贡献日志**
 > 如需为新版本添加日志，请在对应版本号下补充内容，并注明日期和主要贡献者。
 
+## [1.2.0]
+### 新增
+- 添加 `main.py` 的初始化方法
+- 添加CLI: `epsdk init` 初始化项目
+
+### 修复
+- 修复 `Windows` 平台下安装本地模块时无法指定目录的问题
+
+---
+
 ## [1.1.16]
 ### 修复
 - 修复本地模块安装时可能出现的错误

{erispulse-1.1.16 → erispulse-1.2.0}/docs/DEVELOPMENT.md

@@ -346,7 +346,7 @@ class MyPlatformAdapter(sdk.BaseAdapter):
 > - 必须实现 `call_api`, `start`, `shutdown` 方法 和 `Send`类并继承自 `super().Send`；
 > - 推荐实现 `.Text(...)` 方法作为基础消息发送接口。
 
-## 4. DSL 风格消息接口（SendDSL）
+### 4. DSL 风格消息接口（SendDSL）
 
 每个适配器可定义一组链式调用风格的方法，例如：
 
@@ -372,6 +372,25 @@ sdk.adapter.MyPlatform.Send.To("user", "U1001").Text("你好")
 > 建议方法名首字母大写，保持命名统一。
 
 ---
+### 四、最简 main.py 示例
+```python
+from ErisPulse import sdk
+
+async def main():
+    try:
+        sdk.init()
+        await sdk.adapter.startup()
+
+    except Exception as e:
+        sdk.logger.error(e)
+    except KeyboardInterrupt:
+        sdk.logger.info("正在停止程序")
+    finally:
+        await sdk.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
 ### 四、开发建议
 

{erispulse-1.1.16 → erispulse-1.2.0}/docs/ForAIDocs/ErisPulseDevelop.md

@@ -523,7 +523,7 @@ class MyPlatformAdapter(sdk.BaseAdapter):
 > - 必须实现 `call_api`, `start`, `shutdown` 方法 和 `Send`类并继承自 `super().Send`；
 > - 推荐实现 `.Text(...)` 方法作为基础消息发送接口。
 
-## 4. DSL 风格消息接口（SendDSL）
+### 4. DSL 风格消息接口（SendDSL）
 
 每个适配器可定义一组链式调用风格的方法，例如：
 
@@ -549,6 +549,25 @@ sdk.adapter.MyPlatform.Send.To("user", "U1001").Text("你好")
 > 建议方法名首字母大写，保持命名统一。
 
 ---
+### 四、最简 main.py 示例
+```python
+from ErisPulse import sdk
+
+async def main():
+    try:
+        sdk.init()
+        await sdk.adapter.startup()
+
+    except Exception as e:
+        sdk.logger.error(e)
+    except KeyboardInterrupt:
+        sdk.logger.info("正在停止程序")
+    finally:
+        await sdk.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
 ### 四、开发建议
 
@@ -1876,6 +1895,25 @@ buttons = [
 await yunhu.Send.To("user", user_id).Text("带按钮的消息", buttons=buttons)
 ```
 
+#### env.py 配置示例
+```python
+sdk.env.set("YunhuAdapter", {
+    "token": "",       # 机器人 Token
+    "mode": "server",  # server / polling (polling使用社区脚本支持)
+    "server": {
+        "host": "0.0.0.0",
+        "port": 25888,
+        "path": "/yunhu/webhook"
+    },
+    "polling": {
+        "url": "https://example.com/",
+    }
+})
+```
+> **注意：**
+> - 云湖适配器使用 `server` 模式时，需要配置 `server` 字段；使用 `polling` 模式时，需要配置 `polling` 字段。
+> - 云湖需要在控制台指向我们开启的 `server` 地址，否则无法正常接收消息。
+
 #### 数据格式示例
 ```json
 {
@@ -1982,33 +2020,39 @@ await telegram.Send.To("user", user_id).Text("Hello World!")
 - `.DeleteMessage(message_id: int)`：删除指定消息。
 - `.GetChat()`：获取聊天信息。
 
-#### 数据格式示例
-```json
-{
-  "update_id": 123456789,
-  "message": {
-    "message_id": 101,
-    "from": {
-      "id": 123456789,
-      "is_bot": false,
-      "first_name": "John",
-      "last_name": "Doe",
-      "username": "johndoe",
-      "language_code": "en"
+#### env.py 配置示例
+```python
+sdk.env.set("TelegramAdapter", {
+    # 必填：Telegram Bot Token
+    "token": "YOUR_BOT_TOKEN",
+
+    # Webhook 模式下的服务配置（如使用 webhook）
+    "server": {
+        "host": "127.0.0.1",            # 推荐监听本地，防止外网直连
+        "port": 8443,                   # 监听端口
+        "path": "/telegram/webhook"     # Webhook 路径
     },
-    "chat": {
-      "id": 123456789,
-      "first_name": "John",
-      "last_name": "Doe",
-      "username": "johndoe",
-      "type": "private"
-},
-    "date": 1672531199,
-    "text": "Hello!"
-  }
-}
+    "webhook": {
+        "host": "example.com",          # Telegram API 监听地址（外部地址）
+        "port": 8443,                   # 监听端口
+        "path": "/telegram/webhook"     # Webhook 路径
+    }
+
+    # 启动模式: webhook 或 polling
+    "mode": "webhook",
+
+    # 可选：代理配置（用于连接 Telegram API）
+    "proxy": {
+        "host": "127.0.0.1",
+        "port": 1080,
+        "type": "socks5"  # 支持 socks4 / socks5
+    }
+})
 ```
 
+#### 数据格式示例
+> 略: 使用你了解的 TG 事件数据格式即可,这里不进行演示
+
 ---
 
 ### 3. OneBotAdapter
@@ -2039,20 +2083,26 @@ await onebot.Send.To("group", group_id).Text("Hello World!")
 - `.Edit(message_id: int, new_text: str)`：编辑消息。
 - `.Batch(target_ids: List[str], text: str)`：批量发送消息。
 
-#### 数据格式示例
-```json
-{
-  "post_type": "message",
-  "message_type": "group",
-  "group_id": 123456,
-  "user_id": 987654321,
-  "message": "Hello!",
-  "raw_message": "Hello!",
-  "time": 1672531199,
-  "self_id": 123456789
-}
+#### env.py 配置示例
+```python
+sdk.env.set("OneBotAdapter", {
+    "mode": "client", # 或者 "server"
+    "server": {
+        "host": "127.0.0.1",
+        "port": 8080,
+        "path": "/",
+        "token": ""
+    },
+    "client": {
+        "url": "ws://127.0.0.1:3001",
+        "token": ""
+    }
+})
 ```
 
+#### 数据格式示例
+> 略: 使用你了解的 OneBot v11 事件数据格式即可,这里不进行演示
+
 ---
 
 ## 生命周期管理

{erispulse-1.1.16 → erispulse-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "1.1.16"
+version = "1.2.0"
 description = "ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。"
 readme = "README.md"
 requires-python = ">=3.10"

{erispulse-1.1.16 → erispulse-1.2.0}/src/ErisPulse/__init__.py

@@ -87,12 +87,67 @@ for error, doc in BaseErrors.items():
         raiserr.register(error, doc=doc)
     except Exception as e:
         raise e
+def init_progress():
+    from pathlib import Path
+    env_file = Path("env.py")
+    main_file = Path("main.py")
+
+    if not env_file.exists():
+        content = '''# env.py
+# ErisPulse 环境配置文件
+# 本文件由 SDK 自动创建，请勿随意删除
+# 配置项可通过 sdk.env.get(key, default) 获取，或使用 sdk.env.set(key, value) 设置
+# 你也可以像写普通变量一样直接定义配置项，例如：
+#
+#     MY_CONFIG = "value"
+#     MY_CONFIG_2 = {"key": "value"}
+#     MY_CONFIG_3 = [1, 2, 3]
+#
+#     sdk.env.set("MY_CONFIG", "value")
+#     sdk.env.set("MY_CONFIG_2", {"key": "value"})
+#     sdk.env.set("MY_CONFIG_3", [1, 2, 3])
+#
+# 这些变量会自动被加载到 SDK 的配置系统中，可通过 sdk.env.MY_CONFIG 或 sdk.env.get("MY_CONFIG") 访问。
+
+from ErisPulse import sdk
+'''
+    if not main_file.exists():
+        content += '''# main.py
+# ErisPulse 主程序文件
+# 本文件由 SDK 自动创建，您可随意修改
+
+from ErisPulse import sdk
+
+async def main():
+    try:
+        sdk.init()
+        await sdk.adapter.startup()
+
+    except Exception as e:
+        sdk.logger.error(e)
+    except KeyboardInterrupt:
+        sdk.logger.info("正在停止程序")
+    finally:
+        await sdk.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+'''
+        try:
+            with open(env_file, "w", encoding="utf-8") as f:
+                f.write(content)
+            return True
+        except Exception as e:
+            from . import sdk
+            sdk.logger.error(f"无法初始化项目环境: {e}")
+            return False
+    return False
 
 def _prepare_environment() -> bool:
     # 检查环境
     logger.info("[Init] 准备初始化环境...")
     try:
-        if env.create_env_file_if_not_exists():
+        if init_progress():
             logger.info("[Init] 项目首次初始化，建议先配置环境变量")
             if input("是否立即退出？(y/n): ").strip().lower() == "y":
                 return False

{erispulse-1.1.16 → erispulse-1.2.0}/src/ErisPulse/__main__.py

@@ -551,29 +551,27 @@ def install_pip_dependencies(dependencies):
         return False
 
 def install_local_module(module_path, force=False):
-    """安装本地目录中的模块"""
-    module_path = os.path.abspath(module_path)
-    if not os.path.exists(module_path):
-        shellprint.panel(f"路径不存在: {module_path}", "错误", "error")
-        return False
-    
-    # 尝试从目录名获取模块名
-    module_name = os.path.basename(module_path.rstrip('/\\'))
-    
-    # 检查是否是有效的模块目录
-    init_py = os.path.join(module_path, '__init__.py')
-    if not os.path.exists(init_py):
-        shellprint.panel(f"目录 {module_path} 不是一个有效的Python模块", "错误", "error")
-        return False
-    
-    # 尝试导入模块获取moduleInfo
     try:
-        spec = importlib.util.spec_from_file_location(module_name, init_py)
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        if not hasattr(module, 'moduleInfo'):
-            shellprint.panel(f"模块 {module_name} 缺少 moduleInfo 定义", "错误", "error")
+        module_path = os.path.abspath(module_path)
+        if not os.path.exists(module_path):
+            shellprint.panel(f"路径不存在: {module_path}", "错误", "error")
             return False
+        
+        module_name = os.path.basename(module_path.rstrip('/\\'))
+        init_py = os.path.join(module_path, '__init__.py')
+        
+        if not os.path.exists(init_py):
+            shellprint.panel(f"目录 {module_path} 不是一个有效的Python模块", "错误", "error")
+            return False
+        import sys
+        sys.path.insert(0, os.path.dirname(module_path))
+        try:
+            module = importlib.import_module(module_name)
+            if not hasattr(module, 'moduleInfo'):
+                shellprint.panel(f"模块 {module_name} 缺少 moduleInfo 定义", "错误", "error")
+                return False
+        finally:
+            sys.path.remove(os.path.dirname(module_path))
     except Exception as e:
         shellprint.panel(f"导入模块 {module_name} 失败: {e}", "错误", "error")
         return False

{erispulse-1.1.16 → erispulse-1.2.0}/src/ErisPulse/db.py

@@ -646,38 +646,6 @@ class EnvManager:
             for key, value in vars(env_module).items():
                 if not key.startswith("__") and isinstance(value, (dict, list, str, int, float, bool)):
                     self.set(key, value)
-
-    def create_env_file_if_not_exists(self):
-        env_file = Path("env.py")
-        if not env_file.exists():
-            content = '''# env.py
-# ErisPulse 环境配置文件
-# 本文件由 SDK 自动创建，请勿随意删除
-# 配置项可通过 sdk.env.get(key, default) 获取，或使用 sdk.env.set(key, value) 设置
-# 你也可以像写普通变量一样直接定义配置项，例如：
-#
-#     MY_CONFIG = "value"
-#     MY_CONFIG_2 = {"key": "value"}
-#     MY_CONFIG_3 = [1, 2, 3]
-#
-#     sdk.env.set("MY_CONFIG", "value")
-#     sdk.env.set("MY_CONFIG_2", {"key": "value"})
-#     sdk.env.set("MY_CONFIG_3", [1, 2, 3])
-#
-# 这些变量会自动被加载到 SDK 的配置系统中，可通过 sdk.env.MY_CONFIG 或 sdk.env.get("MY_CONFIG") 访问。
-
-from ErisPulse import sdk
-'''
-            try:
-                with open(env_file, "w", encoding="utf-8") as f:
-                    f.write(content)
-                return True
-            except Exception as e:
-                from . import sdk
-                sdk.logger.error(f"无法创建 env.py 文件: {e}")
-                return False
-        return False
-
     def __getattr__(self, key):
         try:
             return self.get(key)