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

ErisPulse ドキュメント

ErisPulse はイベント駆動型のモジュール式非同期ボットフレームワークです。ビジネスコードは一度だけ書けば、アダプター経由で QQ、Telegram、Kook、云湖 など複数のプラットフォームにデプロイでき、プラグインシステム、ホットリロード、完全な開発者ツールチェーンが最初から使える状態で提供されます。

初めてご利用ですか? 5分クイックスタート を直接ご覧ください —— インストールから最初のボットの実行まで、一気通貫で進められます。


自分に合ったパスを選ぶ

目標に応じて、対応する学習パスを選択してください。各パス内では、易しいものから難しいものへと順に並んでいます。

Important

すべてのドキュメントを読み切る必要はありません。 大多数の開発者は、L1 コア5編 (約1〜2時間)を順番に読むだけで、機能の90%を独力で開発できるようになります。それ以外の ドキュメントはすべて、特定のシナリオ向けの必要に応じた参照資料です。該当するニーズが 生じた時点で参照すればよく、各記事の冒頭には「いつこの記事を読むべきか」が明記されています。

L1 コア5編:モジュール開発入門 → 基本概念 → Event ラッパークラス → 設定ファイルの説明 → 例外の捕捉

アダプター作者にはさらに以下が必要です:アダプター開発入門 → イベントコンバーター → SendDSL 詳解

一、ボットを使いたい

ボットを動かし、モジュールをインストールし、設定を行います。

進行状況 ドキュメント 説明
① スタート 5分クイックスタート インストール、初期化、実行 —— 唯一のスタート地点
App 直インストール ErisPulse-App クライアント 公式全プラットフォームクライアント:スマホ / PC の GUI で直接実行・管理、ターミナル不要
② 深掘り 最初のボットを作成する 最初のコマンドハンドラーを書く
③ 概念 基本概念 アダプター/モジュール/イベントの設計を理解する
④ 実践 よくあるタスクの例 ストレージ、定期タスク、権限制御
参照 設定ファイルの説明 · CLI コマンド · デプロイガイド 必要に応じて参照
参照 プラットフォーム特性ガイド 各プラットフォーム(云湖/QQ/Telegram…)の違い
選定 選定ガイド NoneBot2 / AstrBot / LangBot との比較と移行

二、モジュール / アダプターを開発したい

ErisPulse 用の配布可能な拡張機能を作成します。

タイプ 入門 応用
モジュール開発(推奨) モジュール開発入門 コア概念 · Event ラッパークラス · ベストプラクティス
アダプター開発 アダプター開発入門 コア概念 · SendDSL 詳解 · イベントコンバーター · ベストプラクティス
技術標準 標準仕様の概観 アダプター開発が従うべき セッションタイプ · イベント変換 · 送信メソッド · API レスポンス · リクエスト操作 の各仕様
テストとトラブルシューティング モジュールテスト(ErisPulse-Testing) ディスパッチ決定チェーンによる「コマンドがなぜ発火しなかったのか」の調査
公開 公開とモジュールストア 作品を PyPI とモジュールストアに公開する

三、仕組みを深く理解したい

フレームワーク内部がどのように動作するかを理解します。まずアーキテクチャと API リファレンスを確認し、その後、下記の対応表に従って各トピックへ進んでください。

アーキテクチャと API リファレンス

ドキュメント 説明
アーキテクチャ概観 可視化図表:コアアーキテクチャ、初期化フロー、イベント処理、ライフサイクル、モジュール読み込み戦略(activate_on によるイベント駆動の遅延アクティベーションを含む)、ローカルプラグインフォルダとモジュールホットリロードアーキテクチャ(すべてのモジュールソースに対応)
イベントシステム 5大イベントカテゴリの完全な API
アダプターシステム アダプターの登録、起動・停止、API 呼び出し
コアモジュール Storage / Config / Logger / Router などの基本機能

L2 必読(本番レベルのモジュールを書くなら避けて通れない)

ドキュメント 説明
スコープ(scope) 3次元スコープ制御:モジュールの可用性 / イベントの受け入れ可否 / 送信アクションの制限(メソッドレベルのきめ細かいルール、バインド継承の merge を含む)
所有権(owner)システム リソースの所有と自動回収:owner コンテキスト、所有リソースの全体像、アンロード時のクリーンアップシーケンス、設計上の境界とモジュール作者向けガイド
ライフサイクル管理 ライフサイクルイベントシステム:モジュール / アダプターの読み込み、アンロード、リロード、無効化の際にそれぞれ何をすべきか
インタラクションセッションシステム wait_reply 完全解説、セッションタイマー(remind/escalate)、複数同時待ち(select)、セッション相互排他リース、受信箱、メッセージトランザクション、トレーシング

