Multi-Account & ID Management
Relevant source files
The following files were used as context for generating this wiki page:
The OneBots framework coordinates multiple Instant Messaging (IM) accounts across various platforms through a centralized management system. It abstracts platform-specific identities into a unified internal model, allowing a single process to handle diverse protocols like OneBot, Satori, and Milky. The @onebots/core package provides the fundamental logic for account lifecycles and the ID mapping system.
Sources: README.en.md:27-32, AGENTS.md:14-22
Account Lifecycle Management
The Account class represents a unique identity on a specific IM platform. Each account maintains its own status and associated protocol instances. The management system tracks these accounts through the Adapter which serves as the factory and controller for platform-specific interactions.
Account Status Transitions
Accounts transition through specific states during their operational lifecycle. These states inform the gateway and downstream consumers about the account's availability.
- Pending: The initial state when an account is created but not yet connected.
- Online: The active state after a successful connection to the platform.
- Offline: The state when an account is manually stopped or disconnected due to an error.
Sources: adapters/adapter-mock/src/tests/adapter.test.ts:74-88, architecture-diagrams.md:50-54
The diagram shows the standard state transitions for an account instance within the framework.
Sources: adapters/adapter-mock/src/tests/adapter.test.ts:74-88
Key Account Components
| Component | Description |
|---|---|
account_id | A unique string identifying the account within its platform (e.g., qq.123456). |
status | The current operational state (Online, Offline, Pending). |
adapter | The platform-specific adapter managing the low-level connection. |
protocols | A collection of protocol instances (OneBot, Satori, etc.) exporting this account's data. |
Sources: architecture-diagrams.md:265-274, CONTRIBUTING.md:105-115
ID Management and Normalization
OneBots uses a normalization system to handle the varying ID formats used by different IM platforms. This system ensures that downstream plugins and protocols interact with a consistent data structure regardless of whether the platform uses numeric UINs, alphanumeric strings, or internal handles.
The ID Mapping Process
- Normalization (
createId): The adapter converts raw platform IDs into an internalCommonTypes.Idobject. This object stores the original source and provides both string and numeric representations. - Resolution (
resolveId): The system restores the original platform ID when sending data back to the IM platform.
Sources: AGENTS.md:145-148, adapters/adapter-mock/src/tests/adapter.test.ts:227-245
The flowchart illustrates the transformation lifecycle of an ID from the platform through the core and back.
Sources: AGENTS.md:14-22, adapters/adapter-mock/src/tests/adapter.test.ts:227-245
ID Object Structure
The normalized ID provides multiple accessors for different implementation requirements.
id.string: Returns the ID as a string for unified processing.id.number: Returns a numeric version of the ID, useful for legacy OneBot v11 protocols.id.source: Maintains the original raw data received from the platform.
Sources: AGENTS.md:145-148, adapters/adapter-mock/src/tests/adapter.test.ts:227-234
System Architecture and Routing
Accounts act as the bridge between the Adapter Layer and the Protocol Layer. The framework supports running multiple protocols on a single account simultaneously.
Data Flow for Multi-Account Events
When a platform sends an event, the following steps occur:
- Platform Event: The raw event reaches the specific Adapter.
- Normalization: The Adapter converts the event to a
CommonEventand normalizes all IDs. - Account Dispatch: The Account receives the
CommonEventviaaccount.dispatch(). - Protocol Export: The Account forwards the event to every active Protocol instance attached to it.
- Consumer Delivery: Each Protocol formats the event (e.g., OneBot v11 JSON) and delivers it to downstream clients.
Sources: README.en.md:40-45, architecture-diagrams.md:94-118
The sequence diagram shows how a single message from a platform is processed and delivered through multiple layers.
Sources: architecture-diagrams.md:94-118, README.en.md:79-81
Configuration Management
Account configurations are stored in the config.yaml file using a structured key format. The framework uses these configurations to instantiate adapters and accounts during startup.
Configuration Structure
Configurations follow a platform.account_id hierarchy.
- General Settings: Define global defaults for protocols.
- Platform Settings: Define credentials like tokens and secrets specific to the adapter.
- Protocol Overrides: Define specific listening ports or connection URLs for that specific account.
Sources: AGENTS.md:104-107, architecture-diagrams.md:195-215
Relationship Summary
The class diagram represents the ownership and communication relationships between core components.
Sources: architecture-diagrams.md:237-320
Multi-Account and ID Management ensures that the complexity of individual IM platforms remains isolated from the application logic. By enforcing ID normalization and status tracking, OneBots provides a stable environment for developing cross-platform bot services.