Skip to content

权限、群管与入群审批 ​

平台角色:主人 / 管理员 / 成员 ​

平台为每台机器人维护一份权限名单,在后台「插件生态 → 我的插件 → 主人 / 管理员」里配置。名单属于整台机器人,所有插件共用同一套角色,插件不需要自己维护名单。

角色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 官方决定。

薇薇官机平台 · ZL 系列插件