https://github.com/nonebot/plugin-alconna
强大的 Nonebot2 命令匹配拓展，支持富文本/多媒体解析，跨平台消息收发
https://github.com/nonebot/plugin-alconna
Last synced: about 2 months ago
JSON representation
强大的 Nonebot2 命令匹配拓展，支持富文本/多媒体解析，跨平台消息收发
- Host: GitHub
- URL: https://github.com/nonebot/plugin-alconna
- Owner: nonebot
- License: mit
- Created: 2023-07-21T10:20:08.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-12-18T16:09:20.000Z (3 months ago)
- Last Synced: 2025-12-20T20:14:18.050Z (3 months ago)
- Language: Python
- Homepage: https://nonebot.dev/docs/next/best-practice/alconna
- Size: 2.14 MB
- Stars: 130
- Watchers: 3
- Forks: 22
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# NoneBot Plugin Alconna
_✨ Alconna Usage For NoneBot2 ✨_
_✨ All Receive in One, And One Send All ✨_
该插件提供了 [Alconna](https://github.com/ArcletProject/Alconna) 的 [NoneBot2](https://github.com/nonebot/nonebot2) 适配版本与工具
## 特性
- 完整的 Alconna 特性支持
- 自动回复命令帮助信息选项
- 跨平台的接收与发送消息(被动+主动)
- 对**22种适配器**的收发消息支持
- 比 `got-reject` 更强大的补全会话机制
- 多种内置插件 (echo，help，lang)
- i18n 支持
## 讨论
QQ 交流群: [链接](https://jq.qq.com/?_wv=1027&k=PUPOnCSH)
## 使用方法
NoneBot 文档: [📖这里](https://nonebot.dev/docs/next/best-practice/alconna/)
仓库内介绍: [📦这里](/docs.md)
## 跨平台消息
```python
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():
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():
await test.send("图片已收到, 即将撤回")
await message_recall()
@driver.on_startup
async def _():
await Target.group("123456789", SupportScope.qq_client).send(UniMessage.image(path="test.png"))
```
## 支持情况
### 支持的适配器
| 协议名称 | 路径 |
|------------------------------------------------------------------------|--------------------------------------|
| [OneBot 协议](https://onebot.dev/) | adapters.onebot11, adapters.onebot12 |
| [Telegram](https://core.telegram.org/bots/api) | adapters.telegram |
| [飞书](https://open.feishu.cn/document/home/index) | adapters.feishu |
| [GitHub](https://docs.github.com/en/developers/apps) | adapters.github |
| [QQ bot](https://github.com/nonebot/adapter-qq) | adapters.qq |
| [钉钉](https://open.dingtalk.com/document/) | adapters.ding |
| [Console](https://github.com/nonebot/adapter-console) | adapters.console |
| [开黑啦](https://developer.kookapp.cn/) | adapters.kook |
| [Mirai](https://docs.mirai.mamoe.net/mirai-api-http/) | adapters.mirai |
| [Ntchat](https://github.com/JustUndertaker/adapter-ntchat) | adapters.ntchat |
| [MineCraft](https://github.com/17TheWord/nonebot-adapter-minecraft) | adapters.minecraft |
| [Walle-Q](https://github.com/onebot-walle/nonebot_adapter_walleq) | adapters.onebot12 |
| [Discord](https://github.com/nonebot/adapter-discord) | adapters.discord |
| [Red 协议](https://github.com/nonebot/adapter-red) | adapters.red |
| [Satori](https://github.com/nonebot/adapter-satori) | adapters.satori |
| [Dodo IM](https://github.com/nonebot/adapter-dodo) | adapters.dodo |
| [Kritor](https://github.com/nonebot/adapter-kritor) | adapters.kritor |
| [Tailchat](https://github.com/eya46/nonebot-adapter-tailchat) | adapters.tailchat |
| [Mail](https://github.com/mobyw/nonebot-adapter-mail) | adapters.mail |
| [微信公众号](https://github.com/YangRucheng/nonebot-adapter-wxmp) | adapters.wxmp |
| [黑盒语音](https://github.com/lclbm/adapter-heybox) | adapters.heybox |
| [Milky](https://github.com/nonebot/adapter-milky) | adapters.milky |
| [EFChat](https://github.com/molanp/nonebot_adapter_efchat) | adapters.efchat |
| [B站直播间](https://github.com/MingxuanGame/nonebot-adapter-bilibili-live) | adapters.bililive | |
### 支持的消息元素
- ✅: 支持(接收和发送)
- ⬇️: 支持接收
- ⬆️: 支持发送
- ➖: 情况不存在
- ❌: 插件/适配器未支持
- 🚫: 协议未支持
- (🚧): 计划中或部分支持或为实验性支持
> [!WARNING]
> 斜体的协议名称意味着其协议或其适配器长时间未维护或已失效
| 元素\适配器 | OneBot V11 | OneBot V12 | Telegram | 飞书 | Github | QQ-API | _钉钉_ | Console | 开黑啦 | Mirai | _Ntchat_ | MineCraft | Discord | _Red_ | Satori | Dodo IM | _Kritor_ | Tailchat | Mail | 微信公众号 | 黑盒语音 | Milky | EFChat | B站直播间 |
|------------------|------------|------------|----------|----|--------|--------|------|---------|-----|-------|----------|-----------|---------|-------|--------|---------|----------|----------|------|-------|------|-------|--------|-------|
| 文本 Text | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 样式文本 Styled Text | 🚫 | 🚫 | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ✅ | 🚫 | 🚫 | 🚫 | ❌ | 🚫 |
| 提及用户 At(user) | ✅ | ✅ | ✅ | ✅ | ⬆️ | ✅ | ✅ | 🚫 | ✅ | ✅ | ❌ | 🚫 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⬆️ | 🚫 | ⬆️ | ✅ | ✅ | ✅ |
| 提及角色 At(role) | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | ✅ | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| 提及频道 At(channel) | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | ✅ | ✅ | 🚫 | ✅ | ⬆️ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| 提及全体 AtAll | ✅ | ✅ | 🚫 | ✅ | 🚫 | ✅ | ✅ | 🚫 | ✅ | ✅ | 🚫 | 🚫 | ✅ | ✅ | ✅ | ✅ | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 |
| 表情 Emoji | ✅ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | 🚫 | ✅ | ✅ | ✅ | 🚫 | 🚫 | ✅ | ✅ | 🚫 | 🚫 | ✅ | ✅ | 🚫 | ✅ | 🚫 | ✅ | 🚫 | ✅ |
| 图片 Image | ✅ | ✅ | ✅ | ✅ | ⬆️ | ✅ | ✅ | 🚫 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⬆️ | ✅ | ✅ | 🚫 |
| 音频 Audio | ⬆️ | ✅ | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ⬆️ | ⬇️ | 🚫 | ⬆️ | ⬆️ | ✅ | 🚫 | ⬆️ | 🚫 | ✅ | ✅ | 🚫 | ⬆️ | ⬆️ | 🚫 |
| 语音 Voice | ✅ | ✅ | ✅ | ⬆️ | 🚫 | ⬆️ | 🚫 | 🚫 | ⬆️ | ✅ | ⬇️ | 🚫 | ⬆️ | ✅ | ⬆️ | 🚫 | ✅ | 🚫 | ✅ | ✅ | 🚫 | ✅ | ✅ | 🚫 |
| 视频 Video | ✅ | ✅ | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ✅ | ✅ | 🚫 | ⬆️ | ✅ | ✅ | ✅ | ✅ | 🚫 | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 |
| 文件 File | ⬇️,⬆️(🚧) | ✅ | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ✅ | ✅ | 🚫 | ⬆️ | ✅ | ✅ | ⬇️ | ⬇️ | ✅ | ✅ | 🚫 | 🚫 | ⬆️ | 🚫 | 🚫 |
| 回复 Reply | ✅ | ✅ | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ✅ | ✅ | 🚫 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚫 | ⬆️ | ✅ | ⬆️ | ⬆️ |
| 引用转发 Reference | ✅ | 🚫 | 🚫 | ❌ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | ✅ | ✅ | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 |
| 超级消息 Hyper | ✅ | 🚫 | 🚫 | ⬇️ | 🚫 | ✅ | 🚫 | 🚫 | ✅ | ✅ | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | ✅ | 🚫 | ⬇️ | 🚫 | 🚫 |
| 按钮 Button | 🚫 | 🚫 | ⬆️ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | ⬆️ | ✅ | 🚫 | ✅ | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| 其余 Other | ✅ | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ➖ | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ | ✅ | ➖ | ✅ | ➖ | ➖ |
### 支持的消息操作
- ✅: 支持
- ❌: 插件/适配器未支持
- 🚫: 协议未支持
- (🚧): 计划中或部分支持或为实验性支持
> [!WARNING]
> 斜体的协议名称意味着其协议或其适配器长时间未维护或已失效
| 操作\适配器 | OneBot V11 | OneBot V12 | Telegram | 飞书 | Github | QQ-API | _钉钉_ | Console | 开黑啦 | Mirai | _Ntchat_ | MineCraft | Discord | _Red_ | Satori | Dodo IM | _Kritor_ | Tailchat | Mail | 微信公众号 | 黑盒语音 | Milky | EFChat | B站直播间 |
|---------------|------------|------------|----------|----|--------|--------|------|---------|-----|-------|----------|-----------|---------|-------|--------|---------|----------|----------|------|-------|------|-------|--------|-------|
| 发送 Send | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 撤回 Recall | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | 🚫 | ✅ | ✅ | ❌ | 🚫 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 |
| 编辑 Edit | 🚫 | 🚫 | ✅ | ✅ | ❌ | 🚫 | ❌ | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | ✅ | ✅ | 🚫 | 🚫 | ❌ | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| 表情响应 Reaction | ✅(🚧) | 🚫 | ✅ | ✅ | ❌ | ✅ | 🚫 | 🚫 | ✅ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | ✅ | ✅ | ✅ | ❌ | 🚫 | 🚫 | 🚫 | ✅ | 🚫 | 🚫 |
## 配置项
- ALCONNA_AUTO_SEND_OUTPUT : 是否全局启用输出信息自动发送
- ALCONNA_USE_COMMAND_START : 是否将 COMMAND_START 作为全局命令前缀
- ALCONNA_GLOBAL_COMPLETION: 全局的补全会话配置 (不代表全局启用补全会话)
- ALCONNA_USE_ORIGIN: 是否全局使用原始消息 (即未经过 to_me 等处理的)
- ALCONNA_USE_PARAM: 是否使用特制的 Param 提供更好的依赖注入
- ALCONNA_USE_CMD_SEP: 是否将 COMMAND_SEP 作为全局命令分隔符
- ALCONNA_GLOBAL_EXTENSIONS: 全局加载的扩展, 路径以 . 分隔, 如 foo.bar.baz:DemoExtension
- ALCONNA_CONTEXT_STYLE: 全局命令上下文插值的风格，None 为关闭，bracket 为 {...}，parentheses 为 $(...)
- ALCONNA_ENABLE_SAA_PATCH: 是否启用 SAA 补丁
- ALCONNA_APPLY_FILEHOST: 是否启用文件托管
- ALCONNA_APPLY_FETCH_TARGETS: 是否启动时拉取一次发送对象列表
- ALCONNA_BUILTIN_PLUGINS: 需要加载的alc内置插件集合
- ALCONNA_CONFLICT_RESOLVER: 命令冲突解决策略，default 为保留两个命令，raise 为抛出异常，ignore 为忽略新命令，replace 为替换旧命令
- ALCONNA_RESPONSE_SELF: 是否允许响应自己的消息
- ALCONNA_CACHE_MESSAGE: 是否缓存消息
## 插件示例
[demo bot](./example/plugins/demo.py)
```python
# echo 插件
from nonebot_plugin_alconna import UniMessage, Command
@Command("echo <...content>").build(auto_send_output=True).handle()
async def _(content: UniMessage):
await content.finish()
```