@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/dist/src/proactive.d.ts

@@ -1,170 +0,0 @@
-/**
- * QQ Bot 主动发送消息模块
- *
- * 该模块提供以下能力：
- * 1. 记录已知用户（曾与机器人交互过的用户）
- * 2. 主动发送消息给用户或群组
- * 3. 查询已知用户列表
- */
-import type { ResolvedQQBotAccount } from "./types.js";
-/**
- * 已知用户信息
- */
-export interface KnownUser {
-    type: "c2c" | "group" | "channel";
-    openid: string;
-    accountId: string;
-    nickname?: string;
-    firstInteractionAt: number;
-    lastInteractionAt: number;
-}
-/**
- * 主动发送消息选项
- */
-export interface ProactiveSendOptions {
-    to: string;
-    text: string;
-    type?: "c2c" | "group" | "channel";
-    imageUrl?: string;
-    accountId?: string;
-}
-/**
- * 主动发送消息结果
- */
-export interface ProactiveSendResult {
-    success: boolean;
-    messageId?: string;
-    timestamp?: number | string;
-    error?: string;
-}
-/**
- * 列出已知用户选项
- */
-export interface ListKnownUsersOptions {
-    type?: "c2c" | "group" | "channel";
-    accountId?: string;
-    sortByLastInteraction?: boolean;
-    limit?: number;
-}
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-/**
- * 记录一个已知用户（当收到用户消息时调用）
- *
- * @param user - 用户信息
- */
-export declare function recordKnownUser(user: Omit<KnownUser, "firstInteractionAt">): void;
-/**
- * 获取一个已知用户
- *
- * @param type - 用户类型
- * @param openid - 用户 openid
- * @param accountId - 账户 ID
- */
-export declare function getKnownUser(type: string, openid: string, accountId: string): KnownUser | undefined;
-/**
- * 列出已知用户
- *
- * @param options - 过滤选项
- */
-export declare function listKnownUsers(options?: ListKnownUsersOptions): KnownUser[];
-/**
- * 删除一个已知用户
- *
- * @param type - 用户类型
- * @param openid - 用户 openid
- * @param accountId - 账户 ID
- */
-export declare function removeKnownUser(type: string, openid: string, accountId: string): boolean;
-/**
- * 清除所有已知用户
- *
- * @param accountId - 可选，只清除指定账户的用户
- */
-export declare function clearKnownUsers(accountId?: string): number;
-/**
- * 主动发送消息（带配置解析）
- * 注意：与 outbound.ts 中的 sendProactiveMessage 不同，这个函数接受 OpenClawConfig 并自动解析账户
- *
- * @param options - 发送选项
- * @param cfg - OpenClaw 配置
- * @returns 发送结果
- *
- * @example
- * ```typescript
- * // 发送私聊消息
- * const result = await sendProactive({
- *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",  // 用户 openid
- *   text: "你好！这是一条主动消息",
- *   type: "c2c",
- * }, cfg);
- *
- * // 发送群聊消息
- * const result = await sendProactive({
- *   to: "A1B2C3D4E5F6A7B8",  // 群组 openid
- *   text: "群公告：今天有活动",
- *   type: "group",
- * }, cfg);
- *
- * // 发送带图片的消息
- * const result = await sendProactive({
- *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",
- *   text: "看看这张图片",
- *   imageUrl: "https://example.com/image.png",
- *   type: "c2c",
- * }, cfg);
- * ```
- */
-export declare function sendProactive(options: ProactiveSendOptions, cfg: OpenClawConfig): Promise<ProactiveSendResult>;
-/**
- * 批量发送主动消息
- *
- * @param recipients - 接收者列表（openid 数组）
- * @param text - 消息内容
- * @param type - 消息类型
- * @param cfg - OpenClaw 配置
- * @param accountId - 账户 ID
- * @returns 发送结果列表
- */
-export declare function sendBulkProactiveMessage(recipients: string[], text: string, type: "c2c" | "group", cfg: OpenClawConfig, accountId?: string): Promise<Array<{
-    to: string;
-    result: ProactiveSendResult;
-}>>;
-/**
- * 发送消息给所有已知用户
- *
- * @param text - 消息内容
- * @param cfg - OpenClaw 配置
- * @param options - 过滤选项
- * @returns 发送结果统计
- */
-export declare function broadcastMessage(text: string, cfg: OpenClawConfig, options?: {
-    type?: "c2c" | "group";
-    accountId?: string;
-    limit?: number;
-}): Promise<{
-    total: number;
-    success: number;
-    failed: number;
-    results: Array<{
-        to: string;
-        result: ProactiveSendResult;
-    }>;
-}>;
-/**
- * 根据账户配置直接发送主动消息（不需要 cfg）
- *
- * @param account - 已解析的账户配置
- * @param to - 目标 openid
- * @param text - 消息内容
- * @param type - 消息类型
- */
-export declare function sendProactiveMessageDirect(account: ResolvedQQBotAccount, to: string, text: string, type?: "c2c" | "group"): Promise<ProactiveSendResult>;
-/**
- * 获取已知用户统计
- */
-export declare function getKnownUsersStats(accountId?: string): {
-    total: number;
-    c2c: number;
-    group: number;
-    channel: number;
-};

