# CC Switch v3.14.1

> 托盘用量可见化、Codex OAuth 多项稳定性修复、Skills 导入/安装可靠性提升、Hermes 配置健康扫描器移除

**[English →](v3.14.1-en.md) | [日本語版 →](v3.14.1-ja.md)**

---

## 概览

CC Switch v3.14.1 是 v3.14.0 之后的一次补丁版本，围绕 **Codex OAuth 反代稳定性**、**托盘用量可见化**、**Skills 导入 / 安装可靠性**、**Gemini 会话恢复路径**，以及**简化 Hermes 配置健康处理**展开。

系统托盘第一次把当前 Claude / Codex / Gemini 供应商的**缓存用量**直接呈现在子菜单里——包含订阅额度摘要和用量脚本摘要，并用颜色标记利用率；针对 Kimi / 智谱 / MiniMax 这类中国编码套餐供应商，托盘还会额外渲染 `🟢 h12% w80%` 风格的 **5 小时 + 周窗口**双窗口排版，语义与官方订阅徽章完全一致（取更紧的那个驱动 emoji）。创建 Claude 供应商时，如果 `ANTHROPIC_BASE_URL` 命中已知的编码套餐 host，会自动注入 `meta.usage_script`，托盘可以不打开 Usage Script 模态框就直接点亮。

Codex OAuth 侧修复了多项反代稳定性问题：使用客户端自带的 session ID 作为 `prompt_cache_key` 和 Codex session 头，避免生成 UUID 造成缓存抖动，显著提高缓存命中率；非流式 Anthropic 客户端在 ChatGPT Codex 上游强制 OpenAI Responses SSE 时也能正确拿到 JSON 响应；Stream Check 现在会以和生产一致的 `store: false`、encrypted reasoning include 以及供应商 FAST 模式构造探测请求，避免出现"检测失败但实际能用"的错位。配合新增的 **FAST 模式显式开关**，让用户可以在 Codex OAuth 型 Claude 供应商上按需发 `service_tier="priority"`，在延迟和 ChatGPT 配额消耗之间自己选。

另外，移除了 CC Switch 内置的 **Hermes 配置健康扫描器**及其警告横幅（以及对应的 `scan_hermes_config_health` 命令、`HermesHealthWarning` 类型和 `HermesWriteOutcome.warnings` 载荷），把 Hermes 面板聚焦回当前供应商展示、默认切换、Memory 编辑和启动 Hermes Web UI，深度配置健康度由 Hermes 自己负责。

**发布日期**：2026-04-23

**更新规模**：13 commits | 48 files changed | +1,883 / -808 lines

---

## 重点内容

