dsh-qq-stack

dsh-qq-stack

DeepSeek Harness 的 QQ 协议端插件。把 LinuxQQ 与 NapCat 安装、启动、登录这一整套流程交给插件管理，对外提供标准的 OneBot 11 接口，供任意兼容客户端接入。

功能

• 随引擎启动：引擎拉起后自动检查运行环境，缺失时后台安装，已就绪时直接启动 QQ
• 标准协议端：OneBot 11 正向 WebSocket，默认监听 127.0.0.1:3001
• 登录态托管：扫码一次后保存账号，后续启动使用快速登录
• 安装过程可见：分步显示 LinuxQQ、NapCat 的下载与解压状态，以及镜像测速进度
• 配置可在页面修改：监听地址与访问令牌保存后自动生效
• 运行环境可清理：页面内一键停止 QQ 并删除已下载的客户端与登录数据

安装

dsh plugin --profile web add dsh-qq-stack

也可以在插件页的「添加插件」中填入包名，或使用 Release 中提供的压缩包。

安装完成后重启一次引擎。

首次运行

引擎启动后约 2 秒，插件检查 ~/.dsh/qq-bot。若运行环境不存在，会在后台执行安装：

1. 下载 LinuxQQ 客户端（约 198MB）
2. 检查系统依赖，缺失时按当前发行版安装对应软件包
3. 测试多个下载源，选择可用且最快的一个下载 NapCat（约 34MB）
4. 解包、写入 OneBot 配置、生成启动脚本
5. 启动 QQ

安装过程与结果记录在 ~/.dsh/qq-bot/logs/install.log，页面会同步显示当前步骤与进度。

使用

设置页分为两个页面。

登录

• 未登录时显示二维码，用手机 QQ 扫码并在手机上确认登录
• 扫码后二维码区域会显示当前状态
• 登录成功后显示头像、昵称与 QQ 号，可切换账号

设置

• 连接设置：监听地址与访问令牌，修改后自动保存并重启 QQ 生效
• 清理运行环境：停止 QQ 并删除 ~/.dsh/qq-bot

配置

配置文件为 ~/.dsh/qq-bot/config.env。

键	默认	说明
DSH_QQ_UIN	登录后自动写入	用于快速登录的 QQ 号
DSH_QQ_HOST	127.0.0.1	OneBot 监听地址
DSH_QQ_WS_PORT	3001	OneBot 监听端口
DSH_QQ_TOKEN	空	访问令牌；留空表示不校验

安装目录默认为 ~/.dsh/qq-bot，可通过环境变量 DSH_QQ_ROOT 修改。

接入 OneBot 客户端

任意兼容 OneBot 11 的客户端都可以连接：

• 地址：ws://127.0.0.1:3001
• 令牌：与 DSH_QQ_TOKEN 一致；该值为空时无需填写

日志

路径	内容
~/.dsh/qq-bot/logs/plugin.log	插件操作日志：每次按钮请求、状态变化、保存/应用/登出等（令牌已脱敏，超过 2MB 轮转）
~/.dsh/qq-bot/logs/install.log	安装过程与各步骤进度
~/.dsh/qq-bot/logs/qq.log	QQ 与 NapCat 运行日志

排查

页面上的每个操作（保存配置、应用配置、切换账号、清理运行环境、刷新二维码）都会记进 logs/plugin.log，包含请求路径、耗时、结果和关键状态变化。也可以直接取尾部内容：

http://127.0.0.1:3080/api/plugins/qq-stack/log?n=200

日志中的令牌一律替换为 ***。

环境要求

• Linux（aarch64 / amd64），可安装 apt 软件包；Android 上的 DSH 运行环境同样适用
• Node ≥ 22.5
• 首次安装约需 250MB 磁盘空间与相应下载流量

不支持 Windows：插件安装的是 Linux 版 QQ 客户端，启动依赖 xvfb-run 与 dbus-run-session。

常见问题

扫码后仍显示未登录

需要先在手机上确认登录，仅扫码不构成登录。

卸载重装后需要重新扫码

卸载或清理运行环境会删除登录数据，重装后属于全新安装。

一段时间后掉线

引擎启动时插件会重新拉起 QQ 并使用已保存的账号快速登录。若登录态失效，需要重新扫码。

群里没有回复

消息处理由接入的对话插件负责，本插件只维护 QQ 在线与协议接口。

提示登录失败或账号受限

属于 QQ 账号侧限制，需在 QQ 安全中心完成身份验证后再尝试登录。

卸载

卸载插件不会自动删除运行环境。删除方式二选一：

• 卸载前在设置页点击「清理运行环境」
• 手动执行：

bash ~/.dsh/qq-bot/stop-qq.sh && rm -rf ~/.dsh/qq-bot

许可

MIT