Framework Interop
Relevant source files
The following files were used as context for generating this wiki page:
Framework Interop provides a standardized mechanism for connecting the OneBots gateway to external bot frameworks. It utilizes pre-defined profiles and connection plans to map IM platform accounts to standard protocols like OneBot (v11/v12), Satori, and Milky. This system ensures that downstream consumers, such as NoneBot or Koishi, can interact with multiple IM platforms without requiring custom glue code for each platform.
Sources: README.en.md:15-20, AGENTS.md:12-16
Integration Architecture
The interop system operates through a registry-based architecture. It loads framework definitions and provides tools to generate configuration templates for both OneBots and the target framework.
Core Components
- Framework Registry: Maintains a collection of immutable integration profiles for supported frameworks.
- Integration Profiles: Store metadata including the framework name, supported protocols (e.g.,
onebot.v11), transport types (e.g.,websocket,reverse-websocket), and verification status. - Connection Planner: Calculates the specific endpoints and configuration strings required to establish a link between a OneBots account and a framework instance.
- Distribution Audit: Tracks the compatibility of specific bot actions (e.g.,
send_private_msg) between the framework's requirements and the gateway's capabilities.
Sources: packages/onebots/src/framework-integration.spec.ts:13-30, packages/onebots/src/cli/framework-command.ts:43-55
Data Flow for Connection Planning
The following diagram illustrates how the system generates a connection plan when requested by a user or the CLI.
The system requires a valid framework ID and a platform account (formatted as platform.account_id) to generate a template.
Sources: packages/onebots/src/cli/framework-command.ts:39-65, packages/onebots/src/framework-integration.spec.ts:258-265
Integration Profiles
Integration profiles define how a specific framework interacts with OneBots. Each profile includes a verification level that indicates the maturity of the integration.
Verification Levels
| Level | Description |
|---|---|
| Handshake | Indicates that interoperability has been verified with specific versions of the framework and its adapter. |
| Documented | Confirms the upstream integration interface exists but lacks full automated interoperability evidence in the current version. |
| Experimental | New or unstable integrations available via extension management. |
| Legacy | Older integrations maintained for backward compatibility. |
Sources: packages/onebots/src/cli/framework-command.ts:107-111, packages/onebots/src/cli/command-application.frameworks.spec.ts:27-32
Supported Frameworks (Subset)
| Framework | Protocol | Transport | Verification |
|---|---|---|---|
| Koishi | Satori | HTTP | handshake |
| NoneBot2 | OneBot v11 | Reverse WS | handshake |
| AlemonJS | OneBot v11 | WebSocket | handshake |
| Karin | Milky v1 | HTTP/WS | handshake |
| Yunzai | OneBot v11 | WebSocket | documented |
Sources: packages/onebots/src/framework-integration.spec.ts:48-75, packages/onebots/src/cli/command-application.frameworks.spec.ts:16-25
Connection Types and Transports
The interop system handles various transport methods to accommodate different framework architectures.
Reverse WebSocket
In this mode, OneBots acts as a client and connects to the framework's server. The connection plan generates ws_reverse arrays for the OneBots config.yaml and corresponding environment variables or config keys for the framework.
Sources: packages/onebots/src/framework-integration.spec.ts:101-125
Forward WebSocket
The framework acts as a client and connects to the OneBots gateway. The system resolves the endpoint URL based on the onebotsOrigin (e.g., ws://127.0.0.1:6727/qq/main/onebot/v11).
Sources: packages/onebots/src/framework-integration.spec.ts:127-135
Flow diagrams describe the directional nature of WebSocket connections between the gateway and the framework.
Sources: architecture-diagrams.md:255-285
Verification and Auditing
To ensure reliable operation, the system performs "Distribution Audits" on framework source code.
Source Coverage Audit
The audit compares the actions required by the framework against those supported by the OneBots protocol implementation. For example, a Yunzai audit might show 31 out of 59 required actions are supported, identifying gaps like upload_group_file or get_guild_list.
Sources: packages/onebots/src/framework-integration.spec.ts:77-99, packages/onebots/src/cli/command-application.frameworks.spec.ts:39-45
Connection Checks
Connection plans include a checks array used to verify the environment. Each check specifies a name and an expected outcome (e.g., verifying if a command returns a specific version).
Sources: packages/onebots/src/cli/framework-command.ts:95-101
CLI Usage
The onebots frameworks command provides access to interop features.
- List Frameworks:
onebots frameworkslists all registered profiles, their protocols, and verification status. - Generate Plan:
onebots frameworks --framework <id> --account <platform.id>generates a complete connection template. - JSON Output: The
--jsonflag provides machine-readable metadata for automated tools. - Origins: The
--originand--framework_originflags allow specifying custom base URLs for endpoint resolution.
Sources: packages/onebots/src/cli/framework-command.ts:25-37, packages/onebots/src/cli/command-application.frameworks.spec.ts:8-15
Conclusion
Framework Interop serves as the critical link between IM platform adapters and the diverse ecosystem of bot frameworks. By centralizing connection logic and verification evidence into immutable profiles, it provides a reliable and transparent deployment path for developers. The system ensures that compatibility is documented and audited, reducing the operational complexity of running multi-platform bot services.