207 lines
6.3 KiB
Markdown
207 lines
6.3 KiB
Markdown
# EPEEKit 开发环境说明
|
||
|
||
> 最后更新：2026-04-16
|
||
|
||
## 系统要求
|
||
|
||
| 项目 | 最低版本 | 备注 |
|
||
|------|---------|------|
|
||
| OS | Windows 10+ / macOS / Linux | 跨平台支持 |
|
||
| Python | 3.12+ | 用于后端 |
|
||
| Node.js | 22+ LTS | 用于前端 |
|
||
| npm | 10+ | 随 Node.js 安装 |
|
||
| Ollama | latest | Mem0 embedding 服务依赖，需启动 `nomic-embed-text` 模型 |
|
||
|
||
## 本地环境配置（local-env.json）
|
||
|
||
设备绑定的路径（如 Node.js 安装位置）**不硬编码在任何 Skill 或配置中**，
|
||
统一通过 `.cursor/local-env.json` 管理。
|
||
|
||
| 字段 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `nodejs_path` | Node.js 安装目录（含 node/npm），为 `null` 表示已在系统 PATH | `C:\Users\xxx\AppData\Local\nodejs` |
|
||
| `shell` | 当前设备的 shell 类型 | `powershell` / `bash` / `zsh` |
|
||
|
||
- **首次使用**：Agent 会自动探测并生成，也可手动复制 `.cursor/local-env.example.json` 并修改
|
||
- **已 gitignored**：不进入版本控制，每台设备独立维护
|
||
- **模板参考**：`.cursor/local-env.example.json`
|
||
|
||
### Node.js PATH 注意事项
|
||
|
||
如果 `nodejs_path` 不为 null，说明 Node.js 未在系统 PATH 中，启动前端前需注入：
|
||
|
||
```powershell
|
||
# PowerShell（路径来自 local-env.json 的 nodejs_path）
|
||
$env:PATH = "你的nodejs_path;" + $env:PATH
|
||
```
|
||
|
||
```bash
|
||
# bash/zsh
|
||
export PATH="你的nodejs_path:$PATH"
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
EPEEAIKit/
|
||
├── .cursor/
|
||
│ ├── local-env.json # 本地环境配置（gitignored，设备绑定）
|
||
│ ├── local-env.example.json # 本地环境配置模板（git tracked）
|
||
│ ├── hooks.json # Cursor hooks 配置
|
||
│ └── hooks/ # Hook 脚本（.ps1 + .sh 双版本）
|
||
├── art-agent/
|
||
│ ├── backend/ # FastAPI 后端（Python）
|
||
│ │ ├── app/ # 应用代码
|
||
│ │ ├── venv/ # Python 虚拟环境（gitignored）
|
||
│ │ ├── requirements.txt # 直接依赖（锁定版本）
|
||
│ │ └── requirements-lock.txt # 完整依赖树（pip freeze）
|
||
│ ├── frontend/ # Next.js 前端（TypeScript）
|
||
│ │ ├── src/ # 应用代码
|
||
│ │ ├── node_modules/ # npm 依赖（gitignored）
|
||
│ │ ├── package.json # 直接依赖
|
||
│ │ └── package-lock.json # 完整依赖树锁定
|
||
│ └── ENVIRONMENT.md # 本文件
|
||
```
|
||
|
||
## 后端依赖（Python）
|
||
|
||
### 直接依赖
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| fastapi | 0.135.3 | Web 框架 |
|
||
| uvicorn | 0.44.0 | ASGI 服务器 |
|
||
| openai | 2.32.0 | OpenAI / 向量引擎 LLM & 生图 API |
|
||
| replicate | 1.0.7 | Replicate 生图 API（Flux/SDXL/Kolors 等） |
|
||
| sse-starlette | 3.3.4 | Server-Sent Events 流式响应 |
|
||
| python-multipart | 0.0.26 | 文件上传处理 |
|
||
| httpx | 0.28.1 | 异步 HTTP 客户端 |
|
||
| python-dotenv | 1.2.2 | 环境变量 `.env` 加载 |
|
||
| Pillow | 12.2.0 | 图像处理 |
|
||
| mem0ai | 1.0.11 | Mem0 长期记忆系统 |
|
||
| ollama | 0.6.1 | Ollama 本地 LLM/embedding 客户端 |
|
||
| sqlmodel | 0.0.38 | SQLModel ORM（SQLite 用户表） |
|
||
| pwdlib[argon2,bcrypt] | 0.3.0 | 密码哈希（Argon2id + bcrypt 兼容） |
|
||
| python-jose[cryptography] | 3.5.0 | JWT 认证 |
|
||
|
||
### 间接依赖（关键）
|
||
|
||
| 包名 | 版本 | 来源 |
|
||
|------|------|------|
|
||
| pydantic | 2.13.1 | fastapi 依赖 |
|
||
| starlette | 1.0.0 | fastapi 依赖 |
|
||
| SQLAlchemy | 2.0.49 | sqlmodel / mem0ai 依赖 |
|
||
| qdrant-client | 1.17.1 | mem0ai 依赖（向量数据库） |
|
||
| numpy | 2.4.4 | qdrant-client 依赖 |
|
||
| grpcio | 1.80.0 | qdrant-client 依赖 |
|
||
| cryptography | 46.0.7 | python-jose[cryptography] 依赖 |
|
||
| argon2-cffi | 25.1.0 | pwdlib[argon2] 依赖 |
|
||
| bcrypt | 5.0.0 | pwdlib[bcrypt] 依赖 |
|
||
|
||
完整依赖树见 `requirements-lock.txt`（共 61 个包）。
|
||
|
||
## 前端依赖（Node.js）
|
||
|
||
### 直接依赖（dependencies）
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| next | 15.5.15 | React 全栈框架 |
|
||
| react | 19.2.5 | UI 库 |
|
||
| react-dom | 19.2.5 | React DOM 渲染 |
|
||
|
||
### 开发依赖（devDependencies）
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| typescript | 5.9.3 | TypeScript 编译器 |
|
||
| tailwindcss | 4.2.2 | CSS 工具框架 |
|
||
| @tailwindcss/postcss | 4.2.2 | Tailwind PostCSS 插件 |
|
||
| postcss | 8.5.9 | CSS 后处理器 |
|
||
| @types/node | 22.19.17 | Node.js 类型定义 |
|
||
| @types/react | 19.2.14 | React 类型定义 |
|
||
| @types/react-dom | 19.2.3 | ReactDOM 类型定义 |
|
||
|
||
完整依赖树见 `package-lock.json`（共 46 个包）。
|
||
|
||
## 外部服务依赖
|
||
|
||
| 服务 | 端口 | 用途 | 必需 |
|
||
|------|------|------|------|
|
||
| Ollama | 11434 | 本地 embedding（nomic-embed-text）| 是（Mem0 依赖） |
|
||
| Qdrant | 6333 | 本地向量数据库（Mem0 存储） | 是（Mem0 依赖） |
|
||
|
||
## 环境变量
|
||
|
||
后端通过 `.env` 文件加载配置，主要包含：
|
||
- LLM API Key（向量引擎 / DeepSeek）
|
||
- Replicate API Token
|
||
- 代理配置（HTTPS_PROXY）
|
||
- Gemini 超时参数（VECTORENGINE_GEMINI_*_TIMEOUT）
|
||
- JWT Secret
|
||
|
||
详见 `art-agent/backend/.env`（gitignored，不纳入版本控制）。
|
||
|
||
## 环境搭建步骤
|
||
|
||
### 0. 本地环境配置（首次）
|
||
|
||
复制 `.cursor/local-env.example.json` 为 `.cursor/local-env.json`，修改为本机实际值。
|
||
或者启动 Cursor Agent 会话，Agent 会自动探测并生成。
|
||
|
||
### 1. 后端
|
||
|
||
```bash
|
||
cd art-agent/backend
|
||
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows PowerShell:
|
||
.\venv\Scripts\Activate.ps1
|
||
# macOS/Linux:
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 启动（需要先启动 Ollama）
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 2. 前端
|
||
|
||
```bash
|
||
cd art-agent/frontend
|
||
|
||
# 如果 Node.js 未在系统 PATH 中（参考 local-env.json 的 nodejs_path）：
|
||
# PowerShell: $env:PATH = "你的nodejs_path;" + $env:PATH
|
||
# bash/zsh: export PATH="你的nodejs_path:$PATH"
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
### 3. Ollama
|
||
|
||
```bash
|
||
# 启动 Ollama 服务
|
||
ollama serve
|
||
|
||
# 拉取 embedding 模型（首次）
|
||
ollama pull nomic-embed-text
|
||
```
|
||
|
||
## 访问地址
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| 前端页面 | http://localhost:3000 |
|
||
| 后端 API | http://localhost:8000 |
|
||
| API 文档 | http://localhost:8000/docs |
|
||
| Ollama | http://localhost:11434 |
|