@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

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

@@ -1,112 +0,0 @@
-/**
- * QQBot 结构化消息载荷工具
- *
- * 用于处理 AI 输出的结构化消息载荷，包括：
- * - 定时提醒载荷 (cron_reminder)
- * - 媒体消息载荷 (media)
- */
-/**
- * 定时提醒载荷
- */
-export interface CronReminderPayload {
-    type: 'cron_reminder';
-    /** 提醒内容 */
-    content: string;
-    /** 目标类型：c2c (私聊) 或 group (群聊) */
-    targetType: 'c2c' | 'group';
-    /** 目标地址：user_openid 或 group_openid */
-    targetAddress: string;
-    /** 原始消息 ID（可选） */
-    originalMessageId?: string;
-}
-/**
- * 媒体消息载荷
- */
-export interface MediaPayload {
-    type: 'media';
-    /** 媒体类型：image, audio, video, file */
-    mediaType: 'image' | 'audio' | 'video' | 'file';
-    /** 来源类型：url 或 file */
-    source: 'url' | 'file';
-    /** 媒体路径或 URL */
-    path: string;
-    /** 媒体描述（可选） */
-    caption?: string;
-}
-/**
- * QQBot 载荷联合类型
- */
-export type QQBotPayload = CronReminderPayload | MediaPayload;
-/**
- * 解析结果
- */
-export interface ParseResult {
-    /** 是否为结构化载荷 */
-    isPayload: boolean;
-    /** 解析后的载荷对象（如果是结构化载荷） */
-    payload?: QQBotPayload;
-    /** 原始文本（如果不是结构化载荷） */
-    text?: string;
-    /** 解析错误信息（如果解析失败） */
-    error?: string;
-}
-/**
- * 解析 AI 输出的结构化载荷
- *
- * 检测消息是否以 QQBOT_PAYLOAD: 前缀开头，如果是则提取并解析 JSON
- *
- * @param text AI 输出的原始文本
- * @returns 解析结果
- *
- * @example
- * const result = parseQQBotPayload('QQBOT_PAYLOAD:\n{"type": "media", "mediaType": "image", ...}');
- * if (result.isPayload && result.payload) {
- *   // 处理结构化载荷
- * }
- */
-export declare function parseQQBotPayload(text: string): ParseResult;
-/**
- * 将定时提醒载荷编码为 Cron 消息格式
- *
- * 将 JSON 编码为 Base64，并添加 QQBOT_CRON: 前缀
- *
- * @param payload 定时提醒载荷
- * @returns 编码后的消息字符串，格式为 QQBOT_CRON:{base64}
- *
- * @example
- * const message = encodePayloadForCron({
- *   type: 'cron_reminder',
- *   content: '喝水时间到！',
- *   targetType: 'c2c',
- *   targetAddress: 'user_openid_xxx'
- * });
- * // 返回: QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...
- */
-export declare function encodePayloadForCron(payload: CronReminderPayload): string;
-/**
- * 解码 Cron 消息中的载荷
- *
- * 检测 QQBOT_CRON: 前缀，解码 Base64 并解析 JSON
- *
- * @param message Cron 触发时收到的消息
- * @returns 解码结果，包含是否为 Cron 载荷、解析后的载荷对象或错误信息
- *
- * @example
- * const result = decodeCronPayload('QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...');
- * if (result.isCronPayload && result.payload) {
- *   // 处理定时提醒
- * }
- */
-export declare function decodeCronPayload(message: string): {
-    isCronPayload: boolean;
-    payload?: CronReminderPayload;
-    error?: string;
-};
-/**
- * 判断载荷是否为定时提醒类型
- */
-export declare function isCronReminderPayload(payload: QQBotPayload): payload is CronReminderPayload;
-/**
- * 判断载荷是否为媒体消息类型
- */
-export declare function isMediaPayload(payload: QQBotPayload): payload is MediaPayload;

package/dist/src/utils/payload.js

