dsh-qq-notify：基于本地 NapCat 的 QQ 通知插件

前言¶

在使用 DeepSeek Harness (DSH) 进行智能体开发或调试时，经常需要将系统的运行状态、错误日志或处理结果通过即时通讯工具通知给用户。直接调用第三方 IM 的 API 开发成本高且存在安全隐患。本插件提供了一套原生工具，允许 DSH 通过本地运行的 NapCat 机器人向 QQ 主号发送私聊消息，同时提供 NapCat 的部署、启停和状态检查能力。

插件简介¶

该插件由 wodongx123 维护，属于“联网工具”类别。它利用本机安装的 NapCat（QQ 机器人协议端）作为中转，实现 DSH 与 QQ 生态的互通。插件内置了 8 个工具，覆盖了从环境准备到消息发送的全流程。

核心功能¶

插件提供以下功能：
* 全自动部署：下载并引导安装 NapCat Shell（Windows Node 版）。
* 后台启停 NapCat：控制本地 NapCat 进程的运行状态。
* 检查 NapCat 在线状态：确认服务是否可用及当前登录账号。
* 向主号发送私聊消息：通过 QQ 发送通知。
* 查看与修改 QQ 配置：读取和更新配置文件。
* 检测目录是否为 NapCat：验证指定路径是否为合法的 NapCat 安装目录。
* 扫描全机 NapCat：自动发现本机所有 NapCat 实例。

安装与启用¶

在 DSH 插件目录下执行以下命令进行本地注册：

dsh plugin --profile web add file:<本目录>

插件安装后需重启 DSH 才能生效。

前置要求：
* 操作系统：Windows 10/11 x64。
* 账号准备：需准备一个已登录的机器人小号（用于扫码登录 NapCat），并将该小号添加主号为好友。

典型用法¶

插件提供的工具可通过自然语言指令调用：

1. 部署与启动

   • 帮我装好QQ通知：调用 qq_deploy，自动下载 NapCat Shell（Windows Node 版）、解压、修复 Bug（如 --no-sandbox、预置 crypto.dll/ssl.dll）并引导登录。
   • 启动QQ通知 / 重启NapCat：调用 qq_napcat，在后台启停 NapCat。

2. 状态与配置

   • 查一下QQ通道状态：调用 qq_status，返回 NapCat 是否在线及当前登录账号。
   • 查看当前QQ配置：调用 qq_config_show，显示所有配置项。
   • 我的QQ主号改成 xxx：调用 qq_config_set，修改 mainQq 等配置并保存。

3. 消息与检测

   • 用QQ发：xxx：调用 qq_send，向主号发送私聊消息。
   • 检测某目录是不是NapCat：调用 qq_detect，检查指定目录。
   • 扫描全机NapCat：调用 qq_find，自动发现所有安装实例。

配置文件¶

配置文件存储于插件根目录的 napcat 文件夹下，文件名为 qq-notify.config.json。主要配置项包括：
* mainQq：接收通知的主号 QQ（默认为空，需设置）。
* apiPort：NapCat HTTP API 端口（默认为 3002）。
* napcatDir：NapCat 部署目录（默认自动发现）。
* botQq：机器人小号 QQ（可选）。

注意事项¶

• 扫码登录：初次部署或状态未运行时，需通过浏览器访问 NapCat 的 WebUI（如 http://127.0.0.1:6099/webui）进行扫码登录。
• API 可达性：如果 qq_send 报错 API unreachable，需检查 NapCat 是否已启动以及 apiPort 端口是否被占用。
• 好友关系：发送消息成功的前提是主号与机器人小号互为好友。

生态链接¶

• DSH 插件目录
• GitHub 仓库