Pydantic AI 贡献指南从 Issue 到合并的完整协作流程与工程实践【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-aiPydantic AI 是一个由小型核心团队维护的 AI Agent 框架仓库其贡献流程与传统开源项目有显著差异维护者按对最多用户最有价值的优先级处理 issue 与 PR而非按提交顺序代码被视作起点而非成品维护者可能重写贡献的代码类型检查、文档导航、新模型准入等环节都有一套精确且与众不同的工程规则。本文以仓库内 docs/contributing.md 为骨架结合 Makefile、pyproject.toml、scripts/typecheck_changed.py 等仓库源码与配置完整梳理从提出想法到代码合并的每个环节帮助你避免最常见的踩坑点让贡献真正被看见、被合并。我们如何工作短版本Pydantic AI 由一个小团队维护他们根据什么对最多用户最有价值来设定自己的优先级并按此顺序处理 issue 和 PR——而不是按到达顺序。这一点决定了整个贡献流程的基调你的提交质量再高如果不在维护者的优先级里就可能长时间无人问津。针对不同类型的诉求官方给出的路径是发现 bug开一个 issue包含清晰描述和最小可复现示例。附带一个 Logfire trace 链接能显著加快调试速度。想要新功能或 API 变更开 issue 描述你正在解决的问题不要直接写代码。想帮助构建某个功能在 issue 下评论说明你为什么需要它、你能带来什么上下文。这就是下文要讲的 champion拥护者机制。有修复或代码要分享确保维护者已在 issue 上认可方案并分配给你然后再开 PR。写代码之前先对齐再动手对于任何非平凡的工作在写代码之前先与维护者对齐方案。一个预先对齐过的 PR 比一个冷启动的 PR 合并快得多。平凡修复Trivial fixes拼写错误、失效链接、小的文档改进、显而易见的一行修复直接开 PR 即可不需要 issue。Bug 修复如果修复方式可能有多种走向或者你不确定它到底算不算 bug先开 issue。包含最小可复现示例理想情况下附上展示问题的 Logfire trace 链接。对于边界清晰的 bug维护团队可能内部直接生成修复——此时你最有价值的贡献是提交一份清晰的报告然后验证修复在你的用例下是否有效。功能、集成或 API 变更写代码之前先问一个问题这个变更真的需要进入核心吗大多数新的 Agent 行为属于 Pydantic AI Harness官方能力库而不是本仓库。Pydantic AI 核心只负责 agent 循环agent loop、模型提供商以及需要模型特定支持或对 Agent 体验至关重要的能力。而独立的 capabilities——如 guardrails护栏、memory记忆、context management上下文管理、文件系统访问等——属于 harness那里可以更快迭代。仓库内 docs/extensibility.md 对边界做了详细说明capabilities 是 Pydantic AI 的主要扩展点它们把工具、生命周期钩子、指令和模型设置打包成可复用单元如果你想贡献一个 capability应当到 Pydantic AI Harness 开 issue而不是 pydantic-ai。你也可以用pydantic-ai-name命名约定把自己的 capability 发布成独立包参见 Publishing capability packages。如果确实属于核心流程是先搜索。如果已有 issue 覆盖你的需求直接评论如果最近的 issue 只是相关开一个新 issue 并链接到它。描述问题而不只是解决方案。告诉团队你在构建什么、什么阻塞了你、你尝试过什么。这些上下文比代码更重要。在构建之前提出计划。在 issue 上贴一份简短计划或者开一个只包含PLAN.md的草稿 PR。对于较大的功能维护者会与贡献者进行简短视频通话来迭代设计——20 分钟的通话往往能省下数周的异步评审周期。等待分配。维护者需要在 issue 上认可方案并分配给你之后你才能开 PR。未被分配的 PR 可能被自动关闭。⚠️ 警告原文即强调在没有预先对齐的情况下写一个大功能 PR是贡献停滞或关闭的最常见原因。Champions让功能进入优先级的机制Champion拥护者是需要某个功能、对问题有上下文、并愿意投入时间帮助团队把它做对的人。如果你愿意拥护一个功能在 issue 下评论说明你在构建什么、为什么需要它、你能贡献什么领域知识、测试、验证。团队优先考虑那些有生产级用例的 champion 站出来的功能。没有 champion 的功能会一直留在 backlog 里直到团队自己将其列为优先或某个有真实上下文的人出现。成为 champion 不代表要写代码而是塑造计划并验证结果。对于重要功能团队会安排通话一起迭代设计。功能发布时champion 会被署名列为共同作者。审查期间你会遇到什么按优先级审查而非按提交顺序团队不会自动分诊每一个新 PR。未预先对齐的 issue 上的 PR 不在评审队列中——无论它写得多好。如果没有维护者在 issue 上同意变更并分配给你请默认他们没看到你的 PR。即使是对已经参与过的代码所有贡献代码都被视为起点而不是成品。团队根据功能对项目的重要性来评审和排序 PR而不是看代码投入了多少精力。这是对传统开源工作方式的一种改变团队宁愿坦诚相告也不愿让 PR 毫无音讯地挂在那里。想知道 PR 状态最好的方式是到 Pydantic Slack 的#pydantic-ai频道 ping 一下。我们可能重写或取代你的代码贡献的代码被视为示例它展示提议的变更并证明方案可行而不是最终合并的形态。对于非平凡的变更你能给团队最有用的东西是一个计划加一个可运行的示例——而不是一份打磨好、可随时合并的实现。在任何 PR 上维护者都可能向你的分支推送提交、开一个取代你的后续 PR、或者从头重写。出于安全原因团队倾向于重写贡献代码而非原样合并。你仍会被署名为原作者。因此请不要在未对齐的 PR 上花精力追 CI 绿灯、处理每条自动评审意见、或为合并冲突做 rebase。如果团队接手推进这个变更这些打磨会在重写时被丢弃。让方案跑通然后停下来在 Slack 上 ping 团队。另外不要对已开的 PR 做 force-push。重写其提交会使之前的评审失效请推送后续提交follow-up commits合并时会由维护者 squash。自动评审是建议性的不是门槛PR 会自动接受 Devin 和团队自有工具的评审但这些评审是建议性的机器人的 approval 不意味着你的 PR 可以合并——只有人类维护者的评审才算数。机器人的发现不意味着你必须处理——如果你不同意直接说明。如果自动评审在你的 PR 上产生噪音告诉团队。他们会用这些反馈来调优工具。仓库的 .github/workflows 目录里可以看到这套自动化矩阵的真实规模pydantic-ai-pr-reviewPR 评审、pydantic-ai-bug-hunterbug 猎人、pydantic-ai-regression-detector回归检测、pydantic-ai-docs-drift文档漂移检测等数十个工作流协同运转。优先级如何权衡团队收到的贡献远超可评审量他们把精力集中在影响最大的地方无法承诺处理每一个 PR即使是好 PR。优先级权重如下用户需求更多用户需要的功能优先有生产用例 champion 支持的功能胜过投机性的提案。提供商重要性影响前沿提供商Anthropic、OpenAI、Google或已知重度使用的提供商的工作优先。小众提供商的模型集成要等而 Anthropic 的修复不会等。路线图对齐与当前重点领域对齐的功能优先。目前重点包括 capabilities/hooks API、provider-adaptive tools提供商自适应工具和 Pydantic AI Harness 能力库。能力优先于核心能以 capability 形式存在的功能应进入 Pydantic AI Harness 或作为你自己的包发布——这通常是最快的路径。获得牵引力后再回来讨论上游化。如果 PR 或 issue 沉寂了在 Pydantic Slack 的#pydantic-ai频道 ping 团队并附上链接。说清你需要什么能看一下吗、我被阻塞了——这在你们的雷达上吗、我该关闭它吗都可以。如果数周都没有任何人类回应请标记出来——这是团队侧的流程失败他们想知道。安装与本地环境搭建克隆你的 fork 并进入仓库目录git clone gitgithub.com:your username/pydantic-ai.git cd pydantic-ai安装uv。最低支持的uv版本由仓库根目录 pyproject.toml 中tool.uv.required-version设置当前仓库的约束为0.9.25。安装pydantic-ai、全部依赖以及 pre-commit 钩子。如果系统里没有pre-commitmake install会顺带用uv安装它make install查看 Makefile 中install目标的真实实现可以看到它不只是uv sync还做了三件事以--frozen --all-extras --no-extra mcp-tasks --all-packages --group lint参数同步工作区跳过会与 dev 依赖组冲突的mcp-tasksextra详见 pyproject.toml 中tool.uv.conflicts的注释额外安装pydantic-ai-harness0.7.0pyright 需要类型检查 gh-aw shim而 harness 被刻意排除在 lock 之外最后安装 pre-commit 钩子。运行测试等make 命令全解团队用make管理绝大多数命令。查看可用命令列表make helpMakefile 中的help目标会解析每个目标后##后的注释并打印出彩色清单。运行代码格式化、lint、静态类型检查以及带覆盖率报告生成的测试一次执行makemake的默认目标.DEFAULT_GOAL : all等价于make all串联了format lint typecheck testcov四个阶段formatruff formatruff check --fix --fix-only自动修复lintruff format --checkruff check仅检查typecheck调用typecheck-pyright详见下节testcovcoverage run -m pytest -n auto --distloadgroup --durations20并行跑测试并生成 HTML 覆盖率报告此外Makefile 还提供test无覆盖率的快速本地测试同样支持-n auto --distloadgroup并行分发、test-all-python在 Python 3.10–3.13 四个解释器上全量测试并合并覆盖率、update-examples用pytest --update-examples tests/test_examples.py更新文档示例以及update-vcr-tests--record-moderewrite重录 VCR 磁带需要配置相应 API key。关于代码风格pyproject.toml 中的[tool.ruff]配置规定了行宽 120、目标 Python 3.10、Google 风格 docstring 约定、单引号字符串偏好并且通过banned-api强制了一些规范如用typing_extensions.TypedDict而非typing.TypedDict、用anyio.Lock而非asyncio.Lock。提交前确保代码通过这些检查。类型检查机制深度解析make typecheck全量 Pyrightmake typecheck对项目中每一个文件运行 Pyright。看 Makefile 的typecheck-pyright目标它实际执行PYRIGHT_PYTHON_IGNORE_WARNINGS1 uv run pyright [--threads N] [--pythonversion X.Y]其中PYRIGHT_PYTHON_IGNORE_WARNINGS1是为了避免每次调用都向 GitHub 请求最新版本PYRIGHT_PYTHON环境变量可指定目标 Python 版本需先运行make install-all-python准备好对应解释器。Pyright 配置位于 pyproject.toml 的[tool.pyright]typeCheckingMode strict严格模式、pythonVersion 3.10include覆盖pydantic_ai_slim、pydantic_evals、pydantic_graph、tests、examples、clai及若干脚本。make typecheck-changed增量类型检查pre-commit 钩子运行的是make typecheck-changed它只检查自上次 Pyright 通过以来内容发生变化的文件以及所有传递性导入它们的文件。全量类型检查在每次提交时都跑一遍是不划算的——这正是该脚本存在的理由。其实现位于 scripts/typecheck_changed.py值得展开理解检查点机制脚本把什么通过了记录在 git 目录下的pyright-checkpoint.json中CHECKPOINT_NAME常量因此记录是按 worktree 隔离、永远不会被提交的。模块导入图脚本用ast解析每个文件的静态 import构建第一方模块的导入边_parse_imports、_affected从而找出被变更文件传递性影响的所有文件。测试文件豁免本地运行时未变化的tests/文件绝不进入检查集——测试占了项目约三分之二的行数且大多数导入pydantic_ai若把它们纳入任何核心改动都会把整个项目重新拖回命令行。CI 才是测试文件类型错误的关卡一个源码变更若破坏测试文件的类型CI 会拦住它。放弃收窄的降级条件当无法保证收窄集合的完备性时脚本退回全量首次运行、Pyright 或 Python 版本变化包括通过PYRIGHT_PYTHON指定的版本、pyproject.toml/uv.lock/Makefile任一变更_CONFIGURATION_FILES、某个 import 现在解析到不同文件、出现可能遮蔽已装模块的新顶层模块、或变更波及超过一半项目len(affected) * 2 len(checkable)。只有三种情况把整个项目交给make typecheck-pyright设置了CI、解释器低于 Python 3.11读取 pyproject.toml 需要tomllib、或遇到脚本无法复现的 Pyright 配置如存在pyrightconfig.json或extends。性能预算PYRIGHT_TIME_BUDGET环境变量会让一次通过但超时的检查失败——如果某次变更让 Pyright 本身变慢它会在自己的 PR 里失败而不是污染main。 实践建议由于本地收窄运行只考虑被跟踪文件_tracked_files基于git ls-files对于你新增但尚未git add的文件请先自行运行make typecheck再依赖 pre-commit 钩子的绿灯。PYRIGHT_THREADS并行检查全量运行默认是单进程除非设置PYRIGHT_THREADS。CI 将其设为autoexport PYRIGHT_THREADSauto该变量开启 Pyright 的并行检查阶段在更短的墙钟时间内得到相同诊断auto是每个逻辑核心最多一个 worker正整数则封顶 worker 数。注意只有make typecheck-pyright读取它因此钩子在收窄运行时不会启用并行。请导出而非逐命令设置这样每次make typecheck都能生效。每个 worker 都是一个完整的 Node 进程因此只有在机器内存足以容纳它们时才划算——内存已接近上限的机器会发生交换反而比默认的单进程更慢。取消该变量或设为1即回到单进程。任何 Pyright 无法解析为正整数的值包括0和off都意味着auto。Makefile 中PYRIGHT_THREADS ?的注释也引用了 pyright 上游的parseThreadsArgValue实现来佐证这一取值语义而 .github/workflows/ci.yml 中确实设置了PYRIGHT_THREADS: auto。文档变更规范docs/navigation.yml是 Pydantic AI 文档的侧边栏、公开路由和重定向的唯一所有者。添加、删除或移动页面时必须同步更新它。路由规则docs/navigation.yml中所有路由都相对于 Pydantic AI 文档根。每个页面在slug中给出完整的规范路由aliases只用于重定向源。两者都不要加/ai前缀或前导斜杠。从文件头部可以看到实际结构version: 1和navigation列表每个条目包含section分区、path源文件相对路径、slug规范路由以及可选的aliases旧路由重定向。例如 Installation 页面的slug是overview/installaliases包含installation和install两个历史路径。验证导航变更的方式请维护者给 PR 打上trigger:docs标签。这会检查pydantic/unified-docs中的导航清单、被引用的 Markdown 文件、路由、别名和重定向并把结果贴在 PR 上注意它不构建渲染预览。CI 会检查文档页面之间的每个链接是否都能解析包括锚点遇到Cannot find fragment即失败。由于标题的锚点由其文本生成重命名标题会静默破坏指向它的所有链接。因此对于被链接的标题要用{#custom-id}固定锚点——这样标题文本可以自由改动而锚点不移动。本文开头提到的{#new-model-rules}锚点就是这一做法的实例。添加新模型到 Pydantic AI 的规则为了避免维护者工作量过载团队无法接受所有模型贡献因此制定了明确的准入规则以减少失望和浪费的功夫要添加带额外依赖的新模型该依赖需要在 PyPI 上持续 3 个月以上每月超过 50 万次下载。要添加内部复用其他模型逻辑、且无额外依赖的模型该模型的 GitHub 组织总 star 数需超过 2 万。其他任何只是自定义 URL API key的模型团队乐意添加一段话的描述附上链接和要使用的 URL 说明。其他需要更多逻辑的模型建议你发布自己的 Python 包pydantic-ai-xxx它依赖pydantic-ai-slim并实现一个继承自团队Model抽象基类的模型。ModelABC 位于 pydantic_ai_slim/pydantic_ai/models/init.pyclass Model(AbstractModel, Generic[InterfaceClient])是接入新模型的核心契约。如果你不确定是否该添加模型请先 创建 issue 讨论。仓库中 pydantic_ai_slim/pydantic_ai/models 目录下已实现的 33 个模型文件OpenAI、Anthropic、Google、Bedrock、Cohere、Mistral、xAI、Groq、OpenRouter 等展示了这一抽象如何被各种提供商实现而 docs/install.md 列出了pydantic-ai-slim的全部可选分组openai、google、anthropic、bedrock、xai、mcp、ui、logfire等独立模型包正是通过声明这些 extra 依赖来保持轻量的。总结一份贡献的完整生命周期把全文串起来一份 Pydantic AI 贡献的典型生命周期是判断归属这是核心agent 循环、模型提供商还是 capability后者去 Pydantic AI Harness 或自发布pydantic-ai-name包。先开 issue描述问题而非方案附最小复现与 Logfire 链接成为 champion 或找到 champion。等分配维护者认可方案并分配 issue 后才开 PR未被分配的 PR 可能被自动关闭。本地验证make install搭好环境make跑完整套格式化、lint、类型检查与测试用PYRIGHT_THREADSauto加速全量 Pyright文档改动同步更新docs/navigation.yml并固定被链接标题的锚点。PR 阶段不要 force-push、不要追未对齐 PR 的绿 CI、把自动评审当建议需要推进时在 Pydantic Slack#pydantic-ai频道 ping。等待与配合重写团队可能重写或取代你的代码你仍保留原作者署名若数周无人回应主动标记。理解并接受这套优先级驱动、重写取向的协作哲学是让贡献真正落地的第一步。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pydantic AI 贡献指南：从 Issue 到合并的完整协作流程与工程实践
Pydantic AI 贡献指南从 Issue 到合并的完整协作流程与工程实践【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-aiPydantic AI 是一个由小型核心团队维护的 AI Agent 框架仓库其贡献流程与传统开源项目有显著差异维护者按对最多用户最有价值的优先级处理 issue 与 PR而非按提交顺序代码被视作起点而非成品维护者可能重写贡献的代码类型检查、文档导航、新模型准入等环节都有一套精确且与众不同的工程规则。本文以仓库内 docs/contributing.md 为骨架结合 Makefile、pyproject.toml、scripts/typecheck_changed.py 等仓库源码与配置完整梳理从提出想法到代码合并的每个环节帮助你避免最常见的踩坑点让贡献真正被看见、被合并。我们如何工作短版本Pydantic AI 由一个小团队维护他们根据什么对最多用户最有价值来设定自己的优先级并按此顺序处理 issue 和 PR——而不是按到达顺序。这一点决定了整个贡献流程的基调你的提交质量再高如果不在维护者的优先级里就可能长时间无人问津。针对不同类型的诉求官方给出的路径是发现 bug开一个 issue包含清晰描述和最小可复现示例。附带一个 Logfire trace 链接能显著加快调试速度。想要新功能或 API 变更开 issue 描述你正在解决的问题不要直接写代码。想帮助构建某个功能在 issue 下评论说明你为什么需要它、你能带来什么上下文。这就是下文要讲的 champion拥护者机制。有修复或代码要分享确保维护者已在 issue 上认可方案并分配给你然后再开 PR。写代码之前先对齐再动手对于任何非平凡的工作在写代码之前先与维护者对齐方案。一个预先对齐过的 PR 比一个冷启动的 PR 合并快得多。平凡修复Trivial fixes拼写错误、失效链接、小的文档改进、显而易见的一行修复直接开 PR 即可不需要 issue。Bug 修复如果修复方式可能有多种走向或者你不确定它到底算不算 bug先开 issue。包含最小可复现示例理想情况下附上展示问题的 Logfire trace 链接。对于边界清晰的 bug维护团队可能内部直接生成修复——此时你最有价值的贡献是提交一份清晰的报告然后验证修复在你的用例下是否有效。功能、集成或 API 变更写代码之前先问一个问题这个变更真的需要进入核心吗大多数新的 Agent 行为属于 Pydantic AI Harness官方能力库而不是本仓库。Pydantic AI 核心只负责 agent 循环agent loop、模型提供商以及需要模型特定支持或对 Agent 体验至关重要的能力。而独立的 capabilities——如 guardrails护栏、memory记忆、context management上下文管理、文件系统访问等——属于 harness那里可以更快迭代。仓库内 docs/extensibility.md 对边界做了详细说明capabilities 是 Pydantic AI 的主要扩展点它们把工具、生命周期钩子、指令和模型设置打包成可复用单元如果你想贡献一个 capability应当到 Pydantic AI Harness 开 issue而不是 pydantic-ai。你也可以用pydantic-ai-name命名约定把自己的 capability 发布成独立包参见 Publishing capability packages。如果确实属于核心流程是先搜索。如果已有 issue 覆盖你的需求直接评论如果最近的 issue 只是相关开一个新 issue 并链接到它。描述问题而不只是解决方案。告诉团队你在构建什么、什么阻塞了你、你尝试过什么。这些上下文比代码更重要。在构建之前提出计划。在 issue 上贴一份简短计划或者开一个只包含PLAN.md的草稿 PR。对于较大的功能维护者会与贡献者进行简短视频通话来迭代设计——20 分钟的通话往往能省下数周的异步评审周期。等待分配。维护者需要在 issue 上认可方案并分配给你之后你才能开 PR。未被分配的 PR 可能被自动关闭。⚠️ 警告原文即强调在没有预先对齐的情况下写一个大功能 PR是贡献停滞或关闭的最常见原因。Champions让功能进入优先级的机制Champion拥护者是需要某个功能、对问题有上下文、并愿意投入时间帮助团队把它做对的人。如果你愿意拥护一个功能在 issue 下评论说明你在构建什么、为什么需要它、你能贡献什么领域知识、测试、验证。团队优先考虑那些有生产级用例的 champion 站出来的功能。没有 champion 的功能会一直留在 backlog 里直到团队自己将其列为优先或某个有真实上下文的人出现。成为 champion 不代表要写代码而是塑造计划并验证结果。对于重要功能团队会安排通话一起迭代设计。功能发布时champion 会被署名列为共同作者。审查期间你会遇到什么按优先级审查而非按提交顺序团队不会自动分诊每一个新 PR。未预先对齐的 issue 上的 PR 不在评审队列中——无论它写得多好。如果没有维护者在 issue 上同意变更并分配给你请默认他们没看到你的 PR。即使是对已经参与过的代码所有贡献代码都被视为起点而不是成品。团队根据功能对项目的重要性来评审和排序 PR而不是看代码投入了多少精力。这是对传统开源工作方式的一种改变团队宁愿坦诚相告也不愿让 PR 毫无音讯地挂在那里。想知道 PR 状态最好的方式是到 Pydantic Slack 的#pydantic-ai频道 ping 一下。我们可能重写或取代你的代码贡献的代码被视为示例它展示提议的变更并证明方案可行而不是最终合并的形态。对于非平凡的变更你能给团队最有用的东西是一个计划加一个可运行的示例——而不是一份打磨好、可随时合并的实现。在任何 PR 上维护者都可能向你的分支推送提交、开一个取代你的后续 PR、或者从头重写。出于安全原因团队倾向于重写贡献代码而非原样合并。你仍会被署名为原作者。因此请不要在未对齐的 PR 上花精力追 CI 绿灯、处理每条自动评审意见、或为合并冲突做 rebase。如果团队接手推进这个变更这些打磨会在重写时被丢弃。让方案跑通然后停下来在 Slack 上 ping 团队。另外不要对已开的 PR 做 force-push。重写其提交会使之前的评审失效请推送后续提交follow-up commits合并时会由维护者 squash。自动评审是建议性的不是门槛PR 会自动接受 Devin 和团队自有工具的评审但这些评审是建议性的机器人的 approval 不意味着你的 PR 可以合并——只有人类维护者的评审才算数。机器人的发现不意味着你必须处理——如果你不同意直接说明。如果自动评审在你的 PR 上产生噪音告诉团队。他们会用这些反馈来调优工具。仓库的 .github/workflows 目录里可以看到这套自动化矩阵的真实规模pydantic-ai-pr-reviewPR 评审、pydantic-ai-bug-hunterbug 猎人、pydantic-ai-regression-detector回归检测、pydantic-ai-docs-drift文档漂移检测等数十个工作流协同运转。优先级如何权衡团队收到的贡献远超可评审量他们把精力集中在影响最大的地方无法承诺处理每一个 PR即使是好 PR。优先级权重如下用户需求更多用户需要的功能优先有生产用例 champion 支持的功能胜过投机性的提案。提供商重要性影响前沿提供商Anthropic、OpenAI、Google或已知重度使用的提供商的工作优先。小众提供商的模型集成要等而 Anthropic 的修复不会等。路线图对齐与当前重点领域对齐的功能优先。目前重点包括 capabilities/hooks API、provider-adaptive tools提供商自适应工具和 Pydantic AI Harness 能力库。能力优先于核心能以 capability 形式存在的功能应进入 Pydantic AI Harness 或作为你自己的包发布——这通常是最快的路径。获得牵引力后再回来讨论上游化。如果 PR 或 issue 沉寂了在 Pydantic Slack 的#pydantic-ai频道 ping 团队并附上链接。说清你需要什么能看一下吗、我被阻塞了——这在你们的雷达上吗、我该关闭它吗都可以。如果数周都没有任何人类回应请标记出来——这是团队侧的流程失败他们想知道。安装与本地环境搭建克隆你的 fork 并进入仓库目录git clone gitgithub.com:your username/pydantic-ai.git cd pydantic-ai安装uv。最低支持的uv版本由仓库根目录 pyproject.toml 中tool.uv.required-version设置当前仓库的约束为0.9.25。安装pydantic-ai、全部依赖以及 pre-commit 钩子。如果系统里没有pre-commitmake install会顺带用uv安装它make install查看 Makefile 中install目标的真实实现可以看到它不只是uv sync还做了三件事以--frozen --all-extras --no-extra mcp-tasks --all-packages --group lint参数同步工作区跳过会与 dev 依赖组冲突的mcp-tasksextra详见 pyproject.toml 中tool.uv.conflicts的注释额外安装pydantic-ai-harness0.7.0pyright 需要类型检查 gh-aw shim而 harness 被刻意排除在 lock 之外最后安装 pre-commit 钩子。运行测试等make 命令全解团队用make管理绝大多数命令。查看可用命令列表make helpMakefile 中的help目标会解析每个目标后##后的注释并打印出彩色清单。运行代码格式化、lint、静态类型检查以及带覆盖率报告生成的测试一次执行makemake的默认目标.DEFAULT_GOAL : all等价于make all串联了format lint typecheck testcov四个阶段formatruff formatruff check --fix --fix-only自动修复lintruff format --checkruff check仅检查typecheck调用typecheck-pyright详见下节testcovcoverage run -m pytest -n auto --distloadgroup --durations20并行跑测试并生成 HTML 覆盖率报告此外Makefile 还提供test无覆盖率的快速本地测试同样支持-n auto --distloadgroup并行分发、test-all-python在 Python 3.10–3.13 四个解释器上全量测试并合并覆盖率、update-examples用pytest --update-examples tests/test_examples.py更新文档示例以及update-vcr-tests--record-moderewrite重录 VCR 磁带需要配置相应 API key。关于代码风格pyproject.toml 中的[tool.ruff]配置规定了行宽 120、目标 Python 3.10、Google 风格 docstring 约定、单引号字符串偏好并且通过banned-api强制了一些规范如用typing_extensions.TypedDict而非typing.TypedDict、用anyio.Lock而非asyncio.Lock。提交前确保代码通过这些检查。类型检查机制深度解析make typecheck全量 Pyrightmake typecheck对项目中每一个文件运行 Pyright。看 Makefile 的typecheck-pyright目标它实际执行PYRIGHT_PYTHON_IGNORE_WARNINGS1 uv run pyright [--threads N] [--pythonversion X.Y]其中PYRIGHT_PYTHON_IGNORE_WARNINGS1是为了避免每次调用都向 GitHub 请求最新版本PYRIGHT_PYTHON环境变量可指定目标 Python 版本需先运行make install-all-python准备好对应解释器。Pyright 配置位于 pyproject.toml 的[tool.pyright]typeCheckingMode strict严格模式、pythonVersion 3.10include覆盖pydantic_ai_slim、pydantic_evals、pydantic_graph、tests、examples、clai及若干脚本。make typecheck-changed增量类型检查pre-commit 钩子运行的是make typecheck-changed它只检查自上次 Pyright 通过以来内容发生变化的文件以及所有传递性导入它们的文件。全量类型检查在每次提交时都跑一遍是不划算的——这正是该脚本存在的理由。其实现位于 scripts/typecheck_changed.py值得展开理解检查点机制脚本把什么通过了记录在 git 目录下的pyright-checkpoint.json中CHECKPOINT_NAME常量因此记录是按 worktree 隔离、永远不会被提交的。模块导入图脚本用ast解析每个文件的静态 import构建第一方模块的导入边_parse_imports、_affected从而找出被变更文件传递性影响的所有文件。测试文件豁免本地运行时未变化的tests/文件绝不进入检查集——测试占了项目约三分之二的行数且大多数导入pydantic_ai若把它们纳入任何核心改动都会把整个项目重新拖回命令行。CI 才是测试文件类型错误的关卡一个源码变更若破坏测试文件的类型CI 会拦住它。放弃收窄的降级条件当无法保证收窄集合的完备性时脚本退回全量首次运行、Pyright 或 Python 版本变化包括通过PYRIGHT_PYTHON指定的版本、pyproject.toml/uv.lock/Makefile任一变更_CONFIGURATION_FILES、某个 import 现在解析到不同文件、出现可能遮蔽已装模块的新顶层模块、或变更波及超过一半项目len(affected) * 2 len(checkable)。只有三种情况把整个项目交给make typecheck-pyright设置了CI、解释器低于 Python 3.11读取 pyproject.toml 需要tomllib、或遇到脚本无法复现的 Pyright 配置如存在pyrightconfig.json或extends。性能预算PYRIGHT_TIME_BUDGET环境变量会让一次通过但超时的检查失败——如果某次变更让 Pyright 本身变慢它会在自己的 PR 里失败而不是污染main。 实践建议由于本地收窄运行只考虑被跟踪文件_tracked_files基于git ls-files对于你新增但尚未git add的文件请先自行运行make typecheck再依赖 pre-commit 钩子的绿灯。PYRIGHT_THREADS并行检查全量运行默认是单进程除非设置PYRIGHT_THREADS。CI 将其设为autoexport PYRIGHT_THREADSauto该变量开启 Pyright 的并行检查阶段在更短的墙钟时间内得到相同诊断auto是每个逻辑核心最多一个 worker正整数则封顶 worker 数。注意只有make typecheck-pyright读取它因此钩子在收窄运行时不会启用并行。请导出而非逐命令设置这样每次make typecheck都能生效。每个 worker 都是一个完整的 Node 进程因此只有在机器内存足以容纳它们时才划算——内存已接近上限的机器会发生交换反而比默认的单进程更慢。取消该变量或设为1即回到单进程。任何 Pyright 无法解析为正整数的值包括0和off都意味着auto。Makefile 中PYRIGHT_THREADS ?的注释也引用了 pyright 上游的parseThreadsArgValue实现来佐证这一取值语义而 .github/workflows/ci.yml 中确实设置了PYRIGHT_THREADS: auto。文档变更规范docs/navigation.yml是 Pydantic AI 文档的侧边栏、公开路由和重定向的唯一所有者。添加、删除或移动页面时必须同步更新它。路由规则docs/navigation.yml中所有路由都相对于 Pydantic AI 文档根。每个页面在slug中给出完整的规范路由aliases只用于重定向源。两者都不要加/ai前缀或前导斜杠。从文件头部可以看到实际结构version: 1和navigation列表每个条目包含section分区、path源文件相对路径、slug规范路由以及可选的aliases旧路由重定向。例如 Installation 页面的slug是overview/installaliases包含installation和install两个历史路径。验证导航变更的方式请维护者给 PR 打上trigger:docs标签。这会检查pydantic/unified-docs中的导航清单、被引用的 Markdown 文件、路由、别名和重定向并把结果贴在 PR 上注意它不构建渲染预览。CI 会检查文档页面之间的每个链接是否都能解析包括锚点遇到Cannot find fragment即失败。由于标题的锚点由其文本生成重命名标题会静默破坏指向它的所有链接。因此对于被链接的标题要用{#custom-id}固定锚点——这样标题文本可以自由改动而锚点不移动。本文开头提到的{#new-model-rules}锚点就是这一做法的实例。添加新模型到 Pydantic AI 的规则为了避免维护者工作量过载团队无法接受所有模型贡献因此制定了明确的准入规则以减少失望和浪费的功夫要添加带额外依赖的新模型该依赖需要在 PyPI 上持续 3 个月以上每月超过 50 万次下载。要添加内部复用其他模型逻辑、且无额外依赖的模型该模型的 GitHub 组织总 star 数需超过 2 万。其他任何只是自定义 URL API key的模型团队乐意添加一段话的描述附上链接和要使用的 URL 说明。其他需要更多逻辑的模型建议你发布自己的 Python 包pydantic-ai-xxx它依赖pydantic-ai-slim并实现一个继承自团队Model抽象基类的模型。ModelABC 位于 pydantic_ai_slim/pydantic_ai/models/init.pyclass Model(AbstractModel, Generic[InterfaceClient])是接入新模型的核心契约。如果你不确定是否该添加模型请先 创建 issue 讨论。仓库中 pydantic_ai_slim/pydantic_ai/models 目录下已实现的 33 个模型文件OpenAI、Anthropic、Google、Bedrock、Cohere、Mistral、xAI、Groq、OpenRouter 等展示了这一抽象如何被各种提供商实现而 docs/install.md 列出了pydantic-ai-slim的全部可选分组openai、google、anthropic、bedrock、xai、mcp、ui、logfire等独立模型包正是通过声明这些 extra 依赖来保持轻量的。总结一份贡献的完整生命周期把全文串起来一份 Pydantic AI 贡献的典型生命周期是判断归属这是核心agent 循环、模型提供商还是 capability后者去 Pydantic AI Harness 或自发布pydantic-ai-name包。先开 issue描述问题而非方案附最小复现与 Logfire 链接成为 champion 或找到 champion。等分配维护者认可方案并分配 issue 后才开 PR未被分配的 PR 可能被自动关闭。本地验证make install搭好环境make跑完整套格式化、lint、类型检查与测试用PYRIGHT_THREADSauto加速全量 Pyright文档改动同步更新docs/navigation.yml并固定被链接标题的锚点。PR 阶段不要 force-push、不要追未对齐 PR 的绿 CI、把自动评审当建议需要推进时在 Pydantic Slack#pydantic-ai频道 ping。等待与配合重写团队可能重写或取代你的代码你仍保留原作者署名若数周无人回应主动标记。理解并接受这套优先级驱动、重写取向的协作哲学是让贡献真正落地的第一步。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考