Derpyu520/qq-bridge

解決的問題

本專案將 QQ 訊息系統與 DeepSeek Harness (DSH) 代理框架相連接，讓使用者能透過 QQ 個人訊息或群組聊天與 AI 代理互動。它將 QQ 訊息轉換為 DSH 會話，並把代理的回覆、問題與工具授權結果回傳給 QQ 使用者。

工作原理

此橋接器作為 SnowLuma（OneBot v11 WebSocket 客戶端）與 DSH Web API 之間的中介。它將每個 QQ 聊天（個人或群組）映射至專用「QQ 聊天」工作區內的唯一 DSH 會話。

主要技術元件包括：

• 通訊：使用 WebSocket 透過 SnowLuma 連接 QQ，並使用 REST/Event-stream API 與 DSH 通訊。
• MCP 整合：整合 Model Context Protocol (MCP) 伺服器，為代理提供安全功能，例如發送訊息、檢查群組狀態，以及具 SSRF 保護的網路搜尋。
• 運作模式：支援多種模式，包括 chat（標準安全聊天）、closed-agent（僅所有者擁有完整工具存取權限）、reserved（透過狀態機模擬群組成員行為，支援活躍與靜默狀態）。
• 互動邏輯：處理複雜的 QQ 互動，如訊息引用（回覆）、斜線指令（例如 /reset），以及為模擬角色拆分多段訊息。

適用對象

• 希望將 AI 代理引入 QQ 的 DeepSeek Harness 使用者。
• 想要建立「AI 模擬群組成員」以自主觀察與參與聊天的開發者。
• 希望透過 QQ 遠端控制其 DSH 實例的高階使用者。

核心亮點

• 多模式運作：可在標準聊天、所有者專屬代理控制與自主模擬模式之間自由切換。
• 安全工具：透過 MCP 限制 QQ 操作子集，防止未經授權的帳戶控制。
• 會話管理：自動管理並持久化 QQ ID 與 DSH 會話之間的對應關係。
• 互動式回饋：將代理請求的使用者問題與工具授權請求直接轉發至 QQ，實現即時決策。
• 內建控制台：提供基於 Web 的控制面板，支援即時切換模式與角色設定。