# SuperClaude v3 🚀
[![网站预览](https://img.shields.io/badge/Visit-Website-blue?logo=google-chrome)](https://superclaude-org.github.io/SuperClaude_Website/)
[![许可证：MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI 版本](https://img.shields.io/pypi/v/SuperClaude.svg)](https://pypi.org/project/SuperClaude/)
[![版本](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework)
[![GitHub 问题](https://img.shields.io/github/issues/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
[![欢迎 PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/CONTRIBUTING.md)
[![贡献者](https://img.shields.io/github/contributors/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)
[![网站](https://img.shields.io/website?url=https://superclaude-org.github.io/SuperClaude_Website/)](https://superclaude-org.github.io/SuperClaude_Website/)

一个通过专业命令、角色（personas）和 MCP 服务器集成扩展 Claude Code 的框架。

**📢 状态**：初始版本，刚从 beta 发布！随着我们不断改进，可能会出现错误。

## 什么是 SuperClaude？🤔

SuperClaude 尝试通过添加以下功能使 Claude Code 对开发工作更有帮助：
- 🛠️ **16 个专业命令**用于常见开发任务（有些比其他更好用！）
- 🎭 **智能角色**通常会为不同领域选择合适的专家
- 🔧 **MCP 服务器集成**用于文档、UI 组件和浏览器自动化
- 📋 **任务管理**尝试跟踪进度
- ⚡ **令牌优化**帮助进行更长的对话

这就是我们一直在构建的，以使开发工作流程更顺畅。仍然有些粗糙，但正在变得更好！😊

## 当前状态 📊

✅ **运行良好的部分：**
- 安装套件（从零重写）
- 包含 9 个文档文件的核心框架
- 16 个用于各种开发任务的斜杠命令
- MCP 服务器集成（Context7、Sequential、Magic、Playwright）
- 用于轻松设置的统一 CLI 安装程序

⚠️ **已知问题：**
- 这是初始版本 - 预期会有错误
- 某些功能可能尚未完美工作
- 文档仍在改进中
- Hooks 系统已移除（v4 中将回归）

## 核心功能 ✨

### 命令 🛠️
我们专注于 16 个最常见任务的基本命令：

**开发**：`/sc:implement`、`/sc:build`、`/sc:design`
**分析**：`/sc:analyze`、`/sc:troubleshoot`、`/sc:explain`
**质量**：`/sc:improve`、`/sc:test`、`/sc:cleanup`
**其他**：`/sc:document`、`/sc:git`、`/sc:estimate`、`/sc:task`、`/sc:index`、`/sc:load`、`/sc:spawn`

### 智能角色 🎭
当看起来相关时尝试介入的 AI 专家：
- 🏗️ **architect** - 系统设计和架构相关
- 🎨 **frontend** - UI/UX 和可访问性
- ⚙️ **backend** - API 和基础设施
- 🔍 **analyzer** - 调试和解决问题
- 🛡️ **security** - 安全问题和漏洞
- ✍️ **scribe** - 文档和写作
- *...还有 5 个更多专家*

*（他们并不总是选择完美，但通常都能正确！）*

### MCP 集成 🔧
在有用时连接的外部工具：
- **Context7** - 获取官方库文档和模式
- **Sequential** - 帮助进行复杂的多步骤思考
- **Magic** - 生成现代 UI 组件
- **Playwright** - 浏览器自动化和测试相关

*（当正确连接时，这些工具运行得相当好！🤞）*

## ⚠️ 从 v2 升级？重要！

如果您从 SuperClaude v2 升级，首先需要清理：

1. **卸载 v2** 使用其卸载程序（如果可用）
2. **手动清理** - 如果存在，删除以下内容：
   - `SuperClaude/`
   - `~/.claude/shared/`
   - `~/.claude/commands/`
   - `~/.claude/CLAUDE.md`
4. **然后继续** 下面的 v3 安装

这是因为 v3 具有不同的结构，旧文件可能导致冲突。

### 🔄 **v2 用户的关键变更**
**`/build` 命令发生了变化！** 在 v2 中，`/build` 用于功能实现。在 v3 中：
- `/sc:build` = 仅编译/打包
- `/sc:implement` = 功能实现（新功能！）

**迁移**：将 `v2 /build myFeature` 替换为 `v3 /sc:implement myFeature`

## 安装 📦

SuperClaude 安装是一个**两步过程**：
1. 首先安装 Python 包
2. 然后运行安装程序设置 Claude Code 集成

### 步骤 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
```

### ✅ 完成安装

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

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

或使用 bash 风格 CLI：

```bash
SuperClaude install
```

### 🧠 注意：

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

---
**缺少 Python？** 首先安装 Python 3.7+：
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip

# macOS
brew install python3

# Windows
# 从 https://python.org/downloads/ 下载
```

### 步骤 2：运行安装程序

安装包后，运行 SuperClaude 安装程序配置 Claude Code（您可以使用任何方法）：

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

```bash
# 快速设置（推荐大多数用户）
python3 SuperClaude install

# 交互式选择（选择组件）
python3 SuperClaude install --interactive

# 最小安装（仅核心框架）
python3 SuperClaude install --minimal

# 开发者设置（包含所有内容）
python3 SuperClaude install --profile developer

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

### 或 Python 模块化使用
```bash
# 快速设置（推荐大多数用户）
python3 -m SuperClaude install

# 交互式选择（选择组件）
python3 -m SuperClaude install --interactive

# 最小安装（仅核心框架）
python3 -m SuperClaude install --minimal

# 开发者设置（包含所有内容）
python3 -m SuperClaude install --profile developer

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

### 简单 bash 命令使用
```bash
# 快速设置（推荐大多数用户）
SuperClaude install

# 交互式选择（选择组件）
SuperClaude install --interactive

# 最小安装（仅核心框架）
SuperClaude install --minimal

# 开发者设置（包含所有内容）
SuperClaude install --profile developer

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

**就是这样！🎉** 安装程序处理所有事情：框架文件、MCP 服务器和 Claude Code 配置。

## 工作原理 🔄

SuperClaude 尝试通过以下方式增强 Claude Code：

1. **框架文件** - 安装到 `~/.claude/` 的文档，指导 Claude 如何响应
2. **斜杠命令** - 16 个用于不同开发任务的专业命令
3. **MCP 服务器** - 在工作时添加额外功能的外部服务！
4. **智能路由** - 尝试根据您正在做的事情选择正确的工具和专家

大多数时候它与 Claude Code 的现有功能配合得很好。🤝

## v4 中将会有什么 🔮

我们希望为下一个版本处理这些事情：
- **Hooks 系统** - 事件驱动相关（从 v3 中移除，正在尝试正确重新设计）
- **MCP 套件** - 更多外部工具集成
- **更好的性能** - 尝试让事情更快、更少错误
- **更多角色** - 也许再增加一些领域专家
- **跨 CLI 支持** - 可能与其他 AI 编码助手配合使用

*（不过不保证时间表 - 我们仍在摸索 v3！😅）*

## 配置 ⚙️

安装后，您可以通过编辑以下内容自定义 SuperClaude：
- `~/.claude/settings.json` - 主配置
- `~/.claude/*.md` - 框架行为文件

大多数用户可能不需要更改任何内容 - 开箱即用效果通常不错。🎛️

## 文档 📖

想了解更多？查看我们的指南：

- 📚 [**用户指南**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Docs/superclaude-user-guide.md) - 完整概览和入门
- 🛠️ [**命令指南**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Docs/commands-guide.md) - 全部 16 个斜杠命令说明
- 🏳️ [**标志指南**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Docs/flags-guide.md) - 命令标志和选项
- 🎭 [**角色指南**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Docs/personas-guide.md) - 了解角色系统
- 📦 [**安装指南**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Docs/installation-guide.md) - 详细安装说明

这些指南比此 README 有更多细节，并保持最新。

## 贡献 🤝

我们欢迎贡献！我们可以使用帮助的领域：
- 🐛 **错误报告** - 让我们知道什么坏了
- 📝 **文档** - 帮助我们更好地解释事物
- 🧪 **测试** - 为不同设置提供更多测试覆盖率
- 💡 **想法** - 新功能或改进的建议

代码库是相当直接的 Python + 文档文件。

## 项目结构 📁

```
SuperClaude/
├── setup.py               # pypi 设置文件
├── SuperClaude/           # 框架文件
│   ├── Core/              # 行为文档（COMMANDS.md、FLAGS.md 等）
│   ├── Commands/          # 16 个斜杠命令定义
│   └── Settings/          # 配置文件
├── setup/                 # 安装系统
└── profiles/              # 安装配置文件（quick、minimal、developer）
```

## 架构说明 🏗️

v3 架构专注于：
- **简单性** - 移除没有增加价值的复杂性
- **可靠性** - 更好的安装和更少的破坏性变更
- **模块化** - 只选择您想要的组件
- **性能** - 通过更智能的缓存实现更快的操作

我们从 v2 学到了很多，并试图解决主要痛点。

## 常见问题 🙋

**Q：为什么移除 hooks 系统？**
A：它变得复杂且有错误。我们正在为 v4 正确地重新设计它。

**Q：这是否与其他 AI 助手配合使用？**
A：目前仅支持 Claude Code，但 v4 将有更广泛的兼容性。

**Q：这对于日常使用足够稳定吗？**
A：基本功能运行得相当好，但由于是全新版本，肯定预期会有一些粗糙边缘。可能适合实验！🧪

## SuperClaude 贡献者

[![贡献者](https://contrib.rocks/image?repo=SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)

## 许可证

MIT - [查看 LICENSE 文件了解详情](https://opensource.org/licenses/MIT)

## Star 历史

<a href="https://www.star-history.com/#SuperClaude-Org/SuperClaude_Framework&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
 </picture>
</a>
---

*由厌倦了通用响应的开发者构建。希望您觉得有用！🙂*

---