ErisPulse 2.5.0.dev0

ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。

English | 简体中文 | 繁體中文 | 日本語 | Русский ErisPulse 事件驱动的多平台机器人开发框架 基于 OneBot12 标准接口，一次编写，多平台部署。灵活的插件系统、热重载支持和完整的开发者工具链，适用于从简单聊天机器人到复杂自动化系统的各种场景。 支持 Vibe Coding 工作流，让 AI 直接生成可用模块 — 查看

---

核心特性

⚡ 事件驱动架构 基于 OneBot12 标准的清晰事件模型，让消息处理逻辑更加直观和高效	🌐 跨平台兼容 插件模块编写一次即可在所有平台使用，无需为不同平台重复开发
🧩 模块化设计 灵活的插件系统，易于扩展和集成，支持热插拔模块管理	🔄 热重载支持 开发时无需重启即可重新加载代码，大幅提升开发迭代效率

---

快速开始

一键安装脚本（推荐）

安装脚本会自动检测您的环境（Docker、Python、uv），引导选择最适合的安装方式，支持多语言（中文/English/日本語/Русский/繁體中文）。

Windows (PowerShell):

irm https://get.erisdev.com/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1

macOS / Linux:

curl -fsSL https://get.erisdev.com/install.sh -o install.sh && chmod +x install.sh && ./install.sh

Docker 安装演示

pip 安装演示

使用 Docker (推荐)

docker pull erispulse/erispulse:latest

Docker Hub不可用？

如果 Docker Hub 无法访问，可以使用 GitHub Container Registry：

docker pull ghcr.io/erispulse/erispulse:latest

使用 ghcr.io 镜像时，需要修改 docker-compose.yml 中的 image：

image: ghcr.io/erispulse/erispulse:latest

快速启动

# 下载 docker-compose.yml
curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml

# 设置 Dashboard 登录令牌并启动
ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d

镜像内置 ErisPulse 框架和 Dashboard 管理面板，支持 linux/amd64 和 linux/arm64 架构。

启动后访问 http://<host>:<port>/Dashboard，使用设置的令牌作为密码登录 Dashboard 管理面板。

使用预发布版本 (Dev)

设置 ERISPULSE_CHANNEL=dev 即可使用预发布版本：

# 方式一：使用环境变量（推荐）
ERISPULSE_CHANNEL=dev ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d

# 方式二：构建 dev 镜像
ERISPULSE_BUILD_TARGET=dev docker compose up -d --build

如需启动时自动更新到最新版本（无论 stable 还是 dev），显式设置 ERISPULSE_UPDATE_ON_START=true：

ERISPULSE_CHANNEL=dev ERISPULSE_UPDATE_ON_START=true docker compose up -d

也可以拉取预构建的 dev 镜像：

docker pull erispulse/erispulse:dev

Docker 环境变量

变量	默认值	说明
ERISPULSE_CHANNEL	stable	版本通道：stable（稳定版）或 dev（预发布版）
ERISPULSE_UPDATE_ON_START	false	容器启动时是否自动更新到最新版本（需显式启用）
ERISPULSE_DASHBOARD_TOKEN	空	Dashboard 登录令牌
ERISPULSE_PORT	8000	Dashboard 端口映射
TZ	Asia/Shanghai	容器时区

启用 ERISPULSE_UPDATE_ON_START=true 可确保即使镜像较旧，容器也能在启动时自动获取最新版本。

1Panel 应用商店

通过 1Panel 应用商店一键安装 ErisPulse，详见 ErisPulse-1Panel。

