@tencent-connect/openclaw-qqbot 1.5.6 → 1.5.7

package/src/api.ts

@@ -12,6 +12,35 @@ const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 // 运行时配置
 let currentMarkdownSupport = false;
 
+// 出站消息回调钩子：消息发送成功且回包含 ext_info.ref_idx 时触发
+// 由外层（gateway/outbound）注册，用于统一缓存 bot 出站消息的 refIdx
+
+/** 出站消息元信息（结构化存储，不做预格式化） */
+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;
+let onMessageSentHook: OnMessageSentCallback | null = null;
+
+/**
+ * 注册出站消息回调
+ * 当消息发送成功且 QQ 返回 ref_idx 时，自动回调此函数
+ * 用于在最底层统一缓存 bot 出站消息的 refIdx
+ */
+export function onMessageSent(callback: OnMessageSentCallback): void {
+  onMessageSentHook = callback;
+}
+
 /**
  * 初始化 API 配置
  * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
@@ -98,7 +127,8 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
   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: { access_token?: string; expires_in?: number };
   let rawBody: string;
@@ -214,6 +244,7 @@ export async function apiRequest<T = unknown>(
     if (typeof logBody.file_data === "string") {
       logBody.file_data = `<base64 ${(logBody.file_data as string).length} chars>`;
     }
+    console.log(`[qqbot-api] >>> Body:`, JSON.stringify(logBody));
   }
 
   let res: Response;
@@ -235,12 +266,14 @@ export async function apiRequest<T = unknown>(
   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: 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)}`);
@@ -303,12 +336,39 @@ export async function getGatewayUrl(accessToken: string): Promise<string> {
 export interface MessageResponse {
   id: string;
   timestamp: number | string;
+  /** 消息的引用索引信息（出站时由 QQ 服务端返回） */
+  ext_info?: {
+    ref_idx?: string;
+  };
+}
+
+/**
+ * 发送消息并自动触发 refIdx 回调
+ * 所有消息发送函数统一经过此处，确保每条出站消息的 refIdx 都被捕获
+ */
+async function sendAndNotify(
+  accessToken: string,
+  method: string,
+  path: string,
+  body: unknown,
+  meta: OutboundMeta,
+): Promise<MessageResponse> {
+  const result = await apiRequest<MessageResponse>(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: string,
   msgId: string | undefined,
-  msgSeq: number
+  msgSeq: number,
+  messageReference?: string
 ): Record<string, unknown> {
   const body: Record<string, unknown> = currentMarkdownSupport
     ? {
@@ -325,6 +385,9 @@ function buildMessageBody(
   if (msgId) {
     body.msg_id = msgId;
   }
+  if (messageReference && !currentMarkdownSupport) {
+    body.message_reference = { message_id: messageReference };
+  }
   return body;
 }
 
@@ -332,11 +395,12 @@ export async function sendC2CMessage(
   accessToken: string,
   openid: string,
   content: string,
-  msgId?: string
+  msgId?: string,
+  messageReference?: string
 ): Promise<MessageResponse> {
   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(
@@ -344,7 +408,7 @@ export async function sendC2CInputNotify(
   openid: string,
   msgId?: string,
   inputSecond: number = 60
-): Promise<void> {
+): Promise<{ refIdx?: string }> {
   const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
   const body = {
     msg_type: 6,
@@ -355,7 +419,8 @@ export async function sendC2CInputNotify(
     msg_seq: msgSeq,
     ...(msgId ? { msg_id: msgId } : {}),
   };
-  await apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+  const response = await apiRequest<{ ext_info?: { ref_idx?: string } }>(accessToken, "POST", `/v2/users/${openid}/messages`, body);
+  return { refIdx: response.ext_info?.ref_idx };
 }
 
 export async function sendChannelMessage(
@@ -396,9 +461,9 @@ export async function sendProactiveC2CMessage(
   accessToken: string,
   openid: string,
   content: string
-): Promise<{ id: string; timestamp: number }> {
+): Promise<MessageResponse> {
   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(
@@ -501,16 +566,17 @@ export async function sendC2CMediaMessage(
   openid: string,
   fileInfo: string,
   msgId?: string,
-  content?: string
-): Promise<{ id: string; timestamp: number }> {
+  content?: string,
+  meta?: OutboundMeta,
+): Promise<MessageResponse> {
   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(
@@ -530,21 +596,29 @@ export async function sendGroupMediaMessage(
   });
 }
 
-export async function sendC2CImageMessage(accessToken: string, openid: string, imageUrl: string, msgId?: string, content?: string): Promise<{ id: string; timestamp: number }> {
+export async function sendC2CImageMessage(accessToken: string, openid: string, imageUrl: string, msgId?: string, content?: string, localPath?: string): Promise<MessageResponse> {
   let uploadResult: UploadMediaResponse;
-  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");
     uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.IMAGE, undefined, matches[2], false);
   } else {
     uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.IMAGE, imageUrl, undefined, false);
   }
-  return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, content);
+  const meta: OutboundMeta = {
+    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: string, groupOpenid: string, imageUrl: string, msgId?: string, content?: string): Promise<{ id: string; timestamp: string }> {
   let uploadResult: UploadMediaResponse;
-  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");
     uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.IMAGE, undefined, matches[2], false);
@@ -554,9 +628,13 @@ export async function sendGroupImageMessage(accessToken: string, groupOpenid: st
   return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId, content);
 }
 
-export async function sendC2CVoiceMessage(accessToken: string, openid: string, voiceBase64: string, msgId?: string): Promise<{ id: string; timestamp: number }> {
+export async function sendC2CVoiceMessage(accessToken: string, openid: string, voiceBase64: string, msgId?: string, ttsText?: string, filePath?: string): Promise<MessageResponse> {
   const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VOICE, undefined, voiceBase64, false);
-  return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId);
+  return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, undefined, { 
+    mediaType: "voice", 
+    ...(ttsText ? { ttsText } : {}),
+    ...(filePath ? { mediaLocalPath: filePath } : {})
+  });
 }
 
 export async function sendGroupVoiceMessage(accessToken: string, groupOpenid: string, voiceBase64: string, msgId?: string): Promise<{ id: string; timestamp: string }> {
@@ -564,9 +642,10 @@ export async function sendGroupVoiceMessage(accessToken: string, groupOpenid: st
   return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId);
 }
 
-export async function sendC2CFileMessage(accessToken: string, openid: string, fileBase64?: string, fileUrl?: string, msgId?: string, fileName?: string): Promise<{ id: string; timestamp: number }> {
+export async function sendC2CFileMessage(accessToken: string, openid: string, fileBase64?: string, fileUrl?: string, msgId?: string, fileName?: string, localFilePath?: string): Promise<MessageResponse> {
   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: string, groupOpenid: string, fileBase64?: string, fileUrl?: string, msgId?: string, fileName?: string): Promise<{ id: string; timestamp: string }> {
@@ -574,9 +653,10 @@ export async function sendGroupFileMessage(accessToken: string, groupOpenid: str
   return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId);
 }
 
-export async function sendC2CVideoMessage(accessToken: string, openid: string, videoUrl?: string, videoBase64?: string, msgId?: string, content?: string): Promise<{ id: string; timestamp: number }> {
+export async function sendC2CVideoMessage(accessToken: string, openid: string, videoUrl?: string, videoBase64?: string, msgId?: string, content?: string, localPath?: string): Promise<MessageResponse> {
   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: string, groupOpenid: string, videoUrl?: string, videoBase64?: string, msgId?: string, content?: string): Promise<{ id: string; timestamp: string }> {

package/src/channel.ts

@@ -1,6 +1,7 @@
 import {
   type ChannelPlugin,
   type OpenClawConfig,
+  type NormalizeTargetResult,
   applyAccountNameToChannelSection,
   deleteAccountFromConfigSection,
   setAccountEnabledInConfigSection,
@@ -167,7 +168,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
      * - channel:channelid -> 频道
      * - 纯 openid（32位十六进制）-> 私聊
      */
-    normalizeTarget: (target: string) => {
+    normalizeTarget: (target: string): NormalizeTargetResult => {
       // 去掉 qqbot: 前缀（如果有）
       const id = target.replace(/^qqbot:/i, "");