agentscope-ai--agentscope/CONTRIBUTING_zh.md

为 AgentScope 做贡献

感谢大家对 AgentScope 的关注！

作为一个开源项目，我们欢迎并鼓励来自社区的贡献。无论是修复 bug、新增功能、完善文档，还是分享想法，每一份贡献都让 AgentScope 变得更好。

1. 开发路线图与参与方式

为了支持 AgentScope 开源社区的长期健康发展，我们将公开、透明地维护 AgentScope 的开发计划。

路线图公开。AgentScope 的开发计划会发布在 GitHub Projects 页面，并持续更新。路线图会反映 AgentScope 的技术发展方向，由核心开发团队对 AgentScope 的整体设计与质量负责。

社区可认领的任务。Projects 页面 / Issues 中标有 help wanted 的条目对所有人开放。如果你有兴趣参与某一项：

• 请在对应 issue 下评论，告知准备认领
• 这样可以避免重复劳动，也方便我们尽早协作

成为核心开发者。我们欢迎想要更深入参与、共同塑造 AgentScope 的开发者。我们会在合适的时机邀请投入度高的贡献者成为核心开发者。 成为核心开发者也意味着更频繁的参与到 AgentScope 的开发工作中，包括：

• 更加频繁的设计讨论、代码评审与多轮迭代，需要持续的时间和精力投入
• 为保证 AgentScope 的整体一致性与可靠性，核心团队保留对项目技术方向与质量标准的把控

提出新想法。针对有路线图上还没有的想法，请新建 issue 描述提议。核心开发团队会尽可能地及时回复并一起讨论可行的推进路径。

2. 在贡献中负责任地使用 AI

AgentScope 欢迎使用 AI 编码助手的贡献者——Claude Code、Cursor、Codex、Copilot 等等。我们只要求负责任地使用。AgentScope 依靠评审者的时间和社区信任运转，AI 辅助的贡献需要兼顾两者。

涉及 AI 时的几条要求：

• 作者是人，不是 AI。在 push 之前，请逐行阅读 diff，运行代码，确认理解了改了什么和为什么改。“Claude Code / Cursor / Codex 就是这么写的”并不是一个合适的理由，也不利于开源社区的健康发展。

• 创建 PR 前先自行评审 AI 生成的代码。所有人的事件都是宝贵的资源，请不要将没有审阅过的 AI 代码/改动直接丢给维护者评审。

• 保持 PR 原子化。不要提交 AI 一次性生成的 10K+ 行 PR，这种 PR 无法评审，会被拒绝。请把改动拆成若干个聚焦原子化功能的、具有单一目标的 PR。

• AI 生成代码遵守同样的原则。AgentScope 的所有开发原则——模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——对 AI 辅助代码同等适用。

简而言之：AI 让我们的开发更快，但确保合入 AgentScope 的代码质量责任仍在贡献者本人。

3. 贡献流程

端到端的贡献流程如下。

第 1 步：认领或创建 issue

在写代码之前，先找到或创建对应的 issue。

• 基于已有任务：浏览 Projects 与 Issues 中标有 help wanted 的条目(参见 §1)，在 issue 下评论认领后再开始。
• 提出新想法：新建 issue 描述问题、方案与设计上的取舍。等待核心开发团队反馈后再开始实现，避免事后大规模返工。

第 2 步：Fork 仓库并创建开发分支

1. 在 GitHub 上 fork agentscope-ai/agentscope。
2. clone 自己的 fork 并添加 upstream 远端：

   git clone https：//github.com/<your-username>/agentscope.git
   cd agentscope
   git remote add upstream https：//github.com/agentscope-ai/agentscope.git
   

3. 基于最新的 main 创建主题分支：

   git checkout main
   git pull upstream main
   git checkout -b feat/<short-description>
   

第 3 步：搭建本地环境

AgentScope 要求 Python 3.11+(详见 pyproject.toml)。

# 创建隔离环境(这里用 uv，也可用 virtualenv / conda)
uv venv
source .venv/bin/activate

# 以可编辑模式安装 AgentScope，并带上 dev extras
pip install -e ".[dev]"
# 等价的 uv 写法：
uv pip install -e ".[dev]"

