Skip to content

UniQQ 真实号协作 ​

机器人主人在「UniQQ 生态」里接入真实号执行端(QQBotRelay + UniQQ SDK)后,插件可以:

  • 派动作:把官机做不到的动作(真实号发言、踢人、全员禁言、发公告、名片赞、戳一戳)交给真实号执行;
  • 用数据:真实号的群消息已经自动入库平台,可直接支撑发言排行、活跃统计类功能;
  • 发主题:通过协作主题让多个插件互通事件。

能力边界一句话:自动行为(群管自动处置、消息统计回复等)由统一路由决定官机还是真实号执行,避免两边重复动手;开发者显式调用(requestUniqqAction 点名的 UniQQ 能力)直达真实号执行端,想用哪个能力就用哪个,平台全量收录 UniQQ 能力目录,全程命令审计。

API ​

ts
ctx.requestUniqqAction(capabilityKey: string, args?: object, correlationKey?: string): Promise<ActionIntent>
ctx.publishUniqqTopic(topic: string, payload?: unknown, correlationKey?: string): Promise<TopicRecord>

requestUniqqAction 返回的意图记录:

字段说明
id意图 ID
statusdispatched(已下发)或 succeeded / failed(查询类能力,已带回执行结果)
executoruniqq(显式调用直达真实号执行端)
capability_key请求的能力
command_id下发给执行端的命令 ID
result仅查询类能力:命令执行成功后的返回数据(等待最多 10 秒)
error_code / error_message执行失败时说明原因

显式调用直达真实号。 requestUniqqAction 是开发者点名的 UniQQ 能力调用,直接派给真实号执行端,不受「统一路由策略」拦截(路由策略只约束自动回复类行为,如群管自动处置走哪一侧)。没有可用执行端时抛错 AGENT_NOT_FOUND。

示例 ​

js
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 真实号事件」权限确认):

json
{ "permissions": ["relay"] }

第二步:插件代码里导出 onRelayEvent:

js
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群        │      │                     │
└─────────────────────────────────────────────┘      └─────────────────────┘

要点:

  1. 发言数据不用采集——平台已入库,官机的「消息统计」回复里就有发言榜;UniQQ 插件只需在自己库里补一个 last_at(最近发言时间)字段,供红包报表引用;
  2. 抢红包:NapCat 补丁把灰条 POST 到插件本地 HTTP(http://127.0.0.1:19877/ingest),插件解析出"谁在几点抢了红包"写入 SQLite;
  3. 报表输出:群里有人发「红包战报」→ UniQQ 插件本地匹配指令 → 查库拼 Markdown → FrameworkOfficialBotService.TrySendGroupMarkdownAsync 让官机发(被动回复 5 分钟内不占官机配额);
  4. 发言次数交叉统计:红包报表需要"抢包人今日发言次数"时,插件本地也维护一份每日发言计数(监听 GroupMessageEvent 即可),不要依赖平台数据——本地查询零网络延迟;
  5. 去重与容错:灰条消息用 MessageId 去重;NapCat 补丁输出先落原始 JSON 再解析字段,QQ 版本升级可能改变字段路径;所有 API 调用包 try-catch。

方案 C:平台侧扩展(✅ 已全部落地) ​

「小号采数据、官机插件消费」平台化的四个能力,全部完成:

  1. ✅ relay 事件白名单放行 real.custom.* 自定义事件类型并落库(custom.* 归一化 + 主题流);
  2. ✅ 内置插件事件系统新增 RelayEvent 事件类型,官机插件可订阅真实号上报的全部事件(含自定义事件);
  3. ✅ 查询类动作意图异步回传(awaitResult,最多等 10 秒,结果在 intent.result);
  4. ✅ 用户插件订阅 relay 事件(permissions 声明 relay + 导出 onRelayEvent,见通路五)。

抢红包数据现在可以走「UniQQ 插件上报 → 平台插件/用户插件消费 → 官机/真实号回复」的标准链路,报表格式也能在平台侧用工作流模板自定义。

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