cc-switch/docs/release-note-v3.6.1-en.md

CC Switch v3.6.1

Stability improvements and user experience optimization (based on v3.6.0)

中文更新说明 Chinese Documentation →

---

📦 What's New in v3.6.1 (2025-11-10)

This release focuses on user experience optimization and configuration parsing robustness, fixing several critical bugs and enhancing the usage query system.

✨ New Features

Usage Query System Enhancements

• Credential Decoupling - Usage queries can now use independent API Key and Base URL, no longer dependent on provider configuration
  • Support for different query endpoints and authentication methods
  • Automatically displays credential input fields based on template type
  • General template: API Key + Base URL
  • NewAPI template: Base URL + Access Token + User ID
  • Custom template: Fully customizable
• UI Component Upgrade - Replaced native checkbox with shadcn/ui Switch component for modern experience
• Form Unification - Unified use of shadcn/ui Input components, consistent styling with the application
• Password Visibility Toggle - Added show/hide password functionality (API Key, Access Token)

Form Validation Infrastructure

• Common Schema Library - New JSON/TOML generic validators to reduce code duplication
  • jsonConfigSchema: Generic JSON object validator
  • tomlConfigSchema: Generic TOML format validator
  • mcpJsonConfigSchema: MCP-specific JSON validator
• MCP Conditional Field Validation - Strict type checking
  • stdio type requires command field
  • http type requires url field

Partner Integration

• PackyCode - New official partner
  • Added to Claude and Codex provider presets
  • 10% discount promotion support
  • New logo and partner identification

---

🔧 Improvements

User Experience

• Drag Sort Sync - Tray menu order now syncs with drag-and-drop sorting in real-time
• Enhanced Error Notifications - Provider switch failures now display copyable error messages
• Removed Misleading Placeholders - Deleted example text from model input fields to avoid user confusion
• Auto-fill Base URL - All non-official provider categories automatically populate the Base URL input field

Configuration Parsing

• CJK Quote Normalization - Automatically handles IME-input fullwidth quotes to prevent TOML parsing errors
  • Supports automatic conversion of Chinese quotes (" " ' ') to ASCII quotes
  • Applied in TOML input handlers
  • Disabled browser auto-correction in Textarea component
• Preserve Custom Fields - Editing Codex MCP TOML configuration now preserves unknown fields
  • Supports extension fields like timeout_ms, retry_count
  • Forward compatibility with future MCP protocol extensions

---

🐛 Bug Fixes

Critical Fixes

• Fixed usage script panel white screen crash - FormLabel component missing FormField context caused entire app to crash
  • Replaced with standalone Label component
  • Root cause: FormLabel internally calls useFormField() hook which requires FormFieldContext
• Fixed CJK input quote parsing failure - IME-input fullwidth quotes caused TOML parsing errors
  • Added textNormalization utility function
  • Automatically normalizes quotes before parsing
