fix(issue-1287): [bug]-windows-免安装桌面端进入通知/agent-设置可能黑屏

Author: ZhuLinsen

apps/dsa-web/src/components/settings/SettingsPanelErrorBoundary.tsx

@@ -0,0 +1,72 @@
+import { Component } from 'react';
+import type { ErrorInfo, ReactNode } from 'react';
+import { InlineAlert } from '../common';
+import { cn } from '../../utils/cn';
+
+interface SettingsPanelErrorBoundaryProps {
+  title: string;
+  children: ReactNode;
+  resetKey?: string | number;
+  className?: string;
+}
+
+interface SettingsPanelErrorBoundaryState {
+  hasError: boolean;
+  errorMessage: string;
+}
+
+export class SettingsPanelErrorBoundary extends Component<
+  SettingsPanelErrorBoundaryProps,
+  SettingsPanelErrorBoundaryState
+> {
+  override state: SettingsPanelErrorBoundaryState = {
+    hasError: false,
+    errorMessage: '',
+  };
+
+  static getDerivedStateFromError(error: unknown): SettingsPanelErrorBoundaryState {
+    return {
+      hasError: true,
+      errorMessage: error instanceof Error ? error.message : '未知前端运行时异常',
+    };
+  }
+
+  override componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error(`Settings panel runtime error: ${this.props.title}`, error, errorInfo);
+  }
+
+  override componentDidUpdate(prevProps: SettingsPanelErrorBoundaryProps) {
+    if (this.state.hasError && prevProps.resetKey !== this.props.resetKey) {
+      this.setState({ hasError: false, errorMessage: '' });
+    }
+  }
+
+  override render() {
+    if (!this.state.hasError) {
+      return this.props.children;
+    }
+
+    return (
+      <div className={cn('rounded-[1.5rem] border settings-border bg-card/94 p-5 shadow-soft-card-strong backdrop-blur-sm', this.props.className)}>
+        <InlineAlert
+          title={`${this.props.title}加载失败`}
+          variant="danger"
+          message={(
+            <div className="space-y-2">
+              <p>
+                该设置区域发生前端运行时异常，页面其他设置仍可继续使用。请查看并提供桌面端日志
+                <code className="mx-1 rounded bg-background/45 px-1 py-0.5 font-mono text-xs">desktop.log</code>
+                ，同时补充 release 版本、Windows 版本和触发入口。
+              </p>
+              {this.state.errorMessage ? (
+                <p className="break-words font-mono text-xs opacity-80">
+                  错误摘要：{this.state.errorMessage}
+                </p>
+              ) : null}
+            </div>
+          )}
+        />
+      </div>
+    );
+  }
+}

apps/dsa-web/src/components/settings/__tests__/SettingsPanelErrorBoundary.test.tsx

@@ -0,0 +1,53 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import type { ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SettingsPanelErrorBoundary } from '../SettingsPanelErrorBoundary';
+
+function ThrowingPanel(): ReactElement {
+  throw new Error('mock settings panel crash');
+}
+
+describe('SettingsPanelErrorBoundary', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('renders a diagnostic desktop-log fallback when a settings panel throws', () => {
+    render(
+      <SettingsPanelErrorBoundary title="通知设置" resetKey="notification">
+        <ThrowingPanel />
+      </SettingsPanelErrorBoundary>
+    );
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByText('通知设置加载失败')).toBeInTheDocument();
+    expect(screen.getByText('desktop.log')).toBeInTheDocument();
+    expect(screen.getByText(/release 版本、Windows 版本和触发入口/)).toBeInTheDocument();
+    expect(screen.getByText(/错误摘要：mock settings panel crash/)).toBeInTheDocument();
+  });
+
+  it('resets after resetKey changes so the panel can render again', async () => {
+    const { rerender } = render(
+      <SettingsPanelErrorBoundary title="Agent 设置" resetKey="agent:v1">
+        <ThrowingPanel />
+      </SettingsPanelErrorBoundary>
+    );
+
+    expect(screen.getByText('Agent 设置加载失败')).toBeInTheDocument();
+
+    rerender(
+      <SettingsPanelErrorBoundary title="Agent 设置" resetKey="agent:v2">
+        <div>Agent 设置已恢复</div>
+      </SettingsPanelErrorBoundary>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Agent 设置已恢复')).toBeInTheDocument();
+    });
+    expect(screen.queryByText('Agent 设置加载失败')).not.toBeInTheDocument();
+  });
+});

