dsh-qq-remote — 用 QQ 远程控制你的 DeepSeek Harness

⚠️⚠️ 安全警告（必读）⚠️⚠️

本插件可以通过 QQ 远程执行命令、截图、查看文件——权限很大，请务必注意：

1. 必须配置白名单：allowedUsers 留空 = 任何 QQ 号都能控制你的电脑。 安装后第一件事：在 DSH 设置页「QQ 远程」面板的控制白名单里添加你自己的 QQ 号（或编辑 ~/.dsh/qq-remote.json 的 allowedUsers）。
2. 强烈建议使用小号：机器人 QQ 请用小号 / 专用机器人号，不要用日常主号。 QQ 机器人框架（NapCat 等）存在被风控甚至封号的风险；且插件权限极大，小号出问题不会影响你的主号与账号资产。

装上这个插件，你的 QQ 就能变成 DSH 的遥控器：出门在外用手机发条消息就能让电脑干活 —— 派任务、跑命令、看进度、收截图；想聊天时它又能变成陪你闲聊的 AI 搭子。登录失效不用折腾命令行，打开设置面板扫码即恢复。

⚠️ 前置依赖（必装）：本插件不包含 QQ 协议实现，需要先安装并运行 NapCat（或 Lagrange.OneBot / go-cqhttp / LLOneBot 等 OneBot 11 实现）作为 QQ 桥。NapCat 未运行时插件无法收发 QQ 消息，面板会显示"NapCat 未启动"。

NapCat 与插件联动三步：

1. 安装 NapCat（Linux：https://im.qq.com/linuxqq 装 QQ 后用 NapCat 官方脚本注入，或用 NapCat.Shell；Windows/macOS 用官方安装包），启动并手机扫码登录机器人 QQ
2. 打开 NapCat WebUI（默认 http://127.0.0.1:6099/webui）→ 网络配置 → 新增 WebSocket 服务端：监听 127.0.0.1:3001（路径 /ws，消息格式 array）——与插件默认 wsUrl 一致
3. 启动 DSH + 插件后，DSH 设置页「QQ 远程」面板会显示"已连接"；若 NapCat 登录失效，面板可直接扫码恢复

💡 安装提示：直接把这个仓库链接发给你的 AI 编程助手（Codex、Claude Code 等），它能按本 README 自行完成安装与配置。

功能

命令一览

环境要求

平台支持情况：

• ✅ 已在 Ubuntu 环境验证安装通过（一键安装脚本、插件市场 cordis-plugin 安装管线、与 NapCat 联动、扫码登录全链路均实测可用）

安装与配置

一键安装（推荐，开源用户）

git clone https://github.com/ASAKAFENG/dsh-qq-remote
cd dsh-qq-remote
bash scripts/install.sh

自动完成：构建 → 安装到 DSH profile → 注册 loader 条目 → 生成配置模板（~/.dsh/qq-remote.json），重启 DSH 生效。

手动安装

1. 构建：bash scripts/build.sh（纯 JS，无编译依赖）
2. 注入：DSH 侧 dev_inject_plugin（或 loader 装配），插件名 @dsh-external/dsh-qq-remote
3. 运行任一 OneBot 11 实现（如 NapCat），开启反向 WebSocket（默认 ws://127.0.0.1:3001/ws）， 路径与插件 wsUrl 保持一致；配置了 token 时 WS 走 ?access_token=、HTTP 走 Authorization: Bearer

配置有两种方式：插件 Config（loader 注入时传入）或覆盖层文件 ~/.dsh/qq-remote.json （免改代码、即时生效，热重载后应用）：

{
  "wsUrl": "ws://127.0.0.1:3001/ws",
  "allowedUsers": [123456789],
  "groupPrefix": "/",
  "privatePlainAsTask": true,
  "autoReport": true,
  "reportMode": "phase",
  "chatSystemPrompt": "你是用户通过 QQ 联系的一位聊天伙伴。回复要像真人 QQ 聊天一样：简短自然、口语化、有来有回，不要使用列表/表格/标题等正式格式，不要提及你是 AI、模型或助手。",
  "chatHistoryLimit": 0,
  "chatMaxChars": 0,
  "chatSessionNames": []
}