• Fixed drag sort tray desync (#179) - Tray menu order not updated after drag-and-drop sorting
  • Automatically calls updateTrayMenu after sorting completes
  • Ensures UI and tray menu stay consistent
• Fixed MCP custom field loss - Custom fields silently dropped when editing Codex MCP configuration
  • Uses spread operator to retain all fields
  • Preserves unknown fields in normalizeServerConfig

Stability Improvements

• Error Isolation - Tray menu update failures no longer affect main operations
  • Decoupled tray update errors from main operations
  • Provides warning when main operation succeeds but tray update fails
• Safe Pattern Matching - Replaced unwrap() with safe pattern matching
  • Avoids panic-induced app crashes
  • Tray menu event handling uses match patterns
• Import Config Classification - Importing from default config now automatically sets category to custom
  • Avoids imported configs being mistaken for official presets
  • Provides clearer configuration source identification

---

📊 Technical Statistics

Commits: 17 commits
Code Changes: 31 files
  - Additions: 1,163 lines
  - Deletions: 811 lines
  - Net Growth: +352 lines
Contributors: Jason (16), ZyphrZero (1)

By Module:

• UI/User Interface: 3 commits
• Usage Query System: 3 commits
• Configuration Parsing: 2 commits
• Form Validation: 1 commit
• Other Improvements: 8 commits

---

📥 Installation

macOS

Via Homebrew (Recommended):

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

Manual Download:

• Download CC-Switch-v3.6.1-macOS.zip from Assets below

Note

: Due to lack of Apple Developer account, you may see "unidentified developer" warning. Go to System Settings → Privacy & Security → Click "Open Anyway"

Windows

• Installer: CC-Switch-v3.6.1-Windows.msi
• Portable: CC-Switch-v3.6.1-Windows-Portable.zip

Linux

• AppImage: CC-Switch-v3.6.1-Linux.AppImage
• Debian: CC-Switch-v3.6.1-Linux.deb

---

📚 Documentation

• 中文文档 (Chinese)
• English Documentation
• 完整更新日志 (Full Changelog)

---

🙏 Acknowledgments

Special thanks to:

• Zhipu AI - For sponsoring this project with GLM CODING PLAN
• PackyCode - New official partner
• ZyphrZero - For contributing tray menu sync fix (#179)

---

Full Changelog: https://github.com/farion1231/cc-switch/compare/v3.6.0...v3.6.1

---

---

📜 v3.6.0 Complete Feature Review

Content below is from v3.6.0 (2025-11-07), helping you understand the complete feature set

Click to expand v3.6.0 detailed content →

What's New

Edit Mode & Provider Management

• Provider Duplication - Quickly duplicate existing provider configurations to create variants with one click
• Manual Sorting - Drag and drop to reorder providers, with visual push effect animations. Thanks to @ZyphrZero
• Edit Mode Toggle - Show/hide drag handles to optimize editing experience

Custom Endpoint Management

• Multi-Endpoint Configuration - Support for aggregator providers with multiple API endpoints
• Endpoint Input Visibility - Shows endpoint field for all non-official providers automatically

Usage Query Enhancements

• Auto-Refresh Interval - Configure periodic automatic usage queries with customizable intervals
• Test Script API - Validate JavaScript usage query scripts before execution
• Enhanced Templates - Custom blank templates with access token and user ID parameter support Thanks to @Sirhexs

Custom Configuration Directory (Cloud Sync)

• Customizable Storage Location - Customize CC Switch's configuration storage directory
• Cloud Sync Support - Point to cloud sync folders (Dropbox, OneDrive, iCloud Drive, etc.) to enable automatic config synchronization across devices
• Independent Management - Managed via Tauri Store for better isolation and reliability Thanks to @ZyphrZero

Configuration Directory Switching (WSL Support)

• Auto-Sync on Directory Change - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to the new directory without manual operation
• Post-Change Sync Utility - Unified postChangeSync.ts utility for graceful error handling without blocking main flow
• Import Config Auto-Sync - Automatically sync after config import to ensure immediate effectiveness
• Smart Conflict Resolution - Distinguishes "fully successful" and "partially successful" states for precise user feedback

Configuration Editor Improvements

• JSON Format Button - One-click JSON formatting in configuration editors
• Real-Time TOML Validation - Live syntax validation for Codex configuration with error highlighting

Load Live Config When Editing

• Protect Manual Modifications - When editing the currently active provider, prioritize displaying the actual effective configuration from live files
• Dual-Source Strategy - Automatically loads from live config for active provider, SSOT for inactive ones

Claude Configuration Data Structure Enhancements

• Granular Model Configuration - Migrated from dual-key to quad-key system for better model tier differentiation
  • New fields: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_MODEL
  • Replaces legacy ANTHROPIC_SMALL_FAST_MODEL with automatic migration
  • Backend normalizes old configs on first read/write with smart fallback chain
  • UI expanded from 2 to 4 model input fields with intelligent defaults
• ANTHROPIC_API_KEY Support - Providers can now use ANTHROPIC_API_KEY field in addition to ANTHROPIC_AUTH_TOKEN
• Template Variable System - Support for dynamic configuration replacement (e.g., KAT-Coder's ENDPOINT_ID parameter)
• Endpoint Candidates - Predefined endpoint list for speed testing and endpoint management
• Visual Theme Configuration - Custom icons and colors for provider cards

Updated Provider Models

• Kimi k2 - Updated to latest kimi-k2-thinking model

New Provider Presets

Added 5 new provider presets:

• DMXAPI - Multi-model aggregation service
• Azure Codex - Microsoft Azure OpenAI endpoint
• AnyRouter - None-profit routing service
• AiHubMix - Multi-model aggregation service
• MiniMax - Open source AI model provider

Partner Promotion Mechanism

• Support for ecosystem partner promotion (Zhipu GLM Z.ai)
• Sponsored banner integration in README

---

Improvements

Configuration & Sync

• Unified Error Handling - AppError with internationalized error messages throughout backend
• Fixed apiKeyUrl Priority - Correct priority order for API key URL resolution
• Fixed MCP Sync Issues - Resolved sync-to-other-side functionality failures
• Import Config Sync - Fixed sync issues after configuration import
• Config Error Handling - Force exit on config error to prevent silent fallback and data loss

UI/UX Enhancements

• Unique Provider Icons - Each provider card now has unique icons and color identification
• Unified Border System - Consistent border design across all components
• Drag Interaction - Push effect animation and improved drag handle icons
• Enhanced Visual Feedback - Better current provider visual indication
• Dialog Standardization - Unified dialog sizes and layout consistency
• Form Improvements - Optimized model placeholders, simplified provider hints, category-specific hints
• Usage Display Inline - Usage info moved next to enable button for better space utilization

Complete Internationalization

• Error Messages i18n - All backend error messages support Chinese/English
• Tray Menu i18n - System tray menu fully internationalized
• UI Components i18n - 100% coverage across all user-facing components

---

Bug Fixes

Configuration Management

• Fixed apiKeyUrl priority issue
• Fixed MCP sync-to-other-side functionality failure
• Fixed sync issues after config import
• Fixed Codex API Key auto-sync
• Fixed endpoint speed test functionality
• Fixed provider duplicate insertion position (now inserts next to original)
• Fixed custom endpoint preservation in edit mode
• Prevent silent fallback and data loss on config error

Usage Query

• Fixed auto-query interval timing issue
• Ensured refresh button shows loading animation on click

UI Issues

• Fixed name collision error (get_init_error command)
• Fixed language setting rollback after successful save
• Fixed language switch state reset (dependency cycle)
• Fixed edit mode button alignment

Startup Issues

• Force exit on config error (no silent fallback)
• Eliminated code duplication causing initialization errors

---

Architecture Refactoring

Backend (Rust) - 5 Phase Refactoring

1. Phase 1: Unified error handling (AppError + i18n error messages)
2. Phase 2: Command layer split by domain (commands/{provider,mcp,config,settings,plugin,misc}.rs)
3. Phase 3: Integration tests and transaction mechanism (config snapshot + failure rollback)
4. Phase 4: Extracted Service layer (services/{provider,mcp,config,speedtest}.rs)
5. Phase 5: Concurrency optimization (RwLock instead of Mutex, scoped guard to avoid deadlock)

Frontend (React + TypeScript) - 4 Stage Refactoring

1. Stage 1: Test infrastructure (vitest + MSW + @testing-library/react)
2. Stage 2: Extracted custom hooks (useProviderActions, useMcpActions, useSettings, useImportExport, etc.)
3. Stage 3: Component splitting and business logic extraction
4. Stage 4: Code cleanup and formatting unification

Testing System

• Hooks Unit Tests - 100% coverage for all custom hooks
• Integration Tests - Coverage for key processes (App, SettingsDialog, MCP Panel)
• MSW Mocking - Backend API mocking to ensure test independence
• Test Infrastructure - vitest + MSW + @testing-library/react

Code Quality

• Unified Parameter Format - All Tauri commands migrated to camelCase (Tauri 2 specification)
• Semantic Clarity - AppType renamed to AppId for better semantics
• Centralized Parsing - Unified app parameter parsing with FromStr trait
• DRY Violations Cleanup - Eliminated code duplication throughout codebase
• Dead Code Removal - Removed unused missing_param helper, deprecated tauri-api.ts, redundant KimiModelSelector

---

Internal Optimizations (User Transparent)

Removed Legacy Migration Logic

v3.6.0 removed v1 config auto-migration and copy file scanning logic:

• Impact: Improved startup performance, cleaner codebase
• Compatibility: v2 format configs fully compatible, no action required
• Note: Users upgrading from v3.1.0 or earlier should first upgrade to v3.2.x or v3.5.x for one-time migration, then upgrade to v3.6.0

Command Parameter Standardization

Backend unified to use app parameter (values: claude or codex):

• Impact: More standardized code, friendlier error prompts
• Compatibility: Frontend fully adapted, users don't need to care about this change

---

Dependencies

• Updated to Tauri 2.8.x
• Updated to TailwindCSS 4.x
• Updated to TanStack Query v5.90.x
• Maintained React 18.2.x and TypeScript 5.3.x

---

🌟 About CC Switch

CC Switch is a cross-platform desktop application for managing and switching between different provider configurations for Claude Code and Codex. Built with Tauri 2.0 + React 18 + TypeScript, supporting Windows, macOS, and Linux.

Core Features:

• 🔄 One-click switching between multiple AI providers
• 📦 Support for both Claude Code and Codex applications
• 🎨 Modern UI with complete Chinese/English internationalization
• 🔐 Local storage, secure and reliable data
• ☁️ Support for cloud sync configurations
• 🧩 Unified MCP server management

---

Project Repository: https://github.com/farion1231/cc-switch