Technical Standards

General Principles: Adapter Standardization Guide — Standardization principles, standard maps, naming conventions, difference handling patterns, and developer Checklist. Please read it first for new adapters/new capabilities.

This document contains the technical standards specifications for ErisPulse, ensuring consistency and compatibility among components.

Standard Document List

1. Session Type Standard - ErisPulse session type definitions and mapping specifications
2. Event Conversion Standard - Platform event conversion specifications, extension naming conventions, and message segment standards
3. API Response Standard - Adapter API response format standards and extension requirements
4. Send Method Specification - Naming, parameter specifications for Send class methods, and reverse conversion requirements
5. Request Action Specification - Request event field requirements, HandleRequest DSL, and adapter implementation requirements
6. API Action Standard - Unified interface for OneBot12 standard API actions (user/group/channel/message management/file with chunking/meta actions)
7. Adapter Standardization Guide (General Outline) - Standardization principles/workflow/naming conventions + interaction component standards (buttons/keyboards/interaction callback events) and platform mappings

Standard Overview

ErisPulse adopts OneBot12 as its core event standard, and extends and refines it based on this foundation.

Core Principles

1. Compatibility: All standards must remain compatible with the OneBot12 standard.
2. Extensibility: Platform-specific features are extended using prefixes to avoid conflicts.
3. Consistency: Key fields such as timestamps and ID formats must be uniformly handled.
4. Traceability: Original data is retained for debugging and issue troubleshooting.

Why is a Standard Needed?

1. Ensure Cross-Platform Compatibility

Event formats vary across different platforms. Standardized conversion ensures:

• Module code needs to be written only once and can run on all platforms
• Event handling logic remains consistent
• Development and maintenance costs are reduced

2. Standardize API Interfaces

A unified API response format ensures:

• Modules can consistently handle API errors
• Error messages are uniform and easy to understand
• Return data structures are consistent

3. Improve Code Quality

Standardized specifications help:

• Maintain consistent code style
• Reduce naming conflicts
• Improve code readability

Benefits of Following Standards

For Adapter Developers

• Clear conversion rules
• Unified response format
• Easy debugging and testing

For Module Developers

• Consistent event interface
• Predictable API behavior
• Simplified cross-platform development

For End Users

• Stable system behavior
• Uniform message format
• Good compatibility

Standard Compliance Checklist

Event Transformation

• All standard fields have been correctly mapped
• Platform-specific fields have been prefixed
• Timestamps have been converted to 10-digit second-level
• Raw data has been saved in {platform}_raw
• Raw event type has been saved in {platform}_raw_type
• alt_message for message segments has been generated
• Request events contain the request_id field

API Response

• Contains status field
• Contains retcode field
• Contains data field
• Contains message_id field
• Contains message field
• Return codes follow the OneBot12 specification

Sending Method Naming

• Uses PascalCase naming convention
• Returns a Task object
• Modifier methods return self
• Parameter naming conforms to the specification

Media Sending (Image / Voice / Video / File)

• The file parameter must support all forms: HTTP(S) URL / local path / bytes
• Form determination follows the specification order (bytes → URL → file:// → path)
• The filename for File is generated in the following order (explicit filename > URL basename > path basename > platform default)
• Platform media limits are declared in the adapter documentation
• Unsupported media types are handled via a degradation ladder (nearby types degraded or retcode=10002, no exceptions thrown, no silent discarding)

See Sending Method Specification §2.1 for detailed protocol

Request Operations

• HandleRequest class has implemented _do_accept / _do_reject
• Operation returns standard API response format
• Unsupported operations return retcode=10002

Related Documentation

• Platform Features Guide - Learn about the feature differences between platforms
• Developer Guide - Develop custom modules and adapters