Skip to content

CONTRIBUTING_zh.md

Latest commit

 

History

History
317 lines (225 loc) · 11.1 KB

CONTRIBUTING_zh.md

File metadata and controls

317 lines (225 loc) · 11.1 KB

贡献到 AgentScope

欢迎！🎉

感谢开源社区对 AgentScope 项目的关注和支持，作为一个开源项目，我们热烈欢迎并鼓励来自社区的贡献。无论是修复错误、添加新功能、改进文档还是 分享想法，这些贡献都能帮助 AgentScope 变得更好。

如何贡献

为了确保顺利协作并保持项目质量，请在贡献时遵循以下指南：

1. 检查现有计划和问题

在开始贡献之前，请查看我们的开发路线图：

  • 查看 Projects 页面 和 带有 roadmap 标签的 Issues 以了解我们计划的开发任务。

    • 如果存在相关问题 并且标记为未分配或开放状态：

      • 请在该问题下评论，表达您有兴趣参与该任务
      • 这有助于协调开发工作，避免重复工作

    • 如果不存在相关问题：

      • 请创建一个新 issue 用以描述对应的更改或功能
      • 我们的团队将及时进行回复并提供反馈
      • 这有助于我们维护项目路线图并协调社区工作

2. 提交信息格式

AgentScope 遵循 Conventional Commits 规范。这使得提交历史更易读，并能够自动生成更新日志。

格式：

<type>(<scope>): <subject>

类型：

  • feat: 新功能
  • fix: 错误修复
  • docs: 仅文档更改
  • style: 不影响代码含义的更改（空格、格式等）
  • refactor: 既不修复错误也不添加功能的代码更改
  • perf: 提高性能的代码更改
  • ci: 添加缺失的测试或更正现有测试
  • chore: 对构建过程或辅助工具和库的更改

示例：

feat(models): add support for Claude-3 model
fix(agent): resolve memory leak in ReActAgent
docs(readme): update installation instructions
refactor(formatter): simplify message formatting logic
ci(models): add unit tests for OpenAI integration

3. Pull Request 标题格式

Pull Request 标题必须遵循相同的 Conventional Commits 规范：

格式：

<type>(<scope>): <description>

要求：

  • 标题必须以允许的类型之一开头：feat、fix、docs、ci、refactor、test、chore、perf、style、build、revert
  • Scope 是可选的但建议添加
  • Scope 必须是小写 - 只允许小写字母、数字、连字符（-）和下划线（_）
  • 描述应以小写字母开头
  • 保持标题简洁且具有描述性

示例：

✅ 有效：
feat(memory): add redis cache support
fix(agent): resolve memory leak in ReActAgent
docs(tutorial): update installation guide
ci(workflow): add PR title validation
refactor(my-feature): simplify logic

❌ 无效：
feat(Memory): add cache          # Scope 必须是小写
feat(MEMORY): add cache          # Scope 必须是小写
feat(MyFeature): add feature     # Scope 必须是小写

自动化验证：

  • 针对 main 分支的 PR 标题会通过 GitHub Actions 自动验证
  • 标题无效的 PR 将被阻止，直到标题被修正

4. 代码开发指南

a. 提交前检查

在提交代码之前，请运行 pre-commit 钩子以确保代码质量和一致性：

pip install pre-commit
pre-commit install

运行 pre-commit：

# 在所有文件上运行
pre-commit run --all-files

# 安装后，pre-commit 将在 git commit 时自动运行

b. 关于代码中的 Import

AgentScope 遵循懒加载导入原则以最小化资源加载：

  • 推荐做法：仅在实际使用时导入模块 
    def some_function():
    import openai
    # 在此处使用 openai 库

这种方法确保 import agentscope 是一个轻量操作，不会加载不必要的依赖项。

c. 单元测试

  • 所有新功能都必须包含适当的单元测试
  • 在提交 PR 之前确保现有测试通过
  • 使用以下命令运行测试： 
    pytest tests

d. 文档

  • 为新功能更新相关文档
  • 在适当的地方包含代码示例
  • 如果更改影响面向用户的功能，请更新 README.md

贡献类型

添加新的 ChatModel

AgentScope 目前内置支持以下 API 提供商：OpenAI、DashScope、Gemini、Anthropic 和 Ollama。 其中 OpenAIChatModel 的实现还兼容不同的服务提供商，如 vLLM，DeepSeek、SGLang 等。

⚠️ 重要：

添加新的 ChatModel 不仅涉及模型层面的实现，还涉及到其它组件的配合，具体包括：

  • 消息格式化器（formatter）
  • Token 计数器（token counter）
  • Tools API 集成

这意味着添加一个 ChatModel 需要大量的工作来确保其与 AgentScope 生态系统的其他部分无缝集成。 为了更好地专注于智能体能力开发和维护，官方开发团队目前不计划添加对新 API 的支持。 但是当开发者社区有强烈需求时，我们将尽力满足这些需求。

对于一个 ChatModel 类的实现，为了与仓库中 ReActAgent 兼容，所需要实现的组件如下：

必需组件：

  1. ChatModel（位于 agentscope.model 下）：

    from agentscope.model import ChatModelBase


class YourChatModel(ChatModelBase):
    """
    需要考虑的功能包括：
    - 集成 tools API
    - 支持流式和非流式模式，并与 tools API 兼容
    - 支持 tool_choice 参数
    - 考虑支持推理模型
    """

  2. 格式化器类（位于 agentscope.formatter 下）：

    from agentscope.formatter import FormatterBase

