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

package/dist/src/tools/remind.js

@@ -1,3 +1,4 @@
+import { getRequestTarget } from "../request-context.js";
 // ========== JSON Schema ==========
 const RemindSchema = {
     type: "object",
@@ -13,8 +14,8 @@ const RemindSchema = {
         },
         to: {
             type: "string",
-            description: "投递目标地址，取自上下文中 [QQBot] to= 的值。" +
-                "私聊格式：user_openid，群聊格式：group:group_openid。action=add 时必填。",
+            description: "投递目标地址（可选）。系统会自动从当前会话获取，通常无需手动填写。" +
+                "私聊格式：qqbot:c2c:user_openid，群聊格式：qqbot:group:group_openid。",
         },
         time: {
             type: "string",
@@ -99,9 +100,8 @@ function generateJobName(content) {
 /**
  * 构建一次性提醒的 cron 工具参数
  */
-function buildOnceJob(params, delayMs) {
+function buildOnceJob(params, delayMs, to) {
     const atMs = Date.now() + delayMs;
-    const to = params.to;
     const content = params.content;
     const name = params.name || generateJobName(content);
     return {
@@ -125,8 +125,7 @@ function buildOnceJob(params, delayMs) {
 /**
  * 构建周期提醒的 cron 工具参数
  */
-function buildCronJob(params) {
-    const to = params.to;
+function buildCronJob(params, to) {
     const content = params.content;
     const name = params.name || generateJobName(content);
     const tz = params.timezone || "Asia/Shanghai";
@@ -207,8 +206,10 @@ export function registerRemindTool(api) {
             if (!p.content) {
                 return json({ error: "action=add 时 content（提醒内容）为必填参数" });
             }
-            if (!p.to) {
-                return json({ error: "action=add 时 to（目标地址）为必填参数，取自上下文 [QQBot] to= 的值" });
+            // 优先使用 AI 传入的 to，否则自动从请求级上下文获取（AsyncLocalStorage）
+            const resolvedTo = p.to || getRequestTarget();
+            if (!resolvedTo) {
+                return json({ error: "action=add 时无法确定投递目标地址。请稍后重试。" });
             }
             if (!p.time) {
                 return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
@@ -216,7 +217,7 @@ export function registerRemindTool(api) {
             // 判断是 cron 表达式还是相对时间
             if (isCronExpression(p.time)) {
                 // 周期提醒
-                const cronJob = buildCronJob(p);
+                const cronJob = buildCronJob(p, resolvedTo);
                 return json({
                     _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
                     cronParams: cronJob,
@@ -235,7 +236,7 @@ export function registerRemindTool(api) {
             if (delayMs < 30_000) {
                 return json({ error: "提醒时间不能少于 30 秒" });
             }
-            const onceJob = buildOnceJob(p, delayMs);
+            const onceJob = buildOnceJob(p, delayMs, resolvedTo);
             return json({
                 _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
                 cronParams: onceJob,

package/dist/src/types.d.ts

@@ -68,6 +68,45 @@ export interface QQBotAccountConfig {
      * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
      */
     upgradeMode?: "doc" | "hot-reload";
+    /**
+     * 出站消息合并回复（debounce）配置
+     * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸
+     */
+    deliverDebounce?: DeliverDebounceConfig;
+    /**
+     * 是否启用流式消息（默认 false）
+     * 启用后，AI 的回复会以流式形式逐步显示在 QQ 聊天中，
+     * 用户可以看到文字逐字出现的打字机效果。
+     * 设置为 true 可开启流式消息。
+     *
+     * 注意：仅 C2C（私聊）支持流式消息 API。
+     */
+    streaming?: boolean;
+}
+/**
+ * 出站消息合并回复配置
+ */
+export interface DeliverDebounceConfig {
+    /**
+     * 是否启用合并回复（默认 true）
+     */
+    enabled?: boolean;
+    /**
+     * 合并窗口时长（毫秒），在此时间内的连续 deliver 会被合并
+     * 默认 1500ms
+     */
+    windowMs?: number;
+    /**
+     * 最大等待时长（毫秒），从第一条 deliver 开始计算，超过此时间强制发送
+     * 防止持续有新 deliver 导致一直不发送
+     * 默认 8000ms
+     */
+    maxWaitMs?: number;
+    /**
+     * 合并文本之间的分隔符
+     * 默认 "\n\n---\n\n"
+     */
+    separator?: string;
 }
 /**
  * 音频格式策略：控制哪些格式可跳过转换
@@ -173,3 +212,65 @@ export interface WSPayload {
     s?: number;
     t?: string;
 }
+/** 流式消息输入模式 */
+export declare const StreamInputMode: {
+    /** 每次发送的 content_raw 替换整条消息内容 */
+    readonly REPLACE: "replace";
+};
+export type StreamInputMode = (typeof StreamInputMode)[keyof typeof StreamInputMode];
+/** 流式消息输入状态 */
+export declare const StreamInputState: {
+    /** 正文生成中 */
+    readonly GENERATING: 1;
+    /** 正文生成结束（终结状态） */
+    readonly DONE: 10;
+};
+export type StreamInputState = (typeof StreamInputState)[keyof typeof StreamInputState];
+/** 流式消息内容类型 */
+export declare const StreamContentType: {
+    readonly MARKDOWN: "markdown";
+};
+export type StreamContentType = (typeof StreamContentType)[keyof typeof StreamContentType];
+/**
+ * 流式消息请求体
+ * 对应 StreamReq proto
+ */
+export interface StreamMessageRequest {
+    /** 输入模式 */
+    input_mode: StreamInputMode;
+    /** 输入状态 */
+    input_state: StreamInputState;
+    /** 内容类型 */
+    content_type: StreamContentType;
+    /** markdown 内容 */
+    content_raw: string;
+    /** 事件 ID */
+    event_id: string;
+    /** 原始消息 ID */
+    msg_id: string;
+    /** 流式消息 ID，首次发送后返回，后续分片需携带 */
+    stream_msg_id?: string;
+    /** 递增序号 */
+    msg_seq: number;
+    /** 同一条流式会话内的发送索引，从 0 开始，每次发送前递增；新流式会话重新从 0 开始 */
+    index: number;
+}
+/**
+ * 流式消息响应体
+ * 对应 StreamRsp proto
+ *
+ * 成功时返回：{ id, timestamp, extInfo }（无 code/message）
+ * 失败时返回：{ code, message }（code > 0）
+ */
+export interface StreamMessageResponse {
+    /** 错误码，仅失败时存在（> 0 表示失败）；成功时不存在 */
+    code?: number;
+    /** 错误信息，仅失败时存在 */
+    message?: string;
+    /** 流式消息 ID */
+    id?: string;
+    /** 时间戳 */
+    timestamp?: string;
+    /** 扩展信息 */
+    extInfo?: Record<string, unknown>;
+}

package/dist/src/types.js

@@ -1 +1,17 @@
-export {};
+// ---- 流式消息常量 ----
+/** 流式消息输入模式 */
+export const StreamInputMode = {
+    /** 每次发送的 content_raw 替换整条消息内容 */
+    REPLACE: "replace",
+};
+/** 流式消息输入状态 */
+export const StreamInputState = {
+    /** 正文生成中 */
+    GENERATING: 1,
+    /** 正文生成结束（终结状态） */
+    DONE: 10,
+};
+/** 流式消息内容类型 */
+export const StreamContentType = {
+    MARKDOWN: "markdown",
+};

package/dist/src/update-checker.js

@@ -9,6 +9,7 @@
  */
 import { createRequire } from "node:module";
 import https from "node:https";
+import { getPackageVersion } from "./utils/pkg-version.js";
 const require = createRequire(import.meta.url);
 const PKG_NAME = "@tencent-connect/openclaw-qqbot";
 const ENCODED_PKG = encodeURIComponent(PKG_NAME);
@@ -16,14 +17,7 @@ const REGISTRIES = [
     `https://registry.npmjs.org/${ENCODED_PKG}`,
     `https://registry.npmmirror.com/${ENCODED_PKG}`,
 ];
-let CURRENT_VERSION = "unknown";
-try {
-    const pkg = require("../package.json");
-    CURRENT_VERSION = pkg.version ?? "unknown";
-}
-catch {
-    // fallback
-}
+let CURRENT_VERSION = getPackageVersion(import.meta.url);
 let _log;
 function fetchJson(url, timeoutMs) {
     return new Promise((resolve, reject) => {

package/dist/src/utils/audio-convert.d.ts

@@ -72,6 +72,15 @@ export declare function textToSilk(text: string, ttsCfg: TTSConfig, outputDir: s
  * @param directUploadFormats - 自定义直传格式列表，覆盖默认值。传 undefined 使用 QQ_NATIVE_UPLOAD_FORMATS
  */
 export declare function audioFileToSilkBase64(filePath: string, directUploadFormats?: string[]): Promise<string | null>;
+/**
+ * 将音频文件转码为 SILK，**输出到临时文件**（供分片上传使用）。
+ *
+ * 如果文件已经是 QQ 原生格式（WAV/MP3/SILK）或已经是 SILK 编码，
+ * 则直接返回原文件路径（不需要转码）。
+ *
+ * @returns 转码后的文件路径，或 null 表示转码失败
+ */
+export declare function audioFileToSilkFile(filePath: string, directUploadFormats?: string[]): Promise<string | null>;
 /**
  * 等待文件就绪（轮询直到文件出现且大小稳定）
  * 用于 TTS 生成后等待文件写入完成

package/dist/src/utils/audio-convert.js

@@ -434,6 +434,57 @@ export async function audioFileToSilkBase64(filePath, directUploadFormats) {
     console.error(`[audio-convert] unsupported format: ${ext} (no ffmpeg available). ${installHint}`);
     return null;
 }
+/**
+ * 将音频文件转码为 SILK，**输出到临时文件**（供分片上传使用）。
+ *
+ * 如果文件已经是 QQ 原生格式（WAV/MP3/SILK）或已经是 SILK 编码，
+ * 则直接返回原文件路径（不需要转码）。
+ *
+ * @returns 转码后的文件路径，或 null 表示转码失败
+ */
+export async function audioFileToSilkFile(filePath, directUploadFormats) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const buf = fs.readFileSync(filePath);
+    if (buf.length === 0) {
+        console.error(`[audio-convert] file is empty: ${filePath}`);
+        return null;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    // 0. 直传格式 → 直接返回原文件
+    const uploadFormats = directUploadFormats ? normalizeFormats(directUploadFormats) : QQ_NATIVE_UPLOAD_FORMATS;
+    if (uploadFormats.includes(ext)) {
+        console.log(`[audio-convert] direct upload (QQ native format): ${ext} (${buf.length} bytes)`);
+        return filePath;
+    }
+    // 1. 已经是 SILK 编码 → 直接返回原文件
+    if ([".slk", ".slac"].includes(ext)) {
+        const stripped = stripAmrHeader(buf);
+        const raw = new Uint8Array(stripped.buffer, stripped.byteOffset, stripped.byteLength);
+        if (isSilk(raw)) {
+            console.log(`[audio-convert] SILK file, direct use: ${filePath} (${buf.length} bytes)`);
+            return filePath;
+        }
+    }
+    const rawCheck = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    const strippedCheck = stripAmrHeader(buf);
+    const strippedRaw = new Uint8Array(strippedCheck.buffer, strippedCheck.byteOffset, strippedCheck.byteLength);
+    if (isSilk(rawCheck) || isSilk(strippedRaw)) {
+        console.log(`[audio-convert] SILK detected by header: ${filePath} (${buf.length} bytes)`);
+        return filePath;
+    }
+    // 需要转码 → 调用 audioFileToSilkBase64 获取结果，写入临时文件
+    const silkBase64 = await audioFileToSilkBase64(filePath, directUploadFormats);
+    if (!silkBase64)
+        return null;
+    const silkBuffer = Buffer.from(silkBase64, "base64");
+    const os = await import("node:os");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "voice-silk-"));
+    const tmpFile = path.join(tmpDir, `voice${Date.now()}.silk`);
+    fs.writeFileSync(tmpFile, silkBuffer);
+    console.log(`[audio-convert] SILK written to temp file: ${tmpFile} (${silkBuffer.length} bytes)`);
+    return tmpFile;
+}
 /**
  * 等待文件就绪（轮询直到文件出现且大小稳定）
  * 用于 TTS 生成后等待文件写入完成

package/dist/src/utils/chunked-upload.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 大文件分片上传模块
+ *
+ * 流程（对照序列图）：
+ * 1. 申请上传 (upload_prepare) → 获取 upload_id + block_size + 分片预签名链接
+ * 2. 并行上传所有分片：
+ *    对于每个分片 i（并行执行，但分片内部串行）：
+ *      a. 读取文件的第 i 块数据
+ *      b. PUT 到预签名 URL (COS)
+ *      c. 调用 upload_part_finish 通知开放平台分片 i 已完成
+ * 3. 所有分片完成后，调用完成文件上传接口 → 获取 file_info
+ *
+ * 注意：N 个分片之间是并行的，但每个分片的"上传 + 完成"是串行的。
+ */
+import { type MediaFileType, type MediaUploadResponse } from "../api.js";
+/** 分片上传进度回调 */
+export interface ChunkedUploadProgress {
+    /** 当前已完成分片数 */
+    completedParts: number;
+    /** 总分片数 */
+    totalParts: number;
+    /** 已上传字节数 */
+    uploadedBytes: number;
+    /** 总字节数 */
+    totalBytes: number;
+}
+/** 分片上传选项 */
+export interface ChunkedUploadOptions {
+    /** 进度回调 */
+    onProgress?: (progress: ChunkedUploadProgress) => void;
+    /** 最大并发数（默认 5） */
+    maxConcurrent?: number;
+    /** 日志前缀 */
+    logPrefix?: string;
+}
+/**
+ * C2C 大文件分片上传
+ *
+ * @param appId - 应用 ID
+ * @param clientSecret - 应用密钥
+ * @param userId - 用户 openid
+ * @param filePath - 本地文件路径
+ * @param fileType - 文件类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param options - 上传选项
+ * @returns 上传结果（包含 file_info 可直接用于发送消息）
+ */
+export declare function chunkedUploadC2C(appId: string, clientSecret: string, userId: string, filePath: string, fileType: MediaFileType, options?: ChunkedUploadOptions): Promise<MediaUploadResponse>;
+/**
+ * Group 大文件分片上传
+ *
+ * @param appId - 应用 ID
+ * @param clientSecret - 应用密钥
+ * @param groupId - 群 openid
+ * @param filePath - 本地文件路径
+ * @param fileType - 文件类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param options - 上传选项
+ * @returns 上传结果（包含 file_info 可直接用于发送消息）
+ */
+export declare function chunkedUploadGroup(appId: string, clientSecret: string, groupId: string, filePath: string, fileType: MediaFileType, options?: ChunkedUploadOptions): Promise<MediaUploadResponse>;

package/dist/src/utils/chunked-upload.js

@@ -0,0 +1,289 @@
+/**
+ * 大文件分片上传模块
+ *
+ * 流程（对照序列图）：
+ * 1. 申请上传 (upload_prepare) → 获取 upload_id + block_size + 分片预签名链接
+ * 2. 并行上传所有分片：
+ *    对于每个分片 i（并行执行，但分片内部串行）：
+ *      a. 读取文件的第 i 块数据
+ *      b. PUT 到预签名 URL (COS)
+ *      c. 调用 upload_part_finish 通知开放平台分片 i 已完成
+ * 3. 所有分片完成后，调用完成文件上传接口 → 获取 file_info
+ *
+ * 注意：N 个分片之间是并行的，但每个分片的"上传 + 完成"是串行的。
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import { c2cUploadPrepare, c2cUploadPartFinish, c2cCompleteUpload, groupUploadPrepare, groupUploadPartFinish, groupCompleteUpload, getAccessToken, } from "../api.js";
+import { formatFileSize } from "./file-utils.js";
+/** 分片上传并发控制：最多同时上传 N 个分片 */
+const MAX_CONCURRENT_PARTS = 5;
+/** 单个分片上传超时（毫秒）— 5 分钟，兼容低带宽场景 */
+const PART_UPLOAD_TIMEOUT = 300_000;
+/** 单个分片上传最大重试次数 */
+const PART_UPLOAD_MAX_RETRIES = 2;
+/**
+ * C2C 大文件分片上传
+ *
+ * @param appId - 应用 ID
+ * @param clientSecret - 应用密钥
+ * @param userId - 用户 openid
+ * @param filePath - 本地文件路径
+ * @param fileType - 文件类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param options - 上传选项
+ * @returns 上传结果（包含 file_info 可直接用于发送消息）
+ */
+export async function chunkedUploadC2C(appId, clientSecret, userId, filePath, fileType, options) {
+    const prefix = options?.logPrefix ?? "[chunked-upload]";
+    const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
+    // 1. 读取文件信息
+    const stat = await fs.promises.stat(filePath);
+    const fileSize = stat.size;
+    const fileName = filePath.split(/[/\\]/).pop() ?? "file";
+    console.log(`${prefix} Starting chunked upload: file=${fileName}, size=${formatFileSize(fileSize)}, type=${fileType}`);
+    // 2. 计算文件哈希（md5, sha1, md5_10m）
+    console.log(`${prefix} Computing file hashes...`);
+    const hashes = await computeFileHashes(filePath, fileSize);
+    console.log(`${prefix} File hashes: md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m}`);
+    // 3. 申请上传 → 获取 upload_id + block_size + 预签名链接
+    const accessToken = await getAccessToken(appId, clientSecret);
+    console.log(`${prefix} >>> Calling c2cUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
+    const prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+    console.log(`${prefix} <<< c2cUploadPrepare response:`, JSON.stringify(prepareResp));
+    const { upload_id, parts } = prepareResp;
+    // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
+    const block_size = Number(prepareResp.block_size);
+    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+    // 4. 并行上传所有分片（带并发控制）
+    let completedParts = 0;
+    let uploadedBytes = 0;
+    const uploadPart = async (part) => {
+        const partIndex = part.index; // API 返回的 1-based index
+        const partNum = partIndex; // 显示用序号（与 API 一致）
+        // 计算本分片在文件中的偏移和长度（index 是 1-based，需要减 1）
+        const offset = (partIndex - 1) * block_size;
+        const length = Math.min(block_size, fileSize - offset);
+        // 读取分片数据
+        const partBuffer = await readFileChunk(filePath, offset, length);
+        // 计算 MD5
+        const md5Hex = crypto.createHash("md5").update(partBuffer).digest("hex");
+        console.log(`${prefix} Part ${partNum}/${parts.length}: uploading ${formatFileSize(length)} (offset=${offset}, md5=${md5Hex})`);
+        // a. PUT 到预签名 URL（带重试）
+        await putToPresignedUrl(part.presigned_url, partBuffer, prefix, partNum, parts.length);
+        // b. 通知开放平台分片上传完成（需要重新获取 token，避免长时间上传后 token 过期）
+        const token = await getAccessToken(appId, clientSecret);
+        console.log(`${prefix} >>> Calling c2cUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
+        await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex);
+        console.log(`${prefix} <<< c2cUploadPartFinish(partIndex=${partIndex}) done`);
+        // 更新进度
+        completedParts++;
+        uploadedBytes += length;
+        console.log(`${prefix} Part ${partNum}/${parts.length}: completed (${completedParts}/${parts.length})`);
+        if (options?.onProgress) {
+            options.onProgress({
+                completedParts,
+                totalParts: parts.length,
+                uploadedBytes,
+                totalBytes: fileSize,
+            });
+        }
+    };
+    // 并发控制：同时最多执行 maxConcurrent 个分片上传
+    await runWithConcurrency(parts.map(part => () => uploadPart(part)), maxConcurrent);
+    console.log(`${prefix} All ${parts.length} parts uploaded successfully, completing upload...`);
+    // 5. 完成文件上传
+    const finalToken = await getAccessToken(appId, clientSecret);
+    console.log(`${prefix} >>> Calling c2cCompleteUpload(upload_id=${upload_id})`);
+    const result = await c2cCompleteUpload(finalToken, userId, upload_id);
+    console.log(`${prefix} <<< c2cCompleteUpload response:`, JSON.stringify(result));
+    console.log(`${prefix} Upload completed: file_uuid=${result.file_uuid}, ttl=${result.ttl}s`);
+    return result;
+}
+/**
+ * Group 大文件分片上传
+ *
+ * @param appId - 应用 ID
+ * @param clientSecret - 应用密钥
+ * @param groupId - 群 openid
+ * @param filePath - 本地文件路径
+ * @param fileType - 文件类型（1=图片, 2=视频, 3=语音, 4=文件）
+ * @param options - 上传选项
+ * @returns 上传结果（包含 file_info 可直接用于发送消息）
+ */
+export async function chunkedUploadGroup(appId, clientSecret, groupId, filePath, fileType, options) {
+    const prefix = options?.logPrefix ?? "[chunked-upload]";
+    const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
+    // 1. 读取文件信息
+    const stat = await fs.promises.stat(filePath);
+    const fileSize = stat.size;
+    const fileName = filePath.split(/[/\\]/).pop() ?? "file";
+    console.log(`${prefix} Starting chunked upload (group): file=${fileName}, size=${formatFileSize(fileSize)}, type=${fileType}`);
+    // 2. 计算文件哈希（md5, sha1, md5_10m）
+    console.log(`${prefix} Computing file hashes...`);
+    const hashes = await computeFileHashes(filePath, fileSize);
+    console.log(`${prefix} File hashes: md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m}`);
+    // 3. 申请上传
+    const accessToken = await getAccessToken(appId, clientSecret);
+    console.log(`${prefix} >>> Calling groupUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
+    const prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+    console.log(`${prefix} <<< groupUploadPrepare response:`, JSON.stringify(prepareResp));
+    const { upload_id, parts } = prepareResp;
+    // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
+    const block_size = Number(prepareResp.block_size);
+    console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+    // 4. 并行上传所有分片（带并发控制）
+    let completedParts = 0;
+    let uploadedBytes = 0;
+    const uploadPart = async (part) => {
+        const partIndex = part.index; // API 返回的 1-based index
+        const partNum = partIndex; // 显示用序号（与 API 一致）
+        const offset = (partIndex - 1) * block_size;
+        const length = Math.min(block_size, fileSize - offset);
+        const partBuffer = await readFileChunk(filePath, offset, length);
+        const md5Hex = crypto.createHash("md5").update(partBuffer).digest("hex");
+        console.log(`${prefix} Part ${partNum}/${parts.length}: uploading ${formatFileSize(length)} (offset=${offset}, md5=${md5Hex})`);
+        await putToPresignedUrl(part.presigned_url, partBuffer, prefix, partNum, parts.length);
+        const token = await getAccessToken(appId, clientSecret);
+        console.log(`${prefix} >>> Calling groupUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
+        await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex);
+        console.log(`${prefix} <<< groupUploadPartFinish(partIndex=${partIndex}) done`);
+        completedParts++;
+        uploadedBytes += length;
+        console.log(`${prefix} Part ${partNum}/${parts.length}: completed (${completedParts}/${parts.length})`);
+        if (options?.onProgress) {
+            options.onProgress({
+                completedParts,
+                totalParts: parts.length,
+                uploadedBytes,
+                totalBytes: fileSize,
+            });
+        }
+    };
+    await runWithConcurrency(parts.map(part => () => uploadPart(part)), maxConcurrent);
+    console.log(`${prefix} All ${parts.length} parts uploaded successfully, completing upload...`);
+    // 5. 完成文件上传
+    const finalToken = await getAccessToken(appId, clientSecret);
+    console.log(`${prefix} >>> Calling groupCompleteUpload(upload_id=${upload_id})`);
+    const result = await groupCompleteUpload(finalToken, groupId, upload_id);
+    console.log(`${prefix} <<< groupCompleteUpload response:`, JSON.stringify(result));
+    console.log(`${prefix} Upload completed: file_uuid=${result.file_uuid}, ttl=${result.ttl}s`);
+    return result;
+}
+/**
+ * 读取文件的指定区间（分片）
+ */
+async function readFileChunk(filePath, offset, length) {
+    const fd = await fs.promises.open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await fd.read(buffer, 0, length, offset);
+        if (bytesRead < length) {
+            // 文件末尾，返回实际读取的部分
+            return buffer.subarray(0, bytesRead);
+        }
+        return buffer;
+    }
+    finally {
+        await fd.close();
+    }
+}
+/**
+ * PUT 分片数据到预签名 URL（带重试）
+ */
+async function putToPresignedUrl(presignedUrl, data, prefix, partIndex, totalParts) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= PART_UPLOAD_MAX_RETRIES; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), PART_UPLOAD_TIMEOUT);
+            try {
+                // 将 Buffer 转为标准 ArrayBuffer 再包装为 Blob，兼容 bun-types 类型定义
+                const ab = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+                const attemptLabel = attempt > 0 ? ` (retry ${attempt})` : "";
+                console.log(`${prefix} >>> PUT Part ${partIndex}/${totalParts}${attemptLabel}: url=${presignedUrl}, size=${data.length}`);
+                const startTime = Date.now();
+                const response = await fetch(presignedUrl, {
+                    method: "PUT",
+                    body: new Blob([ab]),
+                    headers: {
+                        "Content-Length": String(data.length),
+                    },
+                    signal: controller.signal,
+                });
+                const elapsed = Date.now() - startTime;
+                const etag = response.headers.get("ETag") ?? "-";
+                const requestId = response.headers.get("x-cos-request-id") ?? "-";
+                if (!response.ok) {
+                    const body = await response.text().catch(() => "");
+                    console.error(`${prefix} <<< PUT Part ${partIndex}/${totalParts}: FAILED ${response.status} ${response.statusText} (${elapsed}ms, requestId=${requestId}) body=${body}`);
+                    throw new Error(`COS PUT failed: ${response.status} ${response.statusText} - ${body}`);
+                }
+                console.log(`${prefix} <<< PUT Part ${partIndex}/${totalParts}: ${response.status} OK (${elapsed}ms, ETag=${etag}, requestId=${requestId})`);
+                return; // 成功
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (lastError.name === "AbortError") {
+                lastError = new Error(`Part ${partIndex}/${totalParts} upload timeout after ${PART_UPLOAD_TIMEOUT}ms`);
+            }
+            if (attempt < PART_UPLOAD_MAX_RETRIES) {
+                const delay = 1000 * Math.pow(2, attempt);
+                console.warn(`${prefix} Part ${partIndex}/${totalParts}: attempt ${attempt + 1} failed (${lastError.message}), retrying in ${delay}ms...`);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * 带并发限制的异步任务执行器（批次模式）
+ * 每批最多执行 maxConcurrent 个任务，等全部完成后再启动下一批
+ */
+async function runWithConcurrency(tasks, maxConcurrent) {
+    for (let i = 0; i < tasks.length; i += maxConcurrent) {
+        const batch = tasks.slice(i, i + maxConcurrent);
+        await Promise.all(batch.map(task => task()));
+    }
+}
+// ============ 文件哈希计算 ============
+/** 文件前 N 字节用于计算 md5_10m（与协议定义一致：10002432 Bytes） */
+const MD5_10M_SIZE = 10002432;
+/**
+ * 流式计算文件的 MD5、SHA1、md5_10m（前 10002432 Bytes 的 MD5）
+ * 只遍历文件一次，内存友好
+ */
+async function computeFileHashes(filePath, fileSize) {
+    return new Promise((resolve, reject) => {
+        const md5Hash = crypto.createHash("md5");
+        const sha1Hash = crypto.createHash("sha1");
+        const md5_10mHash = crypto.createHash("md5");
+        let bytesRead = 0;
+        const need10m = fileSize > MD5_10M_SIZE; // 文件超过阈值才需要单独计算 md5_10m
+        const stream = fs.createReadStream(filePath);
+        stream.on("data", (chunk) => {
+            // ReadStream 默认 encoding=null，chunk 一定是 Buffer，但类型声明要求兼容 string
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            md5Hash.update(buf);
+            sha1Hash.update(buf);
+            if (need10m) {
+                const remaining = MD5_10M_SIZE - bytesRead;
+                if (remaining > 0) {
+                    md5_10mHash.update(remaining >= buf.length ? buf : buf.subarray(0, remaining));
+                }
+            }
+            bytesRead += buf.length;
+        });
+        stream.on("end", () => {
+            const md5 = md5Hash.digest("hex");
+            const sha1 = sha1Hash.digest("hex");
+            // 文件不足 MD5_10M_SIZE 时，md5_10m 等于整文件 MD5
+            const md5_10m = need10m ? md5_10mHash.digest("hex") : md5;
+            resolve({ md5, sha1, md5_10m });
+        });
+        stream.on("error", reject);
+    });
+}

package/dist/src/utils/file-utils.d.ts

@@ -1,7 +1,13 @@
 /**
  * 文件操作工具 — 异步读取 + 大小校验 + 进度提示
  */
-/** QQ Bot API 最大上传文件大小：20MB */
+/** QQ Bot API 各类型文件上传大小限制（QQ 机器人上行） */
+export declare const UPLOAD_SIZE_LIMITS: Record<number, number>;
+/** 获取文件类型的中文名称；未知类型返回 "文件" */
+export declare function getFileTypeName(fileType: number): string;
+/** 获取指定文件类型的上传大小限制；未知类型默认 200MB */
+export declare function getMaxUploadSize(fileType: number): number;
+/** @deprecated 使用 getMaxUploadSize(fileType) 代替 */
 export declare const MAX_UPLOAD_SIZE: number;
 /** 大文件阈值（超过此值发送进度提示）：5MB */
 export declare const LARGE_FILE_THRESHOLD: number;