@xmanrui/dsh-im 4.22.0 → 4.23.0

package/src/channels/email/transports/agently-cli.mjs

@@ -0,0 +1,288 @@
+/**
+ * Runs the official `agently-cli` and returns its JSON.
+ *
+ * The CLI owns the Agent mailbox protocol, including OAuth and the token
+ * refresh. A hand-written client could not refresh: the server issued an
+ * access token that worked while the matching refresh token was rejected with
+ * `invalid_grant` the moment it was used, so the mailbox died an hour after
+ * every authorization. The CLI keeps credentials in the system keychain, tracks
+ * `expires_at`, refreshes ahead of expiry, and re-authorizes a watcher that has
+ * gone stale — none of which is reproducible from outside.
+ *
+ * Contract notes learned from the binary and its own schemas:
+ *   - stdout carries the JSON document; the `tip:` lines go to stderr.
+ *   - The exit code is 0 even for an error document, so `ok` is the only
+ *     reliable success signal.
+ *   - A `--print-output-schema` flag documents every command's fields.
+ */
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+/** Platform-specific binaries, mirroring the CLI's own packaging. */
+const PLATFORM_PACKAGES = {
+  'darwin-arm64': '@tencent-qqmail/agently-cli-darwin-arm64',
+  'darwin-x64': '@tencent-qqmail/agently-cli-darwin-x64',
+  'linux-arm64': '@tencent-qqmail/agently-cli-linux-arm64',
+  'linux-x64': '@tencent-qqmail/agently-cli-linux-x64',
+  'win32-arm64': '@tencent-qqmail/agently-cli-win32-arm64',
+  'win32-x64': '@tencent-qqmail/agently-cli-win32-x64',
+};
+
+/** How long a single CLI invocation may run before it is abandoned. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export class AgentMailCliError extends Error {
+  constructor(message, { code = 'cli-failed', status = null, detail = null, cause } = {}) {
+    super(message, { cause });
+    this.name = 'AgentMailCliError';
+    this.code = code;
+    if (status !== null) this.status = status;
+    if (detail !== null) this.detail = detail;
+  }
+}
+
+/**
+ * Resolve the CLI binary.
+ *
+ * The bundled platform package is preferred so a working install never depends
+ * on a global one; `agently-cli` on the PATH is the fallback for a user who
+ * installed it themselves.
+ */
+export function resolveCliBinary() {
+  const platformPackage = PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
+  if (platformPackage) {
+    try {
+      const resolved = require.resolve(`${platformPackage}/package.json`);
+      const name = process.platform === 'win32' ? 'agently-cli.exe' : 'agently-cli';
+      return { command: join(dirname(resolved), 'bin', name), source: 'bundled' };
+    } catch {
+      // Fall through to the wrapper, then PATH.
+    }
+  }
+  try {
+    const wrapper = require.resolve('@tencent-qqmail/agently-cli/package.json');
+    return { command: join(dirname(wrapper), 'scripts', 'run.js'), source: 'wrapper' };
+  } catch {
+    return { command: 'agently-cli', source: 'path' };
+  }
+}
+
+/** Whether the CLI can be launched at all. */
+export function isCliAvailable() {
+  const { command, source } = resolveCliBinary();
+  if (source === 'path') return false;
+  return Boolean(command);
+}
+
+/**
+ * Start `auth login` and resolve as soon as it prints the authorization URL.
+ *
+ * The command then blocks until the user completes the scan, so it is left
+ * running rather than waited on; the caller polls `auth status` to observe the
+ * outcome, and the process exits on its own once the scan lands or it expires.
+ */
+export function startCliLogin({ signal, timeoutMs = 30_000, env = {}, workspace } = {}) {
+  const { command } = resolveCliBinary();
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, ['auth', 'login'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...cliEnv(workspace), ...env },
+      });
+    } catch (error) {
+      reject(new AgentMailCliError(`unable to launch agently-cli: ${error.message}`, {
+        code: 'cli-unavailable', cause: error,
+      }));
+      return;
+    }
+
+    let settled = false;
+    let buffered = '';
+    const stop = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+    };
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+        if (settled) return;
+        stop();
+        reject(new AgentMailCliError('agently-cli printed no authorization URL', {
+          code: 'authorization-url-missing', detail: buffered.slice(0, 400),
+        }));
+      }, timeoutMs)
+      : null;
+    timer?.unref?.();
+
+    const onAbort = () => {
+      child.kill('SIGTERM');
+      stop();
+      reject(new AgentMailCliError('authorization aborted', { code: 'cli-aborted' }));
+    };
+    if (signal) {
+      if (signal.aborted) { onAbort(); return; }
+      signal.addEventListener?.('abort', onAbort, { once: true });
+    }
+
+    const scan = (chunk) => {
+      buffered += chunk;
+      const url = /https:\/\/agent\.qq\.com\/page\/oauth\S*/.exec(buffered)?.[0];
+      if (!url) return;
+      stop();
+      // The process keeps running so the scan can complete; it is detached from
+      // this promise on purpose.
+      resolve({ browserUrl: url, inputCode: /user_code=([^&\s]+)/.exec(url)?.[1] ?? '', child });
+    };
+    child.stdout.on('data', (chunk) => scan(String(chunk)));
+    child.stderr.on('data', (chunk) => scan(String(chunk)));
+    child.on('error', (error) => {
+      stop();
+      reject(new AgentMailCliError(`agently-cli failed to start: ${error.message}`, {
+        code: 'cli-unavailable', cause: error,
+      }));
+    });
+    child.on('close', () => {
+      if (settled) return;
+      stop();
+      reject(new AgentMailCliError('agently-cli exited before printing an authorization URL', {
+        code: 'authorization-url-missing', detail: buffered.slice(0, 400),
+      }));
+    });
+  });
+}
+
+/**
+ * Run the CLI and parse its JSON document.
+ *
+ * `input` is written to stdin, which is how a body avoids both the argument
+ * list and the shell.
+ */
+/**
+ * The environment a CLI call runs with.
+ *
+ * The CLI isolates accounts by workspace, so a mailbox is addressed by its own
+ * workspace name. Without this every Agent mailbox shared one login and the
+ * second one always read the first one's account.
+ */
+export function cliEnv(workspace) {
+  return workspace ? { AGENTLY_WORKSPACE: String(workspace) } : {};
+}
+
+export function runCli(args, {
+  input = null, timeoutMs = DEFAULT_TIMEOUT_MS, signal, env = {},
+} = {}) {
+  const { command, source } = resolveCliBinary();
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...env },
+      });
+    } catch (error) {
+      reject(new AgentMailCliError(`unable to launch agently-cli (${source}): ${error.message}`, {
+        code: 'cli-unavailable', cause: error,
+      }));
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      fn(value);
+    };
+
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+        child.kill('SIGTERM');
+        finish(reject, new AgentMailCliError(`agently-cli timed out after ${timeoutMs}ms`, {
+          code: 'cli-timeout',
+        }));
+      }, timeoutMs)
+      : null;
+    timer?.unref?.();
+
+    const onAbort = () => {
+      child.kill('SIGTERM');
+      finish(reject, new AgentMailCliError('agently-cli aborted', { code: 'cli-aborted' }));
+    };
+    if (signal) {
+      if (signal.aborted) { onAbort(); return; }
+      signal.addEventListener?.('abort', onAbort, { once: true });
+    }
+
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => {
+      finish(reject, new AgentMailCliError(`agently-cli failed to start: ${error.message}`, {
+        code: 'cli-unavailable', cause: error,
+      }));
+    });
+    child.on('close', (exitCode) => {
+      // The exit code is 0 even for an error document, so `ok` decides.
+      let document = null;
+      const text = stdout.trim();
+      if (text) {
+        try {
+          document = JSON.parse(text);
+        } catch {
+          finish(reject, new AgentMailCliError('agently-cli returned unparseable output', {
+            code: 'cli-invalid-output', detail: text.slice(0, 400),
+          }));
+          return;
+        }
+      }
+      if (document && document.ok === false) {
+        const failure = document.error ?? {};
+        finish(reject, new AgentMailCliError(
+          String(failure.message ?? 'agently-cli reported a failure'),
+          {
+            code: String(failure.type ?? 'cli-failed'),
+            status: typeof failure.status === 'number' ? failure.status : null,
+            detail: failure,
+          },
+        ));
+        return;
+      }
+      if (!document) {
+        finish(reject, new AgentMailCliError(
+          `agently-cli produced no output (exit ${exitCode})`,
+          { code: 'cli-empty-output', detail: stderr.trim().slice(0, 400) },
+        ));
+        return;
+      }
+      finish(resolve, { document, stdout, stderr, exitCode });
+    });
+
+    if (input !== null) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+/**
+ * Run the CLI through an injected implementation.
+ *
+ * Exists so tests can drive the failure and confirmation paths without a real
+ * binary; production always goes through `runCli`.
+ */
+export async function runCliDocumentForTests(args, { runCliImpl, input = null } = {}) {
+  const result = await runCliImpl(args, { input });
+  if (result.document && result.document.ok === false) {
+    const failure = result.document.error ?? {};
+    throw new AgentMailCliError(String(failure.message ?? 'agently-cli reported a failure'), {
+      code: String(failure.type ?? 'cli-failed'), detail: failure,
+    });
+  }
+  return result;
+}

