贡献指南

如何为 browseruse-bench 项目做出贡献

欢迎为 browseruse-bench 项目做出贡献！本指南将帮助你了解如何参与项目开发。

​

开发环境设置

1. Fork 仓库

   在 GitHub 上 Fork browseruse-bench 仓库

2. 克隆代码

   git clone https://github.com/your-username/browseruse-bench.git
   cd browseruse-bench
   
3. 安装依赖

   # 使用 uv（推荐）
   uv sync --all-extras
   
   # 或使用 pip
   pip install -e ".[all,dev]"
   
4. 创建分支

   git checkout -b feature/your-feature-name
   

​

贡献类型

​

添加新 Agent

1. 在 agents/ 目录下创建新 Agent 目录
2. 实现 Agent 接口
3. 提交 config.yaml.example，config.yaml 保持本地
4. 更新文档

详见 添加新 Agent

​

添加新 Benchmark

1. 在 benchmarks/ 目录下创建新 Benchmark 目录
2. 准备任务数据和 data_info.json
3. 实现评估器（可选）
4. 更新文档

详见 自定义 Benchmark

​

修复 Bug

1. 创建 Issue 描述问题
2. 提交包含修复的 PR
3. 确保测试通过

​

改进文档

1. 修改 docs/ 目录下的文档
2. 提交 PR

​

添加新 Agent

​

目录结构

agents/
└── YourAgent/
    ├── config.yaml.example  # 提交的示例配置
    ├── config.yaml          # 本地配置（忽略提交）
    ├── requirements.txt # 依赖（可选）
    └── run.py           # 入口脚本（可选）

请提交 config.yaml.example，将 config.yaml 保持为本地文件以保存密钥。

​

实现接口

新 Agent 需要实现以下接口：

class YourAgent:
    def __init__(self, config: dict):
        """初始化 Agent"""
        pass
    
    async def execute_task(self, task: dict) -> dict:
        """
        执行任务
        
        Args:
            task: 任务字典，包含 task_id, task 等字段
            
        Returns:
            结果字典，包含 action_history, metrics 等
        """
        pass

​

注册 Agent

在 browseruse_bench/agents/__init__.py 中注册：

AGENTS = {
    "browser-use": ...,
    "Agent-TARS": ...,
    "YourAgent": {
        "module": "agents.YourAgent.run:YourAgent",
        "config_file": "agents/YourAgent/config.yaml"
    }
}

​

代码规范

​

格式化

# 使用 ruff 格式化
ruff format .

# 检查代码风格
ruff check .

​

类型检查

# 使用 mypy 进行类型检查
mypy browseruse_bench

​

测试

# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_eval.py -v

​

提交 PR

1. 确保测试通过

   pytest tests/
   ruff check .
   
2. 提交更改

   git add .
   git commit -m "feat: add your feature description"
   
3. 推送分支

   git push origin feature/your-feature-name
   
4. 创建 PR

   在 GitHub 上创建 Pull Request，描述你的更改

​

Commit 规范

使用 Conventional Commits 格式：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• refactor: 代码重构
• test: 添加测试
• chore: 其他更改

示例：

feat: add WebArena benchmark support
fix: resolve timeout issue in browser-use agent
docs: update quickstart guide