QQ 私聊桥接 hZsFN/dsh-qq-bot

dsh-qq-bot

把 QQ 桥接进 DeepSeek Harness (dsh) 的智能体会话。两种后端，一套插件：

| 后端 | 走什么 | 适合谁 |
| official | QQ 官方机器人开放平台（私聊 C2C + 群聊 @） | 有开放平台账号、要正规不封号 |
| onebot | 自建协议端：NapCat / SnowLuma（OneBot v11） | 想用自己的 QQ 号、要全量群消息 |

每个 QQ 用户 / 每个群对应一个持久化的 dsh 会话，会话历史即上下文，dsh 重启后自动 resume。智能体的回复实时发回 QQ。

功能

通用

- ✅ 每个 QQ 用户 / 每个群一个独立 dsh 会话（懒创建 + 重启 resume）
- ✅ 通用附件下载：图片、PDF、Office、压缩包、音视频等约 30 类扩展名落到 <cwd>/inbox/，未知类型按 Content-Type → 文件名 → URL 推断，兜底 .bin
- ✅ 三个智能体工具：qq-send-image（富媒体图）、qq-send-file（≤5MB 直传 / >5MB 分片，上限 200MB）、qq-send-message（主动推文字，不要求当前会话来自 QQ）
- ✅ 文件日志 $DSH_HOME/storages/qq-bot.log
- ✅ 进程级兜底：未捕获异常只写日志，不拖垮 dsh

official 后端

- ✅ 原生 WebSocket 网关：心跳保活、断线 10s/30s 重连、access_token 提前 5 分钟刷新
- ✅ 群聊响应 GROUP_AT_MESSAGE_CREATE，每群独立会话（前缀 qq-grp2-）
- ✅ 凭证可走环境变量 QQ_BOT_APP_ID / QQ_BOT_APP_SECRET，不落盘

onebot 后端（v3.0.0 新增）

- ✅ 两种事件来源：正向 WebSocket（插件主动连）/ HTTP 上报（插件起服务收）
- ✅ HTTP 上报支持 X-Signature HMAC-SHA1 校验（timingSafeEqual）
- ✅ 引用回复：发出的消息带 reply 段，别人点"回复"引用它也算在跟你说话
- ✅ 防回环 + 消息去重：自己发的不处理，同一 message_id 60 秒内只处理一次（跨热重载实例）
- ✅ 群聊接话策略：只回 @ / 关键词触发 / 冷却秒数 / 主人白名单
- ✅ WS 连接接管：热重载后新实例自动关掉旧实例的连接

v3.0.0 另外两项

- ✅ 内置设置界面：插件自带 HTTP 服务（默认 127.0.0.1:3211）提供可视化配置页，改完点保存即生效
- ✅ 运行时热配置：配置独立成 runtime-config.json，插件每 3 秒读取一次，改完不用重启 dsh

安装

插件以 cordis bundle 插件方式挂载到 dsh 配置档：

1. 把本仓库放进配置档能引到的地方，例如 ~/.dsh/profiles/desktop/qq-bot-plugin/
2. 在配置档补丁层注册（~/.dsh/profiles/desktop/cordis.patch.yml），模板见 cordis.patch.example.yml
3. 重启 dsh

后端一：官方机器人

config:
backend: 'official'
appId: 'YOUR_APP_ID' # 或环境变量 QQ_BOT_APP_ID clientSecret: 'YOUR_SECRET' # 或环境变量 QQ_BOT_APP_SECRET

到 QQ 开放平台 创建应用拿 AppID / AppSecret，开通 C2C（私聊）与/或群聊能力（沙箱即可先测）。

后端二：OneBot v11（NapCat / SnowLuma）

1. 装协议端（NapCat 或 SnowLuma），用你的 QQ 登录
2. 协议端里开 OneBot v11 的 HTTP API（记下端口与 token）和 WebSocket 服务（正向 WS，同样有 token）
3. 本插件配置：

config:
backend: 'onebot'
onebot:
apiBase: 'http://127.0.0.1:3000' # 协议端 HTTP API accessToken: 'YOUR_HTTP_TOKEN' events: 'ws' # ws = 插件主动连；http = 插件起服务收上报 wsUrl: 'ws://127.0.0.1:3001' # 正向 WS 地址 wsToken: 'YOUR_WS_TOKEN' # 与 HTTP token 不同时单独填，留空回退 accessToken selfId: 'YOUR_BOT_QQ' # 机器人自己的 QQ 号（用于防回环 / @ 判定）
ownerUsers: ['YOUR_QQ'] # 主人白名单（真实 QQ 号）

