📝 Docs: 更新最佳实践 Alconna (#2401)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

assets/plugins.json

@@ -199,15 +199,15 @@
     "author": "RF-Tar-Railt",
     "tags": [
       {
-        "label": "matcher",
+        "label": "多适配器",
         "color": "#5280ea"
       },
       {
-        "label": "command",
+        "label": "消息匹配",
         "color": "#ea6f52"
       },
       {
-        "label": "alconna",
+        "label": "跨平台",
         "color": "#5452ea"
       }
     ],

website/docs/best-practice/alconna/README.mdx

@@ -13,8 +13,6 @@ slug: /best-practice/alconna/
 
 该插件提供了一类新的事件响应器辅助函数 `on_alconna`，以及 `AlconnaResult` 等依赖注入函数。
 
-同时，基于 [Annotated 支持](https://github.com/nonebot/nonebot2/pull/1832), 添加了两类注解 `AlcMatches` 与 `AlcResult`
-
 该插件声明了一个 `Matcher` 的子类 `AlconnaMatcher`，并在 `AlconnaMatcher` 中添加了一些新的方法，例如：
 
 - `assign`：基于 `Alconna` 解析结果，执行满足目标路径的处理函数
@@ -112,7 +110,7 @@ async def got_location(location: str):
 ```
 
 在上面的代码中，我们使用 `Alconna` 来解析命令，`on_alconna` 用来创建响应器，使用 `Match` 来获取解析结果。
-command
+
 关于更多 `Alconna` 的使用方法，可参考 [Alconna 文档](https://arclet.top/docs/tutorial/alconna)，
 或阅读 [Alconna 基本介绍](./command.md) 一节。
 

website/docs/best-practice/alconna/command.md

@@ -77,10 +77,16 @@ Bracket Header 类似 python 里的 f-string 写法，通过 "{}" 声明匹配
 
 我们可以看到主要的两大组件：`Option` 与 `Subcommand`。
 
-`Option` 可以传入一组 `alias`，如 `Option("--foo|-F|--FOO|-f")` 或 `Option("--foo", alias=["-F"])`
+`Option` 可以传入一组 `alias`，如 `Option("--foo|-F|FOO|f")` 或 `Option("--foo", alias=["-F"])`
 
 传入别名后，Option 会选择其中长度最长的作为选项名称。若传入为 "--foo|-f"，则命令名称为 "--foo"。
 
+:::tip 特别提醒！！！
+
+在 Alconna 中 Option 的名字或别名**没有要求**必须在前面写上 `-`
+
+:::
+
 `Subcommand` 则可以传入自己的 **Option** 与 **Subcommand**。
 
 ```python
@@ -93,7 +99,7 @@ alc = Alconna(
     Subcommand(
         "sub1",
         Option("sub1_opt1"),
-        Option("-SO2"),
+        Option("SO2"),
         Subcommand(
             "sub1_sub1"
         )
@@ -112,7 +118,7 @@ alc = Alconna(
   对于命令 `test foo bar baz qux <a:int>` 来讲，因为`foo bar baz` 仅需要判断是否相等, 所以可以这么编写：
 
   ```python
-  Alconna("test", Option("qux", Args.a[int], requires=["foo", "bar", "baz"]))
+  Alconna("test", Option("qux", Args["a", int], requires=["foo", "bar", "baz"]))
   ```
 
 - `default`: 默认值，在该组件未被解析时使用使用该值替换。
@@ -167,14 +173,15 @@ alc = Alconna(
 `foo#这是注释;?` 或 `foo?#这是注释`
 
 :::tip
+
 `Args` 中的 `name` 在实际命令中并不需要传入（keyword 参数除外）：
 
 ```python
 from arclet.alconna import Alconna, Args
 
 alc = Alconna("test", Args["foo", str])
 alc.parse("test --foo abc")  # 错误
-alc.parse("test abc")  # 之前
+alc.parse("test abc")  # 正确
 ```
 
 若需要 `test --foo abc`，你应该使用 `Option`：
@@ -226,6 +233,7 @@ args = Args["foo", BasePattern("@\d+")]
 - ...
 
 :::tip
+
 几类特殊的传入标记：
 
 - `"foo"`: 匹配字符串 "foo" (若没有某个 `BasePattern` 与之关联)
@@ -244,11 +252,13 @@ args = Args["foo", BasePattern("@\d+")]
 同样的还有 `KeyWordVar`，其构造方法形如 `KeyWordVar(str)`，用于告知解析器该参数为一个 keyword-only 参数。
 
 :::tip
+
 `MultiVar` 与 `KeyWordVar` 组合时，代表该参数为一个可接受多个 key-value 的参数，其构造方法形如 `MultiVar(KeyWordVar(str))`
 
 `MultiVar` 与 `KeyWordVar` 也可以传入 `default` 参数，用于指定默认值。
 
 `MultiVar` 不能在 `KeyWordVar` 之后传入。
+
 :::
 
 ### 紧凑命令
@@ -378,7 +388,7 @@ class ShortcutArgs(TypedDict):
 
 快捷指令允许三类特殊的 placeholder:
 
-- `{%X}`: 如 `setu {%0}`，表示此处填入快捷指令后随的第 X 个参数。
+- `{%X}`: 如 `setu {%0}`，表示此处必须填入快捷指令后随的第 X 个参数。
 
   例如，若快捷指令为 `涩图`, 配置为 `{"command": "setu {%0}"}`, 则指令 `涩图 1` 相当于 `setu 1`
 

website/docs/best-practice/alconna/config.md

@@ -39,3 +39,17 @@ description: 配置项
 - **默认值**: `True`
 
 是否使用特制的 Param 提供更好的依赖注入，该选项不会对使用依赖注入函数形式造成影响
+
+## alconna_use_command_sep
+
+- **类型**: `bool`
+- **默认值**: `False`
+
+是否读取 Nonebot 的配置项 `COMMAND_SEP` 来作为全局的 Alconna 命令分隔符
+
+## alconna_global_extensions
+
+- **类型**: `List[str]`
+- **默认值**: `[]`
+
+全局加载的扩展, 路径以 . 分隔, 如 foo.bar.baz:DemoExtension