# AGENTS.md

## 專案概述

《初學者的數據科學》是一個由 Microsoft Azure Cloud Advocates 創建的全面 10 週、20 課的課程。此存儲庫是一個學習資源，通過基於項目的課程教授基礎數據科學概念，包括 Jupyter 筆記本、互動測驗和實作練習。

**主要技術：**
- **Jupyter 筆記本**：使用 Python 3 作為主要學習媒介
- **Python 庫**：pandas、numpy、matplotlib 用於數據分析和可視化
- **Vue.js 2**：測驗應用程式（quiz-app 資料夾）
- **Docsify**：離線存取的文件站點生成器
- **Node.js/npm**：JavaScript 元件的套件管理
- **Markdown**：所有課程內容和文件

**架構：**
- 多語言教育存儲庫，提供廣泛的翻譯
- 結構化為課程模組（1-Introduction 至 6-Data-Science-In-Wild）
- 每課包含 README、筆記本、作業和測驗
- 獨立的 Vue.js 測驗應用程式，用於課前/課後評估
- 支援 GitHub Codespaces 和 VS Code 開發容器

## 設置指令

### 存儲庫設置
```bash
# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners
```

### Python 環境設置
```bash
# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn
```

### 測驗應用程式設置
```bash
# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint
```

### Docsify 文件伺服器
```bash
# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000
```

### 可視化項目設置
針對像 meaningful-visualizations（第 13 課）這樣的可視化項目：
```bash
# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint
```


## 開發工作流程

### 使用 Jupyter 筆記本
1. 在存儲庫根目錄啟動 Jupyter：`jupyter notebook`
2. 導航到所需的課程資料夾
3. 打開 `.ipynb` 文件進行練習
4. 筆記本是自包含的，包含解釋和代碼單元
5. 大多數筆記本使用 pandas、numpy 和 matplotlib，請確保已安裝這些庫

### 課程結構
每課通常包含：
- `README.md` - 主要課程內容，包含理論和範例
- `notebook.ipynb` - 實作 Jupyter 筆記本練習
- `assignment.ipynb` 或 `assignment.md` - 練習作業
- `solution/` 資料夾 - 解答筆記本和代碼
- `images/` 資料夾 - 支援的視覺材料

### 測驗應用程式開發
- Vue.js 2 應用程式，開發期間支援熱重載
- 測驗存儲於 `quiz-app/src/assets/translations/`
- 每種語言有自己的翻譯資料夾（en, fr, es 等）
- 測驗編號從 0 開始，最多 39（共 40 個測驗）

### 添加翻譯
- 翻譯存放於存儲庫根目錄的 `translations/` 資料夾
- 每種語言的課程結構與英文完全鏡像
- 通過 GitHub Actions 自動翻譯（co-op-translator.yml）

## 測試指導

### 測驗應用程式測試
```bash
cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve
```

### 筆記本測試
- 筆記本沒有自動化測試框架
- 手動驗證：按順序運行所有單元以確保無錯誤
- 確認數據文件可訪問且輸出正確生成
- 檢查可視化是否正確渲染

### 文件測試
```bash
# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation
```

### 代碼質量檢查
```bash
# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors
```


## 代碼風格指南

### Python（Jupyter 筆記本）
- 遵循 PEP 8 代碼風格指南
- 使用清晰的變數名稱，解釋所分析的數據
- 在代碼單元之前包含帶有解釋的 Markdown 單元
- 代碼單元應專注於單一概念或操作
- 使用 pandas 進行數據操作，matplotlib 進行可視化
- 常見導入模式：
  ```python
  import pandas as pd
  import numpy as np
  import matplotlib.pyplot as plt
  ```


### JavaScript/Vue.js
- 遵循 Vue.js 2 風格指南和最佳實踐
- ESLint 配置於 `quiz-app/package.json`
- 使用 Vue 單文件元件（.vue 文件）
- 維持基於元件的架構
- 提交更改前運行 `npm run lint`

### Markdown 文件
- 使用清晰的標題層次結構（# ## ### 等）
- 包含帶有語言指定的代碼塊
- 為圖片添加替代文字
- 鏈接相關課程和資源
- 保持合理的行長以提高可讀性

### 文件組織
- 課程內容存放於編號資料夾（01-defining-data-science 等）
- 解答存放於專用的 `solution/` 子資料夾
- 翻譯在 `translations/` 資料夾中鏡像英文結構
- 數據文件存放於 `data/` 或課程專用資料夾

## 構建和部署

### 測驗應用程式部署
```bash
cd quiz-app

# Build production version
npm run build

# Output is in dist/ folder
# Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.)
```

### Azure 靜態 Web 應用部署
測驗應用程式可部署至 Azure 靜態 Web 應用：
1. 創建 Azure 靜態 Web 應用資源
2. 連接至 GitHub 存儲庫
3. 配置構建設置：
   - 應用位置：`quiz-app`
   - 輸出位置：`dist`
