📦 agentscope-ai / agentscope

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318# 贡献到 AgentScope

## 欢迎！🎉

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

## 如何贡献

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

### 1. 检查现有计划和问题

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

- **查看 [Projects](https://github.com/orgs/agentscope-ai/projects/2) 页面** 和 **[带有 `roadmap` 标签的 Issues](https://github.com/agentscope-ai/agentscope/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** 以了解我们计划的开发任务。

  - **如果存在相关问题** 并且标记为未分配或开放状态：
    - 请在该问题下评论，表达您有兴趣参与该任务
    - 这有助于协调开发工作，避免重复工作

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

### 2. 提交信息格式

AgentScope 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。这使得提交历史更易读，并能够自动生成更新日志。

**格式：**
```
<type>(<scope>): <subject>
```

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

**示例：**
```bash
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](https://www.conventionalcommits.org/) 规范：

**格式：**
```
<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 钩子以确保代码质量和一致性：


```bash
pip install pre-commit
pre-commit install
```

**运行 pre-commit：**
```bash
# 在所有文件上运行
pre-commit run --all-files

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

#### b. 关于代码中的 Import

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

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

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

#### c. 单元测试

- 所有新功能都必须包含适当的单元测试
- 在提交 PR 之前确保现有测试通过
- 使用以下命令运行测试：
  ```bash
  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` 下）：
   ```python
   from agentscope.model import ChatModelBase


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

2. **格式化器类**（位于 `agentscope.formatter` 下）：
   ```python
   from agentscope.formatter import FormatterBase

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

3. **Token 计数器**（位于 `agentscope.token` 下，推荐）：
   ```python
   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](https://github.com/agentscope-ai/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](https://github.com/agentscope-ai/agentscope/discussions)
- 🐛 通过 [Issues](https://github.com/agentscope-ai/agentscope/issues) 报告错误
- 📧 通过钉钉交流群或 Discord 联系开发团队（链接在 README.md 中）


---

感谢为 AgentScope 做出贡献！🚀