feat(onebot): query group todo messages

Fixes #332
This commit is contained in:
DrSmoothl
2026-08-09 13:36:41 +08:00
parent 4aba81ec6b
commit c08150fc0c
12 changed files with 1066 additions and 11 deletions
+12 -1
View File
@@ -4,6 +4,10 @@ import {
type AiVoiceCategory as NamespaceAiVoiceCategory,
} from '@snowluma/protocol/oidb-services/extras/fetch-ai-voice-list';
import { GetStrangerStatus, type StrangerStatus as NamespaceStrangerStatus } from '@snowluma/protocol/oidb-services/extras/get-stranger-status';
import {
GetGroupTodoList,
type GroupTodoListItem as NamespaceGroupTodoListItem,
} from '@snowluma/protocol/oidb-services/extras/get-group-todo-list';
import { GroupTodo } from '@snowluma/protocol/oidb-services/extras/group-todo';
import { convertAudioBytes } from '@snowluma/protocol/highway/ffmpeg-addon';
import { loadBinarySource } from '@snowluma/protocol/highway/utils';
@@ -35,6 +39,7 @@ export interface PttTransInput {
// ─────────────── public types (re-exported from bridge.ts as before) ───
export type StrangerStatus = NamespaceStrangerStatus;
export type GroupTodoListItem = NamespaceGroupTodoListItem;
export const AiVoiceChatType = {
Unknown: 0,
@@ -87,7 +92,13 @@ export class ExtrasApi {
constructor(private readonly ctx: BridgeContext) { }
// ─────────────── Group todo (0xF90) ───────────────
// ─────────────── Group todo query / mutations (0x9474 / 0xF90) ───────────────
async getGroupTodoList(groupId: number): Promise<GroupTodoListItem[]> {
const items = await GetGroupTodoList.invoke(this.ctx, { groupId });
log.debug('group todo list fetched group=%d count=%d', groupId, items.length);
return items;
}
setGroupTodo(groupId: number, msgSeq: bigint): Promise<void> {
return GroupTodo.invoke(this.ctx, { groupId, msgSeq, action: 'set' });
+18 -2
View File
@@ -5,6 +5,8 @@ import type { QQEventVariant } from '@snowluma/protocol/events';
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type {
OidbGroupTodo,
OidbQueryGroupTopBannersReq,
OidbQueryGroupTopBannersResp,
OidbStrangerStatusReq,
OidbStrangerStatusResp,
} from '@snowluma/proto-defs/oidb-actions/base';
@@ -15,7 +17,7 @@ import type {
OidbAiVoiceResp,
} from '@snowluma/proto-defs/oidb-actions/media';
// Post-namespace migration: ExtrasApi forwards 6 OIDB cmds through
// Post-namespace migration: ExtrasApi forwards OIDB cmds through
// namespaces under @snowluma/protocol/oidb-services/extras. Tests assert
// against bridge.sendRawPacket directly.
import { ExtrasApi, AiVoiceChatType } from '../../src/bridge/apis/extras';
@@ -28,7 +30,21 @@ function packResponse(body: Uint8Array) {
};
}
describe('apis/extras / group todo (0xF90)', () => {
describe('apis/extras / group todo (0x9474 / 0xF90)', () => {
it('getGroupTodoList dispatches the todo-only banner query', async () => {
const bridge = mockBridge();
bridge.sendRawPacket.mockResolvedValueOnce(packResponse(
protobuf_encode<OidbBase<OidbQueryGroupTopBannersResp>>({ body: {} }),
));
await expect(new ExtrasApi(bridge as any).getGroupTodoList(12345)).resolves.toEqual([]);
const [wireName, bytes] = bridge.sendRawPacket.mock.calls[0]!;
expect(wireName).toBe('OidbSvcTrpcTcp.0x9474_0');
const env = protobuf_decode<OidbBase<OidbQueryGroupTopBannersReq>>(bytes);
expect(env.body).toEqual({ groupId: 12345n, bannerFlag: 1 });
});
it.each([
['setGroupTodo', 'OidbSvcTrpcTcp.0xf90_1'] as const,
['completeGroupTodo', 'OidbSvcTrpcTcp.0xf90_2'] as const,
+289 -2
View File
@@ -1890,6 +1890,73 @@
},
"category": "扩展"
},
{
"name": "fetch_custom_face_detail",
"aliases": [],
"summary": "获取自定义表情详情",
"returns": "自定义表情详情数组,包含资源标识、图片地址、摘要与描述。",
"returnsSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"emoji_id": {
"type": "string",
"description": "可传给 SnowLuma 表情管理接口的资源标识"
},
"resId": {
"type": "string",
"description": "兼容 NapCat 的资源标识"
},
"url": {
"type": "string",
"description": "表情图片地址"
},
"md5": {
"type": "string",
"description": "表情内容摘要"
},
"desc": {
"type": "string",
"description": "自定义表情描述;未设置时为空字符串"
}
},
"required": [
"emoji_id",
"resId",
"url",
"md5",
"desc"
]
}
},
"readOnly": true,
"params": [
{
"name": "count",
"type": "int",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
},
"default": 48
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0,
"default": 48
}
},
"additionalProperties": true
},
"category": "扩展"
},
{
"name": "fetch_emoji_like",
"aliases": [],
@@ -5768,6 +5835,43 @@
},
"category": "群信息"
},
{
"name": "get_group_todo_list",
"aliases": [],
"summary": "获取群待办列表",
"returns": "群待办数组,包含可用于待办操作的消息标识、服务端摘要与时间",
"readOnly": true,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
}
},
"required": [
"group_id"
],
"additionalProperties": true
},
"category": "扩展"
},
{
"name": "get_image",
"aliases": [],
@@ -9797,6 +9901,141 @@
},
"category": "群管理"
},
{
"name": "set_group_member_invite_policy",
"aliases": [],
"summary": "设置群成员邀请策略",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "policy",
"type": "enum",
"required": true,
"values": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
],
"schema": {
"enum": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
]
}
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"policy": {
"enum": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
]
}
},
"required": [
"group_id",
"policy"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_member_permissions",
"aliases": [],
"summary": "设置群成员权限",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "allow_member_upload_album",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "allow_member_temporary_session",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "allow_member_create_group",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"invariants": [
"at least one of: allow_member_upload_album, allow_member_temporary_session, allow_member_create_group"
],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"allow_member_upload_album": {
"type": "boolean"
},
"allow_member_temporary_session": {
"type": "boolean"
},
"allow_member_create_group": {
"type": "boolean"
}
},
"required": [
"group_id"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_name",
"aliases": [],
@@ -9846,6 +10085,54 @@
},
"category": "群管理"
},
{
"name": "set_group_new_member_history_visibility",
"aliases": [],
"summary": "设置新成员是否可查看历史消息",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "visible",
"type": "bool",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"visible": {
"type": "boolean"
}
},
"required": [
"group_id",
"visible"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_portrait",
"aliases": [],
@@ -11657,7 +11944,7 @@
},
{
"category": "群管理",
"count": 14
"count": 17
},
{
"category": "群文件",
@@ -11669,7 +11956,7 @@
},
{
"category": "扩展",
"count": 111
"count": 113
},
{
"category": "群相册",
+289 -2
View File
@@ -1893,6 +1893,73 @@ export const ACTIONS: CatalogAction[] = [
},
"category": "扩展"
},
{
"name": "fetch_custom_face_detail",
"aliases": [],
"summary": "获取自定义表情详情",
"returns": "自定义表情详情数组,包含资源标识、图片地址、摘要与描述。",
"returnsSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"emoji_id": {
"type": "string",
"description": "可传给 SnowLuma 表情管理接口的资源标识"
},
"resId": {
"type": "string",
"description": "兼容 NapCat 的资源标识"
},
"url": {
"type": "string",
"description": "表情图片地址"
},
"md5": {
"type": "string",
"description": "表情内容摘要"
},
"desc": {
"type": "string",
"description": "自定义表情描述;未设置时为空字符串"
}
},
"required": [
"emoji_id",
"resId",
"url",
"md5",
"desc"
]
}
},
"readOnly": true,
"params": [
{
"name": "count",
"type": "int",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
},
"default": 48
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 0,
"default": 48
}
},
"additionalProperties": true
},
"category": "扩展"
},
{
"name": "fetch_emoji_like",
"aliases": [],
@@ -5771,6 +5838,43 @@ export const ACTIONS: CatalogAction[] = [
},
"category": "群信息"
},
{
"name": "get_group_todo_list",
"aliases": [],
"summary": "获取群待办列表",
"returns": "群待办数组,包含可用于待办操作的消息标识、服务端摘要与时间",
"readOnly": true,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
}
},
"required": [
"group_id"
],
"additionalProperties": true
},
"category": "扩展"
},
{
"name": "get_image",
"aliases": [],
@@ -9800,6 +9904,141 @@ export const ACTIONS: CatalogAction[] = [
},
"category": "群管理"
},
{
"name": "set_group_member_invite_policy",
"aliases": [],
"summary": "设置群成员邀请策略",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "policy",
"type": "enum",
"required": true,
"values": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
],
"schema": {
"enum": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
]
}
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"policy": {
"enum": [
"disabled",
"require_approval",
"no_approval",
"no_approval_under_100"
]
}
},
"required": [
"group_id",
"policy"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_member_permissions",
"aliases": [],
"summary": "设置群成员权限",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "allow_member_upload_album",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "allow_member_temporary_session",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "allow_member_create_group",
"type": "bool",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"invariants": [
"at least one of: allow_member_upload_album, allow_member_temporary_session, allow_member_create_group"
],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"allow_member_upload_album": {
"type": "boolean"
},
"allow_member_temporary_session": {
"type": "boolean"
},
"allow_member_create_group": {
"type": "boolean"
}
},
"required": [
"group_id"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_name",
"aliases": [],
@@ -9849,6 +10088,54 @@ export const ACTIONS: CatalogAction[] = [
},
"category": "群管理"
},
{
"name": "set_group_new_member_history_visibility",
"aliases": [],
"summary": "设置新成员是否可查看历史消息",
"readOnly": false,
"params": [
{
"name": "group_id",
"type": "uint",
"required": true,
"role": "group_id",
"schema": {
"type": "integer",
"minimum": 1
},
"desc": "群号"
},
{
"name": "visible",
"type": "bool",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"invariants": [],
"inputSchema": {
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"minimum": 1,
"description": "群号",
"x-role": "group_id"
},
"visible": {
"type": "boolean"
}
},
"required": [
"group_id",
"visible"
],
"additionalProperties": true
},
"category": "群管理"
},
{
"name": "set_group_portrait",
"aliases": [],
@@ -11661,7 +11948,7 @@ export const CATEGORIES: CatalogCategory[] = [
},
{
"category": "群管理",
"count": 14
"count": 17
},
{
"category": "群文件",
@@ -11673,7 +11960,7 @@ export const CATEGORIES: CatalogCategory[] = [
},
{
"category": "扩展",
"count": 111
"count": 113
},
{
"category": "群相册",
+46
View File
@@ -2475,6 +2475,52 @@ export const actions = [
},
}),
groupAction({
name: 'get_group_todo_list',
summary: '获取群待办列表',
returns: '群待办数组,包含可用于待办操作的消息标识、服务端摘要与时间',
readOnly: true,
run: async (p, ctx) => {
const todos = await ctx.bridge.apis.extras.getGroupTodoList(p.group_id);
const projections = todos.map((todo) => {
const messageId = hashMessageIdInt32(
todo.sequence,
p.group_id,
GROUP_MESSAGE_EVENT,
);
const meta: MessageMeta = {
isGroup: true,
targetId: p.group_id,
sequence: todo.sequence,
sequenceAuthoritative: true,
eventName: GROUP_MESSAGE_EVENT,
clientSequence: 0,
random: todo.random,
timestamp: todo.createdAt,
};
return { todo, messageId, meta };
});
ctx.cacheMessageMetas(projections.map(({ messageId, meta }) => ({
messageId,
meta,
})));
return okResponse(projections.map(({ todo, messageId }) => {
const cached = ctx.getMessage(messageId)?.message;
return {
message_id: messageId,
message_seq: todo.sequence,
message_random: todo.random,
message: Array.isArray(cached) ? cached : null,
text: todo.text,
create_time: todo.createdAt,
update_time: todo.updatedAt,
};
}));
},
}),
groupAction({
name: 'set_group_todo',
summary: '设置群待办',
@@ -90,9 +90,9 @@ describe('compileActionRegistry namespace conflicts', () => {
});
describe('compiled production Action registry', () => {
it('preserves all 187 canonical Action docs', () => {
expect(ACTION_REGISTRY.actions).toHaveLength(187);
expect(collectActionDocs()).toHaveLength(187);
it('preserves all 190 canonical Action docs', () => {
expect(ACTION_REGISTRY.actions).toHaveLength(190);
expect(collectActionDocs()).toHaveLength(190);
});
it('resolves every executable name to exactly one canonical doc', () => {
@@ -72,6 +72,7 @@ const APIS_ROUTING: Record<string, [string, string]> = {
setGroupTodo: ['extras', 'setGroupTodo'],
completeGroupTodo: ['extras', 'completeGroupTodo'],
cancelGroupTodo: ['extras', 'cancelGroupTodo'],
getGroupTodoList: ['extras', 'getGroupTodoList'],
getStrangerStatus: ['extras', 'getStrangerStatus'],
fetchAiVoiceList: ['extras', 'fetchAiVoiceList'],
fetchAiVoice: ['extras', 'fetchAiVoice'],
@@ -1176,6 +1177,82 @@ describe('extended-actions / set_/complete_/cancel_group_todo', () => {
});
});
describe('extended-actions / get_group_todo_list', () => {
it('maps QQ identities to OneBot ids, caches metadata, and includes cached content', async () => {
const getGroupTodoList = vi.fn(async () => [{
sourceId: '5631_0',
sequence: 5631,
random: 0,
text: '测试待办',
createdAt: 1735000000,
updatedAt: 1735000001,
}]);
const bridge = fakeBridge({ getGroupTodoList });
const messageId = hashMessageIdInt32(5631, 100, GROUP_MESSAGE_EVENT);
const cacheMessageMetas = vi.fn();
const message = [{ type: 'text', data: { text: '原消息' } }];
const ctx = fakeCtx(bridge, {
cacheMessageMetas,
getMessage: (id) => id === messageId ? { message } : null,
});
const response = await makeHandler(ctx).handle('get_group_todo_list', { group_id: 100 });
expect(getGroupTodoList).toHaveBeenCalledWith(100);
expect(cacheMessageMetas).toHaveBeenCalledWith([{
messageId,
meta: {
isGroup: true,
targetId: 100,
sequence: 5631,
sequenceAuthoritative: true,
eventName: GROUP_MESSAGE_EVENT,
clientSequence: 0,
random: 0,
timestamp: 1735000000,
},
}]);
expect(response).toMatchObject({
status: 'ok',
data: [{
message_id: messageId,
message_seq: 5631,
message_random: 0,
message,
text: '测试待办',
create_time: 1735000000,
update_time: 1735000001,
}],
});
});
it('still returns a usable message id when the original body is not cached', async () => {
const bridge = fakeBridge({
getGroupTodoList: vi.fn(async () => [{
sourceId: '88_0',
sequence: 88,
random: 0,
text: '',
createdAt: 0,
updatedAt: 0,
}]),
});
const response = await makeHandler(fakeCtx(bridge)).handle(
'get_group_todo_list',
{ group_id: 100 },
);
expect(response).toMatchObject({
status: 'ok',
data: [{
message_id: hashMessageIdInt32(88, 100, GROUP_MESSAGE_EVENT),
message_seq: 88,
message: null,
}],
});
});
});
describe('extended-actions / set_group_reaction', () => {
it('rejects a local-only message id without calling the reaction protocol', async () => {
const setGroupReaction = vi.fn(async () => {});
@@ -955,6 +955,64 @@ export interface OidbGroupTodo {
groupUin?: pb<1, uint_32>;
msgSeq?: pb<2, uint_64>;
}
// 0x9474_0 — query group top banners. A request flag of 1 selects group
// todos; current QQ represents them with commonBanner while older responses
// may still use the legacy todoBanner shape.
export interface OidbQueryGroupTopBannersReq {
groupId?: pb<1, uint_64>;
bannerFlag?: pb<2, uint_32>;
}
export interface OidbGroupTopBannerUi {
iconUrl?: pb<1, string>;
preText?: pb<2, string>;
text?: pb<3, string>;
highText?: pb<4, string>;
accessoryType?: pb<5, uint_32>;
iconColor?: pb<6, uint_32>;
needTranslation?: pb<7, bool>;
}
export interface OidbGroupTopBannerJumpInfo {
jumpType?: pb<1, uint_32>;
jumpUrl?: pb<2, string>;
jumpParam?: pb<3, bytes>;
}
export interface OidbGroupTopBannerCommon {
ui?: pb<1, OidbGroupTopBannerUi>;
jumpInfo?: pb<2, OidbGroupTopBannerJumpInfo>;
createTime?: pb<3, uint_64>;
updateTime?: pb<4, uint_64>;
}
export interface OidbGroupTodoLegacyBanner {
redText?: pb<1, string>;
text?: pb<2, string>;
url?: pb<3, string>;
isExposure?: pb<4, bool>;
isComplete?: pb<5, bool>;
}
export interface OidbGroupTopBannerPriority {
categoryType?: pb<1, uint_32>;
priority?: pb<2, int_32>;
}
export interface OidbOnlineBanner {
bizType?: pb<1, uint_32>;
bannerType?: pb<2, uint_32>;
msgId?: pb<3, bytes>;
isDisappear?: pb<4, bool>;
expireTime?: pb<8, uint_64>;
todoBanner?: pb<12, OidbGroupTodoLegacyBanner>;
commonBanner?: pb<20, OidbGroupTopBannerCommon>;
bannerPriority?: pb<40, OidbGroupTopBannerPriority>;
bizId?: pb<41, int_32>;
priority?: pb<42, int_32>;
leftShowTimes?: pb<43, int_32>;
supportMultiBanners?: pb<44, bool>;
supportLongPress?: pb<45, bool>;
noNeedReportShow?: pb<46, bool>;
}
export interface OidbQueryGroupTopBannersResp {
banners?: pb_repeated<1, OidbOnlineBanner>;
newSeq?: pb<3, uint_64>;
}
export interface OidbStrangerStatusKey {
key?: pb<1, uint_32>;
}
@@ -0,0 +1,149 @@
// 0x9474_0 — query the group's current todo banners.
//
// Current QQ exposes this as a packet-backed query. Request flag 1 selects
// todos. Each active banner identifies its source message twice: msgId carries
// `sequence_random`, while commonBanner.jumpInfo.jumpParam carries JSON with
// the same pair. Both sources are checked when present so a malformed identity
// can never poison SnowLuma's message-id cache.
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type {
OidbOnlineBanner,
OidbQueryGroupTopBannersReq,
OidbQueryGroupTopBannersResp,
} from '@snowluma/proto-defs/oidb-actions/base';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import { invokeOidb, type OidbSender } from '../../oidb-service';
export interface GroupTodoListItem {
sourceId: string;
sequence: number;
random: number;
text: string;
createdAt: number;
updatedAt: number;
}
interface MessageIdentity {
sequence: number;
random: number;
}
const TODO_BANNER_FLAG = 1;
const SOURCE_ID_PATTERN = /^([1-9]\d*)_(-?\d+)$/;
const utf8 = new TextDecoder('utf-8', { fatal: true });
function decodeUtf8(bytes: Uint8Array, description: string): string {
try {
return utf8.decode(bytes);
} catch {
throw new Error(`invalid group todo ${description}`);
}
}
function parseSafeInteger(value: unknown, description: string): number {
if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
throw new Error(`invalid group todo ${description}`);
}
return value;
}
function parseSourceIdentity(bytes: Uint8Array | undefined): MessageIdentity & { sourceId: string } {
if (!bytes || bytes.length === 0) {
throw new Error('invalid group todo message identity');
}
const sourceId = decodeUtf8(bytes, 'message identity');
const match = SOURCE_ID_PATTERN.exec(sourceId);
if (!match) throw new Error('invalid group todo message identity');
const sequence = Number(match[1]);
const random = Number(match[2]);
if (!Number.isSafeInteger(sequence) || sequence <= 0 || !Number.isSafeInteger(random)) {
throw new Error('invalid group todo message identity');
}
return { sourceId, sequence, random };
}
function parseJumpIdentity(bytes: Uint8Array | undefined): MessageIdentity | null {
if (!bytes || bytes.length === 0) return null;
let decoded: unknown;
try {
decoded = JSON.parse(decodeUtf8(bytes, 'jump identity'));
} catch (error) {
if (error instanceof Error && error.message.startsWith('invalid group todo')) throw error;
throw new Error('invalid group todo jump identity');
}
if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
throw new Error('invalid group todo jump identity');
}
const record = decoded as Record<string, unknown>;
const sequence = parseSafeInteger(record.seq, 'jump identity');
const random = parseSafeInteger(record.random, 'jump identity');
if (sequence <= 0) throw new Error('invalid group todo jump identity');
return { sequence, random };
}
function parseTimestamp(value: bigint | number | null | undefined, description: string): number {
if (value === undefined || value === null) return 0;
const timestamp = typeof value === 'bigint' ? Number(value) : value;
if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
throw new Error(`invalid group todo ${description}`);
}
return timestamp;
}
function parseBanner(banner: OidbOnlineBanner): GroupTodoListItem {
const source = parseSourceIdentity(banner.msgId);
const jump = parseJumpIdentity(banner.commonBanner?.jumpInfo?.jumpParam);
if (jump && (jump.sequence !== source.sequence || jump.random !== source.random)) {
throw new Error('group todo message identity mismatch');
}
return {
sourceId: source.sourceId,
sequence: source.sequence,
random: source.random,
text: banner.commonBanner?.ui?.text ?? banner.todoBanner?.text ?? '',
createdAt: parseTimestamp(banner.commonBanner?.createTime, 'create time'),
updatedAt: parseTimestamp(banner.commonBanner?.updateTime, 'update time'),
};
}
export namespace GetGroupTodoList {
export const command = 0x9474;
export const subCommand = 0;
export interface Params {
groupId: number;
}
export type Deps = OidbSender;
export const serialize = (_ctx: Deps, p: Params): OidbQueryGroupTopBannersReq => {
if (!Number.isSafeInteger(p.groupId) || p.groupId <= 0) {
throw new Error('invalid group id');
}
return {
groupId: BigInt(p.groupId),
bannerFlag: TODO_BANNER_FLAG,
};
};
export const deserialize = (
_ctx: Deps,
body: OidbQueryGroupTopBannersResp,
): GroupTodoListItem[] => (body.banners ?? [])
.filter((banner) => banner.isDisappear !== true)
.map(parseBanner);
export const encode = (env: OidbBase<OidbQueryGroupTopBannersReq>): Uint8Array =>
protobuf_encode<OidbBase<OidbQueryGroupTopBannersReq>>(env);
export const decode = (bytes: Uint8Array): OidbBase<OidbQueryGroupTopBannersResp> =>
protobuf_decode<OidbBase<OidbQueryGroupTopBannersResp>>(bytes);
export const invoke = (deps: Deps, params: Params): Promise<GroupTodoListItem[]> =>
invokeOidb(deps, GetGroupTodoList, params);
}
@@ -0,0 +1,112 @@
import { describe, expect, it, vi } from 'vitest';
import { protobuf_decode } from '@snowluma/proton';
import type { SendPacketResult } from '@snowluma/common/packet-sender';
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type { OidbQueryGroupTopBannersReq } from '@snowluma/proto-defs/oidb-actions/base';
import { GetGroupTodoList } from '../../../src/oidb-services/extras/get-group-todo-list';
// Fixed wire fixture shaped after a live QQ 3.2.32-51802 0x9474_0 response.
// It deliberately uses the current common-banner representation rather than
// constructing the response with the production protobuf encoder.
const ACTIVE_TODO_RESPONSE = Buffer.from(
'08f4a802100018002291010a8e01080f10021a06353633315f3040d09ba8bb06'
+ 'a2016a0a3f0a1d68747470733a2f2f6578616d706c652e746573742f746f646f'
+ '2e706e67120ce7bea4e5be85e58a9eefbd9c1a0ce6b58be8af95e5be85e58a9e'
+ '28023003121b08031a177b22736571223a353633312c2272616e646f6d223a307d'
+ '18c0ffa7bb0620c1ffa7bb06c802a29c01d002c801e80201f002012a006000',
'hex',
);
function makeSender(responseData = Buffer.alloc(0)) {
const result: SendPacketResult = {
success: true,
gotResponse: true,
errorCode: 0,
errorMessage: '',
responseData,
};
return { sendRawPacket: vi.fn(async () => result) };
}
describe('GetGroupTodoList namespace', () => {
it('queries 0x9474_0 with the todo-only banner flag', async () => {
const sender = makeSender();
await GetGroupTodoList.invoke(sender, { groupId: 941657197 });
const [wireName, bytes] = sender.sendRawPacket.mock.calls[0]!;
expect(wireName).toBe('OidbSvcTrpcTcp.0x9474_0');
expect(GetGroupTodoList.subCommand).toBe(0);
const envelope = protobuf_decode<OidbBase<OidbQueryGroupTopBannersReq>>(bytes);
expect(envelope).toMatchObject({
command: 0x9474,
body: { groupId: 941657197n, bannerFlag: 1 },
});
});
it('decodes the current common-banner todo and validates both identity sources', async () => {
const sender = makeSender(ACTIVE_TODO_RESPONSE);
await expect(GetGroupTodoList.invoke(sender, { groupId: 941657197 })).resolves.toEqual([
{
sourceId: '5631_0',
sequence: 5631,
random: 0,
text: '测试待办',
createdAt: 1735000000,
updatedAt: 1735000001,
},
]);
});
it('filters disappeared todo tombstones', () => {
expect(GetGroupTodoList.deserialize({} as never, {
banners: [{ bizType: 15, bannerType: 2, isDisappear: true, bizId: 20002 }],
})).toEqual([]);
});
it('supports the legacy todo text shape without inventing timestamps', () => {
expect(GetGroupTodoList.deserialize({} as never, {
banners: [{
msgId: Buffer.from('88_0'),
isDisappear: false,
todoBanner: { text: '旧版待办' },
}],
})).toEqual([{
sourceId: '88_0',
sequence: 88,
random: 0,
text: '旧版待办',
createdAt: 0,
updatedAt: 0,
}]);
});
it('rejects an active todo whose message identity cannot be mapped', () => {
expect(() => GetGroupTodoList.deserialize({} as never, {
banners: [{
bizType: 15,
bannerType: 2,
msgId: Buffer.from('not-a-message-id'),
isDisappear: false,
bizId: 20002,
}],
})).toThrow(/invalid group todo message identity/);
});
it('rejects disagreement between msgId and the jump payload', () => {
expect(() => GetGroupTodoList.deserialize({} as never, {
banners: [{
bizType: 15,
bannerType: 2,
msgId: Buffer.from('5631_0'),
isDisappear: false,
bizId: 20002,
commonBanner: {
jumpInfo: { jumpParam: Buffer.from('{"seq":5632,"random":0}') },
},
}],
})).toThrow(/identity mismatch/);
});
});
+2
View File
@@ -90,6 +90,7 @@ import type {
GroupFileUrl,
GroupMessageHistory,
GroupNoticeInfo,
GroupTodoListItem,
LoginInfo,
MediaInfo,
OnlineClientsInfo,
@@ -247,6 +248,7 @@ export interface SnowLumaActionMap {
nc_get_user_status: { params: NcGetUserStatusParams; data: UserOnlineStatus };
get_group_ignore_add_request: { params: JsonObject; data: JsonArray };
delete_group_folder: { params: DeleteGroupFolderParams; data: EmptyData };
get_group_todo_list: { params: GroupIdParams; data: GroupTodoListItem[] };
set_group_todo: { params: GroupTodoParams; data: EmptyData };
complete_group_todo: { params: GroupTodoParams; data: EmptyData };
cancel_group_todo: { params: GroupTodoParams; data: EmptyData };
+11 -1
View File
@@ -1,4 +1,4 @@
import type { JsonObject, JsonValue } from './json';
import type { JsonArray, JsonObject, JsonValue } from './json';
export interface SendMessageResult {
message_id: number;
@@ -217,6 +217,16 @@ export interface GroupAtAllRemainInfo {
remain_at_all_count_for_uin: number;
}
export interface GroupTodoListItem {
message_id: number;
message_seq: number;
message_random: number;
message: JsonArray | null;
text: string;
create_time: number;
update_time: number;
}
export type EmptyData = null;
// — AI 语音角色:get_ai_characters 返回的分类数组 —