AutoGen 开源贡献指南：uv 本地 CI 检查、版本号规则与发布流程深度解析

本文以 AutoGen 仓库根目录的 CONTRIBUTING.md 为核心，结合 python/README.md、python/pyproject.toml 与 .github/workflows/ 下的 CI 工作流源码，系统讲解如何以 uv + poe 在本地复现 CI 检查、autogen-* 包的版本管理与发布五步流程、社区 Triage 职责，以及 docstring 与版本标注（versionadded/versionchanged）的书写规范。读完后可独立完成一次合规的 Pull Request，并理解 AutoGen 多包同步发版的底层机制。

贡献类型与 CLA 协议

CONTRIBUTING.md 开篇明确了项目欢迎的贡献形式，并不限于代码：

• 提交补丁（Pushing patches）；
• 评审 Pull Request；
• 文档、示例与测试用例；
• 可读性改进，例如完善 docstring 与注释；
• 社区参与（issues、discussions、Twitter、Discord）；
• 推广项目的教程、博客与技术分享；
• 分享应用案例和相关研究。

协议方面，绝大多数贡献需要先签署微软的 Contributor License Agreement（CLA），声明你有权授予项目使用你贡献的权利。提交 PR 时，CLA bot 会自动判断你是否需要提供 CLA，并在 PR 上做出相应标注（状态检查、评论等），按 bot 提示操作一次即可，该签署在整个使用同一 CLA 体系的仓库间通用。项目同时采用微软开源行为准则（Code of Conduct）。

本地运行 CI 检查：uv + poe

CONTRIBUTING.md 在 "Running CI checks locally" 一节强调：本地运行 CI 检查必须使用 uv，因为它保证依赖与版本和 CI 环境一致。文档指引读者按照 python/README.md 的 Setup 与 Common Tasks 两节操作。下面结合仓库源码把这条链路补全。

环境准备

python/ 目录是一个 uv workspace，python/pyproject.toml 中声明了工作区成员与包间依赖关系：

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/autogen-magentic-one"]

[tool.uv.sources]
autogen-agentchat = { workspace = true }
autogen-core = { workspace = true }
autogen-ext = { workspace = true }
autogen-test-utils = { workspace = true }
autogenstudio = { workspace = true }
# ...

在 python/ 目录下执行即可创建基于当前目录状态的虚拟环境并安装全部工作区包：

uv sync --all-extras
source .venv/bin/activate

• --all-extras 会额外安装各包的可选依赖；
• 从仓库当前结构看，工作区涵盖 autogen-core、autogen-agentchat、autogen-ext、autogen-studio、agbench 等多个包（见 python/packages/），它们以源码方式装入 .venv，因此你修改任何包代码后无需重装即可被测试直接引用。

检查任务总览：poe 任务映射

predicted 中 [tool.poe.tasks] 段定义了所有本地检查任务，这是 python/README.md "Common Tasks" 一节命令列表的底层定义：

任务	poe 命令	实际执行
格式化	poe format	逐包执行 ruff format（见 python/shared_tasks.toml）
静态检查	poe lint	逐包执行 ruff check
类型检查（MyPy）	poe mypy	各包 mypy --config-file $POE_ROOT/../../pyproject.toml src tests
类型检查（Pyright）	poe pyright	各包执行 pyright
单元测试	poe test	逐包执行 pytest
构建文档	poe docs-build	sphinx-build docs/src docs/build
文档检查	poe docs-check	sphinx-build --fail-on-warning
文档示例代码检查	poe docs-check-examples	sphinx-build -b code_lint（用 Pyright 校验 docstring 中的 code-block 示例）
样例代码检查	poe samples-code-check	pyright ./samples
一键全量	poe check	依次运行 fmt、lint、pyright、mypy、docs-mypy、test、markdown-code-lint、samples-code-check

其中逐包分发由 python/run_task_in_pkgs_if_exist.py 实现：根级任务 fmt = "python run_task_in_pkgs_if_exist.py fmt" 等会进入每个子包，在其存在对应 poe 任务时执行。各包的具体命令定义在 python/shared_tasks.toml，例如 fmt = "ruff format"、lint = "ruff check"。

TL;DR（与 python/README.md 一致）：

uv sync --all-extras
source .venv/bin/activate
poe check

检查背后的静态工具配置

predicted 还固化了这些检查的严格程度，值得贡献者知晓：

