前言¶
在 DeepSeek Harness（DSH）上做一个能收发 QQ 消息的机器人，绕不开三件事：装 LinuxQQ、装 NapCat 这类 OneBot 实现、再分别处理登录态和启动。这三件事分散在命令行与多个进程之间，换台机器就要重做一遍，登录态也容易丢。下面介绍的 dsh-qq-stack 就是把这一整套流程收进一个插件里：下载、解包、配置、启动交给插件，登录态托管起来，对外只暴露标准的 OneBot 11 接口。
这是什么¶
dsh-qq-stack 是 DSH 的 QQ 协议端插件，维护者为 2008BingYu。它解决的是上面说的重复劳动：把 LinuxQQ 与 NapCat 的安装、启动、登录交给插件管理，对上提供 OneBot 11 正向 WebSocket，供任意兼容客户端接入。仓库版本为 1.1.0，许可证 MIT。
核心功能¶
插件的能力按职责拆开看主要有六项：
- 随引擎启动：引擎拉起后自动检查运行环境，缺失时后台安装，就绪时直接启动 QQ
- 标准协议端：OneBot 11 正向 WebSocket，默认监听
127.0.0.1:3001 - 登录态托管：扫码一次后保存账号，后续启动使用快速登录
- 安装过程可见：分步显示 LinuxQQ、NapCat 的下载与解压状态，以及镜像测速进度
- 配置可在页面修改：监听地址与访问令牌保存后自动生效
- 运行环境可清理：页面内一键停止 QQ，并删除已下载的客户端与登录数据
安装启用¶
安装命令来自 README 原文：
dsh plugin --profile web add dsh-qq-stack
也可以在插件页的「添加插件」中填入包名，或使用 Release 中提供的压缩包。安装完成后需要重启一次引擎。
需要注意：插件不会自动安装运行环境。引擎启动后约 2 秒会检查 ~/.dsh/qq-bot：已安装则直接启动 QQ；未安装时只在设置页提示，需要点击「开始安装」后才会执行下面这几步：
- 下载 LinuxQQ 客户端（约 198MB）
- 检查系统依赖，缺失时按当前发行版安装对应软件包
- 测试多个下载源，选择可用且最快的一个下载 NapCat（约 34MB）
- 解包、写入 OneBot 配置、生成启动脚本
- 启动 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 运行日志 |
页面上的每个操作都会记进 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 磁盘空间与相应下载流量。插件启动的 Linux 版 QQ 客户端依赖 xvfb-run 与 dbus-run-session，因此不支持 Windows。
几个容易踩的点：
- 扫码后仍显示未登录，需要先在手机上确认登录，仅扫码不构成登录
- 卸载或清理运行环境会删除登录数据，重装后属于全新安装，需要重新扫码
- 一段时间后掉线时，引擎启动会重新拉起 QQ 并用已保存账号快速登录；登录态失效则需重新扫码
- 群里没有回复时，消息处理由接入的对话插件负责，本插件只维护 QQ 在线与协议接口
- 提示登录失败或账号受限属于 QQ 账号侧限制，需在 QQ 安全中心完成身份验证后再尝试登录
另外要注意权限边界：插件以当前 dsh 进程的权限运行，安装前应先检查源码与许可证，再决定是否引入。
卸载插件不会自动删除运行环境，删除方式二选一：卸载前在设置页点击「清理运行环境」，或手动执行：
bash ~/.dsh/qq-bot/stop-qq.sh && rm -rf ~/.dsh/qq-bot
结尾¶
dsh-qq-stack 的价值在于把「装环境、起 QQ、管登录、暴露协议」做成一条可复现的链路，让 QQ 机器人接入 DSH 时不必再手工维护 LinuxQQ 与 NapCat。目录页在 https://www.skillhub.cn/plugins/2008BingYu/dsh-qq-stack，源码在 https://github.com/2008BingYu/dsh-qq-stack。该目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
