DOCSEARCHbyAlgolia
Submit Docs

Koishi Chatbot Framework

repository·master·Indexed 26 days ago

https://github.com/koishijs/koishi

A high-performance, extensible TypeScript chatbot framework featuring a web-based console and a rich plugin ecosystem. It supports multiple platforms including QQ, Telegram, Discord, and Feishu. The framework provides a robust Command system with support for subcommands, aliases, custom argument domains, and middleware via .before() and .action() methods.

Tokens
9.4K
Snippets
8
Records
71
Agent score
91%

What's inside Koishi

  1. Overview of Koishi Chatbot Framework

    master

    Koishi is a cross-platform, extensible, and high-performance chatbot framework. It is designed to support a wide range of chat platforms and provides a robust ecosystem for building both large-scale interactive applications and lightweight assistant bots.

    Key Features

    • Out-of-the-box usability: Includes a convenient web console for managing bots, an online plugin market for easy installation without programming knowledge, and support for mainstream platforms like QQ, Telegram, Discord, and Feishu.
    • Rich Ecosystem: Over 3,000 official and community plugins covering platform support, databases, resource storage, web consoles, state management, and business logic.
    • Developer-Centric Design:
      • TypeScript Support: Built entirely with TypeScript, providing top-tier type definitions and code completion.
      • Unit Testing: Core features are fully tested, providing a reliable foundation and best practices for plugin testing.
      • Module Hot Reloading: Supports hot reloading during plugin development, allowing changes to take effect without restarting the entire bot.

  5. Use the Mock adapter for testing and simulation

    master

    The mock adapter allows you to simulate bot interactions and messages within Koishi. It provides a MockBot and a MockAdapter that can be used to trigger events and manage mock users and channels via the database.

    When using the mock adapter, the Context is extended with a mock property, and User objects include a mock string property.

  6. Use the callme command

    master

    The callme plugin allows users to change their display name via a command. It can be triggered using the command name, an alias, or a shortcut.

    Command Details:

    • Command: callme [name:text]
    • Alias: nn
    • Shortcut: 叫我 (supports prefix: true and fuzzy: true matching)

    Behavior:

    • If no name is provided, the bot returns the current username or an unnamed placeholder.
    • If a name is provided, the plugin attempts to update the user's name in the database.
    • If the provided name is the same as the current name, it returns an 'unchanged' message.
    • If the name update fails due to a duplicate entry, it returns a 'duplicate' message.

  7. Use the help command

    master

    The help plugin provides a help command to retrieve information about other commands.

    Usage

    • help: Lists global commands.
    • help <command_name>: Shows detailed help for a specific command, including its description, usage, options, and examples.
    • help <command_name> -H: Shows help information including hidden options (if the user has permission).

    Features

    • Fuzzy Matching: If shortcut is enabled, you can use fuzzy/shortcut names to find commands.
    • Permission Aware: The help output respects user permissions; commands or options the user cannot access will not be shown unless -H is used and permissions allow.

  8. Configure I18n settings

    master

    The I18n.Config schema defines how internationalization behaves.

    • locales: An array of available languages, ordered by fallback priority. Defaults to ['zh-CN', 'en-US', 'fr-FR', 'ja-JP', 'de-DE', 'ru-RU'].
    • output: Determines the language preference for output.
      • 'prefer-user': Prioritize the user's language.
      • 'prefer-channel': Prioritize the channel's language (Default).

  10. Configure Commander prefix settings

    master

    The Commander class can be configured with prefix settings to control how commands are triggered.

    Config Options:

    • prefix (optional): A Computed<string | string[]> defining the command prefixes (e.g., !, ?, or /).
    • prefixMode (optional):
      • 'auto': Default behavior.
      • 'strict': Requires the prefix to be present for commands to be interpreted in certain contexts (like non-direct messages).

  11. Configure the Help plugin

    master

    The help plugin provides command usage and help information. You can configure it using the following options:

    • shortcut (boolean, default: true): Enables shortcut calls for the help command (e.g., fuzzy matching).
    • options (boolean, default: true): Automatically adds a -h, --help option to every command in the system.
    export const Config: Schema<Config> = Schema.object({
  shortcut: Schema.boolean().default(true).description('是否启用快捷调用。'),
  options: Schema.boolean().default(true).description('是否为每个指令添加 `-h, --help` 选项。
})

  12. Configure Koishi Context settings

    master

    The Context.Config interface defines the configuration schema for the Koishi instance. It is divided into several namespaces:

    Basic Configuration (Basic)

    • prefix: string[] - Array of command prefix characters.
    • prefixMode: 'auto' | 'strict' - 'auto' allows triggering without a prefix when a mention is present; 'strict' requires the prefix.
    • nickname: string[] - Array of bot nicknames used for matching.
    • autoAssign: boolean - If true, uses the receiver as the handler when channel data is unavailable.
    • autoAuthorize: number - Default permission level when user data is unavailable.
    • minSimilarity: number (0 to 1) - Threshold for fuzzy matching commands.

    Delay Configuration (Delay)

    Controls delays for various asynchronous operations:

    • character: Minimum delay between messages in session.sendQueued(), calculated by character count.
    • message: Fixed minimum delay between messages in session.sendQueued().
    • cancel: Delay for session.cancelQueued().
    • broadcast: Default delay for bot.broadcast().
    • prompt: Default waiting time for session.prompt().

    Advanced Configuration (Advanced)

    • maxListeners: number - Maximum number of listeners per event type before a memory leak warning is issued.