Pydantic AI 文档编写规范：docs/AGENTS.md 的链接约定、可执行示例契约与首页同步机制

Pydantic AI 文档编写规范docs/AGENTS.md 的链接约定、可执行示例契约与首页同步机制【免费下载链接】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 官方文档docs/目录的质量由一份机器可执行的约定文件 docs/AGENTS.md 约束它规定了 API 元素引用式链接、admonition 提示块、提供商标注列、fence 属性排除等写法并要求docs/index.md与仓库README.md两个门面保持代码逐字一致。本文逐条解析这些规范的写法动机并结合 tests/test_docs_parity.py、tests/test_examples.py 等验证源码说明这些约定如何在 CI 中落地、读者与贡献者应如何遵循。一、文档约定体系docs/AGENTS.md 的定位docs/AGENTS.md 是docs/目录的专用约定文件目录级 instructions开头声明遵循通用 文档指南这些规则覆盖docs/下的已发布 Markdown。agent_docs/documentation.md 则给出面向所有用户可见文本文档、docstring、注释、示例的总原则以读者价值为先保留每个有用的事实、条件、后果、限制与区分逐句检验删掉它读者是否损失信息每个概念在全仓库使用一个精确术语每个维护中的事实只有一个权威归属canonical home其他地方链接过去而非复制面向读者的示例使用当前前沿模型而非照抄静态示例。docs/AGENTS.md在此之上补充了四组可操作的细则链接与结构、示例、评审、首页front pages同步契约。值得强调的是这些规则不是软性的风格建议——其中多条示例可执行性、首页一致性由测试代码直接强制检查后文会给出证据。二、链接与结构引用式链接、admonition 与提供方页面隔离2.1 API 元素使用引用式链接规范第一条要求Use reference-style links for API elements:[ElementName][module.path.ElementName]. They provide hover documentation and API navigation on the published site.即引用 API 符号时写成[ElementName][module.path.ElementName]形式元素名 以模块路径为目标的引用定义而不是行内 URL 链接。这在发布站上能悬停显示文档、并导航到 API 参考页。仓库中大量页面已按此约定书写例如 docs/models/anthropic.md 关联页与 docs/api/models/anthropic.md API 参考页的分工以及 docs/native-tools.md 中大量形如 [NativeToolReturnPart][pydantic_ai.messages.NativeToolReturnPart] 的引用式链接。2.2 提示块统一用 admonition不用 blockquote规范第二条调用提示统一使用 MkDocs 的 admonition 语法而不是 blockquote 或 GitHub alerts!!! note 标题 提示正文 !!! warning 标题 警告正文在 docs/tools.md 中可以看到!!! info Function tools vs. RAG、!!! tip Debugging Tool Calls等实际用例docs/models/anthropic.md 使用!!! note Claude Opus 4.7 / 4.8 / 5 migration提示温度参数自动剥离行为。admonition 由 unified-docs 渲染成醒目的彩色提示块语义强于引用块。2.3 项目名固定写为Pydantic AI文档中项目名称的书写形式固定为Pydantic AI两个独立单词各自大写用于搜索与术语一致性。2.4 提供方相关内容隔离到专用页面规范第四条规定提供方provider专属的配置与行为一律放在docs/models/{provider}.md用户指南和docs/api/models/{provider}.mdAPI 参考中通用指南只放一个最小的、提供方无关的示例并链接到对应提供方页面。这与 agent_docs/documentation.md 中每个事实只有一个权威归属链接而非复制的原则一脉相承——例如通用 docs/embeddings.md、docs/models/overview.md 讲通用用法而docs/models/anthropic.md、docs/models/google.md等承载各家的安装、鉴权、环境变量细节。2.5 提供方特性表的标准标注规范第五条针对功能 × 提供方的矩阵表约定用Notes或Provider Support Notes列承载变体、限制与特殊取值并使用标准标签列/标签含义Full feature support完整支持该特性Limited parameter support支持但参数受限需说明限制条件Unsupported列放不支持的变体docs/native-tools.md 是该约定的标准样板例如其中 Web 搜索、图像生成特性表逐行使用 Full feature support. / Limited parameter support. … 的措辞并在注释里给出受限原因如仅新模型支持需走 compound models。这种固定词汇让读者跨表格比对时能直接按标签搜索、过滤。三、示例规范可执行优先排除项写在 fence 上3.1 示例必须可执行Keep code examples executable unless they require external services, credentials, or non-deterministic behavior. Use mocks or fixtures when they keep the example representative.这条规则的执行者正是 tests/test_examples.py它会抓取README.md、docs/、pydantic_ai_slim/、pydantic_graph/、pydantic_evals/下所有代码围栏find_examples(README.md, docs, ...)逐块lintruff 检查 实际运行 断言print输出与文档中记录一致eval_example.run_print_check(...)。测试运行时通过mocker.patch把httpx/httpx2的get/post全部替换为返回 202 的空响应注入全套假 API keyOPENAI_API_KEY、ANTHROPIC_API_KEY等约 30 个环境变量甚至把 Codex 的auth.json也伪造出来——从源码结构看其设计目标就是让文档里的每一段示例代码在 CI 中真实跑通。3.2 排除项写在 fence 属性上而非代码内Put example-level exclusions on the fence, such as{testskip lintskip}, rather than adding tooling suppressions to pedagogical code.即如果某个示例无法或不值得运行/检查排除标记放在围栏的属性里python {testskip lintskip} # 教学示意代码不参与测试tests/test_examples.py 中读取这些属性并据此跳过当 opt_test.startswith(skip) and opt_lint.startswith(skip) 时执行 pytest.skip(both running code and lint skipped)testskip 只跳运行仍做 lintci_only 变体则只在 GITHUB_ACTIONStrue 时运行。[docs/agent.md](https://link.gitcode.com/i/bc39e9eb261d1647d830c2c6df9a1300) 中可见 python {testskip lintskip formatskip}、 yaml {testskip} 等实际用法。这样教学代码保持干净可读# noqa 之类的工具抑制不会污染读者看到的示例。 ### 3.3 示例的拆分与合并原则 规范给出了两个方向的判断标准 - **合并**若一个示例 若干说明能保留全部有意义差异就把参数变体合并进一个示例附文字说明各参数取值 - **拆分**当使用场景、前置条件或约束不同比如不同的鉴权方式、不同的输出类型则拆成独立示例。 同时要求示例应展示可信的用户任务或决策不引入与特性无关的复杂度。配合 [agent_docs/documentation.md](https://link.gitcode.com/i/1ffd9c0717003ff180bf853c418e5dc7) 中面向读者的示例使用当前前沿模型的要求示例既贴近真实使用又不冗余。 ## 四、首页同步契约docs/index.md 与 README.md 的一个故事两个表面 [docs/AGENTS.md](https://link.gitcode.com/i/3dcd951501494ba191e512934d1c6b92) 的后半部分规定了本仓库最有特色的一条契约——文档索引页 [docs/index.md](https://link.gitcode.com/i/5b6f6d9337dbc0ac82ac4f819ae71b03) 与仓库 [README.md](https://link.gitcode.com/i/6636f9802b2f7542c32100dcfae329d3) 讲同一个故事只是渲染在不同表面。两者必须同步共享的措辞与代码示例但各自保留渲染器所需的标记差异 | 维度 | docs/index.md | README.md | | --- | --- | --- | | 链接形式 | 相对链接 | 指向文档站的绝对链接 | | 分节 | tab 语法 ... | 用 ### 小节替代 tab | | 代码注释 | 编号标注# (1)!、# (2)! | 普通的单行 # 注释 | | 代码内容 | 逐字相同 | 逐字相同 | 关键约束是**镜像代码示例必须 code-identical**——只有注释、标注、链接形式和 fence 属性允许不同。此外README 中无法在文档测试环境运行的片段通过 tests/test_examples.py 按内容排除而不是加 fence 属性这样 README 的围栏保持裸状态、兼容 GitHub 的 Markdown 渲染。 ### 4.1 一致性由 test_docs_parity.py 强制校验 契约的执行者是 [tests/test_docs_parity.py](https://link.gitcode.com/i/fae2b13810cb6cc11586d48dbe977e50)文件头注释直接引用了 docs/AGENTS.md 的 Front pages 一节。其机制 1. **镜像示例清单**MIRRORED_EXAMPLE_MARKERS 列出必须在两处同时存在且代码一致的关键示例如 Advisor(openai:gpt-5.6-sol)、class Sentiment(BaseModel):、agent.realtime(openai:gpt-realtime-2.1) 等 7 个标记 2. **提取与归一化**_python_blocks() 用正则抽取 python 围栏内容并去除 docs 中为 tab 缩进产生的公共缩进_normalize() 剥掉行尾 # 注释与空行使得带编号标注和带普通注释两种变体可以**只按代码本身比较** 3. **断言**每个 marker 在两处都命中且归一化后完全相等否则报 front-page example diverged between docs/index.md and README.md 4. **排版一致性**test_front_pages_have_no_em_dashes 还检查 [docs/index.md](https://link.gitcode.com/i/5b6f6d9337dbc0ac82ac4f819ae71b03)、[README.md](https://link.gitcode.com/i/6636f9802b2f7542c32100dcfae329d3)、[docs/interfaces.md](https://link.gitcode.com/i/70c55c5520b066d288b0e274c8af1ace) 三个页面不出现 em dash—保持风格统一。 对照仓库实际内容可以看到约定在起作用[docs/index.md](https://link.gitcode.com/i/5b6f6d9337dbc0ac82ac4f819ae71b03) 中 class SupportDependencies: 后跟 # (1)!、db: DatabaseConn # (2)! 编号标注而 [README.md](https://link.gitcode.com/i/6636f9802b2f7542c32100dcfae329d3) 的同一示例用普通注释两者代码逐字一致。 ### 4.2 跨仓库检查义务 规范最后一条当共享的 tagline 或 Harness 相关表述变更时还需检查 Harness 仓库的 docs/index.md 与 README.md。这说明该同步契约横跨多个仓库docs/AGENTS.md 把它写进本仓库是为了提醒贡献者改一面看两面。 ## 五、评审与发布unified-docs 预览与导航注册 规范Review一节只有一条合并前在 unified-docs 预览中渲染文档。结合 [docs/contributing.md](https://link.gitcode.com/i/7830a19772d949c6765e14e782694b9c) 的Documentation Changes一节可补全整条发布链路 - 文档由 pydantic/unified-docs 发布[docs/navigation.yml](https://link.gitcode.com/i/be6a51ec5080a8927d6d0af154bafaf4) 独占 Pydantic AI 文档站的侧边栏、路由与重定向——新增、删除、移动页面都必须同步更新该文件 - 路由均相对文档根slug 写完整规范化路由aliases 只用于重定向来源且都不要加 /ai 前缀或前导斜杠 - CI 会检查所有文档页间链接含 anchor能否解析标题重命名会悄悄弄断所有指向它的链接因此被引用的标题要用 {#custom-id} 固定 anchor——这条与 [agent_docs/documentation.md](https://link.gitcode.com/i/1ffd9c0717003ff180bf853c418e5dc7) 中需要稳定锚点时加 {#custom-id}的通则一致。 ## 六、小结如何遵循这套规范 为 docs/ 下新增或修改页面时可按以下清单核对全部依据 [docs/AGENTS.md](https://link.gitcode.com/i/3dcd951501494ba191e512934d1c6b92) 与对应验证源码 1. API 符号引用写成 [ElementName][module.path.ElementName]项目名写 Pydantic AI提示用 !!! note/!!! warning不用 blockquote 2. 提供方专属内容放入 docs/models/{provider}.md 与 docs/api/models/{provider}.md通用指南只留提供方无关的最小示例并链接过去 3. 特性矩阵使用 Full feature support / Limited parameter support 标准标签不支持项放入 Unsupported 列 4. 示例默认可执行tests/test_examples.py 会真实运行并比对输出不可执行的把排除写在 fence 属性{testskip lintskip}而非代码内 5. 示例按场景/前置条件不同则拆、参数变体可合并的原则组织展示可信的用户任务 6. 改动 docs/index.md 时同步 README.md反之亦然保持代码逐字一致、仅注释/链接形式不同由 tests/test_docs_parity.py 守护 7. 新页面注册进 [docs/navigation.yml](https://link.gitcode.com/i/be6a51ec5080a8927d6d0af154bafaf4)被引用标题加 {#custom-id}合并前走 unified-docs 预览。 这套约定的核心思路是把文档风格从评审人的口头判断沉淀为约定文件里的明确条款再用 parity 测试与示例执行测试把它们变成 CI 可失败的硬约束——这也是 Pydantic AI 文档能长期保持示例即契约风格的关键机制。【免费下载链接】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），仅供参考