# CC Switch

> 🚀 Claude Code 配置切换器 - 轻松管理多个 Claude Code 配置

CC Switch 是一个命令行工具，帮助您轻松管理和切换多个 Claude Code 配置。支持存储多组 URL 和 Token，并可一键切换，提升开发效率。

## ✨ 特性

- 🔧 **多配置管理** - 存储和管理多个 Claude Code 配置
- 🔄 **一键切换** - 快速切换不同的 URL 和 Token
- 🛡️ **安全存储** - Token 安全遮蔽显示，配置文件权限保护
- 💾 **自动备份** - 切换前自动备份，支持手动备份和恢复
- 🔍 **智能检测** - 自动检测 Claude Code 配置文件位置
- 📊 **系统诊断** - 全面的系统状态检查和问题诊断
- 🌐 **跨平台** - 支持 macOS、Linux 和 Windows

## 📦 安装

### 系统要求

- Node.js 18 或更高版本
- Claude Code 已安装

### 快速安装

#### macOS / Linux

```bash
# 克隆项目
git clone https://github.com/songunity/ccswitch.git
cd cc-switch

# 安装依赖
npm install

# 运行安装脚本
./install.sh
```

#### Windows

```cmd
# 克隆项目
git clone https://github.com/songunity/ccswitch.git
cd cc-switch

# 安装依赖
npm install

# 运行安装脚本
install.bat
```

### 手动安装

```bash
# 构建项目
npm run build

# 全局链接（开发模式）
npm link

# 或直接使用
node dist/cli.js
```

## 🚀 快速开始

### 1. 检查系统状态

```bash
ccs diagnostics
```

### 2. 添加配置

```bash
# 添加开发环境配置
ccs add dev https://api.anthropic.com sk-ant-api03-your-dev-token

# 添加生产环境配置  
ccs add prod https://api.anthropic.com sk-ant-api03-your-prod-token
```

### 3. 查看配置列表

```bash
ccs list
```

### 4. 切换配置

```bash
# 切换到开发环境
ccs switch dev

# 切换到生产环境
ccs switch prod
```

### 5. 查看当前配置

```bash
ccs current
```

## 📋 命令参考

### 基础命令

| 命令 | 简写 | 描述 | 示例 |
|------|------|------|------|
| `add <name> <url> <token>` | `a` | 添加新配置 | `ccs add dev https://api.anthropic.com sk-xxx` |
| `list` | `ls` | 显示所有配置 | `ccs list` |
| `switch <name>` | `sw` | 切换到指定配置 | `ccs switch dev` |
| `remove <name>` | `rm` | 删除配置 | `ccs remove dev` |
| `current` | `cur` | 显示当前配置 | `ccs current` |

### 高级命令

| 命令 | 简写 | 描述 | 示例 |
|------|------|------|------|
| `backup` | - | 创建手动备份 | `ccs backup` |
| `restore <backup-file>` | - | 从备份恢复 | `ccs restore ~/.claude/settings.json.backup.xxx` |
| `diagnostics` | `diag` | 系统诊断 | `ccs diagnostics` |

### 帮助命令

```bash
# 显示帮助信息
ccs --help

# 显示版本信息
ccs --version

# 显示特定命令帮助
ccs help <command>
```

## 🛡️ 安全特性

### Token 安全

- **智能遮蔽**: 根据 token 类型（sk-ant-, sk-, pk- 等）智能遮蔽显示
- **安全存储**: 配置文件权限设置为 600（仅所有者可读写）
- **原子操作**: 使用临时文件和原子重命名确保写入安全

### 备份保护

- **自动备份**: 每次切换前自动创建备份
- **备份管理**: 自动保留最近 5 个备份文件
- **恢复功能**: 支持从任意备份文件恢复配置

### 权限检查

- **文件权限**: 自动检查和设置适当的文件权限
- **目录权限**: 确保配置目录权限安全
- **访问验证**: 切换前验证目标文件的读写权限

## 📁 配置文件位置

### CCS 配置文件

- **位置**: `~/.ccswitcher/configs.json`
- **权限**: 600 (仅所有者可读写)
- **内容**: 存储所有 CCS 配置和设置

### Claude Code 配置文件

CCS 自动检测以下位置的 Claude Code 配置：

1. `~/.claude/settings.json` (用户级别，优先)
2. `.claude/settings.json` (项目级别)  
3. `.claude/settings.local.json` (项目本地)

## 🔧 配置选项

### 全局设置

CCS 配置文件支持以下全局设置：

```json
{
  "configs": [...],
  "currentConfig": "dev",
  "settings": {
    "backupRetentionCount": 5,
    "autoBackup": true
  }
}
```

### 配置验证

- **URL 验证**: 必须是有效的 HTTP/HTTPS URL
- **Token 验证**: 不能为空，至少 10 个字符
- **名称验证**: 不能包含特殊字符，不能使用保留字

## 🐛 故障排除

### 常见问题

#### 1. 配置文件不存在

```bash
# 运行诊断检查
ccs diagnostics

# 确保 Claude Code 已安装并至少运行过一次
# 手动创建目录（如需要）
mkdir -p ~/.claude
```

#### 2. 权限被拒绝

```bash
# 修复文件权限
chmod 755 ~/.claude
chmod 644 ~/.claude/settings.json

# 修复 CCS 配置权限
chmod 700 ~/.ccswitcher
chmod 600 ~/.ccswitcher/configs.json
```

#### 3. 切换后配置不生效

```bash
# 检查当前状态
ccs current

# 重新切换配置
ccs switch <config-name>

# 检查 Claude Code 配置文件
cat ~/.claude/settings.json
```

### 错误代码

| 错误代码 | 描述 | 解决方案 |
|----------|------|----------|
| `CONFIG_NOT_FOUND` | 配置不存在 | 使用 `ccs list` 查看可用配置 |
| `CONFIG_EXISTS` | 配置名称已存在 | 选择不同的名称或删除现有配置 |
| `CLAUDE_CONFIG_NOT_FOUND` | Claude 配置文件不存在 | 运行 Claude Code 创建配置文件 |
| `PERMISSION_DENIED` | 权限不足 | 检查并修复文件权限 |
| `INVALID_URL` | URL 格式错误 | 确保 URL 以 http:// 或 https:// 开头 |
| `INVALID_TOKEN` | Token 格式错误 | 检查 token 长度和格式 |

## 🔄 使用流程

### 典型工作流程

```bash
# 1. 初次设置
ccs diagnostics                    # 检查系统状态
ccs add dev https://dev-api.com sk-dev-token    # 添加开发配置
ccs add prod https://api.com sk-prod-token      # 添加生产配置

# 2. 日常使用
ccs list                          # 查看所有配置
ccs switch dev                    # 切换到开发环境
# 进行开发工作...
ccs switch prod                   # 切换到生产环境
# 进行生产部署...

# 3. 维护
ccs backup                        # 手动备份
ccs current                       # 检查当前状态
ccs diagnostics                   # 定期诊断检查
```

### 团队协作

```bash
# 导出配置（不包含敏感信息）
ccs list > team-configs.txt

# 团队成员添加相同的配置结构
ccs add staging https://staging-api.com <their-staging-token>
ccs add production https://prod-api.com <their-prod-token>
```

## 📊 系统监控

### 诊断报告

`ccs diagnostics` 命令提供全面的系统状态报告：

- **系统信息**: 平台、Node.js 版本、主目录
- **配置状态**: CCS 配置文件状态和统计
- **Claude 配置**: 所有检测到的 Claude 配置文件状态
- **权限检查**: 文件创建和读取权限验证
- **问题识别**: 自动识别问题并提供解决建议

### 状态检查

```bash
# 快速状态检查
ccs current

# 详细系统诊断
ccs diagnostics

# 配置列表和状态
ccs list
```

## 🎯 最佳实践

### 配置命名

- 使用描述性名称：`dev`, `staging`, `prod`
- 避免特殊字符和空格
- 保持简短且易记

### 安全建议

- 定期更换 Token
- 不要在公共场所显示配置
- 定期备份重要配置
- 使用系统诊断检查安全状态

### 维护建议

- 定期运行 `ccs diagnostics`
- 清理不需要的配置：`ccs remove <name>`
- 检查备份文件占用空间
- 更新 CCS 到最新版本

## 🆘 获取帮助

### 内置帮助

```bash
ccs --help              # 总体帮助
ccs help add            # 特定命令帮助
ccs diagnostics         # 系统诊断
```

### 社区支持

- **GitHub Issues**: [项目地址](https://github.com/songunity/ccswitch/issues)
- **文档**: [详细文档](https://github.com/songunity/ccswitch/wiki)

### 问题报告

报告问题时，请包含：

1. CCS 版本：`ccs --version`
2. 系统诊断：`ccs diagnostics`
3. 具体错误信息
4. 复现步骤

## 📝 许可证

此项目基于 ISC 许可证开源。

## 🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！

---

**Happy Coding with CC Switch! 🚀**