手把手带你写个 ErisPulse 机器人
这篇文章,带泥从零写出一个完整业务的 ErisPulse 机器人 能跑、能聊、能收集用户信息的那种
框架的安装
前提是装好 uv 或者 Python 3.10+(二选一即可),这里默认泥都有
1# 使用 uv 创建虚拟环境(python 3.12)
2uv venv --python 3.12
3
4# 如果你没有 uv 这个工具链,并且在安装 Python 大于 3.10 的情况下,也可以直接开始
5# python -m venv .venv
6
7# 激活虚拟环境
8# windows: .venv\Scripts\activate
9source .venv/bin/activate
10
11# 安装框架
12pip install ErisPulse
创建虚拟环境后如图:

安装我这里用的 uv,直接 pip install ErisPulse 也一样:

装完了,初始化一个基础机器人目录:
1epsdk init -q -n my_bot

创建了一个叫 my_bot 的目录,结构如下:

就两个文件,config/config.toml 是配置文件,main.py 是写逻辑的地方。
安装沙箱适配器
接真实平台之前,先用 Sandbox 适配器调试,自带一个 Web 界面,不用配真实平台的 token 就能跑。
1epsdk install
运行后进入交互式界面:

选 1. 适配器,然后找 sandbox:

我这里是第 7 个,选 7 回车安装。泥那边的序号可能不一样,找到 sandbox 就行。
装完基础设施就齐了,开写。
第一个命令:ping!
打开 main.py,自动生成的代码大概长这样:
1"""
2my_bot 主程序
3
4这是 ErisPulse 自动生成的主程序文件
5您可以根据需要修改此文件
6"""
7
8import asyncio
9from ErisPulse import sdk
10
11async def main():
12 await sdk.run(keep_running=True)
13
14if __name__ == "__main__":
15 asyncio.run(main())
不用删任何东西,from ErisPulse import sdk 下面加一行导入,async def main() 上面加命令就行:
1"""
2my_bot 主程序
3
4这是 ErisPulse 自动生成的主程序文件
5您可以根据需要修改此文件
6"""
7
8import asyncio
9from ErisPulse import sdk
10from ErisPulse.Core.Event import command
11
12@command("ping")
13async def ping(event):
14 await event.reply("pong!")
15
16async def main():
17 await sdk.run(keep_running=True)
18
19if __name__ == "__main__":
20 asyncio.run(main())
sdk.run(keep_running=True) 那行是框架包好的启动逻辑,初始化、启动适配器、保持运行全包了
泥只管用装饰器写命令,底层怎么跑的不用操心
跑起来:
1epsdk run main.py

