Skip to content

ctx API 总览 ​

ctx 是插件唯一入口对象。下面是完整字段和方法。

消息字段 ​

字段类型说明
ctx.contentstring消息文本,已去掉 @机器人 前缀
ctx.userIdstring发送者 openid
ctx.userNamestring发送者昵称
ctx.groupIdstring群 openid;私聊为空
ctx.surfacestringgroup / c2c / channel
ctx.msgIdstring消息/交互 ID
ctx.isAtboolean是否 @机器人
ctx.role'owner' | 'admin' | 'member'发送者在本机器人上的平台角色
ctx.isOwnerboolean是否机器人主人
ctx.isAdminboolean是否主人或管理员
ctx.isMemberboolean是否普通成员
ctx.mentionsarray被 @ 的成员
ctx.attachmentsarray附件
ctx.payloadobjectQQ 原始事件体
ctx.timestringISO 时间
ctx.buttonDatastring按钮回调的 button_data
ctx.interactionIdstring交互 ID,仅按钮回调事件
ctx.settingsobject当前机器人下的安装配置,由 settings_schema 配置页保存

配置字段可以直接读取:

js
const endpoint = String(ctx.settings.api_url || '');
const retry = Number(ctx.settings.retry_count ?? 3);
const enabled = ctx.settings.auto_reply !== false;

完整字段声明、条件显示和分组方式见自定义配置页面。

回复 ​

js
ctx.reply(text, quote?)
ctx.replyText(text)
ctx.replyMarkdown(md, keyboard?, quote?)
ctx.replyImage(url)
ctx.replyMedia(url, type)
ctx.replyVideo(url)
ctx.replyAudio(url)
ctx.replyFile(url)
ctx.replyArk(templateId, kv)

quote 为布尔值,控制该条回复是否以「引用触发消息」的形式发出;不传时沿用机器人全局的引用开关。详见文本、Markdown 与按钮。

reply* 系列返回平台侧的 message_id(字符串,拿不到时为空串),主动消息的 sendGroupMarkdown / sendPrivateMarkdown 等同理。拿到 id 后可以撤回自己发的消息:

js
const noticeId = await ctx.replyMarkdown('订单已创建…');
// 支付成功后撤回这条
await ctx.recallGroupMessage(ctx.groupId, noticeId);
await ctx.recallPrivateMessage(userId, privateMsgId);
接口说明
ctx.recallGroupMessage(groupId, messageId)撤回机器人自己发的群消息;QQ 只允许撤回 2 分钟内、机器人自己发送的消息,超时会抛错
ctx.recallPrivateMessage(userId, messageId)撤回机器人自己发的私聊消息,同样受 2 分钟限制
ctx.recallMessage(messageId?)撤回当前消息场景里机器人发的消息,需要管理员权限(普通插件用上面两个更合适)

定时任务 ​

导出 onTimer 后,平台约每 30 秒调用一次,可以主动查单、补发、清理数据:

js
module.exports = {
  async onTimer(ctx) {
    if (ctx.timer !== true) return false;
    // 没有 msgId,只能用主动消息接口
    await ctx.sendGroupMarkdown(groupId, '这条是定时发的');
  },
};

定时上下文里 ctx.reply* 不可用(没有消息可回),其余约束见运行时与生命周期。

媒体 ​

js
ctx.uploadImage(url)
ctx.uploadVideo(url)
ctx.uploadAudio(url)
ctx.uploadFile(url)
ctx.rehost(url)

发邮件 ​

沙箱期私聊不通、群消息又不能让卡密见光,邮件是最稳的落地通道。平台内置了发信能力,不需要额外部署中继服务:

js
await ctx.sendMail({
  to: 'buyer@example.com',
  subject: '你购买的商品已发货',
  text: '卡密:ABCD-1234',
  // html 可选
  smtp: {
    host: 'smtp.qq.com',
    port: 465,
    security: 'ssl',          // ssl | starttls | none
    username: 'you@qq.com',
    password: '授权码',        // 注意是授权码,不是登录密码
    fromAddress: 'you@qq.com',
    fromName: '卡密商店',
  },
});
规则说明
发信通道用你传进来的 SMTP 发,不写入平台配置;不传 smtp 时若平台配了邮箱则用平台的(usePlatform: false 可禁用)
限流单插件实例每分钟 20 封、每小时 200 封
失败直接抛错,err.message 就是 SMTP 的真实报错,建议 try/catch 后降级
收件人必须能解析成邮箱;纯数字会按 <digit>@qq.com 补全

