dsh-qq-bot

hzsfn/dsh-qq-bot

QQ official bot private message (C2C) bridge for DeepSeek Harness (dsh): per-user persistent agent sessions, image attachments, auto-reconnect

前往 GitHub

星标

Fork

MIT

许可证

2026-08-14

创建于

2026-08-14

README

dsh-qq-bot

把 QQ 官方机器人私聊（C2C）桥接进 DeepSeek Harness (dsh) 的 agent 会话。

每个 QQ 用户（openid）对应一个持久化的 dsh 会话，会话历史即上下文；dsh 重启后自动 resume 恢复历史。agent 的回复经 QQ 网关实时发回。只处理私聊，不处理群消息。

功能

✅ 私聊消息 → 对应 openid 的独立 dsh 会话（懒创建 + 重启 resume）
✅ 图片附件自动下载到 agent 工作目录的 inbox/（文本模型也能通过本地文件工具处理）
✅ 回复自动回发（完整 turn 结束后的最终文本）
✅ 发图工具 qq-send-image（v2.0）：agent 可把本地图片直接推送给当前 QQ 用户（富媒体消息 msg_type: 7；仅 QQ 会话可用，GUI 会话返回友好错误）
✅ 原生 WebSocket 网关：心跳保活、断线 10s/30s 自动重连、access_token 提前 5 分钟自动刷新
✅ 进程级兜底：未捕获异常只写日志，不会拖垮 dsh 进程
✅ 文件日志：$DSH_HOME/storages/qq-bot.log（排查全靠它）

安装

插件以 cordis bundle 插件 方式挂载到 dsh web profile：

把本仓库放到任意位置，将 index.js 放入（或软链到）profile 目录，例如：
```
~/.dsh/profiles/web/qq-bot-plugin/index.js
```

在 profile 的补丁层注册插件（~/.dsh/profiles/web/cordis.patch.yml）：

- insert:
    - id: qq-bot
      name: ./qq-bot-plugin/index.js
      config:
        enabled: true
        cwd: 'C:\your\agent\workspace'   # agent 工作目录（可选，默认取 dsh 进程 cwd）

凭证两种给法（二选一）：
- 环境变量（推荐，不落盘）：QQ_BOT_APP_ID / QQ_BOT_APP_SECRET
- config（见 cordis.patch.example.yml）
重启 dsh web，日志出现 QQ 网关 READY（开始接收私聊） 即成功。

获取 QQ 机器人凭证

前往 QQ 开放平台 → 创建应用/机器人，拿到 AppID 与 AppSecret。
机器人需要开通 C2C（私聊） 能力（沙箱环境即可先测）。
用该机器人的 QQ 号给你的 QQ 发消息 → 事件 C2C_MESSAGE_CREATE 会带 author.user_openid。

注意：openid 是机器人视角下对你 QQ 的 ID，不是你的 QQ 号；不同机器人 openid 不同。

工作原理

QQ 用户 ──私聊──▶ QQ 开放平台网关 (WSS)
                      │ C2C_MESSAGE_CREATE
                      ▼
                dsh-qq-bot 插件
                 ├─ 图片附件 → 下载到 <cwd>/inbox/
                 ├─ 文本 + 附件路径 → createUserMessage → 该 openid 的 agent 会话
                 ├─ session/event 监听 turn 结束 → 最终文本 → POST /v2/users/<openid>/messages 回发
                 └─ 工具 qq-send-image：agent 上传本地图片（POST /files）→ 富媒体消息回发

会话映射持久化在 $DSH_HOME/storages/qq-bot-sessions.json（openid → sessionId）。
图片以本地路径进入 agent 上下文（不经过图像模态），纯文本模型也能处理。
发图工具通过 exec.agent.id（sessionId）反查 openid，多用户各发各的。
断线重连：网关关闭 10 秒重连；获取 token/网关失败 30 秒重试。

已知注意事项

只接私聊：intents 仅订阅 1<<25（C2C），群消息不处理。
每个 openid 一个会话，消息排队进同一个 turn 上下文；不建议多用户共用一台机器时放敏感数据。
日志文件 qq-bot.log 会记录收到的消息摘要（前 60 字符），部署时注意隐私。
插件运行在 dsh web 进程内：dsh 重启 = 桥重启（自动 resume 会话）。

License

MIT