@tencent-connect/openclaw-qqbot 1.5.7 → 1.6.0-alpha.1

package/README.md

@@ -6,14 +6,19 @@
 
 # QQ Bot Channel Plugin for OpenClaw
 
+
+
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
+### 🚀 Current Version: `v1.5.7`
+
 [![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/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
 [![Node.js](https://img.shields.io/badge/Node.js->=18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
+
 <br/>
 
 **[简体中文](README.zh.md) | English**
@@ -56,6 +61,8 @@ QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original me
 - Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
 - Quote body may include text + media summary (image/voice/video/file).
 
+<img width="360" src="docs/images/ref_msg.png" alt="Quoted Message Context Demo" />
+
 ### 🎙️ Voice Messages (STT)
 
 With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.
@@ -86,7 +93,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
 
-### 🎨 Image Generation
+### 🎨 Image Sending
 
 > **You**: Draw me a cat
 >
@@ -96,7 +103,7 @@ AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Format
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
 
-### 🔊 Voice Reply (TTS)
+### 🔊 Voice Sending
 
 > **You**: Tell me a joke in voice
 >

package/README.zh.md

@@ -6,8 +6,11 @@
 
 # QQ Bot — OpenClaw 渠道插件
 
+
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
+### 🚀 当前版本： `v1.5.7`
+
 [![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/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
@@ -53,6 +56,8 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 - 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
 - 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
 
+<img width="360" src="docs/images/ref_msg.png" alt="引用消息上下文演示" />
+
 ### 🎙️ 语音消息（STT）
 
 配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
@@ -83,7 +88,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
 
-### 🎨 AI 画图
+### 🎨 图片发送
 
 > **你**：画一只猫咪
 >
@@ -93,7 +98,7 @@ AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
-### 🔊 语音回复（TTS）
+### 🔊 语音发送
 
 > **你**：给我讲一个笑话
 >

package/dist/scripts/upgrade-via-npm.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+
+# qqbot 通过 npm 包升级（纯文件操作版本）
+#
+# 重要：此脚本不修改 openclaw.json 配置文件！
+# 配置更新由调用方（TS handler）在脚本完成后统一处理，
+# 避免 gateway config watcher 在安装过程中触发 SIGUSR1 重启导致竞态。
+#
+# 用法:
+#   upgrade-via-npm.sh                                    # 升级到 latest（默认）
+#   upgrade-via-npm.sh --version <version>                # 升级到指定版本
+#   upgrade-via-npm.sh --self-version                     # 升级到当前仓库 package.json 版本
+
+set -eo pipefail
+
+PKG_NAME="@tencent-connect/openclaw-qqbot"
+INSTALL_SRC=""
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+LOCAL_VERSION="$(node -e "
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const p = path.join('$PROJECT_DIR', 'package.json');
+    const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
+    if (v) process.stdout.write(String(v));
+  } catch {}
+" 2>/dev/null || true)"
+
+print_usage() {
+    echo "用法:"
+    echo "  upgrade-via-npm.sh                              # 升级到 latest（默认）"
+    echo "  upgrade-via-npm.sh --version <版本号>            # 升级到指定版本"
+    if [ -n "$LOCAL_VERSION" ]; then
+        echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本（$LOCAL_VERSION）"
+    else
+        echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本"
+    fi
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --tag)
+            [ -z "$2" ] && echo "❌ --tag 需要参数" && exit 1
+            INSTALL_SRC="${PKG_NAME}@$2"
+            shift 2
+            ;;
+        --version)
+            [ -z "$2" ] && echo "❌ --version 需要参数" && exit 1
+            INSTALL_SRC="${PKG_NAME}@$2"
+            shift 2
+            ;;
+        --self-version)
+            [ -z "$LOCAL_VERSION" ] && echo "❌ 无法从 package.json 读取版本" && exit 1
+            INSTALL_SRC="${PKG_NAME}@${LOCAL_VERSION}"
+            shift 1
+            ;;
+        -h|--help)
+            print_usage
+            exit 0
+            ;;
+        *) echo "未知选项: $1"; print_usage; exit 1 ;;
+    esac
+done
+INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
+
+# 检测 CLI（仅用于确定 extensions 目录路径）
+CMD=""
+for name in openclaw clawdbot moltbot; do
+    command -v "$name" &>/dev/null && CMD="$name" && break
+done
+[ -z "$CMD" ] && echo "❌ 未找到 openclaw / clawdbot / moltbot" && exit 1
+
+EXTENSIONS_DIR="$HOME/.$CMD/extensions"
+
+echo "==========================================="
+echo "  qqbot npm 升级: $INSTALL_SRC"
+echo "==========================================="
+echo ""
+
+# [1/3] 下载并安装新版本到临时目录
+echo "[1/3] 下载新版本..."
+TMPDIR_PACK=$(mktemp -d)
+EXTRACT_DIR=$(mktemp -d)
+trap "rm -rf '$TMPDIR_PACK' '$EXTRACT_DIR'" EXIT
+
+cd "$TMPDIR_PACK"
+npm pack "$INSTALL_SRC" --quiet 2>&1 || { echo "❌ npm pack 失败"; exit 1; }
+TGZ_FILE=$(ls -1 *.tgz 2>/dev/null | head -1)
+[ -z "$TGZ_FILE" ] && echo "❌ 未找到下载的 tgz 文件" && exit 1
+echo "  已下载: $TGZ_FILE"
+
+tar xzf "$TGZ_FILE" -C "$EXTRACT_DIR"
+PACKAGE_DIR="$EXTRACT_DIR/package"
+[ ! -d "$PACKAGE_DIR" ] && echo "❌ 解压失败，未找到 package 目录" && exit 1
+
+# 准备 staging 目录：放在 ~/.openclaw/ 下（extensions 的父目录），
+# 同一文件系统保证 mv 原子操作，同时避免 OpenClaw 扫描 extensions/ 时发现它。
+STAGING_DIR="$(dirname "$EXTENSIONS_DIR")/.qqbot-upgrade-staging"
+rm -rf "$STAGING_DIR"
+mkdir -p "$STAGING_DIR"
+cp -R "$PACKAGE_DIR/"* "$STAGING_DIR/"
+
+# 安装依赖（使用临时缓存目录，避免全局缓存权限问题）
+if [ -f "$STAGING_DIR/package.json" ]; then
+    echo "  安装依赖..."
+    NPM_TMP_CACHE=$(mktemp -d)
+    (cd "$STAGING_DIR" && npm install --omit=dev --cache="$NPM_TMP_CACHE" --quiet 2>&1) || echo "  ⚠️  依赖安装失败（可能无 dependencies）"
+    rm -rf "$NPM_TMP_CACHE"
+fi
+
+# 清理下载临时文件
+rm -rf "$TMPDIR_PACK" "$EXTRACT_DIR"
+cd "$HOME"
+
+# [2/3] 原子替换：先移走旧目录，再把 staging 目录 rename 过去
+# 这样 extensions/openclaw-qqbot 只有极短的不存在时间窗口
+echo ""
+echo "[2/3] 原子替换插件目录..."
+TARGET_DIR="$EXTENSIONS_DIR/openclaw-qqbot"
+OLD_DIR="$(dirname "$EXTENSIONS_DIR")/.qqbot-upgrade-old"
+
+rm -rf "$OLD_DIR"
+if [ -d "$TARGET_DIR" ]; then
+    mv "$TARGET_DIR" "$OLD_DIR"
+fi
+mv "$STAGING_DIR" "$TARGET_DIR"
+rm -rf "$OLD_DIR"
+
+# 清理可能残留的旧版 staging 目录（extensions 内外都清理）
+rm -rf "$EXTENSIONS_DIR/openclaw-qqbot.staging"
+rm -rf "$EXTENSIONS_DIR/.qqbot-upgrade-staging"
+rm -rf "$EXTENSIONS_DIR/.qqbot-upgrade-old"
+
+# 同时清理历史遗留的其他目录名
+for dir_name in qqbot openclaw-qq; do
+    [ -d "$EXTENSIONS_DIR/$dir_name" ] && rm -rf "$EXTENSIONS_DIR/$dir_name"
+done
+echo "  已安装到: $TARGET_DIR"
+
+# [3/3] 输出新版本号和升级报告（供调用方解析）
+echo ""
+echo "[3/3] 验证安装..."
+NEW_VERSION="$(node -e "
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const p = path.join('$EXTENSIONS_DIR', 'openclaw-qqbot', 'package.json');
+    if (fs.existsSync(p)) {
+      const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
+      if (v) { process.stdout.write(v); process.exit(0); }
+    }
+  } catch {}
+" 2>/dev/null || true)"
+echo "QQBOT_NEW_VERSION=${NEW_VERSION:-unknown}"
+
+# 输出结构化升级报告（QQBOT_REPORT=...），供 TS handler 解析后直接回复用户
+if [ -n "$NEW_VERSION" ] && [ "$NEW_VERSION" != "unknown" ]; then
+    echo "QQBOT_REPORT=✅ QQBot 升级完成: v${NEW_VERSION}"
+else
+    echo "QQBOT_REPORT=⚠️ QQBot 升级异常，无法确认新版本"
+fi
+
+echo ""
+echo "==========================================="
+echo "  ✅ 文件安装完成"
+echo "==========================================="

