前言¶
在 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 消息鏈路中，適合作爲個人開發機上的遠程控制入口。由於它能執行命令和截圖，務必先配置白名單，再使用小號進行測試。
