ErisPulse-HelpNext 0.1.0__py3-none-any.whl

HelpNext/Core.py

@@ -0,0 +1,349 @@
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from ErisPulse import sdk
+from ErisPulse.Core.Bases import BaseConfig, BaseI18n, BaseModule, I18nKey
+from ErisPulse.Core.Event import command
+
+from .Templates import HelpTemplates
+from .Visualizer import Visualizer
+
+class Main(BaseModule):
+    """ErisPulse modern help module (Takumi-rendered, i18n-aware)."""
+
+    @dataclass
+    class ConfigClass(BaseConfig):
+        show_hidden_commands: bool = field(
+            default=False,
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_show_hidden", "default": "显示隐藏命令"},
+                "ui": {"widget": "switch", "group": "basic", "order": 1},
+            },
+        )
+        group_commands: bool = field(
+            default=True,
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_group_commands", "default": "按分组显示命令"},
+                "ui": {"widget": "switch", "group": "basic", "order": 2},
+            },
+        )
+        theme: str = field(
+            default="auto",
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_theme", "default": "图片主题"},
+                "ui": {
+                    "widget": "select", "group": "render", "order": 3,
+                    "options": [
+                        {"label": {"i18n": "HelpNext.theme_auto", "default": "自动（跟随时间）"}, "value": "auto"},
+                        {"label": {"i18n": "HelpNext.theme_light", "default": "浅色"}, "value": "light"},
+                        {"label": {"i18n": "HelpNext.theme_dark", "default": "深色"}, "value": "dark"},
+                    ],
+                },
+            },
+        )
+        utc_offset: int = field(
+            default=8,
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_utc_offset", "default": "UTC 时区偏移（用于昼夜切换）"},
+                "min": -12, "max": 14,
+                "ui": {"widget": "number", "group": "render", "order": 4},
+            },
+        )
+        show_logo: bool = field(
+            default=True,
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_show_logo", "default": "头部显示 ErisPulse 图标"},
+                "ui": {"widget": "switch", "group": "header", "order": 5},
+            },
+        )
+        header_title: str = field(
+            default="",
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_header_title", "default": "自定义头部标题（留空使用默认）"},
+                "ui": {"widget": "text", "group": "header", "order": 6},
+            },
+        )
+        header_subtitle: str = field(
+            default="",
+            metadata={
+                "description": {"i18n": "HelpNext.cfg_header_subtitle", "default": "自定义头部副标题（留空使用默认）"},
+                "ui": {"widget": "text", "group": "header", "order": 7},
+            },
+        )
+
+        _schema_meta = {
+            "group_labels": {
+                "basic": {"i18n": "HelpNext.group_basic", "default": "基本"},
+                "render": {"i18n": "HelpNext.group_render", "default": "渲染"},
+                "header": {"i18n": "HelpNext.group_header", "default": "头部"},
+            },
+        }
+
+    class I18nClass(BaseI18n):
+        title: I18nKey = I18nKey(default="Command Help", zh_CN="命令帮助", zh_TW="命令幫助", en="Command Help", ja="コマンドヘルプ", ru="Справка по командам")
+        detail_title: I18nKey = I18nKey(default="Command Detail", zh_CN="命令详情", zh_TW="命令詳情", en="Command Detail", ja="コマンド詳細", ru="Подробности команды")
+        group_default: I18nKey = I18nKey(default="General", zh_CN="通用命令", zh_TW="一般命令", en="General", ja="一般", ru="Общие")
+        no_description: I18nKey = I18nKey(default="No description", zh_CN="暂无描述", zh_TW="暫無描述", en="No description", ja="説明なし", ru="Нет описания")
+        usage_hint: I18nKey = I18nKey(default="Use {prefix}help <index> for details", zh_CN="使用 {prefix}help <序号> 查看命令详情", zh_TW="使用 {prefix}help <序號> 查看命令詳情", en="Use {prefix}help <index> for details", ja="{prefix}help <番号> で詳細を表示", ru="Введите {prefix}help <номер> для подробностей")
+        command_count: I18nKey = I18nKey(default="{count} commands available", zh_CN="共 {count} 个可用命令", zh_TW="共 {count} 個可用命令", en="{count} commands available", ja="利用可能なコマンド {count} 件", ru="Доступно команд: {count}")
+        other_prefixes: I18nKey = I18nKey(default="Other prefixes", zh_CN="其他触发前缀", zh_TW="其他觸發前綴", en="Other prefixes", ja="その他のプレフィックス", ru="Другие префиксы")
+
+        label_description: I18nKey = I18nKey(default="Description", zh_CN="描述", zh_TW="描述", en="Description", ja="説明", ru="Описание")
+        label_aliases: I18nKey = I18nKey(default="Aliases", zh_CN="别名", zh_TW="別名", en="Aliases", ja="エイリアス", ru="Псевдонимы")
+        label_usage: I18nKey = I18nKey(default="Usage", zh_CN="用法", zh_TW="用法", en="Usage", ja="使い方", ru="Использование")
+        label_permission: I18nKey = I18nKey(default="Permission", zh_CN="权限", zh_TW="權限", en="Permission", ja="権限", ru="Права")
+        label_group: I18nKey = I18nKey(default="Group", zh_CN="分组", zh_TW="分組", en="Group", ja="グループ", ru="Группа")
+        permission_required: I18nKey = I18nKey(default="Requires permission", zh_CN="需要特殊权限", zh_TW="需要特殊權限", en="Requires permission", ja="特殊権限が必要", ru="Требуются права")
+
+        chip_commands: I18nKey = I18nKey(default="Commands", zh_CN="命令", zh_TW="命令", en="Commands", ja="コマンド", ru="Команды")
+        chip_groups: I18nKey = I18nKey(default="Groups", zh_CN="分组", zh_TW="分組", en="Groups", ja="グループ", ru="Группы")
+
+        err_out_of_range: I18nKey = I18nKey(default="Index out of range", zh_CN="序号超出范围", zh_TW="序號超出範圍", en="Index out of range", ja="番号が範囲外", ru="Номер вне диапазона")
+        err_range_hint: I18nKey = I18nKey(default="Please enter a number between 1 and {count}", zh_CN="请输入 1-{count} 之间的序号", zh_TW="請輸入 1-{count} 之間的序號", en="Please enter a number between 1 and {count}", ja="1〜{count} の番号を入力してください", ru="Введите номер от 1 до {count}")
+        err_invalid_arg: I18nKey = I18nKey(default="Invalid argument", zh_CN="参数错误", zh_TW="參數錯誤", en="Invalid argument", ja="引数エラー", ru="Неверный аргумент")
+        err_invalid_hint: I18nKey = I18nKey(default="Please enter a valid number", zh_CN="请输入有效的序号", zh_TW="請輸入有效的序號", en="Please enter a valid number", ja="有効な番号を入力してください", ru="Введите корректный номер")
+        err_fmt: I18nKey = I18nKey(default="Invalid output format: {fmt}", zh_CN="无效的输出格式：{fmt}", zh_TW="無效的輸出格式：{fmt}", en="Invalid output format: {fmt}", ja="出力形式が無効です: {fmt}", ru="Недопустимый формат вывода: {fmt}")
+        err_unknown: I18nKey = I18nKey(default="Unknown argument: {arg}", zh_CN="未知参数：{arg}", zh_TW="未知參數：{arg}", en="Unknown argument: {arg}", ja="不明な引数: {arg}", ru="Неизвестный аргумент: {arg}")
+        err_img_unavailable: I18nKey = I18nKey(default="Image output unavailable, falling back to text", zh_CN="图片输出不可用，已回退到文本", zh_TW="圖片輸出不可用，已回退到文字", en="Image output unavailable, falling back to text", ja="画像出力は利用できません。テキストにフォールバックします", ru="Вывод изображений недоступен, используется текст")
+
+        cfg_show_hidden: I18nKey = I18nKey(key="HelpNext.cfg_show_hidden", default="Show hidden commands", zh_CN="显示隐藏命令", zh_TW="顯示隱藏命令", en="Show hidden commands", ja="非表示コマンドを表示", ru="Показывать скрытые команды")
+        cfg_group_commands: I18nKey = I18nKey(key="HelpNext.cfg_group_commands", default="Group commands by category", zh_CN="按分组显示命令", zh_TW="按分組顯示命令", en="Group commands by category", ja="カテゴリ別にグループ化", ru="Группировать команды")
+        cfg_theme: I18nKey = I18nKey(key="HelpNext.cfg_theme", default="Image theme", zh_CN="图片主题", zh_TW="圖片主題", en="Image theme", ja="画像テーマ", ru="Тема изображения")
+        cfg_utc_offset: I18nKey = I18nKey(key="HelpNext.cfg_utc_offset", default="UTC offset for day/night switching", zh_CN="UTC 时区偏移（用于昼夜切换）", zh_TW="UTC 時區偏移（用於晝夜切換）", en="UTC offset (day/night switching)", ja="UTCオフセット（昼夜切替用）", ru="Смещение UTC (для смены темы)")
+        cfg_show_logo: I18nKey = I18nKey(key="HelpNext.cfg_show_logo", default="Show ErisPulse icon in header", zh_CN="头部显示 ErisPulse 图标", zh_TW="頭部顯示 ErisPulse 圖示", en="Show ErisPulse icon in header", ja="ヘッダーに ErisPulse アイコンを表示", ru="Показывать иконку ErisPulse в шапке")
+        cfg_header_title: I18nKey = I18nKey(key="HelpNext.cfg_header_title", default="Custom header title (empty for default)", zh_CN="自定义头部标题（留空使用默认）", zh_TW="自訂頭部標題（留空使用預設）", en="Custom header title (empty for default)", ja="カスタムヘッダータイトル（空でデフォルト）", ru="Свой заголовок шапки (пусто = по умолчанию)")
+        cfg_header_subtitle: I18nKey = I18nKey(key="HelpNext.cfg_header_subtitle", default="Custom header subtitle (empty for default)", zh_CN="自定义头部副标题（留空使用默认）", zh_TW="自訂頭部副標題（留空使用預設）", en="Custom header subtitle (empty for default)", ja="カスタムヘッダーサブタイトル（空でデフォルト）", ru="Свой подзаголовок шапки (пусто = по умолчанию)")
+
+        theme_auto: I18nKey = I18nKey(key="HelpNext.theme_auto", default="Auto (by time)", zh_CN="自动（跟随时间）", zh_TW="自動（跟隨時間）", en="Auto (by time)", ja="自動（時間帯）", ru="Авто (по времени)")
+        theme_light: I18nKey = I18nKey(key="HelpNext.theme_light", default="Light", zh_CN="浅色", zh_TW="淺色", en="Light", ja="ライト", ru="Светлая")
+        theme_dark: I18nKey = I18nKey(key="HelpNext.theme_dark", default="Dark", zh_CN="深色", zh_TW="深色", en="Dark", ja="ダーク", ru="Тёмная")
+        group_basic: I18nKey = I18nKey(key="HelpNext.group_basic", default="Basic", zh_CN="基本", zh_TW="基本", en="Basic", ja="基本", ru="Основные")
+        group_render: I18nKey = I18nKey(key="HelpNext.group_render", default="Rendering", zh_CN="渲染", zh_TW="渲染", en="Rendering", ja="レンダリング", ru="Отрисовка")
+        group_header: I18nKey = I18nKey(key="HelpNext.group_header", default="Header", zh_CN="头部", zh_TW="頭部", en="Header", ja="ヘッダー", ru="Шапка")
+
+    def __init__(self):
+        self.sdk = sdk
+        self.logger = sdk.logger.get_child("HelpNext")
+        self.command_map: Dict[int, Dict] = {}
+        self.visualizer = Visualizer(sdk, {})
+        self._help_handler = None
+
+    @staticmethod
+    def get_load_strategy():
+        from ErisPulse.loaders import ModuleLoadStrategy
+        return ModuleLoadStrategy(
+            lazy_load=False,
+            priority=60,
+        )
+
+    async def on_load(self, event):
+        self._help_handler = self._make_handler()
+        command(
+            "help",
+            aliases=["h", "帮助"],
+            help="显示帮助信息",
+            usage="help [序号] [--format <image|html|markdown|text>]",
+        )(self._help_handler)
+        self.logger.info("HelpNext 已加载")
+
+    async def on_unload(self, event):
+        if self._help_handler is not None:
+            command.unregister(self._help_handler)
+        self.logger.info("HelpNext 已卸载")
+        return True
+
+    def _cfg_view(self) -> Dict:
+        cfg = self.cfg
+        return {
+            "show_hidden_commands": cfg.show_hidden_commands,
+            "group_commands": cfg.group_commands,
+            "theme": cfg.theme,
+            "utc_offset": cfg.utc_offset,
+            "show_logo": cfg.show_logo,
+            "header_title": cfg.header_title,
+            "header_subtitle": cfg.header_subtitle,
+        }
+
+    def _all_prefixes(self) -> List[str]:
+        # 读取框架命令处理器维护的前缀（随配置热更新，与命令解析保持一致）
+        prefix = command.prefix
+        if isinstance(prefix, list):
+            return [str(p) for p in prefix] if prefix else ["/"]
+        return [str(prefix)] if prefix else ["/"]
+
+    def _build_command_list(self, event) -> List[Dict]:
+        cfg = self._cfg_view()
+        show_hidden = cfg["show_hidden_commands"]
+        result: List[Dict] = []
+        # 会话感知：按作用域过滤当前会话不可用模块的命令（与框架静默语义一致）
+        names = command.get_commands(event=event) if show_hidden else command.get_visible_commands(event=event)
+        for name in names:
+            info = command.get_command(name, event=event)
+            if info and name == info.get("main_name"):
+                result.append({"name": name, "info": info})
+        return result
+
+    def _make_handler(self):
+        async def help_command(event):
+            await self._handle(event)
+        return help_command
+
+    async def _handle(self, event) -> None:
+        try:
+            args = event.get_command_args()
+            commands = self._build_command_list(event)
+            prefixes = self._all_prefixes()
+            prefix = prefixes[0] if prefixes else "/"
+            cfg = self._cfg_view()
+            self.visualizer.config = cfg
+
+            self._index_commands(commands, cfg["group_commands"])
+
+            index, fmt, err = self._parse_args(args)
+
+            if err:
+                if err[0] == "format":
+                    msg = HelpTemplates._t("err_fmt", fmt=err[1] or "?")
+                else:
+                    msg = HelpTemplates._t("err_unknown", arg=err[1])
+                title = HelpTemplates._t("err_invalid_arg")
+                await self._send(event, HelpTemplates.build_error(title, msg), None, "auto-text")
+                return
+
+            image = None
+            templates = None
+            want_image = fmt in ("auto", "image")
+
+            if index is not None:
+                if index in self.command_map:
+                    cmd = self.command_map[index]
+                    if want_image:
+                        image = self.visualizer.render_command_detail(cmd, prefix, prefixes)
+                    templates = HelpTemplates.build_command_detail(cmd, prefix, prefixes)
+                else:
+                    title = HelpTemplates._t("err_out_of_range")
+                    msg = HelpTemplates._t("err_range_hint", count=len(commands))
+                    if want_image:
+                        image = self.visualizer.render_error(title, msg)
+                    templates = HelpTemplates.build_error(title, msg)
+            else:
+                if want_image:
+                    image = self.visualizer.render_help_list(
+                        commands, self.command_map, prefix, cfg["group_commands"], prefixes,
+                    )
+                templates = HelpTemplates.build_help_list(
+                    commands, self.command_map, prefix, cfg["group_commands"], prefixes,
+                )
+
+            await self._send(event, templates, image, fmt)
+        except Exception as e:
+            self.logger.error(f"处理帮助命令出错: {e}", exc_info=True)
+
+    @staticmethod
+    def _normalize_format(v) -> Optional[str]:
+        v = str(v).lower().strip()
+        return {
+            "image": "image", "img": "image",
+            "html": "html", "h5": "html",
+            "markdown": "markdown", "md": "markdown",
+            "text": "text", "txt": "text",
+        }.get(v)
+
+    @staticmethod
+    def _parse_args(args: List[str]) -> Tuple[Optional[int], str, Optional[Tuple[str, str]]]:
+        index = None
+        fmt = "auto"
+        err = None
+        i, n = 0, len(args)
+        while i < n:
+            low = str(args[i]).lower()
+            if low.isdigit():
+                if index is None:
+                    index = int(low)
+                else:
+                    err = ("unknown", args[i])
+                    break
+            elif low == "--format":
+                if i + 1 < n:
+                    v = Main._normalize_format(args[i + 1])
+                    if v is None:
+                        err = ("format", str(args[i + 1]))
+                        break
+                    fmt = v
+                    i += 1
+                else:
+                    err = ("format", "")
+                    break
+            elif low.startswith("--format="):
+                v = Main._normalize_format(low.split("=", 1)[1])
+                if v is None:
+                    err = ("format", low.split("=", 1)[1])
+                    break
+                fmt = v
+            else:
+                err = ("unknown", args[i])
+                break
+            i += 1
+        return index, fmt, err
+
+    def _index_commands(self, commands: List[Dict], group_commands: bool) -> None:
+        self.command_map = {}
+        grouped: Dict[str, List[Dict]] = {}
+        if group_commands:
+            for cmd in commands:
+                g = cmd["info"].get("group") or "default"
+                grouped.setdefault(g, []).append(cmd)
+        else:
+            grouped["default"] = list(commands)
+        idx = 1
+        for _, cmds in grouped.items():
+            for cmd in cmds:
+                self.command_map[idx] = cmd
+                idx += 1
+
+    @staticmethod
+    def _supports(event, method: str) -> bool:
+        try:
+            return event.supports(method)
+        except Exception:
+            return False
+
+    def _select_text_format(self, event, templates) -> Tuple[str, str]:
+        if self._supports(event, "Html"):
+            return ("Html", templates["html"])
+        if self._supports(event, "Markdown"):
+            return ("Markdown", templates["markdown"])
+        return ("Text", templates["text"])
+
+    async def _send(self, event, templates, image: Optional[bytes], fmt: str) -> None:
+        try:
+            if fmt == "image":
+                if image and self._supports(event, "Image"):
+                    await event.reply(image, method="Image")
+                    return
+                note = HelpTemplates._t("err_img_unavailable")
+                await event.reply(note)
+                return
+
+            if fmt in ("html", "markdown", "text"):
+                await event.reply(templates[fmt], method=fmt.capitalize())
+                return
+
+            if fmt == "auto" and image and self._supports(event, "Image"):
+                try:
+                    await event.reply(image, method="Image")
+                    return
+                except Exception as e:
+                    self.logger.warning(f"图片发送失败，回退到文本: {e}")
+
+            method, content = self._select_text_format(event, templates)
+            try:
+                await event.reply(content, method=method)
+            except Exception:
+                await event.reply(templates["text"])
+        except Exception as e:
+            self.logger.error(f"发送帮助出错: {e}")
+            try:
+                await event.reply(templates["text"])
+            except Exception:
+                pass

