# 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