API 参考

NapCat SDK 将 API 按功能域拆分为独立模块，每个模块封装一组相关操作。

模块总览

模块	职责
MessageApi	消息收发（私聊、群聊、合并转发）
GroupApi	群管理（禁言、踢人、群信息、群公告、群相册）
FriendApi	好友操作（列表、备注、请求处理）
FileApi	文件上传、下载、群文件管理
SystemApi	系统信息查询（版本、状态、登录信息）
ExtensionApi	NapCat 扩展功能（戳一戳、AI 语音、自定义表情等）

通用模式

所有 API 方法遵循统一模式：

import { MessageApi } from '@aemeath-projects/napcat'

const api = new MessageApi(client)

// 所有方法返回 Result<T>
const result = await api.sendPrivateMsg(userId, [Seg.text('hello')])

if (result.ok) {
  // result.data 包含返回值
  console.log(result.data.message_id)
} else {
  // result.error 包含错误信息
  console.error(result.error.code, result.error.message)
}

Result 类型

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: { code: number; message: string } }

事件类型

client.on() 可监听以下事件。事件名支持分层订阅（如 message.group）和顶层订阅（如 message）。

连接事件

事件名	回调参数	说明
connect	() => void	连接建立
close	() => void	连接断开
error	(error: Error) => void	连接错误
reconnecting	(attempt: number, delay: number) => void	正在重连

消息事件

事件名	回调参数	说明
message	(event: PrivateMessageEvent | GroupMessageEvent) => void	所有消息
message.private	(event: PrivateMessageEvent) => void	私聊消息
message.group	(event: GroupMessageEvent) => void	群消息
message_sent	(event: MessageSentEvent) => void	机器人自发消息（NapCat 扩展）

通知事件

事件名	回调参数	说明
notice	(event: AnyNoticeEvent) => void	所有通知
notice.group_increase	(event: GroupIncreaseNotice) => void	群成员增加
notice.group_decrease	(event: GroupDecreaseNotice) => void	群成员减少
notice.group_ban	(event: GroupBanNotice) => void	群禁言
notice.group_admin	(event: GroupAdminNotice) => void	群管理员变更
notice.group_upload	(event: GroupUploadNotice) => void	群文件上传
notice.group_recall	(event: GroupRecallNotice) => void	群消息撤回
notice.group_card	(event: GroupCardNotice) => void	群名片变更
notice.friend_add	(event: FriendAddNotice) => void	好友添加
notice.friend_recall	(event: FriendRecallNotice) => void	好友消息撤回
notice.essence	(event: EssenceNotice) => void	精华消息
notice.group_msg_emoji_like	(event: GroupMsgEmojiLikeNotice) => void	群消息表情回应
notice.notify	(event: NotifyEvent) => void	通知子事件（戳一戳、群名称变更等）
notice.bot_offline	(event: BotOfflineNotice) => void	机器人下线

请求事件

事件名	回调参数	说明
request	(event: FriendRequestEvent | GroupRequestEvent) => void	所有请求
request.friend	(event: FriendRequestEvent) => void	好友添加请求
request.group	(event: GroupRequestEvent) => void	加群请求/邀请

元事件

事件名	回调参数	说明
meta_event	(event: LifecycleEvent | HeartbeatEvent) => void	所有元事件
meta_event.lifecycle	(event: LifecycleEvent) => void	生命周期事件
meta_event.heartbeat	(event: HeartbeatEvent) => void	心跳事件

事件监听示例

client.on('message.group', async (event) => {
  console.log(`[群 ${event.group_id}] ${event.sender.nickname}: ${event.raw_message}`)
})

client.on('notice.friend_add', (event) => {
  console.log(`好友 ${event.user_id} 已添加`)
})

client.on('request.friend', (event) => {
  // 自动同意好友请求
  await friendApi.setFriendAddRequest(event.flag, true)
})