Best Practices for Adapter Development
Tip
When to read this: After the adapter skeleton is running, it is recommended to read (engineering best practices). If not needed, skip it; it does not affect the use of other features.
This section summarizes engineering conventions for adapter development: Bot status reporting, connection retry and heartbeat, multi-account parsing, and standardized error responses. Following these practices can avoid common issues during platform integration, such as undetected disconnections, incorrect multi-account message targets, and hard-to-locate error reporting.
Bot Status Management and Meta Events
The adapter should actively send meta events via adapter.emit() to allow the framework to automatically track the Bot's connection status, online/offline events, and heartbeat information.
1. When to Send Meta Events
| Event | detail_type |
Trigger Timing | Framework Behavior |
|---|---|---|---|
| Connect | "connect" |
When the Bot establishes a connection with the platform | Register the Bot, trigger the adapter.bot.online lifecycle event |
| Disconnect | "disconnect" |
When the Bot disconnects from the platform | Mark the Bot as offline, trigger the adapter.bot.offline lifecycle event |
| Heartbeat | "heartbeat" |
Sent periodically (recommended: 30-60 seconds) | Update the Bot's active time and metadata |
2. Sending Meta Events
The framework provides the emit_meta() method, which allows sending meta events in one line:
class MyAdapter(BaseAdapter):
async def _ws_handler(self, websocket):
bot_id = self._get_bot_id()
# Bot online: send connect event in one line
await self.emit_meta("connect", bot_id, user_name="MyBot", nickname="我的机器人")
try:
while True:
data = await websocket.receive_text()
event = self.convert(data)
if event:
await self.adapter.emit(event)
except WebSocketDisconnect:
pass
finally:
# Bot offline
await self.emit_meta("disconnect", bot_id)
You can also manually construct a standard meta event (the old method is still compatible):
await self.adapter.emit({
"id": str(uuid4()),
"time": int(time.time()),
"type": "meta",
"detail_type": "connect",
"platform": "myplatform",
"self": {
"platform": "myplatform",
"user_id": bot_id,
"user_name": "MyBot",
"avatar": "https://example.com/avatar.jpg",
},
"myplatform_raw": raw_data,
"myplatform_raw_type": "connected",
})
3. Heartbeat Event
The adapter should regularly send heartbeat events during the connection's active period to update the Bot's active time:
class MyAdapter(BaseAdapter):
async def _heartbeat_loop(self, bot_id: str):
while self._connected:
# Send meta heartbeat to the framework (one line)
await self.emit_meta("heartbeat", bot_id)
await asyncio.sleep(30)
4. Automatic Discovery of the self Field
The framework's adapter.emit() automatically processes the self field in all events (not just meta events):
- The
selffield in normal events (message/notice/request) will be automatically discovered and registered as a Bot. - Extended information in the
selffield: Supports optional fields such asuser_name,nickname,avatar, andaccount_id.
# Include the `self` field in the converter to automatically register the Bot
onebot_event = {
"type": "message",
"detail_type": "private",
"platform": "myplatform",
"self": {
"platform": "myplatform",
"user_id": "bot123",
"user_name": "MyBot",
"nickname": "我的机器人",
},
# ... other fields
}
await self.adapter.emit(onebot_event)
# Bot "bot123" is automatically registered and its active time is updated
5. Bot Status Query
The query APIs (get_bot_info() / list_bots() / is_bot_online() / get_status_summary()) and the Bot lifecycle event table are available at Adapter System API - Bot Status Management.
Connection Management
1. Implementing Connection Retry
import asyncio
class MyAdapter(BaseAdapter):
async def start(self):
retry_count = 0
max_retries = 5
while retry_count < max_retries:
try:
await self._connect_to_platform()
self.logger.info("Connection successful")
break
except Exception as e:
retry_count += 1
if retry_count < max_retries:
# Exponential backoff strategy
wait_time = min(60 * (2 ** retry_count), 600)
self.logger.warning(
f"Connection failed, retrying in {wait_time} seconds ({retry_count}/{max_retries}): {e}"
)
await asyncio.sleep(wait_time)
else:
self.logger.error("Connection failed, maximum retry attempts reached")
raise
2. Connection State Management
class MyAdapter(BaseAdapter):
async def start(self):
self.connection = None
self._connected = False
async def _ws_handler(self, websocket: WebSocket):
self.connection = websocket
self._connected = True
self.logger.info("Connection established")
try:
while True:
data = await websocket.receive_text()
await self._process_event(data)
except WebSocketDisconnect:
self.logger.info("Connection disconnected")
finally:
self.connection = None
self._connected = False
3. Heartbeat Keepalive and Meta Heartbeat
The adapter's heartbeat should simultaneously perform two tasks: sending a heartbeat keepalive to the platform and sending a meta heartbeat event to the framework.
class MyAdapter(BaseAdapter):
async def start(self):
self.connection = await self._connect_to_platform()
self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
async def _heartbeat_loop(self):
while self.connection:
try:
# 1. Send heartbeat keepalive to the platform
await self.connection.send_json({"type": "ping"})
# 2. Send meta heartbeat to the framework (using emit_meta in one line)
await self.emit_meta("heartbeat", self._bot_id)
await asyncio.sleep(30)
except Exception as e:
self.logger.error(f"Failed to heartbeat: {e}")
break
4. Connection Information Exposure
The routes registered by the adapter should be visible to users to facilitate configuring the callback address on the platform side. It is recommended to actively output connection information in start():
class MyAdapter(BaseAdapter):
async def start(self):
router.register_websocket(
module_name=self.platform,
path="/ws",
handler=self._ws_handler
)
if self.sdk:
info = self.sdk.adapter.get_connection_info(self.platform)
if info:
self.logger.info(f"WebSocket address: "
f"{info.get('connection', {}).get('base_url', '')}"
f"{info.get('connection', {}).get('websocket_routes', [])}")
Users can query the adapter's routes and connection addresses via the following APIs:
from ErisPulse import sdk
# Adapter-level connection information (recommended)
info = sdk.adapter.get_connection_info("myplatform")
# Router manager-level query
sdk.router.list_namespaces() # List all namespaces
sdk.router.get_module_routes("myplatform") # Detailed route information
sdk.router.get_module_urls("myplatform") # Complete connection URL
Note: The
module_nameused during route registration must exactly match theplatformname registered by the adapter in ErisPulse, otherwiseget_connection_info()will not associate the routes. For multi-account adapters, register sub-paths (e.g.,/account1/webhook,/account2/webhook) instead of using differentmodule_name.
5. HTTP Route Lifecycle
HTTP/WebSocket routes registered by the adapter/module are managed by the framework according to the ownership principle:
- The
module_name(namespace) used during registration is the ownership identifier; the framework automatically cleans up all routes and connection resources under this ownership during reload / stop / unload, without the need for manual deregistration - Therefore, routes must be re-registered unconditionally in
start()(module-levelon_load). Do not use instance-level boolean flags for "register only once" optimization: configuration hot reload (e.g., immediate saving of account field changes) triggers stop/start and reuses the same instance, causing the flag to persist and routes to be permanently lost after cleanup, resulting in 404 errors and requiring a process restart to recover
class MyAdapter(BaseAdapter):
async def start(self):
# Re-register routes unconditionally on each startup (routes were automatically cleaned up after previous stop)
router.register_http_route(self.platform, "/qr/start", self._qr_start, methods=["POST"])
router.register_http_route(self.platform, "/qr/poll", self._qr_poll, methods=["POST"])
The module side is similar (register in on_load):
class MyModule(BaseModule):
async def on_load(self):
router.register_http_route("MyModule", "/api/panel", self._panel, methods=["GET"])
If you need to manually unregister routes in advance (e.g., dynamically taking down an entry), you can actively deregister:
from ErisPulse.Core import router
router.unregister_http_route(self.platform, "/qr/start")
- Frontend/callers may receive 404 errors during the hot reload window, which is a transient phenomenon; for browser-facing interactive pages, it is recommended to implement limited automatic retries for 404 errors
Event Conversion
1. Strictly Follow the OneBot12 Standard
class MyPlatformConverter:
def convert(self, raw_event):
"""Convert event"""
onebot_event = {
"id": str(raw_event.get("event_id", uuid.uuid4())),
"time": int(time.time()),
"type": self._convert_type(raw_event.get("type")),
"detail_type": self._convert_detail_type(raw_event),
"platform": "myplatform",
"self": {
"platform": "myplatform",
"user_id": str(raw_event.get("bot_id", ""))
},
"myplatform_raw": raw_event, # Preserve raw data (required)
"myplatform_raw_type": raw_event.get("type", "") # Raw type (required)
}
return onebot_event
2. Standardize Timestamps
def _convert_timestamp(self, timestamp):
"""Convert to 10-digit second-level timestamp"""
if not timestamp:
return int(time.time())
# If it is a millisecond-level timestamp
if timestamp > 10**12:
return int(timestamp / 1000)
# If it is a second-level timestamp
return int(timestamp)
3. Generate Event IDs
import uuid
def _generate_event_id(self, raw_event):
"""Generate event ID"""
event_id = raw_event.get("event_id")
if event_id:
return str(event_id)
# If the platform does not provide an ID, generate a UUID
return str(uuid.uuid4())
SendDSL Implementation
The At/AtAll/Reply decorators are already built into the framework's SendDSL base class; the adapter only needs to implement Raw_ob12 and specific send methods. Use self._apply_modifiers(message) and self.send_context to simplify development.
1. Must Return a Task Object
class Send(BaseAdapter.Send):
def Raw_ob12(self, message, **kwargs):
"""Recommended implementation: Use framework helper method"""
async def _do_send():
segments = self._apply_modifiers(message)
return await self._adapter.call_api(
endpoint="/send_message",
message=segments,
**self.send_context,
**kwargs
)
return asyncio.create_task(_do_send())
def Text(self, text: str):
return self.Raw_ob12([{"type": "text", "data": {"text": text}}])
2. Chainable Modifier Methods Return self
class Send(BaseAdapter.Send):
def __init__(self, adapter, target_type=None, target_id=None, account_id=None):
super().__init__(adapter, target_type, target_id, account_id)
self.buttons = []
def Button(self, content: list) -> 'Send':
self.buttons.append(content)
return self # Return self
3. Support Platform-Specific Methods
class Send(BaseAdapter.Send):
def Sticker(self, sticker_id: str):
"""Send sticker"""
return asyncio.create_task(
self._adapter.call_api(
endpoint="/send_sticker",
message=[{"type": "sticker", "data": {"id": sticker_id}}],
**self.send_context
)
)
def Card(self, card_data: dict):
"""Send card message"""
return asyncio.create_task(
self._adapter.call_api(
endpoint="/send_card",
message=[{"type": "card", "data": card_data}],
**self.send_context
)
)
API Response
1. Standardized Response Format
The framework provides make_response() and make_error() methods to construct standardized responses:
async def call_api(self, endpoint: str, **params):
try:
raw_response = await self._platform_api_call(endpoint, **params)
if raw_response.get("success"):
return self.make_response(
data=raw_response.get("data"),
message_id=raw_response.get("data", {}).get("message_id", ""),
raw=raw_response,
)
else:
return self.make_error(
retcode=raw_response.get("code", 10001),
message=raw_response.get("message", ""),
raw=raw_response,
)
except Exception as e:
return self.make_error(message=str(e))
make_response() will automatically generate a response dictionary containing the {platform}_raw key. make_error() defaults to using retcode=34000 (Platform Error).
2. Error Code Specification
Follow the OneBot12 standard error codes:
# 1xxxx - Action request errors
10001: Bad Request
10002: Unsupported Action
10003: Bad Param
# 2xxxx - Action handler errors
20001: Bad Handler
20002: Internal Handler Error
# 3xxxx - Action execution errors
31000: Database Error
32000: Filesystem Error
33000: Network Error
34000: Platform Error
35000: Logic Error
Multi-Account Support
1. Declarative Configuration (Recommended)
After declaring the configuration class using AccountConfigClass, the framework will automatically manage multi-account loading, validation, and template generation. The BotAccountConfig base class provides the enabled and name fields, which the adapter does not need to declare:
from dataclasses import dataclass, field
from ErisPulse.Core.Bases import BotAccountConfig
@dataclass
class MyBotConfig(BotAccountConfig):
token: str = field(default="", metadata={
"description": {"i18n": "my_adapter.bot_token", "default": "Bot Token"},
"required": True,
"secret": True,
})
class MyAdapter(BaseAdapter):
AccountConfigClass = MyBotConfig
async def start(self):
for name, account in self.enabled_accounts.items():
self.logger.info(f"Starting account {name}")
await self._connect(name, account.token)
# bot_id is automatically filled by the framework from the platform protocol/login response
async def call_api(self, endpoint: str, **params):
account_id = params.pop("account_id", None)
name, account = self._resolve_account(account_id)
# name: account name, account: MyBotConfig instance
The configuration file is automatically generated as:
[MyAdapter.accounts.default]
token = ""
enabled = true
name = ""
2. Account Selection Mechanism
The account identifier specified when sending (via Using() or event chain binding) is automatically resolved by the framework, with matching priority:
- Account name — exact match with the configuration key
bot_idfield —bot_idfrom the account configuration (automatically filled at runtime, usuallyevent["self"]["user_id"])- Any str field — other string fields in the configuration
- Fallback — the first enabled account
When implementing call_api, use the framework's built-in account resolution to complete the mapping from "identifier → account configuration":
# Match by account name
name, account = self._resolve_account("account1")
# Match by bot_id (most commonly used, from event)
name, account = self._resolve_account("bot_123")
# Get the first enabled account (pass None)
name, account = self._resolve_account(None)
Error Handling
1. Categorized Exception Handling
Use make_error() to construct standardized error responses. When using sdk.client to request, catch ErisPulse exceptions:
from ErisPulse.Core.Bases.errors import ClientError, ClientTimeoutError
async def call_api(self, endpoint: str, **params):
try:
from ErisPulse.Core import client
resp = await client.post(
f"https://api.platform.com/{endpoint}",
json=params,
max_retries=2,
)
response = await resp.json()
return self.make_response(data=response, raw=response)
except ClientTimeoutError:
self.logger.error(f"Request timeout: {endpoint}")
return self.make_error(retcode=32000, message="Request timeout")
except ClientError as e:
self.logger.error(f"Network error: {e}")
return self.make_error(retcode=33000, message="Network request failed")
except json.JSONDecodeError:
self.logger.error("JSON parsing failed")
return self.make_error(retcode=10006, message="Response format error")
except Exception as e:
self.logger.error(f"Unknown error: {e}", exc_info=True)
return self.make_error(message=str(e))
Backward Compatibility: The old adapter code using
aiohttpis unaffected and can still catchaiohttp.ClientError. Exception conversion only takes effect when requests are made viasdk.client.
2. Logging
The framework automatically creates a sub-logger for the adapter (sdk.logger.get_child("MyAdapter")), so there is no need to manually initialize:
class MyAdapter(BaseAdapter):
# ConfigClass = ... # After declaring the configuration class, self.logger is automatically available
async def start(self):
self.logger.info("Adapter starting...")
# ...
self.logger.info("Adapter started")
async def shutdown(self):
self.logger.info("Adapter shutting down...")
# ...
self.logger.info("Adapter shutdown complete")
Testing
1. Unit Tests
import pytest
from ErisPulse.Core.Bases import BaseAdapter
class TestMyAdapter:
def test_converter(self):
"""Test converter"""
converter = MyPlatformConverter()
raw_event = {"type": "message", "content": "Hello"}
result = converter.convert(raw_event)
assert result is not None
assert result["platform"] == "myplatform"
assert "myplatform_raw" in result
def test_api_response(self):
"""Test API response format"""
adapter = MyAdapter()
response = adapter.call_api("/test", param="value")
assert "status" in response
assert "retcode" in response
2. Integration Tests
@pytest.mark.asyncio
async def test_adapter_start():
"""Test adapter start"""
adapter = MyAdapter()
await adapter.start()
assert adapter._connected is True
@pytest.mark.asyncio
async def test_send_message():
"""Test send message"""
adapter = MyAdapter()
await adapter.start()
result = await adapter.Send.To("user", "123").Text("Hello")
assert result is not None
Reverse Conversion and Message Building
Raw_ob12 is the method that the adapter must implement, serving as the unified entry point for reverse conversion (OneBot12 → platform). Standard methods (Text, Image, etc.) should delegate to Raw_ob12, and modifier states (At/Reply/AtAll) must be merged into message segments within Raw_ob12.
MessageBuilder is a message segment builder tool that works in conjunction with Raw_ob12, supporting chainable calls and rapid construction.
For complete implementation specifications, code examples, and usage methods, please refer to:
Platform Event Method Extension
The adapter can register platform-specific methods for Event wrapper classes, allowing module developers to more easily access platform-specific data.
1. Use Mixin Class for Batch Registration (Recommended)
When the platform has multiple specific methods, it is recommended to use a Mixin class:
# Register at the start() or module level
from ErisPulse.Core.Event import register_event_mixin
class MyPlatformEventMixin:
def get_chat_name(self):
"""Get chat name"""
return self.get("myplatform_raw", {}).get("chat", {}).get("name", "")
def is_official_message(self):
"""Check if it is an official message"""
raw = self.get("myplatform_raw", {})
return raw.get("sender", {}).get("is_official", False)
def get_message_type(self):
"""Get platform message type"""
return self.get("myplatform_raw", {}).get("msg_type", "text")
# Register in bulk
register_event_mixin("myplatform", MyPlatformEventMixin)
2. Use Decorator to Register a Single Method
from ErisPulse.Core.Event import register_event_method
@register_event_method("myplatform")
def get_chat_name(self):
return self.get("myplatform_raw", {}).get("chat", {}).get("name", "")
3. Clean Up on Adapter Shutdown
from ErisPulse.Core.Event import unregister_platform_event_methods
class MyAdapter(BaseAdapter):
async def shutdown(self):
# Clean up platform event method registration
unregister_platform_event_methods("myplatform")
# ... other cleanup
For more detailed registration and deregistration instructions, please refer to Event System API - Register Platform Extension Methods.
Documentation Maintenance
1. Maintain Platform Feature Documentation
Create a {platform}.md document under docs/en/platform-guide/ (other language versions will be automatically generated):
# Platform Name Adapter Documentation
## Basic Information
- Corresponding Module Version: 1.0.0
- Maintainer: Your Name
## Supported Message Sending Types
...
## Specific Event Types
...
## Configuration Options
...
2. Update Version Information
When releasing a new version, update the version information in the documentation:
[project]
version = "2.0.0" # Update the version number
Related Documentation
Review Prerequisites
- Getting Started with Adapter Development - Create your first adapter
- Core Concepts of Adapters - Understand adapter architecture
- SendDSL Detailed Explanation - Learn message sending
After Completing the Adapter
- Publishing and Module Store Guide - Publish to PyPI and the module store