ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

ErisPulse Documentation

ErisPulse is an event-driven, modular asynchronous bot framework — write your business code once, then deploy to QQ, Telegram, Kook, Yunhu, and many other platforms via adapters. The plugin system, hot reloading, and a complete developer toolchain work out of the box.

First time here? Head straight to the 5-Minute Quick Start — from installation to running your first bot, all in one go.


Choose Your Path

Depending on your goal, choose the corresponding learning path. Within each path, content is ordered from basic to advanced.

Important

You do not need to read all the documentation. The vast majority of developers can independently develop 90% of features just by reading the five L1 core articles in order (about 1–2 hours); all remaining documentation is on-demand reference material for specific scenarios—consult it only when you encounter the corresponding need. Each article states at its beginning "when you need to read this article".

Five L1 core articles: Module Development Getting Started → Basic Concepts → Event Wrapper Classes → Configuration File Reference → Exception Handling

Adapter authors additionally need: Adapter Development Getting Started → Event Converters → SendDSL in Detail

1. I Want to Use a Bot

Get the bot running, install modules, and make configurations.

Progress Document Description
① Get Started 5-Minute Quick Start Installation, initialization, running — the single entry point
App Direct Install ErisPulse-App Client Official all-platform client: run and manage directly via graphical interface on mobile / desktop, no terminal needed
② Go Deeper Create Your First Bot Write your first command handler
③ Concepts Basic Concepts Understand the design of adapters/modules/events
④ Practice Common Task Examples Storage, scheduled tasks, permission control
Reference Configuration File Reference · CLI Commands · Deployment Guide Consult as needed
Reference Platform Features Guide Differences across platforms (Yunhu/QQ/Telegram…)
Selection Selection Guide Comparison with and migration from NoneBot2 / AstrBot / LangBot

2. I Want to Develop Modules / Adapters

Write distributable extensions for ErisPulse.

Type Getting Started Advanced
Module Development (recommended) Module Development Getting Started Core Concepts · Event Wrapper Classes · Best Practices
Adapter Development Adapter Development Getting Started Core Concepts · SendDSL in Detail · Event Converters · Best Practices
Technical Standards Standards Overview Standards that adapter development must follow: Session Types · Event Conversion · Send Methods · API Responses · Request Actions
Testing & Troubleshooting Module Testing (ErisPulse-Testing) Trace the dispatch decision chain to find out "why a command didn't trigger"
Publishing Publishing & Module Store Publish your work to PyPI and the Module Store

3. I Want to Deeply Understand the Internals

Understand how the framework works internally. Start with the architecture and API reference, then dive into specific topics using the tables below.

Architecture & API Reference

Document Description
Architecture Overview Visual diagrams: core architecture, initialization flow, event handling, lifecycle, module loading strategy (including activate_on event-driven lazy activation), local plugin folders, and module hot-reload architecture (supports all module sources)
Event System Complete API for the five major event categories
Adapter System Adapter registration, start/stop, API calls
Core Modules Storage / Config / Logger / Router and other foundational capabilities

L2 Must-Read (Unavoidable for Production-Grade Modules)

Document Description
Scope Three-dimensional scope control: module availability / event admission / outbound action restrictions (including method-level fine-grained rules and binding inheritance merge)
Ownership (owner) System Resource ownership and automatic reclamation: owner context, full picture of owned resources, unload cleanup sequence, design boundaries, and module author guide
Lifecycle Management Lifecycle event system: what modules / adapters should do when loaded, unloaded, reloaded, or disabled
Interactive Session System Complete guide to wait_reply, session timers (remind/escalate), multi-way waiting (select), session mutex leases, inbox, message transactions, and traceability

Grouped by Scenario (Consult as Needed)

Group Documents Pitfalls if You Skip the First Article
Startup & Boot Startup Flow & Manual Control · Lazy Loading Without understanding the startup chain (Finder / Loader / Manager / Router), you'll be left staring blankly at logs when module loading fails
Communication & Connections Inter-Module Communication · Connection Pools & Broadcasting · Routing System Without understanding the service contract (meta.services) whitelist, cross-module module.call will be rejected with ServiceNotProvidedError and you won't know why
Data Storage Storage Backends · SQL Builder · Network Client Without understanding the cooldown semantics for connection failures, database instability may lead you to wrongly conclude "the framework crashed" (in fact, storage operations fail fast and automatically reconnect after cooldown)
Messaging & Conversation Conversation Multi-Turn Dialogues · Session Inbox · MessageBuilder · Internationalization Without understanding session mutex leases, two modules waiting for the same user's reply simultaneously will kick each other out
Performance & Observability Performance Benchmarks & Tuning Skip the benchmark numbers before deployment and capacity planning is pure guesswork; skip regression comparison after upgrades and performance degradation goes unnoticed
Shadow & Canary Shadow Modules & Canary Promotion Promote a shadow module early without understanding the five isolation gates, and its outbound messages will leak to real users

Concept Relationship Master Table

When you can't tell which subsystem handles what, use this table to find your way:

Subsystem What Question It Answers One-Line Mnemonic
Communication (module-communication) How do modules call each other and send targeted events? Cross-module calls go through module.call; if the target declares meta.services, only whitelisted methods can be called
Permissions (scope) Who can use a module, who can trigger events, and which actions can be performed? Three gates—module binding, identity admission, and outbound restrictions—all dictated by user configuration
Ownership (ownership) After a module unloads, where do its connections, timers, and subscriptions go? Whoever registers owns it; unloading reclaims everything, leaving no dangling resources
Lazy Loading & Dormancy (lazy-loading) When does a module actually load, and where does it go when idle? activate_on wakes it only when needed; dormant_after puts it back to sleep when idle
Interaction (interaction) How to wait for the user's next reply, and how to write multi-turn collection? wait_reply waits for one; .got() chains collect multiple turns; leases guarantee no conflicts
Shadow & Canary (shadow) How to trial-run a new module version without affecting production? The shadow receives copies and outbound actions are only logged; promote requires human confirmation before going official
Storage (storage-backends) Where is data stored, and how do you switch backends? One storage API; switch between sqlite / mysql / postgres via configuration

4. Ecosystem & Official Client

Official client plus ecosystem modules that are installed on demand and work out of the box (none of them are built-in framework features).

Document Description
Ecosystem Overview How to install ecosystem modules, and why these aren't built-in features
ErisPulse-QvQChat General-purpose agent module: tool loop / MCP / long-term memory / knowledge base; modules declaring services automatically become AI tools
ErisPulse-ApiMCP Exposes the bot in reverse as MCP tools, letting AI clients like Claude control it directly
ErisPulse-App Official all-platform client (Android / Windows / Linux / macOS): manage multiple instances via native UI, runs directly on mobile, resides in the desktop tray
ErisPulse-Dashboard Web management panel + view registration API (modules can register custom pages in the sidebar)
ErisPulse-Cron Scheduled task module: one-time / interval / cron expressions, callback parameters, SQLite persistence; other modules can delegate scheduled callbacks to it
ErisPulse-Takumi Image rendering (HTML / node tree / SVG / animation, with built-in Chinese and English fonts)

5. I Want to Contribute to ErisPulse

Make the framework better

Document Description
Contributing to ErisPulse Overview of ways to contribute: documentation / i18n / bugs / modules / adapters
First Contribution From fork to submitting a PR

Advanced Features Version Quick Reference

When making version compatibility checks, or when taking over a legacy project and wondering "which version introduced this capability," look it up in this table (based on the version entries in the repository root CHANGELOG.md).

Version Capabilities Introduced
2.7 Production-ready foundation: OneBot12 standardized base classes (ApiDSL / BaseConverter), systematized configuration hot-reload, graceful shutdown with SIGTERM/SIGHUP signal handling, environment variable configuration overrides, lifecycle callback hooks, lazy loading of the web stack; 2.7.1 adds configuration write reliability and GC generational tuning
2.8 Permission and communication skeleton: three-dimensional scoping system (scope), interactive session infrastructure (lease / checkpoint / message transaction / session inbox transcript), protocol-based inter-module RPC (module.call / meta.services service contracts / targeted events emit(to=)), multi-backend async storage (sqlite / mysql / postgres, connection failures do not block the framework), ownership cleanup, configuration comment preservation; subsequent 2.8.x releases polish CLI scaffolding, subcommands, and more
2.9 "Module development experience" mainline (EPRFC-2026-001): declarative command parameters (args= / options=) and command governance (cooldown= / rate_limit=), unified dependency injection (Depends), middleware event veto power, built-in ORM (auto migration + relational mapping), shadow module canary-to-official promotion, dispatch decision-chain tracing and troubleshooting diagnostics, official support for Python 3.14
2.10 Connections as first-class resources (connections registry: broadcast / business grouping / cross-module passing and reuse / automatic reclamation on uninstall), root import contract (all commonly used APIs importable via from ErisPulse import), ownership system completion, runtime override of inbox retention policy; 2.10.2 adds adapter-local plugin directory (plugins/) + epsdk create pack + tomlclass lossless configuration writes
2.11 (dev) "Edit code → see results" development loop: hot-reload default full semantics (syntax pre-check + code identity verification + cascading re-export for dependents), lazy-load dormancy (dormant_after), adapter code-level hot reload (sdk.adapter.reload), .got() command-flow syntactic sugar, epsdk stop / restart runtime control
2.12 (dev) Lifecycle governance and operability: nested lifecycles (ownership.nest()), fine-grained hot reload (per-module/per-adapter determination, framework source changes trigger a process restart), background task pending queue, automatic account binding in the event dispatch chain (send_context / api_context / request_context with the same criteria, zero changes for multi-account modules), cross-account duplicate acceptance correlation (framework.cross_account_policy), shadow module whl ingestion and persistent-promotion closed loop, in-container epsdk restart in-process soft restart, SendDSL.Location()

Development Approaches

ErisPulse supports two development approaches:

  • Module development (recommended): create standalone module packages installed via a package manager, making distribution and management easy.
  • Embedded development: write handlers directly in your project, suitable for rapid prototyping. See the Quick Start for details.

Other

Getting Help