# SuperClaude 安装指南 📦

## 🎯 它比看起来更容易！

**诚实的真相**：本指南看起来很长，因为我们想涵盖所有细节，但安装实际上非常简单。大多数人在 2 分钟内用一个命令就完成了！

### 步骤 1：安装包

**选项 A：来自 PyPI（推荐）**
```bash
uv add SuperClaude
```

**选项 B：来自源码**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync
```

### 🔧 UV / UVX 设置指南

SuperClaude v3 还支持通过 [`uv`](https://github.com/astral-sh/uv)（更快、现代的 Python 包管理器）或 `uvx` 进行跨平台安装。

### 🌀 使用 `uv` 安装

确保安装了 `uv`：

```bash
curl -Ls https://astral.sh/uv/install.sh | sh
```

> 或按照以下说明操作：[https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)

一旦 `uv` 可用，您可以像这样安装 SuperClaude：

```bash
uv venv
source .venv/bin/activate
uv pip install SuperClaude
```

### ⚡ 使用 `uvx` 安装（跨平台 CLI）

如果您使用的是 `uvx`，只需运行：

```bash
uvx pip install SuperClaude
```

## 🔧 UV / UVX 设置指南

SuperClaude v3 还支持通过 [`uv`](https://github.com/astral-sh/uv)（更快、现代的 Python 包管理器）或 `uvx` 进行跨平台安装。

### 🌀 使用 `uv` 安装

确保安装了 `uv`：

```bash
curl -Ls https://astral.sh/uv/install.sh | sh
```

> 或按照以下说明操作：[https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)

一旦 `uv` 可用，您可以像这样安装 SuperClaude：

```bash
uv venv
source .venv/bin/activate
uv pip install SuperClaude
```

### ⚡ 使用 `uvx` 安装（跨平台 CLI）

如果您使用的是 `uvx`，只需运行：

```bash
uvx pip install SuperClaude
```

### ✅ 完成安装

安装后，继续常规安装程序步骤：

```bash
python3 -m SuperClaude install
```

或使用 bash 风格 CLI：

```bash
SuperClaude install
```

### 🧠 注意：

* `uv` 提供更好的缓存和性能。
* 与 Python 3.8+ 兼容，与 SuperClaude 配合顺畅。

---

### ⚠️ 重要说明
**安装 SuperClaude 后。**
**您可以使用 `SuperClaude commands`、`python3 -m SuperClaude commands` 或 `python3 SuperClaude commands`**

**刚刚发生了什么？** SuperClaude 尝试设置您需要的一切。通常没有复杂的配置、依赖搜索或设置头痛！🎉

---

SuperClaude v3 安装的综合指南。但请记住 - 大多数人永远不需要阅读上面快速开始之后的内容！😊

## 开始之前 🔍

### 您需要什么 💻

SuperClaude 适用于 **Windows**、**macOS** 和 **Linux**。这是您需要的：

**必需：**
- **Python 3.8 或更新版本** - 框架用 Python 编写
- **Claude CLI** - SuperClaude 增强 Claude Code，因此您需要先安装它

**可选（但推荐）：**
- **Node.js 16+** - 仅当您想要 MCP 服务器集成时才需要
- **Git** - 对开发工作流程有帮助

### 快速检查 🔍

在安装前，让我们确保您有基础知识：

```bash
# 检查 Python 版本（应该是 3.8+）
python3 --version

# 检查是否安装了 Claude CLI
claude --version

# 检查 Node.js（可选，用于 MCP 服务器）
node --version
```

如果其中任何一个失败，请参阅下面的[先决条件设置](#先决条件设置-🛠️)部分。

## 快速开始 🚀

**🏆 "让它工作" 方法（推荐给 90% 的用户）**
**选项 A：来自 PyPI（推荐）**
```bash
pip install SuperClaude

# 使用推荐设置安装
SuperClaude install --quick

# 就是这样！🎉
```
**选项 B：来自源码**
```bash
# 克隆仓库
git clone <repository-url>
cd SuperClaude
pip install .

# 使用推荐设置安装
SuperClaude install --quick