HelpNext/Templates.py

@@ -0,0 +1,293 @@
+from typing import Dict, List, Optional
+
+from ErisPulse import i18n
+from ErisPulse.Core.Event import command
+
+class HelpTemplates:
+    """i18n-aware fallback templates (html / markdown / text)."""
+
+    PRIMARY_COLOR = "#0071e3"
+    WARNING_COLOR = "#ff9f0a"
+    ERROR_COLOR = "#ff453a"
+    PRIMARY_BG = "rgba(0, 113, 227, 0.06)"
+
+    @classmethod
+    def _t(cls, key: str, **kwargs) -> str:
+        full = f"HelpNext.{key}"
+        return i18n.t(full, default=full, **kwargs)
+
+    @classmethod
+    def _group_name(cls, group: str) -> str:
+        if not group or group == "default":
+            return cls._t("group_default")
+        return group
+
+    @classmethod
+    def _aliases_of(cls, name: str, info: Dict) -> List[str]:
+        main_name = info.get("main_name", name)
+        return [
+            alias
+            for alias, mapped in command.aliases.items()
+            if mapped == main_name and alias != main_name
+        ]
+
+    @classmethod
+    def _other_prefixes(cls, prefixes: Optional[list], display: str) -> list:
+        if not prefixes or len(prefixes) <= 1:
+            return []
+        return [p for p in prefixes if p != display]
+
+    @classmethod
+    def build_help_list(
+        cls,
+        commands: List[Dict],
+        command_map: Dict[int, Dict],
+        prefix: str,
+        group_commands: bool = True,
+        prefixes: Optional[list] = None,
+    ) -> Dict[str, str]:
+        others = cls._other_prefixes(prefixes or [prefix], prefix)
+        grouped = cls._group(commands, group_commands)
+
+        global_idx = 1
+        for _, cmds in grouped.items():
+            for cmd in cmds:
+                command_map[global_idx] = cmd
+                global_idx += 1
+
+        return {
+            "html": cls._list_html(commands, grouped, command_map, prefix, others),
+            "markdown": cls._list_md(commands, grouped, command_map, prefix, others),
+            "text": cls._list_text(commands, grouped, command_map, prefix, others),
+        }
+
+    @staticmethod
+    def _group(commands: List[Dict], group_commands: bool) -> Dict[str, List[Dict]]:
+        if not group_commands:
+            return {"default": list(commands)}
+        grouped: Dict[str, List[Dict]] = {}
+        for cmd in commands:
+            g = cmd["info"].get("group") or "default"
+            grouped.setdefault(g, []).append(cmd)
+        return grouped
+
+    @classmethod
+    def _list_html(cls, commands, grouped, command_map, prefix, others) -> str:
+        title = cls._t("title")
+        hint = cls._t("usage_hint", prefix=prefix)
+        count = cls._t("command_count", count=len(commands))
+
+        sections = ""
+        for group, cmds in grouped.items():
+            sections += (
+                f'<div style="font-size:13px;margin-bottom:8px;font-weight:600;'
+                f'color:{cls.PRIMARY_COLOR};">{cls._group_name(group)}</div>'
+            )
+            for cmd in cmds:
+                idx = next(
+                    i for i, c in command_map.items() if c["name"] == cmd["name"]
+                )
+                name = cmd["name"]
+                help_text = cmd["info"].get("help") or cls._t("no_description")
+                sections += (
+                    f'<div style="margin-bottom:6px;font-size:13px;">'
+                    f'<b style="margin-right:6px;">{idx}.</b>'
+                    f'<code style="background:rgba(0,0,0,0.05);padding:2px 6px;'
+                    f'border-radius:4px;margin-right:6px;">{prefix}{name}</code>'
+                    f'<span style="color:#666;">- {help_text}</span></div>'
+                )
+            sections += "\n"
+
+        others_html = cls._prefix_note_html(others)
+        return (
+            f'<div style="padding:12px;border-radius:8px;">'
+            f'<div style="color:{cls.PRIMARY_COLOR};font-size:16px;font-weight:700;'
+            f'margin-bottom:12px;">{title}</div>'
+            f'<div style="padding:8px;background:{cls.PRIMARY_BG};border-radius:6px;'
+            f'margin-bottom:12px;font-size:13px;">{hint}</div>'
+            f'{sections}'
+            f'<div style="font-size:12px;color:#666;margin-top:8px;">{count}</div>'
+            f'{others_html}'
+            f'</div>'
+        )
+
+    @classmethod
+    def _list_md(cls, commands, grouped, command_map, prefix, others) -> str:
+        lines = [
+            f"**{cls._t('title')}**",
+            "",
+            cls._t("usage_hint", prefix=prefix),
+            "",
+        ]
+        for group, cmds in grouped.items():
+            lines.append(f"**{cls._group_name(group)}**")
+            lines.append("")
+            for cmd in cmds:
+                idx = next(i for i, c in command_map.items() if c["name"] == cmd["name"])
+                help_text = cmd["info"].get("help") or cls._t("no_description")
+                lines.append(f"{idx}. `{prefix}{cmd['name']}` - {help_text}")
+            lines.append("")
+
+        lines.append("---")
+        lines.append(cls._t("command_count", count=len(commands)))
+        if others:
+            lines.append("")
+            lines.append(f"{cls._t('other_prefixes')}: {'、'.join(others)}")
+        return "\n".join(lines)
+
+    @classmethod
+    def _list_text(cls, commands, grouped, command_map, prefix, others) -> str:
+        lines = [
+            cls._t("title"),
+            "----------",
+            cls._t("usage_hint", prefix=prefix),
+            "",
+        ]
+        for group, cmds in grouped.items():
+            lines.append(f"[{cls._group_name(group)}]")
+            lines.append("")
+            for cmd in cmds:
+                idx = next(i for i, c in command_map.items() if c["name"] == cmd["name"])
+                help_text = cmd["info"].get("help") or cls._t("no_description")
+                lines.append(f"{idx}. {prefix}{cmd['name']} - {help_text}")
+            lines.append("")
+
+        lines.append("----------")
+        lines.append(cls._t("command_count", count=len(commands)))
+        if others:
+            lines.append("")
+            lines.append(f"{cls._t('other_prefixes')}: {'、'.join(others)}")
+        return "\n".join(lines)
+
+    @classmethod
+    def _prefix_note_html(cls, others) -> str:
+        if not others:
+            return ""
+        note = "、".join(f"<code style='font-size:11px;'>{p}</code>" for p in others)
+        return (
+            f'<div style="font-size:11px;color:#999;margin-top:4px;">'
+            f'{cls._t("other_prefixes")}: {note}</div>'
+        )
+
+    @classmethod
+    def build_command_detail(cls, cmd: Dict, prefix: str, prefixes: Optional[list] = None) -> Dict[str, str]:
+        others = cls._other_prefixes(prefixes or [prefix], prefix)
+        return {
+            "html": cls._detail_html(cmd, prefix, others),
+            "markdown": cls._detail_md(cmd, prefix, others),
+            "text": cls._detail_text(cmd, prefix, others),
+        }
+
+    @classmethod
+    def _detail_html(cls, cmd: Dict, prefix: str, others) -> str:
+        name = cmd["name"]
+        info = cmd["info"]
+        title = cls._t("detail_title")
+        parts = [
+            f'<div style="padding:12px;border-radius:8px;">'
+            f'<div style="color:{cls.PRIMARY_COLOR};font-size:16px;font-weight:700;'
+            f'margin-bottom:12px;">{title}: <code style="background:rgba(0,0,0,0.05);'
+            f'padding:2px 6px;border-radius:4px;">{prefix}{name}</code></div>'
+        ]
+
+        parts.append(cls._kv_html(cls._t("label_description"),
+                                  info.get("help") or cls._t("no_description")))
+
+        aliases = cls._aliases_of(name, info)
+        if aliases:
+            parts.append(cls._kv_html(cls._t("label_aliases"),
+                                      ", ".join(f"{prefix}{a}" for a in aliases)))
+
+        if info.get("usage"):
+            parts.append(cls._kv_html(cls._t("label_usage"),
+                                      info["usage"].replace("/", prefix), mono=True))
+
+        if info.get("permission"):
+            parts.append(cls._kv_html(cls._t("label_permission"),
+                                      cls._t("permission_required"), warn=True))
+
+        if info.get("group"):
+            parts.append(cls._kv_html(cls._t("label_group"),
+                                      cls._group_name(info["group"])))
+
+        if others:
+            parts.append(cls._prefix_note_html(others))
+
+        parts.append("</div>")
+        return "\n".join(parts)
+
+    @classmethod
+    def _kv_html(cls, label: str, value: str, mono: bool = False, warn: bool = False) -> str:
+        color = cls.WARNING_COLOR if warn else "inherit"
+        style = "font-family:monospace;background:rgba(0,0,0,0.03);padding:2px 6px;border-radius:4px;" if mono else ""
+        return (
+            f'<div style="margin-bottom:8px;">'
+            f'<div style="font-size:13px;margin-bottom:4px;"><b>{label}:</b></div>'
+            f'<div style="font-size:13px;color:{color};{style}">{value}</div></div>'
+        )
+
+    @classmethod
+    def _detail_md(cls, cmd: Dict, prefix: str, others) -> str:
+        name = cmd["name"]
+        info = cmd["info"]
+        lines = [
+            f"**{cls._t('detail_title')}:** `{prefix}{name}`",
+            "",
+            f"**{cls._t('label_description')}:** {info.get('help') or cls._t('no_description')}",
+            "",
+        ]
+        aliases = cls._aliases_of(name, info)
+        if aliases:
+            lines.append(f"**{cls._t('label_aliases')}:** {', '.join(f'`{prefix}{a}`' for a in aliases)}")
+            lines.append("")
+        if info.get("usage"):
+            lines.append(f"**{cls._t('label_usage')}:** `{info['usage'].replace('/', prefix)}`")
+            lines.append("")
+        if info.get("permission"):
+            lines.append(f"**{cls._t('label_permission')}:** {cls._t('permission_required')}")
+            lines.append("")
+        if info.get("group"):
+            lines.append(f"**{cls._t('label_group')}:** {cls._group_name(info['group'])}")
+            lines.append("")
+        if others:
+            lines.append(f"{cls._t('other_prefixes')}: {'、'.join(others)}")
+        return "\n".join(lines)
+
+    @classmethod
+    def _detail_text(cls, cmd: Dict, prefix: str, others) -> str:
+        name = cmd["name"]
+        info = cmd["info"]
+        lines = [
+            f"{cls._t('detail_title')}: {prefix}{name}",
+            "----------",
+            f"{cls._t('label_description')}: {info.get('help') or cls._t('no_description')}",
+            "",
+        ]
+        aliases = cls._aliases_of(name, info)
+        if aliases:
+            lines.append(f"{cls._t('label_aliases')}: {', '.join(f'{prefix}{a}' for a in aliases)}")
+            lines.append("")
+        if info.get("usage"):
+            lines.append(f"{cls._t('label_usage')}: {info['usage'].replace('/', prefix)}")
+            lines.append("")
+        if info.get("permission"):
+            lines.append(f"{cls._t('label_permission')}: {cls._t('permission_required')}")
+            lines.append("")
+        if info.get("group"):
+            lines.append(f"{cls._t('label_group')}: {cls._group_name(info['group'])}")
+            lines.append("")
+        if others:
+            lines.append(f"{cls._t('other_prefixes')}: {'、'.join(others)}")
+        return "\n".join(lines)
+
+    @classmethod
+    def build_error(cls, title: str, message: str) -> Dict[str, str]:
+        html = (
+            f'<div style="padding:12px;border-radius:8px;">'
+            f'<div style="color:{cls.ERROR_COLOR};font-size:14px;font-weight:700;'
+            f'margin-bottom:8px;">{title}</div>'
+            f'<div style="font-size:13px;">{message}</div></div>'
+        )
+        markdown = f"**{title}**\n\n{message}"
+        text = f"{title}\n\n{message}"
+        return {"html": html, "markdown": markdown, "text": text}