• Ruff：line-length = 120，lint 规则集为 ["E", "F", "W", "B", "Q", "I", "ASYNC", "T20"]；且通过 flake8-tidy-imports.banned-api 显式禁用 unittest（提示 "Use pytest instead."），也就是说新测试应使用 pytest 而非标准库 unittest。
• MyPy：strict = true、python_version = "3.10"，并开启 disallow_untyped_defs、warn_return_any 等选项。
• Pyright：typeCheckingMode = "strict"，覆盖范围 include = ["src", "tests", "samples"]。

这些任务与 CI 一一对应：.github/workflows/checks.yml 中定义了 format、lint、mypy、docs-mypy 等 job，CI 同样在 ./python 下先执行 uv sync --locked --all-extras 再激活 venv 运行 poe 任务；其中 mypy job 采用矩阵策略逐包检查 autogen-core、agbench、autogen-ext、autogen-agentchat、magentic-one-cli。本地跑通 poe check 基本等价于通过了主干 CI 的检查集。

版本管理与发布流程

版本号规则

CONTRIBUTING.md 的 "Versioning" 一节规定：

• 所有 autogen-* 包统一版本管理：任何一个包发生变化，全部包同步更新到同一版本号，以保证包间同步；
• 破坏性变更（breaking changes）提升 minor 版本（0.X.0）；
• 新功能或 bug 修复提升 patch 版本（0.0.X）。

仓库当前状态印证了这一规则：python/packages/autogen-core/pyproject.toml、autogen-agentchat、autogen-ext 的 version 字段目前均为 0.7.5，即三个核心包同版本发布。

五步发布流程

CONTRIBUTING.md 给出的官方发布步骤如下（示例版本号以文档中的 0.4.0.dev13 为例）：

1. 创建版本更新 PR：一个 PR 统一更新全代码库中的版本号；
2. 文档 CI 预期失败：该 PR 上 docs CI 会失败，属预期行为，由下一步解决；
3. 合并后打 tag：例如

   git tag v0.4.0.dev13 && git push origin v0.4.0.dev13
   

4. 重启 docs CI：找到由 push 事件触发的失败 job 并重启所有 job（工作流定义见 .github/workflows/docs.yml）；
5. 逐包触发发布工作流：对需要发布的每个包运行单包发布工作流并获取审批后执行。

第 5 步对应 .github/workflows/single-python-package.yml，其源码可确认几个关键约束：

• 工作流为 workflow_dispatch 手动触发，需选择 package（可选值：autogen-agentchat、autogen-core、autogen-ext、agbench、autogen-studio、magentic-one-cli、pyautogen）与 ref；
• 发布前会执行 git show-ref --verify refs/tags/<ref>，强制 ref 必须是 tag，与第 3 步的打 tag 流程衔接；
• 构建使用 uv build --package <package> --out-dir dist/（在 python/ 目录下），最后通过 Trusted Publishing（id-token: write）将包发布到 PyPI；
• job 绑定 environment: package，即发布需要人工审批——对应文档中 "get an approval for the release for it to run" 的说明。

Triage 流程与 Reviewer 机制

CONTRIBUTING.md 的 "Triage process" 一节规定：AutoGen committers 每周进行一次 Triage，确保所有 issues 与 PRs 被及时评审。值班职责包括：

• Issues
  • 审阅所有新 issue（自动带 needs-triage 标签）；
  • 打标签：按所属项目打一个 proj-* 标签，以及 documentation（文档相关）、x-lang（跨语言功能）、dotnet（.NET 相关）等；
  • 必要时加入相应 milestone；
  • 能解决或回复 OP 就直接做；不能解决则指派给合适的人；
  • 等待 OP 回复时打 awaiting-op-response（OP 回复后该标签自动移除）；
  • 有余力时清理积压的历史 issue，关闭或刷新。
• PRs
  • 忽略 Draft PR，评审其余近期更新的 PR；
  • 自己能评审就评审，不能则指派他人（可用 Codespace 快速拉起 PR 环境测试）;
  • 需要 OP 回复的 PR 打 awaiting-op-response；
  • PR 已获批准且 CI 通过即可合并；疑似瞬时 CI 失败则重跑失败 job。
• Discussions：查看近期更新的讨论，回复或找团队成员回复。
• Security：处理安全告警，按需提 issue 或忽略。

关于 "Becoming a Reviewer"：文档说明目前没有正式的 reviewer 招募流程，现有 reviewer 会从活跃贡献者中产生——换言之，持续高质量的贡献是成为 reviewer 的现实路径。

