@ryantest/openclaw-qqbot 0.0.1

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/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * QQ Bot 配置类型
+ */
+export interface QQBotConfig {
+    appId: string;
+    clientSecret?: string;
+    clientSecretFile?: string;
+}
+/**
+ * 解析后的 QQ Bot 账户
+ */
+export interface ResolvedQQBotAccount {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    appId: string;
+    clientSecret: string;
+    secretSource: "config" | "file" | "env" | "none";
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 图床服务器公网地址 */
+    imageServerBaseUrl?: string;
+    /** 是否支持 markdown 消息（默认 true） */
+    markdownSupport: boolean;
+    config: QQBotAccountConfig;
+}
+/**
+ * QQ Bot 账户配置
+ */
+export interface QQBotAccountConfig {
+    enabled?: boolean;
+    name?: string;
+    appId?: string;
+    clientSecret?: string;
+    clientSecretFile?: string;
+    dmPolicy?: "open" | "pairing" | "allowlist";
+    allowFrom?: string[];
+    /** 系统提示词，会添加在用户消息前面 */
+    systemPrompt?: string;
+    /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
+    imageServerBaseUrl?: string;
+    /** 是否支持 markdown 消息（默认 true，设为 false 可禁用） */
+    markdownSupport?: boolean;
+    /**
+     * @deprecated 请使用 audioFormatPolicy.uploadDirectFormats
+     * 可直接上传的音频格式（不转换为 SILK），向后兼容
+     */
+    voiceDirectUploadFormats?: string[];
+    /**
+     * 音频格式策略配置
+     * 统一管理入站（STT）和出站（上传）的音频格式转换行为
+     */
+    audioFormatPolicy?: AudioFormatPolicy;
+    /**
+     * 是否启用公网 URL 直传 QQ 平台（默认 true）
+     * 启用时：公网 URL 先直传给 QQ 开放平台的富媒体 API，平台自行拉取；失败后自动 fallback 到插件下载再 Base64 上传
+     * 禁用时：公网 URL 始终由插件先下载到本地，再以 Base64 上传（适用于 QQ 平台无法访问目标 URL 的场景）
+     */
+    urlDirectUpload?: boolean;
+    /**
+     * /bot-upgrade 指令返回的升级指引网址
+     * 默认: https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg
+     */
+    upgradeUrl?: string;
+    /**
+     * /bot-upgrade 指令的行为模式
+     * - "doc"：展示升级文档链接（默认，安全模式）
+     * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
+     */
+    upgradeMode?: "doc" | "hot-reload";
+}
+/**
+ * 音频格式策略：控制哪些格式可跳过转换
+ */
+export interface AudioFormatPolicy {
+    /**
+     * STT 模型直接支持的音频格式（入站：跳过 SILK→WAV 转换）
+     * 如果 STT 服务支持直接处理某些格式（如 silk/amr），可将其加入此列表
+     * 例如: [".silk", ".amr", ".wav", ".mp3", ".ogg"]
+     * 默认为空（所有语音都先转换为 WAV 再送 STT）
+     */
+    sttDirectFormats?: string[];
+    /**
+     * QQ 平台支持直传的音频格式（出站：跳过→SILK 转换）
+     * 默认为 [".wav", ".mp3", ".silk"]（QQ Bot API 原生支持的三种格式）
+     * 仅当需要覆盖默认值时才配置此项
+     */
+    uploadDirectFormats?: string[];
+    /**
+     * 是否启用语音转码（默认 true）
+     * 设为 false 可在环境无 ffmpeg 时跳过转码，直接以文件形式发送
+     * 当禁用时，非原生格式的音频会 fallback 到 sendDocument（文件发送）
+     */
+    transcodeEnabled?: boolean;
+}
+/**
+ * 富媒体附件
+ */
+export interface MessageAttachment {
+    content_type: string;
+    filename?: string;
+    height?: number;
+    width?: number;
+    size?: number;
+    url: string;
+    voice_wav_url?: string;
+    asr_refer_text?: string;
+}
+/**
+ * C2C 消息事件
+ */
+export interface C2CMessageEvent {
+    author: {
+        id: string;
+        union_openid: string;
+        user_openid: string;
+    };
+    content: string;
+    id: string;
+    timestamp: string;
+    message_scene?: {
+        source: string;
+        /** ext 数组，可能包含 ref_msg_idx=REFIDX_xxx（引用的消息）和 msg_idx=REFIDX_xxx（自身索引） */
+        ext?: string[];
+    };
+    attachments?: MessageAttachment[];
+}
+/**
+ * 频道 AT 消息事件
+ */
+export interface GuildMessageEvent {
+    id: string;
+    channel_id: string;
+    guild_id: string;
+    content: string;
+    timestamp: string;
+    author: {
+        id: string;
+        username?: string;
+        bot?: boolean;
+    };
+    member?: {
+        nick?: string;
+        joined_at?: string;
+    };
+    attachments?: MessageAttachment[];
+}
+/**
+ * 群聊 AT 消息事件
+ */
+export interface GroupMessageEvent {
+    author: {
+        id: string;
+        member_openid: string;
+    };
+    content: string;
+    id: string;
+    timestamp: string;
+    group_id: string;
+    group_openid: string;
+    message_scene?: {
+        source: string;
+        ext?: string[];
+    };
+    attachments?: MessageAttachment[];
+}
+/**
+ * WebSocket 事件负载
+ */
+export interface WSPayload {
+    op: number;
+    d?: unknown;
+    s?: number;
+    t?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/typing-keepalive.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 输入状态自动续期
+ * 在消息处理期间定时续发 "正在输入" 状态通知，确保用户持续看到 bot 在处理中。
+ * 仅 C2C 私聊有效（QQ 群聊 API 不支持输入状态通知）。
+ */
+export declare const TYPING_INTERVAL_MS = 50000;
+export declare const TYPING_INPUT_SECOND = 60;
+export declare class TypingKeepAlive {
+    private readonly getToken;
+    private readonly clearCache;
+    private readonly openid;
+    private readonly msgId;
+    private readonly log?;
+    private readonly logPrefix;
+    private timer;
+    private stopped;
+    constructor(getToken: () => Promise<string>, clearCache: () => void, openid: string, msgId: string | undefined, log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    } | undefined, logPrefix?: string);
+    /** 启动定时续期（首次发送由调用方自行处理，这里只负责后续续期） */
+    start(): void;
+    /** 停止续期 */
+    stop(): void;
+    private send;
+}

