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

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.4`
+### 🚀 Current Version: `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -183,24 +183,11 @@ Shows framework version, plugin version, and a direct link to the official repos
 >
 > **QQBot**: 📌 Current: v1.6.3 / ✅ New version v1.6.4 available / Click button below to confirm
 
-Send in private chat to upgrade the plugin without server login. Supported usage:
-
-| Command | Description |
-|---------|-------------|
-| `/bot-upgrade` | Check for updates, show confirmation button |
-| `/bot-upgrade --latest` | Confirm upgrade to the latest version |
-| `/bot-upgrade --version 1.6.4` | Upgrade to a specific version |
-| `/bot-upgrade --force` | Force reinstall current version |
-
 Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.
 
-<<<<<<< Updated upstream
-<!-- TODO: add /bot-upgrade screenshot -->
-=======
-> **Platform Support:** Hot upgrade is currently supported on **Linux** and **macOS**. On Windows, `/bot-upgrade` will return a manual upgrade guide instead.
+> ⚠️ Hot upgrade is currently not supported on Windows. Sending `/bot-upgrade` on Windows will return a manual upgrade guide instead.
 
 <img width="360" src="docs/images/hot-update.jpg" alt="Hot Upgrade Demo" />
->>>>>>> Stashed changes
 
 #### `/bot-logs` — Log Export
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.4`
+### 🚀 当前版本： `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -178,24 +178,11 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 >
 > **QQBot**：📌当前版本 v1.6.3 / ✅发现新版本 v1.6.4 / 点击下方按钮确认升级
 
-在私聊中发送即可完成版本升级，全程无需登录服务器。支持的用法：
-
-| 命令 | 说明 |
-|------|------|
-| `/bot-upgrade` | 检查是否有新版本，展示确认按钮 |
-| `/bot-upgrade --latest` | 确认升级到最新版本 |
-| `/bot-upgrade --version 1.6.4` | 升级到指定版本 |
-| `/bot-upgrade --force` | 强制重新安装当前版本 |
-
 升级流程自动备份凭证，升级前校验版本是否存在于 npm，升级失败自动恢复。
 
-<<<<<<< Updated upstream
-<!-- TODO: 补充 /bot-upgrade 截图 -->
-=======
-> **平台支持：** 热更新目前支持 **Linux** 和 **macOS**。Windows 暂不支持热更，发送 `/bot-upgrade` 后会返回手动升级指引。
+> ⚠️ 热更新指令暂不支持 Windows 系统，在 Windows 上发送 `/bot-upgrade` 会返回手动升级指引。
 
-<img width="360" src="docs/images/hot-update.jpg" alt="热更新演示" />
->>>>>>> Stashed changes
+<img width="360" src="docs/images/hot-update.jpg" alt="一键热更新演示" />
 
 #### `/bot-logs` — 日志导出
 

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

@@ -13,15 +13,21 @@ export interface AdminResolverContext {
         error: (msg: string) => void;
     };
 }
-export declare function loadAdminOpenId(accountId: string): string | undefined;
-export declare function saveAdminOpenId(accountId: string, openid: string): void;
-export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string): string | undefined;
+/**
+ * 读取 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. 优先读持久化文件（稳定）
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
  * 2. fallback 取第一个私聊用户，并写入文件锁定
  */
-export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined;
-/** 异步发送启动问候语（仅发给管理员） */
+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

@@ -11,49 +11,86 @@ import { listKnownUsers } from "./known-users.js";
 import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
 import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
 // ---- 文件路径 ----
-function getAdminMarkerFile(accountId) {
+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) {
-    const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
-    const safeAppId = appId.replace(/[^a-zA-Z0-9._-]/g, "_");
-    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeAccountId}-${safeAppId}.json`);
+    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeName(accountId)}-${safeName(appId)}.json`);
 }
 // ---- 管理员 openid 持久化 ----
-export function loadAdminOpenId(accountId) {
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export function loadAdminOpenId(accountId, appId) {
     try {
-        const file = getAdminMarkerFile(accountId);
-        if (fs.existsSync(file)) {
-            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        // 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, openid) {
+export function saveAdminOpenId(accountId, appId, openid) {
     try {
-        fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+        fs.writeFileSync(getAdminMarkerFile(accountId, appId), JSON.stringify({ accountId, appId, openid, savedAt: new Date().toISOString() }));
     }
     catch { /* ignore */ }
 }
 // ---- 升级问候目标 ----
-export function loadUpgradeGreetingTargetOpenId(accountId, appId) {
+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)
+            if (!data.openid) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target file found but openid is empty`);
                 return undefined;
-            if (data.appId && data.appId !== appId)
+            }
+            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)
+            }
+            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}`);
     }
-    catch { /* 文件损坏视为无 */ }
     return undefined;
 }
 export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
@@ -68,54 +105,52 @@ export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
 // ---- 解析管理员 ----
 /**
  * 解析管理员 openid：
- * 1. 优先读持久化文件（稳定）
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
  * 2. fallback 取第一个私聊用户，并写入文件锁定
  */
 export function resolveAdminOpenId(ctx) {
-    const saved = loadAdminOpenId(ctx.accountId);
+    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, 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();
+        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);
-        const targetOpenId = upgradeTargetOpenId || resolveAdminOpenId(ctx);
-        if (!targetOpenId) {
-            markStartupGreetingFailed(plan.version, "no-admin");
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (no admin or known user)`);
+        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 {
-            const receiverType = upgradeTargetOpenId ? "upgrade-requester" : "admin";
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Sending startup greeting to ${receiverType} (trigger=${trigger}): "${plan.greeting}"`);
+            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, targetOpenId, plan.greeting),
+                sendProactiveC2CMessage(token, upgradeTargetOpenId, plan.greeting),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
             ]);
