尧图网页设计 
AgentScope 开源贡献指南从 issue 认领、Conventional Commits 到 Chat Model 模块扩展的完整实操手册【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscopeAgentScope 是一个以构建你能看见、理解并信任的 Agent为理念的多 Agent 平台见 pyproject.toml 中的项目描述。本文基于仓库根目录的 CONTRIBUTING_zh.md 编写系统梳理向 AgentScope 提交贡献的完整流程从公开路线图上的任务认领到 fork 分支、本地环境搭建、编码规范尤其是惰性导入原则再到 Conventional Commits 提交与 PR 标题校验规则最后深入 Chat Model、Agent、Workspace 与 Examples 四个模块的源码级扩展要求。读完本文你将掌握一套可立即执行的贡献 SOP并理解每一条规范背后的仓库实现依据。1. 开发路线图与参与方式AgentScope 的开发计划是公开透明维护的路线图发布在 GitHub Projects 页面并持续更新反映核心团队确定的技术发展方向核心团队对项目的整体设计与质量负责。社区参与主要有三种方式认领help wanted任务Projects 页面 / Issues 中标有help wanted的条目对所有人开放。如果感兴趣应在对应 issue 下评论告知准备认领这既能避免重复劳动也方便维护者尽早与你协作。成为核心开发者投入度高的贡献者会被邀请进入核心开发圈这意味着更频繁的设计讨论、代码评审与多轮迭代需要持续的时间精力投入同时核心团队保留对技术方向与质量标准的把控以保证 AgentScope 的整体一致性与可靠性。提出新想法针对路线图上还没有的想法新建 issue 描述提议即可核心团队会尽量及时回复并一起讨论可行的推进路径。从仓库结构看这一先讨论、后实现的协作节奏贯穿始终——无论是新增模型 provider 还是新的 agent 类文档都要求在动手前先开 issue 获得设计反馈。2. 贡献中负责任地使用 AIAgentScope 欢迎使用 Claude Code、Cursor、Codex、Copilot 等 AI 编码助手的贡献者但要求负责任地使用因为项目依靠评审者的时间和社区信任运转。具体几条硬性要求作者是人不是 AIpush 之前逐行阅读 diff、运行代码确认理解改了什么和为什么改。Claude Code / Cursor / Codex 就是这么写的不是合适的理由。创建 PR 前先自行评审 AI 生成的代码不要把未经审阅的 AI 改动直接丢给维护者评审。保持 PR 原子化不要提交 AI 一次性生成的 10K 行 PR这种 PR 无法评审且会被拒绝应拆成若干聚焦原子化、单一目标的 PR。AI 生成代码遵守同样的原则模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——这些开发原则对 AI 辅助代码同等适用。一句话概括AI 让开发更快但合入 AgentScope 的代码质量责任仍在贡献者本人。3. 端到端贡献流程第 1 步认领或创建 issue写代码之前先找到或创建对应的 issue基于已有任务浏览 Projects 与 Issues 中标有help wanted的条目在 issue 下评论认领后再开始。提出新想法新建 issue 描述问题、方案与设计取舍等待核心团队反馈后再开始实现避免事后大规模返工。这条规则与下文非平凡改动先开 issue的横向约束互为呼应。第 2 步Fork 仓库并创建开发分支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分支名建议与改动类型对齐例如feat/redis-memory、fix/react-agent-leak、docs/contributing-update。第 3 步搭建本地环境AgentScope 要求Python 3.11这一约束在 pyproject.toml 中通过requires-python 3.11声明并由classifiers中的Programming Language :: Python :: 3.11佐证。# 创建隔离环境这里用 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关于devextrapyproject.toml 中的[project.optional-dependencies]给出了精确组成dev会拉入pre-commit、pytest、pytest-forked、文档工具链myst_parser以及fullextra而full又聚合了models含 gemini / ollama / xai 三个 model extra、servicefastapi / uvicorn / apscheduler / ag-ui-protocol、storage-redis、storage-sql、storage-s3、channel、workspace、tools、a2a、rag、全部vdb-*向量库与memorymem0 / reme等。一次安装即可获得开发与运行完整测试套件所需的一切这也是文档中一个命令装齐全部依赖的实现基础。第 4 步开发——惰性导入是硬性约定写代码时最重要的约定是可选依赖必须惰性导入任何未列在 pyproject.toml 的[project.dependencies]中的依赖——即来自可选 extragemini、ollama、xai、service、storage等的——必须在使用点惰性导入而不是放在模块顶部def some_function(): import google.genai # 来自 gemini extra惰性导入 # ... 在这里使用 google.genai这样能保持import agentscope轻量ImportError只在真正用到该 extra 的功能时才抛出。从 pyproject.toml 可以看到基础[project.dependencies]刻意保持精简如anthropic、dashscope、openai等核心 SDK而google-genai、ollama、xai-sdk等则被划分到model-gemini、model-ollama、model-xai等可选 extra 中——这正是惰性导入原则在依赖划分层面的体现。如果改动需要引入全新依赖先决定它属于基础依赖始终需要、保持精简还是某个可选 extra并在 issue 中讨论后再合入。其余约定还包括遵守项目代码风格pre-commit 自动处理格式与大部分 lint 规则、功能要配套写单元测试测试位于tests/下并沿用现有结构依赖可选 extra 的测试如 Redis、Ollama 在该 extra 未安装时应能干净 skip。仓库的 tests 目录中可以看到大量此类测试例如middleware_budget_test.py、toolkit_test.py等与[project.optional-dependencies]中可选能力一一对应。第 5 步跑 pre-commit、测试并更新文档创建 PR 之前请在本地运行与 CI 相同的检查# 自动格式化与 lint pre-commit run --all-files # 运行单元测试 pytest tests如果 pre-commit hook 失败修复格式问题多数会自动修复后重新 commit不要用--no-verify绕过。改代码的同时请更新文档AgentScope 的用户文档放在独立仓库agentscope-ai/docs如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——需在那里同步开配套 PR。为新公开 API 更新 docstring 与示例片段。如果改动影响新手上手或对外宣传内容更新仓库根目录的 README.md。第 6 步提交与发起 PRCommit 信息格式遵循 Conventional Commits 规范便于阅读历史与自动生成 changelogtype(scope): subjectType 列表Type含义feat新功能fixbug 修复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 integrationPR 标题格式同样遵循 Conventional Commits并由 GitHub Actions 在针对main的 PR 上自动校验标题不合规的 PR 会被阻止合入type(scope): description要求标题须以下列 type 之一开头feat、fix、docs、ci、refactor、test、chore、perf、style、build、revertscope 可选建议带上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 描述中应关联认领的 issueFixes #123或Refs #123概述改了什么、为什么改标注任何破坏性改动、废弃项或迁移步骤如果同时开了文档 PR链接到 agentscope-ai/docs 的对应 PR。4. 重要事项开始贡献前的横向约束以下约束适用于所有模块无论贡献哪个功能都需遵守非平凡改动先开 issue突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审多半会被拒。PR 保持聚焦、原子一个 PR 一个目的不要把重构和功能、或功能和不相干的 bug 修复混在一起。不擅自破坏公开 API能保持向后兼容就保持无法避免的破坏性改动在 PR 描述中清楚说明并在同一个 PR 里更新受影响的示例和文档。不绕过惰性导入原则可选依赖必须在使用点导入不能放在模块顶部。不随意引入依赖每个新依赖都是长期维护负担如果只有一个模块用到优先在该模块内部惰性导入。不忽视 CI 失败pre-commit、类型检查、测试必须通过后再发起 review不要把修复负担推给评审者。保持尊重遵守行为准则AgentScope 的评审风格直接但友善对贡献者也是同样期待。5. 模块特定贡献指南文档覆盖了社区贡献者最常扩展的四个模块每个都有明确的源码级要求其他模块请先开 issue 协调。5.1 Chat Model完整的四件套在 AgentScope 中一个 chat model不只是一个类——要在Agent中可用需要一组上下游配套实现。一个完整的 chat model 贡献必须包含以下全部四部分① Credential 类——位于agentscope.credential继承CredentialBase承载 API key、endpoint 及 SDK 所需的其他鉴权字段。参考实现是 src/agentscope/credential/_anthropic.py 中的AnthropicCredential它声明api_key: SecretStr与可选的base_url并提供get_chat_model_class()类方法返回对应的AnthropicChatModel从而把鉴权凭据与模型实现在类型层面绑定起来。② Chat model 类——位于agentscope.model.provider/继承ChatModelBase实现需覆盖流式与非流式两种模式、Tools API 集成function/tool calling、tool_choice参数以及适用时的 reasoning 模型支持。参考目录是 src/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。仓库中 src/agentscope/model/_anthropic/_models/ 目录实际存放了claude-sonnet-4-6.yaml、claude-opus-4-5.yaml、claude-haiku-4-5.yaml等 10 份模型卡片。以claude-sonnet-4-6.yaml为例name: claude-sonnet-4-6 label: Claude Sonnet 4.6 status: active input_types: - text/plain - application/x-thinking - image/jpeg - image/png - image/gif - image/webp - application/pdf output_types: - text/plain - application/x-thinking context_size: 1000000 output_size: 128000 parameter_overrides: max_tokens: {maximum: 128000} thinking_mode: default: adaptive anyOf: - enum: [adaptive, enabled, disabled] type: string - type: null reasoning_effort: anyOf: - enum: [low, medium, high, max] type: string - type: null从该文件可以看到parameter_overrides可用于约束参数枚举值如thinking_mode仅允许adaptive/enabled/disabled与数值上限如max_tokens最大 128000是模型能力边界声明的重要扩展点。这些 YAML 文件在打包时通过 pyproject.toml 中的* [py.typed, _models/*.yaml, ...]规则随包发布。④ Formatter 类——位于agentscope.formatter均继承FormatterBase。需要两种变体因为部分 API 对多 agent 对话与单用户对话的处理方式不同ProviderChatFormatter处理单用户对话场景ProviderMultiAgentFormatter处理多 agent 场景。每个 formatter 把Msg对象转换成对应 provider API 期望的请求格式。参考实现是 src/agentscope/formatter/_anthropic_formatter.py其中AnthropicChatFormatter针对仅一个用户与一个 agent的聊天场景、以role字段区分对话实体AnthropicMultiAgentFormatter面向多 agent 对话、通过conversation_history_prompt等字段注入对话历史上下文两者共享_AnthropicFormatterBase基类中的_format_messages消息转换逻辑。注意只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。5.2 Agent只维护一个核心类AgentScope 刻意只维护一个核心 agent 类——src/agentscope/agent/_agent.py 中的agentscope.agent.Agent——它整合了 AgentScope 库的全部功能memory、tools、MCP、formatter、model 等。特定领域或专用 agent 请作为 Examples 贡献而不是在agentscope.agent中新增类。如果确信某个用例确实需要新的顶层 agent 类先开 issue描述用例并说明为什么组合现有Agent能力不够等核心团队的设计讨论再开始具体的代码实现未经事先讨论就引入新 agent 类的 PR 会被拒绝。5.3 Workspace两个类加配套文档Workspace 提供 agent 运行所需的运行时上下文skills、scheduled tasks 等。新增一个 workspace 后端需要两个类加配套文档① Workspace 类——位于agentscope.workspace继承WorkspaceBase实现该后端的存储与生命周期语义。参考实现是 src/agentscope/workspace/_local_workspace.py 中的LocalWorkspace其抽象基类WorkspaceBase定义在 src/agentscope/workspace/_base.py。② Workspace manager 类——继承WorkspaceManagerBase把 workspace 接入应用生命周期。当前仓库中该基类实际位于 src/agentscope/app/workspace_manager/_base.py同目录的 src/agentscope/app/workspace_manager/_local_workspace_manager.py 提供了LocalWorkspaceManager参考实现按 workspace_id 缓存、TTL 驱动的懒加载生命周期管理。仓库还内置了 docker、k8s、e2b、daytona、bubblewrap、applecontainer、opensandbox 等多种后端实现新增后端时可对照这些既有 manager 的结构。③ 文档——在 agentscope-ai/docs 配套发起 PR说明该 workspace 的配置与使用方式。5.4 Examples主仓库聚焦教学性示例主仓库 examples 目录聚焦于演示具体特性与能力——简洁、教学性的参考实现更完整、贴近生产形态的应用请贡献到独立的 agentscope-samples 仓库。新 example 放在自己的子目录下examples/ └── example-name/ ├── main.py ├── README.md # 说明 example 的目的、运行方式与预期输出 └── ...examples/agent_service 是不错的参考起点——它包含main.py与 README展示了示例自带可运行入口 完整使用说明的标准形态。6. 获取帮助需要协助或有问题时可以发起 Discussion 讨论、在 Issues 中报告 bug或通过钉钉 / Discord 联系维护者链接见 README.md。结语AgentScope 的贡献流程是一个公开规划 → 先讨论后实现 → 小步原子提交 → 自动校验 人工评审的闭环惰性导入与依赖划分写进了 pyproject.tomlPR 标题校验由 GitHub Actions 在main上强制执行而 Chat Model 的四件套、Agent 的单一核心类、Workspace 的两类一文档则把模块扩展的验收标准直接固化在源码结构里。无论你贡献的是 bug 修复、新模型 provider还是全新的 workspace 后端遵循本文的流程与约束都能让你的改动顺利通过评审、合入项目。【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AgentScope 开源贡献指南：从 issue 认领、Conventional Commits 到 Chat Model 模块扩展的完整实操手册
AgentScope 开源贡献指南从 issue 认领、Conventional Commits 到 Chat Model 模块扩展的完整实操手册【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscopeAgentScope 是一个以构建你能看见、理解并信任的 Agent为理念的多 Agent 平台见 pyproject.toml 中的项目描述。本文基于仓库根目录的 CONTRIBUTING_zh.md 编写系统梳理向 AgentScope 提交贡献的完整流程从公开路线图上的任务认领到 fork 分支、本地环境搭建、编码规范尤其是惰性导入原则再到 Conventional Commits 提交与 PR 标题校验规则最后深入 Chat Model、Agent、Workspace 与 Examples 四个模块的源码级扩展要求。读完本文你将掌握一套可立即执行的贡献 SOP并理解每一条规范背后的仓库实现依据。1. 开发路线图与参与方式AgentScope 的开发计划是公开透明维护的路线图发布在 GitHub Projects 页面并持续更新反映核心团队确定的技术发展方向核心团队对项目的整体设计与质量负责。社区参与主要有三种方式认领help wanted任务Projects 页面 / Issues 中标有help wanted的条目对所有人开放。如果感兴趣应在对应 issue 下评论告知准备认领这既能避免重复劳动也方便维护者尽早与你协作。成为核心开发者投入度高的贡献者会被邀请进入核心开发圈这意味着更频繁的设计讨论、代码评审与多轮迭代需要持续的时间精力投入同时核心团队保留对技术方向与质量标准的把控以保证 AgentScope 的整体一致性与可靠性。提出新想法针对路线图上还没有的想法新建 issue 描述提议即可核心团队会尽量及时回复并一起讨论可行的推进路径。从仓库结构看这一先讨论、后实现的协作节奏贯穿始终——无论是新增模型 provider 还是新的 agent 类文档都要求在动手前先开 issue 获得设计反馈。2. 贡献中负责任地使用 AIAgentScope 欢迎使用 Claude Code、Cursor、Codex、Copilot 等 AI 编码助手的贡献者但要求负责任地使用因为项目依靠评审者的时间和社区信任运转。具体几条硬性要求作者是人不是 AIpush 之前逐行阅读 diff、运行代码确认理解改了什么和为什么改。Claude Code / Cursor / Codex 就是这么写的不是合适的理由。创建 PR 前先自行评审 AI 生成的代码不要把未经审阅的 AI 改动直接丢给维护者评审。保持 PR 原子化不要提交 AI 一次性生成的 10K 行 PR这种 PR 无法评审且会被拒绝应拆成若干聚焦原子化、单一目标的 PR。AI 生成代码遵守同样的原则模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——这些开发原则对 AI 辅助代码同等适用。一句话概括AI 让开发更快但合入 AgentScope 的代码质量责任仍在贡献者本人。3. 端到端贡献流程第 1 步认领或创建 issue写代码之前先找到或创建对应的 issue基于已有任务浏览 Projects 与 Issues 中标有help wanted的条目在 issue 下评论认领后再开始。提出新想法新建 issue 描述问题、方案与设计取舍等待核心团队反馈后再开始实现避免事后大规模返工。这条规则与下文非平凡改动先开 issue的横向约束互为呼应。第 2 步Fork 仓库并创建开发分支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分支名建议与改动类型对齐例如feat/redis-memory、fix/react-agent-leak、docs/contributing-update。第 3 步搭建本地环境AgentScope 要求Python 3.11这一约束在 pyproject.toml 中通过requires-python 3.11声明并由classifiers中的Programming Language :: Python :: 3.11佐证。# 创建隔离环境这里用 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关于devextrapyproject.toml 中的[project.optional-dependencies]给出了精确组成dev会拉入pre-commit、pytest、pytest-forked、文档工具链myst_parser以及fullextra而full又聚合了models含 gemini / ollama / xai 三个 model extra、servicefastapi / uvicorn / apscheduler / ag-ui-protocol、storage-redis、storage-sql、storage-s3、channel、workspace、tools、a2a、rag、全部vdb-*向量库与memorymem0 / reme等。一次安装即可获得开发与运行完整测试套件所需的一切这也是文档中一个命令装齐全部依赖的实现基础。第 4 步开发——惰性导入是硬性约定写代码时最重要的约定是可选依赖必须惰性导入任何未列在 pyproject.toml 的[project.dependencies]中的依赖——即来自可选 extragemini、ollama、xai、service、storage等的——必须在使用点惰性导入而不是放在模块顶部def some_function(): import google.genai # 来自 gemini extra惰性导入 # ... 在这里使用 google.genai这样能保持import agentscope轻量ImportError只在真正用到该 extra 的功能时才抛出。从 pyproject.toml 可以看到基础[project.dependencies]刻意保持精简如anthropic、dashscope、openai等核心 SDK而google-genai、ollama、xai-sdk等则被划分到model-gemini、model-ollama、model-xai等可选 extra 中——这正是惰性导入原则在依赖划分层面的体现。如果改动需要引入全新依赖先决定它属于基础依赖始终需要、保持精简还是某个可选 extra并在 issue 中讨论后再合入。其余约定还包括遵守项目代码风格pre-commit 自动处理格式与大部分 lint 规则、功能要配套写单元测试测试位于tests/下并沿用现有结构依赖可选 extra 的测试如 Redis、Ollama 在该 extra 未安装时应能干净 skip。仓库的 tests 目录中可以看到大量此类测试例如middleware_budget_test.py、toolkit_test.py等与[project.optional-dependencies]中可选能力一一对应。第 5 步跑 pre-commit、测试并更新文档创建 PR 之前请在本地运行与 CI 相同的检查# 自动格式化与 lint pre-commit run --all-files # 运行单元测试 pytest tests如果 pre-commit hook 失败修复格式问题多数会自动修复后重新 commit不要用--no-verify绕过。改代码的同时请更新文档AgentScope 的用户文档放在独立仓库agentscope-ai/docs如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——需在那里同步开配套 PR。为新公开 API 更新 docstring 与示例片段。如果改动影响新手上手或对外宣传内容更新仓库根目录的 README.md。第 6 步提交与发起 PRCommit 信息格式遵循 Conventional Commits 规范便于阅读历史与自动生成 changelogtype(scope): subjectType 列表Type含义feat新功能fixbug 修复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 integrationPR 标题格式同样遵循 Conventional Commits并由 GitHub Actions 在针对main的 PR 上自动校验标题不合规的 PR 会被阻止合入type(scope): description要求标题须以下列 type 之一开头feat、fix、docs、ci、refactor、test、chore、perf、style、build、revertscope 可选建议带上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 描述中应关联认领的 issueFixes #123或Refs #123概述改了什么、为什么改标注任何破坏性改动、废弃项或迁移步骤如果同时开了文档 PR链接到 agentscope-ai/docs 的对应 PR。4. 重要事项开始贡献前的横向约束以下约束适用于所有模块无论贡献哪个功能都需遵守非平凡改动先开 issue突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审多半会被拒。PR 保持聚焦、原子一个 PR 一个目的不要把重构和功能、或功能和不相干的 bug 修复混在一起。不擅自破坏公开 API能保持向后兼容就保持无法避免的破坏性改动在 PR 描述中清楚说明并在同一个 PR 里更新受影响的示例和文档。不绕过惰性导入原则可选依赖必须在使用点导入不能放在模块顶部。不随意引入依赖每个新依赖都是长期维护负担如果只有一个模块用到优先在该模块内部惰性导入。不忽视 CI 失败pre-commit、类型检查、测试必须通过后再发起 review不要把修复负担推给评审者。保持尊重遵守行为准则AgentScope 的评审风格直接但友善对贡献者也是同样期待。5. 模块特定贡献指南文档覆盖了社区贡献者最常扩展的四个模块每个都有明确的源码级要求其他模块请先开 issue 协调。5.1 Chat Model完整的四件套在 AgentScope 中一个 chat model不只是一个类——要在Agent中可用需要一组上下游配套实现。一个完整的 chat model 贡献必须包含以下全部四部分① Credential 类——位于agentscope.credential继承CredentialBase承载 API key、endpoint 及 SDK 所需的其他鉴权字段。参考实现是 src/agentscope/credential/_anthropic.py 中的AnthropicCredential它声明api_key: SecretStr与可选的base_url并提供get_chat_model_class()类方法返回对应的AnthropicChatModel从而把鉴权凭据与模型实现在类型层面绑定起来。② Chat model 类——位于agentscope.model.provider/继承ChatModelBase实现需覆盖流式与非流式两种模式、Tools API 集成function/tool calling、tool_choice参数以及适用时的 reasoning 模型支持。参考目录是 src/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。仓库中 src/agentscope/model/_anthropic/_models/ 目录实际存放了claude-sonnet-4-6.yaml、claude-opus-4-5.yaml、claude-haiku-4-5.yaml等 10 份模型卡片。以claude-sonnet-4-6.yaml为例name: claude-sonnet-4-6 label: Claude Sonnet 4.6 status: active input_types: - text/plain - application/x-thinking - image/jpeg - image/png - image/gif - image/webp - application/pdf output_types: - text/plain - application/x-thinking context_size: 1000000 output_size: 128000 parameter_overrides: max_tokens: {maximum: 128000} thinking_mode: default: adaptive anyOf: - enum: [adaptive, enabled, disabled] type: string - type: null reasoning_effort: anyOf: - enum: [low, medium, high, max] type: string - type: null从该文件可以看到parameter_overrides可用于约束参数枚举值如thinking_mode仅允许adaptive/enabled/disabled与数值上限如max_tokens最大 128000是模型能力边界声明的重要扩展点。这些 YAML 文件在打包时通过 pyproject.toml 中的* [py.typed, _models/*.yaml, ...]规则随包发布。④ Formatter 类——位于agentscope.formatter均继承FormatterBase。需要两种变体因为部分 API 对多 agent 对话与单用户对话的处理方式不同ProviderChatFormatter处理单用户对话场景ProviderMultiAgentFormatter处理多 agent 场景。每个 formatter 把Msg对象转换成对应 provider API 期望的请求格式。参考实现是 src/agentscope/formatter/_anthropic_formatter.py其中AnthropicChatFormatter针对仅一个用户与一个 agent的聊天场景、以role字段区分对话实体AnthropicMultiAgentFormatter面向多 agent 对话、通过conversation_history_prompt等字段注入对话历史上下文两者共享_AnthropicFormatterBase基类中的_format_messages消息转换逻辑。注意只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。5.2 Agent只维护一个核心类AgentScope 刻意只维护一个核心 agent 类——src/agentscope/agent/_agent.py 中的agentscope.agent.Agent——它整合了 AgentScope 库的全部功能memory、tools、MCP、formatter、model 等。特定领域或专用 agent 请作为 Examples 贡献而不是在agentscope.agent中新增类。如果确信某个用例确实需要新的顶层 agent 类先开 issue描述用例并说明为什么组合现有Agent能力不够等核心团队的设计讨论再开始具体的代码实现未经事先讨论就引入新 agent 类的 PR 会被拒绝。5.3 Workspace两个类加配套文档Workspace 提供 agent 运行所需的运行时上下文skills、scheduled tasks 等。新增一个 workspace 后端需要两个类加配套文档① Workspace 类——位于agentscope.workspace继承WorkspaceBase实现该后端的存储与生命周期语义。参考实现是 src/agentscope/workspace/_local_workspace.py 中的LocalWorkspace其抽象基类WorkspaceBase定义在 src/agentscope/workspace/_base.py。② Workspace manager 类——继承WorkspaceManagerBase把 workspace 接入应用生命周期。当前仓库中该基类实际位于 src/agentscope/app/workspace_manager/_base.py同目录的 src/agentscope/app/workspace_manager/_local_workspace_manager.py 提供了LocalWorkspaceManager参考实现按 workspace_id 缓存、TTL 驱动的懒加载生命周期管理。仓库还内置了 docker、k8s、e2b、daytona、bubblewrap、applecontainer、opensandbox 等多种后端实现新增后端时可对照这些既有 manager 的结构。③ 文档——在 agentscope-ai/docs 配套发起 PR说明该 workspace 的配置与使用方式。5.4 Examples主仓库聚焦教学性示例主仓库 examples 目录聚焦于演示具体特性与能力——简洁、教学性的参考实现更完整、贴近生产形态的应用请贡献到独立的 agentscope-samples 仓库。新 example 放在自己的子目录下examples/ └── example-name/ ├── main.py ├── README.md # 说明 example 的目的、运行方式与预期输出 └── ...examples/agent_service 是不错的参考起点——它包含main.py与 README展示了示例自带可运行入口 完整使用说明的标准形态。6. 获取帮助需要协助或有问题时可以发起 Discussion 讨论、在 Issues 中报告 bug或通过钉钉 / Discord 联系维护者链接见 README.md。结语AgentScope 的贡献流程是一个公开规划 → 先讨论后实现 → 小步原子提交 → 自动校验 人工评审的闭环惰性导入与依赖划分写进了 pyproject.tomlPR 标题校验由 GitHub Actions 在main上强制执行而 Chat Model 的四件套、Agent 的单一核心类、Workspace 的两类一文档则把模块扩展的验收标准直接固化在源码结构里。无论你贡献的是 bug 修复、新模型 provider还是全新的 workspace 后端遵循本文的流程与约束都能让你的改动顺利通过评审、合入项目。【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考