HTTP 与 WS 的 token 通常是两个不同的值，SnowLuma 就是分开的。连不上先看协议端日志里有没有 rejected unauthorized WebSocket upgrade —— 那是 token 不对，不是路径问题。

设置界面（v3.0.0）

插件自带配置页：http://127.0.0.1:3211/（浏览器直接打开就能用）。四块表单——后端选择、会话预设、群聊策略、OneBot 连接；右下「保存」写入 runtime-config.json，3 秒内自动生效；Ctrl+S 也能保存。

想在 dsh 设置页里内嵌，再装一个客户端插件，只负责注册 settings.section（渲染 iframe 指向上面这个地址）即可，本仓库的 settings-page.html 就是页面本体。

配置项

顶层

| 键 | 默认 | 说明 |
| backend | 'official' | official / onebot，单选，两种后端暂不能同时跑 |
| enabled | true | 关掉则插件不启动 |
| preset | '' | 统一指定 agent 预设；留空 = 群用 qqgroup、私聊用默认预设 |
| groupPreset | '' | 群聊专用预设；留空 = 跟随 preset |
| privatePreset | '' | 私聊专用预设；留空 = 跟随 preset |
| cwd | $DSH_QQ_BOT_CWD → 进程 cwd | agent 工作目录（附件落 <cwd>/inbox/） |
| appId / clientSecret | 环境变量 | official 后端凭证 |
| fixedSessionId | — | 把私聊固定绑到某个 sessionId |
| runtimeConfig | '' | 运行时配置文件名（相对插件目录，默认 runtime-config.json） |

onebot.

| 键 | 默认 | 说明 |
| apiBase | http://127.0.0.1:3000 | OneBot HTTP API 地址 |
| accessToken | — | HTTP API token |
| events | 'http' | ws（主动连）/ http（起服务收上报） |
| wsUrl / wsToken | — / 回退 accessToken | 正向 WS 地址与 token |
| selfId | — | 机器人 QQ 号 |
| listenHost / listenPort / listenPath | 127.0.0.1 / 3200 / /onebot | HTTP 上报监听 |
| secret | '' | HTTP 上报的 X-Signature 密钥，留空不校验 |
| atOnly | true | 群里只回 @；false = 全量群消息都进 agent |
| groupKeywords | [] | 没被 @ 时，只有文本命中这些词才接（解决全量群消息刷屏） |
| groupCooldownSec | 0 | 非 @ 消息的接话冷却秒数，0 = 不冷却 |
| ownerUsers | [] | 主人白名单（真实 QQ 号）。OneBot 模式下私聊也必须是白名单 |

运行时热配置

runtime-config.json 里可以放上述任意字段（backend、preset、groupPreset、privatePreset、onebot. 都行），插件每 3 秒检查文件 mtime：

- 连接参数变了（token / 地址 / selfId / events…）→ 停旧连接、400ms 后重启后端
- 只改了策略（atOnly / 关键词 / 冷却 / preset / groupPreset / privatePreset）→ 直接换值，不断线
- JSON 写坏了 → 只记日志，继续用旧配置跑

注意：enabled / appId / clientSecret / runtimeConfig 这几项不能靠热配置改，仍要改 profile 的 patch 并重启。

工作原理

official：QQ 用户 ──私聊/群@──▶ QQ 开放平台网关 (WSS) ──▶ 插件 ──▶ dsh 会话 ──▶ POST /v2/users|groups/<id>/messages

onebot： QQ 用户 ──消息──▶ 协议端(HTTP API + WS) ──事件──▶ 插件 ──▶ dsh 会话 ──▶ POST /{send_private_msg|send_group_msg}

- 会话映射持久化在 $DSH_HOME/storages/qq-bot-sessions.json
- 附件以本地路径进 agent 上下文（不经过图像模态），纯文本模型也能处理
- 工具通过 exec.agent.id（sessionId）反查 openid / group_openid / QQ 号，多用户各发各的

已知限制

- backend 单选。要同时跑官方和 OneBot，得改会话映射与发送分派（约 5 处），当前版本不支持
- OneBot 后端依赖第三方协议端，有账号风控风险（新号、异地 IP、高频群发最危险），小号建议先正常挂几天
- 群消息来自协议端时只有 QQ 号与群名片，没有官方那套 openid；主人判定用 ownerUsers 白名单
- 日志会记录消息摘要（前 60 字符），部署注意隐私
- 插件跑在 dsh 进程内：dsh 重启 = 桥重启（自动 resume 会话）
- 热重载插件代码会留下旧实例的 WS 连接，v3.0.0 已做接管与去重，但仍建议改完代码重启一次

License

MIT