Web-Dev-For-Beginners AGENTS.md：AI Agent 与协作者的全仓工程指南

本篇基于仓库根目录的 AGENTS.md 及其保加利亚语本地化版本 translations/bg/AGENTS.md 展开。AGENTS.md 是专为 AI 编码 Agent 和人类协作者编写的全仓操作手册，覆盖 12 周、24 课网页开发课程仓库的项目概览、各子项目环境搭建、开发工作流、测试策略、代码风格、构建部署、PR 规范、翻译体系与排障安全实践。读完本文，你可以快速定位任意子项目（Quiz App、Bank API、浏览器扩展、太空游戏、AI 聊天项目）的启动命令，并掌握在提交变更前需要执行的检查清单与安全约束。

一、项目概览与关键组件

AGENTS.md 开篇明确：这是一个由 Microsoft Cloud Advocates 开发的教育型课程仓库，面向零基础学员，以"12 周、24 个实践课"组织网页开发基础教学，覆盖 JavaScript、CSS 与 HTML。根目录 package.json 中 author 字段为 "Microsoft Cloud Advocates"、license 为 MIT，与文档描述一致。

文档将仓库的关键组件归纳为五类：

组件	说明	仓库内可验证的落点
教育内容	24 个按模块组织的结构化课程	docs/_sidebar.md 中编号 1–24 的课程目录
实践项目	生态瓶（Terrarium）、打字游戏、浏览器扩展、太空游戏、银行应用、代码编辑器、AI 聊天助手	3-terrarium/、4-typing-game/、5-browser-extension/、6-space-game/、7-bank-project/、8-code-editor/、9-chat-project/ 等目录
互动测验	48 个测验，每个 3 题，用于课前/课后评估	各课 assignment.md 与课程 README
多语言支持	通过 GitHub Actions 自动化翻译 50+ 语言	translations/ 目录下 50 个语言子目录（ar/、bg/、zh-CN/ 等）与 translations/bg/AGENTS.md 等译本
技术栈	HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AI 项目）	各子项目 package.json 与 9-chat-project/solution/backend/python/api.py

架构上，AGENTS.md 指出这是一个"基于课程目录的教育仓库"：每个课程文件夹包含 README、示例代码和解答；独立项目放在各自目录中；翻译由 GitHub Actions（co-op-translator）驱动；文档通过 Docsify 提供服务并可导出 PDF。

二、文件组织与"伪 Monorepo"结构

AGENTS.md 的"File Organization"与"Monorepo Structure"两节给出了全仓目录约定，这也是 Agent 探索仓库时的导航依据：

• 课程按序号命名：1-getting-started-lessons、2-js-basics、3-terrarium……按学习顺序推进；
• 每个项目有 solution/ 解答目录，常伴有 start/ 或 your-work/ 学员工作目录（如 4-typing-game/ 的 assignment 与 solution/ 对照）；
• 图片存于各课程专属 images/ 目录；
• 译文存于 translations/{language-code}/ 结构，与源文件一一对应；
• 各课程相互独立、项目间不共享依赖——从源码结构看，这由各自独立的 package.json 印证：quiz-app/package.json、7-bank-project/api/package.json、5-browser-extension/solution/package.json、6-space-game/solution/package.json 完全独立，Agent 可在不触及其他项目的前提下单独开发某一子项目。

文档同时提醒：想要完整课程体验应克隆整个仓库；仅做内容工作时可使用浅克隆（见后文性能一节）。

三、各子项目环境搭建命令

AGENTS.md 的核心价值在于给出每个子项目"可复制可运行"的启动命令。以下按原文档完整继承，并结合同仓库 package.json 补充实际依赖与脚本定义。

3.1 克隆仓库

git clone https://gitcode.com/GitHub_Trending/we/Web-Dev-For-Beginners
cd Web-Dev-For-Beginners

3.2 Quiz App（Vue 3 + Vite）

cd quiz-app
npm install
npm run dev        # 启动开发服务器
npm run build      # 生产构建
npm run lint       # 运行 ESLint

