@sliverp/qqbot 1.3.5 → 1.3.7

package/bin/qqbot-cli.js

@@ -164,8 +164,8 @@ function upgrade() {
   }
 
   console.log('\n=== 升级完成 ===');
-  console.log(`\n可以运行以下命令启动机器人:`);
-  console.log(`  ${foundInstallation} gateway --verbose`);
+  console.log(`\n可以运行以下命令前台运行启动机器人:`);
+  console.log(`  ${foundInstallation} gateway  stop && ${foundInstallation} gateway --port 18789 --verbose`);
 }
 
 // 安装命令

package/clawdbot.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "qqbot",
+  "name": "QQ Bot Channel",
+  "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
+  "channels": ["qqbot"],
+  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "capabilities": {
+    "proactiveMessaging": true,
+    "cronJobs": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

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/src/api.d.ts

@@ -0,0 +1,194 @@
+/**
+ * QQ Bot API 鉴权和请求封装
+ */
+/**
+ * 初始化 API 配置
+ * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
+ */
+export declare function initApiConfig(options: {
+    markdownSupport?: boolean;
+}): void;
+/**
+ * 获取当前是否支持 markdown
+ */
+export declare function isMarkdownSupport(): boolean;
+/**
+ * 获取 AccessToken（带缓存 + singleflight 并发安全）
+ *
+ * 使用 singleflight 模式：当多个请求同时发现 Token 过期时，
+ * 只有第一个请求会真正去获取新 Token，其他请求复用同一个 Promise。
+ */
+export declare function getAccessToken(appId: string, clientSecret: string): Promise<string>;
+/**
+ * 清除 Token 缓存
+ */
+export declare function clearTokenCache(): void;
+/**
+ * 获取 Token 缓存状态（用于监控）
+ */
+export declare function getTokenStatus(): {
+    status: "valid" | "expired" | "refreshing" | "none";
+    expiresAt: number | null;
+};
+/**
+ * 获取并递增消息序号
+ * 返回的 seq 会基于时间戳，避免进程重启后重复
+ */
+export declare function getNextMsgSeq(msgId: string): number;
+/**
+ * API 请求封装
+ */
+export declare function apiRequest<T = unknown>(accessToken: string, method: string, path: string, body?: unknown): Promise<T>;
+/**
+ * 获取 WebSocket Gateway URL
+ */
+export declare function getGatewayUrl(accessToken: string): Promise<string>;
+/**
+ * 消息响应
+ */
+export interface MessageResponse {
+    id: string;
+    timestamp: number | string;
+}
+/**
+ * 发送 C2C 单聊消息
+ */
+export declare function sendC2CMessage(accessToken: string, openid: string, content: string, msgId?: string): Promise<MessageResponse>;
+/**
+ * 发送 C2C 输入状态提示（告知用户机器人正在输入）
+ */
+export declare function sendC2CInputNotify(accessToken: string, openid: string, msgId?: string, inputSecond?: number): Promise<void>;
+/**
+ * 发送频道消息（不支持流式）
+ */
+export declare function sendChannelMessage(accessToken: string, channelId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 发送群聊消息
+ */
+export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
+/**
+ * 主动发送 C2C 单聊消息（不需要 msg_id，每月限 4 条/用户）
+ *
+ * 注意：
+ * 1. 内容不能为空（对应 markdown.content 字段）
+ * 2. 不支持流式发送
+ */
+export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 主动发送群聊消息（不需要 msg_id，每月限 4 条/群）
+ *
+ * 注意：
+ * 1. 内容不能为空（对应 markdown.content 字段）
+ * 2. 不支持流式发送
+ */
+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;
+}
+/**
+ * 上传富媒体文件到 C2C 单聊
+ * @param url - 公网可访问的图片 URL（与 fileData 二选一）
+ * @param fileData - Base64 编码的文件内容（与 url 二选一）
+ */
+export declare function uploadC2CMedia(accessToken: string, openid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+/**
+ * 上传富媒体文件到群聊
+ * @param url - 公网可访问的图片 URL（与 fileData 二选一）
+ * @param fileData - Base64 编码的文件内容（与 url 二选一）
+ */
+export declare function uploadGroupMedia(accessToken: string, groupOpenid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+/**
+ * 发送 C2C 单聊富媒体消息
+ */
+export declare function sendC2CMediaMessage(accessToken: string, openid: string, fileInfo: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 发送群聊富媒体消息
+ */
+export declare function sendGroupMediaMessage(accessToken: string, groupOpenid: string, fileInfo: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 发送带图片的 C2C 单聊消息（封装上传+发送）
+ * @param imageUrl - 图片来源，支持：
+ *   - 公网 URL: https://example.com/image.png
+ *   - Base64 Data URL: data:image/png;base64,xxxxx
+ */
+export declare function sendC2CImageMessage(accessToken: string, openid: string, imageUrl: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 发送带图片的群聊消息（封装上传+发送）
+ * @param imageUrl - 图片来源，支持：
+ *   - 公网 URL: https://example.com/image.png
+ *   - Base64 Data URL: data:image/png;base64,xxxxx
+ */
+export declare function sendGroupImageMessage(accessToken: string, groupOpenid: string, imageUrl: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 后台 Token 刷新配置
+ */
+interface BackgroundTokenRefreshOptions {
+    /** 提前刷新时间（毫秒，默认 5 分钟） */
+    refreshAheadMs?: number;
+    /** 随机偏移范围（毫秒，默认 0-30 秒） */
+    randomOffsetMs?: number;
+    /** 最小刷新间隔（毫秒，默认 1 分钟） */
+    minRefreshIntervalMs?: number;
+    /** 失败后重试间隔（毫秒，默认 5 秒） */
+    retryDelayMs?: number;
+    /** 日志函数 */
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/**
+ * 启动后台 Token 刷新
+ * 在后台定时刷新 Token，避免请求时才发现过期
+ *
+ * @param appId 应用 ID
+ * @param clientSecret 应用密钥
+ * @param options 配置选项
+ */
+export declare function startBackgroundTokenRefresh(appId: string, clientSecret: string, options?: BackgroundTokenRefreshOptions): void;
+/**
+ * 停止后台 Token 刷新
+ */
+export declare function stopBackgroundTokenRefresh(): void;
+/**
+ * 检查后台 Token 刷新是否正在运行
+ */
+export declare function isBackgroundTokenRefreshRunning(): boolean;
+export {};