@raolin2025/claude-code-node 2.4.3 → 2.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.4.3",
-  "description": "Node.js AI Code Agent CLI - Zero dependencies, pure JavaScript, security hardened, multi-channel notifications, Telegram & QQ Bot remote programming",
+  "version": "2.5.0",
+  "description": "Node.js AI Code Agent CLI - Zero dependencies, pure JavaScript, security hardened, multi-channel notifications, Telegram & QQ Bot remote programming, rich media upload, multi-account management",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/channel/index.js

@@ -195,82 +195,140 @@ class TelegramChannel {
 }
 
 // ============================================================
-// QQ Bot 通道适配器 v2.0
+// QQ Bot 通道适配器 v3.0 — 多账户、权限、富媒体
 // ============================================================
 
+import { QQBotEnhanced } from './qqbot-enhanced.js'
+import { QQBotAccountManager } from './qqbot-account-manager.js'
+
 /**
- * QQ Bot 通道适配器 — 独立、零依赖
+ * QQ Bot 增强版通道适配器
  *
- * 使用 QQ Bot API v2，仅需 appId + clientSecret
+ * 功能：
+ * - 多账户管理（从配置文件加载）
+ * - 权限控制（dmPolicy/groupPolicy + allowFrom 白名单）
+ * - 自动解析 <qqmedia> 标签并上传富媒体
+ * - 支持图片、文件、语音上传（限于 ~/.openclaw/media/qqbot）
+ * - WebSocket 监听（可选）
  */
 class QQBotChannel {
-  constructor(config = {}) {
-    this.appId = config.appId || process.env.CC_NODE_CHANNEL_QQBOT_APPID || ''
-    this.secret = config.secret || config.clientSecret || process.env.CC_NODE_CHANNEL_QQBOT_SECRET || ''
-    this._token = null
-    this._tokenCache = { token: null, expireAt: 0 }
-    this.channelId = config.channelId || ''
-    this.groupOpenId = config.groupOpenId || ''
-  }
+  constructor(config = {}, globalConfig = {}) {
+    this.name = 'qqbot'
+    this.enabled = config.enabled !== false
+
+    // 合并全局配置
+    const qqbotConfig = {
+      ...globalConfig.qqbot,
+      ...config
+    }
 
-  get name() { return 'qqbot' }
+    // 创建增强版 QQBot 实例
+    this.bot = new QQBotEnhanced(qqbotConfig)
 
-  async _getToken() {
-    if (this._tokenCache.token && Date.now() < this._tokenCache.expireAt - 300000) {
-      return this._tokenCache.token
-    }
-    const res = await fetch('https://bots.qq.com/app/getAppAccessToken', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ appId: this.appId, clientSecret: this.secret }),
-    })
-    if (!res.ok) throw new Error('QQ Token API ' + res.status)
-    const data = JSON.parse(await res.text())
-    if (!data.access_token) throw new Error('Token API no access_token')
-    this._tokenCache.token = data.access_token
-    this._tokenCache.expireAt = Date.now() + (data.expires_in || 7200) * 1000
-    return data.access_token
+    // 通道特定配置
+    this.scope = config.scope || 'group'  // 默认发送到群
+    this.defaultTargetId = config.targetId || config.groupOpenId || ''
+
+    // WebSocket 监听状态
+    this._listener = null
+    this._onMessageCallback = null
   }
 
