284 lines
5.5 KiB
Markdown
284 lines
5.5 KiB
Markdown
# 🚀 快速开始指南
|
||
|
||
本指南帮助你在 5 分钟内运行红山智能开发助手 Demo。
|
||
|
||
## 📋 前置要求
|
||
|
||
确保你已安装以下工具：
|
||
|
||
- **Node.js** >= 18.0.0 ([下载](https://nodejs.org/))
|
||
- **Python** >= 3.10 ([下载](https://www.python.org/))
|
||
- **Rust** >= 1.70 ([安装 Tauri](https://tauri.app/v1/guides/getting-started/prerequisites))
|
||
|
||
## ⚡ 快速启动（5 分钟）
|
||
|
||
### 步骤 1: 克隆项目
|
||
|
||
```bash
|
||
cd Red
|
||
```
|
||
|
||
### 步骤 2: 安装前端依赖
|
||
|
||
```bash
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
```
|
||
|
||
### 步骤 3: 安装后端依赖
|
||
|
||
```bash
|
||
# 创建虚拟环境（推荐）
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows:
|
||
venv\Scripts\activate
|
||
# Mac/Linux:
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
cd api
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 步骤 4: 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
copy .env.example .env # Windows
|
||
cp .env.example .env # Mac/Linux
|
||
```
|
||
|
||
编辑 `.env` 文件，至少配置一个 AI 提供商的 API 密钥：
|
||
|
||
```env
|
||
# 使用 OpenAI
|
||
OPENAI_API_KEY=sk-your-key-here
|
||
|
||
# 或使用 Google Gemini
|
||
GOOGLE_API_KEY=your-google-key-here
|
||
|
||
# 或使用本地 Ollama（无需 API 密钥）
|
||
MODEL_PROVIDER=ollama
|
||
OLLAMA_HOST=http://localhost:11434
|
||
```
|
||
|
||
### 步骤 5: 启动应用
|
||
|
||
**打开第一个终端 - 启动后端：**
|
||
|
||
```bash
|
||
cd api
|
||
python main.py
|
||
```
|
||
|
||
你应该看到：
|
||
```
|
||
INFO: Starting Red Mountain Dev Assistant API on port 8001
|
||
INFO: Application startup complete.
|
||
INFO: Uvicorn running on http://0.0.0.0:8001
|
||
```
|
||
|
||
**打开第二个终端 - 启动前端：**
|
||
|
||
```bash
|
||
npm run dev
|
||
# 或
|
||
yarn dev
|
||
```
|
||
|
||
你应该看到：
|
||
```
|
||
VITE v6.0.7 ready in XXX ms
|
||
|
||
➜ Local: http://localhost:1420/
|
||
```
|
||
|
||
**🎉 完成！** 在浏览器打开 http://localhost:1420/
|
||
|
||
### 步骤 6: 启动桌面应用（可选）
|
||
|
||
如果你想使用桌面应用而非浏览器：
|
||
|
||
```bash
|
||
# 在新终端中运行
|
||
npm run tauri:dev
|
||
# 或
|
||
yarn tauri:dev
|
||
```
|
||
|
||
Tauri 会自动打开桌面窗口。
|
||
|
||
---
|
||
|
||
## 🧪 测试功能
|
||
|
||
### 1. 测试智能问答
|
||
|
||
1. 点击侧边栏的 **"智能问答"**
|
||
2. 在输入框输入问题，例如：`什么是红山开源平台？`
|
||
3. 点击发送按钮
|
||
|
||
**注意**: 当前是 Demo 阶段，会返回模拟响应。真实 AI 功能需要完成后端 RAG 实现。
|
||
|
||
### 2. 测试代码分析
|
||
|
||
1. 点击侧边栏的 **"代码分析"**
|
||
2. 选择仓库类型（GitHub/GitLab/Bitbucket）
|
||
3. 输入仓库地址，例如：`https://github.com/facebook/react`
|
||
4. 点击 **"开始分析"**
|
||
|
||
**注意**: 当前是 Demo 阶段，会显示"功能开发中"提示。
|
||
|
||
### 3. 配置设置
|
||
|
||
1. 点击侧边栏的 **"设置"**
|
||
2. 选择 API 提供商
|
||
3. 输入 API 密钥
|
||
4. 配置后端服务地址
|
||
5. 点击 **"保存设置"**
|
||
|
||
---
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 问题 1: 端口已被占用
|
||
|
||
**错误**: `Address already in use`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 修改端口
|
||
# 后端: 编辑 .env 文件
|
||
API_PORT=8002
|
||
|
||
# 前端: 编辑 vite.config.ts
|
||
server: {
|
||
port: 1421, # 修改这里
|
||
}
|
||
```
|
||
|
||
### 问题 2: Python 包安装失败
|
||
|
||
**错误**: `ERROR: Could not find a version that satisfies the requirement...`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 升级 pip
|
||
pip install --upgrade pip
|
||
|
||
# 使用国内镜像（中国用户）
|
||
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
### 问题 3: Tauri 构建失败
|
||
|
||
**错误**: `Rust compiler not found`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 安装 Rust
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
# 重启终端后验证
|
||
rustc --version
|
||
```
|
||
|
||
### 问题 4: Node.js 版本过低
|
||
|
||
**错误**: `error:0308010C:digital envelope routines::unsupported`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 安装 Node.js 18+
|
||
# 使用 nvm（推荐）
|
||
nvm install 18
|
||
nvm use 18
|
||
|
||
# 或从官网下载: https://nodejs.org/
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 下一步
|
||
|
||
### 学习资源
|
||
|
||
- **完整文档**: 查看 [README.md](./README.md)
|
||
- **开发计划**: 查看 [DEVELOPMENT_PLAN.md](./DEVELOPMENT_PLAN.md)
|
||
- **参考实现**: 查看 `reference-deepwiki/` 目录
|
||
|
||
### 开发建议
|
||
|
||
1. **先运行 Demo** - 熟悉项目结构和界面
|
||
2. **阅读 DeepWiki 源码** - 理解 RAG 实现
|
||
3. **实现核心功能** - 按照开发计划逐步实现
|
||
4. **测试和优化** - 确保功能稳定可靠
|
||
|
||
### 参与开发
|
||
|
||
1. 创建功能分支
|
||
2. 实现功能并测试
|
||
3. 提交 Pull Request
|
||
4. 代码审查和合并
|
||
|
||
---
|
||
|
||
## 🎯 常用命令
|
||
|
||
```bash
|
||
# 前端开发
|
||
npm run dev # 启动开发服务器
|
||
npm run build # 构建生产版本
|
||
npm run preview # 预览生产版本
|
||
|
||
# Tauri 桌面应用
|
||
npm run tauri:dev # 开发模式
|
||
npm run tauri:build # 构建应用
|
||
|
||
# 后端开发
|
||
python api/main.py # 启动 API 服务
|
||
pytest # 运行测试
|
||
|
||
# 代码质量
|
||
npm run lint # 前端代码检查
|
||
pylint api/ # 后端代码检查
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 获取帮助
|
||
|
||
- **查看文档**: [README.md](./README.md)
|
||
- **查看示例**: 参考 DeepWiki 实现
|
||
- **报告问题**: 在 Issues 中提问
|
||
- **技术讨论**: 参与社区讨论
|
||
|
||
---
|
||
|
||
## ✅ 检查清单
|
||
|
||
确保完成以下步骤：
|
||
|
||
- [ ] 安装了 Node.js 18+
|
||
- [ ] 安装了 Python 3.10+
|
||
- [ ] 安装了 Rust（如果要用 Tauri）
|
||
- [ ] 克隆了项目代码
|
||
- [ ] 安装了前端依赖 (`npm install`)
|
||
- [ ] 安装了后端依赖 (`pip install -r api/requirements.txt`)
|
||
- [ ] 配置了 `.env` 文件
|
||
- [ ] 后端服务正常启动 (http://localhost:8001)
|
||
- [ ] 前端应用正常访问 (http://localhost:1420)
|
||
- [ ] 能够看到应用界面
|
||
- [ ] 测试了基本功能
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<p>🎉 恭喜！你已经成功运行了红山智能开发助手！</p>
|
||
<p>现在可以开始探索和开发了 🚀</p>
|
||
</div>
|
||
|