# Agent Framework 依赖管理

## 📦 核心依赖

### 必需依赖

| 包名 | 版本 | 用途 |
|------|------|------|
| `httpx[socks]` | >=0.28.0 | HTTP 客户端，用于调用 Gemini REST API，支持 SOCKS 代理 |
| `python-dotenv` | >=1.0.0 | 环境变量管理，用于加载 `.env` 配置文件 |

### 可选依赖

| 包名 | 版本 | 用途 | 安装建议 |
|------|------|------|----------|
| `docstring-parser` | >=0.15 | 工具文档解析，提供更好的类型提示和描述解析 | 推荐安装 |
| `google-generativeai` | >=0.8.0 | Google Gemini SDK（不推荐使用） | ❌ 不推荐，使用 HTTP API 代替 |

## 🚀 安装方式

### 方式一：使用 requirements.txt（推荐）

```bash
pip install -r requirements.txt
```

### 方式二：手动安装

```bash
# 安装核心依赖
pip install httpx[socks]>=0.28.0 python-dotenv>=1.0.0

# 可选：安装 docstring-parser
pip install docstring-parser>=0.15
```

### 方式三：使用 pip 直接安装

```bash
pip install httpx[socks] python-dotenv
```

## 📝 依赖说明

### httpx[socks]
- **用途**：异步 HTTP 客户端，用于调用 Gemini REST API
- **为什么需要 `[socks]`**：支持 SOCKS 代理（很多用户需要代理访问 Google API）
- **如果不需要代理**：可以只安装 `httpx`，但推荐安装完整版

### python-dotenv
- **用途**：从 `.env` 文件加载环境变量
- **配置示例**：
  ```bash
  # .env
  GEMINI_API_KEY=your_api_key_here
  ```

### docstring-parser（可选）
- **用途**：解析工具函数的 docstring，提取参数类型和描述
- **如果没安装**：框架会使用 fallback 解析器，功能稍弱但可用
- **推荐理由**：提供更准确的工具 schema 生成

### google-generativeai（不推荐）
- **为什么不推荐**：
  - SDK 对 JSON Schema 格式要求严格，与 OpenAI 工具格式不完全兼容
  - 难以调试和自定义
  - HTTP API 提供更好的控制和灵活性
- **何时使用**：仅用于学习或简单场景

## 🔧 开发依赖

如果你要开发或测试框架，还需要：

```bash
# 测试框架
pip install pytest pytest-asyncio

# 代码质量
pip install black flake8 mypy

# 文档生成
pip install mkdocs mkdocs-material
```

## 🌐 Python 版本要求

- **最低版本**：Python 3.9
- **推荐版本**：Python 3.11+
- **兼容性**：
  - ✅ Python 3.9+
  - ✅ Python 3.10
  - ✅ Python 3.11
  - ✅ Python 3.12

## 📋 依赖检查

运行以下命令检查依赖是否正确安装：

```bash
python3 -c "
import httpx
import dotenv
print('✅ 核心依赖安装成功')

try:
    import docstring_parser
    print('✅ docstring-parser 已安装')
except ImportError:
    print('⚠️  docstring-parser 未安装（可选）')
"
```

## 🐛 常见问题

### Q1: 安装 httpx 时报错 "No module named 'socksio'"

**解决方案**：
```bash
pip install 'httpx[socks]'
```

### Q2: ImportError: cannot import name 'AsyncClient' from 'httpx'

**解决方案**：升级 httpx 到最新版本
```bash
pip install --upgrade httpx
```

### Q3: 代理设置

如果你使用代理，在 `.env` 中配置：
```bash
HTTP_PROXY=socks5://127.0.0.1:7890
HTTPS_PROXY=socks5://127.0.0.1:7890
```

或者在代码中设置：
```python
import httpx

client = httpx.AsyncClient(
    proxies={
        "http://": "socks5://127.0.0.1:7890",
        "https://": "socks5://127.0.0.1:7890"
    }
)
```

## 📦 生成 requirements.txt

如果你修改了依赖，可以重新生成：

```bash
# 导出当前环境所有包（不推荐）
pip freeze > requirements-full.txt

# 手动维护 requirements.txt（推荐）
# 只包含项目直接依赖，不包括子依赖
```

## 🔄 更新依赖

```bash
# 更新所有依赖到最新版本
pip install --upgrade -r requirements.txt

# 更新特定包
pip install --upgrade httpx
```

## 🎯 最小化依赖原则

本框架遵循最小化依赖原则：
- ✅ 只依赖必需的包
- ✅ 避免大型框架（如 Django, FastAPI）
- ✅ 使用标准库优先（asyncio, json, logging）
- ✅ 可选依赖明确标注

## 📊 依赖关系图

```
agent/
├── httpx (必需)
│   ├── httpcore
│   ├── certifi
│   ├── idna
│   └── socksio (SOCKS 代理支持)
│
├── python-dotenv (必需)
│
└── docstring-parser (可选)
```

## 🌟 生产环境建议

生产环境推荐固定版本：

```txt
# requirements-prod.txt
httpx[socks]==0.28.1
python-dotenv==1.2.1
docstring-parser==0.16
```

使用：
```bash
pip install -r requirements-prod.txt
```

## 📚 相关文档

- [httpx 文档](https://www.python-httpx.org/)
- [python-dotenv 文档](https://github.com/theskumar/python-dotenv)
- [docstring-parser 文档](https://github.com/rr-/docstring_parser)
- [Gemini API 文档](https://ai.google.dev/api/rest)