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