感谢您对 OCR Agent 项目的兴趣！本指南将帮助您了解如何贡献代码。
- Python 3.10+
- Git
- pip 或 conda
# 克隆项目
git clone https://github.com/your-repo/ocr-agent.git
cd ocr-agent
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
pip install pytest pytest-cov flake8 black isort# 从 main 分支创建新分支
git checkout main
git pull origin main
git checkout -b feature/your-feature-name分支命名规范：
feature/- 新功能fix/- bug 修复docs/- 文档更新refactor/- 代码重构test/- 测试相关
遵循 PEP 8 规范：
# 格式化代码
black src/ tests/
# 排序导入
isort src/ tests/
# 检查代码风格
flake8 src/ tests/ --max-line-length=100使用类型提示提高代码可读性：
from typing import Optional, List, Dict
from pathlib import Path
import numpy as np
def process_image(
image_path: Path,
output_format: str = "docx"
) -> Dict[str, str]:
"""处理图像并返回结果。
Args:
image_path: 输入图像路径
output_format: 输出格式
Returns:
包含输出文件路径的字典
"""
pass使用 Google 风格的文档字符串：
def repair_image_advanced(
self,
image: np.ndarray,
config: Optional[Config] = None
) -> np.ndarray:
"""高级图像修复，自动选择修复策略。
根据图像质量自动选择超分辨率倍数和去噪方法。
Args:
image: 输入图像（BGR 格式）
config: 配置对象（可选）
Returns:
修复后的图像
Raises:
ValueError: 如果图像格式无效
RuntimeError: 如果修复失败
Example:
>>> module = ImageRepairModule()
>>> repaired = module.repair_image_advanced(image)
"""
pass使用 TDD（测试驱动开发）方法：
import pytest
import numpy as np
from ocr_agent.modules.repair import ImageRepairModule
def test_repair_image_advanced():
"""测试高级修复功能。"""
# 创建测试数据
test_image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
# 执行操作
module = ImageRepairModule()
result = module.repair_image_advanced(test_image)
# 验证结果
assert result is not None
assert result.shape[2] == 3
assert result.dtype == np.uint8
def test_repair_image_advanced_with_config():
"""测试带配置的修复功能。"""
from ocr_agent.core.config import Config
config = Config(repair_upscale_factor=4)
module = ImageRepairModule(upscale_factor=4)
test_image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
result = module.repair_image_advanced(test_image, config)
assert result is not None运行测试：
# 运行所有测试
pytest tests/ -v
# 运行特定测试文件
pytest tests/test_repair.py -v
# 运行特定测试函数
pytest tests/test_repair.py::test_repair_image_advanced -v
# 生成覆盖率报告
pytest tests/ --cov=src/ocr_agent --cov-report=html# 查看更改
git status
git diff
# 暂存更改
git add src/ocr_agent/modules/repair.py tests/test_repair.py
# 提交更改
git commit -m "feat: add advanced image repair with auto strategy selection"提交信息规范：
feat:- 新功能fix:- bug 修复docs:- 文档更新test:- 测试相关refactor:- 代码重构perf:- 性能优化chore:- 其他更改
# 推送分支
git push origin feature/your-feature-name
# 在 GitHub 上创建 Pull Request
# 1. 访问 https://github.com/your-repo/ocr-agent
# 2. 点击 "New Pull Request"
# 3. 选择您的分支
# 4. 填写 PR 描述## 描述
简要描述您的更改。
## 相关 Issue
关闭 #123
## 更改类型
- [ ] 新功能
- [ ] bug 修复
- [ ] 文档更新
- [ ] 代码重构
## 测试
- [ ] 添加了新测试
- [ ] 所有测试通过
- [ ] 覆盖率 > 80%
## 检查清单
- [ ] 代码遵循风格指南
- [ ] 文档已更新
- [ ] 没有新的警告
- [ ] 测试通过- 功能正确性 - 代码是否实现了预期功能
- 代码质量 - 代码是否清晰、可维护
- 测试覆盖 - 是否有充分的测试
- 文档完整 - 是否有清晰的文档
- 性能影响 - 是否有性能问题
- 作者回复审查意见
- 进行必要的修改
- 重新请求审查
- 获得批准后合并
## 描述
清晰简洁地描述 bug。
## 复现步骤
1. 执行...
2. 然后...
3. 看到...
## 预期行为
应该发生什么。
## 实际行为
实际发生了什么。
## 环境
- OS: [e.g. Ubuntu 20.04]
- Python: [e.g. 3.10]
- 版本: [e.g. 0.1.0]
## 日志粘贴相关日志
## 描述
清晰简洁地描述您想要的功能。
## 用例
为什么需要这个功能？
## 建议的解决方案
您建议如何实现？
## 替代方案
是否有其他方式实现？docs/
├── USER_GUIDE.md # 用户指南
├── DOCKER_DEPLOYMENT.md # Docker 部署
├── superpowers/
│ ├── specs/ # 设计文档
│ └── plans/ # 实现计划
└── implementation/ # 实现指南
- 使用 Markdown 格式
- 清晰的标题层级
- 代码示例要完整可运行
- 包含必要的图表和表格
# 运行性能基准测试
pytest tests/test_benchmark.py -v -s
# 使用 cProfile 分析
python -m cProfile -s cumulative src/ocr_agent/pipeline.py- 使用 NumPy 向量化操作
- 避免不必要的复制
- 使用缓存减少重复计算
- 考虑并行处理
遵循 Semantic Versioning：
MAJOR.MINOR.PATCH- 例如：
0.1.0
- 更新版本号
- 更新 CHANGELOG
- 创建 git tag
- 发布到 PyPI
A:
pytest tests/ -v --cov=src/ocr_agent --cov-report=htmlA:
# 使用 pdb
import pdb; pdb.set_trace()
# 或使用 IDE 调试器A:
# 重新创建虚拟环境
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"- 提交 Issue：GitHub Issues
- 讨论：GitHub Discussions
- 邮件：your-email@example.com
感谢您的贡献！🎉