@tencent-connect/openclaw-qqbot 1.6.4-alpha.13 → 1.6.4-alpha.15

package/clawdbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -2,6 +2,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
 import { registerChannelTool } from "./src/tools/channel.js";
+import { registerRemindTool } from "./src/tools/remind.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -11,6 +12,7 @@ const plugin = {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
         registerChannelTool(api);
+        registerRemindTool(api);
     },
 };
 export default plugin;

package/dist/src/channel.js

@@ -5,6 +5,7 @@ import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
+import { initApiConfig } from "./api.js";
 /** QQ Bot 单条消息文本长度上限 */
 export const TEXT_CHUNK_LIMIT = 5000;
 /**
@@ -201,6 +202,7 @@ export const qqbotPlugin = {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
             const account = resolveQQBotAccount(cfg, accountId);
+            initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendText({ to, text, accountId, replyToId, account });
             console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
@@ -213,6 +215,7 @@ export const qqbotPlugin = {
         sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
             const account = resolveQQBotAccount(cfg, accountId);
+            initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
             console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);

package/dist/src/gateway.js

@@ -8,12 +8,12 @@ import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex } from "./ref-index-store.js";
 import { matchSlashCommand, getPluginVersion } from "./slash-commands.js";
 import { triggerUpdateCheck } from "./update-checker.js";
-import { startImageServer, isImageServerRunning, downloadFile } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload } from "./utils/payload.js";
 import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig, textToSilk } from "./utils/audio-convert.js";
+import { startImageServer, isImageServerRunning } from "./image-server.js";
 import { normalizeMediaTags } from "./utils/media-tags.js";
-import { checkFileSize, readFileAsync, fileExistsAsync, formatFileSize } from "./utils/file-utils.js";
+import { checkFileSize, readFileAsync, fileExistsAsync, formatFileSize, downloadFile } from "./utils/file-utils.js";
 import { getQQBotDataDir, isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
 import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto } from "./outbound.js";
 import { chunkText, TEXT_CHUNK_LIMIT } from "./channel.js";
@@ -628,12 +628,34 @@ export async function startGateway(ctx) {
         };
     };
     // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
+    // 紧急命令列表：这些命令会立即执行，不进入斜杠匹配流程
+    const URGENT_COMMANDS = ["/stop"];
     const trySlashCommandOrEnqueue = async (msg) => {
         const content = (msg.content ?? "").trim();
         if (!content.startsWith("/")) {
             enqueueMessage(msg);
             return;
         }
+        // 检测是否为紧急命令 — 立即执行，清空该用户队列
+        const contentLower = content.toLowerCase();
+        const isUrgentCommand = URGENT_COMMANDS.some(cmd => contentLower.startsWith(cmd.toLowerCase()));
+        if (isUrgentCommand) {
+            log?.info(`[qqbot:${account.accountId}] Urgent command detected: ${content.slice(0, 20)}, executing immediately`);
+            const peerId = getMessagePeerId(msg);
+            const queue = userQueues.get(peerId);
+            if (queue) {
+                const droppedCount = queue.length;
+                queue.length = 0;
+                totalEnqueued = Math.max(0, totalEnqueued - droppedCount);
+                log?.info(`[qqbot:${account.accountId}] Dropped ${droppedCount} queued messages for ${peerId} due to urgent command`);
+            }
+            if (handleMessageFnRef) {
+                handleMessageFnRef(msg).catch(err => {
+                    log?.error(`[qqbot:${account.accountId}] Urgent command error: ${err}`);
+                });
+            }
+            return;
+        }
         const receivedAt = Date.now();
         const peerId = getMessagePeerId(msg);
         const cmdCtx = {
@@ -834,7 +856,7 @@ export async function startGateway(ctx) {
                 });
                 const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(cfg);
                 // 组装消息体
-                // 静态系统提示已移至 skills/qqbot-cron/SKILL.md 和 skills/qqbot-media/SKILL.md
+                // 静态系统提示已移至 skills/qqbot-remind/SKILL.md 和 skills/qqbot-media/SKILL.md
                 // BodyForAgent 只保留必要的动态上下文信息
                 // ============ 用户标识信息 ============
                 // 收集额外的系统提示（如果配置了账户级别的 systemPrompt）

package/dist/src/slash-commands.js

@@ -337,26 +337,55 @@ function switchPluginSourceToNpm() {
             const cfgPath = path.join(homeDir, `.${cli}`, `${cli}.json`);
             if (!fs.existsSync(cfgPath))
                 continue;
-            // 读取当前配置
+            // 读取当前配置（保留原始文本用于回退）
             const raw = fs.readFileSync(cfgPath, "utf8");
-            const cfg = JSON.parse(raw);
+            let cfg;
+            try {
+                cfg = JSON.parse(raw);
+            }
+            catch {
+                // 配置文件已经是损坏的 JSON，不要继续操作以免加剧问题
+                break;
+            }
             const inst = cfg?.plugins?.installs?.["openclaw-qqbot"];
             if (!inst || inst.source === "npm") {
                 break; // 无需修改
             }
-            // 记录修改前的 channels.qqbot 快照，用于写后校验
-            const channelsBefore = JSON.stringify(cfg.channels?.qqbot ?? null);
+            // 记录修改前的完整快照，用于写后校验
+            const channelsBefore = JSON.stringify(cfg.channels ?? null);
             inst.source = "npm";
             delete inst.sourcePath;
             const newRaw = JSON.stringify(cfg, null, 4) + "\n";
-            // 写后校验：重新解析确认 channels.qqbot 未被破坏
-            const verify = JSON.parse(newRaw);
-            const channelsAfter = JSON.stringify(verify.channels?.qqbot ?? null);
+            // 写后校验：重新解析确认整个 JSON 合法且 channels 未被破坏
+            let verify;
+            try {
+                verify = JSON.parse(newRaw);
+            }
+            catch {
+                // stringify 后竟然无法 parse（理论上不会），放弃写入
+                break;
+            }
+            const channelsAfter = JSON.stringify(verify.channels ?? null);
             if (channelsBefore !== channelsAfter) {
                 // channels 数据异常，放弃写入
                 break;
             }
-            fs.writeFileSync(cfgPath, newRaw);
+            // 原子写入：先写临时文件，再 rename 替换，避免写入中途崩溃导致配置文件损坏
+            const tmpPath = cfgPath + ".qqbot-upgrade.tmp";
+            fs.writeFileSync(tmpPath, newRaw, { mode: 0o644 });
+            // 再次校验临时文件的完整性
+            try {
+                JSON.parse(fs.readFileSync(tmpPath, "utf8"));
+            }
+            catch {
+                // 写入的临时文件不完整，清理后放弃
+                try {
+                    fs.unlinkSync(tmpPath);
+                }
+                catch { }
+                break;
+            }
+            fs.renameSync(tmpPath, cfgPath);
             break;
         }
     }

package/dist/src/tools/remind.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+export declare function registerRemindTool(api: OpenClawPluginApi): void;

package/dist/src/tools/remind.js

@@ -0,0 +1,247 @@
+// ========== JSON Schema ==========
+const RemindSchema = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            description: "操作类型。add=创建提醒, list=查看已有提醒, remove=删除提醒",
+            enum: ["add", "list", "remove"],
+        },
+        content: {
+            type: "string",
+            description: '提醒内容，如"喝水"、"开会"。action=add 时必填。',
+        },
+        to: {
+            type: "string",
+            description: "投递目标地址，取自上下文中 [QQBot] to= 的值。" +
+                "私聊格式：user_openid，群聊格式：group:group_openid。action=add 时必填。",
+        },
+        time: {
+            type: "string",
+            description: "时间描述。支持两种格式：\n" +
+                "1. 相对时间：如 \"5m\"(5分钟后)、\"1h\"(1小时后)、\"1h30m\"(1.5小时后)、\"2d\"(2天后)\n" +
+                "2. cron 表达式：如 \"0 8 * * *\"(每天8点)、\"0 9 * * 1-5\"(工作日9点)\n" +
+                "系统会自动判断：包含空格的视为 cron 表达式（周期提醒），否则视为相对时间（一次性提醒）。\n" +
+                "action=add 时必填。",
+        },
+        timezone: {
+            type: "string",
+            description: "时区，仅周期提醒(cron)时需要。默认 \"Asia/Shanghai\"。",
+        },
+        name: {
+            type: "string",
+            description: "提醒任务名称（可选）。默认自动从 content 截取前 20 字。",
+        },
+        jobId: {
+            type: "string",
+            description: "要删除的任务 ID。action=remove 时必填，先用 list 获取。",
+        },
+    },
+    required: ["action"],
+};
+// ========== 工具函数 ==========
+function json(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}
+/**
+ * 解析相对时间字符串为毫秒数
+ * 支持格式：5m, 1h, 1h30m, 2d, 30s, 1d2h30m 等
+ */
+function parseRelativeTime(timeStr) {
+    const s = timeStr.trim().toLowerCase();
+    // 纯数字 → 视为分钟
+    if (/^\d+$/.test(s)) {
+        return parseInt(s, 10) * 60_000;
+    }
+    let totalMs = 0;
+    let matched = false;
+    const regex = /(\d+(?:\.\d+)?)\s*(d|h|m|s)/g;
+    let match;
+    while ((match = regex.exec(s)) !== null) {
+        matched = true;
+        const value = parseFloat(match[1]);
+        const unit = match[2];
+        switch (unit) {
+            case "d":
+                totalMs += value * 86_400_000;
+                break;
+            case "h":
+                totalMs += value * 3_600_000;
+                break;
+            case "m":
+                totalMs += value * 60_000;
+                break;
+            case "s":
+                totalMs += value * 1_000;
+                break;
+        }
+    }
+    return matched ? Math.round(totalMs) : null;
+}
+/**
+ * 判断是否为 cron 表达式（包含空格且有 3~6 段）
+ */
+function isCronExpression(timeStr) {
+    const parts = timeStr.trim().split(/\s+/);
+    return parts.length >= 3 && parts.length <= 6;
+}
+/**
+ * 自动生成任务名称
+ */
+function generateJobName(content) {
+    const trimmed = content.trim();
+    const short = trimmed.length > 20 ? trimmed.slice(0, 20) + "…" : trimmed;
+    return `提醒: ${short}`;
+}
+/**
+ * 构建一次性提醒的 cron 工具参数
+ */
+function buildOnceJob(params, delayMs) {
+    const atMs = Date.now() + delayMs;
+    const to = params.to;
+    const content = params.content;
+    const name = params.name || generateJobName(content);
+    return {
+        action: "add",
+        job: {
+            name,
+            schedule: { kind: "at", atMs },
+            sessionTarget: "isolated",
+            wakeMode: "now",
+            deleteAfterRun: true,
+            payload: {
+                kind: "agentTurn",
+                message: buildReminderPrompt(content),
+                deliver: true,
+                channel: "qqbot",
+                to,
+            },
+        },
+    };
+}
+/**
+ * 构建周期提醒的 cron 工具参数
+ */
+function buildCronJob(params) {
+    const to = params.to;
+    const content = params.content;
+    const name = params.name || generateJobName(content);
+    const tz = params.timezone || "Asia/Shanghai";
+    return {
+        action: "add",
+        job: {
+            name,
+            schedule: { kind: "cron", expr: params.time.trim(), tz },
+            sessionTarget: "isolated",
+            wakeMode: "now",
+            payload: {
+                kind: "agentTurn",
+                message: buildReminderPrompt(content),
+                deliver: true,
+                channel: "qqbot",
+                to,
+            },
+        },
+    };
+}
+/**
+ * 构建提醒 payload 中的 AI prompt
+ */
+function buildReminderPrompt(content) {
+    return (`你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：${content}。` +
+        `要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 ` +
+        `(3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 ` +
+        `(5) 控制在2-3句话以内 (6) 用emoji点缀`);
+}
+/**
+ * 格式化延迟时间为人类可读文本
+ */
+function formatDelay(ms) {
+    const totalSeconds = Math.round(ms / 1000);
+    if (totalSeconds < 60)
+        return `${totalSeconds}秒`;
+    const totalMinutes = Math.round(ms / 60_000);
+    if (totalMinutes < 60)
+        return `${totalMinutes}分钟`;
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    if (minutes === 0)
+        return `${hours}小时`;
+    return `${hours}小时${minutes}分钟`;
+}
+// ========== 注册入口 ==========
+export function registerRemindTool(api) {
+    api.registerTool({
+        name: "qqbot_remind",
+        label: "QQBot 定时提醒",
+        description: "创建、查询、删除 QQ 定时提醒。" +
+            "使用简单参数即可，无需手动构造 cron JSON。\n" +
+            "创建提醒：action=add, content=提醒内容, to=目标地址, time=时间\n" +
+            "查看提醒：action=list\n" +
+            "删除提醒：action=remove, jobId=任务ID（先 list 获取）\n" +
+            "时间格式示例：\"5m\"(5分钟后) \"1h\"(1小时后) \"0 8 * * *\"(每天8点)",
+        parameters: RemindSchema,
+        execute(_toolCallId, params) {
+            const p = params;
+            // ===== list =====
+            if (p.action === "list") {
+                return json({
+                    _instruction: "请立即使用 cron 工具执行以下参数",
+                    cronParams: { action: "list" },
+                });
+            }
+            // ===== remove =====
+            if (p.action === "remove") {
+                if (!p.jobId) {
+                    return json({ error: "action=remove 时 jobId 为必填参数。请先用 action=list 获取 jobId。" });
+                }
+                return json({
+                    _instruction: "请立即使用 cron 工具执行以下参数",
+                    cronParams: { action: "remove", jobId: p.jobId },
+                });
+            }
+            // ===== add =====
+            if (!p.content) {
+                return json({ error: "action=add 时 content（提醒内容）为必填参数" });
+            }
+            if (!p.to) {
+                return json({ error: "action=add 时 to（目标地址）为必填参数，取自上下文 [QQBot] to= 的值" });
+            }
+            if (!p.time) {
+                return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
+            }
+            // 判断是 cron 表达式还是相对时间
+            if (isCronExpression(p.time)) {
+                // 周期提醒
+                const cronJob = buildCronJob(p);
+                return json({
+                    _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
+                    cronParams: cronJob,
+                    summary: `⏰ 周期提醒: "${p.content}" (${p.time}, tz=${p.timezone || "Asia/Shanghai"})`,
+                });
+            }
+            // 一次性提醒
+            const delayMs = parseRelativeTime(p.time);
+            if (!delayMs || delayMs <= 0) {
+                return json({
+                    error: `无法解析时间 "${p.time}"。支持格式：` +
+                        `相对时间如 "5m"、"1h"、"1h30m"、"2d"；` +
+                        `cron 表达式如 "0 8 * * *"（每天8点）`,
+                });
+            }
+            if (delayMs < 30_000) {
+                return json({ error: "提醒时间不能少于 30 秒" });
+            }
+            const onceJob = buildOnceJob(p, delayMs);
+            return json({
+                _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
+                cronParams: onceJob,
+                summary: `⏰ ${formatDelay(delayMs)}后提醒: "${p.content}"`,
+            });
+        },
+    }, { name: "qqbot_remind" });
+    console.log("[qqbot-remind] Registered QQBot remind tool");
+}