@@ -1,186 +0,0 @@
-/**
- * QQBot 结构化消息载荷工具
- *
- * 用于处理 AI 输出的结构化消息载荷，包括：
- * - 定时提醒载荷 (cron_reminder)
- * - 媒体消息载荷 (media)
- */
-// ============================================
-// 常量定义
-// ============================================
-/** AI 输出的结构化载荷前缀 */
-const PAYLOAD_PREFIX = 'QQBOT_PAYLOAD:';
-/** Cron 消息存储的前缀 */
-const CRON_PREFIX = 'QQBOT_CRON:';
-// ============================================
-// 解析函数
-// ============================================
-/**
- * 解析 AI 输出的结构化载荷
- *
- * 检测消息是否以 QQBOT_PAYLOAD: 前缀开头，如果是则提取并解析 JSON
- *
- * @param text AI 输出的原始文本
- * @returns 解析结果
- *
- * @example
- * const result = parseQQBotPayload('QQBOT_PAYLOAD:\n{"type": "media", "mediaType": "image", ...}');
- * if (result.isPayload && result.payload) {
- *   // 处理结构化载荷
- * }
- */
-export function parseQQBotPayload(text) {
-    const trimmedText = text.trim();
-    // 检查是否以 QQBOT_PAYLOAD: 开头
-    if (!trimmedText.startsWith(PAYLOAD_PREFIX)) {
-        return {
-            isPayload: false,
-            text: text
-        };
-    }
-    // 提取 JSON 内容（去掉前缀）
-    const jsonContent = trimmedText.slice(PAYLOAD_PREFIX.length).trim();
-    if (!jsonContent) {
-        return {
-            isPayload: true,
-            error: '载荷内容为空'
-        };
-    }
-    try {
-        const payload = JSON.parse(jsonContent);
-        // 验证必要字段
-        if (!payload.type) {
-            return {
-                isPayload: true,
-                error: '载荷缺少 type 字段'
-            };
-        }
-        // 根据 type 进行额外验证
-        if (payload.type === 'cron_reminder') {
-            if (!payload.content || !payload.targetType || !payload.targetAddress) {
-                return {
-                    isPayload: true,
-                    error: 'cron_reminder 载荷缺少必要字段 (content, targetType, targetAddress)'
-                };
-            }
-        }
-        else if (payload.type === 'media') {
-            if (!payload.mediaType || !payload.source || !payload.path) {
-                return {
-                    isPayload: true,
-                    error: 'media 载荷缺少必要字段 (mediaType, source, path)'
-                };
-            }
-        }
-        return {
-            isPayload: true,
-            payload
-        };
-    }
-    catch (e) {
-        return {
-            isPayload: true,
-            error: `JSON 解析失败: ${e instanceof Error ? e.message : String(e)}`
-        };
-    }
-}
-// ============================================
-// Cron 编码/解码函数
-// ============================================
-/**
- * 将定时提醒载荷编码为 Cron 消息格式
- *
- * 将 JSON 编码为 Base64，并添加 QQBOT_CRON: 前缀
- *
- * @param payload 定时提醒载荷
- * @returns 编码后的消息字符串，格式为 QQBOT_CRON:{base64}
- *
- * @example
- * const message = encodePayloadForCron({
- *   type: 'cron_reminder',
- *   content: '喝水时间到！',
- *   targetType: 'c2c',
- *   targetAddress: 'user_openid_xxx'
- * });
- * // 返回: QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...
- */
-export function encodePayloadForCron(payload) {
-    const jsonString = JSON.stringify(payload);
-    const base64 = Buffer.from(jsonString, 'utf-8').toString('base64');
-    return `${CRON_PREFIX}${base64}`;
-}
-/**
- * 解码 Cron 消息中的载荷
- *
- * 检测 QQBOT_CRON: 前缀，解码 Base64 并解析 JSON
- *
- * @param message Cron 触发时收到的消息
- * @returns 解码结果，包含是否为 Cron 载荷、解析后的载荷对象或错误信息
- *
- * @example
- * const result = decodeCronPayload('QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...');
- * if (result.isCronPayload && result.payload) {
- *   // 处理定时提醒
- * }
- */
-export function decodeCronPayload(message) {
-    const trimmedMessage = message.trim();
-    // 检查是否以 QQBOT_CRON: 开头
-    if (!trimmedMessage.startsWith(CRON_PREFIX)) {
-        return {
-            isCronPayload: false
-        };
-    }
-    // 提取 Base64 内容
-    const base64Content = trimmedMessage.slice(CRON_PREFIX.length);
-    if (!base64Content) {
-        return {
-            isCronPayload: true,
-            error: 'Cron 载荷内容为空'
-        };
-    }
-    try {
-        // Base64 解码
-        const jsonString = Buffer.from(base64Content, 'base64').toString('utf-8');
-        const payload = JSON.parse(jsonString);
-        // 验证类型
-        if (payload.type !== 'cron_reminder') {
-            return {
-                isCronPayload: true,
-                error: `期望 type 为 cron_reminder，实际为 ${payload.type}`
-            };
-        }
-        // 验证必要字段
-        if (!payload.content || !payload.targetType || !payload.targetAddress) {
-            return {
-                isCronPayload: true,
-                error: 'Cron 载荷缺少必要字段'
-            };
-        }
-        return {
-            isCronPayload: true,
-            payload
-        };
-    }
-    catch (e) {
-        return {
-            isCronPayload: true,
-            error: `Cron 载荷解码失败: ${e instanceof Error ? e.message : String(e)}`
-        };
-    }
-}
-// ============================================
-// 辅助函数
-// ============================================
-/**
- * 判断载荷是否为定时提醒类型
- */
-export function isCronReminderPayload(payload) {
-    return payload.type === 'cron_reminder';
-}
-/**
- * 判断载荷是否为媒体消息类型
- */
-export function isMediaPayload(payload) {
-    return payload.type === 'media';
-}

