11 KiB

Raw Blame History Unescape Escape

AGENTS.md

项目概述

这是一个用于教授初学者网页开发基础知识的教育课程库。该课程是由微软云倡导者开发的全面12周课程，包含24节动手实践课程，涵盖JavaScript、CSS和HTML。

主要组成部分

教育内容：24节结构化课程，按项目模块组织
实践项目：生态瓶、打字游戏、浏览器扩展、太空游戏、银行应用、代码编辑器和AI聊天助手
互动测验：48个测验，每个测验包含3个问题（课前/课后评估）
多语言支持：通过GitHub Actions实现50多种语言的自动翻译
技术栈：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（用于AI项目）

架构

基于课程的教育资源库
每个课程文件夹包含README、代码示例和解决方案
独立项目存放在单独的目录中（quiz-app，各种课程项目）
使用GitHub Actions的翻译系统（co-op-translator）
文档通过Docsify提供，并可导出为PDF

设置命令

此资源库主要用于教育内容的学习。对于具体项目的操作：

主资源库设置

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

测验应用设置（Vue 3 + Vite）

cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

银行项目API（Node.js + Express）

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

浏览器扩展项目

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

太空游戏项目

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

聊天项目（Python后端）

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

开发工作流程

对于内容贡献者

Fork资源库到你的GitHub账户
克隆你的Fork到本地
创建新分支以进行更改
修改课程内容或代码示例
在相关项目目录中测试代码更改
按照贡献指南提交拉取请求

对于学习者

Fork或克隆资源库
按顺序浏览课程目录
阅读每节课程的README文件
在https://ff-quizzes.netlify.app/web/完成课前测验
在课程文件夹中完成代码示例
完成作业和挑战
进行课后测验

实时开发

文档：在根目录运行docsify serve（端口3000）
测验应用：在quiz-app目录运行npm run dev
项目：使用VS Code的Live Server扩展运行HTML项目
API项目：在相关API目录运行npm start

测试说明

测验应用测试

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

银行API测试

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

一般测试方法

这是一个教育资源库，没有全面的自动化测试
手动测试重点：
- 代码示例运行无错误
- 文档中的链接正常工作
- 项目构建成功完成
- 示例遵循最佳实践

提交前检查

在包含package.json的目录运行npm run lint
验证Markdown链接是否有效
在浏览器或Node.js中测试代码示例
确保翻译保持正确结构

代码风格指南

JavaScript

使用现代ES6+语法
遵循项目中提供的标准ESLint配置
使用有意义的变量和函数名称以便于学习
添加注释解释概念以帮助学习者
在配置了Prettier的地方进行格式化

HTML/CSS

使用语义化HTML5元素
响应式设计原则
清晰的类命名规范
添加注释解释CSS技术以帮助学习者

Python

遵循PEP 8风格指南
提供清晰的教育代码示例
在有帮助的地方添加类型提示

Markdown文档

清晰的标题层次结构
带语言说明的代码块
链接到额外资源
在images/目录中提供截图和图片
为图片添加辅助文本以提高可访问性

文件组织

课程按顺序编号（1-getting-started-lessons, 2-js-basics等）
每个项目有solution/目录，通常还有start/或your-work/目录
图片存储在课程特定的images/文件夹中
翻译存储在translations/{language-code}/结构中

构建和部署

测验应用部署（Azure Static Web Apps）

测验应用已配置为Azure Static Web Apps部署：

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

Azure Static Web Apps配置：

应用位置：/quiz-app
输出位置：dist
工作流：.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

文档PDF生成

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Docsify文档

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

项目特定构建

每个项目目录可能有自己的构建过程：

Vue项目：npm run build生成生产包
静态项目：无需构建步骤，直接提供文件

拉取请求指南

标题格式

使用清晰、描述性的标题指明更改的区域：

[Quiz-app] 为课程X添加新测验
[Lesson-3] 修复生态瓶项目中的拼写错误
[Translation] 为课程5添加西班牙语翻译
[Docs] 更新设置说明

必需检查

提交PR之前：

