add how to contribute file

2025-10-27 11:44:20 +08:00
parent bf18b100ff
commit 64677848ab
2 changed files with 309 additions and 0 deletions
--- a/CONTRIBUTING_en.md
+++ b/CONTRIBUTING_en.md
@@ -0,0 +1,155 @@
+# How to Contribute
+
+Thank you for your interest in AgentScope Samples! AgentScope Samples provides ready-to-use agent examples built on AgentScope and AgentScope Runtime. We welcome all types of contributions, from new sample agent applications to bug fixes and documentation improvements.
+
+## Community
+
+Connect with us through:
+
+- **GitHub Discussions**: Ask questions and share experiences (in **English**)
+- **Discord**: Join our Discord channel for real-time discussions
+- **DingTalk**: Chinese users can join our DingTalk group
+
+## Reporting Issues
+
+### Bugs
+
+Before reporting a bug, please test with the latest version and search existing issues. When submitting a bug report, include:
+
+- Clear description of the issue and reproduction steps
+- Code/error messages
+- Environment details (OS, Python version, AgentScope version)
+- Affected examples
+
+### Security Issues
+
+Report security issues through [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/).
+
+## Requesting New Features
+
+If you'd like a feature or new type of example that doesn't exist in AgentScope Samples, please open a feature request issue on GitHub describing:
+
+- The feature or example and its purpose
+- How it should work
+- What problem it solves or what use case it demonstrates
+
+
+
+## Contributing Code
+
+### Setup
+
+1. **Fork and clone** the repository
+2. **Install pre-commit**:
+   ```bash
+   pip install pre-commit
+   pre-commit install
+   ```
+3. **Create a branch**:
+   ```bash
+   git checkout -b feature/your-sample-name
+   ```
+
+### Creating New Examples
+
+#### Directory Structure
+
+Choose an appropriate category (`browser_use/`, `conversational_agents/`, `deep_research/`, `evaluation/`, `functionality/`, `games/`) and create your example directory. If a suitable category doesn't exist, you can propose a new one in your pull request.
+
+**Simple example:**
+```
+your_sample_name/
+├── README.md
+├── main.py
+├── your_agent.py
+└── requirements.txt
+```
+
+**Full-stack example** (use `_fullstack_runtime` suffix):
+```
+your_sample_fullstack_runtime/
+├── README.md
+├── backend/
+│   ├── requirements.txt
+│   └── ...
+└── frontend/
+    ├── package.json
+    └── ...
+```
+
+#### README.md Requirements (Mandatory)
+
+Your README.md **must** include:
+
+1. **Title and Description**: What the example demonstrates
+
+2. **Project Structure** (mandatory): File tree with descriptions
+   ```markdown
+   ## 🌳 Project Structure
+   
+   \`\`\`
+   .
+   ├── README.md                 # Documentation
+   ├── main.py                   # Entry point
+   ├── agent.py                  # Agent implementation
+   └── requirements.txt          # Dependencies
+   \`\`\`
+   ```
+
+3. **Prerequisites**: Python version, API keys, etc.
+
+4. **Installation**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+5. **Setup**: Environment variables or configuration steps
+
+6. **Usage**: How to run the example
+   ```bash
+   python main.py
+   ```
+
+#### Standalone Installation
+
+Each example must include a standalone `requirements.txt` file listing all necessary dependencies to ensure it can be installed and run independently without relying on other examples.
+
+#### Code Quality
+
+We enforce the following using pre-commit hooks:
+
+- **Black**: Code formatting (line length 79)
+- **flake8** and **pylint**: Code linting
+- **mypy**: Type checking
+
+When writing example code:
+- Add clear comments and follow existing code style
+- Add type hints to function signatures
+- Keep code simple and focused on demonstrating specific features
+
+Ensure all checks pass:
+```bash
+pre-commit run --all-files
+```
+
+### Submitting Your Contribution
+
+1. **Commit** with clear messages:
+   ```bash
+   git commit -m "Add: new browser automation sample"
+   ```
+   Use prefixes: `Add:`, `Fix:`, `Update:`, `Doc:`
+
+2. **Push** to your fork:
+   ```bash
+   git push origin feature/your-sample-name
+   ```
+
+3. **Create a Pull Request** including:
+   - Clear description of what the example demonstrates
+   - References to related issues (e.g., "Closes #123")
+
+4. **Code Review**: Address feedback from maintainers
+
+Thank you for contributing to AgentScope Samples!
+
--- a/CONTRIBUTING_zh.md
+++ b/CONTRIBUTING_zh.md
@@ -0,0 +1,154 @@
+# 如何贡献
+
+感谢您对 AgentScope Samples 的关注！AgentScope Samples 提供基于 AgentScope 和 AgentScope Runtime 构建的即用型智能体示例。我们欢迎各种类型的贡献，从新的示例智能体应用到错误修复和文档改进。
+
+## 社区
+
+通过以下方式与我们联系：
+
+- **GitHub Discussions**：提问和分享经验（使用**英文**）
+- **Discord**：加入我们的 Discord 频道进行实时讨论
+- **钉钉**：中国用户可以加入我们的钉钉群
+
+## 报告问题
+
+### Bug
+
+报告 bug 前，请先测试最新版本并搜索已有问题。提交 bug 报告时，请包括：
+
+- 清晰的问题描述和复现步骤
+- 代码/错误信息
+- 环境详情（操作系统、Python 版本、AgentScope 版本）
+- 受影响的示例
+
+### 安全问题
+
+通过[阿里巴巴安全响应中心（ASRC）](https://security.alibaba.com/)报告安全问题。
+
+## 请求新功能
+
+如果您希望有一个在 AgentScope Samples 中不存在的功能或新类型的示例，请在 GitHub 上开一个功能请求 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 做出贡献！