QQ 官方机器人拿不到用户的 QQ 号(只有 openid),所以别指望「自动发到 QQ 邮箱」——下单时让用户填一次邮箱,或者提供「邮箱 xxx@qq.com」指令让用户自己设置。

存储与网络 ​

js
ctx.kv.get(key)
ctx.kv.set(key, value)
ctx.kv.has(key)
ctx.kv.delete(key)
ctx.kv.keys()

ctx.http(url, options)

机器人 / 群 ​

js
ctx.getBotInfo()
ctx.getBotList()
ctx.getGroupInfo(groupId?)
ctx.getGroupList()
ctx.getGroupMembers(groupId?, cursor?)
ctx.getGroupBotState(groupId?)
ctx.getGroupMuteState(groupId?)
ctx.getJoinRequests(groupId?, cursor?, limit?)
ctx.auditJoinRequest(memberOpenid, approve, requestId?, reason?)
ctx.setMemberBlacklist(memberOpenid, blacklist, groupId?)
ctx.getMessageHistory(limit?)
ctx.aiChat(prompt, system?)

主动发送 ​

js
ctx.sendGroup(groupId, text)
ctx.sendPrivate(userId, text)
ctx.sendGroupMarkdown(groupId, md, keyboard?)
ctx.sendPrivateMarkdown(userId, md, keyboard?)
ctx.sendGroupMedia(groupId, url, type)
ctx.sendPrivateMedia(userId, url, type)

这三个 sendPrivate* 走 QQ 主动私聊,和群消息不是一个口径,踩坑最多:

现象 / 报错原因处理
沙箱环境不能访问此资源机器人还在沙箱环境,QQ 不支持沙箱私信。注意:主体认证(个人/企业)通过不等于上线,还要在开放平台「发布」提审通过、机器人状态变成「在线」;沙箱期私信双向都不通机器人上线后再用;沙箱期改用群内被动回复(让用户自己发指令)或邮件
该用户未开启私聊权限平台侧未放行该用户调 botScopeAllows 的开关,或让用户先给机器人发过消息
发送成功但用户没收到主动私聊额度/频控见下方额度说明

所以「私聊发货」这类关键路径一定要有兜底:私聊失败 → 群里 @用户 提示他发「补发 订单号」,那条是用户自己触发的被动回复,沙箱下也能发出去。

js
try {
  await ctx.sendPrivateMarkdown(userId, md);
} catch (e) {
  ctx.log('私聊失败:' + e.message);
  // @ 必须用 QQ 的标签语法,<@openid> 只会被当成普通文字
  await ctx.sendGroupMarkdown(groupId,
    `⚠️ <qqbot-at-user id="${userId}" /> 私聊发不出去,请发送「补发 订单号」自取`);
}

别把敏感内容发群里

私聊失败时不要把卡密、密码这类东西直接发到群里——同群所有人都看得到,等于让人白买。 正确做法:只 @ 他本人 + 告诉他怎么自取(私聊发指令 / 填邮箱走邮件)。

权限 / 群管 ​

js
ctx.isOwner / ctx.isAdmin / ctx.isMember / ctx.role
ctx.requireOwner()        // 非主人抛错(同步)
ctx.requireAdmin()        // 非主人/管理员抛错(同步)
await ctx.isGroupAdmin()  // 本群群主/管理员,含平台角色

ctx.recallMessage(messageId?)
ctx.muteMember(memberOpenid, minutes)
ctx.kickMember(memberOpenid, blacklist?)
ctx.respond(code?)

撤回、禁言、踢人、黑名单、入群审批要求发送者是主人、管理员或本群管理员。详见权限、群管与入群审批。

底层 ​

js
ctx.callApi(method, path, body?)

仅机器人主人可用。

UniQQ 真实号协作 ​

js
await ctx.requestUniqqAction(capabilityKey, args?, correlationKey?)
await ctx.publishUniqqTopic(topic, payload?, correlationKey?)

异步派发给真实号执行端,返回意图记录而不是执行结果。详见 UniQQ 真实号协作。

命名空间别名 ​

js
ctx.bot.info()
ctx.group.info()
ctx.group.members()
ctx.group.joinRequests()
ctx.private.send()

日志 ​

js
ctx.log(...)
ctx.info(...)
ctx.warn(...)
ctx.error(...)

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