NoneBot Plugin Alconna

The uniseg module provides a set of universal message components for building cross-platform messages that work across different adapters.

Universal Segments

You can use these segments in Alconna definitions or UniMessage construction:

• Text(text: str)
• At(type: Literal["user", "role", "channel"], target: str)
• AtAll()
• Emoji(id: str, name: Optional[str])
• Image(url, id, path, raw)
• Audio, Voice, Video, File, Reply, Reference, Card, Other

Using UniMessage

UniMessage is a sequence of universal segments. It can be used to:

• Receive messages: Use UniMsg dependency injection to get a UniMessage from an event.
• Send messages: Use UniMessage.send() or UniMessage.export() to convert to adapter-specific segments.
• Chain messages: Use .text(), .at(), .image() for fluent construction, or use + to concatenate strings, segments, and other UniMessage objects.
• Use Templates: UniMessage.template supports standard formatting and special {:XXX} syntax for segments like {:At(user, target)}.

Special Template Syntax in AlconnaMatcher

In AlconnaMatcher, the {:XXX} syntax can access $event and $bot attributes (e.g., {:At(user, $event.get_user_id())}). It also supports $message_id and $target.

Checking and Iterating

• Check existence: At(...) in message or message.has(At).
• Check exclusivity: message.only(Text).
• Filter: message.include(Text, At) or message.exclude(Reply).
• Indexing/Slicing: Supports type-based indexing like message[At, 0] or message[Text, 0:2].
• Extraction: message.extract_plain_text() returns the plain text string.

from nonebot_plugin_alconna.uniseg import UniMsg, At, Reply

@matcher.handle()
async def _(msg: UniMsg):
    reply = msg[Reply, 0]
    if msg.has(At):
        ats = msg.get(At)
        print(ats)

# Sending cross-platform
await test.send(await UniMessage(Image(path="path/to/img")).export())

# Fluent construction
msg = UniMessage.text("Hello").at("124").image(path="/path/to/img")

A Command Header is the combination of a Prefix and a Command name. Alconna supports various header types:

Note: Regex only works on the command name; regex in the prefix is escaped. For a more concise way to use regex, use Bracket Headers.

The plugin provides UniMessage for constructing cross-platform messages and Target for sending messages to specific entities (like groups or users) regardless of the underlying adapter. You can use SupportScope to specify the platform scope for active messaging.

To send an image to a specific group actively:

1. Use Target.group(group_id, scope) to define the destination.
2. Use .send() on the target with a UniMessage object.

To handle message recall:

• Use message_recall() within a handler to trigger recall logic.
• When sending a message via UniMessage.send(), the returned object may have a .recallable attribute and a .recall(delay=..., index=...) method.

from nonebot import get_driver
from nonebot_plugin_alconna import Target, UniMessage, SupportScope, on_alconna, message_recall

driver = get_driver()
test = on_alconna("test")

@test.handle()
async def handle_test():
    # Sending an image and handling recall
    r = await UniMessage.image(path="path/to/img").send()
    if r.recallable:
        await r.reply("图片已发送，10秒后撤回")
        await r.recall(delay=10, index=0)

@test.got("foo", prompt=UniMessage.template("{:Reply($message_id)}请输入图片"))
async def handle_foo():
    # Using message_recall to trigger recall in a handler
    await test.send("图片已收到, 即将撤回")
    await message_recall()

@driver.on_startup
async def _():
    # Active sending to a group using Target
    await Target.group("123456789", SupportScope.qq_client).send(UniMessage.image(path="test.png"))

The Extension class is the base for customizing how Alconna interacts with NoneBot. By subclassing Extension, you can override specific lifecycle hooks to modify message handling, permission checks, context provision, or dependency injection.

Extensions are executed in order of their priority property. When multiple extensions override the same method, they are processed according to the internal ExtensionExecutor logic (e.g., some methods like receive_wrapper or send_wrapper act as a chain, while others like message_provider or output_converter return the first non-None/non-empty result).

from nonebot_plugin_alconna.extension import Extension

class MyCustomExtension(Extension):
    @property
    def priority(self) -> int:
        return 10

    @property
    def id(self) -> str:
        return "my_custom_ext"

    async def permission_check(self, bot, event, medium) -> bool:
        # Custom logic to allow/deny commands
        return True

    async def send_wrapper(self, bot, event, send) -> str | Message | UniMessage:
        # Modify the message before it is sent
        return send

You can configure the global behavior of the plugin using the following environment variables:

Namespaces allow you to group Alconna settings (like prefixes, separators, and formatters). By default, Alconna uses the "Alconna" namespace.

Creating and using a Namespace

You can create a custom Namespace and assign it to an Alconna instance, or use a context manager to apply settings to all commands created within that block.

from arclet.alconna import Alconna, namespace, Namespace, config

# Create a namespace that requires a '/' prefix
ns = Namespace("foo", prefixes=["/"])

# Use the namespace in Alconna
alc = Alconna("pip", namespace=ns)

# Or use a context manager to inject settings into all commands in the block
with namespace("bar") as np1:
    np1.prefixes = ["!"]
    # Commands created here will use the 'bar' namespace

Managing Namespaces

• Global Config: Use config.namespaces["name"] = ns to register a namespace.
• Default Namespace: Modify config.default_namespace to change settings for all commands without an explicit namespace.

from arclet.alconna import Alconna, namespace, Namespace, config

ns = Namespace("foo", prefixes=["/"])

alc = Alconna("pip", Subcommand("install", Args["package", str]), namespace=ns)

with namespace("bar") as np1:
    np1.prefixes = ["!"]
    np1.formatter_type = ShellTextFormatter
    np1.builtin_option_name["help"] = {"帮助", "-h"}

config.namespaces["foo"] = ns