说明：chatSystemPrompt 是聊天模式的人设提示词，默认只约束"像真人聊天"的回复格式，可自由替换成任何角色（如 AI 女友、助理、猫娘…）； chatHistoryLimit / chatMaxChars 为 0 表示上下文无限制（全量发送）； chatSessionNames 由 /chatbind 命令自动维护，一般无需手改。

完整配置项见 USAGE.md（含 reportMode/phaseIntervalMs/chatSessionNames 等全部字段）。

快速上手

1. 配置白名单：通过设置里面的 QQ远程 来配置 或者 ~/.dsh/qq-remote.json，把 allowedUsers 改成你的 QQ 号（默认示例 [123456789] 会放行任意消息，务必替换）
2. 重启 DSH 让插件加载生效（或热重载）
3. 确保 NapCat 已安装并运行（前置依赖，见文首"NapCat 与插件联动三步"）：NapCat WebUI 里配好 127.0.0.1:3001 的 WebSocket 服务端并已扫码登录机器人 QQ
4. 验证打通：DSH 设置页「QQ 远程」面板显示"已连接"，用你的 QQ 号给机器人发 /ping → 回复 pong 即成功；发 /help 查看全部命令
5. 登录失效恢复：面板出现二维码后用手机 QQ 扫码授权（2 分钟有效，自动刷新；扫码是 QQ 安全机制，无法跳过）
6. 常用命令：

💡 进度会自动推送到 QQ（/quiet off 可关）；设置页可增删控制白名单；uninstall.sh --purge 可彻底卸载。

截图原理

优先调用 xdg-desktop-portal 的 Screenshot（GNOME Wayland 非交互截屏，无需额外安装）； 失败则依次尝试自定义 screenshotCommand、grim、scrot、maim、import、gnome-screenshot。

测试

test/onebot-mock.mjs 是一个本地 OneBot 模拟服务端，用于无 QQ 环境下的端到端验证：

cd test && npm i        # 安装 ws（仅测试依赖）
node test/onebot-mock.mjs 3001
# 另一个终端：node test/onebot-mock.mjs 的 stdin 输入:
#   msg 123456 /exec echo hello
#   msg 123456 /screenshot

安全提示

• allowedUsers 务必配置为你的 QQ 号，否则任何给你机器人发消息的人都能控制电脑
• /exec 可执行任意命令；execAllowed: false 可整体禁用
• 建议通过 NapCat 使用小号/机器人号，避免主号被风控

更新日志

v1.0.0（2026-08-16）—— 🎉 正式版

• ✅ 已彻底完成全流程验证：Ubuntu 环境安装（一键脚本 / 插件市场 cordis-plugin 管线）→ 前置 NapCat 部署与联动（WebUI 配置 3001 WebSocket 服务端）→ OneBot 连接 → QQ 扫码登录 → 命令执行 / 任务派发 / 进度推送 / 截图回传 / AI 聊天 / 会话管理 / 白名单 / 二维码失效自动刷新与扫码恢复 —— 全链路实测通过
• 🎯 本版本作为正式版本（1.0.0），后续功能迭代将在 1.x 上继续

v0.3.16（2026-08-16）—— 清理引导残留文案

• 🧹 全面清理移除一键引导后的残留：panel.js 注释/头部描述、设置面板与完整面板的"一键安装/启动 NapCat"提示文案（改为指向 README 前置依赖）、README 遗留 FAQ 行
• 🔧 relogin/诊断提示统一指向"README 前置依赖 + WebUI 3001 配置"

v0.3.15（2026-08-16）—— 移除一键引导，回归"前置依赖 NapCat"模式