# 就是这样！🎉
```
**⚠️ 重要说明**
**安装 SuperClaude 后。**
**您可以使用 `SuperClaude commands`、`python3 -m SuperClaude commands` 或 `python3 SuperClaude commands`**

**您刚刚得到的：**
- ✅ 所有 16 个智能命令，自动激活专家
- ✅ 11 个专业角色，知道何时提供帮助
- ✅ 智能路由，为您解决复杂性
- ✅ 约 2 分钟时间和 ~50MB 磁盘空间

**说实话，您完成了。** 打开 Claude Code，输入 `/help`，观看 SuperClaude 发挥其魔力。

**担心它会做什么？** 先用这个看看：
```bash
SuperClaude install --quick --dry-run
```

## 安装选项 🎯

我们有三个安装配置文件可供选择：

### 🎯 最小安装
```bash
SuperClaude install --minimal
```
- **内容**：仅核心框架文件
- **时间**：约 1 分钟
- **空间**：约 20MB
- **适合**：测试、基本增强、最小设置
- **包括**：指导 Claude 的核心行为文档

### 🚀 快速安装（推荐）
```bash
SuperClaude install --quick
```
- **内容**：核心框架 + 16 个斜杠命令
- **时间**：约 2 分钟
- **空间**：约 50MB
- **适合**：大多数用户、一般开发
- **包括**：最小中的所有内容 + `/analyze`、`/build`、`/improve` 等专业命令

### 🔧 开发者安装
```bash
SuperClaude install --profile developer
```
- **内容**：包括 MCP 服务器集成的所有内容
- **时间**：约 5 分钟
- **空间**：约 100MB
- **适合**：高级用户、贡献者、高级工作流程
- **包括**：所有内容 + Context7、Sequential、Magic、Playwright 服务器

### 🎛️ 交互式安装
```bash
SuperClaude install
```
- 允许您选择和选择组件
- 显示每个组件功能的详细描述
- 如果您想控制安装的内容，这是好的

## 分步安装 📋

### 先决条件设置 🛠️

**缺少 Python？**
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip

# macOS
brew install python3

# Windows
# 从 https://python.org/downloads/ 下载
# 或打开命令提示符或 powershell
winget install python
```

**缺少 Claude CLI？**
- 访问 https://claude.ai/code 获取安装说明
- SuperClaude 增强 Claude Code，因此您需要先安装它

**缺少 Node.js？（可选）**
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install nodejs npm

# macOS
brew install node

# Windows
# 从 https://nodejs.org/ 下载
# 或打开命令提示符或 powershell
winget install nodejs
```

### 获取 SuperClaude 📥

**选项 1：来自 PyPI（推荐）**
```bash
pip install SuperClaude
```

**选项 2：下载最新版本**
```bash
# 下载并提取最新版本
#（将 URL 替换为实际版本 URL）
curl -L <release-url> -o superclaude-v3.zip
unzip superclaude-v3.zip
cd superclaude-v3
pip install .
```

**选项 3：从 Git 克隆**
```bash
git clone <repository-url>
cd SuperClaude
pip install .
```

### 运行安装程序 🎬

安装程序相当智能，会引导您完成过程：

```bash
# 查看所有可用选项
SuperClaude install --help

# 快速安装（推荐）
SuperClaude install --quick

# 想先看看会发生什么？
SuperClaude install --quick --dry-run

# 安装所有内容
SuperClaude install --profile developer

# 静默安装（最少输出）
SuperClaude install --quick --quiet

# 强制安装（跳过确认）
python3 SuperClaude.py install --quick --force
```

### 安装期间 📱

安装时会发生什么：

1. **系统检查** - 验证您有所需的依赖项
2. **目录设置** - 创建 `~/.claude/` 目录结构
3. **核心文件** - 复制框架文档文件
4. **命令** - 安装斜杠命令定义（如果选择）
5. **MCP 服务器** - 下载和配置 MCP 服务器（如果选择）
6. **配置** - 使用您的偏好设置 `settings.json`
7. **验证** - 测试一切工作

安装程序显示进度，如果出现任何问题会告诉您。

## 安装后 ✅

### 快速测试 🧪

让我们确保一切工作正常：

```bash
# 检查文件是否已安装
ls ~/.claude/