package/dist/src/proactive.js

@@ -1,399 +0,0 @@
-/**
- * QQ Bot 主动发送消息模块
- *
- * 该模块提供以下能力：
- * 1. 记录已知用户（曾与机器人交互过的用户）
- * 2. 主动发送消息给用户或群组
- * 3. 查询已知用户列表
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getAccessToken, sendProactiveC2CMessage, sendProactiveGroupMessage, sendC2CImageMessage, sendGroupImageMessage, } from "./api.js";
-import { resolveQQBotAccount } from "./config.js";
-// ============ 用户存储管理 ============
-/**
- * 已知用户存储
- * 使用简单的 JSON 文件存储，保存在 .openclaw/qqbot 目录下
- */
-import { getQQBotDataDir } from "./utils/platform.js";
-const STORAGE_DIR = getQQBotDataDir("data");
-const KNOWN_USERS_FILE = path.join(STORAGE_DIR, "known-users.json");
-// 内存缓存
-let knownUsersCache = null;
-let cacheLastModified = 0;
-/**
- * 确保存储目录存在
- */
-function ensureStorageDir() {
-    if (!fs.existsSync(STORAGE_DIR)) {
-        fs.mkdirSync(STORAGE_DIR, { recursive: true });
-    }
-}
-/**
- * 生成用户唯一键
- */
-function getUserKey(type, openid, accountId) {
-    return `${accountId}:${type}:${openid}`;
-}
-/**
- * 从文件加载已知用户
- */
-function loadKnownUsers() {
-    if (knownUsersCache !== null) {
-        // 检查文件是否被修改
-        try {
-            const stat = fs.statSync(KNOWN_USERS_FILE);
-            if (stat.mtimeMs <= cacheLastModified) {
-                return knownUsersCache;
-            }
-        }
-        catch {
-            // 文件不存在，使用缓存
-            return knownUsersCache;
-        }
-    }
-    const users = new Map();
-    try {
-        if (fs.existsSync(KNOWN_USERS_FILE)) {
-            const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
-            const parsed = JSON.parse(data);
-            for (const user of parsed) {
-                const key = getUserKey(user.type, user.openid, user.accountId);
-                users.set(key, user);
-            }
-            cacheLastModified = fs.statSync(KNOWN_USERS_FILE).mtimeMs;
-        }
-    }
-    catch (err) {
-        console.error(`[qqbot:proactive] Failed to load known users: ${err}`);
-    }
-    knownUsersCache = users;
-    return users;
-}
-/**
- * 保存已知用户到文件
- */
-function saveKnownUsers(users) {
-    try {
-        ensureStorageDir();
-        const data = Array.from(users.values());
-        fs.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(data, null, 2), "utf-8");
-        cacheLastModified = Date.now();
-        knownUsersCache = users;
-    }
-    catch (err) {
-        console.error(`[qqbot:proactive] Failed to save known users: ${err}`);
-    }
-}
-/**
- * 记录一个已知用户（当收到用户消息时调用）
- *
- * @param user - 用户信息
- */
-export function recordKnownUser(user) {
-    const users = loadKnownUsers();
-    const key = getUserKey(user.type, user.openid, user.accountId);
-    const existing = users.get(key);
-    const now = user.lastInteractionAt || Date.now();
-    users.set(key, {
-        ...user,
-        lastInteractionAt: now,
-        firstInteractionAt: existing?.firstInteractionAt ?? now,
-        // 更新昵称（如果有新的）
-        nickname: user.nickname || existing?.nickname,
-    });
-    saveKnownUsers(users);
-    console.log(`[qqbot:proactive] Recorded user: ${key}`);
-}
-/**
- * 获取一个已知用户
- *
- * @param type - 用户类型
- * @param openid - 用户 openid
- * @param accountId - 账户 ID
- */
-export function getKnownUser(type, openid, accountId) {
-    const users = loadKnownUsers();
-    const key = getUserKey(type, openid, accountId);
-    return users.get(key);
-}
-/**
- * 列出已知用户
- *
- * @param options - 过滤选项
- */
-export function listKnownUsers(options) {
-    const users = loadKnownUsers();
-    let result = Array.from(users.values());
-    // 过滤类型
-    if (options?.type) {
-        result = result.filter(u => u.type === options.type);
-    }
-    // 过滤账户
-    if (options?.accountId) {
-        result = result.filter(u => u.accountId === options.accountId);
-    }
-    // 排序
-    if (options?.sortByLastInteraction !== false) {
-        result.sort((a, b) => b.lastInteractionAt - a.lastInteractionAt);
-    }
-    // 限制数量
-    if (options?.limit && options.limit > 0) {
-        result = result.slice(0, options.limit);
-    }
-    return result;
-}
-/**
- * 删除一个已知用户
- *
- * @param type - 用户类型
- * @param openid - 用户 openid
- * @param accountId - 账户 ID
- */
-export function removeKnownUser(type, openid, accountId) {
-    const users = loadKnownUsers();
-    const key = getUserKey(type, openid, accountId);
-    const deleted = users.delete(key);
-    if (deleted) {
-        saveKnownUsers(users);
-    }
-    return deleted;
-}
-/**
- * 清除所有已知用户
- *
- * @param accountId - 可选，只清除指定账户的用户
- */
-export function clearKnownUsers(accountId) {
-    const users = loadKnownUsers();
-    let count = 0;
-    if (accountId) {
-        for (const [key, user] of users) {
-            if (user.accountId === accountId) {
-                users.delete(key);
-                count++;
-            }
-        }
-    }
-    else {
-        count = users.size;
-        users.clear();
-    }
-    if (count > 0) {
-        saveKnownUsers(users);
-    }
-    return count;
-}
-// ============ 主动发送消息 ============
-/**
- * 主动发送消息（带配置解析）
- * 注意：与 outbound.ts 中的 sendProactiveMessage 不同，这个函数接受 OpenClawConfig 并自动解析账户
- *
- * @param options - 发送选项
- * @param cfg - OpenClaw 配置
- * @returns 发送结果
- *
- * @example
- * ```typescript
- * // 发送私聊消息
- * const result = await sendProactive({
- *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",  // 用户 openid
- *   text: "你好！这是一条主动消息",
- *   type: "c2c",
- * }, cfg);
- *
- * // 发送群聊消息
- * const result = await sendProactive({
- *   to: "A1B2C3D4E5F6A7B8",  // 群组 openid
- *   text: "群公告：今天有活动",
- *   type: "group",
- * }, cfg);
- *
- * // 发送带图片的消息
- * const result = await sendProactive({
- *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",
- *   text: "看看这张图片",
- *   imageUrl: "https://example.com/image.png",
- *   type: "c2c",
- * }, cfg);
- * ```
- */
-export async function sendProactive(options, cfg) {
-    const { to, text, type = "c2c", imageUrl, accountId = "default" } = options;
-    // 解析账户配置
-    const account = resolveQQBotAccount(cfg, accountId);
-    if (!account.appId || !account.clientSecret) {
-        return {
-            success: false,
-            error: "QQBot not configured (missing appId or clientSecret)",
-        };
-    }
-    try {
-        const accessToken = await getAccessToken(account.appId, account.clientSecret);
-        // 如果有图片，先发送图片
-        if (imageUrl) {
-            try {
-                if (type === "c2c") {
-                    await sendC2CImageMessage(accessToken, to, imageUrl, undefined, undefined);
-                }
-                else if (type === "group") {
-                    await sendGroupImageMessage(accessToken, to, imageUrl, undefined, undefined);
-                }
-                console.log(`[qqbot:proactive] Sent image to ${type}:${to}`);
-            }
-            catch (err) {
-                console.error(`[qqbot:proactive] Failed to send image: ${err}`);
-                // 图片发送失败不影响文本发送
-            }
-        }
-        // 发送文本消息
-        let result;
-        if (type === "c2c") {
-            result = await sendProactiveC2CMessage(accessToken, to, text);
-        }
-        else if (type === "group") {
-            result = await sendProactiveGroupMessage(accessToken, to, text);
-        }
-        else if (type === "channel") {
-            // 频道消息需要 channel_id，这里暂时不支持主动发送
-            return {
-                success: false,
-                error: "Channel proactive messages are not supported. Please use group or c2c.",
-            };
-        }
-        else {
-            return {
-                success: false,
-                error: `Unknown message type: ${type}`,
-            };
-        }
-        console.log(`[qqbot:proactive] Sent message to ${type}:${to}, id: ${result.id}`);
-        return {
-            success: true,
-            messageId: result.id,
-            timestamp: result.timestamp,
-        };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`[qqbot:proactive] Failed to send message: ${message}`);
-        return {
-            success: false,
-            error: message,
-        };
-    }
-}
-/**
- * 批量发送主动消息
- *
- * @param recipients - 接收者列表（openid 数组）
- * @param text - 消息内容
- * @param type - 消息类型
- * @param cfg - OpenClaw 配置
- * @param accountId - 账户 ID
- * @returns 发送结果列表
- */
-export async function sendBulkProactiveMessage(recipients, text, type, cfg, accountId = "default") {
-    const results = [];
-    for (const to of recipients) {
-        const result = await sendProactive({ to, text, type, accountId }, cfg);
-        results.push({ to, result });
-        // 添加延迟，避免频率限制
-        await new Promise(resolve => setTimeout(resolve, 500));
-    }
-    return results;
-}
-/**
- * 发送消息给所有已知用户
- *
- * @param text - 消息内容
- * @param cfg - OpenClaw 配置
- * @param options - 过滤选项
- * @returns 发送结果统计
- */
-export async function broadcastMessage(text, cfg, options) {
-    const users = listKnownUsers({
-        type: options?.type,
-        accountId: options?.accountId,
-        limit: options?.limit,
-        sortByLastInteraction: true,
-    });
-    // 过滤掉频道用户（不支持主动发送）
-    const validUsers = users.filter(u => u.type === "c2c" || u.type === "group");
-    const results = [];
-    let success = 0;
-    let failed = 0;
-    for (const user of validUsers) {
-        const result = await sendProactive({
-            to: user.openid,
-            text,
-            type: user.type,
-            accountId: user.accountId,
-        }, cfg);
-        results.push({ to: user.openid, result });
-        if (result.success) {
-            success++;
-        }
-        else {
-            failed++;
-        }
-        // 添加延迟，避免频率限制
-        await new Promise(resolve => setTimeout(resolve, 500));
-    }
-    return {
-        total: validUsers.length,
-        success,
-        failed,
-        results,
-    };
-}
-// ============ 辅助函数 ============
-/**
- * 根据账户配置直接发送主动消息（不需要 cfg）
- *
- * @param account - 已解析的账户配置
- * @param to - 目标 openid
- * @param text - 消息内容
- * @param type - 消息类型
- */
-export async function sendProactiveMessageDirect(account, to, text, type = "c2c") {
-    if (!account.appId || !account.clientSecret) {
-        return {
-            success: false,
-            error: "QQBot not configured (missing appId or clientSecret)",
-        };
-    }
-    try {
-        const accessToken = await getAccessToken(account.appId, account.clientSecret);
-        let result;
-        if (type === "c2c") {
-            result = await sendProactiveC2CMessage(accessToken, to, text);
-        }
-        else {
-            result = await sendProactiveGroupMessage(accessToken, to, text);
-        }
-        return {
-            success: true,
-            messageId: result.id,
-            timestamp: result.timestamp,
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/**
- * 获取已知用户统计
- */
-export function getKnownUsersStats(accountId) {
-    const users = listKnownUsers({ accountId });
-    return {
-        total: users.length,
-        c2c: users.filter(u => u.type === "c2c").length,
-        group: users.filter(u => u.type === "group").length,
-        channel: users.filter(u => u.type === "channel").length,
-    };
-}

package/dist/src/ref-index-store.d.ts

@@ -1,101 +0,0 @@
-/**
- * QQ Bot 引用索引持久化存储
- *
- * QQ Bot 使用 REFIDX_xxx 索引体系做引用消息，
- * 入站事件只有索引值，无 API 可回查内容。
- * 采用 内存缓存 + JSONL 追加写持久化 方案，确保重启后历史引用仍可命中。
- *
- * 存储位置：~/.openclaw/qqbot/data/ref-index.jsonl
- *
- * 每行格式：{"k":"REFIDX_xxx","v":{...},"t":1709000000}
- * - k = refIdx 键
- * - v = 消息数据
- * - t = 写入时间（用于 TTL 淘汰和 compact）
- */
-export interface RefIndexEntry {
-    /** 消息文本内容（完整保存） */
-    content: string;
-    /** 发送者 ID */
-    senderId: string;
-    /** 发送者名称 */
-    senderName?: string;
-    /** 消息时间戳 (ms) */
-    timestamp: number;
-    /** 是否是 bot 发出的消息 */
-    isBot?: boolean;
-    /** 附件摘要（图片/语音/视频/文件等） */
-    attachments?: RefAttachmentSummary[];
-}
-/** 附件摘要：存本地路径、在线 URL 和类型描述 */
-export interface RefAttachmentSummary {
-    /** 附件类型 */
-    type: "image" | "voice" | "video" | "file" | "unknown";
-    /** 文件名（如有） */
-    filename?: string;
-    /** MIME 类型 */
-    contentType?: string;
-    /** 语音转录文本（入站：STT/ASR识别结果；出站：TTS原文本） */
-    transcript?: string;
-    /** 语音转录来源：stt=本地STT、asr=平台ASR、tts=TTS原文本、fallback=兜底文案 */
-    transcriptSource?: "stt" | "asr" | "tts" | "fallback";
-    /** 已下载到本地的文件路径（持久化后可供引用时访问） */
-    localPath?: string;
-    /** 在线来源 URL（公网图片/文件等） */
-    url?: string;
-}
-/**
- * 存储一条消息的 refIdx 映射
- */
-export declare function setRefIndex(refIdx: string, entry: RefIndexEntry): void;
-/**
- * 查找被引用消息
- */
-export declare function getRefIndex(refIdx: string): RefIndexEntry | null;
-/**
- * 将引用消息内容格式化为人类可读的描述（供 AI 上下文注入）
- */
-export declare function formatRefEntryForAgent(entry: RefIndexEntry): string;
-/**
- * 将 QQ 推送事件中的 message_reference 结构格式化为人类可读的描述（供 AI 上下文注入）
- *
- * 完整参考 gateway 中对当前消息的处理流程：
- * 1. 调用 processAttachments 下载附件到本地、语音转录
- * 2. 调用 formatVoiceText 格式化语音转录文本
- * 3. 调用 parseFaceTags 解析 QQ 表情标签
- * 4. 按 gateway 中 userContent 的拼接逻辑组合最终文本
- */
-export declare function formatMessageReferenceForAgent(ref: {
-    content: string;
-    attachments?: Array<{
-        content_type: string;
-        url: string;
-        filename?: string;
-        height?: number;
-        width?: number;
-        size?: number;
-        voice_wav_url?: string;
-        asr_refer_text?: string;
-    }>;
-} | undefined, ctx: {
-    appId: string;
-    peerId?: string;
-    cfg: unknown;
-    log?: {
-        info: (msg: string) => void;
-        error: (msg: string) => void;
-        debug?: (msg: string) => void;
-    };
-}): Promise<string>;
-/**
- * 进程退出前强制 compact（确保数据一致性）
- */
-export declare function flushRefIndex(): void;
-/**
- * 缓存统计（调试用）
- */
-export declare function getRefIndexStats(): {
-    size: number;
-    maxEntries: number;
-    totalLinesOnDisk: number;
-    filePath: string;
-};