@xmanrui/dsh-im 0.10.0 → 0.12.0

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

@@ -6,6 +6,10 @@ import {
   maskDingtalkClientId,
   maskDingtalkSenderId,
 } from './config-store.mjs';
+import {
+  connectionTestMessage,
+  connectionTestTargetUnavailable,
+} from '../shared/connection-test.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set(['starting', 'pending', 'connecting']);
 const TERMINAL_ATTEMPT_STATES = new Set(['connected', 'expired', 'failed', 'cancelled']);
@@ -386,6 +390,20 @@ export class DingtalkController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown DingTalk bot');
+    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(
+        `钉钉机器人（${maskDingtalkClientId(config.clientId)}）`,
+      ));
+    });
+  }
+
   /** Removes one bot, its secret, runtime, and local conversation state. */
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);

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

@@ -3,6 +3,7 @@ import {
   createDingtalkBridgeStatus,
   DingtalkHarnessBridge,
 } from './dingtalk-bridge.mjs';
+import { sendRememberedConnectionTest } from '../shared/connection-test.mjs';
 
 function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -347,6 +348,26 @@ export class DingtalkRuntime {
     return this.status;
   }
 
+  async sendConnectionTest(text) {
+    return sendRememberedConnectionTest({
+      state: this.#state,
+      text,
+      channelLabel: '钉钉机器人',
+      send: async ({ sessionWebhook }, content) => {
+        if (!this.#status.ready || !this.#abortController) {
+          throw new Error('DingTalk runtime is not connected');
+        }
+        await this.#api.sendText({
+          clientId: this.#config.clientId,
+          clientSecret: this.#clientSecret,
+          sessionWebhook,
+          text: content,
+          signal: this.#abortController.signal,
+        });
+      },
+    });
+  }
+
   #pendingSenders() {
     return typeof this.#state.pendingSenders === 'function'
       ? this.#state.pendingSenders()

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

@@ -108,7 +108,7 @@ export class DiscordApi {
         headers: {
           authorization: `Bot ${this.#token}`,
           'content-type': 'application/json',
-          'user-agent': 'DeepSeek-Harness-dsh-im (https://github.com/xmanrui/dsh-im, 0.10.0)',
+          'user-agent': 'DeepSeek-Harness-dsh-im (https://github.com/xmanrui/dsh-im, 0.12.0)',
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
         signal: requestSignal(signal, timeoutMs),

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

@@ -108,6 +108,7 @@ export function normalizeDiscordMessage(message, botId, { fetchImpl = fetch } =
       channelId: String(message.channel_id),
       replyToMessageId: String(message.id),
     },
+    connectionTestTarget: { channelId: String(message.channel_id) },
   };
 }
 