- **托盘用量可见化**：Claude / Codex / Gemini 托盘子菜单展示当前供应商缓存用量，含订阅与脚本摘要及颜色标记；刷新带节流、仅针对可见应用、并回写到 React Query (#2184, 感谢 @TuYv)
- **托盘编码套餐用量（Kimi / 智谱 / MiniMax）**：托盘渲染 5 小时 + 周窗口双窗口用量，沿用 `🟢 h12% w80%` 排版；命中已知 host 的 Claude 供应商自动注入 `meta.usage_script`
- **Codex OAuth FAST 模式**：为 Codex OAuth 型 Claude 供应商新增显式 FAST 开关，开启后转换后的 Responses 请求发 `service_tier="priority"`，默认关闭 (#2210, 感谢 @JesusDR01)
- **Codex OAuth 稳定性**：修复反代缓存路由 (#2218, 感谢 @majiayu000)、Responses SSE 聚合 (#2235, 感谢 @xpfo-go)、Stream Check 与生产一致性 (#2210, 感谢 @JesusDR01)
- **Hermes 配置健康扫描器移除**：把 Hermes 面板聚焦回供应商管理、Memory 编辑和 Web UI 启动，不再重复承担深度配置健康判断
- **Skills 导入 / 安装可靠性**：导入过程中禁用操作按钮、结果按 ID 去重 (#2211, 感谢 @TuYv)；一键配置基于最新表单状态 (#2249, 感谢 @Coconut-Fish)；根级 `SKILL.md` 仓库安装稳定 (#2231, 感谢 @santugege)
- **Gemini 会话恢复路径**：扫描会话时读取 `.project_root` 元数据，把原始项目目录带回恢复流程 (#2240, 感谢 @tisonkun)
- **Session / 设置布局打磨**：滚动区域视口加宽度约束修复横向溢出，应用底部和设置页底部间距更紧凑 (#2201, 感谢 @Coconut-Fish)

---

## 新功能

### 托盘用量可见化

- 系统托盘子菜单新增当前 Claude / Codex / Gemini 供应商的**缓存用量**展示 (#2184, 感谢 @TuYv)
- 包含订阅额度摘要和用量脚本摘要，并用颜色标记利用率
- 托盘触发的刷新**带节流**、**只覆盖可见应用**，并同步回 React Query，主窗口和托盘共享同一份用量数据

### 托盘编码套餐用量（Kimi / 智谱 / MiniMax）

- 托盘为中国编码套餐供应商渲染 **5 小时 + 周窗口**双窗口用量
- 使用与官方订阅徽章一致的 `🟢 h12% w80%` 两窗口排版，取更紧的那个利用率驱动 emoji 颜色
- 创建 Claude 供应商时，如果 `ANTHROPIC_BASE_URL` 匹配已知编码套餐 host，会**自动注入** `meta.usage_script`，托盘不打开 Usage Script 模态框也能直接点亮
- 更新时会**保留已有** `usage_script` 值，不覆盖用户自定义

### Codex OAuth FAST 模式

- 为 Codex OAuth 型 Claude 供应商新增显式 FAST 模式开关 (#2210, 感谢 @JesusDR01)
- 开启时，转换后的 Responses 请求会发 `service_tier="priority"` 以降低延迟
- 默认关闭，避免意外增加 ChatGPT 配额消耗

---

## 变更

### Session 与设置布局打磨

- 滚动区域视口加上宽度约束，修复横向溢出 (#2201, 感谢 @Coconut-Fish)
- 应用底部和设置页底部间距更紧凑，让长 Session / 设置视图看起来更干净

---

## 移除

### Hermes 配置健康扫描器

- 移除应用内的 Hermes 配置健康扫描器和警告横幅
- 移除 `scan_hermes_config_health` 命令、`HermesHealthWarning` 类型以及 `HermesWriteOutcome.warnings` 载荷
- CC Switch 的 Hermes 面板回归核心职责：当前供应商展示、切换默认供应商、Memory 编辑、以及启动 Hermes Web UI 处理深度配置

---

## 修复

### Codex OAuth 缓存路由

- 使用客户端自带的 session ID 作为 `prompt_cache_key` 和 Codex session 头，保留显式缓存 key (#2218, 感谢 @majiayu000)
- 停止生成 UUID 导致的缓存抖动，让 ChatGPT Codex 反代的缓存身份更稳定

### Codex OAuth Responses SSE 聚合

- ChatGPT Codex 上游强制 OpenAI Responses SSE 时，非流式 Anthropic 客户端也能正确拿到 JSON (#2235, 感谢 @xpfo-go)
- CC Switch 会在非流式转换之前先聚合上游 SSE 事件

### Codex OAuth Stream Check 对齐

- Stream Check 构造的 Codex OAuth 测试请求现在与生产代理一致，使用相同的 `store: false`、加密 reasoning include 和供应商 FAST 模式设置 (#2210, 感谢 @JesusDR01)
- 避免"检测失败但实际能用"的错位

### Codex 模型提取

- 读取 Codex 配置的 `model` 字段时，改用 TOML 解析替代首行正则匹配 (#2227, 感谢 @nmsn)
- 多行 TOML 也能正确处理

### 模型快速填入 / 一键配置

- 模型快速填入现在基于**最新的**供应商表单配置应用 (#2249, 感谢 @Coconut-Fish)
- 修复陈旧表单状态导致一键配置失败的问题

### Skills 导入去重

- Skills 导入对话框在导入进行时禁用所有操作按钮 (#2211, 感谢 @TuYv)
- 已安装 Skills 的缓存按 ID 去重，避免双击造成重复的已安装条目 (#2139)

### 根级 Skill 仓库

- Skill 的安装与更新流程现在能一致地识别三种源路径：直接嵌套路径、按 install-name 递归搜索、以及仓库根的 `SKILL.md` 源 (#2231, 感谢 @santugege)

### Gemini 会话恢复路径

- Gemini 会话扫描时读取 `.project_root` 元数据 (#2240, 感谢 @tisonkun)
- 恢复流程可以在可用时把原始项目目录传回

### 供应商名悬浮提示

- 供应商图标在 inline SVG、图像 URL、以及首字母回退渲染路径下都会在 hover 时展示供应商名称 (#2237, 感谢 @tisonkun)

---

## 说明与注意事项

- **Hermes 健康扫描器已移除**：如果你依赖 CC Switch 提示 Hermes YAML 的深度配置问题，请改为通过工具栏的"启动 Hermes Web UI"按钮在 Hermes 原生面板里查看。日常供应商管理、切换、Memory 编辑、MCP 与 Skills 同步仍然由 CC Switch 负责。
- **Codex OAuth FAST 模式默认关闭**：只有在你接受可能增加 ChatGPT 配额消耗换取更低延迟时，才需要打开。
- **托盘缓存用量**：刷新带节流，只覆盖当前显示的应用，避免无必要的上游 API 调用；数据会回写到 React Query，因此主窗口和托盘看到的值一致。

---

## 下载与安装

访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。

### 系统要求

| 系统    | 最低版本                   | 架构                                |
| ------- | -------------------------- | ----------------------------------- |
| Windows | Windows 10 及以上          | x64                                 |
| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
| Linux   | 见下表                     | x64                                 |

### Windows

| 文件                                     | 说明                                |
| ---------------------------------------- | ----------------------------------- |
| `CC-Switch-v3.14.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.14.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

### macOS

| 文件                             | 说明                                          |
| -------------------------------- | --------------------------------------------- |
| `CC-Switch-v3.14.1-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
| `CC-Switch-v3.14.1-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
| `CC-Switch-v3.14.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |

> macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。

### Homebrew（macOS）

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

### Linux

| 发行版                                  | 推荐格式    | 安装方式                                                               |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
