You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by wy...@apache.org on 2026/09/22 22:11:47 UTC

(maka) branch feat/runtime-host-rust updated: fix(desktop): expose recoverable bot onboarding retries

This is an automated email from the ASF dual-hosted git repository.

M4n5ter pushed a commit to branch feat/runtime-host-rust
in repository https://gitbox.apache.org/repos/asf/maka.git


The following commit(s) were added to refs/heads/feat/runtime-host-rust by this push:
     new b293818504 fix(desktop): expose recoverable bot onboarding retries
b293818504 is described below

commit b293818504d8a2733e05c3f2c1df48a9e4781a0c
Author: Wang <m4...@gmail.com>
AuthorDate: Wed Sep 23 06:11:42 2026 +0800

    fix(desktop): expose recoverable bot onboarding retries
    
    Generated-by: Codex
---
 .../src/main/__tests__/bot-onboarding-main.test.ts | 200 +++++++++++++++++++++
 .../__tests__/bot-onboarding-status-copy.test.ts   |  58 ++++++
 apps/desktop/src/main/bot-onboarding-main.ts       |  65 +++++--
 .../src/renderer/locales/settings-bot-copy.ts      |  76 +++++++-
 .../src/renderer/settings/bot-onboarding-modal.tsx |  33 +---
 packages/core/src/bot-onboarding.ts                |  10 ++
 packages/core/src/redaction.ts                     |   5 +
 7 files changed, 397 insertions(+), 50 deletions(-)

diff --git a/apps/desktop/src/main/__tests__/bot-onboarding-main.test.ts b/apps/desktop/src/main/__tests__/bot-onboarding-main.test.ts
index 60603532c6..c61a1321d0 100644
--- a/apps/desktop/src/main/__tests__/bot-onboarding-main.test.ts
+++ b/apps/desktop/src/main/__tests__/bot-onboarding-main.test.ts
@@ -422,6 +422,30 @@ describe('BotOnboardingService', () => {
     assert.equal(connected.warningCode, undefined);
   });
 
