前言¶

DSH 的理念是「一切皆插件」，渠道类能力（飞书、Discord、Telegram 之类）本该由插件补齐，但 QQ 这条渠道一直比较特殊：QQ 机器人的出站消息有频率限制、长消息要分块、事件订阅 intents 要在连接期声明，官方 SDK 的默认行为在这些边界上未必符合预期。dsh-qqbot 就是在这条渠道上做工程化的插件，把流式输出、发送链路重试、事件订阅和可视化设置面板都处理了一遍，并提供了机器人 AppID/AppSecret 之后就能跑起来的完整链路。下面介绍这个插件的定位、安装方式和典型用法。

这是什么¶

一句话定位：给 DeepSeek Harness（dsh）接 QQ 机器人的 IM 渠道插件，支持群聊与私聊、发图发文件、定时任务、多人格与可视化设置面板。

维护者 RrOrange，分类为客户端，当前星标 0。它以 zaofan-make/dsh-qqbot 的 npm 发布版 1.11.36 为基础手工维护，上游又 fork 自 tencent-connect/dsh-qqbot；包名沿用原有发布名，因此 package.json 里写的是 @zaofan/dsh-qqbot，版本号 1.11.36，许可证 MIT。

它要解决的问题集中在两处：一是出站链路，包括流式输出、限流退避、长消息分块、群发降速；二是设置入口，把配置、账号、定时任务、群管理、审批等收敛到 dsh 的「设置」面板里，而不是靠改 cordis.patch.yml。

核心功能¶

下面只列插件 README 中明确写明的能力。

流式输出。 修复后首帧自建缓冲，私聊可以边生成边刷新同一条消息；面板里新增「流式输出（默认开）」开关，私聊可关成非流式。群聊受 QQ 平台限制只能整条发送。

发送链路健壮性。 限流/5xx 退避重试；长消息分块时单块失败不再影响后续块；群发降速到平台配额以内；审批监听重建后不再被旧实例抢走。

图片消息。 修复纯 ![alt](url) 消息被当纯文本发出的问题；上传失败时不再把 [MEDIA:image|…] 字面标记发到群里。

事件订阅补全。 机器人被移出群、对方关闭主动消息，插件能感知并在面板给出提示。

设置面板。 搜索框合一（字面 + 语义）、保存条吸底、顶部标签吸顶、「账号与预设」页重做，删掉了冗余的「怎么用 / 定时唤醒 / 扩展示例」等页签。

渠道基础能力。 群里发图/文件、定时任务、多人格、多账号（每个账号实例一页）、斜杠命令（发 /help 查看）。

扩展口。 提供用户扩展样板与契约文档，工具/命令/自定义卡片都可以写在账号数据目录的 .qqbot-extensions/ 下，不随插件包下发。

安装与启用¶

前置：已装好 dsh，并准备好 QQ 机器人的 AppID/AppSecret（在 https://q.qq.com 注册获取）。

README 给出的安装方式是先打包再从本地 tgz 安装，不要直接 git clone 后运行 npm run build——这份 fork 直接改编译产物，dist/ 是随包提交的，没有 src/。

git clone https://github.com/RrOrange/dsh-qqbot.git
cd dsh-qqbot
pnpm pack --pack-destination .
$tgz = (Get-ChildItem *.tgz).FullName
npx @deepseek-ai/dsh plugin --profile desktop add $tgz   # 桌面客户端
# npx @deepseek-ai/dsh plugin --profile web add $tgz     # dsh web（网页版）

上面 --profile 要填你实际在用的 profile 名，也就是 %USERPROFILE%\.dsh\profiles\ 下的文件夹名：桌面客户端一般叫 desktop，dsh web 一般叫 web。装错 profile 的表现是重启后设置里没有 QQ 机器人面板。