apps/dsa-web/src/components/settings/index.ts

@@ -6,6 +6,7 @@ export * from './NotificationTestPanel';
 export * from './SettingsField';
 export * from './SettingsHelpButton';
 export * from './SettingsLoading';
+export * from './SettingsPanelErrorBoundary';
 export * from './SettingsSectionCard';
 export * from './SettingsCategoryNav';
 export * from './AuthSettingsCard';

apps/dsa-web/src/pages/SettingsPage.tsx

@@ -14,6 +14,7 @@ import {
   SettingsAlert,
   SettingsField,
   SettingsLoading,
+  SettingsPanelErrorBoundary,
   SettingsSectionCard,
 } from '../components/settings';
 import { WEB_BUILD_INFO } from '../utils/constants';
@@ -495,6 +496,31 @@ const SettingsPage: React.FC = () => {
   };
 
   const desktopUpdateNotice = getDesktopUpdateNotice(desktopUpdateState);
+  const shouldGuardActiveConfigPanel = activeCategory === 'notification' || activeCategory === 'agent';
+  const activeConfigPanelErrorTitle = activeCategory === 'agent' ? 'Agent 设置' : '通知设置';
+  const activeConfigPanel = activeItems.length ? (
+    <SettingsSectionCard
+      title="当前分类配置项"
+      description={getCategoryDescriptionZh(activeCategory as SystemConfigCategory, '') || '使用统一字段卡片维护当前分类的系统配置。'}
+    >
+      {activeItems.map((item) => (
+        <SettingsField
+          key={item.key}
+          item={item}
+          value={item.value}
+          disabled={isSaving}
+          onChange={setDraftValue}
+          issues={issueByKey[item.key] || []}
+        />
+      ))}
+    </SettingsSectionCard>
+  ) : (
+    <EmptyState
+      title="当前分类下暂无配置项"
+      description="当前分类没有可编辑字段；可切换左侧分类继续查看其它系统配置。"
+      className="settings-surface-panel settings-border-strong border-none bg-transparent shadow-none"
+    />
+  );
 
   return (
     <div className="settings-page min-h-full px-4 pb-6 pt-4 md:px-6">
@@ -754,35 +780,25 @@ const SettingsPage: React.FC = () => {
               <ChangePasswordCard />
             ) : null}
             {activeCategory === 'notification' ? (
-              <NotificationTestPanel
-                items={rawActiveItems.map((item) => ({ key: item.key, value: String(item.value ?? '') }))}
-                maskToken={maskToken}
-                disabled={isSaving || isLoading}
-              />
+              <SettingsPanelErrorBoundary
+                title="通知测试"
+                resetKey={`notification-test:${configVersion}`}
+              >
+                <NotificationTestPanel
+                  items={rawActiveItems.map((item) => ({ key: item.key, value: String(item.value ?? '') }))}
+                  maskToken={maskToken}
+                  disabled={isSaving || isLoading}
+                />
+              </SettingsPanelErrorBoundary>
             ) : null}
