609 lines
15 KiB
Markdown
609 lines
15 KiB
Markdown
# 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月 - 如果本指南中的任何内容错误或令人困惑，请告诉我们！*
|