NcatBot 文档

外观

查询与文件操作 API 详解

约 1480 字大约 5 分钟

2026-03-19

QQQuery 信息查询（40+ 方法）+ QQFile 文件操作的完整参数表、返回值和示例。

信息查询（QQQuery）

通过 api.qq.query.xxx() 调用。源码：ncatbot/api/qq/query.py。

基础查询

get_login_info()

async def get_login_info(self) -> LoginInfo:

返回值：LoginInfo — 包含 user_id: str 和 nickname: str

info = await api.qq.query.get_login_info()
print(f"Bot QQ: {info.user_id}")

get_stranger_info()

async def get_stranger_info(self, user_id: Union[str, int]) -> StrangerInfo:
参数类型必填说明
user_idstr | int是目标用户 QQ 号

返回值：StrangerInfo — 用户信息（user_id, nickname, sex, age 等）

get_friend_list()

async def get_friend_list(self) -> List[FriendInfo]:

返回值：List[FriendInfo] — 好友列表，每项包含 user_id, nickname, remark

get_group_info()

async def get_group_info(self, group_id: Union[str, int]) -> GroupInfo:

返回值：GroupInfo — 群信息（group_id, group_name, member_count 等）

get_group_list()

async def get_group_list(self) -> List[GroupInfo]:

返回值：List[GroupInfo] — 群列表

groups = await api.qq.query.get_group_list()
for g in groups:
    print(g.group_name)

get_group_member_info()

async def get_group_member_info(
    self, group_id: Union[str, int], user_id: Union[str, int],
) -> GroupMemberInfo:

返回值：GroupMemberInfo — 群成员信息（group_id, user_id, nickname, card, role 等）

get_group_member_list()

async def get_group_member_list(self, group_id: Union[str, int]) -> List[GroupMemberInfo]:

返回值：List[GroupMemberInfo] — 群成员列表

get_msg()

async def get_msg(self, message_id: Union[str, int]) -> MessageData:

返回值：MessageData — 消息详情（message_id, real_id, sender, time, message 等）

get_forward_msg()

async def get_forward_msg(self, message_id: Union[str, int]) -> ForwardMessageData:

返回值：ForwardMessageData — 合并转发消息内容

群扩展查询

get_group_notice()

async def get_group_notice(self, group_id: Union[str, int]) -> List[GroupNotice]:

获取群公告列表。

get_essence_msg_list()

async def get_essence_msg_list(self, group_id: Union[str, int]) -> List[EssenceMessage]:

获取群精华消息列表。

get_group_honor_info()

async def get_group_honor_info(
    self, group_id: Union[str, int], type: str = "all",
) -> GroupHonorInfo:

获取群荣誉信息。type 可选 "talkative", "performer", "legend", "strong_newbie", "emotion", "all"。

get_group_at_all_remain()

async def get_group_at_all_remain(self, group_id: Union[str, int]) -> GroupAtAllRemain:

获取群 @全体成员 剩余次数。

get_group_shut_list()

async def get_group_shut_list(self, group_id: Union[str, int]) -> List[GroupShutInfo]:

获取群禁言列表。

get_group_system_msg()

async def get_group_system_msg(self) -> GroupSystemMsg:

获取群系统消息（加群请求/邀请等）。

get_group_info_ex()

async def get_group_info_ex(self, group_id: Union[str, int]) -> GroupInfoEx:

获取群扩展信息。

文件查询

get_group_root_files()

async def get_group_root_files(self, group_id: Union[str, int]) -> GroupFileList:

获取群根目录文件列表。

get_group_file_url()

async def get_group_file_url(
    self, group_id: Union[str, int], file_id: str,
) -> str:

获取群文件下载 URL。

url = await api.qq.query.get_group_file_url(123456, "file_abc123")

get_group_file_system_info()

async def get_group_file_system_info(self, group_id: Union[str, int]) -> GroupFileSystemInfo:

获取群文件系统信息（文件数/容量等）。

get_group_files_by_folder()

async def get_group_files_by_folder(
    self, group_id: Union[str, int], folder_id: str,
) -> GroupFileList:

获取指定文件夹中的文件列表。

get_private_file_url()

async def get_private_file_url(self, user_id: Union[str, int], file_id: str) -> str:

获取私聊文件下载 URL。

get_file()

async def get_file(self, file_id: str) -> FileData:

获取文件信息。

表情回应查询

fetch_emoji_like()

async def fetch_emoji_like(
    self, message_id: Union[str, int], emoji_id: str,
    emoji_type: str = "1", count: int = 20, cookie: str = "",
) -> EmojiLikeInfo:

获取消息的表情回应详情。

get_emoji_likes()

async def get_emoji_likes(
    self, message_id: Union[str, int], emoji_id: str = "", count: int = 0,
) -> EmojiLikesResult:

获取消息的表情回应汇总。

系统信息

get_version_info()

async def get_version_info(self) -> VersionInfo:

获取 NapCat 版本信息。

