Merge pull request #5 from Osier-Yi/contribute_file

Contribute file

CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# 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
+
+| [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"> |
+
+## 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
+
+**Note**: If you want to contribute your own example, please also open an issue first to discuss your idea and avoid duplicate work.
+
+
+
+## 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!
+

CONTRIBUTING_GUIDELINES.md

@@ -1,91 +0,0 @@
-# 🤝 Contributing Guide
-
-Welcome to contribute to the AgentScope Sample Agents project! Please follow this guide to ensure efficient collaboration.
-
-
----
-
-# 📁 Directory Structure Requirements
-All examples must be organized by functionality. The structure follows the root README.md layout:
-```bash
-agentscope-samples/
-├── browser_use/                      # Browser automation examples
-│   ├── agent_browser/                # Pure Python browser agent
-│   └── browser_use_fullstack_runtime/ # Full-stack runtime version
-├── deep_research/                    # Deep research examples
-│   ├── agent_deep_research/
-│   └── qwen_langgraph_search_fullstack_runtime/
-├── games/
-│   └── game_werewolves/              # Werewolf game
-├── conversational_agents/            # Conversational applications
-│   ├── chatbot/
-│   └── multiagent_conversation/
-├── functionality/                    # Functional examples
-│   ├── long_term_memory_mem0/
-│   └── stream_printing_messages/
-└── CONTRIBUTING_GUIDELINES.md
-```
-
-
----
-
-# 📥 Submitting a Pull Request (PR)
-
-### 1. **Directory Placement**
-- **Location**:
-  Choose an existing subdirectory (e.g., `browser_use/`、`games/`), or create a new one (update the **Example List** table in the root `README.md`)
-- **File Naming**:  
-  - Example files: `feature_description.py`(如 `chatbot_multi_turn.py`)  
-  - Test files: `test_feature_description.py`
-
-### 2. **Write a Detailed README**
-- **Subdirectory `README.md`**:  
-  Include the following to ensure reproducibility:
-  ```markdown
-  ## Example Name (e.g., Multi-turn Chatbot)
-
-  ### 📌 Description
-  Demonstrates the implementation of multi-turn conversations.
-
-  ### 📦 Dependencies
-  ```bash
-  pip install -r requirements.txt
-  ```
-  
-### 🚀 Run Command
-```bash
-python chatbot_multi_turn.py
-```
-
-
-- **Root `README.md`**:  
-Update the **Example List** table with links to new examples.
-
-### 3. **Dependency Management**
-- **Each Subdirectory Requires `requirements.txt`**:  
-List only dependencies needed for that example:
-
-```txt
-openai==0.27.0
-pandas==2.0.0
-```
-
-### 4. **Code Formatting**
-- **Install `pre-commit`**:  
-```bash
-pip install pre-commit
-pre-commit install
-pre-commit run --all-files
-# Fix any formatting errors (e.g., indentation, line length)
-```
-
-
-### PR Checklist
-- [ ] Example placed in the correct subdirectory (e.g., `browser_use/`、`games/`)
-- [ ] Subdirectory includes `README.md` and `requirements.txt`
-- [ ] Code formatted with `pre-commit`
-- [ ] New test cases cover core functionality
-- [ ] Root `README.md` updated with the new example
-- [ ] PR title is clear (e.g.,  `Add multi-turn chatbot example`)
-
----

CONTRIBUTING_zh.md

@@ -0,0 +1,160 @@
+# 如何贡献
+
+感谢您对 AgentScope Samples 的关注！AgentScope Samples 提供基于 AgentScope 和 AgentScope Runtime 构建的即用型智能体示例。我们欢迎各种类型的贡献，从新的示例智能体应用到错误修复和文档改进。
+
+## 社区
+
+通过以下方式与我们联系：
+
+- **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"> |
+
+## 报告问题
+
+### 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 做出贡献！

README.md

@@ -135,7 +135,7 @@ We welcome contributions such as:
 - Documentation improvements
 - Code contributions
 
-See the [Contributing Guidelines](https://github.com/agentscope-ai/agentscope-samples/blob/main/CONTRIBUTING_GUIDELINES.md) for details.
+See the [Contributing](https://github.com/agentscope-ai/agentscope-samples/blob/main/CONTRIBUTING.md) for details.
 
 ------