feat(welcome): show first-run welcome dialog on fresh install

Introduce a one-time welcome dialog that explains CC Switch's workflow
to new users: how their existing config is preserved as a "default"
provider and how the bundled "Official" preset enables one-click revert.
Upgrade users are excluded by checking is_providers_empty() at startup
and never see the dialog.

Persistence follows the existing *_confirmed convention in AppSettings
(proxy/usage/stream_check/failover), stored in settings.json. The field
is only written when the user explicitly clicks the confirm button,
keeping its semantics strictly about user acknowledgement.

Also adds two reusable DAO helpers:
- Database::is_providers_empty for fresh-install detection, using
  EXISTS(SELECT 1) for a short-circuit query.
- Database::get_bool_flag accepting "true" | "1", with
  init_default_official_providers migrated to use it.

Dialog copy in zh/en/ja uses conditional phrasing so it stays
accurate whether or not existing live config was found.

src-tauri/src/database/dao/providers.rs

@@ -502,6 +502,20 @@ impl Database {
         }))
     }
 
+    /// 判断 providers 表是否为空（全 app_type 一起算）。
+    ///
+    /// 用于区分"全新安装"和"升级用户"：在启动流程 import/seed 之前调用。
+    /// 使用 `EXISTS` 短路查询，比 `COUNT(*)` 在将来表变大时更高效。
+    pub fn is_providers_empty(&self) -> Result<bool, AppError> {
+        let conn = lock_conn!(self.conn);
+        let exists: bool = conn
+            .query_row("SELECT EXISTS(SELECT 1 FROM providers)", [], |row| {
+                row.get(0)
+            })
+            .map_err(|e| AppError::Database(e.to_string()))?;
+        Ok(!exists)
+    }
+
     /// 仅获取指定 app 下所有 provider 的 id 集合。
     ///
     /// 比 `get_all_providers` 轻量得多：只读 id 列、无 endpoint 子查询。
