fw1201 教學小程式開發 + 自動部署 v1.0
哲學定位
「讓每位教師都能有自己的教學工具，無需程式背景。」
互動工具設計原則
互動式學習工具最核心的問題不是「好不好玩」，而是學生有沒有感受到學會了。
設計時優先考慮三件事：
- 自主感：學生可以選擇難度或題型（而不是被強迫走同一條路）
- 勝任感：任務難度讓學生能嘗試成功，而不是反覆失敗然後放棄
- 連結感：工具有讓學生分享、比較、或一起完成的機制
分數回饋設計原則：
- 顯示「你比上次進步了 X 題」或「你連續答對了 X 題」
- 不要只顯示絕對分數或排行名次
- 進步感比排名更能維持學習動機——尤其對基礎較弱的學生
避免純外部獎勵： 只靠星星、勳章、排行榜的外部獎勵在移除後會降低學習意願。優先設計讓學生感到「我真的理解了」的成就反饋，而非「我得到了點數」的交換反饋。
設計系統 V2.0：Edu Warm
基於 Claude Design（2026-04-17）+ canvas-design 字型庫（Work Sans + Noto Sans TC）
Edu Warm CSS Token
:root {
--bg: #fffbf5; --surface: #f5f0e8;
--text: #141413; --text-muted: #6B6B6B;
--primary: #d97757; --primary-hover: #c4664a;
--secondary: #6a9bcc; --accent: #788c5d;
--radius: 12px; --shadow: 0 4px 24px rgba(0,0,0,0.08);
--font-heading: 'Work Sans', 'Noto Sans TC', sans-serif;
--font-body: 'Noto Sans TC', sans-serif;
}
禁用字型：Inter、Roboto、Arial — 改用 Work Sans（標題）+ Noto Sans TC（內文）
禁用模式：border-left accent callout（視覺陳腐）、漸層轟炸、SVG 插圖嘗試
色彩延伸：oklch(72% 0.13 50)可衍生 Edu Warm 暖色中間色
Edu Warm 元件規格（canvas-design 共用元件庫）
/* 按鈕 */
.btn-primary { background: #d97757; color: white; border-radius: 8px;
padding: 12px 24px; font: Work Sans Bold 16px; }
/* 卡片 */
.card { background: white; border-radius: 12px; padding: 24px;
box-shadow: 0 4px 24px rgba(0,0,0,0.08); }
/* 強調框 */
.callout { border-left: 4px solid #d97757; background: rgba(217,119,87,0.08);
padding: 16px 20px; border-radius: 0 8px 8px 0; }
/* 進度徽章 */
.badge { background: #d97757; color: white; border-radius: 50%;
width: 32px; height: 32px; display: flex; align-items: center;
justify-content: center; font: Work Sans Bold 14px; }
版面：HTML artifact 輸出標準
所有小程式以 HTML artifact 形式輸出（可即時預覽），確保：
- Google Fonts 載入：Work Sans + Noto Sans TC
- CSS token 完整定義（:root 變數）
- 響應式設計（max-width: 720px 居中）
- 微調模式支援：用戶說「換主色」只更新 --primary 變數
text-wrap: pretty用於所有段落文字，防止孤字
React HTML artifact 技術規格（固定版本）
使用 React 時，CDN 版本必須固定，避免外部變動影響：
<script crossorigin src="https://unpkg.com/react@18.3.1/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js"></script>
<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"></script>
樣式物件命名規則（避免 Babel scope 衝突）：
// ❌ 錯誤：const styles = {...} 在多個 Babel 腳本中會衝突
// ✅ 正確：使用唯一名稱
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// 組件跨腳本共享
Object.assign(window, { QuizCard, TimerDisplay });
狀態持久化（LocalStorage）
需要記憶進度的工具（測驗/學習卡/計時設定）必須加 LocalStorage：
// 儲存狀態
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// 恢復狀態（頁面重載後繼續）
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');
Step 0：讀取必要文件
references/mini_app_types.md— 常見教學小程式類型與規格../../shared/grade-adapter.md— 年級適應系統../../shared/guided-collection.md— 引導式收集框架references/deployment_guide.md— Vercel + GitHub Pages 部署指南
概念對齊協議（必要前置步驟）：
../../shared/concept-alignment.md
→ 在執行任何工作前，先完成概念對齊確認卡。
Step 1：年級偵測 + 引導式資訊收集
第一輪問題（最多 3 個）
Q1: 「想要什麼類型的教學小程式？
常見類型（可多選或描述你的想法）：
🎯 A. 互動測驗（選擇題/是非題，含計分）
🎲 B. 隨機抽籤/分組工具
⏱ C. 課堂計時器（含倒數音效）
🃏 D. 字詞/概念記憶卡（翻牌遊戲）
🎮 E. 填字/配對遊戲
📊 F. 即時投票/情緒溫度計
🔧 G. 其他（請描述）」
Q2: 「給哪個年級的學生使用？」（若未偵測到）
Q3: 「需要學生輸入資料/名字嗎？（若有，我會設計輸入區塊）」
第二輪問題（選填）
Q4: 「有具體的題目、詞語或內容要放進去嗎？
（可以直接貼上，或告訴我主題由我設計範例內容）」
Q5: 「部署偏好？
A. Vercel（推薦，更快更穩定，需要 Vercel 帳號）
B. GitHub Pages（免費，需要 GitHub 帳號）
C. 只需要 HTML 檔案，我自己部署」
確認摘要
✅ 小程式類型：{類型}
🎓 適用年級：{年級}
📝 內容：{主題/題目說明}
🚀 部署方式：{Vercel/GitHub Pages/本地}
🔗 完成後：生成可分享的永久連結
Step 2：技術架構規範
技術選擇原則
單頁互動工具（測驗/遊戲/計時器）：
→ 純 HTML + CSS + Vanilla JS（單一 .html 檔）
→ 無需 npm、無需框架，方便教師直接使用
複雜互動工具（多頁面/後端資料）：
→ React + Tailwind CSS
→ 部署至 Vercel
資料持久化工具（需儲存結果）：
→ React + localStorage（不需後端）
→ 或 Vercel + KV store（需後端）
設計系統（教育用）
/* 主色 */
--edu-blue: #1A5276; /* 主要操作按鈕 */
--edu-green: #1E8449; /* 正確/完成 */
--edu-orange: #CA6F1E; /* 警示/進行中 */
--edu-gold: #D4AC0D; /* 獎勵/高亮 */
/* 字型 */
--font-main: 'Noto Sans TC', 'Microsoft JhengHei', sans-serif;
/* 年級字體大小 */
國小低： 標題 2.5rem / 內文 1.5rem / 按鈕 1.3rem
國小中高：標題 2rem / 內文 1.3rem / 按鈕 1.1rem
國中： 標題 1.8rem / 內文 1.1rem / 按鈕 1rem
高中： 標題 1.5rem / 內文 1rem / 按鈕 0.9rem
Step 3：各類型小程式規格
A. 互動測驗（最常用）
功能規格：
- 題目逐一顯示，選完後即時回饋（正確/錯誤 + 解析）
- 進度條顯示（第 X 題 / 共 X 題）
- 計分系統（答對 +10 分，可設定時間加分）
- 完成後顯示總分 + 成績評語
- 可重新作答按鈕
- 題目/選項支援直接修改（教師模式）
資料格式（Claude 自動填入或依使用者提供）：
const questions = [
{
id: 1,
question: "題目文字",
options: ["選項A", "選項B", "選項C", "選項D"],
answer: 0, // 答案索引
explanation: "解析說明",
difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
}
];
B. 隨機抽籤/分組
功能規格：
- 輸入學生名單（每行一個名字）
- 設定分組數目或每組人數
- 隨機分組動畫效果
- 一鍵重新分組
- 複製結果按鈕
額外功能：
- 冷卻模式（被抽過的暫時不再被抽）
- 轉盤抽籤視覺效果（可選）
C. 課堂計時器
功能規格：
- 多段計時模式（思考 1 分/討論 3 分/發表 2 分）
- 大字顯示倒數時間
- 最後 10 秒變色提示
- 音效提示（完成時）
- 課堂情境預設：
* 小組討論、個人思考、上台發表、課前複習、考試
視覺：
- 全螢幕顯示（方便投影）
- 深色模式（不刺眼）
D. 記憶卡翻牌遊戲
功能規格：
- 翻牌配對（詞語+定義、問題+答案、圖+字）
- 計時 + 配對次數記錄
- 完成動畫
- 自訂卡片內容
適用：字詞學習、公式記憶、歷史事件配對
E. 即時投票/情緒溫度計
功能規格：
- 教師端：顯示問題 + QR Code
- 學生端（手機掃碼）：點選答案
- 即時顯示統計圖表
注意：此功能需後端支援，推薦使用 Vercel + Upstash Redis
Step 4：開發 + 部署流程
方案A：純 HTML 單檔（最簡單）
# 生成單一 HTML 檔
python scripts/generate_mini_app.py \
--type "[quiz/lottery/timer/flashcard]" \
--grade "[年級]" \
--content "[題目/內容 JSON]" \
--output "/mnt/user-data/outputs/[名稱].html"
# 使用者可直接在瀏覽器開啟，或上傳到任何靜態伺服器
方案B：Vercel 自動部署（推薦）
需要的 MCP：Vercel MCP
若 Vercel MCP 可用時的流程：
1. Claude 生成 React 專案原始碼（/tmp/mini-app-[名稱]/）
2. 呼叫 Vercel MCP 部署：
deploy_to_vercel(project_dir="/tmp/mini-app-[名稱]")
3. Vercel MCP 返回永久連結（https://xxx.vercel.app）
4. Claude 輸出連結給使用者
⚠️ 需要使用者已在 Claude Code 中連接 Vercel MCP
若 Vercel MCP 不可用：
# 生成 React 專案 + vercel.json
python scripts/generate_mini_app_react.py \
--type "[類型]" --grade "[年級]" \
--output_dir "/mnt/user-data/outputs/mini-app-[名稱]/"
# 輸出部署說明給使用者
echo "請執行以下指令部署：
cd mini-app-[名稱]
npx vercel --prod"
方案C：GitHub Pages
python scripts/generate_github_pages.py \
--type "[類型]" --grade "[年級]" \
--output_dir "/mnt/user-data/outputs/mini-app-[名稱]/"
# 輸出部署說明：
echo "請將資料夾推送到 GitHub，並在 Settings > Pages 啟用部署"
Step 5：品質確認清單
- 行動裝置友善（手機/平板可正常使用）
- 字體大小符合年級規格
- 支援觸控操作
- 色彩對比度符合可及性標準（WCAG AA）
- 有返回/重置功能
- 無需帳號即可使用（學生端）
- 中文顯示正常（字型已嵌入或指定備用字型）
- 部署成功並測試連結可訪問
- React 版本已固定（18.3.1 + Babel 7.29.0）？
- 樣式物件名稱唯一（非
const styles）？ - 需要記憶進度的工具已加 LocalStorage？
- 無漸層轟炸、無 SVG 插圖嘗試、無 border-left accent callout？
-
text-wrap: pretty已套用？
MCP 連接器（平台差異，核心功能）
Claude Code（完整支援）
Vercel MCP（若已連接）：
用途：一鍵將小程式部署到 Vercel，生成可分享連結
啟用：claude mcp add vercel
使用時機：使用者說「部署到 Vercel」或「生成可分享連結」
MCP 呼叫：deploy_to_vercel(project_path, project_name)
返回值：{ url: "https://xxx.vercel.app", deployment_id: "..." }
GitHub MCP / Filesystem（若已連接）：
用途：建立 GitHub repository 並啟用 Pages
使用時機：使用者說「放到 GitHub Pages」
Claude.ai（設定頁啟用）
目前 Vercel MCP 需在 Claude Code 環境使用。
Claude.ai 使用者建議：
1. Claude 生成完整 HTML 單檔
2. 使用者手動上傳到 Vercel / Netlify / GitHub Pages
Codex 平台
支援 Vercel CLI 和 GitHub Pages 部署腳本生成，Vercel MCP 透過 ~/.codex/config.toml 設定後可自動部署。
未設定 Vercel MCP 時，Claude 生成完整的 deploy.sh 腳本，使用者手動執行。
Antigravity 平台（Google AI IDE）
MCP 透過 MCP Server Hub 設定 Vercel Connector 後可自動部署。
未設定時，Claude 生成 deploy.sh 腳本，使用者手動執行。
部署 MCP 調用範例（Claude Code）
# 若 Vercel MCP 已連接
[Claude 生成程式碼後]
[呼叫 Vercel MCP 部署]
→ 返回 https://edu-quiz-xxxxx.vercel.app
→ Claude 輸出：「✅ 已部署！分享連結：https://edu-quiz-xxxxx.vercel.app」