# 1.3 界面概览

## 主界面布局

![image-20260108001629138](../../assets/image-20260108001629138.png)

## 顶部导航栏

| 序号 | 元素 | 功能说明 |
|------|------|----------|
| ① | Logo | 点击访问 GitHub 项目页 |
| ② | 设置按钮 | 打开设置页面（快捷键 `Cmd/Ctrl + ,`） |
| ③ | 代理开关 | 启动/停止本地代理服务 |
| ④ | 应用切换器 | 切换 Claude / Codex / Gemini / OpenCode / OpenClaw |
| ⑤ | 功能区 | Skills / Prompts / MCP 入口 |
| ⑥ | 添加按钮 | 添加新供应商 |

### 应用切换器

点击下拉菜单切换当前管理的应用：

- **Claude** - 管理 Claude Code 配置
- **Codex** - 管理 Codex 配置
- **Gemini** - 管理 Gemini CLI 配置
- **OpenCode** - 管理 OpenCode 配置
- **OpenClaw** - 管理 OpenClaw 配置

切换后，供应商列表会显示对应应用的配置。

### 功能区按钮

| 按钮 | 功能 | 可见条件 |
|------|------|----------|
| Skills | 技能扩展管理 | 始终可见 |
| Prompts | 系统提示词管理 | 始终可见 |
| MCP | MCP 服务器管理 | 始终可见 |

## 供应商卡片

每个供应商以卡片形式展示，从左到右依次包含以下元素：

### 卡片元素（从左到右）

| 序号 | 元素 | 图标 | 功能说明 |
|------|------|------|----------|
| ① | 拖拽手柄 | ≡ | 按住上下拖动调整供应商顺序 |
| ② | 供应商图标 | 🔷 | 显示供应商品牌图标，可自定义颜色 |
| ③ | 供应商信息 | - | 名称、备注/端点地址（可点击打开官网） |
| ④ | 用量信息 | - | 显示剩余额度，多套餐时显示套餐数量 |
| ⑤ | 启用按钮 | ▶ | 切换为当前使用的供应商 |
| ⑥ | 编辑按钮 | ✏️ | 编辑供应商配置 |
| ⑦ | 复制按钮 | 📋 | 复制供应商（创建副本） |
| ⑧ | 测速按钮 | 🧪 | 测试模型可用性和响应速度 |
| ⑨ | 用量查询 | 📊 | 配置用量查询脚本 |
| ⑩ | 删除按钮 | 🗑️ | 删除供应商（当前启用时禁用） |

> 💡 **提示**：操作按钮区域（⑤-⑩）在鼠标悬停时显示，平时隐藏以保持界面简洁。

### 按钮详细说明

| 按钮 | 状态变化 | 说明 |
|------|----------|------|
| **启用** | 已启用时显示 ✓ 并禁用 | 故障转移模式下变为「加入/已加入」 |
| **编辑** | 始终可用 | 打开编辑面板修改配置 |
| **复制** | 始终可用 | 创建供应商副本，名称后缀 `copy` |
| **测速** | 测试中显示加载动画 | 仅代理服务运行时可用 |
| **用量查询** | 始终可用 | 配置自定义用量查询脚本 |
| **删除** | 当前启用时半透明禁用 | 需先切换到其他供应商才能删除 |

### 卡片状态

| 状态 | 边框颜色 | 说明 |
|------|----------|------|
| **当前启用** | 🔵 蓝色边框 | 普通模式下当前使用的供应商 |
| **代理活跃** | 🟢 绿色边框 | 代理接管模式下实际使用的供应商 |
| **普通状态** | 默认边框 | 未启用的供应商 |
| **故障转移中** | 显示优先级徽章 | 如 P1、P2 表示故障转移优先级 |

### 健康状态徽章

在代理模式下，加入故障转移队列的供应商会显示健康状态：

| 徽章 | 颜色 | 说明 |
|------|------|------|
| 健康 | 🟢 绿色 | 连续失败 0 次 |
| 警告 | 🟡 黄色 | 连续失败 1-2 次 |
| 不健康 | 🔴 红色 | 连续失败 ≥3 次，可能触发熔断 |


## 系统托盘

CC Switch 在系统托盘显示图标，提供快速操作入口。

### 托盘菜单结构

![image-20260108002153668](../../assets/image-20260108002153668.png)

### 菜单功能

| 菜单项 | 功能 |
|--------|------|
| 打开主界面 | 显示主窗口并聚焦 |
| 应用子菜单 | 按 Claude/Codex/Gemini/OpenCode/OpenClaw 分组的折叠子菜单（如 "Claude · PackyCode"） |
| 供应商列表 | 在每个子菜单内，点击切换，当前启用的显示勾选标记 |
| 轻量模式 | 勾选框切换，进入/退出仅托盘运行模式 |
| 退出 | 完全退出应用 |

> **注意**：每个应用子菜单的标题会显示当前供应商名称（如 "Claude · PackyCode"）。没有配置供应商的应用会显示禁用的"(无供应商)"条目。应用可见性由设置中的"应用可见性"选项控制。

### 多语言支持

托盘菜单支持三种语言，根据设置自动切换：

| 语言 | 打开主界面 | 退出 |
|------|-----------|------|
| 中文 | 打开主界面 | 退出 |
| English | Open main window | Quit |
| 日本語 | メインウィンドウを開く | 終了 |

### 轻量模式

托盘菜单包含 **轻量模式** 切换开关（勾选框）。启用后：

- 主窗口关闭以释放资源
- 应用仅在系统托盘中运行
- 你仍可通过托盘子菜单切换供应商
- 在 macOS 上，Dock 图标也会隐藏

要退出轻量模式，取消勾选该选项或点击"打开主界面" — 主窗口将被重建并显示。

### 使用场景

托盘切换供应商无需打开主界面，适合：

- 频繁切换供应商
- 主窗口最小化时快速操作
- 后台运行时管理配置
- 使用轻量模式以最小化资源占用

## 设置页面

设置页面分为多个 Tab：

### 通用 Tab

- 语言设置（中文/English/日本語）
- 主题设置（跟随系统/浅色/深色）
- 窗口行为（开机自启、关闭行为）

### 高级 Tab

- 配置目录设置
- 代理服务配置
- 故障转移设置
- 定价配置
- 数据导入导出

### 用量 Tab

- 请求统计概览
- 趋势图表
- 请求日志
- 供应商/模型统计

### 关于 Tab

- 版本信息
- 更新检查
- 开源协议

## 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Cmd/Ctrl + ,` | 打开设置 |
| `Cmd/Ctrl + F` | 搜索供应商 |
| `Esc` | 关闭弹窗/搜索 |

## 搜索功能

按 `Cmd/Ctrl + F` 打开搜索框：

- 支持按名称、备注、URL 搜索
- 实时过滤供应商列表
- 按 `Esc` 关闭搜索