シナリオ別グループ(必要に応じて参照)

グループ ドキュメント 最初の記事を理解しないと陥る落とし穴
起動 起動フローと手動制御 · 遅延読み込み 起動チェーン(Finder / Loader / Manager / Router)を理解していないと、モジュールの読み込み失敗時にログを眺めることしかできません
通信接続 モジュール間通信 · 接続プールとブロードキャスト · ルーティングシステム サービス契約(meta.services)のホワイトリストを理解していないと、モジュール間の module.call が ServiceNotProvidedError で拒否されても理由が分かりません
データストレージ ストレージバックエンド · SQL ビルド · ネットワーククライアント 接続失敗時のクールダウン期間のセマンティクスを理解していないと、データベースに不調が起きたときに「フレームワークが壊れた」と誤認します(実際にはストレージ操作がフェイルファストし、クールダウン後に自動再接続するだけです)
メッセージ対話 Conversation 多ターン対話 · セッション受信箱 · MessageBuilder · 国際化 セッション相互排他リースを理解していないと、2つのモジュールが同じユーザーの返信を同時に待つと互いに追い出されてしまいます
パフォーマンス計測 パフォーマンスベンチマークとチューニング デプロイ前にベンチマーク数値を確認しないと、キャパシティプランニングが当てずっぽうになります。アップグレード後に回帰比較をしないと、パフォーマンス劣化に気付けません
シャドウとグレースケール シャドウモジュールとグレースケール昇格 5つの分離ゲートを理解しないまま昇格を急ぐと、シャドウの送信メッセージが実際のユーザーに漏れ出てしまいます

概念関係の一覧表

どのサブシステムが何を管轄しているのか分からないときは、この表で該当する行を探してください:

サブシステム どのような問題に答えるか 一言まとめ
通信(module-communication) モジュール同士はどう呼び合うか、イベントをどう宛先指定で送るか? モジュール間は module.call を使う。相手が meta.services を宣言している場合、ホワイトリスト内のメソッドしか呼べない
権限(scope) 誰がこのモジュールを使えるか、誰がイベントを発火できるか、どのアクションを実行できるか? 3つのゲート —— モジュールバインド、ID 受け入れ、送信制限。すべてユーザー設定が決定する
所有(ownership) モジュールのアンロード後、そのモジュールが開いた接続、タイマー、サブスクリプションはどこへ? 登録した者が所有し、アンロード時に回収。宙ぶらりんのリソースは残さない
遅延読み込みとスリープ(lazy-loading) モジュールはいつ実際に読み込まれ、アイドル後はどこへ? activate_on は使われるときに目覚め、dormant_after でアイドル時にスリープへ
インタラクション(interaction) ユーザーの次の返信をどう待つか、多ターンの収集はどう書くか? wait_reply は1件を待ち、.got() チェーンは複数ターンを収集。リースが衝突を防止する
シャドウとグレースケール(shadow) 新バージョンのモジュールを本番に影響なく試験運用するには? シャドウはコピーを受け取り、送信は記録のみ。promote は人間の確認後に初めて正式昇格する
ストレージ(storage-backends) データはどこに保存され、バックエンドはどう切り替えるか? 同一のストレージ API で、sqlite / mysql / postgres を設定で切り替え

四、エコシステムと公式クライアント

公式クライアント + 必要に応じてインストールし、インストール後すぐに使えるエコシステムモジュール(いずれもフレームワークに内蔵された機能ではありません)。

ドキュメント 説明
エコシステム概観 エコシステムモジュールのインストール方法、これらが内蔵機能ではない理由
ErisPulse-QvQChat 汎用エージェントモジュール:ツールループ / MCP / 長期記憶 / ナレッジベース。サービスを宣言したモジュールは自動的に AI ツールになります
ErisPulse-ApiMCP ボットを逆に MCP ツールとして公開し、Claude などの AI クライアントに直接操作させる
ErisPulse-App 公式全プラットフォームクライアント(Android / Windows / Linux / macOS):ネイティブ UI で複数インスタンスを管理、スマホで直接実行、デスクトップトレイに常駐
ErisPulse-Dashboard Web 管理パネル + ペイン登録 API(モジュールはサイドバーにカスタムページを登録できます)
ErisPulse-Cron 定期タスクスケジューリングモジュール:単発 / 間隔 / Cron 式、コールバックへの引数渡し、SQLite 永続化、他のモジュールは定期コールバックを委託可能
ErisPulse-Takumi 画像レンダリング(HTML / ノードツリー / SVG / アニメーション、中国語・英語フォント内蔵)