package/dist/src/typing-keepalive.js

@@ -0,0 +1,64 @@
+/**
+ * 输入状态自动续期
+ * 在消息处理期间定时续发 "正在输入" 状态通知，确保用户持续看到 bot 在处理中。
+ * 仅 C2C 私聊有效（QQ 群聊 API 不支持输入状态通知）。
+ */
+import { sendC2CInputNotify } from "./api.js";
+// 每 50 秒续发一次（QQ API input_second=60，留 10s 余量）
+export const TYPING_INTERVAL_MS = 50_000;
+export const TYPING_INPUT_SECOND = 60;
+export class TypingKeepAlive {
+    getToken;
+    clearCache;
+    openid;
+    msgId;
+    log;
+    logPrefix;
+    timer = null;
+    stopped = false;
+    constructor(getToken, clearCache, openid, msgId, log, logPrefix = "[qqbot]") {
+        this.getToken = getToken;
+        this.clearCache = clearCache;
+        this.openid = openid;
+        this.msgId = msgId;
+        this.log = log;
+        this.logPrefix = logPrefix;
+    }
+    /** 启动定时续期（首次发送由调用方自行处理，这里只负责后续续期） */
+    start() {
+        if (this.stopped)
+            return;
+        this.timer = setInterval(() => {
+            if (this.stopped) {
+                this.stop();
+                return;
+            }
+            this.send().catch(() => { });
+        }, TYPING_INTERVAL_MS);
+    }
+    /** 停止续期 */
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    async send() {
+        try {
+            const token = await this.getToken();
+            await sendC2CInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+            this.log?.debug?.(`${this.logPrefix} Typing keep-alive sent to ${this.openid}`);
+        }
+        catch (err) {
+            try {
+                this.clearCache();
+                const token = await this.getToken();
+                await sendC2CInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+            }
+            catch {
+                this.log?.debug?.(`${this.logPrefix} Typing keep-alive failed for ${this.openid}: ${err}`);
+            }
+        }
+    }
+}

package/dist/src/update-checker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 版本检查器
+ *
+ * - triggerUpdateCheck(): gateway 启动时调用，后台预热缓存
+ * - getUpdateInfo(): 每次实时查询 npm registry，返回最新结果
+ *
+ * 使用 HTTPS 直接请求 npm registry API（不依赖 npm CLI），
+ * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
+ */
+export interface UpdateInfo {
+    current: string;
+    /** 最佳升级目标（prerelease 用户优先 alpha，稳定版用户取 latest） */
+    latest: string | null;
+    /** 稳定版 dist-tag */
+    stable: string | null;
+    /** alpha dist-tag */
+    alpha: string | null;
+    hasUpdate: boolean;
+    checkedAt: number;
+    error?: string;
+}
+/** gateway 启动时调用，保存 log 引用 */
+export declare function triggerUpdateCheck(log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+}): void;
+/** 每次实时查询 npm registry */
+export declare function getUpdateInfo(): Promise<UpdateInfo>;
+/**
+ * 检查指定版本是否存在于 npm registry
+ * 用于 /bot-upgrade --version 的前置校验
+ */
+export declare function checkVersionExists(version: string): Promise<boolean>;