11 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

專案概覽

這是一個用於教授初學者網頁開發基礎的教育課程儲存庫。該課程是由 Microsoft Cloud Advocates 開發的完整 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 或使用 Live Server

聊天專案 (Python 後端)

cd 9-chat-project/solution/backend/python
pip install openai
# 設定 GITHUB_TOKEN 環境變數
python api.py

開發工作流程

內容貢獻者

將儲存庫分支 (fork) 至你的 GitHub 帳號
在本機複製 (clone) 你的分支
建立新分支 來進行修改
修改課程內容或程式碼範例
在相關專案目錄中測試程式碼變更
按照貢獻指南提交 Pull Request

學習者

分支或複製儲存庫
按順序瀏覽課程目錄
閱讀各課程的 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/ 資料夾中的截圖與圖片
針對圖片附加替代文字以利無障礙

檔案組織

課程依序編號（1-getting-started-lessons、2-js-basics 等）
每個專案有 solution/ 且通常有 start/ 或 your-work/ 目錄
圖片儲存在課程專屬的 images/ 資料夾中
翻譯存放於 translations/{language-code}/ 結構中

建置與部署

測驗應用部署 (Azure 靜態網站)

quiz-app 配置為 Azure 靜態網站部署：

cd quiz-app
npm run build      # 建立 dist/ 資料夾
# 在推送至 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 產生生產包
靜態專案：不需建置，直接提供檔案服務

Pull Request 指南

標題格式

使用清晰且描述性標題指示修改範圍：

[Quiz-app] 新增課程 X 測驗
[Lesson-3] 修正生態瓶專案錯字
[Translation] 新增課程 5 之西班牙文翻譯
[Docs] 更新安裝說明

必要檢查

提交 PR 前：

程式碼品質：
- 在相關專案目錄執行 npm run lint
- 修正所有 lint 錯誤與警告
建置驗證：
- 如適用，執行 npm run build
- 確保無建置錯誤
連結校驗：
- 測試所有 markdown 連結
- 確認圖片引用有效
內容審核：
- 校對拼字與語法
- 確保程式碼範例正確且具教育意義
- 確認翻譯準確且保持原意

貢獻條件

同意 Microsoft CLA（首次 PR 自動檢查）
遵循 Microsoft 開源行為準則
詳細指南見 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 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）
文件中說明所需環境變數

Python 專案

使用虛擬環境：python -m venv venv
持續更新相依套件
GitHub Token 需具最小必要權限

GitHub Models 存取權限

使用個人存取權杖（PAT）
將 Token 設為環境變數
絕不提交 Token 或帳密

附加說明

目標對象

完全初學者的網頁開發學習者
學生與自我學習者
在教室使用課程的老師
內容設計強調無障礙性及技能逐步建立

教育理念

以專案為基礎的學習方式
頻繁的知識檢核（測驗）
實作程式練習
真實世界應用範例
注重基礎概念，先於框架學習

儲存庫維護

積極的學習及貢獻社群
定期更新相依套件與內容
維護者監控議題與討論
透過 GitHub Actions 自動化翻譯更新

使用特定專案說明

個別專案詳細說明請參考：

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