DeepSearcher开源贡献者指南：代码规范与PR流程

DeepSearcher是一个开源深度研究工具，为私有数据推理提供了强大的替代方案。作为开源项目，我们热忱欢迎开发者参与贡献！本指南将详细介绍如何成为DeepSearcher项目的贡献者，从环境搭建到PR提交的完整流程。🚀

快速入门：贡献者准备工作

在开始贡献代码之前，你需要完成一些基础准备工作。首先克隆项目仓库并建立开发环境：

git clone https://gitcode.com/gh_mirrors/de/deep-searcher
cd deep-searcher

DeepSearcher使用现代化的uv包管理器，确保依赖管理和环境隔离。通过uv sync命令同步依赖并激活虚拟环境，这是项目开发的基础步骤。

开发环境配置详细步骤

uv包管理器设置

DeepSearcher采用uv作为官方包管理器，相比传统工具提供更快的依赖解析和安装速度。配置开发环境的具体命令如下：

uv sync
source .venv/bin/activate

如果需要安装所有可选依赖和开发工具，可以使用：

uv sync --all-extras --dev

依赖管理最佳实践

项目通过pyproject.toml文件管理所有依赖。添加新依赖时使用uv add <package_name>命令，对于可选依赖则使用uv add <package_name> --optional <extra>语法。

代码规范与质量保证

代码格式化和检查

保持一致的代码风格对于项目维护至关重要。DeepSearcher要求所有贡献者在提交PR前运行代码检查和格式化：

# 检查代码风格
make lint

# 自动修复代码风格
make format

我们的CI流水线会在所有拉取请求上自动运行这些检查，确保代码质量和一致性。

测试框架与质量验证

完整的测试套件

DeepSearcher拥有完善的测试体系，覆盖了核心模块：

• 嵌入模块测试：tests/embedding/
• LLM模块测试：tests/llm/
• 加载器测试：tests/loader/
• 向量数据库测试：tests/vector_db/

运行测试的命令

安装测试依赖：

uv sync --all-extras --dev

运行完整测试套件：

uv run pytest tests -v

提交PR的完整流程

五步提交法

1. Fork仓库：从master分支创建你的开发分支
2. 实现变更：按照项目规范编写代码
3. 测试验证：运行测试确保代码质量
4. 文档更新：必要时更新相关文档

• 提交PR：通过平台提交拉取请求

开发者证书要求

所有贡献都需要签署开发者证书（DCO），在提交信息中添加：

Signed-off-by: Your Name <[e-mail]>

项目维护与审核机制

DeepSearcher项目由核心维护团队管理，他们在OWNERS和MAINTAINERS文件中定义。所有PR都会经过维护团队的审核，确保代码符合项目标准。

通过遵循这些指南，你的贡献将更容易被接受，同时也能帮助维护项目的整体质量。我们期待看到你的精彩贡献！🎉

记住：清晰的提交信息、完整的测试覆盖和遵循代码规范是快速通过审核的关键要素。