ErisPulse 2.6.2.dev1__tar.gz → 2.6.3.dev0__tar.gz

erispulse-2.6.3.dev0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: ErisPulse
+Version: 2.6.3.dev0
+Summary: Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署
+Project-URL: Homepage, https://github.com/ErisPulse/ErisPulse
+Project-URL: Documentation, https://www.erisdev.com#docs
+Project-URL: Repository, https://github.com/ErisPulse/ErisPulse
+Project-URL: Issues, https://github.com/ErisPulse/ErisPulse/issues
+Project-URL: Bug Tracker, https://github.com/ErisPulse/ErisPulse/blob/main/docs/en/bug-tracker.md
+Project-URL: Changelog, https://github.com/ErisPulse/ErisPulse/blob/main/CHANGELOG.md
+Author: ErisDev
+Maintainer-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>
+License: MIT License
+        
+        Copyright (c) 2025-2026 ErisPulse
+        
+        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
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        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.
+License-File: LICENSE
+Keywords: async,asyncio,bot,bot-framework,chatbot,email,extensible,framework,instant-messaging,kook,matrix,modular,multi-platform,onebot,onebot12,qq,robot,sdk,telegram,yunhu
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: fastapi>=0.116.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.20.0; extra == 'dev'
+Requires-Dist: pyclean>=3.6.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.7; extra == 'dev'
+Requires-Dist: typing-extensions>=4.7.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: test
+Requires-Dist: httpx>=0.24.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+![ErisPulse](https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/mascot-hero.png)
+
+# ErisPulse
+
+**Write once, deploy on multiple platforms.**
+
+An event-driven, multi-platform chatbot development framework based on the OneBot12 standard.
+
+[![PyPI](https://img.shields.io/pypi/v/ErisPulse?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ErisPulse/)
+[![Python](https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue)](https://pypi.org/project/ErisPulse/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/ErisPulse/ErisPulse/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-erisdev.com-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white)](https://www.erisdev.com)
+[![Stars](https://img.shields.io/github/stars/ErisPulse/ErisPulse?style=for-the-badge&logo=github&color=brightgreen)](https://github.com/ErisPulse/ErisPulse)
+[![Downloads](https://img.shields.io/pepy/dt/ErisPulse?style=for-the-badge&color=blue)](https://pepy.tech/project/ErisPulse)
+[![Discussions](https://img.shields.io/badge/GitHub-Discussions-181717?style=for-the-badge&logo=github)](https://github.com/ErisPulse/ErisPulse/discussions)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/erispulse/erispulse)
+
+---
+
+## Overview
+
+ErisPulse is an event-driven, modular async framework for building chatbots that run on **multiple platforms from a single codebase**. It implements the [OneBot12](https://12.onebot.dev/) standard event model, so you write command handlers, conversation flows and message senders once — then deploy them to QQ, Telegram, Discord, Kook, Yunhu, Matrix, Email, WeChat and more without touching business logic.
+
+It ships with a flexible plugin system, hot reload, a visual Dashboard, an AI Builder that turns natural-language prompts into modules, and the `epsdk` CLI scaffolding tool — suitable for everything from a simple chatbot to a complex automation pipeline.
+
+## Key Features
+
+- **Event-driven architecture** — Clear event model based on OneBot12, making message handling intuitive and consistent across platforms.
+- **Cross-platform compatibility** — Write handlers once, deploy to 15+ platforms without rewriting business logic.
+- **Modular design** — Flexible plugin system with hot-plug module management and per-module configuration.
+- **Hot reload** — Iterate on code during development without restarting the bot process.
+- **Chainable SendDSL** — Express `@mention`, reply, retry, timeout, progress hook and bulk send as a single fluent chain.
+- **Complete toolchain** — `epsdk` CLI, visual Dashboard, AI Builder and Module Market included out of the box.
+
+## Installation
+
+### Option 1 — pip (for library / module developers)
+
+```bash
+pip install ErisPulse
+```
+
+### Option 2 — Docker (recommended for production)
+
+```bash
+docker pull erispulse/erispulse:latest
+```
+
+Quick start with `docker-compose.yml`:
+
+```bash
+curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml
+ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d
+```
+
+The image bundles the ErisPulse framework **and** the Dashboard management panel, supporting `linux/amd64` and `linux/arm64`. After startup, visit `http://<host>:<port>/Dashboard` and log in with the token you set.
+
+<details>
+<summary>Docker Hub unavailable? Use GitHub Container Registry</summary>
+
+```bash
+docker pull ghcr.io/erispulse/erispulse:latest
+```
+
+And update the image in your `docker-compose.yml`:
+
+```yaml
+image: ghcr.io/erispulse/erispulse:latest
+```
+
+</details>
+
+<details>
+<summary>Docker environment variables</summary>
+
+| Variable | Default | Description |
+|------|--------|------|
+| `ERISPULSE_CHANNEL` | `stable` | Version channel: `stable` or `dev` (pre-release) |
+| `ERISPULSE_UPDATE_ON_START` | `false` | Auto-update to the latest version on container start |
+| `ERISPULSE_DASHBOARD_TOKEN` | empty | Dashboard login token |
+| `ERISPULSE_PORT` | `8000` | Dashboard port mapping |
+| `TZ` | `Asia/Shanghai` | Container timezone |
+
+</details>
+
+### Option 3 — One-click install script (auto-detects environment)
+
+The installer detects Docker / Python / uv and guides you through the most suitable setup. Supports Chinese, English, Japanese, Russian and Traditional Chinese.
+
+Windows (PowerShell):
+
+```powershell
+irm https://get.erisdev.com/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1
+```
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://get.erisdev.com/install.sh -o install.sh && chmod +x install.sh && ./install.sh
+```
+
+## Quick Start
+
+Initialize a new project:
+
+```bash
+# Interactive initialization
+epsdk init
+
+# Quick initialization with a project name
+epsdk init -q -n my_bot
+```
+
+Create a `main.py` file:
+
+```python
+from ErisPulse import sdk
+from ErisPulse.Core.Event import command
+
+@command("hello", help="Send greeting message")
+async def hello_handler(event):
+    user_name = event.get_user_nickname() or "friend"
+    await event.reply(f"Hello, {user_name}!")
+
+@command("ping", help="Test if the bot is online")
+async def ping_handler(event):
+    await event.reply("Pong! The bot is running normally.")
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(sdk.run(keep_running=True))
+```
+
+Run it:
+
+```bash
+epsdk run main.py
+# Or in development mode with hot reload
+epsdk run main.py --reload
+```
+
+Now send `/hello` or `/ping` to the bot on any connected platform — the same handlers work everywhere.
+
+For the full walkthrough (multi-turn conversations, request handlers, adapter configuration), see the [Quick Start guide](https://www.erisdev.com#docs).
+
+## The SendDSL — fluent message sending
+
+Compose the entire send flow — `@mention`, reply, retry, timeout, progress hook and bulk dispatch — as one readable chain:
+
+```python
+yunhu = sdk.adapter.get("yunhu")
+
+# Single send: @user + reply + retry + timeout + success callback
+await (yunhu.Send.To("group", "123")
+       .At("456").Reply("msg_789")
+       .Retry(3).Timeout(10)
+       .Hook(lambda r: print("Send successful!"))
+       .Text("Hello"))
+
+# Bulk send: build multiple messages, then dispatch in one chain
+results = await (yunhu.Send.To("user", "123")
+                .Build()
+                .Text("Notification 1")
+                .Image("pic.jpg")
+                .Retry(2)
+                .send_all())
+```
+
+Supported chainable methods include `Hook` (success callback), `Retry` (failure retry), `Timeout` (timeout cancellation), `OnProgress` (progress monitoring), `Defer` (delayed send) and `Build` (batch construction).
+
+> Full reference: [SendDSL documentation](https://www.erisdev.com#docs)
+
+## Supported Platforms
+
+Officially maintained adapters (community contributions welcome):
+
+- [Kook](https://github.com/shanfishapp/ErisPulse-KookAdapter) — instant messaging platform
+- [Matrix](https://github.com/ErisPulse/ErisPulse-MatrixAdapter) — decentralized communication protocol
+- [OneBot11](https://github.com/ErisPulse/ErisPulse-OneBot11Adapter) — universal OneBot v11 protocol
+- [OneBot12](https://github.com/ErisPulse/ErisPulse-OneBot12Adapter) — OneBot v12 standard protocol
+- [QQ Bot](https://github.com/ErisPulse/ErisPulse-QQBotAdapter) — official QQ bot platform
+- [Telegram](https://github.com/ErisPulse/ErisPulse-TelegramAdapter) — global instant messaging
+- [Discord](https://github.com/ErisPulse/ErisPulse-DiscordAdapter) — community communication platform
+- [Yunhu](https://github.com/ErisPulse/ErisPulse-YunhuAdapter) / [Yunhu User](https://github.com/wsu2059q/ErisPulse-YunhuUserAdapter) — enterprise IM
+- [Email](https://github.com/ErisPulse/ErisPulse-EmailAdapter) — email protocol adapter
+- [WeChat Official Account](https://github.com/ErisPulse/ErisPulse-WechatMpAdapter)
+- [Webhook](https://github.com/ErisPulse/ErisPulse-WebhookAdapter) — HTTP bridge to any system
+- [Sandbox](https://github.com/ErisPulse/ErisPulse-SandboxAdapter) — in-browser debugging, no real platform needed
+- [HuaFeng Coffee House](https://github.com/ErisPulse/ErisPulse-Ideaura/)
+
+See the [adapter guide](https://www.erisdev.com#docs) for configuration details.
+
+## Ecosystem
+
+- **Framework** — core runtime with a unified event & message model.
+- **Dashboard** — visual management for plugins, logs and configuration. ([live demo](https://dashdemo.erisdev.com/))
+- **AI Builder** — natural-language prompts → ready-to-use modules. ([try it](https://www.erisdev.com/#builder))
+- **Module Market** — plug-and-play community plugins. ([browse](https://www.erisdev.com/#market))
+- **CLI** — `epsdk` scaffolding, project init, run and reload.
+- **Docker** — multi-architecture images at `erispulse/erispulse`.
+
+## Documentation & Community
+
+- 📖 **Documentation & API reference:** [erisdev.com](https://www.erisdev.com)
+- 💬 **GitHub Discussions:** [ErisPulse/ErisPulse/discussions](https://github.com/ErisPulse/ErisPulse/discussions)
+- 📋 **Changelog:** [CHANGELOG.md](https://github.com/ErisPulse/ErisPulse/blob/main/CHANGELOG.md)
+- 🤝 **Contributing:** [CONTRIBUTING.md](https://github.com/ErisPulse/ErisPulse/blob/main/CONTRIBUTING.md)
+- 🐛 **Bug reports:** [GitHub Issues](https://github.com/ErisPulse/ErisPulse/issues)
+- 🧠 **DeepWiki:** [deepwiki.com/ErisPulse/ErisPulse](https://deepwiki.com/ErisPulse/ErisPulse)
+
+Chat with us on:
+
+- Telegram: <https://t.me/ErisPulse>
+- QQ Group: <https://qm.qq.com/q/TOwnCmypcy>
+- Yunhu Group: <https://yhfx.jwznb.com/share?key=VWJL4fTWXepa&ts=1781889199>
+
+---
+
+**Why ErisPulse?** Because platform differences should never be your bottleneck — focus on business logic, and let the framework handle the rest. Write once, deploy everywhere.

erispulse-2.6.3.dev0/README.pypi.md

@@ -0,0 +1,219 @@
+![ErisPulse](https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/mascot-hero.png)
+
+# ErisPulse
+
+**Write once, deploy on multiple platforms.**
+
+An event-driven, multi-platform chatbot development framework based on the OneBot12 standard.
+
+[![PyPI](https://img.shields.io/pypi/v/ErisPulse?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ErisPulse/)
+[![Python](https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue)](https://pypi.org/project/ErisPulse/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/ErisPulse/ErisPulse/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-erisdev.com-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white)](https://www.erisdev.com)
+[![Stars](https://img.shields.io/github/stars/ErisPulse/ErisPulse?style=for-the-badge&logo=github&color=brightgreen)](https://github.com/ErisPulse/ErisPulse)
+[![Downloads](https://img.shields.io/pepy/dt/ErisPulse?style=for-the-badge&color=blue)](https://pepy.tech/project/ErisPulse)
+[![Discussions](https://img.shields.io/badge/GitHub-Discussions-181717?style=for-the-badge&logo=github)](https://github.com/ErisPulse/ErisPulse/discussions)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/erispulse/erispulse)
+
+---
+
+## Overview
+
+ErisPulse is an event-driven, modular async framework for building chatbots that run on **multiple platforms from a single codebase**. It implements the [OneBot12](https://12.onebot.dev/) standard event model, so you write command handlers, conversation flows and message senders once — then deploy them to QQ, Telegram, Discord, Kook, Yunhu, Matrix, Email, WeChat and more without touching business logic.
+
+It ships with a flexible plugin system, hot reload, a visual Dashboard, an AI Builder that turns natural-language prompts into modules, and the `epsdk` CLI scaffolding tool — suitable for everything from a simple chatbot to a complex automation pipeline.
+
+## Key Features
+
+- **Event-driven architecture** — Clear event model based on OneBot12, making message handling intuitive and consistent across platforms.
+- **Cross-platform compatibility** — Write handlers once, deploy to 15+ platforms without rewriting business logic.
+- **Modular design** — Flexible plugin system with hot-plug module management and per-module configuration.
+- **Hot reload** — Iterate on code during development without restarting the bot process.
+- **Chainable SendDSL** — Express `@mention`, reply, retry, timeout, progress hook and bulk send as a single fluent chain.
+- **Complete toolchain** — `epsdk` CLI, visual Dashboard, AI Builder and Module Market included out of the box.
+
+## Installation
+
+### Option 1 — pip (for library / module developers)
+
+```bash
+pip install ErisPulse
+```
+
+### Option 2 — Docker (recommended for production)
+
+```bash
+docker pull erispulse/erispulse:latest
+```
+
+Quick start with `docker-compose.yml`:
+
+```bash
+curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml
+ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d
+```
+
+The image bundles the ErisPulse framework **and** the Dashboard management panel, supporting `linux/amd64` and `linux/arm64`. After startup, visit `http://<host>:<port>/Dashboard` and log in with the token you set.
+
+<details>
+<summary>Docker Hub unavailable? Use GitHub Container Registry</summary>
+
+```bash
+docker pull ghcr.io/erispulse/erispulse:latest
+```
+
+And update the image in your `docker-compose.yml`:
+
+```yaml
+image: ghcr.io/erispulse/erispulse:latest
+```
+
+</details>
+
+<details>
+<summary>Docker environment variables</summary>
+
+| Variable | Default | Description |
+|------|--------|------|
+| `ERISPULSE_CHANNEL` | `stable` | Version channel: `stable` or `dev` (pre-release) |
+| `ERISPULSE_UPDATE_ON_START` | `false` | Auto-update to the latest version on container start |
+| `ERISPULSE_DASHBOARD_TOKEN` | empty | Dashboard login token |
+| `ERISPULSE_PORT` | `8000` | Dashboard port mapping |
+| `TZ` | `Asia/Shanghai` | Container timezone |
+
+</details>
+
+### Option 3 — One-click install script (auto-detects environment)
+
+The installer detects Docker / Python / uv and guides you through the most suitable setup. Supports Chinese, English, Japanese, Russian and Traditional Chinese.
+
+Windows (PowerShell):
+
+```powershell
+irm https://get.erisdev.com/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1
+```
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://get.erisdev.com/install.sh -o install.sh && chmod +x install.sh && ./install.sh
+```
+
+## Quick Start
+
+Initialize a new project:
+
+```bash
+# Interactive initialization
+epsdk init
+
+# Quick initialization with a project name
+epsdk init -q -n my_bot
+```
+
+Create a `main.py` file:
+
+```python
+from ErisPulse import sdk
+from ErisPulse.Core.Event import command
+
+@command("hello", help="Send greeting message")
+async def hello_handler(event):
+    user_name = event.get_user_nickname() or "friend"
+    await event.reply(f"Hello, {user_name}!")
+
+@command("ping", help="Test if the bot is online")
+async def ping_handler(event):
+    await event.reply("Pong! The bot is running normally.")
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(sdk.run(keep_running=True))
+```
+
+Run it:
+
+```bash
+epsdk run main.py
+# Or in development mode with hot reload
+epsdk run main.py --reload
+```
+
+Now send `/hello` or `/ping` to the bot on any connected platform — the same handlers work everywhere.
+
+For the full walkthrough (multi-turn conversations, request handlers, adapter configuration), see the [Quick Start guide](https://www.erisdev.com#docs).
+
+## The SendDSL — fluent message sending
+
+Compose the entire send flow — `@mention`, reply, retry, timeout, progress hook and bulk dispatch — as one readable chain:
+
+```python
+yunhu = sdk.adapter.get("yunhu")
+
+# Single send: @user + reply + retry + timeout + success callback
+await (yunhu.Send.To("group", "123")
+       .At("456").Reply("msg_789")
+       .Retry(3).Timeout(10)
+       .Hook(lambda r: print("Send successful!"))
+       .Text("Hello"))
+
+# Bulk send: build multiple messages, then dispatch in one chain
+results = await (yunhu.Send.To("user", "123")
+                .Build()
+                .Text("Notification 1")
+                .Image("pic.jpg")
+                .Retry(2)
+                .send_all())
+```
+
+Supported chainable methods include `Hook` (success callback), `Retry` (failure retry), `Timeout` (timeout cancellation), `OnProgress` (progress monitoring), `Defer` (delayed send) and `Build` (batch construction).
+
+> Full reference: [SendDSL documentation](https://www.erisdev.com#docs)
+
+## Supported Platforms
+
+Officially maintained adapters (community contributions welcome):
+
+- [Kook](https://github.com/shanfishapp/ErisPulse-KookAdapter) — instant messaging platform
+- [Matrix](https://github.com/ErisPulse/ErisPulse-MatrixAdapter) — decentralized communication protocol
+- [OneBot11](https://github.com/ErisPulse/ErisPulse-OneBot11Adapter) — universal OneBot v11 protocol
+- [OneBot12](https://github.com/ErisPulse/ErisPulse-OneBot12Adapter) — OneBot v12 standard protocol
+- [QQ Bot](https://github.com/ErisPulse/ErisPulse-QQBotAdapter) — official QQ bot platform
+- [Telegram](https://github.com/ErisPulse/ErisPulse-TelegramAdapter) — global instant messaging
+- [Discord](https://github.com/ErisPulse/ErisPulse-DiscordAdapter) — community communication platform
+- [Yunhu](https://github.com/ErisPulse/ErisPulse-YunhuAdapter) / [Yunhu User](https://github.com/wsu2059q/ErisPulse-YunhuUserAdapter) — enterprise IM
+- [Email](https://github.com/ErisPulse/ErisPulse-EmailAdapter) — email protocol adapter
+- [WeChat Official Account](https://github.com/ErisPulse/ErisPulse-WechatMpAdapter)
+- [Webhook](https://github.com/ErisPulse/ErisPulse-WebhookAdapter) — HTTP bridge to any system
+- [Sandbox](https://github.com/ErisPulse/ErisPulse-SandboxAdapter) — in-browser debugging, no real platform needed
+- [HuaFeng Coffee House](https://github.com/ErisPulse/ErisPulse-Ideaura/)
+
+See the [adapter guide](https://www.erisdev.com#docs) for configuration details.
+
+## Ecosystem
+
+- **Framework** — core runtime with a unified event & message model.
+- **Dashboard** — visual management for plugins, logs and configuration. ([live demo](https://dashdemo.erisdev.com/))
+- **AI Builder** — natural-language prompts → ready-to-use modules. ([try it](https://www.erisdev.com/#builder))
+- **Module Market** — plug-and-play community plugins. ([browse](https://www.erisdev.com/#market))
+- **CLI** — `epsdk` scaffolding, project init, run and reload.
+- **Docker** — multi-architecture images at `erispulse/erispulse`.
+
+## Documentation & Community
+
+- 📖 **Documentation & API reference:** [erisdev.com](https://www.erisdev.com)
+- 💬 **GitHub Discussions:** [ErisPulse/ErisPulse/discussions](https://github.com/ErisPulse/ErisPulse/discussions)
+- 📋 **Changelog:** [CHANGELOG.md](https://github.com/ErisPulse/ErisPulse/blob/main/CHANGELOG.md)
+- 🤝 **Contributing:** [CONTRIBUTING.md](https://github.com/ErisPulse/ErisPulse/blob/main/CONTRIBUTING.md)
+- 🐛 **Bug reports:** [GitHub Issues](https://github.com/ErisPulse/ErisPulse/issues)
+- 🧠 **DeepWiki:** [deepwiki.com/ErisPulse/ErisPulse](https://deepwiki.com/ErisPulse/ErisPulse)
+
+Chat with us on:
+
+- Telegram: <https://t.me/ErisPulse>
+- QQ Group: <https://qm.qq.com/q/TOwnCmypcy>
+- Yunhu Group: <https://yhfx.jwznb.com/share?key=VWJL4fTWXepa&ts=1781889199>
+
+---
+
+**Why ErisPulse?** Because platform differences should never be your bottleneck — focus on business logic, and let the framework handle the rest. Write once, deploy everywhere.

{erispulse-2.6.2.dev1 → erispulse-2.6.3.dev0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.6.2-dev.1"
+version = "2.6.3-dev.0"
 description = "Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署"
-readme = "README.md"
+readme = "README.pypi.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
 

{erispulse-2.6.2.dev1 → erispulse-2.6.3.dev0}/src/ErisPulse/CLI/cli.py

@@ -149,6 +149,43 @@ class CLI:
             )
         )
 
+    def _print_quickstart(self) -> None:
+        """
+        打印 Quick Start 面板
+
+        在 ``epsdk`` 不带任何子命令时输出，帮助新用户在 30 秒内看到
+        三步走路径（安装 / 创建项目 / 运行），降低首次使用门槛。
+        """
+        steps = [
+            (
+                i18n.t("cli.run.quickstart.step1_label"),
+                i18n.t("cli.run.quickstart.step1_cmd"),
+            ),
+            (
+                i18n.t("cli.run.quickstart.step2_label"),
+                i18n.t("cli.run.quickstart.step2_cmd"),
+            ),
+            (
+                i18n.t("cli.run.quickstart.step3_label"),
+                i18n.t("cli.run.quickstart.step3_cmd"),
+            ),
+        ]
+        lines: list[str] = []
+        for idx, (label, cmd) in enumerate(steps, start=1):
+            lines.append(f"[bold]{idx}. {label}[/]  [cmd]{cmd}[/]")
+        lines.append("")
+        lines.append(f"[dim]{i18n.t('cli.run.quickstart.docs_hint')}[/]")
+        lines.append(f"[dim]{i18n.t('cli.run.quickstart.run_help_hint')}[/]")
+
+        console.print(
+            Panel(
+                "\n".join(lines),
+                title=f"[title]{i18n.t('cli.run.quickstart.title')}[/]",
+                subtitle=i18n.t("cli.run.quickstart.subtitle"),
+                border_style="info",
+            )
+        )
+
     def _check_command_typo(self) -> None:
         """
         在 argparse 解析之前检查命令拼写
@@ -174,23 +211,24 @@ class CLI:
             return
 
         # 命令无效，给出拼写建议（前缀加成确保 ins → install 而非 list）
-        from ..runtime.hints import best_match_with_prefix
+        from .hints import best_match_with_prefix
 
         print_banner()
         suggestion = best_match_with_prefix(
             cmd, canonical_names, cutoff=0.5
         )
 
-        console.print(
-            f"[error]{i18n.t('cli.run.unknown_command', command=cmd)}[/]"
-        )
         if suggestion:
-            console.print(
-                f"[hint]{i18n.t('cli.run.did_you_mean', name=suggestion)}[/]"
+            from .console import print_suggestion
+
+            print_suggestion(
+                title=i18n.t("cli.run.unknown_command", command=cmd),
+                suggestions=[f"epsdk {suggestion} --help"],
             )
-            console.print()
-            console.print(f"  [dim]epsdk {suggestion} --help[/]")
         else:
+            console.print(
+                f"[error]{i18n.t('cli.run.unknown_command', command=cmd)}[/]"
+            )
             self.parser.print_help()
         sys.exit(1)
 
@@ -258,12 +296,13 @@ class CLI:
             self._print_version()
             return
 
-        # 没有指定命令时显示帮助
+        # 没有指定命令时显示 Quick Start + 帮助
         if not args.command:
             if unknown:
                 console.print(
                     f"[warning]{i18n.t('cli.run.unknown_args', args=' '.join(unknown))}[/]"
                 )
+            self._print_quickstart()
             self.parser.print_help()
             return
 
@@ -289,7 +328,7 @@ class CLI:
                 command.execute(args)
             else:
                 # 拼写建议：检查是否输入了与已知命令相似的名称
-                from ..runtime.hints import best_match_with_prefix
+                from .hints import best_match_with_prefix
 
                 suggestion = best_match_with_prefix(
                     args.command, self.registry.list_all(), cutoff=0.5
@@ -309,6 +348,12 @@ class CLI:
             sys.exit(1)
         except Exception as e:
             console.print(f"[error]{i18n.t('cli.run.exec_error', error=e)}[/]")
+            # 场景化友好提示：根据异常类型给出下一步建议
+            from .hints import suggest_for_exception
+
+            hint_key = suggest_for_exception(e)
+            if hint_key:
+                console.print(f"[hint]{i18n.t(hint_key)}[/]")
             if args.verbose >= 1:
                 console.print(traceback.format_exc())
             sys.exit(1)

{erispulse-2.6.2.dev1 → erispulse-2.6.3.dev0}/src/ErisPulse/CLI/cli.pyi

@@ -55,6 +55,14 @@ class CLI:
         打印版本信息
         """
         ...
+    def _print_quickstart(self) -> None:
+        """
+        打印 Quick Start 面板
+        
+        在 ``epsdk`` 不带任何子命令时输出，帮助新用户在 30 秒内看到
+        三步走路径（安装 / 创建项目 / 运行），降低首次使用门槛。
+        """
+        ...
     def _check_command_typo(self) -> None:
         """
         在 argparse 解析之前检查命令拼写

{erispulse-2.6.2.dev1 → erispulse-2.6.3.dev0}/src/ErisPulse/CLI/commands/run.py

@@ -110,10 +110,16 @@ class RunCommand(Command):
 
         if script:
             if not Path(script).exists():
+                # 列出当前目录的 .py 文件作为上下文参考
+                py_files = sorted(Path().glob("*.py"))
+                file_list = ", ".join(f.name for f in py_files[:5]) if py_files else None
+                hint_text = i18n.t("cli.run.use_init")
+                if file_list:
+                    hint_text += "  " + i18n.t("cli.run.available_scripts", files=file_list)
                 console.print(
                     f"[error]{i18n.t('cli.run.script_not_found', script=script)}[/]"
                 )
-                console.print(f"[info]{i18n.t('cli.run.use_init')}[/]")
+                console.print(f"[info]{hint_text}[/]")
                 return
             if Path(script).is_dir():
                 console.print(