WeChat Article Reader MCP Server

# 贡献指南 感谢您对微信公众号文章读取 MCP 服务器项目的关注！我们欢迎各种形式的贡献，包括但不限于： - 提交 Bug 报告 - 提出新功能建议 - 提交代码改进 - 改进文档 - 分享使用经验 ## 开发环境设置 ### 1. Fork 和克隆项目 1. 在 GitHub 上 Fork 本项目 2. 克隆您的 Fork 到本地： ```bash git clone https://github.com/your-username/mcp-server-wechat.git cd mcp-server-wechat ``` 3. 添加上游仓库： ```bash git remote add upstream https://github.com/original-owner/mcp-server-wechat.git ``` ### 2. 设置开发环境 1. 创建虚拟环境： ```bash python -m venv venv source venv/bin/activate # Linux/macOS # 或 venv\Scripts\activate # Windows ``` 2. 安装依赖： ```bash pip install -r requirements.txt pip install -r requirements-dev.txt # 开发依赖 ``` 3. 安装预提交钩子： ```bash pre-commit install ``` ## 提交代码 ### 1. 创建功能分支 从主分支创建一个新的功能分支： ```bash git checkout main git pull upstream main git checkout -b feature/your-feature-name ``` ### 2. 进行开发 1. 编写代码 2. 添加测试 3. 运行测试确保所有测试通过： ```bash python run_tests.py ``` 4. 确保代码符合项目规范： ```bash black src tests flake8 src tests isort src tests mypy src ``` ### 3. 提交更改 1. 添加更改： ```bash git add . ``` 2. 提交更改，使用清晰的提交信息： ```bash git commit -m "feat: 添加新功能描述" ``` 3. 推送到您的 Fork： ```bash git push origin feature/your-feature-name ``` ### 4. 创建 Pull Request 1. 在 GitHub 上创建 Pull Request 2. 填写 PR 模板 3. 等待代码审查 ## 提交信息规范 我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： ### 格式 ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的脚注] ``` ### 类型 - `feat`: 新功能 - `fix`: 修复 Bug - `docs`: 文档更新 - `style`: 代码格式化（不影响功能） - `refactor`: 代码重构 - `test`: 添加或修改测试 - `chore`: 构建过程或辅助工具的变动 - `perf`: 性能优化 - `ci`: 持续集成相关 ### 示例 ```bash feat: 添加文章搜索功能 - 实现基于关键词的文章搜索 - 添加排序和过滤选项 - 更新 API 文档 Closes #123 ``` ## 代码规范 ### 1. Python 代码风格 - 遵循 PEP 8 代码风格指南 - 使用 Black 进行代码格式化 - 使用 Flake8 进行代码检查 - 使用 isort 进行导入排序 - 使用 MyPy 进行类型检查 ### 2. 文档字符串 所有公共函数、方法和类都应有详细的文档字符串： ```python def fetch_article(url: str, content_formats: List[str] = None) -> Dict[str, Any]: """ 获取微信公众号文章内容 Args: url: 文章URL content_formats: 内容格式列表，可选值：markdown, text Returns: 包含文章内容和元数据的字典 Raises: ValidationError: 当URL无效时 NetworkError: 当网络请求失败时 """ ``` ### 3. 类型注解 所有函数和方法都应有类型注解： ```python def process_data( input_data: Dict[str, Any], config: Optional[Dict[str, Any]] = None ) -> Tuple[bool, str]: """处理输入数据""" ``` ## 测试 ### 1. 测试类型 - **单元测试**：测试单个函数或方法 - **集成测试**：测试多个组件的交互 - **性能测试**：测试系统性能 ### 2. 编写测试 1. 为新功能编写测试 2. 确保测试覆盖率高 3. 使用清晰的测试名称 ```python class TestFetchArticleTool(unittest.TestCase): async def test_execute_success(self): """测试成功获取文章""" tool = FetchArticleTool() result = await tool.execute(url="valid_url") self.assertTrue(result["success"]) async def test_execute_invalid_url(self): """测试无效URL处理""" tool = FetchArticleTool() result = await tool.execute(url="invalid_url") self.assertFalse(result["success"]) self.assertEqual(result["error_code"], "INVALID_URL") ``` ### 3. 运行测试 ```bash # 运行所有测试 python run_tests.py # 只运行单元测试 python run_tests.py --unit # 只运行集成测试 python run_tests.py --integration # 只运行性能测试 python run_tests.py --performance ``` ## 报告 Bug ### 1. 检查现有问题 在提交新 Bug 报告前，请检查是否已有相关问题： 1. 查看 [Issues](https://github.com/original-owner/mcp-server-wechat/issues) 2. 搜索关键词确认问题未被报告 ### 2. 创建 Bug 报告 使用以下模板创建 Bug 报告： ```markdown ## Bug 描述 简要描述 Bug ## 复现步骤 1. 执行操作 A 2. 点击按钮 B 3. 观察现象 C ## 期望行为 描述您期望发生的情况 ## 实际行为 描述实际发生的情况 ## 环境信息 - 操作系统: - Python 版本: - 项目版本: ## 附加信息 添加任何其他有助于解决问题的信息，如日志、截图等 ``` ## 提出新功能建议 ### 1. 检查现有建议 在提交新功能建议前，请检查是否已有相关建议： 1. 查看 [Issues](https://github.com/original-owner/mcp-server-wechat/issues) 2. 搜索关键词确认建议未被提出 ### 2. 创建功能建议 使用以下模板创建功能建议： ```markdown ## 功能描述 简要描述建议的功能 ## 问题背景 描述这个功能要解决的问题 ## 解决方案 描述您设想的解决方案 ## 替代方案 描述您考虑过的其他解决方案 ## 附加信息 添加任何其他相关信息，如参考资料、示例等 ``` ## 代码审查 ### 1. 审查流程 1. 提交 Pull Request 后，项目维护者会进行代码审查 2. 审查者可能会提出修改建议 3. 根据反馈修改代码 4. 所有审查通过后，代码将被合并 ### 2. 审查标准 - 代码是否符合项目规范 - 是否有适当的测试 - 文档是否更新 - 是否有潜在的安全问题 - 是否有性能问题 ### 3. 审查者指南 如果您是代码审查者，请关注以下几点： - 代码可读性和可维护性 - 测试覆盖率和测试质量 - 是否遵循项目最佳实践 - 是否有安全漏洞 - 是否有性能问题 ## 发布流程 ### 1. 版本控制 项目使用语义化版本控制（Semantic Versioning）： - 主版本号：不兼容的 API 修改 - 次版本号：向下兼容的功能性新增 - 修订号：向下兼容的问题修正 ### 2. 发布步骤 1. 更新版本号 2. 更新 CHANGELOG.md 3. 运行完整测试套件 4. 创建 Git 标签 5. 构建分发包 6. 发布到 PyPI ## 社区准则 ### 1. 行为准则 我们致力于为每个人提供友好、安全和欢迎的环境。请遵循以下准则： - 尊重所有参与者 - 使用友好和包容的语言 - 接受建设性批评 - 专注于对社区最有利的事情 - 对其他社区成员表示同理心 ### 2. 沟通渠道 - GitHub Issues：Bug 报告和功能建议 - GitHub Discussions：一般讨论和问答 - Pull Requests：代码贡献和审查 ## 获得帮助 如果您需要帮助或有任何问题，请： 1. 查看 [文档](https://github.com/original-owner/mcp-server-wechat/docs) 2. 搜索 [Issues](https://github.com/original-owner/mcp-server-wechat/issues) 3. 创建新的 Issue 或 Discussion ## 致谢 感谢所有为项目做出贡献的开发者！您的贡献使这个项目变得更好。 --- 再次感谢您的贡献！我们期待您的参与。