diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8ecbf71 --- /dev/null +++ b/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 | +|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| | | + +## 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! + diff --git a/CONTRIBUTING_GUIDELINES.md b/CONTRIBUTING_GUIDELINES.md deleted file mode 100644 index 5b2670a..0000000 --- a/CONTRIBUTING_GUIDELINES.md +++ /dev/null @@ -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`) - ---- diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md new file mode 100644 index 0000000..9350879 --- /dev/null +++ b/CONTRIBUTING_zh.md @@ -0,0 +1,160 @@ +# 如何贡献 + +感谢您对 AgentScope Samples 的关注！AgentScope Samples 提供基于 AgentScope 和 AgentScope Runtime 构建的即用型智能体示例。我们欢迎各种类型的贡献，从新的示例智能体应用到错误修复和文档改进。 + +## 社区 + +通过以下方式与我们联系： + +- **GitHub Discussions**：提问和分享经验（使用**英文**） +- **Discord**：加入我们的 Discord 频道进行实时讨论 +- **钉钉**：中国用户可以加入我们的钉钉群 + +| [Discord](https://discord.gg/eYMpfnkG8h) | DingTalk | +|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| | | + +## 报告问题 + +### 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 做出贡献！ \ No newline at end of file diff --git a/README.md b/README.md index 13de567..01d23b7 100644 --- a/README.md +++ b/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. ------