feat(onebot): report forced offline as notice/bot_offline

Register a handler for the StatusService.KickNT push (QQ NT's unified
forced-offline notification — kick / login-elsewhere / risk-control),
decode KickNTResponse and emit bot_offline {user_id, tag, message},
matching NapCat. Command + field layout (f4=tips_title, f3=tips_content)
RE-confirmed against wrapper.linux.node + Lagrange; not yet live-captured.
This commit is contained in:
DrSmoothl
2026-07-07 15:25:35 +08:00
parent eda1c32994
commit d9dfe513ee
9 changed files with 120 additions and 1 deletions
+2
View File
@@ -4,6 +4,7 @@ import type { PacketInfo } from '@snowluma/common/protocol-types';
import { BridgeEventBus } from '@snowluma/protocol/event-bus';
import { IdentityService } from '@snowluma/protocol/identity-service';
import { MSG_PUSH_CMD, parseMsgPush, SysMsgDedup } from '@snowluma/protocol/msg-push';
import { KICK_NT_CMD, parseKickNT } from '@snowluma/protocol/kick-nt';
import { IncomingPacketPipeline, type CmdParser } from '@snowluma/protocol/packet-pipeline';
import { buildApiHub, type ApiHub } from './apis';
import {
@@ -65,6 +66,7 @@ export class Bridge implements BridgeInterface {
},
});
this.pipeline.registerCmd(MSG_PUSH_CMD, (pkt, identity) => parseMsgPush(pkt, identity, this.sysMsgDedup_));
this.pipeline.registerCmd(KICK_NT_CMD, parseKickNT);
}
dispose(): void {
@@ -6,6 +6,7 @@ import {
convertTempMessage,
} from './to-message';
import {
convertBotOffline,
convertFriendAdd,
convertFriendInputStatus,
convertFriendProfileLike,
@@ -85,6 +86,7 @@ const CONVERTERS: ConverterRegistry = {
friend_add: convertFriendAdd,
friend_input_status: convertFriendInputStatus,
friend_profile_like: convertFriendProfileLike,
bot_offline: convertBotOffline,
group_name_change: convertGroupNameChange,
group_title_change: convertGroupTitleChange,
group_card_change: convertGroupCardChange,
@@ -22,6 +22,7 @@ type GroupNameChange = Extract<QQEventVariant, { kind: 'group_name_change' }>;
type GroupCardChange = Extract<QQEventVariant, { kind: 'group_card_change' }>;
type GroupTitleChange = Extract<QQEventVariant, { kind: 'group_title_change' }>;
type FriendProfileLike = Extract<QQEventVariant, { kind: 'friend_profile_like' }>;
type BotOffline = Extract<QQEventVariant, { kind: 'bot_offline' }>;
export function convertGroupMemberJoin(ctx: ConverterContext, event: GroupMemberJoin): JsonObject {
return notice(ctx, event, {
@@ -173,6 +174,17 @@ export function convertGroupCardChange(ctx: ConverterContext, event: GroupCardCh
});
}
export function convertBotOffline(ctx: ConverterContext, event: BotOffline): JsonObject {
// Mirrors NapCat's OB11BotOfflineEvent: notice_type bot_offline with the bot's
// own uin plus the tag/message describing why it went offline.
return notice(ctx, event, {
notice_type: 'bot_offline',
user_id: event.selfUin,
tag: event.tag,
message: event.message,
});
}
export function convertFriendProfileLike(ctx: ConverterContext, event: FriendProfileLike): JsonObject {
// Mirrors NapCat's OB11ProfileLikeEvent: notify/profile_like with the liker's
// uin, nickname and like count.
+1
View File
@@ -72,6 +72,7 @@ const NOTICE_KINDS = [
'friend_add',
'friend_input_status',
'friend_profile_like',
'bot_offline',
'group_name_change',
'group_title_change',
'group_card_change',
+12
View File
@@ -263,6 +263,18 @@ export interface GroupReactNotify {
groupReactionData?: pb<44, GroupReactionData>;
}
// Forced-offline ("被迫下线") push — SSO cmd
// `trpc.qq_new_tech.status_svc.StatusService.KickNT`. QQ NT's unified offline
// notification (kick / login-elsewhere / risk-control-triggered offline all
// arrive here; the reason is in the strings). Field layout RE'd from
// wrapper.linux.node (log fmt "tips_title:{} tips_content:{}") + Lagrange's
// ServiceKickNTResponse: f4 = tips_title (short title), f3 = tips_content (desc).
export interface KickNTResponse {
uin?: pb<1, uint_32>;
tips?: pb<3, string>; // tips_content — the longer description
title?: pb<4, string>; // tips_title — the short title
}
// Group-name change (Event 0x2DC subType 16, NotifyMessageBody.field13 == 12).
// Rides in `NotifyMessageBody.eventParam` (field 5). Field layout matches
// Lagrange's `GroupNameChange` (RE'd from wrapper.linux.node): only the new
+4
View File
@@ -28,6 +28,10 @@
"types": "./src/packet-pipeline.ts",
"default": "./src/packet-pipeline.ts"
},
"./kick-nt": {
"types": "./src/kick-nt.ts",
"default": "./src/kick-nt.ts"
},
"./element-builder": {
"types": "./src/element-builder.ts",
"default": "./src/element-builder.ts"
+13 -1
View File
@@ -294,6 +294,17 @@ export interface PttTransResultEvent extends QQEvent {
text: string;
}
/**
* The bot account was forced offline (kicked / logged in elsewhere / risk-control)
* — SSO push `StatusService.KickNT`. Mirrors NapCat's OB11BotOfflineEvent →
* `notice_type:'bot_offline'`. `tag` = short title, `message` = description.
*/
export interface BotOfflineEvent extends QQEvent {
kind: 'bot_offline';
tag: string;
message: string;
}
/**
* A group member's card (群名片) changed — detected from message traffic when
* the sender's live card differs from the cached one (same mechanism as NapCat's
@@ -377,4 +388,5 @@ export type QQEventVariant =
| GroupNameChangeEvent
| GroupCardChangeEvent
| GroupTitleChangeEvent
| FriendProfileLikeEvent;
| FriendProfileLikeEvent
| BotOfflineEvent;
+33
View File
@@ -0,0 +1,33 @@
// Forced-offline push. QQ NT tells a client it was kicked / logged in elsewhere /
// dropped for risk-control via the SSO command
// `trpc.qq_new_tech.status_svc.StatusService.KickNT`, whose body is a
// `KickNTResponse`. We surface it as a `bot_offline` event (NapCat parity).
//
// The push arrives on the same StatusService channel SnowLuma already receives
// (e.g. StatusService.SsoHeartBeat), so it just needs its own cmd handler.
// Command + field layout RE-confirmed against wrapper.linux.node + Lagrange's
// KickNTService/ServiceKickNTResponse.
import { protobuf_decode } from '@snowluma/proton';
import type { KickNTResponse } from '@snowluma/proto-defs/notify';
import type { PacketInfo } from '@snowluma/common/protocol-types';
import type { IdentityService } from './identity-service';
import type { QQEventVariant } from './events';
export const KICK_NT_CMD = 'trpc.qq_new_tech.status_svc.StatusService.KickNT';
type BotOfflineEvent = Extract<QQEventVariant, { kind: 'bot_offline' }>;
export function parseKickNT(pkt: PacketInfo, identity: IdentityService): QQEventVariant[] {
const resp = protobuf_decode<KickNTResponse>(pkt.body);
if (!resp) return [];
const ev: BotOfflineEvent = {
kind: 'bot_offline',
// KickNT carries no timestamp — stamp with receive time.
time: Math.floor(Date.now() / 1000),
selfUin: Number(pkt.uin) || Number(identity.uin) || 0,
tag: resp.title ?? '', // tips_title — the short title
message: resp.tips ?? '', // tips_content — the description / reason
};
return [ev];
}
+41
View File
@@ -0,0 +1,41 @@
// StatusService.KickNT (forced-offline push) → bot_offline event.
// Command + field layout RE-confirmed against wrapper.linux.node + Lagrange's
// KickNTService/ServiceKickNTResponse (f4 = tips_title, f3 = tips_content).
import { describe, expect, it } from 'vitest';
import { protobuf_encode } from '@snowluma/proton';
import { parseKickNT, KICK_NT_CMD } from '@snowluma/protocol/kick-nt';
import { IdentityService } from '@snowluma/protocol/identity-service';
import type { KickNTResponse } from '@snowluma/proto-defs/notify';
import type { PacketInfo } from '@snowluma/common/protocol-types';
import type { QQEventVariant } from '@snowluma/protocol/events';
type BotOfflineEvent = Extract<QQEventVariant, { kind: 'bot_offline' }>;
describe('parseKickNT (StatusService.KickNT → bot_offline)', () => {
const identity = IdentityService.memory('3433035623');
function pkt(resp: KickNTResponse, uin = '3433035623'): PacketInfo {
return {
pid: 1, uin, serviceCmd: KICK_NT_CMD, seqId: 1, retCode: 0,
fromClient: false, body: protobuf_encode<KickNTResponse>(resp),
};
}
it('emits bot_offline with tag=title (f4) and message=tips (f3)', () => {
const [ev] = parseKickNT(
pkt({ uin: 3433035623, title: '你已离线', tips: '你的账号在其他设备登录' }),
identity,
) as BotOfflineEvent[];
expect(ev.kind).toBe('bot_offline');
expect(ev.selfUin).toBe(3433035623);
expect(ev.tag).toBe('你已离线');
expect(ev.message).toBe('你的账号在其他设备登录');
});
it('falls back to the identity uin when the packet uin is missing', () => {
const [ev] = parseKickNT(pkt({ title: 't', tips: 'm' }, ''), identity) as BotOfflineEvent[];
expect(ev.selfUin).toBe(3433035623);
});
});