sususu98
f1ab858212
Some checks failed
Deploy to Cloudflare Pages / deploy (push) Failing after 11s
根因: irm/iwr 文本解码时将 UTF-8 中文替换为 ?， 字符串在进入 iex 之前就已损坏。 改用 iwr -OutFile 写入原始字节到临时文件再执行， 绕过文本解码链路，彻底修复编码问题。
150 lines
6.1 KiB
Markdown
150 lines
6.1 KiB
Markdown
# 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.sh # Unix 统一启动器
|
||
├── setup-claude-code.ps1/.sh # Claude Code 配置脚本 (根目录副本)
|
||
├── ClaudeCode/
|
||
│ └── setup-claude-code.ps1/.sh
|
||
├── GeminiCLI/
|
||
│ └── setup-gemini.ps1/.sh
|
||
├── codex/
|
||
│ └── setup-codex.ps1/.sh
|
||
└── docs/ # VitePress 文档站点
|
||
├── .vitepress/config.ts # VitePress 配置 (导航、侧边栏、主题)
|
||
├── index.md # 首页 (VitePress home layout, 含 Vue 交互组件)
|
||
├── cherry-studio-nanobana.md # Cherry Studio 图文配置教程
|
||
├── assets/ # 文档图片资源 (截图)
|
||
├── guide/
|
||
│ ├── index.md # 快速开始总览页
|
||
│ ├── claude-code.md # Claude Code 单独配置指南
|
||
│ ├── gemini-cli.md # Gemini CLI 单独配置指南
|
||
│ └── codex.md # Codex 单独配置指南
|
||
└── package.json # 文档依赖 (vitepress ^1.5.0)
|
||
```
|
||
|
||
## 三个工具的配置差异
|
||
|
||
| 工具 | 配置位置 | 配置格式 | 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` |
|
||
|
||
## 工具安装方式差异
|
||
|
||
| 工具 | 安装方式 | 依赖 |
|
||
| ---- | ---- | ---- |
|
||
| Claude Code | 官方原生脚本 `curl -fsSL https://claude.ai/install.sh \| bash` | 无需 Node.js，自动更新 |
|
||
| Gemini CLI | `npm install -g @google/gemini-cli@latest` | **需要 Node.js >= 20** |
|
||
| Codex | `npm install -g @openai/codex` | **需要 Node.js >= 20** |
|
||
|
||
## 统一启动器 (setup.ps1 / setup.sh)
|
||
|
||
跨平台一站式安装配置工具：
|
||
|
||
- 检测 Node.js 环境，缺失时使用 fnm 安装 (Gemini CLI / Codex 需要)
|
||
- 显示三个工具的安装状态
|
||
- Claude Code 使用官方原生安装脚本 (`curl -fsSL https://claude.ai/install.sh | bash`)
|
||
- Gemini CLI / Codex 使用 `npm install -g` 安装 (需要 Node.js >= 20)
|
||
- 下载并执行对应工具的配置脚本
|
||
|
||
```powershell
|
||
# 使用方式
|
||
$key='YOUR_API_KEY'; $f="$env:TEMP\xc.ps1";iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup.ps1 -OutFile $f;& $f
|
||
```
|
||
|
||
## 通用脚本模式
|
||
|
||
所有配置脚本共享相同的设计模式：
|
||
|
||
### 参数接口
|
||
|
||
- 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. 写入新配置文件
|
||
|
||
## 常用开发命令
|
||
|
||
```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
|
||
```
|
||
|
||
## 开发注意事项
|
||
|
||
### 脚本一致性
|
||
|
||
- 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 格式)
|
||
|
||
## 文档站点 (docs/)
|
||
|
||
基于 **VitePress** 的静态文档站点，语言为 `zh-CN`。
|
||
|
||
### 开发命令
|
||
|
||
```bash
|
||
# 在 docs/ 目录下执行
|
||
bun run dev # 本地开发服务器
|
||
bun run build # 构建静态站点
|
||
bun run preview # 预览构建结果
|
||
```
|
||
|
||
### 站点结构
|
||
|
||
| 页面 | 文件 | 说明 |
|
||
| ------------- | -------------------------------- | ----------------------------------------------------------------------------- |
|
||
| 首页 | `docs/index.md` | VitePress home layout，含 Vue `<script setup>` 交互组件 (Tab 切换 + 一键复制) |
|
||
| 快速开始 | `docs/guide/index.md` | 全自动一键配置说明 + 各工具单独配置入口 |
|
||
| Claude Code | `docs/guide/claude-code.md` | Claude Code 安装配置指南 |
|
||
| Gemini CLI | `docs/guide/gemini-cli.md` | Gemini CLI 安装配置指南 |
|
||
| Codex | `docs/guide/codex.md` | Codex 安装配置指南 |
|
||
| Cherry Studio | `docs/cherry-studio-nanobana.md` | Cherry Studio 图文教程 (仅支持 Gemini 模型) |
|
||
|
||
### 文档开发注意事项
|
||
|
||
- 首页 `index.md` 包含 Vue SFC 代码 (`<script setup>` + `<style>`)，修改时注意保持 VitePress 兼容性
|
||
- 图片资源放在 `docs/assets/`，文件名可含中文
|
||
- 侧边栏和导航配置在 `.vitepress/config.ts` 中维护
|
||
- Cherry Studio 页面强调 **仅支持 Gemini 模型**，Claude/GPT 系列不支持
|