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

2025-11-03 17:26:58 +08:00
parent a2abc11082
commit b6b5f01f1b
2 changed files with 219 additions and 112 deletions
--- 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.
+**注意**: 请确保您的 API 密钥安全，不要在公共代码库中提交包含真实 API 密钥的配置文件。