ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

快速入門

這是你的第一步。 在 5 分鐘內從零開始運行一個 ErisPulse 机器人——先看效果,再逐步深入每一步。

60 秒效果:先讓機器人回你一句話

1. 安裝(Python >= 3.10):

pip install ErisPulse

2. 初始化項目。向導會讓你設定項目名、選擇要接入的平台適配器並完成配置,然後生成 main.py 和 config/config.toml:

epsdk init

3. 打開 main.py,替換為這 9 行程式碼:

from ErisPulse import sdk
from ErisPulse.Core.Event import command

@command("ping", help="測試機器人是否在線")
async def ping_handler(event):
    await event.reply("Pong!機器人運行正常。")

if __name__ == "__main__":
    import asyncio
    asyncio.run(sdk.run(keep_running=True))

4. 運行:

epsdk run main.py

終端會輸出框架啟動日誌和適配器的連接資訊。這時在你接入的平台裡給機器人發 /ping,它會回覆:

Pong!機器人運行正常。

看到這條回覆,說明框架、適配器、事件處理這條鏈路已經打通。沒跑通?直接翻到文末遇到問題;跑通了,往下看每一步還有哪些選擇。

安裝 ErisPulse:三種方式

上面使用的是最直接的 pip。根據您的環境選擇:

使用 pip 安裝

確保您的 Python 版本 >= 3.10,然後使用 pip 安裝:

pip install ErisPulse

如果您已安裝 uv,也可以使用 uv pip install ErisPulse,安裝速度更快。

如果您只想將 epsdk 命令行工具安裝到全域、不污染項目環境,推薦使用 uv tool install:

uv tool install ErisPulse

安裝後 epsdk 全域可用:在項目目錄內運行時會自動感知項目 .venv(epsdk install 裝進項目環境、epsdk run 用項目環境運行),框架本體由工具環境提供。詳見安裝參考。

一鍵安裝腳本(新環境推薦)

安裝腳本會自動檢測您的環境(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 安裝(檢測到 Docker 時推薦):選擇鏡像源(Docker Hub / GHCR)、版本通道(穩定版 / 預發布版)、Dashboard 管理面板配置、端口設定
  • 全域 CLI 安裝(uv tool,推薦):將 epsdk 安裝為全域命令,無需虛擬環境,uv 自動管理 Python(系統版本過低亦可);項目目錄內運行時自動感知項目 .venv
  • 傳統安裝:自動建立虛擬環境、選擇 ErisPulse 版本、可選安裝 Dashboard 管理面板模組

使用 Docker

Docker 鏡像已內建 ErisPulse 框架和 Dashboard 管理面板,支援 linux/amd64 和 linux/arm64 架構。

# 下載 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
Docker Hub 不可用?

使用 GitHub Container Registry 鏡像,修改 docker-compose.yml 中的 image:

image: ghcr.io/erispulse/erispulse:latest

啟動後訪問 http://<host>:8000/Dashboard,使用設定的令牌登入。

初始化項目

交互式初始化(推薦)

epsdk init

這將啟動一個交互式向導,引導您完成:

  • 項目名稱設置
  • 日誌級別配置
  • 伺服器配置(主機和端口)
  • 適配器選擇和配置
  • 項目結構創建

快速初始化

# 指定項目名稱的快速模式
epsdk init -q -n my_bot

# 或者只指定項目名稱
epsdk init -n my_bot

手動創建項目

如果更喜歡手動創建項目:

mkdir my_bot && cd my_bot
epsdk init

安裝模塊

通過 CLI 安裝

epsdk install Yunhu AIChat

查看可用模塊

epsdk list-remote

交互式安裝

不指定包名時進入交互式安裝界面:

epsdk install

運行項目

# 普通運行
epsdk run main.py

# 熱重載模式(開發時推薦)
epsdk run main.py --reload

啟用 IDE 補全(可選)

ErisPulse 動態發現模塊/適配器,IDE 默认無法補全平台特有方法。
運行以下命令生成類型存根:

epsdk types

生成後用導入的類型作為變量標註即可獲得精確補全(詳見 IDE 補全指南):

from _ep_types import Yunhu
from ErisPulse import sdk

adapter: Yunhu = sdk.adapter.get("yunhu")
await adapter.Send.To("group", "123").Board(...)  # 補全平台特有方法

項目結構

初始化後的項目結構:

my_bot/
├── config/
│   └── config.toml          # 配置文件
└── main.py                  # 入口文件

配置文件

基本的 config.toml 配置:

[ErisPulse.server]
host = "0.0.0.0"
port = 8000

[ErisPulse.logger]
level = "INFO"

[Yunhu_Adapter]
# 適配器配置

下一步

機器人跑起來後,根據你的目標選擇下一步:

想做群組機器人(處理訊息、群組管理、通知)

想寫自己的模組 / 適配器

想讓機器人長期運行

遇到問題