AGENTS.md

1# AGENTS.md
2 
3## 项目概述
4 
5这是一个面向初学者教授网页开发基础知识的教育课程仓库。该课程是一门由微软云宣传人员开发的为期12周的综合课程，包含24个涵盖JavaScript、CSS和HTML的实践课程。
6 
7### 关键组成部分
8 
9- <strong>教学内容</strong>：24个结构化课程，按项目模块组织
10- <strong>实用项目</strong>：生态瓶、打字游戏、浏览器扩展、太空游戏、银行应用、代码编辑器和AI聊天助手
11- <strong>互动测验</strong>：48个测验，每个包含3个问题（课前/课后评估）
12- <strong>多语言支持</strong>：通过GitHub Actions自动翻译50多种语言
13- <strong>技术栈</strong>：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（用于AI项目）
14 
15### 架构
16 
17- 教育仓库，基于课程结构
18- 每课文件夹包含README、代码示例和解决方案
19- 独立项目位于单独目录（quiz-app、各种课程项目）
20- 使用GitHub Actions（co-op-translator）实现翻译系统
21- 文档通过Docsify提供，并可导出为PDF
22 
23## 设置命令
24 
25此仓库主要用于教学内容的使用。若需使用具体项目：
26 
27### 主仓库设置
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### 测验应用设置（Vue 3 + Vite）
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # 启动开发服务器
40npm run build      # 构建生产版本
41npm run lint       # 运行 ESLint
42```
43 
44### 银行项目 API（Node.js + Express）
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # 启动 API 服务器
50npm run lint       # 运行 ESLint
51npm run format     # 使用 Prettier 格式化
52```
53 
54### 浏览器扩展项目
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# 遵循浏览器特定的扩展加载说明
60```
61 
62### 太空游戏项目
63 
64```bash
65cd 6-space-game/solution
66npm install
67# 在浏览器中打开 index.html 或使用实时服务器
68```
69 
70### 聊天项目（Python 后端）
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# 设置 GITHUB_TOKEN 环境变量
76python api.py
77```
78 
79## 开发工作流
80 
81### 内容贡献者
82 
831. <strong>Fork 仓库</strong>到你的GitHub账号
842. **克隆你的 Fork** 到本地
853. <strong>创建新的分支</strong> 用于改动
864. 修改课程内容或代码示例
875. 在相关项目目录中测试代码改动
886. 按贡献指南提交拉取请求
89 
90### 学习者
91 
921. Fork 或克隆仓库
932. 按顺序进入课程目录
943. 阅读每课的README文件
954. 在 https://ff-quizzes.netlify.app/web/ 完成课前测验
965. 按课程学习代码示例
976. 完成作业和挑战
987. 参加课后测验
99 
100### 实时开发
101 
102- <strong>文档</strong>：在根目录运行 `docsify serve` （端口3000）
103- <strong>测验应用</strong>：在quiz-app目录运行 `npm run dev`
104- <strong>项目</strong>：使用VS Code Live Server扩展打开HTML项目
105- **API项目**：分别在对应API目录运行 `npm start`
106 
107## 测试指南
108 
109### 测验应用测试
110 
111```bash
112cd quiz-app
113npm run lint       # 检查代码风格问题
114npm run build      # 验证构建是否成功
115```
116 
117### 银行API测试
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # 检查代码风格问题
122node server.js     # 验证服务器启动无错误
123```
124 
125### 测试总体方法
126 
127- 这是一个没有完整自动测试的教学仓库
128- 手动测试关注点：
129  - 代码示例无错误运行
130  - 文档中的链接正常
131  - 项目构建成功完成
132  - 示例符合最佳实践
133 
134### 提交前检查
135 
136- 在含package.json的目录运行 `npm run lint`
137- 验证Markdown链接有效
138- 在浏览器或Node.js中测试代码示例
139- 检查翻译结构是否正确保持
140 
141## 代码风格指南
142 
143### JavaScript
144 
145- 使用现代ES6+语法
146- 遵循项目中的标准ESLint配置
147- 使用有意义的变量和函数名，便于教学理解
148- 添加注释解释概念
149- 配置Prettier进行代码格式化
150 
151### HTML/CSS
152 
153- 语义化的HTML5元素
154- 响应式设计原则
155- 清晰的类命名规范
156- 注释说明CSS技术点
157 
158### Python
159 
160- 遵循PEP 8规范
161- 清晰的教学示例代码
162- 适当添加类型提示，便于学习
163 
164### Markdown文档
165 
166- 明确的标题层级结构
167- 代码块标明语言
168- 资源链接
169- 在`images/`目录下存放截图和图片
170- 图片含有Alt文本，方便无障碍访问
171 
172### 文件组织
173 
174- 课程按顺序编号（1-getting-started-lessons、2-js-basics等）
175- 每个项目包含`solution/`，通常还有`start/`或`your-work/`目录
176- 图片存放在对应课程的`images/`文件夹
177- 翻译文件在`translations/{language-code}/`结构下
178 
179## 构建与部署
180 
181### 测验应用部署（Azure Static Web Apps）
182 
183quiz-app配置为Azure静态网页应用部署：
184 
185```bash
186cd quiz-app
187npm run build      # 创建 dist/ 文件夹
188# 在 push 到 main 时通过 GitHub Actions 工作流部署
189```
190 
191Azure静态网页应用配置：
192- <strong>应用位置</strong>：`/quiz-app`
193- <strong>输出位置</strong>：`dist`
194- <strong>工作流</strong>：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### 文档PDF生成
197 
198```bash
199npm install                    # 安装 docsify-to-pdf
200npm run convert               # 从 docs 生成 PDF
201```
202 
203### Docsify文档
204 
205```bash
206npm install -g docsify-cli    # 全局安装 Docsify
207docsify serve                 # 在 localhost:3000 上启动服务
208```
209 
210### 项目专属构建
211 
212各项目目录可能有自己的构建流程：
213- Vue项目：运行`npm run build`生成生产包
214- 静态项目：无构建步骤，直接提供文件
215 
216## 拉取请求指南
217 
218### 标题格式
219 
220使用清晰、描述性的标题，说明改动内容：
221- `[Quiz-app] 新增第X课测验`
222- `[Lesson-3] 修复生态瓶项目拼写错误`
223- `[Translation] 为第5课添加西班牙语翻译`
224- `[Docs] 更新设置说明`
225 
226### 必需检查
227 
228提交PR前：
229 
2301. <strong>代码质量</strong>：
231   - 在相关项目目录运行 `npm run lint`
232   - 修复所有lint错误和警告
233 
2342. <strong>构建验证</strong>：
235   - 如适用，运行`npm run build`
236   - 确保无构建错误
237 
2383. <strong>链接验证</strong>：
239   - 测试所有Markdown链接
240   - 确认图片引用正常
241 
2424. <strong>内容校对</strong>：
243   - 拼写和语法检查
244   - 确保代码示例正确且有教学价值
245   - 翻译准确保持原意
246 
247### 贡献要求
248 
249- 同意微软CLA（首次PR自动检查）
250- 遵守[微软开源行为准则](https://opensource.microsoft.com/codeofconduct/)
251- 请参阅[CONTRIBUTING.md](./CONTRIBUTING.md)了解详细指南
252- 若相关，请在PR描述中注明issue编号
253 
254### 审核流程
255 
256- PR由维护者和社区审核
257- 优先保证教育清晰度
258- 代码示例应遵循当前最佳实践
259- 翻译要求准确且文化适应
260 
261## 翻译系统
262 
263### 自动翻译
264 
265- 使用GitHub Actions的co-op-translator工作流
266- 自动翻译50多种语言
267- 源文件位于主目录
268- 翻译文件存放于`translations/{language-code}/`目录
269 
270### 手动改进翻译
271 
2721. 在`translations/{language-code}/`找到文件
2732. 保持结构下做改进
2743. 确保代码示例依然可用
2754. 测试本地化测验内容
276 
277### 翻译元数据
278 
279翻译文件包含元数据头：
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## 调试与排错
293 
294### 常见问题
295 
296<strong>测验应用启动失败</strong>：
297- 检查Node.js版本（建议v14+）
298- 删除`node_modules`和`package-lock.json`，重新运行`npm install`
299- 检查端口冲突（默认Vite使用5173端口）
300 
301**API服务器无法启动**：
302- 验证Node.js版本（node >=10）
303- 检查端口是否被占用
304- 确认所有依赖已安装`npm install`
305 
306<strong>浏览器扩展无法加载</strong>：
307- 确认manifest.json格式正确
308- 检查浏览器控制台错误
309- 按浏览器扩展安装说明操作
310 
311**Python聊天项目问题**：
312- 确认已安装OpenAI包：`pip install openai`
313- 确认GITHUB_TOKEN环境变量已设置
314- 检查GitHub模型访问权限
315 
316**Docsify未提供文档**：
317- 全局安装docsify-cli：`npm install -g docsify-cli`
318- 在仓库根目录运行
319- 检查`docs/_sidebar.md`是否存在
320 
321### 开发环境提示
322 
323- HTML项目推荐使用VS Code Live Server扩展
324- 安装ESLint和Prettier扩展保持格式一致
325- 利用浏览器开发者工具调试JavaScript
326- Vue项目安装Vue DevTools浏览器扩展
327 
328### 性能考虑
329 
330- 多语言翻译文件众多（50+语言）导致完整克隆体积大
331- 仅工作内容时可使用浅克隆：`git clone --depth 1`
332- 编辑英文内容时排除翻译文件搜索
333- 初次运行构建过程较慢（npm install，Vite构建）
334 
335## 安全考虑
336 
337### 环境变量
338 
339- API密钥绝不可提交到仓库
340- 使用`.env`文件（已包含在`.gitignore`中）
341- 在项目README中注明所需环境变量
342 
343### Python项目
344 
345- 使用虚拟环境：`python -m venv venv`
346- 保持依赖更新
347- GitHub令牌应仅授予必要权限
348 
349### GitHub模型访问权限
350 
351- 访问GitHub模型需要个人访问令牌（PAT）
352- 令牌应存为环境变量
353- 严禁提交令牌或凭据
354 
355## 其他说明
356 
357### 目标受众
358 
359- 完全的网页开发初学者
360- 学生和自学者
361- 教室中使用该课程的教师
362- 内容设计注重无障碍和渐进技能培养
363 
364### 教学理念
365 
366- 基于项目的学习方法
367- 频繁的知识检测（测验）
368- 实操编码练习
369- 真实应用示例
370- 先掌握基础再学框架
371 
372### 仓库维护
373 
374- 活跃的学习者和贡献者社区
375- 定期更新依赖和内容
376- 维护者监控问题和讨论
377- 翻译更新自动化通过GitHub Actions
378 
379### 相关资源
380 
381- [Microsoft Learn模块](https://docs.microsoft.com/learn/)
382- [学生中心资源](https://docs.microsoft.com/learn/student-hub/)
383- 推荐学习者使用[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
384- 额外课程：生成式AI、数据科学、机器学习、物联网课程等
385 
386### 使用具体项目
387 
388详见各项目README文件：
389- `quiz-app/README.md` - Vue 3测验应用
390- `7-bank-project/README.md` - 带认证的银行应用
391- `5-browser-extension/README.md` - 浏览器扩展开发
392- `6-space-game/README.md` - 基于Canvas的游戏开发
393- `9-chat-project/README.md` - AI聊天助手项目
394 
395### Monorepo结构
396 
397虽非传统monorepo，但此仓库包含多个独立项目：
398- 每课内容自成体系
399- 项目不共享依赖
400- 可单独开发项目互不影响
401- 克隆整个仓库获得完整课程体验
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**免责声明**：  
407本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 进行翻译。虽然我们力求准确，但请注意自动翻译可能包含错误或不准确之处。原文的母语版本应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们不对因使用本翻译而产生的任何误解或误释承担责任。
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->