前言¶
在 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 的方式。
启用连续消息合并¶
任选其一：
- 打开 DSH 设置页 →「连续消息智能合并」，打开开关并保存；同一页可查看运行期计数与最近一批。
- 在 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。
