generative-ai-for-beginners 仓库 AGENTS.md 实践指南：环境配置、开发工作流与贡献规范全解析

generative-ai-for-beginners 仓库 AGENTS.md 实践指南：环境配置、开发工作流与贡献规范全解析

【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners

本文以 AGENTS.md 为核心，系统讲解 generative-ai-for-beginners 课程仓库的完整工程实践：从克隆仓库、配置.env多供应商凭据，到 Python/TypeScript/Jupyter 三类示例的运行方式、代码风格约定、Markdown 文档规范与 GitHub Actions 校验机制。读完后，你可以独立搭建该仓库的开发环境、按规范运行课程示例，并以符合仓库校验要求的标准提交贡献。

项目定位：一份面向"AI Agent + 人类贡献者"的工程手册

仓库根目录的 AGENTS.md（阿拉伯语版见 translations/ar/AGENTS.md）是该课程的"元文档"：它不教生成式 AI 概念，而是告诉协作者（尤其是自动化 AI 编码代理）这个仓库"长什么样、怎么跑、改什么要守什么规矩"。文档开宗明义：

这是一个教学型仓库，聚焦学习而非生产代码；示例刻意保持简单、每课自包含、可独立完成；仓库同时支持 Azure OpenAI、OpenAI API 与 Microsoft Foundry Models（原 GitHub Models，计划于 2026 年 7 月底退役）等多种模型提供商。

课程结构与核心技术栈（文档原文要素）：

• 22 个编号课程目录（00-course-setup 至 21-meta），每课含 README 理论讲解、代码示例与练习；
• 多语言实现：Python、TypeScript，部分课程另附 .NET 示例；
• 40+ 语言翻译，存于 translations/ 目录，配图翻译存于 translated_images/；
• 集中式配置：所有课程共用根目录.env文件（以.env.copy为模板）。

从源码结构看，文档声明的技术栈与仓库完全一致：requirements.txt 锁定openai>=1.12.0、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib；根级 package.json 声明openai（v1 端点 + Responses API）、@azure-rest/ai-inference（Microsoft Foundry Models）与文档工具docsify-to-pdf。

初始配置：克隆仓库与.env凭据模板

标准初始化命令

文档给出的初始配置流程：

# Clone the repository git clone https://github.com/microsoft/generative-ai-for-beginners.git cd generative-ai-for-beginners # Copy environment template cp .env.copy .env # Edit .env with your API keys and endpoints

关键点在于模板文件 .env.copy。当前模板中定义的变量及默认值（比文档正文更精确，可直接作为填写依据）：

从 .env.copy 源码注释看，模板中AZURE_OPENAI_API_VERSION已预置默认值2024-10-21，并且AZURE_INFERENCE_*两个变量是 GitHub Models 退役前的迁移产物——即文档中"GitHub Models 于 2026 年 7 月底退役"的说法与模板注释相互印证。

Python 环境

# Create virtual environment python3 -m venv venv # On macOS/Linux: source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt

当前 requirements.txt 的实际内容（含精确版本锁定，比文档罗列的库名更具可操作性）：

ipywidgets==8.1.8 numpy==2.4.2 matplotlib==3.10.8 pandas==3.0.0 tqdm==4.68.4 python-dotenv==1.2.2 openai>=1.12.0 tiktoken azure-ai-inference scikit-learn

仓库根目录的 .python-version 固定为3.12.10，满足文档"Python 3.9+"的最低要求；若用 pyenv 等工具，建议直接对齐该版本。

Node.js/TypeScript 环境

# Install root-level dependencies (for documentation tooling) npm install # For individual lesson TypeScript examples, navigate to the specific lesson: cd 06-text-generation-apps/typescript/recipe-app npm install

根级npm install只为文档工具链服务（package.json 中docsify-to-pdf属于 devDependencies）；各课程 TypeScript 示例有独立的package.json，必须进入具体应用目录再安装。

Dev Container（文档推荐方式）

仓库附带完整的 .devcontainer 配置。按 devcontainer.json 的实际声明，容器行为如下：

