前言¶
DeepSeek Harness（DSH）支持通過 QQ 頻道作爲遠程入口，上游 dsh-qq-plugin 提供了私聊遙控、掃碼綁定、多會話、附件與審批迴流等能力。但原插件沒有羣聊支持，在 QQ 羣裏只能被動接收消息，無法主動應答或參與羣內討論。
dsh-qq-plugin-group-expand 是對上游項目的擴展分支，補上了羣聊收發、羣聊禮儀、引用圖片、表情包收藏、權限默認值與 token 優化。項目基於官方 QQ 機器人平臺，不需要個人號協議，也不依賴公網 IP。
插件定位¶
- 包名：
dsh-qq-plugin-group-expand - 版本：1.2.0
- 運行環境：DSH desktop 0.2.0-rc.2 或更新
- QQ 側：騰訊官方機器人，通過手機 QQ 掃碼創建
核心能力¶
與上游的關係¶
上游 dsh-qq-plugin 提供的能力在 dsh-qq-plugin-group-expand 中全部繼承：
- 私聊遙控、掃碼綁定、多會話（
/new/list/switch） - 圖片 / 文件 / 語音雙向
- 權限審批迴流、
notify_qq主動推送 - 語音優先使用 QQ 服務端 ASR 轉寫
本分支新增的能力：
- 羣聊收發：支持在 QQ 羣裏與 agent 交互
- 羣聊禮儀與門禁：只在特定條件（被 @、提到人格名或關鍵詞）下發言
- 連續對話窗口：被 @ 後 5 分鐘內，每條文字消息都交給 agent 判斷是否回應
- 引用圖片：下載引用消息中的圖片到本地，把絕對路徑交給 agent
- 表情包收藏：自動收集羣裏的方形小圖，支持用戶導入，最多 300 張
- 權限默認值：新會話默認
read-only，強制鎖定只讀 - Token 優化：
presenceNote（渠道上下文說明）只在每個新對話的第一條提示詞裏發送一次
安裝¶
從 npm 安裝（推薦）¶
dsh plugin --profile desktop add dsh-qq-plugin-group-expand
也可以在 DSH 的「添加插件」裏直接輸入包名：
dsh-qq-plugin-group-expand
從 GitHub 安裝¶
dsh plugin --profile web add https://github.com/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
或者把 Git 地址粘進「添加插件」。
從本地目錄 / tarball¶
npm pack
生成 dsh-qq-plugin-group-expand-1.2.0.tgz 後，把 .tgz 的絕對路徑或放着 package.json 的目錄粘進「添加插件」。
從舊插件遷移¶
- 先在 DSH 裏停用並移除原來的
dsh-qq-plugin，否則兩個插件會搶同一個 QQ 通道和qqChannel服務 - 安裝
dsh-qq-plugin-group-expand - 憑據作用域沿用上游的
dsh-qq-plugin，已綁定過的 AppSecret 可以直接複用 - 狀態文件仍是
~/.dsh/qq/state.json，會話映射、待發隊列和設置會繼續生效 - 啓動後檢查設置頁的連接狀態和
boot.log
羣聊行爲與禮儀¶
羣聊和私聊的禮貌規則不同。本分支默認只在以下情況發言：
| 條件 | 行爲 |
|---|---|
| 被 @ | 立即交給 agent，正常回答 |
| 被 @ 後 5 分鐘內 | 每條文字消息都交給 agent，由模型判斷是否回應 |
| 正文提到人格名或接話關鍵詞 | 本地短句 + 表情包接一句，不調用模型 |
| 其他 | 不發言 |
被 @ 後會開啓一個 5 分鐘的連續對話窗口。窗口內不按關鍵詞過濾：消息會原樣交給 agent，並在提示詞裏附上最近 8 條羣消息（發送者 + 正文，單條截斷 120 字）。如果 agent 輸出 [[NO_REPLY]]，插件會把整條回覆丟棄，羣裏一個字都不發。
表情包與引用圖片¶
表情包¶
不生成表情包，只用兩種來源：
- 羣裏像表情包的方形小圖，收到時靜默下載到
~/.dsh/qq/stickers/collected/ - 用戶自己導入到
~/.dsh/qq/stickers/根目錄的png/jpg/gif/webp
收藏判定條件：
- 最長邊 ≤ 1024
- 寬高比 0.45–2.2
- 文件 ≤ 2 MiB
- SHA-256 去重
- 最多 300 張
索引寫 index.json。手機照片和截圖會被排除。發送失敗或目錄爲空時退到 emoji，不影響文字回覆。
引用圖片¶
QQ 把被引消息的圖片放在 msg_elements[<refMsgIdx>].attachments。本分支會把引用附件下載到會話媒體目錄，把本地絕對路徑交給 agent，而不是隻寫一句「（引用了 image/png）」。
權限與安全¶
新會話默認 read-only：
permissionPreset默認值改爲read-onlynewSessionsReadOnly默認開啓，新建/採納的會話會被強制施加只讀，即使狀態文件裏存着舊的danger-full-access- 已有會話的權限由 DSH 鎖定，插件不會偷偷改
要讓某條新會話動手，需要先關閉只讀鎖，再選擇「工作區可寫」或「完全訪問」。這是有意的摩擦：羣裏任何人都能觸發它，默認不能寫文件。
配置¶
設置項與上游一致，羣聊新增字段主要在 lib/settings.js：
| 設置 | 默認 | 說明 |
|---|---|---|
groupChatEnabled |
true |
羣聊總開關 |
groupPersonaNames |
鯨魚娘 |
羣裏認的人格名，逗號分隔 |
groupAutoSpeak |
true |
提到人格/關鍵詞時自動接話 |
groupFollowUpWindowMs |
300000 |
被 @ 後的連續對話窗口（5 分鐘） |
groupContextWindowMs |
120000 |
羣歷史語境窗口 |
groupAutoSpeakKeywords |
鯨魚娘,魚魚,胖魚,在嗎,哈哈,笑死,可愛,笨蛋 |
接話關鍵詞 |
groupSpeakCooldownMs |
20000 |
自動接話冷卻 |
groupSpeakMaxPerHour |
20 |
自動接話每小時上限 |
groupCollectStickers |
true |
收藏羣裏的表情包 |
groupStickerChance |
70 |
接話時附帶表情包的概率 |
groupStickerDir |
<home>/qq/stickers |
表情包目錄 |
groupFullMessageMode |
未啓用 | 平臺推送全量羣消息時纔有的分支 |
permissionPreset |
read-only |
新會話權限預設 |
newSessionsReadOnly |
true |
新會話強制只讀鎖 |
完整說明見 docs/HANDBOOK-USER.md 和設置頁內置幫助。
適用場景與注意¶
適合需要通過 QQ 羣與 DSH 智能體交互的場景，例如：
- 羣內日常問答與協作
- 羣聊中的任務審批與決策
- 通過羣聊分享圖片、文件與語音
注意：
- 插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證
- 官方通道下，非 @ 的羣消息默認不可見；需要平臺權限，插件無法繞過
sendTyping僅支持單聊，羣聊裏會記錄一條非致命錯誤- 羣歷史在內存中，DSH 重啓後從零開始
- 表情包只支持圖片，不支持羣裏的動態表情協議
結尾¶
dsh-qq-plugin-group-expand 在上游 dsh-qq-plugin 的基礎上補齊了羣聊能力，通過官方 QQ 機器人平臺提供了更安全的默認權限和 token 優化，適合需要在 QQ 羣裏遠程控制 DSH 的場景。
- 目錄頁：https://www.skillhub.cn/plugins/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
- GitHub：https://github.com/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
