dsh-qq-bot

把 QQ 接进 DeepSeek Harness 的机器人插件：用 NapCat 当协议端，走 OneBot v11（WebSocket），在 DSH 里跑人设、记忆、存档、白名单、主动暖场、表情包和扩展。

仓库名 dsh-qq-bot，插件内部包名与 bundle id 仍是 dsh-napcat（安装脚本、路径 ~/.dsh/dsh-napcat、路由 /dsh-napcat/api/* 都以此为准）。

实测环境：Android 手机上的 DSH（Ubuntu 24.04 proot）+ NapCat 4.18.42 + Linux QQ 3.2.34 arm64，全程 127.0.0.1，不需要把机器人挂到公网。

---

特性

协议	NapCat → OneBot v11 正向 WS（默认 ws://127.0.0.1:3001/），也支持 HTTP 模式与远程 NapCat
连接	「一键启动 NapCat」「打开 WebUI」「扫描本机」「连接这个账号」——不用手改 JSON
人设与记忆	分人设配置、长期记忆、对话存档，可回滚
白名单	只回指定 QQ / 群，其余消息直接丢弃
主动暖场	长时间没人说话可自动抛话题
表情包	本地表情包目录 + 自动挑选发送
扩展	examples/extensions/*.mjs 热插拔自定义命令
日志	每轮请求、回复、错误都落盘，可在设置页查看

环境要求

• Linux（arm64 或 amd64），在 Android 的 proot 容器里同样可用
• Node.js ≥ 20
• DSH 0.2.x，profile 目录可用（默认 ~/.dsh/profiles/web）
• 一键安装会额外装：Xvfb、x11vnc、noVNC、Electron 运行库、中文字体、NapCat.Shell、Linux QQ
• 建议能访问 GitHub 镜像（gh-proxy.com）与腾讯 CDN（qqdl.gtimg.cn）

一键安装

tar xzf dist/dsh-napcat-0.1.0.tgz
cd package
bash install.sh

安装器会做六件事：

1. 把插件复制到 $DSH_HOME/plugin-src/dsh-napcat 并以 link: 装进 $DSH_HOME/profiles/web
2. 把 dsh-napcat 写进 profile 的 dsh.profile.bundles
3. 装 Xvfb / x11vnc / noVNC / Electron 运行库 / 中文字体
4. 下载并解包 NapCat.Shell
5. 下载并安装 Linux QQ 3.2.34（arm64 / amd64）
6. 编译 libnapcat_launcher.so（启动时注入 loadNapCat.js，不依赖 ptrace），并安装登录后自动配置 OneBot 的钩子

装完重启一次 DSH。

连接 QQ

1. 设置 → QQ 机器人
2. 点「一键启动 NapCat」
3. 点「打开 WebUI」，用目标 QQ 扫码或密码登录
4. 登录后 autoconfig-onebot.sh 自动给 onebot11_<QQ号>.json 加上 127.0.0.1:3001 的 WS 服务（含 token），并带 -q <QQ号> 快速重启 NapCat
5. 回插件点「扫描本机」→「连接这个账号」
6. 用另一个 QQ 发条消息验证

也可以用命令行手动确认：

/opt/napcat/start.sh                     # 起 Xvfb/VNC/QQ/NapCat
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/   # 426 = WS 在听
tail -f /root/.dsh/dsh-napcat/boot.log   # 插件日志

远程 NapCat

不想在手机上跑 QQ 也行：在设置页「NapCat 主机」填那台机器（电脑 / 服务器）的局域网 IP，WebUI 端口 6099、OneBot 端口 3001，点「扫描本机」或直接填 ws://<IP>:3001/ + token。

目录结构

lib/index.js        宿主半端：路由、工具、懒人连接、配置
lib/napcat.js       NapCat 探测 / onebot11 解析 / 启停
lib/onebot.js       OneBot v11 客户端（重连、心跳、API 超时）
lib/pipeline.js     人设、记忆、聊天、暖场、表情包
lib/store.js        存档 / 记忆 / 表情包 / 扩展的数据层
lib/client.js       设置页（React）
install.sh          一键安装器
scripts/setup-napcat.sh       环境安装（NapCat + QQ + Xvfb/noVNC）
scripts/autoconfig-onebot.sh  登录后自动配 3001
docs/HANDOVER.md    完整交接：目录地图、九个坑、从零重装、排错、恢复
docs/SETTINGS.md    全部设置项速查
docs/EXTENSIONS.md  写扩展
dist/               压缩附件（见下）

压缩附件

仓库里 dist/ 放的是直接可用的压缩包，不展开：

文件	说明
dist/dsh-napcat-0.1.0.tgz	插件包本体，tar xzf 后 bash install.sh 即可
dist/dsh-napcat-handover2.zip	交接整包：插件 tgz + 交接文档 + 一键入口，适合直接丢给智能体或另一台设备

附带的环境安装脚本（install.sh / scripts/setup-napcat.sh）会自己把 NapCat、Linux QQ、Xvfb 等环境备齐，不需要预先手工装依赖。

常见问题

• 装了插件 DSH 起不来：插件顶层 inject: ['webServer'] 会卡在"等待服务"，必须用 ctx.inject([...], scope => ...)。恢复步骤见 docs/HANDOVER.md 第 5 节。
• WebUI 打不开：确认 6099 在听，http://127.0.0.1:6099/webui/；token 在 /opt/napcat/napcat/config/webui.json。
• 连上了但提示离线：NapCat 没登录（缺 -q <QQ号> 会停在扫码页），3001 在听也拿不到 get_login_info。
• 登录服务 timeout：NapCat 的 msf 登录服务掉线，重试或换网络。
• 数据目录：插件数据放 ~/.dsh/dsh-napcat/data，不要放 /sdcard（FUSE 权限会炸）。

更多排错命令、恢复步骤、升级时的注意事项都在 docs/HANDOVER.md。

许可

插件本体 MIT。NapCat 与 Linux QQ 由各自上游提供，安装器只从官方 / 镜像下载，不随包分发。