package/dist/src/api.d.ts

@@ -2,6 +2,27 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
+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 配置
  * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
@@ -47,18 +68,21 @@ export declare function getGatewayUrl(accessToken: string): Promise<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): Promise<MessageResponse>;
-export declare function sendC2CInputNotify(accessToken: string, openid: string, msgId?: string, inputSecond?: number): Promise<void>;
+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;
 }>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
-export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<{
-    id: string;
-    timestamp: number;
-}>;
+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;
@@ -77,42 +101,27 @@ export interface UploadMediaResponse {
 }
 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): Promise<{
-    id: string;
-    timestamp: number;
-}>;
+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): Promise<{
-    id: string;
-    timestamp: number;
-}>;
+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, msgId?: string): Promise<{
-    id: string;
-    timestamp: number;
-}>;
-export declare function sendGroupVoiceMessage(accessToken: string, groupOpenid: string, voiceBase64: string, msgId?: string): Promise<{
+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): Promise<{
-    id: string;
-    timestamp: number;
-}>;
+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): Promise<{
-    id: string;
-    timestamp: number;
-}>;
+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;

package/dist/src/api.js

@@ -2,12 +2,33 @@
  * 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";
 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 */ }
+export const PLUGIN_USER_AGENT = `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()})`;
 // 运行时配置
 let currentMarkdownSupport = false;
