add command help generator (build 450)

增加命令帮助生成器 by @sunxyw

README.md

@@ -16,7 +16,7 @@
 
 开发者 QQ 群：**670821194** [点击加入群聊](https://jq.qq.com/?_wv=1027&k=YkNI3AIr)
 
-**如果有愿意一起开发框架本身的开发者，请提出 PR 或 Issue 参与开发！如果对框架本身的核心设计有更好的想法，可与作者成立开发组（目前仅作者 1 人），参与 OneBot V12 生态和框架本身的开发。**
+**如果有愿意一起开发框架本身的开发者，请提出 PR 或 Issue 参与开发！如果对框架本身的核心设计有更好的想法，可与作者成立开发组（目前仅 2 人），参与 OneBot V12 生态和框架本身的开发。**
 
 **相关正在进行的版本任务见 Projects 一栏！**
 

src/Module/Example/Hello.php

@@ -216,4 +216,17 @@ class Hello
         Console::info('Unknown connection , I will close it.');
         server()->disconnect(ctx()->getConnection()->getFd());
     }
+
+    /**
+     * 输出帮助信息
+     *
+     * @CQCommand("帮助")
+     */
+    #[CQCommand('帮助')]
+    public function help(): string
+    {
+        $helps = MessageUtil::generateCommandHelp();
+        array_unshift($helps, '帮助：');
+        return implode("\n", $helps);
+    }
 }

src/ZM/ConsoleApplication.php

@@ -28,9 +28,9 @@ use ZM\Exception\InitException;
 
 class ConsoleApplication extends Application
 {
-    public const VERSION_ID = 449;
+    public const VERSION_ID = 450;
 
-    public const VERSION = '2.7.2';
+    public const VERSION = '2.7.3';
 
     private static $obj;
 

src/ZM/Utils/MessageUtil.php

@@ -5,6 +5,8 @@ declare(strict_types=1);
 namespace ZM\Utils;
 
 use Exception;
+use ReflectionException;
+use ReflectionMethod;
 use ZM\Annotation\CQ\CQCommand;
 use ZM\API\CQ;
 use ZM\Config\ZMConfig;
@@ -12,6 +14,7 @@ use ZM\Console\Console;
 use ZM\Entity\MatchResult;
 use ZM\Event\EventManager;
 use ZM\Requests\ZMRequest;
+use ZM\Store\WorkerCache;
 use ZM\Utils\Manager\WorkerManager;
 
 class MessageUtil
@@ -242,4 +245,72 @@ class MessageUtil
         }
         return $str;
     }
+
+    /**
+     * 根据注解树生成命令列表、帮助
+     *
+     * @return array 帮助信息，每个元素对应一个命令的帮助信息，格式为：命令名（其他触发条件）：命令描述
+     */
+    public static function generateCommandHelp(): array
+    {
+        try {
+            if ($cache = WorkerCache::get('command_help')) {
+                return $cache;
+            }
+        } catch (Exception $e) {
+            // 不做任何处理，尝试重新生成
+        }
+        $helps = [];
+        foreach (EventManager::$events[CQCommand::class] as $annotation) {
+            if ($annotation instanceof CQCommand) {
+                try {
+                    $reflection = new ReflectionMethod($annotation->class, $annotation->method);
+                } catch (ReflectionException $e) {
+                    Console::warning('注解解析错误：' . $e->getMessage());
+                    continue;
+                }
+                $doc = $reflection->getDocComment();
+                if ($doc) {
+                    // 匹配出不以@开头，且后接中文或任意非空格字符，并以换行符结尾的字符串，也就是命令描述
+                    preg_match_all('/\*\s((?!@)[\x{4e00}-\x{9fa5}\S]+)(\r\n|\r|\n)/u', $doc, $matches);
+                    // 多行描述用分号分隔
+                    $help = implode('；', $matches[1]);
+                    if (empty($help)) {
+                        Console::warning('命令 ' . $annotation->class . '::' . $annotation->method . ' 没有描述！');
+                        $help = '无描述';
+                    }
+                } else {
+                    Console::warning('命令 ' . $annotation->class . '::' . $annotation->method . ' 没有描述！');
+                    $help = '无描述';
+                }
+
+                // 可以触发命令的参数
+                $possible_keys = [
+                    'match' => '%s',
+                    'pattern' => '符合”%s“',
+                    'regex' => '匹配“%s”',
+                    'start_with' => '以”%s“开头',
+                    'end_with' => '以”%s“结尾',
+                    'keyword' => '包含“%s”',
+                    'alias' => '%s',
+                ];
+                $command_seg = [];
+                foreach ($possible_keys as $key => $help_format) {
+                    // 如果定义了该参数，则添加到帮助信息中
+                    if (isset($annotation->{$key}) && !empty($annotation->{$key})) {
+                        $command_seg[] = sprintf($help_format, $annotation->{$key});
+                    }
+                }
+                // 第一个触发参数为主命令名
+                $command = array_shift($command_seg);
+                if (count($command_seg) > 0) {
+                    $command .= '（' . implode('，', $command_seg) . '）';
+                }
+                $helps[] = sprintf('%s：%s', $command, $help);
+            }
+        }
+        // 放到跨进程缓存以供取用
+        WorkerCache::set('command_helps', $helps);
+        return $helps;
+    }
 }