package/src/channels/email/transports/imap-smtp.mjs

@@ -0,0 +1,165 @@
+/**
+ * Standard mailbox transport: IMAP receive + SMTP send.
+ *
+ * One dedicated mailbox (the bot identity). Inbound mail is polled over IMAP;
+ * replies go back over SMTP inside the same mail thread. Everything above the
+ * transport — thread mapping, allowlist, quote stripping, loop prevention —
+ * is shared with every other transport.
+ */
+import { ImapFlow } from 'imapflow';
+import { simpleParser } from 'mailparser';
+import nodemailer from 'nodemailer';
+
+import {
+  MAX_REPLY_CHARS, imapSecurity, normalizeAddress, smtpSecurity,
+} from '../mail-format.mjs';
+
+export class ImapSmtpTransport {
+  #config;
+  #signal;
+  #imap = null;
+  #transport = null;
+
+  constructor({ config, signal } = {}) {
+    if (!config?.address || !config?.password) {
+      throw new TypeError('ImapSmtpTransport requires an address and password');
+    }
+    this.#config = config;
+    this.#signal = signal;
+  }
+
+  get address() {
+    return this.#config.address;
+  }
+
+  /** Open the IMAP connection and select the monitored mailbox. */
+  async connect() {
+    if (this.#imap) return;
+    const client = new ImapFlow({
+      host: this.#config.imapHost,
+      port: this.#config.imapPort,
+      ...imapSecurity(this.#config.imapPort, this.#config.imapSecure),
+      auth: { user: this.#config.address, pass: this.#config.password },
+      logger: false,
+      ...(this.#config.rejectUnauthorized === false ? { tls: { rejectUnauthorized: false } } : {}),
+    });
+    client.on('error', () => { /* surfaced by the caller's poll/connection state */ });
+    await client.connect();
+    await client.mailboxOpen(this.#config.mailbox ?? 'INBOX');
+    this.#imap = client;
+  }
+
+  async disconnect() {
+    const client = this.#imap;
+    this.#imap = null;
+    if (client) await client.logout().catch(() => client.close?.());
+  }
+
+  /** Highest UID currently in the mailbox, used to skip pre-existing mail. */
+  async latestUid() {
+    await this.connect();
+    const status = await this.#imap.status(this.#config.mailbox ?? 'INBOX', { uidNext: true, messages: true });
+    const next = Number(status?.uidNext);
+    return Number.isFinite(next) && next > 1 ? next - 1 : 0;
+  }
+
+  /**
+   * Fetch messages with a UID greater than `afterUid`.
+   *
+   * The sender is read from the lightweight envelope first and checked against
+   * `allowSenders` before the body is requested. A monitored mailbox also
+   * receives ordinary personal mail, and that content must not be downloaded
+   * or parsed at all — not merely filtered after the fact.
+   */
+  async listMessages({ afterUid = 0, limit = 25, allowSenders = null } = {}) {
+    await this.connect();
+    const mailbox = this.#config.mailbox ?? 'INBOX';
+    // A Set — even an empty one — means the caller supplied a policy: an
+    // empty allowlist admits nobody, so no body is fetched at all. Treating
+    // it as "no filter" downloaded mail the policy had already refused.
+    const allowed = allowSenders instanceof Set ? allowSenders : null;
+
+    // Step 1: read only the lightweight envelopes. ImapFlow cannot run a second
+    // fetch while one is being iterated, so the accepted UIDs are collected
+    // first and their bodies pulled afterwards.
+    const accepted = [];
+    for await (const message of this.#imap.fetch(
+      { uid: `${afterUid + 1}:*` },
+      { uid: true, envelope: true },
+      { uid: true },
+    )) {
+      // A range fetch that matches nothing still yields the last message, so
+      // the UID bound is re-checked here.
+      if (!Number.isFinite(message.uid) || message.uid <= afterUid) continue;
+      if (allowed) {
+        const from = normalizeAddress(message.envelope?.from?.[0]?.address);
+        if (!from || !allowed.has(from)) continue;
+      }
+      accepted.push(message.uid);
+      if (accepted.length >= limit) break;
+    }
+
+    // Step 2: fetch and parse the bodies of accepted senders only. Mail from
+    // anyone else is never downloaded, so its content is not read at all.
+    const found = [];
+    for (const uid of accepted) {
+      const source = await this.#fetchSource(uid);
+      if (!source) continue;
+      const parsed = await simpleParser(source);
+      // Carry the UID alongside the parsed mail: it is the polling cursor and
+      // is not part of the RFC822 source.
+      parsed.uid = uid;
+      found.push(parsed);
+    }
+    await this.#imap.mailboxOpen(mailbox, { readOnly: false }).catch(() => {});
+    return found;
+  }
+
+  /** Read one message's RFC822 source by UID. */
+  async #fetchSource(uid) {
+    try {
+      const message = await this.#imap.fetchOne(String(uid), { source: true }, { uid: true });
+      return message?.source ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Send a reply inside the originating thread. */
+  async sendReply({ to, subject, text, inReplyTo, references, attachments = [] } = {}) {
+    const body = String(text ?? '').slice(0, MAX_REPLY_CHARS);
+    const transport = await this.#transportFor();
+    const info = await transport.sendMail({
+      from: this.#config.from ?? this.#config.address,
+      to,
+      subject: subject || '(no subject)',
+      text: body,
+      // RFC 3834: mark this as an automatic reply so any bot on the other side
+      // (including this mailbox replying to itself) can refuse to auto-answer
+      // it. That is the standard loop break, and it lets a mailbox accept its
+      // own address as a sender without risking an endless exchange.
+      headers: { 'Auto-Submitted': 'auto-replied' },
+      ...(inReplyTo ? { inReplyTo } : {}),
+      ...(references?.length ? { references: references.join(' ') } : {}),
+      ...(attachments.length ? { attachments } : {}),
+    });
+    return { sent: true, messageId: info?.messageId ?? null };
+  }
+
+  /** Send a standalone message (proactive delivery, no thread). */
+  async sendText({ to, subject, text, attachments = [] } = {}) {
+    return this.sendReply({ to, subject, text, attachments });
+  }
+
+  async #transportFor() {
+    if (this.#transport) return this.#transport;
+    this.#transport = nodemailer.createTransport({
+      host: this.#config.smtpHost,
+      port: this.#config.smtpPort,
+      ...smtpSecurity(this.#config.smtpPort, this.#config.smtpSecure),
+      auth: { user: this.#config.address, pass: this.#config.password },
+      ...(this.#config.rejectUnauthorized === false ? { tls: { rejectUnauthorized: false } } : {}),
+    });
+    return this.#transport;
+  }
+}

package/src/channels/feishu/bridge.mjs

@@ -4062,7 +4062,7 @@ export class FeishuHarnessBridge {
     await Promise.allSettled(sessionIds.map((sessionId) => this.#scheduleCompensation(sessionId)));
   }
 
-  #interactionAskOptions(event, key, files) {
+  #interactionAskOptions(event, key, files, images) {
     return {
       timeoutMs: this.#replyTimeoutMs,
       signal: this.#signal,
@@ -4076,6 +4076,7 @@ export class FeishuHarnessBridge {
       }),
       onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
       files,
+      images,
     };
   }
 
@@ -4894,7 +4895,7 @@ export class FeishuHarnessBridge {
     // 的上下文增强按原样重放。直推分流发生在 `#answerWithStream` 构造之前，
     // 这里就是本回合唯一一次构造（无重复的 prompt 往返）。
     let content = hasInboundImages(message) || hasReplyReference(message)
-      ? await promptContentForInboundMessage(message, { signal: this.#signal })
+      ? await promptContentForInboundMessage(message, { signal: this.#signal, deferImages: true })
       : undefined;
     const snapshot = this.#acceptedMessageIds.get(messageId);
     let contextEnhanced = false;
@@ -4940,7 +4941,7 @@ export class FeishuHarnessBridge {
     // /stop 打标：回合进行中收到停止请求时，封存为「已停止」而非「已完成」。
     const stepStopFlag = streamingCard ? { requested: false } : null;
     if (streamingCard) this.#stepStopFlags.set(key, stepStopFlag);
-    const baseAskOptions = this.#interactionAskOptions(event, key, message.files);
+    const baseAskOptions = this.#interactionAskOptions(event, key, message.files, message.images);
 
     // 上下文注入动作在详细级别下也体现为一条步骤（注入细节可忽略）。
     // 不计入工具/助手消息的熔断计数（规格口径：熔断只管「工具 + 助手」）。
@@ -5214,7 +5215,7 @@ export class FeishuHarnessBridge {
       return this.#answerWithStepPush(event, key, message, { onAskComplete });
     }
     let content = hasInboundImages(message) || hasReplyReference(message)
-      ? await promptContentForInboundMessage(message, { signal: this.#signal })
+      ? await promptContentForInboundMessage(message, { signal: this.#signal, deferImages: true })
       : undefined;
     const snapshot = this.#acceptedMessageIds.get(messageId);
     let contextEnhanced = false;
@@ -5241,7 +5242,7 @@ export class FeishuHarnessBridge {
         contextEnhanced,
         createOptions: { signal: this.#signal },
         existsOptions: { signal: this.#signal },
-        askOptions: this.#interactionAskOptions(event, key, message.files),
+        askOptions: this.#interactionAskOptions(event, key, message.files, message.images),
       });
       markAskComplete();
       let textReceipt;
@@ -5285,7 +5286,7 @@ export class FeishuHarnessBridge {
       stream = await this.#channel.stream(chatId, {
         markdown: async (controller) => {
           promptStarted = true;
-          const baseAskOptions = this.#interactionAskOptions(event, key, message.files);
+          const baseAskOptions = this.#interactionAskOptions(event, key, message.files, message.images);
           const askOptions = {
             ...baseAskOptions,
             // issue #86：独立交互消息（提问/审批）会落在占位卡下方，呈现前
@@ -5394,7 +5395,7 @@ export class FeishuHarnessBridge {
         contextEnhanced,
         createOptions: { signal: this.#signal },
         existsOptions: { signal: this.#signal },
-        askOptions: this.#interactionAskOptions(event, key, message.files),
+        askOptions: this.#interactionAskOptions(event, key, message.files, message.images),
       });
       markAskComplete();
       let textReceipt;

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

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 import { FeishuHarnessBridge } from './bridge.mjs';
 import { cardActionProbeCard } from './feishu-cards.mjs';
@@ -125,6 +126,7 @@ export class FeishuRuntime {
   #requestTimeoutMs;
   #wsAgent;
   #logger;
+  #diagnostics;
   #repair;
   #client = null;
   #bridge = null;
@@ -200,7 +202,7 @@ export class FeishuRuntime {
     this.#requestTimeoutMs = requestTimeoutMs;
     this.#slashCommands = Boolean(slashCommands);
     this.#wsAgent = wsAgent;
-    this.#logger = logger;
+    this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'feishu', logger });
     this.#status = createBridgeStatus({ allowedSenderCount: normalizedOwners.length });
   }
 
@@ -277,10 +279,10 @@ export class FeishuRuntime {
     };
     this.#status.startedAt = new Date().toISOString();
     this.#status.feishuLongConnectionState = 'connecting';
-    this.#status.lastError = null;
+    this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
 
     try {
-      await this.#harness.ensureRunning({ signal });
+      await atConnectionStage('harness.check', () => this.#harness.ensureRunning({ signal }));
       assertCurrentStart();
       this.#status.harnessReachable = true;
 
@@ -391,15 +393,16 @@ export class FeishuRuntime {
           if (!isCurrentStart()) return;
           this.#status.feishuLongConnectionState = 'connected';
           this.#status.ready = true;
-          this.#status.lastError = null;
+          this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
           settleReady();
         },
         onError: (error) => {
           if (!isCurrentStart()) return;
           this.#status.feishuLongConnectionState = 'failed';
           this.#status.ready = false;
-          this.#status.lastError = error?.message ?? String(error);
-          this.#logger.error('[dsh-feishu] Feishu long connection failed:', this.#status.lastError);
+          this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#botId, automatic: true }).publicError;
+          this.#status.lastError = this.#status.error.message;
+
           settleError(error);
         },
         onReconnecting: () => {
@@ -411,7 +414,7 @@ export class FeishuRuntime {
           if (!isCurrentStart()) return;
           this.#status.feishuLongConnectionState = 'connected';
           this.#status.ready = true;
-          this.#status.lastError = null;
+          this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
         },
       });
       this.#wsClient = wsClient;
@@ -436,7 +439,8 @@ export class FeishuRuntime {
       if (signal.aborted) throw error;
       this.#status.ready = false;
       this.#status.feishuLongConnectionState = 'failed';
-      this.#status.lastError = error?.message ?? String(error);
+      this.#status.error = this.#diagnostics.report(error, { operation: 'connection.restore', reuse: true, botId: this.#botId, automatic: true }).publicError;
+      this.#status.lastError = this.#status.error.message;
       await this.#cleanup({ preserveError: true, abortController });
       throw error;
     }
@@ -720,6 +724,7 @@ export class FeishuRuntime {
 
   async #cleanup({ preserveError = false, abortController } = {}) {
     const error = preserveError ? this.#status.lastError : null;
+    const diagnostic = preserveError ? this.#status.error : null;
     if (this.#abortController === abortController) this.#abortController = null;
     abortController?.abort(new DOMException('Feishu runtime stopped', 'AbortError'));
     for (const probe of this.#pendingCardActionProbes.values()) {
@@ -742,7 +747,9 @@ export class FeishuRuntime {
     this.#client = null;
     this.#status.feishuLongConnectionState = preserveError ? 'failed' : 'idle';
     this.#status.slashCommandRegistration = 'idle';
+    this.#status.error = diagnostic;
     this.#status.lastError = error;
+    if (!preserveError) this.#diagnostics.clear();
     return this.status;
   }
 }

package/src/channels/feishu/group-message-permission-manager.mjs

@@ -27,7 +27,7 @@ export class GroupMessagePermissionManager {
   #appId;
   #domain;
 
-  constructor({ registerApp, onCredentials, appId, domain = 'feishu' } = {}) {
+  constructor({ registerApp, onCredentials, appId, domain = 'feishu', diagnostics } = {}) {
     if (typeof registerApp !== 'function') throw new TypeError('registerApp is required');
     if (typeof onCredentials !== 'function') throw new TypeError('onCredentials is required');
     if (typeof appId !== 'string' || !appId.trim()) throw new TypeError('appId is required');
@@ -36,6 +36,7 @@ export class GroupMessagePermissionManager {
     this.#appId = appId.trim();
     this.#domain = domain;
     this.#manager = new RegistrationManager({
+      diagnostics,
       registerApp: (options) => registerApp({
         ...options,
         onQRCodeReady: (info) => {

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

@@ -1,3 +1,4 @@
+import { imageDownloadLimitMessage } from '../shared/image-prompt.mjs';
 import { ImagePromptError } from '../shared/image-prompt.mjs';
 import { t } from '../shared/i18n.mjs';
 
@@ -256,7 +257,7 @@ async function readBoundedStream(stream, { signal, maxBytes }) {
         throw new ImagePromptError(
           'image-too-large',
           `Feishu image exceeds ${maxBytes} bytes`,
-          t('图片超过 5 MB，请压缩后重试。'),
+          imageDownloadLimitMessage(maxBytes),
         );
       }
       chunks.push(data);
@@ -392,7 +393,7 @@ function feishuImageSource(event, client, key) {
         throw new ImagePromptError(
           'image-too-large',
           `Feishu image declares ${size} bytes; the limit is ${maxBytes}`,
-          t('图片超过 5 MB，请压缩后重试。'),
+          imageDownloadLimitMessage(maxBytes),
         );
       }
       return readBoundedStream(resource?.getReadableStream?.(), { signal, maxBytes });