DeepSeek Harness 插件：dsh-im-qq（QQ 官方機器人接入）

前言¶

DeepSeek Harness（DSH）將大模型能力封裝爲本地可運行的 Agent。在本地運行 Agent 的常見場景中，往往需要通過 IM 渠道與其交互。接入 QQ 官方機器人（q.qq.com）通常涉及處理 WebSocket 長連接、消息路由、會話隔離以及複雜的權限審批邏輯。

dsh-im-qq 插件解決了上述問題。它作爲一箇中間層，將 QQ 的消息流轉換爲 DSH 的標準事件，並反向將 Agent 的思考結果發回 QQ。通過該插件，用戶可以直接在 QQ 私聊、羣聊或頻道中調用 Harness 的完整能力（工具調用、記憶、子代理等）。

插件簡介¶

名稱：dsh-im-qq
維護者：988hj7tczd-oss
核心價值：將 QQ 官方機器人協議接入 DSH，實現全功能 Agent 的 IM 交互。
許可協議：MIT

核心功能¶

該插件實現了以下核心能力：

消息接入：支持私聊（C2C）、羣聊 @機器人、頻道 @機器人。
會話隔離：自動爲每人/每羣建立獨立會話，消息前綴統一爲 qq:。
Agent 能力：完整支持工具調用、記憶管理、子代理和文件系統操作。
連接機制：基於 WebSocket 長連接，支持心跳、斷線重連（RESUME）和自動識別。
消息處理：支持回覆合併、超長分段、去除內部標籤及錯誤兜底。
安全與頻控：白名單機制（Fail-closed）與消息頻率控制。
審批橋：通過 QQ 內聯按鈕（✅/⭐/❌）實現高權限操作的審批，支持 /revoke 撤銷。
斜槓命令：支持 /help、/ping、/me、/new、/approve、/always、/revoke 等指令。

安裝與配置¶

安裝¶

在插件目錄下執行安裝腳本：

./install.sh

安裝完成後，重啓 harness-desktop。

配置¶

方式 A（推薦）：桌面端設置
1. 打開 設置 → 插件 → 插件配置。
2. 找到 QQ 機器人 卡片。
3. 填入 AppID 和 AppSecret，點擊保存並啓動。憑據將寫入 $DSH_HOME/.credentials.yaml。

方式 B（手動）：編輯配置文件
編輯 $DSH_HOME/cordis.patch.yml，添加如下配置塊（id 必須加引號以防 YAML 解析爲數字）：

- insert:
    - id: dsh-im-qq
      name: dsh-im-qq
      config:
        id: '你的AppID'
        secret: '你的AppSecret'
        sandbox: true
        transport: 'websocket'
        provider: 'deepseek-official'
        model: 'deepseek-v4-flash'
        agentPreset: 'standard'
        cwd: '~/qq-workspace'
        workspaceIsolation: true
        allowFrom: ['*']
        groupAllowFrom: ['*']
        deliverWindowMs: 900
        textChunkLimit: 4000
        replyPassiveLimit: 4
        approval: true
        slashCommands: true
        debug: false

使用方法¶

私聊：直接發送消息給機器人。
羣聊/頻道：@機器人後跟消息內容。
斜槓命令：
- /help：查看幫助
- /ping：檢查連接狀態
- /me：發送用戶信息
- /new：創建新會話
- /approve / /always：審批相關
- /revoke：撤銷審批權限
審批流程：當 Agent 需要執行高權限操作時，會在 QQ 消息中彈出內聯按鈕。
- ✅ 允許一次：臨時授權。
- ⭐ 始終允許：永久授權（可用 /revoke 撤銷）。
- ❌ 拒絕：拒絕該次請求。

注意事項與故障排查¶

1. 機器人類型與測試人員（必須覈對）¶

公域 vs 私域：在 q.qq.com 創建機器人時，必須選擇公域機器人。私域機器人無法調用羣組接口，會導致永久報錯 11255。
測試人員：必須在 測試人員管理 中添加你的 QQ 號。非測試人員發消息也會導致 11255 錯誤。
Sandbox 模式：建議先開啓 sandbox: true 驗證，穩定後再切換爲 false。

2. 常見錯誤處理¶

WS Close Code 4009：日誌中出現此代碼是正常行爲（QQ 服務器約每 30 分鐘主動斷連），插件會自動 RESUME/重連，無需干預。
消息回覆慢/無回覆：
- 開啓 debug: true 查看日誌。
- 檢查入站管線是否被 ACL 拒絕。
- 檢查 Agent 是否報錯（會有兜底文本提示）。
回覆帶 URL 發送失敗：QQ 平臺要求消息中的 URL 必須在後臺 消息 URL 配置 中預先添加，否則整條消息發送失敗。
缺少憑據：檢查 id 是否被解析爲數字（必須加引號），secretEnv 指向的環境變量是否已導出。
審批按鈕無反應：確認平臺側已訂閱按鈕互動事件（intent 1<<26）。

3. 主動消息配額¶

QQ 官方限制主動消息每月 4 條/人/羣。插件默認優先使用被動回覆（在 msg_id 有效期內），正常對話不消耗配額。只有當回覆長度超過被動上限（默認 4 條/消息）時，纔會轉爲消耗配額的主動消息。若遇到 50015014 錯誤，說明觸發了頻控，插件已實現指數退避重試，但高頻主動推送仍可能受限。

4. 已知邊界¶

圖片/流式/Typing：接口預留了配置項，但代碼尚未實現（P4/P5 級別）。
Webhook：官方長期方向是 Webhook（需公網 HTTPS + IP 白名單）。當前架構已抽象雙模式，未來僅需實現 platform/transport/webhook.js 即可切換。