Roadmap 方面，项目使用 GitHub issues 与 milestones 跟踪路线，可在 roadmap milestone 中查看后续规划（文档内为外部链接，此处不再赘述）。

代码与文档规范

什么是一个好的 docstring

CONTRIBUTING.md 提出的四条标准：

• 简洁、切中要点；
• 描述函数/类的预期契约与行为；
• 描述所有参数、返回值和异常；
• 尽可能提供示例。

文档以 TypeSubscription 的 docstring 为例，它恰好与仓库中 python/packages/autogen-core/src/autogen_core/_type_prefix_subscription.py 的源码一致：

"""This subscription matches on topics based on a prefix of the type and maps to agents using the source of the topic as the agent key.

This subscription causes each source to have its own agent instance.

Example:

    .. code-block:: python

        from autogen_core import TypePrefixSubscription

        subscription = TypePrefixSubscription(topic_type_prefix="t1", agent_type="a1")

    In this case:

    - A topic_id with type `t1` and source `s1` will be handled by an agent of type `a1` with key `s1`
    - A topic_id with type `t1` and source `s2` will be handled by an agent of type `a1` with key `s2`.
    - A topic_id with type `t1SUFFIX` and source `s2` will be handled by an agent of type `a1` with key `s2`.

Args:
    topic_type_prefix (str): Topic type prefix to match against
    agent_type (str): Agent type to handle this subscription
"""

对照源码可以看到该 docstring 确实描述了实际契约：is_match 用 topic_id.type.startswith(prefix) 做前缀匹配，map_to_agent 将 topic 的 source 映射为 AgentId 的 key，即每个 source 拥有独立的 agent 实例。

新增 API 时的版本标注

为保证各版本间文档可导航，CONTRIBUTING.md 要求新增或变更的 API 在 docstring 中加入 Sphinx 版本标注：

.. versionadded:: v0.4.1

   Here's a version added message.

.. versionchanged:: v0.4.1

   Here's a version changed message.

文档说明中标注的版本号应替换为实际引入/变更的版本（该节以 0.4.0 为例）。python/README.md 的 "Writing Documentation" 一节进一步补充了完整规范：docstring 采用 Google style 布局加 Sphinx RST 格式，包含简短描述、Args/Returns/Raises 分节、以及用 .. code-block:: python 编写的示例；引用类/函数必须使用 :class:、:meth:、:func: 指令并写全限定名（如 :class:~autogen_agentchat.AssistantAgent）。由于 docs-check-examples 任务会用 Pyright 校验 docstring 里的代码块，示例代码必须是合法可运行的 Python。

测试书写要求

python/README.md 的 "Writing Tests" 一节为贡献者给出配套要求：

• 新增公开类/函数必须配套测试，项目跟踪覆盖率，不允许因新变更降低覆盖率；
• 使用 pytest 与 fixtures 组织测试依赖，用 mock 模拟外部依赖，避免真实 API 调用；
• 模型客户端测试可用 autogen_ext.models.replay.ReplayChatCompletionClient 作为即插即用的替代客户端，重放预设响应而不发起真实请求；
• 确需真实外部服务的测试，用 pytest.mark.skipif 在环境变量（如 API key）缺失时跳过。

这与 Ruff 配置中禁用 unittest 的规则相互呼应，构成 AutoGen 测试风格的完整约束。

创建新包

python/README.md 还给出了基于 cookiecutter 模板创建新包的命令（模板位于 python/templates/new-package/）：

uv sync --python 3.12
source .venv/bin/activate
cookiecutter ./templates/new-package/

生成后即可按现有 autogen-* 包的模式加入 uv workspace 与 CI 矩阵。

小结

AutoGen 的贡献流程可以概括为一条闭环：用 uv sync --all-extras 搭建与 CI 完全一致的 workspace 环境，用 poe check 本地复现格式化、Lint、双类型检查（MyPy/Pyright strict）、测试与文档检查；提交遵循 Google style + Sphinx RST 的 docstring 规范并标注 versionadded/versionchanged；发版时所有 autogen-* 包同步升版，经"版本号 PR → 打 tag → 重启 docs CI → 逐包审批发布"五步流程上线。配合每周 Triage 与从活跃贡献者中培养 reviewer 的机制，整个流程对首次贡献者而言是可预期、可验证、可复制的。