# 如何贡献

感谢您对 AgentScope Samples 的关注！AgentScope Samples 提供基于 AgentScope 和 AgentScope Runtime 构建的即用型智能体示例。我们欢迎各种类型的贡献，从新的示例智能体应用到错误修复和文档改进。

## 报告问题

### Bug

报告 bug 前，请先测试最新版本并搜索已有问题。提交 bug 报告时，请包括：

- 清晰的问题描述和复现步骤
- 代码/错误信息
- 环境详情（操作系统、Python 版本、AgentScope 版本）
- 受影响的示例

### 安全问题

通过[阿里巴巴安全响应中心（ASRC）](https://security.alibaba.com/)报告安全问题。

## 请求新功能

如果您希望有一个在 AgentScope Samples 中不存在的功能或新类型的示例，请在 GitHub 上开一个功能请求 issue 来描述：

- 该功能或示例及其目的
- 它应该如何工作
- 它解决了什么问题或演示了什么用例

**注意**：如果您想贡献自己的示例，也请先开一个 issue 讨论您的想法，避免重复工作。



## 贡献代码

### 设置

1. **Fork 并克隆**仓库
2. **安装 pre-commit**：
   ```bash
   pip install pre-commit
   pre-commit install
   ```
3. **创建分支**：
   ```bash
   git checkout -b feature/your-sample-name
   ```

### 创建新示例

#### 目录结构

选择合适的类别（`browser_use/`、`conversational_agents/`、`deep_research/`、`evaluation/`、`functionality/`、`games/`）并创建示例目录。如果不存在合适的类别，您可以在 pull request 中提议一个新类别。

**简单示例：**
```
your_sample_name/
├── README.md
├── main.py
├── your_agent.py
└── requirements.txt
```

**全栈示例**（使用 `_fullstack_runtime` 后缀）：
```
your_sample_fullstack_runtime/
├── README.md
├── backend/
│   ├── requirements.txt
│   └── ...
└── frontend/
    ├── package.json
    └── ...
```

#### README.md 要求（强制）

您的 README.md **必须**包含：

1. **标题和描述**：示例演示的内容

2. **项目结构**（强制）：带说明的文件树
   ```markdown
   ## 🌳 项目结构

   \`\`\`
   .
   ├── README.md                 # 文档
   ├── main.py                   # 入口点
   ├── agent.py                  # 智能体实现
   └── requirements.txt          # 依赖项
   \`\`\`
   ```

3. **前置要求**：Python 版本、API 密钥等

4. **安装**：
   ```bash
   pip install -r requirements.txt
   ```

5. **设置**：环境变量或配置步骤

6. **使用方法**：如何运行示例
   ```bash
   python main.py
   ```

#### 独立安装

每个示例需包含独立的 `requirements.txt` 文件，列出所有必需的依赖项，以确保可独立安装和运行，不依赖其他示例。

#### 代码质量

我们使用 pre-commit hooks 强制执行：

- **Black**：代码格式化（行长度 79）
- **flake8** 和 **pylint**：代码检查
- **mypy**：类型检查

编写示例代码时：
- 添加清晰的注释，遵循现有代码风格
- 为函数签名添加类型提示
- 保持代码简单，专注于演示特定功能

确保通过所有检查：
```bash
pre-commit run --all-files
```

### 提交您的贡献

1. **提交**时使用清晰的消息：
   ```bash
   git commit -m "Add: new browser automation sample"
   ```
   使用前缀：`Add:`、`Fix:`、`Update:`、`Doc:`

2. **推送**到您的 fork：
   ```bash
   git push origin feature/your-sample-name
   ```

3. **创建 Pull Request**，包含：
   - 示例演示内容的清晰描述
   - 相关问题的引用（例如 "Closes #123"）

4. **代码审查**：处理维护者的反馈

感谢您为 AgentScope Samples 做出贡献！如有任何问题，欢迎通过以下方式与我们联系：

- **GitHub Discussions**：提问和分享经验（使用**英文**）
- **Discord**：加入我们的 Discord 频道进行实时讨论
- **钉钉**：中国用户可以加入我们的钉钉群

| [Discord](https://discord.gg/eYMpfnkG8h)                                                                                         | DingTalk                                                                                                                          |
|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i1/O1CN01LxzZha1thpIN2cc2E_!!6000000005934-2-tps-497-477.png" width="100" height="100"> |