# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

XCodeCLI-Shells 是一个智能配置工具集，用于设置 Claude Code 与 XCodeCLI API 路由器的集成。项目包含跨平台的安装脚本，支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash)，具备自动端点发现和选择功能。

## 核心架构

### 脚本功能
- **setup-claude-code.ps1**: Windows PowerShell 配置脚本
- **setup-claude-code.sh**: Unix/Linux/macOS Bash 配置脚本

两个脚本提供相同的功能:
- 验证 API 密钥格式
- **智能端点发现**: 自动测试多个 API 端点并选择可用的
- **自动 API 连接测试**: 使用 `/v1/models` 端点验证连接
- 创建 Claude Code 配置文件 (~/.claude/settings.json)
- 设置环境变量 (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN)
- 支持环境变量传递 API 密钥 (bash 脚本)

### 配置结构
脚本生成的 settings.json 包含:
```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "<自动选择的URL>",
    "ANTHROPIC_AUTH_TOKEN": "<用户API密钥>",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 20000,
    "DISABLE_TELEMETRY": 1,
    "DISABLE_ERROR_REPORTING": 1,
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": 1,
    "MAX_THINKING_TOKENS": 12000
  },
  "model": "sonnet"
}
```

### 支持的 API 端点
脚本会按顺序测试以下端点，选择第一个可用的：
1. `https://api.xcodecli.com`
2. `https://api2.xcodecli.com`

## 常用命令

### 🚀 一行命令快速配置

#### 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 -ApiKey your-api-key

# 测试连接（测试所有端点）
.\setup-claude-code.ps1 -Test -ApiKey your-api-key

# 显示当前设置
.\setup-claude-code.ps1 -Show

# 交互模式
.\setup-claude-code.ps1

# 帮助
.\setup-claude-code.ps1 -Help
```

### Unix/Linux/macOS (Bash)
```bash
# 基本使用（自动选择可用端点）
./setup-claude-code.sh --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

# 帮助
./setup-claude-code.sh --help
```

## 智能特性

### 自动端点发现
脚本使用智能算法自动发现和选择最佳可用的 API 端点：

1. **端点测试**: 依次测试所有配置的端点
2. **连通性验证**: 使用 `/v1/models` 端点检查服务可用性
3. **模型验证**: 确保端点返回有效的模型列表
4. **自动选择**: 选择第一个通过所有测试的端点
5. **智能降级**: 如果所有端点都失败，提供手动选择选项

### 错误处理和恢复
- **连接失败**: 自动尝试下一个端点
- **认证失败**: 提供清晰的错误信息和解决建议
- **服务不可用**: 智能降级到默认配置
- **用户选择**: 在失败时允许用户决定是否继续



## 开发注意事项

### PowerShell 脚本特性
- 支持执行策略绕过: `powershell -ExecutionPolicy Bypass`
- 彩色输出功能 (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`

## 故障排除

### 端点连接问题
如果所有端点都无法连接：
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 密钥，其他配置都由脚本智能处理。