对照 quiz-app/package.json 可确认：dev 即 vite，build 即 vite build，lint 为 eslint . --ext .vue,.js,.jsx,.cjs,.mjs --fix --ignore-path .gitignore（注意它带 --fix，运行 lint 会自动修复问题）。依赖为 vue ^3.4.29、vue-router ^4.3.3，开发依赖为 vite ^6.4.2、@vitejs/plugin-vue ^5.2.4、eslint ^8.57.0、eslint-plugin-vue ^9.23.0。项目 type 为 module，采用 ESM。

3.3 Bank Project API（Node.js + Express）

cd 7-bank-project/api
npm install
npm start          # 启动 API 服务器
npm run lint       # 运行 ESLint
npm run format     # Prettier 格式化

7-bank-project/api/package.json 中 start 实际执行 node server.js（入口见 7-bank-project/api/server.js），format 为 prettier --single-quote --write *.js（单引号风格）。运行时依赖为 express ^4.21.2、cors ^2.8.5、body-parser ^1.20.3，且 engines 字段声明 "node": ">=10"——这与文档排障一节"API 服务器要求 node >=10"的要求相互印证。

3.4 浏览器扩展项目

cd 5-browser-extension/solution
npm install
# 随后按浏览器特定的扩展加载指引操作

从 5-browser-extension/solution/package.json 看，解答扩展名为 carbon-trigger-extension（碳排放触发器示例），基于 webpack 构建，engines 要求 node >=18.0.0、npm >=9.0.0，依赖 axios ^1.15.0，并提供 watch（webpack --watch）与 build（webpack）脚本——即构建产物为 webpack 打包结果，再按 Chrome/Edge 各自指引加载 unpacked 扩展。

3.5 太空游戏项目

cd 6-space-game/solution
npm install
# 用浏览器打开 index.html，或使用 Live Server

补充一点：6-space-game/solution/package.json 额外定义了 start 脚本为 npx http-server -c-1 -p 5000（禁用缓存、5000 端口），比"直接打开 index.html"更规范。

3.6 聊天项目（Python 后端）

cd 9-chat-project/solution/backend/python
pip install openai
# 设置 GITHUB_TOKEN 环境变量
python api.py

该目录下的实际文件为 api.py、llm.py 与 README.md，前后端分离（前端在 9-chat-project/solution/frontend/ 下）。注意其鉴权依赖 GITHUB_TOKEN 环境变量访问 GitHub Models，切勿将其写入代码（见安全一节）。

四、开发工作流

AGENTS.md 将工作流区分为"内容贡献者"与"学习者"两条路径，并给出"本地实时开发"的服务器启动方式。

4.1 内容贡献者流程

1. 将仓库 Fork 到自己的账号；
2. 克隆自己的 Fork 到本地；
3. 为新变更创建分支；
4. 修改课程内容或代码示例；
5. 在相应项目目录中测试所有代码变更；
6. 按贡献指引提交 Pull Request。

4.2 学习者流程

1. Fork 或克隆仓库；
2. 按顺序进入各课程目录；
3. 阅读每课的 README；
4. 在课程配套在线测验站完成课前测验（站点地址见原文档）；
5. 练习课程文件夹中的代码示例；
6. 完成作业（assignment）与挑战；
7. 完成课后测验。

4.3 本地实时开发

• 文档：在根目录运行 docsify serve（端口 3000）；
• Quiz App：在 quiz-app 目录运行 npm run dev；
• 纯 HTML 项目：使用 VS Code 的 Live Server 扩展；
• API 项目：在对应 API 目录运行 npm start。

五、测试策略与提交前检查

文档坦诚指出：这是一个教育型仓库，没有完整的自动化测试体系，验证以"lint + build + 人工检查"为主。

5.1 Quiz App 测试

cd quiz-app
npm run lint       # 检查代码风格问题
npm run build      # 验证构建成功

5.2 Bank API 测试

cd 7-bank-project/api
npm run lint       # 检查代码风格问题
node server.js     # 验证服务器无错误启动

5.3 通用人工测试要点

• 代码示例能够无错误运行；
• 文档中的链接均有效；
• 各项目构建能够成功完成；
• 示例代码遵循良好的实践。

5.4 提交前检查清单