+let onMessageSentHook = null;
+/**
+ * 注册出站消息回调
+ * 当消息发送成功且 QQ 返回 ref_idx 时，自动回调此函数
+ * 用于在最底层统一缓存 bot 出站消息的 refIdx
+ */
+export function onMessageSent(callback) {
+    onMessageSentHook = callback;
+}
 /**
  * 初始化 API 配置
  * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
@@ -65,7 +86,7 @@ export async function getAccessToken(appId, clientSecret) {
  */
 async function doFetchToken(appId, clientSecret) {
     const requestBody = { appId, clientSecret };
-    const requestHeaders = { "Content-Type": "application/json" };
+    const requestHeaders = { "Content-Type": "application/json", "User-Agent": PLUGIN_USER_AGENT };
     // 打印请求信息（隐藏敏感信息）
     console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
     let response;
@@ -85,7 +106,8 @@ async function doFetchToken(appId, clientSecret) {
     response.headers.forEach((value, key) => {
         responseHeaders[key] = value;
     });
-    console.log(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}`);
+    const tokenTraceId = response.headers.get("x-tps-trace-id") ?? "";
+    console.log(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}${tokenTraceId ? ` | TraceId: ${tokenTraceId}` : ""}`);
     let data;
     let rawBody;
     try {
@@ -160,6 +182,7 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     const headers = {
         Authorization: `QQBot ${accessToken}`,
         "Content-Type": "application/json",
+        "User-Agent": PLUGIN_USER_AGENT,
     };
     const isFileUpload = path.includes("/files");
     const timeout = timeoutMs ?? (isFileUpload ? FILE_UPLOAD_TIMEOUT : DEFAULT_API_TIMEOUT);
@@ -182,6 +205,7 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
         if (typeof logBody.file_data === "string") {
             logBody.file_data = `<base64 ${logBody.file_data.length} chars>`;
         }
+        console.log(`[qqbot-api] >>> Body:`, JSON.stringify(logBody));
     }
     let res;
     try {
@@ -203,11 +227,13 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     res.headers.forEach((value, key) => {
         responseHeaders[key] = value;
     });
-    console.log(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}`);
+    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) {
@@ -248,7 +274,23 @@ export async function getGatewayUrl(accessToken) {
     const data = await apiRequest(accessToken, "GET", "/gateway");
     return data.url;
 }
-function buildMessageBody(content, msgId, msgSeq) {
+/**
+ * 发送消息并自动触发 refIdx 回调
+ * 所有消息发送函数统一经过此处，确保每条出站消息的 refIdx 都被捕获
+ */
+async function sendAndNotify(accessToken, method, path, body, meta) {
+    const result = await apiRequest(accessToken, method, path, body);
+    if (result.ext_info?.ref_idx && onMessageSentHook) {
+        try {
+            onMessageSentHook(result.ext_info.ref_idx, meta);
+        }
+        catch (err) {
+            console.error(`[qqbot-api] onMessageSent hook error: ${err}`);
+        }
+    }
+    return result;
+}
+function buildMessageBody(content, msgId, msgSeq, messageReference) {
     const body = currentMarkdownSupport
         ? {
             markdown: { content },
@@ -263,12 +305,15 @@ function buildMessageBody(content, msgId, msgSeq) {
     if (msgId) {
         body.msg_id = msgId;
     }
+    if (messageReference && !currentMarkdownSupport) {
+        body.message_reference = { message_id: messageReference };
+    }
     return body;
 }
-export async function sendC2CMessage(accessToken, openid, content, msgId) {
+export async function sendC2CMessage(accessToken, openid, content, msgId, messageReference) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
-    const body = buildMessageBody(content, msgId, msgSeq);
-    return apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+    const body = buildMessageBody(content, msgId, msgSeq, messageReference);
+    return sendAndNotify(accessToken, "POST", `/v2/users/${openid}/messages`, body, { text: content });
 }
 export async function sendC2CInputNotify(accessToken, openid, msgId, inputSecond = 60) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
@@ -281,7 +326,8 @@ export async function sendC2CInputNotify(accessToken, openid, msgId, inputSecond
         msg_seq: msgSeq,
         ...(msgId ? { msg_id: msgId } : {}),
     };
-    await apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+    const response = await apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+    return { refIdx: response.ext_info?.ref_idx };
 }
 export async function sendChannelMessage(accessToken, channelId, content, msgId) {
     return apiRequest(accessToken, "POST", `/channels/${channelId}/messages`, {
@@ -307,7 +353,7 @@ function buildProactiveMessageBody(content) {
 }
 export async function sendProactiveC2CMessage(accessToken, openid, content) {
     const body = buildProactiveMessageBody(content);
-    return apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+    return sendAndNotify(accessToken, "POST", `/v2/users/${openid}/messages`, body, { text: content });
 }
 export async function sendProactiveGroupMessage(accessToken, groupOpenid, content) {
     const body = buildProactiveMessageBody(content);
@@ -369,15 +415,15 @@ export async function uploadGroupMedia(accessToken, groupOpenid, fileType, url,
     }
     return result;
 }
-export async function sendC2CMediaMessage(accessToken, openid, fileInfo, msgId, content) {
+export async function sendC2CMediaMessage(accessToken, openid, fileInfo, msgId, content, meta) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
-    return apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, {
+    return sendAndNotify(accessToken, "POST", `/v2/users/${openid}/messages`, {
         msg_type: 7,
         media: { file_info: fileInfo },
         msg_seq: msgSeq,
         ...(content ? { content } : {}),
         ...(msgId ? { msg_id: msgId } : {}),
-    });
+    }, meta ?? { text: content });
 }
 export async function sendGroupMediaMessage(accessToken, groupOpenid, fileInfo, msgId, content) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
@@ -389,9 +435,10 @@ export async function sendGroupMediaMessage(accessToken, groupOpenid, fileInfo,
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
-export async function sendC2CImageMessage(accessToken, openid, imageUrl, msgId, content) {
+export async function sendC2CImageMessage(accessToken, openid, imageUrl, msgId, content, localPath) {
     let uploadResult;
-    if (imageUrl.startsWith("data:")) {
+    const isBase64 = imageUrl.startsWith("data:");
+    if (isBase64) {
         const matches = imageUrl.match(/^data:([^;]+);base64,(.+)$/);
         if (!matches)
             throw new Error("Invalid Base64 Data URL format");
@@ -400,11 +447,18 @@ export async function sendC2CImageMessage(accessToken, openid, imageUrl, msgId,
     else {
         uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.IMAGE, imageUrl, undefined, false);
     }
-    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, content);
+    const meta = {
+        text: content,
+        mediaType: "image",
+        ...(!isBase64 ? { mediaUrl: imageUrl } : {}),
+        ...(localPath ? { mediaLocalPath: localPath } : {}),
+    };
+    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, content, meta);
 }
 export async function sendGroupImageMessage(accessToken, groupOpenid, imageUrl, msgId, content) {
     let uploadResult;
-    if (imageUrl.startsWith("data:")) {
+    const isBase64 = imageUrl.startsWith("data:");
+    if (isBase64) {
         const matches = imageUrl.match(/^data:([^;]+);base64,(.+)$/);
         if (!matches)
             throw new Error("Invalid Base64 Data URL format");
@@ -415,25 +469,29 @@ export async function sendGroupImageMessage(accessToken, groupOpenid, imageUrl,
     }
     return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId, content);
 }
-export async function sendC2CVoiceMessage(accessToken, openid, voiceBase64, msgId) {
-    const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VOICE, undefined, voiceBase64, false);
-    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId);
+export async function sendC2CVoiceMessage(accessToken, openid, voiceBase64, voiceUrl, msgId, ttsText, filePath) {
+    const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VOICE, voiceUrl, voiceBase64, false);
+    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, undefined, {
+        mediaType: "voice",
+        ...(ttsText ? { ttsText } : {}),
+        ...(filePath ? { mediaLocalPath: filePath } : {})
+    });
 }
-export async function sendGroupVoiceMessage(accessToken, groupOpenid, voiceBase64, msgId) {
-    const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.VOICE, undefined, voiceBase64, false);
+export async function sendGroupVoiceMessage(accessToken, groupOpenid, voiceBase64, voiceUrl, msgId) {
+    const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.VOICE, voiceUrl, voiceBase64, false);
     return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId);
 }
-export async function sendC2CFileMessage(accessToken, openid, fileBase64, fileUrl, msgId, fileName) {
+export async function sendC2CFileMessage(accessToken, openid, fileBase64, fileUrl, msgId, fileName, localFilePath) {
     const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.FILE, fileUrl, fileBase64, false, fileName);
-    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId);
+    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, undefined, { mediaType: "file", mediaUrl: fileUrl, mediaLocalPath: localFilePath ?? fileName });
 }
 export async function sendGroupFileMessage(accessToken, groupOpenid, fileBase64, fileUrl, msgId, fileName) {
     const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.FILE, fileUrl, fileBase64, false, fileName);
     return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId);
 }
-export async function sendC2CVideoMessage(accessToken, openid, videoUrl, videoBase64, msgId, content) {
+export async function sendC2CVideoMessage(accessToken, openid, videoUrl, videoBase64, msgId, content, localPath) {
     const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VIDEO, videoUrl, videoBase64, false);
-    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, content);
+    return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, content, { text: content, mediaType: "video", ...(videoUrl ? { mediaUrl: videoUrl } : {}), ...(localPath ? { mediaLocalPath: localPath } : {}) });
 }
 export async function sendGroupVideoMessage(accessToken, groupOpenid, videoUrl, videoBase64, msgId, content) {
     const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.VIDEO, videoUrl, videoBase64, false);

package/dist/src/channel.js

@@ -151,21 +151,21 @@ export const qqbotPlugin = {
             const id = target.replace(/^qqbot:/i, "");
             // 检查是否是已知格式
             if (id.startsWith("c2c:") || id.startsWith("group:") || id.startsWith("channel:")) {
-                return { ok: true, to: `qqbot:${id}` };
+                return `qqbot:${id}`;
             }
             // 检查是否是纯 openid（32位十六进制，不带连字符）
             // QQ Bot OpenID 格式类似: 207A5B8339D01F6582911C014668B77B
             const openIdHexPattern = /^[0-9a-fA-F]{32}$/;
             if (openIdHexPattern.test(id)) {
-                return { ok: true, to: `qqbot:c2c:${id}` };
+                return `qqbot:c2c:${id}`;
             }
             // 检查是否是 UUID 格式的 openid（带连字符）
             const openIdUuidPattern = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
             if (openIdUuidPattern.test(id)) {
-                return { ok: true, to: `qqbot:c2c:${id}` };
+                return `qqbot:c2c:${id}`;
             }
-            // 不认识的格式
-            return { ok: false, error: `unrecognized target format: ${target}` };
+            // 不认识的格式，返回 undefined 让核心使用原始值
+            return undefined;
         },
         /**
          * 目标解析器配置