Zhiwen Assistant MCP

# 智文助手贡献指南 感谢您对智文助手项目的关注！我们欢迎所有形式的贡献，包括但不限于： - 🐛 报告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*