QQ 机器人接入leliln52/dsh-qqbot

dsh-qqbot

把 DeepSeek Harness（DSH）接入
QQ 机器人的插件，支持两种接入通道：

| 通道 | transport | 适用 | 说明 |
| --- | --- | --- | --- |
| OneBot 11 | onebot（默认） | NapCat / Lagrange / LLOneBot 等协议端 | 正向 WebSocket，功能全（群聊任意消息、图片等） |
| QQ 官方开放平台 | official | q.qq.com 官方机器人 | AppID/AppSecret 直连，群聊（@触发）/单聊/频道 |

两种通道下行为一致：

- 每个 QQ 会话一个持久 Agent：私聊、每个群、每个频道各自独立上下文，历史跨重启保留
（会话日志持久化到 $DSH_HOME/sessions）；
- 完整工具链：Agent 挂载部署的 Agent 预设（web profile 下为 standard），
拥有文件读写、Shell/PowerShell、网页搜索、子代理、任务清单等 DSH 全部能力；
- Agent 可主动发消息：注册 qq_send 工具，Agent 可以主动向对话方汇报进度、
提问或输出结果；
- 本地命令 #help / #status / #reset，长回复自动分块，断线自动重连。

工作原理

QQ 消息 ──► OneBot 实现 / QQ 官方开放平台
│  正向 WebSocket / 官方 WS 长连接（q.qq.com）
▼
dsh-qqbot 插件（web profile 内）
│  ctx.agents.create / resume（每个 QQ 会话一个 Agent）
▼
DeepSeek Harness Agent（模型 + 工具 + 预设）
│  回复文本
▼
send_*_msg / 官方 OpenAPI ──► QQ

安装

1. 准备 QQ 接入端

OneBot 通道（默认）：任选一个协议实现，例如 NapCat：
登录机器人 QQ 号，开启「网络监听 → WebSocket 客户端（正向 WS）」，记下地址
（默认 ws://127.0.0.1:3001），可选设置 access token。

QQ 官方通道：到 QQ 开放平台 创建机器人，在「开发设置」
拿到 AppID 与 AppSecret；在「沙箱配置」添加测试群/私聊用户（或发布后使用）。
群聊中机器人只会收到 @它的消息；单聊需用户主动发起。

2. 安装插件到 DSH web profile

dsh plugin --profile web add file:C:\path\to\dsh-qqbot

等价于在 $DSH_HOME/profiles/web 下执行 pnpm add file:...，
并把 dsh-qqbot 加入该 profile 的 bundle 列表。

然后重启 dsh web（先 Ctrl+C 停掉旧进程再启动）。启动日志出现
qqbot: connected to ... 即成功。

3. 配置

OneBot 通道：默认连接 ws://127.0.0.1:3001，可设环境变量：

set QQBOT_WS_URL=ws://127.0.0.1:3001
set QQBOT_ACCESS_TOKEN=你的token
dsh web

QQ 官方通道（任选其一）：

方式 A —— 环境变量：

set QQBOT_TRANSPORT=official
set QQBOT_APP_ID=你的AppID
set QQBOT_APP_SECRET=你的AppSecret
dsh web

方式 B —— profile 的 cordis.patch.yml（$DSH_HOME/profiles/web/cordis.patch.yml）：

- id: qqbot
config:
transport: official
appId: '你的AppID'
clientSecret: '你的AppSecret'
sandbox: true          # 沙箱域名（默认正式环境）
groupMentionOnly: true # 群聊只在 @机器人 时回复（官方通道天然只收 @）
allowedUsers: ['xxx']  # 只允许这些用户 openid（空 = 全部）
allowedGroups: ['xxx'] # 只回复这些群 openid（空 = 全部）

配置项见插件 Config（lib/index.js）与下方「配置项一览」。

使用

| 命令 | 作用 |
| --- | --- |
| 任意消息 | 交给本会话的 Agent 处理并回复 |
| #help | 显示帮助 |
| #status | 显示接入通道、连接与会话状态 |
| #reset | 重置当前会话（清空上下文） |

每个 QQ 会话的工作目录位于 /qqbot-chats/（可在
workspaceRoot 配置中改；建议保持在 DSH 沙箱根内，否则文件类工具会被拦截）。

Agent 主动发消息（qq_send）

插件向所有 Agent（包括 web GUI 会话）注册 qq_send 工具：把文本发送给
“当前正在与这个 Agent 对话的 QQ 会话”。例如 Agent 在长时间任务中可以汇报进度，
或向用户提问。非 QQ 会话调用会得到明确报错。

注意：QQ 官方开放平台自 2025-04-21 起已停用主动消息能力，因此官方通道中的
qq_send 会明确报错；OneBot 通道不受此限制。官方被动回复仍受平台窗口和
“同一条入站消息最多回复 5 次”等限制，插件会在分块超过 5 条时拒绝发送，避免静默丢尾。

配置项一览

| 键 | 默认 | 说明 |
| --- | --- | --- |
| transport | onebot | onebot（OneBot 11）或 official（QQ 官方） |
| url | ws://127.0.0.1:3001 | OneBot 正向 WS 地址 |
| accessToken | '' | OneBot token（Bearer） |
| reconnectDelayMs | 3000 | 重连初始延迟，指数退避封顶 60s |
| appId | '' | QQ 官方机器人 AppID |
| clientSecret | '' | QQ 官方机器人 AppSecret |
| apiBase | https://api.sgroup.qq.com | 官方 OpenAPI 域名 |
| tokenUrl | https://bots.qq.com/app/getAppAccessToken | access_token 接口 |
| sandbox | false | 使用沙箱域名 sandbox.api.sgroup.qq.com |
| gatewayUrl | '' | 强制指定官方 WS 网关；留空自动获取 |
| replyMaxChars | 4500 | 单条回复字符上限，超出分块（官方通道另限 3000 字节） |
| workspaceRoot | /qqbot-chats | 会话工作目录根 |
| persona | 内置默认 | 附加到每个 QQ Agent 的系统提示词 |
| preset | ''（部署默认） | QQ Agent 挂载的 Agent 预设 id |
| allowedUsers | [] | 允许私聊的 QQ 号/openid（空=全部） |
| allowedGroups | [] | 允许回复的群号/群 openid/频道键 -（空=全部） |
| groupMentionOnly | false | 群聊仅 @机器人 时回复 |
| maxTurnMs | 600000 | 单轮回复最长等待，超时后取消当前任务并提示 |
| httpTimeoutMs | 15000 | QQ 官方 token/OpenAPI HTTP 请求超时（ms） |
| registerSendTool | true | 是否注册 qq_send 工具 |

卸载

dsh plugin --profile web remove dsh-qqbot

安全注意

- QQ 机器人是无认证的入口：任何能向你机器人发消息的人都能使用 DSH 的
Agent 能力（包括 Shell）。请务必通过 allowedUsers / allowedGroups
限制可用范围，并只登录可信的 QQ 号。
- 审批（approval）弹窗仍会出现在 web GUI 中（policy 为 ask 时）；如果
需要 QQ 内审批，请自行扩展（例如把 qq_send 接到审批 answerer）。
- 工作目录默认位于 DSH 沙箱根内；改到别处时请同步调整
fs-sandbox.workspaceRoot，否则文件类工具会被沙箱拦截。

License

MIT