-            markStartupGreetingSent(plan.version);
-            if (upgradeTargetOpenId) {
-                clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
-            }
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to ${receiverType}: ${targetOpenId}`);
+            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(plan.version, message);
+            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

@@ -2,6 +2,12 @@
  * 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 {
@@ -25,7 +31,6 @@ type OnMessageSentCallback = (refIdx: string, meta: OutboundMeta) => void;
 export declare function onMessageSent(callback: OnMessageSentCallback): void;
 /**
  * 初始化 API 配置
- * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
  */
 export declare function initApiConfig(options: {
     markdownSupport?: boolean;
@@ -108,6 +113,90 @@ export interface UploadMediaResponse {
     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>;
@@ -153,4 +242,19 @@ export declare function startBackgroundTokenRefresh(appId: string, clientSecret:
  */
 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 {};

package/dist/src/api.js

@@ -2,21 +2,28 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
-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 {
+    status;
+    path;
+    constructor(message, status, path) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        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()})`;
 // 运行时配置
 let currentMarkdownSupport = false;
@@ -31,7 +38,6 @@ export function onMessageSent(callback) {
 }
 /**
  * 初始化 API 配置
- * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
  */
 export function initApiConfig(options) {
     currentMarkdownSupport = options.markdownSupport === true;
@@ -234,21 +240,48 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     });
     const traceId = res.headers.get("x-tps-trace-id") ?? "";
     console.log(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`);
-    let data;
     let rawBody;
     try {
         rawBody = await res.text();
-        console.log(`[qqbot-api] <<< Body:`, rawBody);
-        data = JSON.parse(rawBody);
     }
     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;
-        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);
+            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);
+        }
+    }
+    // 成功响应但不是 JSON（极端异常情况）
+    if (isHtmlResponse) {
+        throw new Error(`QQ 服务端返回了非 JSON 响应（${path}），可能是临时故障，请稍后重试`);
+    }
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        throw new Error(`开放平台响应格式异常（${path}），请稍后重试`);
     }
-    return data;
 }
 // ============ 上传重试（指数退避） ============
 const UPLOAD_MAX_RETRIES = 2;
@@ -275,6 +308,51 @@ async function apiRequestWithRetry(accessToken, method, path, body, maxRetries =
     }
     throw lastError;
 }
+// ============ 完成上传重试（无条件，任何错误都重试） ============
+const COMPLETE_UPLOAD_MAX_RETRIES = 2;
+const COMPLETE_UPLOAD_BASE_DELAY_MS = 2000;
+/**
+ * 完成上传专用重试：无条件重试所有错误（包括 4xx、5xx、网络错误、超时等）
+ * 分片上传完成接口的失败往往是平台侧异步处理未就绪，重试通常能成功
+ */
+async function completeUploadWithRetry(accessToken, method, path, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= COMPLETE_UPLOAD_MAX_RETRIES; attempt++) {
+        try {
+            return await apiRequest(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;
+}
+// ============ 分片完成重试（无条件，与 completeUpload 策略一致） ============
+const PART_FINISH_MAX_RETRIES = 2;
+const PART_FINISH_BASE_DELAY_MS = 1000;
+async function partFinishWithRetry(accessToken, method, path, body) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= PART_FINISH_MAX_RETRIES; attempt++) {
+        try {
+            await apiRequest(accessToken, method, path, body);
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < PART_FINISH_MAX_RETRIES) {
+                const delay = PART_FINISH_BASE_DELAY_MS * Math.pow(2, attempt);
+                console.warn(`[qqbot-api] PartFinish 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) {
     const data = await apiRequest(accessToken, "GET", "/gateway");
     return data.url;
@@ -383,6 +461,68 @@ export var MediaFileType;
     MediaFileType[MediaFileType["VOICE"] = 3] = "VOICE";
     MediaFileType[MediaFileType["FILE"] = 4] = "FILE";
 })(MediaFileType || (MediaFileType = {}));
+/**
+ * 申请上传（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, userId, fileType, fileName, fileSize, hashes) {
+    return apiRequest(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, userId, uploadId, partIndex, blockSize, md5) {
+    await partFinishWithRetry(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, userId, uploadId) {
+    return completeUploadWithRetry(accessToken, "POST", `/v2/users/${userId}/files`, { upload_id: uploadId });
+}
+/**
+ * 申请上传（Group）
+ * POST /v2/groups/{group_id}/upload_prepare
+ */
+export async function groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes) {
+    return apiRequest(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, groupId, uploadId, partIndex, blockSize, md5) {
+    await partFinishWithRetry(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, groupId, uploadId) {
+    return completeUploadWithRetry(accessToken, "POST", `/v2/groups/${groupId}/files`, { upload_id: uploadId });
+}
 export async function uploadC2CMedia(accessToken, openid, fileType, url, fileData, srvSendMsg = false, fileName) {
     if (!url && !fileData)
         throw new Error("uploadC2CMedia: url or fileData is required");
@@ -597,3 +737,33 @@ async function sleep(ms, signal) {
         }
     });
 }
+/**
+ * 发送流式消息（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, openid, req) {
+    const path = `/v2/users/${openid}/stream_messages`;
+    const body = {
+        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(accessToken, "POST", path, body);
+}