@wenbin_wb/dsh-bridge 2.1.0 → 2.1.2

package/README.md

@@ -18,6 +18,7 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 - **Cloudflare Tunnel**: One-click public internet exposure, connect from anywhere without a public server of your own — keep working even when you're away from home
 - **Custom Tunnel**: Connect to your own tunnel server with a fixed domain ([Setup Guide](docs/custom-tunnel.md))
 - **WeChat Bot (ClawBot / iLink)**: Scan a QR code to log in a WeChat personal account, then chat with, control, and approve your DeepSeek Harness agents right inside WeChat. **Multi-workspace selection, restart-persistent sessions, grouped session listing with titles, media (image/file/voice) transfer, and permission approvals** — over Tencent's official iLink Bot API, no public server or tunnel required ([Usage Guide](docs/wechat-usage.md))
+- **QQ Bot (OpenAPI v2)**: Connect your QQ Bot to receive private/group messages, send Markdown, button keyboards, and rich media. **Full event coverage (C2C / GROUP_AT_MESSAGE_CREATE), auto token refresh, reconnection with backoff, message deduplication** — over Tencent's official QQ Bot OpenAPI v2 ([Usage Guide](docs/qq-usage.md))
 - **IM Integration (More Planned)**: WeChat / QQ / Feishu / OpenClaw direct chat integration
 - **Security Alerts**: URLs and QR codes with access warnings to prevent accidental sharing
 - **Auto Version Check**: Automatic update detection when entering the panel
@@ -35,7 +36,7 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 |--------|-------------|--------|
 | **Platform Abstraction** | Platform-agnostic core (sessions / approvals / commands / digest) shared across IM channels | ✅ **Completed** (v2.0.0) |
 | **WeChat** | Chat with your Agent directly in WeChat | ✅ Supported (workspaces / persisted sessions / media / approvals) |
-| **QQ Bot** | QQ bot integration for group/private chat | 🚧 Next (platform adapter implementation) |
+| **QQ Bot** | QQ bot integration for group/private chat | ✅ **Completed** (v2.1.0) — Markdown / buttons / rich media |
 | **Feishu** | Feishu message/bot integration for workplace scenarios | Planned |
 | **OpenClaw** | Integration with OpenClaw ecosystem | Planned |
 | **Telegram** | Self-hosted IM channel | Planned |

package/README.zh-CN.md

@@ -18,7 +18,8 @@
 - **Cloudflare 隧道**：一键暴露公网地址，随时随地连接，出差在外、不在家也能接着干，无需自建公网服务器
 - **自建隧道**：连接自己的隧道服务器，获得固定域名（[搭建教程](docs/custom-tunnel.md)）
 - **微信 Bot（ClawBot / iLink）**：扫码登录微信个人号后，直接在微信里对话、控制 DeepSeek Harness 的 agent。**支持多工作区选择、会话跨重启持久化、按工作区分组查看、媒体（图片/文件/语音）收发、权限审批**——走腾讯官方 iLink Bot API，无需公网（[使用说明](docs/wechat-usage.md)）
-- **IM 集成（更多平台规划中）**：QQ / 飞书 / OpenClaw，直接在聊天软件里呼唤你的 Agent
+- **QQ Bot（OpenAPI v2）**：接入 QQ 机器人，私聊/群聊接收消息，发送 Markdown、按钮键盘和富媒体。**完整事件覆盖（C2C / GROUP_AT_MESSAGE_CREATE）、Token 自动刷新、断线重连、消息去重**——走腾讯官方 QQ Bot OpenAPI v2（[使用说明](docs/qq-usage.md)）
+- **IM 集成（更多平台规划中）**：飞书 / OpenClaw，直接在聊天软件里呼唤你的 Agent
 - **安全提示**：URL 和二维码带访问警告，防止误分享
 - **版本检查**：进入面板自动检测是否有新版本
 
@@ -35,7 +36,7 @@
 |------|------|------|
 | **平台抽象层** | 平台无关的核心（会话/审批/命令/digest）跨 IM 渠道复用 | ✅ **已完成**（v2.0.0） |
 | **微信** | 在微信里直接与你的 Agent 对话 | ✅ 已支持（多工作区 / 会话持久化 / 媒体 / 审批） |
-| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent | 🚧 下一步（平台适配器实现） |
+| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent | ✅ **已完成**（v2.1.0）— Markdown / 按钮 / 富媒体 |
 | **飞书** | 飞书消息/机器人集成，办公场景直接调用 | 规划中 |
 | **OpenClaw** | 与 OpenClaw 生态打通 | 规划中 |
 | **Telegram** | 适合自托管的 IM 渠道 | 规划中 |

package/lib/index.js

@@ -545,6 +545,9 @@ function apply(ctx, config = {}) {
           accountId: cfg.accountId,
         });
         logger.info('dsh-bridge: loaded saved qq bot config, starting gateway');
+        await qq.start().catch((err) => {
+          logger.error('dsh-bridge: qq auto-start failed: %s', err?.message ?? err);
+        });
       }
     }
   }).catch(() => {});

package/lib/qq/gateway.js

@@ -14,6 +14,7 @@ const RECONNECT_DELAY_MS = 3000
 
 export const QQ_INTENTS = {
   C2C_MESSAGE_CREATE: 1 << 25,
+  INTERACTION_CREATE: 1 << 26,
   GROUP_AT_MESSAGE_CREATE: 1 << 30,
   PUBLIC_GUILD_MESSAGES: 1 << 9,
   DIRECT_MESSAGE: 1 << 12,
@@ -60,6 +61,7 @@ function normalizeEvent(payload) {
       peerId: data.author?.user_openid || data.user_openid,
       text: stringValue(data.content).trim(),
       message: data,
+      messageReference: data.message_reference,
     }
   }
   if (event === 'GROUP_AT_MESSAGE_CREATE') {
@@ -71,6 +73,7 @@ function normalizeEvent(payload) {
       groupId: data.group_openid || data.group_id,
       text: stringValue(data.content).trim(),
       message: data,
+      messageReference: data.message_reference,
     }
   }
   if (event === 'AT_MESSAGE_CREATE') {
@@ -82,6 +85,19 @@ function normalizeEvent(payload) {
       guildId: data.guild_id,
       text: stringValue(data.content).trim(),
       message: data,
+      messageReference: data.message_reference,
+    }
+  }
+  if (event === 'INTERACTION_CREATE') {
+    return {
+      type: 'interaction', scope: data.group_openid ? 'group' : 'c2c', event,
+      id: data.id,
+      interactionId: data.id,
+      senderId: data.group_member_openid || data.user_openid,
+      peerId: data.group_openid || data.user_openid,
+      groupId: data.group_openid,
+      data: data.data,
+      message: data,
     }
   }
   return { type: 'event', event, message: data }
@@ -98,7 +114,7 @@ export class QqGateway extends Service {
       accessToken: config.accessToken || '',
       accessTokenExpiresAt: Number(config.accessTokenExpiresAt || 0),
       gatewayUrl: config.gatewayUrl || '',
-      intents: Number(config.intents ?? (QQ_INTENTS.C2C_MESSAGE_CREATE | QQ_INTENTS.GROUP_AT_MESSAGE_CREATE)),
+      intents: Number(config.intents ?? (QQ_INTENTS.C2C_MESSAGE_CREATE | QQ_INTENTS.GROUP_AT_MESSAGE_CREATE | QQ_INTENTS.INTERACTION_CREATE)),
       reconnectDelayMs: Number(config.reconnectDelayMs ?? RECONNECT_DELAY_MS),
       apiTimeoutMs: Number(config.apiTimeoutMs ?? REQUEST_TIMEOUT_MS),
     }
@@ -253,6 +269,9 @@ export class QqGateway extends Service {
       if (event.type === 'message' && event.id && !this.seen(event.id)) {
         this.ctx.emit?.('qq/message', event)
       }
+      if (event.type === 'interaction' && event.interactionId) {
+        this.ctx.emit?.('qq/interaction', event)
+      }
       return
     }
     if (op === 7) { try { ws.close() } catch {}; return }
@@ -311,11 +330,11 @@ export class QqGateway extends Service {
     })
   }
 
