sususu/xcodecli-shells
Private
Public Access
1
0
Fork 0
Code Activity

docs: enhance CLAUDE.md with smart features and quick setup

Browse Source
This commit is contained in:
sususu
2025-11-03 17:26:58 +08:00
parent a2abc11082
commit b6b5f01f1b
2 changed files with 219 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
CLAUDE.md
View File

@@ -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 端点并选择可用的
- **自动 API 连接测试**: 使用 `/v1/models` 端点验证连接
- 创建 Claude Code 配置文件 (~/.claude/settings.json) - 创建 Claude Code 配置文件 (~/.claude/settings.json)
- 设置环境变量 (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN) - 设置环境变量 (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN)
- 支持团队和个人 API 端点 - 支持环境变量传递 API 密钥 (bash 脚本)
### 配置结构 ### 配置结构
脚本生成的 settings.json 包含: 脚本生成的 settings.json 包含:
```json ```json
{ {
"env": { "env": {
"ANTHROPIC_BASE_URL": "<用户提供的URL>", "ANTHROPIC_BASE_URL": "<自动选择的URL>",
"ANTHROPIC_AUTH_TOKEN": "<用户API密钥>", "ANTHROPIC_AUTH_TOKEN": "<用户API密钥>",
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": 20000, "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 20000,
"DISABLE_TELEMETRY": 1, "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) ### Windows (PowerShell)
```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 .\setup-claude-code.ps1 -Show
@@ -59,11 +79,15 @@ XCodeCLI-Shells 是一个配置工具集，用于设置 Claude Code 与 XCodeCLI
### Unix/Linux/macOS (Bash) ### Unix/Linux/macOS (Bash)
```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 ./setup-claude-code.sh --show
@@ -75,16 +99,24 @@ XCodeCLI-Shells 是一个配置工具集，用于设置 Claude Code 与 XCodeCLI
./setup-claude-code.sh --help ./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) - 彩色输出功能 (Blue/Green/Yellow/Red)
- 环境变量持久化 (用户级别) - 环境变量持久化 (用户级别)
- JSON 配置验证 - JSON 配置验证
- **智能端点测试**: 自动测试多个 API 端点
- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头
- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性
### Bash 脚本特性 ### Bash 脚本特性
- 依赖 jq 进行 JSON 处理 - 依赖 jq 进行 JSON 处理
- ANSI 颜色输出 - ANSI 颜色输出
- 临时文件清理 - 临时文件清理
- 错误处理和回滚机制 - 错误处理和回滚机制
- **环境变量支持**: 支持 `API_KEY` 环境变量
- **智能端点测试**: 自动测试多个 API 端点
- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头
- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性
### 安全考虑 ### 安全考虑
- API 密钥格式验证 (仅允许字母数字、连字符、下划线) - API 密钥格式验证 (仅允许字母数字、连字符、下划线)
- 配置文件自动备份 (时间戳) - 配置文件自动备份 (时间戳)
- 敏感信息掩码显示 - 敏感信息掩码显示
- HTTP 状态码验证 - HTTP 状态码验证
- **端点安全**: 仅测试预定义的可信端点
- **连接超时**: 自动处理网络超时情况
### 配置文件位置 ### 配置文件位置
- Windows: `%USERPROFILE%\.claude\settings.json` - Windows: `%USERPROFILE%\.claude\settings.json`
- Unix/Linux/macOS: `~/.claude/settings.json` - 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 密钥，其他配置都由脚本智能处理。

195
README.md
View File

@@ -1,40 +1,57 @@
# XCodeCLI-Shells # 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) [![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) [![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) - 🌐 **跨平台支持**: 支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash)
- 🔐 **Security validation**: API key format validation and connection testing - 🔐 **安全验证**: API 密钥格式验证和连接测试
- ⚡ **Quick setup**: Auto-generates Claude Code configuration files and environment variables - ⚡ **快速配置**: 自动生成 Claude Code 配置文件和环境变量
- 🛡️ **Data protection**: Automatic backup of existing configs, sensitive info masking - 🛡️ **数据保护**: 自动备份现有配置，敏感信息掩码显示
- 🎯 **Multi-endpoint support**: Supports both personal and team API endpoints - 🎯 **智能端点选择**: 自动测试多个 API 端点，选择最佳可用服务
- 📊 **Real-time feedback**: Colored output and detailed status information - 📊 **实时反馈**: 彩色输出和详细的状态信息
- 🚀 **一键安装**: 支持从远程直接下载执行，无需本地文件
## 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 #### Windows
- PowerShell 5.0 or higher - PowerShell 5.0 或更高版本
- Internet connection - 网络连接
#### Unix/Linux/macOS #### Unix/Linux/macOS
- Bash shell - Bash shell
- `jq` command-line tool - `jq` 命令行工具
- `curl` tool - `curl` 工具
### Install jq (Unix/Linux/macOS only) ### 安装 jq (仅 Unix/Linux/macOS)
```bash ```bash
# macOS (using Homebrew) # macOS (使用 Homebrew)
brew install jq brew install jq
# Ubuntu/Debian # Ubuntu/Debian
@@ -42,109 +59,105 @@ sudo apt-get install jq
# CentOS/RHEL/Fedora # CentOS/RHEL/Fedora
sudo yum install jq sudo yum install jq
# or (newer versions) # 或者 (较新版本)
sudo dnf install jq sudo dnf install jq
``` ```
## Usage ## 使用方法
### Windows (PowerShell) ### Windows (PowerShell)
#### Basic usage #### 基本使用
```powershell ```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 ```powershell
.\setup-claude-code.ps1 .\setup-claude-code.ps1
``` ```
#### Test connection #### 测试连接
```powershell ```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 ```powershell
.\setup-claude-code.ps1 -Show .\setup-claude-code.ps1 -Show
``` ```
#### Help #### 帮助信息
```powershell ```powershell
.\setup-claude-code.ps1 -Help .\setup-claude-code.ps1 -Help
``` ```
> **智能端点选择**: 脚本会自动测试多个 API 端点并选择可用的那个，无需手动指定 URL。
### Unix/Linux/macOS (Bash) ### Unix/Linux/macOS (Bash)
#### Basic usage #### 基本使用
```bash ```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 ```bash
./setup-claude-code.sh ./setup-claude-code.sh
``` ```
#### Test connection #### 测试连接
```bash ```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 ```bash
./setup-claude-code.sh --show ./setup-claude-code.sh --show
``` ```
#### Help #### 帮助信息
```bash ```bash
./setup-claude-code.sh --help ./setup-claude-code.sh --help
``` ```
## Parameters > **智能端点选择**: 脚本会自动测试多个 API 端点并选择可用的那个，无需手动指定 URL。
### PowerShell Script Parameters ## 参数说明
| Parameter | Type | Description | ### PowerShell 脚本参数
|-----------|------|-------------|
| `-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 |
### Bash Script Parameters | 参数 | 类型 | 描述 |
|------|------|------|
| `-ApiKey` | String | API 密钥 |
| `-Test` | Switch | 仅测试 API 连接（会自动测试所有可用端点） |
| `-Show` | Switch | 显示当前设置 |
| `-Help` | Switch | 显示帮助信息 |
| Parameter | Type | Description | > **自动端点发现**: 脚本会自动测试以下端点并选择第一个可用的：
|-----------|------|-------------| > - `https://api.xcodecli.com`
| `-u, --url` | String | XCodeCLI API base URL | > - `https://newapi.sususu.cf`
| `-k, --key` | String | API key |
| `-t, --test` | Flag | Test API connection only |
| `-s, --show` | Flag | Show current settings |
| `-h, --help` | Flag | Show help information |
## API Endpoint Support ### Bash 脚本参数
### Personal API | 参数 | 类型 | 描述 |
- **Endpoint**: `/api/v1/claude/balance` |------|------|------|
- **Response field**: `balance` | `-k, --key` | String | API 密钥 |
- **Usage**: Query personal account balance | `-t, --test` | Flag | 仅测试 API 连接（会自动测试所有可用端点） |
| `-s, --show` | Flag | 显示当前设置 |
| `-h, --help` | Flag | 显示帮助信息 |
### Team API > **环境变量支持**: 脚本也支持通过 `API_KEY` 环境变量传递 API 密钥。
- **Endpoint**: `/api/v1/team/stats/spending`
- **Response field**: `daily_remaining`
- **Usage**: Query team daily remaining quota
- **URL format**: Must end with `/team`
## Configuration Files
Scripts create configuration files at: ## 配置文件
脚本会在以下位置创建配置文件：
- **Windows**: `%USERPROFILE%\.claude\settings.json` - **Windows**: `%USERPROFILE%\.claude\settings.json`
- **Unix/Linux/macOS**: `~/.claude/settings.json` - **Unix/Linux/macOS**: `~/.claude/settings.json`
### Configuration Structure ### 配置文件结构
```json ```json
{ {
@@ -162,63 +175,63 @@ Scripts create configuration files at:
} }
``` ```
## Security Features ## 安全特性
- **API key validation**: Only accepts keys with alphanumeric characters, hyphens, and underscores - **API 密钥验证**: 只接受包含字母数字、连字符和下划线的密钥格式
- **Configuration backup**: Auto-backup existing config files (with timestamp) - **配置备份**: 自动备份现有配置文件（带时间戳）
- **Sensitive info protection**: Automatic masking of API keys in output - **敏感信息保护**: 在输出中自动掩码显示 API 密钥
- **Connection verification**: Test API connection validity before configuration - **连接验证**: 配置前测试 API 连接有效性
## Troubleshooting ## 故障排除
### Windows PowerShell Execution Policy Error ### Windows PowerShell 执行策略错误
If you encounter execution policy errors, use: 如果遇到执行策略错误，请使用以下命令：
```powershell ```powershell
powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1 powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1
``` ```
### Unix/Linux/macOS Permission Issues ### Unix/Linux/macOS 权限问题
Ensure the script has execute permissions: 确保脚本具有执行权限：
```bash ```bash
chmod +x setup-claude-code.sh 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 1. 检查网络连接
2. Verify API URL is correct 2. 验证 API URL 是否正确
3. Confirm API key validity 3. 确认 API 密钥有效性
4. Check firewall settings 4. 检查防火墙设置
## Verify Installation ## 验证安装
After installation, you can verify Claude Code configuration with: 安装完成后，您可以使用以下命令验证 Claude Code 配置：
```bash ```bash
claude --version 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) - [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code)
- [XCodeCLI Project](https://github.com/your-username/XCodeCLI) - [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. **注意**: 请确保您的 API 密钥安全，不要在公共代码库中提交包含真实 API 密钥的配置文件。