检查本地 NapCatQQ 运行时安装状态、OneBot 端口 (3000/3001) 监听情况、本地缓存账号列表，并请求 GitHub Release API 对比官方最新版本。 适用场景：首次连接、排查接口调用失败或判断是否有新版本可升级时优先调用。不适用与替代：若仅需读取当前在线 QQ 的 user_id 与昵称，请改用轻量级的 get_login_info（无需请求 GitHub，速度更快）。 行为与返回：纯只读无副作用操作（包含一次约 5 秒超时的外部 GitHub 版本探测）；返回包含 installed、port_listening、cached_accounts、latest_release 及 needs_update 诊断结论的字典，失败时在相应字段返回原因。

自动下载、解压并部署或升级本地 Windows NapCatQQ 运行时环境，同时自动写入 OneBot 11 (3000/3001) 端口配置。 适用场景：当 check_napcat_environment 显示未安装（选 action='deploy'）或存在新版本需升级（选 action='update'）时使用。不适用与替代：若运行时已安装且仅需启动、重启或切换账号，请改用 switch_qq_account 或 call_napcat_api，切勿重复重装。 参数约束与两阶段门禁：强制采用两阶段确认锁——首次调用必须传 confirmed=False 获取只读预览计划；向用户展示计划并获得明确许可后，再传 confirmed=True 真正执行文件覆写。target_uin 若指定须为 5~11 位纯数字 QQ 号字符串。 行为与副作用：confirmed=True 时会终止现有本地 NapCat 进程并覆写运行时目录（升级失败或健康检查不通过时自动回滚至旧版本备份）；仅支持本地 Windows 模式，外部远程 OneBot URL 调用将直接返回 status='failed'。

读取本地沙箱中所有已缓存登录凭证的 QQ 账号列表、当前默认激活账号及当前在线账号详情。 适用场景：在切换账号前查询有哪些历史已登录 QQ 号可供免扫码切换。不适用与替代：若仅需确认当前在线账号的 user_id 和昵称，请改用 get_login_info；若需同时检查运行时安装与 GitHub 版本更新，请改用 check_napcat_environment。 行为与返回：纯只读无副作用操作；返回 service_running、online_account、default_account 与 cached_accounts 数组。列表中的账号可直接传给 switch_qq_account 热切换。

在本地已保存登录凭证的多个 QQ 账号之间免扫码热切换，自动更新默认账号、OneBot 端口配置及按账号隔离的消息缓存池。 适用场景：目标 QQ 号此前已在本地扫码登录过（可通过 check_napcat_environment 的 cached_accounts 查看），需快速切换上线时调用。不适用与替代：若目标是一个从未登录过的新 QQ 号或登录凭证已失效，请勿使用本工具，应改用 login_new_qq_by_qrcode 扫码登录。 参数约束与交互：uin 必须为 5~11 位纯数字字符串；当 restart_immediately=True 时会立即终止旧账号进程并等待最多 wait_seconds 秒直至新账号端口就绪，为 False 时仅修改配置待下次启动生效。 行为与返回：幂等配置变更与进程重启操作（仅限本地运行时，外部 URL 返回失败）；返回 status、switched_to、online_account 与 available_accounts。

启动全新 QQ 账号的二维码扫码登录流程，生成高清二维码图片 (qrcode.png) 等待手机 QQ 扫码，成功后自动写入 OneBot 11 端口配置并转为后台常驻运行。 适用场景：首次绑定新 QQ 号，或已有账号登录态过期需要重新手机扫码授权时调用。不适用与替代：若目标 QQ 号已在本地缓存列表且凭证有效，请勿重新扫码，应改用 switch_qq_account 免扫码秒级切换。 参数约束与交互：open_image=True 会在本机 Windows 桌面自动弹出二维码查看器；wait_scan_seconds 控制阻塞等待用户手机确认的最大秒数（超时未扫返回 status='scan_timed_out'）。 行为与副作用：会主动停止当前正在运行的本地 NapCat 进程并重置自动登录配置；前置要求本地 NapCat 已部署（未部署请先调用 deploy_or_update_napcat），成功时返回 status='logged_in_and_configured'、new_uin 及 online_account。

