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
安装器会做六件事：
- 把插件复制到
$DSH_HOME/plugin-src/dsh-napcat并以link:装进$DSH_HOME/profiles/web - 把
dsh-napcat写进 profile 的dsh.profile.bundles - 装 Xvfb / x11vnc / noVNC / Electron 运行库 / 中文字体
- 下载并解包 NapCat.Shell
- 下载并安装 Linux QQ 3.2.34（arm64 / amd64）
- 编译
libnapcat_launcher.so（启动时注入loadNapCat.js，不依赖 ptrace），并安装登录后自动配置 OneBot 的钩子
装完重启一次 DSH。
连接 QQ
- 设置 → QQ 机器人
- 点「一键启动 NapCat」
- 点「打开 WebUI」，用目标 QQ 扫码或密码登录
- 登录后
autoconfig-onebot.sh自动给onebot11_.json加上127.0.0.1:3001的 WS 服务（含 token），并带-q快速重启 NapCat - 回插件点「扫描本机」→「连接这个账号」
- 用另一个 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://: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会停在扫码页），3001 在听也拿不到get_login_info。 - 登录服务 timeout：NapCat 的 msf 登录服务掉线，重试或换网络。
- 数据目录：插件数据放
~/.dsh/dsh-napcat/data，不要放/sdcard（FUSE 权限会炸）。
更多排错命令、恢复步骤、升级时的注意事项都在 docs/HANDOVER.md。
许可
插件本体 MIT。NapCat 与 Linux QQ 由各自上游提供，安装器只从官方 / 镜像下载，不随包分发。
