ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2025-07-28 08:41:29 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 Docs: 更新最佳实践 Alconna 章节 (#3447)

Browse Source
This commit is contained in:
Tarrailt
2025-04-16 17:19:38 +08:00
committed by GitHub
parent a338d71f1d
commit a8549140c5
14 changed files with 2193 additions and 976 deletions
Download Patch File Download Diff File Expand all files Collapse all files

715
website/docs/best-practice/alconna/matcher.mdx
View File

@ -4,136 +4,133 @@ description: 响应规则的使用
---
import Messenger from "@site/src/components/Messenger";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
# Alconna 插件
# `on_alconna` 响应器
展示：
`nonebot_plugin_alconna` 插件本体的大部分功能都围绕着 `on_alconna` 响应器展开。
该响应器类似于 `on_command`，基于 `Alconna` 解析器来解析命令。
以下是一个简单的 `on_alconna` 响应器的例子：
```python
from nonebot_plugin_alconna import At, Image, on_alconna
from arclet.alconna import Args, Option, Alconna, Arparma, MultiVar, Subcommand
from nonebot_plugin_alconna import At, Image, Match, on_alconna
from arclet.alconna import Args, Option, Alconna, MultiVar, Subcommand
alc = Alconna(
["/", "!"],
"role-group",
Subcommand(
"add",
"add|添加",
Args["name", str],
Option("member", Args["target", MultiVar(At)]),
dest="add",
compact=True,
),
Option("list"),
Option("icon", Args["icon", Image])
)
rg = on_alconna(alc, auto_send_output=True)
rg = on_alconna(alc, use_command_start=True, aliases={"角色组"})
@rg.handle()
async def _(result: Arparma):
if result.find("list"):
img: bytes = await gen_role_group_list_image()
await rg.finish(Image(raw=img))
if result.find("add"):
group = await create_role_group(result.query[str]("add.name"))
if result.find("add.member"):
ats = result.query[tuple[At, ...]]("add.member.target")
group.extend(member.target for member in ats)
await rg.finish("添加成功")
@rg.assign("list")
async def list_role_group():
img: bytes = await gen_role_group_list_image()
await rg.finish(Image(raw=img))
@rg.assign("add")
async def _(name: str, target: Match[tuple[At, ...]]):
group = await create_role_group(name)
if target.available:
ats: tuple[At, ...] = target.result
group.extend(member.target for member in ats)
await rg.finish("添加成功")
```
## 响应器使用
<Messenger
msgs={[
{ position: "right", msg: "/role-group list" },
{
position: "left",
msg: "[图片]",
},
{ position: "right", msg: "/角色组 添加foo @bar @baz" },
{ position: "left", msg: "添加成功" },
]}
/>
本插件基于 **Alconna**，为 **Nonebot** 提供了一类新的事件响应器辅助函数 `on_alconna`：
## 声明
`on_alconna` 的参数如下:
```python
def on_alconna(
command: Alconna | str,
rule: Rule | T_RuleChecker | None = None,
skip_for_unmatch: bool = True,
auto_send_output: bool = False,
aliases: set[str | tuple[str, ...]] | None = None,
auto_send_output: bool | None = None,
aliases: set[str] | tuple[str, ...] | None = None,
comp_config: CompConfig | None = None,
extensions: list[type[Extension] | Extension] | None = None,
exclude_ext: list[type[Extension] | str] | None = None,
use_origin: bool = False,
use_cmd_start: bool = False,
use_cmd_sep: bool = False,
**kwargs,
...,
):
use_origin: bool | None = None,
use_cmd_start: bool | None = None,
use_cmd_sep: bool | None = None,
response_self: bool | None = None,
**kwargs: Any,
) -> type[AlconnaMatcher]:
...
```
- `command`: Alconna 命令或字符串，字符串将通过 `AlconnaFormat` 转换为 Alconna 命令
- `skip_for_unmatch`: 是否在命令不匹配时跳过该响应
- `auto_send_output`: 是否自动发送输出信息并跳过响应
- `rule`: 事件响应规则， 详见 [响应器规则](../../advanced/matcher.md#事件响应规则)
- `skip_for_unmatch`: 是否在命令不匹配时跳过该响应, 默认为 `True`
- `auto_send_output`: 是否自动发送输出信息并跳过该响应。
- `True`：自动发送输出信息并跳过该响应
- `False`：不自动发送输出信息，而是传递进行处理
- `None`：跟随全局配置项 `alconna_auto_send_output`，默认值为 `True`
- `aliases`: 命令别名， 作用类似于 `on_command` 中的 aliases
- `comp_config`: 补全会话配置， 不传入则不启用补全会话
- `extensions`: 需要加载的匹配扩展, 可以是扩展类或扩展实例
- `exclude_ext`: 需要排除的匹配扩展, 可以是扩展类或扩展的id
- `use_origin`: 是否使用未经 to_me 等处理过的消息
- `use_cmd_start`: 是否使用 COMMAND_START 作为命令前缀
- `use_cmd_sep`: 是否使用 COMMAND_SEP 作为命令分隔符
- `use_origin`: 是否使用未经 to_me 等处理过的消息。`None` 时跟随全局配置项 `alconna_use_origin`，默认值为 `False`
- `use_cmd_start`: 是否使用 COMMAND_START 作为命令前缀。`None` 时跟随全局配置项 `alconna_use_command_start`，默认值为 `False`
- `use_cmd_sep`: 是否使用 COMMAND_SEP 作为命令分隔符。`None` 时跟随全局配置项 `alconna_use_command_sep`，默认值为 `False`
- `response_self`: 是否响应自身消息。`None` 时跟随全局配置项 `alconna_response_self`，默认值为 `False`
`on_alconna` 返回的是 `Matcher` 的子类 `AlconnaMatcher` ，其拓展了如下方法：
- `.assign(path, value, or_not)`: 用于对包含多个选项/子命令的命令的分派处理（具体请看[条件控制](./matcher.mdx#条件控制)）
- `.got_path(path, prompt, middleware)`: 在 `got` 方法的基础上，会以 path 对应的参数为准，读取传入 message 的最后一个消息段并验证转换
- `.set_path_arg(key, value)`, `.get_path_arg(key)`: 类似 `set_arg` 和 `got_arg`，为 `got_path` 的特化版本
- `.reject_path(path[, prompt, fallback])`: 类似于 `reject_arg`，对应 `got_path`
- `.assign(path, value, or_not)`: 用于对包含多个选项/子命令的命令的分派处理
- `.dispatch`: 同样的分派处理，但是是类似 `CommandGroup` 一样返回新的 `AlconnaMatcher`
- `.got_path(path, prompt, middleware)`: 在 `got` 方法的基础上，会以 path 对应的参数为准，读取传入 message 的最后一个消息段并验证转换
- `.got`, `send`, `reject`, ... : 拓展了 prompt 类型，即支持使用 `UniMessage` 作为 prompt
- ...
实例：
```python
from nonebot import require
require("nonebot_plugin_alconna")
from arclet.alconna import Alconna, Option, Args
from nonebot_plugin_alconna import on_alconna, Match, UniMessage
login = on_alconna(Alconna(["/"], "login", Args["password?", str], Option("-r|--recall"))) # 这里["/"]指命令前缀必须是/
# /login -r 触发
@login.assign("recall")
async def login_exit():
await login.finish("已退出")
# /login xxx 触发
@login.assign("password")
async def login_handle(pw: Match[str]):
if pw.available:
login.set_path_arg("password", pw.result)
# /login 触发
@login.got_path("password", prompt=UniMessage.template("{:At(user, $event.get_user_id())} 请输入密码"))
async def login_got(password: str):
assert password
await login.send("登录成功")
```
除了标准的创建方式，本插件也提供了 `funcommand` 和 `Command` 两种快捷方式来创建 `AlconnaMatcher`， 详见 [快捷方式](./shortcut.md)。
## 依赖注入
本插件提供了一系列依赖注入函数，便于在响应函数中获取解析结果：
`AlconnaMatcher` 的特性之一是拓展了依赖注入的功能。
- `AlconnaResult`: `CommandResult` 类型的依赖注入函数
- `AlconnaMatches`: `Arparma` 类型的依赖注入函数
- `AlconnaDuplication`: `Duplication` 类型的依赖注入函数
- `AlconnaMatch`: `Match` 类型的依赖注入函数
- `AlconnaQuery`: `Query` 类型的依赖注入函数
### 注入模型
同时，基于 [`Annotated` 支持](https://github.com/nonebot/nonebot2/pull/1832)，添加了两类注解：
插件提供了几种用来处理解析结果的模型：
- `AlcMatches`：同 `AlconnaMatches`
- `AlcResult`：同 `AlconnaResult`
可以看到，本插件提供了几类额外的模型：
- `CommandResult`: 解析结果，包括了源命令 `source: Alconna` ，解析结果 `result: Arparma`，以及可能的输出信息 `output: str | None` 字段
- `Match`: 匹配项，表示参数是否存在于 `all_matched_args` 内，可用 `Match.available` 判断是否匹配，`Match.result` 获取匹配的值
- `CommandResult`: 用于快捷访问命令解析结果
- `result (Arparma)`: 解析结果
- `source (Alconna)`: 源命令
- `matched (bool)`: 是否匹配
- `context (dict)`: 命令的上下文
- `output (str | None)`: 命令的输出
- `Match`: 匹配项，表示参数是否存在于 `Arparma.all_matched_args` 内，可用 `Match.available` 判断是否匹配，`Match.result` 获取匹配的值
- `Match` 只能查找到 `Arparma.all_matched_args` 中的参数。对于特定选项/子命令的参数，需要使用 `Query` 来查询
- `Query`: 查询项，表示参数是否可由 `Arparma.query` 查询并获得结果，可用 `Query.available` 判断是否查询成功，`Query.result` 获取查询结果
- `Query` 除了查询参数，也可以查询某个选项/子命令是否存在
**Alconna** 默认依赖注入的目标参数皆不需要使用依赖注入函数， 该效果对于 `AlconnaMatcher.got_path` 下的 Arg 同样有效：
### 编写
```python
async def handle(
@ -141,13 +138,32 @@ async def handle(
arp: Arparma,
dup: Duplication,
source: Alconna,
abc: str, # 类似 Match, 但是若匹配结果不存在对应字段则跳过该 handler
ext: Extension,
exts: SelectedExtensions,
abc: str,
foo: Match[str],
bar: Query[int] = Query("ttt.bar", 0) # Query 仍然需要一个默认值来传递 path 参数
bar: Query[int] = Query("ttt.bar", 0)
):
...
```
`AlconnaMatcher` 的依赖注入拓展支持以下情况：
- `xxx: CommandResult`
- `xxx: Arparma`：命令的[解析结果](./command.md#解析结果)
- `xxx: Duplication`：命令的解析结果的 [`Duplication`](./command.md#Duplication)
- `xxx: Alconna`：命令的源命令
- `<key>: Match[<type>]`：上述的匹配项，使用 `key` 作为查询路径
- `xxx: Query[<type>] = Query(<path>, default)`：上述的查询项，必需声明默认值以设置查询路径 `path`
- 当用来查询选项/子命令是否存在时，可不写 `Query[<type>]`
- `xxx: Extension`：当前 `AlconnaMatcher` 使用的指定类型的匹配扩展
- `xxx: SelectedExtensions`：当前 `AlconnaMatcher` 使用的所有可用的匹配扩展
- `<key>: <type>`: 其他情况
- 当 `key` 的名称是 "ctx" 或 "context" 并且类型为 `dict` 时，会注入命令的上下文
- 当 `key` 存在于命令的上下文中时，会注入对应的值
- 当 `key` 存在于 `Arparma` 的 `all_matched_args` 中时，会注入对应的值, 类似于 `Match` 的用法，但当该值不存在时将跳过响应器。
- 当 `key` 属于 `got_path` 的参数时，会注入对应的值
- 当 `key` 被某个 `Extension.before_catch` 确认为需要注入的参数时，会调用 `Extension.catch` 来注入对应的值
:::note
如果你更喜欢 Depends 式的依赖注入，`nonebot_plugin_alconna` 同时提供了一系列的依赖注入函数，他们包括：
@ -162,19 +178,13 @@ async def handle(
:::
实例:
示例：
```python
from nonebot import require
require("nonebot_plugin_alconna")
from nonebot_plugin_alconna import (
on_alconna,
Match,
Query,
AlconnaMatch,
AlcResult
)
from nonebot_plugin_alconna import AlconnaQuery, AlcResult, Match, Query, on_alconna
from arclet.alconna import Alconna, Args, Option, Arparma
@ -183,8 +193,7 @@ test = on_alconna(
"test",
Option("foo", Args["bar", int]),
Option("baz", Args["qux", bool, False])
),
auto_send_output=True
)
)
@test.handle()
@ -198,99 +207,100 @@ async def handle_test2(result: Arparma):
await test.send(f"args: {result.all_matched_args}")
@test.handle()
async def handle_test3(bar: Match[int] = AlconnaMatch("bar")):
async def handle_test3(bar: Match[int]):
if bar.available:
await test.send(f"foo={bar.result}")
@test.handle()
async def handle_test4(qux: Query[bool] = Query("baz.qux", False)):
async def handle_test4(qux: Query[bool] = AlconnaQuery("baz.qux", False)):
if qux.available:
await test.send(f"baz.qux={qux.result}")
```
## 多平台适配
本插件提供了通用消息段标注， 通用消息段序列， 使插件使用者可以忽略平台之间字段的差异
响应器使用示例中使用了消息段标注，其中 `At` 属于通用标注，而 `Image` 属于 `onebot12` 适配器下的标注。
具体介绍和使用请查看 [通用信息组件](./uniseg.mdx#通用消息段)
本插件为以下适配器提供了专门的适配器标注：
| 协议名称 | 路径 |
| ------------------------------------------------------------------- | ------------------------------------ |
| [OneBot 协议](https://github.com/nonebot/adapter-onebot) | adapters.onebot11, adapters.onebot12 |
| [Telegram](https://github.com/nonebot/adapter-telegram) | adapters.telegram |
| [飞书](https://github.com/nonebot/adapter-feishu) | adapters.feishu |
| [GitHub](https://github.com/nonebot/adapter-github) | adapters.github |
| [QQ bot](https://github.com/nonebot/adapter-qq) | adapters.qq |
| [钉钉](https://github.com/nonebot/adapter-ding) | adapters.ding |
| [Dodo](https://github.com/nonebot/adapter-dodo) | adapters.dodo |
| [Console](https://github.com/nonebot/adapter-console) | adapters.console |
| [开黑啦](https://github.com/Tian-que/nonebot-adapter-kaiheila) | adapters.kook |
| [Mirai](https://github.com/ieew/nonebot_adapter_mirai2) | adapters.mirai |
| [Ntchat](https://github.com/JustUndertaker/adapter-ntchat) | adapters.ntchat |
| [MineCraft](https://github.com/17TheWord/nonebot-adapter-minecraft) | adapters.minecraft |
| [BiliBili Live](https://github.com/wwweww/adapter-bilibili) | adapters.bilibili |
| [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 |
## 条件控制
本插件可以通过 `assign` 来控制一个具体的响应函数是否在不满足条件时跳过响应。
### `assign` 方法
`AlconnaMatcher` 的 `assign` 方法与 `handle` 类似，但是可以控制响应函数是否在不满足条件时跳过响应。
`assign` 方法的参数如下：
```python
...
from nonebot import require
require("nonebot_plugin_alconna")
...
from arclet.alconna import Alconna, Subcommand, Option, Args
from nonebot_plugin_alconna import on_alconna, CommandResult
pip = Alconna(
"pip",
Subcommand(
"install", Args["pak", str],
Option("--upgrade"),
Option("--force-reinstall")
),
Subcommand("list", Option("--out-dated"))
)
pip_cmd = on_alconna(pip)
# 仅在命令为 `pip install pip` 时响应
@pip_cmd.assign("install.pak", "pip")
async def update(res: CommandResult):
...
# 仅在命令为 `pip list` 时响应
@pip_cmd.assign("list")
async def list_(res: CommandResult):
...
# 在命令为 `pip install xxx` 时响应
@pip_cmd.assign("install")
async def install(res: CommandResult):
def assign(
cls,
path: str,
value: Any = _seminal,
or_not: bool = False,
additional: CHECK | None = None,
parameterless: Iterable[Any] | None = None,
):
...
```
此外，使用 `AlconnaMatcher.dispatch` 还能像 `CommandGroup` 一样为每个分发设置独立的 matcher：
- `path`: 指定的[查询路径](./command.md#路径查询)
- "$main" 表示没有任何选项/子命令匹配的时候
- "\~XX" 时会把 "\~" 替换为父级路径
- `value`: 可能的指定查询值
- `or_not`: 是否同时处理没有查询成功的情况
- `additional`: 额外的条件检查函数
例如：
```python
update_cmd = pip_cmd.dispatch("install.pak", "pip")
# 处理没有任何选项/子命令匹配的情况
@rg.assign("$main")
async def handle_main(): ...
@update_cmd.handle()
async def update(arp: CommandResult):
...
# 处理 list 选项
@rg.assign("list")
async def handle_list(): ...
# 处理 add 选项，且 name 为 admin
@rg.assign("add.name", "admin")
async def handle_add_admin(): ...
```
另外，`AlconnaMatcher` 有类似于 `got` 的 `got_path`：
### `dispatch` 方法
此外，使用 `.dispatch` 还能像 `CommandGroup` 一样为每个分发设置独立的 matcher：
```python
rg_list_cmd = rg.dispatch("list")
@rg_list_cmd.handle()
async def handle_list(): ...
```
`dispatch` 的参数与 `assign` 相同。
当使用 `dispatch` 时，父级路径表示为传入 `dispatch` 的 `path`:
```python
rg_add_cmd = rg.dispatch("add")
# 此时 ~name 表示 add.name
@rg_add_cmd.assign("~name", "admin")
async def handle_add_admin(): ...
```
:::tip
在 `dispatch` 下, `Query` 的 `path` 也同样支持 `~` 前缀来表示父级路径
```python
@rg_add_cmd.assign("~name", "admin")
async def handle_add_admin(target: Query[tuple[At, ...]] = Query("~target")):
if target.available:
await rg.send(f"添加成功: {target.result}")
```
:::
### `got_path` 方法
另外，`AlconnaMatcher` 有类似于 [`got`](../../appendices/session-control.mdx#got) 的 `got_path` 与配套的 `get_path_arg`, `set_path_arg`：
```python
from nonebot_plugin_alconna import At, Match, UniMessage, on_alconna
@ -312,95 +322,27 @@ async def tt(target: Union[str, At]):
`got_path` 会获取消息的最后一个消息段并转为 path 对应的类型，例如示例中 `target` 对应的 Arg 里要求 str 或 At，则 got 后用户输入的消息只有为 text 或 at 才能进入处理函数。
:::tip
`got_path` 中可以使用依赖注入函数 `AlconnaArg`, 类似于 [`Arg`](../../advanced/dependency.mdx#arg).
`path` 支持 ~XXX 语法，其会把 ~ 替换为可能的父级路径：
### `prompt` 方法
基于 [`Waiter`](https://github.com/RF-Tar-Railt/nonebot-plugin-waiter) 插件，`AlconnaMatcher` 提供了 `prompt` 方法来实现更灵活的交互式提示。
```python
pip = Alconna(
"pip",
Subcommand(
"install",
Args["pak", str],
Option("--upgrade|-U"),
Option("--force-reinstall"),
),
Subcommand("list", Option("--out-dated")),
)
pipcmd = on_alconna(pip)
pip_install_cmd = pipcmd.dispatch("install")
from nonebot_plugin_alconna import At, Match, UniMessage, on_alconna
@pip_install_cmd.assign("~upgrade")
async def pip1_u(pak: Query[str] = Query("~pak")):
await pip_install_cmd.finish(f"pip upgrading {pak.result}...")
```
test_cmd = on_alconna(Alconna("test", Args["target?", Union[str, At]]))
:::
## 响应器创建装饰
本插件提供了一个 `funcommand` 装饰器, 其用于将一个接受任意参数， 返回 `str` 或 `Message` 或 `MessageSegment` 的函数转换为命令响应器：
```python
from nonebot_plugin_alconna import funcommand
@funcommand()
async def echo(msg: str):
return msg
```
其等同于：
```python
from arclet.alconna import Alconna, Args
from nonebot_plugin_alconna import on_alconna, AlconnaMatch, Match
echo = on_alconna(Alconna("echo", Args["msg", str]))
@echo.handle()
async def echo_exit(msg: Match[str] = AlconnaMatch("msg")):
await echo.finish(msg.result)
```
## 类Koishi构造器
本插件提供了一个 `Command` 构造器，其基于 `arclet.alconna.tools` 中的 `AlconnaString`， 以类似 `Koishi` 中注册命令的方式来构建一个 **AlconnaMatcher** ：
```python
from nonebot_plugin_alconna import Command, Arparma
book = (
Command("book", "测试")
.option("writer", "-w <id:int>")
.option("writer", "--anonymous", {"id": 0})
.usage("book [-w <id:int> | --anonymous]")
.shortcut("测试", {"args": ["--anonymous"]})
.build()
)
@book.handle()
async def _(arp: Arparma):
await book.send(str(arp.options))
```
甚至，你可以设置 `action` 来设定响应行为：
```python
book = (
Command("book", "测试")
.option("writer", "-w <id:int>")
.option("writer", "--anonymous", {"id": 0})
.usage("book [-w <id:int> | --anonymous]")
.shortcut("测试", {"args": ["--anonymous"]})
.action(lambda options: str(options)) # 会自动通过 bot.send 发送
.build()
)
@test_cmd.handle()
async def tt_h(target: Match[Union[str, At]]):
if target.available:
await test_cmd.finish(UniMessage(["ok\n", target]))
resp = await test_cmd.prompt("请输入目标", timeout=30) # 等待 30 秒
if resp is None:
await test_cmd.finish("超时")
await test_cmd.finish(UniMessage(["ok\n", resp[-1]]))
```
## 返回值中间件
@ -411,9 +353,7 @@ book = (
from nonebot_plugin_alconna import image_fetch
mask_cmd = on_alconna(
Alconna("search", Args["img?", Image]),
)
mask_cmd = on_alconna(Alconna("search", Args["img?", Image]))
@mask_cmd.handle()
@ -424,10 +364,105 @@ async def mask_h(matcher: AlconnaMatcher, img: Match[bytes] = AlconnaMatch("img"
其中，`image_fetch` 是一个中间件，其接受一个 `Image` 对象，并提取图片的二进制数据返回。
## i18n
本插件基于 `tarina.lang` 模块提供了 i18n 的支持，参见 [Lang 用法](https://github.com/nonebot/plugin-alconna/discussions/50)。
当你编写完语言文件后，你便可以通过 `AlconnaMatcher.i18n` 来快速地将语言文件中的内容转为 UniMessage.
<Tabs groupId="i18n">
<TabItem value="zh" label="中文">
```yaml title="zh-CN.yml"
# 中文语言文件
demo:
command:
role-group:
add: 添加 {name} 成功!
```
<Messenger
msgs={[
{ position: "right", msg: "/角色组 添加 foo" },
{ position: "left", msg: "添加 foo 成功!" },
]}
/>
</TabItem>
<TabItem value="en" label="英文">
```yaml title="en-US.yml"
# 英文语言文件
demo:
command:
role-group:
add: Add {name} successfully!
```
<Messenger
msgs={[
{ position: "right", msg: "/role-group add foo" },
{ position: "left", msg: "Add foo successfully!" },
]}
/>
</TabItem>
</Tabs>
```python title="使用 i18n"
@rg.assign("add")
async def handle_add(name: str):
await rg.i18n("demo", "command.role-group.add", name=name).finish()
```
## 匹配测试
`AlconnaMatcher.test` 方法允许你在 NoneBot 启动时对命令进行测试。
```python
def test(
cls,
message: str | UniMessage,
expected: dict[str, Any] | None = None,
prefix: bool = True
): ...
```
- `message`: 测试的消息
- `expected`: 预期的解析结果，若为 None 则表示只测试是否匹配
- `prefix`: 是否使用命令前缀，默认为 True
## 匹配拓展
本插件提供了一个 `Extension` 类，其用于自定义 AlconnaMatcher 的部分行为
目前 `Extension` 的功能有：
- `validate`: 对于事件的来源适配器或 bot 选择是否接受响应
- `output_converter`: 输出信息的自定义转换方法
- `message_provider`: 从传入事件中自定义提取消息的方法
- `receive_provider`: 对传入的消息 (UniMessage) 的额外处理
- `context_provider`: 对命令上下文的额外处理
- `permission_check`: 命令对消息解析并确认头部匹配（即确认选择响应）时对发送者的权限判断
- `parse_wrapper`: 对命令解析结果的额外处理
- `send_wrapper`: 对发送的消息 (Message 或 UniMessage) 的额外处理
- `before_catch`: 自定义依赖注入的绑定确认函数
- `catch`: 自定义依赖注入处理函数
- `post_init`: 响应器创建后对命令对象的额外处理
:::tip
Extension 可以通过 `add_global_extension` 方法来全局添加。
```python
from nonebot_plugin_alconna import add_global_extension
from nonebot_plugin_alconna.builtins.extensions.telegram import TelegramSlashExtension
add_global_extension(TelegramSlashExtension)
```
全局的 Extension 可延迟加载 (即若有全局拓展加载于部分 AlconnaMatcher 之后，这部分响应器会被追加拓展)
:::
例如一个 `LLMExtension` 可以如下实现 (仅举例)：
```python
@ -469,59 +504,121 @@ matcher = on_alconna(
那么添加了 `LLMExtension` 的响应器便能接受任何能通过 llm 翻译为具体命令的自然语言消息，同时可以在响应器中为所有 `llm` 参数注入模型变量。
目前 `Extension` 的功能有：
- `validate`: 对于事件的来源适配器或 bot 选择是否接受响应
- `output_converter`: 输出信息的自定义转换方法
- `message_provider`: 从传入事件中自定义提取消息的方法
- `receive_provider`: 对传入的消息 (Message 或 UniMessage) 的额外处理
- `context_provider`: 对命令上下文的额外处理
- `permission_check`: 命令对消息解析并确认头部匹配（即确认选择响应）时对发送者的权限判断
- `parse_wrapper`: 对命令解析结果的额外处理
- `send_wrapper`: 对发送的消息 (Message 或 UniMessage) 的额外处理
- `before_catch`: 自定义依赖注入的绑定确认函数
- `catch`: 自定义依赖注入处理函数
- `post_init`: 响应器创建后对命令对象的额外处理
例如内置的 `DiscordSlashExtension`，其可自动将 Alconna 对象翻译成 slash 指令并注册，且将收到的指令交互事件转为指令供命令解析：
### validate
```python
from nonebot_plugin_alconna import Match, on_alconna
from nonebot_plugin_alconna.builtins.extensions.discord import DiscordSlashExtension
alc = Alconna(
["/"],
"permission",
Subcommand("add", Args["plugin", str]["priority?", int]),
Option("remove", Args["plugin", str]["time?", int]),
meta=CommandMeta(description="权限管理"),
)
matcher = on_alconna(alc, extensions=[DiscordSlashExtension()])
@matcher.assign("add")
async def add(plugin: Match[str], priority: Match[int]):
await matcher.finish(f"added {plugin.result} with {priority.result if priority.available else 0}")
@matcher.assign("remove")
async def remove(plugin: Match[str], time: Match[int]):
await matcher.finish(f"removed {plugin.result} with {time.result if time.available else -1}")
def validate(self, bot: Bot, event: Event) -> bool: ...
```
目前插件提供了 4 个内置的 `Extension`，它们在 `nonebot_plugin_alconna.builtins.extensions` 下：
默认情况下，`validate` 方法会筛选 `event.get_type()` 为 `message` 的情况，表示接受消息事件。
- `ReplyRecordExtension`: 将消息事件中的回复暂存在 extension 中，使得解析用的消息不带回复信息，同时可以在后续的处理中获取回复信息。
- `DiscordSlashExtension`: 将 Alconna 的命令自动转换为 Discord 的 Slash Command，并将 Slash Command 的交互事件转换为消息交给 Alconna 处理。
- `MarkdownOutputExtension`: 将 Alconna 的自动输出转换为 Markdown 格式
- `TelegramSlashExtension`: 将 Alconna 的命令注册在 Telegram 上以获得提示。
### output_converter
:::tip
```python
async def output_converter(self, output_type: OutputType, content: str) -> UniMessage: ...
```
全局的 Extension 可延迟加载 (即若有全局拓展加载于部分 AlconnaMatcher 之后，这部分响应器会被追加拓展)
依据输出信息的类型，将字符串转换为消息对象以便发送。
其中 `OutputType` 为 "help", "shortcut", "completion", "error" 其中之一。
该方法只会调用一次，即对于多个 Extension，选择优先级靠前且实现了该方法的 Extension。
### message_provider
```python
async def message_provider(
self, event: Event, state: T_State, bot: Bot, use_origin: bool = False
) -> UniMessage | None:...
```
该方法用于从事件中提取消息，默认情况下会使用 `event.get_message()` 来获取消息。
该方法可能会调用多次，即对于多个 Extension，选择优先级靠前且实现了该方法的 Extension，若调用的返回值不为 `None` 则作为结果。
:::caution
该方法的默认实现对结果 (UniMessage) 会进行缓存。`Extension` 的实现也应尽量实现缓存机制。
:::
### receive_provider
```python
async def receive_provider(self, bot: Bot, event: Event, command: Alconna, receive: UniMessage) -> UniMessage: ...
```
该方法用于对传入的消息 (UniMessage) 进行额外处理，默认情况下会返回原始消息。
该方法会调用多次，即对于多个 Extension，前一个 Extension 的返回值会作为下一个 Extension 的输入。
### context_provider
```python
async def context_provider(self, ctx: dict[str, Any], bot: Bot, event: Event, state: T_State) -> dict[str, Any]:
```
该方法用于提取命令上下文，默认情况下会返回 `ctx` 本身。
该方法会调用多次，即对于多个 Extension，前一个 Extension 的返回值会作为下一个 Extension 的输入。
### permission_check
```python
async def permission_check(self, bot: Bot, event: Event, command: Alconna) -> bool: ...
```
该方法用于对发送者的权限进行检查，默认情况下会返回 `True`。
该方法可能会调用多次，即对于多个 Extension，若调用的返回值不为 `True` 则结束判断。
### parse_wrapper
```python
async def parse_wrapper(self, bot: Bot, state: T_State, event: Event, res: Arparma) -> None: ...
```
该方法用于对命令解析结果进行额外处理。
该方法会调用多次，即对于多个 Extension，会并发地调用该方法。
### send_wrapper
```python
async def send_wrapper(self, bot: Bot, event: Event, send: TMessage) -> TMessage: ...
```
该方法用于对 `AlconnaMatcher.send` 或 `UniMessage.send` 发送的消息 (str 或 Message 或 UniMessage) 进行额外处理，默认情况下会返回原始消息。
该方法会调用多次，即对于多个 Extension，前一个 Extension 的返回值会作为下一个 Extension 的输入。
由于需要保证输入与输出的类型一致，该方法内需要自行判断类型。
### before_catch
```python
def before_catch(self, name: str, annotation: type, default: Any) -> bool: ...
```
该方法用于响应函数中某个参数是否需要绑定到该 Extension 上。
### catch
```python
async def catch(self, interface: Interface) -> Any: ...
```
该方法用于注入经过 `before_catch` 确认的参数。其中 `Interface` 的定义为
```python
class Interface(Generic[TE]):
event: TE
state: T_State
name: str
annotation: Any
default: Any
```
## 补全会话
补全会话基于 [`半自动补全`](./command.md#半自动补全)，用于指令参数缺失或参数错误时给予交互式提示，类似于 `got-reject`：
@ -578,30 +675,6 @@ class CompConfig(TypedDict):
"""禁用的指令"""
lite: NotRequired[bool]
"""是否使用简洁版本的补全会话（相当于同时配置 disables、hides、hide_tabs）"""
block: NotRequired[bool]
"""进行补全会话时是否阻塞响应器"""
```
## 内置插件
类似于 Nonebot 本身提供的内置插件，`nonebot_plugin_alconna` 提供了两个内置插件：`echo` 和 `help`。
你可以用本插件的 `load_builtin_plugin(s)` 来加载它们：
```python
from nonebot_plugin_alconna import load_builtin_plugins
load_builtin_plugins("echo", "help")
```
其中 `help` 仅能列出所有 Alconna 指令。
<Messenger
msgs={[
{ position: "right", msg: "/帮助" },
{
position: "left",
msg: "# 当前可用的命令有:\n 0 /echo : echo 指令\n 1 /help : 显示所有命令帮助\n# 输入'命令名 -h|--help' 查看特定命令的语法",
},
{ position: "right", msg: "/echo [图片]" },
{ position: "left", msg: "[图片]" },
]}
/>