✨ Feature: CommandGroup 支持命令别名添加前缀选项 (#2134)

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

nonebot/plugin/on.py

@@ -429,6 +429,7 @@ class CommandGroup(_Group):
 
     参数:
         cmd: 指定命令内容
+        prefix_aliases: 是否影响命令别名，给命令别名加前缀
         rule: 事件响应规则
         permission: 事件响应权限
         handlers: 事件处理函数列表
@@ -439,11 +440,14 @@ class CommandGroup(_Group):
         state: 默认 state
     """
 
-    def __init__(self, cmd: Union[str, Tuple[str, ...]], **kwargs):
+    def __init__(
+        self, cmd: Union[str, Tuple[str, ...]], prefix_aliases: bool = False, **kwargs
+    ):
         """命令前缀"""
         super().__init__(**kwargs)
         self.basecmd: Tuple[str, ...] = (cmd,) if isinstance(cmd, str) else cmd
         self.base_kwargs.pop("aliases", None)
+        self.prefix_aliases = prefix_aliases
 
     def __repr__(self) -> str:
         return f"CommandGroup(cmd={self.basecmd}, matchers={len(self.matchers)})"
@@ -466,6 +470,11 @@ class CommandGroup(_Group):
         """
         sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
         cmd = self.basecmd + sub_cmd
+        if self.prefix_aliases and (aliases := kwargs.get("aliases")):
+            kwargs["aliases"] = {
+                self.basecmd + ((alias,) if isinstance(alias, str) else alias)
+                for alias in aliases
+            }
         matcher = on_command(cmd, **self._get_final_kwargs(kwargs))
         self.matchers.append(matcher)
         return matcher
@@ -490,6 +499,11 @@ class CommandGroup(_Group):
         """
         sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
         cmd = self.basecmd + sub_cmd
+        if self.prefix_aliases and (aliases := kwargs.get("aliases")):
+            kwargs["aliases"] = {
+                self.basecmd + ((alias,) if isinstance(alias, str) else alias)
+                for alias in aliases
+            }
         matcher = on_shell_command(cmd, **self._get_final_kwargs(kwargs))
         self.matchers.append(matcher)
         return matcher

nonebot/plugin/on.pyi

@@ -179,6 +179,7 @@ class CommandGroup:
     def __init__(
         self,
         cmd: str | tuple[str, ...],
+        prefix_aliases: bool = ...,
         *,
         rule: Rule | T_RuleChecker | None = ...,
         permission: Permission | T_PermissionChecker | None = ...,

tests/plugins/plugin/matchers.py

@@ -220,7 +220,7 @@ matcher_on_type = on_type(
 
 
 cmd_group = CommandGroup(
-    "test",
+    "prefix",
     rule=rule,
     permission=permission,
     handlers=[handler],
@@ -230,8 +230,30 @@ cmd_group = CommandGroup(
     block=True,
     state=state,
 )
-matcher_sub_cmd = cmd_group.command("sub")
+matcher_prefix_cmd = cmd_group.command("sub", aliases={"help", ("help", "foo")})
-matcher_sub_shell_cmd = cmd_group.shell_command("sub")
+matcher_prefix_shell_cmd = cmd_group.shell_command(
+    "sub", aliases={"help", ("help", "foo")}
+)
+
+
+cmd_group_prefix_aliases = CommandGroup(
+    "prefix",
+    prefix_aliases=True,
+    rule=rule,
+    permission=permission,
+    handlers=[handler],
+    temp=True,
+    expire_time=expire_time,
+    priority=priority,
+    block=True,
+    state=state,
+)
+matcher_prefix_aliases_cmd = cmd_group_prefix_aliases.command(
+    "sub", aliases={"help", ("help", "foo")}
+)
+matcher_prefix_aliases_shell_cmd = cmd_group_prefix_aliases.shell_command(
+    "sub", aliases={"help", ("help", "foo")}
+)
 
 
 matcher_group = MatcherGroup(

tests/test_plugin/test_on.py

@@ -41,10 +41,30 @@ from nonebot.rule import (
         ),
         pytest.param("matcher_on_regex", lambda e: RegexRule("test"), True),
         pytest.param("matcher_on_type", lambda e: IsTypeRule(e), True),
-        pytest.param("matcher_sub_cmd", lambda e: CommandRule([("test", "sub")]), True),
         pytest.param(
-            "matcher_sub_shell_cmd",
+            "matcher_prefix_cmd",
-            lambda e: ShellCommandRule([("test", "sub")], None),
+            lambda e: CommandRule([("prefix", "sub"), ("help",), ("help", "foo")]),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_shell_cmd",
+            lambda e: ShellCommandRule(
+                [("prefix", "sub"), ("help",), ("help", "foo")], None
+            ),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_aliases_cmd",
+            lambda e: CommandRule(
+                [("prefix", "sub"), ("prefix", "help"), ("prefix", "help", "foo")]
+            ),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_aliases_shell_cmd",
+            lambda e: ShellCommandRule(
+                [("prefix", "sub"), ("prefix", "help"), ("prefix", "help", "foo")], None
+            ),
             True,
         ),
         pytest.param("matcher_group_on", None, True),

website/docs/advanced/matcher.md

@@ -291,6 +291,19 @@ sub_cmd = group.command("sub")
 help_cmd = group.command("help")
 ```
 
+命令别名 aliases 默认不会添加 `CommandGroup` 设定的前缀，如果需要为 aliases 添加前缀，可以添加 `prefix_aliases=True` 参数:
+
+```python
+from nonebot import CommandGroup
+
+group = CommandGroup("cmd", prefix_aliases=True)
+
+cmd = group.command(tuple())
+help_cmd = group.command("help", aliases={"帮助"})
+```
+
+这样就能成功匹配 `/cmd`、`/cmd.help`、`/cmd.帮助` 命令。如果未设置，将默认匹配 `/cmd`、`/cmd.help`、`/帮助` 命令。
+
 ### `MatcherGroup`
 
 `MatcherGroup` 可以用于管理一系列具有相同属性的响应器。