# 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 ## 设置命令 此资源库主要用于教育内容的学习。对于具体项目的操作： ### 主资源库设置 ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### 测验应用设置（Vue 3 + Vite） ```bash 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） ```bash cd 7-bank-project/api npm install npm start # Start API server npm run lint # Run ESLint npm run format # Format with Prettier ``` ### 浏览器扩展项目 ```bash cd 5-browser-extension/solution npm install # Follow browser-specific extension loading instructions ``` ### 太空游戏项目 ```bash cd 6-space-game/solution npm install # Open index.html in browser or use Live Server ``` ### 聊天项目（Python后端） ```bash cd 9-chat-project/solution/backend/python pip install openai # Set GITHUB_TOKEN environment variable python api.py ``` ## 开发工作流程 ### 对于内容贡献者 1. **Fork资源库**到你的GitHub账户 2. **克隆你的Fork**到本地 3. **创建新分支**以进行更改 4. 修改课程内容或代码示例 5. 在相关项目目录中测试代码更改 6. 按照贡献指南提交拉取请求 ### 对于学习者 1. Fork或克隆资源库 2. 按顺序浏览课程目录 3. 阅读每节课程的README文件 4. 在https://ff-quizzes.netlify.app/web/完成课前测验 5. 在课程文件夹中完成代码示例 6. 完成作业和挑战 7. 进行课后测验 ### 实时开发 - **文档**：在根目录运行`docsify serve`（端口3000） - **测验应用**：在quiz-app目录运行`npm run dev` - **项目**：使用VS Code的Live Server扩展运行HTML项目 - **API项目**：在相关API目录运行`npm start` ## 测试说明 ### 测验应用测试 ```bash cd quiz-app npm run lint # Check for code style issues npm run build # Verify build succeeds ``` ### 银行API测试 ```bash 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部署： ```bash 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生成 ```bash npm install # Install docsify-to-pdf npm run convert # Generate PDF from docs ``` ### Docsify文档 ```bash 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之前： 1. **代码质量**： - 在受影响的项目目录运行`npm run lint` - 修复所有lint错误和警告 2. **构建验证**： - 如果适用，运行`npm run build` - 确保没有构建错误 3. **链接验证**： - 测试所有Markdown链接 - 验证图片引用是否正常工作 4. **内容审查**： - 校对拼写和语法 - 确保代码示例正确且具有教育意义 - 验证翻译保持原意 ### 贡献要求 - 同意微软CLA（首次PR时自动检查） - 遵循[微软开源行为准则](https://opensource.microsoft.com/codeofconduct/) - 参阅[CONTRIBUTING.md](./CONTRIBUTING.md)获取详细指南 - 在PR描述中引用问题编号（如果适用） ### 审核流程 - PR由维护者和社区审核 - 优先考虑教育清晰度 - 代码示例应遵循当前最佳实践 - 翻译需审核准确性和文化适应性 ## 翻译系统 ### 自动翻译 - 使用GitHub Actions和co-op-translator工作流 - 自动翻译为50多种语言 - 源文件位于主目录 - 翻译文件存储在`translations/{language-code}/`目录中 ### 添加手动翻译改进 1. 在`translations/{language-code}/`中找到文件 2. 在保持结构的同时进行改进 3. 确保代码示例仍然可用 4. 测试任何本地化的测验内容 ### 翻译元数据 翻译文件包含元数据头： ```markdown ``` ## 调试和故障排除 ### 常见问题 **测验应用无法启动**： - 检查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自动更新翻译 ### 相关资源 - [微软学习模块](https://docs.microsoft.com/learn/) - [学生中心资源](https://docs.microsoft.com/learn/student-hub/) - 推荐学习者使用[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - 其他课程：生成式AI、数据科学、机器学习、物联网课程可用 ### 处理具体项目 有关单个项目的详细说明，请参阅以下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](https://github.com/Azure/co-op-translator) 进行翻译。尽管我们努力确保翻译的准确性，但请注意，自动翻译可能包含错误或不准确之处。原始语言的文档应被视为权威来源。对于关键信息，建议使用专业人工翻译。我们不对因使用此翻译而产生的任何误解或误读承担责任。