# 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

# 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

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

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

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

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

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

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

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

# 运行测试
python -m pytest tests/

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

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

# 添加更改
git add .

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

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

# ✅ 好的示例
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("目录不存在")  # 使用具体异常类型

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
    """

# 变量和函数：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

# ✅ 好的错误处理
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  # 静默忽略所有错误

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配置

# 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"
            })

# 运行所有测试
pytest

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

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

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

# 标题使用#号

## 二级标题

### 三级标题

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

1. 有序列表
2. 第二项

`代码`使用反引号

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

### 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