package/dist/src/utils/file-utils.d.ts

@@ -44,3 +44,12 @@ export declare function formatFileSize(bytes: number): string;
  * 根据文件扩展名获取 MIME 类型
  */
 export declare function getMimeType(filePath: string): string;
+/**
+ * 将远端文件下载到本地目录。
+ *
+ * @param url 远端 URL
+ * @param destDir 目标目录（不存在时自动创建）
+ * @param originalFilename 可选的原始文件名（覆盖 URL 推断）
+ * @returns 本地文件完整路径；下载失败返回 null
+ */
+export declare function downloadFile(url: string, destDir: string, originalFilename?: string): Promise<string | null>;

package/dist/src/utils/file-utils.js

@@ -3,6 +3,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import crypto from "node:crypto";
 /** QQ Bot API 最大上传文件大小：20MB */
 export const MAX_UPLOAD_SIZE = 20 * 1024 * 1024;
 /** 大文件阈值（超过此值发送进度提示）：5MB */
@@ -105,3 +106,45 @@ export function getMimeType(filePath) {
     };
     return mimeTypes[ext] ?? "application/octet-stream";
 }
+/**
+ * 将远端文件下载到本地目录。
+ *
+ * @param url 远端 URL
+ * @param destDir 目标目录（不存在时自动创建）
+ * @param originalFilename 可选的原始文件名（覆盖 URL 推断）
+ * @returns 本地文件完整路径；下载失败返回 null
+ */
+export async function downloadFile(url, destDir, originalFilename) {
+    try {
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        const resp = await fetch(url, { redirect: "follow" });
+        if (!resp.ok || !resp.body)
+            return null;
+        // 确定文件名：优先使用 originalFilename，否则从 URL 推断
+        let filename = originalFilename?.trim() || "";
+        if (!filename) {
+            try {
+                const urlPath = new URL(url).pathname;
+                filename = path.basename(urlPath) || "download";
+            }
+            catch {
+                filename = "download";
+            }
+        }
+        // 加上时间戳避免同名冲突
+        const ts = Date.now();
+        const ext = path.extname(filename);
+        const base = path.basename(filename, ext) || "file";
+        const rand = crypto.randomBytes(3).toString("hex");
+        const safeFilename = `${base}_${ts}_${rand}${ext}`;
+        const destPath = path.join(destDir, safeFilename);
+        const buffer = Buffer.from(await resp.arrayBuffer());
+        await fs.promises.writeFile(destPath, buffer);
+        return destPath;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -29,6 +29,16 @@ export declare function getHomeDir(): string;
  * 替代各文件中分散的 path.join(HOME, ".openclaw", "qqbot", ...)
  */
 export declare function getQQBotDataDir(...subPaths: string[]): string;
+/**
+ * 获取 .openclaw/media/qqbot 下的子目录路径，并自动创建
+ *
+ * 与 getQQBotDataDir 不同，此目录位于 OpenClaw 核心的媒体安全白名单
+ * (~/.openclaw/media) 之下，下载到这里的文件可以被框架的 image/media
+ * 工具直接访问，不会触发 "Local media path is not under an allowed directory" 错误。
+ *
+ * 用于存放从 QQ 下载的图片、语音等需要被框架处理的媒体文件。
+ */
+export declare function getQQBotMediaDir(...subPaths: string[]): string;
 /**
  * 获取系统临时目录（跨平台安全）
  * Mac: /var/folders/... 或 /tmp

package/dist/src/utils/platform.js

@@ -59,6 +59,22 @@ export function getQQBotDataDir(...subPaths) {
     }
     return dir;
 }
+/**
+ * 获取 .openclaw/media/qqbot 下的子目录路径，并自动创建
+ *
+ * 与 getQQBotDataDir 不同，此目录位于 OpenClaw 核心的媒体安全白名单
+ * (~/.openclaw/media) 之下，下载到这里的文件可以被框架的 image/media
+ * 工具直接访问，不会触发 "Local media path is not under an allowed directory" 错误。
+ *
+ * 用于存放从 QQ 下载的图片、语音等需要被框架处理的媒体文件。
+ */
+export function getQQBotMediaDir(...subPaths) {
+    const dir = path.join(getHomeDir(), ".openclaw", "media", "qqbot", ...subPaths);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
 // ============ 临时目录 ============
 /**
  * 获取系统临时目录（跨平台安全）

package/index.ts

@@ -4,6 +4,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
 import { registerChannelTool } from "./src/tools/channel.js";
+import { registerRemindTool } from "./src/tools/remind.js";
 
 const plugin = {
   id: "openclaw-qqbot",
@@ -14,6 +15,7 @@ const plugin = {
     setQQBotRuntime(api.runtime);
     api.registerChannel({ plugin: qqbotPlugin });
     registerChannelTool(api);
+    registerRemindTool(api);
   },
 };
 

package/moltbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.4-alpha.13",
+  "version": "1.6.4-alpha.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/{qqbot-cron → qqbot-remind}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qqbot-cron
+name: qqbot-remind
 description: QQBot 定时提醒。支持一次性和周期性提醒的创建、查询、取消。当通过 QQ 通道通信且涉及提醒/定时任务时使用。
 metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 ---
@@ -8,13 +8,43 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 
 ## ⚠️ 强制规则
 
-**当用户提到「提醒」「闹钟」「定时」「X分钟/小时后」「每天X点」「叫我」等任何涉及延时或定时的请求时，你必须调用 `cron` 工具，绝对不能只用自然语言回复说"好的，我会提醒你"！**
+**当用户提到「提醒」「闹钟」「定时」「X分钟/小时后」「每天X点」「叫我」等任何涉及延时或定时的请求时，你必须调用工具，绝对不能只用自然语言回复说"好的，我会提醒你"！**
 
-你没有内存或后台线程，口头承诺"到时候提醒"是无效的——只有调用 `cron` 工具才能真正注册定时任务。
+你没有内存或后台线程，口头承诺"到时候提醒"是无效的——只有调用工具才能真正注册定时任务。
 
 ---
 
-## 核心规则
+## 推荐流程（优先使用 `qqbot_remind` 工具）
+
+**第一步**：调用 `qqbot_remind` 工具，传入简单参数：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `action` | 操作类型 | `"add"` / `"list"` / `"remove"` |
+| `content` | 提醒内容 | `"喝水"` |
+| `to` | 目标地址（取自上下文 `[QQBot] to=` 的值） | `"user_openid_xxx"` 或 `"group:group_openid_xxx"` |
+| `time` | 时间（相对时间或 cron 表达式） | `"5m"` / `"1h30m"` / `"0 8 * * *"` |
+| `jobId` | 任务 ID（仅 remove） | `"xxx"` |
+
+**第二步**：`qqbot_remind` 会返回 `cronParams`，你必须**立即**将 `cronParams` 的值作为参数调用 `cron` 工具。
+
+**第三步**：根据 `cron` 工具的返回结果，回复用户。
+
+### 示例
+
+用户说："5分钟后提醒我喝水"
+
+1. 调用 `qqbot_remind`：`{ "action": "add", "content": "喝水", "to": "xxx", "time": "5m" }`
+2. 收到返回的 `cronParams` → 立即调用 `cron` 工具，参数为该 `cronParams`
+3. 回复用户：`⏰ 好的，5分钟后提醒你喝水~`
+
+---
+
+## 备用方案（直接使用 `cron` 工具）
+
+> 仅当 `qqbot_remind` 工具不可用时使用以下方式。
+
+### 核心规则
 
 > **payload.kind 必须是 `"agentTurn"`，绝对不能用 `"systemEvent"`！**
 > `systemEvent` 只在 AI 会话内部注入文本，用户收不到 QQ 消息。
@@ -32,10 +62,6 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 > `schedule.atMs` 必须是**绝对毫秒时间戳**（如 `1770733800000`），不支持 `"5m"` 等相对字符串。
 > 计算方式：`当前时间戳ms + 延迟毫秒`。
 
----
-
-## 参数模板
-
 ### 一次性提醒（schedule.kind = "at"）
 
 ```json
@@ -98,20 +124,14 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 
 ---
 
-## 查询与删除
-
-- **查询**：`{ "action": "list" }`
-- **删除**：先 `list` 找到 jobId，再 `{ "action": "remove", "jobId": "{id}" }`
-- **修改**：删除后重建
-
----
-
 ## AI 决策指南
 
-| 用户说法 | action | schedule.kind |
-|----------|--------|---------------|
-| "5分钟后提醒我喝水" | `add` | `at` |
-| "每天8点提醒我打卡" | `add` | `cron` |
+| 用户说法 | action | time 格式 |
+|----------|--------|-----------|
+| "5分钟后提醒我喝水" | `add` | `"5m"` |
+| "1小时后提醒开会" | `add` | `"1h"` |
+| "每天8点提醒我打卡" | `add` | `"0 8 * * *"` |
+| "工作日早上9点提醒" | `add` | `"0 9 * * 1-5"` |
 | "我有哪些提醒" | `list` | — |
 | "取消喝水提醒" | `remove` | — |
 | "修改提醒时间" | `remove` → `add` | — |

package/src/channel.ts

@@ -13,6 +13,7 @@ import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
+import { initApiConfig } from "./api.js";
 
 /** QQ Bot 单条消息文本长度上限 */
 export const TEXT_CHUNK_LIMIT = 5000;
@@ -222,6 +223,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
       console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
       console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
       const account = resolveQQBotAccount(cfg, accountId);
+      initApiConfig({ markdownSupport: account.markdownSupport });
       console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
       const result = await sendText({ to, text, accountId, replyToId, account });
       console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
@@ -234,6 +236,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
     sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
       console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
       const account = resolveQQBotAccount(cfg, accountId);
+      initApiConfig({ markdownSupport: account.markdownSupport });
       console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
       const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
       console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);

package/src/gateway.ts

@@ -9,13 +9,13 @@ import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex, type RefAttachmentSummary } from "./ref-index-store.js";
 import { matchSlashCommand, getPluginVersion, type SlashCommandContext, type SlashCommandFileResult, type QueueSnapshot } from "./slash-commands.js";
 import { triggerUpdateCheck } from "./update-checker.js";
-import { startImageServer, isImageServerRunning, downloadFile, type ImageServerConfig } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize, DEFAULT_IMAGE_SIZE } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload, type CronReminderPayload, type MediaPayload } from "./utils/payload.js";
 import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig, textToSilk } from "./utils/audio-convert.js";
