@leoqlin/openclaw-qqbot 1.6.7-alpha1

package/dist/src/stt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 通用 OpenAI 兼容 STT（语音转文字）
+ *
+ * 为什么在插件侧做 STT 而不走框架管道？
+ * 框架的 applyMediaUnderstanding 同时执行 runCapability("audio") 和 extractFileBlocks。
+ * 后者会把 WAV 文件的 PCM 二进制当文本注入 Body（looksLikeUtf8Text 误判），导致 context 爆炸。
+ * 在插件侧完成 STT 后不把 WAV 放入 MediaPaths，即可规避此框架 bug。
+ *
+ * 配置解析策略（与 TTS 统一的两级回退）：
+ * 1. 优先 channels.qqbot.stt（插件专属配置）
+ * 2. 回退 tools.media.audio.models[0]（框架级配置）
+ * 3. 再从 models.providers.[provider] 继承 apiKey/baseUrl
+ * 4. 支持任何 OpenAI 兼容的 STT 服务
+ */
+export interface STTConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}
+export declare function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null;
+export declare function transcribeAudio(audioPath: string, cfg: Record<string, unknown>): Promise<string | null>;

package/dist/src/stt.js

@@ -0,0 +1,70 @@
+/**
+ * 通用 OpenAI 兼容 STT（语音转文字）
+ *
+ * 为什么在插件侧做 STT 而不走框架管道？
+ * 框架的 applyMediaUnderstanding 同时执行 runCapability("audio") 和 extractFileBlocks。
+ * 后者会把 WAV 文件的 PCM 二进制当文本注入 Body（looksLikeUtf8Text 误判），导致 context 爆炸。
+ * 在插件侧完成 STT 后不把 WAV 放入 MediaPaths，即可规避此框架 bug。
+ *
+ * 配置解析策略（与 TTS 统一的两级回退）：
+ * 1. 优先 channels.qqbot.stt（插件专属配置）
+ * 2. 回退 tools.media.audio.models[0]（框架级配置）
+ * 3. 再从 models.providers.[provider] 继承 apiKey/baseUrl
+ * 4. 支持任何 OpenAI 兼容的 STT 服务
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { sanitizeFileName } from "./utils/platform.js";
+export function resolveSTTConfig(cfg) {
+    const c = cfg;
+    // 优先使用 channels.qqbot.stt（插件专属配置）
+    const channelStt = c?.channels?.qqbot?.stt;
+    if (channelStt && channelStt.enabled !== false) {
+        const providerId = channelStt?.provider || "openai";
+        const providerCfg = c?.models?.providers?.[providerId];
+        const baseUrl = channelStt?.baseUrl || providerCfg?.baseUrl;
+        const apiKey = channelStt?.apiKey || providerCfg?.apiKey;
+        const model = channelStt?.model || "whisper-1";
+        if (baseUrl && apiKey) {
+            return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
+        }
+    }
+    // 回退到 tools.media.audio.models[0]（框架级配置）
+    const audioModelEntry = c?.tools?.media?.audio?.models?.[0];
+    if (audioModelEntry) {
+        const providerId = audioModelEntry?.provider || "openai";
+        const providerCfg = c?.models?.providers?.[providerId];
+        const baseUrl = audioModelEntry?.baseUrl || providerCfg?.baseUrl;
+        const apiKey = audioModelEntry?.apiKey || providerCfg?.apiKey;
+        const model = audioModelEntry?.model || "whisper-1";
+        if (baseUrl && apiKey) {
+            return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
+        }
+    }
+    return null;
+}
+export async function transcribeAudio(audioPath, cfg) {
+    const sttCfg = resolveSTTConfig(cfg);
+    if (!sttCfg)
+        return null;
+    const fileBuffer = fs.readFileSync(audioPath);
+    const fileName = sanitizeFileName(path.basename(audioPath));
+    const mime = fileName.endsWith(".wav") ? "audio/wav"
+        : fileName.endsWith(".mp3") ? "audio/mpeg"
+            : fileName.endsWith(".ogg") ? "audio/ogg"
+                : "application/octet-stream";
+    const form = new FormData();
+    form.append("file", new Blob([fileBuffer], { type: mime }), fileName);
+    form.append("model", sttCfg.model);
+    const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
+        method: "POST",
+        headers: { "Authorization": `Bearer ${sttCfg.apiKey}` },
+        body: form,
+    });
+    if (!resp.ok) {
+        const detail = await resp.text().catch(() => "");
+        throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
+    }
+    const result = await resp.json();
+    return result.text?.trim() || null;
+}

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

@@ -0,0 +1,16 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+/**
+ * 注册 QQ 频道 API 代理工具。
+ *
+ * 该工具作为 QQ 开放平台频道 API 的 HTTP 代理，自动处理 Token 鉴权。
+ * AI 通过 skill 文档了解各接口的路径、方法和参数，构造请求后由此工具代理发送。
+ *
+ * 支持的能力：
+ * - 频道管理（Guild）
+ * - 子频道管理（Channel）
+ * - 成员管理（Member）
+ * - 公告管理（Announces）
+ * - 论坛管理（Forum Thread）
+ * - 日程管理（Schedule）
+ */
+export declare function registerChannelTool(api: OpenClawPluginApi): void;