@@ -239,6 +240,15 @@ export class DiscordRuntime {
     return structuredClone(this.#status);
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#bridge) {
+      const error = new Error('Discord bot is not connected');
+      error.code = 'test-target-unavailable';
+      throw error;
+    }
+    return this.#bridge.sendConnectionTest(text);
+  }
+
   async start() {
     if (this.#status.ready && this.#socket) return this.status;
     if (this.#starting) return this.#starting;

package/src/channels/feishu/bridge.mjs

@@ -18,6 +18,15 @@ import {
 } from '../shared/harness-question.mjs';
 import { HarnessApprovalQueue } from '../shared/harness-approval.mjs';
 import { runCompactCommand } from '../shared/compact-command.mjs';
+import {
+  isControlCommand,
+  runControlCommand,
+} from '../shared/control-command.mjs';
+import { rememberConnectionTestTarget } from '../shared/connection-test.mjs';
+import {
+  isModelCommand,
+  runModelCommand,
+} from '../shared/model-command.mjs';
 import { runWorkspaceCommand } from '../shared/workspace-command.mjs';
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
 
@@ -34,6 +43,10 @@ const HELP_TEXT = [
   '/workspacelist  列出工作区绝对路径',
   '/sessionlist [工作区序号或绝对路径]  列出会话 ID 和标题',
   '/session Session ID 或当前工作区序号  将当前聊天绑定到指定会话',
+  '/models  列出所有可用模型',
+  '/model [模型ID]  查看或切换当前会话模型',
+  '/stop  停止当前任务',
+  '/steer 补充指令  纠偏当前任务',
   '/status  检查连接状态',
   '/help  显示本帮助',
 ].join('\n');
@@ -76,6 +89,7 @@ export class FeishuHarnessBridge {
   #resolvedQuestionReplies = new Map();
   #acceptedMessageIds = new Set();
   #interactionTasks = new Set();
+  #commandTasks = new Set();
   #approvals;
   #status;
   #allowedSenderOpenIds;
@@ -133,8 +147,44 @@ export class FeishuHarnessBridge {
       return Promise.resolve();
     }
 
+    if (event.message.chat_type === 'p2p') {
+      const chatId = nonEmptyString(event.message.chat_id);
+      if (chatId) rememberConnectionTestTarget(this.#state, { chatId });
+    }
+
     this.#acceptedMessageIds.add(messageId);
     const processingReaction = this.#addReaction(messageId, 'OnIt');
+    const commandMessage = extractInboundMessage(event, this.#client);
+    const commandText = nonEmptyString(commandMessage.content) ?? '';
+    const commandRunner = isControlCommand(commandText)
+      ? runControlCommand
+      : (isModelCommand(commandText) ? runModelCommand : null);
+    const addressed = event?.message?.chat_type === 'p2p'
+      || (Array.isArray(event?.message?.mentions) && event.message.mentions.length > 0);
+    if (commandRunner && addressed) {
+      const processing = this.#processFastCommand(
+        event,
+        messageId,
+        key,
+        commandMessage,
+        commandRunner,
+      );
+      let current;
+      current = processing
+        .then(() => this.#finishReaction(messageId, processingReaction, 'DONE'))
+        .catch((error) => this.#handleMessageFailure(
+          event,
+          messageId,
+          processingReaction,
+          error,
+        ))
+        .finally(() => {
+          this.#acceptedMessageIds.delete(messageId);
+          this.#commandTasks.delete(current);
+        });
+      this.#commandTasks.add(current);
+      return current;
+    }
     if (this.#isResolvedQuestionReply(event, key)) {
       const current = Promise.resolve()
         .then(() => this.#discardResolvedInteractionReply(event, messageId))
@@ -270,6 +320,10 @@ export class FeishuHarnessBridge {
   }
 
   async #handleMessageFailure(event, messageId, processingReaction, error) {
+    if (error?.code === 'turn-stopped') {
+      await this.#removeProcessingReaction(messageId, processingReaction);
+      return;
+    }
     if (this.#signal?.aborted) {
       await this.#removeProcessingReaction(messageId, processingReaction);
       return;
@@ -291,9 +345,41 @@ export class FeishuHarnessBridge {
         pending.queue ? [pending.queue] : []
       )),
       ...this.#interactionTasks,
+      ...this.#commandTasks,
     ]);
   }
 
+  async #processFastCommand(event, messageId, key, message, runner) {
+    this.#signal?.throwIfAborted();
+    if (this.#state.hasSeen(messageId)) return;
+    await this.#state.markSeen(messageId);
+    this.#status.lastMessageAt = new Date().toISOString();
+    this.#status.messagesReceived += 1;
+    const result = await runner(
+      nonEmptyString(message.content) ?? '',
+      this.#harness,
+      this.#state,
+      key,
+      {
+        signal: this.#signal,
+        hasImages: hasInboundImages(message),
+        pendingInteraction: this.#pendingInteractions.has(key)
+          || this.#approvals.hasPending(key),
+        control: { owner: this, key },
+      },
+    );
+    if (result?.stopped) {
+      await Promise.allSettled([
+        this.#cancelPendingInteraction(key),
+        this.#approvals.closeRoute(key),
+      ]);
+    }
+    for (const reply of result?.messages ?? [result?.message]) {
+      if (reply) await this.#send(event.message.chat_id, reply);
+    }
+    this.#status.lastError = null;
+  }
+
   async #handle(event, key, { alreadyRecorded = false } = {}) {
     this.#signal?.throwIfAborted();
     const messageId = event.message.message_id;
@@ -366,6 +452,7 @@ export class FeishuHarnessBridge {
     return {
       timeoutMs: this.#replyTimeoutMs,
       signal: this.#signal,
+      control: { owner: this, key },
       onInteraction: (interaction) => this.#handleInteraction(interaction, {
         key,
         actor: senderOpenId(event),

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

@@ -1,5 +1,9 @@
 import { FeishuHarnessBridge } from './bridge.mjs';
 import { VerifiedFeishuChannel } from './feishu-channel.mjs';
+import {
+  connectionTestTargetUnavailable,
+  sendRememberedConnectionTest,
+} from '../shared/connection-test.mjs';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 
@@ -240,6 +244,47 @@ export class FeishuRuntime {
     }
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#client) {
+      const error = new Error('飞书机器人尚未连接');
+      error.code = 'test-target-unavailable';
+      throw error;
+    }
+    if (typeof text !== 'string' || !text.trim()) {
+      throw new TypeError('Feishu connection test text is required');
+    }
+    const send = async (receiveIdType, receiveId, content) => {
+      const response = await this.#client.im.v1.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: 'text',
+          content: JSON.stringify({ text: content }),
+        },
+      });
+      if (response?.code && response.code !== 0) {
+        throw new Error(`Feishu connection test failed: ${response.msg || response.code}`);
+      }
+    };
+
+    const ownerOpenId = this.#ownerOpenIds.find((value) => value !== '*');
+    if (ownerOpenId) {
+      await send('open_id', ownerOpenId, text);
+      return { sent: true };
+    }
+
+    return sendRememberedConnectionTest({
+      state: this.#state,
+      text,
+      channelLabel: '飞书机器人',
+      send: async (target, content) => {
+        const chatId = typeof target?.chatId === 'string' ? target.chatId.trim() : '';
+        if (!chatId) throw connectionTestTargetUnavailable('飞书机器人');
+        await send('chat_id', chatId, content);
+      },
+    });
+  }
+
   async stop({ preserveError = false } = {}) {
     const error = preserveError ? this.#status.lastError : null;
     const abortController = this.#abortController;

package/src/channels/feishu/message-utils.mjs

@@ -1,5 +1,11 @@
 import { ImagePromptError } from '../shared/image-prompt.mjs';
 
+const FEISHU_MISSING_MESSAGE_SCOPE_CODE = 99991672;
+const FEISHU_ERROR_BODY_LIMIT = 64 * 1024;
+const FEISHU_ERROR_BODY_TIMEOUT_MS = 1_000;
+const FEISHU_IMAGE_PERMISSION_MESSAGE =
+  '飞书机器人缺少图片读取权限。请在飞书开放平台为该应用添加 im:message:readonly，发布新版本并完成必要的管理员审批后，再重新发送图片。';
+
 export function conversationKey(event) {
   const chatType = event?.message?.chat_type;
   if (chatType === 'p2p') {
@@ -119,17 +125,98 @@ async function readBoundedStream(stream, { signal, maxBytes }) {
   }
 }
 
+function providerCode(value) {
+  if (!value || typeof value !== 'object') return null;
+  const code = value.code ?? value.error?.code;
+  return Number.isSafeInteger(Number(code)) ? Number(code) : null;
+}
+
+async function readFeishuErrorBody(stream, signal) {
+  if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') return null;
+  signal?.throwIfAborted();
+  const timeout = AbortSignal.timeout(FEISHU_ERROR_BODY_TIMEOUT_MS);
+  const readSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const abort = () => stream.destroy?.(readSignal.reason);
+  readSignal.addEventListener('abort', abort, { once: true });
+  const chunks = [];
+  let size = 0;
+  try {
+    for await (const chunk of stream) {
+      const data = Buffer.from(chunk);
+      size += data.length;
+      if (size > FEISHU_ERROR_BODY_LIMIT) {
+        stream.destroy?.();
+        return null;
+      }
+      chunks.push(data);
+    }
+    return Buffer.concat(chunks, size).toString('utf8');
+  } catch {
+    signal?.throwIfAborted();
+    return null;
+  } finally {
+    readSignal.removeEventListener('abort', abort);
+  }
+}
+
+async function feishuProviderCode(error, signal) {
+  const pending = [error];
+  const seen = new Set();
+  while (pending.length > 0 && seen.size < 8) {
+    const value = pending.shift();
+    if (!value || (typeof value !== 'object' && typeof value !== 'function') || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    const directCode = providerCode(value);
+    const data = value.response?.data ?? value.data;
+    if (directCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) {
+      data?.destroy?.();
+      return directCode;
+    }
+    if (data && typeof data[Symbol.asyncIterator] === 'function') {
+      const body = await readFeishuErrorBody(data, signal);
+      try {
+        const parsedCode = providerCode(JSON.parse(body));
+        if (parsedCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return parsedCode;
+      } catch {
+        // Non-JSON provider failures keep the generic image download message.
+      }
+    } else {
+      const dataCode = providerCode(data);
+      if (dataCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return dataCode;
+    }
+    pending.push(value.cause);
+  }
+  return null;
+}
+
+async function feishuImageDownloadError(error, signal) {
+  if (await feishuProviderCode(error, signal) !== FEISHU_MISSING_MESSAGE_SCOPE_CODE) return error;
+  return new ImagePromptError(
+    'feishu-image-permission-required',
+    'Feishu image download requires the im:message:readonly tenant scope',
+    FEISHU_IMAGE_PERMISSION_MESSAGE,
+    { cause: error },
+  );
+}
+
 function feishuImageSource(event, client, key) {
   return {
     async load({ signal, maxBytes }) {
       signal?.throwIfAborted();
-      const resource = await client?.im?.v1?.messageResource?.get?.({
-        path: {
-          message_id: event.message.message_id,
-          file_key: key,
-        },
-        params: { type: 'image' },
-      });
+      let resource;
+      try {
+        resource = await client?.im?.v1?.messageResource?.get?.({
+          path: {
+            message_id: event.message.message_id,
+            file_key: key,
+          },
+          params: { type: 'image' },
+        });
+      } catch (error) {
+        throw await feishuImageDownloadError(error, signal);
+      }
       signal?.throwIfAborted();
       const size = declaredSize(resource?.headers);
       if (size !== null && size > maxBytes) {

package/src/channels/feishu/multi-bot-controller.mjs

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { RegistrationManager } from './registration-manager.mjs';
 import { REQUIRED_TENANT_SCOPES } from './plugin-controller.mjs';
 
@@ -339,6 +340,26 @@ export class MultiBotDshFeishuController {
     });
   }
 
+  async sendConnectionTest(botId) {
+    this.#assertOpen();
+    return this.#withBotTransition(botId, async () => {
+      const config = this.#requireBot(botId);
+      const runtime = this.#runtimes.get(botId);
+      if (!isConnected(connectionStatus(runtime))
+        || typeof runtime.sendConnectionTest !== 'function') {
+        const error = new Error('飞书机器人尚未连接');
+        error.code = 'test-target-unavailable';
+        throw error;
+      }
+      return runtime.sendConnectionTest(
+        connectionTestMessage(
+          `${config.botName}（${maskedAppId(config.appId)}）`,
+          '飞书机器人',
+        ),
+      );
+    });
+  }
+
   async disconnectBot(botId) {
     this.#assertOpen();
     // An operational pause only: credentials/config remain durable, so the

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

@@ -1,11 +1,20 @@
 import { runWorkspaceCommand } from '../shared/workspace-command.mjs';
 import { runCompactCommand } from '../shared/compact-command.mjs';
+import {
+  isControlCommand,
+  runControlCommand,
+} from '../shared/control-command.mjs';
+import { rememberConnectionTestTarget } from '../shared/connection-test.mjs';
 import {
   harnessAnswerForQuestion,
   harnessQuestionText,
   validHarnessQuestion,
 } from '../shared/harness-question.mjs';
 import { HarnessApprovalQueue } from '../shared/harness-approval.mjs';
+import {
+  isModelCommand,
+  runModelCommand,
+} from '../shared/model-command.mjs';
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
 import {
   fetchImageBuffer,
@@ -37,6 +46,10 @@ const HELP_TEXT = [
   '/workspacelist  列出工作区绝对路径',
   '/sessionlist [工作区序号或绝对路径]  列出会话 ID 和标题',
   '/session Session ID 或当前工作区序号  将当前聊天绑定到指定会话',
+  '/models  列出所有可用模型',
+  '/model [模型ID]  查看或切换当前会话模型',
+  '/stop  停止当前任务',
+  '/steer 补充指令  纠偏当前任务',
   '/status  检查连接状态',
   '/help  显示本帮助',
 ].join('\n');
@@ -133,6 +146,7 @@ export class QqHarnessBridge {
   #interactionKeys = new Map();
   #acceptedMessageIds = new Set();
   #approvalTasks = new Set();
+  #commandTasks = new Set();
   #approvals;
 
   constructor({
@@ -176,7 +190,41 @@ export class QqHarnessBridge {
       || this.#acceptedMessageIds.has(messageId)) return Promise.resolve();
     const key = conversationKey(message);
     this.#acceptedMessageIds.add(messageId);
+    if (message.kind === 'c2c'
+      && (this.#ownerUserOpenid === '*' || sender === this.#ownerUserOpenid)
+      && message.replyTarget?.scope === 'c2c'
+      && nonEmptyString(message.replyTarget.targetId) === sender) {
+      rememberConnectionTestTarget(this.#state, message.replyTarget);
+    }
     const pending = this.#pendingInteractions.get(key);
+    const commandText = safeText(message);
+    const commandRunner = isControlCommand(commandText)
+      ? runControlCommand
+      : (isModelCommand(commandText) ? runModelCommand : null);
+    const allowed = this.#ownerUserOpenid === '*' || sender === this.#ownerUserOpenid;
+    const addressed = message.kind !== 'group'
+      || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE';
+    if (commandRunner && allowed && addressed) {
+      let task;
+      task = this.#processFastCommand(
+        message,
+        messageId,
+        key,
+        commandText,
+        commandRunner,
+      ).catch((error) => {
+        if (error?.code === 'turn-stopped' || this.#signal?.aborted) return;
+        this.#status.lastError = error?.message ?? String(error);
+        this.#logger.error?.('[dsh-im:qq] failed to process a command:', error);
+        return this.#bot.sendText(message.replyTarget, '消息处理失败，请稍后重试。')
+          .catch(() => undefined);
+      }).finally(() => {
+        this.#acceptedMessageIds.delete(messageId);
+        this.#commandTasks.delete(task);
+      });
+      this.#commandTasks.add(task);
+      return task;
+    }
     const approval = this.#approvals.claimReply({
       key,
       actor: sender,
@@ -255,9 +303,35 @@ export class QqHarnessBridge {
         pending.queue ? [pending.queue] : []
       )),
       ...this.#approvalTasks,
+      ...this.#commandTasks,
     ]);
   }
 
+  async #processFastCommand(message, messageId, key, text, runner) {
+    this.#signal?.throwIfAborted();
+    if (this.#state.hasSeen(messageId)) return;
+    await this.#state.markSeen(messageId);
+    this.#status.messagesReceived += 1;
+    this.#status.lastMessageAt = new Date().toISOString();
+    const result = await runner(text, this.#harness, this.#state, key, {
+      signal: this.#signal,
+      hasImages: hasQqImageAttachments(message),
+      pendingInteraction: this.#pendingInteractions.has(key)
+        || this.#approvals.hasPending(key),
+      control: { owner: this, key },
+    });
+    if (result?.stopped) {
+      await Promise.allSettled([
+        this.#cancelPendingInteraction(key),
+        this.#approvals.closeRoute(key),
+      ]);
+    }
+    for (const reply of result?.messages ?? [result?.message]) {
+      if (reply) await this.#bot.sendText(message.replyTarget, reply);
+    }
+    this.#status.lastError = null;
+  }
+
   async #process(message, key, { alreadyRecorded = false } = {}) {
     if (this.#signal?.aborted) return;
     const messageId = nonEmptyString(message?.messageId);
@@ -353,6 +427,7 @@ export class QqHarnessBridge {
           askOptions: {
             timeoutMs: this.#replyTimeoutMs,
             signal: this.#signal,
+            control: { owner: this, key },
             onUpdate: stream ? async (update) => {
               const progress = update.type === 'text'
                 ? update.text
@@ -392,6 +467,22 @@ export class QqHarnessBridge {
       this.#status.lastReplyAt = new Date().toISOString();
       this.#status.lastError = null;
     } catch (error) {
+      if (error?.code === 'turn-stopped') {
+        if (stream) {
+          try {
+            await stream.cancel?.();
+          } catch (streamError) {
+            this.#logger.warn?.('[dsh-im:qq] unable to cancel a stopped QQ stream:', streamError);
+          }
+          try {
+            await this.#bot.sendText(target, '已停止。');
+          } catch (sendError) {
+            this.#logger.warn?.('[dsh-im:qq] unable to announce a stopped QQ turn:', sendError);
+          }
+        }
+        await this.#state.markSeen(messageId);
+        return;
+      }
       stream?.cancel?.();
       if (this.#signal?.aborted) return;
       this.#status.lastError = error?.message ?? String(error);

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

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 
+import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { deriveQqBotIdentity, maskQqAppId } from './config-store.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set(['starting', 'pending', 'refreshing', 'connecting']);
@@ -248,6 +249,23 @@ export class QqController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown QQ bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        const error = new Error('QQ机器人尚未连接');
+        error.code = 'test-target-unavailable';
+        throw error;
+      }
+      await runtime.sendConnectionTest(connectionTestMessage(
+        `QQ 机器人（${maskQqAppId(config.appId)}）`,
+      ));
+      return { sent: true };
+    });
+  }
+
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown QQ bot');

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

@@ -1,5 +1,9 @@
 import { QQBot, typingIndicator } from '@tencent-connect/qqbot-nodejs';
 
+import {
+  connectionTestTarget,
+  connectionTestTargetUnavailable,
+} from '../shared/connection-test.mjs';
 import { createQqBridgeStatus, QqHarnessBridge } from './qq-bridge.mjs';
 
 function timeoutError() {
@@ -67,6 +71,28 @@ export class QqRuntime {
     return structuredClone(this.#status);
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#bot) {
+      throw connectionTestTargetUnavailable('QQ机器人');
+    }
+    const ownerUserOpenid = typeof this.#config.ownerUserOpenid === 'string'
+      ? this.#config.ownerUserOpenid.trim()
+      : '';
+    const remembered = connectionTestTarget(this.#state);
+    const rememberedUserOpenid = remembered?.scope === 'c2c'
+      && typeof remembered.targetId === 'string'
+      ? remembered.targetId.trim()
+      : '';
+    const target = rememberedUserOpenid
+      ? { scope: 'c2c', targetId: rememberedUserOpenid }
+      : (ownerUserOpenid && ownerUserOpenid !== '*'
+        ? { scope: 'c2c', targetId: ownerUserOpenid }
+        : null);
+    if (!target) throw connectionTestTargetUnavailable('QQ机器人');
+    await this.#bot.sendText(target, text);
+    return { sent: true };
+  }
+
   async start() {
     if (this.#status.ready && this.#bot) return this.status;
     if (this.#starting) return this.#starting;