cc-switchy

简体中文 · English

cc-switchy is a download-only Rust CLI and Ratatui application for restoring CC Switch cloud snapshots from WebDAV or S3-compatible storage. It can manage multiple sources, restore the latest selected snapshot, and apply providers, MCP servers, and Skills to supported local Agents, including Grok Build and Pi.

cc-switchy --sync always downloads and applies the current snapshot from the selected source. It does not upload, merge, or delete remote data.

简体中文

功能

• 默认启动支持键盘与鼠标的 Ratatui TUI。
• 通过向导管理多个 WebDAV 与 S3 同步源：列表、新增、查看、编辑、删除、测试和设置默认源。
• cc-switchy --sync 一键重新下载并恢复默认源的最新快照。
• 安全恢复 CC Switch v2/db-v6 的 manifest.json、db.sql 和 skills.zip，兼容 WebDAV db-v5 旧路径回退。
• 兼容 CC Switch v3.18 的 SQLite schema v16，并支持 Grok Build 与 Pi 的供应商投影。
• 在 TUI 中查看供应商端点、模型和备注，并通过外部编辑器修改供应商。
• 将供应商、MCP 和 Skills 应用到本地 Agent，并在 TUI 中切换或重新应用供应商。
• CLI、向导、TUI、进度与错误均支持简体中文和英文。
• 全程显示阶段、下载字节、耗时、警告和备份位置。

安装

从 GitHub Releases 下载与系统对应的压缩包，校验 SHA256SUMS 后，将 cc-switchy（Windows 为 cc-switchy.exe）放入 PATH。

也可以从源码构建：

git clone https://github.com/ca-x/cc-switchy.git
cd cc-switchy
cargo build --release --locked
install -Dm755 target/release/cc-switchy ~/.local/bin/cc-switchy

发布包含以下目标：

• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• aarch64-unknown-linux-musl
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-msvc

Linux GNU 构建依赖构建环境的 glibc 基线。需要更强的发行版兼容性、静态 运行时或容器部署时，优先使用 MUSL 构建。

首次运行与命令

cc-switchy
cc-switchy --wizard
cc-switchy --sync
cc-switchy --sync --source backup-s3
cc-switchy --lang zh
cc-switchy --lang en

• cc-switchy：打开 TUI。没有同步源时显示 cc-switchy --wizard 引导。
• cc-switchy --wizard：打开同步源管理向导。
• cc-switchy --sync：从默认源重新下载、校验、恢复并应用当前快照。
• cc-switchy --sync --source backup-s3：只在本次运行使用 backup-s3，不修改默认源。
• --lang zh|en：只覆盖本次运行的语言；向导/TUI 中的语言操作会持久化偏好。

向导按键

• a 新增 WebDAV 或 S3 来源
• 表单内直接输入文字，Tab/Shift+Tab 切换字段
• Enter 查看详情、进入下一字段或保存
• e 编辑，x 删除，t 测试连接，m 设置默认源
• b 打开备份设置；可开关备份并设置全局保留数量，0 表示不限数量
• L 切换语言
• Esc 放弃当前表单或返回上一层
• q 在非表单界面退出，Ctrl+C 可从任意向导界面退出
• 详情页使用 PageUp/PageDown 滚动长内容

向导同时支持鼠标操作：单击列表项或字段会先选中，滚轮移动选择，底部动作栏可 直接单击；详情页滚轮用于滚动。动作栏会在窄终端自动换行，不会隐藏可用操作。 删除、保存等操作仍使用明确的动作按钮，不会因单击列表行直接执行。

首次新增的来源自动成为默认源。删除默认源时，如果仍有其他来源，必须先 选择替代默认源。密码和 Secret Access Key 完全遮挡，Access Key ID 只显示 有限前缀。

TUI 按键

• 顶栏持续显示当前 Agent、供应商、默认同步源和操作状态。
• 1 切换，2 同步，3 Skills，4 活动。
• ↑/↓ 或 j/k 移动，Tab/Shift+Tab 切换焦点。
• 窄终端可单击 [Tab] 详情/返回 往返列表和详情；详情使用 PageUp/PageDown 滚动。
• Agent 工作区获得焦点时，←/→ 或 h/l 切换 Agent；[/] 可在任意主界面切换 Agent。此操作只浏览，不会切换供应商。
• Enter 切换独占式 Agent 的供应商，或重新应用累加式 Agent 的受管供应商集合
• e 使用外部编辑器修改当前选中的供应商
• s 同步默认源；在“同步”页同步当前选中源
• t 测试选中源，m 设置默认源，w 打开向导，L 切换语言
• Esc 在本地恢复开始前请求取消，q 安全退出

