@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: unknown;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;
+export { qqbotPlugin } from "./src/channel.js";
+export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
+export { qqbotOnboardingAdapter } from "./src/onboarding.js";
+export * from "./src/types.js";
+export * from "./src/api.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/outbound.js";

package/dist/index.js

@@ -0,0 +1,26 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { qqbotPlugin } from "./src/channel.js";
+import { setQQBotRuntime } from "./src/runtime.js";
+import { registerChannelTool } from "./src/tools/channel.js";
+import { registerRemindTool } from "./src/tools/remind.js";
+const plugin = {
+    id: "openclaw-qqbot",
+    name: "QQ Bot",
+    description: "QQ Bot channel plugin",
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        setQQBotRuntime(api.runtime);
+        api.registerChannel({ plugin: qqbotPlugin });
+        registerChannelTool(api);
+        registerRemindTool(api);
+    },
+};
+export default plugin;
+export { qqbotPlugin } from "./src/channel.js";
+export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
+export { qqbotOnboardingAdapter } from "./src/onboarding.js";
+export * from "./src/types.js";
+export * from "./src/api.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/outbound.js";

package/dist/src/admin-resolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+export interface AdminResolverContext {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export declare function loadAdminOpenId(accountId: string, appId: string): string | undefined;
+export declare function saveAdminOpenId(accountId: string, appId: string, openid: string): void;
+export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string, log?: {
+    info: (msg: string) => void;
+}): string | undefined;
+export declare function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void;
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "appId" | "log">): string | undefined;
+/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
+export declare function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void;

package/dist/src/admin-resolver.js

