EPEEAIKit/art-agent/ENVIRONMENT.md

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（路径来自 local-env.json 的 nodejs_path）
$env:PATH = "你的nodejs_path;" + $env:PATH

# 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. 后端

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. 前端

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

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