目录

1. 项目概述
2. 依赖管理工具介绍
3. 依赖文件详解
4. PyCharm中的依赖安装
5. Ubuntu系统中的依赖安装
6. 常见问题与最佳实践

---

项目概述

JoyAgent-JDGenie 是一个多模块Python项目，包含两个主要的Python子项目：

项目结构

joyagent-jdgenie/
├── genie-client/          # FastAPI MCP客户端
│   ├── pyproject.toml     # 依赖声明文件
│   └── uv.lock           # 依赖锁定文件
├── genie-tool/           # 工具服务
│   ├── pyproject.toml    # 依赖声明文件
│   └── uv.lock          # 依赖锁定文件
├── genie-backend/        # Java后端
└── ui/                  # 前端界面

Python版本要求

• genie-client: Python 3.10 - 3.13
• genie-tool: Python 3.11 - 3.13

---

依赖管理工具介绍

为什么使用 uv？

本项目使用 uv 作为依赖管理工具，这是一个用Rust编写的现代化Python包管理器，相比传统的 pip + virtualenv 方案有显著优势：

特性	uv	pip	poetry
安装速度	极快（10-100x）	慢	中等
依赖解析	智能快速	简单	较慢
虚拟环境管理	自动化	手动	自动化
跨平台一致性	优秀	一般	良好
锁文件	uv.lock	❌	poetry.lock

uv vs pip 核心区别

# 传统方式（pip）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
pip install -r requirements.txt

# 现代方式（uv）
uv sync  # 一条命令完成虚拟环境创建、依赖安装

---

依赖文件详解

1. pyproject.toml - 项目配置与依赖声明

这是Python项目的标准配置文件（PEP 518/621规范），替代传统的 setup.py 和 requirements.txt。

genie-client/pyproject.toml

[project]
name = "genie-client"
version = "0.1.0"
description = "FastAPI-based web service client for Model Context Protocol (MCP) servers"
readme = "README.md"
requires-python = ">=3.10,<=3.13"  # Python版本约束
dependencies = [
    "fastapi>=0.115.12",           # Web框架
    "mcp==1.9.4",                  # MCP协议库
]

关键字段解析：

• requires-python: 指定兼容的Python版本范围
• dependencies: 运行时必需的依赖包
• 使用语义化版本约束：
  • >=0.115.12: 最低版本要求
  • ==1.9.4: 精确版本锁定
  • ^1.0.0: 兼容版本（poetry风格）

genie-tool/pyproject.toml

[project]
name = "python"
version = "0.1.0"
description = "Genie Tools"
readme = "README.md"
requires-python = ">=3.11,<4.0"
dependencies = [
    "aiosqlite>=0.21.0",           # 异步SQLite
    "asyncio>=4.0.0",              # 异步IO
    "beautifulsoup4>=4.13.4",      # HTML解析
    "elasticsearch==7.17.12",      # ES客户端
    "fastapi>=0.115.14",           # Web框架
    "pandas>=2.3.0",               # 数据分析
    "scikit-learn>=1.7.1",         # 机器学习
    "openai>=1.93.0",              # OpenAI SDK
    # ... 更多依赖
]

依赖分类：

1. Web框架: fastapi, uvicorn, sse-starlette
2. 数据处理: pandas, numpy, openpyxl
3. AI/ML: openai, litellm, smolagents, scikit-learn
4. 数据库: aiosqlite, sqlmodel, elasticsearch, qdrant-client
5. 工具库: beautifulsoup4, jieba, loguru

2. uv.lock - 依赖锁定文件

类似于 package-lock.json (npm) 或 poetry.lock，记录所有依赖包的精确版本和哈希值。

作用：

• 确保团队成员安装完全相同的依赖版本
• 记录传递依赖（dependencies of dependencies）
• 包含完整性校验哈希
• 支持跨平台一致性

示例结构：

[[package]]
name = "fastapi"
version = "0.115.14"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "pydantic" },
    { name = "starlette" },
]
wheels = [
    { url = "...", hash = "sha256:..." },
]

3. 依赖文件对比表

文件类型	pyproject.toml	uv.lock	requirements.txt
用途	声明直接依赖	锁定所有依赖	声明所有依赖
版本	范围约束	精确版本	可精确可范围
传递依赖	❌	✅	❌
可读性	高	低（自动生成）	中等
推荐手动编辑	✅	❌	✅