• 在所有含 package.json 的目录运行 npm run lint；
• 校验 Markdown 链接有效性；
• 在浏览器或 Node.js 中实测代码示例；
• 确认译文文件保持了正确的结构。

六、代码风格指南

AGENTS.md 对不同语言给出了明确规范，Agent 修改仓库时应逐条遵守：

• JavaScript：使用现代 ES6+ 语法；遵循项目内提供的 ESLint 配置；为教学清晰性使用有意义的变量与函数名；添加面向学员的解释性注释；在已配置 Prettier 的项目（如 Bank API）中按其规则格式化。
• HTML/CSS：语义化 HTML5 元素；遵循响应式设计原则；类名命名约定清晰；注释解释 CSS 技巧。
• Python：遵循 PEP 8；示例代码清晰且具教育性；在有助学习处使用类型提示。
• Markdown 文档：标题层级清晰；代码块标注语言；提供延伸阅读链接；截图统一放 images/ 目录；图片必须带 alt 文本（无障碍要求）。

七、构建与部署

7.1 Quiz App 部署到 Azure Static Web Apps

cd quiz-app
npm run build      # 生成 dist/ 目录
# 推送 main 分支后由 GitHub Actions workflow 自动部署

文档给出三项关键配置：应用位置 /quiz-app、输出位置 dist、工作流文件 .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml。该 workflow 文件确实存在于当前仓库中；同一目录下还有 links.yml、lock.yml、stale.yml、daily-repo-status.lock.yml 等工作流。

7.2 Docsify 文档服务

npm install -g docsify-cli    # 全局安装 Docsify CLI
docsify serve                 # 在 localhost:3000 提供服务

Docsify 的侧边栏数据来自 docs/_sidebar.md，该文件列出了全部 24 课（Introduction → JS Basics → HTML/CSS/JS → Typing Game → Browser Extension → Space Game → Bank Project），可据此核对课程编号与目录路径是否对应。

7.3 生成 PDF 文档

npm install
npm run convert               # 从 docs 生成 PDF

根 package.json 中 convert 脚本指向 node_modules/.bin/docsify-to-pdf，对应开发依赖 docsify-to-pdf: 0.0.5。具体行为由 docsifytopdf.js 定义：以 docs/_sidebar.md 为目录源，输出到 pdf/readme.pdf（仓库中该 PDF 已存在），页边距上下各 100px，emulateMedia 为 print，生成后删除临时文件（removeTemp: true）。

7.4 项目专属构建

• Vue 项目：npm run build 生成生产包；
• 静态项目：无构建步骤，直接伺服文件；
• 扩展项目：webpack build/watch（见 3.4 节）。

八、Pull Request 规范

8.1 标题格式

要求标题带领域前缀、清晰描述变更区域，文档给出的四个示例：

• [Quiz-app] Add new quiz for lesson X
• [Lesson-3] Fix typo in terrarium project
• [Translation] Add Spanish translation for lesson 5
• [Docs] Update setup instructions

8.2 提交前的强制检查

1. 代码质量：在受影响的项目目录运行 npm run lint，修复所有错误与警告；
2. 构建验证：如适用则运行 npm run build，确保无构建错误；
3. 链接校验：测试所有 Markdown 链接与图片引用；
4. 内容审阅：校对拼写与语法、确认代码示例正确且有教育性、确认译文保留原意。

8.3 贡献要求与评审流程

贡献者需同意 Microsoft CLA（首次 PR 时自动检查）、遵循 Microsoft 开源行为准则，并参阅 CONTRIBUTING.md 获取详细指引；如 PR 对应 issue，应在描述中引用 issue 编号。评审由维护者与社区共同完成，优先看"教育清晰度"，代码示例应遵循当前最佳实践，译文则按准确性与文化适配性审阅。

九、多语言翻译体系

AGENTS.md 专设"Translation System"一节，当前仓库的 translations/ 目录包含 50 个语言子目录（ar/、bg/、cs/、de/、zh-CN/、zh-TW/ 等，每目录约 98 个译文 Markdown），另有 translated_images/ 存放各语言版本的图片资源——这正是本文档 translations/bg/AGENTS.md 所在的机制产物。

