dsh-QQbot：接入 QQ 官方機器人

前言¶

DeepSeek Harness（DSH）的核心設計理念是「一切皆插件」，通過插件化擴展能力來構建本地智能體環境。接入 QQ 官方機器人通常涉及複雜的 WebSocket 連接維護和回調配置，普通開發者難以直接維護。dsh-QQbot 插件封裝了官方 SDK 的連接邏輯，將其接入本機 DSH，從而讓 AI 能夠直接在 QQ 羣聊或單聊中工作。

是什麼¶

dsh-QQbot 是一個客戶端插件，由 master1Sun 維護。它利用 QQ 官方機器人的 WebSocket 長連接模式，將消息流轉發到本地 DSH 的會話中。通過 DSH 的 AI 能力處理後，回覆再由插件分發回 QQ。該插件支持多機器人獨立運行、免公網接入以及豐富的消息處理功能。

核心功能¶

多機器人：通過 bots.json 作爲唯一事實來源管理機器人。每個機器人擁有獨立的憑據和配置，可同時在線，所有回覆均由來源機器人發出。
免公網接入：利用官方 SDK 主動外連 QQ 網關的特性，插件本身無需公網 IP、域名或回調配置即可運行。
消息響應：
- 羣聊：@ 機器人直接回復（附帶最近 10 條上下文）；未 @ 消息經價值評分過濾後才插話。
- 單聊：直接建立會話。
會話與記憶：同一羣聊或單聊複用會話，支持 /new 重開會話、/記憶 和 /清空記憶 進行長期記憶管理。
多模態與語音：支持圖片、文件、語音入上下文；語音轉寫支持五檔；支持 TTS 語音回覆和「正在輸入」狀態。
定時消息：支持 /定時 命令，調度精度約 30 秒。支持每天定時、間隔重複以及 AI 現場生成內容的 mode=ai 模式。
羣管理：內置敏感詞撤回、/廣播、入羣歡迎語、表情撤回以及敏感操作審批功能。
AI 工具：提供 qqbot_schedule_*、qqbot_send_message、qqbot_memory_* 等工具函數，允許在對話中直接調用這些能力。
安全與可靠：包含回覆淨化、媒體 SSRF 防護、本地路徑白名單、主動消息每日配額控制以及消息本地歸檔。
設置界面：集成在 DSH 的設置頁面中，支持掃碼或手動添加機器人，行爲配置熱生效。

安裝與啓用¶

插件需要安裝在 DSH 的特定配置文件（profile）中。確保你在正確的 profile 目錄下執行安裝命令。

dsh plugin --profile web add <本目錄或 git 地址>

安裝完成後，插件依賴 @deepseek-ai/dsh-webhook 提供的 ctx.webhookRuntime。若該依賴不可用，插件會降級運行（不創建會話），此時可通過設置頁與 /status 查看狀態。

典型用法¶

準備環境：在 QQ 開放平臺創建機器人，獲取 appId 和 appSecret。配置出口 IP 白名單，並將羣設置中的「可獲取的羣聊消息範圍」設爲全部。
添加機器人：打開 DSH 設置，進入「QQ 機器人」頁面。通過掃碼或手動填寫信息添加機器人，保存後立即生效。
開始交互：將機器人拉入羣聊或添加爲好友。直接 @ 它說話，或在私聊中對話即可。

已知邊界¶

定時消息精度：調度精度爲 30 秒，且僅在進程運行時觸發，進程停止時不會觸發。
羣聊回覆限制：被動回覆窗口限制爲 5 分鐘 / 5 次。對於超長任務，可能導致發送失敗（可開啓 proactiveFallback 消耗主動配額）。
上下文限制：羣聊歷史上下文只回放文本內容，不包含歷史附件中的圖片或文件。
進程可靠性：webhookRuntime 採用進程內 fire-and-forget 模式。若 DSH 進程崩潰，未入會話的消息會丟失。

結語¶

該插件適合需要在本地運行 DSH 並希望直接在 QQ 生態中使用的開發者。安裝前建議檢查源碼與許可證（MIT）。更多配置細節請參考 GitHub 倉庫。