237 lines
7.1 KiB
Markdown
237 lines
7.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 快速参考
|
||
|
||
### 常用命令
|
||
|
||
**安装与配置：**
|
||
```bash
|
||
# 以开发模式安装
|
||
uv sync
|
||
|
||
# 运行安装程序（多种选项）
|
||
SuperClaude install # 快速设置（推荐）
|
||
SuperClaude install --interactive # 交互式组件选择
|
||
SuperClaude install --minimal # 最小化安装
|
||
SuperClaude install --profile developer # 完整开发者设置
|
||
SuperClaude install --dry-run # 预览更改而不应用
|
||
|
||
# 替代安装方法
|
||
python3 -m SuperClaude install
|
||
SuperClaude update --verbose
|
||
SuperClaude backup --create
|
||
SuperClaude uninstall --yes
|
||
```
|
||
|
||
**包管理：**
|
||
```bash
|
||
# 从 PyPI（推荐）
|
||
uv add SuperClaude
|
||
|
||
# 从源码
|
||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||
cd SuperClaude_Framework
|
||
uv sync
|
||
```
|
||
|
||
**测试（有限）：**
|
||
```bash
|
||
# 注意：尚无正式测试套件
|
||
# 文档中有引用但未实现：
|
||
python Tests/comprehensive_test.py
|
||
python Tests/task_management_test.py
|
||
python Tests/performance_test_suite.py
|
||
```
|
||
|
||
## 架构概述
|
||
|
||
SuperClaude Framework v3.0 是一个**基于 Python 的 Claude Code 增强系统**，通过专业命令、角色（personas）和 MCP 服务器集成扩展 AI 辅助开发功能。
|
||
|
||
### 核心结构
|
||
|
||
```
|
||
SuperClaude_Framework/
|
||
├── SuperClaude/ # 框架文件（安装到 ~/.claude/）
|
||
│ ├── Core/ # 9 个定义行为的核心文档文件
|
||
│ │ ├── CLAUDE.md # 主入口点
|
||
│ │ ├── COMMANDS.md # 命令执行框架
|
||
│ │ ├── FLAGS.md # 标志参考
|
||
│ │ ├── PERSONAS.md # 11 个专业角色（personas）
|
||
│ │ ├── MCP.md # MCP 服务器集成
|
||
│ │ ├── ORCHESTRATOR.md # 智能路由系统
|
||
│ │ ├── PRINCIPLES.md # 核心原则
|
||
│ │ ├── RULES.md # 操作规则
|
||
│ │ ├── MODES.md # 操作模式
|
||
│ ├── Commands/ # 16 个基于 Markdown 的斜杠命令
|
||
│ │ ├── analyze.md
|
||
│ │ ├── build.md
|
||
│ │ ├── implement.md # v3 中的新增功能（替换 v2 的 /build 功能）
|
||
│ │ └── ...
|
||
│ └── Hooks/ # v3 中已移除，v4 中将回归
|
||
│
|
||
├── setup/ # 安装系统
|
||
│ ├── base/ # 核心安装程序基础架构
|
||
│ ├── components/ # 组件安装程序
|
||
│ ├── core/ # 注册表和验证
|
||
│ ├── managers # 配置、文件、设置管理器
|
||
│ ├── operations # 安装、更新、卸载、备份操作
|
||
│ └── utils # UI、日志、安全工具
|
||
│
|
||
├── config/ # 配置
|
||
│ ├── features.json # 功能定义
|
||
│ └── requirements.json # 系统要求
|
||
│
|
||
├── profiles/ # 安装配置文件
|
||
│ ├── quick.json # 快速设置
|
||
│ ├── minimal.json # 最小化安装
|
||
│ └── developer.json # 完整开发者设置
|
||
│
|
||
├── Docs/ # 用户文档（5 个指南）
|
||
└── SuperClaude/__main__.py # 统一 CLI 入口点
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
**1. 安装系统（`setup/` 模块）**
|
||
- 模块化安装程序，支持基于组件的安装
|
||
- 入口点：`SuperClaude/__main__.py`（254 行）
|
||
- 操作：安装、更新、卸载、备份
|
||
- 配置文件：quick、minimal、developer
|
||
|
||
**2. 框架文件（`SuperClaude/` 目录）**
|
||
- 9 个核心文档文件指导 Claude 的行为
|
||
- 16 个 Markdown 格式的斜杠命令定义
|
||
- 安装到 `~/.claude/` 以集成 Claude Code
|
||
|
||
**3. MCP 集成**
|
||
- Context7：文档查找
|
||
- Sequential：复杂分析
|
||
- Magic：UI 组件生成
|
||
- Playwright：浏览器自动化
|
||
|
||
**4. 角色系统（Personas System）**
|
||
- 11 个专业 AI 角色：架构师、前端、后端、分析员、安全员、文员等
|
||
- 智能路由尝试选择合适的专家
|
||
|
||
## 开发工作流程
|
||
|
||
### 开发环境设置
|
||
|
||
```bash
|
||
# 克隆并设置
|
||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||
cd SuperClaude_Framework
|
||
uv sync
|
||
|
||
# 以开发模式安装
|
||
SuperClaude install --profile developer
|
||
```
|
||
|
||
### 核心开发领域
|
||
|
||
**框架文件** - 修改 `SuperClaude/Core/` 和 `SuperClaude/Commands/` 以实现：
|
||
- 文档和行为变更
|
||
- 命令定义和更新
|
||
- 角色配置
|
||
|
||
**安装系统** - 在 `setup/` 模块中工作以实现：
|
||
- 安装程序改进
|
||
- 组件管理
|
||
- 配置文件调整
|
||
|
||
**配置** - 更新以下文件：
|
||
- `config/requirements.json` - 系统要求
|
||
- `config/features.json` - 功能定义
|
||
- `profiles/*.json` - 安装配置文件
|
||
|
||
### 代码组织模式
|
||
|
||
- **模块化架构：** 跨模块分离关注点
|
||
- **文档驱动：** Markdown 文件定义行为
|
||
- **基于组件：** 安装分解为离散组件
|
||
- **配置文件驱动：** 多种安装配置文件适用于不同用例
|
||
- **错误处理：** 具有回退机制的全面错误处理
|
||
|
||
## 重要说明
|
||
|
||
### v2 到 v3 迁移
|
||
|
||
**破坏性变更：** `/build` 命令发生了变化！
|
||
- v2: `/build myFeature` = 功能实现
|
||
- v3: `/sc:build` = 仅编译/打包
|
||
- v3: `/sc:implement` = 功能实现（新功能！）
|
||
|
||
**迁移：** 将 `v2 /build myFeature` 替换为 `v3 /sc:implement myFeature`
|
||
|
||
### 已知问题
|
||
|
||
- 这是 v3.0 的初始发布版本 - 预期会有错误
|
||
- Hooks 系统已移除（v4 中将回归）
|
||
- 无正式测试套件（文档中有引用但未实现）
|
||
- 无 linting/格式化配置
|
||
- MCP 集成部分工作
|
||
|
||
### 构建系统
|
||
|
||
- **构建后端：** Hatchling（通过 pyproject.toml）
|
||
- **包管理器：** uv（现代 Python 包管理器）
|
||
- **依赖：** 最小化（仅 `setuptools>=45.0.0`）
|
||
- **语言：** Python 3.8+（专注于标准库）
|
||
|
||
## 重要文档
|
||
|
||
- **README.md**（342 行）- 主要项目文档、安装指南
|
||
- **CONTRIBUTING.md** - 贡献指南、代码标准
|
||
- **Docs/superclaude-user-guide.md** - 完整用户概览
|
||
- **Docs/commands-guide.md** - 全部 16 个斜杠命令说明
|
||
- **Docs/flags-guide.md** - 命令标志和选项
|
||
- **Docs/installation-guide.md** - 详细安装说明
|
||
|
||
## 日常开发命令
|
||
|
||
```bash
|
||
# 快速安装测试
|
||
SuperClaude install --dry-run
|
||
|
||
# 更新安装
|
||
SuperClaude update --verbose
|
||
|
||
# 更改前创建备份
|
||
SuperClaude backup --create
|
||
|
||
# 查看所有安装选项
|
||
SuperClaude install --help
|
||
|
||
# 使用特定配置文件运行安装程序
|
||
SuperClaude install --profile developer
|
||
```
|
||
|
||
## 配置
|
||
|
||
安装后，用户可以通过以下方式进行自定义：
|
||
- `~/.claude/settings.json` - 主配置
|
||
- `~/.claude/*.md` - 框架行为文件
|
||
|
||
## 未来路线图（v4）
|
||
|
||
- Hooks 系统重新设计和回归
|
||
- 增强的 MCP 套件
|
||
- 性能改进
|
||
- 更多角色
|
||
- 跨 CLI 支持
|
||
|
||
## 故障排除
|
||
|
||
**安装问题：**
|
||
- 检查 Python 3.8+ 已安装
|
||
- 确保 `~/.claude/` 目录权限
|
||
- 使用 `--verbose` 标志获取详细输出
|
||
- 从 v2 升级时进行备份和全新安装
|
||
|
||
**开发问题：**
|
||
- 框架文件位于 `SuperClaude/`（安装到 `~/.claude/`）
|
||
- 安装系统位于 `setup/` 模块
|
||
- 入口点是 `SuperClaude/__main__.py`
|