maimai993/koishi-plugin-help-md

koishi-plugin-help-md

npm

以 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