dsh-qqbot：DeepSeek Harness × QQ 雙通道接入插件

前言¶

DeepSeek Harness（DSH）採用插件化架構，通過擴展能力實現不同場景的接入。將 DSH 接入 QQ 機器人需要處理協議轉換與會話管理。dsh-qqbot 插件支持 OneBot 11（NapCat/Lagrange 等正向 WebSocket）與 QQ 官方開放平臺（q.qq.com）雙通道，允許每個 QQ 會話對應一個持久 Agent，支持文件、Shell、聯網等完整工具鏈，並允許 Agent 主動發消息。

核心功能¶

雙通道接入：支持 OneBot 11 協議端（NapCat、Lagrange 等）與 QQ 官方開放平臺（AppID/AppSecret 直連）。
持久化會話：每個 QQ 會話（私聊、羣聊、頻道）對應一個獨立 Agent，歷史記錄跨重啓保留。
完整工具鏈：掛載 DSH 預設（默認 standard），具備文件讀寫、Shell/PowerShell、網頁搜索、子代理、任務清單等能力。
主動發消息：註冊 qq_send 工具，Agent 可主動向對話方彙報或提問。
本地命令：支持 #help、#status、#reset 等本地指令。

安裝與配置¶

1. 準備 QQ 接入端¶

OneBot 通道：選擇 NapCat 或 Lagrange 等協議實現，開啓正向 WebSocket，獲取地址與 Token。
官方通道：在 QQ 開放平臺創建機器人，獲取 AppID 與 AppSecret。

2. 安裝插件¶

在 DSH 的 web profile 下執行安裝命令：

dsh plugin --profile web add file:C:\path\to\dsh-qqbot

安裝後需重啓 dsh web 進程。啓動日誌中出現 qqbot: connected to ... 即爲成功。

3. 配置¶

配置通過環境變量或 cordis.patch.yml 完成。

OneBot 通道（默認）：

set QQBOT_WS_URL=ws://127.0.0.1:3001
set QQBOT_ACCESS_TOKEN=你的token
dsh web

QQ 官方通道：

set QQBOT_TRANSPORT=official
set QQBOT_APP_ID=你的AppID
set QQBOT_APP_SECRET=你的AppSecret
dsh web

或編輯 $DSH_HOME/profiles/web/cordis.patch.yml：

- id: qqbot
  config:
    transport: official
    appId: '你的AppID'
    clientSecret: '你的AppSecret'
    allowedGroups: []  # 限制回覆羣組，空爲全部
    allowedUsers: []  # 限制私聊用戶，空爲全部

使用方法¶

正常對話：向機器人發送任意消息，由當前會話的 Agent 處理並回復。
查看狀態：輸入 #status 查看接入通道、連接與會話狀態。
重置會話：輸入 #reset 清空當前會話上下文。
Agent 主動消息：Agent 可調用 qq_send 工具向當前會話發送文本。

注意事項¶

安全限制：QQ 機器人入口無認證，任何能發消息的人均可調用 Agent 能力（含 Shell）。必須通過 allowedUsers / allowedGroups 限制範圍。
官方通道限制：QQ 官方開放平臺自 2025-04-21 起已停用主動消息能力，官方通道下 qq_send 會報錯。OneBot 通道不受此限制。
回覆限制：官方回覆受平臺窗口和“同一條入站消息最多回復 5 次”限制，插件會拒絕超過 5 條的分塊發送。
工作目錄：Agent 的工作目錄默認位於 DSH 沙箱根內。若修改 workspaceRoot，請確保路徑在沙箱範圍內，否則文件類工具會被攔截。

結尾¶

dsh-qqbot 爲 DSH 用戶提供了標準化的 QQ 機器人接入方案，通過雙通道支持與持久化 Agent 機制，適合需要將大模型能力集成到 QQ 生態的開發場景。更多細節可參考 GitHub 倉庫。