# 启用 git pre-commit hooks
pre-commit install

dev extra 会拉入 pre-commit、pytest、文档工具链以及 full extra(包含 models、service、storage)。一次安装即可获得开发与运行完整测试套件所需的一切。

第 4 步：开发

写代码时遵守的几条约定：

• 可选依赖必须惰性导入。任何未列在 pyproject.toml 的 [project.dependencies] 中的依赖——也就是来自可选 extra(gemini、ollama、xai、service、storage 等)的——必须在使用点惰性导入，而不是放在模块顶部：

  def some_function():
      import google.genai  # 来自 `gemini` extra，惰性导入
      # ... 在这里使用 google.genai
  

  这样保持 import agentscope 轻量，ImportError 只在实际用到该 extra 的功能时才抛出。如果改动需要引入全新的依赖，先决定它属于基础 [project.dependencies](始终需要、保持精简)还是某个可选 extra，并在 issue 中讨论后再合入。

• 遵守项目代码风格。pre-commit 会自动处理格式与大部分 lint 规则，请在提交前运行 pre-commit 来修复问题。

• 功能要配套写单元测试。测试位于 tests/ 下，沿用现有结构。依赖可选 extra 的测试(如 Redis、Ollama)在该 extra 未安装时应能干净 skip。

第 5 步：跑 pre-commit、测试，并更新文档

创建 PR 之前，请在本地运行如下的命令检查代码格式与功能：

# 自动格式化与 lint
pre-commit run --all-files

# 单元测试
pytest tests

如果 pre-commit hook 失败，请修复格式问题（多数会自动修复），然后重新 commit。

改代码的同时请更新文档。

• AgentScope 文档放在独立仓库：agentscope-ai/docs。如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——请在该仓库同步开一个配套 PR。
• 为新公开 API 更新 docstring 与示例片段。
• 如果改动影响新手上手或 AgentScope 的对外宣传内容，更新 README.md。

第 6 步：提交与发起 PR

Commit 信息格式。我们遵循 Conventional Commits 规范，便于阅读历史与自动生成 changelog。

<type>(<scope>)： <subject>

Type 列表：

• feat： 新功能
• fix： bug 修复
• docs： 仅文档变更
• style： 不影响代码语义的改动(空白、格式等)
• refactor： 既不是修 bug 也不是加功能的代码改动
• 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

PR 标题格式。PR 标题同样遵循 Conventional Commits 格式，并由 GitHub Actions 在针对 main 的 PR 上自动校验。标题不合规的 PR 会被阻止合入，直到修正为止。

<type>(<scope>)： <description>

要求：

• 标题须以下列 type 之一开头：feat、fix、docs、ci、refactor、test、chore、perf、style、build、revert
• scope 可选，建议带上
• scope 必须小写——只允许小写字母、数字、连字符(-)和下划线(_)
• description 以小写字母开头
• 标题保持简洁、有信息量

示例：

✅ 合规：
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 必须小写

发起 PR。把分支 push 到自己的 fork，对 agentscope-ai/agentscope：main 发起 pull request。在 PR 描述里：

• 关联认领的 issue(Fixes #123 或 Refs #123)
• 概述改了什么、为什么改
• 标注任何破坏性改动、废弃项或迁移步骤
• 如果同时开了文档 PR，链接到 agentscope-ai/docs 的对应 PR

4. 重要事项

开始贡献前需要了解的几条横向约束。模块特定的事项见下文对应模块指南。

• 非平凡改动先开 issue。突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审，多半会被拒。先在 issue 中讨论设计。
• PR 保持聚焦、原子。一个 PR 一个目的。不要把重构和功能、或功能和不相干的 bug 修复混在一起。
• 不擅自破坏公开 API。能保持向后兼容就保持。无法避免的破坏性改动，在 PR 描述中清楚说明，并在同一个 PR 里更新受影响的示例和文档。
• 不绕过惰性导入原则。可选依赖必须在使用点导入，不能放在模块顶部。
• 不随意引入依赖。每个新依赖都是长期维护负担。如果只有一个模块用到，优先在该模块内部惰性导入。
• 不忽视 CI 失败。pre-commit、类型检查、测试必须通过后再发起 review，不要把修复负担推给评审者。
• 保持尊重。遵守行为准则。AgentScope 的评审风格直接但友善，对贡献者也是同样期待。

5. 模块特定贡献指南

下文覆盖社区贡献者最常扩展的模块。其他模块请先开 issue 协调。

Chat Model

AgentScope 中的一个 chat model 不只是一个类——要在 Agent 中可用，需要一组上下游配套实现。一个完整的 chat model 贡献需包含以下全部：

1. Credential 类——位于 agentscope.credential，继承 CredentialBase。承载 API key、endpoint 及 SDK 所需的其他鉴权字段。 参考：agentscope/credential/_anthropic.py

2. Chat model 类——位于 agentscope.model.<provider>/，继承 ChatModelBase。实现需覆盖：

   • 流式与非流式两种模式
   • Tools API 集成(function/tool calling)
   • tool_choice 参数
   • 适用时的 reasoning 模型支持

   参考：agentscope/model/_anthropic/

3. Model card YAML——位于 agentscope.model.<provider>._models/，每个支持的模型一份 YAML。必填字段：name、label、status、input_types、output_types、context_size、output_size。可选字段：parameter_overrides、deprecated_at。

   示例(claude-sonnet-4-6.yaml)：

   name： claude-sonnet-4-6
   label： Claude Sonnet 4.6
   status： active
   input_types：
     - text/plain
     - image/jpeg
   output_types：
     - text/plain
   context_size： 1000000
   output_size： 65536
   parameter_overrides：
     max_tokens： {"maximum"： 65536}
   

4. Formatter 类——位于 agentscope.formatter，均继承 FormatterBase。需要两种变体，因为部分 API 对多 agent 对话与单用户对话的处理方式不同：

   • <Provider>ChatFormatter 处理单用户对话场景
   • <Provider>MultiAgentFormatter 处理多 agent 场景

   每个 formatter 把 Msg 对象转换成对应 provider API 期望的请求格式。 参考：agentscope/formatter/_anthropic_formatter.py

⚠️ 只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。

Agent

AgentScope 目前只维护一个核心 agent 类——agentscope.agent.Agent——它整合了 AgentScope 库的全部功能（memory、tools、MCP、formatter、model 等）。

特定领域或专用 agent 请作为 example 贡献，而不是在 agentscope.agent 中新增类。

如果确信某个用例需要新的顶层 agent 类：

1. 先开 issue，描述用例并说明为什么组合现有 Agent 能力不够。
2. 等核心团队的设计讨论，再开始具体的代码实现。
3. 未经事先讨论就引入新 agent 类的 PR 会被拒绝。

Workspace

Workspace 提供 agent 运行所需的运行时上下文（skills、scheduled tasks 等）。新增 workspace 后端需要两个类加配套文档：

1. Workspace 类——位于 agentscope.workspace，继承 WorkspaceBase。实现该后端的存储与生命周期语义。 参考：agentscope/workspace/_local_workspace.py(LocalWorkspace)

2. Workspace manager 类——位于 agentscope/app/_manager/_workspace_manager.py，继承 WorkspaceManagerBase。把 workspace 接入应用生命周期。 参考：同文件中的 LocalWorkspaceManager

3. 文档——在 agentscope-ai/docs 配套发起 PR，说明该 workspace 的配置与使用方式。

Examples

我们非常欢迎新增展示 AgentScope 能力的 example。

主仓库 examples/ 目录聚焦于演示具体特性与能力——简洁、教学性的参考实现。更完整、贴近生产形态的应用，请贡献到 agentscope-samples。

新 example 放在自己的子目录下：

examples/
└── <example-name>/
    ├── main.py
    ├── README.md   # 说明 example 的目的、运行方式与预期输出
    └── ...

examples/agent_service/ 是不错的参考起点。

获取帮助

需要协助或有问题，可以：

• 发起 Discussion
• 在 Issues 中报告 bug
• 通过钉钉或 Discord 联系维护者(链接见 README.md)

---

感谢您为 AgentScope 所做的贡献！每一份努力都在为社区构建更好的开源工具。