鼠标可单击顶部任务标签、Agent 标签、供应商或同步源列表，以及底部动作栏；滚轮 用于移动当前列表或 Agent，在详情面板内则滚动详情。动作栏会按终端宽度自动换行。 列表行单击只选中，切换、编辑、同步等修改操作必须再单击明确的动作。

导航没有装饰动画。只有真实同步或应用操作才刷新进度，终端 raw mode、备用 屏幕和光标状态会在正常退出及 panic 路径恢复。

供应商详情与编辑

供应商详情页显示名称、状态、ID、分类、端点、模型、网站、排序、备注和配置项 名称，不显示配置值、API Key 或 URL 查询参数。按 e 或单击“编辑”会暂停 TUI， 依次使用 VISUAL、EDITOR 或系统默认编辑器（Unix 为 vi，Windows 为 notepad）打开临时 JSON 文件，不经过 shell。

可编辑字段为名称、settingsConfig、网站、备注和排序；供应商 ID、Agent、分类、 图标、元数据和当前状态保持不变。当前供应商或受管累加式供应商保存后会立即重新 投影；写入失败会恢复数据库和相关本地配置。除下文说明的 Pi 过渡兼容外，下一次 同步仍以远端快照为准，本地编辑会被覆盖。

配置文件

cc-switchy 自有配置位于 ~/.cc-switchy：

~/.cc-switchy/
├── config.toml
├── config.toml.bak
├── state.json
├── lock
├── staging/
└── backups/

CC Switch 兼容数据库、设备设置和默认 Skills SSOT 保留在 ~/.cc-switch。 如果本机 CC Switch 设置使用 ~/.agents/skills，则按该 SSOT 应用 Skills。

示例配置：

version = 1
language = "auto"
default_source = "home-webdav"

[backup]
enabled = true
max_count = 10

[[sources]]
name = "home-webdav"
type = "webdav"
remote_root = "cc-switch-sync"
profile = "default"

[sources.webdav]
base_url = "https://dav.example.com/remote.php/dav/files/user"
username = "user"
password = "replace-me"

[[sources]]
name = "backup-s3"
type = "s3"
remote_root = "cc-switch-sync"
profile = "default"

[sources.s3]
region = "auto"
bucket = "cc-switch"
endpoint = "https://account.r2.cloudflarestorage.com"
access_key_id = "replace-me"
secret_access_key = "replace-me"

空 S3 endpoint 使用 AWS 虚拟主机风格；自定义端点使用 path-style。未写协议 的自定义端点默认使用 HTTPS。

同步、恢复与回滚

显式同步每次都重新获取 manifest 和两个制品；云端所选快照是本次恢复的权威 来源，即使本地数据更新也不会做双向合并。流程会先校验协议、大小、SHA-256、 ZIP 路径和 SQL。备份开启时，程序会先创建完整本地备份、执行保留清理，再替换 数据库与 Skills。

备份保存在 ~/.cc-switchy/backups/<timestamp>/，默认开启并全局保留最新 10 个。 max_count = 0 表示不限数量；正数限制会在下一次开启备份的同步中清理最旧的已 识别备份。未知目录、文件和符号链接不会自动删除。enabled = false 时完全不创建 备份，因此恢复失败时也无法回滚；向导保存此设置前会再次确认。备份开启时， 数据库替换失败会回滚 Skills；任何 Agent 投影失败会成为警告，其他 Agent 继续应用。

• Exit code 0：恢复及所有本地投影成功。
• Exit code 1：配置、网络、校验、恢复或回滚失败。
• Exit code 2：数据库和 Skills 已恢复，但一个或多个 Agent 投影产生警告。

Agent 能力