---

PyCharm中的依赖安装

方法一：使用PyCharm内置终端（推荐）

步骤1：安装uv工具

在PyCharm内置终端中执行：

Windows:

# 使用pip安装
pip install uv

# 或使用官方安装脚本
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

# 使用pip安装
pip install uv

# 或使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

步骤2：安装项目依赖

# 进入genie-tool目录
cd genie-tool

# 同步依赖（自动创建虚拟环境）
uv sync

# 激活虚拟环境
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

uv sync 命令详解：

• 自动读取 pyproject.toml 和 uv.lock
• 自动创建 .venv 虚拟环境（如果不存在）
• 安装所有锁定版本的依赖
• 验证依赖完整性

方法二：配置PyCharm解释器（图形界面）

步骤1：创建虚拟环境

1. 打开 File → Settings → Project → Python Interpreter
2. 点击右上角 齿轮图标 → Add Interpreter → Add Local Interpreter
3. 选择 Virtualenv Environment
4. 设置：
   • Location: D:\work-src\joyagent-jdgenie\genie-tool\.venv
   • Base interpreter: 选择 Python 3.11+
   • 勾选 Inherit global site-packages（可选）

步骤2：安装依赖

有两种方式：

方式A：使用uv（推荐）
在PyCharm终端执行：

cd genie-tool
uv sync

方式B：使用pip
如果团队不使用uv，可以导出requirements.txt：

# 从pyproject.toml生成requirements.txt
uv pip compile pyproject.toml -o requirements.txt

# 安装依赖
pip install -r requirements.txt

方法三：使用PyCharm的uv插件（未来支持）

PyCharm 2024+ 版本可能原生支持uv，届时可直接在项目配置中选择uv作为包管理器。

验证安装

在PyCharm Python Console中测试：

import fastapi
import pandas as pd
import openai

print("依赖安装成功！")
print(f"FastAPI version: {fastapi.__version__}")
print(f"Pandas version: {pd.__version__}")

---

Ubuntu系统中的依赖安装

前置要求

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装Python 3.11+（如果未安装）
sudo apt install python3.11 python3.11-venv python3-pip -y

# 验证Python版本
python3.11 --version

方法一：使用uv（推荐生产环境）

步骤1：安装uv

# 方法A：使用官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法B：使用pip
pip3 install uv

# 添加到PATH（如果使用官方脚本）
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证安装
uv --version

步骤2：克隆项目并安装依赖

# 克隆项目
git clone <your-repo-url>
cd joyagent-jdgenie/genie-tool

# 同步依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate

# 验证环境
python --version
pip list

步骤3：初始化数据库（首次运行）

python -m genie_tool.db.db_engine

步骤4：配置环境变量

# 复制环境变量模板
cp .env_template .env

# 编辑配置
nano .env  # 或使用 vim/vi

步骤5：启动服务

# 使用uv运行
uv run python server.py

# 或激活虚拟环境后运行
source .venv/bin/activate
python server.py

方法二：使用传统pip方式

步骤1：创建虚拟环境

cd genie-tool

# 创建虚拟环境
python3.11 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate

步骤2：安装依赖

# 方式A：使用uv导出requirements.txt
pip install uv
uv pip compile pyproject.toml -o requirements.txt
pip install -r requirements.txt

# 方式B：直接使用uv安装（在虚拟环境中）
pip install uv
uv pip install -e .

系统服务配置（可选）

创建systemd服务自动启动：

# 创建服务文件
sudo nano /etc/systemd/system/genie-tool.service

服务配置：

[Unit]
Description=Genie Tool Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/joyagent-jdgenie/genie-tool
Environment="PATH=/path/to/.venv/bin"
ExecStart=/path/to/.venv/bin/python server.py
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable genie-tool
sudo systemctl start genie-tool
sudo systemctl status genie-tool

Docker部署（推荐生产环境）

项目根目录已包含 Dockerfile：

# 构建镜像
docker build -t joyagent-genie:latest .

# 运行容器
docker run -d \
  --name genie-tool \
  -p 8000:8000 \
  -v $(pwd)/genie-tool/.env:/app/genie-tool/.env \
  joyagent-genie:latest

# 查看日志
docker logs -f genie-tool