@@ -0,0 +1,157 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+import path from "node:path";
+import * as fs from "node:fs";
+import { getQQBotDataDir } from "./utils/platform.js";
+import { listKnownUsers } from "./known-users.js";
+import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
+import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
+// ---- 文件路径 ----
+function safeName(id) {
+    return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+/** 新版 admin 文件路径（按 accountId + appId 区分） */
+function getAdminMarkerFile(accountId, appId) {
+    return path.join(getQQBotDataDir("data"), `admin-${safeName(accountId)}-${safeName(appId)}.json`);
+}
+/** 旧版 admin 文件路径（仅按 accountId 区分，用于迁移兼容） */
+function getLegacyAdminMarkerFile(accountId) {
+    return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
+}
+function getUpgradeGreetingTargetFile(accountId, appId) {
+    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeName(accountId)}-${safeName(appId)}.json`);
+}
+// ---- 管理员 openid 持久化 ----
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export function loadAdminOpenId(accountId, appId) {
+    try {
+        // 1. 先尝试新版路径
+        const newFile = getAdminMarkerFile(accountId, appId);
+        if (fs.existsSync(newFile)) {
+            const data = JSON.parse(fs.readFileSync(newFile, "utf8"));
+            if (data.openid)
+                return data.openid;
+        }
+        // 2. fallback 旧版路径（仅按 accountId）
+        const legacyFile = getLegacyAdminMarkerFile(accountId);
+        if (fs.existsSync(legacyFile)) {
+            const data = JSON.parse(fs.readFileSync(legacyFile, "utf8"));
+            if (data.openid) {
+                // 自动迁移：写到新路径，删除旧文件
+                saveAdminOpenId(accountId, appId, data.openid);
+                try {
+                    fs.unlinkSync(legacyFile);
+                }
+                catch { /* ignore */ }
+                return data.openid;
+            }
+        }
+    }
+    catch { /* 文件损坏视为无 */ }
+    return undefined;
+}
+export function saveAdminOpenId(accountId, appId, openid) {
+    try {
+        fs.writeFileSync(getAdminMarkerFile(accountId, appId), JSON.stringify({ accountId, appId, openid, savedAt: new Date().toISOString() }));
+    }
+    catch { /* ignore */ }
+}
+// ---- 升级问候目标 ----
+export function loadUpgradeGreetingTargetOpenId(accountId, appId, log) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!data.openid) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target file found but openid is empty`);
+                return undefined;
+            }
+            if (data.appId && data.appId !== appId) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target appId mismatch: file=${data.appId}, current=${appId}`);
+                return undefined;
+            }
+            if (data.accountId && data.accountId !== accountId) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target accountId mismatch: file=${data.accountId}, current=${accountId}`);
+                return undefined;
+            }
+            log?.info(`[qqbot:${accountId}] upgrade-greeting-target loaded: openid=${data.openid}`);
+            return data.openid;
+        }
+        else {
+            log?.info(`[qqbot:${accountId}] upgrade-greeting-target file not found: ${file}`);
+        }
+    }
+    catch (err) {
+        log?.info(`[qqbot:${accountId}] upgrade-greeting-target file read error: ${err}`);
+    }
+    return undefined;
+}
+export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            fs.unlinkSync(file);
+        }
+    }
+    catch { /* ignore */ }
+}
+// ---- 解析管理员 ----
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export function resolveAdminOpenId(ctx) {
+    const saved = loadAdminOpenId(ctx.accountId, ctx.appId);
+    if (saved)
+        return saved;
+    const first = listKnownUsers({ accountId: ctx.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+    if (first) {
+        saveAdminOpenId(ctx.accountId, ctx.appId, first);
+        ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+    }
+    return first;
+}
+// ---- 启动问候语 ----
+/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
+export function sendStartupGreetings(ctx, trigger) {
+    (async () => {
+        const plan = getStartupGreetingPlan(ctx.accountId, ctx.appId);
+        if (!plan.shouldSend || !plan.greeting) {
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (${plan.reason ?? "debounced"}, trigger=${trigger})`);
+            return;
+        }
+        const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId, ctx.log);
+        // 没有 upgrade-greeting-target 文件 → 不是通过 /bot-upgrade 触发的升级
+        // （console 手动重启、脚本升级等场景），静默更新 marker 不发消息
+        if (!upgradeTargetOpenId) {
+            markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Version changed but no upgrade-greeting-target, silently updating marker (trigger=${trigger})`);
+            return;
+        }
+        try {
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Sending startup greeting to upgrade-requester (trigger=${trigger}): "${plan.greeting}"`);
+            const token = await getAccessToken(ctx.appId, ctx.clientSecret);
+            const GREETING_TIMEOUT_MS = 10_000;
+            await Promise.race([
+                sendProactiveC2CMessage(token, upgradeTargetOpenId, plan.greeting),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+            ]);
+            markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
+            clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to upgrade-requester: ${upgradeTargetOpenId}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, message);
+            ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
+        }
+    })();
+}

package/dist/src/api.d.ts

@@ -0,0 +1,264 @@
+/**
+ * QQ Bot API 鉴权和请求封装
+ * [修复版] 已重构为支持多实例并发，消除全局变量冲突
+ */
+/** API 请求错误，携带 HTTP status code */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    constructor(message: string, status: number, path: string);
+}
+export declare const PLUGIN_USER_AGENT: string;
+/** 出站消息元信息（结构化存储，不做预格式化） */
+export interface OutboundMeta {
+    /** 消息文本内容 */
+    text?: string;
+    /** 媒体类型 */
+    mediaType?: "image" | "voice" | "video" | "file";
+    /** 媒体来源：在线 URL */
+    mediaUrl?: string;
+    /** 媒体来源：本地文件路径或文件名 */
+    mediaLocalPath?: string;
+    /** TTS 原文本（仅 voice 类型有效，用于保存 TTS 前的文本内容） */
+    ttsText?: string;
+}
+type OnMessageSentCallback = (refIdx: string, meta: OutboundMeta) => void;
+/**
+ * 注册出站消息回调
+ * 当消息发送成功且 QQ 返回 ref_idx 时，自动回调此函数
+ * 用于在最底层统一缓存 bot 出站消息的 refIdx
+ */
+export declare function onMessageSent(callback: OnMessageSentCallback): void;
+/**
+ * 初始化 API 配置
+ */
+export declare function initApiConfig(options: {
+    markdownSupport?: boolean;
+}): void;
+/**
+ * 获取当前是否支持 markdown
+ */
+export declare function isMarkdownSupport(): boolean;
+/**
+ * 获取 AccessToken（带缓存 + singleflight 并发安全）
+ *
+ * 使用 singleflight 模式：当多个请求同时发现 Token 过期时，
+ * 只有第一个请求会真正去获取新 Token，其他请求复用同一个 Promise。
+ *
+ * 按 appId 隔离，支持多机器人并发请求。
+ */
+export declare function getAccessToken(appId: string, clientSecret: string): Promise<string>;
+/**
+ * 清除 Token 缓存
+ * @param appId 选填。如果有，只清空特定账号的缓存；如果没有，清空所有账号。
+ */
+export declare function clearTokenCache(appId?: string): void;
+/**
+ * 获取 Token 缓存状态（用于监控）
+ */
+export declare function getTokenStatus(appId: string): {
+    status: "valid" | "expired" | "refreshing" | "none";
+    expiresAt: number | null;
+};
+/**
+ * 获取全局唯一的消息序号（范围 0 ~ 65535）
+ * 使用毫秒级时间戳低位 + 随机数异或混合，无状态，避免碰撞
+ */
+export declare function getNextMsgSeq(_msgId: string): number;
+/**
+ * API 请求封装
+ */
+export declare function apiRequest<T = unknown>(accessToken: string, method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+export declare function getGatewayUrl(accessToken: string): Promise<string>;
+/** 回应按钮交互（INTERACTION_CREATE），避免客户端按钮持续 loading */
+export declare function acknowledgeInteraction(accessToken: string, interactionId: string, code?: 0 | 1 | 2 | 3 | 4 | 5, data?: Record<string, unknown>): Promise<void>;
+/** 获取插件版本号（从 package.json 读取，和 PLUGIN_USER_AGENT 同源） */
+export declare function getApiPluginVersion(): string;
+export interface MessageResponse {
+    id: string;
+    timestamp: number | string;
+    /** 消息的引用索引信息（出站时由 QQ 服务端返回） */
+    ext_info?: {
+        ref_idx?: string;
+    };
+}
+export declare function sendC2CMessage(accessToken: string, openid: string, content: string, msgId?: string, messageReference?: string): Promise<MessageResponse>;
+export declare function sendC2CInputNotify(accessToken: string, openid: string, msgId?: string, inputSecond?: number): Promise<{
+    refIdx?: string;
+}>;
+export declare function sendChannelMessage(accessToken: string, channelId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export declare function sendDmMessage(accessToken: string, guildId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string, messageReference?: string): Promise<MessageResponse>;
+export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
+export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare enum MediaFileType {
+    IMAGE = 1,
+    VIDEO = 2,
+    VOICE = 3,
+    FILE = 4
+}
+export interface UploadMediaResponse {
+    file_uuid: string;
+    file_info: string;
+    ttl: number;
+    id?: string;
+}
+/** 分片信息 */
+export interface UploadPart {
+    /** 分片索引（从 1 开始） */
+    index: number;
+    /** 预签名上传链接 */
+    presigned_url: string;
+}
+/** 申请上传响应 */
+export interface UploadPrepareResponse {
+    /** 上传任务 ID */
+    upload_id: string;
+    /** 分块大小（字节） */
+    block_size: number;
+    /** 分片列表（含预签名链接） */
+    parts: UploadPart[];
+}
+/** 完成文件上传响应（与 UploadMediaResponse 一致） */
+export interface MediaUploadResponse {
+    /** 文件 UUID */
+    file_uuid: string;
+    /** 文件信息（用于发送消息），是 InnerUploadRsp 的序列化 */
+    file_info: string;
+    /** 文件信息过期时长（秒） */
+    ttl: number;
+}
+/** 申请上传时的文件哈希信息 */
+export interface UploadPrepareHashes {
+    /** 整个文件的 MD5（十六进制） */
+    md5: string;
+    /** 整个文件的 SHA1（十六进制） */
+    sha1: string;
+    /** 文件前 10002432 Bytes 的 MD5（十六进制）；文件不足该大小时为整文件 MD5 */
+    md5_10m: string;
+}
+/**
+ * 申请上传（C2C）
+ * POST /v2/users/{user_id}/upload_prepare
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param fileType - 业务类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param fileName - 文件名
+ * @param fileSize - 文件大小（字节）
+ * @param hashes - 文件哈希信息（md5, sha1, md5_10m）
+ * @returns 上传任务 ID、分块大小、分片预签名链接列表
+ */
+export declare function c2cUploadPrepare(accessToken: string, userId: string, fileType: MediaFileType, fileName: string, fileSize: number, hashes: UploadPrepareHashes): Promise<UploadPrepareResponse>;
+/**
+ * 完成分片上传（C2C）
+ * POST /v2/users/{user_id}/upload_part_finish
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @param partIndex - 分片索引（从 1 开始）
+ * @param blockSize - 分块大小（字节）
+ * @param md5 - 分片数据的 MD5（十六进制）
+ */
+export declare function c2cUploadPartFinish(accessToken: string, userId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+/**
+ * 完成文件上传（C2C）
+ * POST /v2/users/{user_id}/files
+ *
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @returns 文件信息（file_uuid, file_info, ttl）
+ */
+export declare function c2cCompleteUpload(accessToken: string, userId: string, uploadId: string): Promise<MediaUploadResponse>;
+/**
+ * 申请上传（Group）
+ * POST /v2/groups/{group_id}/upload_prepare
+ */
+export declare function groupUploadPrepare(accessToken: string, groupId: string, fileType: MediaFileType, fileName: string, fileSize: number, hashes: UploadPrepareHashes): Promise<UploadPrepareResponse>;
+/**
+ * 完成分片上传（Group）
+ * POST /v2/groups/{group_id}/upload_part_finish
+ */
+export declare function groupUploadPartFinish(accessToken: string, groupId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+/**
+ * 完成文件上传（Group）
+ * POST /v2/groups/{group_id}/files
+ */
+export declare function groupCompleteUpload(accessToken: string, groupId: string, uploadId: string): Promise<MediaUploadResponse>;
+export declare function uploadC2CMedia(accessToken: string, openid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+export declare function uploadGroupMedia(accessToken: string, groupOpenid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+export declare function sendC2CMediaMessage(accessToken: string, openid: string, fileInfo: string, msgId?: string, content?: string, meta?: OutboundMeta): Promise<MessageResponse>;
+export declare function sendGroupMediaMessage(accessToken: string, groupOpenid: string, fileInfo: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare function sendC2CImageMessage(accessToken: string, openid: string, imageUrl: string, msgId?: string, content?: string, localPath?: string): Promise<MessageResponse>;
+export declare function sendGroupImageMessage(accessToken: string, groupOpenid: string, imageUrl: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare function sendC2CVoiceMessage(accessToken: string, openid: string, voiceBase64?: string, voiceUrl?: string, msgId?: string, ttsText?: string, filePath?: string): Promise<MessageResponse>;
+export declare function sendGroupVoiceMessage(accessToken: string, groupOpenid: string, voiceBase64?: string, voiceUrl?: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare function sendC2CFileMessage(accessToken: string, openid: string, fileBase64?: string, fileUrl?: string, msgId?: string, fileName?: string, localFilePath?: string): Promise<MessageResponse>;
+export declare function sendGroupFileMessage(accessToken: string, groupOpenid: string, fileBase64?: string, fileUrl?: string, msgId?: string, fileName?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+export declare function sendC2CVideoMessage(accessToken: string, openid: string, videoUrl?: string, videoBase64?: string, msgId?: string, content?: string, localPath?: string): Promise<MessageResponse>;
+export declare function sendGroupVideoMessage(accessToken: string, groupOpenid: string, videoUrl?: string, videoBase64?: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+interface BackgroundTokenRefreshOptions {
+    refreshAheadMs?: number;
+    randomOffsetMs?: number;
+    minRefreshIntervalMs?: number;
+    retryDelayMs?: number;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+export declare function startBackgroundTokenRefresh(appId: string, clientSecret: string, options?: BackgroundTokenRefreshOptions): void;
+/**
+ * 停止后台 Token 刷新
+ * @param appId 选填。如果有，仅停止该账号的定时刷新。
+ */
+export declare function stopBackgroundTokenRefresh(appId?: string): void;
+export declare function isBackgroundTokenRefreshRunning(appId?: string): boolean;
+import type { StreamMessageRequest, StreamMessageResponse } from "./types.js";
+/**
+ * 发送流式消息（C2C 私聊）
+ *
+ * 流式协议：
+ * - 首次调用时不传 stream_msg_id，由平台返回
+ * - 后续分片携带 stream_msg_id 和递增 msg_seq
+ * - input_state="1" 表示生成中，"10" 表示生成结束（终结状态）
+ *
+ * @param accessToken - access_token
+ * @param openid - 用户 openid
+ * @param req - 流式消息请求体
+ * @returns 流式消息响应
+ */
+export declare function sendC2CStreamMessage(accessToken: string, openid: string, req: StreamMessageRequest): Promise<StreamMessageResponse>;
+export {};