ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

最初のロボットを作成する

Tip

この記事を読むタイミング:ロボットが動作している状態で、最初の /hello コマンドハンドラを実装し、sdk.run とコマンドデコレータがそれぞれ何をしているのかを理解したい場合。まだ ErisPulse をインストールしておらず、プロジェクトを初期化していない場合は、まず 5 分間クイックスタート の「インストール」「プロジェクトの初期化」「プロジェクトの実行」の 3 ステップを完了してください。必要ない場合はスキップしてください。

クイックスタートを実行したのは第一歩です。この記事では、最初のコマンドハンドラを実装し、フレームワーク内で各行のコードが何を行っているのかを解説します。

最初のステップ:最初のコマンドを記述する

main.py を開き、シンプルなコマンドハンドラを記述します。

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

@command("hello", help="挨拶メッセージを送信します")
async def hello_handler(event):
    """hello コマンドを処理します"""
    user_name = event.get_user_nickname() or "友達"
    await event.reply(f"こんにちは、{user_name}!私は ErisPulse ロボットです。")

@command("ping", help="ロボットがオンラインかどうかをテストします")
async def ping_handler(event):
    """ping コマンドを処理します"""
    await event.reply("Pong!ロボットは正常に動作しています。")

async def main():
    """メインエントリーポイント関数"""
    print("ErisPulse を起動しています...")
    
    # keep_running=True(デフォルト):フレームワークはブロックして実行を維持し、終了信号(例:Ctrl+C)が受信されるまで待ちます
    await sdk.run(keep_running=True)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

keep_running パラメータ

sdk.run(keep_running) は、フレームワークがブロックして実行を維持するかどうかを制御します。

  • keep_running=True(デフォルト):run() はブロックし続け、終了信号(例:Ctrl+C)が受信されるまで待ちます。これは純粋な bot アプリケーションに適しています。
  • keep_running=False:run() は初期化後に即座に返ります。フレームワークはアンロードされません——起動されたアダプタ/モジュールはバックグラウンドタスクとしてメッセージイベントの処理を続けます。その後、独自のロジックを実行し、イベントループが終了するまでフレームワークは閉じられません。例:
async def main():
    await sdk.run(keep_running=False)   # 初期化後に即座に返ります
    # フレームワークはバックグラウンドで実行中です。ここでは他の処理を続行できます
    while True:
        await asyncio.sleep(3600)
        print("1時間ごとにチェックします")

run() の2つのモードに加えて、init()/uninit() を使用したライフサイクルの手動制御、個別のアダプタ/ルーティングの起動/停止など、より細かい制御方法もあります。詳細は 起動プロセスと手動制御 を参照してください。

第二ステップ:ロボットの実行

# 通常実行
epsdk run main.py

# 開発モード(ホットリロードをサポート)
epsdk run main.py --reload

第三段階:ロボットのテスト

チャットプラットフォームで次のコマンドを送信します:

/hello

これで、ロボットからの返信が届くはずです。

コード説明

コマンドデコレータ

@command("hello", help="挨拶メッセージを送信")
  • hello:コマンド名。ユーザーは /hello で呼び出します。
  • help:コマンドのヘルプ説明。/help コマンドで表示されます。

イベントパラメータ

async def hello_handler(event):

event パラメータは Event オブジェクトであり、以下を含みます:

  • メッセージ内容:event.get_text()
  • 送信者情報:event.get_user_id()、event.get_user_nickname()
  • プラットフォーム情報:event.get_platform()
  • グループ情報:event.get_group_id()
  • 元のデータ:event.get_raw()

完全な Event オブジェクトのメソッドについては、Event 包装クラスの詳細 を参照してください。

レスポンスの送信

await event.reply("レスポンスの内容")

event.reply() は、送信者にメッセージを送信するための便利なメソッドです。

拡張機能:追加の機能を追加

ErisPulse は、豊富なイベント処理とデータ処理機能を提供します:

よくある質問

コマンドが反応しない?

  1. アダプタが正しく設定されているか確認し、config/config.toml 内のアダプタの status が true であることを確認します。
  2. ターミナルのログ出力を確認し、エラー情報(特に ERROR レベルのログ)がないか確認します。
  3. コマンドのプレフィックスが正しいか確認します(デフォルトは / です)。設定ファイルの [ErisPulse.event.command] 部分で確認できます。
  4. コマンド名のスペルが正しいか、大文字小文字の区別が正しく設定されているか確認します。

コマンドのプレフィックスを変更するには?

config.toml に以下を追加します:

[ErisPulse.event.command]
prefix = "!"
case_sensitive = false

複数のプラットフォームをサポートするには?

ErisPulse は OneBot12 標準を用いて、異なるプラットフォームのイベント形式を統一しています。@command および @message で登録されたハンドラは、すべてのプラットフォームからのイベントを自動的に受け取ります。イベントの元プラットフォームを区別するには、event.get_platform() を使用します:

@command("hello")
async def hello_handler(event):
    platform = event.get_platform()
    
    if platform == "yunhu":
        await event.reply("你好!来自云湖")
    elif platform == "telegram":
        await event.reply("Hello! From Telegram")
    else:
        await event.reply("你好!")

詳細な多プラットフォーム対応のテクニックについては、よくあるタスクの例 を参照してください。

次のステップ

  • 学習の流れに従って進む:基本概念を読んで、コマンドプロセッサの背後でフレームワークが何をしているかを理解する
  • より多くのメッセージタイプに対応したい:イベント処理の入門、メッセージ / 通知 / 要求 / メタイベントのハンドラの書き方
  • 実用的な機能を追加したい:一般的なタスクの例、永続化、定時タスク、権限制御の既製コード