feat(onebot): expose extended account profile information

Add account identifiers, compatible level names, available registration and membership details, and documented account age for group members. Keep unavailable values absent and refresh the action documentation.

Fixes #496
This commit is contained in:
DrSmoothl
2026-10-04 13:04:42 +08:00
parent b69108e1cc
commit 3068d3ef60
11 changed files with 243 additions and 8 deletions
+45 -1
View File
@@ -5342,6 +5342,14 @@
"type": "string",
"description": "群等级"
},
"qq_level": {
"type": "integer",
"description": "QQ 等级,仅在账号资料可用时返回"
},
"qage": {
"type": "integer",
"description": "按注册时间计算的完整周年数(UTC),注册时间不可用时省略"
},
"role": {
"type": "string",
"enum": [
@@ -5513,6 +5521,14 @@
"type": "string",
"description": "群等级"
},
"qq_level": {
"type": "integer",
"description": "QQ 等级,仅在账号资料可用时返回"
},
"qage": {
"type": "integer",
"description": "按注册时间计算的完整周年数(UTC),注册时间不可用时省略"
},
"role": {
"type": "string",
"enum": [
@@ -7585,7 +7601,7 @@
"name": "get_stranger_info",
"aliases": [],
"summary": "获取陌生人信息",
"returns": "用户资料:QQ 号、昵称、好友备注、性别、年龄与个性签名,命中资料时另含等级、企点标志与企业名称。",
"returns": "用户资料,含账号标识、等级别名和可用的注册时间、会员信息。注册时间或会员信息未返回时省略对应字段;登录天数暂无可靠来源,不返回占位值。",
"returnsSchema": {
"type": "object",
"properties": {
@@ -7593,6 +7609,14 @@
"type": "integer",
"description": "QQ 号"
},
"uid": {
"type": "string",
"description": "账号唯一标识(仅查到资料时返回)"
},
"qid": {
"type": "string",
"description": "自定义账号标识(仅查到资料时返回)"
},
"nickname": {
"type": "string",
"description": "昵称"
@@ -7617,6 +7641,26 @@
"type": "integer",
"description": "QQ 等级(仅查到资料时返回)"
},
"qqLevel": {
"type": "integer",
"description": "QQ 等级,同 qq_level"
},
"reg_time": {
"type": "integer",
"description": "注册时间戳(秒),不可用时省略"
},
"is_vip": {
"type": "boolean",
"description": "超级会员状态,兼容 NapCat;不可用时省略"
},
"is_years_vip": {
"type": "boolean",
"description": "年费会员状态,不可用时省略"
},
"vip_level": {
"type": "integer",
"description": "会员等级,不可用时省略"
},
"level": {
"type": "integer",
"description": "QQ 等级,同 qq_level(仅查到资料时返回)"
+45 -1
View File
@@ -5345,6 +5345,14 @@ export const ACTIONS: CatalogAction[] = [
"type": "string",
"description": "群等级"
},
"qq_level": {
"type": "integer",
"description": "QQ 等级,仅在账号资料可用时返回"
},
"qage": {
"type": "integer",
"description": "按注册时间计算的完整周年数(UTC),注册时间不可用时省略"
},
"role": {
"type": "string",
"enum": [
@@ -5516,6 +5524,14 @@ export const ACTIONS: CatalogAction[] = [
"type": "string",
"description": "群等级"
},
"qq_level": {
"type": "integer",
"description": "QQ 等级,仅在账号资料可用时返回"
},
"qage": {
"type": "integer",
"description": "按注册时间计算的完整周年数(UTC),注册时间不可用时省略"
},
"role": {
"type": "string",
"enum": [
@@ -7588,7 +7604,7 @@ export const ACTIONS: CatalogAction[] = [
"name": "get_stranger_info",
"aliases": [],
"summary": "获取陌生人信息",
"returns": "用户资料:QQ 号、昵称、好友备注、性别、年龄与个性签名,命中资料时另含等级、企点标志与企业名称。",
"returns": "用户资料,含账号标识、等级别名和可用的注册时间、会员信息。注册时间或会员信息未返回时省略对应字段;登录天数暂无可靠来源,不返回占位值。",
"returnsSchema": {
"type": "object",
"properties": {
@@ -7596,6 +7612,14 @@ export const ACTIONS: CatalogAction[] = [
"type": "integer",
"description": "QQ 号"
},
"uid": {
"type": "string",
"description": "账号唯一标识(仅查到资料时返回)"
},
"qid": {
"type": "string",
"description": "自定义账号标识(仅查到资料时返回)"
},
"nickname": {
"type": "string",
"description": "昵称"
@@ -7620,6 +7644,26 @@ export const ACTIONS: CatalogAction[] = [
"type": "integer",
"description": "QQ 等级(仅查到资料时返回)"
},
"qqLevel": {
"type": "integer",
"description": "QQ 等级,同 qq_level"
},
"reg_time": {
"type": "integer",
"description": "注册时间戳(秒),不可用时省略"
},
"is_vip": {
"type": "boolean",
"description": "超级会员状态,兼容 NapCat;不可用时省略"
},
"is_years_vip": {
"type": "boolean",
"description": "年费会员状态,不可用时省略"
},
"vip_level": {
"type": "integer",
"description": "会员等级,不可用时省略"
},
"level": {
"type": "integer",
"description": "QQ 等级,同 qq_level(仅查到资料时返回)"
+8 -1
View File
@@ -32,17 +32,24 @@ export const actions = [
name: 'get_stranger_info',
summary: '获取陌生人信息',
readOnly: true,
returns: '用户资料:QQ 号、昵称、好友备注、性别、年龄与个性签名,命中资料时另含等级、企点标志与企业名称。',
returns: '用户资料,含账号标识、等级别名和可用的注册时间、会员信息。注册时间或会员信息未返回时省略对应字段;登录天数暂无可靠来源,不返回占位值。',
returnsSchema: {
type: 'object',
properties: {
user_id: { type: 'integer', description: 'QQ 号' },
uid: { type: 'string', description: '账号唯一标识(仅查到资料时返回)' },
qid: { type: 'string', description: '自定义账号标识(仅查到资料时返回)' },
nickname: { type: 'string', description: '昵称' },
remark: { type: 'string', description: '好友备注;非好友或未设置时为空字符串' },
sex: { type: 'string', description: '性别(male/female/unknown)' },
age: { type: 'integer', description: '年龄' },
long_nick: { type: 'string', description: '个性签名' },
qq_level: { type: 'integer', description: 'QQ 等级(仅查到资料时返回)' },
qqLevel: { type: 'integer', description: 'QQ 等级,同 qq_level' },
reg_time: { type: 'integer', description: '注册时间戳(秒),不可用时省略' },
is_vip: { type: 'boolean', description: '超级会员状态,兼容 NapCat;不可用时省略' },
is_years_vip: { type: 'boolean', description: '年费会员状态,不可用时省略' },
vip_level: { type: 'integer', description: '会员等级,不可用时省略' },
level: { type: 'integer', description: 'QQ 等级,同 qq_level(仅查到资料时返回)' },
status: { type: 'integer', description: '在线状态码' },
extStatus: { type: 'integer', description: '扩展状态码' },
@@ -108,6 +108,8 @@ export const actions = [
last_sent_time: { type: 'integer', description: '最后发言时间戳(秒)' },
shut_up_timestamp: { type: 'integer', description: '禁言结束时间戳(秒,未禁言时为 0)' },
level: { type: 'string', description: '群等级' },
qq_level: { type: 'integer', description: 'QQ 等级,仅在账号资料可用时返回' },
qage: { type: 'integer', description: '按注册时间计算的完整周年数(UTC),注册时间不可用时省略' },
role: { type: 'string', enum: ['owner', 'admin', 'member'], description: '角色' },
title: { type: 'string', description: '专属头衔' },
area: { type: 'string', description: '地区(QQ NT 不提供,恒空)' },
@@ -151,6 +153,8 @@ export const actions = [
last_sent_time: { type: 'integer', description: '最后发言时间戳(秒)' },
shut_up_timestamp: { type: 'integer', description: '禁言结束时间戳(秒,未禁言时为 0)' },
level: { type: 'string', description: '群等级' },
qq_level: { type: 'integer', description: 'QQ 等级,仅在账号资料可用时返回' },
qage: { type: 'integer', description: '按注册时间计算的完整周年数(UTC),注册时间不可用时省略' },
role: { type: 'string', enum: ['owner', 'admin', 'member'], description: '角色' },
title: { type: 'string', description: '专属头衔' },
area: { type: 'string', description: '地区(QQ NT 不提供,恒空)' },
+25 -3
View File
@@ -256,11 +256,12 @@ export async function getGroupMemberInfo(
// 企点标志(#404 后续 PR):优先读身份缓存,无缓存时再按需拉取一次用户资料。
// 均为 best-effort —— 失败时回退为 0,不影响成员信息主流程。
let profile = cachedQidianProfile(bridge, userId);
if (!profile) {
if (noCache || !profile) {
try {
profile = await bridge.apis.contacts.fetchUserProfile(userId);
} catch {
// profile enrichment is best-effort; fall back to all-zero flags
} catch (error) {
log.warn('group member profile unavailable: group=%d member=%d error=%s',
groupId, userId, error instanceof Error ? error.message : String(error));
}
}
return formatGroupMember(groupId, m, profile ?? undefined);
@@ -304,13 +305,20 @@ export async function getGroupFiles(
function formatStrangerInfo(p: UserProfileInfo, corp?: QidianCorpInfo | null): JsonObject {
return {
user_id: p.uin,
uid: p.uid,
qid: p.qid,
nickname: p.nickname,
remark: p.remark,
sex: p.sex,
age: p.age,
long_nick: p.sign,
qq_level: p.level,
qqLevel: p.level,
level: p.level,
...(p.regTime !== undefined ? { reg_time: p.regTime } : {}),
...(p.svipFlag !== undefined ? { is_vip: p.svipFlag } : {}),
...(p.yearVipFlag !== undefined ? { is_years_vip: p.yearVipFlag } : {}),
...(p.vipLevel !== undefined ? { vip_level: p.vipLevel } : {}),
status: p.status ?? 0,
extStatus: p.extStatus ?? 0,
ext_status: p.extStatus ?? 0,
@@ -563,6 +571,7 @@ function formatGroupMember(
`group member robot classification unavailable: group=${groupId} member=${member.uin}`,
);
}
const qage = accountAge(profile?.regTime);
return {
group_id: groupId,
user_id: member.uin,
@@ -575,6 +584,8 @@ function formatGroupMember(
last_sent_time: member.lastSentTime,
shut_up_timestamp: member.shutUpTime,
level: String(member.level),
...(profile ? { qq_level: profile.level } : {}),
...(qage !== undefined ? { qage } : {}),
role: member.role,
title: member.title,
// OneBot v11 completeness (#197). QQ NT doesn't expose these, so they're
@@ -592,6 +603,17 @@ function formatGroupMember(
};
}
/** Completed UTC calendar years since registration; unavailable dates stay absent. */
function accountAge(regTime: number | undefined): number | undefined {
if (regTime === undefined || !Number.isSafeInteger(regTime) || regTime <= 0) return undefined;
const now = new Date();
const registered = new Date(regTime * 1000);
if (!Number.isFinite(registered.getTime()) || registered > now) return undefined;
const years = now.getUTCFullYear() - registered.getUTCFullYear();
registered.setUTCFullYear(now.getUTCFullYear());
return years - (registered > now ? 1 : 0);
}
/** Best-effort read of a cached user profile's qidian flags. Triggers no
* network call — only the identity cache (populated by fetchUserProfile /
* fetchUserProfileByUid). */
@@ -467,6 +467,24 @@ describe('onebot/contact-actions / getGroupMemberList', () => {
});
describe('onebot/contact-actions / getGroupMemberInfo', () => {
it('includes account level and completed account years without changing group level', async () => {
vi.useFakeTimers();
vi.setSystemTime(new Date('2026-10-04T00:00:00Z'));
try {
const profile = { ...makeProfile(88, 'member'), level: 64, regTime: Date.parse('2016-10-05T00:00:00Z') / 1000 };
const fetchUserProfile = vi.fn(async () => profile);
const bridge = fakeBridge({
fetchUserProfile,
identity: fakeIdentity({ findGroupMember: () => makeMember(88, 'member') }),
});
expect(await getGroupMemberInfo(bridge, 1400, 88)).toMatchObject({ level: '1', qq_level: 64, qage: 9 });
vi.setSystemTime(new Date('2026-10-05T00:00:00Z'));
expect(await getGroupMemberInfo(bridge, 1400, 88)).toMatchObject({ qage: 10 });
} finally {
vi.useRealTimers();
}
});
it('returns the cached member when present and noCache is false', async () => {
const member = makeMember(44, 'dave', 'D');
const bridge = fakeBridge({
@@ -581,6 +599,27 @@ describe('onebot/contact-actions / getGroupMemberInfo', () => {
});
describe('onebot/contact-actions / getStrangerInfo', () => {
it('exposes available compatibility fields without fabricating login days', async () => {
const bridge = fakeBridge({ fetchUserProfile: vi.fn(async () => ({
...makeProfile(55555, 'member'), qid: 'my_qid', level: 64, regTime: 1_200_000_000,
svipFlag: true, yearVipFlag: false, vipLevel: 7,
})) });
const out = await getStrangerInfo(bridge, 55555);
expect(out).toMatchObject({
uid: 'u_55555', qid: 'my_qid', qq_level: 64, qqLevel: 64, level: 64,
reg_time: 1_200_000_000, is_vip: true, is_years_vip: false, vip_level: 7,
});
expect(out).not.toHaveProperty('login_days');
});
it('omits unavailable registration and membership values', async () => {
const bridge = fakeBridge({ fetchUserProfile: vi.fn(async () => makeProfile(55555, 'member')) });
const out = await getStrangerInfo(bridge, 55555);
for (const field of ['reg_time', 'is_vip', 'is_years_vip', 'vip_level']) {
expect(out).not.toHaveProperty(field);
}
});
it('returns a fetched profile', async () => {
const bridge = fakeBridge({
fetchUserProfile: vi.fn(async () => makeProfile(
@@ -810,6 +810,7 @@ describe('buildApiContext contact reads', () => {
uin: 20002,
uid: 'u_20002',
nickname: 'stranger',
qid: 'qid_20002',
remark: 'r',
sex: 'female',
age: 21,
@@ -822,12 +823,15 @@ describe('buildApiContext contact reads', () => {
await expect(api.getStrangerInfo(20002)).resolves.toEqual({
user_id: 20002,
uid: 'u_20002',
qid: 'qid_20002',
nickname: 'stranger',
remark: 'r',
sex: 'female',
age: 21,
long_nick: 'hello sign',
qq_level: 17,
qqLevel: 17,
level: 17,
status: 0,
extStatus: 0,
@@ -22,12 +22,13 @@ import type {
OidbUserInfoResponse,
} from '@snowluma/proto-defs/oidb-actions/base';
import type { UserProfileInfo } from '../../qq-info';
import { applyOnlineStatus } from './fetch-user-profile';
import { applyOnlineStatus, applyProfileDetails } from './fetch-user-profile';
import { invokeOidb, type OidbSender } from '../../oidb-service';
const REQUESTED_KEYS = [
20002, 27394, 20009, 20031, 101, 103, 102, 20020, 20003, 20026,
105, 27372, 27406, 20037,
41756, 41757, 42241,
// 企点标志(QQ 企点 / 企业版 QQ 账号):员工号实测为 1,普通账号为 0
40410, 42031,
];
@@ -88,6 +89,7 @@ export namespace FetchUserProfileByUid {
info.age = numMap.get(20037) ?? 0;
info.level = numMap.get(105) ?? 0;
applyOnlineStatus(info, bytesMap, numMap);
applyProfileDetails(info, numMap);
// 企点标志:40410 / 42031,服务器仅在返回时才出现(普通账号缺省 → 0)
info.qidianMasterFlag = numMap.get(42031) ?? 0;
info.qidianCrewFlag = numMap.get(40410) ?? 0;
@@ -52,9 +52,29 @@ export function applyOnlineStatus(
}
}
export function applyProfileDetails(info: UserProfileInfo, numMap: Map<number, number>): void {
const registered = numMap.get(20026);
if (registered !== undefined && registered > 0) info.regTime = registered;
const flags = numMap.get(41756);
if (flags !== undefined) {
info.vipFlag = (flags & 1) !== 0;
info.yearVipFlag = (flags & 2) !== 0;
info.svipFlag = (flags & 0x100) !== 0;
}
const level = numMap.get(41757);
if (level !== undefined) {
const mask = level & 0xFFF;
if (mask !== 0) info.vipLevel = 33 - Math.clz32(mask);
else if (info.vipFlag || info.yearVipFlag || info.svipFlag || numMap.get(42241) === 1) {
info.vipLevel = 1;
} else if (flags !== undefined && numMap.has(42241)) info.vipLevel = 0;
}
}
const REQUESTED_KEYS = [
20002, 27394, 20009, 20031, 101, 103, 102, 20020, 20003, 20026,
105, 27372, 27406, 20037,
41756, 41757, 42241,
// 企点标志(QQ 企点 / 企业版 QQ 账号):员工号实测为 1,普通账号为 0
40410, 42031,
];
@@ -119,6 +139,7 @@ export namespace FetchUserProfile {
info.age = numMap.get(20037) ?? 0;
info.level = numMap.get(105) ?? 0;
applyOnlineStatus(info, bytesMap, numMap);
applyProfileDetails(info, numMap);
// 企点标志:40410 / 42031,服务器仅在返回时才出现(普通账号缺省 → 0)
info.qidianMasterFlag = numMap.get(42031) ?? 0;
info.qidianCrewFlag = numMap.get(40410) ?? 0;
+5
View File
@@ -12,6 +12,11 @@ export interface UserProfileInfo {
* Already requested in `fetchUserProfile` keys[]; LagrangeV2
* `FetchStrangerService.cs` confirms `// Level`. */
level: number;
regTime?: number;
vipFlag?: boolean;
yearVipFlag?: boolean;
svipFlag?: boolean;
vipLevel?: number;
status?: number;
extStatus?: number;
batteryStatus?: number;
@@ -2,11 +2,12 @@ import { describe, expect, it, vi } from 'vitest';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type {
AvatarInfo, OidbUserInfoRequest, OidbUserInfoResponse,
AvatarInfo, OidbUserInfoRequest, OidbUserInfoByUidRequest, OidbUserInfoResponse,
} from '@snowluma/proto-defs/oidb-actions/base';
import type { SendPacketResult } from '@snowluma/common/packet-sender';
import { FetchUserProfile } from '../../../src/oidb-services/contacts/fetch-user-profile';
import { FetchUserProfileByUid } from '../../../src/oidb-services/contacts/fetch-user-profile-by-uid';
function makeSender(body?: OidbUserInfoResponse) {
const responseData = body !== undefined
@@ -24,6 +25,48 @@ describe('FetchUserProfile namespace', () => {
});
describe('invoke (e2e)', () => {
it.each(['uin', 'uid'])('preserves registration and membership through the %s request', async form => {
const sender = makeSender({ body: { uin: 10001, uid: 'u_test', properties: {
numberProperties: [
{ number1: 20026, number2: 1_200_000_000 },
{ number1: 41756, number2: 0x103 },
{ number1: 41757, number2: 1 << 5 },
{ number1: 42241, number2: 0 },
],
} } });
const profile = form === 'uin'
? await FetchUserProfile.invoke(sender, { uin: 10001 })
: await FetchUserProfileByUid.invoke(sender, { uid: 'u_test' });
expect(profile).toMatchObject({
regTime: 1_200_000_000, vipFlag: true, yearVipFlag: true, svipFlag: true, vipLevel: 7,
});
const [, bytes] = sender.sendRawPacket.mock.calls[0]!;
const request = form === 'uin'
? protobuf_decode<OidbBase<OidbUserInfoRequest>>(bytes)
: protobuf_decode<OidbBase<OidbUserInfoByUidRequest>>(bytes);
expect(request.body?.keys?.map(k => k.key))
.toEqual(expect.arrayContaining([20026, 41756, 41757, 42241]));
});
it.each([
[0, 0, 0], [1, 0, 1], [0x100, 1, 2], [0x103, 0x801, 13],
])('decodes membership flags %i and level mask %i as level %i', async (flags, mask, level) => {
const sender = makeSender({ body: { uin: 10001, properties: { numberProperties: [
{ number1: 41756, number2: flags }, { number1: 41757, number2: mask },
{ number1: 42241, number2: 0 },
] } } });
expect(await FetchUserProfile.invoke(sender, { uin: 10001 })).toMatchObject({
vipFlag: !!(flags & 1), yearVipFlag: !!(flags & 2), svipFlag: !!(flags & 0x100), vipLevel: level,
});
});
it('keeps missing registration and membership fields unavailable', async () => {
const profile = await FetchUserProfile.invoke(makeSender({ body: { uin: 10001 } }), { uin: 10001 });
for (const name of ['regTime', 'vipFlag', 'yearVipFlag', 'svipFlag', 'vipLevel']) {
expect(profile).not.toHaveProperty(name);
}
});
it('routes to OidbSvcTrpcTcp.0xfe1_2 with reserved=1', async () => {
const sender = makeSender({ body: { uin: 10001, uid: 'u' } as any });
await FetchUserProfile.invoke(sender, { uin: 10001 });