package/dist/src/utils/pkg-version.d.ts

@@ -1,5 +0,0 @@
-/**
- * 从 import.meta.url 向上遍历目录树查找 package.json 并读取 version。
- * 不依赖硬编码的 "../" 层级，无论编译输出结构如何变化都能可靠找到。
- */
-export declare function getPackageVersion(metaUrl?: string): string;

package/dist/src/utils/pkg-version.js

@@ -1,61 +0,0 @@
-/**
- * 从 import.meta.url 向上遍历目录树查找 package.json 并读取 version。
- * 不依赖硬编码的 "../" 层级，无论编译输出结构如何变化都能可靠找到。
- */
-import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
-import path from "node:path";
-import fs from "node:fs";
-/** 已定位到的 package.json 路径，避免重复遍历目录树 */
-let _resolvedPkgPath = null;
-export function getPackageVersion(metaUrl) {
-    // 如果之前已定位到 package.json 路径，直接重新读取（快速路径）
-    if (_resolvedPkgPath) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(_resolvedPkgPath, "utf8"));
-            if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-                return pkg.version;
-            }
-        }
-        catch {
-            // 文件可能已被删除（升级过程中），清除路径缓存，走完整查找
-            _resolvedPkgPath = null;
-        }
-    }
-    // Strategy 1: 从调用者的 import.meta.url（或本模块）向上遍历找 package.json
-    const startFile = metaUrl ? fileURLToPath(metaUrl) : fileURLToPath(import.meta.url);
-    let dir = path.dirname(startFile);
-    const root = path.parse(dir).root;
-    while (dir !== root) {
-        const candidate = path.join(dir, "package.json");
-        try {
-            if (fs.existsSync(candidate)) {
-                const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
-                // 确认是我们自己的包（避免找到其他 package.json）
-                if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-                    _resolvedPkgPath = candidate;
-                    return pkg.version;
-                }
-            }
-        }
-        catch {
-            // ignore and try parent
-        }
-        dir = path.dirname(dir);
-    }
-    // Strategy 2: fallback 用 createRequire 尝试常见相对路径
-    try {
-        const require = createRequire(metaUrl ?? import.meta.url);
-        for (const rel of ["../../package.json", "../package.json", "./package.json"]) {
-            try {
-                const pkg = require(rel);
-                if (pkg?.version) {
-                    return pkg.version;
-                }
-            }
-            catch { /* next */ }
-        }
-    }
-    catch { /* fallback */ }
-    return "unknown";
-}

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

