CONTRIBUTING_zh.md
感谢大家对 AgentScope 的关注！
作为一个开源项目，我们欢迎并鼓励来自社区的贡献。无论是修复 bug、新增功能、完善文档，还是分享想法，每一份贡献都让 AgentScope 变得更好。
为了支持 AgentScope 开源社区的长期健康发展，我们将公开、透明地维护 AgentScope 的开发计划。
路线图公开。AgentScope 的开发计划会发布在 GitHub Projects 页面，并持续更新。路线图会反映 AgentScope 的技术发展方向，由核心开发团队对 AgentScope 的整体设计与质量负责。
社区可认领的任务。Projects 页面 / Issues 中标有 help wanted 的条目对所有人开放。如果你有兴趣参与某一项：
成为核心开发者。我们欢迎想要更深入参与、共同塑造 AgentScope 的开发者。我们会在合适的时机邀请投入度高的贡献者成为核心开发者。 成为核心开发者也意味着更频繁的参与到 AgentScope 的开发工作中，包括：
提出新想法。针对有路线图上还没有的想法，请新建 issue 描述提议。核心开发团队会尽可能地及时回复并一起讨论可行的推进路径。
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 的代码质量责任仍在贡献者本人。
端到端的贡献流程如下。
在写代码之前，先找到或创建对应的 issue。
help wanted 的条目(参见 §1)，在 issue 下评论认领后再开始。git clone https：//github.com/<your-username>/agentscope.git
cd agentscope
git remote add upstream https：//github.com/agentscope-ai/agentscope.git
main 创建主题分支：
git checkout main
git pull upstream main
git checkout -b feat/<short-description>
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)。一次安装即可获得开发与运行完整测试套件所需的一切。
写代码时遵守的几条约定：
可选依赖必须惰性导入。任何未列在 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。
创建 PR 之前，请在本地运行如下的命令检查代码格式与功能：
# 自动格式化与 lint
pre-commit run --all-files
# 单元测试
pytest tests
如果 pre-commit hook 失败，请修复格式问题（多数会自动修复），然后重新 commit。
改代码的同时请更新文档。
README.md。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>
要求：
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 必须小写
发起 PR。把分支 push 到自己的 fork，对 agentscope-ai/agentscope：main 发起 pull request。在 PR 描述里：
Fixes #123 或 Refs #123)开始贡献前需要了解的几条横向约束。模块特定的事项见下文对应模块指南。
下文覆盖社区贡献者最常扩展的模块。其他模块请先开 issue 协调。
AgentScope 中的一个 chat model 不只是一个类——要在 Agent 中可用，需要一组上下游配套实现。一个完整的 chat model 贡献需包含以下全部：
Credential 类——位于 agentscope.credential，继承 CredentialBase。承载 API key、endpoint 及 SDK 所需的其他鉴权字段。
参考：agentscope/credential/_anthropic.py
Chat model 类——位于 agentscope.model.<provider>/，继承 ChatModelBase。实现需覆盖：
tool_choice 参数参考：agentscope/model/_anthropic/
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}
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 不会被合入。
AgentScope 目前只维护一个核心 agent 类——agentscope.agent.Agent——它整合了 AgentScope 库的全部功能（memory、tools、MCP、formatter、model 等）。
特定领域或专用 agent 请作为 example 贡献，而不是在 agentscope.agent 中新增类。
如果确信某个用例需要新的顶层 agent 类：
Agent 能力不够。Workspace 提供 agent 运行所需的运行时上下文（skills、scheduled tasks 等）。新增 workspace 后端需要两个类加配套文档：
Workspace 类——位于 agentscope.workspace，继承 WorkspaceBase。实现该后端的存储与生命周期语义。
参考：agentscope/workspace/_local_workspace.py(LocalWorkspace)
Workspace manager 类——位于 agentscope/app/_manager/_workspace_manager.py，继承 WorkspaceManagerBase。把 workspace 接入应用生命周期。
参考：同文件中的 LocalWorkspaceManager
文档——在 agentscope-ai/docs 配套发起 PR，说明该 workspace 的配置与使用方式。
我们非常欢迎新增展示 AgentScope 能力的 example。
主仓库 examples/ 目录聚焦于演示具体特性与能力——简洁、教学性的参考实现。更完整、贴近生产形态的应用，请贡献到 agentscope-samples。
新 example 放在自己的子目录下：
examples/
└── <example-name>/
├── main.py
├── README.md # 说明 example 的目的、运行方式与预期输出
└── ...
examples/agent_service/ 是不错的参考起点。
需要协助或有问题，可以：
感谢您为 AgentScope 所做的贡献！每一份努力都在为社区构建更好的开源工具。