class YourModelFormatter(FormatterBase):
    """
    将 `Msg` 对象转换为对应 API 提供商所需的格式。
    如果模型 API 不支持多智能体场景（例如不支持消息中的 name 字段），需要
    为 chatbot 和多智能体场景分别实现两个格式化器类。
    """

  3. Token 计数器（位于 agentscope.token 下，推荐）：

    from agentscope.token import TokenCounterBase

class YourTokenCounter(TokenCounterBase):
    """
    为对应模型实现 token 计数逻辑（推荐实现，非严格要求）。
    """

添加新的智能体

为了确保 AgentScope 中所有的功能实现都是模块化的、可拆卸的和可组合的，agentscope.agent 模块目前仅维护 ReActAgent 类作为核心实现。

在 AgentScope 中，我们遵循示例优先的开发工作流程：

  • 在 examples/ 目录中初步实现新的功能
  • 然后将重要功能抽象和模块化，集成到核心库中
  • 修改 examples/ 目录中的示例以使用新的核心功能

对于专门的或特定领域的智能体，我们建议按照以下组织形式将它们贡献到 examples/agent 目录：

examples/
└── agent/
    ├── main.py
    ├── README.md  # 解释智能体的目的和用法
    └── ... # 其他脚本

添加新的示例

欢迎开源社区贡献新的示例来展示 AgentScope 的各种功能！

📝 关于示例目录：

为了避免仓库变得过于臃肿，我们将 AgentScope 仓库中的 examples/ 目录设计为专注于展示 AgentScope 的功能性。可以把这些示例看作是指导性的参考和功能展示，帮助开发者快速理解 AgentScope 能做什么。

什么样的示例适合放在这里：

  • 清晰地展示 AgentScope 的特定功能或能力
  • 易于理解和跟随学习
  • 作为学习材料或参考实现
  • 专注且简洁

对于更复杂的应用：

对于更加复杂，生产就绪的应用，我们非常期待在 agentscope-samples 仓库中看到您的作品。这个仓库专门用于展示、分享基于 AgentScope 生态搭建的完整的、真实世界的应用。

示例组织方式：

主仓库中的示例根据类型组织到子目录中：

  • examples/agent/ 用于专门的智能体
  • examples/functionality/ 用于展示 AgentScope 的特定功能
  • examples/game/ 用于游戏相关示例
  • examples/evaluation/ 用于评估脚本
  • examples/workflows/ 用于工作流演示
  • examples/tuner/ 用于微调相关示例

示例结构如下：

examples/
└── {example_type}/
    └── {example_name}/
        ├── main.py
        ├── README.md  # 解释示例的目的和用法
        └── ... # 其他脚本

添加新的记忆数据库

AgentScope 的记忆模块目前支持：

  • 内存存储：用于轻量级的临时记忆需求
  • 通过 SQLAlchemy 支持关系型数据库：用于持久化的结构化数据存储
  • NoSQL 数据库：用于灵活的模式需求（例如 Redis）

⚠️ 请注意：

对于关系型数据库，我们使用 SQLAlchemy 作为统一的抽象层。SQLAlchemy 已经支持多种 SQL 数据库，包括 PostgreSQL、MySQL、SQLite、Oracle、Microsoft SQL Server 等。

因此，为了保持 AgentScope 代码的整洁，目前不接受为 SQLAlchemy 已经支持的关系型数据库单独实现新的支持。 如果您需要支持特定的关系型数据库，请确保通过现有的 SQLAlchemy 集成来实现。

如果您希望贡献新的记忆数据库实现，请考虑以下几点：

  1. 对于关系型数据库：使用现有的 SQLAlchemy 集成。

  2. 对于 NoSQL 数据库：如果您要添加对新 NoSQL 数据库的支持（例如 MongoDB、Cassandra），请：

    • 实现一个扩展适当基类的新记忆类
    • 添加全面的单元测试
    • 相应地更新文档

Do's and Don'ts

✅ DO

  • 从小处着手：从小的、可管理的贡献开始
  • 及早沟通：在实现主要功能之前进行讨论
  • 编写测试：确保代码经过充分测试
  • 添加代码注释：帮助他人理解贡献内容
  • 遵循提交约定：使用约定式提交消息
  • 保持尊重：遵守我们的行为准则
  • 提出问题：如果不确定某事，请提问！

❌ DON'T

  • 不要用大型 PR 让我们措手不及：大型的、意外的 PR 难以审查，并且可能与项目目标不一致。在进行重大更改之前，请务必先开启一个问题进行讨论
  • 不要忽略 CI 失败：修复持续集成标记的任何问题
  • 不要混合关注点：保持 PR 专注于单一功能的实现或修复
  • 不要忘记更新测试：功能的更改应反映在测试中
  • 不要破坏现有 API：在可能的情况下保持向后兼容性，或清楚地记录破坏性更改
  • 不要添加不必要的依赖项：保持核心库轻量级
  • 不要绕过懒加载导入原则：确保 AgentScope 在导入阶段不至于臃肿

获取帮助

如果需要帮助或有疑问：

  • 💬 开启一个 Discussion
  • 🐛 通过 Issues 报告错误
  • 📧 通过钉钉交流群或 Discord 联系开发团队（链接在 README.md 中）

感谢为 AgentScope 做出贡献！🚀