检查本地 NapCatQQ 运行环境、服务端口状态、已保存账号列表，并与 GitHub 官方最新 Release 版本进行对比。 当不确定 NapCat 是否已部署、是否正在运行或是否有新版本可更新时，优先调用此工具。

一键自动部署或更新 NapCat 运行时环境 (支持从 GitHub 官方 Release 下载或使用本地离线包解压并自动配置 OneBot 端口)。 ⚠️ 安全规范：首次调用必须保持 confirmed=False 以获取部署预览计划；向用户展示计划并获得明确授权后，再传入 confirmed=True 执行。 :param action: 执行动作类型，'deploy' (部署安装) 或 'update' (更新升级) :param confirmed: 是否已获得用户明确许可 (False 时仅返回预览，True 时真正执行解压/下载) :param use_local_zip_if_available: 部署时若本地存在离线包是否优先使用 :param target_uin: 要自动配置 OneBot 11 端口的 QQ 号 (留空则使用当前默认账号)

查看本地沙箱中所有已保存登录凭证的 QQ 账号列表、当前默认激活账号以及当前正在线运行的账号信息。 列表中的账号均可直接通过 switch_qq_account 免扫码快速切换上线。

切换当前使用的 QQ 账号（支持在多个已登录过的 QQ 号之间热切换）。 会自动更新默认配置与 OneBot 11 端口配置；当 restart_immediately=True 时，会自动停止旧账号进程并以新账号重启上线。 :param uin: 要切换的目标 QQ 号 :param restart_immediately: 是否立即重启 NapCat 服务使新账号即刻上线，默认 True :param wait_seconds: 重启时等待端口就绪的最大秒数，默认 25

启动新 QQ 账号扫码登录流程（绑定新 QQ 号或当旧账号凭证过期需要重新扫码时使用）。 执行流程：

1. 自动停止当前后台 NapCat 进程并清空自动登录配置；

2. 启动扫码沙箱生成高清二维码图片 (qrcode.png)，并在屏幕上自动弹出该二维码供用户用手机 QQ 扫码；

3. 等待用户扫码成功后，自动为新 QQ 号生成 OneBot 11 (3000/3001) 端口配置，并自动转为后台常驻模式上线。 :param open_image: 是否自动在电脑屏幕上用图片查看器弹出二维码图片，默认 True :param wait_scan_seconds: 等待用户手机扫码的最大秒数，默认 45 秒

查看本地最新的 NapCat 登录二维码图片路径 (qrcode.png)，并可选在电脑屏幕上直接打开展示该二维码。 :param open_image: 若二维码文件存在，是否立即在屏幕上打开图片查看器，默认 True

启动本地 NapCat 后台服务进程并等待端口 (3000/3001) 就绪。 若服务已在运行则直接返回就绪状态。 :param uin: 指定要登录启动的 QQ 号 (留空则使用默认激活账号) :param wait_seconds: 等待端口监听的最大秒数

安全停止当前后台运行的 NapCat 沙箱进程 (仅精准终止 napcat_runtime 下的进程，不影响系统其他 Node 服务)。

强制重启本地 NapCat 后台服务进程（可指定要登录的 QQ 号）。 :param uin: 指定重启登录的 QQ 号 (可选，留空则使用当前默认账号) :param wait_seconds: 等待端口监听就绪的秒数，默认 25

向指定好友或用户发送私聊消息 (OneBot 11: send_private_msg)。 支持纯文本、CQ 码 (如 [CQ:image,file=xxx] / [CQ:face,id=14])。 :param user_id: 对方 QQ 号 :param message: 要发送的消息内容 (文本或 CQ 码字符串) :param auto_escape: 是否作为纯文本发送 (不解析 CQ 码)，默认 False

向指定 QQ 群发送群聊消息 (OneBot 11: send_group_msg)。 支持纯文本、@全体成员 ([CQ:at,qq=all] 或直接 @全体成员)、@指定成员 ([CQ:at,qq=123456]) 及图片/表情等 CQ 码。 :param group_id: 目标 QQ 群号 :param message: 要发送的群消息内容 :param auto_escape: 是否作为纯文本发送 (不解析 CQ 码)，默认 False

通用消息发送接口 (OneBot 11: send_msg)，可根据 message_type 发送私聊或群聊消息。 :param message_type: 消息类型，'private' (私聊) 或 'group' (群聊) :param target_id: 当 message_type='private' 时为对方 QQ 号；为 'group' 时为目标群号 :param message: 要发送的消息文本或 CQ 码 :param auto_escape: 是否不解析 CQ 码，默认 False

撤回指定消息 (OneBot 11: delete_msg)。可撤回自己发出的消息，或作为群管理员撤回群成员消息。 :param message_id: 目标消息 ID

