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

feat: 增强三个 CLI 工具配置脚本

Browse Source 
- Gemini CLI: 添加 GEMINI_MODEL 环境变量、settings.json 输出及备份逻辑
- Codex: 修复模型名称一致性 (gpt-5-codex)、添加 auth.json 备份逻辑
- Claude Code: 添加 VSCode 插件 config.json 配置支持
- CLAUDE.md: 重构文档，添加三个工具配置差异表

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
sususu98
2025-12-11 18:15:54 +08:00
parent badf8e6bb6
commit 2314140bce
9 changed files with 292 additions and 497 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
CLAUDE.md
View File

@@ -4,202 +4,94 @@ 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**、**Gemini CLI** 和 **Codex** 三个 AI CLI 工具连接到 XCodeCLI API 路由器。每个工具都有 PowerShell (.ps1) 和 Bash (.sh) 两个版本。
## 核心架构
## 项目结构
### 脚本功能
- **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"
}
```
xcodecli-shells/
├── setup.ps1 # Windows 统一启动器 (安装+配置三个工具)
├── setup-claude-code.ps1/.sh # Claude Code 配置脚本 (根目录副本)
├── ClaudeCode/
│ └── setup-claude-code.ps1/.sh
├── GeminiCLI/
│ └── setup-gemini.ps1/.sh
└── codex/
└── setup-codex.ps1/.sh
```
### 支持的 API 端点
脚本会按顺序测试以下端点，选择第一个可用的：
## 三个工具的配置差异
| 工具 | 配置位置 | 配置格式 | API 认证头 |
| ----------- | ------------------------------------ | ----------- | ----------------------- |
| Claude Code | `~/.claude/settings.json` | JSON | `Authorization: Bearer` |
| Gemini CLI | `~/.gemini/.env` | ENV 文件 | `x-goog-api-key` |
| Codex | `~/.codex/config.toml` + `auth.json` | TOML + JSON | `Authorization: Bearer` |
## 统一启动器 (setup.ps1)
Windows 专用的一站式安装配置工具：
- 检测 Node.js/Bun 包管理器，缺失时引导安装 Bun
- 显示三个工具的安装状态
- 自动安装缺失的工具 (`npm install -g` 或 `bun add -g`)
- 下载并执行对应工具的配置脚本
```powershell
# 使用方式
$key='YOUR_API_KEY'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup.ps1 | iex
```
## 通用脚本模式
所有配置脚本共享相同的设计模式：
### 参数接口
- PowerShell: `-ApiKey`, `-Test`, `-Show`, `-Help`
- Bash: `--key`, `--test`, `--show`, `--help`
- 支持 `$key` 变量 (PowerShell) 或 `$API_KEY` 环境变量 (Bash)
### 智能端点发现
按顺序测试端点，选择第一个可用的：
1. `https://api2.xcodecli.com`
2. `https://api.xcodecli.com`
## 常用命令
### 核心流程
### 🚀 一行命令快速配置
1. API 密钥格式验证 (字母数字、连字符、下划线)
2. 调用 `/v1/models` 测试连接
3. 备份现有配置 (时间戳命名)
4. 写入新配置文件
#### 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
# 本地测试脚本
./setup-claude-code.sh --key test-key --test
./GeminiCLI/setup-gemini.sh --key test-key --test
./codex/setup-codex.sh --key test-key --test
# PowerShell 执行 (绕过执行策略)
powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1 -ApiKey test-key -Test
```
### 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` 端点验证服务可用性
- PowerShell 和 Bash 版本必须功能对等
- 新增端点需同时更新所有 6 个配置脚本
- 输出格式保持一致: `[INFO]`, `[SUCCESS]`, `[WARNING]`, `[ERROR]`
### 安全考虑
- API 密钥格式验证 (仅允许字母数字、连字符、下划线)
- 配置文件自动备份 (时间戳)
- 敏感信息掩码显示
- HTTP 状态码验证
- **端点安全**: 仅测试预定义的可信端点
- **连接超时**: 自动处理网络超时情况
### Bash 脚本依赖
### 配置文件位置
- Windows: `%USERPROFILE%\.claude\settings.json`
- Unix/Linux/macOS: `~/.claude/settings.json`
- Claude Code 脚本依赖 `jq` 处理 JSON
- Gemini/Codex 脚本使用 `grep` 解析响应，无需 jq
## 故障排除
### API 响应格式差异
### 端点连接问题
如果所有端点都无法连接：
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 密钥，其他配置都由脚本智能处理。
- Claude/Codex: 检查 `response.data` 或 `response.models` 数组
- Gemini: 检查 `response.models` 数组 (Google API 格式)