# 应该显示：CLAUDE.md、COMMANDS.md、settings.json 等
```

**用 Claude Code 测试：**
1. 打开 Claude Code
2. 尝试输入 `/help` - 您应该看到 SuperClaude 命令
3. 尝试 `/analyze --help` - 应该显示命令选项

### 安装了什么 📂

SuperClaude 默认安装到 `~/.claude/`。这是您会找到的内容：

```
~/.claude/
├── CLAUDE.md              # 主要框架入口点
├── COMMANDS.md             # 可用斜杠命令
├── FLAGS.md                # 命令标志和选项
├── PERSONAS.md             # 智能角色系统
├── PRINCIPLES.md           # 开发原则
├── RULES.md                # 操作规则
├── MCP.md                  # MCP 服务器集成
├── MODES.md                # 操作模式
├── ORCHESTRATOR.md         # 智能路由
├── settings.json           # 配置文件
└── commands/               # 单个命令定义
    ├── analyze.md
    ├── build.md
    ├── improve.md
    └── ...（另外 13 个）
```

**每个文件的功能：**
- **CLAUDE.md** - 告诉 Claude Code 关于 SuperClaude 并加载其他文件
- **settings.json** - 配置（MCP 服务器、hooks 等）
- **commands/** - 每个斜杠命令的详细定义

### 第一步 🎯

尝试这些命令开始：

```bash
# 在 Claude Code 中，尝试这些：
/sc:help                    # 查看可用命令
/sc:analyze README.md       # 分析文件
/sc:build --help           # 查看构建选项
/sc:improve --help         # 查看改进选项
```

**如果看起来不知所措，不要担心** - SuperClaude 逐渐增强 Claude Code。您可以根据需要使用任意多或少。

## 管理您的安装 🛠️

### 更新 📅

保持 SuperClaude 最新：

```bash
# 检查更新
SuperClaude update

# 强制更新（覆盖本地更改）
SuperClaude update --force

# 仅更新特定组件
SuperClaude update --components core,commands

# 查看会更新什么
SuperClaude update --dry-run
```

**何时更新：**
- 当发布新 SuperClaude 版本时
- 如果您遇到问题（更新通常包括修复）
- 当新的 MCP 服务器可用时

### 备份 💾

在重大更改前创建备份：

```bash
# 创建备份
SuperClaude backup --create

# 列出现有备份
SuperClaude backup --list

# 从备份恢复
SuperClaude backup --restore

# 创建带自定义名称的备份
SuperClaude backup --create --name "before-update"
```

**何时备份：**
- 更新 SuperClaude 之前
- 在尝试设置之前
- 卸载之前
- 如果您大量自定义，定期进行

### 卸载 🗑️

如果您需要删除 SuperClaude：

```bash
# 删除 SuperClaude（保留备份）
SuperClaude uninstall

# 完全删除（删除所有内容）
SuperClaude uninstall --complete

# 查看会删除什么
SuperClaude uninstall --dry-run
```

**会删除的内容：**
- `~/.claude/` 中的所有文件
- MCP 服务器配置
- Claude Code 中的 SuperClaude 设置

**保留的内容：**
- 您的备份（除非您使用 `--complete`）
- Claude Code 本身（SuperClaude 不会触及它）
- 您的项目和其他文件

## 故障排除 🔧

### 常见问题 🚨

**"未找到 Python"**
```bash
# 尝试 python 而不是 python3
python --version

# 或检查是否安装但不在 PATH 中
which python3
```

**"未找到 Claude CLI"**
- 确保首先安装了 Claude Code
- 尝试 `claude --version` 验证
- 访问 https://claude.ai/code 获取安装帮助

**"权限被拒绝"**
```bash
# 尝试使用显式 Python 路径
/usr/bin/python3 SuperClaude.py install --quick

