11 KiB

Raw Permalink 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        # 启动开发服务器
npm run build      # 构建生产版本
npm run lint       # 运行 ESLint

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

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

浏览器扩展项目

cd 5-browser-extension/solution
npm install
# 遵循浏览器特定的扩展加载说明

太空游戏项目

cd 6-space-game/solution
npm install
# 在浏览器中打开 index.html 或使用实时服务器

聊天项目（Python 后端）

cd 9-chat-project/solution/backend/python
pip install openai
# 设置 GITHUB_TOKEN 环境变量
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       # 检查代码风格问题
npm run build      # 验证构建是否成功

银行API测试

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

测试总体方法

这是一个没有完整自动测试的教学仓库
手动测试关注点：
- 代码示例无错误运行
- 文档中的链接正常
- 项目构建成功完成
- 示例符合最佳实践

提交前检查

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

代码风格指南

JavaScript

使用现代ES6+语法
遵循项目中的标准ESLint配置
使用有意义的变量和函数名，便于教学理解
添加注释解释概念
配置Prettier进行代码格式化

HTML/CSS

语义化的HTML5元素
响应式设计原则
清晰的类命名规范
注释说明CSS技术点

Python

遵循PEP 8规范
清晰的教学示例代码
适当添加类型提示，便于学习

Markdown文档

明确的标题层级结构
代码块标明语言
资源链接
在images/目录下存放截图和图片
图片含有Alt文本，方便无障碍访问

文件组织

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

构建与部署

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

quiz-app配置为Azure静态网页应用部署：

cd quiz-app
npm run build      # 创建 dist/ 文件夹
# 在 push 到 main 时通过 GitHub Actions 工作流部署

Azure静态网页应用配置：

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

文档PDF生成

npm install                    # 安装 docsify-to-pdf
npm run convert               # 从 docs 生成 PDF

Docsify文档

npm install -g docsify-cli    # 全局安装 Docsify
docsify serve                 # 在 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描述中注明issue编号

审核流程

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模型访问权限

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构建）

安全考虑

环境变量

API密钥绝不可提交到仓库
使用.env文件（已包含在.gitignore中）
在项目README中注明所需环境变量

Python项目

使用虚拟环境：python -m venv venv
保持依赖更新
GitHub令牌应仅授予必要权限

GitHub模型访问权限

访问GitHub模型需要个人访问令牌（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 Permalink Blame History Unescape Escape