@@ -568,11 +582,11 @@ impl Database {
     pub fn init_default_official_providers(&self) -> Result<usize, AppError> {
         use crate::database::dao::providers_seed::OFFICIAL_SEEDS;
 
-        // flag 检查：已执行过则跳过
-        if let Ok(Some(flag)) = self.get_setting("official_providers_seeded") {
-            if flag == "true" || flag == "1" {
-                return Ok(0);
-            }
+        if self
+            .get_bool_flag("official_providers_seeded")
+            .unwrap_or(false)
+        {
+            return Ok(0);
         }
 
         let mut inserted = 0_usize;

src-tauri/src/database/dao/settings.rs

@@ -33,6 +33,18 @@ impl Database {
         }
     }
 
+    /// 以布尔语义读取 flag：`"true"` 或 `"1"` → true，其它全部 false。
+    ///
+    /// 用于一次性启动 flag（`official_providers_seeded` / `first_run_notice_shown` 等）。
+    /// 与 `is_legacy_common_config_migrated` 等只认 `"true"` 的历史辅助函数**不同**——
+    /// 这里同时接受 `"1"` 是为了兼容 `init_default_official_providers` 既有写法。
+    pub fn get_bool_flag(&self, key: &str) -> Result<bool, AppError> {
+        Ok(matches!(
+            self.get_setting(key)?.as_deref(),
+            Some("true") | Some("1")
+        ))
+    }
+
     /// 设置值
     pub fn set_setting(&self, key: &str, value: &str) -> Result<(), AppError> {
         let conn = lock_conn!(self.conn);

src-tauri/src/lib.rs

@@ -472,6 +472,15 @@ pub fn run() {
             // 先 import 后 seed 是有意为之：先把用户手动配置的 settings.json / auth.json / .env
             // 落成 "default" provider 设为 current，再追加官方预设（is_current=false）。
             // 这样用户切到官方预设时，回填机制会保护原 live 配置不丢失。
+            //
+            // 捕获首次运行快照：所有全新装用户都会看到欢迎弹窗介绍 CC Switch 的工作方式。
+            // 读失败时默认不弹，宁可漏弹也不要因为故障打扰用户。
+            let first_run_already_confirmed = crate::settings::get_settings()
+                .first_run_notice_confirmed
+                .unwrap_or(false);
+            let fresh_install_at_startup =
+                app_state.db.is_providers_empty().unwrap_or(false);
+
             for app_type in
                 crate::app_config::AppType::all().filter(|t| !t.is_additive_mode())
             {
@@ -502,6 +511,12 @@ pub fn run() {
                 Err(e) => log::warn!("✗ Failed to seed official providers: {e}"),
             }
 
+            // 老用户 / 已确认的路径由 `fresh_install_at_startup` 自行拦截，这里不做写入。
+            // 字段只由前端在用户点击"我知道了"时 save_settings 回写，语义是"用户显式确认过"。
+            if !first_run_already_confirmed && fresh_install_at_startup {
+                log::info!("✓ First-run welcome notice pending");
+            }
+
             // 1.6. 自动同步 OpenCode / OpenClaw 的 live providers 到数据库
             //
             // additive 模式（OpenCode / OpenClaw）的 import 函数本身按 id 幂等，

src-tauri/src/settings.rs

@@ -205,6 +205,9 @@ pub struct AppSettings {
     /// User has confirmed the failover toggle first-run notice
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub failover_confirmed: Option<bool>,
+    /// User has confirmed the first-run welcome notice
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_run_notice_confirmed: Option<bool>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub language: Option<String>,
 
@@ -297,6 +300,7 @@ impl Default for AppSettings {
             stream_check_confirmed: None,
             enable_failover_toggle: false,
             failover_confirmed: None,
+            first_run_notice_confirmed: None,
             language: None,
             visible_apps: None,
             claude_config_dir: None,

src/App.tsx

@@ -62,6 +62,7 @@ import PromptPanel from "@/components/prompts/PromptPanel";
 import { SkillsPage } from "@/components/skills/SkillsPage";
 import UnifiedSkillsPanel from "@/components/skills/UnifiedSkillsPanel";
 import { DeepLinkImportDialog } from "@/components/DeepLinkImportDialog";
+import { FirstRunNoticeDialog } from "@/components/FirstRunNoticeDialog";
 import { AgentsPanel } from "@/components/agents/AgentsPanel";
 import { UniversalProviderPanel } from "@/components/universal";
 import { McpIcon } from "@/components/BrandIcons";
@@ -1354,6 +1355,7 @@ function App() {
       />
 
       <DeepLinkImportDialog />
+      <FirstRunNoticeDialog />
     </div>
   );
 }

src/components/FirstRunNoticeDialog.tsx

@@ -0,0 +1,67 @@
+import { useTranslation } from "react-i18next";
+import { useQueryClient } from "@tanstack/react-query";
+import { Sparkles } from "lucide-react";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { useSettingsQuery } from "@/lib/query";
+import { settingsApi } from "@/lib/api";
+
+/** 首次运行欢迎提示：仅当后端启动阶段保留 firstRunNoticeConfirmed 为空时弹出。 */
+export function FirstRunNoticeDialog() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+  const { data: settings } = useSettingsQuery();
+
+  // 后端启动时已经决定好要不要弹：条件不满足的话字段会立即被写成 true，
+  // 所以前端这里只需要判空即可——完全对齐 streamCheckConfirmed 等既有 flag 的模式。
+  const isOpen = settings != null && settings.firstRunNoticeConfirmed !== true;
+
+  const handleAcknowledge = async () => {
+    if (!settings) return;
+    try {
+      const { webdavSync: _, ...rest } = settings;
+      await settingsApi.save({ ...rest, firstRunNoticeConfirmed: true });
+      await queryClient.invalidateQueries({ queryKey: ["settings"] });
+    } catch (error) {
+      console.error("Failed to save firstRunNoticeConfirmed:", error);
+    }
+  };
+
+  return (
+    <Dialog
+      open={isOpen}
+      onOpenChange={(open) => {
+        if (!open) void handleAcknowledge();
+      }}
+    >
+      <DialogContent className="max-w-md" zIndex="top">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-5 w-5 text-blue-500" />
+            {t("firstRunNotice.title")}
+          </DialogTitle>
+        </DialogHeader>
+        <div className="space-y-3 px-6 py-5">
+          <DialogDescription className="whitespace-pre-line leading-relaxed">
+            {t("firstRunNotice.bodyDefault")}
+          </DialogDescription>
+          <DialogDescription className="whitespace-pre-line leading-relaxed">
+            {t("firstRunNotice.bodyOfficial")}
+          </DialogDescription>
+        </div>
+        <DialogFooter>
+          <Button onClick={handleAcknowledge}>
+            {t("firstRunNotice.confirm")}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/i18n/locales/en.json

@@ -42,6 +42,12 @@
     "enabled": "Enabled",
     "notSet": "Not Set"
   },
+  "firstRunNotice": {
+    "title": "Welcome to CC Switch",
+    "bodyDefault": "CC Switch lets you switch between multiple Claude Code / Codex / Gemini CLI providers with a single click. If you already had these tools configured, CC Switch has saved your existing setup as a provider named “default” so none of your previous configuration is lost.",
+    "bodyOfficial": "An “Official” preset is also included in the list — click it any time you want to switch back to the official default. CC Switch automatically backs up your current config to “default” before switching, so you can move back and forth freely. That's how CC Switch works 😊",
+    "confirm": "Got it"
+  },
   "apiKeyInput": {
     "placeholder": "Enter API Key",
     "show": "Show API Key",

src/i18n/locales/ja.json

@@ -42,6 +42,12 @@
     "enabled": "有効",
     "notSet": "未設定"
   },
+  "firstRunNotice": {
+    "title": "CC Switch へようこそ",
+    "bodyDefault": "CC Switch は Claude Code / Codex / Gemini CLI の複数プロバイダーをワンクリックで切り替えられるツールです。すでにこれらのツールを設定済みの場合、CC Switch は現在の設定を「default」という名前のプロバイダーとして自動的に保存するので、既存の設定が失われることはありません。",
+    "bodyOfficial": "リストには「Official（公式）」プリセットも用意されており、公式バージョンに戻したくなったらクリックするだけで切り替えられます。切り替える前に現在の設定は自動で default にバックアップされるので、自由に行き来できます。これが CC Switch の仕組みです 😊",
+    "confirm": "了解しました"
+  },
   "apiKeyInput": {
     "placeholder": "API Key を入力",
     "show": "API Key を表示",

src/i18n/locales/zh.json

@@ -42,6 +42,12 @@
     "enabled": "已开启",
     "notSet": "未设置"
   },
+  "firstRunNotice": {
+    "title": "欢迎使用 CC Switch",
+    "bodyDefault": "CC Switch 可以帮你在 Claude Code / Codex / Gemini CLI 的多个供应商之间一键切换。如果你之前已经配置过这些工具，CC Switch 会自动把现有设置保存为名为 “default” 的供应商，保证你的配置不会丢失。",
+    "bodyOfficial": "列表里还预置了 “官方（Official）” 供应商，随时点一下即可切回官方默认配置。切换前 CC Switch 会自动把当前配置备份回 default，可以放心来回切。CC Switch 就是这样工作的 😊",
+    "confirm": "我知道了"
+  },
   "apiKeyInput": {
     "placeholder": "请输入API Key",
     "show": "显示API Key",

src/types.ts

@@ -264,6 +264,8 @@ export interface Settings {
   enableFailoverToggle?: boolean;
   // User has confirmed the failover toggle first-run notice
   failoverConfirmed?: boolean;
+  // User has confirmed the first-run welcome notice
+  firstRunNoticeConfirmed?: boolean;
   // User has confirmed the auto-sync traffic warning
   autoSyncConfirmed?: boolean;
   // 首选语言（可选，默认中文）