CONTRIBUTING_zh.md
感谢开源社区对 AgentScope 项目的关注和支持，作为一个开源项目，我们热烈欢迎并鼓励来自社区的贡献。无论是修复错误、添加新功能、改进文档还是 分享想法，这些贡献都能帮助 AgentScope 变得更好。
为了确保顺利协作并保持项目质量，请在贡献时遵循以下指南：
在开始贡献之前，请查看我们的开发路线图：
查看 Projects 页面 和 带有 roadmap 标签的 Issues 以了解我们计划的开发任务。
如果存在相关问题 并且标记为未分配或开放状态：
如果不存在相关问题：
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
Pull Request 标题必须遵循相同的 Conventional Commits 规范：
格式：
<type>(<scope>): <description>
要求：
feat、fix、docs、ci、refactor、test、chore、perf、style、build、revert-）和下划线（_）示例：
✅ 有效：
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 自动验证在提交代码之前，请运行 pre-commit 钩子以确保代码质量和一致性：
pip install pre-commit
pre-commit install
运行 pre-commit：
# 在所有文件上运行
pre-commit run --all-files
# 安装后，pre-commit 将在 git commit 时自动运行
AgentScope 遵循懒加载导入原则以最小化资源加载：
def some_function():
import openai
# 在此处使用 openai 库
这种方法确保 import agentscope 是一个轻量操作，不会加载不必要的依赖项。
pytest tests
AgentScope 目前内置支持以下 API 提供商：OpenAI、DashScope、Gemini、Anthropic 和 Ollama。
其中 OpenAIChatModel 的实现还兼容不同的服务提供商，如 vLLM，DeepSeek、SGLang 等。
⚠️ 重要：
添加新的 ChatModel 不仅涉及模型层面的实现，还涉及到其它组件的配合，具体包括：
这意味着添加一个 ChatModel 需要大量的工作来确保其与 AgentScope 生态系统的其他部分无缝集成。 为了更好地专注于智能体能力开发和维护，官方开发团队目前不计划添加对新 API 的支持。 但是当开发者社区有强烈需求时，我们将尽力满足这些需求。
对于一个 ChatModel 类的实现，为了与仓库中 ReActAgent 兼容，所需要实现的组件如下：
ChatModel（位于 agentscope.model 下）：
from agentscope.model import ChatModelBase
class YourChatModel(ChatModelBase):
"""
需要考虑的功能包括：
- 集成 tools API
- 支持流式和非流式模式，并与 tools API 兼容
- 支持 tool_choice 参数
- 考虑支持推理模型
"""
格式化器类（位于 agentscope.formatter 下）：
from agentscope.formatter import FormatterBase
class YourModelFormatter(FormatterBase):
"""
将 `Msg` 对象转换为对应 API 提供商所需的格式。
如果模型 API 不支持多智能体场景（例如不支持消息中的 name 字段），需要
为 chatbot 和多智能体场景分别实现两个格式化器类。
"""
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-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 作为统一的抽象层。SQLAlchemy 已经支持多种 SQL 数据库，包括 PostgreSQL、MySQL、SQLite、Oracle、Microsoft SQL Server 等。
因此，为了保持 AgentScope 代码的整洁，目前不接受为 SQLAlchemy 已经支持的关系型数据库单独实现新的支持。 如果您需要支持特定的关系型数据库，请确保通过现有的 SQLAlchemy 集成来实现。
如果您希望贡献新的记忆数据库实现，请考虑以下几点：
对于关系型数据库：使用现有的 SQLAlchemy 集成。
对于 NoSQL 数据库：如果您要添加对新 NoSQL 数据库的支持（例如 MongoDB、Cassandra），请：
如果需要帮助或有疑问：
感谢为 AgentScope 做出贡献！🚀