@sliverp/qqbot 1.3.0

package/dist/src/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 消息（默认 false，需要机器人具备该权限才能启用） */
+    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 消息（默认 false，需要机器人具备该权限才能启用） */
+    markdownSupport?: boolean;
+}
+/**
+ * 富媒体附件
+ */
+export interface MessageAttachment {
+    content_type: string;
+    filename?: string;
+    height?: number;
+    width?: number;
+    size?: number;
+    url: string;
+}
+/**
+ * C2C 消息事件
+ */
+export interface C2CMessageEvent {
+    author: {
+        id: string;
+        union_openid: string;
+        user_openid: string;
+    };
+    content: string;
+    id: string;
+    timestamp: string;
+    message_scene?: {
+        source: 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;
+    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/utils/image-size.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 图片尺寸工具
+ * 用于获取图片尺寸，生成 QQBot 的 markdown 图片格式
+ *
+ * QQBot markdown 图片格式: ![#宽px #高px](url)
+ */
+import { Buffer } from "buffer";
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** 默认图片尺寸（当无法获取时使用） */
+export declare const DEFAULT_IMAGE_SIZE: ImageSize;
+/**
+ * 从图片数据 Buffer 解析尺寸
+ */
+export declare function parseImageSize(buffer: Buffer): ImageSize | null;
+/**
+ * 从公网 URL 获取图片尺寸
+ * 只下载前 64KB 数据，足够解析大部分图片格式的头部
+ */
+export declare function getImageSizeFromUrl(url: string, timeoutMs?: number): Promise<ImageSize | null>;
+/**
+ * 从 Base64 Data URL 获取图片尺寸
+ */
+export declare function getImageSizeFromDataUrl(dataUrl: string): ImageSize | null;
+/**
+ * 获取图片尺寸（自动判断来源）
+ * @param source - 图片 URL 或 Base64 Data URL
+ * @returns 图片尺寸，失败返回 null
+ */
+export declare function getImageSize(source: string): Promise<ImageSize | null>;
+/**
+ * 生成 QQBot markdown 图片格式
+ * 格式: ![#宽px #高px](url)
+ *
+ * @param url - 图片 URL
+ * @param size - 图片尺寸，如果为 null 则使用默认尺寸
+ * @returns QQBot markdown 图片字符串
+ */
+export declare function formatQQBotMarkdownImage(url: string, size: ImageSize | null): string;
+/**
+ * 检查 markdown 图片是否已经包含 QQBot 格式的尺寸信息
+ * 格式: ![#宽px #高px](url)
+ */
+export declare function hasQQBotImageSize(markdownImage: string): boolean;
+/**
+ * 从已有的 QQBot 格式 markdown 图片中提取尺寸
+ * 格式: ![#宽px #高px](url)
+ */
+export declare function extractQQBotImageSize(markdownImage: string): ImageSize | null;

package/dist/src/utils/image-size.js

@@ -0,0 +1,234 @@
+/**
+ * 图片尺寸工具
+ * 用于获取图片尺寸，生成 QQBot 的 markdown 图片格式
+ *
+ * QQBot markdown 图片格式: ![#宽px #高px](url)
+ */
+import { Buffer } from "buffer";
+/** 默认图片尺寸（当无法获取时使用） */
+export const DEFAULT_IMAGE_SIZE = { width: 512, height: 512 };
+/**
+ * 从 PNG 文件头解析图片尺寸
+ * PNG 文件头结构: 前 8 字节是签名，IHDR 块从第 8 字节开始
+ * IHDR 块: 长度(4) + 类型(4, "IHDR") + 宽度(4) + 高度(4) + ...
+ */
+function parsePngSize(buffer) {
+    // PNG 签名: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.length < 24)
+        return null;
+    if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4E || buffer[3] !== 0x47) {
+        return null;
+    }
+    // IHDR 块从第 8 字节开始，宽度在第 16-19 字节，高度在第 20-23 字节
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    return { width, height };
+}
+/**
+ * 从 JPEG 文件解析图片尺寸
+ * JPEG 尺寸在 SOF0/SOF2 块中
+ */
+function parseJpegSize(buffer) {
+    // JPEG 签名: FF D8 FF
+    if (buffer.length < 4)
+        return null;
+    if (buffer[0] !== 0xFF || buffer[1] !== 0xD8) {
+        return null;
+    }
+    let offset = 2;
+    while (offset < buffer.length - 9) {
+        if (buffer[offset] !== 0xFF) {
+            offset++;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        // SOF0 (0xC0) 或 SOF2 (0xC2) 包含图片尺寸
+        if (marker === 0xC0 || marker === 0xC2) {
+            // 格式: FF C0 长度(2) 精度(1) 高度(2) 宽度(2)
+            if (offset + 9 <= buffer.length) {
+                const height = buffer.readUInt16BE(offset + 5);
+                const width = buffer.readUInt16BE(offset + 7);
+                return { width, height };
+            }
+        }
+        // 跳过当前块
+        if (offset + 3 < buffer.length) {
+            const blockLength = buffer.readUInt16BE(offset + 2);
+            offset += 2 + blockLength;
+        }
+        else {
+            break;
+        }
+    }
+    return null;
+}
+/**
+ * 从 GIF 文件头解析图片尺寸
+ * GIF 文件头: GIF87a 或 GIF89a (6字节) + 宽度(2) + 高度(2)
+ */
+function parseGifSize(buffer) {
+    if (buffer.length < 10)
+        return null;
+    const signature = buffer.toString("ascii", 0, 6);
+    if (signature !== "GIF87a" && signature !== "GIF89a") {
+        return null;
+    }
+    const width = buffer.readUInt16LE(6);
+    const height = buffer.readUInt16LE(8);
+    return { width, height };
+}
+/**
+ * 从 WebP 文件解析图片尺寸
+ * WebP 文件头: RIFF(4) + 文件大小(4) + WEBP(4) + VP8/VP8L/VP8X(4) + ...
+ */
+function parseWebpSize(buffer) {
+    if (buffer.length < 30)
+        return null;
+    // 检查 RIFF 和 WEBP 签名
+    const riff = buffer.toString("ascii", 0, 4);
+    const webp = buffer.toString("ascii", 8, 12);
+    if (riff !== "RIFF" || webp !== "WEBP") {
+        return null;
+    }
+    const chunkType = buffer.toString("ascii", 12, 16);
+    // VP8 (有损压缩)
+    if (chunkType === "VP8 ") {
+        // VP8 帧头从第 23 字节开始，检查签名 9D 01 2A
+        if (buffer.length >= 30 && buffer[23] === 0x9D && buffer[24] === 0x01 && buffer[25] === 0x2A) {
+            const width = buffer.readUInt16LE(26) & 0x3FFF;
+            const height = buffer.readUInt16LE(28) & 0x3FFF;
+            return { width, height };
+        }
+    }
+    // VP8L (无损压缩)
+    if (chunkType === "VP8L") {
+        // VP8L 签名: 0x2F
+        if (buffer.length >= 25 && buffer[20] === 0x2F) {
+            const bits = buffer.readUInt32LE(21);
+            const width = (bits & 0x3FFF) + 1;
+            const height = ((bits >> 14) & 0x3FFF) + 1;
+            return { width, height };
+        }
+    }
+    // VP8X (扩展格式)
+    if (chunkType === "VP8X") {
+        if (buffer.length >= 30) {
+            // 宽度和高度在第 24-26 和 27-29 字节（24位小端）
+            const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
+            const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
+            return { width, height };
+        }
+    }
+    return null;
+}
+/**
+ * 从图片数据 Buffer 解析尺寸
+ */
+export function parseImageSize(buffer) {
+    // 尝试各种格式
+    return parsePngSize(buffer)
+        ?? parseJpegSize(buffer)
+        ?? parseGifSize(buffer)
+        ?? parseWebpSize(buffer);
+}
+/**
+ * 从公网 URL 获取图片尺寸
+ * 只下载前 64KB 数据，足够解析大部分图片格式的头部
+ */
+export async function getImageSizeFromUrl(url, timeoutMs = 5000) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        // 使用 Range 请求只获取前 64KB
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                "Range": "bytes=0-65535",
+                "User-Agent": "QQBot-Image-Size-Detector/1.0",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok && response.status !== 206) {
+            console.log(`[image-size] Failed to fetch ${url}: ${response.status}`);
+            return null;
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        const size = parseImageSize(buffer);
+        if (size) {
+            console.log(`[image-size] Got size from URL: ${size.width}x${size.height} - ${url.slice(0, 60)}...`);
+        }
+        return size;
+    }
+    catch (err) {
+        console.log(`[image-size] Error fetching ${url.slice(0, 60)}...: ${err}`);
+        return null;
+    }
+}
+/**
+ * 从 Base64 Data URL 获取图片尺寸
+ */
+export function getImageSizeFromDataUrl(dataUrl) {
+    try {
+        // 格式: data:image/png;base64,xxxxx
+        const matches = dataUrl.match(/^data:image\/[^;]+;base64,(.+)$/);
+        if (!matches) {
+            return null;
+        }
+        const base64Data = matches[1];
+        const buffer = Buffer.from(base64Data, "base64");
+        const size = parseImageSize(buffer);
+        if (size) {
+            console.log(`[image-size] Got size from Base64: ${size.width}x${size.height}`);
+        }
+        return size;
+    }
+    catch (err) {
+        console.log(`[image-size] Error parsing Base64: ${err}`);
+        return null;
+    }
+}
+/**
+ * 获取图片尺寸（自动判断来源）
+ * @param source - 图片 URL 或 Base64 Data URL
+ * @returns 图片尺寸，失败返回 null
+ */
+export async function getImageSize(source) {
+    if (source.startsWith("data:")) {
+        return getImageSizeFromDataUrl(source);
+    }
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        return getImageSizeFromUrl(source);
+    }
+    return null;
+}
+/**
+ * 生成 QQBot markdown 图片格式
+ * 格式: ![#宽px #高px](url)
+ *
+ * @param url - 图片 URL
+ * @param size - 图片尺寸，如果为 null 则使用默认尺寸
+ * @returns QQBot markdown 图片字符串
+ */
+export function formatQQBotMarkdownImage(url, size) {
+    const { width, height } = size ?? DEFAULT_IMAGE_SIZE;
+    return `![#${width}px #${height}px](${url})`;
+}
+/**
+ * 检查 markdown 图片是否已经包含 QQBot 格式的尺寸信息
+ * 格式: ![#宽px #高px](url)
+ */
+export function hasQQBotImageSize(markdownImage) {
+    return /!\[#\d+px\s+#\d+px\]/.test(markdownImage);
+}
+/**
+ * 从已有的 QQBot 格式 markdown 图片中提取尺寸
+ * 格式: ![#宽px #高px](url)
+ */
+export function extractQQBotImageSize(markdownImage) {
+    const match = markdownImage.match(/!\[#(\d+)px\s+#(\d+)px\]/);
+    if (match) {
+        return { width: parseInt(match[1], 10), height: parseInt(match[2], 10) };
+    }
+    return null;
+}

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 */
+    mediaType: 'image' | 'audio' | 'video';
+    /** 来源类型：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';
+}