-  async send(text, options = {}) {
-    if (!this.appId || !this.secret) {
-      return [{ channel: 'qqbot', ok: false, error: '需要 appId 和 clientSecret' }]
+  /** 启动消息监听 */
+  async listen(onMessage) {
+    if (!this.enabled) {
+      console.warn('[QQBotChannel] 通道未启用')
+      return
     }
     try {
-      const token = await this._getToken()
-      const results = []
-
-      const scope = options.scope || (this.groupOpenId ? 'group' : '')
-      const targetId = options.targetId || this.groupOpenId || this.channelId
+      this._onMessageCallback = onMessage
+      await this.bot.listen(this._handleIncomingMessage.bind(this))
+      console.log('[QQBotChannel] 监听已启动')
+    } catch (e) {
+      console.error('[QQBotChannel] 监听启动失败:', e.message)
+      throw e
+    }
+  }
 
-      if (!scope || !targetId) {
-        return [{ channel: 'qqbot', ok: false, error: '未配置目标 (groupOpenId)' }]
-      }
+  _handleIncomingMessage(msg) {
+    // 包装为统一消息格式，转发给回调
+    if (this._onMessageCallback) {
+      this._onMessageCallback({
+        channel: 'qqbot',
+        text: msg.text,
+        scope: msg.scope,
+        chatId: msg.chatId,
+        from: msg.from,
+        messageId: msg.messageId,
+        raw: msg.raw,
+        accountId: msg.accountId
+      })
+    }
+  }
 
-      const path = scope === 'group'
-        ? '/v2/groups/' + targetId + '/messages'
-        : '/v2/users/' + targetId + '/messages'
+  /** 停止监听 */
+  stop() {
+    if (this.bot) {
+      this.bot.stop()
+    }
+  }
 
-      const body = { content: text.slice(0, 2000), msg_type: 0 }
-      if (options.replyMsgId) body.msg_id = options.replyMsgId
+  /** 发送消息（支持富媒体标签） */
+  async send(text, options = {}) {
+    if (!this.enabled) {
+      return [{ channel: 'qqbot', ok: false, error: '通道未启用' }]
+    }
 
-      const r = await fetch('https://api.sgroup.qq.com' + path, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Authorization: 'QQBot ' + token },
-        body: JSON.stringify(body),
+    try {
+      const scope = options.scope || this.scope
+      const targetId = options.targetId || this.defaultTargetId
+      const accountId = options.accountId || null
+
+      const result = await this.bot.send({
+        text,
+        scope,
+        targetId,
+        accountId,
+        opts: { replyMsgId: options.replyMsgId }
       })
-      if (!r.ok) {
-        const errText = await r.text().catch(() => '')
-        throw new Error('HTTP ' + r.status + ': ' + errText.slice(0, 100))
-      }
-      results.push({ channel: 'qqbot', ok: true })
-      return results
+
+      return result.ok
+        ? [{ channel: 'qqbot', ok: true }]
+        : [{ channel: 'qqbot', ok: false, error: result.error }]
     } catch (e) {
-      return [{ channel: 'qqbot', ok: false, error: e.message.slice(0, 200) }]
+      console.error('[QQBotChannel] 发送失败:', e)
+      return [{ channel: 'qqbot', ok: false, error: e.message }]
+    }
+  }
+
+  /** 支持的工具调用（提供给 Agent） */
+  get tools() {
+    return {
+      /** 发送 QQ 消息 */
+      qqbot_send: async (args) => {
+        const { text, scope = this.scope, targetId = this.defaultTargetId } = args
+        const result = await this.send(text, { scope, targetId })
+        return result[0]
+      },
+
+      /** 获取账户列表 */
+      qqbot_list_accounts: async () => {
+        const accounts = this.bot.accountManager.getAllAccounts()
+        return accounts.map(a => ({ id: a.id, name: a.name, enabled: a.enabled }))
+      },
+
+      /** 发送图片（直接文件路径） */
+      qqbot_send_image: async (args) => {
+        const { path, scope = this.scope, targetId = this.defaultTargetId } = args
+        // 这里需要支持直接的图片发送，不通过文本标签
+        // 临时方案：调用 bot 的底层方法
+        return { ok: false, error: '暂未实现' }
+      }
     }
   }
 }
 
+
 // ============================================================
 // 已有适配器（保持兼容）
 // ============================================================

package/src/channel/qqbot-account-manager.js

@@ -0,0 +1,117 @@
+/**
+ * QQBot 多账户管理器
+ *
+ * 功能：
+ * - 管理多个 QQ 机器人账户
+ * - 自动选择账户发送消息
+ * - 支持账户级别的权限控制
+ */
+
+export class QQBotAccount {
+  constructor(config, globalConfig = {}) {
+    this.id = config.id || 'default'
+    this.name = config.name || this.id
+    this.enabled = config.enabled !== false
+
+    // 认证信息（支持环境变量或直接配置）
+    this.appId = config.appId || process.env[`CC_NODE_CHANNEL_QQBOT_${this.id.toUpperCase()}_APPID`] || ''
+    this.clientSecret = config.clientSecret || process.env[`CC_NODE_CHANNEL_QQBOT_${this.id.toUpperCase()}_SECRET`] || ''
+
+    // 权限策略
+    this.dmPolicy = config.dmPolicy || globalConfig.dmPolicy || 'open'  // 'open'|'allowlist'|'disabled'
+    this.groupPolicy = config.groupPolicy || globalConfig.groupPolicy || 'open'
+
+    // 白名单（格式: "qqbot:openid" 或 "qqbot:group:group_openid"）
+    this.allowFrom = config.allowFrom || globalConfig.allowFrom || ['*']
+
+    // 目标群/用户（可选默认值）
+    this.defaultTargets = config.defaultTargets || {}
+
+    // 高级配置
+    this.markdownSupport = config.markdownSupport !== false
+    this.streaming = config.streaming || { mode: 'partial' }
+
+    // 验证
+    if (!this.appId || !this.clientSecret) {
+      console.warn(`[QQBot] 账户 ${this.id} 未配置 appId/clientSecret`)
+    }
+  }
+
+  /** 检查是否允许来自指定源的消息 */
+  isAllowed(scope, openid, groupOpenid = null) {
+    // 如果允许所有人
+    if (this.allowFrom.includes('*')) return true
+
+    // 检查具体白名单
+    const checks = []
+    if (scope === 'c2c') {
+      checks.push(`qqbot:${openid}`)
+    } else if (scope === 'group' && groupOpenid) {
+      checks.push(`qqbot:${groupOpenid}`)  // 群级别
+      checks.push(`qqbot:group:${groupOpenid}:${openid}`)  // 用户级别
+    }
+
+    return checks.some(c => this.allowFrom.includes(c))
+  }
+
+  /** 获取目标 ID（优先级：传入 > 默认配置） */
+  getTargetId(scope, overrideTargetId = null) {
+    if (overrideTargetId) return overrideTargetId
+    return this.defaultTargets[scope] || null
+  }
+}
+
+export class QQBotAccountManager {
+  constructor(config = {}) {
+    this.accounts = new Map()
+    this.defaultAccountId = config.defaultAccount || 'default'
+    this.globalConfig = {
+      dmPolicy: config.dmPolicy || 'open',
+      groupPolicy: config.groupPolicy || 'open',
+      allowFrom: config.allowFrom || ['*']
+    }
+
+    // 初始化所有账户
+    if (config.accounts) {
+      for (const [id, accountConfig] of Object.entries(config.accounts)) {
+        this.addAccount(new QQBotAccount(accountConfig, this.globalConfig))
+      }
+    }
+
+    // 确保有默认账户
+    if (!this.accounts.has(this.defaultAccountId)) {
+      this.addAccount(new QQBotAccount({ id: this.defaultAccountId }, this.globalConfig))
+    }
+  }
+
+  addAccount(account) {
+    this.accounts.set(account.id, account)
+    return this
+  }
+
+  getAccount(id = null) {
+    const targetId = id || this.defaultAccountId
+    return this.accounts.get(targetId)
+  }
+
+  getAllAccounts() {
+    return Array.from(this.accounts.values()).filter(a => a.enabled)
+  }
+
+  /** 根据消息上下文选择账户（基于 routing 规则） */
+  selectAccount(scope, openid, groupOpenid = null) {
+    // 遍历所有账户，找到第一个匹配权限的
+    for (const account of this.getAllAccounts()) {
+      const policy = scope === 'c2c' ? account.dmPolicy : account.groupPolicy
+      if (policy === 'disabled') continue
+
+      if (account.isAllowed(scope, openid, groupOpenid)) {
+        return account
+      }
+    }
+
+    // 没匹配到，返回默认账户（如果默认账户开启了的话）
+    const defaultAcc = this.getAccount()
+    return defaultAcc && defaultAcc.enabled ? defaultAcc : null
+  }
+}

package/src/channel/qqbot-enhanced.js

@@ -0,0 +1,470 @@
+/**
+ * QQ Bot 增强版 — 多账户、权限控制、富媒体、工具集成
+ *
+ * 功能：
+ * - 多账户管理（基于配置路由）
+ * - 权限控制（dmPolicy/groupPolicy + allowFrom 白名单）
+ * - 富媒体上传（图片/文件/语音）
+ * - 支持 <qqmedia> 标签自动替换
+ * - Markdown 安全编码
+ *
+ * 与 OpenClaw 能力对齐的独立实现
+ */
+
+import { QQBotAccountManager } from './qqbot-account-manager.js'
+
+const API_BASE = 'https://api.sgroup.qq.com'
+const TOKEN_URL = 'https://bots.qq.com/app/getAppAccessToken'
+
+// ── Token 管理 ─────────────────────────────────────────────
+
+class TokenCache {
+  constructor() {
+    this._tokens = new Map() // appId → { token, expireAt }
+  }
+
+  async get(appId, clientSecret) {
+    const cache = this._tokens.get(appId)
+    if (cache && Date.now() < cache.expireAt - 300_000) {
+      return cache.token
+    }
+
+    const res = await fetch(TOKEN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appId, clientSecret }),
+    })
+    if (!res.ok) {
+      const t = await res.text().catch(() => '')
+      throw new Error(`Token API ${res.status}: ${t.slice(0, 200)}`)
+    }
+    const data = JSON.parse(await res.text())
+    if (!data.access_token) throw new Error('Token API 未返回 access_token')
+
+    const token = data.access_token
+    const expireAt = Date.now() + (data.expires_in || 7200) * 1000
+    this._tokens.set(appId, { token, expireAt })
+    return token
+  }
+
+  clear(appId) {
+    if (appId) {
+      this._tokens.delete(appId)
+    } else {
+      this._tokens.clear()
+    }
+  }
+}
+
+// ── API 调用 ────────────────────────────────────────────────
+
+async function apiCall(token, method, path, body, timeoutMs = 30_000) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      method,
+      headers: {
+        Authorization: `QQBot ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: body && ['POST', 'PUT', 'PATCH'].includes(method) ? JSON.stringify(body) : undefined,
+      signal: ac.signal,
+    })
+    const raw = await res.text()
+    if (!res.ok) {
+      let detail = raw.slice(0, 200)
+      try { detail = JSON.parse(raw).message || detail } catch {}
+      throw new Error(`API ${method} ${path} → ${res.status}: ${detail}`)
+    }
+    return raw.trim() ? JSON.parse(raw) : null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ── 富媒体处理 ─────────────────────────────────────────────
+
+/**
+ * 解析文本中的 <qqmedia> 标签，提取文件路径
+ * @param {string} text
+ * @returns {{ text: string, mediaFiles: Array<{path: string, type: string}> }}
+ */
+export function parseQQMediaTags(text) {
+  const mediaRegex = /<qqmedia>(.*?)<\/qqmedia>/g
+  const mediaFiles = []
+  let match
+  let parsedText = text
+
+  while ((match = mediaRegex.exec(text)) !== null) {
+    const path = match[1].trim()
+    const ext = path.split('.').pop().toLowerCase()
+    let type = 'file'
+    if (['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp'].includes(ext)) type = 'image'
+    else if (['silk', 'wav', 'mp3', 'ogg', 'aac', 'flac', 'm4a'].includes(ext)) type = 'audio'
+    else if (['mp4', 'mov', 'avi', 'mkv', 'webm'].includes(ext)) type = 'video'
+
+    mediaFiles.push({ path, type })
+    // 替换标签为占位符
+    parsedText = parsedText.replace(match[0], `[上传${type}: ${path.split('/').pop()}]`)
+  }
+
+  return { text: parsedText, mediaFiles }
+}
+
+// ── 增强 QQBot 类 ───────────────────────────────────────────
+
+export class QQBotEnhanced {
+  constructor(config = {}) {
+    // 账户管理器
+    this.accountManager = new QQBotAccountManager(config)
+
+    // Token 缓存（多账户）
+    this._tokenCache = new TokenCache()
+
+    // 监听状态
+    this.onMessage = null
+    this._listening = false
+    this._ws = null
+    this._hbTimer = null
+    this._seq = 0
+    this._sessionId = null
+
+    // WebSocket 连接参数（所有账户共享一个 WS，通过 intents 接收所有消息）
+    this._allAccounts = [] // 将用于存储所有账户的 appId 用于 WS identify
+  }
+
+  /** 获取指定账户的 token */
+  async _getToken(account) {
+    return await this._tokenCache.get(account.appId, account.clientSecret)
+  }
+
+  // ── 发送消息（主入口） ───────────────────────────────────
+
+  /**
+   * 发送消息（自动处理富媒体、权限检查、账户路由）
+   *
+   * @param {object} params
+   * @param {string} params.text - 消息文本（支持 <qqmedia> 标签）
+   * @param {'c2c'|'group'} [params.scope] - 发送范围
+   * @param {string} [params.targetId] - 目标 openid / group_openid
+   * @param {string} [params.accountId] - 指定账户（不指定则自动路由）
+   * @param {object} [params.opts] - 原始发送选项
+   * @param {string} [params.opts.replyMsgId] - 回复消息 ID
+   * @returns {Promise<{ok: boolean, error?: string, accountId?: string}>}
+   */
+  async send({ text, scope, targetId, accountId, opts = {} }) {
+    try {
+      // 1. 选择账户
+      const account = accountId
+        ? this.accountManager.getAccount(accountId)
+        : this.accountManager.selectAccount(scope, null, targetId) // 注意：权限检查需要 openid，这里简化
+
+      if (!account) {
+        return { ok: false, error: '无可用账户或权限不足' }
+      }
+
+      // 2. 解析 <qqmedia> 标签
+      const { text: cleanText, mediaFiles } = parseQQMediaTags(text)
+
+      // 3. 发送文本
+      const resolvedTargetId = targetId || account.getTargetId(scope)
+      if (!resolvedTargetId) {
+        return { ok: false, error: '未配置目标 ID (targetId)' }
+      }
+
+      // 发送主文本
+      await this._sendText(account, scope, resolvedTargetId, cleanText, opts)
+
+      // 4. 发送富媒体（如果有）
+      for (const media of mediaFiles) {
+        await this._sendMedia(account, scope, resolvedTargetId, media)
+      }
+
+      return { ok: true, accountId: account.id }
+    } catch (e) {
+      console.error('[QQBotEnhanced] 发送失败:', e)
+      return { ok: false, error: e.message }
+    }
+  }
+
+  async _sendText(account, scope, targetId, content, opts) {
+    const token = await this._getToken(account)
+    const path = scope === 'group'
+      ? `/v2/groups/${targetId}/messages`
+      : `/v2/users/${targetId}/messages`
+    const body = { content: content.slice(0, 2000), msg_type: 0 }
+    if (opts.replyMsgId) body.msg_id = opts.replyMsgId
+
+    return apiCall(token, 'POST', path, body)
+  }
+
+  async _sendMedia(account, scope, targetId, { path: filePath, type }) {
+    const token = await this._getToken(account)
+
+    // 文件类型映射
+    const fileTypeMap = {
+      image: 1,
+      video: 2,
+      audio: 3,
+      file: 4
+    }
+    const fileType = fileTypeMap[type] || 4
+
+    // 检查文件是否存在
+    const { existsSync } = await import('node:fs')
+    if (!existsSync(filePath)) {
+      throw new Error(`文件不存在: ${filePath}`)
+    }
+
+    // 获取绝对路径（如果是 media/qqbot 下的）
+    const { resolve } = await import('node:path')
+    const absPath = resolve(filePath)
+
+    // 检查媒体目录限制
+    const allowedDirs = [
+      process.env.HOME + '/.openclaw/media/qqbot',
+      process.env.HOME + '/.openclaw/media'
+    ]
+    const isAllowed = allowedDirs.some(dir => absPath.startsWith(dir))
+    if (!isAllowed) {
+      throw new Error(`安全限制: 文件必须在 ~/.openclaw/media/qqbot 或 ~/.openclaw/media 目录下`)
+    }
+
+    // 上传
+    const { readFileSync } = await import('node:fs')
+    const buf = readFileSync(absPath)
+    const uploadResult = await uploadMedia(token, scope, targetId, {
+      fileType,
+      base64: buf.toString('base64')
+    })
+
+    if (!uploadResult?.file_info) {
+      throw new Error(`媒体上传失败: ${JSON.stringify(uploadResult)}`)
+    }
+
+    // 发送媒体消息
+    const targetPath = scope === 'group'
+      ? `/v2/groups/${targetId}/messages`
+      : `/v2/users/${targetId}/messages`
+    const body = { msg_type: 7, media: { file_info: uploadResult.file_info } }
+
+    return apiCall(token, 'POST', targetPath, body)
+  }
+
+  // ── WebSocket 监听 ──────────────────────────────────────
+
+  /**
+   * 启动监听（接收 QQ 消息）
+   * 注意：WebSocket 只能连接一个账户，所以这里选择第一个启用的账户
+   */
+  async listen(onMessage) {
+    this.onMessage = onMessage
+    this._listening = true
+
+    // 选择一个用于 WS 的账户（第一个启用的）
+    const listenAccount = this.accountManager.getAllAccounts()[0]
+    if (!listenAccount) {
+      throw new Error('无可用账户用于监听')
+    }
+
+    await this._connect(listenAccount)
+  }
+
+  async _connect(account) {
+    let delay = 1000
+    while (this._listening) {
+      try {
+        const token = await this._getToken(account)
+        const url = await this._getWSURL(token)
+        log('[QQ] Connecting to WebSocket...')
+        const ws = await this._createWS(url)
+        this._ws = ws
+        delay = 1000
+
+        ws.onopen = () => log('[QQ] WebSocket connected')
+        ws.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data)
+            this._handleWS(msg, account)
+          } catch (e) {
+            log(`[QQ] WS parse error: ${e.message}`)
+          }
+        }
+        ws.onclose = (ev) => {
+          log(`[QQ] WS closed: ${ev.code}`)
+          this._hbTimer = null
+          if (this._listening) setTimeout(() => this._connect(account), delay)
+        }
+        ws.onerror = () => log('[QQ] WS error, reconnecting...')
+
+        // 等待 Identify 完成
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => reject(new Error('Identify timeout')), 15000)
+          const handler = (event) => {
+            try {
+              const parsed = JSON.parse(event.data)
+              if (parsed.op === 0 && parsed.t === 'READY') {
+                clearTimeout(timeout)
+                ws.removeEventListener('message', handler)
+                resolve()
+              }
+            } catch {}
+          }
+          ws.addEventListener('message', handler)
+        })
+        log('[QQ] Ready!')
+        return
+      } catch (e) {
+        log(`[QQ] Connection error: ${e.message}, retry in ${delay}ms`)
+        this._cleanupWS()
+        await this._sleep(delay)
+        delay = Math.min(delay * 2, 30000)
+      }
+    }
+  }
+
+  async _getWSURL(token) {
+    const res = await fetch(`${API_BASE}/websocket`, {
+      headers: { Authorization: `QQBot ${token}` },
+    })
+    if (!res.ok) throw new Error(`WS URL ${res.status}`)
+    const data = await res.json()
+    return data.url
+  }
+
+  _handleWS(msg, account) {
+    const { op, d, s, t } = msg
+    if (s) this._seq = s
+
+    switch (op) {
+      case 0: this._dispatch(t, d, account); break
+      case 7: log('[QQ] Reconnect requested'); this._reconnect(); break
+      case 9: log('[QQ] Invalid session'); this._sessionId = null; this._reconnect(); break
+      case 10:
+        this._startHeartbeat(d?.heartbeat_interval || 30000)
+        this._send({ op: 2, d: { token: `QQBot ${this._token}`, intents: 1 << 30 | 1 << 25 | 1 << 12, shard: [0, 1], properties: { $os: 'linux', $browser: 'cc-notify', $device: 'cc-notify' } } })
+        break
+      case 11: break
+    }
+  }
+
+  _dispatch(eventType, data, account) {
+    if (!data) return
+
+    let scope = 'c2c'
+    let chatId = ''
+    let from = ''
+    let content = ''
+
+    switch (eventType) {
+      case 'READY':
+        this._sessionId = data.session_id
+        break
+
+      case 'AT_MESSAGE_CREATE':
+      case 'MESSAGE_CREATE': {
+        scope = 'c2c'
+        chatId = data.author?.id || data.channel_id
+        from = data.author?.username || data.member?.nick || '?'
+        content = (data.content || '').replace(/<@!\d+>/g, '').trim()
+        break
+      }
+
+      case 'GROUP_AT_MESSAGE_CREATE': {
+        scope = 'group'
+        chatId = data.group_openid
+        from = data.author?.member_name || data.member?.nick || '?'
+        content = (data.content || '').replace(/<@bot\w*>/g, '').trim()
+        break
+      }
+
+      case 'DIRECT_MESSAGE_CREATE': {
+        scope = 'c2c'
+        chatId = data.author?.id || data.guild_id
+        from = data.author?.username || '?'
+        content = data.content || ''
+        break
+      }
+    }
+
+    if (!content) return
+
+    // 权限检查
+    if (scope === 'c2c') {
+      if (!account.isAllowed(scope, chatId)) {
+        log(`[QQ] 消息来自未授权用户 ${from} (${chatId})，已忽略`)
+        return
+      }
+    } else if (scope === 'group') {
+      const memberOpenId = data.author?.id
+      if (!account.isAllowed(scope, memberOpenId, chatId)) {
+        log(`[QQ] 群消息来自未授权用户 ${from} (${memberOpenId})，已忽略`)
+        return
+      }
+    }
+
+    log(`[QQ] ← ${from} (${scope}): ${content.slice(0, 60)}`)
+
+    this.onMessage?.({
+      text: content,
+      scope,
+      chatId,
+      from,
+      messageId: data.id,
+      raw: data,
+      accountId: account.id
+    })
+  }
+
+  _send(payload) {
+    if (this._ws?.readyState === 1) {
+      this._ws.send(JSON.stringify(payload))
+    }
+  }
+
+  _startHeartbeat(intervalMs) {
+    if (this._hbTimer) clearInterval(this._hbTimer)
+    this._hbTimer = setInterval(() => {
+      this._send({ op: 1, d: this._seq || null })
+    }, intervalMs)
+  }
+
+  _reconnect() {
+    this._cleanupWS()
+  }
+
+  _cleanupWS() {
+    if (this._hbTimer) { clearInterval(this._hbTimer); this._hbTimer = null }
+    if (this._ws) { try { this._ws.close() } catch {}; this._ws = null }
+  }
+
+  _createWS(url) {
+    return new Promise((resolve, reject) => {
+      if (typeof WebSocket === 'undefined') {
+        reject(new Error('WebSocket 不可用。请使用 Node.js >= 21'))
+        return
+      }
+      const ws = new WebSocket(url)
+      const t = setTimeout(() => { ws.close(); reject(new Error('WS timeout')) }, 10000)
+      ws.onopen = () => { clearTimeout(t); resolve(ws) }
+      ws.onerror = () => { clearTimeout(t); reject(new Error('WS failed')) }
+    })
+  }
+
+  /** 停止监听 */
+  stop() {
+    this._listening = false
+    this._cleanupWS()
+    log('[QQ] Listener stopped')
+  }
+
+  _sleep(ms) { return new Promise(r => setTimeout(r, ms)) }
+}
+
+function log(msg) {
+  const ts = new Date().toISOString().slice(11, 19)
+  process.stdout.write(`[${ts}] ${msg}\n`)
+}
+
+export default QQBotEnhanced

package/src/core/config.js

@@ -26,8 +26,26 @@ const DEFAULTS = {
     fileRead: { maxLines: 2000, maxSizeKB: 256 },
     webFetch: { timeout: 30, maxChars: 100000 },
   },
-    channels: {},
-    defaultChannel: null,
+  channels: {},
+  defaultChannel: null,
+  qqbot: {
+    enabled: false,
+    accounts: {
+      default: {
+        enabled: true,
+        appId: '',
+        clientSecret: '',
+        dmPolicy: 'open',
+        groupPolicy: 'open',
+        allowFrom: ['*'],
+        defaultTargets: {}
+      }
+    },
+    defaultAccount: 'default',
+    globalDmPolicy: 'open',
+    globalGroupPolicy: 'open',
+    globalAllowFrom: ['*']
+  },
   mcp: {
     servers: {},
   },

package/src/tools/index.js

@@ -11,6 +11,8 @@ import { webFetchTool } from './web-fetch.js'
 import { webSearchTool } from './web-search.js'
 import { askUserTool } from './ask-user.js'
 import { gitTool } from './git-tool.js'
+// QQ Bot 工具（外部包装）
+import { qqbotTools } from '../tools/qqbot-tools-wrapper.js'
 
 /**
  * 所有内置工具列表
@@ -26,6 +28,7 @@ export const builtinTools = [
   webSearchTool,
   askUserTool,
   gitTool,
+  ...qqbotTools
 ]
 
 /**

package/src/tools/qqbot-tools-wrapper.js

@@ -0,0 +1,185 @@
+/**
+ * QQ Bot 工具包装器 — 将新工具适配到 claude-code-node 工具系统
+ *
+ * 将以下工具包装为标准 ToolDef 格式：
+ * - qqbot_channel_api
+ * - qqbot_remind
+ * - qqbot_media
+ */
+
+import { ToolDef } from '../types/index.js'
+import { tools as qqbotChannelApiTools } from '../../tools/qqbot-channel-api.js'
+import { tools as qqbotRemindTools } from '../../tools/qqbot-remind.js'
+import { tools as qqbotMediaTools } from '../../tools/qqbot-media.js'
+
+// 通用执行器：将原始函数包装为 ToolDef 的执行格式
+function createExecutor(originalFunc) {
+  return async (input, ctx) => {
+    try {
+      // 合并上下文配置（如 targetId, scope, accountId）
+      const args = { ...input, ...ctx }
+      const result = await originalFunc(args)
+      // 保持与现有工具一致的返回格式
+      if (result.ok) {
+        return typeof result.result !== 'undefined' ? result.result : result
+      }
+      return `[ERROR] ${result.error || 'Unknown error'}`
+    } catch (e) {
+      return `[ERROR] ${e.message}`
+    }
+  }
+}
+
+// 导出所有工具（使用 ToolDef 格式）
+export const qqbotTools = [
+  // qqbot_channel_api — 通用 API 调用
+  new ToolDef(
+    'qqbot_channel_api',
+    `调用 QQ Bot API v2。自动携带鉴权 Token，无需手动处理。
+使用方法：
+  method: HTTP 方法 (GET/POST/PUT/PATCH/DELETE)
+  path: API 路径（不含域名），如 /guilds/{guild_id}/channels
+  body: 请求体 JSON（POST/PUT/PATCH 使用）
+  query: URL 查询参数对象（值必须是字符串）
+
+示例：
+- 获取频道列表: { "method": "GET", "path": "/users/@me/guilds", "query": { "limit": "100" } }
+- 获取子频道: { "method": "GET", "path": "/guilds/123/channels" }`,
+    {
+      type: 'object',
+      properties: {
+        method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], description: 'HTTP 方法' },
+        path: { type: 'string', description: 'API 路径（不含域名），如 /guilds/{guild_id}/channels' },
+        body: { type: 'object', description: '请求体 JSON（POST/PUT/PATCH 使用）' },
+        query: { type: 'object', additionalProperties: { type: 'string' }, description: 'URL 查询参数（值必须是字符串）' }
+      },
+      required: ['method', 'path']
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_channel_api)
+  ),
+
+  // qqbot_list_guilds — 获取频道列表
+  new ToolDef(
+    'qqbot_list_guilds',
+    '获取机器人所在的频道列表（GUILD 列表）',
+    {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: '返回数量，最大100' },
+        before: { type: 'string', description: '分页游标（上一页最后一条的 id）' },
+        after: { type: 'string', description: '分页游标（上一页第一条的 id）' }
+      }
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_list_guilds)
+  ),
+
+  // qqbot_list_channels — 获取子频道列表
+  new ToolDef(
+    'qqbot_list_channels',
+    '获取指定频道的子频道列表',
+    {
+      type: 'object',
+      properties: {
+        guildId: { type: 'string', description: '频道 ID' }
+      },
+      required: ['guildId']
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_list_channels)
+  ),
+
+  // qqbot_get_member — 获取成员详情
+  new ToolDef(
+    'qqbot_get_member',
+    '获取指定成员详情',
+    {
+      type: 'object',
+      properties: {
+        guildId: { type: 'string', description: '频道 ID' },
+        userId: { type: 'string', description: '用户 ID' }
+      },
+      required: ['guildId', 'userId']
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_get_member)
+  ),
+
+  // qqbot_list_members — 获取成员列表（分页）
+  new ToolDef(
+    'qqbot_list_members',
+    '获取频道成员列表（分页），首次调用 after=0',
+    {
+      type: 'object',
+      properties: {
+        guildId: { type: 'string', description: '频道 ID' },
+        limit: { type: 'number', description: '每页数量（1-400）' },
+        after: { type: 'string', description: '上一页最后一条的 user.id，首次填 0' }
+      },
+      required: ['guildId']
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_list_members)
+  ),
+
+  // qqbot_get_channel_online — 获取在线人数
+  new ToolDef(
+    'qqbot_get_channel_online',
+    '获取子频道在线人数',
+    {
+      type: 'object',
+      properties: {
+        channelId: { type: 'string', description: '子频道 ID' }
+      },
+      required: ['channelId']
+    },
+    createExecutor(qqbotChannelApiTools.qqbot_get_channel_online)
+  ),
+
+  // qqbot_remind — 定时提醒
+  new ToolDef(
+    'qqbot_remind',
+    `QQ Bot 定时提醒。支持：
+- 一次性：time = "5m"（5分钟）、"1h30m"（1.5小时）
+- 周期性：time = "0 8 * * *"（每天8点），需设置 tz = "Asia/Shanghai"
+
+注意：必须提供 targetId（openid 或 group_openid）和 content。
+
+示例：
+{ "action": "add", "content": "喝水", "time": "5m", "targetId": "群OPENID" }`,
+    {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['add', 'list', 'remove'], description: '操作类型' },
+        content: { type: 'string', description: '提醒内容' },
+        time: { type: 'string', description: '相对时间 (5m, 1h30m) 或 cron 表达式 ("0 8 * * *")' },
+        targetId: { type: 'string', description: '目标 openid 或 group_openid' },
+        accountId: { type: 'string', description: '使用的 QQ 账户 ID（可选）' },
+        jobId: { type: 'string', description: '任务 ID（仅 remove 使用）' }
+      },
+      required: ['action']
+    },
+    createExecutor(qqbotRemindTools.qqbotRemind)
+  ),
+
+  // qqbot_media_upload — 富媒体上传
+  new ToolDef(
+    'qqbot_media_upload',
+    `上传并发送图片/文件/语音。
+重要：文件必须位于 ~/.openclaw/media/qqbot/ 或 ~/.openclaw/media/ 目录下（安全限制）。
+自动检测文件类型：图片（jpg/png/gif）、视频（mp4/mkv）、语音（mp3/silk）、文件（其他）。
+
+示例：
+{ "path": "/home/user/.openclaw/media/qqbot/result.png", "scope": "group", "targetId": "群OPENID" }`,
+    {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '本地文件绝对路径' },
+        scope: { type: 'string', enum: ['c2c', 'group'], description: '发送范围' },
+        targetId: { type: 'string', description: '目标 ID' },
+        accountId: { type: 'string', description: '使用的 QQ 账户 ID（可选）' },
+        appId: { type: 'string', description: 'QQ Bot AppID（可选，默认使用环境变量）' },
+        clientSecret: { type: 'string', description: 'QQ Bot ClientSecret（可选）' }
+      },
+      required: ['path', 'scope', 'targetId']
+    },
+    createExecutor(qqbotMediaTools.qqbot_media_upload)
+  )
+]
+