ExtensionApi

NapCat 扩展功能模块，涵盖戳一戳、AI 语音、自定义表情、收藏、频道等 NapCat 特有的扩展 API。

方法

交互扩展

方法	返回类型	说明
friendPoke(userId: number)	Result<void>	私聊戳一戳
groupPoke(groupId: number, userId: number)	Result<void>	群聊戳一戳
setMsgEmojiLike(messageId: number, emojiId: string)	Result<void>	设置消息表情回应
setOnlineStatus(status: number, extStatus: number, batteryStatus?: number)	Result<void>	设置在线状态
setInputStatus(userId: number, eventType: number)	Result<void>	设置输入状态
markAllAsRead()	Result<void>	标记所有消息已读

AI 语音

方法	返回类型	说明
getAiCharacters(groupId: number, chatType?: number)	Result<AiCharacter[]>	获取 AI 语音角色列表
getAiRecord(character: string, text: string, groupId?: number)	Result<{ url: string }>	获取 AI 语音
sendGroupAiRecord(groupId: number, character: string, text: string)	Result<void>	群聊发送 AI 语音

表情与收藏

方法	返回类型	说明
createCollection(rawData: string, brief: string)	Result<void>	创建收藏
getCollectionList(category?: string, count?: number)	Result<CollectionItem[]>	获取收藏列表
fetchCustomFace(count?: number)	Result<unknown>	获取收藏表情
addCustomFace(file: string, params?: AddCustomFaceParams)	Result<void>	添加自定义表情
deleteCustomFace(params?: DeleteCustomFaceParams)	Result<void>	删除自定义表情
fetchCustomFaceDetail(count?: number)	Result<unknown>	获取自定义表情详情
setCustomFaceDesc(emojiId: string, resId: string, md5: string, desc: string)	Result<void>	修改自定义表情描述
getEmojiLikes(groupId: number, messageId: string, emojiId: string, count: number, emojiType?: number)	Result<unknown>	获取消息表情点赞列表

消息转发

方法	返回类型	说明
forwardGroupSingleMsg(groupId: number, messageId: string)	Result<void>	转发单条消息到群聊
sendFlashMsg(filesetId: string, userId?: number, groupId?: number)	Result<void>	发送闪传消息
fetchPttText(messageId: string)	Result<{ text: string }>	获取语音转文字结果

Ark 分享

方法	返回类型	说明
arkSharePeer(phoneNumber: string, userId?: number, groupId?: number)	Result<void>	推荐联系人/群聊（Ark 分享）
arkShareGroup(groupId: number)	Result<void>	推荐群聊（Ark 分享）
sendArkShare(phoneNumber: string, userId?: number, groupId?: number)	Result<void>	分享用户（Ark 新接口）
sendGroupArkShare(groupId: number)	Result<void>	分享群（Ark 新接口）
getMiniAppArk(params: Record<string, unknown>)	Result<{ data: string }>	获取小程序 Ark 签名
translateEn2Zh(words: string[])	Result<string[]>	英译中翻译

安全与密钥

方法	返回类型	说明
getRkey()	Result<RkeyInfo[]>	获取 Rkey（NapCat 扩展接口）
getRkeyV2()	Result<RkeyInfo[]>	获取扩展 RKey
getRkeyServer()	Result<unknown>	获取 RKey 服务器
sendPacket(cmd: string, data: string, rsp?: string)	Result<unknown>	发送原始数据包

频道

方法	返回类型	说明
getGuildList()	Result<unknown[]>	获取频道列表
getGuildServiceProfile()	Result<unknown>	获取频道个人信息

其他

方法	返回类型	说明
getGroupIgnoreAddRequest()	Result<unknown[]>	获取群忽略添加请求列表

返回数据结构

AiCharacter

interface AiCharacter {
  character_id: string
  character_name: string
  [key: string]: unknown
}

RkeyInfo

interface RkeyInfo {
  channel_type: number
  rkey: string
  ttl: number
  [key: string]: unknown
}

CollectionItem

type CollectionItem = Record<string, unknown>

AddCustomFaceParams

interface AddCustomFaceParams {
  emojiId?: string
  packageId?: string
  fileName?: string
  fileSize?: number
  md5?: string
  isMarkFace?: boolean
  isOrigin?: boolean
}

DeleteCustomFaceParams

interface DeleteCustomFaceParams {
  resId?: string
  id?: string
  ids?: string[]
  md5?: string
}

示例

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

const ext = new ExtensionApi(client)

// 群聊戳一戳
const pokeResult = await ext.groupPoke(123456789, 987654321)
if (pokeResult.ok) {
  console.log('戳一戳成功')
} else {
  console.error('戳一戳失败:', pokeResult.error.code, pokeResult.error.message)
}

// 获取 AI 语音角色
const chars = await ext.getAiCharacters(123456789)
if (chars.ok) {
  console.log('AI 角色:', chars.data)
}

// 翻译
const trans = await ext.translateEn2Zh(['hello', 'world'])
if (trans.ok) {
  console.log('翻译结果:', trans.data)
}

// 获取 AI 语音
const voice = await ext.getAiRecord('角色ID', '你好')
if (voice.ok) {
  console.log('语音 URL:', voice.data.url)
}

// 标记所有消息已读
await ext.markAllAsRead()