UniQQ 真实号协作
机器人主人在「UniQQ 生态」里接入真实号执行端(QQBotRelay + UniQQ SDK)后,插件可以:
- 派动作:把官机做不到的动作(真实号发言、踢人、全员禁言、发公告、名片赞、戳一戳)交给真实号执行;
- 用数据:真实号的群消息已经自动入库平台,可直接支撑发言排行、活跃统计类功能;
- 发主题:通过协作主题让多个插件互通事件。
能力边界一句话:自动行为(群管自动处置、消息统计回复等)由统一路由决定官机还是真实号执行,避免两边重复动手;开发者显式调用(requestUniqqAction 点名的 UniQQ 能力)直达真实号执行端,想用哪个能力就用哪个,平台全量收录 UniQQ 能力目录,全程命令审计。
API
ctx.requestUniqqAction(capabilityKey: string, args?: object, correlationKey?: string): Promise<ActionIntent>
ctx.publishUniqqTopic(topic: string, payload?: unknown, correlationKey?: string): Promise<TopicRecord>requestUniqqAction 返回的意图记录:
| 字段 | 说明 |
|---|---|
id | 意图 ID |
status | dispatched(已下发)或 succeeded / failed(查询类能力,已带回执行结果) |
executor | uniqq(显式调用直达真实号执行端) |
capability_key | 请求的能力 |
command_id | 下发给执行端的命令 ID |
result | 仅查询类能力:命令执行成功后的返回数据(等待最多 10 秒) |
error_code / error_message | 执行失败时说明原因 |
显式调用直达真实号。
requestUniqqAction是开发者点名的 UniQQ 能力调用,直接派给真实号执行端,不受「统一路由策略」拦截(路由策略只约束自动回复类行为,如群管自动处置走哪一侧)。没有可用执行端时抛错AGENT_NOT_FOUND。
示例
module.exports = {
async onMessage(ctx) {
if (ctx.content !== '真实号报到') return false;
if (!ctx.isAdmin) {
await ctx.reply('只有机器人主人或管理员可以使用');
return true;
}
try {
const intent = await ctx.requestUniqqAction(
'message.group.send',
{ content: '真实号执行端已收到任务' },
`report:${ctx.msgId}`,
);
if (intent.status === 'dispatched') {
await ctx.reply('已派发给真实号执行');
} else {
await ctx.reply('派发未完成:' + (intent.error_message ?? intent.status));
}
} catch (e) {
await ctx.reply('派发失败:' + e.message);
}
return true;
},
};必须知道的规则
- 显式调用直达真实号。 调用即派发,不受路由策略拦截。没有可用执行端时抛错
AGENT_NOT_FOUND,请做降级。 - 查询类能力能取回数据了。
group.member.list、group.info.read这类查询(capabilityKey 以.read/.list/.url结尾、kind=query)会等待命令执行结果再返回,结果在intent.result字段里(最多等 10 秒,超时返回status: 'dispatched'且无result)。动作类能力(发消息、踢人等)仍是异步派发,dispatched只代表命令已发给执行端。 - 自动换算真实群号与 QQ 号。 在群聊里调用时,平台会把当前群映射为已绑定的真实群号(
realGroupId);传memberOpenid时,只有已确认(verified / manual)的成员映射才会换成真实 QQ 号(realUserId)。 - 危险能力需要权限。 风险等级为「危险」的能力(撤回、成员禁言、全员禁言、踢人、设管理员、改群名、处理入群申请)要求发送者是机器人主人、管理员或本群管理员,否则抛错。
- 幂等。
correlationKey不传时默认使用当前消息 ID。同一关联键 + 同一动作只会执行一次,网络重试或 QQ 重推不会导致重复禁言。需要重复执行同一动作时,请换一个关联键。 - 必须做降级。 不是所有用户都接入了真实号,执行端版本过低时部分能力也不可用。调用失败时请回退到官方 API,或给出明确提示。
能力目录
按 capabilityKey 调用,完整可用性以「UniQQ 生态 → 能力矩阵」为准(执行端会上报自身支持的能力清单)。
消息类
| capabilityKey | 说明 | 风险 |
|---|---|---|
message.group.send | 真实号发送群消息 | 写入 |
message.private.send | 发送私聊消息 | 写入 |
message.temp.send | 发送群临时会话消息 | 写入 |
message.recall | 撤回消息(真实号消息 ID) | 危险 |
message.reaction.write | 消息表情回应 | 写入 |
message.music.send | 发送音乐卡片 | 写入 |
message.history.read | 读取群聊历史消息(结果不回传插件) | 读取 |
群资料类
| capabilityKey | 说明 | 风险 |
|---|---|---|
group.info.read | 读取群资料(结果不回传插件) | 读取 |
group.member.list | 读取群成员列表(结果不回传插件) | 读取 |
group.member.read | 读取单个成员资料(结果不回传插件) | 读取 |
group.member.card.write | 修改成员群名片 | 写入 |
group.member.title.write | 设置专属头衔 | 写入 |
group.name.write | 修改群名称 | 危险 |
group.notice.send | 发布群公告 | 写入 |
group.notice.list | 读取群公告列表(结果不回传插件) | 读取 |
group.essence.list | 读取精华消息(结果不回传插件) | 读取 |
group.file.list | 读取群文件列表(结果不回传插件) | 读取 |
group.file.url | 获取群文件下载地址(结果不回传插件) | 读取 |
group.file.upload | 上传群文件(需执行端支持,默认关闭) | 写入 |
群管类
| capabilityKey | 说明 | 风险 |
|---|---|---|
group.member.mute | 成员禁言(秒,0 解禁) | 危险 |
group.mute.all | 开关全员禁言 | 危险 |
group.member.kick | 移出群成员(可选拉黑) | 危险 |
group.admin.write | 设置 / 取消管理员 | 危险 |
group.mute.list | 读取禁言成员(结果不回传插件) | 读取 |
group.request.handle | 同意 / 拒绝入群申请 | 危险 |
社交类
| capabilityKey | 说明 | 风险 |
|---|---|---|
social.like.send | 发送名片赞 | 写入 |
social.poke.send | 发送戳一戳 | 写入 |
social.friend.list | 读取好友列表(结果不回传插件) | 读取 |
social.friend.read | 读取好友资料(结果不回传插件) | 读取 |
事件类(执行端上报方向)
执行端会按能力矩阵把真实号事件持续上报平台:群消息、私聊消息、入群退群、撤回、入群申请、表情回应、机器人状态、戳一戳等(event.* 系列能力键),以及 UniQQ 插件自行上报的自定义事件(real.custom.* → 平台按 custom.* 归一化)。
官机内置插件可以订阅全部 relay 事件:在 register(ctx) 里 ctx.on('RelayEvent', handler),通过 ev.getType()(如 real.group.message / real.custom.checkin)区分事件,ev.getContent() / ev.getRealGroupId() / ev.get(key) 取数据,ev.replyText('...') 直接让真实号回群(走命令审计链)。UniQQ 侧新增事件类型时平台无需改动,开发者直接按类型消费即可。
用户插件(沙箱 JS)暂不能直接订阅 relay 事件,见「数据协作的三条通路」。
错误处理
| 情况 | 插件看到的结果 | 处理 |
|---|---|---|
| 没有可用执行端 | 抛错:没有可执行该意图的 UniQQ 代理 | 提示主人在「UniQQ 生态」创建代理并启动 Relay |
| 能力不存在 / 不可派发 | 抛错:该能力不能创建远程动作意图 | 检查 capabilityKey 拼写,或改用官方 API |
| 危险动作权限不足 | 抛错:只有机器人主人或管理员(本群管理员也可)可以执行该操作 | 先判断 ctx.isAdmin,给用户友好提示 |
| 查询超时 | 返回 status: 'dispatched' 且无 result | 稍后在「UniQQ 生态 → 动作意图」查看,或引导用户重试 |
插件协作主题
publishUniqqTopic 发布一条主题消息,在「UniQQ 生态 → 插件协作」里订阅了该主题的其它插件可以消费。主题名建议使用 插件slug.事件 的点分格式,例如 group-guard.spam.detected;订阅端支持精确值或 xxx.* 通配。
数据协作的通路
官机插件与真实号之间除了「派动作」,还经常需要「拿数据」。通路有四条,边界必须清楚:
通路一:真实号群消息已自动入库(零开发,直接用)
执行端上报的每一条真实号群消息(real.group.message)都会进入平台的消息统计库。因此发言排行、活跃统计类需求不需要任何自定义上报:
- 内置「消息统计」插件已支持发言榜、活跃人数、时段分布,真实号消息一并计入;回复模板支持
{top_last_at}占位符(发言最多者的最近发言时间); - 群里发「消息统计」即可由官机回复统计结果;
- 工作流也能基于这些消息记录做定时汇总。
适合:发言排行、今日发言次数、水王榜、周报月报。
通路二:动作派发(requestUniqqAction)
插件把动作交给真实号执行,见上文 API。查询类能力能拿回数据(intent.result,最多等 10 秒);动作类(发消息、踢人等)是异步派发,结果在「UniQQ 生态 → 动作意图」里查看。
适合:踢人、禁言、改名片、发公告等"让真实号干活"的场景,以及用查询类能力取群成员列表、群资料。
通路四:自定义事件上报(real.custom.*,小号采数据、平台插件消费)
UniQQ 侧的 .NET 插件可以通过事件上报接口把自己的事件发给平台,类型用 real.custom.<名称>(名称为字母/数字开头的 1~64 位字母数字点横线下划线):
UniQQ 插件(.NET)─ 上报 real.custom.redpacket.grabbed ─→ 平台 relay_events(normalized: custom.redpacket.grabbed)
├─ 官机内置插件:ctx.on('RelayEvent') 消费
├─ 主题流:custom.* 供外部消费者订阅
└─ relay_event_deliveries 投递记录规则:
- 自定义事件必须携带
realGroupId,且该群已绑定、群权限正常,否则拒收(GROUP_NOT_ALLOWED); - 事件 payload 是任意 JSON,平台透传存储,插件用
ev.get('字段名')读取; - 平台按
custom.<名称小写>归一化,主题流订阅用custom.*通配。
适合:红包战报、签到数据、UniQQ 插件自有业务事件 → 平台插件消费 → 官机回复。
通路五:用户插件订阅 relay 事件(onRelayEvent)
用户插件(插件市场的沙箱 JS 插件)也可以直接订阅真实号上报的全部事件。两步接入:
第一步:plugin.json 的 permissions 里声明 relay(安装时用户会看到「订阅 UniQQ 真实号事件」权限确认):
{ "permissions": ["relay"] }第二步:插件代码里导出 onRelayEvent:
module.exports = {
name: '签到播报',
async onRelayEvent(ctx) {
// 只处理自定义签到事件
if (ctx.normalizedType !== 'custom.checkin') return false;
await ctx.replyText(`${ctx.senderName} 签到成功,连签 ${ctx.payload.streak} 天`);
return true;
},
};onRelayEvent 的 ctx 字段:
| 字段 | 说明 |
|---|---|
type / relayType | 原始事件类型(real.group.message、real.custom.<名称> 等) |
normalizedType / eventType | 归一化类型(message.group.created、custom.checkin 等) |
content | 消息内容(消息类事件) |
realGroupId / groupId | 真实群号 |
realUserId / userId | 发送者真实 QQ 号 |
senderName / userName | 发送者昵称(消息类事件) |
payload | 完整事件数据(自定义事件的字段从这里取) |
eventId / messageId / occurredAt | 事件标识与时间 |
settings / kv / log | 与 onMessage 相同的配置与存储 |
可用的动作 API:ctx.replyText(content) 让真实号回群;ctx.requestUniqqAction 派发能力(危险能力在事件场景一律拒绝——事件没有发送者身份,防止插件被恶意事件注入后自动踢人/禁言);ctx.http、ctx.kv 照常可用。
注意:relay 事件不经过触发词路由,插件自己按 type / content 判断要不要处理;机器人自己的消息不会进 onRelayEvent(回环防护)。
UniQQ 侧自治采集(NapCat 补丁类需求)
有些数据只有真实号能看到、QQ 官方接口又不提供——典型就是抢红包。QQ 不向官方机器人推送任何红包事件,所以官机侧无论怎么开发都拿不到"谁抢了红包"。这类需求只能由 UniQQ 侧的 .NET 插件完成:
QQ 群 → NapCat(灰条解析)→ UniQQ 插件(.NET,本地 SQLite 统计)
→ 自己用真实号发送统计结果
或 → 通过 FrameworkOfficialBotService 让官机 Markdown 直发关键限制(写代码前必须知道):
- UniQQ 框架不推送红包领取灰条,必须给 NapCat 打补丁解析
busiId=19357/19360的灰条消息; - 红包金额 QQ 不下发,无解,统计只能到"谁抢了、几点抢的";
- UniQQ 侧插件现在可以上报自定义事件(
real.custom.<名称>,见通路四),平台插件已能消费——「小号采数据、平台插件消费」这条链路已打通。
完整案例:发言排行 + 抢红包统计
需求:官机负责回复,统计抢包人最近发言时间和当天发言次数,并做出报表。
拆解与结论
| 子需求 | 结论 | 实现路径 |
|---|---|---|
| 发言排行 / 今日发言次数 | ✅ 现在就能做 | 真实号消息已入库 → 内置「消息统计」直接支持,零开发 |
| 最近发言时间 | ✅ 已支持 | 消息统计已记录 last_at;模板用 {top_last_at} 占位符展示发言最多者的最近发言时间 |
| 抢红包名单 | ⚠️ 有条件可行 | 必须 NapCat 补丁 + UniQQ .NET 插件采集;红包金额拿不到 |
| 抢红包数据上报平台 | ✅ 已支持 | UniQQ 插件上报 real.custom.redpacket.* 事件 → 内置插件 RelayEvent 或用户插件 onRelayEvent 消费 → 官机/真实号回复 |
推荐架构(方案 B:UniQQ 侧自治采集)
┌─ 本机 Windows ─────────────────────────────┐ ┌─ 云端平台 ──────────┐
│ │ │ │
│ QQ群 ─ NapCat(补丁抓红包灰条) │ │ 内置「消息统计」 │
│ │ │ │ 群消息自动入库 │
│ ▼ │ │ 官机回复发言榜 │
│ UniQQ 插件(.NET) │ │ │
│ ├─ 群消息事件 → 本地 SQLite(今日次数/最后)│ │ 「红包战报」指令 │
│ ├─ 红包灰条 → 抢包名单/时间 │ │ ← UniQQ 插件本地 │
│ └─ 指令触发 → 查库拼报表 │ │ 匹配并直发 │
│ │ │ │ │
│ ├─ 真实号发送 → QQ群 │ │ │
│ └─ FrameworkOfficialBotService │ │ │
│ → 官机 Markdown 直发 → QQ群 │ │ │
└─────────────────────────────────────────────┘ └─────────────────────┘要点:
- 发言数据不用采集——平台已入库,官机的「消息统计」回复里就有发言榜;UniQQ 插件只需在自己库里补一个
last_at(最近发言时间)字段,供红包报表引用; - 抢红包:NapCat 补丁把灰条 POST 到插件本地 HTTP(
http://127.0.0.1:19877/ingest),插件解析出"谁在几点抢了红包"写入 SQLite; - 报表输出:群里有人发「红包战报」→ UniQQ 插件本地匹配指令 → 查库拼 Markdown →
FrameworkOfficialBotService.TrySendGroupMarkdownAsync让官机发(被动回复 5 分钟内不占官机配额); - 发言次数交叉统计:红包报表需要"抢包人今日发言次数"时,插件本地也维护一份每日发言计数(监听
GroupMessageEvent即可),不要依赖平台数据——本地查询零网络延迟; - 去重与容错:灰条消息用
MessageId去重;NapCat 补丁输出先落原始 JSON 再解析字段,QQ 版本升级可能改变字段路径;所有 API 调用包 try-catch。
方案 C:平台侧扩展(✅ 已全部落地)
「小号采数据、官机插件消费」平台化的四个能力,全部完成:
- ✅ relay 事件白名单放行
real.custom.*自定义事件类型并落库(custom.*归一化 + 主题流); - ✅ 内置插件事件系统新增
RelayEvent事件类型,官机插件可订阅真实号上报的全部事件(含自定义事件); - ✅ 查询类动作意图异步回传(
awaitResult,最多等 10 秒,结果在intent.result); - ✅ 用户插件订阅 relay 事件(
permissions声明relay+ 导出onRelayEvent,见通路五)。
抢红包数据现在可以走「UniQQ 插件上报 → 平台插件/用户插件消费 → 官机/真实号回复」的标准链路,报表格式也能在平台侧用工作流模板自定义。
