@ryantest/openclaw-qqbot 0.0.2 → 1.6.6-alpha.0

package/src/api.ts

@@ -3,20 +3,32 @@
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
 
-import { createRequire } from "node:module";
 import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
 
+// ============ 自定义错误 ============
+
+/** API 请求错误，携带 HTTP status code */
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly path: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
 const API_BASE = "https://api.sgroup.qq.com";
 const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 
 // ============ Plugin User-Agent ============
 // 格式: QQBotPlugin/{version} (Node/{nodeVersion}; {os})
 // 示例: QQBotPlugin/1.6.0 (Node/22.14.0; darwin)
-const _require = createRequire(import.meta.url);
-let _pluginVersion = "unknown";
-try { _pluginVersion = _require("../package.json").version ?? "unknown"; } catch { /* fallback */ }
+import { getPackageVersion } from "./utils/pkg-version.js";
+const _pluginVersion = getPackageVersion(import.meta.url);
 export const PLUGIN_USER_AGENT = `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()})`;
 
 // 运行时配置
@@ -53,7 +65,6 @@ export function onMessageSent(callback: OnMessageSentCallback): void {
 
 /**
  * 初始化 API 配置
- * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
  */
 export function initApiConfig(options: { markdownSupport?: boolean }): void {
   currentMarkdownSupport = options.markdownSupport === true;
@@ -285,22 +296,48 @@ export async function apiRequest<T = unknown>(
   const traceId = res.headers.get("x-tps-trace-id") ?? "";
   console.log(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`);
 
-  let data: T;
   let rawBody: string;
   try {
     rawBody = await res.text();
-    console.log(`[qqbot-api] <<< Body:`, rawBody);
-    data = JSON.parse(rawBody) as T;
   } catch (err) {
-    throw new Error(`Failed to parse response[${path}]: ${err instanceof Error ? err.message : String(err)}`);
+    throw new Error(`读取响应失败[${path}]: ${err instanceof Error ? err.message : String(err)}`);
   }
+  console.log(`[qqbot-api] <<< Body:`, rawBody);
+
+  // 检测非 JSON 响应（HTML 网关错误页 / CDN 限流页等）
+  const contentType = res.headers.get("content-type") ?? "";
+  const isHtmlResponse = contentType.includes("text/html") || rawBody.trimStart().startsWith("<");
 
   if (!res.ok) {
-    const error = data as { message?: string; code?: number };
-    throw new Error(`API Error [${path}]: ${error.message ?? JSON.stringify(data)}`);
+    if (isHtmlResponse) {
+      // HTML 响应 = 网关/限流层返回的错误页，给出友好提示
+      const statusHint = res.status === 502 || res.status === 503 || res.status === 504
+        ? "调用发生异常，请稍候重试"
+        : res.status === 429
+          ? "请求过于频繁，已被限流"
+          : `开放平台返回 HTTP ${res.status}`;
+      throw new ApiError(`${statusHint}（${path}），请稍后重试`, res.status, path);
+    }
+    // JSON 错误响应
+    try {
+      const error = JSON.parse(rawBody) as { message?: string; code?: number };
+      throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path);
+    } catch (parseErr) {
+      if (parseErr instanceof ApiError) throw parseErr;
+      throw new ApiError(`API Error [${path}] HTTP ${res.status}: ${rawBody.slice(0, 200)}`, res.status, path);
+    }
   }
 
-  return data;
+  // 成功响应但不是 JSON（极端异常情况）
+  if (isHtmlResponse) {
+    throw new Error(`QQ 服务端返回了非 JSON 响应（${path}），可能是临时故障，请稍后重试`);
+  }
+
+  try {
+    return JSON.parse(rawBody) as T;
+  } catch {
+    throw new Error(`开放平台响应格式异常（${path}），请稍后重试`);
+  }
 }
 
 // ============ 上传重试（指数退避） ============
@@ -342,6 +379,40 @@ async function apiRequestWithRetry<T = unknown>(
   throw lastError!;
 }
 
+// ============ 完成上传重试（无条件，任何错误都重试） ============
+
+const COMPLETE_UPLOAD_MAX_RETRIES = 2;
+const COMPLETE_UPLOAD_BASE_DELAY_MS = 2000;
+
+/**
+ * 完成上传专用重试：无条件重试所有错误（包括 4xx、5xx、网络错误、超时等）
+ * 分片上传完成接口的失败往往是平台侧异步处理未就绪，重试通常能成功
+ */
+async function completeUploadWithRetry(
+  accessToken: string,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<MediaUploadResponse> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= COMPLETE_UPLOAD_MAX_RETRIES; attempt++) {
+    try {
+      return await apiRequest<MediaUploadResponse>(accessToken, method, path, body);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (attempt < COMPLETE_UPLOAD_MAX_RETRIES) {
+        const delay = COMPLETE_UPLOAD_BASE_DELAY_MS * Math.pow(2, attempt);
+        console.warn(`[qqbot-api] CompleteUpload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
 export async function getGatewayUrl(accessToken: string): Promise<string> {
   const data = await apiRequest<{ url: string }>(accessToken, "GET", "/gateway");
   return data.url;
@@ -524,6 +595,168 @@ export interface UploadMediaResponse {
   id?: string;
 }
 
+// ============ 大文件分片上传 API ============
+
+/** 分片信息 */
+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 async function c2cUploadPrepare(
+  accessToken: string,
+  userId: string,
+  fileType: MediaFileType,
+  fileName: string,
+  fileSize: number,
+  hashes: UploadPrepareHashes,
+): Promise<UploadPrepareResponse> {
+  return apiRequest<UploadPrepareResponse>(
+    accessToken, "POST", `/v2/users/${userId}/upload_prepare`,
+    { file_type: fileType, file_name: fileName, file_size: fileSize, md5: hashes.md5, sha1: hashes.sha1, md5_10m: hashes.md5_10m },
+  );
+}
+
+/**
+ * 完成分片上传（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 async function c2cUploadPartFinish(
+  accessToken: string,
+  userId: string,
+  uploadId: string,
+  partIndex: number,
+  blockSize: number,
+  md5: string,
+): Promise<void> {
+  await apiRequest<Record<string, unknown>>(
+    accessToken, "POST", `/v2/users/${userId}/upload_part_finish`,
+    { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 },
+  );
+}
+
+/**
+ * 完成文件上传（C2C）
+ * POST /v2/users/{user_id}/files
+ * 
+ * @param accessToken - 访问令牌
+ * @param userId - 用户 openid
+ * @param uploadId - 上传任务 ID
+ * @returns 文件信息（file_uuid, file_info, ttl）
+ */
+export async function c2cCompleteUpload(
+  accessToken: string,
+  userId: string,
+  uploadId: string,
+): Promise<MediaUploadResponse> {
+  return completeUploadWithRetry(
+    accessToken, "POST", `/v2/users/${userId}/files`,
+    { upload_id: uploadId },
+  );
+}
+
+/**
+ * 申请上传（Group）
+ * POST /v2/groups/{group_id}/upload_prepare
+ */
+export async function groupUploadPrepare(
+  accessToken: string,
+  groupId: string,
+  fileType: MediaFileType,
+  fileName: string,
+  fileSize: number,
+  hashes: UploadPrepareHashes,
+): Promise<UploadPrepareResponse> {
+  return apiRequest<UploadPrepareResponse>(
+    accessToken, "POST", `/v2/groups/${groupId}/upload_prepare`,
+    { file_type: fileType, file_name: fileName, file_size: fileSize, md5: hashes.md5, sha1: hashes.sha1, md5_10m: hashes.md5_10m },
+  );
+}
+
+/**
+ * 完成分片上传（Group）
+ * POST /v2/groups/{group_id}/upload_part_finish
+ */
+export async function groupUploadPartFinish(
+  accessToken: string,
+  groupId: string,
+  uploadId: string,
+  partIndex: number,
+  blockSize: number,
+  md5: string,
+): Promise<void> {
+  await apiRequest<Record<string, unknown>>(
+    accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`,
+    { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 },
+  );
+}
+
+/**
+ * 完成文件上传（Group）
+ * POST /v2/groups/{group_id}/files
+ */
+export async function groupCompleteUpload(
+  accessToken: string,
+  groupId: string,
+  uploadId: string,
+): Promise<MediaUploadResponse> {
+  return completeUploadWithRetry(
+    accessToken, "POST", `/v2/groups/${groupId}/files`,
+    { upload_id: uploadId },
+  );
+}
+
 export async function uploadC2CMedia(
   accessToken: string,
   openid: string,
@@ -817,3 +1050,42 @@ async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
     }
   });
 }
+
+// ============ 流式消息 API ============
+
+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 async function sendC2CStreamMessage(
+  accessToken: string,
+  openid: string,
+  req: StreamMessageRequest,
+): Promise<StreamMessageResponse> {
+  const path = `/v2/users/${openid}/stream_messages`;
+  const body: Record<string, unknown> = {
+    input_mode: req.input_mode,
+    input_state: req.input_state,
+    content_type: req.content_type,
+    content_raw: req.content_raw,
+    event_id: req.event_id,
+    msg_id: req.msg_id,
+    msg_seq: req.msg_seq,
+    index: req.index,
+  };
+  if (req.stream_msg_id) {
+    body.stream_msg_id = req.stream_msg_id;
+  }
+  return apiRequest<StreamMessageResponse>(accessToken, "POST", path, body);
+}

package/src/channel.ts

@@ -240,6 +240,18 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
       console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
       const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
       console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
+      // 此 sendMedia 是框架 Channel Plugin 的标准出站接口，
+      // 用于非 gateway deliver 场景（如 API 直接发送、cron 等）。
+      // gateway 消息响应走的是 deliver 回调 → sendPlainReply，不经过此处。
+      // 框架拿到 error 后不一定会给用户发文字兜底，所以这里主动发一条。
+      if (result.error) {
+        try {
+          const fallbackResult = await sendText({ to, text: result.error, accountId, replyToId, account });
+          console.log(`[qqbot:channel] sendMedia fallback text sent: messageId=${fallbackResult.messageId}, error=${fallbackResult.error ?? "none"}`);
+        } catch (fallbackErr) {
+          console.error(`[qqbot:channel] sendMedia fallback text failed: ${fallbackErr}`);
+        }
+      }
       return {
         channel: "qqbot",
         messageId: result.messageId,

package/src/config.ts

@@ -70,17 +70,10 @@ export function resolveQQBotAccount(
   let secretSource: "config" | "file" | "env" | "none" = "none";
 
   if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
-    // 默认账户从顶层读取
+    // 默认账户从顶层读取（展开所有字段，避免遗漏新增配置项）
+    const { accounts: _accounts, ...topLevelConfig } = qqbot ?? {} as QQBotChannelConfig;
     accountConfig = {
-      enabled: qqbot?.enabled,
-      name: qqbot?.name,
-      appId: qqbot?.appId,
-      clientSecret: qqbot?.clientSecret,
-      clientSecretFile: qqbot?.clientSecretFile,
-      dmPolicy: qqbot?.dmPolicy,
-      allowFrom: qqbot?.allowFrom,
-      systemPrompt: qqbot?.systemPrompt,
-      imageServerBaseUrl: qqbot?.imageServerBaseUrl,
+      ...topLevelConfig,
       markdownSupport: qqbot?.markdownSupport ?? true,
     };
     appId = normalizeAppId(qqbot?.appId);

package/src/deliver-debounce.ts

@@ -0,0 +1,229 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+
+import type { DeliverDebounceConfig } from "./types.js";
+
+// ============ 默认值 ============
+
+const DEFAULT_WINDOW_MS = 1500;
+const DEFAULT_MAX_WAIT_MS = 8000;
+const DEFAULT_SEPARATOR = "\n\n---\n\n";
+
+// ============ 类型定义 ============
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrls?: string[];
+  mediaUrl?: string;
+}
+
+export interface DeliverInfo {
+  kind: string;
+}
+
+/** 实际执行发送的回调 */
+export type DeliverExecutor = (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+
+// ============ DeliverDebouncer 类 ============
+
+export class DeliverDebouncer {
+  private readonly windowMs: number;
+  private readonly maxWaitMs: number;
+  private readonly separator: string;
+  private readonly executor: DeliverExecutor;
+  private readonly log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+  private readonly prefix: string;
+
+  /** 缓冲中的文本片段 */
+  private bufferedTexts: string[] = [];
+  /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+  private lastInfo: DeliverInfo | null = null;
+  /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+  private lastPayload: DeliverPayload | null = null;
+  /** debounce 定时器 */
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  /** 最大等待定时器（从第一条 deliver 开始计算） */
+  private maxWaitTimer: ReturnType<typeof setTimeout> | null = null;
+  /** 是否正在 flush */
+  private flushing = false;
+  /** 已销毁标记 */
+  private disposed = false;
+
+  constructor(
+    config: DeliverDebounceConfig | undefined,
+    executor: DeliverExecutor,
+    log?: { info: (msg: string) => void; error: (msg: string) => void },
+    prefix = "[debounce]",
+  ) {
+    this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    this.separator = config?.separator ?? DEFAULT_SEPARATOR;
+    this.executor = executor;
+    this.log = log;
+    this.prefix = prefix;
+  }
+
+  /**
+   * 接收一次 deliver 调用。
+   * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+   * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+   */
+  async deliver(payload: DeliverPayload, info: DeliverInfo): Promise<void> {
+    if (this.disposed) return;
+
+    const hasMedia = Boolean(
+      (payload.mediaUrls && payload.mediaUrls.length > 0) || payload.mediaUrl,
+    );
+    const text = (payload.text ?? "").trim();
+
+    // 含媒体的 deliver：立即 flush 缓冲 + 直接执行
+    if (hasMedia) {
+      this.log?.info(`${this.prefix} Media deliver detected, flushing ${this.bufferedTexts.length} buffered text(s) first`);
+      await this.flush();
+      await this.executor(payload, info);
+      return;
+    }
+
+    // 空文本 deliver：直接透传（不缓冲）
+    if (!text) {
+      await this.executor(payload, info);
+      return;
+    }
+
+    // 纯文本 deliver：缓冲
+    this.bufferedTexts.push(text);
+    this.lastInfo = info;
+    this.lastPayload = payload;
+
+    this.log?.info(
+      `${this.prefix} Buffered text #${this.bufferedTexts.length} (${text.length} chars), window=${this.windowMs}ms`,
+    );
+
+    // 重置 debounce 定时器
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.flush().catch((err) => {
+        this.log?.error(`${this.prefix} Flush error (debounce timer): ${err}`);
+      });
+    }, this.windowMs);
+
+    // 首次缓冲时启动最大等待定时器
+    if (this.bufferedTexts.length === 1) {
+      if (this.maxWaitTimer) {
+        clearTimeout(this.maxWaitTimer);
+      }
+      this.maxWaitTimer = setTimeout(() => {
+        this.log?.info(`${this.prefix} Max wait (${this.maxWaitMs}ms) reached, force flushing`);
+        this.flush().catch((err) => {
+          this.log?.error(`${this.prefix} Flush error (max wait timer): ${err}`);
+        });
+      }, this.maxWaitMs);
+    }
+  }
+
+  /**
+   * 将缓冲中的文本合并为一条消息发送
+   */
+  async flush(): Promise<void> {
+    if (this.flushing || this.bufferedTexts.length === 0) return;
+    this.flushing = true;
+
+    // 清除定时器
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+
+    // 取出缓冲
+    const texts = this.bufferedTexts;
+    const info = this.lastInfo!;
+    const lastPayload = this.lastPayload!;
+    this.bufferedTexts = [];
+    this.lastInfo = null;
+    this.lastPayload = null;
+
+    try {
+      if (texts.length === 1) {
+        // 只有一条，直接透传原始 payload
+        this.log?.info(`${this.prefix} Flushing single buffered text (${texts[0].length} chars)`);
+        await this.executor({ ...lastPayload, text: texts[0] }, info);
+      } else {
+        // 多条合并
+        const merged = texts.join(this.separator);
+        this.log?.info(
+          `${this.prefix} Merged ${texts.length} buffered texts into one (${merged.length} chars)`,
+        );
+        await this.executor({ ...lastPayload, text: merged }, info);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /**
+   * 销毁：flush 剩余缓冲并清除定时器
+   */
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+    // flush 剩余
+    if (this.bufferedTexts.length > 0) {
+      this.flushing = false; // 确保 flush 能执行
+      await this.flush();
+    }
+  }
+
+  /** 当前是否有缓冲中的文本 */
+  get hasPending(): boolean {
+    return this.bufferedTexts.length > 0;
+  }
+
+  /** 缓冲中的文本数量 */
+  get pendingCount(): number {
+    return this.bufferedTexts.length;
+  }
+}
+
+// ============ 工厂函数 ============
+
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export function createDeliverDebouncer(
+  config: DeliverDebounceConfig | undefined,
+  executor: DeliverExecutor,
+  log?: { info: (msg: string) => void; error: (msg: string) => void },
+  prefix?: string,
+): DeliverDebouncer | null {
+  // 未配置时默认启用
+  if (config?.enabled === false) {
+    return null;
+  }
+  return new DeliverDebouncer(config, executor, log, prefix);
+}