+import { startImageServer, isImageServerRunning, type ImageServerConfig } from "./image-server.js";
 import { normalizeMediaTags } from "./utils/media-tags.js";
-import { checkFileSize, readFileAsync, fileExistsAsync, isLargeFile, formatFileSize } from "./utils/file-utils.js";
-import { getQQBotDataDir, isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
+import { checkFileSize, readFileAsync, fileExistsAsync, isLargeFile, formatFileSize, downloadFile } from "./utils/file-utils.js";
+import { getQQBotDataDir, getQQBotMediaDir, isLocalPath as isLocalFilePath, looksLikeLocalPath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
 
 import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, type MediaTargetContext } from "./outbound.js";
 import { chunkText, TEXT_CHUNK_LIMIT } from "./channel.js";
@@ -748,6 +748,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   };
 
   // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
+  // 紧急命令列表：这些命令会立即执行，不进入斜杠匹配流程
+  const URGENT_COMMANDS = ["/stop"];
+
   const trySlashCommandOrEnqueue = async (msg: QueuedMessage): Promise<void> => {
     const content = (msg.content ?? "").trim();
     if (!content.startsWith("/")) {
@@ -755,6 +758,27 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
       return;
     }
 
+    // 检测是否为紧急命令 — 立即执行，清空该用户队列
+    const contentLower = content.toLowerCase();
+    const isUrgentCommand = URGENT_COMMANDS.some(cmd => contentLower.startsWith(cmd.toLowerCase()));
+    if (isUrgentCommand) {
+      log?.info(`[qqbot:${account.accountId}] Urgent command detected: ${content.slice(0, 20)}, executing immediately`);
+      const peerId = getMessagePeerId(msg);
+      const queue = userQueues.get(peerId);
+      if (queue) {
+        const droppedCount = queue.length;
+        queue.length = 0;
+        totalEnqueued = Math.max(0, totalEnqueued - droppedCount);
+        log?.info(`[qqbot:${account.accountId}] Dropped ${droppedCount} queued messages for ${peerId} due to urgent command`);
+      }
+      if (handleMessageFnRef) {
+        handleMessageFnRef(msg).catch(err => {
+          log?.error(`[qqbot:${account.accountId}] Urgent command error: ${err}`);
+        });
+      }
+      return;
+    }
+
     const receivedAt = Date.now();
     const peerId = getMessagePeerId(msg);
 
@@ -988,7 +1012,7 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(cfg);
 
         // 组装消息体
-        // 静态系统提示已移至 skills/qqbot-cron/SKILL.md 和 skills/qqbot-media/SKILL.md
+        // 静态系统提示已移至 skills/qqbot-remind/SKILL.md 和 skills/qqbot-media/SKILL.md
         // BodyForAgent 只保留必要的动态上下文信息
         
         // ============ 用户标识信息 ============

package/src/slash-commands.ts

@@ -433,30 +433,57 @@ function switchPluginSourceToNpm(): void {
       const cfgPath = path.join(homeDir, `.${cli}`, `${cli}.json`);
       if (!fs.existsSync(cfgPath)) continue;
 
-      // 读取当前配置
+      // 读取当前配置（保留原始文本用于回退）
       const raw = fs.readFileSync(cfgPath, "utf8");
-      const cfg = JSON.parse(raw);
+
+      let cfg: any;
+      try {
+        cfg = JSON.parse(raw);
+      } catch {
+        // 配置文件已经是损坏的 JSON，不要继续操作以免加剧问题
+        break;
+      }
+
       const inst = cfg?.plugins?.installs?.["openclaw-qqbot"];
       if (!inst || inst.source === "npm") {
         break; // 无需修改
       }
 
-      // 记录修改前的 channels.qqbot 快照，用于写后校验
-      const channelsBefore = JSON.stringify(cfg.channels?.qqbot ?? null);
+      // 记录修改前的完整快照，用于写后校验
+      const channelsBefore = JSON.stringify(cfg.channels ?? null);
 
       inst.source = "npm";
       delete inst.sourcePath;
       const newRaw = JSON.stringify(cfg, null, 4) + "\n";
 
-      // 写后校验：重新解析确认 channels.qqbot 未被破坏
-      const verify = JSON.parse(newRaw);
-      const channelsAfter = JSON.stringify(verify.channels?.qqbot ?? null);
+      // 写后校验：重新解析确认整个 JSON 合法且 channels 未被破坏
+      let verify: any;
+      try {
+        verify = JSON.parse(newRaw);
+      } catch {
+        // stringify 后竟然无法 parse（理论上不会），放弃写入
+        break;
+      }
+      const channelsAfter = JSON.stringify(verify.channels ?? null);
       if (channelsBefore !== channelsAfter) {
         // channels 数据异常，放弃写入
         break;
       }
 
-      fs.writeFileSync(cfgPath, newRaw);
+      // 原子写入：先写临时文件，再 rename 替换，避免写入中途崩溃导致配置文件损坏
+      const tmpPath = cfgPath + ".qqbot-upgrade.tmp";
+      fs.writeFileSync(tmpPath, newRaw, { mode: 0o644 });
+
+      // 再次校验临时文件的完整性
+      try {
+        JSON.parse(fs.readFileSync(tmpPath, "utf8"));
+      } catch {
+        // 写入的临时文件不完整，清理后放弃
+        try { fs.unlinkSync(tmpPath); } catch {}
+        break;
+      }
+
+      fs.renameSync(tmpPath, cfgPath);
       break;
     }
   } catch {

package/src/tools/remind.ts

@@ -0,0 +1,296 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+// ========== 类型定义 ==========
+
+interface RemindParams {
+  action: "add" | "list" | "remove";
+  /** 提醒内容（action=add 时必填） */
+  content?: string;
+  /** 目标地址，格式为上下文中的 to= 值（action=add 时必填） */
+  to?: string;
+  /**
+   * 时间描述（action=add 时必填）
+   * - 一次性：相对时间如 "5m"、"1h30m"、"2h"，或绝对毫秒时间戳
+   * - 周期性：cron 表达式如 "0 8 * * *"
+   */
+  time?: string;
+  /** 时区（周期提醒时使用，默认 Asia/Shanghai） */
+  timezone?: string;
+  /** 提醒名称（可选，默认自动生成） */
+  name?: string;
+  /** jobId（action=remove 时必填） */
+  jobId?: string;
+}
+
+// ========== JSON Schema ==========
+
+const RemindSchema = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      description:
+        "操作类型。add=创建提醒, list=查看已有提醒, remove=删除提醒",
+      enum: ["add", "list", "remove"],
+    },
+    content: {
+      type: "string",
+      description: '提醒内容，如"喝水"、"开会"。action=add 时必填。',
+    },
+    to: {
+      type: "string",
+      description:
+        "投递目标地址，取自上下文中 [QQBot] to= 的值。" +
+        "私聊格式：user_openid，群聊格式：group:group_openid。action=add 时必填。",
+    },
+    time: {
+      type: "string",
+      description:
+        "时间描述。支持两种格式：\n" +
+        "1. 相对时间：如 \"5m\"(5分钟后)、\"1h\"(1小时后)、\"1h30m\"(1.5小时后)、\"2d\"(2天后)\n" +
+        "2. cron 表达式：如 \"0 8 * * *\"(每天8点)、\"0 9 * * 1-5\"(工作日9点)\n" +
+        "系统会自动判断：包含空格的视为 cron 表达式（周期提醒），否则视为相对时间（一次性提醒）。\n" +
+        "action=add 时必填。",
+    },
+    timezone: {
+      type: "string",
+      description:
+        "时区，仅周期提醒(cron)时需要。默认 \"Asia/Shanghai\"。",
+    },
+    name: {
+      type: "string",
+      description: "提醒任务名称（可选）。默认自动从 content 截取前 20 字。",
+    },
+    jobId: {
+      type: "string",
+      description: "要删除的任务 ID。action=remove 时必填，先用 list 获取。",
+    },
+  },
+  required: ["action"],
+} as const;
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+/**
+ * 解析相对时间字符串为毫秒数
+ * 支持格式：5m, 1h, 1h30m, 2d, 30s, 1d2h30m 等
+ */
+function parseRelativeTime(timeStr: string): number | null {
+  const s = timeStr.trim().toLowerCase();
+
+  // 纯数字 → 视为分钟
+  if (/^\d+$/.test(s)) {
+    return parseInt(s, 10) * 60_000;
+  }
+
+  let totalMs = 0;
+  let matched = false;
+  const regex = /(\d+(?:\.\d+)?)\s*(d|h|m|s)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(s)) !== null) {
+    matched = true;
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    switch (unit) {
+      case "d": totalMs += value * 86_400_000; break;
+      case "h": totalMs += value * 3_600_000; break;
+      case "m": totalMs += value * 60_000; break;
+      case "s": totalMs += value * 1_000; break;
+    }
+  }
+
+  return matched ? Math.round(totalMs) : null;
+}
+
+/**
+ * 判断是否为 cron 表达式（包含空格且有 3~6 段）
+ */
+function isCronExpression(timeStr: string): boolean {
+  const parts = timeStr.trim().split(/\s+/);
+  return parts.length >= 3 && parts.length <= 6;
+}
+
+/**
+ * 自动生成任务名称
+ */
+function generateJobName(content: string): string {
+  const trimmed = content.trim();
+  const short = trimmed.length > 20 ? trimmed.slice(0, 20) + "…" : trimmed;
+  return `提醒: ${short}`;
+}
+
+/**
+ * 构建一次性提醒的 cron 工具参数
+ */
+function buildOnceJob(params: RemindParams, delayMs: number) {
+  const atMs = Date.now() + delayMs;
+  const to = params.to!;
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+
+  return {
+    action: "add",
+    job: {
+      name,
+      schedule: { kind: "at", atMs },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      deleteAfterRun: true,
+      payload: {
+        kind: "agentTurn",
+        message: buildReminderPrompt(content),
+        deliver: true,
+        channel: "qqbot",
+        to,
+      },
+    },
+  };
+}
+
+/**
+ * 构建周期提醒的 cron 工具参数
+ */
+function buildCronJob(params: RemindParams) {
+  const to = params.to!;
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+  const tz = params.timezone || "Asia/Shanghai";
+
+  return {
+    action: "add",
+    job: {
+      name,
+      schedule: { kind: "cron", expr: params.time!.trim(), tz },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      payload: {
+        kind: "agentTurn",
+        message: buildReminderPrompt(content),
+        deliver: true,
+        channel: "qqbot",
+        to,
+      },
+    },
+  };
+}
+
+/**
+ * 构建提醒 payload 中的 AI prompt
+ */
+function buildReminderPrompt(content: string): string {
+  return (
+    `你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：${content}。` +
+    `要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 ` +
+    `(3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 ` +
+    `(5) 控制在2-3句话以内 (6) 用emoji点缀`
+  );
+}
+
+/**
+ * 格式化延迟时间为人类可读文本
+ */
+function formatDelay(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}秒`;
+  const totalMinutes = Math.round(ms / 60_000);
+  if (totalMinutes < 60) return `${totalMinutes}分钟`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (minutes === 0) return `${hours}小时`;
+  return `${hours}小时${minutes}分钟`;
+}
+
+// ========== 注册入口 ==========
+
+export function registerRemindTool(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "qqbot_remind",
+      label: "QQBot 定时提醒",
+      description:
+        "创建、查询、删除 QQ 定时提醒。" +
+        "使用简单参数即可，无需手动构造 cron JSON。\n" +
+        "创建提醒：action=add, content=提醒内容, to=目标地址, time=时间\n" +
+        "查看提醒：action=list\n" +
+        "删除提醒：action=remove, jobId=任务ID（先 list 获取）\n" +
+        "时间格式示例：\"5m\"(5分钟后) \"1h\"(1小时后) \"0 8 * * *\"(每天8点)",
+      parameters: RemindSchema,
+      execute(_toolCallId, params) {
+        const p = params as RemindParams;
+
+        // ===== list =====
+        if (p.action === "list") {
+          return json({
+            _instruction: "请立即使用 cron 工具执行以下参数",
+            cronParams: { action: "list" },
+          });
+        }
+
+        // ===== remove =====
+        if (p.action === "remove") {
+          if (!p.jobId) {
+            return json({ error: "action=remove 时 jobId 为必填参数。请先用 action=list 获取 jobId。" });
+          }
+          return json({
+            _instruction: "请立即使用 cron 工具执行以下参数",
+            cronParams: { action: "remove", jobId: p.jobId },
+          });
+        }
+
+        // ===== add =====
+        if (!p.content) {
+          return json({ error: "action=add 时 content（提醒内容）为必填参数" });
+        }
+        if (!p.to) {
+          return json({ error: "action=add 时 to（目标地址）为必填参数，取自上下文 [QQBot] to= 的值" });
+        }
+        if (!p.time) {
+          return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
+        }
+
+        // 判断是 cron 表达式还是相对时间
+        if (isCronExpression(p.time)) {
+          // 周期提醒
+          const cronJob = buildCronJob(p);
+          return json({
+            _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
+            cronParams: cronJob,
+            summary: `⏰ 周期提醒: "${p.content}" (${p.time}, tz=${p.timezone || "Asia/Shanghai"})`,
+          });
+        }
+
+        // 一次性提醒
+        const delayMs = parseRelativeTime(p.time);
+        if (!delayMs || delayMs <= 0) {
+          return json({
+            error: `无法解析时间 "${p.time}"。支持格式：` +
+              `相对时间如 "5m"、"1h"、"1h30m"、"2d"；` +
+              `cron 表达式如 "0 8 * * *"（每天8点）`,
+          });
+        }
+
+        if (delayMs < 30_000) {
+          return json({ error: "提醒时间不能少于 30 秒" });
+        }
+
+        const onceJob = buildOnceJob(p, delayMs);
+        return json({
+          _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
+          cronParams: onceJob,
+          summary: `⏰ ${formatDelay(delayMs)}后提醒: "${p.content}"`,
+        });
+      },
+    },
+    { name: "qqbot_remind" },
+  );
+
+  console.log("[qqbot-remind] Registered QQBot remind tool");
+}

package/src/utils/file-utils.ts

@@ -4,6 +4,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import crypto from "node:crypto";
 
 /** QQ Bot API 最大上传文件大小：20MB */
 export const MAX_UPLOAD_SIZE = 20 * 1024 * 1024;
@@ -120,3 +121,47 @@ export function getMimeType(filePath: string): string {
   };
   return mimeTypes[ext] ?? "application/octet-stream";
 }
+
+/**
+ * 将远端文件下载到本地目录。
+ *
+ * @param url 远端 URL
+ * @param destDir 目标目录（不存在时自动创建）
+ * @param originalFilename 可选的原始文件名（覆盖 URL 推断）
+ * @returns 本地文件完整路径；下载失败返回 null
+ */
+export async function downloadFile(url: string, destDir: string, originalFilename?: string): Promise<string | null> {
+  try {
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    const resp = await fetch(url, { redirect: "follow" });
+    if (!resp.ok || !resp.body) return null;
+
+    // 确定文件名：优先使用 originalFilename，否则从 URL 推断
+    let filename = originalFilename?.trim() || "";
+    if (!filename) {
+      try {
+        const urlPath = new URL(url).pathname;
+        filename = path.basename(urlPath) || "download";
+      } catch {
+        filename = "download";
+      }
+    }
+
+    // 加上时间戳避免同名冲突
+    const ts = Date.now();
+    const ext = path.extname(filename);
+    const base = path.basename(filename, ext) || "file";
+    const rand = crypto.randomBytes(3).toString("hex");
+    const safeFilename = `${base}_${ts}_${rand}${ext}`;
+
+    const destPath = path.join(destDir, safeFilename);
+    const buffer = Buffer.from(await resp.arrayBuffer());
+    await fs.promises.writeFile(destPath, buffer);
+    return destPath;
+  } catch {
+    return null;
+  }
+}

package/src/utils/platform.ts

@@ -68,6 +68,23 @@ export function getQQBotDataDir(...subPaths: string[]): string {
   return dir;
 }
 
+/**
+ * 获取 .openclaw/media/qqbot 下的子目录路径，并自动创建
+ *
+ * 与 getQQBotDataDir 不同，此目录位于 OpenClaw 核心的媒体安全白名单
+ * (~/.openclaw/media) 之下，下载到这里的文件可以被框架的 image/media
+ * 工具直接访问，不会触发 "Local media path is not under an allowed directory" 错误。
+ *
+ * 用于存放从 QQ 下载的图片、语音等需要被框架处理的媒体文件。
+ */
+export function getQQBotMediaDir(...subPaths: string[]): string {
+  const dir = path.join(getHomeDir(), ".openclaw", "media", "qqbot", ...subPaths);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
 // ============ 临时目录 ============
 
 /**