根据 message_id 获取单条消息的详细信息，包括发送者、发送时间、原始消息段等 (OneBot 11: get_msg)。 :param message_id: 目标消息 ID

获取合并转发消息的具体内容节点列表 (OneBot 11: get_forward_msg)。 :param message_id: 合并转发 ID (id / message_id)

向指定好友发送合并转发消息 (NapCat OneBot 11: send_private_forward_msg)。 节点格式示例: [{"type": "node", "data": {"name": "发送者昵称", "uin": "10001", "content": "消息内容"}}] :param user_id: 接收方好友 QQ 号 :param messages: 合并转发消息节点数组 (list of node dicts)

向指定群聊发送合并转发消息 (NapCat OneBot 11: send_group_forward_msg)。 节点格式示例: [{"type": "node", "data": {"name": "发送者昵称", "uin": "10001", "content": "消息内容"}}] :param group_id: 目标 QQ 群号 :param messages: 合并转发消息节点数组 (list of node dicts)

向指定好友资料卡点赞 (OneBot 11: send_like)。 :param user_id: 对方 QQ 号 :param times: 点赞次数 (1~10，默认 10)

发送“戳一戳”互动提醒 (NapCat 扩展接口: send_poke)。 若提供 group_id 则在群内戳指定成员；若不提供则发送私聊戳一戳。 :param user_id: 要戳的目标 QQ 号 :param group_id: 所在群号 (可选，不填则为私聊戳一戳)

对指定消息添加或取消表情回应 / 贴表情 (NapCat 扩展接口: set_msg_emoji_like)。 :param message_id: 目标消息 ID :param emoji_id: 表情 ID (如 128077 表示👍，或 QQ 表情 ID) :param set_like: True 为添加贴表情，False 为取消

将指定消息、私聊会话或群聊会话标记为已读 (NapCat 扩展接口: mark_msg_as_read / mark_private_msg_as_read / mark_group_msg_as_read)。 :param message_id: 消息 ID (可选) :param user_id: 好友 QQ 号，标记该私聊已读 (可选) :param group_id: 群号，标记该群聊已读 (可选)

将指定群消息设为群精华消息 (NapCat 扩展接口: set_essence_msg)。 :param message_id: 要设为精华的消息 ID

移出指定的群精华消息 (NapCat 扩展接口: delete_essence_msg)。 :param message_id: 要移出精华的消息 ID

获取指定 QQ 群的精华消息列表 (NapCat 扩展接口: get_essence_msg_list)。 :param group_id: 目标群号

将指定成员移出群聊 / 群踢人 (OneBot 11: set_group_kick)。需具备管理员或群主权限。 :param group_id: 群号 :param user_id: 被移出的成员 QQ 号 :param reject_add_request: 是否拒绝此人今后的加群申请，默认 False

群聊单人禁言或解禁 (OneBot 11: set_group_ban)。 :param group_id: 群号 :param user_id: 目标成员 QQ 号 :param duration: 禁言时长(秒)，设为 0 表示解除禁言，默认 1800 (30分钟)

开启或关闭群全员禁言 (OneBot 11: set_group_whole_ban)。 :param group_id: 群号 :param enable: True 开启全员禁言，False 关闭全员禁言

设置或取消群管理员 (OneBot 11: set_group_admin)。需群主权限。 :param group_id: 群号 :param user_id: 目标成员 QQ 号 :param enable: True 设为管理员，False 取消管理员

修改群成员的群名片 / 群昵称 (OneBot 11: set_group_card)。 :param group_id: 群号 :param user_id: 目标成员 QQ 号 :param card: 新群名片内容 (传空字符串表示清空群名片)

修改 QQ 群名称 (OneBot 11: set_group_name)。 :param group_id: 群号 :param group_name: 新群名称

设置群成员专属头衔 (OneBot 11: set_group_special_title)。需群主权限。 :param group_id: 群号 :param user_id: 目标成员 QQ 号 :param special_title: 专属头衔名称 (空字符串表示取消头衔) :param duration: 有效期秒数，默认 -1 表示永久

退出群聊或解散群聊 (OneBot 11: set_group_leave)。 :param group_id: 群号 :param is_dismiss: 是否解散群 (仅当自己是群主时有效)，默认 False

审批处理加群请求或邀请入群请求 (OneBot 11: set_group_add_request)。 :param flag: 加群请求事件上报的 flag 标识 :param sub_type: 请求类型，'add' (他人申请入群) 或 'invite' (被邀请入群) :param approve: True 同意，False 拒绝 :param reason: 拒绝时的理由 (仅在 approve=False 时生效)