五、ErisPulse に貢献したい

フレームワークをより良いものに

ドキュメント 説明
ErisPulse への貢献 貢献方法の概観:ドキュメント / i18n / Bug / モジュール / アダプター
初めての貢献 fork から PR 提出まで

高度な機能のバージョン早見表

バージョン互換性の判断をする場合や、古いプロジェクトを引き継いだ際に「この機能はどのバージョンで導入されたのか」を知りたい場合は、この表で該当項目を探してください(リポジトリルートの CHANGELOG.md の各バージョンエントリが正とします)。

バージョン 導入された機能
2.7 本番運用基盤:OneBot12 標準化基底クラス(ApiDSL / BaseConverter)、設定ホットアップデートの体系化、グレースフルシャットダウンと SIGTERM/SIGHUP シグナル処理、環境変数による設定の上書き、ライフサイクルコールバックフック、Web スタックの遅延読み込み。2.7.1 で設定書き込みの信頼性と GC 世代管理を補強
2.8 権限と通信のスケルトン:3次元スコープ体系(scope)、インタラクションセッションインフラ(リース / チェックポイント / メッセージトランザクション / セッション受信箱 transcript)、モジュール間 RPC のプロトコル化(module.call / meta.services サービス契約 / 宛先指定イベント emit(to=))、マルチバックエンド非同期ストレージ(sqlite / mysql / postgres、接続失敗時にフレームワークをブロックしない)、所有権クリーンアップ、設定コメントの保持。2.8.x の後続バージョンは CLI スキャフォールド、サブコマンドなどの磨き込み
2.9 「モジュール開発体験」メインライン(EPRFC-2026-001):宣言型コマンドパラメータ(args= / options=)とコマンドガバナンス(cooldown= / rate_limit=)、統一依存性注入(Depends)、ミドルウェアによるイベント拒否権、内蔵 ORM(自動マイグレーション + リレーションマッピング)、シャドウモジュールのグレースケール昇格、ディスパッチ決定チェーンの追跡とトラブルシューティング診断、Python 3.14 の正式サポート
2.10 接続のファーストクラスリソース化(connections レジストリ:ブロードキャスト / ビジネスグループ / モジュール間受け渡しでの再利用 / アンロード時の自動回収)、ルートインポート契約(常用 API はすべて from ErisPulse import で可能)、所有権体系の補完、受信箱保持ポリシーのランタイムオーバーライド。2.10.2 でアダプターのローカルプラグインディレクトリ(plugins/)+ epsdk create pack + tomlclass による損失なしの設定書き込み
2.11(dev) 「コードを変更 → 結果を確認」の開発ループ:ホットリロードのデフォルト全量セマンティクス(構文プリチェック + コード同一性の照合 + 依存モジュールのカスケード再エクスポート)、遅延読み込みスリープ(dormant_after)、アダプターのコードレベルホットリロード(sdk.adapter.reload)、.got() コマンドフロー糖衣構文、epsdk stop / restart によるランタイム制御
2.12(dev) ライフサイクルガバナンスと運用性:ネストされたライフサイクル(ownership.nest())、きめ細かなホットリロード(単一モジュール/単一アダプターの判定、フレームワークソースの変更はプロセス再起動へ)、バックグラウンドタスクの送信待ちキュー、イベントディスパッチチェーンのアカウント自動バインド(send_context / api_context / request_context が同一基準、マルチアカウントモジュールは変更ゼロ)、アカウント横断の重複受付関連付け(framework.cross_account_policy)、シャドウモジュールの whl 取り込みと永続化昇格の閉ループ、コンテナ内での epsdk restart によるプロセス内ソフト再起動、SendDSL.Location()

開発方式

ErisPulse は2つの開発方式をサポートしています:

  • モジュール開発(推奨):独立したモジュールパッケージを作成し、パッケージマネージャーでインストールします。配布と管理が容易になります。
  • 組み込み開発:プロジェクト内に直接ハンドラーを記述する方式で、迅速なプロトタイピングに適しています。詳しくはクイックスタートをご覧ください。

その他

ヘルプの入手

関連リンク