diff --git a/website/docs/best-practice/alconna/README.mdx b/website/docs/best-practice/alconna/README.mdx index a0a39bd4..44abd611 100644 --- a/website/docs/best-practice/alconna/README.mdx +++ b/website/docs/best-practice/alconna/README.mdx @@ -6,6 +6,7 @@ import TabItem from "@theme/TabItem"; [`nonebot-plugin-alconna`](https://github.com/nonebot/plugin-alconna) 是一类极大地提升了 NoneBot 开发体验的插件。 该插件可分为三个部分： + - 增强的命令解析: 基于 [Alconna](https://github.com/ArcletProject/Alconna), 提供一类新的事件响应器辅助函数 `on_alconna`. 相比 `on_command`, `on_shell`, `on_regex` 等函数，`on_alconna` 提供了更强大的命令解析能力与诸多特性。 - 通用消息组件: 实现了跨平台接收、发送、撤回、编辑、表态消息的功能。 - `UniMessage` 通用消息模型，支持各适配器下的消息转换和导出，发送。 @@ -22,32 +23,31 @@ import TabItem from "@theme/TabItem"; 以最新版本为例 (v0.57), 本插件已支持 NoneBot 生态中几乎所有的适配器, 包括: -| 协议名称 | 路径 | -|---------------------------------------------------------------------|--------------------------------------| -| [OneBot 协议](https://onebot.dev/) | adapters.onebot11, adapters.onebot12 | +| 协议名称 | 路径 | +| ------------------------------------------------------------------- | ------------------------------------ | +| [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 | +| [飞书](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 | +| [钉钉](https://open.dingtalk.com/document/) | adapters.ding | | [Console](https://github.com/nonebot/adapter-console) | adapters.console | -| [开黑啦](https://developer.kookapp.cn/) | adapters.kook | +| [开黑啦](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 | +| [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 | +| [微信公众号](https://github.com/YangRucheng/nonebot-adapter-wxmp) | adapters.wxmp | +| [黑盒语音](https://github.com/lclbm/adapter-heybox) | adapters.heybox | | [Gewechat](https://github.com/Shine-Light/nonebot-adapter-gewechat) | adapters.gewechat | - ## 安装插件 在使用前请先安装 `nonebot-plugin-alconna` 插件至项目环境中，可参考[获取商店插件](../../tutorial/store.mdx#安装插件)来了解并选择安装插件的方式。如： diff --git a/website/docs/best-practice/alconna/builtins.mdx b/website/docs/best-practice/alconna/builtins.mdx index 2e30bbb6..ebb5928e 100644 --- a/website/docs/best-practice/alconna/builtins.mdx +++ b/website/docs/best-practice/alconna/builtins.mdx @@ -2,6 +2,7 @@ sidebar_position: 7 description: 内置组件 --- + import Messenger from "@site/src/components/Messenger"; # 内置组件 @@ -149,7 +150,7 @@ i18n配置相关功能 }, { position: "right", msg: "/with lang" }, { position: "left", msg: "设置前缀成功" }, - { position: "right", msg: "list"}, + { position: "right", msg: "list" }, { position: "left", msg: "支持的语言列表:\n * en-US\n * zh-CN", @@ -229,6 +230,7 @@ async def handle(content: Match[str]): ``` 其构造时可传入两个参数: + - `add_left`: 否在当前消息的左侧合并回复消息，默认为 False - `sep`: 合并时的分隔符，默认为空格 @@ -265,6 +267,7 @@ async def remove(plugin: Match[str], time: Match[int]): `MarkdownOutputExtension` 可将 Alconna 的自动输出转换为 Markdown 格式 其构造时可传入两个参数: + - `escape_dot`: 是否转义句中的点号（用来避免被识别为 url） - `text_to_image` 将文本转换为图片的函数，可不传入。一般用来设置渲染 markdown 为图片的函数 diff --git a/website/docs/best-practice/alconna/command.md b/website/docs/best-practice/alconna/command.md index 1fd4dcfe..e80b136d 100644 --- a/website/docs/best-practice/alconna/command.md +++ b/website/docs/best-practice/alconna/command.md @@ -40,20 +40,20 @@ print(res.all_matched_args) 命令构造时, `Alconna([prefix], command)` 与 `Alconna(command, [prefix])` 是等价的。 -| 前缀 | 命令名 | 匹配内容 | 说明 | -|:----------------------------:|:----------:|:---------------------------------------------------------:|:--------:| -| 不传入 | "foo" | `"foo"` | 无前缀的纯文字头 | -| 不传入 | 123 | `123` | 无前缀的元素头 | -| 不传入 | "re:\d{2}" | `"32"` | 无前缀的正则头 | -| 不传入 | int | `123` 或 `"456"` | 无前缀的类型头 | -| [int, bool] | 不传入 | `True` 或 `123` | 无名的元素类头 | -| ["foo", "bar"] | 不传入 | `"foo"` 或 `"bar"` | 无名的纯文字头 | -| ["foo", "bar"] | "baz" | `"foobaz"` 或 `"barbaz"` | 纯文字头 | -| [int, bool] | "foo" | `[123, "foo"]` 或 `[False, "foo"]` | 类型头 | -| [123, 4567] | "foo" | `[123, "foo"]` 或 `[4567, "foo"]` | 元素头 | -| [nepattern.NUMBER] | "bar" | `[123, "bar"]` 或 `[123.456, "bar"]` | 表达式头 | -| [123, "foo"] | "bar" | `[123, "bar"]` 或 `"foobar"` 或 `["foo", "bar"]` | 混合头 | -| [(int, "foo"), (456, "bar")] | "baz" | `[123, "foobaz"]` 或 `[456, "foobaz"]` 或 `[456, "barbaz"]` | 对头 | +| 前缀 | 命令名 | 匹配内容 | 说明 | +| :--------------------------: | :--------: | :---------------------------------------------------------: | :--------------: | +| 不传入 | "foo" | `"foo"` | 无前缀的纯文字头 | +| 不传入 | 123 | `123` | 无前缀的元素头 | +| 不传入 | "re:\d{2}" | `"32"` | 无前缀的正则头 | +| 不传入 | int | `123` 或 `"456"` | 无前缀的类型头 | +| [int, bool] | 不传入 | `True` 或 `123` | 无名的元素类头 | +| ["foo", "bar"] | 不传入 | `"foo"` 或 `"bar"` | 无名的纯文字头 | +| ["foo", "bar"] | "baz" | `"foobaz"` 或 `"barbaz"` | 纯文字头 | +| [int, bool] | "foo" | `[123, "foo"]` 或 `[False, "foo"]` | 类型头 | +| [123, 4567] | "foo" | `[123, "foo"]` 或 `[4567, "foo"]` | 元素头 | +| [nepattern.NUMBER] | "bar" | `[123, "bar"]` 或 `[123.456, "bar"]` | 表达式头 | +| [123, "foo"] | "bar" | `[123, "bar"]` 或 `"foobar"` 或 `["foo", "bar"]` | 混合头 | +| [(int, "foo"), (456, "bar")] | "baz" | `[123, "foobaz"]` 或 `[456, "foobaz"]` 或 `[456, "barbaz"]` | 对头 | 对于无前缀的类型头，此时会将传入的值尝试转为 BasePattern，例如 `int` 会转为 `nepattern.INTEGER`。如此该命令头会匹配对应的类型， 例如 `int` 会匹配 `123` 或 `"456"`，但不会匹配 `"foo"`。解析后，Alconna 会将命令头匹配到的值转为对应的类型，例如 `int` 会将 `"123"` 转为 `123`。 diff --git a/website/docs/best-practice/alconna/config.md b/website/docs/best-practice/alconna/config.md index af900fdd..84c5b40c 100644 --- a/website/docs/best-practice/alconna/config.md +++ b/website/docs/best-practice/alconna/config.md @@ -78,7 +78,6 @@ description: 配置项 是否启动时拉取一次[发送对象](./uniseg/utils.mdx#发送对象)列表。 - ## alconna_builtin_plugins - **类型**: `set[str]` @@ -92,6 +91,7 @@ description: 配置项 - **默认值**: `"default"` 命令冲突解决策略，决定当不同插件之间或者同一插件之间存在两个以上相同的命令时的处理方式： + - `default`: 默认处理方式，保留两个命令 - `raise`: 抛出异常 - `ignore`: 忽略较新的命令 diff --git a/website/docs/best-practice/alconna/matcher.mdx b/website/docs/best-practice/alconna/matcher.mdx index f0bffa62..682dd51a 100644 --- a/website/docs/best-practice/alconna/matcher.mdx +++ b/website/docs/best-practice/alconna/matcher.mdx @@ -61,7 +61,6 @@ async def _(name: str, target: Match[tuple[At, ...]]): ]} /> - ## 声明 `on_alconna` 的参数如下: @@ -148,6 +147,7 @@ async def handle( ``` `AlconnaMatcher` 的依赖注入拓展支持以下情况： + - `xxx: CommandResult` - `xxx: Arparma`：命令的[解析结果](./command.md#解析结果) - `xxx: Duplication`：命令的解析结果的 [`Duplication`](./command.md#Duplication) @@ -260,7 +260,6 @@ async def handle_list(): ... async def handle_add_admin(): ... ``` - ### `dispatch` 方法 此外，使用 `.dispatch` 还能像 `CommandGroup` 一样为每个分发设置独立的 matcher： @@ -297,7 +296,6 @@ async def handle_add_admin(target: Query[tuple[At, ...]] = Query("~target")): ::: - ### `got_path` 方法 另外，`AlconnaMatcher` 有类似于 [`got`](../../appendices/session-control.mdx#got) 的 `got_path` 与配套的 `get_path_arg`, `set_path_arg`： @@ -324,7 +322,6 @@ async def tt(target: Union[str, At]): `got_path` 中可以使用依赖注入函数 `AlconnaArg`, 类似于 [`Arg`](../../advanced/dependency.mdx#arg). - ### `prompt` 方法 基于 [`Waiter`](https://github.com/RF-Tar-Railt/nonebot-plugin-waiter) 插件，`AlconnaMatcher` 提供了 `prompt` 方法来实现更灵活的交互式提示。 @@ -426,6 +423,7 @@ def test( prefix: bool = True ): ... ``` + - `message`: 测试的消息 - `expected`: 预期的解析结果，若为 None 则表示只测试是否匹配 - `prefix`: 是否使用命令前缀，默认为 True diff --git a/website/docs/best-practice/alconna/shortcut.md b/website/docs/best-practice/alconna/shortcut.md index 8eea0476..dbcba1cb 100644 --- a/website/docs/best-practice/alconna/shortcut.md +++ b/website/docs/best-practice/alconna/shortcut.md @@ -76,6 +76,7 @@ book = ( ### 参数类型 `Command` 的参数类型也如 `koishi` 一样，**必选参数** 用尖括号包裹，**可选参数** 用方括号包裹: + - `foo` 表示参数 `foo`, 类型为 Any - `foo:int` 表示参数 `foo`, 类型为 int - `foo:int=1` 表示参数 `foo`, 类型为 int, 默认值为 1 @@ -84,6 +85,7 @@ book = ( - `foo:+str`, `foo:text` 表示参数 `foo`, 类型为 str, 并且将包含空格 (即将变长参数的结果用空格合并) 特别的，针对类型部分，本插件拓展了如下内容: + - `foo:At`, `foo:Image`, ... 表示类型为[通用消息段](./uniseg/segment.md) - `foo:select(Image).first` 表示获取子元素类型 - `foo:Dot(Image, 'url')` 表示类型为 `Image`，并且只获取 `url` 属性 @@ -107,8 +109,7 @@ shortcuts: - key: 测试 args: ["--anonymous"] actions: - - - params: ["options"] + - params: ["options"] code: | return str(options) ``` diff --git a/website/docs/best-practice/alconna/uniseg/message.mdx b/website/docs/best-practice/alconna/uniseg/message.mdx index 45391534..fe7ad5c2 100644 --- a/website/docs/best-practice/alconna/uniseg/message.mdx +++ b/website/docs/best-practice/alconna/uniseg/message.mdx @@ -101,6 +101,7 @@ async def send( ) -> Receipt: ... ``` + - `target`: 发送目标，支持事件和[发送对象](./utils.mdx#发送对象)，不传入时会尝试从响应器上下文中获取。 - `bot`: 发送消息使用的 Bot 对象，若不传入则会尝试从响应器上下文中获取。 - `fallback`: [回退策略](#回退策略)。 @@ -134,6 +135,7 @@ async def tt(target: At): ### 回退策略 `send` 方法的 `fallback` 参数用于指定回退策略（即当前适配器不支持的消息段如何处理）： + - `FallbackStrategy.ignore`: 忽略未转换的消息段 - `FallbackStrategy.to_text`: 将未转换的消息段转为文本元素 - `FallbackStrategy.rollback`: 从未转换消息段的子元素中提取可能的可发送消息段 @@ -178,6 +180,7 @@ async def handle(): ``` `Receipt` 对象拥有以下方法： + - `recallable`: 表明是否可以撤回 - `recall`: 撤回消息 - `editable`: 表明是否可以修改 @@ -188,7 +191,6 @@ async def handle(): - `send`, `finish`: 发送消息 - `reply`: 回复已经发送的消息 - ## 构造 如同 `Message`, `UniMessage` 可以传入单个字符串/消息段，或可迭代的字符串/消息段： @@ -268,7 +270,6 @@ async def tt(): ::: - ### 拼接消息 `str`、`UniMessage`、`Segment` 对象之间可以直接相加，相加均会返回一个新的 `UniMessage` 对象： @@ -447,15 +448,15 @@ message.transform(rule) 转换规则的类型一般为 `dict[str, Transformer]`，以消息元素类型的名称为键，定义方式如下： ```typescript -type Fragment = Segment | Segment[] -type Render = (attrs: dict, children: Segment[]) => T -type Transformer = boolean | Fragment | Render +type Fragment = Segment | Segment[]; +type Render = (attrs: dict, children: Segment[]) => T; +type Transformer = boolean | Fragment | Render; ``` - ### 字符串操作 类似于 `str`，消息序列可以通过如下方法来操作消息内的文本部分： + - `split`, - `replace`, - `startwith`, `endswith`, @@ -499,6 +500,7 @@ def dump(self, media_save_dir: str | Path | bool | None = None, json: bool = Fal ``` 其中，`media_save_dir` 用于指定持久化的媒体文件存储目录: + - 若 `media_save_dir` 为 str 或 Path，则会将媒体文件保存到指定目录下。 - 若 `media_save_dir` 为 False，则不会保存媒体文件。 - 若 `media_save_dir` 为 True，则会将文件数据转为 base64 编码。 diff --git a/website/docs/best-practice/alconna/uniseg/segment.md b/website/docs/best-practice/alconna/uniseg/segment.md index 1b64d748..f084a770 100644 --- a/website/docs/best-practice/alconna/uniseg/segment.md +++ b/website/docs/best-practice/alconna/uniseg/segment.md @@ -35,7 +35,7 @@ class Text(Segment): """Text对象, 表示一类文本元素""" text: str styles: dict[tuple[int, int], list[str]] - + def cover(self, text: str): ... def mark(self, start: Optional[int] = None, end: Optional[int] = None, *styles: str): ... diff --git a/website/docs/best-practice/alconna/uniseg/utils.mdx b/website/docs/best-practice/alconna/uniseg/utils.mdx index 3feb6bca..df9780b3 100644 --- a/website/docs/best-practice/alconna/uniseg/utils.mdx +++ b/website/docs/best-practice/alconna/uniseg/utils.mdx @@ -16,7 +16,6 @@ import TabItem from "@theme/TabItem"; ::: - ## 消息事件 ID 消息事件 ID 是用来标识当前消息事件的唯一 ID，通常用于回复/撤回/编辑/表态当前消息。 @@ -175,7 +174,6 @@ async def _(): 若配置了 [`alconna_apply_fetch_targets`](../config.md#alconna_apply_fetch_targets) 选项，则在启动时会主动拉取一次发送对象列表。即对于 某一主动构造的 `Target` 对象，插件将其与拉取下来的众多发送对象进行匹配，并选择第一个符合条件的发送对象，以选择对应的 Bot 对象。 - ## 撤回消息 通过 `message_recall` 方法来撤回消息事件。 @@ -271,6 +269,7 @@ async def message_reaction( ## 响应规则 `uniseg` 模块提供了两个响应规则： + - `at_in`: 是否在消息中 @ 了指定的用户 - `at_me`: 是否在消息中 @ 了机器人 diff --git a/website/docs/best-practice/multi-adapter.mdx b/website/docs/best-practice/multi-adapter.mdx index af45fbb3..36c2920a 100644 --- a/website/docs/best-practice/multi-adapter.mdx +++ b/website/docs/best-practice/multi-adapter.mdx @@ -187,16 +187,19 @@ async def handle_onebot_reply(bot: OnebotBot, state: T_State, location: str = Ar 这些插件可以分为三类： ### 事件处理 + - [all4one](https://github.com/nonepkg/nonebot-plugin-all4one): 将不同平台的事件转为符合 OneBot V12 协议的插件 - 支持的适配器: OneBot V11/V12, Discord, QQ, Telegram ### 消息处理 + - [alconna](https://github.com/nonebot/plugin-alconna): 对几乎所有适配器中消息的收发、撤回、编辑、表态的统一插件 - 支持的适配器: OneBot V11/V12, Telegram, Feishu, Github, QQ, Ding, Console, Kaiheila, Mirai, NtChat, Minecraft, Discord, Satori, Red, Dodo, Kritor, Tailchat, Mail, WXMP, Heybox, Gewechat - [send-anything-anywhere](https://github.com/felinae98/nonebot-plugin-send-anything-anywhere): 帮助处理不同适配器消息的适配和发送的插件 - 支持的适配器: OneBot V11/V12, Kaiheila, Telegram, Feishu, Red, DoDo, Satori, QQ, Discord ### 会话信息提取 + - [uninfo](https://github.com/RF-Tar-Railt/nonebot-plugin-uninfo): 多平台的会话信息(用户、群组、频道)获取插件 - 支持的适配器: OneBot V11/V12, Telegram, Feishu, QQ, Console, Kaiheila, Mirai, Minecraft, Discord, Satori, Dodo, Kritor, Mail, WXMP, Gewechat - [session](https://github.com/noneplugin/nonebot-plugin-session): 会话信息提取与会话 id 定义插件 diff --git a/website/src/changelog/changelog.md b/website/src/changelog/changelog.md index d8509570..067c196b 100644 --- a/website/src/changelog/changelog.md +++ b/website/src/changelog/changelog.md @@ -9,6 +9,7 @@ toc_max_heading_level: 2 ### 📝 文档 +- Docs: 更新最佳实践 `Alconna` 章节 [@RF-Tar-Railt](https://github.com/RF-Tar-Railt) ([#3447](https://github.com/nonebot/nonebot2/pull/3447)) - Docs: 修复移动端侧边栏折叠状态异常 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3414](https://github.com/nonebot/nonebot2/pull/3414)) - Docs: 添加 Gewechat 适配器描述 [@Shine-Light](https://github.com/Shine-Light) ([#3372](https://github.com/nonebot/nonebot2/pull/3372))