dsh-qqbot：將 QQ 消息作爲 DSH Agent 的前端協議驅動

前言¶

DeepSeek Harness (DSH) 的核心理念之一是“一切皆插件”。當需要通過即時通訊軟件與 Agent 交互時，需要一個標準化的驅動層。dsh-qqbot 插件提供了這樣的能力，將 QQ 消息平臺作爲 dsh agent 的前端協議驅動。用戶可以在 QQ 私聊或羣聊中與 Agent 對話，執行工具、切換模型、管理會話或工作區，並通過 QQ 消息完成審批。

插件定位¶

dsh-qqbot 是一個開源的 DeepSeek Harness (dsh) QQ Bot IM 插件。該項目由 cafeawa 維護，遵循 MIT 許可證。

本插件從零重寫，不包含騰訊內部插件代碼，也不依賴 UNLICENSED 的 @tencent-connect/qqbot-connector。其底層協議使用 MIT 許可的 @tencent-connect/qqbot-nodejs。

核心功能¶

插件具備以下核心能力：

消息接入與展示：支持 QQ 私聊（C2C）與羣聊消息接入。支持流式回覆與 Markdown 分塊發送，確保長文本在 QQ 平臺上的正常展示。
會話管理：支持會話隔離、空閒回收與重啓恢復，以及工作區隔離與跨會話切換。
模型路由：支持 per-peer（單聊對象）偏好配置，或通過 settings.yaml 配置，亦可繼承宿主默認設置。
上下文處理：支持羣聊歷史上下文、引用消息處理及文件附件下載。
內置命令：提供 dsh、goal、/bot-model、/bot-reset、/bot-status、/bot-workspace 等命令。
審批橋接：提供 dsh 審批橋接功能，支持通過 QQ 按鈕/文字審批，WebUI 同時給予提示。
任務通知：支持 goal 長任務完成通知。

安裝與配置¶

環境要求¶

Node.js >= 18，且 dsh 環境已可用。

構建與安裝¶

在 dsh-qqbot 項目目錄下，執行以下命令進行構建並安裝到 dsh profile：

# 1. 安裝依賴並構建
corepack pnpm install
corepack pnpm build

# 2. 安裝插件（使用本地路徑）
dsh plugin --profile qqbot add /path/to/dsh-qqbot

安裝後，可通過 --patch 方式通過 cordis.patch.yml 加載。

配置文件¶

在 profile 的 cordis.patch.yml 中，需配置 QQ Bot 的憑證及部分運行參數：

- id: im-qqbot
  config:
    appId: __FROM_ENV__
    appSecret: __FROM_ENV__
    requireMention: true
    textChunkLimit: 4500
    sessionIdleTimeout: 1800000
    maxQueue: 20
    processingTimeoutMs: 120000
    historyLimit: 10
    access:
      c2cMode: open
      c2cAllow: []
      groupMode: open
      groupAllow: []
    debug: false

主要配置項說明：
* appId / appSecret：QQ Bot 憑據，支持從環境變量 QQBOT_APPID / QQBOT_SECRET 讀取。
* requireMention：羣聊模式下是否需要被 @bot 才能觸發對話。
* sessionIdleTimeout：會話閒置回收時間（毫秒）。
* access：訪問控制模式（open 爲開放）。

啓動與使用¶

配置完成後，通過以下方式啓動 dsh 並加載插件：

export QQBOT_APPID="你的AppID"
export QQBOT_SECRET="你的AppSecret"
dsh --profile qqbot

架構說明¶

插件的消息處理流程如下：

QQ 用戶 → QQ WebSocket → @tencent-connect/qqbot-nodejs → 中間件鏈
                                                              ↓
                                                     handleInbound
                                                              ↓
                                                     SessionManager → dsh agent
                                                              ↓
                                              session/event → outbound → QQ Markdown

注意事項¶

插件以當前 dsh 進程的權限運行，請確保安裝前檢查源碼與許可證。
生態背景：DSH 理念是“一切皆插件”，社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。

總結¶

dsh-qqbot 爲 DSH Agent 提供了標準化的 QQ 接入層。通過會話管理、模型路由和審批橋接等功能，它使得在 QQ 平臺上構建複雜工作流成爲可能。項目地址：https://github.com/cafeawa/dsh-qqbot