bash <(curl -sL https://get-1panel.erisdev.com/install.sh)

使用 pip 安装

pip install ErisPulse

也可以使用上方的一键安装脚本，自动检测环境并引导配置。

运行效果

仪表盘：

💡 在线体验演示仪表盘：DashDemo

同一端代码，多个平台响应：

Kook

QQ

云湖

初始化项目

# 交互式初始化
epsdk init

# 快速初始化（指定项目名称）
epsdk init -q -n my_bot

创建第一个机器人

创建 main.py 文件：

命令处理器 from ErisPulse import sdk from ErisPulse.Core.Event import command @command("hello", help="发送问候消息") async def hello_handler(event): user_name = event.get_user_nickname() or "朋友" await event.reply(f"你好，{user_name}！") @command("ping", help="测试机器人是否在线") async def ping_handler(event): await event.reply("Pong！机器人运行正常。") if __name__ == "__main__": import asyncio asyncio.run(sdk.run(keep_running=True))

效果说明 发送 /hello 机器人回复：你好，{用户名}！ 发送 /ping 机器人回复：Pong！机器人运行正常。 运行方式 epsdk run main.py # 或开发模式 epsdk run main.py --reload

更多详细说明请参阅：

• 快速开始指南
• 入门指南

多轮对话示例

ErisPulse 内置了强大的多轮对话引擎，轻松实现引导式操作、信息收集等交互场景：

from ErisPulse.Core.Event import command, request

@command("register")
async def register_handler(event):
    conv = event.conversation(timeout=60)
    
    await conv.say("欢迎注册！")
    
    # 多步骤收集用户信息，自动验证
    data = await conv.collect([
        {"key": "name", "prompt": "请输入姓名"},
        {"key": "age", "prompt": "请输入年龄",
         "validator": lambda e: e.get_text().strip().isdigit(),
         "retry_prompt": "年龄必须是数字，请重新输入"},
    ])
    
    if data and await conv.confirm(f"确认注册？姓名: {data['name']}, 年龄: {data['age']}"):
        # 通过 SendDSL 主动推送通知
        await sdk.adapter.get(event.get_platform()).Send.To(
            "user", event.get_user_id()
        ).Text(f"注册成功！欢迎 {data['name']}")
        # 或 await event.reply("注册成功！")

# 自动处理好友请求
@request.on_friend_request()
async def handle_friend_request(event):
    user_name = event.get_user_nickname() or event.get_user_id()
    
    # 同意请求
    result = await event.approve()
    if result.get("status") == "ok":
        await event.reply(f"已自动通过好友请求，欢迎 {user_name}")

查看更多 Conversation API（分支跳转 / 选择 / 持久化）

@command("quiz")
async def quiz_handler(event):
    conv = event.conversation(timeout=30)
    
    # 选项式问答
    answer = await conv.choose("Python 的创造者是谁？", [
        "Guido van Rossum",
        "James Gosling", 
        "Dennis Ritchie",
    ])
    
    if answer == 0:
        await conv.say("正确！")
    elif answer is None:
        await conv.say("超时了，下次再来吧！")
    else:
        await conv.say("错误了，正确答案是 Guido van Rossum")

@command("menu")
async def menu_handler(event):
    conv = event.conversation(timeout=60)
    
    # 分支跳转，构建复杂交互流程
    @conv.branch("main")
    async def main_menu():
        await conv.say("=== 主菜单 ===\n1. 个人信息\n2. 设置\n3. 退出")
        resp = await conv.wait()
        if resp and resp.get_text().strip() == "1":
            await conv.goto("profile")
    
    @conv.branch("profile")
    async def profile():
        await conv.say("姓名: Alice\n0. 返回")
        resp = await conv.wait()
        if resp and resp.get_text().strip() == "0":
            await conv.goto("main")
    
    await conv.start()

详见 Conversation 多轮对话

---

支持的适配器

欢迎您贡献适配器！

适配器	说明
Kook	Kook（开黑啦）即时通讯平台
Matrix	Matrix 去中心化通讯协议
OneBot11	OneBot v11 通用机器人协议
OneBot12	OneBot v12 标准协议
QQ	QQ 官方机器人平台
沙箱	网页端调试，无需接入真实平台
Telegram	全球性即时通讯平台
邮件	邮件协议收发适配器
云湖	企业级即时通讯平台（机器人接入）
云湖用户	基于云湖用户协议的接入适配器
花枫咖啡馆	Allons! (・ω・) /

查看 适配器详情介绍

---

应用场景

多平台机器人	聊天助手	自动化工具	消息转发
在多个平台部署 相同功能的机器人	接入 AI 聊天模块 实现娱乐和交互	消息通知、任务管理 数据收集	跨平台消息 同步和转发

---

贡献指南

ErisPulse 项目的健全性还需要您的一份力！我们欢迎各种形式的贡献：

1. 报告问题 — 在 GitHub Issues 提交 bug 报告
2. 功能请求 — 通过 社区讨论 提出新想法
3. 代码贡献 — 提交 PR 前请阅读 代码风格 及 贡献指南
4. 文档改进 — 帮助完善文档和示例代码

加入社区讨论

---

Star History

---

致谢

本项目部分代码基于 sdkFrame · 核心适配器标准化层基于 OneBot12 规范 · 感谢所有为开源社区做出贡献的开发者和作者