• 基础镜像mcr.microsoft.com/devcontainers/universal:2.13（文档正文写2.11.2，当前仓库已升级）；要求宿主至少 4 CPU（hostRequirements.cpus: 4）；
• updateContentCommand执行python3 -m pip install -r requirements.txt，同步内容时自动装好 Python 依赖；
• postCreateCommand触发 .devcontainer/post-create.sh。

从 post-create.sh 源码看，创建后会额外执行：pip install python-dotenv openai（脚本注释说明这两项暂无法并入 requirements.txt），以及pip install ruff black mypy pytest——后者"与 .github/workflows/code-quality.yml 的检查一致，便于贡献者在本地复现 CI"。VS Code 侧则预配置了 Python、Pylance、Jupyter、Black、Ruff、ESLint、Prettier、Copilot 等扩展，并开启formatOnSave（Python 默认 Black 格式化器）。另有 .devcontainer/environment.yml 提供 Conda 依赖清单作为备选路径。

使用方式即文档所写：在 GitHub Codespaces 或装了 Dev Containers 扩展的 VS Code 中打开仓库，上述安装与配置全自动完成。

开发工作流：三类示例的运行姿势

文档将课程分为两类形态："Learn" 课以 README 概念讲解为主；"Build" 课附 Python/TypeScript 可运行示例。每课 README 均含理论、代码走查与视频链接。

运行 Python 示例

# Navigate to lesson directory cd 06-text-generation-apps/python # Run a Python script python aoai-app.py

06-text-generation-apps/python/ 目录下按前缀区分供应商：aoai-app.py（Azure OpenAI）、oai-app.py（OpenAI API）、githubmodels-app.py（Foundry/GitHub Models），还有*-study-buddy.py、*-history-bot.py等配套脚本，命名前缀约定（aoai-/oai-/githubmodels-）在全部课程目录中一致，文档明确要求新示例沿用该约定。

运行 TypeScript 示例

# Navigate to TypeScript app directory cd 06-text-generation-apps/typescript/recipe-app # Build the TypeScript code npm run build # Run the application npm start

每个 TS 应用有独立的tsconfig.json；文档建议开发期使用nodemon自动重载，且先npm run build再npm start。

运行 Jupyter Notebook

# Start Jupyter in the repository root jupyter notebook # Or use VS Code with Jupyter extension

课程中的.ipynb练习（如 04-prompt-engineering-fundamentals/python/、15-rag-and-vector-databases/notebook-rag-vector-databases.ipynb）依赖ipywidgets（requirements 已锁定 8.1.8），Dev Container 场景下内核已预配置。

代码风格指南：保持"教学清晰"优先

文档的 Python 规范：用python-dotenv管理环境变量；用openai库交互；允许部分示例保留# pylint: disable=all以简化阅读；遵循 PEP 8；凭据只放.env，绝不写入代码。

TypeScript 规范：用dotenv包；每应用独立tsconfig.json；Azure 服务用@azure-rest/ai-inference（Foundry Models）或指向/openai/v1/端点的openai客户端；先构建后运行。

通用约定（也是本仓库最有辨识度的工程文化）：

1. 示例保持简单、自包含、可独立运行；
2. 注释必须解释关键概念——代码首先是教材；
3. 命名一致：{provider}-{example-name}.{py|ts|js}，如 aoai-solution.py 与 solution.js。

补充一个源码层面的现状：虽然文档描述仓库为"教学示例集合"，但根目录已存在 tests/（含conftest.py与针对 shared/python/ 工具模块的test_api_utils.py、test_env_utils.py、test_input_validation.py），且 code-quality.yml 工作流会在 CI 中运行 ruff/black/mypy 等检查——本地可通过pip install ruff black mypy pytest复现，这与 Dev Container 的 post-create 脚本形成闭环。

文档规范：Markdown 风格与 40+ 语言翻译体系

Markdown 硬性规则

文档列出五条规则，且仓库的 CI 会强制执行前三条：

• 所有链接必须包裹为text形式，无多余空格；
• 相对链接必须以./或../开头；
• 所有指向 Microsoft 域名的链接必须携带追踪参数?WT.mc_id=academic-105485-koreyst；
• URL 中不得出现国家地区子路径（避免/en-us/）；
• 图片存于各课./images目录，命名使用英文、数字与连字符。