• 自动化翻译：文档说明使用 GitHub Actions 的 co-op-translator 工作流自动翻译到 50+ 语言；源文件在主目录，译文写入 translations/{language-code}/；
• 手工润色流程：在对应语言目录定位文件 → 保持结构进行润色 → 确保代码示例仍然可运行 → 测试本地化后的测验内容；
• 译文字段规范：文档展示了译文文件的元数据头部格式：

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

一个值得注意的细节：本仓库的保加利亚语版本 translations/bg/AGENTS.md 正文即根目录 AGENTS.md 的逐节机器翻译（节标题、命令块完全对应），且文末附有 Co-op Translator 免责声明，声明"原文档（母语版本）为权威来源，关键信息建议专业人工翻译"。这意味着：当英文版与译文版表述冲突时，应以根目录英文 AGENTS.md 为准。

十、常见故障排查

AGENTS.md 汇总了五类高频问题及处置步骤，是 Agent 排障时的第一参考：

故障现象	排查步骤
Quiz App 无法启动	检查 Node.js 版本（文档建议 v14+；注意当前 package.json 使用 Vite ^6.4.2，实际运行时建议采用更新的 Node 版本）；删除 node_modules 与 package-lock.json 后重新 npm install；检查端口冲突（Vite 默认端口 5173）
API 服务器无法启动	确认 Node.js ≥10（与 7-bank-project/api/package.json 的 engines 一致）；检查端口占用；确认已 npm install
浏览器扩展无法加载	检查 manifest.json 格式；查看浏览器控制台报错；按浏览器专属指引安装扩展
Python 聊天项目异常	确认已执行 pip install openai；确认已设置 GITHUB_TOKEN 环境变量；检查 GitHub Models 访问权限
Docsify 无法提供文档	全局安装 docsify-cli；在仓库根目录运行；确认 docs/_sidebar.md 存在（当前仓库中该文件存在）

开发环境建议：VS Code + Live Server 处理 HTML 项目；安装 ESLint 与 Prettier 扩展保持格式一致；用浏览器 DevTools 调试 JavaScript；Vue 项目安装 Vue DevTools 浏览器扩展。

性能考虑：50+ 语言的译文使完整克隆体积较大——若只维护英文内容，建议使用 git clone --depth 1 浅克隆；检索英文内容时可排除 translations/ 目录；首次构建（npm install、Vite build）可能较慢，属正常现象。

十一、安全注意事项

文档对 AI Agent 尤其重要的约束集中在此节：

• 环境变量：API 密钥绝不可提交进仓库；使用 .env 文件（已在 .gitignore 中）；在项目的 README 中记录所需环境变量；
• Python 项目：使用虚拟环境 python -m venv venv；保持依赖更新；GitHub Token 遵循最小权限原则；
• GitHub Models 访问：需要 Personal Access Token（PAT）；Token 只能以环境变量形式保存；任何情况下不得提交 Token 或凭据。

十二、面向对象与教育哲学（背景信息）

AGENTS.md 末节说明目标受众为零基础学习者、学生与自学者、以及将课程用于课堂的教师；内容设计强调可访问性与技能渐进。教育哲学为：项目式学习、高频知识检测（48 个测验）、动手编码练习、真实应用示例、"先基础后框架"。仓库由活跃的社区维护者监控 issues 与讨论，依赖与内容定期更新，译文更新由 GitHub Actions 自动化。文档还指向各子项目的深入 README：quiz-app/README.md、7-bank-project/README.md、5-browser-extension/README.md、6-space-game/README.md、9-chat-project/README.md。

小结

AGENTS.md 的价值在于把"一个课程仓库如何被工程化协作"压缩成了单页可执行手册：课程与项目以序号目录隔离、各自独立依赖；每个可运行项目都有明确的 npm install / npm start / npm run dev 入口（均可在各子项目 package.json 中逐条核对）；变更质量靠 lint + build + 人工检查三道关保障；多语言体系由自动翻译工作流驱动并以 translations/{lang}/ 落盘；安全上则以"Token 不落库、最小权限、虚拟环境"为硬约束。对 AI Agent 而言，遵循本文所述目录约定与检查清单，即可在任一子项目中安全、可验证地开展贡献工作。