HelpNext/Visualizer.py

@@ -0,0 +1,498 @@
+import base64
+import html
+import math
+import struct
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from ErisPulse import i18n
+from ErisPulse.Core.Event import command
+
+class Visualizer:
+    CARD_WIDTH = 880
+    _PAGE_PAD = 36
+    _CARD_PAD_V = 16
+    _CARD_PAD_H = 18
+    _CARD_GAP = 14
+    _COL_GAP = 14
+    _CARD_BORDER = 2
+    _LOGO_W = 120
+
+    ACCENT = "#0071e3"
+    ACCENT_DARK = "#0a84ff"
+    WARN = "#ff9f0a"
+
+    PALETTE = [
+        "#0a84ff", "#5e5ce6", "#bf5af2", "#ff375f", "#ff9f0a",
+        "#34c759", "#64d2ff", "#30b0c7", "#ff453a", "#8e8e93",
+    ]
+
+    _ICON_PATH = Path(__file__).parent / "assets" / "icon.png"
+    _icon_cache: Optional[Tuple[str, Tuple[int, int]]] = None
+
+    _CSS_TPL = """
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+        font-family: "Noto Sans SC", "Source Han Sans SC", sans-serif;
+        background: __PAGE__; color: __INK__; -webkit-font-smoothing: antialiased;
+        padding: 36px;
+    }
+    .card {
+        background: __CARD__; border: 1px solid __BORDER__; border-radius: 16px;
+        padding: 16px 18px; box-shadow: __SHADOW__; margin-bottom: 12px;
+    }
+    .head-row { display: flex; align-items: center; gap: 14px; }
+    .logo-side { display: block; }
+    .head-text { min-width: 0; }
+    .title { font-size: 20px; font-weight: 700; color: __INK__; letter-spacing: -0.3px; }
+    .subtitle { font-size: 13px; color: __SUB__; margin-top: 2px; }
+    .divider { height: 1px; background: __SEP__; margin: 14px 0; }
+    .chips { display: flex; flex-wrap: wrap; gap: 10px; justify-content: center; }
+    .chip { padding: 7px 14px; border-radius: 9px; font-size: 13px; background: __SOFT__; color: __INK__; border: 1px solid __BORDER__; }
+    .chip b { color: __ACCENT__; font-weight: 600; margin-right: 4px; }
+    .masonry { display: flex; gap: 14px; align-items: flex-start; }
+    .mcol { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 14px; }
+    .mcol .card { margin-bottom: 0; }
+    .cmd-head { display: flex; align-items: center; gap: 10px; }
+    .num {
+        flex: 0 0 26px; width: 26px; height: 26px; border-radius: 8px;
+        background: __ACCENTBG__; border: 1px solid __ACCENTLINE__;
+        color: __ACCENT__; font-size: 12px; font-weight: 700;
+        display: flex; align-items: center; justify-content: center;
+        font-variant-numeric: tabular-nums;
+    }
+    .cmd-code {
+        font-family: "Source Code Pro", monospace; font-size: 13.5px; font-weight: 700;
+        color: __INK__; white-space: nowrap;
+    }
+    .cmd-code .pfx { color: __ACCENT__; font-weight: 600; }
+    .group-tag {
+        margin-left: auto; font-size: 11px; font-weight: 600;
+        padding: 3px 10px; border-radius: 6px; white-space: nowrap;
+        display: inline-flex; align-items: center; gap: 5px;
+    }
+    .group-tag::before {
+        content: ""; width: 6px; height: 6px; border-radius: 50%;
+        background: currentColor; flex: 0 0 auto;
+    }
+    .cmd-desc { font-size: 13px; color: __INK__; margin-top: 8px; line-height: 1.55; }
+    .cmd-aliases { margin-top: 8px; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+    .cmd-aliases .lbl { font-size: 11px; color: __SUB__; margin-right: 2px; }
+    .alias-tag {
+        font-family: "Source Code Pro", monospace; font-size: 12px;
+        background: __CODEBG__; color: __INK__; padding: 3px 9px; border-radius: 6px;
+    }
+    .cmd-usage {
+        margin-top: 8px; font-family: "Source Code Pro", monospace; font-size: 12.5px;
+        background: __CODEBG__; color: __SUB__; padding: 7px 10px; border-radius: 7px;
+        line-height: 1.5;
+    }
+    .detail-label { font-size: 12px; font-weight: 600; color: __SUB__; letter-spacing: 0.6px; margin-bottom: 6px; text-transform: uppercase; }
+    .detail-value { font-size: 15px; color: __INK__; line-height: 1.5; }
+    .detail-value.mono { font-family: "Source Code Pro", monospace; background: __CODEBG__; padding: 8px 12px; border-radius: 8px; font-size: 14px; }
+    .detail-value.warn { color: __WARN__; }
+    .aliases { display: flex; flex-wrap: wrap; gap: 8px; }
+    .foot { font-size: 12.5px; color: __SUB__; text-align: center; margin-top: 14px; line-height: 1.7; }
+    .foot code { color: __ACCENT__; background: __CODEBG__; padding: 2px 7px; border-radius: 5px; font-family: "Source Code Pro", monospace; }
+    .err-title { font-size: 18px; font-weight: 700; color: __WARN__; }
+    .err-msg { font-size: 14px; color: __INK__; margin-top: 8px; line-height: 1.5; }
+    """
+
+    def __init__(self, sdk, config: Dict):
+        self.sdk = sdk
+        self.logger = sdk.logger.get_child("HelpNext.Visualizer")
+        self.config = config
+        self._takumi_inst = None
+
+    @staticmethod
+    def _t(key: str, **kwargs) -> str:
+        full = f"HelpNext.{key}"
+        return i18n.t(full, default=full, **kwargs)
+
+    @property
+    def takumi(self):
+        if self._takumi_inst is None:
+            inst = None
+            try:
+                inst = self.sdk.module.get("Takumi")
+            except Exception:
+                inst = None
+            if inst is None:
+                inst = getattr(self.sdk, "Takumi", None)
+            self._takumi_inst = inst
+        return self._takumi_inst
+
+    def _theme(self) -> Dict:
+        mode = self.config.get("theme", "auto")
+        if mode == "auto":
+            offset = self.config.get("utc_offset", 8)
+            hour = int((time.time() / 3600 + offset) % 24)
+            mode = "dark" if (hour >= 19 or hour < 7) else "light"
+        accent = self.ACCENT_DARK if mode == "dark" else self.ACCENT
+        if mode == "dark":
+            return {
+                "page": "#000000", "card": "#1c1c1e", "ink": "#f5f5f7", "sub": "#8e8e93",
+                "sep": "#38383a", "soft": "#2c2c2e", "codebg": "rgba(255,255,255,0.08)",
+                "accent": accent, "tag_alpha": 0.22, "shadow": "none",
+                "border": "rgba(255,255,255,0.08)",
+                "accentline": self._rgba(accent, 0.35),
+            }
+        return {
+            "page": "#f5f5f7", "card": "#ffffff", "ink": "#1d1d1f", "sub": "#6e6e73",
+            "sep": "#d2d2d7", "soft": "#f5f5f7", "codebg": "rgba(0,0,0,0.05)",
+            "accent": accent, "tag_alpha": 0.12, "shadow": "0 1px 2px rgba(0,0,0,0.04), 0 2px 8px rgba(0,0,0,0.04)",
+            "border": "rgba(0,0,0,0.06)",
+            "accentline": self._rgba(accent, 0.25),
+        }
+
+    def _css(self) -> Tuple[str, Dict]:
+        t = self._theme()
+        css = (
+            self._CSS_TPL
+            .replace("__PAGE__", t["page"]).replace("__CARD__", t["card"])
+            .replace("__INK__", t["ink"]).replace("__SUB__", t["sub"])
+            .replace("__SEP__", t["sep"]).replace("__SOFT__", t["soft"])
+            .replace("__CODEBG__", t["codebg"]).replace("__ACCENT__", t["accent"])
+            .replace("__ACCENTBG__", self._rgba(t["accent"], t["tag_alpha"]))
+            .replace("__ACCENTLINE__", t["accentline"])
+            .replace("__BORDER__", t["border"])
+            .replace("__SHADOW__", t["shadow"])
+        )
+        return css, t
+
+    @staticmethod
+    def _rgba(hexcolor: str, alpha: float) -> str:
+        h = hexcolor.lstrip("#")
+        r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+        return f"rgba({r},{g},{b},{alpha})"
+
+    @staticmethod
+    def _png_dims(data: bytes) -> Optional[Tuple[int, int]]:
+        try:
+            if data[:8] != b"\x89PNG\r\n\x1a\n":
+                return None
+            w, h = struct.unpack(">II", data[16:24])
+            return w, h
+        except Exception:
+            return None
+
+    @classmethod
+    def _icon(cls) -> Optional[Tuple[str, Tuple[int, int]]]:
+        if cls._icon_cache is None:
+            try:
+                data = cls._ICON_PATH.read_bytes()
+                dims = cls._png_dims(data)
+                b64 = base64.b64encode(data).decode()
+                cls._icon_cache = (b64, dims) if dims else ("", None)
+            except Exception:
+                cls._icon_cache = ("", None)
+        b64, dims = cls._icon_cache
+        if not b64 or not dims:
+            return None
+        return b64, dims
+
+    @staticmethod
+    def _esc(text) -> str:
+        return html.escape(str(text))
+
+    @staticmethod
+    def _text_lines(text: str, width: int, cjk_w: float = 13.0, latin_w: float = 7.5) -> int:
+        w = sum(cjk_w if ord(c) > 0x2E80 else latin_w for c in str(text))
+        return max(1, math.ceil(w / max(1, width)))
+
+    @staticmethod
+    def _aliases_of(name: str, info: Dict) -> List[str]:
+        main_name = info.get("main_name", name)
+        return [
+            a for a, m in command.aliases.items()
+            if m == main_name and a != main_name
+        ]
+
+    def _render(self, body_html: str, height: int) -> Optional[bytes]:
+        takumi = self.takumi
+        if takumi is None or not hasattr(takumi, "render_html"):
+            self.logger.warning("Takumi 不可用，跳过图片渲染")
+            return None
+        css, _ = self._css()
+        try:
+            return takumi.render_html(
+                body_html, stylesheets=[css],
+                width=self.CARD_WIDTH, height=height, lang="zh-CN",
+            )
+        except Exception as e:
+            self.logger.error(f"Takumi 渲染失败: {e}")
+            return None
+
+    def _card(self, inner: str) -> str:
+        return f"<div class='card'>{inner}</div>"
+
+    def _h_card(self, inner_h: int) -> int:
+        return self._CARD_PAD_V * 2 + inner_h + self._CARD_BORDER + self._CARD_GAP
+
+    def _total_height(self, block_heights: List[int], footer_h: int = 0) -> int:
+        return self._PAGE_PAD * 2 + sum(block_heights) + footer_h + 16
+
+    @staticmethod
+    def _num_cols(count: int) -> int:
+        if count <= 8:
+            return 1
+        if count <= 24:
+            return 2
+        return 3
+
+    def _header(self, subtitle: str, chips_html: str) -> Tuple[str, int]:
+        cfg = self.config
+        show_logo = cfg.get("show_logo", True)
+        title = cfg.get("header_title") or "ErisPulse"
+        sub = cfg.get("header_subtitle") or subtitle
+
+        logo_html = ""
+        logo_h = 0
+        if show_logo:
+            icon = self._icon()
+            if icon:
+                b64, (nw, nh) = icon
+                dw = self._LOGO_W
+                dh = round(nh * dw / nw)
+                logo_html = (
+                    f"<img class='logo-side' src='data:image/png;base64,{b64}' "
+                    f"width='{dw}' height='{dh}' alt='ErisPulse'/>"
+                )
+                logo_h = dh
+
+        text_html = (
+            f"<div class='head-text'><div class='title'>{self._esc(title)}</div>"
+            f"<div class='subtitle'>{self._esc(sub)}</div></div>"
+        )
+        inner = (
+            f"<div class='head-row'>{logo_html}{text_html}</div>"
+            f"<div class='divider'></div>{chips_html}"
+        )
+        row_h = max(logo_h, 44)
+        inner_h = row_h + 33 + 32
+        return inner, inner_h
+
+    def _chips(self, cmd_count: int, group_count: Optional[int] = None) -> str:
+        s = (
+            f"<div class='chips'>"
+            f"<div class='chip'><b>{cmd_count}</b>{self._esc(self._t('chip_commands'))}</div>"
+        )
+        if group_count is not None:
+            s += f"<div class='chip'><b>{group_count}</b>{self._esc(self._t('chip_groups'))}</div>"
+        s += "</div>"
+        return s
+
+    def _command_card(
+        self,
+        cmd: Dict,
+        idx: int,
+        prefix: str,
+        t: Dict,
+        avail: int,
+        group_color: Optional[str] = None,
+        show_group: bool = False,
+    ) -> Tuple[str, int]:
+        info = cmd["info"]
+        name = cmd["name"]
+        desc = info.get("help") or self._t("no_description")
+
+        head = f"<div class='cmd-head'><div class='num'>{idx}</div>"
+        head += (
+            f"<div class='cmd-code'><span class='pfx'>{self._esc(prefix)}</span>"
+            f"{self._esc(name)}</div>"
+        )
+        if show_group and info.get("group") and group_color:
+            gname = self._t("group_default") if info["group"] == "default" else info["group"]
+            bg = self._rgba(group_color, t["tag_alpha"])
+            head += f"<span class='group-tag' style='color:{group_color};background:{bg}'>{self._esc(gname)}</span>"
+        head += "</div>"
+
+        desc_html = f"<div class='cmd-desc'>{self._esc(desc)}</div>"
+        desc_h = 8 + self._text_lines(desc, avail) * 20
+
+        extra_html = ""
+        extra_h = 0
+        aliases = self._aliases_of(name, info)
+        if aliases:
+            tags = "".join(
+                f"<span class='alias-tag'>{self._esc(prefix)}{self._esc(a)}</span>"
+                for a in aliases
+            )
+            extra_html += (
+                f"<div class='cmd-aliases'><span class='lbl'>{self._esc(self._t('label_aliases'))}</span>"
+                f"{tags}</div>"
+            )
+            a_w = sum((len(prefix) + len(a)) * 7.5 + 18 + 6 for a in aliases)
+            a_rows = max(1, math.ceil(a_w / max(1, avail)))
+            extra_h += 8 + a_rows * 24
+        if info.get("usage"):
+            usage = info["usage"].replace("/", prefix)
+            extra_html += f"<div class='cmd-usage'>{self._esc(usage)}</div>"
+            extra_h += 22 + self._text_lines(usage, avail, cjk_w=12.5, latin_w=7.5) * 19
+
+        inner = head + desc_html + extra_html
+        inner_h = 24 + desc_h + extra_h
+        return inner, inner_h
+
+    def _masonry(self, items: List[Tuple[str, int]], num_cols: int) -> Tuple[str, int]:
+        cols: List[List[str]] = [[] for _ in range(num_cols)]
+        col_h = [0] * num_cols
+        for html, inner_h in items:
+            card_h = inner_h + self._CARD_PAD_V * 2 + self._CARD_BORDER
+            c = min(range(num_cols), key=lambda i: col_h[i])
+            cols[c].append(html)
+            col_h[c] += card_h + self._COL_GAP
+        heights = [max(0, ch - self._COL_GAP) for ch in col_h]
+        inner = "".join(f"<div class='mcol'>{''.join(col)}</div>" for col in cols)
+        return f"<div class='masonry'>{inner}</div>", max(heights)
+
+    def render_help_list(
+        self,
+        commands: List[Dict],
+        command_map: Dict[int, Dict],
+        prefix: str,
+        group_commands: bool,
+        prefixes: Optional[list] = None,
+    ) -> Optional[bytes]:
+        if not commands:
+            return None
+
+        others = [
+            p for p in (prefixes or [prefix])
+            if p != prefix and len(prefixes or []) > 1
+        ]
+
+        num_cols = self._num_cols(len(commands))
+        avail = int(
+            (self.CARD_WIDTH - self._PAGE_PAD * 2 - self._COL_GAP * (num_cols - 1))
+            / num_cols - self._CARD_PAD_H * 2 - 2
+        )
+        _, t = self._css()
+
+        grouped: Dict[str, List[Dict]] = {}
+        for cmd in commands:
+            g = cmd["info"].get("group") or "default"
+            grouped.setdefault(g, []).append(cmd)
+
+        group_colors: Dict[str, str] = {}
+        for g in grouped:
+            group_colors[g] = self.PALETTE[len(group_colors) % len(self.PALETTE)]
+
+        ordered: List[Dict] = []
+        for g, cmds in grouped.items():
+            ordered.extend(cmds)
+
+        for i, cmd in enumerate(ordered, start=1):
+            command_map[i] = cmd
+
+        chips = self._chips(len(commands), len(grouped) if group_commands else None)
+        head_inner, head_h = self._header(self._t("title"), chips)
+
+        items = []
+        for i, cmd in enumerate(ordered, start=1):
+            g = cmd["info"].get("group") or "default"
+            color = group_colors[g] if group_commands else None
+            inner, inner_h = self._command_card(
+                cmd, i, prefix, t, avail,
+                group_color=color, show_group=group_commands,
+            )
+            items.append((self._card(inner), inner_h))
+
+        masonry_html, masonry_h = self._masonry(items, num_cols)
+
+        foot_lines = [self._t("command_count", count=len(commands))]
+        if others:
+            foot_lines.append(f"{self._t('other_prefixes')}: {'、'.join(others)}")
+        footer = "<div class='foot'>" + "<br>".join(foot_lines) + "</div>"
+        footer_h = 34 + (20 if others else 0)
+
+        body = self._card(head_inner) + masonry_html + footer
+        height = self._total_height([self._h_card(head_h), masonry_h], footer_h)
+        return self._render(body, height)
+
+    def render_command_detail(
+        self,
+        cmd: Dict,
+        prefix: str,
+        prefixes: Optional[list] = None,
+    ) -> Optional[bytes]:
+        name = cmd["name"]
+        info = cmd["info"]
+        others = [
+            p for p in (prefixes or [prefix])
+            if p != prefix and len(prefixes or []) > 1
+        ]
+
+        chips = (
+            f"<div class='chips'>"
+            f"<div class='chip'><code style='font-family:Source Code Pro,monospace;'>"
+            f"{self._esc(prefix)}{self._esc(name)}</code></div></div>"
+        )
+        head_inner, head_h = self._header(self._t("detail_title"), chips)
+
+        blocks = [(self._card(head_inner), self._h_card(head_h))]
+
+        def add_card(label: str, value_html: str, value_h: int, value_class: str = ""):
+            vc = f" {value_class}" if value_class else ""
+            inner = (
+                f"<div class='detail-label'>{self._esc(label)}</div>"
+                f"<div class='detail-value{vc}'>{value_html}</div>"
+            )
+            blocks.append((self._card(inner), self._h_card(30 + value_h)))
+
+        add_card(
+            self._t("label_description"),
+            self._esc(info.get("help") or self._t("no_description")),
+            24,
+        )
+
+        aliases = self._aliases_of(name, info)
+        if aliases:
+            tags = "".join(
+                f"<span class='alias-tag'>{self._esc(prefix)}{self._esc(a)}</span>"
+                for a in aliases
+            )
+            add_card(self._t("label_aliases"), f"<div class='aliases'>{tags}</div>", 32)
+
+        if info.get("usage"):
+            add_card(
+                self._t("label_usage"),
+                self._esc(info["usage"].replace("/", prefix)),
+                24,
+                value_class="mono",
+            )
+
+        if info.get("permission"):
+            add_card(
+                self._t("label_permission"),
+                self._esc(self._t("permission_required")),
+                22,
+                value_class="warn",
+            )
+
+        if info.get("group"):
+            gname = self._t("group_default") if info["group"] == "default" else info["group"]
+            add_card(self._t("label_group"), self._esc(gname), 22)
+
+        footer, footer_h = "", 0
+        if others:
+            footer = (f"<div class='foot'>{self._t('other_prefixes')}: "
+                      f"{'、'.join(self._esc(p) for p in others)}</div>")
+            footer_h = 40
+
+        body = "".join(h for h, _ in blocks) + footer
+        height = self._total_height([b for _, b in blocks], footer_h)
+        return self._render(body, height)
+
+    def render_error(self, title: str, message: str) -> Optional[bytes]:
+        head_inner, head_h = self._header(self._t("title"), "")
+        err = (f"<div class='err-title'>{self._esc(title)}</div>"
+               f"<div class='err-msg'>{self._esc(message)}</div>")
+        blocks = [
+            (self._card(head_inner), self._h_card(head_h)),
+            (self._card(err), self._h_card(70)),
+        ]
+        body = "".join(h for h, _ in blocks)
+        height = self._total_height([b for _, b in blocks])
+        return self._render(body, height)