• 🗑️ 移除一键引导功能：不再自动下载/安装/配置 NapCat（引导模块 napcat.js 及面板按钮、下载源、机器人 QQ 号输入全部移除）——插件回归纯远程控制职责，NapCat 由用户自行安装（README 摘要给出前置依赖提醒与联动三步）
• 📖 README 摘要新增 "前置依赖（必装）" 提醒：NapCat 与插件联动三步（装 NapCat + 扫码 → WebUI 配 3001 WebSocket 服务端 → 面板显示已连接）
• 🧹 代码精简：移除 napcat.js 模块（约 400 行）、3 个配置项、4 个面板路由、引导 UI 区块
• 🧪 e2e 精简为 17 用例（保留诊断/二维码/消息链路）

v0.3.14（2026-08-16）—— 修复 launcher 引导：NAPCAT_BOOTMAIN 层级错误

• 🐛 根因：launcher 的 loadNapCat.js 加载 ${NAPCAT_BOOTMAIN}/napcat.mjs，但服务把 NAPCAT_BOOTMAIN 指向了 launcher 目录（~/.dsh/napcat-linux）——实际 napcat.mjs 在 napcat/ 子目录（符号链接）里 → ERR_MODULE_NOT_FOUND
• 🔧 修复：NAPCAT_BOOTMAIN 与 WorkingDirectory 直接指向 NapCat 实际根目录（~/.dsh/napcat），LD_PRELOAD 仍指向 launcher 的 so
• 🧪 e2e 扩至 26 用例（BOOTMAIN/WorkingDirectory 指向安装目录）

v0.3.13（2026-08-16）—— 二维码过期自动刷新（不再显示死码）

• 🐛 根因：二维码约 2 分钟有效，但插件 10 分钟内都视为"新鲜"——过期旧码一直显示，扫码提示失效
• 🔧 新鲜窗口收紧：文件模式 10 分钟 → 3 分钟；过期时自动调用 NapCat WebUI RefreshQRcode 强制换新码
• 🔧 死码清理：连续 6 分钟未更新的二维码文件自动删除（UI 明确进入等待，NapCat 刷新后重写）
• 🔧 WebUI URL 陈旧检测：取到的二维码 URL 超过 2.5 分钟自动 Refresh 重取（不再长期显示内存缓存的旧码）
• 🔧 修复 status 400（findStaleQrcode 作用域错误）
• 🧪 e2e 25 用例保持全过

v0.3.12（2026-08-16）—— Linux 引导修复：NapCat 经 launcher 注入 QQ 宿主

• 🐛 根因：NapCat.Shell 在 Linux 上不是独立程序，node napcat.mjs 直启会失败（--no-sandbox 传给 node / 找不到 QQ 资源）
• 🔧 Linux launcher 模式：引导自动下载官方预编译 libnapcat_launcher.so（按架构）→ 建立 ~/.dsh/napcat-linux/（含 napcat 符号链接）→ 服务改为 LD_PRELOAD=launcher /opt/QQ/qq --no-sandbox + NAPCAT_BOOTMAIN
• ✨ Linux 下无需填写 QQ 号：QQ 内核随宿主启动即进入登录流程，二维码直接生成
• ❌ 找不到 Linux QQ（/opt/QQ/qq）时明确报错并提示安装（不再用 node 硬启）
• 🧪 e2e 扩至 25 用例（launcher 模板/宿主/LD_PRELOAD）

v0.3.11（2026-08-16）—— 修复 QQ 号保存失效

• 🐛 根因：设置页保存按钮在镜像列表未加载完时，URL 计算出空值直接 return——QQ 号根本没提交（静默丢弃）
• 🔧 修复：URL 为空时回退到服务端当前值；QQ 号始终随保存提交；后端空 URL 不再报错（仅保存 QQ 号）
• 🔍 引导验证步骤：引导完成后输出服务实际 ExecStart 命令（一眼确认 -q <QQ号> 是否写入）

v0.3.10（2026-08-16）—— 白名单保存失败提示 + 引导可重复应用