# 或检查是否需要不同权限
ls -la ~/.claude/
```

**"MCP 服务器无法安装"**
- 检查是否安装了 Node.js：`node --version`
- 检查 npm 是否可用：`npm --version`
- 尝试先不使用 MCP 安装：`--minimal` 或 `--quick`

**"安装中途失败"**
```bash
# 尝试使用详细输出查看发生什么
SuperClaude install --quick --verbose

# 或首先尝试干运行
SuperClaude install --quick --dry-run
```

### 平台特定问题 🖥️

**Windows：**
- 如果您收到"命令未找到"，使用 `python` 而不是 `python3`
- 如果您收到权限错误，以管理员身份运行命令提示符
- 确保 Python 在您的 PATH 中

**macOS：**
- 您可能需要在安全和隐私设置中批准 SuperClaude
- 如果您没有 Python 3.8+，使用 `brew install python3`
- 尝试显式使用 `python3` 而不是 `python`

**Linux：**
- 确保您安装了 `python3-pip`
- 某些包安装可能需要 `sudo`
- 检查 `~/.local/bin` 是否在您的 PATH 中

### 仍有疑问？🤔

**检查我们的故障排除资源：**
- GitHub Issues：https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
- 查找与您相似的现有问题
- 如果找不到解决方案，创建新问题

**报告错误时，请包括：**
- 您的操作系统和版本
- Python 版本（`python3 --version`）
- Claude CLI 版本（`claude --version`）
- 您运行的确切命令
- 完整的错误消息
- 您期望发生的事情

**获取帮助：**
- GitHub 讨论区用于一般问题
- 查看 README.md 获取最新更新
- 查看 ROADMAP.md 以了解您的问题是否已知

## 高级选项 ⚙️

### 自定义安装目录

```bash
# 安装到自定义位置
SuperClaude install --quick --install-dir /custom/path

# 使用环境变量
export SUPERCLAUDE_DIR=/custom/path
SuperClaude install --quick
```

### 组件选择

```bash
# 查看可用组件
SuperClaude install --list-components

# 仅安装特定组件
SuperClaude install --components core,commands

# 跳过某些组件
SuperClaude install --quick --skip mcp
```

### 开发设置

如果您计划贡献或修改 SuperClaude：

```bash
# 安装所有组件的开发者安装
SuperClaude install --profile developer

# 以开发模式安装（符号链接而不是副本）
SuperClaude install --profile developer --dev-mode

# 安装用于开发的 git hooks
SuperClaude install --profile developer --dev-hooks
```

## 下一步？🚀

**现在 SuperClaude 已安装（这很简单，对吧？）：**

1. **开始使用它** - 尝试 `/analyze some-file.js` 或 `/build` 看看会发生什么 ✨
2. **不要为学习而压力** - SuperClaude 通常会弄清楚您需要什么
3. **自由实验** - `/improve` 和 `/troubleshoot` 这样的命令相当宽容
4. **好奇时阅读指南** - 当您想了解刚刚发生的事情时查看 `Docs/`
5. **提供反馈** - 让我们知道什么有效，什么无效

**真正的秘密**：SuperClaude 旨在增强您现有的工作流程，而无需您学习一堆新东西。就像使用常规 Claude Code 一样使用它，但注意它变得多聪明！🎯

**仍然感到不确定？** 先从 `/help` 和 `/analyze README.md` 开始 - 您会看到它实际上多么不令人生畏。

---

## 最后说明 📝

- **安装需要 1-5 分钟** 取决于您选择什么
- **需要磁盘空间：20-100MB**（不多！）
- **与现有工具配合工作** - 不会干扰您的设置
- **易于卸载** 如果您改变主意
- **社区支持** - 我们实际上阅读并回应问题
- ### ⚠️ 重要说明
**安装 SuperClaude 后。**
**您可以使用 `SuperClaude commands`、`python3 -m SuperClaude commands` 或 `python3 SuperClaude commands`**

感谢尝试 SuperClaude！我们希望它让您的开发工作流程更顺畅一些。🙂

---

*最后更新：2024年7月 - 如果本指南中的任何内容错误或令人困惑，请告诉我们！*