koishi-plugin-ll-group-welcome

适配 QQ 官方机器人的 入群欢迎 / 机器人入群通知 插件,支持按群定制不同的通知模板。

本版本在 0.0.1 基础上裁剪:已移除「成员退群通知」与「机器人被移出群通知」,新增按群定制模板能力。

功能

• 新成员入群自动发送欢迎消息(支持 Markdown、@ 新成员)
• 机器人被加入群时发送入群通知(默认关闭,需订阅 GROUP_ADD_ROBOT intent;用事件的 event_id 做被动回复,无需主动消息权限也能喊话)
• 按群定制:不同群可配置不同的欢迎 / 机器人入群模板,未配置的群使用默认模板
• Markdown 发送失败自动回退纯文本
• 主动消息受限错误码静默处理,不刷日志
• welcome-preview 命令预览/实测模板

需要订阅的 intents

• GROUP_MEMBER_ADD(成员入群欢迎)
• GROUP_ADD_ROBOT(机器人入群通知,可选)

配置项

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | enableWelcome | boolean | true | 是否启用新成员欢迎消息 | | enableRobotJoinNotify | boolean | false | 是否启用机器人入群通知 | | welcomeTemplate | string | 见下 | 默认欢迎模板 | | robotJoinTemplate | string | 见下 | 默认机器人入群模板 | | groupList | string[] | [] | 生效群 openid 列表,留空表示所有群 | | groupTemplates | GroupTemplate[] | [] | 按群定制模板(见下) | | useMarkdown | boolean | true | 是否使用 Markdown,关闭后发纯文本 | | atNewMember | boolean | true | 欢迎时是否 @ 新成员(仅 Markdown 生效) | | fetchNickname | boolean | false | 是否通过 QQ 开放平台 API 获取昵称 | | cacheTTL | number | 600 | 昵称缓存秒数,0 不缓存 | | debugLog | boolean | false | 是否输出调试日志 |

模板占位符:{userAt}、{userId}、{userIdShort}、{userName}、{guildId}、{guildName}、{operatorAt}、{operatorId}、{operatorName}、{time}、{date}。

按群定制:在设置页里配置

所有配置(包括按群定制)都在 Koishi 设置页中完成,无需编辑任何配置文件。设置页由插件的配置项自动生成,安装插件后打开「插件配置」即可看到。

在设置页的「按群定制」列表中,点「添加」即可配置一套「欢迎模板+按钮」,一个条目可以应用到多个群。每个条目包含:

| 字段 | 说明 | | --- | --- | | guildIds | 群 openid 列表(可填多个),这一套模板+按钮应用于这些群 | | remark | 备注(可选),如「小助手群」,方便区分 | | welcomeTemplate | 该组群专属欢迎模板,留空使用上方「默认欢迎模板」 | | buttons | 该组群欢迎消息底部按钮(留空则使用全局按钮) |

• 按群定制只针对「人加群」的欢迎;机器人入群通知始终用全局模板,不在按群定制里配置(且已定制群不再发机器人入群通知)。
• 几个群要同一套欢迎+按钮:把它们 openid 都填进一个条目的 guildIds 即可,不必一个群一个条目
• 想给不同群不同文案,就添加多个条目,各自的 guildIds 填对应的群
• 添加过条目的群,即使不在 groupList 中也会自动生效
• 群 openid 可以在调试日志中看到,或从 QQ 开放平台控制台获取

⚠️ 0.0.4 起,原字段 guildId(单个群)已改为 guildIds(多个群),升级后需重新填一下。0.0.9 起按群定制移除了 robotJoinTemplate(机器人入群统一走全局)。

消息按钮(buttons)

设置页里的「消息按钮」列表可为欢迎消息底部添加可点击的按钮(如「点此下载」「点此购买」)。每个条目含:

| 字段 | 说明 | | --- | --- | | label | 按钮文字(必填) | | url | 点击跳转的网址(必填) | | style | 0 灰色线框 / 1 蓝色线框(默认 1) |

• 最多添加 5 个按钮,按行排列在消息底部
• ⚠️ 前提:QQ 开放平台「消息按钮」能力需要内邀开通(或申请按钮模版),否则按钮不会显示。
• 若机器人没权限导致带按钮的消息发送失败,插件会自动重试去掉按钮的 markdown并保留样式,再不行才回退纯文本,不会崩。

权限管理命令(需在设置页「管理员 openid 列表」里填自己的 openid)

• 权限检查 / welcome-check [群openid...]:只查询各群的 bot_state(不发任何消息),列出哪些群未开启主动消息或未开启群内全部消息。默认检查 groupList + 按群定制 里的群,也可在命令后跟具体 openid。
• 权限提醒 / welcome-push-permission:对上面判定的"未就绪"群,尝试推一次机器人入群提醒(全局 robotJoinTemplate),并报告每个群推送成功/失败。

⚠️ 三个已知限制(来自官方文档):

1. 没有"获取机器人所在群列表"的接口,所以只能检查到配置里(「生效群列表」「按群定制」)出现的群,或你在命令里手动填的群。
2. 获取机器人群内状态(/v2/groups/{openid}/bot_state)仅白名单机器人可用,若提示 查询失败,需向平台申请权限或改用其它方式。
3. 给"主动消息已关闭"的群推不进去(机器人发不了主动消息),权限提醒 会把这类群标成"发送失败",只能靠群主手动开。

预览命令

• welcome-preview welcome [userId] — 预览欢迎模板(在 QQ 群中执行会真实发送)
• welcome-preview join [userId] — 预览机器人入群模板
• welcome-preview welcome -t — 仅返回渲染字符串,不发送
• welcome-preview welcome -g <群openid> -t — 按指定群的定制设置预览