✨ feat(help): 引入LLM智能帮助并优化其功能 (#1982)

- 【新功能】引入LLM智能帮助功能，当传统帮助未找到结果时，可自动调用LLM提供智能回复 - 【配置项】新增多项LLM帮助相关配置： - `ENABLE_LLM_HELPER`: 控制LLM智能帮助的启用与禁用 - `DEFAULT_LLM_MODEL`: 配置智能帮助使用的LLM模型 - `LLM_HELPER_STYLE`: 设置LLM回复的口吻或风格 - `LLM_HELPER_REPLY_AS_IMAGE_THRESHOLD`: 定义LLM回复字数超过此阈值时转为图片发送 - 【逻辑优化】帮助指令处理流程调整： - 优先尝试传统插件帮助查询 - 若传统查询无结果且LLM智能帮助已启用，则调用LLM进行自然语言回答 Co-authored-by: webjoin111 <455457521@qq.com> Co-authored-by: HibiKier <45528451+HibiKier@users.noreply.github.com>
2026-09-29 08:39:59 +08:00 · 2025-07-16 13:48:13 +08:00
parent 205f4ff1fa
commit a0b57b6bea
2 changed files with 149 additions and 12 deletions
@@ -11,9 +11,15 @@ from zhenxun.configs.utils import PluginExtraData
 from zhenxun.models.level_user import LevelUser
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.models.statistics import Statistics
-from zhenxun.utils._image_template import ImageTemplate
+from zhenxun.services import (
+    LLMException,
+    LLMMessage,
+    generate,
+)
+from zhenxun.services.log import logger
+from zhenxun.utils._image_template import Markdown
 from zhenxun.utils.enum import PluginType
-from zhenxun.utils.image_utils import BuildImage
+from zhenxun.utils.image_utils import BuildImage, ImageTemplate

 from ._config import (
    GROUP_HELP_PATH,
@@ -202,3 +208,89 @@ async def get_plugin_help(user_id: str, name: str, is_superuser: bool) -> str |
                return await get_normal_help(_plugin.metadata, extra_data, is_superuser)
        return "糟糕! 该功能没有帮助喔..."
    return "没有查找到这个功能噢..."
+
+
+async def get_llm_help(question: str, user_id: str) -> str | bytes:
+    """
+    使用LLM来回答用户的自然语言求助。
+
+    参数:
+        question: 用户的问题。
+        user_id: 提问用户的ID。
+
+    返回:
+        str | bytes: LLM生成的回答或错误提示。
+    """
+
+    try:
+        allowed_types = await get_user_allow_help(user_id)
+
+        plugins = await PluginInfo.filter(
+            is_show=True, plugin_type__in=allowed_types
+        ).all()
+
+        knowledge_base_parts = []
+        for p in plugins:
+            meta = nonebot.get_plugin_by_module_name(p.module_path)
+            if not meta or not meta.metadata:
+                continue
+            usage = meta.metadata.usage.strip() or "无"
+            desc = meta.metadata.description.strip() or "无"
+            part = f"功能名称: {p.name}\n功能描述: {desc}\n用法示例:\n{usage}"
+            knowledge_base_parts.append(part)
+
+        if not knowledge_base_parts:
+            return "抱歉，根据您的权限，当前没有可供查询的功能信息。"
+
+        knowledge_base = "\n\n---\n\n".join(knowledge_base_parts)
+
+        user_role = "普通用户"
+        if PluginType.SUPERUSER in allowed_types:
+            user_role = "超级管理员"
+        elif PluginType.ADMIN in allowed_types:
+            user_role = "管理员"
+
+        base_system_prompt = (
+            f"你是一个精通机器人功能的AI助手。当前向你提问的用户是一位「{user_role}」。\n"
+            "你的任务是根据下面提供的功能列表和详细说明，来回答用户关于如何使用机器人的问题。\n"
+            "请仔细阅读每个功能的描述和用法，然后用简洁、清晰的语言告诉用户应该使用哪个或哪些命令来解决他们的问题。\n"
+            "如果找不到完全匹配的功能，可以推荐最相关的一个或几个。直接给出操作指令和简要解释即可。"
+        )
+
+        if (
+            Config.get_config("help", "LLM_HELPER_STYLE")
+            and Config.get_config("help", "LLM_HELPER_STYLE").strip()
+        ):
+            style = Config.get_config("help", "LLM_HELPER_STYLE")
+            style_instruction = f"请务必使用「{style}」的风格和口吻来回答。"
+            system_prompt = f"{base_system_prompt}\n{style_instruction}"
+        else:
+            system_prompt = base_system_prompt
+
+        full_instruction = (
+            f"{system_prompt}\n\n=== 功能列表和说明 ===\n{knowledge_base}"
+        )
+
+        messages = [
+            LLMMessage.system(full_instruction),
+            LLMMessage.user(question),
+        ]
+        response = await generate(
+            messages=messages,
+            model=Config.get_config("help", "DEFAULT_LLM_MODEL"),
+        )
+
+        reply_text = response.text if response else "抱歉，我暂时无法回答这个问题。"
+        threshold = Config.get_config("help", "LLM_HELPER_REPLY_AS_IMAGE_THRESHOLD", 50)
+        if len(reply_text) > threshold:
+            markdown = Markdown()
+            markdown.text(reply_text)
+            return await markdown.build()
+        return reply_text
+
+    except LLMException as e:
+        logger.error(f"LLM智能帮助出错: {e}", "帮助", e=e)
+        return "抱歉，智能帮助功能当前不可用，请稍后再试或联系管理员。"
+    except Exception as e:
+        logger.error(f"构建LLM帮助时发生未知错误: {e}", "帮助", e=e)
+        return "抱歉，智能帮助功能遇到了一点小问题，正在紧急处理中！"