-            {activeItems.length ? (
-              <SettingsSectionCard
-                title="当前分类配置项"
-                description={getCategoryDescriptionZh(activeCategory as SystemConfigCategory, '') || '使用统一字段卡片维护当前分类的系统配置。'}
+            {shouldGuardActiveConfigPanel && activeItems.length ? (
+              <SettingsPanelErrorBoundary
+                title={activeConfigPanelErrorTitle}
+                resetKey={`${activeCategory}:${configVersion}`}
               >
-                {activeItems.map((item) => (
-                  <SettingsField
-                    key={item.key}
-                    item={item}
-                    value={item.value}
-                    disabled={isSaving}
-                    onChange={setDraftValue}
-                    issues={issueByKey[item.key] || []}
-                  />
-                ))}
-              </SettingsSectionCard>
-            ) : (
-              <EmptyState
-                title="当前分类下暂无配置项"
-                description="当前分类没有可编辑字段；可切换左侧分类继续查看其它系统配置。"
-                className="settings-surface-panel settings-border-strong border-none bg-transparent shadow-none"
-              />
-            )}
+                {activeConfigPanel}
+              </SettingsPanelErrorBoundary>
+            ) : activeConfigPanel}
           </section>
         </div>
       )}

apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx

@@ -21,6 +21,7 @@ const {
   applyPartialUpdate,
   refreshAfterExternalSave,
   refreshStatus,
+  settingsPanelErrorBoundary,
   useAuthMock,
   useSystemConfigMock,
   webBuildInfoMock,
@@ -41,6 +42,7 @@ const {
   applyPartialUpdate: vi.fn(),
   refreshAfterExternalSave: vi.fn(),
   refreshStatus: vi.fn(),
+  settingsPanelErrorBoundary: vi.fn(),
   useAuthMock: vi.fn(),
   useSystemConfigMock: vi.fn(),
   webBuildInfoMock: {
@@ -141,6 +143,16 @@ vi.mock('../../components/settings', () => ({
   ),
   SettingsField: ({ item }: { item: { key: string } }) => <div>{item.key}</div>,
   SettingsLoading: () => <div>loading</div>,
+  SettingsPanelErrorBoundary: ({
+    title,
+    children,
+  }: {
+    title: string;
+    children: React.ReactNode;
+  }) => {
+    settingsPanelErrorBoundary(title);
+    return <>{children}</>;
+  },
   SettingsSectionCard: ({
     title,
     description,
@@ -578,6 +590,7 @@ describe('SettingsPage', () => {
     expect(screen.getByText('AGENT_ORCHESTRATOR_TIMEOUT_S')).toBeInTheDocument();
     expect(screen.getByText('AGENT_DEEP_RESEARCH_BUDGET')).toBeInTheDocument();
     expect(screen.getByText('AGENT_EVENT_MONITOR_ENABLED')).toBeInTheDocument();
+    expect(settingsPanelErrorBoundary).toHaveBeenCalledWith('Agent 设置');
   });
 
   it('reset button semantic: discards local changes without network request', () => {
@@ -633,6 +646,8 @@ describe('SettingsPage', () => {
 
     expect(screen.getByText('通知测试面板:WECHAT_WEBHOOK_URL')).toBeInTheDocument();
     expect(screen.getByText('WECHAT_WEBHOOK_URL')).toBeInTheDocument();
+    expect(settingsPanelErrorBoundary).toHaveBeenCalledWith('通知测试');
+    expect(settingsPanelErrorBoundary).toHaveBeenCalledWith('通知设置');
   });
 
   it('renders env backup actions outside desktop runtime', () => {

docs/CHANGELOG.md

@@ -40,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [修复] 修正分析报告 API 构建策略点位时数值字段未归一为字符串的问题，避免策略价格触发响应 DTO 类型校验失败。
 - [修复] Docker 启动入口自动修复 `data` / `logs` / `reports` 挂载目录权限并降权运行，文档化的 Compose `exec` 手动命令显式使用 `dsa` 用户，避免普通部署需要手动 `chown` / `chmod`。
 - [修复] Web 首页大盘复盘结果改由主内容滚动区承载，避免 loading 切换到长结果后下方报告区域被截断或无法继续滚动。
+- [修复] Web 设置页为通知测试与 Agent/通知配置区域增加局部运行时错误兜底，异常时提示提供 Windows 桌面端 `desktop.log`，避免整页黑屏。
 
 ## [3.16.0] - 2026-05-10