docs/development-guide.md

# 开发者指南

本文档面向希望参与项目开发、贡献代码或深度定制功能的开发者。

## 🛠️ 开发环境设置

### 前置要求

- **Python**: >=3.9, <4.0 (推荐 3.10+ 以获得最佳性能)
- **Poetry**: 现代化 Python 依赖管理工具
- **Node.js**: >=16.0 (用于 Pyright 类型检查，可选)
- **Git**: 版本控制

### 快速开始

```bash
# 1. 克隆项目
git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
cd AIstudioProxyAPI

# 2. 安装 Poetry (如果尚未安装)
curl -sSL https://install.python-poetry.org | python3 -

# 3. 安装项目依赖 (包括开发依赖)
poetry install --with dev

# 4. 激活虚拟环境
poetry env activate

# 5. 安装 Pyright (可选，用于类型检查)
npm install -g pyright
```

## 📁 项目结构

```
AIstudioProxyAPI/
├── api_utils/              # FastAPI 应用核心模块
│   ├── app.py             # FastAPI 应用入口
│   ├── routes.py          # API 路由定义
│   ├── request_processor.py # 请求处理逻辑
│   ├── queue_worker.py    # 队列工作器
│   └── auth_utils.py      # 认证工具
├── browser_utils/          # 浏览器自动化模块
│   ├── page_controller.py # 页面控制器
│   ├── model_management.py # 模型管理
│   ├── script_manager.py  # 脚本注入管理
│   └── operations.py      # 浏览器操作
├── config/                 # 配置管理模块
│   ├── settings.py        # 主要设置
│   ├── constants.py       # 常量定义
│   ├── timeouts.py        # 超时配置
│   └── selectors.py       # CSS 选择器
├── models/                 # 数据模型
│   ├── chat.py           # 聊天相关模型
│   ├── exceptions.py     # 异常定义
│   └── logging.py        # 日志模型
├── stream/                 # 流式代理服务
│   ├── main.py           # 代理服务入口
│   ├── proxy_server.py   # 代理服务器
│   └── interceptors.py   # 请求拦截器
├── logging_utils/          # 日志工具
├── docs/                   # 文档目录
├── docker/                 # Docker 相关文件
├── pyproject.toml         # Poetry 配置文件
├── pyrightconfig.json     # Pyright 类型检查配置
├── .env.example           # 环境变量模板
└── README.md              # 项目说明
```

## 🔧 依赖管理 (Poetry)

### Poetry 基础命令

```bash
# 查看项目信息
poetry show

# 查看依赖树
poetry show --tree

# 添加新依赖
poetry add package_name

# 添加开发依赖
poetry add --group dev package_name

# 移除依赖
poetry remove package_name

# 更新依赖
poetry update

# 更新特定依赖
poetry update package_name

# 导出 requirements.txt (兼容性)
poetry export -f requirements.txt --output requirements.txt
```

### 依赖分组

项目使用 Poetry 的依赖分组功能：

```toml
[tool.poetry.dependencies]
# 生产依赖
python = ">=3.9,<4.0"
fastapi = "==0.115.12"
# ... 其他生产依赖

[tool.poetry.group.dev.dependencies]
# 开发依赖 (可选安装)
pytest = "^7.0.0"
black = "^23.0.0"
isort = "^5.12.0"
```

### 虚拟环境管理

```bash
# 查看虚拟环境信息
poetry env info

# 查看虚拟环境路径
poetry env info --path

# 激活虚拟环境
poetry env activate

# 在虚拟环境中运行命令
poetry run python script.py

# 删除虚拟环境
poetry env remove python
```

## 🔍 类型检查 (Pyright)

### Pyright 配置

项目使用 `pyrightconfig.json` 进行类型检查配置：

```json
{
    "pythonVersion": "3.13",
    "pythonPlatform": "Darwin",
    "typeCheckingMode": "off",
    "extraPaths": [
        "./api_utils",
        "./browser_utils",
        "./config",
        "./models",
        "./logging_utils",
        "./stream"
    ]
}
```

### 使用 Pyright

```bash
# 安装 Pyright
npm install -g pyright

# 检查整个项目
pyright

# 检查特定文件
pyright api_utils/app.py

# 监视模式 (文件变化时自动检查)
pyright --watch
```

### 类型注解最佳实践

```python
from typing import Optional, List, Dict, Any
from pydantic import BaseModel

# 函数类型注解
def process_request(data: Dict[str, Any]) -> Optional[str]:
    """处理请求数据"""
    return data.get("message")

# 类型别名
ModelConfig = Dict[str, Any]
ResponseData = Dict[str, str]

# Pydantic 模型
class ChatRequest(BaseModel):
    message: str
    model: Optional[str] = None
    temperature: float = 0.7
```

## 🧪 测试

### 运行测试

```bash
# 运行所有测试
poetry run pytest

# 运行特定测试文件
poetry run pytest tests/test_api.py

# 运行测试并生成覆盖率报告
poetry run pytest --cov=api_utils --cov-report=html
```

### 测试结构

```
tests/
├── conftest.py           # 测试配置
├── test_api.py          # API 测试
├── test_browser.py      # 浏览器功能测试
└── test_config.py       # 配置测试
```

## 🔄 开发工作流程

### 1. 代码格式化

```bash
# 使用 Black 格式化代码
poetry run black .

# 使用 isort 整理导入
poetry run isort .

# 检查代码风格
poetry run flake8 .
```

### 2. 类型检查

```bash
# 运行类型检查
pyright

# 或使用 mypy (如果安装)
poetry run mypy .
```

### 3. 测试

```bash
# 运行测试
poetry run pytest

# 运行测试并检查覆盖率
poetry run pytest --cov
```

### 4. 提交代码

```bash
# 添加文件
git add .

# 提交 (建议使用规范的提交信息)
git commit -m "feat: 添加新功能"

# 推送
git push origin feature-branch
```

## 📝 代码规范

### 命名规范

- **文件名**: 使用下划线分隔 (`snake_case`)
- **类名**: 使用驼峰命名 (`PascalCase`)
- **函数名**: 使用下划线分隔 (`snake_case`)
- **常量**: 使用大写字母和下划线 (`UPPER_CASE`)

### 文档字符串

```python
def process_chat_request(request: ChatRequest) -> ChatResponse:
    """
    处理聊天请求
    
    Args:
        request: 聊天请求对象
        
    Returns:
        ChatResponse: 聊天响应对象
        
    Raises:
        ValidationError: 当请求数据无效时
        ProcessingError: 当处理失败时
    """
    pass
```

## 🚀 部署和发布

### 构建项目

```bash
# 构建分发包
poetry build

# 检查构建结果
ls dist/
```

### Docker 开发

```bash
# 构建开发镜像
docker build -f docker/Dockerfile.dev -t aistudio-dev .

# 运行开发容器
docker run -it --rm -v $(pwd):/app aistudio-dev bash
```

## 🤝 贡献指南

### 提交 Pull Request

1. Fork 项目
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 提交更改: `git commit -m 'feat: 添加惊人的功能'`
4. 推送分支: `git push origin feature/amazing-feature`
5. 创建 Pull Request

### 代码审查清单

- [ ] 代码遵循项目规范
- [ ] 添加了必要的测试
- [ ] 测试通过
- [ ] 类型检查通过
- [ ] 文档已更新
- [ ] 变更日志已更新

## 📞 获取帮助

- **GitHub Issues**: 报告 Bug 或请求功能
- **GitHub Discussions**: 技术讨论和问答
- **开发者文档**: 查看详细的 API 文档

## 🔗 相关资源

- [Poetry 官方文档](https://python-poetry.org/docs/)
- [Pyright 官方文档](https://github.com/microsoft/pyright)
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Playwright 官方文档](https://playwright.dev/python/)