DOCSEARCHbyAlgolia
Submit Docs

PepperBot Documentation

website·Indexed 29 days ago

https://ssmjae.github.io/PepperBot/

A Python-based bot framework supporting multiple platforms including QQ (via go-cqhttp), WeChat, and Telegram. It features a class-based command system with state management, flexible event response mechanisms similar to Django class views, and integrated support for APScheduler for timed tasks. The framework utilizes Sanic for its web server and worker management, and Poetry for dependency management.

Tokens
22.3K
Snippets
148
Records
206
Agent score
74%

What's inside PepperBot

  1. Overview of PepperBot design philosophy

    PepperBot is a Python-based robot framework designed to eliminate bloated boilerplate code and provide an intuitive, semantic API. Its primary goal is to allow developers to focus on business logic rather than framework overhead. Key features include:

    • Intuitive API: Designed to be understood at a glance.
    • Low Entry Barrier: Developers can start with simple event response mechanisms before moving to advanced features like commands.
    • Battery-included: Comes with built-in common functionalities such as commands and routing, removing the need for manual implementation.
    • Customizability: Provides high flexibility for customized requirements while offering established best practices.

  3. Understand PepperBot's caching architecture

    PepperBot stores its cache in a separate dictionary instead of directly on the class. This design choice is made because PepperBot performs numerous pre-runtime (compile-time) AST checks. Since classes are typically not yet instantiated during these checks, storing cache on the class instance would make it difficult to retrieve and could lead to runtime errors.

  4. Understand PepperBot route resolution logic

    PepperBot resolves routes by creating a mapping based on three primary dimensions: the bot protocol (e.g., onebot for QQ, keaimao for WeChat), the session type (e.g., private chat, group chat, channel), and the handler type (e.g., event_handler, command). When an event is received, PepperBot uses this mapping to locate and execute the corresponding handler.

  5. Understand PepperBot Command Lifecycle Hooks

    PepperBot uses a session-based lifecycle to manage commands from trigger to completion. This allows developers to define specific behaviors for different stages of a command's execution. The lifecycle hooks map conceptually to Python's exception handling blocks:

    • initial: The entry point (similar to the try block).
    • catch: Handles exceptions from any other handler (similar to except).
    • finish: Triggered when the command completes naturally without timeout, exit, or error (similar to else).
    • cleanup: Always executes at the end of the session (similar to finally).

  6. Utilize PepperBot as a flexible event receiver or API caller

    PepperBot is designed to be used flexibly. Developers are not required to use all its features and can use it strictly as:

    • An event receiver (listening for platform events).
    • An API caller (sending requests to platform APIs).

  7. Apply @available to Handlers and Commands

    The @available decorator can be applied to various components of the PepperBot architecture:
    # 1. On a Handler class
@available(checker1, checker2)
class MyHandler:
    ...

# 2. On a Handler method
class MyHandler:
    @available(checker3)
    async def group_message(self, ...):
        ...

# 3. On a Command class (order relative to @as_command does not matter)
@available(checker1)
@as_command(...)
class MyCommand:
    ...

# 4. On a Command method
@as_command(...)
class MyCommand:
    @available(checker3)
    async def initial(self, ...):
        ...

  8. Understand Message Chains and Segments

    A MessageChain represents a message received by the bot. It consists of one or more MessageSegments (e.g., Text, Face, Image).

    Cross-Platform Behavior:

    • QQ: Supports multiple segments in a single message.
    • WeChat: Only supports one segment per message. If a MessageChain with multiple segments is sent to WeChat, PepperBot automatically splits it and sends each segment as a separate message.

  10. Understand the role of the Protocol Backend in PepperBot

    PepperBot does not natively communicate with platforms like QQ, WeChat, or Telegram; it only handles business logic. It relies on a "Protocol End" (also called a "Backend") to simulate client behavior and perform the actual receiving and sending of messages to these platforms.

  11. Retrieve group and member information

    Fetch detailed information about a group or a specific member. Use no_cache to bypass cached data for more up-to-date results.
    // Get Group Info
// Args: group_id (int), no_cache (bool, optional)
get_group_info(group_id, no_cache);
/* Returns: { group_id, group_name, group_memo, group_create_time, group_level, member_count, max_member_count }
*/

// Get Member Info
// Args: group_id (str), user_id (str)
get_group_member_info(group_id, user_id);

  12. Understand PepperBot bidirectional communication architecture

    PepperBot uses a bidirectional communication model to interact with protocol adapters (e.g., go-cqhttp for QQ).

    1. Event Flow: When a protocol adapter receives a new event, it sends that event to PepperBot.
    2. API Flow: When PepperBot needs to perform an action (e.g., sending a message), it sends an API call request to the protocol adapter.

    Requirement: To use a protocol adapter, both the adapter (e.g., go-cqhttp) and PepperBot must be running simultaneously in separate processes/windows.