4. GitHub Actions 工作流程將在推送時自動部署

### 文件站點
```bash
# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify
```

### GitHub Codespaces
- 存儲庫包含開發容器配置
- Codespaces 自動設置 Python 和 Node.js 環境
- 通過 GitHub UI 打開存儲庫中的 Codespace
- 所有依賴項自動安裝

## 拉取請求指南

### 提交前
```bash
# For Vue.js changes in quiz-app
cd quiz-app
npm run lint
npm run build

# Test changes locally
npm run serve
```

### PR 標題格式
- 使用清晰、描述性的標題
- 格式：`[元件] 簡短描述`
- 範例：
  - `[第 7 課] 修復 Python 筆記本導入錯誤`
  - `[測驗應用] 添加德語翻譯`
  - `[文件] 更新 README，添加新前置條件`

### 必要檢查
- 確保所有代碼運行無錯誤
- 驗證筆記本完全執行
- 確認 Vue.js 應用程式成功構建
- 檢查文件鏈接是否正常
- 測試修改的測驗應用程式
- 確保翻譯保持一致結構

### 貢獻指南
- 遵循現有代碼風格和模式
- 為複雜邏輯添加解釋性註釋
- 更新相關文件
- 在不同課程模組中測試更改（如適用）
- 查看 CONTRIBUTING.md 文件

## 附加說明

### 常用庫
- **pandas**：數據操作和分析
- **numpy**：數值計算
- **matplotlib**：數據可視化和繪圖
- **seaborn**：統計數據可視化（部分課程）
- **scikit-learn**：機器學習（進階課程）

### 使用數據文件
- 數據文件存放於 `data/` 資料夾或課程專用目錄
- 大多數筆記本預期數據文件位於相對路徑
- CSV 文件是主要數據格式
- 部分課程使用 JSON 作為非關聯數據範例

### 多語言支援
- 通過 GitHub Actions 提供 40+ 語言翻譯
- 翻譯工作流程位於 `.github/workflows/co-op-translator.yml`
- 翻譯存放於 `translations/` 資料夾，使用語言代碼命名
- 測驗翻譯存放於 `quiz-app/src/assets/translations/`

### 開發環境選項
1. **本地開發**：本地安裝 Python、Jupyter、Node.js
2. **GitHub Codespaces**：基於雲的即時開發環境
3. **VS Code 開發容器**：基於容器的本地開發
4. **Binder**：在雲端啟動筆記本（如已配置）

### 課程內容指南
- 每課是獨立的，但建立在之前概念的基礎上
- 課前測驗測試先前知識
- 課後測驗加強學習
- 作業提供實作練習
- Sketchnotes 提供視覺摘要

### 常見問題排查

**Jupyter 核心問題：**
```bash
# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience
```

**npm 安裝失敗：**
```bash
# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

**筆記本導入錯誤：**
- 確認已安裝所有所需庫
- 檢查 Python 版本兼容性（建議使用 Python 3.7+）
- 確保虛擬環境已啟動

**Docsify 無法加載：**
- 確認您從存儲庫根目錄提供服務
- 檢查 `index.html` 是否存在
- 確保正確的網絡訪問（端口 3000）

### 性能考量
- 大型數據集可能需要較長時間加載至筆記本
- 複雜圖表的可視化渲染可能較慢
- Vue.js 開發伺服器啟用熱重載以快速迭代
- 生產構建已優化並縮小

### 安全注意事項
- 不應提交敏感數據或憑證
- 在雲課程中使用環境變數存儲 API 密鑰
- 與 Azure 相關的課程可能需要 Azure 帳戶憑證
- 保持依賴項更新以獲取安全補丁

## 貢獻翻譯
- 通過 GitHub Actions 管理自動翻譯
- 歡迎手動修正以提高翻譯準確性
- 遵循現有翻譯資料夾結構
- 更新測驗鏈接以包含語言參數：`?loc=fr`
- 測試翻譯課程以確保正確渲染

## 相關資源
- 主課程：https://aka.ms/datascience-beginners
- Microsoft Learn：https://docs.microsoft.com/learn/
- 學生中心：https://docs.microsoft.com/learn/student-hub
- 討論論壇：https://github.com/microsoft/Data-Science-For-Beginners/discussions
- 其他 Microsoft 課程：ML for Beginners, AI for Beginners, Web Dev for Beginners

## 專案維護
- 定期更新以保持內容最新
- 歡迎社群貢獻
- 問題在 GitHub 上追蹤
- PR 由課程維護者審核
- 每月進行內容審查和更新

---

**免責聲明**：  
本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原始語言的文件作為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或誤釋不承擔責任。