# AGENTS.md ## 專案概述 這是一個教育課程的資源庫，旨在教導初學者網頁開發的基礎知識。課程為期12週，由 Microsoft Cloud Advocates 開發，包含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. 根據貢獻指南提交 Pull Request ### 對於學習者 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 靜態網頁應用程式） 測驗應用程式已配置為 Azure 靜態網頁應用程式部署： ```bash cd quiz-app npm run build # Creates dist/ folder # Deploys via GitHub Actions workflow on push to main ``` Azure 靜態網頁應用程式配置： - **應用程式位置**：`/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` 生成生產環境包 - 靜態專案：無需建置步驟，直接提供檔案 ## Pull Request 指南 ### 標題格式 使用清晰、描述性的標題，指明修改範圍： - `[Quiz-app] 為課程 X 添加新測驗` - `[Lesson-3] 修正植物園專案中的拼寫錯誤` - `[Translation] 添加課程 5 的西班牙語翻譯` - `[Docs] 更新設置指令` ### 必要檢查 提交 PR 前： 1. **程式碼品質**： - 在受影響的專案目錄執行 `npm run lint` - 修正所有 lint 錯誤和警告 2. **建置驗證**： - 如果適用，執行 `npm run build` - 確保無建置錯誤 3. **連結驗證**： - 測試所有 Markdown 連結 - 確認圖片引用正常運作 4. **內容審查**： - 校對拼寫和語法 - 確保程式碼範例正確且具有教育性 - 確認翻譯保持原意 ### 貢獻要求 - 同意 Microsoft CLA（首次 PR 時自動檢查） - 遵循 [Microsoft 開源行為準則](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` 存在 ### 開發環境提示 - 使用 VS Code 和 Live Server 擴充功能開啟 HTML 專案 - 安裝 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 Token 應具有最低必要權限 ### GitHub Models 存取 - 需要個人存取 Token（PAT）以使用 GitHub Models - Token 應存放為環境變數 - 絕不可提交 Token 或憑證 ## 附加說明 ### 目標受眾 - 完全初學者的網頁開發學習者 - 學生和自學者 - 在課堂中使用課程的教師 - 內容設計以提高可訪問性和逐步技能建設 ### 教育理念 - 基於專案的學習方法 - 頻繁的知識檢查（測驗） - 實作程式碼練習 - 真實世界應用範例 - 在框架之前專注於基礎知識 ### 資源庫維護 - 活躍的學習者和貢獻者社群 - 定期更新依賴和內容 - 維護者監控問題和討論 - 翻譯更新透過 GitHub Actions 自動化 ### 相關資源 - [Microsoft Learn 模組](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) 進行翻譯。我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原始語言的文件作為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對於因使用本翻譯而引起的任何誤解或錯誤解讀概不負責。