前言¶
在 DSH 裏做智能體時，常見做法是自己接 OneBot 協議、再寫一堆工具讓助手查羣、發消息、讀媒體。協議地址、Token、羣白名單和視覺開關往往散落在配置文件或腳本里，運維和試聊也要換好幾個界面。下面介紹社區插件 dsh-qq（維護者 oka-rin，分類爲客戶端）：它把 QQ 對話、媒體理解、DSH 內操作 QQ，以及在線狀態與配置面板收進一個插件，並支持 NapCat、SnowLuma 與通用 OneBot 後端接入。
這是什麼¶
dsh-qq 是面向 DeepSeek Harness 的 QQ 機器人集成插件。源碼在 GitHub：oka-rin/dsh-qq，社區目錄頁爲 skillhub.cn/plugins/oka-rin/dsh-qq。插件描述爲： bundled bot、NapCat/SnowLuma/OneBot 連接、控制面板與 QQ 相關工具；網關後端由外部自行部署，插件不捆綁鏡像、不隱式安裝後端。
運行環境要求 DSH 與 Node.js 22.13 或更新版本（見 package.json 中 engines.node）。當前資料中的版本號爲 0.8.0，許可證爲 MIT。
核心功能¶
README 中的能力表與說明可覈對如下要點。
QQ 對話：羣內 @ 機器人、引用其消息，或私聊；新安裝默認不開口，需在配置中開啓聊天，並按需開啓私聊與羣範圍（羣白名單留空表示不限制羣）。
圖片、動圖、視頻：發給機器人讓其理解內容；可展開合併轉發裏的聊天和媒體。圖片需要支持視覺的模型；動圖與視頻還需要主機上的 ffmpeg / ffprobe；相關開關新安裝默認關閉。
在 DSH 裏操作 QQ：通過自然語言讓助手發消息、查羣成員、找歷史聊天、查看人物檔案等（README 稱插件內提供多類工具，具體以安裝後助手可用能力爲準）。
統一面板：在 DSH 設置 → QQ 機器人 查看在線狀態、會話和日誌，修改配置，開關自動聊天；支持打開 QQ 登錄頁人工登錄（SnowLuma Docker 的 noVNC、NapCat WebUI 等流程見官方文檔）。
按需擴展：表情包、生圖、學習、資訊分享、QQ 空間與羣管理等；部分擴展取決於後端權限和外部服務。
後端與部署：可填寫已有 OneBot HTTP / WebSocket 與 Token；無後端時可在 接入與部署 使用 一鍵部署 SnowLuma（Linux / Windows 宿主，依賴 Docker 等條件見 docker 文檔）。NapCat 接入見 napcat.md。高級項見 advanced.md。
安裝與啓用¶
1、準備環境¶
- 已安裝並運行 DSH，Node.js ≥ 22.13。
- 準備 NapCat / SnowLuma / OneBot 後端的 HTTP 地址、正向 WebSocket 地址和 Token（或安裝後按嚮導一鍵部署 SnowLuma）。
- 準備 OpenAI 兼容 的模型接口地址、模型名與 API Key。
2、安裝插件¶
安裝來源爲該 GitHub 倉庫，不是 npm 上的同名包。在 DSH 對話裏把下面這句話發給助手即可：
幫我從 https://github.com/oka-rin/dsh-qq 安裝這個插件。
也可下載源碼，在 DSH 插件管理器中用本地目錄安裝。
3、連接 QQ 與模型¶
打開 DSH 設置 → QQ 機器人 → 接入與部署。若使用一鍵部署，需按 SnowLuma 原版流程在網頁登錄 QQ、審閱條款並配置網關 hook，再檢測連接；新建部署僅保存本機 OneBot 接入信息，不代表已在線。
已有後端可直接填寫（端口以你的後端爲準）：
| 填什麼 | 示例 |
|---|---|
| OneBot HTTP 地址 | http://127.0.0.1:3000 |
| OneBot WebSocket 地址 | ws://127.0.0.1:3001/event |
| OneBot Token | 後端設置的令牌，不是 QQ 密碼 |
| 模型接口 / 模型名 / API Key | 模型服務提供的內容 |
點擊 檢測 OneBot 連接，成功後保存，再到「運維」重啓機器人。連接檢查通過只代表 QQ 側可達，模型是否可用需試聊確認。
NapCat 未登錄時，可在插件配置選擇 gatewayBackend: napcat，按 README 複製登錄令牌並在官方 WebUI 掃碼；不要將令牌或密碼發到聊天。
4、開啓聊天並試一條¶
在配置中開啓聊天；羣聊需填寫允許的羣后再啓用。在 QQ 私聊或在允許羣裏 @ 機器人發「你好」。收到回覆後，再按需打開視覺、動圖、視頻與轉發展開開關並試發對應消息。
典型用法¶
裝好後在 DSH 對話裏直接用自然語言即可，無需記憶工具名。README 給出的示例包括：
- 「看看 QQ 機器人在線沒有。」
- 「列出機器人加入的羣。」
- 「看看這個羣最近在聊什麼。」
- 「查一下之前聊過的視頻。」
- 「給這個羣發一條消息：今晚八點開始。」（需指定目標羣）
- 「爲什麼機器人剛纔沒回復？」
適用場景與注意¶
適合誰：已在用或計劃用 DSH 做助手，並希望 QQ 作爲客戶端通道，同時在 DSH 內完成接入檢測、運維與部分羣管/檔案操作的用戶。
連接通過但不回覆：檢查聊天開關、私聊開關與羣範圍；連接成功不會自動開啓發言。
已有 Docker 版 SnowLuma：可繼續連接原實例；遷移到原生需按文檔備份與人工掃碼，安裝腳本不會停止容器或複製登錄態。
數據與更新：配置、聊天歸檔與學習數據在獨立 dataDir，不在插件代碼目錄；更新前備份並沿用同一 dataDir，避免另開實例導致記錄割裂。
安全與權限：插件以當前 DSH 進程權限運行；安裝前應閱讀源碼與 MIT 許可證，並理解 OneBot Token、VNC 密碼與 API Key 的保管方式。社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；NapCat、SnowLuma、QQ 與模型服務各遵循其自身條款。
結尾¶
dsh-qq 把 QQ 聊天、媒體理解、助手側 QQ 工具與設置面板集中在 DSH 插件內，並對接 NapCat、SnowLuma 與 OneBot。按 README 安裝、接好後端、開啓聊天即可在 QQ 與 DSH 兩側聯調。
- 目錄頁：https://www.skillhub.cn/plugins/oka-rin/dsh-qq
- 源碼與文檔：https://github.com/oka-rin/dsh-qq
