From 0e8a194d4f1f22fb209ecfb60ff5ad612c73bbd0 Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Fri, 26 Jun 2026 23:05:52 +0800 Subject: [PATCH] feat(onebot): backfill returnsSchema on remaining read-only actions (c2: source-proven only) --- packages/onebot/src/actions/extended.ts | 391 ++++++++++++++++++++- packages/onebot/src/actions/friend.ts | 26 ++ packages/onebot/src/actions/group-album.ts | 51 +++ packages/onebot/src/actions/group-file.ts | 100 +++++- packages/onebot/src/actions/message.ts | 1 + packages/onebot/src/actions/qzone.ts | 48 +++ 6 files changed, 612 insertions(+), 5 deletions(-) diff --git a/packages/onebot/src/actions/extended.ts b/packages/onebot/src/actions/extended.ts index d10265f9..56b06ce6 100644 --- a/packages/onebot/src/actions/extended.ts +++ b/packages/onebot/src/actions/extended.ts @@ -325,6 +325,14 @@ export const actions = [ name: 'get_group_msg_history', summary: '获取群消息历史', readOnly: true, + returns: '{ messages }:群消息事件对象数组(每项为 OneBot 消息事件,内部字段不固定)。', + returnsSchema: { + type: 'object', + properties: { + messages: { type: 'array', description: '消息事件对象数组', items: { type: 'object' } }, + }, + required: ['messages'], + }, params: { // message_id is a signed int32 hash (hashMessageIdInt32) and is // frequently NEGATIVE — a `{min:0}` validator rejects a real anchor at @@ -344,6 +352,14 @@ export const actions = [ name: 'get_friend_msg_history', summary: '获取好友消息历史', readOnly: true, + returns: '{ messages }:好友消息事件对象数组(每项为 OneBot 消息事件,内部字段不固定)。', + returnsSchema: { + type: 'object', + properties: { + messages: { type: 'array', description: '消息事件对象数组', items: { type: 'object' } }, + }, + required: ['messages'], + }, params: { user_id: f.uint(), // Signed int32 hash, frequently negative — see get_group_msg_history. @@ -549,6 +565,14 @@ export const actions = [ name: ['fetch_ptt_text', 'get_ptt_text', 'get_record_text'], summary: '获取语音转文字结果', readOnly: true, + returns: '{ text }:语音识别出的文本。', + returnsSchema: { + type: 'object', + properties: { + text: { type: 'string', description: '语音转写文本' }, + }, + required: ['text'], + }, params: { message_id: f.string().default(''), }, @@ -569,6 +593,14 @@ export const actions = [ name: 'get_cookies', summary: '获取 Cookies', readOnly: true, + returns: '{ cookies }:指定域名的 Cookie 字符串。', + returnsSchema: { + type: 'object', + properties: { + cookies: { type: 'string', description: '该域名的 Cookie 字符串' }, + }, + required: ['cookies'], + }, params: { domain: f.string().default('qun.qq.com') }, run: async (p, ctx) => { try { @@ -584,6 +616,14 @@ export const actions = [ name: 'get_csrf_token', summary: '获取 CSRF 令牌', readOnly: true, + returns: '{ token }:CSRF 令牌(bkn,数值)。', + returnsSchema: { + type: 'object', + properties: { + token: { type: 'integer', description: 'CSRF 令牌(bkn)' }, + }, + required: ['token'], + }, params: {}, run: async (_p, ctx) => { try { @@ -599,6 +639,16 @@ export const actions = [ name: 'get_credentials', summary: '获取凭证', readOnly: true, + returns: '{ cookies, token, csrf_token }:Cookie 字符串与 CSRF 令牌(token 与 csrf_token 同值)。', + returnsSchema: { + type: 'object', + properties: { + cookies: { type: 'string', description: '该域名的 Cookie 字符串' }, + token: { type: 'integer', description: 'CSRF 令牌(bkn)' }, + csrf_token: { type: 'integer', description: 'CSRF 令牌(同 token)' }, + }, + required: ['cookies', 'token', 'csrf_token'], + }, params: { domain: f.string().default('qun.qq.com') }, run: async (p, ctx) => { try { @@ -686,6 +736,17 @@ export const actions = [ name: 'get_group_file_system_info', summary: '获取群文件系统信息', readOnly: true, + returns: '{ file_count, limit_count, used_space, total_space }:群文件数量与容量信息(used_space 恒 0,total_space 为固定 10GiB 常量)。', + returnsSchema: { + type: 'object', + properties: { + file_count: { type: 'integer', description: '当前文件数' }, + limit_count: { type: 'integer', description: '最大文件数' }, + used_space: { type: 'integer', description: '已用空间(占位,恒 0)' }, + total_space: { type: 'integer', description: '总空间(占位,恒 10GiB)' }, + }, + required: ['file_count', 'limit_count', 'used_space', 'total_space'], + }, run: async (p, ctx) => { const info = await ctx.bridge.apis.groupFile.getCount(p.group_id); return okResponse({ @@ -701,6 +762,14 @@ export const actions = [ name: 'check_url_safely', summary: '检查链接安全性', readOnly: true, + returns: '{ level }:安全等级(占位实现,恒为 1)。', + returnsSchema: { + type: 'object', + properties: { + level: { type: 'integer', description: '安全等级(占位,恒 1)' }, + }, + required: ['level'], + }, params: {}, run: async () => { return okResponse({ level: 1 }); @@ -772,6 +841,27 @@ export const actions = [ name: 'get_group_ignored_notifies', summary: '获取被过滤的入群请求', readOnly: true, + returns: '被过滤的入群请求数组,每项含群号、申请人、邀请人、留言与处理标记。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + group_id: { type: 'integer', description: '群号' }, + group_name: { type: 'string', description: '群名称' }, + request_id: { type: 'integer', description: '请求序列号' }, + requester_uin: { type: 'integer', description: '申请人 QQ 号' }, + requester_nick: { type: 'string', description: '申请人昵称' }, + message: { type: 'string', description: '验证留言' }, + checked: { type: 'boolean', description: '是否已处理' }, + actor: { type: 'integer', description: '处理人 QQ 号' }, + invitor_uin: { type: 'integer', description: '邀请人 QQ 号' }, + invitor_nick: { type: 'string', description: '邀请人昵称' }, + flag: { type: 'string', description: '处理用 flag(eventType:groupId:targetUid:filtered)' }, + }, + required: ['group_id', 'group_name', 'request_id', 'requester_uin', 'requester_nick', 'message', 'checked', 'actor', 'invitor_uin', 'invitor_nick', 'flag'], + }, + }, params: {}, run: async (_p, ctx) => { const reqs = await fetchFilteredGroupRequests(ctx); @@ -798,6 +888,25 @@ export const actions = [ name: 'get_group_ignore_add_request', summary: '获取被忽略的入群请求(NapCat)', readOnly: true, + returns: '被忽略的入群请求数组(NapCat 字段命名),每项含请求序列、邀请人、群信息与处理标记。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + request_id: { type: 'integer', description: '请求序列号' }, + invitor_uin: { type: 'integer', description: '邀请人 QQ 号' }, + invitor_nick: { type: 'string', description: '邀请人昵称' }, + group_id: { type: 'integer', description: '群号' }, + message: { type: 'string', description: '验证留言' }, + group_name: { type: 'string', description: '群名称' }, + checked: { type: 'boolean', description: '是否已处理' }, + actor: { type: 'integer', description: '处理人 QQ 号' }, + requester_nick: { type: 'string', description: '申请人昵称' }, + }, + required: ['request_id', 'invitor_uin', 'invitor_nick', 'group_id', 'message', 'group_name', 'checked', 'actor', 'requester_nick'], + }, + }, params: {}, run: async (_p, ctx) => { const reqs = await fetchFilteredGroupRequests(ctx); @@ -825,6 +934,19 @@ export const actions = [ name: 'get_group_shut_list', summary: '获取群禁言列表', readOnly: true, + returns: '仍在禁言中的成员数组,每项含 QQ 号、昵称与禁言到期时间戳(秒)。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + user_id: { type: 'integer', description: '成员 QQ 号' }, + nickname: { type: 'string', description: '成员昵称' }, + shut_up_time: { type: 'integer', description: '禁言到期时间戳(秒)' }, + }, + required: ['user_id', 'nickname', 'shut_up_time'], + }, + }, run: async (p, ctx) => { const members = await ctx.bridge.apis.contacts.fetchGroupMemberList(p.group_id); const nowSec = Math.floor(Date.now() / 1000); @@ -890,6 +1012,36 @@ export const actions = [ name: 'get_profile_like', summary: '获取资料点赞', readOnly: true, + returns: '点赞资料:uid、最近点赞时间、收藏(favoriteInfo)与点赞(voteInfo)统计。', + returnsSchema: { + type: 'object', + properties: { + uid: { type: 'string', description: '用户 uid' }, + time: { type: 'integer', description: '最近点赞时间戳' }, + favoriteInfo: { + type: 'object', + description: '收藏统计', + properties: { + total_count: { type: 'integer', description: '收藏总数' }, + last_time: { type: 'integer', description: '最近收藏时间戳' }, + today_count: { type: 'integer', description: '今日收藏数' }, + userInfos: { type: 'array', description: '用户列表(恒空)' }, + }, + }, + voteInfo: { + type: 'object', + description: '点赞统计', + properties: { + total_count: { type: 'integer', description: '点赞总数' }, + new_count: { type: 'integer', description: '新增点赞数' }, + new_nearby_count: { type: 'integer', description: '附近的人新增点赞数' }, + last_visit_time: { type: 'integer', description: '最近访问时间戳' }, + userInfos: { type: 'array', description: '用户列表(恒空)' }, + }, + }, + }, + required: ['uid', 'time', 'favoriteInfo', 'voteInfo'], + }, params: { // 原实现 user_id 经 asNumber,无校验(0 也透传)。 user_id: f.int({ min: 0 }).default(0), @@ -910,6 +1062,11 @@ export const actions = [ name: 'fetch_custom_face', summary: '获取自定义表情', readOnly: true, + returns: '字符串数组:return_type=url 时为图片 URL,return_type=id 时为 emoji_id。', + returnsSchema: { + type: 'array', + items: { type: 'string', description: '图片 URL 或 emoji_id(取决于 return_type)' }, + }, params: { count: f.int({ min: 0 }).default(10), // return_type=url 返回图片 URL(默认,给前端显示); @@ -937,6 +1094,25 @@ export const actions = [ name: 'get_emoji_likes', summary: '获取表情回应用户', readOnly: true, + returns: '{ emoji_like_list }:回应该表情的用户列表(nick_name 恒为空串)。', + returnsSchema: { + type: 'object', + properties: { + emoji_like_list: { + type: 'array', + description: '回应用户列表', + items: { + type: 'object', + properties: { + user_id: { type: 'string', description: '用户 QQ 号(字符串)' }, + nick_name: { type: 'string', description: '昵称(当前实现恒为空串)' }, + }, + required: ['user_id', 'nick_name'], + }, + }, + }, + required: ['emoji_like_list'], + }, params: { message_id: f.messageId(), emoji_id: f.string({ allowEmpty: false }), @@ -957,6 +1133,31 @@ export const actions = [ name: 'fetch_emoji_like', summary: '获取表情回应用户(NapCat 分页)', readOnly: true, + returns: '分页的表情回应用户列表(NapCat 形状),含分页游标 cookie 与首/末页标记。', + returnsSchema: { + type: 'object', + properties: { + result: { type: 'integer', description: '结果码(恒 0)' }, + errMsg: { type: 'string', description: '错误信息(恒空串)' }, + emojiLikesList: { + type: 'array', + description: '回应用户列表', + items: { + type: 'object', + properties: { + tinyId: { type: 'string', description: '用户 QQ 号(字符串)' }, + nickName: { type: 'string', description: '昵称(恒空串)' }, + headUrl: { type: 'string', description: '头像 URL(恒空串)' }, + }, + required: ['tinyId', 'nickName', 'headUrl'], + }, + }, + cookie: { type: 'string', description: '下一页游标(末页为空串)' }, + isLastPage: { type: 'boolean', description: '是否末页' }, + isFirstPage: { type: 'boolean', description: '是否首页' }, + }, + required: ['result', 'errMsg', 'emojiLikesList', 'cookie', 'isLastPage', 'isFirstPage'], + }, params: { message_id: f.messageId(), emojiId: f.string({ allowEmpty: false }), @@ -1005,6 +1206,8 @@ export const actions = [ name: 'get_recent_contact', summary: '获取最近会话(占位)', readOnly: true, + returns: '占位实现,恒返回空数组。', + returnsSchema: { type: 'array', description: '最近会话列表(占位,恒空)' }, params: { count: f.int({ min: 0 }).default(10), }, @@ -1021,6 +1224,14 @@ export const actions = [ name: 'get_online_clients', summary: '获取在线客户端(占位,OneBot v11 形状)', readOnly: true, + returns: '{ clients }:在线设备列表(占位,clients 恒为空数组)。', + returnsSchema: { + type: 'object', + properties: { + clients: { type: 'array', description: '在线设备列表(占位,恒空)' }, + }, + required: ['clients'], + }, params: {}, run: async () => { return okResponse({ clients: [] }); @@ -1036,6 +1247,24 @@ export const actions = [ name: '_get_model_show', summary: '获取机型展示(兼容 mock)', readOnly: true, + returns: '数组,每项含 variants(回显请求的机型名与 need_pay 标记)。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + variants: { + type: 'object', + properties: { + model_show: { type: 'string', description: '机型展示名(回显请求的 model,缺省 snowluma)' }, + need_pay: { type: 'boolean', description: '是否需付费(恒 false)' }, + }, + required: ['model_show', 'need_pay'], + }, + }, + required: ['variants'], + }, + }, params: { model: f.string().default(''), }, @@ -1058,6 +1287,16 @@ export const actions = [ name: 'get_group_at_all_remain', summary: '获取群 @全体成员 剩余次数', readOnly: true, + returns: '{ can_at_all, remain_at_all_count_for_group, remain_at_all_count_for_uin }:@全体可用性与剩余次数。', + returnsSchema: { + type: 'object', + properties: { + can_at_all: { type: 'boolean', description: '当前是否可 @全体成员' }, + remain_at_all_count_for_group: { type: 'integer', description: '本群今日剩余 @全体次数' }, + remain_at_all_count_for_uin: { type: 'integer', description: '本账号今日剩余 @全体次数' }, + }, + required: ['can_at_all', 'remain_at_all_count_for_group', 'remain_at_all_count_for_uin'], + }, run: async (p, ctx) => { try { const data = await ctx.bridge.apis.groupAdmin.getAtAllRemain(p.group_id); @@ -1087,6 +1326,16 @@ export const actions = [ name: 'get_clientkey', summary: '获取 clientkey', readOnly: true, + returns: '{ clientKey, expireTime, keyIndex }:clientkey 及其过期时间与索引。', + returnsSchema: { + type: 'object', + properties: { + clientKey: { type: 'string', description: 'clientkey' }, + expireTime: { type: 'string', description: '过期时间' }, + keyIndex: { type: 'string', description: 'key 索引' }, + }, + required: ['clientKey', 'expireTime', 'keyIndex'], + }, params: {}, run: async (_p, ctx) => { const clientKeyInfo = await ctx.bridge.apis.web.forceFetchClientKey(); @@ -1109,6 +1358,14 @@ export const actions = [ name: 'share_peer', summary: '分享用户/群 Ark 卡片', readOnly: true, + returns: '{ arkMsg }:服务端生成的推荐联系人 Ark 卡片 JSON 字符串。', + returnsSchema: { + type: 'object', + properties: { + arkMsg: { type: 'string', description: 'Ark 卡片 JSON 字符串' }, + }, + required: ['arkMsg'], + }, params: { user_id: f.uint().optional(), group_id: f.uint().optional(), @@ -1132,6 +1389,14 @@ export const actions = [ name: 'send_ark_share', summary: '分享用户/群 Ark 卡片(NapCat 标准名)', readOnly: true, + returns: '{ arkMsg }:服务端生成的推荐联系人 Ark 卡片 JSON 字符串。', + returnsSchema: { + type: 'object', + properties: { + arkMsg: { type: 'string', description: 'Ark 卡片 JSON 字符串' }, + }, + required: ['arkMsg'], + }, params: { user_id: f.uint().optional(), group_id: f.uint().optional(), @@ -1160,6 +1425,8 @@ export const actions = [ name: 'share_group_ex', summary: '分享群 Ark 卡片', readOnly: true, + returns: '服务端生成的群推荐 Ark 卡片 JSON 字符串。', + returnsSchema: { type: 'string', description: '群 Ark 卡片 JSON 字符串' }, params: { group_id: f.uint() }, run: async (p, ctx) => { try { @@ -1173,6 +1440,8 @@ export const actions = [ name: 'send_group_ark_share', summary: '分享群 Ark 卡片(NapCat 标准名)', readOnly: true, + returns: '服务端生成的群推荐 Ark 卡片 JSON 字符串。', + returnsSchema: { type: 'string', description: '群 Ark 卡片 JSON 字符串' }, params: { group_id: f.uint() }, run: async (p, ctx) => { try { @@ -1189,6 +1458,21 @@ export const actions = [ name: 'get_doubt_friends_add_request', summary: '获取可疑好友申请', readOnly: true, + returns: '可疑好友申请数组,每项含 uid(作为处理用 flag)、昵称、来源、留言与申请时间。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + uid: { type: 'string', description: '申请人 uid(回传作 set_doubt_friends_add_request 的 flag)' }, + nick: { type: 'string', description: '申请人昵称' }, + source: { type: 'string', description: '申请来源' }, + msg: { type: 'string', description: '验证留言' }, + reqTime: { type: 'integer', description: '申请时间戳' }, + }, + required: ['uid', 'nick', 'source', 'msg', 'reqTime'], + }, + }, params: { count: f.int({ min: 0 }).default(50) }, run: async (p, ctx) => { try { @@ -1251,6 +1535,8 @@ export const actions = [ name: 'get_collection_list', summary: '获取收藏列表(占位)', readOnly: true, + returns: '占位实现,恒返回空数组。', + returnsSchema: { type: 'array', description: '收藏列表(占位,恒空)' }, params: {}, run: async () => { return okResponse([]); @@ -1391,6 +1677,8 @@ export const actions = [ name: 'nc_get_packet_status', summary: '获取 packet 状态(占位)', readOnly: true, + returns: '占位实现,恒返回 null。', + returnsSchema: { type: 'null', description: 'packet 状态(占位,恒 null)' }, params: {}, run: async () => { return okResponse(null); @@ -1415,6 +1703,15 @@ export const actions = [ name: 'nc_get_user_status', summary: '获取用户在线/扩展状态', readOnly: true, + returns: '{ status, ext_status }:用户在线状态码与扩展状态码。', + returnsSchema: { + type: 'object', + properties: { + status: { type: 'integer', description: '在线状态码' }, + ext_status: { type: 'integer', description: '扩展状态码' }, + }, + required: ['status', 'ext_status'], + }, params: { user_id: f.uint() }, run: async (p, ctx) => { const status = await ctx.bridge.apis.extras.getStrangerStatus(p.user_id); @@ -1428,6 +1725,30 @@ export const actions = [ name: 'get_ai_characters', summary: '获取 AI 语音角色', readOnly: true, + returns: '按分类分组的 AI 语音角色列表,每组含分类名与角色(id、名称、试听 URL)。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + type: { type: 'string', description: '角色分类名' }, + characters: { + type: 'array', + description: '该分类下的角色列表', + items: { + type: 'object', + properties: { + character_id: { type: 'string', description: '角色 ID' }, + character_name: { type: 'string', description: '角色显示名' }, + preview_url: { type: 'string', description: '试听音频 URL' }, + }, + required: ['character_id', 'character_name', 'preview_url'], + }, + }, + }, + required: ['type', 'characters'], + }, + }, params: { chat_type: f.int({ min: 0 }).default(1) }, run: async (p, ctx) => { try { @@ -1535,6 +1856,17 @@ export const actions = [ name: 'get_rkey_server', summary: '获取 rkey 服务器信息', readOnly: true, + returns: '{ expired_time, name, private_rkey?, group_rkey? }:rkey 过期时间与(存在时的)私聊/群聊 rkey。', + returnsSchema: { + type: 'object', + properties: { + expired_time: { type: 'integer', description: '过期时间戳(秒)' }, + name: { type: 'string', description: '服务器名(恒 SnowLuma)' }, + private_rkey: { type: 'string', description: '私聊 rkey(存在时返回)' }, + group_rkey: { type: 'string', description: '群聊 rkey(存在时返回)' }, + }, + required: ['expired_time', 'name'], + }, params: {}, run: async (_p, ctx) => { if (!ctx.getDownloadRKeys) return failedResponse(RETCODE.ACTION_FAILED, 'not implemented'); @@ -1570,6 +1902,38 @@ export const actions = [ name: ['ocr_image', '.ocr_image'], summary: 'OCR 图片(服务端,需图片 URL 或已缓存的图片 file_id)', readOnly: true, + returns: '{ texts, language }:识别文本数组(含置信度与坐标)与识别语言。', + returnsSchema: { + type: 'object', + properties: { + texts: { + type: 'array', + description: '识别出的文本块', + items: { + type: 'object', + properties: { + text: { type: 'string', description: '文本内容' }, + confidence: { type: 'number', description: '置信度' }, + coordinates: { + type: 'array', + description: '文本框顶点坐标', + items: { + type: 'object', + properties: { + x: { type: 'number', description: 'X 坐标' }, + y: { type: 'number', description: 'Y 坐标' }, + }, + required: ['x', 'y'], + }, + }, + }, + required: ['text', 'confidence', 'coordinates'], + }, + }, + language: { type: 'string', description: '识别语言' }, + }, + required: ['texts', 'language'], + }, params: { image: f.string({ allowEmpty: false }) }, run: async (p, ctx) => { // A passed-in http(s) URL is used verbatim (NOT re-signed) — if it is a @@ -1671,7 +2035,14 @@ export const actions = [ name: 'get_forward_msg', summary: '获取合并转发消息(id 或 message_id)', readOnly: true, - returns: '{ messages }', + returns: '{ messages }:转发内的消息节点数组(每项为 OneBot 消息事件,内部字段不固定)。', + returnsSchema: { + type: 'object', + properties: { + messages: { type: 'array', description: '转发消息节点数组', items: { type: 'object' } }, + }, + required: ['messages'], + }, params: { id: f.string().optional() }, run: async (p, ctx, raw) => { let id = p.id || ''; @@ -1736,7 +2107,14 @@ export const actions = [ name: 'translate_en2zh', summary: '英译中', readOnly: true, - returns: '{ words }', + returns: '{ words }:与输入等长的中文译文字符串数组。', + returnsSchema: { + type: 'object', + properties: { + words: { type: 'array', description: '译文数组', items: { type: 'string' } }, + }, + required: ['words'], + }, params: { words: f.raw() }, run: async (p, ctx) => { const rawWords = p.words; @@ -2053,7 +2431,14 @@ export const actions = [ name: 'get_fileset_id', summary: '从分享码/链接获取 fileset_id', readOnly: true, - returns: '{ fileset_id }', + returns: '{ fileset_id }:解析出的文件集 ID。', + returnsSchema: { + type: 'object', + properties: { + fileset_id: { type: 'string', description: '文件集 ID' }, + }, + required: ['fileset_id'], + }, params: { share_code: f.string({ allowEmpty: false }) }, run: async (p, ctx) => { try { diff --git a/packages/onebot/src/actions/friend.ts b/packages/onebot/src/actions/friend.ts index 93189af2..cbf878ff 100644 --- a/packages/onebot/src/actions/friend.ts +++ b/packages/onebot/src/actions/friend.ts @@ -7,6 +7,19 @@ export const actions = [ name: 'get_friend_list', summary: '获取好友列表', readOnly: true, + returns: '好友列表数组,每项含 QQ 号、昵称与备注。', + returnsSchema: { + type: 'array', + items: { + type: 'object', + properties: { + user_id: { type: 'integer', description: '好友 QQ 号' }, + nickname: { type: 'string', description: '好友昵称' }, + remark: { type: 'string', description: '好友备注' }, + }, + required: ['user_id', 'nickname', 'remark'], + }, + }, params: {}, run: async (_p, ctx) => { if (ctx.getFriendList) { @@ -20,6 +33,19 @@ export const actions = [ name: 'get_stranger_info', summary: '获取陌生人信息', readOnly: true, + returns: '陌生人资料:QQ 号、昵称、性别、年龄,命中资料时另含等级。', + returnsSchema: { + type: 'object', + properties: { + user_id: { type: 'integer', description: 'QQ 号' }, + nickname: { type: 'string', description: '昵称' }, + sex: { type: 'string', description: '性别(male/female/unknown)' }, + age: { type: 'integer', description: '年龄' }, + qq_level: { type: 'integer', description: 'QQ 等级(仅查到资料时返回)' }, + level: { type: 'integer', description: 'QQ 等级,同 qq_level(仅查到资料时返回)' }, + }, + required: ['user_id', 'nickname', 'sex', 'age'], + }, params: { user_id: f.uint().describe('QQ 号') }, run: async (p, ctx) => { const userId = p.user_id; diff --git a/packages/onebot/src/actions/group-album.ts b/packages/onebot/src/actions/group-album.ts index 5fd1a83a..df022179 100644 --- a/packages/onebot/src/actions/group-album.ts +++ b/packages/onebot/src/actions/group-album.ts @@ -7,6 +7,21 @@ export const actions = [ groupAction({ name: 'get_group_album_list', readOnly: true, + returns: '群相册列表数组,每项为一个相册的基本信息。', + returnsSchema: { + type: 'array', + description: '群相册列表', + items: { + type: 'object', + properties: { + id: { type: 'string', description: '相册 id' }, + name: { type: 'string', description: '相册名称' }, + picNum: { type: 'integer', description: '相册内照片数量' }, + createTime: { type: 'integer', description: '相册创建时间(unix 秒)' }, + }, + required: ['id', 'name', 'picNum', 'createTime'], + }, + }, run: async (p, ctx) => { try { const albumList = await ctx.bridge.apis.groupAlbum.list(p.group_id); @@ -28,6 +43,29 @@ export const actions = [ groupAction({ name: 'get_qun_album_list', readOnly: true, + returns: 'NapCat 风格的相册列表封套:{album_list, attach_info, has_more}(本实现 attach_info 恒为空串、has_more 恒为 false)。', + returnsSchema: { + type: 'object', + properties: { + album_list: { + type: 'array', + description: '相册列表', + items: { + type: 'object', + properties: { + album_id: { type: 'string', description: '相册 id' }, + album_name: { type: 'string', description: '相册名称' }, + create_time: { type: 'integer', description: '相册创建时间(unix 秒)' }, + pic_num: { type: 'integer', description: '相册内照片数量' }, + }, + required: ['album_id', 'album_name', 'create_time', 'pic_num'], + }, + }, + attach_info: { type: 'string', description: '分页游标(本 web 实现一次取满,恒为空串)' }, + has_more: { type: 'boolean', description: '是否还有更多(本 web 实现恒为 false)' }, + }, + required: ['album_list', 'attach_info', 'has_more'], + }, run: async (p, ctx) => { try { const albumList = await ctx.bridge.apis.groupAlbum.list(p.group_id); @@ -69,6 +107,19 @@ export const actions = [ groupAction({ name: 'get_group_album_media_list', readOnly: true, + returns: '相册媒体列表及下一页分页游标:{mediaList, nextAttachInfo}。', + returnsSchema: { + type: 'object', + properties: { + mediaList: { + type: 'array', + description: '相册媒体项列表(各项字段不固定)', + items: { type: 'object' }, + }, + nextAttachInfo: { type: 'string', description: '下一页分页游标(空串表示无更多)' }, + }, + required: ['mediaList', 'nextAttachInfo'], + }, params: { album_id: f.string({ allowEmpty: false }), attach_info: f.string().default(''), diff --git a/packages/onebot/src/actions/group-file.ts b/packages/onebot/src/actions/group-file.ts index afa92a6a..fab90184 100644 --- a/packages/onebot/src/actions/group-file.ts +++ b/packages/onebot/src/actions/group-file.ts @@ -59,7 +59,12 @@ export const actions = [ name: 'get_group_file_url', summary: '获取群文件下载链接', readOnly: true, - returns: '{ url: string }', + returns: '群文件下载链接。', + returnsSchema: { + type: 'object', + properties: { url: { type: 'string', description: '文件下载直链' } }, + required: ['url'], + }, // busid is accepted but tolerant (see busidOr102): NapCat/LLBot ignore it, // so a present null/empty/non-numeric value must not 400 the request (#147). params: { file_id: f.string({ allowEmpty: false }), busid: f.raw() }, @@ -72,6 +77,49 @@ export const actions = [ name: 'get_group_root_files', summary: '获取群根目录文件列表', readOnly: true, + returns: '群文件系统信息(文件与文件夹列表)。', + returnsSchema: { + type: 'object', + properties: { + files: { + type: 'array', + description: '文件列表', + items: { + type: 'object', + properties: { + group_id: { type: 'integer', description: '群号' }, + file_id: { type: 'string', description: '文件 ID' }, + file_name: { type: 'string', description: '文件名' }, + busid: { type: 'integer', description: '业务 ID' }, + file_size: { type: 'integer', description: '文件大小(字节)' }, + upload_time: { type: 'integer', description: '上传时间戳' }, + dead_time: { type: 'integer', description: '过期时间戳' }, + modify_time: { type: 'integer', description: '修改时间戳' }, + download_times: { type: 'integer', description: '下载次数' }, + uploader: { type: 'integer', description: '上传者 QQ 号' }, + uploader_name: { type: 'string', description: '上传者昵称' }, + }, + }, + }, + folders: { + type: 'array', + description: '文件夹列表', + items: { + type: 'object', + properties: { + group_id: { type: 'integer', description: '群号' }, + folder_id: { type: 'string', description: '文件夹 ID' }, + folder_name: { type: 'string', description: '文件夹名' }, + create_time: { type: 'integer', description: '创建时间戳' }, + creator: { type: 'integer', description: '创建者 QQ 号' }, + create_name: { type: 'string', description: '创建者昵称' }, + total_file_count: { type: 'integer', description: '文件夹内文件总数' }, + }, + }, + }, + }, + required: ['files', 'folders'], + }, run: async (p, ctx) => { return okResponse(await ctx.getGroupFiles(p.group_id, '/')); }, @@ -81,6 +129,49 @@ export const actions = [ name: 'get_group_files_by_folder', summary: '获取群子目录文件列表', readOnly: true, + returns: '群文件系统信息(文件与文件夹列表)。', + returnsSchema: { + type: 'object', + properties: { + files: { + type: 'array', + description: '文件列表', + items: { + type: 'object', + properties: { + group_id: { type: 'integer', description: '群号' }, + file_id: { type: 'string', description: '文件 ID' }, + file_name: { type: 'string', description: '文件名' }, + busid: { type: 'integer', description: '业务 ID' }, + file_size: { type: 'integer', description: '文件大小(字节)' }, + upload_time: { type: 'integer', description: '上传时间戳' }, + dead_time: { type: 'integer', description: '过期时间戳' }, + modify_time: { type: 'integer', description: '修改时间戳' }, + download_times: { type: 'integer', description: '下载次数' }, + uploader: { type: 'integer', description: '上传者 QQ 号' }, + uploader_name: { type: 'string', description: '上传者昵称' }, + }, + }, + }, + folders: { + type: 'array', + description: '文件夹列表', + items: { + type: 'object', + properties: { + group_id: { type: 'integer', description: '群号' }, + folder_id: { type: 'string', description: '文件夹 ID' }, + folder_name: { type: 'string', description: '文件夹名' }, + create_time: { type: 'integer', description: '创建时间戳' }, + creator: { type: 'integer', description: '创建者 QQ 号' }, + create_name: { type: 'string', description: '创建者昵称' }, + total_file_count: { type: 'integer', description: '文件夹内文件总数' }, + }, + }, + }, + }, + required: ['files', 'folders'], + }, // folder_id / folder are aliases; first non-empty wins, else '/'. params: { folder_id: f.string().default(''), folder: f.string().default('') }, run: async (p, ctx) => { @@ -171,7 +262,12 @@ export const actions = [ name: 'get_private_file_url', summary: '获取私聊文件下载链接', readOnly: true, - returns: '{ url: string }', + returns: '私聊文件下载链接。', + returnsSchema: { + type: 'object', + properties: { url: { type: 'string', description: '文件下载直链' } }, + required: ['url'], + }, // NapCat's `get_private_file_url` requires only file_id — it re-derives the // file hash by decoding its composite file_id and reading file10MMd5 off the // original message. SnowLuma's file_id is the bare fileUUID, so it relies on diff --git a/packages/onebot/src/actions/message.ts b/packages/onebot/src/actions/message.ts index 6f816794..eedf7b48 100644 --- a/packages/onebot/src/actions/message.ts +++ b/packages/onebot/src/actions/message.ts @@ -89,6 +89,7 @@ export const actions = [ name: 'get_msg', summary: '获取消息', readOnly: true, + returns: '消息事件对象(首次收到时存储的副本,已去除 post_type/self_id、附带 real_id 字段并刷新图片 URL)。', params: { message_id: f.messageId() }, run: async (p, ctx) => { const data = ctx.getMessage(p.message_id); diff --git a/packages/onebot/src/actions/qzone.ts b/packages/onebot/src/actions/qzone.ts index a9d329e6..92b77812 100644 --- a/packages/onebot/src/actions/qzone.ts +++ b/packages/onebot/src/actions/qzone.ts @@ -10,6 +10,30 @@ export const actions = [ defineAction({ name: 'get_qzone_msg_list', readOnly: true, + returns: '说说列表对象,含说说总数与本页说说数组。', + returnsSchema: { + type: 'object', + properties: { + total: { type: 'integer', description: '账号说说总数(非本页数量)' }, + msglist: { + type: 'array', + description: '本页说说数组', + items: { + type: 'object', + properties: { + tid: { type: 'string', description: '说说 id(delete/comment/like 的句柄)' }, + content: { type: 'string', description: '说说正文' }, + time: { type: 'integer', description: '发表时间(unix 秒)' }, + comment_num: { type: 'integer', description: '评论数' }, + is_private: { type: 'boolean', description: '是否仅自己可见' }, + images: { type: 'array', items: { type: 'string' }, description: '图片 URL 列表(每图取最大可用变体)' }, + }, + required: ['tid', 'content', 'time', 'comment_num', 'is_private', 'images'], + }, + }, + }, + required: ['total', 'msglist'], + }, summary: '获取 QQ 空间说说列表(默认机器人自己的空间)', params: { target_uin: f.uint().describe('目标 QQ 号,省略则取机器人自己').optional(), @@ -32,6 +56,30 @@ export const actions = [ defineAction({ name: 'get_qzone_feeds', readOnly: true, + returns: '好友动态对象,含本页 feed 数组与是否有更多页。', + returnsSchema: { + type: 'object', + properties: { + feeds: { + type: 'array', + description: '本页好友动态数组', + items: { + type: 'object', + properties: { + uin: { type: 'integer', description: '动态作者 QQ 号' }, + nickname: { type: 'string', description: '作者昵称' }, + time: { type: 'integer', description: '发表时间(unix 秒)' }, + appid: { type: 'integer', description: 'Qzone 应用 id(311=说说,4=相册,…)' }, + key: { type: 'string', description: 'feed 句柄(Qzone 用于定位该条动态)' }, + html: { type: 'string', description: '预渲染 HTML 原样透传' }, + }, + required: ['uin', 'nickname', 'time', 'appid', 'key', 'html'], + }, + }, + has_more: { type: 'boolean', description: '服务端是否报告本页之后还有更多页' }, + }, + required: ['feeds', 'has_more'], + }, summary: '获取 QQ 空间好友动态(feed);page_num 仅首页可靠,深翻页需时间游标(暂未实现)', params: { page_num: f.int({ min: 1 }).describe('页码(1 起;仅首页可靠)').default(1),