HelpNext/__init__.py

@@ -0,0 +1,3 @@
+from .Core import Main
+
+__all__ = ["Main"]

erispulse_helpnext-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: ErisPulse-HelpNext
+Version: 0.1.0
+Summary: Modern help command module for ErisPulse, full i18n (requires ErisPulse 2.8.0+)
+Project-URL: homepage, https://github.com/wsu2059q/ErisPulse-HelpNext
+Author-email: wsu2059q <wsu2059@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ErisPulse,HelpModule,Takumi,help,i18n
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Requires-Dist: erispulse-takumi
+Description-Content-Type: text/markdown
+
+# ErisPulse-HelpNext
+
+<div align="center">
+  <img src=".github/assets/ErisPulseLogo.png" width="140" alt="ErisPulse" />
+</div>
+
+Renders the ErisPulse `/help` command as a card image via [ErisPulse-Takumi](https://pypi.org/project/ErisPulse-Takumi/), with day/night theme and multilingual support. Requires ErisPulse 2.8.0+.
+
+[English](#english) | [简体中文](#简体中文)
+
+---
+
+<a id="english"></a>
+
+## English
+
+> 2.8.0+ recommends this module. The classic [`ErisPulse-HelpModule`](https://pypi.org/project/ErisPulse-HelpModule/) is still maintained for backward compatibility. Both register `/help`, so enable only one.
+
+### Features
+
+- Day/night theme by local time (19–7 dark), or pin light / dark
+- Multilingual: zh-CN / zh-TW / en / ja / ru (declarative `I18nClass`)
+- Session-aware listing: commands from modules disabled by scope in the current session are hidden
+- Falls back to Html → Markdown → Text when images aren't supported
+- Declarative config (`ConfigClass`), descriptions also translated
+
+### Install
+
+```bash
+epsdk install HelpNext
+```
+
+### Commands
+
+```
+/help                        List all available commands (card image)
+/help <index>                Show detail of the command at <index>
+/help --format <fmt>         Force output format: image | html | markdown | text
+```
+
+Aliases: `/h`, `/帮助`
+
+### Config
+
+First load writes defaults; edit the `HelpNext` section:
+
+```toml
+[HelpNext]
+show_hidden_commands = false   # show commands marked hidden
+group_commands = true          # group commands by category
+theme = "auto"                 # auto | light | dark
+utc_offset = 8                 # UTC offset for day/night switching
+show_logo = true               # show ErisPulse icon in header
+header_title = ""              # custom header title (empty = default)
+header_subtitle = ""           # custom header subtitle (empty = default)
+```
+
+- `show_hidden_commands`: when `true`, shows commands marked as hidden
+- `group_commands`: when `false`, lists all commands in a single group
+- `theme`: `auto` (by time), or fixed `light` / `dark`
+- `utc_offset`: UTC offset used for day/night detection
+- `show_logo`: show the ErisPulse icon in the header
+- `header_title` / `header_subtitle`: customize the header text (empty = defaults)
+
+### Dependencies
+
+- ErisPulse SDK 2.8.0+
+- [ErisPulse-Takumi](https://pypi.org/project/ErisPulse-Takumi/) (declared as a dependency, auto-installed)
+
+---
+
+<a id="简体中文"></a>
+
+## 简体中文
+
+> 2.8.0+ 推荐使用本模块；经典版 [ErisPulse-HelpModule](https://pypi.org/project/ErisPulse-HelpModule/) 继续维护，用于向后兼容。两者都注册 `/help`，请按需启用其一。
+
+### 功能特性
+
+- 按本地时间自动切换昼夜主题（19–7 点深色），也可固定为浅色 / 深色
+- 多语言：zh-CN / zh-TW / en / ja / ru（声明式 `I18nClass`）
+- 会话感知列表：被作用域禁用的模块，其命令不在当前会话的帮助中列出
+- 平台不支持图片时按 Html → Markdown → 文本 回退
+- 声明式配置（`ConfigClass`），配置描述同样支持多语言
+
+### 安装
+
+```bash
+epsdk install HelpNext
+```
+
+### 命令
+
+```
+/help                        列出所有可用命令（卡片图片）
+/help <序号>                  查看指定序号命令的详情
+/help --format <格式>         指定输出格式：image | html | markdown | text
+```
+
+别名：`/h`、`/帮助`
+
+### 配置选项
+
+首次加载会写入默认配置，可在 ErisPulse 配置的 `HelpNext` 节修改：
+
+```toml
+[HelpNext]
+show_hidden_commands = false   # 是否显示隐藏命令
+group_commands = true          # 是否按分组显示
+theme = "auto"                 # auto | light | dark
+utc_offset = 8                 # 昼夜切换用的时区偏移
+show_logo = true               # 头部是否显示 ErisPulse 图标
+header_title = ""              # 自定义头部标题（留空使用默认）
+header_subtitle = ""           # 自定义头部副标题（留空使用默认）
+```
+
+- `show_hidden_commands`：设为 `true` 时显示标记为隐藏的命令
+- `group_commands`：设为 `false` 时不分组，所有命令在同一列表
+- `theme`：图片主题，`auto` 跟随时间，或固定 `light` / `dark`
+- `utc_offset`：昼夜判定使用的 UTC 时区偏移
+- `show_logo`：头部是否显示 ErisPulse 图标
+- `header_title` / `header_subtitle`：自定义头部标题 / 副标题（留空使用默认）
+
+### 依赖
+
+- ErisPulse SDK 2.8.0+
+- [ErisPulse-Takumi](https://pypi.org/project/ErisPulse-Takumi/)（已声明为依赖，自动安装）

erispulse_helpnext-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+HelpNext/Core.py,sha256=pvzCIgDvHCxLRo1nBeqjmII5dVbiZjWvS65W4N4_fxU,20323
+HelpNext/Templates.py,sha256=TjOKE0XRTsp03_JMXwTBmjUsZ0EdR71pcJJvI6VhtYU,11686
+HelpNext/Visualizer.py,sha256=fIqdEVCmCeU82yuDFubgGTnZ_Cxe3D6UmDoAfAk3Fhw,19543
+HelpNext/__init__.py,sha256=ZiKcK7IRyOCxNl_-TYuzKuTnz7YDQbkEDKZ0U6GVSks,43
+HelpNext/assets/icon.png,sha256=vXYncrvAc42m6Ra5V8dpZTpZ73T7XmutozyI5bLV4P4,87722
+erispulse_helpnext-0.1.0.dist-info/METADATA,sha256=Ye0p7y8Av3rLi1iwWC8-IIdobtSaQPGv-pTwzBIWuwA,5411
+erispulse_helpnext-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+erispulse_helpnext-0.1.0.dist-info/entry_points.txt,sha256=DyXAx3ALy7r4F-iHdgFKamsU3pnf9VNgHTo2bgmUl08,44
+erispulse_helpnext-0.1.0.dist-info/licenses/LICENSE,sha256=7BKmRD_5YpTGfc12w9L3TIskHF3A_AWDU4xuDQKE92w,1055
+erispulse_helpnext-0.1.0.dist-info/RECORD,,

erispulse_helpnext-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

erispulse_helpnext-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[erispulse.module]
+HelpNext = HelpNext:Main

erispulse_helpnext-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 wsu2059q
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.