@@ -1,137 +0,0 @@
-/**
- * 跨平台兼容工具
- *
- * 统一 Mac / Linux / Windows 三大系统的：
- * - 用户主目录获取
- * - 临时目录获取
- * - 本地路径判断
- * - ffmpeg / ffprobe 可执行文件路径
- * - silk-wasm 原生模块兼容性检测
- * - 启动诊断报告
- */
-export type PlatformType = "darwin" | "linux" | "win32" | "other";
-export declare function getPlatform(): PlatformType;
-export declare function isWindows(): boolean;
-/**
- * 安全获取用户主目录
- *
- * 优先级:
- * 1. os.homedir()（Node 原生，所有平台）
- * 2. $HOME（Mac/Linux）或 %USERPROFILE%（Windows）
- * 3. 降级到 /tmp（Linux/Mac）或 os.tmpdir()（Windows）
- *
- * 与之前 `process.env.HOME || "/home/ubuntu"` 的硬编码相比，
- * 现在能正确处理 Windows 和非 ubuntu 用户。
- */
-export declare function getHomeDir(): string;
-/**
- * 获取 .openclaw/qqbot 下的子目录路径，并自动创建
- * 替代各文件中分散的 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
- * Linux: /tmp
- * Windows: %TEMP% 或 C:\Users\xxx\AppData\Local\Temp
- */
-export declare function getTempDir(): string;
-/**
- * 展开路径中的波浪线（~）为用户主目录
- *
- * Mac/Linux 用户经常使用 `~/Desktop/file.png` 这样的路径，
- * 但 Node.js 的 fs 模块不会像 shell 一样自动展开 `~`。
- *
- * 支持:
- * - `~/xxx`  → `/Users/you/xxx`（Mac）或 `/home/you/xxx`（Linux）
- * - `~`      → `/Users/you`
- * - 非 `~` 开头的路径原样返回
- *
- * 注意: 不支持 `~otheruser/xxx` 语法（极少使用，且需要系统调用获取其他用户信息）
- */
-export declare function expandTilde(p: string): string;
-/**
- * 对路径进行完整的规范化处理：剥离 file:// 前缀 + 展开波浪线 + 去除首尾空白
- * 所有文件操作前应通过此函数处理用户输入的路径
- */
-export declare function normalizePath(p: string): string;
-/**
- * 规范化文件名为 QQ Bot API 要求的 UTF-8 编码格式
- *
- * 问题场景:
- * - macOS HFS+/APFS 文件系统使用 NFD（Unicode 分解形式）存储文件名，
- *   例如「中文.txt」被分解为多个码点，QQ Bot API 可能拒绝
- * - 文件名可能包含 API 不接受的特殊控制字符
- * - URL 路径中可能包含 percent-encoded 的文件名需要解码
- *
- * 处理:
- * 1. Unicode NFC 规范化（将 NFD 分解形式合并为 NFC 组合形式）
- * 2. 去除 ASCII 控制字符（0x00-0x1F, 0x7F）
- * 3. 去除首尾空白
- * 4. 对 percent-encoded 的文件名尝试 URI 解码
- */
-export declare function sanitizeFileName(name: string): string;
-/**
- * 判断字符串是否为本地文件路径（非 URL）
- *
- * 覆盖:
- * - Unix 绝对路径: /Users/..., /home/..., /tmp/...
- * - Windows 绝对路径: C:\..., D:/..., \\server\share
- * - 相对路径: ./file, ../file
- * - 波浪线路径: ~/Desktop/file.png
- * - file:// 协议: file:///Users/..., file:///home/...
- *
- * 不匹配:
- * - http:// / https:// URL
- * - data: URL
- */
-export declare function isLocalPath(p: string): boolean;
-/**
- * 判断 markdown 中提取的路径是否像本地路径
- * 比 isLocalPath 更宽松，用于从 markdown ![](path) 中检测误用
- */
-export declare function looksLikeLocalPath(p: string): boolean;
-/**
- * 检测 ffmpeg 是否可用，返回可执行路径
- *
- * Windows 上检测 ffmpeg.exe，Mac/Linux 检测 ffmpeg
- * 支持通过环境变量 FFMPEG_PATH 指定自定义路径
- *
- * @returns ffmpeg 可执行文件路径，不可用返回 null
- */
-export declare function detectFfmpeg(): Promise<string | null>;
-/** 重置 ffmpeg 缓存（用于测试） */
-export declare function resetFfmpegCache(): void;
-/**
- * 检测 silk-wasm 是否可用
- *
- * silk-wasm 依赖 WASM 运行时，在某些环境（如老版本 Node、某些容器）可能不可用。
- * 提前检测避免运行时崩溃。
- */
-export declare function checkSilkWasmAvailable(): Promise<boolean>;
-export interface DiagnosticReport {
-    platform: string;
-    arch: string;
-    nodeVersion: string;
-    homeDir: string;
-    tempDir: string;
-    dataDir: string;
-    ffmpeg: string | null;
-    silkWasm: boolean;
-    warnings: string[];
-}
-/**
- * 运行启动诊断，返回环境报告
- * 在 gateway 启动时调用，打印环境信息并给出警告
- */
-export declare function runDiagnostics(): Promise<DiagnosticReport>;