@xmanrui/dsh-im 0.9.0 → 0.11.0

package/src/channels/weixin/weixin-api.mjs

@@ -1,8 +1,13 @@
-import { randomBytes, randomUUID } from 'node:crypto';
+import { createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+
+import { fetchImageBuffer } from '../shared/image-prompt.mjs';
 
 export const WEIXIN_QR_BASE_URL = 'https://ilinkai.weixin.qq.com/';
 export const WEIXIN_PROTOCOL_VERSION = '2.4.6';
 export const DEFAULT_BOT_TYPE = '3';
+export const WEIXIN_CDN_BASE_URL = 'https://novac2c.cdn.weixin.qq.com/c2c';
+
+const WEIXIN_CDN_HOST = 'novac2c.cdn.weixin.qq.com';
 
 const ILINK_APP_ID = 'bot';
 const ILINK_CLIENT_VERSION = (2 << 16) | (4 << 8) | 6;
@@ -32,6 +37,93 @@ function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+function strictBase64(value) {
+  const text = nonEmptyString(value);
+  if (!text || text.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(text)) return null;
+  return Buffer.from(text, 'base64');
+}
+
+/** Parse the two AES key encodings used by Weixin iLink image messages. */
+export function parseWeixinImageAesKey(imageItem) {
+  const directHex = nonEmptyString(imageItem?.aeskey);
+  if (directHex) {
+    if (!/^[0-9a-fA-F]{32}$/.test(directHex)) {
+      throw new WeixinApiError('invalid-image-key', '微信图片的加密密钥无效。');
+    }
+    return Buffer.from(directHex, 'hex');
+  }
+
+  const encoded = strictBase64(imageItem?.media?.aes_key);
+  if (encoded?.length === 16) return encoded;
+  if (encoded?.length === 32 && /^[0-9a-fA-F]{32}$/.test(encoded.toString('ascii'))) {
+    return Buffer.from(encoded.toString('ascii'), 'hex');
+  }
+  throw new WeixinApiError('invalid-image-key', '微信图片的加密密钥无效。');
+}
+
+export function decryptWeixinImage(ciphertext, key) {
+  const encrypted = Buffer.from(ciphertext);
+  const aesKey = Buffer.from(key);
+  if (aesKey.length !== 16 || encrypted.length === 0 || encrypted.length % 16 !== 0) {
+    throw new WeixinApiError('invalid-image-ciphertext', '微信图片的加密数据无效。');
+  }
+  try {
+    const decipher = createDecipheriv('aes-128-ecb', aesKey, null);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+  } catch (error) {
+    throw new WeixinApiError('image-decryption-failed', '微信图片解密失败。', { cause: error });
+  }
+}
+
+export function weixinImageDownloadUrl(media) {
+  const query = nonEmptyString(media?.encrypt_query_param);
+  if (query) {
+    return `${WEIXIN_CDN_BASE_URL}/download?encrypted_query_param=${encodeURIComponent(query)}`;
+  }
+
+  const fullUrl = nonEmptyString(media?.full_url);
+  if (!fullUrl) throw new WeixinApiError('missing-image-url', '微信图片没有可用的下载地址。');
+  let url;
+  try {
+    url = new URL(fullUrl);
+  } catch {
+    throw new WeixinApiError('invalid-image-url', '微信图片的下载地址无效。');
+  }
+  if (url.protocol !== 'https:' || url.hostname !== WEIXIN_CDN_HOST
+    || (url.port && url.port !== '443') || !url.pathname.startsWith('/c2c/')) {
+    throw new WeixinApiError('untrusted-image-url', '微信图片的下载地址不受信任。');
+  }
+  url.username = '';
+  url.password = '';
+  url.hash = '';
+  return url.toString();
+}
+
+/** Convert iLink image items into lazily downloaded, decrypted image references. */
+export function extractWeixinImages(message, { fetchImpl = fetch } = {}) {
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetchImpl must be a function');
+  const images = [];
+  for (const item of message?.item_list ?? []) {
+    const imageItem = item?.image_item;
+    if (!imageItem || typeof imageItem !== 'object') continue;
+    images.push({
+      name: images.length === 0 ? 'image' : `image-${images.length + 1}`,
+      load: async ({ signal, maxBytes }) => {
+        const key = parseWeixinImageAesKey(imageItem);
+        const url = weixinImageDownloadUrl(imageItem.media);
+        const ciphertext = await fetchImageBuffer(url, {
+          fetchImpl,
+          signal,
+          maxBytes: maxBytes + 16,
+          allowedHosts: [WEIXIN_CDN_HOST],
+        });
+        return decryptWeixinImage(ciphertext, key);
+      },
+    });
+  }
+  return images;
+}
+
 function isWeixinHost(hostname) {
   const normalized = hostname.toLowerCase().replace(/\.$/, '');
   return normalized === 'weixin.qq.com' || normalized.endsWith('.weixin.qq.com');
@@ -92,7 +184,7 @@ function authenticatedHeaders(token) {
 function baseInfo() {
   return {
     channel_version: WEIXIN_PROTOCOL_VERSION,
-    bot_agent: 'DeepSeekHarness/0.9.0',
+    bot_agent: 'DeepSeekHarness/0.11.0',
   };
 }
 
@@ -170,6 +262,10 @@ export function createWeixinApi({ fetchImpl = fetch } = {}) {
   if (typeof fetchImpl !== 'function') throw new TypeError('fetchImpl must be a function');
 
   return Object.freeze({
+    inboundImages(message) {
+      return extractWeixinImages(message, { fetchImpl });
+    },
+
     async beginLogin({ localTokens = [], botType = DEFAULT_BOT_TYPE, signal } = {}) {
       const tokens = [...new Set(localTokens.map(nonEmptyString).filter(Boolean))].slice(-10);
       const response = await requestJson(fetchImpl, {

package/src/channels/weixin/weixin-bridge.mjs

@@ -1,4 +1,5 @@
 import {
+  extractWeixinImages,
   extractWeixinText,
   splitWeixinText,
   weixinMessageId,
@@ -12,13 +13,19 @@ import { HarnessApprovalQueue } from '../shared/harness-approval.mjs';
 import { runCompactCommand } from '../shared/compact-command.mjs';
 import { runWorkspaceCommand } from '../shared/workspace-command.mjs';
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
+import {
+  hasInboundImages,
+  imagePromptUserMessage,
+  promptContentForMessage,
+} from '../shared/image-prompt.mjs';
+import { rememberConnectionTestTarget } from '../shared/connection-test.mjs';
 
 const INTERACTION_RESOLVED_TEXT = '这个问题已在其他客户端处理，无需再次回答。';
 
 const HELP_TEXT = [
   '微信已连接 DeepSeek Harness。',
   '',
-  '直接发送文字或带文字识别结果的语音即可继续当前会话。',
+  '直接发送文字、图片或带文字识别结果的语音即可继续当前会话。',
   '/new  开启一个全新会话',
   '/compact  压缩当前会话的较早上下文',
   '/workspace 工作区绝对路径  切换工作区',
@@ -37,9 +44,15 @@ function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+function hasWeixinImageItems(message) {
+  return Array.isArray(message?.item_list)
+    && message.item_list.some((item) => item?.image_item && typeof item.image_item === 'object');
+}
+
 function canClaimInteractionReply(message, pending) {
   return pending.questions[pending.index]
     && nonEmptyString(message?.from_user_id) === pending.actor
+    && !hasWeixinImageItems(message)
     && nonEmptyString(extractWeixinText(message));
 }
 
@@ -116,6 +129,9 @@ export class WeixinHarnessBridge {
     if (!messageId || !sender || this.#state.hasSeen(messageId)
       || this.#acceptedMessageIds.has(messageId)) return Promise.resolve();
     this.#acceptedMessageIds.add(messageId);
+    if (sender === this.#ownerUserId) {
+      rememberConnectionTestTarget(this.#state, { toUserId: sender });
+    }
     const key = conversationKey(sender);
     const contextToken = nonEmptyString(message?.context_token) ?? undefined;
     const runId = nonEmptyString(message?.run_id) ?? undefined;
@@ -124,7 +140,7 @@ export class WeixinHarnessBridge {
       key,
       actor: sender,
       messageId,
-      text: extractWeixinText(message),
+      text: hasWeixinImageItems(message) ? '' : extractWeixinText(message),
       addressed: true,
       hasPendingQuestion: Boolean(pending),
       questionCompletion: pending?.submitting || pending?.claimedReplyMessageId
@@ -216,33 +232,40 @@ export class WeixinHarnessBridge {
 
     const contextToken = typeof message.context_token === 'string' ? message.context_token : undefined;
     const runId = typeof message.run_id === 'string' ? message.run_id : undefined;
-    const text = extractWeixinText(message);
+    const text = extractWeixinText(message) ?? '';
     try {
-      if (!text) {
-        await this.#send(sender, '目前仅支持文字消息，以及微信已转成文字的语音消息。', contextToken, runId);
+      const images = typeof this.#api.inboundImages === 'function'
+        ? this.#api.inboundImages(message)
+        : extractWeixinImages(message);
+      const promptMessage = { content: text, images };
+      const hasImages = hasInboundImages(promptMessage);
+      if (!text && !hasImages) {
+        await this.#send(sender, '目前支持文字、图片，以及微信已转成文字的语音消息。', contextToken, runId);
         await this.#state.markSeen(messageId);
         return;
       }
 
       const command = text.trim().toLowerCase();
-      if (command === '/help') {
+      if (!hasImages && command === '/help') {
         await this.#send(sender, HELP_TEXT, contextToken, runId);
         await this.#state.markSeen(messageId);
         return;
       }
-      if (command === '/status') {
+      if (!hasImages && command === '/status') {
         await this.#harness.ensureRunning({ signal: this.#signal });
         await this.#send(sender, '微信与 DeepSeek Harness 连接正常。', contextToken, runId);
         await this.#state.markSeen(messageId);
         return;
       }
-      if (command === '/new') {
+      if (!hasImages && command === '/new') {
         await this.#state.clearSession(key);
         await this.#send(sender, '已开启新会话。请发送你的问题。', contextToken, runId);
         await this.#state.markSeen(messageId);
         return;
       }
-      const workspaceCommand = await runWorkspaceCommand(text, this.#harness, key);
+      const workspaceCommand = hasImages
+        ? null
+        : await runWorkspaceCommand(text, this.#harness, key);
       if (workspaceCommand) {
         for (const reply of workspaceCommand.messages ?? [workspaceCommand.message]) {
           await this.#send(sender, reply, contextToken, runId);
@@ -250,26 +273,31 @@ export class WeixinHarnessBridge {
         await this.#state.markSeen(messageId);
         return;
       }
-      const compactCommand = await runCompactCommand(
-        text,
-        this.#harness,
-        this.#state,
-        key,
-        { signal: this.#signal },
-      );
+      const compactCommand = hasImages
+        ? null
+        : await runCompactCommand(
+            text,
+            this.#harness,
+            this.#state,
+            key,
+            { signal: this.#signal },
+          );
       if (compactCommand) {
         await this.#send(sender, compactCommand.message, contextToken, runId);
         await this.#state.markSeen(messageId);
         return;
       }
 
+      const content = hasImages
+        ? await promptContentForMessage(promptMessage, { signal: this.#signal })
+        : undefined;
       let answer;
       try {
         ({ answer } = await askInWorkspaceSession({
           harness: this.#harness,
           state: this.#state,
           key,
-          text,
+          ...(hasImages ? { content } : { text }),
           createOptions: { signal: this.#signal },
           existsOptions: { signal: this.#signal },
           askOptions: {
@@ -300,7 +328,12 @@ export class WeixinHarnessBridge {
       this.#status.lastError = error?.message ?? String(error);
       this.#logger.error?.('[dsh-weixin] failed to process an inbound message:', error);
       try {
-        await this.#send(sender, '消息处理失败，请稍后重试。', contextToken, runId);
+        await this.#send(
+          sender,
+          imagePromptUserMessage(error) ?? '消息处理失败，请稍后重试。',
+          contextToken,
+          runId,
+        );
         await this.#state.markSeen(messageId);
       } catch (sendError) {
         this.#logger.error?.('[dsh-weixin] failed to send the safe error reply:', sendError);
@@ -326,7 +359,7 @@ export class WeixinHarnessBridge {
     const text = nonEmptyString(extractWeixinText(message));
     const contextToken = nonEmptyString(message?.context_token) ?? undefined;
     const runId = nonEmptyString(message?.run_id) ?? undefined;
-    if (!text) {
+    if (!text || hasWeixinImageItems(message)) {
       await this.#send(
         expected.actor,
         '请用文字回答当前问题。',

package/src/channels/weixin/weixin-controller.mjs

@@ -6,6 +6,10 @@ import {
   WeixinApiError,
 } from './weixin-api.mjs';
 import { deriveWeixinBotIdentity, maskWeixinAccountId } from './config-store.mjs';
+import {
+  connectionTestMessage,
+  connectionTestTargetUnavailable,
+} from '../shared/connection-test.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set([
   'starting',
@@ -240,6 +244,20 @@ export class WeixinController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Weixin account');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        throw connectionTestTargetUnavailable('微信机器人');
+      }
+      return runtime.sendConnectionTest(connectionTestMessage(
+        `微信机器人（${maskWeixinAccountId(config.accountId)}）`,
+      ));
+    });
+  }
+
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown Weixin account');

package/src/channels/weixin/weixin-runtime.mjs

@@ -1,5 +1,9 @@
 import { WeixinApiError } from './weixin-api.mjs';
 import { createWeixinBridgeStatus, WeixinHarnessBridge } from './weixin-bridge.mjs';
+import {
+  connectionTestTarget,
+  connectionTestTargetUnavailable,
+} from '../shared/connection-test.mjs';
 
 const DEFAULT_START_RETRY_DELAYS_MS = Object.freeze([250, 1_000, 3_000]);
 
@@ -250,4 +254,25 @@ export class WeixinRuntime {
     this.#status.weixinConnectionState = 'idle';
     return this.status;
   }
+
+  async sendConnectionTest(text) {
+    const remembered = connectionTestTarget(this.#state);
+    const toUserId = typeof remembered?.toUserId === 'string' && remembered.toUserId.trim()
+      ? remembered.toUserId.trim()
+      : typeof this.#config.ownerUserId === 'string' && this.#config.ownerUserId.trim()
+        ? this.#config.ownerUserId.trim()
+        : null;
+    if (!toUserId) throw connectionTestTargetUnavailable('微信机器人');
+    if (!this.#status.ready || !this.#abortController) {
+      throw new Error('Weixin runtime is not connected');
+    }
+    await this.#api.sendText({
+      baseUrl: this.#config.baseUrl,
+      token: this.#token,
+      toUserId,
+      text,
+      signal: this.#abortController.signal,
+    });
+    return { sent: true };
+  }
 }

package/src/channels/whatsapp/whatsapp-controller.mjs

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 
+import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { deriveWhatsappBotId, maskWhatsappAccount } from './config-store.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set(['starting', 'pending', 'connecting']);
@@ -198,6 +199,25 @@ export class WhatsappController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown WhatsApp bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        const error = new Error('WhatsApp机器人尚未连接');
+        error.code = 'test-target-unavailable';
+        throw error;
+      }
+      return runtime.sendConnectionTest(
+        connectionTestMessage(
+          `${config.name}（${maskWhatsappAccount(config.accountJid)}）`,
+          'WhatsApp机器人',
+        ),
+      );
+    });
+  }
+
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown WhatsApp bot');

package/src/channels/whatsapp/whatsapp-runtime.mjs

@@ -1,12 +1,45 @@
 import {
   areJidsSameUser,
+  downloadMediaMessage,
   normalizeMessageContent,
 } from '@whiskeysockets/baileys';
 
 import { splitMessageText } from '../shared/editable-message-stream.mjs';
+import { ImagePromptError } from '../shared/image-prompt.mjs';
 import { createWhatsappBridgeStatus, WhatsappHarnessBridge } from './whatsapp-bridge.mjs';
 import { createWhatsappWebSession } from './whatsapp-web-session.mjs';
 
+const IMAGE_MEDIA_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
+const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const IMAGE_DOWNLOAD_TIMEOUT_MS = 15_000;
+const MESSAGE_WRAPPER_KEYS = [
+  'ephemeralMessage',
+  'viewOnceMessage',
+  'documentWithCaptionMessage',
+  'viewOnceMessageV2',
+  'viewOnceMessageV2Extension',
+  'editedMessage',
+  'associatedChildMessage',
+  'groupStatusMessage',
+  'groupStatusMessageV2',
+];
+const VIEW_ONCE_WRAPPER_KEYS = new Set([
+  'viewOnceMessage',
+  'viewOnceMessageV2',
+  'viewOnceMessageV2Extension',
+]);
+
+function hasViewOnceWrapper(content) {
+  let current = content;
+  for (let depth = 0; depth < 5 && current && typeof current === 'object'; depth += 1) {
+    const wrapperKey = MESSAGE_WRAPPER_KEYS.find((key) => current[key]?.message);
+    if (!wrapperKey) return false;
+    if (VIEW_ONCE_WRAPPER_KEYS.has(wrapperKey)) return true;
+    current = current[wrapperKey].message;
+  }
+  return false;
+}
+
 function messageContext(content) {
   return content?.extendedTextMessage?.contextInfo
     ?? content?.imageMessage?.contextInfo
@@ -24,7 +57,114 @@ function messageText(content) {
     ?? '';
 }
 
-export function normalizeWhatsappMessage(message, accountJid) {
+function mediaSize(value) {
+  if (Number.isSafeInteger(value) && value >= 0) return value;
+  let converted;
+  try {
+    converted = Number(value?.toString?.());
+  } catch {
+    return undefined;
+  }
+  return Number.isSafeInteger(converted) && converted >= 0 ? converted : undefined;
+}
+
+async function downloadWhatsappImage(message, download, {
+  signal,
+  maxBytes = DEFAULT_MAX_IMAGE_BYTES,
+} = {}) {
+  signal?.throwIfAborted();
+  const timeout = AbortSignal.timeout(IMAGE_DOWNLOAD_TIMEOUT_MS);
+  const downloadSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const pendingStream = Promise.resolve().then(() => (
+    download(message, 'stream', { options: { signal: downloadSignal } })
+  ));
+  const stream = await new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return false;
+      settled = true;
+      downloadSignal.removeEventListener('abort', onAbort);
+      callback(value);
+      return true;
+    };
+    const onAbort = () => finish(reject, downloadSignal.reason);
+    downloadSignal.addEventListener('abort', onAbort, { once: true });
+    pendingStream.then((value) => {
+      if (!finish(resolve, value)) value?.destroy?.();
+    }, (error) => finish(reject, error));
+    if (downloadSignal.aborted) onAbort();
+  }).catch((error) => {
+    if (signal?.aborted) throw signal.reason ?? error;
+    if (timeout.aborted) {
+      throw new ImagePromptError(
+        'image-download-failed',
+        `WhatsApp image download timed out after ${IMAGE_DOWNLOAD_TIMEOUT_MS} ms`,
+        '图片下载失败，请重新发送后再试。',
+      );
+    }
+    throw error;
+  });
+  const chunks = [];
+  let size = 0;
+  const abortStream = () => stream?.destroy?.(downloadSignal.reason);
+  downloadSignal.addEventListener('abort', abortStream, { once: true });
+  try {
+    for await (const chunk of stream) {
+      downloadSignal.throwIfAborted();
+      const data = Buffer.from(chunk);
+      size += data.length;
+      if (size > maxBytes) {
+        stream.destroy?.();
+        throw new ImagePromptError(
+          'image-too-large',
+          `WhatsApp image exceeded ${maxBytes} bytes`,
+          '图片超过 5 MB，请压缩后重试。',
+        );
+      }
+      chunks.push(data);
+    }
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason ?? error;
+    if (timeout.aborted) {
+      throw new ImagePromptError(
+        'image-download-failed',
+        `WhatsApp image stream timed out after ${IMAGE_DOWNLOAD_TIMEOUT_MS} ms`,
+        '图片下载失败，请重新发送后再试。',
+      );
+    }
+    throw error;
+  } finally {
+    downloadSignal.removeEventListener('abort', abortStream);
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function whatsappImageSource(message, content, download, { viewOnce = false } = {}) {
+  let media;
+  let name;
+  if (!viewOnce && content?.imageMessage && content.imageMessage.viewOnce !== true) {
+    media = content.imageMessage;
+  } else if (content?.documentMessage) {
+    const type = typeof content.documentMessage.mimetype === 'string'
+      ? content.documentMessage.mimetype.toLowerCase() : '';
+    if (!IMAGE_MEDIA_TYPES.has(type)) return null;
+    media = content.documentMessage;
+    name = typeof media.fileName === 'string' ? media.fileName : undefined;
+  }
+  if (!media) return null;
+  const mediaType = typeof media.mimetype === 'string' ? media.mimetype.toLowerCase() : '';
+  if (!IMAGE_MEDIA_TYPES.has(mediaType)) return null;
+  return {
+    name,
+    mediaType,
+    size: mediaSize(media.fileLength),
+    load: (options) => downloadWhatsappImage(message, download, options),
+  };
+}
+
+export function normalizeWhatsappMessage(message, accountJid, {
+  download = downloadMediaMessage,
+} = {}) {
   const remoteJid = typeof message?.key?.remoteJid === 'string' ? message.key.remoteJid : '';
   const alternateRemoteJid = typeof message?.key?.remoteJidAlt === 'string'
     ? message.key.remoteJidAlt : '';
@@ -38,12 +178,14 @@ export function normalizeWhatsappMessage(message, accountJid) {
   if (fromMe && !selfChat) return null;
   const senderJid = selfChat ? accountJid : group ? message.key.participant : remoteJid;
   if (typeof senderJid !== 'string' || !senderJid) return null;
+  const viewOnce = hasViewOnceWrapper(message.message);
   const content = normalizeMessageContent(message.message);
   const context = messageContext(content);
   const mentioned = Array.isArray(context?.mentionedJid)
     && context.mentionedJid.some((jid) => areJidsSameUser(jid, accountJid));
   const replyToSelf = typeof context?.participant === 'string'
     && areJidsSameUser(context.participant, accountJid);
+  const image = whatsappImageSource(message, content, download, { viewOnce });
   return {
     messageId: `${remoteJid}:${messageId}`,
     providerMessageId: messageId,
@@ -52,6 +194,7 @@ export function normalizeWhatsappMessage(message, accountJid) {
     kind: group ? 'group' : 'direct',
     conversationId: remoteJid,
     content: messageText(content),
+    images: image ? [image] : [],
     addressed: !group || mentioned || replyToSelf,
     selfChat,
     replyTarget: { jid: remoteJid, quoted: message, selfChat },
@@ -278,6 +421,22 @@ export class WhatsappRuntime {
     return this.stop();
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#client) {
+      const error = new Error('WhatsApp机器人尚未连接');
+      error.code = 'test-target-unavailable';
+      throw error;
+    }
+    if (typeof text !== 'string' || !text.trim()) {
+      throw new TypeError('WhatsApp connection test text is required');
+    }
+    await this.#client.sendText({
+      jid: this.#config.accountJid,
+      selfChat: true,
+    }, text);
+    return { sent: true };
+  }
+
   async stop() {
     const session = this.#session;
     const client = this.#client;