读取本地缓存的最新 NapCat 登录二维码图片路径 (qrcode.png)，并可选在桌面弹出展示该图片。 适用场景：当 login_new_qq_by_qrcode 已经生成二维码但用户关闭了图片窗口需要重新查看时调用。不适用与替代：本工具不会启动扫码进程或刷新过期二维码；如需发起新的扫码会话，请改用 login_new_qq_by_qrcode。 行为与返回：只读查询本地文件状态（open_image=True 时触发本地图片查看器）；文件存在返回 status='ok' 与 qrcode_path，不存在返回 status='not_found'。

启动本地 NapCatQQ 后台服务进程并等待 OneBot (3000/3001) 端口就绪，同时挂载后台 WebSocket 事件监听。 适用场景：当本地服务处于停止状态、需要以默认或指定已缓存账号拉起后台进程时调用（启动前会自动检查并结束冲突的独立 QQ.exe 进程；若检测到需要扫码登录，会自动把登录二维码放到桌面并提示用户打开扫描）。不适用与替代：若服务已在运行且需切换其他已缓存账号，请改用 switch_qq_account。 行为与返回：幂等操作——启动前先结束冲突的独立 QQ.exe 进程；若端口已在监听则返回 status='already_running'；新启动成功返回 status='started'；若需扫码登录则将二维码导出至桌面并返回 login_required=True 及 desktop_qrcode_path。

安全终止本地后台运行的 NapCatQQ 沙箱进程（严格校验进程可执行文件与入口路径，绝不误杀系统其他 Node.js 进程）。 适用场景：需要彻底下线当前 QQ 机器人、释放本地 3000/3001 端口或维护运行时目录时调用。不适用与替代：若希望重启服务或切换其他已缓存 QQ 号上线，请直接改用 switch_qq_account。 行为与副作用：破坏性但幂等的进程终止操作——调用后当前 QQ 账号立即离线且实时消息监听中断，直至重新调用 switch_qq_account、login_new_qq_by_qrcode 或任意触发自动自愈的核心工具；返回被终止的 PID 列表 stopped_processes 与端口状态。

向指定 QQ 好友或私聊用户发送单条即时私聊消息 (OneBot 11: send_private_msg)。 适用场景：向个人 QQ 账号发送文本、CQ 码或富媒体消息段。不适用与替代：若目标是 QQ 群聊，请改用 send_group_msg；若需发送本地文件附件，请改用 upload_private_file。 参数约束与交互：message 支持含 CQ 码的字符串或 OneBot 标准消息段数组（如 [{"type":"face","data":{"id":"14"}}]）；仅当希望将 [CQ:...] 原样作为纯文本输出时才将 auto_escape 设为 True。 行为与返回：非幂等外部发送操作（调用即真实发出消息）；前置要求当前账号已在线且与目标存在好友或临时会话关系，成功返回 status='ok' 及 data.message_id（可用于后续 delete_msg 撤回），被风控或非好友时返回非 0 retcode。

向指定 QQ 群发送单条群聊消息 (OneBot 11: send_group_msg)。 适用场景：在已加入的 QQ 群内发布通知、@成员或发送富媒体消息。不适用与替代：若目标是个人好友私聊，请改用 send_private_msg；若需向群内上传文档或压缩包附件，请改用 upload_group_file。 参数约束与交互：如需产生真实的 @全体成员 或 @指定成员 提醒，必须在 message 中使用 CQ 码 [CQ:at,qq=all] / [CQ:at,qq=123456]（且保持 auto_escape=False）或传入 at 类型消息段，手写纯文本“@全体成员”不会触发群提醒。 行为与返回：非幂等群广播操作；前置要求当前 QQ 已加入目标群且未被禁言（@全体成员需群主或管理员权限且受每日次数限制），成功返回 status='ok' 及 data.message_id，无权限或被禁言时返回非 0 retcode。