package/dist/src/tools/channel.js

@@ -0,0 +1,234 @@
+import { resolveQQBotAccount } from "../config.js";
+import { listQQBotAccountIds } from "../config.js";
+import { getAccessToken } from "../api.js";
+// ========== 常量 ==========
+const API_BASE = "https://api.sgroup.qq.com";
+const DEFAULT_TIMEOUT_MS = 30000;
+// ========== JSON Schema ==========
+const ChannelApiSchema = {
+    type: "object",
+    properties: {
+        method: {
+            type: "string",
+            description: "HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE",
+            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+        },
+        path: {
+            type: "string",
+            description: "API 路径（不含域名），占位符需替换为实际值。" +
+                "示例：/users/@me/guilds, /guilds/{guild_id}/channels, /channels/{channel_id}",
+        },
+        body: {
+            type: "object",
+            description: "请求体（JSON），用于 POST/PUT/PATCH 请求。" +
+                "GET/DELETE 请求不需要此参数。",
+        },
+        query: {
+            type: "object",
+            description: "URL 查询参数（键值对），会拼接到路径后面。" +
+                "如 { \"limit\": \"100\", \"after\": \"0\" } 会拼接为 ?limit=100&after=0",
+            additionalProperties: { type: "string" },
+        },
+    },
+    required: ["method", "path"],
+};
+// ========== 工具函数 ==========
+function json(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}
+/**
+ * 构建完整的请求 URL
+ */
+function buildUrl(path, query) {
+    let url = `${API_BASE}${path}`;
+    if (query && Object.keys(query).length > 0) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null && value !== "") {
+                params.set(key, value);
+            }
+        }
+        const qs = params.toString();
+        if (qs) {
+            url += `?${qs}`;
+        }
+    }
+    return url;
+}
+/**
+ * 校验 path 防止 SSRF
+ */
+function validatePath(path) {
+    if (!path.startsWith("/")) {
+        return "path 必须以 / 开头";
+    }
+    if (path.includes("..") || path.includes("//")) {
+        return "path 不允许包含 .. 或 //";
+    }
+    // 只允许合法的 URL path 字符
+    if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") {
+        return "path 包含非法字符";
+    }
+    return null;
+}
+// ========== 注册入口 ==========
+/**
+ * 注册 QQ 频道 API 代理工具。
+ *
+ * 该工具作为 QQ 开放平台频道 API 的 HTTP 代理，自动处理 Token 鉴权。
+ * AI 通过 skill 文档了解各接口的路径、方法和参数，构造请求后由此工具代理发送。
+ *
+ * 支持的能力：
+ * - 频道管理（Guild）
+ * - 子频道管理（Channel）
+ * - 成员管理（Member）
+ * - 公告管理（Announces）
+ * - 论坛管理（Forum Thread）
+ * - 日程管理（Schedule）
+ */
+export function registerChannelTool(api) {
+    const cfg = api.config;
+    if (!cfg) {
+        console.log("[qqbot-channel-api] No config available, skipping");
+        return;
+    }
+    const accountIds = listQQBotAccountIds(cfg);
+    if (accountIds.length === 0) {
+        console.log("[qqbot-channel-api] No QQBot accounts configured, skipping");
+        return;
+    }
+    const firstAccountId = accountIds[0];
+    const account = resolveQQBotAccount(cfg, firstAccountId);
+    if (!account.appId || !account.clientSecret) {
+        console.log("[qqbot-channel-api] Account not fully configured, skipping");
+        return;
+    }
+    api.registerTool({
+        name: "qqbot_channel_api",
+        label: "QQBot Channel API",
+        description: "QQ 开放平台频道 API HTTP 代理，自动填充鉴权 Token。" +
+            "常用接口速查：" +
+            "频道列表 GET /users/@me/guilds | " +
+            "子频道列表 GET /guilds/{guild_id}/channels | " +
+            "子频道详情 GET /channels/{channel_id} | " +
+            "创建子频道 POST /guilds/{guild_id}/channels | " +
+            "成员列表 GET /guilds/{guild_id}/members?after=0&limit=100 | " +
+            "成员详情 GET /guilds/{guild_id}/members/{user_id} | " +
+            "帖子列表 GET /channels/{channel_id}/threads | " +
+            "发帖 PUT /channels/{channel_id}/threads | " +
+            "创建公告 POST /guilds/{guild_id}/announces | " +
+            "创建日程 POST /channels/{channel_id}/schedules。" +
+            "更多接口和参数详情请阅读 qqbot-channel skill。",
+        parameters: ChannelApiSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            // 参数校验
+            if (!p.method) {
+                return json({ error: "method 为必填参数" });
+            }
+            if (!p.path) {
+                return json({ error: "path 为必填参数" });
+            }
+            const method = p.method.toUpperCase();
+            if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+                return json({ error: `不支持的 HTTP 方法: ${method}，可选值：GET, POST, PUT, PATCH, DELETE` });
+            }
+            // 路径安全校验
+            const pathError = validatePath(p.path);
+            if (pathError) {
+                return json({ error: pathError });
+            }
+            // GET/DELETE 不应有 body
+            if ((method === "GET" || method === "DELETE") && p.body && Object.keys(p.body).length > 0) {
+                console.log(`[qqbot-channel-api] ${method} request with body, body will be ignored`);
+            }
+            try {
+                // 获取鉴权 Token
+                const accessToken = await getAccessToken(account.appId, account.clientSecret);
+                // 构建请求
+                const url = buildUrl(p.path, p.query);
+                const headers = {
+                    Authorization: `QQBot ${accessToken}`,
+                    "Content-Type": "application/json",
+                };
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+                const fetchOptions = {
+                    method,
+                    headers,
+                    signal: controller.signal,
+                };
+                // POST/PUT/PATCH 才发送 body
+                if (p.body && ["POST", "PUT", "PATCH"].includes(method)) {
+                    fetchOptions.body = JSON.stringify(p.body);
+                }
+                console.log(`[qqbot-channel-api] >>> ${method} ${url} (timeout: ${DEFAULT_TIMEOUT_MS}ms)`);
+                let res;
+                try {
+                    res = await fetch(url, fetchOptions);
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    if (err instanceof Error && err.name === "AbortError") {
+                        console.error(`[qqbot-channel-api] <<< Request timeout after ${DEFAULT_TIMEOUT_MS}ms`);
+                        return json({ error: `请求超时（${DEFAULT_TIMEOUT_MS}ms）`, path: p.path });
+                    }
+                    console.error(`[qqbot-channel-api] <<< Network error:`, err);
+                    return json({
+                        error: `网络错误: ${err instanceof Error ? err.message : String(err)}`,
+                        path: p.path,
+                    });
+                }
+                finally {
+                    clearTimeout(timeoutId);
+                }
+                console.log(`[qqbot-channel-api] <<< Status: ${res.status} ${res.statusText}`);
+                // 解析响应
+                const rawBody = await res.text();
+                // 空响应（如 DELETE 204）
+                if (!rawBody || rawBody.trim() === "") {
+                    if (res.ok) {
+                        return json({ success: true, status: res.status, path: p.path });
+                    }
+                    return json({
+                        error: `API 返回 ${res.status} ${res.statusText}`,
+                        status: res.status,
+                        path: p.path,
+                    });
+                }
+                let data;
+                try {
+                    data = JSON.parse(rawBody);
+                }
+                catch {
+                    return json({
+                        error: "响应解析失败",
+                        status: res.status,
+                        raw: rawBody.slice(0, 500),
+                        path: p.path,
+                    });
+                }
+                if (!res.ok) {
+                    const errData = data;
+                    return json({
+                        error: errData.message ?? `API 错误 (HTTP ${res.status})`,
+                        code: errData.code,
+                        status: res.status,
+                        path: p.path,
+                        detail: data,
+                    });
+                }
+                return json(data);
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                console.error(`[qqbot-channel-api] Error [${method} ${p.path}]: ${errMsg}`);
+                return json({ error: errMsg, path: p.path });
+            }
+        },
+    }, { name: "qqbot_channel_api" });
+    console.log("[qqbot-channel-api] Registered QQ channel API proxy tool");
+}

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,256 @@
+import { getRequestTarget, getRequestAccountId } from "../request-context.js";
+// ========== 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:c2c:user_openid，群聊格式：qqbot:group:group_openid。",
+        },
+        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, to, accountId) {
+    const atMs = Date.now() + delayMs;
+    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),
+            },
+            delivery: {
+                mode: "announce",
+                channel: "qqbot",
+                to,
+                accountId,
+            },
+        },
+    };
+}
+/**
+ * 构建周期提醒的 cron 工具参数
+ */
+function buildCronJob(params, to, accountId) {
+    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),
+            },
+            delivery: {
+                mode: "announce",
+                channel: "qqbot",
+                to,
+                accountId,
+            },
+        },
+    };
+}
+/**
+ * 构建提醒 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（提醒内容）为必填参数" });
+            }
+            // 优先使用 AI 传入的 to，否则自动从请求级上下文获取（AsyncLocalStorage）
+            const resolvedTo = p.to || getRequestTarget();
+            if (!resolvedTo) {
+                return json({ error: "action=add 时无法确定投递目标地址。请稍后重试。" });
+            }
+            // 从请求上下文获取当前账户 ID（多账户场景），fallback 到 "default"
+            const resolvedAccountId = getRequestAccountId() || "default";
+            if (!p.time) {
+                return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
+            }
+            // 判断是 cron 表达式还是相对时间
+            if (isCronExpression(p.time)) {
+                // 周期提醒
+                const cronJob = buildCronJob(p, resolvedTo, resolvedAccountId);
+                return json({
+                    _instruction: "请立即使用 cron 工具，将 cronParams 的值原样作为参数传入（不要修改或省略任何字段，特别是 delivery.accountId），然后回复用户提醒已设置",
+                    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, resolvedTo, resolvedAccountId);
+            return json({
+                _instruction: "请立即使用 cron 工具，将 cronParams 的值原样作为参数传入（不要修改或省略任何字段，特别是 delivery.accountId），然后回复用户提醒已设置",
+                cronParams: onceJob,
+                summary: `⏰ ${formatDelay(delayMs)}后提醒: "${p.content}"`,
+            });
+        },
+    }, { name: "qqbot_remind" });
+    console.log("[qqbot-remind] Registered QQBot remind tool");
+}