xcodecli-shells/CLAUDE.md

CLAUDE.md

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

项目概述

XCodeCLI-Shells 是一个跨平台配置工具集，用于配置 Claude Code、Gemini CLI 和 Codex 三个 AI CLI 工具连接到 XCodeCLI API 路由器。每个工具都有 PowerShell (.ps1) 和 Bash (.sh) 两个版本。

项目结构

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 认证头
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)
• 下载并执行对应工具的配置脚本

# 使用方式
$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. 写入新配置文件

常用开发命令

# 本地测试脚本
./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

开发注意事项

脚本一致性

• PowerShell 和 Bash 版本必须功能对等
• 新增端点需同时更新所有 6 个配置脚本
• 输出格式保持一致: [INFO], [SUCCESS], [WARNING], [ERROR]

Bash 脚本依赖

• Claude Code 脚本依赖 jq 处理 JSON
• Gemini/Codex 脚本使用 grep 解析响应，无需 jq

API 响应格式差异

• Claude/Codex: 检查 response.data 或 response.models 数组
• Gemini: 检查 response.models 数组 (Google API 格式)