diff --git a/packages/core/src/bridge/apis/extras.ts b/packages/core/src/bridge/apis/extras.ts index 9a5dcacb..76da91fb 100644 --- a/packages/core/src/bridge/apis/extras.ts +++ b/packages/core/src/bridge/apis/extras.ts @@ -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 { + 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 { return GroupTodo.invoke(this.ctx, { groupId, msgSeq, action: 'set' }); diff --git a/packages/core/tests/actions/extras.test.ts b/packages/core/tests/actions/extras.test.ts index 3421d13b..7f4aa8b3 100644 --- a/packages/core/tests/actions/extras.test.ts +++ b/packages/core/tests/actions/extras.test.ts @@ -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>({ 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>(bytes); + expect(env.body).toEqual({ groupId: 12345n, bannerFlag: 1 }); + }); + it.each([ ['setGroupTodo', 'OidbSvcTrpcTcp.0xf90_1'] as const, ['completeGroupTodo', 'OidbSvcTrpcTcp.0xf90_2'] as const, diff --git a/packages/mcp/src/generated/catalog.json b/packages/mcp/src/generated/catalog.json index a5a44970..fe29bb99 100644 --- a/packages/mcp/src/generated/catalog.json +++ b/packages/mcp/src/generated/catalog.json @@ -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": "群相册", diff --git a/packages/mcp/src/generated/catalog.ts b/packages/mcp/src/generated/catalog.ts index c3124532..9083070e 100644 --- a/packages/mcp/src/generated/catalog.ts +++ b/packages/mcp/src/generated/catalog.ts @@ -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": "群相册", diff --git a/packages/onebot/src/actions/extended.ts b/packages/onebot/src/actions/extended.ts index 1f513cbd..06a8f182 100644 --- a/packages/onebot/src/actions/extended.ts +++ b/packages/onebot/src/actions/extended.ts @@ -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: '设置群待办', diff --git a/packages/onebot/tests/action-registry.test.ts b/packages/onebot/tests/action-registry.test.ts index 7133d366..0e91bc67 100644 --- a/packages/onebot/tests/action-registry.test.ts +++ b/packages/onebot/tests/action-registry.test.ts @@ -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', () => { diff --git a/packages/onebot/tests/extended-actions.test.ts b/packages/onebot/tests/extended-actions.test.ts index 2ed5b587..e8d40f55 100644 --- a/packages/onebot/tests/extended-actions.test.ts +++ b/packages/onebot/tests/extended-actions.test.ts @@ -72,6 +72,7 @@ const APIS_ROUTING: Record = { 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 () => {}); diff --git a/packages/proto-defs/src/oidb-actions/base.ts b/packages/proto-defs/src/oidb-actions/base.ts index ba05a1f7..56f2ed3f 100644 --- a/packages/proto-defs/src/oidb-actions/base.ts +++ b/packages/proto-defs/src/oidb-actions/base.ts @@ -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>; } diff --git a/packages/protocol/src/oidb-services/extras/get-group-todo-list.ts b/packages/protocol/src/oidb-services/extras/get-group-todo-list.ts new file mode 100644 index 00000000..5065b485 --- /dev/null +++ b/packages/protocol/src/oidb-services/extras/get-group-todo-list.ts @@ -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; + 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): Uint8Array => + protobuf_encode>(env); + + export const decode = (bytes: Uint8Array): OidbBase => + protobuf_decode>(bytes); + + export const invoke = (deps: Deps, params: Params): Promise => + invokeOidb(deps, GetGroupTodoList, params); +} diff --git a/packages/protocol/tests/oidb-services/extras/get-group-todo-list.test.ts b/packages/protocol/tests/oidb-services/extras/get-group-todo-list.test.ts new file mode 100644 index 00000000..85c0a161 --- /dev/null +++ b/packages/protocol/tests/oidb-services/extras/get-group-todo-list.test.ts @@ -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>(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/); + }); +}); diff --git a/packages/sdk/src/types/actions.ts b/packages/sdk/src/types/actions.ts index 6add8ae1..ea06a6ae 100644 --- a/packages/sdk/src/types/actions.ts +++ b/packages/sdk/src/types/actions.ts @@ -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 }; diff --git a/packages/sdk/src/types/results.ts b/packages/sdk/src/types/results.ts index f8c7b553..bee8a63d 100644 --- a/packages/sdk/src/types/results.ts +++ b/packages/sdk/src/types/results.ts @@ -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 返回的分类数组 —