将群内的某条消息设置为“群待办”提醒全员 (NapCat 扩展接口: set_group_todo)。 :param group_id: 群号 :param message_id: 要设为群待办的消息 ID

修改 QQ 群头像 (OneBot 11: set_group_portrait)。 :param group_id: 群号 :param file: 图片本地绝对路径、网络 URL 或 base64:// 字符串

查询指定群聊今日剩余的 @全体成员 次数 (OneBot 11: get_group_at_all_remain)。 :param group_id: 群号

获取指定群聊当前处于被禁言状态的成员列表 (NapCat 扩展接口: get_group_shut_list)。 :param group_id: 群号

获取群系统消息列表 (包括待审批的入群申请、被邀请进群通知等) (OneBot 11: get_group_system_msg)。

向指定好友发送本地文件附件 (NapCat OneBot 11: upload_private_file)。 :param user_id: 接收方好友 QQ 号 :param file_path: 本地文件的绝对路径 (如 'D:/Desktop/report.xlsx') :param file_name: 对方看到的显示文件名 (如 'report.xlsx')

向指定 QQ 群上传群文件 (NapCat OneBot 11: upload_group_file)。 :param group_id: 目标 QQ 群号 :param file_path: 本地文件的绝对路径 :param file_name: 群文件中显示的文件名 :param folder: 目标群文件夹 ID (可选，不填则上传至群文件根目录)

删除指定的 QQ 群文件 (NapCat OneBot 11: delete_group_file)。 :param group_id: 群号 :param file_id: 群文件 ID :param busid: 文件类型 busid，默认 102

删除指定的 QQ 群文件夹 (NapCat OneBot 11: delete_group_folder)。 :param group_id: 群号 :param folder_id: 群文件夹 ID

获取 QQ 群文件根目录下的所有文件与文件夹列表 (NapCat OneBot 11: get_group_root_files)。 :param group_id: 群号

获取 QQ 群指定文件夹内的文件与子文件夹列表 (NapCat OneBot 11: get_group_files_by_folder)。 :param group_id: 群号 :param folder_id: 文件夹 ID

获取指定群文件的直接 HTTP 下载链接 (NapCat OneBot 11: get_group_file_url)。 :param group_id: 群号 :param file_id: 群文件 ID :param busid: 文件 busid (可选，默认 102)

获取私聊文件的直接下载链接或本地缓存路径 (NapCat 扩展接口: get_private_file_url)。 :param file_id: 私聊文件 file_id

获取 QQ 群文件系统的空间使用情况 (总空间、已用空间、文件数上限等) (NapCat OneBot 11: get_group_file_system_info)。 :param group_id: 群号

调用 QQ 内置 OCR 引擎识别图片中的文字 (NapCat OneBot 11: ocr_image)。 :param image: 图片文件 ID、本地绝对路径或 HTTP URL

通过 NapCat 下载网络文件到本地缓存目录并返回本地绝对路径 (OneBot 11: download_file)。 :param url: 文件下载 URL :param thread_count: 下载线程数，默认 3 :param headers: 自定义请求头列表 (如 ["User-Agent=xxx"])

获取当前登录 QQ 的全部好友列表 (包括 user_id、nickname、remark 等) (OneBot 11: get_friend_list)。 :param no_cache: 是否强制不使用缓存刷新列表，默认 False

获取按好友分组归类的好友列表 (NapCat 扩展接口: get_friends_with_category)。

获取指定 QQ 用户（好友或陌生人）的公开个人资料 (昵称、性别、年龄、等级、个性签名等) (OneBot 11: get_stranger_info)。 :param user_id: 目标 QQ 号 :param no_cache: 是否不使用缓存

删除指定 QQ 好友 (OneBot 11: delete_friend)。 :param user_id: 要删除的好友 QQ 号

设置或修改指定好友的备注名 (NapCat 扩展接口: set_friend_remark)。 :param user_id: 好友 QQ 号 :param remark: 新备注名称

审批处理他人发来的加好友请求 (OneBot 11: set_friend_add_request)。 :param flag: 加好友请求事件上报的 flag 标识 :param approve: True 同意添加，False 拒绝添加 :param remark: 同意后的好友备注名 (可选)

修改当前登录 QQ 账号的个人资料 (NapCat 扩展接口: set_qq_profile)。 :param nickname: 新昵称 (可选) :param personal_note: 个人说明 / 个性签名 (可选) :param sex: 性别代码 (1男, 2女, 0未知，可选)

修改当前登录 QQ 账号的头像 (NapCat 扩展接口: set_qq_avatar)。 :param file: 图片本地绝对路径、HTTP URL 或 base64:// 字符串

设置当前登录 QQ 的个性签名 (NapCat 扩展接口: set_self_longnick)。 :param long_nick: 个性签名内容