从私聊或群聊会话中永久撤回指定消息 (OneBot 11: delete_msg)。 适用场景：发错消息需紧急撤回，或作为群主/群管理员撤回群成员的违规发言。不适用与替代：若仅需将群精华消息移出精华列表或删除群共享文件，请通过 call_napcat_api 调用 delete_essence_msg 或 delete_group_file。 参数约束：传入的 message_id 必须来自 send_private_msg、send_group_msg 的返回值或 get_recent_messages 消息记录中的有效整数 ID。 行为与权限限制：不可逆的破坏性操作（撤回后消息无法恢复）；撤回自身消息受 QQ 平台 2 分钟时效限制，撤回他人群消息要求当前账号在该群具备管理员或群主权限，超时或权限不足将返回非 0 retcode。

将本机磁盘上的文件作为私聊附件发送给指定 QQ 好友 (NapCat OneBot 11: upload_private_file)。 适用场景：向个人 QQ 好友交付文档、表格、PDF 或压缩包等本地文件。不适用与替代：若需将文件上传至 QQ 群共享空间，请改用 upload_group_file；若仅需发送纯文本或图片消息段，请改用 send_private_msg。 参数约束与交互：file_path 必须为当前机器上已存在且可读的本地绝对路径（如 D:/Desktop/report.xlsx）；file_name 应包含正确的文件扩展名以便接收方客户端识别打开。 行为与返回：非幂等外部文件传输操作（默认超时 120 秒以支持大文件上传）；前置要求当前账号已在线且目标为好友，成功返回 status='ok'，若本地文件不存在、超出大小限制或非好友则返回非 0 retcode。

将本机磁盘上的文件上传至指定 QQ 群的群文件共享空间 (NapCat OneBot 11: upload_group_file)。 适用场景：向 QQ 群发布共享资料、汇总表或通知附件。不适用与替代：若需将文件单独私发给某个好友，请改用 upload_private_file；若仅需在群内发送文字通知，请改用 send_group_msg。 参数约束与交互：file_path 必须为本机已存在的绝对路径；省略 folder 时默认上传至群文件根目录，若指定 folder 则须传入通过 call_napcat_api(action='get_group_root_files') 查询到的有效群文件夹 ID。 行为与返回：非幂等群文件创建操作（默认超时 120 秒，同名文件通常会在群文件列表中产生新条目）；前置要求当前账号已加入目标群且群文件空间未满、具备上传权限，成功返回 status='ok'。

获取当前在线 QQ 账号的基础身份信息，返回 user_id（QQ 号）与 nickname（昵称）(OneBot 11: get_login_info)。 适用场景：快速确认当前是哪个 QQ 号在线，或验证 OneBot 接口连通性。不适用与替代：若需检查本地所有已缓存的历史账号列表或运行时安装与 GitHub 最新版本对比，请改用 check_napcat_environment。 行为与返回：纯只读无副作用操作；成功返回 status='ok' 及 data: {"user_id": int, "nickname": str}，若当前未登录或服务未启动则返回 status='failed' 及非 0 retcode。

获取当前登录 QQ 账号已加入的全部 QQ 群列表，包含每群的 group_id、group_name、member_count 与 max_member_count (OneBot 11: get_group_list)。 适用场景：在发送群消息或上传群文件前，根据群名称查找对应的 group_id 或遍历已加入的群聊。不适用与替代：若已知具体 group_id 仅需查询该单群的详细资料或需查询好友列表，请通过 call_napcat_api 调用 get_group_info 或 get_friend_list。 参数约束与行为：no_cache=True（默认）会强制向 QQ 服务器拉取最新群列表以确保新加入的群立即可见；纯只读无副作用操作，成功在 data 中返回群信息字典数组。

读取 MCP 服务后台通过 WebSocket 实时监听并保存在本地环形内存缓存池（上限 200 条，按登录账号隔离）中的近期 QQ 消息列表。 适用场景：快速轮询或按条件检索服务运行期间实时收到的最新私聊与群聊消息。不适用与替代：若需查询 MCP 启动之前的历史聊天记录或向更早页码翻页，请通过 call_napcat_api 调用 get_friend_msg_history 或 get_group_msg_history；若需查看加群/加好友审批请求或群撤回通知，请调用 get_recent_notices_and_requests。 参数约束与交互：当指定 target_id 时，若 chat_type='group' 则按群号过滤，若 chat_type='private' 则按发送者 QQ 号过滤，若 chat_type='all' 则同时匹配群号或 QQ 号；keyword 对净化后的消息文本 clean_text 与发送者昵称做大小写不敏感子串匹配。 行为与返回：纯内存只读操作（零外部网络延迟，不修改缓存状态）；返回 ws_connected、count 及 messages 数组（每项含 message_id, chat_type, user_id, group_id, sender_name, clean_text, time）。

