11 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

專案概覽

這是一個用於教導初學者網頁開發基礎的教育課程資源庫。該課程為 Microsoft 雲端倡導者開發的全面 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

開發工作流程

內容貢獻者指南

將本資源庫分叉至您的 GitHub 帳戶
克隆您的分叉庫到本地
建立新分支用於您的修改
修改課程內容或程式碼範例
在相關專案目錄測試程式碼變動
按照貢獻指南提交拉取請求

學習者指南

分叉或克隆本資源庫
依序瀏覽課程目錄
閱讀每課的 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 Static Web Apps）

quiz-app 已配置為 Azure Static Web Apps 部署：

cd quiz-app
npm run build      # 建立 dist/ 資料夾
# 當推送到 main 分支時，透過 GitHub Actions 工作流程進行部署

Azure Static Web Apps 配置：

應用程式位置：/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 產生生產包
靜態專案：無建置步驟，直接提供檔案服務

拉取請求指引

標題格式

使用清楚、具描述性的標題表明更改範圍：

[Quiz-app] 新增課程 X 測驗
[Lesson-3] 修正玻璃箱專案錯字
[Translation] 新增第 5 課西班牙語翻譯
[Docs] 更新安裝說明

必須檢查項目

提交 PR 前：

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

貢獻要求

同意 Microsoft CLA（首次 PR 時自動檢查）
遵守 Microsoft 開源行為守則
詳細指南見 CONTRIBUTING.md
若有，於 PR 描述內提及相關議題編號

審查流程

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 建置）

安全事項

環境變數

API 金鑰絕不可提交至資源庫
使用 .env 檔（已加入 .gitignore）
專案 README 中記錄所需環境變數

Python 專案

使用虛擬環境：python -m venv venv
維護相依套件更新
GitHub 令牌設定最低必要權限

GitHub Models 存取

需使用個人訪問令牌 (PAT)
令牌應儲存在環境變數
禁止提交令牌或認證資訊

附加說明

目標對象

完全沒有網頁開發經驗的初學者
學生及自學者
在課堂中使用本課程的教師
內容設計強調易懂性與循序漸進技能建立

教育理念

採用專案導向學習方式
定期知識檢核（測驗）
實作程式練習
真實世界應用範例
強調基礎概念後再著重框架

資源庫維護

積極活躍的學習者與貢獻者社群
定期更新依賴與內容
維護者監控問題與討論
翻譯更新自動化使用 GitHub Actions

操作特定專案

有關各專案詳細說明，請參閱對應 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 進行翻譯。雖然我們致力於保持準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始語言版本的文件應被視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對使用本翻譯文件所產生之任何誤解或誤釋負責。

11 KiB Raw Permalink Blame History Unescape Escape