+  it('does not advertise poll retry health for post-confirmation failures', async () => {
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { return startResult(); },
+      async poll() {
+        return {
+          status: 'confirmed',
+          credential: {
+            provider: 'dingtalk',
+            clientId: 'public-client-id',
+            clientSecret: 'private-client-secret',
+          },
+        };
+      },
+    };
+    const test = harness(adapter, async () => {
+      throw Object.assign(new Error('The operation timed out'), { name: 'TimeoutError' });
+    });
+    const started = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const result = await test.service.poll(started.sessionId);
+    assert.equal(result.state, 'error');
+    assert.equal(result.retryHealth, undefined);
+  });
+
   it('invalidates an older session when the same provider starts again', async () => {
     const pending = deferred<any>();
     let polls = 0;
@@ -527,6 +551,10 @@ describe('BotOnboardingService', () => {
     const afterFirst = await test.service.poll(started.sessionId);
     assert.equal(afterFirst.state, 'waiting', 'a single transient blip must not kill the session');
     assert.equal(attempts, 1);
+    assert.deepEqual(afterFirst.retryHealth, {
+      category: 'timeout',
+      consecutiveFailures: 1,
+    });
 
     let last = afterFirst;
     for (let i = 0; i < 12 && last.state !== 'error'; i += 1) {
@@ -534,6 +562,176 @@ describe('BotOnboardingService', () => {
       last = await test.service.poll(started.sessionId);
     }
     assert.equal(last.state, 'error', 'repeated consecutive transient failures must go terminal');
+    assert.equal(last.retryHealth, undefined, 'terminal sessions must not advertise another retry');
+  });
+
+  for (const status of ['pending', 'scanned', 'slow_down'] as const) {
+    it(`wakes at QR expiry after a ${status} provider response`, async () => {
+      let polls = 0;
+      const adapter: BotOnboardingProviderAdapter = {
+        async start() { return { ...startResult(), expiresInSeconds: 6 }; },
+        async poll() { polls += 1; return { status }; },
+      };
+      const test = harness(adapter);
+      const started = await test.service.start({ provider: 'dingtalk' });
+      test.advance(5_000);
+      const response = await test.service.poll(started.sessionId);
+      assert.equal(response.state, status === 'scanned' ? 'scanned' : 'waiting');
+      assert.equal(response.nextPollAfterMs, 1_000);
+      test.advance(1_000);
+      assert.equal((await test.service.poll(started.sessionId)).state, 'expired');
+      assert.equal(polls, 1);
+    });
+  }
+
+  for (const expiresInSeconds of [6, 12]) {
+    it(`does not promise a retry when backoff reaches the QR expiry (${expiresInSeconds}s)`, async () => {
+      let polls = 0;
+      const adapter: BotOnboardingProviderAdapter = {
+        async start() { return { ...startResult(), expiresInSeconds }; },
+        async poll() {
+          polls += 1;
+          throw new Error('HTTP 503 provider unavailable');
+        },
+      };
+      const test = harness(adapter);
+      const started = await test.service.start({ provider: 'dingtalk' });
+      test.advance(5_000);
+      const backingOff = await test.service.poll(started.sessionId);
+      assert.equal(backingOff.state, 'waiting');
+      assert.equal(backingOff.retryHealth, undefined);
+      const untilExpiry = expiresInSeconds * 1_000 - 5_000;
+      assert.equal(backingOff.nextPollAfterMs, untilExpiry);
+
+      test.advance(untilExpiry - 1);
+      assert.equal((await test.service.poll(started.sessionId)).state, 'waiting');
+      assert.equal(polls, 1);
+      test.advance(1);
+      const expired = await test.service.poll(started.sessionId);
+      assert.equal(expired.state, 'expired');
+      assert.equal(expired.retryHealth, undefined);
+      assert.equal(polls, 1, 'the expired code must never be polled again');
+    });
+  }
+
+  it('expires when an in-flight transient poll fails after the QR deadline', async () => {
+    const pending = deferred<never>();
+    let polls = 0;
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { return { ...startResult(), expiresInSeconds: 6 }; },
+      async poll() { polls += 1; return pending.promise; },
+    };
+    const test = harness(adapter);
+    const started = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const inFlight = test.service.poll(started.sessionId);
+    test.advance(1_001);
+    pending.reject(new Error('fetch failed'));
+    const expired = await inFlight;
+    assert.equal(expired.state, 'expired');
+    assert.equal(expired.retryHealth, undefined);
+    assert.equal(polls, 1);
+  });
+
+  it('projects only a finite redacted category and clears retry health after recovery', async () => {
+    let attempts = 0;
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { return startResult(); },
+      async poll() {
+        attempts += 1;
+        if (attempts === 1) {
+          throw new Error('HTTP 503 https://provider.example/poll?token=super-secret credential=hidden');
+        }
+        return { status: 'pending' };
+      },
+    };
+    const test = harness(adapter);
+    const started = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const backingOff = await test.service.poll(started.sessionId);
+    assert.deepEqual(backingOff.retryHealth, {
+      category: 'server',
+      consecutiveFailures: 1,
+    });
+    assert.equal(JSON.stringify(backingOff).includes('super-secret'), false);
+    assert.equal(JSON.stringify(backingOff).includes('provider.example'), false);
+
+    test.advance(7_000);
+    const recovered = await test.service.poll(started.sessionId);
+    assert.equal(recovered.state, 'waiting');
+    assert.equal(recovered.retryHealth, undefined);
+  });
+
+  it('clears retry health on provider terminal responses and cancellation', async () => {
+    let attempts = 0;
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { return startResult(); },
+      async poll() {
+        attempts += 1;
+        if (attempts === 1) throw new Error('HTTP 429 rate limited');
+        return { status: 'denied', error: 'Provider denied authorization' };
+      },
+    };
+    const test = harness(adapter);
+    const first = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const backingOff = await test.service.poll(first.sessionId);
+    assert.equal(backingOff.retryHealth?.category, 'rate_limited');
+    assert.equal(test.service.cancel(first.sessionId).retryHealth, undefined);
+
+    attempts = 0;
+    const second = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    assert.equal((await test.service.poll(second.sessionId)).retryHealth?.category, 'rate_limited');
+    test.advance(7_000);
+    const denied = await test.service.poll(second.sessionId);
+    assert.equal(denied.state, 'denied');
+    assert.equal(denied.retryHealth, undefined);
+    assert.equal((await test.service.poll(second.sessionId)).retryHealth, undefined);
+  });
+
+  it('does not project a late transient failure after session supersession', async () => {
+    const pending = deferred<never>();
+    let starts = 0;
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { starts += 1; return startResult(); },
+      async poll() { return pending.promise; },
+    };
+    const test = harness(adapter);
+    const first = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const stalePoll = test.service.poll(first.sessionId);
+    await test.service.start({ provider: 'dingtalk' });
+    assert.equal(starts, 2);
+    pending.reject(new Error('network token=late-super-secret'));
+    const superseded = await stalePoll;
+    assert.equal(superseded.state, 'cancelled');
+    assert.equal(superseded.retryHealth, undefined);
+    assert.equal(JSON.stringify(superseded).includes('late-super-secret'), false);
+  });
+
+  it('clears network retry health when the next poll fails authentication', async () => {
+    let attempts = 0;
+    const adapter: BotOnboardingProviderAdapter = {
+      async start() { return startResult(); },
+      async poll() {
+        attempts += 1;
+        throw new Error(attempts === 1 ? 'fetch failed' : 'HTTP 401 unauthorized after network timeout');
+      },
+    };
+    const test = harness(adapter);
+    const started = await test.service.start({ provider: 'dingtalk' });
+    test.advance(5_000);
+    const retry = await test.service.poll(started.sessionId);
+    assert.equal(retry.state, 'waiting');
+    assert.equal(retry.retryHealth?.category, 'network');
+    test.advance(retry.nextPollAfterMs);
+    const failed = await test.service.poll(started.sessionId);
+    assert.equal(failed.state, 'error');
+    assert.equal(failed.errorCode, 'auth_failed');
+    assert.equal(failed.retryHealth, undefined);
+    await test.service.poll(started.sessionId);
+    assert.equal(attempts, 2);
   });
 
   it('fails immediately on a fatal (non-transient) poll error', async () => {
@@ -556,9 +754,11 @@ describe('BotOnboardingService', () => {
     };
     const test = harness(adapter);
     const started = await test.service.start({ provider: 'dingtalk' });
+    assert.equal(started.nextPollAfterMs, 1_000);
     test.advance(1_001);
     const expired = await test.service.poll(started.sessionId);
     assert.equal(expired.state, 'expired');
+    assert.equal(expired.retryHealth, undefined);
     assert.equal(polls, 0);
   });
 
diff --git a/apps/desktop/src/main/__tests__/bot-onboarding-status-copy.test.ts b/apps/desktop/src/main/__tests__/bot-onboarding-status-copy.test.ts
new file mode 100644
index 0000000000..9c41b779e1
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/bot-onboarding-status-copy.test.ts
@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import type { BotOnboardingSnapshot } from '@maka/core/bot-onboarding';
+import { botOnboardingStatusCopy, getBotSettingsCopy } from '../../renderer/locales/settings-bot-copy.js';
+
+test('provides concise localized retry health without provider error text', () => {
+  const zh = getBotSettingsCopy('zh-CN');
+  const en = getBotSettingsCopy('en');
+  assert.equal(
+    zh.onboarding.retrying('network', 2, 7),
+    '网络暂时异常;连续失败 2 次,约 7 秒后自动重试。',
+  );
+  assert.equal(
+    en.onboarding.retrying('network', 2, 7),
+    'The network is temporarily unavailable; 2 consecutive failures. Retrying automatically in about 7s.',
+  );
+});
+
+for (const locale of ['zh-CN', 'zh-TW', 'en'] as const) {
+  test(`retry presentation preserves scanned instructions and clears on recovery (${locale})`, () => {
+    const shared = getBotSettingsCopy(locale).onboarding;
+    const copy = shared.providers.dingtalk;
+    const snapshot: BotOnboardingSnapshot = {
+      sessionId: 'onboarding', provider: 'dingtalk', state: 'waiting',
+      nextPollAfterMs: 7_000, canOpenInBrowser: false,
+      retryHealth: { category: 'network', consecutiveFailures: 2 },
+    };
+    const retry = shared.retrying('network', 2, 7);
+    assert.equal(botOnboardingStatusCopy(snapshot, false, null, copy, locale), retry);
+    snapshot.state = 'scanned';
+    assert.equal(botOnboardingStatusCopy(snapshot, false, null, copy, locale), `${copy.scanned} ${retry}`);
+    assert.equal(botOnboardingStatusCopy(snapshot, true, null, copy, locale), shared.generating);
+    assert.equal(botOnboardingStatusCopy(snapshot, false, 'failed', copy, locale), 'failed');
+    delete snapshot.retryHealth;
+    assert.equal(botOnboardingStatusCopy(snapshot, false, null, copy, locale), copy.scanned);
+    snapshot.state = 'waiting';
+    assert.equal(botOnboardingStatusCopy(snapshot, false, null, copy, locale), copy.waiting);
+  });
+}
diff --git a/apps/desktop/src/main/bot-onboarding-main.ts b/apps/desktop/src/main/bot-onboarding-main.ts
index 516cc0bdbd..523e0160c0 100644
--- a/apps/desktop/src/main/bot-onboarding-main.ts
+++ b/apps/desktop/src/main/bot-onboarding-main.ts
@@ -25,6 +25,7 @@ import type {
   BotOnboardingBrand,
   BotOnboardingErrorCode,
   BotOnboardingProvider,
+  BotOnboardingRetryFailureCategory,
   BotOnboardingSnapshot,
   BotOnboardingStartInput,
   BotOnboardingState,
@@ -104,6 +105,7 @@ interface BotOnboardingSession {
   controller: AbortController;
   pollPromise?: Promise<BotOnboardingSnapshot>;
   pollFailures: number;
+  pollFailureCategory?: BotOnboardingRetryFailureCategory;
   identity?: { id?: string; displayName?: string };
   error?: string;
   errorCode?: BotOnboardingErrorCode;
@@ -189,7 +191,7 @@ export class BotOnboardingService {
       session.verificationUrl = result.verificationUrl;
       session.pollIntervalMs = clampPollInterval(result.pollIntervalMs);
       session.expiresAt = this.now() + Math.max(1, result.expiresInSeconds) * 1_000;
-      session.nextPollAt = this.now() + session.pollIntervalMs;
+      this.scheduleNextPoll(session);
       session.state = 'waiting';
       // PR1197 review (P2-13): the QR data URL is large; emit it only on the
       // start snapshot. The modal caches it and every subsequent poll snapshot
@@ -214,6 +216,7 @@ export class BotOnboardingService {
     }
     if (session.expiresAt !== undefined && session.expiresAt <= this.now()) {
       session.state = 'expired';
+      this.clearRetryHealth(session);
       return this.snapshot(session);
     }
     if (session.nextPollAt > this.now()) return this.snapshot(session);
@@ -248,24 +251,26 @@ export class BotOnboardingService {
   }
 
   private async pollOnce(session: BotOnboardingSession): Promise<BotOnboardingSnapshot> {
+    let providerPollSettled = false;
     try {
       const result = await this.adapters[session.provider].poll(session, session.controller.signal);
+      providerPollSettled = true;
       this.assertCurrent(session);
       // A response of any kind clears the transient-failure streak.
-      session.pollFailures = 0;
+      this.clearRetryHealth(session);
       switch (result.status) {
         case 'pending':
           session.state = 'waiting';
-          session.nextPollAt = this.now() + session.pollIntervalMs;
+          this.scheduleNextPoll(session);
           break;
         case 'scanned':
           session.state = 'scanned';
-          session.nextPollAt = this.now() + session.pollIntervalMs;
+          this.scheduleNextPoll(session);
           break;
         case 'slow_down':
           session.state = 'waiting';
           session.pollIntervalMs = Math.min(session.pollIntervalMs + 5_000, MAX_POLL_INTERVAL_MS);
-          session.nextPollAt = this.now() + session.pollIntervalMs;
+          this.scheduleNextPoll(session);
           break;
         case 'expired':
           session.state = 'expired';
@@ -304,14 +309,21 @@ export class BotOnboardingService {
       // retry with backoff until enough CONSECUTIVE failures accumulate; only
       // then surface a terminal error. A definite provider/protocol error is
       // fatal immediately.
-      if (isTransientPollError(error)) {
+      const failureCategory = providerPollSettled ? undefined : classifyTransientPollError(error);
+      if (failureCategory) {
+        if (session.expiresAt !== undefined && session.expiresAt <= this.now()) {
+          this.clearRetryHealth(session);
+          session.state = 'expired';
+          return this.snapshot(session);
+        }
         session.pollFailures += 1;
         if (session.pollFailures < MAX_CONSECUTIVE_POLL_FAILURES) {
           session.pollIntervalMs = Math.min(session.pollIntervalMs + 2_000, MAX_POLL_INTERVAL_MS);
-          session.nextPollAt = this.now() + session.pollIntervalMs;
+          session.pollFailureCategory = this.scheduleNextPoll(session) ? failureCategory : undefined;
           return this.snapshot(session);
         }
       }
+      this.clearRetryHealth(session);
       session.state = 'error';
       session.error = safeProviderError(error);
       session.errorCode = providerErrorCode(error);
@@ -432,6 +444,7 @@ export class BotOnboardingService {
 
   private cancelSession(session: BotOnboardingSession): void {
     if (!session.controller.signal.aborted) session.controller.abort();
+    this.clearRetryHealth(session);
     if (session.state !== 'connected' && session.state !== 'expired' && session.state !== 'denied') {
       session.state = 'cancelled';
     }
@@ -449,6 +462,18 @@ export class BotOnboardingService {
     if (!this.isCurrent(session)) throw new Error('Bot onboarding session is no longer active');
   }
 
+  /** Return true only when the next provider poll can run before QR expiry. */
+  private scheduleNextPoll(session: BotOnboardingSession): boolean {
+    const retryAt = this.now() + session.pollIntervalMs;
+    session.nextPollAt = Math.min(retryAt, session.expiresAt ?? retryAt);
+    return session.expiresAt === undefined || retryAt < session.expiresAt;
+  }
+
+  private clearRetryHealth(session: BotOnboardingSession): void {
+    session.pollFailures = 0;
+    session.pollFailureCategory = undefined;
+  }
+
   private snapshot(session: BotOnboardingSession, includeQrCode = false): BotOnboardingSnapshot {
     const state = session.state === 'starting' ? 'waiting' : session.state;
     return {
@@ -459,6 +484,14 @@ export class BotOnboardingService {
       ...(includeQrCode && session.qrCodeDataUrl ? { qrCodeDataUrl: session.qrCodeDataUrl } : {}),
       ...(session.expiresAt !== undefined ? { expiresAt: session.expiresAt } : {}),
       nextPollAfterMs: Math.max(0, session.nextPollAt - this.now()),
+      ...(session.pollFailureCategory && session.pollFailures > 0
+        ? {
+            retryHealth: {
+              category: session.pollFailureCategory,
+              consecutiveFailures: session.pollFailures,
+            },
+          }
+        : {}),
       canOpenInBrowser: Boolean(session.verificationUrl),
       ...(session.identity ? { identity: { ...session.identity } } : {}),
       ...(session.error ? { error: session.error } : {}),
@@ -509,19 +542,21 @@ function safeProviderError(error: unknown): string {
  * fault, server 5xx, or 429 rate limit) versus a fatal provider/protocol error.
  * User-initiated aborts are filtered out before this runs.
  */
-function isTransientPollError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  if (error.name === 'TimeoutError' || error.name === 'AbortError') return true;
+function classifyTransientPollError(error: unknown): BotOnboardingRetryFailureCategory | undefined {
+  if (!(error instanceof Error)) return undefined;
   const message = error.message.toLowerCase();
-  if (/fetch failed|network|socket|econn|enotfound|eai_again|und_err|timeout|timed out/.test(message)) {
-    return true;
-  }
   const httpMatch = message.match(/http (\d{3})/);
   if (httpMatch) {
     const status = Number(httpMatch[1]);
-    return status === 429 || status >= 500;
+    if (status === 429) return 'rate_limited';
+    if (status >= 500 && status < 600) return 'server';
+    return undefined;
+  }
+  if (error.name === 'TimeoutError' || error.name === 'AbortError' || /timeout|timed out/.test(message)) return 'timeout';
+  if (/fetch failed|network|socket|econn|enotfound|eai_again|und_err/.test(message)) {
+    return 'network';
   }
-  return false;
+  return undefined;
 }
 
 function channelPatchFromCredential(credential: OnboardingCredential): Partial<BotChannelSettings> {
diff --git a/apps/desktop/src/renderer/locales/settings-bot-copy.ts b/apps/desktop/src/renderer/locales/settings-bot-copy.ts
index a94f960ba7..2cc0f0f30b 100644
--- a/apps/desktop/src/renderer/locales/settings-bot-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-bot-copy.ts
@@ -20,7 +20,7 @@
 import type { StatusSemantic } from '@maka/ui';
 import type { BotProvider, BotReadinessState } from '@maka/core/bot-chat-settings';
 import type { BotStatusCode, BotTestErrorCode, WechatBridgeQrHintCode } from '@maka/runtime/bots';
-import type { BotOnboardingErrorCode } from '@maka/core/bot-onboarding';
+import type { BotOnboardingErrorCode, BotOnboardingProvider, BotOnboardingSnapshot, BotOnboardingRetryFailureCategory } from '@maka/core/bot-onboarding';
 import type { GeneralizedErrorClass } from '@maka/core/redaction';
 
 import { type UiCatalog, type UiLocale, lookupCopy } from '@maka/core/ui-locale';
@@ -177,7 +177,7 @@ const zhCopy = {
     connectedRefreshFailed: (message: string) => `连接已完成,但状态刷新失败:${message}`, close: (title: string) => `关闭${title}`,
     generatingAria: '正在生成二维码', privacy: '凭据仅保存在本机,不会传给 renderer 或 Maka 云端。', openBrowser: '无法扫码?在浏览器中打开',
     done: '完成', regenerate: '重新生成', refreshQr: '刷新二维码', cancel: '取消', generating: '正在生成安全二维码…', connecting: '授权完成,正在保存凭据并启动连接…',
-    connected: (name: string) => `${name} 已连接`, connectedWarning: '凭据已保存,但连接尚未成功启动。', expired: '二维码已过期,请重新生成', denied: '授权已取消,请重新生成二维码', cancelled: '扫码接入已取消', failed: '扫码接入失败,请重试', preparing: '准备扫码接入…',
+    connected: (name: string) => `${name} 已连接`, connectedWarning: '凭据已保存,但连接尚未成功启动。', retrying: (category: BotOnboardingRetryFailureCategory, count: number, seconds: number) => `${retryCategoryZh(category)};连续失败 ${count} 次,约 ${seconds} 秒后自动重试。`, expired: '二维码已过期,请重新生成', denied: '授权已取消,请重新生成二维码', cancelled: '扫码接入已取消', failed: '扫码接入失败,请重试', preparing: '准备扫码接入…',
     savedNotConnected: '凭据已保存,但连接未建立,可稍后在设置中重试。',
     savedNotConnectedDetail: (detail: string) => `凭据已保存,但连接未建立:${detail},可稍后在设置中重试。`,
     errors: {
@@ -316,7 +316,7 @@ const zhTwCopy = {
     connectedRefreshFailed: (message: string) => `連線已完成,但狀態重新整理失敗:${message}`, close: (title: string) => `關閉${title}`,
     generatingAria: '正在生成二維碼', privacy: '憑證僅儲存在本機,不會傳給 renderer 或 Maka 雲端。', openBrowser: '無法掃碼?在瀏覽器中開啟',
     done: '完成', regenerate: '重新生成', refreshQr: '重新整理二維碼', cancel: '取消', generating: '正在生成安全二維碼…', connecting: '授權完成,正在儲存憑證並啟動連線…',
-    connected: (name: string) => `${name} 已連線`, connectedWarning: '憑證已儲存,但連線尚未成功啟動。', expired: '二維碼已過期,請重新生成', denied: '授權已取消,請重新生成二維碼', cancelled: '掃碼串接已取消', failed: '掃碼串接失敗,請重試', preparing: '準備掃碼串接…',
+    connected: (name: string) => `${name} 已連線`, connectedWarning: '憑證已儲存,但連線尚未成功啟動。', retrying: (category: BotOnboardingRetryFailureCategory, count: number, seconds: number) => `${retryCategoryZhTw(category)};連續失敗 ${count} 次,約 ${seconds} 秒後自動重試。`, expired: '二維碼已過期,請重新生成', denied: '授權已取消,請重新生成二維碼', cancelled: '掃碼串接已取消', failed: '掃碼串接失敗,請重試', preparing: '準備掃碼串接…',
     savedNotConnected: '憑證已儲存,但連線未建立,可稍後在設定中重試。',
     savedNotConnectedDetail: (detail: string) => `憑證已儲存,但連線未建立:${detail},可稍後在設定中重試。`,
     errors: {
@@ -407,7 +407,7 @@ const enCopy: BotSettingsCopy = {
   },
   onboarding: {
     providers: { dingtalk: { title: 'Set up DingTalk', ariaLabel: 'Set up DingTalk with a QR code', qrAlt: 'DingTalk setup QR code', subtitle: 'Scan in DingTalk to register the app', waiting: 'Scan with DingTalk and confirm authorization', scanned: 'Scanned. Complete confirmation in DingTalk.' }, feishu: { title: 'Set up Feishu', ariaLabel: 'Set up Feishu with a QR code', qrAlt: 'Feishu setup QR code', subtitle: 'Scan with Feishu to create and configure the bot', waiting: 'Scan with Feis [...]
-    lark: { title: 'Set up Lark', ariaLabel: 'Set up Lark with a QR code', qrAlt: 'Lark setup QR code', subtitle: 'Scan with Lark to create and configure the bot', waiting: 'Scan with Lark and confirm creation', scanned: 'Scanned. Complete confirmation in Lark.' }, connectedRefreshFailed: (message) => `Connected, but status refresh failed: ${message}`, close: (title) => `Close ${title}`, generatingAria: 'Generating QR code', privacy: 'Credentials stay on this device and are never sent to [...]
+    lark: { title: 'Set up Lark', ariaLabel: 'Set up Lark with a QR code', qrAlt: 'Lark setup QR code', subtitle: 'Scan with Lark to create and configure the bot', waiting: 'Scan with Lark and confirm creation', scanned: 'Scanned. Complete confirmation in Lark.' }, connectedRefreshFailed: (message) => `Connected, but status refresh failed: ${message}`, close: (title) => `Close ${title}`, generatingAria: 'Generating QR code', privacy: 'Credentials stay on this device and are never sent to [...]
     savedNotConnected: 'Credentials were saved, but the connection did not start. Retry from settings later.',
     savedNotConnectedDetail: (detail) => `Credentials were saved, but the connection did not start: ${detail}. Retry from settings later.`,
     errors: {
@@ -429,6 +429,36 @@ export function getBotSettingsCopy(locale: UiLocale): BotSettingsCopy {
   return BOT_SETTINGS_COPY[locale];
 }
 
+function retryCategoryZh(category: BotOnboardingRetryFailureCategory): string {
+  switch (category) {
+    case 'timeout': return '请求超时';
+    case 'network': return '网络暂时异常';
+    case 'rate_limited': return '服务请求频率受限';
+    case 'server': return '服务端暂时异常';
+    default: return '服务暂时异常';
+  }
+}
+
+function retryCategoryZhTw(category: BotOnboardingRetryFailureCategory): string {
+  switch (category) {
+    case 'timeout': return '請求逾時';
+    case 'network': return '網路暫時異常';
+    case 'rate_limited': return '服務請求頻率受限';
+    case 'server': return '服務端暫時異常';
+    default: return '服務暫時異常';
+  }
+}
+
+function retryCategoryEn(category: BotOnboardingRetryFailureCategory): string {
+  switch (category) {
+    case 'timeout': return 'The request timed out';
+    case 'network': return 'The network is temporarily unavailable';
+    case 'rate_limited': return 'The service is rate limiting requests';
+    case 'server': return 'The service is temporarily unavailable';
+    default: return 'The service is temporarily unavailable';
+  }
+}
+
 const BOT_STATUS_REASON_PATTERNS: ReadonlyArray<{
   pattern: RegExp;
   key: keyof BotSettingsCopy['statusReasons']['withCode'];
@@ -482,3 +512,41 @@ export function botOnboardingErrorMessage(errorCode: string | undefined, locale:
   const shared = BOT_SETTINGS_COPY[locale].onboarding;
   return lookupCopy(shared.errors, errorCode) ?? shared.failed;
 }
+
+export function botOnboardingStatusCopy(
+  snapshot: BotOnboardingSnapshot | null,
+  starting: boolean,
+  error: string | null,
+  copy: BotSettingsCopy['onboarding']['providers'][BotOnboardingProvider],
+  locale: 'zh-CN' | 'zh-TW' | 'en',
+): string {
+  const shared = getBotSettingsCopy(locale).onboarding;
+  if (starting) return shared.generating;
+  if (error) return error;
+  if (snapshot?.retryHealth) {
+    const seconds = Math.max(1, Math.ceil(snapshot.nextPollAfterMs / 1_000));
+    const retry = shared.retrying(
+      snapshot.retryHealth.category,
+      snapshot.retryHealth.consecutiveFailures,
+      seconds,
+    );
+    return snapshot.state === 'scanned' ? `${copy.scanned} ${retry}` : retry;
+  }
+  switch (snapshot?.state) {
+    case 'waiting': return copy.waiting;
+    case 'scanned': return copy.scanned;
+    case 'connecting': return shared.connecting;
+    // PR1197 review (P0-3): honour the honest "saved but not connected" notice
+    // instead of claiming a healthy connection.
+    case 'connected': return snapshot.warningCode
+      ? (snapshot.warningDetail
+          ? shared.savedNotConnectedDetail(botStatusReasonMessage(snapshot.warningDetail, locale))
+          : shared.savedNotConnected)
+      : shared.connected(getBotSettingsCopy(locale).providers[snapshot.provider].label);
+    case 'expired': return shared.expired;
+    case 'denied': return shared.denied;
+    case 'cancelled': return shared.cancelled;
+    case 'error': return botOnboardingErrorMessage(snapshot.errorCode, locale);
+    default: return shared.preparing;
+  }
+}
diff --git a/apps/desktop/src/renderer/settings/bot-onboarding-modal.tsx b/apps/desktop/src/renderer/settings/bot-onboarding-modal.tsx
index b4e735620c..5fbf987e97 100644
--- a/apps/desktop/src/renderer/settings/bot-onboarding-modal.tsx
+++ b/apps/desktop/src/renderer/settings/bot-onboarding-modal.tsx
@@ -37,7 +37,7 @@ import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
 import { ICON_SIZE, AlertCircle, Check } from '@maka/ui/icons';
 import { BotBrandLogo } from './bot-chat-shared';
 import { settingsActionErrorMessage } from '../application/contracts/settings-presentation/settings-error-copy.js';
-import { botOnboardingErrorMessage, botStatusReasonMessage, getBotSettingsCopy, type BotSettingsCopy } from '../locales/settings-bot-copy';
+import { botOnboardingStatusCopy, getBotSettingsCopy, type BotSettingsCopy } from '../locales/settings-bot-copy';
 
 export function BotOnboardingModal(props: {
   provider: BotOnboardingProvider;
@@ -156,7 +156,7 @@ export function BotOnboardingModal(props: {
     if (!isOpen) requestClose();
   }
 
-  const status = statusCopy(snapshot, starting, error, copy, locale);
+  const status = botOnboardingStatusCopy(snapshot, starting, error, copy, locale);
   const qrDataUrl = snapshot?.qrCodeDataUrl ?? qrCacheRef.current;
   const showQr = Boolean(qrDataUrl)
     && snapshot?.state !== 'expired'
@@ -245,32 +245,3 @@ function providerCopy(
   if (provider !== 'feishu' || brand !== 'lark') return copy.providers[provider];
   return copy.lark;
 }
-
-function statusCopy(
-  snapshot: BotOnboardingSnapshot | null,
-  starting: boolean,
-  error: string | null,
-  copy: BotSettingsCopy['onboarding']['providers'][BotOnboardingProvider],
-  locale: 'zh-CN' | 'zh-TW' | 'en',
-): string {
-  const shared = getBotSettingsCopy(locale).onboarding;
-  if (starting) return shared.generating;
-  if (error) return error;
-  switch (snapshot?.state) {
-    case 'waiting': return copy.waiting;
-    case 'scanned': return copy.scanned;
-    case 'connecting': return shared.connecting;
-    // PR1197 review (P0-3): honour the honest "saved but not connected" notice
-    // instead of claiming a healthy connection.
-    case 'connected': return snapshot.warningCode
-      ? (snapshot.warningDetail
-          ? shared.savedNotConnectedDetail(botStatusReasonMessage(snapshot.warningDetail, locale))
-          : shared.savedNotConnected)
-      : shared.connected(getBotSettingsCopy(locale).providers[snapshot.provider].label);
-    case 'expired': return shared.expired;
-    case 'denied': return shared.denied;
-    case 'cancelled': return shared.cancelled;
-    case 'error': return botOnboardingErrorMessage(snapshot.errorCode, locale);
-    default: return shared.preparing;
-  }
-}
diff --git a/packages/core/src/bot-onboarding.ts b/packages/core/src/bot-onboarding.ts
index a6d8aa018d..1e54e9f05c 100644
--- a/packages/core/src/bot-onboarding.ts
+++ b/packages/core/src/bot-onboarding.ts
@@ -49,6 +49,14 @@ export interface BotOnboardingStartInput {
   brand?: BotOnboardingBrand;
 }
 
+export type BotOnboardingRetryFailureCategory = 'timeout' | 'network' | 'rate_limited' | 'server';
+
+export interface BotOnboardingRetryHealth {
+  /** Finite, renderer-safe classification. Raw provider failures never cross IPC. */
+  category: BotOnboardingRetryFailureCategory;
+  consecutiveFailures: number;
+}
+
 /**
  * Renderer-safe projection of a main-process-owned onboarding session.
  * Provider device codes and final credentials never cross the preload boundary.
@@ -61,6 +69,8 @@ export interface BotOnboardingSnapshot {
   qrCodeDataUrl?: string;
   expiresAt?: number;
   nextPollAfterMs: number;
+  /** Present only while the main-process owner is backing off after a transient failure. */
+  retryHealth?: BotOnboardingRetryHealth;
   canOpenInBrowser: boolean;
   identity?: {
     id?: string;
diff --git a/packages/core/src/redaction.ts b/packages/core/src/redaction.ts
index 41113357fa..af51638d75 100644
--- a/packages/core/src/redaction.ts
+++ b/packages/core/src/redaction.ts
@@ -235,6 +235,11 @@ export type GeneralizedErrorClass =
 export function classifyGeneralizedError(error: unknown): GeneralizedErrorClass | undefined {
   const message = error instanceof Error ? error.message : String(error);
   const lower = redactSecrets(message).toLowerCase();
+  // A provider response takes precedence over incidental transport wording.
+  const status = Number(lower.match(/\bhttp\s+(\d{3})\b/u)?.[1]);
+  if (status === 401 || status === 403) return 'auth_failed';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500 && status < 600) return 'provider_error';
   if (/\b(?:timeout|timed[\s-]+out|etimedout)\b/u.test(lower)) return 'timeout';
   if (lower.includes('429') || lower.includes('rate')) return 'rate_limited';
   if (lower.includes('401') || lower.includes('403') || isAuthenticationErrorText(lower))


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org