Agent	供应商模式	MCP	Skills
Claude	独占	支持	支持
Claude Desktop	独占；仅 macOS/Windows，代理模式为警告	不支持	不支持
Codex	独占	支持	支持
Gemini	独占	支持	支持
Grok Build	独占	支持	支持
OpenCode	累加	支持	支持
OpenClaw	累加	不支持	不支持
Hermes	累加	支持	支持
Pi	累加注册表并可选择当前供应商	不支持	不支持

Pi 写入 ~/.pi/agent/models.json 和 ~/.pi/agent/settings.json；设置 PI_CODING_AGENT_DIR 可覆盖该目录。同步会保留不由 cc-switchy 管理的供应商和 同一供应商下用户已选择的有效模型。若外部供应商与快照供应商使用相同 ID，普通 同步会保留外部配置并报告冲突；只有显式切换或编辑才会由 cc-switchy 接管该 ID。

当前 CC Switch 稳定版尚未默认生成 app_type = "pi" 行。作为过渡兼容，下载的 快照没有任何 Pi 行时，cc-switchy 会在临时数据库事务中保留本机已有的 Pi 供应商；当前下载快照只要包含任意 Pi 行，快照中的整组 Pi 供应商即为准，本地旧 行不会合并或复活。现有协议无法区分“原生支持 Pi 但供应商为空”和“尚不支持 Pi”， 所以空 Pi 快照仍按旧版快照保留本地配置。该机制不上传或下载 Pi sidecar，也不 新增任何远端写入。上游进度见 CC Switch #1855 与 PR #5598。

安全说明

CC Switch 快照协议不加密内容。db.sql 可能包含供应商 API Key、访问令牌和 其他明文秘密。必须保护 WebDAV/S3 存储、账户、网络访问和本地备份。

• cc-switchy 只实现 GET/HEAD 与只读连接诊断，不包含远程上传、删除或建桶接口。
• config.toml 与 state.json 在 Unix 上使用 0600；凭据仍以兼容所需的明文保存。
• 下载大小、ZIP 展开路径/数量/总量、SQL 导入和 SHA-256 均在修改本地状态前校验。
• Reqwest 使用 Rustls 与 webpki roots。依赖仅由私有 CA 签发的 WebDAV/S3 端点 默认不会被信任；当前版本不提供自定义 CA 导入参数。
• 日志和 TUI 会遮挡密码、Authorization、S3 签名和 URL 查询值，但操作系统、 终端录制和备份权限仍需由使用者保护。
• 供应商编辑临时文件在 Unix 上使用 0600，限制为 1 MiB，并拒绝符号链接、 非普通文件、无效 JSON 和被并发修改的供应商。

English

What it does

• Opens a keyboard-and-mouse Ratatui TUI by default.
• Manages multiple WebDAV and S3 sources with CRUD, connection tests, and one default source.
• Re-fetches and restores the current selected CC Switch snapshot with one --sync command.
• Safely validates and restores CC Switch v2/db-v6 manifest.json, db.sql, and skills.zip artifacts.
• Supports the CC Switch v3.18 SQLite schema v16 and projects Grok Build and Pi providers.
• Shows provider endpoint, model, website, notes, and config-key details, with external-editor updates from the TUI.
• Projects providers, MCP servers, and Skills to supported local Agents and switches or reapplies providers from the TUI.
• Renders CLI, Wizard, TUI, progress, and errors in English or Simplified Chinese.

Quick start

Download a target archive from GitHub Releases, verify it against SHA256SUMS, and place the executable on PATH. The six target triples are listed in the Chinese installation section above.

cc-switchy --wizard
cc-switchy
cc-switchy --sync
cc-switchy --sync --source backup-s3
cc-switchy --lang en
cc-switchy --lang zh

The first source becomes the default. --source overrides it only for the current invocation. Every explicit sync re-downloads the current remote snapshot and overwrites/repairs compatible local state; there is no timestamp comparison, merge, upload, remote delete, or conflict resolution.

Wizard and TUI

Wizard keys: printable characters enter text inside forms, Tab/Shift+Tab changes fields, Enter inspects/advances/saves, a adds, e edits, x deletes, t tests, m makes the selected source default, b opens the global backup settings, and L changes language. Backup settings provide an explicit creation switch and retention count; 0 means unlimited. Esc discards a form or goes back, q exits outside forms, and Ctrl+C exits from every Wizard screen. PageUp/PageDown scroll long details. Wizard lists, choices, fields, and contextual footer actions also accept mouse clicks and wheel input; footer actions wrap instead of disappearing on narrow terminals.

The TUI header always shows the selected Agent, its current provider, the default sync source, and operation state. Main keys are 1 Switch, 2 Sync, 3 Skills, and 4 Activity. Use j/k or arrows to move, Tab to change focus, left/right while the Agent workspace is focused, or [/] anywhere to browse Agents. Enter switches or reapplies providers, s syncs, t tests a source, m makes it default, e edits the selected provider, w opens the Wizard, L changes language, and q quits safely. Mouse clicks select task tabs, Agents, rows, and explicit footer actions; selecting a row alone never switches or edits it. On narrow terminals, the clickable [Tab] Details/back action changes panes. PageUp/PageDown or the mouse wheel scrolls long details, and footer actions wrap without being dropped.

Provider editing uses VISUAL, then EDITOR, then vi on Unix or notepad on Windows. The temporary JSON allows changes to the name, settingsConfig, website, notes, and sort index while keeping identity and snapshot-owned metadata immutable. Current or managed additive providers are reprojected immediately with rollback on failure. A later remote sync replaces local edits except for the temporary Pi compatibility rule described below.

Pi providers are merged into ~/.pi/agent/models.json, while active provider and model selection live in settings.json; PI_CODING_AGENT_DIR overrides that directory. Foreign providers and a valid user-selected model are kept. When a foreign provider and a snapshot provider share an ID, normal sync keeps the foreign entry and reports the collision; an explicit switch or edit claims that ID for cc-switchy. Current stable CC Switch releases do not emit app_type = "pi" rows by default. As a compatibility bridge, when a downloaded snapshot has no Pi rows, cc-switchy transactionally carries the existing local Pi provider set into the prepared database. Whenever the current snapshot contains any native Pi row, that complete snapshot Pi set is authoritative and stale local rows are not merged or resurrected. The current protocol cannot distinguish "native Pi with an empty provider set" from "Pi not supported", so an empty Pi snapshot still uses the legacy preservation rule. This behavior adds no Pi sidecar upload, sidecar download, or other remote write operation. Track upstream support in CC Switch #1855 and PR #5598.

Storage and results

Application configuration, progress state, staging, and durable backups live under ~/.cc-switchy. The compatible database, device-local settings, and default Skills SSOT remain under ~/.cc-switch; a configured ~/.agents/skills SSOT is respected.

Backups are enabled by default and the newest 10 recognized backups are kept globally. Set [backup].max_count = 0 for unlimited retention. When [backup].enabled = false, synchronization creates no backup and restore failures cannot roll back. Positive limits are enforced during the next sync with backups enabled; unknown directories, files, and symbolic links are kept.

• Exit code 0: restore and all requested projections succeeded.
• Exit code 1: configuration, transport, validation, restore, or rollback failed.
• Exit code 2: database and Skills were restored, but at least one Agent projection warned.

The Agent capability matrix and TOML example in the Chinese section apply equally to the English interface.

Security limits

The CC Switch snapshot format is not encrypted. db.sql may contain provider API keys, access tokens, and other plaintext secrets. Protect the WebDAV/S3 account, storage, network path, local configuration, and backups accordingly.

cc-switchy exposes no remote write API. It validates manifest and artifact limits, SHA-256 hashes, ZIP paths and expansion limits, and SQL imports before live replacement. It uses Rustls with public webpki roots; endpoints signed only by a private CA are not trusted unless that CA is available through a future supported mechanism. For Linux portability, prefer the MUSL release; the GNU binary inherits the build runner's glibc baseline.

Compatibility and license

cc-switchy is MIT licensed. CC Switch compatibility behavior was studied and adapted from CC Switch at commits c6197ae32450cd70e2bf03b35e3f5f53ac12044c, 3d176b98cc0bfd151a42882e88ab59b62083b92f (v3.17.0, SQLite schema v13), and a377d79303bc1e592d2783d559ca5bd6b8ba1417 (v3.18.0, SQLite schema v16 and Grok Build). See THIRD_PARTY_NOTICES.md for attribution and the upstream MIT notice. Pi behavior also follows Pi Coding Agent and pi-switch; provider editing and TUI interaction were compared with cc-switch-cli.