前言¶
在 DeepSeek Harness（DSH）裏跑 Agent，產出往往還在工作臺裏；要送到同事或客戶常用的 QQ 羣、私聊，常見做法仍是人工複製粘貼。QQ 開放平臺有官方機器人，本機也可以跑 NapCat、Lagrange.OneBot 等 OneBot v11 框架，但和 DSH 之間缺少一條統一、可審計、能被工具調用的通道。
@deepwhale-cn/dsh-qq-bridge（社區倉庫 feely0208/dsh-qq-bridge）是 DSH 的客戶端類插件：從 v0.3 起可在 QQ 官方機器人 WebSocket 與 OneBot v11 HTTP 兩條通道里二選一；側欄收發、入站入隊、全量審計 JSONL；官方通道還可選開關鍵詞規則自動回覆（默認關閉）。下面介紹它解決什麼問題、怎麼裝、怎麼用。
這是什麼¶
插件 npm 包名爲 @deepwhale-cn/dsh-qq-bridge，當前資料中的版本爲 0.3.1，MIT 許可證，維護者 feely0208（倉庫與 SkillHub 目錄頁 一致）。定位一句話：把 QQ 接進 DSH——發消息、收入站、留審計。
與「只在 IM 裏掛一個獨立 bot」相比，它把 QQ 側事件和發送能力接到 DSH Web 側欄與 qq_send 等工具鏈上，本地隊列上限 1000 條，收發與失敗原因（含官方 code / trace_id）寫入本機審計文件。AppSecret、access_token 只存本機，請求 10s 超時，只連官方域名或你配置的 OneBot 端點。
核心功能¶
雙通道二選一¶
通道一：QQ 官方機器人（v0.2 起，README 推薦先用）
- 只需在 q.qq.com 創建機器人，填寫 AppID、AppSecret，無需本機跑 OneBot 框架。
- 走 QQ 開放平臺 WebSocket；訂閱羣 @ 與私聊等事件，歸一化入隊。
- 沙箱勾選時走
sandbox.api.sgroup.qq.com，正式環境走api.sgroup.qq.com。
通道二：OneBot v11（v0.1 起）
- 依賴本機已有 OneBot v11 HTTP API（如 NapCat、LLOneBot、Lagrange.OneBot）。
- 面板配置端點（例如
http://127.0.0.1:3000）、access_token、可選上報共享密鑰；OneBot 上報地址設爲http://127.0.0.1:<DSH Web 端口>/dsh-qq-bridge/api/hook。
兩條通道的入站都進入同一隊列；配置集中在 ~/.dsh/qq-bridge.json（權限 0600），字段 mode 爲 official 或 onebot（未配時默認 onebot，兼容老配置）。
發送、入站與審計¶
- 發得出去：面板或工具把純文本（≤4000 字符）發到私聊 c2c、羣 group、頻道等；支持帶
msg_id的被動回覆。 - 收得進來：官方 dispatch 與 OneBot 上報寫入本機 inbox；羣消息需真正 @ 機器人才會收到（平臺規則）。
- 留得下痕：
~/.dsh/qq-bridge-audit.jsonl記錄動作、結果與錯誤；inbox 在~/.dsh/qq-bridge-inbox.json。富媒體、撤回、按鈕交互當前未實現。
自動回覆（v0.3，僅官方機器人通道）¶
默認關閉。開啓後：入隊後按面板規則行順序匹配關鍵詞（包含 / 精確: / 正則:），命中則用模板回覆，佔位符含 {暱稱}、{內容}、{時間}；一律用原消息 msg_id 被動回覆。內置防刷：同會話最小間隔默認 30s、全局每小時上限默認 60 條、連續 3 次失敗自動暫停等。OneBot 通道仍只入隊與審計，不做自動回覆。
README 列舉的典型用法方向：法律/客服接待歸檔、企業審批通知、多渠道統一後臺的基礎 IM 通道。
安裝與啓用¶
在終端執行（命令來自插件 README）：
dsh plugin --profile web add @deepwhale-cn/dsh-qq-bridge
裝完後重啓 DSH 桌面端或 Web 配置對應的 DSH 實例，側欄會出現「QQ 橋接」。package.json 中聲明的 DSH 引擎範圍爲 >=0.1.0-rc.6 <0.3.0，Node >=18；安裝前請對照你本地的 DSH 版本與插件源碼、許可證。
典型用法¶
官方機器人：從零到連通¶
- 執行上述安裝命令並重啓。
- 瀏覽器打開 q.qq.com，創建機器人，在「開發設置」複製 AppID、AppSecret。
- 側欄「QQ 橋接」→「QQ 官方機器人」→ 粘貼並「保存配置」→ 點「連接」，狀態爲
已連接（機器人名）即成功。 - 將機器人拉進羣或讓用戶私聊；羣裏須從成員列表 @ 機器人，手打「@名字」不算。
- 可選：「自動回覆」卡片打開開關，配置默認模板與規則行，「保存並生效」。
手機端只需 QQ 客戶端聊天；配置在電腦完成。電腦關機或 DSH 未運行時，機器人不會回覆——邏輯跑在本機，不是雲端託管服務。
OneBot：端點與上報¶
- 本機啓動 OneBot v11 框架，記下 HTTP API 地址與 token。
- 面板「通道切換」選 OneBot v11，填寫端點與
access_token，保存。 - 在框架裏把 HTTP 上報指到 DSH 的 hook 路徑，並與面板「上報共享密鑰」或
access_token校驗方式一致。
Agent 側¶
插件作爲 DSH 客戶端注入 Web 平臺（dsh.client.platform: web），並提供發送等能力；具體工具名與參數以面板和倉庫文檔爲準（README 提到 qq_send）。入站消息可在面板「入站 / 審計」查看，並可用「回覆」帶入 msg_id 做被動回覆，避免主動消息配額錯誤（如 40034105）。
適用場景與注意¶
適合誰：已在用 DSH 做 Agent 或自動化，又需要 QQ 作爲觸達或收集入口的團隊；希望本地留存收發審計、而不是隻在第三方 bot 控制台裏翻記錄的場景。
權限與安全：插件以當前 DSH 進程權限運行，會讀寫 ~/.dsh/ 下 qq-bridge 相關文件（明文、0600）。安裝前應自行審查 GitHub 源碼 與 MIT 許可證；勿把含 AppSecret 的配置或審計文件放進共享目錄或雲盤。須遵守 QQ 開放平臺服務條款；插件不提供繞過審覈、自動加羣或羣發能力。
常見報錯（面板對照 README 報錯表）：主動消息無權限 40034105、被動回覆窗口過期 40034005、token 錯誤 401、OneBot fetch failed 需先啓動框架或改走官方通道；沙箱與正式環境的密鑰/地址不可混用。
結尾¶
@deepwhale-cn/dsh-qq-bridge 補的是 DSH 與 QQ 之間「可控、可審計、可工具化」的一段：官方機器人或 OneBot 二選一，側欄收發與全量審計，官方通道還可選關鍵詞自動回覆。社區目錄與 DeepSeek / 幻方無官方從屬關係，屬 DSH「一切皆插件」生態中的獨立條目。
