Adapter Standardization Guide (General Overview)

This document is the general overview of ErisPulse adapter standardization: it establishes cross-platform standardization principles, standard maps, difference handling models, the process for new capabilities to enter the standard, and provides complete definitions for interaction component standards (buttons/keyboard, dropdowns, etc.) and interaction callback events. Any adapter developer implementing new features should prioritize using the standard definitions, ensuring that module developers can achieve a consistent experience across any platform with the same code—consistent naming, consistent parameters, and consistent returns.

1. Standardization Principles

1. Consistent Naming: The same concept uses the same name across all platforms (e.g., delete_message for message deletion, keyboard for button segments), regardless of the platform.
2. Consistent Parameters: The parameter structure for standard actions/segments/methods remains consistent across all platforms; platform-specific parameters are provided as optional extended parameters or extended fields, without polluting the standard signature.
3. Consistent Return: All API/send calls return a standard response structure (status/retcode/data/message_id/message), and standard fields within data (such as user_id/user_name) have consistent semantics; platform-specific raw data is placed in {platform}_raw.
4. Reasoned Extension: Platform-specific capabilities are named with a {platform}_ prefix (segments: yunhu_form; actions: yunhu.board; event fields: qqbot_button_id), clearly indicating non-cross-platform features.
5. Platform Differences Absorbed in Adapter Layer: Module code is designed for standard programming, and platform differences are handled by the adapter (parameter mapping, field standardization, capability degradation), eliminating the need for modules to write platform-specific branches.
6. Graceful Degradation for Unsupported Capabilities: When a platform does not support a standard capability, it gracefully degrades (returns retcode=10002, component textification into alt_message), without throwing exceptions that interrupt module logic.

2. Standard Maps

3. Standardized Workflow (How New Capabilities Enter the Standard)

Platform-specific capabilities ({platform}_ prefix)
        │  ≥2 platforms exhibit similar capabilities
        ▼
Identify commonalities (extract generic concepts and parameter subsets)
        │
        ▼
Standard draft (naming + parameters + return + mapping table across platforms)
        │  Review
        ▼
Integrate into this overview/field-specific standard documents + implement compatibility layer via framework base class/adapters
        │
        ▼
Standard segments/actions (no prefix) — modules can be used across platforms

Example: Buttons were initially independently implemented across platforms (telegram_inline_keyboard / Yunhu buttons / QQBot keyboard) → appeared in ≥3 platforms → extracted generic structure (label/type/data + rows) → released standard segment keyboard → each adapter implements compatibility layer (decorator accepts generic structure + standard segment conversion + native segment passthrough).

3.1 Naming Rules

3.2 Parameter and Return Rules

• Standard parameters must be name and meaning consistent across all platforms; units/format are explicitly defined in the standard documentation (e.g., second-level timestamps, string IDs)
• Required parameters must be the common subset of all platform capabilities; platform-enhanced capabilities are optional parameters
• Platform-specific strong constraints (e.g., QQBot rich media cannot be mixed with event_id) are automatically handled/downgraded by adapters, not exposed to modules
• Standard fields returning data must be consistent across all platforms; platform-specific additional information is placed in platform-named fields within data or in {platform}_raw

4. Differential Handling Modes (Adapter Layer)

5. Interaction Component Standards

5.1 Component List and States

Modifier Hierarchy Convention: Send modifiers for generic interaction components are implemented by the adapter's Send class (not built into the framework base class), following the naming convention in §5.2, with parameters conforming to the standard structure defined in this document.

5.2 keyboard Button/Inline Keyboard

Message Segment Structure (Sending Direction)

{
  "type": "keyboard",
  "data": {
    "rows": [
      [
        {"label": "Option A", "type": "callback", "data": "vote:A"},
        {"label": "Website",   "type": "link",     "data": "https://example.com"}
      ]
    ]
  }
}

Platform Mapping Comparison

Send Modifier (Implemented by Each Adapter's Send Class)

The generic modifier is implemented by each adapter in its own Send class (without modifying the framework base class):

• .Keyboard(rows): Standard naming, accepts the generic rows structure in §5.2, internally generates the standard keyboard message segment (or directly converts to the platform-native structure), handled uniformly by Raw_ob12
• .Buttons(rows): Optional semantic alias, behavior is identical
• Backward Compatibility: When platform-native structures are detected, they are directly passed through (no error, no conversion)
• Platform-native extension segments (e.g., telegram_inline_keyboard) continue to be passed through and remain unaffected

# Same code, any platform (adapters provide modifier and conversion)
rows = [[{"label": "Like", "type": "callback", "data": "like:1"},
         {"label": "Homepage", "type": "link", "data": "https://example.com"}]]
await adapter.Send.To("group", gid).Keyboard(rows).Text("Please select")

Adapter Compatibility List: QQBot / Telegram / Yunhu have implemented (modifier + standard segment conversion); new adapters can implement as described in this document (see §7 Checklist).

5.3 Interaction Callback Events (After Button Click)

After the user clicks a button, the event pushed by the platform must provide the following standard fields (detail_type may retain platform naming):

detail_type Convention: Retain existing platform naming (qqbot_interaction / telegram_callback_query / yunhu_a2ui_button etc.), but standard fields must be complete—modules can retrieve values cross-platform using event.get("button_data").

Recommended Event Extension Methods (provided by adapter EventMixin):

def get_button_data(self) -> str: ...     # button_data
def get_interaction_id(self) -> str: ...  # interaction_id

Responding to Interaction (according to platform capability): adapter.reply_interaction(interaction_id, code=0) (QQBot) / answerCallbackQuery (Telegram), naming follows the platform method family, no mandatory unification.

Platform Callback Event Mapping

5.4 select Dropdown Selection (Reserved)

{
  "type": "select",
  "data": {
    "placeholder": "Please select",
    "options": [
      {"label": "Option A", "data": "opt:A"},
      {"label": "Option B", "data": "opt:B"}
    ],
    "min_values": 1,
    "max_values": 1
  }
}

Callback events reuse the fields in §5.3 (button_data = selected data, array for multiple selections). First platforms to implement: Discord (select menu), Telegram (keyboard switching). Platforms not implementing this segment should degrade to a text list in alt_message.

5.5 card Card (Reserved, Postponed Standardization)

Card structures vary greatly (Kook full-featured card module vs Yunhu html vs QQ markdown+keyboard), so no strict standard is enforced yet. Suggestions:

• Express rich text cards using text + keyboard combinations (sufficient for most scenarios)
• Continue using {platform}_card extension segments (e.g., kook_card) for full-featured cards
• Re-evaluate and upgrade once ≥2 platforms have similar card capabilities

6. Future Candidates (Roadmap)

The following capabilities have appeared or are expected to appear on ≥2 platforms, and are prioritized for standardization:

7. Standard Checklist for New Adapter Developers

When developing a new adapter, please follow this checklist for implementation (★ indicates required, others are recommended):

• ★ Convert events into OneBot12 standard structure, inherit BaseConverter
• ★ Support for standard message segment sending and receiving (text/image/mention/reply/keyboard…; media segments handled with hierarchical up/downgrading according to the form in Sending Method Specification §2.1)
• ★ Implement Raw_ob12 (including standard segment → platform structure conversion; standard keyboard segment must be implemented)
• ★ Return standard response structure (make_response/make_error)
• ★ Multi-account: AccountConfigClass(BotAccountConfig) + _resolve_account
• ★ Send class inherits BaseAdapter.Send, use _apply_modifiers/send_context
• ☆ API DSL: Map standard actions to platform APIs (see API Action Standards)
• ☆ Request DSL: Request events include request_id + accept/reject
• ☆ Interactive components: keyboard segment conversion + standard interactive callback fields + .Keyboard()/.Buttons()` decorators (implemented in adapter's Send class)
• ☆ EventMixin: Platform extension methods such as get_raw_event() / get_button_data()
• ☆ Use runtime.spawn_background for lifecycle tasks
• ☆ Use self.cfg for configuration reading
• ☆ Framework soft dependencies: Do not declare hard dependency on ErisPulse + runtime version detection
• ☆ i18n: Multi-language configuration fields and logs
• ☆ Platform documentation + adapter repository platform-features.md

8. Related Documentation

• See §2 Standard Maps for standards in various domains.
• Built-in adapters in the framework can serve as reference implementations: QQBot (full v5 paradigm), OneBot11 (API DSL mapping), YunHu (BaseConverter + Web API extension).