foliko 1.1.38 → 1.1.39

package/plugins/qq-plugin.js

@@ -0,0 +1,939 @@
+/**
+ * QQ 插件
+ * 使用 @chnak/qq-bot 实现 QQ 对话
+ *
+ * 配置：
+ * - appId: QQ 开放平台应用 ID
+ * - clientSecret: QQ 开放平台应用密钥
+ * - allowedUsers: 允许交互的用户 openid 列表（空数组表示允许所有人）
+ */
+
+const { Plugin } = require('../src/core/plugin-base')
+const { logger } = require('../src/utils/logger')
+const log = logger.child('QQ')
+const { cleanResponse } = require('../src/utils')
+const { FileDownloader } = require('../src/utils/download')
+const { z } = require('zod')
+const { createQQBotClient, QQBotAPIClient, StreamSession } = require('@chnak/qq-bot')
+const path = require('path')
+const fs = require('fs')
+
+class QQPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'qq'
+    this.version = '1.0.0'
+    this.description = 'QQ 对话插件，使用 QQ 开放平台进行对话'
+    this.priority = 80
+    this.enabled = false
+    this.path = `.agent/data`
+
+    this.config = {
+      appId: config.appId || process.env.QQ_APP_ID,
+      clientSecret: config.clientSecret || process.env.QQ_CLIENT_SECRET,
+      allowedUsers: config.allowedUsers || [],
+      markdownSupport: true,
+    }
+
+    this._framework = null
+    this._client = null
+    this._apiClient = null  // 独立的 API 客户端（用于流式消息）
+    this._sessionPlugin = null
+    this._sessionDeleteHandler = null
+    this._sessionAgents = new Map()  // openid -> Agent
+    this._sessionScopes = new Map()  // sessionId -> sessionScope
+    this._streamSessions = new Map()  // sessionId -> StreamSession
+    this._initialized = false
+    this._myUserId = null
+    this._typingUsers = new Set()  // 正在发送 typing 的用户（防抖）
+    this.agent = null
+    this.sessionId = null
+
+    const saveDir = path.join(process.cwd(), '.agent', 'data', this.name)
+    this.downloader = new FileDownloader({
+      retries: 3,
+      baseDir: saveDir
+    })
+
+    this.systemPrompt = `你是一个 QQ 助手。
+
+**重要:** 子Agent 匹配规则必须遵守：
+- 根据【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理
+- 使用 subagent_call 工具并指定 agentName 来委托任务
+- 只有当没有匹配的子Agent时，才直接调用工具
+
+**命令执行规范：**
+- 执行 npx skills add / npx skills remove / npx skills list 命令时，必须自动添加参数：-a openclaw -y
+- 禁止添加 -g 参数
+- 例如：npx skills add xxx 应该执行为 npx skills add xxx -a openclaw -y`
+  }
+
+  install(framework) {
+    this._framework = framework
+    this._registerTools()
+    return this
+  }
+
+  /**
+   * 注册 QQ 发送工具
+   */
+  _registerTools() {
+    // 发送文本消息
+    this.registerTool({
+      name: 'qq_send_message',
+      description: '发送文本消息到 QQ（私聊）',
+      inputSchema: z.object({
+        message: z.string().describe('要发送的文本内容'),
+        openid: z.string().optional().describe('用户 openid（不填则发给机器人自己）'),
+      }),
+      execute: async (args) => {
+        return this._sendMessage(args.openid || this._myUserId, args.message)
+      }
+    })
+
+    // 发送图片/语音/视频（根据文件后缀自动判断）
+    this.registerTool({
+      name: 'qq_send_media',
+      description: '发送图片/语音/视频到 QQ（私聊），支持本地路径或 URL',
+      inputSchema: z.object({
+        filePath: z.string().optional().describe('本地文件路径（支持图片/语音/视频）'),
+        imageUrl: z.string().optional().describe('图片 URL（与 filePath 二选一）'),
+        openid: z.string().optional().describe('用户 openid（不填则发给机器人自己）'),
+        content: z.string().optional().describe('内容描述'),
+      }),
+      execute: async (args) => {
+        if (args.imageUrl) {
+          return this._sendImageByUrl(args.openid || this._myUserId, args.imageUrl, args.content)
+        } else if (args.filePath) {
+          return this._sendMedia(args.openid || this._myUserId, args.filePath, args.content)
+        }
+        return { error: '需要提供 filePath 或 imageUrl' }
+      }
+    })
+
+    // 发送文件
+    this.registerTool({
+      name: 'qq_send_file',
+      description: '发送本地文件到 QQ（私聊）',
+      inputSchema: z.object({
+        filePath: z.string().describe('本地文件路径'),
+        openid: z.string().optional().describe('用户 openid（不填则发给机器人自己）'),
+        content: z.string().optional().describe('文件描述文字'),
+      }),
+      execute: async (args) => {
+        return this._sendFile(args.openid || this._myUserId, args.filePath, args.content)
+      }
+    })
+
+    // 发送群聊消息（支持文本或图片）
+    this.registerTool({
+      name: 'qq_send_group_message',
+      description: '发送消息到 QQ 群（文本或本地图片）',
+      inputSchema: z.object({
+        groupOpenid: z.string().describe('群 openid'),
+        message: z.string().optional().describe('文本消息'),
+        imagePath: z.string().optional().describe('本地图片路径（与 message 二选一）'),
+      }),
+      execute: async (args) => {
+        if (args.imagePath) {
+          return this._sendGroupLocalImage(args.groupOpenid, args.imagePath, args.message)
+        } else if (args.message) {
+          return this._sendGroupMessage(args.groupOpenid, args.message)
+        }
+        return { error: '需要提供 message 或 imagePath' }
+      }
+    })
+  }
+
+  /**
+   * 发送私聊文本消息
+   */
+  async _sendMessage(openid, content, originalMsg = null) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!openid) {
+      return { error: '未指定用户 openid' }
+    }
+    try {
+      // 如果有 originalMsg，使用流式发送
+      if (originalMsg && originalMsg.id) {
+        const stream = new StreamSession(
+          this._apiClient,
+          openid,
+          originalMsg.id,
+          `stream_${Date.now()}`,
+          {
+            chunk: () => {},
+            done: () => {},
+            error: (err) => log.error('Stream error:', err.message),
+          }
+        )
+        await stream.write(content)
+        await stream.done()
+      } else {
+        // 降级为普通发送
+        await this._client.sendC2CMessage({ openid, content })
+      }
+      return { success: true, message: '消息发送成功' }
+    } catch (err) {
+      log.error(`消息发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  /**
+   * 发送私聊图片（URL 方式）
+   */
+  async _sendImageByUrl(openid, imageUrl, content) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!openid) {
+      return { error: '未指定用户 openid' }
+    }
+    try {
+      await this._client.sendC2CImageMessage({
+        openid,
+        imageUrl,
+        content,
+      })
+      return { success: true, message: '图片发送成功' }
+    } catch (err) {
+      log.error(`图片发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  /**
+   * 根据文件后缀自动发送媒体文件（图片/语音/视频）
+   */
+  async _sendMedia(openid, filePath, content) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!openid) {
+      return { error: '未指定用户 openid' }
+    }
+    if (!fs.existsSync(filePath)) {
+      return { error: `文件不存在: ${filePath}` }
+    }
+
+    const ext = path.extname(filePath).toLowerCase()
+    const imageExts = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp']
+    const voiceExts = ['.silk', '.mp3', '.amr', '.wav', '.m4a']
+    const videoExts = ['.mp4', '.avi', '.mov', '.mkv', '.flv']
+
+    try {
+      if (imageExts.includes(ext)) {
+        await this._client.sendC2CLocalImageMessage({ openid, filePath, content })
+        return { success: true, message: '图片发送成功' }
+      } else if (voiceExts.includes(ext)) {
+        await this._client.sendC2CLocalVoiceMessage({ openid, filePath })
+        return { success: true, message: '语音发送成功' }
+      } else if (videoExts.includes(ext)) {
+        await this._client.sendC2CLocalVideoMessage({ openid, filePath, content })
+        return { success: true, message: '视频发送成功' }
+      } else {
+        // 未知格式，当作文件处理
+        return this._sendFile(openid, filePath, content)
+      }
+    } catch (err) {
+      log.error(`媒体发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  /**
+   * 发送私聊文件
+   */
+  async _sendFile(openid, filePath, content) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!openid) {
+      return { error: '未指定用户 openid' }
+    }
+    try {
+      if (!fs.existsSync(filePath)) {
+        return { error: `文件不存在: ${filePath}` }
+      }
+      await this._client.sendC2CLocalFileMessage({
+        openid,
+        filePath,
+        content,
+      })
+      return { success: true, message: '文件发送成功' }
+    } catch (err) {
+      log.error(`文件发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  /**
+   * 发送群聊文本消息
+   */
+  async _sendGroupMessage(groupOpenid, content) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!groupOpenid) {
+      return { error: '未指定群 openid' }
+    }
+    try {
+      await this._client.sendGroupMessage({
+        groupOpenid,
+        content,
+      })
+      return { success: true, message: '群消息发送成功' }
+    } catch (err) {
+      log.error(`群消息发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  /**
+   * 发送群本地图片
+   */
+  async _sendGroupLocalImage(groupOpenid, imagePath, content) {
+    if (!this._client) {
+      return { error: 'QQ 机器人未连接' }
+    }
+    if (!groupOpenid) {
+      return { error: '未指定群 openid' }
+    }
+    try {
+      if (!fs.existsSync(imagePath)) {
+        return { error: `文件不存在: ${imagePath}` }
+      }
+      await this._client.sendGroupLocalImageMessage({
+        groupOpenid,
+        filePath: imagePath,
+        content,
+      })
+      return { success: true, message: '群图片发送成功' }
+    } catch (err) {
+      log.error(`群图片发送失败: ${err.message}`)
+      return { error: err.message }
+    }
+  }
+
+  async start(framework) {
+    if (this._initialized) return this
+    this._initialized = true
+
+    this._framework = framework
+    this._sessionPlugin = framework.pluginManager.get('session')
+
+    // 监听 SessionPlugin 的会话删除事件
+    if (this._sessionPlugin) {
+      this._sessionDeleteHandler = (sessionId) => {
+        if (sessionId.startsWith('qq_')) {
+          // log.info(`Session deleted: ${sessionId}`)
+        }
+      }
+      this._sessionPlugin.on('session:deleted', this._sessionDeleteHandler)
+    }
+
+    // 监听统一通知事件
+    if (this._framework) {
+      this._framework.on('webhook:received', async (data) => {
+        await this._handleWebhookNotification(data)
+      })
+
+      this._framework.on('notification', async (data) => {
+        await this._handleNotification(data)
+      })
+    }
+
+    // 异步初始化 Bot
+    this._initBotAsync().catch(err => {
+      log.error('Failed to initialize bot:', err.message)
+    })
+
+    return this
+  }
+
+  async _initBotAsync() {
+    if (!this.config.appId || !this.config.clientSecret) {
+      log.error('QQ_APP_ID and QQ_CLIENT_SECRET must be configured')
+      return
+    }
+
+    this._client = createQQBotClient({
+      appId: this.config.appId,
+      clientSecret: this.config.clientSecret,
+      markdownSupport: true, // 启用 Markdown 支持
+      log: {
+        info: (msg) => log.info('[QQ]', msg),
+        error: (msg) => log.error('[QQ]', msg),
+        warn: (msg) => log.warn('[QQ]', msg),
+      },
+    })
+
+    // 连接后可以从事件中获取机器人信息，先直接连接
+    // 获取机器人自身的 openid（用于发送消息）
+    // try {
+    //   const token = await this._client.api.getToken()
+    // } catch (err) {
+    //   log.warn('Failed to get access token:', err.message)
+    // }
+
+    // 监听私聊消息
+    this._client.on('C2C_MESSAGE_CREATE', async (event) => {
+      await this._handleC2CMessage(event)
+    })
+
+    // 监听群聊@消息
+    this._client.on('GROUP_AT_MESSAGE_CREATE', async (event) => {
+      await this._handleGroupMessage(event)
+    })
+
+    // 监听按钮交互
+    this._client.on('INTERACTION_CREATE', async (event) => {
+      await this._handleInteraction(event)
+    })
+
+    // 启动连接
+    await this._client.connect()
+
+    // 创建独立的 API 客户端（用于流式消息）
+    this._apiClient = new QQBotAPIClient({
+      appId: this.config.appId,
+      clientSecret: this.config.clientSecret,
+      markdownSupport: this.config.markdownSupport,
+    })
+
+    log.info('QQ Bot 已连接')
+  }
+
+  /**
+   * 处理私聊消息
+   */
+  async _handleC2CMessage(event) {
+    const openid = event.author.user_openid || event.author.id
+    const content = event.content?.trim()
+
+    if (!openid || !content) return
+
+    // 权限检查
+    if (!this._checkPermission(openid)) {
+      await this._sendMessage(openid, '你没有权限使用此机器人')
+      return
+    }
+
+    // 记录机器人自己的 openid（用于工具发送）
+    if (!this._myUserId) {
+      this._myUserId = openid
+    }
+
+    // 处理命令
+    if (content.startsWith('/')) {
+      await this._handleCommand(openid, content, event)
+      return
+    }
+
+    await this._processChat(openid, content, event, 'c2c')
+  }
+
+  /**
+   * 处理群聊消息
+   */
+  async _handleGroupMessage(event) {
+    const groupOpenid = event.group_openid
+    const content = event.content?.trim()
+    const username = event.author?.username || event.author?.id || 'unknown'
+
+    if (!groupOpenid || !content) return
+
+    // 检查是否@了机器人（content 通常包含 @机器人 的前缀）
+    // 去掉 @xxx 前缀后处理实际内容
+    const actualContent = content.replace(/^\s*@.*?\s*/, '').trim()
+
+    if (!actualContent) return
+
+    // 权限检查（可以按群或用户检查）
+    // if (!this._checkGroupPermission(groupOpenid, userId)) { ... }
+
+    // 处理命令
+    if (actualContent.startsWith('/')) {
+      await this._handleGroupCommand(groupOpenid, username, actualContent, event)
+      return
+    }
+
+    await this._processChat(groupOpenid, actualContent, event, 'group', username)
+  }
+
+  /**
+   * 处理按钮交互
+   */
+  async _handleInteraction(event) {
+    try {
+      const { button_data, button_id } = event.raw?.data?.resolved || {}
+      log.info(`Button interaction: ${button_id} - ${button_data}`)
+
+      // 确认交互
+      await this._client.acknowledgeInteraction(event.id, 0, {
+        msg: `收到按钮点击: ${button_id}`,
+      })
+    } catch (err) {
+      log.error(`Button interaction error: ${err.message}`)
+    }
+  }
+
+  /**
+   * 获取或创建会话 Agent
+   */
+  _getSessionAgent(identifier, type = 'c2c') {
+    const sessionId = `qq_${type}_${identifier}`
+    this.sessionId = sessionId
+
+    // 检查缓存
+    if (this._sessionAgents.has(identifier)) {
+      const agent = this._sessionAgents.get(identifier)
+      return { agent, sessionId }
+    }
+
+    const agent = this._framework.createAgent({
+      name: `qq_${identifier}`,
+      systemPrompt: this.systemPrompt,
+      sharedPrompt: `工作目录: {{WORK_DIR}}`,
+      metadata: { WORK_DIR: process.cwd(), platform: 'qq', identifier }
+    })
+
+    this._sessionAgents.set(identifier, agent)
+
+    // 使用 SessionPlugin 管理会话历史
+    if (this._sessionPlugin) {
+      this._sessionPlugin.getOrCreateSession(sessionId, {
+        metadata: { platform: 'qq', identifier, type }
+      })
+    }
+
+    return { agent, sessionId }
+  }
+
+  /**
+   * 设置 session scope 事件监听
+   */
+  _setupSessionScopeListeners(agent, sessionId, originalMsg, identifier, msgType) {
+    const sessionScope = agent.createSessionScope(sessionId)
+    const streamSessionMap = this._streamSessions
+
+    sessionScope.on('stream:chunk', async ({ chunk, isFirst }) => {
+      if (!this._client || !originalMsg) return
+
+      const isGroup = msgType === 'group'
+      const openid = isGroup ? null : identifier
+
+
+      // 创建流式会话（仅第一次时创建）
+      if (isFirst) {
+        const msgId = originalMsg.id
+        const eventId = `stream_${Date.now()}`
+
+        let streamSession
+        if (msgType === 'group') {
+          // 群聊暂不支持流式，降级为普通发送
+          return
+        } else {
+          try {
+            streamSession = new StreamSession(
+              this._apiClient,  // 使用独立的 API 客户端
+              openid,
+              msgId,
+              eventId,
+              {
+                chunk: (content) => {},  // 累积模式，不需要实时回调
+                done: () => {},
+                error: (err) => log.error('Stream error:', err.message),
+              }
+            )
+          } catch (err) {
+            log.error('Failed to create stream session:', err.message)
+            return
+          }
+        }
+
+        streamSessionMap.set(sessionId, streamSession)
+      }
+
+      const streamSession = streamSessionMap.get(sessionId)
+      if (streamSession) {
+        try {
+          await streamSession.write(chunk)
+        } catch (err) {
+          log.error('Stream write error:', err.message)
+        }
+      }
+    })
+
+    sessionScope.on('message:complete', async ({ content }) => {
+      // 清理定时器
+      this.stopTypingInterval?.()
+
+      const streamSession = streamSessionMap.get(sessionId)
+      if (streamSession) {
+        try {
+          await streamSession.done()
+        } catch (err) {
+          log.error('Stream done error:', err.message)
+        }
+        streamSessionMap.delete(sessionId)
+      }
+
+      if (content) {
+        if (msgType === 'group') {
+          await this._sendGroupMessage(identifier, content)
+        } else {
+          await this._sendMessage(identifier, content, originalMsg)
+        }
+      }
+    })
+
+    sessionScope.on('queue:failed', async ({ error }) => {
+      // 清理定时器
+      this.stopTypingInterval?.()
+
+      // 清理流式会话
+      const streamSession = streamSessionMap.get(sessionId)
+      if (streamSession) {
+        streamSessionMap.delete(sessionId)
+      }
+
+      if (msgType === 'group') {
+        await this._sendGroupMessage(identifier, error)
+      } else {
+        await this._sendMessage(identifier, error, originalMsg)
+      }
+    })
+
+    this._sessionScopes.set(sessionId, sessionScope)
+    return sessionScope
+  }
+
+  /**
+   * 处理对话
+   */
+  async _processChat(identifier, text, originalMsg, msgType = 'c2c', username = null) {
+    const sessionInfo = this._getSessionAgent(identifier, msgType)
+    if (!sessionInfo) {
+      log.error('No session agent available')
+      return
+    }
+
+    const { agent, sessionId } = sessionInfo
+
+    // 预创建或获取 sessionScope
+    let sessionScope = this._sessionScopes.get(sessionId)
+    if (!sessionScope) {
+      sessionScope = this._setupSessionScopeListeners(agent, sessionId, originalMsg, identifier, msgType)
+    }
+
+    // 添加用户名上下文（群聊时）
+    const messageWithContext = username && msgType === 'group'
+      ? `[群聊消息，来自 ${username}]\n${text}`
+      : text
+
+    try {
+      await agent.sendMessage(messageWithContext, { sessionId, priority: 1 })
+    } catch (err) {
+      log.error('Chat error:', err.message)
+      if (msgType === 'group') {
+        await this._sendGroupMessage(identifier, `发生错误：${err.message}`)
+      } else {
+        await this._sendMessage(identifier, `发生错误：${err.message}`)
+      }
+    } finally {
+      this.stopTypingInterval?.()
+    }
+  }
+
+  /**
+   * 处理命令
+   */
+  async _handleCommand(openid, text, originalMsg) {
+    const parts = text.split(' ')
+    const command = parts[0].substring(1)
+    const args = parts.slice(1).join(' ')
+
+    switch (command.toLowerCase()) {
+      case 'start':
+      case 'help':
+        await this._sendMessage(openid,
+          '👋 欢迎使用 AI 助手！\n\n直接发送消息即可与我对话。\n\n可用命令：\n/clean - 清除对话上下文\n/history - 查看历史消息数')
+        break
+      case 'clean':
+      case 'clear':
+        await this._clearSessionContext(openid)
+        await this._sendMessage(openid, '✅ 对话上下文已清除')
+        break
+      case 'history':
+        const sessionInfo = this._getSessionAgent(openid)
+        if (sessionInfo && this._framework) {
+          const sessionCtx = this._framework.getSessionContext(sessionInfo.sessionId)
+          const count = sessionCtx?.messageStore?.messages?.length || 0
+          const compressionCount = sessionCtx?.metadata?.compressionCount || 0
+          await this._sendMessage(openid,
+            `📊 当前状态\n\n历史消息：${count}\n压缩次数：${compressionCount}`)
+        }
+        break
+      default:
+        await this._processChat(openid, text, originalMsg, 'c2c')
+    }
+  }
+
+  /**
+   * 处理群命令
+   */
+  async _handleGroupCommand(groupOpenid, username, text, originalMsg) {
+    const parts = text.split(' ')
+    const command = parts[0].substring(1)
+    const args = parts.slice(1).join(' ')
+
+    switch (command.toLowerCase()) {
+      case 'start':
+      case 'help':
+        await this._sendGroupMessage(groupOpenid,
+          '👋 欢迎使用 AI 助手！\n\n可用命令：\n/clean - 清除对话上下文\n/history - 查看历史消息数')
+        break
+      case 'clean':
+      case 'clear':
+        await this._clearSessionContext(groupOpenid)
+        await this._sendGroupMessage(groupOpenid, '✅ 对话上下文已清除')
+        break
+      case 'history':
+        const sessionInfo = this._getSessionAgent(groupOpenid, 'group')
+        if (sessionInfo && this._framework) {
+          const sessionCtx = this._framework.getSessionContext(sessionInfo.sessionId)
+          const count = sessionCtx?.messageStore?.messages?.length || 0
+          const compressionCount = sessionCtx?.metadata?.compressionCount || 0
+          await this._sendGroupMessage(groupOpenid,
+            `📊 当前状态\n\n历史消息：${count}\n压缩次数：${compressionCount}`)
+        }
+        break
+      default:
+        await this._processChat(groupOpenid, text, originalMsg, 'group', username)
+    }
+  }
+
+  /**
+   * 清除会话上下文
+   */
+  async _clearSessionContext(identifier) {
+    const sessionId = `qq_c2c_${identifier}`
+
+    const { agent } = this._getSessionAgent(identifier)
+
+    if (agent._chatHandler) {
+      agent._chatHandler.clearHistory(sessionId)
+    }
+
+    if (this._framework) {
+      const sessionCtx = this._framework.getSessionContext(sessionId)
+      if (sessionCtx) {
+        sessionCtx.clearMessages()
+        sessionCtx.compressionState.count = 0
+        sessionCtx.metadata.compressionCount = 0
+      }
+      const cachedCtx = this._framework._sessionContexts?.get(sessionId)
+      if (cachedCtx) {
+        cachedCtx.clearMessages()
+        cachedCtx.compressionState.count = 0
+        cachedCtx.metadata.compressionCount = 0
+      }
+    }
+  }
+
+  /**
+   * 权限检查
+   */
+  _checkPermission(openid) {
+    if (!this.config.allowedUsers || this.config.allowedUsers.length === 0) {
+      return true
+    }
+    return this.config.allowedUsers.includes(openid)
+  }
+
+  /**
+   * 处理 webhook 通知
+   */
+  async _handleWebhookNotification(data) {
+    const { data: webhookData, response, sessionId } = data
+
+    if (!this._client) {
+      log.warn('Bot not ready, cannot send webhook notification')
+      return
+    }
+
+    if (!sessionId || !sessionId.startsWith('qq_')) {
+      return
+    }
+
+    const identifier = sessionId.replace('qq_c2c_', '').replace('qq_group_', '')
+    const isGroup = sessionId.includes('group_')
+    const notificationText = `📥 [Webhook 接收]\n\n路径: ${webhookData.path}\n方法: ${webhookData.method}\n\n处理结果: ${response || '处理中...'}`
+
+    try {
+      if (isGroup) {
+        await this._sendGroupMessage(identifier, notificationText)
+      } else {
+        await this._sendMessage(identifier, notificationText)
+      }
+    } catch (err) {
+      log.error(`Failed to send webhook notification: ${err.message}`)
+    }
+  }
+
+  /**
+   * 处理统一通知
+   */
+  async _handleNotification(data) {
+    const { title, message, source = '系统消息', level, sessionId } = data
+
+    if (!this._client) {
+      log.warn('Bot not ready, cannot send notification')
+      return
+    }
+
+    let identifier = null
+    let isGroup = false
+
+    if (sessionId && sessionId.startsWith('qq_')) {
+      if (sessionId.includes('group_')) {
+        identifier = sessionId.replace('qq_group_', '')
+        isGroup = true
+      } else {
+        identifier = sessionId.replace('qq_c2c_', '')
+      }
+    } else if (this._sessionPlugin) {
+      const sessions = this._sessionPlugin.listSessions()
+        .filter(s => s.id.startsWith('qq_'))
+        .sort((a, b) => new Date(b.lastActive).getTime() - new Date(a.lastActive).getTime())
+      if (sessions.length > 0) {
+        const s = sessions[0]
+        if (s.id.includes('group_')) {
+          identifier = s.id.replace('qq_group_', '')
+          isGroup = true
+        } else {
+          identifier = s.id.replace('qq_c2c_', '')
+        }
+      }
+    }
+
+    if (!identifier) {
+      log.warn('No QQ session found for notification')
+      return
+    }
+
+    const levelEmoji = {
+      info: 'ℹ️',
+      warning: '⚠️',
+      success: '✅',
+      error: '❌'
+    }
+    const emoji = levelEmoji[level] || 'ℹ️'
+    const notificationText = `${emoji} [${source}] ${title || '通知'}\n\n${message || ''}`
+
+    try {
+      if (isGroup) {
+        await this._sendGroupMessage(identifier, notificationText)
+      } else {
+        await this._sendMessage(identifier, notificationText)
+      }
+    } catch (err) {
+      log.error(`Failed to send notification: ${err.message}`)
+    }
+  }
+
+  /**
+   * 获取插件状态
+   */
+  getStatus() {
+    let sessions = []
+    if (this._sessionPlugin) {
+      const allSessions = this._sessionPlugin.listSessions()
+      sessions = allSessions
+        .filter(s => s.id.startsWith('qq_'))
+        .map(s => ({
+          id: s.id,
+          historyLength: s.messageCount,
+          lastActive: s.lastActive
+        }))
+    }
+
+    return {
+      connected: !!this._client,
+      sessionCount: sessions.length,
+      sessions,
+      config: {
+        appId: this.config.appId ? `${this.config.appId.substring(0, 8)}...` : 'not set',
+        allowedUsersCount: this.config.allowedUsers?.length || 0,
+        markdownSupport: this.config.markdownSupport,
+      }
+    }
+  }
+
+  /**
+   * 停止 Bot
+   */
+  stopBot() {
+    if (this._client) {
+      this._client.disconnect()
+      this._client = null
+      log.info('Bot stopped')
+    }
+  }
+
+  reload(framework) {
+    this._framework = framework
+    this._initialized = false
+    this.stopBot()
+    this.start(framework)
+  }
+
+  uninstall(framework) {
+    // 清理所有流式会话
+    for (const streamSession of this._streamSessions.values()) {
+      try {
+        streamSession.done?.()
+      } catch {}
+    }
+    this._streamSessions.clear()
+
+    // 销毁所有 session agents
+    for (const agent of this._sessionAgents.values()) {
+      agent.destroy()
+    }
+    this._sessionAgents.clear()
+    this._sessionScopes.clear()
+    this.stopBot()
+
+    if (this._sessionPlugin && this._sessionDeleteHandler) {
+      this._sessionPlugin.off('session:deleted', this._sessionDeleteHandler)
+      this._sessionDeleteHandler = null
+    }
+
+    this._sessionPlugin = null
+    this._framework = null
+  }
+}
+
+// 简单的 interval 工具函数（从 cli/src/utils/debounce 引入）
+function interval(fn, ms) {
+  let timer = null
+  const start = () => {
+    stop()
+    fn()
+    timer = setInterval(fn, ms)
+  }
+  const stop = () => {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+  return { start, stop }
+}
+
+module.exports = QQPlugin