# 智文助手贡献指南

感谢您对智文助手项目的关注！我们欢迎所有形式的贡献，包括但不限于：

- 🐛 报告Bug
- 💡 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复
- ⭐ 添加新功能

## 📋 目录

- [开始之前](#开始之前)
- [开发环境搭建](#开发环境搭建)
- [贡献流程](#贡献流程)
- [代码规范](#代码规范)
- [测试指南](#测试指南)
- [文档贡献](#文档贡献)
- [提交规范](#提交规范)
- [社区行为准则](#社区行为准则)

## 🚀 开始之前

### 1. 了解项目

在开始贡献之前，建议您：

- 📖 阅读 [项目README](README.md) 了解项目概况
- 🛠️ 查看 [使用指南](USAGE.md) 了解功能特性
- 🔧 阅读 [API文档](API.md) 了解技术实现

### 2. 选择贡献方式

| 贡献类型 | 说明 | 难度 |
|---------|------|--------|
| 报告Bug | 发现问题并详细描述 | ⭐ |
| 改进文档 | 完善文档内容 | ⭐⭐ |
| 代码修复 | 修复已知问题 | ⭐⭐⭐ |
| 添加功能 | 实现新功能 | ⭐⭐⭐⭐ |
| 重构优化 | 改进代码结构 | ⭐⭐⭐⭐⭐ |

## 🛠️ 开发环境搭建

### 1. Fork和克隆项目

```bash
# 1. Fork 项目到您的GitHub账户
# 访问 https://github.com/kscz0000/Zhiwen-Assistant-MCP 点击 "Fork"

# 2. 克隆您的Fork
git clone https://github.com/YOUR_USERNAME/Zhiwen-Assistant-MCP.git

# 3. 添加原始仓库为上游
cd Zhiwen-Assistant-MCP
git remote add upstream https://github.com/kscz0000/Zhiwen-Assistant-MCP.git
```

### 2. 设置开发环境

```bash
# 1. 创建虚拟环境
python -m venv zhiwen-dev

# 2. 激活虚拟环境
# Windows
zhiwen-dev\Scripts\activate
# macOS/Linux
source zhiwen-dev/bin/activate

# 3. 安装开发依赖
pip install -r requirements-dev.txt

# 4. 安装pre-commit钩子
pre-commit install
```

### 3. 验证环境

```bash
# 运行测试套件
python -m pytest tests/

# 检查代码质量
python -m flake8 .

# 运行类型检查
python -m mypy folder_documentation_mcp.py
```

## 🔄 贡献流程

### 1. 创建Issue（可选但推荐）

对于较大的更改，建议先创建Issue讨论：

- 🐛 Bug报告：使用 [Bug模板](.github/ISSUE_TEMPLATE/bug_report.md)
- 💡 功能请求：使用 [功能请求模板](.github/ISSUE_TEMPLATE/feature_request.md)
- 📝 文档改进：使用 [文档模板](.github/ISSUE_TEMPLATE/documentation.md)

### 2. 创建功能分支

```bash
# 同步主分支
git checkout main
git pull upstream main

# 创建功能分支
git checkout -b feature/amazing-feature

# 或修复分支
git checkout -b fix/bug-description
```

### 3. 开发和测试

```bash
# 进行开发
# ... 编写代码 ...

# 运行测试
python -m pytest tests/

# 检查代码规范
python -m flake8 your_file.py

# 检查类型注解
python -m mypy your_file.py
```

### 4. 提交更改

```bash
# 添加更改
git add .

# 提交（遵循提交规范）
git commit -m "feat: add amazing new feature"

# 推送到您的Fork
git push origin feature/amazing-feature
```

### 5. 创建Pull Request

1. 访问您的Fork页面
2. 点击 "New Pull Request"
3. 选择正确的分支
4. 填写PR模板
5. 等待代码审查

## 📝 代码规范

### 1. Python代码规范

我们遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 规范：

```python
# ✅ 好的示例
import os
from typing import List, Dict, Optional

def generate_readme_files(
    root_dir: str,
    exclude_dirs: Optional[List[str]] = None,
    force_update: bool = False
) -> Dict[str, int]:
    """
    为项目中的每个主要文件夹生成中文README.md文件
    
    Args:
        root_dir: 项目根目录路径
        exclude_dirs: 排除的目录列表
        force_update: 是否强制更新现有README.md文件
        
    Returns:
        包含生成统计信息的字典
    """
    if not os.path.exists(root_dir):
        raise ValueError(f"目录不存在: {root_dir}")
    
    # 实现代码...

# ❌ 不好的示例
import os, sys, typing

def generate_readme_files(root_dir, exclude_dirs=None, force_update=False):
    # 缺少类型注解
    # 缺少文档字符串
    if not os.path.exists(root_dir):
        raise Exception("目录不存在")  # 使用具体异常类型
```

### 2. 文档字符串规范

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

```python
def example_function(param1: str, param2: int) -> bool:
    """函数功能简述。
    
    详细描述函数的功能和使用场景。
    
    Args:
        param1: 参数1的描述
        param2: 参数2的描述
        
    Returns:
        返回值描述
        
    Raises:
        ValueError: 当参数无效时
        PermissionError: 当权限不足时
        
    Example:
        >>> result = example_function("test", 123)
        >>> print(result)
        True
    """
```

### 3. 命名规范

```python
# 变量和函数：snake_case
current_directory = "/path/to/dir"
def get_file_list() -> List[str]:

# 类名：PascalCase
class DocumentationGenerator:
    def __init__(self):
        self.config = {}

# 常量：UPPER_SNAKE_CASE
MAX_FILE_SIZE = 1024 * 1024  # 1MB
DEFAULT_ENCODING = "utf-8"

# 私有方法：前缀下划线
def _internal_helper() -> None:
    pass
```

### 4. 错误处理

```python
# ✅ 好的错误处理
try:
    result = process_file(file_path)
except FileNotFoundError:
    logger.error(f"文件不存在: {file_path}")
    return {}
except PermissionError:
    logger.error(f"权限不足: {file_path}")
    raise
except Exception as e:
    logger.error(f"处理文件时发生未知错误: {e}")
    raise

# ❌ 不好的错误处理
try:
    result = process_file(file_path)
except:
    pass  # 静默忽略所有错误
```

## 🧪 测试指南

### 1. 测试结构

```
tests/
├── unit/                   # 单元测试
│   ├── test_readme.py
│   ├── test_mindmap.py
│   └── test_validation.py
├── integration/             # 集成测试
│   ├── test_full_workflow.py
│   └── test_mcp_integration.py
├── fixtures/               # 测试数据
│   └── sample_projects/
└── conftest.py            # pytest配置
```

### 2. 编写测试

```python
# tests/unit/test_readme.py
import pytest
from folder_documentation_mcp import generate_readme_files

class TestReadmeGeneration:
    """README生成功能测试"""
    
    def test_generate_readme_success(self, tmp_path):
        """测试成功生成README"""
        # 准备测试数据
        test_dir = tmp_path / "test_project"
        test_dir.mkdir()
        (test_dir / "src").mkdir()
        (test_dir / "docs").mkdir()
        
        # 执行测试
        result = generate_readme_files({
            "root_dir": str(test_dir),
            "force_update": True
        })
        
        # 验证结果
        assert result["success"] is True
        assert result["generated_count"] >= 1
        assert (test_dir / "README.md").exists()
        assert (test_dir / "src" / "README.md").exists()
    
    def test_generate_readme_invalid_path(self):
        """测试无效路径处理"""
        with pytest.raises(ValueError):
            generate_readme_files({
                "root_dir": "/nonexistent/path"
            })
```

### 3. 运行测试

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

# 运行特定测试文件
pytest tests/unit/test_readme.py

# 运行带覆盖率报告的测试
pytest --cov=folder_documentation_mcp --cov-report=html

# 运行特定标记的测试
pytest -m unit          # 只运行单元测试
pytest -m integration   # 只运行集成测试
```

## 📖 文档贡献

### 1. 文档类型

| 文档类型 | 路径 | 说明 |
|---------|------|------|
| API文档 | docs/api/ | 接口说明 |
| 用户指南 | docs/guide/ | 使用说明 |
| 开发文档 | docs/development/ | 开发指南 |
| 部署文档 | docs/deployment/ | 部署说明 |

### 2. 文档格式

使用Markdown格式，遵循以下规范：

```markdown
# 标题使用#号

## 二级标题

### 三级标题

- 使用列表
  - 子列表项1
  - 子列表项2

1. 有序列表
2. 第二项

`代码`使用反引号

```python
# 代码块指定语言
def example():
    pass
```

> 引用使用大于号

[链接文本](链接地址)

![图片描述](图片地址)

| 表格标题1 | 表格标题2 |
|---------|---------|
| 内容1    | 内容2    |
```

### 3. 文档审查

提交文档前请检查：

- ✅ 标题层级正确
- ✅ 链接可点击
- ✅ 代码可运行
- ✅ 图片显示正常
- ✅ 表格格式正确
- ✅ 拼写和语法正确

## 📋 提交规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

### 提交类型

| 类型 | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug修复 |
| `docs` | 文档更新 |
| `style` | 代码格式调整 |
| `refactor` | 代码重构 |
| `test` | 测试相关 |
| `chore` | 构建工具、依赖更新 |

### 提交格式

```
<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]
```

### 示例

```bash
# 好的提交
feat(readme): 添加自定义模板支持
fix(validation): 修复路径遍历漏洞
docs(api): 更新README生成API文档
refactor(config): 重构配置加载逻辑

# 不好的提交
update readme
fix bug
add stuff
```

## 🤝 社区行为准则

### 我们的承诺

为了营造开放和友好的环境，我们承诺：

- 尊重所有参与者
- 使用友好和包容的语言
- 接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心

### 不当行为

以下行为不被接受：

- 使用性别化语言或图像
- 人身攻击或政治攻击
- 公开或私下骚扰
- 未经明确许可发布他人信息
- 其他在专业环境中可能认为不当的行为

### 执行

项目维护者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、wiki编辑、问题和其他贡献。

## 🏆 贡献者

我们感谢所有为智文助手做出贡献的开发者！

### 贡献方式

- 💻 代码贡献
- 📖 文档改进
- 🐛 Bug报告
- 💡 功能建议
- 🌟 推广项目
- 🙋‍♂️ 帮助其他用户

### 贡献者列表

贡献者将自动添加到 [CONTRIBUTORS.md](CONTRIBUTORS.md) 文件中。

## 📞 联系方式

如果您有任何问题或建议，请通过以下方式联系：

- 📧 Gmail: byilb3619b@gmail.com
- 📧 QQ邮箱: 1715635335@qq.com
- 📱 微信公众号: ASI-CN
- 💬 讨论: [GitHub Discussions](https://github.com/kscz0000/Zhiwen-Assistant-MCP/discussions)
- 🐛 问题: [GitHub Issues](https://github.com/kscz0000/Zhiwen-Assistant-MCP/issues)

---

感谢您的贡献！🎉

*更新时间: 2025-12-19*