koishi-plugin-help-md
以 Markdown 卡片（仅 QQ 官方机器人） + 按插件/外显名分组的形式发送 help 菜单，支持分页、一键“全部展示”、定时自动撤回与“任意指令提前撤回”。
本插件基于 koishi-plugin-help-markdown 修改而来。
特性
- QQ 原生 Markdown 菜单：菜单以 Markdown 卡片下发；
- mqqapi 行内指令：菜单里的指令名可点击，点击后把指令文字填入输入框；
- 按插件分组 / 外显名分组：真实指令按插件名分组，自定义指令按“外显名”分组；
- 分页：超出每页行数自动分页，附带
上一页 / 下一页按钮； - 全部展示：底部
全部展示按钮或help -a，一次发送全部内容； - 自动撤回：可设置帮助消息在 N 秒后自动撤回（QQ 约 2 分钟后不可撤回，上限 100 秒）；
- 任意指令提前撤回：某用户查看帮助后，再次触发任意指令时，可立即撤回之前的帮助消息；
- 自定义指令：默认不注册为指令、仅展示在帮助列表；可选同时注册并发送自定义 Markdown 内容。
指令用法
| 输入 | 说明 |
|---|---|
/help |
显示第 1 页帮助菜单 |
/help 2 或 /help -p 2 |
跳转到第 2 页 |
/help -a |
全部展示（不分页，一次发送全部内容） |
/help <指令名> |
查看某个指令的详细用法 |
/help <插件名/分类名> |
只看该插件/分类下的指令 |
任意指令名尾部加
-h也会跳到该指令的详细帮助页。
菜单每页底部都会提示：
输入
/help <指令名>查看特定指令的语法和使用示例。
配置项
基本展示
| 配置 | 默认 | 说明 |
|---|---|---|
helpTitle |
帮助中心 |
帮助菜单顶部标题文字 |
helpDescription |
欢迎使用机器人服务，以下为指令列表： |
标题下方的说明文字，可留空不显示 |
pageSize |
12 |
每页最大行数（含分组标题），超出自动分页；数字输入框 |
过滤与命名
| 配置 | 默认 | 说明 |
|---|---|---|
filterMode |
blacklist |
blacklist 排除指定插件 / whitelist 仅显示指定插件 |
pluginList |
["help-md"] |
配合 filterMode 使用的插件 ID 列表（默认排除本插件自身） |
pluginNameMapping |
{} |
插件外显名映射，例如 { "help": "帮助" } 可让分组标题显示为中文 |
自动撤回
| 配置 | 默认 | 说明 |
|---|---|---|
showAllRecallSeconds |
0 |
帮助消息发送后多少秒自动撤回；0 表示不撤回；QQ 约 2 分钟后无法撤回，故最大 100 |
showAllEarlyRecall |
true |
开启后，该用户之后触发任意指令（斜杠、前缀指令、上一页/下一页等）时，立即撤回之前的帮助消息 |
撤回对所有帮助消息生效：分页页、全部展示、插件分组页、指令详情页、自定义帮助页。
自定义指令 markdownCommands
每条字段：
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 指令名，例如 rules；首词为 help 的条目作为自定义帮助页，不会被注册 |
aliases |
否 | 指令别名列表 |
group |
否 | 外显名（帮助列表中的分组名）；留空归入「自定义指令」分组 |
register |
否 | 是否同时注册为可执行指令。默认 false：不注册，仅在帮助列表中展示 |
markdown |
否 | 指令执行后发送的 Markdown 内容；可留空，留空则执行后不发送任何内容（即使已注册也一样） |
fillText |
否 | 帮助列表中点击该指令后填入客户端输入框的文字；留空默认 /指令名 |
自定义指令展示效果
### [ 群规 ]
- rules（别名：r）
- help
### [ 自定义指令 ]
- about
- 相同
group的条目会合并到同一个### [ 外显名 ]分组下； - 指令行在 QQ 原生 Markdown 下为可点击的 mqqapi 行内指令，点击后在输入框填入
fillText。
完整示例
plugins:
help-md:
pageSize: 10
helpTitle: 指令大全
helpDescription: 发送 /help <指令名> 查看具体用法
showAllRecallSeconds: 60
showAllEarlyRecall: true
filterMode: blacklist
pluginList:
- help-md
pluginNameMapping:
help: 基础帮助
markdownCommands:
- name: rules
aliases: [rule, rg]
group: 群规
fillText: /rules
register: false
markdown: |
# 群规
- 第一条
- name: about
group: 群规
register: true
markdown: |
# 关于本群
...
- name: help # 自定义帮助页（首词为 help）
markdown: |
## 自定义菜单
...
行为说明与限制
- Markdown 卡片与按钮仅在 QQ 平台生效；非 QQ 平台自动降级为纯文本。
- 自动撤回需要获取到发送消息的 ID，仅 QQ 原生 Markdown 消息可满足；纯文本平台无法自动撤回。
- QQ 平台超过约 2 分钟的消息无法撤回，因此
showAllRecallSeconds上限为100。 - “任意指令提前撤回”依赖适配器
deleteMessage能力，并同时使用了before('command/execute')与中间件两层监听兜底。
License
MIT
演示
触发任意指令撤回上一条帮助信息