从本地 WebSocket 环形缓存池中读取近期实时捕获的群通知事件（群文件上传、消息撤回、禁言、成员变动）及加好友/加群验证请求。 适用场景：监听群动态或获取验证请求的 flag 标识以便通过 call_napcat_api 调用 set_friend_add_request / set_group_add_request 审批。不适用与替代：若需读取普通私聊或群聊文字/富媒体消息，请改用 get_recent_messages。 行为与返回：纯本地内存只读操作；返回 ws_connected、notices 数组与 requests 数组。

清空当前登录账号在本地 MCP 内存环形缓冲区中暂存的所有实时消息、群通知与请求事件记录。 适用场景：在完成一批消息处理或测试重置时，主动清空本地内存缓冲以避免重复读取旧事件。不适用与替代：本工具仅清空本地内存缓存，不会撤回 QQ 聊天消息（撤回请用 delete_msg）也不会清除 QQ 客户端未读红点（标记已读请通过 call_napcat_api 调用 mark_msg_as_read）。 行为与副作用：本地破坏性且不可逆的内存清空操作（不影响 QQ 服务器端历史记录，后续可通过 call_napcat_api 调用 get_friend_msg_history / get_group_msg_history 重新从服务器拉取）；返回被清除的记录总数 cleared_count。

调用 NapCatQQ 任意 OneBot 11 标准或扩展底层 Action（覆盖全部 144+ 项功能）的通用兜底透传工具。 适用场景：仅当核心专用工具未覆盖所需功能时使用（例如查询历史记录 get_friend_msg_history/get_group_msg_history、群管禁言踢人 set_group_ban/set_group_kick、文件下载与 OCR download_file/ocr_image、好友与资料管理 get_friend_list/set_qq_profile、群相册或打卡等）。不适用与替代：严禁使用本工具替代已暴露的核心专用工具（发送私聊/群聊请用 send_private_msg/send_group_msg，撤回请用 delete_msg，上传文件请用 upload_private_file/upload_group_file）；不确定 action 精确名称时，请先调用 list_supported_napcat_actions 检索。 参数约束与交互：action 必须为合法的 OneBot 11 / NapCat 端点名（不含前导斜杠 /）；params 为传给该端点的 JSON 键值字典，上传或下载大文件时建议将 timeout 调大至 120.0。 行为、权限与副作用：操作性质完全取决于所调用的 action——get_*/fetch_* 为只读查询，而 delete_*/set_group_kick/set_group_leave 属于不可逆破坏性操作且要求当前账号已在线并具备相应群主/管理员权限；返回标准 OneBot 响应字典 {"status": "ok"|"failed", "retcode": int, "data": ...}，未知 action 或参数错误时返回非 0 retcode 并提示调用 list_supported_napcat_actions。

查询 NapCatQQ 引擎支持的全部 144+ 个底层 OneBot 11 与扩展 Action 名称分类目录。 适用场景：在准备调用 call_napcat_api 但不确定目标功能的精确 action 英文名称时，先调用本工具按分类查阅。不适用与替代：若所需操作已有直接对应的核心具名工具（如 send_private_msg、send_group_msg、get_group_list 等），则无需查阅本目录；本工具仅返回接口名称清单，真正执行接口调用请使用 call_napcat_api。 参数约束与交互：category 可按功能域筛选子集（如群管选 'group_management'，媒体选 'files_and_media'，系统与 AI 声聊选 'ai_and_system'），若传入未识别的分类名则自动回退返回 'all' 全量字典。 行为与返回：纯本地静态目录只读查询（无网络请求、无需登录在线、零副作用）；当 category='all' 时返回 total_count 与按分类组织的 categories 字典，指定单一分类时返回 count 与 actions 字符串数组。