@ryantest/openclaw-qqbot 0.0.1

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

@@ -0,0 +1,112 @@
+/**
+ * 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

@@ -0,0 +1,186 @@
+/**
+ * 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/platform.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 跨平台兼容工具
+ *
+ * 统一 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>;