打开 Sandbox 的 Web 调试界面(默认 http://localhost:8000/sandbox),输入 /ping,机器人回泥一句 pong!。

框架搞定一切,泥只管决定收到命令后回什么。
让机器人记住事
光回 pong 没意思。改一下 ping,让它记住泥 ping 了多少次:
1@command("ping")
2async def ping(event):
3 count = sdk.storage.get("ping_count", 0)
4 count += 1
5 sdk.storage.set("ping_count", count)
6 await event.reply(f"pong!这是你第 {count} 次 ping 我了")
sdk.storage 是框架内置的键值存储,支持KV和SQL链式调用存储(SQL链式方法可以查看相关文档)

收集用户信息
前面都是小打小闹,现在来个真的——用户注册功能,机器人依次问名字、年龄、邮箱,格式不对会要求重填:
1@command("register")
2async def register(event):
3 data = await event.collect([
4 {"key": "name", "prompt": "你的名字是?"},
5 {"key": "age", "prompt": "你的年龄?",
6 "validator": lambda e: e.get_text().isdigit()},
7 {"key": "email", "prompt": "你的邮箱?",
8 "validator": lambda e: "@" in e.get_text()}
9 ])
10
11 if data:
12 await event.reply(
13 f"注册完成!\n"
14 f"姓名:{data['name']}\n"
15 f"年龄:{data['age']}\n"
16 f"邮箱:{data['email']}"
17 )
18 else:
19 await event.reply("超时了,下次再来吧!")
发 /register 试试。机器人挨个问问题,年龄输"abc"会让泥重填,邮箱没 @ 也会重来。整个过程像这样:

注意看这段代码——没有状态机,没有维护用户走到第几步的字典,没有中间件拦截消息,没有超时定时器
collect 一个方法全干完了
在别的框架手写这种表单收集,光状态管理就两百行,这里一个方法调用就解决了~
链式消息发送方法
ErisPulse 发消息是链式语法,从左往右读就是消息的组装过程:
1from ErisPulse import sdk
2
3adapter = sdk.adapter.get("sandbox")
4
5# 普通文本
6await adapter.Send.To("group", "room_123").Text("大家好")
7
8# @用户 + 回复消息
9await adapter.Send.To("group", "room_123").At("user_456").Reply("msg_789").Text("回复你的消息")
修饰方法(At、Reply)返回 self,可以一直往后链
发送方法(Text、Image)返回 asyncio.Task,可以 await 等结果,也可以不 await 让它后台发:
1# 不等,后台发
2adapter.Send.To("user", "123").Text("发了不管了")
3
4# 等结果
5result = await adapter.Send.To("user", "123").Text("等等结果")
6
7# 存起来,过会儿再等
8task = adapter.Send.To("user", "123").Text("存起来")
9# 干点别的……
10result = await task
对比一下别的框架怎么发的:
1await bot.send(target_type="group", target_id="room_123", message=[
2 {"type": "at", "data": {"user_id": "user_456"}},
3 {"type": "reply", "data": {"message_id": "msg_789"}},
4 {"type": "text", "data": {"text": "回复你的消息"}}
5])
现在的完整 main.py
到这儿,main.py 长这样:
1"""
2my_bot 主程序
3
4这是 ErisPulse 自动生成的主程序文件
5您可以根据需要修改此文件
6"""
7
8import asyncio
9from ErisPulse import sdk
10from ErisPulse.Core.Event import command
11
12@command("ping")
13async def ping(event):
14 count = sdk.storage.get("ping_count", 0)
15 count += 1
16 sdk.storage.set("ping_count", count)
17 await event.reply(f"pong!这是你第 {count} 次 ping 我了")
18
19@command("register")
20async def register(event):
21 data = await event.collect([
22 {"key": "name", "prompt": "你的名字是?"},
23 {"key": "age", "prompt": "你的年龄?",
24 "validator": lambda e: e.get_text().isdigit()},
25 {"key": "email", "prompt": "你的邮箱?",
26 "validator": lambda e: "@" in e.get_text()}
27 ])
28 if data:
29 await event.reply(
30 f"注册完成!\n"
31 f"姓名:{data['name']}\n"
32 f"年龄:{data['age']}\n"
33 f"邮箱:{data['email']}"
34 )
35 else:
36 await event.reply("超时了,下次再来吧!")
37
38async def main():
39 await sdk.run(keep_running=True)
40
41if __name__ == "__main__":
42 asyncio.run(main())
三十多行,一个带计数器的 ping、一个完整的用户注册系统,都能直接跑。
1epsdk run main.py
换个平台?改个配置就行
上面一直在用 Sandbox 调试,准备好接真实平台了就:
1# Telegram
2epsdk install Telegram
3
4# 云湖
5epsdk install Yunhu
6
7# OneBot11 (QQ)
8epsdk install OneBot11
然后去 config/config.toml 里填对应平台的 token:
1[Telegram_Adapter]
2token = "你的_bot_token"

重启,main.py 一行不改,命令照常工作。
这背后是 ErisPulse 把每个平台的事件都转成了 OneBot12 统一标准 泥的代码只跟标准打交道,适配器负责翻译各平台的方言 换平台就是换配置,不是换代码
装个 Dashboard,告别黑框框
1epsdk install Dashboard
访问 http://localhost:8000/Dashboard,能看到:
- 机器人在线状态
- 实时日志和事件流
- 已安装的模块和适配器
- 在线改配置
- 模块商店,点一下就能装新模块

不用再 SSH 进服务器翻日志了。
走完这套流程,ErisPulse 的几个特点泥应该感受到了:
collect、confirm、choose让写对话像写脚本,不用管状态机- 链式 Send 语法从左往右就是消息结构,不用拼 JSON
- 换平台只换配置不换代码
- Dashboard 让管理变得可视
动手试试⑧:
1pip install ErisPulse
2epsdk init -n my_bot
评论