AGENTS.md

1# AGENTS.md
2 
3## 專案概覽
4 
5這是一個用於教導初學者網頁開發基礎的教育課程資源庫。該課程為 Microsoft 雲端倡導者開發的全面 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 或使用 Live Server
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>將本資源庫分叉</strong>至您的 GitHub 帳戶
842. <strong>克隆您的分叉庫</strong>到本地
853. <strong>建立新分支</strong>用於您的修改
864. 修改課程內容或程式碼範例
875. 在相關專案目錄測試程式碼變動
886. 按照貢獻指南提交拉取請求
89 
90### 學習者指南
91 
921. 分叉或克隆本資源庫
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- 圖片提供可及性說明的替代文字
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 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### 文件 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- 同意 Microsoft CLA（首次 PR 時自動檢查）
250- 遵守 [Microsoft 開源行為守則](https://opensource.microsoft.com/codeofconduct/)
251- 詳細指南見 [CONTRIBUTING.md](./CONTRIBUTING.md)
252- 若有，於 PR 描述內提及相關議題編號
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 Models 存取權限
315 
316**Docsify 無法提供文件服務**：
317- 全局安裝 docsify-cli：`npm install -g docsify-cli`
318- 於資源庫根目錄執行
319- 確認 `docs/_sidebar.md` 檔案存在
320 
321### 開發環境小技巧
322 
323- 使用 VS Code 搭配 Live Server 擴充開發 HTML 專案
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 Models 存取
350 
351- 需使用個人訪問令牌 (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 -->