AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5這是一個教育課程資源庫，旨在教導初學者網頁開發基礎。該課程由 Microsoft Cloud Advocates 開發，為期12週，包含24個實作課程，涵蓋 JavaScript、CSS 及 HTML。
6 
7### Key Components
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### Architecture
16 
17- 教育資源庫，採課程結構
18- 每個課程資料夾包含 README、範例程式碼及解答
19- 獨立專案存於不同目錄（quiz-app、多個課程專案）
20- 使用 GitHub Actions (co-op-translator) 的翻譯系統
21- 文件由 Docsify 提供，並以 PDF 形式可用
22 
23## Setup Commands
24 
25本資源庫主要用於教育內容瀏覽。若要操作特定專案：
26 
27### Main Repository Setup
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App Setup (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # 啟動開發伺服器
40npm run build      # 為生產環境編譯
41npm run lint       # 執行 ESLint
42```
43 
44### Bank Project 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### Browser Extension Projects
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# 遵循瀏覽器特定的擴充功能載入指示
60```
61 
62### Space Game Projects
63 
64```bash
65cd 6-space-game/solution
66npm install
67# 在瀏覽器中打開 index.html 或使用 Live Server
68```
69 
70### Chat Project (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# 設定 GITHUB_TOKEN 環境變量
76python api.py
77```
78 
79## Development Workflow
80 
81### For Content Contributors
82 
831. <strong>派生資源庫</strong>至您的 GitHub 帳號
842. <strong>將派生版本複製（clone）</strong>到本機
853. <strong>為變更建立新分支</strong>
864. 修改課程內容或程式碼範例
875. 在相關專案資料夾測試程式碼變更
886. 依照貢獻指引提交 pull request
89 
90### For Learners
91 
921. 派生或複製資源庫
932. 依序瀏覽課程資料夾
943. 閱讀每個課程的 README 文件
954. 完成課前測驗 https://ff-quizzes.netlify.app/web/
965. 練習課堂範例程式碼
976. 完成作業與挑戰
987. 參加課後測驗
99 
100### Live Development
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## Testing Instructions
108 
109### Quiz App Testing
110 
111```bash
112cd quiz-app
113npm run lint       # 檢查代碼風格問題
114npm run build      # 驗證構建成功
115```
116 
117### Bank API Testing
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # 檢查程式碼風格問題
122node server.js     # 驗證伺服器能否無錯誤啟動
123```
124 
125### General Testing Approach
126 
127- 本教育資源庫未包含全面的自動測試
128- 手動測試重點：
129  - 範例程式碼無錯誤執行
130  - 文件中的連結均正常
131  - 專案能成功編譯與建置
132  - 範例符合最佳實踐
133 
134### Pre-submission Checks
135 
136- 在有 package.json 的目錄執行 `npm run lint`
137- 驗證 Markdown 連結有效
138- 瀏覽器或 Node.js 測試範例程式碼
139- 確認翻譯結構維持正確
140 
141## Code Style Guidelines
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 Documentation
165 
166- 清晰的標題層級
167- 語言指定的程式碼區塊
168- 連結至額外資源
169- `images/` 目錄內的截圖與圖片
170- 圖片需有替代文字以利無障礙
171 
172### File Organization
173 
174- 課程依序編號（1-getting-started-lessons、2-js-basics 等）
175- 每個專案含 `solution/`，通常也有 `start/` 或 `your-work/` 目錄
176- 圖片存放於各課程專屬的 `images/` 資料夾
177- 翻譯存於 `translations/{language-code}/` 結構下
178 
179## Build and Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183quiz-app 已設定用於 Azure Static Web Apps 部署：
184 
185```bash
186cd quiz-app
187npm run build      # 建立 dist/ 資料夾
188# 在推送至 main 時通過 GitHub Actions 工作流程部署
189```
190 
191Azure Static Web Apps 配置：
192- <strong>應用程式位置</strong>：`/quiz-app`
193- <strong>輸出位置</strong>：`dist`
194- <strong>工作流程</strong>：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Documentation PDF Generation
197 
198```bash
199npm install                    # 安裝 docsify-to-pdf
200npm run convert               # 從 docs 生成 PDF
201```
202 
203### Docsify Documentation
204 
205```bash
206npm install -g docsify-cli    # 全域安裝 Docsify
207docsify serve                 # 在 localhost:3000 提供服務
208```
209 
210### Project-specific Builds
211 
212每個專案目錄可能有自己的建置流程：
213- Vue 專案：`npm run build` 產生生產用套件
214- 靜態專案：無建置步驟，直接提供檔案服務
215 
216## Pull Request Guidelines
217 
218### Title Format
219 
220使用清晰、有描述性的標題以指明變更範圍：
221- `[Quiz-app] 新增第X課測驗`
222- `[Lesson-3] 修正溫室專案錯字`
223- `[Translation] 新增第5課的西班牙文翻譯`
224- `[Docs] 更新設定指引`
225 
226### Required Checks
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### Contribution Requirements
248 
249- 同意 Microsoft CLA（首個 PR 自動檢查）
250- 遵守 [Microsoft 開源行為準則](https://opensource.microsoft.com/codeofconduct/)
251- 詳細指引請參閱 [CONTRIBUTING.md](./CONTRIBUTING.md)
252- 如適用於 Issue，請於 PR 說明中引用編號
253 
254### Review Process
255 
256- PR 由維護者與社群審查
257- 優先考量教育清晰性
258- 程式碼範例需符合現行最佳實踐
259- 翻譯確認準確且文化適切
260 
261## Translation System
262 
263### Automated Translation
264 
265- 使用 GitHub Actions 及 co-op-translator 工作流程
266- 自動翻譯成50多種語言
267- 主要檔案位於主目錄
268- 翻譯檔案位於 `translations/{language-code}/` 目錄
269 
270### Adding Manual Translation Improvements
271 
2721. 在 `translations/{language-code}/` 找到檔案
2732. 在維持結構的前提下優化翻譯
2743. 確保範例程式碼可運作
2754. 測試本地化測驗內容
276 
277### Translation Metadata
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## Debugging and Troubleshooting
293 
294### Common Issues
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 Models 存取權限
315 
316**Docsify 文件無法啟動**：
317- 全域安裝 docsify-cli：`npm install -g docsify-cli`
318- 於資源庫根目錄執行
319- 檢查 `docs/_sidebar.md` 是否存在
320 
321### Development Environment Tips
322 
323- 使用 VS Code 的 Live Server 擴充功能開發 HTML 專案
324- 安裝 ESLint 和 Prettier 擴充套件以統一格式
325- 使用瀏覽器開發者工具除錯 JavaScript
326- Vue 專案安裝 Vue DevTools 瀏覽器擴充功能
327 
328### Performance Considerations
329 
330- 大量翻譯檔案（50多種語言）使完整克隆檔案龐大
331- 僅工作於內容時，可使用淺層克隆：`git clone --depth 1`
332- 處理英文內容時，建議排除翻譯資料夾搜尋
333- 第一次建置流程（npm install、Vite build）可能較慢
334 
335## Security Considerations
336 
337### Environment Variables
338 
339- API 金鑰切勿提交至資源庫
340- 使用 `.env` 檔（已加入 `.gitignore`）
341- 在專案 README 文件中說明必須的環境變數
342 
343### Python Projects
344 
345- 使用虛擬環境：`python -m venv venv`
346- 維持依賴套件更新
347- GitHub Token 需限權限為最小必須
348 
349### GitHub Models Access
350 
351- 需要個人存取權杖（PAT）
352- 令牌應存為環境變數
353- 切勿提交令牌或認證資訊
354 
355## Additional Notes
356 
357### Target Audience
358 
359- 完全初學者的網頁開發
360- 學生與自學者
361- 教師於課堂中使用本課綱
362- 內容設計符合無障礙及循序漸進學習
363 
364### Educational Philosophy
365 
366- 專案導向學習
367- 頻繁知識檢測（測驗）
368- 動手練習程式碼實作
369- 實務應用範例
370- 強調基礎而非框架
371 
372### Repository Maintenance
373 
374- 積極的學習者與貢獻者社群
375- 定期更新依賴與內容
376- 維護者監控議題與討論
377- 翻譯更新自動化由 GitHub Actions 管理
378 
379### Related Resources
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### Working with Specific Projects
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 Structure
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 -->