仓库结构和贡献指南

相关源文件

• .github/authors_schema.json
• .github/pull_request_template.md
• .github/registry_schema.json
• CONTRIBUTING.md
• README.md
• images/openai-cookbook-white.png
• images/openai-cookbook.png

本文档解释了 OpenAI Cookbook 仓库的组织方式、注册表驱动的内容管理系统以及贡献新示例和指南的流程。该 Cookbook 是一个全面的实用示例和模式集合，用于处理 OpenAI API。

有关特定 API 使用模式和示例的信息，请参阅核心 API 模式。有关为您的用例选择合适模型的指导，请参阅模型选择和指南。

仓库组织结构

OpenAI Cookbook 采用注册表驱动的架构，其中内容发现和网站生成由中央配置文件控制。这种方法确保了组织的一致性，并支持示例和指南的自动化处理。

来源： README.md1-21 .github/pull_request_template.md15 .github/registry_schema.json1-42 .github/authors_schema.json1-25

注册表系统架构

内容管理系统以两个主要的 YAML 文件为核心，这两个文件定义了所有内容和贡献者。这种注册表驱动的方法实现了自动化验证、网站生成和内容发现。

来源： .github/registry_schema.json4-40 .github/authors_schema.json4-22

注册表条目字段

registry.yaml 中的每个内容条目都必须包含 JSON 模式中定义的以下必填字段：

字段	类型	必填	描述
title	字符串	是	内容的显示标题
path	字符串	是	相对于仓库根目录的文件路径
tags	string[]	是	内容组织分类
authors	string[]	是	来自 authors.yaml 的作者标识符
date	字符串	否	发布日期（YYYY-MM-DD 格式）
redirects	string[]	否	重定向到此内容的替代路径
archived	布尔值	否	内容是否已归档/已弃用

来源： .github/registry_schema.json7-39

作者数据库结构

authors.yaml 文件维护贡献者信息，并符合验证模式要求：

字段	类型	必填	描述
名称	字符串	是	完整显示名称
website	URI	是	作者网站或个人资料 URL
avatar	URI	是	个人资料图片 URL

来源： .github/authors_schema.json8-20

贡献工作流程

该仓库通过 GitHub 拉取请求（Pull Request）实施结构化的贡献流程，其中包括自动化验证和手动审查要求。

来源： .github/pull_request_template.md1-25 CONTRIBUTING.md1-7

拉取请求（PR）要求

贡献者在提交新内容时必须完成以下清单：

1. 注册表更新：在 registry.yaml 中添加条目，并可选地在 authors.yaml 中添加
2. 自查：根据贡献准则进行评估
3. 模板填写：填写拉取请求模板的所有部分

来源： .github/pull_request_template.md15-16

质量准则

所有贡献都将根据六个维度，采用 1-4 分制进行评估，接受的最低分数要求为 3 分：

标准	描述
相关性	内容与 OpenAI 技术相关，并为用户提供价值
唯一性	提供现有文档未涵盖的新见解
拼写和语法	没有语言错误
清晰性	组织良好，易于理解
正确性	信息准确，代码可执行
完整性	充分解释，并附带必要的参考文献和引用

来源： .github/pull_request_template.md17-23

内容组织模式

该仓库遵循既定的模式来组织不同类型的内容，明确区分交互式示例和解释性指南。

来源： README.md12-14 .github/registry_schema.json19-24

验证和模式强制

该仓库使用 JSON Schema 验证来确保数据一致性并防止畸形的注册表条目。

注册表模式验证

registry_schema.json 定义了严格的验证规则：

• 数组结构：注册表必须是内容对象的数组
• 必填字段：title、path、tags 和 authors 是强制性的
• 类型安全：强制执行字符串、数组和布尔类型
• 日期格式：如果提供，则为 ISO 日期格式（YYYY-MM-DD）
• 无额外属性：防止出现未记录的字段

来源： .github/registry_schema.json3-41

作者模式验证

authors_schema.json 强制执行贡献者数据完整性：

• 模式属性：具有结构化值的灵活作者键
• URI 验证：网站和头像字段必须是有效的 URI
• 必填字段：所有作者属性（姓名、网站、头像）都是强制性的
• 类型安全：强制执行字符串和 URI 格式

来源： .github/authors_schema.json4-24

与网站生成集成

注册表系统驱动着 cookbook.openai.com 上的 Cookbook 网站的自动化生成，在仓库内容和用户可见文档之间提供了无缝桥梁。

来源： README.md10 .github/pull_request_template.md15

这种注册表驱动的架构确保所有内容在整个 Cookbook 生态系统中保持可发现性、正确分类和一致格式。