-  async sendKeyboard(peerId, keyboard, opts = {}) {
+  async sendKeyboard(peerId, content, keyboard, opts = {}) {
     return this.api(this.endpoint(peerId, opts.scope), {
       method: 'POST',
       body: {
-        content: opts.content || '',
+        content: stringValue(content),
         keyboard,
         msg_type: 2,
         msg_id: opts.msgId,
@@ -335,7 +354,43 @@ export class QqGateway extends Service {
     })
   }
 
-  async sendTyping() { return { ok: false, unsupported: true } }
+  async sendStream(peerId, content, opts = {}) {
+    const endpoint = this.endpoint(peerId, opts.scope, 'stream-messages')
+    return this.api(endpoint, {
+      method: 'POST',
+      body: {
+        content: stringValue(content).slice(0, MAX_MESSAGE_CHARS),
+        msg_type: 0,
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+        input_state: opts.inputState, // 0=结束输入, 1=输入中
+      },
+    })
+  }
+
+  async respondInteraction(interactionId, response) {
+    return this.api(`/interactions/${encodeURIComponent(interactionId)}`, {
+      method: 'PUT',
+      body: response,
+    })
+  }
+
+  async sendTyping(peerId, opts = {}) {
+    // QQ Bot API v2 通过流式消息的 input_state 参数控制输入状态
+    // input_state: 0=结束输入, 1=输入中
+    // 参考：https://bot.q.qq.com/wiki/develop/api-v2/autogen/api/v2_users_user_openid_stream_messages.post.html
+    const endpoint = this.endpoint(peerId, opts.scope, 'stream-messages')
+    return this.api(endpoint, {
+      method: 'POST',
+      body: {
+        content: '', // 仅设置输入状态，不发送内容
+        msg_type: 0,
+        input_state: 1, // 1=输入中
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+      },
+    })
+  }
 
   setCredentials(values = {}) {
     for (const key of ['appId', 'clientSecret', 'accessToken', 'accessTokenExpiresAt', 'gatewayUrl', 'intents']) {

package/lib/qq/node.js

@@ -19,7 +19,8 @@ function makePlatform(gateway) {
     get accountId() { return gateway.accountId ?? '' },
     get capabilities() { return gateway.capabilities },
     sendText: (peer, text) => gateway.sendText(peer, text, {}),
-    sendTyping: (peer, state) => gateway.sendTyping(peer, state),
+    sendTyping: (peer, opts) => gateway.sendTyping(peer, opts),
+    sendKeyboard: (peer, content, keyboard) => gateway.sendKeyboard(peer, content, keyboard, {}),
   }
 }
 
@@ -42,11 +43,94 @@ export class QqConversationNode extends ConversationBridge {
       onActiveSessionChange,
     })
     this.gateway = ctx.qq
+    this.lastMessageId = null // 存储最后发送的消息 ID，用于消息引用
 
     // 订阅网关入站事件
     this.ctx.on('qq/message', (event) => {
       void this._handleInbound(event)
     })
+    this.ctx.on('qq/interaction', (event) => {
+      void this._handleInteraction(event)
+    })
+  }
+
+  // ---- 出站：覆盖 sendText，在提示消息中添加按钮 ----
+
+  async sendText(text) {
+    const peer = this.peerId
+    if (!peer) return
+    
+    // 检测是否是提示用户开始新会话的消息
+    const isPromptMessage = text.includes('没有活动会话') || text.includes('恢复会话失败')
+    
+    if (isPromptMessage) {
+      // 发送带按钮的消息，方便用户快速操作
+      const keyboard = {
+        rows: [
+          {
+            buttons: [
+              { id: 'new_conversation', render_data: { label: '🆕 新建会话', visited_label: '新建会话' }, action: { type: 2, permission: { type: 2 } } },
+              { id: 'list_sessions', render_data: { label: '📋 会话列表', visited_label: '会话列表' }, action: { type: 2, permission: { type: 2 } } },
+            ],
+          },
+          {
+            buttons: [
+              { id: 'help', render_data: { label: '❓ 帮助', visited_label: '帮助' }, action: { type: 2, permission: { type: 2 } } },
+            ],
+          },
+        ],
+      }
+      const result = await this.platform.sendKeyboard(peer, text, keyboard)
+      // 保存消息 ID
+      if (result?.data?.message_id) {
+        this.lastMessageId = result.data.message_id
+      }
+      return result
+    }
+    
+    // 其他消息使用流式发送
+    const content = String(text || '').trim()
+    if (content.length === 0) return { success: true }
+    
+    const STREAM_CHUNK_SIZE = 200
+    
+    // 如果消息较短，直接发送普通消息
+    if (content.length <= STREAM_CHUNK_SIZE) {
+      const result = await this.gateway.sendText(peer, content, {})
+      // 保存消息 ID
+      if (result?.data?.message_id) {
+        this.lastMessageId = result.data.message_id
+      }
+      return result
+    }
+    
+    // 流式发送：把内容切分成多段
+    const chunks = []
+    for (let i = 0; i < content.length; i += STREAM_CHUNK_SIZE) {
+      chunks.push(content.slice(i, i + STREAM_CHUNK_SIZE))
+    }
+    
+    // 逐段发送流式消息
+    let firstMsgId = null
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]
+      const isLast = i === chunks.length - 1
+      const result = await this.gateway.sendStream(peer, chunk, {
+        msgId: firstMsgId, // 后续段关联到第一段
+        inputState: isLast ? 0 : 1, // 最后一段结束输入状态，其他段显示输入中
+      })
+      if (!firstMsgId && result?.data?.message_id) {
+        firstMsgId = result.data.message_id
+        this.lastMessageId = firstMsgId // 保存第一段消息 ID
+      }
+      if (result?.error) {
+        return { success: false, error: result.error }
+      }
+      // 流式发送间隔稍短，避免刷屏
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    
+    return { success: true }
   }
 
   // ---- 入站 ----
@@ -70,9 +154,53 @@ export class QqConversationNode extends ConversationBridge {
     // 群聊：仅在群聊 @ 机器人事件中处理（GROUP_AT_MESSAGE_CREATE 已由网关归一化）
     const isGroup = event.scope === 'group' || event.scope === 'guild'
 
+    // 检测消息引用（文本交互）：如果用户回复了机器人的消息，且当前没有活动会话或消息以 /new 开头，
+    // 则自动创建新会话并发送消息
+    const messageReference = event.messageReference
+    if (messageReference && !this.activeSessionId && !text.startsWith('/')) {
+      this.logger?.info?.(`[dsh-bridge qq] detected message reference from ${sender}, auto-starting conversation`)
+      // 先创建新会话，再处理消息
+      await this.handleInbound({ senderId: sender, text: '/new', isGroup })
+      // 等待一小段时间确保会话创建完成
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+
     // 交给平台无关核心：白名单/群消息/命令路由/agent 分发
     await this.handleInbound({ senderId: sender, text, isGroup })
   }
+
+  // ---- 互动事件 ----
+
+  async _handleInteraction(event) {
+    const sender = String(event.senderId ?? '').trim()
+    if (!sender) return
+
+    // 快速预检查：白名单非空时，未授权发件人直接忽略
+    if (!this.isAllowed(sender) && this.config.allowFrom.length > 0) {
+      this.logger?.info?.(`[dsh-bridge qq] ignore interaction from non-allowlisted sender ${sender}`)
+      return
+    }
+
+    const data = event.data || {}
+    const resolved = data.resolved || {}
+    const buttonId = resolved.button_id || ''
+
+    // 响应互动
+    await this.gateway.respondInteraction(event.interactionId, {
+      code: 0,
+    })
+
+    // 根据按钮 ID 执行对应操作
+    if (buttonId === 'new_conversation') {
+      await this.handleInbound({ senderId: sender, text: '/new', isGroup: event.scope === 'group' })
+    } else if (buttonId === 'list_sessions') {
+      await this.handleInbound({ senderId: sender, text: '/list', isGroup: event.scope === 'group' })
+    } else if (buttonId === 'help') {
+      await this.handleInbound({ senderId: sender, text: '/help', isGroup: event.scope === 'group' })
+    } else {
+      this.logger?.info?.(`[dsh-bridge qq] unknown button interaction: ${buttonId}`)
+    }
+  }
 }
 
 // 导出，便于测试与复用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenbin_wb/dsh-bridge",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "手机扫码即可在移动端/公网继续用 DeepSeek Harness，人不在电脑前也能接着干。一键局域网二维码、Cloudflare 公网隧道、自建隧道与微信 Bot（多工作区/会话持久化/媒体/审批），无需自己搭公网服务器。",
   "type": "module",
   "main": "lib/index.js",
@@ -22,6 +22,10 @@
     "docs/custom-tunnel.md",
     "docs/wechat-usage.md"
   ],
+  "scripts": {
+    "build:client": "node client/build.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
   "dependencies": {
     "qrcode": "^1.5.3",
     "ws": "^8.18.0",
@@ -81,9 +85,5 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build:client": "node client/build.mjs",
-    "test": "node --test test/*.test.mjs"
   }
-}
+}