打包出的 .tgz 文件名由 package.json 里的 name + version 决定（本项目原名 @zaofan/dsh-qqbot，所以会是 zaofan-dsh-qqbot-1.11.36.tgz 这类），代码里用 (Get-ChildItem *.tgz).FullName 取即可，改名不影响安装。装完重启 dsh：跑 dsh web 的重启那个进程，桌面客户端退出重开，dist/ 的改动必须重启才生效。

README 也给出了一条备用路径：dsh plugin --profile <你的profile> add github:RrOrange/dsh-qqbot。这是作者提供的简写形式，本质仍是拉取该仓库的包，不是把仓库当源码构建。

夹带在安装命令里的两条注意点：

• Windows 上不要把带空格的目录直接 add（会报 "- isn't supported"），必须先 pnpm pack 再 add 生成的 tgz。
• 这个仓库没有构建步骤，npm run build / pnpm build 都是无效的（会因缺少 src/ 失败），打包前不要执行。

典型用法¶

进入面板。 dsh 侧打开「设置 → QQ 机器人」。多账号时每个实例一页；面板只在 web profile 下出现。

群里回复范围。 默认只有 @ 机器人 才回复。想让机器人读取全部群消息，需要去手机 QQ 里改「机器人可获取的群聊消息范围」，插件侧不提供开关。

远程审批。 Agent 的工具要访问工作区之外的位置时，dsh 会触发权限审批；开启插件的「QQ 远程审批」后，审批请求会发到发起者的 QQ 会话，直接用 /approve <码> 放行、/deny <码> 拒绝，120 秒后自动拒绝。开启位置在「设置 → QQ 机器人 → ⑤ QQ 远程审批」，保存即对新请求生效，不需要重启。

群管理（可选）。 机器人为群管理员时可在「⑥ QQ 群管理」开启能力：接收入群申请、按申请审批、查询与设置禁言。注意 watchJoinRequests 要在连接期注册 intents，改动必须重启宿主，不是 live 热改。

斜杠命令。 直接在会话里发 /help 看内置命令列表。

适用场景与注意¶

适合的场景：已经用 dsh 跑 agent，想多一个 QQ 渠道做群助手或个人机器人的开发者；对流式显示、群发稳定性有要求、愿意自己维护 fork 的用法。

需要注意的：

• 插件以当前 dsh 进程的权限运行，Agent 能访问的文件、工具和命令集取决于你给 dsh 配的权限，本插件不会收紧也不会放宽这个边界。
• 它依赖 @tencent-connect/qqbot-connector 与 @tencent-connect/qqbot-nodejs，并且声明了对 @deepseek-ai/cordis、dsh-agent、dsh-llm、dsh-session、dsh-tools 的 peer 依赖；README 声明要求 dsh >=0.1.5-rc.2。升级 dsh 前先确认这些版本约束。
• 仓库不含任何机器人凭据、图库数据或日志。AppID/AppSecret 请通过环境变量或 Web 面板注入，不要提交进 git。
• 这是个人修改版，上游是 zaofan-make/dsh-qqbot，再上游是 tencent-connect/dsh-qqbot；许可证 MIT，上游版权归各自作者。安装前建议通读 dist/ 里的实现、docs/ 中的用户手册与扩展契约，以及 cordis.patch.yml。
• 仓库 dist/ 就是源码，改动后刷新网页即可生效（设置面板的 client/qqbot-settings.js 是单文件手写 bundle），因此不要用 npm run build 覆盖。

结尾¶

这个插件的价值在于把 QQ 渠道里那些容易踩的坑——流式突发、限流退避、分块重试、事件订阅——在前面的 fork 里补齐，并且把配置入口搬进了 dsh 的设置面板，日常使用不需要改配置文件。如果你已经在用 dsh 并觉得 QQ 渠道的缺点正好卡在这几处，它是值得装的一个选择。

• 目录页：https://www.skillhub.cn/plugins/RrOrange/dsh-qqbot
• GitHub：https://github.com/RrOrange/dsh-qqbot
• 上游：https://github.com/zaofan-make/dsh-qqbot