更新首页与指南文档

2025-12-26 15:54:28 +08:00
parent d8440a1ccf
commit aea92bc1ec
6 changed files with 261 additions and 121 deletions
--- a/docs/cherry-studio-nanobana.md
+++ b/docs/cherry-studio-nanobana.md
@@ -72,13 +72,11 @@ Cherry Studio 是一款支持多服务商集成的 AI 对话客户端，目前
 > 💡 **提示：**
 >
 > - `aspectRatio` 可选值：`16:9`、`4:3`、`1:1` 等
-> - `imageSize` 可选值：`4K`、`2K`、`1K` 等（K必须是大写）
+> - `imageSize` 可选值：`4K`、`2K`、`1K` 等（K 必须是大写）
 > - 详情请参考：[Google Gemini API 文档](https://ai.google.dev/gemini-api/docs/image-generation?hl=zh-cn#aspect_ratios_and_image_size)

 ![助手参数配置](assets/9a1a0771d520055942e263d4b1011328.png)

-
-
 ---

 ## 六、提醒
@@ -99,4 +97,4 @@ Cherry Studio 是一款支持多服务商集成的 AI 对话客户端，目前
 2. 添加提供商：名称填 `XCodeCLI`，类型选 `Gemini`
 3. 填写 API Key 和地址 `https://api2.xcodecli.com`
 4. 生成高清图时：关闭流式输出 + 配置自定义参数
-5. 优先使用 Gemini 系列模型，避开天价的 Claude 和 GPT 系列
+5. 优先使用 Gemini 系列模型，暂不支持 Claude、GPT 系列模型
--- a/docs/guide/claude-code.md
+++ b/docs/guide/claude-code.md
@@ -0,0 +1,44 @@
+# Claude Code 配置指南
+
+Claude Code 是 Anthropic 推出的 AI 编码助手。通过 XCodeCLI，你可以将其连接到自定义 API 端点。
+
+## 快速安装与配置
+
+使用下面的单一行命令即可自动完成安装和配置。
+
+::: code-group
+
+```bash [macOS / Linux]
+API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/ClaudeCode/setup-claude-code.sh)"
+```
+
+```powershell [Windows]
+$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/ClaudeCode/setup-claude-code.ps1 | iex
+```
+
+:::
+
+> 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+
+## 手动配置说明
+
+如果你想手动配置，Claude Code 的配置文件位于：
+
+- **macOS / Linux**: `~/.claude/settings.json`
+- **Windows**: `~/.claude/settings.json` (位于用户主目录下)
+
+配置内容示例：
+
+```json
+{
+  "apiBaseUrl": "https://api2.xcodecli.com",
+  "apiKey": "sk-your-key-here"
+}
+```
+
+## 常见问题
+
+- **Q: 安装后无法使用？**
+  - A: 确保你已安装 Node.js (推荐 v18+)。
+- **Q: 权限错误？**
+  - A: 在 macOS/Linux 上可能需要 `sudo` 权限来安装全局 npm 包，但我们的脚本尝试使用非 root 方式或引导安装 fnm。
--- a/docs/guide/codex.md
+++ b/docs/guide/codex.md
@@ -0,0 +1,41 @@
+# Codex 配置指南
+
+Codex 是一个强大的代码生成和补全工具。
+
+## 快速安装与配置
+
+使用下面的单一行命令即可自动完成安装和配置。
+
+::: code-group
+
+```bash [macOS / Linux]
+API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/codex/setup-codex.sh)"
+```
+
+```powershell [Windows]
+$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/codex/setup-codex.ps1 | iex
+```
+
+:::
+
+> 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+
+## 手动配置说明
+
+Codex 的配置文件通常位于 `~/.codex/config.toml`。
+
+配置示例 (TOML)：
+
+```toml
+[server]
+url = "https://api2.xcodecli.com"
+token = "sk-your-key-here"
+
+[editor]
+completion = true
+```
+
+## 注意事项
+
+- Codex 需要支持 TOML 格式的配置文件。
+- 确保你的编辑器插件已正确指向本地的 Codex 配置。
--- a/docs/guide/gemini-cli.md
+++ b/docs/guide/gemini-cli.md
@@ -0,0 +1,37 @@
+# Gemini CLI 配置指南
+
+Gemini CLI 是 Google 的 AI 命令行工具。通过 XCodeCLI，你可以无缝切换到自定义 API 源。
+
+## 快速安装与配置
+
+使用下面的单一行命令即可自动完成安装和配置。
+
+::: code-group
+
+```bash [macOS / Linux]
+API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/GeminiCLI/setup-gemini.sh)"
+```
+
+```powershell [Windows]
+$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/GeminiCLI/setup-gemini.ps1 | iex
+```
+
+:::
+
+> 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+
+## 手动配置说明
+
+Gemini CLI 通常使用环境变量或 `.env` 文件进行配置。XCodeCLI 脚本配置的位置通常为 `~/.gemini/.env`。
+
+关键环境变量：
+
+```env
+GEMINI_API_KEY=sk-your-key-here
+GEMINI_API_BASE=https://api2.xcodecli.com
+```
+
+## 使用技巧
+
+- 使用 `gemini` 开始对话。
+- 确保你的网络环境可以连接到配置的 API 端点。
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,14 +1,22 @@
 # 快速开始

+欢迎使用 **XCodeCLI** 配置工具。本指南将帮助你快速配置常用的 AI CLI 工具，使其连接到 XCodeCLI 的 API 端点。
+
 ## 前置要求

- 有效的 XCodeCLI API 密钥
- macOS / Linux: `curl` 和 `bash`
- Windows: PowerShell 5.1+
+在开始之前，请确保你拥有：

-## 一键安装配置（推荐）
+- **有效的 XCodeCLI API 密钥** (通常以 `sk-` 开头)
+- **网络连接**：能够访问我们的 API 端点 (`https://api2.xcodecli.com` 或 `https://api.xcodecli.com`)

-运行一条命令，自动安装并配置全部三个工具：
+对于操作系统环境：
+
+- **macOS / Linux**: 需要 `curl` 和 `bash` 环境。
+- **Windows**: 需要 PowerShell 5.1 或更高版本。
+
+## 全自动一键配置（推荐）
+
+这是最简单的方法。运行一条命令，脚本会自动检测、安装并配置 **Claude Code**、**Gemini CLI** 和 **Codex**。

 ::: code-group

@@ -22,59 +30,29 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra

 :::

-脚本会自动：
+> 💡 **提示**：请将命令中的 `你的密钥` 替换为你的实际 API 密钥。

-1. 检测 Node.js / Bun 包管理器，缺失时引导安装 Bun
-2. 显示三个工具的安装状态
-3. 依次安装并配置 Claude Code、Gemini CLI、Codex
-4. 显示最终配置结果
+### 脚本执行流程

-<div class="tip custom-block" style="padding-top: 8px">
-将命令中的 <code>你的密钥</code> 替换为你的 API 密钥
-</div>
+1. **环境检测**：检查 Node.js 等必要运行时。如果缺失，脚本会尝试引导安装（如 fnm）。
+2. **工具状态检查**：显示当前已安装的工具及其版本。
+3. **自动化配置**：依次为检测到的或默认的工具写入配置文件（备份原有配置）。
+4. **验证连接**：简单的 API 连接测试（部分脚本支持）。
+5. **结果汇总**：显示所有配置文件的路径和最终状态。

-## 单独配置某个工具
+## 单独配置

-如果只需要配置其中一个工具，可以使用单独的脚本：
+如果你只需要配置特定的工具，或者想了解每个工具的详细配置参数，请参考以下指南：

-### Claude Code
+- [Claude Code 配置指南](/guide/claude-code)
+- [Gemini CLI 配置指南](/guide/gemini-cli)
+- [Codex 配置指南](/guide/codex)

-::: code-group
+## API 端点说明

-```bash [macOS / Linux]
-API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/ClaudeCode/setup-claude-code.sh)"
-```
+我们的配置脚本会自动测试并选择最快的可用端点：

-```powershell [Windows]
-$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/ClaudeCode/setup-claude-code.ps1 | iex
-```
+1. `https://api2.xcodecli.com` (主要，优先尝试)
+2. `https://api.xcodecli.com` (备用)

-:::
-
-### Gemini CLI
-
-::: code-group
-
-```bash [macOS / Linux]
-API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/GeminiCLI/setup-gemini.sh)"
-```
-
-```powershell [Windows]
-$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/GeminiCLI/setup-gemini.ps1 | iex
-```
-
-:::
-
-### Codex
-
-::: code-group
-
-```bash [macOS / Linux]
-API_KEY='你的密钥' bash -c "$(curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/codex/setup-codex.sh)"
-```
-
-```powershell [Windows]
-$key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/codex/setup-codex.ps1 | iex
-```
-
-:::
+所有的工具都会统一配置使用同一个有效的 API 端点。
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,23 +3,26 @@ layout: home

 hero:
  name: XCodeCLI
-  text: AI CLI 配置工具
-  tagline: 一键配置 Claude Code / Gemini CLI / Codex 连接到 XCodeCLI API
+  text: 全能 AI 开发配置中心
+  tagline: 统一管理 Claude Code / Gemini CLI / Codex 及 Cherry Studio 配置
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/
+    - theme: alt
+      text: Cherry Studio 教程
+      link: /cherry-studio-nanobana

 features:
  - icon: 🚀
-    title: 一键配置
-    details: 运行一条命令，自动检测 API 端点并写入配置文件
-  - icon: 🔧
-    title: 跨平台支持
-    details: 支持 macOS、Linux、Windows，提供 Bash 和 PowerShell 脚本
+    title: CLI 一键配置
+    details: 一行命令自动配置 Claude Code、Gemini CLI 和 Codex
+  - icon: 🍒
+    title: Cherry Studio 支持
+    details: 完美适配 Cherry Studio，支持 Gemini 系列模型可视化交互
  - icon: 🔒
-    title: 安全备份
-    details: 自动备份现有配置，支持回滚
+    title: 安全可靠
+    details: 自动备份现有配置，本地化管理 API 密钥
 ---

 <script setup>
@@ -40,62 +43,118 @@ function copyCommand() {
 }
 </script>

-<div class="quick-install">
-  <h2>⚡ 一键安装配置</h2>
-  <p class="desc">运行一条命令，自动安装并配置 Claude Code、Gemini CLI、Codex</p>
+<div class="setup-section">
+
+## 1. CLI 工具一键配置
+
+<p class="desc">适用于 <strong>Claude Code</strong>、<strong>Gemini CLI</strong> 和 <strong>Codex</strong> 的自动化配置。</p>

 <div class="install-card">
-<div class="tabs">
-<button :class="{ active: activeTab === 'bash' }" @click="activeTab = 'bash'">
-<span class="icon">🍎/🐧</span> macOS / Linux
-</button>
-<button :class="{ active: activeTab === 'powershell' }" @click="activeTab = 'powershell'">
-<span class="icon">🪟</span> Windows
-</button>
+  <div class="tabs">
+    <button :class="{ active: activeTab === 'bash' }" @click="activeTab = 'bash'">
+      <span class="icon">🍎/🐧</span> macOS / Linux
+    </button>
+    <button :class="{ active: activeTab === 'powershell' }" @click="activeTab = 'powershell'">
+      <span class="icon">🪟</span> Windows
+    </button>
+  </div>
+
+  <div class="code-block-wrapper">
+    <div class="code-block">
+      <code>{{ commands[activeTab] }}</code>
+    </div>
+    <button class="copy-btn" @click="copyCommand" :class="{ copied: copied }">
+      {{ copied ? '已复制' : '复制命令' }}
+    </button>
+  </div>
 </div>

-<div class="code-block-wrapper">
-<div class="code-block">
-<code>{{ commands[activeTab] }}</code>
-</div>
-<button class="copy-btn" @click="copyCommand" :class="{ copied: copied }">
-{{ copied ? '已复制' : '复制命令' }}
-</button>
-</div>
+<p class="tip">💡 提示：运行前请将命令中的 <code>你的密钥</code> 替换为实际 API Key</p>
+
 </div>

-  <p class="tip">💡 提示：将命令中的 <code>你的密钥</code> 替换为你的实际 API 密钥</p>
+<div class="setup-section">
+
+## 2. Cherry Studio 配置
+
+<p class="desc">在 Cherry Studio 中使用 XCodeCLI 服务，享受可视化的对话体验。</p>
+
+::: danger ⚠️ 重要提示：模型兼容性
+**Cherry Studio 仅支持 Gemini 系列模型！**
+
+- ❌ **Claude 模型**：暂不支持在 Cherry Studio 中使用（请在 Claude Code 内使用）
+- ❌ **GPT 模型**：暂不支持在 Cherry Studio 中使用（请在 Codex 内使用）
+- ✅ **Gemini 模型**：完美支持
+  :::
+
+### 配置参数
+
+请在 Cherry Studio 设置中添加 **自定义提供商**：
+
+| 配置项         | 值                          | 说明                     |
+| :------------- | :-------------------------- | :----------------------- |
+| **提供商类型** | `Gemini`                    | **必选** (不要选 OpenAI) |
+| **API 密钥**   | `sk-...`                    | 你的 XCodeCLI 密钥       |
+| **API 地址**   | `https://api2.xcodecli.com` | Base URL                 |
+
+::: tip 📝 详细教程
+查看完整的 [Cherry Studio 图文配置指南](/cherry-studio-nanobana)
+:::
+
+</div>
+
+<div class="setup-section">
+
+## 3. 参考信息
+
+### CLI 配置文件位置
+
+| 工具            | 配置文件                  | 格式 |
+| :-------------- | :------------------------ | :--- |
+| **Claude Code** | `~/.claude/settings.json` | JSON |
+| **Gemini CLI**  | `~/.gemini/.env`          | ENV  |
+| **Codex**       | `~/.codex/config.toml`    | TOML |
+
+### API 端点
+
+脚本会自动测试以下端点，选择第一个可用的：
+
+- `https://api2.xcodecli.com` (主要)
+- `https://api.xcodecli.com` (备用)
+
 </div>

 <style>
-.quick-install {
-  margin: 0 auto 4rem;
-  padding: 0 1rem;
-  text-align: center;
-}
-.quick-install h2 {
-  margin-top: 0;
-  margin-bottom: 0.5rem;
-  border-top: none;
-  font-size: 2rem;
-  font-weight: 700;
-  letter-spacing: -0.5px;
-}
-.quick-install .desc {
-  margin: 0 auto 2rem;
-  color: var(--vp-c-text-2);
-  font-size: 1.1rem;
-  max-width: 600px;
+.setup-section {
+  margin: 3rem auto;
+  max-width: 960px;
+  padding: 0 1.5rem;
 }

+.setup-section h2 {
+  border-top: none;
+  font-size: 1.8rem;
+  font-weight: 700;
+  margin-bottom: 1rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.desc {
+  color: var(--vp-c-text-2);
+  font-size: 1.1rem;
+  margin-bottom: 1.5rem;
+}
+
+/* Install Card Styles */
 .install-card {
-  max-width: 780px;
-  margin: 0 auto;
  background: var(--vp-c-bg-soft);
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
  overflow: hidden;
  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.05);
+  margin-bottom: 1rem;
 }

 .tabs {
@@ -145,7 +204,6 @@ function copyCommand() {
  overflow-x: auto;
  white-space: pre;
  padding-right: 0.5rem;
-  /* Hide scrollbar for cleaner look */
  scrollbar-width: thin;
 }
 .code-block::-webkit-scrollbar {
@@ -179,7 +237,6 @@ function copyCommand() {
 }

 .tip {
-  margin-top: 1.5rem;
  font-size: 0.9rem;
  color: var(--vp-c-text-2);
 }
@@ -190,18 +247,3 @@ function copyCommand() {
  border-radius: 4px;
 }
 </style>
-
-## 支持的工具
-
-| 工具        | 配置位置                  | 配置格式 |
-| ----------- | ------------------------- | -------- |
-| Claude Code | `~/.claude/settings.json` | JSON     |
-| Gemini CLI  | `~/.gemini/.env`          | ENV      |
-| Codex       | `~/.codex/config.toml`    | TOML     |
-
-## API 端点
-
-脚本会自动测试以下端点，选择第一个可用的：
-
- `https://api2.xcodecli.com` (主要)
- `https://api.xcodecli.com` (备用)