# 贡献指南 / Contributing Guide
感谢您对 Lanhu MCP Server 项目的关注！我们欢迎任何形式的贡献。
Thank you for your interest in the Lanhu MCP Server project! We welcome all forms of contributions.
[English](#english) | [简体中文](#简体中文)
---
## 简体中文
### 🤝 如何贡献
#### 报告 Bug
如果您发现了 Bug，请通过 [GitHub Issues](https://github.com/dsphper/lanhu-mcp/issues) 提交,并包含以下信息：
- **Bug 描述**：清晰简洁的描述
- **复现步骤**：详细的复现步骤
- **期望行为**：您期望发生什么
- **实际行为**：实际发生了什么
- **环境信息**：
- 操作系统和版本
- Python 版本
- 依赖版本（从 `pip list` 获取）
- **相关日志**：错误堆栈或日志信息
- **截图**（如适用）
#### 提出新功能
如果您有新功能的想法：
1. 先查看 [Issues](https://github.com/dsphper/lanhu-mcp/issues) 确认是否已有相关讨论
2. 创建一个新的 Feature Request Issue
3. 详细描述功能的使用场景和预期效果
4. 如果可能，提供实现思路
#### 提交代码
**准备工作：**
```bash
# 1. Fork 本仓库到您的账号
# 2. 克隆您的 Fork
git clone https://github.com/YOUR_USERNAME/lanhu-mcp.git
cd lanhu-mcp
# 3. 添加上游仓库
git remote add upstream https://github.com/dsphper/lanhu-mcp.git
# 4. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 5. 安装开发依赖
pip install -r requirements.txt
pip install black flake8 pytest pytest-cov
```
**开发流程：**
```bash
# 1. 创建功能分支
git checkout -b feature/your-feature-name
# 2. 进行开发
# ... 编写代码 ...
# 3. 代码格式化
black lanhu_mcp_server.py
# 4. 代码检查
flake8 lanhu_mcp_server.py --max-line-length=120
# 5. 运行测试（如果有）
pytest tests/ -v
# 6. 提交更改
git add .
git commit -m "feat: add amazing feature"
# 7. 推送到您的 Fork
git push origin feature/your-feature-name
# 8. 在 GitHub 上创建 Pull Request
```
**提交信息规范：**
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
- `feat:` 新功能
- `fix:` Bug 修复
- `docs:` 文档更新
- `style:` 代码格式调整（不影响功能）
- `refactor:` 重构（既不是新功能也不是 Bug 修复）
- `perf:` 性能优化
- `test:` 测试相关
- `chore:` 构建过程或辅助工具的变动
**示例：**
```bash
feat: add support for Figma design import
fix: resolve cache invalidation issue when version changes
docs: update README with new configuration options
refactor: extract message store logic into separate class
```
### 📋 代码规范
#### Python 代码风格
- 遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 规范
- 使用 Black 进行自动格式化（行长度 120）
- 函数和类必须有文档字符串（docstring）
- 复杂逻辑需要添加注释
**示例：**
```python
async def fetch_metadata(url: str, use_cache: bool = True) -> dict:
"""
从蓝湖URL获取元数据
Args:
url: 蓝湖文档URL
use_cache: 是否使用缓存，默认为True
Returns:
包含元数据的字典
Raises:
ValueError: URL格式不正确时抛出
"""
# 实现代码...
```
#### 命名约定
- 类名：`PascalCase` (例如：`MessageStore`, `LanhuExtractor`)
- 函数名：`snake_case` (例如：`get_pages_list`, `send_notification`)
- 常量：`UPPER_CASE` (例如：`BASE_URL`, `DEFAULT_COOKIE`)
- 私有成员：前缀 `_` (例如：`_load_cache`, `_metadata_cache`)
#### 错误处理
- 使用明确的异常类型
- 提供有意义的错误消息
- 记录错误日志
```python
try:
response = await self.client.get(url)
response.raise_for_status()
except httpx.HTTPStatusError as e:
logger.error(f"HTTP error occurred: {e}")
raise ValueError(f"Failed to fetch data from {url}: {e.response.status_code}")
```
### 🧪 测试
如果您添加了新功能，请编写相应的测试：
```python
# tests/test_message_store.py
import pytest
from lanhu_mcp_server import MessageStore
def test_save_message():
"""测试消息保存功能"""
store = MessageStore("test_project")
msg = store.save_message(
summary="Test message",
content="Test content",
author_name="Test User",
author_role="Developer"
)
assert msg["id"] == 1
assert msg["summary"] == "Test message"
assert msg["author_name"] == "Test User"
```
### 📖 文档
如果您更改了 API 或添加了新功能，请更新相关文档：
- 更新 README.md
- 更新工具的 docstring
- 添加使用示例
- 更新英文文档（README_EN.md）
### 🔍 代码审查
所有 Pull Request 都需要经过代码审查。请确保：
- ✅ 代码通过所有 CI 检查
- ✅ 遵循项目代码规范
- ✅ 有完整的提交信息
- ✅ 有相关的测试（如适用）
- ✅ 文档已更新（如适用）
### ⚠️ 安全注意事项
- **不要**提交包含真实 Cookie 的代码
- **不要**提交包含真实 API 密钥的代码
- **不要**提交包含用户隐私数据的代码
- 使用环境变量或配置文件处理敏感信息
- 在提交前检查 `.gitignore` 是否正确配置
---
## English
### 🤝 How to Contribute
#### Report Bugs
If you find a bug, please submit it through [GitHub Issues](https://github.com/dsphper/lanhu-mcp/issues) with the following information:
- **Bug Description**: Clear and concise description
- **Reproduction Steps**: Detailed steps to reproduce
- **Expected Behavior**: What you expected to happen
- **Actual Behavior**: What actually happened
- **Environment Info**:
- OS and version
- Python version
- Dependencies versions (from `pip list`)
- **Related Logs**: Error stack or log information
- **Screenshots** (if applicable)
#### Suggest New Features
If you have ideas for new features:
1. Check [Issues](https://github.com/dsphper/lanhu-mcp/issues) to see if there's already a discussion
2. Create a new Feature Request Issue
3. Describe the use case and expected behavior in detail
4. Provide implementation ideas if possible
#### Submit Code
**Preparation:**
```bash
# 1. Fork this repository to your account
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/lanhu-mcp.git
cd lanhu-mcp
# 3. Add upstream repository
git remote add upstream https://github.com/dsphper/lanhu-mcp.git
# 4. Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 5. Install development dependencies
pip install -r requirements.txt
pip install black flake8 pytest pytest-cov
```
**Development Workflow:**
```bash
# 1. Create feature branch
git checkout -b feature/your-feature-name
# 2. Develop
# ... write code ...
# 3. Format code
black lanhu_mcp_server.py
# 4. Code linting
flake8 lanhu_mcp_server.py --max-line-length=120
# 5. Run tests (if available)
pytest tests/ -v
# 6. Commit changes
git add .
git commit -m "feat: add amazing feature"
# 7. Push to your fork
git push origin feature/your-feature-name
# 8. Create Pull Request on GitHub
```
**Commit Message Convention:**
We follow [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation update
- `style:` Code style change (no functionality change)
- `refactor:` Refactoring (neither feature nor bug fix)
- `perf:` Performance optimization
- `test:` Test-related
- `chore:` Build process or auxiliary tool changes
### 📋 Code Standards
#### Python Code Style
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/)
- Use Black for auto-formatting (line length 120)
- Functions and classes must have docstrings
- Add comments for complex logic
#### Naming Conventions
- Class names: `PascalCase` (e.g., `MessageStore`, `LanhuExtractor`)
- Function names: `snake_case` (e.g., `get_pages_list`, `send_notification`)
- Constants: `UPPER_CASE` (e.g., `BASE_URL`, `DEFAULT_COOKIE`)
- Private members: prefix `_` (e.g., `_load_cache`, `_metadata_cache`)
### 🧪 Testing
If you add new features, please write corresponding tests.
### 📖 Documentation
If you change APIs or add new features, please update relevant documentation.
### ⚠️ Security Considerations
- **DO NOT** commit code with real Cookies
- **DO NOT** commit code with real API keys
- **DO NOT** commit code with user privacy data
- Use environment variables or config files for sensitive information
- Check `.gitignore` is properly configured before committing
---
## 📞 Questions?
If you have any questions, feel free to:
- Open a [Discussion](https://github.com/dsphper/lanhu-mcp/discussions)
- Join our community chat (if available)
- Email us at: dsphper@gmail.com
Thank you for contributing! 🎉
<!-- Last checked: 2026-01-31 12:43 -->
