权限、群管与入群审批
平台角色:主人 / 管理员 / 成员
平台为每台机器人维护一份权限名单,在后台「插件生态 → 我的插件 → 主人 / 管理员」里配置。名单属于整台机器人,所有插件共用同一套角色,插件不需要自己维护名单。
| 角色 | ctx.role | 判断字段 | 典型用途 |
|---|---|---|---|
| 主人 | 'owner' | ctx.isOwner | 最高权限:重置数据、调用底层 API |
| 管理员 | 'admin' | ctx.isAdmin(主人也为 true) | 日常管理:开关功能、清空统计、管理黑名单 |
| 普通成员 | 'member' | ctx.isMember | 查询、娱乐类指令 |
js
// 不满足直接抛错(同步调用,无需 await)
ctx.requireOwner(); // 非主人:只有机器人主人可以执行该操作
ctx.requireAdmin(); // 非主人/管理员:只有机器人主人或管理员可以执行该操作
// 想给更友好的提示,就自己判断
if (!ctx.isAdmin) {
await ctx.reply('只有机器人主人或管理员可以使用该指令');
return true;
}requireOwner() / requireAdmin() 抛出的错误如果不捕获,会记为一次运行失败(计入连续失败熔断),用户也收不到提示,建议包在 try/catch 里或改用上面的显式判断。
角色按机器人隔离:同一个人在不同机器人上可以是不同角色。
判断群管理员
ctx.isGroupAdmin() 查的是当前 QQ 群的群主/管理员身份,和平台角色是两套东西;它已经包含平台角色(主人/管理员直接返回 true):
js
if (!(await ctx.isGroupAdmin())) {
await ctx.reply('只有机器人主人、管理员或本群管理员可以使用');
return true;
}WARNING
群身份依赖 QQ 官方「群成员列表」白名单接口(未开通时错误码 11253)。没有开通的机器人上 isGroupAdmin() 对普通群管一直返回 false,即使对方是群主。权限判断请以平台角色为主,isGroupAdmin() 只作补充。
群管
js
await ctx.recallMessage(); // 撤回当前消息
await ctx.muteMember(openid, 10); // 10 分钟,0 = 解禁
await ctx.kickMember(openid, false); // 第二参数是否拉黑
await ctx.setMemberBlacklist(openid, true);限制:
- 只能在群聊使用
- 调用者必须是机器人主人、管理员或本群管理员,否则抛错
- 机器人自身必须有对应权限
- 官机能力受 QQ 开放平台限制;普通机器人依赖 Relay 在线
群信息
js
const info = await ctx.getGroupInfo();
const members = await ctx.getGroupMembers();
const state = await ctx.getGroupBotState();
const mute = await ctx.getGroupMuteState();群成员接口可能需要官方白名单,未开通会返回 QQ 原始错误。
入群申请
js
const list = await ctx.getJoinRequests();
const req = list.list?.[0];
if (req) {
await ctx.auditJoinRequest(req.member_openid, true, req.join_request_id);
}拒绝:
js
await ctx.auditJoinRequest(req.member_openid, false, req.join_request_id, '资料不完整');主动消息
js
await ctx.sendGroup(groupId, '主动群消息');
await ctx.sendPrivate(userId, '主动私聊');主动消息受 QQ 每日额度限制。
底层 API
js
if (ctx.isOwner) {
const me = await ctx.callApi('GET', '/users/@me');
}底层 API 不做业务封装,权限和参数由 QQ 官方决定。
