K2cr2O1
d458413e4b
- 新增 `/status` 指令，展示机器人运行状态和系统指标 - 实现Redis Lua脚本支持原子化计数器操作 - 添加消息收发统计功能 - 完善文档，包括插件开发和性能优化指南 - 重构WebSocket连接池，增加健康检查机制 - 移除旧版编译脚本，优化项目结构
9.6 KiB
9.6 KiB
账号 API
这一页讲的是怎么管理机器人自己的账号：查看登录信息、设置在线状态、修改资料、退出登录等等。这些都是跟机器人自身相关的操作。
账号信息
get_login_info - 获取登录信息
async def get_login_info(self, no_cache: bool = False) -> LoginInfo
获取当前登录的机器人账号信息。默认会缓存 1 小时。
参数：
no_cache: 是否跳过缓存，直接从服务器获取
返回值：
LoginInfo: 登录信息对象
示例：
info = await bot.get_login_info()
print(f"机器人QQ号: {info.user_id}")
print(f"机器人昵称: {info.nickname}")
LoginInfo 对象包含：
user_id: 机器人 QQ 号nickname: 机器人昵称
get_version_info - 获取版本信息
async def get_version_info(self) -> VersionInfo
获取 OneBot v11 实现的版本信息（比如 NapCatQQ 的版本）。
返回值：
VersionInfo: 版本信息对象
示例：
version = await bot.get_version_info()
print(f"客户端: {version.app_name}")
print(f"版本: {version.app_version}")
print(f"OneBot 协议版本: {version.protocol_version}")
VersionInfo 对象包含：
app_name: 客户端名称（如 "NapCatQQ"）app_version: 客户端版本protocol_version: 支持的 OneBot 协议版本
get_status - 获取运行状态
async def get_status(self) -> Status
获取 OneBot 实现的运行状态信息。
返回值：
Status: 状态信息对象
示例：
status = await bot.get_status()
print(f"在线: {status.online}")
print(f"状态: {status.status}")
print(f"正常: {status.good}")
Status 对象包含：
online: 是否在线status: 状态描述good: 运行是否正常
get_profile_like - 获取资料点赞信息
async def get_profile_like(self) -> Dict[str, Any]
获取个人资料的点赞信息。
返回值：
- 包含点赞信息的字典
nc_get_user_status - 获取用户在线状态 (NapCat)
async def nc_get_user_status(self, user_id: int) -> Dict[str, Any]
获取指定用户的在线状态（NapCatQQ 特有 API）。
参数：
user_id: 目标用户的 QQ 号
返回值：
- 包含用户状态信息的字典
状态设置
set_self_longnick - 设置个性签名
async def set_self_longnick(self, long_nick: str) -> Dict[str, Any]
设置机器人账号的个性签名（QQ 资料里的那个长签名）。
参数：
long_nick: 要设置的个性签名内容
示例：
@matcher.command("setsign")
async def handle_setsign(event: MessageEvent, args: str):
if not args:
await event.reply("需要签名内容")
return
await event.bot.set_self_longnick(args)
await event.reply("个性签名已更新")
set_online_status - 设置在线状态
async def set_online_status(self, status_code: int) -> Dict[str, Any]
设置机器人的在线状态（在线、离开、忙碌等）。
参数：
status_code: 状态码1: 在线2: 离开3: 忙碌4: 请勿打扰5: 隐身- 其他值取决于客户端支持
示例：
# 设置为隐身
await bot.set_online_status(5)
set_diy_online_status - 设置自定义在线状态
async def set_diy_online_status(
self,
face_id: int,
face_type: int,
wording: str
) -> Dict[str, Any]
设置自定义的在线状态（需要客户端支持）。
参数：
face_id: 状态表情 IDface_type: 状态表情类型wording: 状态描述文本
示例：
# 设置为"摸鱼中"
await bot.set_diy_online_status(
face_id=100,
face_type=1,
wording="摸鱼中"
)
set_input_status - 设置"正在输入"状态
async def set_input_status(
self,
user_id: int,
event_type: int
) -> Dict[str, Any]
向指定用户显示"对方正在输入..."的状态提示。
参数：
user_id: 目标用户的 QQ 号event_type: 事件类型（具体含义取决于客户端）
示例：
# 向某个用户显示"正在输入"
await bot.set_input_status(123456, 1)
资料修改
set_qq_profile - 设置个人资料
async def set_qq_profile(self, **kwargs) -> Dict[str, Any]
设置机器人账号的个人资料。
参数：
**kwargs: 个人资料的相关参数，具体字段请参考 OneBot v11 规范
示例：
# 修改昵称
await bot.set_qq_profile(nickname="新的昵称")
# 修改多个字段
await bot.set_qq_profile(
nickname="新昵称",
sex="female",
age=18,
level=50
)
set_qq_avatar - 设置头像
async def set_qq_avatar(self, **kwargs) -> Dict[str, Any]
设置机器人账号的头像。
参数：
**kwargs: 头像的相关参数，具体字段请参考 OneBot v11 规范
示例：
# 设置头像（具体参数格式取决于客户端）
await bot.set_qq_avatar(file="path/to/avatar.jpg")
系统操作
bot_exit - 退出登录
async def bot_exit(self) -> Dict[str, Any]
让机器人进程退出（需要客户端支持）。谨慎使用！
示例：
@matcher.command("shutdown", permission="admin")
async def handle_shutdown(event: MessageEvent):
await event.reply("机器人正在退出...")
await event.bot.bot_exit()
clean_cache - 清理缓存
async def clean_cache(self) -> Dict[str, Any]
清理 OneBot 客户端的缓存。
示例：
@matcher.command("clearcache", permission="admin")
async def handle_clearcache(event: MessageEvent):
await event.bot.clean_cache()
await event.reply("缓存已清理")
get_clientkey - 获取客户端密钥
async def get_clientkey(self) -> Dict[str, Any]
获取客户端密钥（通常用于 QQ 登录相关操作）。
返回值：
- 包含客户端密钥的字典
实用示例
机器人状态查询插件
@matcher.command("status")
async def handle_status(event: MessageEvent):
# 获取各种信息
login_info = await event.bot.get_login_info()
version_info = await event.bot.get_version_info()
status_info = await event.bot.get_status()
# 构建状态消息
msg = "🤖 机器人状态\n"
msg += f"QQ号: {login_info.user_id}\n"
msg += f"昵称: {login_info.nickname}\n"
msg += f"客户端: {version_info.app_name} v{version_info.app_version}\n"
msg += f"协议: OneBot v{version_info.protocol_version}\n"
msg += f"状态: {'在线' if status_info.online else '离线'}\n"
msg += f"运行: {'正常' if status_info.good else '异常'}"
await event.reply(msg)
自动切换状态
import asyncio
from datetime import datetime
async def auto_status_scheduler(bot):
"""
定时自动切换状态
"""
while True:
now = datetime.now().hour
if 9 <= now < 18:
# 工作时间：在线
await bot.set_online_status(1)
status_text = "工作中"
elif 18 <= now < 22:
# 晚上：离开
await bot.set_online_status(2)
status_text = "休息中"
else:
# 深夜：隐身
await bot.set_online_status(5)
status_text = "睡眠模式"
# 设置个性签名
await bot.set_self_longnick(f"当前状态: {status_text} | 最后更新: {datetime.now():%H:%M}")
# 每小时更新一次
await asyncio.sleep(3600)
# 在初始化插件时启动
# （注意：这只是一个示例，实际使用需要考虑插件生命周期）
资料备份与恢复
import json
@matcher.command("backupprofile", permission="admin")
async def handle_backup_profile(event: MessageEvent):
"""
备份当前资料到文件
"""
# 获取当前登录信息
login_info = await event.bot.get_login_info()
# 构建备份数据
backup_data = {
"user_id": login_info.user_id,
"nickname": login_info.nickname,
"backup_time": datetime.now().isoformat()
}
# 保存到文件
filename = f"profile_backup_{login_info.user_id}.json"
with open(filename, "w", encoding="utf-8") as f:
json.dump(backup_data, f, ensure_ascii=False, indent=2)
await event.reply(f"资料已备份到 {filename}")
@matcher.command("restoreprofile", permission="admin")
async def handle_restore_profile(event: MessageEvent, args: str):
"""
从备份恢复资料
"""
if not args:
await event.reply("需要备份文件名")
return
try:
with open(args, "r", encoding="utf-8") as f:
backup_data = json.load(f)
# 恢复资料（这里只是示例，实际可能需要更多字段）
await event.bot.set_qq_profile(
nickname=backup_data.get("nickname", "")
)
await event.reply("资料已恢复")
except Exception as e:
await event.reply(f"恢复失败: {e}")
注意事项
- 权限: 修改资料、退出登录等操作通常需要机器人有相应权限。
- 频率限制: 不要频繁修改资料或状态，可能被限制。
- 客户端支持: 不是所有 OneBot 客户端都支持全部 API，使用前最好测试一下。
- 谨慎操作:
bot_exit会让机器人下线，谨慎使用。