校验机制：validate-markdown 工作流

文档明确：提交 PR 前，.github/workflows/validate-markdown.yml 会自动检查——

# The validate-markdown.yml workflow checks: # - Broken relative paths # - Missing tracking IDs on paths # - Missing tracking IDs on URLs # - URLs with country locale # - Broken external URLs

即：损坏的相对路径、缺失的追踪 ID（路径与 URL）、带地区 locale 的 URL、失效外链都会被 CI 拦截。仓库.github/workflows/目录中还包含code-quality.yml（代码静态检查）、lock.yml、security.yml、stale.yml等配套工作流。

翻译支持规则

• 40+ 语言由 GitHub Actions 自动翻译流水线生成，译文存放于 translations/，翻译后的图片存放于 translated_images/（按语言子目录 + 内容哈希命名）；
• 不接受部分翻译，也不接受机器翻译作为人工贡献；
• 更新英文源文档后，翻译由 Actions 自动刷新，不要手动编辑translations/下的文件。

测试验证与 PR 提交规范

提交前检查清单

文档给出的手动验证流程：

1. Python 示例：激活 venv 后运行脚本；
2. TypeScript 示例：npm install→npm run build→npm start全链路跑通；
3. 环境变量：确认.env已按当前课程需要配齐，API Key 对示例代码可用；
4. 多供应商覆盖：示例适用时同时用 Azure OpenAI 与 OpenAI API 各测一遍，Foundry Models 支持处也需验证。

PR 标题与描述格式

• 描述性标题，如[Lesson 06] Fix Python example typo或Update README for lesson 08；
• 关联 issue 时写Fixes #123；
• 描述中说明"改了什么、为什么改"，代码变更需注明测试过哪些示例；翻译 PR 必须包含该语言全部文件；
• 贡献要求：首次 PR 自动签署 Microsoft CLA；先 Fork 再改；一个 PR 只包含一个逻辑变更，保持小而聚焦。

常见工作流：新增一个代码示例

1. 进入对应课程目录；
2. 在python/或typescript/子目录创建示例；
3. 遵循{provider}-{example-name}.{py|ts|js}命名；
4. 用真实 API 凭据实测；
5. 在课程 README 中补充文档（含新增环境变量说明）。

交付与消费方式：没有"部署"，只有"阅读"

文档明确此仓库无部署流程，课程通过四种渠道被消费：

1. GitHub 仓库：直接阅读代码与文档；
2. GitHub Codespaces：基于上述 Dev Container 的即开即用环境；
3. Microsoft Learn：内容可能同步到官方学习平台；
4. docsify 文档站：由 Markdown 构建，配套 docsifytopdf.js 与npm run convert脚本：

# Generate PDF from documentation (if needed) npm run convert

从 docsifytopdf.js 源码看，该脚本以docs/_sidebar.md为目录、输出到pdf/readme.pdf，边距上下各 100px，生成后自动清理临时.md/.html文件；package.json 中convert脚本即调用node_modules/.bin/docsify-to-pdf。

故障排查速查表

文档给出的四类常见问题与处理路径：

结合 Dev Container 用户：若容器内仍缺依赖，可检查postCreateCommand是否执行完毕（devcontainer.json 中waitFor: "onCreateCommand"保证容器创建完成前会等待requirements.txt安装结束）。

延伸阅读

• 课程入口与学习路径：00-course-setup/README.md（含云端/本地两种起步方式与 03-providers.md 供应商选择）；
• 仓库主文档：README.md；
• 贡献流程细节：CONTRIBUTING.md；
• 协作规范：CODE_OF_CONDUCT.md、SECURITY.md；
• 共享工具模块（测试对象）：shared/python/。

小结：AGENTS.md 将"教学仓库"这一看似松散的内容形态约束成了一套可机读、可校验的工程契约——.env.copy定凭据、.devcontainer定环境、validate-markdown 与 code-quality 两条 CI 定质量门槛、{provider}-*前缀定命名文化。对贡献者和 AI Agent 而言，照此执行即可在零歧义的前提下理解并修改这个多语言、多供应商的生成式 AI 课程仓库。

【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners