@izhimu/qq 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,9 @@
 # @izhimu/qq
 
 <p align="center">
+  <a href="https://github.com/izhimu/openclaw-channel-qq/releases">
+    <img src="https://img.shields.io/github/v/release/izhimu/openclaw-channel-qq?display_name=tag" alt="Release">
+  </a>
   <a href="https://opensource.org/licenses/MIT">
     <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
   </a>
@@ -36,6 +39,7 @@
 - [API 文档](#api-文档)
 - [开发指南](#开发指南)
 - [故障排查](#故障排查)
+- [更新日志](#更新日志)
 
 ---
 
@@ -44,7 +48,8 @@
 - **多渠道支持** - 同时支持 QQ 私聊和群聊
 - **消息类型** - 文本、@提及、图片、表情、语音、文件、回复
 - **实时通信** - WebSocket 全双工连接，支持自动重连
-- **心跳监测** - 内置健康检查和连接状态监控
+- **心跳监测** - 内置健康检查、心跳超时检测和连接状态监控
+- **媒体支持** - 支持图片、语音、文件等媒体消息的收发
 - **交互式配置** - 提供向导式配置界面
 - **TypeScript** - 完整的类型定义和类型安全
 
@@ -252,8 +257,8 @@ openclaw-channel-qq/
 | `image` | ✓ | ✓ | 图片 |
 | `face` | ✓ | - | QQ 表情 |
 | `reply` | ✓ | ✓ | 消息回复 |
-| `record` | ✓ | - | 语音消息 |
-| `file` | ✓ | - | 文件 |
+| `record` | ✓ | ✓ | 语音消息 |
+| `file` | ✓ | ✓ | 文件 |
 | `json` | ✓ | - | JSON 富文本 |
 
 ### OneBot 11 接口
@@ -364,6 +369,60 @@ npm run build
 
 ---
 
+## 更新日志
+
+### [0.3.0] - 2026-02-12
+
+#### 新增
+- 心跳超时检测和自动重连机制
+- 媒体消息处理功能（图片、语音、文件等）
+- 媒体文件发送功能
+- 运行状态标记和探针功能
+- 通道状态管理功能
+
+#### 修复
+- 修复连接状态管理逻辑
+- 修复空消息过滤逻辑
+
+#### 重构
+- 重构通道状态管理逻辑
+
+### [0.2.3] - 2026-02-09
+
+#### 新增
+- Markdown 文本转换功能
+
+### [0.2.2] - 2026-02-08
+
+#### 新增
+- 账号启用和删除功能
+- 消息回复功能
+- Markdown 解析优化
+
+#### 修复
+- 修复多 Agent 通信消息回调问题
+- 修复回复消息格式问题
+- 修复字符串连接时换行符丢失问题
+
+### [0.2.1] - 2026-02-08
+
+#### 优化
+- 优化 Markdown 转文本功能（移动端适配）
+
+### [0.2.0] - 2026-02-07
+
+#### 重构
+- 重构 QQ 频道消息发送功能
+
+### [0.1.1] - 2026-02-07
+
+#### 优化
+- 重构项目配置并更新文档
+- 重构 QQ 频道插件的类型定义和配置管理
+- 优化日志系统
+
+---
+
 ## 相关链接
 
 - [OpenClaw 官方文档](https://docs.openclaw.ai/)

package/dist/src/channel.d.ts

@@ -2,6 +2,6 @@
  * QQ NapCat Plugin for OpenClaw
  * Main plugin entry point
  */
-import { ChannelPlugin } from "openclaw/plugin-sdk";
-import type { QQConfig } from "./types/index.js";
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import type { QQConfig } from "./types";
 export declare const qqPlugin: ChannelPlugin<QQConfig>;

package/dist/src/channel.js

@@ -2,14 +2,13 @@
  * QQ NapCat Plugin for OpenClaw
  * Main plugin entry point
  */
-import { setAccountEnabledInConfigSection, deleteAccountFromConfigSection } from "openclaw/plugin-sdk";
-import { buildChannelConfigSchema, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
-import { messageIdToString, markdownToText, getFileType, getFileName, Logger as log } from "./utils/index.js";
+import { buildChannelConfigSchema, setAccountEnabledInConfigSection, deleteAccountFromConfigSection, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import { messageIdToString, markdownToText, buildMediaMessage, Logger as log } from "./utils/index.js";
 import { setContext, setContextStatus, clearContext, setConnection, getConnection, clearConnection } from "./core/runtime.js";
 import { ConnectionManager } from "./core/connection.js";
 import { openClawToNapCatMessage } from "./adapters/message.js";
 import { listQQAccountIds, resolveQQAccount, QQConfigSchema, CHANNEL_ID } from "./core/config.js";
-import { eventListener, sendMsg } from "./core/request.js";
+import { eventListener, sendMsg, getStatus } from "./core/request.js";
 import { qqOnboardingAdapter } from "./onboarding.js";
 export const qqPlugin = {
     id: CHANNEL_ID,
@@ -71,13 +70,67 @@ export const qqPlugin = {
         sendMedia: outboundSend,
     },
     status: {
-        buildAccountSnapshot: ({ account, runtime }) => {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            name: "QQ",
+            enabled: false,
+            configured: false,
+            linked: false,
+            running: false,
+            connected: false,
+            reconnectAttempts: 0,
+            lastConnectedAt: null,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+            lastInboundAt: null,
+            lastOutboundAt: null,
+        },
+        buildChannelSummary: ({ snapshot }) => ({
+            enabled: snapshot.enabled ?? false,
+            configured: snapshot.configured ?? false,
+            linked: snapshot.linked ?? false,
+            running: snapshot.running ?? false,
+            connected: snapshot.connected ?? false,
+            reconnectAttempts: snapshot.reconnectAttempts ?? 0,
+            lastConnectedAt: snapshot.lastConnectedAt ?? null,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            lastInboundAt: snapshot.lastInboundAt ?? null,
+            lastOutboundAt: snapshot.lastOutboundAt ?? null,
+            probe: snapshot.probe,
+            lastProbeAt: snapshot.lastProbeAt ?? null,
+        }),
+        probeAccount: async () => {
+            const status = await getStatus();
+            setContextStatus({
+                running: true,
+                lastProbeAt: Date.now(),
+            });
+            return {
+                ok: status.status === "ok",
+                status: status.retcode,
+                error: status.status === "failed" ? status.msg : null,
+            };
+        },
+        buildAccountSnapshot: ({ account, runtime, probe }) => {
             return {
                 accountId: DEFAULT_ACCOUNT_ID,
-                name: CHANNEL_ID,
-                enabled: account.enabled,
-                configured: Boolean(account.wsUrl),
-                ...runtime,
+                name: "QQ",
+                enabled: account.enabled ?? false,
+                configured: Boolean(account.wsUrl?.trim()),
+                linked: runtime?.linked ?? false,
+                running: runtime?.running ?? false,
+                connected: runtime?.connected ?? false,
+                reconnectAttempts: runtime?.reconnectAttempts ?? 0,
+                lastStartAt: runtime?.lastStartAt ?? null,
+                lastStopAt: runtime?.lastStopAt ?? null,
+                lastError: runtime?.lastError ?? null,
+                lastInboundAt: runtime?.lastInboundAt ?? null,
+                lastOutboundAt: runtime?.lastOutboundAt ?? null,
+                probe,
+                lastProbeAt: runtime?.lastProbeAt ?? null,
             };
         },
     },
@@ -87,8 +140,7 @@ export const qqPlugin = {
             const { account } = ctx;
             log.info('gateway', `Starting gateway`);
             // Update start time
-            ctx.setStatus({
-                ...ctx.getStatus(),
+            setContextStatus({
                 running: true,
                 lastStartAt: Date.now(),
             });
@@ -110,6 +162,14 @@ export const qqPlugin = {
                     });
                 }
             });
+            connection.on("reconnecting", (info) => {
+                log.info('gateway', `Reconnecting: ${info.reason}, attempt ${info.totalAttempts}`);
+                setContextStatus({
+                    connected: false,
+                    lastError: `Reconnecting (${info.reason})`,
+                    reconnectAttempts: info.totalAttempts,
+                });
+            });
             await connection.start();
             setConnection(connection);
             log.info('gateway', `Started gateway`);
@@ -128,6 +188,30 @@ export const qqPlugin = {
             clearContext();
         },
     },
+    heartbeat: {
+        checkReady: async () => {
+            const status = await getStatus();
+            if (status.status === "ok" && status.data?.online && status.data?.good) {
+                setContextStatus({
+                    linked: true,
+                });
+                return {
+                    ok: true,
+                    reason: 'ok'
+                };
+            }
+            else {
+                log.warn('heartbeat', `Heartbeat failed, status: ${status.status}, data: ${status.data}`);
+                setContextStatus({
+                    linked: false,
+                });
+                return {
+                    ok: false,
+                    reason: status.msg
+                };
+            }
+        }
+    }
 };
 async function outboundSend(ctx) {
     const { to, text, mediaUrl, accountId, replyToId } = ctx;
@@ -142,16 +226,7 @@ async function outboundSend(ctx) {
         content.push({ type: "text", text: markdownToText(text) });
     }
     if (mediaUrl) {
-        switch (getFileType(mediaUrl)) {
-            case "image":
-                content.push({ type: "image", url: mediaUrl.trim() });
-                break;
-            case "audio":
-                content.push({ type: "audio", path: mediaUrl.trim(), url: mediaUrl.trim(), file: getFileName(mediaUrl.trim()) });
-                break;
-            default:
-                content.push({ type: "file", url: mediaUrl.trim(), file: getFileName(mediaUrl.trim()) });
-        }
+        content.push(buildMediaMessage(mediaUrl));
     }
     if (replyToId) {
         content.push({ type: "reply", messageId: replyToId });

package/dist/src/core/config.d.ts

@@ -2,7 +2,7 @@
  * QQ 配置管理
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import type { QQConfig } from "../types/index.js";
+import type { QQConfig } from "../types";
 import { z } from "zod";
 export declare const CHANNEL_ID = "qq";
 /**

package/dist/src/core/config.js

@@ -25,8 +25,15 @@ export function resolveQQAccount(params) {
         accessToken: config?.accessToken,
     };
 }
+/**
+ * Custom Zod refinement to validate WebSocket URL format
+ */
+const wsUrlRegex = /^wss?:\/\/[\w.-]+(:\d+)?(\/[\w./-]*)?$/;
+const wsUrlSchema = z.string()
+    .regex(wsUrlRegex, { message: "Invalid WebSocket URL format. Expected: ws://host:port or wss://host:port" })
+    .default("ws://127.0.0.1:3001");
 export const QQConfigSchema = z.object({
-    wsUrl: z.string().default("ws://127.0.0.1:3001"),
+    wsUrl: wsUrlSchema,
     accessToken: z.string().default("access-token"),
     enable: z.boolean().default(true)
 });

package/dist/src/core/connection.d.ts

@@ -3,7 +3,7 @@
  * Handles per-account WebSocket connections with auto-reconnect and heartbeat
  */
 import EventEmitter from 'events';
-import type { NapCatResp, QQConfig, ConnectionStatus, NapCatAction } from '../types/index.js';
+import type { NapCatResp, QQConfig, ConnectionStatus, NapCatAction } from '../types';
 /**
  * Connection Manager for a single NapCat account
  */
@@ -12,9 +12,9 @@ export declare class ConnectionManager extends EventEmitter {
     private ws;
     private state;
     private lastHeartbeatTime;
-    private totalReconnectAttempts;
+    private heartbeatCheckTimer?;
     private reconnectTimer?;
-    private reconnectAttempts;
+    private totalReconnectAttempts;
     private shouldReconnect;
     private pendingRequests;
     private healthStatus;
@@ -31,6 +31,18 @@ export declare class ConnectionManager extends EventEmitter {
      * Establish WebSocket connection
      */
     private connect;
+    /**
+     * Clear all pending requests and reject them with an error
+     */
+    private clearPendingRequests;
+    /**
+     * Start heartbeat timeout detection
+     */
+    private startHeartbeatCheck;
+    /**
+     * Stop heartbeat timeout detection
+     */
+    private stopHeartbeatCheck;
     /**
      * Close WebSocket connection
      */

package/dist/src/core/connection.js

@@ -7,6 +7,8 @@ import EventEmitter from 'events';
 import { Logger as log, generateEchoId, calculateBackoff, getCloseCodeMessage, } from '../utils/index.js';
 const MAX_RECONNECT_ATTEMPTS = -1;
 const REQUEST_TIMEOUT = 30000; // 30 seconds
+const HEARTBEAT_TIMEOUT = 60000; // 60 seconds - time without heartbeat before reconnecting
+const HEARTBEAT_CHECK_INTERVAL = 30000; // 30 seconds - how often to check for heartbeat timeout
 /**
  * Connection Manager for a single NapCat account
  */
@@ -16,11 +18,10 @@ export class ConnectionManager extends EventEmitter {
     state = 'disconnected';
     // Heartbeat - active ping + OneBot 11 meta_event based
     lastHeartbeatTime = 0;
-    // Connection stats
-    totalReconnectAttempts = 0;
+    heartbeatCheckTimer;
     // Reconnection
     reconnectTimer;
-    reconnectAttempts = 0;
+    totalReconnectAttempts = 0;
     shouldReconnect = true;
     // Pending requests
     pendingRequests = new Map();
@@ -46,7 +47,6 @@ export class ConnectionManager extends EventEmitter {
             return;
         }
         this.shouldReconnect = true;
-        this.reconnectAttempts = 0;
         await this.connect();
         log.info('connection', `Started connection`);
     }
@@ -71,12 +71,25 @@ export class ConnectionManager extends EventEmitter {
         try {
             // Build WebSocket URL with access_token query parameter (NapCat OneBot 11 standard)
             let wsUrl = this.config.wsUrl;
+            // Validate URL format before processing
+            if (!wsUrl || !wsUrl.match(/^wss?:\/\//)) {
+                log.error('connection', `Invalid WebSocket URL: ${wsUrl}`);
+                return;
+            }
             if (this.config.accessToken) {
-                const url = new URL(wsUrl);
-                url.searchParams.set('access_token', this.config.accessToken);
-                wsUrl = url.toString();
+                try {
+                    const url = new URL(wsUrl);
+                    url.searchParams.set('access_token', this.config.accessToken);
+                    wsUrl = url.toString();
+                }
+                catch (urlError) {
+                    log.error('connection', `Failed to parse WebSocket URL: ${wsUrl}`);
+                    return;
+                }
             }
-            log.info('connection', `Connecting to ${wsUrl}`);
+            // Sanitize URL for logging (hide access token)
+            const sanitizedUrl = wsUrl.replace(/access_token=[^&]+/, 'access_token=***');
+            log.info('connection', `Connecting to ${sanitizedUrl}`);
             this.ws = new WebSocket(wsUrl);
             this.ws.on('open', this.handleOpen.bind(this));
             this.ws.on('message', this.handleMessage.bind(this));
@@ -102,10 +115,75 @@ export class ConnectionManager extends EventEmitter {
             this.handleConnectionFailed(error instanceof Error ? error : new Error(String(error)));
         }
     }
+    /**
+     * Clear all pending requests and reject them with an error
+     */
+    clearPendingRequests(reason) {
+        if (this.pendingRequests.size === 0) {
+            return;
+        }
+        log.debug('connection', `Clearing ${this.pendingRequests.size} pending requests: ${reason}`);
+        for (const [_echo, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error(`Connection closed: ${reason}`));
+        }
+        this.pendingRequests.clear();
+    }
+    // ==========================================================================
+    // Heartbeat Timeout Detection
+    // ==========================================================================
+    /**
+     * Start heartbeat timeout detection
+     */
+    startHeartbeatCheck() {
+        this.stopHeartbeatCheck();
+        this.heartbeatCheckTimer = setInterval(() => {
+            const elapsed = Date.now() - this.lastHeartbeatTime;
+            if (elapsed > HEARTBEAT_TIMEOUT && this.isConnected()) {
+                log.warn('connection', `Heartbeat timeout (${elapsed}ms since last heartbeat), reconnecting...`);
+                this.healthStatus = {
+                    healthy: false,
+                    lastHeartbeatAt: this.lastHeartbeatTime,
+                    consecutiveFailures: this.healthStatus.consecutiveFailures + 1,
+                };
+                this.emit('heartbeat', this.healthStatus);
+                // Close connection and trigger immediate reconnect
+                this.close('Heartbeat timeout').then(() => {
+                    if (this.shouldReconnect) {
+                        // Increment total reconnect attempts
+                        this.totalReconnectAttempts++;
+                        // Emit reconnecting event for external status updates
+                        this.emit('reconnecting', {
+                            reason: 'heartbeat-timeout',
+                            totalAttempts: this.totalReconnectAttempts,
+                        });
+                        this.connect().catch(error => {
+                            log.error('connection', `Reconnect failed:`, error);
+                        });
+                    }
+                });
+            }
+        }, HEARTBEAT_CHECK_INTERVAL);
+        log.debug('connection', 'Started heartbeat timeout detection');
+    }
+    /**
+     * Stop heartbeat timeout detection
+     */
+    stopHeartbeatCheck() {
+        if (this.heartbeatCheckTimer) {
+            clearInterval(this.heartbeatCheckTimer);
+            this.heartbeatCheckTimer = undefined;
+            log.debug('connection', 'Stopped heartbeat timeout detection');
+        }
+    }
     /**
      * Close WebSocket connection
      */
     async close(reason) {
+        // Stop heartbeat detection
+        this.stopHeartbeatCheck();
+        // Clear all pending requests before closing connection
+        this.clearPendingRequests(reason);
         if (this.ws) {
             log.info('connection', `Closing connection: ${reason}`);
             // Clear event listeners to prevent further processing
@@ -122,8 +200,8 @@ export class ConnectionManager extends EventEmitter {
     handleOpen() {
         log.info('connection', `Connected to NapCat`);
         this.setState('connected');
-        this.totalReconnectAttempts += this.reconnectAttempts;
-        this.reconnectAttempts = 0;
+        // Start heartbeat timeout detection
+        this.startHeartbeatCheck();
         this.emit('connected');
     }
     handleMessage(data) {
@@ -220,17 +298,17 @@ export class ConnectionManager extends EventEmitter {
         if (!this.shouldReconnect) {
             return;
         }
-        if (MAX_RECONNECT_ATTEMPTS != -1 && this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+        if (MAX_RECONNECT_ATTEMPTS != -1 && this.totalReconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
             log.error('connection', `Max reconnect attempts reached`);
             this.setState('failed', 'Max reconnect attempts reached');
             this.emit('max-reconnect-attempts-reached');
             return;
         }
-        const delayMs = calculateBackoff(this.reconnectAttempts);
-        log.info('connection', `Scheduling reconnect in ${delayMs}ms (attempt ${this.reconnectAttempts + 1}/${MAX_RECONNECT_ATTEMPTS})`);
+        const delayMs = calculateBackoff(this.totalReconnectAttempts);
+        log.info('connection', `Scheduling reconnect in ${delayMs}ms (attempt ${this.totalReconnectAttempts + 1}/${MAX_RECONNECT_ATTEMPTS})`);
         this.clearReconnectTimer();
         this.reconnectTimer = setTimeout(async () => {
-            this.reconnectAttempts++;
+            this.totalReconnectAttempts++;
             try {
                 await this.connect();
             }
@@ -304,9 +382,9 @@ export class ConnectionManager extends EventEmitter {
         return {
             state: this.state,
             lastConnected: this.lastHeartbeatTime || undefined,
-            lastAttempted: this.reconnectAttempts > 0 ? Date.now() : undefined,
+            lastAttempted: this.totalReconnectAttempts > 0 ? Date.now() : undefined,
             error: this.state === 'failed' ? 'Connection failed' : undefined,
-            reconnectAttempts: this.reconnectAttempts > 0 ? this.reconnectAttempts : undefined,
+            reconnectAttempts: this.totalReconnectAttempts > 0 ? this.totalReconnectAttempts : undefined,
         };
     }
     // ==========================================================================

package/dist/src/core/dispatch.d.ts

@@ -2,7 +2,7 @@
  * Message Dispatch Module
  * Handles routing and dispatching incoming messages to the AI
  */
-import type { DispatchMessageParams } from '../types/index.js';
+import type { DispatchMessageParams } from '../types';
 /**
  * Dispatch an incoming message to the AI for processing
  */

package/dist/src/core/dispatch.js

@@ -4,8 +4,8 @@
  */
 import { getRuntime, getContext } from './runtime.js';
 import { getFile, sendMsg, setInputStatus } from './request.js';
-import { napCatToOpenClawMessage } from '../adapters/message.js';
-import { Logger as log, markdownToText } from '../utils/index.js';
+import { napCatToOpenClawMessage, openClawToNapCatMessage } from '../adapters/message.js';
+import { Logger as log, markdownToText, buildMediaMessage } from '../utils/index.js';
 import { CHANNEL_ID } from "./config.js";
 /**
  * Convert OpenClaw message content array to plain text
@@ -24,7 +24,9 @@ async function contentToPlainText(content) {
             case 'json':
                 return `[JSON]\n\`\`\`json\n${c.data}\n\`\`\``;
             case 'reply':
-                let replyContent = `${c.sender}(${c.senderId}):\n${c.message}`;
+                const senderInfo = c.sender && c.senderId ? `${c.sender}(${c.senderId})` : '未知用户';
+                const replyMsg = c.message ?? '[无法获取原消息]';
+                let replyContent = `${senderInfo}:\n${replyMsg}`;
                 replyContent = replyContent.split('\n').map(line => `> ${line}`).join('\n');
                 return `[回复]\n${replyContent}\n`;
             default:
@@ -83,6 +85,21 @@ async function sendText(isGroup, chatId, text) {
         log.error('dispatch', `Send failed: ${error}`);
     }
 }
+async function sendMedia(isGroup, chatId, mediaUrl) {
+    const content = [buildMediaMessage(mediaUrl)];
+    try {
+        await sendMsg({
+            message_type: isGroup ? 'group' : 'private',
+            group_id: isGroup ? chatId : undefined,
+            user_id: !isGroup ? chatId : undefined,
+            message: openClawToNapCatMessage(content),
+        });
+        log.info('dispatch', `Sent reply: ${mediaUrl.slice(0, 100)}`);
+    }
+    catch (error) {
+        log.error('dispatch', `Send failed: ${error}`);
+    }
+}
 /**
  * Dispatch an incoming message to the AI for processing
  */
@@ -168,9 +185,20 @@ export async function dispatchMessage(params) {
                 },
                 deliver: async (payload, info) => {
                     log.info('dispatch', `deliver(${info.kind}): ${JSON.stringify(payload)}`);
-                    if (payload.text) {
+                    if (payload.text && !payload.text.startsWith('MEDIA:')) {
                         await sendText(isGroup, chatId, payload.text);
                     }
+                    if (payload.text && payload.text.startsWith('MEDIA:')) {
+                        await sendMedia(isGroup, chatId, payload.text.replace('MEDIA:', ''));
+                    }
+                    if (payload.mediaUrl) {
+                        await sendMedia(isGroup, chatId, payload.mediaUrl);
+                    }
+                    if (payload.mediaUrls && payload.mediaUrls.length > 0) {
+                        for (const mediaUrl of payload.mediaUrls) {
+                            await sendMedia(isGroup, chatId, mediaUrl);
+                        }
+                    }
                 },
                 onError: async (err) => {
                     log.error('dispatch', `Dispatch error: ${err}`);

package/dist/src/core/request.d.ts

@@ -1,11 +1,11 @@
-import type { GetFileReq, GetFileResp, GetMsgReq, GetMsgResp, NapCatResp, SendMsgReq, SendMsgResp, SetInputStatusReq } from "../types/index.js";
+import type { GetFileReq, GetFileResp, GetMsgReq, GetMsgResp, GetStatusResp, NapCatResp, SendMsgReq, SendMsgResp, SetInputStatusReq } from "../types";
 /**
  * 事件监听
  * @param event
  */
 export declare function eventListener(event: any): Promise<void>;
 /**
- * 发送消息
+ * 发送消息（带限流）
  * @param params
  */
 export declare function sendMsg(params: SendMsgReq): Promise<NapCatResp<SendMsgResp>>;
@@ -24,3 +24,7 @@ export declare function getFile(params: GetFileReq): Promise<NapCatResp<GetFileR
  * @param params
  */
 export declare function setInputStatus(params: SetInputStatusReq): Promise<NapCatResp<void>>;
+/**
+ * 获取状态
+ */
+export declare function getStatus(): Promise<NapCatResp<GetStatusResp>>;

package/dist/src/core/request.js

@@ -1,7 +1,13 @@
+import pLimit from 'p-limit';
 import { Logger as log } from "../utils/index.js";
 import { setContextStatus, getContext, getConnection } from "./runtime.js";
 import { handleGroupMessage, handlePrivateMessage, handlePokeEvent } from "./dispatch.js";
 import { failResp } from "./connection.js";
+/**
+ * Rate limiter for sendMsg requests
+ * Limits concurrent messages to prevent API throttling
+ */
+const sendMsgLimiter = pLimit(1);
 /**
  * 事件监听
  * @param event
@@ -20,6 +26,11 @@ export async function eventListener(event) {
     }
     switch (event.post_type) {
         case "message":
+            // 过滤空消息
+            if (!event.raw_message || event.raw_message === '') {
+                log.debug("request", `Ignored empty message`);
+                break;
+            }
             setContextStatus({
                 lastInboundAt: Date.now(),
             });
@@ -66,7 +77,7 @@ export async function eventListener(event) {
     }
 }
 /**
- * 发送消息
+ * 发送消息（带限流）
  * @param params
  */
 export async function sendMsg(params) {
@@ -75,7 +86,8 @@ export async function sendMsg(params) {
         log.warn("request", `No connection available`);
         return failResp();
     }
-    return connection.sendRequest("send_msg", params);
+    // 使用限流器控制并发，避免触发 NapCat API 限流
+    return sendMsgLimiter(() => connection.sendRequest("send_msg", params));
 }
 /**
  * 获取消息
@@ -113,3 +125,14 @@ export async function setInputStatus(params) {
     }
     return connection.sendRequest("set_input_status", params);
 }
+/**
+ * 获取状态
+ */
+export async function getStatus() {
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return failResp();
+    }
+    return connection.sendRequest("get_status");
+}

package/dist/src/types/index.d.ts

@@ -243,6 +243,11 @@ export interface SetInputStatusReq {
     user_id: string;
     event_type: 0 | 1 | 2;
 }
+export interface GetStatusResp {
+    online: boolean;
+    good: boolean;
+    stat: Record<any, any>;
+}
 export interface DispatchMessageMedia {
     type?: string;
     path?: string;
@@ -258,3 +263,8 @@ export interface DispatchMessageParams {
     media?: DispatchMessageMedia;
     timestamp: number;
 }
+export type QQProbe = {
+    ok: boolean;
+    status?: number | null;
+    error?: string | null;
+};

package/dist/src/utils/index.d.ts

@@ -1,12 +1,15 @@
 /**
  * Utility functions for QQ NapCat plugin
  */
+import type { OpenClawMessage } from '../types';
 /**
  * Generate a unique message ID for OpenClaw
+ * Uses UUID for thread-safe and collision-free ID generation
  */
 export declare function generateMessageId(): string;
 /**
  * Generate a unique echo ID for request correlation
+ * Uses UUID for thread-safe and collision-free ID generation
  */
 export declare function generateEchoId(): string;
 /**
@@ -49,6 +52,11 @@ export declare function getCloseCodeMessage(code: number): string;
 export type FileCategory = 'image' | 'audio' | 'file';
 export declare function getFileType(pathOrUrl: string): FileCategory;
 export declare function getFileName(pathOrUrl: string): string;
+/**
+ * Build an OpenClawMessage from a media URL
+ * Automatically detects file type (image, audio, or file)
+ */
+export declare function buildMediaMessage(mediaUrl: string): OpenClawMessage;
 export { CQCodeUtils, CQNode } from './cqcode.js';
 export { Logger } from './log.js';
 export { MarkdownToText, markdownToText, } from './markdown.js';

package/dist/src/utils/index.js

@@ -1,21 +1,23 @@
 /**
  * Utility functions for QQ NapCat plugin
  */
+import { randomUUID } from 'crypto';
 // =============================================================================
 // ID Generation
 // =============================================================================
-let idCounter = 0;
 /**
  * Generate a unique message ID for OpenClaw
+ * Uses UUID for thread-safe and collision-free ID generation
  */
 export function generateMessageId() {
-    return `qq-${Date.now()}-${++idCounter}`;
+    return `qq-${randomUUID()}`;
 }
 /**
  * Generate a unique echo ID for request correlation
+ * Uses UUID for thread-safe and collision-free ID generation
  */
 export function generateEchoId() {
-    return `echo-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    return `echo-${randomUUID()}`;
 }
 // =============================================================================
 // Message ID Conversion
@@ -296,6 +298,33 @@ export function getFileName(pathOrUrl) {
     }
 }
 // =============================================================================
+// Media Message Builder
+// =============================================================================
+/**
+ * Build an OpenClawMessage from a media URL
+ * Automatically detects file type (image, audio, or file)
+ */
+export function buildMediaMessage(mediaUrl) {
+    const trimmedUrl = mediaUrl.trim();
+    switch (getFileType(trimmedUrl)) {
+        case "image":
+            return { type: "image", url: trimmedUrl };
+        case "audio":
+            return {
+                type: "audio",
+                path: trimmedUrl,
+                url: trimmedUrl,
+                file: getFileName(trimmedUrl)
+            };
+        default:
+            return {
+                type: "file",
+                url: trimmedUrl,
+                file: getFileName(trimmedUrl)
+            };
+    }
+}
+// =============================================================================
 // CQ Code Utilities
 // =============================================================================
 export { CQCodeUtils } from './cqcode.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izhimu/qq",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "A QQ channel plugin for OpenClaw using NapCat WebSocket",
   "type": "module",
   "main": "dist/index.js",
@@ -49,6 +49,7 @@
     }
   },
   "dependencies": {
+    "p-limit": "^7.3.0",
     "ws": "^8.19.0",
     "zod": "^4.3.6"
   },