# 依赖管理指南

## 依赖类型说明

### 1. dependencies - 运行时依赖

**在 `pyproject.toml` 中：**
```toml
[project]
dependencies = [
    "langchain>=1.0.2",
    "pydantic>=2.0.0",
]
```

**含义：**
- 这些是项目**运行必需**的依赖
- 安装你的包时会自动安装
- 最终用户需要这些包

**何时使用：**
- 代码中 `import` 的包
- 应用运行时需要的库
- 生产环境需要的依赖

**示例：**
```python
# 这些包在 dependencies 中
from langchain.schema import BaseMessage  # ✓ 运行时需要
from pydantic import BaseModel           # ✓ 运行时需要
```

---

### 2. dependency-groups - 依赖分组

**在 `pyproject.toml` 中：**
```toml
[dependency-groups]
dev = [
    "black>=25.9.0",      # 代码格式化
    "mypy>=1.18.2",       # 类型检查
    "pytest>=8.4.2",      # 测试框架
    "pytest-cov>=7.0.0",  # 测试覆盖率
    "ruff>=0.14.2",       # 代码检查
]
```

**含义：**
- 这些是**可选的**依赖组
- 不会自动安装
- 只有开发者需要

**何时使用：**
- 开发工具（linter, formatter）
- 测试工具
- 文档生成工具
- 构建工具

**示例：**
```bash
# 这些是开发时使用的命令
uv run black src/      # 格式化代码
uv run pytest          # 运行测试
uv run mypy src/       # 类型检查
```

---

## 安装方式

### 场景1：作为最终用户安装

```bash
# 用户只想使用你的包
pip install agentcenter

# 或使用 uv
uv pip install agentcenter
```

**结果：**
- ✓ 安装 `langchain`
- ✓ 安装 `pydantic`
- ✗ 不安装 `black`、`pytest` 等

**用户可以：**
```python
from agentcenter import AgentCenter
agent = AgentCenter()  # ✓ 可以运行
```

**用户不能：**
```bash
black src/  # ✗ 命令不存在（未安装 black）
pytest      # ✗ 命令不存在（未安装 pytest）
```

---

### 场景2：作为开发者安装

```bash
# 克隆项目
git clone <repo>
cd agentcenter

# 安装运行时依赖 + dev 组
uv sync --group dev
```

**结果：**
- ✓ 安装 `langchain`
- ✓ 安装 `pydantic`
- ✓ 安装 `black`、`pytest`、`mypy`、`ruff` 等

**开发者可以：**
```python
from agentcenter import AgentCenter
agent = AgentCenter()  # ✓ 可以运行
```

**还可以：**
```bash
uv run black src/      # ✓ 格式化代码
uv run pytest          # ✓ 运行测试
uv run mypy src/       # ✓ 类型检查
uv run ruff check src/ # ✓ 代码检查
```

---

## uv sync 命令详解

### 基本用法

```bash
# 只安装运行时依赖（dependencies）
uv sync

# 安装运行时依赖 + dev 组
uv sync --group dev

# 安装运行时依赖 + 多个组
uv sync --group dev --group docs --group test

# 安装所有依赖组
uv sync --all-groups
```

### 只安装特定组

```bash
# 只安装 dev 组，不安装运行时依赖
uv sync --only-group dev

# 只安装 test 组
uv sync --only-group test
```

---

## 多个依赖组示例

你可以定义多个依赖组：

```toml
[dependency-groups]
# 开发工具
dev = [
    "black>=25.9.0",
    "mypy>=1.18.2",
    "ruff>=0.14.2",
]

# 测试工具
test = [
    "pytest>=8.4.2",
    "pytest-cov>=7.0.0",
    "pytest-asyncio>=0.23.0",
]

# 文档工具
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.0.0",
]

# 构建工具
build = [
    "build>=1.0.0",
    "twine>=5.0.0",
]
```

**使用：**
```bash
# 安装开发 + 测试
uv sync --group dev --group test

# 安装所有
uv sync --all-groups

# 只安装文档工具
uv sync --only-group docs
```

---

## 对比表格

| 特性 | `dependencies` | `dependency-groups` |
|------|----------------|---------------------|
| **位置** | `[project]` | 顶级配置 |
| **用途** | 运行时必需依赖 | 可选依赖组 |
| **自动安装** | ✓ 是 | ✗ 否，需显式指定 |
| **最终用户** | ✓ 会安装 | ✗ 不会安装 |
| **开发者** | ✓ 会安装 | ✓ 可选安装 |
| **示例** | langchain, pydantic | black, pytest, mypy |
| **场景** | 应用运行 | 开发、测试、构建 |

---

## 最佳实践

### ✓ 好的做法

```toml
[project]
dependencies = [
    "langchain>=1.0.2",      # ✓ 代码中使用的包
    "pydantic>=2.0.0",       # ✓ 运行时需要
]

[dependency-groups]
dev = [
    "black>=25.9.0",         # ✓ 只有开发者需要
    "pytest>=8.4.2",         # ✓ 只有测试时需要
]
```

### ✗ 不好的做法

```toml
[project]
dependencies = [
    "langchain>=1.0.2",
    "pydantic>=2.0.0",
    "pytest>=8.4.2",         # ✗ 最终用户不需要测试工具
    "black>=25.9.0",         # ✗ 最终用户不需要格式化工具
]
```

**问题：**
- 最终用户安装了不需要的包
- 增加安装时间和磁盘空间
- 可能引入不必要的依赖冲突

---

## 快速参考

```bash
# 普通用户（只想运行程序）
uv sync                    # 安装运行时依赖

# 开发者（需要开发工具）
uv sync --group dev        # 安装运行时 + 开发依赖

# 测试人员（只需要测试）
uv sync --only-group test  # 只安装测试依赖

# CI/CD（需要特定组）
uv sync --group test --group build  # 安装测试和构建工具
```

---

## 检查已安装的包

```bash
# 查看所有已安装的包
uv pip list

# 查看依赖树
uv pip tree

# 查看特定包
uv pip show langchain
```

---

## 总结

- **`dependencies`**: 运行时必需，自动安装
- **`dependency-groups`**: 可选分组，按需安装
- 使用 `--group` 或 `--only-group` 控制安装哪些组
- 最终用户只会得到 `dependencies` 中的包
- 开发者可以选择性安装需要的依赖组
