ctx API 总览
ctx是插件唯一入口对象。下面是完整字段和方法。
消息字段
| 字段 | 类型 | 说明 |
|---|---|---|
| ctx.content | string | 消息文本,已去掉 @机器人 前缀 |
| ctx.userId | string | 发送者 openid |
| ctx.userName | string | 发送者昵称 |
| ctx.groupId | string | 群 openid;私聊为空 |
| ctx.surface | string | group / c2c / channel |
| ctx.msgId | string | 消息/交互 ID |
| ctx.isAt | boolean | 是否 @机器人 |
| ctx.role | 'owner' | 'admin' | 'member' | 发送者在本机器人上的平台角色 |
| ctx.isOwner | boolean | 是否机器人主人 |
| ctx.isAdmin | boolean | 是否主人或管理员 |
| ctx.isMember | boolean | 是否普通成员 |
| ctx.mentions | array | 被 @ 的成员 |
| ctx.attachments | array | 附件 |
| ctx.payload | object | QQ 原始事件体 |
| ctx.time | string | ISO 时间 |
| ctx.buttonData | string | 按钮回调的 button_data |
| ctx.interactionId | string | 交互 ID,仅按钮回调事件 |
| ctx.settings | object | 当前机器人下的安装配置,由 settings_schema 配置页保存 |
配置字段可以直接读取:
const endpoint = String(ctx.settings.api_url || '');
const retry = Number(ctx.settings.retry_count ?? 3);
const enabled = ctx.settings.auto_reply !== false;完整字段声明、条件显示和分组方式见自定义配置页面。
回复
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 后可以撤回自己发的消息:
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 秒调用一次,可以主动查单、补发、清理数据:
module.exports = {
async onTimer(ctx) {
if (ctx.timer !== true) return false;
// 没有 msgId,只能用主动消息接口
await ctx.sendGroupMarkdown(groupId, '这条是定时发的');
},
};定时上下文里 ctx.reply* 不可用(没有消息可回),其余约束见运行时与生命周期。
媒体
ctx.uploadImage(url)
ctx.uploadVideo(url)
ctx.uploadAudio(url)
ctx.uploadFile(url)
ctx.rehost(url)发邮件
沙箱期私聊不通、群消息又不能让卡密见光,邮件是最稳的落地通道。平台内置了发信能力,不需要额外部署中继服务:
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」指令让用户自己设置。
存储与网络
ctx.kv.get(key)
ctx.kv.set(key, value)
ctx.kv.has(key)
ctx.kv.delete(key)
ctx.kv.keys()
ctx.http(url, options)机器人 / 群
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?)主动发送
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 的开关,或让用户先给机器人发过消息 |
| 发送成功但用户没收到 | 主动私聊额度/频控 | 见下方额度说明 |
所以「私聊发货」这类关键路径一定要有兜底:私聊失败 → 群里 @用户 提示他发「补发 订单号」,那条是用户自己触发的被动回复,沙箱下也能发出去。
try {
await ctx.sendPrivateMarkdown(userId, md);
} catch (e) {
ctx.log('私聊失败:' + e.message);
// @ 必须用 QQ 的标签语法,<@openid> 只会被当成普通文字
await ctx.sendGroupMarkdown(groupId,
`⚠️ <qqbot-at-user id="${userId}" /> 私聊发不出去,请发送「补发 订单号」自取`);
}别把敏感内容发群里
私聊失败时不要把卡密、密码这类东西直接发到群里——同群所有人都看得到,等于让人白买。 正确做法:只 @ 他本人 + 告诉他怎么自取(私聊发指令 / 填邮箱走邮件)。
权限 / 群管
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?)撤回、禁言、踢人、黑名单、入群审批要求发送者是主人、管理员或本群管理员。详见权限、群管与入群审批。
底层
ctx.callApi(method, path, body?)仅机器人主人可用。
UniQQ 真实号协作
await ctx.requestUniqqAction(capabilityKey, args?, correlationKey?)
await ctx.publishUniqqTopic(topic, payload?, correlationKey?)异步派发给真实号执行端,返回意图记录而不是执行结果。详见 UniQQ 真实号协作。
命名空间别名
ctx.bot.info()
ctx.group.info()
ctx.group.members()
ctx.group.joinRequests()
ctx.private.send()日志
ctx.log(...)
ctx.info(...)
ctx.warn(...)
ctx.error(...)