前言¶
在 DeepSeek Harness（DSH）里做智能体开发时，常会遇到需要离开本机但仍希望查看 agent 状态、派发任务、执行命令、收取截图的情况。已有做法通常依赖本机终端或面板访问，dsh-qq-remote 提供了另一种入口：通过 QQ 消息向 DSH 发送命令，再经 OneBot 11 桥接到插件。下面介绍它的定位、环境要求、安装配置和典型用法。
定位¶
dsh-qq-remote 是一个 DSH 插件，仓库地址为 https://github.com/ASAKAFENG/dsh-qq-remote，许可证为 MIT。它通过 QQ 消息实现远程控制，主要包括：
- 执行 shell 命令并回传输出：
/exec - 派发任务到当前 DSH agent 会话：
/ask - 查看 agent 状态与最近进度：
/status、/progress - 阶段汇报与自动进度推送：
phase模式 - 会话标题化管理：
/sessions、/session、/title、/newsession - AI 聊天模式与聊天特化会话：
/chat、/chatbind - 取消任务：
/cancel - 截图回传：
/screenshot - Agent 主动向 QQ 发送文本或截图：
qq_report、qq_screenshot - QQ 图形控制面板与扫码登录恢复：
/panel
它不包含 QQ 协议实现，需要 NapCat、Lagrange.OneBot、go-cqhttp 或 LLOneBot 等 OneBot 11 实现作为 QQ 桥。
环境要求¶
插件要求如下：
- Node.js
>= 22，使用内置 WebSocket / fetch，零 npm 依赖 - 宿主为 DSH 环境，提供
@deepseek-ai/*peer 依赖 - 任一 OneBot 11 实现：NapCat、Lagrange.OneBot、go-cqhttp、LLOneBot
- 平台：Linux 完整支持；macOS / Windows 核心功能可用；已在 Ubuntu 环境验证安装通过
安装与启用¶
先准备 QQ 桥。以 NapCat 为例：
1、安装并启动 NapCat，完成机器人 QQ 扫码登录。
2、在 NapCat WebUI 新增 WebSocket 服务端：
127.0.0.1:3001
路径：/ws
消息格式：array
3、克隆插件并运行安装脚本：
git clone https://github.com/ASAKAFENG/dsh-qq-remote
cd dsh-qq-remote
bash scripts/install.sh
4、配置白名单。可在 DSH 设置页「QQ 远程」面板添加自己的 QQ 号，也可以编辑 ~/.dsh/qq-remote.json 中的 allowedUsers。
5、用 QQ 发送 /ping，收到 pong 即表示连通。
经过上面的步骤后，可以先用以下命令验证基本链路：
/ask 帮我整理桌面文件
/exec ls -la
/screenshot
白名单与配置¶
allowedUsers 是必须认真配置的项目。如果 allowedUsers 留空，任何 QQ 号都能控制你的电脑。
覆盖层配置文件路径为：
~/.dsh/qq-remote.json
已核实资料给出的配置字段示例包括：
{
"wsUrl": "ws://127.0.0.1:3001/ws",
"allowedUsers": [123456789],
"groupPrefix": "/",
"privatePlainAsTask": true,
"autoReport": true,
"reportMode": "phase",
"chatHistoryLimit": 0,
"chatMaxChars": 0,
"chatSessionNames": []
}
其中 allowedUsers 里的默认示例 [123456789] 会放行任意消息，务必替换成你自己的 QQ 号。reportMode 可用于 phase 模式。完整配置项见 USAGE.md。
常用命令¶
下面列出已核实的常用命令：
/ping：连通性测试，回复pong即成功/ask <任务>：派发任务到当前 DSH agent 会话/exec <命令>：在电脑上执行 shell 命令并回传输出/status：查看 agent 状态/progress：查看最近进度/screenshot：截图并发送/cancel：取消当前任务/sessions：列出会话/session <标题或id>：切换目标会话/title <名称>：给当前目标会话重命名/newsession：新建会话/chat on：开启 AI 聊天模式/chat off：退出 AI 聊天模式/chatbind on：开启聊天特化会话/chatbind off：退出聊天特化会话/panel：打开 QQ 图形控制面板
阶段汇报与主动发送¶
插件支持 phase 模式，用于阶段汇报与自动进度推送。Agent 也可以在会话中主动调用 qq_report、qq_screenshot 向 QQ 发送文本或截图。
登录失效恢复¶
登录失效时，可使用 /panel 打开 QQ 图形控制面板。二维码约 2 分钟有效，失效后可自动刷新或重新扫码恢复。
安全与适用场景¶
这个插件的权限较高：它可以通过 QQ 远程执行命令、截图、查看文件。由于它依赖 DSH 进程执行本机能力，权限取决于当前 DSH 进程和系统环境，应作为高权限工具对待。
使用前建议：
1、必须配置 allowedUsers 白名单。
2、强烈建议使用小号或专用机器人 QQ，避免主号被风控或封号。
3、安装前检查源码，并确认 MIT 许可证符合你的使用要求。
它适合以下场景：
- 出门在外时，通过 QQ 查看 DSH agent 状态和最近进度
- 需要在手机上派发任务、执行命令、取消任务
- 需要接收屏幕截图
- 需要通过 QQ 进行 AI 聊天或切换会话
- 已有 NapCat 或其他 OneBot 11 实现作为 QQ 桥
结尾¶
dsh-qq-remote 把 DSH 的远程操作收敛到 QQ 消息链路中，适合作为个人开发机上的远程控制入口。由于它能执行命令和截图，务必先配置白名单，再使用小号进行测试。
