koishi-plugin-menu

现代化的可视化帮助菜单插件，提供美观直观的命令展示界面，支持分组与背景图片

功能特性

• 🎨 美观的界面设计 - 现代化的卡片布局，渐变背景和圆角设计
• 📱 响应式布局 - 自适应移动端和桌面端显示，支持网格布局
• 🌐 多语言支持 - 支持 Koishi 的国际化系统，自动检测会话语言
• 🔧 灵活的数据源 - 支持文件缓存和内存实时读取两种模式
• 🎯 智能权限过滤 - 自动过滤用户无权限的命令和选项
• 📦 智能命令管理 - 支持命令分组、隐藏选项和子命令展示
• 🖼️ 图片渲染 - 基于 Puppeteer 的高质量图片输出
• 🔍 详情页支持 - 显示命令的详细用法、选项和示例
• ⚡ 智能缓存 - 支持图片缓存，MD5 哈希键防重复生成
• 🎛️ 高度可定制 - 支持自定义 CSS、毛玻璃效果和背景图片
• 🔄 自动调用 - 无 action 命令自动显示帮助页面
• 🏷️ 命令扩展 - 支持为命令和选项添加自定义属性

使用方法

menu              # 显示所有可用命令的菜单
menu <命令名>      # 显示指定命令的详细信息
menu -H           # 显示所有命令和选项（包括隐藏项）
menu -c           # 清理缓存并重新生成
menu <命令名> -c   # 清理指定命令的缓存并重新生成

配置选项

数据源配置

• source: 命令数据源类型
  • inline: 内存实时读取，数据更新及时 (默认)
  • file: 本地文件缓存，性能更好，支持多语言文件
• enableCache: 是否启用图片缓存 (默认 true)

样式配置

• padding: 内边距大小，单位 px (默认 16)
• radius: 圆角大小，单位 px (默认 12)
• glassBlur: 毛玻璃模糊强度，单位 px，0 表示关闭 (默认 0)
• fontSize: 基础字体大小，单位 px (默认 24)
• titleSize: 标题字体大小倍数 (默认 2)

页面配置

• fontlink: 自定义字体的 URL 链接（支持 Google Fonts 等）
• bgimg: 背景图片文件名或完整 URL 地址
• header: 页头 HTML 内容（支持 HTML 标签）
• footer: 页脚 HTML 内容 (默认为空)
• customCss: 自定义 CSS 样式（可覆盖默认样式）

颜色配置

• primary: 主色调 (默认 rgba(139, 92, 246, 1))
• secondary: 副色调 (默认 rgba(56, 189, 248, 1))
• bgColor: 背景色 (默认 rgba(254, 254, 254, 1))
• textColor: 文本色 (默认 rgba(100, 116, 139, 1))

高级功能

自动命令调用

当用户输入没有 action 的命令时，插件会自动调用 menu <命令名> 显示该命令的详细帮助。这对于提供更好的用户体验非常有用。

智能缓存系统

• 基于命令内容、配置和命令列表生成 MD5 哈希缓存键
• 支持按命令名称清理特定缓存
• 缓存文件存储在 data/menu/cache/ 目录
• 可通过 -c 选项强制刷新缓存
• 缓存键格式：<命令名>_<12位哈希>.png

文件存储管理

插件提供完整的文件存储解决方案：

• 命令数据存储：data/menu/commands.json 或 data/menu/commands-<locale>.json
• 缓存文件：data/menu/cache/ 目录
• 本地资源：支持相对路径，自动转换为 file:// 协议
• 路径解析：支持 URL 和本地文件混合使用

权限系统

插件完全集成 Koishi 权限系统：

• 根据用户权限等级自动过滤命令
• 支持命令级和选项级权限控制
• 隐藏的命令和选项可通过 -H 参数强制显示
• 子命令继承父命令权限设置

多语言支持

• 自动检测会话语言（支持频道、群组、用户语言设置）
• 支持 i18n 国际化文本
• 多语言命令数据分别缓存
• 回退机制：zh-CN → en-US → 默认语言

样式定制

毛玻璃效果

启用毛玻璃效果时，建议配合背景图片使用：

自定义 CSS

可以通过 customCss 配置覆盖默认样式：

响应式设计

插件内置响应式断点：

• 桌面端：自动网格布局，最小列宽 200px
• 平板端（≤768px）：最小列宽 180px
• 移动端（≤480px）：单列布局