# 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 |