前言¶

在 DSH 裏把 Agent 接到 QQ 私聊或羣聊時，用戶往往在模型還在跑工具、還沒回完一條消息時就連續補發好幾段文字。官方 @tencent-connect/dsh-qqbot 0.5.3 會把這類消息用 concurrencyGuard(strategy:'merge') 緩衝到本輪結束後再合併，下一輪才處理；一輪裏多個 step 也可能各自發一條 QQ 消息，聊天窗口裏顯得碎、也難讀。維護者 bufan528 的 dsh-qqbot-merge 是在上游 0.5.3（MIT）上的維護分支，在保留審批、待答問題、文件交付、羣聊歷史、綁定頁等能力的前提下，增加「連續消息智能合併」和「同一輪單條回覆持續修訂」，並對外提供 qqbotMerge cordis 服務。下面介紹它是什麼、與官方的差異、如何替換安裝，以及啓用合併時要注意的事項。

這是什麼¶

dsh-qqbot-merge（npm 包名 dsh-qqbot-merge，當前資料中的版本爲 0.1.1）是 @tencent-connect/dsh-qqbot 0.5.3 的 modified fork，不是騰訊官方發佈包。原項目版權歸 Tencent Connect；本分支修改部分同樣以 MIT 發佈。分類上屬於 DSH 客戶端插件：通過 QQ Bot WebSocket 把會話接到 ctx.agents 與 DSH agent loop。

它與官方插件不能同時啓用——兩者會使用同一個 QQ Bot appId 建網關連接並註冊同名綁定頁路由。啓用本包即替換官方 QQ 插件，而不是並列安裝。

核心功能¶

連續消息智能合併（默認關閉）¶

合併功能默認關閉（qqbotMerge.enabled: false），關閉時行爲與官方 0.5.3 一致。

開啓後，Agent 執行任務期間用戶連續發來的消息按 QQ 會話隔離，經靜默窗口（默認 800ms）合併成一批：

• 忙碌時通過公開的 agent.steer(...) 非打斷式併入當前輪的下一個 step，不取消正在進行的模型調用或工具。
• 空閒時用 agent.followup(...)，不再排隊到下一輪。
• agent/turn-stopping 時會把仍在窗口內的批次併入當前輪；steer 競態會自動降級爲 followup；超過單批上限的消息會通知用戶並作爲下一批 followup，不會靜默丟棄。

官方 0.5.3 在任務執行中收到新消息時，是緩衝到本輪結束再合併、下一輪處理；本分支在合併窗口結束後用 steer 併入當前輪，這是 README 中明確列出的行爲差異。

同一輪單條回覆¶

在 replyMode: 'single-message' 時，一輪裏多個 step 的文本會在同一條 QQ 消息上全量重寫，turn/end 時只 complete 一次。流式不可用時（羣聊或非流式場景）會降級爲輪末單條靜態發送。官方 0.5.3 則是每個 assistant/message 各發一條 QQ 消息。

qqbotMerge cordis 服務¶

本分支通過 ctx.provide('qqbotMerge', …) 對外暴露 cordis 服務，契約爲 qqbot-merge@v1，供 dsh-longterm-memory 等插件在「QQ 接入」頁讀取/寫入配置、查看運行期計數與最近一批。配置只寫入本插件自己的 cordis row config。

端內設置¶

DSH 設置頁提供 「連續消息智能合併」 欄目：可配置開關、靜默窗口、單批上限、私聊與羣聊開關、運行中策略、回覆模式，並查看運行期計數與最近一批，無需僅依賴其他插件改 profile。

繼承的上游能力¶

README 說明本分支保留：審批、待答問題、文件交付、羣聊歷史、模型/預設切換、綁定頁等。上游常見的 appId / appSecret、訪問控制、富媒體與 vision 等配置項在文檔中仍適用；安全提示與官方相同——憑據會以明文寫入 profile 的 cordis.patch.yml，本分支沿用該機制，不額外保存、不上傳、不回顯 Secret。

安裝與遷移（替換官方 QQ 插件）¶

資料中的推薦步驟針對 DSH 桌面 profile，按順序執行：

# 1) 安裝本分支
npx @deepseek-ai/dsh plugin --profile desktop add dsh-qqbot-merge

# 2) 從 profile 移除官方插件，並把 bundles 裏的 "@tencent-connect/dsh-qqbot" 換成 "dsh-qqbot-merge"
npx @deepseek-ai/dsh plugin --profile desktop remove @tencent-connect/dsh-qqbot

# 3) 遷移憑據：把原 `im-qqbot` 行的 appId/appSecret 複製到新行（行 id 爲 `qqbot-merge`），
#    或重啓後重新掃碼綁定；不要在兩行裏同時保留憑據

# 4) 重啓 DSH 桌面端

從源碼本地構建時，README 給出：

npm install
npm run build
npm run build:client
npx vitest run
npm pack

然後使用打包產物安裝，例如：

npx @deepseek-ai/dsh plugin --profile <name> add .\dsh-qqbot-merge-0.1.1.tgz

插件以當前 DSH 進程權限運行；安裝前應自行查看 GitHub 倉庫 源碼與 MIT 許可證，並理解憑據寫入 profile 的方式。

啓用連續消息合併¶

任選其一：

1. 打開 DSH 設置頁 →「連續消息智能合併」，打開開關並保存；同一頁可查看運行期計數與最近一批。
2. 在 profile 的 cordis.patch.yml 裏，將 qqbot-merge 行的 qqbotMerge.enabled 設爲 true。

其餘合併相關項（靜默窗口、單批上限、私聊/羣聊開關、回覆模式等）可在同一設置頁配置，或通過 cordis 服務由配套插件讀寫。

適用場景與注意¶

適合誰： 已在 DSH 桌面或 CLI 中使用 QQ Bot 插件、希望用戶在 Agent 忙碌時連發消息能被非打斷式併入當前輪，且希望一輪多 step 在 QQ 側呈現爲一條可修訂回覆的開發者。若需要 Memory Vault 的 QQ 接入頁統一管理合併配置，可配合 dsh-longterm-memory 使用 qqbotMerge 服務。

務必知曉：

• 不能與 @tencent-connect/dsh-qqbot 同時啓用；回滾時將 profile 的 dependencies / bundles 換回 @tencent-connect/dsh-qqbot@0.5.3 即可。
• 發佈者在 README 中寫明：真實 QQ 端到端（連續消息 → 一條回覆）尚未在發佈者機器上驗證（同一 appId 無法並行建兩條連接）。使用前請自行測試並保留回滾路徑。
• package.json 中聲明 Node >=20.3.0，並與資料中列出的 DSH 發行版兼容性條目一致時再升級生產環境。

結尾¶

dsh-qqbot-merge 把騰訊 Connect 開源的 QQ Bot 插件 0.5.3 當作基線，用可選的合併窗口、agent.steer() 與單條消息修訂改善 QQ 側對話體驗，並用 qqbot-merge@v1 把配置與運行態暴露給生態裏的其他插件。目錄與說明見 SkillHub 插件頁，源碼與遷移細節見 GitHub：bufan528/dsh-qqbot-merge。