diff --git a/CLAUDE.md b/CLAUDE.md index 388b0f5..8ce7473 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 项目概述 -XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI API 路由器的集成。项目包含跨平台的安装脚本,支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash)。 +XCodeCLI-Shells 是一个智能配置工具集,用于设置 Claude Code 与 XCodeCLI API 路由器的集成。项目包含跨平台的安装脚本,支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash),具备自动端点发现和选择功能。 ## 核心架构 @@ -14,17 +14,18 @@ XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI 两个脚本提供相同的功能: - 验证 API 密钥格式 -- 测试 API 连接 +- **智能端点发现**: 自动测试多个 API 端点并选择可用的 +- **自动 API 连接测试**: 使用 `/v1/models` 端点验证连接 - 创建 Claude Code 配置文件 (~/.claude/settings.json) - 设置环境变量 (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN) -- 支持团队和个人 API 端点 +- 支持环境变量传递 API 密钥 (bash 脚本) ### 配置结构 脚本生成的 settings.json 包含: ```json { "env": { - "ANTHROPIC_BASE_URL": "<用户提供的URL>", + "ANTHROPIC_BASE_URL": "<自动选择的URL>", "ANTHROPIC_AUTH_TOKEN": "<用户API密钥>", "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 20000, "DISABLE_TELEMETRY": 1, @@ -37,15 +38,34 @@ XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI } ``` +### 支持的 API 端点 +脚本会按顺序测试以下端点,选择第一个可用的: +1. `https://api.xcodecli.com` +2. `https://newapi.sususu.cf` + ## 常用命令 +### 🚀 一行命令快速配置 + +#### Windows (PowerShell) +```powershell +$key='YOUR_API_KEY' +iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.ps1 | iex +``` + +#### Unix/Linux/macOS (Bash) +```bash +export API_KEY='YOUR_API_KEY' +curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.sh | bash +``` + ### Windows (PowerShell) ```powershell -# 基本使用 -.\setup-claude-code.ps1 -BaseUrl https://api.xcodecli.com -ApiKey your-api-key +# 基本使用(自动选择可用端点) +.\setup-claude-code.ps1 -ApiKey your-api-key -# 测试连接 -.\setup-claude-code.ps1 -Test -BaseUrl https://api.xcodecli.com -ApiKey your-api-key +# 测试连接(测试所有端点) +.\setup-claude-code.ps1 -Test -ApiKey your-api-key # 显示当前设置 .\setup-claude-code.ps1 -Show @@ -59,11 +79,15 @@ XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI ### Unix/Linux/macOS (Bash) ```bash -# 基本使用 -./setup-claude-code.sh --url https://api.xcodecli.com --key your-api-key +# 基本使用(自动选择可用端点) +./setup-claude-code.sh --key your-api-key -# 测试连接 -./setup-claude-code.sh --test --url https://api.xcodecli.com --key your-api-key +# 使用环境变量 +export API_KEY='your-api-key' +./setup-claude-code.sh + +# 测试连接(测试所有端点) +./setup-claude-code.sh --test --key your-api-key # 显示当前设置 ./setup-claude-code.sh --show @@ -75,16 +99,24 @@ XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI ./setup-claude-code.sh --help ``` -## API 端点支持 +## 智能特性 + +### 自动端点发现 +脚本使用智能算法自动发现和选择最佳可用的 API 端点: + +1. **端点测试**: 依次测试所有配置的端点 +2. **连通性验证**: 使用 `/v1/models` 端点检查服务可用性 +3. **模型验证**: 确保端点返回有效的模型列表 +4. **自动选择**: 选择第一个通过所有测试的端点 +5. **智能降级**: 如果所有端点都失败,提供手动选择选项 + +### 错误处理和恢复 +- **连接失败**: 自动尝试下一个端点 +- **认证失败**: 提供清晰的错误信息和解决建议 +- **服务不可用**: 智能降级到默认配置 +- **用户选择**: 在失败时允许用户决定是否继续 -### 个人 API -- 端点: `/api/v1/claude/balance` -- 响应字段: `balance` -### 团队 API -- 端点: `/api/v1/team/stats/spending` -- 响应字段: `daily_remaining` -- URL 格式: 必须以 `/team` 结尾 ## 开发注意事项 @@ -93,19 +125,81 @@ XCodeCLI-Shells 是一个配置工具集,用于设置 Claude Code 与 XCodeCLI - 彩色输出功能 (Blue/Green/Yellow/Red) - 环境变量持久化 (用户级别) - JSON 配置验证 +- **智能端点测试**: 自动测试多个 API 端点 +- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头 +- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性 ### Bash 脚本特性 - 依赖 jq 进行 JSON 处理 - ANSI 颜色输出 - 临时文件清理 - 错误处理和回滚机制 +- **环境变量支持**: 支持 `API_KEY` 环境变量 +- **智能端点测试**: 自动测试多个 API 端点 +- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头 +- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性 ### 安全考虑 - API 密钥格式验证 (仅允许字母数字、连字符、下划线) - 配置文件自动备份 (时间戳) - 敏感信息掩码显示 - HTTP 状态码验证 +- **端点安全**: 仅测试预定义的可信端点 +- **连接超时**: 自动处理网络超时情况 ### 配置文件位置 - Windows: `%USERPROFILE%\.claude\settings.json` -- Unix/Linux/macOS: `~/.claude/settings.json` \ No newline at end of file +- Unix/Linux/macOS: `~/.claude/settings.json` + +## 故障排除 + +### 端点连接问题 +如果所有端点都无法连接: +1. 检查网络连接 +2. 验证 API 密钥是否有效 +3. 确认防火墙设置允许访问 +4. 检查代理配置 + +### API 密钥认证失败 +如果遇到 401 认证错误: +1. 验证 API 密钥格式是否正确 +2. 确认密钥是否过期 +3. 检查密钥权限设置 +4. 尝试重新生成密钥 + +### 脚本执行问题 +#### PowerShell 执行策略错误 +```powershell +powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1 +``` + +#### Bash 权限问题 +```bash +chmod +x setup-claude-code.sh +``` + +### 环境变量问题 +#### Windows +检查用户环境变量是否正确设置: +```powershell +[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", [EnvironmentVariableTarget]::User) +[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", [EnvironmentVariableTarget]::User) +``` + +#### Unix/Linux/macOS +检查环境变量: +```bash +echo $ANTHROPIC_BASE_URL +echo $ANTHROPIC_AUTH_TOKEN +``` + +## 总结 + +XCodeCLI-Shells 现在提供智能化的配置体验: +- **零配置URL**: 无需手动指定API端点,自动发现可用服务 +- **一键安装**: 支持从远程直接下载执行 +- **智能降级**: 在连接失败时提供多种选择 +- **跨平台一致性**: Windows 和 Unix/Linux/macOS 脚本功能完全一致 +- **用户友好**: 清晰的错误提示和帮助信息 + +通过这些改进,用户只需要关心 API 密钥,其他配置都由脚本智能处理。 \ No newline at end of file diff --git a/README.md b/README.md index 495db84..9ac1a62 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,57 @@ # XCodeCLI-Shells -> Configuration scripts for integrating Claude Code with XCodeCLI API router +> Claude Code 与 XCodeCLI API 路由器集成的配置脚本 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-blue.svg)](https://github.com/your-username/XCodeCLI-Shells) -## Overview +## 项目简介 -XCodeCLI-Shells is a cross-platform configuration toolkit for setting up Claude Code integration with XCodeCLI API router. These scripts enable you to easily configure Claude Code to use custom API endpoints, supporting both personal and team API access. +XCodeCLI-Shells 是一个跨平台的配置工具集,用于设置 Claude Code 与 XCodeCLI API 路由器的集成。通过这些脚本,您可以轻松配置 Claude Code 使用自定义的 API 端点,支持个人和团队 API 访问。 -## Features +## 功能特性 -- 🌐 **Cross-platform support**: Windows (PowerShell) and Unix/Linux/macOS (Bash) -- 🔐 **Security validation**: API key format validation and connection testing -- ⚡ **Quick setup**: Auto-generates Claude Code configuration files and environment variables -- 🛡️ **Data protection**: Automatic backup of existing configs, sensitive info masking -- 🎯 **Multi-endpoint support**: Supports both personal and team API endpoints -- 📊 **Real-time feedback**: Colored output and detailed status information +- 🌐 **跨平台支持**: 支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash) +- 🔐 **安全验证**: API 密钥格式验证和连接测试 +- ⚡ **快速配置**: 自动生成 Claude Code 配置文件和环境变量 +- 🛡️ **数据保护**: 自动备份现有配置,敏感信息掩码显示 +- 🎯 **智能端点选择**: 自动测试多个 API 端点,选择最佳可用服务 +- 📊 **实时反馈**: 彩色输出和详细的状态信息 +- 🚀 **一键安装**: 支持从远程直接下载执行,无需本地文件 -## Quick Start +## 快速开始 -### Requirements +### 🚀 一行命令快速配置 + +#### Windows (PowerShell) +```powershell +$key='YOUR_API_KEY' +iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.ps1 | iex +``` + +#### Unix/Linux/macOS (Bash) +```bash +export API_KEY='YOUR_API_KEY' +curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.sh | bash +``` + +> **注意**: 请将 `YOUR_API_KEY` 替换为您的实际 API 密钥。脚本会自动测试 `https://api.xcodecli.com` 和 `https://newapi.sususu.cf`,选择可用的端点。 + +### 环境要求 #### Windows -- PowerShell 5.0 or higher -- Internet connection +- PowerShell 5.0 或更高版本 +- 网络连接 #### Unix/Linux/macOS - Bash shell -- `jq` command-line tool -- `curl` tool +- `jq` 命令行工具 +- `curl` 工具 -### Install jq (Unix/Linux/macOS only) +### 安装 jq (仅 Unix/Linux/macOS) ```bash -# macOS (using Homebrew) +# macOS (使用 Homebrew) brew install jq # Ubuntu/Debian @@ -42,109 +59,105 @@ sudo apt-get install jq # CentOS/RHEL/Fedora sudo yum install jq -# or (newer versions) +# 或者 (较新版本) sudo dnf install jq ``` -## Usage +## 使用方法 ### Windows (PowerShell) -#### Basic usage +#### 基本使用 ```powershell -.\setup-claude-code.ps1 -BaseUrl https://api.xcodecli.com -ApiKey your-api-key-here +.\setup-claude-code.ps1 -ApiKey your-api-key-here ``` -#### Interactive mode +#### 交互模式 ```powershell .\setup-claude-code.ps1 ``` -#### Test connection +#### 测试连接 ```powershell -.\setup-claude-code.ps1 -Test -BaseUrl https://api.xcodecli.com -ApiKey your-api-key-here +.\setup-claude-code.ps1 -Test -ApiKey your-api-key-here ``` -#### Show current settings +#### 显示当前设置 ```powershell .\setup-claude-code.ps1 -Show ``` -#### Help +#### 帮助信息 ```powershell .\setup-claude-code.ps1 -Help ``` +> **智能端点选择**: 脚本会自动测试多个 API 端点并选择可用的那个,无需手动指定 URL。 + ### Unix/Linux/macOS (Bash) -#### Basic usage +#### 基本使用 ```bash -./setup-claude-code.sh --url https://api.xcodecli.com --key your-api-key-here +./setup-claude-code.sh --key your-api-key-here ``` -#### Interactive mode +#### 交互模式 ```bash ./setup-claude-code.sh ``` -#### Test connection +#### 测试连接 ```bash -./setup-claude-code.sh --test --url https://api.xcodecli.com --key your-api-key-here +./setup-claude-code.sh --test --key your-api-key-here ``` -#### Show current settings +#### 显示当前设置 ```bash ./setup-claude-code.sh --show ``` -#### Help +#### 帮助信息 ```bash ./setup-claude-code.sh --help ``` -## Parameters +> **智能端点选择**: 脚本会自动测试多个 API 端点并选择可用的那个,无需手动指定 URL。 -### PowerShell Script Parameters +## 参数说明 -| Parameter | Type | Description | -|-----------|------|-------------| -| `-BaseUrl` | String | XCodeCLI API base URL | -| `-ApiKey` | String | API key | -| `-Test` | Switch | Test API connection only | -| `-Show` | Switch | Show current settings | -| `-Help` | Switch | Show help information | +### PowerShell 脚本参数 -### Bash Script Parameters +| 参数 | 类型 | 描述 | +|------|------|------| +| `-ApiKey` | String | API 密钥 | +| `-Test` | Switch | 仅测试 API 连接(会自动测试所有可用端点) | +| `-Show` | Switch | 显示当前设置 | +| `-Help` | Switch | 显示帮助信息 | -| Parameter | Type | Description | -|-----------|------|-------------| -| `-u, --url` | String | XCodeCLI API base URL | -| `-k, --key` | String | API key | -| `-t, --test` | Flag | Test API connection only | -| `-s, --show` | Flag | Show current settings | -| `-h, --help` | Flag | Show help information | +> **自动端点发现**: 脚本会自动测试以下端点并选择第一个可用的: +> - `https://api.xcodecli.com` +> - `https://newapi.sususu.cf` -## API Endpoint Support +### Bash 脚本参数 -### Personal API -- **Endpoint**: `/api/v1/claude/balance` -- **Response field**: `balance` -- **Usage**: Query personal account balance +| 参数 | 类型 | 描述 | +|------|------|------| +| `-k, --key` | String | API 密钥 | +| `-t, --test` | Flag | 仅测试 API 连接(会自动测试所有可用端点) | +| `-s, --show` | Flag | 显示当前设置 | +| `-h, --help` | Flag | 显示帮助信息 | -### Team API -- **Endpoint**: `/api/v1/team/stats/spending` -- **Response field**: `daily_remaining` -- **Usage**: Query team daily remaining quota -- **URL format**: Must end with `/team` +> **环境变量支持**: 脚本也支持通过 `API_KEY` 环境变量传递 API 密钥。 -## Configuration Files -Scripts create configuration files at: +## 配置文件 + +脚本会在以下位置创建配置文件: - **Windows**: `%USERPROFILE%\.claude\settings.json` - **Unix/Linux/macOS**: `~/.claude/settings.json` -### Configuration Structure +### 配置文件结构 ```json { @@ -162,63 +175,63 @@ Scripts create configuration files at: } ``` -## Security Features +## 安全特性 -- **API key validation**: Only accepts keys with alphanumeric characters, hyphens, and underscores -- **Configuration backup**: Auto-backup existing config files (with timestamp) -- **Sensitive info protection**: Automatic masking of API keys in output -- **Connection verification**: Test API connection validity before configuration +- **API 密钥验证**: 只接受包含字母数字、连字符和下划线的密钥格式 +- **配置备份**: 自动备份现有配置文件(带时间戳) +- **敏感信息保护**: 在输出中自动掩码显示 API 密钥 +- **连接验证**: 配置前测试 API 连接有效性 -## Troubleshooting +## 故障排除 -### Windows PowerShell Execution Policy Error +### Windows PowerShell 执行策略错误 -If you encounter execution policy errors, use: +如果遇到执行策略错误,请使用以下命令: ```powershell powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1 ``` -### Unix/Linux/macOS Permission Issues +### Unix/Linux/macOS 权限问题 -Ensure the script has execute permissions: +确保脚本具有执行权限: ```bash chmod +x setup-claude-code.sh ``` -### jq Not Installed Error +### jq 未安装错误 -Please install `jq` tool according to the [Requirements](#requirements) section. +请按照[环境要求](#环境要求)部分安装 `jq` 工具。 -### API Connection Failed +### API 连接失败 -1. Check network connection -2. Verify API URL is correct -3. Confirm API key validity -4. Check firewall settings +1. 检查网络连接 +2. 验证 API URL 是否正确 +3. 确认 API 密钥有效性 +4. 检查防火墙设置 -## Verify Installation +## 验证安装 -After installation, you can verify Claude Code configuration with: +安装完成后,您可以使用以下命令验证 Claude Code 配置: ```bash claude --version ``` -## Contributing +## 贡献 -Welcome to submit Issues and Pull Requests to improve this project. +欢迎提交 Issues 和 Pull Requests 来改进这个项目。 -## License +## 许可证 -This project is licensed under the MIT License. See [LICENSE](LICENSE) file for details. +本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。 -## Related Links +## 相关链接 -- [Claude Code Official Documentation](https://docs.claude.com/en/docs/claude-code) -- [XCodeCLI Project](https://github.com/your-username/XCodeCLI) +- [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code) +- [XCodeCLI 项目](https://api.xcodecli.com) --- -**Note**: Please keep your API key secure and do not commit configuration files containing real API keys to public repositories. \ No newline at end of file +**注意**: 请确保您的 API 密钥安全,不要在公共代码库中提交包含真实 API 密钥的配置文件。 \ No newline at end of file