Package Exports

@songhe/cc-switch
@songhe/cc-switch/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@songhe/cc-switch) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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

# 安装依赖
npm install

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

Windows

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

# 安装依赖
npm install

# 运行安装脚本
install.bat

手动安装

# 构建项目
npm run build

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

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

🚀 快速开始

1. 检查系统状态

ccs diagnostics

2. 添加配置

# 添加开发环境配置
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. 查看配置列表

ccs list

4. 切换配置

# 切换到开发环境
ccs switch dev

# 切换到生产环境
ccs switch prod

5. 查看当前配置

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`

帮助命令

# 显示帮助信息
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 配置：

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

🔧 配置选项

全局设置

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

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

配置验证

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

🐛 故障排除

常见问题

1. 配置文件不存在

# 运行诊断检查
ccs diagnostics

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

2. 权限被拒绝

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

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

3. 切换后配置不生效

# 检查当前状态
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 长度和格式

🔄 使用流程

典型工作流程

# 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                   # 定期诊断检查

团队协作

# 导出配置（不包含敏感信息）
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 配置文件状态
权限检查: 文件创建和读取权限验证
问题识别: 自动识别问题并提供解决建议

状态检查

# 快速状态检查
ccs current

# 详细系统诊断
ccs diagnostics

# 配置列表和状态
ccs list

🎯 最佳实践

配置命名

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

安全建议

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

维护建议

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

🆘 获取帮助

内置帮助

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

社区支持

GitHub Issues: 项目地址
文档: 详细文档

问题报告

报告问题时，请包含：

CCS 版本：ccs --version
系统诊断：ccs diagnostics
具体错误信息
复现步骤

📝 许可证

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

🤝 贡献

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

Happy Coding with CC Switch! 🚀