设置当前登录 QQ 的在线状态 (NapCat 扩展接口: set_online_status)。 常用状态码: status=10(在线), 30(离开), 40(隐身), 50(忙碌), 60(Q我吧), 70(请勿打扰)。 :param status: 主状态码 (默认 10 在线) :param ext_status: 扩展状态码 (默认 0) :param battery_status: 电量状态 (默认 0)

获取当前登录的 QQ 账号信息 (返回 user_id 与 nickname) (OneBot 11: get_login_info)。

获取当前账号已加入的所有 QQ 群列表 (包含 group_id, group_name, member_count, max_member_count 等) (OneBot 11: get_group_list)。 :param no_cache: 是否强制刷新最新群列表而不使用缓存，默认 True

获取指定 QQ 群的详细信息 (群名称、人数、群主、群备注等) (OneBot 11: get_group_info)。 :param group_id: 目标群号 :param no_cache: 是否不使用缓存

获取指定群成员的详细资料 (群名片 card、昵称 nickname、群角色 role[owner/admin/member]、入群时间、最后发言时间、头衔等) (OneBot 11: get_group_member_info)。 :param group_id: 群号 :param user_id: 群成员 QQ 号 :param no_cache: 是否强制刷新缓存

获取指定 QQ 群的全部成员名单列表 (OneBot 11: get_group_member_list)。 :param group_id: 群号 :param no_cache: 是否强制刷新缓存

获取指定 QQ 群的群荣誉信息 (龙王、群聊之火、快乐源泉等) (OneBot 11: get_group_honor_info)。 :param group_id: 群号 :param honor_type: 荣誉类型: 'talkative'(龙王), 'performer'(群聊之火), 'legend'(群聊炽焰), 'strong_newbie'(冒尖小春笋), 'emotion'(快乐源泉), 或 'all'(全部)

从 NapCat 获取与指定好友的历史私聊消息记录 (NapCat OneBot 11: get_friend_msg_history)。 :param user_id: 好友 QQ 号 :param count: 获取的消息条数，默认 20 :param message_seq: 起始消息序号 (可选，不填则从最新一条往前拉取)

从 NapCat 获取指定群聊的历史聊天记录 (NapCat OneBot 11: get_group_msg_history)。 :param group_id: 群号 :param count: 获取的消息条数，默认 20 :param message_seq: 起始消息序号 (可选，不填则从最新一条往前拉取)

获取当前 QQ 最近联系列表 / 最近会话列表 (包含最近联系的好友和群聊及最新消息摘要) (NapCat 扩展接口: get_recent_contact)。 :param count: 返回的最近会话数量，默认 20

获取 NapCat OneBot 11 协议端运行状态与版本信息 (组合调用 get_status 与 get_version_info)。

获取 MCP 服务后台通过 WebSocket 实时监听并缓存的近期 QQ 消息列表。 支持按私聊/群聊、目标 QQ 号或群号、关键词过滤。 :param count: 返回的最大消息条数，默认 20 :param chat_type: 消息类型过滤: 'all' (全部), 'private' (仅私聊), 'group' (仅群聊) :param target_id: 按特定群号 (group_id) 或特定用户 QQ 号 (user_id) 过滤 (可选) :param keyword: 按消息文本或发送者昵称关键词过滤 (可选) :param include_self_sent: 是否包含自己发出的消息，默认 False

获取后台实时捕获的近期群通知事件 (如群文件上传、撤回、禁言、成员增减) 以及加好友/加群验证请求。 返回的 flag 字段可直接传入 set_friend_add_request 或 set_group_add_request 进行审批。 :param count: 最大返回条数，默认 20

清空本地内存中的近期实时消息缓存池。

万能底层接口透传工具：直接调用 NapCatQQ 支持的任意 OneBot 11 标准或扩展 Action (覆盖全部 144+ 项功能)。 当高层具名工具未涵盖某个特定冷门接口 (如群相册、群签到、语音转文字 fetch_ptt_text、AI声聊 send_group_ai_record、清理缓存 clean_cache 等) 时，使用此工具直接调用。 :param action: NapCat 接口名称 (例如 'send_group_sign', 'fetch_ptt_text', 'get_cookies' 等) :param params: 传递给该接口的 JSON 参数字典 (例如 {"group_id": 123456}) :param timeout: 请求超时秒数，默认 30.0

列出 NapCatQQ 官方引擎支持的全部 140+ 个底层 Action 名称目录，方便在使用 call_napcat_api 前查阅精确的接口名。 :param category: 分类过滤: 'all' | 'messaging' | 'group_management' | 'files_and_media' | 'friends_and_account' | 'ai_and_system'