get_status()

async def get_status(self) -> BotStatus:

获取 Bot 在线状态。

get_recent_contact()

async def get_recent_contact(self, count: int = 10) -> List[RecentContact]:

获取最近联系人列表。

ocr_image()

async def ocr_image(self, image: str) -> OcrResult:

OCR 图片识别。

get_user_avatar()

async def get_user_avatar(
    self,
    user_id: Union[str, int],
    spec: Literal[40, 100, 640] = 640,
) -> ImageAttachment:

获取 QQ 用户头像，返回 ImageAttachment。通过 QQ 头像公开接口构造下载链接，无需经过 NapCat 服务。

参数类型必填说明
user_idstr | int是目标用户 QQ 号
spec40 | 100 | 640否头像尺寸（像素），默认 640

返回值：ImageAttachment — 可直接 download() / as_bytes() / to_segment()

avatar = await api.qq.query.get_user_avatar(event.user_id)
# 下载到本地
await avatar.download("/tmp/avatars")
# 转为消息段发送
await api.qq.send_group_image(group_id, avatar.url)

文件操作（QQFile）

通过 api.qq.file.xxx() 调用。源码：ncatbot/api/qq/file.py。

upload_group_file()

async def upload_group_file(
    self, group_id: Union[str, int], file: Union[str, Attachment],
    name: str = "", folder_id: str = "",
) -> None:

上传群文件。file 可以是本地路径字符串，也可以直接传入 Attachment 对象（自动下载并上传）。

参数类型必填说明
group_idstr | int是群号
filestr | Attachment是本地文件路径、URL，或 Attachment 对象
namestr否上传后的文件名（传 Attachment 时自动取 att.name）
folder_idstr否目标文件夹 ID，默认为根目录
# 传统 str 用法
await api.qq.file.upload_group_file(123456, "/tmp/report.pdf", "月报.pdf")

# 直接传 Attachment 对象
await api.qq.file.upload_group_file(123456, attachment, folder_id=folder_id)

delete_group_file()

async def delete_group_file(
    self, group_id: Union[str, int], file_id: str,
) -> None:

删除群文件。

create_group_file_folder()

async def create_group_file_folder(
    self, group_id: Union[str, int], name: str, parent_id: str = "",
) -> CreateFolderResult:

创建群文件夹。

delete_group_folder()

async def delete_group_folder(
    self, group_id: Union[str, int], folder_id: str,
) -> None:

删除群文件夹。

get_or_create_group_folder()

async def get_or_create_group_folder(
    self, group_id: Union[str, int], folder_name: str, parent_id: str = "",
) -> str:

查找群文件夹，不存在则自动创建，返回 folder_id。这是一个 sugar 方法，组合了 get_group_root_files / get_group_files_by_folder + create_group_file_folder。

参数类型必填说明
group_idstr | int是群号
folder_namestr是文件夹名称，或 "parent/child" 路径格式
parent_idstr否父文件夹 ID，为空表示根目录

返回值：str — 文件夹 ID；失败返回空字符串。

支持路径格式 "parent/child" 自动拆分为两级查找/创建（仅限一级子目录）。当同时提供 parent_id 和含 / 的 folder_name 时，以 parent_id 优先。

# 根目录查找或创建
folder_id = await api.qq.file.get_or_create_group_folder(123456, "备份")

# 在指定父文件夹下查找或创建
child_id = await api.qq.file.get_or_create_group_folder(
    123456, "daily", parent_id=folder_id
)

# 路径格式：自动创建两级目录
folder_id = await api.qq.file.get_or_create_group_folder(123456, "备份/daily")

upload_private_file()

async def upload_private_file(
    self, user_id: Union[str, int], file: Union[str, Attachment], name: str = "",
) -> None:

上传私聊文件。file 同样支持 str 或 Attachment。

upload_attachment()

async def upload_attachment(
    self, target_id: Union[str, int], attachment: Attachment, *,
    target_type: str = "group", folder_id: str = "", folder: str = "",
) -> None:

一步上传 Attachment 对象到 QQ 群/私聊。自动处理下载→上传→清理临时文件的全部流程。

这是 QQFile 平台专属 sugar，不属于跨平台 IFileTransfer 协议。

参数类型必填说明
target_idstr | int是群号或用户 ID
attachmentAttachment是Attachment 实例
target_typestr否"group"（默认）或 "private"
folder_idstr否群文件夹 ID（仅 group）
folderstr否群文件夹名称（仅 group），自动查找/创建
# 从 GitHub Release 获取附件并上传到群文件
await api.qq.file.upload_attachment(
    group_id, attachment, folder="ncatbot-ref"
)

# 上传到私聊
await api.qq.file.upload_attachment(
    user_id, attachment, target_type="private"
)

download_file()

async def download_file(
    self, url: str = "", file: str = "", headers: str = "",
) -> DownloadResult:

下载文件到本地。url 或 file 至少指定一个。

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot