# 贡献指南

感谢你对 NSFC Spider 项目的关注！我们欢迎各种形式的贡献。

## 如何贡献

### 报告 Bug

如果你发现了 Bug，请：

1. 在 [Issues](https://github.com/yourusername/nsfc-spider/issues) 中搜索是否已有相关问题
2. 如果没有，创建新 Issue，包含：
   - 清晰的标题
   - 详细的问题描述
   - 复现步骤
   - 预期行为和实际行为
   - 环境信息（Python 版本、操作系统等）
   - 错误日志或截图

### 提出新功能

如果你有新功能建议：

1. 先在 Issues 中讨论你的想法
2. 说明功能的用途和价值
3. 如果可能，提供实现思路

### 提交代码

#### 1. Fork 项目

点击项目页面右上角的 "Fork" 按钮。

#### 2. 克隆到本地

```bash
git clone https://github.com/your-username/nsfc-spider.git
cd nsfc-spider
```

#### 3. 创建分支

```bash
git checkout -b feature/your-feature-name
```

分支命名规范：
- `feature/xxx` - 新功能
- `fix/xxx` - Bug 修复
- `docs/xxx` - 文档更新
- `refactor/xxx` - 代码重构

#### 4. 设置开发环境

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 安装 Playwright
playwright install chromium
```

#### 5. 进行修改

- 遵循项目的代码风格
- 添加必要的测试
- 更新相关文档

#### 6. 运行测试

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

# 运行特定测试
pytest tests/test_scraper.py
```

#### 7. 提交代码

```bash
git add .
git commit -m "feat: 添加新功能描述"
```

提交信息规范（遵循 [Conventional Commits](https://www.conventionalcommits.org/)）：

- `feat:` - 新功能
- `fix:` - Bug 修复
- `docs:` - 文档更新
- `style:` - 代码格式调整
- `refactor:` - 代码重构
- `test:` - 测试相关
- `chore:` - 构建/工具相关

#### 8. 推送到 GitHub

```bash
git push origin feature/your-feature-name
```

#### 9. 创建 Pull Request

1. 访问你的 Fork 页面
2. 点击 "New Pull Request"
3. 填写 PR 描述：
   - 说明改动内容
   - 关联相关 Issue
   - 列出测试情况

## 代码规范

### Python 代码风格

- 遵循 [PEP 8](https://pep8.org/)
- 使用 4 个空格缩进
- 最大行长度 100 字符
- 使用类型注解

示例：

```python
from typing import List, Optional

def search_projects(
    keyword: str,
    pages: int = 1,
    years: Optional[List[int]] = None
) -> SearchResults:
    """搜索项目
    
    Args:
        keyword: 搜索关键词
        pages: 页数，0 表示全部
        years: 年份列表
        
    Returns:
        搜索结果
    """
    pass
```

### 文档字符串

使用 Google 风格的文档字符串：

```python
def function(arg1: str, arg2: int) -> bool:
    """简短描述
    
    详细描述（可选）
    
    Args:
        arg1: 参数1描述
        arg2: 参数2描述
        
    Returns:
        返回值描述
        
    Raises:
        ValueError: 错误情况描述
    """
    pass
```

### 命名规范

- 类名：`PascalCase`
- 函数/变量：`snake_case`
- 常量：`UPPER_SNAKE_CASE`
- 私有成员：`_leading_underscore`

## 项目结构

```
nsfc-spider/
├── src/nsfc_spider/      # 源代码
│   ├── __init__.py
│   ├── agent.py          # Agent 封装
│   ├── config.py         # 配置管理
│   ├── memory.py         # 记忆系统
│   ├── cli/              # CLI 模块
│   └── tasks/            # 任务模块
│       ├── direct_scraper.py
│       ├── nsfc_search.py
│       ├── analyzer.py
│       ├── llm_filter.py
│       └── review_generator.py
├── tests/                # 测试文件
├── docs/                 # 文档
├── config/               # 配置示例
└── pyproject.toml        # 项目配置
```

## 开发指南

### 添加新的爬取任务

1. 在 `src/nsfc_spider/tasks/` 创建新文件
2. 继承基础类或实现接口
3. 添加到 `tasks/__init__.py`
4. 在 CLI 中添加命令
5. 编写测试
6. 更新文档

### 添加新的 LLM 提供商

1. 在 `config.py` 中添加配置
2. 在 `agent.py` 中添加支持
3. 更新文档

### 调试技巧

```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 使用 headless=False 查看浏览器
scraper = NSFCDirectScraper(headless=False)
```

## 发布流程

维护者发布新版本的步骤：

1. 更新版本号（`pyproject.toml` 和 `__init__.py`）
2. 更新 `CHANGELOG.md`
3. 提交并打标签
4. 构建和发布到 PyPI

## 行为准则

- 尊重他人
- 保持友善和专业
- 接受建设性批评
- 关注项目最佳利益

## 许可证

贡献的代码将采用 MIT 许可证。

## 联系方式

- Issues: [GitHub Issues](https://github.com/yourusername/nsfc-spider/issues)
- Email: nsfc-spider@example.com

感谢你的贡献！🎉