代码质量：
- 在受影响的项目目录运行npm run lint
- 修复所有lint错误和警告
构建验证：
- 如果适用，运行npm run build
- 确保没有构建错误
链接验证：
- 测试所有Markdown链接
- 验证图片引用是否正常工作
内容审查：
- 校对拼写和语法
- 确保代码示例正确且具有教育意义
- 验证翻译保持原意

贡献要求

同意微软CLA（首次PR时自动检查）
遵循微软开源行为准则
参阅CONTRIBUTING.md获取详细指南
在PR描述中引用问题编号（如果适用）

审核流程

PR由维护者和社区审核
优先考虑教育清晰度
代码示例应遵循当前最佳实践
翻译需审核准确性和文化适应性

翻译系统

自动翻译

使用GitHub Actions和co-op-translator工作流
自动翻译为50多种语言
源文件位于主目录
翻译文件存储在translations/{language-code}/目录中

添加手动翻译改进

在translations/{language-code}/中找到文件
在保持结构的同时进行改进
确保代码示例仍然可用
测试任何本地化的测验内容

翻译元数据

翻译文件包含元数据头：

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

调试和故障排除

常见问题

测验应用无法启动：

检查Node.js版本（推荐v14+）
删除node_modules和package-lock.json，重新运行npm install
检查端口冲突（默认：Vite使用端口5173）

API服务器无法启动：

验证Node.js版本是否满足最低要求（node >=10）
检查端口是否已被占用
确保所有依赖项已通过npm install安装

浏览器扩展无法加载：

验证manifest.json格式是否正确
检查浏览器控制台中的错误
按照浏览器特定的扩展安装说明操作

Python聊天项目问题：

确保已安装OpenAI包：pip install openai
验证是否设置了GITHUB_TOKEN环境变量
检查GitHub Models访问权限

Docsify无法提供文档：

全局安装docsify-cli：npm install -g docsify-cli
从资源库根目录运行
检查docs/_sidebar.md是否存在

开发环境提示

对于HTML项目，使用VS Code的Live Server扩展
安装ESLint和Prettier扩展以保持一致的格式
使用浏览器开发工具调试JavaScript
对于Vue项目，安装Vue DevTools浏览器扩展

性能考虑

大量翻译文件（50多种语言）导致完整克隆体积较大
如果只处理内容，请使用浅克隆：git clone --depth 1
在处理英文内容时排除翻译文件的搜索
第一次运行构建过程可能较慢（npm install, Vite build）

安全注意事项

环境变量

API密钥绝不能提交到资源库
使用.env文件（已在.gitignore中）
在项目README中记录所需的环境变量

Python项目

使用虚拟环境：python -m venv venv
保持依赖项更新
GitHub令牌应具有最低必要权限

GitHub Models访问

GitHub Models需要个人访问令牌（PAT）
令牌应存储为环境变量
切勿提交令牌或凭据

附加说明

目标受众

完全的网页开发初学者
学生和自学者
在课堂上使用课程的教师
内容设计注重可访问性和逐步技能提升

教育理念

基于项目的学习方法
频繁的知识检查（测验）
动手编码练习
真实世界应用示例
在框架之前专注于基础知识

资源库维护

活跃的学习者和贡献者社区
定期更新依赖项和内容
维护者监控问题和讨论
通过GitHub Actions自动更新翻译

处理具体项目

有关单个项目的详细说明，请参阅以下README文件：

quiz-app/README.md - Vue 3测验应用
7-bank-project/README.md - 带认证的银行应用
5-browser-extension/README.md - 浏览器扩展开发
6-space-game/README.md - 基于Canvas的游戏开发
9-chat-project/README.md - AI聊天助手项目

Monorepo结构

虽然不是传统的Monorepo，但此资源库包含多个独立项目：

每节课程都是自包含的
项目之间不共享依赖项
可单独处理项目而不影响其他项目
克隆整个资源库以体验完整课程

免责声明：
本文档使用AI翻译服务 Co-op Translator 进行翻译。尽管我们努力确保翻译的准确性，但请注意，自动翻译可能包含错误或不准确之处。原始语言的文档应被视为权威来源。对于关键信息，建议使用专业人工翻译。我们不对因使用此翻译而产生的任何误解或误读承担责任。

11 KiB Raw Blame History Unescape Escape