• 🔧 白名单保存不再静默失败：写入 ~/.dsh/qq-remote.json 失败时前端显示真实错误（此前显示"已保存"但刷新后丢失）
• 🔧 引导按钮常驻：未登录时始终显示「NapCat 引导」区块（QQ 号/下载源/引导按钮），服务已启动时按钮变为「重新应用 NapCat 服务（修复）」
• 🔧 服务可重写：引导发现托管服务（dsh-napcat.service）的 unit 与期望不一致（如补上 -q QQ号）时自动重写并重启——填了 QQ 号后重新引导即可生效，无需手动改服务

v0.3.9（2026-08-16）—— 修复引导后无二维码（NapCat 需要 -q 登录）

• 🔧 根因：NapCat.Shell 不带 -q <QQ号> 启动时只跑 WebUI 模式，不会生成登录二维码
• ✨ 设置面板新增「机器人 QQ 号」输入：引导安装时自动写入服务启动参数 -q <QQ号>（快速登录/二维码），保存到 ~/.dsh/qq-remote.json（napcatQQ）
• 🧭 探测路径补全：WebUI 配置与二维码文件探测加入引导安装目录 ~/.dsh/napcat（此前引导装到哪就探测不到哪）
• 🔔 未配置 QQ 号时引导会明确提示"请填写机器人 QQ 号后重新引导"

v0.3.6（2026-08-16）—— 设置面板可配置 NapCat 下载源

• ⬇️ 下载源可选项：设置页「QQ 远程」面板新增「NapCat 下载源」—— 官方 GitHub / gh-proxy.com 镜像 / ghfast.top 镜像 / 自定义地址，一键切换并保存（写入 ~/.dsh/qq-remote.json 即时生效）
• 🔧 后端 GET/POST /qq-remote/napcat/settings：镜像列表单一事实源，支持自定义 URL 校验（http/https/file）
• 🧪 e2e 21 用例保持全过

v0.3.5（2026-08-16）—— 引导下载体验：实时进度 + 镜像支持

• ⚡ 实时下载进度：引导面板显示「下载中 xMB / 29MB（x%）」，不再干等
• ⏱️ 下载超时放宽：5 分钟 → 15 分钟（慢网络友好）
• 🔗 可配置下载源：新增 napcatDownloadUrl（默认官方 GitHub Release，可换镜像或本地文件路径）；手动预下载 ~/.dsh/NapCat.Shell.zip 自动跳过下载
• 🧪 e2e 21 用例保持全过

v0.3.4（2026-08-16）—— 修复"一键安装 NapCat"按钮消失

• 🐛 按钮消失根因：NapCat 的 systemd unit 存在但未运行（inactive，如引导注册过服务或残留 unit）时，被误判为"服务存在"→ 二维码原因变成 webui_not_found/waiting → 引导按钮隐藏
• 🔧 修正语义：napcat_not_running 现在严格按"服务正在运行"判断（unit 不存在或 inactive 都显示引导按钮）；/qq-remote/status 新增 napcatActive 字段区分"服务存在"与"正在运行"
• ❌ relogin 同步：服务 inactive 时也返回真实错误（含修复指引）
• 🧪 e2e 扩至 20 用例（含"unit 存在但 inactive → 显示引导按钮"场景）

v0.3.3（2026-08-16）—— 引导修复：dirname bug + 防双实例顶号

• 🐛 修复引导崩溃：Cannot read properties of undefined (reading 'dirname') —— os.path.dirname 误用修正为 path.dirname
• 🛡️ 防双实例顶号：bootstrap 前检查已有活跃 NapCat 服务 / OneBot 连接，存在则跳过并提示（不再出现"两个 NapCat 抢同一 QQ 账号互相顶下线"）
• 🔒 安装目录排他：配置 napcatInstallDir 时只信任配置值，不再扫描其他候选
• 🧪 e2e 扩至 19 用例（防顶号跳过、下载失败结构化错误路径）

v0.3.2（2026-08-16）—— 开箱即用：NapCat 引导 + 二维码诊断

• 🧩 一键安装 NapCat：面板新增「一键安装/启动 NapCat」—— 自动下载官方 NapCat.Shell → 解压 → 幂等写入 OneBot11 反向 WS 配置（3001）→ 注册 systemd 用户服务 dsh-napcat.service → 启动 → 二维码自动出现，扫码即登录
• 🔍 二维码诊断分级：/qq-remote/status 现在区分 napcat_not_running / webui_not_found / stale_qrcode / waiting，设置页与完整面板直接显示原因，不再无限"等待"
• ❌ 重新登录不再假装成功：NapCat 服务缺失时返回真实错误（含修复指引），前端恢复按钮并显示原因
• ⚡ 轮询优化：QR 获取 5s 结果缓存 + WebUI 失败 10s 退避（避免登录限流）
• 🧭 探测增强：/proc/<pid>/cwd 与 NAPCAT_WORKDIR 反推 NapCat 工作目录；~/.config/napcat 等路径补充
• 🧪 e2e 回归扩至 16 用例（含四类 qrReason 诊断场景）

v0.3.1（2026-08-16）—— 对齐插件市场 STANDARD 规范

• ✅ 修正市场类型判定：安装脚本移入 scripts/ 子目录 —— 根目录不再有 install.sh，市场正确识别为 cordis-plugin（此前会被误判为「脚本型」，跳过构建/依赖/注册/更新/卸载全管线）
• 📦 改为产物型：提交 lib/ 构建产物，市场安装无需构建弹窗、直接复制使用
• 📝 package.json 完善：main / repository / files（含 scripts）对齐规范；npm 包名唯一性已确认
• 🛠️ 安装命令更新：bash scripts/install.sh（卸载 bash scripts/uninstall.sh，诊断 bash scripts/repair.sh）

v0.3.0（2026-08-16）—— 模块化重构 + 彻底卸载

• 🧱 代码重构：单文件（1700+ 行）拆分为模块化结构 —— index.js（装配）+ util/onebot/chat/commands/panel/qrgen 六模块，行为完全一致（本机全量回归：消息链路 9/9、面板路由、QR 生成器交叉验证）
• 🗑️ 彻底卸载：uninstall.sh 增强 —— 移除 patch 条目 + 删除安装目录（含 junction）+ 清理注入器 registry + 清理 profile package.json 残留（dependencies/bundles）；bash uninstall.sh --purge 可连配置与聊天记忆一起删除
• 🧪 回归测试入库：test/e2e.mjs 一键跑消息链路 + QR 生成器验证（cd test && node e2e.mjs）
• 🩺 保留 v0.2.4 的 install.sh 自愈能力（写前备份、disabled 自动启用、安装后结构检查）

v0.2.4（2026-08-16）—— 重装自愈 + 诊断工具

• 🔧 重装自动启用：若 patch 中残留 disabled: true 的旧条目（卸载残留），重新安装时自动移除 disabled 恢复启用
• 🔧 写前备份：install.sh 修改 cordis.patch.yml 前自动备份为 cordis.patch.yml.bak-install，任何意外可一键回滚
• 🩺 新增 repair.sh 诊断工具：列出 patch 全部插件条目、检测旧版 install.sh 造成的残缺结构（子行被删）、提示皮肤类条目是否缺失、发现备份文件时给出恢复命令；安装完成时自动运行检查
• 📦 repair.sh 随包分发（安装目录与 tgz 均包含）

v0.2.3（2026-08-16）—— 修复皮肤插件失效 + 二维码自动获取

• 🐛 修复安装后其他插件（如皮肤 UI）失效：install.sh 不再对已有 patch 条目做任何清理/重排（旧逻辑会误删其他插件的嵌套配置），只做幂等追加
• ✨ 二维码自动获取：面板不再依赖猜测 NapCat 安装路径 —— 自动读取 NapCat WebUI 配置（webui.json）调用 GetQQLoginQrcode API 主动获取二维码并本地生成 PNG（内置零依赖 QR 生成器）；Docker / 自定义目录 / 任意安装方式都能显示二维码
• 🧭 二维码候选路径扩展：NapCat.Shell、Installer、.config/QQ/NapCat、macOS 路径、systemd NAPCAT_WORKDIR 反推全覆盖
• 🔧 新增 webuiPort / webuiToken 配置项（默认自动探测，一般无需配置）

v0.2.2（2026-08-16）—— 安装可靠性 + 面板路由 + 白名单

• 🐛 修复面板路由不注册：注册条目补 inject: [webServer, tools]（cordis.patch.yml / install.sh 模板）；插件代码增加 webServer 未就绪的延迟重试 + 防重复注册 —— 通过 dsh plugin 官方安装后 /qq-remote/* 路由必定注册
• ✨ 设置页新增白名单管理：「QQ 远程」面板可增删控制白名单（QQ 号）并保存到 ~/.dsh/qq-remote.json，即时生效

安装/卸载

• 🔧 YAML-aware patch 写入：正确处理空模板 []、精确幂等匹配、原子替换（临时文件+rename）
• 🔧 client 路径统一：exports["./client"] 指向 lib/client.js（唯一路径），安装后强制校验存在
• 🔧 新增 dsh.bundle.patch 声明：支持 dsh plugin 官方安装流程（profile bundle 装配）
• 🔧 依赖版本从当前 DSH 运行时探测（不再猜 npx 缓存 / 硬编码漂移）
• 🔧 新增 uninstall.sh：移除 patch 条目 + 删除安装目录 + 清理注入器 registry（防重启复活）
• 🔧 平台表述修正：明确 Linux/macOS（Windows 需 WSL 或 Git Bash）
• 🐛 修复残留空 - insert: 块：重复安装后 patch 文件保持干净（幂等且不留垃圾行）

体验

• 🐛 面板容错：服务未就绪时显示友好提示并自动重试（不再报 JSON.parse 原始错误）
• 🐛 修复设置面板偶发整体消失：面板状态改为增量合并，白名单/输入框内容不再被覆盖丢失
• 🐛 登录失效时新增"等待二维码"提示文案；二维码候选路径扩展到更多常见 NapCat 安装位置
• 🎭 默认聊天人设改为中性"聊天格式"预设（不定义角色，角色可自由配置）

v0.2.0（2026-08-15）

新功能

• 🖥️ QQ 图形开关：DSH 设置页新增「QQ 远程」面板（Web UI 设置 → QQ 远程）—— 实时显示插件/登录状态，一键重新登录，登录失效时自动弹出二维码（手机扫码即登）
• 🎛️ 控制面板页面：http://127.0.0.1:3080/qq-remote/panel（完整面板，/panel 命令可获取链接）
• ⚡ 指令缩写：长命令新增等效缩写（原命令不变）—— /st /ss /s /ns /cb /pg /sc /q /x /run /task /h /pn，/help 查看对照
• 💬 聊天模式增强：多聊天会话（/chat <名字>）、记忆持久化（~/.dsh/qq-remote-chats/）、上下文无限制
• 💗 聊天特化会话（/chatbind）：指定会话直接聊天回复，其他会话不受影响
• 📋 会话标题化：/sessions 显示标题，/session <序号|标题|id> 切换，/title 重命名，/newsession 新建
• 📦 一键安装脚本 install.sh

Bug 修复

• 🐛 聊天模式第二轮崩溃（reading 'kind'）：消息缺少 source 字段导致 LLM 管道报错
• 🐛 /newsession 创建的会话随插件重载消失：改为根上下文创建，生命周期独立
• 🐛 重启后 QQ 连接不自动恢复：看门狗增加 CONNECTING 卡死判定（15 秒未连接强制重建）
• 🐛 语音/图片消息无响应：改为友好提示"请用文字发送"
• 🐛 会话标题显示 [object Object]：正确读取标题对象
• 🐛 设置页空白（locale.t is not a function）：改用新版 locale API（ctx.locale.bind）

平台

• Linux 完整支持；macOS/Windows 核心功能可用（详见"环境要求"）

v0.1.0（2026-08-15）

• 首个开源版本：OneBot 11 桥接、/exec、/ask、阶段进度汇报、截图回传、qq_report/qq_screenshot 工具、零 npm 依赖