SystemApi

系统/账号相关 API 模块，涵盖登录信息、版本查询、资料设置、安全检测等。

方法

账号信息

方法	返回类型	说明
getLoginInfo()	Result<LoginInfo>	获取登录号信息
getVersionInfo()	Result<VersionInfo>	获取版本信息
getStatus()	Result<BotStatus>	获取运行状态
canSendImage()	Result<{ yes: boolean }>	检查是否可以发送图片
canSendRecord()	Result<{ yes: boolean }>	检查是否可以发送语音

陌生人信息

方法	返回类型	说明
getStrangerInfo(userId: number, noCache?: boolean)	Result<StrangerInfo>	获取陌生人信息

凭证与密钥

方法	返回类型	说明
getCookies(domain?: string)	Result<{ cookies: string }>	获取 Cookies
getCsrfToken()	Result<{ token: number }>	获取 CSRF Token
getCredentials(domain?: string)	Result<Credentials>	获取 QQ 相关接口凭证
getClientkey()	Result<ClientKey>	获取客户端密钥

缓存与文件

方法	返回类型	说明
cleanCache()	Result<void>	清理缓存
getImage(file: string)	Result<{ file: string }>	获取图片信息
getRecord(file?: string, outFormat?: string)	Result<{ file: string }>	获取语音信息
ocrImage(image: string)	Result<OcrResult>	图片 OCR 识别

资料设置

方法	返回类型	说明
setQQProfile(nickname: string, personalNote?: string, sex?: number | string)	Result<void>	设置登录号资料
setQQAvatar(file: string)	Result<void>	设置 QQ 头像
botExit()	Result<void>	退出机器人
setSelfLongnick(longNick: string)	Result<void>	设置个性签名
setDiyOnlineStatus(faceId: number | string, faceType: number | string, wording: string)	Result<void>	设置自定义在线状态

在线信息

方法	返回类型	说明
getModelShow()	Result<ModelShow>	获取在线机型（兼容 go-cqhttp）
setModelShow()	Result<void>	设置在线机型（兼容 go-cqhttp）
getOnlineClients()	Result<OnlineClient[]>	获取当前账号在线客户端列表

安全与检测

方法	返回类型	说明
checkUrlSafely(url: string)	Result<UrlSafety>	检查链接安全性
getRobotUinRange()	Result<RobotUinRange>	获取机器人 QQ 号区间
ncGetPacketStatus()	Result<PacketStatus>	获取 PacketServer 状态（NapCat 扩展）

好友请求管理

方法	返回类型	说明
getDoubtFriendsAddRequest(count?: number)	Result<unknown>	获取可疑好友添加请求
setDoubtFriendsAddRequest(flag: string, approve: boolean)	Result<void>	处理可疑好友添加请求

其他

方法	返回类型	说明
setRestart()	Result<void>	重启服务

返回数据结构

LoginInfo

interface LoginInfo {
  user_id: number
  nickname: string
}

VersionInfo

interface VersionInfo {
  app_name: string
  app_version: string
  protocol_version: string
  [key: string]: unknown
}

BotStatus

interface BotStatus {
  online?: boolean
  good: boolean
  [key: string]: unknown
}

StrangerInfo

interface StrangerInfo {
  user_id: number
  nickname: string
  sex?: string
  age?: number
  [key: string]: unknown
}

Credentials

interface Credentials {
  cookies: string
  csrf_token: number
  [key: string]: unknown
}

ClientKey

interface ClientKey {
  client_key: string
  [key: string]: unknown
}

OcrResult

interface OcrResult {
  texts: { text: string; confidence: number; coordinates: unknown[] }[]
  language: string
  [key: string]: unknown
}

ModelShow

interface ModelShow {
  model_show: string
  [key: string]: unknown
}

OnlineClient

interface OnlineClient {
  app_id: number
  device_name: string
  device_kind: string
  [key: string]: unknown
}

UrlSafety

interface UrlSafety {
  level: number
  [key: string]: unknown
}

RobotUinRange

interface RobotUinRange {
  min_uin: number
  max_uin: number
  [key: string]: unknown
}

PacketStatus

interface PacketStatus {
  online: boolean
  good: boolean
  [key: string]: unknown
}

示例

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

const system = new SystemApi(client)

// 获取版本信息
const ver = await system.getVersionInfo()
if (ver.ok) {
  console.log('NapCat 版本:', ver.data.app_version)
} else {
  console.error('获取版本失败:', ver.error.code, ver.error.message)
}

// 获取登录信息
const login = await system.getLoginInfo()
if (login.ok) {
  console.log('当前账号:', login.data.user_id, login.data.nickname)
}

// 图片 OCR 识别
const ocr = await system.ocrImage('/path/to/image.png')
if (ocr.ok) {
  ocr.data.texts.forEach((t) => console.log(t.text, `(置信度: ${t.confidence})`))
}

// 检查链接安全性
const safe = await system.checkUrlSafely('https://example.com')
if (safe.ok) {
  console.log('安全等级:', safe.data.level)
}

// 获取在线客户端列表
const clients = await system.getOnlineClients()
if (clients.ok) {
  clients.data.forEach((c) => console.log(c.device_name, c.device_kind))
}